@cotal-ai/core 0.171.4 → 0.171.5

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 (35) hide show
  1. package/dist/control-exchange.d.ts.map +1 -1
  2. package/dist/control-exchange.js +3 -4
  3. package/dist/control-exchange.js.map +1 -1
  4. package/dist/endpoint-anycast.d.ts +110 -0
  5. package/dist/endpoint-anycast.d.ts.map +1 -0
  6. package/dist/endpoint-anycast.js +316 -0
  7. package/dist/endpoint-anycast.js.map +1 -0
  8. package/dist/endpoint-consumers.d.ts +147 -0
  9. package/dist/endpoint-consumers.d.ts.map +1 -0
  10. package/dist/endpoint-consumers.js +459 -0
  11. package/dist/endpoint-consumers.js.map +1 -0
  12. package/dist/endpoint-dial.d.ts +3 -1
  13. package/dist/endpoint-dial.d.ts.map +1 -1
  14. package/dist/endpoint-dial.js +5 -2
  15. package/dist/endpoint-dial.js.map +1 -1
  16. package/dist/endpoint-durable.d.ts +82 -0
  17. package/dist/endpoint-durable.d.ts.map +1 -0
  18. package/dist/endpoint-durable.js +164 -0
  19. package/dist/endpoint-durable.js.map +1 -0
  20. package/dist/endpoint-principal-serve.d.ts +110 -0
  21. package/dist/endpoint-principal-serve.d.ts.map +1 -0
  22. package/dist/endpoint-principal-serve.js +233 -0
  23. package/dist/endpoint-principal-serve.js.map +1 -0
  24. package/dist/endpoint.d.ts +30 -189
  25. package/dist/endpoint.d.ts.map +1 -1
  26. package/dist/endpoint.js +201 -1089
  27. package/dist/endpoint.js.map +1 -1
  28. package/dist/launch-artifacts.d.ts.map +1 -1
  29. package/dist/launch-artifacts.js +17 -9
  30. package/dist/launch-artifacts.js.map +1 -1
  31. package/dist/websocket-dial.d.ts +9 -0
  32. package/dist/websocket-dial.d.ts.map +1 -0
  33. package/dist/websocket-dial.js +121 -0
  34. package/dist/websocket-dial.js.map +1 -0
  35. package/package.json +1 -1
package/dist/endpoint.js CHANGED
@@ -3,37 +3,38 @@ export { MULTI_FILTER_BATCH, MULTI_FILTER_READ_CONCURRENCY } from "./endpoint-hi
3
3
  import { nativeBindingAfter } from "./native-connection.js";
4
4
  import { EventEmitter } from "node:events";
5
5
  import { randomUUID } from "node:crypto";
6
- import { nanos, PermissionViolationError, NoRespondersError, RequestError, TimeoutError, } from "@nats-io/transport-node";
6
+ import { PermissionViolationError, RequestError, TimeoutError, } from "@nats-io/transport-node";
7
7
  import { responderFromLease, responderFromProbe, } from "./liveness.js";
8
8
  import { EndpointPresence } from "./endpoint-presence.js";
9
9
  export { PresenceWriteStuckError } from "./endpoint-presence.js";
10
10
  import { idFromCreds } from "./identity.js";
11
- import { withDeadline } from "./deadline.js";
12
11
  import {} from "./secret-store.js";
13
12
  import { BIND_SPLIT_REISSUES, resolveService } from "./endpoint-invoke.js";
14
13
  import { EpEnvelopeError, respondedButUnbound, replyRefusedBeforeEffect, replyTargetUnmapped } from "./endpoint-envelope.js";
15
14
  import { isRepeatSafeCommand } from "./endpoint-grants.js";
16
15
  import { assertGeneration, assertRuntimeToken, endpointToken } from "./endpoint-subjects.js";
17
- import { servePrincipalRoute, describeContracts } from "./endpoint-serve.js";
16
+ import {} from "./endpoint-serve.js";
18
17
  import { epPrincipalCall } from "./endpoint-call.js";
19
- import { AGENT_CLUSTER, AGENT_CONTRACTS, AGENT_ENDPOINT } from "./agent-endpoint.js";
18
+ import { AGENT_CLUSTER, AGENT_ENDPOINT } from "./agent-endpoint.js";
20
19
  import { processRuntime } from "./process-runtime.js";
21
20
  import { issuedPermitsSubject } from "./issued-authority.js";
22
21
  import { listRegistryEndpoints } from "./registry-client.js";
23
- import { isConsumerNotFound, isJetStreamMissing, isStreamNotFound } from "./jetstream-missing.js";
22
+ import { isJetStreamMissing } from "./jetstream-missing.js";
24
23
  import { assertValidKind } from "./agent-file.js";
25
24
  import { assertValidName } from "./resolve.js";
26
- import { anycastStoreDefinition, taskDurableConfig } from "./streams.js";
27
- import { jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, } from "@nats-io/jetstream";
25
+ import { JetStreamApiCodes, } from "@nats-io/jetstream";
28
26
  import {} from "@nats-io/jetstream";
29
- import { Kvm } from "@nats-io/kv";
27
+ import {} from "@nats-io/kv";
30
28
  import { listMembers } from "./members.js";
31
- import { readAcl } from "./acls.js";
32
29
  import { EndpointDeliveryLease } from "./endpoint-delivery-lease.js";
33
30
  import { EndpointDeliveryPlane } from "./endpoint-delivery-plane.js";
34
31
  import { EndpointControlPlane } from "./endpoint-control-plane.js";
35
32
  import { EndpointMessaging, assertPartsSerializable } from "./endpoint-messaging.js";
36
33
  import { EndpointDurableBackstop } from "./endpoint-durable-backstop.js";
34
+ import { EndpointDurable } from "./endpoint-durable.js";
35
+ import { EndpointAnycast } from "./endpoint-anycast.js";
36
+ import { EndpointConsumers } from "./endpoint-consumers.js";
37
+ import { EndpointPrincipalServe } from "./endpoint-principal-serve.js";
37
38
  import { EndpointSubscriptions, membershipConsumerReleased } from "./endpoint-subscriptions.js";
38
39
  import { EndpointChannelDiscovery } from "./endpoint-channel-discovery.js";
39
40
  import { EndpointLiveness } from "./endpoint-liveness.js";
@@ -42,23 +43,19 @@ import { EndpointReconnect } from "./endpoint-reconnect.js";
42
43
  import { EndpointConnection } from "./endpoint-connection.js";
43
44
  import { EndpointProvisioning } from "./endpoint-provisioning.js";
44
45
  import { EndpointBootMemberships } from "./endpoint-boot-memberships.js";
45
- import { ackWaitOf, durableDelivery, isRecord } from "./endpoint-inbound.js";
46
+ import { isRecord } from "./endpoint-inbound.js";
46
47
  import { effectiveReplay, effectiveReplayWindowMs, readChannelConfig, readChannelDefaults, } from "./channels.js";
47
48
  import { isCasLoss } from "./endpoint-records.js";
48
- import { ANYCAST_CANCEL_OP, ANYCAST_NOTICE_KEY, ANYCAST_RECORDS_CREDENTIAL_OUTDATED, ANYCAST_STATUS_OP, ANYCAST_TAKES_OP, AnycastRequestAuthority, isAnycastSeq, } from "./anycast-requests.js";
49
- import { assertValidRole, chatStream, chatSubject, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, membershipInAllow, isConcreteChannel, isChannelFamily, MENTION_NOTICE_KEY, parseSubject, isPrincipalOwnerToken, assertInboxConnId, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, takeServeFilter, takeSubject, parseTakeSubject, TAKE_ROUTE, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
49
+ import { AnycastRequestAuthority, } from "./anycast-requests.js";
50
+ import { assertValidRole, chatStream, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, isConcreteChannel, isChannelFamily, parseSubject, assertInboxConnId, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, DEV_OWNER, spaceWildcard, subjectMatches, unicastSubject, unicastRecvFilter, } from "./subjects.js";
50
51
  import { isPermissionDenied } from "./permission-denied.js";
51
52
  export { isPermissionDenied };
52
53
  import { DEFAULT_SERVER, isPublishPermissionDenied, isAuthRejection, kvWatchConsumer, decodeBearerPrincipal, RepeatedRefusal, describeStatusError, } from "./endpoint-dial.js";
53
54
  export { DEFAULT_SERVER, isPublishPermissionDenied, wsServers, defaultProbeTimeoutMs, dialerFor, isAuthRejection, isReachable, probeConnect, } from "./endpoint-dial.js";
54
- import { MAX_TIMER_MS, ANYCAST_SWEEP_MS, MAX_TAKES_IN_FLIGHT, ANYCAST_TAKE_TIMEOUT_MS, DmDurableMissingError, DmBindRefusedError, } from "./endpoint-options.js";
55
+ import { MAX_TIMER_MS, } from "./endpoint-options.js";
55
56
  export { deliveryLimitOf, DEFAULT_SPACE, DmDurableMissingError, DmBindRefusedError, fitHistoryPage, } from "./endpoint-options.js";
56
- import { historyMessageFromDelivery, isUsableMessageId, isFromSubjectSender, authenticatedMessage, isReadableMessagePart, kindFromParsed, dmOnlyDelivery, } from "./endpoint-messages.js";
57
+ import { historyMessageFromDelivery, isUsableMessageId, isFromSubjectSender, authenticatedMessage, isReadableMessagePart, } from "./endpoint-messages.js";
57
58
  export { isFromSubjectSender, } from "./endpoint-messages.js";
58
- /** The highest `prompts` presence `seq` this process used under each runtime id (SPEC §6). A reader
59
- * orders lists by `seq` within one `runtime.id`, and a runtime id lives as long as the process, so
60
- * this does too: across a stopped serve, a stopped endpoint and a new endpoint for the lifecycle. */
61
- const promptsSeqs = new Map();
62
59
  /** The principal endpoint each `{space, runtime id, endpoint}` is served by in this process. Two
63
60
  * would subscribe the same subject and both answer one request (SPEC 13.21). */
64
61
  const principalServers = new Map();
@@ -188,16 +185,16 @@ export class CotalEndpoint extends EventEmitter {
188
185
  serveControl: (...args) => this.serveControl(...args),
189
186
  aclRegistry: (...args) => this.aclRegistry(...args),
190
187
  membersRegistry: (...args) => this.membersRegistry(...args),
191
- armAnycastRequests: (...args) => this.armAnycastRequests(...args),
192
- deliveryAnycast: (...args) => this.deliveryAnycast(...args),
193
- dropAnycastRequests: (...args) => this.dropAnycastRequests(...args),
188
+ armAnycastRequests: (...args) => this.anycastRail.armAnycastRequests(...args),
189
+ deliveryAnycast: (...args) => this.anycastRail.deliveryAnycast(...args),
190
+ dropAnycastRequests: (...args) => this.anycastRail.dropAnycastRequests(...args),
194
191
  manager: (...args) => this.manager(...args),
195
192
  notLiveMsg: (...args) => this.notLiveMsg(...args),
196
- plane3MsgId: (...args) => this.plane3MsgId(...args),
197
- publishDinbox: (...args) => this.publishDinbox(...args),
198
- resolveOwnerByName: (...args) => this.resolveOwnerByName(...args),
199
- scheduleResidentSwap: (...args) => this.scheduleResidentSwap(...args),
200
- sendMentionNotice: (...args) => this.sendMentionNotice(...args),
193
+ plane3MsgId: (...args) => this.durableBackstop.plane3MsgId(...args),
194
+ publishDinbox: (...args) => this.durableBackstop.publishDinbox(...args),
195
+ resolveOwnerByName: (...args) => this.durableBackstop.resolveOwnerByName(...args),
196
+ scheduleResidentSwap: (...args) => this.credentials.scheduleResidentSwap(...args),
197
+ sendMentionNotice: (...args) => this.anycastRail.sendMentionNotice(...args),
201
198
  emit: (event, ...args) => this.emit(event, ...args),
202
199
  });
203
200
  /** The anycast take responder, the request records it writes, and their maintenance timer
@@ -234,7 +231,7 @@ export class CotalEndpoint extends EventEmitter {
234
231
  notLiveMsg: () => this.notLiveMsg(),
235
232
  requireLifecycleUid: (operation) => this.requireLifecycleUid(operation),
236
233
  requestDelivery: (op, args) => this.requestDelivery(op, args),
237
- deleteConsumerIfPresent: (stream, name) => this.deleteConsumerIfPresent(stream, name),
234
+ deleteConsumerIfPresent: (stream, name) => this.consumers.deleteConsumerIfPresent(stream, name),
238
235
  joinPolicyFresh: (channel) => this.joinPolicyFresh(channel),
239
236
  chatMayHaveLost: (subject, sinceSeq) => this.chatMayHaveLost(subject, sinceSeq),
240
237
  emit: (event, ...args) => this.emit(event, ...args),
@@ -252,7 +249,7 @@ export class CotalEndpoint extends EventEmitter {
252
249
  * reported itself connected again. */
253
250
  taps = [];
254
251
  /** The liveness responders {@link serveLiveness} was asked for, by plane. This is INTENT, re-bound
255
- * by {@link bindLiveness} on every (re)connect: a rebuild closes the old connection and every
252
+ * by {@link EndpointLiveness.bindLiveness} on every (re)connect: a rebuild closes the old connection and every
256
253
  * subscription on it, so a responder bound once would leave its plane to the broker's
257
254
  * no-responders answer, which a peer grades `unbound`, while this endpoint is connected and serving. */
