patchwork-os 1.2.0-beta.2.canary.782 → 1.2.0-beta.2.canary.783

package/dist/governance/effectivePolicy.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Effective policy — one deterministic calculation answering
+ * "what can this recipe / worker / tool actually do right now?"
+ *
+ * It COMPOSES the existing pure decision functions; it replaces none of them:
+ *
+ *   kill switch   → readKillSwitch                       (killSwitchPolicy.ts)
+ *   worker        → decideWorkerAction + resolveGateOutcome (workers/workerGate.ts)
+ *   privacy       → decideBoundary                       (privacy/dataPolicy.ts)
+ *   tool tier     → classifyTool                         (riskTier.ts)
+ *   profile       → resolveProfile                       (profile.ts)
+ *
+ * The runtime and `patchwork policy explain` call the SAME functions in this
+ * file (`shouldConsultApproval`, `tierVerdict`, `computeEffectivePolicy`), so
+ * the explanation cannot drift from enforcement. `effectivePolicy.test.ts`
+ * asserts preview == enforcement over a matrix of inputs.
+ *
+ * Stage order is the runtime order (see ARCHITECTURE note in the Phase 0
+ * report): kill switch → authority (worker, tool tier, trigger) → privacy →
+ * approval → dispatch. A REFUSE at any stage is final; an APPROVAL at any
+ * stage is final unless a later stage refuses.
+ */
+import type { BoundaryDecision } from "../privacy/dataPolicy.js";
+import type { RiskTier } from "../riskTier.js";
+import type { WorkerGateAction } from "../workers/workerGate.js";
+import type { GovernanceProfile } from "./profile.js";
+export type TriggerKind = "manual" | "cron" | "webhook" | "file_watch" | "git_hook" | "on_file_save" | "on_test_run" | "chained" | "nested" | "replay" | "local" | (string & {});
+export interface ToolFacts {
+    id: string;
+    /** From `classifyTool(id)`. */
+    tier: RiskTier;
+    /** From the recipe tool registry; `undefined` when the id is not registered. */
+    isWrite?: boolean;
+    /** True when the registry (or an explicit map) supplied the tier; false when inferred from the name. */
+    tierDeclared: boolean;
+    /** False when nothing is registered under this id. */
+    registered: boolean;
+    /**
+     * From `classifyActionClass(id)` (workers/actionClass.ts): the same
+     * reversibility the worker gate uses. Governed gates every NON-reversible
+     * write regardless of tier; reversible writes (file.write, rollback-able)
+     * flow below the tier threshold, as the threat model intends.
+     */
+    reversibility?: "reversible" | "compensable" | "irreversible";
+    /** True for `agent:` steps (tool id "agent"). */
+    isAgentStep?: boolean;
+    /** For agent steps: whether containment is enforced for this step. */
+    agentContained?: boolean;
+    /** For agent steps: widenings the step requested. */
+    agentWidenings?: string[];
+}
+export interface WorkerFacts {
+    id: string;
+    action: WorkerGateAction;
+    /** Rule id from the decision record, when known. */
+    ruleId?: string;
+    standingPermissionId?: string;
+}
+export interface PrivacyFacts {
+    classification: string;
+    destination: string;
+    decision: BoundaryDecision;
+    reason?: string;
+}
+export interface EffectivePolicyInput {
+    profile: GovernanceProfile;
+    recipe: {
+        name: string;
+        requireApproval?: boolean;
+    };
+    trigger: TriggerKind;
+    tool: ToolFacts;
+    /** Present only when a worker owns the recipe and its gate is active. */
+    worker?: WorkerFacts;
+    /** Present only for agent steps with a registered destination. */
+    privacy?: PrivacyFacts;
+    killSwitch: {
+        engaged: boolean;
+        reason: string;
+    };
+    /** Per-recipe tool allowlist, when declared (`tools:` on the recipe). */
+    recipeToolAllowlist?: string[];
+    /**
+     * What the orchestrator actually injected into the runner. When absent the
+     * calculation derives it from the profile (the `explain` path); the runner
+     * passes the real values so the two cannot disagree about what is wired.
+     */
+    gate?: {
+        approvalFnInjected: boolean;
+        workerGateInjected: boolean;
+    };
+}
+export type StageVerdict = "ALLOW" | "APPROVAL" | "REFUSE" | "SKIP" | "N/A";
+export interface PolicyStage {
+    stage: "kill_switch" | "tool_registration" | "recipe_tool_allowlist" | "worker_authority" | "tool_tier" | "trigger" | "privacy" | "standing_permission";
+    verdict: StageVerdict;
+    reason: string;
+}
+export type FinalVerdict = "ALLOW" | "HUMAN_APPROVAL_REQUIRED" | "REFUSED";
+export interface EffectivePolicy {
+    final: FinalVerdict;
+    stages: PolicyStage[];
+    /** True when the runtime will call the approval fn for this step. */
+    consultsApproval: boolean;
+}
+/**
+ * Does the TRIGGER put this step in front of the approval fn at all?
+ * This is the predicate the flat and chained runners evaluate. Kept as one
+ * function so `policy explain` and the runner cannot disagree about it.
+ */
+export declare function shouldConsultApproval(args: {
+    profile: GovernanceProfile;
+    trigger: TriggerKind;
+    recipeRequireApproval?: boolean;
+    /** The worker gate is injected (compat: worker flag on + manifest). */
+    workerGateInjected: boolean;
+    /** An approval fn was injected at all (approvalGate != off, or worker). */
+    approvalFnInjected: boolean;
+}): {
+    consult: boolean;
+    reason: string;
+};
+/**
+ * The TIER half: given the approval-gate level and what we know about the
+ * tool, does the tier gate want a human? Mirrors `makeRecipeApprovalFn`'s
+ * threshold plus the governed rules for unknown write tools and agent steps.
+ */
+export declare function tierVerdict(profile: GovernanceProfile, tool: ToolFacts): {
+    verdict: "ALLOW" | "APPROVAL";
+    reason: string;
+};
+export declare function computeEffectivePolicy(input: EffectivePolicyInput): EffectivePolicy;
+/** Plain-text rendering for `patchwork policy explain`. */
+export declare function formatEffectivePolicy(input: EffectivePolicyInput, result: EffectivePolicy): string;

package/dist/governance/effectivePolicy.js

@@ -0,0 +1,322 @@
+/**
+ * Effective policy — one deterministic calculation answering
+ * "what can this recipe / worker / tool actually do right now?"
+ *
+ * It COMPOSES the existing pure decision functions; it replaces none of them:
+ *
+ *   kill switch   → readKillSwitch                       (killSwitchPolicy.ts)
+ *   worker        → decideWorkerAction + resolveGateOutcome (workers/workerGate.ts)
+ *   privacy       → decideBoundary                       (privacy/dataPolicy.ts)
+ *   tool tier     → classifyTool                         (riskTier.ts)
+ *   profile       → resolveProfile                       (profile.ts)
+ *
+ * The runtime and `patchwork policy explain` call the SAME functions in this
+ * file (`shouldConsultApproval`, `tierVerdict`, `computeEffectivePolicy`), so
+ * the explanation cannot drift from enforcement. `effectivePolicy.test.ts`
+ * asserts preview == enforcement over a matrix of inputs.
+ *
+ * Stage order is the runtime order (see ARCHITECTURE note in the Phase 0
+ * report): kill switch → authority (worker, tool tier, trigger) → privacy →
+ * approval → dispatch. A REFUSE at any stage is final; an APPROVAL at any
+ * stage is final unless a later stage refuses.
+ */
+/**
+ * Does the TRIGGER put this step in front of the approval fn at all?
+ * This is the predicate the flat and chained runners evaluate. Kept as one
+ * function so `policy explain` and the runner cannot disagree about it.
+ */
+export function shouldConsultApproval(args) {
+    const { profile, trigger, recipeRequireApproval, workerGateInjected, approvalFnInjected, } = args;
+    if (!approvalFnInjected) {
+        return {
+            consult: false,
+            reason: "no approval gate configured (approvalGate: off)",
+        };
+    }
+    const automated = trigger !== "manual";
+    const gateAutomated = profile.gateAutomatedRuns || workerGateInjected;
+    if (automated && !gateAutomated) {
+        return {
+            consult: false,
+            reason: `trigger ${trigger} is not gated (compat profile: manual runs only)`,
+        };
+    }
+    if (recipeRequireApproval === false) {
+        if (workerGateInjected) {
+            return {
+                consult: true,
+                reason: "recipe requireApproval:false cannot opt out of worker governance",
+            };
+        }
+        if (!profile.recipeOptOutHonoured) {
+            return {
+                consult: true,
+                reason: "recipe requireApproval:false ignored under governed profile",
+            };
+        }
+        return {
+            consult: false,
+            reason: "recipe opted out (requireApproval: false)",
+        };
+    }
+    return {
+        consult: true,
+        reason: automated
+            ? `trigger ${trigger} gated like a manual run`
+            : "manual run",
+    };
+}
+/**
+ * The TIER half: given the approval-gate level and what we know about the
+ * tool, does the tier gate want a human? Mirrors `makeRecipeApprovalFn`'s
+ * threshold plus the governed rules for unknown write tools and agent steps.
+ */
+export function tierVerdict(profile, tool) {
+    const gate = profile.approvalGate;
+    if (gate === "off")
+        return { verdict: "ALLOW", reason: "approval gate off" };
+    if (tool.isAgentStep) {
+        if (profile.agentContainment === "enforced") {
+            return tool.agentContained
+                ? {
+                    verdict: tool.agentWidenings?.length ? "APPROVAL" : "ALLOW",
+                    reason: tool.agentWidenings?.length
+                        ? `agent step widened containment (${tool.agentWidenings.join(", ")})`
+                        : "agent step contained (read-only tools, no network, no shell)",
+                }
+                : { verdict: "APPROVAL", reason: "agent step not contained" };
+        }
+        // compat: agent classified by name → medium → passes under "high"
+        return gate === "all"
+            ? { verdict: "APPROVAL", reason: "approval gate: all" }
+            : { verdict: "ALLOW", reason: "agent step tier medium < high" };
+    }
+    if (gate === "all")
+        return { verdict: "APPROVAL", reason: "approval gate: all" };
+    if (tool.tier === "high")
+        return { verdict: "APPROVAL", reason: "tool tier high" };
+    // Governed: every NON-reversible write asks, whatever its tier. The
+    // reversibility comes from the same action classifier the worker gate
+    // uses, so "reversible" here means rollback-able (file.write), not "low".
+    if (profile.unknownWriteTools === "gate" &&
+        tool.isWrite === true &&
+        tool.reversibility !== undefined &&
+        tool.reversibility !== "reversible") {
+        return {
+            verdict: "APPROVAL",
+            reason: `${tool.reversibility} write gated under governed profile (${tool.tier} tier)`,
+        };
+    }
+    if (profile.unknownWriteTools === "gate" &&
+        tool.isWrite !== false &&
+        (!tool.tierDeclared || tool.isWrite === undefined)) {
+        return {
+            verdict: "APPROVAL",
+            reason: tool.registered
+                ? "write tool with inferred tier gated under governed profile"
+                : "tool of unknown provenance gated under governed profile",
+        };
+    }
+    return { verdict: "ALLOW", reason: `tool tier ${tool.tier} below threshold` };
+}
+export function computeEffectivePolicy(input) {
+    const { profile, tool } = input;
+    const stages = [];
+    // 1. Kill switch — absolute.
+    if (input.killSwitch.engaged) {
+        stages.push({
+            stage: "kill_switch",
+            verdict: "REFUSE",
+            reason: input.killSwitch.reason,
+        });
+        return { final: "REFUSED", stages, consultsApproval: false };
+    }
+    stages.push({
+        stage: "kill_switch",
+        verdict: "ALLOW",
+        reason: input.killSwitch.reason,
+    });
+    // 2. Registration.
+    if (!tool.registered && !tool.isAgentStep) {
+        if (profile.unregisteredTools === "refuse") {
+            stages.push({
+                stage: "tool_registration",
+                verdict: "REFUSE",
+                reason: `tool ${tool.id} is not registered (governed profile refuses rather than skips)`,
+            });
+            return { final: "REFUSED", stages, consultsApproval: false };
+        }
+        // Compat: the runner still consults the approval fn for the step (the
+        // old predicate never looked at registration) and only SKIPS at dispatch
+        // when nothing answers to the id. Record that, and keep going.
+        stages.push({
+            stage: "tool_registration",
+            verdict: "SKIP",
+            reason: `tool ${tool.id} is not registered — dispatch will skip it (compat forward-compat rule)`,
+        });
+    }
+    else {
+        stages.push({
+            stage: "tool_registration",
+            verdict: "ALLOW",
+            reason: tool.isAgentStep ? "agent step" : "tool registered",
+        });
+    }
+    // 3. Recipe tool allowlist.
+    if (input.recipeToolAllowlist && !tool.isAgentStep) {
+        if (!input.recipeToolAllowlist.includes(tool.id)) {
+            stages.push({
+                stage: "recipe_tool_allowlist",
+                verdict: "REFUSE",
+                reason: `tool ${tool.id} not in recipe tools: allowlist`,
+            });
+            return { final: "REFUSED", stages, consultsApproval: false };
+        }
+        stages.push({
+            stage: "recipe_tool_allowlist",
+            verdict: "ALLOW",
+            reason: "tool declared",
+        });
+    }
+    else {
+        stages.push({
+            stage: "recipe_tool_allowlist",
+            verdict: "N/A",
+            reason: "no allowlist declared",
+        });
+    }
+    // 4. Worker authority (forbid is final; gate → approval unless standing).
+    let workerWantsApproval = false;
+    if (input.worker) {
+        const w = input.worker;
+        if (w.action === "forbid") {
+            stages.push({
+                stage: "worker_authority",
+                verdict: "REFUSE",
+                reason: `worker ${w.id} forbids this action (${w.ruleId ?? "forbid rule"}) — no approval can unlock it`,
+            });
+            return { final: "REFUSED", stages, consultsApproval: false };
+        }
+        if (w.action === "gate") {
+            if (w.standingPermissionId) {
+                stages.push({
+                    stage: "worker_authority",
+                    verdict: "APPROVAL",
+                    reason: `worker ${w.id} has not earned this action`,
+                });
+                stages.push({
+                    stage: "standing_permission",
+                    verdict: "ALLOW",
+                    reason: `standing permission ${w.standingPermissionId} converts queue → flow`,
+                });
+            }
+            else {
+                workerWantsApproval = true;
+                stages.push({
+                    stage: "worker_authority",
+                    verdict: "APPROVAL",
+                    reason: `worker ${w.id} has not earned this action (${w.ruleId ?? "trust below threshold"})`,
+                });
+                stages.push({
+                    stage: "standing_permission",
+                    verdict: "N/A",
+                    reason: "none",
+                });
+            }
+        }
+        else {
+            stages.push({
+                stage: "worker_authority",
+                verdict: "ALLOW",
+                reason: `worker ${w.id} may act autonomously (${w.ruleId ?? "earned"})`,
+            });
+        }
+    }
+    else {
+        stages.push({
+            stage: "worker_authority",
+            verdict: "N/A",
+            reason: "no worker owns this recipe",
+        });
+    }
+    // 5. Tool tier.
+    const tier = tierVerdict(profile, tool);
+    stages.push({
+        stage: "tool_tier",
+        verdict: tier.verdict,
+        reason: tier.reason,
+    });
+    // 6. Trigger — does the approval fn get consulted at all?
+    const consult = shouldConsultApproval({
+        profile,
+        trigger: input.trigger,
+        recipeRequireApproval: input.recipe.requireApproval,
+        workerGateInjected: input.gate?.workerGateInjected ?? input.worker !== undefined,
+        approvalFnInjected: input.gate?.approvalFnInjected ??
+            (profile.approvalGate !== "off" || input.worker !== undefined),
+    });
+    stages.push({
+        stage: "trigger",
+        verdict: consult.consult ? "ALLOW" : "SKIP",
+        reason: consult.reason,
+    });
+    // 7. Privacy — refuses everything but ALLOW (executeAgent's rule).
+    if (input.privacy) {
+        const p = input.privacy;
+        if (p.decision === "ALLOW") {
+            stages.push({
+                stage: "privacy",
+                verdict: "ALLOW",
+                reason: `${p.classification} → ${p.destination} allowed`,
+            });
+        }
+        else {
+            stages.push({
+                stage: "privacy",
+                verdict: "REFUSE",
+                reason: `${p.classification} → ${p.destination}: ${p.decision}${p.reason ? ` (${p.reason})` : ""}`,
+            });
+            return { final: "REFUSED", stages, consultsApproval: false };
+        }
+    }
+    else {
+        stages.push({
+            stage: "privacy",
+            verdict: "N/A",
+            reason: tool.isAgentStep
+                ? "no destination registered"
+                : "not a model dispatch",
+        });
+    }
+    // Final composition.
+    const wantsApproval = consult.consult && (tier.verdict === "APPROVAL" || workerWantsApproval);
+    return {
+        final: wantsApproval ? "HUMAN_APPROVAL_REQUIRED" : "ALLOW",
+        stages,
+        consultsApproval: consult.consult,
+    };
+}
+/** Plain-text rendering for `patchwork policy explain`. */
+export function formatEffectivePolicy(input, result) {
+    const lines = [];
+    lines.push(`RECIPE: ${input.recipe.name}`);
+    lines.push(`PROFILE: ${input.profile.mode.toUpperCase()}${input.profile.declared ? "" : " (defaulted — no profile: key)"}`);
+    lines.push(`TRIGGER: ${String(input.trigger).toUpperCase()}`);
+    lines.push(`TOOL: ${input.tool.id}${input.tool.isAgentStep ? " (agent step)" : ""}`);
+    lines.push(`TOOL RISK: ${input.tool.tier.toUpperCase()}${input.tool.tierDeclared ? "" : " (inferred from name)"}${input.tool.isWrite ? " · WRITE" : ""}`);
+    if (input.worker)
+        lines.push(`WORKER: ${input.worker.id}`);
+    lines.push("");
+    for (const s of result.stages) {
+        lines.push(`${s.stage.padEnd(22)} ${s.verdict.padEnd(9)} ${s.reason}`);
+    }
+    lines.push("");
+    const label = result.final === "ALLOW"
+        ? "ALLOWED"
+        : result.final === "HUMAN_APPROVAL_REQUIRED"
+            ? "HUMAN APPROVAL REQUIRED"
+            : "REFUSED";
+    lines.push(`FINAL RESULT: ${label}`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=effectivePolicy.js.map

package/dist/governance/effectivePolicy.js.map

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

package/dist/governance/killSwitchPolicy.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Kill-switch read with a profile-dependent failure mode.
+ *
+ * Invariant the governed profile promises: if the kill switch is active, no
+ * Patchwork-mediated consequential write occurs. A read that FAILS cannot be
+ * allowed to resolve to "released" under that promise — an unreadable flags
+ * state is exactly what tampering with `flags.json` or the install would
+ * produce. Under `compat` the historical fail-open stays, because that is
+ * what every existing call site did and this module exists to replace those
+ * sites without changing what they do for existing installs.
+ *
+ * Every dispatch chokepoint (recipe `executeTool`, MCP `transport.ts`,
+ * subprocess spawn, orchestrator enqueue, recipe entry) calls
+ * `readKillSwitch()` / `assertKillSwitchReleased()` rather than importing
+ * `isWriteKillSwitchActive` and wrapping it in its own `try {} catch {}` —
+ * which is how four sites ended up fail-open with a comment saying "same as
+ * every other site".
+ */
+import { type GovernanceProfile } from "./profile.js";
+export interface KillSwitchReading {
+    /** True ⇒ refuse the write. */
+    engaged: boolean;
+    reason: "engaged" | "released" | "unreadable_fail_closed" | "unreadable_fail_open";
+}
+export declare function readKillSwitch(profile?: GovernanceProfile): KillSwitchReading;
+export declare function killSwitchMessage(r: KillSwitchReading, operation: string): string;
+/** Throw a coded error when the switch is engaged. Same code as `assertWriteAllowed`. */
+export declare function assertKillSwitchReleased(operation: string, profile?: GovernanceProfile): void;
+/** Test seam: replace the underlying reader (e.g. with one that throws). */
+export declare function _setKillSwitchReaderForTesting(fn: (() => boolean) | null): void;

package/dist/governance/killSwitchPolicy.js

@@ -0,0 +1,52 @@
+/**
+ * Kill-switch read with a profile-dependent failure mode.
+ *
+ * Invariant the governed profile promises: if the kill switch is active, no
+ * Patchwork-mediated consequential write occurs. A read that FAILS cannot be
+ * allowed to resolve to "released" under that promise — an unreadable flags
+ * state is exactly what tampering with `flags.json` or the install would
+ * produce. Under `compat` the historical fail-open stays, because that is
+ * what every existing call site did and this module exists to replace those
+ * sites without changing what they do for existing installs.
+ *
+ * Every dispatch chokepoint (recipe `executeTool`, MCP `transport.ts`,
+ * subprocess spawn, orchestrator enqueue, recipe entry) calls
+ * `readKillSwitch()` / `assertKillSwitchReleased()` rather than importing
+ * `isWriteKillSwitchActive` and wrapping it in its own `try {} catch {}` —
+ * which is how four sites ended up fail-open with a comment saying "same as
+ * every other site".
+ */
+import { isWriteKillSwitchActive } from "../featureFlags.js";
+import { activeProfile } from "./profile.js";
+let reader = isWriteKillSwitchActive;
+export function readKillSwitch(profile = activeProfile()) {
+    try {
+        const engaged = reader();
+        return { engaged, reason: engaged ? "engaged" : "released" };
+    }
+    catch {
+        if (profile.killSwitchFailClosed) {
+            return { engaged: true, reason: "unreadable_fail_closed" };
+        }
+        return { engaged: false, reason: "unreadable_fail_open" };
+    }
+}
+export function killSwitchMessage(r, operation) {
+    return r.reason === "unreadable_fail_closed"
+        ? `kill_switch_blocked: ${operation} refused — kill-switch state unreadable and the governed profile fails closed`
+        : `kill_switch_blocked: ${operation} refused — write kill switch engaged. Release with \`patchwork kill-switch release\`.`;
+}
+/** Throw a coded error when the switch is engaged. Same code as `assertWriteAllowed`. */
+export function assertKillSwitchReleased(operation, profile = activeProfile()) {
+    const r = readKillSwitch(profile);
+    if (r.engaged) {
+        const err = new Error(killSwitchMessage(r, operation));
+        err.code = "kill_switch_blocked";
+        throw err;
+    }
+}
+/** Test seam: replace the underlying reader (e.g. with one that throws). */
+export function _setKillSwitchReaderForTesting(fn) {
+    reader = fn ?? isWriteKillSwitchActive;
+}
+//# sourceMappingURL=killSwitchPolicy.js.map

package/dist/governance/killSwitchPolicy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"killSwitchPolicy.js","sourceRoot":"","sources":["../../src/governance/killSwitchPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,aAAa,EAA0B,MAAM,cAAc,CAAC;AAYrE,IAAI,MAAM,GAAkB,uBAAuB,CAAC;AAEpD,MAAM,UAAU,cAAc,CAC5B,UAA6B,aAAa,EAAE;IAE5C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC;QACzB,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;IAC/D,CAAC;IAAC,MAAM,CAAC;QACP,IAAI,OAAO,CAAC,oBAAoB,EAAE,CAAC;YACjC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,wBAAwB,EAAE,CAAC;QAC7D,CAAC;QACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAC5D,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,CAAoB,EACpB,SAAiB;IAEjB,OAAO,CAAC,CAAC,MAAM,KAAK,wBAAwB;QAC1C,CAAC,CAAC,wBAAwB,SAAS,+EAA+E;QAClH,CAAC,CAAC,wBAAwB,SAAS,uFAAuF,CAAC;AAC/H,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,wBAAwB,CACtC,SAAiB,EACjB,UAA6B,aAAa,EAAE;IAE5C,MAAM,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IAClC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;QACd,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,iBAAiB,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC;QACtD,GAAiC,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAChE,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,8BAA8B,CAC5C,EAA0B;IAE1B,MAAM,GAAG,EAAE,IAAI,uBAAuB,CAAC;AACzC,CAAC"}