taphound 0.2.0-dev.1 → 0.2.0-dev.11

package/dist/adapters/filesystem/generation-store/session-lock.d.ts

@@ -0,0 +1,29 @@
+import type { FileSystemGenerationSessionStoreHooks } from "../generation-session-store.js";
+export interface SessionLockConfig {
+    generationRoot: string;
+    locksRoot: string;
+    lockTimeoutMs: number;
+    lockRetryMs: number;
+    hooks: Pick<FileSystemGenerationSessionStoreHooks, "beforeLockStagingWrite" | "beforeLockInstall" | "afterLockTombstoneRename">;
+}
+export interface LockOwner {
+    pid: number;
+    token: string;
+}
+/**
+ * The per-session exclusive lock: a linked owner file, reaped only when its
+ * owner process is gone. Every store operation runs inside `withLock`.
+ */
+export declare class SessionLock {
+    private readonly config;
+    constructor(config: SessionLockConfig);
+    private readonly lockPath;
+    readonly withLock: <T>(id: string, operation: () => Promise<T>) => Promise<T>;
+    private readonly acquireLock;
+    private readonly tryInstallLock;
+    private readonly reapDeadOwnerLock;
+    private readonly releaseLock;
+    private readonly readLockOwner;
+    private readonly fileIdentity;
+    private readonly isProcessAlive;
+}

package/dist/adapters/filesystem/generation-store/session-lock.js

@@ -0,0 +1,202 @@
+import { randomUUID } from "node:crypto";
+import { constants, link, lstat, open, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { GenerationSessionStoreError } from "../../../ports/generation-session-store.js";
+import { isErrnoException } from "../../../shared/errors.js";
+import { asStoreIoError, captureStoreDirectory, serializeJson, verifyStoreDirectory } from "./store-files.js";
+/**
+ * The per-session exclusive lock: a linked owner file, reaped only when its
+ * owner process is gone. Every store operation runs inside `withLock`.
+ */
+export class SessionLock {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    lockPath = (id) => (join(this.config.locksRoot, `${id}.lock`));
+    withLock = async (id, operation) => {
+        const token = randomUUID();
+        let generationRootEvidence;
+        let locksRootEvidence;
+        try {
+            generationRootEvidence = await captureStoreDirectory(this.config.generationRoot);
+            locksRootEvidence = await captureStoreDirectory(this.config.locksRoot);
+            await this.acquireLock(id, { pid: process.pid, token }, generationRootEvidence, locksRootEvidence);
+            await verifyStoreDirectory(generationRootEvidence);
+            await verifyStoreDirectory(locksRootEvidence);
+        }
+        catch (error) {
+            throw asStoreIoError(error, "acquire its exclusive lock");
+        }
+        let outcome;
+        let releaseError;
+        try {
+            outcome = {
+                status: "succeeded",
+                value: await operation()
+            };
+        }
+        catch (error) {
+            outcome = { status: "failed", error };
+        }
+        finally {
+            try {
+                await this.releaseLock(id, token);
+            }
+            catch (error) {
+                releaseError = error;
+            }
+        }
+        if (outcome.status === "failed") {
+            throw asStoreIoError(outcome.error, "complete a locked operation");
+        }
+        if (releaseError !== undefined) {
+            throw asStoreIoError(releaseError, "release its exclusive lock");
+        }
+        return outcome.value;
+    };
+    acquireLock = async (id, owner, generationRootEvidence, locksRootEvidence) => {
+        const lockPath = this.lockPath(id);
+        const deadline = Date.now() + this.config.lockTimeoutMs;
+        for (;;) {
+            if (await this.tryInstallLock(id, lockPath, owner, generationRootEvidence, locksRootEvidence)) {
+                return;
+            }
+            await this.reapDeadOwnerLock(id, lockPath);
+            if (Date.now() >= deadline) {
+                throw new GenerationSessionStoreError("LOCK_TIMEOUT", `Timed out acquiring generation session lock: ${id}`);
+            }
+            await new Promise((resolveDelay) => {
+                setTimeout(resolveDelay, this.config.lockRetryMs);
+            });
+        }
+    };
+    tryInstallLock = async (id, lockPath, owner, generationRootEvidence, locksRootEvidence) => {
+        const stagingPath = join(this.config.locksRoot, `.${id}.lock.acquire-${randomUUID()}.tmp`);
+        try {
+            const handle = await open(stagingPath, "wx", 0o600);
+            try {
+                await this.config.hooks.beforeLockStagingWrite?.();
+                await handle.writeFile(serializeJson(owner), "utf8");
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+            await this.config.hooks.beforeLockInstall?.();
+            await verifyStoreDirectory(generationRootEvidence);
+            await verifyStoreDirectory(locksRootEvidence);
+            try {
+                await link(stagingPath, lockPath);
+            }
+            catch (error) {
+                if (isErrnoException(error) && error.code === "EEXIST") {
+                    return false;
+                }
+                throw error;
+            }
+            // The lock excludes other processes as soon as link() returns; it
+            // needs no directory sync. Only its owner record is synced (above), so
+            // a lock that survives a power loss names a dead owner and is reaped.
+            try {
+                await verifyStoreDirectory(generationRootEvidence);
+                await verifyStoreDirectory(locksRootEvidence);
+            }
+            catch (error) {
+                await this.releaseLock(id, owner.token).catch(() => undefined);
+                throw error;
+            }
+            return true;
+        }
+        finally {
+            await unlink(stagingPath).catch(() => undefined);
+        }
+    };
+    reapDeadOwnerLock = async (id, lockPath) => {
+        try {
+            const identity = await this.fileIdentity(lockPath);
+            const owner = await this.readLockOwner(lockPath);
+            if (owner === null || this.isProcessAlive(owner.pid)) {
+                return;
+            }
+            const tombstone = join(this.config.locksRoot, `.${id}.lock.reap-${randomUUID()}`);
+            await rename(lockPath, tombstone);
+            const movedIdentity = await this.fileIdentity(tombstone);
+            if (movedIdentity.dev !== identity.dev
+                || movedIdentity.ino !== identity.ino) {
+                await rename(tombstone, lockPath).catch(() => undefined);
+                return;
+            }
+            await this.config.hooks.afterLockTombstoneRename?.();
+            await unlink(tombstone);
+        }
+        catch (error) {
+            if (!isErrnoException(error) || error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    };
+    releaseLock = async (id, token) => {
+        const lockPath = this.lockPath(id);
+        try {
+            const identity = await this.fileIdentity(lockPath);
+            const current = await this.readLockOwner(lockPath);
+            if (current?.pid === process.pid && current.token === token) {
+                const tombstone = join(this.config.locksRoot, `.${id}.lock.release-${randomUUID()}`);
+                await rename(lockPath, tombstone);
+                const movedIdentity = await this.fileIdentity(tombstone);
+                if (movedIdentity.dev === identity.dev
+                    && movedIdentity.ino === identity.ino) {
+                    // A release lost to a power loss reappears as a dead-owner lock,
+                    // which the next acquirer reaps; it needs no directory sync.
+                    await unlink(tombstone);
+                }
+                else {
+                    await rename(tombstone, lockPath).catch(() => undefined);
+                }
+            }
+        }
+        catch (error) {
+            if (!isErrnoException(error) || error.code !== "ENOENT") {
+                throw error;
+            }
+        }
+    };
+    readLockOwner = async (lockPath) => {
+        const handle = await open(lockPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        try {
+            const value = JSON.parse(await handle.readFile("utf8"));
+            if (value === null
+                || typeof value !== "object"
+                || !Number.isSafeInteger(value.pid)
+                || value.pid <= 0
+                || typeof value.token !== "string"
+                || value.token.length === 0) {
+                return null;
+            }
+            return value;
+        }
+        catch {
+            return null;
+        }
+        finally {
+            await handle.close();
+        }
+    };
+    fileIdentity = async (path) => {
+        const stats = await lstat(path, { bigint: true });
+        if (!stats.isFile() || stats.isSymbolicLink()) {
+            throw new GenerationSessionStoreError("IO_ERROR", `Generation lock path is not a real file: ${path}`);
+        }
+        return { dev: stats.dev, ino: stats.ino };
+    };
+    isProcessAlive = (pid) => {
+        try {
+            process.kill(pid, 0);
+            return true;
+        }
+        catch (error) {
+            return !isErrnoException(error) || error.code !== "ESRCH";
+        }
+    };
+}

package/dist/adapters/filesystem/generation-store/session-transitions.d.ts

@@ -0,0 +1,24 @@
+import { type GenerationInFlight, type GenerationSession, type VerificationPhase } from "../../../domain/generation.js";
+export declare function assertId(id: unknown): asserts id is string;
+export declare function parseSession(value: unknown, classifyInvalidId?: boolean): GenerationSession;
+export declare function sessionId(value: GenerationSession): string;
+export declare function parseVerificationPhase(value: unknown): VerificationPhase;
+export declare function validateExpectedRevision(revision: number): void;
+export declare function validateInitialRevision(session: GenerationSession): void;
+export declare function validateNextRevision(id: string, expectedRevision: number, next: GenerationSession): void;
+export declare function parseInFlight(value: unknown): GenerationInFlight;
+export declare function sameInFlight(left: GenerationSession["inFlight"], right: GenerationSession["inFlight"]): boolean;
+export declare function transitionStableState(session: GenerationSession): Record<string, unknown>;
+export declare function assertCoreIdentityPreserved(current: GenerationSession, next: GenerationSession): void;
+export declare function assertLatestSnapshotPreserved(current: GenerationSession, next: GenerationSession): void;
+export declare function assertSnapshotTransition(current: GenerationSession, next: GenerationSession): void;
+export declare function assertOrdinaryTransition(current: GenerationSession, next: GenerationSession): void;
+export declare function verificationStableState(session: GenerationSession): Record<string, unknown>;
+export declare function assertVerificationCompletionTransition(current: GenerationSession, next: GenerationSession, status: "passed" | "failed"): void;
+export declare function assertVerificationRecoveryTransition(current: GenerationSession, next: GenerationSession): void;
+export declare function assertVerificationReopenTransition(current: GenerationSession, next: GenerationSession): void;
+export declare function assertBundlePublishableTransition(current: GenerationSession, next: GenerationSession): void;
+export declare function confirmationStableState(session: GenerationSession): Record<string, unknown>;
+export declare function assertConfirmationTransition(current: GenerationSession, next: GenerationSession): void;
+export declare function assertRecoveryTransition(current: GenerationSession, next: GenerationSession): void;
+export declare function assertArchiveTransition(current: GenerationSession, next: GenerationSession): void;

package/dist/adapters/filesystem/generation-store/session-transitions.js

@@ -0,0 +1,340 @@
+// Parsing and the allowed state transitions of a stored generation session.
+import { GenerationInFlightSchema, GenerationSessionSchema, VerificationPhaseSchema, generationCoreIdentity } from "../../../domain/generation.js";
+import { GenerationSessionStoreError } from "../../../ports/generation-session-store.js";
+export function assertId(id) {
+    if (typeof id !== "string"
+        || !/^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$/.test(id)) {
+        throw new GenerationSessionStoreError("INVALID_ID", "Invalid generation session id");
+    }
+}
+export function parseSession(value, classifyInvalidId = false) {
+    try {
+        return GenerationSessionSchema.parse(value);
+    }
+    catch (error) {
+        if (classifyInvalidId && value !== null && typeof value === "object") {
+            try {
+                const id = Reflect.get(value, "id");
+                if (typeof id === "string") {
+                    assertId(id);
+                }
+            }
+            catch (idError) {
+                if (idError instanceof GenerationSessionStoreError) {
+                    throw idError;
+                }
+            }
+        }
+        throw new GenerationSessionStoreError("INVALID_SESSION", "Generation session state is invalid", { cause: error });
+    }
+}
+export function sessionId(value) {
+    const id = value.id;
+    assertId(id);
+    return id;
+}
+export function parseVerificationPhase(value) {
+    try {
+        return VerificationPhaseSchema.parse(value);
+    }
+    catch (error) {
+        throw new GenerationSessionStoreError("INVALID_SESSION", "Verification phase is invalid", { cause: error });
+    }
+}
+export function validateExpectedRevision(revision) {
+    if (!Number.isSafeInteger(revision) || revision < 0) {
+        throw new GenerationSessionStoreError("INVALID_REVISION", "Invalid expected generation revision");
+    }
+}
+export function validateInitialRevision(session) {
+    if (session.revision !== 0) {
+        throw new GenerationSessionStoreError("INVALID_REVISION", "A new generation session must start at revision 0");
+    }
+}
+export function validateNextRevision(id, expectedRevision, next) {
+    validateExpectedRevision(expectedRevision);
+    if (expectedRevision === Number.MAX_SAFE_INTEGER) {
+        throw new GenerationSessionStoreError("INVALID_REVISION", "Generation revision cannot increment beyond Number.MAX_SAFE_INTEGER");
+    }
+    if (sessionId(next) !== id) {
+        throw new GenerationSessionStoreError("INVALID_ID", "Updated generation session id does not match the requested id");
+    }
+    if (next.revision !== expectedRevision + 1) {
+        throw new GenerationSessionStoreError("INVALID_REVISION", "Next generation revision must increment expectedRevision by exactly one");
+    }
+}
+export function parseInFlight(value) {
+    try {
+        return GenerationInFlightSchema.parse(value);
+    }
+    catch (error) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Expected inFlight record is invalid", { cause: error });
+    }
+}
+export function sameInFlight(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+export function transitionStableState(session) {
+    return {
+        version: session.version,
+        id: session.id,
+        bindings: session.bindings,
+        target: session.target,
+        variables: session.variables,
+        ...(session.baseFlow === undefined ? {} : { baseFlow: session.baseFlow }),
+        candidateSteps: session.candidateSteps,
+        candidateSources: session.candidateSources,
+        pendingConfirmation: session.pendingConfirmation,
+        verification: session.verification,
+        verificationHistory: session.verificationHistory,
+        publication: session.publication
+    };
+}
+export function assertCoreIdentityPreserved(current, next) {
+    const currentIdentity = generationCoreIdentity(current);
+    const nextIdentity = generationCoreIdentity(next);
+    if (JSON.stringify(currentIdentity) !== JSON.stringify(nextIdentity)) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Generation Core identity is immutable");
+    }
+}
+export function assertLatestSnapshotPreserved(current, next) {
+    if (current.bindings.snapshotHash !== next.bindings.snapshotHash) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Latest snapshot may only change through commitSnapshot");
+    }
+}
+export function assertSnapshotTransition(current, next) {
+    assertCoreIdentityPreserved(current, next);
+    const currentBindings = {
+        projectHash: current.bindings.projectHash,
+        configHash: current.bindings.configHash,
+        contextHash: current.bindings.contextHash,
+        uiBackend: current.bindings.uiBackend
+    };
+    const { snapshotHash: nextSnapshotHash, ...nextBindings } = next.bindings;
+    if (current.state !== "active"
+        || current.inFlight !== null
+        || current.pendingConfirmation !== null
+        || current.verification.status !== "notRun"
+        || current.publication.status !== "notRun"
+        || next.state !== "active"
+        || next.inFlight !== null
+        || next.pendingConfirmation !== null
+        || nextSnapshotHash === null
+        || JSON.stringify(currentBindings) !== JSON.stringify(nextBindings)
+        || JSON.stringify({
+            ...transitionStableState(current),
+            bindings: undefined
+        }) !== JSON.stringify({
+            ...transitionStableState(next),
+            bindings: undefined
+        })) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Snapshot commit may only replace the active snapshot binding");
+    }
+}
+export function assertOrdinaryTransition(current, next) {
+    assertCoreIdentityPreserved(current, next);
+    assertLatestSnapshotPreserved(current, next);
+    if (current.verification.status !== "notRun"
+        || current.publication.status !== "notRun"
+        || JSON.stringify(current.verification) !== JSON.stringify(next.verification)
+        || JSON.stringify(current.publication) !== JSON.stringify(next.publication)) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Verification and publication require explicit transitions");
+    }
+    if (current.state === "recoveryRequired") {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Recovery-required state must use the explicit recovery transition");
+    }
+    if (JSON.stringify(current.pendingConfirmation)
+        !== JSON.stringify(next.pendingConfirmation)) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Pending confirmation must use the explicit confirmation transition");
+    }
+    const stableStateMatches = JSON.stringify(transitionStableState(current))
+        === JSON.stringify(transitionStableState(next));
+    if (current.inFlight !== null) {
+        if (next.state === "recoveryRequired"
+            && sameInFlight(current.inFlight, next.inFlight)
+            && stableStateMatches) {
+            return;
+        }
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Persisted inFlight may only be marked recoveryRequired without mutation");
+    }
+    if (next.state === "recoveryRequired"
+        || (next.inFlight !== null && !stableStateMatches)) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Starting inFlight cannot mutate candidate or result state");
+    }
+}
+export function verificationStableState(session) {
+    return {
+        ...transitionStableState(session),
+        verification: undefined
+    };
+}
+export function assertVerificationCompletionTransition(current, next, status) {
+    assertCoreIdentityPreserved(current, next);
+    assertLatestSnapshotPreserved(current, next);
+    if (current.state !== "active"
+        || next.state !== "active"
+        || current.inFlight !== null
+        || next.inFlight !== null
+        || current.pendingConfirmation !== null
+        || next.pendingConfirmation !== null
+        || current.verification.status !== "running"
+        || next.verification.status !== status
+        || next.publication.status !== "notRun"
+        || JSON.stringify(verificationStableState(current))
+            !== JSON.stringify(verificationStableState(next))) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", `Verification completion must record ${status} from the running attempt`);
+    }
+    if (next.verification.status === "passed"
+        && next.verification.attemptId !== current.verification.attemptId) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Verification completion attempt does not match");
+    }
+}
+export function assertVerificationRecoveryTransition(current, next) {
+    assertCoreIdentityPreserved(current, next);
+    assertLatestSnapshotPreserved(current, next);
+    if (current.state !== "active"
+        || next.state !== "active"
+        || current.inFlight !== null
+        || next.inFlight !== null
+        || current.pendingConfirmation !== null
+        || next.pendingConfirmation !== null
+        || current.verification.status !== "running"
+        || next.verification.status !== "notRun"
+        || current.publication.status !== "notRun"
+        || next.publication.status !== "notRun"
+        || JSON.stringify(verificationStableState(current))
+            !== JSON.stringify(verificationStableState(next))) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Verification recovery may only reset an interrupted running attempt");
+    }
+}
+export function assertVerificationReopenTransition(current, next) {
+    assertCoreIdentityPreserved(current, next);
+    assertLatestSnapshotPreserved(current, next);
+    const currentHistory = current.verificationHistory;
+    const nextHistory = next.verificationHistory;
+    const expectedHistory = current.verification.status === "failed"
+        ? [
+            ...currentHistory,
+            {
+                failedRevision: current.revision,
+                reopenedAt: nextHistory.at(-1)?.reopenedAt,
+                reason: nextHistory.at(-1)?.reason,
+                failure: current.verification.failure
+            }
+        ]
+        : currentHistory;
+    const stable = (session) => ({
+        ...transitionStableState(session),
+        verification: undefined,
+        verificationHistory: undefined
+    });
+    if (current.state !== "active"
+        || next.state !== "active"
+        || current.inFlight !== null
+        || next.inFlight !== null
+        || current.pendingConfirmation !== null
+        || next.pendingConfirmation !== null
+        || current.verification.status !== "failed"
+        || next.verification.status !== "notRun"
+        || current.publication.status !== "notRun"
+        || next.publication.status !== "notRun"
+        || nextHistory.length !== currentHistory.length + 1
+        || nextHistory.at(-1)?.reason.trim().length === 0
+        || JSON.stringify(nextHistory) !== JSON.stringify(expectedHistory)
+        || JSON.stringify(stable(current)) !== JSON.stringify(stable(next))) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Verification reopen may only preserve one failed attempt in history and reset it to notRun");
+    }
+}
+export function assertBundlePublishableTransition(current, next) {
+    assertCoreIdentityPreserved(current, next);
+    assertLatestSnapshotPreserved(current, next);
+    if (current.state !== "active"
+        || next.state !== "active"
+        || current.inFlight !== null
+        || next.inFlight !== null
+        || current.pendingConfirmation !== null
+        || next.pendingConfirmation !== null
+        || current.verification.status !== "passed"
+        || JSON.stringify(current.verification) !== JSON.stringify(next.verification)
+        || current.publication.status !== "notRun"
+        || next.publication.status !== "published"
+        || JSON.stringify({
+            ...transitionStableState(current),
+            publication: undefined
+        }) !== JSON.stringify({
+            ...transitionStableState(next),
+            publication: undefined
+        })) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Bundle publication must be explicitly marked after passed verification");
+    }
+}
+export function confirmationStableState(session) {
+    const stable = transitionStableState(session);
+    return { ...stable, pendingConfirmation: undefined };
+}
+export function assertConfirmationTransition(current, next) {
+    assertCoreIdentityPreserved(current, next);
+    assertLatestSnapshotPreserved(current, next);
+    if (current.state !== "active"
+        || next.state !== "active"
+        || current.inFlight !== null
+        || next.inFlight !== null
+        || current.verification.status !== "notRun"
+        || current.publication.status !== "notRun"
+        || JSON.stringify(confirmationStableState(current))
+            !== JSON.stringify(confirmationStableState(next))) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Confirmation transition may only change pending confirmation state");
+    }
+    const before = current.pendingConfirmation;
+    const after = next.pendingConfirmation;
+    if (before === null) {
+        if (after !== null && after.status === "pending") {
+            return;
+        }
+    }
+    else if (after === null) {
+        return;
+    }
+    else if (before.status === "pending"
+        && after.status === "approved"
+        && before.approvalMode === undefined
+        && after.approvalMode !== undefined
+        && JSON.stringify({
+            ...before,
+            status: undefined,
+            approvalMode: undefined
+        }) === JSON.stringify({
+            ...after,
+            status: undefined,
+            approvalMode: undefined
+        })) {
+        return;
+    }
+    throw new GenerationSessionStoreError("INVALID_TRANSITION", "Invalid pending confirmation lifecycle transition");
+}
+export function assertRecoveryTransition(current, next) {
+    assertCoreIdentityPreserved(current, next);
+    assertLatestSnapshotPreserved(current, next);
+    if (current.state !== "recoveryRequired"
+        || current.inFlight === null
+        || next.state !== "active"
+        || next.inFlight !== null
+        || JSON.stringify(transitionStableState(current))
+            !== JSON.stringify(transitionStableState(next))) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Recovery must only clear preserved inFlight evidence and reactivate state");
+    }
+}
+export function assertArchiveTransition(current, next) {
+    assertCoreIdentityPreserved(current, next);
+    assertLatestSnapshotPreserved(current, next);
+    if (current.state !== "active"
+        || current.inFlight !== null
+        || current.pendingConfirmation !== null
+        || next.state !== "archived"
+        || next.inFlight !== null
+        || next.pendingConfirmation !== null
+        || JSON.stringify(transitionStableState(current))
+            !== JSON.stringify(transitionStableState(next))) {
+        throw new GenerationSessionStoreError("INVALID_TRANSITION", "Archive may only mark an idle active session as archived without mutation");
+    }
+}

package/dist/adapters/filesystem/generation-store/store-files.d.ts

@@ -0,0 +1,50 @@
+import type { BigIntStats, Dirent } from "node:fs";
+import type { GenerationInFlight, GenerationSession } from "../../../domain/generation.js";
+import { GenerationSessionStoreError } from "../../../ports/generation-session-store.js";
+export interface FileIdentity {
+    dev: bigint;
+    ino: bigint;
+}
+export interface FileSnapshotMetadata extends FileIdentity {
+    size: bigint;
+    mtimeNs: bigint;
+    ctimeNs: bigint;
+}
+export declare function snapshotMetadata(stats: BigIntStats): FileSnapshotMetadata;
+export declare function sameSnapshotMetadata(left: FileSnapshotMetadata, right: FileSnapshotMetadata): boolean;
+export declare function evidenceEntryType(entry: Dirent): string;
+export declare function evidenceEntrySnapshot(entries: readonly Dirent[]): readonly string[];
+export interface DirectoryEvidence {
+    path: string;
+    canonicalPath: string;
+    identity: FileIdentity;
+}
+export interface StoreDirectoryEvidence {
+    path: string;
+    canonicalPath: string;
+    identity: FileIdentity;
+}
+export declare function sameIdentity(left: FileIdentity, right: FileIdentity): boolean;
+export declare function captureStoreDirectory(path: string): Promise<StoreDirectoryEvidence>;
+export declare function verifyStoreDirectory(expected: StoreDirectoryEvidence): Promise<void>;
+export declare function captureStoreFile(path: string): Promise<FileIdentity>;
+export declare function captureOptionalStoreFile(path: string): Promise<FileIdentity | null>;
+export declare function verifyOptionalStoreFile(path: string, expected: FileIdentity | null): Promise<void>;
+export declare function asStoreIoError(error: unknown, action: string): Error;
+export declare function pathExists(path: string): Promise<boolean>;
+export declare function requireRealDirectory(path: string): Promise<void>;
+export declare function createOrRequireDirectory(path: string): Promise<boolean>;
+export declare function syncDirectory(path: string): Promise<void>;
+export declare function serializeJson(value: unknown): string;
+export declare function canonicalizeEvidenceValue(value: unknown, ancestors?: Set<object>): unknown;
+export declare function canonicalizeEvidence(value: unknown): unknown;
+export declare function validateEvidencePath(relativePath: unknown): string[];
+export declare function assertContained(root: string, candidate: string, allowRoot?: boolean): void;
+export declare function captureDirectoryEvidence(path: string): Promise<DirectoryEvidence>;
+export declare function verifyDirectoryEvidence(activeCanonicalPath: string, directories: readonly DirectoryEvidence[]): Promise<void>;
+export declare function assertEvidenceNamespaceAvailable(activeDirectory: string, activeEvidence: StoreDirectoryEvidence, inFlight: GenerationInFlight): Promise<void>;
+export declare function fileIdentity(path: string): Promise<FileIdentity>;
+export declare function evidenceNotFound(relativePath: string, cause: unknown): GenerationSessionStoreError;
+export declare function readStateFromDirectory(directory: string, afterOpen?: () => Promise<void> | void, expectedDirectory?: StoreDirectoryEvidence): Promise<GenerationSession>;
+export declare function readBoundState(directory: string, id: string, afterOpen?: () => Promise<void> | void, expectedDirectory?: StoreDirectoryEvidence): Promise<GenerationSession>;
+export declare function writeStateAtomically(directory: string, session: GenerationSession, sync?: (path: string) => Promise<void>, beforeRename?: () => Promise<void> | void, expectedDirectory?: StoreDirectoryEvidence, beforeInstall?: () => Promise<void> | void): Promise<void>;