@cotal-ai/core 0.11.6 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (170) hide show
  1. package/dist/acls.d.ts +31 -7
  2. package/dist/acls.d.ts.map +1 -1
  3. package/dist/acls.js +105 -17
  4. package/dist/acls.js.map +1 -1
  5. package/dist/agent-file.js +1 -1
  6. package/dist/agent-file.js.map +1 -1
  7. package/dist/auth-provider.d.ts +90 -10
  8. package/dist/auth-provider.d.ts.map +1 -1
  9. package/dist/auth-provider.js.map +1 -1
  10. package/dist/backup-config.d.ts +55 -0
  11. package/dist/backup-config.d.ts.map +1 -0
  12. package/dist/backup-config.js +243 -0
  13. package/dist/backup-config.js.map +1 -0
  14. package/dist/backup.d.ts +86 -0
  15. package/dist/backup.d.ts.map +1 -0
  16. package/dist/backup.js +497 -0
  17. package/dist/backup.js.map +1 -0
  18. package/dist/broker-floor.d.ts +34 -0
  19. package/dist/broker-floor.d.ts.map +1 -0
  20. package/dist/broker-floor.js +39 -0
  21. package/dist/broker-floor.js.map +1 -0
  22. package/dist/canonical.d.ts +24 -0
  23. package/dist/canonical.d.ts.map +1 -0
  24. package/dist/canonical.js +159 -0
  25. package/dist/canonical.js.map +1 -0
  26. package/dist/channels.d.ts.map +1 -1
  27. package/dist/channels.js +8 -1
  28. package/dist/channels.js.map +1 -1
  29. package/dist/connector.d.ts +4 -0
  30. package/dist/connector.d.ts.map +1 -1
  31. package/dist/endpoint-action.d.ts +424 -0
  32. package/dist/endpoint-action.d.ts.map +1 -0
  33. package/dist/endpoint-action.js +910 -0
  34. package/dist/endpoint-action.js.map +1 -0
  35. package/dist/endpoint-binding.d.ts +344 -0
  36. package/dist/endpoint-binding.d.ts.map +1 -0
  37. package/dist/endpoint-binding.js +753 -0
  38. package/dist/endpoint-binding.js.map +1 -0
  39. package/dist/endpoint-checkpoint.d.ts +292 -0
  40. package/dist/endpoint-checkpoint.d.ts.map +1 -0
  41. package/dist/endpoint-checkpoint.js +818 -0
  42. package/dist/endpoint-checkpoint.js.map +1 -0
  43. package/dist/endpoint-cluster.d.ts +95 -0
  44. package/dist/endpoint-cluster.d.ts.map +1 -0
  45. package/dist/endpoint-cluster.js +194 -0
  46. package/dist/endpoint-cluster.js.map +1 -0
  47. package/dist/endpoint-contract-store.d.ts +90 -0
  48. package/dist/endpoint-contract-store.d.ts.map +1 -0
  49. package/dist/endpoint-contract-store.js +348 -0
  50. package/dist/endpoint-contract-store.js.map +1 -0
  51. package/dist/endpoint-envelope.d.ts +165 -0
  52. package/dist/endpoint-envelope.d.ts.map +1 -0
  53. package/dist/endpoint-envelope.js +346 -0
  54. package/dist/endpoint-envelope.js.map +1 -0
  55. package/dist/endpoint-grants.d.ts +123 -0
  56. package/dist/endpoint-grants.d.ts.map +1 -0
  57. package/dist/endpoint-grants.js +215 -0
  58. package/dist/endpoint-grants.js.map +1 -0
  59. package/dist/endpoint-guard.d.ts +222 -0
  60. package/dist/endpoint-guard.d.ts.map +1 -0
  61. package/dist/endpoint-guard.js +468 -0
  62. package/dist/endpoint-guard.js.map +1 -0
  63. package/dist/endpoint-handle.d.ts +176 -0
  64. package/dist/endpoint-handle.d.ts.map +1 -0
  65. package/dist/endpoint-handle.js +608 -0
  66. package/dist/endpoint-handle.js.map +1 -0
  67. package/dist/endpoint-journal.d.ts +225 -0
  68. package/dist/endpoint-journal.d.ts.map +1 -0
  69. package/dist/endpoint-journal.js +431 -0
  70. package/dist/endpoint-journal.js.map +1 -0
  71. package/dist/endpoint-receipt.d.ts +225 -0
  72. package/dist/endpoint-receipt.d.ts.map +1 -0
  73. package/dist/endpoint-receipt.js +417 -0
  74. package/dist/endpoint-receipt.js.map +1 -0
  75. package/dist/endpoint-records.d.ts +243 -0
  76. package/dist/endpoint-records.d.ts.map +1 -0
  77. package/dist/endpoint-records.js +591 -0
  78. package/dist/endpoint-records.js.map +1 -0
  79. package/dist/endpoint-serve.d.ts +176 -0
  80. package/dist/endpoint-serve.d.ts.map +1 -0
  81. package/dist/endpoint-serve.js +446 -0
  82. package/dist/endpoint-serve.js.map +1 -0
  83. package/dist/endpoint-service.d.ts +518 -0
  84. package/dist/endpoint-service.d.ts.map +1 -0
  85. package/dist/endpoint-service.js +973 -0
  86. package/dist/endpoint-service.js.map +1 -0
  87. package/dist/endpoint-session.d.ts +398 -0
  88. package/dist/endpoint-session.d.ts.map +1 -0
  89. package/dist/endpoint-session.js +834 -0
  90. package/dist/endpoint-session.js.map +1 -0
  91. package/dist/endpoint-signing.d.ts +105 -0
  92. package/dist/endpoint-signing.d.ts.map +1 -0
  93. package/dist/endpoint-signing.js +190 -0
  94. package/dist/endpoint-signing.js.map +1 -0
  95. package/dist/endpoint-subjects.d.ts +222 -0
  96. package/dist/endpoint-subjects.d.ts.map +1 -0
  97. package/dist/endpoint-subjects.js +381 -0
  98. package/dist/endpoint-subjects.js.map +1 -0
  99. package/dist/endpoint-supervisor.d.ts +19 -0
  100. package/dist/endpoint-supervisor.d.ts.map +1 -0
  101. package/dist/endpoint-supervisor.js +12 -0
  102. package/dist/endpoint-supervisor.js.map +1 -0
  103. package/dist/endpoint-traits.d.ts +225 -0
  104. package/dist/endpoint-traits.d.ts.map +1 -0
  105. package/dist/endpoint-traits.js +469 -0
  106. package/dist/endpoint-traits.js.map +1 -0
  107. package/dist/endpoint-verbs.d.ts +277 -0
  108. package/dist/endpoint-verbs.d.ts.map +1 -0
  109. package/dist/endpoint-verbs.js +576 -0
  110. package/dist/endpoint-verbs.js.map +1 -0
  111. package/dist/endpoint-virtual.d.ts +308 -0
  112. package/dist/endpoint-virtual.d.ts.map +1 -0
  113. package/dist/endpoint-virtual.js +440 -0
  114. package/dist/endpoint-virtual.js.map +1 -0
  115. package/dist/endpoint-work.d.ts +304 -0
  116. package/dist/endpoint-work.d.ts.map +1 -0
  117. package/dist/endpoint-work.js +728 -0
  118. package/dist/endpoint-work.js.map +1 -0
  119. package/dist/endpoint.d.ts +66 -22
  120. package/dist/endpoint.d.ts.map +1 -1
  121. package/dist/endpoint.js +289 -89
  122. package/dist/endpoint.js.map +1 -1
  123. package/dist/evict.d.ts +95 -32
  124. package/dist/evict.d.ts.map +1 -1
  125. package/dist/evict.js +193 -3
  126. package/dist/evict.js.map +1 -1
  127. package/dist/index.d.ts +29 -0
  128. package/dist/index.d.ts.map +1 -1
  129. package/dist/index.js +29 -0
  130. package/dist/index.js.map +1 -1
  131. package/dist/lease.d.ts +4 -0
  132. package/dist/lease.d.ts.map +1 -1
  133. package/dist/lease.js.map +1 -1
  134. package/dist/members.d.ts +4 -4
  135. package/dist/members.d.ts.map +1 -1
  136. package/dist/members.js +12 -12
  137. package/dist/members.js.map +1 -1
  138. package/dist/provision.d.ts +78 -20
  139. package/dist/provision.d.ts.map +1 -1
  140. package/dist/provision.js +214 -37
  141. package/dist/provision.js.map +1 -1
  142. package/dist/runtime.d.ts +3 -0
  143. package/dist/runtime.d.ts.map +1 -1
  144. package/dist/safe-pattern.d.ts +33 -0
  145. package/dist/safe-pattern.d.ts.map +1 -0
  146. package/dist/safe-pattern.js +486 -0
  147. package/dist/safe-pattern.js.map +1 -0
  148. package/dist/schema-profile.d.ts +93 -0
  149. package/dist/schema-profile.d.ts.map +1 -0
  150. package/dist/schema-profile.js +284 -0
  151. package/dist/schema-profile.js.map +1 -0
  152. package/dist/secret-store.d.ts +46 -0
  153. package/dist/secret-store.d.ts.map +1 -0
  154. package/dist/secret-store.js +2 -0
  155. package/dist/secret-store.js.map +1 -0
  156. package/dist/space-auth.d.ts +9 -0
  157. package/dist/space-auth.d.ts.map +1 -0
  158. package/dist/space-auth.js +126 -0
  159. package/dist/space-auth.js.map +1 -0
  160. package/dist/streams.d.ts +14 -10
  161. package/dist/streams.d.ts.map +1 -1
  162. package/dist/streams.js +47 -76
  163. package/dist/streams.js.map +1 -1
  164. package/dist/subjects.d.ts +100 -40
  165. package/dist/subjects.d.ts.map +1 -1
  166. package/dist/subjects.js +136 -60
  167. package/dist/subjects.js.map +1 -1
  168. package/dist/types.d.ts +9 -0
  169. package/dist/types.d.ts.map +1 -1
  170. package/package.json +6 -2
@@ -0,0 +1,304 @@
1
+ /**
2
+ * Claim work pools (SPEC §13.5 "claim", §13.6 predicate, §13.9 rows): competitive
3
+ * at-most-one-winner acquisition from a durable pool, OWNER-MEDIATED end to end.
4
+ *
5
+ * The pool's owning endpoint holds the pool's single AckExplicit pull consumer
6
+ * (`pool_<e>_<pool>`, provisioner-pre-created, exact filter); workers hold NO JetStream grant
7
+ * on the pool and acquire, renew, and settle work exclusively through the owner's reserved
8
+ * `lease` and `commit` commands on the ordinary `ep` rails. This is the only shape that
9
+ * satisfies both claim invariants at once: the delivery's ack token never leaves the party
10
+ * allowed to use it, and the attempt binding is OWNER-RECORDED at assignment (a worker-carried
11
+ * "sequence + attempt" proves nothing about delivery; an owner assignment does).
12
+ *
13
+ * The stored pool message is WORK IDENTITY AND INPUT ONLY, never the authoritative lease:
14
+ * broker redelivery re-delivers the same stored bytes, so a token in the payload cannot fence,
15
+ * and the consumer's ack_wait is the broker's redelivery-to-owner timer only.
16
+ *
17
+ * THE LEASE RECORD IS THE SINGLE PER-ITEM LINEARIZATION POINT. The `lease` record
18
+ * (`lease.<e>.<pool>.<acceptance>`, §13.7) holds the owner-recorded assignment for the item's
19
+ * CURRENT attempt AND its settlement state (`leased` | `settled`). A redelivery-advance, a
20
+ * commit, and an expiry all contend on this ONE key's revision, so lease currency and terminal
21
+ * settlement share a fence rather than reading across KV + EPF: the winner of the lease's CAS to
22
+ * `settled` decides the disposition, and the per-item terminal fact
23
+ * `epf.<endpoint>.wrk.<pool>.<acceptance identity>` is DERIVED from the settled lease (published
24
+ * create-only, idempotently, by the committing worker's owner or by reconciliation). This closes
25
+ * the double-effect windows a cross-store read-then-write left open (a stale attempt committing
26
+ * after reassignment; an already-settled item being leased again).
27
+ *
28
+ * Every accepted item carries an absolute `workExpiry` (from its AcceptanceFact, §13.8). The
29
+ * lease deadline is CLAMPED to it (`min(now + ttl, workExpiry)`), so no valid lease outlives the
30
+ * horizon, and commit additionally refuses at `now >= workExpiry`: the item is dead once it
31
+ * passes, leased or not. An endpoint worker's process epoch is freshly resolved and re-checked
32
+ * at commit (§13.8), so a superseded process cannot settle a lease its predecessor held.
33
+ */
34
+ import type { KV } from "@nats-io/kv";
35
+ import { type JetStreamClient, type JetStreamManager } from "@nats-io/jetstream";
36
+ import { type NatsConnection } from "@nats-io/transport-node";
37
+ import { type EpCaller } from "./endpoint-subjects.js";
38
+ import { type AcceptanceFact } from "./endpoint-journal.js";
39
+ /** A pool item's coordinates: the pool plus the item's ACCEPTANCE IDENTITY (§13.2: the accepted
40
+ * submission's caller triple + request id — the four trailing subject tokens). */
41
+ export interface WorkItemRef {
42
+ endpoint: string;
43
+ pool: string;
44
+ acceptance: EpCaller & {
45
+ id: string;
46
+ };
47
+ }
48
+ /** A trusted, space-bonded work-pool context: the KV + JS + JSM are all DERIVED from one
49
+ * binding-layer connection and one space by the constructor (never injected independently), so
50
+ * a caller can never check a space-A lease against space-B facts. Every seam takes this
51
+ * context. */
52
+ export interface WorkPoolContext {
53
+ kv: KV;
54
+ js: JetStreamClient;
55
+ jsm: JetStreamManager;
56
+ space: string;
57
+ }
58
+ /** Bond the resources to one space by CONSTRUCTION: the JetStream client, the manager, and the
59
+ * records KV (the space's own bucket) all derive from the ONE connection passed in — four
60
+ * already-separated resources are not accepted, so the advertised bond is real, not asserted.
61
+ * The returned context is FROZEN (no later swap) and BRANDED: every seam accepts only a
62
+ * context this constructor built, so a hand-assembled structural look-alike (the cross-space
63
+ * mixup the bond exists to prevent) is rejected at the consuming boundary. */
64
+ export declare function workPoolContext(nc: NatsConnection, space: string): Promise<WorkPoolContext>;
65
+ /** The brand assertion, exported for sibling modules composing over this context (the §13.6
66
+ * virtual admission/occupancy seams): every seam that accepts a WorkPoolContext enforces the
67
+ * constructed bond, none trusts a structural look-alike. */
68
+ export declare function assertWorkPoolContext(ctx: WorkPoolContext): void;
69
+ /** The item's stored subject (`epw.<e>.<pool>.<cOwner>.<cActor>.<cUid>.<id>`). */
70
+ export declare function workItemSubject(space: string, ref: WorkItemRef): string;
71
+ /** The item's terminal-fact subject (`epf.<e>.wrk.<pool>.<acceptance identity>`, §13.2). */
72
+ export declare function workTerminalSubject(space: string, ref: WorkItemRef): string;
73
+ /** The CANONICAL acceptance→item-bytes derivation (§13.6): the ONE deterministic projection of a
74
+ * pool-routed {@link AcceptanceFact} into the EPW stored bytes — work identity + input ONLY
75
+ * (`v`/`id`/`fingerprint`/`sourceSeq`/`workExpiry`/`caller`/`request`; never a lease, token, or
76
+ * decision metadata), RFC-8785 canonical JSON so two independent derivations are BYTE-IDENTICAL.
77
+ * Every first enqueue AND every reconciliation re-enqueue MUST derive through this function:
78
+ * {@link enqueueWorkItem}'s idempotency is same-subject AND same-bytes, so a canonicalizer and a
79
+ * drain repairing its crash-before-enqueue must agree byte-for-byte or the repair fails loud as
80
+ * a mixup. Refuses a non-pool route or a missing work horizon (those never enqueue). */
81
+ export declare function workItemBytesOf(acceptance: AcceptanceFact): Uint8Array;
82
+ /** Enqueue a pool item (the canonicalizer's seam, §13.6): CREATE-ONLY per acceptance-identity
83
+ * subject, so acceptance→enqueue spanning two streams stays idempotent — a duplicate or
84
+ * reconciliation re-enqueue of the same item loses its CAS harmlessly. The bytes are the
85
+ * acceptance-derived work identity + input ONLY (never a lease/token; {@link workItemBytesOf}
86
+ * is the canonical derivation). A CAS loss is only a
87
+ * benign duplicate if the stored bytes are BYTE-IDENTICAL to the ones offered (same
88
+ * acceptance-derived work): a differing prior body under the same identity is a canonicalizer
89
+ * mixup and fails loud, never silently executes the wrong input. */
90
+ export declare function enqueueWorkItem(ctx: WorkPoolContext, itemRef: WorkItemRef, itemBytes: Uint8Array): Promise<{
91
+ enqueued: boolean;
92
+ seq?: number;
93
+ }>;
94
+ /** The worker identity the OWNER binds at assignment: the broker-authenticated caller of the
95
+ * reserved `lease` command (§13.5), DISCRIMINATED by kind. An `endpoint` worker (an endpoint
96
+ * instance draining the pool) MUST carry its fenced process `epoch`, freshly re-checked at
97
+ * commit; an `agent` worker has no epoch (its lifecycle UID is the whole currency). The kind is
98
+ * structural so a missing epoch can never silently disable the fence. */
99
+ export type WorkWorker = {
100
+ kind: "agent";
101
+ owner: string;
102
+ actor: string;
103
+ lifecycleUid: string;
104
+ } | {
105
+ kind: "endpoint";
106
+ owner: string;
107
+ actor: string;
108
+ lifecycleUid: string;
109
+ epoch: number;
110
+ };
111
+ /** The authoritative lease value at `lease.<e>.<pool>.<acceptance>.spec` (§13.7). The lease is
112
+ * the item's per-item state machine: `leased` (a live assignment for the CURRENT attempt) or
113
+ * `settled` (terminal — carries the disposition + committed outcome so the terminal fact is
114
+ * derivable). */
115
+ export interface WorkLease {
116
+ v: 1;
117
+ state: "leased" | "settled";
118
+ /** The enqueued item's stream sequence — binds the lease to the exact stored execution. */
119
+ sourceSeq: number;
120
+ /** The broker delivery count of the owner's fetch: the ONLY evidence of delivery. */
121
+ attempt: number;
122
+ /** Present for `leased` and `settled:committed` (and kept when an existing lease is settled
123
+ * expired/retired); ABSENT only for a NEVER-LEASED workerless settlement sentinel. */
124
+ worker?: WorkWorker;
125
+ /** CAS-incremented once per attempt — the §13.8 monotonic fencing token. */
126
+ fencingToken: number;
127
+ /** From the OWNER's own clock, CLAMPED to `workExpiry`; expiry revokes the claim. */
128
+ leaseDeadline: number;
129
+ /** The item's absolute work horizon (§13.8), persisted so commit fences on it too. */
130
+ workExpiry: number;
131
+ /** Present iff `state === "settled"`: how it settled and (for a commit) the cached outcome. */
132
+ disposition?: "committed" | "expired" | "retired";
133
+ outcome?: unknown;
134
+ opId?: string;
135
+ targetUid?: string;
136
+ committedTs?: number;
137
+ }
138
+ /** Issue (or idempotently re-issue) the item's lease for the owner's CURRENT delivery — the
139
+ * reserved `lease` command's handler seam, driven ONLY by the pool-owning endpoint after it
140
+ * fetched the item off its own durable (§13.5).
141
+ *
142
+ * First-wins idempotent CAS per (item, attempt):
143
+ * - no record → create `leased {attempt, worker, fencingToken: 1, leaseDeadline, workExpiry}`;
144
+ * - the recorded attempt EQUALS this delivery → the SAME lease returns unchanged (no
145
+ * reassignment within an attempt; the commit gate binds to the RECORDED worker);
146
+ * - the recorded attempt is OLDER → redelivery advanced: revision-pinned update to the new
147
+ * attempt with `fencingToken + 1`;
148
+ * - the recorded attempt is NEWER → the caller's delivery is stale (`expired`).
149
+ * Refusals before touching state: EXPIRED work (`now >= workExpiry`, settled by reconciliation,
150
+ * never leased) and a SETTLED lease (`state === "settled"` — a committed item can never be
151
+ * leased again, fenced on the SAME key, no cross-store read). `leaseDeadline` is CLAMPED to
152
+ * `workExpiry` so no valid lease outlives the horizon. A DEL marker on the lease refuses. */
153
+ export declare function leaseWorkItem(ctx: WorkPoolContext, args: {
154
+ ref: WorkItemRef;
155
+ sourceSeq: number;
156
+ attempt: number;
157
+ worker: WorkWorker;
158
+ /** The pool OWNER's own clock (never the worker's). */
159
+ now: number;
160
+ leaseTtlMs: number;
161
+ /** The item's absolute work expiry, read from its AcceptanceFact (§13.8). */
162
+ workExpiry: number;
163
+ }): Promise<WorkLease>;
164
+ /** A pool item's cached terminal fact (`epf.<e>.wrk.<pool>.<acceptance>`), DERIVED from the
165
+ * settled lease — except `retired`, which the §13.1 retirement barrier's exact-pool cleaner
166
+ * writes for an item whose acceptance targets the retiring lifecycle (never from a lease; the
167
+ * owner's credentials are already revoked). Create-only CAS per item; the first terminal wins
168
+ * forever. */
169
+ export type WorkTerminalFact = {
170
+ v: 1;
171
+ disposition: "committed";
172
+ pool: string;
173
+ caller: EpCaller & {
174
+ id: string;
175
+ };
176
+ sourceSeq: number;
177
+ attempt: number;
178
+ fencingToken: number;
179
+ worker: WorkWorker;
180
+ outcome: unknown;
181
+ ts: number;
182
+ } | {
183
+ v: 1;
184
+ disposition: "expired";
185
+ pool: string;
186
+ caller: EpCaller & {
187
+ id: string;
188
+ };
189
+ workExpiry: number;
190
+ ts: number;
191
+ } | {
192
+ v: 1;
193
+ disposition: "retired";
194
+ pool: string;
195
+ caller: EpCaller & {
196
+ id: string;
197
+ };
198
+ /** The retirement operation that settled the item and the retiring target it re-bound the
199
+ * item to through its acceptance decision (§13.9 cleaner row: the `epw` subject carries
200
+ * no target, so the binding is recorded here). */
201
+ opId: string;
202
+ targetUid: string;
203
+ ts: number;
204
+ };
205
+ /** Validate a terminal fact fully AND bind it to the subject it was read from (§13.4): a garbled
206
+ * or mis-subjected fact never counts as authoritative settlement (which would suppress all
207
+ * future leasing). Exported as the shared codec: the retirement cleaner (§13.1), which holds no
208
+ * pool-owner context, validates the winners it reads through this same seam. */
209
+ export declare function parseWorkTerminalFact(raw: unknown, subject: string, ref: WorkItemRef): WorkTerminalFact;
210
+ /** Read the item's cached terminal state (leader-served last-by-subject: the CAS-loser read
211
+ * needs read-your-writes, §13.4). `undefined` when the item has no terminal yet. */
212
+ export declare function readWorkTerminal(ctx: WorkPoolContext, itemRef: WorkItemRef): Promise<WorkTerminalFact | undefined>;
213
+ /** Settle a claimed item — the reserved `commit` command's handler seam, driven ONLY by the
214
+ * pool-owning endpoint on behalf of the broker-authenticated commit caller (§13.5). Gate order
215
+ * against the OWNER-RECORDED lease and the owner's clock: execution binding (sourceSeq) →
216
+ * token currency (attempt + fencingToken) → the caller IS the lease's bound worker → FRESH
217
+ * epoch currency for an endpoint worker → `now < workExpiry` → `now < leaseDeadline`. Then the
218
+ * FENCE: a revision-pinned CAS advances the lease `leased → settled{committed, outcome}` — the
219
+ * SAME key a redelivery-advance contends on, so a stale attempt cannot slip a commit in after
220
+ * reassignment. Only after winning that CAS is the terminal fact (derived from the settled
221
+ * lease) published. A lost lease CAS means the lease advanced or settled concurrently: a
222
+ * same-tuple settle is a DUPLICATE (return the cached terminal, which DOMINATES lease-expiry —
223
+ * a true duplicate always sees its cached outcome, §13.5); anything else is `expired`/`conflict`.
224
+ *
225
+ * `resolveCurrentEpoch` freshly resolves an endpoint worker's CURRENT process epoch from trusted
226
+ * authority (the lifecycle mapping) — a required seam for endpoint workers, absent for agents. */
227
+ export declare function commitWorkItem(ctx: WorkPoolContext, args: {
228
+ ref: WorkItemRef;
229
+ /** The broker-authenticated caller of the `commit` command — never a payload claim. */
230
+ caller: WorkWorker;
231
+ /** The exact lease tuple the worker carries back (§13.5). */
232
+ lease: {
233
+ sourceSeq: number;
234
+ attempt: number;
235
+ fencingToken: number;
236
+ };
237
+ outcome: unknown;
238
+ /** The pool OWNER's own clock. */
239
+ now: number;
240
+ /** REQUIRED for an endpoint worker: fresh current-epoch resolver (null = retired/unknown
241
+ * lifecycle). Absent/ignored for an agent worker. */
242
+ resolveCurrentEpoch?: (worker: WorkWorker) => Promise<number | null> | number | null;
243
+ /** OWNER-CONTROLLED budget on the resolver await (default 5000ms): a stuck lifecycle
244
+ * authority is a bounded `unavailable` refusal, never a hung commit. */
245
+ epochResolveBudgetMs?: number;
246
+ }): Promise<{
247
+ won: boolean;
248
+ fact: WorkTerminalFact;
249
+ }>;
250
+ /** The §13.6 reconciliation verdict for one accepted, pool-routed item. */
251
+ export type WorkReconcileVerdict = {
252
+ state: "settled";
253
+ fact: WorkTerminalFact;
254
+ } | {
255
+ state: "expired-settled";
256
+ fact: WorkTerminalFact;
257
+ } | {
258
+ state: "live";
259
+ } | {
260
+ state: "re-enqueued";
261
+ seq: number;
262
+ };
263
+ /** Decide and repair one item against the §13.6 predicate — the canonicalizer's reconciliation
264
+ * seam (§13.9 row), for an ACCEPTED pool-routed item. The LEASE is consulted as the settlement
265
+ * arbiter so reconciliation never contradicts a committing worker:
266
+ * 1. a terminal `wrk` fact exists → SETTLED (the owner acks without effect);
267
+ * 2. the lease is `settled` (a commit fenced it, maybe crashed before publishing) → publish
268
+ * the derived terminal (idempotent) → SETTLED — recovery, never re-enqueued;
269
+ * 3. `now >= workExpiry` → the item is DEAD, leased or not: fence it by CAS-settling the lease
270
+ * `expired` (racing a live commit on the SAME key; a lost CAS re-reads the winner), then
271
+ * publish the derived terminal → EXPIRED-SETTLED; with no lease record, a worker-less
272
+ * `settled:expired` lease is CAS-CREATED on the same key first, so a racing FIRST lease
273
+ * contends there instead of assigning dead work behind the expiry;
274
+ * 4. a live pool entry exists (subject-confined LEADER-SERVED STREAM.MSG.GET, §13.6:1797-1799 —
275
+ * a fencing read whose stale follower miss would re-arm settled work) → LIVE;
276
+ * 5. else re-check the terminal (a commit may have landed since step 1), then re-enqueue the
277
+ * SAME acceptance-derived bytes create-only — the ONLY re-enqueueable state.
278
+ * Fail-closed preconditions: a DEL/PURGE marker on the lease REFUSES before any classification
279
+ * (reconciling over a deletion could recreate authoritative state), and whenever a lease record
280
+ * exists the caller-supplied `workExpiry` must EQUAL the persisted horizon (§13.8) — a mis-wired
281
+ * reconciliation never expires a live lease against a foreign horizon. */
282
+ export declare function reconcileWorkItem(ctx: WorkPoolContext, args: {
283
+ ref: WorkItemRef;
284
+ /** The acceptance-derived stored bytes (work identity + input only). */
285
+ itemBytes: Uint8Array;
286
+ /** From the item's AcceptanceFact — an absolute horizon a re-enqueue never resets. */
287
+ workExpiry: number;
288
+ now: number;
289
+ }): Promise<WorkReconcileVerdict>;
290
+ /** Settle a still-live pool item as `retired` for the §13.1 exact-pool cleaner. Unlike ordinary
291
+ * expiry reconciliation, retirement is target-bound and may settle unexpired work, but it still
292
+ * uses the lease key as the single arbiter: a racing commit, lease advance, or cleaner settlement
293
+ * all contend on this revision before any terminal fact is published. */
294
+ export declare function retireWorkItem(ctx: WorkPoolContext, args: {
295
+ ref: WorkItemRef;
296
+ workExpiry: number;
297
+ opId: string;
298
+ targetUid: string;
299
+ now: number;
300
+ }): Promise<{
301
+ won: boolean;
302
+ fact: WorkTerminalFact;
303
+ }>;
304
+ //# sourceMappingURL=endpoint-work.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"endpoint-work.d.ts","sourceRoot":"","sources":["../src/endpoint-work.ts"],"names":[],"mappings":"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"}