@connexum/ai-governance 1.0.0-beta.11

package/dist/governance/approval-gate-enforcer.js

@@ -0,0 +1,443 @@
+"use strict";
+/**
+ * ApprovalGateEnforcer -- Mandatory approval gates with per-class policy.
+ *
+ * Categorises actions into six explicit approval classes (destructive,
+ * irreversible, financial, data-export, network-egress, secret-rotation),
+ * applies per-class disposition policy (requires-approval /
+ * auto-approve-low-risk / always-deny), and blocks synchronously until a
+ * human approves, rejects, or the configured timeout elapses.
+ *
+ * RELATIONSHIP TO PR #24 (feat/p3-t1-autonomy-spectrum):
+ *   PR #24 ships AutonomySpectrumEnforcer (Level 0-4). At Level 4 certain
+ *   action classes are routed to an approval queue via `guardAction()` which
+ *   returns `{ decision: 'approval-required', approvalRequestId }`. The
+ *   Level 4 gate intentionally does NOT own the queue lifecycle -- it only
+ *   names the classes that need gating.
+ *
+ *   THIS MODULE owns the gate lifecycle:
+ *     - Explicit class definitions with rationale (action-classes.ts)
+ *     - Per-class disposition config (ClassPolicyMap)
+ *     - Synchronous blocking via Promise + polling (no busy-spin)
+ *     - Audit chain writes on every decision
+ *     - Replay protection in the store (PT-APPROVAL-3)
+ *     - Empty packBinding[] guard (PT-APPROVAL-1)
+ *     - Config validation at construction (PT-APPROVAL-2)
+ *     - Authorised-approver list enforcement (PT-APPROVAL-4)
+ *
+ * HOOK POSITION:
+ *   The gate should fire AFTER blast-radius enforcement (PR #42) but BEFORE
+ *   action-isolation (PR #29). Rationale: blast-radius has already confirmed
+ *   the action is within scope; the gate then checks whether it needs human
+ *   sign-off before it executes. Action-isolation runs post-approval to
+ *   sandbox the approved execution. As of main HEAD, PRs #42 and #29 are
+ *   not yet merged, so this ordering is documented here but has no direct
+ *   code coupling to either module.
+ *
+ * TIMEOUT SEMANTICS:
+ *   On timeout, the safe default is DENY. Operators may override per-class
+ *   via `ActionClassPolicy.timeoutMs`. There is no "allow on timeout" option.
+ *
+ * COMPLIANCE BINDINGS:
+ *   HIPAA 164.308(a)(1): Security management process
+ *   HIPAA 164.308(a)(3): Workforce authorisation and supervision
+ *   HIPAA 164.312(a)(1): Access controls
+ *   SOC 2 CC6.1: Logical access restrictions
+ *   GDPR Art. 22: Automated decision-making
+ *   PCI DSS Req 7: Restrict access by business need
+ *   NIST 800-53 AC-3: Access enforcement
+ *   ISO 27001 A.9.4.1: Information access restriction
+ *
+ * @connexum/ai-governance P3-T2
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApprovalGateEnforcer = exports.ConfigValidationError = exports.ActionClass = void 0;
+exports.generateApprovalId = generateApprovalId;
+const crypto = __importStar(require("crypto"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const index_1 = require("../errors/index");
+const action_classes_1 = require("./action-classes");
+Object.defineProperty(exports, "ActionClass", { enumerable: true, get: function () { return action_classes_1.ActionClass; } });
+Object.defineProperty(exports, "ConfigValidationError", { enumerable: true, get: function () { return action_classes_1.ConfigValidationError; } });
+const approval_queue_store_1 = require("./approval-queue-store");
+// ---------------------------------------------------------------------------
+// ApprovalGateEnforcer
+// ---------------------------------------------------------------------------
+class ApprovalGateEnforcer {
+    cfg;
+    /**
+     * PT-APPROVAL-2: constructor validates the class policy map.
+     * Throws ConfigValidationError immediately on invalid configuration.
+     */
+    constructor(config = {}) {
+        // Merge caller-supplied partial policies over the defaults.
+        const defaults = (0, action_classes_1.buildDefaultClassPolicies)();
+        const merged = config.classPolicies
+            ? { ...defaults, ...config.classPolicies }
+            : defaults;
+        // Validate before storing.
+        (0, action_classes_1.validateClassPolicies)(merged);
+        // Additional config validation.
+        const defaultTimeoutMs = config.defaultTimeoutMs ?? 600_000;
+        if (!Number.isFinite(defaultTimeoutMs) || defaultTimeoutMs <= 0) {
+            throw new action_classes_1.ConfigValidationError(`Invalid defaultTimeoutMs "${defaultTimeoutMs}". Must be a positive finite number.`);
+        }
+        const pollIntervalMs = config.pollIntervalMs ?? 200;
+        if (!Number.isFinite(pollIntervalMs) || pollIntervalMs <= 0) {
+            throw new action_classes_1.ConfigValidationError(`Invalid pollIntervalMs "${pollIntervalMs}". Must be a positive finite number.`);
+        }
+        this.cfg = {
+            classPolicies: merged,
+            defaultTimeoutMs,
+            pollIntervalMs,
+            store: config.store ?? new approval_queue_store_1.InMemoryApprovalQueueStore(),
+            auditDir: config.auditDir ?? null,
+        };
+        if (this.cfg.auditDir) {
+            fs.mkdirSync(this.cfg.auditDir, { recursive: true });
+        }
+    }
+    // ---------------------------------------------------------------------------
+    // Primary enforcement API
+    // ---------------------------------------------------------------------------
+    /**
+     * Enforce the approval gate for a given action.
+     *
+     * Behaviour by disposition:
+     *   auto-approve-low-risk  -- Returns immediately with allowed=true.
+     *   always-deny            -- Returns immediately with allowed=false.
+     *   requires-approval      -- Blocks (polls) until approved/rejected/timeout.
+     *
+     * PT-APPROVAL-1: empty packBinding throws UnboundDataError before any
+     * queue insertion.
+     *
+     * @param actionContext  Describes the action and its governance context.
+     * @returns EnforcementResult promise that resolves when a decision is made.
+     */
+    async enforce(actionContext) {
+        // PT-APPROVAL-1: pack binding must be non-empty.
+        if (!actionContext.packBinding || actionContext.packBinding.length === 0) {
+            throw new index_1.UnboundDataError(`approval-gate:enforce[${actionContext.actionClass}]`, actionContext.tenantId ?? 'unknown');
+        }
+        const policy = this.cfg.classPolicies[actionContext.actionClass];
+        const now = new Date().toISOString();
+        // ---- auto-approve-low-risk ----
+        if (policy.disposition === 'auto-approve-low-risk') {
+            const result = {
+                allowed: true,
+                outcome: 'auto-approved',
+                decidedAt: now,
+                reason: policy.rationale ?? 'Auto-approved: class policy is auto-approve-low-risk.',
+            };
+            this.writeAudit({
+                type: 'APPROVAL_GATE_AUTO_APPROVED',
+                actionClass: actionContext.actionClass,
+                initiator: actionContext.initiator,
+                packBinding: actionContext.packBinding,
+                tenantId: actionContext.tenantId,
+                reason: result.reason,
+                timestamp: now,
+            });
+            return result;
+        }
+        // ---- always-deny ----
+        if (policy.disposition === 'always-deny') {
+            const result = {
+                allowed: false,
+                outcome: 'always-denied',
+                decidedAt: now,
+                reason: policy.rationale ?? 'Denied: class policy is always-deny.',
+            };
+            this.writeAudit({
+                type: 'APPROVAL_GATE_ALWAYS_DENIED',
+                actionClass: actionContext.actionClass,
+                initiator: actionContext.initiator,
+                packBinding: actionContext.packBinding,
+                tenantId: actionContext.tenantId,
+                reason: result.reason,
+                timestamp: now,
+            });
+            return result;
+        }
+        // ---- requires-approval ----
+        const timeoutMs = policy.timeoutMs ?? this.cfg.defaultTimeoutMs;
+        const expiresAt = new Date(Date.now() + timeoutMs).toISOString();
+        const approvalId = this.cfg.store.insert({
+            createdAt: now,
+            expiresAt,
+            actionClass: actionContext.actionClass,
+            actionDescription: actionContext.description,
+            initiator: actionContext.initiator,
+            packBinding: actionContext.packBinding,
+        });
+        this.writeAudit({
+            type: 'APPROVAL_GATE_QUEUED',
+            approvalId,
+            actionClass: actionContext.actionClass,
+            initiator: actionContext.initiator,
+            packBinding: actionContext.packBinding,
+            tenantId: actionContext.tenantId,
+            timestamp: now,
+        });
+        // Block (poll) until resolved or timed out.
+        const decision = await this.waitForDecision(approvalId, timeoutMs);
+        const record = this.cfg.store.get(approvalId);
+        const decidedAt = record.decidedAt ?? new Date().toISOString();
+        if (decision === 'timed-out') {
+            this.writeAudit({
+                type: 'APPROVAL_GATE_TIMED_OUT',
+                approvalId,
+                actionClass: actionContext.actionClass,
+                initiator: actionContext.initiator,
+                packBinding: actionContext.packBinding,
+                tenantId: actionContext.tenantId,
+                reason: 'Timed out. Default action: deny.',
+                timestamp: decidedAt,
+            });
+            return {
+                allowed: false,
+                outcome: 'timed-out',
+                approvalId,
+                decidedAt,
+                reason: 'Timed out waiting for human approval. Default action: deny.',
+            };
+        }
+        if (decision === 'approved') {
+            this.writeAudit({
+                type: 'APPROVAL_GATE_APPROVED',
+                approvalId,
+                actionClass: actionContext.actionClass,
+                initiator: actionContext.initiator,
+                packBinding: actionContext.packBinding,
+                tenantId: actionContext.tenantId,
+                approverId: record.approverId,
+                reason: record.reason,
+                timestamp: decidedAt,
+            });
+            return {
+                allowed: true,
+                outcome: 'approved',
+                approvalId,
+                approverId: record.approverId,
+                reason: record.reason,
+                decidedAt,
+            };
+        }
+        // rejected
+        this.writeAudit({
+            type: 'APPROVAL_GATE_REJECTED',
+            approvalId,
+            actionClass: actionContext.actionClass,
+            initiator: actionContext.initiator,
+            packBinding: actionContext.packBinding,
+            tenantId: actionContext.tenantId,
+            approverId: record.approverId,
+            reason: record.reason,
+            timestamp: decidedAt,
+        });
+        return {
+            allowed: false,
+            outcome: 'rejected',
+            approvalId,
+            approverId: record.approverId,
+            reason: record.reason,
+            decidedAt,
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Approval submission API (caller-side hooks for human approver)
+    // ---------------------------------------------------------------------------
+    /**
+     * Submit an approval decision for a pending gate.
+     *
+     * PT-APPROVAL-3: If the approvalId has already been decided, this call
+     * is a silent no-op (the store's replay protection handles it).
+     *
+     * PT-APPROVAL-4: If the class policy specifies `allowedApprovers` and
+     * `approverId` is not in that list, the approval is rejected and an
+     * APPROVAL_GATE_UNAUTHORIZED_APPROVER audit entry is written.
+     *
+     * @param approvalId  The ID returned by `enforce()`.
+     * @param approverId  Identity of the human approver.
+     * @param reason      Optional human-readable reason.
+     */
+    submitApproval(approvalId, approverId, reason) {
+        const record = this.cfg.store.get(approvalId);
+        if (!record)
+            return;
+        // PT-APPROVAL-4: check authorised approvers.
+        if (!this.isAuthorizedApprover(record.actionClass, approverId)) {
+            this.writeAudit({
+                type: 'APPROVAL_GATE_UNAUTHORIZED_APPROVER',
+                approvalId,
+                actionClass: record.actionClass,
+                initiator: record.initiator,
+                packBinding: record.packBinding,
+                approverId,
+                reason: `Approver "${approverId}" is not in the allowedApprovers list for class "${record.actionClass}".`,
+                timestamp: new Date().toISOString(),
+            });
+            // Reject the attempt rather than silently ignoring -- fail closed.
+            this.cfg.store.resolve(approvalId, 'rejected', `system:unauthorized:${approverId}`, `Approver "${approverId}" is not authorised for class "${record.actionClass}".`);
+            return;
+        }
+        this.cfg.store.resolve(approvalId, 'approved', approverId, reason);
+    }
+    /**
+     * Submit a rejection decision for a pending gate.
+     *
+     * PT-APPROVAL-3: If the approvalId has already been decided, this call
+     * is a silent no-op.
+     *
+     * @param approvalId  The ID returned by `enforce()`.
+     * @param approverId  Identity of the rejecting human.
+     * @param reason      Optional human-readable reason.
+     */
+    submitRejection(approvalId, approverId, reason) {
+        const record = this.cfg.store.get(approvalId);
+        if (!record)
+            return;
+        this.cfg.store.resolve(approvalId, 'rejected', approverId, reason);
+    }
+    // ---------------------------------------------------------------------------
+    // Query API
+    // ---------------------------------------------------------------------------
+    /**
+     * Return all currently pending approvals.
+     * Optionally filter by action class or initiator.
+     * Used by the dashboard / UI to display the approval queue.
+     */
+    getPendingApprovals(filter) {
+        return this.cfg.store.getPending(filter);
+    }
+    /**
+     * Return a snapshot of all approvals (pending and decided).
+     * Useful for audit queries.
+     */
+    getAllApprovals() {
+        return this.cfg.store.getAll();
+    }
+    /**
+     * Retrieve a single approval by ID.
+     */
+    getApproval(approvalId) {
+        return this.cfg.store.get(approvalId);
+    }
+    // ---------------------------------------------------------------------------
+    // Private helpers
+    // ---------------------------------------------------------------------------
+    /**
+     * Poll the store until the approval is no longer 'pending' or timeout elapses.
+     *
+     * Uses setInterval-based polling (no busy-spin per AIAG-013).
+     * On timeout, calls `store.timeout()` to mark the record, then resolves.
+     */
+    waitForDecision(approvalId, timeoutMs) {
+        return new Promise((resolve) => {
+            const deadline = Date.now() + timeoutMs;
+            const interval = setInterval(() => {
+                const record = this.cfg.store.get(approvalId);
+                if (!record) {
+                    clearInterval(interval);
+                    resolve('rejected');
+                    return;
+                }
+                if (record.status === 'approved') {
+                    clearInterval(interval);
+                    resolve('approved');
+                    return;
+                }
+                if (record.status === 'rejected') {
+                    clearInterval(interval);
+                    resolve('rejected');
+                    return;
+                }
+                if (record.status === 'timed-out') {
+                    clearInterval(interval);
+                    resolve('timed-out');
+                    return;
+                }
+                // Still pending -- check if we're past deadline.
+                if (Date.now() >= deadline) {
+                    clearInterval(interval);
+                    this.cfg.store.timeout(approvalId);
+                    resolve('timed-out');
+                }
+            }, this.cfg.pollIntervalMs);
+        });
+    }
+    /**
+     * PT-APPROVAL-4: Returns true if the approverId is permitted to approve
+     * for the given action class. Always returns true when no allowedApprovers
+     * constraint is configured for that class.
+     */
+    isAuthorizedApprover(actionClass, approverId) {
+        const policy = this.cfg.classPolicies[actionClass];
+        if (!policy.allowedApprovers || policy.allowedApprovers.length === 0) {
+            return true;
+        }
+        return policy.allowedApprovers.includes(approverId);
+    }
+    /**
+     * Append an audit entry to the JSONL file when auditDir is configured.
+     * Errors are logged to stderr but never thrown -- the gate must not fail
+     * because the audit writer has a transient I/O error.
+     */
+    writeAudit(entry) {
+        if (!this.cfg.auditDir)
+            return;
+        const filePath = path.join(this.cfg.auditDir, 'approval-gate-audit.jsonl');
+        try {
+            fs.appendFileSync(filePath, JSON.stringify(entry) + '\n');
+        }
+        catch (err) {
+            process.stderr.write(`[APPROVAL GATE AUDIT] Failed to write audit entry: ${err.message}\n`);
+        }
+    }
+}
+exports.ApprovalGateEnforcer = ApprovalGateEnforcer;
+// ---------------------------------------------------------------------------
+// generateApprovalId -- exported helper for tests / integrations
+// ---------------------------------------------------------------------------
+/**
+ * Generate a unique approval ID in the same format used by the enforcer.
+ * Exposed for testing and integration code that needs to pre-generate IDs.
+ */
+function generateApprovalId() {
+    return `apg_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
+}
+//# sourceMappingURL=approval-gate-enforcer.js.map

package/dist/governance/approval-gate-enforcer.js.map

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

package/dist/governance/approval-notifications.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Approval Notification Channels (W1.10 of F-NEW-PRODUCT-AGENT-VISIBILITY-CLUSTER-2026-05-12).
+ *
+ * Thomas directive 2026-05-12: "make sure in the UX/UI for the human in the
+ * loop section we have the ability to email and/or send a text message to
+ * the user for approval."
+ *
+ * Extends the existing approval-required pipeline (ApprovalRoute / ApprovalTicket
+ * already shipped in packages/governance-server/src/approval-routing.ts) with
+ * out-of-band notification fan-out: dashboard inbox (existing), email (new),
+ * SMS (new). Per-reviewer channel preferences. Audit chain captures the
+ * channel used.
+ *
+ * Transport adapters are pluggable so we can swap Resend ↔ SES ↔ SendGrid for
+ * email and Twilio ↔ Vonage ↔ AWS-SNS for SMS without touching the dispatcher.
+ *
+ * @connexum/ai-governance  F-NEW-PRODUCT-APPROVAL-CHANNEL-EMAIL-SMS
+ */
+export type ApprovalChannel = 'dashboard' | 'email' | 'sms';
+export interface ApprovalNotificationRecipient {
+    /** Stable reviewer identity (e.g. SSO sub). */
+    reviewerId: string;
+    /** Display name for the notification body. */
+    name: string;
+    /** Email address (required when channels include 'email'). */
+    email?: string;
+    /** E.164 phone number (required when channels include 'sms'). */
+    phoneE164?: string;
+    /** Channels this reviewer wants notifications on. Defaults to ['dashboard']. */
+    channels?: ApprovalChannel[];
+}
+export interface ApprovalNotificationContext {
+    /** ApprovalTicket id (matches the existing dashboard route). */
+    ticketId: string;
+    /** Org / tenant that owns the ticket. */
+    orgId: string;
+    /** Agent attempting the action. */
+    agentId: string;
+    /** Tool name being gated. */
+    toolName: string;
+    /** Risk level annotation from the ApprovalTicket. */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** Human-readable summary of the proposed action (sanitized). */
+    summary: string;
+    /** Approval / decision URL (signed link). */
+    approveUrl: string;
+    /** Deny URL (signed link). */
+    denyUrl: string;
+    /** ISO 8601 deadline for response before escalation. */
+    slaDeadline: string;
+}
+export interface EmailSender {
+    send(params: {
+        to: string;
+        subject: string;
+        html: string;
+        text: string;
+    }): Promise<{
+        ok: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+}
+export interface SmsSender {
+    send(params: {
+        to: string;
+        body: string;
+    }): Promise<{
+        ok: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+}
+export interface NotificationOutcome {
+    recipientId: string;
+    channel: ApprovalChannel;
+    delivered: boolean;
+    providerMessageId?: string;
+    error?: string;
+}
+export interface DispatcherOptions {
+    /** Email adapter. Defaults to a NOOP that records but does not transmit. */
+    emailSender?: EmailSender;
+    /** SMS adapter. Defaults to a NOOP. */
+    smsSender?: SmsSender;
+    /** Dashboard sink — callback to enqueue an in-app notification. */
+    dashboardSink?: (ctx: ApprovalNotificationContext, recipient: ApprovalNotificationRecipient) => void;
+}
+/**
+ * Dispatcher that fans out approval notifications across the requested
+ * channels. Returns one NotificationOutcome per (recipient, channel) pair.
+ */
+export declare class ApprovalChannelDispatcher {
+    private readonly emailSender;
+    private readonly smsSender;
+    private readonly dashboardSink?;
+    constructor(options?: DispatcherOptions);
+    dispatch(ctx: ApprovalNotificationContext, recipients: ReadonlyArray<ApprovalNotificationRecipient>): Promise<NotificationOutcome[]>;
+    private deliver;
+}
+//# sourceMappingURL=approval-notifications.d.ts.map

package/dist/governance/approval-notifications.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-notifications.d.ts","sourceRoot":"","sources":["../../src/governance/approval-notifications.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG,OAAO,GAAG,KAAK,CAAC;AAE5D,MAAM,WAAW,6BAA6B;IAC5C,+CAA+C;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,8DAA8D;IAC9D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gFAAgF;IAChF,QAAQ,CAAC,EAAE,eAAe,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,2BAA2B;IAC1C,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,SAAS,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,UAAU,CAAC;IAClD,iEAAiE;IACjE,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,CAAC,MAAM,EAAE;QACX,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,CAAC,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC1G;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,eAAe,CAAC;IACzB,SAAS,EAAE,OAAO,CAAC;IACnB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,iBAAiB;IAChC,4EAA4E;IAC5E,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,uCAAuC;IACvC,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,mEAAmE;IACnE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,2BAA2B,EAAE,SAAS,EAAE,6BAA6B,KAAK,IAAI,CAAC;CACtG;AAuDD;;;GAGG;AACH,qBAAa,yBAAyB;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAc;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;IACtC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAqC;gBAExD,OAAO,GAAE,iBAAsB;IAMrC,QAAQ,CACZ,GAAG,EAAE,2BAA2B,EAChC,UAAU,EAAE,aAAa,CAAC,6BAA6B,CAAC,GACvD,OAAO,CAAC,mBAAmB,EAAE,CAAC;YAcnB,OAAO;CA+DtB"}