open-multi-agent-kit 1.0.0 → 1.2.2

package/dist/core/verified-run/authority-store.d.ts

@@ -0,0 +1,204 @@
+import { type ResourceClaimInput } from "../../coordination/resource.ts";
+import { type GrantToken, type Sequence } from "../../coordination/types.ts";
+import { type AuthorityGrantRecord, type AuthorityProjection } from "./authority-events.ts";
+import { type AuthorityRecord, type ParsedAuthority } from "./authority-journal.ts";
+export type { AuthorityRecord } from "./authority-journal.ts";
+import type { NamespaceIdentity } from "./namespace-identity.ts";
+/**
+ * Durable authority store (WP03): the single-writer boundary for supervisor
+ * authorization state.
+ *
+ * Storage is a head-sidecar pair — `authority.events.jsonl` plus
+ * `authority.events.jsonl.head` — mirroring `ReplayLedgerStore`: the committed
+ * head is the transaction boundary, bytes after `head.size` are uncommitted
+ * and get quarantined then truncated on the next open, and every append is an
+ * expected-head CAS inside the `"mutation"` lock critical section. Cross-process
+ * exclusion is the `"authority"` scope durable-file lease held for the store's
+ * lifetime; its owner record (pid+host+token) is the writer identity, and dead
+ * owners are reclaimed by the existing reclaim protocol.
+ *
+ * Authority epoch durability: `open` appends `authority-epoch-advanced` inside
+ * the lease critical section — never the in-memory default "1" — and leaves the
+ * epoch unreconciled. Only `reconcile()` (termination-witness probes per
+ * quarantined effect, then `authority-reconciled`) reopens admission. A crash
+ * between the epoch event and reconciliation leaves `pendingReconcile` set;
+ * the next open adopts that epoch instead of advancing again.
+ */
+export { AuthorityLeaseHeldError, AuthorityStoreError } from "./authority-errors.ts";
+export declare const authorityStorePath: (root: string) => string;
+export interface AuthorityHead {
+    readonly fileIdentity: {
+        readonly dev: string;
+        readonly ino: string;
+    } | null;
+    readonly size: number;
+    readonly lastSeq: number;
+    readonly lastHash: string;
+}
+export interface AuthorityStoreHooks {
+    /** Fires after the events file is fsynced but before the head publishes — the commit crash window. */
+    readonly afterLedgerFsync?: () => void;
+    /** Fires before a quarantine artifact is fsynced. */
+    readonly beforeQuarantineFsync?: () => void;
+    /** Fires after GC's atomic rewrite lands but before the new head publishes — the GC crash window. */
+    readonly afterAtomicRewrite?: () => void;
+    /** Test seam replacing the durable record append. */
+    readonly persistRecord?: (path: string, bytes: Uint8Array) => void;
+}
+export type AuthorityProbe = (grant: AuthorityGrantRecord) => "terminated" | "alive" | "unknown";
+export interface OpenAuthorityStoreOptions {
+    /** Total admissible weight of concurrently active grants (broker parity). */
+    readonly capacity: number;
+    readonly hooks?: AuthorityStoreHooks;
+    readonly probe?: AuthorityProbe;
+    /** Trusted host clock; never supplied by a serialized command. */
+    readonly clock?: () => number;
+    /** Disable only the parsing cache; disk integrity and durability checks always run. */
+    readonly incrementalReplay?: boolean;
+}
+export interface AuthorityAcquireInput {
+    readonly sessionId: string;
+    readonly incarnation: Sequence | string;
+    /** Idempotency key; unique across grants and tombstones (I08/I31). */
+    readonly commandId: string;
+    readonly intentDigest: string;
+    readonly claims: readonly ResourceClaimInput[];
+    readonly now: number;
+    readonly ttl: number;
+    readonly weight?: number;
+}
+export type AuthorityAcquireResult = {
+    readonly status: "granted";
+    readonly token: GrantToken;
+    readonly duplicate: boolean;
+} | {
+    readonly status: "blocked";
+} | {
+    readonly status: "result";
+    readonly resultDigest: string;
+    readonly token: GrantToken;
+} | {
+    readonly status: "result-expired";
+};
+export type AuthorityLookup = {
+    readonly status: "pending";
+    readonly token: GrantToken;
+} | {
+    readonly status: "result";
+    readonly resultDigest: string;
+    readonly token: GrantToken;
+} | {
+    readonly status: "result-expired";
+    readonly token: GrantToken;
+} | {
+    readonly status: "unknown";
+};
+/** Committed projection plus the hashed records it was replayed from. */
+export interface AuthorityJournalInspection {
+    readonly state: AuthorityProjection;
+    readonly records: readonly AuthorityRecord[];
+    readonly head: AuthorityHead;
+}
+/** The durable single-writer authority boundary. */
+export declare class AuthorityStore {
+    private readonly context;
+    private readonly capacity;
+    private readonly probe;
+    private readonly lease;
+    private accepted;
+    private released;
+    private readonly now;
+    private readonly incrementalReplay;
+    private constructor();
+    /**
+     * Take the `"authority"` scope lease and advance the persisted epoch.
+     * When the previous epoch never reconciled, this restart adopts it — the
+     * pending reconciliation must finish before new admission, and the epoch
+     * is not bumped again (review §5 fault row).
+     */
+    static open(path: string, options: OpenAuthorityStoreOptions): AuthorityStore;
+    /** Read-only committed projection; performs no repair and writes nothing. */
+    static inspect(path: string): AuthorityProjection;
+    /**
+     * Read-only committed journal: projection plus the hashed records it was
+     * replayed from, so callers can see transition causes (cancel-requested vs
+     * authorization-expired vs epoch restart) and termination witnesses — the
+     * projection alone intentionally does not restate them.
+     */
+    static inspectJournal(path: string): AuthorityJournalInspection;
+    get path(): string;
+    get head(): AuthorityHead;
+    get state(): AuthorityProjection;
+    get lastReplay(): ParsedAuthority["replay"];
+    get pendingReconcile(): boolean;
+    private writerId;
+    /**
+     * Commit events as one transaction: mutation lock → committed-head CAS →
+     * reducer pre-validation → append+fsync → head publish → re-read
+     * verification. The head CAS is the fencing boundary — a store whose lease
+     * was reclaimed and taken by another writer sees a changed head and fails
+     * closed instead of authorizing. Persist failures never mint in-memory
+     * state (docs/04: no memory-only authorization after storage failure).
+     */
+    private commit;
+    private commitEpochAdvance;
+    /** Announce a session incarnation (S2); the counter survives restarts durably. */
+    register(sessionId: string): Sequence;
+    /**
+     * Admit an authorization: claim-overlap check, capacity check, idempotency
+     * replay, and the `grant-reserved` record in one lease/mutation-locked
+     * critical section — the check and the record are one transaction (docs/04).
+     * The lease is held for the store's lifetime, so committed state cannot
+     * move between the check and the append; the head CAS in commit() is the
+     * backstop if it ever could.
+     */
+    acquire(input: AuthorityAcquireInput): AuthorityAcquireResult;
+    private resolveToken;
+    /**
+     * Persisted dispatch intent. A committed intent whose spawn was never
+     * witnessed cannot be assumed un-run; on restart it quarantines like any
+     * other possibly-live effect (I01/I02).
+     */
+    dispatchIntent(token: GrantToken, dispatchId: string, now?: number): boolean;
+    /** Bind an effect to its reservation; actual claims must equal the reserved set exactly. */
+    effectStarted(token: GrantToken, actualClaims: readonly ResourceClaimInput[], identity?: NamespaceIdentity, now?: number): boolean;
+    /** Revalidate a running effect before its next irreversible boundary, without starting it again. */
+    effectAuthorized(token: GrantToken, actualClaims: readonly ResourceClaimInput[]): boolean;
+    /** Requested cancellation is not observed termination; live effects quarantine. */
+    cancel(token: GrantToken): boolean;
+    /** Settle lapsed authorizations; never evicts a live effect. */
+    expire(now: number): void;
+    /**
+     * Trusted supervisor witness: this exact effect is gone. Accepted across
+     * superseded epochs so a restarted authority can settle what the previous
+     * one started, never to authorize new work.
+     */
+    confirmTerminated(token: GrantToken): boolean;
+    /** Retain the final result as an idempotency tombstone (S3, docs/04). */
+    retainResult(commandId: string, resultDigest: string, now: number, retentionMs: number): void;
+    /** Command disposition without re-execution (I08/I31). */
+    lookup(commandId: string, now: number): AuthorityLookup;
+    /**
+     * Finish the restart reconciliation: every quarantined effect is compared
+     * against the real execution boundary — only an observed termination
+     * settles it ("gone"); "alive"/"unknown" stay quarantined and keep their
+     * claims (docs/04, review §6). Ends with `authority-reconciled` for the
+     * current epoch; the reconciled scope only then admits new work.
+     */
+    reconcile(probe?: AuthorityProbe): void;
+    /**
+     * GC (review §7): fold droppable state into an `authority-snapshot` and
+     * atomically rewrite the log to that snapshot. Retained: the epoch pair,
+     * incarnation counters, the grant counter (I31 — sequences never reissue),
+     * every unsettled grant, every settled grant still referenced by an
+     * unexpired tombstone, and the unexpired tombstones themselves. A crash
+     * between the atomic rewrite and head publish self-heals on next open via
+     * the snapshot continuation check.
+     */
+    compact(now: number): {
+        readonly dropped: number;
+    };
+    /** Release the authority lease; further commits fail closed. */
+    release(): void;
+}
+//# sourceMappingURL=authority-store.d.ts.map

package/dist/core/verified-run/authority-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authority-store.d.ts","sourceRoot":"","sources":["../../../src/core/verified-run/authority-store.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\nimport {\n\tcloseSync,\n\texistsSync,\n\tconstants as fsConstants,\n\tfstatSync,\n\tfsyncSync,\n\tftruncateSync,\n\tmkdirSync,\n\topenSync,\n\treadFileSync,\n\trenameSync,\n\tunlinkSync,\n\twriteSync,\n} from \"node:fs\";\nimport { dirname, join } from \"node:path\";\nimport {\n\tcanonicalClaim,\n\tclaimSetsConflict,\n\ttype ResourceClaimInput,\n\tsameClaimSet,\n} from \"../../coordination/resource.ts\";\nimport { type GrantToken, SETTLED_EFFECT_STATES, type Sequence, sequence } from \"../../coordination/types.ts\";\nimport { atomicRewriteFileSync } from \"../atomic-session-file.ts\";\nimport {\n\tacquireDurableFileLockSync,\n\tacquireDurableFileMutationLockSync,\n\ttype DurableFileLock,\n\tDurableFileLockBusyError,\n\tinspectDurableFileLockSync,\n} from \"../durable-file-identity.ts\";\nimport { fsyncDirectorySync, writeExclusiveFileDurablySync } from \"../durable-file-io.ts\";\nimport { canonicalJson } from \"../run-journal.ts\";\nimport { createAuthorityClock } from \"./authority-clock.ts\";\nimport { AuthorityLeaseHeldError, AuthorityStoreError } from \"./authority-errors.ts\";\nimport {\n\ttype AuthorityEvent,\n\ttype AuthorityGrantRecord,\n\ttype AuthorityProjection,\n\tapplyAuthorityEvents,\n\tauthorityPendingReconcile,\n\tparseAuthorityEvent,\n\tsnapshotFromProjection,\n} from \"./authority-events.ts\";\nimport {\n\ttype AuthorityRecord,\n\tGENESIS_PREVIOUS,\n\tmaterializeRecord,\n\ttype ParsedAuthority,\n\tparseCommitted,\n\trecordLine,\n} from \"./authority-journal.ts\";\nimport { assertSameCommandMeaning, authorizationStillOpen, expiryEvents, sameGrantToken } from \"./authority-meaning.ts\";\n\nexport type { AuthorityRecord } from \"./authority-journal.ts\";\n\nimport type { NamespaceIdentity } from \"./namespace-identity.ts\";\nimport { readRunClock } from \"./recovery-clock.ts\";\nimport { VerifiedRunError } from \"./storage.ts\";\nimport { probeOwnedNamespace } from \"./supervisor-adapter.ts\";\n\n/**\n * Durable authority store (WP03): the single-writer boundary for supervisor\n * authorization state.\n *\n * Storage is a head-sidecar pair — `authority.events.jsonl` plus\n * `authority.events.jsonl.head` — mirroring `ReplayLedgerStore`: the committed\n * head is the transaction boundary, bytes after `head.size` are uncommitted\n * and get quarantined then truncated on the next open, and every append is an\n * expected-head CAS inside the `\"mutation\"` lock critical section. Cross-process\n * exclusion is the `\"authority\"` scope durable-file lease held for the store's\n * lifetime; its owner record (pid+host+token) is the writer identity, and dead\n * owners are reclaimed by the existing reclaim protocol.\n *\n * Authority epoch durability: `open` appends `authority-epoch-advanced` inside\n * the lease critical section — never the in-memory default \"1\" — and leaves the\n * epoch unreconciled. Only `reconcile()` (termination-witness probes per\n * quarantined effect, then `authority-reconciled`) reopens admission. A crash\n * between the epoch event and reconciliation leaves `pendingReconcile` set;\n * the next open adopts that epoch instead of advancing again.\n */\n\nexport { AuthorityLeaseHeldError, AuthorityStoreError } from \"./authority-errors.ts\";\n\nconst AUTHORITY_SCOPE = \"authority\";\n\nexport const authorityStorePath = (root: string): string => join(root, \"authority.events.jsonl\");\n\nexport interface AuthorityHead {\n\treadonly fileIdentity: { readonly dev: string; readonly ino: string } | null;\n\treadonly size: number;\n\treadonly lastSeq: number;\n\treadonly lastHash: string;\n}\n\nconst EMPTY_AUTHORITY_HEAD: AuthorityHead = Object.freeze({\n\tfileIdentity: null,\n\tsize: 0,\n\tlastSeq: 0,\n\tlastHash: GENESIS_PREVIOUS,\n});\n\ninterface CommittedView {\n\treadonly head: AuthorityHead;\n\treadonly parsed: ParsedAuthority;\n}\n\nfunction authorityHeadsEqual(left: AuthorityHead, right: AuthorityHead): boolean {\n\treturn (\n\t\tleft.size === right.size &&\n\t\tleft.lastSeq === right.lastSeq &&\n\t\tleft.lastHash === right.lastHash &&\n\t\t(left.fileIdentity === null\n\t\t\t? right.fileIdentity === null\n\t\t\t: right.fileIdentity !== null &&\n\t\t\t\tleft.fileIdentity.dev === right.fileIdentity.dev &&\n\t\t\t\tleft.fileIdentity.ino === right.fileIdentity.ino)\n\t);\n}\n\nfunction parseHead(raw: unknown): AuthorityHead {\n\tif (typeof raw !== \"object\" || raw === null || Array.isArray(raw)) throw new AuthorityStoreError(\"corrupt\");\n\tconst value = raw as Record<string, unknown>;\n\tif (Object.keys(value).sort().join(\",\") !== \"fileIdentity,lastHash,lastSeq,size\")\n\t\tthrow new AuthorityStoreError(\"corrupt\");\n\tlet fileIdentity: AuthorityHead[\"fileIdentity\"] = null;\n\tif (value.fileIdentity !== null) {\n\t\tif (typeof value.fileIdentity !== \"object\" || Array.isArray(value.fileIdentity))\n\t\t\tthrow new AuthorityStoreError(\"corrupt\");\n\t\tconst identity = value.fileIdentity as Record<string, unknown>;\n\t\tif (\n\t\t\tObject.keys(identity).sort().join(\",\") !== \"dev,ino\" ||\n\t\t\ttypeof identity.dev !== \"string\" ||\n\t\t\t!/^\\d+$/.test(identity.dev) ||\n\t\t\ttypeof identity.ino !== \"string\" ||\n\t\t\t!/^\\d+$/.test(identity.ino)\n\t\t)\n\t\t\tthrow new AuthorityStoreError(\"corrupt\");\n\t\tfileIdentity = Object.freeze({ dev: identity.dev, ino: identity.ino });\n\t}\n\tif (\n\t\t!Number.isSafeInteger(value.size) ||\n\t\t(value.size as number) < 0 ||\n\t\t!Number.isSafeInteger(value.lastSeq) ||\n\t\t(value.lastSeq as number) < 0 ||\n\t\ttypeof value.lastHash !== \"string\" ||\n\t\t(value.lastSeq === 0 ? value.lastHash !== GENESIS_PREVIOUS : !/^[0-9a-f]{64}$/.test(value.lastHash))\n\t)\n\t\tthrow new AuthorityStoreError(\"corrupt\");\n\treturn Object.freeze({\n\t\tfileIdentity,\n\t\tsize: value.size as number,\n\t\tlastSeq: value.lastSeq as number,\n\t\tlastHash: value.lastHash,\n\t});\n}\n\nfunction fileIdentityOf(stat: {\n\tdev: number | bigint;\n\tino: number | bigint;\n}): NonNullable<AuthorityHead[\"fileIdentity\"]> {\n\treturn Object.freeze({ dev: String(stat.dev), ino: String(stat.ino) });\n}\n\nfunction sameFileIdentity(left: AuthorityHead[\"fileIdentity\"], right: AuthorityHead[\"fileIdentity\"]): boolean {\n\treturn left === null ? right === null : right !== null && left.dev === right.dev && left.ino === right.ino;\n}\n\nfunction writeAll(fd: number, bytes: Uint8Array): void {\n\tlet offset = 0;\n\twhile (offset < bytes.byteLength) offset += writeSync(fd, bytes, offset, bytes.byteLength - offset);\n}\n\nfunction appendDurably(path: string, bytes: Uint8Array): void {\n\tconst fd = openSync(path, fsConstants.O_CREAT | fsConstants.O_APPEND | fsConstants.O_WRONLY, 0o600);\n\ttry {\n\t\twriteAll(fd, bytes);\n\t\tfsyncSync(fd);\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n}\n\nexport interface AuthorityStoreHooks {\n\t/** Fires after the events file is fsynced but before the head publishes — the commit crash window. */\n\treadonly afterLedgerFsync?: () => void;\n\t/** Fires before a quarantine artifact is fsynced. */\n\treadonly beforeQuarantineFsync?: () => void;\n\t/** Fires after GC's atomic rewrite lands but before the new head publishes — the GC crash window. */\n\treadonly afterAtomicRewrite?: () => void;\n\t/** Test seam replacing the durable record append. */\n\treadonly persistRecord?: (path: string, bytes: Uint8Array) => void;\n}\n\nexport type AuthorityProbe = (grant: AuthorityGrantRecord) => \"terminated\" | \"alive\" | \"unknown\";\n\nexport interface OpenAuthorityStoreOptions {\n\t/** Total admissible weight of concurrently active grants (broker parity). */\n\treadonly capacity: number;\n\treadonly hooks?: AuthorityStoreHooks;\n\treadonly probe?: AuthorityProbe;\n\t/** Trusted host clock; never supplied by a serialized command. */\n\treadonly clock?: () => number;\n\t/** Disable only the parsing cache; disk integrity and durability checks always run. */\n\treadonly incrementalReplay?: boolean;\n}\n\nexport interface AuthorityAcquireInput {\n\treadonly sessionId: string;\n\treadonly incarnation: Sequence | string;\n\t/** Idempotency key; unique across grants and tombstones (I08/I31). */\n\treadonly commandId: string;\n\treadonly intentDigest: string;\n\treadonly claims: readonly ResourceClaimInput[];\n\treadonly now: number;\n\treadonly ttl: number;\n\treadonly weight?: number;\n}\n\nexport type AuthorityAcquireResult =\n\t| { readonly status: \"granted\"; readonly token: GrantToken; readonly duplicate: boolean }\n\t| { readonly status: \"blocked\" }\n\t| { readonly status: \"result\"; readonly resultDigest: string; readonly token: GrantToken }\n\t| { readonly status: \"result-expired\" };\n\nexport type AuthorityLookup =\n\t| { readonly status: \"pending\"; readonly token: GrantToken }\n\t| { readonly status: \"result\"; readonly resultDigest: string; readonly token: GrantToken }\n\t| { readonly status: \"result-expired\"; readonly token: GrantToken }\n\t| { readonly status: \"unknown\" };\n\n/** Committed projection plus the hashed records it was replayed from. */\nexport interface AuthorityJournalInspection {\n\treadonly state: AuthorityProjection;\n\treadonly records: readonly AuthorityRecord[];\n\treadonly head: AuthorityHead;\n}\n\ninterface StoreContext {\n\treadonly path: string;\n\treadonly headPath: string;\n\treadonly hooks: AuthorityStoreHooks;\n}\n\nfunction publishHead(context: StoreContext, head: AuthorityHead): void {\n\tconst temp = `${context.headPath}.${randomUUID()}.tmp`;\n\tconst fd = openSync(temp, fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY, 0o600);\n\ttry {\n\t\twriteAll(fd, Buffer.from(`${JSON.stringify(head)}\\n`, \"utf8\"));\n\t\tfsyncSync(fd);\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n\ttry {\n\t\trenameSync(temp, context.headPath);\n\t\tfsyncDirectorySync(dirname(context.headPath));\n\t} catch (error) {\n\t\tif (existsSync(temp)) unlinkSync(temp);\n\t\tthrow error;\n\t}\n}\n\nfunction quarantineSuffix(context: StoreContext, bytes: Buffer): void {\n\tcontext.hooks.beforeQuarantineFsync?.();\n\twriteExclusiveFileDurablySync(`${context.path}.quarantine-${randomUUID()}`, bytes);\n}\n\n/**\n * Load committed state. With `repair`, an uncommitted suffix is quarantined\n * and truncated; a file whose identity no longer matches its head is accepted\n * only when it begins with exactly the GC snapshot continuation of that head\n * (the GC rename-landed/head-publish-crashed window), otherwise the store is\n * tampered and opens refuse. Without `repair` the suffix is left untouched\n * and simply not part of committed state.\n */\nfunction loadCommitted(context: StoreContext, repair: boolean, cached?: CommittedView): CommittedView {\n\tconst fileExists = existsSync(context.path);\n\tconst headExists = existsSync(context.headPath);\n\tconst empty: CommittedView = {\n\t\thead: EMPTY_AUTHORITY_HEAD,\n\t\tparsed: parseCommitted(Buffer.alloc(0)),\n\t};\n\tif (!fileExists && !headExists) return empty;\n\tif (fileExists && !headExists) {\n\t\tconst fd = openSync(context.path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));\n\t\ttry {\n\t\t\tconst stat = fstatSync(fd);\n\t\t\tif (!stat.isFile() || stat.size !== 0) throw new AuthorityStoreError(\"corrupt\");\n\t\t} finally {\n\t\t\tcloseSync(fd);\n\t\t}\n\t\tif (!repair) return empty;\n\t\tunlinkSync(context.path);\n\t\tfsyncDirectorySync(dirname(context.path));\n\t\treturn empty;\n\t}\n\tif (!fileExists) throw new AuthorityStoreError(\"corrupt\");\n\tlet head: AuthorityHead;\n\ttry {\n\t\thead = parseHead(JSON.parse(readFileSync(context.headPath, \"utf8\")));\n\t} catch (error) {\n\t\tif (error instanceof AuthorityStoreError || error instanceof VerifiedRunError) throw error;\n\t\tthrow new AuthorityStoreError(\"corrupt\");\n\t}\n\tconst fd = openSync(context.path, fsConstants.O_RDWR | (fsConstants.O_NOFOLLOW ?? 0));\n\ttry {\n\t\tconst before = fstatSync(fd);\n\t\tconst bytes = readFileSync(fd);\n\t\tconst after = fstatSync(fd);\n\t\tif (\n\t\t\t!before.isFile() ||\n\t\t\t!after.isFile() ||\n\t\t\tbefore.size !== after.size ||\n\t\t\tbefore.ctimeMs !== after.ctimeMs ||\n\t\t\tafter.size !== bytes.byteLength\n\t\t)\n\t\t\tthrow new AuthorityStoreError(\"tampered\");\n\t\tconst actual = fileIdentityOf(after);\n\t\tif (!sameFileIdentity(head.fileIdentity, actual)) {\n\t\t\thead = healGarbageCollect(context, head, bytes, actual, repair);\n\t\t}\n\t\tif (head.size > after.size) throw new AuthorityStoreError(\"tampered\");\n\t\tconst committed = Buffer.from(bytes.subarray(0, head.size));\n\t\tconst prefix =\n\t\t\tcached &&\n\t\t\tsameFileIdentity(cached.head.fileIdentity, actual) &&\n\t\t\thead.size >= cached.head.size &&\n\t\t\thead.lastSeq >= cached.head.lastSeq\n\t\t\t\t? cached.parsed\n\t\t\t\t: undefined;\n\t\tconst parsed = parseCommitted(committed, prefix);\n\t\tif (parsed.lastSeq !== head.lastSeq || parsed.lastHash !== head.lastHash)\n\t\t\tthrow new AuthorityStoreError(\"tampered\");\n\t\tif (head.size < after.size && repair) {\n\t\t\tquarantineSuffix(context, bytes.subarray(head.size));\n\t\t\tftruncateSync(fd, head.size);\n\t\t\tfsyncSync(fd);\n\t\t\tfsyncDirectorySync(dirname(context.path));\n\t\t}\n\t\treturn { head, parsed };\n\t} finally {\n\t\tcloseSync(fd);\n\t}\n}\n\n/**\n * The only legal file whose identity differs from its head: an atomic GC\n * rewrite that landed but whose head publish never committed. Its first\n * record must be exactly the snapshot continuing `head`; the healed head\n * covers just that record, and any bytes after it are uncommitted suffix.\n */\nfunction healGarbageCollect(\n\tcontext: StoreContext,\n\thead: AuthorityHead,\n\tbytes: Buffer,\n\tactual: NonNullable<AuthorityHead[\"fileIdentity\"]>,\n\trepair: boolean,\n): AuthorityHead {\n\tif (!repair) throw new AuthorityStoreError(\"tampered\");\n\tlet healed: AuthorityHead | null = null;\n\ttry {\n\t\tconst newline = bytes.indexOf(10);\n\t\tif (newline > 0) {\n\t\t\tconst first = bytes.subarray(0, newline + 1);\n\t\t\tconst raw: unknown = JSON.parse(new TextDecoder(\"utf-8\", { fatal: true }).decode(first).slice(0, -1));\n\t\t\tconst event =\n\t\t\t\ttypeof raw === \"object\" && raw !== null && \"event\" in raw\n\t\t\t\t\t? parseAuthorityEvent((raw as { event: unknown }).event)\n\t\t\t\t\t: null;\n\t\t\tif (event?.kind === \"authority-snapshot\") {\n\t\t\t\tconst record = materializeRecord(event.archivedThroughSequence + 1, event.continuesHash, event);\n\t\t\t\t// Only the snapshot line itself must be proven: any bytes after it\n\t\t\t\t// (including a torn tail) are uncommitted suffix and go to quarantine.\n\t\t\t\tif (\n\t\t\t\t\tcanonicalJson(raw) === canonicalJson(record) &&\n\t\t\t\t\tevent.archivedThroughSequence === head.lastSeq &&\n\t\t\t\t\tevent.continuesHash === head.lastHash\n\t\t\t\t) {\n\t\t\t\t\thealed = Object.freeze({\n\t\t\t\t\t\tfileIdentity: actual,\n\t\t\t\t\t\tsize: first.byteLength,\n\t\t\t\t\t\tlastSeq: record.seq,\n\t\t\t\t\t\tlastHash: record.hash,\n\t\t\t\t\t});\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t} catch (error) {\n\t\tif (!(error instanceof AuthorityStoreError || error instanceof VerifiedRunError)) throw error;\n\t}\n\tif (!healed) throw new AuthorityStoreError(\"tampered\");\n\tpublishHead(context, healed);\n\treturn healed;\n}\n\nfunction defaultProbe(grant: AuthorityGrantRecord): \"terminated\" | \"alive\" | \"unknown\" {\n\tif (!grant.identity) return \"unknown\";\n\treturn probeOwnedNamespace(grant.identity);\n}\n\nfunction nextSequenceValue(value: Sequence): Sequence {\n\treturn sequence(String(BigInt(value) + 1n));\n}\n\nfunction assertNonNegativeInteger(value: number, label: string): void {\n\tif (typeof value !== \"number\" || !Number.isSafeInteger(value) || value < 0)\n\t\tthrow new TypeError(`${label} must be a nonnegative safe integer`);\n}\n\n/** The durable single-writer authority boundary. */\nexport class AuthorityStore {\n\tprivate readonly context: StoreContext;\n\tprivate readonly capacity: number;\n\tprivate readonly probe: AuthorityProbe;\n\tprivate readonly lease: DurableFileLock;\n\tprivate accepted: CommittedView;\n\tprivate released = false;\n\tprivate readonly now: () => number;\n\tprivate readonly incrementalReplay: boolean;\n\n\tprivate constructor(\n\t\tcontext: StoreContext,\n\t\tlease: DurableFileLock,\n\t\taccepted: CommittedView,\n\t\toptions: OpenAuthorityStoreOptions,\n\t) {\n\t\tthis.context = context;\n\t\tthis.lease = lease;\n\t\tthis.accepted = accepted;\n\t\tthis.capacity = options.capacity;\n\t\tthis.probe = options.probe ?? defaultProbe;\n\t\tthis.now = createAuthorityClock(options.clock);\n\t\tthis.incrementalReplay = options.incrementalReplay !== false;\n\t}\n\n\t/**\n\t * Take the `\"authority\"` scope lease and advance the persisted epoch.\n\t * When the previous epoch never reconciled, this restart adopts it — the\n\t * pending reconciliation must finish before new admission, and the epoch\n\t * is not bumped again (review §5 fault row).\n\t */\n\tstatic open(path: string, options: OpenAuthorityStoreOptions): AuthorityStore {\n\t\tassertNonNegativeInteger(options.capacity, \"capacity\");\n\t\tmkdirSync(dirname(path), { recursive: true });\n\t\tconst context: StoreContext = { path, headPath: `${path}.head`, hooks: options.hooks ?? {} };\n\t\tconst mutation = acquireDurableFileMutationLockSync(path);\n\t\tlet lease: DurableFileLock;\n\t\ttry {\n\t\t\tlease = acquireDurableFileLockSync(path, AUTHORITY_SCOPE, { timeoutMs: 0 });\n\t\t} catch (error) {\n\t\t\tconst failure =\n\t\t\t\terror instanceof DurableFileLockBusyError\n\t\t\t\t\t? new AuthorityLeaseHeldError(inspectDurableFileLockSync(path, AUTHORITY_SCOPE))\n\t\t\t\t\t: error;\n\t\t\ttry {\n\t\t\t\tmutation.release();\n\t\t\t} catch (cleanupError) {\n\t\t\t\tthrow new AggregateError(\n\t\t\t\t\t[failure, cleanupError instanceof Error ? cleanupError : new Error(String(cleanupError))],\n\t\t\t\t\t\"Authority lease acquisition cleanup failed\",\n\t\t\t\t);\n\t\t\t}\n\t\t\tthrow failure;\n\t\t}\n\t\tlet store: AuthorityStore;\n\t\ttry {\n\t\t\tstore = new AuthorityStore(context, lease, loadCommitted(context, true), options);\n\t\t} catch (error) {\n\t\t\ttry {\n\t\t\t\tlease.release();\n\t\t\t} catch (releaseError) {\n\t\t\t\tthrow new AggregateError(\n\t\t\t\t\t[error, releaseError instanceof Error ? releaseError : new Error(String(releaseError))],\n\t\t\t\t\t\"Authority store open cleanup failed\",\n\t\t\t\t);\n\t\t\t}\n\t\t\tthrow error;\n\t\t} finally {\n\t\t\tmutation.release();\n\t\t}\n\t\ttry {\n\t\t\tif (store.state.epoch === null || !authorityPendingReconcile(store.state)) {\n\t\t\t\t// Fresh store or fully reconciled previous epoch: this restart\n\t\t\t\t// durably advances the epoch. A pending epoch is adopted, not bumped.\n\t\t\t\tstore.commitEpochAdvance();\n\t\t\t}\n\t\t} catch (error) {\n\t\t\ttry {\n\t\t\t\tstore.release();\n\t\t\t} catch (releaseError) {\n\t\t\t\tthrow new AggregateError(\n\t\t\t\t\t[error, releaseError instanceof Error ? releaseError : new Error(String(releaseError))],\n\t\t\t\t\t\"Authority store open cleanup failed\",\n\t\t\t\t);\n\t\t\t}\n\t\t\tthrow error;\n\t\t}\n\t\treturn store;\n\t}\n\n\t/** Read-only committed projection; performs no repair and writes nothing. */\n\tstatic inspect(path: string): AuthorityProjection {\n\t\tconst context: StoreContext = { path, headPath: `${path}.head`, hooks: {} };\n\t\treturn loadCommitted(context, false).parsed.state;\n\t}\n\n\t/**\n\t * Read-only committed journal: projection plus the hashed records it was\n\t * replayed from, so callers can see transition causes (cancel-requested vs\n\t * authorization-expired vs epoch restart) and termination witnesses — the\n\t * projection alone intentionally does not restate them.\n\t */\n\tstatic inspectJournal(path: string): AuthorityJournalInspection {\n\t\tconst context: StoreContext = { path, headPath: `${path}.head`, hooks: {} };\n\t\tconst committed = loadCommitted(context, false);\n\t\treturn Object.freeze({\n\t\t\tstate: committed.parsed.state,\n\t\t\trecords: committed.parsed.records,\n\t\t\thead: committed.head,\n\t\t});\n\t}\n\n\tget path(): string {\n\t\treturn this.context.path;\n\t}\n\n\tget head(): AuthorityHead {\n\t\treturn this.accepted.head;\n\t}\n\n\tget state(): AuthorityProjection {\n\t\treturn structuredClone(this.accepted.parsed.state);\n\t}\n\n\tget lastReplay(): ParsedAuthority[\"replay\"] {\n\t\treturn this.accepted.parsed.replay;\n\t}\n\n\tget pendingReconcile(): boolean {\n\t\treturn authorityPendingReconcile(this.state);\n\t}\n\n\tprivate writerId(): string {\n\t\ttry {\n\t\t\treturn `${readRunClock().bootId}:${process.pid}`;\n\t\t} catch {\n\t\t\treturn `unknown:${process.pid}`;\n\t\t}\n\t}\n\n\t/**\n\t * Commit events as one transaction: mutation lock → committed-head CAS →\n\t * reducer pre-validation → append+fsync → head publish → re-read\n\t * verification. The head CAS is the fencing boundary — a store whose lease\n\t * was reclaimed and taken by another writer sees a changed head and fails\n\t * closed instead of authorizing. Persist failures never mint in-memory\n\t * state (docs/04: no memory-only authorization after storage failure).\n\t */\n\tprivate commit(events: readonly AuthorityEvent[]): void {\n\t\tif (this.released) throw new AuthorityStoreError(\"stale_owner\");\n\t\tconst mutation = acquireDurableFileMutationLockSync(this.context.path);\n\t\ttry {\n\t\t\tconst current = loadCommitted(this.context, true, this.incrementalReplay ? this.accepted : undefined);\n\t\t\tif (!authorityHeadsEqual(current.head, this.accepted.head)) throw new AuthorityStoreError(\"stale_head\");\n\t\t\tif (events.length === 0) {\n\t\t\t\tthis.accepted = current;\n\t\t\t\treturn;\n\t\t\t}\n\t\t\t// Every event must be accepted by the deterministic reducer before a\n\t\t\t// single byte reaches disk.\n\t\t\tapplyAuthorityEvents(current.parsed.state, events);\n\t\t\tconst lines: string[] = [];\n\t\t\tlet seq = current.parsed.lastSeq;\n\t\t\tlet previous = current.parsed.lastHash;\n\t\t\tfor (const event of events) {\n\t\t\t\tseq += 1;\n\t\t\t\tconst record = materializeRecord(seq, previous, event);\n\t\t\t\tlines.push(recordLine(record));\n\t\t\t\tprevious = record.hash;\n\t\t\t}\n\t\t\tconst payload = Buffer.from(lines.join(\"\"), \"utf8\");\n\t\t\t(this.context.hooks.persistRecord ?? appendDurably)(this.context.path, payload);\n\t\t\tconst fd = openSync(this.context.path, fsConstants.O_RDWR | (fsConstants.O_NOFOLLOW ?? 0));\n\t\t\tlet head: AuthorityHead;\n\t\t\ttry {\n\t\t\t\tconst stat = fstatSync(fd);\n\t\t\t\t// CAS on the file itself: for an established store the inode must be\n\t\t\t\t// the one the committed head names; for genesis the append must have\n\t\t\t\t// produced exactly the expected size. Anything else is a replaced or\n\t\t\t\t// foreign file and commits must not bless it.\n\t\t\t\tif (\n\t\t\t\t\tstat.size !== current.head.size + payload.byteLength ||\n\t\t\t\t\t(current.head.fileIdentity !== null &&\n\t\t\t\t\t\t!sameFileIdentity(current.head.fileIdentity, fileIdentityOf(stat)))\n\t\t\t\t)\n\t\t\t\t\tthrow new AuthorityStoreError(\"stale_head\");\n\t\t\t\thead = Object.freeze({\n\t\t\t\t\tfileIdentity: fileIdentityOf(stat),\n\t\t\t\t\tsize: stat.size,\n\t\t\t\t\tlastSeq: seq,\n\t\t\t\t\tlastHash: previous,\n\t\t\t\t});\n\t\t\t} finally {\n\t\t\t\tcloseSync(fd);\n\t\t\t}\n\t\t\tthis.context.hooks.afterLedgerFsync?.();\n\t\t\tpublishHead(this.context, head);\n\t\t\tconst verified = loadCommitted(this.context, false, this.incrementalReplay ? current : undefined);\n\t\t\tif (verified.parsed.lastSeq !== head.lastSeq || verified.parsed.lastHash !== head.lastHash)\n\t\t\t\tthrow new AuthorityStoreError(\"corrupt\");\n\t\t\tthis.accepted = verified;\n\t\t} finally {\n\t\t\tmutation.release();\n\t\t}\n\t}\n\n\tprivate commitEpochAdvance(): void {\n\t\tconst state = this.state;\n\t\tconst epoch = nextSequenceValue(state.epoch ?? sequence(\"0\"));\n\t\tconst transitions = [...state.grants.values()]\n\t\t\t.filter((grant) => !SETTLED_EFFECT_STATES.has(grant.state))\n\t\t\t.map((grant) =>\n\t\t\t\tObject.freeze({\n\t\t\t\t\tgrantSequence: grant.token.grantSequence,\n\t\t\t\t\toutcome: grant.effectLive ? (\"quarantined\" as const) : (\"cancelled\" as const),\n\t\t\t\t}),\n\t\t\t);\n\t\tthis.commit([\n\t\t\t{ kind: \"authority-epoch-advanced\", authorityEpoch: epoch, writerId: this.writerId(), transitions },\n\t\t]);\n\t}\n\n\t/** Announce a session incarnation (S2); the counter survives restarts durably. */\n\tregister(sessionId: string): Sequence {\n\t\tif (typeof sessionId !== \"string\" || sessionId.length === 0)\n\t\t\tthrow new TypeError(\"sessionId must be a non-empty string\");\n\t\tconst current = this.state.incarnations.get(sessionId) ?? sequence(\"0\");\n\t\tconst incarnation = nextSequenceValue(current);\n\t\tthis.commit([{ kind: \"session-registered\", sessionId, incarnation }]);\n\t\treturn incarnation;\n\t}\n\n\t/**\n\t * Admit an authorization: claim-overlap check, capacity check, idempotency\n\t * replay, and the `grant-reserved` record in one lease/mutation-locked\n\t * critical section — the check and the record are one transaction (docs/04).\n\t * The lease is held for the store's lifetime, so committed state cannot\n\t * move between the check and the append; the head CAS in commit() is the\n\t * backstop if it ever could.\n\t */\n\tacquire(input: AuthorityAcquireInput): AuthorityAcquireResult {\n\t\tassertNonNegativeInteger(input.now, \"now\");\n\t\tconst weight = input.weight ?? 1;\n\t\tassertNonNegativeInteger(weight, \"weight\");\n\t\tif (!Number.isSafeInteger(input.ttl) || input.ttl <= 0)\n\t\t\tthrow new TypeError(\"ttl must be a positive safe integer\");\n\t\tconst authorizationDeadline = input.now + input.ttl;\n\t\tif (!Number.isSafeInteger(authorizationDeadline)) throw new RangeError(\"authorization deadline overflow\");\n\t\tconst incarnation = sequence(input.incarnation);\n\t\tif (this.state.incarnations.get(input.sessionId) !== incarnation)\n\t\t\tthrow new AuthorityStoreError(\"stale_incarnation\");\n\t\tif (!/^[a-f0-9]{64}$/.test(input.intentDigest)) throw new TypeError(\"intentDigest must be a sha256 hex digest\");\n\t\tif (!Array.isArray(input.claims) || input.claims.length === 0)\n\t\t\tthrow new TypeError(\"an unknown scope must not be admitted as an empty scope\");\n\t\tconst claims = Object.freeze(Array.from(input.claims, (claim) => canonicalClaim(claim)));\n\n\t\t// Idempotency (I08): replayed commands return their recorded disposition\n\t\t// without re-executing. A live tombstone returns the result; an expired\n\t\t// one reports expiry; an in-flight grant is a duplicate only when the\n\t\t// full intent matches — otherwise it is an ID collision (I09/I20).\n\t\tconst tombstone = this.state.tombstones.get(input.commandId);\n\t\tif (tombstone) {\n\t\t\tconst grant = this.state.grants.get(tombstone.grantSequence);\n\t\t\tif (!grant) throw new AuthorityStoreError(\"corrupt\");\n\t\t\tassertSameCommandMeaning(grant, {\n\t\t\t\tintentDigest: input.intentDigest,\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tincarnation,\n\t\t\t\tclaims,\n\t\t\t\tweight,\n\t\t\t});\n\t\t\tif (tombstone.expiresAtMs <= input.now) return { status: \"result-expired\" };\n\t\t\treturn { status: \"result\", resultDigest: tombstone.resultDigest, token: grant.token };\n\t\t}\n\t\tfor (const grant of this.state.grants.values()) {\n\t\t\tif (grant.commandId !== input.commandId) continue;\n\t\t\tassertSameCommandMeaning(grant, {\n\t\t\t\tintentDigest: input.intentDigest,\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tincarnation,\n\t\t\t\tclaims,\n\t\t\t\tweight,\n\t\t\t});\n\t\t\treturn { status: \"granted\", token: grant.token, duplicate: true };\n\t\t}\n\n\t\tif (this.pendingReconcile) throw new AuthorityStoreError(\"reconcile_pending\");\n\t\tconst epoch = this.state.epoch;\n\t\tif (epoch === null) throw new AuthorityStoreError(\"corrupt\");\n\n\t\tconst expired = expiryEvents(this.state, input.now, epoch);\n\t\tconst settledState = expired.length ? applyAuthorityEvents(this.state, expired) : this.state;\n\t\tconst active = [...settledState.grants.values()].filter((grant) => !SETTLED_EFFECT_STATES.has(grant.state));\n\t\tconst used = active.reduce((sum, grant) => sum + grant.weight, 0);\n\t\tif (weight > this.capacity - used) return { status: \"blocked\" };\n\t\tif (active.some((grant) => claimSetsConflict([...claims], [...grant.claims]))) return { status: \"blocked\" };\n\n\t\tconst grantSequence = nextSequenceValue(this.state.grantCounter);\n\t\tconst grant: AuthorityGrantRecord = Object.freeze({\n\t\t\ttoken: Object.freeze({\n\t\t\t\tauthorityEpoch: epoch,\n\t\t\t\tgrantSequence,\n\t\t\t\tsessionId: input.sessionId,\n\t\t\t\tsessionIncarnation: incarnation,\n\t\t\t\tauthorizationDeadline,\n\t\t\t}),\n\t\t\tcommandId: input.commandId,\n\t\t\tintentDigest: input.intentDigest,\n\t\t\tclaims,\n\t\t\tweight,\n\t\t\tstate: \"reserved\",\n\t\t\teffectLive: false,\n\t\t\tdispatchId: null,\n\t\t\tactualClaims: null,\n\t\t\tidentity: null,\n\t\t});\n\t\tthis.commit([...expired, { kind: \"grant-reserved\", grant }]);\n\t\treturn { status: \"granted\", token: grant.token, duplicate: false };\n\t}\n\n\tprivate resolveToken(token: GrantToken, authoritative: boolean): AuthorityGrantRecord | undefined {\n\t\tconst grant = this.state.grants.get(token.grantSequence);\n\t\tif (!grant || !sameGrantToken(grant.token, token)) return undefined;\n\t\tif (authoritative) {\n\t\t\tif (this.released) return undefined;\n\t\t\tif (\n\t\t\t\ttoken.authorityEpoch !== this.state.epoch ||\n\t\t\t\tthis.state.incarnations.get(token.sessionId) !== token.sessionIncarnation ||\n\t\t\t\tSETTLED_EFFECT_STATES.has(grant.state)\n\t\t\t)\n\t\t\t\treturn undefined;\n\t\t} else if (SETTLED_EFFECT_STATES.has(grant.state)) return undefined;\n\t\treturn grant;\n\t}\n\n\t/**\n\t * Persisted dispatch intent. A committed intent whose spawn was never\n\t * witnessed cannot be assumed un-run; on restart it quarantines like any\n\t * other possibly-live effect (I01/I02).\n\t */\n\tdispatchIntent(token: GrantToken, dispatchId: string, now = this.now()): boolean {\n\t\tif (!/^[A-Za-z0-9_-]{1,128}$/.test(dispatchId)) throw new TypeError(\"dispatchId is invalid\");\n\t\tconst grant = this.resolveToken(token, true);\n\t\tif (!grant || grant.state !== \"reserved\") return false;\n\t\tconst epoch = this.state.epoch;\n\t\tif (epoch === null) return false;\n\t\tif (!authorizationStillOpen(now, grant.token.authorizationDeadline)) {\n\t\t\tthis.expire(now);\n\t\t\treturn false;\n\t\t}\n\t\tthis.commit([\n\t\t\t{ kind: \"dispatch-intent\", grantSequence: grant.token.grantSequence, authorityEpoch: epoch, dispatchId },\n\t\t]);\n\t\treturn true;\n\t}\n\n\t/** Bind an effect to its reservation; actual claims must equal the reserved set exactly. */\n\teffectStarted(\n\t\ttoken: GrantToken,\n\t\tactualClaims: readonly ResourceClaimInput[],\n\t\tidentity?: NamespaceIdentity,\n\t\tnow = this.now(),\n\t): boolean {\n\t\tconst grant = this.resolveToken(token, true);\n\t\tif (!grant || (grant.state !== \"reserved\" && grant.state !== \"starting\")) return false;\n\t\tif (!authorizationStillOpen(now, grant.token.authorizationDeadline)) {\n\t\t\tthis.expire(now);\n\t\t\treturn false;\n\t\t}\n\t\tif (!Array.isArray(actualClaims)) throw new TypeError(\"actualClaims must be an array\");\n\t\tconst claims = Object.freeze(Array.from(actualClaims, (entry) => canonicalClaim(entry)));\n\t\tif (!sameClaimSet([...claims], [...grant.claims])) return false;\n\t\tconst epoch = this.state.epoch;\n\t\tif (epoch === null) return false;\n\t\tthis.commit([\n\t\t\t{\n\t\t\t\tkind: \"effect-started\",\n\t\t\t\tgrantSequence: grant.token.grantSequence,\n\t\t\t\tauthorityEpoch: epoch,\n\t\t\t\tactualClaims: claims,\n\t\t\t\t...(identity ? { identity } : {}),\n\t\t\t},\n\t\t]);\n\t\treturn true;\n\t}\n\n\t/** Revalidate a running effect before its next irreversible boundary, without starting it again. */\n\teffectAuthorized(token: GrantToken, actualClaims: readonly ResourceClaimInput[]): boolean {\n\t\tif (this.released) return false;\n\t\tthis.commit([]);\n\t\tconst now = this.now();\n\t\tconst grant = this.resolveToken(token, true);\n\t\tif (!grant || grant.state !== \"running\") return false;\n\t\tif (!authorizationStillOpen(now, token.authorizationDeadline)) {\n\t\t\tthis.expire(now);\n\t\t\treturn false;\n\t\t}\n\t\treturn sameClaimSet(\n\t\t\tArray.from(actualClaims, (claim) => canonicalClaim(claim)),\n\t\t\tgrant.claims,\n\t\t);\n\t}\n\n\t/** Requested cancellation is not observed termination; live effects quarantine. */\n\tcancel(token: GrantToken): boolean {\n\t\tconst grant = this.resolveToken(token, false);\n\t\tif (!grant) return false;\n\t\tconst epoch = this.state.epoch;\n\t\tif (epoch === null) return false;\n\t\tthis.commit([\n\t\t\t{\n\t\t\t\tkind: \"cancel-requested\",\n\t\t\t\tgrantSequence: grant.token.grantSequence,\n\t\t\t\tauthorityEpoch: epoch,\n\t\t\t\toutcome: grant.effectLive ? \"quarantined\" : \"cancelled\",\n\t\t\t},\n\t\t]);\n\t\treturn true;\n\t}\n\n\t/** Settle lapsed authorizations; never evicts a live effect. */\n\texpire(now: number): void {\n\t\tassertNonNegativeInteger(now, \"now\");\n\t\tconst epoch = this.state.epoch;\n\t\tif (epoch === null) return;\n\t\tconst events = expiryEvents(this.state, now, epoch);\n\t\tif (events.length) this.commit(events);\n\t}\n\n\t/**\n\t * Trusted supervisor witness: this exact effect is gone. Accepted across\n\t * superseded epochs so a restarted authority can settle what the previous\n\t * one started, never to authorize new work.\n\t */\n\tconfirmTerminated(token: GrantToken): boolean {\n\t\tconst grant = this.resolveToken(token, false);\n\t\tif (!grant) return false;\n\t\tconst epoch = this.state.epoch;\n\t\tif (epoch === null) return false;\n\t\tthis.commit([{ kind: \"termination-observed\", grantSequence: grant.token.grantSequence, authorityEpoch: epoch }]);\n\t\treturn true;\n\t}\n\n\t/** Retain the final result as an idempotency tombstone (S3, docs/04). */\n\tretainResult(commandId: string, resultDigest: string, now: number, retentionMs: number): void {\n\t\tassertNonNegativeInteger(now, \"now\");\n\t\tif (!Number.isSafeInteger(retentionMs) || retentionMs <= 0)\n\t\t\tthrow new TypeError(\"retentionMs must be a positive safe integer\");\n\t\tif (!/^[a-f0-9]{64}$/.test(resultDigest)) throw new TypeError(\"resultDigest must be a sha256 hex digest\");\n\t\tconst grant = [...this.state.grants.values()].find((entry) => entry.commandId === commandId);\n\t\tif (!grant) throw new AuthorityStoreError(\"unknown_command\");\n\t\tif (!SETTLED_EFFECT_STATES.has(grant.state)) throw new AuthorityStoreError(\"unsettled\");\n\t\tif (this.state.tombstones.has(commandId)) throw new AuthorityStoreError(\"duplicate\");\n\t\tthis.commit([\n\t\t\t{\n\t\t\t\tkind: \"result-retained\",\n\t\t\t\tcommandId,\n\t\t\t\tgrantSequence: grant.token.grantSequence,\n\t\t\t\tresultDigest,\n\t\t\t\tretainedAtMs: now,\n\t\t\t\texpiresAtMs: now + retentionMs,\n\t\t\t},\n\t\t]);\n\t}\n\n\t/** Command disposition without re-execution (I08/I31). */\n\tlookup(commandId: string, now: number): AuthorityLookup {\n\t\tassertNonNegativeInteger(now, \"now\");\n\t\tconst tombstone = this.state.tombstones.get(commandId);\n\t\tif (tombstone) {\n\t\t\tconst grant = this.state.grants.get(tombstone.grantSequence);\n\t\t\tif (!grant) throw new AuthorityStoreError(\"corrupt\");\n\t\t\treturn tombstone.expiresAtMs <= now\n\t\t\t\t? { status: \"result-expired\", token: grant.token }\n\t\t\t\t: { status: \"result\", resultDigest: tombstone.resultDigest, token: grant.token };\n\t\t}\n\t\tfor (const grant of this.state.grants.values())\n\t\t\tif (grant.commandId === commandId) return { status: \"pending\", token: grant.token };\n\t\treturn { status: \"unknown\" };\n\t}\n\n\t/**\n\t * Finish the restart reconciliation: every quarantined effect is compared\n\t * against the real execution boundary — only an observed termination\n\t * settles it (\"gone\"); \"alive\"/\"unknown\" stay quarantined and keep their\n\t * claims (docs/04, review §6). Ends with `authority-reconciled` for the\n\t * current epoch; the reconciled scope only then admits new work.\n\t */\n\treconcile(probe?: AuthorityProbe): void {\n\t\tconst state = this.state;\n\t\tconst epoch = state.epoch;\n\t\tif (epoch === null) throw new AuthorityStoreError(\"corrupt\");\n\t\tif (!authorityPendingReconcile(state)) return;\n\t\tconst check = probe ?? this.probe;\n\t\tconst events: AuthorityEvent[] = [];\n\t\tfor (const grant of state.grants.values()) {\n\t\t\tif (grant.state !== \"quarantined\") continue;\n\t\t\tif (check(grant) === \"terminated\") {\n\t\t\t\tevents.push({\n\t\t\t\t\tkind: \"termination-observed\",\n\t\t\t\t\tgrantSequence: grant.token.grantSequence,\n\t\t\t\t\tauthorityEpoch: epoch,\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\t\tevents.push({ kind: \"authority-reconciled\", authorityEpoch: epoch });\n\t\tthis.commit(events);\n\t}\n\n\t/**\n\t * GC (review §7): fold droppable state into an `authority-snapshot` and\n\t * atomically rewrite the log to that snapshot. Retained: the epoch pair,\n\t * incarnation counters, the grant counter (I31 — sequences never reissue),\n\t * every unsettled grant, every settled grant still referenced by an\n\t * unexpired tombstone, and the unexpired tombstones themselves. A crash\n\t * between the atomic rewrite and head publish self-heals on next open via\n\t * the snapshot continuation check.\n\t */\n\tcompact(now: number): { readonly dropped: number } {\n\t\tassertNonNegativeInteger(now, \"now\");\n\t\tif (this.released) throw new AuthorityStoreError(\"stale_owner\");\n\t\tconst mutation = acquireDurableFileMutationLockSync(this.context.path);\n\t\ttry {\n\t\t\tconst current = loadCommitted(this.context, true);\n\t\t\tif (!authorityHeadsEqual(current.head, this.accepted.head)) throw new AuthorityStoreError(\"stale_head\");\n\t\t\tconst state = current.parsed.state;\n\t\t\tif (state.epoch === null) return { dropped: 0 };\n\t\t\tconst keepGrant = new Set<Sequence>();\n\t\t\tconst keepTombstone = new Set<string>();\n\t\t\tfor (const tombstone of state.tombstones.values()) {\n\t\t\t\tif (tombstone.expiresAtMs > now) {\n\t\t\t\t\tkeepTombstone.add(tombstone.commandId);\n\t\t\t\t\tkeepGrant.add(tombstone.grantSequence);\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst grants = [...state.grants.values()].filter(\n\t\t\t\t(grant) => !SETTLED_EFFECT_STATES.has(grant.state) || keepGrant.has(grant.token.grantSequence),\n\t\t\t);\n\t\t\tconst tombstones = [...state.tombstones.values()].filter((stone) => keepTombstone.has(stone.commandId));\n\t\t\tconst dropped = state.grants.size - grants.length + (state.tombstones.size - tombstones.length);\n\t\t\tif (dropped === 0) return { dropped: 0 };\n\t\t\tconst snapshot = snapshotFromProjection({\n\t\t\t\t...state,\n\t\t\t\tgrants: new Map(grants.map((grant) => [grant.token.grantSequence, grant])),\n\t\t\t\ttombstones: new Map(tombstones.map((stone) => [stone.commandId, stone])),\n\t\t\t});\n\t\t\tconst record = materializeRecord(current.parsed.lastSeq + 1, current.parsed.lastHash, {\n\t\t\t\tkind: \"authority-snapshot\",\n\t\t\t\tarchivedThroughSequence: current.parsed.lastSeq,\n\t\t\t\tcontinuesHash: current.parsed.lastHash,\n\t\t\t\tstate: snapshot,\n\t\t\t});\n\t\t\tatomicRewriteFileSync(this.context.path, recordLine(record));\n\t\t\tthis.context.hooks.afterAtomicRewrite?.();\n\t\t\tconst fd = openSync(this.context.path, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0));\n\t\t\tlet head: AuthorityHead;\n\t\t\ttry {\n\t\t\t\tconst stat = fstatSync(fd);\n\t\t\t\thead = Object.freeze({\n\t\t\t\t\tfileIdentity: fileIdentityOf(stat),\n\t\t\t\t\tsize: stat.size,\n\t\t\t\t\tlastSeq: record.seq,\n\t\t\t\t\tlastHash: record.hash,\n\t\t\t\t});\n\t\t\t} finally {\n\t\t\t\tcloseSync(fd);\n\t\t\t}\n\t\t\tpublishHead(this.context, head);\n\t\t\tthis.accepted = loadCommitted(this.context, false);\n\t\t\treturn { dropped };\n\t\t} finally {\n\t\t\tmutation.release();\n\t\t}\n\t}\n\n\t/** Release the authority lease; further commits fail closed. */\n\trelease(): void {\n\t\tif (this.released) return;\n\t\tthis.released = true;\n\t\tthis.lease.release();\n\t}\n}\n"]}