@cotal-ai/core 0.57.0 → 0.59.0

package/dist/kv-scan.js

@@ -103,7 +103,20 @@ export class IncompleteKvScan extends Error {
  * 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) {
+export async function liveKvEntries(kv, filterOrOptions, options) {
+    let filter;
+    // The three-argument form may deliberately omit the filter: (kv, undefined, options).
+    let opts = options;
+    if (typeof filterOrOptions === "string" || Array.isArray(filterOrOptions)) {
+        filter = filterOrOptions;
+        opts = options;
+    }
+    else if (filterOrOptions && typeof filterOrOptions === "object") {
+        opts = filterOrOptions;
+    }
+    if (opts?.signal?.aborted) {
+        throw opts.signal.reason ?? new Error("scan aborted");
+    }
     // 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
@@ -134,38 +147,101 @@ export async function liveKvEntries(kv, filter) {
     let sawTerminal = false;
     let bucketName = bucket.bucket;
     let expected = 0;
+    let activeConsumerName;
+    let initialName;
     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;
+        const initialInfo = await oc.info(true);
+        initialName = initialInfo.name;
+        activeConsumerName = initialInfo.name;
+        expected = initialInfo.num_pending;
+        if (opts?.signal?.aborted) {
+            throw opts.signal.reason ?? new Error("scan aborted");
+        }
+        // Keep the empty path inside this try/finally too. Returning here would commit [] before
+        // cleanup finishes, even if a caller aborts while the consumer delete is pending.
+        if (expected !== 0) {
+            // 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();
+            const statusIter = typeof iter.status === "function" ? iter.status() : undefined;
+            if (statusIter) {
+                (async () => {
+                    try {
+                        for await (const s of statusIter) {
+                            if (s.type === "ordered_consumer_recreated" && "name" in s && typeof s.name === "string") {
+                                activeConsumerName = s.name;
+                            }
+                        }
+                    }
+                    catch {
+                        /* status iterator closed */
+                    }
+                })();
+            }
+            const onAbort = () => {
+                iter.stop(opts?.signal?.reason ?? new Error("scan aborted"));
+            };
+            opts?.signal?.addEventListener("abort", onAbort, { once: true });
+            try {
+                for await (const m of iter) {
+                    if (opts?.signal?.aborted)
+                        break;
+                    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 {
+                opts?.signal?.removeEventListener("abort", onAbort);
+                if (typeof iter.close === "function") {
+                    await iter.close().catch(() => { });
+                }
+                else {
+                    iter.stop();
                 }
             }
-        }
-        finally {
-            iter.stop();
         }
     }
     finally {
-        await oc.delete().catch(() => { });
+        // Delete ONLY this scan's own consumer in finally. If rotation occurred, delete the rotated consumer too.
+        // TTL (inactive_threshold) remains the crash/deletion-failure backstop.
+        const targetName = oc.name ?? activeConsumerName;
+        if (targetName && initialName && targetName !== initialName) {
+            for (let i = 0; i < 20; i++) {
+                let deleted = false;
+                try {
+                    deleted = await bucket.jsm.consumers.delete(bucket.stream, targetName);
+                }
+                catch {
+                    // in-flight creation or already deleted
+                }
+                if (deleted)
+                    break;
+                await new Promise((r) => setTimeout(r, 20));
+            }
+        }
+        else {
+            await oc.delete().catch(() => { });
+        }
+    }
+    if (opts?.signal?.aborted) {
+        throw opts.signal.reason ?? new Error("scan aborted");
     }
+    // No original scan error was caught or replaced; only a successful empty result waits for
+    // cleanup and this final abort check before it can be returned.
+    if (expected === 0)
+        return [];
     // 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.
@@ -242,9 +318,9 @@ export async function walkKvEntries(kv, filter) {
 /** {@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) {
+export async function liveKvValues(kv, decode, filterOrOptions, options) {
     const out = [];
-    for (const e of await liveKvEntries(kv, filter)) {
+    for (const e of await liveKvEntries(kv, filterOrOptions, options)) {
         const v = decode(e);
         if (v !== undefined)
             out.push(v);

package/dist/kv-scan.js.map

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

package/dist/launch-artifacts.d.ts

@@ -0,0 +1,42 @@
+import type { LaunchSpec } from "./connector.js";
+/**
+ * Thrown by a runtime's `spawn` for a failure before it handed the spec's command to anything that
+ * could start it (an unsafe name, a backend that is not reachable, a launch script it could not
+ * write). It is the one spawn failure that proves no child will read the spec's artifacts, so the
+ * launcher removes them on it. Throw it only from code that runs before that handoff.
+ */
+export declare class SpawnRefused extends Error {
+    constructor(message: string);
+}
+/**
+ * Write `body` to `<fresh private dir>/<file>` and return the file path. The directory is appended to
+ * `artifacts` as soon as it exists, so a write that fails afterwards still leaves it owned; on a
+ * failure every artifact recorded so far is removed before the error propagates, because the launch
+ * that would have owned them is not going to happen.
+ *
+ * `mkdtemp` rather than a predictable name: a pre-created or symlinked path in the world-writable
+ * tmpdir cannot be raced, and a fresh file guarantees the private mode applies at create. The name
+ * also carries 128 random bits, which makes it this launch's identity: a stale list of directories
+ * already removed (a custodian killed between removing them and updating its record) cannot name a
+ * later launch's directory, because no later launch draws the same name.
+ */
+export declare function writeLaunchArtifact(artifacts: string[], prefix: string, file: string, body: string): string;
+/**
+ * Remove a launch's artifact directories. Call it only once the child is gone or never started.
+ * Refuses, before removing anything, a path that is not a `cotal-` directory directly under the OS
+ * temp dir: a spec carrying anything else is a connector bug, and recursive removal of whatever it
+ * named is the one mistake this must never make. Otherwise it tries every directory and then throws
+ * naming each one it could not remove, so the caller can keep them owned and try again.
+ */
+export declare function discardLaunchArtifacts(artifacts: readonly string[] | undefined): void;
+/**
+ * Wrap a spec so its child owns its own artifacts. `/bin/sh` starts a watcher and then `exec`s the
+ * spec's command, so the agent keeps the shell's pid, its argv after the wrapper, its signals and its
+ * exit status. The watcher removes this launch's directories, and no other, once that pid is gone,
+ * whether or not the launcher is still alive. Use it wherever the launcher is the only other owner
+ * (every runtime but one with durable custody, and the foreground `cotal spawn`). The launcher still
+ * removes them on its own proof of exit; both removals are idempotent. A spec with no artifacts, and
+ * any spec on Windows, which has no POSIX shell, comes back unchanged.
+ */
+export declare function reclaimWithChild(spec: LaunchSpec): LaunchSpec;
+//# sourceMappingURL=launch-artifacts.d.ts.map

package/dist/launch-artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch-artifacts.d.ts","sourceRoot":"","sources":["../src/launch-artifacts.ts"],"names":[],"mappings":"AAmCA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAOjD;;;;;GAKG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAa3G;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,CAYrF;AAoCD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAS7D"}

package/dist/launch-artifacts.js

@@ -0,0 +1,155 @@
+/**
+ * Launch artifacts: the private temporary directories a connector writes for ONE launch's child to
+ * read, such as a persona carrier or an MCP config file. They keep text off the process argv, which
+ * every same-host observer can read.
+ *
+ * WHO OWNS THEM. The connector creates them in `buildLaunch` and lists them on
+ * `LaunchSpec.artifacts`; it cannot remove them itself, because the child reads them after
+ * `buildLaunch` returns (Claude re-reads its MCP config on `/mcp reconnect`). The launcher that
+ * spawns the spec owns them from then on: it removes them once it has proved the child gone. Nothing
+ * earlier is safe, since the child may read them at any point in its life. A spawn that throws is not
+ * that proof, since a backend can fail after its child has started, and neither is losing the
+ * connection to whatever watches the child. A failure before the runtime has handed the spec's
+ * command to anything that could start it is: a runtime says so by throwing {@link SpawnRefused},
+ * and the launcher removes the files on that error only. A removal that fails leaves them owned, and
+ * the owner tries again.
+ *
+ * WHAT IS LEFT. On a custodial runtime the seat's custodian, the child's parent, removes them when it
+ * sees the child exit, whether or not the launcher is still alive. Its custody record keeps any it
+ * could not remove, and the reap that proves the seat gone removes those and the ones a custodian
+ * killed first left, against the temp dir the record names, and keeps the record until it has. Every
+ * other launcher starts the child through {@link reclaimWithChild}, so a watcher beside the child
+ * removes them once the child is gone, even when the launcher was killed.
+ * What stays until the OS temp reaper removes it: the files of a spawn that threw anything but
+ * {@link SpawnRefused} before its child started, those of a watcher that was itself SIGKILLed while
+ * its launcher was dead, and on Windows, which has no POSIX shell to run the watcher, those of a
+ * killed launcher.
+ *
+ * WHAT OWNER-PRIVATE MEANS. Each file is 0600 inside a 0700 directory. That is OS-user isolation:
+ * any process running as the same user can read the file while it exists, as it can the agent file
+ * it came from.
+ */
+import { randomBytes } from "node:crypto";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { hardenPrivate, writeSecretFile } from "./secret-fs.js";
+/** Every artifact directory name starts with this, so {@link discardLaunchArtifacts} can refuse a
+ *  path this module did not create. */
+const DIR_PREFIX = "cotal-";
+/**
+ * Thrown by a runtime's `spawn` for a failure before it handed the spec's command to anything that
+ * could start it (an unsafe name, a backend that is not reachable, a launch script it could not
+ * write). It is the one spawn failure that proves no child will read the spec's artifacts, so the
+ * launcher removes them on it. Throw it only from code that runs before that handoff.
+ */
+export class SpawnRefused extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SpawnRefused";
+    }
+}
+/**
+ * Write `body` to `<fresh private dir>/<file>` and return the file path. The directory is appended to
+ * `artifacts` as soon as it exists, so a write that fails afterwards still leaves it owned; on a
+ * failure every artifact recorded so far is removed before the error propagates, because the launch
+ * that would have owned them is not going to happen.
+ *
+ * `mkdtemp` rather than a predictable name: a pre-created or symlinked path in the world-writable
+ * tmpdir cannot be raced, and a fresh file guarantees the private mode applies at create. The name
+ * also carries 128 random bits, which makes it this launch's identity: a stale list of directories
+ * already removed (a custodian killed between removing them and updating its record) cannot name a
+ * later launch's directory, because no later launch draws the same name.
+ */
+export function writeLaunchArtifact(artifacts, prefix, file, body) {
+    if (!prefix.startsWith(DIR_PREFIX))
+        throw new Error(`launch artifact prefix must start with "${DIR_PREFIX}": ${prefix}`);
+    try {
+        const dir = mkdtempSync(join(tmpdir(), `${prefix}${randomBytes(16).toString("hex")}-`));
+        artifacts.push(dir);
+        hardenPrivate(dir, "dir"); // win32: mkdtemp's 0700 is a no-op, so harden the ACL before the file lands
+        const path = join(dir, file);
+        writeSecretFile(path, body);
+        return path;
+    }
+    catch (e) {
+        discardLaunchArtifacts(artifacts);
+        throw e;
+    }
+}
+/**
+ * Remove a launch's artifact directories. Call it only once the child is gone or never started.
+ * Refuses, before removing anything, a path that is not a `cotal-` directory directly under the OS
+ * temp dir: a spec carrying anything else is a connector bug, and recursive removal of whatever it
+ * named is the one mistake this must never make. Otherwise it tries every directory and then throws
+ * naming each one it could not remove, so the caller can keep them owned and try again.
+ */
+export function discardLaunchArtifacts(artifacts) {
+    if (!artifacts?.length)
+        return;
+    assertArtifactDirs(artifacts);
+    const failed = [];
+    for (const dir of artifacts) {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch (e) {
+            failed.push(`${dir} (${e.message})`);
+        }
+    }
+    if (failed.length)
+        throw new Error(`could not remove launch artifact ${failed.join(", ")}`);
+}
+/** Refuse any path that is not a `cotal-` directory directly under the OS temp dir. */
+function assertArtifactDirs(artifacts) {
+    const root = resolve(tmpdir());
+    for (const dir of artifacts) {
+        if (dirname(resolve(dir)) !== root || !basename(dir).startsWith(DIR_PREFIX))
+            throw new Error(`refusing to remove launch artifact ${dir}: not a ${DIR_PREFIX}* directory directly under ${root}`);
+    }
+}
+/** Run by `/bin/sh -c` as `<script> cotal-launch <n> <n dirs> <command> <args...>`. The watcher
+ *  ignores the hangup, interrupt and terminate signals a closing terminal or a stop sends to the
+ *  child's process group, holds no terminal, and polls the shell's pid, which `exec` hands to the
+ *  command. A reused pid only delays the removal. It is the only owner left once the launcher is
+ *  dead, so it tries every directory it could not remove again every five seconds until all are
+ *  gone. */
+const RECLAIM_SCRIPT = `p=$$ n=$1
+shift
+(
+  trap '' HUP INT QUIT TERM
+  while kill -0 "$p" 2>/dev/null; do sleep 1; done
+  while :; do
+    i=0 left=0
+    for d; do
+      [ "$i" -lt "$n" ] || break
+      rm -rf -- "$d" || left=1
+      i=$((i + 1))
+    done
+    [ "$left" = 0 ] && break
+    sleep 5
+  done
+) </dev/null >/dev/null 2>&1 &
+shift "$n"
+exec "$@"`;
+/**
+ * Wrap a spec so its child owns its own artifacts. `/bin/sh` starts a watcher and then `exec`s the
+ * spec's command, so the agent keeps the shell's pid, its argv after the wrapper, its signals and its
+ * exit status. The watcher removes this launch's directories, and no other, once that pid is gone,
+ * whether or not the launcher is still alive. Use it wherever the launcher is the only other owner
+ * (every runtime but one with durable custody, and the foreground `cotal spawn`). The launcher still
+ * removes them on its own proof of exit; both removals are idempotent. A spec with no artifacts, and
+ * any spec on Windows, which has no POSIX shell, comes back unchanged.
+ */
+export function reclaimWithChild(spec) {
+    const dirs = spec.artifacts;
+    if (!dirs?.length || process.platform === "win32")
+        return spec;
+    assertArtifactDirs(dirs);
+    return {
+        ...spec,
+        command: "/bin/sh",
+        args: ["-c", RECLAIM_SCRIPT, "cotal-launch", String(dirs.length), ...dirs, spec.command, ...spec.args],
+    };
+}
+//# sourceMappingURL=launch-artifacts.js.map

package/dist/launch-artifacts.js.map

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

package/dist/lease.d.ts

@@ -41,6 +41,11 @@ export interface DeliveryLeaseInfo {
      *  Optional because rows written by daemons from before this field exist in live buckets; a row
      *  without one cannot be proven ours (some other process wrote it), which is the safe reading. */
     incarnation?: string;
+    /** Epoch ms when this incarnation acquired the shard. Unlike `since`, which every ready flip and
+     *  renewal re-stamps, it is written once at acquisition and carried on every later write. Optional
+     *  because rows written before this field exist; their acquisition time is unknown. */
+    acquiredAt?: number;
+    /** Epoch ms of this row's latest write: the acquisition, a ready flip, or a renewal. */
     since: number;
     ready: boolean;
 }

package/dist/lease.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAO,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAK3C;;;;;;;;mGAQmG;AACnG,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;qEAIqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;sGAUkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;4GAK4G;AAC5G,MAAM,WAAW,gBAAgB;IAC/B;;;;;8BAK0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf;0GACsG;IACtG,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;6GAC6G;AAC7G,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,OAAO,yBAAyB,EAAE,cAAc,EACpD,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,EAAE,CAAC,CAEb;AAED;;;;;;;;;;;;gGAYgG;AAChG,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,OAAO,CAAC,CAkCnB"}
+{"version":3,"file":"lease.d.ts","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAO,KAAK,EAAE,EAAE,MAAM,aAAa,CAAC;AAK3C;;;;;;;;mGAQmG;AACnG,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED;;;;qEAIqE;AACrE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;;;;sGAUkG;IAClG,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;2FAEuF;IACvF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;CAChB;AAED;;;;;4GAK4G;AAC5G,MAAM,WAAW,gBAAgB;IAC/B;;;;;8BAK0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf;0GACsG;IACtG,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAED;6GAC6G;AAC7G,wBAAsB,oBAAoB,CACxC,EAAE,EAAE,OAAO,yBAAyB,EAAE,cAAc,EACpD,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,EAAE,CAAC,CAEb;AAED;;;;;;;;;;;;gGAYgG;AAChG,wBAAsB,oBAAoB,CAAC,IAAI,EAAE;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,OAAO,CAAC,CAkCnB"}

package/dist/lease.js.map

@@ -1 +1 @@
-{"version":3,"file":"lease.js","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,GAAG,EAAW,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;mGAQmG;AACnG,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,OAAO,YAAY,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;AACzD,CAAC;AAgDD;6GAC6G;AAC7G,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAAoD,EACpD,KAAa;IAEb,OAAO,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;gGAYgG;AAChG,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAO1C;IACC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;IACvD,IAAI,EAAmD,CAAC;IACxD,IAAI,CAAC;QACH,EAAE,GAAG,MAAM,OAAO,CAAC;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,aAAa,EAAE,kBAAkB,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvE,WAAW,EAAE,UAAU,IAAI,CAAC,EAAE,EAAE;YAChC,oBAAoB,EAAE,CAAC;SACxB,CAAC,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,oBAAoB,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YACpC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,KAAK,KAAK,IAAI,CAAC,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;gBAC1D,yFAAyF;gBACzF,uFAAuF;gBACvF,+CAA+C;gBAC/C,IAAI,CAAC;oBACH,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,EAAqB,CAAC;oBACzC,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC;wBAAE,OAAO,IAAI,CAAC;gBACrG,CAAC;gBAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC;YAC3B,CAAC;YACD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,YAAY;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"lease.js","sourceRoot":"","sources":["../src/lease.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,GAAG,EAAW,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AACtE,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;;;;mGAQmG;AACnG,MAAM,UAAU,sBAAsB,CAAC,KAAa;IAClD,OAAO,YAAY,CAAC,SAAS,EAAE,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;AACzD,CAAC;AAqDD;6GAC6G;AAC7G,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,EAAoD,EACpD,KAAa;IAEb,OAAO,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;;;gGAYgG;AAChG,MAAM,CAAC,KAAK,UAAU,oBAAoB,CAAC,IAO1C;IACC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,CAAC;IACvD,IAAI,EAAmD,CAAC;IACxD,IAAI,CAAC;QACH,EAAE,GAAG,MAAM,OAAO,CAAC;YACjB,OAAO,EAAE,IAAI,CAAC,OAAO;YACrB,aAAa,EAAE,kBAAkB,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACvE,WAAW,EAAE,UAAU,IAAI,CAAC,EAAE,EAAE;YAChC,oBAAoB,EAAE,CAAC;SACxB,CAAC,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,oBAAoB,CAAC,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACtD,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,MAAM,CAAC,GAAG,MAAM,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;YACpC,IAAI,CAAC,IAAI,CAAC,CAAC,SAAS,KAAK,KAAK,IAAI,CAAC,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;gBAC1D,yFAAyF;gBACzF,uFAAuF;gBACvF,+CAA+C;gBAC/C,IAAI,CAAC;oBACH,MAAM,IAAI,GAAG,CAAC,CAAC,IAAI,EAAqB,CAAC;oBACzC,IAAI,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC;wBAAE,OAAO,IAAI,CAAC;gBACrG,CAAC;gBAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC;YAC3B,CAAC;YACD,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,0DAA0D;IAC5D,CAAC;YAAS,CAAC;QACT,IAAI,CAAC;YACH,MAAM,EAAE,EAAE,KAAK,EAAE,CAAC;QACpB,CAAC;QAAC,MAAM,CAAC;YACP,YAAY;QACd,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/liveness.d.ts

@@ -0,0 +1,180 @@
+/**
+ * THE PEER-READABLE LIVENESS SURFACE (#1577) — "which plane is broken?", askable by a credentialed
+ * peer that does not own the plane it is asking about.
+ *
+ * THE DEFECT THIS MODULE EXISTS TO REMOVE. The subjects that answer "is the manager alive" are
+ * owner-only, so a peer holding valid credentials cannot ask. When its join or its send fails, the
+ * peer cannot tell a credential problem from a dead manager, an unbound delivery daemon, or a broker
+ * that is perfectly fine — so EVERY failure presents as a credential failure, because that is the
+ * only hypothesis the peer is able to form. The reporter's week produced six independent surfaces
+ * that each reported success over a failure, including a `pgrep` that matched its own command line
+ * and therefore fails in BOTH directions. An instrument that cannot fail is not an instrument.
+ *
+ * WHAT IS BORROWED RATHER THAN INVENTED. The vocabulary is #1594's responder classifier
+ * ({@link ResponderState}), moved here from the CLI so there is ONE of it: bound, unbound, stale,
+ * unknown, with `unknown` first class. That module's whole point was that a lease which cannot be
+ * read is NOT health, and this surface inherits that property rather than re-deciding it. The CLI's
+ * `delivery-responder.ts` now re-exports these, so both surfaces cannot drift apart.
+ *
+ * WHAT IS NEW: the ASK, and only the ask. A peer cannot read either lease — the manager bucket is
+ * denied to agents by omission and must stay that way (see the note on {@link LivenessAnswer}) — so
+ * the peer does not read state at all. It sends a presence request and grades THE OUTCOME OF ASKING.
+ *
+ * WHY THE OUTCOME OF ASKING IS A SOUND LIVENESS SIGNAL, AND WHERE IT STOPS BEING ONE. NATS reports
+ * "nobody is subscribed to this subject" (NoResponders, status 503) as a distinct outcome from "I
+ * waited and nothing came back" (a timeout). That distinction is the entire instrument:
+ *
+ *   • a reply            → the responder is bound AND answered, so it grades its own readiness;
+ *   • NoResponders (503) → the broker itself says no responder is bound: `unbound`, positively;
+ *   • a timeout          → SOMETHING is subscribed but did not answer, or the broker never
+ *                          answered us at all. That is `unknown`, never `unbound` and never health.
+ *   • a permission error → `unknown`. The peer has learnt about its own credential, not about the
+ *                          plane, and converting that into a verdict about the plane is the
+ *                          reported bug wearing new clothes.
+ *
+ * This is why a timeout must not be folded into `unbound` even though both "look like" nothing came
+ * back. A 503 is the BROKER's own report about subscription state and is evidence. A timeout is the
+ * absence of evidence, and an absence of evidence is exactly what this issue says must stop being
+ * rendered as a verdict.
+ *
+ * SHAPE. This is the Synadia micro protocol's `$SRV.INFO` in intent — a read-only, presence-only,
+ * request/reply probe on a well-known subject — but it is deliberately NOT the literal `$SRV` wire
+ * protocol. `$SRV` appears nowhere in this repository, and its subjects sit OUTSIDE the
+ * `cotal.<space>.>` tree: a surface there would escape per-space account isolation, every existing
+ * grant builder, and the subject audit that sweeps a space by prefix. So the probe rides a Cotal
+ * rail inside the space ({@link livenessSubject}), carries the micro protocol's semantics, and stays
+ * inside the boundaries the rest of the system already enforces.
+ */
+import type { DeliveryLeaseInfo } from "./lease.js";
+/** What is known about a RESPONDER, as opposed to a process. Moved verbatim from the CLI's #1594
+ *  classifier so the liveness surface and `cotal status` cannot drift apart.
+ *
+ *  `unknown` IS A FIRST-CLASS ANSWER AND MUST NOT BE FOLDED INTO `bound`. A read can fail for
+ *  reasons that say nothing about the daemon (no target resolved, broker unreachable, a denied read
+ *  on a mesh whose creds predate the read grant). Reporting any of those as health is the original
+ *  defect in a new place.
+ *
+ *  `stale` IS ALSO NOT `bound`. A ready record whose holder is not the daemon this workspace
+ *  launched is a dead or foreign daemon's leftover, and the mesh it describes cannot spawn, retire
+ *  or join. It is kept distinct from `unbound` because the operator's next move differs. */
+export type ResponderState = "bound" | "unbound" | "stale" | "unknown";
+/** The two planes a peer may ask about. Deliberately a CLOSED set rather than a free string: the
+ *  whole complaint is that liveness is unaskable, and the fix must not become a general-purpose
+ *  probe rail that grows a third meaning later. `manager` is the lifecycle/control plane (its
+ *  control moved to the v0.4 `service` endpoint at 1d); `delivery` is the server-side delivery
+ *  daemon that serves `ctl.delivery`. */
+export declare const LIVENESS_PLANES: readonly ["manager", "delivery"];
+export type LivenessPlane = (typeof LIVENESS_PLANES)[number];
+/** Is `plane` one this surface answers for? A closed-set guard, so an unrecognised plane is refused
+ *  rather than answered with a default — a probe that answers every input is the "sweep that gives
+ *  the same answer at every input" failure, and it would report health for planes that do not
+ *  exist. */
+export declare function isLivenessPlane(plane: string): plane is LivenessPlane;
+/** THE ANSWER, AND EVERYTHING IT IS NOT.
+ *
+ *  Two fields: whether a responder is bound for the named plane, and an OPAQUE token for which
+ *  responder said so. No holder, no pid, no workspace root, no instance id, no runtime, no roster,
+ *  no membership — none of which a peer needs in order to learn WHICH PLANE IS BROKEN, and all of
+ *  which the issue explicitly says the surface does not need to expose.
+ *
+ *  THIS IS THE SECURITY BOUNDARY AND IT IS WHY THE PEER DOES NOT SIMPLY READ THE LEASE. The manager
+ *  lease row ({@link import("./lease.js").ManagerLeaseInfo}) carries `holder`, `instanceId`,
+ *  `runtime`, `root` and `pid` — the operator's workspace path and process id. An agent holds no
+ *  grant on that bucket at all, by deliberate omission (`provision.ts`: "an agent must never read,
+ *  write, or delete it"), and granting one to make liveness askable would hand every peer the
+ *  operator's filesystem layout and a pid to signal. So the row NEVER leaves the responder: the
+ *  responder reduces it to one enum and answers with that. Presence is the whole ask, and
+ *  presence is the whole answer.
+ *
+ *  `since`/`uptime` are deliberately absent too, though `$SRV.INFO` would carry them: a timestamp
+ *  on the manager's lease dates the operator's last restart, which is state. */
+export interface LivenessAnswer {
+    /** The plane this answer is about, echoed so a reply cannot be mistaken for another plane's. */
+    plane: LivenessPlane;
+    /** Whether a responder is bound for that plane, in #1594's vocabulary. */
+    responder: ResponderState;
+    /** WHICH RESPONDER ANSWERED, as an opaque per-bind token, or `undefined` when no responder
+     *  answered at all (a 503, a timeout, a refusal, an unreadable reply).
+     *
+     *  IT ANSWERS "WAS THIS THE SAME ONE" AND NOTHING ELSE, and that narrowness is the design. Manager
+     *  instances coexist per instance id, each answers only about ITSELF, and the queue group hands a
+     *  probe to an arbitrary member — so two probes that disagree are, without this field,
+     *  indistinguishable from one responder that changed state. Comparing tokens tells those apart.
+     *
+     *  IT IS NOT AN IDENTITY. The value is minted at bind time from nothing ({@link
+     *  import("./endpoint.js").CotalEndpoint.serveLiveness}) and is not the endpoint's principal, the
+     *  lease row's `instanceId`, a pid, a host or a path. A peer can tell two responders apart and can
+     *  learn nothing else about either, which is the same boundary the rest of this type holds: a
+     *  field that named the real instance would have re-opened the lease row the responder exists to
+     *  keep off the wire.
+     *
+     *  ONE PROBE STILL SAMPLES ONE RESPONDER. This field does not aggregate the plane, and a single
+     *  answer cannot report a split. It makes a split OBSERVABLE across repeated probes, where before
+     *  it was not observable at all. */
+    instance?: string;
+}
+/** Classify a lease record into responder state — #1594's pure classifier, moved here so the CLI
+ *  status surfaces and this liveness surface grade by the SAME rule.
+ *
+ *  `undefined` means the lease key is absent, which on a mesh that HAS a daemon recorded is an
+ *  unbound responder rather than a missing opinion: the daemon creates its lease before it binds, so
+ *  no lease at all means nothing has even claimed the slot.
+ *
+ *  `expectedHolder` is not optional information when it is knowable. A daemon that is SIGKILLed
+ *  leaves its `ready:true` record in the bucket for the rest of the bucket TTL, so `ready` alone
+ *  answers "did SOME daemon bind recently enough that its record has not expired", which is not the
+ *  question being asked. When the caller can name the daemon it means, a foreign or dead holder's
+ *  record classifies as `stale` rather than as health. When it genuinely cannot know, pass
+ *  `undefined` and the holder is not checked. */
+export declare function responderFromLease(lease: DeliveryLeaseInfo | undefined, expectedHolder?: string): ResponderState;
+/** Read the axis through a caller-supplied lease reader, mapping a FAILED read to `unknown` rather
+ *  than to either health state. The reader is injected so offline surfaces (which must not open a
+ *  connection) and connected ones share one classification without sharing a transport. */
+export declare function responderStateFromReader(readLease: () => Promise<DeliveryLeaseInfo | undefined>, expectedHolder?: string): Promise<ResponderState>;
+/** How a peer's probe ENDED, as distinct from what it means. Kept separate from
+ *  {@link ResponderState} on purpose: the caller reports what happened on the wire, and this module
+ *  owns the single rule that turns that into a verdict, so no call site can invent its own mapping.
+ *
+ *   • `replied`      — a well-formed answer came back; the responder graded itself.
+ *   • `noResponders` — the BROKER reported 503/no-responders: positively nothing is subscribed.
+ *   • `timeout`      — we waited and nothing came back. Something may be subscribed and wedged.
+ *   • `refused`      — the broker refused us (permissions), or the transport failed. This says
+ *                      something about OUR credential or OUR link, and nothing about the plane.
+ *   • `malformed`    — a reply arrived that this surface cannot read. */
+export type ProbeOutcome = "replied" | "noResponders" | "timeout" | "refused" | "malformed";
+/** THE ONE RULE that turns a probe outcome into a responder verdict, and the heart of #1577.
+ *
+ *  ONLY `noResponders` may become `unbound`, because only it is the broker's own positive report
+ *  that no responder is subscribed. `timeout`, `refused` and `malformed` ALL become `unknown`: each
+ *  is a failure to find out, and this issue exists because failures to find out were being rendered
+ *  as findings. A peer that cannot reach the broker learns that it cannot reach the broker.
+ *
+ *  `replied` defers to the responder's OWN verdict, which it derived from its lease through
+ *  {@link responderFromLease} — so a daemon that has claimed its slot but not bound its loops
+ *  answers `unbound` about itself rather than being counted as alive merely because it answered. A
+ *  reply carrying no readable verdict is `malformed`, hence `unknown`; it is not silently promoted
+ *  to `bound` on the strength of having replied at all. That promotion is precisely the `pgrep`
+ *  error — treating evidence that a process exists as evidence that it works. */
+export declare function responderFromProbe(outcome: ProbeOutcome, answered?: ResponderState): ResponderState;
+/** Read a wire reply into an answer, or `undefined` if it is not one. Strict on purpose: an
+ *  unrecognised `responder` value, a plane that does not match the one asked about, or a body of the
+ *  wrong shape all return `undefined`, which the caller grades as `malformed` and therefore
+ *  `unknown`. A lenient parse here would let a garbled or foreign reply be read as health, and this
+ *  is the exact seam where "it said something" becomes "it said it was fine".
+ *
+ *  `instance` IS STRICT TOO, FOR A DIFFERENT REASON THAN THE OTHER FIELDS. It is not the verdict, so
+ *  a bad one cannot say "healthy" — but a caller compares tokens to tell two responders apart, and
+ *  a value it cannot compare (a number, an object, an empty string) would silently read as "the same
+ *  responder as the other answer that also had no usable token". That is a split rendered as
+ *  agreement. A reply naming a responder in a form this surface cannot read is therefore `malformed`
+ *  rather than an answer with the field dropped. A reply with NO `instance` at all is still
+ *  readable: it is an answer from a responder that predates the field. */
+export declare function parseLivenessAnswer(body: unknown, expectPlane: LivenessPlane): LivenessAnswer | undefined;
+/** The consequence of an unbound responder, in the operator's terms rather than the daemon's — per
+ *  plane, because they break different things and the reporter's cost was diagnosis time, not
+ *  ignorance that something was wrong. Purely presentational: no state, no identity. */
+export declare function livenessConsequence(plane: LivenessPlane): string;
+/** Render one axis for a human, naming UNKNOWN as unchecked rather than as either health state.
+ *  The `unknown` arm is the line this whole issue is about: it must never read as reassurance. */
+export declare function livenessLine(answer: LivenessAnswer): string;
+//# sourceMappingURL=liveness.d.ts.map

package/dist/liveness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"liveness.d.ts","sourceRoot":"","sources":["../src/liveness.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD;;;;;;;;;;4FAU4F;AAC5F,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAEvE;;;;yCAIyC;AACzC,eAAO,MAAM,eAAe,kCAAkD,CAAC;AAC/E,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE7D;;;aAGa;AACb,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,aAAa,CAErE;AAED;;;;;;;;;;;;;;;;;gFAiBgF;AAChF,MAAM,WAAW,cAAc;IAC7B,gGAAgG;IAChG,KAAK,EAAE,aAAa,CAAC;IACrB,0EAA0E;IAC1E,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;;;;;;;;;;;;;wCAiBoC;IACpC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;iDAYiD;AACjD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,iBAAiB,GAAG,SAAS,EACpC,cAAc,CAAC,EAAE,MAAM,GACtB,cAAc,CAKhB;AAED;;2FAE2F;AAC3F,wBAAsB,wBAAwB,CAC5C,SAAS,EAAE,MAAM,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,EACvD,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,cAAc,CAAC,CAMzB;AAED;;;;;;;;;yEASyE;AACzE,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,CAAC;AAE5F;;;;;;;;;;;;iFAYiF;AACjF,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,EAAE,cAAc,GAAG,cAAc,CAInG;AAED;;;;;;;;;;;;0EAY0E;AAC1E,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,GAAG,cAAc,GAAG,SAAS,CAOzG;AAED;;wFAEwF;AACxF,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAIhE;AAED;kGACkG;AAClG,wBAAgB,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAW3D"}