@deftai/directive-core 0.107.0 → 0.108.0

package/dist/vbrief-build/parity-scenarios.js

@@ -2,7 +2,7 @@ import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { createScopeVbrief, referenceWithDefaultTrust, slugify } from "./build.js";
 import { pythonJsonPretty } from "./json.js";
-import { atomicWriteProjectDefinition, loadProjectDefinitionForMutation, projectDefinitionMutationLock, } from "./project-definition-io.js";
+import { withProjectDefinitionMutation } from "./project-definition-mutation.js";
 import { buildScopeVbriefFromReconciled, folderForStatus, planStatusMatchesFolder, } from "./routing.js";
 import { deriveOverviewNarrative, extractTechStack, firstProseParagraph, parseRoadmapItems, resolveRepoUrl, } from "./sources.js";
 import { createSpeckitScopeVbrief, dependenciesForItem, edgeNodes, migrateSpeckitPlan, speckitIpIndex, speckitIpSlug, } from "./speckit.js";
@@ -209,11 +209,11 @@ export function runParityScenario(name, ctx) {
             const pdPath = join(vbriefDir, "PROJECT-DEFINITION.xbrief.json");
             writeFileSync(pdPath, pythonJsonPretty(seed), "utf8");
             let roundtrip = {};
-            projectDefinitionMutationLock(ctx.fixtureRoot, () => {
-                const [data, path] = loadProjectDefinitionForMutation(ctx.fixtureRoot);
+            withProjectDefinitionMutation(ctx.fixtureRoot, (mutation) => {
+                const data = mutation.load();
                 data.plan.policy = { wipCap: 12 };
-                atomicWriteProjectDefinition(path, data);
-                roundtrip = JSON.parse(readFileSync(path, "utf8"));
+                mutation.persist(data);
+                roundtrip = JSON.parse(readFileSync(mutation.artifactPath, "utf8"));
             });
             return { scenario: name, ok: true, payload: roundtrip };
         }

package/dist/vbrief-build/project-definition-io.d.ts

@@ -1,4 +1,15 @@
 import type { JsonObject } from "./types.js";
+/** Setup override for a noncanonical PROJECT-DEFINITION path. */
+export declare const ENV_PROJECT_PATH = "DEFT_PROJECT_PATH";
+/**
+ * Constant display label for a PROJECT-DEFINITION reached through the
+ * `DEFT_PROJECT_PATH` override (#3796). A configured path is operator- or
+ * environment-supplied data, so lock and loader diagnostics name this label
+ * instead of interpolating the raw path. Matches the label already used by
+ * `verify:vbrief-conformance` so one artifact reads the same way on every
+ * diagnostic surface.
+ */
+export declare const CONFIGURED_PROJECT_DEFINITION_LABEL = "<configured PROJECT-DEFINITION>";
 /**
  * Absolute path to the PROJECT-DEFINITION artifact. Layout-aware (#2302):
  * resolves `xbrief/PROJECT-DEFINITION.xbrief.json` on a migrated tree, else the
@@ -6,14 +17,63 @@ import type { JsonObject } from "./types.js";
  * name the path that actually applies to the project's layout.
  */
 export declare function projectDefinitionPath(projectRoot: string): string;
+/**
+ * Control-safe label for an artifact path in a human diagnostic (#3796).
+ * A configured artifact collapses to {@link CONFIGURED_PROJECT_DEFINITION_LABEL};
+ * a layout-resolved canonical artifact keeps its path because the layout
+ * resolver derived it rather than reading it from configuration.
+ */
+export declare function projectDefinitionArtifactLabel(artifactPath: string): string;
+/** Result of probing whether a recorded lock owner PID is still running. */
+export type ProcessLiveness = "dead" | "alive" | "unknown";
+/**
+ * Why an acquisition attempt could not take the lock. Only `contended` is
+ * ordinary traffic; the rest fail closed to manual recovery (#3796).
+ */
+export type LockBlockedReason = "contended" | "owner-alive" | "owner-liveness-unknown" | "malformed-lock-directory" | "legacy-file-sidecar";
 export interface MutationLockDeps {
     readonly sleepMs?: (ms: number) => void;
-    readonly now?: () => number;
+    /**
+     * Monotonic millisecond clock. One budget is derived from a single reading of
+     * this clock and shared by every retry and recovery branch (#3796), so a
+     * wall-clock step or a recovery detour cannot extend the acquisition window.
+     */
+    readonly monotonicNowMs?: () => number;
+    /** Total acquisition budget in milliseconds. */
+    readonly acquisitionBudgetMs?: number;
+    /**
+     * Three-state liveness oracle. Only `dead` authorises an automatic reap;
+     * `alive` (including possible PID reuse) and `unknown` fail closed.
+     */
+    readonly probeProcess?: (pid: number) => ProcessLiveness;
+    readonly writeOwner?: (fd: number, payload: string) => number;
+    readonly renameLock?: (source: string, destination: string) => void;
+    /** Test seam: fires after the stale owner entry is unlinked, before `rmdir`. */
+    readonly beforeLockDirRemove?: (lockPath: string) => void;
 }
-/** Serialise PROJECT-DEFINITION read-modify-write critical sections. */
-export declare function projectDefinitionMutationLock<T>(projectRoot: string, fn: () => T, deps?: MutationLockDeps): T;
+/** Acquisition failed within the shared budget. `reason` names the blocker. */
+export declare class ProjectDefinitionLockError extends Error {
+    readonly reason: LockBlockedReason;
+    constructor(message: string, reason: LockBlockedReason);
+}
+/**
+ * Serialise PROJECT-DEFINITION read-modify-write critical sections.
+ *
+ * Acquisition publishes a fully-materialised, non-empty owner directory by
+ * renaming it onto the public lock pathname, so no contender can observe a
+ * partial lock. Prefer {@link withProjectDefinitionMutation} in
+ * `project-definition-mutation.ts`: it binds load/parse/persist to the captured
+ * artifact path so a caller cannot lock one identity and write another (#3796).
+ */
+export declare function projectDefinitionMutationLock<T>(projectRoot: string, fn: (artifactPath: string) => T, deps?: MutationLockDeps): T;
 /** Read PROJECT-DEFINITION.vbrief.json and return ``(data, path)``. */
 export declare function loadProjectDefinitionForMutation(projectRoot: string): [JsonObject, string];
+/**
+ * Load and parse the PROJECT-DEFINITION at an already-captured path (#3796).
+ * Diagnostics name the artifact through {@link projectDefinitionArtifactLabel}
+ * so a configured path is never interpolated raw.
+ */
+export declare function parseProjectDefinitionAt(path: string): JsonObject;
 /** Atomically write ``data`` to ``path`` as pretty-printed JSON. */
 export declare function atomicWriteProjectDefinition(path: string, data: JsonObject): void;
 //# sourceMappingURL=project-definition-io.d.ts.map

package/dist/vbrief-build/project-definition-io.js

@@ -1,11 +1,23 @@
 import { randomBytes } from "node:crypto";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { closeSync, existsSync, lstatSync, mkdirSync, openSync, readdirSync, readFileSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeSync, } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
 import { containedWrite } from "../fs/contained-write.js";
 import { resolveProjectDefinitionPath } from "../layout/resolve.js";
 import { pythonJsonPretty } from "./json.js";
 import { ProjectDefinitionIOError } from "./types.js";
 const mutationThreadLock = { held: false };
+/** Setup override for a noncanonical PROJECT-DEFINITION path. */
+export const ENV_PROJECT_PATH = "DEFT_PROJECT_PATH";
+/**
+ * Constant display label for a PROJECT-DEFINITION reached through the
+ * `DEFT_PROJECT_PATH` override (#3796). A configured path is operator- or
+ * environment-supplied data, so lock and loader diagnostics name this label
+ * instead of interpolating the raw path. Matches the label already used by
+ * `verify:vbrief-conformance` so one artifact reads the same way on every
+ * diagnostic surface.
+ */
+export const CONFIGURED_PROJECT_DEFINITION_LABEL = "<configured PROJECT-DEFINITION>";
 /**
  * Absolute path to the PROJECT-DEFINITION artifact. Layout-aware (#2302):
  * resolves `xbrief/PROJECT-DEFINITION.xbrief.json` on a migrated tree, else the
@@ -13,23 +25,209 @@ const mutationThreadLock = { held: false };
  * name the path that actually applies to the project's layout.
  */
 export function projectDefinitionPath(projectRoot) {
+    const override = process.env[ENV_PROJECT_PATH]?.trim();
+    if (override) {
+        const configuredPath = resolve(projectRoot, override);
+        return existsSync(configuredPath) ? realpathSync(configuredPath) : configuredPath;
+    }
     return resolveProjectDefinitionPath(resolve(projectRoot));
 }
+/**
+ * Control-safe label for an artifact path in a human diagnostic (#3796).
+ * A configured artifact collapses to {@link CONFIGURED_PROJECT_DEFINITION_LABEL};
+ * a layout-resolved canonical artifact keeps its path because the layout
+ * resolver derived it rather than reading it from configuration.
+ */
+export function projectDefinitionArtifactLabel(artifactPath) {
+    return process.env[ENV_PROJECT_PATH]?.trim() ? CONFIGURED_PROJECT_DEFINITION_LABEL : artifactPath;
+}
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
 function defaultSleep(ms) {
-    const end = Date.now() + ms;
-    while (Date.now() < end) {
-        /* spin */
+    Atomics.wait(sleepCell, 0, 0, ms);
+}
+const DEFAULT_ACQUISITION_BUDGET_MS = 30_000;
+const LOCK_OWNER_ENTRY_RE = /^([1-9]\d*)-([a-f0-9]{32})$/;
+const RENAME_CONTENTION_CODES = new Set([
+    "EACCES",
+    "EEXIST",
+    "EISDIR",
+    "ENOTDIR",
+    "ENOTEMPTY",
+    "EPERM",
+]);
+/** Acquisition failed within the shared budget. `reason` names the blocker. */
+export class ProjectDefinitionLockError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.name = "ProjectDefinitionLockError";
+        this.reason = reason;
+    }
+}
+function defaultProbeProcess(pid) {
+    try {
+        process.kill(pid, 0);
+        return "alive";
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ESRCH")
+            return "dead";
+        // EPERM proves a process holds the PID but not that we may signal it. That
+        // is indistinguishable from a live owner, so it is never a reap licence.
+        if (code === "EPERM")
+            return "alive";
+        return "unknown";
+    }
+}
+function createAcquisitionBudget(monotonicNowMs, totalMs) {
+    const startedAt = monotonicNowMs();
+    return {
+        expired: () => monotonicNowMs() - startedAt >= totalMs,
+        totalMs,
+    };
+}
+function lstatIfExists(path) {
+    return lstatSync(path, { throwIfNoEntry: false }) ?? null;
+}
+function parseDirectoryLockOwnerEntry(entryName) {
+    const match = LOCK_OWNER_ENTRY_RE.exec(entryName);
+    if (match === null)
+        return null;
+    const pid = Number(match[1]);
+    if (!Number.isSafeInteger(pid) || pid <= 0 || match[2] === undefined)
+        return null;
+    return { pid, token: match[2], entryName };
+}
+/**
+ * Read the single owner entry of a well-formed lock directory. Any other shape
+ * (empty, multiple entries, unparseable name) is deliberately `null` -- the
+ * caller must then fail closed rather than guess which entry owns the lock.
+ */
+function readDirectoryLockOwner(lockPath) {
+    let entries;
+    try {
+        entries = readdirSync(lockPath);
     }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    if (entries.length !== 1)
+        return null;
+    return parseDirectoryLockOwnerEntry(entries[0] ?? "");
 }
-/** Serialise PROJECT-DEFINITION read-modify-write critical sections. */
+/**
+ * Reap a current-version directory lock whose owner is unambiguously dead.
+ *
+ * The unique owner entry is removed first: exactly one contender can win that
+ * unlink, and only the winner may `rmdir`. Because every published lock
+ * directory is non-empty at the instant it becomes visible, a delayed `rmdir`
+ * from an older generation cannot remove a replacement -- it fails `ENOTEMPTY`.
+ *
+ * Reaping is automatic only for a `dead` liveness result. `alive` (which cannot
+ * be distinguished from PID reuse) and `unknown` fail closed, as does any
+ * malformed directory: age is not evidence of safety (#3796).
+ */
+function reapDirectoryLock(lockPath, probeProcess, beforeLockDirRemove) {
+    const owner = readDirectoryLockOwner(lockPath);
+    if (owner === null) {
+        return { reaped: false, reason: "malformed-lock-directory" };
+    }
+    const liveness = probeProcess(owner.pid);
+    if (liveness === "alive")
+        return { reaped: false, reason: "owner-alive" };
+    if (liveness === "unknown")
+        return { reaped: false, reason: "owner-liveness-unknown" };
+    try {
+        unlinkSync(join(lockPath, owner.entryName));
+    }
+    catch (err) {
+        // Another contender won the entry unlink; only that winner may rmdir.
+        if (err.code === "ENOENT") {
+            return { reaped: false, reason: "contended" };
+        }
+        throw err;
+    }
+    beforeLockDirRemove(lockPath);
+    try {
+        rmdirSync(lockPath);
+        return { reaped: true };
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return { reaped: true };
+        // A replacement generation was published into this pathname while the
+        // rmdir was delayed. It is non-empty, so the rmdir cannot destroy it.
+        if (code === "ENOTEMPTY" || code === "EEXIST") {
+            return { reaped: false, reason: "contended" };
+        }
+        throw err;
+    }
+}
+function describeLockFailure(artifactLabel, lockPath, reason, budgetMs) {
+    // The sidecar name is derived from the artifact name, so naming it would leak
+    // a configured filename back into a message that is supposed to be labelled.
+    const sidecarName = artifactLabel === CONFIGURED_PROJECT_DEFINITION_LABEL ? ".lock" : basename(lockPath);
+    const header = `timed out acquiring the PROJECT-DEFINITION mutation lock for ${artifactLabel} ` +
+        `after ${budgetMs}ms (blocked by: ${reason}).`;
+    if (reason === "legacy-file-sidecar") {
+        return [
+            header,
+            "A legacy single-file lock sidecar holds the public lock pathname. It is",
+            "never removed or moved automatically: releasing that pathname would let a",
+            "new waiter enter while the legacy holder's descriptor and critical section",
+            "are still live.",
+            "Manual recovery:",
+            "  1. Stop every legacy deft client that mutates this project.",
+            "  2. Confirm no PROJECT-DEFINITION mutation is running.",
+            `  3. Remove the '${sidecarName}' sidecar beside ${artifactLabel}.`,
+        ].join("\n");
+    }
+    if (reason === "malformed-lock-directory" || reason === "owner-liveness-unknown") {
+        return [
+            header,
+            "The lock state cannot be attributed to a known owner, so it is never",
+            "recovered automatically -- elapsed time is not evidence that the owner is",
+            "gone.",
+            "Manual recovery:",
+            "  1. Stop every deft client that mutates this project.",
+            "  2. Confirm no PROJECT-DEFINITION mutation is running.",
+            `  3. Remove the '${sidecarName}' lock directory beside ${artifactLabel}.`,
+        ].join("\n");
+    }
+    return [
+        header,
+        "Another PROJECT-DEFINITION mutation still holds the lock. Retry once it",
+        "completes; if the owner has gone without releasing, stop all deft clients",
+        `and remove the '${sidecarName}' lock directory beside ${artifactLabel}.`,
+    ].join("\n");
+}
+/**
+ * Serialise PROJECT-DEFINITION read-modify-write critical sections.
+ *
+ * Acquisition publishes a fully-materialised, non-empty owner directory by
+ * renaming it onto the public lock pathname, so no contender can observe a
+ * partial lock. Prefer {@link withProjectDefinitionMutation} in
+ * `project-definition-mutation.ts`: it binds load/parse/persist to the captured
+ * artifact path so a caller cannot lock one identity and write another (#3796).
+ */
 export function projectDefinitionMutationLock(projectRoot, fn, deps = {}) {
     const sleepMs = deps.sleepMs ?? defaultSleep;
-    const now = deps.now ?? Date.now;
+    const monotonicNowMs = deps.monotonicNowMs ?? (() => performance.now());
+    const budgetMs = deps.acquisitionBudgetMs ?? DEFAULT_ACQUISITION_BUDGET_MS;
+    const probeProcess = deps.probeProcess ?? defaultProbeProcess;
+    const writeOwner = deps.writeOwner ?? writeSync;
+    const renameLock = deps.renameLock ?? renameSync;
+    const beforeLockDirRemove = deps.beforeLockDirRemove ?? (() => undefined);
     // Derive the sidecar lock path from the layout-aware resolved PROJECT-DEFINITION
     // path (xbrief/ when migrated, else vbrief/) so the lock lives next to the real
     // artifact and every mutator sharing a project root contends on the same lock,
     // instead of the constant vbrief/ path which would strand a stray lock (#1260).
-    const path = resolveProjectDefinitionPath(resolve(projectRoot));
+    const path = projectDefinitionPath(projectRoot);
+    const artifactLabel = projectDefinitionArtifactLabel(path);
     const lockPath = `${path}.lock`;
     mkdirSync(dirname(lockPath), { recursive: true });
     if (mutationThreadLock.held) {
@@ -37,50 +235,178 @@ export function projectDefinitionMutationLock(projectRoot, fn, deps = {}) {
     }
     mutationThreadLock.held = true;
     let fd;
+    let ownerEntryPath;
+    let ownerToken;
+    let preparedEntryPath;
+    let preparedLockPath;
+    let acquired = false;
     try {
-        const deadline = now() + 30_000;
+        // Fully materialize owner metadata in a unique sibling directory before
+        // publishing it. Renaming the non-empty directory is the exclusive claim: no
+        // contender can observe an empty or partial lock, and a stale reaper cannot
+        // remove a replacement because replacements are non-empty when they become
+        // visible.
+        ownerToken = randomBytes(16).toString("hex");
+        const ownerEntryName = `${process.pid}-${ownerToken}`;
+        const preparedPath = `${lockPath}.claim-${ownerEntryName}`;
+        preparedLockPath = preparedPath;
+        preparedEntryPath = join(preparedPath, ownerEntryName);
+        mkdirSync(preparedPath);
+        const payload = `${JSON.stringify({ pid: process.pid, token: ownerToken })}\n`;
+        try {
+            fd = openSync(preparedEntryPath, "wx");
+            const written = writeOwner(fd, payload);
+            if (written !== Buffer.byteLength(payload)) {
+                throw new Error("short write while recording project definition lock owner");
+            }
+            closeSync(fd);
+            fd = undefined;
+        }
+        catch (err) {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    /* best-effort */
+                }
+                fd = undefined;
+            }
+            throw err;
+        }
+        // One budget, read once from the monotonic clock, shared by every retry and
+        // recovery branch below. Callback execution happens after acquisition and is
+        // deliberately outside this budget.
+        const budget = createAcquisitionBudget(monotonicNowMs, budgetMs);
+        // Every blocked branch either yields for a retry or spends the shared budget
+        // and reports the blocker it just observed. Keeping that in one place means
+        // no branch carries a reason it never reports.
+        const yieldOrFail = (reason) => {
+            if (budget.expired()) {
+                throw new ProjectDefinitionLockError(describeLockFailure(artifactLabel, lockPath, reason, budget.totalMs), reason);
+            }
+            sleepMs(20);
+        };
         while (true) {
+            // Check for a legacy file BEFORE attempting to publish. POSIX `rename`
+            // refuses to move a directory onto a file (ENOTDIR), but Windows
+            // `MoveFileEx` is called with MOVEFILE_REPLACE_EXISTING and will happily
+            // replace the file -- which would destroy the legacy sidecar this
+            // protocol exists to preserve. So absence of a non-directory at the
+            // public pathname is a precondition of publication, not a side effect of
+            // it. (A legacy client that creates the sidecar inside the window between
+            // this check and the rename is still a Windows-only residual; nothing in
+            // portable Node makes the publish itself conditional on the destination.)
+            const existing = lstatIfExists(lockPath);
+            if (existing !== null && !existing.isDirectory()) {
+                yieldOrFail("legacy-file-sidecar");
+                continue;
+            }
             try {
-                fd = openSync(lockPath, "a+");
-                const existing = readFileSync(lockPath);
-                if (existing.length === 0) {
-                    writeSync(fd, Buffer.from("\0"));
-                }
+                renameLock(preparedPath, lockPath);
+                acquired = true;
+                preparedLockPath = undefined;
+                preparedEntryPath = undefined;
+                ownerEntryPath = join(lockPath, ownerEntryName);
                 break;
             }
             catch (err) {
                 const code = err.code;
-                if (code !== "EACCES" && code !== "EBUSY") {
+                if (code === undefined || !RENAME_CONTENTION_CODES.has(code)) {
                     throw err;
                 }
-                if (now() > deadline) {
-                    throw err;
+                const lockStat = lstatIfExists(lockPath);
+                if (lockStat === null) {
+                    // Windows may surface destination collisions as EACCES/EPERM, but
+                    // without a destination these are permission failures rather than
+                    // contention. Propagate them instead of spinning until timeout.
+                    if (code === "EACCES" || code === "EPERM")
+                        throw err;
+                    // The observed owner released between rename and inspection.
+                    continue;
                 }
-                sleepMs(20);
+                if (lockStat.isDirectory()) {
+                    const outcome = reapDirectoryLock(lockPath, probeProcess, beforeLockDirRemove);
+                    if (outcome.reaped)
+                        continue;
+                    yieldOrFail(outcome.reason);
+                    continue;
+                }
+                // A legacy client took the public lock pathname with a plain file
+                // between the pre-check above and this rename. `rename` is atomic name
+                // movement, not compare-and-remove: vacating this name -- by unlink or
+                // by quarantine -- hands it to a non-cooperating `open(..., "wx")`
+                // waiter while the displaced holder's descriptor and critical section
+                // stay live. So the file is preserved and recovery is manual (#3796).
+                yieldOrFail("legacy-file-sidecar");
             }
         }
-        return fn();
+        return fn(path);
     }
     finally {
-        if (fd !== undefined) {
-            closeSync(fd);
-        }
-        mutationThreadLock.held = false;
         try {
-            if (existsSync(lockPath)) {
-                unlinkSync(lockPath);
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            if (acquired) {
+                try {
+                    if (ownerEntryPath !== undefined && ownerToken !== undefined) {
+                        const current = readDirectoryLockOwner(lockPath);
+                        if (current?.token === ownerToken &&
+                            join(lockPath, current.entryName) === ownerEntryPath) {
+                            unlinkSync(ownerEntryPath);
+                            rmdirSync(lockPath);
+                        }
+                    }
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+            else {
+                // Publication never happened: drop the prepared owner so a crash-free
+                // failure path leaves no litter. Surviving litter from a crash stays
+                // fail-closed rather than being age-guessed into safety.
+                try {
+                    if (preparedEntryPath !== undefined)
+                        unlinkSync(preparedEntryPath);
+                }
+                catch {
+                    /* best-effort */
+                }
+                try {
+                    if (preparedLockPath !== undefined)
+                        rmdirSync(preparedLockPath);
+                }
+                catch {
+                    /* best-effort */
+                }
             }
         }
-        catch {
-            /* best-effort */
+        finally {
+            mutationThreadLock.held = false;
         }
     }
 }
 /** Read PROJECT-DEFINITION.vbrief.json and return ``(data, path)``. */
 export function loadProjectDefinitionForMutation(projectRoot) {
     const path = projectDefinitionPath(projectRoot);
+    return [parseProjectDefinitionAt(path), path];
+}
+/**
+ * Load and parse the PROJECT-DEFINITION at an already-captured path (#3796).
+ * Diagnostics name the artifact through {@link projectDefinitionArtifactLabel}
+ * so a configured path is never interpolated raw.
+ */
+export function parseProjectDefinitionAt(path) {
+    const label = projectDefinitionArtifactLabel(path);
     if (!existsSync(path)) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION not found at ${path}; run task triage:welcome / ` +
+        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION not found at ${label}; run task triage:welcome / ` +
             "task triage:bootstrap to scaffold one first.");
     }
     let raw;
@@ -89,7 +415,7 @@ export function loadProjectDefinitionForMutation(projectRoot) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new ProjectDefinitionIOError(`Could not read PROJECT-DEFINITION at ${path}: ${msg}`);
+        throw new ProjectDefinitionIOError(`Could not read PROJECT-DEFINITION at ${label}: ${msg}`);
     }
     let data;
     try {
@@ -97,12 +423,12 @@ export function loadProjectDefinitionForMutation(projectRoot) {
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} is not valid JSON: ${msg}`);
+        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${label} is not valid JSON: ${msg}`);
     }
     if (typeof data !== "object" || data === null || Array.isArray(data)) {
-        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${path} top-level value is not a JSON object`);
+        throw new ProjectDefinitionIOError(`PROJECT-DEFINITION at ${label} top-level value is not a JSON object`);
     }
-    return [structuredClone(data), path];
+    return structuredClone(data);
 }
 /** Atomically write ``data`` to ``path`` as pretty-printed JSON. */
 export function atomicWriteProjectDefinition(path, data) {

package/dist/vbrief-build/project-definition-mutation.d.ts

@@ -0,0 +1,32 @@
+import { type MutationLockDeps } from "./project-definition-io.js";
+import type { JsonObject } from "./types.js";
+/**
+ * Capability handed to a PROJECT-DEFINITION mutation critical section (#3796).
+ *
+ * The artifact identity is captured once, when the lock is acquired, and every
+ * read and write goes through this object. That is what makes "every mutator
+ * uses the shared lock" checkable: a caller cannot resolve the path again, so it
+ * cannot lock one artifact and then load or persist a different one after a
+ * configured path or symlink is retargeted mid-section.
+ */
+export interface ProjectDefinitionMutation {
+    /** Artifact path captured at lock acquisition. Stable for the section. */
+    readonly artifactPath: string;
+    /** Control-safe label for this artifact in diagnostics. */
+    readonly artifactLabel: string;
+    /** Load and parse the captured artifact. Throws `ProjectDefinitionIOError`. */
+    load(): JsonObject;
+    /** Atomically persist `data` to the captured artifact under containment. */
+    persist(data: JsonObject): void;
+}
+/**
+ * Run `fn` inside the shared PROJECT-DEFINITION mutation lock with load, parse
+ * and persist bound to the artifact identity captured at acquisition.
+ *
+ * This is the only sanctioned mutation entry point. `verify:*`-adjacent
+ * inventory coverage in `project-definition-mutation-inventory.test.ts` fails
+ * closed when production code reaches for the raw resolver, the raw lock, or the
+ * raw write sink instead (#3796).
+ */
+export declare function withProjectDefinitionMutation<T>(projectRoot: string, fn: (mutation: ProjectDefinitionMutation) => T, deps?: MutationLockDeps): T;
+//# sourceMappingURL=project-definition-mutation.d.ts.map

package/dist/vbrief-build/project-definition-mutation.js

@@ -0,0 +1,43 @@
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { assertWriteTargetSafe } from "../fs/projection-containment.js";
+import { atomicWriteProjectDefinition, parseProjectDefinitionAt, projectDefinitionArtifactLabel, projectDefinitionMutationLock, } from "./project-definition-io.js";
+/**
+ * Containment root for a persist.
+ *
+ * For an in-tree artifact this is the project root, so a force-added directory
+ * symlink anywhere on the way down (`xbrief/` and friends) fails closed before
+ * temp+rename -- the #3042 / #3077 guarantee. A `DEFT_PROJECT_PATH` override may
+ * legitimately resolve outside the project root, and refusing those writes would
+ * be a new restriction rather than a mutation-identity fix, so those fall back to
+ * the artifact's own directory and keep the leaf-symlink refusal.
+ */
+function containmentRootFor(projectRoot, artifactPath) {
+    const rel = relative(projectRoot, resolve(artifactPath));
+    const inTree = rel.length > 0 && !rel.startsWith("..") && !isAbsolute(rel);
+    return inTree ? projectRoot : dirname(resolve(artifactPath));
+}
+/**
+ * Run `fn` inside the shared PROJECT-DEFINITION mutation lock with load, parse
+ * and persist bound to the artifact identity captured at acquisition.
+ *
+ * This is the only sanctioned mutation entry point. `verify:*`-adjacent
+ * inventory coverage in `project-definition-mutation-inventory.test.ts` fails
+ * closed when production code reaches for the raw resolver, the raw lock, or the
+ * raw write sink instead (#3796).
+ */
+export function withProjectDefinitionMutation(projectRoot, fn, deps = {}) {
+    const root = resolve(projectRoot);
+    return projectDefinitionMutationLock(projectRoot, (artifactPath) => {
+        const mutation = {
+            artifactPath,
+            artifactLabel: projectDefinitionArtifactLabel(artifactPath),
+            load: () => parseProjectDefinitionAt(artifactPath),
+            persist: (data) => {
+                assertWriteTargetSafe(containmentRootFor(root, artifactPath), resolve(artifactPath));
+                atomicWriteProjectDefinition(artifactPath, data);
+            },
+        };
+        return fn(mutation);
+    }, deps);
+}
+//# sourceMappingURL=project-definition-mutation.js.map

package/dist/vbrief-validate/conformance.d.ts

@@ -21,5 +21,6 @@ export interface ConformanceEvaluateResult {
 export declare function evaluateConformance(projectRoot: string, options?: {
     mode?: ConformanceMode;
     allowListPath?: string | null;
+    projectDefinitionPath?: string | null;
 }): ConformanceEvaluateResult;
 //# sourceMappingURL=conformance.d.ts.map