@cotal-ai/manager 0.16.0 → 0.17.0

package/dist/session/establish.js

@@ -0,0 +1,174 @@
+import { EpEnvelopeError, mintSessionGrant, redeemSession, retrieveServingCredential, verifySessionGrant, } from "@cotal-ai/core";
+import { MANAGER_ENDPOINT } from "../manager-service-contract.js";
+/** Mint an attach offer: a §13.6 session grant on the `manager` endpoint bound to the holder triple
+ *  + serving instance/epoch, paired with the manager-side target binding. Pure — signs + returns;
+ *  the manager records the offer in its {@link ManagerSessionRegistry}. */
+export function mintAttachOffer(args) {
+    const grant = mintSessionGrant({
+        space: args.space,
+        endpoint: MANAGER_ENDPOINT,
+        holder: args.holder,
+        serving: args.serving,
+        ttlMs: args.ttlMs,
+        ...(args.window !== undefined ? { window: args.window } : {}),
+        issuerKeyId: args.signer.keyId,
+        ...(args.now !== undefined ? { now: args.now } : {}),
+    }, args.signer.keyPair);
+    return { grant, target: { name: args.target.name, lifecycleUid: args.target.lifecycleUid } };
+}
+/**
+ * The STATIC redeem seam (item 6's wired path): the manager runs the §13.6 redemption — verify the
+ * signed grant, then `redeemSession` (the one-use `issuing` create-CAS + presenter-equality + the
+ * gate-pinned stage + the finalize's fresh epoch re-checks) — and, for the SERVING half, mints,
+ * stages, releases and revokes a real per-session credential through {@link SessionServing}.
+ *
+ * WHAT EACH HALF ACTUALLY GETS, stated exactly, because the two halves are NOT symmetric here and a
+ * comment claiming they are would be worse than the asymmetry:
+ *
+ *  - SERVING half (this manager's own): a real `session-serving` credential, exact-subject
+ *    (`eps.<endpoint>.<sessionId>.<epoch>.{in,out}`), TTL-bound to the session, staged into this
+ *    instance's §13.1 `epcred.<endpoint>.<instanceId>` family under the open-and-commit fence, and
+ *    revoked BY NAME at the session's terminal. It replaces a STANDING wildcard credential that
+ *    reached every live session's bytes at its epoch (SPEC 13.9:2526).
+ *  - CALLER half: NOT minted, staged, or revoked here, and `releaseCredential` returns a MARKER with
+ *    no usable bytes for it. The caller's `session-caller` JWT is minted OUT OF BAND from the local
+ *    space seed — by the console establisher and by CLI attach — after redemption.
+ *
+ *    SPEC 13.6 PAIR-REVOKE IS NOT IMPLEMENTED FOR THE CALLER HALF. Stated exactly, because the
+ *    difference between this and pair-revoke is the whole residual: that JWT is not written into the
+ *    session lineage, is not named by the session row's credential material, and is untouched by
+ *    session close and by takeover reconcile. It dies by TTL alone, at a 24h ceiling
+ *    (`SESSION_GRANT_MAX_TTL_MS`).
+ *
+ *    Why the window is tolerable for THIS static slice, as reviewed: the caller grant is
+ *    exact-pinned to one `(endpoint, sessionId, epoch)`, so it can reach neither a sibling session
+ *    nor a successor epoch; and once the serving half is revoked and its connection closed there is
+ *    no counterparty on those two subjects. What survives is a broker-valid connection, not reach
+ *    into another session. Closing it properly means minting the caller half inside redemption,
+ *    which needs the user-mode (#29) callout exchange. Until that lands, do not describe any part of
+ *    this as pair teardown.
+ *  - `revokeCredential` is therefore ONE-SIDED by construction: it revokes an id this seam minted
+ *    and is an explicit no-op for the caller id, rather than silently appearing to revoke both.
+ */
+export function staticRedemptionSeam(deps) {
+    // The minted-but-unreleased serving credential, held between `allocateCredentialIds` and
+    // `releaseCredential`. NAMED RESIDUAL: the JWT exists before the one-use create-CAS is won,
+    // because the credential id the `issuing` row must name IS its digest. If the create loses, the
+    // bytes are dropped here having never been staged, released, or connected with — they reach no
+    // other party and no ledger row was written for them.
+    const minted = new Map();
+    const callerId = (grant) => `${grant.sessionId}.c`;
+    const marker = async (sessionId, credentialId) => {
+        const row = await deps.ledger.read(sessionId);
+        if (!row)
+            throw new EpEnvelopeError("failed-precondition", `no session row for ${sessionId}; nothing releases without its authority row (SPEC 13.6)`);
+        return { id: credentialId, creds: "", exp: row.exp };
+    };
+    // The serving pin core observed for THIS redemption, kept so the stage fences on the WHOLE
+    // observation rather than the bare {key, revision} core's hook type carries. One seam is built per
+    // establishment, so this holds exactly one redemption's pin and cannot be crossed with another's.
+    let servingPin;
+    const hooks = {
+        ledger: deps.ledger,
+        holderProcessEpoch: (h) => deps.holderProcessEpoch(h),
+        servingEpoch: (e, i) => deps.servingEpoch(e, i),
+        observeHolderGate: (h) => deps.observeHolderGate(h),
+        observeServingGate: async (e, i) => {
+            servingPin = await deps.observeServingGate(e, i);
+            return servingPin;
+        },
+        allocateCredentialIds: async (grant) => {
+            const cred = await deps.serving.mint(grant);
+            minted.set(grant.sessionId, cred);
+            return { credCaller: callerId(grant), credServing: cred.id };
+        },
+        // The §13.1 fence for the half this manager owns: stage the serving credential's ledger row
+        // REVISION-PINNED to the serving gate observed moments ago. A barrier that moved the gate makes
+        // this LOSE and throw, and redeemSession turns that into a refusal that releases nothing.
+        stagePair: async (grant, ids, pins) => {
+            const cred = minted.get(grant.sessionId);
+            if (!cred || cred.id !== ids.credServing)
+                throw new EpEnvelopeError("internal", `no minted serving credential for session ${grant.sessionId}; the stage cannot pin a credential that was never minted (SPEC 13.6)`);
+            // The pin handed to the stage MUST be the one this seam observed. Core passes the observation
+            // through, so this is an identity re-check, not a conversion: if it ever failed we would be
+            // fencing against a gate nobody in this redemption read, which is worse than not staging.
+            if (!servingPin || servingPin.revision !== pins.serving.revision || servingPin.key !== pins.serving.key)
+                throw new EpEnvelopeError("internal", `the serving gate pin staged against is not the one this redemption observed for session ${grant.sessionId} (SPEC 13.1)`);
+            await deps.serving.stage(grant, cred, servingPin);
+        },
+        releaseCredential: async (sessionId, credentialId) => {
+            const cred = minted.get(sessionId);
+            // Idempotent for the row's life (§13.6 lost-response retry): the SAME bytes, never a re-mint.
+            if (cred && cred.id === credentialId)
+                return cred;
+            return marker(sessionId, credentialId); // the caller half: no bytes to hand back (see doc)
+        },
+        revokeCredential: async (id) => {
+            for (const [sessionId, cred] of minted) {
+                if (cred.id !== id)
+                    continue;
+                await deps.serving.revoke(id);
+                minted.delete(sessionId);
+                return;
+            }
+            // Not ours: the caller id, which this seam never minted and therefore cannot revoke.
+        },
+        ...(deps.now ? { now: deps.now } : {}),
+    };
+    return {
+        async redeem(grant, presenter) {
+            const now = deps.now?.() ?? Date.now();
+            const verified = await verifySessionGrant(grant, { space: deps.space, resolveAnchor: deps.resolveAnchor, now });
+            try {
+                await redeemSession(verified, presenter, hooks); // one-use CAS + presenter-equality (throws on refuse)
+            }
+            catch (e) {
+                minted.delete(verified.sessionId); // a refused redemption keeps no minted bytes
+                throw e;
+            }
+            return { sessionId: verified.sessionId };
+        },
+        serving: (sessionId, presenter) => retrieveServingCredential(sessionId, presenter, hooks),
+    };
+}
+/** The USER-MODE redeem seam: UNWIRED (the #29 auth-trigger slice owns the callout-minted
+ *  per-session credential path). It REFUSES LOUD, naming the path — a user-mode attach fails rather
+ *  than degrading to the static seam (item-6 binding no-fallback rule). */
+export function userModeRedemptionSeam() {
+    const refuse = () => Promise.reject(new EpEnvelopeError("unimplemented", "user-mode session redemption (callout-minted per-session credentials) is not wired in this build; " +
+        "it is the #29 auth-trigger slice. A user-mode attach fails loud rather than degrading (SPEC 13.6, item-6 no-fallback)."));
+    return { redeem: refuse, serving: refuse };
+}
+/** The manager's in-memory session registry: the sessionId → (target lifecycle, offer) binding the
+ *  §13.6 grant cannot carry. The serve path looks the target up here and re-checks its liveness
+ *  before bridging, so a despawned/replaced target ends the session (`target-despawn`). */
+export class ManagerSessionRegistry {
+    #byId = new Map();
+    /** Record a freshly minted offer. Throws on a sessionId collision (a fresh unguessable id never
+     *  repeats — a repeat is a mint bug, never silently overwritten). */
+    record(offer) {
+        if (this.#byId.has(offer.grant.sessionId))
+            throw new EpEnvelopeError("already-exists", `session ${offer.grant.sessionId} is already recorded; a fresh sessionId never repeats (SPEC 13.6)`);
+        this.#byId.set(offer.grant.sessionId, { target: offer.target, grant: offer.grant });
+    }
+    /** The target bound to a sessionId, or undefined if unknown/removed. */
+    target(sessionId) {
+        return this.#byId.get(sessionId)?.target;
+    }
+    /** Drop a session (redeem-refused, closed, expired, or target gone). Idempotent. */
+    remove(sessionId) {
+        this.#byId.delete(sessionId);
+    }
+    /** Every sessionId whose target is a given agent incarnation — the set a despawn/restart must end. */
+    forTarget(name, lifecycleUid) {
+        const out = [];
+        for (const [id, e] of this.#byId)
+            if (e.target.name === name && e.target.lifecycleUid === lifecycleUid)
+                out.push(id);
+        return out;
+    }
+    get size() {
+        return this.#byId.size;
+    }
+}
+//# sourceMappingURL=establish.js.map

package/dist/session/establish.js.map

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

package/dist/session/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * P2 item 6 — the manager's mesh-attach session plane: the offer mint + redeem enforcement, the
+ * PTY ↔ rail bridge, and the application framing over the core §13.6 session composite. The
+ * generic composite (grant/redeem/rails/ledger) lives in `@cotal-ai/core` +
+ * `implementations/auth`; this module is the manager-side CONSUMER that replaces the loopback
+ * `ws://127.0.0.1` attach face.
+ */
+export { mintAttachOffer, staticRedemptionSeam, userModeRedemptionSeam, ManagerSessionRegistry, type AttachOffer, type MintAttachOfferArgs, type SessionTarget, type RedemptionSeam, type SessionServing, type StaticRedemptionDeps, } from "./establish.js";
+export { serveSessionBridge, type ServeSessionBridgeOpts, type SessionBridge, type AttachEndReason } from "./bridge.js";
+export { ManagerSessionPlane, kvManagerSessionLedger, openSessionLedgerKv, MAX_LIVE_SESSIONS_DEFAULT, type ManagerSessionPlaneDeps, } from "./plane.js";
+export { encodeTerminalData, terminalFrameBytes, decodeTerminalFrame, type TerminalFrame } from "@cotal-ai/core";
+//# sourceMappingURL=index.d.ts.map

package/dist/session/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,EACtB,KAAK,WAAW,EAChB,KAAK,mBAAmB,EACxB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,oBAAoB,GAC1B,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,KAAK,aAAa,EAAE,KAAK,eAAe,EAAE,MAAM,aAAa,CAAC;AACxH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,EACzB,KAAK,uBAAuB,GAC7B,MAAM,YAAY,CAAC;AAIpB,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/session/index.js

@@ -0,0 +1,15 @@
+/**
+ * P2 item 6 — the manager's mesh-attach session plane: the offer mint + redeem enforcement, the
+ * PTY ↔ rail bridge, and the application framing over the core §13.6 session composite. The
+ * generic composite (grant/redeem/rails/ledger) lives in `@cotal-ai/core` +
+ * `implementations/auth`; this module is the manager-side CONSUMER that replaces the loopback
+ * `ws://127.0.0.1` attach face.
+ */
+export { mintAttachOffer, staticRedemptionSeam, userModeRedemptionSeam, ManagerSessionRegistry, } from "./establish.js";
+export { serveSessionBridge } from "./bridge.js";
+export { ManagerSessionPlane, kvManagerSessionLedger, openSessionLedgerKv, MAX_LIVE_SESSIONS_DEFAULT, } from "./plane.js";
+// The terminal-session frame codec is NORMATIVE WIRE and lives in core (the §13.6 terminal-session
+// profile); re-exported here for the manager's own consumers/smokes. The CLI + console import it
+// straight from @cotal-ai/core (implementations cannot import each other).
+export { encodeTerminalData, terminalFrameBytes, decodeTerminalFrame } from "@cotal-ai/core";
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/session/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EACL,eAAe,EACf,oBAAoB,EACpB,sBAAsB,EACtB,sBAAsB,GAOvB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,kBAAkB,EAAyE,MAAM,aAAa,CAAC;AACxH,OAAO,EACL,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,EACnB,yBAAyB,GAE1B,MAAM,YAAY,CAAC;AACpB,mGAAmG;AACnG,iGAAiG;AACjG,2EAA2E;AAC3E,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,mBAAmB,EAAsB,MAAM,gBAAgB,CAAC"}

package/dist/session/plane.d.ts

@@ -0,0 +1,120 @@
+import type { KV } from "@nats-io/kv";
+import type { NatsConnection } from "@nats-io/transport-node";
+import { type AnchorResolver, type AttachSession, type SessionGrant, type SessionLedger } from "@cotal-ai/core";
+import { type SessionServing, type SessionTarget } from "./establish.js";
+import type { AttachEndReason } from "./bridge.js";
+/** A manager-local {@link SessionLedger} over `session.<id>` rows in the DEDICATED sessions bucket
+ *  KV (never the auth bucket — §13.9 subject-blindness confinement). Drives the SAME core row/key
+ *  types as implementations/auth's ledger with the manager's own KV CAS: the
+ *  one-use is `createIssuing`'s create-only CAS; finalize/terminal/revoke are revision-pinned
+ *  updates (a lost CAS returns false / retries on the next sweep, never a silent overwrite). */
+export declare function kvManagerSessionLedger(kv: KV): SessionLedger;
+/** The default global live-session ceiling. Configurable per manager
+ *  ({@link ManagerSessionPlaneDeps.maxSessions}) because the right number is deployment-shaped: the
+ *  browser console opens a session PER PANE, so a dashboard over a large mesh legitimately holds
+ *  many at once, and a ceiling low enough to feel like a bound would break it. */
+export declare const MAX_LIVE_SESSIONS_DEFAULT = 64;
+export interface ManagerSessionPlaneDeps {
+    space: string;
+    /** The serving manager incarnation — instanceId = the managerLifecycleUid, epoch = the serve grant epoch. */
+    serving: {
+        instanceId: string;
+        epoch: number;
+    };
+    /** The manager's `sessions`-role signer + the resolver that returns its matching anchor (the
+     *  manager self-signs and self-verifies its own offers). */
+    signer: {
+        keyId: string;
+        keyPair: {
+            sign(input: Uint8Array): Uint8Array;
+        };
+    };
+    resolveAnchor: AnchorResolver;
+    /** The DEDICATED sessions-bucket KV holding the `session.<id>` ledger rows (never the auth bucket). */
+    ledgerKv: KV;
+    /** The per-session SERVING credential seam: mint, gate-checked stage, connection open, revoke.
+     *  Injected because minting needs the space auth + the §13.1 gate, which live on the Manager. */
+    servingCredential: SessionServing;
+    /** Session lifetime (§13.6 live-class) + the bounded flow window. */
+    ttlMs: number;
+    window?: number;
+    /**
+     * Global ceiling on concurrently live sessions; defaults to {@link MAX_LIVE_SESSIONS_DEFAULT}.
+     *
+     * Redemption is caller-triggered and each session now mints a credential and opens a connection,
+     * so without a ceiling an authorized caller could drive both without bound. This is deliberately
+     * the plane's OWN bound rather than an inherited one: whatever route authz sits in front of
+     * establishment, the process-level resource limit is a number here that can be executed against.
+     *
+     * RESIDUAL, NAMED: the ceiling is GLOBAL, not per caller. It protects the process, which is what
+     * it is for, but it does not stop one authorized operator from exhausting it and denying sessions
+     * to another. That was accepted on the grounds that only authorized operators reach redemption at
+     * all — the attach face's console-token gate refuses before the establisher runs. If that gate is
+     * ever relaxed, weakened, or made optional, this scoping assumption goes with it and the ceiling
+     * needs a per-caller dimension.
+     */
+    maxSessions?: number;
+    now?(): number;
+}
+export declare class ManagerSessionPlane {
+    #private;
+    constructor(deps: ManagerSessionPlaneDeps);
+    /** Mint an offer for the authenticated attach caller, enforce its one-use redemption, and stand
+     *  up the PTY bridge — all atomically. Returns the HOLDER-BOUND grant (the attach reply): no URL,
+     *  and it must never be logged. Throws on a redeem refusal (a foreign presenter, an already-live
+     *  session, a stale serving epoch). */
+    establishAttach(caller: {
+        owner: string;
+        actor: string;
+        uid: string;
+    }, target: SessionTarget, session: AttachSession, 
+    /** A slot already claimed by an establisher in front of this one ({@link claimSlot}), so the
+     *  reservation covers ITS side effects too (the PTY attach above all). Omitted = claim here. */
+    claimed?: {
+        release(): void;
+    }): Promise<{
+        grant: SessionGrant;
+    }>;
+    /** End every session bound to a target incarnation, with a distinct reason — the despawn/restart
+     *  hook (the successor incarnation's differing epoch already refuses old-epoch redemptions; this
+     *  proactively tears the live bridges down and surfaces the reason to each client). The bridge's
+     *  own `onEnd` drives {@link #teardown}, so the connection and credential go with it. */
+    endForTarget(name: string, lifecycleUid: string, reason: AttachEndReason): void;
+    /** End all live sessions (manager stop / drain). */
+    endAll(reason: AttachEndReason): void;
+    /** Await every in-flight teardown (manager stop): the bridges' `onEnd` teardown is async, so a
+     *  synchronous `endAll` alone would let the process exit with connections still draining. */
+    drain(reason: AttachEndReason): Promise<void>;
+    get liveSessions(): number;
+    /** The configured global ceiling (surfaced so an operator-facing status can report it). */
+    get maxSessions(): number;
+    /**
+     * CLAIM a session slot, or refuse loudly. ONE implementation, called by {@link establishAttach}
+     * and by every establisher in front of it, so the two cannot drift into disagreeing about
+     * capacity. It must run before ANY of: minting the offer, redeeming it, minting a per-session
+     * credential on either side, opening a connection, or attaching the target's PTY.
+     *
+     * THIS RESERVES, IT DOES NOT MERELY CHECK. A bare read of the live count would be check-then-act:
+     * establishment awaits a mint, a redemption and a connection before the session becomes live, so
+     * two concurrent establishes at `max - 1` would both observe room, both mint credentials, and
+     * both land — overshooting the ceiling by exactly the concurrency the HTTP face already has, and
+     * over-minting the seed-signed credentials the ceiling exists to bound. Occupancy is therefore
+     * live sessions PLUS in-flight reservations, and the increment happens with no `await` between
+     * the read and the write, so on a single-threaded runtime no second establishment can interleave.
+     *
+     * The returned release is idempotent: the caller releases on every failure path, and
+     * {@link establishAttach} releases at the same instant it records the live session, so a slot is
+     * counted once and never twice.
+     *
+     * The message names the ceiling and its current value: an operator who hits it should not have to
+     * read source to learn which knob to raise.
+     */
+    claimSlot(): {
+        release(): void;
+    };
+}
+/** Open the DEDICATED sessions-bucket KV a plane's ledger needs (the `session.<id>` rows live in
+ *  the §13.6 session store — {@link sessionsBucket}, NOT the auth bucket). Split out so the manager
+ *  can build the plane from its own bucket handle. */
+export declare function openSessionLedgerKv(nc: NatsConnection, bucket: string): Promise<KV>;
+//# sourceMappingURL=plane.d.ts.map

package/dist/session/plane.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plane.d.ts","sourceRoot":"","sources":["../../src/session/plane.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AACtC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAKL,KAAK,cAAc,EACnB,KAAK,aAAa,EAElB,KAAK,YAAY,EACjB,KAAK,aAAa,EAGnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAiE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAExI,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAInD;;;;gGAIgG;AAChG,wBAAgB,sBAAsB,CAAC,EAAE,EAAE,EAAE,GAAG,aAAa,CA4C5D;AAED;;;kFAGkF;AAClF,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,MAAM,CAAC;IACd,6GAA6G;IAC7G,OAAO,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C;gEAC4D;IAC5D,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE;YAAE,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAAA;SAAE,CAAA;KAAE,CAAC;IAC5E,aAAa,EAAE,cAAc,CAAC;IAC9B,uGAAuG;IACvG,QAAQ,EAAE,EAAE,CAAC;IACb;qGACiG;IACjG,iBAAiB,EAAE,cAAc,CAAC;IAClC,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;;;;;;;;OAcG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,IAAI,MAAM,CAAC;CAChB;AAUD,qBAAa,mBAAmB;;gBASlB,IAAI,EAAE,uBAAuB;IAQzC;;;2CAGuC;IACjC,eAAe,CACnB,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EACrD,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,aAAa;IACtB;oGACgG;IAChG,OAAO,CAAC,EAAE;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE,GAC5B,OAAO,CAAC;QAAE,KAAK,EAAE,YAAY,CAAA;KAAE,CAAC;IA0HnC;;;6FAGyF;IACzF,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,IAAI;IAI/E,oDAAoD;IACpD,MAAM,CAAC,MAAM,EAAE,eAAe,GAAG,IAAI;IAIrC;iGAC6F;IACvF,KAAK,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED,2FAA2F;IAC3F,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,SAAS,IAAI;QAAE,OAAO,IAAI,IAAI,CAAA;KAAE;CAUjC;AAED;;sDAEsD;AACtD,wBAAsB,mBAAmB,CAAC,EAAE,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,EAAE,CAAC,CAEzF"}