@cotal-ai/core 0.14.11 → 0.16.0

package/dist/kv-scan.d.ts

@@ -0,0 +1,97 @@
+import type { KV, KvEntry } from "@nats-io/kv";
+/**
+ * The ONE sanctioned way to read every live entry of a KV bucket.
+ *
+ * ## Why this exists
+ *
+ * Four call sites independently open-coded a whole-bucket read. `readMembership` had the worst
+ * shape: enumerate keys, then fetch each key's value. `kv.keys()` is one ordered-consumer pass, but
+ * every yielded key then costs a separate `STREAM.MSG.GET` round trip, sequentially. That is O(N)
+ * round trips to read N records. It is invisible against a loopback broker and catastrophic anywhere
+ * else: 89 membership keys measured 30-34 seconds against a mesh at 534ms RTT, where a single pass is
+ * ~3 round trips regardless of N.
+ *
+ * The other three were already close to a single pass; what they gained is the completeness
+ * guarantee below, which none of them had.
+ *
+ * Fixing the call sites one at a time guarantees a fifth, so no call site may open-code this. That is
+ * currently a CONVENTION, not an enforced rule: nothing in the build rejects a new `keys()`-then-
+ * `get()` loop.
+ *
+ * ## Why it owns the pass instead of wrapping `kv.history()`
+ *
+ * `kv.history()` would deliver values in one pass, but its public iterator does not expose the
+ * consumer's `num_pending`. Without it, a caller cannot distinguish an EMPTY bucket from a pass that
+ * died before its first message — both arrive as zero entries and a clean end. For membership and
+ * ACL reads that ambiguity produces a confident empty set, which is worse than a short one because
+ * nothing about it looks wrong.
+ *
+ * ## What the completeness check guarantees
+ *
+ * In `@nats-io/kv`, `iter.closed().then(...)` ends an iterator CLEANLY on any mid-stream
+ * termination: a dropped connection, a deleted consumer, a server error. Nothing throws. On exactly
+ * the high-latency, jittery links this helper exists to serve, a silently truncated read would
+ * otherwise be the default failure mode.
+ *
+ * Because the pass is bound here, both halves are decidable:
+ *   - EMPTY is proven, not inferred. `num_pending` is read at bind, before any delivery, so an empty
+ *     result means the bucket (or the filtered subset) really had nothing — never that the pass died
+ *     before its first message. That distinction is why this does not wrap `history()`, which hides
+ *     the count: read through that, a dropped link during a filtered ACL scan reported a provisioned
+ *     principal as having no row, and a durable join was refused as "not provisioned".
+ *   - COMPLETE means a delivered message reported nothing behind it. An idle heartbeat is NOT
+ *     accepted as completion, unlike `history()`, whose "a heartbeat means we got all the keys"
+ *     shortcut is how a stalled pass returns a short list wearing a clean end.
+ *
+ * Anything else raises {@link IncompleteKvScan}. Treat it as retryable: it says this read did not
+ * finish, never that data was lost.
+ *
+ * ## Why tombstones are carried through the collapse
+ *
+ * Filtering DEL/PURGE markers DURING iteration resurrects deleted keys: if a key's PUT is delivered
+ * and its later DEL is skipped, the stale PUT survives as the "latest". So the collapse keeps
+ * markers, picks the greatest revision per key, and only then drops keys whose final state is a
+ * marker.
+ *
+ * This is required for CONCURRENCY, not merely for misconfigured buckets. `DeliverPolicy.All` chases
+ * a moving tail, so a key rewritten while the pass drains legitimately appears at two revisions even
+ * on a `history: 1` bucket.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * It never asserts `status().history === 1`. Greatest-revision-with-tombstones is correct for every
+ * `history >= 1`, so a drifted bucket is read correctly rather than refused; throwing on a read
+ * because PROVISIONING drifted would turn a bucket-config problem into a mesh-wide outage. Bucket
+ * reconcile is a privileged setup concern and needs `STREAM.UPDATE`, which read credentials do not
+ * have and must not be given.
+ *
+ * ## Grant
+ *
+ * Same broker authority as the `keys()` + `get()` pair it replaces: one ordered/push consumer over
+ * `$KV.<bucket>.>`, differing only in `deliver_policy`. Values are not new authority — the existing
+ * `keys()` consumer grant could already request bodies. No ACL widening anywhere.
+ */
+/** Thrown when a pass ends without reaching its terminal message. The caller decides whether to
+ *  retry or surface it; what it may NOT do is treat the partial set as the answer. */
+export declare class IncompleteKvScan extends Error {
+    readonly bucket: string;
+    readonly received: number;
+    readonly expected: number;
+    constructor(bucket: string, received: number, expected: number);
+}
+/**
+ * Every currently-live entry of `kv`, in ONE pass, with values.
+ *
+ * `filter` narrows the scan to matching keys (NATS subject wildcards), for callers that scan a
+ * key prefix rather than the whole bucket. Returns entries whose final operation is a real value;
+ * deleted and purged keys are absent.
+ *
+ * Throws {@link IncompleteKvScan} if the pass is cut short. Returns `[]` for a bucket that is
+ * genuinely empty (proven at bind time, not inferred from silence).
+ */
+export declare function liveKvEntries(kv: KV, filter?: string | string[]): Promise<KvEntry[]>;
+/** {@link liveKvEntries}, decoded. `decode` returning `undefined` drops the entry — for callers that
+ *  skip garbled records rather than failing the whole read (the prevailing convention in the
+ *  registries: one unparseable row must not blind the surface to every other row). */
+export declare function liveKvValues<T>(kv: KV, decode: (e: KvEntry) => T | undefined, filter?: string | string[]): Promise<T[]>;
+//# sourceMappingURL=kv-scan.d.ts.map

