@cotal-ai/core 0.170.0 → 0.171.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 (33) hide show
  1. package/dist/agent-endpoint.d.ts +146 -5
  2. package/dist/agent-endpoint.d.ts.map +1 -1
  3. package/dist/agent-endpoint.js +69 -12
  4. package/dist/agent-endpoint.js.map +1 -1
  5. package/dist/connector-setup.d.ts +2 -0
  6. package/dist/connector-setup.d.ts.map +1 -1
  7. package/dist/endpoint-action.d.ts +2 -2
  8. package/dist/endpoint-action.js +6 -7
  9. package/dist/endpoint-action.js.map +1 -1
  10. package/dist/endpoint-boot-memberships.d.ts +71 -0
  11. package/dist/endpoint-boot-memberships.d.ts.map +1 -0
  12. package/dist/endpoint-boot-memberships.js +119 -0
  13. package/dist/endpoint-boot-memberships.js.map +1 -0
  14. package/dist/endpoint-journal.d.ts.map +1 -1
  15. package/dist/endpoint-journal.js +14 -6
  16. package/dist/endpoint-journal.js.map +1 -1
  17. package/dist/endpoint-provisioning.d.ts +73 -0
  18. package/dist/endpoint-provisioning.d.ts.map +1 -0
  19. package/dist/endpoint-provisioning.js +122 -0
  20. package/dist/endpoint-provisioning.js.map +1 -0
  21. package/dist/endpoint.d.ts +10 -33
  22. package/dist/endpoint.d.ts.map +1 -1
  23. package/dist/endpoint.js +44 -150
  24. package/dist/endpoint.js.map +1 -1
  25. package/dist/provision-permission-builders.d.ts +356 -0
  26. package/dist/provision-permission-builders.d.ts.map +1 -0
  27. package/dist/provision-permission-builders.js +1383 -0
  28. package/dist/provision-permission-builders.js.map +1 -0
  29. package/dist/provision-permissions.d.ts +2 -47
  30. package/dist/provision-permissions.d.ts.map +1 -1
  31. package/dist/provision-permissions.js +9 -1378
  32. package/dist/provision-permissions.js.map +1 -1
  33. package/package.json +1 -1
package/dist/endpoint.js CHANGED
@@ -32,7 +32,7 @@ import { isConsumerNotFound, isJetStreamMissing, isStreamNotFound } from "./jets
32
32
  import { assertValidKind } from "./agent-file.js";
33
33
  import { assertValidName } from "./resolve.js";
34
34
  import { nextHeartbeat } from "./presence-heartbeat.js";
35
- import { anycastStoreDefinition, createSpaceStreams, dmDurableConfig, dlvDurableConfig, taskDurableConfig, PRESENCE_STORAGE } from "./streams.js";
35
+ import { anycastStoreDefinition, taskDurableConfig, PRESENCE_STORAGE } from "./streams.js";
36
36
  import { DELIVERY_LIMIT_HEADER, PLANE3_MAX_MSGS_PER_SUBJECT } from "./backup-config.js";
37
37
  import { jetstream, jetstreamManager, AckPolicy, DeliverPolicy, JetStreamApiCodes, } from "@nats-io/jetstream";
38
38
  import {} from "@nats-io/jetstream";
@@ -47,11 +47,13 @@ import { EndpointDurableBackstop } from "./endpoint-durable-backstop.js";
47
47
  import { EndpointSubscriptions, membershipConsumerReleased } from "./endpoint-subscriptions.js";
48
48
  import { EndpointChannelDiscovery } from "./endpoint-channel-discovery.js";
49
49
  import { EndpointLiveness } from "./endpoint-liveness.js";
50
+ import { EndpointProvisioning } from "./endpoint-provisioning.js";
51
+ import { EndpointBootMemberships } from "./endpoint-boot-memberships.js";
50
52
  import { ackWaitOf, authenticatedChannelMessage, durableDelivery, isRecord } from "./endpoint-inbound.js";
51
53
  import { openChannelRegistry, effectiveReplay, effectiveReplayWindowMs, readChannelConfig, readChannelDefaults, } from "./channels.js";
52
54
  import { isCasLoss } from "./endpoint-records.js";
