open-multi-agent-kit 0.95.1 → 0.96.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## [Unreleased]
+
+## [0.96.0] - 2026-08-16
+
+### Added
+
+- Added `omk-protocol`, the versioned `TaskSpec -> ExecutionAttempt -> Observation -> EvaluationResult -> RuntimeDecision` contract package, with runtime validators, explicit waivers, and pure semantic and runtime-decision reducers.
+- Added `evidenceReceiptToObservation()` to project integrity-checked EvidenceReceipt v3 cores into immutable protocol facts. Legacy mutable `EvidenceStatus` and `TaskContract` verdict APIs remain compatible but are deprecated.
+- Added the optional `omk-book-to-skill` package with compile/update commands, a pinned upstream workflow, advisory generated-skill scanning, and SHA-256 source/artifact provenance checks. Python extractors remain outside OMK core.
+- Added deterministically seeded, bounded `fast-check` model and property suites for WPL transitions, replay migration and CAS, evidence freshness, subagent topology, run-journal CAS, and timeout/abort settlement ordering.
+
+### Changed
+
+- New replay events declare `jcs-rfc8785-v2` and hash RFC 8785-canonical payloads. Events without an algorithm remain verified as `json-stringify-v1`; mixed ledgers and exports preserve legacy records without rewriting them.
+
+### Fixed
+
+- NVIDIA NIM's `z-ai/glm-5.2` entry now transmits `reasoning_effort`, including the generated `max` thinking level; other NVIDIA models keep conservative compatibility defaults.
+- Billing-cycle and quota exhaustion, including provider 403 usage-limit responses, now classify as `provider.rate_limit` and can switch to the first configured, authenticated resilience candidate before retry. Each attempt remains journaled, and a recovered retry ends with a later `completed` termination.
+- Subagent DAG scheduling now sorts simultaneously ready lanes by lane ID, so topology aggregation does not depend on input insertion order.
+- Local release bundles now include `omk-adaptorch-wpl`, allowing isolated installs of the full packed workspace without resolving that dependency from the registry.
+
+## [0.95.2] - 2026-08-15
+
+### Changed
+
+- macOS sessions now derive replay-ledger process identity from bounded BSD `ps -o lstart=` output, so replay-lock acquisition no longer fails closed during AgentSession startup on Darwin while Linux `/proc` behavior remains unchanged.
+- The status rail now verifies connected MCP servers with protocol pings, marks dead processes as failed, and retries failed servers on a bounded slower cadence without spawning idle servers.
+- Interactive UX now includes an empty-editor affordance hint, elapsed-time and interrupt details on the working indicator, transient information notices, width-safe editor scroll borders, and opt-in footer CPU/memory metrics.
+- Extension tools can resolve timeouts from current context. The subagent extension uses this to remove task-count, concurrency, execution-budget, attempt, and outer tool-timeout caps in Ultra while preserving explicit cancellation and non-Ultra limits.
+- The startup control panel now identifies the product with `WELCOME TO OMK` instead of legacy Pi agent branding.
+- Context-budget prompts use compact metadata for valid zero-resource plans while retaining cache-state and legacy optimizer compatibility telemetry; diagnostic and non-empty plans keep full observability, and invalid budgets bypass the plan cache so diagnostics cannot be hidden by a prior hit.
+- The workspace context-budget cache scans every persisted key/value, keeps credential-shaped entries in memory only, and removes unsafe legacy snapshots instead of persisting secret-shaped text.
+- Exact context representations now reuse content-addressed cache entries across different queries and budget sizes instead of forcing avoidable misses.
+- Opt-in reasoning-router learning now isolates default ledgers and compiled bias snapshots per repository or git worktree, captures explicit manual thinking-level overrides as bounded feedback, and keeps updates behind the shipped, deterministic `omk router-feedback compile-bias` between-session command. Snapshot loading rejects nonzero biases below the strong-evidence threshold, unsafe or inconsistent counts, and duplicate cells; compilation uses an exclusive randomized temporary file before atomic rename.
+- Session bash now defaults to OS sandbox enforcement instead of ledger-only audit mode. macOS `sandbox-exec` and Linux `bwrap` restrict writes to the workspace/temp directories and disable network access; missing backends fail closed. Unwrapped `audit` and disabled `off` modes now require an explicit `OMK_BASH_SANDBOX` value, and unknown values resolve to `enforce`.
+
 ## [0.95.1] - 2026-08-01
 
 ### Added

package/README.md

@@ -40,6 +40,16 @@ Then:
 
 OMK stores user configuration under `~/.omk/agent/` and project configuration under `.omk/`.
 
+## Optional document compiler
+
+Install `omk-book-to-skill` to compile documents into reusable skills without adding Python extractors to OMK core:
+
+```bash
+omk install npm:omk-book-to-skill@0.95.2
+```
+
+It provides compile, update, and verification commands plus a local SHA-256 provenance manifest. See [Book to Skill](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/book-to-skill.md).
+
 ## Providers & Models
 
 OMK includes provider adapters for Anthropic, OpenAI Codex, Google, OpenCode, Kimi, Qwen, ZAI/GLM, Grok, and other compatible services. Availability depends on the credentials and endpoints configured on the current machine.
@@ -47,11 +57,14 @@ OMK includes provider adapters for Anthropic, OpenAI Codex, Google, OpenCode, Ki
 - `/login` adds or selects credentials.
 - `/logout` removes credentials for a selected provider.
 - `/model` lists models available to the current credential set.
+- NVIDIA NIM's `z-ai/glm-5.2` entry transmits reasoning effort, including `/thinking max`.
 - The optional status rail shows independent provider quota windows when an official API or passive response signal is available.
 - Missing quota values are shown as unavailable rather than estimated.
 
 OAuth credentials are stored locally in `~/.omk/agent/auth.json`. Multi-account providers keep accounts separate and send requests only through the explicitly selected account.
 
+Quota and billing-cycle errors are classified as rate limits and can switch to the first authenticated resilience candidate before retry. See [Provider resilience](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/provider-resilience.md).
+
 See [Provider setup](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/providers.md) for provider-specific authentication, quota behavior, and environment variables.
 
 ### Kimi For Coding
