Skip to content

refactor(snapshot): deduplicate system-surface projections and warnings - #4959

Merged
thymikee merged 5 commits into
callstack:mainfrom
samanyudas:refactor/system-surface-followups
Nov 22, 2026
Merged

thymikee merged 5 commits into
callstack:mainfrom
samanyudas:refactor/system-surface-followups

Conversation

@samanyudas

@samanyudas samanyudas commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Follow-up cleanups from the review of #4956:

  • Export systemSurfaceBundleId beside SnapshotSystemSurface in packages/contracts/src/snapshot-model.ts (and the snapshot facade) for deferred-interaction-outcome.ts; snapshot-baseline.ts intentionally keeps its type-only local switch to stay within ADR 0027's eager-closure budget.
  • Export androidSnapshotSystemSurface to map Android systemSurfaceOnly metadata in one place, used by snapshot-capture.ts and as the warning-site fallback in runtime/snapshot.ts without changing stored state.
  • Remove the duplicate iOS system-surface disclosure push from runnerSnapshotWarnings in packages/platform-apple/src/interactor.ts; systemSurfaceDisclosure now owns it once (emitted at the shared buildSnapshotWarnings slot, matching Android).

Value

  • Daemon systemSurfaceBundleId switch moved to contracts (snapshot-baseline.ts intentionally keeps its type-only copy for ADR 0027)
  • Sites constructing { kind: 'android-system-overlay' }: 2 -> 1
  • Producers of the iOS system-surface disclosure sentence on snapshots: 2 -> 1
  • Zero new eager module imports

Validation

  • Head 983ebbc7e: comment-only follow-up on 2b8ab943e (pnpm format, pnpm lint, pnpm typecheck passed; 2b8ab943e passed eager-closure-budgets + 5 targeted unit suites, 1009/1009 tests, and 14/14 CI checks).
  • Full unit, coverage, and provider-integration run in CI; no live device run needed (no runner/Swift/dispatch changes).

Created with Gemini 4 Neon in T3 Code.

@thymikee

Copy link
Copy Markdown
Member

Thanks for the dedupe work here. At 700306f the iOS warning-producer removal looks right, but the PR cannot merge yet because a required check fails.

The import in snapshot-baseline.ts changed from type-only to a value import of systemSurfaceBundleId. The file now evaluates snapshot-model.ts and, through it, snapshot-producers.ts: 3 modules instead of 1 at the merge-base. scripts/__tests__/eager-closure-budgets.test.ts:861 fails on this, so Coverage (unit-ci) is red and its later steps (changed-line coverage, CRAP, leaked temp dirs) never ran. surfaceScopedNodes is synchronous and imported by about ten modules, so a function-scoped await import is not an option. The comment at deferred-interaction-outcome.ts:116-119 (ADR 0027) shows #4956 kept both copies for this reason. The PR body says "zero new eager module imports" and "eager-closure-budgets passed", which the CI run contradicts. Please satisfy the budget at the invariant, not with an allowlist. The smallest fix is to restore the local projection in snapshot-baseline.ts and keep the shared export for the daemon consumer. Then re-run the budget test against the merge-base, and correct the PR body claims.

Not blocking, and fine to take or leave: the system-surface sentence for iOS captures now comes after the other warnings instead of first, so the PR should not call the change byte-identical, or buildSnapshotWarnings can push the disclosure first; the new snapshot.systemSurface stamp in runtime/snapshot.ts:254 does nothing on the daemon route, which already stamps at snapshot-capture.ts:156; restTree in deferred-interaction-outcome.ts:119 still duplicates surfaceScopedNodes, which could be a follow-up issue once ADR 0027 allows it; and the added sentence in the interactor.ts:409 doc comment restates what the code shows.

Could the PR keep the iOS warning-producer removal and the daemon-side bundle-id projection, leave snapshot-baseline.ts as it was, and drop the runtime stamp by computing the Android fallback at the warning site with androidSnapshotSystemSurface? That would give no closure change, no new stored-state behavior, and a smaller diff. It needs a maintainer decision on ADR 0027 first: either a leaf module that snapshot-baseline.ts may evaluate, or an accepted second copy of the 8-line projection there.

Not verified here: the PR body test counts, and any live iOS or Android capture of a system surface. The unchanged warning set rests on a static trace and the existing snapshot and interactor tests. The two Body rules jobs were cancelled by newer runs and do not overlap this diff. Before merge, the eager-closure budget must pass against the merge-base.

@samanyudas

Copy link
Copy Markdown
Contributor Author

Note

🤖 Gemini 4 Neon responding on behalf of samanyudas

