cool-workflow 0.1.97 → 0.2.0

package/dist/{validation.js → core/state/validation.js}

@@ -1,47 +1,58 @@
 "use strict";
-// Fail-closed shape guards for persisted per-record types (F5, integrity boundary).
+// core/state/validation.ts — RecordValidationError + per-record shape
+// guards.
 //
-// `JSON.parse(...) as T` is a LIE: the cast asserts a shape TypeScript never
-// checked at runtime, so a corrupt/forged/old-schema record flows in as if it
-// were a valid T and is used/upserted unvalidated. These guards re-establish the
-// integrity boundary at the read edge: after parse, the raw value is structurally
-// validated against the type def in src/types/* BEFORE it is trusted.
+// MILESTONE 3 (+ WorkerScope port). Byte-exact port of the old build's
+// src/validation.ts. NodeSnapshot / NodeReplayRun are read at the
+// `readNodeSnapshot`/`readNodeReplay` edge in shell/node-store.ts.
+// WorkerScope is read at the `getWorkerScope`/`loadWorkerScopesFromDisk`
+// edge in shell/worker-isolation.ts. CandidateScore/CandidateRecord
+// guards still land with their owning milestone (9) rather than being
+// spec'd ahead of need here.
 //
-// Two callers, two error semantics — both fail closed, neither fabricates:
-//   - validate*()      throw a descriptive Error on mismatch (for readers that
-//                      already let parse errors propagate / require the record).
-//   - tryValidate*()   return null on mismatch (for best-effort readers that
-//                      swallow parse errors and SKIP the record — the downstream
-//                      gate then fails closed on the absence). Never throws.
+// WorkerScope itself is a shell-layer concept (its full type carries
+// ResolvedSandboxPolicy/SandboxAttestation from shell/execution-backend),
+// so this pure core module does not import that type. Instead it
+// declares WorkerScopeShape: the subset of required fields the old guard
+// actually checks. Any real WorkerScope satisfies this shape structurally
+// (TypeScript structural typing), so shell/worker-isolation.ts can call
+// this guard and get its own WorkerScope back without a core -> shell
+// import.
 //
-// Dependency-light by construction: imports ONLY from ./types. No fs, no clock,
-// no randomness — pure structural checks, safe in replay/core paths.
+// Two callers, two error semantics, both fail closed:
+//   - validate*()     throws a descriptive Error on mismatch.
+//   - tryValidate*()  returns null on mismatch (never throws).
+//
+// Dependency-light by construction: imports only from ./types. No fs, no
+// clock, no randomness — pure structural checks, safe in replay/core paths.
+//
+// Evidence: SPEC/state-core.md "src/validation.ts — persisted-record shape
+// guards", "Fail-closed record reads".
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RecordValidationError = void 0;
 exports.validateWorkerScope = validateWorkerScope;
 exports.validateNodeSnapshot = validateNodeSnapshot;
 exports.validateNodeReplayRun = validateNodeReplayRun;
-exports.validateCandidateScore = validateCandidateScore;
 exports.tryValidateCandidateScore = tryValidateCandidateScore;
-exports.validateCandidateRecord = validateCandidateRecord;
-// ---------------------------------------------------------------------------
-// Primitive predicates — small, total, never throw.
-// ---------------------------------------------------------------------------
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 function isString(value) {
     return typeof value === "string";
 }
-function isFiniteNumber(value) {
-    return typeof value === "number" && Number.isFinite(value);
+function isObjectArray(value) {
+    return Array.isArray(value) && value.every((entry) => isRecord(entry));
 }
 function isStringArray(value) {
     return Array.isArray(value) && value.every((entry) => typeof entry === "string");
 }
-function isObjectArray(value) {
-    return Array.isArray(value) && value.every((entry) => isRecord(entry));
+function isFiniteNumber(value) {
+    return typeof value === "number" && Number.isFinite(value);
+}
+function isNumberRecord(value) {
+    return isRecord(value) && Object.values(value).every((entry) => isFiniteNumber(entry));
 }
+const SNAPSHOT_FRESHNESS = new Set(["valid", "stale", "absent"]);
 const WORKER_STATUSES = new Set([
     "allocated",
     "running",
@@ -49,21 +60,10 @@ const WORKER_STATUSES = new Set([
     "failed",
     "rejected",
     "verified",
-    "orphaned"
-]);
-const SCORE_VERDICTS = new Set(["pass", "warn", "fail"]);
-const CANDIDATE_STATUSES = new Set([
-    "registered",
-    "scored",
-    "selected",
-    "rejected",
-    "verified",
-    "failed"
+    "orphaned",
 ]);
-const CANDIDATE_KINDS = new Set(["worker-output", "result", "artifact", "manual", "release"]);
-const SNAPSHOT_FRESHNESS = new Set(["valid", "stale", "absent"]);
-/** Descriptive integrity error — the message names the type and the field that
- *  broke, so a corrupt record is diagnosable from logs alone. */
+/** Descriptive integrity error — the message names the type and the field
+ *  that broke, so a corrupt record is diagnosable from logs alone. */
 class RecordValidationError extends Error {
     code = "record-shape-invalid";
     typeName;
@@ -77,11 +77,12 @@ class RecordValidationError extends Error {
 }
 exports.RecordValidationError = RecordValidationError;
 // ---------------------------------------------------------------------------
-// WorkerScope — worker-isolation.ts:309 / :905
-// Required (per src/types/worker.ts WorkerScope): schemaVersion===1, id, runId,
-// taskId, createdAt, updatedAt, status (enum), workerDir, inputPath, resultPath,
-// artifactsDir, logsDir are strings; allowedPaths string[]; feedbackIds string[];
-// errors object[]. Optional fields are not enforced (additive, may be absent).
+// WorkerScope — worker-isolation.ts getWorkerScope / loadWorkerScopesFromDisk
+// Required: schemaVersion===1, id, runId, taskId, createdAt, updatedAt,
+// workerDir, inputPath, resultPath, artifactsDir, logsDir are strings;
+// status a valid WorkerIsolationStatus; allowedPaths string[]; feedbackIds
+// string[]; errors object[]. Optional fields are not enforced (additive,
+// may be absent).
 // ---------------------------------------------------------------------------
 function workerScopeReason(value) {
     if (!isRecord(value))
@@ -98,7 +99,7 @@ function workerScopeReason(value) {
         "inputPath",
         "resultPath",
         "artifactsDir",
-        "logsDir"
+        "logsDir",
     ];
     for (const field of requiredStrings) {
         if (!isString(value[field]))
@@ -115,19 +116,15 @@ function workerScopeReason(value) {
         return { field: "errors", reason: "must be a StateNodeError[]" };
     return undefined;
 }
-/** Throw-on-mismatch guard for WorkerScope (callers that require the record). */
+/** Throw-on-mismatch guard for WorkerScope (callers that require the
+ *  record). Returns WorkerScopeShape — the caller (shell/worker-isolation.ts)
+ *  casts to its own richer WorkerScope, which is a structural superset. */
 function validateWorkerScope(value) {
     const problem = workerScopeReason(value);
     if (problem)
         throw new RecordValidationError("WorkerScope", problem.reason, problem.field);
     return value;
 }
-// ---------------------------------------------------------------------------
-// NodeSnapshotBody — shared by NodeSnapshot.body and NodeReplayRun.body.
-// Required (per src/types/state-node.ts): id, kind, status, loopStage strings;
-// inputs/outputs records; artifacts/evidence/errors object arrays;
-// parents/children string arrays.
-// ---------------------------------------------------------------------------
 function nodeSnapshotBodyReason(value, prefix) {
     if (!isRecord(value))
         return { field: prefix, reason: "must be a NodeSnapshotBody object" };
@@ -152,11 +149,6 @@ function nodeSnapshotBodyReason(value, prefix) {
         return { field: `${prefix}.children`, reason: "must be a string[]" };
     return undefined;
 }
-// ---------------------------------------------------------------------------
-// NodeSnapshot — node-snapshot.ts:121
-// Required: schemaVersion===1, snapshotId, runId, nodeId, capturedAt,
-// sourceFingerprint strings; body a valid NodeSnapshotBody.
-// ---------------------------------------------------------------------------
 function nodeSnapshotReason(value) {
     if (!isRecord(value))
         return { reason: "not an object" };
@@ -169,32 +161,20 @@ function nodeSnapshotReason(value) {
     }
     return nodeSnapshotBodyReason(value.body, "body");
 }
-/** Throw-on-mismatch guard for NodeSnapshot (read edge requires the record). */
+/** Throw-on-mismatch guard for NodeSnapshot (read edge requires the
+ *  record). */
 function validateNodeSnapshot(value) {
     const problem = nodeSnapshotReason(value);
     if (problem)
         throw new RecordValidationError("NodeSnapshot", problem.reason, problem.field);
     return value;
 }
-// ---------------------------------------------------------------------------
-// NodeReplayRun — node-snapshot.ts:133
-// Required: schemaVersion===1, replayId, runId, nodeId, snapshotId, replayedAt,
-// outputFingerprint strings; freshness enum; contractValidated boolean; body a
-// valid NodeSnapshotBody.
-// ---------------------------------------------------------------------------
 function nodeReplayRunReason(value) {
     if (!isRecord(value))
         return { reason: "not an object" };
     if (value.schemaVersion !== 1)
         return { field: "schemaVersion", reason: "must equal 1" };
-    const requiredStrings = [
-        "replayId",
-        "runId",
-        "nodeId",
-        "snapshotId",
-        "replayedAt",
-        "outputFingerprint"
-    ];
+    const requiredStrings = ["replayId", "runId", "nodeId", "snapshotId", "replayedAt", "outputFingerprint"];
     for (const field of requiredStrings) {
         if (!isString(value[field]))
             return { field: field, reason: "must be a string" };
@@ -207,7 +187,8 @@ function nodeReplayRunReason(value) {
     }
     return nodeSnapshotBodyReason(value.body, "body");
 }
-/** Throw-on-mismatch guard for NodeReplayRun (read edge requires the record). */
+/** Throw-on-mismatch guard for NodeReplayRun (read edge requires the
+ *  record). */
 function validateNodeReplayRun(value) {
     const problem = nodeReplayRunReason(value);
     if (problem)
@@ -215,14 +196,15 @@ function validateNodeReplayRun(value) {
     return value;
 }
 // ---------------------------------------------------------------------------
-// CandidateScore — multi-agent-operator-ux.ts:502 / evidence-reasoning.ts:750
-// Required (per src/types/candidate.ts): schemaVersion===1, id, candidateId,
-// runId, createdAt, scorer strings; criteria record of numbers; total/maxTotal/
-// normalized finite numbers; verdict enum; evidence/artifacts object arrays.
+// CandidateScore — the score records evidence-reasoning.ts reads off disk to
+// build the score gate. A corrupt/forged score must NOT flow into the run as a
+// trusted record: the gate that backs commit selection reads these fields, so
+// we fail closed at the read edge. schemaVersion===1; id/candidateId/runId/
+// createdAt/scorer strings; criteria a Record<string, number>; total/maxTotal/
+// normalized finite numbers; verdict a pass|warn|fail enum; evidence/artifacts
+// object arrays. Byte-behavior port of the old build's src/validation.ts guard.
 // ---------------------------------------------------------------------------
-function isNumberRecord(value) {
-    return isRecord(value) && Object.values(value).every((entry) => isFiniteNumber(entry));
-}
+const SCORE_VERDICTS = new Set(["pass", "warn", "fail"]);
 function candidateScoreReason(value) {
     if (!isRecord(value))
         return { reason: "not an object" };
@@ -242,7 +224,7 @@ function candidateScoreReason(value) {
     if (!isFiniteNumber(value.normalized))
         return { field: "normalized", reason: "must be a finite number" };
     if (!isString(value.verdict) || !SCORE_VERDICTS.has(value.verdict)) {
-        return { field: "verdict", reason: "must be a valid CandidateScoreVerdict" };
+        return { field: "verdict", reason: "must be a valid CandidateScore verdict (pass|warn|fail)" };
     }
     if (!isObjectArray(value.evidence))
         return { field: "evidence", reason: "must be a StateEvidence[]" };
@@ -250,58 +232,9 @@ function candidateScoreReason(value) {
         return { field: "artifacts", reason: "must be a StateArtifact[]" };
     return undefined;
 }
-/** Throw-on-mismatch guard for CandidateScore (callers that require the record). */
-function validateCandidateScore(value) {
-    const problem = candidateScoreReason(value);
-    if (problem)
-        throw new RecordValidationError("CandidateScore", problem.reason, problem.field);
-    return value;
-}
-/** Best-effort variant: returns null on mismatch (caller skips the record so the
- *  downstream score gate fails closed on its absence). */
+/** Best-effort guard: returns null on a shape mismatch so the caller skips the
+ *  record and the downstream score gate fails closed on its absence, rather
+ *  than trusting a forged/corrupt score. */
 function tryValidateCandidateScore(value) {
     return candidateScoreReason(value) ? null : value;
 }
-// ---------------------------------------------------------------------------
-// CandidateRecord — candidate-scoring.ts getCandidate / loadCandidatesFromDisk.
-// Required (per src/types/candidate.ts): schemaVersion===1, id, runId, createdAt,
-// updatedAt strings; kind/status enums; artifacts/evidence object arrays;
-// scores/feedbackIds string arrays. Optional ids (workerId/taskId/…) not enforced.
-// A corrupt/forged candidate record must NOT flow into the run as a trusted T —
-// the gate that backs commit selection reads these fields, so we fail closed at
-// the read edge instead of upserting an unvalidated cast.
-// ---------------------------------------------------------------------------
-function candidateRecordReason(value) {
-    if (!isRecord(value))
-        return { reason: "not an object" };
-    if (value.schemaVersion !== 1)
-        return { field: "schemaVersion", reason: "must equal 1" };
-    const requiredStrings = ["id", "runId", "createdAt", "updatedAt"];
-    for (const field of requiredStrings) {
-        if (!isString(value[field]))
-            return { field: field, reason: "must be a string" };
-    }
-    if (!isString(value.kind) || !CANDIDATE_KINDS.has(value.kind)) {
-        return { field: "kind", reason: "must be a valid CandidateKind" };
-    }
-    if (!isString(value.status) || !CANDIDATE_STATUSES.has(value.status)) {
-        return { field: "status", reason: "must be a valid CandidateStatus" };
-    }
-    if (!isObjectArray(value.artifacts))
-        return { field: "artifacts", reason: "must be a StateArtifact[]" };
-    if (!isObjectArray(value.evidence))
-        return { field: "evidence", reason: "must be a StateEvidence[]" };
-    if (!isStringArray(value.scores))
-        return { field: "scores", reason: "must be a string[]" };
-    if (!isStringArray(value.feedbackIds))
-        return { field: "feedbackIds", reason: "must be a string[]" };
-    return undefined;
-}
-/** Throw-on-mismatch guard for CandidateRecord (callers that require the record
- *  at the disk read edge — getCandidate / loadCandidatesFromDisk). */
-function validateCandidateRecord(value) {
-    const problem = candidateRecordReason(value);
-    if (problem)
-        throw new RecordValidationError("CandidateRecord", problem.reason, problem.field);
-    return value;
-}

package/dist/core/trust/evidence-grounding.js

@@ -0,0 +1,134 @@
+"use strict";
+// core/trust/evidence-grounding.ts — isGroundedEvidence, confidence tiers,
+// extractEvidenceContent's PURE decision half.
+//
+// MILESTONE 6+7 (combined). Byte-exact port of the old build's
+// src/evidence-grounding.ts, split so this file stays pure (no fs):
+// resolution against real disk paths takes a caller-supplied
+// `pathExists`/`readFile`, matching the core/shell split. Real callers
+// (shell/) pass `fs.existsSync`/`fs.readFileSync`.
+//
+// Evidence: SPEC/pipeline-run.md "Result ingest — src/result-normalize.ts"
+// (isGroundedEvidence is its evidence-classification primitive);
+// plugins/cool-workflow/src/evidence-grounding.ts (byte-exact source).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isGroundedEvidence = isGroundedEvidence;
+exports.hasGroundedEvidence = hasGroundedEvidence;
+exports.requireResolvableEvidence = requireResolvableEvidence;
+exports.resolveEvidenceLocator = resolveEvidenceLocator;
+exports.unresolvedFileEvidence = unresolvedFileEvidence;
+exports.computeEvidenceConfidence = computeEvidenceConfidence;
+exports.extractEvidenceContent = extractEvidenceContent;
+const URL_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+const PATH_SEP_RE = /[\\/]/;
+const FILE_EXT_RE = /\.[A-Za-z0-9]{1,12}(?::\d+(?:-\d+)?)?$/;
+const NAMESPACE_TOKEN_RE = /^[A-Za-z][A-Za-z0-9_.-]*:\S/;
+const LINE_SUFFIX_RE = /:(\d+(?:-\d+)?)$/;
+/** A single evidence string is "grounded" if it is machine-shaped — a
+ *  URL, a path-like locator, or a `namespace:value` token — rather than
+ *  free prose. */
+function isGroundedEvidence(raw) {
+    const value = String(raw ?? "").trim();
+    if (!value)
+        return false;
+    if (URL_RE.test(value))
+        return true;
+    if (PATH_SEP_RE.test(value))
+        return true;
+    if (FILE_EXT_RE.test(value))
+        return true;
+    if (NAMESPACE_TOKEN_RE.test(value))
+        return true;
+    return false;
+}
+/** An evidence array passes the gate if at least one entry is grounded. */
+function hasGroundedEvidence(evidence) {
+    return Array.isArray(evidence) && evidence.some((entry) => isGroundedEvidence(entry));
+}
+/** Whether opt-in strict resolution is requested via the environment.
+ *  Enabled by DEFAULT: file-style evidence locators MUST exist on disk.
+ *  `CW_REQUIRE_RESOLVABLE_EVIDENCE=0` restores the prior shape-only
+ *  check. */
+function requireResolvableEvidence(env = process.env) {
+    const raw = env.CW_REQUIRE_RESOLVABLE_EVIDENCE;
+    if (raw === undefined || raw === null || raw === "")
+        return true;
+    if (/^(0|false|no|off)$/i.test(raw))
+        return false;
+    return true;
+}
+function classify(raw) {
+    const value = raw.trim();
+    if (!value)
+        return { kind: "opaque" };
+    if (URL_RE.test(value))
+        return { kind: "url" };
+    const line = value.match(LINE_SUFFIX_RE);
+    const pathPart = line ? value.slice(0, value.length - line[0].length) : value;
+    const looksFile = (PATH_SEP_RE.test(pathPart) || FILE_EXT_RE.test(value)) && !/\s/.test(pathPart);
+    return looksFile ? { kind: "file", pathPart } : { kind: "opaque" };
+}
+/** Resolve one locator against base dirs (used only in strict mode).
+ *  `resolve(candidatePath)` is caller-supplied (real fs.existsSync in
+ *  shell/), matching the core/shell split — this pure module never
+ *  imports fs itself. */
+function resolveEvidenceLocator(raw, baseDirs, exists, isAbsolute, resolvePath) {
+    const shape = classify(raw);
+    if (shape.kind === "url")
+        return "external";
+    if (shape.kind === "opaque" || !shape.pathPart)
+        return "opaque";
+    const candidates = isAbsolute(shape.pathPart) ? [shape.pathPart] : baseDirs.filter(Boolean).map((base) => resolvePath(base, shape.pathPart));
+    for (const candidate of candidates) {
+        if (exists(candidate))
+            return "resolved";
+    }
+    return "unresolved";
+}
+/** In strict mode, the file-style locators that could NOT be resolved on
+ *  disk. Returns [] when strict mode is off or all file locators
+ *  resolve. */
+function unresolvedFileEvidence(evidence, baseDirs, ops, env = process.env) {
+    if (!requireResolvableEvidence(env) || !Array.isArray(evidence))
+        return [];
+    return evidence.map((entry) => String(entry)).filter((entry) => resolveEvidenceLocator(entry, baseDirs, ops.exists, ops.isAbsolute, ops.resolve) === "unresolved");
+}
+/** Compute the confidence tier for a single evidence string. */
+function computeEvidenceConfidence(raw, baseDirs, ops, env = process.env) {
+    if (!isGroundedEvidence(raw))
+        return "ungrounded";
+    if (!baseDirs || !baseDirs.length || !ops || !requireResolvableEvidence(env))
+        return "grounded";
+    const value = String(raw).trim();
+    const shape = classify(value);
+    if (shape.kind === "url")
+        return "grounded";
+    if (shape.kind === "opaque")
+        return "grounded";
+    const resolution = resolveEvidenceLocator(value, baseDirs, ops.exists, ops.isAbsolute, ops.resolve);
+    return resolution === "resolved" ? "resolvable" : "grounded";
+}
+/** Extract actual content from a file-style evidence locator. Never
+ *  fabricates: returns undefined when the file doesn't exist or the
+ *  locator is not file-style. Lines are 1-indexed. `readFile` is
+ *  caller-supplied (real fs.readFileSync in shell/). */
+function extractEvidenceContent(locator, baseDirs, ops, readFile) {
+    const shape = classify(locator);
+    if (shape.kind !== "file" || !shape.pathPart)
+        return undefined;
+    const lineMatch = locator.match(/:(\d+)$/);
+    const lineNum = lineMatch ? Number(lineMatch[1]) : undefined;
+    const candidatePath = ops.isAbsolute(shape.pathPart)
+        ? shape.pathPart
+        : baseDirs.filter(Boolean).map((base) => ops.resolve(base, shape.pathPart)).find((p) => ops.exists(p));
+    if (!candidatePath)
+        return undefined;
+    const content = readFile(candidatePath);
+    if (content === undefined)
+        return undefined;
+    if (lineNum && lineNum > 0) {
+        const lines = content.split("\n");
+        return lines[lineNum - 1] || undefined;
+    }
+    return content.slice(0, 200);
+}

package/dist/core/trust/ledger.js

@@ -0,0 +1,199 @@
+"use strict";
+// core/trust/ledger.ts — the cross-agent handoff ledger kernel.
+//
+// MILESTONE 8 (v2/PLAN.md build order, step 8; SPEC/ledger-trust.md in
+// full). Pure: computeLedgerDigest, buildLedgerProposal/Review,
+// verifyLedgerEntry, applyLedgerProposal. Directory reads
+// (listLedgerEntries/unionLedgerEntries) live in shell/ledger-io.ts, NOT
+// here — this file touches no fs.
+//
+// Byte-exact port of the old build's src/ledger.ts. Uses
+// core/hash.ts's `ledgerStableStringify` (byte-identical to
+// `stableStringify`, kept as its own named export per PLAN.md's Hash
+// dedup rule) rather than reimplementing a private copy.
+//
+// Evidence: SPEC/ledger-trust.md "Handoff ledger entry", "Exported
+// functions", "Edge cases"; plugins/cool-workflow/src/ledger.ts:1-429.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeLedgerDigest = computeLedgerDigest;
+exports.buildLedgerProposal = buildLedgerProposal;
+exports.buildLedgerReview = buildLedgerReview;
+exports.verifyLedgerEntry = verifyLedgerEntry;
+exports.applyLedgerProposal = applyLedgerProposal;
+exports.resolveLedgerInbox = resolveLedgerInbox;
+const hash_1 = require("../hash");
+/** sha256 over the canonical content (every field except `id` and
+ *  `digest`, which are derived FROM it). Returns the full `sha256:<hex>`
+ *  form — the same prefixed spelling every other hash chain uses. */
+function computeLedgerDigest(entry) {
+    return (0, hash_1.sha256)((0, hash_1.ledgerStableStringify)(entry));
+}
+/** Content-addressed id: `ldg-` + the first 16 hex chars of the digest. */
+function deriveId(digest) {
+    return `ldg-${digest.replace(/^sha256:/, "").slice(0, 16)}`;
+}
+function seal(content) {
+    const digest = computeLedgerDigest(content);
+    return { ...content, id: deriveId(digest), digest };
+}
+function buildLedgerProposal(input) {
+    const content = {
+        kind: "proposal",
+        schemaVersion: 1,
+        from: input.from,
+        to: input.to,
+        title: input.title,
+        rationale: input.rationale,
+        targetFiles: [...input.targetFiles],
+        suggestedDiff: input.suggestedDiff || "",
+        createdAt: input.createdAt,
+    };
+    return seal(content);
+}
+function buildLedgerReview(input) {
+    const content = {
+        kind: "review",
+        schemaVersion: 1,
+        from: input.from,
+        to: input.to,
+        target: input.target,
+        verdict: input.verdict,
+        findings: [...input.findings],
+        createdAt: input.createdAt,
+    };
+    return seal(content);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+const PROPOSAL_FIELDS = ["from", "to", "title", "rationale", "targetFiles", "suggestedDiff", "createdAt"];
+const REVIEW_FIELDS = ["from", "to", "target", "verdict", "findings", "createdAt"];
+/** Fail-closed verification. Any structural defect, unknown kind, or
+ *  digest mismatch yields `ok:false`. Check names run in this order and
+ *  stop at the first failure: structure, kind, schema, digest-present,
+ *  fields (verdict nested inside for reviews), digest, id. */
+function verifyLedgerEntry(raw) {
+    const checks = [];
+    const fail = (name, code, detail) => {
+        checks.push({ name, pass: false, code, detail });
+        return {
+            ok: false,
+            id: isRecord(raw) && typeof raw.id === "string" ? raw.id : null,
+            kind: isRecord(raw) && typeof raw.kind === "string" ? raw.kind : null,
+            checks,
+            failedChecks: checks
+                .filter((c) => !c.pass)
+                .map((c) => ({ name: c.name, code: c.code, detail: c.detail })),
+        };
+    };
+    if (!isRecord(raw))
+        return fail("structure", "ledger-not-object", "entry is not a JSON object");
+    checks.push({ name: "structure", pass: true });
+    const kind = raw.kind;
+    if (kind !== "proposal" && kind !== "review") {
+        return fail("kind", "ledger-unknown-kind", `kind must be proposal|review, got ${JSON.stringify(kind)}`);
+    }
+    checks.push({ name: "kind", pass: true });
+    if (raw.schemaVersion !== 1) {
+        return fail("schema", "ledger-bad-schema", `schemaVersion must be 1, got ${JSON.stringify(raw.schemaVersion)}`);
+    }
+    checks.push({ name: "schema", pass: true });
+    if (typeof raw.digest !== "string" || !raw.digest) {
+        return fail("digest-present", "ledger-missing-digest", "digest is absent or not a string");
+    }
+    checks.push({ name: "digest-present", pass: true });
+    const fields = kind === "proposal" ? PROPOSAL_FIELDS : REVIEW_FIELDS;
+    const content = { kind, schemaVersion: 1 };
+    for (const field of fields) {
+        if (!(field in raw))
+            return fail("fields", "ledger-missing-field", `required field ${field} is absent`);
+        content[field] = raw[field];
+    }
+    if (kind === "review" && raw.verdict !== "APPROVED" && raw.verdict !== "REJECTED") {
+        return fail("verdict", "ledger-bad-verdict", `verdict must be APPROVED|REJECTED, got ${JSON.stringify(raw.verdict)}`);
+    }
+    checks.push({ name: "fields", pass: true });
+    const recomputed = computeLedgerDigest(content);
+    if (recomputed !== raw.digest) {
+        return fail("digest", "ledger-digest-mismatch", `stored digest does not match content (recomputed ${recomputed})`);
+    }
+    checks.push({ name: "digest", pass: true });
+    // Bind the id to the content: it MUST be the content-addressed id
+    // derived from the digest. Without this, `id` is a free, unverified
+    // field (excluded from the digest) — a forged entry could set `id` to
+    // collide with a legit one, and any id-keyed de-duplication (`cw
+    // ledger list` union) would silently drop one of them.
+    const expectedId = deriveId(raw.digest);
+    if (raw.id !== expectedId) {
+        return fail("id", "ledger-id-mismatch", `id ${JSON.stringify(raw.id)} is not the content-addressed id for this digest (expected ${expectedId})`);
+    }
+    checks.push({ name: "id", pass: true });
+    return { ok: true, id: expectedId, kind, checks, failedChecks: [] };
+}
+/** Fail-closed extraction of a proposal's `suggestedDiff`. The diff can
+ *  ONLY escape after the entry verifies: a tampered entry, a review (not
+ *  a proposal), or a proposal with no diff all yield `ok:false` and
+ *  `diff:null`. */
+function applyLedgerProposal(raw) {
+    const verified = verifyLedgerEntry(raw);
+    if (!verified.ok) {
+        return { ok: false, id: verified.id, kind: verified.kind, diff: null, failedChecks: verified.failedChecks };
+    }
+    if (verified.kind !== "proposal") {
+        return {
+            ok: false,
+            id: verified.id,
+            kind: verified.kind,
+            diff: null,
+            failedChecks: [{ name: "kind", code: "ledger-not-a-proposal", detail: "apply expects a proposal entry, not a review" }],
+        };
+    }
+    const rec = isRecord(raw) ? raw : {};
+    const diff = typeof rec.suggestedDiff === "string" ? rec.suggestedDiff : "";
+    if (!diff) {
+        return {
+            ok: false,
+            id: verified.id,
+            kind: verified.kind,
+            diff: null,
+            failedChecks: [{ name: "diff", code: "ledger-empty-diff", detail: "proposal carries no suggestedDiff to apply" }],
+        };
+    }
+    return { ok: true, id: verified.id, kind: verified.kind, diff, failedChecks: [] };
+}
+/** Derive a machine-actionable inbox summary: pair each proposal with the
+ *  review(s) that target it and report whether it is pending, approved,
+ *  rejected, or contested. Only VERIFIED entries take part — a tampered
+ *  review must never resolve a proposal. */
+function resolveLedgerInbox(entries) {
+    const verified = entries.filter((e) => e.ok);
+    const reviews = verified.filter((e) => e.kind === "review" && e.target);
+    const proposals = verified
+        .filter((e) => e.kind === "proposal" && e.id)
+        .map((p) => {
+        const answering = reviews.filter((r) => r.target === p.id);
+        const verdicts = new Set(answering.map((r) => r.verdict));
+        let resolution;
+        if (answering.length === 0)
+            resolution = "pending";
+        else if (verdicts.size > 1)
+            resolution = "contested";
+        else
+            resolution = verdicts.has("APPROVED") ? "approved" : "rejected";
+        return {
+            id: p.id,
+            title: p.title,
+            resolution,
+            reviews: answering.map((r) => r.id).sort(),
+        };
+    })
+        .sort((a, b) => a.id.localeCompare(b.id));
+    const tally = (s) => proposals.filter((p) => p.resolution === s).length;
+    return {
+        proposals,
+        pending: tally("pending"),
+        approved: tally("approved"),
+        rejected: tally("rejected"),
+        contested: tally("contested"),
+    };
+}