From 8eea0a70b896897b5cf9ce8ecfc537353dd00022 Mon Sep 17 00:00:00 2001 From: Enrico Piovesan Date: Sun, 23 Aug 2026 16:57:07 -0600 Subject: [PATCH] chore(sync): gate registry_ref materialize pending Spec 520 hosts Default stays on so shells keep working; APP_REFS_MATERIALIZE_REGISTRY_REFS=0 preserves destination registry_ref for hosts that resolve via verified cache. Co-authored-by: Cursor --- AGENTS.md | 4 +- docs/production-packaging.md | 11 ++--- docs/runtime-bundle-sync.md | 2 + scripts/ci/repository_checks.sh | 1 + scripts/ci/sync_bundle_core.sh | 14 +++++++ ...dle_materialize_registry_refs_gate_test.sh | 41 +++++++++++++++++++ 6 files changed, 67 insertions(+), 6 deletions(-) create mode 100755 scripts/ci/sync_bundle_materialize_registry_refs_gate_test.sh diff --git a/AGENTS.md b/AGENTS.md index 043f14e..1926f56 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,9 +28,11 @@ gh project item-list 2 --owner traverse-framework --format json --limit 300 \ | `llm-mcp-meeting-notes-workflow` | **Done** (#239) | Meeting-notes MCP tool-sequence runbook | | `llm-mcp-cursor-live-smoke` | **Done** (#240) | Cursor MCP Mode A stdio evidence | | `llm-mcp-claude-live-smoke` | **Done** (#241) | Claude Desktop/Code MCP Mode A evidence | -| `llm-mcp-traverse-starter-catalog` | **Blocked** | Kit IDs on MCP stdio — Traverse #865 / registry #99 | +| `llm-mcp-traverse-starter-catalog` | **Blocked** | Traverse #865 (registry #99 closed) | | `loop-wf1-registry-deps` | **Done** (#263) | Digest inventory in `docs/loop-registry-deps.md` | | `loop-wf1-multi-os` | **Done** (#265) | `apps/loop/` WF1 × 7 OS; compose via `registry_ref` | +| `retire-registry-ref-materialize` | **In Progress** | Phase A gate/docs; full delete blocked on Traverse BundleEmbedder + Spec 107 | +| `llm-mcp-embedded-host` | **Ready** | Mode B host on Spec 520 cache (#860 closed) | Full gap table + wave notes: [`docs/production-reference-plan.md`](docs/production-reference-plan.md). diff --git a/docs/production-packaging.md b/docs/production-packaging.md index 9ab75a1..7870f47 100644 --- a/docs/production-packaging.md +++ b/docs/production-packaging.md @@ -111,11 +111,12 @@ Governing Traverse / Registry specs: | Layer | Today | Next | |---|---|---| -| Component manifests under `manifests/` | **All six primary components** use `registry_ref` (`^1.0.0` → live `1.0.1` when yank-aware) | Keep ranges; no local-path reintroduction | -| Sync / packaging | [`runtime-bundle-sync.md`](runtime-bundle-sync.md) + `sync_bundle_materialize_registry_refs` for embedder trees | Embedder-native resolve (Traverse) can retire materialize | -| Implementation ticket | `registry-ref-full-kit-cutover` | Done when smoke evidence is green | +| Component manifests under `manifests/` | **All six primary components** (+ Loop WF1) use `registry_ref` | Keep ranges; no local-path reintroduction | +| Sync / packaging | [`runtime-bundle-sync.md`](runtime-bundle-sync.md) + **gated** `sync_bundle_materialize_registry_refs` (default **on**) | Retire rewrite once hosts resolve `registry_ref` offline from Spec 520 cache | +| Spec 520 (Traverse) | `#860` closed — Rust `HostRegistryCache` + web standalone prepare/resolve APIs | Web `BundleEmbedder` still requires `wasm_binary_path`; native Spec 107 adopt incomplete | +| App-Refs ticket | `retire-registry-ref-materialize` | Phase A: gate/tests/docs; full delete blocked on Traverse BundleEmbedder + Spec 107 | -**Checked-in source of truth** for every primary component is `registry_ref` only (no local `contract_path` / `wasm_*` on source manifests). Platform sync **materializes** local wasm paths into destination bundles for FetchBundleLoader hosts that still require `wasm_binary_path`. +**Checked-in source of truth** for every primary component is `registry_ref` only (no local `contract_path` / `wasm_*` on source manifests). Platform sync **materializes** local wasm paths into destination bundles by default (`APP_REFS_MATERIALIZE_REGISTRY_REFS=1`) for FetchBundleLoader / native bridges that still require `wasm_binary_path`. Set `APP_REFS_MATERIALIZE_REGISTRY_REFS=0` to leave destination `registry_ref` intact (hosts must use Traverse prepare + verified cache — not production-ready for all App-Refs shells yet). ## Intended component shape @@ -167,7 +168,7 @@ If sync has not run, registration must fail with a stable error that `traverse-c ## Agent / playbook rules - Do **not** reintroduce local `contract_path` / `wasm_*` on checked-in primary `manifests/` components. -- Platform sync may materialize `registry_ref` → local wasm in **destination** bundles only. +- Platform sync may materialize `registry_ref` → local wasm in **destination** bundles only (default on). Do not flip `APP_REFS_MATERIALIZE_REGISTRY_REFS=0` for primary shells until BundleEmbedder / native adopt paths are proven in smoke. - Prefer `version_range: "^1.0.0"` so yanked stub `1.0.0` is skipped and live `1.0.1` is selected when the resolver is yank-aware (registry spec 005). - UI remains a rendering layer — registry adoption does not move business field computation into App-References. diff --git a/docs/runtime-bundle-sync.md b/docs/runtime-bundle-sync.md index d5e1a26..b2c7207 100644 --- a/docs/runtime-bundle-sync.md +++ b/docs/runtime-bundle-sync.md @@ -28,6 +28,8 @@ Wrappers only choose destination, app id, component list, and which optional lay | `--traverse-assets` | `required` / `optional` / `none` | Web required; WinUI optional; Swift/Android none | | `--manifest-layout` | `root` / `subdir` | Android uses `subdir` (`manifests/` under bundle); others `root` | +`registry_ref` destination rewrite is gated by `APP_REFS_MATERIALIZE_REGISTRY_REFS` (default `1`). See [`production-packaging.md`](production-packaging.md) and ticket `retire-registry-ref-materialize`. + ## Commands ```bash diff --git a/scripts/ci/repository_checks.sh b/scripts/ci/repository_checks.sh index 0db960f..3b54dc7 100644 --- a/scripts/ci/repository_checks.sh +++ b/scripts/ci/repository_checks.sh @@ -149,6 +149,7 @@ check "scripts/ci/fixtures/traverse-starter-smoke-agents/process-agent.wasm" "Pi check "scripts/ci/fixtures/traverse-starter-smoke-agents/validate-agent.wasm" "Pinned Traverse validate agent wasm" check "scripts/ci/fixtures/traverse-starter-smoke-agents/summarize-agent.wasm" "Pinned Traverse summarize agent wasm" check "scripts/ci/sync_bundle_core.sh" "Shared bundle sync core" +check "scripts/ci/sync_bundle_materialize_registry_refs_gate_test.sh" "registry_ref materialize gate test" check "scripts/ci/sync_web_starter_bundle.sh" "Web starter bundle sync" check "scripts/ci/sync_web_doc_approval_bundle.sh" "Web doc-approval bundle sync" check "scripts/ci/sync_web_meeting_notes_bundle.sh" "Web meeting-notes bundle sync" diff --git a/scripts/ci/sync_bundle_core.sh b/scripts/ci/sync_bundle_core.sh index ab34cf9..1b29f3f 100755 --- a/scripts/ci/sync_bundle_core.sh +++ b/scripts/ci/sync_bundle_core.sh @@ -276,9 +276,23 @@ sync_bundle_destination() { # Canonical source under manifests/ stays registry_ref; destinations materialize. # Also copies the referenced example WASM + contract into dest/_traverse when missing # (Android/Swift sync with --traverse-assets none). +# +# Interim gate (ticket retire-registry-ref-materialize / Spec 520): +# APP_REFS_MATERIALIZE_REGISTRY_REFS=1 (default) — rewrite destination manifests +# APP_REFS_MATERIALIZE_REGISTRY_REFS=0 — leave registry_ref intact (hosts must +# resolve via Traverse HostRegistryCache / prepare+offline APIs). Full +# retirement waits on BundleEmbedder accepting registry_ref without wasm_* +# (web) and Spec 107 native adopt tickets. sync_bundle_materialize_registry_refs() { local dest="$1" local app_id="$2" + local materialize_mode="${APP_REFS_MATERIALIZE_REGISTRY_REFS:-1}" + case "$materialize_mode" in + 0|false|off|no|NO|False|Off) + echo "OK: skipping registry_ref materialize (APP_REFS_MATERIALIZE_REGISTRY_REFS=$materialize_mode)" + return 0 + ;; + esac REPO_ROOT="$REPO_ROOT" TRAVERSE_REPO="$TRAVERSE_REPO" DEST="$dest" APP_ID="$app_id" python3 - <<'PY' import hashlib, json, os, pathlib, shutil, sys diff --git a/scripts/ci/sync_bundle_materialize_registry_refs_gate_test.sh b/scripts/ci/sync_bundle_materialize_registry_refs_gate_test.sh new file mode 100755 index 0000000..7a6c4d3 --- /dev/null +++ b/scripts/ci/sync_bundle_materialize_registry_refs_gate_test.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +# Assert APP_REFS_MATERIALIZE_REGISTRY_REFS gate for sync_bundle_materialize_registry_refs. +# Does not require TRAVERSE_REPO example trees when materialize is off. +set -euo pipefail +ROOT="$(cd "$(dirname "$0")/../.." && pwd)" +# shellcheck source=scripts/ci/sync_bundle_core.sh +source "$ROOT/scripts/ci/sync_bundle_core.sh" +sync_bundle_init + +TMP="$(mktemp -d)" +trap 'rm -rf "$TMP"' EXIT + +mkdir -p "$TMP/components/process" +cat >"$TMP/components/process/component.manifest.json" <<'JSON' +{ + "component_id": "test.process-component", + "version": "1.0.0", + "schema_version": "1.0.0", + "capability_id": "meeting-notes.process", + "capability_version": "1.0.0", + "registry_ref": { + "namespace": "meeting-notes", + "id": "meeting-notes.process", + "version_range": "^1.0.0" + } +} +JSON + +# Off: destination must keep registry_ref and must not gain wasm_* fields. +APP_REFS_MATERIALIZE_REGISTRY_REFS=0 sync_bundle_materialize_registry_refs "$TMP" "meeting-notes" +python3 - <