From 09ad28833d505026da697a45806259d748265768 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Mon, 6 Jul 2026 16:40:34 -0600 Subject: [PATCH 1/2] Define Phase 3 embedded runtime architecture in governance docs. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit HTTP sidecar is dev-only; production target is WASM runtime in every app with uniform platform embedder. Links to Traverse specs 057–059 and registry spec 008. Co-authored-by: Cursor --- .agents/skills/app-refs-ops/SKILL.md | 9 +- .specify/memory/constitution.md | 6 +- AGENTS.md | 16 ++- CLAUDE.md | 15 ++- README.md | 103 ++++++++++++++---- docs/design-language.md | 8 +- docs/embedded-runtime-plan.md | 150 +++++++++++++++++++++++++++ docs/quality-standards.md | 8 +- docs/traverse-runtime.md | 51 +++++---- docs/traverse-starter-plan.md | 25 +++-- 10 files changed, 319 insertions(+), 72 deletions(-) create mode 100644 docs/embedded-runtime-plan.md diff --git a/.agents/skills/app-refs-ops/SKILL.md b/.agents/skills/app-refs-ops/SKILL.md index 2cb685f..02da128 100644 --- a/.agents/skills/app-refs-ops/SKILL.md +++ b/.agents/skills/app-refs-ops/SKILL.md @@ -15,13 +15,12 @@ APP REFS OPS ## Context -This repo is **UI-only**. Traverse runtime and business logic live outside this repo. -The UI must not compute business fields (tags, note type, next action, status) — it renders runtime-provided data only. +This repo is **UI-only**. Business logic lives in Traverse WASM agents. **Phase 3 target:** embedded runtime in every platform app. Phase 1/2 HTTP sidecar is dev-only interim. All tickets live in [Project 2](https://github.com/orgs/traverse-framework/projects/2) (`traverse-framework`, project number `2`). The target repo is `traverse-framework/reference-apps` (GitHub slug; product name App-References). -Read `docs/traverse-starter-plan.md` and `.specify/memory/constitution.md` before any implementation work. +Read `docs/embedded-runtime-plan.md`, `docs/traverse-starter-plan.md`, and `.specify/memory/constitution.md` before any implementation work. ## Continuous run mode (default) @@ -182,7 +181,9 @@ Minimality must never push business logic into the UI, import private Traverse i - **Never** import private Traverse internals - **Never** fake workflow registration or runtime behavior in application code - **Always** drive UI state from runtime-provided events -- Phase 2 (app validation/registration) is **blocked** until Traverse public CLI surface exists +- Phase 3 (embedded in-app runtime) is the production target — see `docs/embedded-runtime-plan.md` +- Phase 2 (app validation/registration) uses Traverse CLI against dev sidecar +- Phase 1 HTTP sidecar is **not** the shipping architecture ## Operating Lanes diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md index 6f27028..b0a1079 100644 --- a/.specify/memory/constitution.md +++ b/.specify/memory/constitution.md @@ -21,6 +21,8 @@ Phase 1 is deterministic and does not require live AI access. It does require a ### V. Phase Gate Discipline Phase 2 (app validation and registration via Traverse CLI) is available when the Traverse public CLI surface (`traverse-cli app validate`, `traverse-cli app register`) is present in a released or pinned build (v0.5.0+). Do not implement a workaround, HTTP registration endpoint, or service registry as a substitute for the CLI flow. Phase 2 work must use the official CLI surface and remain within the UI-only architecture boundary of this repo. +Phase 3 (embedded in-app WASM runtime) is the **production target** for all platform clients. Shipped apps must bundle the Traverse host and WASM artifacts; they must not require a separate `traverse-cli serve` process for end users. Phase 1 HTTP sidecar integration is a dev/CI path only until Phase 3 migration completes. See `docs/embedded-runtime-plan.md`. + ### VI. Traceability Every meaningful change must be tracked through a GitHub issue, a Project 2 item, and a pull request. These three artifacts are the minimum traceability model. @@ -41,7 +43,7 @@ When multiple agents work in parallel, claim before you code. Check for any exis - **Determinism**: same runtime events must produce the same rendered output - **Testability**: non-trivial UI logic must be designed for full automated verification - **Maintainability**: component boundaries must support long-term evolution without hidden coupling to runtime internals -- **Portability**: the UI shell must remain deployable as a standard web app without coupling to a specific Traverse host or infrastructure vendor +- **Portability**: each platform client ships as a self-contained app with an embedded Traverse runtime host; dev HTTP sidecar is optional and not the production deployment model - **Reproducibility**: builds, tests, and CI gates must be reproducible from pinned inputs and documented commands ## Development Workflow @@ -65,4 +67,4 @@ All reviews must check for: Amendments require documenting the rule being changed, the reason, and the migration impact. -**Version**: 1.0.1 | **Ratified**: 2026-06-27 | **Amended**: 2026-07-06 — Principle V: Phase 2 unblocked at Traverse v0.5.0+; Principle VIII: multi-agent pre-flight aligned with `AGENTS.md` +**Version**: 1.1.0 | **Ratified**: 2026-06-27 | **Amended**: 2026-07-06 — Phase 3 embedded runtime as production target; Phase 1 HTTP sidecar demoted to dev-only path diff --git a/AGENTS.md b/AGENTS.md index fc84ac6..ea1c4de 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # App-References Development Guidelines -This repo is **UI-only**. Traverse runtime and business logic live outside this repo. +This repo is **UI-only**. Business logic and WASM agents live in the Traverse framework. **Shipped apps embed the Traverse runtime host (Phase 3 target);** Phase 1/2 dev uses an external HTTP sidecar. ## Current State @@ -40,9 +40,11 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \ ### Blocked work summary -- **Web SSE refactor** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on Traverse #525, #526, #527 -- **Platform SSE upgrade (Phase 2)** — iOS/macOS/Android/Windows/Linux/CLI Phase 1 scaffolds use HTTP polling; SSE blocked on same Traverse issues -- **doc-approval shared core** ([#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — extract shared Swift/Rust client packages; blocked on Phase 2 SSE / shared crate design +- **Phase 3 embedded runtime** ([#109](https://github.com/traverse-framework/reference-apps/issues/109)–[#118](https://github.com/traverse-framework/reference-apps/issues/118)) — see `docs/embedded-runtime-plan.md`; blocked on [Traverse #553](https://github.com/traverse-framework/Traverse/issues/553) +- **Multi-capability showcase workflows** ([#110](https://github.com/traverse-framework/reference-apps/issues/110), [#111](https://github.com/traverse-framework/reference-apps/issues/111)) — pipeline workflows with multiple WASM agents +- **Web SSE refactor** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on Traverse **#527** only (#525/#526 done) +- **Platform SSE upgrade** — iOS/macOS/Android/Windows/Linux/CLI Phase 1 scaffolds use HTTP polling; SSE blocked on same Traverse issues +- **Shared embedded host packages** ([#58](https://github.com/traverse-framework/reference-apps/issues/58), [#59](https://github.com/traverse-framework/reference-apps/issues/59), [#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — Swift/Rust wrappers around embeddable host SDK; blocked on Phase 3 SDK Update this section when a PR changes platform status (see PR template checklist). @@ -76,7 +78,9 @@ scripts/ci/ # CI gate scripts ## Traverse Runtime -**Current release: v0.6.0** (recommended for all phases) | Phase 1 minimum: v0.3.0 | Phase 2 minimum: v0.5.0 | API spec: **033-http-json-api** (approved v1.1.0) +**Production target (Phase 3):** embedded in-app WASM runtime host in every platform client — see `docs/embedded-runtime-plan.md`. + +**Dev sidecar (Phase 1/2, current):** v0.6.0 recommended | Phase 1 minimum: v0.3.0 | Phase 2 minimum: v0.5.0 | API spec: **033-http-json-api** (approved v1.1.0) ```bash # Start local runtime @@ -103,6 +107,8 @@ npm run typecheck npm run lint npm run test npm run test:coverage +bash scripts/dev/check-native-prerequisites.sh # doc-approval native toolchain (macOS) +bash scripts/dev/test-doc-approval-macos.sh # doc-approval unit tests (macOS-testable platforms) bash scripts/ci/repository_checks.sh bash scripts/ci/phase1_smoke.sh ``` diff --git a/CLAUDE.md b/CLAUDE.md index d29e222..1dcec4f 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -2,9 +2,7 @@ ## Repo Purpose -This repo is **UI-only**. Traverse runtime and business logic live outside this repo. -The React UI must not compute business fields — it renders, sorts, filters, and displays -data provided by the Traverse runtime. +This repo is **UI-only**. Business logic and WASM agents live in Traverse. **Phase 3 target:** each platform app embeds the WASM runtime host. Phase 1/2 dev uses an HTTP sidecar until migration completes. See `docs/traverse-starter-plan.md` for the full plan and architecture boundary. @@ -95,16 +93,15 @@ Read `.specify/memory/constitution.md` before any implementation work. Key rules | Detail | Value | |---|---| -| Current release | **v0.6.0** (recommended checkout for all phases) | +| **Production target (Phase 3)** | Embedded in-app WASM runtime host in every platform client | +| Dev sidecar (Phase 1/2 interim) | **v0.6.0** — `cargo run -p traverse-cli -- serve` @ `127.0.0.1:8787` | | Phase 1 minimum | v0.3.0 — HTTP/JSON API | | Phase 2 minimum | v0.5.0 — CLI app validate/register | -| Start runtime | `cargo run -p traverse-cli -- serve` | -| Default address | `127.0.0.1:8787` | -| Discovery file | `.traverse/server.json` | | Default workspace | `local-default` | -| Governing API spec | `033-http-json-api` (approved v1.1.0) | +| Governing API spec (dev sidecar) | `033-http-json-api` (approved v1.1.0) | +| Phase 3 plan | `docs/embedded-runtime-plan.md` | -Local setup: +Dev sidecar setup (interim): ```bash git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse cd /tmp/traverse && git checkout v0.6.0 diff --git a/README.md b/README.md index 33031ac..f3f1136 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,9 @@ Reference UI applications for the [Traverse](https://github.com/traverse-framework/Traverse) framework. -**Architecture in one sentence:** This repo is UI-only. All business logic runs in the Traverse WASM runtime — the React clients start workflows, subscribe to events, and render runtime-provided output. +**Architecture in one sentence:** This repo is UI-only. Each platform ships a **native UI shell** with an **embedded Traverse WASM runtime** (Phase 3 target). Business logic lives in bundled WASM agents; the UI starts workflows and renders runtime-provided output only. + +> **Current state:** Phase 1/2 clients still use an HTTP dev sidecar (`traverse-cli serve`). Phase 3 migration is tracked on [Project 2](https://github.com/orgs/traverse-framework/projects/2). See [`docs/embedded-runtime-plan.md`](docs/embedded-runtime-plan.md). ## Prerequisites @@ -12,28 +14,15 @@ Reference UI applications for the [Traverse](https://github.com/traverse-framewo - **Rust 1.94+** (to build and run the Traverse runtime) - **`gh` CLI** (for agents claiming Project 2 tickets) -## Getting Started +## Getting Started (Phase 1/2 dev sidecar) +Until Phase 3 embedded runtime lands, local development uses a separate Traverse process: ```bash # 1. Clone this repo git clone https://github.com/traverse-framework/reference-apps.git cd reference-apps -# 2. Clone and start the Traverse runtime (separate terminal) -git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse -cd /tmp/traverse && git checkout v0.6.0 -cargo run -p traverse-cli -- serve -# Writes .traverse/server.json → http://127.0.0.1:8787 - -# 3. Install dependencies -npm install - -# 4. Start the traverse-starter dev server -npm run dev -# Opens http://localhost:5173 - -# 5. In the browser: type a note → Start Workflow → see structured output -``` +# 2. Clone and start the Traverse dev sidecar (separate terminal — not required in Phase 3) ## What You Will See @@ -51,13 +40,14 @@ A successful run shows all five output fields populated by the runtime. The UI c |---|---| | [`apps/traverse-starter/web-react/`](apps/traverse-starter/web-react/) | traverse-starter React UI shell | | [`apps/trace-explorer/web-react/`](apps/trace-explorer/web-react/) | Trace Explorer — execution timeline debugger | -| [`docs/`](docs/) | Plan, runtime setup, quality standards | +| [`docs/embedded-runtime-plan.md`](docs/embedded-runtime-plan.md) | Phase 3 target — embedded runtime + multi-capability workflows | +| [`docs/traverse-runtime.md`](docs/traverse-runtime.md) | Dev sidecar setup (Phase 1/2) | | [`manifests/traverse-starter/`](manifests/traverse-starter/) | App manifest + component manifests (Phase 2) | | [`scripts/ci/`](scripts/ci/) | Repository checks, smoke tests, coverage gate | ## Platform clients -All clients are UI-only shells — they invoke the runtime and render structured output. Phase 1 scaffolds use HTTP polling; SSE upgrade is tracked in [#43](https://github.com/traverse-framework/reference-apps/issues/43). +All clients are **native UI shells** separated from business logic. Phase 1/2 use an HTTP dev sidecar; **Phase 3 embeds the WASM runtime in every app** ([#109](https://github.com/traverse-framework/reference-apps/issues/109)–[#118](https://github.com/traverse-framework/reference-apps/issues/118)). SSE upgrade tracked in [#43](https://github.com/traverse-framework/reference-apps/issues/43). | Platform | Status | Path | |---|---|---| @@ -94,6 +84,73 @@ bash scripts/ci/phase1_smoke.sh # requires running runtime bash scripts/ci/onboarding_check.sh # local setup verification (runtime steps skip if offline) ``` +### doc-approval native testing on macOS + +Platforms testable on a Mac without a Linux/Windows VM: **web-react**, **cli-rust**, **macos-swift**, **ios-swift**, **android-compose**. + +**One-time prerequisites** + +| Tool | Purpose | Install | +|---|---|---| +| Xcode 16+ | iOS + macOS | App Store | +| JDK 17 | Android Gradle tests | `brew install openjdk@17` | +| Android command-line tools | SDK for Gradle + emulator | `brew install android-commandlinetools` | +| Android Studio | Android emulator (manual runs) | [developer.android.com](https://developer.android.com/studio) (optional if using CLI SDK) | +| Rust | CLI client | [rustup.rs](https://rustup.rs/) | + +**Check prerequisites** + +```bash +source scripts/dev/android-env.sh # JAVA_HOME + ANDROID_HOME (after brew install below) +bash scripts/dev/check-native-prerequisites.sh +``` + +**Android SDK one-time install (Homebrew, no Android Studio required for unit tests)** + +```bash +brew install openjdk@17 android-commandlinetools +source scripts/dev/android-env.sh +yes | sdkmanager --licenses +sdkmanager "platform-tools" "platforms;android-35" "build-tools;35.0.0" +``` + +**Run all macOS-testable unit tests** + +```bash +bash scripts/dev/test-doc-approval-macos.sh +# optional E2E when runtime is up: +bash scripts/dev/test-doc-approval-macos.sh --with-runtime-smoke +``` + +Per-app READMEs under `apps/doc-approval/*/README.md` cover manual GUI runs and runtime URL settings (Android emulator uses `http://10.0.2.2:8787` for host loopback). + +### Run the apps visually (manual testing) + +**1. Start the runtime** (keep this terminal open): + +```bash +cd /tmp/traverse && cargo run -p traverse-cli -- serve +``` + +**2. Launch a client** (pick one per terminal/window): + +```bash +bash scripts/dev/launch-doc-approval.sh web # browser → http://localhost:5173 +bash scripts/dev/launch-doc-approval.sh macos # opens Xcode → press ⌘R +bash scripts/dev/launch-doc-approval.sh ios # opens Xcode + Simulator → press ⌘R +bash scripts/dev/launch-doc-approval.sh android # starts emulator, installs app +bash scripts/dev/launch-doc-approval.sh # show menu +``` + +| App | How you see it | Runtime URL in settings | +|-----|----------------|-------------------------| +| Web | Browser at `http://localhost:5173` | `http://127.0.0.1:8787` (in `.env`) | +| macOS | DocApprovalMac window | `http://127.0.0.1:8787` (⌘,) | +| iOS | iPhone Simulator | `http://127.0.0.1:8787` (Settings) | +| Android | Emulator | `http://10.0.2.2:8787` (Settings) | + +Paste document text → **Analyze** / submit → you should see analysis fields when the runtime is online and the capability is registered. + See [docs/traverse-starter-plan.md](docs/traverse-starter-plan.md) for the full plan and [docs/traverse-runtime.md](docs/traverse-runtime.md) for runtime setup. ## Verify Your Setup @@ -110,6 +167,8 @@ Checks 1–5 validate Node, install, typecheck, lint, and tests (no runtime requ Active blockers on [Project 2](https://github.com/orgs/traverse-framework/projects/2): -- **SSE state subscription** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on [Traverse #525](https://github.com/traverse-framework/Traverse/issues/525), [#526](https://github.com/traverse-framework/Traverse/issues/526), [#527](https://github.com/traverse-framework/Traverse/issues/527). All platform clients inherit this blocker for Phase 2 SSE upgrade. -- **meeting-notes web-react** ([#57](https://github.com/traverse-framework/reference-apps/issues/57)) — second domain app (list-type output); blocked pending runtime capability work. -- **doc-approval shared core** ([#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — extract shared Swift/Rust client packages for iOS/macOS and linux-gtk/cli-rust; Phase 2 work blocked on SSE and crate design. +- **Phase 3 embedded runtime** ([#109](https://github.com/traverse-framework/reference-apps/issues/109)–[#118](https://github.com/traverse-framework/reference-apps/issues/118)) — all platform clients must bundle the WASM runtime host; blocked on [Traverse #553](https://github.com/traverse-framework/Traverse/issues/553). HTTP sidecar is dev-only. +- **Multi-capability showcase workflow** ([#110](https://github.com/traverse-framework/reference-apps/issues/110), [#111](https://github.com/traverse-framework/reference-apps/issues/111)) — traverse-starter and doc-approval pipeline workflows with multiple WASM capabilities. +- **SSE state subscription** ([#43](https://github.com/traverse-framework/reference-apps/issues/43)) — replace polling with runtime SSE; blocked on [Traverse #527](https://github.com/traverse-framework/Traverse/issues/527) only (#525/#526 done). +- **meeting-notes web-react** ([#57](https://github.com/traverse-framework/reference-apps/issues/57)) — second domain app (list-type output); blocked on [Traverse #532](https://github.com/traverse-framework/Traverse/issues/532). +- **Embedded runtime client packages** ([#58](https://github.com/traverse-framework/reference-apps/issues/58), [#59](https://github.com/traverse-framework/reference-apps/issues/59), [#72](https://github.com/traverse-framework/reference-apps/issues/72), [#73](https://github.com/traverse-framework/reference-apps/issues/73)) — shared Swift/Rust host wiring for embedded mode; reprioritized from HTTP client extraction. diff --git a/docs/design-language.md b/docs/design-language.md index d330985..909c5f6 100644 --- a/docs/design-language.md +++ b/docs/design-language.md @@ -10,10 +10,12 @@ Every client presents the same three zones, top to bottom: | Element | Description | |---|---| -| Runtime URL | Text display of the configured base URL | -| Runtime status | `Online` (green) / `Offline` (red) / `Checking` (animated) | +| Runtime mode | `Embedded` (Phase 3) or `Sidecar` (Phase 1/2 dev) | +| Runtime status | `Ready` (green) / `Unavailable` (red) / `Starting` (animated) | | Workspace | Workspace ID (e.g. `local-default`) | -| Capability ID | Capability being invoked (e.g. `traverse-starter.process`) | +| Workflow / capability | Workflow or capability being invoked (e.g. `traverse-starter.pipeline`) | + +Phase 1/2 clients may still show a sidecar URL during dev migration. Phase 3 clients must not expose loopback URL as a required user configuration. ### Zone 2 — Input diff --git a/docs/embedded-runtime-plan.md b/docs/embedded-runtime-plan.md new file mode 100644 index 0000000..37f01b0 --- /dev/null +++ b/docs/embedded-runtime-plan.md @@ -0,0 +1,150 @@ +# Phase 3 — Embedded Runtime Plan + +## Purpose + +App-References must demonstrate the **production-shaped** Traverse integration model: + +1. **Native UI per platform** — each client uses its platform toolkit (SwiftUI, Compose, WinUI, GTK, React). UI renders only; it never computes business fields. +2. **Embedded WASM runtime in every app** — the Traverse host runs **inside** the application process/bundle. No separate `traverse-cli serve` step is required for end users. +3. **Multi-capability showcase workflow** — at least one reference app runs a **single workflow** that chains **multiple WASM capabilities** so developers can see orchestration, not just one-shot execute. + +Phase 1 (HTTP sidecar) and Phase 2 (CLI registration into a sidecar) remain valid **developer/integration** paths until Phase 3 lands. They are **not** the target production architecture. + +## Architecture Boundary (unchanged) + +| Concern | Lives in | +|---|---| +| Native UI shell | This repo — `apps///` | +| Runtime host boundary (FFI / SDK) | Traverse repo — embeddable host per platform | +| WASM agents + workflow definitions | Traverse repo — `examples/` | +| App + component manifests | This repo — `manifests//` | +| Business output fields | Traverse runtime — UI renders, never computes | + +**Constitution still applies:** no business logic in UI, no private Traverse internals imported into UI code, no fake runtime responses in application code. + +## Target Deployment Model + +``` +┌─────────────────────────────────────────────────────────┐ +│ Platform app (shipped binary / web bundle) │ +│ ┌──────────────────┐ ┌──────────────────────────┐ │ +│ │ Native UI │───►│ Embedded Traverse host │ │ +│ │ (Swift/Compose/ │ │ + bundled app manifest │ │ +│ │ WinUI/GTK/React)│◄───│ + WASM agents + workflow │ │ +│ └──────────────────┘ └──────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ + No external HTTP server required at runtime +``` + +### Dev vs production + +| Mode | When | Runtime location | Discovery | +|---|---|---|---| +| **Production (Phase 3 target)** | Shipped apps | Embedded in app bundle | In-process SDK / local workspace path | +| **Dev sidecar (Phase 1/2)** | Local development, CI smoke | `traverse-cli serve` @ 8787 | `.traverse/server.json` or env vars | + +HTTP to `127.0.0.1:8787` is a **dev convenience**, not the long-term client architecture. + +## Multi-Capability Showcase + +**Primary showcase app:** `traverse-starter` + +One workflow (`traverse-starter.pipeline`) chains three capabilities: + +| Step | Capability ID | WASM component | Input (from prior step) | Output (runtime-owned) | +|---|---|---|---|---| +| 1 | `traverse-starter.validate` | validate-agent | `{ note }` | `{ valid, issues[] }` | +| 2 | `traverse-starter.process` | process-agent (existing) | `{ note }` | `{ title, tags, noteType, suggestedNextAction, status }` | +| 3 | `traverse-starter.summarize` | summarize-agent | process output | `{ summary, wordCount }` | + +The UI submits once; the workflow orchestrates steps. The UI renders **final workflow output** and trace events — it does not call capabilities individually unless explicitly designing a stepped UX (future). + +**Secondary showcase app:** `doc-approval` + +Workflow `doc-approval.pipeline` chains: + +| Step | Capability ID | Notes | +|---|---|---| +| 1 | `doc-approval.extract` | Traverse [#538](https://github.com/traverse-framework/Traverse/issues/538) | +| 2 | `doc-approval.analyze` | Existing client capability ID | +| 3 | `doc-approval.recommend` | New capability — approval recommendation | + +Both apps must run the same workflow on all seven platform clients once embedded runtime is available. + +## Platform Matrix (Phase 3 exit criteria) + +Every cell must: embed runtime, bundle manifests + WASM at build time, execute multi-capability workflow end-to-end, render output without local business logic. + +| Platform | traverse-starter | doc-approval | +|---|---|---| +| web-react | Required | Required | +| ios-swift | Required | Required | +| macos-swift | Required | Required | +| android-compose | Required | Required | +| windows-winui | Required | Required | +| linux-gtk | Required | Required | +| cli-rust | Required | Required | + +`trace-explorer` may remain HTTP-attached for debugging until an embedded trace API exists; it is not in the Phase 3 matrix. + +## Shared Client Layers + +Platform-specific **UI** stays separate. Repeated **runtime host wiring** should consolidate: + +| Package | Platforms | Issue | +|---|---|---| +| `TraverseCore` (Swift) | iOS + macOS | [#58](https://github.com/traverse-framework/reference-apps/issues/58), [#72](https://github.com/traverse-framework/reference-apps/issues/72) | +| `traverse-core-rs` (Rust) | linux-gtk + cli-rust | [#59](https://github.com/traverse-framework/reference-apps/issues/59), [#73](https://github.com/traverse-framework/reference-apps/issues/73) | + +Phase 3 shared packages wrap the **public embedded runtime SDK** — not raw HTTP clients. HTTP client code from Phase 1 is retired from production paths after migration. + +## Traverse Framework Dependencies (blocking) + +Phase 3 is blocked until Traverse ships: + +1. **Spec 057 embeddable runtime host** ([Traverse spec 057](https://github.com/traverse-framework/Traverse/blob/main/specs/057-embeddable-runtime-host/spec.md), issue [#557](https://github.com/traverse-framework/Traverse/issues/557)) — WASM runtime in every app; WASI wasm caps (~90%); compatible-mode native caps; uniform thin embedder API +2. **Embeddable runtime host SDK** ([Traverse #553](https://github.com/traverse-framework/Traverse/issues/553)) — implementation of spec 057 +3. **Spec 058 pipeline execution** ([Traverse spec 058](https://github.com/traverse-framework/Traverse/blob/main/specs/058-workflow-pipeline-execution/spec.md)) — multi-capability workflows +4. **Additional WASM agents** — [#554](https://github.com/traverse-framework/Traverse/issues/554), [#538](https://github.com/traverse-framework/Traverse/issues/538), [#555](https://github.com/traverse-framework/Traverse/issues/555), [#556](https://github.com/traverse-framework/Traverse/issues/556) +5. **Registry spec 008** — reference capability publication ([registry spec 008](https://github.com/traverse-framework/registry/blob/main/specs/008-reference-capability-publication/spec.md)) + +Until (1–2) exist, platform migration tickets stay **Blocked**. + +## Phase History + +| Phase | Status | Model | +|---|---|---| +| Phase 1 | ✅ Shipped | HTTP sidecar, single capability execute + poll | +| Phase 2 | ✅ Shipped | CLI validate/register into sidecar workspace | +| **Phase 3** | 🎯 Target | Embedded runtime + multi-capability workflow on all platforms | + +## Ticket Index (Phase 3) + +| # | Title | Status | +|---|---|---| +| [109](https://github.com/traverse-framework/reference-apps/issues/109) | Land embedded runtime architecture spec | Ready | +| [Traverse #557](https://github.com/traverse-framework/Traverse/issues/557) | Spec **057** approved — embeddable runtime host | Done (spec merged) | +| [Traverse #553](https://github.com/traverse-framework/Traverse/issues/553) | Implement spec 057 SDK | Blocked → Ready after 057 PR | +| [Traverse #558](https://github.com/traverse-framework/Traverse/issues/558) | Implement spec 058 pipeline | Ready | +| [Traverse #527](https://github.com/traverse-framework/Traverse/issues/527) | Implement spec 059 command dispatch | Blocked | +| [110](https://github.com/traverse-framework/reference-apps/issues/110) | traverse-starter.pipeline multi-capability workflow | Blocked | +| [111](https://github.com/traverse-framework/reference-apps/issues/111) | doc-approval.pipeline multi-capability workflow | Blocked | +| [112](https://github.com/traverse-framework/reference-apps/issues/112) | doc-approval manifests | Blocked | +| [113](https://github.com/traverse-framework/reference-apps/issues/113) | Embed runtime — web-react | Blocked | +| [114](https://github.com/traverse-framework/reference-apps/issues/114) | Embed runtime — Swift (iOS + macOS) | Blocked | +| [115](https://github.com/traverse-framework/reference-apps/issues/115) | Embed runtime — Android | Blocked | +| [116](https://github.com/traverse-framework/reference-apps/issues/116) | Embed runtime — Windows | Blocked | +| [117](https://github.com/traverse-framework/reference-apps/issues/117) | Embed runtime — Linux + CLI | Blocked | +| [118](https://github.com/traverse-framework/reference-apps/issues/118) | embedded_smoke.sh CI gate | Future | +| [58](https://github.com/traverse-framework/reference-apps/issues/58), [72](https://github.com/traverse-framework/reference-apps/issues/72) | Shared Swift embedded host package | Blocked | +| [59](https://github.com/traverse-framework/reference-apps/issues/59), [73](https://github.com/traverse-framework/reference-apps/issues/73) | Shared Rust embedded host package | Blocked | + +## Validation (Phase 3 complete) + +When Phase 3 is done: + +1. Install/build any platform client **without** starting `traverse-cli serve` +2. Submit input → multi-capability workflow runs → all output fields render +3. `bash scripts/ci/embedded_smoke.sh` passes (to be added) on CI agents with embedded host support +4. No business field computation in UI diff review +5. Manifests in `manifests/` reference WASM digests bundled in app artifacts diff --git a/docs/quality-standards.md b/docs/quality-standards.md index 9c99022..7050d05 100644 --- a/docs/quality-standards.md +++ b/docs/quality-standards.md @@ -53,9 +53,13 @@ The coverage gate is merge-safe before non-trivial logic exists — it passes wh ## Native Platform Clients -Native traverse-starter clients follow the same UI-only architecture boundary as web: they render, sort, filter, and display runtime-provided data. They must not compute business fields (title, tags, note type, next action, status) or import private Traverse internals. +Native clients follow the UI-only boundary: **native UI separated from business logic**. Business fields come from the embedded Traverse host (Phase 3) or dev HTTP sidecar (Phase 1/2 interim). -**Runtime boundary**: use only the public Traverse HTTP/JSON API ([spec 033](https://github.com/traverse-framework/Traverse/blob/main/docs/specs/033-http-json-api.md)). Phase 1 clients poll execution status; SSE upgrades are tracked separately in `AGENTS.md`. +**Runtime boundary (interim):** public HTTP/JSON API ([spec 033](https://github.com/traverse-framework/Traverse/blob/main/docs/specs/033-http-json-api.md)) for dev sidecar only. + +**Runtime boundary (target):** public embedded host SDK from Traverse — in-process execute, event subscription, bundled manifests + WASM. No `127.0.0.1:8787` in production builds. + +See [`docs/embedded-runtime-plan.md`](embedded-runtime-plan.md) for the Phase 3 platform matrix. **IA parity**: native shells must match the traverse-starter information architecture documented in [`docs/design-language.md`](design-language.md). diff --git a/docs/traverse-runtime.md b/docs/traverse-runtime.md index 1444a53..48e543f 100644 --- a/docs/traverse-runtime.md +++ b/docs/traverse-runtime.md @@ -1,6 +1,15 @@ # Traverse Runtime Setup -This document is the canonical local setup reference for all apps in this repo. +This document covers **how to run the Traverse runtime for local development**. For the **production target** (embedded in-app host), see [`embedded-runtime-plan.md`](embedded-runtime-plan.md). + +## Deployment Models + +| Model | Status | Use when | +|---|---|---| +| **Embedded in-app host (Phase 3)** | Target — not yet in platform clients | Building/shipping reference apps to end users | +| **HTTP sidecar `traverse-cli serve` (Phase 1/2)** | Current dev path | Local development, CI smoke tests, trace-explorer | + +End-user apps **must not** depend on a separately running sidecar. The sidecar exists so developers can iterate before the embeddable host SDK ships in Traverse. ## Pinned Version @@ -8,12 +17,13 @@ This document is the canonical local setup reference for all apps in this repo. |---|---|---| | Phase 1 (HTTP integration) | **v0.3.0** | HTTP/JSON API, `/healthz`, execute, poll, trace | | Phase 2 (CLI app registration) | **v0.5.0** | `traverse-cli app validate/register`, workspace state | +| Phase 3 (embedded host) | **TBD** | In-app WASM runtime host SDK per platform | -**Current release: v0.6.0** — recommended checkout for all phases (backward-compatible with Phase 1 and Phase 2 minimums). +**Current release: v0.6.0** — recommended for Phase 1/2 dev sidecar. Requirements: Rust 1.94+ -## Start the Runtime +## Dev Sidecar — Start the Runtime ```bash git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse @@ -34,7 +44,7 @@ cat .traverse/server.json # } ``` -## API Surface +## HTTP API Surface (dev sidecar only) Governed by `033-http-json-api` (approved v1.1.0). @@ -48,7 +58,9 @@ Governed by `033-http-json-api` (approved v1.1.0). Default workspace: `local-default` -## Discovery in App Code +Phase 3 embedded clients use the **public host SDK** instead of these HTTP endpoints for in-process execution. + +## Discovery in App Code (Phase 1/2 — dev only) ```typescript import fs from 'fs' @@ -58,53 +70,54 @@ const baseUrl = server.base_url // http://127.0.0.1:8787 const workspaceId = server.workspace_default // local-default ``` -In the browser (Vite dev server proxies to runtime): +In the browser (Vite env vars): + ```typescript const baseUrl = import.meta.env.VITE_TRAVERSE_BASE_URL ?? 'http://127.0.0.1:8787' const workspaceId = import.meta.env.VITE_TRAVERSE_WORKSPACE ?? 'local-default' ``` -## App Registration (Phase 2) +Phase 3 clients load bundled manifests from the app artifact and initialize an in-process workspace — no URL discovery. + +## App Registration (Phase 2 — dev sidecar) Governed by `044-application-bundle-manifest` and `046-public-cli-app-registration` (both approved). ```bash -# Validate app manifest traverse-cli app validate --manifest manifests//app.manifest.json --json -# Register app into workspace traverse-cli app register \ --manifest manifests//app.manifest.json \ --workspace local-default \ --json ``` -## Local Development Override +Phase 3 production builds embed manifests + WASM at **build time**; registration into a sidecar workspace is not the shipping path. -For active Traverse framework development, point at a local checkout instead of a tagged release: +## Local Development Override ```bash export TRAVERSE_REPO=/path/to/Traverse cd $TRAVERSE_REPO && cargo run -p traverse-cli -- serve ``` -Do not commit `TRAVERSE_REPO` references into app code. This is a local developer override only. +Do not commit `TRAVERSE_REPO` references into app code. ## CI Environment -For CI environments without a local runtime, set: - ```bash TRAVERSE_RUNTIME_URL=http://: TRAVERSE_WORKSPACE_ID=local-default ``` -The `scripts/ci/phase1_smoke.sh` reads these env vars when `.traverse/server.json` is not present. +`scripts/ci/phase1_smoke.sh` reads these when `.traverse/server.json` is absent. -Phase 2 validation and registration require a Traverse checkout: +Phase 2: ```bash -export TRAVERSE_REPO=/path/to/Traverse # main branch with traverse-starter example -bash scripts/ci/phase2_link_traverse.sh # symlink WASM/contracts into manifests/ -bash scripts/ci/phase2_smoke.sh # validate → register → HTTP execute +export TRAVERSE_REPO=/path/to/Traverse +bash scripts/ci/phase2_link_traverse.sh +bash scripts/ci/phase2_smoke.sh ``` + +Phase 3 will add `scripts/ci/embedded_smoke.sh` when the embeddable host is available. diff --git a/docs/traverse-starter-plan.md b/docs/traverse-starter-plan.md index 381fd6e..888a9be 100644 --- a/docs/traverse-starter-plan.md +++ b/docs/traverse-starter-plan.md @@ -4,8 +4,9 @@ `traverse-starter` is the minimal Traverse reference UI app. It demonstrates the full app-consumable path for downstream developers: -- **Phase 1**: UI → HTTP execute → poll → render runtime-provided structured output -- **Phase 2**: app manifest → `traverse-cli app validate` → `traverse-cli app register` → runtime loads registered capability → UI invokes it end-to-end +- **Phase 1**: UI → HTTP execute → poll → render runtime-provided structured output (dev sidecar) +- **Phase 2**: app manifest → `traverse-cli app validate` → `traverse-cli app register` → sidecar loads capability → UI invokes it end-to-end +- **Phase 3**: native UI → **embedded in-app WASM runtime** → multi-capability workflow → render runtime-provided output (production target — see [`embedded-runtime-plan.md`](embedded-runtime-plan.md)) ## Architecture Boundary @@ -18,7 +19,7 @@ | App manifest + component manifests | This repo — `manifests/traverse-starter/` | | Capability contract + WASM agent | Traverse repo — `examples/traverse-starter/` | | Business output fields (title, tags, etc.) | Traverse runtime — UI renders, never computes | -| Traverse CLI/runtime binary | External — pinned (see below) | +| Traverse CLI/runtime binary | External for dev sidecar; **embedded host in shipped apps (Phase 3)** | ## Runtime Pin @@ -113,12 +114,24 @@ bash scripts/ci/phase2_smoke.sh | 24 | Author traverse-starter app manifest | ✅ Ready (Traverse #499 merged) | | 6 | Phase 2 app registration | ✅ Ready (Traverse #499, #500 merged) | +## Phase 3 — Embedded Runtime + Multi-Capability Workflow + +**Status: target — blocked on Traverse embeddable host SDK** + +See [`embedded-runtime-plan.md`](embedded-runtime-plan.md) for the full matrix and ticket index. + +**Showcase workflow:** `traverse-starter.pipeline` chains `validate` → `process` → `summarize`. + +**Exit criteria:** all seven platform clients run the pipeline with embedded runtime; no sidecar required. + ## Accepted Decisions - UI renders runtime-provided fields only — no local business logic -- No private Traverse internals imported -- No HTTP app registration endpoint — setup uses CLI only -- No service registry — discovery via `.traverse/server.json` +- No private Traverse internals imported into UI code +- No HTTP app registration endpoint — Phase 2 setup uses CLI only +- Phase 1 HTTP sidecar + `.traverse/server.json` is **dev-only**, not production +- Shipped apps embed Traverse host + bundled WASM (Phase 3) - No fake runtime responses in application code - Phase 1 does not require live AI/model access — runtime determinism is guaranteed - `TRAVERSE_REPO` env override is for active framework development only +- At least one multi-capability workflow demonstrates orchestration across WASM agents From ce4dac66f985951321294b72eeae0f1d09f2d0e0 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Mon, 6 Jul 2026 16:46:50 -0600 Subject: [PATCH 2/2] ci: retrigger checks Co-authored-by: Cursor