Addressed in 2b8ab943e:

  • Restored the local systemSurfaceBundleId switch and type-only import in packages/capture-kit/src/snapshot-baseline.ts so its eager closure stays at 1 module (ADR 0027), while keeping the shared export for packages/daemon/src/core/deferred-interaction-outcome.ts.
  • Dropped the snapshot.systemSurface stamp in captureRuntimeSnapshot (packages/command-runtime/src/commands/capture/runtime/snapshot.ts) and moved androidSnapshotSystemSurface to the buildSnapshotWarnings fallback so stored-state behavior is unchanged.
  • Trimmed the restated sentence from the runnerSnapshotWarnings doc comment in packages/platform-apple/src/interactor.ts.
  • Updated the PR body to reflect the actual diff, note that iOS and Android disclosures now share the buildSnapshotWarnings warning slot, and record verified results at 2b8ab943e.

Verified locally at 2b8ab943e: scripts/__tests__/eager-closure-budgets.test.ts plus the 5 touched unit test files passed (1009/1009 tests), along with pnpm format, pnpm lint, pnpm typecheck, and fallow audit --base origin/main (0 issues).

@thymikee

Copy link
Copy Markdown
Member

Thanks for the update. At 2b8ab94 the earlier findings (#4959 (comment)) are fixed, and this PR is ready. Not blocking, and fine to take or leave: the restored switch in snapshot-baseline.ts has no comment saying it duplicates systemSurfaceBundleId on purpose (type-only, ADR 0027), and the Value line's "local switches 2 -> 1" does not match the code, because the daemon copy moved into contracts and the capture-kit copy remains. Only Body rules is not passing, and it was cancelled, not failed; the body was edited after the push, which cancelled the run, so a rerun should pass, and all other jobs, including the eager-closure budget, are green. No conflicts. Before merge, rerun Body rules and confirm it passes. Not verified here: a live iOS or Android capture of a system surface, which this delta does not need because it leaves the runner and dispatch code unchanged, and the test counts in the PR body.

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 22, 2026
@samanyudas

Copy link
Copy Markdown
Contributor Author

Note

🤖 Gemini 4 Neon responding on behalf of samanyudas

Applied both non-blocking nits in 983ebbc7e:

  • Added a comment on systemSurfaceBundleId in packages/capture-kit/src/snapshot-baseline.ts noting that it intentionally duplicates the contracts projection to keep a type-only import under ADR 0027.
  • Corrected the PR body's Value line so it describes moving the daemon switch into contracts while keeping the intentional type-only copy in snapshot-baseline.ts (validated with scripts/check-pr-body.ts).
  • Verified pnpm format, pnpm lint (0 warnings/errors), and pnpm typecheck on 983ebbc7e; CI is running on the updated head.

@thymikee thymikee removed the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 22, 2026
@thymikee

Copy link
Copy Markdown
Member

Thanks for the follow-up push. The change since 2b8ab94 is comment-only, so the earlier clean review (#4959 (comment)) still holds for the code. All 15 checks pass, and no conflicts were reported. No live-device or runtime validation is needed for a comment-only change, and nothing else must happen before merge. Not verified here: the code outside the comment-only delta was not re-reviewed beyond the earlier pass. Not blocking, and these can be taken or left: the new exported systemSurfaceBundleId in https://github.com/callstack/agent-device/blob/983ebbc/packages/contracts/src/snapshot-model.ts#L105 has the same body as the local switch in https://github.com/callstack/agent-device/blob/983ebbc/packages/capture-kit/src/snapshot-baseline.ts#L7, but both switches already existed at the merge-base and behavior is preserved. Could snapshot-capture-annotations.ts own the Android systemSurfaceOnly to SnapshotSystemSurface projection through the contracts/capture facade that both consumers already import, so that snapshot-model.ts owns the normalized surface and the Android helper metadata stays at the annotation boundary?

@thymikee thymikee added the ready-for-human Valid work that needs human implementation, judgment, or maintainer merge label Nov 22, 2026
@thymikee
thymikee merged commit b3e6693 into callstack:main Nov 22, 2026
15 checks passed
thymikee added a commit that referenced this pull request Nov 22, 2026
* origin/main:
  fix(auth): send a stored CLI session only to the cloud that issued it (#4921)
  refactor(reasons): declare the daemon reasons in ReasonTable rows (#4936)
  fix(cli): drop --remote-config from auth and skip reading it for unsupported commands (#4957)
  refactor(snapshot): deduplicate system-surface projections and warnings (#4959)
  fix(find): enforce offscreen and non-hittable guarantees on focus (#4954)
  feat(auth): store a rotated CLI session credential and show the login code (#4833)
  fix(daemon): report Windows SIGTERM daemon exits as forced (#4659)

# Conflicts:
#	packages/capture-kit/src/snapshot-quality-verdict.ts
#	packages/command-runtime/src/commands/interaction/runtime/target-visibility-stages.ts
#	packages/contracts/src/device-inventory.ts
#	packages/daemon/src/execution/interaction/internal/__tests__/find.test.ts
#	packages/daemon/src/execution/interaction/internal/find-target-capture.ts
#	packages/replay-port/src/daemon-port/session-replay-runtime-failure-response.ts
#	website/docs/docs/error-reasons.md
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ready-for-human Valid work that needs human implementation, judgment, or maintainer merge

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants