@codyswann/lisa 4.28.4 → 4.29.0

package/dist/configs/vitest/scratch-route-profile.js

@@ -0,0 +1,217 @@
+/** Immutable wrapper-authoritative scratch registries for every managed route. */
+import { env } from "node:process";
+/** JSON-array environment contract for operator-added direct-child prefixes. */
+export const SCRATCH_PREFIXES_ENV = "LISA_TEST_SCRATCH_PREFIXES";
+/** Environment assertion for the immutable route suite label. */
+export const SCRATCH_SUITE_ENV = "LISA_TEST_SCRATCH_SUITE";
+/** Maximum number of registered prefixes accepted from configuration. */
+const MAX_REGISTERED_PREFIXES = 64;
+/** Maximum bytes in one registered prefix or suite label. */
+const MAX_LABEL_BYTES = 128;
+/** Wrapper-owned base registry; operator additions may only widen prefixes. */
+const ROUTE_PROFILES = Object.freeze({
+    lisa: Object.freeze({
+        suiteLabel: "lisa",
+        registeredPrefixes: Object.freeze([
+            "changelog-",
+            "derived-",
+            "e2e-",
+            "failure-signatures-",
+            "invoked-",
+            "lisa-",
+            "maestro-",
+            "node-",
+            "review-",
+            "skipreq-",
+            "state-",
+            "vacuity-",
+            "wiki-",
+        ]),
+    }),
+    typescript: Object.freeze({
+        suiteLabel: "typescript",
+        registeredPrefixes: [],
+    }),
+    "npm-package": Object.freeze({
+        suiteLabel: "npm-package",
+        registeredPrefixes: [],
+    }),
+    node: Object.freeze({
+        suiteLabel: "node",
+        registeredPrefixes: Object.freeze(["node-"]),
+    }),
+    expo: Object.freeze({
+        suiteLabel: "expo",
+        registeredPrefixes: [],
+    }),
+    nestjs: Object.freeze({ suiteLabel: "nestjs", registeredPrefixes: [] }),
+    cdk: Object.freeze({
+        suiteLabel: "cdk",
+        registeredPrefixes: Object.freeze(["cdk.out"]),
+    }),
+    "harper-fabric": Object.freeze({
+        suiteLabel: "harper-fabric",
+        registeredPrefixes: [],
+    }),
+    phaser: Object.freeze({
+        suiteLabel: "phaser",
+        registeredPrefixes: [],
+    }),
+});
+/**
+ * Whether a label contains a control code unsafe for markers/diagnostics.
+ * @param label - Candidate label
+ * @returns True when a control code is present
+ */
+function containsControlCode(label) {
+    return [...label].some(character => {
+        const codePoint = character.codePointAt(0) ?? 0;
+        return codePoint <= 0x1f || codePoint === 0x7f;
+    });
+}
+/**
+ * Parse one inherited registry while preserving its public diagnostic.
+ * @param raw - Serialized prefix registry
+ * @returns Decoded unvalidated value
+ */
+function parsePrefixRegistry(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${SCRATCH_PREFIXES_ENV} must be a JSON array of prefixes`);
+    }
+}
+/**
+ * Read the validated bounded prefix registry inherited by scratch owners.
+ * @returns Sorted unique direct-child prefixes
+ */
+export function registeredScratchPrefixes() {
+    const raw = env[SCRATCH_PREFIXES_ENV];
+    if (raw === undefined || raw === "")
+        return [];
+    const parsed = parsePrefixRegistry(raw);
+    if (!Array.isArray(parsed) || parsed.length > MAX_REGISTERED_PREFIXES) {
+        throw new Error(`${SCRATCH_PREFIXES_ENV} must contain at most ${String(MAX_REGISTERED_PREFIXES)} prefixes`);
+    }
+    const prefixes = parsed.map(value => {
+        if (typeof value !== "string" ||
+            value === "" ||
+            Buffer.byteLength(value, "utf8") > MAX_LABEL_BYTES ||
+            value.includes("/") ||
+            value.includes("\\") ||
+            value === "." ||
+            value === "..") {
+            throw new Error(`${SCRATCH_PREFIXES_ENV} contains an invalid prefix`);
+        }
+        return value;
+    });
+    return [...new Set(prefixes)].sort((left, right) => left.localeCompare(right));
+}
+/**
+ * Read the opaque bounded suite label used for owner attribution.
+ * @returns Valid suite label
+ */
+export function scratchSuiteLabel() {
+    const label = env[SCRATCH_SUITE_ENV] ?? "vitest";
+    if (label === "" ||
+        Buffer.byteLength(label, "utf8") > MAX_LABEL_BYTES ||
+        containsControlCode(label)) {
+        throw new Error(`${SCRATCH_SUITE_ENV} contains an invalid suite label`);
+    }
+    return label;
+}
+/**
+ * Demand one bounded direct basename.
+ * @param value - Candidate value
+ * @param context - Public diagnostic context
+ * @returns Validated direct label
+ */
+function validateLabel(value, context) {
+    if (typeof value !== "string" ||
+        value === "" ||
+        Buffer.byteLength(value, "utf8") > MAX_LABEL_BYTES ||
+        containsControlCode(value) ||
+        value.includes("/") ||
+        value.includes("\\") ||
+        value === "." ||
+        value === "..") {
+        throw new Error(`${context} contains an invalid direct label`);
+    }
+    return value;
+}
+/**
+ * Decode one operator prefix registry.
+ * @param raw - Serialized registry
+ * @returns Unvalidated decoded value
+ */
+function parseOperatorPrefixes(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${SCRATCH_PREFIXES_ENV} must be a JSON array of prefixes`);
+    }
+}
+/**
+ * Parse and canonicalize operator prefix additions exactly once.
+ * @param environment - Inherited operator configuration
+ * @returns Validated operator-added prefixes
+ */
+function operatorPrefixes(environment) {
+    const raw = environment[SCRATCH_PREFIXES_ENV];
+    if (raw === undefined || raw === "")
+        return [];
+    const parsed = parseOperatorPrefixes(raw);
+    if (!Array.isArray(parsed) || parsed.length > MAX_REGISTERED_PREFIXES) {
+        throw new Error(`${SCRATCH_PREFIXES_ENV} must contain at most ${String(MAX_REGISTERED_PREFIXES)} prefixes`);
+    }
+    return parsed.map(value => validateLabel(value, SCRATCH_PREFIXES_ENV));
+}
+/**
+ * Resolve a generated route plus bounded operator additions before allocation.
+ * @param name - Exact managed route name
+ * @param environment - Inherited operator configuration
+ * @returns Deeply frozen immutable registry
+ */
+export function resolveScratchRouteProfile(name, environment = env) {
+    if (!Object.hasOwn(ROUTE_PROFILES, name)) {
+        throw new Error(`Unknown lisa-test-run scratch profile: ${name || "<missing>"}`);
+    }
+    const routeName = name;
+    const base = ROUTE_PROFILES[routeName];
+    const assertedSuite = environment[SCRATCH_SUITE_ENV];
+    if (assertedSuite !== undefined &&
+        validateLabel(assertedSuite, SCRATCH_SUITE_ENV) !== base.suiteLabel) {
+        throw new Error(`${SCRATCH_SUITE_ENV} conflicts with wrapper profile ${routeName}`);
+    }
+    const prefixes = [
+        ...new Set([...base.registeredPrefixes, ...operatorPrefixes(environment)]),
+    ].sort((left, right) => (left === right ? 0 : left < right ? -1 : 1));
+    if (prefixes.length > MAX_REGISTERED_PREFIXES) {
+        throw new Error(`${SCRATCH_PREFIXES_ENV} exceeds the ${String(MAX_REGISTERED_PREFIXES)} prefix limit after composition`);
+    }
+    return Object.freeze({
+        name: routeName,
+        suiteLabel: base.suiteLabel,
+        registeredPrefixes: Object.freeze(prefixes),
+    });
+}
+/**
+ * Assert dynamic Vitest env agrees with the frozen wrapper lease exactly.
+ * @param profile - Frozen wrapper-authoritative profile
+ * @param environment - Dynamic Vitest environment to compare
+ */
+export function assertScratchRouteProfile(profile, environment = env) {
+    const observedSuite = validateLabel(environment[SCRATCH_SUITE_ENV], SCRATCH_SUITE_ENV);
+    const observedPrefixes = operatorPrefixes(environment);
+    const canonical = [...new Set(observedPrefixes)].sort((left, right) => left === right ? 0 : left < right ? -1 : 1);
+    if (observedSuite !== profile.suiteLabel ||
+        canonical.length !== profile.registeredPrefixes.length ||
+        canonical.some((prefix, index) => prefix !== profile.registeredPrefixes[index])) {
+        throw new Error(`Vitest scratch configuration conflicts with the immutable wrapper profile: ` +
+            `expected ${profile.suiteLabel}/${JSON.stringify(profile.registeredPrefixes)}, ` +
+            `received ${observedSuite}/${JSON.stringify(canonical)}`);
+    }
+}
+//# sourceMappingURL=scratch-route-profile.js.map

