@cotal-ai/core 0.168.0 → 0.170.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 (118) hide show
  1. package/dist/agent-file.d.ts +9 -5
  2. package/dist/agent-file.d.ts.map +1 -1
  3. package/dist/agent-file.js +30 -17
  4. package/dist/agent-file.js.map +1 -1
  5. package/dist/anycast-requests.d.ts +8 -1
  6. package/dist/anycast-requests.d.ts.map +1 -1
  7. package/dist/anycast-requests.js +47 -0
  8. package/dist/anycast-requests.js.map +1 -1
  9. package/dist/backup-config.d.ts +5 -2
  10. package/dist/backup-config.d.ts.map +1 -1
  11. package/dist/backup-config.js +7 -2
  12. package/dist/backup-config.js.map +1 -1
  13. package/dist/backup.d.ts +6 -0
  14. package/dist/backup.d.ts.map +1 -1
  15. package/dist/backup.js +11 -4
  16. package/dist/backup.js.map +1 -1
  17. package/dist/connector-setup.d.ts +2 -0
  18. package/dist/connector-setup.d.ts.map +1 -1
  19. package/dist/connector.d.ts +8 -11
  20. package/dist/connector.d.ts.map +1 -1
  21. package/dist/control-exchange.d.ts +114 -0
  22. package/dist/control-exchange.d.ts.map +1 -0
  23. package/dist/control-exchange.js +416 -0
  24. package/dist/control-exchange.js.map +1 -0
  25. package/dist/endpoint-binding.d.ts.map +1 -1
  26. package/dist/endpoint-binding.js +2 -0
  27. package/dist/endpoint-binding.js.map +1 -1
  28. package/dist/endpoint-call.d.ts +2 -1
  29. package/dist/endpoint-call.d.ts.map +1 -1
  30. package/dist/endpoint-call.js +14 -7
  31. package/dist/endpoint-call.js.map +1 -1
  32. package/dist/endpoint-channel-discovery.d.ts +102 -0
  33. package/dist/endpoint-channel-discovery.d.ts.map +1 -0
  34. package/dist/endpoint-channel-discovery.js +170 -0
  35. package/dist/endpoint-channel-discovery.js.map +1 -0
  36. package/dist/endpoint-control-plane.d.ts +204 -0
  37. package/dist/endpoint-control-plane.d.ts.map +1 -0
  38. package/dist/endpoint-control-plane.js +627 -0
  39. package/dist/endpoint-control-plane.js.map +1 -0
  40. package/dist/endpoint-delivery-plane.d.ts +337 -0
  41. package/dist/endpoint-delivery-plane.d.ts.map +1 -0
  42. package/dist/endpoint-delivery-plane.js +1291 -0
  43. package/dist/endpoint-delivery-plane.js.map +1 -0
  44. package/dist/endpoint-durable-backstop.d.ts +249 -0
  45. package/dist/endpoint-durable-backstop.d.ts.map +1 -0
  46. package/dist/endpoint-durable-backstop.js +485 -0
  47. package/dist/endpoint-durable-backstop.js.map +1 -0
  48. package/dist/endpoint-envelope.d.ts +2 -1
  49. package/dist/endpoint-envelope.d.ts.map +1 -1
  50. package/dist/endpoint-envelope.js +9 -3
  51. package/dist/endpoint-envelope.js.map +1 -1
  52. package/dist/endpoint-history.d.ts +370 -0
  53. package/dist/endpoint-history.d.ts.map +1 -0
  54. package/dist/endpoint-history.js +969 -0
  55. package/dist/endpoint-history.js.map +1 -0
  56. package/dist/endpoint-inbound.d.ts +10 -0
  57. package/dist/endpoint-inbound.d.ts.map +1 -0
  58. package/dist/endpoint-inbound.js +28 -0
  59. package/dist/endpoint-inbound.js.map +1 -0
  60. package/dist/endpoint-liveness.d.ts +105 -0
  61. package/dist/endpoint-liveness.d.ts.map +1 -0
  62. package/dist/endpoint-liveness.js +223 -0
  63. package/dist/endpoint-liveness.js.map +1 -0
  64. package/dist/endpoint-messaging.d.ts +229 -0
  65. package/dist/endpoint-messaging.d.ts.map +1 -0
  66. package/dist/endpoint-messaging.js +420 -0
  67. package/dist/endpoint-messaging.js.map +1 -0
  68. package/dist/endpoint-presence.d.ts +15 -0
  69. package/dist/endpoint-presence.d.ts.map +1 -1
  70. package/dist/endpoint-presence.js +35 -0
  71. package/dist/endpoint-presence.js.map +1 -1
  72. package/dist/endpoint-serve.d.ts +11 -1
  73. package/dist/endpoint-serve.d.ts.map +1 -1
  74. package/dist/endpoint-serve.js +42 -5
  75. package/dist/endpoint-serve.js.map +1 -1
  76. package/dist/endpoint-subjects.d.ts +3 -0
  77. package/dist/endpoint-subjects.d.ts.map +1 -1
  78. package/dist/endpoint-subjects.js +3 -0
  79. package/dist/endpoint-subjects.js.map +1 -1
  80. package/dist/endpoint-subscriptions.d.ts +199 -0
  81. package/dist/endpoint-subscriptions.d.ts.map +1 -0
  82. package/dist/endpoint-subscriptions.js +543 -0
  83. package/dist/endpoint-subscriptions.js.map +1 -0
  84. package/dist/endpoint.d.ts +96 -344
  85. package/dist/endpoint.d.ts.map +1 -1
  86. package/dist/endpoint.js +518 -3854
  87. package/dist/endpoint.js.map +1 -1
  88. package/dist/index.d.ts +3 -1
  89. package/dist/index.d.ts.map +1 -1
  90. package/dist/index.js +5 -1
  91. package/dist/index.js.map +1 -1
  92. package/dist/launch-material.d.ts +9 -3
  93. package/dist/launch-material.d.ts.map +1 -1
  94. package/dist/launch-material.js +22 -2
  95. package/dist/launch-material.js.map +1 -1
  96. package/dist/provision-jwt.d.ts.map +1 -1
  97. package/dist/provision-jwt.js +1 -0
  98. package/dist/provision-jwt.js.map +1 -1
  99. package/dist/provision-permissions.d.ts +1 -1
  100. package/dist/provision-permissions.d.ts.map +1 -1
  101. package/dist/provision-permissions.js +10 -1
  102. package/dist/provision-permissions.js.map +1 -1
  103. package/dist/remote-manager-authority.d.ts +1 -1
  104. package/dist/run-host.d.ts +4 -1
  105. package/dist/run-host.d.ts.map +1 -1
  106. package/dist/run-journal.d.ts +2 -0
  107. package/dist/run-journal.d.ts.map +1 -1
  108. package/dist/run-journal.js +1 -1
  109. package/dist/run-journal.js.map +1 -1
  110. package/dist/run-record.d.ts +4 -0
  111. package/dist/run-record.d.ts.map +1 -1
  112. package/dist/run-record.js +36 -0
  113. package/dist/run-record.js.map +1 -1
  114. package/dist/space-quiescence-resources.d.ts +30 -0
  115. package/dist/space-quiescence-resources.d.ts.map +1 -0
  116. package/dist/space-quiescence-resources.js +45 -0
  117. package/dist/space-quiescence-resources.js.map +1 -0
  118. package/package.json +5 -1