53
55
  import { ANYCAST_CANCEL_OP, ANYCAST_NOTICE_KEY, ANYCAST_RECORDS_CREDENTIAL_OUTDATED, ANYCAST_STATUS_OP, ANYCAST_TAKES_OP, AnycastRequestAuthority, isAnycastSeq, } from "./anycast-requests.js";
54
- import { assertValidRole, chatStream, chatSubject, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, dlvStream, membershipInAllow, isConcreteChannel, isChannelFamily, MENTION_NOTICE_KEY, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, takeServeFilter, takeSubject, parseTakeSubject, TAKE_ROUTE, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
56
+ import { assertValidRole, chatStream, chatSubject, controlServiceSubject, CONTROL_DELIVERY, CONTROL_DELIVERY_ADMIN, dmStream, dmDurable, membershipInAllow, isConcreteChannel, isChannelFamily, MENTION_NOTICE_KEY, parseSubject, isPrincipalOwnerToken, assertInboxConnId, presenceBucket, MEMBERSHIP_FEED_KEY, principalKey, parsePrincipalKey, assertLifecycleToken, mintLifecycleUid, lifecycleNameKey, DEV_OWNER, spacePrefix, spaceWildcard, subjectMatches, taskStream, taskDurable, takeServeFilter, takeSubject, parseTakeSubject, TAKE_ROUTE, token, unicastSubject, unicastRecvFilter, } from "./subjects.js";
55
57
  import { isPermissionDenied } from "./permission-denied.js";
56
58
  export { isPermissionDenied };
57
59
  export const DEFAULT_SERVER = "nats://127.0.0.1:4222";
@@ -3079,26 +3081,26 @@ export class CotalEndpoint extends EventEmitter {
3079
3081
  throw error;
3080
3082
  }
3081
3083
  }
3082
- /** Create the three backing streams for this space (idempotent). Open-mode lazy create;
3083
- * the same definitions are used by `cotal up` at privileged setup. */
3084
+ /** Stream creation and the privileged DM, DELIVER and TASK durable provisioning of this endpoint.
3085
+ * Every dependency is read when it is used, so a field assigned after construction is seen. */
3086
+ provisioning = new EndpointProvisioning({
3087
+ jsm: () => this.jsm,
3088
+ space: () => this.space,
3089
+ authed: () => this.authed,
3090
+ notLiveMsg: () => this.notLiveMsg(),
3091
+ manager: () => this.manager(),
3092
+ });
3093
+ /** Forwards to the provisioning component's {@link EndpointProvisioning.ensureStreams}. */
3084
3094
  async ensureStreams() {
3085
- if (!this.jsm)
3086
- throw new Error(this.notLiveMsg());
3087
- await createSpaceStreams(this.jsm, this.space);
3095
+ return this.provisioning.ensureStreams();
3088
3096
  }
3089
3097
  /** Create this open space's message streams if they are not there yet, as a consuming endpoint
3090
3098
  * does when it starts. For a sender that consumes nothing and may be the space's first
3091
3099
  * participant (#7045). An authenticated broker's streams come from its setup, and its agents may
3092
3100
  * not create them, so this throws there. */
3093
3101
  async ensureOpenSpaceStreams() {
3094
- if (this.authed)
3095
- throw new Error(`the streams of ${this.space} come from its broker's setup on an authenticated space; a sender does not create them`);
3096
- await createSpaceStreams(await this.manager(), this.space);
3097
- }
3098
- // (v3) The old `provisionMembership` — manager/provisioner-written boot membership at spawn — is GONE.
3099
- // Boot durable membership is now the AGENT self-joining its durable boot channels via the daemon's
3100
- // `ctl.delivery` op at connect ({@link armBootDurableMemberships}), reconciled on outage. The
3101
- // primitive it wrapped, {@link durableJoinFor}, is now driven by the daemon's `ctl.delivery` handler.
3102
+ return this.provisioning.ensureOpenSpaceStreams();
3103
+ }
3102
3104
  /**
3103
3105
  * Privileged: pre-create an agent's DM inbox durable (auth mode), so the agent can BIND
3104
3106
  * it without holding CONSUMER.CREATE on DM_<space>. The creator sets the filter to
@@ -3107,56 +3109,11 @@ export class CotalEndpoint extends EventEmitter {
3107
3109
  * safe to call again on manager restart. The caller must be permissive on DM_<space>.
3108
3110
  */
