feat: wrap put/get/has/hash/verify/list with {type,value} envelope (Phase 2)

Fixes #70

packages/cli-json-cas/src/__snapshots__/e2e.test.ts.snap

@@ -2,15 +2,23 @@
 
 exports[`Phase 1: CAS Core 1.6 get returns node JSON (snapshot) 1`] = `
 {
-  "payload": {
-    "age": 30,
-    "name": "Alice",
+  "type": "ASE7K6A0HG8W9",
+  "value": {
+    "payload": {
+      "age": 30,
+      "name": "Alice",
+    },
+    "type": "7XX5H51CVD9H0",
   },
-  "type": "7XX5H51CVD9H0",
 }
 `;
 
-exports[`Phase 1: CAS Core 1.9 verify returns ok for valid node 1`] = `"ok"`;
+exports[`Phase 1: CAS Core 1.9 verify returns ok for valid node 1`] = `
+{
+  "type": "8E2M8H30BHXS8",
+  "value": "ok",
+}
+`;
 
 exports[`Phase 1: CAS Core 1.10 refs lists direct references (snapshot) 1`] = `""`;
 
@@ -216,16 +224,16 @@ exports[`Phase 7: Edge Cases 7.5 no subcommand shows help text 1`] = `
 "Usage: json-cas [--store <path>] [--json] <command> [args]
 
 Commands:
-  put <type-hash> <file.json>       Store node, print hash
-  get <hash>                        Print node as JSON
-  has <hash>                        Print true/false
-  verify <hash>                     Verify integrity + schema, print ok/corrupted/invalid
+  put <type-hash> <file.json>       Store node, print { type, value } envelope (value=hash)
+  get <hash>                        Print node as { type, value } envelope
+  has <hash>                        Print { type, value } envelope (value=boolean)
+  verify <hash>                     Verify integrity + schema → { type, value } (value=ok/corrupted/invalid)
   refs <hash>                       List direct cas_ref edges
   walk <hash> [--format tree]       Recursive traversal
-  hash <type-hash> <file.json>      Compute hash without storing (dry run)
+  hash <type-hash> <file.json>      Compute hash without storing → { type, value } envelope
   render <hash> [options]           Render node as YAML with resolution decay
   render --pipe/-p [options]        Render { type, value } from stdin
-  list --type <hash-or-alias>       List all hashes for a given type
+  list --type <hash-or-alias>       List hashes for a type → { type, value } envelope (value=string[])
   var set <name> <hash> [--tag <tag>...] Create/update a variable
   var get <name> --schema <hash>    Get a variable by name + schema
   var delete <name> [--schema <hash>] Delete variable(s)

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

@@ -15,6 +15,11 @@ import { createFsStore, openStore as openFsStore } from "@uncaged/json-cas-fs";
 const pkgPath = resolve(import.meta.dir, "../package.json");
 const entrypoint = resolve(import.meta.dir, "index.ts");
 
+/** 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;
+}
+
 /**
  * Register a schema directly via the library (CLI schema put was removed).
  * Returns the type hash.
@@ -168,8 +173,8 @@ describe("@ Alias Resolution - put", () => {
 
     expect(exitCode).toBe(0);
     expect(stderr).toBe("");
-    // Should output a valid hash (13 chars)
-    expect(stdout).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    // 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 () => {
@@ -185,7 +190,7 @@ describe("@ Alias Resolution - put", () => {
     );
 
     expect(exitCode).toBe(0);
-    expect(stdout).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
   });
 
   test("ucas put @object <file> should resolve alias", async () => {
@@ -201,7 +206,7 @@ describe("@ Alias Resolution - put", () => {
     );
 
     expect(exitCode).toBe(0);
-    expect(stdout).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
   });
 
   test("ucas put @invalid <file> should fail", async () => {
@@ -236,7 +241,7 @@ describe("@ Alias Resolution - hash", () => {
 
     expect(exitCode).toBe(0);
     expect(stderr).toBe("");
-    expect(stdout).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
   });
 });
 
@@ -313,10 +318,10 @@ describe("Issue #50: Schema Validation in put", () => {
 
         expect(exitCode).toBe(0);
         expect(stderr).toBe("");
-        expect(stdout.trim()).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
 
         // Verify node was stored
-        const hash = stdout.trim();
+        const hash = envValue(stdout) as string;
         const { exitCode: hasExitCode } = await runCli(["has", hash], tmpStore);
         expect(hasExitCode).toBe(0);
       } finally {
@@ -355,7 +360,7 @@ describe("Issue #50: Schema Validation in put", () => {
         );
 
         expect(exitCode).toBe(0);
-        expect(stdout.trim()).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
       } finally {
         rmSync(tmpStore, { recursive: true, force: true });
       }
@@ -403,7 +408,7 @@ describe("Issue #50: Schema Validation in put", () => {
         );
 
         expect(exitCode).toBe(0);
-        expect(stdout.trim()).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
       } finally {
         rmSync(tmpStore, { recursive: true, force: true });
       }
@@ -423,7 +428,7 @@ describe("Issue #50: Schema Validation in put", () => {
         );
 
         expect(exitCode).toBe(0);
-        expect(stdout.trim()).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
       } finally {
         rmSync(tmpStore, { recursive: true, force: true });
       }
@@ -469,7 +474,7 @@ describe("Issue #50: Schema Validation in put", () => {
           ["has", "0000000000000"],
           tmpStore,
         );
-        expect(hasOutput.trim()).toBe("false");
+        expect(envValue(hasOutput)).toBe(false);
       } finally {
         rmSync(tmpStore, { recursive: true, force: true });
       }
@@ -692,7 +697,7 @@ describe("Issue #50: Schema Validation in put", () => {
         );
 
         expect(exitCode).toBe(0);
-        expect(stdout.trim()).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+        expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
       } finally {
         rmSync(tmpStore, { recursive: true, force: true });
       }
@@ -850,33 +855,30 @@ describe("Suite 6: CLI Integration with Templates", () => {
       // Create node
       const nodeFile = join(tmpStore, "node.json");
       writeFileSync(nodeFile, JSON.stringify({ name: "Alice" }));
-      const { stdout: nodeHash } = await runCli(
+      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: tmplHash } = await runCli(
+      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.trim(),
-        ],
+        ["var", "set", `@ucas/template/text/${schemaHash.trim()}`, tmplHash],
         tmpStore,
       );
 
       // Render with template
       const { stdout: output, exitCode } = await runCli(
-        ["render", nodeHash.trim()],
+        ["render", nodeHash],
         tmpStore,
       );
 
@@ -911,21 +913,23 @@ describe("Suite 6: CLI Integration with Templates", () => {
       // Create child node
       const childFile = join(tmpStore, "child.json");
       writeFileSync(childFile, JSON.stringify({ value: "child", child: null }));
-      const { stdout: childHash } = await runCli(
+      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.trim() }),
+        JSON.stringify({ value: "parent", child: childHash }),
       );
-      const { stdout: parentHash } = await runCli(
+      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");
@@ -933,25 +937,21 @@ describe("Suite 6: CLI Integration with Templates", () => {
         templateFile,
         JSON.stringify("{{ payload.value }}(res={{ resolution }})"),
       );
-      const { stdout: tmplHash } = await runCli(
+      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.trim(),
-        ],
+        ["var", "set", `@ucas/template/text/${schemaHash.trim()}`, tmplHash],
         tmpStore,
       );
 
       // Render with custom decay
       const { stdout: output, exitCode } = await runCli(
-        ["render", parentHash.trim(), "--decay", "0.7"],
+        ["render", parentHash, "--decay", "0.7"],
         tmpStore,
       );
 
@@ -979,10 +979,11 @@ describe("Suite 6: CLI Integration with Templates", () => {
 
       const nodeFile = join(tmpStore, "node.json");
       writeFileSync(nodeFile, JSON.stringify({ name: "Bob" }));
-      const { stdout: nodeHash } = await runCli(
+      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");
@@ -990,25 +991,21 @@ describe("Suite 6: CLI Integration with Templates", () => {
         templateFile,
         JSON.stringify("Greetings {{ payload.name }}!"),
       );
-      const { stdout: tmplHash } = await runCli(
+      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.trim(),
-        ],
+        ["var", "set", `@ucas/template/text/${schemaHash.trim()}`, tmplHash],
         tmpStore,
       );
 
       const { stdout: output, exitCode } = await runCli(
         [
           "render",
-          nodeHash.trim(),
+          nodeHash,
           "--resolution",
           "0.8",
           "--decay",
@@ -1043,14 +1040,15 @@ describe("Suite 6: CLI Integration with Templates", () => {
 
       const nodeFile = join(tmpStore, "node.json");
       writeFileSync(nodeFile, JSON.stringify({ name: "Charlie" }));
-      const { stdout: nodeHash } = await runCli(
+      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.trim()],
+        ["render", nodeHash],
         tmpStore,
       );
 
@@ -1079,13 +1077,14 @@ describe("Suite 6: CLI Integration with Templates", () => {
 
       const nodeFile = join(tmpStore, "node.json");
       writeFileSync(nodeFile, JSON.stringify({ name: "Test" }));
-      const { stdout: nodeHash } = await runCli(
+      const { stdout: nodeOut } = await runCli(
         ["put", schemaHash.trim(), nodeFile],
         tmpStore,
       );
+      const nodeHash = envValue(nodeOut) as string;
 
       const { exitCode, stderr } = await runCli(
-        ["render", nodeHash.trim(), "--decay", "1.5"],
+        ["render", nodeHash, "--decay", "1.5"],
         tmpStore,
       );
 
@@ -1126,14 +1125,15 @@ describe("Suite 6: CLI Integration with Templates", () => {
       // Create and store a simple string node
       const nodeFile = join(tmpStore, "test.json");
       writeFileSync(nodeFile, JSON.stringify("hello world"));
-      const { stdout: nodeHash } = await runCli(
+      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.trim()],
+        ["render", nodeHash],
         tmpStore,
       );
 

packages/cli-json-cas/src/e2e.test.ts

@@ -54,6 +54,11 @@ function stripVolatile(json: string): unknown {
   return strip(JSON.parse(json));
 }
 
+/** Extract the `value` field from a { type, value } envelope JSON string. */
+function envValue(json: string): unknown {
+  return (JSON.parse(json) as { value: unknown }).value;
+}
+
 // ---- Phase 1: CAS Core ----
 
 describe("Phase 1: CAS Core", () => {
@@ -88,8 +93,8 @@ describe("Phase 1: CAS Core", () => {
     writeFileSync(nodeFile, JSON.stringify({ name: "Alice", age: 30 }));
     const { stdout, exitCode } = await runCli(["put", typeHash, nodeFile]);
     expect(exitCode).toBe(0);
-    expect(stdout).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
-    nodeHash = stdout;
+    expect(envValue(stdout)).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
+    nodeHash = envValue(stdout) as string;
   });
 
   test("1.6 get returns node JSON (snapshot)", async () => {
@@ -101,19 +106,19 @@ describe("Phase 1: CAS Core", () => {
   test("1.7 has returns true for existing node", async () => {
     const { stdout, exitCode } = await runCli(["has", nodeHash]);
     expect(exitCode).toBe(0);
-    expect(stdout).toBe("true");
+    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(stdout).toBe("false");
+    expect(envValue(stdout)).toBe(false);
   });
 
   test("1.9 verify returns ok for valid node", async () => {
     const { stdout, exitCode } = await runCli(["verify", nodeHash]);
     expect(exitCode).toBe(0);
-    expect(stdout).toMatchSnapshot();
+    expect(stripVolatile(stdout)).toMatchSnapshot();
   });
 
   test("1.10 refs lists direct references (snapshot)", async () => {
@@ -132,13 +137,13 @@ describe("Phase 1: CAS Core", () => {
     const nodeFile = join(tmpStore, "test-node.json");
     const { stdout, exitCode } = await runCli(["hash", typeHash, nodeFile]);
     expect(exitCode).toBe(0);
-    expect(stdout).toBe(nodeHash);
+    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(stdout).toContain(nodeHash);
+    expect(envValue(stdout)).toContain(nodeHash);
   });
 });
 
@@ -163,7 +168,7 @@ 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(stdout).toBe("ok");
+    expect(envValue(stdout)).toBe("ok");
   });
 
   test("2.3 put against non-existent schema hash fails", async () => {
@@ -222,12 +227,13 @@ describe("Phase 3: Variable System", () => {
   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: node2Hash } = await runCli(["put", typeHash, node2File]);
+    const { stdout: node2Out } = await runCli(["put", typeHash, node2File]);
+    const node2Hash = envValue(node2Out) as string;
     const { exitCode, stdout } = await runCli([
       "var",
       "set",
       "myapp/config",
-      node2Hash.trim(),
+      node2Hash,
     ]);
     expect(exitCode).toBe(0);
     expect(stripVolatile(stdout)).toMatchSnapshot();
@@ -405,7 +411,7 @@ describe("Phase 6: GC", () => {
     const gcNodeFile = join(tmpStore, "gc-node.json");
     writeFileSync(gcNodeFile, JSON.stringify({ name: "GcAlice", age: 30 }));
     const { stdout } = await runCli(["put", typeHash, gcNodeFile]);
-    gcNodeHash = stdout.trim();
+    gcNodeHash = envValue(stdout) as string;
     // Set a var referencing this node so it survives GC during Phase 6
     await runCli(["var", "set", "gc-test/ref", gcNodeHash]);
   });
@@ -428,25 +434,21 @@ describe("Phase 6: GC", () => {
     const { exitCode } = await runCli(["gc"]);
     expect(exitCode).toBe(0);
     const { stdout } = await runCli(["has", gcNodeHash]);
-    expect(stdout).toBe("true");
+    expect(envValue(stdout)).toBe(true);
   });
 
   test("6.3 gc reclaims orphan node", async () => {
     const orphanFile = join(tmpStore, "orphan.json");
     writeFileSync(orphanFile, JSON.stringify({ name: "Orphan", age: 99 }));
-    const { stdout: orphanHashRaw } = await runCli([
-      "put",
-      typeHash,
-      orphanFile,
-    ]);
-    const orphanHash = orphanHashRaw.trim();
+    const { stdout: orphanOut } = await runCli(["put", typeHash, orphanFile]);
+    const orphanHash = envValue(orphanOut) as string;
 
     const { stdout: beforeGc } = await runCli(["has", orphanHash]);
-    expect(beforeGc).toBe("true");
+    expect(envValue(beforeGc)).toBe(true);
 
     await runCli(["gc"]);
     const { stdout: afterGc } = await runCli(["has", orphanHash]);
-    expect(afterGc).toBe("false");
+    expect(envValue(afterGc)).toBe(false);
   });
 });
 

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

@@ -22,6 +22,7 @@ import {
   validate,
   verify,
   walk,
+  wrapEnvelope,
 } from "@uncaged/json-cas";
 import { openStore as openFsStore } from "@uncaged/json-cas-fs";
 
@@ -253,7 +254,7 @@ async function cmdPut(args: string[]): Promise<void> {
   }
 
   const hash = await store.put(typeHash, payload);
-  console.log(hash);
+  out(await wrapEnvelope(store, "@output/put", hash));
 }
 
 async function cmdGet(args: string[]): Promise<void> {
@@ -262,14 +263,14 @@ async function cmdGet(args: string[]): Promise<void> {
   const store = await openStore();
   const node = store.get(hash);
   if (node === null) die(`Node not found: ${hash}`);
-  out(node);
+  out(await wrapEnvelope(store, "@output/get", node));
 }
 
 async function cmdHas(args: string[]): Promise<void> {
   const hash = args[0];
   if (!hash) die("Usage: json-cas has <hash>");
   const store = await openStore();
-  console.log(String(store.has(hash)));
+  out(await wrapEnvelope(store, "@output/has", store.has(hash)));
 }
 
 async function cmdVerify(args: string[]): Promise<void> {
@@ -279,12 +280,13 @@ async function cmdVerify(args: string[]): Promise<void> {
   const node = store.get(hash);
   if (node === null) die(`Node not found: ${hash}`);
   const ok = await verify(hash, node);
+  let status: string;
   if (!ok) {
-    console.log("corrupted");
+    status = "corrupted";
   } else {
-    const valid = validate(store, node);
-    console.log(valid ? "ok" : "invalid");
+    status = validate(store, node) ? "ok" : "invalid";
   }
+  out(await wrapEnvelope(store, "@output/verify", status));
 }
 
 async function cmdRefs(args: string[]): Promise<void> {
@@ -346,7 +348,8 @@ async function cmdHash(args: string[]): Promise<void> {
   const typeHash = await resolveTypeHash(typeHashOrAlias);
   const payload = readJsonFile(file);
   const hash = await computeHash(typeHash, payload);
-  console.log(hash);
+  const store = await openStore();
+  out(await wrapEnvelope(store, "@output/hash", hash));
 }
 
 async function cmdRender(args: string[]): Promise<void> {
@@ -826,9 +829,8 @@ async function cmdList(_args: string[]): Promise<void> {
     die("Usage: json-cas list --type <hash-or-alias>");
   const typeHash = await resolveTypeHash(typeFlag);
   const store = await openStore();
-  for (const hash of store.listByType(typeHash)) {
-    console.log(hash);
-  }
+  const hashes = Array.from(store.listByType(typeHash));
+  out(await wrapEnvelope(store, "@output/list", hashes));
 }
 
 function printUsage(): void {
@@ -836,16 +838,16 @@ function printUsage(): void {
 Usage: json-cas [--store <path>] [--json] <command> [args]
 
 Commands:
-  put <type-hash> <file.json>       Store node, print hash
-  get <hash>                        Print node as JSON
-  has <hash>                        Print true/false
-  verify <hash>                     Verify integrity + schema, print ok/corrupted/invalid
+  put <type-hash> <file.json>       Store node, print { type, value } envelope (value=hash)
+  get <hash>                        Print node as { type, value } envelope
+  has <hash>                        Print { type, value } envelope (value=boolean)
+  verify <hash>                     Verify integrity + schema → { type, value } (value=ok/corrupted/invalid)
   refs <hash>                       List direct cas_ref edges
   walk <hash> [--format tree]       Recursive traversal
-  hash <type-hash> <file.json>      Compute hash without storing (dry run)
+  hash <type-hash> <file.json>      Compute hash without storing → { type, value } envelope
   render <hash> [options]           Render node as YAML with resolution decay
   render --pipe/-p [options]        Render { type, value } from stdin
-  list --type <hash-or-alias>       List all hashes for a given type
+  list --type <hash-or-alias>       List hashes for a type → { type, value } envelope (value=string[])
   var set <name> <hash> [--tag <tag>...] Create/update a variable
   var get <name> --schema <hash>    Get a variable by name + schema
   var delete <name> [--schema <hash>] Delete variable(s)

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

@@ -65,7 +65,7 @@ describe("createFsStore – init and bootstrap", () => {
     const h2 = await bootstrap(store);
 
     expect(h1).toEqual(h2);
-    expect(store.listByType(h1["@schema"] ?? "")).toHaveLength(6);
+    expect(store.listByType(h1["@schema"] ?? "")).toHaveLength(24);
   });
 });
 

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

@@ -1,18 +1,40 @@
 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/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 built-in schema aliases to hashes", async () => {
+  test("should return map of 24 built-in schema aliases to hashes", async () => {
     const store = createMemoryStore();
     const builtinSchemas = await bootstrap(store);
 
-    // Should return object with 6 aliases
+    // Should return object with 6 primitive + 18 output aliases = 24
     expect(builtinSchemas).toHaveProperty("@schema");
     expect(builtinSchemas).toHaveProperty("@string");
     expect(builtinSchemas).toHaveProperty("@number");
@@ -20,6 +42,12 @@ describe("bootstrap - Built-in Schemas", () => {
     expect(builtinSchemas).toHaveProperty("@array");
     expect(builtinSchemas).toHaveProperty("@bool");
 
+    for (const alias of OUTPUT_ALIASES) {
+      expect(builtinSchemas).toHaveProperty(alias);
+    }
+
+    expect(Object.keys(builtinSchemas)).toHaveLength(24);
+
     // All values should be valid hashes
     for (const [_alias, hash] of Object.entries(builtinSchemas)) {
       expect(typeof hash).toBe("string");
@@ -127,3 +155,164 @@ describe("bootstrap - Built-in Schemas", () => {
     }
   });
 });
+
+// ──────────────────────────────────────────────────────────────────────────────
+// @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);
+  });
+});

packages/json-cas/src/bootstrap.ts

@@ -63,9 +63,168 @@ const BOOTSTRAP_PAYLOAD = {
   },
 } 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/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 and 5 primitive 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>> {
@@ -83,8 +242,8 @@ export async function bootstrap(store: Store): Promise<Record<string, Hash>> {
   const arrayHash = await store.put(metaHash, { type: "array" });
   const boolHash = await store.put(metaHash, { type: "boolean" });
 
-  // 3. Return map of aliases to hashes
-  return {
+  // 3. Register @output/* schemas
+  const aliases: Record<string, Hash> = {
     "@schema": metaHash,
     "@string": stringHash,
     "@number": numberHash,
@@ -92,4 +251,10 @@ export async function bootstrap(store: Store): Promise<Record<string, Hash>> {
     "@array": arrayHash,
     "@bool": boolHash,
   };
+
+  for (const [alias, schema] of OUTPUT_SCHEMAS) {
+    aliases[alias] = await store.put(metaHash, schema);
+  }
+
+  return aliases;
 }

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

@@ -264,7 +264,7 @@ describe("bootstrap", () => {
     );
   });
 
-  test("returns a map with 6 built-in schema aliases", async () => {
+  test("returns a map with 24 built-in schema aliases", async () => {
     const store = createMemoryStore();
     const builtinSchemas = await bootstrap(store);
 
@@ -280,6 +280,8 @@ describe("bootstrap", () => {
       expect(hash).toHaveLength(13);
       expect(hash).toMatch(/^[0-9A-HJKMNP-TV-Z]{13}$/);
     }
+
+    expect(Object.keys(builtinSchemas)).toHaveLength(24);
   });
 
   test("meta-schema node is stored and retrievable", async () => {
@@ -316,7 +318,7 @@ describe("bootstrap", () => {
     const h2 = await bootstrap(store);
 
     expect(h1).toEqual(h2);
-    // All 6 built-in schemas should be typed by the meta-schema
-    expect(store.listByType(h1["@schema"] ?? "")).toHaveLength(6);
+    // All 24 built-in schemas should be typed by the meta-schema
+    expect(store.listByType(h1["@schema"] ?? "")).toHaveLength(24);
   });
 });

packages/json-cas/src/index.ts

@@ -5,6 +5,7 @@ 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,
@@ -34,3 +35,4 @@ export {
   VariableStore,
 } from "./variable-store.js";
 export { verify } from "./verify.js";
+export { wrapEnvelope } from "./wrap-envelope.js";

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/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 };
+}