@@ -142,6 +155,8 @@ See [RPC](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/rpc
 
 The TypeScript SDK exposes session creation, provider configuration, tools, and event streams. Extensions can add commands, tools, UI components, themes, and resource loaders without patching OMK core.
 
+`omk-protocol` provides the versioned `TaskSpec -> ExecutionAttempt -> Observation -> EvaluationResult -> RuntimeDecision` contracts and pure semantic reducers. See [Run Protocol v1](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/run-protocol.md) for the implemented scope and migration boundaries.
+
 - [SDK](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/sdk.md)
 - [Extensions](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/extensions.md)
 - [Skills](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/skills.md)
@@ -170,7 +185,7 @@ npm test
 
 See [Development](https://github.com/dmae97/omk/blob/main/packages/coding-agent/docs/development.md) and [CONTRIBUTING.md](https://github.com/dmae97/omk/blob/main/CONTRIBUTING.md).
 
-Release notes: [v0.95.1](https://github.com/dmae97/omk/blob/main/.github/RELEASE_NOTES_v0.95.1.md).
+Release notes: [v0.95.2](https://github.com/dmae97/omk/blob/main/.github/RELEASE_NOTES_v0.95.2.md).
 
 ## License
 

package/dist/approvals/approval-receipt-store.d.ts

@@ -0,0 +1,18 @@
+import { type ApprovalReceipt } from "./approval-receipt.ts";
+export interface ApprovalReceiptWriteResult {
+    path: string;
+    created: boolean;
+}
+export declare class ApprovalReceiptStore {
+    readonly rootDir: string;
+    constructor(rootDir: string);
+    private ensurePrivateDirectory;
+    private assertRootUnchanged;
+    private pathFor;
+    private openReceiptForRead;
+    write(receipt: ApprovalReceipt): ApprovalReceiptWriteResult;
+    has(receiptId: string): boolean;
+    read(receiptId: string): ApprovalReceipt;
+    listReceiptIds(): string[];
+}
+//# sourceMappingURL=approval-receipt-store.d.ts.map

package/dist/approvals/approval-receipt-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-receipt-store.d.ts","sourceRoot":"","sources":["../../src/approvals/approval-receipt-store.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,KAAK,eAAe,EAAqD,MAAM,uBAAuB,CAAC;AAKhH,MAAM,WAAW,0BAA0B;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;CACjB;AAsDD,qBAAa,oBAAoB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,YAAY,OAAO,EAAE,MAAM,EAG1B;IAED,OAAO,CAAC,sBAAsB;IAa9B,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,kBAAkB;IAW1B,KAAK,CAAC,OAAO,EAAE,eAAe,GAAG,0BAA0B,CA4D1D;IAED,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAe9B;IAED,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,eAAe,CAUvC;IAED,cAAc,IAAI,MAAM,EAAE,CASzB;CACD","sourcesContent":["import {\n\tcloseSync,\n\tconstants,\n\tfchmodSync,\n\tfstatSync,\n\tfsyncSync,\n\tlstatSync,\n\tmkdirSync,\n\topenSync,\n\treaddirSync,\n\treadSync,\n\twriteFileSync,\n} from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { type ApprovalReceipt, serializeApprovalReceipt, validateApprovalReceipt } from \"./approval-receipt.ts\";\n\nconst MAX_RECEIPT_BYTES = 1024 * 1024;\nconst NOFOLLOW = constants.O_NOFOLLOW ?? 0;\n\nexport interface ApprovalReceiptWriteResult {\n\tpath: string;\n\tcreated: boolean;\n}\n\ninterface RootIdentity {\n\tdev: number;\n\tino: number;\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n\treturn error instanceof Error && \"code\" in error && error.code === code;\n}\n\nfunction assertOwnedByCurrentUser(uid: number, label: string): void {\n\tconst getuid = process.getuid;\n\tif (typeof getuid === \"function\" && uid !== getuid()) {\n\t\tthrow new Error(`${label} is not owned by the current user`);\n\t}\n}\n\nfunction receiptFileName(receiptId: string): string {\n\tif (!/^approval-[a-f0-9]{32}$/u.test(receiptId)) throw new Error(\"Approval receipt id is invalid\");\n\treturn `${receiptId}.json`;\n}\n\nfunction assertPrivateReceiptFd(fd: number, filePath: string): void {\n\tconst stat = fstatSync(fd);\n\tif (!stat.isFile()) throw new Error(`Approval receipt is not a regular file: ${filePath}`);\n\tif (stat.nlink !== 1) throw new Error(`Approval receipt must not be hard-linked: ${filePath}`);\n\tassertOwnedByCurrentUser(stat.uid, `Approval receipt ${filePath}`);\n\tif ((stat.mode & 0o777) !== 0o600) {\n\t\tthrow new Error(`Approval receipt permissions must be 0600: ${filePath}`);\n\t}\n\tif (stat.size > MAX_RECEIPT_BYTES) throw new Error(`Approval receipt exceeds ${MAX_RECEIPT_BYTES} bytes`);\n}\n\nfunction readReceiptFromFd(fd: number, filePath: string): ApprovalReceipt {\n\tassertPrivateReceiptFd(fd, filePath);\n\tconst buffer = Buffer.alloc(MAX_RECEIPT_BYTES + 1);\n\tlet offset = 0;\n\twhile (offset < buffer.length) {\n\t\tconst read = readSync(fd, buffer, offset, buffer.length - offset, offset);\n\t\tif (read === 0) break;\n\t\toffset += read;\n\t}\n\tif (offset > MAX_RECEIPT_BYTES) throw new Error(`Approval receipt exceeds ${MAX_RECEIPT_BYTES} bytes`);\n\tassertPrivateReceiptFd(fd, filePath);\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(buffer.subarray(0, offset).toString(\"utf8\")) as unknown;\n\t} catch {\n\t\tthrow new Error(`Approval receipt is not valid JSON: ${filePath}`);\n\t}\n\treturn validateApprovalReceipt(value);\n}\n\nexport class ApprovalReceiptStore {\n\treadonly rootDir: string;\n\n\tconstructor(rootDir: string) {\n\t\tthis.rootDir = resolve(rootDir);\n\t\tthis.ensurePrivateDirectory();\n\t}\n\n\tprivate ensurePrivateDirectory(): RootIdentity {\n\t\tmkdirSync(this.rootDir, { recursive: true, mode: 0o700 });\n\t\tconst stat = lstatSync(this.rootDir);\n\t\tif (stat.isSymbolicLink() || !stat.isDirectory()) {\n\t\t\tthrow new Error(`Approval receipt root must be a real directory: ${this.rootDir}`);\n\t\t}\n\t\tassertOwnedByCurrentUser(stat.uid, `Approval receipt root ${this.rootDir}`);\n\t\tif ((stat.mode & 0o777) !== 0o700) {\n\t\t\tthrow new Error(`Approval receipt root permissions must be 0700: ${this.rootDir}`);\n\t\t}\n\t\treturn { dev: stat.dev, ino: stat.ino };\n\t}\n\n\tprivate assertRootUnchanged(expected: RootIdentity): void {\n\t\tconst current = this.ensurePrivateDirectory();\n\t\tif (current.dev !== expected.dev || current.ino !== expected.ino) {\n\t\t\tthrow new Error(\"Approval receipt root changed during the operation\");\n\t\t}\n\t}\n\n\tprivate pathFor(receiptId: string): string {\n\t\treturn join(this.rootDir, receiptFileName(receiptId));\n\t}\n\n\tprivate openReceiptForRead(filePath: string): number {\n\t\tconst fd = openSync(filePath, constants.O_RDONLY | NOFOLLOW);\n\t\ttry {\n\t\t\tassertPrivateReceiptFd(fd, filePath);\n\t\t\treturn fd;\n\t\t} catch (error) {\n\t\t\tcloseSync(fd);\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\twrite(receipt: ApprovalReceipt): ApprovalReceiptWriteResult {\n\t\tconst validated = validateApprovalReceipt(receipt);\n\t\tconst rootIdentity = this.ensurePrivateDirectory();\n\t\tconst filePath = this.pathFor(validated.core.receiptId);\n\t\tconst canonical = serializeApprovalReceipt(validated);\n\t\tconst bytes = Buffer.from(canonical, \"utf8\");\n\t\tif (bytes.byteLength > MAX_RECEIPT_BYTES) throw new Error(`Approval receipt exceeds ${MAX_RECEIPT_BYTES} bytes`);\n\n\t\t// Explicit existence/symlink pre-check. O_EXCL/O_NOFOLLOW are honored on\n\t\t// proper Linux but silently ignored on some platforms (e.g. WSL2), which\n\t\t// would silently void the never-overwrite and symlink-rejection invariants\n\t\t// (hard rule: no silent degraded operation). Enforce them via lstat so the\n\t\t// guarantees hold on every platform; O_EXCL below stays as the atomic\n\t\t// backstop for the create path on capable platforms.\n\t\tlet existingStat: ReturnType<typeof lstatSync> | null = null;\n\t\ttry {\n\t\t\texistingStat = lstatSync(filePath);\n\t\t} catch (error) {\n\t\t\tif (!isErrno(error, \"ENOENT\")) throw error;\n\t\t}\n\t\tif (existingStat !== null) {\n\t\t\tif (existingStat.isSymbolicLink()) {\n\t\t\t\tthrow new Error(`Approval receipt must not be a symbolic link: ${filePath}`);\n\t\t\t}\n\t\t\tconst prior = this.read(validated.core.receiptId);\n\t\t\tif (serializeApprovalReceipt(prior) !== canonical) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Approval receipt already exists with different content and is never overwritten: ${validated.core.receiptId}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tthis.assertRootUnchanged(rootIdentity);\n\t\t\treturn { path: filePath, created: false };\n\t\t}\n\n\t\tlet fd: number;\n\t\ttry {\n\t\t\tfd = openSync(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW, 0o600);\n\t\t} catch (error) {\n\t\t\tif (!isErrno(error, \"EEXIST\")) throw error;\n\t\t\tconst existing = this.read(validated.core.receiptId);\n\t\t\tif (serializeApprovalReceipt(existing) !== canonical) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Approval receipt already exists with different content and is never overwritten: ${validated.core.receiptId}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tthis.assertRootUnchanged(rootIdentity);\n\t\t\treturn { path: filePath, created: false };\n\t\t}\n\n\t\ttry {\n\t\t\tfchmodSync(fd, 0o600);\n\t\t\tassertPrivateReceiptFd(fd, filePath);\n\t\t\twriteFileSync(fd, bytes);\n\t\t\tfsyncSync(fd);\n\t\t\tassertPrivateReceiptFd(fd, filePath);\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t\tthis.assertRootUnchanged(rootIdentity);\n\t\treturn { path: filePath, created: true };\n\t}\n\n\thas(receiptId: string): boolean {\n\t\tconst rootIdentity = this.ensurePrivateDirectory();\n\t\tlet fd: number;\n\t\ttry {\n\t\t\tfd = this.openReceiptForRead(this.pathFor(receiptId));\n\t\t} catch (error) {\n\t\t\tif (isErrno(error, \"ENOENT\")) {\n\t\t\t\tthis.assertRootUnchanged(rootIdentity);\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t\tcloseSync(fd);\n\t\tthis.assertRootUnchanged(rootIdentity);\n\t\treturn true;\n\t}\n\n\tread(receiptId: string): ApprovalReceipt {\n\t\tconst rootIdentity = this.ensurePrivateDirectory();\n\t\tconst filePath = this.pathFor(receiptId);\n\t\tconst fd = this.openReceiptForRead(filePath);\n\t\ttry {\n\t\t\treturn readReceiptFromFd(fd, filePath);\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t\tthis.assertRootUnchanged(rootIdentity);\n\t\t}\n\t}\n\n\tlistReceiptIds(): string[] {\n\t\tconst rootIdentity = this.ensurePrivateDirectory();\n\t\tconst ids = readdirSync(this.rootDir)\n\t\t\t.map((name) => /^(approval-[a-f0-9]{32})\\.json$/u.exec(name)?.[1])\n\t\t\t.filter((id): id is string => id !== undefined)\n\t\t\t.sort((left, right) => left.localeCompare(right));\n\t\tfor (const id of ids) this.has(id);\n\t\tthis.assertRootUnchanged(rootIdentity);\n\t\treturn ids;\n\t}\n}\n"]}

package/dist/approvals/approval-receipt-store.js

@@ -0,0 +1,194 @@
+import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readdirSync, readSync, writeFileSync, } from "node:fs";
+import { join, resolve } from "node:path";
+import { serializeApprovalReceipt, validateApprovalReceipt } from "./approval-receipt.js";
+const MAX_RECEIPT_BYTES = 1024 * 1024;
+const NOFOLLOW = constants.O_NOFOLLOW ?? 0;
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function assertOwnedByCurrentUser(uid, label) {
+    const getuid = process.getuid;
+    if (typeof getuid === "function" && uid !== getuid()) {
+        throw new Error(`${label} is not owned by the current user`);
+    }
+}
+function receiptFileName(receiptId) {
+    if (!/^approval-[a-f0-9]{32}$/u.test(receiptId))
+        throw new Error("Approval receipt id is invalid");
+    return `${receiptId}.json`;
+}
+function assertPrivateReceiptFd(fd, filePath) {
+    const stat = fstatSync(fd);
+    if (!stat.isFile())
+        throw new Error(`Approval receipt is not a regular file: ${filePath}`);
+    if (stat.nlink !== 1)
+        throw new Error(`Approval receipt must not be hard-linked: ${filePath}`);
+    assertOwnedByCurrentUser(stat.uid, `Approval receipt ${filePath}`);
+    if ((stat.mode & 0o777) !== 0o600) {
+        throw new Error(`Approval receipt permissions must be 0600: ${filePath}`);
+    }
+    if (stat.size > MAX_RECEIPT_BYTES)
+        throw new Error(`Approval receipt exceeds ${MAX_RECEIPT_BYTES} bytes`);
+}
+function readReceiptFromFd(fd, filePath) {
+    assertPrivateReceiptFd(fd, filePath);
+    const buffer = Buffer.alloc(MAX_RECEIPT_BYTES + 1);
+    let offset = 0;
+    while (offset < buffer.length) {
+        const read = readSync(fd, buffer, offset, buffer.length - offset, offset);
+        if (read === 0)
+            break;
+        offset += read;
+    }
+    if (offset > MAX_RECEIPT_BYTES)
+        throw new Error(`Approval receipt exceeds ${MAX_RECEIPT_BYTES} bytes`);
+    assertPrivateReceiptFd(fd, filePath);
+    let value;
+    try {
+        value = JSON.parse(buffer.subarray(0, offset).toString("utf8"));
+    }
+    catch {
+        throw new Error(`Approval receipt is not valid JSON: ${filePath}`);
+    }
+    return validateApprovalReceipt(value);
+}
+export class ApprovalReceiptStore {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = resolve(rootDir);
+        this.ensurePrivateDirectory();
+    }
+    ensurePrivateDirectory() {
+        mkdirSync(this.rootDir, { recursive: true, mode: 0o700 });
+        const stat = lstatSync(this.rootDir);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+            throw new Error(`Approval receipt root must be a real directory: ${this.rootDir}`);
+        }
+        assertOwnedByCurrentUser(stat.uid, `Approval receipt root ${this.rootDir}`);
+        if ((stat.mode & 0o777) !== 0o700) {
+            throw new Error(`Approval receipt root permissions must be 0700: ${this.rootDir}`);
+        }
+        return { dev: stat.dev, ino: stat.ino };
+    }
+    assertRootUnchanged(expected) {
+        const current = this.ensurePrivateDirectory();
+        if (current.dev !== expected.dev || current.ino !== expected.ino) {
+            throw new Error("Approval receipt root changed during the operation");
+        }
+    }
+    pathFor(receiptId) {
+        return join(this.rootDir, receiptFileName(receiptId));
+    }
+    openReceiptForRead(filePath) {
+        const fd = openSync(filePath, constants.O_RDONLY | NOFOLLOW);
+        try {
+            assertPrivateReceiptFd(fd, filePath);
+            return fd;
+        }
+        catch (error) {
+            closeSync(fd);
+            throw error;
+        }
+    }
+    write(receipt) {
+        const validated = validateApprovalReceipt(receipt);
+        const rootIdentity = this.ensurePrivateDirectory();
+        const filePath = this.pathFor(validated.core.receiptId);
+        const canonical = serializeApprovalReceipt(validated);
+        const bytes = Buffer.from(canonical, "utf8");
+        if (bytes.byteLength > MAX_RECEIPT_BYTES)
+            throw new Error(`Approval receipt exceeds ${MAX_RECEIPT_BYTES} bytes`);
+        // Explicit existence/symlink pre-check. O_EXCL/O_NOFOLLOW are honored on
+        // proper Linux but silently ignored on some platforms (e.g. WSL2), which
+        // would silently void the never-overwrite and symlink-rejection invariants
+        // (hard rule: no silent degraded operation). Enforce them via lstat so the
+        // guarantees hold on every platform; O_EXCL below stays as the atomic
+        // backstop for the create path on capable platforms.
+        let existingStat = null;
+        try {
+            existingStat = lstatSync(filePath);
+        }
+        catch (error) {
+            if (!isErrno(error, "ENOENT"))
+                throw error;
+        }
+        if (existingStat !== null) {
+            if (existingStat.isSymbolicLink()) {
+                throw new Error(`Approval receipt must not be a symbolic link: ${filePath}`);
+            }
+            const prior = this.read(validated.core.receiptId);
+            if (serializeApprovalReceipt(prior) !== canonical) {
+                throw new Error(`Approval receipt already exists with different content and is never overwritten: ${validated.core.receiptId}`);
+            }
+            this.assertRootUnchanged(rootIdentity);
+            return { path: filePath, created: false };
+        }
+        let fd;
+        try {
+            fd = openSync(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW, 0o600);
+        }
+        catch (error) {
+            if (!isErrno(error, "EEXIST"))
+                throw error;
+            const existing = this.read(validated.core.receiptId);
+            if (serializeApprovalReceipt(existing) !== canonical) {
+                throw new Error(`Approval receipt already exists with different content and is never overwritten: ${validated.core.receiptId}`);
+            }
+            this.assertRootUnchanged(rootIdentity);
+            return { path: filePath, created: false };
+        }
+        try {
+            fchmodSync(fd, 0o600);
+            assertPrivateReceiptFd(fd, filePath);
+            writeFileSync(fd, bytes);
+            fsyncSync(fd);
+            assertPrivateReceiptFd(fd, filePath);
+        }
+        finally {
+            closeSync(fd);
+        }
+        this.assertRootUnchanged(rootIdentity);
+        return { path: filePath, created: true };
+    }
+    has(receiptId) {
+        const rootIdentity = this.ensurePrivateDirectory();
+        let fd;
+        try {
+            fd = this.openReceiptForRead(this.pathFor(receiptId));
+        }
+        catch (error) {
+            if (isErrno(error, "ENOENT")) {
+                this.assertRootUnchanged(rootIdentity);
+                return false;
+            }
+            throw error;
+        }
+        closeSync(fd);
+        this.assertRootUnchanged(rootIdentity);
+        return true;
+    }
+    read(receiptId) {
+        const rootIdentity = this.ensurePrivateDirectory();
+        const filePath = this.pathFor(receiptId);
+        const fd = this.openReceiptForRead(filePath);
+        try {
+            return readReceiptFromFd(fd, filePath);
+        }
+        finally {
+            closeSync(fd);
+            this.assertRootUnchanged(rootIdentity);
+        }
+    }
+    listReceiptIds() {
+        const rootIdentity = this.ensurePrivateDirectory();
+        const ids = readdirSync(this.rootDir)
+            .map((name) => /^(approval-[a-f0-9]{32})\.json$/u.exec(name)?.[1])
+            .filter((id) => id !== undefined)
+            .sort((left, right) => left.localeCompare(right));
+        for (const id of ids)
+            this.has(id);
+        this.assertRootUnchanged(rootIdentity);
+        return ids;
+    }
+}
+//# sourceMappingURL=approval-receipt-store.js.map