258
255
  livenessResponders = new Map();
@@ -279,7 +276,7 @@ export class CotalEndpoint extends EventEmitter {
279
276
  * so this in-memory mirror is kept, not rebuilt. Cleared only on full stop. */
280
277
  plane3Channels = new Map();
281
278
  /** Channels whose live sub was REFUSED while they held a Plane-3 durable membership, whose §7
282
- * tombstone has not yet confirmed (channel → join generation). {@link closeRefusedMembership} retries
279
+ * tombstone has not yet confirmed (channel → join generation). {@link EndpointDurable.closeRefusedMembership} retries
283
280
  * the tombstone until it lands; until then this is a `durable-unclosed` state surfaced via
284
281
  * {@link pendingDurableLeaves} (the connector shows it in `cotal_channels`, never as ordinary
285
282
  * absence). Persists across reconnect; cleared on tombstone success or full stop. */
@@ -292,7 +289,7 @@ export class CotalEndpoint extends EventEmitter {
292
289
  pendingBootJoins = new Set();
293
290
  /** The refusals a channel's live subscription callback received. nats.js hands a subscription
294
291
  * refusal to the refused subscription's callback and then dispatches that same instance on the
295
- * connection status, so the callback owns it (see {@link subscribeChat}) and watchStatus skips it. */
292
+ * connection status, so the callback owns it (see {@link EndpointConsumers.subscribeChat}) and watchStatus skips it. */
296
293
  chatSubRefusals = new WeakSet();
297
294
  /** Service iterators and connection status can receive the same subscription denial. */
298
295
  reportedSubRefusals = new WeakSet();
@@ -340,7 +337,7 @@ export class CotalEndpoint extends EventEmitter {
340
337
  /** Bumped by every connection-scoped teardown and by {@link stop}. A presence or lease-watch bind
341
338
  * that was awaiting the broker when the epoch moved belongs to a retired epoch: it releases the
342
339
  * iterator it got and installs nothing (see {@link startPresenceWatch} and
343
- * {@link bindDeliveryLeaseWatch}). */
340
+ * {@link EndpointDeliveryLease.bindDeliveryLeaseWatch}). */
344
341
  presenceEpoch = 0;
345
342
  stopped = false;
346
343
  stopPromise;
@@ -365,7 +362,7 @@ export class CotalEndpoint extends EventEmitter {
365
362
  * now instead of awaiting the full retryMs. */
366
363
  backoffResolve;
367
364
  backoffTimer;
368
- /** Wakes for the membership retry loops' pauses (see {@link membershipPause}); stop() runs them all. */
365
+ /** Wakes for the membership retry loops' pauses (see {@link EndpointReconnect.membershipPause}); stop() runs them all. */
369
366
  membershipPauses = new Set();
370
367
  retryMs = 3000;
371
368
  /** Consecutive failed rebuilds, driving {@link nextRetryDelayMs}. Reset on every success. */
@@ -707,18 +704,6 @@ export class CotalEndpoint extends EventEmitter {
707
704
  refreshBearer(initial = false) {
708
705
  return this.credentials.refreshBearer(initial);
709
706
  }
710
- /** Forwards to the credentials component's {@link EndpointCredentials.bearerForWire}. */
711
- bearerForWire() {
712
- return this.credentials.bearerForWire();
713
- }
714
- /** Forwards to the credentials component's {@link EndpointCredentials.presentCreds}. */
715
- presentCreds() {
716
- return this.credentials.presentCreds();
717
- }
718
- /** Forwards to the credentials component's {@link EndpointCredentials.presentBearer}. */
719
- presentBearer() {
720
- return this.credentials.presentBearer();
721
- }
722
707
  /** The credential this endpoint presents on its next connect, checked as {@link credsForWire}
723
708
  * checks it. A second connection under the same identity reads it on every attempt, so it
724
709
  * presents each credential this endpoint adopts and never an expired one. */
@@ -729,18 +714,10 @@ export class CotalEndpoint extends EventEmitter {
729
714
  disableLibraryReconnect(nc) {
730
715
  return this.credentials.disableLibraryReconnect(nc);
731
716
  }
732
- /** Forwards to the credentials component's {@link EndpointCredentials.closeWithoutLibraryReconnect}. */
733
- closeWithoutLibraryReconnect(nc) {
734
- return this.credentials.closeWithoutLibraryReconnect(nc);
735
- }
736
717
  /** Forwards to the credentials component's {@link EndpointCredentials.armAuthExpiryReconnectFence}. */
737
718
  armAuthExpiryReconnectFence(nc) {
738
719
  return this.credentials.armAuthExpiryReconnectFence(nc);
739
720
  }
740
- /** Forwards to the credentials component's {@link EndpointCredentials.refreshCreds}. */
741
- refreshCreds(initial = false) {
742
- return this.credentials.refreshCreds(initial);
743
- }
744
721
  /** Forwards to the credentials component's {@link EndpointCredentials.renewCredsOnTimer}. */
745
722
  renewCredsOnTimer() {
746
723
  return this.credentials.renewCredsOnTimer();
@@ -771,10 +748,6 @@ export class CotalEndpoint extends EventEmitter {
771
748
  reloadCreds(expected) {
772
749
  return this.credentials.reloadCreds(expected);
773
750
  }
774
- /** Forwards to the credentials component's {@link EndpointCredentials.scheduleResidentSwap}. */
775
- scheduleResidentSwap() {
776
- return this.credentials.scheduleResidentSwap();
777
- }
778
751
  armCredsRefresh(delayMs) {
779
752
  if (this.stopped)
780
753
  return;
@@ -790,7 +763,7 @@ export class CotalEndpoint extends EventEmitter {
790
763
  }
791
764
  /** Open the connection and bind everything that hangs off it: status watch, presence
792
765
  * watch + heartbeat, channel registry, and the durable consumers. Re-runnable — a
793
- * reconnect calls it again after {@link clearConnectionScoped}; every binding is
766
+ * reconnect calls it again after {@link EndpointConnection.clearConnectionScoped}; every binding is
794
767
  * idempotent (durables bind by name, JetStream dedups by msgID, KV opens are idempotent). */
795
768
  async connectAndBind() {
796
769
  try {
@@ -909,52 +882,48 @@ export class CotalEndpoint extends EventEmitter {
909
882
  residentSwap: () => this.residentSwap,
910
883
  nativeBound: () => this.nativeBound,
911
884
  refreshBearer: (initial) => this.refreshBearer(initial),
912
- refreshCreds: (initial) => this.refreshCreds(initial),
913
- bearerForWire: () => this.bearerForWire(),
914
- presentCreds: () => this.presentCreds(),
915
- presentBearer: () => this.presentBearer(),
885
+ refreshCreds: (initial) => this.credentials.refreshCreds(initial),
886
+ bearerForWire: () => this.credentials.bearerForWire(),
887
+ presentCreds: () => this.credentials.presentCreds(),
888
+ presentBearer: () => this.credentials.presentBearer(),
916
889
  armAuthExpiryReconnectFence: (nc) => this.armAuthExpiryReconnectFence(nc),
917
890
  watchStatus: () => this.watchStatus(),
918
- bindDmOnly: (mode) => this.bindDmOnly(mode),
891
+ bindDmOnly: (mode) => this.consumers.bindDmOnly(mode),
919
892
  requireLifecycleUid: (what) => this.requireLifecycleUid(what),
920
893
  readPresenceOnce: () => this.readPresenceOnce(),
921
894
  startPresenceWatch: () => this.startPresenceWatch(),
922
895
  sweep: () => this.sweep(),
923
- readChannelsOnce: () => this.readChannelsOnce(),
924
- startChannelWatch: () => this.startChannelWatch(),
896
+ readChannelsOnce: () => this.channelDiscovery.readChannelsOnce(),
897
+ startChannelWatch: () => this.channelDiscovery.startChannelWatch(),
925
898
  readChannels: () => this.readChannels(),
926
- bindDeliveryLeaseWatch: () => this.bindDeliveryLeaseWatch(),
927
- ensureStreams: () => this.ensureStreams(),
928
- startConsumers: () => this.startConsumers(),
899
+ bindDeliveryLeaseWatch: () => this.deliveryLease.bindDeliveryLeaseWatch(),
900
+ ensureStreams: () => this.provisioning.ensureStreams(),
901
+ startConsumers: () => this.consumers.startConsumers(),
929
902
  publishPresence: () => this.publishPresence(),
930
903
  emitRecoverable: (err) => this.emitRecoverable(err),
931
- rearmMembershipWatches: () => this.rearmMembershipWatches(),
904
+ rearmMembershipWatches: () => this.subscriptions.rearmMembershipWatches(),
932
905
  armPlane3: () => this.armPlane3(),
933
- bindLiveness: (plane) => this.bindLiveness(plane),
906
+ bindLiveness: (plane) => this.liveness.bindLiveness(plane),
934
907
  rebindPrincipalServes: (reconnected) => this.rebindPrincipalServes(reconnected),
935
908
  bindTap: (tap) => this.bindTap(tap),
936
909
  retireKvWatch: (iter) => this.retireKvWatch(iter),
937
- stopDeliveryLeaseWatch: () => this.stopDeliveryLeaseWatch(),
910
+ stopDeliveryLeaseWatch: () => this.deliveryLease.stopDeliveryLeaseWatch(),
938
911
  disarmMembershipWatch: (watch) => this.disarmMembershipWatch(watch),
939
912
  disableLibraryReconnect: (nc) => this.disableLibraryReconnect(nc),
940
- dropAnycastRequests: () => this.dropAnycastRequests(),
941
- closeWithoutLibraryReconnect: (nc) => this.closeWithoutLibraryReconnect(nc),
913
+ dropAnycastRequests: () => this.anycastRail.dropAnycastRequests(),
914
+ closeWithoutLibraryReconnect: (nc) => this.credentials.closeWithoutLibraryReconnect(nc),
942
915
  stopPrincipalServe: (intent, republish) => this.stopPrincipalServe(intent, republish),
943
916
  kickBackoff: () => this.kickBackoff(),
944
- deleteRetainedMembershipConsumer: (watch) => this.deleteRetainedMembershipConsumer(watch),
917
+ deleteRetainedMembershipConsumer: (watch) => this.subscriptions.deleteRetainedMembershipConsumer(watch),
945
918
  settleDeliveryLeaseWatches: () => this.settleDeliveryLeaseWatches(),
946
919
  settleKvWatches: () => this.settleKvWatches(),
947
- clearPresenceWriteFailure: () => this.clearPresenceWriteFailure(),
920
+ clearPresenceWriteFailure: () => this.presence.clearPresenceWriteFailure(),
948
921
  emit: (event, ...args) => this.emit(event, ...args),
949
922
  });
950
923
  /** Forwards to the connection component's {@link EndpointConnection.bindConnection}. */
951
924
  bindConnection() {
952
925
  return this.connection.bindConnection();
953
926
  }
954
- /** Forwards to the connection component's {@link EndpointConnection.clearConnectionScoped}. */
955
- clearConnectionScoped() {
956
- return this.connection.clearConnectionScoped();
957
- }
958
927
  /** Forwards to the connection component's {@link EndpointConnection.closeFailedBind}. */
959
928
  closeFailedBind() {
960
929
  return this.connection.closeFailedBind();
@@ -1024,10 +993,10 @@ export class CotalEndpoint extends EventEmitter {
1024
993
  setBackoffTimer: (value) => { this.backoffTimer = value; },
1025
994
  membershipPauses: () => this.membershipPauses,
1026
995
  disableLibraryReconnect: (nc) => this.disableLibraryReconnect(nc),
1027
- clearConnectionScoped: () => this.clearConnectionScoped(),
996
+ clearConnectionScoped: () => this.connection.clearConnectionScoped(),
1028
997
  settleDeliveryLeaseWatches: () => this.settleDeliveryLeaseWatches(),
1029
998
  settleKvWatches: () => this.settleKvWatches(),
1030
- closeWithoutLibraryReconnect: (nc) => this.closeWithoutLibraryReconnect(nc),
999
+ closeWithoutLibraryReconnect: (nc) => this.credentials.closeWithoutLibraryReconnect(nc),
1031
1000
  connectAndBind: () => this.connectAndBind(),
1032
1001
  tearDownIfStopped: () => this.tearDownIfStopped(),
1033
1002
  superviseConnection: () => this.superviseConnection(),
@@ -1045,10 +1014,6 @@ export class CotalEndpoint extends EventEmitter {
1045
1014
  kickBackoff() {
1046
1015
  return this.reconnection.kickBackoff();
1047
1016
  }
1048
- /** Forwards to the reconnect component's {@link EndpointReconnect.membershipPause}. */
1049
- membershipPause(attempt) {
1050
- return this.reconnection.membershipPause(attempt);
1051
- }
1052
1017
  /** Rebuild with backoff until it sticks or we're stopped. Interruptible: a manual
1053
1018
  * {@link reconnect} kicks the backoff so the next attempt runs immediately instead of
1054
1019
  * awaiting the full delay. One loop at a time ({@link reestablishing}); concurrent
@@ -1676,9 +1641,9 @@ export class CotalEndpoint extends EventEmitter {
1676
1641
  readChannels: () => this.readChannels(),
1677
1642
  armJoin: (channels) => this.armJoin(channels),
1678
1643
  backfillArmed: (frontiers, floorSeq) => this.backfillArmed(frontiers, floorSeq),
1679
- subscribeChat: (channel) => this.subscribeChat(channel),
1680
- unsubscribeChat: (channel) => this.unsubscribeChat(channel),
1681
- confirmChatSub: () => this.confirmChatSub(),
1644
+ subscribeChat: (channel) => this.consumers.subscribeChat(channel),
1645
+ unsubscribeChat: (channel) => this.consumers.unsubscribeChat(channel),
1646
+ confirmChatSub: () => this.consumers.confirmChatSub(),
1682
1647
  durableJoinChannel: (channel) => this.durableJoinChannel(channel),
1683
1648
  durableLeaveChannel: (...args) => this.durableLeaveChannel(...args),
1684
1649
  fetchMemberships: (channel) => this.fetchMemberships(channel),
@@ -1791,10 +1756,6 @@ export class CotalEndpoint extends EventEmitter {
1791
1756
  async watchMembership(onChange, onClosed) {
1792
1757
  return this.subscriptions.watchMembership(onChange, onClosed);
1793
1758
  }
1794
- /** Forwards to the subscriptions component's {@link EndpointSubscriptions.deleteRetainedMembershipConsumer}. */
1795
- async deleteRetainedMembershipConsumer(watch) {
1796
- return this.subscriptions.deleteRetainedMembershipConsumer(watch);
1797
- }
1798
1759
  /** Record the consumer behind one of this connection's own KV watches or membership scans, and
1799
1760
  * return the delete-subject prefix it recorded. nats.js names it `<prefix>_<serial>` and,
1800
1761
  * rebuilding it after a stall or a sequence gap, deletes the predecessor itself with no hook before
@@ -1851,10 +1812,6 @@ export class CotalEndpoint extends EventEmitter {
1851
1812
  async disarmMembershipWatch(watch) {
1852
1813
  return this.subscriptions.disarmMembershipWatch(watch);
1853
1814
  }
1854
- /** Forwards to the subscriptions component's {@link EndpointSubscriptions.rearmMembershipWatches}. */
1855
- async rearmMembershipWatches() {
1856
- return this.subscriptions.rearmMembershipWatches();
1857
- }
1858
1815
  /** Fetch recent messages from a channel's JetStream backlog. `signal` cancels the active pull and
1859
1816
  * reclaims its ephemeral consumer before the promise rejects. Returns `HistoryMessage[]`
1860
1817
  * (#1413): every field present on a row was checked by the drain before the row was
@@ -2014,7 +1971,7 @@ export class CotalEndpoint extends EventEmitter {
2014
1971
  * failing call — so without this an over-tight ACL silently drops the agent's
2015
1972
  * traffic and it just looks "absent". A denied request is the exception: nats.js also
2016
1973
  * rejects that request with the denial, so its caller owns it (see {@link trackRequestDenials}).
2017
- * So is a refused channel subscription, whose callback owns it (see {@link subscribeChat}).
1974
+ * So is a refused channel subscription, whose callback owns it (see {@link EndpointConsumers.subscribeChat}).
2018
1975
  * We annotate permission denials explicitly so a denial is never mistaken for absence
2019
1976
  * (which already has a benign cause: MCP reconnect).
2020
1977
  */
@@ -2176,10 +2133,6 @@ export class CotalEndpoint extends EventEmitter {
2176
2133
  notLiveMsg: () => this.notLiveMsg(),
2177
2134
  manager: () => this.manager(),
2178
2135
  });
2179
- /** Forwards to the provisioning component's {@link EndpointProvisioning.ensureStreams}. */
2180
- async ensureStreams() {
2181
- return this.provisioning.ensureStreams();
2182
- }
2183
2136
  /** Create this open space's message streams if they are not there yet, as a consuming endpoint
2184
2137
  * does when it starts. For a sender that consumes nothing and may be the space's first
2185
2138
  * participant (#7045). An authenticated broker's streams come from its setup, and its agents may
@@ -2197,10 +2150,6 @@ export class CotalEndpoint extends EventEmitter {
2197
2150
  async provisionDmInbox(owner, actor, lifecycleUid) {
2198
2151
  return this.provisioning.provisionDmInbox(owner, actor, lifecycleUid);
2199
2152
  }
2200
- /** Forwards to the provisioning component's {@link EndpointProvisioning.ensureDmDurable}. */
2201
- async ensureDmDurable(owner, actor, lifecycleUid, opts) {
2202
- return this.provisioning.ensureDmDurable(owner, actor, lifecycleUid, opts);
2203
- }
2204
2153
  /**
2205
2154
  * Privileged: pre-create an agent's bind-only Plane-3 DELIVER durable (`dlv_<id>`, filtered to
2206
2155
  * `dlv.<id>`), so the agent can BIND its per-member durable handoff without holding CONSUMER.CREATE
@@ -2251,11 +2200,11 @@ export class CotalEndpoint extends EventEmitter {
2251
2200
  daemonRenewalLeaseRevision: () => this.daemonRenewalLeaseRevision,
2252
2201
  setDaemonRenewalLeaseRevision: (revision) => { this.daemonRenewalLeaseRevision = revision; },
2253
2202
  notLiveMsg: () => this.notLiveMsg(),
2254
- consumerInfo: (stream, durable) => this.consumerInfo(stream, durable),
2203
+ consumerInfo: (stream, durable) => this.consumers.consumerInfo(stream, durable),
2255
2204
  manager: () => this.manager(),
2256
2205
  chatFrontier: () => this.chatFrontier(),
2257
2206
  aclAllows: (owner, lifecycleUid, channel) => this.aclAllows(owner, lifecycleUid, channel),
2258
- catchupCopy: (...args) => this.catchupCopy(...args),
2207
+ catchupCopy: (...args) => this.durable.catchupCopy(...args),
2259
2208
  });
2260
2209
  /** Forwards to the durable backstop's {@link EndpointDurableBackstop.membersRegistry}. */
2261
2210
  async membersRegistry() {
@@ -2391,9 +2340,6 @@ export class CotalEndpoint extends EventEmitter {
2391
2340
  async watchDeliveryLease(shardIndex, onEvent) {
2392
2341
  return this.deliveryLease.watchDeliveryLease(shardIndex, onEvent);
2393
2342
  }
2394
- stopDeliveryLeaseWatch() {
2395
- return this.deliveryLease.stopDeliveryLeaseWatch();
2396
- }
2397
2343
  /** Wait for the lease-watch binds still in flight, then for every retired watch's consumer delete.
2398
2344
  * {@link stop} and a live-epoch rebuild run this before they close the connection those deletes
2399
2345
  * need (#3966). */
@@ -2449,12 +2395,6 @@ export class CotalEndpoint extends EventEmitter {
2449
2395
  void binding.then(settled, settled);
2450
2396
  return binding;
2451
2397
  }
2452
- /** Bind the lease watch on the current connection. A bind that lands after a newer watch replaced
2453
- * its intent, or after a stop or connection teardown moved the epoch, retires its watch instead of
2454
- * installing it: the epoch it was bound for is gone, and a rebuilt one binds its own. */
2455
- bindDeliveryLeaseWatch() {
2456
- return this.deliveryLease.bindDeliveryLeaseWatch();
2457
- }
2458
2398
  /** The principal recorded as holding a shard's delivery lease, read by THIS process from the row,
2459
2399
  * or `undefined` when no row is live or the read failed.
2460
2400
  *
@@ -2576,18 +2516,6 @@ export class CotalEndpoint extends EventEmitter {
2576
2516
  async deliveryClassFresh(channel) {
2577
2517
  return this.durableBackstop.deliveryClassFresh(channel);
2578
2518
  }
2579
- /** Forwards to the durable backstop's {@link EndpointDurableBackstop.resolveOwnerByName}. */
2580
- resolveOwnerByName(name) {
2581
- return this.durableBackstop.resolveOwnerByName(name);
2582
- }
2583
- /** Forwards to the durable backstop's {@link EndpointDurableBackstop.plane3MsgId}. */
2584
- plane3MsgId(entry, keySuffix) {
2585
- return this.durableBackstop.plane3MsgId(entry, keySuffix);
2586
- }
2587
- /** Forwards to the durable backstop's {@link EndpointDurableBackstop.publishDinbox}. */
2588
- async publishDinbox(principal, lifecycleUid, entry) {
2589
- return this.durableBackstop.publishDinbox(principal, lifecycleUid, entry);
2590
- }
2591
2519
  /**
2592
2520
  * Privileged durable-JOIN write (v3: the delivery daemon calls this from its `ctl.delivery` handler
2593
2521
  * after validating channel ⊆ the caller's read ACL): capture `joinCursor`, commit a `durable-active`
@@ -2612,95 +2540,33 @@ export class CotalEndpoint extends EventEmitter {
2612
2540
  async durableJoinFor(owner, channel, lifecycleUid, opts = {}) {
2613
2541
  return this.durableBackstop.durableJoinFor(owner, channel, lifecycleUid, opts);
2614
2542
  }
2615
- /** Whether one lifecycle's exact ACL row allows a membership on `channel` now (a family must lie
2616
- * inside one entry, {@link membershipInAllow}). A leader-served read: the handle is opened without
2617
- * direct reads, so a row narrowed before this read began is the row it returns. */
2618
- async aclAllows(owner, lifecycleUid, channel) {
2619
- const row = await readAcl(await this.aclRegistry(), owner, lifecycleUid);
2620
- return row !== undefined && membershipInAllow(row.record.allowSubscribe, channel);
2543
+ /** The agent-side durable membership of this endpoint. Every dependency is read when it is used, so a
2544
+ * field assigned after construction is seen. */
2545
+ durable = new EndpointDurable({
2546
+ js: () => this.js,
2547
+ jsm: () => this.jsm,
2548
+ space: () => this.space,
2549
+ pendingDurableLeave: () => this.pendingDurableLeave,
2550
+ stopped: () => this.stopped,
2551
+ plane3Channels: () => this.plane3Channels,
2552
+ aclRegistry: () => this.aclRegistry(),
2553
+ deliveryClassFresh: (channel) => this.deliveryClassFresh(channel),
2554
+ deleteConsumerIfPresent: (stream, durable) => this.consumers.deleteConsumerIfPresent(stream, durable),
2555
+ publishDinbox: (principal, lifecycleUid, entry) => this.durableBackstop.publishDinbox(principal, lifecycleUid, entry),
2556
+ requestDelivery: (op, args, timeoutMs) => this.requestDelivery(op, args, timeoutMs),
2557
+ requireLifecycleUid: (what) => this.requireLifecycleUid(what),
2558
+ emitRecoverable: (err) => this.emitRecoverable(err),
2559
+ membershipPause: (attempt) => this.reconnection.membershipPause(attempt),
2560
+ });
2561
+ /** Forwards to the durable-membership component's {@link EndpointDurable.aclAllows}. */
2562
+ aclAllows(owner, lifecycleUid, channel) {
2563
+ return this.durable.aclAllows(owner, lifecycleUid, channel);
2621
2564
  }
2622
2565
  /** Privileged durable-LEAVE write: tombstone the membership at `leaveCursor = frontier` so the
2623
2566
  * backstop denies `seq > leaveCursor` while a pre-leave entry stays deliverable (SPEC §7 interval). */
2624
2567
  async durableLeaveFor(owner, channel, lifecycleUid, expectedGeneration) {
2625
2568
  return this.durableBackstop.durableLeaveFor(owner, channel, lifecycleUid, expectedGeneration);
2626
2569
  }
2627
- /** Idempotently copy the eligible chat messages in `(fromSeqExcl, toSeqIncl]` for `channel` into the
2628
- * owner inbox, via a DEDICATED per-(owner,join) ephemeral consumer (NOT the agent-scoped
2629
- * `chathist_<id>`/`histLock` — red-team HIGH-8). It copies what the stream still holds in that
2630
- * window; a post the history limit removed first is not copied and is not reported (SPEC §4).
2631
- *
2632
- * A FAMILY row (`review.>`, #5404) reads the window on every channel under it and copies a post only
2633
- * when that post's own channel is durable-class. Each copy names the post's own channel, never the
2634
- * family, and it skips nothing another row of the lifecycle covers: two joins can both be pending
2635
- * when a post lands, so neither proves the other copied it. The per-message, per-lifecycle dedupe id
2636
- * keeps one copy. */
2637
- async catchupCopy(owner, lifecycleUid, channel, fromSeqExcl, toSeqIncl, generation) {
2638
- if (!this.js || !this.jsm || toSeqIncl <= fromSeqExcl)
2639
- return 0;
2640
- const subject = chatSubject(this.space, "*", "*", channel);
2641
- const family = isChannelFamily(channel);
2642
- const durableClass = new Map();
2643
- const stored = (ch) => {
2644
- if (!family)
2645
- return Promise.resolve(true);
2646
- let cls = durableClass.get(ch);
2647
- if (cls === undefined)
2648
- durableClass.set(ch, (cls = this.deliveryClassFresh(ch).then((c) => c === "durable")));
2649
- return cls;
2650
- };
2651
- // Consumer NAME must be JetStream-safe (no `.`) AND collision-free: use the principal DASH-form
2652
- // (`<owner>-<actor>`, `-` reserved as the sole separator), NOT `token(owner)` — `token()` maps the
2653
- // dot-form `.`→`_`, which is NOT collision-free (`_` is legal inside a token, so `a.b_c` and `a_b.c`
2654
- // would both underscore to `a_b_c`). LIFECYCLE-KEYED (SPEC 13.1): generations restart at 1 per
2655
- // lifecycle, so an alias-keyed `cu_<principal>_<gen>` would let a same-alias successor
2656
- // delete/recreate a predecessor's in-flight catch-up consumer — the uid disambiguates.
2657
- const cuP = parsePrincipalKey(owner);
2658
- const name = `cu_${cuP ? lifecycleNameKey(cuP.owner, cuP.actor, lifecycleUid) : `${token(owner)}-${lifecycleUid}`}_${generation}`;
2659
- // A failed read throws, leaving the pending row to retry over the same window.
2660
- await this.deleteConsumerIfPresent(chatStream(this.space), name);
2661
- await this.jsm.consumers.add(chatStream(this.space), {
2662
- name, filter_subject: subject, ack_policy: AckPolicy.None, mem_storage: true,
2663
- inactive_threshold: nanos(30_000), deliver_policy: DeliverPolicy.StartSequence, opt_start_seq: fromSeqExcl + 1,
2664
- });
2665
- let copied = 0;
2666
- try {
2667
- const consumer = await this.js.consumers.get(chatStream(this.space), name);
2668
- let pending = (await consumer.info()).num_pending;
2669
- while (pending > 0) {
2670
- const want = Math.min(pending, 256);
2671
- const iter = await consumer.fetch({ max_messages: want, expires: 5_000 });
2672
- let got = 0;
2673
- for await (const m of iter) {
2674
- got++;
2675
- if (m.seq > toSeqIncl)
2676
- return copied;
2677
- let msg;
2678
- try {
2679
- msg = m.json();
2680
- }
2681
- catch {
2682
- continue;
2683
- }
2684
- const parsed = parseSubject(m.subject);
2685
- if (!parsed || !isFromSubjectSender(msg, parsed) || msg.from.id === owner)
2686
- continue;
2687
- if (!(await stored(parsed.rest)))
2688
- continue;
2689
- await this.publishDinbox(owner, lifecycleUid, {
2690
- msg, channel: parsed.rest, seq: m.seq, reason: "durable-channel", generation, ...(family ? { row: channel } : {}),
2691
- });
2692
- copied++;
2693
- }
2694
- if (got < want)
2695
- break;
2696
- pending -= got;
2697
- }
2698
- }
2699
- finally {
2700
- await this.deleteConsumerIfPresent(chatStream(this.space), name);
2701
- }
2702
- return copied;
2703
- }
2704
2570
  /** Start the Plane-3 fan-out writer + trusted reader on THIS (privileged, server-side delivery-daemon)
2705
2571
  * endpoint, AND serve the `ctl.delivery` control service (runtime durable join/leave/list). `aclFor`
2706
2572
  * maps an owner id to its current read ACL for the reader's re-authorization — read FRESH per entry
@@ -2752,195 +2618,40 @@ export class CotalEndpoint extends EventEmitter {
2752
2618
  async rearmPlane3() {
2753
2619
  return this.deliveryPlane.rearmPlane3();
2754
2620
  }
2755
- /** Forwards to the delivery plane's {@link EndpointDeliveryPlane.plane3MayAct}. */
2756
- plane3MayAct() {
2757
- return this.deliveryPlane.plane3MayAct();
2758
- }
2759
2621
  /** Forwards to the delivery plane's {@link EndpointDeliveryPlane.armPlane3}. */
2760
2622
  async armPlane3() {
2761
2623
  return this.deliveryPlane.armPlane3();
2762
2624
  }
2763
- /** Forwards to the delivery plane's {@link EndpointDeliveryPlane.pumpDlv}. */
2764
- async pumpDlv() {
2765
- return this.deliveryPlane.pumpDlv();
2766
- }
2767
- /** (Re)bind the anycast take responder and the request records maintenance on the current
2768
- * connection (SPEC §8.1). The records bucket is created here as well as at space setup, so a mesh
2769
- * that predates it gets one when its daemon restarts at this version. */
2770
- async armAnycastRequests() {
2771
- if (!this.nc || !this.jsm)
2772
- return;
2773
- this.dropAnycastRequests();
2774
- const definition = anycastStoreDefinition(this.space);
2775
- let kv;
2776
- try {
2777
- kv = await new Kvm(this.nc).create(definition.bucket, definition.createOptions);
2778
- }
2779
- catch (e) {
2780
- // A credential minted before the records existed cannot open them. That costs the records and
2781
- // nothing else: the rest of Plane-3 still serves, and every anycast op answers with the cause.
2782
- if (!isPermissionDenied(e))
2783
- throw e;
2784
- this.anycastUnavailable = ANYCAST_RECORDS_CREDENTIAL_OUTDATED;
2785
- this.emitRecoverable(new Error(`delivery: ${ANYCAST_RECORDS_CREDENTIAL_OUTDATED}`));
2786
- return;
2787
- }
2788
- this.anycastUnavailable = undefined;
2789
- const authority = new AnycastRequestAuthority({
2790
- jsm: this.jsm,
2791
- kv,
2792
- stream: taskStream(this.space),
2793
- send: (to, event) => this.sendAnycastNotice(to, event),
2794
- mayAct: () => this.plane3MayAct(),
2795
- onError: (e) => this.emitRecoverable(e),
2796
- });
2797
- this.anycastAuthority = authority;
2798
- this.takeServeSub = this.serveTakes(authority);
2799
- const sweep = () => void authority.sweep().catch((e) => this.emitRecoverable(e));
2800
- this.anycastSweep = setInterval(sweep, ANYCAST_SWEEP_MS);
2801
- this.anycastSweep.unref?.();
2802
- sweep();
2803
- }
2804
- dropAnycastRequests() {
2805
- if (this.takeServeSub) {
2806
- try {
2807
- this.takeServeSub.unsubscribe();
2808
- }
2809
- catch { /* dead with the old connection */ }
2810
- const i = this.subs.indexOf(this.takeServeSub);
2811
- if (i >= 0)
2812
- this.subs.splice(i, 1);
2813
- this.takeServeSub = undefined;
2814
- }
2815
- clearInterval(this.anycastSweep);
2816
- this.anycastSweep = undefined;
2817
- this.anycastAuthority = undefined;
2818
- }
2819
- /** Serve takes on `take.*.*.*`, each in its own time: a take reads one request and writes one row,
2820
- * and shares nothing with any other take but the row's CAS. The reply is bound to the caller's own
2821
- * request subtree, as `serveControl`'s `boundReply` binds it. */
2822
- serveTakes(authority) {
2823
- const sub = this.nc.subscribe(takeServeFilter(this.space), { queue: TAKE_ROUTE });
2824
- this.subs.push(sub);
2825
- void (async () => {
2826
- for await (const m of sub) {
2827
- if (!m.reply || !m.reply.startsWith(`${m.subject}.reply.`)) {
2828
- this.emitRecoverable(new Error(`rejected take on ${m.subject}: reply target "${m.reply ?? "(none)"}" is not under the sender's own reply subtree`));
2829
- continue;
2830
- }
2831
- void this.answerTake(authority, m).catch((e) => this.emitRecoverable(e));
2832
- }
2833
- })().catch((e) => this.emitRecoverable(e));
2834
- return sub;
2835
- }
2836
- async answerTake(authority, m) {
2837
- let reply;
2838
- if (this.takesInFlight >= MAX_TAKES_IN_FLIGHT)
2839
- reply = { ok: false, code: "busy", error: "the delivery daemon is answering too many takes; retry" };
2840
- else {
2841
- this.takesInFlight++;
2842
- try {
2843
- reply = await this.takeFor(authority, m);
2844
- }
2845
- catch (e) {
2846
- reply = { ok: false, code: "busy", error: `the take could not be recorded: ${e.message}` };
2847
- }
2848
- finally {
2849
- this.takesInFlight--;
2850
- }
2851
- }
2852
- m.respond(JSON.stringify(reply));
2853
- }
2854
- /** Check one take's caller and arguments, then record it. The role and the caller come from the
2855
- * broker-policed subject; the payload's `from.id` must match, as on every control rail. */
2856
- async takeFor(authority, m) {
2857
- if (!this.plane3MayAct())
2858
- return { ok: false, code: "busy", error: "delivery: this daemon is not serving this shard (it is re-checking ownership); retry" };
2859
- const parsed = parseTakeSubject(m.subject);
2860
- let req;
2861
- try {
2862
- req = m.json();
2863
- }
2864
- catch {
2865
- req = undefined;
2866
- }
2867
- if (!parsed || !isPrincipalOwnerToken(parsed.owner) || req?.from?.id !== parsed.sender || typeof req.from.name !== "string")
2868
- return { ok: false, code: "mismatch", error: "sender mismatch - take rejected" };
2869
- if (!isAnycastSeq(req.seq) || !isAnycastSeq(req.count) || typeof req.id !== "string" || req.id.length > 256 ||
2870
- typeof req.epoch !== "string" || req.epoch.length > 64)
2871
- return { ok: false, code: "mismatch", error: "a take names a seq, the request id, a delivery count and the stream's creation time" };
2872
- // The name reaches the sender's status text, so it must pass the rule a presence card name does.
2873
- try {
2874
- assertValidName(req.from.name);
2875
- }
2876
- catch (e) {
2877
- return { ok: false, code: "mismatch", error: `a take names its holder by a valid display name: ${e.message}` };
2878
- }
2879
- return authority.take(parsed.role, { from: { id: parsed.sender, name: req.from.name }, seq: req.seq, id: req.id, count: req.count, epoch: req.epoch });
2880
- }
2881
- /** DM one notice to a request's sender from this daemon's own principal. The event key is the
2882
- * message id, so a resend after a crash is dropped by the DM stream's duplicate window and by
2883
- * the receiving connector. */
2884
- async sendAnycastNotice(to, event) {
2885
- if (!this.js)
2886
- throw new Error(this.notLiveMsg());
2887
- const recipient = parsePrincipalKey(to);
2888
- if (!recipient)
2889
- throw new Error(`anycast notice: "${to}" is not a principal`);
2890
- const msg = {
2891
- id: event.key,
2892
- ts: Date.now(),
2893
- space: this.space,
2894
- from: this.ref(),
2895
- to,
2896
- parts: [{ kind: "text", text: event.text }, { kind: "data", data: { [ANYCAST_NOTICE_KEY]: event.notice } }],
2897
- };
2898
- await this.js.publish(unicastSubject(this.space, recipient.owner, recipient.actor, this.owner, this.actor), JSON.stringify(msg), { msgID: msg.id });
2899
- }
2900
- /** DM a post's sender that its mentions of `names` reached no one, because each of those agents
2901
- * may not read `channel`. The id carries the post's stream seq, so a fan-out redelivered after a
2902
- * crash sends the notice again under the same id and the DM stream drops the duplicate. */
2903
- async sendMentionNotice(msg, channel, seq, names) {
2904
- if (!this.js)
2905
- throw new Error(this.notLiveMsg());
2906
- const recipient = parsePrincipalKey(msg.from.id);
2907
- if (!recipient)
2908
- throw new Error(`mention notice: "${msg.from.id}" is not a principal`);
2909
- const named = names.map((n) => `@${n}`).join(", ");
2910
- const notice = {
2911
- id: `mention.${seq}.${msg.id}`,
2912
- ts: Date.now(),
2913
- space: this.space,
2914
- from: this.ref(),
2915
- to: msg.from.id,
2916
- parts: [
2917
- { kind: "text", text: `Your post on #${channel} mentioned ${named}, who may not read #${channel} and ${names.length === 1 ? "was" : "were"} not given it. Reach ${names.length === 1 ? "them" : "each"} another way, such as cotal_dm.` },
2918
- { kind: "data", data: { [MENTION_NOTICE_KEY]: { channel, message: msg.id, names: [...names] } } },
2919
- ],
2920
- };
2921
- await this.js.publish(unicastSubject(this.space, recipient.owner, recipient.actor, this.owner, this.actor), JSON.stringify(notice), { msgID: notice.id });
2922
- }
2923
- /** Answer a sender's status or cancel for one of its own requests. The caller is the
2924
- * authenticated subject sender, checked against the request's stored subject. */
2925
- async deliveryAnycast(op, caller, args) {
2926
- const authority = this.anycastAuthority;
2927
- if (!authority)
2928
- return { ok: false, error: `delivery: ${this.anycastUnavailable ?? "the anycast request records are not open on this daemon; retry"}` };
2929
- if (!isAnycastSeq(args.seq))
2930
- return { ok: false, error: `${op}: seq must be a whole number of at least 1` };
2931
- if (args.id !== undefined && (typeof args.id !== "string" || args.id.length > 256))
2932
- return { ok: false, error: `${op}: id must be a request id` };
2933
- const q = { seq: args.seq, ...(typeof args.id === "string" ? { id: args.id } : {}) };
2934
- try {
2935
- const status = op === ANYCAST_CANCEL_OP ? await authority.cancel(caller, q) : await authority.status(caller, q);
2936
- if (!this.plane3MayAct())
2937
- return { ok: false, error: "delivery: this daemon stopped serving this shard while the request was in flight; retry" };
2938
- return { ok: true, data: status };
2939
- }
2940
- catch (e) {
2941
- return { ok: false, error: e.message };
2942
- }
2943
- }
2625
+ /** The anycast request rail of this endpoint. Every dependency is read when it is used, so a field
2626
+ * assigned after construction is seen. */
2627
+ anycastRail = new EndpointAnycast({
2628
+ nc: () => this.nc,
2629
+ jsm: () => this.jsm,
2630
+ js: () => this.js,
2631
+ space: () => this.space,
2632
+ owner: () => this.owner,
2633
+ actor: () => this.actor,
2634
+ card: () => this.card,
2635
+ authed: () => this.authed,
2636
+ subs: () => this.subs,
2637
+ anycastUnavailable: () => this.anycastUnavailable,
2638
+ setAnycastUnavailable: (value) => { this.anycastUnavailable = value; },
2639
+ anycastAuthority: () => this.anycastAuthority,
2640
+ setAnycastAuthority: (value) => { this.anycastAuthority = value; },
2641
+ takeServeSub: () => this.takeServeSub,
2642
+ setTakeServeSub: (value) => { this.takeServeSub = value; },
2643
+ anycastSweep: () => this.anycastSweep,
2644
+ setAnycastSweep: (value) => { this.anycastSweep = value; },
2645
+ takesInFlight: () => this.takesInFlight,
2646
+ setTakesInFlight: (value) => { this.takesInFlight = value; },
2647
+ emitRecoverable: (err) => this.emitRecoverable(err),
2648
+ plane3MayAct: () => this.deliveryPlane.plane3MayAct(),
2649
+ notLiveMsg: () => this.notLiveMsg(),
2650
+ ref: () => this.ref(),
2651
+ requestBoundReply: (nc, subject, body, reply, timeoutMs) => this.requestBoundReply(nc, subject, body, reply, timeoutMs),
2652
+ readTaskEpoch: () => this.consumers.readTaskEpoch(),
2653
+ requestDelivery: (op, args, timeoutMs) => this.requestDelivery(op, args, timeoutMs),
2654
+ });
2944
2655
  // ---- the peer-readable liveness surface (#1577) --------------------------
2945
2656
  /** The peer-readable liveness responders and the probe, of this endpoint. Every dependency is read
2946
2657
  * when it is used, so a field assigned after construction is seen. */
@@ -3001,10 +2712,6 @@ export class CotalEndpoint extends EventEmitter {
3001
2712
  serveLiveness(plane, readState) {
3002
2713
  return this.liveness.serveLiveness(plane, readState);
3003
2714
  }
3004
- /** Forwards to the liveness component's {@link EndpointLiveness.bindLiveness}. */
3005
- bindLiveness(plane) {
3006
- return this.liveness.bindLiveness(plane);
3007
- }
3008
2715
  /** Bind the liveness responder for the DELIVERY plane, grading itself from its own shard-0 lease
3009
2716
  * through the shared classifier. The daemon is the one process that can answer this honestly: it
3010
2717
  * knows its own incarnation, so a predecessor's `ready:true` corpse in the bucket classifies
@@ -3093,134 +2800,42 @@ export class CotalEndpoint extends EventEmitter {
3093
2800
  void this.armPrincipalServe(intent, nc, handle);
3094
2801
  return { ready, failed, stop: () => this.stopPrincipalServe(intent) };
3095
2802
  }
3096
- /** Subscribe `intent` on `nc`. */
2803
+ /** The principal serve and prompts of this endpoint. Every dependency is read when it is used, and
2804
+ * every endpoint method is looked up at call time, so a member a caller replaced on the endpoint runs. */
2805
+ principalServe = new EndpointPrincipalServe({
2806
+ space: () => this.space,
2807
+ nc: () => this.nc,
2808
+ owner: () => this.owner,
2809
+ actor: () => this.actor,
2810
+ card: () => this.card,
2811
+ principalServes: () => this.principalServes,
2812
+ principalServers: () => principalServers,
2813
+ promptsPresence: () => this.promptsPresence,
2814
+ setPromptsPresence: (value) => { this.promptsPresence = value; },
2815
+ publishPresence: () => this.publishPresence(),
2816
+ emitRecoverable: (err) => this.emitRecoverable(err),
2817
+ requireLifecycleUid: (what) => this.requireLifecycleUid(what),
2818
+ notLiveMsg: () => this.notLiveMsg(),
2819
+ });
2820
+ /** Forwards to the principal-serve component's {@link EndpointPrincipalServe.bindPrincipalHandle}. */
3097
2821
  bindPrincipalHandle(intent, nc) {
3098
- return servePrincipalRoute(nc, this.space, intent.self, intent.serve);
2822
+ return this.principalServe.bindPrincipalHandle(intent, nc);
3099
2823
  }
3100
- /** A principal-route refusal a call or a serve reports itself: a request publish, a serve
3101
- * subscription or a reply read. Only a reply publish is left, which no call or serve awaits. */
2824
+ /** Forwards to the principal-serve component's {@link EndpointPrincipalServe.ownedPrincipalRouteRefusal}. */
3102
2825
  ownedPrincipalRouteRefusal(err) {
3103
- const p = `${spacePrefix(this.space)}.ep.`;
3104
- if (err.operation === "publish")
3105
- return err.subject.startsWith(`${p}prin.`);
3106
- return err.subject.startsWith(`${p}prin.`) || err.subject.startsWith(`${p}prin-reply.`);
2826
+ return this.principalServe.ownedPrincipalRouteRefusal(err);
3107
2827
  }
3108
- /** Track one binding: a refusal ends the serve, and an accepted subscription on the current
3109
- * connection shows the presence field. */
2828
+ /** Forwards to the principal-serve component's {@link EndpointPrincipalServe.armPrincipalServe}. */
3110
2829
  async armPrincipalServe(intent, nc, handle) {
3111
- intent.binding = { nc, handle };
3112
- // Every earlier binding is on a replaced connection: retire it once its handlers finish.
3113
- for (const old of intent.handles)
3114
- void old.stop().finally(() => {
3115
- const i = intent.handles.indexOf(old);
3116
- if (i >= 0)
3117
- intent.handles.splice(i, 1);
3118
- });
3119
- intent.handles.push(handle);
3120
- intent.readyOn = undefined;
3121
- void handle.refused.then((err) => {
3122
- if (!intent.ended && intent.binding?.handle === handle)
3123
- this.endPrincipalServe(intent, err);
3124
- });
3125
- try {
3126
- await handle.ready;
3127
- }
3128
- catch {
3129
- // A refusal ends the serve through `refused`. A flush that failed because the connection
3130
- // went away is answered by the binding the next connection makes.
3131
- return;
3132
- }
3133
- this.principalServeConfirmed(intent, nc, handle);
3134
- }
3135
- /** The broker accepted `handle` on `nc`. When that is still the current binding, the serve is
3136
- * ready there. */
3137
- principalServeConfirmed(intent, nc, handle) {
3138
- if (intent.ended || intent.binding?.handle !== handle || this.nc !== nc)
3139
- return;
3140
- intent.readyOn = nc;
3141
- if (!intent.readySettled) {
3142
- intent.readySettled = true;
3143
- intent.resolveReady();
3144
- }
3145
- if (intent.serve.endpoint === AGENT_ENDPOINT)
3146
- this.publishPresence().catch((e) => this.emitRecoverable(e));
2830
+ return this.principalServe.armPrincipalServe(intent, nc, handle);
3147
2831
  }
3148
- /** Re-bind every principal serve on a replaced connection (a rebuild), or re-run the check on the
3149
- * connection the library reconnected and re-subscribed itself. */
2832
+ /** Forwards to the principal-serve component's {@link EndpointPrincipalServe.rebindPrincipalServes}. */
3150
2833
  rebindPrincipalServes(reconnected) {
3151
- const nc = this.nc;
3152
- if (!nc)
3153
- return;
3154
- for (const intent of this.principalServes.values()) {
3155
- if (intent.ended)
3156
- continue;
3157
- const bound = intent.binding;
3158
- if (bound && bound.nc === nc) {
3159
- if (!reconnected)
3160
- continue;
3161
- intent.readyOn = undefined;
3162
- void bound.handle.check().then(() => this.principalServeConfirmed(intent, nc, bound.handle), () => { });
3163
- continue;
3164
- }
3165
- let handle;
3166
- try {
3167
- handle = this.bindPrincipalHandle(intent, nc);
3168
- }
3169
- catch (e) {
3170
- this.endPrincipalServe(intent, e);
3171
- continue;
3172
- }
3173
- void this.armPrincipalServe(intent, nc, handle);
3174
- }
2834
+ return this.principalServe.rebindPrincipalServes(reconnected);
3175
2835
  }
3176
- /** End a serve the broker refused: no more serving, `failed` resolves, the presence field goes. */
3177
- endPrincipalServe(intent, err) {
3178
- if (intent.ended)
3179
- return;
3180
- this.forgetPrincipalServe(intent);
3181
- const wasReady = intent.readySettled;
3182
- if (!intent.readySettled) {
3183
- intent.readySettled = true;
3184
- intent.rejectReady(err);
3185
- }
3186
- intent.resolveFailed(err);
3187
- for (const handle of intent.handles)
3188
- void handle.stop();
3189
- if (intent.serve.endpoint === AGENT_ENDPOINT) {
3190
- this.promptsPresence = undefined;
3191
- this.publishPresence().catch((e) => this.emitRecoverable(e));
3192
- }
3193
- // `ready` already carried a refusal that came before it settled; a later one is reported here.
3194
- if (wasReady)
3195
- this.emitRecoverable(new Error(`stopped serving "${intent.serve.endpoint}" on the principal route: ${err.message}`, { cause: err }));
3196
- }
3197
- /** Mark `intent` ended and release what it holds in this endpoint and in this process. */
3198
- forgetPrincipalServe(intent) {
3199
- intent.ended = true;
3200
- intent.readyOn = undefined;
3201
- if (this.principalServes.get(intent.serve.endpoint) === intent)
3202
- this.principalServes.delete(intent.serve.endpoint);
3203
- if (principalServers.get(intent.serverKey) === intent)
3204
- principalServers.delete(intent.serverKey);
3205
- }
3206
- /** Stop serving `intent` and wait for its handlers in flight, each until its request's deadline
3207
- * at most. The ending is synchronous, so a
3208
- * `ready` still waiting for the broker rejects before the caller's next step. `republish` writes
3209
- * presence without the `prompts` field; the endpoint's own stop writes it offline instead. */
2836
+ /** Forwards to the principal-serve component's {@link EndpointPrincipalServe.stopPrincipalServe}. */
3210
2837
  async stopPrincipalServe(intent, republish = true) {
3211
- if (!intent.ended) {
3212
- this.forgetPrincipalServe(intent);
3213
- if (!intent.readySettled) {
3214
- intent.readySettled = true;
3215
- intent.rejectReady(new Error(`stopped serving "${intent.serve.endpoint}" before the broker confirmed the subscription`));
3216
- }
3217
- if (intent.serve.endpoint === AGENT_ENDPOINT) {
3218
- this.promptsPresence = undefined;
3219
- if (republish)
3220
- this.publishPresence().catch((e) => this.emitRecoverable(e));
3221
- }
3222
- }
3223
- await Promise.all(intent.handles.map((handle) => handle.stop()));
2838
+ return this.principalServe.stopPrincipalServe(intent, republish);
3224
2839
  }
3225
2840
  /**
3226
2841
  * Set this process's `prompts` presence field and write presence at once (SPEC §6): how many
@@ -3231,18 +2846,7 @@ export class CotalEndpoint extends EventEmitter {
3231
2846
  * endpoint is not served, and a RangeError for a `seq` below one this runtime already used.
3232
2847
  */
3233
2848
  async setPromptsPresence(prompts) {
3234
- for (const k of ["open", "seq"])
3235
- if (!Number.isSafeInteger(prompts?.[k]) || prompts[k] < 0)
3236
- throw new TypeError(`prompts.${k} must be a non-negative safe integer`);
3237
- const intent = this.principalServes.get(AGENT_ENDPOINT);
3238
- if (!intent)
3239
- throw new Error(`the prompts presence field belongs to a served "${AGENT_ENDPOINT}" endpoint: call servePrincipal first (SPEC §6)`);
3240
- const used = promptsSeqs.get(intent.self.runtimeId) ?? 0;
3241
- if (prompts.seq < used)
3242
- throw new RangeError(`prompts.seq ${prompts.seq} is below ${used}, which this process already used under runtime ${intent.self.runtimeId}: seq never goes back under one runtime id (SPEC §6)`);
3243
- promptsSeqs.set(intent.self.runtimeId, prompts.seq);
3244
- this.promptsPresence = { open: prompts.open, seq: prompts.seq };
3245
- await this.publishPresence();
2849
+ return this.principalServe.setPromptsPresence(prompts);
3246
2850
  }
3247
2851
  /**
3248
2852
  * Take the next `prompts` `seq` for this process's runtime (SPEC §6): 0 the first time, then one
@@ -3250,18 +2854,11 @@ export class CotalEndpoint extends EventEmitter {
3250
2854
  * prompt desk takes every `seq` it shows from here. Throws without a lifecycle UID.
3251
2855
  */
3252
2856
  nextPromptsSeq() {
3253
- const runtimeId = processRuntime(this.requireLifecycleUid("nextPromptsSeq")).id;
3254
- const used = promptsSeqs.get(runtimeId);
3255
- const next = used === undefined ? 0 : used + 1;
3256
- promptsSeqs.set(runtimeId, next);
3257
- return next;
2857
+ return this.principalServe.nextPromptsSeq();
3258
2858
  }
3259
- /** The `prompts` field this process's presence carries now, or none. */
2859
+ /** Forwards to the principal-serve component's {@link EndpointPrincipalServe.servedPrompts}. */
3260
2860
  servedPrompts() {
3261
- const intent = this.principalServes.get(AGENT_ENDPOINT);
3262
- if (!intent || intent.ended || !this.nc || intent.readyOn !== this.nc)
3263
- return undefined;
3264
- return this.promptsPresence;
2861
+ return this.principalServe.servedPrompts();
3265
2862
  }
3266
2863
  /**
3267
2864
  * Call one command of a principal's own endpoint on the principal route (SPEC 13.21), as this
@@ -3277,159 +2874,45 @@ export class CotalEndpoint extends EventEmitter {
3277
2874
  * (`unknown`) when no reply came. See {@link epPrincipalCall}.
3278
2875
  */
3279
2876
  async callPrincipal(call) {
3280
- const nc = this.nc;
3281
- if (!nc)
3282
- throw new Error(this.notLiveMsg());
3283
- const contract = call.contract
3284
- ?? (call.command === "describe" ? describeContracts() : call.endpoint === AGENT_ENDPOINT ? AGENT_CONTRACTS[call.command] : undefined);
3285
- if (contract === undefined)
3286
- throw new EpEnvelopeError("bad-request", `no contract is built in for ${call.endpoint}.${call.command}; pass one`, undefined, "not-executed");
3287
- const caller = { owner: this.owner, actor: this.actor, uid: this.requireLifecycleUid("callPrincipal") };
3288
- return epPrincipalCall(nc, this.space, { principal: call.principal, authority: call.authority }, {
3289
- endpoint: call.endpoint, command: call.command, contract, caller, name: this.card.name,
3290
- ...(call.args !== undefined ? { args: call.args } : {}),
3291
- }, { deadlineMs: call.deadlineMs, ...(call.signal ? { signal: call.signal } : {}) });
2877
+ return this.principalServe.callPrincipal(call);
3292
2878
  }
3293
2879
  /** Agent-side: request a Plane-3 durable backstop for a channel via the server-side delivery daemon (ctl.delivery). Throws
3294
2880
  * when no privileged writer is present (open / no delivery daemon). 30s timeout — activation catch-up may
3295
2881
  * run before the reply (the window is small, but a busy channel can take more than the 5s default). */
3296
- async durableJoinChannel(channel) {
3297
- const reply = await this.requestDelivery("durableJoin", { channel }, 30_000);
3298
- if (!reply.ok)
3299
- throw new Error(reply.error ?? "durable join rejected");
3300
- return reply.data ?? { durable: false };
2882
+ durableJoinChannel(channel) {
2883
+ return this.durable.durableJoinChannel(channel);
3301
2884
  }
3302
2885
  /** Agent-side: release a Plane-3 durable backstop (tombstone membership at the leave cursor). Passes
3303
2886
  * the join generation so a stale leave can't tombstone a newer rejoin (the delivery daemon validates
3304
2887
  * it) AND this incarnation's lifecycleUid — membership rows are lifecycle-keyed (SPEC 13.1), and a
3305
2888
  * leave must resolve the selected principal-owned row even after the ACL row was narrowed or purged. */
3306
- async durableLeaveChannel(channel, generation, lifecycleUid = this.requireLifecycleUid("leaving a durable channel")) {
3307
- const reply = await this.requestDelivery("durableLeave", { channel, generation, lifecycleUid });
3308
- if (!reply.ok)
3309
- throw new Error(reply.error ?? "durable leave rejected");
3310
- }
3311
- /** Fail-closed async cleanup for a channel forced out by a LATE sub.allow refusal (the broker revoked
3312
- * the live read). The sync sub callback can't await, so this RETRIES the Plane-3 tombstone with capped
3313
- * backoff UNTIL IT SUCCEEDS (or the endpoint stops) — the §7 boundary always closes once the manager
3314
- * is reachable, never a silent give-up. While pending, the channel is tracked in
3315
- * {@link pendingDurableLeave} and surfaced via {@link pendingDurableLeaves} (the connector shows it in
3316
- * `cotal_channels` as `durable-unclosed`, never ordinary absence). The generation is kept the whole
3317
- * time. Authoritative closure of a revoked membership is also handled by revocation (rotate creds + tear down). */
3318
- async closeRefusedMembership(channel, generation) {
3319
- this.pendingDurableLeave.set(channel, generation);
3320
- for (let attempt = 0;; attempt++) {
3321
- if (this.stopped)
3322
- return;
3323
- try {
3324
- await this.durableLeaveChannel(channel, generation);
3325
- this.plane3Channels.delete(channel);
3326
- this.pendingDurableLeave.delete(channel);
3327
- return;
3328
- }
3329
- catch (e) {
3330
- if (attempt === 0)
3331
- this.emitRecoverable(new Error(`channel "${channel}": Plane-3 durable membership (generation ${generation}) not yet tombstoned after a refused live sub - retrying; §7 boundary may be open until it succeeds (${e.message})`));
3332
- await this.membershipPause(attempt);
3333
- }
3334
- }
2889
+ durableLeaveChannel(channel, generation, lifecycleUid) {
2890
+ return this.durable.durableLeaveChannel(channel, generation, lifecycleUid);
3335
2891
  }
3336
2892
  /** Channels with a Plane-3 durable membership whose §7 tombstone is still pending after a refused live
3337
- * sub (see {@link closeRefusedMembership}) — surfaced by the connector as a `durable-unclosed` state so
2893
+ * sub (see {@link EndpointDurable.closeRefusedMembership}) — surfaced by the connector as a `durable-unclosed` state so
3338
2894
  * it is never presented as ordinary "not subscribed". */
3339
2895
  pendingDurableLeaves() {
3340
- return [...this.pendingDurableLeave.keys()];
2896
+ return this.durable.pendingDurableLeaves();
3341
2897
  }
3342
- /** A control request that found NO responder — open / manager-less (no privileged control plane),
3343
- * distinct from a responder that errored. nats.js surfaces it as NoRespondersError, or a RequestError
3344
- * whose `isNoResponders()` is true. */
2898
+ /** Forwards to the anycast component's {@link EndpointAnycast.isNoResponders}. */
3345
2899
  isNoResponders(e) {
3346
- return e instanceof NoRespondersError || (e instanceof RequestError && e.isNoResponders());
2900
+ return this.anycastRail.isNoResponders(e);
3347
2901
  }
3348
- /** Holder side of a take (SPEC §8.1): ask the delivery daemon to record this endpoint's take of the
3349
- * request at `seq`, for the copy with `count` deliveries. Never throws; a take the daemon could
3350
- * not decide is reported as held, with what the operator has to do when that is anything. */
3351
- async takeAnycast(role, seq, id, count, epoch, nak) {
3352
- const nc = this.nc;
3353
- if (!nc)
3354
- return { taken: false, drop: false, reason: "daemon-down", detail: this.notLiveMsg() };
3355
- const held = (reason, detail) => ({ taken: false, drop: false, reason, detail });
3356
- const subject = takeSubject(this.space, role, this.owner, this.actor);
3357
- const body = { from: { id: this.card.id, name: this.card.name }, seq, id, count, epoch };
3358
- let reply;
3359
- try {
3360
- const m = await this.requestBoundReply(nc, subject, JSON.stringify(body), `${subject}.reply.${randomUUID()}`, ANYCAST_TAKE_TIMEOUT_MS);
3361
- reply = m.json();
3362
- }
3363
- catch (e) {
3364
- if (isPermissionDenied(e))
3365
- return held("credential-outdated", "this seat's credential was minted before anycast takes existed, so it cannot take role requests; respawn the seat to get a current credential");
3366
- if (this.isNoResponders(e))
3367
- return this.takeResponderMissing();
3368
- return held("daemon-down", `the delivery daemon did not answer the take: ${e.message}`);
3369
- }
3370
- if (reply.ok)
3371
- return { taken: true };
3372
- // A mismatch can mean the stream was recreated under this consumer, which resumes on the new
3373
- // stream: read its creation time again, so the copies delivered from here on carry it. When the
3374
- // time moved, this copy is nakked, so the broker delivers it again at once with the new time. A
3375
- // redelivery that still mismatches carries the time read here, so it is forgotten, not nakked.
3376
- if (reply.code === "mismatch") {
3377
- const current = await this.readTaskEpoch().catch(() => undefined);
3378
- if (current !== undefined && current !== epoch)
3379
- nak();
3380
- }
3381
- if (reply.code === "cancelled" || reply.code === "taken" || reply.code === "gone" || reply.code === "mismatch")
3382
- return { taken: false, drop: true, reason: reply.code, detail: reply.error };
3383
- return held("daemon-busy", reply.error);
3384
- }
3385
- /** No responder on the take rail: an older daemon answers the probe op as unsupported, and a
3386
- * stopped one does not answer at all. */
3387
- async takeResponderMissing() {
3388
- const held = (reason, detail) => ({ taken: false, drop: false, reason, detail });
3389
- let reply;
3390
- try {
3391
- reply = await this.requestDelivery(ANYCAST_TAKES_OP, {}, ANYCAST_TAKE_TIMEOUT_MS);
3392
- }
3393
- catch {
3394
- return held("daemon-down", "no delivery daemon is answering on this mesh, so role requests wait on the queue until one does");
3395
- }
3396
- if (!reply.ok && /not supported on the delivery control service/.test(reply.error ?? ""))
3397
- return held("daemon-outdated", "the delivery daemon predates anycast takes, so this seat holds role requests until the daemon is restarted at this version (`cotal up` runs it)");
3398
- if (!reply.ok && reply.error?.includes(ANYCAST_RECORDS_CREDENTIAL_OUTDATED))
3399
- return held("daemon-outdated", `this seat holds role requests until the delivery daemon can record takes: ${ANYCAST_RECORDS_CREDENTIAL_OUTDATED}`);
3400
- return held("daemon-down", "the delivery daemon is not answering takes, so role requests wait on the queue until it does");
2902
+ /** Forwards to the anycast component's {@link EndpointAnycast.takeAnycast}. */
2903
+ takeAnycast(role, seq, id, count, epoch, nak) {
2904
+ return this.anycastRail.takeAnycast(role, seq, id, count, epoch, nak);
3401
2905
  }
3402
2906
  /** The status of one of this endpoint's own anycast requests, from the delivery daemon's record
3403
2907
  * or, with no record, from the queue (SPEC §8.1). `id` narrows the answer to that request. Throws
3404
2908
  * on an open mesh, which runs no delivery daemon. */
3405
- async anycastStatus(seq, id) {
3406
- return this.anycastRequest(ANYCAST_STATUS_OP, seq, id);
2909
+ anycastStatus(seq, id) {
2910
+ return this.anycastRail.anycastStatus(seq, id);
3407
2911
  }
3408
2912
  /** Cancel one of this endpoint's own anycast requests while it waits. A request a holder already
3409
2913
  * took is refused, and the returned status names the taker. */
3410
- async cancelAnycast(seq, id) {
3411
- return this.anycastRequest(ANYCAST_CANCEL_OP, seq, id);
3412
- }
3413
- async anycastRequest(op, seq, id) {
3414
- if (!this.authed)
3415
- throw new Error("an open mesh runs no delivery daemon, so it keeps no record of anycast requests");
3416
- if (!isAnycastSeq(seq))
3417
- throw new Error(`seq must be a whole number of at least 1, got ${seq}`);
3418
- let reply;
3419
- try {
3420
- reply = await this.requestDelivery(op, { seq, ...(id !== undefined ? { id } : {}) }, 10_000);
3421
- }
3422
- catch (e) {
3423
- if (this.isNoResponders(e))
3424
- throw new Error("no delivery daemon is answering on this mesh, so the request's record cannot be read");
3425
- throw e;
3426
- }
3427
- if (!reply.ok) {
3428
- if (/not supported on the delivery control service/.test(reply.error ?? ""))
3429
- throw new Error("the delivery daemon predates anycast request status; restart it at this version (`cotal up` runs it)");
3430
- throw new Error(reply.error ?? `${op} failed`);
3431
- }
3432
- return reply.data;
2914
+ cancelAnycast(seq, id) {
2915
+ return this.anycastRail.cancelAnycast(seq, id);
3433
2916
  }
3434
2917
  /** The boot durable self-join and its reconcile, and the membership read the leave path uses, of
3435
2918
  * this endpoint. Every dependency is read when it is used, and every endpoint method is looked up
@@ -3443,7 +2926,7 @@ export class CotalEndpoint extends EventEmitter {
3443
2926
  requireLifecycleUid: (what) => this.requireLifecycleUid(what),
3444
2927
  deliveryClassFresh: (channel) => this.deliveryClassFresh(channel),
3445
2928
  durableJoinChannel: (channel) => this.durableJoinChannel(channel),
3446
- membershipPause: (attempt) => this.membershipPause(attempt),
2929
+ membershipPause: (attempt) => this.reconnection.membershipPause(attempt),
3447
2930
  isNoResponders: (e) => this.isNoResponders(e),
3448
2931
  emitRecoverable: (err) => this.emitRecoverable(err),
3449
2932
  });
@@ -3454,398 +2937,55 @@ export class CotalEndpoint extends EventEmitter {
3454
2937
  async fetchMemberships(channel) {
3455
2938
  return this.bootMemberships.fetchMemberships(channel);
3456
2939
  }
3457
- /** Forwards to the boot-membership component's {@link EndpointBootMemberships.armBootDurableMemberships}. */
3458
- async armBootDurableMemberships() {
3459
- return this.bootMemberships.armBootDurableMemberships();
3460
- }
3461
2940
  /** True if this session holds an established Plane-3 durable membership for `channel` (in `plane3Channels`).
3462
2941
  * Drives the membership-aware delivery-health surface: a joined durable channel that is NOT yet a member
3463
2942
  * (boot self-join pending / daemon down) must render degraded, never "active" off a live lease alone. */
3464
2943
  hasDurableMembership(channel) {
3465
2944
  return this.bootMemberships.hasDurableMembership(channel);
3466
2945
  }
3467
- /** Lazily obtain a JetStream manager — so a non-consuming endpoint (e.g. the supervisor,
3468
- * consume:false) can still pre-create others' durables. */
3469
- async manager() {
3470
- if (!this.nc)
3471
- throw new Error(this.notLiveMsg());
3472
- this.jsm ??= await jetstreamManager(this.nc);
3473
- return this.jsm;
3474
- }
3475
- /** Bind this endpoint's durable consumers: DM inbox, chat, and (if a role) the task queue. */
3476
- async startConsumers() {
3477
- if (!this.jsm)
3478
- throw new Error(this.notLiveMsg());
3479
- // Unicast: this instance's private DM inbox, keyed on this endpoint's owner+actor principal. Open
3480
- // mode self-creates; auth mode BINDS a durable the provisioner pre-created (agents are denied
3481
- // CONSUMER.CREATE on DM_<space>, since the create-time filter_subject is the attack surface).
3482
- const ownUid = this.requireLifecycleUid("consuming the DM inbox");
3483
- if (!this.authed) {
3484
- // Open-mode self-create rides the SAME per-lifecycle ensure as the privileged pre-create: an
3485
- // existing `dm_…-<uid>` durable (this lifecycle's own restart) is kept with its ORIGINAL
3486
- // activation frontier; a fresh lifecycle captures its frontier at creation.
3487
- await this.ensureDmDurable(this.owner, this.actor, ownUid, {
3488
- ackWaitMs: this.ackWaitMs,
3489
- inactiveThresholdMs: this.inactiveThresholdMs,
3490
- });
3491
- }
3492
- const dm = dmDurable(this.owner, this.actor, ownUid);
3493
- try {
3494
- await this.pump(dmStream(this.space), dm, { inbox: true });
3495
- }
3496
- catch (e) {
3497
- // Auth mode cannot create the durable, so every rebind fails the same way until the session is
3498
- // replaced. The typed error lets a caller name that route instead of a bare "consumer not found".
3499
- if (this.authed && isConsumerNotFound(e))
3500
- throw new DmDurableMissingError(dmStream(this.space), dm);
3501
- throw e;
3502
- }
3503
- // Plane-3 (SPEC §8): bind + pump our per-member DELIVER durable (`dlv_<id>`) — the re-authorized
3504
- // durable-backstop channel copies the trusted reader transfers to us. No-op when it isn't present
3505
- // (open mode / un-provisioned). Auth-only feature; the pump self-guards on the durable's existence.
3506
- await this.pumpDlv();
3507
- // Multicast: open a native CORE subscription for each channel (live, manager-free, broker-enforced
3508
- // by sub.allow) — boot + runtime joins use the SAME path; there is no per-instance chat durable.
3509
- // The durable backstop (a busy/offline turn) is Plane-3 (auth: membership established by the agent's
3510
- // self-join, the delivery daemon's fan-out writer + trusted reader deliver via the `dlv_<id>` pump
3511
- // above; open dev mode is live-only — the durable plane needs the daemon's trusted reader, the
3512
- // security boundary). Per-
3513
- // channel history is the explicit replay-gated backfill, on FIRST connect only; a reconnect reopens
3514
- // the subs without re-backfilling (the durable backstop redelivers any missed window via dlv).
3515
- if (this.channels.length) {
3516
- // Arm the per-channel join watermarks BEFORE opening the subs: the backfill reads <= frontier and
3517
- // the core-sub delivers > frontier, so they never overlap (first connect). On reconnect we reopen
3518
- // without arming/backfilling.
3519
- const armed = this.firstConnect ? await this.armJoin(this.channels) : undefined;
3520
- for (const ch of this.channels)
3521
- this.subscribeChat(ch);
3522
- await this.confirmChatSub();
3523
- if (armed)
3524
- await this.backfillArmed(armed, this.backfillFloor);
3525
- }
3526
- // First connect, auth mode: self-join BOOT durable channels via the server-side delivery daemon
3527
- // (it owns membership now — there is no manager-written boot membership). Seeds plane3Channels so a
3528
- // later leave can tombstone the §7 boundary; idempotent on relaunch. Open mode has no Plane-3.
3529
- if (this.firstConnect && this.authed && this.channels.length)
3530
- await this.armBootDurableMemberships();
3531
- this.firstConnect = false;
3532
- // Anycast: a shared work-queue consumer for our role — one instance grabs each task.
3533
- // Open mode self-creates; auth mode BINDS the provisioner-pre-created svc_<role>
3534
- // durable (agents are denied CONSUMER.CREATE on TASK_<space>, since the create-time
3535
- // filter is the cross-role-drain attack surface — see provisionTaskQueue).
3536
- if (this.card.role) {
3537
- if (!this.authed) {
3538
- await this.jsm.consumers.add(taskStream(this.space), taskDurableConfig(this.space, this.card.role, { ackWaitMs: this.ackWaitMs }));
3539
- }
3540
- await this.pump(taskStream(this.space), taskDurable(this.card.role), this.authed ? { takeRole: this.card.role } : {});
3541
- }
3542
- }
3543
- /** Drive one consumer: decode and hand each message to listeners with ack control. Our own sends are
3544
- * delivered too: on the DM inbox and the role queue they were addressed to us, so none is an echo,
3545
- * and acking one unseen on the work queue would delete the only copy of the request. */
3546
- async pump(stream, durable, opts = {}) {
3547
- if (!this.js)
3548
- throw new Error(this.notLiveMsg());
3549
- const consumer = opts.takeRole === undefined
3550
- ? await this.js.consumers.get(stream, durable)
3551
- : await this.bindTaskConsumer(stream, durable);
3552
- const ackWaitMs = await ackWaitOf(consumer);
3553
- const msgs = await consumer.consume();
3554
- this.streamMsgs.push(msgs);
3555
- if (opts.inbox)
3556
- this.watchInbox(msgs, stream, durable);
3557
- void (async () => {
3558
- for await (const m of msgs) {
3559
- const authed = this.authenticateStreamMsg(m);
3560
- if (!authed)
3561
- continue;
3562
- const { msg, parsed } = authed;
3563
- const delivery = durableDelivery(m, ackWaitMs);
3564
- // On an auth mesh a role request carries its take: the holder records it with the delivery
3565
- // daemon before showing the request, so its sender can cancel it until then (SPEC §8.1).
3566
- // The copy carries the creation time of the stream it came from, read at bind.
3567
- const role = opts.takeRole;
3568
- if (role !== undefined) {
3569
- const epoch = this.taskEpoch;
3570
- delivery.take = () => this.takeAnycast(role, m.seq, msg.id, m.info.deliveryCount, epoch, () => m.nak());
3571
- }
3572
- this.emit("message", authenticatedMessage(msg, parsed), delivery, {
3573
- historical: false,
3574
- kind: kindFromParsed(parsed.kind),
3575
- });
3576
- }
3577
- })().catch((e) => {
3578
- if (!this.stopped)
3579
- this.emit("error", e);
3580
- });
3581
- }
3582
- /** Bind the role consumer and read the TASK stream's creation time on both sides of the bind, so
3583
- * the time belongs to the stream the consumer was bound on (SPEC §8.1). */
3584
- async bindTaskConsumer(stream, durable) {
3585
- for (let attempt = 0; attempt < 3; attempt++) {
3586
- const before = await this.readTaskEpoch();
3587
- const consumer = await this.js.consumers.get(stream, durable);
3588
- if (before === (await this.readTaskEpoch()))
3589
- return consumer;
3590
- }
3591
- throw new Error(`the ${stream} stream was recreated while its role consumer was binding; reconnect to bind it again`);
3592
- }
3593
- /** Read the TASK stream's creation time into {@link taskEpoch}. */
3594
- async readTaskEpoch() {
3595
- const epoch = (await (await this.manager()).streams.info(taskStream(this.space))).created;
3596
- this.taskEpoch = epoch;
3597
- return epoch;
3598
- }
3599
- /** Warn once when the broker reports this endpoint's own DM inbox missing while the connection is
3600
- * up, as after a store reset that the client's reconnect rode through, or after a manager restart
3601
- * deletes the inbox. nats.js keeps checking and resumes pulling if the inbox comes back, so this
3602
- * only reports. A `consumer_deleted` status is the consumer going away, so it warns at once. A
3603
- * not-found can be a passing state, so that warning waits for a second report; the several 409s a
3604
- * delete answers pending pulls with count once. A pull means the consumer was found again, which
3605
- * re-arms the warning. The loop ends when the consumer is stopped, by `stop()` or by a rebuild
3606
- * replacing this connection. */
3607
- watchInbox(msgs, stream, durable) {
3608
- const boundNc = this.nc;
3609
- void (async () => {
3610
- let absences = 0;
3611
- let deleted = false;
3612
- for await (const s of msgs.status()) {
3613
- if (this.stopped || this.nc !== boundNc)
3614
- break;
3615
- if (s.type === "next") {
3616
- absences = 0;
3617
- deleted = false;
3618
- continue;
3619
- }
3620
- if (s.type === "consumer_deleted") {
3621
- if (deleted)
3622
- continue;
3623
- deleted = true;
3624
- absences = 1; // the deletion itself is the second report: warn on this one
3625
- }
3626
- else if (s.type !== "consumer_not_found" && s.type !== "stream_not_found")
3627
- continue;
3628
- if (++absences === 2)
3629
- this.emitRecoverable(new Error(`DM inbox missing: the broker reports consumer "${durable}" on stream "${stream}" missing, so direct ` +
3630
- "messages to this endpoint are not delivered. The endpoint keeps checking; if the inbox does not " +
3631
- "come back, end this session and start a new one"));
3632
- }
3633
- })().catch((e) => {
3634
- if (!this.stopped)
3635
- this.emit("error", e);
3636
- });
3637
- }
3638
- /** Decode one stream copy and apply the authenticity guard (fail closed): the sender is encoded in
3639
- * the subject, which the server policed who could publish. The payload `from` is advisory — it
3640
- * must match, and a missing `from` or an unparseable subject on a delivery is itself an anomaly.
3641
- * A rejected copy is `term()`ed (permanently invalid, never redelivered) and reported, and
3642
- * `undefined` returns, so no handler ever sees it. */
3643
- authenticateStreamMsg(m) {
3644
- let msg;
3645
- try {
3646
- msg = m.json();
3647
- }
3648
- catch (e) {
3649
- m.term(); // undecodable — never redeliver
3650
- this.emit("error", e);
3651
- return undefined;
3652
- }
3653
- if (!isRecord(msg) || !isUsableMessageId(msg.id)) {
3654
- m.term(); // malformed envelope (SPEC sec 5): absent/non-string id — permanently invalid
3655
- this.emit("error", new Error(`dropped message on ${m.subject}: absent or non-string id`));
3656
- return undefined;
3657
- }
3658
- const parsed = parseSubject(m.subject);
3659
- if (!parsed || !isFromSubjectSender(msg, parsed)) {
3660
- m.term();
3661
- this.emit("error", new Error(`dropped message on ${m.subject}: payload from ${msg.from?.id ?? "(none)"} ` +
3662
- `does not match subject sender ${parsed?.sender ?? "(unparseable)"}`));
3663
- return undefined;
3664
- }
3665
- return { msg, parsed };
3666
- }
3667
- /** Bind this endpoint's own existing DM durable and drive it serially (EndpointOptions.dmOnly).
3668
- * The bind is one CONSUMER.INFO on `dm_<owner>-<actor>-<uid>`; reading is MSG.NEXT with a batch
3669
- * of one, and the next copy reaches the handler only after the previous handler settles. */
3670
- async bindDmOnly(mode) {
3671
- if (!this.js)
3672
- throw new Error(this.notLiveMsg());
3673
- const stream = dmStream(this.space);
3674
- const durable = dmDurable(this.owner, this.actor, this.requireLifecycleUid("consuming the DM inbox"));
3675
- let consumer;
3676
- try {
3677
- consumer = await this.js.consumers.get(stream, durable);
3678
- }
3679
- catch (e) {
3680
- if (isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
3681
- throw new DmDurableMissingError(stream, durable);
3682
- throw new DmBindRefusedError(stream, durable, e);
3683
- }
3684
- const ackWaitMs = await ackWaitOf(consumer); // cached by the bind's own CONSUMER.INFO, no request
3685
- // A rebind after reconnect must not overlap the previous epoch's running handler. A handler that
3686
- // does not settle within the stop bound fails this bind; the retry loop tries again.
3687
- if (this.dmOnlyInFlight) {
3688
- const settleMs = mode.settleTimeoutMs ?? 30_000;
3689
- await withDeadline(this.dmOnlyInFlight, settleMs, () => new Error(`DM-only rebind waited ${settleMs}ms for the previous handler to settle; not reading the next DM yet`));
3690
- }
3691
- const msgs = await consumer.consume({ max_messages: 1 });
3692
- this.streamMsgs.push(msgs);
3693
- // The epoch this loop belongs to. nats.js can yield copies it already received after stop() began
3694
- // or after a rebuild replaced the connection (a stacked pull after a missed-heartbeat reset hands
3695
- // over several at once). Such a copy never reaches the handler and is neither acked nor nak'd:
3696
- // the connection is closing or closed, so any reply could be lost, and the broker redelivers an
3697
- // unacked copy after the durable's ack_wait to whichever epoch binds next.
3698
- const boundNc = this.nc;
3699
- const retired = () => this.stopped || this.nc !== boundNc || !boundNc || boundNc.isClosed();
3700
- void (async () => {
3701
- for await (const m of msgs) {
3702
- if (retired())
3703
- break;
3704
- const authed = this.authenticateStreamMsg(m);
3705
- if (!authed)
3706
- continue;
3707
- if (authed.parsed.kind !== "inst") {
3708
- m.term(); // the DM stream filter admits only inst.* subjects; anything else is not a DM
3709
- continue;
3710
- }
3711
- const run = Promise.resolve().then(() => mode.handler(authenticatedMessage(authed.msg, authed.parsed), dmOnlyDelivery(m, ackWaitMs, boundNc), {
3712
- historical: false,
3713
- kind: "dm",
3714
- }));
3715
- const flight = run.then(() => { }, () => { });
3716
- this.dmOnlyInFlight = flight;
3717
- try {
3718
- await run;
3719
- }
3720
- catch (e) {
3721
- this.emit("error", e instanceof Error ? e : new Error(String(e)));
3722
- }
3723
- finally {
3724
- if (this.dmOnlyInFlight === flight)
3725
- this.dmOnlyInFlight = undefined;
3726
- }
3727
- }
3728
- })().catch((e) => {
3729
- if (!this.stopped)
3730
- this.emit("error", e);
3731
- });
3732
- }
3733
- /** Open a native core subscription to a channel's live feed (the manager-free live read path,
3734
- * broker-enforced by `sub.allow`). At-most-once — no replay, no ack; it is the live delivery for
3735
- * every channel (boot + runtime). For a `durable` channel it is also the low-latency wake-hint
3736
- * alongside the Plane-3 durable copy, coalesced by the receiver's id-dedup. Drops our own echo +
3737
- * spoofed senders. */
3738
- subscribeChat(channel) {
3739
- if (!this.nc || this.chatSubs.has(channel))
3740
- return;
3741
- this.chatSubDenied.delete(channel);
3742
- const subject = chatSubject(this.space, "*", "*", channel);
3743
- const sub = this.nc.subscribe(subject, {
3744
- callback: (err, m) => {
3745
- if (err) {
3746
- // async sub.allow refusal (or sub error): the live feed for this channel is dead — never a
3747
- // leak (the broker refused it). Drop the channel from local joined state even if it was
3748
- // already treated as joined — a LATE refusal beyond the confirm window: conformance #13
3749
- // "drop on late refusal". (During the join's own confirm the channel isn't pushed yet, so
3750
- // this fires nothing then; joinChannel reads `chatSubDenied` and throws cleanly.) Either way
3751
- // the refusal is reported from here, by that throw or the leave below, so watchStatus skips it.
3752
- if (err instanceof PermissionViolationError)
3753
- this.chatSubRefusals.add(err);
3754
- this.chatSubDenied.add(channel);
3755
- this.chatSubs.delete(channel);
3756
- const i = this.channels.indexOf(channel);
3757
- if (i >= 0) {
3758
- this.channels.splice(i, 1);
3759
- // A late sub.allow refusal forces this agent out of the channel (the broker revoked its live
3760
- // read). If it held a Plane-3 durable membership, the §7 boundary must close too. This sub
3761
- // callback can't await, so a fail-closed async helper RETRIES the tombstone (backoff) UNTIL it
3762
- // succeeds, clearing the mirror only then; while pending it is surfaced via cotal_channels —
3763
- // never a silent drop, never lost retry state.
3764
- const gen = this.plane3Channels.get(channel);
3765
- if (gen !== undefined)
3766
- void this.closeRefusedMembership(channel, gen);
3767
- this.emit("error", new Error(`left channel "${channel}": its live subscription was refused by the broker`, { cause: err }));
3768
- }
3769
- return;
3770
- }
3771
- const parsed = parseSubject(m.subject);
3772
- if (!parsed || parsed.kind !== "chat")
3773
- return;
3774
- let msg;
3775
- try {
3776
- msg = m.json();
3777
- }
3778
- catch (e) {
3779
- this.emit("error", e);
3780
- return;
3781
- }
3782
- if (!isRecord(msg) || !isUsableMessageId(msg.id))
3783
- return; // malformed envelope (SPEC sec 5) — live is at-most-once: drop
3784
- if (!isFromSubjectSender(msg, parsed))
3785
- return; // spoof/malformed/old-shape-alias — drop (at-most-once)
3786
- if (msg.from.id === this.card.id)
3787
- return; // our own echo
3788
- const delivery = { ack: () => { }, nak: () => { }, durable: false }; // live = at-most-once, not acked
3789
- this.emit("message", authenticatedMessage(msg, parsed), delivery, {
3790
- historical: false,
3791
- kind: kindFromParsed(parsed.kind),
3792
- });
3793
- },
3794
- });
3795
- this.chatSubs.set(channel, sub);
3796
- }
3797
- /** Close a channel's core subscription (manager-free leave). */
3798
- unsubscribeChat(channel) {
3799
- const sub = this.chatSubs.get(channel);
3800
- if (sub) {
3801
- try {
3802
- sub.unsubscribe();
3803
- }
3804
- catch {
3805
- /* closing with the connection */
3806
- }
3807
- this.chatSubs.delete(channel);
3808
- }
3809
- this.chatSubDenied.delete(channel);
3810
- }
3811
- /** Confirm a just-opened core subscription was accepted by the broker. A `sub.allow` violation is
3812
- * async in NATS, so flush (round-trips the SUB) then settle briefly to let the refusal land — a
3813
- * denied subscribe must not read as a successful join (SPEC conformance #13). */
3814
- async confirmChatSub() {
3815
- if (!this.nc)
3816
- throw new Error("connection not established");
3817
- // flush() is the deterministic boundary: the broker's -ERR for an out-of-ACL SUB arrives BEFORE the
3818
- // PONG, so once flush resolves the subscribe callback has already recorded any denial. A flush
3819
- // FAILURE means the connection drained/closed mid-join — we have no confirmation, so let it throw
3820
- // (joinChannel fails closed) instead of swallowing it and continuing as if confirmed.
3821
- await this.nc.flush();
3822
- await new Promise((r) => setTimeout(r, 50));
3823
- }
3824
- /** The durable's info (rebind) or null (fresh — 404). Gates create/backfill to the join event
3825
- * and exposes the current `filter_subjects` for restart reconciliation. */
3826
- async consumerInfo(stream, durable) {
3827
- if (!this.jsm)
3828
- throw new Error(this.notLiveMsg());
3829
- try {
3830
- return await this.jsm.consumers.info(stream, durable);
3831
- }
3832
- catch (e) {
3833
- if (isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
3834
- return null; // structured absence — fresh durable
3835
- throw e;
3836
- }
3837
- }
3838
- /** Delete one named consumer, swallowing ONLY structured consumer/stream absence. */
3839
- async deleteConsumerIfPresent(stream, durable) {
3840
- if (!this.jsm)
3841
- throw new Error(this.notLiveMsg());
3842
- try {
3843
- await this.jsm.consumers.delete(stream, durable);
3844
- }
3845
- catch (e) {
3846
- if (!isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound, JetStreamApiCodes.StreamNotFound))
3847
- throw e;
3848
- }
2946
+ /** The durable consumers of this endpoint. Every dependency is read when it is used, so a field
2947
+ * assigned after construction is seen. */
2948
+ consumers = new EndpointConsumers({
2949
+ nc: () => this.nc,
2950
+ jsm: () => this.jsm,
2951
+ setJsm: (value) => { this.jsm = value; },
2952
+ js: () => this.js,
2953
+ space: () => this.space,
2954
+ owner: () => this.owner,
2955
+ actor: () => this.actor,
2956
+ card: () => this.card,
2957
+ authed: () => this.authed,
2958
+ channels: () => this.channels,
2959
+ ackWaitMs: () => this.ackWaitMs,
2960
+ inactiveThresholdMs: () => this.inactiveThresholdMs,
2961
+ firstConnect: () => this.firstConnect,
2962
+ setFirstConnect: (value) => { this.firstConnect = value; },
2963
+ backfillFloor: () => this.backfillFloor,
2964
+ streamMsgs: () => this.streamMsgs,
2965
+ taskEpoch: () => this.taskEpoch,
2966
+ setTaskEpoch: (value) => { this.taskEpoch = value; },
2967
+ stopped: () => this.stopped,
2968
+ dmOnlyInFlight: () => this.dmOnlyInFlight,
2969
+ setDmOnlyInFlight: (value) => { this.dmOnlyInFlight = value; },
2970
+ chatSubs: () => this.chatSubs,
2971
+ chatSubDenied: () => this.chatSubDenied,
2972
+ chatSubRefusals: () => this.chatSubRefusals,
2973
+ plane3Channels: () => this.plane3Channels,
2974
+ notLiveMsg: () => this.notLiveMsg(),
2975
+ requireLifecycleUid: (what) => this.requireLifecycleUid(what),
2976
+ ensureDmDurable: (owner, actor, lifecycleUid, opts) => this.provisioning.ensureDmDurable(owner, actor, lifecycleUid, opts),
2977
+ pumpDlv: () => this.deliveryPlane.pumpDlv(),
2978
+ armJoin: (channels) => this.armJoin(channels),
2979
+ backfillArmed: (frontiers, floorSeq) => this.backfillArmed(frontiers, floorSeq),
2980
+ armBootDurableMemberships: () => this.bootMemberships.armBootDurableMemberships(),
2981
+ takeAnycast: (role, seq, id, count, epoch, nak) => this.takeAnycast(role, seq, id, count, epoch, nak),
2982
+ emitRecoverable: (err) => this.emitRecoverable(err),
2983
+ closeRefusedMembership: (channel, generation) => this.durable.closeRefusedMembership(channel, generation),
2984
+ emit: (event, ...args) => this.emit(event, ...args),
2985
+ });
2986
+ /** Forwards to the consumers component's {@link EndpointConsumers.manager}. */
2987
+ manager() {
2988
+ return this.consumers.manager();
3849
2989
  }
3850
2990
  /** Current frontier (last sequence) of the chat stream — a channel's join watermark, the
3851
2991
  * focus-watermark a connector captures on entering `focus` (recall reads ambient after it), and
@@ -3858,22 +2998,14 @@ export class CotalEndpoint extends EventEmitter {
3858
2998
  }
3859
2999
  /** Whether this connection's account has a JetStream stream of this name. A missing stream is
3860
3000
  * false. Any other failure is thrown, so a caller does not treat an unread broker as absence. */
3861
- async streamRecorded(name) {
3862
- try {
3863
- await (await this.manager()).streams.info(name);
3864
- return true;
3865
- }
3866
- catch (e) {
3867
- if (isStreamNotFound(e))
3868
- return false;
3869
- throw e;
3870
- }
3001
+ streamRecorded(name) {
3002
+ return this.consumers.streamRecorded(name);
3871
3003
  }
3872
3004
  /** The bytes this connection's account holds in JetStream file storage, as `$JS.API.INFO`
3873
3005
  * reports them. A broker's `max_file_store` cap counts every account it serves, so this is a
3874
3006
  * lower bound on what that cap measures. */
3875
- async storedBytes() {
3876
- return (await (await this.manager()).getAccountInfo()).storage;
3007
+ storedBytes() {
3008
+ return this.consumers.storedBytes();
3877
3009
  }
3878
3010
  /** Phase 1 of a join: capture each channel's current CHAT stream frontier before opening the
3879
3011
  * core subscription. The frontier bounds the {@link backfillArmed} read (`seq <= frontier`),
@@ -3995,18 +3127,6 @@ export class CotalEndpoint extends EventEmitter {
3995
3127
  async publishPresence() {
3996
3128
  return this.presence.publishPresence();
3997
3129
  }
3998
- /** #1356: drop the presence-refusal record when the connection that OBSERVED those refusals goes
3999
- * away. "This bucket is refusing writes" is a claim about a specific broker connection; once that
4000
- * connection is torn down or rebuilt the claim has no remaining basis, and a later failure on a
4001
- * fresh connection must establish it again from its own evidence.
4002
- *
4003
- * Cleared at the SOURCE rather than guarded at each reader, because a guard protects one consumer
4004
- * and clearing protects every consumer, including ones not yet written. Measured: without this, a
4005
- * failed bind against an unreachable server still reported the presence-refusal sentence while the
4006
- * endpoint's own `connectionIssue` already said "connection refused". */
4007
- clearPresenceWriteFailure() {
4008
- return this.presence.clearPresenceWriteFailure();
4009
- }
4010
3130
  /** #1356: the presence bucket has been refusing writes since this time, or `undefined` when the
4011
3131
  * last publish succeeded. Cleared by a successful write that is the latest evidence on its
4012
3132
  * epoch (#1461), so a survived blip reads as healthy and only a SUSTAINED failure carries a
@@ -4033,14 +3153,6 @@ export class CotalEndpoint extends EventEmitter {
4033
3153
  async readPresenceOnce() {
4034
3154
  return this.presence.readPresenceOnce();
4035
3155
  }
4036
- /** Forwards to the channel discovery component's {@link EndpointChannelDiscovery.startChannelWatch}. */
4037
- async startChannelWatch() {
4038
- return this.channelDiscovery.startChannelWatch();
4039
- }
4040
- /** Forwards to the channel discovery component's {@link EndpointChannelDiscovery.readChannelsOnce}. */
4041
- async readChannelsOnce() {
4042
- return this.channelDiscovery.readChannelsOnce();
4043
- }
4044
3156
  sweep() {
4045
3157
  return this.presence.sweep();
4046
3158
  }