3109
3111
  async provisionDmInbox(owner, actor, lifecycleUid) {
3110
- await this.ensureDmDurable(owner, actor, lifecycleUid, {});
3111
- }
3112
- /** Idempotent-PER-LIFECYCLE create of a `dm_<o>-<a>-<uid>` durable with its ACTIVATION FRONTIER
3113
- * (SPEC §8). Info-first: an existing durable (a manager-restart re-provision of the SAME uid, or
3114
- * the same lifecycle's own restart) is kept as-is, preserving the ORIGINAL frontier — the
3115
- * activation moment never moves. A fresh lifecycle captures the DM stream's current `last_seq` and
3116
- * starts delivery at frontier+1, so a same-alias successor inherits none of the predecessor's
3117
- * pending DMs (its filter is the shared alias subject `inst.>`; the FRONTIER, not the subject, is
3118
- * the cut).
3119
- *
3120
- * HONESTY (panel-locked): the no-gap guarantee (a DM published between the capture and the create
3121
- * lands ABOVE the frontier and is delivered) holds ONLY under ONE provisioner per lifecycle uid —
3122
- * the manager provisions sequentially, which satisfies it. Under CONCURRENT same-uid provisioners
3123
- * (a split-brain manager), a higher-frontier winner excludes the loser's N+1..M capture window:
3124
- * the lost-race branch below keeps the winner's durable unconditionally. No per-uid serialization
3125
- * or persisted-frontier machinery is added in this slice; concurrent same-uid provisioning is
3126
- * out-of-contract (at-least-once best-effort). */
3112
+ return this.provisioning.provisionDmInbox(owner, actor, lifecycleUid);
3113
+ }
3114
+ /** Forwards to the provisioning component's {@link EndpointProvisioning.ensureDmDurable}. */
3127
3115
  async ensureDmDurable(owner, actor, lifecycleUid, opts) {
3128
- const jsm = await this.manager();
3129
- const stream = dmStream(this.space);
3130
- const name = dmDurable(owner, actor, lifecycleUid);
3131
- try {
3132
- await jsm.consumers.info(stream, name);
3133
- return; // this lifecycle's durable exists — keep its original frontier
3134
- }
3135
- catch (e) {
3136
- if (!isJetStreamMissing(e, JetStreamApiCodes.ConsumerNotFound))
3137
- throw e;
3138
- // Genuinely absent consumer: create it below. A denial is not absence.
3139
- }
3140
- const frontier = (await jsm.streams.info(stream)).state.last_seq;
3141
- try {
3142
- await jsm.consumers.add(stream, dmDurableConfig(this.space, owner, actor, lifecycleUid, { ...opts, activationFrontier: frontier }));
3143
- }
3144
- catch (e) {
3145
- // A concurrent same-lifecycle provisioner may have won the create with an earlier frontier —
3146
- // if the durable now exists it is authoritative; anything else stays a loud failure.
3147
- try {
3148
- await jsm.consumers.info(stream, name);
3149
- return;
3150
- }
3151
- catch (probeError) {
3152
- // The probe never creates a successful result: it either proves the concurrent winner above,
3153
- // or the original create failure stays authoritative. Preserve a denial from the probe because
3154
- // it names the missing capability more accurately than an unrelated create conflict.
3155
- if (isPermissionDenied(probeError))
3156
- throw probeError;
3157
- }
3158
- throw e;
3159
- }
3116
+ return this.provisioning.ensureDmDurable(owner, actor, lifecycleUid, opts);
3160
3117
  }
3161
3118
  /**
3162
3119
  * Privileged: pre-create an agent's bind-only Plane-3 DELIVER durable (`dlv_<id>`, filtered to
@@ -3166,8 +3123,7 @@ export class CotalEndpoint extends EventEmitter {
3166
3123
  * acks them via native JetStream (SPEC §8). Idempotent. The caller must be permissive on DLV.
3167
3124
  */
3168
3125
  async provisionDlvInbox(owner, actor, lifecycleUid) {
3169
- const jsm = await this.manager();
3170
- await jsm.consumers.add(dlvStream(this.space), dlvDurableConfig(this.space, owner, actor, lifecycleUid));
3126
+ return this.provisioning.provisionDlvInbox(owner, actor, lifecycleUid);
3171
3127
  }
