@cotal-ai/core 0.134.0 → 0.135.1

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 (72) hide show
  1. package/dist/agent-file.d.ts +1 -1
  2. package/dist/agent-file.d.ts.map +1 -1
  3. package/dist/agent-file.js +11 -2
  4. package/dist/agent-file.js.map +1 -1
  5. package/dist/backup-config.d.ts +5 -7
  6. package/dist/backup-config.d.ts.map +1 -1
  7. package/dist/backup-config.js +5 -9
  8. package/dist/backup-config.js.map +1 -1
  9. package/dist/connector.d.ts +48 -0
  10. package/dist/connector.d.ts.map +1 -1
  11. package/dist/connector.js.map +1 -1
  12. package/dist/endpoint-checkpoint.d.ts +2 -0
  13. package/dist/endpoint-checkpoint.d.ts.map +1 -1
  14. package/dist/endpoint-checkpoint.js +1 -1
  15. package/dist/endpoint-checkpoint.js.map +1 -1
  16. package/dist/endpoint-grants.d.ts +3 -2
  17. package/dist/endpoint-grants.d.ts.map +1 -1
  18. package/dist/endpoint-grants.js +3 -2
  19. package/dist/endpoint-grants.js.map +1 -1
  20. package/dist/endpoint-service.d.ts.map +1 -1
  21. package/dist/endpoint-service.js +14 -11
  22. package/dist/endpoint-service.js.map +1 -1
  23. package/dist/endpoint.d.ts +45 -19
  24. package/dist/endpoint.d.ts.map +1 -1
  25. package/dist/endpoint.js +165 -58
  26. package/dist/endpoint.js.map +1 -1
  27. package/dist/kv-scan.d.ts +7 -2
  28. package/dist/kv-scan.d.ts.map +1 -1
  29. package/dist/kv-scan.js +47 -28
  30. package/dist/kv-scan.js.map +1 -1
  31. package/dist/members.d.ts +8 -6
  32. package/dist/members.d.ts.map +1 -1
  33. package/dist/members.js +12 -8
  34. package/dist/members.js.map +1 -1
  35. package/dist/membership-feed.d.ts +5 -0
  36. package/dist/membership-feed.d.ts.map +1 -1
  37. package/dist/membership-feed.js +8 -1
  38. package/dist/membership-feed.js.map +1 -1
  39. package/dist/provision.js +6 -6
  40. package/dist/provision.js.map +1 -1
  41. package/dist/registry-contract.d.ts +2 -2
  42. package/dist/registry-contract.d.ts.map +1 -1
  43. package/dist/runtime.d.ts +8 -0
  44. package/dist/runtime.d.ts.map +1 -1
  45. package/dist/runtime.js.map +1 -1
  46. package/dist/schema-profile.d.ts +6 -5
  47. package/dist/schema-profile.d.ts.map +1 -1
  48. package/dist/schema-profile.js +18 -22
  49. package/dist/schema-profile.js.map +1 -1
  50. package/dist/space-schema-diff.d.ts +1 -1
  51. package/dist/space-schema-diff.d.ts.map +1 -1
  52. package/dist/space-schema-diff.js +11 -16
  53. package/dist/space-schema-diff.js.map +1 -1
  54. package/dist/startup-confirm.d.ts +18 -4
  55. package/dist/startup-confirm.d.ts.map +1 -1
  56. package/dist/startup-confirm.js +61 -12
  57. package/dist/startup-confirm.js.map +1 -1
  58. package/dist/streams.d.ts +3 -11
  59. package/dist/streams.d.ts.map +1 -1
  60. package/dist/streams.js +5 -22
  61. package/dist/streams.js.map +1 -1
  62. package/dist/subjects.d.ts +28 -12
  63. package/dist/subjects.d.ts.map +1 -1
  64. package/dist/subjects.js +49 -15
  65. package/dist/subjects.js.map +1 -1
  66. package/dist/turn-contract.d.ts +10 -0
  67. package/dist/turn-contract.d.ts.map +1 -1
  68. package/dist/turn-contract.js +18 -0
  69. package/dist/turn-contract.js.map +1 -1
  70. package/dist/types.d.ts +11 -4
  71. package/dist/types.d.ts.map +1 -1
  72. package/package.json +3 -2
package/dist/endpoint.js CHANGED
@@ -28,6 +28,7 @@ import { assertValidKind } from "./agent-file.js";
28
28
  import { assertValidName } from "./resolve.js";
29
29
  import { EVICT_PRINCIPALS_MAX } from "./evict.js";
30
30
  import { createSpaceStreams, dmDurableConfig, dlvDurableConfig, taskDurableConfig, fanoutDurableConfig, inboxReaderConfig, MANAGER_LEASE_TTL_MS, MANAGER_LEASE_ATTEMPT_MS, TTL_RECONCILE_CANARY_KEY, PRESENCE_STORAGE } from "./streams.js";
31
+ import { PLANE3_MAX_MSGS_PER_SUBJECT } from "./backup-config.js";
31
32
  import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, JetStreamApiError, } from "@nats-io/jetstream";
