diff --git a/docs/traverse-runtime.md b/docs/traverse-runtime.md index fec84e4..305c654 100644 --- a/docs/traverse-runtime.md +++ b/docs/traverse-runtime.md @@ -4,7 +4,10 @@ This document is the canonical local setup reference for all apps in this repo. ## Pinned Version -**Traverse v0.3.0** — source build required. +| Phase | Minimum version | Adds | +|---|---|---| +| 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 | Requirements: Rust 1.94+ @@ -13,7 +16,7 @@ Requirements: Rust 1.94+ ```bash git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse cd /tmp/traverse -git checkout v0.3.0 +git checkout v0.5.0 # minimum for Phase 2; use v0.3.0 for Phase 1 only cargo run -p traverse-cli -- serve ``` diff --git a/docs/traverse-starter-plan.md b/docs/traverse-starter-plan.md index d04a333..f4d4358 100644 --- a/docs/traverse-starter-plan.md +++ b/docs/traverse-starter-plan.md @@ -1,17 +1,11 @@ -# App-References Plan +# traverse-starter Plan ## Purpose -This repo holds reference UI applications that demonstrate integrating a React frontend with the Traverse runtime. Each app is a thin UI layer — it starts workflows, receives events, and renders runtime-provided structured output without owning any business logic. +`traverse-starter` is the minimal Traverse reference UI app. It demonstrates the full app-consumable path for downstream developers: -## Apps In This Repo - -| App | Path | Status | -|---|---|---| -| `traverse-starter` | `apps/traverse-starter/web-react` | Phase 1 in progress | -| `youaskm3` | `apps/youaskm3/web-react` | Planned | - ---- +- **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 ## Architecture Boundary @@ -19,226 +13,102 @@ This repo holds reference UI applications that demonstrate integrating a React f | Concern | Lives in | |---|---| -| React UI shells | This repo | -| Runtime event client (thin boundary only) | This repo | -| App manifests and WASM component manifests | This repo (`manifests//`) | -| Business capabilities and workflow execution | Traverse runtime (external) | -| Business output fields (tags, title, note type, etc.) | Traverse runtime (external) | -| Traverse CLI/runtime binary | External — pinned to `v0.3.0` | +| React UI shell | This repo — `apps/traverse-starter/web-react` | +| HTTP client boundary (spec 033) | This repo | +| 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) | -The React UI must not compute business fields. It renders, sorts, filters, and displays data provided by the runtime. +## Runtime Pin -## Accepted Decisions +| Phase | Minimum Traverse version | +|---|---| +| Phase 1 (HTTP integration) | v0.3.0 | +| Phase 2 (CLI app registration) | v0.5.0 | -- Phase 1 does not require live AI/model access — runtime determinism is guaranteed -- No private Traverse internals are imported into this repo -- No HTTP app registration endpoint — setup uses `traverse-cli app validate` + `traverse-cli app register` -- No service registry — discovery via `.traverse/server.json` -- No fake business logic or fake registration in the UI -- Canonical consumer path pins `v0.3.0` of the Traverse source build -- `TRAVERSE_REPO=/path/to/Traverse` env override is supported for active framework development only +Start the runtime: -## Traverse Runtime API (Resolved) +```bash +git clone https://github.com/traverse-framework/Traverse.git /tmp/traverse +cd /tmp/traverse && git checkout +cargo run -p traverse-cli -- serve +# Writes .traverse/server.json +``` -The public integration surface is governed by spec `033-http-json-api` (approved, v1.1.0). +Override for active Traverse development: -| Detail | Value | -|---|---| -| Start runtime | `cargo run -p traverse-cli -- serve` | -| Default address | `127.0.0.1:8787` | -| Discovery file | `.traverse/server.json` | -| Default workspace | `local-default` | -| Health check | `GET /healthz` | -| Execute capability | `POST /v1/workspaces/{workspace_id}/execute` | -| Poll execution | `GET /v1/workspaces/{workspace_id}/executions/{execution_id}` | -| Fetch trace | `GET /v1/workspaces/{workspace_id}/traces/{execution_id}` | -| Error format | RFC 9457 Problem Details | -| App validate | `traverse-cli app validate --manifest --json` | -| App register | `traverse-cli app register --manifest --workspace --json` | - -Discovery sequence: ```bash -BASE_URL="$(jq -r '.base_url' .traverse/server.json)" -WORKSPACE_ID="$(jq -r '.workspace_default' .traverse/server.json)" +TRAVERSE_REPO=/path/to/Traverse +cd $TRAVERSE_REPO && cargo run -p traverse-cli -- serve ``` -## Governing Specs (in Traverse repo) +## API Surface (spec 033-http-json-api, approved v1.1.0) -| Spec | Status | Governs | +| Endpoint | Method | Purpose | |---|---|---| -| `033-http-json-api` | ✅ Approved v1.1.0 | HTTP+JSON runtime API, execute, trace, discovery | -| `044-application-bundle-manifest` | ✅ Approved | App manifest, WASM component manifests, validation | -| `046-public-cli-app-registration` | ✅ Approved | `traverse-cli app validate` + `app register` | -| `013-browser-runtime-subscription` | ⚠️ Draft | Browser event subscription contract | -| `019-local-browser-adapter-transport` | ⚠️ Draft | Local browser adapter transport | - -Phase 1 is governed by spec `033`. Phase 2 is governed by specs `044` and `046` — both are approved. - ---- - -## traverse-starter - -### Purpose +| `/healthz` | GET | Health check | +| `/v1/workspaces/{workspace_id}/execute` | POST | Execute a capability | +| `/v1/workspaces/{workspace_id}/executions/{execution_id}` | GET | Poll execution status | +| `/v1/workspaces/{workspace_id}/traces/{execution_id}` | GET | Fetch public trace | -The simplest possible Traverse reference app. User enters a short note → Traverse processes it → UI renders runtime-provided structured output. +Discovery: `.traverse/server.json` → `base_url`, `workspace_default` -### Phase 1 — HTTP Integration +In the browser (env vars): -**Governing spec**: `033-http-json-api` - -**Deliverables:** - -1. **UI shell** — `apps/traverse-starter/web-react` - - React 18 + TypeScript + Vite + Vitest + ESLint - - Node version pinned in `.nvmrc` - - Configured for local Traverse runtime discovery via `.traverse/server.json` - -2. **Runtime HTTP client** - - Reads `.traverse/server.json` for `base_url` and `workspace_default` - - `POST /v1/workspaces/{workspace_id}/execute` to start capability - - `GET /v1/workspaces/{workspace_id}/executions/{execution_id}` to poll - - UI state: loading → polling → complete / error - - No private Traverse internals imported - -3. **Deterministic UI flow** - - User enters a short note input - - UI sends to Traverse runtime via HTTP execute - - UI renders runtime-provided: `title`, `tags`, `noteType`, `suggestedNextAction`, `status` - - UI computes none of these fields - -4. **Phase 1 smoke test** - - Connects to local Traverse runtime at `127.0.0.1:8787` - - POSTs execute request with fixture input - - Polls for completion - - Asserts required output fields present and non-empty - -### Phase 2 — App Registration - -**Governing specs**: `044-application-bundle-manifest`, `046-public-cli-app-registration` - -**Deliverables:** - -1. App manifest at `manifests/traverse-starter/app.manifest.json` -2. WASM component manifest(s) in `manifests/traverse-starter/components/` -3. CLI validation + registration in setup script -4. Runtime loads registered workspace state -5. Phase 2 smoke test proves end-to-end path - ---- - -## youaskm3 - -### Purpose +``` +VITE_TRAVERSE_BASE_URL=http://127.0.0.1:8787 +VITE_TRAVERSE_WORKSPACE=local-default +``` -The primary downstream reference app. A browser-hosted knowledge workflow app that uses Traverse for runtime execution, workflow state progression, trace generation, and MCP-facing behavior. Demonstrates the full app-consumable path including app bundle registration. +## Phase 1 — HTTP Integration -### Phase 1 — HTTP Integration +**Status: complete** -**Governing spec**: `033-http-json-api` +**Deliverables (all merged):** -Same HTTP integration pattern as traverse-starter, applied to a knowledge Q&A workflow. +1. **UI shell** — `apps/traverse-starter/web-react` (issue #2) +2. **Runtime HTTP client** — `src/client/traverseClient.ts` + `src/hooks/useExecution.ts` (issue #3) +3. **Deterministic UI flow** — renders `title`, `tags`, `noteType`, `suggestedNextAction`, `status` from runtime output; computes none locally (issue #4) +4. **Phase 1 smoke test** — `scripts/ci/phase1_smoke.sh` (issue #5); set `TRAVERSE_RUNTIME_URL` to activate -**Deliverables:** +**Capability invoked:** `traverse-starter.process` +**Input:** `{ "note": string }` +**Output (runtime-owned):** `{ "title", "tags", "noteType", "suggestedNextAction", "status" }` -1. **UI shell** — `apps/youaskm3/web-react` -2. **Runtime HTTP client** — same boundary as traverse-starter -3. **Knowledge workflow UI** - - User submits a question or knowledge item - - UI sends to Traverse via HTTP execute - - UI renders runtime-provided output: answer, sources, reasoning trace, status -4. **Phase 1 smoke test** +## Phase 2 — App Registration -### Phase 2 — App Registration +**Status: blocked — waiting on Traverse #499** -**Governing specs**: `044-application-bundle-manifest`, `046-public-cli-app-registration` +**Governing specs:** `044-application-bundle-manifest`, `046-public-cli-app-registration` **Deliverables:** -1. App manifest at `manifests/youaskm3/app.manifest.json` -2. WASM component manifests in `manifests/youaskm3/components/` -3. `traverse-cli app validate --manifest manifests/youaskm3/app.manifest.json --json` -4. `traverse-cli app register --manifest manifests/youaskm3/app.manifest.json --workspace local-default --json` -5. Runtime loads registered app → UI invokes registered workflow -6. Phase 2 smoke test proves end-to-end path - ---- - -## Traverse Dependency Model - -```bash -# Default: Traverse v0.3.0 source build -git clone https://github.com/traverse-framework/Traverse.git -cd Traverse && git checkout v0.3.0 -cargo run -p traverse-cli -- serve - -# Override for active framework development -TRAVERSE_REPO=/path/to/Traverse -``` - -Requirements: Rust 1.94+, local source checkout of Traverse `v0.3.0`. - -Do not assume the Traverse repo is present unless confirmed. The canonical path is a pinned v0.3.0 source build. - -## Proposed Smoke Tests - -### Phase 1 (traverse-starter and youaskm3) - -``` -1. cargo run -p traverse-cli -- serve (in Traverse v0.3.0) -2. Confirm .traverse/server.json written -3. POST /v1/workspaces/local-default/execute with fixture input -4. Poll GET /v1/workspaces/local-default/executions/{id} until completed -5. Assert output fields present and non-empty -6. Assert no business field computed in UI -``` - -### Phase 2 (youaskm3) - -``` -1. traverse-cli app validate --manifest manifests/youaskm3/app.manifest.json --json → exit 0 -2. traverse-cli app register --manifest manifests/youaskm3/app.manifest.json --workspace local-default --json → exit 0 -3. cargo run -p traverse-cli -- serve -4. Confirm registered workflow is discoverable -5. Execute workflow via HTTP API -6. Assert output matches registered app behavior -``` +1. App manifest at `manifests/traverse-starter/app.manifest.json` (issue #24 — draft present, binary digest pending Traverse #499) +2. `traverse-cli app validate --manifest manifests/traverse-starter/app.manifest.json --json` → exit 0 +3. `traverse-cli app register --manifest manifests/traverse-starter/app.manifest.json --workspace local-default --json` +4. Phase 2 smoke test (issue #6) -## Open Questions (updated) - -| # | Question | Status | -|---|---|---| -| 1 | What is the pinned Traverse CLI version? | ✅ Resolved — `v0.3.0` source build | -| 2 | What does the runtime event client interface look like? | ✅ Resolved — HTTP+JSON, spec `033` | -| 3 | What is the local runtime discovery mechanism? | ✅ Resolved — `.traverse/server.json`, port `8787`, workspace `local-default` | -| 4 | What fields does the runtime guarantee in final output? | ⚠️ Pending — depends on registered capability contract | -| 5 | Is there an existing app manifest schema? | ✅ Resolved — spec `044` is approved | -| 6 | Does Phase 2 CLI registration exist in any released build? | ✅ Resolved — spec `046` is approved; verify implementation in v0.3.0 | +**Unblocked by:** Traverse [#499](https://github.com/traverse-framework/Traverse/issues/499) (capability contract + WASM agent) and [#500](https://github.com/traverse-framework/Traverse/issues/500) (v0.5.0 pin confirmation) ## Ticket Index -### traverse-starter - | # | Title | Status | |---|---|---| -| 1 | Define traverse-starter UI-only reference app plan | Done | -| 7 | Enable branch protection on main | Ready | -| 8 | Track project governance and CI setup | Done | -| 9 | Pin Traverse runtime to v0.3.0 and document local discovery | Ready | -| 2 | Scaffold web React UI shell for traverse-starter | Ready | -| 3 | Add runtime event client boundary for web React | Ready | -| 4 | Add deterministic traverse-starter UI flow | Ready | -| 5 | Add Phase 1 smoke test | Ready | -| 6 | Track Phase 2 app registration integration | Ready (unblocked — spec 046 approved) | - -### youaskm3 +| 1 | Define traverse-starter plan | ✅ Done | +| 2 | Scaffold web React UI shell | ✅ Done | +| 3 | Add runtime event client boundary | ✅ Done | +| 4 | Add deterministic UI flow | ✅ Done | +| 5 | Add Phase 1 smoke test | ✅ Done | +| 24 | Author traverse-starter app manifest | 🔴 Blocked (Traverse #499) | +| 6 | Phase 2 app registration | 🔴 Blocked (Traverse #499, #500) | -| # | Title | Status | -|---|---|---| -| 10 | Define youaskm3 reference app plan and scope | Ready | -| 11 | Scaffold youaskm3 web React UI shell | Ready | -| 12 | Author youaskm3 app manifest and WASM component manifests | Ready | -| 13 | Add youaskm3 runtime HTTP client | Ready | -| 14 | Implement youaskm3 knowledge workflow UI | Ready | -| 15 | Add youaskm3 Phase 1 smoke test | Ready | -| 16 | Implement youaskm3 CLI app validation and registration (Phase 2) | Ready | -| 17 | Add youaskm3 Phase 2 smoke test | Ready | +## 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 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 diff --git a/manifests/traverse-starter/app.manifest.json b/manifests/traverse-starter/app.manifest.json new file mode 100644 index 0000000..995f2eb --- /dev/null +++ b/manifests/traverse-starter/app.manifest.json @@ -0,0 +1,29 @@ +{ + "kind": "app_manifest", + "schema_version": "1.0.0", + "app_id": "traverse-starter", + "version": "0.1.0", + "summary": "Minimal Traverse reference app demonstrating the Phase 1 HTTP integration and Phase 2 CLI registration path.", + "capabilities": [ + { + "id": "traverse-starter.process", + "version": "1.0.0", + "contract_path": "contracts/examples/traverse-starter/capabilities/process/contract.json" + } + ], + "workflows": [ + { + "workflow_id": "traverse-starter.process", + "workflow_version": "1.0.0" + } + ], + "components": [ + { + "ref": "./components/process-agent.manifest.json" + } + ], + "registration": { + "workspace": "local-default", + "discovery": ".traverse/server.json" + } +} diff --git a/manifests/traverse-starter/components/process-agent.manifest.json b/manifests/traverse-starter/components/process-agent.manifest.json new file mode 100644 index 0000000..8967477 --- /dev/null +++ b/manifests/traverse-starter/components/process-agent.manifest.json @@ -0,0 +1,35 @@ +{ + "kind": "agent_package", + "schema_version": "1.0.0", + "package_id": "traverse-starter.process-agent", + "version": "1.0.0", + "summary": "Deterministic note-processing agent for the traverse-starter reference app.", + "capability_ref": { + "id": "traverse-starter.process", + "version": "1.0.0", + "contract_path": "contracts/examples/traverse-starter/capabilities/process/contract.json" + }, + "workflow_refs": [ + { + "workflow_id": "traverse-starter.process", + "workflow_version": "1.0.0" + } + ], + "source": { + "path": "examples/traverse-starter/process-agent/src/agent.rs", + "language": "rust", + "entry": "run" + }, + "binary": { + "path": "examples/traverse-starter/process-agent/artifacts/process-agent.wasm", + "format": "wasm", + "expected_digest": "PENDING — set after Traverse #499 ships the compiled artifact", + "abi_version": "1.0.0" + }, + "constraints": { + "host_api_access": "none", + "network_access": "forbidden", + "filesystem_access": "none" + }, + "model_dependencies": [] +}