@cotal-ai/core 0.168.0 → 0.170.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (118) hide show
  1. package/dist/agent-file.d.ts +9 -5
  2. package/dist/agent-file.d.ts.map +1 -1
  3. package/dist/agent-file.js +30 -17
  4. package/dist/agent-file.js.map +1 -1
  5. package/dist/anycast-requests.d.ts +8 -1
  6. package/dist/anycast-requests.d.ts.map +1 -1
  7. package/dist/anycast-requests.js +47 -0
  8. package/dist/anycast-requests.js.map +1 -1
  9. package/dist/backup-config.d.ts +5 -2
  10. package/dist/backup-config.d.ts.map +1 -1
  11. package/dist/backup-config.js +7 -2
  12. package/dist/backup-config.js.map +1 -1
  13. package/dist/backup.d.ts +6 -0
  14. package/dist/backup.d.ts.map +1 -1
  15. package/dist/backup.js +11 -4
  16. package/dist/backup.js.map +1 -1
  17. package/dist/connector-setup.d.ts +2 -0
  18. package/dist/connector-setup.d.ts.map +1 -1
  19. package/dist/connector.d.ts +8 -11
  20. package/dist/connector.d.ts.map +1 -1
  21. package/dist/control-exchange.d.ts +114 -0
  22. package/dist/control-exchange.d.ts.map +1 -0
  23. package/dist/control-exchange.js +416 -0
  24. package/dist/control-exchange.js.map +1 -0
  25. package/dist/endpoint-binding.d.ts.map +1 -1
  26. package/dist/endpoint-binding.js +2 -0
  27. package/dist/endpoint-binding.js.map +1 -1
  28. package/dist/endpoint-call.d.ts +2 -1
  29. package/dist/endpoint-call.d.ts.map +1 -1
  30. package/dist/endpoint-call.js +14 -7
  31. package/dist/endpoint-call.js.map +1 -1
  32. package/dist/endpoint-channel-discovery.d.ts +102 -0
  33. package/dist/endpoint-channel-discovery.d.ts.map +1 -0
  34. package/dist/endpoint-channel-discovery.js +170 -0
  35. package/dist/endpoint-channel-discovery.js.map +1 -0
  36. package/dist/endpoint-control-plane.d.ts +204 -0
  37. package/dist/endpoint-control-plane.d.ts.map +1 -0
  38. package/dist/endpoint-control-plane.js +627 -0
  39. package/dist/endpoint-control-plane.js.map +1 -0
  40. package/dist/endpoint-delivery-plane.d.ts +337 -0
  41. package/dist/endpoint-delivery-plane.d.ts.map +1 -0
  42. package/dist/endpoint-delivery-plane.js +1291 -0
  43. package/dist/endpoint-delivery-plane.js.map +1 -0
  44. package/dist/endpoint-durable-backstop.d.ts +249 -0
  45. package/dist/endpoint-durable-backstop.d.ts.map +1 -0
  46. package/dist/endpoint-durable-backstop.js +485 -0
  47. package/dist/endpoint-durable-backstop.js.map +1 -0
  48. package/dist/endpoint-envelope.d.ts +2 -1
  49. package/dist/endpoint-envelope.d.ts.map +1 -1
  50. package/dist/endpoint-envelope.js +9 -3
  51. package/dist/endpoint-envelope.js.map +1 -1
  52. package/dist/endpoint-history.d.ts +370 -0
  53. package/dist/endpoint-history.d.ts.map +1 -0
  54. package/dist/endpoint-history.js +969 -0
  55. package/dist/endpoint-history.js.map +1 -0
  56. package/dist/endpoint-inbound.d.ts +10 -0
  57. package/dist/endpoint-inbound.d.ts.map +1 -0
  58. package/dist/endpoint-inbound.js +28 -0
  59. package/dist/endpoint-inbound.js.map +1 -0
  60. package/dist/endpoint-liveness.d.ts +105 -0
  61. package/dist/endpoint-liveness.d.ts.map +1 -0
  62. package/dist/endpoint-liveness.js +223 -0
  63. package/dist/endpoint-liveness.js.map +1 -0
  64. package/dist/endpoint-messaging.d.ts +229 -0
  65. package/dist/endpoint-messaging.d.ts.map +1 -0
  66. package/dist/endpoint-messaging.js +420 -0
  67. package/dist/endpoint-messaging.js.map +1 -0
  68. package/dist/endpoint-presence.d.ts +15 -0
  69. package/dist/endpoint-presence.d.ts.map +1 -1
  70. package/dist/endpoint-presence.js +35 -0
  71. package/dist/endpoint-presence.js.map +1 -1
  72. package/dist/endpoint-serve.d.ts +11 -1
  73. package/dist/endpoint-serve.d.ts.map +1 -1
  74. package/dist/endpoint-serve.js +42 -5
  75. package/dist/endpoint-serve.js.map +1 -1
  76. package/dist/endpoint-subjects.d.ts +3 -0
  77. package/dist/endpoint-subjects.d.ts.map +1 -1
  78. package/dist/endpoint-subjects.js +3 -0
  79. package/dist/endpoint-subjects.js.map +1 -1
  80. package/dist/endpoint-subscriptions.d.ts +199 -0
  81. package/dist/endpoint-subscriptions.d.ts.map +1 -0
  82. package/dist/endpoint-subscriptions.js +543 -0
  83. package/dist/endpoint-subscriptions.js.map +1 -0
  84. package/dist/endpoint.d.ts +96 -344
  85. package/dist/endpoint.d.ts.map +1 -1
  86. package/dist/endpoint.js +518 -3854
  87. package/dist/endpoint.js.map +1 -1
  88. package/dist/index.d.ts +3 -1
  89. package/dist/index.d.ts.map +1 -1
  90. package/dist/index.js +5 -1
  91. package/dist/index.js.map +1 -1
  92. package/dist/launch-material.d.ts +9 -3
  93. package/dist/launch-material.d.ts.map +1 -1
  94. package/dist/launch-material.js +22 -2
  95. package/dist/launch-material.js.map +1 -1
  96. package/dist/provision-jwt.d.ts.map +1 -1
  97. package/dist/provision-jwt.js +1 -0
  98. package/dist/provision-jwt.js.map +1 -1
  99. package/dist/provision-permissions.d.ts +1 -1
  100. package/dist/provision-permissions.d.ts.map +1 -1
  101. package/dist/provision-permissions.js +10 -1
  102. package/dist/provision-permissions.js.map +1 -1
  103. package/dist/remote-manager-authority.d.ts +1 -1
  104. package/dist/run-host.d.ts +4 -1
  105. package/dist/run-host.d.ts.map +1 -1
  106. package/dist/run-journal.d.ts +2 -0
  107. package/dist/run-journal.d.ts.map +1 -1
  108. package/dist/run-journal.js +1 -1
  109. package/dist/run-journal.js.map +1 -1
  110. package/dist/run-record.d.ts +4 -0
  111. package/dist/run-record.d.ts.map +1 -1
  112. package/dist/run-record.js +36 -0
  113. package/dist/run-record.js.map +1 -1
  114. package/dist/space-quiescence-resources.d.ts +30 -0
  115. package/dist/space-quiescence-resources.d.ts.map +1 -0
  116. package/dist/space-quiescence-resources.js +45 -0
  117. package/dist/space-quiescence-resources.js.map +1 -0
  118. package/package.json +5 -1
@@ -1,3 +1,4 @@
1
+ export { MULTI_FILTER_BATCH, MULTI_FILTER_READ_CONCURRENCY } from "./endpoint-history.js";
1
2
  import { type NativeConnectionBinding } from "./native-connection.js";
2
3
  import { EventEmitter } from "node:events";
3
4
  import { connect, type NatsConnection } from "@nats-io/transport-node";
@@ -8,13 +9,13 @@ import { type SecretStoreIdentity } from "./secret-store.js";
8
9
  import { type ResolvedService, type SubmitAndFollowGoalOptions } from "./endpoint-invoke.js";
9
10
  import type { EpCaller, EpPrincipal, IssuedCaller, PrincipalAuthority } from "./endpoint-subjects.js";
10
11
  import { type EpPrincipalCommandDef } from "./endpoint-serve.js";
11
- import type { ClusterDocument } from "./endpoint-cluster.js";
12
12
  import type { EndpointReply } from "./endpoint-envelope.js";
