looply-cli 0.0.0-stage → 0.2.0

package/dist/governed-broker.js

@@ -0,0 +1,196 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.outcomeOf = outcomeOf;
+exports.observationOf = observationOf;
+exports.fixtureEffectDir = fixtureEffectDir;
+exports.fixturePublishExecutor = fixturePublishExecutor;
+exports.createGovernedBroker = createGovernedBroker;
+const node_path_1 = require("node:path");
+const core_1 = require("@looply/core");
+const machine_store_1 = require("./machine-store");
+function outcomeOf(result) {
+    switch (result.kind) {
+        case 'success':
+            return 'success';
+        case 'failure':
+            return 'failure';
+        case 'ambiguous':
+            return 'ambiguous';
+    }
+}
+function observationOf(result) {
+    switch (result.kind) {
+        case 'observed-success':
+            return 'observed-success';
+        case 'observed-not-executed':
+            return 'observed-not-executed';
+        case 'observed-failure':
+            return 'observed-failure';
+        case 'ambiguous':
+            return 'ambiguous';
+    }
+}
+/* ------------------------------------------------------- the fixture effect */
+/**
+ * WHERE A BROKER-OWNED EFFECT LIVES.
+ *
+ * Under the machine's own Looply home, which is outside every project worktree
+ * and is one of the roots contained execution may never be granted. The
+ * contained tool worker confines every path to the project root — lexically and
+ * physically, resolving reparse points — so a model cannot read this, write it,
+ * or delete it, whatever it asks for.
+ *
+ * That is what makes the tests worth anything. A fixture effect written inside
+ * the repository would be an effect the thing under test can forge, and
+ * "exactly one effect happened" would be a claim about a file the model could
+ * have produced itself.
+ */
+function fixtureEffectDir(home) {
+    return (0, node_path_1.join)(home ?? (0, machine_store_1.machineHome)(), 'governed-fixture-effects');
+}
+/** What the effect IS, derived from the action rather than from the moment. */
+function effectOf(request) {
+    const a = request.action;
+    return `${request.type}:${String(a['target'])}:${String(a['artifact'])}:${String(a['revision'])}`;
+}
+/**
+ * The fixture executor for `fixture.publish`.
+ *
+ * Inert in the world and real on this machine: it produces a durable artifact
+ * outside the model's reach, which is exactly the property a real executor will
+ * need and the only one the tests can check independently.
+ */
+function fixturePublishExecutor(deps) {
+    const dir = fixtureEffectDir(deps.home);
+    const path = (executionId) => (0, node_path_1.join)(dir, `${executionId}.json`);
+    const read = async (executionId) => {
+        const text = await deps.fs.readFile(path(executionId));
+        if (text === null)
+            return null;
+        try {
+            const parsed = JSON.parse(text);
+            return typeof parsed?.executionId === 'string' ? parsed : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    return {
+        type: 'fixture.publish',
+        async execute(env) {
+            const record = {
+                executionId: env.executionId,
+                approvalId: env.approvalId,
+                claimId: env.claimId,
+                actionFingerprint: env.actionFingerprint,
+                effect: effectOf(env.actionRequest),
+                at: new Date(deps.now?.() ?? Date.now()).toISOString(),
+            };
+            await deps.fs.mkdir(dir);
+            try {
+                if (deps.attempt)
+                    await deps.attempt(record);
+                await deps.fs.createExclusive(path(env.executionId), JSON.stringify(record, null, 2) + '\n');
+            }
+            catch (e) {
+                if (e.code === 'EEXIST') {
+                    // THIS EXECUTION HAS ALREADY HAPPENED. Not a failure and not a second
+                    // effect: the same id was attempted twice and the filesystem refused
+                    // the second, which is the answer rather than an error.
+                    const held = await read(env.executionId);
+                    if (held === null) {
+                        const unreadable = {
+                            kind: 'ambiguous',
+                            safeReason: 'the effect exists and cannot be read',
+                            evidence: {},
+                        };
+                        return unreadable;
+                    }
+                    const already = {
+                        kind: 'success',
+                        evidence: { effect: held.effect, at: held.at },
+                    };
+                    return already;
+                }
+                // ANYTHING ELSE IS AMBIGUOUS, NOT A FAILURE. The write may have landed
+                // and the acknowledgement may have been what was lost.
+                return {
+                    kind: 'ambiguous',
+                    safeReason: `the effect could not be confirmed (${e.message})`,
+                    evidence: {},
+                };
+            }
+            return { kind: 'success', evidence: { effect: record.effect, at: record.at } };
+        },
+        async reconcile(env) {
+            let held;
+            try {
+                held = await read(env.executionId);
+            }
+            catch (e) {
+                return { kind: 'ambiguous', safeReason: `the effect could not be read (${e.message})` };
+            }
+            if (held === null) {
+                // Looked, and there is nothing. The one arm that permits the same
+                // execution id to be attempted again.
+                return { kind: 'observed-not-executed' };
+            }
+            if (held.actionFingerprint !== env.actionFingerprint) {
+                // Something is there under this execution id and it is not this action.
+                // Not a success and certainly not a licence to write another.
+                return { kind: 'ambiguous', safeReason: 'the recorded effect is for a different action' };
+            }
+            return { kind: 'observed-success', evidence: { effect: held.effect, at: held.at } };
+        },
+    };
+}
+/* ------------------------------------------------------------- the broker */
+/**
+ * Route an envelope to the executor for its action, or refuse it.
+ *
+ * FAILS CLOSED THREE TIMES OVER. The action type must be one Looply has
+ * registered, it must classify as consequential, and the stored request must
+ * still verify against its own fingerprint. An unregistered type is refused
+ * rather than assumed harmless — that is the branch that stops a tool added
+ * next year from executing simply because nothing has classified it yet.
+ *
+ * A refusal here is `failure`, not `ambiguous`, and that is correct rather than
+ * convenient: nothing was attempted, so no effect can exist, and saying so
+ * definitely is what lets the pursuit plan around it instead of holding.
+ */
+function createGovernedBroker(executors) {
+    const byType = new Map(executors.map((e) => [e.type, e]));
+    const refuse = (why) => ({ kind: 'failure', safeReason: why, evidence: {} });
+    const executorFor = (env) => {
+        if (!(0, core_1.isActionType)(env.actionType))
+            return `no such action: ${String(env.actionType)}`;
+        if ((0, core_1.classifyAction)(env.actionType) !== 'consequential') {
+            return `${env.actionType} is not a consequential action`;
+        }
+        if (env.actionRequest.fingerprint !== env.actionFingerprint) {
+            return 'the action does not match the fingerprint this execution is for';
+        }
+        if (!(0, core_1.verifyActionRequest)(env.actionRequest)) {
+            return 'the action did not survive its own fingerprint check';
+        }
+        const executor = byType.get(env.actionType);
+        return executor ?? `nothing here can carry out ${env.actionType}`;
+    };
+    return {
+        async execute(env) {
+            const found = executorFor(env);
+            if (typeof found === 'string')
+                return refuse(found);
+            return found.execute(env);
+        },
+        async reconcile(env) {
+            const found = executorFor(env);
+            if (typeof found === 'string') {
+                // Nothing could have run it, so nothing can have happened.
+                return { kind: 'observed-not-executed' };
+            }
+            return found.reconcile(env);
+        },
+    };
+}
+//# sourceMappingURL=governed-broker.js.map

package/dist/governed-broker.js.map

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

package/dist/governed-run.d.ts

@@ -0,0 +1,220 @@
+import type { ServerApprovalRow, ServerExecution, ServerExecutionEnvelope } from './server-client';
+import { type GovernedApprovals } from './governed-approvals';
+import { type BrokerEvidence, type GovernedActionBroker } from './governed-broker';
+import { type BrokerOutcome } from '@looply/core';
+import { type PublishPolicy } from './config';
+/**
+ * TURNING ONE PERSON'S YES INTO ONE THING ACTUALLY HAPPENING.
+ *
+ * This runs BEFORE any model reasoning, and that ordering is the product
+ * decision it exists for. If a model asked to publish an artifact and somebody
+ * approved it, the next run should not open by asking the model what it would
+ * like to do — the exact thing a person authorised is already known, and the
+ * only honest first act is to do it.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * IT LIVES HERE RATHER THAN IN `run-cmd` ON PURPOSE
+ *
+ * A guard written at 7B4-B asserts that the stopping path — `run-approval`,
+ * `round-runner`, `pending-action` and `run-cmd` — contains no claim
+ * vocabulary at all. That guard is still right and still passing, and this
+ * module is why: every word about claims, execution ids and fingerprints is in
+ * here, and the composition root calls one function and reads a typed answer.
+ * A prehook inlined into `run-cmd` would have meant deleting the guard.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * ARGV IS TRANSPORT AND NEVER AUTHORITY
+ *
+ * The run is told an approval id on its command line. That, alone, proves
+ * nothing: anybody who can type can type an id. What makes it authority is a
+ * durable chain the daemon wrote before this process existed —
+ *
+ *     explicit Start command C
+ *       → the Start gate reserves the approval under `requestId = C.id`
+ *       → the daemon spawns the run with `--command-id C.id`
+ *       → this checks that the reservation names THIS run's Start
+ *
+ * — so `looply run --governed-approval apv_x` typed at a terminal reaches
+ * nothing. There is no reservation naming its Start, and there is no way for
+ * this module to make one.
+ *
+ * THE HONEST LIMIT: somebody with a shell on this machine already holds the
+ * machine credential and could read the reservation to copy a request id. That
+ * is not the boundary being defended. The boundary is the MODEL, which cannot
+ * reach `.looply/state` at all, cannot spawn a run, and cannot see this file.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * AND IT LOOKS BEFORE IT ACTS, EVERY TIME
+ *
+ * `reconcile` runs before `execute`, unconditionally — not only after a crash,
+ * because a process cannot know it is the one that crashed. That single
+ * ordering closes both dangerous windows at once: an execution recorded but not
+ * attempted, and an effect produced whose result was never written. The only
+ * observation that permits acting is the one that says nothing happened.
+ */
+/** What the run is told about a governed action that has been carried out. */
+export interface GovernedActionResultContext {
+    readonly approvalId: string;
+    readonly executionId: string;
+    readonly actionType: string;
+    readonly actionFingerprint: string;
+    readonly outcome: 'succeeded' | 'failed';
+    /** The one line the person was shown, from the server's own formatter. */
+    readonly display: string;
+    readonly safeEvidence: BrokerEvidence;
+}
+export type GovernedOutcome = 
+/** Nothing governed was asked of this run. Carry on as an ordinary run. */
+{
+    readonly kind: 'none';
+}
+/** It was carried out and this run owns the answer. Reasoning may continue. */
+ | {
+    readonly kind: 'done';
+    readonly result: GovernedActionResultContext;
+}
+/**
+ * The run must stop, and the pursuit stays alive.
+ *
+ * `ambiguous` is the case this exists for: nobody can say whether the effect
+ * happened, so there is nothing to tell a model and nothing safe to retry.
+ */
+ | {
+    readonly kind: 'stop';
+    readonly because: string;
+}
+/**
+ * Nothing was attempted and nothing may be. A plain failure, not a refusal
+ * code: every `RunRefusalCode` is terminal, and ending a person's grant
+ * because a governed step could not start would be the wrong answer.
+ */
+ | {
+    readonly kind: 'refused';
+    readonly because: string;
+};
+/** The client surface this needs. Injected so a test can fail any single call. */
+export interface GovernedServer {
+    projectApproval(projectId: string, approvalId: string): Promise<ServerApprovalRow>;
+    claimApproval(projectId: string, approvalId: string, input: {
+        claimRef: string;
+        expectedFingerprint: string;
+        expectedVersion: number;
+    }): Promise<ServerApprovalRow & {
+        claimId: string | null;
+        version: number;
+    }>;
+    beginExecution(projectId: string, approvalId: string, input: {
+        claimId: string;
+        expectedFingerprint: string;
+    }): Promise<ServerExecutionEnvelope>;
+    settleExecution(projectId: string, executionId: string, input: {
+        claimId: string;
+        expectedVersion: number;
+        expectedFingerprint: string;
+        outcome: BrokerOutcome;
+        reason?: string;
+        evidence?: BrokerEvidence;
+    }): Promise<ServerExecution>;
+    assignExecutionResult(projectId: string, executionId: string, runId: string): Promise<ServerExecution>;
+    acknowledgeExecutionResult(projectId: string, executionId: string, runId: string): Promise<ServerExecution>;
+}
+/**
+ * The governed surface, narrowed out of the full client.
+ *
+ * BUILT HERE RATHER THAN AT THE CALL SITE, and that is not tidiness. The
+ * composition root is on a list of files asserted to contain no claim
+ * vocabulary at all, and writing these six lines there would put the words back
+ * into exactly the file the guard exists to keep clean. It also keeps the
+ * narrowing discipline `openGoalServer` already follows: the client itself
+ * never leaves the function that made it.
+ */
+export declare function governedServerOf(client: {
+    projectApproval: GovernedServer['projectApproval'];
+    claimApproval: GovernedServer['claimApproval'];
+    beginExecution: GovernedServer['beginExecution'];
+    settleExecution: GovernedServer['settleExecution'];
+    assignExecutionResult: GovernedServer['assignExecutionResult'];
+    acknowledgeExecutionResult: GovernedServer['acknowledgeExecutionResult'];
+}): GovernedServer;
+export interface GovernedRunDeps {
+    readonly server: GovernedServer;
+    readonly broker: GovernedActionBroker;
+    readonly reservations: Pick<GovernedApprovals, 'reservationOf'>;
+    readonly log?: (line: string) => void;
+}
+export interface GovernedRunInput {
+    readonly projectId: string;
+    readonly goalId: string;
+    readonly goalVersion: number;
+    readonly runId: string;
+    /** The Start that spawned this run, from the trusted daemon-to-child wire. */
+    readonly commandId: string | undefined;
+    /** What argv said. Proves nothing on its own. */
+    readonly approvalId: string;
+    /**
+     * Whether this project permits Looply to publish. Absent means it does not.
+     *
+     * A PRE-CLAIM PREDICATE, like expiry and goal context — and for exactly the
+     * same reason they are. Before a claim it decides whether authority may be
+     * TAKEN, and a project that has turned publishing off is entitled to stop an
+     * approval it granted yesterday from being acted on today.
+     *
+     * After a claim it decides NOTHING. The machine holding one may already be
+     * between the claim and the push, and a policy flipped in that window cannot
+     * reach back through it — refusing there would strand authority legitimately
+     * taken, with an effect possibly already in the world and nothing able to
+     * record it. That is the dead claim C1 exists to prevent, and a standing
+     * setting is no more entitled to create one than a passing clock is.
+     */
+    readonly publishPolicy?: PublishPolicy;
+}
+export declare function runGovernedAction(deps: GovernedRunDeps, input: GovernedRunInput): Promise<GovernedOutcome>;
+/**
+ * What a resumed model is told, as plain lines.
+ *
+ * PROSE, AND DELIBERATELY NOT JSON, for the reason `describeResolution` gives:
+ * the implementer's transcript is scanned for a structured declaration and the
+ * scan takes the FIRST one it finds, so a prompt containing something shaped
+ * like a request is a decoy an echoing model files for real.
+ */
+/**
+ * WHAT A GUARANTEE RESTS ON, SAID BESIDE THE GUARANTEE (the audit’s H-06).
+ *
+ * 🔴 THE TWO ARMS OF THIS SENTENCE DISAGREED ABOUT SCOPE. The failure arm says
+ * "nothing was changed outside this machine" and scopes itself; the success arm
+ * said "it happened exactly once" and named nothing — and the success arm is the
+ * one a model acts on, because it ends "do not ask for it a second time".
+ *
+ * ⚠️ AND WHAT MAKES IT TRUE IS NOT THIS MACHINE. The audit reads the fixture
+ * executor's `createExclusive` and calls exactly-once local, which invites the
+ * conclusion that two machines could each do it once. They cannot: a claim by a
+ * second machine is refused by the server with `already_claimed`, behind a
+ * unique index, and its idempotent arm is reached only by the same machine under
+ * its own key. Two fences at two layers — the server stops a second MACHINE, the
+ * executor's own record stops the same machine doing it twice.
+ *
+ * ⚠️ IT CLAIMS NO MORE THAN THAT. It does not say the effect was verified against
+ * a remote — only `git.push` can say that, and it says it in its own evidence —
+ * and it promises nothing about a machine that never claimed.
+ */
+export declare const EVIDENCE_MAX_LINES = 6;
+/** Bound on one value, for the reason every free field on a prompt has one. */
+export declare const EVIDENCE_MAX_CHARS = 120;
+/**
+ * The broker's own evidence, as lines in the shape this block already uses.
+ *
+ * 🔴 CARRIED HERE SINCE IT WAS WRITTEN AND READ BY NOTHING. `safeEvidence` is
+ * declared on the context, populated where the result is taken up, and shown by
+ * nobody — while for `git.push` it holds `remote`, `ref`, `sha` and the
+ * `observedSha` the executor actually read back: the observation that makes
+ * "exactly once" checkable rather than believable. Its own type calls it
+ * "bounded, deterministic where possible, and never secret".
+ *
+ * ⚠️ LINES, NEVER JSON. The block's own rule: the transcript is scanned for a
+ * structured declaration and the scan takes the first one it finds, so anything
+ * here shaped like a request is a decoy an echoing model files for real. This
+ * uses the same `  key : value` shape as the two lines above it and no other.
+ */
+export declare function evidenceLines(e: BrokerEvidence): string[];
+export declare function describeGovernedResult(r: GovernedActionResultContext): string;
+//# sourceMappingURL=governed-run.d.ts.map

package/dist/governed-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governed-run.d.ts","sourceRoot":"","sources":["../src/governed-run.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iBAAiB,EACjB,eAAe,EACf,uBAAuB,EACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,oBAAoB,EAE1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAKL,KAAK,aAAa,EACnB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAc,KAAK,aAAa,EAAE,MAAM,UAAU,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAEH,8EAA8E;AAC9E,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,CAAC;IACzC,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC;CACvC;AAED,MAAM,MAAM,eAAe;AACzB,2EAA2E;AACzE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE;AAC3B,+EAA+E;GAC7E;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAA;CAAE;AACzE;;;;;GAKG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE;AACrD;;;;GAIG;GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;IACnF,aAAa,CACX,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,GAChF,OAAO,CAAC,iBAAiB,GAAG;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5E,cAAc,CACZ,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,mBAAmB,EAAE,MAAM,CAAA;KAAE,GACtD,OAAO,CAAC,uBAAuB,CAAC,CAAC;IACpC,eAAe,CACb,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,eAAe,EAAE,MAAM,CAAC;QACxB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,OAAO,EAAE,aAAa,CAAC;QACvB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,cAAc,CAAC;KAC3B,GACA,OAAO,CAAC,eAAe,CAAC,CAAC;IAC5B,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACvG,0BAA0B,CACxB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,eAAe,CAAC,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,eAAe,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IACnD,aAAa,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;IAC/C,cAAc,EAAE,cAAc,CAAC,gBAAgB,CAAC,CAAC;IACjD,eAAe,EAAE,cAAc,CAAC,iBAAiB,CAAC,CAAC;IACnD,qBAAqB,EAAE,cAAc,CAAC,uBAAuB,CAAC,CAAC;IAC/D,0BAA0B,EAAE,cAAc,CAAC,4BAA4B,CAAC,CAAC;CAC1E,GAAG,cAAc,CASjB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,IAAI,CAAC,iBAAiB,EAAE,eAAe,CAAC,CAAC;IAChE,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8EAA8E;IAC9E,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,iDAAiD;IACjD,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAC;CACxC;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,eAAe,CAAC,CA0P1B;AAkCD;;;;;;;GAOG;AACH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,kBAAkB,IAAI,CAAC;AACpC,+EAA+E;AAC/E,eAAO,MAAM,kBAAkB,MAAM,CAAC;AAEtC;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,cAAc,GAAG,MAAM,EAAE,CAezD;AAED,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,2BAA2B,GAAG,MAAM,CA+B7E"}