You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
App-Refs can no longer close most of these alone. They need Traverse + Registry productization. Project 2 Ready queue for App-Refs-only engineering is effectively empty (only Future leftover: phase2-sidecar-nightly).
Meta
Value
Kind
Tracking / prioritization umbrella — not one implementable DoD
Owner org
Traverse maintainers (split into Project 1 child tickets)
Do not claim this umbrella as a single coding ticket. Spawn children with Ticket ID + governing Spec/ADR + DoD + Validation.
Why this exists (problem statement)
A new team trying to ship a real multi-OS Traverse product today hits this reality:
Capabilities exist in the public registry for starter / doc-approval / meeting-notes — but App-Refs still consumes 5 of 6 primary components via local-path + TRAVERSE_REPO example trees.
The one registry_ref component still requires an App-Refs materialize hack because embedders demand wasm_binary_path / wasm_digest.
Traces and durable product state are process-local / permanence-blocked — Trace Explorer is useful for a session, useless for audit.
Agents prove packaging + WASM execute, but are still example-grade, not a governed product agent supply chain.
Multi-OS shells exist for starter/doc-approval; meeting-notes and new domains still pay hand-port every OS.
Until sections 1–2 below move, App-Refs remains a proof kit, not a product factory.
Evidence snapshot (checked 2026-07)
A. App-Refs component source inventory (canonical manifests/)
App
Component path
Capability
Source today
Notes
traverse-starter
components/process/
traverse-starter.process
registry_ref^1.0.0
Only cutover; destination bundles still materialized
traverse-starter
components/validate/
traverse-starter.validate
local contract_path + wasm_*
Registry already has capabilities/traverse-starter/traverse-starter.validate/1.0.0/
traverse-starter
components/summarize/
traverse-starter.summarize
local contract_path + wasm_*
Registry already has summarize 1.0.0
doc-approval
components/analyze/
doc-approval.analyze
local
Registry has analyze 1.0.0
doc-approval
components/recommend/
doc-approval.recommend
local
Registry has recommend 1.0.0
meeting-notes
components/process/
meeting-notes.process
local
Registry has process 1.0.0
Cutover lag: public registry already lists the six primary reference capabilities under traverse-framework/registrycapabilities/{traverse-starter,doc-approval,meeting-notes}/…, but App-Refs only pins one via registry_ref. The blocker is no longer “nothing published for starter” — it is consumer + host resolve + publish-ops maturity.
B. Digest identity smell (local-path components)
Several local-path App-Refs component manifests currently share the samewasm_digest:
Observed on validate, summarize, doc-approval analyze/recommend, meeting-notes process (local-path rows). That is incompatible with a “registry digest is source of truth” product story and is a concrete cross-repo identity failure mode.
C. Materialize workaround (embedder friction)
Canonical process source: manifests/traverse-starter/components/process/component.manifest.json — registry_ref only (xor clean).
Behavior: strip registry_ref, write contract_path / wasm_binary_path / wasm_digest into destination trees for FetchBundleLoader-style hosts.
Docs: reference-apps docs/production-packaging.md (“Platform sync may materialize…”).
Needed long-term: embedder-native resolve from synced public tier + content-addressed cache (spec 054 FR-010/011), or a first-class Traverse CLI “materialize for embed” that is supported product path — not an App-Refs script.
D. Platform matrix (consumer shells)
App
Web
Linux GTK
CLI
iOS
macOS
Android
Windows
traverse-starter
✅
✅
✅
✅
✅
✅
✅
doc-approval
✅
✅
✅
✅
✅
✅
✅
meeting-notes
✅
✅
✅
❌
❌
❌
❌
trace-explorer
✅ (embedded API)
—
—
—
—
—
—
meeting-notes Wave 1 (Web + Linux/CLI) shipped; Apple/Windows/Android still hand-work for showcase Wave 2.
E. Project 1 items already tracking pieces of this umbrella
Today: Seeded capabilities cover the three reference apps (process/validate/summarize, analyze/recommend, meeting-notes.process) plus example/expedition trees. There is no product-sized catalog for connectors, vertical pipelines, third-party publishers, or “default supply chain” beyond the kit.
Why it blocks real apps: Teams cannot treat the registry as the default place to find what they need; they still vendor Traverse example trees.
Acceptance sketch (child ticket): Documented catalog tiers (kit / certified / community); at least one non-kit capability path with publish → sync → resolve evidence; consumer docs that do not require cloning Traverse examples for those capabilities.
Paradox: Those capabilities already exist under registry/capabilities/…. Cutover is blocked by host materialize friction (§2.4), digest provenance (§1.8), and “do not flip without Project 2 + published record” discipline — not by empty registry folders.
Acceptance sketch: All six primary App-Refs components are registry_ref-only in checked-in manifests; smoke fails closed without registry sync; no TRAVERSE_REPO example tree required for those six.
how App-Refs / third parties request a new capability without maintainers hand-seeding
Acceptance sketch: Published playbook + CI template; one external-shaped publish dry-run; yank/deprecate documented.
1.5 Version / identity ops immature
Independent versioning exists as registry decisions; day-2 ops are thin:
“what version does my app resolve?”
yank / deprecate / security advisory
range resolution (^1.0.0) evidence in consumer CI
multi-capability lockfiles / app-level pins vs floating ranges
conflict when app manifest digest ≠ registry digest (§1.8)
1.6 Registry sync is not the default developer first step
App-Refs still teaches TRAVERSE_REPO + example tree sync for most components. traverse-cli registry sync is additive, not the primary getting-started path for every capability.
Acceptance sketch: Getting-started (Traverse + App-Refs) leads with sync; TRAVERSE_REPO reserved for runtime pin / contributor workflows only.
1.7 No golden “app as registry consumer” template in Traverse
Consumers invent hybrid manifests. Traverse should own:
a golden sample app with all capabilities from registry
CI that fails if local-path sneaks back into the golden app
1.8 Cross-repo identity alignment
App-Refs app/component digests, registry-published digests, and smoke fixture digests have historically drifted (including identical stub digests on multiple local-path components — Evidence §B).
Needed: Single provenance story: registry digest is source of truth; consumer CI verifies against synced record; stub digests forbidden in primary shells.
1.9 Registry schema / sync DX gaps for embedders
Even after CLI register can resolve registry_ref against synced tier, bundle loaders used by UI hosts do not share that path (§2.4). Registry work is incomplete until the host packaging story is first-class, not only CLI validate/register.
1.10 No consumer lockfile / SBOM story
Product apps need a reproducible “what we resolved on date D” artifact (lockfile / SBOM-like pin set) for audits and rollback. Today pins are scattered across manifests, sync scripts, and runtime-release.json.
2. Runtime / Traverse host gaps
2.1 Demo-grade agents, not product agents
Real WASM execute landed (PRs #795 / #809). Example agents still prove packaging more than product business:
limited / stdout-style behavior relative to customer domains
model / connector dependencies not productized for app teams
governed secrets / policy incomplete for “ship to customers”
no clear support bar for “this is what product apps call”
App-Refs impact:consume-product-wasm-agents can only mean “Traverse-published starter agents,” not customer-grade agents.
2.2 Trace durability (in-memory only)
Tracked: Project 1 Blocked — “Permanence: trace store is in-memory only, all trace/audit history lost on restart.”
Needs approved successor spec/ADR for:
storage format
retention
recovery
private-trace compatibility
durable-write error semantics
App-Refs impact: Trace Explorer after #225 uses embedded-trace-api (PR #802) — safe, process-local only. Fine for session debug; useless for production audit / support.
2.3 DataStore permanence cluster (blocked)
Canonical gate: formal approval follow-through on Draft Spec 518 / ADR-0017 (PR #801 merged as draft decision).
Blocked Project 1 cluster includes:
Theme
Example titles
Adapter integrity
#788 production adapter call sites + integrity hash
compatibility matrix: embedder-api version × runtime digest × registry schema × capability ABI
2.7 Sidecar vs embedded narrative conflict
HTTP traverse-cli serve is deprecated appendix in App-Refs production docs. Project 1 still has Blocked #810 “Document traverse-cli serve's HTTP API as the real generic capability/workflow execution path” — which conflicts with embedded-first production unless explicitly rescoped.
B) Governed remote-host product exists → new spec, not “document serve as the real path” under the old framing
2.8 Authoring DX for new agents/apps
Missing short golden path with CI templates:
build real agent → package → digest → publish → sync → consume from UI shell
Today authors must understand specs, examples trees, registry seeds, and embedder packages separately.
2.9 Observability beyond safe Trace API
embedded-trace-api/1.0.0 correctly exposes safe projections (no raw payloads). Product debugging still needs a governed story for deeper diagnostics without reintroducing sidecar-as-architecture.
2.10 Connector / model dependency productization
Governed model dependency execution exists in pieces; turning that into something app teams configure for real domains (doc approval, meeting notes, custom verticals) is incomplete relative to “ship a product.”
2.11 Error UX / actionable failures at the host boundary
When sync missing, digest mismatch, capability yanked, or runtime pin incompatible, hosts and CLI should share stable, documented error codes that UI shells can render. Partial today; not productized for all registry_ref failure modes.
2.12 Update / distribution of runtime.wasm for shipped apps
Kit sync assumes a Traverse checkout or release JSON. Product apps need an update channel story (CDN / release API / OS package) that does not require developers to re-sync from a monorepo.
Mostly symptoms of §§1–2, but they still prevent “copy this repo → ship my product.”
3.1 Kit ≠ product factory
App-Refs proves multi-OS embedded shells. It does not provide a turnkey generator:
new domain app → manifests → agents → all OS clients → CI → store packages
3.2 Hybrid manifests remain the norm
Only traverse-starter.process uses registry_ref. Getting-started still centers on cloning Traverse for the rest (§1.2 / Evidence §A).
3.3 Incomplete OS matrix for non-starter domains
meeting-notes: Web + Linux GTK + CLI only. New domains inherit “port every OS by hand” cost (§ Evidence §D).
3.4 Heavy sync / pin DX
Per-platform scripts (sync_web_*, sync_swift_*, sync_android_*, sync_winui_*), digest pins, and materialization are powerful but expert-only. Product teams need fewer concepts (one sync entrypoint, clear failure modes).
3.5 Smoke / CI still kit-shaped
embedded_smoke proves host + runtime-owned fields. It does not prove:
customer agents from registry end-to-end without TRAVERSE_REPO examples
durable traces/state
store packaging / update channels
yank / range-resolve failure paths
3.6 Trace Explorer is embedded but session-local
After reference-apps #225, no sidecar — but without durable trace store (§2.2) it remains a local-session debugger, not a production audit UI.
3.7 Docs / board drift risk
Status tables in plans sometimes lag Project 2 flips. Slows agents and humans discovering what is Ready (process issue, not runtime).
3.8 Secondary demos vs primary shells
react-demo, android-demo, macos-demo, youaskm3-starter-kit are lighter kits. Without hard boundaries, teams copy the wrong pattern (partially mitigated by docs/adopted-platform-clients.md + production plan tiers).
3.9 No App-Refs ticket left for most product blockers
Project 2 non-Done leftover observed: Future phase2-sidecar-nightly only. Upstream must move (this issue §§1–2) before App-Refs can claim meaningful Ready work again.
3.10 Store packaging / signing not a Traverse-owned consumer story
OS store packages (Apple, Play, MSIX, etc.) are app-team concerns, but the kit does not yet demonstrate a reference “release channel + signed artifact + runtime pin” path per OS beyond CI smoke.
3.11 Accessibility / localization / design-system product bar
Reference UIs prove runtime field rendering. They are not a full product UX kit (a11y, i18n, design tokens beyond design-language docs). Lower priority than §§1–2, but real for “ship.”
4. Suggested sequencing (maintainers — not binding)
Summary
Cross-cutting gap inventory blocking shipping real multi-OS product apps on Traverse — not just reference demos or kit smoke.
This issue consolidates every gap observed from App-References (Project 2 /
traverse-framework/reference-apps) after Wave 1–2 kit work landed:registry_refcutover (traverse-starter.process)embedded-trace-api/1.0.0consume-product-wasm-agents)App-Refs can no longer close most of these alone. They need Traverse + Registry productization. Project 2 Ready queue for App-Refs-only engineering is effectively empty (only Future leftover:
phase2-sidecar-nightly).docs/production-reference-plan.md,docs/production-packaging.md,docs/production-playbook.md#224(registry_refprocess),#225(Trace Explorer embed),#227(product WASM agents)Do not claim this umbrella as a single coding ticket. Spawn children with Ticket ID + governing Spec/ADR + DoD + Validation.
Why this exists (problem statement)
A new team trying to ship a real multi-OS Traverse product today hits this reality:
TRAVERSE_REPOexample trees.registry_refcomponent still requires an App-Refs materialize hack because embedders demandwasm_binary_path/wasm_digest.Until sections 1–2 below move, App-Refs remains a proof kit, not a product factory.
Evidence snapshot (checked 2026-07)
A. App-Refs component source inventory (canonical
manifests/)components/process/traverse-starter.processregistry_ref^1.0.0components/validate/traverse-starter.validatecontract_path+wasm_*capabilities/traverse-starter/traverse-starter.validate/1.0.0/components/summarize/traverse-starter.summarizecontract_path+wasm_*components/analyze/doc-approval.analyzecomponents/recommend/doc-approval.recommendcomponents/process/meeting-notes.processCutover lag: public registry already lists the six primary reference capabilities under
traverse-framework/registrycapabilities/{traverse-starter,doc-approval,meeting-notes}/…, but App-Refs only pins one viaregistry_ref. The blocker is no longer “nothing published for starter” — it is consumer + host resolve + publish-ops maturity.B. Digest identity smell (local-path components)
Several local-path App-Refs component manifests currently share the same
wasm_digest:Observed on validate, summarize, doc-approval analyze/recommend, meeting-notes process (local-path rows). That is incompatible with a “registry digest is source of truth” product story and is a concrete cross-repo identity failure mode.
C. Materialize workaround (embedder friction)
manifests/traverse-starter/components/process/component.manifest.json—registry_refonly (xor clean).scripts/ci/sync_bundle_core.sh→sync_bundle_materialize_registry_refs.registry_ref, writecontract_path/wasm_binary_path/wasm_digestinto destination trees forFetchBundleLoader-style hosts.docs/production-packaging.md(“Platform sync may materialize…”).Needed long-term: embedder-native resolve from synced public tier + content-addressed cache (spec 054 FR-010/011), or a first-class Traverse CLI “materialize for embed” that is supported product path — not an App-Refs script.
D. Platform matrix (consumer shells)
meeting-notes Wave 1 (Web + Linux/CLI) shipped; Apple/Windows/Android still hand-work for showcase Wave 2.
E. Project 1 items already tracking pieces of this umbrella
traverse-cli serveHTTP API1. Registry gaps
1.1 Thin / demo-shaped public catalog
Today: Seeded capabilities cover the three reference apps (process/validate/summarize, analyze/recommend, meeting-notes.process) plus example/expedition trees. There is no product-sized catalog for connectors, vertical pipelines, third-party publishers, or “default supply chain” beyond the kit.
Why it blocks real apps: Teams cannot treat the registry as the default place to find what they need; they still vendor Traverse example trees.
Acceptance sketch (child ticket): Documented catalog tiers (kit / certified / community); at least one non-kit capability path with publish → sync → resolve evidence; consumer docs that do not require cloning Traverse examples for those capabilities.
1.2 Incomplete
registry_refconsumer cutoverLanded: Dual-mode component manifests (Traverse PR #811); App-Refs flipped only
traverse-starter.process.Still local-path in App-Refs:
traverse-starter.validatetraverse-starter.summarizedoc-approval.analyzedoc-approval.recommendmeeting-notes.processParadox: Those capabilities already exist under
registry/capabilities/…. Cutover is blocked by host materialize friction (§2.4), digest provenance (§1.8), and “do not flip without Project 2 + published record” discipline — not by empty registry folders.Governing specs:
054-public-scope-registry-ref,055-registry-sync.Acceptance sketch: All six primary App-Refs components are
registry_ref-only in checked-in manifests; smoke fails closed withoutregistry sync; noTRAVERSE_REPOexample tree required for those six.1.3 No browse / search of synced public index
Tracked: #814 (Blocked — needs governing spec).
Operators still dig raw JSON / repo trees. Needed:
Why it blocks real apps: Discovery is expert-only; app authors cannot answer “is X published at ^1?” without repo spelunking.
1.4 Publish path is expert-only
Publishing still looks like an internal registry-repo / seed-PR workflow, not a documented one-command flow:
Missing productized answers for:
Acceptance sketch: Published playbook + CI template; one external-shaped publish dry-run; yank/deprecate documented.
1.5 Version / identity ops immature
Independent versioning exists as registry decisions; day-2 ops are thin:
^1.0.0) evidence in consumer CI1.6 Registry sync is not the default developer first step
App-Refs still teaches
TRAVERSE_REPO+ example tree sync for most components.traverse-cli registry syncis additive, not the primary getting-started path for every capability.Acceptance sketch: Getting-started (Traverse + App-Refs) leads with sync;
TRAVERSE_REPOreserved for runtime pin / contributor workflows only.1.7 No golden “app as registry consumer” template in Traverse
Consumers invent hybrid manifests. Traverse should own:
1.8 Cross-repo identity alignment
App-Refs app/component digests, registry-published digests, and smoke fixture digests have historically drifted (including identical stub digests on multiple local-path components — Evidence §B).
Needed: Single provenance story: registry digest is source of truth; consumer CI verifies against synced record; stub digests forbidden in primary shells.
1.9 Registry schema / sync DX gaps for embedders
Even after CLI register can resolve
registry_refagainst synced tier, bundle loaders used by UI hosts do not share that path (§2.4). Registry work is incomplete until the host packaging story is first-class, not only CLI validate/register.1.10 No consumer lockfile / SBOM story
Product apps need a reproducible “what we resolved on date D” artifact (lockfile / SBOM-like pin set) for audits and rollback. Today pins are scattered across manifests, sync scripts, and
runtime-release.json.2. Runtime / Traverse host gaps
2.1 Demo-grade agents, not product agents
Real WASM execute landed (PRs #795 / #809). Example agents still prove packaging more than product business:
App-Refs impact:
consume-product-wasm-agentscan only mean “Traverse-published starter agents,” not customer-grade agents.2.2 Trace durability (in-memory only)
Tracked: Project 1 Blocked — “Permanence: trace store is in-memory only, all trace/audit history lost on restart.”
Needs approved successor spec/ADR for:
App-Refs impact: Trace Explorer after
#225usesembedded-trace-api(PR #802) — safe, process-local only. Fine for session debug; useless for production audit / support.2.3 DataStore permanence cluster (blocked)
Canonical gate: formal approval follow-through on Draft Spec 518 / ADR-0017 (PR #801 merged as draft decision).
Blocked Project 1 cluster includes:
Why it blocks real apps: No durable product state story across platforms. UI shells cannot honestly claim “offline product with recoverable state.”
2.4 Host packaging friction for
registry_ref(critical)Web embedder /
FetchBundleLoader(and App-Refsvendor/traverse-embedder-web) still require localwasm_digest+wasm_binary_pathwhen loading bundles.Registry-ref-only manifests cannot be consumed directly without:
sync_bundle_materialize_registry_refs, orSame class of issue likely on other hosts that assume local artifact trees.
Options (pick one product path):
traverse-cli … materialize-for-embedowned by Traverse, with tests — App-Refs wrappers become thin callers.2.5 Uneven native host hardening
Examples:
runtime.wasmnot equal across Web / Rust / Kotlin / .NET / Swift2.6 Runtime pin / release channel DX
App-Refs pins
runtime/runtime.wasmviaruntime-release.json+ per-platform sync wrappers. Kit-OK, product-incomplete:2.7 Sidecar vs embedded narrative conflict
HTTP
traverse-cli serveis deprecated appendix in App-Refs production docs. Project 1 still has Blocked #810 “Document traverse-cli serve's HTTP API as the real generic capability/workflow execution path” — which conflicts with embedded-first production unless explicitly rescoped.Needed decision (write it down once):
2.8 Authoring DX for new agents/apps
Missing short golden path with CI templates:
Today authors must understand specs, examples trees, registry seeds, and embedder packages separately.
2.9 Observability beyond safe Trace API
embedded-trace-api/1.0.0correctly exposes safe projections (no raw payloads). Product debugging still needs a governed story for deeper diagnostics without reintroducing sidecar-as-architecture.2.10 Connector / model dependency productization
Governed model dependency execution exists in pieces; turning that into something app teams configure for real domains (doc approval, meeting notes, custom verticals) is incomplete relative to “ship a product.”
2.11 Error UX / actionable failures at the host boundary
When sync missing, digest mismatch, capability yanked, or runtime pin incompatible, hosts and CLI should share stable, documented error codes that UI shells can render. Partial today; not productized for all
registry_reffailure modes.2.12 Update / distribution of
runtime.wasmfor shipped appsKit sync assumes a Traverse checkout or release JSON. Product apps need an update channel story (CDN / release API / OS package) that does not require developers to re-sync from a monorepo.
3. Reference apps / consumer kit gaps (downstream symptoms)
Mostly symptoms of §§1–2, but they still prevent “copy this repo → ship my product.”
3.1 Kit ≠ product factory
App-Refs proves multi-OS embedded shells. It does not provide a turnkey generator:
3.2 Hybrid manifests remain the norm
Only
traverse-starter.processusesregistry_ref. Getting-started still centers on cloning Traverse for the rest (§1.2 / Evidence §A).3.3 Incomplete OS matrix for non-starter domains
meeting-notes: Web + Linux GTK + CLI only. New domains inherit “port every OS by hand” cost (§ Evidence §D).
3.4 Heavy sync / pin DX
Per-platform scripts (
sync_web_*,sync_swift_*,sync_android_*,sync_winui_*), digest pins, and materialization are powerful but expert-only. Product teams need fewer concepts (one sync entrypoint, clear failure modes).3.5 Smoke / CI still kit-shaped
embedded_smokeproves host + runtime-owned fields. It does not prove:TRAVERSE_REPOexamples3.6 Trace Explorer is embedded but session-local
After reference-apps
#225, no sidecar — but without durable trace store (§2.2) it remains a local-session debugger, not a production audit UI.3.7 Docs / board drift risk
Status tables in plans sometimes lag Project 2 flips. Slows agents and humans discovering what is Ready (process issue, not runtime).
3.8 Secondary demos vs primary shells
react-demo,android-demo,macos-demo,youaskm3-starter-kitare lighter kits. Without hard boundaries, teams copy the wrong pattern (partially mitigated bydocs/adopted-platform-clients.md+ production plan tiers).3.9 No App-Refs ticket left for most product blockers
Project 2 non-Done leftover observed: Future
phase2-sidecar-nightlyonly. Upstream must move (this issue §§1–2) before App-Refs can claim meaningful Ready work again.3.10 Store packaging / signing not a Traverse-owned consumer story
OS store packages (Apple, Play, MSIX, etc.) are app-team concerns, but the kit does not yet demonstrate a reference “release channel + signed artifact + runtime pin” path per OS beyond CI smoke.
3.11 Accessibility / localization / design-system product bar
Reference UIs prove runtime field rendering. They are not a full product UX kit (a11y, i18n, design tokens beyond design-language docs). Lower priority than §§1–2, but real for “ship.”
4. Suggested sequencing (maintainers — not binding)
registry_refcutover for the six primary capabilities (§1.2) + digest provenance (§1.8).5. Suggested child tickets (split this umbrella)
Create Project 1 tickets (Spec + DoD) roughly as:
registry-browse-search-cliregistry-publish-playbookregistry-ref-full-kit-cutoverregistry_refembedder-registry-resolvetrace-store-permanencedatastore-permanence-mvpruntime-release-channelshttp-serve-narrativegolden-registry-consumer-appproduct-agent-baragent-author-golden-pathdigest-provenance-ciEach child must include: Ticket ID, Problem, Governing Spec/ADR, DoD checkboxes, Validation commands, Non-goals.
6. Explicit non-goals of this umbrella
registry_reffrom this issue alone — use Project 2 consumer tickets after host resolve lands.7. References
517-embedded-trace-apitraverse-framework/registrycapabilities/054-public-scope-registry-ref,055-registry-syncregistry_refconsumer#224,docs/production-packaging.md#225docs/production-reference-plan.mdscripts/ci/sync_bundle_core.sh→sync_bundle_materialize_registry_refsDefinition of Done (for closing this umbrella)