@cotal-ai/auth 0.12.0 → 0.13.0

package/dist/retirement-barrier.d.ts

@@ -0,0 +1,217 @@
+/**
+ * The D13 (5) TERMINAL RETIREMENT BARRIER + the EXACT-POOL TERMINAL CLEANER (SPEC §13.1, as
+ * amended; the §13.9 cleaner matrix row). The third sibling of `lifecycle-registry.ts` /
+ * `credential-ledger.ts`: the SAME minting authority over the SAME stores, reached only through
+ * the sealed registry ({@link registryStores}).
+ *
+ * The barrier, in the NORMATIVE order (§13.1) — every boundary crash-resumable from the durable
+ * `stage.<opId>` intent, and only the SAME operation resumes it:
+ *  1. durable retirement intent (create-only, captured BEFORE any movement; it carries only the
+ *     frontier stream set: the barrier DISCOVERS the whole cleaner inventory from the target's
+ *     own accepted pool obligations, taking no caller-supplied pool hint, §13.1 #F);
+ *  2. CAS the issuance gate `open → frozen` carrying the intent (the bar: a staged mint loses
+ *     its finalize touch) — a retirement freeze NEVER reopens (§13.1: its only exit is the
+ *     terminal);
+ *  3. CAS the head `active → retiring` bound to the same op (every currency seam now yields no
+ *     current mapping and no current epoch; the alias is NOT replaceable);
+ *  4. the shared containment core ({@link containLifecycleFamily}): revoke every ledger row
+ *     under `cred.<uid>.>`, reconcile both halves of every session-derived credential, and
+ *     VERIFIED cluster-wide eviction of every holder principal + the alias principal;
+ *  5. drain the target's acceptance obligations to quiescence (§13.8): enumerate
+ *     `oblig.<targetUid>.>` for endpoint discovery, drive each endpoint's injected drain
+ *     ({@link drainTargetForEndpoint} over that endpoint's mediator), then RE-ENUMERATE and
+ *     verify — the barrier OWNS the quiescence check, never the injected seam; then, BEFORE
+ *     anything else proceeds, fence the drain's per-op repair principals (the commit applier /
+ *     pool-route reconciler / effects canceller, {@link drainRepairPrincipals}) with a
+ *     cluster-verified eviction — the APPLIER especially, whose records-KV last-value write is
+ *     visible to a normal reader regardless of the frontier cutoff (#4);
+ *  6. the exact-pool terminal cleaner ({@link runExactPoolCleaner}) under a DISTINCT,
+ *     separately minted, bounded-lived profile per (op × endpoint), then — BEFORE any frontier
+ *     records — revoke the cleaner's own credential and cluster-verify eviction of its
+ *     principal (the §13.1 cleaner fence: no in-flight cleaner can ACK a redelivery or write a
+ *     terminal after the alias is reused);
+ *  7. record the per-stream retirement frontiers (`frontier.<lifecycleUid>`, create-only,
+ *     never deleted — the cutoffs that bound the predecessor's half-open interval);
+ *  8. CAS the gate `frozen → retired` (terminal; unlike takeover, never reopened);
+ *  9. CAS the head `retiring → retired` — only now is the alias replaceable, and `retired`
+ *     ASSERTS the completed barrier.
+ *
+ * FAIL-CLOSED CONTRACT: any failure after the freeze leaves the gate FROZEN and the head at its
+ * current containment state (nothing mints, the alias is not replaceable); eviction failure is
+ * `unavailable`; a live, unexpired, FOREIGN-target pool item is never settled or ACKed and the
+ * barrier refuses to close frontiers while one remains (§13.9).
+ *
+ * SURFACE: NOTHING here is exported from the package index (the same discipline as the
+ * takeover barrier); production wiring lands with the activation slices. The executor seam is
+ * the sealed registry; an `opId` is an identifier, never a bearer capability.
+ */
+import { type JetStreamClient, type JetStreamManager } from "@nats-io/jetstream";
+import { type WorkPoolContext, type WorkItemRef, type WorkTerminalFact } from "@cotal-ai/core";
+import { type LifecycleRegistry } from "./lifecycle-registry.js";
+import { type TakeoverDeps } from "./credential-ledger.js";
+/** One endpoint's EXACT pool list for the cleaner step — the cleaner profile's grant is minted
+ *  from these (§13.9: never a pool wildcard). The barrier DISCOVERS this inventory from the
+ *  target's own accepted pool obligations (#F); it takes no caller-supplied hint. */
+export interface RetirementPoolSpec {
+    endpoint: string;
+    pools: string[];
+}
+/** The durable retirement intent at `stage.<opId>` — captured BEFORE the freeze; every resumed
+ *  step works from these SAME coordinates ({@link resumeAgentRetirement}). */
+export interface RetirementIntent {
+    kind: "retirement";
+    lifecycleUid: string;
+    owner: string;
+    actor: string;
+    /** The gate generation the barrier freezes at (a retirement freeze never reopens, so there is
+     *  no successor generation — the gate terminalizes at this one). */
+    fromGeneration: number;
+    /** The streams whose last sequence the frontier step records (§13.1: the deployment's
+     *  lifecycle-bounded streams). */
+    frontierStreams: string[];
+}
+/** The cleaner's bind: JS handles over the cleaner's OWN authenticated connection (the
+ *  separately minted, bounded-lived, exact-pool profile — NEVER the executor's or the revoked
+ *  owner's connection) plus the CONNZ-attributable principal of that connection, which the
+ *  barrier verified-evicts at the cleaner fence. */
+export interface PoolCleanerBind {
+    jsm: JetStreamManager;
+    js: JetStreamClient;
+    principal: string;
+}
+/** The settlement executor's bind: a space-bonded {@link WorkPoolContext} DERIVED from the
+ *  executor's OWN authenticated connection (the separately minted, op-bounded settlement
+ *  profile, SPEC 13.9 "Retirement settlement"; never the cleaner's bind and never the barrier's
+ *  standing connection, so the settlement rights and the settlement code sit on ONE connection)
+ *  plus that connection's CONNZ-attributable principal, which the barrier verified-evicts at
+ *  the fence alongside the cleaner's. */
+export interface RetirementExecutorBind {
+    work: WorkPoolContext;
+    principal: string;
+}
+/** The retirement barrier's injected capabilities — the takeover deps plus the retirement-only
+ *  seams. Every seam is deployment-owned mechanics; the barrier owns the ORDER and the
+ *  verification. */
+export interface RetirementDeps extends TakeoverDeps {
+    /** Drive ONE endpoint's obligations under the retiring target to §13.8 quiescence (wire to
+     *  `drainTargetForEndpoint` over that endpoint's admission mediator). `opId` is the barrier's
+     *  own durable operation id: the drain's per-op repair credentials (the confined
+     *  commit-applier and pool-route reconciler) mint under it, so their principals are
+     *  op-attributable and op-bounded. The barrier re-checks
+     *  quiescence itself afterward; a drain that lied fails the barrier, not the invariant. */
+    drainTargetObligations: (endpoint: string, targetUid: string, opId: string) => Promise<void>;
+    /** Mint + connect the DISTINCT bounded-lived cleaner profile for (op × endpoint), granted
+     *  exactly the listed pools (§13.9 cleaner row). */
+    openCleaner: (args: {
+        opId: string;
+        endpoint: string;
+        pools: string[];
+    }) => Promise<PoolCleanerBind>;
+    /** Revoke the cleaner bind's credential (the deny-new half) and release its resources. The
+     *  barrier then verified-evicts the bind's principal itself (the kill-live half). Called on
+     *  BOTH the success and the failure path — a wedged barrier never leaves a live cleaner. */
+    retireCleanerCredential: (bind: PoolCleanerBind) => Promise<void>;
+    /** Mint + connect the DISTINCT bounded-lived settlement-executor profile for (op × endpoint),
+     *  granted exactly the listed pools' settlement rows (§13.9 "Retirement settlement": the lease
+     *  CAS + `wrk` terminal publish + the leader-served EPF/records fencing reads; NO EPW read, that
+     *  live-entry probe is unreachable from the settlement path). The barrier builds the settlement
+     *  seam over THIS bind's work context, never its own standing connection. */
+    openExecutor: (args: {
+        opId: string;
+        endpoint: string;
+        pools: string[];
+    }) => Promise<RetirementExecutorBind>;
+    /** Revoke the executor bind's credential (the deny-new half); the barrier verified-evicts its
+     *  principal too. Same discipline as the cleaner: called on success AND failure paths. */
+    retireExecutorCredential: (bind: RetirementExecutorBind) => Promise<void>;
+    /** The executor's clock (the `workExpiry` comparisons and the terminal-fact timestamps). */
+    now: () => number;
+    /** Cleaner pacing knobs (tests tighten them; production defaults hold). */
+    cleaner?: {
+        fetchExpiresMs?: number;
+        maxStalledPasses?: number;
+    };
+}
+/** What one pool's cleaning pass settled. */
+export interface PoolCleanResult {
+    /** Messages ACKed because their item was ALREADY durably terminal. */
+    ackedTerminal: number;
+    /** Items this run settled `expired` (their own `workExpiry` passed). */
+    settledExpired: number;
+    /** Items this run settled `retired` (re-bound to the retiring target via their acceptance). */
+    settledRetired: number;
+}
+/** Executor-authority settlement seam. The cleaner supplies only delivery identity/bytes and a
+ *  requested disposition; the implementation is closed over the durable retirement intent and
+ *  independently re-derives every authority coordinate before touching the lease. */
+export type SettleRetirementPoolItem = (args: {
+    ref: WorkItemRef;
+    itemBytes: Uint8Array;
+    disposition: "expired" | "retired";
+}) => Promise<WorkTerminalFact>;
+/**
+ * Run the exact-pool terminal cleaner over ONE named pool (§13.9 matrix row), on the CLEANER's
+ * own bind. Bind-time re-proof first: the pre-created durable's filter is exactly the named
+ * pool's subtree, pull mode, explicit ack, unlimited delivery ceiling. Then drain to a PROVEN
+ * quiescent pool: for each delivered message — ACK only if the item is durably terminal; settle
+ * `expired` when its own `workExpiry` passed (any target); settle `retired` ONLY after
+ * re-binding the item to THIS operation's retiring target through its acceptance decision fact
+ * (the `epw` subject carries no target); a live, unexpired, FOREIGN-target item is never
+ * settled or ACKed and quiescence fails loud while one remains. Quiescence is a FRESH consumer
+ * read showing zero `num_pending` and zero `num_ack_pending` (pre-existing owner ACKs drain
+ * through `AckWait` redelivery into this loop).
+ */
+export declare function runExactPoolCleaner(bind: PoolCleanerBind, args: {
+    space: string;
+    endpoint: string;
+    pool: string;
+    /** Executor-authority, effective-inventory-closed lease/terminal seam; never cleaner-owned handles. */
+    settleItem: SettleRetirementPoolItem;
+    /** The retiring target this operation may re-bind items to. */
+    targetUid: string;
+    now: () => number;
+    fetchExpiresMs?: number;
+    maxStalledPasses?: number;
+}): Promise<PoolCleanResult>;
+/** The barrier's outcome (durable facts, re-readable on resume; a resume that found the work
+ *  already done reports zero counts, exactly the takeover discipline). */
+export interface RetirementResult {
+    opId: string;
+    lifecycleUid: string;
+    revokedRows: number;
+    evictedPrincipals: string[];
+    /** Endpoints whose obligations the drain step drove (discovery order, sorted). */
+    drainedEndpoints: string[];
+    /** Per `<endpoint>/<pool>` cleaning counts for the pools THIS run cleaned. */
+    cleaned: Record<string, PoolCleanResult>;
+    /** The recorded per-stream retirement frontiers. */
+    frontiers: Record<string, number>;
+}
+/** Build the effective-inventory-closed executor settlement seam (§13.9): the returned function
+ *  runs under the barrier's op-bounded authority and refuses any ref outside its effective
+ *  inventory (the barrier-discovered `spec.pools`, the accepted `oblig.<uid>.>` routes) or
+ *  this retirement's lifecycle — a foreign endpoint or a pool outside its discovered spec, an
+ *  unaccepted or non-pool decision, expiring a live item, or retiring an item accepted for a
+ *  target outside this intent's lifecycle. The cleaner chooses refs; it can never borrow this
+ *  authority beyond its discovered inventory or this retirement's lifecycle (the confused-deputy
+ *  closure). */
+export declare function settlementForIntent(work: WorkPoolContext, intent: RetirementIntent, spec: RetirementPoolSpec, space: string, opId: string, now: () => number): SettleRetirementPoolItem;
+/**
+ * Run the FULL terminal retirement barrier for a managed-agent lifecycle (SPEC 13.1, in the
+ * normative order — module header). Idempotent/crash-resumable: every step re-checks durable
+ * state, so calling it again with the SAME `opId` (directly or via
+ * {@link resumeAgentRetirement}) finishes the same operation; a different operation's freeze, a
+ * foreign generation movement, or a stranger's opId refuses before any CAS.
+ */
+export declare function runAgentRetirementBarrier(reg: LifecycleRegistry, args: {
+    owner: string;
+    actor: string;
+    lifecycleUid: string;
+    opId: string;
+    frontierStreams: string[];
+}, deps: RetirementDeps): Promise<RetirementResult>;
+/** Resume a crashed retirement from its durable intent alone (`{ opId }` — SPEC 13.1). Re-runs
+ *  {@link runAgentRetirementBarrier} with the intent's own coordinates; a stranger's opId (no
+ *  intent) is `not-found`. */
+export declare function resumeAgentRetirement(reg: LifecycleRegistry, opId: string, deps: RetirementDeps): Promise<RetirementResult>;
+//# sourceMappingURL=retirement-barrier.d.ts.map

package/dist/retirement-barrier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retirement-barrier.d.ts","sourceRoot":"","sources":["../src/retirement-barrier.ts"],"names":[],"mappings":"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"}