3172
3128
  /**
3173
3129
  * Privileged: pre-create a role's shared TASK work-queue durable (auth mode), so agents
@@ -3176,8 +3132,7 @@ export class CotalEndpoint extends EventEmitter {
3176
3132
  * Idempotent per role. The caller must be permissive on TASK_<space>.
3177
3133
  */
3178
3134
  async provisionTaskQueue(role) {
3179
- const jsm = await this.manager();
3180
- await jsm.consumers.add(taskStream(this.space), taskDurableConfig(this.space, role));
3135
+ return this.provisioning.provisionTaskQueue(role);
3181
3136
  }
3182
3137
  // ---- Plane-3: durable backstop (SPEC §8) — privileged, hosted by the server-side DELIVERY DAEMON ----
3183
3138
  //
@@ -4390,99 +4345,38 @@ export class CotalEndpoint extends EventEmitter {
4390
4345
  }
4391
4346
  return reply.data;
4392
4347
  }
4348
+ /** The boot durable self-join and its reconcile, and the membership read the leave path uses, of
4349
+ * this endpoint. Every dependency is read when it is used, and every endpoint method is looked up
4350
+ * at call time, so a test that replaces one on the endpoint is seen here. */
4351
+ bootMemberships = new EndpointBootMemberships({
4352
+ channels: () => this.channels,
4353
+ plane3Channels: () => this.plane3Channels,
4354
+ pendingBootJoins: () => this.pendingBootJoins,
4355
+ stopped: () => this.stopped,
4356
+ requestDelivery: (op, args, timeoutMs) => this.requestDelivery(op, args, timeoutMs),
4357
+ requireLifecycleUid: (what) => this.requireLifecycleUid(what),
4358
+ deliveryClassFresh: (channel) => this.deliveryClassFresh(channel),
4359
+ durableJoinChannel: (channel) => this.durableJoinChannel(channel),
4360
+ membershipPause: (attempt) => this.membershipPause(attempt),
4361
+ isNoResponders: (e) => this.isNoResponders(e),
4362
+ emitRecoverable: (err) => this.emitRecoverable(err),
4363
+ });
4393
4364
  /** Agent-side: current lifecycle memberships, or all principal-owned rows for an explicit channel,
4394
4365
  * from the delivery service. The agent holds no read on the privileged members KV. `undefined` ⇒ NO control responder
4395
4366
  * (open / no delivery daemon, so there is no Plane-3 and no memberships). THROWS on a responder-present RPC
4396
4367
  * failure, so a caller can FAIL-CLOSED rather than mistaking a transient error for "no membership". */
4397
4368
  async fetchMemberships(channel) {
4398
- let reply;
4399
- try {
4400
- reply = await this.requestDelivery("listMemberships", { lifecycleUid: this.requireLifecycleUid("listing durable memberships"), ...(channel === undefined ? {} : { channel }) }, 5_000);
4401
- }
4402
- catch (e) {
4403
- if (this.isNoResponders(e))
4404
- return undefined; // no delivery daemon — open / daemon-less, no Plane-3
4405
- throw e; // responder present but errored — surface it (leaveChannel fails closed)
4406
- }
4407
- if (!reply.ok)
4408
- throw new Error(reply.error ?? "listMemberships failed");
4409
- return reply.data?.memberships ?? [];
4410
- }
4411
- /** Agent-side, first connect (auth): SELF-JOIN this session's durable boot channels via the
4412
- * server-side delivery daemon — replacing the old manager-written boot membership. Each concrete
4413
- * `durable`-class boot channel, and each family such as `review.>`, gets a `durableJoin` whose
4414
- * returned generation seeds the leave mirror
4415
- * + durable-state surface; an already-active membership (a relaunch) is idempotent (no re-catch-up).
4416
- * If the daemon is down/absent at first connect (or reports a transient `durable:false`), the channel
4417
- * is handed to {@link reconcileBootJoin} for capped-backoff retry — so the backstop is RESTORED once
4418
- * the daemon recovers, not left silently live-only. Until a membership exists the channel renders
4419
- * degraded in `cotal_channels` ({@link hasDurableMembership}). */
4420
- async armBootDurableMemberships() {
4421
- for (const channel of this.channels) {
4422
- if (this.plane3Channels.has(channel))
4423
- continue;
4424
- // A family (`review.>`) asks for its row whatever the default class: each channel under it decides
4425
- // its own at fan-out (#5404). Any other pattern has no durable membership.
4426
- if (!isChannelFamily(channel)) {
4427
- if (!isConcreteChannel(channel))
4428
- continue;
4429
- // A missing channel row legitimately resolves through the defaults. A failed/denied registry
4430
- // read does not prove the channel is live-only, so let it fail startup loudly.
4431
- const cls = await this.deliveryClassFresh(channel);
4432
- if (cls !== "durable")
4433
- continue;
4434
- }
4435
- try {
4436
- const r = await this.durableJoinChannel(channel);
4437
- if (r.durable)
4438
- this.plane3Channels.set(channel, r.generation ?? 0);
4439
- else
4440
- void this.reconcileBootJoin(channel); // present but not yet durable — reconcile to recovery
4441
- }
4442
- catch (e) {
4443
- if (!this.isNoResponders(e))
4444
- this.emitRecoverable(e); // no daemon ⇒ retry until it recovers
4445
- void this.reconcileBootJoin(channel);
4446
- }
4447
- }
4369
+ return this.bootMemberships.fetchMemberships(channel);
4448
4370
  }
