@agent-teams/engineering-foundation 0.12.0 → 0.13.1

package/dist/transaction-coordination/adapters/node/node-foundation-transaction-slot.js

@@ -0,0 +1,332 @@
+import { lstat, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { TextDecoder } from "node:util";
+import { FOUNDATION_TRANSACTION_FILE, FOUNDATION_TRANSACTION_TEMPORARY_FILE, FOUNDATION_LINK_STATE_FILE, FOUNDATION_REGISTRY_BACKUP, LOCAL_STATE_DIRECTORY } from "../../../foundation-state-contract.js";
+import { assertSchema } from "../../../schema-catalog.js";
+import { sha256Bytes, sha256Json } from "../../../scaffolding/kernel/canonical-json.js";
+import { assertAuthorityScaffoldJournal } from "../../../scaffolding/kernel/authority-journal-validation.js";
+import { parseStrictJson } from "../../../strict-json.js";
+import { readBoundedRegularFile } from "../../../repository-mutation/adapters/node/node-bounded-regular-file.js";
+const maximumTransactionBytes = 32 * 1024 * 1024;
+const maximumLinkStateBytes = 64 * 1024;
+const maximumStateDirectoryEntries = 1024;
+const strictUtf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
+function isMissing(error) {
+    return (error instanceof Error &&
+        "code" in error &&
+        error.code === "ENOENT");
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function pathExists(path) {
+    try {
+        await lstat(path);
+        return true;
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return false;
+        }
+        throw error;
+    }
+}
+function manual(reason, message) {
+    return {
+        state: "manual-recovery-required",
+        reason,
+        diagnostics: [
+            {
+                code: "FOUNDATION_TRANSACTION_MANUAL_RECOVERY_REQUIRED",
+                message
+            }
+        ]
+    };
+}
+function recoveryRoute(exactFoundationVersion) {
+    return {
+        commandId: "scaffold-recover",
+        exactFoundationVersion
+    };
+}
+function pending(options) {
+    const diagnostics = [];
+    if (options.foundationVersion !== options.installedVersion) {
+        diagnostics.push({
+            code: "FOUNDATION_TRANSACTION_VERSION_MISMATCH",
+            message: `Foundation ${options.foundationVersion} must recover the pending ${options.operationKind} transaction before package ${options.installedVersion} (${options.installedBuildIdentity}) can mutate this repository.`
+        });
+    }
+    else {
+        diagnostics.push({
+            code: "FOUNDATION_TRANSACTION_ACTIVE",
+            message: `A pending ${options.operationKind} transaction must be recovered before another Foundation mutation can start.`
+        });
+    }
+    return {
+        state: "pending",
+        operationKind: options.operationKind,
+        format: options.format,
+        foundationVersion: options.foundationVersion,
+        recovery: recoveryRoute(options.foundationVersion),
+        diagnostics
+    };
+}
+function localModePending(message) {
+    return {
+        state: "pending",
+        operationKind: "local-mode",
+        format: "local-mode-v1",
+        recovery: { commandId: "detach" },
+        diagnostics: [{ code: "FOUNDATION_TRANSACTION_ACTIVE", message }]
+    };
+}
+function parseLinkPhase(value) {
+    if (!isRecord(value)) {
+        throw new Error("Foundation local-mode recovery state is invalid.");
+    }
+    const expectedKeys = [
+        "attachedAt",
+        "consumerRoot",
+        "gitCommit",
+        "gitDirty",
+        "packageVersion",
+        "phase",
+        "registryBackupPath",
+        "registryEntryKind",
+        "registryPackageRoot",
+        "schemaVersion",
+        "targetPackageRoot"
+    ];
+    if (value["schemaVersion"] !== 1 ||
+        !["ATTACHING", "DETACHING", "LOCAL"].includes(String(value["phase"])) ||
+        typeof value["consumerRoot"] !== "string" ||
+        typeof value["targetPackageRoot"] !== "string" ||
+        typeof value["registryBackupPath"] !== "string" ||
+        !["directory", "symbolic-link"].includes(String(value["registryEntryKind"])) ||
+        typeof value["registryPackageRoot"] !== "string" ||
+        typeof value["packageVersion"] !== "string" ||
+        typeof value["gitCommit"] !== "string" ||
+        typeof value["gitDirty"] !== "boolean" ||
+        typeof value["attachedAt"] !== "string" ||
+        Object.keys(value).toSorted().join(",") !== expectedKeys.join(",")) {
+        throw new Error("Foundation local-mode recovery state is invalid.");
+    }
+    return value["phase"];
+}
+async function inspectLocalModeEvidence(stateDirectory) {
+    let entries;
+    try {
+        entries = await readdir(stateDirectory);
+    }
+    catch (error) {
+        if (isMissing(error)) {
+            return { state: "idle", diagnostics: [] };
+        }
+        return manual("local-mode-evidence-invalid", "Foundation local-mode recovery evidence cannot be inspected safely.");
+    }
+    if (entries.length > maximumStateDirectoryEntries) {
+        return manual("local-mode-evidence-invalid", "Foundation local-mode state contains too many entries.");
+    }
+    if (entries.some((entry) => entry.startsWith(`${FOUNDATION_LINK_STATE_FILE}.`) &&
+        entry.endsWith(".tmp"))) {
+        return manual("local-mode-evidence-invalid", "An incomplete Foundation local-mode state write requires manual recovery.");
+    }
+    const hasBackup = entries.includes(FOUNDATION_REGISTRY_BACKUP);
+    if (!entries.includes(FOUNDATION_LINK_STATE_FILE)) {
+        return hasBackup
+            ? localModePending("An orphan Foundation registry backup must be recovered with detach before another mutation can start.")
+            : { state: "idle", diagnostics: [] };
+    }
+    try {
+        const record = await readBoundedRegularFile(join(stateDirectory, FOUNDATION_LINK_STATE_FILE), maximumLinkStateBytes);
+        if (record.outcome !== "read") {
+            throw new Error("Foundation local-mode state is not a stable regular file.");
+        }
+        const phase = parseLinkPhase(parseStrictJson(strictUtf8.decode(record.bytes)));
+        if (phase === "LOCAL" && hasBackup) {
+            return { state: "idle", diagnostics: [] };
+        }
+        return localModePending(`Foundation local-mode recovery is required (${phase}${hasBackup ? "" : ", registry backup missing"}) before another mutation can start.`);
+    }
+    catch {
+        return manual("local-mode-evidence-invalid", "Foundation local-mode recovery evidence is invalid and was preserved.");
+    }
+}
+function assertEnvelopeDigests(envelope) {
+    const journal = envelope["journal"];
+    if (envelope["payloadDigest"] !== sha256Json(journal)) {
+        throw new Error("Foundation transaction payload digest is invalid.");
+    }
+    const { envelopeDigest, ...body } = envelope;
+    if (envelopeDigest !== sha256Json(body)) {
+        throw new Error("Foundation transaction envelope digest is invalid.");
+    }
+}
+function assertDocumentPlanDigest(plan) {
+    const { planDigest, ...body } = plan;
+    if (planDigest !== sha256Json(body)) {
+        throw new Error("Document Plan digest is invalid.");
+    }
+}
+function assertDocumentTransactionBindings(journal, plan, envelopeState) {
+    const intent = plan["intent"];
+    const output = plan["output"];
+    const destination = journal["destination"];
+    if (!isRecord(intent) ||
+        plan["intentDigest"] !== sha256Json(intent) ||
+        !isRecord(output) ||
+        typeof output["contentBase64"] !== "string" ||
+        !isRecord(destination) ||
+        destination["path"] !== plan["destination"]) {
+        throw new Error("Document transaction semantic binding is invalid.");
+    }
+    const outputBytes = Buffer.from(output["contentBase64"], "base64");
+    if (outputBytes.toString("base64") !== output["contentBase64"] ||
+        output["size"] !== outputBytes.byteLength ||
+        output["digest"] !== sha256Bytes(outputBytes)) {
+        throw new Error("Document transaction output binding is invalid.");
+    }
+    const ownedTemporary = journal["ownedTemporary"];
+    if (ownedTemporary !== undefined) {
+        if (!isRecord(ownedTemporary) ||
+            ownedTemporary["digest"] !== output["digest"] ||
+            typeof ownedTemporary["path"] !== "string" ||
+            ownedTemporary["path"] !== `${String(plan["destination"])}.foundation-document.tmp`) {
+            throw new Error("Document transaction temporary binding is invalid.");
+        }
+    }
+    const precondition = plan["destinationPrecondition"];
+    if (!isRecord(precondition)) {
+        throw new Error("Document transaction destination precondition is invalid.");
+    }
+    const lifecycle = `${String(precondition["state"])}:${String(destination["state"])}:${String(ownedTemporary !== undefined)}`;
+    const expectedLifecycle = new Map([
+        ["PREPARED", new Set(["absent:pending:false", "absent:preexisting:false"])],
+        ["PUBLISHING", new Set(["absent:publishing:true"])],
+        ["PUBLISHED", new Set(["absent:published:false"])],
+    ]).get(String(envelopeState));
+    if (expectedLifecycle === undefined || !expectedLifecycle.has(lifecycle)) {
+        throw new Error("Document transaction lifecycle binding is invalid.");
+    }
+}
+async function inspectParsedTransaction(value, installedVersion, installedBuildIdentity) {
+    if (!isRecord(value) || typeof value["schemaVersion"] !== "number") {
+        return manual("invalid-slot", "The Foundation transaction slot is invalid and was preserved.");
+    }
+    if (value["schemaVersion"] === 1) {
+        await assertSchema("scaffold-recovery-journal/v1", value, "foundation-transaction-slot");
+        const journal = value;
+        assertAuthorityScaffoldJournal(journal);
+        const plan = journal.plan;
+        const compiler = plan["compiler"];
+        if (!isRecord(compiler) || typeof compiler["version"] !== "string") {
+            throw new Error("Legacy scaffolding journal compiler version is invalid.");
+        }
+        return pending({
+            operationKind: "scaffolding",
+            format: "legacy-scaffolding-v1",
+            foundationVersion: compiler["version"],
+            installedVersion,
+            installedBuildIdentity
+        });
+    }
+    if (value["schemaVersion"] === 2) {
+        await assertSchema("foundation-transaction-envelope/v2", value, "foundation-transaction-slot");
+        assertEnvelopeDigests(value);
+        const foundation = value["foundation"];
+        const operationKind = value["operationKind"];
+        const journal = value["journal"];
+        if (!isRecord(foundation) ||
+            typeof foundation["version"] !== "string" ||
+            typeof foundation["buildIdentity"] !== "string" ||
+            !isRecord(journal) ||
+            !["document-authoring", "scaffolding"].includes(String(operationKind))) {
+            throw new Error("Foundation transaction envelope binding is invalid.");
+        }
+        const plan = journal["plan"];
+        if (!isRecord(plan)) {
+            throw new Error("Foundation transaction Plan binding is invalid.");
+        }
+        const compiler = plan["compiler"];
+        if (!isRecord(compiler) ||
+            compiler["version"] !== foundation["version"] ||
+            (operationKind === "document-authoring" &&
+                compiler["buildIdentity"] !== foundation["buildIdentity"])) {
+            throw new Error("Foundation transaction compiler binding is invalid.");
+        }
+        if (operationKind === "document-authoring") {
+            assertDocumentPlanDigest(plan);
+            assertDocumentTransactionBindings(journal, plan, value["state"]);
+        }
+        else {
+            assertAuthorityScaffoldJournal(journal);
+        }
+        return {
+            state: "manual-recovery-required",
+            reason: "recovery-handler-unavailable",
+            operationKind: operationKind,
+            format: "envelope-v2",
+            foundationVersion: foundation["version"],
+            foundationBuildIdentity: foundation["buildIdentity"],
+            diagnostics: [
+                {
+                    code: "FOUNDATION_TRANSACTION_MANUAL_RECOVERY_REQUIRED",
+                    message: `A verified ${String(operationKind)} envelope v2 from Foundation ${foundation["version"]} (${foundation["buildIdentity"]}) was preserved, but this release does not yet provide its recovery handler.`
+                }
+            ]
+        };
+    }
+    return manual("unsupported-schema", `Foundation transaction schema version ${String(value["schemaVersion"])} is unsupported and was preserved.`);
+}
+export class NodeFoundationTransactionSlot {
+    #installedBuildIdentity;
+    #installedVersion;
+    #stateDirectory;
+    #slotPath;
+    #temporaryPath;
+    constructor(options) {
+        this.#installedBuildIdentity = options.installedBuildIdentity;
+        this.#installedVersion = options.installedVersion;
+        const stateDirectory = join(options.consumerRoot, LOCAL_STATE_DIRECTORY);
+        this.#stateDirectory = stateDirectory;
+        this.#slotPath = join(stateDirectory, FOUNDATION_TRANSACTION_FILE);
+        this.#temporaryPath = join(stateDirectory, FOUNDATION_TRANSACTION_TEMPORARY_FILE);
+    }
+    async #inspectTransactionEvidence() {
+        if (await pathExists(this.#temporaryPath)) {
+            return manual("orphan-temporary", "An orphan Foundation transaction temporary exists; it was preserved and requires manual recovery.");
+        }
+        let record;
+        try {
+            record = await readBoundedRegularFile(this.#slotPath, maximumTransactionBytes);
+        }
+        catch (error) {
+            if (isMissing(error)) {
+                return { state: "idle", diagnostics: [] };
+            }
+            return manual("invalid-slot", "The Foundation transaction slot could not be read safely and was preserved.");
+        }
+        if (record.outcome !== "read") {
+            return manual("unstable-slot", "The Foundation transaction slot is not a stable bounded regular file and was preserved.");
+        }
+        try {
+            const source = strictUtf8.decode(record.bytes);
+            return await inspectParsedTransaction(parseStrictJson(source), this.#installedVersion, this.#installedBuildIdentity);
+        }
+        catch {
+            return manual("corrupt-or-incompatible", "The Foundation transaction slot is corrupt, tampered, or incompatible; it was preserved.");
+        }
+    }
+    async inspect() {
+        const [localMode, transaction] = await Promise.all([
+            inspectLocalModeEvidence(this.#stateDirectory),
+            this.#inspectTransactionEvidence()
+        ]);
+        if (localMode.state !== "idle" && transaction.state !== "idle") {
+            return manual("multiple-transactions", "Local-mode and transaction-slot recovery evidence coexist; both were preserved and require manual recovery.");
+        }
+        return transaction.state === "idle" ? localMode : transaction;
+    }
+}
+//# sourceMappingURL=node-foundation-transaction-slot.js.map

package/dist/transaction-coordination/adapters/node/node-foundation-transaction-slot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-foundation-transaction-slot.js","sourceRoot":"","sources":["../../../../src/transaction-coordination/adapters/node/node-foundation-transaction-slot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EACL,2BAA2B,EAC3B,qCAAqC,EACrC,0BAA0B,EAC1B,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,EACL,WAAW,EACX,UAAU,EACX,MAAM,+CAA+C,CAAC;AAKvD,OAAO,EAAE,8BAA8B,EAAE,MAAM,6DAA6D,CAAC;AAC7G,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAQ1D,OAAO,EAAE,sBAAsB,EAAE,MAAM,yEAAyE,CAAC;AAEjH,MAAM,uBAAuB,GAAG,EAAE,GAAG,IAAI,GAAG,IAAI,CAAC;AACjD,MAAM,qBAAqB,GAAG,EAAE,GAAG,IAAI,CAAC;AACxC,MAAM,4BAA4B,GAAG,IAAI,CAAC;AAC1C,MAAM,UAAU,GAAG,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AAE9E,SAAS,SAAS,CAAC,KAAc;IAC/B,OAAO,CACL,KAAK,YAAY,KAAK;QACtB,MAAM,IAAI,KAAK;QACd,KAA+B,CAAC,IAAI,KAAK,QAAQ,CACnD,CAAC;AACJ,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,MAAM,KAAK,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,MAAM,CACb,MAAsC,EACtC,OAAe;IAEf,OAAO;QACL,KAAK,EAAE,0BAA0B;QACjC,MAAM;QACN,WAAW,EAAE;YACX;gBACE,IAAI,EAAE,iDAAiD;gBACvD,OAAO;aACR;SACF;KACF,CAAC;AACJ,CAAC;AAED,SAAS,aAAa,CAAC,sBAA8B;IACnD,OAAO;QACL,SAAS,EAAE,kBAAkB;QAC7B,sBAAsB;KACvB,CAAC;AACJ,CAAC;AAED,SAAS,OAAO,CAAC,OAMhB;IACC,MAAM,WAAW,GAAsC,EAAE,CAAC;IAC1D,IAAI,OAAO,CAAC,iBAAiB,KAAK,OAAO,CAAC,gBAAgB,EAAE,CAAC;QAC3D,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,yCAAyC;YAC/C,OAAO,EAAE,cAAc,OAAO,CAAC,iBAAiB,6BAA6B,OAAO,CAAC,aAAa,+BAA+B,OAAO,CAAC,gBAAgB,KAAK,OAAO,CAAC,sBAAsB,+BAA+B;SAC5N,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,WAAW,CAAC,IAAI,CAAC;YACf,IAAI,EAAE,+BAA+B;YACrC,OAAO,EAAE,aAAa,OAAO,CAAC,aAAa,8EAA8E;SAC1H,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,KAAK,EAAE,SAAS;QAChB,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,iBAAiB,CAAC;QAClD,WAAW;KACZ,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAe;IACvC,OAAO;QACL,KAAK,EAAE,SAAS;QAChB,aAAa,EAAE,YAAY;QAC3B,MAAM,EAAE,eAAe;QACvB,QAAQ,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE;QACjC,WAAW,EAAE,CAAC,EAAE,IAAI,EAAE,+BAA+B,EAAE,OAAO,EAAE,CAAC;KAClE,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,MAAM,YAAY,GAAG;QACnB,YAAY;QACZ,cAAc;QACd,WAAW;QACX,UAAU;QACV,gBAAgB;QAChB,OAAO;QACP,oBAAoB;QACpB,mBAAmB;QACnB,qBAAqB;QACrB,eAAe;QACf,mBAAmB;KACpB,CAAC;IACF,IACE,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC;QAC5B,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACrE,OAAO,KAAK,CAAC,cAAc,CAAC,KAAK,QAAQ;QACzC,OAAO,KAAK,CAAC,mBAAmB,CAAC,KAAK,QAAQ;QAC9C,OAAO,KAAK,CAAC,oBAAoB,CAAC,KAAK,QAAQ;QAC/C,CAAC,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;QAC5E,OAAO,KAAK,CAAC,qBAAqB,CAAC,KAAK,QAAQ;QAChD,OAAO,KAAK,CAAC,gBAAgB,CAAC,KAAK,QAAQ;QAC3C,OAAO,KAAK,CAAC,WAAW,CAAC,KAAK,QAAQ;QACtC,OAAO,KAAK,CAAC,UAAU,CAAC,KAAK,SAAS;QACtC,OAAO,KAAK,CAAC,YAAY,CAAC,KAAK,QAAQ;QACvC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,EAClE,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,kDAAkD,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAwC,CAAC;AAC/D,CAAC;AAED,KAAK,UAAU,wBAAwB,CACrC,cAAsB;IAEtB,IAAI,OAAiB,CAAC;IACtB,IAAI,CAAC;QACH,OAAO,GAAG,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;YACrB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;QAC5C,CAAC;QACD,OAAO,MAAM,CACX,6BAA6B,EAC7B,qEAAqE,CACtE,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,4BAA4B,EAAE,CAAC;QAClD,OAAO,MAAM,CACX,6BAA6B,EAC7B,wDAAwD,CACzD,CAAC;IACJ,CAAC;IACD,IACE,OAAO,CAAC,IAAI,CACV,CAAC,KAAK,EAAE,EAAE,CACR,KAAK,CAAC,UAAU,CAAC,GAAG,0BAA0B,GAAG,CAAC;QAClD,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CACzB,EACD,CAAC;QACD,OAAO,MAAM,CACX,6BAA6B,EAC7B,2EAA2E,CAC5E,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAC,CAAC;IAC/D,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAC,EAAE,CAAC;QAClD,OAAO,SAAS;YACd,CAAC,CAAC,gBAAgB,CACd,uGAAuG,CACxG;YACH,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;IACzC,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,sBAAsB,CACzC,IAAI,CAAC,cAAc,EAAE,0BAA0B,CAAC,EAChD,qBAAqB,CACtB,CAAC;QACF,IAAI,MAAM,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YAC9B,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;QAC/E,CAAC;QACD,MAAM,KAAK,GAAG,cAAc,CAC1B,eAAe,CAAC,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CACjD,CAAC;QACF,IAAI,KAAK,KAAK,OAAO,IAAI,SAAS,EAAE,CAAC;YACnC,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;QAC5C,CAAC;QACD,OAAO,gBAAgB,CACrB,+CAA+C,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,2BAA2B,sCAAsC,CAC1I,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CACX,6BAA6B,EAC7B,uEAAuE,CACxE,CAAC;IACJ,CAAC;AACH,CAAC;AAED,SAAS,qBAAqB,CAAC,QAAiC;IAC9D,MAAM,OAAO,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IACpC,IAAI,QAAQ,CAAC,eAAe,CAAC,KAAK,UAAU,CAAC,OAAoB,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,EAAE,cAAc,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC;IAC7C,IAAI,cAAc,KAAK,UAAU,CAAC,IAAiB,CAAC,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;AACH,CAAC;AAED,SAAS,wBAAwB,CAAC,IAA6B;IAC7D,MAAM,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,IAAI,CAAC;IACrC,IAAI,UAAU,KAAK,UAAU,CAAC,IAAiB,CAAC,EAAE,CAAC;QACjD,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED,SAAS,iCAAiC,CACxC,OAAgC,EAChC,IAA6B,EAC7B,aAAsB;IAEtB,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9B,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAC;IAC9B,MAAM,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;IAC3C,IACE,CAAC,QAAQ,CAAC,MAAM,CAAC;QACjB,IAAI,CAAC,cAAc,CAAC,KAAK,UAAU,CAAC,MAAmB,CAAC;QACxD,CAAC,QAAQ,CAAC,MAAM,CAAC;QACjB,OAAO,MAAM,CAAC,eAAe,CAAC,KAAK,QAAQ;QAC3C,CAAC,QAAQ,CAAC,WAAW,CAAC;QACtB,WAAW,CAAC,MAAM,CAAC,KAAK,IAAI,CAAC,aAAa,CAAC,EAC3C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;IACvE,CAAC;IACD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,CAAC;IACnE,IACE,WAAW,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,eAAe,CAAC;QAC1D,MAAM,CAAC,MAAM,CAAC,KAAK,WAAW,CAAC,UAAU;QACzC,MAAM,CAAC,QAAQ,CAAC,KAAK,WAAW,CAAC,WAAW,CAAC,EAC7C,CAAC;QACD,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;IACrE,CAAC;IACD,MAAM,cAAc,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACjD,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,IACE,CAAC,QAAQ,CAAC,cAAc,CAAC;YACzB,cAAc,CAAC,QAAQ,CAAC,KAAK,MAAM,CAAC,QAAQ,CAAC;YAC7C,OAAO,cAAc,CAAC,MAAM,CAAC,KAAK,QAAQ;YAC1C,cAAc,CAAC,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,0BAA0B,EACnF,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IACD,MAAM,YAAY,GAAG,IAAI,CAAC,yBAAyB,CAAC,CAAC;IACrD,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,2DAA2D,CAAC,CAAC;IAC/E,CAAC;IACD,MAAM,SAAS,GAAG,GAAG,MAAM,CAAC,YAAY,CAAC,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,MAAM,CAAC,cAAc,KAAK,SAAS,CAAC,EAAE,CAAC;IAC7H,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;QAChC,CAAC,UAAU,EAAE,IAAI,GAAG,CAAC,CAAC,sBAAsB,EAAE,0BAA0B,CAAC,CAAC,CAAC;QAC3E,CAAC,YAAY,EAAE,IAAI,GAAG,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC;QACnD,CAAC,WAAW,EAAE,IAAI,GAAG,CAAC,CAAC,wBAAwB,CAAC,CAAC,CAAC;KACnD,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC;IAC9B,IAAI,iBAAiB,KAAK,SAAS,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;QACzE,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;AACH,CAAC;AAED,KAAK,UAAU,wBAAwB,CACrC,KAAc,EACd,gBAAwB,EACxB,sBAA8B;IAE9B,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,eAAe,CAAC,KAAK,QAAQ,EAAE,CAAC;QACnE,OAAO,MAAM,CACX,cAAc,EACd,+DAA+D,CAChE,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,YAAY,CAChB,8BAA8B,EAC9B,KAAK,EACL,6BAA6B,CAC9B,CAAC;QACF,MAAM,OAAO,GAAG,KAA4C,CAAC;QAC7D,8BAA8B,CAAC,OAAO,CAAC,CAAC;QACxC,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QAC1B,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAClC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,OAAO,QAAQ,CAAC,SAAS,CAAC,KAAK,QAAQ,EAAE,CAAC;YACnE,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;QAC7E,CAAC;QACD,OAAO,OAAO,CAAC;YACb,aAAa,EAAE,aAAa;YAC5B,MAAM,EAAE,uBAAuB;YAC/B,iBAAiB,EAAE,QAAQ,CAAC,SAAS,CAAC;YACtC,gBAAgB;YAChB,sBAAsB;SACvB,CAAC,CAAC;IACL,CAAC;IACD,IAAI,KAAK,CAAC,eAAe,CAAC,KAAK,CAAC,EAAE,CAAC;QACjC,MAAM,YAAY,CAChB,oCAAoC,EACpC,KAAK,EACL,6BAA6B,CAC9B,CAAC;QACF,qBAAqB,CAAC,KAAK,CAAC,CAAC;QAC7B,MAAM,UAAU,GAAG,KAAK,CAAC,YAAY,CAAC,CAAC;QACvC,MAAM,aAAa,GAAG,KAAK,CAAC,eAAe,CAAC,CAAC;QAC7C,MAAM,OAAO,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;QACjC,IACE,CAAC,QAAQ,CAAC,UAAU,CAAC;YACrB,OAAO,UAAU,CAAC,SAAS,CAAC,KAAK,QAAQ;YACzC,OAAO,UAAU,CAAC,eAAe,CAAC,KAAK,QAAQ;YAC/C,CAAC,QAAQ,CAAC,OAAO,CAAC;YAClB,CAAC,CAAC,oBAAoB,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC,EACtE,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;QACD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;QAC7B,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACpB,MAAM,IAAI,KAAK,CAAC,iDAAiD,CAAC,CAAC;QACrE,CAAC;QACD,MAAM,QAAQ,GAAG,IAAI,CAAC,UAAU,CAAC,CAAC;QAClC,IACE,CAAC,QAAQ,CAAC,QAAQ,CAAC;YACnB,QAAQ,CAAC,SAAS,CAAC,KAAK,UAAU,CAAC,SAAS,CAAC;YAC7C,CAAC,aAAa,KAAK,oBAAoB;gBACrC,QAAQ,CAAC,eAAe,CAAC,KAAK,UAAU,CAAC,eAAe,CAAC,CAAC,EAC5D,CAAC;YACD,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,aAAa,KAAK,oBAAoB,EAAE,CAAC;YAC3C,wBAAwB,CAAC,IAAI,CAAC,CAAC;YAC/B,iCAAiC,CAAC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QACnE,CAAC;aAAM,CAAC;YACN,8BAA8B,CAC5B,OAA8C,CAC/C,CAAC;QACJ,CAAC;QACD,OAAO;YACL,KAAK,EAAE,0BAA0B;YACjC,MAAM,EAAE,8BAA8B;YACtC,aAAa,EAAE,aAAqD;YACpE,MAAM,EAAE,aAAa;YACrB,iBAAiB,EAAE,UAAU,CAAC,SAAS,CAAC;YACxC,uBAAuB,EAAE,UAAU,CAAC,eAAe,CAAC;YACpD,WAAW,EAAE;gBACX;oBACE,IAAI,EAAE,iDAAiD;oBACvD,OAAO,EAAE,cAAc,MAAM,CAAC,aAAa,CAAC,gCAAgC,UAAU,CAAC,SAAS,CAAC,KAAK,UAAU,CAAC,eAAe,CAAC,8EAA8E;iBAChN;aACF;SACF,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CACX,oBAAoB,EACpB,yCAAyC,MAAM,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,oCAAoC,CAC5G,CAAC;AACJ,CAAC;AAED,MAAM,OAAO,6BAA6B;IAC/B,uBAAuB,CAAS;IAChC,iBAAiB,CAAS;IAC1B,eAAe,CAAS;IACxB,SAAS,CAAS;IAClB,cAAc,CAAS;IAEhC,YAAY,OAIX;QACC,IAAI,CAAC,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC;QAC9D,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC;QAClD,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,YAAY,EAAE,qBAAqB,CAAC,CAAC;QACzE,IAAI,CAAC,eAAe,GAAG,cAAc,CAAC;QACtC,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,cAAc,EAAE,2BAA2B,CAAC,CAAC;QACnE,IAAI,CAAC,cAAc,GAAG,IAAI,CACxB,cAAc,EACd,qCAAqC,CACtC,CAAC;IACJ,CAAC;IAED,KAAK,CAAC,2BAA2B;QAC/B,IAAI,MAAM,UAAU,CAAC,IAAI,CAAC,cAAc,CAAC,EAAE,CAAC;YAC1C,OAAO,MAAM,CACX,kBAAkB,EAClB,mGAAmG,CACpG,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC;QACX,IAAI,CAAC;YACH,MAAM,GAAG,MAAM,sBAAsB,CACnC,IAAI,CAAC,SAAS,EACd,uBAAuB,CACxB,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;gBACrB,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC;YAC5C,CAAC;YACD,OAAO,MAAM,CACX,cAAc,EACd,6EAA6E,CAC9E,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,OAAO,KAAK,MAAM,EAAE,CAAC;YAC9B,OAAO,MAAM,CACX,eAAe,EACf,yFAAyF,CAC1F,CAAC;QACJ,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAC/C,OAAO,MAAM,wBAAwB,CACnC,eAAe,CAAC,MAAM,CAAC,EACvB,IAAI,CAAC,iBAAiB,EACtB,IAAI,CAAC,uBAAuB,CAC7B,CAAC;QACJ,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,MAAM,CACX,yBAAyB,EACzB,0FAA0F,CAC3F,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO;QACX,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;YACjD,wBAAwB,CAAC,IAAI,CAAC,eAAe,CAAC;YAC9C,IAAI,CAAC,2BAA2B,EAAE;SACnC,CAAC,CAAC;QACH,IAAI,SAAS,CAAC,KAAK,KAAK,MAAM,IAAI,WAAW,CAAC,KAAK,KAAK,MAAM,EAAE,CAAC;YAC/D,OAAO,MAAM,CACX,uBAAuB,EACvB,6GAA6G,CAC9G,CAAC;QACJ,CAAC;QACD,OAAO,WAAW,CAAC,KAAK,KAAK,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC;IAChE,CAAC;CACF"}

package/dist/transaction-coordination/application/foundation-transaction-coordinator.d.ts

@@ -0,0 +1,22 @@
+import type { FoundationMutationKind, FoundationTransactionStatus } from "./model/transaction-status.js";
+import type { FoundationOperationLock } from "./ports/foundation-operation-lock.js";
+import type { FoundationTransactionSlot } from "./ports/foundation-transaction-slot.js";
+export interface FoundationTransactionLease {
+    readonly status: FoundationTransactionStatus;
+    release(options?: {
+        readonly retainTransactionBarrier?: boolean;
+    }): Promise<void>;
+}
+export declare class FoundationTransactionCoordinator {
+    #private;
+    constructor(options: {
+        readonly lock: FoundationOperationLock;
+        readonly slot: FoundationTransactionSlot;
+    });
+    inspect(): Promise<FoundationTransactionStatus>;
+    acquire(options: {
+        readonly requestedMutation: FoundationMutationKind;
+        readonly allowRecoveryOf?: "local-mode" | "scaffolding";
+    }): Promise<FoundationTransactionLease>;
+}
+//# sourceMappingURL=foundation-transaction-coordinator.d.ts.map

package/dist/transaction-coordination/application/foundation-transaction-coordinator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-transaction-coordinator.d.ts","sourceRoot":"","sources":["../../../src/transaction-coordination/application/foundation-transaction-coordinator.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,sBAAsB,EACtB,2BAA2B,EAC5B,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sCAAsC,CAAC;AACpF,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,wCAAwC,CAAC;AAsCxF,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;IAC7C,OAAO,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnF;AAED,qBAAa,gCAAgC;;IAI3C,YAAY,OAAO,EAAE;QACnB,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;QACvC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;KAC1C,EAGA;IAEK,OAAO,IAAI,OAAO,CAAC,2BAA2B,CAAC,CAEpD;IAEK,OAAO,CAAC,OAAO,EAAE;QACrB,QAAQ,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;QACnD,QAAQ,CAAC,eAAe,CAAC,EAAE,YAAY,GAAG,aAAa,CAAC;KACzD,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAgDtC;CACF"}

package/dist/transaction-coordination/application/foundation-transaction-coordinator.js

@@ -0,0 +1,78 @@
+import { FoundationTransactionError } from "./foundation-transaction-error.js";
+function preservePrimaryFailure(primaryFailure, releaseFailure) {
+    if (!(primaryFailure instanceof Error)) {
+        return new AggregateError([primaryFailure, releaseFailure], "Foundation transaction and operation-lock release both failed.");
+    }
+    const previousCause = primaryFailure.cause;
+    const releaseEvidence = previousCause === undefined
+        ? releaseFailure
+        : new AggregateError([previousCause, releaseFailure], "The primary failure cause and operation-lock release both failed.");
+    const attached = Reflect.defineProperty(primaryFailure, "cause", {
+        configurable: true,
+        value: releaseEvidence,
+        writable: true
+    });
+    return attached
+        ? primaryFailure
+        : new AggregateError([primaryFailure, releaseFailure], "Foundation transaction and operation-lock release both failed.");
+}
+function observedStatusFormat(status) {
+    return Reflect.get(status, "format");
+}
+export class FoundationTransactionCoordinator {
+    #lock;
+    #slot;
+    constructor(options) {
+        this.#lock = options.lock;
+        this.#slot = options.slot;
+    }
+    async inspect() {
+        return this.#slot.inspect();
+    }
+    async acquire(options) {
+        const release = await this.#lock.acquire();
+        let held = true;
+        try {
+            const status = await this.#slot.inspect();
+            const scaffoldingRecoveryAllowed = status.state === "pending" &&
+                status.operationKind === "scaffolding" &&
+                observedStatusFormat(status) === "legacy-scaffolding-v1" &&
+                options.allowRecoveryOf === status.operationKind &&
+                options.requestedMutation === status.operationKind &&
+                !status.diagnostics.some(({ code }) => code === "FOUNDATION_TRANSACTION_VERSION_MISMATCH");
+            const localModeRecoveryAllowed = status.state === "pending" &&
+                status.operationKind === "local-mode" &&
+                observedStatusFormat(status) === "local-mode-v1" &&
+                options.allowRecoveryOf === "local-mode" &&
+                options.requestedMutation === "detach";
+            if (status.state !== "idle" &&
+                !scaffoldingRecoveryAllowed &&
+                !localModeRecoveryAllowed) {
+                throw new FoundationTransactionError({
+                    requestedMutation: options.requestedMutation,
+                    status
+                });
+            }
+            return {
+                status,
+                async release(releaseOptions) {
+                    if (held) {
+                        await release(releaseOptions);
+                        held = false;
+                    }
+                }
+            };
+        }
+        catch (error) {
+            try {
+                await release({ retainTransactionBarrier: true });
+                held = false;
+            }
+            catch (releaseError) {
+                throw preservePrimaryFailure(error, releaseError);
+            }
+            throw error;
+        }
+    }
+}
+//# sourceMappingURL=foundation-transaction-coordinator.js.map

package/dist/transaction-coordination/application/foundation-transaction-coordinator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-transaction-coordinator.js","sourceRoot":"","sources":["../../../src/transaction-coordination/application/foundation-transaction-coordinator.ts"],"names":[],"mappings":"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"}

package/dist/transaction-coordination/application/foundation-transaction-error.d.ts

@@ -0,0 +1,16 @@
+import type { FoundationMutationKind, FoundationTransactionDiagnostic, FoundationTransactionStatus } from "./model/transaction-status.js";
+export declare class FoundationTransactionError extends Error {
+    readonly code: "FOUNDATION_TRANSACTION_ACTIVE" | "FOUNDATION_TRANSACTION_MANUAL_RECOVERY_REQUIRED" | "FOUNDATION_TRANSACTION_VERSION_MISMATCH";
+    readonly diagnostics: readonly FoundationTransactionDiagnostic[];
+    readonly requestedMutation: FoundationMutationKind;
+    readonly status: Exclude<FoundationTransactionStatus, {
+        readonly state: "idle";
+    }>;
+    constructor(options: {
+        readonly requestedMutation: FoundationMutationKind;
+        readonly status: Exclude<FoundationTransactionStatus, {
+            readonly state: "idle";
+        }>;
+    });
+}
+//# sourceMappingURL=foundation-transaction-error.d.ts.map

package/dist/transaction-coordination/application/foundation-transaction-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-transaction-error.d.ts","sourceRoot":"","sources":["../../../src/transaction-coordination/application/foundation-transaction-error.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,+BAA+B,EAC/B,2BAA2B,EAC5B,MAAM,+BAA+B,CAAC;AAEvC,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EACT,+BAA+B,GAC/B,iDAAiD,GACjD,yCAAyC,CAAC;IAC9C,QAAQ,CAAC,WAAW,EAAE,SAAS,+BAA+B,EAAE,CAAC;IACjE,QAAQ,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;IACnD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,2BAA2B,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAElF,YAAY,OAAO,EAAE;QACnB,QAAQ,CAAC,iBAAiB,EAAE,sBAAsB,CAAC;QACnD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,2BAA2B,EAAE;YAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACnF,EAWA;CACF"}

package/dist/transaction-coordination/application/foundation-transaction-error.js

@@ -0,0 +1,19 @@
+export class FoundationTransactionError extends Error {
+    code;
+    diagnostics;
+    requestedMutation;
+    status;
+    constructor(options) {
+        const primary = options.status.diagnostics[0] ?? {
+            code: "FOUNDATION_TRANSACTION_ACTIVE",
+            message: "A Foundation transaction requires recovery before another mutation can start."
+        };
+        super(primary.message);
+        this.name = "FoundationTransactionError";
+        this.code = primary.code;
+        this.diagnostics = options.status.diagnostics;
+        this.requestedMutation = options.requestedMutation;
+        this.status = options.status;
+    }
+}
+//# sourceMappingURL=foundation-transaction-error.js.map

package/dist/transaction-coordination/application/foundation-transaction-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-transaction-error.js","sourceRoot":"","sources":["../../../src/transaction-coordination/application/foundation-transaction-error.ts"],"names":[],"mappings":"AAMA,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,CAGiC;IACrC,WAAW,CAA6C;IACxD,iBAAiB,CAAyB;IAC1C,MAAM,CAAmE;IAElF,YAAY,OAGX;QACC,MAAM,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI;YAC/C,IAAI,EAAE,+BAAwC;YAC9C,OAAO,EAAE,+EAA+E;SACzF,CAAC;QACF,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;QACzB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,WAAW,CAAC;QAC9C,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,iBAAiB,CAAC;QACnD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAC/B,CAAC;CACF"}

package/dist/transaction-coordination/application/model/transaction-status.d.ts

@@ -0,0 +1,47 @@
+export type FoundationMutationKind = "attach" | "detach" | "document-authoring" | "scaffolding";
+export type FoundationRecoveryRoute = {
+    readonly commandId: "scaffold-recover";
+    readonly exactFoundationVersion: string;
+    readonly exactFoundationBuildIdentity?: string;
+} | {
+    readonly commandId: "detach";
+};
+export type FoundationTransactionDiagnostic = {
+    readonly code: "FOUNDATION_TRANSACTION_ACTIVE";
+    readonly message: string;
+} | {
+    readonly code: "FOUNDATION_TRANSACTION_MANUAL_RECOVERY_REQUIRED";
+    readonly message: string;
+} | {
+    readonly code: "FOUNDATION_TRANSACTION_VERSION_MISMATCH";
+    readonly message: string;
+};
+export type FoundationManualRecoveryReason = "corrupt-or-incompatible" | "invalid-slot" | "local-mode-evidence-invalid" | "multiple-transactions" | "orphan-temporary" | "recovery-handler-unavailable" | "unstable-slot" | "unsupported-schema";
+export type FoundationTransactionStatus = {
+    readonly state: "idle";
+    readonly diagnostics: readonly [];
+} | {
+    readonly state: "pending";
+    readonly operationKind: "scaffolding";
+    readonly format: "legacy-scaffolding-v1";
+    readonly foundationVersion: string;
+    readonly recovery: FoundationRecoveryRoute;
+    readonly diagnostics: readonly FoundationTransactionDiagnostic[];
+} | {
+    readonly state: "pending";
+    readonly operationKind: "local-mode";
+    readonly format: "local-mode-v1";
+    readonly recovery: {
+        readonly commandId: "detach";
+    };
+    readonly diagnostics: readonly FoundationTransactionDiagnostic[];
+} | {
+    readonly state: "manual-recovery-required";
+    readonly reason: FoundationManualRecoveryReason;
+    readonly operationKind?: "document-authoring" | "scaffolding";
+    readonly format?: "envelope-v2";
+    readonly foundationVersion?: string;
+    readonly foundationBuildIdentity?: string;
+    readonly diagnostics: readonly FoundationTransactionDiagnostic[];
+};
+//# sourceMappingURL=transaction-status.d.ts.map

package/dist/transaction-coordination/application/model/transaction-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-status.d.ts","sourceRoot":"","sources":["../../../../src/transaction-coordination/application/model/transaction-status.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAC9B,QAAQ,GACR,QAAQ,GACR,oBAAoB,GACpB,aAAa,CAAC;AAElB,MAAM,MAAM,uBAAuB,GAC/B;IACE,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,4BAA4B,CAAC,EAAE,MAAM,CAAC;CAChD,GACD;IACE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC;CAC9B,CAAC;AAEN,MAAM,MAAM,+BAA+B,GACvC;IACE,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,iDAAiD,CAAC;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,yCAAyC,CAAC;IACzD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEN,MAAM,MAAM,8BAA8B,GACtC,yBAAyB,GACzB,cAAc,GACd,6BAA6B,GAC7B,uBAAuB,GACvB,kBAAkB,GAClB,8BAA8B,GAC9B,eAAe,GACf,oBAAoB,CAAC;AAEzB,MAAM,MAAM,2BAA2B,GACnC;IACE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,SAAS,EAAE,CAAC;CACnC,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,QAAQ,CAAC,WAAW,EAAE,SAAS,+BAA+B,EAAE,CAAC;CAClE,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAA;KAAE,CAAC;IACpD,QAAQ,CAAC,WAAW,EAAE,SAAS,+BAA+B,EAAE,CAAC;CAClE,GACD;IACE,QAAQ,CAAC,KAAK,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,8BAA8B,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,oBAAoB,GAAG,aAAa,CAAC;IAC9D,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;IAChC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,uBAAuB,CAAC,EAAE,MAAM,CAAC;IAC1C,QAAQ,CAAC,WAAW,EAAE,SAAS,+BAA+B,EAAE,CAAC;CAClE,CAAC"}

package/dist/transaction-coordination/application/model/transaction-status.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=transaction-status.js.map

package/dist/transaction-coordination/application/model/transaction-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transaction-status.js","sourceRoot":"","sources":["../../../../src/transaction-coordination/application/model/transaction-status.ts"],"names":[],"mappings":""}

package/dist/transaction-coordination/application/ports/foundation-operation-lock.d.ts

@@ -0,0 +1,7 @@
+export interface FoundationOperationReleaseOptions {
+    readonly retainTransactionBarrier?: boolean;
+}
+export interface FoundationOperationLock {
+    acquire(): Promise<(options?: FoundationOperationReleaseOptions) => Promise<void>>;
+}
+//# sourceMappingURL=foundation-operation-lock.d.ts.map

package/dist/transaction-coordination/application/ports/foundation-operation-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-operation-lock.d.ts","sourceRoot":"","sources":["../../../../src/transaction-coordination/application/ports/foundation-operation-lock.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,iCAAiC;IAChD,QAAQ,CAAC,wBAAwB,CAAC,EAAE,OAAO,CAAC;CAC7C;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,IAAI,OAAO,CAChB,CAAC,OAAO,CAAC,EAAE,iCAAiC,KAAK,OAAO,CAAC,IAAI,CAAC,CAC/D,CAAC;CACH"}

package/dist/transaction-coordination/application/ports/foundation-operation-lock.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=foundation-operation-lock.js.map

package/dist/transaction-coordination/application/ports/foundation-operation-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-operation-lock.js","sourceRoot":"","sources":["../../../../src/transaction-coordination/application/ports/foundation-operation-lock.ts"],"names":[],"mappings":""}

package/dist/transaction-coordination/application/ports/foundation-transaction-slot.d.ts

@@ -0,0 +1,5 @@
+import type { FoundationTransactionStatus } from "../model/transaction-status.js";
+export interface FoundationTransactionSlot {
+    inspect(): Promise<FoundationTransactionStatus>;
+}
+//# sourceMappingURL=foundation-transaction-slot.d.ts.map

package/dist/transaction-coordination/application/ports/foundation-transaction-slot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-transaction-slot.d.ts","sourceRoot":"","sources":["../../../../src/transaction-coordination/application/ports/foundation-transaction-slot.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,gCAAgC,CAAC;AAElF,MAAM,WAAW,yBAAyB;IACxC,OAAO,IAAI,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACjD"}

package/dist/transaction-coordination/application/ports/foundation-transaction-slot.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=foundation-transaction-slot.js.map

package/dist/transaction-coordination/application/ports/foundation-transaction-slot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"foundation-transaction-slot.js","sourceRoot":"","sources":["../../../../src/transaction-coordination/application/ports/foundation-transaction-slot.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-teams/engineering-foundation",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "description": "Versioned engineering policy, tooling, and conformance for Agent Teams repositories.",
   "license": "Apache-2.0",
   "type": "module",