Skip to content

Umbrella: gaps blocking real multi-OS product apps (registry + runtime + reference-apps) #826

Description

@enricopiovesan

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:

  • Embedded hosts on primary platforms (Web, Linux/CLI, Windows, Apple, Android)
  • First registry_ref cutover (traverse-starter.process)
  • Embedded Trace Explorer via embedded-trace-api/1.0.0
  • Digest-pinned Traverse-published starter agents (consume-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).

Meta Value
Kind Tracking / prioritization umbrella — not one implementable DoD
Owner org Traverse maintainers (split into Project 1 child tickets)
Consumer evidence repo https://github.com/traverse-framework/reference-apps
Consumer plan docs/production-reference-plan.md, docs/production-packaging.md, docs/production-playbook.md
Recent consumer PRs reference-apps #224 (registry_ref process), #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:

  1. 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.
  2. The one registry_ref component still requires an App-Refs materialize hack because embedders demand wasm_binary_path / wasm_digest.
  3. Traces and durable product state are process-local / permanence-blocked — Trace Explorer is useful for a session, useless for audit.
  4. Agents prove packaging + WASM execute, but are still example-grade, not a governed product agent supply chain.
  5. 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/registry capabilities/{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 same wasm_digest:

sha256:5647c39a1d25d8728350f9619025292a62e78a602068a2ad9b6f075751c93d99

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.jsonregistry_ref only (xor clean).
  • Destination sync: scripts/ci/sync_bundle_core.shsync_bundle_materialize_registry_refs.
  • 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

Status Issue / draft title Maps to
Blocked #814 browse/search synced public registry index §1.3
Blocked #810 document traverse-cli serve HTTP API §2.7 (needs narrative decision)
Blocked #788 production data-store adapter / integrity hash §2.3
Blocked #825 DataStore ownership locking §2.3
Blocked Permanence: trace store in-memory only §2.2
Blocked DataStore: migration, retention, encryption, remote KV, IndexedDB, sync protocol, peer sync, multi-process, … §2.3 cluster
Blocked upstream(swift): WasmKit public resource-control §2.5
Merged (decision draft) PR #801 Spec 518 / ADR-0017 durable local datastore §2.3 gate
Merged PR #811 dual-mode / synced component refs §1.2 partial
Merged PR #802 embedded Trace API §2.2 consumer exists; durability missing
Merged PR #795 / #809 real WASM agent execute §2.1 partial

1. 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_ref consumer cutover

Landed: Dual-mode component manifests (Traverse PR #811); App-Refs flipped only traverse-starter.process.

Still local-path in App-Refs:

  • traverse-starter.validate
  • traverse-starter.summarize
  • doc-approval.analyze
  • doc-approval.recommend
  • meeting-notes.process

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.

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 without registry sync; no TRAVERSE_REPO example 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:

  • list vs search semantics
  • contract retrieval / cache behavior
  • offline + error semantics
  • stable CLI UX for “what can I sync / pin?”

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:

author agent → package → digest → publish → consumers registry sync → resolve

Missing productized answers for:

  • who may publish (trust / signing)
  • namespace ownership
  • CI gates for publish
  • consumer-visible changelog / yank
  • 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
  • negative tests: no sync → actionable stable error (054 scenario 2)
  • 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
Local locking #825 cross-platform ownership locking
Format / ops Specify + implement migration, retention/compaction/backup/restore
Security Specify + implement encryption at rest + key lifecycle
Remote / browser Remote KV adapter; browser IndexedDB adapter
Sync Provider-neutral sync protocol; hosted transport; local peer conformance
Multi-process Specify + implement multi-process coordination

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-Refs vendor/traverse-embedder-web) still require local wasm_digest + wasm_binary_path when loading bundles.

Registry-ref-only manifests cannot be consumed directly without:

  • App-Refs sync_bundle_materialize_registry_refs, or
  • future embedder-native resolve from synced cache

Same class of issue likely on other hosts that assume local artifact trees.

Options (pick one product path):

  1. Embedder-native resolve at load/register time from synced public tier + content-addressed cache (preferred long-term; matches 054).
  2. First-class CLI traverse-cli … materialize-for-embed owned by Traverse, with tests — App-Refs wrappers become thin callers.
  3. Do not leave materialize as an undocumented App-Refs script forever.

2.5 Uneven native host hardening

Examples:

  • Swift / WasmKit public resource-control still upstream-blocked (Project 1)
  • Memory caps, kill/timeouts, update channels for runtime.wasm not equal across Web / Rust / Kotlin / .NET / Swift
  • Nightly CI in App-Refs proves “builds + smokes,” not production resource governance

2.6 Runtime pin / release channel DX

App-Refs pins runtime/runtime.wasm via runtime-release.json + per-platform sync wrappers. Kit-OK, product-incomplete:

  • documented release channels (stable / candidate)
  • upgrade / rollback
  • 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.

Needed decision (write it down once):

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.


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:

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)

  1. Decide HTTP vs embedded (§2.7) so Document traverse-cli serve as a development/CI HTTP API; direct production apps to embedded hosts #810 stops fighting the production narrative.
  2. Approve permanence specs — durable trace store + DataStore Spec 518 / ADR-0017 successors (§§2.2–2.3); unblock the Blocked cluster with real child DoDs.
  3. Embedder-native registry resolve (or first-class materialize CLI) (§2.4) — remove App-Refs hack as the long-term path.
  4. Registry productization — browse/search (Add CLI tooling to browse/search the synced public registry index, not just raw JSON #814) + publish DX (§1.4) + finish registry_ref cutover for the six primary capabilities (§1.2) + digest provenance (§1.8).
  5. Product agent quality bar + golden author → publish → consume path (§§2.1, 2.8).
  6. App-Refs follow-ups — remaining meeting-notes OS ports, registry-only manifests, thinner sync DX — only after 3–5 exist.
flowchart TD
  decision[Decide embedded vs HTTP narrative] --> permanence[Approve trace + DataStore permanence specs]
  permanence --> resolve[Embedder-native registry resolve]
  resolve --> cutover[Full registry_ref cutover + browse/publish DX]
  cutover --> agents[Product agent bar + golden path]
  agents --> apprefs[App-Refs OS ports + kit DX thinning]
Loading

5. Suggested child tickets (split this umbrella)

Create Project 1 tickets (Spec + DoD) roughly as:

Proposed Ticket ID Title focus Depends on
registry-browse-search-cli Implements #814 after spec Spec for #814
registry-publish-playbook One-command publish + trust/yank Registry governance
registry-ref-full-kit-cutover All six primary capabilities registry_ref §2.4 resolve path
embedder-registry-resolve Hosts resolve without App-Refs materialize 054/055
trace-store-permanence Durable trace store New/approved spec
datastore-permanence-mvp Minimal durable local DataStore MVP ADR-0017 approval path
runtime-release-channels Channels + compat matrix Release eng
http-serve-narrative Rescope or close #810 Product decision
golden-registry-consumer-app Traverse sample: all-registry, negative tests resolve + cutover
product-agent-bar Definition + one certified non-demo agent publish path
agent-author-golden-path Docs + CI template author→consume publish + resolve
digest-provenance-ci Forbid stub digests; registry SoT checks registry records

Each child must include: Ticket ID, Problem, Governing Spec/ADR, DoD checkboxes, Validation commands, Non-goals.


6. Explicit non-goals of this umbrella

  • Do not implement all gaps in one PR.
  • Do not treat App-Refs UI as the place to invent business logic.
  • Do not reopen sidecar as the production architecture for primary shells without a new approved product decision.
  • Do not use this issue as a claim lock for a single agent.
  • Do not flip more App-Refs components to registry_ref from this issue alone — use Project 2 consumer tickets after host resolve lands.

7. References

Area Pointer
Dual-mode / synced component refs Traverse PR #811
Embedded Trace API Traverse PR #802, spec 517-embedded-trace-api
Real WASM agent execute Traverse PRs #795, #809
DataStore decision draft Traverse PR #801 (Spec 518 / ADR-0017)
Registry browse/search Traverse #814
HTTP serve docs conflict Traverse #810
DataStore adapter integrity Traverse #788
DataStore locking Traverse #825
Public registry capabilities tree traverse-framework/registry capabilities/
Registry ref specs 054-public-scope-registry-ref, 055-registry-sync
App-Refs registry_ref consumer reference-apps #224, docs/production-packaging.md
App-Refs Trace Explorer embed reference-apps #225
App-Refs production kit plan docs/production-reference-plan.md
App-Refs materialize workaround scripts/ci/sync_bundle_core.shsync_bundle_materialize_registry_refs

Definition of Done (for closing this umbrella)

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions