pi-daddy 0.27.4 → 0.32.0

package/dist/kernel/resolve.js

@@ -0,0 +1,201 @@
+/**
+ * Grant resolution — the entire security surface of capability governance, as a pure function.
+ *
+ * The invariant (ADR-0008): a capability set may only ever SHRINK as it passes down a delegation
+ * tree. Escalation is impossible by construction rather than by policy, because a parent can never
+ * confer what it does not itself hold.
+ *
+ *   effective = ( requested ∩ parentGrant ∩ ceiling ) \ (gated \ approved)
+ *
+ * Being pure — no I/O, no model, no network — this is exhaustively testable, which matters because it
+ * is the only place an escalation could be introduced.
+ */
+/**
+ * Capabilities that transitively confer everything else. Granting one is equivalent to granting the
+ * whole catalog, so they can never be a *narrowing* grant.
+ *
+ * `ext:pi-fabric/fabric_exec` is here on measured evidence, not suspicion: a child granted
+ * `tools: []` (nothing at all) plus `recursive: true` still reached `pi.write` and `pi.bash` and
+ * spawned a grandchild that wrote to disk. See docs/probes/pi-fabric-eval (probes 2, 4, 7, 8).
+ */
+export const UNIVERSAL_CAPABILITIES = ["ext:pi-fabric/fabric_exec", "tool:fabric_exec"];
+/**
+ * Capabilities that functionally contain others.
+ *
+ * `bash` can run `grep`, `find`, `ls`, `cat`, and `sed` — so a session holding it can already do
+ * everything the file and search tools do, whatever the tool list says. Modelling this explicitly serves
+ * two purposes:
+ *
+ *  1. It removes false escalation reports. pi's *default* surface is only `read`, `bash`, `edit`, `write`
+ *     (measured, not assumed), so an agent type declaring `tools: read, grep, find, ls` would otherwise
+ *     look like an escalation from any normal parent — despite being strictly weaker.
+ *  2. It makes the uncomfortable truth visible rather than implied: **a grant containing `bash` is not a
+ *     narrow grant.** `subsumedBy` in the result says so, so a reviewer can see what the grant really means.
+ */
+export const SUBSUMPTION = {
+    "tool:bash": ["tool:grep", "tool:find", "tool:ls", "tool:read", "tool:write", "tool:edit", "tool:edit-diff"],
+};
+/** Expand a grant to everything it functionally confers. */
+export function expandSubsumed(grant) {
+    const expanded = new Set(grant);
+    for (const held of grant) {
+        for (const implied of SUBSUMPTION[held] ?? [])
+            expanded.add(implied);
+    }
+    return [...expanded].sort();
+}
+import { WILDCARD } from "./pi-tools.js";
+import { isWellFormedCapability } from "./capabilities.js";
+/**
+ * "Any definition" — ADR-0023, and one of two wildcards this module understands.
+ *
+ * Declared here rather than beside `WILDCARD` because `pi-tools.ts` imports `Capability` from this module.
+ * That import is `import type`, so it is erased and the runtime dependency runs one way only — which is
+ * what makes importing `WILDCARD` back safe.
+ *
+ * Deliberately weaker than `tool:*`: it confers **no tool authority**, so `agent:*,tool:read` may spawn
+ * every definition on disk and hand each of them nothing but `read`. It exists because the alternative was
+ * `tool:*` — authority to grant every tool — which made the safe configuration the laborious one.
+ */
+export const AGENT_WILDCARD = "agent:*";
+/**
+ * `workspace:*` covers any `workspace:<id>` — ADR-0035, and the second namespace wildcard.
+ *
+ * Added as a deliberate edit, which is what the comment in `resolve()` below asks for: there is no
+ * generalised `<ns>:*` rule, so a namespace does not acquire a wildcard by existing. Unlike `agent:*` this
+ * one is **not inheritable** (`childEnv` strips it) — R-26's rule, because a root that handed
+ * `workspace:*` down would make routing attenuation meaningless below the root, which is the exact defect
+ * R-131 records.
+ */
+export const WORKSPACE_WILDCARD = "workspace:*";
+const unique = (xs) => [...new Set(xs)].sort();
+/**
+ * Resolve a child's grant. Total and side-effect free; every rejected capability is reported rather
+ * than silently dropped, because a grant nobody can audit proves nothing.
+ */
+export function resolve(input) {
+    const requested = unique(input.requested);
+    const held = new Set(input.parentGrant);
+    const parent = input.subsumption === false ? held : new Set(expandSubsumed(input.parentGrant));
+    /**
+     * `agent:*` covers any `agent:<name>` — ADR-0023. It was the only wildcard rule in this function when
+     * that was written; ADR-0035 added a third, so `covered()` now has `tool:*`, `agent:*` and `workspace:*`.
+     * There is still no GENERALISED `<ns>:*` rule: each is a deliberate edit, which is the property worth
+     * keeping. Corrected because the sentence sat eighty lines above "all THREE wildcards are excluded".
+     *
+     * `resolve` is otherwise exact-match plus subsumption, deliberately: `tool:*` works not because anything
+     * here understands it, but because `deriveOwnGrant` *enumerates* a session's observed tool names beside
+     * it. Definitions are not tools, so nothing enumerates them — which is why `maySpawnDefinition` had to
+     * special-case the wildcard, and why this needs stating rather than falling out.
+     *
+     * Scoped to one namespace on purpose. There is no generalised `<ns>:*` rule, so a namespace added later
+     * does not silently acquire a wildcard; adding one is a deliberate edit and another decision.
+     */
+    const anyDefinition = held.has(AGENT_WILDCARD);
+    /**
+     * `tool:*` satisfies **any** capability, including `skill:` and `agent:` ids.
+     *
+     * Missing until 0.11.2, and the omission broke the one rule this package must never break by accident:
+     * *governance is opt-in*. An ungoverned session holds `[tool:*, …observed tools]` and nothing else, so
+     * spawning a definition whose `allowed-tools` names `agent:worker` or `skill:review` — the composition
+     * ADR-0017 created and ADR-0023's own example uses — was refused with **"capability escalation
+     * blocked"**, and recorded as an escalation attempt, in a session that had opted out.
+     *
+     * `maySpawnDefinition` had always honoured `tool:*` for definition ids and `docs/SPEC.md` had always
+     * claimed it "satisfies any capability". This function disagreed with both, which is R-28's shape: two
+     * spellings of one rule, and the enforcing one was wrong.
+     */
+    const anyCapability = held.has(WILDCARD);
+    const anyWorkspace = held.has(WORKSPACE_WILDCARD);
+    // A malformed id is never covered — not by an exact hold, and above all not by a wildcard's PREFIX rule,
+    // which is how `agent:x,tool:bash` got admitted and then split into two capabilities in the child.
+    // Landing in `denied` is the right outcome rather than a throw: it fails closed AND records an
+    // escalation attempt, so the ledger shows the attempt instead of a clean line.
+    const covered = (c) => isWellFormedCapability(c) &&
+        (parent.has(c) ||
+            anyCapability ||
+            (anyDefinition && c.startsWith("agent:")) ||
+            (anyWorkspace && c.startsWith("workspace:")));
+    const ceiling = input.ceiling === undefined ? null : new Set(input.ceiling);
+    const gated = new Set(input.gated ?? []);
+    const approved = new Set(input.approved ?? []);
+    // Order is irrelevant to the outcome (set intersection is commutative), so each rejection reason is
+    // reported independently rather than being masked by whichever filter happened to run first.
+    const denied = requested.filter((c) => !covered(c));
+    const clipped = requested.filter((c) => covered(c) && ceiling !== null && !ceiling.has(c));
+    /**
+     * Is this capability gated, directly or by subsuming something gated?
+     *
+     * ADR-0012. Exact-name gating was defeatable by handing down a broader capability: the package's own
+     * `SUBSUMPTION` table says `bash` confers `write`, so gating `write` produced **no prompt** when `bash`
+     * was granted instead. The gate read as satisfied because the string never appeared.
+     *
+     * The direction is load-bearing and easy to invert. A capability is gated when it **subsumes**
+     * something gated — never when it **is subsumed by** something gated. Gating `bash` must not quietly
+     * gate a plain `write` grant, which would make gating a broad capability restrict the narrow ones and
+     * invert least privilege.
+     */
+    const isGated = (c) => {
+        if (gated.has(c))
+            return true;
+        if (input.subsumption === false)
+            return false;
+        return (SUBSUMPTION[c] ?? []).some((implied) => gated.has(implied));
+    };
+    const gatedBlocked = requested.filter((c) => covered(c) && (ceiling === null || ceiling.has(c)) && isGated(c) && !approved.has(c));
+    const rejected = new Set([...denied, ...clipped, ...gatedBlocked]);
+    const effective = requested.filter((c) => !rejected.has(c));
+    return {
+        effective,
+        denied,
+        clipped,
+        gatedBlocked,
+        universal: effective.filter((c) => UNIVERSAL_CAPABILITIES.includes(c)),
+        // F9: capabilities covered by a WILDCARD are not "subsumed" — this field means "the grant is broader
+        // than its list suggests", which is the `bash`-covers-`grep` warning. A wildcard holder already knows
+        // its grant is broad; listing every id under it would bury the signal the field exists to carry.
+        //
+        // All THREE wildcards are excluded. `anyWorkspace` was missing, so a caller holding `workspace:*` saw
+        // its own `workspace:prod` reported as subsumed while the `agent:*` holder correctly saw nothing — the
+        // field contradicting its own rule, and a false "broader than it looks" flag in the ledger and in
+        // `/grants`. Every wildcard added to `covered()` above needs a line here; that is now three for three.
+        subsumedBy: effective.filter((c) => !held.has(c) &&
+            !anyCapability &&
+            !(anyDefinition && c.startsWith("agent:")) &&
+            !(anyWorkspace && c.startsWith("workspace:"))),
+    };
+}
+/**
+ * Fail closed on a grant that cannot actually narrow anything.
+ *
+ * A universal capability in an "attenuated" grant is not a narrow grant with one extra item — it is
+ * full authority wearing a narrow grant's clothing. Callers must opt in explicitly rather than
+ * discover this at runtime.
+ */
+export function assertNarrowing(result, allowUniversal = false) {
+    if (!allowUniversal && result.universal.length > 0) {
+        throw new Error(`refusing to issue a grant containing universal capabilities: ${result.universal.join(", ")}. ` +
+            `These transitively confer the whole catalog, so the grant would not narrow anything. ` +
+            `Pass allowUniversal to override deliberately.`);
+    }
+}
+/**
+ * Project an effective grant onto pi's `--tools` allowlist.
+ *
+ * pi core is the enforcement point — verified: `--tools` and `--no-tools` both hard-block extension
+ * tools, and an explicitly `-e`-loaded extension cannot re-add its tool past them
+ * (docs/probes/pi-fabric-eval probes 9–11). That is why enforcement needs no in-descendant runtime.
+ *
+ * Returns `null` when the grant contains no callable tools, meaning the caller should pass
+ * `--no-tools` rather than an empty `--tools` (an empty list is not a valid allowlist).
+ */
+export function toPiToolsAllowlist(effective) {
+    const names = effective
+        .filter((c) => c.startsWith("tool:") || c.startsWith("ext:"))
+        // `tool:read` -> `read`; `ext:pkg/web_search` -> `web_search` (pi matches on bare tool name)
+        .map((c) => (c.startsWith("tool:") ? c.slice(5) : c.slice(c.lastIndexOf("/") + 1)))
+        .filter((n) => n.length > 0);
+    const deduped = [...new Set(names)].sort();
+    return deduped.length > 0 ? deduped : null;
+}
+//# sourceMappingURL=resolve.js.map

package/dist/kernel/resolve.js.map

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

package/dist/kernel/routing-authority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-authority.d.ts","sourceRoot":"","sources":["../../src/kernel/routing-authority.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAsB,KAAK,UAAU,EAAE,MAAM,cAAc,CAAC;AAEnE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,qBAAqB,CACnC,gBAAgB,EAAE,MAAM,GAAG,SAAS,EACpC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAC9B,cAAc,GAAG,IAAI,CA6BvB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,SAAS,UAAU,EAAE,EAChC,QAAQ,EAAE,SAAS,UAAU,EAAE,GAC9B,cAAc,GAAG,IAAI,CAUvB"}

package/dist/kernel/routing-authority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-authority.js","sourceRoot":"","sources":["../../src/kernel/routing-authority.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAChG,OAAO,EAAE,kBAAkB,EAAmB,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAgBzC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,qBAAqB,CACnC,gBAAoC,EACpC,QAA+B;IAE/B,IAAI,gBAAgB,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAChD,MAAM,WAAW,GAAG,mBAAmB,CAAC,gBAAgB,CAAC,CAAC;IAC1D,IAAI,CAAC,iBAAiB,CAAC,gBAAgB,CAAC,EAAE,CAAC;QACzC,OAAO;YACL,IAAI,EAAE,oBAAoB;YAC1B,MAAM,EACJ,gBAAgB,IAAI,CAAC,SAAS,CAAC,gBAAgB,CAAC,+CAA+C;gBAC/F,UAAU,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,8DAA8D;gBACnG,mGAAmG;SACtG,CAAC;IACJ,CAAC;IACD,IAAI,mBAAmB,CAAC,QAAQ,EAAE,gBAAgB,CAAC;QAAE,OAAO,IAAI,CAAC;IACjE,8FAA8F;IAC9F,oFAAoF;IACpF,MAAM,IAAI,GAAG,QAAQ;SAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,YAAY,CAAC,IAAI,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;SAC5F,IAAI,EAAE,CAAC;IACV,OAAO;QACL,IAAI,EAAE,0BAA0B;QAChC,sGAAsG;QACtG,kFAAkF;QAClF,MAAM,EAAE,CAAC,WAAW,CAAC;QACrB,MAAM,EACJ,sCAAsC,gBAAgB,kCAAkC,WAAW,IAAI;YACvG,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC;gBACd,CAAC,CAAC,oBAAoB,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG;gBACxC,CAAC,CAAC,4CAA4C,WAAW,kCAAkC,CAAC;KACjG,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,6BAA6B,CAC3C,SAAgC,EAChC,QAA+B;IAE/B,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,QAAQ,CAAC;QAAE,OAAO,IAAI,CAAC;IACxF,OAAO;QACL,IAAI,EAAE,oBAAoB;QAC1B,MAAM,EACJ,gBAAgB,kBAAkB,kEAAkE;YACpG,oGAAoG;YACpG,mFAAmF;KACtF,CAAC;AACJ,CAAC"}

