traverse-framework · enricopiovesan · Jul 15, 2026 · Jul 15, 2026
@@ -18,4 +18,4 @@ Expected local run path on a machine with full Xcode:
 - run the `TraverseMacOSDemoApp` target
 
 Fixture source:
-- `apps/demo-fixtures/expedition-runtime-session.json`
+- `examples/fixtures/expedition-runtime-session.json`
@@ -95,7 +95,7 @@ struct DemoOutput: Decodable {
 
 enum DemoSessionRepository {
     static func sample() -> DemoSession {
-        let url = URL(fileURLWithPath: "apps/demo-fixtures/expedition-runtime-session.json")
+        let url = URL(fileURLWithPath: "examples/fixtures/expedition-runtime-session.json")
         let data = (try? Data(contentsOf: url)) ?? Data()
         let decoder = JSONDecoder()
 

@@ -468,3 +468,35 @@ Keep the initial durable journal while #629 measures append latency, recovery,
 replay, retention compaction, and disk growth under representative workloads.
 Choose retain, SQLite, or a provider abstraction only from that evidence; no
 storage migration or abstraction is preselected.
+
+## Decision 22: Keep Application Source Out of the Traverse Runtime Repository
+
+- **Date**: 2026-07-15
+- **Status**: Accepted
+- **Related issues**: `#703`, `#704`; App References `#151`
+
+### Decision
+
+Checked-in application UI, platform client demos, and starter/reference source
+belong in `traverse-framework/reference-apps`. Traverse owns only runtime
+conformance inputs: manifests, fixture agents, and deterministic test fixtures.
+Those artifacts live under `examples/`, never `apps/`.
+
+### Migration inventory
+
+| Current path | Owner | Destination |
+| --- | --- | --- |
+| `apps/android-demo/` | Reference Apps | `reference-apps/android-demo/` |
+| `apps/browser-consumer/` | Reference Apps | `reference-apps/browser-consumer/` |
+| `apps/macos-demo/` | Reference Apps | `reference-apps/macos-demo/` |
+| `apps/react-demo/` | Reference Apps | `reference-apps/react-demo/` |
+| `apps/youaskm3-starter-kit/` | Reference Apps | `reference-apps/youaskm3-starter-kit/` |
+| `apps/demo-fixtures/expedition-runtime-session.json` | Traverse fixture | `examples/fixtures/expedition-runtime-session.json` |
+| `apps/meeting-notes/app.manifest.json` | Traverse fixture | `examples/applications/meeting-notes/app.manifest.json` |
+| `apps/traverse-starter/app.manifest.json` | Traverse fixture | `examples/applications/traverse-starter/app.manifest.json` |
+
+### Outcome
+
+The Reference Apps migration preserves app validation against public Traverse
+surfaces. Traverse follows with removal of the now-obsolete `apps/` directory
+and a repository check that prevents application source from returning.
@@ -55,7 +55,7 @@ These stay in checked-in source locations:
 - contracts: `contracts/`
 - workflows: `workflows/`
 - registry bundles and runtime requests: `examples/`
-- shared checked-in demo fixtures: `apps/demo-fixtures/`
+- shared checked-in demo fixtures: `examples/fixtures/`
 
 Executable capability packages may keep deterministic build outputs in package-local `./artifacts/` directories when those artifacts are part of the checked-in package shape. The local runtime home is for runtime-owned copies, caches, and overlays, not for replacing package-local layout.
 

@@ -9,7 +9,7 @@ Consumers that only need public app validation and registration can remain pinne
 ## Highlights
 
 - Adds the `traverse-starter.process` capability contract with deterministic `title`, `tags`, `noteType`, `suggestedNextAction`, and `status` output fields.
-- Adds the `apps/traverse-starter/app.manifest.json` application manifest and the `examples/traverse-starter/process-agent/` WASM agent package.
+- Adds the `examples/applications/traverse-starter/app.manifest.json` application manifest and the `examples/traverse-starter/process-agent/` WASM agent package.
 - Loads durable CLI-produced workspace app registration state during HTTP workspace execution so registered app capabilities can execute through `/v1/workspaces/local-default/execute`.
 - Adds `bash scripts/ci/traverse_starter_example_smoke.sh` to validate app registration and local HTTP execution end to end.
 - Documents the App-References integration path and confirms `v0.5.0 minimum` for downstream apps using `traverse-cli app validate/register`.

@@ -13,7 +13,7 @@ a sidecar").
    (`/pkg/`), the existing React UMD vendor bundles already checked in under
    `apps/react-demo/vendor` (`/vendor/`), and the repository root itself
    (`/repo/`) so the browser can `fetch` the real
-   `apps/traverse-starter/app.manifest.json` bundle and every file it
+   `examples/applications/traverse-starter/app.manifest.json` bundle and every file it
    references (component manifest, workflow definition, compiled WASM
    artifact) by the same relative paths the bundle already declares.
 2. `src/main.js` is a small React app (no build step, `React.createElement`

@@ -2,7 +2,7 @@ import { BundleEmbedder, FetchBundleLoader } from "/pkg/index.js";
 
 const { createElement: h, useEffect, useState } = React;
 
-const MANIFEST_PATH = "/repo/apps/traverse-starter/app.manifest.json";
+const MANIFEST_PATH = "/repo/examples/applications/traverse-starter/app.manifest.json";
 const CAPABILITY_ID = "traverse-starter.process";
 
 function eventList(events) {

@@ -389,7 +389,7 @@ test("release evidence records the linked runtime and bundled wasm digests", asy
 
 test("real checked-in traverse-starter bundle loads and executes without a sidecar", async () => {
   const manifestPath = new URL(
-    "../../../../apps/traverse-starter/app.manifest.json",
+    "../../../../examples/applications/traverse-starter/app.manifest.json",
     import.meta.url,
   ).pathname;
   const embedder = await initEmbedder(manifestPath);

@@ -112,11 +112,11 @@ from the Traverse repository root:
 
 ```bash
 cargo run -p traverse-cli -- app validate \
-  --manifest apps/traverse-starter/app.manifest.json \
+  --manifest examples/applications/traverse-starter/app.manifest.json \
   --json
 
 cargo run -p traverse-cli -- app register \
-  --manifest apps/traverse-starter/app.manifest.json \
+  --manifest examples/applications/traverse-starter/app.manifest.json \
   --workspace local-default \
   --json
 ```

@@ -34,7 +34,7 @@ cargo test -q -p traverse-registry --test application_manifest \
 
 validation_json="$(
   cargo run -q -p traverse-cli -- app validate \
-    --manifest apps/traverse-starter/app.manifest.json \
+    --manifest examples/applications/traverse-starter/app.manifest.json \
     --json
 )"
 

@@ -4,7 +4,7 @@ set -euo pipefail
 repo_root="${TRAVERSE_REPO_ROOT:-$(pwd)}"
 
 required_files=(
-  "apps/demo-fixtures/expedition-runtime-session.json"
+  "examples/fixtures/expedition-runtime-session.json"
   "apps/macos-demo/Package.swift"
   "apps/macos-demo/README.md"
   "apps/macos-demo/Sources/TraverseMacOSDemoApp/TraverseMacOSDemoApp.swift"
@@ -21,7 +21,7 @@ done
 
 grep -q 'import SwiftUI' "${repo_root}/apps/macos-demo/Sources/TraverseMacOSDemoApp/TraverseMacOSDemoApp.swift"
 grep -q 'WindowGroup' "${repo_root}/apps/macos-demo/Sources/TraverseMacOSDemoApp/TraverseMacOSDemoApp.swift"
-grep -q '"status": "completed"' "${repo_root}/apps/demo-fixtures/expedition-runtime-session.json"
-grep -q '"state_updates"' "${repo_root}/apps/demo-fixtures/expedition-runtime-session.json"
+grep -q '"status": "completed"' "${repo_root}/examples/fixtures/expedition-runtime-session.json"
+grep -q '"state_updates"' "${repo_root}/examples/fixtures/expedition-runtime-session.json"
 
 echo "macOS demo smoke passed"
@@ -7,7 +7,7 @@ cd "$repo_root"
 
 agent_manifest="examples/meeting-notes/process-agent/manifest.json"
 agent_request="examples/meeting-notes/runtime-requests/process.json"
-app_manifest="apps/meeting-notes/app.manifest.json"
+app_manifest="examples/applications/meeting-notes/app.manifest.json"
 
 bash examples/meeting-notes/process-agent/build-fixture.sh >/tmp/meeting-notes-build.out
 

@@ -66,7 +66,7 @@ required_files=(
   "examples/hello-world/say-hello-agent/build-fixture.sh"
   "contracts/examples/hello-world/capabilities/say-hello/contract.json"
   "workflows/examples/hello-world/say-hello/workflow.json"
-  "apps/traverse-starter/app.manifest.json"
+  "examples/applications/traverse-starter/app.manifest.json"
   "apps/traverse-starter/components/process/component.manifest.json"
   "examples/traverse-starter/process-agent/manifest.json"
   "examples/traverse-starter/process-agent/build-fixture.sh"
@@ -328,7 +328,7 @@ grep -q "cargo run -p traverse-cli -- agent execute" examples/hello-world/README
 grep -q "hello.world.say-hello" examples/hello-world/README.md
 grep -q "traverse-starter.process" contracts/examples/traverse-starter/capabilities/process/contract.json
 grep -q "traverse-starter.process-agent" examples/traverse-starter/process-agent/manifest.json
-grep -q "traverse-starter.process-component" apps/traverse-starter/app.manifest.json
+grep -q "traverse-starter.process-component" examples/applications/traverse-starter/app.manifest.json
 grep -q "app validate --manifest \"\$app_manifest\" --json" scripts/ci/traverse_starter_example_smoke.sh
 grep -q "/v1/workspaces/local-default/execute" scripts/ci/traverse_starter_example_smoke.sh
 grep -q "starter_status: complete" scripts/ci/traverse_starter_example_smoke.sh
@@ -393,7 +393,7 @@ grep -q "newer for Phase 2 CLI registration" docs/releases/v0.5.0.md
 grep -q ".traverse/server.json" docs/releases/v0.5.0.md
 grep -q "schema version and discovery fields as \`v0.3.0\`" docs/releases/v0.5.0.md
 grep -q "Downstream App Registration Consumers" quickstart.md
-grep -q "apps/traverse-starter/app.manifest.json" quickstart.md
+grep -q "examples/applications/traverse-starter/app.manifest.json" quickstart.md
 grep -q "schema_version: \"1.0.0\"" quickstart.md
 grep -q "optional \`local_dev_token\`" quickstart.md
 grep -q "Traverse v0.6.0" docs/releases/v0.6.0.md

@@ -17,7 +17,7 @@ grep -q '.traverse/local/' "$doc"
 grep -q 'bin/' "$doc"
 grep -q 'fixtures/' "$doc"
 grep -q 'overlays/' "$doc"
-grep -q 'apps/demo-fixtures/' "$doc"
+grep -q 'examples/fixtures/' "$doc"
 grep -q 'package-local `./artifacts/` directories' "$doc"
 grep -q 'bash scripts/ci/runtime_home_smoke.sh' "$doc"
 

@@ -7,7 +7,7 @@ cd "$repo_root"
 
 agent_manifest="examples/traverse-starter/process-agent/manifest.json"
 agent_request="examples/traverse-starter/runtime-requests/process.json"
-app_manifest="apps/traverse-starter/app.manifest.json"
+app_manifest="examples/applications/traverse-starter/app.manifest.json"
 
 bash examples/traverse-starter/process-agent/build-fixture.sh >/tmp/traverse-starter-build.out