13
13
  import type { CompiledContract } from "./schema-profile.js";
14
- import { type RegistryEndpointsInput, type RegistryEndpointsOutput } from "./registry-contract.js";
14
+ import type { RegistryEndpointsInput, RegistryEndpointsOutput } from "./registry-contract.js";
15
15
  import type { EpVerbTarget, EpAttributedReply } from "./endpoint-verbs.js";
16
16
  import type { AgentCard, ChannelConfig, ControlReply, ControlRequest, ControlRequestInit, Delivery, EndpointRef, MessageMeta, Part, Presence, PresencePrompts, PresenceStatus, PresenceCondition, AttentionMode, ChannelMode, CotalMessage, DmHistoryRead, HistoryMessage, DeliveryClass, MembershipChange, MembershipSnapshot } from "./types.js";
17
17
  import type { DeliveryLeaseInfo, ManagerLeaseInfo } from "./lease.js";
18
+ import { type MaybePromise } from "./endpoint-delivery-plane.js";
18
19
  import { type AnycastStatus } from "./anycast-requests.js";
19
20
  import { type ParsedSubject } from "./subjects.js";
20
21
  import { isPermissionDenied } from "./permission-denied.js";
@@ -27,26 +28,6 @@ export declare const DEFAULT_SERVER = "nats://127.0.0.1:4222";
27
28
  export declare function deliveryLimitOf(value: string | undefined): number | null;
28
29
  /** Space joined when none is given on the CLI (the `cotal-<space>` cmux tab, etc.). */
29
30
  export declare const DEFAULT_SPACE = "main";
30
- /** How many channel filters one multi-filter consumer create may carry.
31
- *
32
- * A create names every requested channel in one request, so the request grows with the channel
33
- * count and the CLIENT's request timeout is what gives way, not the broker: the create is never
34
- * refused, it just does not answer. Measured on an isolated broker, one message per channel,
35
- * `limit=5`: 70 filters answer in 43ms, 1,000 in 246ms, 5,000 in 5,345ms, and 10,000 does not
36
- * answer at all, failing `timeout` after 5,023ms. Note 5,000 SUCCEEDED while taking longer than
37
- * 10,000 took to fail, which is what says the ceiling is on the create request rather than on the
38
- * read: past roughly 5s the create itself is what times out.
39
- *
40
- * 1,000 is chosen from that sweep rather than from the failure point: it is a fifth of the largest
41
- * count that still answered, and it answers in a quarter second, so a batch stays far away from
42
- * both the timeout and the response-deadline budget the dashboard has to share with its DM read.
43
- * A space with the 69 chat channels this was built for is still ONE read, so the round-trip claim
44
- * in #1210 is unchanged at that size. */
45
- export declare const MULTI_FILTER_BATCH = 1000;
46
- /** How many filter batches may be in flight at once. Bounded because the point of #1210 was to stop
47
- * issuing one read per channel: a space large enough to need batches must not get the fan-out back
48
- * under another name. */
49
- export declare const MULTI_FILTER_READ_CONCURRENCY = 4;
50
31
  export interface EndpointOptions {
51
32
  /** Trusted composition custody of each opened transport, including replacement epochs.
52
33
  * Called before binding so the owner can await its terminal closed signal on bind failure. */
@@ -243,9 +224,23 @@ export interface TransportState {
243
224
  /** The server nats.js named for this edge. Omitted when the runtime supplied none. */
244
225
  server?: string;
245
226
  }
246
- /** A value or a promise of it — the Plane-3 `aclFor` reads the durable ACL registry FRESH per entry
247
- * (async), so the reader/fan-out call sites await it. */
248
- type MaybePromise<T> = T | Promise<T>;
227
+ /**
228
+ * Events: "message" (CotalMessage), "presence" (PresenceEvent), "roster" (Presence[]), "error" (Error),
229
+ * "connection" ({ connected: boolean }) — true on every successful (re)bind (initial start, manual
230
+ * reconnect, AND background self-heal), false the moment the connection drops (rebuild null window /
231
+ * terminal close). Lets an in-process agent track connectedness off the endpoint's own (re)binds
232
+ * instead of an imperative flag the self-heal path can't reach; "transport" ({ connected, server? })
233
+ * is the lower-level NATS socket edge, true before the full bind finishes and false during an internal
234
+ * nats.js reconnect without changing `connection` readiness. "stored-copies-full" ({ limit: number }): a
235
+ * stored copy arrived with the store at the count the copy was written under ({@link deliveryLimitOf}),
236
+ * so the store may have discarded older copies before this session read them; emitted for each such
237
+ * copy. A lowering of the count or an age set on the store removes copies without this event.
238
+ *
239
+ * Callers MUST attach an "error" listener before `start()`: async faults (incl. NATS
240
+ * permission denials, surfaced via `watchStatus`) are emitted as "error", and Node throws
241
+ * synchronously on an unhandled "error" — a missing listener turns any such fault into a
242
+ * process crash instead of a logged denial.
243
+ */
249
244
  /** One page of a mediated history read: the newest `limit` messages, oldest-first WITHIN the page.
250
245
  *
251
246
  * `complete` is the honest-truncation signal and the reason this is not just `CotalMessage[]`:
@@ -274,7 +269,9 @@ export interface PrincipalServe {
274
269
  /** Resolves with the refusal that ended the serve, including one that arrives on a replaced
275
270
  * connection after `ready` resolved. Never rejects, and never resolves after `stop`. */
276
271
  readonly failed: Promise<Error>;
277
- /** Unsubscribe and wait for the handlers in flight. */
272
+ /** Unsubscribe, abort every handler's `signal`, and wait for each handler in flight until its
273
+ * request's deadline at most, which the route caps at 30 s. A reply that comes after that is
274
+ * dropped. */
278
275
  stop(): Promise<void>;
279
276
  }