package/dist/approvals/approval-receipt-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-receipt-store.js","sourceRoot":"","sources":["../../src/approvals/approval-receipt-store.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n\tcloseSync,\n\tconstants,\n\tfchmodSync,\n\tfstatSync,\n\tfsyncSync,\n\tlstatSync,\n\tmkdirSync,\n\topenSync,\n\treaddirSync,\n\treadSync,\n\twriteFileSync,\n} from \"node:fs\";\nimport { join, resolve } from \"node:path\";\nimport { type ApprovalReceipt, serializeApprovalReceipt, validateApprovalReceipt } from \"./approval-receipt.ts\";\n\nconst MAX_RECEIPT_BYTES = 1024 * 1024;\nconst NOFOLLOW = constants.O_NOFOLLOW ?? 0;\n\nexport interface ApprovalReceiptWriteResult {\n\tpath: string;\n\tcreated: boolean;\n}\n\ninterface RootIdentity {\n\tdev: number;\n\tino: number;\n}\n\nfunction isErrno(error: unknown, code: string): boolean {\n\treturn error instanceof Error && \"code\" in error && error.code === code;\n}\n\nfunction assertOwnedByCurrentUser(uid: number, label: string): void {\n\tconst getuid = process.getuid;\n\tif (typeof getuid === \"function\" && uid !== getuid()) {\n\t\tthrow new Error(`${label} is not owned by the current user`);\n\t}\n}\n\nfunction receiptFileName(receiptId: string): string {\n\tif (!/^approval-[a-f0-9]{32}$/u.test(receiptId)) throw new Error(\"Approval receipt id is invalid\");\n\treturn `${receiptId}.json`;\n}\n\nfunction assertPrivateReceiptFd(fd: number, filePath: string): void {\n\tconst stat = fstatSync(fd);\n\tif (!stat.isFile()) throw new Error(`Approval receipt is not a regular file: ${filePath}`);\n\tif (stat.nlink !== 1) throw new Error(`Approval receipt must not be hard-linked: ${filePath}`);\n\tassertOwnedByCurrentUser(stat.uid, `Approval receipt ${filePath}`);\n\tif ((stat.mode & 0o777) !== 0o600) {\n\t\tthrow new Error(`Approval receipt permissions must be 0600: ${filePath}`);\n\t}\n\tif (stat.size > MAX_RECEIPT_BYTES) throw new Error(`Approval receipt exceeds ${MAX_RECEIPT_BYTES} bytes`);\n}\n\nfunction readReceiptFromFd(fd: number, filePath: string): ApprovalReceipt {\n\tassertPrivateReceiptFd(fd, filePath);\n\tconst buffer = Buffer.alloc(MAX_RECEIPT_BYTES + 1);\n\tlet offset = 0;\n\twhile (offset < buffer.length) {\n\t\tconst read = readSync(fd, buffer, offset, buffer.length - offset, offset);\n\t\tif (read === 0) break;\n\t\toffset += read;\n\t}\n\tif (offset > MAX_RECEIPT_BYTES) throw new Error(`Approval receipt exceeds ${MAX_RECEIPT_BYTES} bytes`);\n\tassertPrivateReceiptFd(fd, filePath);\n\tlet value: unknown;\n\ttry {\n\t\tvalue = JSON.parse(buffer.subarray(0, offset).toString(\"utf8\")) as unknown;\n\t} catch {\n\t\tthrow new Error(`Approval receipt is not valid JSON: ${filePath}`);\n\t}\n\treturn validateApprovalReceipt(value);\n}\n\nexport class ApprovalReceiptStore {\n\treadonly rootDir: string;\n\n\tconstructor(rootDir: string) {\n\t\tthis.rootDir = resolve(rootDir);\n\t\tthis.ensurePrivateDirectory();\n\t}\n\n\tprivate ensurePrivateDirectory(): RootIdentity {\n\t\tmkdirSync(this.rootDir, { recursive: true, mode: 0o700 });\n\t\tconst stat = lstatSync(this.rootDir);\n\t\tif (stat.isSymbolicLink() || !stat.isDirectory()) {\n\t\t\tthrow new Error(`Approval receipt root must be a real directory: ${this.rootDir}`);\n\t\t}\n\t\tassertOwnedByCurrentUser(stat.uid, `Approval receipt root ${this.rootDir}`);\n\t\tif ((stat.mode & 0o777) !== 0o700) {\n\t\t\tthrow new Error(`Approval receipt root permissions must be 0700: ${this.rootDir}`);\n\t\t}\n\t\treturn { dev: stat.dev, ino: stat.ino };\n\t}\n\n\tprivate assertRootUnchanged(expected: RootIdentity): void {\n\t\tconst current = this.ensurePrivateDirectory();\n\t\tif (current.dev !== expected.dev || current.ino !== expected.ino) {\n\t\t\tthrow new Error(\"Approval receipt root changed during the operation\");\n\t\t}\n\t}\n\n\tprivate pathFor(receiptId: string): string {\n\t\treturn join(this.rootDir, receiptFileName(receiptId));\n\t}\n\n\tprivate openReceiptForRead(filePath: string): number {\n\t\tconst fd = openSync(filePath, constants.O_RDONLY | NOFOLLOW);\n\t\ttry {\n\t\t\tassertPrivateReceiptFd(fd, filePath);\n\t\t\treturn fd;\n\t\t} catch (error) {\n\t\t\tcloseSync(fd);\n\t\t\tthrow error;\n\t\t}\n\t}\n\n\twrite(receipt: ApprovalReceipt): ApprovalReceiptWriteResult {\n\t\tconst validated = validateApprovalReceipt(receipt);\n\t\tconst rootIdentity = this.ensurePrivateDirectory();\n\t\tconst filePath = this.pathFor(validated.core.receiptId);\n\t\tconst canonical = serializeApprovalReceipt(validated);\n\t\tconst bytes = Buffer.from(canonical, \"utf8\");\n\t\tif (bytes.byteLength > MAX_RECEIPT_BYTES) throw new Error(`Approval receipt exceeds ${MAX_RECEIPT_BYTES} bytes`);\n\n\t\t// Explicit existence/symlink pre-check. O_EXCL/O_NOFOLLOW are honored on\n\t\t// proper Linux but silently ignored on some platforms (e.g. WSL2), which\n\t\t// would silently void the never-overwrite and symlink-rejection invariants\n\t\t// (hard rule: no silent degraded operation). Enforce them via lstat so the\n\t\t// guarantees hold on every platform; O_EXCL below stays as the atomic\n\t\t// backstop for the create path on capable platforms.\n\t\tlet existingStat: ReturnType<typeof lstatSync> | null = null;\n\t\ttry {\n\t\t\texistingStat = lstatSync(filePath);\n\t\t} catch (error) {\n\t\t\tif (!isErrno(error, \"ENOENT\")) throw error;\n\t\t}\n\t\tif (existingStat !== null) {\n\t\t\tif (existingStat.isSymbolicLink()) {\n\t\t\t\tthrow new Error(`Approval receipt must not be a symbolic link: ${filePath}`);\n\t\t\t}\n\t\t\tconst prior = this.read(validated.core.receiptId);\n\t\t\tif (serializeApprovalReceipt(prior) !== canonical) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Approval receipt already exists with different content and is never overwritten: ${validated.core.receiptId}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tthis.assertRootUnchanged(rootIdentity);\n\t\t\treturn { path: filePath, created: false };\n\t\t}\n\n\t\tlet fd: number;\n\t\ttry {\n\t\t\tfd = openSync(filePath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW, 0o600);\n\t\t} catch (error) {\n\t\t\tif (!isErrno(error, \"EEXIST\")) throw error;\n\t\t\tconst existing = this.read(validated.core.receiptId);\n\t\t\tif (serializeApprovalReceipt(existing) !== canonical) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`Approval receipt already exists with different content and is never overwritten: ${validated.core.receiptId}`,\n\t\t\t\t);\n\t\t\t}\n\t\t\tthis.assertRootUnchanged(rootIdentity);\n\t\t\treturn { path: filePath, created: false };\n\t\t}\n\n\t\ttry {\n\t\t\tfchmodSync(fd, 0o600);\n\t\t\tassertPrivateReceiptFd(fd, filePath);\n\t\t\twriteFileSync(fd, bytes);\n\t\t\tfsyncSync(fd);\n\t\t\tassertPrivateReceiptFd(fd, filePath);\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t\tthis.assertRootUnchanged(rootIdentity);\n\t\treturn { path: filePath, created: true };\n\t}\n\n\thas(receiptId: string): boolean {\n\t\tconst rootIdentity = this.ensurePrivateDirectory();\n\t\tlet fd: number;\n\t\ttry {\n\t\t\tfd = this.openReceiptForRead(this.pathFor(receiptId));\n\t\t} catch (error) {\n\t\t\tif (isErrno(error, \"ENOENT\")) {\n\t\t\t\tthis.assertRootUnchanged(rootIdentity);\n\t\t\t\treturn false;\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t\tcloseSync(fd);\n\t\tthis.assertRootUnchanged(rootIdentity);\n\t\treturn true;\n\t}\n\n\tread(receiptId: string): ApprovalReceipt {\n\t\tconst rootIdentity = this.ensurePrivateDirectory();\n\t\tconst filePath = this.pathFor(receiptId);\n\t\tconst fd = this.openReceiptForRead(filePath);\n\t\ttry {\n\t\t\treturn readReceiptFromFd(fd, filePath);\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t\tthis.assertRootUnchanged(rootIdentity);\n\t\t}\n\t}\n\n\tlistReceiptIds(): string[] {\n\t\tconst rootIdentity = this.ensurePrivateDirectory();\n\t\tconst ids = readdirSync(this.rootDir)\n\t\t\t.map((name) => /^(approval-[a-f0-9]{32})\\.json$/u.exec(name)?.[1])\n\t\t\t.filter((id): id is string => id !== undefined)\n\t\t\t.sort((left, right) => left.localeCompare(right));\n\t\tfor (const id of ids) this.has(id);\n\t\tthis.assertRootUnchanged(rootIdentity);\n\t\treturn ids;\n\t}\n}\n"]}

