Phase 1: discover + plan + review on /discover (no execute)

[enricopiovesan]

Goal

Deliver Phase 1 of the medium-term /discover demo from discussion #1102 and
traverse#1150: a visitor picks a structured goal, and the page — with no backend —
discovers real published capabilities from the live registry and produces a
deterministic browser-local workflow proposal for review. Nothing executes in this
phase. The runtime stays the sole authority; the browser is an untrusted proposer.

This is distinct from the authored-bundle Real mode already shipped in
#58 (#63 / #65 / #67), where the capabilities and their order
are pinned in a committed bundle. That stays as the "simplest case"; this ticket makes
the composition discovered (plan + review only).

Phase 2 (composed execution + per-node traces) is a separate issue — see Related.

Decisions (2026-09-09 brainstorm)

Full log: #68 (comment)

• Ship Phase 1 publicly as soon as traverse-embedder-web@0.8.0 is consumable
• Plan over the full is_automatic_eligible catalog; UI offers one happy-path goal +
  one structurally impossible fail-closed goal
• Goal-scoped prep of the structural neighborhood (eligible-only); verify planner API
  prep requirements
• Third labelled path: Simulation · authored Real · discovered Real
• Honest copy: discovered from the live registry and planned in-browser — reviewed,
  not executed

Upstream: DONE

• registry#383 — catalog.json carries contract_url + contract_digest; CORS-open contracts
• registry#384 — is_automatic_eligible, risk, effect_class, determinism_class
• traverse#1271 — browser-local composition, no remote endpoint (Spec 1277 + ADR-0062)
• traverse#1269 / #1270 — planner + composed-execution in the Rust crate
• traverse#1272 — signed registry_ref activation (index-v263)
• traverse#1308 scope (planner) / PR path for web planner binding — awaiting npm 0.8.0

Blocked by

• traverse-embedder-web@0.8.0 on npm (planner surface from traverse#1308 /
  related PRs). Until npm view traverse-embedder-web version is >=0.8.0, this
  ticket cannot start. (As of 2026-09-09 npm still reports 0.7.0 only.)

Definition of done (Phase 1 only)

• /discover presents a discovered Real path alongside Simulation and the
  authored-bundle Real mode; live / derived / simulated / real-authored /
  real-discovered labelled above the fold.
• The page builds a verified synced-registry snapshot from catalog.json +
  contract_url / contract_digest + registryCache verification evidence; stale
  or unverified evidence fails closed before planning (Spec 1277 FR-001).
• Given a structured target, the page runs the browser-local deterministic
  planner (traverse-embedder-web@>=0.8.0, Spec 1277 FR-002–FR-004): candidates
  derived only from Spec-113 structural / declared-event relationships, ambiguity
  enumerated not chosen, no name/namespace/NL/model inference, bounded, with stable
  plan_search_truncated / no-candidate outcomes. Mappings shown
  mapping_unconfirmed.