package/dist/kernel/run-child.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Run a governed child process under hard limits.
+ *
+ * G8 (review findings A-R1/B-I5, A-R3). `delegate` used to spawn `pi` with no output cap, no timeout,
+ * an abort listener attached too late to observe an already-aborted signal, and a non-zero exit reported
+ * to the model as an ordinary result. Each of those is a way for a child to outlive or overwhelm the
+ * orchestrator that is supposed to be governing it — which is the whole premise of this package.
+ *
+ * It lives here, out of `extensions/grants.ts`, so it can be tested against real processes without pi.
+ */
+export { ENV_CHILD_IDLE_TIMEOUT, ENV_CHILD_TIMEOUT } from "./env-names.ts";
+/**
+ * The longest prefix of `text` that fits in `budget` BYTES, never splitting a character.
+ *
+ * Both halves matter. Truncating by `String.prototype.slice` counts UTF-16 code units against a byte budget,
+ * which overruns by the encoding width of whatever the child printed. Truncating the *buffer* instead would
+ * respect the budget and split a multi-byte character or a surrogate pair, putting a lone `\ud83d` in the
+ * result. So the walk is by code POINT (`for…of` iterates code points, keeping surrogate pairs whole) and the
+ * budget is checked in bytes before each one is admitted.
+ *
+ * Exported for the test that feeds it CJK and emoji: an ASCII-only test cannot fail on any of this, which is
+ * exactly why the original defect survived a test named for it.
+ */
+export declare function takeBytes(text: string, budget: number): string;
+/**
+ * Operator override for the child wall-clock limit, in seconds.
+ *
+ * Deliberately NOT in `GRANT_ENV_KEYS`: those are stripped from a child's environment and re-supplied
+ * only by the spawn plan, which is right for capability state and wrong for an operator preference. This
+ * one should simply inherit, so a bound set at the root applies all the way down.
+ */
+/** Read the override, falling back to the default on absent *or* malformed input (G7's rule). */
+export declare function timeoutFromEnv(raw: string | undefined): number;
+/** The inactivity bound, same rule: absent, malformed and zero all select the default rather than disabling it. */
+export declare function idleTimeoutFromEnv(raw: string | undefined): number;
+export interface ChildRunRequest {
+    command: string;
+    args: string[];
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    signal?: AbortSignal;
+    /** Hard cap on captured output. Beyond it the child is killed and the result flagged. */
+    maxOutputBytes?: number;
+    /** Wall-clock ceiling. On expiry: SIGTERM, then SIGKILL after `killGraceMs`. A runaway bound, not the working bound. */
+    timeoutMs?: number;
+    killGraceMs?: number;
+    /**
+     * Inactivity bound (ADR-0038 note, PR 3e): the child is stopped when this long passes with no activity. Activity
+     * is any stdout/stderr byte, or a change in what `activityProbe` returns. Undefined means no inactivity bound.
+     */
+    idleTimeoutMs?: number;
+    /**
+     * A cheap marker of the child's progress that is not on its stdout, polled every `activityProbeIntervalMs`: the
+     * size and mtime of its pi session file, which pi appends to on every message and tool result. A change resets
+     * the inactivity clock; `undefined` (file not there yet) counts as no change. Never awaited on the control path.
+     */
+    activityProbe?: () => Promise<string | number | undefined> | string | number | undefined;
+    activityProbeIntervalMs?: number;
+    /** Absolute epoch-millisecond hard cap: SIGKILL fires here even when the SIGTERM grace has not elapsed. */
+    hardDeadlineAt?: number;
+    /**
+     * Called with each chunk as it arrives, for the parent's progress display (ADR-0032).
+     *
+     * **Display only, and the distinction is load-bearing.** The child's answer is still `text`, assembled here
+     * and returned; a caller must never treat what it saw streamed as the result. A partial stream that could be
+     * mistaken for a complete answer is R-03's defect — a missing result indistinguishable from an empty one —
+     * with a new cause.
+     *
+     * Bounded by the same `maxOutputBytes` as `text`, so the cap governs the transcript and not merely memory.
+     *
+     * Exceptions are swallowed: a renderer is not a governance control, and one that throws must not kill a
+     * governed child mid-task.
+     */
+    onOutput?: (chunk: string) => void;
+    /** Optional raw observation; isolated from control, never awaited, separate from display text. */
+    onObservation?: (stream: "stdout" | "stderr", bytes: Uint8Array) => void;
+    /** Passive EOF observation. Never a replacement child/settlement handle. Exceptions are isolated. */
+    onStreamEnd?: (stream: "stdout" | "stderr") => void;
+    /** Security hook called immediately after spawn, before output handling (for lease attachment). */
+    onSpawn?: (pid: number) => void;
+}
+export interface ChildRunResult {
+    /** Exit code, or `null` when nothing was spawned or the child was killed by a signal. */
+    code: number | null;
+    text: string;
+    truncated: boolean;
+    timedOut: boolean;
+    /** Set with `timedOut` when it was the inactivity bound, not the wall-clock ceiling, that stopped the child. */
+    idle?: true;
+    aborted: boolean;
+    /** Signal that ended the process, separate from the nullable numeric exit code. */
+    signal?: NodeJS.Signals | null;
+    /** Set when the process could not be started at all. */
+    spawnError?: string;
+}
+/** 1 MiB. A delegation returns a summary; anything larger is a runaway, not an answer. */
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+/**
+ * Six hours (PR 3e, 2026-09-22). No longer the working bound: `DEFAULT_IDLE_TIMEOUT_MS` is what stops a hung child.
+ * This is the runaway ceiling for a child that keeps producing events forever, and it exists so that no typo in the
+ * inactivity variable can make a child unbounded. The history: ten minutes, twenty (ADR-0038), sixty (its note), each
+ * time because a working child was cut off by a wall clock that cannot tell working from hung.
+ */
+export declare const DEFAULT_TIMEOUT_MS: number;
+/** Fifteen minutes with no stdout byte and no session-file change. A hung child is a silent one; a build is not. */
+export declare const DEFAULT_IDLE_TIMEOUT_MS: number;
+export declare const DEFAULT_ACTIVITY_PROBE_INTERVAL_MS = 2000;
+/** Grace between SIGTERM and SIGKILL. A child that ignores SIGTERM must not make the timeout advisory. */
+export declare const DEFAULT_KILL_GRACE_MS = 5000;
+export declare function runChild(request: ChildRunRequest): Promise<ChildRunResult>;
+//# sourceMappingURL=run-child.d.ts.map

package/dist/kernel/run-child.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-child.d.ts","sourceRoot":"","sources":["../../src/kernel/run-child.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,OAAO,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAa3E;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAY9D;AAED;;;;;;GAMG;AAEH,iGAAiG;AACjG,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK9D;AAED,mHAAmH;AACnH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAGlE;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,yFAAyF;IACzF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wHAAwH;IACxH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACzF,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,2GAA2G;IAC3G,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC,kGAAkG;IAClG,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACzE,qGAAqG;IACrG,WAAW,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,KAAK,IAAI,CAAC;IACpD,mGAAmG;IACnG,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC;AAED,MAAM,WAAW,cAAc;IAC7B,yFAAyF;IACzF,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,gHAAgH;IAChH,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,mFAAmF;IACnF,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAC;IAC/B,wDAAwD;IACxD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,0FAA0F;AAC1F,eAAO,MAAM,wBAAwB,QAAc,CAAC;AACpD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAqB,CAAC;AACrD,oHAAoH;AACpH,eAAO,MAAM,uBAAuB,QAAiB,CAAC;AACtD,eAAO,MAAM,kCAAkC,OAAO,CAAC;AACvD,0GAA0G;AAC1G,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAwQ1E"}