package/dist/kv-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-scan.d.ts","sourceRoot":"","sources":["../src/kv-scan.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,EAAE,EAAE,OAAO,EAAgB,MAAM,aAAa,CAAC;AAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AAEH;sFACsF;AACtF,qBAAa,gBAAiB,SAAQ,KAAK;IAEvC,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM;gBAFhB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM;CAO5B;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAoE1F;AAED;;sFAEsF;AACtF,wBAAsB,YAAY,CAAC,CAAC,EAClC,EAAE,EAAE,EAAE,EACN,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,GAAG,SAAS,EACrC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GACzB,OAAO,CAAC,CAAC,EAAE,CAAC,CAOd"}

package/dist/kv-scan.js

@@ -0,0 +1,184 @@
+import { Bucket, KvWatchInclude } from "@nats-io/kv/internal";
+/**
+ * The ONE sanctioned way to read every live entry of a KV bucket.
+ *
+ * ## Why this exists
+ *
+ * Four call sites independently open-coded a whole-bucket read. `readMembership` had the worst
+ * shape: enumerate keys, then fetch each key's value. `kv.keys()` is one ordered-consumer pass, but
+ * every yielded key then costs a separate `STREAM.MSG.GET` round trip, sequentially. That is O(N)
+ * round trips to read N records. It is invisible against a loopback broker and catastrophic anywhere
+ * else: 89 membership keys measured 30-34 seconds against a mesh at 534ms RTT, where a single pass is
+ * ~3 round trips regardless of N.
+ *
+ * The other three were already close to a single pass; what they gained is the completeness
+ * guarantee below, which none of them had.
+ *
+ * Fixing the call sites one at a time guarantees a fifth, so no call site may open-code this. That is
+ * currently a CONVENTION, not an enforced rule: nothing in the build rejects a new `keys()`-then-
+ * `get()` loop.
+ *
+ * ## Why it owns the pass instead of wrapping `kv.history()`
+ *
+ * `kv.history()` would deliver values in one pass, but its public iterator does not expose the
+ * consumer's `num_pending`. Without it, a caller cannot distinguish an EMPTY bucket from a pass that
+ * died before its first message — both arrive as zero entries and a clean end. For membership and
+ * ACL reads that ambiguity produces a confident empty set, which is worse than a short one because
+ * nothing about it looks wrong.
+ *
+ * ## What the completeness check guarantees
+ *
+ * In `@nats-io/kv`, `iter.closed().then(...)` ends an iterator CLEANLY on any mid-stream
+ * termination: a dropped connection, a deleted consumer, a server error. Nothing throws. On exactly
+ * the high-latency, jittery links this helper exists to serve, a silently truncated read would
+ * otherwise be the default failure mode.
+ *
+ * Because the pass is bound here, both halves are decidable:
+ *   - EMPTY is proven, not inferred. `num_pending` is read at bind, before any delivery, so an empty
+ *     result means the bucket (or the filtered subset) really had nothing — never that the pass died
+ *     before its first message. That distinction is why this does not wrap `history()`, which hides
+ *     the count: read through that, a dropped link during a filtered ACL scan reported a provisioned
+ *     principal as having no row, and a durable join was refused as "not provisioned".
+ *   - COMPLETE means a delivered message reported nothing behind it. An idle heartbeat is NOT
+ *     accepted as completion, unlike `history()`, whose "a heartbeat means we got all the keys"
+ *     shortcut is how a stalled pass returns a short list wearing a clean end.
+ *
+ * Anything else raises {@link IncompleteKvScan}. Treat it as retryable: it says this read did not
+ * finish, never that data was lost.
+ *
+ * ## Why tombstones are carried through the collapse
+ *
+ * Filtering DEL/PURGE markers DURING iteration resurrects deleted keys: if a key's PUT is delivered
+ * and its later DEL is skipped, the stale PUT survives as the "latest". So the collapse keeps
+ * markers, picks the greatest revision per key, and only then drops keys whose final state is a
+ * marker.
+ *
+ * This is required for CONCURRENCY, not merely for misconfigured buckets. `DeliverPolicy.All` chases
+ * a moving tail, so a key rewritten while the pass drains legitimately appears at two revisions even
+ * on a `history: 1` bucket.
+ *
+ * ## What it deliberately does NOT do
+ *
+ * It never asserts `status().history === 1`. Greatest-revision-with-tombstones is correct for every
+ * `history >= 1`, so a drifted bucket is read correctly rather than refused; throwing on a read
+ * because PROVISIONING drifted would turn a bucket-config problem into a mesh-wide outage. Bucket
+ * reconcile is a privileged setup concern and needs `STREAM.UPDATE`, which read credentials do not
+ * have and must not be given.
+ *
+ * ## Grant
+ *
+ * Same broker authority as the `keys()` + `get()` pair it replaces: one ordered/push consumer over
+ * `$KV.<bucket>.>`, differing only in `deliver_policy`. Values are not new authority — the existing
+ * `keys()` consumer grant could already request bodies. No ACL widening anywhere.
+ */
+/** Thrown when a pass ends without reaching its terminal message. The caller decides whether to
+ *  retry or surface it; what it may NOT do is treat the partial set as the answer. */
+export class IncompleteKvScan extends Error {
+    bucket;
+    received;
+    expected;
+    constructor(bucket, received, expected) {
+        super(`reading ${bucket} ended after ${received} of ~${expected} entries without reaching the end of the bucket - the connection or consumer died mid-pass. Refusing to return a partial view (a short or empty result here is indistinguishable from a real answer). Retry; if it persists, the link to the broker is dropping.`);
+        this.bucket = bucket;
+        this.received = received;
+        this.expected = expected;
+        this.name = "IncompleteKvScan";
+    }
+}
+/**
+ * Every currently-live entry of `kv`, in ONE pass, with values.
+ *
+ * `filter` narrows the scan to matching keys (NATS subject wildcards), for callers that scan a
+ * key prefix rather than the whole bucket. Returns entries whose final operation is a real value;
+ * deleted and purged keys are absent.
+ *
+ * Throws {@link IncompleteKvScan} if the pass is cut short. Returns `[]` for a bucket that is
+ * genuinely empty (proven at bind time, not inferred from silence).
+ */
+export async function liveKvEntries(kv, filter) {
+    // OWN THE PASS. This deliberately does NOT call `kv.history()`. That helper hides the consumer's
+    // bind-time `num_pending`, and without it an empty result is ambiguous: a genuinely empty bucket
+    // and a pass that died before its first message look identical. For a FILTERED scan that ambiguity
+    // is not academic — `enumerateLiveAclRows` reads this way, so a dropped link mid-scan would report
+    // a provisioned principal as having no ACL row at all, and `deliveryJoin` would refuse the join as
+    // "not provisioned" rather than as "could not read". A wrong reason on an authorization path.
+    //
+    // The pinned client exposes what is needed through its `@nats-io/kv/internal` entry point: the
+    // `Bucket` implementation carries the JetStream client, the stream name, the consumer-config
+    // builder the public watchers use, and the entry decoder. Binding through those keeps this on
+    // EXACTLY the ordered push consumer over `$KV.<bucket>.>` that `keys()` and `history()` already
+    // use — same subject, same verbs, no new broker authority.
+    if (!(kv instanceof Bucket))
+        throw new Error(`liveKvEntries needs the @nats-io/kv Bucket implementation to bind its own consumer (got ${kv?.constructor?.name ?? typeof kv}). Refusing to fall back to history(), whose hidden bind-time pending count is exactly the ambiguity this exists to remove.`);
+    const bucket = kv;
+    const cc = bucket._buildCC(filter ?? ">", KvWatchInclude.AllHistory, { headers_only: false });
+    const oc = await bucket.js.consumers.getPushConsumer(bucket.stream, cc);
+    // THE BIND-TIME PROOF: `num_pending` is how many messages this consumer will deliver, read before
+    // a single one arrives. Zero means the bucket (or the filtered subset) really is empty; it is
+    // never inferred from silence.
+    // ONE try/finally around EVERY exit. The consumer must be reclaimed on the empty path too: an
+    // empty read is not rare, it is the normal answer for a filtered ACL miss, and `readAclForAlias`
+    // performs TWO of those per unknown principal. `_buildCC` sets a 5s idle heartbeat, so an
+    // undeleted consumer lingers until its inactivity threshold; at alias-check churn that piles up on
+    // the broker for no reason.
+    const latest = new Map();
+    let received = 0;
+    let sawTerminal = false;
+    let bucketName = bucket.bucket;
+    let expected = 0;
+    try {
+        // THE BIND-TIME PROOF, continued: zero here is the only thing that yields an empty result.
+        expected = (await oc.info(true)).num_pending;
+        if (expected === 0)
+            return [];
+        // Greatest revision per key, markers INCLUDED — see the header. Collapsing after the fact is
+        // what makes concurrent rewrites and drifted `history` settings both correct.
+        const iter = await oc.consume();
+        try {
+            for await (const m of iter) {
+                const e = bucket.jmToWatchEntry(m, false);
+                received++;
+                bucketName = e.bucket;
+                const prior = latest.get(e.key);
+                if (prior === undefined || e.revision >= prior.revision)
+                    latest.set(e.key, e);
+                // The ONLY completion signal accepted: a delivered message that says nothing is left behind
+                // it. Unlike `history()`, an idle heartbeat is NOT treated as "we got everything" — that
+                // shortcut is precisely how a stalled pass returns a short list wearing a clean end.
+                if (m.info.pending === 0) {
+                    sawTerminal = true;
+                    break;
+                }
+            }
+        }
+        finally {
+            iter.stop();
+        }
+    }
+    finally {
+        await oc.delete().catch(() => { });
+    }
+    // Fell out without the terminal message: the connection dropped, the consumer was removed, or the
+    // stream stalled past the heartbeat. Whatever the cause, this is a PARTIAL view and saying so is
+    // the whole point. Filtered and unfiltered obey the same rule, including zero-received.
+    if (!sawTerminal)
+        throw new IncompleteKvScan(bucketName, received, expected);
+    const out = [];
+    for (const e of latest.values())
+        if (e.operation !== "DEL" && e.operation !== "PURGE")
+            out.push(e);
+    return out;
+}
+/** {@link liveKvEntries}, decoded. `decode` returning `undefined` drops the entry — for callers that
+ *  skip garbled records rather than failing the whole read (the prevailing convention in the
+ *  registries: one unparseable row must not blind the surface to every other row). */
+export async function liveKvValues(kv, decode, filter) {
+    const out = [];
+    for (const e of await liveKvEntries(kv, filter)) {
+        const v = decode(e);
+        if (v !== undefined)
+            out.push(v);
+    }
+    return out;
+}
+//# sourceMappingURL=kv-scan.js.map

package/dist/kv-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kv-scan.js","sourceRoot":"","sources":["../src/kv-scan.ts"],"names":[],"mappings":"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"}

package/dist/members.d.ts

@@ -66,10 +66,14 @@ export declare function deleteMember(kv: KV, channel: string, owner: string, lif
 /**
  * Scan the registry, yielding every live (non-deleted) record matching the filter. `channel` →
  * that channel's members (fan-out's per-channel list); `owner` → that owner's memberships. With no
- * filter, every record. MVP does a full `keys()` scan + per-key get + in-code filter — correct and
- * fine at local scale; a derived channel→members index is the deferred web-scale optimization
- * (the registry stays the single canonical source). Tombstones (with `leaveCursor`) ARE yielded —
- * a caller that wants only currently-open memberships filters on `leaveCursor === undefined`.
+ * filter, every record. Tombstones (with `leaveCursor`) ARE yielded — a caller that wants only
+ * currently-open memberships filters on `leaveCursor === undefined`.
+ *
+ * ONE pass. This was a `keys()` scan plus a sequential per-key `get()`, which cost one round trip
+ * per surviving key; a filtered caller paid for the keys that matched, an unfiltered one paid for
+ * all of them. The filtering is still done in code (the registry stays the single canonical source;
+ * a derived channel→members index remains a separate, deferred decision), but the READ is now
+ * independent of record count.
  */
 export declare function listMembers(kv: KV, filter?: {
     channel?: string;

package/dist/members.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"members.d.ts","sourceRoot":"","sources":["../src/members.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAO,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEnD;oFACoF;AACpF,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM/E;AAED;mEACmE;AACnE,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,OAAO,yBAAyB,EAAE,cAAc,EACpD,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B,OAAO,CAAC,EAAE,CAAC,CAGb;AAED;;gGAEgG;AAChG,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAQrE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuB5F;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAoBvC;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAoBvC;AAED;;2FAE2F;AAC3F,wBAAsB,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9G;AAED;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,EAAE,EACN,MAAM,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAc7B;AAED;;;;;;;;;;;;;gEAagE;AAChE,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAI3E"}
+{"version":3,"file":"members.d.ts","sourceRoot":"","sources":["../src/members.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAO,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAGnD;oFACoF;AACpF,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM/E;AAED;mEACmE;AACnE,wBAAsB,mBAAmB,CACvC,EAAE,EAAE,OAAO,yBAAyB,EAAE,cAAc,EACpD,KAAK,EAAE,MAAM,EACb,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,OAAO,CAAA;CAAO,GAC9B,OAAO,CAAC,EAAE,CAAC,CAGb;AAED;;gGAEgG;AAChG,wBAAsB,UAAU,CAC9B,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAQrE;AAED;;;;;;;GAOG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAuB5F;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,MAAM,EACtB,kBAAkB,CAAC,EAAE,MAAM,GAC1B,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAoBvC;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,EAAE,EACN,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,kBAAkB,EAAE,MAAM,EAC1B,kBAAkB,EAAE,MAAM,GACzB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC,CAoBvC;AAED;;2FAE2F;AAC3F,wBAAsB,YAAY,CAAC,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE9G;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAC/B,EAAE,EAAE,EAAE,EACN,MAAM,GAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,GAChD,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAmB7B;AAED;;;;;;;;;;;;;gEAagE;AAChE,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAI3E"}

package/dist/members.js

@@ -14,6 +14,7 @@
  */
 import { Kvm } from "@nats-io/kv";
 import { membersBucket, memberKey, parseMemberKey } from "./subjects.js";
+import { liveKvEntries } from "./kv-scan.js";
 /** Thrown when a write would regress membership generation — a stale/late control reply. Callers
  *  treat this as "a newer membership change already won", not an error to retry. */
 export class StaleMembershipWrite extends Error {
@@ -148,15 +149,19 @@ export async function deleteMember(kv, channel, owner, lifecycleUid) {
 /**
  * Scan the registry, yielding every live (non-deleted) record matching the filter. `channel` →
  * that channel's members (fan-out's per-channel list); `owner` → that owner's memberships. With no
- * filter, every record. MVP does a full `keys()` scan + per-key get + in-code filter — correct and
- * fine at local scale; a derived channel→members index is the deferred web-scale optimization
- * (the registry stays the single canonical source). Tombstones (with `leaveCursor`) ARE yielded —
- * a caller that wants only currently-open memberships filters on `leaveCursor === undefined`.
+ * filter, every record. Tombstones (with `leaveCursor`) ARE yielded — a caller that wants only
+ * currently-open memberships filters on `leaveCursor === undefined`.
+ *
+ * ONE pass. This was a `keys()` scan plus a sequential per-key `get()`, which cost one round trip
+ * per surviving key; a filtered caller paid for the keys that matched, an unfiltered one paid for
+ * all of them. The filtering is still done in code (the registry stays the single canonical source;
+ * a derived channel→members index remains a separate, deferred decision), but the READ is now
+ * independent of record count.
  */
 export async function listMembers(kv, filter = {}) {
     const out = [];
-    for await (const key of await kv.keys()) {
-        const parsed = parseMemberKey(key);
+    for (const e of await liveKvEntries(kv)) {
+        const parsed = parseMemberKey(e.key);
         if (!parsed)
             continue;
         // `parsed.principal` is the member's owner+actor dot-form (membership is per-agent); the
@@ -166,9 +171,14 @@ export async function listMembers(kv, filter = {}) {
             continue;
         if (filter.owner !== undefined && parsed.principal !== filter.owner)
             continue;
-        const rec = await readMember(kv, parsed.channel, parsed.principal, parsed.lifecycleUid);
-        if (rec)
-            out.push(rec.record);
+        // Same decode + skip-garbled behaviour readMember applies; the DEL/PURGE half is already handled
+        // by the collapse in liveKvEntries.
+        try {
+            out.push(e.json());
+        }
+        catch {
+            /* skip undecodable */
+        }
     }
     return out;
 }

package/dist/members.js.map

@@ -1 +1 @@
-{"version":3,"file":"members.js","sourceRoot":"","sources":["../src/members.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"members.js","sourceRoot":"","sources":["../src/members.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,8 +1,24 @@
 {
   "name": "@cotal-ai/core",
   "description": "The Cotal protocol: endpoint, subjects, message types, the NATS client layer, and the extension contracts.",
-  "version": "0.14.11",
+  "version": "0.16.0",
   "license": "Apache-2.0",
+  "keywords": [
+    "cotal",
+    "agents",
+    "ai-agents",
+    "multi-agent",
+    "agent-communication",
+    "agent-coordination",
+    "agent-orchestration",
+    "swarm",
+    "pubsub",
+    "protocol",
+    "nats",
+    "jetstream",
+    "mcp",
+    "a2a"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/Cotal-AI/Cotal.git",