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

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.5",
+  "version": "0.2.0-beta.6",
   "private": true,
   "type": "module",
   "license": "Apache-2.0",