@oscharko-dev/keiko 0.2.0-beta.4 → 0.2.0-beta.6

package/node_modules/@oscharko-dev/keiko-evidence/dist/qualityIntelligence/store.js

@@ -12,8 +12,8 @@
 // SQLite" alternative.
 //
 // Safety:
-// - Base dir is realpath-contained once at construction (reusing the assertContainedRealPath
-//   primitive); every child path is re-checked before any read/write/delete.
+// - Base dir is realpath-contained once at construction; every child path is derived from a
+//   validated runId and the lexical directory entry is inspected before overwrite/delete.
 // - File names are derived from the VALIDATED runId via assertValidRunId — no separator/`..`/NUL
 //   can reach the resolved path.
 // - Writes are atomic O_EXCL temp + rename. A partial write leaves a `.tmp` that is invisible to
@@ -24,7 +24,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { chmodSync, mkdirSync, readdirSync, readFileSync, lstatSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join, resolve } from "node:path";
-import { assertContainedRealPath, resolveWithinWorkspace, } from "@oscharko-dev/keiko-workspace";
+import { resolveWithinWorkspace } from "@oscharko-dev/keiko-workspace";
 import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
 import { assertValidRunId } from "@oscharko-dev/keiko-security";
 import { EvidenceReadError, EvidenceWriteError } from "../errors.js";
@@ -80,10 +80,9 @@ function existingQiBaseDir(baseDir, fs) {
         throw new EvidenceReadError(`cannot read QI evidence directory: ${error instanceof Error ? error.message : "unknown"}`);
     }
 }
-function containedQiManifestPath(runId, realBase, fs) {
+function lexicalQiManifestPath(runId, realBase) {
     assertValidRunId(runId);
-    const lexical = resolveWithinWorkspace(realBase, `${runId}${QI_MANIFEST_SUFFIX}`);
-    return assertContainedRealPath(fs, realBase, lexical, `${runId}${QI_MANIFEST_SUFFIX}`);
+    return resolveWithinWorkspace(realBase, `${runId}${QI_MANIFEST_SUFFIX}`);
 }
 function isQiManifestName(name) {
     if (!name.endsWith(QI_MANIFEST_SUFFIX)) {
@@ -107,6 +106,14 @@ function isSingleLinkRegularFile(path, fs) {
         throw new EvidenceReadError(`cannot inspect QI manifest: ${error instanceof Error ? error.message : "unknown"}`);
     }
 }
+function assertWritableQiManifestEntry(target, fs) {
+    const entry = lstatSync(target, { throwIfNoEntry: false });
+    if (entry === undefined)
+        return;
+    if (!entry.isFile() || !isSingleLinkRegularFile(target, fs)) {
+        throw new EvidenceWriteError("cannot overwrite a non-ledger QI manifest");
+    }
+}
 function listQiRunIds(realBase, fs) {
     const runIds = [];
     try {
@@ -150,7 +157,7 @@ function reportQiLocation(baseDir, fs, runId) {
     const realBase = existingQiBaseDir(baseDir, fs);
     return realBase === undefined
         ? join(resolve(baseDir), `${runId}${QI_MANIFEST_SUFFIX}`)
-        : containedQiManifestPath(runId, realBase, fs);
+        : lexicalQiManifestPath(runId, realBase);
 }
 function parseAndValidateManifest(json) {
     let parsed;
@@ -179,17 +186,6 @@ function assertHashMatches(label, expected, stored) {
         throw new EvidenceReadError(`QI manifest ${label} integrity hash mismatch`);
     }
 }
-// Backward-compatible group check: a group that shipped before it was integrity-hashed (coverageMatrix
-// #738, sourceFingerprints #735) may exist on a legacy manifest without a stored hash. Enforce the
-// check only once a stored hash is present; new manifests always carry it, so tampering with a current
-// group is still caught.
-function assertOptionalHashMatches(label, value, stored) {
-    if (stored === undefined)
-        return;
-    if (sha256OfJson(value) !== stored) {
-        throw new EvidenceReadError(`QI manifest ${label} integrity hash mismatch`);
-    }
-}
 function assertIntegrityHashesMatch(manifest) {
     const expected = buildIntegrityHashes(manifest.findings, manifest.exports, manifest.evidenceRefs);
     assertHashMatches("findings", expected.findings, manifest.integrityHashes.findings);
@@ -199,8 +195,15 @@ function assertIntegrityHashesMatch(manifest) {
     // directly — a removed or added set (stored present, expected absent or vice versa) is caught too.
     const expectedAtomFingerprints = manifest.atomFingerprints === undefined ? undefined : sha256OfJson(manifest.atomFingerprints);
     assertHashMatches("atomFingerprints", expectedAtomFingerprints, manifest.integrityHashes.atomFingerprints);
-    assertOptionalHashMatches("coverageMatrix", manifest.coverageMatrix, manifest.integrityHashes.coverageMatrix);
-    assertOptionalHashMatches("sourceFingerprints", manifest.sourceFingerprints, manifest.integrityHashes.sourceFingerprints);
+    // coverageMatrix and sourceFingerprints: derive expected = (collection === undefined ? undefined :
+    // sha256OfJson(collection)) and compare with assertHashMatches so a present collection with a
+    // deleted stored sub-hash FAILS CLOSED (mirrors atomFingerprints above — removal-proof).
+    const expectedCoverageMatrix = manifest.coverageMatrix === undefined ? undefined : sha256OfJson(manifest.coverageMatrix);
+    assertHashMatches("coverageMatrix", expectedCoverageMatrix, manifest.integrityHashes.coverageMatrix);
+    const expectedSourceFingerprints = manifest.sourceFingerprints === undefined
+        ? undefined
+        : sha256OfJson(manifest.sourceFingerprints);
+    assertHashMatches("sourceFingerprints", expectedSourceFingerprints, manifest.integrityHashes.sourceFingerprints);
 }
 // Integrity scope (be precise — this is the on-read tamper-detection contract): we verify the
 // (totals ↔ collection-length) invariant for findings/exports AND the per-group SHA-256 hashes for
@@ -248,7 +251,8 @@ function loadQiManifest(baseDir, fs, runId) {
 function recordQiManifest(baseDir, fs, randomSuffix, manifest) {
     assertValidRunId(manifest.runId);
     const realBase = prepareQiBaseDir(baseDir, fs);
-    const target = containedQiManifestPath(manifest.runId, realBase, fs);
+    const target = lexicalQiManifestPath(manifest.runId, realBase);
+    assertWritableQiManifestEntry(target, fs);
     atomicWriteQiManifest(target, JSON.stringify(manifest), randomSuffix);
     return target;
 }
@@ -258,7 +262,7 @@ function deleteQiManifest(baseDir, fs, runId) {
     if (realBase === undefined) {
         return false;
     }
-    const target = containedQiManifestPath(runId, realBase, fs);
+    const target = lexicalQiManifestPath(runId, realBase);
     if (lstatSync(target, { throwIfNoEntry: false })?.isFile() !== true) {
         return false;
     }
@@ -391,6 +395,75 @@ export function recordQualityIntelligenceRun(input, options = {}) {
     });
     return { manifest, location: store.record(manifest) };
 }
+// Fold a second redaction summary into a base one so the manifest's counts-only redaction summary
+// stays internally consistent after an export row is appended (the run summary + the row's scan).
+function foldRedactionSummary(base, add) {
+    const patternsMatched = { ...base.patternsMatched };
+    for (const [key, count] of Object.entries(add.patternsMatched)) {
+        patternsMatched[key] = (patternsMatched[key] ?? 0) + count;
+    }
+    return {
+        totalStringsScanned: base.totalStringsScanned + add.totalStringsScanned,
+        stringsRedacted: base.stringsRedacted + add.stringsRedacted,
+        patternsMatched,
+    };
+}
+/**
+ * Append one export-evidence row to an already-recorded run manifest (Issue #283, AC4 — "export
+ * evidence records target type, artifact IDs, mapping profile, and result without leaking secrets";
+ * Audit Addendum — "audit evidence for every export action").
+ *
+ * Every QI export action — a local serialisation download, a binary PDF/ZIP bundle, or a dry-run
+ * preview — emits one audit row recording WHAT was exported (`targetAdapter`), the artifact id, its
+ * integrity hash, the redaction attestation, and whether it was a dry-run. The disabled external-TMS
+ * write path produces no artifact and therefore records nothing.
+ *
+ * Rows are deduplicated by `(id, dryRun)` so re-exporting the same adapter in the same mode is
+ * idempotent — the audit captures each distinct (artifact, mode) once rather than once per click,
+ * which also bounds manifest growth.
+ *
+ * Invariants preserved (mirrors {@link recordQualityIntelligenceRun}):
+ *  - the new row's string leaves pass the persist redactor before assembly (the row carries only
+ *    ids / an enum / a sha-256 hash / booleans, so this is a no-op in practice, but the persist
+ *    redactor is applied unconditionally to keep the fail-closed contract uniform);
+ *  - `integrityHashes.exports` is recomputed over the full new collection; the other hash groups are
+ *    carried over unchanged because their collections did not change;
+ *  - `totals.exports` stays equal to `exports.length` (asserted on read);
+ *  - the counts-only `redactionSummary` folds in the new row's scan;
+ *  - the manifest is rewritten through the same atomic O_EXCL temp + rename path.
+ *
+ * Throws `EvidenceReadError` when the run manifest does not exist (an export cannot precede its run)
+ * and `EvidenceWriteError` when neither `store` nor `evidenceDir` is supplied or the write fails.
+ */
+export function appendQualityIntelligenceExportRow(input, options = {}) {
+    assertValidRunId(input.runId);
+    const store = resolveStore(options);
+    if (store === undefined) {
+        throw new EvidenceWriteError("appendQualityIntelligenceExportRow requires options.store or options.evidenceDir");
+    }
+    const existing = store.load(input.runId);
+    if (existing === undefined) {
+        throw new EvidenceReadError(`cannot append export evidence: QI run "${input.runId}" was not found`);
+    }
+    const { redacted: redactedRow, summary: rowSummary } = redactQualityIntelligenceEvidence(input.export, options.redaction ?? {});
+    const isSameRow = (row) => row.id === redactedRow.id && (row.dryRun ?? false) === (redactedRow.dryRun ?? false);
+    if (existing.exports.some(isSameRow)) {
+        return { manifest: existing, location: store.location(input.runId) };
+    }
+    const exports = [...existing.exports, redactedRow];
+    const integrityHashes = {
+        ...existing.integrityHashes,
+        exports: sha256OfJson(exports),
+    };
+    const manifest = {
+        ...existing,
+        exports,
+        totals: { ...existing.totals, exports: exports.length },
+        integrityHashes,
+        redactionSummary: foldRedactionSummary(existing.redactionSummary, rowSummary),
+    };
+    return { manifest, location: store.record(manifest) };
+}
 export function loadQualityIntelligenceRun(runId, options = {}) {
     const store = resolveLoadStore(options);
     return store.load(runId);

package/node_modules/@oscharko-dev/keiko-evidence/dist/side-file.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"side-file.d.ts","sourceRoot":"","sources":["../src/side-file.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AASvC,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;CACtC;AAwDD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,qBAA0B,GAClC,mBAAmB,CAmBrB"}
+{"version":3,"file":"side-file.d.ts","sourceRoot":"","sources":["../src/side-file.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AASvC,YAAY,EAAE,mBAAmB,EAAE,CAAC;AAEpC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,CAAC,EAAE,WAAW,CAAC;IAC1B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,MAAM,CAAC;CACtC;AA+DD,wBAAgB,aAAa,CAC3B,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,qBAA0B,GAClC,mBAAmB,CA2BrB"}

package/node_modules/@oscharko-dev/keiko-evidence/dist/side-file.js

@@ -4,7 +4,7 @@
 // realpath-containment primitive — no new path-safety mechanism is introduced. `evidenceSchemaVersion`
 // stays "1" (additive manifest field consumed by callers).
 import { createHash, randomUUID } from "node:crypto";
-import { mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { lstatSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { assertContainedRealPath, resolveWithinWorkspace, } from "@oscharko-dev/keiko-workspace";
 import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
@@ -42,6 +42,12 @@ function ensureDir(absolute) {
         throw new EvidenceWriteError(`cannot create evidence subdirectory: ${error instanceof Error ? error.message : "unknown"}`);
     }
 }
+function assertRealDirectoryEntry(absolute) {
+    const stat = lstatSync(absolute, { throwIfNoEntry: false });
+    if (stat === undefined || !stat.isDirectory() || stat.isSymbolicLink()) {
+        throw new EvidenceWriteError("side-file run directory must be a real directory");
+    }
+}
 function atomicWriteBytes(target, data, randomSuffix) {
     const temp = `${target}.${randomSuffix()}.tmp`;
     try {
@@ -65,11 +71,17 @@ export function writeSideFile(baseDir, runId, name, data, options = {}) {
     const fs = options.fs ?? nodeWorkspaceFs;
     const randomSuffix = options.randomSuffix ?? randomUUID;
     ensureDir(baseDir);
-    const runDir = join(baseDir, runId);
+    const realBase = fs.realPath(baseDir);
+    const runDir = join(realBase, runId);
+    const existingRunDir = lstatSync(runDir, { throwIfNoEntry: false });
+    if (existingRunDir !== undefined &&
+        (!existingRunDir.isDirectory() || existingRunDir.isSymbolicLink())) {
+        throw new EvidenceWriteError("side-file run directory must be a real directory");
+    }
     ensureDir(runDir);
-    const realRunDir = fs.realPath(runDir);
-    const lexicalTarget = resolveWithinWorkspace(realRunDir, name);
-    const absoluteTarget = assertContainedRealPath(fs, realRunDir, lexicalTarget, name);
+    assertRealDirectoryEntry(runDir);
+    const lexicalTarget = resolveWithinWorkspace(realBase, join(runId, name));
+    const absoluteTarget = assertContainedRealPath(fs, realBase, lexicalTarget, `${runId}/${name}`);
     const sha256 = createHash("sha256").update(data).digest("hex");
     atomicWriteBytes(absoluteTarget, data, randomSuffix);
     return {

package/node_modules/@oscharko-dev/keiko-evidence/dist/store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAsBA,OAAO,EAGL,KAAK,WAAW,EACjB,MAAM,+BAA+B,CAAC;AAkBvC,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAKxD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,GAC5D,MAAM,CAER;AAID,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,YAAY,EAAE,aAAa,EAAE,CAAC;AAI9B,wBAAgB,2BAA2B,IAAI,aAAa,CAsB3D;AAsKD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,WAA6B,EACjC,YAAY,GAAE,MAAM,MAAmB,GACtC,aAAa,CAWf"}
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAwBA,OAAO,EAA0B,KAAK,WAAW,EAAE,MAAM,+BAA+B,CAAC;AA6BzF,eAAO,MAAM,oBAAoB,sBAAsB,CAAC;AAKxD,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAAG,SAAS,GAC5D,MAAM,CAER;AAID,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,YAAY,EAAE,aAAa,EAAE,CAAC;AAI9B,wBAAgB,2BAA2B,IAAI,aAAa,CA4B3D;AAwRD,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,EAAE,GAAE,WAA6B,EACjC,YAAY,GAAE,MAAM,MAAmB,GACtC,aAAa,CAaf"}

package/node_modules/@oscharko-dev/keiko-evidence/dist/store.js

@@ -8,22 +8,31 @@
 // resolved child path is re-checked to remain inside the contained base dir before any write,
 // read, or delete. Writes are atomic (temp + rename, same dir = same filesystem). list() returns
 // only real `<runId>.json` files and never follows a symlink (lstat skip).
-import { readdirSync, readFileSync, lstatSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { closeSync, readdirSync, readFileSync, openSync, lstatSync, mkdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { randomUUID } from "node:crypto";
 import { join, resolve } from "node:path";
-import { assertContainedRealPath, resolveWithinWorkspace, } from "@oscharko-dev/keiko-workspace";
+import { resolveWithinWorkspace } from "@oscharko-dev/keiko-workspace";
 import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
 import { EvidenceReadError, EvidenceWriteError, InvalidRunIdError } from "./errors.js";
 import { assertValidRunId } from "./runid.js";
 const MANIFEST_SUFFIX = ".json";
+const MANIFEST_LOCK_SUFFIX = ".lock";
+const MANIFEST_LOCK_TIMEOUT_MS = 5_000;
+const MANIFEST_LOCK_POLL_MS = 25;
 // POSIX limits filenames to 255 bytes. Exceeding this causes an ENAMETOOLONG error whose message
 // includes the absolute path. Guard before any fs call so no path ever leaks (CWE-209).
 const POSIX_FILENAME_LIMIT = 255;
-function assertManifestFilenameFits(runId) {
-    if (runId.length + MANIFEST_SUFFIX.length > POSIX_FILENAME_LIMIT) {
+function assertEvidenceFilenameFits(runId, suffix) {
+    if (runId.length + suffix.length > POSIX_FILENAME_LIMIT) {
         throw new InvalidRunIdError("runId produces a filename that exceeds the filesystem limit");
     }
 }
+function assertManifestFilenameFits(runId) {
+    assertEvidenceFilenameFits(runId, MANIFEST_SUFFIX);
+}
+function assertLockFilenameFits(runId) {
+    assertEvidenceFilenameFits(runId, MANIFEST_LOCK_SUFFIX);
+}
 // The workspace-relative default evidence base dir (ADR-0010 D4): predictable, local, .gitignored.
 export const DEFAULT_EVIDENCE_DIR = "./.keiko/evidence";
 // Single source of the output-location precedence (ADR-0010 D4): an explicit value (CLI
@@ -41,6 +50,12 @@ export function createInMemoryEvidenceStore() {
             data.set(runId, json);
             return `${runId}${MANIFEST_SUFFIX}`;
         },
+        update: (runId, update) => {
+            assertValidRunId(runId);
+            const next = update(data.get(runId));
+            data.set(runId, next);
+            return `${runId}${MANIFEST_SUFFIX}`;
+        },
         list: () => [...data.keys()].sort(),
         get: (runId) => {
             assertValidRunId(runId);
@@ -79,13 +94,14 @@ function existingBaseDir(baseDir, fs) {
         throw new EvidenceReadError(`cannot read evidence directory: ${error instanceof Error ? error.message : "unknown"}`);
     }
 }
-// Returns the realpath-contained absolute path of <runId>.json inside the base dir, or throws if it
-// would escape. The runId is validated first so no separator/`..`/NUL can reach the join.
-function containedManifestPath(runId, realBase, fs) {
+// Returns the lexical absolute path of <runId>.json inside the already-real base dir. The runId is
+// validated first so no separator/`..`/NUL can reach the join. Final manifest operations must target
+// this ledger entry directly and then lstat it; using the entry realpath would follow in-base
+// symlinks and mutate a different manifest.
+function lexicalManifestPath(runId, realBase) {
     assertValidRunId(runId);
     assertManifestFilenameFits(runId);
-    const lexical = resolveWithinWorkspace(realBase, `${runId}${MANIFEST_SUFFIX}`);
-    return assertContainedRealPath(fs, realBase, lexical, `${runId}${MANIFEST_SUFFIX}`);
+    return resolveWithinWorkspace(realBase, `${runId}${MANIFEST_SUFFIX}`);
 }
 function isManifestName(name) {
     if (!name.endsWith(MANIFEST_SUFFIX)) {
@@ -142,16 +158,27 @@ function atomicWrite(target, json, randomSuffix) {
         throw new EvidenceWriteError(`evidence write failed: ${error instanceof Error ? error.message : "unknown"}`);
     }
 }
+function assertWritableLedgerEntry(target, fs) {
+    const entry = lstatSync(target, { throwIfNoEntry: false });
+    if (entry === undefined) {
+        return;
+    }
+    if (!entry.isFile() || !isSingleLinkRegularFile(target, fs)) {
+        throw new EvidenceWriteError("cannot overwrite a non-ledger evidence manifest");
+    }
+}
 function reportLocation(baseDir, fs, runId) {
     assertValidRunId(runId);
+    assertManifestFilenameFits(runId);
     const realBase = existingBaseDir(baseDir, fs);
     return realBase === undefined
         ? join(resolve(baseDir), `${runId}${MANIFEST_SUFFIX}`)
-        : containedManifestPath(runId, realBase, fs);
+        : lexicalManifestPath(runId, realBase);
 }
 function putManifest(baseDir, fs, randomSuffix, runId, json) {
     const realBase = prepareBaseDir(baseDir, fs);
-    const target = containedManifestPath(runId, realBase, fs);
+    const target = lexicalManifestPath(runId, realBase);
+    assertWritableLedgerEntry(target, fs);
     atomicWrite(target, json, randomSuffix);
     return target;
 }
@@ -180,12 +207,100 @@ function getManifest(baseDir, fs, runId) {
         throw new EvidenceReadError(`cannot read evidence manifest: ${error instanceof Error ? error.message : "unknown"}`);
     }
 }
+function sleepSync(ms) {
+    const waitBuffer = new SharedArrayBuffer(4);
+    const waitView = new Int32Array(waitBuffer);
+    Atomics.wait(waitView, 0, 0, ms);
+}
+function acquireManifestLock(realBase, runId) {
+    assertValidRunId(runId);
+    assertLockFilenameFits(runId);
+    const lockPath = resolveWithinWorkspace(realBase, `${runId}${MANIFEST_LOCK_SUFFIX}`);
+    const deadline = Date.now() + MANIFEST_LOCK_TIMEOUT_MS;
+    let fd;
+    while (fd === undefined) {
+        try {
+            fd = openSync(lockPath, "wx");
+        }
+        catch (error) {
+            if (retryManifestLock(error, lockPath, deadline))
+                continue;
+            throw new EvidenceWriteError(`evidence update lock failed: ${error instanceof Error ? error.message : "unknown"}`);
+        }
+    }
+    return () => {
+        try {
+            closeSync(fd);
+        }
+        finally {
+            rmSync(lockPath, { force: true });
+        }
+    };
+}
+function retryManifestLock(error, lockPath, deadline) {
+    if (errorCode(error) !== "EEXIST") {
+        return false;
+    }
+    if (lockIsStale(lockPath)) {
+        rmSync(lockPath, { force: true });
+        return true;
+    }
+    if (Date.now() >= deadline) {
+        return false;
+    }
+    sleepSync(MANIFEST_LOCK_POLL_MS);
+    return true;
+}
+function errorCode(error) {
+    if (typeof error !== "object" || error === null || !("code" in error)) {
+        return undefined;
+    }
+    return typeof error.code === "string" ? error.code : undefined;
+}
+function lockIsStale(lockPath) {
+    try {
+        return Date.now() - lstatSync(lockPath).mtimeMs >= MANIFEST_LOCK_TIMEOUT_MS;
+    }
+    catch {
+        return true;
+    }
+}
+function readManifestForUpdate(target, fs) {
+    try {
+        const entry = lstatSync(target, { throwIfNoEntry: false });
+        if (entry === undefined) {
+            return undefined;
+        }
+        if (!entry.isFile() || !isSingleLinkRegularFile(target, fs)) {
+            throw new EvidenceWriteError("cannot update a non-ledger evidence manifest");
+        }
+        return readFileSync(target, "utf8");
+    }
+    catch (error) {
+        if (error instanceof EvidenceWriteError) {
+            throw error;
+        }
+        throw new EvidenceReadError(`cannot read evidence manifest: ${error instanceof Error ? error.message : "unknown"}`);
+    }
+}
+function updateManifest(baseDir, fs, randomSuffix, runId, update) {
+    const realBase = prepareBaseDir(baseDir, fs);
+    const target = lexicalManifestPath(runId, realBase);
+    const releaseLock = acquireManifestLock(realBase, runId);
+    try {
+        atomicWrite(target, update(readManifestForUpdate(target, fs)), randomSuffix);
+        return target;
+    }
+    finally {
+        releaseLock();
+    }
+}
 function deleteManifest(baseDir, fs, runId) {
     const realBase = existingBaseDir(baseDir, fs);
     if (realBase === undefined) {
         return;
     }
-    const target = containedManifestPath(runId, realBase, fs);
+    const target = lexicalManifestPath(runId, realBase);
     if (lstatSync(target, { throwIfNoEntry: false })?.isFile() !== true) {
         return;
     }
@@ -197,6 +312,7 @@ function deleteManifest(baseDir, fs, runId) {
 export function createNodeEvidenceStore(baseDir, fs = nodeWorkspaceFs, randomSuffix = randomUUID) {
     return {
         put: (runId, json) => putManifest(baseDir, fs, randomSuffix, runId, json),
+        update: (runId, update) => updateManifest(baseDir, fs, randomSuffix, runId, update),
         list: () => listManifests(baseDir, fs),
         get: (runId) => getManifest(baseDir, fs, runId),
         location: (runId) => reportLocation(baseDir, fs, runId),

package/node_modules/@oscharko-dev/keiko-evidence/dist/workflow-evidence.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-evidence.d.ts","sourceRoot":"","sources":["../src/workflow-evidence.ts"],"names":[],"mappings":"AAUA,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAI9D,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAGjE,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAG3D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CACvF;AAID,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAUD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,iBAAiB,EAAE,GACnC,gBAAgB,CAAC,aAAa,CAAC,CAmBjC;AAMD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,SAAS,iBAAiB,EAAE,EACpC,MAAM,EAAE,OAAO,EACf,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,EAC9D,OAAO,GAAE;IAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAA;CAAO,GAC/E,gBAAgB,CA+BlB;AAmBD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,SAAS,iBAAiB,EAAE,EACpC,GAAG,EAAE,sBAAsB,EAC3B,OAAO,GAAE;IAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAA;CAAO,GAC/E,cAAc,CAYhB"}
+{"version":3,"file":"workflow-evidence.d.ts","sourceRoot":"","sources":["../src/workflow-evidence.ts"],"names":[],"mappings":"AAUA,OAAO,EAAuB,KAAK,cAAc,EAAE,MAAM,aAAa,CAAC;AAEvE,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EAGL,KAAK,SAAS,EAEf,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAI9D,MAAM,MAAM,eAAe,GAAG,YAAY,GAAG,mBAAmB,CAAC;AAGjE,MAAM,MAAM,sBAAsB,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;AAE1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAC;IACxB,QAAQ,CAAC,iBAAiB,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAC;IAG3D,QAAQ,CAAC,iBAAiB,CAAC,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,CAAC,GAAG,SAAS,CAAC;CACvF;AAID,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,sBAAsB,CAAC;IACxC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C;AAID,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAUD,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,iBAAiB,EAAE,GACnC,gBAAgB,CAAC,aAAa,CAAC,CAmBjC;AAMD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,SAAS,iBAAiB,EAAE,EACpC,MAAM,EAAE,OAAO,EACf,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,SAAS,GAAG,SAAS,EAC9D,OAAO,GAAE;IAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAA;CAAO,GAC/E,gBAAgB,CA6BlB;AAmBD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,mBAAmB,EAC7B,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,SAAS,iBAAiB,EAAE,EACpC,GAAG,EAAE,sBAAsB,EAC3B,OAAO,GAAE;IAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC,iBAAiB,CAAC,CAAA;CAAO,GAC/E,cAAc,CAMhB"}

package/node_modules/@oscharko-dev/keiko-evidence/dist/workflow-evidence.js

@@ -67,9 +67,7 @@ export function buildWorkflowManifest(identity, events, report, costClassResolve
         verification: verificationOf(report),
         patch: patchOf(report),
         failure: undefined,
-        ...(options.governedHandoff === undefined
-            ? {}
-            : { governedHandoff: options.governedHandoff }),
+        ...(options.governedHandoff === undefined ? {} : { governedHandoff: options.governedHandoff }),
     };
 }
 function contextOf(workspaceRoot) {

package/node_modules/@oscharko-dev/keiko-evidence/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oscharko-dev/keiko-evidence",
-  "version": "0.2.0-beta.4",
+  "version": "0.2.0-beta.6",
   "private": true,
   "type": "module",
   "license": "Apache-2.0",