taskflow-mcp-core 0.3.0-beta.1.1 → 1.0.0

package/dist/control/store/coordinator-store.js

@@ -0,0 +1,620 @@
+/** P16 user-private, files-only capacity authority. Project Runs/Receipts stay
+ * in project ledgers. Every operation re-reads one atomically published state
+ * under the shared persistent mutex; no process-local capacity cache exists. */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { randomUUID } from "node:crypto";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { PersistentFileMutex } from "taskflow-core/persistent-mutex";
+import { ControlError } from "../errors.js";
+import { commandRequestHash } from "../schema/commands.js";
+import { UuidSchema, Sha256HexSchema } from "../schema/common.js";
+import { CoordinatorLeaseSchema, CoordinatorCommandRecordSchema, ConcurrencyReservationSchema, assertReservationInvariants } from "../schema/coordinator.js";
+import { writeJsonAtomicHardened } from "./store.js";
+const integer = Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER });
+const text = Type.String({ minLength: 1 });
+const rowSchema = Type.Object({ reservation: ConcurrencyReservationSchema, ownerId: text, principal: text, updatedAt: integer,
+    admitRunVersion: Type.Optional(integer), releaseKind: Type.Optional(Type.Union([Type.Literal("normal"), Type.Literal("force")])),
+    releaseProofId: Type.Optional(text), concurrencyGuarantee: Type.Union([Type.Literal("enforced"), Type.Literal("operator-overridden")]) }, { additionalProperties: false });
+const operatorRequestSchema = Type.Union([
+    Type.Object({ kind: Type.Literal("setMaxActiveRuns"), maxActiveRuns: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }) }, { additionalProperties: false }),
+    Type.Object({ kind: Type.Literal("forceRelease"), reservationId: UuidSchema, riskAcknowledgement: Type.Literal(true), reason: text }, { additionalProperties: false }),
+]);
+const commandSchema = Type.Object({ request: Type.Optional(operatorRequestSchema), record: CoordinatorCommandRecordSchema, result: Type.Union([rowSchema, Type.Integer({ minimum: 1 })]) }, { additionalProperties: false });
+const auditSchema = Type.Object({ commitSeq: integer, epoch: integer, recordedAt: integer, action: text, principal: text,
+    previousHash: Sha256HexSchema, stateDigest: Sha256HexSchema, hash: Sha256HexSchema }, { additionalProperties: false });
+const stateSchema = Type.Object({ version: Type.Literal(1), fencingEpoch: integer, commitSeq: integer, lastWallTime: integer,
+    directoryIdentity: Type.Object({ canonicalPath: text, dev: integer, ino: integer }, { additionalProperties: false }),
+    instanceId: UuidSchema,
+    maxActiveRuns: Type.Integer({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }), reservations: Type.Record(Type.String(), rowSchema),
+    commands: Type.Record(Type.String(), commandSchema), audit: Type.Array(auditSchema), stateHash: Sha256HexSchema }, { additionalProperties: false });
+const ZERO_HASH = "0".repeat(64);
+export const COORDINATOR_CRASH_ENV = "TASKFLOW_COORDINATOR_CRASH_AT";
+const active = (row) => ["reserved", "committed", "orphan-suspect"].includes(row.reservation.state);
+const fail = (code, message) => { throw new ControlError(code, message, { recoveryAction: "operator", sideEffects: "none" }); };
+const validId = (id) => { if (!Value.Check(UuidSchema, id))
+    fail("TF_COMMAND_FAILED", "coordinator identifier must be a UUID"); };
+const positive = (value, name) => { if (!Number.isSafeInteger(value) || value < 1)
+    fail("TF_COMMAND_FAILED", `${name} must be a positive safe integer`); };
+function capacity(state) {
+    const rows = Object.values(state.reservations);
+    const reserved = rows.filter((r) => r.reservation.state === "reserved").length;
+    const committed = rows.filter((r) => r.reservation.state === "committed").length;
+    const orphanSuspect = rows.filter((r) => r.reservation.state === "orphan-suspect").length;
+    return { maxActiveRuns: state.maxActiveRuns, active: reserved + committed + orphanSuspect, reserved, committed, orphanSuspect };
+}
+function businessDigest(state) {
+    return commandRequestHash({ fencingEpoch: state.fencingEpoch, maxActiveRuns: state.maxActiveRuns, reservations: state.reservations, commands: state.commands });
+}
+function hashState(state) { const { stateHash: _, ...body } = state; return commandRequestHash(body); }
+function assertNoSymlink(file) {
+    try {
+        if (fs.lstatSync(file).isSymbolicLink())
+            fail("TF_DURABILITY_FAILED", `coordinator refuses symlink: ${file}`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+}
+function prepareDirectory(directory) {
+    const missing = [];
+    let ancestor = path.resolve(directory);
+    while (!fs.existsSync(ancestor)) {
+        missing.unshift(path.basename(ancestor));
+        ancestor = path.dirname(ancestor);
+    }
+    assertNoSymlink(ancestor);
+    let canonical = fs.realpathSync(ancestor);
+    for (const segment of missing) {
+        canonical = path.join(canonical, segment);
+        try {
+            fs.mkdirSync(canonical, { mode: 0o700 });
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        assertNoSymlink(canonical);
+        if (!fs.lstatSync(canonical).isDirectory())
+            fail("TF_DURABILITY_FAILED", "coordinator path component is not a directory");
+    }
+    const stat = fs.lstatSync(canonical);
+    if (!stat.isDirectory() || (process.getuid && stat.uid !== process.getuid()))
+        fail("TF_DURABILITY_FAILED", "coordinator directory must be owned by the host user");
+    if (process.platform !== "win32")
+        fs.chmodSync(canonical, 0o700);
+    return canonical;
+}
+function validateState(raw) {
+    if (!Value.Check(stateSchema, raw))
+        fail("TF_DURABILITY_FAILED", "coordinator state has an invalid closed shape");
+    const state = raw;
+    if (hashState(state) !== state.stateHash || state.audit.length !== state.commitSeq)
+        fail("TF_DURABILITY_FAILED", "coordinator state/audit integrity mismatch");
+    let previous = ZERO_HASH;
+    let priorTime = 0;
+    for (const [index, entry] of state.audit.entries()) {
+        const { hash, ...body } = entry;
+        if (entry.commitSeq !== index + 1 || entry.previousHash !== previous || entry.recordedAt < priorTime || entry.epoch > state.fencingEpoch || commandRequestHash(body) !== hash)
+            fail("TF_DURABILITY_FAILED", "coordinator audit chain is inconsistent");
+        previous = hash;
+        priorTime = entry.recordedAt;
+    }
+    if (priorTime > state.lastWallTime || (state.audit.length && state.audit.at(-1).stateDigest !== businessDigest(state)))
+        fail("TF_DURABILITY_FAILED", "coordinator projection is not bound to its latest audit");
+    const bindings = new Set();
+    for (const [id, row] of Object.entries(state.reservations)) {
+        validId(id);
+        if (id !== row.reservation.reservationId || row.updatedAt > state.lastWallTime || row.reservation.coordinatorEpoch > state.fencingEpoch)
+            fail("TF_DURABILITY_FAILED", "coordinator reservation identity/time mismatch");
+        for (const number of [row.reservation.coordinatorEpoch, row.reservation.projectAdmitCommitSeq, row.reservation.reservedExpiresAt, row.reservation.renewedAt]) {
+            if (number !== undefined && (!Number.isSafeInteger(number) || number < 0))
+                fail("TF_DURABILITY_FAILED", "coordinator reservation contains an unsafe numeric authority");
+        }
+        try {
+            assertReservationInvariants(row.reservation);
+        }
+        catch {
+            fail("TF_ADMISSION_BINDING_CONFLICT", "committed/orphan reservation must have admission evidence and no TTL");
+        }
+        if (row.reservation.state === "reserved" && (row.reservation.reservedExpiresAt === undefined || row.reservation.projectAdmitCommitSeq !== undefined))
+            fail("TF_ADMISSION_BINDING_CONFLICT", "pre-admit reservation requires TTL and no admitted sequence");
+        if (["committed", "orphan-suspect"].includes(row.reservation.state)) {
+            const binding = bindingKey(row.reservation);
+            if (bindings.has(binding))
+                fail("TF_ADMISSION_BINDING_CONFLICT", "duplicate admitted project/domain/run binding");
+            bindings.add(binding);
+        }
+    }
+    for (const [id, command] of Object.entries(state.commands)) {
+        validId(id);
+        if (command.request && (command.request.kind !== command.record.kind || commandRequestHash(command.request) !== command.record.requestHash))
+            fail("TF_DURABILITY_FAILED", "coordinator audit request does not match its command");
+        if (id !== command.record.commandId || command.record.status !== "completed" || command.record.firstCommitSeq !== command.record.lastCommitSeq || command.record.lastCommitSeq > state.commitSeq)
+            fail("TF_DURABILITY_FAILED", "coordinator command authority mismatch");
+    }
+    if (capacity(state).active > state.maxActiveRuns)
+        fail("TF_CAPACITY_EXCEEDED", "durable coordinator exceeds its capacity ceiling");
+    return state;
+}
+/** Read-only upgrade fence for homes predating coordinator-epoch.json. Never
+ * trust a bare epoch field: verify the complete ledger and its genesis binding. */
+export function readDurableCoordinatorEpoch(directory) {
+    const resolved = path.resolve(directory);
+    let stat;
+    try {
+        stat = fs.lstatSync(resolved);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return 0;
+        throw error;
+    }
+    if (!stat.isDirectory() || stat.isSymbolicLink() || process.getuid && stat.uid !== process.getuid() || (stat.mode & 0o077) !== 0)
+        fail("TF_DURABILITY_FAILED", "legacy coordinator directory owner, mode or type is invalid");
+    function read(name) {
+        const file = path.join(resolved, name);
+        let named;
+        try {
+            named = fs.lstatSync(file);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+        if (!named.isFile() || named.isSymbolicLink() || process.getuid && named.uid !== process.getuid() || (named.mode & 0o077) !== 0)
+            fail("TF_DURABILITY_FAILED", "legacy coordinator file owner, mode or type is invalid");
+        const fd = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        try {
+            const opened = fs.fstatSync(fd);
+            if (opened.dev !== named.dev || opened.ino !== named.ino)
+                fail("TF_DURABILITY_FAILED", "legacy coordinator file identity changed");
+            const value = JSON.parse(fs.readFileSync(fd, "utf8"));
+            const after = fs.lstatSync(file);
+            if (opened.dev !== after.dev || opened.ino !== after.ino)
+                fail("TF_DURABILITY_FAILED", "legacy coordinator file identity changed");
+            return value;
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    }
+    const raw = read("coordinator.json"), identity = read("coordinator.identity.json");
+    if (raw === undefined && identity === undefined)
+        return 0;
+    if (raw === undefined || identity === undefined)
+        fail("TF_DURABILITY_FAILED", "legacy coordinator ledger or genesis identity is missing");
+    const state = validateState(raw);
+    const identitySchema = Type.Object({ version: Type.Literal(1), canonicalPath: text, dev: integer, ino: integer, instanceId: UuidSchema }, { additionalProperties: false });
+    if (!Value.Check(identitySchema, identity) || identity.canonicalPath !== resolved || identity.dev !== stat.dev || identity.ino !== stat.ino
+        || identity.instanceId !== state.instanceId || state.directoryIdentity.canonicalPath !== resolved || state.directoryIdentity.dev !== stat.dev || state.directoryIdentity.ino !== stat.ino
+        || fs.realpathSync(resolved) !== resolved)
+        fail("TF_DURABILITY_FAILED", "legacy coordinator directory/genesis binding is invalid");
+    const after = fs.lstatSync(resolved);
+    if (after.dev !== stat.dev || after.ino !== stat.ino)
+        fail("TF_DURABILITY_FAILED", "legacy coordinator directory identity changed");
+    return state.fencingEpoch;
+}
+function bindingKey(row) { return `${row.projectId}/${row.projectControlDomainId}/${row.runId}`; }
+function matchesProof(row, proof) {
+    return !!proof && proof.reservationId === row.reservation.reservationId && bindingKey(row.reservation) === bindingKey(proof) && proof.projectAdmitCommitSeq === row.reservation.projectAdmitCommitSeq
+        && Number.isSafeInteger(proof.runVersion) && proof.runVersion >= (row.admitRunVersion ?? 0);
+}
+function isAdmissionProof(proof) {
+    return !!proof && !("status" in proof) && Number.isSafeInteger(proof.projectAdmitCommitSeq) && proof.projectAdmitCommitSeq > 0 && Number.isSafeInteger(proof.runVersion) && proof.runVersion >= 0;
+}
+export class UserCoordinatorStore {
+    storePath;
+    #options;
+    #mutex;
+    #directoryIdentity;
+    #closed = false;
+    #clockHighWater = 0;
+    constructor(directory, options) {
+        positive(options.initialMaxActiveRuns, "initialMaxActiveRuns");
+        if (!Number.isSafeInteger(options.epoch) || options.epoch < 1 || !options.holderId?.trim())
+            fail("TF_AUTHORITY_REVOKED", "coordinator requires a verified holder and positive epoch");
+        if (!options.authority || ["readLease", "authorize", "readAdmission", "readRelease"].some((key) => typeof options.authority[key] !== "function"))
+            fail("TF_AUTHORITY_REVOKED", "coordinator requires trusted live authority callbacks");
+        this.#options = { ...options };
+        this.storePath = prepareDirectory(directory);
+        const { dev, ino } = fs.statSync(this.storePath);
+        this.#directoryIdentity = { dev, ino };
+        this.#mutex = new PersistentFileMutex(path.join(this.storePath, "writer.lock"));
+    }
+    close() { this.#closed = true; }
+    async initialize() { await this.#transaction("initialize", undefined, undefined, async () => undefined); }
+    async snapshot(context) {
+        return this.#transaction("snapshot", context, undefined, async (state) => ({ commitSeq: state.commitSeq, fencingEpoch: state.fencingEpoch, capacity: capacity(state),
+            concurrencyGuarantee: Object.values(state.reservations).some((r) => r.concurrencyGuarantee === "operator-overridden") ? "operator-overridden" : "enforced",
+            reservations: Object.values(state.reservations), commands: Object.values(state.commands) }));
+    }
+    async readReservation(id, context) {
+        validId(id);
+        return this.#transaction("readReservation", context, id, async (state, identity) => {
+            const row = state.reservations[id];
+            if (row)
+                this.#owner(row, identity);
+            return row;
+        });
+    }
+    /** Hold the durable capacity fence through asynchronous preparation and the
+     * synchronous provider launch. Preparation must not launch work or re-enter
+     * this coordinator. The returned activation must not await: its project
+     * binding/auth checks and actual runtime activation occur in one JS turn. */
+    async withDispatch(id, context, prepare) {
+        validId(id);
+        let activate;
+        let result;
+        await this.#transaction("dispatch", context, id, async (state, identity) => {
+            const row = this.#row(state, id);
+            this.#owner(row, identity);
+            if (row.reservation.state !== "committed")
+                fail("TF_ADMISSION_BINDING_CONFLICT", "dispatch requires a committed reservation");
+            activate = await prepare(structuredClone(row));
+            if (typeof activate !== "function")
+                fail("TF_COMMAND_FAILED", "dispatch preparation must return a synchronous activation");
+        }, undefined, () => { result = activate(); });
+        return result;
+    }
+    async readCommand(id, context) {
+        validId(id);
+        return this.#transaction("readCommand", context, undefined, async (state, identity) => {
+            const command = state.commands[id];
+            if (command && command.record.callerPrincipal !== identity.principal)
+                fail("TF_CROSS_PRINCIPAL_COMMAND", "coordinator result belongs to another verified principal");
+            return command;
+        });
+    }
+    async reserve(input, context) {
+        input = structuredClone(input);
+        const id = input.reservationId ?? randomUUID();
+        for (const value of [id, input.projectId, input.projectControlDomainId, input.runId])
+            validId(value);
+        this.#ttl(input.ttlMs);
+        return this.#transaction("reserve", context, id, async (state, identity, now) => {
+            const existing = state.reservations[id];
+            if (existing) {
+                this.#owner(existing, identity);
+                if (bindingKey(existing.reservation) !== bindingKey(input) || existing.reservation.state !== "reserved")
+                    fail("TF_ADMISSION_BINDING_CONFLICT", "reservation ID cannot be rebound or reused after admission/expiry/release");
+                return existing;
+            }
+            if (capacity(state).active >= state.maxActiveRuns)
+                fail("TF_CAPACITY_EXCEEDED", "global admitted-run capacity exhausted");
+            return state.reservations[id] = { reservation: { reservationId: id, projectId: input.projectId, projectControlDomainId: input.projectControlDomainId, runId: input.runId,
+                    state: "reserved", slots: 1, coordinatorEpoch: this.#options.epoch, reservedExpiresAt: now + input.ttlMs },
+                ownerId: identity.ownerId, principal: identity.principal, updatedAt: now, concurrencyGuarantee: "enforced" };
+        }, { reservationId: id, projectId: input.projectId, projectControlDomainId: input.projectControlDomainId, runId: input.runId, state: "reserved", slots: 1, coordinatorEpoch: this.#options.epoch });
+    }
+    async commit(id, input, context) {
+        input = structuredClone(input);
+        positive(input.projectAdmitCommitSeq, "projectAdmitCommitSeq");
+        if (input.attemptId)
+            validId(input.attemptId);
+        return this.#transaction("commit", context, id, async (state, identity, now) => {
+            const row = this.#row(state, id);
+            this.#owner(row, identity);
+            if (row.reservation.state === "committed") {
+                if (row.reservation.projectAdmitCommitSeq !== input.projectAdmitCommitSeq || row.reservation.attemptId !== input.attemptId || row.reservation.providerJobHandle !== input.providerJobHandle)
+                    fail("TF_ADMISSION_BINDING_CONFLICT", "admission retry changed durable binding");
+                return row;
+            }
+            if (row.reservation.state !== "reserved")
+                fail("TF_ADMISSION_BINDING_CONFLICT", "only a live pre-admit reservation can commit");
+            if (Object.values(state.reservations).some((other) => other !== row && ["committed", "orphan-suspect"].includes(other.reservation.state) && bindingKey(other.reservation) === bindingKey(row.reservation)))
+                fail("TF_ADMISSION_BINDING_CONFLICT", "project/domain/run already has a committed reservation");
+            const proposed = { ...row.reservation, ...input };
+            const proof = await this.#options.authority.readAdmission(structuredClone(proposed));
+            this.#now(now);
+            if (row.reservation.reservedExpiresAt <= Date.now())
+                fail("TF_ADMISSION_BINDING_CONFLICT", "reservation expired before durable admission commit");
+            if (!isAdmissionProof(proof) || !matchesProof({ ...row, reservation: proposed }, proof))
+                fail("TF_ADMISSION_BINDING_CONFLICT", "project ledger does not prove this admission");
+            row.reservation = { ...proposed, state: "committed", coordinatorEpoch: this.#options.epoch };
+            delete row.reservation.reservedExpiresAt;
+            row.admitRunVersion = proof.runVersion;
+            row.updatedAt = now;
+            return row;
+        });
+    }
+    async renew(id, input, context) {
+        input = structuredClone(input);
+        if (input.ttlMs !== undefined)
+            this.#ttl(input.ttlMs);
+        return this.#transaction("renew", context, id, async (state, identity, now) => {
+            const row = this.#row(state, id);
+            this.#owner(row, identity);
+            if (!active(row))
+                fail("TF_ADMISSION_BINDING_CONFLICT", "inactive reservation cannot renew");
+            if (row.reservation.state === "reserved") {
+                if (input.ttlMs === undefined)
+                    fail("TF_COMMAND_FAILED", "reserved renewal requires a TTL");
+                row.reservation.reservedExpiresAt = now + input.ttlMs;
+            }
+            else if (input.ttlMs !== undefined)
+                fail("TF_ADMISSION_BINDING_CONFLICT", "committed/orphan reservations must never receive a TTL");
+            row.reservation.renewedAt = now;
+            row.reservation.coordinatorEpoch = this.#options.epoch;
+            row.updatedAt = now;
+            return row;
+        });
+    }
+    async markOrphanSuspect(id, context) {
+        return this.#transaction("markOrphanSuspect", context, id, async (state, identity, now) => {
+            const row = this.#row(state, id);
+            this.#owner(row, identity);
+            if (!["committed", "orphan-suspect"].includes(row.reservation.state))
+                fail("TF_ADMISSION_BINDING_CONFLICT", "only admitted reservations can become orphan-suspect");
+            if (row.reservation.state === "committed") {
+                row.reservation.state = "orphan-suspect";
+                row.updatedAt = now;
+                row.reservation.coordinatorEpoch = this.#options.epoch;
+            }
+            return row;
+        });
+    }
+    async normalRelease(id, context) {
+        return this.#transaction("normalRelease", context, id, async (state, identity, now) => {
+            const row = this.#row(state, id);
+            this.#owner(row, identity);
+            if (row.reservation.state === "released" && row.releaseKind === "normal")
+                return row;
+            if (!["committed", "orphan-suspect"].includes(row.reservation.state))
+                fail("TF_ADMISSION_BINDING_CONFLICT", "normalRelease requires an admitted reservation");
+            const proof = await this.#options.authority.readRelease(structuredClone(row.reservation));
+            this.#now(now);
+            const terminal = ["completed", "failed", "blocked", "cancelled"].includes(proof?.status);
+            const parked = proof?.status === "paused" && proof.stage === "parked" && proof.requiresReadmission === true;
+            if (!matchesProof(row, proof) || !proof.proofId?.trim() || proof.providerNoLiveProcessTree !== true || proof.noAmbiguousJobs !== true || proof.reconcileTimeoutOnly !== false || (!terminal && !parked))
+                fail("TF_RECONCILE_REQUIRED", "D37 requires current ledger-bound terminal/parked and provider quiescence evidence");
+            row.reservation.state = "released";
+            row.reservation.coordinatorEpoch = this.#options.epoch;
+            delete row.reservation.reservedExpiresAt;
+            row.releaseKind = "normal";
+            row.releaseProofId = proof.proofId;
+            row.updatedAt = now;
+            return row;
+        });
+    }
+    async forceRelease(id, input, context) {
+        input = structuredClone(input);
+        validId(input.commandId);
+        if (input.riskAcknowledgement !== true || typeof input.reason !== "string" || !input.reason.trim())
+            fail("TF_POLICY_DENIED", "forceRelease requires explicit risk acknowledgement and reason");
+        return this.#transaction("forceRelease", context, id, async (state, identity, now) => {
+            this.#operator(identity);
+            return this.#command(state, identity, input.commandId, { kind: "forceRelease", reservationId: id, riskAcknowledgement: true, reason: input.reason }, () => {
+                const row = this.#row(state, id);
+                if (row.reservation.state === "expired")
+                    fail("TF_ADMISSION_BINDING_CONFLICT", "expired reservation cannot be force released");
+                row.reservation.state = "released";
+                row.reservation.coordinatorEpoch = this.#options.epoch;
+                delete row.reservation.reservedExpiresAt;
+                row.releaseKind = "force";
+                row.concurrencyGuarantee = "operator-overridden";
+                row.updatedAt = now;
+                return row;
+            });
+        });
+    }
+    async setMaxActiveRuns(input, context) {
+        input = structuredClone(input);
+        validId(input.commandId);
+        positive(input.maxActiveRuns, "maxActiveRuns");
+        return this.#transaction("setMaxActiveRuns", context, undefined, async (state, identity) => {
+            this.#operator(identity);
+            return this.#command(state, identity, input.commandId, { kind: "setMaxActiveRuns", maxActiveRuns: input.maxActiveRuns }, () => {
+                if (input.maxActiveRuns < capacity(state).active)
+                    fail("TF_CAPACITY_EXCEEDED", "cannot lower capacity below reserved/committed/orphan usage");
+                return state.maxActiveRuns = input.maxActiveRuns;
+            });
+        });
+    }
+    #command(state, identity, id, body, execute) {
+        const hash = commandRequestHash(body);
+        const prior = state.commands[id];
+        if (prior) {
+            if (prior.record.callerPrincipal !== identity.principal)
+                fail("TF_CROSS_PRINCIPAL_COMMAND", "coordinator result belongs to another verified principal");
+            if (prior.record.requestHash !== hash)
+                fail("TF_IDEMPOTENCY_CONFLICT", "coordinator command ID was reused with a different request");
+            return prior.result;
+        }
+        const result = execute();
+        state.commands[id] = { request: structuredClone(body), record: { commandId: id, kind: body.kind, requestHash: hash, callerPrincipal: identity.principal, firstCommitSeq: state.commitSeq + 1, lastCommitSeq: state.commitSeq + 1, status: "completed" }, result: structuredClone(result) };
+        return result;
+    }
+    #ttl(ttlMs) { positive(ttlMs, "ttlMs"); if (ttlMs > 86_400_000)
+        fail("TF_COMMAND_FAILED", "reservation TTL must not exceed one day"); }
+    #row(state, id) { validId(id); const row = state.reservations[id]; if (!row)
+        fail("TF_ADMISSION_BINDING_CONFLICT", "reservation not found"); return row; }
+    #owner(row, identity) { if (row.ownerId !== identity.ownerId || row.principal !== identity.principal)
+        fail("TF_AUTHORITY_REVOKED", "reservation owner/project authority does not match"); }
+    #operator(identity) { if (identity.operator !== true)
+        fail("TF_POLICY_DENIED", "an authorized coordinator operator is required"); }
+    #binding() {
+        assertNoSymlink(this.storePath);
+        const st = fs.statSync(this.storePath);
+        if (st.dev !== this.#directoryIdentity.dev || st.ino !== this.#directoryIdentity.ino)
+            fail("TF_DURABILITY_FAILED", "coordinator directory identity changed");
+        assertNoSymlink(path.join(this.storePath, "writer.lock.queue"));
+        assertNoSymlink(path.join(this.storePath, "coordinator.json"));
+        assertNoSymlink(path.join(this.storePath, "coordinator.identity.json"));
+    }
+    #now(floor = 0) {
+        const now = Date.now();
+        if (!Number.isSafeInteger(now) || now < Math.max(floor, this.#clockHighWater))
+            fail("TF_AUTHORITY_REVOKED", "wall clock moved backwards; no TTL reclaim or mutation is safe");
+        this.#clockHighWater = now;
+        return now;
+    }
+    async #fence(now) {
+        const lease = await this.#options.authority.readLease();
+        const observedNow = this.#now(now);
+        if (!Value.Check(CoordinatorLeaseSchema, lease) || !Number.isSafeInteger(lease.expiresAt) || !Number.isSafeInteger(lease.fencingEpoch) || lease.fencingEpoch !== this.#options.epoch || lease.holderId !== this.#options.holderId || lease.expiresAt <= observedNow)
+            fail("TF_AUTHORITY_REVOKED", "coordinator holder/epoch/lease is no longer authoritative");
+        return lease.expiresAt;
+    }
+    async #expireReservations(state, now) {
+        for (const row of Object.values(state.reservations)) {
+            if (row.reservation.state !== "reserved" || row.reservation.reservedExpiresAt > now)
+                continue;
+            let proof;
+            try {
+                proof = await this.#options.authority.readAdmission(structuredClone(row.reservation));
+                // An ordinary observer cannot close the late-admit race. Only the
+                // explicit durable ADMIT/ABANDON arbitration may free a slot.
+                if (!isAdmissionProof(proof) && this.#options.authority.abandonAdmissionIfAbsent) {
+                    await this.#fence(this.#now(now));
+                    proof = await this.#options.authority.abandonAdmissionIfAbsent(structuredClone(row.reservation));
+                }
+            }
+            catch {
+                this.#now(now);
+                continue;
+            } // An unavailable project ledger retains its slot.
+            const observedNow = this.#now(now);
+            await this.#fence(observedNow);
+            if (!proof || proof.reservationId !== row.reservation.reservationId || bindingKey(proof) !== bindingKey(row.reservation))
+                continue;
+            if (isAdmissionProof(proof)) {
+                // Run Admitted may have reached its project ledger before the host
+                // crashed between that fsync and coordinator commit. Never TTL-free it.
+                row.reservation.state = "committed";
+                row.reservation.projectAdmitCommitSeq = proof.projectAdmitCommitSeq;
+                row.reservation.coordinatorEpoch = this.#options.epoch;
+                row.admitRunVersion = proof.runVersion;
+                delete row.reservation.reservedExpiresAt;
+                row.updatedAt = observedNow;
+            }
+            else if ("status" in proof && proof.status === "abandoned"
+                && Number.isSafeInteger(proof.abandonmentCommitSeq) && proof.abandonmentCommitSeq > 0
+                && Number.isSafeInteger(proof.runVersion) && proof.runVersion >= 0) {
+                row.reservation.state = "expired";
+                delete row.reservation.reservedExpiresAt;
+                row.updatedAt = observedNow;
+            }
+        }
+    }
+    async #transaction(action, context, id, apply, authorizationReservation, afterCommit) {
+        if (this.#closed)
+            fail("TF_DURABILITY_FAILED", "coordinator store is closed");
+        this.#binding();
+        const release = await this.#mutex.acquire({ timeoutMs: 30_000, signal: AbortSignal.timeout(30_000) }).catch((error) => {
+            if (error instanceof ControlError)
+                throw error;
+            throw new ControlError("TF_DURABILITY_FAILED", `coordinator writer fence failed: ${error instanceof Error ? error.message : String(error)}`, { recoveryAction: "operator", sideEffects: "none" });
+        });
+        try {
+            if (this.#closed)
+                fail("TF_DURABILITY_FAILED", "coordinator store closed during lock admission");
+            this.#binding();
+            const file = path.join(this.storePath, "coordinator.json"), identityFile = path.join(this.storePath, "coordinator.identity.json");
+            let storeIdentity;
+            if (fs.existsSync(identityFile)) {
+                storeIdentity = JSON.parse(fs.readFileSync(identityFile, "utf8"));
+                if (!Value.Check(Type.Object({ version: Type.Literal(1), canonicalPath: text, dev: integer, ino: integer, instanceId: UuidSchema }, { additionalProperties: false }), storeIdentity) || storeIdentity.canonicalPath !== this.storePath || storeIdentity.dev !== this.#directoryIdentity.dev || storeIdentity.ino !== this.#directoryIdentity.ino)
+                    fail("TF_DURABILITY_FAILED", "coordinator genesis directory identity is invalid or changed");
+                if (!fs.existsSync(file))
+                    fail("TF_DURABILITY_FAILED", "coordinator authoritative ledger is missing; bootstrap would erase admitted capacity");
+            }
+            else {
+                if (fs.existsSync(file) || action !== "initialize")
+                    fail("TF_DURABILITY_FAILED", "coordinator genesis authority is missing");
+                storeIdentity = { version: 1, canonicalPath: this.storePath, ...this.#directoryIdentity, instanceId: randomUUID() };
+                await this.#fence(this.#now());
+                this.#binding();
+                writeJsonAtomicHardened(identityFile, storeIdentity);
+            }
+            let state;
+            if (fs.existsSync(file)) {
+                state = validateState(JSON.parse(fs.readFileSync(file, "utf8")));
+            }
+            else {
+                state = { version: 1, fencingEpoch: this.#options.epoch, commitSeq: 0, lastWallTime: 0, maxActiveRuns: this.#options.initialMaxActiveRuns,
+                    directoryIdentity: { canonicalPath: this.storePath, ...this.#directoryIdentity }, instanceId: storeIdentity.instanceId, reservations: {}, commands: {}, audit: [], stateHash: "" };
+            }
+            if (state.instanceId !== storeIdentity.instanceId || state.directoryIdentity.canonicalPath !== this.storePath || state.directoryIdentity.dev !== this.#directoryIdentity.dev || state.directoryIdentity.ino !== this.#directoryIdentity.ino)
+                fail("TF_DURABILITY_FAILED", "coordinator directory identity changed; explicit authority rebind is required");
+            const before = commandRequestHash(state);
+            const now = this.#now(state.lastWallTime);
+            await this.#fence(now);
+            if (state.fencingEpoch > this.#options.epoch)
+                fail("TF_AUTHORITY_REVOKED", "persisted coordinator epoch fences this host");
+            state.fencingEpoch = this.#options.epoch;
+            let identity;
+            if (action !== "initialize") {
+                identity = structuredClone(await this.#options.authority.authorize(context, action, structuredClone(id && state.reservations[id] ? state.reservations[id].reservation : authorizationReservation)));
+                this.#now(now);
+                if (!identity?.principal?.trim() || !identity.ownerId?.trim() || typeof identity.operator !== "boolean")
+                    fail("TF_AUTHORITY_REVOKED", "trusted authority did not verify a principal and owner");
+            }
+            await this.#expireReservations(state, this.#now(now));
+            const value = await apply(state, identity, now);
+            this.#now(now);
+            if (action !== "initialize") {
+                const currentIdentity = await this.#options.authority.authorize(context, action, structuredClone(id && state.reservations[id] ? state.reservations[id].reservation : authorizationReservation));
+                this.#now(now);
+                if (!currentIdentity || currentIdentity.principal !== identity.principal || currentIdentity.ownerId !== identity.ownerId || currentIdentity.operator !== identity.operator)
+                    fail("TF_AUTHORITY_REVOKED", "live authority changed during coordinator transaction");
+            }
+            if (this.#closed)
+                fail("TF_DURABILITY_FAILED", "coordinator store closed during transaction");
+            this.#binding();
+            const leaseExpiresAt = await this.#fence(this.#now(now));
+            const currentTime = this.#now(now);
+            if (commandRequestHash(state) !== before || !fs.existsSync(file)) {
+                state.lastWallTime = currentTime;
+                state.commitSeq++;
+                const body = { commitSeq: state.commitSeq, epoch: state.fencingEpoch, recordedAt: currentTime, action, principal: identity?.principal ?? "coordinator-bootstrap", previousHash: state.audit.at(-1)?.hash ?? ZERO_HASH, stateDigest: businessDigest(state) };
+                state.audit.push({ ...body, hash: commandRequestHash(body) });
+                state.stateHash = hashState(state);
+                validateState(state);
+                if (this.#now(currentTime) >= leaseExpiresAt)
+                    fail("TF_AUTHORITY_REVOKED", "coordinator lease expired before atomic publication");
+                if (process.env[COORDINATOR_CRASH_ENV] === "before-state-write")
+                    process.kill(process.pid, "SIGKILL");
+                writeJsonAtomicHardened(file, state);
+                if (process.env[COORDINATOR_CRASH_ENV] === "after-state-write")
+                    process.kill(process.pid, "SIGKILL");
+            }
+            if (action === "snapshot")
+                Object.assign(value, { commitSeq: state.commitSeq, fencingEpoch: state.fencingEpoch });
+            // No await may be inserted between the last live fence/publication and
+            // provider activation. The mutex is released only in finally below.
+            if (afterCommit) {
+                if (this.#closed)
+                    fail("TF_DURABILITY_FAILED", "coordinator store closed before dispatch activation");
+                this.#binding();
+                if (this.#now(currentTime) >= leaseExpiresAt)
+                    fail("TF_AUTHORITY_REVOKED", "coordinator lease expired before dispatch activation");
+                afterCommit();
+            }
+            return structuredClone(value);
+        }
+        catch (error) {
+            if (error instanceof ControlError)
+                throw error;
+            throw new ControlError("TF_DURABILITY_FAILED", `coordinator transaction failed: ${error instanceof Error ? error.message : String(error)}`, { recoveryAction: "operator", sideEffects: "unknown" });
+        }
+        finally {
+            release();
+        }
+    }
+}
+export async function openCoordinatorStore(directory, options) {
+    const store = new UserCoordinatorStore(directory, options);
+    try {
+        await store.initialize();
+        return store;
+    }
+    catch (error) {
+        store.close();
+        throw error;
+    }
+}
+//# sourceMappingURL=coordinator-store.js.map