• Selection input to the planner is constrained to is_automatic_eligible
  capabilities (registry#384).
• UI committed goals: one happy-path + one structurally impossible fail-closed /
  no-candidate target; planning may see the full eligible catalog; deps prepared
  goal-scoped (structural neighborhood).
• Fail-closed and redacted for: unverified/stale snapshot, invalid target,
  no-candidate, resource-bound breach / BrowserPlanError codes. No fabricated
  success. No execution path in this phase.
• No hosted model, no prompt storage, no NL planning, no remote planning endpoint,
  no CORS exception (Spec 1277 FR-008) beyond existing registry mirror fetches for
  preparation.
• Checked-in browser E2E: one discovered proposal success (review gate holds, no
  execute) + one fail-closed rejection, against a deterministic pinned snapshot
  fixture.
• discover-truthfulness extended; page copy states discovery + planning only —
  never execution, never an agent/model; no claim exceeds Spec 1277's Phase-1
  boundary.
• PR references traverse-embedder-web@0.8.0 (or later planner release) and Spec
  1277 / ADR-0062; documented local reproduction.

Non-goals

Natural-language goal parsing; a hosted or in-page LLM; automatic review/submission of
proposals; multi-plan auto-selection; registry or manifest mutation from the page;
retiring the authored-bundle Real mode; composed execution / per-node WASM traces
(Phase 2).

Related

• website#71 — Phase 2 execute
• website#58 (authored-bundle Real — shipped)
• discussion #1102, traverse#1150 (umbrella)
• Spec 1277, ADR-0062, Spec 108 / 109 / 113 / 1258
• traverse#1308 (web planner + release), traverse#1313 (composed-exec binding — code
  Done via PR #1315; npm 0.9.0 still required for Phase 2)

[enricopiovesan]

Blocked by traverse-framework/traverse#1308 (expose Spec 1277 browser-local planning + composed execution in traverse-embedder-web + release). Everything else this depends on is done — see the Upstream: DONE list above. Agent stays Unassigned until #1308 ships a consumable release.

[enricopiovesan]

Implementation plan — against traverse-embedder-web@0.8.0

Written from the real 0.8.0 API on main. Two phases, because 0.8.0 ships the
planner only (see traverse#1308 scope check): discovery + planning + review are
buildable the moment 0.8.0 hits npm; execution waits for a composed-execution web
binding.

0.8.0 surface this uses

• browserLocalPlan(identity, snapshot, dependencies, target, startingFacts, workspaceId, appManifest) -> { proposals: BrowserWorkflowProposal[], plan_search_truncated } — deterministic, structural only, no name/NL inference, bounded (5 candidates / 8 nodes / 64KB facts / 128 deps).
• MemoryRegistryCacheStore, prepareRegistryDependency(store, snapshot, ref, fetcher), resolveRegistryDependencyOffline(store, ref) -> VerifiedRegistryDependency { wasmBytes, contractBytes, wasmDigest, evidence }.
• SyncedPublicRegistryState { releaseTag, capabilities: [{namespace,id,version,digest,artifactUrl,contractUrl,contractDigest,deprecated}] }.
• BrowserPlanError codes for every fail-closed case (stale/empty/mismatched snapshot, dependency drift, bounds).

Phase 1 — discover + plan + review (unblocked by 0.8.0 publish)

New src/scripts/discover-discovered.js + a third opt-in panel:

1. Snapshot. Fetch catalog.json (already CORS-open). Build SyncedPublicRegistryState from it — every capability now carries contract_url + contract_digest (registry#383) and is_automatic_eligible + risk (registry#384). releaseTag from the catalog's release identifier.
2. Identity. BrowserSnapshotIdentity { registry_snapshot_digest, source_release, contract_schema_version: "1.0.0" }. The digest is sha256 of the canonical snapshot (planner recomputes and rejects a mismatch).
3. Prepare deps. For the capabilities in scope, prepareRegistryDependency with a RegistryArtifactFetcher that fetches WASM + contract from the CORS-open registry mirror (/artifacts/<ns>.<id>-<ver>/...), digest-verified against the catalog values.
4. Constrain to safe. Only pass dependencies whose catalog is_automatic_eligible === true (registry#384) into the planner. A committed set of demo goals (structured BrowserPlanTarget — capability_id/emits_event, no NL) + startingFacts.
5. Plan. browserLocalPlan(...). Render each BrowserWorkflowProposal: node chain, mapping_unconfirmed badges, plan_search_truncated / no-candidate states. This is the "review" gate — mappings stay unconfirmed; nothing executes.
6. Fail closed on every BrowserPlanError code with distinct copy; the six existing fail-closed strings are reused where they map.

Tests: discover-bundle.test.mjs builds a snapshot from a pinned catalog.json fixture and asserts browserLocalPlan returns the expected deterministic proposal + the drift/stale/bounds rejections. discover-truthfulness.test.mjs: the discovered panel claims discovery + planning only, never execution, never an agent/model. E2E: proposal renders, review gate holds, no execution occurs.

Phase 2 — composed execution (blocked on the web composed-execution binding)

Once the SDK exposes proposal -> execution (Spec 1277 FR-006): take a reviewed
BrowserWorkflowProposal + the prepared RegistryCacheStore, hand off to the local
governed execution path, render per-node real-WASM results + redacted traces, fail
closed on prepared-component drift / authorization denial / a failed node (replan or
halt per the runtime). E2E: one discovered-and-executed success + one fail-closed
rejection against a pinned snapshot fixture.

Copy / page structure

Third labelled path: Simulation · authored Real (one / pipeline) · discovered Real.
Above the fold: live / derived / simulated / real-authored / real-discovered. Phase 1
copy: "discovered from the live registry and planned in your browser — reviewed, not
executed." Phase 2 adds "...and executed." H1 unchanged; no claim exceeds Spec 1277's
boundary; links Spec 1277 / ADR-0062.

DoD mapping

Covers every checkbox in this ticket's description; Phase 1 covers discovery/planning/
review/constraint/fail-closed; Phase 2 covers execution/traces/failure-handling. PR(s)
reference traverse-embedder-web@0.8.0 (+ the composed-exec version for Phase 2).

[enricopiovesan]

Blocked-by updated: traverse#1308 (publish embedder 0.8.0 — planner) for Phase 1, traverse#1313 (composed-execution web binding, ships in 0.9.0) for Phase 2. Plan comment above already splits the work this way.

[enricopiovesan]

Decision log — brainstorm 2026-09-09

Session on website#68 (runtime-discovered governed composition on /discover). Newest decisions first in narrative order below.

Phase 1 public ship

Question: Ship discovered path when Phase 1 (plan + review) is ready, or hold until Phase 2 execute?

Options considered:

• Ship Phase 1 publicly — pros: unblocked on 0.8.0; honest “reviewed, not executed” boundary; cons: DoD spans two PRs
• Hold until Phase 2 — pros: one coherent demo; cons: blocked on #1313 / 0.9.0
• Ship Phase 1 behind a flag — pros: validates early without claiming finished; cons: flag lifecycle; most visitors see nothing

Recommendation: Ship Phase 1 publicly.

Decision: Ship Phase 1 publicly (plan + review, honest not-executed copy) as soon as traverse-embedder-web@0.8.0 lands.

Why: Matches Spec 1277’s review-without-execute boundary; avoids recreating the “blocked forever” pattern.

Catalog vs UI goal scope

Question: Which capabilities enter the browser-local planner?

Options considered:

• All live is_automatic_eligible caps — pros: strongest discovery claim; cons: drift + prep cost
• Curated allowlist only — pros: stable demo; cons: weaker discovery; looks like soft authored bundle
• Hybrid: full eligible catalog for planning; committed goal set in UI — pros: planning truth + reliable UX; cons: two concepts to explain; prep must be scoped

Recommendation: Hybrid.

Decision: Plan over the full eligible catalog; UI offers only a small committed goal set.

Why: Spec 1277 wants structural discovery against a verified snapshot; /discover still needs a reliable visitor path.

Committed goal set

Question: How should the Phase 1 committed goal set be defined?

Options considered:

• 2–3 fixed happy paths — pros: reliable; cons: hides fail-closed teaching
• One happy path + one intentional fail-closed / no-candidate / truncated — pros: matches DoD success+rejection; cons: fail case needs stability strategy
• Larger menu (5+) — pros: richer try-it feel; cons: maintenance + viewport clutter

Recommendation: One happy path + one fail-closed.

Decision: One happy-path target + one intentional fail-closed/no-candidate/truncated target.

Why: /discover’s job is truthfulness; DoD already requires success and rejection paths.

Dependency preparation

Question: When to prepare registry dependencies (fetch + digest-verify)?

Options considered:

• Eager: all eligible before plan — pros: simple; cons: heavy on marketing page
• Goal-scoped structural neighborhood (eligible-only) — pros: fits 2-goal UI; still live snapshot; cons: neighborhood rule must be explicit/tested
• Two-pass: plan without full WASM prep — pros: fastest Phase 1; cons: dead if 0.8.0 requires prepared deps

Recommendation: Goal-scoped, unless API check forces eager.

Decision: Goal-scoped prep of the structural neighborhood (eligible-only); verify browserLocalPlan does not require the full eligible set up front.

Why: Full-catalog planning truth without fetching every artifact on every visit.

Page structure

Question: How should discovered sit next to Simulation and authored Real?

Options considered:

• Third labelled panel/path — pros: clearest labels; doesn’t disturb shipped authored Real; cons: denser page
• Same Real column, authored vs discovered toggle — pros: keeps Simulation vs Real primary; cons: easier to blur claims
• Discovered as default Real; authored demoted — pros: matches medium-term story; cons: regresses simplest-case demo too early

Recommendation: Third labelled path for Phase 1.

Decision: Third labelled path — Simulation · authored Real · discovered Real. Revisit promotion after Phase 2 executes.

Why: Keep authored Real as the proven simplest case; give discovered its own live/derived/real-discovered labels.

Issue tracking

Question: How to track Phase 1 vs Phase 2 on GitHub?

Options considered:

• One issue; Phase 1 partial DoD, Phase 2 closes — pros: single narrative; cons: long-open; fuzzy Done
• Split: #68 = Phase 1; new issue = Phase 2 execute — pros: closable Done on 0.8.0 path; Phase 2 blocked cleanly on #1313; cons: two issues
• Umbrella + child issues — pros: visible umbrella; cons: process-heavy for two phases

Recommendation: Split now.

Decision: #68 = Phase 1 (discover + plan + review) only; file a new Phase 2 execute issue blocked on traverse #1313 / 0.9.0.

Why: Phase 1 is a public ship with its own honest boundary and deserves a closable DoD.

Fail-closed demo stability

Question: How should the intentional fail-closed goal stay honest as the live catalog grows?

Options considered:

• Structurally impossible target — pros: stable under catalog growth; cons: can feel synthetic without clear copy
• Policy/eligibility rejection — pros: teaches FR-005; cons: brittle on catalog contents
• Fixture-only failure; live UI success-only — pros: no live drift; cons: weakens on-page teaching

Recommendation: Structurally impossible target.

Decision: Use a structurally impossible target (no legal eligible candidate) for the live fail-closed demo; keep E2E rejection coverage as well.

Why: Demonstrates Spec 1277 no-candidate fail-closed without depending on a particular capability remaining unpublished.

Decision log location

Question: Where to save this session’s decision log?

Options considered:

• Comment on website #68 — pros: with the implementing ticket; cons: not a durable project log
• App-References docs/decision-log.md — pros: existing format; cons: wrong repo
• New website docs/decision-log.md — pros: right long-term home; cons: needs website PR scaffolding

Recommendation: Comment on #68 for now.

Decision: This comment.

Why: Agents implementing Phase 1 will read the issue; start a website decision log later if brainstorms keep recurring.

Explicitly deferred to implementation

• Exact happy-path BrowserPlanTarget (capability_id / emits_event + startingFacts) against the live eligible catalog
• Exact neighborhood rule wiring (per Spec 113 / planner API), after confirming 0.8.0 prep requirements
• Filing the Phase 2 issue body (blocked on #1313) and editing #68 DoD to Phase 1-only checkboxes

[enricopiovesan]

Split applied per brainstorm decisions:

• This issue (Phase 1: discover + plan + review on /discover (no execute) #68) = Phase 1 only (discover + plan + review). Title + DoD updated.
• Phase 2 execute: Phase 2: execute discovered workflow proposals on /discover #71 (blocked on consumable traverse-embedder-web@>=0.9.0; code path Done in traverse#1313 / PR #1315).

Phase 1 remains blocked until traverse-embedder-web@0.8.0 is on npm (currently still 0.7.0).

[enricopiovesan]

Claiming — traverse-embedder-web@0.9.0 is on npm (planner + composed execution). All upstream deps (registry#383/#384, traverse#1308/#1313/#1314) are closed. Building Phase 1 + Phase 2 per the plan above.

[enricopiovesan]

Build status — Phase 1 proceeding, Phase 2 blocked

Verified traverse-embedder-web@0.9.0 end to end from Node:

• Phase 1 (discover → snapshot → prepare → plan → review): WORKS. Catalog → verified 112-cap SyncedPublicRegistryState → prepareRegistryDependency (digest-verified from the CORS-open mirror) → browserLocalPlan → real proposal summary.aggregate → uncertainty.score, mapping_unconfirmed. Building this now.
• Phase 2 (composed execution): BLOCKED on registry#418. executeBrowserComposedWorkflow refuses every node (composed_workflow_approval_required) because it requires contract.risk.effect_class === "pure_read" && determinism_class === "deterministic", and registry#384 shipped the risk schema with conservative_default for all 136 pure capabilities — none are classified pure_read. Also needs risk included in the served contract.json.

Blocked-by: traverse#1313 (done — API), registry#418 (new — Phase 2 execution).

[enricopiovesan]

Phase 1 — PR #72, CI green

Runtime-discovered browser-local planning is built and verified end to end against the live registry:

• Fetch live catalog.json → digest-verified 112-capability snapshot → prepareRegistryDependency → browserLocalPlan (Spec 1277, deterministic, structural, no name/NL/model inference) → proposal summary.aggregate → uncertainty.score with all mappings unconfirmed.
• Five fail-closed states; review-only, nothing executed.
• npm test 12/12, npm run test:e2e 4/4 (incl. a live-registry discovered-mode E2E), build clean.

Phase 2 (composed execution) stays blocked on registry#418 — executeBrowserComposedWorkflow requires a pure_read/deterministic risk class that no published capability has yet. The page discloses this and links the issue.

Once #72 merges + registry#418 lands, Phase 2 is a small follow-up (swap the review gate for executeBrowserComposedWorkflow, render the ComposedWorkflowTrace).

[enricopiovesan]

Phase 2 — PR #73, CI green — closes the loop

registry#418 landed (17 caps classified pure_read/deterministic/is_automatic_eligible at @1.1.0, risk in contract.json), so Phase 2 is done:

/discover runtime-discovered mode now runs goal → discover from live registry → digest-verified snapshot → deterministic browser-local plan → explicit review gate → executeBrowserComposedWorkflow → redacted per-node trace.

• Review gate is real: mapping_unconfirmed cleared only by a separate "Confirm mappings & execute" click, only for that run. Execution never runs off the plan.
• Verified end to end (Node CHECK_REGISTRY + browser): plan summary.aggregate → uncertainty.score, review, execute → terminal_state: "succeeded", both nodes succeeded, offline.
• Browser is an untrusted proposer; the local governed runtime re-checks snapshot binding, digests, and per-node pure_read authorization, fails closed.
• npm test 12/12, npm run test:e2e 4/4, build clean.

Every DoD item in this ticket is now met. Ready to close on merge of #73.