@cotal-ai/core 0.133.13 → 0.134.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 (51) hide show
  1. package/dist/backup-config.d.ts +48 -5
  2. package/dist/backup-config.d.ts.map +1 -1
  3. package/dist/backup-config.js +72 -10
  4. package/dist/backup-config.js.map +1 -1
  5. package/dist/endpoint-caller.d.ts +4 -1
  6. package/dist/endpoint-caller.d.ts.map +1 -1
  7. package/dist/endpoint-caller.js +3 -1
  8. package/dist/endpoint-caller.js.map +1 -1
  9. package/dist/endpoint-contract-store.d.ts +14 -2
  10. package/dist/endpoint-contract-store.d.ts.map +1 -1
  11. package/dist/endpoint-contract-store.js +16 -3
  12. package/dist/endpoint-contract-store.js.map +1 -1
  13. package/dist/endpoint-coverage.d.ts +55 -0
  14. package/dist/endpoint-coverage.d.ts.map +1 -0
  15. package/dist/endpoint-coverage.js +206 -0
  16. package/dist/endpoint-coverage.js.map +1 -0
  17. package/dist/endpoint.d.ts +67 -20
  18. package/dist/endpoint.d.ts.map +1 -1
  19. package/dist/endpoint.js +111 -75
  20. package/dist/endpoint.js.map +1 -1
  21. package/dist/index.d.ts +3 -0
  22. package/dist/index.d.ts.map +1 -1
  23. package/dist/index.js +3 -0
  24. package/dist/index.js.map +1 -1
  25. package/dist/issued-authority.d.ts +48 -0
  26. package/dist/issued-authority.d.ts.map +1 -1
  27. package/dist/issued-authority.js +78 -0
  28. package/dist/issued-authority.js.map +1 -1
  29. package/dist/provision.d.ts +27 -6
  30. package/dist/provision.d.ts.map +1 -1
  31. package/dist/provision.js +91 -10
  32. package/dist/provision.js.map +1 -1
  33. package/dist/registry-client.d.ts +39 -0
  34. package/dist/registry-client.d.ts.map +1 -0
  35. package/dist/registry-client.js +58 -0
  36. package/dist/registry-client.js.map +1 -0
  37. package/dist/registry-contract.d.ts +79 -0
  38. package/dist/registry-contract.d.ts.map +1 -0
  39. package/dist/registry-contract.js +105 -0
  40. package/dist/registry-contract.js.map +1 -0
  41. package/dist/space-schema-diff.d.ts +2 -2
  42. package/dist/space-schema-diff.d.ts.map +1 -1
  43. package/dist/space-schema-diff.js +29 -2
  44. package/dist/space-schema-diff.js.map +1 -1
  45. package/dist/streams.d.ts +46 -5
  46. package/dist/streams.d.ts.map +1 -1
  47. package/dist/streams.js +120 -8
  48. package/dist/streams.js.map +1 -1
  49. package/dist/types.d.ts +3 -2
  50. package/dist/types.d.ts.map +1 -1
  51. package/package.json +1 -1
package/dist/provision.js CHANGED
@@ -29,8 +29,9 @@ import { assertServeGrantMintable, finalizeServeIssuance } from "./endpoint-serv
29
29
  import { parseServiceConnectionBinding } from "./service-gate.js";
30
30
  import { SERVICE_ACCESS_TTL_SECONDS } from "./service-authority-limits.js";
31
31
  import { effectsBindGrants, poolOwnerBindGrants, goalWriterGrants, sessionLedgerGrants, epAuthBucket, sessionsBucket, epcStreamName, endpointPlaneStreamNames, eptReqStreamName, eptStreamName, hardenedAuthorityStreamNames, timerWriterDurable, timerWriterGrants } from "./endpoint-binding.js";
32
- import { epsSubject, epCallerReplyFilter, assertGeneration, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE } from "./endpoint-subjects.js";
33
- import { acceptedReadGrant, acceptedBucket, importNativeSubjectPermissions, issuedBucket, issuedHorizon, issuedStoreStreamNames, writeAcceptedRow } from "./issued-authority.js";
32
+ import { epsSubject, epCallerReplyFilter, assertGeneration, isIssuedCaller, AUTH_ENDPOINT, EP_CMD_RETIRE_LIFECYCLE } from "./endpoint-subjects.js";
33
+ import { acceptedReadGrant, acceptedBucket, importNativeSubjectPermissions, issuedBucket, issuedHorizon, issuedStoreStreamNames, prepareListing, writeAcceptedRow } from "./issued-authority.js";
34
+ import { REGISTRY_ENDPOINTS_GRANT } from "./registry-contract.js";
34
35
  import { admissionBucket, admissionKey, revocationKey } from "./run-admission.js";
35
36
  import { runSubmissionKey } from "./run-submission.js";
36
37
  import { runDriverGrants, runMediatorGrants, runOperatorGrants } from "./run-driver-grants.js";
@@ -112,6 +113,7 @@ export const CREDENTIAL_LIFETIMES = {
112
113
  "run-driver": { class: "standing-renewable", defaultTtlSeconds: STANDING_RENEWABLE_TTL_SEC, renewalOwner: "manager", note: "one workflow run's driver, per takeover attempt (SPEC 14.6): the hosting manager mints it when it takes the run over and re-mints for the SAME nkey on renewal; a new takeover mints a new one" },
113
114
  "run-mediator": { class: "standing-renewable", defaultTtlSeconds: STANDING_RENEWABLE_TTL_SEC, renewalOwner: "manager", note: "trusted workflow host operations, bound to one run and attempt; kept on the hosting process's connection" },
114
115
  "run-operator": { class: "one-shot", defaultTtlSeconds: 60, note: "one served run-status / run-ps / run-answer call (SPEC 14.3): the hosting manager mints it per call on its own connection, never the serve rails; 60s bounds a copied cred to a minute" },
116
+ "registry-reader": { class: "standing-renewable", defaultTtlSeconds: 60 * 60, renewalOwner: "registry host", note: "the registry's reads (SPEC 13.20), no write of any shape; the evidence-store read is stream-scoped, so it can read every recorded ceiling in the space (a NAMED RESIDUAL), and one hour bounds a copied credential; the process hosting the registry re-mints it" },
115
117
  issuer: { class: "mixed", defaultTtlSeconds: FIVE_MINUTES, renewalOwner: "auth-service", note: "renewed as the auth plane's held session for connect-time issuance (re-minted before exp, closed with the plane); one-shot for every other issuance window and for a lifecycle terminal's issuance retirement (SPEC 13.15)" },
116
118
  "run-admitter": { class: "one-shot", defaultTtlSeconds: 60, note: "one hosted run's admission record create, or its revocation marker (SPEC 14.8); 60s bounds a copied cred to a minute" },
117
119
  "transfer-writer": { class: "one-shot", defaultTtlSeconds: FIVE_MINUTES, note: "one carried resume per CLI call: one object's chunk and meta subjects in one instance's transfer bucket" },
@@ -448,10 +450,11 @@ export async function mintCreds(auth, identity, profile, opts = {}) {
448
450
  // Serve rows are INTERNAL to mintCreds behind the §13.1 fence: the exported permissionsFor
449
451
  // refuses "endpoint-serve" (so a direct caller can never obtain unfenced serve rows), and only
450
452
  // this fenced path calls the row builder.
453
+ const validDates = userValidDates(profile, opts);
454
+ const listing = await prepareStaticListing(auth.space, profile, pr, opts, validDates.exp);
451
455
  const perms = profile === "endpoint-serve"
452
456
  ? endpointServePermissions(auth.space, pr, opts)
453
- : permissionsFor(profile, auth.space, pr, opts);
454
- const validDates = userValidDates(profile, opts);
457
+ : listing?.permissions ?? permissionsFor(profile, auth.space, pr, opts);
455
458
  const userJwt = await encodeUser(profile, fromPublic(identity.id), fromPublic(auth.account.pub),
456
459
  // Stamp the principal `tags` so this connection's identity is CONNZ-recoverable by the membership
457
460
  // feed — the SAME tags the auth callout stamps (user mode), via core's single-source builder. The
@@ -475,6 +478,7 @@ export async function mintCreds(auth, identity, profile, opts = {}) {
475
478
  `mint bound (${channelCount} allowSubscribe+allowPublish channel(s)) - the composed credential ` +
476
479
  `would exceed the broker's CONNECT line and the connect would hang silently (issue #375)`);
477
480
  }
481
+ await listing?.commit();
478
482
  await releaseIssuance(auth.space, profile, pr, opts, perms, validDates.exp, credentialIdOf(creds));
479
483
  // §13.1 mint fence for the serve credential: the credential is BUILT, but released only when its
480
484
  // NORMATIVE ledger row (holderPrincipal/lifecycleUid/sourceChain/state/exp + the currency
@@ -508,6 +512,23 @@ export async function mintCreds(auth, identity, profile, opts = {}) {
508
512
  }
509
513
  return creds;
510
514
  }
515
+ /** A static `agent` mint's listing generation (SPEC 13.15, "Listing issuance"), decided before the
516
+ * credential is signed. Its horizon is the credential's own expiry, so a mint with none gets no
517
+ * listing generation. Bound to no gate: the evidence's expiry is its liveness. */
518
+ async function prepareStaticListing(space, profile, pr, opts, exp) {
519
+ const seam = opts.listingSeam;
520
+ if (!seam)
521
+ return undefined;
522
+ if (profile !== "agent")
523
+ throw new Error(`mintCreds: a listing seam rides the static agent mint only, not "${profile}"`);
524
+ if (opts.issued || opts.listing)
525
+ throw new Error("mintCreds: a listing seam decides the listing generation itself; opts.issued and opts.listing are refused beside it");
526
+ if (exp === undefined)
527
+ return undefined;
528
+ if (!pr.lifecycleUid)
529
+ throw new Error("mintCreds: a listing generation is lifecycle-keyed; mint with opts.lifecycleUid");
530
+ return prepareListing(seam, { space, owner: pr.owner, actor: pr.actor, uid: pr.lifecycleUid, connId: pr.connId, horizon: exp, sources: [], expiresAt: exp }, (binding) => permissionsFor(profile, space, pr, { ...opts, ...(binding ? { listing: binding } : {}) }));
531
+ }
511
532
  /** The SPEC 13.15 issuance fence: an issuing mint persists the ceiling it is handing out BEFORE
512
533
  * the material is returned, and the material expires by its generation's horizon. The evidence is the minted permission set itself (deny rules
513
534
  * included), imported from the same object the JWT was encoded from, so the record and the
@@ -651,6 +672,10 @@ export function permissionsFor(profile, space, pr, opts) {
651
672
  // the generation to, so `issued` on it is a misconfiguration refused here, never dropped.
652
673
  if (opts.issued && !ISSUABLE_PROFILES.has(profile))
653
674
  throw new Error(`permissionsFor: opts.issued binds caller rails and "${profile}" holds none; only ${[...ISSUABLE_PROFILES].join(", ")} mint issued authority (SPEC 13.15)`);
675
+ if (opts.listing && profile !== "agent" && profile !== "manager-caller")
676
+ throw new Error(`permissionsFor: a listing generation rides the agent and manager-caller views only, not "${profile}" (SPEC 13.15)`);
677
+ if (opts.listing && opts.issued)
678
+ throw new Error("permissionsFor: an issued credential lists under its own generation; a listing generation beside it is refused (SPEC 13.15)");
654
679
  if (isEnvironmentManagerProfile(profile))
655
680
  return environmentManagerPermissions(profile, space, pr, opts.environmentManager);
656
681
  if (opts.environmentManager)
@@ -726,6 +751,8 @@ export function permissionsFor(profile, space, pr, opts) {
726
751
  }
727
752
  if (profile === "issuer")
728
753
  return issuerPermissions(space, pr);
754
+ if (profile === "registry-reader")
755
+ return registryReaderPermissions(space, pr);
729
756
  if (profile === "run-admitter") {
730
757
  if (!opts.runAdmitter)
731
758
  throw new Error("permissionsFor: run-admitter requires opts.runAdmitter ({endpoint, runId} of the ONE run it admits)");
@@ -1064,6 +1091,15 @@ export function permissionsFor(profile, space, pr, opts) {
1064
1091
  if (opts.issued)
1065
1092
  pubAllow.push(acceptedReadGrant(space, opts.issued.acceptedToken));
1066
1093
  const epSub = [...baseline.sub];
1094
+ // The registry's listing question rides the issued rail (SPEC 13.20): under the credential's own
1095
+ // generation when its issuance carries it, else under a listing generation.
1096
+ if (opts.issued?.listing)
1097
+ pubAllow.push(...epRequestGrantRows(space, REGISTRY_ENDPOINTS_GRANT, epCaller));
1098
+ if (opts.listing) {
1099
+ const rows = listingGrantRows(space, epCaller, opts.listing);
1100
+ pubAllow.push(...rows.pub);
1101
+ epSub.push(...rows.sub);
1102
+ }
1067
1103
  // BOTH HALVES OF THE ROLLUP, NOT JUST `pub`. `epCallerGrantRows` returns `{pub, sub}` and its
1068
1104
  // `sub` is the per-goal progress row its own docblock promises: "a goal-bearing capability
1069
1105
  // (spawn/launch) adds ONE per-endpoint epGoalProgressGrantRow - the caller may follow its OWN
@@ -1178,15 +1214,18 @@ function managerCallerPermissions(space, pr, opts) {
1178
1214
  ];
1179
1215
  const caller = issuedCallerFor({ owner: pr.owner, actor: pr.actor, uid: assertLifecycleToken(pr.lifecycleUid) }, opts);
1180
1216
  const rows = epCallerGrantRows(space, instanceOnlyManagerCapabilities(ordinary, instanceId), caller);
1217
+ const listing = opts.listing ? listingGrantRows(space, caller, opts.listing) : { pub: [], sub: [] };
1181
1218
  return {
1182
1219
  pub: {
1183
1220
  allow: [
1184
1221
  `$JS.API.DIRECT.GET.${epcStreamName(space)}.${spacePrefix(space)}.epc.>`,
1185
1222
  ...(opts.issued ? [acceptedReadGrant(space, opts.issued.acceptedToken)] : []),
1186
1223
  ...rows.pub,
1224
+ ...(opts.issued?.listing ? epRequestGrantRows(space, REGISTRY_ENDPOINTS_GRANT, caller) : []),
1225
+ ...listing.pub,
1187
1226
  ],
1188
1227
  },
1189
- sub: { allow: [`_INBOX_${pr.connId}.>`, ...rows.sub] },
1228
+ sub: { allow: [`_INBOX_${pr.connId}.>`, ...rows.sub, ...listing.sub] },
1190
1229
  };
1191
1230
  }
1192
1231
  /** The long-lived SUPERVISOR permission set — the always-on manager daemon
@@ -1647,6 +1686,20 @@ function issuedCallerFor(triple, opts) {
1647
1686
  assertGeneration(opts.issued.acceptedToken, "acceptedToken");
1648
1687
  return { ...triple, generation: assertGeneration(opts.issued.generation) };
1649
1688
  }
1689
+ /** The rows a listing generation adds to a legacy-rail credential (SPEC 13.15, "Listing
1690
+ * issuance"): the registry's `endpoints` request publish and its reply subscribe on `ep.v1`, and
1691
+ * the per-key read of the generation's accepted row. Exactly these: one caller value emits one
1692
+ * rail, so these are the only `ep.v1` rows such a credential holds. */
1693
+ export function listingGrantRows(space, caller, listing) {
1694
+ if (isIssuedCaller(caller))
1695
+ throw new Error("listingGrantRows: an issued caller lists under its own generation");
1696
+ assertGeneration(listing.acceptedToken, "acceptedToken");
1697
+ const issued = { owner: caller.owner, actor: caller.actor, uid: caller.uid, generation: assertGeneration(listing.generation) };
1698
+ return {
1699
+ pub: [...epRequestGrantRows(space, REGISTRY_ENDPOINTS_GRANT, issued), acceptedReadGrant(space, listing.acceptedToken)],
1700
+ sub: [epCallerReplyFilter(space, issued)],
1701
+ };
1702
+ }
1650
1703
  /** ENDPOINT-SERVE (v0.4, SPEC §13.9 "Serve grants") — the per-instance serve credential:
1651
1704
  * EXACTLY the instance's registered rails and nothing else. Subscribe: the queue-qualified
1652
1705
  * class rail, the plain scatter rail, and the own-instance rail for the FULL registered
@@ -1805,13 +1858,14 @@ function purgerPermissions(space, pr) {
1805
1858
  * `$JS` is an ENUMERATED allow-list, never `$JS.>`: STREAM.CREATE + INFO for the space streams/buckets,
1806
1859
  * DM/DLV/TASK consumer CREATE/DURABLE.CREATE/INFO — and deliberately NO `MSG.NEXT`/`MSG.GET`/`ACK` on
1807
1860
  * DM/DLV (it creates the bind-only mailbox but never reads it), and NO STREAM.DELETE/PURGE/MSG.DELETE
1808
- * (it provisions, it does not tear down). STREAM.UPDATE is held on EXACTLY nine streams and no others:
1861
+ * (it provisions, it does not tear down). STREAM.UPDATE is held on EXACTLY ten streams and no others:
1809
1862
  * the three TTL'd KV buckets (presence + the two leases, #286: an existing bucket's `max_age` cannot be
1810
1863
  * fixed by `kvm.create`, so reconciling a pre-TTL deployment requires updating it), the four hardened
1811
1864
  * authority stores (records, issued, accepted, admission), each updated once at creation, and the
1812
1865
  * membership KV and artifact Object Store, whose legacy `max_bytes` values setup reconciles to -1 (the
1813
1866
  * reservation a positive cap holds against the broker's `max_file_store` is what stopped a tenth space
1814
- * from being provisioned; `Objm.create` cannot fix an existing bucket's cap either).
1867
+ * from being provisioned; `Objm.create` cannot fix an existing bucket's cap either), and the chat
1868
+ * stream, whose history limit `cotal up` and `cotal history limit` write (`setChatHistoryLimit`).
1815
1869
  * Stated positively on purpose: this docblock previously read "NO …/UPDATE", which was already untrue of
1816
1870
  * the records stream and became untrue of the buckets, and a comment that denies a credential's real
1817
1871
  * power is worse than none — it is the document a reader trusts instead of checking. KV value-writes are
@@ -1857,8 +1911,9 @@ function provisionerPermissions(space, pr) {
1857
1911
  // never updates an existing bucket's config, so a bucket created by a cotal that predates the `max_age`
1858
1912
  // TTL keeps NO expiry forever — dead presence records (and stale leases) never age out. `setupSpaceStreams`
1859
1913
  // reconciles their `max_age` via STREAM.UPDATE at every `cotal up`, which needs this grant. Scoped to these
1860
- // three streams only — the durable streams (chat/dm/task/inbox/dlv and channel/members/acl registries)
1861
- // are never updated — and still NO DELETE/PURGE. The supervisor profile keeps its full UPDATE
1914
+ // three streams here. The durable dm/task/inbox/dlv streams and the channel/members/acl registries
1915
+ // are never updated (the chat stream's history limit is the one exception, below), and there is
1916
+ // still NO DELETE/PURGE. The supervisor profile keeps its full UPDATE
1862
1917
  // denial; this widening is provisioning-only.
1863
1918
  // Derived from the SAME inventory that creates and reconciles them, not a third hand-kept copy.
1864
1919
  // Review found this list was the last independent one: a fourth TTL'd bucket added to `ttlBuckets`
@@ -1874,7 +1929,11 @@ function provisionerPermissions(space, pr) {
1874
1929
  // Still CREATE/INFO/UPDATE only:
1875
1930
  // no publish, no CONSUMER.CREATE (a push consumer's caller-chosen `deliver_subject` would export
1876
1931
  // every artifact in the space), no DELETE/PURGE.
1877
- const streamReconcile = [...ttlStreams, `KV_${membershipBucket(space)}`, OBJ]
1932
+ // ...plus the chat stream, the one durable message stream this credential updates: `cotal up`
1933
+ // moves a chat stream still on the legacy history limit to the default, and `cotal history limit`
1934
+ // sets it (SPEC §8). Both write only `max_age` and `max_msgs_per_subject` (`setChatHistoryLimit`).
1935
+ // DM, TASK, INBOX and DLV stay create-only.
1936
+ const streamReconcile = [...ttlStreams, `KV_${membershipBucket(space)}`, OBJ, CHAT]
1878
1937
  .map((s) => `$JS.API.STREAM.UPDATE.${s}`);
1879
1938
  // #404: one EXACT reserved key on each TTL bucket is the post-update enforcement canary. The
1880
1939
  // provisioner still cannot write presence identities or lease keys; it can only write this fixed
@@ -1973,6 +2032,28 @@ function issuerPermissions(space, pr) {
1973
2032
  sub: { allow: [`_INBOX_${pr.connId}.>`] },
1974
2033
  };
1975
2034
  }
2035
+ /** The REGISTRY READER permission set (SPEC 13.20). The evidence store's `STREAM.MSG.GET` is
2036
+ * stream-scoped because the key rides the request body: NAMED RESIDUAL, the holder can read every
2037
+ * recorded ceiling in the space, so this credential is never a peer's. The records reads are the
2038
+ * key list and the per-key `svc` spec/status Direct Get, no stream-wide read; contract artifacts
2039
+ * ride the agent's subject-scoped fetch row. No write of any shape. */
2040
+ function registryReaderPermissions(space, pr) {
2041
+ const ISSUED = `KV_${issuedBucket(space)}`;
2042
+ const REC = recordsBucket(space);
2043
+ return {
2044
+ pub: {
2045
+ allow: [
2046
+ `$JS.API.STREAM.INFO.${ISSUED}`,
2047
+ `$JS.API.STREAM.MSG.GET.${ISSUED}`,
2048
+ `$JS.API.STREAM.INFO.KV_${REC}`,
2049
+ `$JS.API.DIRECT.GET.KV_${REC}.$KV.${REC}.svc.*.*.spec`,
2050
+ `$JS.API.DIRECT.GET.KV_${REC}.$KV.${REC}.svc.*.*.status`,
2051
+ `$JS.API.DIRECT.GET.${epcStreamName(space)}.${spacePrefix(space)}.epc.>`,
2052
+ ],
2053
+ },
2054
+ sub: { allow: [`_INBOX_${pr.connId}.>`] },
2055
+ };
2056
+ }
1976
2057
  /** The RUN ADMITTER permission set (SPEC 14.8): exactly ONE run's admission record and
1977
2058
  * revocation marker on the admission store (both create-only), plus the leader-served read the
1978
2059
  * create-before-read and the marker's own re-read ride. No other run's keys, no other store. */