Skip to content

docs(simulation): consolidate base.py CodeQL suppression breadcrumb with existing Note (#191) paragraph #230

@cagataycali

Description

@cagataycali

Problem

strands_robots/simulation/base.py now carries two adjacent comment blocks describing overlapping but distinct concerns:

  1. CodeQL suppression breadcrumb (added in security(codeql): suppress py/unsafe-cyclic-import on simulation triple (closes #215) #216 R0). Frames the static-cycle suppression for CodeQL readers and points at .github/codeql/README.md for the full rationale.
  2. Existing Note (#191) paragraph. Explains why OnFrame is referenced as a string annotation in evaluate_benchmark rather than imported at module level, framed as if CodeQL were the constraint that forced the workaround.

With #216 landing the global suppression, the Note (#191) framing is now slightly off -- the OnFrame workaround is still load-bearing for runtime cycle avoidance (the asymmetric edge), but it's no longer load-bearing for CodeQL (the global exclude covers it). A future reader sees two comment blocks that disagree on which constraint is doing the work.

Proposed fix

Consolidate into a single comment block that:

  • Frames the runtime-cycle invariant first (the asymmetric edge between base and policy_runner -- this is what makes the import work, independent of CodeQL).
  • References the CodeQL suppression as the static-checker layer that lives on top, with a pointer at .github/codeql/README.md.
  • Explains the OnFrame string-annotation choice purely in terms of runtime cycle avoidance (which is still the correct rationale even with the suppression in place).

The Note (#191) shape should disappear -- the issue it referenced is closed, and the runtime rationale survives as part of the consolidated breadcrumb.

Acceptance criteria

  • Single consolidated comment block in strands_robots/simulation/base.py covering: runtime-cycle invariant, CodeQL suppression layer, OnFrame string-annotation rationale
  • Note (#191) paragraph removed; its content folded into the consolidated block where still load-bearing
  • Cross-references to .github/codeql/README.md and the regression pin tests preserved
  • No behaviour change; comment-only PR
  • Verify with grep that no other file in the tree references the Note (#191) framing in a way that would drift after the consolidation

Context


Filed by autonomous agent. Strands Agents.

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type
    No fields configured for issues without a type.

    Projects

    Status
    Done

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions