@agent-teams/engineering-foundation 0.7.0 → 0.9.0

package/dist/scaffolding/adapters/node/filesystem-authority-workspace.js

@@ -0,0 +1,257 @@
+import { realpath } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { assertAuthorityScaffoldPlanDigest } from "../../kernel/plan-validation.js";
+import { ScaffoldError } from "../../scaffold-error.js";
+import { assertSchema } from "../../../schema-catalog.js";
+import { acquireFoundationOperationLock } from "../../../local-mode/service.js";
+import { LOCAL_STATE_DIRECTORY } from "../../../local-mode/types.js";
+import { assessScaffoldPlanAuthority } from "./node-plan-authority.js";
+import { assertSafeExistingAncestors, assertSafeOperationPaths } from "./filesystem-path-guard.js";
+import { assertTransactionTemporariesAbsent, publishFilesystemOperation } from "./filesystem-operation-state.js";
+import { freshAuthorityScaffoldJournal, receiptFromJournalStates, reconcileAuthorityScaffoldJournal, replaceScaffoldJournalOperation } from "./filesystem-journal-state.js";
+import { finalizeAuthorityScaffoldJournal, staleBeforeJournal, verifyAlreadyAppliedScaffold } from "./filesystem-finalization.js";
+import { recoveryRequiredForAuthority, resolveAuthority, safeClassifyPlan } from "./filesystem-authority.js";
+import { assertAuthorityScaffoldJournalTemporaryAbsent, readScaffoldJournalEnvelope, SCAFFOLD_JOURNAL_FILE, writeAuthorityScaffoldJournal } from "./filesystem-journal.js";
+function journalFault(faultInjector, operationIndex, operationPath) {
+    return faultInjector === undefined
+        ? undefined
+        : () => faultInjector({
+            phase: "after-journal-temporary-synced",
+            ...(operationIndex === undefined ? {} : { operationIndex }),
+            ...(operationPath === undefined ? {} : { operationPath })
+        });
+}
+function recoveryRequired(plan, phase, ruleId, message, remediation) {
+    return recoveryRequiredForAuthority({ plan, phase, ruleId, message, remediation });
+}
+function isReceipt(value) {
+    return typeof value === "object" && value !== null && "receiptDigest" in value;
+}
+function deepFreezePlanValue(value, visited) {
+    if (typeof value !== "object" || value === null || visited.has(value)) {
+        return;
+    }
+    visited.add(value);
+    for (const child of Object.values(value)) {
+        deepFreezePlanValue(child, visited);
+    }
+    Object.freeze(value);
+}
+function snapshotAuthorityScaffoldPlan(plan) {
+    let snapshot;
+    try {
+        snapshot = structuredClone(plan);
+        deepFreezePlanValue(snapshot, new Set());
+    }
+    catch (error) {
+        throw new ScaffoldError("SCAFFOLD_PLAN_INVALID", "Scaffolding Plan cannot be snapshotted as canonical data.", [], { cause: error });
+    }
+    return snapshot;
+}
+async function prepareJournal(options) {
+    let journal = options.journal;
+    const initialAuthority = await resolveAuthority({ ...options, journal });
+    if (initialAuthority !== undefined) {
+        return initialAuthority;
+    }
+    try {
+        await assertTransactionTemporariesAbsent(options.root, journal.plan);
+        const reconciled = await reconcileAuthorityScaffoldJournal(options.root, journal);
+        journal = reconciled.journal;
+        if (reconciled.conflictIds.size !== 0) {
+            await writeAuthorityScaffoldJournal(options.journalPath, journal, journalFault(options.faultInjector));
+            return receiptFromJournalStates({
+                plan: journal.plan,
+                journal,
+                outcome: "recovery-required",
+                phase: "recovery",
+                conflictOperationIds: reconciled.conflictIds
+            });
+        }
+    }
+    catch {
+        return recoveryRequired(journal.plan, options.recovered ? "recovery" : "apply", "scaffolding.recovery.unverifiable-workspace", "The workspace cannot be safely reconciled; no transaction output was removed.", "Resolve the filesystem state manually, then retry recovery.");
+    }
+    await writeAuthorityScaffoldJournal(options.journalPath, journal, journalFault(options.faultInjector));
+    return journal;
+}
+async function publishPendingOperations(options) {
+    const { continuation } = options;
+    let journal = options.journal;
+    const receipts = new Map();
+    for (const [operationIndex, operation] of journal.plan.operations.entries()) {
+        const current = journal.operations.find((candidate) => candidate.operationId === operation.id);
+        if (current === undefined) {
+            throw new ScaffoldError("SCAFFOLD_RECOVERY_REQUIRED", "Scaffolding source-bound journal operation is missing.");
+        }
+        if (current.state === "preexisting" || current.state === "published") {
+            receipts.set(operation.id, {
+                operationId: operation.id,
+                path: operation.path,
+                outcome: "already-satisfied",
+                resultDigest: operation.after.digest
+            });
+            continue;
+        }
+        await continuation.faultInjector?.({
+            phase: "before-operation-authority-recheck",
+            operationIndex,
+            operationPath: operation.path
+        });
+        const authority = await resolveAuthority({ ...continuation, journal });
+        if (authority !== undefined) {
+            return authority;
+        }
+        try {
+            await assertSafeExistingAncestors(continuation.root, operation.path);
+        }
+        catch {
+            return recoveryRequired(journal.plan, continuation.recovered ? "recovery" : "apply", "scaffolding.recovery.unsafe-ancestor", "Filesystem ancestry cannot be proven safe for publication.", "Resolve the filesystem state manually, then retry recovery.");
+        }
+        journal = replaceScaffoldJournalOperation(journal, operation.id, "publishing");
+        await writeAuthorityScaffoldJournal(continuation.journalPath, journal, journalFault(continuation.faultInjector, operationIndex, operation.path));
+        await continuation.faultInjector?.({
+            phase: "after-journal-operation-publishing",
+            operationIndex,
+            operationPath: operation.path
+        });
+        const outcome = await publishFilesystemOperation(continuation.root, operation, journal.plan.planDigest, operationIndex, continuation.faultInjector);
+        journal = replaceScaffoldJournalOperation(journal, operation.id, outcome === "applied" ? "published" : "preexisting");
+        await writeAuthorityScaffoldJournal(continuation.journalPath, journal, journalFault(continuation.faultInjector, operationIndex, operation.path));
+        await continuation.faultInjector?.({
+            phase: "after-journal-operation-published",
+            operationIndex,
+            operationPath: operation.path
+        });
+        receipts.set(operation.id, {
+            operationId: operation.id,
+            path: operation.path,
+            outcome: continuation.recovered && outcome === "applied" ? "recovered" : outcome,
+            resultDigest: operation.after.digest
+        });
+    }
+    return { journal, receipts };
+}
+async function continueJournal(options) {
+    const prepared = await prepareJournal(options);
+    if (isReceipt(prepared)) {
+        return prepared;
+    }
+    const published = await publishPendingOperations({
+        continuation: options,
+        journal: prepared
+    });
+    if (isReceipt(published)) {
+        return published;
+    }
+    return finalizeAuthorityScaffoldJournal({ ...options, ...published });
+}
+export async function applyAuthorityFilesystemScaffold(consumerRoot, plan) {
+    return applyAuthorityFilesystemScaffoldWithFaultInjection(consumerRoot, plan);
+}
+/** Internal conformance seam. It is intentionally absent from package exports. */
+export async function applyAuthorityFilesystemScaffoldWithFaultInjection(consumerRoot, callerPlan, faultInjector) {
+    const plan = snapshotAuthorityScaffoldPlan(callerPlan);
+    await assertSchema("scaffold-plan/v1", plan, "scaffold-apply-plan");
+    assertAuthorityScaffoldPlanDigest(plan);
+    assertSafeOperationPaths(plan);
+    const canonicalRoot = await realpath(resolve(consumerRoot));
+    const release = await acquireFoundationOperationLock(canonicalRoot);
+    try {
+        const journalPath = join(canonicalRoot, LOCAL_STATE_DIRECTORY, SCAFFOLD_JOURNAL_FILE);
+        await assertAuthorityScaffoldJournalTemporaryAbsent(journalPath);
+        const existing = await readScaffoldJournalEnvelope(journalPath);
+        if (existing !== undefined) {
+            if (existing.plan.planDigest !== plan.planDigest) {
+                throw new ScaffoldError("SCAFFOLD_RECOVERY_REQUIRED", "A different scaffolding transaction requires recovery before this Plan can apply.");
+            }
+            return continueJournal({
+                root: canonicalRoot,
+                journalPath,
+                journal: existing,
+                recovered: true,
+                ...(faultInjector === undefined ? {} : { faultInjector })
+            });
+        }
+        const authority = await assessScaffoldPlanAuthority(canonicalRoot, plan);
+        if (authority.state === "stale") {
+            return staleBeforeJournal(plan);
+        }
+        if (authority.state === "unverifiable") {
+            return recoveryRequired(plan, "apply", "scaffolding.authority.unverifiable", "Authority cannot be re-verified safely; no transaction output was created.", "Restore readable authority sources, then compile a new Plan.");
+        }
+        let classifications;
+        try {
+            classifications = await safeClassifyPlan(canonicalRoot, plan);
+            await assertTransactionTemporariesAbsent(canonicalRoot, plan);
+        }
+        catch {
+            return recoveryRequired(plan, "apply", "scaffolding.apply.unverifiable-workspace", "The workspace cannot be safely prepared for this transaction.", "Resolve the filesystem state manually, then compile a new Plan.");
+        }
+        if (classifications.some(({ state }) => state === "conflict")) {
+            let rejectedJournal = freshAuthorityScaffoldJournal(plan);
+            for (const { operation, state } of classifications) {
+                if (state === "after") {
+                    rejectedJournal = replaceScaffoldJournalOperation(rejectedJournal, operation.id, "preexisting");
+                }
+            }
+            return receiptFromJournalStates({
+                plan,
+                journal: rejectedJournal,
+                outcome: "rejected",
+                phase: "apply",
+                conflictOperationIds: new Set(classifications
+                    .filter(({ state }) => state === "conflict")
+                    .map(({ operation }) => operation.id))
+            });
+        }
+        if (classifications.every(({ state }) => state === "after")) {
+            return verifyAlreadyAppliedScaffold({
+                root: canonicalRoot,
+                plan,
+                ...(faultInjector === undefined ? {} : { faultInjector })
+            });
+        }
+        let journal = freshAuthorityScaffoldJournal(plan);
+        for (const { operation, state } of classifications) {
+            if (state === "after") {
+                journal = replaceScaffoldJournalOperation(journal, operation.id, "preexisting");
+            }
+        }
+        await writeAuthorityScaffoldJournal(journalPath, journal, journalFault(faultInjector));
+        await faultInjector?.({ phase: "after-journal-prepared" });
+        return continueJournal({
+            root: canonicalRoot,
+            journalPath,
+            journal,
+            recovered: false,
+            ...(faultInjector === undefined ? {} : { faultInjector })
+        });
+    }
+    finally {
+        await release();
+    }
+}
+export async function recoverAuthorityFilesystemScaffold(consumerRoot) {
+    const canonicalRoot = await realpath(resolve(consumerRoot));
+    const release = await acquireFoundationOperationLock(canonicalRoot);
+    try {
+        const journalPath = join(canonicalRoot, LOCAL_STATE_DIRECTORY, SCAFFOLD_JOURNAL_FILE);
+        await assertAuthorityScaffoldJournalTemporaryAbsent(journalPath);
+        const journal = await readScaffoldJournalEnvelope(journalPath);
+        if (journal === undefined) {
+            return undefined;
+        }
+        assertSafeOperationPaths(journal.plan);
+        return continueJournal({
+            root: canonicalRoot,
+            journalPath,
+            journal,
+            recovered: true
+        });
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=filesystem-authority-workspace.js.map

package/dist/scaffolding/adapters/node/filesystem-authority-workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-authority-workspace.js","sourceRoot":"","sources":["../../../../src/scaffolding/adapters/node/filesystem-authority-workspace.ts"],"names":[],"mappings":"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"}

package/dist/scaffolding/adapters/node/filesystem-authority.d.ts

@@ -0,0 +1,20 @@
+import type { AuthorityScaffoldJournal, AuthorityScaffoldOperationReceipt, AuthorityScaffoldPlan, AuthorityScaffoldReceipt } from "../../contract/types.js";
+export declare function recoveryRequiredForAuthority(options: {
+    readonly plan: AuthorityScaffoldPlan;
+    readonly phase: "apply" | "recovery";
+    readonly ruleId: string;
+    readonly message: string;
+    readonly remediation: string;
+    readonly operations?: readonly AuthorityScaffoldOperationReceipt[];
+}): AuthorityScaffoldReceipt;
+export declare function safeClassifyPlan(root: string, plan: AuthorityScaffoldPlan): Promise<readonly {
+    readonly operation: AuthorityScaffoldPlan["operations"][number];
+    readonly state: "absent" | "after" | "conflict";
+}[]>;
+export declare function resolveAuthority(options: {
+    readonly root: string;
+    readonly journal: AuthorityScaffoldJournal;
+    readonly recovered: boolean;
+    readonly observedOperations?: readonly AuthorityScaffoldOperationReceipt[];
+}): Promise<AuthorityScaffoldReceipt | undefined>;
+//# sourceMappingURL=filesystem-authority.d.ts.map

package/dist/scaffolding/adapters/node/filesystem-authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-authority.d.ts","sourceRoot":"","sources":["../../../../src/scaffolding/adapters/node/filesystem-authority.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,iCAAiC,EACjC,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAMjC,wBAAgB,4BAA4B,CAAC,OAAO,EAAE;IACpD,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,iCAAiC,EAAE,CAAC;CACpE,GAAG,wBAAwB,CAU3B;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CACR,SAAS;IACP,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;IAChE,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;CACjD,EAAE,CACJ,CAaA;AAED,wBAAsB,gBAAgB,CAAC,OAAO,EAAE;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,SAAS,iCAAiC,EAAE,CAAC;CAC5E,GAAG,OAAO,CAAC,wBAAwB,GAAG,SAAS,CAAC,CAgChD"}

package/dist/scaffolding/adapters/node/filesystem-authority.js

@@ -0,0 +1,55 @@
+import { assessScaffoldPlanAuthority } from "./node-plan-authority.js";
+import { assertSafeExistingAncestors } from "./filesystem-path-guard.js";
+import { classifyFilesystemOperation } from "./filesystem-operation-state.js";
+import { createRecoveryRequiredReceipt } from "./filesystem-journal-state.js";
+export function recoveryRequiredForAuthority(options) {
+    return createRecoveryRequiredReceipt({
+        plan: options.plan,
+        phase: options.phase,
+        ruleId: options.ruleId,
+        subject: options.plan.projectId,
+        message: options.message,
+        remediation: options.remediation,
+        ...(options.operations === undefined ? {} : { operations: options.operations })
+    });
+}
+export async function safeClassifyPlan(root, plan) {
+    const classifications = [];
+    for (const operation of plan.operations) {
+        await assertSafeExistingAncestors(root, operation.path);
+        classifications.push({
+            operation,
+            state: await classifyFilesystemOperation(root, operation)
+        });
+    }
+    return classifications;
+}
+export async function resolveAuthority(options) {
+    const assessment = await assessScaffoldPlanAuthority(options.root, options.journal.plan);
+    if (assessment.state === "current") {
+        return undefined;
+    }
+    if (assessment.state === "unverifiable") {
+        return recoveryRequiredForAuthority({
+            plan: options.journal.plan,
+            phase: options.recovered ? "recovery" : "apply",
+            ruleId: "scaffolding.authority.unverifiable",
+            message: "Authority cannot be re-verified safely after publication began; outputs and journal were preserved.",
+            remediation: "Restore readable authority sources, then retry recovery.",
+            ...(options.observedOperations === undefined
+                ? {}
+                : { operations: options.observedOperations })
+        });
+    }
+    return recoveryRequiredForAuthority({
+        plan: options.journal.plan,
+        phase: options.recovered ? "recovery" : "apply",
+        ruleId: "scaffolding.authority.stale-after-publication",
+        message: "Authority changed after publication began; outputs and journal were preserved because portable file ownership cannot be proven.",
+        remediation: "Resolve the transaction state explicitly, then compile a new Plan.",
+        ...(options.observedOperations === undefined
+            ? {}
+            : { operations: options.observedOperations })
+    });
+}
+//# sourceMappingURL=filesystem-authority.js.map

package/dist/scaffolding/adapters/node/filesystem-authority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-authority.js","sourceRoot":"","sources":["../../../../src/scaffolding/adapters/node/filesystem-authority.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,2BAA2B,EAAE,MAAM,0BAA0B,CAAC;AACvE,OAAO,EAAE,2BAA2B,EAAE,MAAM,4BAA4B,CAAC;AACzE,OAAO,EAAE,2BAA2B,EAAE,MAAM,iCAAiC,CAAC;AAC9E,OAAO,EAAE,6BAA6B,EAAE,MAAM,+BAA+B,CAAC;AAE9E,MAAM,UAAU,4BAA4B,CAAC,OAO5C;IACC,OAAO,6BAA6B,CAAC;QACnC,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,SAAS;QAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC;KAChF,CAAC,CAAC;AACL,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,IAAY,EACZ,IAA2B;IAO3B,MAAM,eAAe,GAAG,EAGrB,CAAC;IACJ,KAAK,MAAM,SAAS,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;QACxC,MAAM,2BAA2B,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACxD,eAAe,CAAC,IAAI,CAAC;YACnB,SAAS;YACT,KAAK,EAAE,MAAM,2BAA2B,CAAC,IAAI,EAAE,SAAS,CAAC;SAC1D,CAAC,CAAC;IACL,CAAC;IACD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,OAKtC;IACC,MAAM,UAAU,GAAG,MAAM,2BAA2B,CAClD,OAAO,CAAC,IAAI,EACZ,OAAO,CAAC,OAAO,CAAC,IAAI,CACrB,CAAC;IACF,IAAI,UAAU,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACnC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,UAAU,CAAC,KAAK,KAAK,cAAc,EAAE,CAAC;QACxC,OAAO,4BAA4B,CAAC;YAClC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI;YAC1B,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO;YAC/C,MAAM,EAAE,oCAAoC;YAC5C,OAAO,EACL,qGAAqG;YACvG,WAAW,EAAE,0DAA0D;YACvE,GAAG,CAAC,OAAO,CAAC,kBAAkB,KAAK,SAAS;gBAC1C,CAAC,CAAC,EAAE;gBACJ,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,kBAAkB,EAAE,CAAC;SAChD,CAAC,CAAC;IACL,CAAC;IACD,OAAO,4BAA4B,CAAC;QAClC,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI;QAC1B,KAAK,EAAE,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO;QAC/C,MAAM,EAAE,+CAA+C;QACvD,OAAO,EACL,iIAAiI;QACnI,WAAW,EAAE,oEAAoE;QACjF,GAAG,CAAC,OAAO,CAAC,kBAAkB,KAAK,SAAS;YAC1C,CAAC,CAAC,EAAE;YACJ,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,kBAAkB,EAAE,CAAC;KAChD,CAAC,CAAC;AACL,CAAC"}

package/dist/scaffolding/adapters/node/filesystem-file-identity.d.ts

@@ -0,0 +1,20 @@
+import { type FileHandle } from "node:fs/promises";
+export interface PortableFileIdentity {
+    readonly birthtimeNs: bigint;
+    readonly dev: bigint;
+    readonly ino: bigint;
+}
+export type BoundedRegularFileRead = {
+    readonly outcome: "read";
+    readonly bytes: Buffer;
+    readonly identity: PortableFileIdentity;
+    readonly mode: number;
+} | {
+    readonly outcome: "changed";
+} | {
+    readonly outcome: "invalid";
+};
+export declare function readBoundedRegularFile(path: string, maximumBytes: number): Promise<BoundedRegularFileRead>;
+export declare function captureFileHandleIdentity(handle: FileHandle): Promise<PortableFileIdentity>;
+export declare function pathMatchesFileIdentity(path: string, expected: PortableFileIdentity): Promise<"different" | "match" | "missing">;
+//# sourceMappingURL=filesystem-file-identity.d.ts.map

package/dist/scaffolding/adapters/node/filesystem-file-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-file-identity.d.ts","sourceRoot":"","sources":["../../../../src/scaffolding/adapters/node/filesystem-file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE3E,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,MAAM,sBAAsB,GAC9B;IACE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,GACD;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,GAC/B;IAAE,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAA;CAAE,CAAC;AAiFpC,wBAAsB,sBAAsB,CAC1C,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,sBAAsB,CAAC,CAiDjC;AAED,wBAAsB,yBAAyB,CAC7C,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,oBAAoB,CAAC,CAE/B;AAED,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,oBAAoB,GAC7B,OAAO,CAAC,WAAW,GAAG,OAAO,GAAG,SAAS,CAAC,CAkB5C"}

package/dist/scaffolding/adapters/node/filesystem-file-identity.js

@@ -0,0 +1,122 @@
+import { constants, lstat, open } from "node:fs/promises";
+function identityFromStat(metadata) {
+    return {
+        birthtimeNs: metadata.birthtimeNs,
+        dev: metadata.dev,
+        ino: metadata.ino
+    };
+}
+function isMissing(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function hasErrorCode(error, code) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === code);
+}
+async function isExistingNonRegularPath(path) {
+    try {
+        const metadata = await lstat(path);
+        return metadata.isSymbolicLink() || !metadata.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function sameFileObservation(left, right) {
+    return (left.dev === right.dev &&
+        left.ino === right.ino &&
+        left.birthtimeNs === right.birthtimeNs &&
+        left.ctimeNs === right.ctimeNs &&
+        left.mtimeNs === right.mtimeNs &&
+        left.size === right.size);
+}
+async function readAtMost(handle, maximumBytes) {
+    const chunks = [];
+    let total = 0;
+    while (total <= maximumBytes) {
+        const remaining = maximumBytes + 1 - total;
+        const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, remaining));
+        const { bytesRead } = await handle.read(buffer, 0, buffer.byteLength, null);
+        if (bytesRead === 0) {
+            return Buffer.concat(chunks, total);
+        }
+        chunks.push(buffer.subarray(0, bytesRead));
+        total += bytesRead;
+    }
+    return undefined;
+}
+export async function readBoundedRegularFile(path, maximumBytes) {
+    if (!Number.isSafeInteger(maximumBytes) || maximumBytes < 0) {
+        throw new TypeError("maximumBytes must be a non-negative safe integer.");
+    }
+    if (await isExistingNonRegularPath(path)) {
+        return { outcome: "invalid" };
+    }
+    const noFollow = process.platform === "win32" ? 0 : constants.O_NOFOLLOW;
+    const nonBlocking = process.platform === "win32" ? 0 : constants.O_NONBLOCK;
+    let handle;
+    try {
+        handle = await open(path, constants.O_RDONLY | noFollow | nonBlocking);
+    }
+    catch (error) {
+        if (hasErrorCode(error, "ELOOP") ||
+            (await isExistingNonRegularPath(path))) {
+            return { outcome: "invalid" };
+        }
+        throw error;
+    }
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile() || before.size > BigInt(maximumBytes)) {
+            return { outcome: "invalid" };
+        }
+        const identity = identityFromStat(before);
+        const bytes = await readAtMost(handle, maximumBytes);
+        if (bytes === undefined) {
+            return { outcome: "invalid" };
+        }
+        const after = await handle.stat({ bigint: true });
+        if (!after.isFile() ||
+            !sameFileObservation(before, after) ||
+            after.size !== BigInt(bytes.byteLength) ||
+            (await pathMatchesFileIdentity(path, identity)) !== "match") {
+            return { outcome: "changed" };
+        }
+        return {
+            outcome: "read",
+            bytes,
+            identity,
+            mode: Number(after.mode)
+        };
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function captureFileHandleIdentity(handle) {
+    return identityFromStat(await handle.stat({ bigint: true }));
+}
+export async function pathMatchesFileIdentity(path, expected) {
+    try {
+        const metadata = await lstat(path, { bigint: true });
+        if (metadata.isSymbolicLink() || !metadata.isFile()) {
+            return "different";
+        }
+        const observed = identityFromStat(metadata);
+        return observed.dev === expected.dev &&
+            observed.ino === expected.ino &&
+            observed.birthtimeNs === expected.birthtimeNs
+            ? "match"
+            : "different";
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return "missing";
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=filesystem-file-identity.js.map

package/dist/scaffolding/adapters/node/filesystem-file-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-file-identity.js","sourceRoot":"","sources":["../../../../src/scaffolding/adapters/node/filesystem-file-identity.ts"],"names":[],"mappings":"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"}

package/dist/scaffolding/adapters/node/filesystem-finalization.d.ts

@@ -0,0 +1,22 @@
+import type { AuthorityScaffoldJournal, AuthorityScaffoldOperationReceipt, AuthorityScaffoldPlan, AuthorityScaffoldReceipt } from "../../contract/types.js";
+interface FinalizationFaultPoint {
+    readonly phase: "after-final-verification" | "after-journal-unlinked" | "before-final-authority-recheck";
+}
+type FinalizationFaultInjector = (point: FinalizationFaultPoint) => Promise<void> | void;
+export declare function staleBeforeJournal(plan: AuthorityScaffoldPlan): AuthorityScaffoldReceipt;
+export declare function verifyAlreadyAppliedScaffold(options: {
+    readonly root: string;
+    readonly plan: AuthorityScaffoldPlan;
+    readonly faultInjector?: FinalizationFaultInjector;
+}): Promise<AuthorityScaffoldReceipt>;
+interface FinalizationOptions {
+    readonly root: string;
+    readonly journalPath: string;
+    readonly journal: AuthorityScaffoldJournal;
+    readonly recovered: boolean;
+    readonly receipts: ReadonlyMap<string, AuthorityScaffoldOperationReceipt>;
+    readonly faultInjector?: FinalizationFaultInjector;
+}
+export declare function finalizeAuthorityScaffoldJournal(options: FinalizationOptions): Promise<AuthorityScaffoldReceipt>;
+export {};
+//# sourceMappingURL=filesystem-finalization.d.ts.map

package/dist/scaffolding/adapters/node/filesystem-finalization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem-finalization.d.ts","sourceRoot":"","sources":["../../../../src/scaffolding/adapters/node/filesystem-finalization.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,iCAAiC,EACjC,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,yBAAyB,CAAC;AAoBjC,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,KAAK,EACV,0BAA0B,GAC1B,wBAAwB,GACxB,gCAAgC,CAAC;CACtC;AAED,KAAK,yBAAyB,GAAG,CAC/B,KAAK,EAAE,sBAAsB,KAC1B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAE1B,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,qBAAqB,GAAG,wBAAwB,CAoBxF;AAwDD,wBAAsB,4BAA4B,CAAC,OAAO,EAAE;IAC1D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,aAAa,CAAC,EAAE,yBAAyB,CAAC;CACpD,GAAG,OAAO,CAAC,wBAAwB,CAAC,CA8BpC;AAED,UAAU,mBAAmB;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAC3C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,iCAAiC,CAAC,CAAC;IAC1E,QAAQ,CAAC,aAAa,CAAC,EAAE,yBAAyB,CAAC;CACpD;AA2DD,wBAAsB,gCAAgC,CACpD,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,wBAAwB,CAAC,CA8CnC"}