@mrciphersmith/keryx 0.2.34 → 0.2.35

package/dist/cli.js

@@ -34772,9 +34772,10 @@ function traceRefFor(traceId) {
 }
 
 // src/sac/index.ts
-import { readFile as readFile62, realpath as realpath3 } from "fs/promises";
+import { access as access3, readFile as readFile62, realpath as realpath3 } from "fs/promises";
 import { createHash as createHash10 } from "crypto";
 import path115 from "path";
+import { fileURLToPath as fileURLToPath6 } from "url";
 var idPattern = /^[a-z][a-z0-9-]{2,63}$/;
 var subjectPattern = /^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$/;
 var revisionPattern = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/;
@@ -34791,6 +34792,28 @@ var normativeSchemaFiles = {
   "review-decision": "review-decision.schema.json"
 };
 var normativeSchemas = new Map;
+var NORMATIVE_SCHEMA_DIR = path115.join("docs", "requirements", "shared-agent-context", "schemas");
+async function resolveSacNormativeSchemaPath(fileName, searchFrom = [fileURLToPath6(new URL(".", import.meta.url)), process.cwd()]) {
+  const seen = new Set;
+  for (const start of searchFrom) {
+    let dir = path115.resolve(start);
+    for (let i = 0;i < 10; i++) {
+      if (seen.has(dir))
+        break;
+      seen.add(dir);
+      const candidate = path115.join(dir, NORMATIVE_SCHEMA_DIR, fileName);
+      try {
+        await access3(candidate);
+        return candidate;
+      } catch {}
+      const parent = path115.dirname(dir);
+      if (parent === dir)
+        break;
+      dir = parent;
+    }
+  }
+  throw new Error(`SAC normative schema not found: ${fileName}`);
+}
 function parseStrictRfc3339Utc(value) {
   if (typeof value !== "string")
     return;
@@ -34829,7 +34852,7 @@ function isRecord2(value) {
 async function loadNormativeSchema(schema) {
   let pending = normativeSchemas.get(schema);
   if (!pending) {
-    pending = readFile62(new URL(`../../docs/requirements/shared-agent-context/schemas/${normativeSchemaFiles[schema]}`, import.meta.url), "utf8").then((source) => JSON.parse(source));
+    pending = resolveSacNormativeSchemaPath(normativeSchemaFiles[schema]).then((file) => readFile62(file, "utf8")).then((source) => JSON.parse(source));
     normativeSchemas.set(schema, pending);
   }
   return pending;
@@ -44800,7 +44823,7 @@ var AGENT_SLASH_COMMANDS = [
     modes: BOTH,
     modeDescriptions: {
       agent: "Connect to an already configured provider (interactive picker)",
-      chat: "Show how to set a provider API key in the environment"
+      chat: "Switch to a connected provider (picker when available)"
     }
   },
   {
@@ -45706,6 +45729,7 @@ function onKeypress2(r, handler) {
 }
 var COMPOSER_MIN_ROWS = 1;
 var COMPOSER_MAX_ROWS = 6;
+var COMPOSER_BORDER_ROWS = 2;
 var MENU_HEIGHT = 10;
 var SIDEBAR_WIDTH = 30;
 var SIDEBAR_BORDER_LEFT = 1;
@@ -45723,9 +45747,29 @@ ${result.installCommand.slice(split)}`);
 var SPINNER = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
 var SPINNER_MS = 120;
 var TOAST_MS = 5000;
-function composerHeightForLines(visualLines) {
+function composerHeightForLines(visualLines, maxRows = COMPOSER_MAX_ROWS) {
+  const cap = Number.isFinite(maxRows) && maxRows >= COMPOSER_MIN_ROWS ? Math.floor(maxRows) : COMPOSER_MAX_ROWS;
   const n = Number.isFinite(visualLines) ? Math.floor(visualLines) : COMPOSER_MIN_ROWS;
-  return Math.min(COMPOSER_MAX_ROWS, Math.max(COMPOSER_MIN_ROWS, n < 1 ? COMPOSER_MIN_ROWS : n));
+  return Math.min(cap, Math.max(COMPOSER_MIN_ROWS, n < 1 ? COMPOSER_MIN_ROWS : n));
+}
+function composerMaxRowsForViewport(viewportRows) {
+  if (!Number.isFinite(viewportRows) || viewportRows < 1) {
+    return COMPOSER_MAX_ROWS;
+  }
+  return Math.max(COMPOSER_MIN_ROWS, Math.floor(viewportRows / 3));
+}
+function wrappedLineCount(text, width) {
+  const inner = Number.isFinite(width) ? Math.floor(width) : 0;
+  const paragraphs = text.length === 0 ? [""] : text.split(`
+`);
+  if (inner < 1) {
+    return Math.max(COMPOSER_MIN_ROWS, paragraphs.length);
+  }
+  let total = 0;
+  for (const paragraph of paragraphs) {
+    total += Math.max(1, Math.ceil(Math.max(paragraph.length, 1) / inner));
+  }
+  return total;
 }
 function prefixFilter(commands, query) {
   const q = query.trim().toLowerCase();
@@ -45903,6 +45947,9 @@ async function createShellChrome(otui, renderer, opts) {
   const composer = new otui.BoxRenderable(r, {
     id: "composer",
     flexShrink: 0,
+    minWidth: 0,
+    width: "100%",
+    flexDirection: "column",
     borderStyle: "rounded",
     border: true,
     paddingLeft: 1,
@@ -45912,10 +45959,12 @@ async function createShellChrome(otui, renderer, opts) {
     id: "prompt",
     placeholder: opts.placeholder,
     wrapMode: "word",
+    minWidth: 0,
+    width: "100%",
     minHeight: COMPOSER_MIN_ROWS,
-    maxHeight: COMPOSER_MAX_ROWS,
     height: COMPOSER_MIN_ROWS,
-    width: "100%",
+    flexShrink: 0,
+    overflow: "scroll",
     keyBindings: [
       { name: "return", action: "submit" },
       { name: "kpenter", action: "submit" },
@@ -45929,17 +45978,28 @@ async function createShellChrome(otui, renderer, opts) {
   });
   composer.add(textarea);
   main.add(composer);
+  const viewportRows = () => {
+    const h = r.height;
+    return typeof h === "number" && h > 0 ? h : COMPOSER_MAX_ROWS * 3;
+  };
   const syncComposerHeight = () => {
+    const cap = composerMaxRowsForViewport(viewportRows());
     let lines = 1;
     try {
-      lines = Math.max(textarea.virtualLineCount || 0, textarea.lineCount || 0, 1);
+      const wrapWidth = typeof textarea.width === "number" && textarea.width > 0 ? textarea.width : 0;
+      lines = Math.max(textarea.virtualLineCount || 0, textarea.lineCount || 0, wrappedLineCount(textarea.plainText, wrapWidth), 1);
     } catch {
-      lines = Math.max(1, (textarea.plainText.match(/\n/g)?.length ?? 0) + 1);
+      lines = wrappedLineCount(textarea.plainText, 0);
     }
-    const h = composerHeightForLines(lines);
+    const h = composerHeightForLines(lines, cap);
     if (textarea.height !== h) {
       textarea.height = h;
     }
+    const boxH = h + COMPOSER_BORDER_ROWS;
+    if (composer.height !== boxH) {
+      composer.height = boxH;
+    }
+    textarea.maxHeight = cap;
   };
   const input2 = {
     get value() {
@@ -46067,6 +46127,10 @@ async function createShellChrome(otui, renderer, opts) {
     syncComposerHeight();
     refilter();
   };
+  const onComposerResized = () => {
+    syncComposerHeight();
+  };
+  textarea.on(otui.LayoutEvents.RESIZED, onComposerResized);
   textarea.focus();
   syncComposerHeight();
   const submitHandlers = new Set;
@@ -46167,6 +46231,9 @@ async function createShellChrome(otui, renderer, opts) {
       clearBusyTimer();
       clearToastTimer();
       unsubscribeMenuKeys();
+      try {
+        textarea.off(otui.LayoutEvents.RESIZED, onComposerResized);
+      } catch {}
       try {
         r.off(otui.CliRenderEvents.SELECTION, onSelection);
       } catch {}
@@ -47266,12 +47333,8 @@ async function filterConnectedDetectedProviders(detected, options = {}) {
     }
     const requiresApiKey = registry.requiresApiKey ?? true;
     const envKey = prov.envKey ?? registry.envKey;
-    if (!requiresApiKey || envKey === undefined) {
-      connected.push(prov);
-      continue;
-    }
-    const raw = env[envKey];
-    if (raw === undefined || raw.length === 0) {
+    const raw = envKey !== undefined ? env[envKey] : undefined;
+    if (requiresApiKey && (raw === undefined || raw.length === 0)) {
       continue;
     }
     const compat = {
@@ -47280,13 +47343,13 @@ async function filterConnectedDetectedProviders(detected, options = {}) {
       ...prov.chatPath !== undefined ? { chatPath: prov.chatPath } : {},
       ...prov.modelsPath !== undefined ? { modelsPath: prov.modelsPath } : {}
     };
-    const result = await fetchOpenAiCompatModelsDetailed(fetchFn, compat, raw, {
+    const result = await fetchOpenAiCompatModelsDetailed(fetchFn, compat, raw ?? "", {
       timeoutMs: MODELS_FETCH_TIMEOUT_MS
     });
     if (result.source !== "live" || result.models.length === 0) {
       continue;
     }
-    connected.push(prov);
+    connected.push({ ...prov, models: result.models });
   }
   return connected;
 }
@@ -47693,11 +47756,11 @@ function selectProviderModelInTui(otui, r, detected, options = {}) {
           resolve3(undefined);
           return;
         }
-        const selectedBaseUrl = prov.baseUrl !== undefined ? await promptBaseUrlStep(otui, r, prov.label ?? prov.name, prov.baseUrl) : prov.baseUrl;
-        if (prov.baseUrl !== undefined && selectedBaseUrl === undefined) {
+        const selectedBaseUrl = options.onlyConnected || prov.baseUrl === undefined ? prov.baseUrl : await promptBaseUrlStep(otui, r, prov.label ?? prov.name, prov.baseUrl);
+        if (!options.onlyConnected && prov.baseUrl !== undefined && selectedBaseUrl === undefined) {
           continue;
         }
-        if (selectedBaseUrl !== undefined)
+        if (!options.onlyConnected && selectedBaseUrl !== undefined)
           saveProviderBaseUrl(prov.name, selectedBaseUrl);
         const selectedProvider = selectedBaseUrl === undefined ? prov : { ...prov, baseUrl: selectedBaseUrl };
         const envKey = prov.envKey;
@@ -49315,6 +49378,12 @@ async function launchTuiChatShell(opts) {
       runShell: opts.runShell,
       pickSelection: async (pickOpts) => {
         const detected = opts.redetect !== undefined ? await opts.redetect() : opts.detected;
+        if (pickOpts?.onlyConnected === true) {
+          return await selectProviderModelInTui(otui, r, detected, {
+            onlyConnected: true,
+            env: process.env
+          });
+        }
         const only = pickOpts?.onlyProvider;
         if (only === undefined) {
           return await selectProviderModelInTui(otui, r, detected);
@@ -49347,7 +49416,7 @@ init_shell_config();
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.34",
+  version: "0.2.35",
   description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {
@@ -49392,6 +49461,7 @@ var package_default = {
   },
   files: [
     "dist",
+    "docs/requirements/shared-agent-context/schemas",
     "src/gdgraph",
     "src/gdskills/bundled",
     "src/gdskills/contracts",
@@ -49407,12 +49477,17 @@ var package_default = {
   },
   devDependencies: {
     "@types/bun": "latest",
+    "@xenova/transformers": "^2.17.2",
     "bun-types": "latest",
     typescript: "^5"
   },
   engines: {
     bun: ">=1.1.0"
-  }
+  },
+  trustedDependencies: [
+    "protobufjs",
+    "sharp"
+  ]
 };
 
 // src/commands/select.ts
@@ -49809,7 +49884,12 @@ Starting a new session.
         continue;
       }
       if (command === "/connect") {
-        system(CONNECT_GUIDANCE);
+        if (deps.selectProviderModel === undefined) {
+          system(CONNECT_GUIDANCE);
+          continue;
+        }
+        const picked = await deps.selectProviderModel(io, { onlyConnected: true });
+        applySelection(picked);
         continue;
       }
       const wrongMode = describeUnavailableCommand(command, "chat");
@@ -53020,9 +53100,9 @@ function printHelp17() {
 // src/commands/update.ts
 import { spawn as spawn5 } from "child_process";
 import { chmod as chmod4, mkdir as mkdir52, readFile as readFile75, readdir as readdir22, writeFile as writeFile47 } from "fs/promises";
-import { access as access3, constants as constants2, existsSync as existsSync29 } from "fs";
+import { access as access4, constants as constants2, existsSync as existsSync29 } from "fs";
 import path141 from "path";
-import { fileURLToPath as fileURLToPath6 } from "url";
+import { fileURLToPath as fileURLToPath7 } from "url";
 init_config();
 init_config2();
 init_templates2();
@@ -54118,7 +54198,7 @@ async function runPostUpdateHooks(projectRoot) {
 }
 async function accessExecutable(filePath) {
   await new Promise((resolve3, reject) => {
-    access3(filePath, constants2.X_OK, (error2) => {
+    access4(filePath, constants2.X_OK, (error2) => {
       if (error2) {
         reject(error2);
         return;
@@ -54166,12 +54246,12 @@ async function copyFileIfChanged2(from, to) {
   await writeFile47(to, next, "utf8");
 }
 function runtimeSourcePath2(relativePath) {
-  const directPath = fileURLToPath6(new URL(relativePath, import.meta.url));
+  const directPath = fileURLToPath7(new URL(relativePath, import.meta.url));
   if (existsSync29(directPath)) {
     return directPath;
   }
   if (relativePath.startsWith("../")) {
-    const packagedSourcePath = path141.join(path141.dirname(fileURLToPath6(import.meta.url)), "..", "src", relativePath.slice(3));
+    const packagedSourcePath = path141.join(path141.dirname(fileURLToPath7(import.meta.url)), "..", "src", relativePath.slice(3));
     if (existsSync29(packagedSourcePath)) {
       return packagedSourcePath;
     }
@@ -56564,6 +56644,53 @@ async function versionCommand(args2, deps = {}) {
 init_args();
 import { randomUUID as randomUUID21 } from "crypto";
 import { writeFile as writeFile50 } from "fs/promises";
+
+// src/sac/fwk-explain.ts
+function isOverflow(result) {
+  return "code" in result;
+}
+function formatFwkExplain(result) {
+  if (isOverflow(result)) {
+    return [`SAC explain: context_overflow (${result.code})`, "No successful manifest/receipt. Shrink the scope or raise the budget."].join(`
+`);
+  }
+  const facts = Array.isArray(result.manifest.facts) ? result.manifest.facts : [];
+  const knowHow = Array.isArray(result.manifest.knowHow) ? result.manifest.knowHow : [];
+  const work = result.manifest.work;
+  const byKind = { wiki: 0, memory: 0, skill: 0, other: 0 };
+  const knowHowLines = knowHow.map((item) => {
+    const row = item;
+    const kind = row.kind === "wiki" || row.kind === "memory" || row.kind === "skill" ? row.kind : "other";
+    byKind[kind] += 1;
+    return `    - ${kind} ${row.uri ?? "?"}  revision=${row.revision ?? "?"}  status=${row.status ?? "?"}`;
+  });
+  const workState = work?.state ?? "unbound";
+  const lines = [
+    "SAC explain (FWK \u2014 Facts / Work / Know-how)",
+    `  freshness: ${result.manifest.freshness}`,
+    `  receipt: ${result.receipt.id}  decision=${result.receipt.decision}`,
+    `  Facts (${facts.length}) \u2014 evidence-linked, task-local; not durable knowledge`,
+    ...facts.map((fact) => {
+      const row = fact;
+      const ev = row.evidence?.[0];
+      return `    - ${row.statement ?? "(no statement)"}  uri=${ev?.uri ?? "?"}  revision=${ev?.revision ?? "?"}  freshness=${row.freshness ?? "?"}`;
+    }),
+    `  Work (${workState}) \u2014 Flow projection only; SAC does not write flow.json`,
+    ...workState === "bound" ? [
+      `    - flow=${work?.flowRef?.uri ?? "?"}  snapshot=${work?.flowRef?.snapshot ?? "?"}  revision=${work?.flowRef?.revision ?? "?"}`,
+      `    - completed=${(work?.completed ?? []).join(",") || "(none)"}  next=${(work?.next ?? []).join(",") || "(none)"}  blocked=${(work?.blocked ?? []).join(",") || "(none)"}`
+    ] : ["    - no flow resource bound on this workspace"],
+    `  Know-how (${knowHow.length}: wiki=${byKind.wiki} memory=${byKind.memory} skill=${byKind.skill}) \u2014 references to owning stores, not SAC copies`,
+    ...knowHowLines.length > 0 ? knowHowLines : ["    - (none accepted/visible in this budget)"],
+    "  Not written here: graph nodes/edges (navigation only), session transcripts, hidden reasoning."
+  ];
+  if (result.partial)
+    lines.push(`  partial: omitted optional ${result.omittedOptional.join(", ") || "(none)"}`);
+  return lines.join(`
+`);
+}
+
+// src/commands/workspace.ts
 var PROPOSAL_KINDS = ["decision", "wiki-update", "memory-entry", "follow-up", "contract-change", "risk"];
 function service4() {
   return new WorkspaceService({
@@ -56612,30 +56739,36 @@ async function workspaceCommand(args2) {
       return;
     }
     if (subcommand === "overview") {
-      rejectUnknownOptions(args2.slice(2), new Set(["--max-items", "--max-tokens"]));
+      rejectUnknownOptions(args2.slice(2), new Set(["--max-items", "--max-tokens", "--explain"]));
       const workspaceId = args2[1];
       if (!workspaceId)
-        throw new Error("Usage: keryx workspace overview <workspace-id> [--max-items N] [--max-tokens N]");
+        throw new Error("Usage: keryx workspace overview <workspace-id> [--max-items N] [--max-tokens N] [--explain]");
       const maxItems = Number(optionValue(args2, "--max-items") ?? "32");
       const maxTokens = Number(optionValue(args2, "--max-tokens") ?? "4096");
       if (!Number.isInteger(maxItems) || !Number.isInteger(maxTokens) || maxItems < 0 || maxTokens < 0)
         throw new Error("--max-items and --max-tokens must be non-negative integers");
       const result = await createLocalFwkReadService(process.cwd()).overview({ workspaceId, request: undefined, requestCorrelationId: randomUUID21(), budget: { maxItems, maxTokens } });
-      console.log(JSON.stringify(normalizeFwkResult(result), null, 2));
+      const normalized = normalizeFwkResult(result);
+      console.log(JSON.stringify(normalized, null, 2));
+      if (args2.includes("--explain"))
+        console.error(formatFwkExplain(normalized));
       return;
     }
     if (subcommand === "read") {
-      rejectUnknownOptions(args2.slice(3), new Set(["--max-items", "--max-tokens"]));
+      rejectUnknownOptions(args2.slice(3), new Set(["--max-items", "--max-tokens", "--explain"]));
       const workspaceId = args2[1];
       const itemId = args2[2];
       if (!workspaceId || !itemId)
-        throw new Error("Usage: keryx workspace read <workspace-id> <item-id> [--max-items N] [--max-tokens N]");
+        throw new Error("Usage: keryx workspace read <workspace-id> <item-id> [--max-items N] [--max-tokens N] [--explain]");
       const maxItems = Number(optionValue(args2, "--max-items") ?? "1");
       const maxTokens = Number(optionValue(args2, "--max-tokens") ?? "4096");
       if (!Number.isInteger(maxItems) || !Number.isInteger(maxTokens) || maxItems < 0 || maxTokens < 0)
         throw new Error("--max-items and --max-tokens must be non-negative integers");
       const result = await createLocalFwkReadService(process.cwd()).read({ workspaceId, itemId, request: undefined, requestCorrelationId: randomUUID21(), budget: { maxItems, maxTokens } });
-      console.log(JSON.stringify(normalizeFwkResult(result), null, 2));
+      const normalized = normalizeFwkResult(result);
+      console.log(JSON.stringify(normalized, null, 2));
+      if (args2.includes("--explain"))
+        console.error(formatFwkExplain(normalized));
       return;
     }
     if (subcommand === "propose") {
@@ -56714,8 +56847,8 @@ function printHelp20() {
 keryx workspace list
 keryx workspace show <workspace-id>
 keryx workspace add-resource <workspace-id> --kind <kind> --uri <workspace-relative-ref> [--revision <revision>]
-keryx workspace overview <workspace-id> [--max-items N] [--max-tokens N]
-keryx workspace read <workspace-id> <item-id> [--max-items N] [--max-tokens N]
+keryx workspace overview <workspace-id> [--max-items N] [--max-tokens N] [--explain]
+keryx workspace read <workspace-id> <item-id> [--max-items N] [--max-tokens N] [--explain]
 keryx workspace propose <workspace-id> --kind <` + PROPOSAL_KINDS.join("|") + `> --session <session-id> [--note <one-line note>]
 keryx workspace review <workspace-id> <proposal-id> --decision <accepted|rejected|dismissed> [--reason <reason>] [--idempotency-key <key>]
 keryx workspace collaboration <workspace-id>

package/docs/requirements/shared-agent-context/schemas/README.md

@@ -0,0 +1,65 @@
+# Shared Agent Context — Schemas and Fixtures
+Version: 1.4.0
+
+## Purpose
+
+These are the normative data contracts used by the implemented SAC phases.
+They use JSON Schema Draft 2020-12. Fixtures define the minimum validator and
+integration-test corpus. The
+implementation must enable format assertion and run the semantic validator for
+the declared `x-` invariants: canonical SubjectId topology, realpath/root
+containment, timestamp ordering and ledger-level idempotency.
+
+## Schemas
+
+- [Workspace manifest](workspace-manifest.schema.json)
+- [FWK receipt](fwk-receipt.schema.json)
+- [Access receipt](access-receipt.schema.json)
+- [Workspace proposal](workspace-proposal.schema.json)
+- [Review decision](review-decision.schema.json)
+
+## Fixtures
+
+- [Valid workspace](fixtures/valid-workspace.json)
+- [Invalid workspace](fixtures/invalid-workspace.json)
+- [Valid FWK receipt](fixtures/valid-fwk-receipt.json)
+- [Invalid evidence without revision](fixtures/invalid-evidence-missing-revision.json)
+- [Invalid bound Work without Flow reference](fixtures/invalid-bound-work-no-flow-ref.json)
+- [Valid proposal](fixtures/valid-proposal.json)
+- [Invalid proposal](fixtures/invalid-proposal.json)
+- [Valid accepted transition](fixtures/valid-accepted-transition.json)
+- [Accepted transition with failed security gate](fixtures/invalid-accepted-transition-failed-gate.json)
+- [Accepted transition without target write](fixtures/invalid-accepted-transition-no-target-write.json)
+- [Valid review decision](fixtures/valid-review-decision.json)
+- [Valid access receipt](fixtures/valid-access-receipt.json)
+- [Invalid duplicate roles](fixtures/invalid-duplicate-roles.json)
+- [Invalid unsafe URI](fixtures/invalid-unsafe-uri.json)
+- [Invalid timestamp order](fixtures/invalid-time-order.json)
+- [Invalid stale evidence](fixtures/invalid-stale-evidence.json)
+- [Spoofed viewer mutation](fixtures/invalid-spoofed-viewer-mutation.json)
+- [Denied resource egress](fixtures/invalid-resource-egress.json)
+- [Replay/idempotency corpus](fixtures/replay-idempotency-corpus.json)
+
+Positive fixtures must validate against their named schema. Negative fixtures
+must fail for the documented contract reason. The replay corpus is evaluated by
+the append-only ledger validator, not by an isolated JSON document. All schemas
+forbid raw transcript, prompt, hidden-reasoning and secret payload fields by
+using closed objects.
+
+Phase 5 publishes its minimized learning/evaluation fixtures separately under
+[`fixtures/sac-policy-experiment`](../../../../fixtures/sac-policy-experiment/).
+The manifest is a closed TypeScript/runtime contract rather than an extension
+of AccessReceipt: it records receipt-chain provenance, independent verifier
+artifact hashes, selection/redaction/quarantine rules and deterministic
+train/holdout/adversarial splits. Receipt self-report is never ground truth.
+
+`workspace-proposal` creation also requires minimal `wrapUp` metadata. It is
+only an audit pointer: runtime authorization requires the corresponding
+server-issued, one-time trusted provenance capability bound to its session or
+read-only Flow wrap-up source, actor, workspace, evidence and expiry.
+
+For an accepted transition, `acceptance.targetWrite.binding` is normative and
+retains the exact immutable owner receipt binding. It must repeat the proposal,
+workspace, correlation/idempotency, reviewer-authority and policy-revision
+values of that transition; implementations must not reduce it to a hash after
+verification.

package/docs/requirements/shared-agent-context/schemas/access-receipt.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/access-receipt/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "workspaceId", "actor", "action", "decision", "recordedAt", "cost", "contextAssembly", "policy", "integrity"],
+  "properties": {
+    "schemaVersion": {"const": "1.0"}, "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"}, "workspaceId": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"}, "actor": {"type": "string", "pattern": "^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"}, "action": {"enum": ["overview", "fwk", "resource"]}, "decision": {"enum": ["allowed", "denied", "budget-exhausted", "stale"]}, "recordedAt": {"$ref": "#/$defs/utcTimestamp"}, "cost": {"type": "object", "additionalProperties": false, "required": ["toolCalls", "elapsedMs"], "properties": {"tokens": {"type": "integer", "minimum": 0}, "toolCalls": {"type": "integer", "minimum": 0}, "elapsedMs": {"type": "integer", "minimum": 0}}}, "contextAssembly": {"type": "object", "additionalProperties": false, "required": ["traceRef", "configurationRevision", "selected", "omittedOptional"], "properties": {"traceRef": {"$ref": "#/$defs/workspacePath"}, "configurationRevision": {"$ref": "#/$defs/revision"}, "selected": {"type": "array", "items": {"$ref": "#/$defs/workspacePath"}}, "omittedOptional": {"type": "array", "items": {"$ref": "#/$defs/workspacePath"}}}}, "policy": {"type": "object", "additionalProperties": false, "required": ["ref", "revision"], "properties": {"ref": {"$ref": "#/$defs/workspacePath"}, "revision": {"$ref": "#/$defs/revision"}}}, "integrity": {"type": "object", "additionalProperties": false, "required": ["recordHash", "previousRecordHash"], "properties": {"recordHash": {"type": "string", "pattern": "^[a-f0-9]{64}$"}, "previousRecordHash": {"type": "string", "pattern": "^(?:[a-f0-9]{64}|GENESIS)$"}}}, "resourceRef": {"$ref": "#/$defs/workspacePath"}, "outcome": {"enum": ["unknown", "useful", "not-useful"]}},
+  "allOf": [{"if": {"properties": {"action": {"const": "resource"}}, "required": ["action"]}, "then": {"required": ["resourceRef"]}, "else": {"not": {"required": ["resourceRef"]}}}],
+  "x-rootContainment": {"fields": ["resourceRef", "contextAssembly.traceRef", "contextAssembly.selected[]", "contextAssembly.omittedOptional[]", "policy.ref"], "root": "workspace root", "resolveSymlinks": true, "rejectEscapes": true}, "x-integrity": {"appendOnlyLedger": true, "verifyRecordHash": true, "owner": "trusted local service"},
+  "$defs": {"utcTimestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$", "x-formatAssertionRequired": true}, "revision": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$", "x-immutable": true}, "workspacePath": {"type": "string", "pattern": "^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$"}}
+}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-accepted-transition-failed-gate.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":1,"priorEventHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:10:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-1","writeIntentRef":"./proposals/proposal-1.intent-1","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"fail","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-accepted-transition-no-target-write.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":1,"priorEventHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:10:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-1","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-bound-work-no-flow-ref.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","workspaceId":"payments-work","generatedAt":"2026-08-11T00:00:00Z","facts":[],"work":{"state":"bound","completed":["task-1"]},"knowHow":[],"freshness":"fresh"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-duplicate-roles.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"},{"subject":"team:payments","role":"editor"}],"resources":[],"createdAt":"2026-08-11T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-evidence-missing-revision.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","workspaceId":"payments-work","generatedAt":"2026-08-11T00:00:00Z","facts":[{"statement":"Flow is ready","evidence":[{"kind":"flow","uri":"./.metaproject/flows/001","observedAt":"2026-08-11T00:00:00Z","trust":"primary"}],"observedAt":"2026-08-11T00:00:00Z","expiresAt":"2026-08-12T00:00:00Z","freshness":"fresh"}],"work":{"state":"unbound"},"knowHow":[],"freshness":"fresh"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-proposal.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-created","id":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","kind":"memory-entry","status":"accepted","summary":"redacted summary","evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"author":"agent:writer","security":{"gate":"pass","redacted":true,"policyRef":"./policies/default","policyRevision":"1"},"createdAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-resource-egress.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"access-1","workspaceId":"payments-work","actor":"agent:release-bot","action":"resource","decision":"allowed","recordedAt":"2026-08-11T00:05:00Z","cost":{"toolCalls":1,"elapsedMs":12},"contextAssembly":{"traceRef":"./context/trace-1","configurationRevision":"1","selected":["./src/payments"],"omittedOptional":[]},"policy":{"ref":"./policies/default","revision":"1"},"integrity":{"recordHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previousRecordHash":"GENESIS"},"resourceRef":"https://outside.invalid/resource"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-spoofed-viewer-mutation.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"decision-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","decision":"accepted","reviewer":{"subject":"user:viewer","authority":"viewer","trustedPrincipalRef":"./identity/principal-1"},"decidedAt":"2026-08-11T00:05:00Z","idempotencyKey":"review-decision-0001","security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","evidenceRevision":"1"},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-stale-evidence.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"decision-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","decision":"accepted","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"decidedAt":"2026-08-11T00:05:00Z","idempotencyKey":"review-decision-0001","security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"stale","verifiedAt":"2026-08-11T00:05:00Z","evidenceRevision":"1"},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-time-order.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"}],"resources":[],"createdAt":"2026-08-12T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-unsafe-uri.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"}],"resources":[{"kind":"component","uri":"https://outside.invalid/resource"}],"createdAt":"2026-08-11T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/invalid-workspace.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"}],"resources":[{"kind":"component","uri":"src/no-prefix"}],"createdAt":"2026-08-11T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/replay-idempotency-corpus.json

@@ -0,0 +1 @@
+{"x-fixturePurpose":"integration negative corpus for x-appendOnly and x-idempotencyScope; each event is individually schema-valid but the pair must be rejected by the ledger validator as a replay","events":[{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":1,"priorEventHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:10:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-1","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}},{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-2","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":2,"priorEventHash":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:11:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-2","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"targetWrite":{"receiptRef":"./writes/receipt-2","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}}]}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-accepted-transition.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-transition","eventId":"event-accepted-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","sequence":1,"priorEventHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","fromStatus":"proposed","toStatus":"accepted","occurredAt":"2026-08-11T00:10:00Z","idempotencyKey":"accepted-transition-0001","acceptance":{"reviewDecisionRef":"./reviews/decision-1","writeIntentRef":"./proposals/proposal-1.intent-1","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","maxEvidenceAgeSeconds":3600},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z","binding":{"owner":"memory","bindingHash":"a62eb99d2270853152d5bc625268f384905b8c558ad704e8e77f2d601c60f66f","intentRef":"./proposals/proposal-1.intent-1","proposalId":"proposal-1","proposalRevision":"1","workspaceId":"payments-work","correlationId":"proposal-correlation-0001","idempotencyKey":"accepted-transition-0001","reviewerSubject":"user:reviewer","reviewerAuthority":"owner","policyRevision":"1"}},"evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"idempotencyKey":"accepted-transition-0001"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-access-receipt.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"access-1","workspaceId":"payments-work","actor":"agent:release-bot","action":"resource","decision":"allowed","recordedAt":"2026-08-11T00:05:00Z","cost":{"toolCalls":1,"elapsedMs":12},"contextAssembly":{"traceRef":"./context/trace-1","configurationRevision":"1","selected":["./src/payments"],"omittedOptional":[]},"policy":{"ref":"./policies/default","revision":"1"},"integrity":{"recordHash":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","previousRecordHash":"GENESIS"},"resourceRef":"./src/payments"}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-fwk-receipt.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","workspaceId":"payments-work","generatedAt":"2026-08-11T00:00:00Z","facts":[{"statement":"Flow is ready","evidence":[{"kind":"flow","uri":"./.metaproject/flows/001","revision":"1","observedAt":"2026-08-11T00:00:00Z","trust":"primary"}],"observedAt":"2026-08-11T00:00:00Z","expiresAt":"2026-08-12T00:00:00Z","freshness":"fresh"}],"work":{"state":"unbound"},"knowHow":[{"kind":"memory","uri":"./.metaproject/memory/constraint","revision":"2","trust":"accepted","status":"fresh"}],"freshness":"fresh"}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-proposal.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","recordType":"proposal-created","id":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","kind":"memory-entry","status":"proposed","summary":"Redacted reusable constraint","evidence":[{"kind":"memory","uri":"./memory/constraint","revision":"1","observedAt":"2026-08-11T00:00:00Z"}],"wrapUp":{"id":"wrapup-1","source":"flow","sourceRef":"./flows/payments-wrapup","sourceRevision":"1","issuedAt":"2026-08-11T00:00:00Z","expiresAt":"2026-08-11T01:00:00Z"},"author":"agent:writer","security":{"gate":"pass","redacted":true,"policyRef":"./policies/default","policyRevision":"1"},"createdAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-review-decision.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"decision-1","proposalId":"proposal-1","proposalRevision":"1","correlationId":"proposal-correlation-0001","workspaceId":"payments-work","decision":"accepted","reviewer":{"subject":"user:reviewer","authority":"owner","trustedPrincipalRef":"./identity/principal-1"},"decidedAt":"2026-08-11T00:05:00Z","idempotencyKey":"review-decision-0001","security":{"gate":"pass","policyRef":"./policies/default","policyRevision":"1"},"freshness":{"state":"fresh","verifiedAt":"2026-08-11T00:05:00Z","evidenceRevision":"1"},"targetWrite":{"receiptRef":"./writes/receipt-1","targetRef":"./memory/constraint","completedAt":"2026-08-11T00:06:00Z"}}

package/docs/requirements/shared-agent-context/schemas/fixtures/valid-workspace.json

@@ -0,0 +1 @@
+{"schemaVersion":"1.0","id":"payments-work","title":"Payments work","status":"active","members":[{"subject":"team:payments","role":"owner"},{"subject":"agent:release-bot","role":"editor"}],"resources":[{"kind":"component","uri":"./src/payments","revision":"abc123"}],"createdAt":"2026-08-11T00:00:00Z","updatedAt":"2026-08-11T00:00:00Z"}

package/docs/requirements/shared-agent-context/schemas/fwk-receipt.schema.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/fwk-receipt/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "workspaceId", "generatedAt", "facts", "work", "knowHow", "freshness"],
+  "properties": {
+    "schemaVersion": {"const": "1.0"},
+    "workspaceId": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"},
+    "generatedAt": {"$ref": "#/$defs/utcTimestamp"},
+    "facts": {"type": "array", "items": {"$ref": "#/$defs/fact"}},
+    "work": {"$ref": "#/$defs/work"},
+    "knowHow": {"type": "array", "items": {"$ref": "#/$defs/knowHow"}},
+    "freshness": {"enum": ["fresh", "stale", "partial", "denied"]}
+  },
+  "x-temporalOrder": [{"earlier": "facts[].observedAt", "laterOrEqual": "facts[].expiresAt"}, {"earlier": "facts[].observedAt", "laterOrEqual": "generatedAt"}],
+  "$defs": {
+    "utcTimestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$", "x-formatAssertionRequired": true},
+    "immutableRevision": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$", "x-immutable": true},
+    "workspacePath": {"type": "string", "pattern": "^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$", "x-rootContainment": "workspace root realpath"},
+    "evidence": {"type": "object", "additionalProperties": false, "required": ["kind", "uri", "revision", "observedAt", "trust"], "properties": {"kind": {"enum": ["code", "flow", "wiki", "memory", "test", "health", "artifact"]}, "uri": {"$ref": "#/$defs/workspacePath"}, "revision": {"$ref": "#/$defs/immutableRevision"}, "observedAt": {"$ref": "#/$defs/utcTimestamp"}, "trust": {"enum": ["primary", "accepted", "reviewed"]}}},
+    "fact": {"type": "object", "additionalProperties": false, "required": ["statement", "evidence", "observedAt", "expiresAt", "freshness"], "properties": {"statement": {"type": "string", "minLength": 1, "maxLength": 4000}, "evidence": {"type": "array", "minItems": 1, "items": {"$ref": "#/$defs/evidence"}}, "observedAt": {"$ref": "#/$defs/utcTimestamp"}, "expiresAt": {"$ref": "#/$defs/utcTimestamp"}, "freshness": {"enum": ["fresh", "stale", "expired", "denied"]}, "confidence": {"type": "number", "minimum": 0, "maximum": 1}}},
+    "flowRef": {"type": "object", "additionalProperties": false, "required": ["uri", "snapshot", "revision"], "properties": {"uri": {"$ref": "#/$defs/workspacePath"}, "snapshot": {"type": "string", "minLength": 1, "maxLength": 256}, "revision": {"$ref": "#/$defs/immutableRevision"}}},
+    "work": {"oneOf": [{"type": "object", "additionalProperties": false, "required": ["state", "flowRef"], "properties": {"state": {"const": "bound"}, "flowRef": {"$ref": "#/$defs/flowRef"}, "completed": {"type": "array", "items": {"type": "string"}}, "next": {"type": "array", "items": {"type": "string"}}, "blocked": {"type": "array", "items": {"type": "string"}}, "evidence": {"type": "array", "items": {"$ref": "#/$defs/evidence"}}}}, {"type": "object", "additionalProperties": false, "required": ["state"], "properties": {"state": {"const": "unbound"}}, "x-forbids": ["flowRef", "completed", "next", "blocked", "evidence"]}]},
+    "knowHow": {"type": "object", "additionalProperties": false, "required": ["kind", "uri", "revision", "trust", "status"], "properties": {"kind": {"enum": ["wiki", "memory", "skill"]}, "uri": {"$ref": "#/$defs/workspacePath"}, "revision": {"$ref": "#/$defs/immutableRevision"}, "trust": {"enum": ["accepted", "reviewed"]}, "status": {"enum": ["fresh", "stale", "withdrawn", "denied"]}, "applicability": {"type": "string", "maxLength": 1000}}}
+  }
+}

package/docs/requirements/shared-agent-context/schemas/review-decision.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/review-decision/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "proposalId", "proposalRevision", "correlationId", "workspaceId", "decision", "reviewer", "decidedAt", "idempotencyKey"],
+  "properties": {
+    "schemaVersion": {"const": "1.0"}, "id": {"$ref": "#/$defs/id"}, "proposalId": {"$ref": "#/$defs/id"}, "proposalRevision": {"$ref": "#/$defs/revision"}, "correlationId": {"$ref": "#/$defs/correlationId"}, "workspaceId": {"$ref": "#/$defs/id"}, "decision": {"enum": ["accepted", "rejected", "dismissed"]}, "reviewer": {"$ref": "#/$defs/actorContext"}, "decidedAt": {"$ref": "#/$defs/utcTimestamp"}, "idempotencyKey": {"$ref": "#/$defs/idempotencyKey"}, "security": {"$ref": "#/$defs/security"}, "freshness": {"$ref": "#/$defs/freshness"}, "targetWrite": {"$ref": "#/$defs/targetWrite"}, "reason": {"type": "string", "minLength": 1, "maxLength": 2000}
+  },
+  "allOf": [{"if": {"properties": {"decision": {"const": "accepted"}}, "required": ["decision"]}, "then": {"required": ["security", "freshness", "targetWrite"]}, "else": {"required": ["reason"], "not": {"anyOf": [{"required": ["targetWrite"]}, {"required": ["freshness"]}]}}}],
+  "x-appendOnly": {"stream": "proposalId", "idempotencyScope": "workspaceId+proposalId", "authoritativeTransition": true},
+  "$defs": {
+    "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"}, "revision": {"type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$", "x-immutable": true}, "correlationId": {"type": "string", "minLength": 16, "maxLength": 256, "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$", "x-immutable": true}, "utcTimestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$", "x-formatAssertionRequired": true}, "workspacePath": {"type": "string", "pattern": "^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$", "x-rootContainment": "workspace root realpath"}, "idempotencyKey": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$"},
+    "actorContext": {"type": "object", "additionalProperties": false, "required": ["subject", "authority", "trustedPrincipalRef"], "properties": {"subject": {"type": "string", "pattern": "^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"}, "authority": {"enum": ["owner", "editor"]}, "trustedPrincipalRef": {"$ref": "#/$defs/workspacePath"}}},
+    "security": {"type": "object", "additionalProperties": false, "required": ["gate", "policyRef", "policyRevision"], "properties": {"gate": {"const": "pass"}, "policyRef": {"$ref": "#/$defs/workspacePath"}, "policyRevision": {"$ref": "#/$defs/revision"}}}, "freshness": {"type": "object", "additionalProperties": false, "required": ["state", "verifiedAt", "evidenceRevision"], "properties": {"state": {"const": "fresh"}, "verifiedAt": {"$ref": "#/$defs/utcTimestamp"}, "evidenceRevision": {"$ref": "#/$defs/revision"}}}, "targetWrite": {"type": "object", "additionalProperties": false, "required": ["receiptRef", "targetRef", "completedAt"], "properties": {"receiptRef": {"$ref": "#/$defs/workspacePath"}, "targetRef": {"$ref": "#/$defs/workspacePath"}, "completedAt": {"$ref": "#/$defs/utcTimestamp"}}}
+  }
+}

package/docs/requirements/shared-agent-context/schemas/workspace-manifest.schema.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/workspace-manifest/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "title", "status", "members", "resources", "createdAt", "updatedAt"],
+  "properties": {
+    "schemaVersion": {"const": "1.0"},
+    "id": {"type": "string", "pattern": "^[a-z][a-z0-9-]{2,63}$"},
+    "title": {"type": "string", "minLength": 1, "maxLength": 160},
+    "status": {"enum": ["active", "archived"]},
+    "members": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {"$ref": "#/$defs/member"},
+      "contains": {"properties": {"role": {"const": "owner"}}, "required": ["role"]},
+      "minContains": 1,
+      "maxContains": 1,
+      "x-uniqueBy": "subject",
+      "x-roleTopology": "exactly-one-owner; each canonical subject has one role"
+    },
+    "resources": {"type": "array", "items": {"$ref": "#/$defs/resourceRef"}, "x-uniqueBy": "uri"},
+    "createdAt": {"$ref": "#/$defs/utcTimestamp"},
+    "updatedAt": {"$ref": "#/$defs/utcTimestamp"}
+  },
+  "x-temporalOrder": [{"earlier": "createdAt", "laterOrEqual": "updatedAt"}],
+  "x-rootContainment": {"fields": ["resources[].uri"], "root": "workspace root", "resolveSymlinks": true, "rejectEscapes": true},
+  "$defs": {
+    "utcTimestamp": {"type": "string", "format": "date-time", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$", "x-formatAssertionRequired": true},
+    "subjectId": {"type": "string", "pattern": "^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"},
+    "member": {"type": "object", "additionalProperties": false, "required": ["subject", "role"], "properties": {"subject": {"$ref": "#/$defs/subjectId"}, "role": {"enum": ["owner", "editor", "viewer"]}}},
+    "workspacePath": {"type": "string", "pattern": "^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$", "x-canonicalize": "realpath within workspace root"},
+    "resourceRef": {"type": "object", "additionalProperties": false, "required": ["kind", "uri"], "properties": {"kind": {"enum": ["component", "repository", "flow", "wiki", "memory", "skill", "evidence", "worktree", "session"]}, "uri": {"$ref": "#/$defs/workspacePath"}, "revision": {"type": "string", "minLength": 1, "maxLength": 256}}}
+  }
+}

package/docs/requirements/shared-agent-context/schemas/workspace-proposal.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "keryx/shared-agent-context/workspace-proposal/v1",
+  "$vocabulary": {"https://json-schema.org/draft/2020-12/vocab/format-assertion": true},
+  "oneOf": [{"$ref":"#/$defs/creation"},{"$ref":"#/$defs/writeIntent"},{"$ref":"#/$defs/transition"}],
+  "$defs": {
+    "id":{"type":"string","pattern":"^[a-z][a-z0-9-]{2,63}$"},
+    "utc":{"type":"string","format":"date-time","pattern":"^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(?:\\.[0-9]+)?Z$","x-formatAssertionRequired":true},
+    "revision":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$","x-immutable":true},
+    "correlationId":{"type":"string","minLength":16,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$","x-immutable":true},
+    "key":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{15,255}$"},
+    "path":{"type":"string","pattern":"^\\./(?!.*(?:^|/)\\.\\.(?:/|$))(?:[A-Za-z0-9._-]+/)*[A-Za-z0-9._-]+$","x-rootContainment":"workspace root realpath"},
+    "evidence":{"type":"object","additionalProperties":false,"required":["kind","uri","revision","observedAt"],"properties":{"kind":{"type":"string","minLength":1,"maxLength":64},"uri":{"$ref":"#/$defs/path"},"revision":{"$ref":"#/$defs/revision"},"observedAt":{"$ref":"#/$defs/utc"}}},
+    "actor":{"type":"object","additionalProperties":false,"required":["subject","authority","trustedPrincipalRef"],"properties":{"subject":{"type":"string","pattern":"^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"},"authority":{"enum":["owner","editor"]},"trustedPrincipalRef":{"$ref":"#/$defs/path"}}},
+    "security":{"type":"object","additionalProperties":false,"required":["gate","policyRef","policyRevision"],"properties":{"gate":{"const":"pass"},"policyRef":{"$ref":"#/$defs/path"},"policyRevision":{"$ref":"#/$defs/revision"}}},
+    "creation":{"type":"object","additionalProperties":false,"required":["schemaVersion","recordType","id","proposalRevision","correlationId","workspaceId","kind","status","summary","evidence","wrapUp","author","security","createdAt"],"properties":{"schemaVersion":{"const":"1.0"},"recordType":{"const":"proposal-created"},"id":{"$ref":"#/$defs/id"},"proposalRevision":{"$ref":"#/$defs/revision"},"correlationId":{"$ref":"#/$defs/correlationId"},"workspaceId":{"$ref":"#/$defs/id"},"kind":{"enum":["decision","wiki-update","memory-entry","follow-up","contract-change","risk"]},"status":{"const":"proposed"},"summary":{"type":"string","minLength":1,"maxLength":8000},"evidence":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/evidence"}},"wrapUp":{"type":"object","additionalProperties":false,"required":["id","source","sourceRef","sourceRevision","issuedAt","expiresAt"],"properties":{"id":{"$ref":"#/$defs/id"},"source":{"enum":["session","flow"]},"sourceRef":{"$ref":"#/$defs/path"},"sourceRevision":{"$ref":"#/$defs/revision"},"issuedAt":{"$ref":"#/$defs/utc"},"expiresAt":{"$ref":"#/$defs/utc"}}},"author":{"type":"string","pattern":"^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"},"security":{"type":"object","additionalProperties":false,"required":["gate","redacted","policyRef","policyRevision"],"properties":{"gate":{"enum":["pass","needs-approval"]},"redacted":{"const":true},"policyRef":{"$ref":"#/$defs/path"},"policyRevision":{"$ref":"#/$defs/revision"}}},"createdAt":{"$ref":"#/$defs/utc"}},"x-immutableRecord":true},
+    "writeIntent":{"type":"object","additionalProperties":false,"required":["schemaVersion","recordType","intentId","proposalId","proposalRevision","correlationId","workspaceId","sequence","priorEventHash","idempotencyKey","reviewer","approvalRef","security","evidence","createdAt"],"properties":{"schemaVersion":{"const":"1.0"},"recordType":{"const":"proposal-write-intent"},"intentId":{"$ref":"#/$defs/id"},"proposalId":{"$ref":"#/$defs/id"},"proposalRevision":{"$ref":"#/$defs/revision"},"correlationId":{"$ref":"#/$defs/correlationId"},"workspaceId":{"$ref":"#/$defs/id"},"sequence":{"type":"integer","minimum":1},"priorEventHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"idempotencyKey":{"$ref":"#/$defs/key"},"reviewer":{"$ref":"#/$defs/actor"},"approvalRef":{"$ref":"#/$defs/path"},"security":{"$ref":"#/$defs/security"},"evidence":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/evidence"}},"createdAt":{"$ref":"#/$defs/utc"}},"x-appendOnly":{"stream":"proposalId","strictSequence":true,"recovery":"owner-idempotency-key"}},
+    "transition":{"type":"object","additionalProperties":false,"required":["schemaVersion","recordType","eventId","proposalId","proposalRevision","correlationId","workspaceId","sequence","priorEventHash","fromStatus","toStatus","occurredAt","idempotencyKey"],"properties":{"schemaVersion":{"const":"1.0"},"recordType":{"const":"proposal-transition"},"eventId":{"$ref":"#/$defs/id"},"proposalId":{"$ref":"#/$defs/id"},"proposalRevision":{"$ref":"#/$defs/revision"},"correlationId":{"$ref":"#/$defs/correlationId"},"workspaceId":{"$ref":"#/$defs/id"},"sequence":{"type":"integer","minimum":1},"priorEventHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"fromStatus":{"const":"proposed"},"toStatus":{"enum":["accepted","rejected","dismissed","stale"]},"occurredAt":{"$ref":"#/$defs/utc"},"idempotencyKey":{"$ref":"#/$defs/key"},"acceptance":{"$ref":"#/$defs/acceptance"},"reason":{"type":"string","minLength":1,"maxLength":2000}},"allOf":[{"if":{"properties":{"toStatus":{"const":"accepted"}},"required":["toStatus"]},"then":{"required":["acceptance"]},"else":{"required":["reason"],"not":{"required":["acceptance"]}}}]},
+    "receiptBinding":{"type":"object","additionalProperties":false,"required":["owner","bindingHash","intentRef","proposalId","proposalRevision","workspaceId","correlationId","idempotencyKey","reviewerSubject","reviewerAuthority","policyRevision"],"properties":{"owner":{"enum":["wiki","memory","skill"]},"bindingHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"intentRef":{"$ref":"#/$defs/path"},"proposalId":{"$ref":"#/$defs/id"},"proposalRevision":{"$ref":"#/$defs/revision"},"workspaceId":{"$ref":"#/$defs/id"},"correlationId":{"$ref":"#/$defs/correlationId"},"idempotencyKey":{"$ref":"#/$defs/key"},"reviewerSubject":{"type":"string","pattern":"^(?:user|team|service|agent):[a-z0-9][a-z0-9._-]{0,127}$"},"reviewerAuthority":{"enum":["owner","editor"]},"policyRevision":{"$ref":"#/$defs/revision"}}},
+    "acceptance":{"type":"object","additionalProperties":false,"required":["reviewDecisionRef","writeIntentRef","reviewer","security","freshness","targetWrite","evidence","idempotencyKey"],"properties":{"reviewDecisionRef":{"$ref":"#/$defs/path"},"writeIntentRef":{"$ref":"#/$defs/path"},"reviewer":{"$ref":"#/$defs/actor"},"security":{"$ref":"#/$defs/security"},"freshness":{"type":"object","additionalProperties":false,"required":["state","verifiedAt","maxEvidenceAgeSeconds"],"properties":{"state":{"const":"fresh"},"verifiedAt":{"$ref":"#/$defs/utc"},"maxEvidenceAgeSeconds":{"type":"integer","minimum":1,"maximum":86400}}},"targetWrite":{"type":"object","additionalProperties":false,"required":["receiptRef","targetRef","completedAt","binding"],"properties":{"receiptRef":{"$ref":"#/$defs/path"},"targetRef":{"$ref":"#/$defs/path"},"completedAt":{"$ref":"#/$defs/utc"},"binding":{"$ref":"#/$defs/receiptBinding"}}},"evidence":{"type":"array","minItems":1,"items":{"$ref":"#/$defs/evidence"}},"idempotencyKey":{"$ref":"#/$defs/key"}},"x-temporalOrder":[{"earlier":"evidence[].observedAt","laterOrEqual":"freshness.verifiedAt"},{"earlier":"freshness.verifiedAt","laterOrEqual":"targetWrite.completedAt"}]}
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.34",
+  "version": "0.2.35",
   "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {
@@ -45,6 +45,7 @@
   },
   "files": [
     "dist",
+    "docs/requirements/shared-agent-context/schemas",
     "src/gdgraph",
     "src/gdskills/bundled",
     "src/gdskills/contracts",
@@ -60,10 +61,15 @@
   },
   "devDependencies": {
     "@types/bun": "latest",
+    "@xenova/transformers": "^2.17.2",
     "bun-types": "latest",
     "typescript": "^5"
   },
   "engines": {
     "bun": ">=1.1.0"
-  }
+  },
+  "trustedDependencies": [
+    "protobufjs",
+    "sharp"
+  ]
 }