32
33
  import {} from "@nats-io/jetstream";
33
34
  import { Kvm } from "@nats-io/kv";
@@ -37,7 +38,7 @@ import { openAclRegistry, readAcl, readAclForAlias, aclRetired, AmbiguousAclAlia
37
38
  import { openDeliveryRegistry } from "./lease.js";
38
39
  import { openChannelRegistry, effectiveReplay, effectiveReplayWindowMs, effectiveDeliveryClass, readChannelConfig, readChannelDefaults, decodeChannelEntry, } from "./channels.js";
39
40
  import { isCasLoss } from "./endpoint-records.js";
40
- import { anycastSubject, assertValidRole, CHANNEL_DEFAULTS_KEY, chatStream, chatHistDurable, chatSubject, historyReaderConsumer, calloutReaderId, HISTORY_READERS, controlServiceSubject, livenessSubject, livenessServeFilter, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, dlvStream, dlvDurable, dlvSubject, dinboxSubject, inboxStream, parseDinboxPrincipal, FANOUT_DURABLE, INBOX_READER_DURABLE, leaseKey, managerBucket, MANAGER_LEASE_KEY, MANAGER_RENEWAL_LEASE_KEY, managerLeaseKey, chatWildcard, assertValidChannel, channelInAllow, isConcreteChannel, normalizeMentions, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, isPresenceRow, assertPresenceRow, membershipBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, memberKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
41
+ import { anycastSubject, assertValidRole, CHANNEL_DEFAULTS_KEY, chatStream, chatHistDurable, chatSubject, historyReaderConsumer, calloutReaderId, HISTORY_READERS, controlServiceSubject, livenessSubject, livenessServeFilter, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, dlvStream, dlvDurable, dlvSubject, dinboxSubject, inboxStream, parseDinboxPrincipal, FANOUT_DURABLE, INBOX_READER_DURABLE, leaseKey, managerBucket, MANAGER_LEASE_KEY, MANAGER_RENEWAL_LEASE_KEY, managerLeaseKey, chatWildcard, assertValidChannel, channelInAllow, membershipInAllow, isConcreteChannel, isChannelFamily, familiesCovering, normalizeMentions, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, isPresenceRow, assertPresenceRow, membershipBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, memberKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
41
42
  import { isPermissionDenied } from "./permission-denied.js";
42
43
  export { isPermissionDenied };
43
44
  export const DEFAULT_SERVER = "nats://127.0.0.1:4222";
@@ -124,7 +125,9 @@ export class PresenceWriteStuckError extends Error {
124
125
  * terminal close). Lets an in-process agent track connectedness off the endpoint's own (re)binds
125
126
  * instead of an imperative flag the self-heal path can't reach; "transport" ({ connected, server? })
126
127
  * is the lower-level NATS socket edge, true before the full bind finishes and false during an internal
127
- * nats.js reconnect without changing `connection` readiness.
128
+ * nats.js reconnect without changing `connection` readiness. "stored-copies-full" (no payload): a stored
129
+ * copy arrived with the store at its {@link PLANE3_MAX_MSGS_PER_SUBJECT}-copy limit, so the limit may have
130
+ * discarded older copies before this session read them; emitted for each such copy.
128
131
  *
129
132
  * Callers MUST attach an "error" listener before `start()`: async faults (incl. NATS
130
133
  * permission denials, surfaced via `watchStatus`) are emitted as "error", and Node throws
@@ -251,6 +254,7 @@ export class CotalEndpoint extends EventEmitter {
251
254
  ackWaitMs;
252
255
  inactiveThresholdMs;
253
256
  nc;
257
+ requestsAwaitingReply = new Map();
254
258
  onConnection;
255
259
  js;
256
260
  jsm;
@@ -2311,6 +2315,38 @@ export class CotalEndpoint extends EventEmitter {
2311
2315
  }
2312
2316
  }
2313
2317
  }
2318
+ /** Keep native named-reply and NoResponders handling, but settle when its connection closes:
2319
+ * nats.js can close a no-mux subscription without settling its request. One close observer per
2320
+ * connection avoids retaining a closed-promise callback for every completed request. */
2321
+ async requestBoundReply(nc, subject, body, reply, timeoutMs) {
2322
+ let pending = this.requestsAwaitingReply.get(nc);
2323
+ if (!pending) {
2324
+ const waiting = new Set();
2325
+ this.requestsAwaitingReply.set(nc, waiting);
2326
+ void nc.closed().then((error) => {
2327
+ this.requestsAwaitingReply.delete(nc);
2328
+ const failure = error ?? new ClosedConnectionError();
2329
+ for (const reject of waiting)
2330
+ reject(failure);
2331
+ waiting.clear();
2332
+ });
2333
+ pending = waiting;
2334
+ }
2335
+ let rejectClosed;
2336
+ const closed = new Promise((_resolve, reject) => {
2337
+ rejectClosed = reject;
2338
+ pending.add(reject);
2339
+ });
2340
+ try {
2341
+ return await Promise.race([
2342
+ nc.request(subject, body, { timeout: timeoutMs, noMux: true, reply }),
2343
+ closed,
2344
+ ]);
2345
+ }
2346
+ finally {
2347
+ pending.delete(rejectClosed);
2348
+ }
2349
+ }
2314
2350
  /** Send a control request to a service and await its reply (client side). Like {@link requestDelivery},
2315
2351
  * the reply rides a BOUNDED subject UNDER the request subject (`ctl.<service>.<id>.reply.<uuid>`), not
2316
2352
  * the per-id `_INBOX`.
@@ -2323,7 +2359,7 @@ export class CotalEndpoint extends EventEmitter {
2323
2359
  const reqSubject = controlServiceSubject(this.space, service, this.owner, this.actor);
2324
2360
  const reply = `${reqSubject}.reply.${randomUUID()}`;
2325
2361
  const body = { ...req, from: req.from ?? this.ref() };
2326
- const m = await this.nc.request(reqSubject, JSON.stringify(body), { timeout: timeoutMs, noMux: true, reply });
2362
+ const m = await this.requestBoundReply(this.nc, reqSubject, JSON.stringify(body), reply, timeoutMs);
2327
2363
  return m.json();
2328
2364
  }
2329
2365
  /** The caller this connection's endpoint requests ride as: the legacy triple, or the issued
@@ -2684,7 +2720,7 @@ export class CotalEndpoint extends EventEmitter {
2684
2720
  // model. Keep both; don't regress to a counter. (Confirmed by the review panel's fact-check.)
2685
2721
  const reply = `${reqSubject}.reply.${randomUUID()}`;
2686
2722
  const body = { op, args, from: this.ref() };
2687
- const m = await this.nc.request(reqSubject, JSON.stringify(body), { timeout: timeoutMs, noMux: true, reply });
2723
+ const m = await this.requestBoundReply(this.nc, reqSubject, JSON.stringify(body), reply, timeoutMs);
2688
2724
  return m.json();
2689
2725
  }
2690
2726
  /** Send a PRIVILEGED delivery-admin request to the server-side delivery daemon and await its reply
@@ -2699,7 +2735,7 @@ export class CotalEndpoint extends EventEmitter {
2699
2735
  const reqSubject = controlServiceSubject(this.space, CONTROL_DELIVERY_ADMIN, this.owner, this.actor);
2700
2736
  const reply = `${reqSubject}.reply.${randomUUID()}`;
2701
2737
  const body = { op, args, from: this.ref() };
2702
- const m = await this.nc.request(reqSubject, JSON.stringify(body), { timeout: timeoutMs, noMux: true, reply });
2738
+ const m = await this.requestBoundReply(this.nc, reqSubject, JSON.stringify(body), reply, timeoutMs);
2703
2739
  return m.json();
2704
2740
  }
2705
2741
  // ---- presence ------------------------------------------------------------
@@ -2934,8 +2970,9 @@ export class CotalEndpoint extends EventEmitter {
2934
2970
  /**
2935
2971
  * Join a channel mid-session: open a native core subscription (manager-free live read, broker-
2936
2972
  * confirmed against `sub.allow`), capture the stream frontier as the join watermark, backfill its
2937
- * history if replay is on, and — for a `durable`-class channel when a delivery daemon is present —
2938
- * request a Plane-3 durable backstop (via `ctl.delivery`). Idempotent: re-joining is a no-op (no
2973
+ * history if replay is on, and — for a `durable`-class channel or a family such as `review.>` when a
2974
+ * delivery daemon is present — request a Plane-3 durable backstop (via `ctl.delivery`). Any other
2975
+ * pattern stays live only, with a `reason`. Idempotent: re-joining is a no-op (no
2939
2976
  * re-backfill). Returns the backfill count + whether the durable backstop is active (+ a `reason`
2940
2977
  * when a durable channel couldn't get one).
2941
2978
  */
@@ -2972,10 +3009,15 @@ export class CotalEndpoint extends EventEmitter {
2972
3009
  // channel, request a Plane-3 per-member backstop from the server-side delivery daemon (durableJoin via ctl.delivery) so a post reaches a
2973
3010
  // busy/offline turn — the core-sub stays as the live wake-hint, dedup-coalesced with the Plane-3
2974
3011
  // copy by id-dedup. No manager (open dev / manager-less) ⇒ joined LIVE only, surfaced via `reason`
2975
- // (never silent). A `live`-class channel takes no backstop (joined live is the contract).
3012
+ // (never silent). A `live`-class channel takes no backstop (joined live is the contract). A family
3013
+ // (`review.>`) always asks for its row: each channel under it decides its own class at fan-out
3014
+ // (#5404). Any other pattern has no backstop, and says so.
2976
3015
  let durable = false;
2977
3016
  let reason;
2978
- if (effectiveDeliveryClass(this.channelConfigs.get(channel), this.channelDefaults) === "durable") {
3017
+ const family = isChannelFamily(channel);
3018
+ if (!family && !isConcreteChannel(channel))
3019
+ reason = "a pattern with * or the root > has no stored copies; follow a concrete channel or a family such as review.>";
3020
+ else if (family || effectiveDeliveryClass(this.channelConfigs.get(channel), this.channelDefaults) === "durable") {
2979
3021
  try {
2980
3022
  const r = await this.durableJoinChannel(channel);
2981
3023
  if (r.durable) {
@@ -3013,7 +3055,7 @@ export class CotalEndpoint extends EventEmitter {
3013
3055
  // tombstone can't be confirmed propagates (live sub stays up, mirror intact) for the caller to retry
3014
3056
  // — reporting `left` while the trusted reader keeps transferring to DLV is the fail-open leak. A
3015
3057
  // genuine no-responder (open / no delivery daemon, no Plane-3) means there is no membership to tombstone.
3016
- if (this.authed && effectiveDeliveryClass(this.channelConfigs.get(channel), this.channelDefaults) === "durable") {
3058
+ if (this.authed && (isChannelFamily(channel) || effectiveDeliveryClass(this.channelConfigs.get(channel), this.channelDefaults) === "durable")) {
3017
3059
  let generation = this.plane3Channels.get(channel);
3018
3060
  if (generation === undefined)
3019
3061
  generation = (await this.fetchMemberships())?.find((m) => m.channel === channel)?.generation;
@@ -3121,11 +3163,13 @@ export class CotalEndpoint extends EventEmitter {
3121
3163
  : { id, name: id, live: false };
3122
3164
  };
3123
3165
  const byName = (a, b) => a.name.localeCompare(b.name);
3124
- if (channel !== undefined)
3125
- return members
3126
- .filter((r) => subjectMatches(r.channel, channel))
3127
- .map((r) => memberForId(r.owner))
3128
- .sort(byName);
3166
+ if (channel !== undefined) {
3167
+ const stored = (await this.deliveryClassFresh(channel)) === "durable";
3168
+ const ids = new Set(members
3169
+ .filter((r) => r.channel === channel || (stored && isChannelFamily(r.channel) && subjectMatches(r.channel, channel)))
3170
+ .map((r) => r.owner));
3171
+ return [...ids].map(memberForId).sort(byName);
3172
+ }
3129
3173
  const map = new Map();
3130
3174
  for (const r of members) {
3131
3175
  const arr = map.get(r.channel);
@@ -4913,7 +4957,8 @@ export class CotalEndpoint extends EventEmitter {
4913
4957
  .map((r) => ({ channel: r.channel, generation: r.generation, activated: r.activated === true }));
4914
4958
  }
4915
4959
  /** Effective delivery class read AUTHORITATIVELY from the registry KV (not the watch cache) — so a
4916
- * `live`→`durable` flip is seen by fan-out without a cache-propagation gap (red-team MED-3). */
4960
+ * `live`→`durable` flip is seen by fan-out without a cache-propagation gap (red-team MED-3), and a
4961
+ * reader just started need not wait for the cache to fill. */
4917
4962
  async deliveryClassFresh(channel) {
4918
4963
  if (!this.channelKv)
4919
4964
  return effectiveDeliveryClass(undefined, undefined);
@@ -4930,17 +4975,21 @@ export class CotalEndpoint extends EventEmitter {
4930
4975
  const matches = [...this.roster.values()].filter((p) => p.card.name.toLowerCase() === name.toLowerCase());
4931
4976
  return matches.length === 1 ? matches[0].card.id : undefined;
4932
4977
  }
4933
- /** Plane-3 publish-dedupe key for a fan-out/transfer entry (#673, SPEC §4: two `id: ""` posts
4934
- * MUST NOT collapse to one delivery). An empty `msg.id` contributes NO msgID — a plain publish,
4935
- * never an empty or salted one — so an id-less message is at-least-once on the durable plane (a
4936
- * redelivery may reach the member twice; the receiver already treats each as its own delivery). */
4937
- plane3MsgId(entry, keyPrefix) {
4938
- return entry.msg.id === "" ? {} : { msgID: `${entry.msg.id}:${keyPrefix}` };
4978
+ /** Plane-3 publish-dedupe key for a fan-out/transfer entry: the message id plus the member
4979
+ * lifecycle (`keySuffix`). One message reaches one lifecycle once, whichever membership row and
4980
+ * whichever writer (fan-out or any row's catch-up) produced the copy (#5404), within the stream's
4981
+ * duplicate window. An empty `msg.id` contributes NO msgID (#673, SPEC §4: two `id: ""` posts MUST
4982
+ * NOT collapse to one delivery) — a plain publish, never an empty or salted one — so an id-less
4983
+ * message is at-least-once on the durable plane (a redelivery may reach the member twice; the
4984
+ * receiver already treats each as its own delivery). */
4985
+ plane3MsgId(entry, keySuffix) {
4986
+ return entry.msg.id === "" ? {} : { msgID: `${entry.msg.id}:${keySuffix}` };
4939
4987
  }
4940
4988
  /** Publish one fan-out entry into a member LIFECYCLE's mixed inbox (`dinbox.<o>.<a>.<uid>`, SPEC
4941
4989
  * §13.1: fan-out addresses the member row's RECORDED lifecycle, never the alias's current
4942
- * occupant), idempotent via `Nats-Msg-Id` (`<msgId>:<principal>:<generation>`) so a catch-up copy
4943
- * and a racing fan-out copy collapse. The `principal` is the member's owner+actor dot-form. */
4990
+ * occupant), idempotent via `Nats-Msg-Id` (`<msgId>:<principal>:<lifecycleUid>`) so a catch-up copy
4991
+ * and a racing fan-out copy collapse, from the same row or from two rows that both cover the post.
4992
+ * The `principal` is the member's owner+actor dot-form. */
4944
4993
  async publishDinbox(principal, lifecycleUid, entry) {
4945
4994
  if (!this.js)
4946
4995
  return;
@@ -4949,9 +4998,10 @@ export class CotalEndpoint extends EventEmitter {
4949
4998
  throw new Error(`publishDinbox: "${principal}" is not a valid member principal <owner>.<actor>`);
4950
4999
  await this.js.publish(dinboxSubject(this.space, p.owner, p.actor, lifecycleUid), JSON.stringify(entry), {
4951
5000
  // JetStream dedupe is STREAM-WIDE, so the id must carry the LIFECYCLE too: with an alias-keyed
4952
- // id, lifecycle A's copy would suppress a same-alias successor B's copy of the same message
4953
- // (both start at generation 1) — cross-lifecycle suppression, not dedup.
4954
- ...this.plane3MsgId(entry, `${principal}:${lifecycleUid}:${entry.generation}`),
5001
+ // id, lifecycle A's copy would suppress a same-alias successor B's copy of the same message —
5002
+ // cross-lifecycle suppression, not dedup. It carries no row generation: two rows of one
5003
+ // lifecycle covering the post must collapse to one copy.
5004
+ ...this.plane3MsgId(entry, `${principal}:${lifecycleUid}`),
4955
5005
  });
4956
5006
  }
4957
5007
  /** The fan-out consumer's delivered stream-seq — the activation-fence upper bound (red-team
@@ -5021,11 +5071,12 @@ export class CotalEndpoint extends EventEmitter {
5021
5071
  return { durable: false, reason: "activation superseded by a concurrent leave or rejoin", generation };
5022
5072
  return { durable: true, generation };
5023
5073
  }
5024
- /** Whether one lifecycle's exact ACL row allows `channel` now. A leader-served read: the handle is
5025
- * opened without direct reads, so a row narrowed before this read began is the row it returns. */
5074
+ /** Whether one lifecycle's exact ACL row allows a membership on `channel` now (a family must lie
5075
+ * inside one entry, {@link membershipInAllow}). A leader-served read: the handle is opened without
5076
+ * direct reads, so a row narrowed before this read began is the row it returns. */
5026
5077
  async aclAllows(owner, lifecycleUid, channel) {
5027
5078
  const row = await readAcl(await this.aclRegistry(), owner, lifecycleUid);
5028
- return row !== undefined && channelInAllow(row.record.allowSubscribe, channel);
5079
+ return row !== undefined && membershipInAllow(row.record.allowSubscribe, channel);
5029
5080
  }
5030
5081
  /** The post-write half of {@link durableJoinFor}'s `aclFence`: keep the row just written (at
5031
5082
  * `revision`) only on proof that the lifecycle's ACL row still allows the channel, and refuse the
@@ -5072,11 +5123,27 @@ export class CotalEndpoint extends EventEmitter {
5072
5123
  /** Idempotently copy the eligible chat messages in `(fromSeqExcl, toSeqIncl]` for `channel` into the
5073
5124
  * owner inbox, via a DEDICATED per-(owner,join) ephemeral consumer (NOT the agent-scoped
5074
5125
  * `chathist_<id>`/`histLock` — red-team HIGH-8). It copies what the stream still holds in that
5075
- * window; a post the history limit removed first is not copied and is not reported (SPEC §4). */
5126
+ * window; a post the history limit removed first is not copied and is not reported (SPEC §4).
5127
+ *
5128
+ * A FAMILY row (`review.>`, #5404) reads the window on every channel under it and copies a post only
5129
+ * when that post's own channel is durable-class. Each copy names the post's own channel, never the
5130
+ * family, and it skips nothing another row of the lifecycle covers: two joins can both be pending
5131
+ * when a post lands, so neither proves the other copied it. The per-message, per-lifecycle dedupe id
5132
+ * keeps one copy. */
5076
5133
  async catchupCopy(owner, lifecycleUid, channel, fromSeqExcl, toSeqIncl, generation) {
5077
5134
  if (!this.js || !this.jsm || toSeqIncl <= fromSeqExcl)
5078
5135
  return 0;
5079
5136
  const subject = chatSubject(this.space, "*", "*", channel);
5137
+ const family = isChannelFamily(channel);
5138
+ const durableClass = new Map();
5139
+ const stored = (ch) => {
5140
+ if (!family)
5141
+ return Promise.resolve(true);
5142
+ let cls = durableClass.get(ch);
5143
+ if (cls === undefined)
5144
+ durableClass.set(ch, (cls = this.deliveryClassFresh(ch).then((c) => c === "durable")));
5145
+ return cls;
5146
+ };
5080
5147
  // Consumer NAME must be JetStream-safe (no `.`) AND collision-free: use the principal DASH-form
5081
5148
  // (`<owner>-<actor>`, `-` reserved as the sole separator), NOT `token(owner)` — `token()` maps the
5082
5149
  // dot-form `.`→`_`, which is NOT collision-free (`_` is legal inside a token, so `a.b_c` and `a_b.c`
@@ -5113,7 +5180,11 @@ export class CotalEndpoint extends EventEmitter {
5113
5180
  const parsed = parseSubject(m.subject);
5114
5181
  if (!parsed || !isFromSubjectSender(msg, parsed) || msg.from.id === owner)
5115
5182
  continue;
5116
- await this.publishDinbox(owner, lifecycleUid, { msg, channel, seq: m.seq, reason: "durable-channel", generation });
5183
+ if (!(await stored(parsed.rest)))
5184
+ continue;
5185
+ await this.publishDinbox(owner, lifecycleUid, {
5186
+ msg, channel: parsed.rest, seq: m.seq, reason: "durable-channel", generation, ...(family ? { row: channel } : {}),
5187
+ });
5117
5188
  copied++;
5118
5189
  }
5119
5190
  if (got < want)
@@ -5195,8 +5266,9 @@ export class CotalEndpoint extends EventEmitter {
5195
5266
  return { ok: false, error: `op "${req.op}" not supported on the delivery control service` };
5196
5267
  }
5197
5268
  /** Validate the channel ARG shape only: non-blank, valid, concrete (NO ACL check, that is op-specific).
5269
+ * `family` also admits a channel family such as `review.>` (a membership join or leave, #5404).
5198
5270
  * Returns the channel on success or a ControlReply error to short-circuit. */
5199
- checkDurableChannelArg(args, op) {
5271
+ checkDurableChannelArg(args, op, opts = {}) {
5200
5272
  const channel = typeof args.channel === "string" ? args.channel.trim() : "";
5201
5273
  if (!channel)
5202
5274
  return { ok: false, error: `${op}: channel must be a non-blank string` };
@@ -5206,14 +5278,22 @@ export class CotalEndpoint extends EventEmitter {
5206
5278
  catch (e) {
5207
5279
  return { ok: false, error: e.message };
5208
5280
  }
5281
+ if (opts.family && isChannelFamily(channel))
5282
+ return channel;
5209
5283
  if (!isConcreteChannel(channel))
5210
- return { ok: false, error: `${op}: "${channel}" must be a concrete channel (durable membership is per-concrete-channel, not wildcard)` };
5284
+ return {
5285
+ ok: false,
5286
+ error: opts.family
5287
+ ? `${op}: "${channel}" stays live only: a durable membership takes a concrete channel or a family such as review.>, never the root > or a pattern with *`
5288
+ : `${op}: "${channel}" must be a concrete channel (durable membership is per-concrete-channel, not wildcard)`,
5289
+ };
5211
5290
  return channel;
5212
5291
  }
5213
5292
  /** JOIN requires the channel be within the caller's CURRENT read ACL (you can't durable-subscribe a
5214
- * channel you may not read). */
5293
+ * channel you may not read). A family must lie inside one ACL entry, so every channel under it is
5294
+ * readable. */
5215
5295
  async deliveryJoin(caller, args) {
5216
- const channel = this.checkDurableChannelArg(args, "durableJoin");
5296
+ const channel = this.checkDurableChannelArg(args, "durableJoin", { family: true });
5217
5297
  if (typeof channel !== "string")
5218
5298
  return channel; // a ControlReply error
5219
5299
  // The caller arrives as an ALIAS (the control subject carries owner+actor, never a uid): resolve
@@ -5229,7 +5309,7 @@ export class CotalEndpoint extends EventEmitter {
5229
5309
  }
5230
5310
  if (acl === undefined)
5231
5311
  return { ok: false, error: `durableJoin: no read ACL on record for ${caller} (not provisioned for durable delivery)` };
5232
- if (!channelInAllow(acl.allowSubscribe, channel))
5312
+ if (!membershipInAllow(acl.allowSubscribe, channel))
5233
5313
  return { ok: false, error: `channel "${channel}" is not within your read ACL [${acl.allowSubscribe.join(", ")}]` };
5234
5314
  const uid = acl.lifecycleUid;
5235
5315
  // The lookup above may be stale by the time the row is written (a retirement can fence and purge
@@ -5282,7 +5362,7 @@ export class CotalEndpoint extends EventEmitter {
5282
5362
  * (the join epoch — without it a stale/replayed leave could tombstone a newer rejoin), and an EXISTING
5283
5363
  * own membership; `durableLeaveFor` → `tombstoneMember` then enforces the generation match. */
5284
5364
  async deliveryLeave(caller, args) {
5285
- const channel = this.checkDurableChannelArg(args, "durableLeave");
5365
+ const channel = this.checkDurableChannelArg(args, "durableLeave", { family: true });
5286
5366
  if (typeof channel !== "string")
5287
5367
  return channel; // a ControlReply error
5288
5368
  if (typeof args.generation !== "number" || !Number.isFinite(args.generation))
@@ -5708,7 +5788,7 @@ export class CotalEndpoint extends EventEmitter {
5708
5788
  let answered;
5709
5789
  let instance;
5710
5790
  try {
5711
- const m = await this.nc.request(reqSubject, "", { timeout: timeoutMs, noMux: true, reply });
5791
+ const m = await this.requestBoundReply(this.nc, reqSubject, "", reply, timeoutMs);
5712
5792
  let body;
5713
5793
  try {
5714
5794
  body = m.json();
@@ -6023,7 +6103,9 @@ export class CotalEndpoint extends EventEmitter {
6023
6103
  if (!this.plane3MayAct())
6024
6104
  return;
6025
6105
  if ((await this.deliveryClassFresh(channel)) === "durable") {
6026
- for (const rec of await listMembers(await this.membersRegistry(), { channel })) {
6106
+ // The channel's own rows and every family row above it (`review.>`). A lifecycle holding two of
6107
+ // them gets two publishes and keeps one copy: the dedupe id is per message and lifecycle (#5404).
6108
+ for (const rec of await listMembers(await this.membersRegistry(), { covering: channel })) {
6027
6109
  if (rec.owner === msg.from.id)
6028
6110
  continue; // never backstop the sender's own post
6029
6111
  if (!durableEligible(rec, seq))
@@ -6038,7 +6120,10 @@ export class CotalEndpoint extends EventEmitter {
6038
6120
  // re-sends the whole set; publishDinbox is idempotent per (owner, lifecycle, msgID).
6039
6121
  if (!this.plane3MayAct())
6040
6122
  return;
6041
- await this.publishDinbox(rec.owner, rec.lifecycleUid, { msg: normalizedMsg, channel, seq, reason: "durable-channel", generation: rec.generation });
6123
+ await this.publishDinbox(rec.owner, rec.lifecycleUid, {
6124
+ msg: normalizedMsg, channel, seq, reason: "durable-channel", generation: rec.generation,
6125
+ ...(rec.channel !== channel ? { row: rec.channel } : {}),
6126
+ });
6042
6127
  }
6043
6128
  }
6044
6129
  else {
@@ -6097,6 +6182,17 @@ export class CotalEndpoint extends EventEmitter {
6097
6182
  })().catch((e) => { if (!this.stopped)
6098
6183
  this.emit("error", e); });
6099
6184
  }
6185
+ /** Whether one of the lifecycle's rows covering concrete `channel`, the channel's own or a family
6186
+ * above it, is eligible for the post at `seq`. One exact read per row, the channel's own first. */
6187
+ async lifecycleCoversPost(owner, lifecycleUid, channel, seq) {
6188
+ const kv = await this.membersRegistry();
6189
+ for (const row of [channel, ...familiesCovering(channel).reverse()]) {
6190
+ const rec = await readMember(kv, row, owner, lifecycleUid);
6191
+ if (rec && durableEligible(rec.record, seq))
6192
+ return true;
6193
+ }
6194
+ return false;
6195
+ }
6100
6196
  /** Remove a retired lifecycle's member row for `channel`, when one exists. Best effort: the row
6101
6197
  * authorizes nothing (its ACL row is retired), and the next entry fan-out writes against it
6102
6198
  * brings the reader back here. */
@@ -6182,7 +6278,7 @@ export class CotalEndpoint extends EventEmitter {
6182
6278
  // removes each copy. Remove the row where that cost is paid, by its exact key, only when it
6183
6279
  // exists: a purge of an absent key would write a marker per dropped entry.
6184
6280
  if (entry.reason === "durable-channel")
6185
- await this.removeRetiredMemberRow(entry.channel, owner, pr.lifecycleUid);
6281
+ await this.removeRetiredMemberRow(entry.row ?? entry.channel, owner, pr.lifecycleUid);
6186
6282
  if (!this.plane3MayAct())
6187
6283
  return;
6188
6284
  m.ack();
@@ -6208,14 +6304,12 @@ export class CotalEndpoint extends EventEmitter {
6208
6304
  m.ack();
6209
6305
  return;
6210
6306
  }
6211
- if (entry.reason === "durable-channel") {
6212
- const rec = await readMember(await this.membersRegistry(), entry.channel, owner, pr.lifecycleUid);
6213
- // INTERVAL re-auth (not a current-member boolean): a pre-leave entry (seq ≤ leaveCursor) stays
6214
- // deliverable; seq > leaveCursor (or after a rejoin's newer joinCursor) is the hard cut.
6215
- if (!rec || !durableEligible(rec.record, entry.seq)) {
6216
- m.ack();
6217
- return;
6218
- }
6307
+ // INTERVAL re-auth (not a current-member boolean): a pre-leave entry (seq ≤ leaveCursor) stays
6308
+ // deliverable; seq > leaveCursor (or after a rejoin's newer joinCursor) is the hard cut. Any of the
6309
+ // lifecycle's rows that cover the channel may hold the post, whichever row addressed the copy.
6310
+ if (entry.reason === "durable-channel" && !(await this.lifecycleCoversPost(owner, pr.lifecycleUid, entry.channel, entry.seq))) {
6311
+ m.ack();
6312
+ return;
6219
6313
  }
6220
6314
  // COMMIT-POINT FENCE. Everything above this line is broker I/O - the ACL read and the member
6221
6315
  // re-read - so the entry check at the top of the handler is stale by now if this unit was
@@ -6237,7 +6331,7 @@ export class CotalEndpoint extends EventEmitter {
6237
6331
  // subject (streams.ts filter_subject), and a predecessor's transferred copy must never suppress
6238
6332
  // a successor's under the same alias (disjoint lifecycles, stream-wide dedupe).
6239
6333
  await this.js.publish(dlvSubject(this.space, pr.owner, pr.actor, pr.lifecycleUid), JSON.stringify(frame), {
6240
- ...this.plane3MsgId(entry, `${owner}:${pr.lifecycleUid}:${entry.generation}`),
6334
+ ...this.plane3MsgId(entry, `${owner}:${pr.lifecycleUid}`),
6241
6335
  headers: frameHeaders,
6242
6336
  });
6243
6337
  }
@@ -6290,6 +6384,12 @@ export class CotalEndpoint extends EventEmitter {
6290
6384
  this.streamMsgs.push(msgs);
6291
6385
  void (async () => {
6292
6386
  for await (const m of msgs) {
6387
+ // A copy with a full store behind it means the store held its limit, so older copies may have
6388
+ // been discarded unread (#5404); NATS gives no notice of the discard itself. Checked on every
6389
+ // delivery, ahead of the checks below and the connector's id dedupe, so a copy the agent also
6390
+ // got live cannot hide it. The connector folds repeats into one notice.
6391
+ if (m.info.pending >= PLANE3_MAX_MSGS_PER_SUBJECT - 1)
6392
+ this.emit("stored-copies-full");
6293
6393
  // The header is minted only by the trusted DLV writer. A body-only discriminator is
6294
6394
  // insufficient because old Cotal envelopes permit unknown fields and could imitate it.
6295
6395
  if (m.headers?.get(PLANE3_FRAME_HEADER) !== "1") {
@@ -6406,7 +6506,8 @@ export class CotalEndpoint extends EventEmitter {
6406
6506
  }
6407
6507
  /** Agent-side, first connect (auth): SELF-JOIN this session's durable boot channels via the
6408
6508
  * server-side delivery daemon — replacing the old manager-written boot membership. Each concrete
6409
- * `durable`-class boot channel gets a `durableJoin` whose returned generation seeds the leave mirror
6509
+ * `durable`-class boot channel, and each family such as `review.>`, gets a `durableJoin` whose
6510
+ * returned generation seeds the leave mirror
6410
6511
  * + durable-state surface; an already-active membership (a relaunch) is idempotent (no re-catch-up).
6411
6512
  * If the daemon is down/absent at first connect (or reports a transient `durable:false`), the channel
6412
6513
  * is handed to {@link reconcileBootJoin} for capped-backoff retry — so the backstop is RESTORED once
@@ -6414,13 +6515,19 @@ export class CotalEndpoint extends EventEmitter {
6414
6515
  * degraded in `cotal_channels` ({@link hasDurableMembership}). */
6415
6516
  async armBootDurableMemberships() {
6416
6517
  for (const channel of this.channels) {
6417
- if (!isConcreteChannel(channel) || this.plane3Channels.has(channel))
6418
- continue;
6419
- // A missing channel row legitimately resolves through the defaults. A failed/denied registry
6420
- // read does not prove the channel is live-only, so let it fail startup loudly.
6421
- const cls = await this.deliveryClassFresh(channel);
6422
- if (cls !== "durable")
6518
+ if (this.plane3Channels.has(channel))
6423
6519
  continue;
6520
+ // A family (`review.>`) asks for its row whatever the default class: each channel under it decides
6521
+ // its own at fan-out (#5404). Any other pattern has no durable membership.
6522
+ if (!isChannelFamily(channel)) {
6523
+ if (!isConcreteChannel(channel))
6524
+ continue;
6525
+ // A missing channel row legitimately resolves through the defaults. A failed/denied registry
6526
+ // read does not prove the channel is live-only, so let it fail startup loudly.
6527
+ const cls = await this.deliveryClassFresh(channel);
6528
+ if (cls !== "durable")
6529
+ continue;
6530
+ }
6424
6531
  try {
6425
6532
  const r = await this.durableJoinChannel(channel);
6426
6533
  if (r.durable)