@blxzer/pactile 0.5.0

package/dist/pactile/runtime/paths.js

@@ -0,0 +1,201 @@
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_CANONICAL_PATHS_V1 } from "@blxzer/pactile-core";
+import { caseFoldComponent } from "./case-fold.js";
+import { normalizeNfc15 } from "./unicode-nfc.js";
+export class RuntimeError extends Error {
+    code;
+    constructor(code, message = code) {
+        super(message);
+        this.code = code;
+        this.name = "RuntimeError";
+    }
+}
+/** Do not leak native errno messages (which commonly embed absolute paths). */
+export function runtimeBoundary(fallback, action) {
+    try {
+        return action();
+    }
+    catch (error) {
+        if (error instanceof RuntimeError)
+            throw error;
+        throw new RuntimeError(fallback);
+    }
+}
+export const nodeRuntimeFileSystem = fs;
+export { caseFoldComponent } from "./case-fold.js";
+export function isMissing(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+export function maybeStat(io, target) {
+    try {
+        return io.lstatSync(target);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return null;
+        throw new RuntimeError("state-malformed");
+    }
+}
+/** Pure, no filesystem access. All data paths come from the frozen M0 contract. */
+export function resolveCanonicalPaths(projectRoot) {
+    const root = path.resolve(projectRoot);
+    const absolute = (relative) => path.join(root, relative);
+    const paths = DEFAULT_CANONICAL_PATHS_V1;
+    return {
+        projectRoot: root,
+        canonicalRoot: absolute(paths.canonicalRoot),
+        writePolicy: paths.writePolicy,
+        installStatePath: absolute(paths.installStatePath),
+        generationsPath: absolute(paths.generationsPath),
+        tilesPath: absolute(paths.tilesPath),
+        tasksPath: absolute(paths.tasksPath),
+        archivePath: absolute(paths.archivePath),
+        workspacePath: absolute(paths.workspacePath),
+        ownershipLedgerPath: absolute(paths.ownershipLedgerPath),
+        migrationJournalsPath: absolute(paths.migrationJournalsPath),
+        receiptsPath: absolute(paths.receiptsPath),
+    };
+}
+/** Portable path grammar: reject aliases (including Windows ADS/device names). */
+export function normalizeRuntimeRelativePath(value) {
+    const normalized = normalizeNfc15(value.replace(/\\/g, "/"));
+    const parts = normalized.split("/");
+    if (!normalized ||
+        normalized.startsWith("/") ||
+        parts.some((part) => !part ||
+            part === "." ||
+            part === ".." ||
+            /[<>:"|?*]/u.test(part) ||
+            Array.from(part).some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127) ||
+            /[. ]$/.test(part) ||
+            /^(con|prn|aux|nul|com[1-9¹²³]|lpt[1-9¹²³])(?:\.|$)/i.test(part))) {
+        throw new RuntimeError("outside-project");
+    }
+    return normalized;
+}
+function contained(root, target) {
+    const relative = path.relative(root, target);
+    return (relative === "" ||
+        (!relative.startsWith(`..${path.sep}`) &&
+            relative !== ".." &&
+            !path.isAbsolute(relative)));
+}
+function assertRoot(io, root) {
+    const stat = maybeStat(io, root);
+    if (stat === null)
+        throw new RuntimeError("outside-project");
+    if (stat.isSymbolicLink())
+        throw new RuntimeError("link-escape");
+    if (!stat.isDirectory())
+        throw new RuntimeError("outside-project");
+    // A symlink in any ancestor would otherwise make the lexical project boundary ambiguous.
+    const real = io.realpathSync(root);
+    if (path.relative(real, root) !== "")
+        throw new RuntimeError("link-escape");
+    return real;
+}
+/** Check each existing component without following links; reject even in-root links.
+ * Callers must use the returned NFC path and recheck immediately before I/O.
+ * This is a local cooperative-writer boundary, not an OS sandbox against a
+ * hostile same-user process replacing directory ancestors concurrently.
+ */
+export function assertCanonicalWriteTarget(projectRoot, target, io = fs) {
+    return runtimeBoundary("state-malformed", () => canonicalWriteTarget(projectRoot, target, io));
+}
+function canonicalWriteTarget(projectRoot, target, io) {
+    const root = path.resolve(projectRoot);
+    const absolute = path.isAbsolute(target)
+        ? path.resolve(target)
+        : path.resolve(root, target.replace(/\\/g, "/"));
+    if (!contained(root, absolute))
+        throw new RuntimeError("outside-project");
+    // Inspect the original spelling, not only path.resolve's collapsed result.
+    const rawRelative = path.isAbsolute(target)
+        ? path.relative(root, target)
+        : target;
+    const relative = normalizeRuntimeRelativePath(rawRelative);
+    const parts = relative.split("/");
+    const first = caseFoldComponent(parts[0]);
+    if (DEFAULT_CANONICAL_PATHS_V1.legacySources.some((source) => first === source.root)) {
+        throw new RuntimeError("legacy-write-denied");
+    }
+    if (first !== DEFAULT_CANONICAL_PATHS_V1.canonicalRoot)
+        throw new RuntimeError("outside-project");
+    if (parts[0] !== DEFAULT_CANONICAL_PATHS_V1.canonicalRoot)
+        throw new RuntimeError("canonical-collision");
+    const realRoot = assertRoot(io, root);
+    let current = root;
+    for (const [index, part] of parts.entries()) {
+        const parentStat = maybeStat(io, current);
+        if (parentStat) {
+            const matches = io
+                .readdirSync(current)
+                .filter((name) => caseFoldComponent(name) === caseFoldComponent(part));
+            if (matches.length > 1 || (matches.length === 1 && matches[0] !== part)) {
+                throw new RuntimeError("canonical-collision");
+            }
+        }
+        current = path.join(current, part);
+        const stat = maybeStat(io, current);
+        if (!stat)
+            continue;
+        if (stat.isSymbolicLink())
+            throw new RuntimeError("link-escape");
+        const real = io.realpathSync(current);
+        if (!contained(realRoot, real) || path.relative(current, real) !== "")
+            throw new RuntimeError("link-escape");
+        if (stat.isFile() && stat.nlink > 1)
+            throw new RuntimeError("link-escape");
+        if (!stat.isFile() && !stat.isDirectory())
+            throw new RuntimeError("link-escape");
+        if (index < parts.length - 1 && !stat.isDirectory())
+            throw new RuntimeError("state-malformed");
+    }
+    return current;
+}
+/** Read-only inventory. Presence never grants permission to write legacy state. */
+export function discoverRuntimeRoots(projectRoot, io = fs) {
+    return runtimeBoundary("state-malformed", () => discoverRoots(projectRoot, io));
+}
+function discoverRoots(projectRoot, io) {
+    const root = path.resolve(projectRoot);
+    assertRoot(io, root);
+    const names = io.readdirSync(root);
+    const diagnostics = [];
+    const inspect = (name) => {
+        const matches = names.filter((entry) => caseFoldComponent(entry) === name);
+        if (matches.length > 1 || (matches.length === 1 && matches[0] !== name)) {
+            diagnostics.push({ code: "canonical-collision", root: name });
+            return false;
+        }
+        if (matches.length === 0)
+            return false;
+        const stat = io.lstatSync(path.join(root, name));
+        if (stat.isSymbolicLink() ||
+            path.relative(path.join(root, name), io.realpathSync(path.join(root, name))) !== "") {
+            diagnostics.push({ code: "link-escape", root: name });
+            return false;
+        }
+        if (!stat.isDirectory()) {
+            diagnostics.push({ code: "state-malformed", root: name });
+            return false;
+        }
+        return true;
+    };
+    const canonical = {
+        root: ".pactile",
+        present: inspect(".pactile"),
+        access: "canonical-only",
+    };
+    const legacy = DEFAULT_CANONICAL_PATHS_V1.legacySources.map((source) => ({
+        ...source,
+        present: inspect(source.root),
+    }));
+    return { canonical, legacy, diagnostics };
+}
+/** Legacy lifecycle facade: intentionally does not select .pactile until Batch 2. */
+export function resolveLegacyWorkflowDirName(projectRoot) {
+    return (DEFAULT_CANONICAL_PATHS_V1.legacySources.find((source) => fs.existsSync(path.join(projectRoot, source.root)))?.root ?? null);
+}
+//# sourceMappingURL=paths.js.map

package/dist/pactile/runtime/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../../src/pactile/runtime/paths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAC;AAClE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAclD,MAAM,OAAO,YAAa,SAAQ,KAAK;IAE1B;IADX,YACW,IAAsB,EAC/B,UAAkB,IAAI;QAEtB,KAAK,CAAC,OAAO,CAAC,CAAC;QAHN,SAAI,GAAJ,IAAI,CAAkB;QAI/B,IAAI,CAAC,IAAI,GAAG,cAAc,CAAC;IAC7B,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,UAAU,eAAe,CAC7B,QAA0B,EAC1B,MAAe;IAEf,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,CAAC;IAClB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,KAAK,YAAY,YAAY;YAAE,MAAM,KAAK,CAAC;QAC/C,MAAM,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;IACnC,CAAC;AACH,CAAC;AAmBD,MAAM,CAAC,MAAM,qBAAqB,GAAsB,EAAE,CAAC;AAC3D,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEnD,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,KAAK,YAAY,KAAK,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,SAAS,CACvB,EAAqB,EACrB,MAAc;IAEd,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,SAAS,CAAC,KAAK,CAAC;YAAE,OAAO,IAAI,CAAC;QAClC,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAC5C,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,qBAAqB,CAAC,WAAmB;IAcvD,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,CAAC,QAAgB,EAAU,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACzE,MAAM,KAAK,GAAG,0BAA0B,CAAC;IACzC,OAAO;QACL,WAAW,EAAE,IAAI;QACjB,aAAa,EAAE,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC;QAC5C,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,gBAAgB,EAAE,QAAQ,CAAC,KAAK,CAAC,gBAAgB,CAAC;QAClD,eAAe,EAAE,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC;QAChD,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC;QACpC,SAAS,EAAE,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC;QACpC,WAAW,EAAE,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC;QACxC,aAAa,EAAE,QAAQ,CAAC,KAAK,CAAC,aAAa,CAAC;QAC5C,mBAAmB,EAAE,QAAQ,CAAC,KAAK,CAAC,mBAAmB,CAAC;QACxD,qBAAqB,EAAE,QAAQ,CAAC,KAAK,CAAC,qBAAqB,CAAC;QAC5D,YAAY,EAAE,QAAQ,CAAC,KAAK,CAAC,YAAY,CAAC;KAC3C,CAAC;AACJ,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,4BAA4B,CAAC,KAAa;IACxD,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IAC7D,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,IACE,CAAC,UAAU;QACX,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC;QAC1B,KAAK,CAAC,IAAI,CACR,CAAC,IAAI,EAAE,EAAE,CACP,CAAC,IAAI;YACL,IAAI,KAAK,GAAG;YACZ,IAAI,KAAK,IAAI;YACb,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CACnB,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,GAAG,CAChE;YACD,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC;YAClB,qDAAqD,CAAC,IAAI,CAAC,IAAI,CAAC,CACnE,EACD,CAAC;QACD,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,SAAS,CAAC,IAAY,EAAE,MAAc;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC7C,OAAO,CACL,QAAQ,KAAK,EAAE;QACf,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,GAAG,EAAE,CAAC;YACpC,QAAQ,KAAK,IAAI;YACjB,CAAC,IAAI,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAC9B,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,EAAqB,EAAE,IAAY;IACrD,MAAM,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACjC,IAAI,IAAI,KAAK,IAAI;QAAE,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAC7D,IAAI,IAAI,CAAC,cAAc,EAAE;QAAE,MAAM,IAAI,YAAY,CAAC,aAAa,CAAC,CAAC;IACjE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;QAAE,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,CAAC;IACnE,yFAAyF;IACzF,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE;QAAE,MAAM,IAAI,YAAY,CAAC,aAAa,CAAC,CAAC;IAC5E,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,WAAmB,EACnB,MAAc,EACd,KAAwB,EAAE;IAE1B,OAAO,eAAe,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAC7C,oBAAoB,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC,CAC9C,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAC3B,WAAmB,EACnB,MAAc,EACd,EAAqB;IAErB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QACtC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC;QACtB,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,CAAC;IACnD,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC;QAAE,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAC1E,2EAA2E;IAC3E,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;QACzC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAC7B,CAAC,CAAC,MAAM,CAAC;IACX,MAAM,QAAQ,GAAG,4BAA4B,CAAC,WAAW,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,MAAM,KAAK,GAAG,iBAAiB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1C,IACE,0BAA0B,CAAC,aAAa,CAAC,IAAI,CAC3C,CAAC,MAAM,EAAE,EAAE,CAAC,KAAK,KAAK,MAAM,CAAC,IAAI,CAClC,EACD,CAAC;QACD,MAAM,IAAI,YAAY,CAAC,qBAAqB,CAAC,CAAC;IAChD,CAAC;IACD,IAAI,KAAK,KAAK,0BAA0B,CAAC,aAAa;QACpD,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAC5C,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,0BAA0B,CAAC,aAAa;QACvD,MAAM,IAAI,YAAY,CAAC,qBAAqB,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACtC,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,MAAM,UAAU,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC1C,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,OAAO,GAAG,EAAE;iBACf,WAAW,CAAC,OAAO,CAAC;iBACpB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,iBAAiB,CAAC,IAAI,CAAC,KAAK,iBAAiB,CAAC,IAAI,CAAC,CAAC,CAAC;YACzE,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;gBACxE,MAAM,IAAI,YAAY,CAAC,qBAAqB,CAAC,CAAC;YAChD,CAAC;QACH,CAAC;QACD,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QACnC,MAAM,IAAI,GAAG,SAAS,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI;YAAE,SAAS;QACpB,IAAI,IAAI,CAAC,cAAc,EAAE;YAAE,MAAM,IAAI,YAAY,CAAC,aAAa,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,SAAS,CAAC,QAAQ,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,EAAE;YACnE,MAAM,IAAI,YAAY,CAAC,aAAa,CAAC,CAAC;QACxC,IAAI,IAAI,CAAC,MAAM,EAAE,IAAI,IAAI,CAAC,KAAK,GAAG,CAAC;YAAE,MAAM,IAAI,YAAY,CAAC,aAAa,CAAC,CAAC;QAC3E,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;YACvC,MAAM,IAAI,YAAY,CAAC,aAAa,CAAC,CAAC;QACxC,IAAI,KAAK,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE;YACjD,MAAM,IAAI,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAC9C,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAaD,mFAAmF;AACnF,MAAM,UAAU,oBAAoB,CAClC,WAAmB,EACnB,KAAwB,EAAE;IAE1B,OAAO,eAAe,CAAC,iBAAiB,EAAE,GAAG,EAAE,CAC7C,aAAa,CAAC,WAAW,EAAE,EAAE,CAAC,CAC/B,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CACpB,WAAmB,EACnB,EAAqB;IAErB,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACvC,UAAU,CAAC,EAAE,EAAE,IAAI,CAAC,CAAC;IACrB,MAAM,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,WAAW,GAAoC,EAAE,CAAC;IACxD,MAAM,OAAO,GAAG,CAAC,IAAY,EAAW,EAAE;QACxC,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;QAC3E,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,EAAE,CAAC;YACxE,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,qBAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC9D,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,MAAM,IAAI,GAAG,EAAE,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC;QACjD,IACE,IAAI,CAAC,cAAc,EAAE;YACrB,IAAI,CAAC,QAAQ,CACX,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,EACrB,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CACvC,KAAK,EAAE,EACR,CAAC;YACD,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACtD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,WAAW,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YAC1D,OAAO,KAAK,CAAC;QACf,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,MAAM,SAAS,GAAG;QAChB,IAAI,EAAE,UAAU;QAChB,OAAO,EAAE,OAAO,CAAC,UAAU,CAAC;QAC5B,MAAM,EAAE,gBAAgB;KAChB,CAAC;IACX,MAAM,MAAM,GAAG,0BAA0B,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACvE,GAAG,MAAM;QACT,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC;KAC9B,CAAC,CAAC,CAAC;IACJ,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;AAC5C,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,4BAA4B,CAC1C,WAAmB;IAEnB,OAAO,CACL,0BAA0B,CAAC,aAAa,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE,CACvD,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CACnD,EAAE,IAAI,IAAI,IAAI,CAChB,CAAC;AACJ,CAAC"}

package/dist/pactile/runtime/stores.d.ts

@@ -0,0 +1,54 @@
+import { type InstallStateV1 } from "@blxzer/pactile-core";
+import { type RuntimeFileSystem } from "./paths.js";
+export interface GenerationFile {
+    path: string;
+    fingerprint: string;
+}
+export interface GenerationSeal {
+    schemaVersion: 1;
+    generationId: string;
+    files: GenerationFile[];
+    fingerprint: string;
+}
+export interface InstallStateSnapshot {
+    state: InstallStateV1;
+    fingerprint: string;
+}
+/** Immutable generation contents live below files/, separately from store metadata. */
+export declare class GenerationStore {
+    readonly projectRoot: string;
+    private readonly io;
+    private readonly paths;
+    constructor(projectRoot: string, io?: RuntimeFileSystem);
+    private directory;
+    stage(id: string): void;
+    private assertStaging;
+    writeFile(id: string, relativePath: string, contents: string | Buffer): GenerationFile;
+    private inventory;
+    /** The caller supplies the expected inventory; unlisted or changed bytes fail seal. */
+    seal(id: string, expectedFiles: readonly GenerationFile[]): GenerationSeal;
+    verify(id: string): GenerationSeal;
+    readFile(id: string, relativePath: string): Buffer;
+    /** Verify the immutable inventory once, then read an exact requested set. */
+    readFiles(id: string, relativePaths: readonly string[]): Map<string, Buffer>;
+}
+export interface RuntimeRecovery {
+    activeGenerationId: string | null;
+    diagnostics: {
+        code: string;
+        path: string;
+    }[];
+}
+/** InstallState.generationId is the sole active pointer, updated under a CAS lock. */
+export declare class InstallStateStore {
+    readonly projectRoot: string;
+    private readonly io;
+    private readonly paths;
+    constructor(projectRoot: string, io?: RuntimeFileSystem);
+    read(): InstallStateSnapshot | null;
+    compareAndSwap(expectedFingerprint: string | null, next: InstallStateV1): InstallStateSnapshot;
+    /** Diagnostics only: never delete an unknown generation, lock or temp. */
+    recover(): RuntimeRecovery;
+    private recoverSnapshot;
+}
+//# sourceMappingURL=stores.d.ts.map

package/dist/pactile/runtime/stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../../src/pactile/runtime/stores.ts"],"names":[],"mappings":"AAGA,OAAO,EAIL,KAAK,cAAc,EACpB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAUL,KAAK,iBAAiB,EACvB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AACD,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,CAAC,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AACD,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,cAAc,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB;AA+HD,uFAAuF;AACvF,qBAAa,eAAe;IAGxB,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,OAAO,CAAC,QAAQ,CAAC,EAAE;IAHrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAEZ,WAAW,EAAE,MAAM,EACX,EAAE,GAAE,iBAAsB;IAK7C,OAAO,CAAC,SAAS;IAQjB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAqBvB,OAAO,CAAC,aAAa;IAyBrB,SAAS,CACP,EAAE,EAAE,MAAM,EACV,YAAY,EAAE,MAAM,EACpB,QAAQ,EAAE,MAAM,GAAG,MAAM,GACxB,cAAc;IA2BjB,OAAO,CAAC,SAAS;IA4BjB,uFAAuF;IACvF,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,cAAc,EAAE,GAAG,cAAc;IAsC1E,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,cAAc;IAmClC,QAAQ,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM;IAMlD,6EAA6E;IAC7E,SAAS,CAAC,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;CAwB7E;AAED,MAAM,WAAW,eAAe;IAC9B,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,WAAW,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C;AAED,sFAAsF;AACtF,qBAAa,iBAAiB;IAG1B,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,OAAO,CAAC,QAAQ,CAAC,EAAE;IAHrB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAEZ,WAAW,EAAE,MAAM,EACX,EAAE,GAAE,iBAAsB;IAK7C,IAAI,IAAI,oBAAoB,GAAG,IAAI;IAkBnC,cAAc,CACZ,mBAAmB,EAAE,MAAM,GAAG,IAAI,EAClC,IAAI,EAAE,cAAc,GACnB,oBAAoB;IA8BvB,0EAA0E;IAC1E,OAAO,IAAI,eAAe;IAI1B,OAAO,CAAC,eAAe;CA+FxB"}

package/dist/pactile/runtime/stores.js

@@ -0,0 +1,375 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash, randomUUID } from "node:crypto";
+import { canonicalizePactileJsonV1, fingerprintPactileContractV1, parseInstallStateV1, } from "@blxzer/pactile-core";
+import { RuntimeError, assertCanonicalWriteTarget, caseFoldComponent, isMissing, maybeStat, normalizeRuntimeRelativePath, resolveCanonicalPaths, runtimeBoundary, } from "./paths.js";
+function digest(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+/** Prefix every M0 ID: percent encoding alone does not escape Windows devices. */
+function generationName(id) {
+    if (!/^[a-z][a-z0-9]*(?:[._:-][a-z0-9]+)*$/.test(id))
+        throw new RuntimeError("generation-invalid");
+    return `g-${encodeURIComponent(id)}`;
+}
+function prepareDirectory(root, directory, io) {
+    const target = assertCanonicalWriteTarget(root, directory, io);
+    runtimeBoundary("atomic-replace-failed", () => io.mkdirSync(target, { recursive: true }));
+    assertCanonicalWriteTarget(root, target, io);
+}
+function writeExclusive(root, target, content, io, collisionCode = "atomic-replace-failed") {
+    assertCanonicalWriteTarget(root, target, io);
+    let descriptor;
+    try {
+        descriptor = io.openSync(target, fs.constants.O_WRONLY |
+            fs.constants.O_CREAT |
+            fs.constants.O_EXCL |
+            (fs.constants.O_NOFOLLOW ?? 0), 0o600);
+        const stat = io.fstatSync(descriptor);
+        if (!stat.isFile() || stat.nlink !== 1)
+            throw new RuntimeError("link-escape");
+        assertCanonicalWriteTarget(root, target, io);
+        io.writeFileSync(descriptor, content);
+        io.fsyncSync(descriptor);
+    }
+    catch (error) {
+        if (error instanceof RuntimeError)
+            throw error;
+        if (error instanceof Error && "code" in error && error.code === "EEXIST")
+            throw new RuntimeError(collisionCode);
+        throw new RuntimeError("atomic-replace-failed");
+    }
+    finally {
+        if (descriptor !== undefined) {
+            const openedDescriptor = descriptor;
+            runtimeBoundary("atomic-replace-failed", () => io.closeSync(openedDescriptor));
+        }
+    }
+}
+/** Cooperative cross-process lock. A crash leaves an explicit lock, never stolen. */
+function withLock(root, target, io, action) {
+    const token = randomUUID();
+    try {
+        writeExclusive(root, target, token, io);
+    }
+    catch (error) {
+        if (error instanceof RuntimeError)
+            throw error;
+        throw new RuntimeError("atomic-replace-failed", "atomic-replace-failed: writer lock unavailable");
+    }
+    try {
+        return runtimeBoundary("atomic-replace-failed", action);
+    }
+    finally {
+        // Only unlink a lock that is provably ours. Recovery reports any residue.
+        try {
+            assertCanonicalWriteTarget(root, target, io);
+            if (io.readFileSync(target, "utf8") === token)
+                io.unlinkSync(target);
+        }
+        catch {
+            /* A failed cleanup must not misreport an already-committed CAS. */
+        }
+    }
+}
+function atomicReplace(root, target, contents, io) {
+    const temporary = `${target}.tmp-${randomUUID()}`;
+    let created = false;
+    try {
+        writeExclusive(root, temporary, contents, io);
+        created = true;
+        assertCanonicalWriteTarget(root, target, io);
+        assertCanonicalWriteTarget(root, temporary, io);
+        io.renameSync(temporary, target);
+    }
+    catch (error) {
+        // Keep the old pointer. Do not delete arbitrary temp files or retry by unlinking target.
+        if (created) {
+            try {
+                assertCanonicalWriteTarget(root, temporary, io);
+                io.unlinkSync(temporary);
+            }
+            catch {
+                /* Leftover temp is discoverable by recover(). */
+            }
+        }
+        if (error instanceof RuntimeError)
+            throw error;
+        throw new RuntimeError("atomic-replace-failed");
+    }
+}
+function fileOrder(a, b) {
+    return a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+}
+/** Immutable generation contents live below files/, separately from store metadata. */
+export class GenerationStore {
+    projectRoot;
+    io;
+    paths;
+    constructor(projectRoot, io = fs) {
+        this.projectRoot = projectRoot;
+        this.io = io;
+        this.paths = resolveCanonicalPaths(projectRoot);
+    }
+    directory(id) {
+        return assertCanonicalWriteTarget(this.projectRoot, path.join(this.paths.generationsPath, generationName(id)), this.io);
+    }
+    stage(id) {
+        const directory = this.directory(id);
+        prepareDirectory(this.projectRoot, this.paths.generationsPath, this.io);
+        if (maybeStat(this.io, directory))
+            throw new RuntimeError("generation-invalid", "generation-invalid");
+        try {
+            this.io.mkdirSync(directory);
+        }
+        catch (error) {
+            if (error instanceof Error && "code" in error && error.code === "EEXIST")
+                throw new RuntimeError("generation-invalid");
+            throw new RuntimeError("atomic-replace-failed");
+        }
+        writeExclusive(this.projectRoot, path.join(directory, ".stage.json"), canonicalizePactileJsonV1({ schemaVersion: 1, generationId: id }), this.io);
+        prepareDirectory(this.projectRoot, path.join(directory, "files"), this.io);
+    }
+    assertStaging(id) {
+        const directory = this.directory(id);
+        if (maybeStat(this.io, path.join(directory, ".sealed.json")))
+            throw new RuntimeError("generation-sealed");
+        try {
+            const markerPath = assertCanonicalWriteTarget(this.projectRoot, path.join(directory, ".stage.json"), this.io);
+            const marker = JSON.parse(this.io.readFileSync(markerPath, "utf8"));
+            if (canonicalizePactileJsonV1(marker) !==
+                canonicalizePactileJsonV1({ schemaVersion: 1, generationId: id }))
+                throw new RuntimeError("generation-invalid");
+        }
+        catch (error) {
+            if (error instanceof RuntimeError)
+                throw error;
+            throw new RuntimeError("generation-invalid");
+        }
+        return directory;
+    }
+    writeFile(id, relativePath, contents) {
+        const relative = normalizeRuntimeRelativePath(relativePath);
+        const directory = this.assertStaging(id);
+        return withLock(this.projectRoot, path.join(directory, ".generation.lock"), this.io, () => {
+            this.assertStaging(id);
+            const target = assertCanonicalWriteTarget(this.projectRoot, path.join(directory, "files", relative), this.io);
+            prepareDirectory(this.projectRoot, path.dirname(target), this.io);
+            writeExclusive(this.projectRoot, target, contents, this.io, "generation-invalid");
+            return { path: relative, fingerprint: digest(contents) };
+        });
+    }
+    inventory(id) {
+        const base = path.join(this.directory(id), "files");
+        const files = [];
+        const visit = (directory) => {
+            assertCanonicalWriteTarget(this.projectRoot, directory, this.io);
+            const names = this.io.readdirSync(directory).sort();
+            const folded = names.map(caseFoldComponent);
+            if (new Set(folded).size !== folded.length)
+                throw new RuntimeError("canonical-collision");
+            for (const name of names) {
+                const target = assertCanonicalWriteTarget(this.projectRoot, path.join(directory, name), this.io);
+                const stat = this.io.lstatSync(target);
+                if (stat.isDirectory())
+                    visit(target);
+                else
+                    files.push({
+                        path: path.relative(base, target).split(path.sep).join("/"),
+                        fingerprint: digest(this.io.readFileSync(target)),
+                    });
+            }
+        };
+        visit(base);
+        return files.sort(fileOrder);
+    }
+    /** The caller supplies the expected inventory; unlisted or changed bytes fail seal. */
+    seal(id, expectedFiles) {
+        const directory = this.assertStaging(id);
+        return withLock(this.projectRoot, path.join(directory, ".generation.lock"), this.io, () => {
+            this.assertStaging(id);
+            const actual = this.inventory(id);
+            const expected = [...expectedFiles].sort(fileOrder);
+            if (canonicalizePactileJsonV1(actual) !==
+                canonicalizePactileJsonV1(expected))
+                throw new RuntimeError("generation-invalid", "generation-invalid: manifest mismatch");
+            const payload = {
+                schemaVersion: 1,
+                generationId: id,
+                files: actual,
+            };
+            const seal = {
+                ...payload,
+                fingerprint: fingerprintPactileContractV1(payload),
+            };
+            atomicReplace(this.projectRoot, path.join(directory, ".sealed.json"), canonicalizePactileJsonV1(seal), this.io);
+            return seal;
+        });
+    }
+    verify(id) {
+        const directory = this.directory(id);
+        try {
+            const marker = assertCanonicalWriteTarget(this.projectRoot, path.join(directory, ".sealed.json"), this.io);
+            const seal = JSON.parse(this.io.readFileSync(marker, "utf8"));
+            const payload = {
+                schemaVersion: 1,
+                generationId: id,
+                files: this.inventory(id),
+            };
+            const expected = {
+                ...payload,
+                fingerprint: fingerprintPactileContractV1(payload),
+            };
+            if (canonicalizePactileJsonV1(seal) !== canonicalizePactileJsonV1(expected))
+                throw new RuntimeError("generation-unsealed");
+            return expected;
+        }
+        catch (error) {
+            if (error instanceof RuntimeError &&
+                ["link-escape", "canonical-collision", "outside-project"].includes(error.code))
+                throw error;
+            throw new RuntimeError("generation-unsealed");
+        }
+    }
+    readFile(id, relativePath) {
+        return this.readFiles(id, [relativePath]).get(normalizeRuntimeRelativePath(relativePath));
+    }
+    /** Verify the immutable inventory once, then read an exact requested set. */
+    readFiles(id, relativePaths) {
+        const normalized = relativePaths.map(normalizeRuntimeRelativePath);
+        if (new Set(normalized).size !== normalized.length)
+            throw new RuntimeError("generation-invalid");
+        const seal = this.verify(id);
+        const allowed = new Set(seal.files.map((file) => file.path));
+        if (normalized.some((relative) => !allowed.has(relative)))
+            throw new RuntimeError("generation-invalid");
+        const result = new Map();
+        for (const relative of normalized) {
+            const target = assertCanonicalWriteTarget(this.projectRoot, path.join(this.directory(id), "files", relative), this.io);
+            result.set(relative, runtimeBoundary("generation-unsealed", () => this.io.readFileSync(target)));
+        }
+        return result;
+    }
+}
+/** InstallState.generationId is the sole active pointer, updated under a CAS lock. */
+export class InstallStateStore {
+    projectRoot;
+    io;
+    paths;
+    constructor(projectRoot, io = fs) {
+        this.projectRoot = projectRoot;
+        this.io = io;
+        this.paths = resolveCanonicalPaths(projectRoot);
+    }
+    read() {
+        const target = assertCanonicalWriteTarget(this.projectRoot, this.paths.installStatePath, this.io);
+        let value;
+        try {
+            value = JSON.parse(this.io.readFileSync(target, "utf8"));
+        }
+        catch (error) {
+            if (isMissing(error))
+                return null;
+            throw new RuntimeError("state-malformed");
+        }
+        const parsed = parseInstallStateV1(value);
+        if (!parsed.success)
+            throw new RuntimeError("state-malformed");
+        return { state: parsed.data, fingerprint: parsed.fingerprint };
+    }
+    compareAndSwap(expectedFingerprint, next) {
+        const parsed = parseInstallStateV1(next);
+        if (!parsed.success)
+            throw new RuntimeError("state-malformed");
+        prepareDirectory(this.projectRoot, path.dirname(this.paths.installStatePath), this.io);
+        return withLock(this.projectRoot, `${this.paths.installStatePath}.lock`, this.io, () => {
+            const current = this.read();
+            if ((current?.fingerprint ?? null) !== expectedFingerprint)
+                throw new RuntimeError("cas-mismatch");
+            new GenerationStore(this.projectRoot, this.io).verify(parsed.data.generationId);
+            atomicReplace(this.projectRoot, this.paths.installStatePath, canonicalizePactileJsonV1(parsed.data), this.io);
+            return { state: parsed.data, fingerprint: parsed.fingerprint };
+        });
+    }
+    /** Diagnostics only: never delete an unknown generation, lock or temp. */
+    recover() {
+        return runtimeBoundary("state-malformed", () => this.recoverSnapshot());
+    }
+    recoverSnapshot() {
+        const result = {
+            activeGenerationId: null,
+            diagnostics: [],
+        };
+        let pointerKnown = true;
+        const report = (code, target) => {
+            const relativePath = path
+                .relative(path.resolve(this.projectRoot), target)
+                .split(path.sep)
+                .join("/");
+            if (!result.diagnostics.some((item) => item.code === code && item.path === relativePath)) {
+                result.diagnostics.push({ code, path: relativePath });
+            }
+        };
+        try {
+            result.activeGenerationId = this.read()?.state.generationId ?? null;
+        }
+        catch (error) {
+            if (!(error instanceof RuntimeError))
+                throw error;
+            pointerKnown = false;
+            report(error.code, this.paths.installStatePath);
+        }
+        // Validate the pointer independently of directory enumeration: a missing
+        // generation (or the whole store) must never produce empty diagnostics.
+        if (result.activeGenerationId !== null) {
+            const activeTarget = path.join(this.paths.generationsPath, generationName(result.activeGenerationId));
+            try {
+                new GenerationStore(this.projectRoot, this.io).verify(result.activeGenerationId);
+            }
+            catch (error) {
+                report(error instanceof RuntimeError ? error.code : "generation-unsealed", activeTarget);
+            }
+        }
+        const directory = assertCanonicalWriteTarget(this.projectRoot, path.dirname(this.paths.installStatePath), this.io);
+        if (!maybeStat(this.io, directory))
+            return result;
+        for (const name of this.io.readdirSync(directory).sort()) {
+            if (name.startsWith("install-state.json.tmp-"))
+                report("leftover-temp", path.join(directory, name));
+            if (name === "install-state.json.lock")
+                report("leftover-lock", path.join(directory, name));
+        }
+        const generations = assertCanonicalWriteTarget(this.projectRoot, this.paths.generationsPath, this.io);
+        if (maybeStat(this.io, generations)) {
+            for (const name of this.io.readdirSync(generations).sort()) {
+                const target = path.join(generations, name);
+                try {
+                    if (!name.startsWith("g-"))
+                        throw new RuntimeError("generation-invalid");
+                    const id = decodeURIComponent(name.slice(2));
+                    if (generationName(id) !== name)
+                        throw new RuntimeError("generation-invalid");
+                    assertCanonicalWriteTarget(this.projectRoot, target, this.io);
+                    for (const metadata of this.io.readdirSync(target).sort()) {
+                        if (metadata.startsWith(".sealed.json.tmp-"))
+                            report("leftover-temp", path.join(target, metadata));
+                        if (metadata === ".generation.lock")
+                            report("leftover-lock", path.join(target, metadata));
+                    }
+                    if (id !== result.activeGenerationId)
+                        new GenerationStore(this.projectRoot, this.io).verify(id);
+                    if (!pointerKnown)
+                        report("generation-activation-unknown", target);
+                    else if (id !== result.activeGenerationId)
+                        report("orphan-generation", target);
+                }
+                catch (error) {
+                    report(error instanceof RuntimeError ? error.code : "generation-invalid", target);
+                }
+            }
+        }
+        result.diagnostics.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : a.code < b.code ? -1 : 1);
+        return result;
+    }
+}
+//# sourceMappingURL=stores.js.map