@eir-labs/coltrane 0.11.0 → 0.12.0

package/dist/src/local_queue.d.ts

@@ -0,0 +1,105 @@
+/** The lease a claimed gig carries — a continuing renewed fact (monotonic `renewed_at`), not a boot
+ *  assertion. */
+export interface LeaseState {
+    holder: string;
+    renewed_at: number;
+    expires_at: number;
+}
+/** A claimed local gig — the sibling of worker.ts ClaimedGig, plus the local lease and, on a
+ *  re-claim, the human seat's role-keyed verdicts. */
+export interface ClaimedLocalGig {
+    gig_id: string;
+    standard_slug: string;
+    standard_version: number | null;
+    mode: string;
+    input: Record<string, unknown>;
+    acting_for: string;
+    venue?: string | null;
+    worker: string;
+    lease: LeaseState;
+    approvals?: Record<string, {
+        verdict: Record<string, unknown>;
+        approved_by?: string;
+    }> | null;
+}
+/** One row's observable state — how a reader tells a live claim from an abandoned one. */
+export interface LocalGigView {
+    gig_id: string;
+    state: "queued" | "claimed" | "awaiting_approval" | "complete" | "failed" | "cancelled";
+    holder?: string;
+    lease?: LeaseState;
+}
+export interface LocalQueueOptions {
+    leaseMs?: number;
+    /** Injected clock for deterministic lease/reap laws. Defaults to Date.now(). */
+    clock?: () => number;
+}
+/** The local queue port — every verb is offline and needs no credential. */
+export interface LocalQueue {
+    enqueue(args: Record<string, unknown>): Promise<{
+        gig_id: string;
+        status: "queued";
+    }>;
+    claim(worker: string): Promise<ClaimedLocalGig | null>;
+    heartbeat(worker: string, gig_id: string): Promise<boolean>;
+    reap(): {
+        requeued: string[];
+        kept: number;
+        errors: string[];
+    };
+    park(worker: string, gig_id: string): Promise<boolean>;
+    approve(gig_id: string, role: string, verdict: Record<string, unknown>, approved_by?: string): Promise<boolean>;
+    cancel(args: Record<string, unknown>): Promise<{
+        gig_id: string;
+        status: "cancelled";
+    }>;
+    complete(worker: string, gig_id: string, output: Record<string, unknown>): Promise<{
+        content_sha: string;
+        duplicated: boolean;
+    }>;
+    list(): LocalGigView[];
+    readonly leaseMs: number;
+}
+/** Which backing owns the queue, decided by which environment is present. */
+export type QueueBackingChoice = {
+    backing: "file";
+    root: string;
+} | {
+    backing: "hosted";
+} | {
+    backing: "none";
+    why: string;
+} | {
+    backing: "conflict";
+    why: string;
+};
+export interface LocalQueueModule {
+    openLocalQueue(root: string, opts?: LocalQueueOptions): LocalQueue;
+    fileQueueGig(root: string): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    fileCancelGig(root: string): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+    selectQueueBacking(env: Record<string, string | undefined>): QueueBackingChoice;
+    LOCAL_QUEUE_DIR_VAR: string;
+    DRAIN_VARS: readonly string[];
+}
+/** The env var whose presence selects the local backing. */
+export declare const LOCAL_QUEUE_DIR_VAR = "COLTRANE_QUEUE_DIR";
+/** The drain's five-variable contract (drain_preflight.ts:55-61), kept SORTED. The local path must
+ *  never read a VALUE of any of these; selectQueueBacking only ever inspects key PRESENCE. */
+export declare const DRAIN_VARS: readonly string[];
+/**
+ * The single backing selector — file when the local dir is present, hosted for the drain env,
+ * conflict when both, none otherwise. It reads the VALUE of exactly one variable, LOCAL_QUEUE_DIR_VAR
+ * (not a drain var), and detects hosted presence by KEY PRESENCE via Object.keys — never by reading a
+ * drain variable's value. That distinction is load-bearing for F8: the test passes an env Proxy whose
+ * `get` trap throws on any drain-var read, so hosted detection must go through `ownKeys` (Object.keys
+ * does not trip the `get` trap), letting a local-present env resolve to `file` without touching one of
+ * the five. Values of the drain vars are never needed — their mere presence is the whole signal.
+ */
+export declare function selectQueueBacking(env: Record<string, string | undefined>): QueueBackingChoice;
+export declare function openLocalQueue(root: string, opts?: LocalQueueOptions): LocalQueue;
+/** The deps.queueGig-shaped enqueue seam — byte-compatible with postgrestQueueGig / rpcQueueGig
+ *  ({gig_id, status:'queued'}), so a caller cannot tell which backing answered (I1). */
+export declare function fileQueueGig(root: string): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;
+/** The deps.cancelGig-shaped seam — sibling of postgrestCancelGig ({gig_id, status:'cancelled'})
+ *  (I18). */
+export declare function fileCancelGig(root: string): (args: Record<string, unknown>) => Promise<Record<string, unknown>>;

package/dist/src/local_queue.js

@@ -0,0 +1,380 @@
+// The local, file-backed gig queue — the third gig backing, the offline sibling of the two HTTP
+// seams (postgrestQueueGig / rpcQueueGig, src/genome_store.ts:532,:493). It closes the asymmetry the
+// SPEC (docs/specs/SPEC-local-queue-contract.md) names: the genome port already ships a LOCAL sibling
+// (fileGenomeStore, src/genome_store.ts:77) so a genome can be READ from files, but the queue port
+// had none — so an open-source user could run gigs in-process yet never enqueue. This module is that
+// missing sibling: clone → build → enqueue → `coltrane work` in another terminal claims and runs it,
+// with no Supabase, no service origin, no cdk_ key, no minting backend.
+//
+// MUTUAL EXCLUSION WITHOUT A DATABASE OR A LOCK. State is a directory-per-state layout under `root`
+// (queued/, claimed/, parked/, done/, failed/, cancelled/), and every transition is a single POSIX
+// rename(2), which is atomic within a filesystem. A claim renames queued/<id> → claimed/<id>: the
+// winner's rename removes the source, and every loser's rename of the same source fails ENOENT — that
+// is how a loser learns it lost (maildir new/→cur/, cr.yp.to; FSQ tmp/→queue/→done/). No lockfile
+// (which would leave stale residue reintroducing the race), no in-process mutex (which cannot cross
+// the server / `coltrane work` process boundary this queue exists to bridge), no SQLite (a forbidden
+// dependency). node's own fs is sufficient, and the atomicity argument depends on staying on one FS.
+//
+// LEASE, not lock. A claim carries a lease {holder, renewed_at, expires_at} embedded in the moved
+// file, so one atomic rename carries the claim AND its lease together — there is never a window where
+// a claim exists without its lease. The holder renews with heartbeat (strictly advances the lease);
+// a crashed holder's grip falls open by timeout, and reap() returns lapsed claims to queued while
+// never touching a fresh one. A clock may be injected (opts.clock) so lease/reap laws are
+// deterministic and fast; it defaults to Date.now().
+//
+// IDEMPOTENT EFFECT. Because a lapsed lease lets a second worker re-run a gig, the honest guarantee
+// is at-least-once + idempotent-effect: complete() seals the output under content_sha (the same
+// sha256Hex(canonJson(...)) primitive the rest of the codebase uses), a re-run with the SAME output
+// re-seals rather than duplicating (duplicated:true), and a re-run that would seal a DIFFERENT output
+// fails closed rather than forking.
+//
+// This module is NOT wired into any surface (deps.queueGig / deps.cancelGig) — shipping the module
+// and its laws going green is a separate act from selecting it as a backing.
+import * as fs from "node:fs";
+import * as fsp from "node:fs/promises";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { sha256Hex, canonJson } from "./canonical_form.js";
+// ── The env-presence contract. ────────────────────────────────────────────────────────────────────
+/** The env var whose presence selects the local backing. */
+export const LOCAL_QUEUE_DIR_VAR = "COLTRANE_QUEUE_DIR";
+/** The drain's five-variable contract (drain_preflight.ts:55-61), kept SORTED. The local path must
+ *  never read a VALUE of any of these; selectQueueBacking only ever inspects key PRESENCE. */
+export const DRAIN_VARS = [
+    "COLTRANE_DRAIN_KEY",
+    "COLTRANE_DRAIN_URL",
+    "COLTRANE_INSTANCE",
+    "COLTRANE_STORE_ANON",
+    "COLTRANE_STORE_URL",
+];
+/**
+ * The single backing selector — file when the local dir is present, hosted for the drain env,
+ * conflict when both, none otherwise. It reads the VALUE of exactly one variable, LOCAL_QUEUE_DIR_VAR
+ * (not a drain var), and detects hosted presence by KEY PRESENCE via Object.keys — never by reading a
+ * drain variable's value. That distinction is load-bearing for F8: the test passes an env Proxy whose
+ * `get` trap throws on any drain-var read, so hosted detection must go through `ownKeys` (Object.keys
+ * does not trip the `get` trap), letting a local-present env resolve to `file` without touching one of
+ * the five. Values of the drain vars are never needed — their mere presence is the whole signal.
+ */
+export function selectQueueBacking(env) {
+    const localRaw = env[LOCAL_QUEUE_DIR_VAR];
+    const localPresent = typeof localRaw === "string" && localRaw.length > 0;
+    const keys = Object.keys(env);
+    const hostedPresent = DRAIN_VARS.some((v) => keys.includes(v));
+    if (localPresent && hostedPresent) {
+        return {
+            backing: "conflict",
+            why: `both ${LOCAL_QUEUE_DIR_VAR} and the hosted drain environment are set — refusing to guess which backing owns the gig`,
+        };
+    }
+    if (localPresent)
+        return { backing: "file", root: localRaw };
+    if (hostedPresent)
+        return { backing: "hosted" };
+    return {
+        backing: "none",
+        why: `no queue backing configured — set ${LOCAL_QUEUE_DIR_VAR} for a local file queue, or the drain environment for the hosted queue`,
+    };
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+const DEFAULT_LEASE_MS = 30_000;
+export function openLocalQueue(root, opts) {
+    const leaseMs = opts?.leaseMs ?? DEFAULT_LEASE_MS;
+    const clock = opts?.clock ?? Date.now;
+    const queuedDir = join(root, "queued");
+    const claimedDir = join(root, "claimed");
+    const parkedDir = join(root, "parked");
+    const doneDir = join(root, "done");
+    const failedDir = join(root, "failed");
+    const cancelledDir = join(root, "cancelled");
+    const tmpDir = join(root, "tmp");
+    const dirsByState = [
+        [queuedDir, "queued"],
+        [claimedDir, "claimed"],
+        [parkedDir, "awaiting_approval"],
+        [doneDir, "complete"],
+        [failedDir, "failed"],
+        [cancelledDir, "cancelled"],
+    ];
+    // A tmp+rename atomic write: a reader of the destination sees either the OLD bytes or the whole NEW
+    // bytes, never a mixture. tmp lives in a dedicated dir so a claim's readdir of queued/ never lists a
+    // half-written temp file (F4).
+    async function atomicWrite(dir, name, obj) {
+        await fsp.mkdir(tmpDir, { recursive: true });
+        const tmp = join(tmpDir, `${randomUUID()}.tmp`);
+        await fsp.writeFile(tmp, JSON.stringify(obj), "utf8");
+        await fsp.mkdir(dir, { recursive: true });
+        await fsp.rename(tmp, join(dir, name));
+    }
+    async function readGig(path) {
+        try {
+            return JSON.parse(await fsp.readFile(path, "utf8"));
+        }
+        catch {
+            return null;
+        }
+    }
+    function isEnoent(e) {
+        return typeof e === "object" && e !== null && e.code === "ENOENT";
+    }
+    async function enqueue(args) {
+        // F10 — a payload with no standard to run is unrunnable. Refuse at enqueue and persist nothing,
+        // rather than enqueue a row that can only fail on a drain thirty minutes later.
+        const slug = args["standard_slug"];
+        if (typeof slug !== "string" || slug.length === 0) {
+            throw new Error("enqueue requires a non-empty standard_slug — nothing to run");
+        }
+        const gig_id = randomUUID();
+        const now = clock();
+        const record = {
+            gig_id,
+            standard_slug: slug,
+            standard_version: typeof args["standard_version"] === "number" ? args["standard_version"] : null,
+            mode: typeof args["mode"] === "string" ? args["mode"] : "live",
+            input: isRecord(args["input"]) ? args["input"] : {},
+            acting_for: typeof args["acting_for"] === "string" ? args["acting_for"] : "",
+            venue: typeof args["venue"] === "string" ? args["venue"] : null,
+            enqueued_at: now,
+        };
+        // F1/F4 — write then rename over queued/<gig_id>. If the root cannot be persisted to (mkdir/rename
+        // fails, e.g. ENOTDIR under a regular file), this throws and NO success is reported.
+        await atomicWrite(queuedDir, gig_id, record);
+        return { gig_id, status: "queued" };
+    }
+    async function claim(worker) {
+        let candidates;
+        try {
+            candidates = (await fsp.readdir(queuedDir)).sort();
+        }
+        catch {
+            return null; // no queued/ dir yet ⇒ nothing to claim
+        }
+        await fsp.mkdir(claimedDir, { recursive: true });
+        for (const id of candidates) {
+            const src = join(queuedDir, id);
+            const dst = join(claimedDir, id);
+            try {
+                // The arbiter. Exactly one concurrent claimer's rename of a given source succeeds; every other
+                // gets ENOENT (I4/I5/F3) and moves on to the next candidate (I19). A live gig is not in
+                // queued/ at all, so it is never a candidate here (F7).
+                await fsp.rename(src, dst);
+            }
+            catch {
+                // A lost rename race (ENOENT) is how a loser learns it lost; any other per-row fault is
+                // likewise "could not take this row". Either way, move to the next candidate — a lost row is
+                // the null sentinel, never a thrown claim (I5/F3).
+                continue;
+            }
+            const record = await readGig(dst);
+            if (record === null)
+                continue;
+            const now = clock();
+            const lease = { holder: worker, renewed_at: now, expires_at: now + leaseMs };
+            record.worker = worker;
+            record.lease = lease;
+            // Persist the lease alongside the claim (idempotent overwrite of a file only this claimer owns).
+            await atomicWrite(claimedDir, id, record);
+            const claimed = {
+                gig_id: record.gig_id,
+                standard_slug: record.standard_slug,
+                standard_version: record.standard_version,
+                mode: record.mode,
+                input: record.input,
+                acting_for: record.acting_for,
+                venue: record.venue,
+                worker,
+                lease,
+                approvals: record.approvals ?? null,
+            };
+            return claimed;
+        }
+        return null;
+    }
+    async function heartbeat(worker, gig_id) {
+        const path = join(claimedDir, gig_id);
+        const record = await readGig(path);
+        // F5 — the caller must still HOLD the claim. A heartbeat against a lease that was lost (the gig
+        // lapsed and someone else took it) or that no longer exists is a loss, never a false "still held".
+        if (record === null || record.lease === undefined || record.lease.holder !== worker)
+            return false;
+        const now = clock();
+        record.lease = { holder: worker, renewed_at: now, expires_at: now + leaseMs };
+        record.worker = worker;
+        await atomicWrite(claimedDir, gig_id, record);
+        return true;
+    }
+    function reap() {
+        // SYNCHRONOUS and best-effort (mirrors worker.ts reapWorkerState): a single unreadable claim never
+        // aborts the sweep. Only claimed/ is scanned, so a parked or terminal gig is structurally out of
+        // reach (I13) rather than guarded by a per-file predicate a future edit could forget.
+        const requeued = [];
+        const errors = [];
+        let kept = 0;
+        const now = clock();
+        let entries;
+        try {
+            entries = fs.readdirSync(claimedDir);
+        }
+        catch {
+            return { requeued, kept, errors };
+        }
+        for (const id of entries) {
+            const path = join(claimedDir, id);
+            try {
+                const record = JSON.parse(fs.readFileSync(path, "utf8"));
+                const expires = record.lease?.expires_at;
+                if (typeof expires === "number" && expires <= now) {
+                    // Lapsed (I9/I10/I11) — return it to queued for the next worker. The rename is atomic; the
+                    // stale lease left in the file is inert (list() reports no lease for a queued row, and the
+                    // next claim overwrites it).
+                    fs.mkdirSync(queuedDir, { recursive: true });
+                    fs.renameSync(path, join(queuedDir, id));
+                    requeued.push(id);
+                }
+                else {
+                    kept++; // fresh (I8/I10) — never touched
+                }
+            }
+            catch (e) {
+                errors.push(`${id}: ${e instanceof Error ? e.message : String(e)}`);
+            }
+        }
+        return { requeued, kept, errors };
+    }
+    async function park(worker, gig_id) {
+        const src = join(claimedDir, gig_id);
+        const record = await readGig(src);
+        if (record === null || record.lease?.holder !== worker)
+            return false;
+        // Move claimed/ → parked/ first (one atomic rename), THEN clear the lease. The gig is never in two
+        // places, and the reaper (which scans only claimed/) can never mistake it for an abandoned claim
+        // (I13). awaiting_approval is not a live claim.
+        await fsp.mkdir(parkedDir, { recursive: true });
+        await fsp.rename(src, join(parkedDir, gig_id));
+        delete record.lease;
+        delete record.worker;
+        await atomicWrite(parkedDir, gig_id, record);
+        return true;
+    }
+    async function approve(gig_id, role, verdict, approved_by) {
+        // F6 — an empty verdict is not an approval. Fail closed rather than resume past the human chair on
+        // a verdict that says nothing.
+        if (!isRecord(verdict) || Object.keys(verdict).length === 0) {
+            throw new Error("an empty verdict is not an approval — refusing to resume past the human chair");
+        }
+        const src = join(parkedDir, gig_id);
+        const record = await readGig(src);
+        if (record === null)
+            return false;
+        const entry = approved_by !== undefined ? { verdict, approved_by } : { verdict };
+        const approvals = {
+            ...(record.approvals ?? {}),
+        };
+        approvals[role] = entry;
+        record.approvals = approvals;
+        // Seal the verdict into the parked row, THEN move parked/ → queued/ in one atomic rename, so the
+        // re-claimable row appears in queued/ already carrying its verdicts (I12).
+        await atomicWrite(parkedDir, gig_id, record);
+        await fsp.mkdir(queuedDir, { recursive: true });
+        await fsp.rename(join(parkedDir, gig_id), join(queuedDir, gig_id));
+        return true;
+    }
+    async function cancel(args) {
+        const gig_id = typeof args["gig_id"] === "string" ? args["gig_id"] : String(args["gig_id"] ?? "");
+        // Sibling of postgrestCancelGig: cancels a QUEUED row so it can never be claimed (I18). Moving it
+        // out of queued/ is the whole mechanism — a cancelled gig is simply no longer a claim candidate.
+        try {
+            await fsp.mkdir(cancelledDir, { recursive: true });
+            await fsp.rename(join(queuedDir, gig_id), join(cancelledDir, gig_id));
+        }
+        catch (e) {
+            if (!isEnoent(e))
+                throw e; // not-queued (already gone) is idempotent; a real IO fault is not
+        }
+        return { gig_id, status: "cancelled" };
+    }
+    async function locate(gig_id) {
+        for (const [dir] of dirsByState) {
+            const path = join(dir, gig_id);
+            try {
+                await fsp.access(path);
+                return { dir, path };
+            }
+            catch {
+                /* not in this state dir */
+            }
+        }
+        return null;
+    }
+    async function complete(worker, gig_id, output) {
+        const loc = await locate(gig_id);
+        if (loc === null)
+            throw new Error(`cannot complete unknown gig ${gig_id}`);
+        const record = await readGig(loc.path);
+        if (record === null)
+            throw new Error(`cannot complete unreadable gig ${gig_id}`);
+        // content_sha is a pure function of the output via the codebase's own canonical hash, so two
+        // separate completions of identical output hash identically by construction (I14).
+        const content_sha = sha256Hex(canonJson(output));
+        if (record.content_sha !== undefined) {
+            // I14 — a re-run (after a lapsed lease let a second worker take the gig) re-seals the SAME output
+            // rather than duplicating. F9 — a DIFFERENT output for the same gig fails closed, never forks.
+            if (record.content_sha === content_sha)
+                return { content_sha, duplicated: true };
+            throw new Error(`gig ${gig_id} already sealed a different output — refusing to fork the result`);
+        }
+        // Record the seal in place. The gig stays where it is (typically still claimed): a lapsed lease can
+        // then let a second worker re-run it, and that re-run dedups against this recorded content_sha.
+        record.content_sha = content_sha;
+        record.output = output;
+        await atomicWrite(loc.dir, gig_id, record);
+        return { content_sha, duplicated: false };
+    }
+    function list() {
+        const views = [];
+        for (const [dir, state] of dirsByState) {
+            let entries;
+            try {
+                entries = fs.readdirSync(dir);
+            }
+            catch {
+                continue; // dir not created yet
+            }
+            for (const id of entries) {
+                if (state === "claimed") {
+                    try {
+                        const record = JSON.parse(fs.readFileSync(join(dir, id), "utf8"));
+                        if (record.lease && typeof record.lease.holder === "string") {
+                            views.push({ gig_id: id, state, holder: record.lease.holder, lease: record.lease });
+                            continue;
+                        }
+                    }
+                    catch {
+                        /* fall through to the lease-less view */
+                    }
+                    views.push({ gig_id: id, state });
+                }
+                else {
+                    views.push({ gig_id: id, state });
+                }
+            }
+        }
+        return views;
+    }
+    return { enqueue, claim, heartbeat, reap, park, approve, cancel, complete, list, leaseMs };
+}
+/** The deps.queueGig-shaped enqueue seam — byte-compatible with postgrestQueueGig / rpcQueueGig
+ *  ({gig_id, status:'queued'}), so a caller cannot tell which backing answered (I1). */
+export function fileQueueGig(root) {
+    const q = openLocalQueue(root);
+    return (args) => q.enqueue(args);
+}
+/** The deps.cancelGig-shaped seam — sibling of postgrestCancelGig ({gig_id, status:'cancelled'})
+ *  (I18). */
+export function fileCancelGig(root) {
+    const q = openLocalQueue(root);
+    return (args) => q.cancel(args);
+}
+//# sourceMappingURL=local_queue.js.map

package/dist/src/local_queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"local_queue.js","sourceRoot":"","sources":["../../src/local_queue.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,qGAAqG;AACrG,sGAAsG;AACtG,mGAAmG;AACnG,qGAAqG;AACrG,qGAAqG;AACrG,wEAAwE;AACxE,EAAE;AACF,oGAAoG;AACpG,mGAAmG;AACnG,kGAAkG;AAClG,sGAAsG;AACtG,kGAAkG;AAClG,oGAAoG;AACpG,qGAAqG;AACrG,qGAAqG;AACrG,EAAE;AACF,kGAAkG;AAClG,sGAAsG;AACtG,oGAAoG;AACpG,kGAAkG;AAClG,0FAA0F;AAC1F,qDAAqD;AACrD,EAAE;AACF,oGAAoG;AACpG,gGAAgG;AAChG,oGAAoG;AACpG,sGAAsG;AACtG,oCAAoC;AACpC,EAAE;AACF,mGAAmG;AACnG,6EAA6E;AAC7E,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,GAAG,MAAM,kBAAkB,CAAC;AACxC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAuE3D,qGAAqG;AAErG,4DAA4D;AAC5D,MAAM,CAAC,MAAM,mBAAmB,GAAG,oBAAoB,CAAC;AAExD;8FAC8F;AAC9F,MAAM,CAAC,MAAM,UAAU,GAAsB;IAC3C,oBAAoB;IACpB,oBAAoB;IACpB,mBAAmB;IACnB,qBAAqB;IACrB,oBAAoB;CACrB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAuC;IACxE,MAAM,QAAQ,GAAG,GAAG,CAAC,mBAAmB,CAAC,CAAC;IAC1C,MAAM,YAAY,GAAG,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC;IACzE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9B,MAAM,aAAa,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAE/D,IAAI,YAAY,IAAI,aAAa,EAAE,CAAC;QAClC,OAAO;YACL,OAAO,EAAE,UAAU;YACnB,GAAG,EAAE,QAAQ,mBAAmB,0FAA0F;SAC3H,CAAC;IACJ,CAAC;IACD,IAAI,YAAY;QAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IAC7D,IAAI,aAAa;QAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAChD,OAAO;QACL,OAAO,EAAE,MAAM;QACf,GAAG,EAAE,qCAAqC,mBAAmB,wEAAwE;KACtI,CAAC;AACJ,CAAC;AAqBD,SAAS,QAAQ,CAAC,CAAU;IAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,gBAAgB,GAAG,MAAM,CAAC;AAEhC,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,IAAwB;IACnE,MAAM,OAAO,GAAG,IAAI,EAAE,OAAO,IAAI,gBAAgB,CAAC;IAClD,MAAM,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,IAAI,CAAC,GAAG,CAAC;IAEtC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACvC,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACzC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACnC,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;IACvC,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;IAC7C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IAEjC,MAAM,WAAW,GAA4D;QAC3E,CAAC,SAAS,EAAE,QAAQ,CAAC;QACrB,CAAC,UAAU,EAAE,SAAS,CAAC;QACvB,CAAC,SAAS,EAAE,mBAAmB,CAAC;QAChC,CAAC,OAAO,EAAE,UAAU,CAAC;QACrB,CAAC,SAAS,EAAE,QAAQ,CAAC;QACrB,CAAC,YAAY,EAAE,WAAW,CAAC;KAC5B,CAAC;IAEF,oGAAoG;IACpG,qGAAqG;IACrG,+BAA+B;IAC/B,KAAK,UAAU,WAAW,CAAC,GAAW,EAAE,IAAY,EAAE,GAAc;QAClE,MAAM,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7C,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,UAAU,EAAE,MAAM,CAAC,CAAC;QAChD,MAAM,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC;QACtD,MAAM,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAC1C,MAAM,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,UAAU,OAAO,CAAC,IAAY;QACjC,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAc,CAAC;QACnE,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,SAAS,QAAQ,CAAC,CAAU;QAC1B,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,IAAK,CAAuB,CAAC,IAAI,KAAK,QAAQ,CAAC;IAC3F,CAAC;IAED,KAAK,UAAU,OAAO,CAAC,IAA6B;QAClD,gGAAgG;QAChG,gFAAgF;QAChF,MAAM,IAAI,GAAG,IAAI,CAAC,eAAe,CAAC,CAAC;QACnC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClD,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;QACjF,CAAC;QACD,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,KAAK,EAAE,CAAC;QACpB,MAAM,MAAM,GAAc;YACxB,MAAM;YACN,aAAa,EAAE,IAAI;YACnB,gBAAgB,EAAE,OAAO,IAAI,CAAC,kBAAkB,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAI,CAAC,kBAAkB,CAAY,CAAC,CAAC,CAAC,IAAI;YAC5G,IAAI,EAAE,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAI,CAAC,MAAM,CAAY,CAAC,CAAC,CAAC,MAAM;YAC1E,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE;YACnD,UAAU,EAAE,OAAO,IAAI,CAAC,YAAY,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAI,CAAC,YAAY,CAAY,CAAC,CAAC,CAAC,EAAE;YACxF,KAAK,EAAE,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAI,CAAC,OAAO,CAAY,CAAC,CAAC,CAAC,IAAI;YAC3E,WAAW,EAAE,GAAG;SACjB,CAAC;QACF,mGAAmG;QACnG,qFAAqF;QACrF,MAAM,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACtC,CAAC;IAED,KAAK,UAAU,KAAK,CAAC,MAAc;QACjC,IAAI,UAAoB,CAAC;QACzB,IAAI,CAAC;YACH,UAAU,GAAG,CAAC,MAAM,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QACrD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,CAAC,wCAAwC;QACvD,CAAC;QACD,MAAM,GAAG,CAAC,KAAK,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACjD,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;YAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;YAChC,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YACjC,IAAI,CAAC;gBACH,+FAA+F;gBAC/F,wFAAwF;gBACxF,wDAAwD;gBACxD,MAAM,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;YAC7B,CAAC;YAAC,MAAM,CAAC;gBACP,wFAAwF;gBACxF,6FAA6F;gBAC7F,mDAAmD;gBACnD,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;YAClC,IAAI,MAAM,KAAK,IAAI;gBAAE,SAAS;YAC9B,MAAM,GAAG,GAAG,KAAK,EAAE,CAAC;YACpB,MAAM,KAAK,GAAe,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,GAAG,OAAO,EAAE,CAAC;YACzF,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;YACvB,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;YACrB,iGAAiG;YACjG,MAAM,WAAW,CAAC,UAAU,EAAE,EAAE,EAAE,MAAM,CAAC,CAAC;YAC1C,MAAM,OAAO,GAAoB;gBAC/B,MAAM,EAAE,MAAM,CAAC,MAAM;gBACrB,aAAa,EAAE,MAAM,CAAC,aAAa;gBACnC,gBAAgB,EAAE,MAAM,CAAC,gBAAgB;gBACzC,IAAI,EAAE,MAAM,CAAC,IAAI;gBACjB,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,UAAU,EAAE,MAAM,CAAC,UAAU;gBAC7B,KAAK,EAAE,MAAM,CAAC,KAAK;gBACnB,MAAM;gBACN,KAAK;gBACL,SAAS,EAAE,MAAM,CAAC,SAAS,IAAI,IAAI;aACpC,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,UAAU,SAAS,CAAC,MAAc,EAAE,MAAc;QACrD,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACtC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QACnC,gGAAgG;QAChG,mGAAmG;QACnG,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,MAAM;YAAE,OAAO,KAAK,CAAC;QAClG,MAAM,GAAG,GAAG,KAAK,EAAE,CAAC;QACpB,MAAM,CAAC,KAAK,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,GAAG,OAAO,EAAE,CAAC;QAC9E,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;QACvB,MAAM,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC9C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,SAAS,IAAI;QACX,mGAAmG;QACnG,iGAAiG;QACjG,sFAAsF;QACtF,MAAM,QAAQ,GAAa,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAa,EAAE,CAAC;QAC5B,IAAI,IAAI,GAAG,CAAC,CAAC;QACb,MAAM,GAAG,GAAG,KAAK,EAAE,CAAC;QACpB,IAAI,OAAiB,CAAC;QACtB,IAAI,CAAC;YACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QACpC,CAAC;QACD,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;YACzB,MAAM,IAAI,GAAG,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;YAClC,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAc,CAAC;gBACtE,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,EAAE,UAAU,CAAC;gBACzC,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,IAAI,GAAG,EAAE,CAAC;oBAClD,2FAA2F;oBAC3F,2FAA2F;oBAC3F,6BAA6B;oBAC7B,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;oBAC7C,EAAE,CAAC,UAAU,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC,CAAC;oBACzC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;gBACpB,CAAC;qBAAM,CAAC;oBACN,IAAI,EAAE,CAAC,CAAC,iCAAiC;gBAC3C,CAAC;YACH,CAAC;YAAC,OAAO,CAAC,EAAE,CAAC;gBACX,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YACtE,CAAC;QACH,CAAC;QACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACpC,CAAC;IAED,KAAK,UAAU,IAAI,CAAC,MAAc,EAAE,MAAc;QAChD,MAAM,GAAG,GAAG,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACrC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM;YAAE,OAAO,KAAK,CAAC;QACrE,mGAAmG;QACnG,iGAAiG;QACjG,gDAAgD;QAChD,MAAM,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;QAC/C,OAAO,MAAM,CAAC,KAAK,CAAC;QACpB,OAAO,MAAM,CAAC,MAAM,CAAC;QACrB,MAAM,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,UAAU,OAAO,CACpB,MAAc,EACd,IAAY,EACZ,OAAgC,EAChC,WAAoB;QAEpB,mGAAmG;QACnG,+BAA+B;QAC/B,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,KAAK,CAAC,+EAA+E,CAAC,CAAC;QACnG,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;QACpC,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAClC,MAAM,KAAK,GACT,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC;QACrE,MAAM,SAAS,GAA+E;YAC5F,GAAG,CAAC,MAAM,CAAC,SAAS,IAAI,EAAE,CAAC;SAC5B,CAAC;QACF,SAAS,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACxB,MAAM,CAAC,SAAS,GAAG,SAAS,CAAC;QAC7B,iGAAiG;QACjG,2EAA2E;QAC3E,MAAM,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC7C,MAAM,GAAG,CAAC,KAAK,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;QACnE,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,UAAU,MAAM,CAAC,IAA6B;QACjD,MAAM,MAAM,GAAG,OAAO,IAAI,CAAC,QAAQ,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAE,IAAI,CAAC,QAAQ,CAAY,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9G,kGAAkG;QAClG,iGAAiG;QACjG,IAAI,CAAC;YACH,MAAM,GAAG,CAAC,KAAK,CAAC,YAAY,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,EAAE,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAC;QACxE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;gBAAE,MAAM,CAAC,CAAC,CAAC,kEAAkE;QAC/F,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACzC,CAAC;IAED,KAAK,UAAU,MAAM,CAAC,MAAc;QAClC,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,WAAW,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;YAC/B,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;gBACvB,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,2BAA2B;YAC7B,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED,KAAK,UAAU,QAAQ,CACrB,MAAc,EACd,MAAc,EACd,MAA+B;QAE/B,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;QACjC,IAAI,GAAG,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,MAAM,EAAE,CAAC,CAAC;QAC3E,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,MAAM,KAAK,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,MAAM,EAAE,CAAC,CAAC;QACjF,6FAA6F;QAC7F,mFAAmF;QACnF,MAAM,WAAW,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;QACjD,IAAI,MAAM,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;YACrC,kGAAkG;YAClG,+FAA+F;YAC/F,IAAI,MAAM,CAAC,WAAW,KAAK,WAAW;gBAAE,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;YACjF,MAAM,IAAI,KAAK,CAAC,OAAO,MAAM,kEAAkE,CAAC,CAAC;QACnG,CAAC;QACD,oGAAoG;QACpG,gGAAgG;QAChG,MAAM,CAAC,WAAW,GAAG,WAAW,CAAC;QACjC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;QACvB,MAAM,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QAC3C,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IAC5C,CAAC;IAED,SAAS,IAAI;QACX,MAAM,KAAK,GAAmB,EAAE,CAAC;QACjC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,WAAW,EAAE,CAAC;YACvC,IAAI,OAAiB,CAAC;YACtB,IAAI,CAAC;gBACH,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;YAChC,CAAC;YAAC,MAAM,CAAC;gBACP,SAAS,CAAC,sBAAsB;YAClC,CAAC;YACD,KAAK,MAAM,EAAE,IAAI,OAAO,EAAE,CAAC;gBACzB,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;oBACxB,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,EAAE,MAAM,CAAC,CAAc,CAAC;wBAC/E,IAAI,MAAM,CAAC,KAAK,IAAI,OAAO,MAAM,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;4BAC5D,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;4BACpF,SAAS;wBACX,CAAC;oBACH,CAAC;oBAAC,MAAM,CAAC;wBACP,yCAAyC;oBAC3C,CAAC;oBACD,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBACpC,CAAC;qBAAM,CAAC;oBACN,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBACpC,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC7F,CAAC;AAED;wFACwF;AACxF,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED;aACa;AACb,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,MAAM,CAAC,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC/B,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAClC,CAAC"}

package/dist/src/residency.d.ts

@@ -0,0 +1,149 @@
+export { workOnce as residencyGigPath } from "./worker.js";
+export type ResidencyState = "seated" | "listening" | "playing" | "hibernated" | "drained" | "unseated";
+export declare const RESIDENCY_STATES: readonly ResidencyState[];
+export declare const LIVE_STATES: ReadonlySet<ResidencyState>;
+export type ResidencyOpKind = "claim" | "listen" | "play" | "wake_seal" | "ack" | "heartbeat" | "hibernate" | "thaw" | "drain" | "unseat" | "reap";
+export declare const RESIDENCY_OPS: readonly ResidencyOpKind[];
+export type ResidencyActor = "holder" | "reaper" | "operator";
+export interface LegalTransition {
+    from: ResidencyState;
+    op: ResidencyOpKind;
+    to: ResidencyState;
+}
+export declare const LEGAL_TRANSITIONS: readonly LegalTransition[];
+export declare const RESIDENCY_ROW_FIELDS: readonly string[];
+export declare const REFLEX_BUDGET_TICKS = 8;
+export interface ResidencyRecord {
+    agent_slug: string;
+    org: string;
+    venue_slug: string;
+    channel_id: string;
+    soul_output_id: string | null;
+    status: ResidencyState;
+    session_id: string | null;
+    cursor: number;
+    host: string | null;
+    lease_until: number;
+    heartbeat_at: number;
+    fence: number;
+    last_sealed_sha: string | null;
+    private_memory?: unknown;
+}
+export interface ResidencyOp {
+    kind: ResidencyOpKind;
+    by?: ResidencyActor;
+    fence?: number;
+    now?: number;
+    host?: string;
+    session_id?: string;
+    message_index?: number;
+    sealed_output_sha?: string | null;
+    cortex_alive?: boolean;
+    agent_slug?: string;
+    org?: string;
+    channel_id?: string;
+}
+export type ResidencyRefusal = "illegal_transition" | "wrong_party" | "stale_fence" | "dead_cortex" | "immutable_identity" | "cursor_without_seal" | "double_activation";
+export type ResidencyTransition = {
+    ok: true;
+    next: ResidencyRecord;
+} | {
+    ok: false;
+    reason: ResidencyRefusal;
+};
+export interface InboundMessage {
+    id: string;
+    text: string;
+    at: number;
+}
+export interface SimClock {
+    now(): number;
+    tick(n?: number): void;
+}
+export interface ReflexDeps {
+    invoke: (...a: unknown[]) => unknown;
+    clock: SimClock;
+}
+export interface ReflexResult {
+    acked: true;
+    elapsed_ticks: number;
+}
+export interface ResidencySpec {
+    agent_slug: string;
+    org: string;
+    venue_slug: string;
+    channel_id: string;
+}
+export interface BootDeps {
+    resolveAgent: (slug: string) => unknown | null;
+    resolveVenue: (slug: string) => unknown | null;
+    cortexPresent: () => boolean;
+    seatRow: (rec: ResidencyRecord) => void;
+}
+export type BootRefusal = "no_such_agent" | "no_such_venue" | "no_cortex";
+export type BootResult = {
+    ok: true;
+    rec: ResidencyRecord;
+} | {
+    ok: false;
+    refusal: BootRefusal;
+};
+export interface VenueLike {
+    credential_surface: readonly string[];
+}
+export type CredentialAdmission = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "credential_breach";
+};
+/**
+ * Apply one residency op under its party constraint. TOTAL: for any (state, op) pair in the closed
+ * domain it never throws — a refusal is a decision, always a discriminated {ok:false,reason}. Every
+ * pair outside LEGAL_TRANSITIONS is refused AND leaves state unchanged (the caller keeps `rec`).
+ */
+export declare function applyResidencyOp(rec: ResidencyRecord, op: ResidencyOp): ResidencyTransition;
+/**
+ * Ack an inbound message in reflex: dumb by design. Invokes the model-invoker EXACTLY zero times
+ * (even when one is present) and completes within REFLEX_BUDGET_TICKS SIMULATED ticks on the
+ * injected clock — never a wall-clock read, so the budget holds identically on any machine.
+ */
+export declare function reflexAck(_msg: InboundMessage, deps: ReflexDeps): ReflexResult;
+/**
+ * The named reader for a dead-hibernated residency: a hibernated seat whose lease has lapsed is
+ * forced to `unseated`. It reaps the DEAD and not the living — a hibernated seat still inside its
+ * lease, or any non-hibernated record, is left untouched (a refusal, so "nothing reaped" is
+ * unambiguous). `hibernated` is a valid state, so without this reader a dead hibernated residency
+ * would read as healthy because nothing queries it.
+ */
+export declare function reapResidency(rec: ResidencyRecord, now: number): ResidencyTransition;
+/**
+ * A presence cannot read its OWN impressions as content: sealing an impression as evidence would let
+ * it witness itself. The self-read is scoped out — no impression content is ever returned.
+ */
+export declare function readOwnImpressions(_rec: ResidencyRecord): {
+    content: null;
+    scoped_out: true;
+} | {
+    content: unknown;
+};
+/**
+ * Admit a credential class only if the venue explicitly declares it in its credential_surface. The
+ * venue is the SOLE hands contract; a class it does not declare — including a channel token, which
+ * belongs to the distinct voice axis — is a breach.
+ */
+export declare function admitVenueCredential(venue: VenueLike, credentialClass: string): CredentialAdmission;
+/**
+ * Seat a residency, fail-closed. Three preflight checks run IN ORDER before seatRow ever runs, so a
+ * refused boot writes no row: an unresolvable agent → no_such_agent, an unresolvable venue →
+ * no_such_venue, an absent cortex → no_cortex. Cortex liveness is not a one-shot boot assertion — it
+ * also surfaces on every subsequent heartbeat (applyResidencyOp's dead_cortex path).
+ */
+export declare function bootResidency(spec: ResidencySpec, deps: BootDeps): BootResult;
+/**
+ * The `reside` verb REUSES work's gig path — it does not fork the drain's five-variable env contract.
+ * Missing COLTRANE_STORE_URL / COLTRANE_STORE_ANON is a usage refusal (exit 2), the same door work
+ * uses (src/cli.ts:241-248). The gig itself is workOnce, re-exported above as residencyGigPath; the
+ * store/channel wiring is a deployment seam the laws inject rather than assert here.
+ */
+export declare function runReside(_argv: readonly string[], io: unknown): Promise<number>;