Skip to content

refactor(snapshot): one shared model for occluding system surfaces - #4956

Merged
thymikee merged 1 commit into
callstack:mainfrom
samanyudas:refactor/2489-shared-system-surface-model
Nov 22, 2026
Merged

thymikee merged 1 commit into
callstack:mainfrom
samanyudas:refactor/2489-shared-system-surface-model

Conversation

@samanyudas

@samanyudas samanyudas commented Nov 22, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Replace the parallel Android and iOS occluding-surface fields on SnapshotState (systemSurfaceOnly and iosSystemSurfaceBundleId) with one discriminated union systemSurface?: SnapshotSystemSurface. Closes #2489.

  • Add SnapshotSystemSurface (android-system-overlay | IosSystemSurfaceProvenance) in packages/contracts/src/snapshot-model.ts and export it from the snapshot facade.
  • Replace @agent-device/contracts/android-system-surface-disclosure with @agent-device/contracts/system-surface-disclosure, routing both deferred capture disclosure and direct capture warnings through systemSurfaceDisclosure.
  • Keep Android wire metadata (AndroidSnapshotBackendMetadata.systemSurfaceOnly), disclosure copy, and surfaceBundleId comparison scoping unchanged.

Value

  • Parallel SnapshotState system-surface fields: 2 -> 1
  • Non-test lines reading platform-specific SnapshotState fields: 14 across 6 files -> 0
  • Disclosure modules imported by capture-disclosure.ts: 2 -> 1
  • Diff: 24 files, +159/-118, zero new eager module imports

Validation

  • Head 779c4cfb8: pnpm format, pnpm check:quick, layering, build, package, di-seams, fallow (0 issues), facade-surface (3/3), eager-closure-budgets + baseline tests (948/948), and 96 contracts/snapshot/daemon test files (933/933) passed.

Reviewed with sol-loop: 2 rounds with gpt-6.2-sol. Sol verdict: approved.
Created with Claude Opus 5.5 and Gemini 4 Neon in T3 Code.


Prove it works
Open in [code]smith · Need help on this PR? Tag @codesmith-bot with what you need.

View guided diff

SnapshotState carried an occluding system surface on two parallel
channels: `systemSurfaceOnly` for Android and `iosSystemSurfaceBundleId`
for iOS. Every consumer branched on both, and a third platform would have
added a third field.

Replace both with `systemSurface?: SnapshotSystemSurface`, a union of the
Android overlay (`{ kind: 'android-system-overlay' }`) and the iOS
registered host provenance (`IosSystemSurfaceProvenance`). The capture
path stores the iOS provenance as the runner reported it, so bundle id
and kind cannot disagree.

- `systemSurfaceDisclosure(surface)` in the renamed
  `@agent-device/contracts/system-surface-disclosure` derives the one
  agent-facing sentence for both platforms.
- `systemSurfaceBundleId(surface)` gives the post-action baseline scope.
  An Android overlay scopes nothing, as before.
- `AndroidSnapshotBackendMetadata.systemSurfaceOnly` stays: it is the
  Android capture backend's own evidence, which the daemon maps to the
  shared model at its one seam.

Disclosure sentences, comparison scoping, and wire payloads are unchanged.

Closes callstack#2489

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@thymikee

Copy link
Copy Markdown
Member

Thanks for the clean refactor. The change at 779c4cf is ready, and the shared model reads well. Required evidence is satisfied by the unit tests and the PR body receipts; no live device run was needed because the change has no runner, dispatch or Swift edits and the output strings are byte-identical. Not verified here: gates, tests and the eager-closure budgets were not run, and whether the daemon and MCP routes that read data.warnings all go through buildSnapshotWarnings was not traced. The two non-passing checks are both Body rules runs that were cancelled, which is likely a body edit or push cancelling the previous run. All 18 other checks pass. Please re-run Body rules at this head (a body edit or an empty rerun) before merge. Not blocking, and fine to take or leave: (1) systemSurfaceBundleId is written twice with the same body, in snapshot-baseline.ts and deferred-interaction-outcome.ts, and restTree re-spells surfaceScopedNodes, so one exported projection next to SnapshotSystemSurface would remove both local switches; (2) the Android metadata becomes the shared model's Android arm at two sites, snapshot-capture.ts and snapshot.ts, so one helper, or stamping snapshot.systemSurface once in the embedded runtime, would leave a single source; (3) runnerSnapshotWarnings in platform-apple still builds the iOS disclosure sentence that snapshot.ts now derives from the model, and the Set dedupe hides the second producer; (4) the SnapshotSystemSurface union mixes a platform-named kind with iOS registry kinds, which is fine as long as the identity projection is enumerated once.

@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 cca2b23 into callstack:main Nov 22, 2026
18 of 20 checks passed
thymikee added a commit that referenced this pull request Nov 22, 2026
* origin/main:
  feat(contracts): allow third-party snapshot producers (#4905)
  refactor(reasons): declare the R3 apple-runner reasons in ReasonTable rows (#4922)
  refactor(reasons): declare the R4 reasons in ReasonTable rows (#4934)
  refactor(snapshot): one shared model for occluding system surfaces (#4956)

# Conflicts:
#	website/docs/docs/error-reasons.md
thymikee added a commit that referenced this pull request Nov 22, 2026
* origin/main:
  feat(contracts): allow third-party snapshot producers (#4905)
  refactor(reasons): declare the R3 apple-runner reasons in ReasonTable rows (#4922)
  refactor(reasons): declare the R4 reasons in ReasonTable rows (#4934)
  refactor(snapshot): one shared model for occluding system surfaces (#4956)

# Conflicts:
#	test/repo-guards/runner-refusal-reason-docs.test.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.

refactor(snapshot): one shared model for occluding system surfaces across Android and iOS

2 participants