4449
- /** Retry a boot durable self-join with capped backoff until a membership EXISTS (success → seed
4450
- * `plane3Channels`) or the channel is left / the endpoint stops. Mirrors {@link closeRefusedMembership}:
4451
- * a one-shot first-connect attempt that swallowed a daemon outage would leave the boot channel live-only
4452
- * forever after the daemon recovers (and the lease-based health could then read "active" with no owner
4453
- * membership). This loop is the reconcile that closes that gap. Idempotent — a channel already pending
4454
- * is not double-driven; survives reconnect (it re-issues `durableJoinChannel` on the current connection). */
4455
- async reconcileBootJoin(channel) {
4456
- if (this.pendingBootJoins.has(channel))
4457
- return; // already reconciling
4458
- this.pendingBootJoins.add(channel);
4459
- for (let attempt = 0;; attempt++) {
4460
- await this.membershipPause(attempt);
4461
- if (this.stopped || !this.channels.includes(channel) || this.plane3Channels.has(channel)) {
4462
- this.pendingBootJoins.delete(channel);
4463
- return; // stopped, left, or another path established it
4464
- }
4465
- try {
4466
- const r = await this.durableJoinChannel(channel);
4467
- if (r.durable) {
4468
- this.plane3Channels.set(channel, r.generation ?? 0);
4469
- this.pendingBootJoins.delete(channel);
4470
- return;
4471
- }
4472
- // present but durable:false (e.g. catch-up window evicted) — keep retrying; the channel stays
4473
- // honestly degraded meanwhile, never silently "active".
4474
- }
4475
- catch (e) {
4476
- if (attempt === 0 && !this.isNoResponders(e))
4477
- this.emitRecoverable(new Error(`channel "${channel}": boot durable self-join not yet established - retrying until the delivery daemon is reachable (${e.message})`));
4478
- }
4479
- }
4371
+ /** Forwards to the boot-membership component's {@link EndpointBootMemberships.armBootDurableMemberships}. */
4372
+ async armBootDurableMemberships() {
4373
+ return this.bootMemberships.armBootDurableMemberships();
4480
4374
  }
4481
4375
  /** True if this session holds an established Plane-3 durable membership for `channel` (in `plane3Channels`).
4482
4376
  * Drives the membership-aware delivery-health surface: a joined durable channel that is NOT yet a member
4483
4377
  * (boot self-join pending / daemon down) must render degraded, never "active" off a live lease alone. */
4484
4378
  hasDurableMembership(channel) {
4485
- return this.plane3Channels.has(channel);
4379
+ return this.bootMemberships.hasDurableMembership(channel);
4486
4380
  }
4487
4381
  /** Lazily obtain a JetStream manager — so a non-consuming endpoint (e.g. the supervisor,
4488
4382
  * consume:false) can still pre-create others' durables. */