Skip to content

feat(ios): productionize the selected Simulator snapshot bridge #2196

Description

@thymikee

Parent: #2188

Blocked by: #2192

Start condition: #2192 must close with an explicit GO naming the selected mechanism. A NO-GO closes
this issue without implementation; do not substitute another private mechanism ad hoc.

Outcome

Productionize the selected Simulator accessibility reader as private, host-local infrastructure
behind one @agent-device/platform-apple acquisition adapter. The bridge must build, cache, spawn,
bind, read, cancel, fail, and recover deterministically, but no production snapshot request routes
to it yet.

Exact scope

Native bridge

  • Put the small native source under apple/snapshot-bridge/.
  • Implement the spike-proven framed batch request/response protocol with logs on stderr.
  • Return acquisition facts only: raw nodes, viewport evidence, target generation, truncation, typed
    residue, and protocol/source versions.
  • Enforce request/response bytes, node count, depth, work, and duration limits.
  • Return typed unsupported, malformed-tree, stale-target, timeout, cancellation, crash, and transport
    failures.

Apple host adapter and lifecycle

  • Put adapter, build/cache, spawn supervision, request client, and lifecycle under
    packages/platform-apple/src/snapshot-source/ behind one narrow runtime facet.
  • Cache outside the npm package using at least source hash, Xcode build, macOS version, architecture,
    and Simulator-runtime compatibility inputs.
  • Compile lazily or through explicit preparation; never compile in npm postinstall.
  • Use atomic cache publication and reject stale/incompatible protocol/source versions.
  • Key target state by UDID plus opaque target generation. Do not retain capture data or comparison
    baselines across sessions or generations.
  • Preserve request cancellation and deadline signals through build, bind, and read.
  • Write bridge/process diagnostics to the owning session's runner/diagnostic artifacts without
    replacing existing warnings or typed error details.

Protocol decision

Hand-maintain the small Swift/TypeScript wire carriers and pin them with round-trip fixtures. Do not
add code generation now. Revisit generation only after an incompatible protocol evolution, a second
independent wire consumer, two demonstrated optionality/enum-drift defects, or a third runtime.

Security and proxy seam

  • The bridge listener/socket is private host infrastructure and is never exposed through
    agent-device proxy.
  • Do not add a bridge, helper-control, or daemon-administration HTTP route.
  • Bound and validate every decoded frame before allocation-heavy work.
  • Do not put daemon, proxy, signing, or user credentials in source, cache keys, logs, or artifacts.

Non-goals

  • No production snapshot routing, circuit breaker, XCTest fallback, runner-demand, open/relaunch,
    provider, or proxy behavior change.
  • No public CLI flag, new workspace package, downloaded executable, pre-signed artifact, or
    physical-iPhone support.
  • Do not copy Swift presentation into the bridge; it acquires only.

Acceptance and evidence

  • The production adapter reproduces perf(ios): decide Simulator AX bridge viability with a bounded spike #2192's fidelity and bounded-resource results through its public
    runtime facet.
  • Build cache cold, hit, invalidation, concurrent publication, corrupt entry, and toolchain-change
    cases are tested.
  • Spawn/read/cancel/crash/restart/stale-generation tests use typed outcomes and leave no orphaned
    helper ownership.
  • A planted route/ownership violation proves the bridge cannot be reached from the proxy or outside
    the Apple runtime facet.
  • Packed, installed, and bundled size deltas are reported against test(ios): establish snapshot convergence baselines and permanent evidence #2189 and stay within the accepted
    budget; the compiled cache is excluded from the npm artifact.
  • Focused native/host tests, XCTest selection when applicable, layering, packaging, and
    pnpm check:affected --run pass; attach live Simulator evidence.

Worker stop conditions

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions