docs: update README — ucas is primary CLI, json-cas deprecated

Also add list-meta and list-schema to command reference.

.changeset/config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://unpkg.com/@changesets/config@3.1.1/schema.json",
-  "changelog": "@changesets/changelog-github",
+  "changelog": ["@changesets/changelog-github", { "repo": "uncaged/json-cas" }],
   "commit": false,
   "fixed": [["@uncaged/*"]],
   "linked": [],

.cursor/rules/sync-readme.mdc

@@ -0,0 +1,3 @@
+# Sync README
+
+See [docs/sync-readme.md](../../docs/sync-readme.md) for full rules.

.gitignore

@@ -1,3 +1,5 @@
 node_modules/
 dist/
 *.d.ts.map
+*.tsbuildinfo
+.worktrees/

.workflows/e2e-check.yaml

@@ -0,0 +1,413 @@
+name: "e2e-check"
+description: "Docker-isolated E2E testing of json-cas CLI. Preparer builds from scratch, tester runs scenarios, reporter files bugs."
+
+roles:
+  preparer:
+    description: "Spins up Docker container, copies repo, installs, builds, runs unit tests"
+    goal: "You set up a clean Docker environment for E2E testing. Your job is to start a container, install deps, build, lint, run unit tests, and initialize a CAS store. Report any setup failures as bugs."
+    capabilities:
+      - docker
+    procedure: |
+      1. Start a detached container:
+         ```bash
+         docker run -d --name json-cas-e2e \
+           -v "<repoPath>:/src:ro" \
+           -w /workspace \
+           oven/bun:latest \
+           sleep 3600
+         ```
+
+      2. Copy repo and install:
+         ```bash
+         docker exec json-cas-e2e bash -c 'cp -r /src/. /workspace/ && cd /workspace && bun install'
+         ```
+         ✅ exit code 0, no missing peer deps
+
+      3. Build:
+         ```bash
+         docker exec json-cas-e2e bash -c 'cd /workspace && bun run build'
+         ```
+         ✅ exit code 0, no type errors
+
+      4. Lint:
+         ```bash
+         docker exec json-cas-e2e bash -c 'cd /workspace && bun run check'
+         ```
+         ✅ exit code 0
+
+      5. Unit tests:
+         ```bash
+         docker exec json-cas-e2e bash -c 'cd /workspace && bun test'
+         ```
+         ✅ all pass (ignore dist/ false positives)
+
+      6. Init CAS store:
+         ```bash
+         docker exec json-cas-e2e bash -c 'mkdir -p /tmp/cas-test && cd /workspace && bun packages/cli-json-cas/src/index.ts --store /tmp/cas-test init && bun packages/cli-json-cas/src/index.ts --store /tmp/cas-test bootstrap'
+         ```
+
+      **Any failure here is a high-severity bug** — it means a clean environment can't build/run the project.
+
+      Set $status=ready if all steps pass. Set $status=setup_failed with failures list if anything breaks.
+
+    output: "Setup result summary."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "ready" }
+            containerName: { type: string }
+            storePath: { type: string }
+            repoPath: { type: string }
+          required: [$status, containerName, storePath, repoPath]
+        - type: object
+          properties:
+            $status: { const: "setup_failed" }
+            failures:
+              type: array
+              items:
+                type: object
+                properties:
+                  title: { type: string }
+                  command: { type: string }
+                  expected: { type: string }
+                  actual: { type: string }
+                  severity: { type: string }
+                  phase: { type: string }
+                required: [title, command, expected, actual, severity, phase]
+            repoPath: { type: string }
+          required: [$status, failures, repoPath]
+
+  tester:
+    description: "Runs CLI scenarios against the prepared Docker environment"
+    goal: "You are an exploratory QA agent. The Docker container is already running with the project built and a CAS store initialized. Run CLI test scenarios and report bugs."
+    capabilities:
+      - testing
+      - cli
+    procedure: |
+      The container `{{{containerName}}}` is already running with the project built.
+      Store path: `{{{storePath}}}`.
+
+      Run all commands via:
+      ```bash
+      docker exec {{{containerName}}} bash -c 'cd /workspace && bun packages/cli-json-cas/src/index.ts --store {{{storePath}}} <subcommand>'
+      ```
+
+      Define a shorthand in your notes:
+      `CMD="cd /workspace && bun packages/cli-json-cas/src/index.ts --store {{{storePath}}}"`
+
+      ## Phase 1: CAS Core Operations
+
+      1. **bootstrap** — `$CMD bootstrap`
+         Expected: prints meta-schema hash (13-char Base32)
+
+      2. **schema put** — Create `/tmp/test-schema.json` in container, then `$CMD schema put /tmp/test-schema.json`
+         Schema: `{"type":"object","properties":{"name":{"type":"string"},"age":{"type":"number"}},"required":["name"],"additionalProperties":false}`
+         Expected: prints type hash
+
+      3. **schema get** — `$CMD schema get <type-hash>`
+         Expected: returns the schema JSON
+
+      4. **schema list** — `$CMD schema list`
+         Expected: lists registered schemas
+
+      5. **put** — Create data file, `$CMD put <type-hash> /tmp/test-node.json`
+         Data: `{"name":"Alice","age":30}`
+         Expected: prints node hash
+
+      6. **get** — `$CMD get <node-hash>`
+         Expected: returns node JSON
+
+      7. **has (exists)** — `$CMD has <node-hash>`
+         Expected: true
+
+      8. **has (not exists)** — `$CMD has AAAAAAAAAAAAA`
+         Expected: false
+
+      9. **verify** — `$CMD verify <node-hash>`
+         Expected: ok
+
+      10. **refs** — `$CMD refs <node-hash>`
+          Expected: lists refs (may be empty)
+
+      11. **walk** — `$CMD walk <node-hash>`
+          Expected: shows traversal tree
+
+      12. **hash (dry run)** — `$CMD hash <type-hash> /tmp/test-node.json`
+          Expected: same hash as put
+
+      13. **cat** — `$CMD cat <node-hash>`
+          Expected: full node output
+
+      14. **cat --payload** — `$CMD cat <node-hash> --payload`
+          Expected: payload only (no type wrapper)
+
+      ## Phase 2: Schema Validation
+
+      1. **Invalid node** — `$CMD put <type-hash> /tmp/bad-node.json` where bad-node = `{"name":123}`
+         Expected: validation error, non-zero exit
+
+      2. **schema validate** — `$CMD schema validate <node-hash>`
+         Expected: valid for good node
+
+      3. **Non-existent schema** — `$CMD put AAAAAAAAAAAAA /tmp/test-node.json`
+         Expected: error about missing schema
+
+      ## Phase 3: Variable System
+
+      1. **var set** — `$CMD var set myapp/config <node-hash>`
+         Expected: creates variable
+
+      2. **var get** — `$CMD var get myapp/config --schema <type-hash>`
+         Expected: returns variable
+
+      3. **var list** — `$CMD var list`
+         Expected: shows all variables
+
+      4. **var list prefix** — `$CMD var list myapp/`
+         Expected: filtered results
+
+      5. **var set (update)** — Put a second node, `$CMD var set myapp/config <new-hash>`
+         Expected: upsert succeeds
+
+      6. **var tag** — `$CMD var tag myapp/config --schema <type-hash> env:prod important`
+         Expected: adds tag and label
+
+      7. **var list --tag** — `$CMD var list --tag env:prod`
+         Expected: finds tagged variable
+
+      8. **var list --tag (label)** — `$CMD var list --tag important`
+         Expected: finds labeled variable
+
+      9. **var tag remove** — `$CMD var tag myapp/config --schema <type-hash> :important`
+         Expected: removes label
+
+      10. **var delete** — `$CMD var delete myapp/config`
+          Expected: deletes variable
+
+      11. **var get (deleted)** — `$CMD var get myapp/config --schema <type-hash>`
+          Expected: not found error
+
+      ## Phase 4: Template System
+
+      1. **template set** — Create template file, `$CMD template set <type-hash> /tmp/test.liquid`
+         Template: `Name: {{ payload.name }}, Age: {{ payload.age }}`
+         Expected: success
+
+      2. **template get** — `$CMD template get <type-hash>`
+         Expected: returns template text
+
+      3. **template list** — `$CMD template list`
+         Expected: lists templates
+
+      4. **template delete** — `$CMD template delete <type-hash>`
+         Expected: success
+
+      5. **template get (deleted)** — `$CMD template get <type-hash>`
+         Expected: not found error
+
+      ## Phase 5: Render
+
+      1. Re-register template, then `$CMD render <node-hash>`
+         Expected: rendered output with payload values filled in
+
+      2. **render --resolution** — `$CMD render <node-hash> --resolution 0.5`
+         Expected: different resolution output
+
+      3. **render (bad hash)** — `$CMD render AAAAAAAAAAAAA`
+         Expected: graceful error, non-zero exit
+
+      ## Phase 6: GC
+
+      1. **gc basic** — `$CMD gc`
+         Expected: runs without error
+
+      2. **gc preserves referenced** — Verify `$CMD has <node-hash>` still true
+
+      3. **gc collects orphans** — Put an orphan node (not in any variable), run gc, check it's gone
+
+      ## Phase 7: Edge Cases & Error Handling
+
+      1. `$CMD get AAAAAAAAAAAAA` — non-existent
+      2. `$CMD put <type-hash> /nonexistent/file.json` — missing file
+      3. `$CMD var set "" <hash>` — empty name
+      4. `$CMD var set "bad name!" <hash>` — invalid name chars
+      5. `$CMD schema put /tmp/bad-schema.json` — `{"type":"invalid"}`
+      6. `$CMD` with no subcommand — should show help
+      7. `$CMD --store /nonexistent/path get <hash>` — bad store path
+
+      ## Recording Results
+
+      For each scenario:
+      - ✅ Pass: works as expected
+      - ❌ Fail: unexpected behavior, crash, wrong output
+      - ⚠️ Questionable: works but confusing UX
+
+      Collect all ❌ and ⚠️. For each, record:
+      - Title (concise description)
+      - Command (exact command run)
+      - Expected behavior
+      - Actual behavior (include actual output)
+      - Severity: critical / high / medium / low
+      - Phase: which test phase
+
+      ## CRITICAL: Frontmatter Output Format
+
+      Your response MUST start with YAML frontmatter. The `bugs` field MUST be an array of objects, NOT strings.
+
+      Example of CORRECT frontmatter:
+      ```yaml
+      ---
+      $status: bugs_found
+      containerName: json-cas-e2e
+      repoPath: /path/to/repo
+      bugs:
+        - title: "put does not validate data against schema"
+          command: "json-cas put <hash> bad-data.json"
+          expected: "Validation error, non-zero exit"
+          actual: "Accepted invalid data, exit 0"
+          severity: "high"
+          phase: "Schema Validation"
+      ---
+      ```
+
+      Do NOT write bugs as plain strings like `- some bug description`. Each bug MUST be an object with all 6 fields.
+
+      If all tests pass:
+      ```yaml
+      ---
+      $status: all_passed
+      containerName: json-cas-e2e
+      ---
+      ```
+
+    output: "Summary of all phases with pass/fail counts. Set $status."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "bugs_found" }
+            bugs:
+              type: array
+              items:
+                type: object
+                properties:
+                  title: { type: string }
+                  command: { type: string }
+                  expected: { type: string }
+                  actual: { type: string }
+                  severity: { type: string }
+                  phase: { type: string }
+                required: [title, command, expected, actual, severity, phase]
+            containerName: { type: string }
+            repoPath: { type: string }
+          required: [$status, bugs, containerName]
+        - type: object
+          properties:
+            $status: { const: "all_passed" }
+            containerName: { type: string }
+          required: [$status, containerName]
+
+  reporter:
+    description: "Opens Gitea issues for each bug found by the tester"
+    goal: "You are a bug reporter. You create well-formatted Gitea issues for each bug found during E2E testing."
+    capabilities:
+      - issue-management
+    procedure: |
+      1. Parse the bugs array from the tester's output
+      2. Group bugs by severity (critical first)
+      3. For each bug, create a Gitea issue:
+         ```bash
+         tea issues create -r uncaged/json-cas \
+           -t "[E2E] <title>" \
+           -d "## Bug Report (E2E Check)
+
+         **Phase:** <phase>
+         **Severity:** <severity>
+
+         **Command:**
+         \`\`\`
+         <exact command>
+         \`\`\`
+
+         **Expected:** <expected>
+
+         **Actual:** <actual>
+
+         ---
+         _Reported by e2e-check workflow (Docker isolated)_"
+         ```
+
+         ⚠️ If `tea issues create` fails with long body, use Gitea REST API:
+         ```bash
+         eval "$(cfg env)" && GITEA_TOKEN=$(cfg get GITEA_TOKEN)
+         curl -s -X POST "https://git.shazhou.work/api/v1/repos/uncaged/json-cas/issues" \
+           -H "Authorization: token $GITEA_TOKEN" \
+           -H "Content-Type: application/json" \
+           -d '{"title":"[E2E] ...","body":"..."}'
+         ```
+
+      4. Collect created issue numbers
+
+    output: "List created issues. Set $status."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "reported" }
+            issues:
+              type: array
+              items: { type: string }
+          required: [$status, issues]
+        - type: object
+          properties:
+            $status: { const: "partial" }
+            created: { type: number }
+            failed: { type: number }
+          required: [$status, created, failed]
+
+  cleanup:
+    description: "Stops and removes the Docker container"
+    goal: "You clean up the Docker environment after testing is complete."
+    capabilities:
+      - docker
+    procedure: |
+      Stop and remove the container:
+      ```bash
+      docker stop {{{containerName}}} && docker rm {{{containerName}}}
+      ```
+
+      Verify it's gone:
+      ```bash
+      docker ps -a --filter name={{{containerName}}} --format '{{.Names}}'
+      ```
+      Expected: empty output.
+
+    output: "Cleanup result."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "cleaned" }
+          required: [$status]
+        - type: object
+          properties:
+            $status: { const: "cleanup_failed" }
+            error: { type: string }
+          required: [$status, error]
+
+graph:
+  $START:
+    _: { role: "preparer", prompt: "Set up Docker environment for E2E testing. Repo at {{{repoPath}}}." }
+  preparer:
+    ready: { role: "tester", prompt: "Environment ready. Container: {{{containerName}}}, store: {{{storePath}}}. Run all test scenarios." }
+    setup_failed: { role: "reporter", prompt: "Setup failures found. File these as bugs: {{{failures}}}" }
+  tester:
+    all_passed: { role: "cleanup", prompt: "All tests passed. Clean up container {{{containerName}}}." }
+    bugs_found: { role: "reporter", prompt: "File these bugs as Gitea issues: {{{bugs}}}" }
+  reporter:
+    reported: { role: "cleanup", prompt: "Bugs filed: {{{issues}}}. Clean up container {{{containerName}}}." }
+    partial: { role: "cleanup", prompt: "Filed {{{created}}} issues, {{{failed}}} failed. Clean up container {{{containerName}}}." }
+  cleanup:
+    cleaned: { role: "$END", prompt: "E2E check complete. Environment cleaned up." }
+    cleanup_failed: { role: "$END", prompt: "E2E check complete but cleanup failed: {{{error}}}" }

.workflows/retrospect-workflow.yaml

@@ -0,0 +1,231 @@
+name: "retrospect-workflow"
+description: "Post-execution retrospective: analyze a completed thread, find inefficiencies, and improve the workflow definition."
+roles:
+  analyst:
+    description: "Scans thread execution for anomalies and produces a findings report"
+    goal: "You are a workflow execution analyst. You review completed thread data to find inefficiencies, wasted effort, and procedure gaps."
+    capabilities:
+      - data-analysis
+    procedure: |
+      You receive a completed thread ID in your task prompt.
+
+      Phase 0 — Validation (must pass before any analysis):
+      1. Run `uwf step list <thread-id>` to get thread metadata including the workflow hash
+      2. Run `uwf workflow show <workflow-hash>` to get the workflow name
+      3. Verify the workflow exists locally: check `.workflows/<name>.yaml` in the current repo
+         - If NOT found: output $status=wrong_project with the workflow name. Do NOT proceed.
+      4. Compare the thread's workflow hash against the current registered version:
+         - Run `uwf workflow show <name>` to get the current hash
+         - If hashes differ: the thread ran on an older version. Note this — you will need to diff versions after analysis.
+
+      Phase 1 — Overview scan:
+      5. From the step list, compute a health signal for each step:
+         - Duration: flag if >2x the median of other steps
+         - Output tokens: flag if >2x the median
+         - Status flow: flag non-happy-path transitions (rejected, fix_code, fix_spec, hook_failed)
+         - Step count: flag if the same role appears more than expected (indicates loops)
+      6. If no anomalies found AND versions match: output $status=clean
+      7. If no anomalies found BUT versions differ:
+         - Diff the two workflow versions to check if any procedure changes are relevant
+         - If the current version already addresses potential concerns: output $status=clean with a note
+         - Otherwise: proceed to Phase 2
+
+      Phase 2 — Targeted deep-dive (only for flagged steps):
+      8. For each flagged step, run `uwf step show <hash>` to get the detail with turns
+      9. Analyze the turn sequence for:
+         - Repeated tool calls with the same or similar input (blind retries)
+         - Tool errors followed by no strategy change (same approach retried)
+         - Unnecessary exploration (reading files or running commands unrelated to the task)
+         - Hallucinated commands or flags (commands that don't exist or wrong syntax)
+         - Excessive turns before reaching the goal
+      10. For each finding, record:
+          - Which role and step hash
+          - What happened (specific turn indices and commands)
+          - Root cause hypothesis (procedure gap, missing pitfall, unclear instruction)
+          - Suggested fix (what to add/change in the procedure)
+      11. If versions differ: compare findings against the version diff.
+          Mark any finding that is already fixed in the current version as "resolved_in_current".
+          Only report findings that are NOT yet addressed.
+
+      Output a structured findings report. Set $status=clean if nothing actionable, $status=findings if unresolved issues exist, or $status=wrong_project if the workflow doesn't belong here.
+    output: "A findings report with per-issue root cause and suggested procedure fixes. Set $status to clean or findings (with report hash)."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "clean" }
+            summary: { type: string }
+          required: [$status, summary]
+        - type: object
+          properties:
+            $status: { const: "findings" }
+            report: { type: string }
+            targetWorkflow: { type: string }
+          required: [$status, report, targetWorkflow]
+        - type: object
+          properties:
+            $status: { const: "wrong_project" }
+            workflowName: { type: string }
+          required: [$status, workflowName]
+  proposer:
+    description: "Translates findings into concrete workflow edits"
+    goal: "You are a workflow improvement proposer. You read the analyst's findings and produce specific, minimal edits to the workflow YAML."
+    capabilities:
+      - planning
+    procedure: |
+      1. Read the analyst's findings report from your task prompt
+      2. Locate the target workflow YAML:
+         - Workflow definitions live in the WORKFLOW ENGINE repo (where `uwf` is developed), NOT in the repo that was analyzed.
+         - Find it via: `uwf workflow show <targetWorkflow> --format yaml` to read the current definition
+         - The physical file is `.workflows/<targetWorkflow>.yaml` in the workflow engine repo
+         - Use `git rev-parse --show-toplevel` in the current directory to find the workflow engine repo root
+      3. Read the current workflow YAML to understand existing procedures
+      4. For each finding, draft a minimal edit:
+         - Prefer adding a pitfall note or clarifying instruction over restructuring
+         - If a procedure step is ambiguous, make it explicit
+         - If a tool usage pattern is wrong, add a "Do NOT" or "IMPORTANT" note
+         - Keep edits surgical — don't rewrite procedures that work fine
+      5. Check if existing tests need updating (search for test files referencing the workflow)
+      6. Produce a change plan as CAS text node via `uwf cas put-text "<plan>"`
+
+      The plan should list each edit with:
+      - File path
+      - What to change (old text → new text, or addition)
+      - Why (linked to which finding)
+      - Any test updates needed
+    output: "A change plan stored in CAS. Set $status to ready (with plan hash and repoPath) or no_action (if findings don't warrant changes)."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "ready" }
+            plan: { type: string }
+            repoPath: { type: string }
+          required: [$status, plan, repoPath]
+        - type: object
+          properties:
+            $status: { const: "no_action" }
+            reason: { type: string }
+          required: [$status, reason]
+  developer:
+    description: "Applies the proposed workflow edits"
+    goal: "You are a developer agent. You apply workflow YAML edits and update related tests."
+    capabilities:
+      - coding
+    procedure: |
+      IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.
+      The workflow definitions live in THIS repo (the workflow engine), not the repo that was analyzed.
+
+      Before starting any work, set up an isolated worktree:
+      1. Use `git rev-parse --show-toplevel` to find the repo root (do NOT use repoPath from proposer — that's the analyzed repo)
+      2. `git fetch origin` to get latest refs
+      3. `git worktree add .worktrees/retrospect/<short-slug> -b retrospect/<short-slug> origin/main`
+      4. `cd .worktrees/retrospect/<short-slug> && bun install`
+      5. ALL subsequent work must happen inside the worktree directory.
+
+      Then apply changes:
+      6. Read the change plan from CAS: `uwf cas get <plan hash>`
+      7. Apply each edit from the plan to the workflow YAML
+      8. Update or add tests as specified in the plan
+      9. Run `bun run build` and `bun test` to verify
+      10. Run `bun run check` for lint
+      11. Commit with message: `improve: <workflow-name> — <brief summary>`
+    output: "List all files changed and provide a summary. Set $status to done (with branch/worktree), or failed (with reason)."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "done" }
+            branch: { type: string }
+            worktree: { type: string }
+          required: [$status, branch, worktree]
+        - type: object
+          properties:
+            $status: { const: "failed" }
+            reason: { type: string }
+          required: [$status, reason]
+  reviewer:
+    description: "Reviews the workflow edits for correctness"
+    goal: "You are a reviewer. You verify that workflow edits are minimal, correct, and actually address the findings."
+    capabilities:
+      - code-review
+    procedure: |
+      The worktree path is provided in your task prompt. cd into it first.
+
+      Review criteria:
+      1. Each edit must trace back to a specific finding — no drive-by changes
+      2. Edits should be minimal — don't rewrite working procedures
+      3. New pitfall notes or instructions must be clear and actionable
+      4. Tests must be updated if assertions changed
+      5. `bun run build` and `bun test` must pass
+      6. `bunx biome check` must pass
+
+      IMPORTANT: `tea pr create` must run from the MAIN repo directory (not a worktree), because tea cannot detect the repo from worktree `.git` files.
+    output: "Explain your decision. Set $status to approved (with branch/worktree) or rejected (with comments)."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "approved" }
+            branch: { type: string }
+            worktree: { type: string }
+          required: [$status, branch, worktree]
+        - type: object
+          properties:
+            $status: { const: "rejected" }
+            comments: { type: string }
+            worktree: { type: string }
+          required: [$status, comments, worktree]
+  committer:
+    description: "Commits and creates PR"
+    goal: "You are a committer agent. You create a clean commit and push a PR."
+    capabilities: []
+    procedure: |
+      The worktree path, branch name, and repo info are provided in your task prompt.
+      cd into the worktree first.
+
+      Note: You inherit the developer's worktree and branch. Do NOT create a new branch.
+      1. Stage all changes: `git add -A`
+      2. Commit with a descriptive message: `git commit -m "improve: <workflow> — <summary>"`
+      3. Push the branch: `git push -u origin <branch-name>`
+         - If push hook fails: capture the error log in your output, mark hook_failed
+      4. On push success: create a PR via `tea pr create --title "..." --description "..."`
+         - IMPORTANT: `tea pr create` must run from the MAIN repo directory (not a worktree), because tea cannot detect the repo from worktree `.git` files. cd to the repo root first.
+         - Do NOT pass `--repo` — let tea auto-detect from the main repo's git remote.
+         - PR description must include: What / Why / Findings / Changes sections
+         - On tea failure: capture stderr/stdout, include PR details for manual creation, mark hook_failed
+      5. After PR creation, clean up the worktree:
+         - cd to the repo root (parent of .worktrees)
+         - `git worktree remove <worktree-path>`
+    output: "Include PR URL on success or error log on failure. Set $status to committed (with prUrl) or hook_failed (with error)."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "committed" }
+            prUrl: { type: string }
+          required: [$status, prUrl]
+        - type: object
+          properties:
+            $status: { const: "hook_failed" }
+            error: { type: string }
+          required: [$status, error]
+graph:
+  $START:
+    _: { role: "analyst", prompt: "Analyze completed thread {{{threadId}}} for execution anomalies." }
+  analyst:
+    clean: { role: "$END", prompt: "No issues found. Thread executed cleanly." }
+    findings: { role: "proposer", prompt: "Findings report: {{{report}}}. Target workflow: {{{targetWorkflow}}}. Propose minimal edits." }
+    wrong_project: { role: "$END", prompt: "Thread uses workflow '{{{workflowName}}}' which does not exist in this project. Run retrospect from the correct repo." }
+  proposer:
+    no_action: { role: "$END", prompt: "No actionable changes needed: {{{reason}}}." }
+    ready: { role: "developer", prompt: "Apply the change plan (CAS hash: {{{plan}}}) to the workflow definitions in this repo." }
+  developer:
+    done: { role: "reviewer", prompt: "Review workflow edits on branch {{{branch}}} at {{{worktree}}}." }
+    failed: { role: "$END", prompt: "Developer failed: {{{reason}}}. Ending workflow." }
+  reviewer:
+    rejected: { role: "developer", prompt: "Reviewer rejected: {{{comments}}}. Fix the issues in {{{worktree}}}." }
+    approved: { role: "committer", prompt: "Approved. Commit and push branch {{{branch}}} from {{{worktree}}}." }
+  committer:
+    hook_failed: { role: "developer", prompt: "Push hook failed: {{{error}}}. Fix and re-submit." }
+    committed: { role: "$END", prompt: "PR created: {{{prUrl}}}. Workflow improved." }

.workflows/solve-issue.yaml

@@ -0,0 +1,209 @@
+name: "solve-issue"
+description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds."
+roles:
+  planner:
+    description: "Analyzes issue and outputs a TDD test spec"
+    goal: "You are a planning agent. You analyze Gitea issues and produce a TDD test specification that downstream roles will implement and verify."
+    capabilities:
+      - issue-analysis
+      - planning
+    procedure: |
+      On first run (no previous steps):
+      1. Read the issue and all comments from Gitea using `tea issues <number> -r <owner/repo>`
+      2. Look for project conventions files (CLAUDE.md, CONTRIBUTING.md, .cursor/rules/) in the repo
+      3. Assess whether the issue has enough information to produce a test spec
+      4. If insufficient info: comment on the issue via `echo "..." | tea comment <number> -r <owner/repo>` (skip if you already commented), then output $status=insufficient_info
+      5. If sufficient: produce a detailed TDD test spec in markdown covering all scenarios
+
+      On subsequent runs (bounced back by tester with fix_spec):
+      1. Read the tester's output from the previous step to understand what's wrong with the spec
+      2. Revise the test spec accordingly
+
+      After producing the test spec:
+      1. Store it via `uwf cas put-text "<markdown content>"` and capture the returned hash
+      2. Put the hash in frontmatter.plan (required when $status=ready)
+      3. Set repoPath to the absolute path of the repository root
+    output: "Output a brief summary of the test spec. Set $status to ready (with plan hash and repoPath) or insufficient_info."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "ready" }
+            plan: { type: string }
+            repoPath: { type: string }
+          required: [$status, plan, repoPath]
+        - type: object
+          properties:
+            $status: { const: "insufficient_info" }
+          required: [$status]
+  developer:
+    description: "TDD implementation per test spec"
+    goal: "You are a developer agent. You implement code changes following TDD — write tests first, then implementation."
+    capabilities:
+      - coding
+    procedure: |
+      IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.
+      The repo path and other details are provided in your task prompt.
+
+      Before starting any work, set up an isolated worktree:
+      1. cd into the repo path provided in your task prompt
+      2. `git fetch origin` to get latest refs
+      3. First time (no existing branch):
+         - `git worktree add .worktrees/fix/<issue-number>-<short-slug> -b fix/<issue-number>-<short-slug> origin/main`
+         - `cd .worktrees/fix/<issue-number>-<short-slug> && bun install`
+      4. If bounced back from reviewer or tester (branch already exists):
+         - cd into the existing worktree under `.worktrees/fix/<issue-number>-<short-slug>`
+         - `git fetch origin && git rebase origin/main`
+      5. ALL subsequent work must happen inside the worktree directory.
+
+      Then implement TDD:
+      6. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the planner's output in your task prompt)
+      7. If bounced back from reviewer or tester: read the previous role's feedback in your task prompt
+      8. Write tests first based on the spec
+      9. Implement the code to make tests pass
+      10. Ensure `bun run build` passes with no errors
+      11. Run `bun test` to verify all tests pass
+
+      If you cannot complete the implementation (e.g. the issue is too complex, blocked by external factors,
+      or repeated attempts fail), set $status=failed with a reason.
+    output: "List all files changed and provide a summary. Set $status to done (with branch/worktree), or failed (with reason)."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "done" }
+            branch: { type: string }
+            worktree: { type: string }
+          required: [$status, branch, worktree]
+        - type: object
+          properties:
+            $status: { const: "failed" }
+            reason: { type: string }
+          required: [$status, reason]
+  reviewer:
+    description: "Code standards compliance check"
+    goal: "You are a code reviewer. You verify code standards compliance — NOT functionality (that's the tester's job)."
+    capabilities:
+      - code-review
+      - static-analysis
+    procedure: |
+      The worktree path is provided in your task prompt. cd into it first.
+
+      Before reviewing, verify the git branch:
+      1. Run `git branch --show-current` — confirm the branch name references the issue number being worked on
+      2. If the branch doesn't correspond to the issue, flag it in your output and reject
+
+      Then perform code review:
+      Hard checks (must all pass):
+      3. `bun run build` — no build errors
+      4. `bunx biome check` — no lint violations
+      5. TypeScript strict mode — no type errors
+
+      Soft checks (review against project conventions if CLAUDE.md / .cursor/rules exist):
+      - Naming conventions, module boundaries, code style
+      - No `console.log` in production code
+      - No dynamic imports in production code
+
+      Only review standards compliance. Do NOT test functionality.
+      If rejecting, you MUST explain the specific reason in your output.
+    output: "Explain your decision with specific file/line references. Set $status to approved (with branch/worktree) or rejected (with comments)."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "approved" }
+            branch: { type: string }
+            worktree: { type: string }
+          required: [$status, branch, worktree]
+        - type: object
+          properties:
+            $status: { const: "rejected" }
+            comments: { type: string }
+            worktree: { type: string }
+          required: [$status, comments, worktree]
+  tester:
+    description: "Functional correctness verification"
+    goal: "You are a tester agent. You verify that the implementation correctly satisfies every scenario in the test spec."
+    capabilities:
+      - testing
+    procedure: |
+      The worktree path is provided in your task prompt. cd into it first.
+
+      1. Run `bun test` for automated test verification
+      2. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the planner step in the thread history)
+      3. Verify each scenario in the spec is covered and passing
+      4. Determine outcome:
+         - passed: all scenarios verified, tests pass
+         - fix_code: tests fail or implementation doesn't match spec → send back to developer
+         - fix_spec: the spec itself is wrong or incomplete → send back to planner
+    output: "Report test results per scenario. Set $status to passed (with branch/worktree), fix_code (with report), or fix_spec (with report)."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "passed" }
+            branch: { type: string }
+            worktree: { type: string }
+          required: [$status, branch, worktree]
+        - type: object
+          properties:
+            $status: { const: "fix_code" }
+            report: { type: string }
+          required: [$status, report]
+        - type: object
+          properties:
+            $status: { const: "fix_spec" }
+            report: { type: string }
+          required: [$status, report]
+  committer:
+    description: "Commits and creates PR"
+    goal: "You are a committer agent. You create a clean commit and push a PR linking the original issue."
+    capabilities: []
+    procedure: |
+      The worktree path, branch name, and repo info are provided in your task prompt.
+      cd into the worktree first.
+
+      Note: You inherit the developer's worktree and branch. Do NOT create a new branch.
+      1. Stage all changes: `git add -A`
+      2. Commit with a descriptive message referencing the issue: `git commit -m "type: description\n\nFixes #N"`
+      3. Push the branch: `git push -u origin <branch-name>`
+         - If push hook fails: capture the error log in your output, mark hook_failed
+      4. On push success: create a PR via `tea pr create --repo <owner/repo> --title "..." --description "..."`
+         - Extract owner/repo from: `git remote get-url origin | sed 's/.*[:/]\([^/]*\/[^.]*\).*/\1/'`
+         - PR description must include: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
+         - On tea failure: capture stderr/stdout, include PR details for manual creation, mark hook_failed
+      5. After PR creation, clean up the worktree:
+         - cd to the repo root (parent of .worktrees)
+         - `git worktree remove <worktree-path>`
+    output: "Include PR URL on success or error log on failure. Set $status to committed (with prUrl) or hook_failed (with error)."
+    frontmatter:
+      oneOf:
+        - type: object
+          properties:
+            $status: { const: "committed" }
+            prUrl: { type: string }
+          required: [$status, prUrl]
+        - type: object
+          properties:
+            $status: { const: "hook_failed" }
+            error: { type: string }
+          required: [$status, error]
+graph:
+  $START:
+    _: { role: "planner", prompt: "Analyze the issue and produce an implementation plan." }
+  planner:
+    insufficient_info: { role: "$END", prompt: "Insufficient information to proceed; end the workflow." }
+    ready: { role: "developer", prompt: "Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}." }
+  developer:
+    done: { role: "reviewer", prompt: "Review branch {{{branch}}} at {{{worktree}}} for code standards compliance." }
+    failed: { role: "$END", prompt: "Developer failed: {{{reason}}}. Ending workflow." }
+  reviewer:
+    rejected: { role: "developer", prompt: "Reviewer rejected: {{{comments}}}. Fix the issues in repo {{{worktree}}}." }
+    approved: { role: "tester", prompt: "Review passed. Run tests on branch {{{branch}}} at {{{worktree}}}." }
+  tester:
+    fix_code: { role: "developer", prompt: "Tests found code issues: {{{report}}}. Fix and re-submit." }
+    fix_spec: { role: "planner", prompt: "Tests found spec issues: {{{report}}}. Revise the test spec." }
+    passed: { role: "committer", prompt: "All tests passed. Commit and push branch {{{branch}}} from {{{worktree}}}." }
+  committer:
+    hook_failed: { role: "developer", prompt: "Push hook failed: {{{error}}}. Fix and re-submit." }
+    committed: { role: "$END", prompt: "PR created: {{{prUrl}}}. Workflow complete." }

CLAUDE.md

@@ -0,0 +1,77 @@
+# CLAUDE.md — json-cas
+
+Self-describing content-addressable storage with JSON Schema typed nodes.
+
+## Project Structure
+
+Monorepo with 4 packages under `packages/`:
+
+| Package | Description |
+|---------|-------------|
+| `json-cas` | Core CAS engine — hashing, schema, store, verify, bootstrap |
+| `json-cas-fs` | Filesystem-backed CAS store |
+| `cli-json-cas` | CLI tool |
+
+## Tech Stack
+
+- **Runtime:** Bun
+- **Language:** TypeScript (strict mode, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`)
+- **Build:** `tsc --build` (composite project references)
+- **Test:** `bun test`
+- **Lint/Format:** Biome (`biome check .` / `biome format --write .`)
+- **Publish:** Changesets → npmjs (`@uncaged/*`)
+
+## Commands
+
+```bash
+bun test          # Run all tests
+bun run build     # Build all packages
+bun run check     # Biome lint
+bun run format    # Biome format (auto-fix)
+```
+
+## Code Conventions
+
+### TypeScript
+
+- **Strict mode** — no `any`, no unchecked index access, no implicit overrides
+- **`verbatimModuleSyntax`** — use `import type` for type-only imports
+- **Import paths** — use `.js` extension in imports (ESM convention with bundler resolution)
+- **Export style** — named exports only, re-export from `index.ts`
+
+### Biome Rules
+
+- `noConsole: "error"` globally (except `cli-json-cas`)
+- Recommended ruleset enabled
+- Auto-organize imports via `assist.actions.source.organizeImports`
+- Indent: 2 spaces
+
+### Naming
+
+- Types: `PascalCase` (`CasNode`, `Hash`, `Store`)
+- Functions: `camelCase` (`computeHash`, `createMemoryStore`)
+- Constants: `UPPER_SNAKE_CASE` (`BOOTSTRAP_STORE`)
+- Files: `kebab-case.ts`
+- Test files: co-located as `*.test.ts`
+
+### Key Types
+
+- `Hash` — 13-character uppercase Crockford Base32 string (XXH64)
+- `CasNode` — content-addressed node with schema
+- `Store` — abstract storage interface (get/put)
+
+## Git
+
+- Commit format: `type: description` (conventional commits)
+- Reference issues: `Fixes #N` / `Closes #N`
+- Author: `小橘 <xiaoju@shazhou.work>`
+
+## Project Rules
+
+- [docs/sync-readme.md](docs/sync-readme.md) — README sync conventions
+
+## Before Submitting
+
+1. `bun test` — all tests pass
+2. `bun run check` — no lint errors
+3. `bun run build` — builds cleanly

README.md

@@ -1,3 +1,167 @@
 # json-cas
 
-Self-describing content-addressable storage with JSON Schema typed nodes
+Self-describing content-addressable storage with JSON Schema typed nodes.
+
+## Overview
+
+json-cas is a monorepo for storing and validating JSON data in a content-addressable store (CAS). Each node has a typed payload: its `type` field is the hash of a JSON Schema node that describes the payload shape. Hashes are 13-character Crockford Base32 strings derived from XXH64 over deterministic CBOR encoding.
+
+A bootstrap meta-schema is stored as a self-referencing seed node (`type === hash`). All other schemas are registered as nodes typed by that meta-schema. Payloads can reference other nodes via `format: "cas_ref"` fields; the library provides traversal, reference extraction, and integrity verification.
+
+Use the in-memory store for tests and embedded apps, the filesystem store for persistence, and the CLI for local store management.
+
+## Architecture
+
+```
+     ┌─────────────────┐
+     │  cli-json-cas   │
+     └────────┬────────┘
+              │
+              ▼
+     ┌─────────────────┐
+     │  json-cas-fs    │
+     └────────┬────────┘
+              │
+              ▼
+     ┌─────────────────┐
+     │    json-cas     │  (core)
+     └─────────────────┘
+```
+
+| Layer | Package | Role |
+|-------|---------|------|
+| Core | `@uncaged/json-cas` | Hashing, schemas, stores, verify, bootstrap |
+| Storage | `@uncaged/json-cas-fs` | Filesystem-backed `Store` |
+| CLI | `@uncaged/cli-json-cas` | `ucas` command-line tool |
+
+## Packages
+
+| Package | Description | Type |
+|---------|-------------|------|
+| [`@uncaged/json-cas`](packages/json-cas/README.md) | Core CAS engine — hashing, schema, store, verify, bootstrap | lib |
+| [`@uncaged/json-cas-fs`](packages/json-cas-fs/README.md) | Filesystem-backed CAS store | lib |
+| [`@uncaged/cli-json-cas`](packages/cli-json-cas/README.md) | CLI tool (`ucas` binary) | cli |
+
+## Quick Start
+
+```bash
+git clone <repo-url>
+cd json-cas
+bun install --no-cache
+bun run build
+```
+
+```typescript
+import {
+  bootstrap,
+  createMemoryStore,
+  putSchema,
+  validate,
+} from "@uncaged/json-cas";
+
+const store = createMemoryStore();
+await bootstrap(store);
+
+const typeHash = await putSchema(store, {
+  type: "object",
+  properties: { message: { type: "string" } },
+  required: ["message"],
+  additionalProperties: false,
+});
+
+const hash = await store.put(typeHash, { message: "hello" });
+const node = store.get(hash);
+console.log(validate(store, node!)); // true
+```
+
+For a persistent store:
+
+```typescript
+import { createFsStore } from "@uncaged/json-cas-fs";
+import { bootstrap } from "@uncaged/json-cas";
+
+const store = createFsStore("/path/to/store");
+await bootstrap(store);
+```
+
+Or use the CLI (see [CLI Reference](#cli-reference) and [`packages/cli-json-cas/README.md`](packages/cli-json-cas/README.md)).
+
+## CLI Reference
+
+Binary: `ucas` (from `@uncaged/cli-json-cas`; legacy alias `json-cas` is deprecated). Default store:
+`~/.uncaged/json-cas`. The store is auto-created and bootstrapped on first use — there is
+no `init`/`bootstrap` command, and schemas are ordinary `@schema`-typed nodes (`ucas put
+@schema file.json`), so there is no `schema` subcommand.
+
+### Envelope format
+
+Every JSON-emitting command prints a uniform `{ type, value }` envelope. `type` is the hash
+of the command's `@output/*` result schema and `value` is the command payload. This makes
+output self-describing and pipeable: feed any envelope into `render -p` to render its
+`value` (embedded `cas_ref` hashes are expanded). `render` is the only command that emits
+raw (non-envelope) text.
+
+```jsonc
+// ucas has <hash>
+{ "type": "AYHQD2YA9G667", "value": true }
+```
+
+```
+Usage: ucas [--store <path>] [--json] <command> [args]
+
+Commands (all emit a { type, value } envelope unless noted):
+  put <type-hash> <file.json>       Store node (value = hash)          (@output/put)
+  get <hash>                        Node payload + metadata            (@output/get)
+  has <hash>                        Existence boolean                  (@output/has)
+  verify <hash>                     ok / corrupted / invalid           (@output/verify)
+  refs <hash>                       Direct cas_ref edges               (@output/refs)
+  walk <hash> [--format tree]       Recursive traversal                (@output/walk)
+  hash <type-hash> <file.json>      Compute hash without storing       (@output/hash)
+  render <hash> [options]           Render node as text (raw output)
+  render --pipe/-p [options]        Render a piped envelope (raw output)
+  list --type <hash-or-alias>       Hashes for a type (value = list)   (@output/list)
+  list-meta                         Meta-schema hashes                 (@output/list-meta)
+  list-schema                       All schema hashes                  (@output/list-schema)
+  var set|get|delete|tag|list ...   Variable CRUD                      (@output/var-*)
+  template set|get|list|delete ...  Output-template CRUD               (@output/template-*)
+  gc                                Garbage collection                 (@output/gc)
+
+Flags:
+  --store <path>   Store directory (default: ~/.uncaged/json-cas)
+  --json           Compact JSON output
+  --pipe, -p       Read a { type, value } envelope from stdin for render
+```
+
+### Pipe examples
+
+```bash
+# Store a node, then render the stored content (the put envelope's hash is
+# a cas_ref, so render -p dereferences and renders it):
+ucas put @schema ./schemas/item.json | ucas render -p
+
+# Render garbage-collection stats:
+ucas gc | ucas render -p
+
+# List every schema, then consume the envelope's value array with jq:
+ucas list --type @schema | jq -r '.value[]'
+```
+
+## Development
+
+```bash
+bun install --no-cache   # install workspace dependencies
+bun run build            # tsc --build (libs)
+bun run check            # biome check
+bun run format           # biome format --write
+bun test                 # run all package tests
+```
+
+## Publishing
+
+Releases use [Changesets](https://github.com/changesets/changesets). From the repo root:
+
+```bash
+bun run release   # changeset version → build → publish to npm (@uncaged/*)
+```
+
+Individual packages block `prepublishOnly` and expect releases via the workspace `release` script.

bun.lock

@@ -10,11 +10,12 @@
         "@changesets/cli": "^2.31.0",
         "bun-types": "^1.3.14",
         "typescript": "^5.8.0",
+        "ulidx": "^2.4.1",
       },
     },
     "packages/cli-json-cas": {
       "name": "@uncaged/cli-json-cas",
-      "version": "0.1.0",
+      "version": "0.5.3",
       "bin": {
         "json-cas": "./src/index.ts",
       },
@@ -25,28 +26,22 @@
     },
     "packages/json-cas": {
       "name": "@uncaged/json-cas",
-      "version": "0.1.0",
+      "version": "0.5.3",
       "dependencies": {
         "ajv": "^8.20.0",
         "cborg": "^4.2.3",
+        "liquidjs": "^10.27.0",
         "xxhash-wasm": "^1.1.0",
       },
     },
     "packages/json-cas-fs": {
       "name": "@uncaged/json-cas-fs",
-      "version": "0.1.0",
+      "version": "0.5.3",
       "dependencies": {
         "@uncaged/json-cas": "workspace:^",
         "cborg": "^4.2.3",
       },
     },
-    "packages/json-cas-workflow": {
-      "name": "@uncaged/json-cas-workflow",
-      "version": "0.1.0",
-      "dependencies": {
-        "@uncaged/json-cas": "workspace:^",
-      },
-    },
   },
   "packages": {
     "@babel/runtime": ["@babel/runtime@7.29.2", "", {}, "sha512-JiDShH45zKHWyGe4ZNVRrCjBz8Nh9TMmZG1kh4QTK8hCBTWBi8Da+i7s1fJw7/lYpM4ccepSNfqzZ/QvABBi5g=="],
@@ -127,8 +122,6 @@
 
     "@uncaged/json-cas-fs": ["@uncaged/json-cas-fs@workspace:packages/json-cas-fs"],
 
-    "@uncaged/json-cas-workflow": ["@uncaged/json-cas-workflow@workspace:packages/json-cas-workflow"],
-
     "ajv": ["ajv@8.20.0", "", { "dependencies": { "fast-deep-equal": "^3.1.3", "fast-uri": "^3.0.1", "json-schema-traverse": "^1.0.0", "require-from-string": "^2.0.2" } }, "sha512-Thbli+OlOj+iMPYFBVBfJ3OmCAnaSyNn4M1vz9T6Gka5Jt9ba/HIR56joy65tY6kx/FCF5VXNB819Y7/GUrBGA=="],
 
     "ansi-colors": ["ansi-colors@4.1.3", "", {}, "sha512-/6w/C21Pm1A7aZitlI5Ni/2J6FFQN8i1Cvz3kHABAAbw93v/NlvKdVOqz7CCWz/3iv/JplRSEEZ83XION15ovw=="],
@@ -149,6 +142,8 @@
 
     "chardet": ["chardet@2.1.1", "", {}, "sha512-PsezH1rqdV9VvyNhxxOW32/d75r01NY7TQCmOqomRo15ZSOKbpTFVsfjghxo6JloQUCGnH4k1LGu0R4yCLlWQQ=="],
 
+    "commander": ["commander@10.0.1", "", {}, "sha512-y4Mg2tXshplEbSGzx7amzPwKKOCGuoSRP/CjEdwwk0FOGlUbq6lKuoyDZTNZkmxHdJtp54hdfY/JUrdL7Xfdug=="],
+
     "cross-spawn": ["cross-spawn@7.0.6", "", { "dependencies": { "path-key": "^3.1.0", "shebang-command": "^2.0.0", "which": "^2.0.1" } }, "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA=="],
 
     "dataloader": ["dataloader@1.4.0", "", {}, "sha512-68s5jYdlvasItOJnCuI2Q9s4q98g0pCyL3HrcKJu8KNugUl8ahgmZYg38ysLTgQjjXX3H8CJLkAvWrclWfcalw=="],
@@ -209,6 +204,10 @@
 
     "jsonfile": ["jsonfile@4.0.0", "", { "optionalDependencies": { "graceful-fs": "^4.1.6" } }, "sha512-m6F1R3z8jjlf2imQHS2Qez5sjKWQzbuuhuJ/FKYFRZvPE3PuHcSMVZzfsLhGVOkfd20obL5SWEBew5ShlquNxg=="],
 
+    "layerr": ["layerr@3.0.0", "", {}, "sha512-tv754Ki2dXpPVApOrjTyRo4/QegVb9eVFq4mjqp4+NM5NaX7syQvN5BBNfV/ZpAHCEHV24XdUVrBAoka4jt3pA=="],
+
+    "liquidjs": ["liquidjs@10.27.0", "", { "dependencies": { "commander": "^10.0.0" }, "bin": { "liquidjs": "bin/liquid.js", "liquid": "bin/liquid.js" } }, "sha512-tw/OA59K7aIBlMKIrKlumr37fiZUheShVHXY8cVctWisgY1p9mc5hreOvlreoS0wTiwlWk14Ya7305c2a/Cg5w=="],
+
     "locate-path": ["locate-path@5.0.0", "", { "dependencies": { "p-locate": "^4.1.0" } }, "sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g=="],
 
     "lodash.startcase": ["lodash.startcase@4.4.0", "", {}, "sha512-+WKqsK294HMSc2jEbNgpHpd0JfIBhp7rEV4aqXWqFr6AlXov+SlcgB1Fv01y2kGe3Gc8nMW7VA0SrGuSkRfIEg=="],
@@ -291,6 +290,8 @@
 
     "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
 
+    "ulidx": ["ulidx@2.4.1", "", { "dependencies": { "layerr": "^3.0.0" } }, "sha512-xY7c8LPyzvhvew0Fn+Ek3wBC9STZAuDI/Y5andCKi9AX6/jvfaX45PhsDX8oxgPL0YFp0Jhr8qWMbS/p9375Xg=="],
+
     "undici-types": ["undici-types@7.24.6", "", {}, "sha512-WRNW+sJgj5OBN4/0JpHFqtqzhpbnV0GuB+OozA9gCL7a993SmU+1JBZCzLNxYsbMfIeDL+lTsphD5jN5N+n0zg=="],
 
     "universalify": ["universalify@0.1.2", "", {}, "sha512-rBJeI5CXAlmy1pV+617WB9J63U6XcazHHF2f2dbJix4XzpUF0RS3Zbj0FGIOCAva5P/d/GBOYaACQ1w+0azUkg=="],

docs/sync-readme.md

@@ -0,0 +1,68 @@
+# Sync README
+
+When updating README.md files in this monorepo, follow these conventions.
+
+## Scope
+
+- Root `README.md` — project overview and navigation hub
+- Per-package `packages/*/README.md` — each package self-contained
+
+## Root README Structure
+
+The root README should have these sections in order:
+
+1. **Title and one-liner** — content-addressed storage for JSON with schema validation
+2. **Overview** — 2-3 paragraphs explaining what it does and key concepts
+3. **Architecture** — dependency layer diagram (text-based)
+4. **Packages** — table with ALL packages from packages/ directory, columns: Package, Description, Type (cli/lib)
+5. **Quick Start** — install, build, basic usage
+6. **CLI Reference** — brief command list, detailed usage in cli-json-cas README
+7. **Development** — bun install / build / check / test
+8. **Publishing** — changeset workflow (bun run release)
+
+## Per-Package README Structure
+
+Each package README should have:
+
+1. **Title** — package name
+2. **One-line description** — matching package.json
+3. **Overview** — what it does, where it sits in the architecture, dependencies
+4. **Installation** — bun add (for libs) or "included as binary" (for cli)
+5. **API** (lib packages) — all exports from src/index.ts with type signatures, grouped by category, minimal usage examples
+6. **CLI Usage** (cli packages) — command reference with examples
+7. **Internal Structure** — brief src/ file organization
+8. **Configuration** (if applicable)
+
+## Execution Steps
+
+### Step 1: Gather current state
+For each package read:
+- package.json (name, version, description, dependencies, bin)
+- src/index.ts (public API exports)
+- Existing README.md (preserve hand-written content worth keeping)
+
+### Step 2: Update root README
+- Ensure ALL packages in packages/ directory are listed in the table
+- Update CLI command reference from actual --help output
+- Keep Quick Start examples valid
+
+### Step 3: Write/update each package README
+- Follow the per-package structure
+- API section MUST match actual src/index.ts exports — never invent
+- For cli packages: document CLI binary name, how it is invoked
+- For lib packages: document exported types and functions
+- Internal structure: list actual files in src/
+
+### Step 4: Verify
+- All relative links work
+- Package names match package.json
+- No references to removed/renamed packages
+- bun run build still passes
+
+## Guidelines
+
+- Only document what src/index.ts actually exports
+- Root README summarizes, package READMEs go into detail
+- Verify CLI examples against actual commands
+- Preserve existing good prose when updating
+- English for all README content

package.json

@@ -9,11 +9,14 @@
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.31.0",
     "bun-types": "^1.3.14",
-    "typescript": "^5.8.0"
+    "typescript": "^5.8.0",
+    "ulidx": "^2.4.1"
   },
   "scripts": {
+    "build": "tsc --build packages/json-cas packages/json-cas-fs",
     "test": "bun test",
     "check": "biome check .",
-    "format": "biome format --write ."
+    "format": "biome format --write .",
+    "release": "changeset version && bun run build && changeset publish"
   }
 }

packages/cli-json-cas/CHANGELOG.md

@@ -0,0 +1,63 @@
+# @uncaged/cli-json-cas
+
+## 0.6.0
+
+### Minor Changes
+
+- Unified `{ type, value }` envelope output for all CLI commands (RFC [#67](https://github.com/uncaged/json-cas/issues/67)).
+
+  ### Breaking Changes
+
+  - Removed `init`, `bootstrap`, `cat`, `schema put/get/list/validate` commands
+  - All CLI command outputs now wrapped in `{ type, value }` envelope (except `render`)
+  - `openStore()` is now async and auto-bootstraps
+
+  ### New Features
+
+  - 18 `@output/*` schemas registered at bootstrap
+  - `list --type <hash-or-alias>` command (replaces `schema list`)
+  - `verify` now checks both hash integrity and schema validation
+  - `wrapEnvelope()` helper exported from `@uncaged/json-cas`
+  - `openStore()` in `@uncaged/json-cas-fs` — async, auto mkdir + bootstrap
+  - Default LiquidJS templates for all output schemas
+  - Pipe composition: any command output can be piped to `render -p`
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.6.0
+  - @uncaged/json-cas-fs@0.6.0
+
+## 0.5.3
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.5.3
+  - @uncaged/json-cas-fs@0.5.3
+
+## 0.3.0
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.3.0
+  - @uncaged/json-cas-fs@0.3.0
+
+## 0.2.0
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.2.0
+  - @uncaged/json-cas-fs@0.2.0
+
+## 0.1.3
+
+### Patch Changes
+
+- fix: replace workspace:^ with actual version numbers in published dependencies
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.1.3
+  - @uncaged/json-cas-fs@0.1.3

packages/cli-json-cas/README.md

@@ -0,0 +1,147 @@
+# @uncaged/cli-json-cas
+
+CLI tool for json-cas stores.
+
+## Overview
+
+`@uncaged/cli-json-cas` provides the `json-cas` command (also aliased `ucas`) for managing a filesystem-backed store: node CRUD, integrity checks, reference listing, graph walks, variables, and output templates. It uses `@uncaged/json-cas-fs` for persistence and `@uncaged/json-cas` for core operations.
+
+The store is **auto-created and bootstrapped** on first use, so there is no `init`/`bootstrap` command. Schemas are ordinary `@schema`-typed nodes — register one with `ucas put @schema file.json` and list them with `ucas list --type @schema`; there is no dedicated `schema` subcommand.
+
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`
+
+## Installation
+
+Published as an npm package with a binary entry:
+
+```bash
+bun add -g @uncaged/cli-json-cas
+# or from the monorepo workspace:
+bun link
+```
+
+**Binary name:** `json-cas` (points to `src/index.ts`, run with Bun).
+
+In development:
+
+```bash
+bun packages/cli-json-cas/src/index.ts <command> [args]
+```
+
+## CLI Usage
+
+```
+Usage: json-cas [--store <path>] [--json] <command> [args]
+```
+
+### Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--store <path>` | Store directory (default: `~/.uncaged/json-cas`) |
+| `--var-db <path>` | Variable database path (default: `<store>/variables.db`) |
+| `--json` | Compact (single-line) JSON output |
+
+### Envelope format
+
+Every JSON-emitting command prints a uniform `{ type, value }` envelope. `type` is the hash
+of the command's `@output/*` result schema and `value` is the command payload. The output
+is therefore self-describing and pipeable: feed any envelope into `render -p` to render its
+`value` (embedded `cas_ref` hashes are expanded). `render` is the only command that emits
+raw, non-envelope text.
+
+```jsonc
+// json-cas has <hash>
+{ "type": "AYHQD2YA9G667", "value": true }
+
+// json-cas template set <schema-hash> --inline "Hi {{ payload.name }}"
+{ "type": "9YJZ09DDAYAWR", "value": { "schemaHash": "7XX5H51CVD9H0", "contentHash": "FC8WACA792B6F" } }
+```
+
+### Commands
+
+| Command | Envelope `value` | Result schema |
+|---------|------------------|---------------|
+| `put <type-hash> <file.json>` | stored node hash (string) | `@output/put` |
+| `get <hash>` | `{ type, payload, timestamp }` | `@output/get` |
+| `has <hash>` | boolean | `@output/has` |
+| `verify <hash>` | `ok` / `corrupted` / `invalid` | `@output/verify` |
+| `refs <hash>` | hashes (string[]) | `@output/refs` |
+| `walk <hash> [--format tree]` | hashes (string[]) or tree string | `@output/walk` |
+| `hash <type-hash> <file.json>` | computed hash (string) | `@output/hash` |
+| `render <hash> [options]` | raw text (no envelope) | — |
+| `render --pipe/-p [options]` | raw text from piped envelope | — |
+| `list --type <hash-or-alias>` | hashes (string[]) | `@output/list` |
+| `var set <name> <hash> [--tag ...]` | variable object | `@output/var-set` |
+| `var get <name> --schema <hash>` | variable object | `@output/var-get` |
+| `var delete <name> [--schema <hash>]` | variable or variable[] | `@output/var-delete` |
+| `var tag <name> --schema <hash> <ops...>` | variable object | `@output/var-tag` |
+| `var list [prefix] [--schema <hash>] [--tag ...]` | variable[] | `@output/var-list` |
+| `template set <schema-hash> <file> \| --inline <text>` | `{ schemaHash, contentHash }` | `@output/template-set` |
+| `template get <schema-hash>` | template content (string) | `@output/template-get` |
+| `template list` | `{ schemaHash, contentHash }[]` | `@output/template-list` |
+| `template delete <schema-hash>` | `{ deleted: boolean }` | `@output/template-delete` |
+| `gc` | `{ total, reachable, collected, scanned }` | `@output/gc` |
+
+### Examples
+
+```bash
+# Register a schema (schemas are plain @schema nodes) and store a payload
+json-cas put @schema ./schemas/item.json
+# → { "type": "...", "value": "0123456789ABC" }  (the schema's type hash)
+
+json-cas put 0123456789ABC ./payloads/item.json
+# → { "type": "...", "value": "<content-hash>" }
+
+json-cas get <content-hash> --json
+json-cas verify <content-hash>
+json-cas walk <content-hash> --format tree
+
+# List every registered schema, then extract the hashes with jq
+json-cas list --type @schema | jq -r '.value[]'
+```
+
+### Pipe composition
+
+Because every command shares the `{ type, value }` envelope, output composes directly into
+`render -p`:
+
+```bash
+# put emits a cas_ref hash envelope; render -p dereferences and renders the node
+json-cas put @schema ./schemas/item.json | json-cas render -p
+
+# render gc statistics
+json-cas gc | json-cas render -p
+
+# render every schema referenced by a list result
+json-cas list --type @schema | json-cas render -p
+```
+
+### Templates
+
+`template` commands manage the LiquidJS template bound to a schema (stored as a
+`@ucas/template/text/<schema-hash>` variable). `render <hash>` uses the template registered
+for the node's type, falling back to YAML when none exists.
+
+```bash
+# Bind a template to a schema, then render a node of that type
+json-cas template set 0123456789ABC --inline "Item: {{ payload.name }}"
+json-cas render <content-hash>
+# → Item: Widget
+```
+
+## Internal Structure
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Argument parsing, command dispatch, and all CLI logic |
+
+There is no separate `src/` module tree; the CLI is a single entry file. Tests (if present) are co-located under the package.
+
+## Configuration
+
+| Setting | Default | Override |
+|---------|---------|----------|
+| Store directory | `~/.uncaged/json-cas` | `--store <path>` |
+
+No config file is read; all behavior is controlled via flags and command arguments.

packages/cli-json-cas/package.json

@@ -1,15 +1,17 @@
 {
   "name": "@uncaged/cli-json-cas",
-"version": "0.1.1",
+  "version": "0.6.0",
   "type": "module",
   "bin": {
-    "json-cas": "./src/index.ts"
+    "json-cas": "./src/index.ts",
+    "ucas": "./src/index.ts"
   },
   "scripts": {
-    "test": "bun test"
+    "test": "bun test",
+    "prepublishOnly": "bash ../../scripts/check-workspace-deps.sh"
   },
   "dependencies": {
-    "@uncaged/json-cas": "workspace:^",
-    "@uncaged/json-cas-fs": "workspace:^"
+    "@uncaged/json-cas": "^0.6.0",
+    "@uncaged/json-cas-fs": "^0.6.0"
   }
 }

packages/cli-json-cas/tests/__snapshots__/edge-cases.test.ts.snap

@@ -0,0 +1,249 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`Phase 7: Edge Cases 7.1 get non-existent hash errors gracefully 1`] = `"Node not found: AAAAAAAAAAAAA"`;
+
+exports[`Phase 7: Edge Cases 7.3 var set empty name errors 1`] = `"Usage: json-cas var set <name> <hash> [--tag <tag>...]"`;
+
+exports[`Phase 7: Edge Cases 7.4 var set name with invalid chars errors 1`] = `"Error: Invalid variable name "invalid name!": Segment "invalid name!" contains invalid characters (only @, a-z, A-Z, 0-9, ., _, - allowed)"`;
+
+exports[`Phase 7: Edge Cases 7.5 no subcommand shows help text 1`] = `
+"Usage: json-cas [--store <path>] [--json] <command> [args]
+
+All JSON commands emit a { type, value } envelope. The type is the hash of the
+command's @output/* schema (shown in parentheses); pipe any envelope into
+\`render -p\` to render its value (cas_ref hashes are expanded).
+
+Commands:
+  put <type-hash> <file.json|--pipe> Store node, print envelope (value=hash)            (@output/put)
+  get <hash>                        Print node as envelope                             (@output/get)
+  has <hash>                        Print envelope (value=boolean)                     (@output/has)
+  verify <hash>                     Verify integrity + schema (value=ok/corrupted/invalid) (@output/verify)
+  refs <hash>                       List direct cas_ref edges                          (@output/refs)
+  walk <hash> [--format tree]       Recursive traversal                                (@output/walk)
+  hash <type-hash> <file.json|--pipe> Compute hash without storing                     (@output/hash)
+  render <hash> [options]           Render node as text with resolution decay (raw output)
+  render --pipe/-p [options]        Render { type, value } from stdin (raw output)
+  list --type <hash-or-alias>       List hashes for a type (value=string[])            (@output/list)
+  list-meta                         List meta-schema hashes (value=string[])           (@output/list-meta)
+  list-schema                       List all schema hashes (value=string[])            (@output/list-schema)
+  var set <name> <hash> [--tag <tag>...] Create/update a variable                      (@output/var-set)
+  var get <name> --schema <hash>    Get a variable by name + schema                    (@output/var-get)
+  var delete <name> [--schema <hash>] Delete variable(s)                               (@output/var-delete)
+  var list [prefix] [--schema <hash>] [--tag <tag>...] List variables                  (@output/var-list)
+  var tag <name> --schema <hash> <operations...> Modify tags/labels                    (@output/var-tag)
+  template set <schema-hash> <file> | --inline <text> Set template for schema          (@output/template-set)
+  template get <schema-hash>        Get template content (value=string)                (@output/template-get)
+  template list                     List all templates                                 (@output/template-list)
+  template delete <schema-hash>     Delete template for schema                         (@output/template-delete)
+  gc                                Run garbage collection                             (@output/gc)
+
+Flags:
+  --store <path>      Store directory (default: ~/.uncaged/json-cas)
+  --var-db <path>     Variable database path (default: <store>/variables.db)
+  --json              Compact JSON output
+  --schema <hash>     Schema hash filter for var get/delete/tag/list
+  --tag <tag>         Tag/label (can be repeated): key:value (tag), name (label), :name (delete)
+  --inline <text>     Inline text content for template set
+  --resolution <n>    Initial resolution for render (default: 1.0)
+  --decay <n>         Decay factor for render (default: 0.5)
+  --epsilon <n>       Cutoff threshold for render (default: 0.01)
+  --pipe, -p          Read from stdin (put/hash: raw JSON payload; render: { type, value } envelope)"
+`;
+
+exports[`Phase 3: Variable System 3.1 var set creates variable 1`] = `
+{
+  "type": "5KVHSESSX7N96",
+  "value": {
+    "labels": [],
+    "name": "myapp/config",
+    "schema": "8WAZV39SD724T",
+    "tags": {},
+    "value": "6KZ930XYK2MHB",
+  },
+}
+`;
+
+exports[`Phase 3: Variable System 3.2 var get returns variable 1`] = `
+{
+  "type": "7D4R2MJ1EYF08",
+  "value": {
+    "labels": [],
+    "name": "myapp/config",
+    "schema": "8WAZV39SD724T",
+    "tags": {},
+    "value": "6KZ930XYK2MHB",
+  },
+}
+`;
+
+exports[`Phase 3: Variable System 3.3 var list shows all variables 1`] = `
+{
+  "type": "E8158M25YNR9M",
+  "value": [
+    {
+      "labels": [],
+      "name": "myapp/config",
+      "schema": "8WAZV39SD724T",
+      "tags": {},
+      "value": "6KZ930XYK2MHB",
+    },
+  ],
+}
+`;
+
+exports[`Phase 3: Variable System 3.4 var list prefix filters by prefix 1`] = `
+{
+  "type": "E8158M25YNR9M",
+  "value": [
+    {
+      "labels": [],
+      "name": "myapp/config",
+      "schema": "8WAZV39SD724T",
+      "tags": {},
+      "value": "6KZ930XYK2MHB",
+    },
+  ],
+}
+`;
+
+exports[`Phase 3: Variable System 3.5 var set upsert updates existing variable 1`] = `
+{
+  "type": "5KVHSESSX7N96",
+  "value": {
+    "labels": [],
+    "name": "myapp/config",
+    "schema": "8WAZV39SD724T",
+    "tags": {},
+    "value": "AE80669JYG4K2",
+  },
+}
+`;
+
+exports[`Phase 3: Variable System 3.6 var tag adds kv tag and label 1`] = `
+{
+  "type": "2WX4XRYSACRWR",
+  "value": {
+    "labels": [
+      "important",
+    ],
+    "name": "myapp/config",
+    "schema": "8WAZV39SD724T",
+    "tags": {
+      "env": "prod",
+    },
+    "value": "6KZ930XYK2MHB",
+  },
+}
+`;
+
+exports[`Phase 3: Variable System 3.7 var list --tag env:prod filters by kv tag 1`] = `
+{
+  "type": "E8158M25YNR9M",
+  "value": [
+    {
+      "labels": [
+        "important",
+      ],
+      "name": "myapp/config",
+      "schema": "8WAZV39SD724T",
+      "tags": {
+        "env": "prod",
+      },
+      "value": "6KZ930XYK2MHB",
+    },
+  ],
+}
+`;
+
+exports[`Phase 3: Variable System 3.8 var list --tag important filters by label 1`] = `
+{
+  "type": "E8158M25YNR9M",
+  "value": [
+    {
+      "labels": [
+        "important",
+      ],
+      "name": "myapp/config",
+      "schema": "8WAZV39SD724T",
+      "tags": {
+        "env": "prod",
+      },
+      "value": "6KZ930XYK2MHB",
+    },
+  ],
+}
+`;
+
+exports[`Phase 3: Variable System 3.9 var tag remove deletes label 1`] = `
+{
+  "type": "2WX4XRYSACRWR",
+  "value": {
+    "labels": [],
+    "name": "myapp/config",
+    "schema": "8WAZV39SD724T",
+    "tags": {
+      "env": "prod",
+    },
+    "value": "6KZ930XYK2MHB",
+  },
+}
+`;
+
+exports[`Phase 3: Variable System 3.10 var delete removes variable 1`] = `
+{
+  "type": "F89626QEK09YY",
+  "value": [
+    {
+      "labels": [],
+      "name": "myapp/config",
+      "schema": "8WAZV39SD724T",
+      "tags": {
+        "env": "prod",
+      },
+      "value": "6KZ930XYK2MHB",
+    },
+  ],
+}
+`;
+
+exports[`Phase 3: Variable System 3.11 var get deleted variable returns not found 1`] = `"Error: Variable not found: name=myapp/config, schema=8WAZV39SD724T"`;
+
+exports[`Phase 4: Template System 4.1 template set registers template 1`] = `
+{
+  "type": "A8RGY9B1JSCDJ",
+  "value": {
+    "contentHash": "0359SHMP7VBFD",
+    "schemaHash": "8WAZV39SD724T",
+  },
+}
+`;
+
+exports[`Phase 4: Template System 4.2 template get returns template text 1`] = `
+{
+  "type": "64FP3TWKK69YH",
+  "value": "Name: {{ payload.name }}, Age: {{ payload.age }}",
+}
+`;
+
+exports[`Phase 4: Template System 4.3 template list shows registered templates 1`] = `
+{
+  "type": "BE20H482GBNM3",
+  "value": [
+    {
+      "contentHash": "0359SHMP7VBFD",
+      "schemaHash": "8WAZV39SD724T",
+    },
+  ],
+}
+`;
+
+exports[`Phase 4: Template System 4.4 template delete removes template 1`] = `
+{
+  "type": "0FXB2GS8Y9R1R",
+  "value": {
+    "deleted": true,
+  },
+}
+`;
+
+exports[`Phase 4: Template System 4.5 template get deleted template returns not found 1`] = `"Error: Template not found for schema: 8WAZV39SD724T"`;

packages/cli-json-cas/tests/__snapshots__/put-get-has.test.ts.snap

@@ -0,0 +1,14 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`Phase 1: CAS Core 1.6 get returns node JSON (snapshot) 1`] = `
+{
+  "type": "CE40D09H75NFZ",
+  "value": {
+    "payload": {
+      "age": 30,
+      "name": "Alice",
+    },
+    "type": "8WAZV39SD724T",
+  },
+}
+`;

packages/cli-json-cas/tests/__snapshots__/render.test.ts.snap

@@ -0,0 +1,5 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`Phase 5: Render 5.1 render fills payload variables 1`] = `"Hello Alice!"`;
+
+exports[`Phase 5: Render 5.2 render --resolution with different value 1`] = `"Hello Alice!"`;

packages/cli-json-cas/tests/__snapshots__/schema-validation.test.ts.snap

@@ -0,0 +1,3 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`Phase 2: Schema Validation 2.3 put against non-existent schema hash fails 1`] = `"Schema not found: AAAAAAAAAAAAA"`;

packages/cli-json-cas/tests/__snapshots__/verify-refs-walk.test.ts.snap

@@ -0,0 +1,24 @@
+// Bun Snapshot v1, https://bun.sh/docs/test/snapshots
+
+exports[`Phase 1: CAS Core 1.9 verify returns ok for valid node 1`] = `
+{
+  "type": "BZ31JDDWX2AWH",
+  "value": "ok",
+}
+`;
+
+exports[`Phase 1: CAS Core 1.10 refs lists direct references (snapshot) 1`] = `
+"{
+  "type": "DG8SAB75PV9P7",
+  "value": []
+}"
+`;
+
+exports[`Phase 1: CAS Core 1.11 walk shows traversal tree (snapshot) 1`] = `
+"{
+  "type": "EVHG7Q7FK83H0",
+  "value": [
+    "6KZ930XYK2MHB"
+  ]
+}"
+`;

packages/cli-json-cas/tests/alias.test.ts

@@ -0,0 +1,187 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+// ---- @ Alias Resolution Tests ----
+
+let testDir: string;
+let storePath: string;
+let cliPath: string;
+
+beforeEach(() => {
+  // Create unique temp directory for each test
+  testDir = join(
+    tmpdir(),
+    `json-cas-cli-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  storePath = join(testDir, "store");
+  cliPath = join(import.meta.dir, "../src/index.ts");
+
+  mkdirSync(testDir, { recursive: true });
+  mkdirSync(storePath, { recursive: true });
+});
+
+afterEach(() => {
+  // Clean up test directory
+  try {
+    rmSync(testDir, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors
+  }
+});
+
+/**
+ * Run CLI command and return stdout, stderr, and exit code
+ */
+async function runCliAlias(...args: string[]): Promise<{
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}> {
+  const proc = Bun.spawn(
+    ["bun", "run", cliPath, "--store", storePath, ...args],
+    {
+      stdout: "pipe",
+      stderr: "pipe",
+    },
+  );
+
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+
+  await proc.exited;
+
+  return {
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+    exitCode: proc.exitCode ?? 0,
+  };
+}
+
+/** Extract the `value` field from a { type, value } envelope JSON string. */
+function envValue(json: string): unknown {
+  return (JSON.parse(json.trim()) as { value: unknown }).value;
+}
+
+describe("@ Alias Resolution - put", () => {
+  test("ucas put @string <file> should resolve alias", async () => {
+    await runCliAlias("init");
+
+    const payloadFile = join(testDir, "payload.json");
+    writeFileSync(payloadFile, JSON.stringify("hello world"));
+
+    const { stdout, stderr, exitCode } = await runCliAlias(
+      "put",
+      "@string",
+      payloadFile,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stderr).toBe("");
+    // Should output an envelope whose value is a valid hash (13 chars)
+    expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("ucas put @number <file> should resolve alias", async () => {
+    await runCliAlias("init");
+
+    const payloadFile = join(testDir, "payload.json");
+    writeFileSync(payloadFile, "42");
+
+    const { stdout, exitCode } = await runCliAlias(
+      "put",
+      "@number",
+      payloadFile,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("ucas put @object <file> should resolve alias", async () => {
+    await runCliAlias("init");
+
+    const payloadFile = join(testDir, "payload.json");
+    writeFileSync(payloadFile, JSON.stringify({ foo: "bar" }));
+
+    const { stdout, exitCode } = await runCliAlias(
+      "put",
+      "@object",
+      payloadFile,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("ucas put @invalid <file> should fail", async () => {
+    await runCliAlias("init");
+
+    const payloadFile = join(testDir, "payload.json");
+    writeFileSync(payloadFile, "{}");
+
+    const { stderr, exitCode } = await runCliAlias(
+      "put",
+      "@invalid",
+      payloadFile,
+    );
+
+    expect(exitCode).not.toBe(0);
+    expect(stderr.length).toBeGreaterThan(0);
+  });
+
+  test("ucas put @schema with nested type constraints should succeed", async () => {
+    await runCliAlias("init");
+
+    const schemaFile = join(testDir, "constrained-schema.json");
+    writeFileSync(
+      schemaFile,
+      JSON.stringify({
+        type: "object",
+        properties: {
+          name: { type: "string", minLength: 1, maxLength: 50 },
+          age: { type: "number", minimum: 0, maximum: 150 },
+          tags: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 1,
+            uniqueItems: true,
+          },
+        },
+        required: ["name"],
+      }),
+    );
+
+    const { stdout, stderr, exitCode } = await runCliAlias(
+      "put",
+      "@schema",
+      schemaFile,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stderr).toBe("");
+    expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+});
+
+describe("@ Alias Resolution - hash", () => {
+  test("ucas hash @string <file> should compute hash without storing", async () => {
+    await runCliAlias("init");
+
+    const payloadFile = join(testDir, "payload.json");
+    writeFileSync(payloadFile, JSON.stringify("test"));
+
+    const { stdout, stderr, exitCode } = await runCliAlias(
+      "hash",
+      "@string",
+      payloadFile,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stderr).toBe("");
+    expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+});

packages/cli-json-cas/tests/edge-cases.test.ts

@@ -0,0 +1,436 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { envValue, stripVolatile } from "./helpers";
+
+const entrypoint = resolve(import.meta.dir, "../src/index.ts");
+const pkgPath = resolve(import.meta.dir, "../package.json");
+
+// --- ucas command alias tests (from cli.test.ts) ---
+
+describe("ucas command alias", () => {
+  test("T1: ucas bin entry exists in package.json", async () => {
+    const pkg = await Bun.file(pkgPath).json();
+    expect(pkg.bin.ucas).toBe("./src/index.ts");
+  });
+
+  test("T2: json-cas bin entry is preserved in package.json", async () => {
+    const pkg = await Bun.file(pkgPath).json();
+    expect(pkg.bin["json-cas"]).toBe("./src/index.ts");
+  });
+
+  test("T3: ucas command is executable and shows help", async () => {
+    const proc = Bun.spawn(["bun", entrypoint, "--help"], {
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    const exitCode = await proc.exited;
+    const stdout = await new Response(proc.stdout).text();
+    expect(exitCode).toBe(0);
+    expect(stdout.length).toBeGreaterThan(0);
+  });
+
+  test("T4: both commands point to the same entrypoint", async () => {
+    const pkg = await Bun.file(pkgPath).json();
+    expect(pkg.bin.ucas).toBe(pkg.bin["json-cas"]);
+  });
+});
+
+// --- e2e Phase 7: Edge Cases ---
+
+describe("Phase 7: Edge Cases", () => {
+  let tmpStore: string;
+  let varDbPath: string;
+  let typeHash: string;
+  let nodeHash: string;
+
+  async function runCli(
+    args: string[],
+  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    const proc = Bun.spawn(
+      ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const exitCode = await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    return { stdout, stderr, exitCode };
+  }
+
+  beforeAll(async () => {
+    tmpStore = mkdtempSync(join(tmpdir(), "json-cas-e2e-"));
+    varDbPath = join(tmpStore, "variables.db");
+
+    const schemaFile = join(tmpStore, "test-schema.json");
+    writeFileSync(
+      schemaFile,
+      JSON.stringify({
+        type: "object",
+        properties: { name: { type: "string" }, age: { type: "number" } },
+        required: ["name"],
+        additionalProperties: false,
+      }),
+    );
+    const { openStore: openFsStore } = await import("@uncaged/json-cas-fs");
+    const { putSchema } = await import("@uncaged/json-cas");
+    const store = await openFsStore(tmpStore);
+    typeHash = await putSchema(
+      store,
+      JSON.parse(readFileSync(schemaFile, "utf-8")),
+    );
+
+    const nodeFile = join(tmpStore, "test-node.json");
+    writeFileSync(nodeFile, JSON.stringify({ name: "Alice", age: 30 }));
+    const { stdout } = await runCli(["put", typeHash, nodeFile]);
+    nodeHash = envValue(stdout) as string;
+  });
+
+  afterAll(() => {
+    rmSync(tmpStore, { recursive: true, force: true });
+  });
+
+  test("7.1 get non-existent hash errors gracefully", async () => {
+    const { stderr, exitCode } = await runCli(["get", "AAAAAAAAAAAAA"]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toMatchSnapshot();
+  });
+
+  test("7.2 put with non-existent file errors with ENOENT", async () => {
+    const { stderr, exitCode } = await runCli([
+      "put",
+      typeHash,
+      "/nonexistent/file.json",
+    ]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("ENOENT");
+  });
+
+  test("7.3 var set empty name errors", async () => {
+    const { stderr, exitCode } = await runCli(["var", "set", "", nodeHash]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr.length).toBeGreaterThan(0);
+    expect(stderr).toMatchSnapshot();
+  });
+
+  test("7.4 var set name with invalid chars errors", async () => {
+    const { stderr, exitCode } = await runCli([
+      "var",
+      "set",
+      "invalid name!",
+      nodeHash,
+    ]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr.length).toBeGreaterThan(0);
+    expect(stderr).toMatchSnapshot();
+  });
+
+  test("7.5 no subcommand shows help text", async () => {
+    const { stdout, stderr, exitCode: _exitCode } = await runCli([]);
+    const combined = stdout + stderr;
+    expect(combined.length).toBeGreaterThan(0);
+    expect(combined).toMatchSnapshot();
+    expect(combined.toLowerCase()).toContain("usage");
+  });
+
+  test("7.6 --store path is a file errors", async () => {
+    const fileAsStore = join(tmpStore, "not-a-directory");
+    writeFileSync(fileAsStore, "test");
+    const proc = Bun.spawn(
+      [
+        "bun",
+        entrypoint,
+        "--store",
+        fileAsStore,
+        "--var-db",
+        varDbPath,
+        "get",
+        "AAAAAAAAAAAAA",
+      ],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const exitCode = await proc.exited;
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("not a directory");
+  });
+});
+
+// --- e2e Phase 3: Variable System (edge cases from e2e.test.ts) ---
+
+describe("Phase 3: Variable System", () => {
+  let tmpStore: string;
+  let varDbPath: string;
+  let typeHash: string;
+  let nodeHash: string;
+
+  async function runCli(
+    args: string[],
+  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    const proc = Bun.spawn(
+      ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const exitCode = await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    return { stdout, stderr, exitCode };
+  }
+
+  beforeAll(async () => {
+    tmpStore = mkdtempSync(join(tmpdir(), "json-cas-e2e-"));
+    varDbPath = join(tmpStore, "variables.db");
+
+    const schemaFile = join(tmpStore, "test-schema.json");
+    writeFileSync(
+      schemaFile,
+      JSON.stringify({
+        type: "object",
+        properties: { name: { type: "string" }, age: { type: "number" } },
+        required: ["name"],
+        additionalProperties: false,
+      }),
+    );
+    const { openStore: openFsStore } = await import("@uncaged/json-cas-fs");
+    const { putSchema } = await import("@uncaged/json-cas");
+    const store = await openFsStore(tmpStore);
+    typeHash = await putSchema(
+      store,
+      JSON.parse(readFileSync(schemaFile, "utf-8")),
+    );
+
+    const nodeFile = join(tmpStore, "test-node.json");
+    writeFileSync(nodeFile, JSON.stringify({ name: "Alice", age: 30 }));
+    const { stdout } = await runCli(["put", typeHash, nodeFile]);
+    nodeHash = envValue(stdout) as string;
+  });
+
+  afterAll(() => {
+    rmSync(tmpStore, { recursive: true, force: true });
+  });
+
+  test("3.1 var set creates variable", async () => {
+    const { exitCode, stdout } = await runCli([
+      "var",
+      "set",
+      "myapp/config",
+      nodeHash,
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("3.2 var get returns variable", async () => {
+    const { stdout, exitCode } = await runCli([
+      "var",
+      "get",
+      "myapp/config",
+      "--schema",
+      typeHash,
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+    expect(stdout).toContain(nodeHash);
+  });
+
+  test("3.3 var list shows all variables", async () => {
+    const { stdout, exitCode } = await runCli(["var", "list"]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+    expect(stdout).toContain("myapp/config");
+  });
+
+  test("3.4 var list prefix filters by prefix", async () => {
+    const { stdout, exitCode } = await runCli(["var", "list", "myapp/"]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+    expect(stdout).toContain("myapp/config");
+  });
+
+  test("3.5 var set upsert updates existing variable", async () => {
+    const node2File = join(tmpStore, "node2.json");
+    writeFileSync(node2File, JSON.stringify({ name: "Bob", age: 25 }));
+    const { stdout: node2Out } = await runCli(["put", typeHash, node2File]);
+    const node2Hash = envValue(node2Out) as string;
+    const { exitCode, stdout } = await runCli([
+      "var",
+      "set",
+      "myapp/config",
+      node2Hash,
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+    // Restore original value
+    await runCli(["var", "set", "myapp/config", nodeHash]);
+  });
+
+  test("3.6 var tag adds kv tag and label", async () => {
+    const { exitCode, stdout } = await runCli([
+      "var",
+      "tag",
+      "myapp/config",
+      "--schema",
+      typeHash,
+      "env:prod",
+      "important",
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("3.7 var list --tag env:prod filters by kv tag", async () => {
+    const { stdout, exitCode } = await runCli([
+      "var",
+      "list",
+      "--tag",
+      "env:prod",
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("myapp/config");
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("3.8 var list --tag important filters by label", async () => {
+    const { stdout, exitCode } = await runCli([
+      "var",
+      "list",
+      "--tag",
+      "important",
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("myapp/config");
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("3.9 var tag remove deletes label", async () => {
+    const { exitCode, stdout } = await runCli([
+      "var",
+      "tag",
+      "myapp/config",
+      "--schema",
+      typeHash,
+      ":important",
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+    // Verify label is gone
+    const { stdout: listOut } = await runCli([
+      "var",
+      "list",
+      "--tag",
+      "important",
+    ]);
+    expect(listOut).not.toContain("myapp/config");
+  });
+
+  test("3.10 var delete removes variable", async () => {
+    const { exitCode, stdout } = await runCli([
+      "var",
+      "delete",
+      "myapp/config",
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("3.11 var get deleted variable returns not found", async () => {
+    const { stderr, exitCode } = await runCli([
+      "var",
+      "get",
+      "myapp/config",
+      "--schema",
+      typeHash,
+    ]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toMatchSnapshot();
+  });
+});
+
+// --- e2e Phase 4: Template System ---
+
+describe("Phase 4: Template System", () => {
+  let tmpStore: string;
+  let varDbPath: string;
+  let typeHash: string;
+
+  async function runCli(
+    args: string[],
+  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    const proc = Bun.spawn(
+      ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const exitCode = await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    return { stdout, stderr, exitCode };
+  }
+
+  beforeAll(async () => {
+    tmpStore = mkdtempSync(join(tmpdir(), "json-cas-e2e-"));
+    varDbPath = join(tmpStore, "variables.db");
+
+    const schemaFile = join(tmpStore, "test-schema.json");
+    writeFileSync(
+      schemaFile,
+      JSON.stringify({
+        type: "object",
+        properties: { name: { type: "string" }, age: { type: "number" } },
+        required: ["name"],
+        additionalProperties: false,
+      }),
+    );
+    const { openStore: openFsStore } = await import("@uncaged/json-cas-fs");
+    const { putSchema } = await import("@uncaged/json-cas");
+    const store = await openFsStore(tmpStore);
+    typeHash = await putSchema(
+      store,
+      JSON.parse(readFileSync(schemaFile, "utf-8")),
+    );
+  });
+
+  afterAll(() => {
+    rmSync(tmpStore, { recursive: true, force: true });
+  });
+
+  test("4.1 template set registers template", async () => {
+    const tmplFile = join(tmpStore, "test.liquid");
+    writeFileSync(tmplFile, "Name: {{ payload.name }}, Age: {{ payload.age }}");
+    const { exitCode, stdout } = await runCli([
+      "template",
+      "set",
+      typeHash,
+      tmplFile,
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("4.2 template get returns template text", async () => {
+    const { stdout, exitCode } = await runCli(["template", "get", typeHash]);
+    expect(exitCode).toBe(0);
+    expect(envValue(stdout)).toBe(
+      "Name: {{ payload.name }}, Age: {{ payload.age }}",
+    );
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("4.3 template list shows registered templates", async () => {
+    const { stdout, exitCode } = await runCli(["template", "list"]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain(typeHash);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("4.4 template delete removes template", async () => {
+    const { exitCode, stdout } = await runCli(["template", "delete", typeHash]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("4.5 template get deleted template returns not found", async () => {
+    const { stderr, exitCode } = await runCli(["template", "get", typeHash]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toMatchSnapshot();
+  });
+});

packages/cli-json-cas/tests/gc.test.ts

@@ -0,0 +1,125 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { envValue } from "./helpers";
+
+const entrypoint = resolve(import.meta.dir, "../src/index.ts");
+
+let tmpStore: string;
+let varDbPath: string;
+let typeHash: string;
+let nodeHash: string;
+
+beforeAll(async () => {
+  tmpStore = mkdtempSync(join(tmpdir(), "json-cas-e2e-"));
+  varDbPath = join(tmpStore, "variables.db");
+
+  const schemaFile = join(tmpStore, "test-schema.json");
+  writeFileSync(
+    schemaFile,
+    JSON.stringify({
+      type: "object",
+      properties: { name: { type: "string" }, age: { type: "number" } },
+      required: ["name"],
+      additionalProperties: false,
+    }),
+  );
+  const { openStore: openFsStore } = await import("@uncaged/json-cas-fs");
+  const { putSchema } = await import("@uncaged/json-cas");
+  const store = await openFsStore(tmpStore);
+  typeHash = await putSchema(
+    store,
+    JSON.parse(readFileSync(schemaFile, "utf-8")),
+  );
+
+  const nodeFile = join(tmpStore, "test-node.json");
+  writeFileSync(nodeFile, JSON.stringify({ name: "Alice", age: 30 }));
+  const { stdout } = await runCli(["put", typeHash, nodeFile]);
+  nodeHash = envValue(stdout) as string;
+
+  // Set a var referencing the node so it survives GC
+  await runCli(["var", "set", "gc-test/ref", nodeHash]);
+});
+
+afterAll(() => {
+  rmSync(tmpStore, { recursive: true, force: true });
+});
+
+async function runCli(
+  args: string[],
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(
+    ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const exitCode = await proc.exited;
+  const stdout = (await new Response(proc.stdout).text()).trim();
+  const stderr = (await new Response(proc.stderr).text()).trim();
+  return { stdout, stderr, exitCode };
+}
+
+// ---- Phase 6: GC ----
+
+describe("Phase 6: GC", () => {
+  test("6.1 gc runs without error", async () => {
+    const { exitCode, stdout } = await runCli(["gc"]);
+    expect(exitCode).toBe(0);
+    // Assert structural shape only — exact counts depend on phase history
+    const result = envValue(stdout) as Record<string, unknown>;
+    expect(typeof result.total).toBe("number");
+    expect(typeof result.reachable).toBe("number");
+    expect(typeof result.collected).toBe("number");
+    expect(typeof result.scanned).toBe("number");
+    expect(result.total as number).toBeGreaterThanOrEqual(
+      result.reachable as number,
+    );
+  });
+
+  test("6.2 gc | render -p renders the gc stats", async () => {
+    const { stdout: gcOut, exitCode: gcExit } = await runCli(["gc"]);
+    expect(gcExit).toBe(0);
+
+    const proc = Bun.spawn(
+      [
+        "bun",
+        entrypoint,
+        "--store",
+        tmpStore,
+        "--var-db",
+        varDbPath,
+        "render",
+        "--pipe",
+      ],
+      { stdin: "pipe", stdout: "pipe", stderr: "pipe" },
+    );
+    proc.stdin.write(gcOut);
+    proc.stdin.end();
+    const exitCode = await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    expect(exitCode).toBe(0);
+    // gc value is an object { total, reachable, collected, scanned }
+    expect(stdout).toContain("total:");
+  });
+
+  test("6.3 gc preserves node referenced by a var", async () => {
+    const { exitCode } = await runCli(["gc"]);
+    expect(exitCode).toBe(0);
+    const { stdout } = await runCli(["has", nodeHash]);
+    expect(envValue(stdout)).toBe(true);
+  });
+
+  test("6.4 gc reclaims orphan node", async () => {
+    const orphanFile = join(tmpStore, "orphan.json");
+    writeFileSync(orphanFile, JSON.stringify({ name: "Orphan", age: 99 }));
+    const { stdout: orphanOut } = await runCli(["put", typeHash, orphanFile]);
+    const orphanHash = envValue(orphanOut) as string;
+
+    const { stdout: beforeGc } = await runCli(["has", orphanHash]);
+    expect(envValue(beforeGc)).toBe(true);
+
+    await runCli(["gc"]);
+    const { stdout: afterGc } = await runCli(["has", orphanHash]);
+    expect(envValue(afterGc)).toBe(false);
+  });
+});

packages/cli-json-cas/tests/helpers.ts

@@ -0,0 +1,107 @@
+import {
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import type { JSONSchema } from "@uncaged/json-cas";
+import { putSchema } from "@uncaged/json-cas";
+import { openStore as openFsStore } from "@uncaged/json-cas-fs";
+
+export {
+  join,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  resolve,
+  rmSync,
+  tmpdir,
+  writeFileSync,
+};
+
+export const entrypoint = resolve(import.meta.dir, "../src/index.ts");
+export const pkgPath = resolve(import.meta.dir, "../package.json");
+
+/** Extract the `value` field from a { type, value } envelope JSON string. */
+export function envValue(json: string): unknown {
+  return (JSON.parse(json.trim()) as { value: unknown }).value;
+}
+
+/**
+ * Register a schema directly via the library (CLI schema put was removed).
+ * Returns the type hash.
+ */
+export async function putSchemaFile(
+  storePath: string,
+  schemaFilePath: string,
+): Promise<string> {
+  const store = await openFsStore(storePath);
+  const schema = JSON.parse(
+    readFileSync(schemaFilePath, "utf-8"),
+  ) as JSONSchema;
+  const hash = await putSchema(store, schema);
+  return hash;
+}
+
+/**
+ * Run CLI command. Accepts either a string[] or ...string[] (rest args).
+ * If first arg is an array, uses that as args. Otherwise treats all args as the command.
+ */
+export async function runCli(
+  args: string[],
+  storePath?: string,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const finalArgs = storePath
+    ? ["bun", entrypoint, "--store", storePath, ...args]
+    : ["bun", entrypoint, ...args];
+  const proc = Bun.spawn(finalArgs, {
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const exitCode = await proc.exited;
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  return { stdout, stderr, exitCode };
+}
+
+export async function runCliWithStdin(
+  args: string[],
+  storePath: string,
+  stdin: string,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const finalArgs = ["bun", entrypoint, "--store", storePath, ...args];
+  const proc = Bun.spawn(finalArgs, {
+    stdout: "pipe",
+    stderr: "pipe",
+    stdin: "pipe",
+  });
+  proc.stdin.write(stdin);
+  proc.stdin.end();
+  const exitCode = await proc.exited;
+  const stdout = await new Response(proc.stdout).text();
+  const stderr = await new Response(proc.stderr).text();
+  return { stdout, stderr, exitCode };
+}
+
+/**
+ * Parse JSON and strip volatile fields (timestamp, created, updated)
+ * so snapshots are stable across runs.
+ */
+export function stripVolatile(json: string): unknown {
+  const strip = (v: unknown): unknown => {
+    if (Array.isArray(v)) return v.map(strip);
+    if (v !== null && typeof v === "object") {
+      const out: Record<string, unknown> = {};
+      for (const [k, val] of Object.entries(v as Record<string, unknown>)) {
+        if (k === "timestamp" || k === "created" || k === "updated") continue;
+        out[k] = strip(val);
+      }
+      return out;
+    }
+    return v;
+  };
+  return strip(JSON.parse(json));
+}

packages/cli-json-cas/tests/list-meta-schema.test.ts

@@ -0,0 +1,156 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BOOTSTRAP_STORE } from "@uncaged/json-cas";
+import { openStore as openFsStore } from "@uncaged/json-cas-fs";
+import { envValue, runCli } from "./helpers.js";
+
+let storePath: string;
+
+beforeEach(() => {
+  storePath = mkdtempSync(join(tmpdir(), "json-cas-list-meta-schema-"));
+  mkdirSync(storePath, { recursive: true });
+});
+
+afterEach(() => {
+  rmSync(storePath, { recursive: true, force: true });
+});
+
+describe("list-meta CLI command", () => {
+  test("E1. list-meta on bootstrapped store contains exactly the meta-schema hash", async () => {
+    // First, get @schema hash by calling has on it (also triggers bootstrap)
+    const { stdout: hashOut, exitCode: hashCode } = await runCli(
+      ["hash", "@schema", "--pipe"],
+      storePath,
+    );
+    // ensure bootstrap by running a no-op command:
+    void hashOut;
+    void hashCode;
+
+    // Bootstrap fully via 'list --type @schema'
+    const { stdout: schemaListOut } = await runCli(
+      ["list", "--type", "@schema"],
+      storePath,
+    );
+    const schemaList = envValue(schemaListOut) as string[];
+    expect(Array.isArray(schemaList)).toBe(true);
+
+    const { stdout, stderr, exitCode } = await runCli(["list-meta"], storePath);
+    expect(exitCode).toBe(0);
+    expect(stderr).toBe("");
+
+    const parsed = JSON.parse(stdout) as { type: string; value: string[] };
+    expect(parsed.type).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    expect(Array.isArray(parsed.value)).toBe(true);
+    expect(parsed.value).toHaveLength(1);
+    expect(parsed.value[0]).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("E1. --json flag yields compact JSON", async () => {
+    const { stdout, exitCode } = await runCli(
+      ["--json", "list-meta"],
+      storePath,
+    );
+    expect(exitCode).toBe(0);
+    // compact = no newlines/spaces between fields
+    expect(stdout.trim()).not.toContain("\n  ");
+  });
+});
+
+describe("list-schema CLI command", () => {
+  test("E2. list-schema on bootstrapped store includes meta-schema and built-ins", async () => {
+    const { stdout, stderr, exitCode } = await runCli(
+      ["list-schema"],
+      storePath,
+    );
+    expect(exitCode).toBe(0);
+    expect(stderr).toBe("");
+
+    const parsed = JSON.parse(stdout) as { type: string; value: string[] };
+    expect(parsed.type).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    expect(Array.isArray(parsed.value)).toBe(true);
+    // meta + 5 primitive + 20 output = 26
+    expect(parsed.value.length).toBeGreaterThanOrEqual(6);
+  });
+});
+
+describe("usage help", () => {
+  test("E3. printing usage includes list-meta and list-schema lines", async () => {
+    const { stdout, exitCode } = await runCli([], storePath);
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("list-meta");
+    expect(stdout).toContain("list-schema");
+  });
+});
+
+describe("F1. output schemas registered", () => {
+  test("@output/list-meta and @output/list-schema schemas exist", async () => {
+    const { stdout, exitCode } = await runCli(["list-meta"], storePath);
+    expect(exitCode).toBe(0);
+    const parsed = JSON.parse(stdout) as { type: string };
+    // type hash references the @output/list-meta schema, must be retrievable
+    const { stdout: getOut, exitCode: getCode } = await runCli(
+      ["get", parsed.type],
+      storePath,
+    );
+    expect(getCode).toBe(0);
+    const node = envValue(getOut) as {
+      payload: { title?: string };
+    };
+    expect(node.payload.title).toBe("ucas list-meta result");
+
+    const { stdout: schemaOut } = await runCli(["list-schema"], storePath);
+    const schemaParsed = JSON.parse(schemaOut) as { type: string };
+    const { stdout: getSchOut, exitCode: getSchCode } = await runCli(
+      ["get", schemaParsed.type],
+      storePath,
+    );
+    expect(getSchCode).toBe(0);
+    const schNode = envValue(getSchOut) as {
+      payload: { title?: string };
+    };
+    expect(schNode.payload.title).toBe("ucas list-schema result");
+  });
+});
+
+describe("E4. list-schema vs list --type with multiple meta-schema versions", () => {
+  test("list-schema includes schemas typed by older meta-schemas; list --type @schema does not", async () => {
+    // Set up two distinct meta-schemas via the library
+    const store = await openFsStore(storePath);
+    const m1 = await store[BOOTSTRAP_STORE]({
+      type: "object",
+      title: "meta-v1",
+    });
+    const m2 = await store[BOOTSTRAP_STORE]({
+      type: "object",
+      title: "meta-v2",
+    });
+    // schema typed by older meta M1
+    const sM1 = await store.put(m1, { type: "string" });
+    expect(m1).not.toBe(m2);
+
+    // CLI: list-schema must include sM1
+    const { stdout: lsOut, exitCode: lsCode } = await runCli(
+      ["list-schema"],
+      storePath,
+    );
+    expect(lsCode).toBe(0);
+    const lsValue = envValue(lsOut) as string[];
+    expect(lsValue).toContain(sM1);
+    expect(lsValue).toContain(m1);
+    expect(lsValue).toContain(m2);
+
+    // CLI: list --type <M2 hash> must NOT include sM1
+    const { stdout: ltOut, exitCode: ltCode } = await runCli(
+      ["list", "--type", m2],
+      storePath,
+    );
+    expect(ltCode).toBe(0);
+    const ltValue = envValue(ltOut) as string[];
+    expect(ltValue).not.toContain(sM1);
+
+    // list-schema.value.length > list --type <newest>.value.length
+    expect(lsValue.length).toBeGreaterThan(ltValue.length);
+  });
+});

packages/cli-json-cas/tests/pipe.test.ts

@@ -0,0 +1,214 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { envValue, stripVolatile } from "./helpers";
+
+const entrypoint = resolve(import.meta.dir, "../src/index.ts");
+
+let tmpStore: string;
+let varDbPath: string;
+let typeHash: string;
+let nodeHash: string;
+
+beforeAll(async () => {
+  tmpStore = mkdtempSync(join(tmpdir(), "json-cas-e2e-"));
+  varDbPath = join(tmpStore, "variables.db");
+
+  const schemaFile = join(tmpStore, "test-schema.json");
+  writeFileSync(
+    schemaFile,
+    JSON.stringify({
+      type: "object",
+      properties: { name: { type: "string" }, age: { type: "number" } },
+      required: ["name"],
+      additionalProperties: false,
+    }),
+  );
+  const { openStore: openFsStore } = await import("@uncaged/json-cas-fs");
+  const { putSchema } = await import("@uncaged/json-cas");
+  const store = await openFsStore(tmpStore);
+  typeHash = await putSchema(
+    store,
+    JSON.parse(readFileSync(schemaFile, "utf-8")),
+  );
+
+  const nodeFile = join(tmpStore, "test-node.json");
+  writeFileSync(nodeFile, JSON.stringify({ name: "Alice", age: 30 }));
+  const { stdout } = await runCli(["put", typeHash, nodeFile]);
+  nodeHash = envValue(stdout) as string;
+
+  // Set up template for render tests
+  const tmplFile = join(tmpStore, "render-template.liquid");
+  writeFileSync(tmplFile, "Hello {{ payload.name }}!");
+  await runCli(["template", "set", typeHash, tmplFile]);
+});
+
+afterAll(() => {
+  rmSync(tmpStore, { recursive: true, force: true });
+});
+
+async function runCli(
+  args: string[],
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(
+    ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const exitCode = await proc.exited;
+  const stdout = (await new Response(proc.stdout).text()).trim();
+  const stderr = (await new Response(proc.stderr).text()).trim();
+  return { stdout, stderr, exitCode };
+}
+
+async function runCliWithStdin(
+  args: string[],
+  stdin: string,
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(
+    ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+    { stdin: "pipe", stdout: "pipe", stderr: "pipe" },
+  );
+  proc.stdin.write(stdin);
+  proc.stdin.end();
+  const exitCode = await proc.exited;
+  const stdout = (await new Response(proc.stdout).text()).trim();
+  const stderr = (await new Response(proc.stderr).text()).trim();
+  return { stdout, stderr, exitCode };
+}
+
+// ---- Phase 8: Pipe Composition ----
+
+describe("Phase 8: Pipe Composition", () => {
+  test("8.1 put | render -p expands the stored hash to its content", async () => {
+    const nodeFile = join(tmpStore, "pipe-node.json");
+    writeFileSync(nodeFile, JSON.stringify({ name: "Bob", age: 42 }));
+
+    const { stdout: putOut, exitCode: putExit } = await runCli([
+      "put",
+      typeHash,
+      nodeFile,
+    ]);
+    expect(putExit).toBe(0);
+
+    // The put envelope value is a cas_ref hash; render -p dereferences it and
+    // renders the stored node's payload.
+    const { stdout, exitCode } = await runCliWithStdin(
+      ["render", "--pipe"],
+      putOut,
+    );
+    expect(exitCode).toBe(0);
+    expect(stdout).toContain("Bob");
+  });
+
+  test("8.3 list --type @schema emits a parseable envelope of hashes", async () => {
+    const { stdout, exitCode } = await runCli(["list", "--type", "@schema"]);
+    expect(exitCode).toBe(0);
+
+    // Downstream consumers (jq, etc.) read the `value` array of hashes.
+    const value = envValue(stdout) as string[];
+    expect(Array.isArray(value)).toBe(true);
+    for (const hash of value) {
+      expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    }
+  });
+
+  test("8.4 list --type @schema | render -p expands the schema list", async () => {
+    const { stdout: listOut } = await runCli(["list", "--type", "@schema"]);
+    // list result items are cas_ref hashes; render -p dereferences each one
+    // and renders the schema contents.
+    const { stdout, exitCode } = await runCliWithStdin(
+      ["render", "--pipe"],
+      listOut,
+    );
+    expect(exitCode).toBe(0);
+    expect(stdout.length).toBeGreaterThan(0);
+  });
+
+  test("8.5 render <hash> uses a registered template", async () => {
+    // Register a template for the schema, then render a fresh node by hash.
+    const tmplFile = join(tmpStore, "pipe-render.liquid");
+    writeFileSync(tmplFile, "Person: {{ payload.name }} ({{ payload.age }})");
+    const { exitCode: setExit } = await runCli([
+      "template",
+      "set",
+      typeHash,
+      tmplFile,
+    ]);
+    expect(setExit).toBe(0);
+
+    const nodeFile = join(tmpStore, "pipe-render-node.json");
+    writeFileSync(nodeFile, JSON.stringify({ name: "Carol", age: 25 }));
+    const { stdout: putOut } = await runCli(["put", typeHash, nodeFile]);
+    const freshHash = envValue(putOut) as string;
+
+    const { stdout, exitCode } = await runCli(["render", freshHash]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe("Person: Carol (25)");
+  });
+});
+
+// ---- Phase 9: Put/Hash Pipe Input ----
+
+describe("Phase 9: Put/Hash Pipe Input", () => {
+  test("9.1 put -p reads JSON from stdin and stores node", async () => {
+    const payload = JSON.stringify({ name: "PipeAlice", age: 99 });
+    const { stdout, exitCode } = await runCliWithStdin(
+      ["put", typeHash, "-p"],
+      payload,
+    );
+    expect(exitCode).toBe(0);
+    const hash = envValue(stdout);
+    expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+
+    // Verify stored correctly
+    const { stdout: getOut } = await runCli(["get", hash as string]);
+    expect(getOut).toContain("PipeAlice");
+  });
+
+  test("9.2 hash -p reads JSON from stdin and computes hash without storing", async () => {
+    const payload = JSON.stringify({ name: "PipeBob", age: 55 });
+    const { stdout, exitCode } = await runCliWithStdin(
+      ["hash", typeHash, "-p"],
+      payload,
+    );
+    expect(exitCode).toBe(0);
+    const hash = envValue(stdout);
+    expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+
+    // Should NOT be stored
+    const { exitCode: hasExit, stdout: hasOut } = await runCli([
+      "has",
+      hash as string,
+    ]);
+    expect(hasExit).toBe(0);
+    expect(envValue(hasOut)).toBe(false);
+  });
+
+  test("9.3 put -p with file arg errors", async () => {
+    const { stderr, exitCode } = await runCliWithStdin(
+      ["put", typeHash, "some-file.json", "-p"],
+      "{}",
+    );
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("Cannot use --pipe/-p with a file argument");
+  });
+
+  test("9.4 put -p with empty stdin errors", async () => {
+    const { stderr, exitCode } = await runCliWithStdin(
+      ["put", typeHash, "-p"],
+      "",
+    );
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("No input on stdin");
+  });
+
+  test("9.5 put -p with invalid JSON errors", async () => {
+    const { stderr, exitCode } = await runCliWithStdin(
+      ["put", typeHash, "-p"],
+      "not json",
+    );
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("Invalid JSON on stdin");
+  });
+});

packages/cli-json-cas/tests/put-get-has.test.ts

@@ -0,0 +1,101 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { envValue, stripVolatile } from "./helpers";
+
+const entrypoint = resolve(import.meta.dir, "../src/index.ts");
+
+let tmpStore: string;
+let varDbPath: string;
+let typeHash: string;
+let nodeHash: string;
+
+beforeAll(async () => {
+  tmpStore = mkdtempSync(join(tmpdir(), "json-cas-e2e-"));
+  varDbPath = join(tmpStore, "variables.db");
+
+  const schemaFile = join(tmpStore, "test-schema.json");
+  writeFileSync(
+    schemaFile,
+    JSON.stringify({
+      type: "object",
+      properties: {
+        name: { type: "string" },
+        age: { type: "number" },
+      },
+      required: ["name"],
+      additionalProperties: false,
+    }),
+  );
+  const { openStore: openFsStore } = await import("@uncaged/json-cas-fs");
+  const { putSchema } = await import("@uncaged/json-cas");
+  const store = await openFsStore(tmpStore);
+  typeHash = await putSchema(
+    store,
+    JSON.parse(readFileSync(schemaFile, "utf-8")),
+  );
+
+  const nodeFile = join(tmpStore, "test-node.json");
+  writeFileSync(nodeFile, JSON.stringify({ name: "Alice", age: 30 }));
+  const { stdout } = await runCli(["put", typeHash, nodeFile]);
+  nodeHash = envValue(stdout) as string;
+});
+
+afterAll(() => {
+  rmSync(tmpStore, { recursive: true, force: true });
+});
+
+async function runCli(
+  args: string[],
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(
+    ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const exitCode = await proc.exited;
+  const stdout = (await new Response(proc.stdout).text()).trim();
+  const stderr = (await new Response(proc.stderr).text()).trim();
+  return { stdout, stderr, exitCode };
+}
+
+describe("Phase 1: CAS Core", () => {
+  test("1.1 init + put with @object bootstraps store", async () => {
+    expect(typeHash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("1.5 put returns node hash", async () => {
+    expect(nodeHash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("1.6 get returns node JSON (snapshot)", async () => {
+    const { stdout, exitCode } = await runCli(["get", nodeHash]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("1.7 has returns true for existing node", async () => {
+    const { stdout, exitCode } = await runCli(["has", nodeHash]);
+    expect(exitCode).toBe(0);
+    expect(envValue(stdout)).toBe(true);
+  });
+
+  test("1.8 has returns false for non-existing hash", async () => {
+    const { stdout, exitCode } = await runCli(["has", "AAAAAAAAAAAAA"]);
+    expect(exitCode).toBe(0);
+    expect(envValue(stdout)).toBe(false);
+  });
+
+  test("1.12 hash dry-run returns same hash as put", async () => {
+    const nodeFile = join(tmpStore, "test-node.json");
+    const { stdout, exitCode } = await runCli(["hash", typeHash, nodeFile]);
+    expect(exitCode).toBe(0);
+    expect(envValue(stdout)).toBe(nodeHash);
+  });
+
+  test("1.13 list --type returns nodes of that type", async () => {
+    const { stdout, exitCode } = await runCli(["list", "--type", typeHash]);
+    expect(exitCode).toBe(0);
+    expect(envValue(stdout)).toContain(nodeHash);
+  });
+});

packages/cli-json-cas/tests/render.test.ts

@@ -0,0 +1,521 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { bootstrap } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+import { envValue, putSchemaFile, runCli, runCliWithStdin } from "./helpers";
+
+const entrypoint = resolve(import.meta.dir, "../src/index.ts");
+
+// --- Standalone render tests from cli.test.ts ---
+
+describe("ucas render command", () => {
+  test("R1: render requires hash argument", async () => {
+    const { exitCode, stderr } = await runCli(["render"]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("Usage");
+  });
+
+  test("R2: render with missing hash shows error", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+      const { exitCode, stderr } = await runCli(
+        ["render", "ZZZZZZZZZZZZZ"],
+        tmpStore,
+      );
+      // Missing hash should exit with error
+      expect(exitCode).not.toBe(0);
+      expect(stderr).toContain("Node not found");
+      expect(stderr).toContain("ZZZZZZZZZZZZZ");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+
+  test("R3: render with invalid numeric flag fails", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+      const { exitCode, stderr } = await runCli(
+        ["render", "AAAAAAAAAAAAA", "--resolution", "invalid"],
+        tmpStore,
+      );
+      expect(exitCode).not.toBe(0);
+      expect(stderr).toContain("valid number");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+});
+
+// --- e2e Phase 5: Render ---
+
+describe("Phase 5: Render", () => {
+  let tmpStore: string;
+  let varDbPath: string;
+  let typeHash: string;
+  let nodeHash: string;
+
+  async function runCliE2e(
+    args: string[],
+  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    const proc = Bun.spawn(
+      ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const exitCode = await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    return { stdout, stderr, exitCode };
+  }
+
+  async function runCliE2eWithStdin(
+    args: string[],
+    stdin: string,
+  ): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    const proc = Bun.spawn(
+      ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+      { stdin: "pipe", stdout: "pipe", stderr: "pipe" },
+    );
+    proc.stdin.write(stdin);
+    proc.stdin.end();
+    const exitCode = await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    return { stdout, stderr, exitCode };
+  }
+
+  beforeAll(async () => {
+    tmpStore = mkdtempSync(join(tmpdir(), "json-cas-e2e-"));
+    varDbPath = join(tmpStore, "variables.db");
+
+    const schemaFile = join(tmpStore, "test-schema.json");
+    writeFileSync(
+      schemaFile,
+      JSON.stringify({
+        type: "object",
+        properties: { name: { type: "string" }, age: { type: "number" } },
+        required: ["name"],
+        additionalProperties: false,
+      }),
+    );
+    const { openStore: openFsStore } = await import("@uncaged/json-cas-fs");
+    const { putSchema } = await import("@uncaged/json-cas");
+    const store = await openFsStore(tmpStore);
+    typeHash = await putSchema(
+      store,
+      JSON.parse(readFileSync(schemaFile, "utf-8")),
+    );
+
+    const nodeFile = join(tmpStore, "test-node.json");
+    writeFileSync(nodeFile, JSON.stringify({ name: "Alice", age: 30 }));
+    const { stdout } = await runCliE2e(["put", typeHash, nodeFile]);
+    nodeHash = envValue(stdout) as string;
+
+    // Register template for render tests
+    const tmplFile = join(tmpStore, "render-template.liquid");
+    writeFileSync(tmplFile, "Hello {{ payload.name }}!");
+    await runCliE2e(["template", "set", typeHash, tmplFile]);
+  });
+
+  afterAll(() => {
+    rmSync(tmpStore, { recursive: true, force: true });
+  });
+
+  test("5.1 render fills payload variables", async () => {
+    const { stdout, exitCode } = await runCliE2e(["render", nodeHash]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toBe("Hello Alice!");
+    expect(stdout).toMatchSnapshot();
+  });
+
+  test("5.2 render --resolution with different value", async () => {
+    const { stdout, exitCode } = await runCliE2e([
+      "render",
+      nodeHash,
+      "--resolution",
+      "0.5",
+    ]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toMatchSnapshot();
+  });
+
+  test("5.3 render non-existent hash fails with error", async () => {
+    const { stderr, exitCode } = await runCliE2e(["render", "ZZZZZZZZZZZZZ"]);
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toContain("Node not found");
+    expect(stderr).toContain("ZZZZZZZZZZZZZ");
+  });
+});
+
+// --- Suite 6: CLI Integration with Templates (from cli.test.ts) ---
+
+describe("Suite 6: CLI Integration with Templates", () => {
+  test("6.1 CLI with Template (Default Parameters)", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      // Initialize store
+      await runCli(["init"], tmpStore);
+
+      // Create schema
+      const schemaFile = join(tmpStore, "schema.json");
+      writeFileSync(
+        schemaFile,
+        JSON.stringify({
+          type: "object",
+          properties: { name: { type: "string" } },
+        }),
+      );
+      const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+      // Create node
+      const nodeFile = join(tmpStore, "node.json");
+      writeFileSync(nodeFile, JSON.stringify({ name: "Alice" }));
+      const { stdout: nodeOut } = await runCli(
+        ["put", schemaHash.trim(), nodeFile],
+        tmpStore,
+      );
+      const nodeHash = envValue(nodeOut) as string;
+
+      // Create template file (JSON-encoded string)
+      const templateFile = join(tmpStore, "template.json");
+      writeFileSync(templateFile, JSON.stringify("Hello {{ payload.name }}!"));
+      const { stdout: tmplOut } = await runCli(
+        ["put", "@string", templateFile],
+        tmpStore,
+      );
+      const tmplHash = envValue(tmplOut) as string;
+
+      // Register template
+      await runCli(
+        ["var", "set", `@ucas/template/text/${schemaHash.trim()}`, tmplHash],
+        tmpStore,
+      );
+
+      // Render with template
+      const { stdout: output, exitCode } = await runCli(
+        ["render", nodeHash],
+        tmpStore,
+      );
+
+      expect(exitCode).toBe(0);
+      expect(output).toBe("Hello Alice!");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+
+  test("6.2 CLI with Template + Custom Decay", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+
+      // Create schema with child ref
+      const schemaFile = join(tmpStore, "schema.json");
+      writeFileSync(
+        schemaFile,
+        JSON.stringify({
+          type: "object",
+          properties: {
+            value: { type: "string" },
+            child: {
+              anyOf: [{ type: "string", format: "cas_ref" }, { type: "null" }],
+            },
+          },
+        }),
+      );
+      const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+      // Create child node
+      const childFile = join(tmpStore, "child.json");
+      writeFileSync(childFile, JSON.stringify({ value: "child", child: null }));
+      const { stdout: childOut } = await runCli(
+        ["put", schemaHash.trim(), childFile],
+        tmpStore,
+      );
+      const childHash = envValue(childOut) as string;
+
+      // Create parent node
+      const parentFile = join(tmpStore, "parent.json");
+      writeFileSync(
+        parentFile,
+        JSON.stringify({ value: "parent", child: childHash }),
+      );
+      const { stdout: parentOut } = await runCli(
+        ["put", schemaHash.trim(), parentFile],
+        tmpStore,
+      );
+      const parentHash = envValue(parentOut) as string;
+
+      // Create template showing resolution (JSON-encoded string)
+      const templateFile = join(tmpStore, "template.json");
+      writeFileSync(
+        templateFile,
+        JSON.stringify("{{ payload.value }}(res={{ resolution }})"),
+      );
+      const { stdout: tmplOut } = await runCli(
+        ["put", "@string", templateFile],
+        tmpStore,
+      );
+      const tmplHash = envValue(tmplOut) as string;
+
+      // Register template
+      await runCli(
+        ["var", "set", `@ucas/template/text/${schemaHash.trim()}`, tmplHash],
+        tmpStore,
+      );
+
+      // Render with custom decay
+      const { stdout: output, exitCode } = await runCli(
+        ["render", parentHash, "--decay", "0.7"],
+        tmpStore,
+      );
+
+      expect(exitCode).toBe(0);
+      expect(output).toContain("parent(res=1)");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+
+  test("6.3 CLI with Template + All Parameters", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+
+      const schemaFile = join(tmpStore, "schema.json");
+      writeFileSync(
+        schemaFile,
+        JSON.stringify({
+          type: "object",
+          properties: { name: { type: "string" } },
+        }),
+      );
+      const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+      const nodeFile = join(tmpStore, "node.json");
+      writeFileSync(nodeFile, JSON.stringify({ name: "Bob" }));
+      const { stdout: nodeOut } = await runCli(
+        ["put", schemaHash.trim(), nodeFile],
+        tmpStore,
+      );
+      const nodeHash = envValue(nodeOut) as string;
+
+      // Create template (JSON-encoded string)
+      const templateFile = join(tmpStore, "template.json");
+      writeFileSync(
+        templateFile,
+        JSON.stringify("Greetings {{ payload.name }}!"),
+      );
+      const { stdout: tmplOut } = await runCli(
+        ["put", "@string", templateFile],
+        tmpStore,
+      );
+      const tmplHash = envValue(tmplOut) as string;
+
+      await runCli(
+        ["var", "set", `@ucas/template/text/${schemaHash.trim()}`, tmplHash],
+        tmpStore,
+      );
+
+      const { stdout: output, exitCode } = await runCli(
+        [
+          "render",
+          nodeHash,
+          "--resolution",
+          "0.8",
+          "--decay",
+          "0.6",
+          "--epsilon",
+          "0.005",
+        ],
+        tmpStore,
+      );
+
+      expect(exitCode).toBe(0);
+      expect(output).toBe("Greetings Bob!");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+
+  test("6.4 CLI with Non-templated Node (YAML Fallback)", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+
+      const schemaFile = join(tmpStore, "schema.json");
+      writeFileSync(
+        schemaFile,
+        JSON.stringify({
+          type: "object",
+          properties: { name: { type: "string" } },
+        }),
+      );
+      const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+      const nodeFile = join(tmpStore, "node.json");
+      writeFileSync(nodeFile, JSON.stringify({ name: "Charlie" }));
+      const { stdout: nodeOut } = await runCli(
+        ["put", schemaHash.trim(), nodeFile],
+        tmpStore,
+      );
+      const nodeHash = envValue(nodeOut) as string;
+
+      // No template registered - should fall back to YAML
+      const { stdout: output, exitCode } = await runCli(
+        ["render", nodeHash],
+        tmpStore,
+      );
+
+      expect(exitCode).toBe(0);
+      expect(output).toContain("name:");
+      expect(output).toContain("Charlie");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+
+  test("6.5 CLI Error: Invalid Decay Value", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+
+      const schemaFile = join(tmpStore, "schema.json");
+      writeFileSync(
+        schemaFile,
+        JSON.stringify({
+          type: "object",
+          properties: { name: { type: "string" } },
+        }),
+      );
+      const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+      const nodeFile = join(tmpStore, "node.json");
+      writeFileSync(nodeFile, JSON.stringify({ name: "Test" }));
+      const { stdout: nodeOut } = await runCli(
+        ["put", schemaHash.trim(), nodeFile],
+        tmpStore,
+      );
+      const nodeHash = envValue(nodeOut) as string;
+
+      const { exitCode, stderr } = await runCli(
+        ["render", nodeHash, "--decay", "1.5"],
+        tmpStore,
+      );
+
+      expect(exitCode).not.toBe(0);
+      expect(stderr).toContain("decay");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+
+  test("R8: render with non-existent hash exits with error", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+      const { exitCode, stderr, stdout } = await runCli(
+        ["render", "AAAAAAAAAAAAA"],
+        tmpStore,
+      );
+      expect(exitCode).not.toBe(0);
+      expect(stderr).toContain("Node not found");
+      expect(stderr).toContain("AAAAAAAAAAAAA");
+      expect(stdout).toBe("");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+
+  test("R9: render with valid hash exits successfully", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+
+      // Get @string type hash via bootstrap
+      const store = createFsStore(tmpStore);
+      const types = await bootstrap(store);
+      const stringType = types["@string"];
+
+      // Create and store a simple string node
+      const nodeFile = join(tmpStore, "test.json");
+      writeFileSync(nodeFile, JSON.stringify("hello world"));
+      const { stdout: nodeOut } = await runCli(
+        ["put", stringType, nodeFile],
+        tmpStore,
+      );
+      const nodeHash = envValue(nodeOut) as string;
+
+      // Render the valid hash
+      const { exitCode, stdout, stderr } = await runCli(
+        ["render", nodeHash],
+        tmpStore,
+      );
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain("hello world");
+      expect(stderr).toBe("");
+      expect(stdout).not.toContain("Error");
+      expect(stdout).not.toContain("Node not found");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+
+  test("R10: render --pipe with valid envelope succeeds", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+
+      // Get @string type hash via bootstrap
+      const store = createFsStore(tmpStore);
+      const types = await bootstrap(store);
+      const stringType = types["@string"];
+
+      // Create envelope and pipe to render
+      const envelope = JSON.stringify({ type: stringType, value: "test" });
+      const { exitCode, stdout, stderr } = await runCliWithStdin(
+        ["render", "--pipe"],
+        tmpStore,
+        envelope,
+      );
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain("test");
+      expect(stderr).toBe("");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+
+  test("R11: render --pipe with invalid type hash still renders", async () => {
+    const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+    try {
+      await runCli(["init"], tmpStore);
+
+      // Use invalid type hash in envelope
+      const envelope = JSON.stringify({
+        type: "ZZZZZZZZZZZZZ",
+        value: "test",
+      });
+      const { exitCode, stdout, stderr } = await runCliWithStdin(
+        ["render", "--pipe"],
+        tmpStore,
+        envelope,
+      );
+
+      expect(exitCode).toBe(0);
+      expect(stdout).toContain("test");
+      expect(stderr).toBe("");
+    } finally {
+      rmSync(tmpStore, { recursive: true, force: true });
+    }
+  });
+});
+
+// Store validation tests removed - with auto-bootstrap in Phase 1a,
+// stores are automatically created and bootstrapped when opened.
+// Issue #55 validation is no longer applicable.

packages/cli-json-cas/tests/schema-validation.test.ts

@@ -0,0 +1,659 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { envValue, putSchemaFile, runCli } from "./helpers";
+
+// ---- Issue #50: Schema Validation in put Command ----
+
+describe("Issue #50: Schema Validation in put", () => {
+  describe("Test Group 1: Valid Data (Regression Tests)", () => {
+    test("T1.1: Valid data matching schema should be accepted", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Create schema with required name property
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: { name: { type: "string" } },
+            required: ["name"],
+            additionalProperties: false,
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Create valid payload
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({ name: "test" }));
+
+        const { stdout, stderr, exitCode } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).toBe(0);
+        expect(stderr).toBe("");
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+
+        // Verify node was stored
+        const hash = envValue(stdout) as string;
+        const { exitCode: hasExitCode } = await runCli(["has", hash], tmpStore);
+        expect(hasExitCode).toBe(0);
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T1.2: Valid data with optional properties should be accepted", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Schema with optional property
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              age: { type: "number" },
+            },
+            required: ["name"],
+            additionalProperties: false,
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Payload with only required properties
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({ name: "test" }));
+
+        const { exitCode, stdout } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).toBe(0);
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T1.3: Valid data with nested objects should be accepted", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Schema with nested structure
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              address: {
+                type: "object",
+                properties: {
+                  street: { type: "string" },
+                  city: { type: "string" },
+                },
+              },
+            },
+            additionalProperties: false,
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Payload with nested structure
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(
+          payloadFile,
+          JSON.stringify({
+            name: "test",
+            address: { street: "123 Main", city: "NYC" },
+          }),
+        );
+
+        const { exitCode, stdout } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).toBe(0);
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T1.4: Valid data using @ alias for type-hash should be accepted", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify("hello world"));
+
+        const { exitCode, stdout } = await runCli(
+          ["put", "@string", payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).toBe(0);
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("Test Group 2: Type Mismatches (New Validation)", () => {
+    test("T2.1: Wrong property type should be rejected", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Schema with name as string
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: { name: { type: "string" } },
+            required: ["name"],
+            additionalProperties: false,
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Payload with name as number
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({ name: 123 }));
+
+        const { exitCode, stdout, stderr } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).toBe(1);
+        expect(stdout).toBe("");
+        expect(stderr).toContain("Validation failed");
+        expect(stderr).toContain(schemaHash.trim());
+        expect(stderr).toContain(payloadFile);
+
+        // Verify no node was stored
+        const { stdout: hasOutput } = await runCli(
+          ["has", "0000000000000"],
+          tmpStore,
+        );
+        expect(envValue(hasOutput)).toBe(false);
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T2.2: Missing required property should be rejected", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Schema with required name
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: { name: { type: "string" } },
+            required: ["name"],
+            additionalProperties: false,
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Empty payload
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({}));
+
+        const { exitCode, stderr } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).not.toBe(0);
+        expect(stderr).toContain("Validation failed");
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T2.3: Additional properties when disallowed should be rejected", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Schema with additionalProperties: false
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: { name: { type: "string" } },
+            additionalProperties: false,
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Payload with extra property
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(
+          payloadFile,
+          JSON.stringify({ name: "test", extra: "not allowed" }),
+        );
+
+        const { exitCode, stderr } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).not.toBe(0);
+        expect(stderr).toContain("Validation failed");
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T2.4: Wrong root type should be rejected", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Schema expecting array
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "array",
+            items: { type: "string" },
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Payload is an object
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({}));
+
+        const { exitCode, stderr } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).not.toBe(0);
+        expect(stderr).toContain("Validation failed");
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T2.5: Nested type mismatch should be rejected", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Schema with nested object
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: {
+              user: {
+                type: "object",
+                properties: {
+                  age: { type: "number" },
+                },
+              },
+            },
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Payload with wrong nested type
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(
+          payloadFile,
+          JSON.stringify({ user: { age: "not a number" } }),
+        );
+
+        const { exitCode, stderr } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).not.toBe(0);
+        expect(stderr).toContain("Validation failed");
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("Test Group 3: Schema Errors (Edge Cases)", () => {
+    test("T3.1: Non-existent type-hash should fail gracefully", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({ name: "test" }));
+
+        const { exitCode, stderr } = await runCli(
+          ["put", "ZZZZZZZZZZZZZ", payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).not.toBe(0);
+        expect(stderr).toContain("Schema not found");
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T3.3: Invalid @ alias should fail before validation", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({}));
+
+        const { exitCode, stderr } = await runCli(
+          ["put", "@nonexistent", payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).not.toBe(0);
+        expect(stderr).toContain("Schema not found");
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("Test Group 4: Integration with Existing Features", () => {
+    test("T4.1: Hash command should not validate (dry-run consistency)", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Create schema
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: { name: { type: "string" } },
+            required: ["name"],
+            additionalProperties: false,
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Invalid payload
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({ name: 123 }));
+
+        // Hash command should succeed even with invalid data
+        const { exitCode, stdout } = await runCli(
+          ["hash", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(exitCode).toBe(0);
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T4.2: Validation respects cas_ref format in schemas", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Schema with cas_ref format
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: {
+              ref: { type: "string", format: "cas_ref" },
+            },
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        // Valid cas_ref
+        const validFile = join(tmpStore, "valid.json");
+        writeFileSync(validFile, JSON.stringify({ ref: "0000000000000" }));
+
+        const { exitCode: validExitCode } = await runCli(
+          ["put", schemaHash.trim(), validFile],
+          tmpStore,
+        );
+        expect(validExitCode).toBe(0);
+
+        // Invalid cas_ref (wrong length)
+        const invalidFile = join(tmpStore, "invalid.json");
+        writeFileSync(invalidFile, JSON.stringify({ ref: "short" }));
+
+        const { exitCode: invalidExitCode, stderr } = await runCli(
+          ["put", schemaHash.trim(), invalidFile],
+          tmpStore,
+        );
+        expect(invalidExitCode).not.toBe(0);
+        expect(stderr).toContain("Validation failed");
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T4.3: Schema self-validation still works", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        // Valid schema
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: { name: { type: "string" } },
+          }),
+        );
+
+        const hash = await putSchemaFile(tmpStore, schemaFile);
+        expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+  });
+
+  describe("Test Group 5: Error Message Quality", () => {
+    test("T5.1: Error message should be helpful", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: { name: { type: "string" } },
+            required: ["name"],
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({ name: 123 }));
+
+        const { stderr } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(stderr).toContain("Validation failed");
+        expect(stderr).toContain(schemaHash.trim());
+        expect(stderr).toContain(payloadFile);
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+
+    test("T5.2: Error should go to stderr, not stdout", async () => {
+      const tmpStore = mkdtempSync(join(tmpdir(), "json-cas-test-"));
+      try {
+        await runCli(["init"], tmpStore);
+
+        const schemaFile = join(tmpStore, "schema.json");
+        writeFileSync(
+          schemaFile,
+          JSON.stringify({
+            type: "object",
+            properties: { name: { type: "string" } },
+          }),
+        );
+        const schemaHash = await putSchemaFile(tmpStore, schemaFile);
+
+        const payloadFile = join(tmpStore, "payload.json");
+        writeFileSync(payloadFile, JSON.stringify({ name: 123 }));
+
+        const { stdout, stderr } = await runCli(
+          ["put", schemaHash.trim(), payloadFile],
+          tmpStore,
+        );
+
+        expect(stdout).toBe("");
+        expect(stderr.length).toBeGreaterThan(0);
+      } finally {
+        rmSync(tmpStore, { recursive: true, force: true });
+      }
+    });
+  });
+});
+
+// e2e Phase 2 tests
+describe("Phase 2: Schema Validation", () => {
+  let tmpStore: string;
+  let varDbPath: string;
+  let typeHash: string;
+  let nodeHash: string;
+
+  const entrypoint = resolve(import.meta.dir, "../src/index.ts");
+
+  beforeAll(async () => {
+    tmpStore = mkdtempSync(join(tmpdir(), "json-cas-e2e-"));
+    varDbPath = join(tmpStore, "variables.db");
+
+    const schemaFile = join(tmpStore, "test-schema.json");
+    writeFileSync(
+      schemaFile,
+      JSON.stringify({
+        type: "object",
+        properties: { name: { type: "string" }, age: { type: "number" } },
+        required: ["name"],
+        additionalProperties: false,
+      }),
+    );
+    const { openStore: openFsStore } = await import("@uncaged/json-cas-fs");
+    const { putSchema } = await import("@uncaged/json-cas");
+    const store = await openFsStore(tmpStore);
+    typeHash = await putSchema(
+      store,
+      JSON.parse(readFileSync(schemaFile, "utf-8")),
+    );
+
+    const nodeFile = join(tmpStore, "test-node.json");
+    writeFileSync(nodeFile, JSON.stringify({ name: "Alice", age: 30 }));
+    const proc = Bun.spawn(
+      [
+        "bun",
+        entrypoint,
+        "--store",
+        tmpStore,
+        "--var-db",
+        varDbPath,
+        "put",
+        typeHash,
+        nodeFile,
+      ],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    nodeHash = envValue(stdout) as string;
+  });
+
+  afterAll(() => {
+    rmSync(tmpStore, { recursive: true, force: true });
+  });
+
+  test("2.1 put {name:123} against string-schema fails with non-zero exit", async () => {
+    const badFile = join(tmpStore, "bad-node.json");
+    writeFileSync(badFile, JSON.stringify({ name: 123 }));
+    const proc = Bun.spawn(
+      [
+        "bun",
+        entrypoint,
+        "--store",
+        tmpStore,
+        "--var-db",
+        varDbPath,
+        "put",
+        typeHash,
+        badFile,
+      ],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const exitCode = await proc.exited;
+    const stdout = (await new Response(proc.stdout).text()).trim();
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    expect(exitCode).not.toBe(0);
+    expect(stdout).toBe("");
+    expect(stderr).toContain("Validation failed");
+    expect(stderr).toContain(typeHash);
+  });
+
+  test("2.3 put against non-existent schema hash fails", async () => {
+    const nodeFile = join(tmpStore, "test-node.json");
+    const proc = Bun.spawn(
+      [
+        "bun",
+        entrypoint,
+        "--store",
+        tmpStore,
+        "--var-db",
+        varDbPath,
+        "put",
+        "AAAAAAAAAAAAA",
+        nodeFile,
+      ],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const exitCode = await proc.exited;
+    const stderr = (await new Response(proc.stderr).text()).trim();
+    expect(exitCode).not.toBe(0);
+    expect(stderr).toMatchSnapshot();
+  });
+});

packages/cli-json-cas/tests/template.test.ts

@@ -0,0 +1,639 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Hash, Store } from "@uncaged/json-cas";
+import { bootstrap } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+
+// ---- Test helpers ----
+
+let testDir: string;
+let storePath: string;
+let varDbPath: string;
+let cliPath: string;
+
+beforeEach(() => {
+  // Create unique temp directory for each test
+  testDir = join(
+    tmpdir(),
+    `json-cas-test-${Date.now()}-${Math.random().toString(36).slice(2)}`,
+  );
+  storePath = join(testDir, "store");
+  varDbPath = join(testDir, "variables.db");
+  cliPath = join(import.meta.dir, "../src/index.ts");
+
+  mkdirSync(testDir, { recursive: true });
+  mkdirSync(storePath, { recursive: true });
+});
+
+afterEach(() => {
+  // Clean up test directory
+  try {
+    rmSync(testDir, { recursive: true, force: true });
+  } catch {
+    // Ignore cleanup errors
+  }
+});
+
+/**
+ * Run CLI command and return stdout, stderr, and exit code
+ */
+async function runCli(...args: string[]): Promise<{
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}> {
+  const proc = Bun.spawn(
+    [
+      "bun",
+      "run",
+      cliPath,
+      "--store",
+      storePath,
+      "--var-db",
+      varDbPath,
+      ...args,
+    ],
+    {
+      stdout: "pipe",
+      stderr: "pipe",
+    },
+  );
+
+  const [stdout, stderr] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+  ]);
+
+  await proc.exited;
+
+  return {
+    stdout: stdout.trim(),
+    stderr: stderr.trim(),
+    exitCode: proc.exitCode ?? 0,
+  };
+}
+
+/**
+ * Get bootstrap @string type hash
+ */
+async function getStringHash(store: Store): Promise<Hash> {
+  const builtinSchemas = await bootstrap(store);
+  return builtinSchemas["@string"] ?? "";
+}
+
+// ---- Tests ----
+
+describe("template set", () => {
+  test("set template from file", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const templateFile = join(testDir, "template.txt");
+    writeFileSync(templateFile, "Hello {{name}}!");
+
+    const { stdout, stderr, exitCode } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      templateFile,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stderr).toBe("");
+
+    const envelope = JSON.parse(stdout);
+    expect(envelope).toHaveProperty("type");
+    expect(envelope.value).toHaveProperty("contentHash");
+    expect(envelope.value.schemaHash).toBe(stringHash);
+  });
+
+  test("set template with --inline flag", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const { stdout, exitCode } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      "--inline",
+      "Inline template content",
+    );
+
+    expect(exitCode).toBe(0);
+
+    const envelope = JSON.parse(stdout);
+    expect(envelope).toHaveProperty("type");
+    expect(envelope.value).toHaveProperty("contentHash");
+    expect(envelope.value.schemaHash).toBe(stringHash);
+  });
+
+  test("update existing template (idempotent)", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const templateFile = join(testDir, "template.txt");
+    writeFileSync(templateFile, "Version 1");
+
+    // Set first time
+    await runCli("template", "set", stringHash, templateFile);
+
+    // Update with new content
+    writeFileSync(templateFile, "Version 2");
+    const { stdout, exitCode } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      templateFile,
+    );
+
+    expect(exitCode).toBe(0);
+
+    const envelope = JSON.parse(stdout);
+    expect(envelope.value).toHaveProperty("contentHash");
+
+    // Verify we can get the new version
+    const { stdout: getOut } = await runCli("template", "get", stringHash);
+    expect(JSON.parse(getOut).value).toBe("Version 2");
+  });
+
+  test("error when file not found", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const { stderr, exitCode } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      "/nonexistent/file.txt",
+    );
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Error:");
+  });
+
+  test("error when schema hash invalid", async () => {
+    const templateFile = join(testDir, "template.txt");
+    writeFileSync(templateFile, "content");
+
+    const { stderr, exitCode } = await runCli(
+      "template",
+      "set",
+      "INVALID_HASH",
+      templateFile,
+    );
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Error:");
+  });
+
+  test("error when both file and --inline provided", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const templateFile = join(testDir, "template.txt");
+    writeFileSync(templateFile, "content");
+
+    const { stderr, exitCode } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      templateFile,
+      "--inline",
+      "inline content",
+    );
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Error:");
+  });
+
+  test("support multi-line templates", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const multilineContent = "Line 1\nLine 2\nLine 3";
+    const { exitCode } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      "--inline",
+      multilineContent,
+    );
+
+    expect(exitCode).toBe(0);
+
+    // Verify content
+    const { stdout: getOut } = await runCli("template", "get", stringHash);
+    expect(JSON.parse(getOut).value).toBe(multilineContent);
+  });
+
+  test("support empty templates", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const { stdout, exitCode } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      "--inline",
+      "",
+    );
+
+    expect(exitCode).toBe(0);
+
+    const envelope = JSON.parse(stdout);
+    expect(envelope.value).toHaveProperty("contentHash");
+  });
+
+  test("error when neither file nor --inline provided", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const { stderr, exitCode } = await runCli("template", "set", stringHash);
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Usage:");
+  });
+
+  test("support templates with special characters", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const specialContent = "Template with {{var}} and $env and @ref";
+    const { exitCode } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      "--inline",
+      specialContent,
+    );
+
+    expect(exitCode).toBe(0);
+
+    // Verify content preserved
+    const { stdout: getOut } = await runCli("template", "get", stringHash);
+    expect(JSON.parse(getOut).value).toBe(specialContent);
+  });
+});
+
+describe("template get", () => {
+  test("retrieve template as envelope value", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const content = "Hello {{name}}!";
+    await runCli("template", "set", stringHash, "--inline", content);
+
+    const { stdout, stderr, exitCode } = await runCli(
+      "template",
+      "get",
+      stringHash,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stderr).toBe("");
+    const envelope = JSON.parse(stdout);
+    expect(envelope).toHaveProperty("type");
+    expect(envelope.value).toBe(content);
+  });
+
+  test("error when template not found", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const { stderr, exitCode } = await runCli("template", "get", stringHash);
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Error:");
+    expect(stderr).toContain("not found");
+  });
+
+  test("preserve exact whitespace", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    // The envelope's value preserves exact whitespace (JSON-escaped),
+    // so trimming the surrounding JSON output is harmless.
+    const content = "spaces\n\ttabs\t\nmixed";
+    await runCli("template", "set", stringHash, "--inline", content);
+
+    const { stdout } = await runCli("template", "get", stringHash);
+
+    expect(JSON.parse(stdout).value).toBe(content);
+  });
+
+  test("support multi-line templates", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const multiline = "Line 1\nLine 2\nLine 3";
+    await runCli("template", "set", stringHash, "--inline", multiline);
+
+    const { stdout } = await runCli("template", "get", stringHash);
+
+    expect(JSON.parse(stdout).value).toBe(multiline);
+  });
+});
+
+describe("template list", () => {
+  test("list all templates", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    // Create multiple templates
+    await runCli("template", "set", stringHash, "--inline", "Template 1");
+    await runCli("template", "set", "SCHEMA_HASH_2", "--inline", "Template 2");
+
+    const { stdout, exitCode } = await runCli("template", "list");
+
+    expect(exitCode).toBe(0);
+
+    const envelope = JSON.parse(stdout);
+    expect(envelope).toHaveProperty("type");
+    expect(Array.isArray(envelope.value)).toBe(true);
+    expect(envelope.value.length).toBeGreaterThanOrEqual(1);
+
+    // Check structure
+    const item = envelope.value[0];
+    expect(item).toHaveProperty("schemaHash");
+    expect(item).toHaveProperty("contentHash");
+  });
+
+  test("entry contentHash matches set result", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const { stdout: setOut } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      "--inline",
+      "Some template content",
+    );
+    const { contentHash } = JSON.parse(setOut).value;
+
+    const { stdout } = await runCli("template", "list");
+
+    const value = JSON.parse(stdout).value as Array<{
+      schemaHash: string;
+      contentHash: string;
+    }>;
+    const item = value.find((i) => i.schemaHash === stringHash);
+    expect(item).toBeDefined();
+    if (item) {
+      expect(item.contentHash).toBe(contentHash);
+    }
+  });
+
+  test("empty list when no templates", async () => {
+    const { stdout, exitCode } = await runCli("template", "list");
+
+    expect(exitCode).toBe(0);
+
+    const envelope = JSON.parse(stdout);
+    expect(Array.isArray(envelope.value)).toBe(true);
+    expect(envelope.value.length).toBe(0);
+  });
+
+  test("exclude non-template variables", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    // Create a template
+    await runCli("template", "set", stringHash, "--inline", "Template");
+
+    // Create a regular variable (not under @ucas/template/text/)
+    const hash = await store.put(stringHash, "regular var content");
+    await runCli("var", "set", "regular/var", hash);
+
+    const { stdout } = await runCli("template", "list");
+
+    const envelope = JSON.parse(stdout);
+    // Should only contain template variables
+    for (const item of envelope.value) {
+      expect(item.schemaHash).toBeDefined();
+    }
+  });
+
+  test("output JSON envelope with array value", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    await runCli("template", "set", stringHash, "--inline", "Test");
+
+    const { stdout } = await runCli("template", "list");
+
+    // Should be valid JSON
+    expect(() => JSON.parse(stdout)).not.toThrow();
+
+    const envelope = JSON.parse(stdout);
+    expect(Array.isArray(envelope.value)).toBe(true);
+  });
+});
+
+describe("template delete", () => {
+  test("delete template variable binding", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    await runCli("template", "set", stringHash, "--inline", "Template");
+
+    const { stdout, stderr, exitCode } = await runCli(
+      "template",
+      "delete",
+      stringHash,
+    );
+
+    expect(exitCode).toBe(0);
+    expect(stderr).toBe("");
+
+    const envelope = JSON.parse(stdout);
+    expect(envelope).toHaveProperty("type");
+    expect(envelope.value).toHaveProperty("deleted");
+    expect(envelope.value.deleted).toBe(true);
+
+    // Verify template is gone
+    const { exitCode: getExitCode } = await runCli(
+      "template",
+      "get",
+      stringHash,
+    );
+    expect(getExitCode).toBe(1);
+  });
+
+  test("error when template not found", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const { stderr, exitCode } = await runCli("template", "delete", stringHash);
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Error:");
+    expect(stderr).toContain("not found");
+  });
+
+  test("deletion does not affect other templates", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    // Create two templates
+    await runCli("template", "set", stringHash, "--inline", "Template 1");
+    await runCli("template", "set", "SCHEMA_HASH_2", "--inline", "Template 2");
+
+    // Delete first template
+    await runCli("template", "delete", stringHash);
+
+    // Verify second still exists
+    const { stdout } = await runCli("template", "list");
+    const value = JSON.parse(stdout).value as Array<{
+      schemaHash: string;
+      contentHash: string;
+    }>;
+
+    // Should not find deleted template
+    const deleted = value.find((i) => i.schemaHash === stringHash);
+    expect(deleted).toBeUndefined();
+  });
+
+  test("CAS content remains after variable deletion", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    await runCli("template", "set", stringHash, "--inline", "Content");
+
+    // Get the content hash before deletion
+    const { stdout: setOut } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      "--inline",
+      "Content",
+    );
+    const { contentHash } = JSON.parse(setOut).value;
+
+    // Delete the template variable
+    await runCli("template", "delete", stringHash);
+
+    // Verify CAS node still exists
+    const { exitCode: hasExitCode } = await runCli("has", contentHash);
+    expect(hasExitCode).toBe(0);
+  });
+
+  test("deletion is non-idempotent (second delete fails)", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    await runCli("template", "set", stringHash, "--inline", "Template");
+
+    // First deletion succeeds
+    const { exitCode: firstExit } = await runCli(
+      "template",
+      "delete",
+      stringHash,
+    );
+    expect(firstExit).toBe(0);
+
+    // Second deletion fails
+    const { exitCode: secondExit } = await runCli(
+      "template",
+      "delete",
+      stringHash,
+    );
+    expect(secondExit).toBe(1);
+  });
+});
+
+describe("template integration", () => {
+  test("end-to-end workflow: set→get→list→delete", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    const content = "Integration test template";
+
+    // Set
+    const { exitCode: setExit } = await runCli(
+      "template",
+      "set",
+      stringHash,
+      "--inline",
+      content,
+    );
+    expect(setExit).toBe(0);
+
+    // Get
+    const { stdout: getOut, exitCode: getExit } = await runCli(
+      "template",
+      "get",
+      stringHash,
+    );
+    expect(getExit).toBe(0);
+    expect(JSON.parse(getOut).value).toBe(content);
+
+    // List
+    const { stdout: listOut, exitCode: listExit } = await runCli(
+      "template",
+      "list",
+    );
+    expect(listExit).toBe(0);
+    const listData = JSON.parse(listOut).value;
+    expect(listData.length).toBeGreaterThan(0);
+
+    // Delete
+    const { exitCode: delExit } = await runCli(
+      "template",
+      "delete",
+      stringHash,
+    );
+    expect(delExit).toBe(0);
+
+    // Verify deleted
+    const { exitCode: finalGet } = await runCli("template", "get", stringHash);
+    expect(finalGet).toBe(1);
+  });
+
+  test("templates compatible with generic var commands", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    // Set via template command
+    await runCli("template", "set", stringHash, "--inline", "Content");
+
+    // List via var command - should see template variable
+    const { stdout } = await runCli("var", "list", "@ucas/template/text/");
+
+    const output = JSON.parse(stdout);
+    expect(output.value.length).toBeGreaterThan(0);
+  });
+
+  test("multiple templates for different schemas", async () => {
+    const store = createFsStore(storePath);
+    const stringHash = await getStringHash(store);
+
+    // Create templates for different schemas
+    await runCli("template", "set", stringHash, "--inline", "Template 1");
+    await runCli("template", "set", "SCHEMA_HASH_2", "--inline", "Template 2");
+    await runCli("template", "set", "SCHEMA_HASH_3", "--inline", "Template 3");
+
+    // List should show all
+    const { stdout } = await runCli("template", "list");
+    const value = JSON.parse(stdout).value;
+    expect(value.length).toBeGreaterThanOrEqual(1);
+  });
+});
+
+describe("template error handling", () => {
+  test("unknown template subcommand", async () => {
+    const { stderr, exitCode } = await runCli("template", "unknown");
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Unknown");
+  });
+
+  test("missing schema hash argument", async () => {
+    const { stderr, exitCode } = await runCli("template", "set");
+
+    expect(exitCode).toBe(1);
+    expect(stderr).toContain("Usage:");
+  });
+});

packages/cli-json-cas/tests/verify-refs-walk.test.ts

@@ -0,0 +1,85 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { envValue, stripVolatile } from "./helpers";
+
+const entrypoint = resolve(import.meta.dir, "../src/index.ts");
+
+let tmpStore: string;
+let varDbPath: string;
+let typeHash: string;
+let nodeHash: string;
+
+beforeAll(async () => {
+  tmpStore = mkdtempSync(join(tmpdir(), "json-cas-e2e-"));
+  varDbPath = join(tmpStore, "variables.db");
+
+  const schemaFile = join(tmpStore, "test-schema.json");
+  writeFileSync(
+    schemaFile,
+    JSON.stringify({
+      type: "object",
+      properties: { name: { type: "string" }, age: { type: "number" } },
+      required: ["name"],
+      additionalProperties: false,
+    }),
+  );
+  const { openStore: openFsStore } = await import("@uncaged/json-cas-fs");
+  const { putSchema } = await import("@uncaged/json-cas");
+  const store = await openFsStore(tmpStore);
+  typeHash = await putSchema(
+    store,
+    JSON.parse(readFileSync(schemaFile, "utf-8")),
+  );
+
+  const nodeFile = join(tmpStore, "test-node.json");
+  writeFileSync(nodeFile, JSON.stringify({ name: "Alice", age: 30 }));
+  const { stdout } = await runCli(["put", typeHash, nodeFile]);
+  nodeHash = envValue(stdout) as string;
+});
+
+afterAll(() => {
+  rmSync(tmpStore, { recursive: true, force: true });
+});
+
+async function runCli(
+  args: string[],
+): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+  const proc = Bun.spawn(
+    ["bun", entrypoint, "--store", tmpStore, "--var-db", varDbPath, ...args],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const exitCode = await proc.exited;
+  const stdout = (await new Response(proc.stdout).text()).trim();
+  const stderr = (await new Response(proc.stderr).text()).trim();
+  return { stdout, stderr, exitCode };
+}
+
+describe("Phase 1: CAS Core", () => {
+  test("1.9 verify returns ok for valid node", async () => {
+    const { stdout, exitCode } = await runCli(["verify", nodeHash]);
+    expect(exitCode).toBe(0);
+    expect(stripVolatile(stdout)).toMatchSnapshot();
+  });
+
+  test("1.10 refs lists direct references (snapshot)", async () => {
+    const { stdout, exitCode } = await runCli(["refs", nodeHash]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toMatchSnapshot();
+  });
+
+  test("1.11 walk shows traversal tree (snapshot)", async () => {
+    const { stdout, exitCode } = await runCli(["walk", nodeHash]);
+    expect(exitCode).toBe(0);
+    expect(stdout).toMatchSnapshot();
+  });
+});
+
+describe("Phase 2: Schema Validation", () => {
+  test("2.2 verify on valid node returns ok (hash + schema)", async () => {
+    const { stdout, exitCode } = await runCli(["verify", nodeHash]);
+    expect(exitCode).toBe(0);
+    expect(envValue(stdout)).toBe("ok");
+  });
+});

packages/json-cas-fs/CHANGELOG.md

@@ -0,0 +1,70 @@
+# @uncaged/json-cas-fs
+
+## 0.6.0
+
+### Minor Changes
+
+- Unified `{ type, value }` envelope output for all CLI commands (RFC [#67](https://github.com/uncaged/json-cas/issues/67)).
+
+  ### Breaking Changes
+
+  - Removed `init`, `bootstrap`, `cat`, `schema put/get/list/validate` commands
+  - All CLI command outputs now wrapped in `{ type, value }` envelope (except `render`)
+  - `openStore()` is now async and auto-bootstraps
+
+  ### New Features
+
+  - 18 `@output/*` schemas registered at bootstrap
+  - `list --type <hash-or-alias>` command (replaces `schema list`)
+  - `verify` now checks both hash integrity and schema validation
+  - `wrapEnvelope()` helper exported from `@uncaged/json-cas`
+  - `openStore()` in `@uncaged/json-cas-fs` — async, auto mkdir + bootstrap
+  - Default LiquidJS templates for all output schemas
+  - Pipe composition: any command output can be piped to `render -p`
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.6.0
+
+## 0.5.3
+
+### Patch Changes
+
+- feat: add oneOf support to meta-schema validation
+
+  Added `oneOf` to `ALLOWED_SCHEMA_KEYS` and corresponding validation logic
+  in `isValidSchema`. This enables workflow frontmatter schemas that use
+  `oneOf` discriminated unions for multi-exit role definitions.
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.5.3
+
+## 0.3.0
+
+### Minor Changes
+
+- Disallow self-referencing nodes in put(). typeHash is now required (no null). Self-ref only via bootstrap().
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.3.0
+
+## 0.2.0
+
+### Minor Changes
+
+- Add listByType(typeHash) to Store interface for O(1) type-based queries, with append-only fs index
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.2.0
+
+## 0.1.3
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @uncaged/json-cas@0.1.3

packages/json-cas-fs/README.md

@@ -0,0 +1,67 @@
+# @uncaged/json-cas-fs
+
+Filesystem-backed CAS store.
+
+## Overview
+
+`@uncaged/json-cas-fs` implements a persistent `Store` on disk. Each node is stored as `<hash>.bin` (CBOR-encoded `CasNode`). A `_index/` directory maps type hashes to content hashes for `listByType`. Stores support bootstrap via the same `BOOTSTRAP_STORE` symbol as the in-memory implementation.
+
+Depends on `@uncaged/json-cas` for hashing, CBOR encoding, and types.
+
+**Dependencies:** `@uncaged/json-cas`, `cborg`
+
+## Installation
+
+```bash
+bun add @uncaged/json-cas-fs
+```
+
+## API
+
+Exported from `src/index.ts`:
+
+```typescript
+function createFsStore(dir: string): BootstrapCapableStore;
+```
+
+Returns a `BootstrapCapableStore` from `@uncaged/json-cas`. The store loads existing `.bin` files on open and migrates or builds the type index on first use.
+
+### Example
+
+```typescript
+import { bootstrap, putSchema } from "@uncaged/json-cas";
+import { createFsStore } from "@uncaged/json-cas-fs";
+
+const store = createFsStore("./my-cas-store");
+await bootstrap(store);
+
+const typeHash = await putSchema(store, {
+  type: "object",
+  properties: { id: { type: "string" } },
+  required: ["id"],
+  additionalProperties: false,
+});
+
+const hash = await store.put(typeHash, { id: "item-1" });
+console.log(store.has(hash)); // true after restart if same dir
+```
+
+### On-disk layout
+
+```
+my-cas-store/
+├── <hash>.bin          # CBOR CasNode
+├── _index/
+│   └── <typeHash>      # newline-separated content hashes
+└── ...
+```
+
+Writes use atomic rename (`<hash>.tmp` → `<hash>.bin`).
+
+## Internal Structure
+
+| File | Purpose |
+|------|---------|
+| `store.ts` | `createFsStore`, load/save nodes and type index |
+| `index.ts` | Public export |
+| `store.test.ts` | Filesystem store tests |

packages/json-cas-fs/package.json

@@ -1,16 +1,25 @@
 {
   "name": "@uncaged/json-cas-fs",
-"version": "0.1.1",
+  "version": "0.6.0",
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
-    "test": "bun test"
+    "test": "bun test",
+    "prepublishOnly": "bash ../../scripts/check-workspace-deps.sh"
   },
   "dependencies": {
-    "@uncaged/json-cas": "workspace:^",
+    "@uncaged/json-cas": "^0.6.0",
     "cborg": "^4.2.3"
   }
 }

packages/json-cas-fs/src/index.ts

@@ -1 +1 @@
-export { createFsStore } from "./store.js";
+export { createFsStore, openStore } from "./store.js";

packages/json-cas-fs/src/store.test.ts

@@ -1,16 +1,24 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtempSync, rmSync } from "node:fs";
+import {
+  existsSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { CasNode } from "@uncaged/json-cas";
 import {
+  BOOTSTRAP_STORE,
   bootstrap,
   computeHash,
   computeSelfHash,
   verify,
 } from "@uncaged/json-cas";
 
-import { createFsStore } from "./store.js";
+import { createFsStore, openStore } from "./store.js";
 
 function makeTmpDir(): string {
   return mkdtempSync(join(tmpdir(), "json-cas-fs-test-"));
@@ -30,20 +38,21 @@ describe("createFsStore – init and bootstrap", () => {
 
   test("store opens against an existing empty dir", () => {
     const store = createFsStore(dir);
-    expect(store.list()).toEqual([]);
+    expect(store.listByType("0000000000000")).toEqual([]);
   });
 
   test("store creates the directory on first put", async () => {
     const nested = join(dir, "sub", "store");
     const store = createFsStore(nested);
     const typeHash = await computeSelfHash({ name: "t" });
-    await store.put(typeHash, { x: 1 });
-    expect(store.list()).toHaveLength(1);
+    const hash = await store.put(typeHash, { x: 1 });
+    expect(store.has(hash)).toBe(true);
   });
 
   test("bootstrap returns a valid 13-char self-referencing hash", async () => {
     const store = createFsStore(dir);
-    const hash = await bootstrap(store);
+    const builtinSchemas = await bootstrap(store);
+    const hash = builtinSchemas["@schema"] ?? "";
 
     expect(hash).toHaveLength(13);
     expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
@@ -57,8 +66,8 @@ describe("createFsStore – init and bootstrap", () => {
     const h1 = await bootstrap(store);
     const h2 = await bootstrap(store);
 
-    expect(h1).toBe(h2);
-    expect(store.list()).toHaveLength(1);
+    expect(h1).toEqual(h2);
+    expect(store.listByType(h1["@schema"] ?? "")).toHaveLength(26);
   });
 });
 
@@ -84,7 +93,7 @@ describe("createFsStore – persistence round-trip", () => {
     const store2 = createFsStore(dir);
     expect(store2.has(h1)).toBe(true);
     expect(store2.has(h2)).toBe(true);
-    expect(store2.list()).toHaveLength(2);
+    expect(store2.listByType(typeHash)).toHaveLength(2);
   });
 
   test("round-trip preserves type, payload, and timestamp", async () => {
@@ -104,7 +113,8 @@ describe("createFsStore – persistence round-trip", () => {
 
   test("bootstrap survives round-trip: self-referencing node reloads correctly", async () => {
     const store1 = createFsStore(dir);
-    const hash = await bootstrap(store1);
+    const builtinSchemas = await bootstrap(store1);
+    const hash = builtinSchemas["@schema"] ?? "";
 
     const store2 = createFsStore(dir);
     const node = store2.get(hash) as CasNode;
@@ -125,7 +135,7 @@ describe("createFsStore – persistence round-trip", () => {
     const ts2 = store2.get(hash)?.timestamp;
 
     expect(ts1).toBe(ts2);
-    expect(store2.list()).toHaveLength(1);
+    expect(store2.listByType(typeHash)).toHaveLength(1);
   });
 });
 
@@ -151,7 +161,7 @@ describe("createFsStore – has and list", () => {
     expect(store.has(hash)).toBe(true);
   });
 
-  test("list returns all stored hashes", async () => {
+  test("listByType returns all stored hashes for a type", async () => {
     const store = createFsStore(dir);
     const typeHash = await computeSelfHash({ name: "t" });
 
@@ -159,16 +169,16 @@ describe("createFsStore – has and list", () => {
     const h2 = await store.put(typeHash, { a: 2 });
     const h3 = await store.put(typeHash, { a: 3 });
 
-    const all = store.list();
+    const all = store.listByType(typeHash);
     expect(all).toHaveLength(3);
     expect(all).toContain(h1);
     expect(all).toContain(h2);
     expect(all).toContain(h3);
   });
 
-  test("list returns empty array on fresh store", () => {
+  test("listByType returns empty array on fresh store", () => {
     const store = createFsStore(dir);
-    expect(store.list()).toEqual([]);
+    expect(store.listByType("0000000000000")).toEqual([]);
   });
 
   test("get returns null for unknown hash", () => {
@@ -177,6 +187,88 @@ describe("createFsStore – has and list", () => {
   });
 });
 
+// ──────────────────────────────────────────────────────────────────────────────
+// listByType and index migration
+// ──────────────────────────────────────────────────────────────────────────────
+describe("createFsStore – listByType", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = makeTmpDir();
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("returns empty array for unknown type", () => {
+    const store = createFsStore(dir);
+    expect(store.listByType("0000000000000")).toEqual([]);
+  });
+
+  test("returns all hashes for the given type", async () => {
+    const store = createFsStore(dir);
+    const typeHash = await computeSelfHash({ name: "t" });
+    const otherType = await computeSelfHash({ name: "other" });
+
+    const h1 = await store.put(typeHash, { a: 1 });
+    const h2 = await store.put(typeHash, { a: 2 });
+    await store.put(otherType, { b: 1 });
+
+    const byType = store.listByType(typeHash);
+    expect(byType).toHaveLength(2);
+    expect(byType).toContain(h1);
+    expect(byType).toContain(h2);
+  });
+
+  test("listByType survives round-trip across store instances", async () => {
+    const typeHash = await computeSelfHash({ name: "persist-by-type" });
+
+    const store1 = createFsStore(dir);
+    const h1 = await store1.put(typeHash, { x: 1 });
+    const h2 = await store1.put(typeHash, { x: 2 });
+
+    const store2 = createFsStore(dir);
+    const byType = store2.listByType(typeHash);
+    expect(byType).toHaveLength(2);
+    expect(byType).toContain(h1);
+    expect(byType).toContain(h2);
+  });
+
+  test("idempotent put does not duplicate in listByType", async () => {
+    const typeHash = await computeSelfHash({ name: "idempotent-index" });
+
+    const store1 = createFsStore(dir);
+    const hash = await store1.put(typeHash, { n: 7 });
+    await store1.put(typeHash, { n: 7 });
+
+    const store2 = createFsStore(dir);
+    expect(store2.listByType(typeHash)).toEqual([hash]);
+  });
+
+  test("rebuilds _index from .bin files when index is missing", async () => {
+    const typeHash = await computeSelfHash({ name: "migrate" });
+
+    const store1 = createFsStore(dir);
+    const h1 = await store1.put(typeHash, { a: 1 });
+    const h2 = await store1.put(typeHash, { a: 2 });
+
+    rmSync(join(dir, "_index"), { recursive: true, force: true });
+
+    const store2 = createFsStore(dir);
+    expect(store2.listByType(typeHash)).toEqual([h1, h2]);
+    expect(existsSync(join(dir, "_index", typeHash))).toBe(true);
+    expect(readdirSync(join(dir, "_index"))).toContain(typeHash);
+  });
+
+  test("bootstrap node is listed under its self type after reload", async () => {
+    const store1 = createFsStore(dir);
+    const builtinSchemas = await bootstrap(store1);
+    const hash = builtinSchemas["@schema"] ?? "";
+
+    const store2 = createFsStore(dir);
+    expect(store2.listByType(hash)).toContain(hash);
+  });
+});
+
 // ──────────────────────────────────────────────────────────────────────────────
 // verify on disk-loaded nodes
 // ──────────────────────────────────────────────────────────────────────────────
@@ -203,7 +295,8 @@ describe("createFsStore – verify on disk-loaded nodes", () => {
 
   test("verify passes on a disk-loaded bootstrap node", async () => {
     const store1 = createFsStore(dir);
-    const hash = await bootstrap(store1);
+    const builtinSchemas = await bootstrap(store1);
+    const hash = builtinSchemas["@schema"] ?? "";
 
     const store2 = createFsStore(dir);
     const node = store2.get(hash) as CasNode;
@@ -227,3 +320,241 @@ describe("createFsStore – verify on disk-loaded nodes", () => {
     }
   });
 });
+
+// ──────────────────────────────────────────────────────────────────────────────
+// openStore – async with auto-bootstrap
+// ──────────────────────────────────────────────────────────────────────────────
+describe("openStore – async with auto-bootstrap", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = makeTmpDir();
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("openStore returns Promise<Store>", async () => {
+    const store = await openStore(dir);
+    expect(store).toBeDefined();
+    expect(typeof store.put).toBe("function");
+    expect(typeof store.get).toBe("function");
+  });
+
+  test("openStore auto-creates directory when it doesn't exist", async () => {
+    const nested = join(dir, "sub", "nested", "store");
+    expect(existsSync(nested)).toBe(false);
+
+    const store = await openStore(nested);
+    expect(existsSync(nested)).toBe(true);
+
+    // Verify store works
+    const typeHash = await computeSelfHash({ name: "t" });
+    const hash = await store.put(typeHash, { x: 1 });
+    expect(store.has(hash)).toBe(true);
+  });
+
+  test("openStore works when directory already exists", async () => {
+    // Pre-create the directory
+    const store1 = await openStore(dir);
+    const typeHash = await computeSelfHash({ name: "t" });
+    await store1.put(typeHash, { x: 1 });
+
+    // Open again
+    const store2 = await openStore(dir);
+    expect(store2.listByType(typeHash)).toHaveLength(1);
+  });
+
+  test("openStore throws error when path exists but is not a directory", async () => {
+    const filePath = join(dir, "not-a-dir");
+    writeFileSync(filePath, "test");
+
+    await expect(openStore(filePath)).rejects.toThrow();
+  });
+
+  test("openStore auto-bootstraps on first open (empty directory)", async () => {
+    const store = await openStore(dir);
+
+    // Check that bootstrap schemas exist
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"];
+
+    expect(metaHash).toBeDefined();
+    expect(store.has(metaHash as string)).toBe(true);
+
+    // Verify all core schemas exist
+    expect(store.has(builtinSchemas["@string"] as string)).toBe(true);
+    expect(store.has(builtinSchemas["@number"] as string)).toBe(true);
+    expect(store.has(builtinSchemas["@object"] as string)).toBe(true);
+    expect(store.has(builtinSchemas["@array"] as string)).toBe(true);
+    expect(store.has(builtinSchemas["@bool"] as string)).toBe(true);
+    expect(store.has(builtinSchemas["@schema"] as string)).toBe(true);
+  });
+
+  test("openStore bootstrap is idempotent on subsequent opens", async () => {
+    const store1 = await openStore(dir);
+    const schemas1 = await bootstrap(store1);
+    const count1 = store1.listAll().length;
+
+    const store2 = await openStore(dir);
+    const schemas2 = await bootstrap(store2);
+    const count2 = store2.listAll().length;
+
+    // Same schemas, same count
+    expect(schemas1).toEqual(schemas2);
+    expect(count1).toBe(count2);
+  });
+
+  test("openStore works on already-bootstrapped store", async () => {
+    // Bootstrap manually first
+    const store1 = createFsStore(dir);
+    const schemas1 = await bootstrap(store1);
+
+    // Open with openStore
+    const store2 = await openStore(dir);
+    const schemas2 = await bootstrap(store2);
+
+    expect(schemas1).toEqual(schemas2);
+  });
+
+  test("openStore auto-bootstraps old store without bootstrap", async () => {
+    // Create a store with some data but no bootstrap
+    const store1 = createFsStore(dir);
+    const typeHash = await computeSelfHash({ name: "custom" });
+    await store1.put(typeHash, { data: "old" });
+
+    // Open with openStore - should auto-bootstrap
+    const store2 = await openStore(dir);
+    const schemas = await bootstrap(store2);
+
+    expect(store2.has(schemas["@schema"] as string)).toBe(true);
+    // Old data still exists
+    expect(store2.listByType(typeHash)).toHaveLength(1);
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────────────────
+// listMeta and listSchemas (FS persistence)
+// ──────────────────────────────────────────────────────────────────────────────
+describe("createFsStore – listMeta and listSchemas", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "json-cas-fs-meta-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  test("C1. _index/_meta exists and contains hash after self-referencing put", async () => {
+    const store = createFsStore(dir);
+    const hash = await store[BOOTSTRAP_STORE]({ type: "object" });
+
+    const metaPath = join(dir, "_index", "_meta");
+    expect(existsSync(metaPath)).toBe(true);
+    const content = readFileSync(metaPath, "utf8");
+    expect(content).toBe(`${hash}\n`);
+  });
+
+  test("C2. multiple meta puts append, no duplicates", async () => {
+    const store = createFsStore(dir);
+    const h1 = await store[BOOTSTRAP_STORE]({ type: "object", v: 1 });
+    const h2 = await store[BOOTSTRAP_STORE]({ type: "object", v: 2 });
+    // re-put first (idempotent)
+    await store[BOOTSTRAP_STORE]({ type: "object", v: 1 });
+
+    const content = readFileSync(join(dir, "_index", "_meta"), "utf8");
+    const lines = content.split("\n").filter((l) => l.length > 0);
+    expect(lines).toHaveLength(2);
+    expect(lines).toContain(h1);
+    expect(lines).toContain(h2);
+  });
+
+  test("C3. reload from disk preserves listMeta", async () => {
+    const store1 = createFsStore(dir);
+    const h1 = await store1[BOOTSTRAP_STORE]({ type: "object", v: "a" });
+    const h2 = await store1[BOOTSTRAP_STORE]({ type: "object", v: "b" });
+
+    const store2 = createFsStore(dir);
+    const meta = store2.listMeta();
+    expect(meta).toContain(h1);
+    expect(meta).toContain(h2);
+    expect(meta).toHaveLength(2);
+  });
+
+  test("C4. migrates from existing nodes when _meta is missing", async () => {
+    const store1 = createFsStore(dir);
+    const h1 = await store1[BOOTSTRAP_STORE]({ type: "object", v: "mig" });
+    const t = await computeSelfHash({ name: "regular" });
+    await store1.put(h1, { type: "string" });
+
+    // Remove _index/_meta but keep _index/* and .bin files
+    const metaPath = join(dir, "_index", "_meta");
+    rmSync(metaPath, { force: true });
+    expect(existsSync(metaPath)).toBe(false);
+
+    const store2 = createFsStore(dir);
+    expect(store2.listMeta()).toContain(h1);
+    expect(existsSync(metaPath)).toBe(true);
+    const content = readFileSync(metaPath, "utf8");
+    expect(content).toContain(h1);
+
+    // unrelated type hash not in meta
+    expect(store2.listMeta()).not.toContain(t);
+  });
+
+  test("C5. existing _meta is not overwritten", async () => {
+    const store1 = createFsStore(dir);
+    const h1 = await store1[BOOTSTRAP_STORE]({ type: "object", v: "keep" });
+
+    const metaPath = join(dir, "_index", "_meta");
+    const before = readFileSync(metaPath, "utf8");
+
+    // Reopen and confirm content unchanged
+    const _store2 = createFsStore(dir);
+    const after = readFileSync(metaPath, "utf8");
+    expect(after).toBe(before);
+    expect(after).toContain(h1);
+  });
+
+  test("C6. listSchemas returns union of typeIndex[m] for m in metaSet", async () => {
+    const store = createFsStore(dir);
+    const m = await store[BOOTSTRAP_STORE]({ type: "object" });
+    const s1 = await store.put(m, { type: "string" });
+    const s2 = await store.put(m, { type: "number" });
+    const s3 = await store.put(m, { type: "array" });
+
+    const schemas = store.listSchemas();
+    expect(schemas).toHaveLength(4);
+    expect(schemas).toContain(m);
+    expect(schemas).toContain(s1);
+    expect(schemas).toContain(s2);
+    expect(schemas).toContain(s3);
+  });
+
+  test("C7. delete persists removal from _meta", async () => {
+    const store1 = createFsStore(dir);
+    const h1 = await store1[BOOTSTRAP_STORE]({ type: "object", v: 1 });
+    const h2 = await store1[BOOTSTRAP_STORE]({ type: "object", v: 2 });
+
+    store1.delete(h1);
+
+    const metaPath = join(dir, "_index", "_meta");
+    const content = readFileSync(metaPath, "utf8");
+    expect(content).not.toContain(h1);
+    expect(content).toContain(h2);
+
+    const store2 = createFsStore(dir);
+    expect(store2.listMeta()).not.toContain(h1);
+    expect(store2.listMeta()).toContain(h2);
+  });
+
+  test("C8. fresh store with no self-ref puts has empty listMeta", () => {
+    const store = createFsStore(dir);
+    expect(store.listMeta()).toEqual([]);
+    // _meta may be absent; that's fine
+    const metaPath = join(dir, "_index", "_meta");
+    if (existsSync(metaPath)) {
+      const content = readFileSync(metaPath, "utf8");
+      expect(content).toBe("");
+    }
+  });
+});

packages/json-cas-fs/src/store.ts

@@ -1,16 +1,29 @@
 import {
+  appendFileSync,
+  existsSync,
   mkdirSync,
   readdirSync,
   readFileSync,
   renameSync,
+  statSync,
+  unlinkSync,
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
-import type { CasNode, Hash, Store } from "@uncaged/json-cas";
+import type { BootstrapCapableStore, CasNode, Hash } from "@uncaged/json-cas";
 
-import { cborEncode, computeHash, computeSelfHash } from "@uncaged/json-cas";
+import {
+  BOOTSTRAP_STORE,
+  bootstrap,
+  cborEncode,
+  computeHash,
+  computeSelfHash,
+} from "@uncaged/json-cas";
 import { decode } from "cborg";
 
+const INDEX_DIR = "_index";
+const META_FILE = "_meta";
+
 function loadDir(dir: string, data: Map<Hash, CasNode>): void {
   let entries: string[];
   try {
@@ -31,20 +44,169 @@ function loadDir(dir: string, data: Map<Hash, CasNode>): void {
   }
 }
 
-export function createFsStore(dir: string): Store {
+function parseIndexFile(content: string): Hash[] {
+  if (content.length === 0) return [];
+  return content.split("\n").filter((line) => line.length > 0) as Hash[];
+}
+
+function loadTypeIndex(indexDir: string): Map<Hash, Hash[]> {
+  const typeIndex = new Map<Hash, Hash[]>();
+  let entries: string[];
+  try {
+    entries = readdirSync(indexDir);
+  } catch {
+    return typeIndex;
+  }
+  for (const typeHash of entries) {
+    try {
+      const content = readFileSync(join(indexDir, typeHash), "utf8");
+      typeIndex.set(typeHash as Hash, parseIndexFile(content));
+    } catch {
+      // skip unreadable index files
+    }
+  }
+  return typeIndex;
+}
+
+function buildTypeIndexFromNodes(data: Map<Hash, CasNode>): Map<Hash, Hash[]> {
+  const typeIndex = new Map<Hash, Hash[]>();
+  for (const [hash, node] of data) {
+    const list = typeIndex.get(node.type) ?? [];
+    list.push(hash);
+    typeIndex.set(node.type, list);
+  }
+  return typeIndex;
+}
+
+function writeTypeIndex(indexDir: string, typeIndex: Map<Hash, Hash[]>): void {
+  mkdirSync(indexDir, { recursive: true });
+  for (const [typeHash, hashes] of typeIndex) {
+    const body = hashes.length > 0 ? `${hashes.join("\n")}\n` : "";
+    writeFileSync(join(indexDir, typeHash), body, "utf8");
+  }
+}
+
+function loadOrMigrateTypeIndex(
+  dir: string,
+  data: Map<Hash, CasNode>,
+): Map<Hash, Hash[]> {
+  const indexDir = join(dir, INDEX_DIR);
+  if (!existsSync(indexDir)) {
+    const typeIndex = buildTypeIndexFromNodes(data);
+    if (typeIndex.size > 0) {
+      writeTypeIndex(indexDir, typeIndex);
+    }
+    return typeIndex;
+  }
+  return loadTypeIndex(indexDir);
+}
+
+function loadOrMigrateMetaSet(
+  dir: string,
+  data: Map<Hash, CasNode>,
+): Set<Hash> {
+  const indexDir = join(dir, INDEX_DIR);
+  const metaPath = join(indexDir, META_FILE);
+  if (existsSync(metaPath)) {
+    try {
+      const content = readFileSync(metaPath, "utf8");
+      return new Set(parseIndexFile(content));
+    } catch {
+      return new Set();
+    }
+  }
+  // Migration: scan loaded nodes for self-referencing nodes (type === hash)
+  const metaSet = new Set<Hash>();
+  for (const [hash, node] of data) {
+    if (node.type === hash) {
+      metaSet.add(hash);
+    }
+  }
+  if (metaSet.size > 0) {
+    mkdirSync(indexDir, { recursive: true });
+    const body = `${[...metaSet].join("\n")}\n`;
+    writeFileSync(metaPath, body, "utf8");
+  }
+  return metaSet;
+}
+
+function appendToMetaSet(
+  indexDir: string,
+  metaSet: Set<Hash>,
+  hash: Hash,
+): void {
+  if (metaSet.has(hash)) return;
+  metaSet.add(hash);
+  mkdirSync(indexDir, { recursive: true });
+  appendFileSync(join(indexDir, META_FILE), `${hash}\n`, "utf8");
+}
+
+function rewriteMetaSet(indexDir: string, metaSet: Set<Hash>): void {
+  const metaPath = join(indexDir, META_FILE);
+  if (metaSet.size === 0) {
+    try {
+      unlinkSync(metaPath);
+    } catch {
+      // ignore
+    }
+    return;
+  }
+  mkdirSync(indexDir, { recursive: true });
+  const body = `${[...metaSet].join("\n")}\n`;
+  writeFileSync(metaPath, body, "utf8");
+}
+
+function appendToTypeIndex(
+  indexDir: string,
+  typeIndex: Map<Hash, Hash[]>,
+  type: Hash,
+  hash: Hash,
+): void {
+  mkdirSync(indexDir, { recursive: true });
+  appendFileSync(join(indexDir, type), `${hash}\n`, "utf8");
+  const list = typeIndex.get(type) ?? [];
+  list.push(hash);
+  typeIndex.set(type, list);
+}
+
+export function createFsStore(dir: string): BootstrapCapableStore {
   const data = new Map<Hash, CasNode>();
   loadDir(dir, data);
+  const indexDir = join(dir, INDEX_DIR);
+  const typeIndex = loadOrMigrateTypeIndex(dir, data);
+  const metaSet = loadOrMigrateMetaSet(dir, data);
 
-  return {
-    async put(typeHash: Hash | null, payload: unknown): Promise<Hash> {
-      const hash =
-        typeHash === null
-          ? await computeSelfHash(payload)
-          : await computeHash(typeHash, payload);
+  async function putSelfReferencing(payload: unknown): Promise<Hash> {
+    const hash = await computeSelfHash(payload);
+    if (!data.has(hash)) {
+      const node: CasNode = { type: hash, payload, timestamp: Date.now() };
+      data.set(hash, node);
+
+      mkdirSync(dir, { recursive: true });
+      const tmp = join(dir, `${hash}.tmp`);
+      const dest = join(dir, `${hash}.bin`);
+      writeFileSync(
+        tmp,
+        cborEncode({ type: hash, payload, timestamp: node.timestamp }),
+      );
+      renameSync(tmp, dest);
+
+      appendToTypeIndex(indexDir, typeIndex, hash, hash);
+    }
+    appendToMetaSet(indexDir, metaSet, hash);
+    return hash;
+  }
+
+  const store: BootstrapCapableStore = {
+    async put(typeHash: Hash, payload: unknown): Promise<Hash> {
+      const hash = await computeHash(typeHash, payload);
 
       if (!data.has(hash)) {
-        const type = typeHash === null ? hash : typeHash;
-        const node: CasNode = { type, payload, timestamp: Date.now() };
+        const node: CasNode = {
+          type: typeHash,
+          payload,
+          timestamp: Date.now(),
+        };
         data.set(hash, node);
 
         mkdirSync(dir, { recursive: true });
@@ -52,9 +214,11 @@ export function createFsStore(dir: string): Store {
         const dest = join(dir, `${hash}.bin`);
         writeFileSync(
           tmp,
-          cborEncode({ type, payload, timestamp: node.timestamp }),
+          cborEncode({ type: typeHash, payload, timestamp: node.timestamp }),
         );
         renameSync(tmp, dest);
+
+        appendToTypeIndex(indexDir, typeIndex, typeHash, hash);
       }
 
       return hash;
@@ -68,8 +232,125 @@ export function createFsStore(dir: string): Store {
       return data.has(hash);
     },
 
-    list(): Hash[] {
-      return [...data.keys()];
+    listByType(typeHash: Hash): Hash[] {
+      return typeIndex.get(typeHash) ?? [];
     },
+
+    listAll(): Hash[] {
+      return Array.from(data.keys());
+    },
+
+    listMeta(): Hash[] {
+      return Array.from(metaSet);
+    },
+
+    listSchemas(): Hash[] {
+      const result = new Set<Hash>();
+      for (const meta of metaSet) {
+        result.add(meta);
+        const list = typeIndex.get(meta);
+        if (list) {
+          for (const h of list) result.add(h);
+        }
+      }
+      return Array.from(result);
+    },
+
+    delete(hash: Hash): void {
+      const node = data.get(hash);
+      if (node) {
+        data.delete(hash);
+        // Delete file
+        try {
+          unlinkSync(join(dir, `${hash}.bin`));
+        } catch {
+          // ignore if file doesn't exist
+        }
+        // Remove from type index
+        const list = typeIndex.get(node.type);
+        if (list) {
+          const idx = list.indexOf(hash);
+          if (idx !== -1) {
+            list.splice(idx, 1);
+          }
+          if (list.length === 0) {
+            typeIndex.delete(node.type);
+            // Delete empty index file
+            try {
+              unlinkSync(join(indexDir, node.type));
+            } catch {
+              // ignore
+            }
+          } else {
+            // Rewrite index file
+            const body = `${list.join("\n")}\n`;
+            writeFileSync(join(indexDir, node.type), body, "utf8");
+          }
+        }
+        // Remove from meta set if applicable
+        if (metaSet.has(hash)) {
+          metaSet.delete(hash);
+          rewriteMetaSet(indexDir, metaSet);
+        }
+      }
+    },
+
+    [BOOTSTRAP_STORE]: putSelfReferencing,
   };
+
+  return store;
+}
+
+/**
+ * Open a filesystem-backed CAS store with automatic directory creation and bootstrap.
+ * This is an async function that:
+ * 1. Creates the directory (with recursive: true) if it doesn't exist
+ * 2. Validates that the path is actually a directory (not a file)
+ * 3. Creates the store
+ * 4. Runs bootstrap (which is idempotent)
+ *
+ * @param dir - The directory path for the store
+ * @returns A Promise resolving to the BootstrapCapableStore
+ * @throws Error if the path exists but is not a directory
+ */
+export async function openStore(dir: string): Promise<BootstrapCapableStore> {
+  // Create directory if it doesn't exist
+  try {
+    mkdirSync(dir, { recursive: true });
+  } catch (error) {
+    if (error instanceof Error && "code" in error) {
+      const nodeError = error as NodeJS.ErrnoException;
+      if (nodeError.code === "EACCES") {
+        throw new Error(`Permission denied: cannot access store at ${dir}`);
+      }
+      if (nodeError.code === "ENOTDIR") {
+        throw new Error(`Path exists but is not a directory: ${dir}`);
+      }
+    }
+    throw error;
+  }
+
+  // Validate that the path is a directory
+  try {
+    const stats = statSync(dir);
+    if (!stats.isDirectory()) {
+      throw new Error(`Path exists but is not a directory: ${dir}`);
+    }
+  } catch (error) {
+    if (error instanceof Error && "code" in error) {
+      const nodeError = error as NodeJS.ErrnoException;
+      if (nodeError.code === "ENOENT") {
+        throw new Error(`Store not found at ${dir}`);
+      }
+    }
+    throw error;
+  }
+
+  // Create the store
+  const store = createFsStore(dir);
+
+  // Bootstrap (idempotent)
+  await bootstrap(store);
+
+  return store;
 }

packages/json-cas-fs/tsconfig.json

@@ -4,5 +4,7 @@
     "rootDir": "src",
     "outDir": "dist"
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"],
+  "references": [{ "path": "../json-cas" }]
 }

packages/json-cas-workflow/package.json

@@ -1,15 +0,0 @@
-{
-  "name": "@uncaged/json-cas-workflow",
-"version": "0.1.1",
-  "type": "module",
-  "main": "./src/index.ts",
-  "exports": {
-    ".": "./src/index.ts"
-  },
-  "scripts": {
-    "test": "bun test"
-  },
-  "dependencies": {
-    "@uncaged/json-cas": "workspace:^"
-  }
-}

packages/json-cas-workflow/src/index.test.ts

@@ -1,646 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import type { CasNode } from "@uncaged/json-cas";
-import {
-  createMemoryStore,
-  getSchema,
-  refs,
-  validate,
-  walk,
-} from "@uncaged/json-cas";
-import type { WorkflowSchemaHashes } from "./schemas.js";
-import { registerWorkflowSchemas } from "./schemas.js";
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Step 1: registerWorkflowSchemas() — registers all 11 schemas
-// ─────────────────────────────────────────────────────────────────────────────
-describe("registerWorkflowSchemas", () => {
-  test("returns an object with all 11 schema hashes", async () => {
-    const store = createMemoryStore();
-    const hashes = await registerWorkflowSchemas(store);
-
-    const keys: (keyof WorkflowSchemaHashes)[] = [
-      "agent",
-      "roleSchema",
-      "role",
-      "workflow",
-      "threadStart",
-      "threadStep",
-      "threadEnd",
-      "content",
-      "reactSession",
-      "reactTurn",
-      "reactToolCall",
-    ];
-    expect(Object.keys(hashes)).toHaveLength(11);
-    for (const key of keys) {
-      expect(hashes[key]).toBeDefined();
-    }
-  });
-
-  test("all hashes are valid 13-char Crockford Base32 strings", async () => {
-    const store = createMemoryStore();
-    const hashes = await registerWorkflowSchemas(store);
-
-    for (const hash of Object.values(hashes)) {
-      expect(hash).toHaveLength(13);
-      expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
-    }
-  });
-
-  test("all 11 hashes are distinct", async () => {
-    const store = createMemoryStore();
-    const hashes = await registerWorkflowSchemas(store);
-
-    const values = Object.values(hashes);
-    const unique = new Set(values);
-    expect(unique.size).toBe(11);
-  });
-
-  test("is idempotent: repeated calls return the same hashes", async () => {
-    const store = createMemoryStore();
-    const first = await registerWorkflowSchemas(store);
-    const second = await registerWorkflowSchemas(store);
-
-    for (const key of Object.keys(first) as (keyof WorkflowSchemaHashes)[]) {
-      expect(first[key]).toBe(second[key]);
-    }
-  });
-
-  test("schemas are stored in the store (getSchema returns non-null)", async () => {
-    const store = createMemoryStore();
-    const hashes = await registerWorkflowSchemas(store);
-
-    for (const hash of Object.values(hashes)) {
-      expect(getSchema(store, hash)).not.toBeNull();
-    }
-  });
-});
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Step 2: getSchema() — schema round-trip for each of the 11 types
-// ─────────────────────────────────────────────────────────────────────────────
-describe("getSchema round-trip", () => {
-  test("agent schema has the expected properties", async () => {
-    const store = createMemoryStore();
-    const { agent } = await registerWorkflowSchemas(store);
-    const schema = getSchema(store, agent);
-
-    expect(schema).not.toBeNull();
-    expect(schema?.type).toBe("object");
-    const props = schema?.properties as Record<string, unknown>;
-    expect(props).toHaveProperty("package");
-    expect(props).toHaveProperty("version");
-    expect(props).toHaveProperty("config");
-  });
-
-  test("role schema references cas_ref for the schema field", async () => {
-    const store = createMemoryStore();
-    const { role } = await registerWorkflowSchemas(store);
-    const schema = getSchema(store, role);
-
-    expect(schema).not.toBeNull();
-    const props = schema?.properties as Record<string, { format?: string }>;
-    expect(props.schema?.format).toBe("cas_ref");
-  });
-
-  test("thread-step schema has six required fields", async () => {
-    const store = createMemoryStore();
-    const { threadStep } = await registerWorkflowSchemas(store);
-    const schema = getSchema(store, threadStep);
-
-    expect(schema?.required).toHaveLength(6);
-  });
-
-  test("react-turn schema has nested tokens object", async () => {
-    const store = createMemoryStore();
-    const { reactTurn } = await registerWorkflowSchemas(store);
-    const schema = getSchema(store, reactTurn);
-
-    const props = schema?.properties as Record<
-      string,
-      { type: string; properties?: unknown }
-    >;
-    expect(props.tokens?.type).toBe("object");
-    expect(props.tokens?.properties).toBeDefined();
-  });
-
-  test("workflow schema has roles with additionalProperties cas_ref", async () => {
-    const store = createMemoryStore();
-    const { workflow } = await registerWorkflowSchemas(store);
-    const schema = getSchema(store, workflow);
-
-    const props = schema?.properties as Record<
-      string,
-      { additionalProperties?: { format?: string } }
-    >;
-    expect(props.roles?.additionalProperties?.format).toBe("cas_ref");
-  });
-});
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Step 3: validate() — correct payloads pass for all 11 schema types
-// ─────────────────────────────────────────────────────────────────────────────
-describe("validate – valid payloads", () => {
-  const HASH = "AAAAAAAAAAAAA";
-
-  test("agent payload is valid", async () => {
-    const store = createMemoryStore();
-    const { agent } = await registerWorkflowSchemas(store);
-    const h = await store.put(agent, {
-      package: "gpt-4o",
-      version: "2024-11",
-      config: { temperature: 0.7 },
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("role-schema payload is valid (any object)", async () => {
-    const store = createMemoryStore();
-    const { roleSchema } = await registerWorkflowSchemas(store);
-    const h = await store.put(roleSchema, {
-      type: "object",
-      properties: { answer: { type: "string" } },
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("role payload is valid", async () => {
-    const store = createMemoryStore();
-    const { role } = await registerWorkflowSchemas(store);
-    const h = await store.put(role, {
-      name: "analyst",
-      description: "Analyses data",
-      systemPrompt: "You are an analyst.",
-      extractPrompt: "Extract the findings.",
-      schema: HASH,
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("workflow payload is valid", async () => {
-    const store = createMemoryStore();
-    const { workflow } = await registerWorkflowSchemas(store);
-    const h = await store.put(workflow, {
-      name: "research",
-      description: "Research workflow",
-      roles: { analyst: HASH },
-      moderator: [{ from: "analyst", to: "analyst", when: null }],
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("thread-start payload is valid (null parentThread)", async () => {
-    const store = createMemoryStore();
-    const { threadStart } = await registerWorkflowSchemas(store);
-    const h = await store.put(threadStart, {
-      workflow: HASH,
-      input: "hello",
-      depth: 0,
-      parentThread: null,
-      agents: { main: HASH },
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("thread-start payload is valid (non-null parentThread)", async () => {
-    const store = createMemoryStore();
-    const { threadStart } = await registerWorkflowSchemas(store);
-    const h = await store.put(threadStart, {
-      workflow: HASH,
-      input: "nested",
-      depth: 1,
-      parentThread: HASH,
-      agents: {},
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("thread-step payload is valid (null previous)", async () => {
-    const store = createMemoryStore();
-    const { threadStep } = await registerWorkflowSchemas(store);
-    const h = await store.put(threadStep, {
-      role: "analyst",
-      meta: { attempt: 1 },
-      content: HASH,
-      react: HASH,
-      start: HASH,
-      previous: null,
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("thread-step payload is valid (non-null previous)", async () => {
-    const store = createMemoryStore();
-    const { threadStep } = await registerWorkflowSchemas(store);
-    const h = await store.put(threadStep, {
-      role: "analyst",
-      meta: {},
-      content: HASH,
-      react: HASH,
-      start: HASH,
-      previous: HASH,
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("thread-end payload is valid", async () => {
-    const store = createMemoryStore();
-    const { threadEnd } = await registerWorkflowSchemas(store);
-    const h = await store.put(threadEnd, {
-      returnCode: 0,
-      summary: "Done",
-      start: HASH,
-      lastStep: HASH,
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("content payload is valid", async () => {
-    const store = createMemoryStore();
-    const { content } = await registerWorkflowSchemas(store);
-    const h = await store.put(content, { text: "Hello, world!" });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("react-session payload is valid (empty turns)", async () => {
-    const store = createMemoryStore();
-    const { reactSession } = await registerWorkflowSchemas(store);
-    const h = await store.put(reactSession, {
-      agent: HASH,
-      role: "analyst",
-      turns: [],
-      totalTokens: 0,
-      durationMs: 42,
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("react-session payload is valid (multiple turns)", async () => {
-    const store = createMemoryStore();
-    const { reactSession } = await registerWorkflowSchemas(store);
-    const h = await store.put(reactSession, {
-      agent: HASH,
-      role: "analyst",
-      turns: [HASH, HASH],
-      totalTokens: 300,
-      durationMs: 1500,
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("react-turn payload is valid", async () => {
-    const store = createMemoryStore();
-    const { reactTurn } = await registerWorkflowSchemas(store);
-    const h = await store.put(reactTurn, {
-      input: HASH,
-      output: HASH,
-      toolCalls: [HASH],
-      tokens: { input: 100, output: 50 },
-      latencyMs: 800,
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-
-  test("react-tool-call payload is valid", async () => {
-    const store = createMemoryStore();
-    const { reactToolCall } = await registerWorkflowSchemas(store);
-    const h = await store.put(reactToolCall, {
-      name: "search",
-      arguments: HASH,
-      result: HASH,
-      durationMs: 200,
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(true);
-  });
-});
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Step 4: validate() — invalid payloads fail for representative types
-// ─────────────────────────────────────────────────────────────────────────────
-describe("validate – invalid payloads", () => {
-  test("agent: missing required field fails", async () => {
-    const store = createMemoryStore();
-    const { agent } = await registerWorkflowSchemas(store);
-    const h = await store.put(agent, { package: "gpt-4o", version: "1" });
-    expect(validate(store, store.get(h) as CasNode)).toBe(false);
-  });
-
-  test("agent: wrong type for config fails", async () => {
-    const store = createMemoryStore();
-    const { agent } = await registerWorkflowSchemas(store);
-    const h = await store.put(agent, {
-      package: "gpt-4o",
-      version: "1",
-      config: "not-an-object",
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(false);
-  });
-
-  test("role: missing systemPrompt fails", async () => {
-    const store = createMemoryStore();
-    const { role } = await registerWorkflowSchemas(store);
-    const h = await store.put(role, {
-      name: "analyst",
-      description: "d",
-      extractPrompt: "e",
-      schema: "AAAAAAAAAAAAA",
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(false);
-  });
-
-  test("thread-start: missing depth fails", async () => {
-    const store = createMemoryStore();
-    const { threadStart } = await registerWorkflowSchemas(store);
-    const h = await store.put(threadStart, {
-      workflow: "AAAAAAAAAAAAA",
-      input: "hi",
-      parentThread: null,
-      agents: {},
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(false);
-  });
-
-  test("thread-end: returnCode as string fails", async () => {
-    const store = createMemoryStore();
-    const { threadEnd } = await registerWorkflowSchemas(store);
-    const h = await store.put(threadEnd, {
-      returnCode: "ok",
-      summary: "Done",
-      start: "AAAAAAAAAAAAA",
-      lastStep: "AAAAAAAAAAAAA",
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(false);
-  });
-
-  test("content: missing text fails", async () => {
-    const store = createMemoryStore();
-    const { content } = await registerWorkflowSchemas(store);
-    const h = await store.put(content, {});
-    expect(validate(store, store.get(h) as CasNode)).toBe(false);
-  });
-
-  test("react-turn: tokens.input as string fails", async () => {
-    const store = createMemoryStore();
-    const { reactTurn } = await registerWorkflowSchemas(store);
-    const h = await store.put(reactTurn, {
-      input: "AAAAAAAAAAAAA",
-      output: "AAAAAAAAAAAAA",
-      toolCalls: [],
-      tokens: { input: "many", output: 50 },
-      latencyMs: 100,
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(false);
-  });
-
-  test("react-tool-call: missing durationMs fails", async () => {
-    const store = createMemoryStore();
-    const { reactToolCall } = await registerWorkflowSchemas(store);
-    const h = await store.put(reactToolCall, {
-      name: "tool",
-      arguments: "AAAAAAAAAAAAA",
-      result: "AAAAAAAAAAAAA",
-    });
-    expect(validate(store, store.get(h) as CasNode)).toBe(false);
-  });
-});
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Step 5: refs() — extracts direct cas_ref fields from node payloads
-// ─────────────────────────────────────────────────────────────────────────────
-describe("refs – cas_ref extraction", () => {
-  const HASH_A = "AAAAAAAAAAAAA";
-  const HASH_B = "BBBBBBBBBBBBB";
-
-  test("content node has no cas_ref fields → empty array", async () => {
-    const store = createMemoryStore();
-    const { content } = await registerWorkflowSchemas(store);
-    const h = await store.put(content, { text: "hello" });
-    const node = store.get(h) as CasNode;
-    expect(refs(store, node)).toEqual([]);
-  });
-
-  test("role node: refs() returns the schema cas_ref", async () => {
-    const store = createMemoryStore();
-    const { role } = await registerWorkflowSchemas(store);
-    const h = await store.put(role, {
-      name: "r",
-      description: "d",
-      systemPrompt: "s",
-      extractPrompt: "e",
-      schema: HASH_A,
-    });
-    const node = store.get(h) as CasNode;
-    expect(refs(store, node)).toContain(HASH_A);
-  });
-
-  test("thread-end: refs() returns start and lastStep", async () => {
-    const store = createMemoryStore();
-    const { threadEnd } = await registerWorkflowSchemas(store);
-    const h = await store.put(threadEnd, {
-      returnCode: 0,
-      summary: "done",
-      start: HASH_A,
-      lastStep: HASH_B,
-    });
-    const node = store.get(h) as CasNode;
-    const result = refs(store, node);
-    expect(result).toContain(HASH_A);
-    expect(result).toContain(HASH_B);
-    expect(result).toHaveLength(2);
-  });
-
-  test("react-tool-call: refs() returns arguments and result", async () => {
-    const store = createMemoryStore();
-    const { reactToolCall } = await registerWorkflowSchemas(store);
-    const h = await store.put(reactToolCall, {
-      name: "search",
-      arguments: HASH_A,
-      result: HASH_B,
-      durationMs: 100,
-    });
-    const node = store.get(h) as CasNode;
-    const result = refs(store, node);
-    expect(result).toContain(HASH_A);
-    expect(result).toContain(HASH_B);
-    expect(result).toHaveLength(2);
-  });
-
-  test("thread-step: refs() returns content, react, and start (previous null is skipped)", async () => {
-    const store = createMemoryStore();
-    const { threadStep } = await registerWorkflowSchemas(store);
-    const h = await store.put(threadStep, {
-      role: "r",
-      meta: {},
-      content: HASH_A,
-      react: HASH_B,
-      start: HASH_A,
-      previous: null,
-    });
-    const node = store.get(h) as CasNode;
-    const result = refs(store, node);
-    expect(result).toContain(HASH_A);
-    expect(result).toContain(HASH_B);
-  });
-
-  test("thread-step: refs() includes previous when non-null", async () => {
-    const store = createMemoryStore();
-    const { threadStep } = await registerWorkflowSchemas(store);
-    const HASH_C = "CCCCCCCCCCCCC";
-    const h = await store.put(threadStep, {
-      role: "r",
-      meta: {},
-      content: HASH_A,
-      react: HASH_B,
-      start: HASH_A,
-      previous: HASH_C,
-    });
-    const node = store.get(h) as CasNode;
-    const result = refs(store, node);
-    expect(result).toContain(HASH_C);
-  });
-
-  test("react-session: refs() returns the agent cas_ref", async () => {
-    const store = createMemoryStore();
-    const { reactSession } = await registerWorkflowSchemas(store);
-    const h = await store.put(reactSession, {
-      agent: HASH_A,
-      role: "r",
-      turns: [],
-      totalTokens: 0,
-      durationMs: 0,
-    });
-    const node = store.get(h) as CasNode;
-    expect(refs(store, node)).toContain(HASH_A);
-  });
-});
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Step 6: walk() — BFS traversal through linked workflow nodes
-// ─────────────────────────────────────────────────────────────────────────────
-describe("walk – cross-schema traversal", () => {
-  test("walk visits content node linked from thread-end", async () => {
-    const store = createMemoryStore();
-    const { threadEnd, content } = await registerWorkflowSchemas(store);
-
-    const contentHash = await store.put(content, { text: "summary text" });
-    const endHash = await store.put(threadEnd, {
-      returnCode: 0,
-      summary: "done",
-      start: contentHash,
-      lastStep: contentHash,
-    });
-
-    const visited = new Set<string>();
-    walk(store, endHash, (h) => visited.add(h));
-
-    expect(visited.has(endHash)).toBe(true);
-    expect(visited.has(contentHash)).toBe(true);
-  });
-
-  test("walk through role → (schema stored in store)", async () => {
-    const store = createMemoryStore();
-    const { role, roleSchema } = await registerWorkflowSchemas(store);
-
-    const schemaDocHash = await store.put(roleSchema, {
-      type: "object",
-      properties: { answer: { type: "string" } },
-    });
-    const roleHash = await store.put(role, {
-      name: "analyst",
-      description: "d",
-      systemPrompt: "s",
-      extractPrompt: "e",
-      schema: schemaDocHash,
-    });
-
-    const visited = new Set<string>();
-    walk(store, roleHash, (h) => visited.add(h));
-
-    expect(visited.has(roleHash)).toBe(true);
-    expect(visited.has(schemaDocHash)).toBe(true);
-  });
-
-  test("walk handles diamond: two thread-end nodes sharing the same start", async () => {
-    const store = createMemoryStore();
-    const { threadEnd, content } = await registerWorkflowSchemas(store);
-
-    const sharedStart = await store.put(content, { text: "start" });
-    const step1 = await store.put(content, { text: "step1" });
-    const step2 = await store.put(content, { text: "step2" });
-
-    const end1 = await store.put(threadEnd, {
-      returnCode: 0,
-      summary: "path A",
-      start: sharedStart,
-      lastStep: step1,
-    });
-    const end2 = await store.put(threadEnd, {
-      returnCode: 1,
-      summary: "path B",
-      start: sharedStart,
-      lastStep: step2,
-    });
-
-    // Use react-turn as the root linking both ends via input/output
-    const { reactTurn } = await registerWorkflowSchemas(store);
-    const turnHash = await store.put(reactTurn, {
-      input: end1,
-      output: end2,
-      toolCalls: [],
-      tokens: { input: 10, output: 5 },
-      latencyMs: 50,
-    });
-
-    const visited = new Set<string>();
-    walk(store, turnHash, (h) => visited.add(h));
-
-    expect(visited.has(turnHash)).toBe(true);
-    expect(visited.has(end1)).toBe(true);
-    expect(visited.has(end2)).toBe(true);
-    // sharedStart is reached from both end1 and end2, but visited only once
-    expect(visited.has(sharedStart)).toBe(true);
-    expect(visited.has(step1)).toBe(true);
-    expect(visited.has(step2)).toBe(true);
-  });
-
-  test("walk visits react-tool-call linked from react-turn", async () => {
-    const store = createMemoryStore();
-    const { reactTurn, reactToolCall, content } =
-      await registerWorkflowSchemas(store);
-
-    const argsHash = await store.put(content, { text: '{"q":"test"}' });
-    const resultHash = await store.put(content, { text: '{"r":"ok"}' });
-    const toolCallHash = await store.put(reactToolCall, {
-      name: "search",
-      arguments: argsHash,
-      result: resultHash,
-      durationMs: 120,
-    });
-
-    const inputHash = await store.put(content, { text: "input" });
-    const outputHash = await store.put(content, { text: "output" });
-    const turnHash = await store.put(reactTurn, {
-      input: inputHash,
-      output: outputHash,
-      toolCalls: [],
-      tokens: { input: 80, output: 40 },
-      latencyMs: 600,
-    });
-
-    const visited = new Set<string>();
-    walk(store, turnHash, (h) => visited.add(h));
-
-    expect(visited.has(turnHash)).toBe(true);
-    expect(visited.has(inputHash)).toBe(true);
-    expect(visited.has(outputHash)).toBe(true);
-    // toolCallHash is not in the turn's cas_ref fields (toolCalls array), only linked manually
-    expect(visited.has(toolCallHash)).toBe(false);
-
-    // walk from toolCallHash to verify it reaches args and result
-    const tcVisited = new Set<string>();
-    walk(store, toolCallHash, (h) => tcVisited.add(h));
-    expect(tcVisited.has(toolCallHash)).toBe(true);
-    expect(tcVisited.has(argsHash)).toBe(true);
-    expect(tcVisited.has(resultHash)).toBe(true);
-  });
-});

packages/json-cas-workflow/src/index.ts

@@ -1,19 +0,0 @@
-export {
-  registerWorkflowSchemas,
-  type WorkflowSchemaHashes,
-} from "./schemas.js";
-export type {
-  AgentPayload,
-  ContentPayload,
-  ReactSessionPayload,
-  ReactToolCallPayload,
-  ReactTurnPayload,
-  ReactTurnTokens,
-  RolePayload,
-  RoleSchemaPayload,
-  ThreadEndPayload,
-  ThreadStartPayload,
-  ThreadStepPayload,
-  WorkflowPayload,
-  WorkflowTransition,
-} from "./types.js";

packages/json-cas-workflow/src/schemas.ts

@@ -1,236 +0,0 @@
-import type { Hash, Store } from "@uncaged/json-cas";
-import { type JSONSchema, putSchema } from "@uncaged/json-cas";
-
-// ── Definition layer ──────────────────────────────────────────────────────────
-
-const AGENT: JSONSchema = {
-  type: "object",
-  required: ["package", "version", "config"],
-  properties: {
-    package: { type: "string" },
-    version: { type: "string" },
-    config: { type: "object" },
-  },
-  additionalProperties: false,
-};
-
-/** role-schema nodes hold raw JSON Schema documents, so any object is valid. */
-const ROLE_SCHEMA: JSONSchema = {
-  type: "object",
-};
-
-const ROLE: JSONSchema = {
-  type: "object",
-  required: ["name", "description", "systemPrompt", "extractPrompt", "schema"],
-  properties: {
-    name: { type: "string" },
-    description: { type: "string" },
-    systemPrompt: { type: "string" },
-    extractPrompt: { type: "string" },
-    schema: { type: "string", format: "cas_ref" },
-  },
-  additionalProperties: false,
-};
-
-const WORKFLOW: JSONSchema = {
-  type: "object",
-  required: ["name", "description", "roles", "moderator"],
-  properties: {
-    name: { type: "string" },
-    description: { type: "string" },
-    roles: {
-      type: "object",
-      additionalProperties: { type: "string", format: "cas_ref" },
-    },
-    moderator: {
-      type: "array",
-      items: {
-        type: "object",
-        required: ["from", "to", "when"],
-        properties: {
-          from: { type: "string" },
-          to: { type: "string" },
-          when: { anyOf: [{ type: "string" }, { type: "null" }] },
-        },
-        additionalProperties: false,
-      },
-    },
-  },
-  additionalProperties: false,
-};
-
-// ── Execution layer ───────────────────────────────────────────────────────────
-
-const THREAD_START: JSONSchema = {
-  type: "object",
-  required: ["workflow", "input", "depth", "parentThread", "agents"],
-  properties: {
-    workflow: { type: "string", format: "cas_ref" },
-    input: { type: "string" },
-    depth: { type: "number" },
-    parentThread: {
-      anyOf: [{ type: "string", format: "cas_ref" }, { type: "null" }],
-    },
-    agents: {
-      type: "object",
-      additionalProperties: { type: "string", format: "cas_ref" },
-    },
-  },
-  additionalProperties: false,
-};
-
-const THREAD_STEP: JSONSchema = {
-  type: "object",
-  required: ["role", "meta", "content", "react", "start", "previous"],
-  properties: {
-    role: { type: "string" },
-    meta: { type: "object" },
-    content: { type: "string", format: "cas_ref" },
-    react: { type: "string", format: "cas_ref" },
-    start: { type: "string", format: "cas_ref" },
-    previous: {
-      anyOf: [{ type: "string", format: "cas_ref" }, { type: "null" }],
-    },
-  },
-  additionalProperties: false,
-};
-
-const THREAD_END: JSONSchema = {
-  type: "object",
-  required: ["returnCode", "summary", "start", "lastStep"],
-  properties: {
-    returnCode: { type: "number" },
-    summary: { type: "string" },
-    start: { type: "string", format: "cas_ref" },
-    lastStep: { type: "string", format: "cas_ref" },
-  },
-  additionalProperties: false,
-};
-
-const CONTENT: JSONSchema = {
-  type: "object",
-  required: ["text"],
-  properties: {
-    text: { type: "string" },
-  },
-  additionalProperties: false,
-};
-
-// ── React layer ───────────────────────────────────────────────────────────────
-
-const REACT_SESSION: JSONSchema = {
-  type: "object",
-  required: ["agent", "role", "turns", "totalTokens", "durationMs"],
-  properties: {
-    agent: { type: "string", format: "cas_ref" },
-    role: { type: "string" },
-    turns: {
-      type: "array",
-      items: { type: "string", format: "cas_ref" },
-    },
-    totalTokens: { type: "number" },
-    durationMs: { type: "number" },
-  },
-  additionalProperties: false,
-};
-
-const REACT_TURN: JSONSchema = {
-  type: "object",
-  required: ["input", "output", "toolCalls", "tokens", "latencyMs"],
-  properties: {
-    input: { type: "string", format: "cas_ref" },
-    output: { type: "string", format: "cas_ref" },
-    toolCalls: {
-      type: "array",
-      items: { type: "string", format: "cas_ref" },
-    },
-    tokens: {
-      type: "object",
-      required: ["input", "output"],
-      properties: {
-        input: { type: "number" },
-        output: { type: "number" },
-      },
-      additionalProperties: false,
-    },
-    latencyMs: { type: "number" },
-  },
-  additionalProperties: false,
-};
-
-const REACT_TOOL_CALL: JSONSchema = {
-  type: "object",
-  required: ["name", "arguments", "result", "durationMs"],
-  properties: {
-    name: { type: "string" },
-    arguments: { type: "string", format: "cas_ref" },
-    result: { type: "string", format: "cas_ref" },
-    durationMs: { type: "number" },
-  },
-  additionalProperties: false,
-};
-
-// ── Registry ──────────────────────────────────────────────────────────────────
-
-export type WorkflowSchemaHashes = {
-  agent: Hash;
-  roleSchema: Hash;
-  role: Hash;
-  workflow: Hash;
-  threadStart: Hash;
-  threadStep: Hash;
-  threadEnd: Hash;
-  content: Hash;
-  reactSession: Hash;
-  reactTurn: Hash;
-  reactToolCall: Hash;
-};
-
-/**
- * Register all 11 workflow schemas into the given store.
- * Returns a map from camelCase schema name to its CAS type hash.
- * Idempotent: safe to call multiple times on the same store.
- */
-export async function registerWorkflowSchemas(
-  store: Store,
-): Promise<WorkflowSchemaHashes> {
-  const [
-    agent,
-    roleSchema,
-    role,
-    workflow,
-    threadStart,
-    threadStep,
-    threadEnd,
-    content,
-    reactSession,
-    reactTurn,
-    reactToolCall,
-  ] = await Promise.all([
-    putSchema(store, AGENT),
-    putSchema(store, ROLE_SCHEMA),
-    putSchema(store, ROLE),
-    putSchema(store, WORKFLOW),
-    putSchema(store, THREAD_START),
-    putSchema(store, THREAD_STEP),
-    putSchema(store, THREAD_END),
-    putSchema(store, CONTENT),
-    putSchema(store, REACT_SESSION),
-    putSchema(store, REACT_TURN),
-    putSchema(store, REACT_TOOL_CALL),
-  ]);
-
-  return {
-    agent,
-    roleSchema,
-    role,
-    workflow,
-    threadStart,
-    threadStep,
-    threadEnd,
-    content,
-    reactSession,
-    reactTurn,
-    reactToolCall,
-  };
-}

packages/json-cas-workflow/src/types.ts

@@ -1,111 +0,0 @@
-import type { Hash } from "@uncaged/json-cas";
-
-// ── Definition layer ──────────────────────────────────────────────────────────
-
-export type AgentPayload = {
-  package: string;
-  version: string;
-  config: Record<string, unknown>;
-};
-
-/** A JSON Schema document stored as-is. */
-export type RoleSchemaPayload = Record<string, unknown>;
-
-export type RolePayload = {
-  name: string;
-  description: string;
-  systemPrompt: string;
-  extractPrompt: string;
-  /** cas_ref → role-schema */
-  schema: Hash;
-};
-
-export type WorkflowTransition = {
-  from: string;
-  to: string;
-  when: string | null;
-};
-
-export type WorkflowPayload = {
-  name: string;
-  description: string;
-  /** cas_ref → role */
-  roles: Record<string, Hash>;
-  moderator: WorkflowTransition[];
-};
-
-// ── Execution layer ───────────────────────────────────────────────────────────
-
-export type ThreadStartPayload = {
-  /** cas_ref → workflow */
-  workflow: Hash;
-  input: string;
-  depth: number;
-  /** cas_ref → thread-start | null */
-  parentThread: Hash | null;
-  /** cas_ref → agent */
-  agents: Record<string, Hash>;
-};
-
-export type ThreadStepPayload = {
-  role: string;
-  meta: Record<string, unknown>;
-  /** cas_ref → content */
-  content: Hash;
-  /** cas_ref → react-session */
-  react: Hash;
-  /** cas_ref → thread-start */
-  start: Hash;
-  /** cas_ref → thread-step | null */
-  previous: Hash | null;
-};
-
-export type ThreadEndPayload = {
-  returnCode: number;
-  summary: string;
-  /** cas_ref → thread-start */
-  start: Hash;
-  /** cas_ref → thread-step */
-  lastStep: Hash;
-};
-
-export type ContentPayload = {
-  text: string;
-};
-
-// ── React layer ───────────────────────────────────────────────────────────────
-
-export type ReactSessionPayload = {
-  /** cas_ref → agent */
-  agent: Hash;
-  role: string;
-  /** cas_ref → react-turn */
-  turns: Hash[];
-  totalTokens: number;
-  durationMs: number;
-};
-
-export type ReactTurnTokens = {
-  input: number;
-  output: number;
-};
-
-export type ReactTurnPayload = {
-  /** cas_ref → content */
-  input: Hash;
-  /** cas_ref → content */
-  output: Hash;
-  /** cas_ref → react-tool-call */
-  toolCalls: Hash[];
-  tokens: ReactTurnTokens;
-  latencyMs: number;
-};
-
-export type ReactToolCallPayload = {
-  name: string;
-  /** cas_ref → content (arguments) */
-  arguments: Hash;
-  /** cas_ref → content (result) */
-  result: Hash;
-  durationMs: number;
-};

packages/json-cas-workflow/tsconfig.json

@@ -1,8 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "dist"
-  },
-  "include": ["src"]
-}

packages/json-cas/CHANGELOG.md

@@ -0,0 +1,47 @@
+# @uncaged/json-cas
+
+## 0.6.0
+
+### Minor Changes
+
+- Unified `{ type, value }` envelope output for all CLI commands (RFC [#67](https://github.com/uncaged/json-cas/issues/67)).
+
+  ### Breaking Changes
+
+  - Removed `init`, `bootstrap`, `cat`, `schema put/get/list/validate` commands
+  - All CLI command outputs now wrapped in `{ type, value }` envelope (except `render`)
+  - `openStore()` is now async and auto-bootstraps
+
+  ### New Features
+
+  - 18 `@output/*` schemas registered at bootstrap
+  - `list --type <hash-or-alias>` command (replaces `schema list`)
+  - `verify` now checks both hash integrity and schema validation
+  - `wrapEnvelope()` helper exported from `@uncaged/json-cas`
+  - `openStore()` in `@uncaged/json-cas-fs` — async, auto mkdir + bootstrap
+  - Default LiquidJS templates for all output schemas
+  - Pipe composition: any command output can be piped to `render -p`
+
+## 0.5.3
+
+### Patch Changes
+
+- feat: add oneOf support to meta-schema validation
+
+  Added `oneOf` to `ALLOWED_SCHEMA_KEYS` and corresponding validation logic
+  in `isValidSchema`. This enables workflow frontmatter schemas that use
+  `oneOf` discriminated unions for multi-exit role definitions.
+
+## 0.3.0
+
+### Minor Changes
+
+- Disallow self-referencing nodes in put(). typeHash is now required (no null). Self-ref only via bootstrap().
+
+## 0.2.0
+
+### Minor Changes
+
+- Add listByType(typeHash) to Store interface for O(1) type-based queries, with append-only fs index
+
+## 0.1.3

packages/json-cas/README.md

@@ -0,0 +1,159 @@
+# @uncaged/json-cas
+
+Core CAS engine — hashing, schema, store, verify, bootstrap.
+
+## Overview
+
+`@uncaged/json-cas` is the foundation of the json-cas monorepo. It defines content-addressed nodes (`CasNode`), the `Store` interface, XXH64-based hashing with deterministic CBOR, JSON Schema registration and validation (including `cas_ref` links between nodes), bootstrap seeding, and integrity verification.
+
+Other packages build on this layer: `json-cas-fs` provides persistence, and `cli-json-cas` exposes store operations on the command line.
+
+**Dependencies:** `ajv`, `cborg`, `xxhash-wasm`
+
+## Installation
+
+```bash
+bun add @uncaged/json-cas
+```
+
+## API
+
+All symbols below are exported from `src/index.ts`.
+
+### Types
+
+```typescript
+/** 13-character uppercase Crockford Base32 (XXH64) */
+type Hash = string;
+
+type CasNode<T = unknown> = {
+  type: Hash;
+  payload: T;
+  timestamp: number; // Unix epoch ms
+};
+
+type Store = {
+  put(typeHash: Hash, payload: unknown): Promise<Hash>;
+  get(hash: Hash): CasNode | null;
+  has(hash: Hash): boolean;
+  listByType(typeHash: Hash): Hash[];
+};
+
+type JSONSchema = Record<string, unknown>;
+
+type BootstrapCapableStore = Store & {
+  [BOOTSTRAP_STORE](payload: unknown): Promise<Hash>;
+};
+```
+
+### Hashing
+
+```typescript
+function computeHash(typeHash: Hash, payload: unknown): Promise<Hash>;
+function computeSelfHash(payload: unknown): Promise<Hash>;
+function cborEncode(value: unknown): Uint8Array;
+```
+
+`computeHash` — `XXH64(utf8(typeHash) ++ CBOR(payload))` for normal nodes.
+
+`computeSelfHash` — `XXH64(CBOR(payload))` for bootstrap nodes where `type === hash`.
+
+### Bootstrap
+
+```typescript
+const BOOTSTRAP_STORE: unique symbol;
+
+async function bootstrap(store: Store): Promise<Hash>;
+```
+
+Writes the meta-schema seed node (idempotent). Requires a `BootstrapCapableStore` (e.g. from `createMemoryStore()`).
+
+### Schema
+
+```typescript
+class SchemaValidationError extends Error;
+
+async function putSchema(store: Store, jsonSchema: JSONSchema): Promise<Hash>;
+function getSchema(store: Store, typeHash: Hash): JSONSchema | null;
+function validate(store: Store, node: CasNode): boolean;
+function refs(store: Store, node: CasNode): Hash[];
+function walk(
+  store: Store,
+  rootHash: Hash,
+  visitor: (hash: Hash, node: CasNode) => void,
+): void;
+```
+
+- `putSchema` — stores a schema typed by the meta-schema; returned hash is the `typeHash` for conforming payloads.
+- `refs` — collects all `format: "cas_ref"` values in the payload per schema shape.
+- `walk` — BFS from `rootHash`, following `cas_ref` edges; cycles are visited once.
+
+### Store
+
+```typescript
+function createMemoryStore(): BootstrapCapableStore;
+```
+
+In-memory `Store` with type indexing, suitable for tests and ephemeral use.
+
+### Verify
+
+```typescript
+async function verify(hash: Hash, node: CasNode): Promise<boolean>;
+```
+
+Recomputes hash from `node` and compares to `hash` (self-referencing vs normal rules).
+
+### Example
+
+```typescript
+import {
+  bootstrap,
+  createMemoryStore,
+  putSchema,
+  refs,
+  validate,
+  walk,
+} from "@uncaged/json-cas";
+
+const store = createMemoryStore();
+const metaHash = await bootstrap(store);
+
+const personType = await putSchema(store, {
+  type: "object",
+  properties: {
+    name: { type: "string" },
+    friend: { type: "string", format: "cas_ref" },
+  },
+  required: ["name"],
+  additionalProperties: false,
+});
+
+const aliceHash = await store.put(personType, { name: "Alice" });
+const bobHash = await store.put(personType, {
+  name: "Bob",
+  friend: aliceHash,
+});
+
+const bob = store.get(bobHash)!;
+console.log(validate(store, bob));           // true
+console.log(refs(store, bob));               // [aliceHash]
+walk(store, bobHash, (h) => console.log(h)); // bobHash, aliceHash
+```
+
+## Internal Structure
+
+| File | Purpose |
+|------|---------|
+| `types.ts` | `Hash`, `CasNode`, `Store` |
+| `hash.ts` | `computeHash`, `computeSelfHash` |
+| `cbor.ts` | Deterministic CBOR encoding |
+| `bootstrap-capable.ts` | `BOOTSTRAP_STORE` symbol and capability check |
+| `bootstrap.ts` | Meta-schema seed and `bootstrap()` |
+| `store.ts` | `createMemoryStore()` |
+| `mem-store.ts` | Alternate in-memory store (tests only; not exported) |
+| `schema.ts` | Schema put/get/validate, `refs`, `walk` |
+| `verify.ts` | Node integrity verification |
+| `index.ts` | Public exports |
+
+Tests live in `src/*.test.ts` and `tests/`.

packages/json-cas/package.json

@@ -1,17 +1,27 @@
 {
   "name": "@uncaged/json-cas",
-"version": "0.1.1",
+  "version": "0.6.0",
   "type": "module",
-  "main": "./src/index.ts",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
   },
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
-    "test": "bun test"
+    "test": "bun test",
+    "prepublishOnly": "bash ../../scripts/check-workspace-deps.sh"
   },
   "dependencies": {
     "ajv": "^8.20.0",
     "cborg": "^4.2.3",
+    "liquidjs": "^10.27.0",
     "xxhash-wasm": "^1.1.0"
   }
 }

packages/json-cas/src/bootstrap-capable.ts

@@ -0,0 +1,16 @@
+import type { Hash, Store } from "./types.js";
+
+/** @internal Store implementations attach this for bootstrap() only. */
+export const BOOTSTRAP_STORE = Symbol.for("@uncaged/json-cas/bootstrap-store");
+
+export type BootstrapCapableStore = Store & {
+  [BOOTSTRAP_STORE](payload: unknown): Promise<Hash>;
+};
+
+export function isBootstrapCapableStore(
+  store: Store,
+): store is BootstrapCapableStore {
+  return (
+    typeof (store as BootstrapCapableStore)[BOOTSTRAP_STORE] === "function"
+  );
+}

packages/json-cas/src/bootstrap.test.ts

@@ -0,0 +1,340 @@
+import { describe, expect, test } from "bun:test";
+import { bootstrap } from "./bootstrap.js";
+import type { JSONSchema } from "./schema.js";
+import { getSchema } from "./schema.js";
+import { createMemoryStore } from "./store.js";
+
+const OUTPUT_ALIASES = [
+  "@output/put",
+  "@output/get",
+  "@output/has",
+  "@output/hash",
+  "@output/verify",
+  "@output/refs",
+  "@output/walk",
+  "@output/list",
+  "@output/list-meta",
+  "@output/list-schema",
+  "@output/var-set",
+  "@output/var-get",
+  "@output/var-delete",
+  "@output/var-tag",
+  "@output/var-list",
+  "@output/template-set",
+  "@output/template-get",
+  "@output/template-list",
+  "@output/template-delete",
+  "@output/gc",
+] as const;
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Built-in Schema Registration Tests
+// ──────────────────────────────────────────────────────────────────────────────
+
+describe("bootstrap - Built-in Schemas", () => {
+  test("should return map of 26 built-in schema aliases to hashes", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+
+    // Should return object with 6 primitive + 20 output aliases = 26
+    expect(builtinSchemas).toHaveProperty("@schema");
+    expect(builtinSchemas).toHaveProperty("@string");
+    expect(builtinSchemas).toHaveProperty("@number");
+    expect(builtinSchemas).toHaveProperty("@object");
+    expect(builtinSchemas).toHaveProperty("@array");
+    expect(builtinSchemas).toHaveProperty("@bool");
+
+    for (const alias of OUTPUT_ALIASES) {
+      expect(builtinSchemas).toHaveProperty(alias);
+    }
+
+    expect(Object.keys(builtinSchemas)).toHaveLength(26);
+
+    // All values should be valid hashes
+    for (const [_alias, hash] of Object.entries(builtinSchemas)) {
+      expect(typeof hash).toBe("string");
+      expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    }
+  });
+
+  test("should register @schema as meta-schema alias", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+
+    const metaHash = builtinSchemas["@schema"];
+    if (!metaHash) throw new Error("@schema not found");
+
+    const metaSchema = getSchema(store, metaHash);
+    expect(metaSchema).not.toBeNull();
+    expect(metaSchema?.type).toBe("object");
+    expect(metaSchema?.description).toBe("json-cas JSON Schema meta-schema");
+  });
+
+  test("should register @string schema correctly", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+
+    const stringHash = builtinSchemas["@string"];
+    if (!stringHash) throw new Error("@string not found");
+
+    const stringSchema = getSchema(store, stringHash);
+    expect(stringSchema).toEqual({ type: "string" });
+  });
+
+  test("should register @number schema correctly", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+
+    const numberHash = builtinSchemas["@number"];
+    if (!numberHash) throw new Error("@number not found");
+
+    const numberSchema = getSchema(store, numberHash);
+    expect(numberSchema).toEqual({ type: "number" });
+  });
+
+  test("should register @object schema correctly", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+
+    const objectHash = builtinSchemas["@object"];
+    if (!objectHash) throw new Error("@object not found");
+
+    const objectSchema = getSchema(store, objectHash);
+    expect(objectSchema).toEqual({ type: "object" });
+  });
+
+  test("should register @array schema correctly", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+
+    const arrayHash = builtinSchemas["@array"];
+    if (!arrayHash) throw new Error("@array not found");
+
+    const arraySchema = getSchema(store, arrayHash);
+    expect(arraySchema).toEqual({ type: "array" });
+  });
+
+  test("should register @bool schema correctly", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+
+    const boolHash = builtinSchemas["@bool"];
+    if (!boolHash) throw new Error("@bool not found");
+
+    const boolSchema = getSchema(store, boolHash);
+    expect(boolSchema).toEqual({ type: "boolean" });
+  });
+
+  test("should return same hashes on repeated bootstrap calls", async () => {
+    const store = createMemoryStore();
+    const first = await bootstrap(store);
+    const second = await bootstrap(store);
+
+    expect(first).toEqual(second);
+
+    // Verify each alias points to same hash
+    expect(first["@string"]).toBe(second["@string"]);
+    expect(first["@number"]).toBe(second["@number"]);
+    expect(first["@object"]).toBe(second["@object"]);
+    expect(first["@array"]).toBe(second["@array"]);
+    expect(first["@bool"]).toBe(second["@bool"]);
+    expect(first["@schema"]).toBe(second["@schema"]);
+  });
+
+  test("all built-in schemas should be typed by meta-schema", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+
+    const metaHash = builtinSchemas["@schema"];
+    if (!metaHash) throw new Error("@schema not found");
+
+    for (const [alias, hash] of Object.entries(builtinSchemas)) {
+      if (alias === "@schema") continue; // meta-schema is self-typed
+
+      const node = store.get(hash);
+      expect(node).not.toBeNull();
+      expect(node?.type).toBe(metaHash);
+    }
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────────────────
+// @output/* Schema Registration Tests
+// ──────────────────────────────────────────────────────────────────────────────
+
+describe("bootstrap - @output/* Schemas", () => {
+  test("each @output/* schema has a title", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+
+    for (const alias of OUTPUT_ALIASES) {
+      const hash = aliases[alias];
+      if (!hash) throw new Error(`${alias} not found`);
+
+      const schema = getSchema(store, hash) as JSONSchema;
+      expect(schema).not.toBeNull();
+      expect(typeof schema.title).toBe("string");
+      expect((schema.title as string).startsWith("ucas ")).toBe(true);
+    }
+  });
+
+  test("@output/put schema describes a cas_ref string", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const hash = aliases["@output/put"];
+    if (!hash) throw new Error("@output/put not found");
+
+    const schema = getSchema(store, hash);
+    expect(schema).toEqual({
+      type: "string",
+      format: "cas_ref",
+      title: "ucas put result",
+    });
+  });
+
+  test("@output/get schema describes object with type, payload, timestamp", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const hash = aliases["@output/get"];
+    if (!hash) throw new Error("@output/get not found");
+
+    const schema = getSchema(store, hash) as JSONSchema;
+    expect(schema.type).toBe("object");
+    expect(schema.title).toBe("ucas get result");
+
+    const props = schema.properties as Record<string, JSONSchema>;
+    expect(props.type).toEqual({ type: "string", format: "cas_ref" });
+    expect(props.payload).toEqual({});
+    expect(props.timestamp).toEqual({ type: "number" });
+  });
+
+  test("@output/has schema describes a boolean", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const hash = aliases["@output/has"];
+    if (!hash) throw new Error("@output/has not found");
+
+    expect(getSchema(store, hash)).toEqual({
+      type: "boolean",
+      title: "ucas has result",
+    });
+  });
+
+  test("@output/verify schema describes enum of ok|corrupted|invalid", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const hash = aliases["@output/verify"];
+    if (!hash) throw new Error("@output/verify not found");
+
+    const schema = getSchema(store, hash);
+    expect(schema).toEqual({
+      type: "string",
+      enum: ["ok", "corrupted", "invalid"],
+      title: "ucas verify result",
+    });
+  });
+
+  test("@output/refs schema describes array of cas_ref strings", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const hash = aliases["@output/refs"];
+    if (!hash) throw new Error("@output/refs not found");
+
+    expect(getSchema(store, hash)).toEqual({
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+      title: "ucas refs result",
+    });
+  });
+
+  test("@output/gc schema describes object with gc stats fields", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const hash = aliases["@output/gc"];
+    if (!hash) throw new Error("@output/gc not found");
+
+    const schema = getSchema(store, hash) as JSONSchema;
+    expect(schema.type).toBe("object");
+    expect(schema.title).toBe("ucas gc result");
+
+    const props = schema.properties as Record<string, JSONSchema>;
+    expect(props.total).toEqual({ type: "number" });
+    expect(props.reachable).toEqual({ type: "number" });
+    expect(props.collected).toEqual({ type: "number" });
+    expect(props.scanned).toEqual({ type: "number" });
+  });
+
+  test("@output/var-set schema describes a Variable object", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const hash = aliases["@output/var-set"];
+    if (!hash) throw new Error("@output/var-set not found");
+
+    const schema = getSchema(store, hash) as JSONSchema;
+    expect(schema.type).toBe("object");
+    expect(schema.title).toBe("ucas var set result");
+
+    const props = schema.properties as Record<string, JSONSchema>;
+    expect(props.name).toEqual({ type: "string" });
+    expect(props.schema).toEqual({ type: "string", format: "cas_ref" });
+    expect(props.value).toEqual({ type: "string", format: "cas_ref" });
+  });
+
+  test("@output/var-list schema describes array of Variable objects", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const hash = aliases["@output/var-list"];
+    if (!hash) throw new Error("@output/var-list not found");
+
+    const schema = getSchema(store, hash) as JSONSchema;
+    expect(schema.type).toBe("array");
+    expect(schema.title).toBe("ucas var list result");
+
+    const items = schema.items as JSONSchema;
+    expect(items.type).toBe("object");
+    const props = items.properties as Record<string, JSONSchema>;
+    expect(props.name).toEqual({ type: "string" });
+  });
+
+  test("@output/template-delete schema describes object with deleted boolean", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const hash = aliases["@output/template-delete"];
+    if (!hash) throw new Error("@output/template-delete not found");
+
+    expect(getSchema(store, hash)).toEqual({
+      type: "object",
+      properties: { deleted: { type: "boolean" } },
+      title: "ucas template delete result",
+    });
+  });
+
+  test("all @output/* schemas are distinct hashes", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+
+    const outputHashes = OUTPUT_ALIASES.map((alias) => aliases[alias]);
+    const uniqueHashes = new Set(outputHashes);
+    expect(uniqueHashes.size).toBe(OUTPUT_ALIASES.length);
+  });
+});
+
+describe("bootstrap - meta and schemas indexes (D1)", () => {
+  test("listMeta contains the bootstrap meta-schema hash", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const metaHash = aliases["@schema"];
+    expect(store.listMeta()).toContain(metaHash as string);
+  });
+
+  test("listSchemas contains meta-schema and all built-in schemas", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    const schemas = store.listSchemas();
+
+    for (const [, hash] of Object.entries(aliases)) {
+      expect(schemas).toContain(hash);
+    }
+    expect(schemas.length).toBeGreaterThanOrEqual(6);
+  });
+});

packages/json-cas/src/bootstrap.ts

@@ -1,27 +1,319 @@
+import {
+  BOOTSTRAP_STORE,
+  isBootstrapCapableStore,
+} from "./bootstrap-capable.js";
 import type { Hash, Store } from "./types.js";
 
-/**
- * The meta-schema seed payload: describes the structure of every CAS node.
- * This is the root type from which all other type nodes derive.
- */
-const BOOTSTRAP_PAYLOAD = {
-  description: "json-cas meta-schema seed",
-  hashAlgorithm: "xxh64",
-  hashEncoding: "crockford-base32-13",
-  nodeSchema: {
-    payload: "any",
-    timestamp: "number",
-    type: "Hash",
-  },
-  payloadEncoding: "cbor-rfc8949-deterministic",
-  version: "1",
-} as const;
+const JSON_SCHEMA_TYPES = [
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "object",
+  "array",
+  "null",
+] as const;
 
 /**
- * Write the meta-schema seed node into the store.
- * The returned hash equals the node's own type field (self-referencing).
- * Idempotent: calling bootstrap multiple times returns the same hash.
+ * Self-describing JSON Schema meta-schema for the supported schema subset.
+ * Stored as the bootstrap node's payload; its hash equals the node's type field.
  */
-export async function bootstrap(store: Store): Promise<Hash> {
-  return store.put(null, BOOTSTRAP_PAYLOAD);
+const BOOTSTRAP_PAYLOAD = {
+  type: "object",
+  additionalProperties: false,
+  description: "json-cas JSON Schema meta-schema",
+  properties: {
+    type: {
+      anyOf: [
+        { type: "string", enum: [...JSON_SCHEMA_TYPES] },
+        {
+          type: "array",
+          items: { type: "string", enum: [...JSON_SCHEMA_TYPES] },
+        },
+      ],
+    },
+    properties: {
+      type: "object",
+      additionalProperties: { type: "object", additionalProperties: false },
+    },
+    required: {
+      type: "array",
+      items: { type: "string" },
+    },
+    additionalProperties: {
+      anyOf: [
+        { type: "boolean" },
+        { type: "object", additionalProperties: false },
+      ],
+    },
+    anyOf: {
+      type: "array",
+      items: { type: "object", additionalProperties: false },
+    },
+    oneOf: {
+      type: "array",
+      items: { type: "object", additionalProperties: false },
+    },
+    items: { type: "object", additionalProperties: false },
+    format: { type: "string" },
+    title: { type: "string" },
+    enum: { type: "array" },
+    const: {},
+    description: { type: "string" },
+    // P1 leaf constraints
+    minimum: { type: "number" },
+    maximum: { type: "number" },
+    exclusiveMinimum: { type: "number" },
+    exclusiveMaximum: { type: "number" },
+    minLength: { type: "number" },
+    maxLength: { type: "number" },
+    pattern: { type: "string" },
+    minItems: { type: "number" },
+    maxItems: { type: "number" },
+    uniqueItems: { type: "boolean" },
+    // P2 combinators + conditionals
+    allOf: {
+      type: "array",
+      items: { type: "object", additionalProperties: false },
+    },
+    if: { type: "object", additionalProperties: false },
+    // biome-ignore lint/suspicious/noThenProperty: JSON Schema keyword, not a thenable
+    then: { type: "object", additionalProperties: false },
+    else: { type: "object", additionalProperties: false },
+    patternProperties: {
+      type: "object",
+      additionalProperties: { type: "object", additionalProperties: false },
+    },
+    prefixItems: {
+      type: "array",
+      items: { type: "object", additionalProperties: false },
+    },
+    // P2 leaf constraints
+    multipleOf: { type: "number" },
+    minProperties: { type: "number" },
+    maxProperties: { type: "number" },
+    default: {},
+    // P3 combinators
+    not: { type: "object", additionalProperties: false },
+    contains: { type: "object", additionalProperties: false },
+    propertyNames: { type: "object", additionalProperties: false },
+    // P3 metadata
+    examples: { type: "array" },
+    readOnly: { type: "boolean" },
+    writeOnly: { type: "boolean" },
+    deprecated: { type: "boolean" },
+    $comment: { type: "string" },
+  },
+} as const;
+
+const VARIABLE_PROPERTIES = {
+  name: { type: "string" },
+  schema: { type: "string", format: "cas_ref" },
+  value: { type: "string", format: "cas_ref" },
+  created: { type: "number" },
+  updated: { type: "number" },
+  tags: { type: "object" },
+  labels: { type: "array", items: { type: "string" } },
+} as const;
+
+const OUTPUT_SCHEMAS: ReadonlyArray<
+  readonly [alias: string, schema: Record<string, unknown>]
+> = [
+  [
+    "@output/put",
+    { type: "string", format: "cas_ref", title: "ucas put result" },
+  ],
+  [
+    "@output/get",
+    {
+      type: "object",
+      properties: {
+        type: { type: "string", format: "cas_ref" },
+        payload: {},
+        timestamp: { type: "number" },
+      },
+      title: "ucas get result",
+    },
+  ],
+  ["@output/has", { type: "boolean", title: "ucas has result" }],
+  [
+    "@output/hash",
+    { type: "string", format: "cas_ref", title: "ucas hash result" },
+  ],
+  [
+    "@output/verify",
+    {
+      type: "string",
+      enum: ["ok", "corrupted", "invalid"],
+      title: "ucas verify result",
+    },
+  ],
+  [
+    "@output/refs",
+    {
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+      title: "ucas refs result",
+    },
+  ],
+  [
+    "@output/walk",
+    {
+      type: "array",
+      items: { type: "string" },
+      title: "ucas walk result",
+    },
+  ],
+  [
+    "@output/list",
+    {
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+      title: "ucas list result",
+    },
+  ],
+  [
+    "@output/list-meta",
+    {
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+      title: "ucas list-meta result",
+    },
+  ],
+  [
+    "@output/list-schema",
+    {
+      type: "array",
+      items: { type: "string", format: "cas_ref" },
+      title: "ucas list-schema result",
+    },
+  ],
+  [
+    "@output/var-set",
+    {
+      type: "object",
+      properties: { ...VARIABLE_PROPERTIES },
+      title: "ucas var set result",
+    },
+  ],
+  [
+    "@output/var-get",
+    {
+      type: "object",
+      properties: { ...VARIABLE_PROPERTIES },
+      title: "ucas var get result",
+    },
+  ],
+  [
+    "@output/var-delete",
+    {
+      type: "object",
+      properties: { ...VARIABLE_PROPERTIES },
+      title: "ucas var delete result",
+    },
+  ],
+  [
+    "@output/var-tag",
+    {
+      type: "object",
+      properties: { ...VARIABLE_PROPERTIES },
+      title: "ucas var tag result",
+    },
+  ],
+  [
+    "@output/var-list",
+    {
+      type: "array",
+      items: { type: "object", properties: { ...VARIABLE_PROPERTIES } },
+      title: "ucas var list result",
+    },
+  ],
+  [
+    "@output/template-set",
+    {
+      type: "object",
+      properties: {
+        schemaHash: { type: "string", format: "cas_ref" },
+        contentHash: { type: "string", format: "cas_ref" },
+      },
+      title: "ucas template set result",
+    },
+  ],
+  [
+    "@output/template-get",
+    { type: "string", title: "ucas template get result" },
+  ],
+  [
+    "@output/template-list",
+    {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          schemaHash: { type: "string", format: "cas_ref" },
+          contentHash: { type: "string", format: "cas_ref" },
+        },
+      },
+      title: "ucas template list result",
+    },
+  ],
+  [
+    "@output/template-delete",
+    {
+      type: "object",
+      properties: { deleted: { type: "boolean" } },
+      title: "ucas template delete result",
+    },
+  ],
+  [
+    "@output/gc",
+    {
+      type: "object",
+      properties: {
+        total: { type: "number" },
+        reachable: { type: "number" },
+        collected: { type: "number" },
+        scanned: { type: "number" },
+      },
+      title: "ucas gc result",
+    },
+  ],
+];
+
+/**
+ * Write the meta-schema seed node into the store and register built-in schemas.
+ * The returned object contains aliases for the meta-schema, 5 primitive schemas,
+ * and 18 @output/* schemas (24 total).
+ * Idempotent: calling bootstrap multiple times returns the same hashes.
+ */
+export async function bootstrap(store: Store): Promise<Record<string, Hash>> {
+  if (!isBootstrapCapableStore(store)) {
+    throw new Error("Store does not support bootstrap");
+  }
+
+  // 1. Bootstrap the meta-schema (self-referential)
+  const metaHash = await store[BOOTSTRAP_STORE](BOOTSTRAP_PAYLOAD);
+
+  // 2. Register built-in primitive schemas directly (without putSchema to avoid recursion)
+  const stringHash = await store.put(metaHash, { type: "string" });
+  const numberHash = await store.put(metaHash, { type: "number" });
+  const objectHash = await store.put(metaHash, { type: "object" });
+  const arrayHash = await store.put(metaHash, { type: "array" });
+  const boolHash = await store.put(metaHash, { type: "boolean" });
+
+  // 3. Register @output/* schemas
+  const aliases: Record<string, Hash> = {
+    "@schema": metaHash,
+    "@string": stringHash,
+    "@number": numberHash,
+    "@object": objectHash,
+    "@array": arrayHash,
+    "@bool": boolHash,
+  };
+
+  for (const [alias, schema] of OUTPUT_SCHEMAS) {
+    aliases[alias] = await store.put(metaHash, schema);
+  }
+
+  return aliases;
 }

packages/json-cas/src/gc.test.ts

@@ -0,0 +1,179 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bootstrap } from "./bootstrap.js";
+import { gc } from "./gc.js";
+import { putSchema } from "./schema.js";
+import { createMemoryStore } from "./store.js";
+import type { Store } from "./types.js";
+import { VariableStore } from "./variable-store.js";
+
+const tmpDbPath = () =>
+  join(
+    tmpdir(),
+    `test-gc-${Date.now()}-${Math.random().toString(36).slice(2)}.db`,
+  );
+
+describe("GC - Variable Model Refactoring", () => {
+  let store: Store;
+  let dbPath: string;
+
+  afterEach(() => {
+    try {
+      unlinkSync(dbPath);
+    } catch {
+      // Ignore cleanup errors
+    }
+  });
+
+  test("GC preserves variable-referenced nodes", async () => {
+    store = createMemoryStore();
+    await bootstrap(store);
+    const schema = { type: "object", properties: { name: { type: "string" } } };
+    const schemaHash = await putSchema(store, schema);
+
+    const hashRef = await store.put(schemaHash, { name: "referenced" });
+    const hashOrphan = await store.put(schemaHash, { name: "orphan" });
+
+    dbPath = tmpDbPath();
+    const varStore = new VariableStore(dbPath, store);
+
+    varStore.set("config", hashRef);
+
+    const stats = gc(store, varStore);
+
+    expect(store.has(hashRef)).toBe(true);
+    expect(store.has(hashOrphan)).toBe(false);
+    expect(stats.scanned).toBe(1);
+    expect(stats.collected).toBeGreaterThanOrEqual(1);
+
+    varStore.close();
+  });
+
+  test("GC preserves nodes from variables with same name, different schemas", async () => {
+    store = createMemoryStore();
+    await bootstrap(store);
+    const schemaA = { type: "object", properties: { x: { type: "number" } } };
+    const schemaB = { type: "object", properties: { y: { type: "string" } } };
+    const schemaAHash = await putSchema(store, schemaA);
+    const schemaBHash = await putSchema(store, schemaB);
+
+    const hashA = await store.put(schemaAHash, { x: 42 });
+    const hashB = await store.put(schemaBHash, { y: "hello" });
+    const hashOrphan = await store.put(schemaAHash, { x: 99 });
+
+    dbPath = tmpDbPath();
+    const varStore = new VariableStore(dbPath, store);
+
+    varStore.set("config", hashA);
+    varStore.set("config", hashB);
+
+    const stats = gc(store, varStore);
+
+    expect(store.has(hashA)).toBe(true);
+    expect(store.has(hashB)).toBe(true);
+    expect(store.has(hashOrphan)).toBe(false);
+    expect(stats.scanned).toBe(2);
+
+    varStore.close();
+  });
+
+  test("GC removes nodes after variable deletion", async () => {
+    store = createMemoryStore();
+    await bootstrap(store);
+    const schema = { type: "object", properties: { name: { type: "string" } } };
+    const schemaHash = await putSchema(store, schema);
+
+    const hashRef = await store.put(schemaHash, { name: "referenced" });
+
+    dbPath = tmpDbPath();
+    const varStore = new VariableStore(dbPath, store);
+
+    varStore.set("config", hashRef);
+    varStore.remove("config", schemaHash);
+
+    const stats = gc(store, varStore);
+
+    expect(store.has(hashRef)).toBe(false);
+    expect(stats.scanned).toBe(0);
+
+    varStore.close();
+  });
+
+  test("GC is global across all variables", async () => {
+    store = createMemoryStore();
+    await bootstrap(store);
+    const schemaA = { type: "object", properties: { x: { type: "number" } } };
+    const schemaB = { type: "object", properties: { y: { type: "string" } } };
+    const schemaAHash = await putSchema(store, schemaA);
+    const schemaBHash = await putSchema(store, schemaB);
+
+    const hash1 = await store.put(schemaAHash, { x: 1 });
+    const hash2 = await store.put(schemaAHash, { x: 2 });
+    const hash3 = await store.put(schemaBHash, { y: "a" });
+    const hashOrphan = await store.put(schemaAHash, { x: 999 });
+
+    dbPath = tmpDbPath();
+    const varStore = new VariableStore(dbPath, store);
+
+    varStore.set("uwf.thread", hash1);
+    varStore.set("uwf.workflow", hash2);
+    varStore.set("app.config", hash3);
+
+    const stats = gc(store, varStore);
+
+    expect(store.has(hash1)).toBe(true);
+    expect(store.has(hash2)).toBe(true);
+    expect(store.has(hash3)).toBe(true);
+    expect(store.has(hashOrphan)).toBe(false);
+    expect(stats.scanned).toBe(3);
+
+    varStore.close();
+  });
+
+  test("GC integration with refactored variable store", async () => {
+    store = createMemoryStore();
+    await bootstrap(store);
+
+    const schemaA = { type: "object", properties: { x: { type: "number" } } };
+    const schemaB = { type: "object", properties: { y: { type: "string" } } };
+    const schemaAHash = await putSchema(store, schemaA);
+    const schemaBHash = await putSchema(store, schemaB);
+
+    const hashA1 = await store.put(schemaAHash, { x: 1 });
+    const hashA2 = await store.put(schemaAHash, { x: 2 });
+    const hashB = await store.put(schemaBHash, { y: "hello" });
+    const hashOrphan1 = await store.put(schemaAHash, { x: 999 });
+    const hashOrphan2 = await store.put(schemaBHash, { y: "orphan" });
+
+    dbPath = tmpDbPath();
+    const varStore = new VariableStore(dbPath, store);
+
+    // Create variables
+    varStore.set("var1", hashA1);
+    varStore.set("var2", hashA2);
+    varStore.set("var3", hashB);
+
+    // First GC: orphans removed
+    let stats = gc(store, varStore);
+    expect(store.has(hashA1)).toBe(true);
+    expect(store.has(hashA2)).toBe(true);
+    expect(store.has(hashB)).toBe(true);
+    expect(store.has(hashOrphan1)).toBe(false);
+    expect(store.has(hashOrphan2)).toBe(false);
+    expect(stats.scanned).toBe(3);
+
+    // Delete one variable
+    varStore.remove("var2", schemaAHash);
+
+    // Second GC: hashA2 removed
+    stats = gc(store, varStore);
+    expect(store.has(hashA1)).toBe(true);
+    expect(store.has(hashA2)).toBe(false);
+    expect(store.has(hashB)).toBe(true);
+    expect(stats.scanned).toBe(2);
+
+    varStore.close();
+  });
+});

packages/json-cas/src/gc.ts

@@ -0,0 +1,94 @@
+import { walk } from "./schema.js";
+import type { Hash, Store } from "./types.js";
+import type { VariableStore } from "./variable-store.js";
+
+export interface GcStats {
+  total: number; // Total CAS nodes before GC
+  reachable: number; // Nodes marked as reachable
+  collected: number; // Nodes deleted (swept)
+  scanned: number; // Variables scanned as roots
+}
+
+/**
+ * Garbage collection: mark-and-sweep algorithm
+ * - Roots: all variable values (global, not scoped)
+ * - Mark: recursively walk refs from roots
+ * - Sweep: delete unmarked nodes
+ * - Schema preservation: schemas of reachable nodes are also marked
+ */
+export function gc(store: Store, varStore: VariableStore): GcStats {
+  // Get all variables (no filters → global)
+  const variables = varStore.list();
+  const scanned = variables.length;
+
+  // Collect unique root hashes from all variables
+  const roots = new Set<Hash>();
+  for (const variable of variables) {
+    roots.add(variable.value);
+  }
+
+  // Mark phase: walk from all roots
+  const reachable = new Set<Hash>();
+
+  for (const rootHash of roots) {
+    walk(store, rootHash, (hash, node) => {
+      // Mark the node itself
+      reachable.add(hash);
+      // Mark the schema (type) of the node
+      reachable.add(node.type);
+    });
+  }
+
+  // Walk the schema chain to ensure bootstrap meta-schema is preserved
+  // For each reachable schema, walk its schema chain (not its references)
+  const schemasToWalk = new Set<Hash>();
+  for (const hash of reachable) {
+    const node = store.get(hash);
+    if (node) {
+      schemasToWalk.add(node.type);
+    }
+  }
+
+  for (const schemaHash of schemasToWalk) {
+    // Walk the schema's type chain (meta-schema, etc.)
+    let current: Hash | null = schemaHash;
+    while (current !== null && !reachable.has(current)) {
+      reachable.add(current);
+      const node = store.get(current);
+      if (!node || node.type === current) {
+        // Self-referencing or missing node, stop
+        break;
+      }
+      current = node.type;
+    }
+  }
+
+  // Preserve all self-referencing nodes (bootstrap meta-schema)
+  // These are nodes where type === hash
+  const allHashes = store.listAll();
+  for (const hash of allHashes) {
+    const node = store.get(hash);
+    if (node && node.type === hash) {
+      reachable.add(hash);
+    }
+  }
+
+  // Count total nodes
+  const total = allHashes.length;
+
+  // Sweep phase: delete unmarked nodes
+  let collected = 0;
+  for (const hash of allHashes) {
+    if (!reachable.has(hash)) {
+      store.delete(hash);
+      collected++;
+    }
+  }
+
+  return {
+    total,
+    reachable: reachable.size,
+    collected,
+    scanned,
+  };
+}

packages/json-cas/src/index.test.ts

@@ -4,7 +4,7 @@ import { bootstrap } from "./bootstrap.js";
 import { cborEncode } from "./cbor.js";
 import { computeHash, computeSelfHash } from "./hash.js";
 import { createMemoryStore } from "./store.js";
-import type { CasNode } from "./types.js";
+import type { CasNode, Store } from "./types.js";
 import { verify } from "./verify.js";
 
 // ──────────────────────────────────────────────────────────────────────────────
@@ -97,7 +97,18 @@ describe("createMemoryStore – put and get", () => {
     const h1 = await store.put(typeHash, { n: 42 });
     const h2 = await store.put(typeHash, { n: 42 });
     expect(h1).toBe(h2);
-    expect(store.list()).toHaveLength(1);
+    expect(store.listByType(typeHash)).toHaveLength(1);
+  });
+
+  test("put does not create self-referencing nodes", async () => {
+    const store = createMemoryStore();
+    const payload = { name: "type-descriptor" };
+    const typeHash = await computeSelfHash(payload);
+    const hash = await store.put(typeHash, payload);
+
+    const node = store.get(hash);
+    expect(node?.type).toBe(typeHash);
+    expect(node?.type).not.toBe(hash);
   });
 
   test("timestamp is preserved on second put (idempotency)", async () => {
@@ -116,9 +127,9 @@ describe("createMemoryStore – put and get", () => {
 });
 
 // ──────────────────────────────────────────────────────────────────────────────
-// Step 4: store.has() and store.list()
+// Step 4: store.has()
 // ──────────────────────────────────────────────────────────────────────────────
-describe("createMemoryStore – has and list", () => {
+describe("createMemoryStore – has", () => {
   test("has returns false before put, true after", async () => {
     const store = createMemoryStore();
     const typeHash = await computeSelfHash({ name: "t" });
@@ -129,7 +140,7 @@ describe("createMemoryStore – has and list", () => {
     expect(store.has(hash)).toBe(true);
   });
 
-  test("list returns all stored hashes", async () => {
+  test("listByType returns all stored hashes for a type", async () => {
     const store = createMemoryStore();
     const typeHash = await computeSelfHash({ name: "t" });
 
@@ -137,16 +148,66 @@ describe("createMemoryStore – has and list", () => {
     const h2 = await store.put(typeHash, { a: 2 });
     const h3 = await store.put(typeHash, { a: 3 });
 
-    const all = store.list();
+    const all = store.listByType(typeHash);
     expect(all).toHaveLength(3);
     expect(all).toContain(h1);
     expect(all).toContain(h2);
     expect(all).toContain(h3);
   });
 
-  test("list returns empty array on fresh store", () => {
+  test("listByType returns empty array on fresh store", () => {
     const store = createMemoryStore();
-    expect(store.list()).toEqual([]);
+    expect(store.listByType("0000000000000")).toEqual([]);
+  });
+});
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Step 4b: store.listByType()
+// ──────────────────────────────────────────────────────────────────────────────
+describe("createMemoryStore – listByType", () => {
+  test("returns empty array for unknown type", () => {
+    const store = createMemoryStore();
+    expect(store.listByType("0000000000000")).toEqual([]);
+  });
+
+  test("returns all hashes for the given type", async () => {
+    const store = createMemoryStore();
+    const typeHash = await computeSelfHash({ name: "t" });
+    const otherType = await computeSelfHash({ name: "other" });
+
+    const h1 = await store.put(typeHash, { a: 1 });
+    const h2 = await store.put(typeHash, { a: 2 });
+    await store.put(otherType, { b: 1 });
+
+    const byType = store.listByType(typeHash);
+    expect(byType).toHaveLength(2);
+    expect(byType).toContain(h1);
+    expect(byType).toContain(h2);
+  });
+
+  test("idempotent put does not duplicate in listByType", async () => {
+    const store = createMemoryStore();
+    const typeHash = await computeSelfHash({ name: "t" });
+
+    const h1 = await store.put(typeHash, { n: 1 });
+    await store.put(typeHash, { n: 1 });
+
+    expect(store.listByType(typeHash)).toEqual([h1]);
+  });
+
+  test("bootstrap node is listed under its self type", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+    const hash = builtinSchemas["@schema"] ?? "";
+
+    // All built-in schemas should be typed by the meta-schema
+    const allTypedByMeta = store.listByType(hash);
+    expect(allTypedByMeta).toContain(hash); // meta-schema itself
+    expect(allTypedByMeta).toContain(builtinSchemas["@string"] ?? "");
+    expect(allTypedByMeta).toContain(builtinSchemas["@number"] ?? "");
+    expect(allTypedByMeta).toContain(builtinSchemas["@object"] ?? "");
+    expect(allTypedByMeta).toContain(builtinSchemas["@array"] ?? "");
+    expect(allTypedByMeta).toContain(builtinSchemas["@bool"] ?? "");
   });
 });
 
@@ -191,44 +252,73 @@ describe("verify", () => {
 // Step 6: bootstrap()
 // ──────────────────────────────────────────────────────────────────────────────
 describe("bootstrap", () => {
-  test("returns a valid 13-char hash", async () => {
-    const store = createMemoryStore();
-    const hash = await bootstrap(store);
-    expect(hash).toHaveLength(13);
-    expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  test("throws when store lacks internal bootstrap path", async () => {
+    const store: Store = {
+      put: async () => "0000000000000",
+      get: () => null,
+      has: () => false,
+      listByType: () => [],
+    };
+    await expect(bootstrap(store)).rejects.toThrow(
+      "Store does not support bootstrap",
+    );
   });
 
-  test("node is stored and retrievable", async () => {
+  test("returns a map with 26 built-in schema aliases", async () => {
     const store = createMemoryStore();
-    const hash = await bootstrap(store);
+    const builtinSchemas = await bootstrap(store);
 
-    expect(store.has(hash)).toBe(true);
-    const node = store.get(hash);
+    expect(builtinSchemas).toHaveProperty("@schema");
+    expect(builtinSchemas).toHaveProperty("@string");
+    expect(builtinSchemas).toHaveProperty("@number");
+    expect(builtinSchemas).toHaveProperty("@object");
+    expect(builtinSchemas).toHaveProperty("@array");
+    expect(builtinSchemas).toHaveProperty("@bool");
+
+    // All values should be valid hashes
+    for (const hash of Object.values(builtinSchemas)) {
+      expect(hash).toHaveLength(13);
+      expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    }
+
+    expect(Object.keys(builtinSchemas)).toHaveLength(26);
+  });
+
+  test("meta-schema node is stored and retrievable", async () => {
+    const store = createMemoryStore();
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
+
+    expect(store.has(metaHash)).toBe(true);
+    const node = store.get(metaHash);
     expect(node).not.toBeNull();
   });
 
-  test("node is self-referencing: type === hash", async () => {
+  test("meta-schema node is self-referencing: type === hash", async () => {
     const store = createMemoryStore();
-    const hash = await bootstrap(store);
-    const node = store.get(hash) as CasNode;
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
+    const node = store.get(metaHash) as CasNode;
 
-    expect(node.type).toBe(hash);
+    expect(node.type).toBe(metaHash);
   });
 
   test("bootstrap node passes verify()", async () => {
     const store = createMemoryStore();
-    const hash = await bootstrap(store);
-    const node = store.get(hash) as CasNode;
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
+    const node = store.get(metaHash) as CasNode;
 
-    expect(await verify(hash, node)).toBe(true);
+    expect(await verify(metaHash, node)).toBe(true);
   });
 
-  test("bootstrap is idempotent: same hash on repeated calls", async () => {
+  test("bootstrap is idempotent: same hashes on repeated calls", async () => {
     const store = createMemoryStore();
     const h1 = await bootstrap(store);
     const h2 = await bootstrap(store);
 
-    expect(h1).toBe(h2);
-    expect(store.list()).toHaveLength(1);
+    expect(h1).toEqual(h2);
+    // All 26 built-in schemas should be typed by the meta-schema
+    expect(store.listByType(h1["@schema"] ?? "")).toHaveLength(26);
   });
 });

packages/json-cas/src/index.ts

@@ -1,8 +1,38 @@
 export { bootstrap } from "./bootstrap.js";
+export type { BootstrapCapableStore } from "./bootstrap-capable.js";
+export { BOOTSTRAP_STORE } from "./bootstrap-capable.js";
 export { cborEncode } from "./cbor.js";
+export { type GcStats, gc } from "./gc.js";
 export { computeHash, computeSelfHash } from "./hash.js";
+export { renderWithTemplate } from "./liquid-render.js";
+export { registerOutputTemplates } from "./output-templates.js";
+export {
+  type RenderOptions,
+  render,
+  renderAsync,
+  renderDirect,
+} from "./render.js";
 export type { JSONSchema } from "./schema.js";
-export { getSchema, putSchema, refs, validate, walk } from "./schema.js";
+export {
+  getSchema,
+  putSchema,
+  refs,
+  SchemaValidationError,
+  validate,
+  walk,
+} from "./schema.js";
 export { createMemoryStore } from "./store.js";
 export type { CasNode, Hash, Store } from "./types.js";
+export type { Variable } from "./variable.js";
+export {
+  CasNodeNotFoundError,
+  createVariableStore,
+  InvalidTagFormatError,
+  InvalidVariableNameError,
+  SchemaMismatchError,
+  TagLabelConflictError,
+  VariableNotFoundError,
+  VariableStore,
+} from "./variable-store.js";
 export { verify } from "./verify.js";
+export { wrapEnvelope } from "./wrap-envelope.js";

packages/json-cas/src/liquid-render.ts

@@ -0,0 +1,285 @@
+import { type Context, Liquid, type TagToken } from "liquidjs";
+import type { RenderOptions } from "./render.js";
+import { putSchema } from "./schema.js";
+import type { Hash, Store } from "./types.js";
+import type { VariableStore } from "./variable-store.js";
+
+const DEFAULT_RESOLUTION = 1.0;
+const DEFAULT_DECAY = 0.5;
+const DEFAULT_EPSILON = 0.01;
+const FLOAT_TOLERANCE = 1e-10;
+
+/**
+ * Render a CAS node using LiquidJS templates with resolution-based decay.
+ * Templates are discovered via variables: @ucas/template/text/<type-hash>
+ */
+export async function renderWithTemplate(
+  store: Store,
+  varStore: VariableStore,
+  hash: Hash,
+  options?: RenderOptions,
+): Promise<string> {
+  const resolution = options?.resolution ?? DEFAULT_RESOLUTION;
+  const decay = options?.decay ?? DEFAULT_DECAY;
+  const epsilon = options?.epsilon ?? DEFAULT_EPSILON;
+
+  // Validate parameters
+  if (resolution < 0 || resolution > 1) {
+    throw new Error("resolution must be in [0, 1]");
+  }
+  if (decay <= 0 || decay > 1) {
+    throw new Error("decay must be in (0, 1]");
+  }
+  if (epsilon < 0) {
+    throw new Error("epsilon must be >= 0");
+  }
+
+  const visited = new Set<Hash>();
+
+  // Create Liquid engine
+  const engine = createLiquidEngine(store, varStore, decay);
+
+  return await renderNode(
+    engine,
+    store,
+    varStore,
+    hash,
+    resolution,
+    epsilon,
+    visited,
+  );
+}
+
+/**
+ * Create a Liquid engine instance with custom render tag
+ */
+function createLiquidEngine(
+  store: Store,
+  varStore: VariableStore,
+  globalDecay: number,
+): Liquid {
+  const engine = new Liquid({
+    strictFilters: false,
+    strictVariables: false,
+  });
+
+  // Type for storing parsed tag data
+  type RenderTagState = {
+    variable: string;
+    decay: number | undefined;
+  };
+
+  // Register custom {% render %} tag
+  // Capture store, varStore, globalDecay in closure
+  engine.registerTag("render", {
+    parse(token: TagToken) {
+      // Parse "variable" or "variable, decay: 0.7" syntax
+      const args = token.args.trim();
+      const match = args.match(/^(\S+)(?:,\s*decay:\s*([\d.]+))?$/);
+
+      if (!match) {
+        throw new Error(
+          `Invalid render tag syntax: ${args}. Expected: {% render variable %} or {% render variable, decay: 0.7 %}`,
+        );
+      }
+
+      // Store parsed values on the tag instance
+      const state = this as unknown as RenderTagState;
+      state.variable = match[1] as string;
+      state.decay = match[2] ? Number.parseFloat(match[2]) : undefined;
+
+      // Validate decay if provided
+      if (state.decay !== undefined) {
+        if (state.decay <= 0 || state.decay > 1) {
+          throw new Error("decay must be in (0, 1]");
+        }
+      }
+    },
+
+    async render(ctxLiquid: Context) {
+      // Access parsed values
+      const state = this as unknown as RenderTagState;
+      const variable = state.variable;
+      const explicitDecay = state.decay;
+
+      // Resolve the variable to a hash (split on dots for nested paths)
+      const variablePath = variable.split(".");
+      const value = ctxLiquid.get(variablePath);
+
+      // Handle null/undefined - render as empty
+      if (value === null || value === undefined) {
+        return "";
+      }
+
+      // Handle non-string values - render as empty
+      if (typeof value !== "string") {
+        return "";
+      }
+
+      const nodeHash = value as Hash;
+
+      // Get current render context
+      const currentResolution = ctxLiquid.get(["resolution"]) as number;
+      const currentEpsilon = ctxLiquid.get(["epsilon"]) as number;
+
+      // Compute child resolution using decay priority:
+      // 1. Template explicit decay (explicitDecay)
+      // 2. Global decay (from CLI/options)
+      // 3. Engine default (0.5)
+      const effectiveDecay =
+        explicitDecay !== undefined
+          ? explicitDecay
+          : (globalDecay ?? DEFAULT_DECAY);
+      const childResolution = currentResolution * effectiveDecay;
+
+      // Recursively render the referenced node
+      const visited = ctxLiquid.get(["__visited"]) as Set<Hash>;
+      const output = await renderNode(
+        engine,
+        store,
+        varStore,
+        nodeHash,
+        childResolution,
+        currentEpsilon,
+        visited,
+      );
+
+      return output;
+    },
+  });
+
+  return engine;
+}
+
+/**
+ * Render a single node with template or fallback to cas: reference
+ */
+async function renderNode(
+  engine: Liquid,
+  store: Store,
+  varStore: VariableStore,
+  hash: Hash,
+  currentResolution: number,
+  epsilon: number,
+  visited: Set<Hash>,
+): Promise<string> {
+  // Check if resolution is below threshold
+  if (currentResolution < epsilon + FLOAT_TOLERANCE) {
+    return `cas:${hash}`;
+  }
+
+  // Fetch the node
+  const node = store.get(hash);
+  if (node === null) {
+    return `cas:${hash}`;
+  }
+
+  // Cycle detection
+  if (visited.has(hash)) {
+    return `cas:${hash}`;
+  }
+  visited.add(hash);
+
+  try {
+    // Try to find a template for this node's type
+    const template = await findTemplate(store, varStore, node.type);
+
+    if (template === null) {
+      // No template found - this is handled by the caller (fallback to YAML)
+      // For now, return a simple representation
+      visited.delete(hash);
+      return renderFallback(store, node.payload);
+    }
+
+    // Render using the template
+    const context = {
+      resolution: currentResolution,
+      epsilon,
+      hash,
+      payload: node.payload,
+      type: node.type,
+      timestamp: node.timestamp,
+      __visited: visited, // Pass visited set through context
+    };
+
+    const output = await engine.parseAndRender(template, context);
+
+    visited.delete(hash);
+    return output;
+  } catch (error) {
+    visited.delete(hash);
+    throw error;
+  }
+}
+
+/**
+ * Find a template for a given type hash
+ */
+async function findTemplate(
+  store: Store,
+  varStore: VariableStore,
+  typeHash: Hash,
+): Promise<string | null> {
+  const varName = `@ucas/template/text/${typeHash}`;
+
+  try {
+    // Find the string schema hash (we need this to query variables)
+    const stringSchema = await putSchema(store, { type: "string" });
+
+    const variable = varStore.get(varName, stringSchema);
+    if (variable === null) {
+      return null;
+    }
+
+    const templateNode = store.get(variable.value);
+    if (templateNode === null) {
+      return null;
+    }
+
+    // Template should be a string
+    if (typeof templateNode.payload !== "string") {
+      return null;
+    }
+
+    return templateNode.payload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Fallback renderer for nodes without templates
+ */
+function renderFallback(_store: Store, payload: unknown): string {
+  // Simple YAML-like representation
+  if (payload === null) {
+    return "null\n";
+  }
+
+  if (typeof payload === "string") {
+    return `${payload}\n`;
+  }
+
+  if (typeof payload === "number" || typeof payload === "boolean") {
+    return `${payload}\n`;
+  }
+
+  if (Array.isArray(payload)) {
+    if (payload.length === 0) {
+      return "[]\n";
+    }
+    return `- ${payload.join("\n- ")}\n`;
+  }
+
+  if (typeof payload === "object") {
+    const obj = payload as Record<string, unknown>;
+    const keys = Object.keys(obj);
+    if (keys.length === 0) {
+      return "{}\n";
+    }
+    const pairs = keys.map((key) => `${key}: ${obj[key]}`);
+    return `${pairs.join("\n")}\n`;
+  }
+
+  return "null\n";
+}

packages/json-cas/src/mem-store.ts

@@ -0,0 +1,49 @@
+import type { BootstrapCapableStore } from "./bootstrap-capable.js";
+import { BOOTSTRAP_STORE } from "./bootstrap-capable.js";
+import { createMemoryStore } from "./store.js";
+import type { CasNode, Hash } from "./types.js";
+
+/** In-memory store wrapper used by schema validation tests. */
+export class MemStore implements BootstrapCapableStore {
+  readonly #inner: BootstrapCapableStore;
+
+  constructor() {
+    this.#inner = createMemoryStore();
+  }
+
+  put(typeHash: Hash, payload: unknown): Promise<Hash> {
+    return this.#inner.put(typeHash, payload);
+  }
+
+  get(hash: Hash): CasNode | null {
+    return this.#inner.get(hash);
+  }
+
+  has(hash: Hash): boolean {
+    return this.#inner.has(hash);
+  }
+
+  listByType(typeHash: Hash): Hash[] {
+    return this.#inner.listByType(typeHash);
+  }
+
+  listAll(): Hash[] {
+    return this.#inner.listAll();
+  }
+
+  listMeta(): Hash[] {
+    return this.#inner.listMeta();
+  }
+
+  listSchemas(): Hash[] {
+    return this.#inner.listSchemas();
+  }
+
+  delete(hash: Hash): void {
+    this.#inner.delete(hash);
+  }
+
+  [BOOTSTRAP_STORE](payload: unknown): Promise<Hash> {
+    return this.#inner[BOOTSTRAP_STORE](payload);
+  }
+}

packages/json-cas/src/output-templates.test.ts

@@ -0,0 +1,117 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { bootstrap } from "./bootstrap.js";
+import { registerOutputTemplates } from "./output-templates.js";
+import { createMemoryStore } from "./store.js";
+import type { Store } from "./types.js";
+import type { VariableStore } from "./variable-store.js";
+import { createVariableStore } from "./variable-store.js";
+
+const OUTPUT_ALIASES = [
+  "@output/put",
+  "@output/get",
+  "@output/has",
+  "@output/hash",
+  "@output/verify",
+  "@output/refs",
+  "@output/walk",
+  "@output/list",
+  "@output/var-set",
+  "@output/var-get",
+  "@output/var-delete",
+  "@output/var-tag",
+  "@output/var-list",
+  "@output/template-set",
+  "@output/template-get",
+  "@output/template-list",
+  "@output/template-delete",
+  "@output/gc",
+] as const;
+
+describe("registerOutputTemplates", () => {
+  let store: Store;
+  let varStore: VariableStore;
+  let tempDir: string;
+
+  afterEach(async () => {
+    varStore.close();
+    await rm(tempDir, { recursive: true });
+  });
+
+  test("registers a template for every @output/* schema", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "json-cas-tmpl-"));
+    store = createMemoryStore();
+    await bootstrap(store);
+    varStore = createVariableStore(join(tempDir, "vars.db"), store);
+
+    const registered = await registerOutputTemplates(store, varStore);
+
+    expect(Object.keys(registered)).toHaveLength(18);
+
+    for (const alias of OUTPUT_ALIASES) {
+      expect(registered).toHaveProperty(alias);
+    }
+  });
+
+  test("each template is retrievable via @ucas/template/text/<hash>", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "json-cas-tmpl-"));
+    store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    varStore = createVariableStore(join(tempDir, "vars.db"), store);
+
+    await registerOutputTemplates(store, varStore);
+
+    const stringHash = aliases["@string"];
+    if (!stringHash) throw new Error("@string not found");
+
+    for (const alias of OUTPUT_ALIASES) {
+      const schemaHash = aliases[alias];
+      if (!schemaHash) throw new Error(`${alias} not found`);
+
+      const varName = `@ucas/template/text/${schemaHash}`;
+      const variable = varStore.get(varName, stringHash);
+      if (variable === null) throw new Error(`Variable ${varName} not found`);
+
+      const templateNode = store.get(variable.value);
+      if (templateNode === null)
+        throw new Error(`Template node ${variable.value} not found`);
+      expect(typeof templateNode.payload).toBe("string");
+    }
+  });
+
+  test("is idempotent — safe to call multiple times", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "json-cas-tmpl-"));
+    store = createMemoryStore();
+    await bootstrap(store);
+    varStore = createVariableStore(join(tempDir, "vars.db"), store);
+
+    const first = await registerOutputTemplates(store, varStore);
+    const second = await registerOutputTemplates(store, varStore);
+
+    expect(first).toEqual(second);
+  });
+
+  test("@output/put template contains payload reference", async () => {
+    tempDir = await mkdtemp(join(tmpdir(), "json-cas-tmpl-"));
+    store = createMemoryStore();
+    const aliases = await bootstrap(store);
+    varStore = createVariableStore(join(tempDir, "vars.db"), store);
+
+    await registerOutputTemplates(store, varStore);
+
+    const putHash = aliases["@output/put"];
+    if (!putHash) throw new Error("@output/put not found");
+    const stringHash = aliases["@string"];
+    if (!stringHash) throw new Error("@string not found");
+
+    const variable = varStore.get(`@ucas/template/text/${putHash}`, stringHash);
+    if (variable === null)
+      throw new Error("@output/put template variable not found");
+
+    const templateNode = store.get(variable.value);
+    if (templateNode === null) throw new Error("Template node not found");
+    expect(templateNode.payload).toBe("{{ payload }}");
+  });
+});

packages/json-cas/src/output-templates.ts

@@ -0,0 +1,87 @@
+import { bootstrap } from "./bootstrap.js";
+import type { Hash, Store } from "./types.js";
+import type { VariableStore } from "./variable-store.js";
+
+const DEFAULT_TEMPLATES: ReadonlyArray<
+  readonly [alias: string, template: string]
+> = [
+  ["@output/put", "{{ payload }}"],
+  [
+    "@output/get",
+    "type: {{ payload.type }}\ntimestamp: {{ payload.timestamp }}",
+  ],
+  ["@output/has", "{{ payload }}"],
+  ["@output/hash", "{{ payload }}"],
+  ["@output/verify", "{{ payload }}"],
+  ["@output/refs", "{% for ref in payload %}{{ ref }}\n{% endfor %}"],
+  ["@output/walk", "{% for item in payload %}{{ item }}\n{% endfor %}"],
+  ["@output/list", "{% for item in payload %}{{ item }}\n{% endfor %}"],
+  [
+    "@output/var-set",
+    "name: {{ payload.name }}\nschema: {{ payload.schema }}\nvalue: {{ payload.value }}",
+  ],
+  [
+    "@output/var-get",
+    "name: {{ payload.name }}\nschema: {{ payload.schema }}\nvalue: {{ payload.value }}",
+  ],
+  [
+    "@output/var-delete",
+    "name: {{ payload.name }}\nschema: {{ payload.schema }}\nvalue: {{ payload.value }}",
+  ],
+  [
+    "@output/var-tag",
+    "name: {{ payload.name }}\nschema: {{ payload.schema }}\nvalue: {{ payload.value }}",
+  ],
+  [
+    "@output/var-list",
+    "{% for v in payload %}name: {{ v.name }}\nschema: {{ v.schema }}\nvalue: {{ v.value }}\n{% endfor %}",
+  ],
+  [
+    "@output/template-set",
+    "schemaHash: {{ payload.schemaHash }}\ncontentHash: {{ payload.contentHash }}",
+  ],
+  ["@output/template-get", "{{ payload }}"],
+  [
+    "@output/template-list",
+    "{% for t in payload %}schemaHash: {{ t.schemaHash }}\ncontentHash: {{ t.contentHash }}\n{% endfor %}",
+  ],
+  ["@output/template-delete", "deleted: {{ payload.deleted }}"],
+  [
+    "@output/gc",
+    "total: {{ payload.total }}\nreachable: {{ payload.reachable }}\ncollected: {{ payload.collected }}\nscanned: {{ payload.scanned }}",
+  ],
+];
+
+/**
+ * Register default LiquidJS templates for all @output/* schemas.
+ * Each template is stored as a @string CAS node and bound to
+ * the variable `@ucas/template/text/<schema-hash>`.
+ *
+ * Idempotent: safe to call multiple times.
+ */
+export async function registerOutputTemplates(
+  store: Store,
+  varStore: VariableStore,
+): Promise<Record<string, Hash>> {
+  const aliases = await bootstrap(store);
+  const stringHash = aliases["@string"];
+  if (stringHash === undefined) {
+    throw new Error("@string schema not found in bootstrap result");
+  }
+
+  const registered: Record<string, Hash> = {};
+
+  for (const [alias, template] of DEFAULT_TEMPLATES) {
+    const schemaHash = aliases[alias];
+    if (schemaHash === undefined) {
+      throw new Error(`Schema alias not found: ${alias}`);
+    }
+
+    const contentHash = await store.put(stringHash, template);
+    const varName = `@ucas/template/text/${schemaHash}`;
+    varStore.set(varName, contentHash);
+    registered[alias] = contentHash;
+  }
+
+  return registered;
+}

packages/json-cas/src/render.ts

@@ -0,0 +1,343 @@
+import { renderWithTemplate } from "./liquid-render.js";
+import { collectRefs, getSchema, putSchema, refs } from "./schema.js";
+import type { Hash, Store } from "./types.js";
+import type { VariableStore } from "./variable-store.js";
+import { CasNodeNotFoundError } from "./variable-store.js";
+
+export type RenderOptions = {
+  resolution?: number; // (0, 1], default 1.0
+  decay?: number; // (0, 1], default 0.5
+  epsilon?: number; // >= 0, default 0.01
+  varStore?: VariableStore; // Optional: for template lookup
+};
+
+const DEFAULT_RESOLUTION = 1.0;
+const DEFAULT_DECAY = 0.5;
+const DEFAULT_EPSILON = 0.01;
+// Small tolerance for floating point comparison
+const FLOAT_TOLERANCE = 1e-10;
+
+/**
+ * Extract and validate resolution/decay/epsilon from options.
+ */
+function validateAndExtractOptions(
+  options:
+    | Pick<RenderOptions, "resolution" | "decay" | "epsilon">
+    | null
+    | undefined,
+): { resolution: number; decay: number; epsilon: number } {
+  const resolution = options?.resolution ?? DEFAULT_RESOLUTION;
+  const decay = options?.decay ?? DEFAULT_DECAY;
+  const epsilon = options?.epsilon ?? DEFAULT_EPSILON;
+
+  if (resolution < 0 || resolution > 1) {
+    throw new Error("resolution must be in [0, 1]");
+  }
+  if (decay <= 0 || decay > 1) {
+    throw new Error("decay must be in (0, 1]");
+  }
+  if (epsilon < 0) {
+    throw new Error("epsilon must be >= 0");
+  }
+
+  return { resolution, decay, epsilon };
+}
+
+/**
+ * Render a CAS node as YAML with resolution-based decay.
+ * When resolution ≤ epsilon, nodes are rendered as opaque `cas:<hash>` references.
+ * This is the synchronous version without template support.
+ * For template support, use renderAsync() with varStore.
+ */
+export function render(
+  store: Store,
+  hash: Hash,
+  options?: RenderOptions,
+): string {
+  const { resolution, decay, epsilon } = validateAndExtractOptions(options);
+
+  // Check if root node exists
+  if (store.get(hash) === null) {
+    throw new CasNodeNotFoundError(hash);
+  }
+
+  const visited = new Set<Hash>();
+  return renderNode(store, hash, resolution, decay, epsilon, visited);
+}
+
+/**
+ * Async render with LiquidJS template support.
+ * When resolution ≤ epsilon, nodes are rendered as opaque `cas:<hash>` references.
+ * If varStore is provided, attempts to use LiquidJS templates first, fallback to YAML.
+ */
+export async function renderAsync(
+  store: Store,
+  hash: Hash,
+  options?: RenderOptions,
+): Promise<string> {
+  const { resolution, decay, epsilon } = validateAndExtractOptions(options);
+
+  // Check if root node exists
+  if (store.get(hash) === null) {
+    throw new CasNodeNotFoundError(hash);
+  }
+
+  const varStore = options?.varStore;
+
+  // If varStore provided, try template rendering first
+  if (varStore !== undefined) {
+    try {
+      const node = store.get(hash);
+      if (node !== null) {
+        // Check if a template exists for this type
+        const templateExists = await hasTemplate(store, varStore, node.type);
+        if (templateExists) {
+          return await renderWithTemplate(store, varStore, hash, {
+            resolution,
+            decay,
+            epsilon,
+          });
+        }
+      }
+    } catch {
+      // Fall through to YAML rendering
+    }
+  }
+
+  // Fallback to YAML rendering
+  const visited = new Set<Hash>();
+  return renderNode(store, hash, resolution, decay, epsilon, visited);
+}
+
+/**
+ * Render a value directly (in-memory) without requiring it to be stored.
+ * Accepts a raw { type, value } pair. Store is optional and read-only —
+ * used only for schema lookup and expanding nested cas_ref references.
+ * No data is written to the store.
+ */
+export function renderDirect(
+  typeHash: Hash,
+  value: unknown,
+  store: Store | null,
+  options: Omit<RenderOptions, "varStore"> | null,
+): string {
+  const { resolution, decay, epsilon } = validateAndExtractOptions(options);
+
+  // Try to get schema from store to identify cas_ref fields
+  let refSet = new Set<Hash>();
+  if (store !== null) {
+    const schema = getSchema(store, typeHash);
+    if (schema !== null) {
+      refSet = new Set(collectRefs(schema, value));
+    }
+  }
+
+  const childResolution = resolution * decay;
+  const visited = new Set<Hash>();
+
+  return renderValue(
+    store ?? null,
+    value,
+    refSet,
+    childResolution,
+    decay,
+    epsilon,
+    visited,
+  );
+}
+
+/**
+ * Check if a template exists for a given type
+ */
+async function hasTemplate(
+  store: Store,
+  varStore: VariableStore,
+  typeHash: Hash,
+): Promise<boolean> {
+  const varName = `@ucas/template/text/${typeHash}`;
+  try {
+    const stringSchema = await putSchema(store, { type: "string" });
+    const variable = varStore.get(varName, stringSchema);
+    return variable !== null;
+  } catch {
+    return false;
+  }
+}
+
+function renderNode(
+  store: Store | null,
+  hash: Hash,
+  currentResolution: number,
+  decay: number,
+  epsilon: number,
+  visited: Set<Hash>,
+): string {
+  // Check if resolution is below threshold (with floating point tolerance)
+  if (currentResolution < epsilon + FLOAT_TOLERANCE) {
+    return `cas:${hash}`;
+  }
+
+  // Fetch the node
+  const node = store !== null ? store.get(hash) : null;
+  if (node === null) {
+    // Missing node - render as cas: reference
+    return `cas:${hash}`;
+  }
+
+  // Cycle detection
+  if (visited.has(hash)) {
+    return `cas:${hash}`;
+  }
+  visited.add(hash);
+
+  // Get references from this node's schema
+  const nodeRefs = store !== null ? refs(store, node) : [];
+  const refSet = new Set(nodeRefs);
+
+  // Calculate child resolution for next level
+  const childResolution = currentResolution * decay;
+
+  // Render the payload with recursive expansion of cas_ref fields
+  const rendered = renderValue(
+    store,
+    node.payload,
+    refSet,
+    childResolution,
+    decay,
+    epsilon,
+    visited,
+  );
+
+  visited.delete(hash);
+
+  return rendered;
+}
+
+function renderValue(
+  store: Store | null,
+  value: unknown,
+  refHashes: Set<Hash>,
+  childResolution: number,
+  decay: number,
+  epsilon: number,
+  visited: Set<Hash>,
+): string {
+  // Handle null
+  if (value === null) {
+    return "null\n";
+  }
+
+  // Handle primitives
+  if (typeof value === "string") {
+    // Check if this string is a cas_ref
+    if (refHashes.has(value as Hash)) {
+      // Recursively render the referenced node
+      return renderNode(
+        store,
+        value as Hash,
+        childResolution,
+        decay,
+        epsilon,
+        visited,
+      );
+    }
+    // Otherwise, render as YAML string
+    return toYamlString(value);
+  }
+
+  if (typeof value === "number" || typeof value === "boolean") {
+    return `${value}\n`;
+  }
+
+  // Handle arrays
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return "[]\n";
+    }
+
+    const items = value.map((item) => {
+      const itemYaml = renderValue(
+        store,
+        item,
+        refHashes,
+        childResolution,
+        decay,
+        epsilon,
+        visited,
+      );
+      return indent(itemYaml.trim(), 2);
+    });
+
+    return `- ${items.join("\n- ")}\n`;
+  }
+
+  // Handle objects
+  if (typeof value === "object") {
+    const obj = value as Record<string, unknown>;
+    const keys = Object.keys(obj);
+
+    if (keys.length === 0) {
+      return "{}\n";
+    }
+
+    const pairs = keys.map((key) => {
+      const val = obj[key];
+      const valYaml = renderValue(
+        store,
+        val,
+        refHashes,
+        childResolution,
+        decay,
+        epsilon,
+        visited,
+      );
+
+      const trimmedVal = valYaml.trim();
+
+      // If value is multiline, indent it
+      if (trimmedVal.includes("\n")) {
+        return `${key}:\n${indent(trimmedVal, 2)}`;
+      }
+
+      return `${key}: ${trimmedVal}`;
+    });
+
+    return `${pairs.join("\n")}\n`;
+  }
+
+  return "null\n";
+}
+
+function toYamlString(str: string): string {
+  // Handle special characters
+  if (
+    str.includes("\n") ||
+    str.includes(":") ||
+    str.includes("#") ||
+    str.includes("[") ||
+    str.includes("]") ||
+    str.includes("{") ||
+    str.includes("}") ||
+    str.includes("'") ||
+    str.includes('"') ||
+    str.startsWith(" ") ||
+    str.endsWith(" ")
+  ) {
+    // Use double-quoted string with escaping
+    const escaped = str
+      .replace(/\\/g, "\\\\")
+      .replace(/"/g, '\\"')
+      .replace(/\n/g, "\\n");
+    return `"${escaped}"\n`;
+  }
+
+  return `${str}\n`;
+}
+
+function indent(text: string, spaces: number): string {
+  const prefix = " ".repeat(spaces);
+  return text
+    .split("\n")
+    .map((line) => (line ? prefix + line : line))
+    .join("\n");
+}

packages/json-cas/src/schema.test.ts

@@ -29,7 +29,8 @@ describe("putSchema", () => {
 
   test("schema node type equals the meta-schema hash", async () => {
     const store = createMemoryStore();
-    const metaHash = await bootstrap(store);
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
     const schemaHash = await putSchema(store, { type: "string" });
     const node = store.get(schemaHash) as CasNode;
 
@@ -355,7 +356,8 @@ describe("walk", () => {
 describe("bootstrap meta-schema self-reference", () => {
   test("metaNode.type === metaHash (self-referencing)", async () => {
     const store = createMemoryStore();
-    const metaHash = await bootstrap(store);
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
     const metaNode = store.get(metaHash) as CasNode;
 
     expect(metaNode.type).toBe(metaHash);
@@ -363,7 +365,8 @@ describe("bootstrap meta-schema self-reference", () => {
 
   test("schema nodes have type === metaHash", async () => {
     const store = createMemoryStore();
-    const metaHash = await bootstrap(store);
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
     const schemaHash = await putSchema(store, { type: "string" });
     const schemaNode = store.get(schemaHash) as CasNode;
 
@@ -372,7 +375,8 @@ describe("bootstrap meta-schema self-reference", () => {
 
   test("data nodes have type === schemaHash (not metaHash)", async () => {
     const store = createMemoryStore();
-    const metaHash = await bootstrap(store);
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
     const schemaHash = await putSchema(store, {
       type: "object",
       properties: { val: { type: "number" } },
@@ -384,9 +388,111 @@ describe("bootstrap meta-schema self-reference", () => {
     expect(dataNode.type).not.toBe(metaHash);
   });
 
+  // ── P1 leaf constraints ──────────────────────────────────────────────────
+
+  test("accepts schema with numeric constraints (minimum/maximum)", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "number",
+      minimum: 0,
+      maximum: 100,
+      exclusiveMinimum: -1,
+      exclusiveMaximum: 101,
+    });
+    expect(hash).toHaveLength(13);
+
+    // validate a conforming payload
+    const nodeHash = await store.put(hash, 42);
+    const node = store.get(nodeHash) as CasNode;
+    expect(validate(store, node)).toBe(true);
+
+    // validate a non-conforming payload
+    const badHash = await store.put(hash, 200);
+    const badNode = store.get(badHash) as CasNode;
+    expect(validate(store, badNode)).toBe(false);
+  });
+
+  test("accepts schema with string constraints (minLength/maxLength/pattern)", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "string",
+      minLength: 1,
+      maxLength: 10,
+      pattern: "^[a-z]+$",
+    });
+    expect(hash).toHaveLength(13);
+
+    const goodHash = await store.put(hash, "hello");
+    expect(validate(store, store.get(goodHash) as CasNode)).toBe(true);
+
+    const badHash = await store.put(hash, "HELLO");
+    expect(validate(store, store.get(badHash) as CasNode)).toBe(false);
+  });
+
+  test("accepts schema with array constraints (minItems/maxItems/uniqueItems)", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "array",
+      items: { type: "number" },
+      minItems: 1,
+      maxItems: 3,
+      uniqueItems: true,
+    });
+    expect(hash).toHaveLength(13);
+
+    const goodHash = await store.put(hash, [1, 2, 3]);
+    expect(validate(store, store.get(goodHash) as CasNode)).toBe(true);
+
+    const tooMany = await store.put(hash, [1, 2, 3, 4]);
+    expect(validate(store, store.get(tooMany) as CasNode)).toBe(false);
+
+    const dupes = await store.put(hash, [1, 1]);
+    expect(validate(store, store.get(dupes) as CasNode)).toBe(false);
+  });
+
+  test("rejects schema with wrong constraint types", async () => {
+    const store = createMemoryStore();
+    await expect(
+      putSchema(store, { type: "number", minimum: "zero" } as never),
+    ).rejects.toThrow();
+    await expect(
+      putSchema(store, { type: "string", maxLength: true } as never),
+    ).rejects.toThrow();
+    await expect(
+      putSchema(store, { type: "array", uniqueItems: 1 } as never),
+    ).rejects.toThrow();
+  });
+
+  test("accepts schema with nested property constraints", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "object",
+      properties: {
+        name: { type: "string", minLength: 1, maxLength: 50 },
+        age: { type: "number", minimum: 0, maximum: 150 },
+        scores: {
+          type: "array",
+          items: { type: "number" },
+          minItems: 1,
+          uniqueItems: true,
+        },
+      },
+      required: ["name"],
+    });
+    expect(hash).toHaveLength(13);
+
+    const good = await store.put(hash, {
+      name: "Alice",
+      age: 30,
+      scores: [95, 87],
+    });
+    expect(validate(store, store.get(good) as CasNode)).toBe(true);
+  });
+
   test("bootstrap is idempotent across putSchema calls", async () => {
     const store = createMemoryStore();
-    const metaHash = await bootstrap(store);
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
 
     await putSchema(store, { type: "string" });
     await putSchema(store, { type: "number" });
@@ -395,4 +501,253 @@ describe("bootstrap meta-schema self-reference", () => {
     const metaNode = store.get(metaHash) as CasNode;
     expect(metaNode.type).toBe(metaHash);
   });
+
+  // ── P2 combinators, conditionals, and leaf constraints ──────────────────
+
+  test("accepts schema with allOf", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      allOf: [
+        { type: "object", properties: { name: { type: "string" } } },
+        { required: ["name"] },
+      ],
+    });
+    expect(hash).toHaveLength(13);
+
+    const good = await store.put(hash, { name: "Alice" });
+    expect(validate(store, store.get(good) as CasNode)).toBe(true);
+
+    const bad = await store.put(hash, {});
+    expect(validate(store, store.get(bad) as CasNode)).toBe(false);
+  });
+
+  test("accepts schema with if/then/else", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "object",
+      properties: {
+        kind: { type: "string" },
+        value: {},
+      },
+      if: { properties: { kind: { const: "number" } } },
+      // biome-ignore lint/suspicious/noThenProperty: JSON Schema keyword, not a thenable
+      then: { properties: { value: { type: "number" } } },
+      else: { properties: { value: { type: "string" } } },
+    });
+    expect(hash).toHaveLength(13);
+  });
+
+  test("accepts schema with patternProperties", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "object",
+      patternProperties: {
+        "^x-": { type: "string" },
+      },
+    });
+    expect(hash).toHaveLength(13);
+
+    const good = await store.put(hash, { "x-custom": "hello" });
+    expect(validate(store, store.get(good) as CasNode)).toBe(true);
+  });
+
+  test("accepts schema with prefixItems (tuple)", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "array",
+      prefixItems: [{ type: "string" }, { type: "number" }],
+    });
+    expect(hash).toHaveLength(13);
+  });
+
+  test("accepts schema with multipleOf", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "number",
+      multipleOf: 5,
+    });
+    expect(hash).toHaveLength(13);
+
+    const good = await store.put(hash, 15);
+    expect(validate(store, store.get(good) as CasNode)).toBe(true);
+
+    const bad = await store.put(hash, 7);
+    expect(validate(store, store.get(bad) as CasNode)).toBe(false);
+  });
+
+  test("accepts schema with minProperties/maxProperties", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "object",
+      minProperties: 1,
+      maxProperties: 3,
+    });
+    expect(hash).toHaveLength(13);
+
+    const good = await store.put(hash, { a: 1, b: 2 });
+    expect(validate(store, store.get(good) as CasNode)).toBe(true);
+
+    const empty = await store.put(hash, {});
+    expect(validate(store, store.get(empty) as CasNode)).toBe(false);
+  });
+
+  test("accepts schema with default value", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "string",
+      default: "hello",
+    });
+    expect(hash).toHaveLength(13);
+  });
+
+  test("rejects invalid P2 keyword types", async () => {
+    const store = createMemoryStore();
+    await expect(
+      putSchema(store, { allOf: "not-array" } as never),
+    ).rejects.toThrow();
+    await expect(
+      putSchema(store, { multipleOf: "five" } as never),
+    ).rejects.toThrow();
+    await expect(
+      putSchema(store, { patternProperties: [1, 2] } as never),
+    ).rejects.toThrow();
+  });
+
+  test("collectRefs traverses allOf sub-schemas", async () => {
+    const store = createMemoryStore();
+    const innerSchema = await putSchema(store, { type: "string" });
+    const schema = await putSchema(store, {
+      allOf: [
+        {
+          type: "object",
+          properties: { ref: { type: "string", format: "cas_ref" } },
+        },
+      ],
+    });
+
+    const targetHash = await store.put(innerSchema, "target");
+    const nodeHash = await store.put(schema, { ref: targetHash });
+    const node = store.get(nodeHash) as CasNode;
+    const refList = refs(store, node);
+    expect(refList).toContain(targetHash);
+  });
+
+  test("collectRefs traverses patternProperties", async () => {
+    const store = createMemoryStore();
+    const innerSchema = await putSchema(store, { type: "string" });
+    const schema = await putSchema(store, {
+      type: "object",
+      patternProperties: {
+        "^ref_": { type: "string", format: "cas_ref" },
+      },
+    });
+
+    const targetHash = await store.put(innerSchema, "hello");
+    const nodeHash = await store.put(schema, { ref_a: targetHash });
+    const node = store.get(nodeHash) as CasNode;
+    const refList = refs(store, node);
+    expect(refList).toContain(targetHash);
+  });
+
+  test("collectRefs traverses prefixItems", async () => {
+    const store = createMemoryStore();
+    const innerSchema = await putSchema(store, { type: "string" });
+    const schema = await putSchema(store, {
+      type: "array",
+      prefixItems: [{ type: "string", format: "cas_ref" }, { type: "number" }],
+    });
+
+    const targetHash = await store.put(innerSchema, "hello");
+    const nodeHash = await store.put(schema, [targetHash, 42]);
+    const node = store.get(nodeHash) as CasNode;
+    const refList = refs(store, node);
+    expect(refList).toContain(targetHash);
+  });
+
+  // ── P3 combinators, propertyNames, and metadata ──────────────────────────
+
+  test("accepts schema with not", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      not: { type: "string" },
+    });
+    expect(hash).toHaveLength(13);
+
+    const good = await store.put(hash, 42);
+    expect(validate(store, store.get(good) as CasNode)).toBe(true);
+
+    const bad = await store.put(hash, "hello");
+    expect(validate(store, store.get(bad) as CasNode)).toBe(false);
+  });
+
+  test("accepts schema with contains", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "array",
+      contains: { type: "number", minimum: 10 },
+    });
+    expect(hash).toHaveLength(13);
+
+    const good = await store.put(hash, [1, 2, 15]);
+    expect(validate(store, store.get(good) as CasNode)).toBe(true);
+
+    const bad = await store.put(hash, [1, 2, 3]);
+    expect(validate(store, store.get(bad) as CasNode)).toBe(false);
+  });
+
+  test("accepts schema with propertyNames", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "object",
+      propertyNames: { pattern: "^[a-z]+$" },
+    });
+    expect(hash).toHaveLength(13);
+
+    const good = await store.put(hash, { foo: 1, bar: 2 });
+    expect(validate(store, store.get(good) as CasNode)).toBe(true);
+
+    const bad = await store.put(hash, { Foo: 1 });
+    expect(validate(store, store.get(bad) as CasNode)).toBe(false);
+  });
+
+  test("accepts schema with metadata keywords", async () => {
+    const store = createMemoryStore();
+    const hash = await putSchema(store, {
+      type: "string",
+      examples: ["hello", "world"],
+      readOnly: true,
+      deprecated: false,
+      $comment: "This is a test schema",
+    });
+    expect(hash).toHaveLength(13);
+  });
+
+  test("rejects invalid P3 keyword types", async () => {
+    const store = createMemoryStore();
+    await expect(
+      putSchema(store, { not: "not-object" } as never),
+    ).rejects.toThrow();
+    await expect(
+      putSchema(store, { examples: "not-array" } as never),
+    ).rejects.toThrow();
+    await expect(
+      putSchema(store, { readOnly: "yes" } as never),
+    ).rejects.toThrow();
+    await expect(putSchema(store, { $comment: 42 } as never)).rejects.toThrow();
+  });
+
+  test("collectRefs traverses contains", async () => {
+    const store = createMemoryStore();
+    const innerSchema = await putSchema(store, { type: "string" });
+    const schema = await putSchema(store, {
+      type: "array",
+      contains: { type: "string", format: "cas_ref" },
+    });
+
+    const targetHash = await store.put(innerSchema, "hello");
+    const nodeHash = await store.put(schema, [targetHash, "not-a-ref"]);
+    const node = store.get(nodeHash) as CasNode;
+    const refList = refs(store, node);
+    expect(refList).toContain(targetHash);
+  });
 });

packages/json-cas/src/schema.ts

@@ -4,7 +4,10 @@ import * as AjvModule from "ajv";
 // but tsc with verbatimModuleSyntax sees the namespace wrapper.
 // biome-ignore lint/suspicious/noExplicitAny: CJS interop
 const Ajv = ((AjvModule as any).default ?? AjvModule) as {
-	new (): { addFormat(name: string, re: RegExp): void; validate(schema: unknown, data: unknown): boolean };
+  new (): {
+    addFormat(name: string, re: RegExp): void;
+    validate(schema: unknown, data: unknown): boolean;
+  };
 };
 
 import { bootstrap } from "./bootstrap.js";
@@ -12,9 +15,235 @@ import type { CasNode, Hash, Store } from "./types.js";
 
 export type JSONSchema = Record<string, unknown>;
 
+export class SchemaValidationError extends Error {
+  override readonly name = "SchemaValidationError";
+}
+
 const ajv = new Ajv();
 ajv.addFormat("cas_ref", /^[0-9A-HJKMNP-TV-Z]{13}$/);
 
+const ALLOWED_SCHEMA_KEYS = new Set([
+  "type",
+  "properties",
+  "required",
+  "additionalProperties",
+  "anyOf",
+  "oneOf",
+  "items",
+  "format",
+  "title",
+  "enum",
+  "const",
+  "description",
+  // P1 leaf constraints (no collectRefs impact)
+  "minimum",
+  "maximum",
+  "exclusiveMinimum",
+  "exclusiveMaximum",
+  "minLength",
+  "maxLength",
+  "pattern",
+  "minItems",
+  "maxItems",
+  "uniqueItems",
+  // P2 combinators + conditionals (need collectRefs)
+  "allOf",
+  "if",
+  "then",
+  "else",
+  "patternProperties",
+  "prefixItems",
+  // P2 leaf constraints
+  "multipleOf",
+  "minProperties",
+  "maxProperties",
+  "default",
+  // P3 combinators (need collectRefs)
+  "not",
+  "contains",
+  "propertyNames",
+  // P3 metadata (no collectRefs impact)
+  "examples",
+  "readOnly",
+  "writeOnly",
+  "deprecated",
+  "$comment",
+]);
+
+const JSON_SCHEMA_TYPES = new Set([
+  "string",
+  "number",
+  "integer",
+  "boolean",
+  "object",
+  "array",
+  "null",
+]);
+
+function isValidTypeValue(type: unknown): boolean {
+  if (typeof type === "string") {
+    return JSON_SCHEMA_TYPES.has(type);
+  }
+  if (Array.isArray(type)) {
+    if (type.length === 0) return false;
+    return type.every(
+      (entry) => typeof entry === "string" && JSON_SCHEMA_TYPES.has(entry),
+    );
+  }
+  return false;
+}
+
+function isValidSchema(value: unknown): boolean {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+
+  const schema = value as JSONSchema;
+  for (const key of Object.keys(schema)) {
+    if (!ALLOWED_SCHEMA_KEYS.has(key)) return false;
+  }
+
+  if ("type" in schema && !isValidTypeValue(schema.type)) return false;
+
+  if ("properties" in schema) {
+    const properties = schema.properties;
+    if (
+      properties === null ||
+      typeof properties !== "object" ||
+      Array.isArray(properties)
+    ) {
+      return false;
+    }
+    for (const nested of Object.values(properties as Record<string, unknown>)) {
+      if (!isValidSchema(nested)) return false;
+    }
+  }
+
+  if ("required" in schema) {
+    if (!Array.isArray(schema.required)) return false;
+    for (const entry of schema.required) {
+      if (typeof entry !== "string") return false;
+    }
+  }
+
+  if ("additionalProperties" in schema) {
+    const additionalProperties = schema.additionalProperties;
+    if (typeof additionalProperties === "boolean") {
+      // allowed
+    } else if (!isValidSchema(additionalProperties)) {
+      return false;
+    }
+  }
+
+  if ("anyOf" in schema) {
+    if (!Array.isArray(schema.anyOf) || schema.anyOf.length === 0) return false;
+    for (const entry of schema.anyOf) {
+      if (!isValidSchema(entry)) return false;
+    }
+  }
+
+  if ("oneOf" in schema) {
+    if (!Array.isArray(schema.oneOf) || schema.oneOf.length === 0) return false;
+    for (const entry of schema.oneOf) {
+      if (!isValidSchema(entry)) return false;
+    }
+  }
+
+  if ("items" in schema && !isValidSchema(schema.items)) return false;
+  if ("format" in schema && typeof schema.format !== "string") return false;
+  if ("title" in schema && typeof schema.title !== "string") return false;
+  if ("description" in schema && typeof schema.description !== "string") {
+    return false;
+  }
+  if ("enum" in schema) {
+    if (!Array.isArray(schema.enum) || schema.enum.length === 0) return false;
+  }
+
+  // P1 leaf constraints — type checks only
+  if ("minimum" in schema && typeof schema.minimum !== "number") return false;
+  if ("maximum" in schema && typeof schema.maximum !== "number") return false;
+  if (
+    "exclusiveMinimum" in schema &&
+    typeof schema.exclusiveMinimum !== "number"
+  )
+    return false;
+  if (
+    "exclusiveMaximum" in schema &&
+    typeof schema.exclusiveMaximum !== "number"
+  )
+    return false;
+  if ("minLength" in schema && typeof schema.minLength !== "number")
+    return false;
+  if ("maxLength" in schema && typeof schema.maxLength !== "number")
+    return false;
+  if ("pattern" in schema && typeof schema.pattern !== "string") return false;
+  if ("minItems" in schema && typeof schema.minItems !== "number") return false;
+  if ("maxItems" in schema && typeof schema.maxItems !== "number") return false;
+  if ("uniqueItems" in schema && typeof schema.uniqueItems !== "boolean")
+    return false;
+
+  // P2 combinators + conditionals — recursive sub-schema checks
+  if ("allOf" in schema) {
+    if (!Array.isArray(schema.allOf) || schema.allOf.length === 0) return false;
+    for (const entry of schema.allOf) {
+      if (!isValidSchema(entry)) return false;
+    }
+  }
+
+  if ("if" in schema && !isValidSchema(schema.if)) return false;
+  if ("then" in schema && !isValidSchema(schema.then)) return false;
+  if ("else" in schema && !isValidSchema(schema.else)) return false;
+
+  if ("patternProperties" in schema) {
+    const pp = schema.patternProperties;
+    if (pp === null || typeof pp !== "object" || Array.isArray(pp))
+      return false;
+    for (const nested of Object.values(pp as Record<string, unknown>)) {
+      if (!isValidSchema(nested)) return false;
+    }
+  }
+
+  if ("prefixItems" in schema) {
+    if (!Array.isArray(schema.prefixItems) || schema.prefixItems.length === 0)
+      return false;
+    for (const entry of schema.prefixItems) {
+      if (!isValidSchema(entry)) return false;
+    }
+  }
+
+  // P2 leaf constraints — type checks only
+  if ("multipleOf" in schema && typeof schema.multipleOf !== "number")
+    return false;
+  if ("minProperties" in schema && typeof schema.minProperties !== "number")
+    return false;
+  if ("maxProperties" in schema && typeof schema.maxProperties !== "number")
+    return false;
+  // "default" accepts any value — no type check needed
+
+  // P3 combinators — recursive sub-schema checks
+  if ("not" in schema && !isValidSchema(schema.not)) return false;
+  if ("contains" in schema && !isValidSchema(schema.contains)) return false;
+  if ("propertyNames" in schema && !isValidSchema(schema.propertyNames))
+    return false;
+
+  // P3 metadata — type checks only
+  if ("examples" in schema && !Array.isArray(schema.examples)) return false;
+  if ("readOnly" in schema && typeof schema.readOnly !== "boolean")
+    return false;
+  if ("writeOnly" in schema && typeof schema.writeOnly !== "boolean")
+    return false;
+  if ("deprecated" in schema && typeof schema.deprecated !== "boolean")
+    return false;
+  if ("$comment" in schema && typeof schema.$comment !== "string") return false;
+
+  return true;
+}
+
+function isMetaSchemaNode(store: Store, node: CasNode): boolean {
+  const schema = getSchema(store, node.type);
+  return schema !== null && schema === node.payload;
+}
+
 /**
  * Store a JSON Schema as a CAS node typed by the meta-schema hash.
  * The returned hash becomes the typeHash for nodes that conform to this schema.
@@ -23,7 +252,16 @@ export async function putSchema(
   store: Store,
   jsonSchema: JSONSchema,
 ): Promise<Hash> {
-  const metaHash = await bootstrap(store);
+  const builtinSchemas = await bootstrap(store);
+  const metaHash = builtinSchemas["@schema"];
+  if (!metaHash) {
+    throw new Error("Meta-schema not found in bootstrap result");
+  }
+  if (!isValidSchema(jsonSchema)) {
+    throw new SchemaValidationError(
+      "Invalid schema: input does not conform to the json-cas JSON Schema meta-schema",
+    );
+  }
   return store.put(metaHash, jsonSchema);
 }
 
@@ -44,6 +282,9 @@ export function getSchema(store: Store, typeHash: Hash): JSONSchema | null {
 export function validate(store: Store, node: CasNode): boolean {
   const schema = getSchema(store, node.type);
   if (schema === null) return false;
+  if (isMetaSchemaNode(store, node)) {
+    return isValidSchema(node.payload);
+  }
   return ajv.validate(
     schema as Parameters<typeof ajv.validate>[0],
     node.payload,
@@ -52,10 +293,11 @@ export function validate(store: Store, node: CasNode): boolean {
 
 /**
  * Recursively collect values of all properties whose schema has format: 'cas_ref'.
- * Handles: direct format, anyOf (nullable refs), items (array refs),
- * properties (nested objects), and additionalProperties (record refs).
+ * Handles: direct format, anyOf/allOf (combinators), oneOf, if/then/else (conditionals),
+ * not, contains, items + prefixItems (arrays), properties (nested objects),
+ * additionalProperties (record refs), and patternProperties (regex-keyed refs).
  */
-function collectRefs(schema: JSONSchema, value: unknown): Hash[] {
+export function collectRefs(schema: JSONSchema, value: unknown): Hash[] {
   const result: Hash[] = [];
 
   if (schema.format === "cas_ref") {
@@ -72,11 +314,55 @@ function collectRefs(schema: JSONSchema, value: unknown): Hash[] {
     return result;
   }
 
-  if (schema.type === "array" && schema.items && Array.isArray(value)) {
-    const itemSchema = schema.items as JSONSchema;
-    for (const item of value as unknown[]) {
-      result.push(...collectRefs(itemSchema, item));
+  // P2: allOf — each sub-schema applies to the same value
+  if (Array.isArray(schema.allOf)) {
+    for (const sub of schema.allOf as JSONSchema[]) {
+      result.push(...collectRefs(sub, value));
     }
+  }
+
+  // P2: if/then/else — conditional sub-schemas apply to the same value
+  if (schema.if && typeof schema.if === "object") {
+    result.push(...collectRefs(schema.if as JSONSchema, value));
+  }
+  if (schema.then && typeof schema.then === "object") {
+    result.push(...collectRefs(schema.then as JSONSchema, value));
+  }
+  if (schema.else && typeof schema.else === "object") {
+    result.push(...collectRefs(schema.else as JSONSchema, value));
+  }
+
+  if (schema.type === "array" && Array.isArray(value)) {
+    // P2: prefixItems — tuple validation, each item has its own schema
+    if (Array.isArray(schema.prefixItems)) {
+      const tupleSchemas = schema.prefixItems as JSONSchema[];
+      const arr = value as unknown[];
+      for (let i = 0; i < tupleSchemas.length && i < arr.length; i++) {
+        const ts = tupleSchemas[i];
+        if (ts) result.push(...collectRefs(ts, arr[i]));
+      }
+    }
+
+    if (schema.items) {
+      const itemSchema = schema.items as JSONSchema;
+      // When prefixItems exists, items applies only to remaining elements
+      const startIdx = Array.isArray(schema.prefixItems)
+        ? (schema.prefixItems as unknown[]).length
+        : 0;
+      const arr = value as unknown[];
+      for (let i = startIdx; i < arr.length; i++) {
+        result.push(...collectRefs(itemSchema, arr[i]));
+      }
+    }
+
+    // P3: contains — sub-schema for array items
+    if (schema.contains && typeof schema.contains === "object") {
+      const containsSchema = schema.contains as JSONSchema;
+      for (const item of value as unknown[]) {
+        result.push(...collectRefs(containsSchema, item));
+      }
+    }
+
     return result;
   }
 
@@ -99,6 +385,28 @@ function collectRefs(schema: JSONSchema, value: unknown): Hash[] {
         result.push(...collectRefs(addlSchema, val));
       }
     }
+
+    // P2: patternProperties — regex-keyed property schemas
+    if (
+      schema.patternProperties &&
+      typeof schema.patternProperties === "object"
+    ) {
+      const pp = schema.patternProperties as Record<string, JSONSchema>;
+      const obj = value as Record<string, unknown>;
+      for (const [pat, subSchema] of Object.entries(pp)) {
+        const re = new RegExp(pat);
+        for (const [key, val] of Object.entries(obj)) {
+          if (re.test(key)) {
+            result.push(...collectRefs(subSchema, val));
+          }
+        }
+      }
+    }
+  }
+
+  // P3: not — sub-schema applies to the same value
+  if (schema.not && typeof schema.not === "object") {
+    result.push(...collectRefs(schema.not as JSONSchema, value));
   }
 
   return result;

packages/json-cas/src/store.test.ts

@@ -0,0 +1,89 @@
+import { describe, expect, test } from "bun:test";
+import { BOOTSTRAP_STORE } from "./bootstrap-capable.js";
+import { createMemoryStore } from "./store.js";
+
+describe("createMemoryStore – meta and schema indexes", () => {
+  test("B1. listMeta and listSchemas are empty on a fresh store", () => {
+    const store = createMemoryStore();
+    expect(store.listMeta()).toEqual([]);
+    expect(store.listSchemas()).toEqual([]);
+  });
+
+  test("B2. self-referencing put adds hash to metaSet and listSchemas", async () => {
+    const store = createMemoryStore();
+    const hash = await store[BOOTSTRAP_STORE]({ type: "object" });
+
+    expect(store.listMeta()).toContain(hash);
+    expect(store.listSchemas()).toContain(hash);
+  });
+
+  test("B3. regular put does not add hash to metaSet", async () => {
+    const store = createMemoryStore();
+    const metaHash = await store[BOOTSTRAP_STORE]({ type: "object" });
+    const schemaHash = await store.put(metaHash, { type: "string" });
+
+    expect(store.listMeta()).not.toContain(schemaHash);
+    expect(store.listMeta()).toContain(metaHash);
+  });
+
+  test("B4. schema typed by meta-schema appears in listSchemas", async () => {
+    const store = createMemoryStore();
+    const m = await store[BOOTSTRAP_STORE]({ type: "object" });
+    const s = await store.put(m, { type: "string" });
+
+    const schemas = store.listSchemas();
+    expect(schemas).toContain(m);
+    expect(schemas).toContain(s);
+
+    const meta = store.listMeta();
+    expect(meta).toContain(m);
+    expect(meta).not.toContain(s);
+  });
+
+  test("B5. multiple meta-schemas (versioning)", async () => {
+    const store = createMemoryStore();
+    const m1 = await store[BOOTSTRAP_STORE]({ type: "object", title: "v1" });
+    const m2 = await store[BOOTSTRAP_STORE]({ type: "object", title: "v2" });
+    const s1 = await store.put(m1, { type: "string" });
+    const s2 = await store.put(m2, { type: "number" });
+
+    const meta = store.listMeta();
+    expect(meta).toContain(m1);
+    expect(meta).toContain(m2);
+    expect(meta).toHaveLength(2);
+
+    const schemas = store.listSchemas();
+    expect(schemas).toContain(m1);
+    expect(schemas).toContain(m2);
+    expect(schemas).toContain(s1);
+    expect(schemas).toContain(s2);
+  });
+
+  test("B6. idempotent self-referencing put does not duplicate", async () => {
+    const store = createMemoryStore();
+    const payload = { type: "object", title: "dup" };
+    const h1 = await store[BOOTSTRAP_STORE](payload);
+    const h2 = await store[BOOTSTRAP_STORE](payload);
+    expect(h1).toBe(h2);
+
+    const meta = store.listMeta();
+    const occurrences = meta.filter((h) => h === h1).length;
+    expect(occurrences).toBe(1);
+  });
+
+  test("B7. delete removes hash from metaSet and listSchemas", async () => {
+    const store = createMemoryStore();
+    const m = await store[BOOTSTRAP_STORE]({ type: "object" });
+    const s = await store.put(m, { type: "string" });
+
+    expect(store.listMeta()).toContain(m);
+    expect(store.listSchemas()).toContain(s);
+
+    store.delete(m);
+
+    expect(store.listMeta()).not.toContain(m);
+    // schemas typed by deleted meta no longer surface
+    expect(store.listSchemas()).not.toContain(s);
+    expect(store.listSchemas()).not.toContain(m);
+  });
+});

packages/json-cas/src/store.ts

@@ -1,19 +1,41 @@
+import {
+  BOOTSTRAP_STORE,
+  type BootstrapCapableStore,
+} from "./bootstrap-capable.js";
 import { computeHash, computeSelfHash } from "./hash.js";
-import type { CasNode, Hash, Store } from "./types.js";
+import type { CasNode, Hash } from "./types.js";
 
-export function createMemoryStore(): Store {
+export function createMemoryStore(): BootstrapCapableStore {
   const data = new Map<Hash, CasNode>();
+  const byType = new Map<Hash, Set<Hash>>();
+  const metaSet = new Set<Hash>();
 
-  return {
-    async put(typeHash: Hash | null, payload: unknown): Promise<Hash> {
-      const hash =
-        typeHash === null
-          ? await computeSelfHash(payload)
-          : await computeHash(typeHash, payload);
+  function indexHash(type: Hash, hash: Hash): void {
+    let set = byType.get(type);
+    if (!set) {
+      set = new Set();
+      byType.set(type, set);
+    }
+    set.add(hash);
+  }
+
+  async function putSelfReferencing(payload: unknown): Promise<Hash> {
+    const hash = await computeSelfHash(payload);
+    if (!data.has(hash)) {
+      data.set(hash, { type: hash, payload, timestamp: Date.now() });
+      indexHash(hash, hash);
+    }
+    metaSet.add(hash);
+    return hash;
+  }
+
+  const store: BootstrapCapableStore = {
+    async put(typeHash: Hash, payload: unknown): Promise<Hash> {
+      const hash = await computeHash(typeHash, payload);
 
       if (!data.has(hash)) {
-        const type = typeHash === null ? hash : typeHash;
-        data.set(hash, { type, payload, timestamp: Date.now() });
+        data.set(hash, { type: typeHash, payload, timestamp: Date.now() });
+        indexHash(typeHash, hash);
       }
 
       return hash;
@@ -27,8 +49,49 @@ export function createMemoryStore(): Store {
       return data.has(hash);
     },
 
-    list(): Hash[] {
-      return [...data.keys()];
+    listByType(typeHash: Hash): Hash[] {
+      const set = byType.get(typeHash);
+      return set ? [...set] : [];
     },
+
+    listAll(): Hash[] {
+      return Array.from(data.keys());
+    },
+
+    listMeta(): Hash[] {
+      return Array.from(metaSet);
+    },
+
+    listSchemas(): Hash[] {
+      const result = new Set<Hash>();
+      for (const meta of metaSet) {
+        result.add(meta);
+        const set = byType.get(meta);
+        if (set) {
+          for (const h of set) result.add(h);
+        }
+      }
+      return Array.from(result);
+    },
+
+    delete(hash: Hash): void {
+      const node = data.get(hash);
+      if (node) {
+        data.delete(hash);
+        // Remove from type index
+        const set = byType.get(node.type);
+        if (set) {
+          set.delete(hash);
+          if (set.size === 0) {
+            byType.delete(node.type);
+          }
+        }
+        metaSet.delete(hash);
+      }
+    },
+
+    [BOOTSTRAP_STORE]: putSelfReferencing,
   };
+
+  return store;
 }

packages/json-cas/src/types.ts

@@ -17,11 +17,15 @@ export type CasNode<T = unknown> = {
 
 /**
  * Content-addressable store interface.
- * put(null, payload) creates a self-referencing (bootstrap) node.
+ * Self-referencing nodes are created only via bootstrap().
  */
 export type Store = {
-  put(typeHash: Hash | null, payload: unknown): Promise<Hash>;
+  put(typeHash: Hash, payload: unknown): Promise<Hash>;
   get(hash: Hash): CasNode | null;
   has(hash: Hash): boolean;
-  list(): Hash[];
+  listByType(typeHash: Hash): Hash[];
+  listAll(): Hash[];
+  listMeta(): Hash[];
+  listSchemas(): Hash[];
+  delete(hash: Hash): void;
 };

packages/json-cas/src/variable-store.ts

@@ -0,0 +1,726 @@
+import { Database } from "bun:sqlite";
+import type { Hash, Store } from "./types.js";
+import type { Variable } from "./variable.js";
+
+/**
+ * Custom error types for variable operations
+ */
+export class VariableNotFoundError extends Error {
+  constructor(
+    public variableName: string,
+    public variableSchema: Hash,
+  ) {
+    super(`Variable not found: name=${variableName}, schema=${variableSchema}`);
+    this.name = "VariableNotFoundError";
+  }
+}
+
+export class InvalidVariableNameError extends Error {
+  constructor(
+    public variableName: string,
+    public reason: string,
+  ) {
+    super(`Invalid variable name "${variableName}": ${reason}`);
+    this.name = "InvalidVariableNameError";
+  }
+}
+
+export class SchemaMismatchError extends Error {
+  constructor(
+    public expected: string,
+    public actual: string,
+  ) {
+    super(`Schema mismatch: expected ${expected}, got ${actual}`);
+    this.name = "SchemaMismatchError";
+  }
+}
+
+export class CasNodeNotFoundError extends Error {
+  constructor(
+    public readonly hash: string,
+    message?: string,
+  ) {
+    super(message ?? `CAS node not found: ${hash}`);
+    this.name = "CasNodeNotFoundError";
+  }
+}
+
+export class TagLabelConflictError extends Error {
+  constructor(
+    public conflictName: string,
+    public existingType: "tag" | "label",
+    public attemptedType: "tag" | "label",
+  ) {
+    super(`Conflict: '${conflictName}' already exists as a ${existingType}`);
+    this.name = "TagLabelConflictError";
+  }
+}
+
+export class InvalidTagFormatError extends Error {
+  constructor(tag: string) {
+    super(`Invalid tag format: ${tag}`);
+    this.name = "InvalidTagFormatError";
+  }
+}
+
+/**
+ * Variable store with SQLite backend
+ */
+export class VariableStore {
+  private db: Database;
+
+  constructor(
+    dbPath: string,
+    private casStore: Store,
+  ) {
+    this.db = new Database(dbPath, { create: true });
+    // Enable foreign keys
+    this.db.exec("PRAGMA foreign_keys = ON");
+    this.initDb();
+  }
+
+  private initDb(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS variables (
+        name TEXT NOT NULL,
+        schema TEXT NOT NULL,
+        value TEXT NOT NULL,
+        created INTEGER NOT NULL,
+        updated INTEGER NOT NULL,
+        PRIMARY KEY (name, schema)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_var_name ON variables(name);
+      CREATE INDEX IF NOT EXISTS idx_var_value ON variables(value);
+      CREATE INDEX IF NOT EXISTS idx_var_schema ON variables(schema);
+
+      CREATE TABLE IF NOT EXISTS variable_tags (
+        variable_name TEXT NOT NULL,
+        variable_schema TEXT NOT NULL,
+        key TEXT NOT NULL,
+        value TEXT NOT NULL,
+        PRIMARY KEY (variable_name, variable_schema, key),
+        FOREIGN KEY (variable_name, variable_schema) REFERENCES variables(name, schema) ON DELETE CASCADE
+      );
+
+      CREATE TABLE IF NOT EXISTS variable_labels (
+        variable_name TEXT NOT NULL,
+        variable_schema TEXT NOT NULL,
+        name TEXT NOT NULL,
+        PRIMARY KEY (variable_name, variable_schema, name),
+        FOREIGN KEY (variable_name, variable_schema) REFERENCES variables(name, schema) ON DELETE CASCADE
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_var_tag_key ON variable_tags(key);
+      CREATE INDEX IF NOT EXISTS idx_var_tag_key_value ON variable_tags(key, value);
+      CREATE INDEX IF NOT EXISTS idx_var_label_name ON variable_labels(name);
+    `);
+  }
+
+  /**
+   * Validate variable name format
+   * @ is allowed at the start of the first segment (system-reserved)
+   */
+  private validateName(name: string): void {
+    // Rule 1: Cannot be empty
+    if (name === "") {
+      throw new InvalidVariableNameError(name, "Name cannot be empty");
+    }
+
+    // Rule 2: No leading slash
+    if (name.startsWith("/")) {
+      throw new InvalidVariableNameError(
+        name,
+        "Name cannot start with leading slash",
+      );
+    }
+
+    // Rule 3: No trailing slash
+    if (name.endsWith("/")) {
+      throw new InvalidVariableNameError(
+        name,
+        "Name cannot end with trailing slash",
+      );
+    }
+
+    // Rule 4: Each segment must match [a-zA-Z0-9._-]+ (with @ allowed at start of first segment)
+    const segments = name.split("/");
+    for (let i = 0; i < segments.length; i++) {
+      const segment = segments[i] as string;
+      if (segment === "") {
+        throw new InvalidVariableNameError(
+          name,
+          "Name contains empty segment (consecutive slashes //)",
+        );
+      }
+
+      // Check for invalid characters
+      // First segment can start with @, all segments can contain [a-zA-Z0-9._-]
+      const regex = i === 0 ? /^@?[a-zA-Z0-9._-]+$/ : /^[a-zA-Z0-9._-]+$/;
+      if (!regex.test(segment)) {
+        throw new InvalidVariableNameError(
+          name,
+          `Segment "${segment}" contains invalid characters (only ${i === 0 ? "@, " : ""}a-z, A-Z, 0-9, ., _, - allowed)`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Extract schema hash from CAS node
+   */
+  private extractSchema(hash: string): string {
+    const node = this.casStore.get(hash);
+    if (node === null) {
+      throw new CasNodeNotFoundError(hash);
+    }
+    return node.type;
+  }
+
+  /**
+   * Load tags for a variable
+   */
+  private loadTags(name: string, schema: Hash): Record<string, string> {
+    const stmt = this.db.prepare(`
+      SELECT key, value
+      FROM variable_tags
+      WHERE variable_name = ? AND variable_schema = ?
+    `);
+
+    const rows = stmt.all(name, schema) as Array<{
+      key: string;
+      value: string;
+    }>;
+    const tags: Record<string, string> = {};
+    for (const row of rows) {
+      tags[row.key] = row.value;
+    }
+    return tags;
+  }
+
+  /**
+   * Load labels for a variable
+   */
+  private loadLabels(name: string, schema: Hash): string[] {
+    const stmt = this.db.prepare(`
+      SELECT name
+      FROM variable_labels
+      WHERE variable_name = ? AND variable_schema = ?
+      ORDER BY name ASC
+    `);
+
+    const rows = stmt.all(name, schema) as Array<{ name: string }>;
+    return rows.map((row) => row.name);
+  }
+
+  /**
+   * Set a variable (upsert: create or update)
+   */
+  set(
+    name: string,
+    value: string,
+    options?: {
+      tags?: Record<string, string>;
+      labels?: string[];
+    },
+  ): Variable {
+    // Validate name format
+    this.validateName(name);
+
+    const schema = this.extractSchema(value);
+
+    // Check if variable exists
+    const existing = this.get(name, schema);
+
+    if (existing !== null) {
+      // Update existing variable
+      const now = Date.now();
+
+      // If options provided, use them; otherwise preserve existing
+      const tags = options?.tags ?? existing.tags;
+      const labels = options?.labels ?? existing.labels;
+
+      // Check for tag/label conflicts when updating with new options
+      if (options !== undefined) {
+        const tagKeys = Object.keys(tags);
+        for (const key of tagKeys) {
+          if (labels.includes(key)) {
+            throw new TagLabelConflictError(key, "label", "tag");
+          }
+        }
+      }
+
+      this.db.exec("BEGIN TRANSACTION");
+
+      try {
+        // Update value and timestamp
+        const updateStmt = this.db.prepare(`
+          UPDATE variables
+          SET value = ?, updated = ?
+          WHERE name = ? AND schema = ?
+        `);
+        updateStmt.run(value, now, name, schema);
+
+        // If options provided, update tags/labels
+        if (options !== undefined) {
+          // Delete existing tags and labels
+          this.db
+            .prepare(`
+            DELETE FROM variable_tags WHERE variable_name = ? AND variable_schema = ?
+          `)
+            .run(name, schema);
+
+          this.db
+            .prepare(`
+            DELETE FROM variable_labels WHERE variable_name = ? AND variable_schema = ?
+          `)
+            .run(name, schema);
+
+          // Insert new tags
+          const tagKeys = Object.keys(tags);
+          if (tagKeys.length > 0) {
+            const tagStmt = this.db.prepare(`
+              INSERT INTO variable_tags (variable_name, variable_schema, key, value)
+              VALUES (?, ?, ?, ?)
+            `);
+            for (const [key, val] of Object.entries(tags)) {
+              tagStmt.run(name, schema, key, val);
+            }
+          }
+
+          // Insert new labels
+          if (labels.length > 0) {
+            const labelStmt = this.db.prepare(`
+              INSERT INTO variable_labels (variable_name, variable_schema, name)
+              VALUES (?, ?, ?)
+            `);
+            for (const labelName of labels) {
+              labelStmt.run(name, schema, labelName);
+            }
+          }
+        }
+
+        this.db.exec("COMMIT");
+      } catch (e) {
+        this.db.exec("ROLLBACK");
+        throw e;
+      }
+
+      return {
+        name,
+        schema,
+        value,
+        created: existing.created,
+        updated: now,
+        tags,
+        labels: [...labels],
+      };
+    }
+
+    // Create new variable
+    const tags = options?.tags ?? {};
+    const labels = options?.labels ?? [];
+
+    // Check for tag/label conflicts
+    const tagKeys = Object.keys(tags);
+    for (const key of tagKeys) {
+      if (labels.includes(key)) {
+        throw new TagLabelConflictError(key, "label", "tag");
+      }
+    }
+
+    const now = Date.now();
+
+    this.db.exec("BEGIN TRANSACTION");
+
+    try {
+      const stmt = this.db.prepare(`
+        INSERT INTO variables (name, schema, value, created, updated)
+        VALUES (?, ?, ?, ?, ?)
+      `);
+
+      stmt.run(name, schema, value, now, now);
+
+      // Insert tags
+      if (tagKeys.length > 0) {
+        const tagStmt = this.db.prepare(`
+          INSERT INTO variable_tags (variable_name, variable_schema, key, value)
+          VALUES (?, ?, ?, ?)
+        `);
+        for (const [key, val] of Object.entries(tags)) {
+          tagStmt.run(name, schema, key, val);
+        }
+      }
+
+      // Insert labels
+      if (labels.length > 0) {
+        const labelStmt = this.db.prepare(`
+          INSERT INTO variable_labels (variable_name, variable_schema, name)
+          VALUES (?, ?, ?)
+        `);
+        for (const labelName of labels) {
+          labelStmt.run(name, schema, labelName);
+        }
+      }
+
+      this.db.exec("COMMIT");
+    } catch (e) {
+      this.db.exec("ROLLBACK");
+      throw e;
+    }
+
+    return {
+      name,
+      schema,
+      value,
+      created: now,
+      updated: now,
+      tags,
+      labels: [...labels],
+    };
+  }
+
+  /**
+   * Get a variable by name, optionally with schema
+   */
+  /**
+   * Get a variable by name and schema
+   * @param name - Variable name
+   * @param schema - Schema hash (required)
+   * @returns Variable if found, null otherwise
+   */
+  get(name: string, schema: Hash): Variable | null {
+    // Precise match with schema
+    const stmt = this.db.prepare(`
+      SELECT name, schema, value, created, updated
+      FROM variables
+      WHERE name = ? AND schema = ?
+    `);
+
+    const row = stmt.get(name, schema) as
+      | {
+          name: string;
+          schema: string;
+          value: string;
+          created: number;
+          updated: number;
+        }
+      | undefined
+      | null;
+
+    if (row === undefined || row === null) {
+      return null;
+    }
+
+    const tags = this.loadTags(row.name, row.schema);
+    const labels = this.loadLabels(row.name, row.schema);
+
+    return {
+      name: row.name,
+      schema: row.schema,
+      value: row.value,
+      created: row.created,
+      updated: row.updated,
+      tags,
+      labels,
+    };
+  }
+
+  /**
+   * Update a variable's value (with schema validation)
+   */
+  update(name: string, schema: Hash, value: string): Variable {
+    // Validate name format
+    this.validateName(name);
+
+    const existing = this.get(name, schema);
+    if (existing === null) {
+      throw new VariableNotFoundError(name, schema);
+    }
+
+    const newSchema = this.extractSchema(value);
+    if (newSchema !== existing.schema) {
+      throw new SchemaMismatchError(existing.schema, newSchema);
+    }
+
+    const now = Date.now();
+
+    const stmt = this.db.prepare(`
+      UPDATE variables
+      SET value = ?, updated = ?
+      WHERE name = ? AND schema = ?
+    `);
+
+    stmt.run(value, now, name, schema);
+
+    return {
+      ...existing,
+      value,
+      updated: now,
+    };
+  }
+
+  /**
+   * Remove a variable (or all variants if schema omitted)
+   */
+  remove(name: string): Variable[];
+  remove(name: string, schema: Hash): Variable;
+  remove(name: string, schema?: Hash): Variable | Variable[] {
+    if (schema !== undefined) {
+      // Remove specific (name, schema) variant
+      const existing = this.get(name, schema);
+      if (existing === null) {
+        throw new VariableNotFoundError(name, schema);
+      }
+
+      const stmt = this.db.prepare(`
+        DELETE FROM variables WHERE name = ? AND schema = ?
+      `);
+
+      stmt.run(name, schema);
+
+      return existing;
+    }
+
+    // Remove all schema variants for this name
+    const variants = this.list({ exactName: name });
+
+    if (variants.length === 0) {
+      return [];
+    }
+
+    const stmt = this.db.prepare(`
+      DELETE FROM variables WHERE name = ?
+    `);
+
+    stmt.run(name);
+
+    return variants;
+  }
+
+  /**
+   * List variables with optional filters
+   */
+  list(options?: {
+    namePrefix?: string;
+    exactName?: string;
+    schema?: Hash;
+    tags?: Record<string, string>;
+    labels?: string[];
+  }): Variable[] {
+    // Validate mutually exclusive options
+    if (options?.namePrefix !== undefined && options?.exactName !== undefined) {
+      throw new Error(
+        "namePrefix and exactName are mutually exclusive - cannot specify both",
+      );
+    }
+
+    const namePrefix = options?.namePrefix ?? "";
+    const exactName = options?.exactName;
+    const schema = options?.schema;
+    const filterTags = options?.tags ?? {};
+    const filterLabels = options?.labels ?? [];
+
+    // Build query with filters
+    let query = `
+      SELECT DISTINCT v.name, v.schema, v.value, v.created, v.updated
+      FROM variables v
+    `;
+
+    const params: (string | number)[] = [];
+
+    // Tag filters (AND logic)
+    const tagKeys = Object.keys(filterTags);
+    for (let i = 0; i < tagKeys.length; i++) {
+      const key = tagKeys[i] as string;
+      const value = filterTags[key] as string;
+      query += `
+        INNER JOIN variable_tags t${i} ON v.name = t${i}.variable_name
+          AND v.schema = t${i}.variable_schema
+          AND t${i}.key = ? AND t${i}.value = ?
+      `;
+      params.push(key, value);
+    }
+
+    // Label filters (AND logic)
+    for (let i = 0; i < filterLabels.length; i++) {
+      const label = filterLabels[i] as string;
+      query += `
+        INNER JOIN variable_labels l${i} ON v.name = l${i}.variable_name
+          AND v.schema = l${i}.variable_schema
+          AND l${i}.name = ?
+      `;
+      params.push(label);
+    }
+
+    // WHERE clause for name filters and schema
+    const whereClauses: string[] = [];
+
+    if (exactName !== undefined) {
+      whereClauses.push("v.name = ?");
+      params.push(exactName);
+    } else if (namePrefix !== "") {
+      whereClauses.push("v.name LIKE ? || '%'");
+      params.push(namePrefix);
+    }
+
+    if (schema !== undefined) {
+      whereClauses.push("v.schema = ?");
+      params.push(schema);
+    }
+
+    if (whereClauses.length > 0) {
+      query += ` WHERE ${whereClauses.join(" AND ")}`;
+    }
+
+    query += " ORDER BY v.created ASC";
+
+    const stmt = this.db.prepare(query);
+    const rows = stmt.all(...params) as Array<{
+      name: string;
+      schema: string;
+      value: string;
+      created: number;
+      updated: number;
+    }>;
+
+    return rows.map((row) => ({
+      name: row.name,
+      schema: row.schema,
+      value: row.value,
+      created: row.created,
+      updated: row.updated,
+      tags: this.loadTags(row.name, row.schema),
+      labels: this.loadLabels(row.name, row.schema),
+    }));
+  }
+
+  /**
+   * Add/update/delete tags and labels
+   */
+  tag(
+    name: string,
+    schema: Hash,
+    operations: {
+      add?: Record<string, string>; // tags to add/update
+      addLabels?: string[]; // labels to add
+      delete?: string[]; // tag keys or label names to delete
+    },
+  ): Variable {
+    // Validate name format
+    this.validateName(name);
+
+    const existing = this.get(name, schema);
+    if (existing === null) {
+      throw new VariableNotFoundError(name, schema);
+    }
+
+    const addTags = operations.add ?? {};
+    const addLabels = operations.addLabels ?? [];
+    const deleteNames = operations.delete ?? [];
+
+    // Check for conflicts between tags and labels
+    const newTagKeys = Object.keys(addTags);
+    for (const key of newTagKeys) {
+      // Check if this key is being added as a label in the same operation
+      if (addLabels.includes(key)) {
+        throw new TagLabelConflictError(key, "label", "tag");
+      }
+      // Check if this key already exists as a label (and not being deleted)
+      if (existing.labels.includes(key) && !deleteNames.includes(key)) {
+        throw new TagLabelConflictError(key, "label", "tag");
+      }
+    }
+
+    for (const labelName of addLabels) {
+      // Check if this name is being added as a tag in the same operation
+      if (newTagKeys.includes(labelName)) {
+        throw new TagLabelConflictError(labelName, "tag", "label");
+      }
+      // Check if this name already exists as a tag key (and not being deleted)
+      if (
+        existing.tags[labelName] !== undefined &&
+        !deleteNames.includes(labelName)
+      ) {
+        throw new TagLabelConflictError(labelName, "tag", "label");
+      }
+    }
+
+    const now = Date.now();
+
+    this.db.exec("BEGIN TRANSACTION");
+
+    try {
+      // Update timestamp
+      const updateStmt = this.db.prepare(`
+        UPDATE variables SET updated = ? WHERE name = ? AND schema = ?
+      `);
+      updateStmt.run(now, name, schema);
+
+      // Delete tags and labels
+      if (deleteNames.length > 0) {
+        const deleteTagStmt = this.db.prepare(`
+          DELETE FROM variable_tags WHERE variable_name = ? AND variable_schema = ? AND key = ?
+        `);
+        const deleteLabelStmt = this.db.prepare(`
+          DELETE FROM variable_labels WHERE variable_name = ? AND variable_schema = ? AND name = ?
+        `);
+        for (const deleteName of deleteNames) {
+          deleteTagStmt.run(name, schema, deleteName);
+          deleteLabelStmt.run(name, schema, deleteName);
+        }
+      }
+
+      // Add or update tags
+      if (newTagKeys.length > 0) {
+        const tagStmt = this.db.prepare(`
+          INSERT OR REPLACE INTO variable_tags (variable_name, variable_schema, key, value)
+          VALUES (?, ?, ?, ?)
+        `);
+        for (const [key, value] of Object.entries(addTags)) {
+          tagStmt.run(name, schema, key, value);
+        }
+      }
+
+      // Add labels (with conflict handling)
+      if (addLabels.length > 0) {
+        const labelStmt = this.db.prepare(`
+          INSERT OR IGNORE INTO variable_labels (variable_name, variable_schema, name)
+          VALUES (?, ?, ?)
+        `);
+        for (const labelName of addLabels) {
+          labelStmt.run(name, schema, labelName);
+        }
+      }
+
+      this.db.exec("COMMIT");
+    } catch (e) {
+      this.db.exec("ROLLBACK");
+      throw e;
+    }
+
+    // Return updated variable
+    const updated = this.get(name, schema);
+    if (updated === null) {
+      throw new VariableNotFoundError(name, schema);
+    }
+    return updated;
+  }
+
+  /**
+   * Close the database connection
+   */
+  close(): void {
+    this.db.close();
+  }
+}
+
+/**
+ * Create a variable store
+ */
+export function createVariableStore(
+  dbPath: string,
+  casStore: Store,
+): VariableStore {
+  return new VariableStore(dbPath, casStore);
+}

packages/json-cas/src/variable.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import type { Variable } from "./variable.js";
+
+describe("Variable Type", () => {
+  test("Variable type uses (name, schema) composite key", () => {
+    const variable: Variable = {
+      name: "config",
+      schema: "ABC123DEF4567",
+      value: "XYZ789GHI0123",
+      created: 1234567890000,
+      updated: 1234567890000,
+      tags: { env: "prod" },
+      labels: ["critical"],
+    };
+
+    expect(variable.name).toBe("config");
+    expect(variable.schema).toBe("ABC123DEF4567");
+    // id and scope should not exist
+    expect((variable as unknown as { id?: unknown }).id).toBeUndefined();
+    expect((variable as unknown as { scope?: unknown }).scope).toBeUndefined();
+  });
+});

packages/json-cas/src/variable.ts

@@ -0,0 +1,15 @@
+import type { Hash } from "./types.js";
+
+/**
+ * Variable: mutable binding to an immutable CAS node
+ * Identified by composite key (name, schema)
+ */
+export type Variable = {
+  name: string; // variable name (unique per schema)
+  schema: Hash; // schema hash (part of composite key)
+  value: Hash; // CAS node hash
+  created: number; // epoch ms
+  updated: number; // epoch ms
+  tags: Record<string, string>; // key-value pairs
+  labels: string[]; // bare identifiers
+};

packages/json-cas/src/wrap-envelope.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from "bun:test";
+import { bootstrap } from "./bootstrap.js";
+import { createMemoryStore } from "./store.js";
+import { wrapEnvelope } from "./wrap-envelope.js";
+
+describe("wrapEnvelope", () => {
+  test("resolves @output/put alias and returns envelope", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+
+    const envelope = await wrapEnvelope(store, "@output/put", "AAAAAAAAAAAAA");
+
+    expect(envelope.type).toBe(aliases["@output/put"]);
+    expect(envelope.value).toBe("AAAAAAAAAAAAA");
+  });
+
+  test("resolves @output/has alias with boolean value", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+
+    const envelope = await wrapEnvelope(store, "@output/has", true);
+
+    expect(envelope.type).toBe(aliases["@output/has"]);
+    expect(envelope.value).toBe(true);
+  });
+
+  test("resolves @output/gc alias with object value", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+
+    const gcStats = { total: 100, reachable: 80, collected: 20, scanned: 5 };
+    const envelope = await wrapEnvelope(store, "@output/gc", gcStats);
+
+    expect(envelope.type).toBe(aliases["@output/gc"]);
+    expect(envelope.value).toEqual(gcStats);
+  });
+
+  test("resolves primitive alias @string", async () => {
+    const store = createMemoryStore();
+    const aliases = await bootstrap(store);
+
+    const envelope = await wrapEnvelope(store, "@string", "hello");
+
+    expect(envelope.type).toBe(aliases["@string"]);
+    expect(envelope.value).toBe("hello");
+  });
+
+  test("throws for unknown alias", async () => {
+    const store = createMemoryStore();
+    await bootstrap(store);
+
+    await expect(
+      wrapEnvelope(store, "@output/nonexistent", "value"),
+    ).rejects.toThrow("Unknown schema alias: @output/nonexistent");
+  });
+
+  test("is idempotent — same alias returns same type hash", async () => {
+    const store = createMemoryStore();
+
+    const first = await wrapEnvelope(store, "@output/verify", "ok");
+    const second = await wrapEnvelope(store, "@output/verify", "corrupted");
+
+    expect(first.type).toBe(second.type);
+    expect(first.value).toBe("ok");
+    expect(second.value).toBe("corrupted");
+  });
+
+  test("preserves complex object values without mutation", async () => {
+    const store = createMemoryStore();
+    await bootstrap(store);
+
+    const original = {
+      name: "test",
+      schema: "AAAAAAAAAAAAA",
+      value: "BBBBBBBBBBBBB",
+      created: 1000,
+      updated: 2000,
+      tags: { env: "prod" },
+      labels: ["stable"],
+    };
+    const envelope = await wrapEnvelope(store, "@output/var-set", original);
+
+    expect(envelope.value).toEqual(original);
+  });
+});

packages/json-cas/src/wrap-envelope.ts

@@ -0,0 +1,19 @@
+import { bootstrap } from "./bootstrap.js";
+import type { Hash, Store } from "./types.js";
+
+/**
+ * Resolve a schema alias (e.g. "@output/put") to its hash via bootstrap,
+ * then return a typed envelope ready for store.put() or direct rendering.
+ */
+export async function wrapEnvelope(
+  store: Store,
+  schemaAlias: string,
+  value: unknown,
+): Promise<{ type: Hash; value: unknown }> {
+  const aliases = await bootstrap(store);
+  const typeHash = aliases[schemaAlias];
+  if (typeHash === undefined) {
+    throw new Error(`Unknown schema alias: ${schemaAlias}`);
+  }
+  return { type: typeHash, value };
+}

packages/json-cas/tests/schema-validation.test.ts

@@ -0,0 +1,754 @@
+import { describe, expect, test } from "bun:test";
+import { bootstrap } from "../src/bootstrap.js";
+import { MemStore } from "../src/mem-store.js";
+import type { JSONSchema } from "../src/schema.js";
+import {
+  getSchema,
+  putSchema,
+  refs,
+  SchemaValidationError,
+  validate,
+  walk,
+} from "../src/schema.js";
+import type { CasNode } from "../src/types.js";
+
+describe("Test Suite 1: Meta-Schema Structure and Self-Validation", () => {
+  test("1.1: Meta-schema is a valid JSON Schema", async () => {
+    const store = new MemStore();
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
+    const metaNode = store.get(metaHash);
+
+    expect(metaNode).not.toBeNull();
+    expect(typeof metaNode?.payload).toBe("object");
+    expect(metaNode?.payload).toHaveProperty("type");
+  });
+
+  test("1.2: Meta-schema self-validates", async () => {
+    const store = new MemStore();
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
+    const metaNode = store.get(metaHash);
+
+    expect(metaNode).not.toBeNull();
+    expect(validate(store, metaNode as CasNode)).toBe(true);
+  });
+
+  test("1.3: Meta-schema defines all supported keywords", async () => {
+    const store = new MemStore();
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
+    const metaSchema = getSchema(store, metaHash);
+
+    expect(metaSchema).not.toBeNull();
+    const properties =
+      (metaSchema?.properties as Record<string, unknown>) || {};
+
+    // Check that all supported keywords are defined
+    expect(properties).toHaveProperty("type");
+    expect(properties).toHaveProperty("properties");
+    expect(properties).toHaveProperty("required");
+    expect(properties).toHaveProperty("additionalProperties");
+    expect(properties).toHaveProperty("anyOf");
+    expect(properties).toHaveProperty("items");
+    expect(properties).toHaveProperty("format");
+    expect(properties).toHaveProperty("title");
+    expect(properties).toHaveProperty("enum");
+    expect(properties).toHaveProperty("const");
+    expect(properties).toHaveProperty("description");
+  });
+
+  test("1.4: Meta-schema does not include unsupported keywords", async () => {
+    const store = new MemStore();
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
+    const metaSchema = getSchema(store, metaHash);
+
+    expect(metaSchema).not.toBeNull();
+    const properties =
+      (metaSchema?.properties as Record<string, unknown>) || {};
+
+    // Unsupported keywords should not be in properties
+    expect(properties).not.toHaveProperty("$ref");
+    expect(properties).not.toHaveProperty("$id");
+    expect(properties).not.toHaveProperty("$defs");
+
+    // P2 keywords should be present
+    expect(properties).toHaveProperty("allOf");
+    expect(properties).toHaveProperty("if");
+    expect(properties).toHaveProperty("then");
+    expect(properties).toHaveProperty("else");
+    expect(properties).toHaveProperty("patternProperties");
+    expect(properties).toHaveProperty("prefixItems");
+    expect(properties).toHaveProperty("multipleOf");
+    expect(properties).toHaveProperty("minProperties");
+    expect(properties).toHaveProperty("maxProperties");
+    expect(properties).toHaveProperty("default");
+
+    // P3 keywords should be present
+    expect(properties).toHaveProperty("not");
+    expect(properties).toHaveProperty("contains");
+    expect(properties).toHaveProperty("propertyNames");
+    expect(properties).toHaveProperty("examples");
+    expect(properties).toHaveProperty("readOnly");
+    expect(properties).toHaveProperty("writeOnly");
+    expect(properties).toHaveProperty("deprecated");
+    expect(properties).toHaveProperty("$comment");
+  });
+
+  test("1.5: Meta-schema node type equals its own hash", async () => {
+    const store = new MemStore();
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
+    const metaNode = store.get(metaHash);
+
+    expect(metaNode).not.toBeNull();
+    expect(metaNode?.type).toBe(metaHash);
+  });
+});
+
+describe("Test Suite 2: putSchema Validation - Valid Schemas", () => {
+  test("2.1: Accept minimal valid schema (empty object)", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {});
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.2: Accept schema with type constraint", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, { type: "string" });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.3: Accept schema with properties", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      type: "object",
+      properties: { name: { type: "string" } },
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.4: Accept schema with required fields", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      type: "object",
+      required: ["id"],
+      properties: { id: { type: "string" } },
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.5: Accept schema with additionalProperties = false", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      type: "object",
+      additionalProperties: false,
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.6: Accept schema with additionalProperties = schema", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      type: "object",
+      additionalProperties: { type: "string" },
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.7: Accept schema with anyOf", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      anyOf: [{ type: "string" }, { type: "null" }],
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.7b: Accept schema with oneOf", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      oneOf: [
+        { properties: { status: { const: "ready" } }, required: ["status"] },
+        { properties: { status: { const: "failed" } }, required: ["status"] },
+      ],
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.8: Accept schema with array items", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      type: "array",
+      items: { type: "number" },
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.9: Accept schema with format constraint", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      type: "string",
+      format: "cas_ref",
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.10: Accept schema with enum", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      type: "string",
+      enum: ["red", "green", "blue"],
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.11: Accept schema with const", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, { const: "FIXED_VALUE" });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.12: Accept schema with title and description", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      type: "string",
+      title: "User Name",
+      description: "The user's full name",
+    });
+    expect(hash).toBeTruthy();
+  });
+
+  test("2.13: Accept complex nested schema", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    const hash = await putSchema(store, {
+      type: "object",
+      required: ["type", "payload"],
+      properties: {
+        type: { type: "string", format: "cas_ref" },
+        payload: {
+          anyOf: [{ type: "object" }, { type: "null" }],
+        },
+        refs: {
+          type: "array",
+          items: { type: "string", format: "cas_ref" },
+        },
+      },
+      additionalProperties: false,
+    });
+    expect(hash).toBeTruthy();
+  });
+});
+
+describe("Test Suite 3: putSchema Validation - Invalid Schemas", () => {
+  test("3.1: Reject schema with invalid type value", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(async () => await putSchema(store, { type: "garbage" })).toThrow();
+  });
+
+  test("3.2: Reject schema with type as number", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, { type: 123 } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.3: Reject schema with properties not an object", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "object",
+          properties: "not-an-object",
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.4: Reject schema with required not an array", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "object",
+          required: "name",
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.5: Reject schema with required containing non-strings", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "object",
+          required: ["name", 123, true],
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.6: Reject schema with additionalProperties as string", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "object",
+          additionalProperties: "yes",
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.7: Reject schema with anyOf not an array", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          anyOf: { type: "string" },
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.8: Reject schema with empty anyOf array", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(async () => await putSchema(store, { anyOf: [] })).toThrow();
+  });
+
+  test("3.9: Reject schema with items not an object", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "array",
+          items: "string",
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.10: Reject schema with format not a string", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "string",
+          format: 123,
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.11: Reject schema with enum not an array", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "string",
+          enum: "red",
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.12: Reject schema with empty enum array", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () => await putSchema(store, { type: "string", enum: [] }),
+    ).toThrow();
+  });
+
+  test("3.13: Reject schema with title not a string", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "string",
+          title: 123,
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.14: Reject schema with description not a string", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "string",
+          description: ["not a string"],
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.15: Reject schema with unsupported $ref keyword", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          $ref: "#/definitions/user",
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.16: Reject completely invalid data (non-object)", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, "not-a-schema" as unknown as JSONSchema),
+    ).toThrow();
+  });
+
+  test("3.17: Reject nested invalid schema in properties", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    expect(
+      async () =>
+        await putSchema(store, {
+          type: "object",
+          properties: {
+            name: { type: "invalid-type" },
+          },
+        } as unknown as JSONSchema),
+    ).toThrow();
+  });
+});
+
+describe("Test Suite 4: Error Messages and Debugging", () => {
+  test("4.1: Error includes schema validation details", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    try {
+      await putSchema(store, { type: 123 } as unknown as JSONSchema);
+      expect(true).toBe(false); // Should not reach here
+    } catch (error) {
+      expect(error).toBeInstanceOf(SchemaValidationError);
+      expect((error as Error).message).toContain("Invalid schema");
+    }
+  });
+
+  test("4.2: Error distinguishes schema validation from data validation", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+    try {
+      await putSchema(store, { type: "invalid-type" } as unknown as JSONSchema);
+      expect(true).toBe(false); // Should not reach here
+    } catch (error) {
+      expect(error).toBeInstanceOf(SchemaValidationError);
+      expect((error as Error).message.toLowerCase()).toContain("schema");
+    }
+  });
+});
+
+describe("Test Suite 5: Backward Compatibility and Migration", () => {
+  test("5.1: Bootstrap hash changes (breaking change)", async () => {
+    // This is a documentation test - the old hash was different
+    const store = new MemStore();
+    const builtinSchemas = await bootstrap(store);
+    const newMetaHash = builtinSchemas["@schema"] ?? "";
+
+    // The new hash should be different from the old system metadata hash
+    // We just verify it's a valid hash format
+    expect(newMetaHash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+  });
+
+  test("5.2: Existing tests compatibility", async () => {
+    // This test ensures our changes don't break existing valid schema usage
+    const store = new MemStore();
+    await bootstrap(store);
+
+    // This is the kind of schema that existed before
+    const schemaHash = await putSchema(store, {
+      type: "object",
+      properties: {
+        name: { type: "string" },
+      },
+    });
+
+    expect(schemaHash).toBeTruthy();
+  });
+
+  test("5.3: Data nodes with valid schemas still validate", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    const schemaHash = await putSchema(store, {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string" },
+      },
+    });
+
+    const dataNode = store.get(await store.put(schemaHash, { name: "test" }));
+
+    expect(dataNode).not.toBeNull();
+    expect(validate(store, dataNode as CasNode)).toBe(true);
+  });
+
+  test("5.4: Invalid data still fails validation", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    const schemaHash = await putSchema(store, {
+      type: "object",
+      required: ["name"],
+      properties: {
+        name: { type: "string" },
+      },
+    });
+
+    const dataNode = store.get(
+      await store.put(schemaHash, { name: 123 }), // wrong type
+    );
+
+    expect(dataNode).not.toBeNull();
+    expect(validate(store, dataNode as CasNode)).toBe(false);
+  });
+});
+
+describe("Test Suite 6: Integration with Existing Functionality", () => {
+  test("6.1: getSchema works with validated schemas", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    const originalSchema = { type: "string", title: "Test" };
+    const schemaHash = await putSchema(store, originalSchema);
+    const retrieved = getSchema(store, schemaHash);
+
+    expect(retrieved).toEqual(originalSchema);
+  });
+
+  test("6.2: validate() works with schemas validated by meta-schema", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    const schemaHash = await putSchema(store, { type: "number" });
+    const validNode = store.get(await store.put(schemaHash, 42));
+    const invalidNode = store.get(await store.put(schemaHash, "not a number"));
+
+    expect(validate(store, validNode as CasNode)).toBe(true);
+    expect(validate(store, invalidNode as CasNode)).toBe(false);
+  });
+
+  test("6.3: refs() works with validated schemas containing cas_ref", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    const schemaHash = await putSchema(store, {
+      type: "object",
+      properties: {
+        ref: { type: "string", format: "cas_ref" },
+      },
+    });
+
+    const refHash = "0000000000001";
+    const dataNode = store.get(await store.put(schemaHash, { ref: refHash }));
+
+    const extractedRefs = refs(store, dataNode as CasNode);
+    expect(extractedRefs).toContain(refHash);
+  });
+
+  test("6.4: walk() works with graphs using validated schemas", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    const schemaHash = await putSchema(store, {
+      type: "object",
+      properties: {
+        next: {
+          anyOf: [{ type: "string", format: "cas_ref" }, { type: "null" }],
+        },
+      },
+    });
+
+    const node2Hash = await store.put(schemaHash, { next: null });
+    const node1Hash = await store.put(schemaHash, { next: node2Hash });
+
+    const visited: string[] = [];
+    walk(store, node1Hash, (hash) => visited.push(hash));
+
+    expect(visited).toContain(node1Hash);
+    expect(visited).toContain(node2Hash);
+  });
+
+  test("6.5: Idempotency preserved for putSchema", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    const schema = { type: "string", title: "Test" };
+    const hash1 = await putSchema(store, schema);
+    const hash2 = await putSchema(store, schema);
+
+    expect(hash1).toBe(hash2);
+  });
+});
+
+describe("Test Suite 7: Meta-Schema Content Validation", () => {
+  test("7.1: Meta-schema allows recursive schema definitions", async () => {
+    const store = new MemStore();
+    const builtinSchemas = await bootstrap(store);
+    const metaHash = builtinSchemas["@schema"] ?? "";
+    const metaSchema = getSchema(store, metaHash);
+
+    expect(metaSchema).not.toBeNull();
+    // The meta-schema should have properties that can contain schemas
+    const properties =
+      (metaSchema?.properties as Record<string, unknown>) || {};
+    expect(properties).toHaveProperty("properties");
+  });
+
+  test("7.2: Meta-schema restricts additionalProperties", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    // Schema with unknown keyword should be rejected if meta-schema is strict
+    try {
+      await putSchema(store, {
+        type: "string",
+        unknownKeyword: "value",
+      } as unknown as JSONSchema);
+      // If we get here, meta-schema allows additional properties
+      // This is acceptable behavior
+    } catch (error) {
+      // If it throws, meta-schema is strict about additionalProperties
+      expect(error).toBeInstanceOf(SchemaValidationError);
+    }
+  });
+
+  test("7.3: Meta-schema validates type as string OR array", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    // Single string type
+    const hash1 = await putSchema(store, { type: "string" });
+    expect(hash1).toBeTruthy();
+
+    // Array of types
+    const hash2 = await putSchema(store, {
+      type: ["string", "null"],
+    } as unknown as JSONSchema);
+    expect(hash2).toBeTruthy();
+
+    // Invalid type (number)
+    expect(
+      async () =>
+        await putSchema(store, { type: 123 } as unknown as JSONSchema),
+    ).toThrow();
+  });
+});
+
+describe("Test Suite 8: Performance and Edge Cases", () => {
+  test("8.1: Validation performance is acceptable", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    const complexSchema = {
+      type: "object",
+      properties: {
+        level1: {
+          type: "object",
+          properties: {
+            level2: {
+              type: "object",
+              properties: {
+                level3: { type: "string" },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const start = performance.now();
+    for (let i = 0; i < 100; i++) {
+      await putSchema(store, complexSchema);
+    }
+    const duration = performance.now() - start;
+
+    // Should complete in reasonable time (< 100ms for 100 validations)
+    expect(duration).toBeLessThan(1000);
+  });
+
+  test("8.2: Large schemas are handled correctly", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    const largeSchema: Record<string, unknown> = {
+      type: "object",
+      properties: {},
+    };
+
+    // Create a schema with 100 properties
+    const props = largeSchema.properties as Record<string, unknown>;
+    for (let i = 0; i < 100; i++) {
+      props[`prop${i}`] = { type: "string" };
+    }
+
+    const hash = await putSchema(store, largeSchema);
+    expect(hash).toBeTruthy();
+  });
+
+  test("8.3: Deeply nested schemas validate correctly", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    // Build a 5-level deep schema
+    let schema: Record<string, unknown> = { type: "string" };
+    for (let i = 0; i < 5; i++) {
+      schema = {
+        type: "object",
+        properties: { nested: schema },
+      };
+    }
+
+    const hash = await putSchema(store, schema);
+    expect(hash).toBeTruthy();
+  });
+
+  test("8.4: Circular-like schemas don't cause infinite loops", async () => {
+    const store = new MemStore();
+    await bootstrap(store);
+
+    // Schema where additionalProperties has same structure as parent
+    const schema = {
+      type: "object",
+      properties: {
+        value: { type: "string" },
+      },
+      additionalProperties: {
+        type: "object",
+        properties: {
+          value: { type: "string" },
+        },
+      },
+    };
+
+    const hash = await putSchema(store, schema);
+    expect(hash).toBeTruthy();
+  });
+});

packages/json-cas/tsconfig.json

@@ -4,5 +4,6 @@
     "rootDir": "src",
     "outDir": "dist"
   },
-  "include": ["src"]
+  "include": ["src"],
+  "exclude": ["src/**/*.test.ts"]
 }

scripts/check-workspace-deps.sh

@@ -0,0 +1,8 @@
+#!/bin/bash
+# Prevent publishing packages that still reference workspace:* dependencies
+if grep -q '"workspace:' package.json 2>/dev/null; then
+  echo "❌ Found workspace:* dependencies in package.json — cannot publish directly."
+  echo "   Use 'changeset publish' which resolves workspace protocol automatically."
+  grep '"workspace:' package.json
+  exit 1
+fi

tsconfig.json

@@ -10,6 +10,10 @@
     "noImplicitOverride": true,
     "verbatimModuleSyntax": true,
     "skipLibCheck": true,
+    "paths": {
+      "@uncaged/json-cas": ["./packages/json-cas/src/index.ts"],
+      "@uncaged/json-cas-fs": ["./packages/json-cas-fs/src/index.ts"]
+    },
     "composite": true,
     "declaration": true,
     "declarationMap": true,