@@ -0,0 +1,627 @@
1
+ // The control plane and service-invocation region of CotalEndpoint, as an internal component. Moved
2
+ // verbatim from endpoint.ts; the endpoint keeps the public methods and forwards to them. Not
3
+ // re-exported by the index.
4
+ import { randomUUID } from "node:crypto";
5
+ import { ClosedConnectionError } from "@nats-io/transport-node";
6
+ import { withDeadline } from "./deadline.js";
7
+ import { isFromSubjectSender } from "./endpoint.js";
8
+ import { resolveService, invokeCommand, goalFollowRefusal, submitAndFollowGoal, BIND_SPLIT_REISSUES } from "./endpoint-invoke.js";
9
+ import { EpEnvelopeError, respondedButUnbound, replyRefusedBeforeEffect, replyTargetUnmapped, EP_BIND_REFUSED } from "./endpoint-envelope.js";
10
+ import { isRepeatSafeCommand } from "./endpoint-grants.js";
11
+ import { REGISTRY_ENDPOINT, REGISTRY_ENDPOINTS_COMMAND } from "./registry-contract.js";
12
+ import { listRegistryEndpoints, registryListingCaller } from "./registry-client.js";
13
+ import { controlServiceSubject, parseSubject } from "./subjects.js";
14
+ /** The request/reply control plane of one endpoint (serve, answer and request control, with the
15
+ * bound reply every request rides) and its service-invocation client (describe, list, invoke,
16
+ * and follow a goal). Internal: `CotalEndpoint` keeps the public methods and forwards to it. */
17
+ export class EndpointControlPlane {
18
+ deps;
19
+ constructor(deps) {
20
+ this.deps = deps;
21
+ }
22
+ get nc() { return this.deps.nc(); }
23
+ get space() { return this.deps.space(); }
24
+ get owner() { return this.deps.owner(); }
25
+ get actor() { return this.deps.actor(); }
26
+ get stopped() { return this.deps.stopped(); }
27
+ get authed() { return this.deps.authed(); }
28
+ get connId() { return this.deps.connId(); }
29
+ get presentedExp() { return this.deps.presentedExp(); }
30
+ get issuedGeneration() { return this.deps.issuedGeneration(); }
31
+ get acceptedToken() { return this.deps.acceptedToken(); }
32
+ get rebuildPromise() { return this.deps.rebuildPromise(); }
33
+ get subs() { return this.deps.subs(); }
34
+ get resolvedServices() { return this.deps.resolvedServices(); }
35
+ get resolvedCommandServices() { return this.deps.resolvedCommandServices(); }
36
+ get serviceInvocations() { return this.deps.serviceInvocations(); }
37
+ get requestsAwaitingReply() { return this.deps.requestsAwaitingReply(); }
38
+ get activeGoalFollowers() { return this.deps.activeGoalFollowers(); }
39
+ get splitsRecovered() { return this.deps.splitsRecovered(); }
40
+ set splitsRecovered(count) { this.deps.setSplitsRecovered(count); }
41
+ notLiveMsg() { return this.deps.notLiveMsg(); }
42
+ requireLifecycleUid(what) { return this.deps.requireLifecycleUid(what); }
43
+ reportSubscriptionDenial(error) { return this.deps.reportSubscriptionDenial(error); }
44
+ ref() { return this.deps.ref(); }
45
+ reconnect() { return this.deps.reconnect(); }
46
+ emit(event, ...args) { return this.deps.emit(event, ...args); }
47
+ /** Serve control requests for a service. Returns the subscription so a caller that re-registers on
48
+ * reconnect (the delivery daemon) can drop the stale one. `boundReply` is REQUIRED for any service
49
+ * whose responder holds a wildcard publish grant over the service subtree (the delivery daemon's
50
+ * `ctl.delivery.*.*.reply.>`): without it, an authenticated caller could set its reply target to a
51
+ * PEER's reply lane (`ctl.delivery.<victim>.reply.<n>`) and turn the responder into a confused
52
+ * deputy — the broker does NOT permission-check the requester's embedded reply subject. With it, a
53
+ * reply is published only when `m.reply` is under the AUTHENTICATED request subject
54
+ * (`${m.subject}.reply.…`), binding the reply to the broker-policed sender token.
55
+ *
56
+ * Requests are answered one at a time, in arrival order. A request `concurrent` accepts is answered
57
+ * in its own time instead: it waits for none of the requests in front of it, including one still
58
+ * running, and holds up none behind it. Only for a request that shares no state with the service's
59
+ * other requests. */
60
+ serveControl(service, handler, opts = {}) {
61
+ if (!this.nc)
62
+ throw new Error(this.notLiveMsg());
63
+ const sub = this.nc.subscribe(controlServiceSubject(this.space, service, "*", "*"), {
64
+ queue: service,
65
+ });
66
+ this.subs.push(sub);
67
+ const inOwnTime = opts.concurrent;
68
+ // With `concurrent`, the in-order requests are answered one after another on this chain, and the
69
+ // reading below never waits on it, so a request answered in its own time is read and answered
70
+ // while an in-order one is still running.
71
+ let inOrder = Promise.resolve();
72
+ void (async () => {
73
+ for await (const m of sub) {
74
+ // Sender-bound reply guard (confused-deputy fix): never respond to a reply target outside the
75
+ // authenticated request subject's own `.reply.` subtree. Drop silently (don't inject elsewhere).
76
+ if (opts.boundReply && (!m.reply || !m.reply.startsWith(`${m.subject}.reply.`))) {
77
+ this.emit("error", new Error(`rejected ${service} request on ${m.subject}: reply target "${m.reply ?? "(none)"}" is not under the sender's own reply subtree`));
78
+ continue;
79
+ }
80
+ const answer = () => this.answerControl(service, handler, m);
81
+ if (inOwnTime === undefined) {
82
+ await answer();
83
+ continue;
84
+ }
85
+ let own = false;
86
+ try {
87
+ own = inOwnTime(m.json());
88
+ }
89
+ catch { /* unreadable: answered in order, as a refusal */ }
90
+ if (own)
91
+ void answer().catch((e) => this.emit("error", e));
92
+ else
93
+ inOrder = inOrder.then(answer).catch((e) => { this.emit("error", e); });
94
+ }
95
+ })().catch((e) => {
96
+ if (!this.reportSubscriptionDenial(e))
97
+ this.emit("error", e);
98
+ });
99
+ return sub;
100
+ }
101
+ /** Answer one control request for {@link serveControl}: the sender guard, the handler, and the reply. */
102
+ async answerControl(service, handler, m) {
103
+ let body;
104
+ try {
105
+ let reply;
106
+ const req = m.json();
107
+ // Authenticity guard (fail closed): control is the most privileged surface
108
+ // (start/stop). The sender is encoded in the subject (ctl.<svc>.<sender>), which
109
+ // the server policed who could publish; the payload `from` is advisory and must
110
+ // match. Reject before the handler acts on a request claiming a forged sender.
111
+ const parsed = parseSubject(m.subject);
112
+ if (!parsed || !isFromSubjectSender(req, parsed)) {
113
+ this.emit("error", new Error(`rejected control request on ${m.subject}: from ${req.from?.id ?? "(none)"} ` +
114
+ `does not match subject sender ${parsed?.sender ?? "(unparseable)"}`));
115
+ reply = { ok: false, error: "sender mismatch - request rejected" };
116
+ }
117
+ else {
118
+ reply = await handler(req);
119
+ }
120
+ body = JSON.stringify(reply);
121
+ }
122
+ catch (e) {
123
+ body = JSON.stringify({ ok: false, error: e.message });
124
+ }
125
+ try {
126
+ m.respond(body);
127
+ }
128
+ catch (e) {
129
+ // `respond` signals a missing reply inbox by returning false; it throws when the reply exceeds the
130
+ // broker's `max_payload`. Silence would leave the caller a bare timeout it cannot tell apart from
131
+ // a dead service.
132
+ const refused = { ok: false, error: `the ${service} reply is ${Buffer.byteLength(body)} bytes and was not published: ${e.message}` };
133
+ try {
134
+ m.respond(JSON.stringify(refused));
135
+ }
136
+ catch (err) {
137
+ this.emit("error", new Error(`could not answer ${service} request on ${m.subject}: ${refused.error}, and the refusal failed too: ${err.message}`));
138
+ }
139
+ }
140
+ }
141
+ /** Keep native named-reply and NoResponders handling, but settle when its connection closes:
142
+ * nats.js can close a no-mux subscription without settling its request. One close observer per
143
+ * connection avoids retaining a closed-promise callback for every completed request. */
144
+ async requestBoundReply(nc, subject, body, reply, timeoutMs) {
145
+ let pending = this.requestsAwaitingReply.get(nc);
146
+ if (!pending) {
147
+ const waiting = new Set();
148
+ this.requestsAwaitingReply.set(nc, waiting);
149
+ void nc.closed().then((error) => {
150
+ this.requestsAwaitingReply.delete(nc);
151
+ const failure = error ?? new ClosedConnectionError();
152
+ for (const reject of waiting)
153
+ reject(failure);
154
+ waiting.clear();
155
+ });
156
+ pending = waiting;
157
+ }
158
+ let rejectClosed;
159
+ const closed = new Promise((_resolve, reject) => {
160
+ rejectClosed = reject;
161
+ pending.add(reject);
162
+ });
163
+ try {
164
+ return await Promise.race([
165
+ nc.request(subject, body, { timeout: timeoutMs, noMux: true, reply }),
166
+ closed,
167
+ ]);
168
+ }
169
+ finally {
170
+ pending.delete(rejectClosed);
171
+ }
172
+ }
173
+ /** Send a control request to a service and await its reply (client side). Like {@link requestDelivery},
174
+ * the reply rides a BOUNDED subject UNDER the request subject (`ctl.<service>.<id>.reply.<uuid>`), not
175
+ * the per-id `_INBOX`.
176
+ * `noMux` lets us name the reply subject while keeping NoResponders detection. The random suffix is
177
+ * defense-in-depth (a predictable suffix would let a peer target an in-flight named reply sub). The
178
+ * reply sits under the sender's OWN request subject, so the responder's `boundReply` guard accepts it. */
179
+ async requestControl(service, req, timeoutMs = 5000) {
180
+ if (!this.nc)
181
+ throw new Error(this.notLiveMsg());
182
+ const reqSubject = controlServiceSubject(this.space, service, this.owner, this.actor);
183
+ const reply = `${reqSubject}.reply.${randomUUID()}`;
184
+ const body = { ...req, from: req.from ?? this.ref() };
185
+ const m = await this.requestBoundReply(this.nc, reqSubject, JSON.stringify(body), reply, timeoutMs);
186
+ return m.json();
187
+ }
188
+ /** The caller this connection's endpoint requests ride as: the legacy triple, or the issued
189
+ * caller with its discovered generation (SPEC 13.15). It names the reply rail this connection's
190
+ * credential reads, which is where a manager's turn notice for it lands (SPEC 14.3). */
191
+ serviceRailCaller() {
192
+ return this.serviceCaller();
193
+ }
194
+ /** This endpoint's v0.4 caller triple (§13.2) — the identity its minted ep-rail rows pin. The
195
+ * owner/actor principal is mode-correct by construction (static: DEV_OWNER + the connection
196
+ * identity; user mode: the bearer's callout-derived pair), and the lifecycle UID is the
197
+ * launcher-supplied incarnation the rows are keyed on (ledger-consistent: the §13.1 presence
198
+ * lifecycle-proof refuses a divergent uid before any publish). */
199
+ serviceCaller() {
200
+ const triple = { owner: this.owner, actor: this.actor, uid: this.requireLifecycleUid("invokeService") };
201
+ if (this.acceptedToken === undefined)
202
+ return triple;
203
+ if (this.issuedGeneration === undefined)
204
+ throw new Error("invokeService: the issued generation is not yet discovered on this connection");
205
+ return { ...triple, generation: this.issuedGeneration };
206
+ }
207
+ /** Follow this caller's goal on its standing connection, subscribing before submission.
208
+ * A submitter may use a separate short-lived control credential for the same caller triple;
209
+ * the accepted action's readiness budget can outlive that credential. This endpoint retains
210
+ * its existing credential renewal and caller-scoped progress grants. */
211
+ async followServiceGoal(endpoint, submit, deadlineMs = 10_000, opts = {}) {
212
+ if (!this.nc)
213
+ throw new Error(this.notLiveMsg());
214
+ if (this.stopped)
215
+ throw new Error("endpoint stopped - cannot follow goal");
216
+ const abortController = new AbortController();
217
+ const onAbort = () => abortController.abort();
218
+ if (opts.signal?.aborted)
219
+ onAbort();
220
+ else
221
+ opts.signal?.addEventListener("abort", onAbort, { once: true });
222
+ let reconnectHandler;
223
+ const entry = {
224
+ cancel: () => abortController.abort(),
225
+ reconnected: (nc) => reconnectHandler?.(nc),
226
+ };
227
+ this.activeGoalFollowers.add(entry);
228
+ try {
229
+ const reconcile = opts.reconcile ?? (async (goalId, _attributed, context) => {
230
+ const current = this.serviceCaller();
231
+ if (current.owner !== context.caller.owner || current.actor !== context.caller.actor || current.uid !== context.caller.uid)
232
+ throw new Error("the renewed goal reader no longer has the accepting caller's full identity");
233
+ // Static callers retain their authorized class route; knowing an instance id grants no rights.
234
+ const q = await this.invokeService(endpoint, "goal-result", { goalId }, {
235
+ deadlineMs: Math.min(deadlineMs, context.deadlineMs), signal: context.signal,
236
+ });
237
+ if (q.reply.ok !== true)
238
+ throw new Error(q.reply.error.message);
239
+ return q.reply.data;
240
+ });
241
+ return await submitAndFollowGoal(this.nc, this.space, endpoint, this.serviceCaller(), deadlineMs, submit, {
242
+ reconcile,
243
+ currentNc: () => this.nc,
244
+ onReconnect: (cb) => {
245
+ reconnectHandler = cb;
246
+ return () => { reconnectHandler = undefined; };
247
+ },
248
+ signal: abortController.signal,
249
+ prepare: opts.prepare,
250
+ });
251
+ }
252
+ finally {
253
+ opts.signal?.removeEventListener("abort", onAbort);
254
+ this.activeGoalFollowers.delete(entry);
255
+ }
256
+ }
257
+ /** Drop every cached handle for one endpoint after refresh or a currency split. */
258
+ clearResolvedService(endpoint) {
259
+ this.resolvedServices.delete(endpoint);
260
+ this.resolvedCommandServices.delete(endpoint);
261
+ }
262
+ /** Hold connection recovery through the whole pre-acceptance phase, including the progress
263
+ * subscription flush. Release on setup failure or the command's answer, never on goal terminal. */
264
+ beginServiceInvocation(nc) {
265
+ let pending = this.serviceInvocations.get(nc);
266
+ if (!pending) {
267
+ pending = new Set();
268
+ this.serviceInvocations.set(nc, pending);
269
+ }
270
+ let settle;
271
+ const request = new Promise((resolve) => { settle = resolve; });
272
+ pending.add(request);
273
+ return () => { pending.delete(request); settle(); };
274
+ }
275
+ async waitServiceRecovery(recovery, deadline, signal, timeout) {
276
+ let onAbort;
277
+ const cancelled = new Promise((_, reject) => {
278
+ onAbort = () => reject(signal?.reason);
279
+ if (signal?.aborted)
280
+ onAbort();
281
+ else
282
+ signal?.addEventListener("abort", onAbort, { once: true });
283
+ });
284
+ try {
285
+ await withDeadline(Promise.race([recovery, cancelled]), deadline - Date.now(), timeout);
286
+ }
287
+ finally {
288
+ if (onAbort)
289
+ signal?.removeEventListener("abort", onAbort);
290
+ }
291
+ signal?.throwIfAborted();
292
+ if (deadline <= Date.now())
293
+ throw timeout();
294
+ }
295
+ /** The resolved, digest-verified command surface of `endpoint` as this connection's caller sees
296
+ * it. Unpinned calls cache the complete discovery surface, and `refresh` drops both the full
297
+ * handle and any command-specific invocation handles. `instanceId` selects one instance without
298
+ * reading or populating either class cache, as a pinned invoke does. The caller's existing
299
+ * credential must permit that route. */
300
+ async describeService(endpoint, opts = {}) {
301
+ if (!this.nc)
302
+ throw new Error(this.notLiveMsg());
303
+ if (opts.refresh)
304
+ this.clearResolvedService(endpoint);
305
+ const cached = opts.instanceId === undefined ? this.resolvedServices.get(endpoint) : undefined;
306
+ if (cached)
307
+ return cached;
308
+ const svc = await resolveService(this.nc, this.space, endpoint, this.serviceCaller(), { deadlineMs: opts.deadlineMs ?? 10_000, signal: opts.signal, ...(opts.instanceId !== undefined ? { instanceId: opts.instanceId } : {}) });
309
+ if (opts.instanceId === undefined)
310
+ this.resolvedServices.set(endpoint, svc);
311
+ return svc;
312
+ }
313
+ /** The caller a registry listing rides (SPEC 13.15). An issued connection lists as itself. Any
314
+ * other connection reads the listing generation the issuer bound to the credential it presented,
315
+ * under the token its connection id and that credential's expiry derive. `undefined`: that
316
+ * credential carries no listing binding, because it predates listing issuance or has no expiry. */
317
+ async listingCaller() {
318
+ if (!this.nc)
319
+ throw new Error(this.notLiveMsg());
320
+ return registryListingCaller(this.nc, this.space, this.serviceCaller(), { connId: this.connId, ...(this.presentedExp !== undefined ? { exp: this.presentedExp } : {}) });
321
+ }
322
+ /** One page of the registry's `endpoints` answer (SPEC 13.20) over this connection
323
+ * ({@link listRegistryEndpoints}). The describe rides this connection's own caller; the question
324
+ * rides the listing caller on an authed mesh. `unbound`: this credential carries no listing
325
+ * binding. */
326
+ async listEndpoints(input, opts = {}) {
327
+ if (!this.nc)
328
+ throw new Error(this.notLiveMsg());
329
+ const nc = this.nc;
330
+ const listing = this.authed ? await this.listingCaller() : undefined;
331
+ if (this.authed && listing === undefined)
332
+ return { unbound: true };
333
+ return this.listEndpointsOver(nc, listing, input, opts);
334
+ }
335
+ /** Ask the registry over `nc` under `listing`: this connection, or another of this caller triple
336
+ * such as a manager-call connection. The describe rides this connection, whose view holds the
337
+ * registry's describe. Every endpoint the page lists has its cached describe dropped, so the next
338
+ * describe of it reads the surface afresh. `unbound`: the broker refused the question under
339
+ * `listing`, whose credential holds no listing row. */
340
+ async listEndpointsOver(nc, listing, input, opts = {}) {
341
+ if (!this.nc)
342
+ throw new Error(this.notLiveMsg());
343
+ const own = this.nc;
344
+ const result = await listRegistryEndpoints(this.space, (deadlineMs, signal) => resolveService(own, this.space, REGISTRY_ENDPOINT, this.serviceCaller(), {
345
+ deadlineMs, signal, commands: [REGISTRY_ENDPOINTS_COMMAND],
346
+ }), { nc, ...(listing ? { caller: listing } : {}) }, input, opts);
347
+ if (result.unbound)
348
+ return result;
349
+ for (const row of result.page?.rows ?? [])
350
+ this.clearResolvedService(row.endpoint);
351
+ return result;
352
+ }
353
+ /** GENERIC v0.4 service invoke over this endpoint's own connection: resolve
354
+ * the named endpoint's registered surface — describe, §13.7 store fetch, digest-verified
355
+ * recompile ({@link resolveService}; cached per endpoint name) — and invoke one command. The
356
+ * resolve is describe-bound currency, and a call that reaches the wrong incarnation is recovered
357
+ * two ways depending on WHO caught it — the difference between knowing the command did not run
358
+ * and only knowing someone answered:
359
+ * - the RESPONDER fenced it on the request's `bind` (§13.2, an `ok:false` reply marked
360
+ * {@link replyRefusedBeforeEffect}): the command did not run, so the bind is dropped and the
361
+ * call re-issued for any command, up to {@link BIND_SPLIT_REISSUES} times while each re-issue
362
+ * is refused the same way. If a re-issue cannot be resolved, the refusal
363
+ * surfaces — still saying the command did not run — naming the resolve failure as why the
364
+ * repair could not be attempted. An unpinned targeted call that reached a member holding no
365
+ * mapping for its target ({@link replyTargetUnmapped}) is repaired the same way, and when the
366
+ * re-issues run out, the latest such refusal is the one surfaced.
367
+ * - this CLIENT caught it on the reply ({@link respondedButUnbound}: a different instance,
368
+ * `failed-precondition`; the same instance at any other epoch, `expired`), which is what a
369
+ * responder too old to know the field produces. A live instance received and answered it, so
370
+ * the bind is dropped but the call is re-issued only for a command on the
371
+ * {@link isRepeatSafeCommand} allowlist; anything else surfaces, since a second attempt could
372
+ * duplicate its effect.
373
+ * A broker permission refusal marked `not-executed` rebuilds the connection and retries once
374
+ * within the original deadline. A second refusal stands. Responder errors and calls that may
375
+ * have run never trigger this repair.
376
+ * Errors from the responder come back structurally on the attributed reply
377
+ * (`reply.ok === false`); transport/validation refusals throw {@link EpEnvelopeError}. */
378
+ async invokeService(endpoint, command, args, opts = {}) {
379
+ const deadline = Date.now() + (opts.deadlineMs ?? 10_000);
380
+ const rebuilding = this.rebuildPromise;
381
+ if (rebuilding) {
382
+ await this.waitServiceRecovery(rebuilding, deadline, opts.signal, () => new EpEnvelopeError("deadline-exceeded", "the invocation deadline elapsed waiting for connection recovery", undefined, "not-executed"));
383
+ opts = { ...opts, deadlineMs: deadline - Date.now() };
384
+ }
385
+ const nc = this.nc;
386
+ if (!nc)
387
+ throw new Error(this.notLiveMsg());
388
+ try {
389
+ return await this.invokeServiceOnce(endpoint, command, args, opts, rebuilding ? deadline : undefined);
390
+ }
391
+ catch (e) {
392
+ if (!(e instanceof EpEnvelopeError) || e.code !== "permission-denied" || e.outcome !== "not-executed"
393
+ || deadline <= Date.now())
394
+ throw e;
395
+ opts.signal?.throwIfAborted();
396
+ const recovery = (async () => {
397
+ // Re-read the live set: calls admitted while earlier ones settle must keep their replies.
398
+ // The empty check and rebuild admission have no await between them. Later calls wait on
399
+ // rebuildPromise instead of publishing on the connection being replaced.
400
+ for (;;) {
401
+ opts.signal?.throwIfAborted();
402
+ if (deadline <= Date.now())
403
+ throw e;
404
+ const pending = this.serviceInvocations.get(nc);
405
+ if (!pending?.size)
406
+ break;
407
+ await Promise.allSettled([...pending]);
408
+ }
409
+ if (this.nc === nc)
410
+ await this.reconnect();
411
+ else
412
+ await this.rebuildPromise;
413
+ })();
414
+ await this.waitServiceRecovery(recovery, deadline, opts.signal, () => e);
415
+ this.clearResolvedService(endpoint);
416
+ return this.invokeServiceOnce(endpoint, command, args, { ...opts, deadlineMs: deadline - Date.now() }, deadline);
417
+ }
418
+ }
419
+ async invokeServiceOnce(endpoint, command, args, opts = {}, retryDeadline) {
420
+ if (!this.nc)
421
+ throw new Error(this.notLiveMsg());
422
+ const nc = this.nc;
423
+ const caller = this.serviceCaller();
424
+ const resolve = async (signal = opts.signal, deadlineMs = opts.deadlineMs ?? 10_000) => {
425
+ signal?.throwIfAborted();
426
+ if (retryDeadline !== undefined)
427
+ deadlineMs = Math.min(deadlineMs, retryDeadline - Date.now());
428
+ if (deadlineMs <= 0)
429
+ throw new EpEnvelopeError("deadline-exceeded", "the invocation deadline elapsed before resolve", undefined, "not-executed");
430
+ const needed = opts.follow ? [command, "goal-result"] : [command];
431
+ const classSelected = opts.instanceId === undefined && opts.classInstanceId === undefined;
432
+ const full = classSelected ? this.resolvedServices.get(endpoint) : undefined;
433
+ if (full && needed.every((name) => full.commands.has(name)))
434
+ return full;
435
+ const cacheKey = [...needed].sort().join("\u0000");
436
+ const commandCache = classSelected ? this.resolvedCommandServices.get(endpoint) : undefined;
437
+ const cached = commandCache?.get(cacheKey);
438
+ if (cached)
439
+ return cached;
440
+ const svc = await resolveService(nc, this.space, endpoint, caller, {
441
+ deadlineMs,
442
+ signal,
443
+ commands: needed,
444
+ ...(opts.follow && command !== "goal-result" ? { optionalCommands: ["goal-result"] } : {}),
445
+ ...(opts.instanceId !== undefined ? { instanceId: opts.instanceId } : {}),
446
+ ...(opts.classInstanceId !== undefined ? { classInstanceId: opts.classInstanceId } : {}),
447
+ });
448
+ // Pinned resolves never enter either class cache. Narrow unpinned handles stay in their own
449
+ // command-set cache, so they cannot truncate discovery or evict another command's handle.
450
+ if (classSelected) {
451
+ let byCommand = this.resolvedCommandServices.get(endpoint);
452
+ if (!byCommand) {
453
+ byCommand = new Map();
454
+ this.resolvedCommandServices.set(endpoint, byCommand);
455
+ }
456
+ byCommand.set(cacheKey, svc);
457
+ }
458
+ return svc;
459
+ };
460
+ const invokeOpts = { ...(opts.target ? { target: opts.target } : {}), ...(opts.deadlineMs !== undefined ? { deadlineMs: opts.deadlineMs } : {}) };
461
+ const invokeResolved = (service, signal) => {
462
+ signal?.throwIfAborted();
463
+ const unfollowable = opts.follow ? goalFollowRefusal(service) : undefined;
464
+ if (unfollowable)
465
+ return Promise.resolve(unfollowable);
466
+ const deadlineMs = retryDeadline === undefined ? invokeOpts.deadlineMs : retryDeadline - Date.now();
467
+ if (deadlineMs !== undefined && deadlineMs <= 0)
468
+ throw new EpEnvelopeError("deadline-exceeded", "the invocation deadline elapsed before publish", undefined, "not-executed");
469
+ return invokeCommand(nc, this.space, service, command, args, { ...invokeOpts, deadlineMs, signal });
470
+ };
471
+ // A `failed-precondition` from the resolve is its own refusal, raised before any command was
472
+ // published, so resolving once more is a repair. The repair spends what is left of the same
473
+ // deadline, and with nothing left the refusal stands.
474
+ const resolveFirst = async (signal = opts.signal, deadline = Date.now() + (opts.deadlineMs ?? 10_000)) => {
475
+ try {
476
+ return await resolve(signal, deadline - Date.now());
477
+ }
478
+ catch (e) {
479
+ if (!(e instanceof EpEnvelopeError) || e.code !== "failed-precondition")
480
+ throw e;
481
+ const left = deadline - Date.now();
482
+ if (left <= 0)
483
+ throw e;
484
+ return await resolve(signal, left);
485
+ }
486
+ };
487
+ const doInvoke = async (service, signal = opts.signal) => {
488
+ signal?.throwIfAborted();
489
+ try {
490
+ let r = await invokeResolved(service, signal);
491
+ // THE RESPONDER FENCED IT (§13.2 `ai.cotal.ep.bind-refused`): a class member saw the call
492
+ // was bound to a different incarnation and refused BEFORE running the command.
493
+ //
494
+ // Handled here rather than below because it arrives as an ordinary `ok:false` REPLY, not a
495
+ // throw, so the `respondedButUnbound` recovery never sees it — a long-lived client would
496
+ // otherwise keep its stale bind and meet the same refusal forever.
497
+ //
498
+ // The re-issue is NOT gated on {@link isRepeatSafeCommand}: the responder states the command
499
+ // did not run, so each re-issue is a FIRST attempt, not a second. It repeats up to the bound
500
+ // the CLI uses, because the re-issue rides the same class queue and splits again at the same
501
+ // rate; repairing once left a quarter of all calls in a two-manager space failing (#443).
502
+ // A member that holds no mapping for the target also ran nothing, and on the class rail a
503
+ // sibling may host it. A pinned call named its instance, so that refusal is its answer.
504
+ // That member looked the target up, so when the re-issues run out its refusal is surfaced
505
+ // in place of a trailing bind refusal, which says nothing about the target.
506
+ const unmappedHere = (x) => opts.instanceId === undefined && replyTargetUnmapped(x.reply.error);
507
+ let unmapped = unmappedHere(r) ? r : undefined;
508
+ for (let reissues = 0; reissues < BIND_SPLIT_REISSUES && r.reply.ok === false
509
+ && (replyRefusedBeforeEffect(r.reply.error) || unmappedHere(r)); reissues++) {
510
+ // Counted before it is repaired: a recovery that leaves no trace takes the split rate with it.
511
+ this.splitsRecovered++;
512
+ // `boundTo` is the other half of `servedBy`: who the handle THOUGHT it was talking to,
513
+ // against who actually answered. Without it a listener sees that a split was recovered
514
+ // but not which bind went stale, so it cannot tell one handle's repeated staleness from
515
+ // splits spread across many — and that is the difference between a handle to drop and a
516
+ // class that is churning.
517
+ this.emit("split-recovered", {
518
+ endpoint, command, servedBy: r.responder, splitsRecovered: this.splitsRecovered,
519
+ boundTo: (r.reply.error.details ?? []).find((d) => d.kind === EP_BIND_REFUSED)?.boundTo,
520
+ });
521
+ this.clearResolvedService(endpoint);
522
+ // A FAILED RE-ISSUE RETHROWS THE ORIGINAL REFUSAL, not the resolve error: if the endpoint
523
+ // has since retired, the resolve times out and the caller would otherwise get `no describe
524
+ // reply within 10000ms` — about a describe it never asked for — losing the one fact that
525
+ // says its handle is stale AND that nothing ran. The resolve failure is named as the
526
+ // reason the repair could not be attempted.
527
+ //
528
+ // The code must be the refusal's own (`failed-precondition` for a different instance,
529
+ // `expired` for the same instance at ANY other epoch — the fence does not compare
530
+ // direction, so a superseded incarnation still answering produces it too); the marker on
531
+ // any other code is incoherent, so it is rejected rather than trusted (§13.3).
532
+ const raw = r.reply.error.code;
533
+ const refusalCode = raw === "expired" ? "expired"
534
+ : raw === "failed-precondition" ? "failed-precondition" : undefined;
535
+ if (refusalCode === undefined)
536
+ throw new EpEnvelopeError("internal", `${endpoint}.${command} came back marked as refused before it ran, but with code ${String(raw)}; the fence produces only failed-precondition or expired (SPEC 13.2)`, r.reply.error.details);
537
+ // ONLY THE RESOLVE IS WRAPPED — do not widen this `try` to cover the re-issue. A re-issue
538
+ // that PUBLISHED AND RAN can still throw (an unfenced responder answers and the post-reply
539
+ // currency check raises `respondedButUnbound`); wrapping that as the first hop's refusal
540
+ // would hand the caller `WAS NOT RUN` for a command that executed, and its next attempt
541
+ // would be a second one believing it was the first. A re-issue that fails on its own terms
542
+ // must propagate its OWN error, because `respondedButUnbound` asserts the opposite of what
543
+ // the fence's marker does: a responder answered and the effect may have landed.
544
+ let reissueTarget;
545
+ try {
546
+ reissueTarget = await resolve(signal);
547
+ const unfollowable = opts.follow ? goalFollowRefusal(reissueTarget) : undefined;
548
+ if (unfollowable)
549
+ throw new Error(unfollowable.reply.error.message);
550
+ }
551
+ catch (reissue) {
552
+ throw new EpEnvelopeError(refusalCode, `${endpoint}.${command} WAS NOT RUN - the incarnation that received it refused it before any effect, and the re-issue could not be resolved: ${reissue instanceof Error ? reissue.message : String(reissue)}. Re-resolve and re-issue when the endpoint is reachable (SPEC 13.2)`, r.reply.error.details,
553
+ // §13.3: the message asserts the command did not run, so the FIELD a caller keys on
554
+ // must assert it too. Omitted, it MUST be read as `unknown`, which is the opposite of
555
+ // what this path knows: the responder fenced the call before any effect and the
556
+ // re-issue never went out. Prose is for the reader; this is for the machine.
557
+ "not-executed");
558
+ }
559
+ r = await invokeResolved(reissueTarget, signal);
560
+ if (unmappedHere(r))
561
+ unmapped = r;
562
+ }
563
+ return replyRefusedBeforeEffect(r.reply.error) ? unmapped ?? r : r;
564
+ }
565
+ catch (e) {
566
+ // DO NOT auto-retry a command a responder already ANSWERED. This path covers the responders
567
+ // WITHOUT the fence above: they ignore `bind`, run the command, and the error is raised
568
+ // afterwards, so core cannot tell a repair from a duplicate and the allowlist is the only
569
+ // guard left. (`failed-precondition` here is not only supersession — it also fires when a
570
+ // DIFFERENT live instance wins the class queue and replies, an ordinary split.)
571
+ //
572
+ // Dropping the retry outright is not an option: in a two-manager space roughly half of all
573
+ // class-queue calls split, so every other `ps` would surface an error this absorbs, and
574
+ // re-running a read costs nothing.
575
+ //
576
+ // So it is gated on an ALLOWLIST (`REPEAT_SAFE_COMMANDS`), keyed by ENDPOINT because this
577
+ // method is endpoint-agnostic. Polarity matters more than membership: an allowlist fails
578
+ // CLOSED. Not a `GOAL_BEARING_COMMANDS`-only gate — `purge` is neither goal-bearing nor
579
+ // convergent, and its second run deletes messages published after the first completed, so
580
+ // the boundary is "changes anything", which core cannot see: commands carry no idempotency
581
+ // declaration and every manager command shares `class: "ephemeral"`.
582
+ //
583
+ // Keyed on the MARKER, not the error code, because the same fact has two producers: a
584
+ // DIFFERENT instance answering (`failed-precondition`) and the SAME instance at ANY OTHER
585
+ // EPOCH (`expired`) — epoch inequality, not "a successor", so a superseded incarnation
586
+ // still answering produces it too. Same rule for both, or a long-lived client stays bound
587
+ // to a dead epoch while every call reaches whoever is actually there.
588
+ if (respondedButUnbound(e)) {
589
+ // Drop the stale bind FIRST, whichever way this goes: it names an incarnation that is not
590
+ // the one answering, so every later call would reuse it and meet the same refusal. This is
591
+ // not a retry — nothing is re-issued by it, and for a command that is not repeat-safe the
592
+ // next call is the caller's, made after it has verified.
593
+ this.clearResolvedService(endpoint);
594
+ if (!isRepeatSafeCommand(endpoint, command))
595
+ throw e;
596
+ return await invokeResolved(await resolve(signal), signal);
597
+ }
598
+ throw e;
599
+ }
600
+ };
601
+ // A goal-bearing command (spawn/launch) follows its acceptance to the terminal so
602
+ // the caller still returns on the real outcome (UX unchanged); every other command replies directly.
603
+ const release = this.beginServiceInvocation(nc);
604
+ try {
605
+ if (!opts.follow)
606
+ return await doInvoke(await resolveFirst());
607
+ // Resolve and confirm observation before submission. Hold the barrier continuously across
608
+ // both phases, then release when the command answers so accepted goals can outlive recovery.
609
+ let service;
610
+ return await this.followServiceGoal(endpoint, async (signal) => {
611
+ try {
612
+ return await doInvoke(service, signal);
613
+ }
614
+ finally {
615
+ release();
616
+ }
617
+ }, opts.deadlineMs ?? 10_000, {
618
+ signal: opts.signal,
619
+ prepare: async (signal, deadline) => { service = await resolveFirst(signal, deadline); },
620
+ });
621
+ }
622
+ finally {
623
+ release();
624
+ }
625
+ }
626
+ }
627
+ //# sourceMappingURL=endpoint-control-plane.js.map