package/dist/configs/vitest/scratch-route-profile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch-route-profile.js","sourceRoot":"","sources":["../../../src/configs/vitest/scratch-route-profile.ts"],"names":[],"mappings":"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"}

package/dist/configs/vitest/scratch-run-root-compatibility.d.ts

@@ -0,0 +1,33 @@
+import { writeScratchOwnerRecord } from "./scratch-owner.js";
+import type { OwnedScratchRunRoot } from "./scratch-run-root-intent.js";
+/** Optional seams for creating one transactional run root. */
+interface CreateRunRootOptions {
+    readonly now?: number;
+    readonly writeOwnerRecord?: typeof writeScratchOwnerRecord;
+}
+/**
+ * Create a legacy-compatible owned root with transactional marker rollback.
+ * @param options - Clock and marker-writer seams
+ * @param options.now - Epoch milliseconds recorded in the basename
+ * @param options.writeOwnerRecord - Injectable transactional marker writer
+ * @returns Absolute run-root path
+ */
+export declare const createRunRoot: ({ now, writeOwnerRecord, }?: CreateRunRootOptions) => string;
+/**
+ * Reclaim residue, then allocate a durable owned-root handle.
+ * @returns Owned current-process root
+ */
+export declare function reclaimAndCreateOwnedRunRoot(): OwnedScratchRunRoot;
+/**
+ * Upgrade a source/dist-compatible path memo created by an older setup copy.
+ * @param root - Existing memoized run-root path
+ * @returns Durable handle for the existing root
+ */
+export declare function adoptOwnedScratchRunRoot(root: string): OwnedScratchRunRoot;
+/**
+ * Reclaim residue, then return one current-process root path.
+ * @returns Newly allocated root path
+ */
+export declare const reclaimAndCreateRunRoot: () => string;
+export {};
+//# sourceMappingURL=scratch-run-root-compatibility.d.ts.map

package/dist/configs/vitest/scratch-run-root-compatibility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch-run-root-compatibility.d.ts","sourceRoot":"","sources":["../../../src/configs/vitest/scratch-run-root-compatibility.ts"],"names":[],"mappings":"AAgBA,OAAO,EAIL,uBAAuB,EAExB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AAQxE,8DAA8D;AAC9D,UAAU,oBAAoB;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,uBAAuB,CAAC;CAC5D;AAyBD;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,6BAG3B,oBAAyB,KAAG,MAsC9B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,4BAA4B,IAAI,mBAAmB,CAYlE;AA8BD;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CAoB1E;AAED;;;GAGG;AACH,eAAO,MAAM,uBAAuB,QAAO,MACN,CAAC"}

package/dist/configs/vitest/scratch-run-root-compatibility.js

@@ -0,0 +1,137 @@
+/** Compatibility allocation/adoption atop the owned run-root lifecycle. */
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createScratchNamespaceAuthority, parseRunRootName, removeAuthorizedScratchRoot, runRootName, } from "./scratch-authority.js";
+import { registeredScratchPrefixes, scratchSuiteLabel, } from "./scratch-route-profile.js";
+import { createScratchOwnerRecord, readScratchOwnerRecord, scratchPathIdentity, writeScratchOwnerRecord, } from "./scratch-owner.js";
+import { sweepScratchNamespace } from "./scratch-sweep.js";
+/**
+ * Create the immutable owner marker for a newly materialized root.
+ * @param authority - Pinned namespace authority
+ * @param root - Newly materialized direct root
+ * @param now - Creation epoch milliseconds
+ * @param configuration - Validated owner attribution
+ * @returns Immutable owner marker
+ */
+function createOwnerForNewRoot(authority, root, now, configuration) {
+    return createScratchOwnerRecord({
+        authority,
+        root,
+        suiteLabel: configuration.suiteLabel,
+        registeredPrefixes: configuration.registeredPrefixes,
+        now: new Date(now),
+    });
+}
+/**
+ * Create a legacy-compatible owned root with transactional marker rollback.
+ * @param options - Clock and marker-writer seams
+ * @param options.now - Epoch milliseconds recorded in the basename
+ * @param options.writeOwnerRecord - Injectable transactional marker writer
+ * @returns Absolute run-root path
+ */
+export const createRunRoot = ({ now = Date.now(), writeOwnerRecord = writeScratchOwnerRecord, } = {}) => {
+    if (!Number.isSafeInteger(now) || now < 0) {
+        throw new Error("Scratch run-root timestamp must be a non-negative integer");
+    }
+    const configuration = {
+        suiteLabel: scratchSuiteLabel(),
+        registeredPrefixes: registeredScratchPrefixes(),
+    };
+    const authority = createScratchNamespaceAuthority();
+    const root = path.join(authority.namespace.canonicalPath, runRootName(process.pid, now, randomBytes(4).toString("hex")));
+    const expectedIdentity = (() => {
+        fs.mkdirSync(root, { mode: 0o700 });
+        return scratchPathIdentity(root);
+    })();
+    try {
+        const owner = createOwnerForNewRoot(authority, root, now, configuration);
+        writeOwnerRecord(root, owner);
+    }
+    catch (error) {
+        try {
+            removeAuthorizedScratchRoot({
+                authority,
+                basename: path.basename(root),
+                expectedIdentity,
+            });
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "Scratch root allocation failed and rollback could not reclaim it");
+        }
+        throw error;
+    }
+    return root;
+};
+/**
+ * Reclaim residue, then allocate a durable owned-root handle.
+ * @returns Owned current-process root
+ */
+export function reclaimAndCreateOwnedRunRoot() {
+    const authority = createScratchNamespaceAuthority();
+    const root = (() => {
+        sweepScratchNamespace();
+        return createRunRoot();
+    })();
+    return {
+        path: root,
+        basename: path.basename(root),
+        authority,
+        owner: readScratchOwnerRecord(root),
+    };
+}
+/**
+ * Read an existing marker or atomically upgrade a legacy current root.
+ * @param authority - Pinned namespace authority
+ * @param root - Existing current-process root
+ * @param startedAt - Timestamp encoded in the recognized basename
+ * @returns Existing or newly written marker
+ */
+function readOrCreateAdoptedOwner(authority, root, startedAt) {
+    try {
+        return readScratchOwnerRecord(root);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        const owner = createScratchOwnerRecord({
+            authority,
+            root,
+            suiteLabel: scratchSuiteLabel(),
+            registeredPrefixes: registeredScratchPrefixes(),
+            now: new Date(startedAt),
+        });
+        writeScratchOwnerRecord(root, owner);
+        return owner;
+    }
+}
+/**
+ * Upgrade a source/dist-compatible path memo created by an older setup copy.
+ * @param root - Existing memoized run-root path
+ * @returns Durable handle for the existing root
+ */
+export function adoptOwnedScratchRunRoot(root) {
+    const authority = createScratchNamespaceAuthority();
+    const canonicalRoot = fs.realpathSync(root);
+    if (path.dirname(canonicalRoot) !== authority.namespace.canonicalPath ||
+        path.basename(root) !== path.basename(canonicalRoot)) {
+        throw new Error("Memoized scratch root is outside canonical authority");
+    }
+    const parsed = parseRunRootName(path.basename(root));
+    if (parsed?.pid !== process.pid) {
+        throw new Error("Memoized scratch root is not owned by this process");
+    }
+    const owner = readOrCreateAdoptedOwner(authority, root, parsed.startedAt);
+    return {
+        path: root,
+        basename: path.basename(root),
+        authority,
+        owner,
+    };
+}
+/**
+ * Reclaim residue, then return one current-process root path.
+ * @returns Newly allocated root path
+ */
+export const reclaimAndCreateRunRoot = () => reclaimAndCreateOwnedRunRoot().path;
+//# sourceMappingURL=scratch-run-root-compatibility.js.map

package/dist/configs/vitest/scratch-run-root-compatibility.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch-run-root-compatibility.js","sourceRoot":"","sources":["../../../src/configs/vitest/scratch-run-root-compatibility.ts"],"names":[],"mappings":"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"}

package/dist/configs/vitest/scratch-run-root-intent.d.ts

@@ -0,0 +1,66 @@
+import { type ScratchNamespaceAuthority } from "./scratch-authority.js";
+import { writeScratchOwnerRecord, type ScratchOwnerRecordV1, type ScratchPathIdentity } from "./scratch-owner.js";
+/** Durable handle for one run root owned by this process. */
+export interface OwnedScratchRunRoot {
+    readonly path: string;
+    readonly basename: string;
+    readonly authority: ScratchNamespaceAuthority;
+    readonly owner: ScratchOwnerRecordV1;
+}
+/** Precommitted immutable intent for one exact direct run root. */
+export interface ScratchRunRootIntentV1 {
+    readonly schema: 1;
+    readonly rootPath: string;
+    readonly basename: string;
+    readonly authority: ScratchNamespaceAuthority;
+    readonly pid: number;
+    readonly processBirthFingerprint: string;
+    readonly createdAt: string;
+    readonly token: string;
+    readonly suiteLabel: string;
+    readonly registeredPrefixes: readonly string[];
+}
+/** Deterministic seams for precommitting process-birth authority. */
+interface PrepareRunRootOptions {
+    readonly platform?: NodeJS.Platform;
+    readonly processBirthFingerprint?: (pid: number) => string | undefined;
+    readonly suiteLabel?: string;
+    readonly registeredPrefixes?: readonly string[];
+}
+/** Deterministic seams for transactional root materialization. */
+interface MaterializeRunRootOptions {
+    readonly writeOwnerRecord?: typeof writeScratchOwnerRecord;
+}
+/**
+ * Prepare an exact root identity without creating that root.
+ * @param options - Deterministic authority seams
+ * @returns Immutable precommitted root intent
+ */
+export declare function prepareOwnedScratchRunRoot(options?: PrepareRunRootOptions): ScratchRunRootIntentV1;
+/**
+ * Materialize one armed root and persist its immutable marker.
+ * @param intent - Precommitted root intent
+ * @param options - Transactional marker-writer seams
+ * @returns Durable owned-root handle
+ */
+export declare function materializeOwnedScratchRunRoot(intent: ScratchRunRootIntentV1, options?: MaterializeRunRootOptions): OwnedScratchRunRoot;
+/**
+ * Validate an opened marker against the complete armed intent.
+ * @param intent - Precommitted root facts
+ * @param owner - Persisted owner marker
+ * @param root - Currently opened root identity
+ */
+declare function assertIntentOwner(intent: ScratchRunRootIntentV1, owner: ScratchOwnerRecordV1, root: ScratchPathIdentity): void;
+/**
+ * Open one exact materialized root without following a replacement symlink.
+ * @param intent - Armed root intent
+ * @returns Owned handle, or undefined when not yet materialized
+ */
+export declare function openOwnedScratchRunRoot(intent: ScratchRunRootIntentV1): OwnedScratchRunRoot | undefined;
+/**
+ * Remove a run root using only the authority captured when it was made.
+ * @param owned - Durable handle or precommitted intent
+ */
+export declare function removeOwnedScratchRunRoot(owned: OwnedScratchRunRoot | ScratchRunRootIntentV1): void;
+export { assertIntentOwner };
+//# sourceMappingURL=scratch-run-root-intent.d.ts.map

package/dist/configs/vitest/scratch-run-root-intent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scratch-run-root-intent.d.ts","sourceRoot":"","sources":["../../../src/configs/vitest/scratch-run-root-intent.ts"],"names":[],"mappings":"AAKA,OAAO,EAML,KAAK,yBAAyB,EAC/B,MAAM,wBAAwB,CAAC;AAKhC,OAAO,EAKL,uBAAuB,EACvB,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAE5B,6DAA6D;AAC7D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAC;CACtC;AAED,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,yBAAyB,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,uBAAuB,EAAE,MAAM,CAAC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;CAChD;AAED,qEAAqE;AACrE,UAAU,qBAAqB;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;IACpC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACvE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACjD;AAED,kEAAkE;AAClE,UAAU,yBAAyB;IACjC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,uBAAuB,CAAC;CAC5D;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,GAAE,qBAA0B,GAClC,sBAAsB,CA+BxB;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,sBAAsB,EAC9B,OAAO,GAAE,yBAA8B,GACtC,mBAAmB,CAiDrB;AAED;;;;;GAKG;AACH,iBAAS,iBAAiB,CACxB,MAAM,EAAE,sBAAsB,EAC9B,KAAK,EAAE,oBAAoB,EAC3B,IAAI,EAAE,mBAAmB,GACxB,IAAI,CAcN;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,sBAAsB,GAC7B,mBAAmB,GAAG,SAAS,CAiBjC;AAiCD;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,mBAAmB,GAAG,sBAAsB,GAClD,IAAI,CAuBN;AAED,OAAO,EAAE,iBAAiB,EAAE,CAAC"}

package/dist/configs/vitest/scratch-run-root-intent.js

@@ -0,0 +1,183 @@
+/** Pre-root intent, materialization, and reopening for one owned scratch root. */
+import { randomBytes } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { SCRATCH_QUARANTINE_PREFIX, createScratchNamespaceAuthority, readBoundedScratchNamespace, removeAuthorizedScratchRoot, runRootName, } from "./scratch-authority.js";
+import { registeredScratchPrefixes, scratchSuiteLabel, } from "./scratch-route-profile.js";
+import { createScratchOwnerRecord, processBirthFingerprint, readScratchOwnerRecord, scratchPathIdentity, writeScratchOwnerRecord, } from "./scratch-owner.js";
+/**
+ * Prepare an exact root identity without creating that root.
+ * @param options - Deterministic authority seams
+ * @returns Immutable precommitted root intent
+ */
+export function prepareOwnedScratchRunRoot(options = {}) {
+    const suiteLabel = options.suiteLabel ?? scratchSuiteLabel();
+    const prefixes = options.registeredPrefixes ?? registeredScratchPrefixes();
+    const authority = createScratchNamespaceAuthority();
+    const now = Date.now();
+    const basename = runRootName(process.pid, now, randomBytes(4).toString("hex"));
+    const platform = options.platform ?? process.platform;
+    const birth = (options.processBirthFingerprint ?? processBirthFingerprint)(process.pid);
+    if (birth === undefined && (platform === "darwin" || platform === "linux")) {
+        throw new Error(`Scratch process-birth authority is unavailable on ${platform}`);
+    }
+    return Object.freeze({
+        schema: 1,
+        rootPath: path.join(authority.namespace.canonicalPath, basename),
+        basename,
+        authority,
+        pid: process.pid,
+        processBirthFingerprint: birth ?? `unsupported:${String(process.pid)}`,
+        createdAt: new Date(now).toISOString(),
+        token: randomBytes(16).toString("hex"),
+        suiteLabel,
+        registeredPrefixes: prefixes,
+    });
+}
+/**
+ * Materialize one armed root and persist its immutable marker.
+ * @param intent - Precommitted root intent
+ * @param options - Transactional marker-writer seams
+ * @returns Durable owned-root handle
+ */
+export function materializeOwnedScratchRunRoot(intent, options = {}) {
+    if (intent.schema !== 1)
+        throw new Error("Invalid scratch root intent schema");
+    if (path.join(intent.authority.namespace.canonicalPath, intent.basename) !==
+        intent.rootPath) {
+        throw new Error("Scratch root intent path does not match its authority");
+    }
+    const expectedIdentity = (() => {
+        fs.mkdirSync(intent.rootPath, { mode: 0o700 });
+        return scratchPathIdentity(intent.rootPath);
+    })();
+    try {
+        const owner = createScratchOwnerRecord({
+            authority: intent.authority,
+            root: intent.rootPath,
+            pid: intent.pid,
+            processBirthFingerprint: intent.processBirthFingerprint,
+            suiteLabel: intent.suiteLabel,
+            registeredPrefixes: intent.registeredPrefixes,
+            token: intent.token,
+            now: new Date(intent.createdAt),
+        });
+        (options.writeOwnerRecord ?? writeScratchOwnerRecord)(intent.rootPath, owner);
+        return {
+            path: intent.rootPath,
+            basename: intent.basename,
+            authority: intent.authority,
+            owner,
+        };
+    }
+    catch (error) {
+        try {
+            removeAuthorizedScratchRoot({
+                authority: intent.authority,
+                basename: intent.basename,
+                expectedIdentity,
+            });
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], "Scratch root materialization failed and rollback could not reclaim it");
+        }
+        throw error;
+    }
+}
+/**
+ * Validate an opened marker against the complete armed intent.
+ * @param intent - Precommitted root facts
+ * @param owner - Persisted owner marker
+ * @param root - Currently opened root identity
+ */
+function assertIntentOwner(intent, owner, root) {
+    if (owner.token !== intent.token ||
+        owner.pid !== intent.pid ||
+        owner.processBirthFingerprint !== intent.processBirthFingerprint ||
+        owner.namespace.dev !== intent.authority.namespace.dev ||
+        owner.namespace.ino !== intent.authority.namespace.ino ||
+        owner.root.dev !== root.dev ||
+        owner.root.ino !== root.ino) {
+        throw new Error("Scratch owner token or armed identity does not match intent");
+    }
+}
+/**
+ * Open one exact materialized root without following a replacement symlink.
+ * @param intent - Armed root intent
+ * @returns Owned handle, or undefined when not yet materialized
+ */
+export function openOwnedScratchRunRoot(intent) {
+    // eslint-disable-next-line functional/no-let -- path-level ENOENT must be separated from marker-level ENOENT
+    let root;
+    try {
+        root = scratchPathIdentity(intent.rootPath);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const owner = readScratchOwnerRecord(intent.rootPath);
+    assertIntentOwner(intent, owner, root);
+    return {
+        path: intent.rootPath,
+        basename: intent.basename,
+        authority: intent.authority,
+        owner,
+    };
+}
+/**
+ * Find an interrupted quarantine bound to the intent token and root inode.
+ * @param intent - Precommitted root facts
+ * @returns Matching quarantine identity, or undefined
+ */
+function interruptedQuarantine(intent) {
+    for (const basename of readBoundedScratchNamespace(intent.authority.namespace.canonicalPath)) {
+        if (!basename.startsWith(SCRATCH_QUARANTINE_PREFIX))
+            continue;
+        const candidate = path.join(intent.authority.namespace.canonicalPath, basename);
+        try {
+            const owner = readScratchOwnerRecord(candidate);
+            if (owner.token !== intent.token)
+                continue;
+            const identity = scratchPathIdentity(candidate);
+            assertIntentOwner(intent, owner, identity);
+            return { basename, identity };
+        }
+        catch {
+            // Foreign and malformed quarantines never authorize this intent.
+        }
+    }
+    return undefined;
+}
+/**
+ * Remove a run root using only the authority captured when it was made.
+ * @param owned - Durable handle or precommitted intent
+ */
+export function removeOwnedScratchRunRoot(owned) {
+    if ("rootPath" in owned) {
+        const opened = openOwnedScratchRunRoot(owned);
+        if (opened !== undefined) {
+            removeOwnedScratchRunRoot(opened);
+            return;
+        }
+        const quarantine = interruptedQuarantine(owned);
+        if (quarantine === undefined)
+            return;
+        removeAuthorizedScratchRoot({
+            authority: owned.authority,
+            basename: quarantine.basename,
+            expectedToken: owned.token,
+            expectedIdentity: quarantine.identity,
+        });
+        return;
+    }
+    removeAuthorizedScratchRoot({
+        authority: owned.authority,
+        basename: owned.basename,
+        expectedToken: owned.owner.token,
+        expectedIdentity: owned.owner.root,
+    });
+}
+export { assertIntentOwner };
+//# sourceMappingURL=scratch-run-root-intent.js.map