package/dist/approvals/approval-receipt.d.ts

@@ -0,0 +1,43 @@
+export type ApprovalDecision = "approved" | "rejected" | "invalidated";
+export interface ApprovalContentDigest {
+    sha256: string;
+    bytes: number;
+}
+export interface ApprovalPlanDigest extends ApprovalContentDigest {
+    path: string;
+}
+export interface ApprovalReceiptCore {
+    schemaVersion: 1;
+    receiptId: string;
+    provider: "plannotator";
+    trust: "external-extension-event";
+    requestId: string;
+    reviewId: string;
+    decision: ApprovalDecision;
+    decidedAt: string;
+    sessionId: string;
+    plan: ApprovalPlanDigest;
+    feedback?: ApprovalContentDigest;
+}
+export interface ApprovalReceipt {
+    core: ApprovalReceiptCore;
+    coreSha256: string;
+}
+export interface CreateApprovalReceiptInput {
+    provider: "plannotator";
+    requestId: string;
+    reviewId: string;
+    decision: ApprovalDecision;
+    decidedAt: string;
+    sessionId: string;
+    planPath: string;
+    planContent: string;
+    feedback?: string;
+}
+export declare function computeApprovalContentDigest(value: string): ApprovalContentDigest;
+export declare function computeApprovalReceiptCoreSha256(core: ApprovalReceiptCore): string;
+export declare function validateApprovalReceipt(value: unknown): ApprovalReceipt;
+export declare function createApprovalReceipt(input: CreateApprovalReceiptInput): ApprovalReceipt;
+export declare function parseApprovalReceipt(serialized: string): ApprovalReceipt;
+export declare function serializeApprovalReceipt(receipt: ApprovalReceipt): string;
+//# sourceMappingURL=approval-receipt.d.ts.map

