@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

package/dist/shared/filereview/cas-substrate.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Content-addressed snapshot/restore substrate for the apply-then-review HITL
+ * subsystem — the sibling of {@link ./git-substrate.js} for paths git cannot
+ * snapshot (`.gitignored` and non-git files). It closes the "gap" the git
+ * substrate documents at its top: shell/MCP and gitignored writes are not
+ * reversible by git, so today they stay on the deny-gate; this module makes
+ * gitignored / non-git file edits capturable, reviewable, and reversible.
+ *
+ * THE MODEL (mirrors the git substrate, different storage domain)
+ * --------------------------------------------------------------
+ * The git substrate snapshots the whole working tree at the turn boundary and
+ * diffs two pinned tree objects. CAS cannot do that: git does not see ignored
+ * paths, and a plain directory has no history to recover a pre-edit byte from.
+ * So the CAS substrate is fed the exact before/after bytes of each touched path
+ * (captured by the harness at mutation time — the deep-agent's
+ * CasCaptureFilesystemBackend, or the Cursor hook staging the file before it
+ * allows the write) and:
+ *
+ *  1. Stores each distinct before/after body as a CONTENT-ADDRESSED blob under
+ *     `artifacts/{executionId}/filereview/cas/blobs/{sha256}` (deduped by hash,
+ *     idempotent), reusing the existing {@link ArtifactStorage} — no new store.
+ *  2. Writes a per-change-set MANIFEST (path -> before/after blob refs) under
+ *     `artifacts/{executionId}/filereview/cas/{changeSetId}.manifest.json`. The
+ *     manifest is the durable, authoritative source for the resume-time
+ *     reconcile — the CAS analogue of the git substrate's pinned refs.
+ *  3. On resume, reconciles the workspace to the user's per-file decisions
+ *     sourced ENTIRELY from the manifest: approved files are written to their
+ *     "after" bytes; rejected/undecided files are snapped back to their "before"
+ *     bytes (or removed, for a rejected create). Symmetric and idempotent.
+ *
+ * DURABILITY DOMAIN (design doc 11 D3)
+ * -----------------------------------
+ * Unlike git refs, which live inside the repo, CAS blobs + manifests live in
+ * artifact storage (a fixed host path in OSS, R2 via the proxy in Cloud) — a
+ * DIFFERENT durability domain that must outlive the multi-day approval wait and
+ * a sandbox recycle. Because reconcile reads only from the manifest + blobs
+ * (never the live tree), it converges regardless of the tree's current state,
+ * so a Temporal retry or a recycled workspace is harmless.
+ *
+ * WHAT THIS MODULE IS NOT
+ * -----------------------
+ * It is harness-agnostic and wiring-agnostic: it takes explicit before/after
+ * bytes, never reads gitignore, never talks to a hook. WHICH paths flow here (vs
+ * stay on the deny-gate or block as DIFF_UNREVIEWABLE), and the secret-safety
+ * gate (design doc 12), are the harness adapter's concern, applied BEFORE bytes
+ * reach this module. This module never persists a path it is not given.
+ *
+ * @since File-Change HITL Redesign (Phase 3 — CAS)
+ */
+import { FileCaptureClass, FileChangeKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { ArtifactStorage } from "../artifact-storage.js";
+/**
+ * Reads an artifact's raw bytes back by storage key. Injected so this module
+ * stays free of HTTP/transport concerns and is trivially testable; production
+ * callers build one with {@link casBlobReader}.
+ */
+export type BlobReader = (storageKey: string) => Promise<Buffer>;
+/** A stored, content-addressed blob and where to find it. */
+export interface CasBlobRef {
+    /** Lowercase-hex SHA-256 of the bytes (the content address + enforcement digest). */
+    readonly sha256: string;
+    /** Artifact-storage key the bytes live under. */
+    readonly storageKey: string;
+    readonly sizeBytes: number;
+    /** A NUL byte was present — the diff cannot render as text (blocks COMPLETE). */
+    readonly isBinary: boolean;
+}
+/** One captured file within a CAS change set (before/after blob refs). */
+export interface CasCapturedFile {
+    /** Path before the change (workspace-relative). Empty for ADD. */
+    readonly pathBefore: string;
+    /** Path after the change. Empty for DELETE. */
+    readonly pathAfter: string;
+    readonly kind: FileChangeKind;
+    /** Which substrate class captured it (GIT_IGNORED_CAPTURED | NON_GIT_CAS). */
+    readonly captureClass: FileCaptureClass;
+    /** Pre-edit blob; absent for ADD. */
+    readonly before?: CasBlobRef;
+    /** Post-edit blob; absent for DELETE. */
+    readonly after?: CasBlobRef;
+    /** False when a side is binary — the change set cannot be approved as complete. */
+    readonly diffComplete: boolean;
+}
+/** The durable manifest for one change set — the reconcile's source of truth. */
+export interface CasManifest {
+    readonly changeSetId: string;
+    readonly files: readonly CasCapturedFile[];
+}
+/** A pointer to a persisted {@link CasManifest} (mirrors the proto CasManifestRef). */
+export interface CasSnapshotRef {
+    /** SHA-256 over the canonical manifest JSON (tamper/integrity check). */
+    readonly manifestDigest: string;
+    /** Artifact-storage key the manifest JSON lives under. */
+    readonly artifactUri: string;
+}
+/** The before/after bytes of one path the harness captured this turn. */
+export interface CasPathCapture {
+    /** Workspace-root-relative path. */
+    readonly path: string;
+    /** Pre-edit bytes; `null` when the file did not exist before (an ADD). */
+    readonly before: Uint8Array | null;
+    /** Post-edit bytes; `null` when the file was removed (a DELETE). */
+    readonly after: Uint8Array | null;
+    /** Which substrate class this path belongs to (for the ledger). */
+    readonly captureClass: FileCaptureClass;
+}
+/** The CAS blob key for a content hash, under the execution's artifact prefix. */
+export declare function casBlobKey(executionId: string, sha256: string): string;
+/**
+ * The manifest key for a change set. The change-set id (`{exec}:{turnSeq}`)
+ * carries a colon; it is sanitized to a filesystem/object-store-safe segment so
+ * the key is portable across the local FS and R2 backends.
+ */
+export declare function casManifestKey(executionId: string, changeSetId: string): string;
+/**
+ * Capture a CAS change set: store every distinct before/after body as a
+ * content-addressed blob (deduped, idempotent), assemble the per-file manifest,
+ * persist it, and return the manifest plus its ref for the ledger's SnapshotRef.
+ *
+ * Captures whose before and after bytes are byte-identical (a path touched but
+ * left unchanged) are dropped — they are not a reviewable change, exactly as the
+ * git substrate's diff omits unchanged files.
+ */
+export declare function snapshotCasChangeSet(opts: {
+    readonly storage: ArtifactStorage;
+    readonly executionId: string;
+    readonly changeSetId: string;
+    readonly captures: readonly CasPathCapture[];
+}): Promise<{
+    manifest: CasManifest;
+    ref: CasSnapshotRef;
+}>;
+/**
+ * Load a change set's CAS manifest for the resume-time reconcile, digest-verified
+ * against the ledger's {@link CasSnapshotRef}.
+ *
+ * Called ONLY when the caller has already determined this turn captured CAS files
+ * — from the change set's CANDIDATE snapshot (the ledger's record of the
+ * substrate), never by probing storage. The ref is the whole contract: the
+ * manifest is fetched from the exact `artifactUri` the CANDIDATE event recorded
+ * (not a re-derived key, so a pending change set survives any future key-scheme
+ * change), and the downloaded bytes must hash to `manifestDigest` before they are
+ * trusted. Per-blob content addresses protect blob BODIES, but only this check
+ * protects the path→blob mapping itself — a corrupted or swapped manifest could
+ * otherwise direct a valid blob to the wrong path.
+ *
+ * Fail-closed: a missing manifest (surfaced by the reader) or a digest mismatch
+ * is a genuine integrity error, never a "this was a git-only turn" signal.
+ * (Deciding the substrate from storage existence was unsafe: a presigned/proxy
+ * backend cannot answer "does this key exist?" reliably, and a git-only turn —
+ * which writes no manifest — would then attempt a doomed download.)
+ */
+export declare function loadCasManifest(opts: {
+    readonly readBlob: BlobReader;
+    readonly ref: CasSnapshotRef;
+}): Promise<CasManifest>;
+/**
+ * Ensure the APPROVED files hold their captured "after" bytes on disk. An
+ * approved CREATE/MODIFY writes the after blob (integrity-checked against its
+ * content address); an approved DELETE removes the file. Idempotent — re-running
+ * converges (the after blob is immutable), so a Temporal retry is safe.
+ *
+ * Enforcement ("what you approve is what applies"): the downloaded bytes must
+ * still hash to the blob's content address; a mismatch (storage corruption)
+ * throws rather than writing wrong bytes.
+ */
+export declare function applyCasApproved(opts: {
+    readonly readBlob: BlobReader;
+    readonly workspaceRoot: string;
+    readonly files: readonly CasCapturedFile[];
+}): Promise<void>;
+/**
+ * Snap the REJECTED/undecided files back to their captured "before" bytes: a
+ * rejected CREATE is removed; a rejected MODIFY/DELETE is rewritten with its
+ * before blob. Idempotent, and the byte-exact inverse of {@link applyCasApproved}.
+ */
+export declare function restoreCasToBaseline(opts: {
+    readonly readBlob: BlobReader;
+    readonly workspaceRoot: string;
+    readonly files: readonly CasCapturedFile[];
+}): Promise<void>;
+/**
+ * Adapt the artifact storage port's {@link ArtifactStorage.download} into a
+ * {@link BlobReader}. The seam is retained so the reconcile functions
+ * ({@link loadCasManifest}, {@link applyCasApproved}, {@link restoreCasToBaseline})
+ * depend only on "read one blob by key", not on the whole storage interface.
+ * `download` already throws a descriptive, key-scoped error on a missing blob or
+ * transport failure, so no extra wrapping is needed here.
+ */
+export declare function casBlobReader(storage: ArtifactStorage): BlobReader;

package/dist/shared/filereview/cas-substrate.js

@@ -0,0 +1,284 @@
+/**
+ * Content-addressed snapshot/restore substrate for the apply-then-review HITL
+ * subsystem — the sibling of {@link ./git-substrate.js} for paths git cannot
+ * snapshot (`.gitignored` and non-git files). It closes the "gap" the git
+ * substrate documents at its top: shell/MCP and gitignored writes are not
+ * reversible by git, so today they stay on the deny-gate; this module makes
+ * gitignored / non-git file edits capturable, reviewable, and reversible.
+ *
+ * THE MODEL (mirrors the git substrate, different storage domain)
+ * --------------------------------------------------------------
+ * The git substrate snapshots the whole working tree at the turn boundary and
+ * diffs two pinned tree objects. CAS cannot do that: git does not see ignored
+ * paths, and a plain directory has no history to recover a pre-edit byte from.
+ * So the CAS substrate is fed the exact before/after bytes of each touched path
+ * (captured by the harness at mutation time — the deep-agent's
+ * CasCaptureFilesystemBackend, or the Cursor hook staging the file before it
+ * allows the write) and:
+ *
+ *  1. Stores each distinct before/after body as a CONTENT-ADDRESSED blob under
+ *     `artifacts/{executionId}/filereview/cas/blobs/{sha256}` (deduped by hash,
+ *     idempotent), reusing the existing {@link ArtifactStorage} — no new store.
+ *  2. Writes a per-change-set MANIFEST (path -> before/after blob refs) under
+ *     `artifacts/{executionId}/filereview/cas/{changeSetId}.manifest.json`. The
+ *     manifest is the durable, authoritative source for the resume-time
+ *     reconcile — the CAS analogue of the git substrate's pinned refs.
+ *  3. On resume, reconciles the workspace to the user's per-file decisions
+ *     sourced ENTIRELY from the manifest: approved files are written to their
+ *     "after" bytes; rejected/undecided files are snapped back to their "before"
+ *     bytes (or removed, for a rejected create). Symmetric and idempotent.
+ *
+ * DURABILITY DOMAIN (design doc 11 D3)
+ * -----------------------------------
+ * Unlike git refs, which live inside the repo, CAS blobs + manifests live in
+ * artifact storage (a fixed host path in OSS, R2 via the proxy in Cloud) — a
+ * DIFFERENT durability domain that must outlive the multi-day approval wait and
+ * a sandbox recycle. Because reconcile reads only from the manifest + blobs
+ * (never the live tree), it converges regardless of the tree's current state,
+ * so a Temporal retry or a recycled workspace is harmless.
+ *
+ * WHAT THIS MODULE IS NOT
+ * -----------------------
+ * It is harness-agnostic and wiring-agnostic: it takes explicit before/after
+ * bytes, never reads gitignore, never talks to a hook. WHICH paths flow here (vs
+ * stay on the deny-gate or block as DIFF_UNREVIEWABLE), and the secret-safety
+ * gate (design doc 12), are the harness adapter's concern, applied BEFORE bytes
+ * reach this module. This module never persists a path it is not given.
+ *
+ * @since File-Change HITL Redesign (Phase 3 — CAS)
+ */
+import { mkdir, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { FileChangeKind, } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { bytesLookBinary } from "../file-change.js";
+import { sha256Bytes, sha256Hex } from "./digest.js";
+// ---------------------------------------------------------------------------
+// Key namespace (design doc 08: execution-scoped, reuse existing authz)
+// ---------------------------------------------------------------------------
+/** The CAS blob key for a content hash, under the execution's artifact prefix. */
+export function casBlobKey(executionId, sha256) {
+    return `artifacts/${executionId}/filereview/cas/blobs/${sha256}`;
+}
+/**
+ * The manifest key for a change set. The change-set id (`{exec}:{turnSeq}`)
+ * carries a colon; it is sanitized to a filesystem/object-store-safe segment so
+ * the key is portable across the local FS and R2 backends.
+ */
+export function casManifestKey(executionId, changeSetId) {
+    const safe = changeSetId.replace(/[^A-Za-z0-9._-]/g, "_");
+    return `artifacts/${executionId}/filereview/cas/${safe}.manifest.json`;
+}
+// ---------------------------------------------------------------------------
+// Capture
+// ---------------------------------------------------------------------------
+/**
+ * Capture a CAS change set: store every distinct before/after body as a
+ * content-addressed blob (deduped, idempotent), assemble the per-file manifest,
+ * persist it, and return the manifest plus its ref for the ledger's SnapshotRef.
+ *
+ * Captures whose before and after bytes are byte-identical (a path touched but
+ * left unchanged) are dropped — they are not a reviewable change, exactly as the
+ * git substrate's diff omits unchanged files.
+ */
+export async function snapshotCasChangeSet(opts) {
+    const { storage, executionId, changeSetId, captures } = opts;
+    const files = [];
+    for (const capture of captures) {
+        const file = await buildCasCapturedFile(storage, executionId, capture);
+        if (file)
+            files.push(file);
+    }
+    // Deterministic order (by after path, then before path) so the manifest digest
+    // is stable and, later, composes with the git manifest into one aggregate
+    // digest that is byte-identical across editions (design doc 08 D3).
+    files.sort(compareByPath);
+    const manifest = { changeSetId, files };
+    const canonical = canonicalManifestJson(manifest);
+    const manifestKey = casManifestKey(executionId, changeSetId);
+    await storage.upload(manifestKey, Buffer.from(canonical, "utf8"), "application/json");
+    return {
+        manifest,
+        ref: { manifestDigest: sha256Hex(canonical), artifactUri: manifestKey },
+    };
+}
+/**
+ * Store one path's before/after blobs and classify the change. Returns
+ * `undefined` for a no-op (both sides absent, or an unchanged touch).
+ */
+async function buildCasCapturedFile(storage, executionId, capture) {
+    const { path, before, after, captureClass } = capture;
+    if (before === null && after === null)
+        return undefined;
+    const beforeBuf = before === null ? null : Buffer.from(before);
+    const afterBuf = after === null ? null : Buffer.from(after);
+    // A touch that did not change the bytes is not a reviewable change.
+    if (beforeBuf && afterBuf && beforeBuf.equals(afterBuf))
+        return undefined;
+    const beforeRef = beforeBuf ? await storeBlob(storage, executionId, beforeBuf) : undefined;
+    const afterRef = afterBuf ? await storeBlob(storage, executionId, afterBuf) : undefined;
+    const kind = beforeRef === undefined
+        ? FileChangeKind.ADD
+        : afterRef === undefined
+            ? FileChangeKind.DELETE
+            : FileChangeKind.MODIFY;
+    const isCreate = kind === FileChangeKind.ADD;
+    const isDelete = kind === FileChangeKind.DELETE;
+    return {
+        pathBefore: isCreate ? "" : path,
+        pathAfter: isDelete ? "" : path,
+        kind,
+        captureClass,
+        before: beforeRef,
+        after: afterRef,
+        // Binary on either side means the diff cannot render as text; the change set
+        // then cannot be approved as complete (parity with the git substrate).
+        diffComplete: !(beforeRef?.isBinary || afterRef?.isBinary),
+    };
+}
+/** Upload bytes under their content-address, skipping the write when present. */
+async function storeBlob(storage, executionId, bytes) {
+    const sha256 = sha256Bytes(bytes);
+    const storageKey = casBlobKey(executionId, sha256);
+    // Content-addressed: identical bytes yield the same key, so an existing blob
+    // is never re-uploaded (idempotent under Temporal retries + intra-turn dedup).
+    if (!(await storage.exists(storageKey))) {
+        await storage.upload(storageKey, bytes, "application/octet-stream");
+    }
+    return { sha256, storageKey, sizeBytes: bytes.length, isBinary: bytesLookBinary(bytes) };
+}
+// ---------------------------------------------------------------------------
+// Resume: load + reconcile
+// ---------------------------------------------------------------------------
+/**
+ * Load a change set's CAS manifest for the resume-time reconcile, digest-verified
+ * against the ledger's {@link CasSnapshotRef}.
+ *
+ * Called ONLY when the caller has already determined this turn captured CAS files
+ * — from the change set's CANDIDATE snapshot (the ledger's record of the
+ * substrate), never by probing storage. The ref is the whole contract: the
+ * manifest is fetched from the exact `artifactUri` the CANDIDATE event recorded
+ * (not a re-derived key, so a pending change set survives any future key-scheme
+ * change), and the downloaded bytes must hash to `manifestDigest` before they are
+ * trusted. Per-blob content addresses protect blob BODIES, but only this check
+ * protects the path→blob mapping itself — a corrupted or swapped manifest could
+ * otherwise direct a valid blob to the wrong path.
+ *
+ * Fail-closed: a missing manifest (surfaced by the reader) or a digest mismatch
+ * is a genuine integrity error, never a "this was a git-only turn" signal.
+ * (Deciding the substrate from storage existence was unsafe: a presigned/proxy
+ * backend cannot answer "does this key exist?" reliably, and a git-only turn —
+ * which writes no manifest — would then attempt a doomed download.)
+ */
+export async function loadCasManifest(opts) {
+    const { readBlob, ref } = opts;
+    const bytes = await readBlob(ref.artifactUri);
+    const actual = sha256Bytes(bytes);
+    if (actual !== ref.manifestDigest) {
+        throw new Error(`CAS manifest integrity check failed for '${ref.artifactUri}': ` +
+            `expected ${ref.manifestDigest}, got ${actual}`);
+    }
+    return JSON.parse(bytes.toString("utf8"));
+}
+/**
+ * Ensure the APPROVED files hold their captured "after" bytes on disk. An
+ * approved CREATE/MODIFY writes the after blob (integrity-checked against its
+ * content address); an approved DELETE removes the file. Idempotent — re-running
+ * converges (the after blob is immutable), so a Temporal retry is safe.
+ *
+ * Enforcement ("what you approve is what applies"): the downloaded bytes must
+ * still hash to the blob's content address; a mismatch (storage corruption)
+ * throws rather than writing wrong bytes.
+ */
+export async function applyCasApproved(opts) {
+    const { readBlob, workspaceRoot, files } = opts;
+    for (const file of files) {
+        if (file.kind === FileChangeKind.DELETE) {
+            await rm(join(workspaceRoot, file.pathBefore), { force: true });
+            continue;
+        }
+        // CREATE or MODIFY: write the approved after bytes.
+        if (!file.after)
+            continue;
+        await writeVerifiedBlob(readBlob, join(workspaceRoot, file.pathAfter), file.after);
+    }
+}
+/**
+ * Snap the REJECTED/undecided files back to their captured "before" bytes: a
+ * rejected CREATE is removed; a rejected MODIFY/DELETE is rewritten with its
+ * before blob. Idempotent, and the byte-exact inverse of {@link applyCasApproved}.
+ */
+export async function restoreCasToBaseline(opts) {
+    const { readBlob, workspaceRoot, files } = opts;
+    for (const file of files) {
+        if (file.kind === FileChangeKind.ADD) {
+            // The file did not exist before this turn — remove the agent's creation.
+            await rm(join(workspaceRoot, file.pathAfter), { force: true });
+            continue;
+        }
+        // MODIFY or DELETE: the baseline holds the file — restore its exact bytes.
+        if (!file.before)
+            continue;
+        await writeVerifiedBlob(readBlob, join(workspaceRoot, file.pathBefore), file.before);
+    }
+}
+/**
+ * Adapt the artifact storage port's {@link ArtifactStorage.download} into a
+ * {@link BlobReader}. The seam is retained so the reconcile functions
+ * ({@link loadCasManifest}, {@link applyCasApproved}, {@link restoreCasToBaseline})
+ * depend only on "read one blob by key", not on the whole storage interface.
+ * `download` already throws a descriptive, key-scoped error on a missing blob or
+ * transport failure, so no extra wrapping is needed here.
+ */
+export function casBlobReader(storage) {
+    return (storageKey) => storage.download(storageKey);
+}
+// ---------------------------------------------------------------------------
+// Internals
+// ---------------------------------------------------------------------------
+/** Download a blob, verify its content address, and write it to `abs`. */
+async function writeVerifiedBlob(readBlob, abs, ref) {
+    const bytes = await readBlob(ref.storageKey);
+    const actual = sha256Bytes(bytes);
+    if (actual !== ref.sha256) {
+        throw new Error(`CAS blob integrity check failed for '${ref.storageKey}': ` +
+            `expected ${ref.sha256}, got ${actual}`);
+    }
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, bytes);
+}
+/** Stable order: by after path, then before path (substrate-agnostic, doc 08 D3). */
+function compareByPath(a, b) {
+    const ka = a.pathAfter || a.pathBefore;
+    const kb = b.pathAfter || b.pathBefore;
+    if (ka < kb)
+        return -1;
+    if (ka > kb)
+        return 1;
+    return a.pathBefore < b.pathBefore ? -1 : a.pathBefore > b.pathBefore ? 1 : 0;
+}
+/** Serialize a blob ref fully so the persisted manifest round-trips faithfully. */
+function serializeBlob(b) {
+    return b
+        ? { sha256: b.sha256, storageKey: b.storageKey, sizeBytes: b.sizeBytes, isBinary: b.isBinary }
+        : null;
+}
+/**
+ * The canonical JSON the manifest is BOTH persisted as and digested over: files
+ * in sorted order with a fixed key order, blob refs serialized in full (incl.
+ * `storageKey`) so a reloaded manifest is a faithful {@link CasManifest} the
+ * resume reconcile can read directly. Every field is deterministic, so the digest
+ * is a stable integrity check over the exact stored bytes.
+ */
+function canonicalManifestJson(manifest) {
+    const files = manifest.files.map((f) => ({
+        pathBefore: f.pathBefore,
+        pathAfter: f.pathAfter,
+        kind: f.kind,
+        captureClass: f.captureClass,
+        before: serializeBlob(f.before),
+        after: serializeBlob(f.after),
+        diffComplete: f.diffComplete,
+    }));
+    return JSON.stringify({ changeSetId: manifest.changeSetId, files });
+}
+//# sourceMappingURL=cas-substrate.js.map

package/dist/shared/filereview/cas-substrate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cas-substrate.js","sourceRoot":"","sources":["../../../src/shared/filereview/cas-substrate.ts"],"names":[],"mappings":"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"}

package/dist/shared/filereview/digest.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Canonical file-review digests — the runner-side mirror of the Go
+ * {@code filereview/digest.go} and the Java {@code FileDigest}, locked
+ * byte-for-byte by `apis/testdata/hitl/file-digest/vectors.json`.
+ *
+ * These are ENFORCEMENT digests, never correlation keys: the reconcile refuses
+ * to apply content whose digest differs from what the user approved. The runner
+ * is the sole producer of `before_sha256`/`after_sha256` (over the exact captured
+ * bytes) and of the derived `file_digest`/`aggregate_digest`; the backends only
+ * carry them. Keeping the formula identical across all three editions is what
+ * lets the cross-edition corpus prove parity.
+ */
+import { FileChangeKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+/** The proto enum value name for a FileChangeKind (for the digest canonical form). */
+export declare function fileChangeKindName(kind: FileChangeKind): string;
+/** Lowercase-hex SHA-256 of a UTF-8 string. */
+export declare function sha256Hex(s: string): string;
+/** Lowercase-hex SHA-256 of raw bytes — used for `before_sha256`/`after_sha256`. */
+export declare function sha256Bytes(bytes: Uint8Array): string;
+/** The identity+content fields a {@link fileDigest} is computed over. */
+export interface FileDigestInput {
+    readonly pathBefore: string;
+    readonly pathAfter: string;
+    readonly kind: FileChangeKind;
+    readonly beforeSha256: string;
+    readonly afterSha256: string;
+}
+/**
+ * The canonical per-file digest:
+ * `sha256(join("\n", [path_before, path_after, kind_name, before_sha256, after_sha256]))`.
+ * Digesting the content HASHES (not raw bytes) keeps the string pure ASCII, free
+ * of any line-ending or encoding ambiguity across editions.
+ */
+export declare function fileDigest(input: FileDigestInput): string;
+/**
+ * The canonical change-set digest: `sha256(join("\n", sort_ascending(file_digests)))`.
+ * Sorting makes it independent of file order (a change set is an unordered set of
+ * files for identity). The empty set hashes the empty string.
+ */
+export declare function aggregateDigest(inputs: readonly FileDigestInput[]): string;

package/dist/shared/filereview/digest.js

@@ -0,0 +1,66 @@
+/**
+ * Canonical file-review digests — the runner-side mirror of the Go
+ * {@code filereview/digest.go} and the Java {@code FileDigest}, locked
+ * byte-for-byte by `apis/testdata/hitl/file-digest/vectors.json`.
+ *
+ * These are ENFORCEMENT digests, never correlation keys: the reconcile refuses
+ * to apply content whose digest differs from what the user approved. The runner
+ * is the sole producer of `before_sha256`/`after_sha256` (over the exact captured
+ * bytes) and of the derived `file_digest`/`aggregate_digest`; the backends only
+ * carry them. Keeping the formula identical across all three editions is what
+ * lets the cross-edition corpus prove parity.
+ */
+import { createHash } from "node:crypto";
+import { FileChangeKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+/**
+ * The proto enum value NAME for a {@link FileChangeKind}, e.g.
+ * `FILE_CHANGE_KIND_MODIFY`. The digest is computed over this name (matching Go's
+ * `kind.String()` and Java's `kind.name()`), NOT the TS member name, so all three
+ * editions hash an identical string. The cross-edition digest corpus validates
+ * this map; a missing or wrong entry fails the parity test.
+ */
+const FILE_CHANGE_KIND_NAME = {
+    [FileChangeKind.UNSPECIFIED]: "FILE_CHANGE_KIND_UNSPECIFIED",
+    [FileChangeKind.ADD]: "FILE_CHANGE_KIND_ADD",
+    [FileChangeKind.MODIFY]: "FILE_CHANGE_KIND_MODIFY",
+    [FileChangeKind.DELETE]: "FILE_CHANGE_KIND_DELETE",
+    [FileChangeKind.RENAME]: "FILE_CHANGE_KIND_RENAME",
+    [FileChangeKind.BINARY_CHANGE]: "FILE_CHANGE_KIND_BINARY_CHANGE",
+};
+/** The proto enum value name for a FileChangeKind (for the digest canonical form). */
+export function fileChangeKindName(kind) {
+    return FILE_CHANGE_KIND_NAME[kind] ?? "FILE_CHANGE_KIND_UNSPECIFIED";
+}
+/** Lowercase-hex SHA-256 of a UTF-8 string. */
+export function sha256Hex(s) {
+    return createHash("sha256").update(s, "utf8").digest("hex");
+}
+/** Lowercase-hex SHA-256 of raw bytes — used for `before_sha256`/`after_sha256`. */
+export function sha256Bytes(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * The canonical per-file digest:
+ * `sha256(join("\n", [path_before, path_after, kind_name, before_sha256, after_sha256]))`.
+ * Digesting the content HASHES (not raw bytes) keeps the string pure ASCII, free
+ * of any line-ending or encoding ambiguity across editions.
+ */
+export function fileDigest(input) {
+    return sha256Hex([
+        input.pathBefore,
+        input.pathAfter,
+        fileChangeKindName(input.kind),
+        input.beforeSha256,
+        input.afterSha256,
+    ].join("\n"));
+}
+/**
+ * The canonical change-set digest: `sha256(join("\n", sort_ascending(file_digests)))`.
+ * Sorting makes it independent of file order (a change set is an unordered set of
+ * files for identity). The empty set hashes the empty string.
+ */
+export function aggregateDigest(inputs) {
+    const digests = inputs.map(fileDigest).sort();
+    return sha256Hex(digests.join("\n"));
+}
+//# sourceMappingURL=digest.js.map

package/dist/shared/filereview/digest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"digest.js","sourceRoot":"","sources":["../../../src/shared/filereview/digest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,cAAc,EAAE,MAAM,8DAA8D,CAAC;AAE9F;;;;;;GAMG;AACH,MAAM,qBAAqB,GAA6C;IACtE,CAAC,cAAc,CAAC,WAAW,CAAC,EAAE,8BAA8B;IAC5D,CAAC,cAAc,CAAC,GAAG,CAAC,EAAE,sBAAsB;IAC5C,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,yBAAyB;IAClD,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,yBAAyB;IAClD,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,yBAAyB;IAClD,CAAC,cAAc,CAAC,aAAa,CAAC,EAAE,gCAAgC;CACjE,CAAC;AAEF,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CAAC,IAAoB;IACrD,OAAO,qBAAqB,CAAC,IAAI,CAAC,IAAI,8BAA8B,CAAC;AACvE,CAAC;AAED,+CAA+C;AAC/C,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,WAAW,CAAC,KAAiB;IAC3C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC1D,CAAC;AAWD;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAsB;IAC/C,OAAO,SAAS,CACd;QACE,KAAK,CAAC,UAAU;QAChB,KAAK,CAAC,SAAS;QACf,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC;QAC9B,KAAK,CAAC,YAAY;QAClB,KAAK,CAAC,WAAW;KAClB,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,MAAkC;IAChE,MAAM,OAAO,GAAG,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,OAAO,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC"}