280
277
  export declare class CotalEndpoint extends EventEmitter {
@@ -369,10 +366,9 @@ export declare class CotalEndpoint extends EventEmitter {
369
366
  /** Caller-owned membership watches survive a connection rebuild as INTENT. Their iterators are
370
367
  * connection-scoped and are stopped/re-created around the epoch swap. */
371
368
  private readonly membershipFeedWatches;
372
- /** The live `ctl.delivery` serve subscription (delivery daemon) — re-created on every (re)connect by
373
- * {@link armDeliveryControl}; tracked so the stale one is dropped on reconnect. */
374
- private deliveryServeSub?;
375
- private deliveryAdminServeSub?;
369
+ /** The plane-3 delivery daemon side of this endpoint (fan-out writer, trusted reader, control
370
+ * responders) and the agent's DELIVER pump. Every dependency is read when it is used. */
371
+ private readonly deliveryPlane;
376
372
  /** The anycast take responder, the request records it writes, and their maintenance timer
377
373
  * (delivery daemon, SPEC §8.1). Bound with the other Plane-3 responders and dropped with them. */
378
374
  private takeServeSub?;
@@ -384,24 +380,6 @@ export declare class CotalEndpoint extends EventEmitter {
384
380
  private anycastUnavailable?;
385
381
  private anycastSweep?;
386
382
  private takesInFlight;
387
- /** The lifecycles whose membership inventory this daemon has been asked for, as principal to uids
388
- * (#4965). A durable join or leave bound to one of them is refused, so no row of a retiring lifecycle
389
- * is written after its inventory read starts. An entry goes when a later inventory for the same
390
- * principal finds its ACL row retired; an alias that never retires again keeps its one entry until
391
- * the daemon restarts. This is the second layer of the fence: it covers a manager that does not
392
- * narrow the ACL row before the inventory, on this daemon process only. The first is the ACL row
393
- * each join re-reads around its write (`durableJoinFor`'s `aclFence`), which holds across daemons. */
394
- private readonly retiringLifecycles;
395
- /** The durable joins and leaves running now, by `<principal>/<lifecycleUid>`: the writes an
396
- * inventory of that lifecycle waits for before it reads. */
397
- private readonly membershipWrites;
398
- /** True once {@link quiescePlane3} has stopped serving this shard pending an ownership answer.
399
- * Guards {@link armPlane3} so a RECONNECT cannot silently resume serving mid-question. */
400
- private plane3Quiesced;
401
- /** When set, this endpoint hosts the Plane-3 fan-out writer + trusted reader (the server-side delivery
402
- * daemon). `aclFor` maps an owner id to its current read ACL (`allowSubscribe`) for the reader's
403
- * re-authorization — read FRESH per entry from the durable ACL registry KV, hence async. */
404
- private plane3?;
405
383
  /** Local cache of the channel registry (key = channel token), kept by a KV watch or, on an
406
384
  * endpoint that reads it on demand, by {@link readChannels}. */
407
385
  private readonly channelConfigs;
@@ -411,9 +389,7 @@ export declare class CotalEndpoint extends EventEmitter {
411
389
  /** Orders {@link readChannels} results: a read that settles after a newer one was applied is dropped. */
412
390
  private channelReadGeneration;
413
391
  private channelReadApplied;
414
- /** Serializes history reads ({@link collectHistory}): they share the fixed per-instance
415
- * `chathist_<id>` consumer, so overlapping reads would delete/recreate it under one another. */
416
- private histLock;
392
+ private readonly history;
417
393
  private readonly subs;
418
394
  /** The observer feeds {@link tap} was asked for. This is INTENT, re-subscribed by {@link bindTap}
419
395
  * on every (re)connect: a rebuild after an outage the library could not ride out closes the old
@@ -468,9 +444,6 @@ export declare class CotalEndpoint extends EventEmitter {
468
444
  /** `$JS.API.CONSUMER.DELETE.<stream>.<prefix>_` for each of this connection's own KV watches and
469
445
  * running membership scans (see {@link recordOwnWatchConsumer}). */
470
446
  private readonly ownWatchDeletePrefixes;
471
- /** Per stream, the history-reader names of this connection's current reader id and the reads
472
- * waiting for one (see {@link acquireHistoryReader}). */
473
- private readonly historyReaderSlots;
474
447
  /** True until the first successful connect completes its boot backfill — distinguishes first-connect
475
448
  * (backfill the boot channels' history) from a reconnect (reopen the core-subs, no re-backfill).
476
449
  * Persists across reconnect (NOT connection-scoped). Replaces the legacy chat-durable consumed-cursor
@@ -875,7 +848,14 @@ export declare class CotalEndpoint extends EventEmitter {
875
848
  * running in the background so the endpoint never stays dead, and rethrows so the caller
876
849
  * can report it. */
877
850
  reconnect(): Promise<void>;
878
- /** The presence epoch moves first: a bind still awaiting the broker must find it moved
851
+ /** Stop the endpoint and close its connection.
852
+ *
853
+ * Every principal serve ends first: its handlers' `signal` aborts, and stop waits for each
854
+ * handler in flight until its request's deadline at most, so a handler that never settles does
855
+ * not hold stop open longer than 30 s, the route's cap on a deadline. A reply that comes after
856
+ * that is dropped.
857
+ *
858
+ * The presence epoch moves first: a bind still awaiting the broker must find it moved
879
859
  * before any await below gives it a window to install a watch on a stopped endpoint
880
860
  * (see {@link startPresenceWatch}). */
881
861
  stop(): Promise<void>;
@@ -887,6 +867,9 @@ export declare class CotalEndpoint extends EventEmitter {
887
867
  * start, during a start, rebuild or stop, while a credential transaction or its connection swap
888
868
  * is pending, and while the connection is down or redialing. */
889
869
  nativeConnections(): NativeConnectionBinding[];
870
+ /** The messaging verbs of this endpoint: multicast, unicast, anycast and the event-payload
871
+ * channel. Every dependency is read when it is used, so a field assigned after construction is seen. */
872
+ private readonly messaging;
890
873
  /** Multicast: broadcast to everyone on a channel. */
891
874
  multicast(text: string, opts?: {
892
875
  channel?: string;
@@ -931,11 +914,6 @@ export declare class CotalEndpoint extends EventEmitter {
931
914
  * one replica. Never degrades to a warning: the failure it prevents is silent.
932
915
  */
933
916
  assertExpectationSemantics(): Promise<void>;
934
- /** The envelope {@link multicastExpecting} publishes, built in ONE place so that a frame and any
935
- * measurement of that frame cannot describe different messages. The fields this adds — `ts`,
936
- * `space`, `from`, `channel` and the normalized `mentions` — are exactly the ones a caller
937
- * holding only its parts cannot account for. */
938
- private casEnvelope;
939
917
  /**
940
918
  * The bytes this frame will ACTUALLY put on the wire, to compare against {@link maxPayload}.
941
919
  *
@@ -951,6 +929,7 @@ export declare class CotalEndpoint extends EventEmitter {
951
929
  *
952
930
  * `expectedLastSubjectSeq` is a parameter because it is a header VALUE: sizing at 0 and publishing
953
931
  * at 123456 differ by five bytes.
932
+ * `expectedLastMsgId` is measured when given, so a caller that may send it can size for it.
954
933
  *
955
934
  * Residual: `ts` is re-stamped at publish, so the two differ in value — not in length until
956
935
  * epoch-millis needs a 14th digit.
@@ -960,6 +939,7 @@ export declare class CotalEndpoint extends EventEmitter {
960
939
  parts: Part[];
961
940
  id: string;
962
941
  expectedLastSubjectSeq: number;
942
+ expectedLastMsgId?: string;
963
943
  mentions?: string[];
964
944
  replyTo?: string;
965
945
  contextId?: string;
@@ -982,6 +962,10 @@ export declare class CotalEndpoint extends EventEmitter {
982
962
  * means "the subject must be empty". A mismatch throws, and the throw stays classifiable by the
983
963
  * already-public {@link isCasLoss} — the error is deliberately **not wrapped**, since wrapping
984
964
  * would hide the `err_code` that classification reads.
965
+ * - `expectedLastMsgId`, when given, becomes `Nats-Expected-Last-Msg-Id`. The broker checks it after
966
+ * its dedup cache, so a fresh value nobody has published turns a publish into a probe: an id the
967
+ * cache holds answers `duplicate: true` with the stored sequence, and any other id is refused
968
+ * with error 10070 before anything is stored.
985
969
  *
986
970
  * @throws if the endpoint is not live, the channel is not concrete, `id` is malformed, `parts` is
987
971
  * empty, or `expectedLastSubjectSeq` is not a non-negative safe integer.
@@ -991,6 +975,7 @@ export declare class CotalEndpoint extends EventEmitter {
991
975
  parts: Part[];
992
976
  id: string;
993
977
  expectedLastSubjectSeq: number;
978
+ expectedLastMsgId?: string;
994
979
  mentions?: string[];
995
980
  replyTo?: string;
996
981
  contextId?: string;
@@ -1076,6 +1061,9 @@ export declare class CotalEndpoint extends EventEmitter {
1076
1061
  }): void;
1077
1062
  /** Subscribe one {@link tap} on the current connection; with none, the next bind subscribes it. */
1078
1063
  private bindTap;
1064
+ /** The control plane and the service-invocation client of this endpoint. Every dependency is
1065
+ * read when it is used, so a field assigned after construction is seen. */
1066
+ private readonly controlPlane;
1079
1067
  /** Serve control requests for a service. Returns the subscription so a caller that re-registers on
1080
1068
  * reconnect (the delivery daemon) can drop the stale one. `boundReply` is REQUIRED for any service
1081
1069
  * whose responder holds a wildcard publish grant over the service subtree (the delivery daemon's
@@ -1093,11 +1081,7 @@ export declare class CotalEndpoint extends EventEmitter {
1093
1081
  boundReply?: boolean;
1094
1082
  concurrent?: (req: ControlRequest) => boolean;
1095
1083
  }): import("@nats-io/transport-node").Subscription;
1096
- /** Answer one control request for {@link serveControl}: the sender guard, the handler, and the reply. */
1097
- private answerControl;
1098
- /** Keep native named-reply and NoResponders handling, but settle when its connection closes:
1099
- * nats.js can close a no-mux subscription without settling its request. One close observer per
1100
- * connection avoids retaining a closed-promise callback for every completed request. */
1084
+ /** Forwards to the control plane's {@link EndpointControlPlane.requestBoundReply}. */
1101
1085
  private requestBoundReply;
1102
1086
  /** Send a control request to a service and await its reply (client side). Like {@link requestDelivery},
1103
1087
  * the reply rides a BOUNDED subject UNDER the request subject (`ctl.<service>.<id>.reply.<uuid>`), not
@@ -1110,23 +1094,11 @@ export declare class CotalEndpoint extends EventEmitter {
1110
1094
  * caller with its discovered generation (SPEC 13.15). It names the reply rail this connection's
1111
1095
  * credential reads, which is where a manager's turn notice for it lands (SPEC 14.3). */
1112
1096
  serviceRailCaller(): EpCaller;
1113
- /** This endpoint's v0.4 caller triple (§13.2) — the identity its minted ep-rail rows pin. The
1114
- * owner/actor principal is mode-correct by construction (static: DEV_OWNER + the connection
1115
- * identity; user mode: the bearer's callout-derived pair), and the lifecycle UID is the
1116
- * launcher-supplied incarnation the rows are keyed on (ledger-consistent: the §13.1 presence
1117
- * lifecycle-proof refuses a divergent uid before any publish). */
1118
- private serviceCaller;
1119
1097
  /** Follow this caller's goal on its standing connection, subscribing before submission.
1120
1098
  * A submitter may use a separate short-lived control credential for the same caller triple;
1121
1099
  * the accepted action's readiness budget can outlive that credential. This endpoint retains
1122
1100
  * its existing credential renewal and caller-scoped progress grants. */
1123
1101
  followServiceGoal(endpoint: string, submit: (signal?: AbortSignal) => Promise<EpAttributedReply>, deadlineMs?: number, opts?: Pick<SubmitAndFollowGoalOptions, "reconcile" | "signal" | "prepare">): Promise<EpAttributedReply>;
1124
- /** Drop every cached handle for one endpoint after refresh or a currency split. */
1125
- private clearResolvedService;
1126
- /** Hold connection recovery through the whole pre-acceptance phase, including the progress
1127
- * subscription flush. Release on setup failure or the command's answer, never on goal terminal. */
1128
- private beginServiceInvocation;
1129
- private waitServiceRecovery;
1130
1102
  /** The resolved, digest-verified command surface of `endpoint` as this connection's caller sees
1131
1103
  * it. Unpinned calls cache the complete discovery surface, and `refresh` drops both the full
1132
1104
  * handle and any command-specific invocation handles. `instanceId` selects one instance without
@@ -1205,7 +1177,6 @@ export declare class CotalEndpoint extends EventEmitter {
1205
1177
  instanceId?: string;
1206
1178
  classInstanceId?: string;
1207
1179
  }): Promise<EpAttributedReply>;
1208
- private invokeServiceOnce;
1209
1180
  /** Send a durable-membership request to the SERVER-SIDE delivery daemon (`ctl.delivery`) and await its
1210
1181
  * reply. The reply rides a subject UNDER `ctl.delivery.<id>.>` (not the per-id `_INBOX`), so the
1211
1182
  * scoped delivery cred can answer without broad inbox-publish — see
@@ -1274,8 +1245,10 @@ export declare class CotalEndpoint extends EventEmitter {
1274
1245
  * or end in whitespace, so it is never trimmed or normalized. An empty string names no directory
1275
1246
  * and leaves the card unchanged. */
1276
1247
  setCardCwd(cwd: string): Promise<void>;
1277
- /** A consumer that reads presence on demand reads the channel registry on demand too: it holds no
1278
- * watch on either, so a seat binds no consumer per member on these buckets (SPEC §6, §7). */
1248
+ /** The channel registry cache, its policy lookups and the registry watch that fills it, of this
1249
+ * endpoint. Every dependency is read when it is used, so a field assigned after construction is seen. */
1250
+ private readonly channelDiscovery;
1251
+ /** Forwards to the channel discovery component's {@link EndpointChannelDiscovery.readsChannelsOnDemand}. */
1279
1252
  private get readsChannelsOnDemand();
1280
1253
  /**
1281
1254
  * Read the channel registry from the broker now, for a consumer that reads presence on demand. One
@@ -1308,6 +1281,9 @@ export declare class CotalEndpoint extends EventEmitter {
1308
1281
  * from the live watch cache — drives the non-gating delivery-health surface (only durable-class
1309
1282
  * channels have a Plane-3 backstop to report on). */
1310
1283
  channelDeliveryClass(channel: string): DeliveryClass;
1284
+ /** Join, leave and channel listing, and the membership feed watches, of this endpoint. Every
1285
+ * dependency is read when it is used, so a field assigned after construction is seen. */
1286
+ private readonly subscriptions;
1311
1287
  /** The channels this endpoint is currently subscribed to (live — reflects join/leave). */
1312
1288
  joinedChannels(): string[];
1313
1289
  /**
@@ -1382,11 +1358,6 @@ export declare class CotalEndpoint extends EventEmitter {
1382
1358
  */
1383
1359
  channelMembers(channel: string): Promise<ChannelMember[]>;
1384
1360
  channelMembers(): Promise<Map<string, ChannelMember[]>>;
1385
- /** Lazily open the DERIVED membership FEED KV (`cotal_membership_<space>`; admin/observer read, the
1386
- * delivery daemon writes it) — the display-only who-is-subscribed view. Distinct from the authoritative
1387
- * {@link membersRegistry} (`cotal_members_<space>`, the Plane-3 durable-membership source of truth): the
1388
- * two names look alike, so this one is explicitly "feed". Read-only here; agents hold no grant. */
1389
- private membershipFeedRegistry;
1390
1361
  /**
1391
1362
  * Snapshot the broker-sourced channel-membership feed (admin/observer read): every agent's
1392
1363
  * `{live, durable}` record plus `asOf` — the feed's freshness heartbeat (epoch ms of the daemon's last
@@ -1405,12 +1376,8 @@ export declare class CotalEndpoint extends EventEmitter {
1405
1376
  watchMembership(onChange: (change: MembershipChange) => void, onClosed?: (err: Error) => void): Promise<{
1406
1377
  stop(): Promise<void>;
1407
1378
  }>;
1408
- /** Bind one caller-owned membership-watch intent to the CURRENT connection. Arming is serialized
1409
- * per intent, so a public watch call cannot race a reconnect rearm into two consumers. */
1410
- private armMembershipWatch;
1411
- /** Delete identity retained across a failed/closed-epoch consumer object using the CURRENT connection. */
1379
+ /** Forwards to the subscriptions component's {@link EndpointSubscriptions.deleteRetainedMembershipConsumer}. */
1412
1380
  private deleteRetainedMembershipConsumer;
1413
- private finishMembershipWatchStop;
1414
1381
  /** Record the consumer behind one of this connection's own KV watches or membership scans, and
1415
1382
  * return the delete-subject prefix it recorded. nats.js names it `<prefix>_<serial>` and,
1416
1383
  * rebuilding it after a stall or a sequence gap, deletes the predecessor itself with no hook before
@@ -1433,10 +1400,9 @@ export declare class CotalEndpoint extends EventEmitter {
1433
1400
  private deleteOwnConsumer;
1434
1401
  /** Delete one membership-watch consumer, swallowing ONLY already-gone and a refused delete. */
1435
1402
  private deleteMembershipConsumer;
1436
- /** Stop the local iterator, then delete when permitted. A known-ungranted delete releases local
1437
- * cleanup custody without a request; the broker reclaims the consumer at its inactive threshold. */
1403
+ /** Forwards to the subscriptions component's {@link EndpointSubscriptions.disarmMembershipWatch}. */
1438
1404
  private disarmMembershipWatch;
1439
- /** Rebind every live membership-watch intent after a connection rebuild. */
1405
+ /** Forwards to the subscriptions component's {@link EndpointSubscriptions.rearmMembershipWatches}. */
1440
1406
  private rearmMembershipWatches;
1441
1407
  /** Fetch recent messages from a channel's JetStream backlog. `signal` cancels the active pull and
1442
1408
  * reclaims its ephemeral consumer before the promise rejects. Returns `HistoryMessage[]`
@@ -1577,65 +1543,6 @@ export declare class CotalEndpoint extends EventEmitter {
1577
1543
  * `before` pages toward the past: pass the `seq` of the oldest message you already have.
1578
1544
  */
1579
1545
  private streamHistory;
1580
- /** This connection's history-reader id, the key of its credential's reader deletes
1581
- * ({@link historyReaderConsumer}). A static credential's is its connId, the nkey it signs with.
1582
- * Under the auth callout the connId is the inbox nonce this client chose, so the callout keys the
1583
- * deletes on {@link calloutReaderId} instead: the server's id and the client id it assigned this
1584
- * connection, which the client reads from the server's INFO and does not choose. */
1585
- private historyReaderId;
1586
- /** Take one of this connection's history-reader names on `stream` ({@link historyReaderConsumer})
1587
- * for one read. The read holds the name for its whole walk and creates and deletes a consumer
1588
- * under it at each step, so this connection keeps at most {@link HISTORY_READERS} reader consumers
1589
- * on a stream (#4123). A read past that many waits for a name, and `signal` ends the wait. A
1590
- * reconnect under the auth callout changes the reader id, and reads from then on take the new
1591
- * id's names. */
1592
- private acquireHistoryReader;
1593
- /** Give a read's history-reader name back and wake one read waiting for a name. A name whose
1594
- * delete failed is set aside instead. */
1595
- private releaseHistoryReader;
1596
- /** Keep `slot` out of use until a consumer under it would have expired, then free it. */
1597
- private setAsideHistoryReader;
1598
- /** Create the reader consumer for one step of a read, under the read's name. It is a plain pull
1599
- * consumer: an nats.js ordered consumer renames itself on every rebuild, and the observer and admin
1600
- * credentials may delete only these exact names.
1601
- *
1602
- * Every create carries a fresh description. NATS answers a create whose config equals the existing
1603
- * consumer's with that consumer, delivery state and all (measured on nats-server 2.15), and a read
1604
- * repeats the same config on the same name. Without the description a reader left under the name
1605
- * would come back as if new: a `DeliverPolicy.Last` reader that already delivered its message
1606
- * reports nothing pending, which reads as an empty channel. With it, a create on a name in use is
1607
- * refused, and a consumer that does not carry this step's description is never used.
1608
- *
1609
- * A consumer already under the name is never deleted, whoever left it: another holder of this
1610
- * credential, a process that stopped mid-read, or this endpoint when a delete's answer was lost and
1611
- * the name was taken again since. The read moves to a free name, and the taken one stays out of use
1612
- * until such a consumer would have expired. */
1613
- private openHistoryReader;
1614
- /** Delete the read's reader consumer; already gone is the same outcome. A failed delete may still
1615
- * have run with its answer lost, and the name may be taken again before this endpoint could tell,
1616
- * so the name is set aside when the read gives it back rather than deleted again later. A refused
1617
- * delete means the credential was minted before the observer and admin profiles held their reader
1618
- * deletes. Each read would then leave a reader for the inactive threshold, which is how a polling
1619
- * dashboard filled the stream's consumer limit (#4123), so the read fails and says to remint
1620
- * rather than leak quietly, and reads on the stream fail at once until that reader expires. */
1621
- private closeHistoryReader;
1622
- private readerDeleteRefused;
1623
- /** The oldest stream sequence matching `subject`, or 0 when the subject has no messages.
1624
- * Mirror of {@link lastMatchingSeq}: same CREATE/INFO/NEXT/DELETE surface, `DeliverPolicy.All`
1625
- * instead of `Last`, first delivered seq instead of last. Read credentials already hold this. */
1626
- private firstMatchingSeq;
1627
- /** The newest stream sequence matching `subject`, or 0 when the subject has no messages.
1628
- *
1629
- * One reader consumer at `DeliverPolicy.Last` with this subject's filter: its `num_pending`
1630
- * (available from the create, before anything is delivered) is 0 for an empty subject, and
1631
- * otherwise one message carries the sequence. Same CREATE/INFO/NEXT/DELETE surface `drainWindow`
1632
- * already uses, so no broker authority is added. */
1633
- private lastMatchingSeq;
1634
- /** Drain every message matching `subject` with sequence in `[start, ceiling]`, oldest-first.
1635
- * One reader consumer, one batched pull — `AckPolicy.None`, so no per-message ack
1636
- * round trip. Fetches exactly the pending count so it returns as soon as the window is
1637
- * delivered rather than blocking for the pull's full expiry. */
1638
- private drainWindow;
1639
1546
  /**
1640
1547
  * Surface the connection's async status errors on our `error` event. NATS reports
1641
1548
  * publish permission violations *only* here (subscription ones too), never on the
@@ -1725,10 +1632,12 @@ export declare class CotalEndpoint extends EventEmitter {
1725
1632
  * Idempotent per role. The caller must be permissive on TASK_<space>.
1726
1633
  */
1727
1634
  provisionTaskQueue(role: string): Promise<void>;
1728
- /** Lazily open the privileged members registry KV (delivery daemon / open-mode self). */
1635
+ /** The Plane-3 registries, manager and daemon-renewal leases, and durable membership writes of this
1636
+ * endpoint. Every dependency is read when it is used, so a field assigned after construction is seen. */
1637
+ private readonly durableBackstop;
1638
+ /** Forwards to the durable backstop's {@link EndpointDurableBackstop.membersRegistry}. */
1729
1639
  private membersRegistry;
1730
- /** Lazily open the durable read-ACL registry KV. Privileged write (the manager records an agent's
1731
- * ACL at mint); the delivery daemon reads it fresh per durable entry to re-authorize. */
1640
+ /** Forwards to the durable backstop's {@link EndpointDurableBackstop.aclRegistry}. */
1732
1641
  private aclRegistry;
1733
1642
  /** Privileged ({@link DurableProvisioner}): record an agent's read ACL in the durable registry at
1734
1643
  * provision/mint time — the same act as baking it into the JWT, persisted so the server-side
@@ -1893,16 +1802,6 @@ export declare class CotalEndpoint extends EventEmitter {
1893
1802
  info: DeliveryLeaseInfo;
1894
1803
  revision: number;
1895
1804
  } | undefined>;
1896
- /** Ensure + bind the manager singleton-lease bucket. Mirrors the presence-bucket pattern (connectAndBind):
1897
- * AUTH mode OPENs the bucket pre-created at `cotal up` (the scoped `supervisor` cred holds no
1898
- * STREAM.CREATE — and `open` binds direct=false, so the CAS-conflict `kv.get` inside `acquire` rides
1899
- * STREAM.MSG.GET, the verb the supervisor grants, never DIRECT.GET). OPEN mode (no creds) create-firsts:
1900
- * `Kvm.open` binds LAZILY — it does NOT verify the stream exists or throw when it's missing (a fresh
1901
- * bucket then fails 'stream not found' on the first write), so `create` is the ensure-exists call (it
1902
- * makes the bucket or, when another endpoint already did, throws and we bind the existing one). Either
1903
- * way the per-KEY CAS create stays the only single-flight gate, so a lost bucket-create race never reads
1904
- * as "lease held". */
1905
- private managerLeaseRegistry;
1906
1805
  /** Take or keep the per-SPACE daemon-credential renewal lease (#1634), returning whether THIS
1907
1806
  * instance now holds it. One atomic CAS `create` per pass: it succeeds for whoever arrives first
1908
1807
  * and throws for everyone else, so exactly one manager remints even when several share the
@@ -1914,7 +1813,6 @@ export declare class CotalEndpoint extends EventEmitter {
1914
1813
  /** Release the renewal lease on a clean stop so a peer takes over at once rather than at the TTL.
1915
1814
  * CAS-guarded, so a lease we already lost is never deleted out from under its new holder. */
1916
1815
  releaseDaemonRenewalLease(): Promise<void>;
1917
- private encodeDaemonRenewalLease;
1918
1816
  /** Read the per-space daemon-credential renewal-lease row (the one {@link holdDaemonRenewalLease}
1919
1817
  * CAS-writes), or `undefined` when nothing holds it. A `doctor auth --fix` that lost `hold` calls
1920
1818
  * this through the SAME bucket the hold attempt opened, to name the live holder in its refusal —
@@ -1923,7 +1821,6 @@ export declare class CotalEndpoint extends EventEmitter {
1923
1821
  instanceId: string;
1924
1822
  since: number;
1925
1823
  } | undefined>;
1926
- private encodeManagerLease;
1927
1824
  /** Acquire THIS logical instance's liveness lease via ATOMIC CAS create on its own per-instance key
1928
1825
  * ({@link managerLeaseKey}). THROWS only if that SAME instance id already holds a live key (a same-root
1929
1826
  * concurrent double-start, or a restart racing the crashed predecessor's not-yet-expired key) — a loud
@@ -1984,27 +1881,12 @@ export declare class CotalEndpoint extends EventEmitter {
1984
1881
  * `live`→`durable` flip is seen by fan-out without a cache-propagation gap (red-team MED-3), and a
1985
1882
  * reader just started need not wait for the cache to fill. */
1986
1883
  deliveryClassFresh(channel: string): Promise<DeliveryClass>;
1987
- /** Collision-safe `@mention` → owner-id resolution: a name that resolves to exactly one present
1988
- * peer wins; 0 or >1 matches drop (never fan a directed durable copy to an unrelated same-named
1989
- * bystander — red-team LOW; SPEC §4 unique instance id). */
1884
+ /** Forwards to the durable backstop's {@link EndpointDurableBackstop.resolveOwnerByName}. */
1990
1885
  private resolveOwnerByName;
1991
- /** Plane-3 publish-dedupe key for a fan-out/transfer entry: the message id plus the member
1992
- * lifecycle (`keySuffix`). One message reaches one lifecycle once, whichever membership row and
1993
- * whichever writer (fan-out or any row's catch-up) produced the copy (#5404), within the stream's
1994
- * duplicate window. An empty `msg.id` contributes NO msgID (#673, SPEC §4: two `id: ""` posts MUST
1995
- * NOT collapse to one delivery) — a plain publish, never an empty or salted one — so an id-less
1996
- * message is at-least-once on the durable plane (a redelivery may reach the member twice; the
1997
- * receiver already treats each as its own delivery). */
1886
+ /** Forwards to the durable backstop's {@link EndpointDurableBackstop.plane3MsgId}. */
1998
1887
  private plane3MsgId;
1999
- /** Publish one fan-out entry into a member LIFECYCLE's mixed inbox (`dinbox.<o>.<a>.<uid>`, SPEC
2000
- * §13.1: fan-out addresses the member row's RECORDED lifecycle, never the alias's current
2001
- * occupant), idempotent via `Nats-Msg-Id` (`<msgId>:<principal>:<lifecycleUid>`) so a catch-up copy
2002
- * and a racing fan-out copy collapse, from the same row or from two rows that both cover the post.
2003
- * The `principal` is the member's owner+actor dot-form. */
1888
+ /** Forwards to the durable backstop's {@link EndpointDurableBackstop.publishDinbox}. */
2004
1889
  private publishDinbox;
2005
- /** The fan-out consumer's delivered stream-seq — the activation-fence upper bound (red-team
2006
- * BLOCKER-1: the shared fan-out cursor advances independently of the stream frontier). */
2007
- private fanoutDeliveredSeq;
2008
1890
  /**
2009
1891
  * Privileged durable-JOIN write (v3: the delivery daemon calls this from its `ctl.delivery` handler
2010
1892
  * after validating channel ⊆ the caller's read ACL): capture `joinCursor`, commit a `durable-active`
@@ -2037,13 +1919,6 @@ export declare class CotalEndpoint extends EventEmitter {
2037
1919
  * inside one entry, {@link membershipInAllow}). A leader-served read: the handle is opened without
2038
1920
  * direct reads, so a row narrowed before this read began is the row it returns. */
2039
1921
  private aclAllows;
2040
- /** The post-write half of {@link durableJoinFor}'s `aclFence`: keep the row just written (at
2041
- * `revision`) only on proof that the lifecycle's ACL row still allows the channel, and refuse the
2042
- * join otherwise. When the ACL row proves the channel is no longer allowed, no row of the lifecycle
2043
- * on that channel is wanted, so the row goes by its exact key whoever wrote its latest revision.
2044
- * When the read itself fails, nothing is proven either way, so only this write is taken back: a
2045
- * later revision belongs to another join of the same lifecycle, which may have been authorized. */
2046
- private keepRowIfAclAllows;
2047
1922
  /** Privileged durable-LEAVE write: tombstone the membership at `leaveCursor = frontier` so the
2048
1923
  * backstop denies `seq > leaveCursor` while a pre-leave entry stays deliverable (SPEC §7 interval). */
2049
1924
  durableLeaveFor(owner: string, channel: string, lifecycleUid: string, expectedGeneration?: number): Promise<void>;
@@ -2075,71 +1950,6 @@ export declare class CotalEndpoint extends EventEmitter {
2075
1950
  onDeliveryCredsAdopted?: () => void;
2076
1951
  startupComplete?: () => boolean;
2077
1952
  }): Promise<void>;
2078
- /** Whether an ALREADY-DISPATCHED unit of Plane-3 work may still take effect.
2079
- *
2080
- * Unsubscribing stops NEW work; it cannot recall work already in flight. A handler that entered
2081
- * before {@link quiescePlane3} and awaited broker I/O inside it resumes AFTER the freeze, and a
2082
- * reviewer traced the ordering that makes that a split rather than a latency blip: the loser
2083
- * accepts a unit and awaits, the loser is descheduled, the successor acquires the shard and flips
2084
- * its lease READY, then the loser resumes and answers or acks for a shard it no longer holds.
2085
- * Subscription counts and parked-pull readings cannot see it, because the effect is the reply and
2086
- * the ack rather than the binding.
2087
- *
2088
- * So each work path re-asks HERE, at the point of effect, after its awaits and before it acts.
2089
- * The lease keeps one ROW, not one SERVER; this is the half that keeps one server. An unacked
2090
- * message is not lost by refusing: a stopped consumer redelivers it to whoever holds the shard
2091
- * next, which is the same property quiescing already relies on. */
2092
- private plane3MayAct;
2093
- /** Serve one runtime durable-membership control request (the server-side delivery daemon). The caller
2094
- * id is the authenticated subject sender ({@link serveControl} fail-closes on a mismatch). Validation
2095
- * is against the durable ACL registry — the SAME KV the reader re-auths against (single source of
2096
- * truth, no in-memory ledger to drift). */
2097
- private handleDeliveryControl;
2098
- /** Validate the channel ARG shape only: non-blank, valid, concrete (NO ACL check, that is op-specific).
2099
- * `family` also admits a channel family such as `review.>` (a membership join or leave, #5404).
2100
- * Returns the channel on success or a ControlReply error to short-circuit. */
2101
- private checkDurableChannelArg;
2102
- /** JOIN requires the channel be within the caller's CURRENT read ACL (you can't durable-subscribe a
2103
- * channel you may not read). A family must lie inside one ACL entry, so every channel under it is
2104
- * readable. */
2105
- private deliveryJoin;
2106
- /** Whether `lifecycleUid`'s exact ACL row still allows reads, so an inventory of it came from a
2107
- * caller that did not fence. A row narrowed to no reads, or retired or absent, is fenced. A read
2108
- * that fails answers true: the caller keeps its in-memory mark, which only ever refuses. */
2109
- private lifecycleAclUnfenced;
2110
- /** Run one durable join or leave that writes `principal`'s rows of `lifecycleUid`, refused once that
2111
- * lifecycle's inventory has been asked for ({@link retiringLifecycles}). The check and the
2112
- * registration have no await between them, so an inventory either finds this write running and
2113
- * waits for it, or this write finds the inventory's mark and is refused. */
2114
- private membershipWrite;
2115
- /** LEAVE must NOT require current-ACL coverage. Leave fires precisely when the ACL was narrowed/revoked
2116
- * (a refused live sub → {@link closeRefusedMembership}); gating the tombstone on the current ACL would
2117
- * loop forever and leave the SPEC §7 boundary open (the membership could resume if the ACL is later
2118
- * restored). The guards are: authenticated caller (serveControl), concrete channel, a finite generation
2119
- * (the join epoch — without it a stale/replayed leave could tombstone a newer rejoin), and an EXISTING
2120
- * own membership; `durableLeaveFor` → `tombstoneMember` then enforces the generation match. */
2121
- private deliveryLeave;
2122
- /** Serve one MEDIATED HISTORY READ (`readHistory`, the client side is {@link readHistory}). The daemon
2123
- * holds the consumer so the caller does not have to: this is a privilege reduction, not a new
2124
- * capability, and it is the shape SPEC's "Mediated reads (normative)" rule asks for.
2125
- *
2126
- * THE ONE INVARIANT THIS METHOD EXISTS FOR: authorization is read FRESH on every call and never
2127
- * cached across calls. A consumer pins its authorization when it is created, so a revoked caller
2128
- * keeps being served by a consumer it already holds; re-reading here is what makes a revocation
2129
- * stop the very NEXT read. Cache this and the verb loses its only advantage over the raw consumer
2130
- * path.
2131
- *
2132
- * AUTHORITY (SPEC §9.6): "current read ACL" is the effective broker-accepted credential. The
2133
- * durable registry is a live mirror of that credential, not a second grant source. History
2134
- * authorizes against `allowSubscribe ∩ issuedAllowSubscribe` — the live row (so revocation via
2135
- * plain commitAcl still stops the next read) intersected with the mint-time ceiling (so a
2136
- * registry widen without a remint cannot grant what the JWT does not). Raising the ceiling is
2137
- * {@link reissueAcl}, which is what provision does when it bakes the list into the JWT.
2138
- *
2139
- * The caller arrives as an alias (the control subject carries owner+actor, never a uid) and is the
2140
- * AUTHENTICATED subject sender — `serveControl` has already fail-closed on any payload that names a
2141
- * different principal, so `caller` cannot be self-asserted. */
2142
- private deliveryReadHistory;
2143
1953
  /** Stop serving Plane-3 WITHOUT tearing down the connection, so a daemon that has just learned its
2144
1954
  * lease may no longer be its own can stop acting on the shard while it finds out for certain.
2145
1955
  *
@@ -2175,19 +1985,12 @@ export declare class CotalEndpoint extends EventEmitter {
2175
1985
  * That is a readiness lie surviving a transient broker error, the daemon claims a responder it does
2176
1986
  * not have, which is the #1318 outage wearing the readiness flag instead of the exit path. */
2177
1987
  rearmPlane3(): Promise<void>;
2178
- /** (Re)bind the Plane-3 fan-out writer + trusted reader. Idempotent — the durables resume from their
2179
- * cursor. Called by {@link startPlane3} once AND by {@link connectAndBind} on every (re)connect, so
2180
- * the delivery daemon's reconnect RE-ARMS the backstop + the ctl.delivery responder. Without this, a broker blip would silently kill
2181
- * the loops while `durableJoinFor` kept reporting `durable:true` (the impl-review's BLOCKER-1). No-op
2182
- * unless this endpoint hosts Plane-3 (`this.plane3` set). */
1988
+ /** Forwards to the delivery plane's {@link EndpointDeliveryPlane.plane3MayAct}. */
1989
+ private plane3MayAct;
1990
+ /** Forwards to the delivery plane's {@link EndpointDeliveryPlane.armPlane3}. */
2183
1991
  private armPlane3;
2184
- /** (Re)register the `ctl.delivery` control responder on the CURRENT connection. A reconnect drains the
2185
- * old connection (the old sub is dead and `clearConnectionScoped` leaves caller-owned subs alone), so
2186
- * this MUST run on every arm — otherwise durable join/leave/list silently lose their responder after a
2187
- * broker blip. The stale sub is dropped (unsubscribed + removed from `this.subs`) before re-creating.
2188
- * `boundReply` is essential here: the daemon holds a wildcard reply-publish grant, so the serve path
2189
- * must reject any reply target outside the authenticated sender's own subtree (confused-deputy fix). */
2190
- private armDeliveryControl;
1992
+ /** Forwards to the delivery plane's {@link EndpointDeliveryPlane.pumpDlv}. */
1993
+ private pumpDlv;
2191
1994
  /** (Re)bind the anycast take responder and the request records maintenance on the current
2192
1995
  * connection (SPEC §8.1). The records bucket is created here as well as at space setup, so a mesh
2193
1996
  * that predates it gets one when its daemon restarts at this version. */
@@ -2212,6 +2015,9 @@ export declare class CotalEndpoint extends EventEmitter {
2212
2015
  /** Answer a sender's status or cancel for one of its own requests. The caller is the
2213
2016
  * authenticated subject sender, checked against the request's stored subject. */
2214
2017
  private deliveryAnycast;
2018
+ /** The peer-readable liveness responders and the probe, of this endpoint. Every dependency is read
2019
+ * when it is used, so a field assigned after construction is seen. */
2020
+ private readonly liveness;
2215
2021
  /** Bind this endpoint as the liveness RESPONDER for one plane, answering presence and nothing
2216
2022
  * else to any credentialed peer that asks (`live.<plane>.<owner>.<actor>`).
2217
2023
  *
@@ -2254,8 +2060,7 @@ export declare class CotalEndpoint extends EventEmitter {
2254
2060
  * the plane answered by the broker's no-responders status while this endpoint is serving. A second
2255
2061
  * call for the same plane replaces the first. */
2256
2062
  serveLiveness(plane: LivenessPlane, readState: () => Promise<ResponderState> | ResponderState): void;
2257
- /** (Re)bind one plane's liveness responder on the CURRENT connection, dropping the stale sub first
2258
- * as {@link armDeliveryControl} does. */
2063
+ /** Forwards to the liveness component's {@link EndpointLiveness.bindLiveness}. */
2259
2064
  private bindLiveness;
2260
2065
  /** Bind the liveness responder for the DELIVERY plane, grading itself from its own shard-0 lease
2261
2066
  * through the shared classifier. The daemon is the one process that can answer this honestly: it
@@ -2283,37 +2088,33 @@ export declare class CotalEndpoint extends EventEmitter {
2283
2088
  * The reply rides `<request>.reply.<uuid>`, the sender's own subtree, so the responder's bound
2284
2089
  * reply guard accepts it and the responder needs no broad inbox-publish grant to answer. */
2285
2090
  probeLiveness(plane: string, timeoutMs?: number): Promise<LivenessAnswer>;
2286
- /** Grade a failed probe that was NOT a no-responders answer. Both arms return an outcome that
2287
- * maps to `unknown`; they are told apart so the distinction stays legible at the call site and so
2288
- * a future caller can render the two differently (a refusal is about YOUR credential, a timeout
2289
- * is about something being wedged). Neither may ever mean health. */
2290
- private probeFailureOutcome;
2291
2091
  /**
2292
- * Serve this process's own endpoint on the principal route (SPEC 13.21): a core-defined command
2293
- * set about this principal, addressed by its own principal, lifecycle UID and runtime id, with no
2294
- * registration. Revision 1 defines one endpoint, `agent` (SPEC 13.22).
2092
+ * Serve this process's `agent` endpoint on the principal route (SPEC 13.21, 13.22): the
2093
+ * `AGENT_CLUSTER` command set about this principal, addressed by its own principal, lifecycle UID
2094
+ * and runtime id, with no registration. `handlers` serves the cluster's commands with
2095
+ * `AGENT_CONTRACTS`; `describe` is built in.
2295
2096
  *
2296
2097
  * Throws on an open mesh and on a static credential, where no row names who may call, without a
2297
- * lifecycle UID, before the endpoint has started, for an endpoint it already serves, and for a
2298
- * cluster with a command that declares no `authorities` (see {@link servePrincipalRoute}). It
2299
- * subscribes this process's own subject with no queue group.
2098
+ * lifecycle UID, before the endpoint has started, while it already serves `agent`, for an
2099
+ * `endpoint` or `cluster` field, which this entry point does not take, and for a set of handlers
2100
+ * that is not the cluster's commands with its contracts. It subscribes this process's own subject
2101
+ * with no queue group.
2300
2102
  *
2301
2103
  * `ready` is a positive check: it resolves only after the broker accepted the subscription
2302
2104
  * (subscribe, flush, and no permission violation for that subject), and rejects with the
2303
2105
  * refusal, which a credential minted before the rows existed gets. The serve is INTENT: every
2304
2106
  * replaced connection subscribes again and runs the check again, and a refusal there ends the
2305
- * serve, resolves `failed` and clears the presence field. `stop` unsubscribes and waits for the
2306
- * handlers in flight.
2107
+ * serve, resolves `failed` and clears the presence field. `stop` unsubscribes, aborts the
2108
+ * handlers' `signal`, and waits for each handler in flight until its request's deadline at most.
2307
2109
  */
2308
- servePrincipal(serve: {
2309
- endpoint: string;
2310
- cluster: ClusterDocument;
2110
+ servePrincipal(spec: {
2311
2111
  handlers: EpPrincipalCommandDef[];
2312
2112
  }): PrincipalServe;
2313
2113
  /** Subscribe `intent` on `nc`. */
2314
2114
  private bindPrincipalHandle;
2315
- /** A request or reply subject (or filter) of the principal route in this space. */
2316
- private isPrincipalRouteSubject;
2115
+ /** A principal-route refusal a call or a serve reports itself: a request publish, a serve
2116
+ * subscription or a reply read. Only a reply publish is left, which no call or serve awaits. */
2117
+ private ownedPrincipalRouteRefusal;
2317
2118
  /** Track one binding: a refusal ends the serve, and an accepted subscription on the current
2318
2119
  * connection shows the presence field. */
2319
2120
  private armPrincipalServe;
@@ -2327,7 +2128,8 @@ export declare class CotalEndpoint extends EventEmitter {
2327
2128
  private endPrincipalServe;
2328
2129
  /** Mark `intent` ended and release what it holds in this endpoint and in this process. */
2329
2130
  private forgetPrincipalServe;
2330
- /** Stop serving `intent` and wait for its handlers in flight. The ending is synchronous, so a
2131
+ /** Stop serving `intent` and wait for its handlers in flight, each until its request's deadline
2132
+ * at most. The ending is synchronous, so a
2331
2133
  * `ready` still waiting for the broker rejects before the caller's next step. `republish` writes
2332
2134
  * presence without the `prompts` field; the endpoint's own stop writes it offline instead. */
2333
2135
  private stopPrincipalServe;
@@ -2336,8 +2138,8 @@ export declare class CotalEndpoint extends EventEmitter {
2336
2138
  * prompts it holds `open` or `sent`, and a counter that goes up by one each time a prompt opens or
2337
2139
  * changes state. The field shows only while the `agent` endpoint is served and the broker accepted
2338
2140
  * its subscription on the current connection. Until this is called it shows `open: 0` with the
2339
- * highest `seq` this process used under its runtime id, or 0. Throws when the `agent` endpoint is
2340
- * not served, and a RangeError for a `seq` below one this runtime already used.
2141
+ * fresh `seq` the serve took from {@link nextPromptsSeq} when it started. Throws when the `agent`
2142
+ * endpoint is not served, and a RangeError for a `seq` below one this runtime already used.
2341
2143
  */
2342
2144
  setPromptsPresence(prompts: PresencePrompts): Promise<void>;
2343
2145
  /**
@@ -2374,52 +2176,6 @@ export declare class CotalEndpoint extends EventEmitter {
2374
2176
  };
2375
2177
  signal?: AbortSignal;
2376
2178
  }): Promise<EndpointReply>;
2377
- /** Serve one PRIVILEGED delivery-admin request (the D5 rail-split). The cred layer is the caller
2378
- * boundary — only the supervisor profile can publish here — and `serveControl`'s sender check +
2379
- * bounded reply still apply on top. `reloadCreds` is the class-2 renewal ADOPTION step: re-read
2380
- * the renewal-owner-re-signed creds file, pin, swap the live connection, reconnect the membership
2381
- * feed's rw connection, and reply with proof (identities + the adopted JWT windows) — or a
2382
- * structured failure (e.g. the file was never re-signed), never a silent partial. */
2383
- private handleDeliveryAdmin;
2384
- /** Create one of the daemon's Plane-3 durables. A named create is idempotent for the same config,
2385
- * and a denial is never taken for existence. The one conflict accepted is this durable as a full
2386
- * restore recreated it, starting after its recorded ACK floor ({@link isRestoredConsumer}); every
2387
- * other failure propagates. */
2388
- private addPlane3Durable;
2389
- /** Fan-out loop: bind the privileged `fanout` durable on CHAT and route each message (routing only —
2390
- * the trusted reader is the auth gate). */
2391
- private runFanout;
2392
- /** Route ONE chat message to eligible owners' mixed inboxes. `durable` channel → its `durable-active`
2393
- * members within interval; `live` channel → `@mention` targets authorized to read it (ACL only).
2394
- * On either class, a mention of an agent whose read ACL excludes the channel is reported to the
2395
- * sender with a mention notice. Members KV is scanned FRESH per message (no cache — red-team
2396
- * BLOCKER-1 catch-up correctness). */
2397
- private fanOutMessage;
2398
- private deliveryLimitRead?;
2399
- /** The DLV count the trusted writer stamps on a copy (SPEC §8): the stream's `max_msgs_per_subject`,
2400
- * read at most {@link DELIVERY_LIMIT_READ_MS} before the write, as a whole number or `none`. */
2401
- private deliveryLimitStamp;
2402
- /** Trusted-reader loop: bind the single privileged `reader` durable over `dinbox.>` and re-authorize
2403
- * + transfer each entry. */
2404
- private runReader;
2405
- /** Whether one of the lifecycle's rows covering concrete `channel`, the channel's own or a family
2406
- * above it, is eligible for the post at `seq`. One exact read per row, the channel's own first. */
2407
- private lifecycleCoversPost;
2408
- /** Remove a retired lifecycle's member row for `channel`, when one exists. Best effort: the row
2409
- * authorizes nothing (its ACL row is retired), and the next entry fan-out writes against it
2410
- * brings the reader back here. */
2411
- private removeRetiredMemberRow;
2412
- /** Re-authorize ONE mixed-inbox entry and transfer it to the owner's DELIVER store. Deny (drop) on a
2413
- * revoked/narrowed ACL or out-of-interval seq; on transfer success, ack the mixed entry (durability
2414
- * has moved to DLV — an §8 equivalent per-member at-least-once mechanism). The agent acks DLV. */
2415
- private readerHandle;
2416
- /** Agent-side: bind + pump our pre-created Plane-3 DELIVER durable (`dlv_<id>`). Every message here is
2417
- * delivery-daemon-written (DLV is delivery-write-only, broker-enforced) and is a CHANNEL message by contract
2418
- * (the backstop never carries DMs), so `kind=channel` is path-derived (SPEC §4) and the body is
2419
- * trusted (no spoof-guard). `durable:true` — real JetStream ack, coalesced with the core-sub live
2420
- * copy by `MeshAgent.ingest`. No-op when the durable isn't present (open mode / not provisioned). A read
2421
- * list declared on a credential that cannot fetch the durable refuses. */
2422
- private pumpDlv;
2423
2179
  /** Agent-side: request a Plane-3 durable backstop for a channel via the server-side delivery daemon (ctl.delivery). Throws
2424
2180
  * when no privileged writer is present (open / no delivery daemon). 30s timeout — activation catch-up may
2425
2181
  * run before the reply (the window is small, but a busy channel can take more than the 5s default). */
@@ -2586,7 +2342,6 @@ export declare class CotalEndpoint extends EventEmitter {
2586
2342
  * calls must be serial — every reader here awaits to completion, so they are.
2587
2343
  */
2588
2344
  private collectHistory;
2589
- private collectHistoryInner;
2590
2345
  /** Read a channel's retained history up to `upToSeq` (the join frontier) and emit each message
2591
2346
  * as a `historical` "message" event. `sinceMs` bounds how far back via a native consumer
2592
2347
  * `start_time` (now − window); unset ⇒ the full retained window. `floorSeq`, when set, is a
@@ -2674,13 +2429,10 @@ export declare class CotalEndpoint extends EventEmitter {
2674
2429
  /** {@link EndpointOptions.readOnce}: fill the roster from one read of the presence bucket. Stale
2675
2430
  * and offline records resolve as they do in a watch's initial replay. */
2676
2431
  private readPresenceOnce;
2677
- /** Watch the channel registry: replay existing keys, then stream updates, into the local
2678
- * cache. A failed bind throws out of connect; an entry that does not decode or validate is
2679
- * reported as a `warning` and dropped, so its channel resolves to the default policy. */
2432
+ /** Forwards to the channel discovery component's {@link EndpointChannelDiscovery.startChannelWatch}. */
2680
2433
  private startChannelWatch;
2681
- /** {@link EndpointOptions.readOnce}: fill the channel cache from one read of the registry. */
2434
+ /** Forwards to the channel discovery component's {@link EndpointChannelDiscovery.readChannelsOnce}. */
2682
2435
  private readChannelsOnce;
2683
- private handleChannelEntry;
2684
2436
  private sweep;
2685
2437
  }
2686
2438
  /** SPEC §5 on receive: a delivery comes from the principal its subject names. The payload is an