package/dist/approvals/approval-receipt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-receipt.d.ts","sourceRoot":"","sources":["../../src/approvals/approval-receipt.ts"],"names":[],"mappings":"AAQA,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAC;AAEvE,MAAM,WAAW,qBAAqB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAChE,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,mBAAmB;IACnC,aAAa,EAAE,CAAC,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,aAAa,CAAC;IACxB,KAAK,EAAE,0BAA0B,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,kBAAkB,CAAC;IACzB,QAAQ,CAAC,EAAE,qBAAqB,CAAC;CACjC;AAED,MAAM,WAAW,eAAe;IAC/B,IAAI,EAAE,mBAAmB,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IAC1C,QAAQ,EAAE,aAAa,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAMD,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAEjF;AAyFD,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAElF;AAOD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CA8CvE;AAiBD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,0BAA0B,GAAG,eAAe,CAwBxF;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAQxE;AAED,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,eAAe,GAAG,MAAM,CAEzE","sourcesContent":["import { createHash, timingSafeEqual } from \"node:crypto\";\nimport { isAbsolute } from \"node:path\";\n\nconst SHA256_PATTERN = /^[a-f0-9]{64}$/u;\nconst SAFE_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9])?$/u;\nconst CORE_DOMAIN = \"omk.approval-receipt.core.v1\\0\";\nconst ID_DOMAIN = \"omk.approval-receipt.id.v1\\0\";\n\nexport type ApprovalDecision = \"approved\" | \"rejected\" | \"invalidated\";\n\nexport interface ApprovalContentDigest {\n\tsha256: string;\n\tbytes: number;\n}\n\nexport interface ApprovalPlanDigest extends ApprovalContentDigest {\n\tpath: string;\n}\n\nexport interface ApprovalReceiptCore {\n\tschemaVersion: 1;\n\treceiptId: string;\n\tprovider: \"plannotator\";\n\ttrust: \"external-extension-event\";\n\trequestId: string;\n\treviewId: string;\n\tdecision: ApprovalDecision;\n\tdecidedAt: string;\n\tsessionId: string;\n\tplan: ApprovalPlanDigest;\n\tfeedback?: ApprovalContentDigest;\n}\n\nexport interface ApprovalReceipt {\n\tcore: ApprovalReceiptCore;\n\tcoreSha256: string;\n}\n\nexport interface CreateApprovalReceiptInput {\n\tprovider: \"plannotator\";\n\trequestId: string;\n\treviewId: string;\n\tdecision: ApprovalDecision;\n\tdecidedAt: string;\n\tsessionId: string;\n\tplanPath: string;\n\tplanContent: string;\n\tfeedback?: string;\n}\n\nfunction sha256(domain: string, value: string): string {\n\treturn createHash(\"sha256\").update(domain).update(value, \"utf8\").digest(\"hex\");\n}\n\nexport function computeApprovalContentDigest(value: string): ApprovalContentDigest {\n\treturn { sha256: sha256(\"omk.approval-content.v1\\0\", value), bytes: Buffer.byteLength(value, \"utf8\") };\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction hasOwn(value: Record<string, unknown>, key: string): boolean {\n\treturn Object.getOwnPropertyDescriptor(value, key) !== undefined;\n}\n\nfunction exactKeys(value: Record<string, unknown>, required: string[], optional: string[] = []): void {\n\tconst allowed = new Set([...required, ...optional]);\n\tfor (const key of Object.keys(value)) {\n\t\tif (!allowed.has(key)) throw new Error(`Unexpected approval receipt field: ${key}`);\n\t}\n\tfor (const key of required) {\n\t\tif (!hasOwn(value, key)) throw new Error(`Missing approval receipt field: ${key}`);\n\t}\n}\n\nfunction safeId(value: unknown, label: string): string {\n\tif (typeof value !== \"string\" || !SAFE_ID_PATTERN.test(value)) throw new Error(`${label} is not a safe identifier`);\n\treturn value;\n}\n\nfunction sha256Hex(value: unknown, label: string): string {\n\tif (typeof value !== \"string\" || !SHA256_PATTERN.test(value)) throw new Error(`${label} must be lowercase SHA-256`);\n\treturn value;\n}\n\nfunction nonNegativeInteger(value: unknown, label: string): number {\n\tif (!Number.isSafeInteger(value) || (value as number) < 0)\n\t\tthrow new Error(`${label} must be a non-negative safe integer`);\n\treturn value as number;\n}\n\nfunction workspaceRelativePath(value: unknown): string {\n\tif (typeof value !== \"string\" || !value || value.includes(\"\\\\\") || value.includes(\"\\0\") || isAbsolute(value)) {\n\t\tthrow new Error(\"plan.path must be workspace-relative\");\n\t}\n\tconst segments = value.split(\"/\");\n\tif (segments.some((segment) => segment === \"\" || segment === \".\" || segment === \"..\")) {\n\t\tthrow new Error(\"plan.path must be workspace-relative\");\n\t}\n\treturn value;\n}\n\nfunction timestamp(value: unknown): string {\n\tif (typeof value !== \"string\") throw new Error(\"decidedAt must be an ISO timestamp\");\n\tconst parsed = new Date(value);\n\tif (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== value) {\n\t\tthrow new Error(\"decidedAt must be a canonical ISO timestamp\");\n\t}\n\treturn value;\n}\n\nfunction parseContentDigest(value: unknown, label: string): ApprovalContentDigest {\n\tif (!isRecord(value)) throw new Error(`${label} must be an object`);\n\texactKeys(value, [\"sha256\", \"bytes\"]);\n\treturn {\n\t\tsha256: sha256Hex(value.sha256, `${label}.sha256`),\n\t\tbytes: nonNegativeInteger(value.bytes, `${label}.bytes`),\n\t};\n}\n\nfunction parsePlan(value: unknown): ApprovalPlanDigest {\n\tif (!isRecord(value)) throw new Error(\"plan must be an object\");\n\texactKeys(value, [\"path\", \"sha256\", \"bytes\"]);\n\treturn {\n\t\tpath: workspaceRelativePath(value.path),\n\t\tsha256: sha256Hex(value.sha256, \"plan.sha256\"),\n\t\tbytes: nonNegativeInteger(value.bytes, \"plan.bytes\"),\n\t};\n}\n\nfunction canonicalJson(value: unknown): string {\n\tif (value === null || typeof value === \"boolean\" || typeof value === \"string\") return JSON.stringify(value);\n\tif (typeof value === \"number\") {\n\t\tif (!Number.isFinite(value)) throw new Error(\"Approval receipt contains a non-finite number\");\n\t\treturn JSON.stringify(value);\n\t}\n\tif (Array.isArray(value)) return `[${value.map(canonicalJson).join(\",\")}]`;\n\tif (!isRecord(value)) throw new Error(\"Approval receipt contains an unsupported value\");\n\treturn `{${Object.keys(value)\n\t\t.sort((left, right) => left.localeCompare(right))\n\t\t.map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)\n\t\t.join(\",\")}}`;\n}\n\nexport function computeApprovalReceiptCoreSha256(core: ApprovalReceiptCore): string {\n\treturn sha256(CORE_DOMAIN, canonicalJson(core));\n}\n\nfunction constantTimeEqual(left: string, right: string): boolean {\n\tif (!SHA256_PATTERN.test(left) || !SHA256_PATTERN.test(right)) return false;\n\treturn timingSafeEqual(Buffer.from(left, \"hex\"), Buffer.from(right, \"hex\"));\n}\n\nexport function validateApprovalReceipt(value: unknown): ApprovalReceipt {\n\tif (!isRecord(value)) throw new Error(\"Approval receipt must be an object\");\n\texactKeys(value, [\"core\", \"coreSha256\"]);\n\tif (!isRecord(value.core)) throw new Error(\"Approval receipt core must be an object\");\n\tconst coreValue = value.core;\n\texactKeys(\n\t\tcoreValue,\n\t\t[\n\t\t\t\"schemaVersion\",\n\t\t\t\"receiptId\",\n\t\t\t\"provider\",\n\t\t\t\"trust\",\n\t\t\t\"requestId\",\n\t\t\t\"reviewId\",\n\t\t\t\"decision\",\n\t\t\t\"decidedAt\",\n\t\t\t\"sessionId\",\n\t\t\t\"plan\",\n\t\t],\n\t\t[\"feedback\"],\n\t);\n\tif (coreValue.schemaVersion !== 1) throw new Error(\"Unsupported approval receipt schemaVersion\");\n\tif (coreValue.provider !== \"plannotator\") throw new Error(\"Unsupported approval provider\");\n\tif (coreValue.trust !== \"external-extension-event\") throw new Error(\"Invalid approval trust classification\");\n\tif (coreValue.decision !== \"approved\" && coreValue.decision !== \"rejected\" && coreValue.decision !== \"invalidated\") {\n\t\tthrow new Error(\"Invalid approval decision\");\n\t}\n\tconst core: ApprovalReceiptCore = {\n\t\tschemaVersion: 1,\n\t\treceiptId: safeId(coreValue.receiptId, \"receiptId\"),\n\t\tprovider: \"plannotator\",\n\t\ttrust: \"external-extension-event\",\n\t\trequestId: safeId(coreValue.requestId, \"requestId\"),\n\t\treviewId: safeId(coreValue.reviewId, \"reviewId\"),\n\t\tdecision: coreValue.decision,\n\t\tdecidedAt: timestamp(coreValue.decidedAt),\n\t\tsessionId: safeId(coreValue.sessionId, \"sessionId\"),\n\t\tplan: parsePlan(coreValue.plan),\n\t\t...(hasOwn(coreValue, \"feedback\") ? { feedback: parseContentDigest(coreValue.feedback, \"feedback\") } : {}),\n\t};\n\tconst expectedReceiptId = computeApprovalReceiptId(core);\n\tif (core.receiptId !== expectedReceiptId) throw new Error(\"Approval receipt id mismatch\");\n\tconst coreSha256 = sha256Hex(value.coreSha256, \"coreSha256\");\n\tconst expectedDigest = computeApprovalReceiptCoreSha256(core);\n\tif (!constantTimeEqual(coreSha256, expectedDigest)) throw new Error(\"Approval receipt digest mismatch\");\n\treturn { core, coreSha256 };\n}\n\nfunction computeApprovalReceiptId(\n\tcore: Omit<ApprovalReceiptCore, \"receiptId\" | \"decidedAt\" | \"decision\" | \"feedback\">,\n): string {\n\tconst identity = {\n\t\tschemaVersion: core.schemaVersion,\n\t\tprovider: core.provider,\n\t\ttrust: core.trust,\n\t\trequestId: core.requestId,\n\t\treviewId: core.reviewId,\n\t\tsessionId: core.sessionId,\n\t\tplan: core.plan,\n\t};\n\treturn `approval-${sha256(ID_DOMAIN, canonicalJson(identity)).slice(0, 32)}`;\n}\n\nexport function createApprovalReceipt(input: CreateApprovalReceiptInput): ApprovalReceipt {\n\tconst plan: ApprovalPlanDigest = {\n\t\tpath: workspaceRelativePath(input.planPath),\n\t\t...computeApprovalContentDigest(input.planContent),\n\t};\n\tconst coreWithoutId = {\n\t\tschemaVersion: 1 as const,\n\t\tprovider: input.provider,\n\t\ttrust: \"external-extension-event\" as const,\n\t\trequestId: safeId(input.requestId, \"requestId\"),\n\t\treviewId: safeId(input.reviewId, \"reviewId\"),\n\t\tdecision: input.decision,\n\t\tdecidedAt: timestamp(input.decidedAt),\n\t\tsessionId: safeId(input.sessionId, \"sessionId\"),\n\t\tplan,\n\t\t...(input.feedback !== undefined && input.feedback.length > 0\n\t\t\t? { feedback: computeApprovalContentDigest(input.feedback) }\n\t\t\t: {}),\n\t};\n\tconst core: ApprovalReceiptCore = {\n\t\t...coreWithoutId,\n\t\treceiptId: computeApprovalReceiptId(coreWithoutId),\n\t};\n\treturn validateApprovalReceipt({ core, coreSha256: computeApprovalReceiptCoreSha256(core) });\n}\n\nexport function parseApprovalReceipt(serialized: string): ApprovalReceipt {\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(serialized) as unknown;\n\t} catch {\n\t\tthrow new Error(\"Approval receipt is not valid JSON\");\n\t}\n\treturn validateApprovalReceipt(parsed);\n}\n\nexport function serializeApprovalReceipt(receipt: ApprovalReceipt): string {\n\treturn `${JSON.stringify(validateApprovalReceipt(receipt), null, 2)}\\n`;\n}\n"]}

package/dist/approvals/approval-receipt.js

@@ -0,0 +1,208 @@
+import { createHash, timingSafeEqual } from "node:crypto";
+import { isAbsolute } from "node:path";
+const SHA256_PATTERN = /^[a-f0-9]{64}$/u;
+const SAFE_ID_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9])?$/u;
+const CORE_DOMAIN = "omk.approval-receipt.core.v1\0";
+const ID_DOMAIN = "omk.approval-receipt.id.v1\0";
+function sha256(domain, value) {
+    return createHash("sha256").update(domain).update(value, "utf8").digest("hex");
+}
+export function computeApprovalContentDigest(value) {
+    return { sha256: sha256("omk.approval-content.v1\0", value), bytes: Buffer.byteLength(value, "utf8") };
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(value, key) {
+    return Object.getOwnPropertyDescriptor(value, key) !== undefined;
+}
+function exactKeys(value, required, optional = []) {
+    const allowed = new Set([...required, ...optional]);
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key))
+            throw new Error(`Unexpected approval receipt field: ${key}`);
+    }
+    for (const key of required) {
+        if (!hasOwn(value, key))
+            throw new Error(`Missing approval receipt field: ${key}`);
+    }
+}
+function safeId(value, label) {
+    if (typeof value !== "string" || !SAFE_ID_PATTERN.test(value))
+        throw new Error(`${label} is not a safe identifier`);
+    return value;
+}
+function sha256Hex(value, label) {
+    if (typeof value !== "string" || !SHA256_PATTERN.test(value))
+        throw new Error(`${label} must be lowercase SHA-256`);
+    return value;
+}
+function nonNegativeInteger(value, label) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new Error(`${label} must be a non-negative safe integer`);
+    return value;
+}
+function workspaceRelativePath(value) {
+    if (typeof value !== "string" || !value || value.includes("\\") || value.includes("\0") || isAbsolute(value)) {
+        throw new Error("plan.path must be workspace-relative");
+    }
+    const segments = value.split("/");
+    if (segments.some((segment) => segment === "" || segment === "." || segment === "..")) {
+        throw new Error("plan.path must be workspace-relative");
+    }
+    return value;
+}
+function timestamp(value) {
+    if (typeof value !== "string")
+        throw new Error("decidedAt must be an ISO timestamp");
+    const parsed = new Date(value);
+    if (!Number.isFinite(parsed.getTime()) || parsed.toISOString() !== value) {
+        throw new Error("decidedAt must be a canonical ISO timestamp");
+    }
+    return value;
+}
+function parseContentDigest(value, label) {
+    if (!isRecord(value))
+        throw new Error(`${label} must be an object`);
+    exactKeys(value, ["sha256", "bytes"]);
+    return {
+        sha256: sha256Hex(value.sha256, `${label}.sha256`),
+        bytes: nonNegativeInteger(value.bytes, `${label}.bytes`),
+    };
+}
+function parsePlan(value) {
+    if (!isRecord(value))
+        throw new Error("plan must be an object");
+    exactKeys(value, ["path", "sha256", "bytes"]);
+    return {
+        path: workspaceRelativePath(value.path),
+        sha256: sha256Hex(value.sha256, "plan.sha256"),
+        bytes: nonNegativeInteger(value.bytes, "plan.bytes"),
+    };
+}
+function canonicalJson(value) {
+    if (value === null || typeof value === "boolean" || typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("Approval receipt contains a non-finite number");
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (!isRecord(value))
+        throw new Error("Approval receipt contains an unsupported value");
+    return `{${Object.keys(value)
+        .sort((left, right) => left.localeCompare(right))
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+        .join(",")}}`;
+}
+export function computeApprovalReceiptCoreSha256(core) {
+    return sha256(CORE_DOMAIN, canonicalJson(core));
+}
+function constantTimeEqual(left, right) {
+    if (!SHA256_PATTERN.test(left) || !SHA256_PATTERN.test(right))
+        return false;
+    return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
+}
+export function validateApprovalReceipt(value) {
+    if (!isRecord(value))
+        throw new Error("Approval receipt must be an object");
+    exactKeys(value, ["core", "coreSha256"]);
+    if (!isRecord(value.core))
+        throw new Error("Approval receipt core must be an object");
+    const coreValue = value.core;
+    exactKeys(coreValue, [
+        "schemaVersion",
+        "receiptId",
+        "provider",
+        "trust",
+        "requestId",
+        "reviewId",
+        "decision",
+        "decidedAt",
+        "sessionId",
+        "plan",
+    ], ["feedback"]);
+    if (coreValue.schemaVersion !== 1)
+        throw new Error("Unsupported approval receipt schemaVersion");
+    if (coreValue.provider !== "plannotator")
+        throw new Error("Unsupported approval provider");
+    if (coreValue.trust !== "external-extension-event")
+        throw new Error("Invalid approval trust classification");
+    if (coreValue.decision !== "approved" && coreValue.decision !== "rejected" && coreValue.decision !== "invalidated") {
+        throw new Error("Invalid approval decision");
+    }
+    const core = {
+        schemaVersion: 1,
+        receiptId: safeId(coreValue.receiptId, "receiptId"),
+        provider: "plannotator",
+        trust: "external-extension-event",
+        requestId: safeId(coreValue.requestId, "requestId"),
+        reviewId: safeId(coreValue.reviewId, "reviewId"),
+        decision: coreValue.decision,
+        decidedAt: timestamp(coreValue.decidedAt),
+        sessionId: safeId(coreValue.sessionId, "sessionId"),
+        plan: parsePlan(coreValue.plan),
+        ...(hasOwn(coreValue, "feedback") ? { feedback: parseContentDigest(coreValue.feedback, "feedback") } : {}),
+    };
+    const expectedReceiptId = computeApprovalReceiptId(core);
+    if (core.receiptId !== expectedReceiptId)
+        throw new Error("Approval receipt id mismatch");
+    const coreSha256 = sha256Hex(value.coreSha256, "coreSha256");
+    const expectedDigest = computeApprovalReceiptCoreSha256(core);
+    if (!constantTimeEqual(coreSha256, expectedDigest))
+        throw new Error("Approval receipt digest mismatch");
+    return { core, coreSha256 };
+}
+function computeApprovalReceiptId(core) {
+    const identity = {
+        schemaVersion: core.schemaVersion,
+        provider: core.provider,
+        trust: core.trust,
+        requestId: core.requestId,
+        reviewId: core.reviewId,
+        sessionId: core.sessionId,
+        plan: core.plan,
+    };
+    return `approval-${sha256(ID_DOMAIN, canonicalJson(identity)).slice(0, 32)}`;
+}
+export function createApprovalReceipt(input) {
+    const plan = {
+        path: workspaceRelativePath(input.planPath),
+        ...computeApprovalContentDigest(input.planContent),
+    };
+    const coreWithoutId = {
+        schemaVersion: 1,
+        provider: input.provider,
+        trust: "external-extension-event",
+        requestId: safeId(input.requestId, "requestId"),
+        reviewId: safeId(input.reviewId, "reviewId"),
+        decision: input.decision,
+        decidedAt: timestamp(input.decidedAt),
+        sessionId: safeId(input.sessionId, "sessionId"),
+        plan,
+        ...(input.feedback !== undefined && input.feedback.length > 0
+            ? { feedback: computeApprovalContentDigest(input.feedback) }
+            : {}),
+    };
+    const core = {
+        ...coreWithoutId,
+        receiptId: computeApprovalReceiptId(coreWithoutId),
+    };
+    return validateApprovalReceipt({ core, coreSha256: computeApprovalReceiptCoreSha256(core) });
+}
+export function parseApprovalReceipt(serialized) {
+    let parsed;
+    try {
+        parsed = JSON.parse(serialized);
+    }
+    catch {
+        throw new Error("Approval receipt is not valid JSON");
+    }
+    return validateApprovalReceipt(parsed);
+}
+export function serializeApprovalReceipt(receipt) {
+    return `${JSON.stringify(validateApprovalReceipt(receipt), null, 2)}\n`;
+}
+//# sourceMappingURL=approval-receipt.js.map