[brentvatne]

Stacked on #74. It makes the exploration side of Explore modular: a capture strategy is one case in one place, and ARCHITECTURE.md says what a strategy decides and what the host owns. It changes no behaviour.

What and why

One place chooses the strategy. explore:binary and explore:session each picked a strategy with the same branch:

const model = replay ? replayModel(replay, platform, limits) : flows ? await flowsModel(flows, platform, limits, options, environment, say, app)
  : await preflightModelSession(options, environment, say);

src/binary/strategy.ts now holds that choice in three functions:

• chooseStrategy(options) checks the options before any device starts. It returns a model, a replay plan or a flows file, and refuses options that would do nothing.
• strategyInputs(choice, hints, environment) reads the {{secret:NAME}} inputs the strategy types.
• startStrategy(choice, …) returns an ExplorationStrategy: the session that drives the explorer's tools, how the report names it, and whether it takes the flow tools.

A new strategy is one more case of StrategyChoice. The model-session code moves out of run.ts with these functions, and assertAppUrl moves to binary/app-url.ts, so strategy.ts doesn't import run.ts.

The archive readers move down a layer. Three modules imported the tar.gz and zip readers from binary/archive.ts, a layer above them: shared/controller-cache, capture/local-simulator and ci/baseline-wait. The readers now live in src/shared/archive-entries.ts. binary/archive.ts keeps what is specific to apps: plists, manifests, icons and the iOS bundle.

ARCHITECTURE.md:

• lists binary/ as a folder and a layer, with its real imports;
• adds a "Capture strategies" section on what a capture decides (what to look at, how to get there, what to record) and where each part lives, in reviews and in explorations;
• says reviews have no strategy seam yet.

Screenshots

No visible change.

Code examples

No change to usage. A strategy is added in binary/strategy.ts:

export type StrategyChoice = { kind: "model" } | { kind: "replay"; plan: ReplayPlan } | { kind: "flows"; plan: FlowPlan };

Try it

Run the flows from #74 on a simulator build. Its strategy is chosen and started through the new module:

npm ci && npm run build
node dist/cli.js explore:binary path/to/app.tar.gz --simulator local --flows flows.json

Testing

• The euxy flows trial from Flows: follow named flows through a build, with named checkpoints that two runs pair up by #74 runs the same after the refactor, on a local iPhone 17 Pro with the euxy main e2e build:
  • 3 flows completed;
  • 6 captures;
  • all 5 checkpoints paired with the run before the refactor.
• A new test covers chooseStrategy's refusals, which had none: FLOWS_WITH_REPLAY, FLOWS_OPTIONS_IGNORED, REPLAY_OPTIONS_IGNORED, and an https: URL in a flows file.
• The fixes from Flows: follow named flows through a build, with named checkpoints that two runs pair up by #74's review are merged in (66393dd), and carried into strategy.ts:
  • secrets and model access are filtered by platform;
  • the turn budget is checked;
  • ExplorationStrategy.flows names the checkpoints a flows run never attempted, for the explorer to record as missing.
• A new test starts a flows strategy whose described steps run only on another platform, and fails if any model is started.
• The second round of Flows: follow named flows through a build, with named checkpoints that two runs pair up by #74's fixes is merged in (6394778). On explore:session without --platform, a flows run's strategyInputs now waits for the session to report its platform.
• npm test passes (1734 tests), and npm run typecheck is clean. Lint shows only the 6 existing Viewer warnings.

Not in this PR

• A strategy seam for reviews (capture:review), and flows in reviews.
• Comparing two flow runs, and the Viewer's step-by-step flow view.
• A non-LLM crawler, which needs a stricter action policy in the explorer first.

🤖 Generated with Claude Code

[github-actions]

Viewer preview of 6394778 · reports from brentvatne/euxy#163

Report	Changes	Open
Android · sdk_gphone64_x86_64 15.0	5	Map · Screens · Compare
iPhone 17 · iPhone 17 26.5 · light + dark	11	Map · Screens · Compare
iPhone Duo (closed) · iPhone Duo 27.1 · light + dark	34	Map · Screens · Compare
iPhone Duo (open) · iPhone Duo 27.1 · light + dark	34	Map · Screens · Compare

The link stays the same on every push. Deploy run