@pellux/goodvibes-sdk 0.18.3 → 0.18.12

package/dist/_internal/platform/runtime/permissions/policy-registry.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Policy-as-Code registry.
+ *
+ * Manages versioned policy bundles with promote/rollback semantics.
+ * Enforces the rule that no bundle may move to enforcement without
+ * prior simulation evidence and a passing divergence gate.
+ *
+ * Bundle lifecycle:
+ *   loaded → simulating → promoting (gate check) → active (enforced)
+ *
+ * At any time:
+ *   - `current`   — the bundle whose rules are actively enforced
+ *   - `candidate` — a loaded bundle awaiting simulation before promotion
+ *   - `history`   — previous active bundles, kept for rollback
+ */
+import type { PolicyRule } from './types.js';
+import type { SignedPolicyBundle } from './policy-signer.js';
+import type { PolicyBundlePayload, BundleProvenance, PolicyLoadResult, PolicyLoaderOptions } from './policy-loader.js';
+import type { DivergenceReport, SimulationMode } from './types.js';
+import type { EnforceGateResult } from './divergence-dashboard.js';
+/**
+ * Lifecycle state of a policy bundle version.
+ *
+ * - `loaded`     — Bundle loaded as candidate; not yet simulated.
+ * - `simulating` — Simulation pipeline is active; divergence being collected.
+ * - `promoting`  — Gate check in progress; simulation evidence collected.
+ * - `active`     — Bundle is the enforced policy.
+ * - `rolled-back`— Bundle was superseded by a rollback operation.
+ */
+export type BundleLifecycleState = 'loaded' | 'simulating' | 'promoting' | 'active' | 'rolled-back';
+/**
+ * A versioned policy bundle entry in the registry.
+ */
+export interface PolicyBundleVersion {
+    /** The signed bundle as loaded from disk/inline. */
+    bundle: SignedPolicyBundle<PolicyBundlePayload>;
+    /** Provenance record from the loader. */
+    provenance: BundleProvenance;
+    /** The extracted rules (only populated when load succeeded). */
+    rules: PolicyRule[];
+    /** Lifecycle state for this version. */
+    state: BundleLifecycleState;
+    /** ISO 8601 timestamp when this version was loaded. */
+    loadedAt: string;
+    /** ISO 8601 timestamp when this version became active, if ever. */
+    activatedAt?: string;
+    /** ISO 8601 timestamp when this version was rolled back, if applicable. */
+    rolledBackAt?: string;
+    /** Simulation report collected before promotion, if any. */
+    simulationReport?: DivergenceReport;
+    /** The gate result that was evaluated at promotion time, if any. */
+    gateResult?: EnforceGateResult;
+}
+/**
+ * Result of a diff between two policy bundle versions.
+ */
+export interface PolicyDiffResult {
+    /** ID of the "from" bundle (current or named). */
+    fromBundleId: string;
+    /** ID of the "to" bundle (candidate or named). */
+    toBundleId: string;
+    /** Rules present in `from` but not in `to` (removed). */
+    removed: PolicyRule[];
+    /** Rules present in `to` but not in `from` (added). */
+    added: PolicyRule[];
+    /** Rules whose `id` matches but whose payload differs. */
+    changed: Array<{
+        ruleId: string;
+        from: PolicyRule;
+        to: PolicyRule;
+    }>;
+    /** Rules identical in both bundles. */
+    unchanged: PolicyRule[];
+    /** Total count of changed rules (added + removed + modified). */
+    totalChanges: number;
+}
+/**
+ * Result of a promote operation.
+ */
+export interface PromoteResult {
+    /** Whether the promotion succeeded. */
+    ok: boolean;
+    /** The gate result evaluated at promotion time. */
+    gate?: EnforceGateResult;
+    /** Human-readable explanation when promotion is blocked. */
+    error?: string;
+    /** The bundle that was promoted, if successful. */
+    bundleId?: string;
+}
+/**
+ * Result of a rollback operation.
+ */
+export interface RollbackResult {
+    /** Whether the rollback succeeded. */
+    ok: boolean;
+    /** The bundle ID restored to active state. */
+    restoredBundleId?: string;
+    /** Human-readable error when rollback fails. */
+    error?: string;
+}
+/**
+ * Configuration for the PolicyRegistry.
+ */
+export interface PolicyRegistryConfig {
+    /**
+     * Maximum number of historical (non-active) bundle versions to retain.
+     * Oldest entries are dropped when the limit is exceeded.
+     * Defaults to 10.
+     */
+    maxHistorySize?: number;
+    /**
+     * Options forwarded to `loadPolicyBundle()` for every bundle load.
+     */
+    loaderOptions?: PolicyLoaderOptions;
+}
+/**
+ * PolicyRegistry — Versioned policy bundle manager.
+ *
+ * Maintains the full bundle lifecycle: loaded → simulating → promoting → active.
+ * Enforces that promotion to `active` (enforcement mode) requires:
+ *   1. A simulation report to have been attached (evidence of simulation).
+ *   2. The divergence gate to be passing (rate below threshold).
+ *
+ * Usage:
+ * ```ts
+ * const registry = new PolicyRegistry();
+ *
+ * // Load a new candidate bundle
+ * const loadResult = registry.loadCandidate(signedBundle);
+ *
+ * // After simulation, attach the report
+ * registry.attachSimulationReport(divergenceReport, gateResult);
+ *
+ * // Promote when gate passes
+ * const promoteResult = registry.promote();
+ *
+ * // Rollback if something goes wrong
+ * registry.rollback();
+ * ```
+ */
+export declare class PolicyRegistry {
+    private _current;
+    private _candidate;
+    private _history;
+    readonly DEFAULT_HISTORY_SIZE = 10;
+    private readonly _maxHistorySize;
+    private readonly _loaderOptions;
+    constructor(config?: PolicyRegistryConfig);
+    /**
+     * loadCandidate — Load a signed policy bundle as the pending candidate.
+     *
+     * Replaces any existing candidate. The candidate must be simulated and
+     * have its gate checked before it can be promoted to active.
+     *
+     * @param bundle  — The signed bundle to load.
+     * @returns `PolicyLoadResult` indicating success or validation failure.
+     */
+    loadCandidate(bundle: SignedPolicyBundle<PolicyBundlePayload>): PolicyLoadResult;
+    /**
+     * markSimulating — Transition candidate to `simulating` state.
+     *
+     * Called by the `/policy simulate` command when a simulation pipeline
+     * is started. Validates that a candidate is loaded and in `loaded` state.
+     *
+     * @returns true if the state was successfully advanced.
+     */
+    markSimulating(): boolean;
+    /**
+     * attachSimulationReport — Attach divergence report and gate result to candidate.
+     *
+     * Advances the candidate to `promoting` state, which is a prerequisite for
+     * calling `promote()`.
+     *
+     * @param report     — The divergence report from the simulation run.
+     * @param gateResult — The gate evaluation at report time.
+     * @returns true if the evidence was attached.
+     */
+    attachSimulationReport(report: DivergenceReport, gateResult: EnforceGateResult): boolean;
+    /**
+     * promote — Promote the candidate bundle to active enforcement.
+     *
+     * Blocked unless:
+     *   - A candidate exists in `promoting` state (simulation evidence attached).
+     *   - The attached gate result is `passing`.
+     *
+     * On success, the previous active bundle moves to history.
+     *
+     * @param force — Skip gate check. Use only for testing; not for production use.
+     */
+    promote(force?: boolean): PromoteResult;
+    /**
+     * rollback — Restore the previous active bundle.
+     *
+     * Moves the current active bundle to history and restores the most recent
+     * previously-active bundle from history.
+     *
+     * @returns `RollbackResult` indicating success or failure.
+     */
+    rollback(): RollbackResult;
+    /**
+     * diff — Produce a structural diff between two bundle rule sets.
+     *
+     * Compares `from` (defaults to current active) and `to` (defaults to candidate).
+     * Rules are matched by `id` field.
+     *
+     * @param fromRules — Override the "from" rule set (defaults to current active).
+     * @param toRules   — Override the "to" rule set (defaults to candidate).
+     */
+    diff(fromRules?: PolicyRule[], toRules?: PolicyRule[]): PolicyDiffResult | null;
+    /** Returns the currently active bundle version, or null if none loaded. */
+    getCurrent(): PolicyBundleVersion | null;
+    /** Returns the candidate bundle version, or null if none loaded. */
+    getCandidate(): PolicyBundleVersion | null;
+    /** Returns the bundle history (previous active bundles), oldest first. */
+    getHistory(): PolicyBundleVersion[];
+    /**
+     * getSimulationMode — Returns the recommended simulation mode based on
+     * whether the candidate has simulation evidence.
+     *
+     * This is a hint for the command handler; callers choose the actual mode.
+     */
+    getSimulationMode(): SimulationMode;
+    private _archiveVersion;
+}
+//# sourceMappingURL=policy-registry.d.ts.map

package/dist/_internal/platform/runtime/permissions/policy-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-registry.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/permissions/policy-registry.ts"],"names":[],"mappings":"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"}

package/dist/_internal/platform/runtime/permissions/policy-registry.js

@@ -0,0 +1,307 @@
+/**
+ * Policy-as-Code registry.
+ *
+ * Manages versioned policy bundles with promote/rollback semantics.
+ * Enforces the rule that no bundle may move to enforcement without
+ * prior simulation evidence and a passing divergence gate.
+ *
+ * Bundle lifecycle:
+ *   loaded → simulating → promoting (gate check) → active (enforced)
+ *
+ * At any time:
+ *   - `current`   — the bundle whose rules are actively enforced
+ *   - `candidate` — a loaded bundle awaiting simulation before promotion
+ *   - `history`   — previous active bundles, kept for rollback
+ */
+import { loadPolicyBundle } from './policy-loader.js';
+// ── PolicyRegistry ─────────────────────────────────────────────────────────────
+/**
+ * PolicyRegistry — Versioned policy bundle manager.
+ *
+ * Maintains the full bundle lifecycle: loaded → simulating → promoting → active.
+ * Enforces that promotion to `active` (enforcement mode) requires:
+ *   1. A simulation report to have been attached (evidence of simulation).
+ *   2. The divergence gate to be passing (rate below threshold).
+ *
+ * Usage:
+ * ```ts
+ * const registry = new PolicyRegistry();
+ *
+ * // Load a new candidate bundle
+ * const loadResult = registry.loadCandidate(signedBundle);
+ *
+ * // After simulation, attach the report
+ * registry.attachSimulationReport(divergenceReport, gateResult);
+ *
+ * // Promote when gate passes
+ * const promoteResult = registry.promote();
+ *
+ * // Rollback if something goes wrong
+ * registry.rollback();
+ * ```
+ */
+export class PolicyRegistry {
+    _current = null;
+    _candidate = null;
+    _history = [];
+    DEFAULT_HISTORY_SIZE = 10;
+    _maxHistorySize;
+    _loaderOptions;
+    constructor(config = {}) {
+        this._maxHistorySize = config.maxHistorySize ?? this.DEFAULT_HISTORY_SIZE;
+        this._loaderOptions = config.loaderOptions ?? {};
+    }
+    // ── Loading ──────────────────────────────────────────────────────────────────
+    /**
+     * loadCandidate — Load a signed policy bundle as the pending candidate.
+     *
+     * Replaces any existing candidate. The candidate must be simulated and
+     * have its gate checked before it can be promoted to active.
+     *
+     * @param bundle  — The signed bundle to load.
+     * @returns `PolicyLoadResult` indicating success or validation failure.
+     */
+    loadCandidate(bundle) {
+        const result = loadPolicyBundle(bundle, this._loaderOptions);
+        if (!result.ok) {
+            return result;
+        }
+        const version = {
+            bundle,
+            provenance: result.provenance,
+            rules: result.rules ?? [],
+            state: 'loaded',
+            loadedAt: new Date().toISOString(),
+        };
+        this._candidate = version;
+        return result;
+    }
+    // ── Simulation evidence ───────────────────────────────────────────────────────
+    /**
+     * markSimulating — Transition candidate to `simulating` state.
+     *
+     * Called by the `/policy simulate` command when a simulation pipeline
+     * is started. Validates that a candidate is loaded and in `loaded` state.
+     *
+     * @returns true if the state was successfully advanced.
+     */
+    markSimulating() {
+        if (!this._candidate || this._candidate.state !== 'loaded') {
+            return false;
+        }
+        this._candidate = { ...this._candidate, state: 'simulating' };
+        return true;
+    }
+    /**
+     * attachSimulationReport — Attach divergence report and gate result to candidate.
+     *
+     * Advances the candidate to `promoting` state, which is a prerequisite for
+     * calling `promote()`.
+     *
+     * @param report     — The divergence report from the simulation run.
+     * @param gateResult — The gate evaluation at report time.
+     * @returns true if the evidence was attached.
+     */
+    attachSimulationReport(report, gateResult) {
+        if (!this._candidate || this._candidate.state !== 'simulating') {
+            return false;
+        }
+        this._candidate = {
+            ...this._candidate,
+            state: 'promoting',
+            simulationReport: report,
+            gateResult,
+        };
+        return true;
+    }
+    // ── Promotion ─────────────────────────────────────────────────────────────────
+    /**
+     * promote — Promote the candidate bundle to active enforcement.
+     *
+     * Blocked unless:
+     *   - A candidate exists in `promoting` state (simulation evidence attached).
+     *   - The attached gate result is `passing`.
+     *
+     * On success, the previous active bundle moves to history.
+     *
+     * @param force — Skip gate check. Use only for testing; not for production use.
+     */
+    promote(force = false) {
+        if (!this._candidate) {
+            return { ok: false, error: 'No candidate bundle loaded.' };
+        }
+        if (this._candidate.state === 'loaded') {
+            return {
+                ok: false,
+                error: 'Candidate has not been simulated. Run `/policy simulate` first to collect divergence evidence.',
+            };
+        }
+        if (this._candidate.state === 'simulating') {
+            return {
+                ok: false,
+                error: 'Simulation is in progress. Attach a divergence report before promoting.',
+            };
+        }
+        if (this._candidate.state !== 'promoting') {
+            return {
+                ok: false,
+                error: `Candidate is in unexpected state: "${this._candidate.state}".`,
+            };
+        }
+        const gateResult = this._candidate.gateResult;
+        if (!gateResult) {
+            throw new Error('Invariant violation: candidate is in "promoting" state but gateResult is missing. ' +
+                'attachSimulationReport() must be called before promote().');
+        }
+        if (!force && gateResult.status === 'blocked') {
+            const rateStr = gateResult.divergenceRate !== undefined
+                ? `${(gateResult.divergenceRate * 100).toFixed(1)}%`
+                : 'unknown';
+            return {
+                ok: false,
+                gate: gateResult,
+                error: `Promotion blocked: divergence gate is "${gateResult.status}" ` +
+                    `(rate ${rateStr} exceeds threshold ` +
+                    `${(gateResult.threshold * 100).toFixed(1)}%). ` +
+                    `Reduce divergence or run more evaluations before promoting.`,
+            };
+        }
+        const now = new Date().toISOString();
+        // Archive the current active bundle
+        if (this._current) {
+            this._archiveVersion({ ...this._current });
+        }
+        // Promote candidate to active
+        this._current = {
+            ...this._candidate,
+            state: 'active',
+            activatedAt: now,
+        };
+        this._candidate = null;
+        return {
+            ok: true,
+            gate: gateResult,
+            bundleId: this._current.bundle.bundleId,
+        };
+    }
+    // ── Rollback ──────────────────────────────────────────────────────────────────
+    /**
+     * rollback — Restore the previous active bundle.
+     *
+     * Moves the current active bundle to history and restores the most recent
+     * previously-active bundle from history.
+     *
+     * @returns `RollbackResult` indicating success or failure.
+     */
+    rollback() {
+        const previous = this._history.findLast((v) => v.state === 'active');
+        if (!previous) {
+            return {
+                ok: false,
+                error: 'No previous bundle version available for rollback.',
+            };
+        }
+        const now = new Date().toISOString();
+        // Archive current active bundle as rolled-back
+        if (this._current) {
+            this._archiveVersion({ ...this._current, state: 'rolled-back', rolledBackAt: now });
+        }
+        // Remove the restored version from history and set as current
+        this._history = this._history.filter((v) => v !== previous);
+        this._current = { ...previous, state: 'active', activatedAt: now };
+        return {
+            ok: true,
+            restoredBundleId: this._current.bundle.bundleId,
+        };
+    }
+    // ── Diff ──────────────────────────────────────────────────────────────────────
+    /**
+     * diff — Produce a structural diff between two bundle rule sets.
+     *
+     * Compares `from` (defaults to current active) and `to` (defaults to candidate).
+     * Rules are matched by `id` field.
+     *
+     * @param fromRules — Override the "from" rule set (defaults to current active).
+     * @param toRules   — Override the "to" rule set (defaults to candidate).
+     */
+    diff(fromRules, toRules) {
+        const from = fromRules ?? this._current?.rules;
+        const to = toRules ?? this._candidate?.rules;
+        if (!from || !to) {
+            return null;
+        }
+        const fromId = this._current?.bundle.bundleId ?? 'unknown';
+        const toId = this._candidate?.bundle.bundleId ?? 'unknown';
+        const fromMap = new Map(from.map((r) => [r.id, r]));
+        const toMap = new Map(to.map((r) => [r.id, r]));
+        const removed = [];
+        const added = [];
+        const changed = [];
+        const unchanged = [];
+        // Check from → to (removed, changed, unchanged)
+        for (const [id, fromRule] of fromMap) {
+            const toRule = toMap.get(id);
+            if (!toRule) {
+                removed.push(fromRule);
+                // Safe: PolicyRule objects are constructed uniformly with consistent key ordering
+                // (all shapes extend BaseRule and are created only through controlled factory paths),
+                // so JSON.stringify produces a stable, deterministic representation for deep equality.
+            }
+            else if (JSON.stringify(fromRule) !== JSON.stringify(toRule)) {
+                changed.push({ ruleId: id, from: fromRule, to: toRule });
+            }
+            else {
+                unchanged.push(fromRule);
+            }
+        }
+        // Check to → from (added)
+        for (const [id, toRule] of toMap) {
+            if (!fromMap.has(id)) {
+                added.push(toRule);
+            }
+        }
+        return {
+            fromBundleId: fromId,
+            toBundleId: toId,
+            removed,
+            added,
+            changed,
+            unchanged,
+            totalChanges: added.length + removed.length + changed.length,
+        };
+    }
+    // ── Accessors ─────────────────────────────────────────────────────────────────
+    /** Returns the currently active bundle version, or null if none loaded. */
+    getCurrent() {
+        return this._current;
+    }
+    /** Returns the candidate bundle version, or null if none loaded. */
+    getCandidate() {
+        return this._candidate;
+    }
+    /** Returns the bundle history (previous active bundles), oldest first. */
+    getHistory() {
+        return [...this._history];
+    }
+    /**
+     * getSimulationMode — Returns the recommended simulation mode based on
+     * whether the candidate has simulation evidence.
+     *
+     * This is a hint for the command handler; callers choose the actual mode.
+     */
+    getSimulationMode() {
+        if (!this._candidate)
+            return 'simulation-only';
+        if (this._candidate.state === 'loaded')
+            return 'simulation-only';
+        return 'warn-on-divergence';
+    }
+    // ── Private helpers ───────────────────────────────────────────────────────────
+    _archiveVersion(version) {
+        this._history.push(version);
+        // Trim to max history size (keep most recent)
+        if (this._history.length > this._maxHistorySize) {
+            this._history = this._history.slice(-this._maxHistorySize);
+        }
+    }
+}

package/dist/_internal/platform/runtime/permissions/policy-signer.d.ts

@@ -0,0 +1,95 @@
+/** SDK-owned platform module. This implementation is maintained in goodvibes-sdk. */
+/**
+ * Opaque identifier for a specific policy bundle instance.
+ *
+ * Used to correlate decisions back to the bundle that produced them.
+ * Typically a content hash or UUID assigned at bundle creation.
+ */
+export type PolicyBundleId = string;
+/**
+ * Signature validation outcome for a loaded policy bundle.
+ *
+ * - `valid`    — Signature present and verified against the payload.
+ * - `invalid`  — Signature present but verification failed (tampered/wrong key).
+ * - `missing`  — No signature field present in the bundle (returned by verifyBundle directly).
+ * - `unsigned` — Bundle has no signature field; loader uses this in non-managed mode.
+ * - `skipped`  — Signature check was bypassed (no key supplied).
+ */
+export type SignatureStatus = 'valid' | 'invalid' | 'missing' | 'unsigned' | 'skipped';
+/**
+ * Describes the origin of the policy bundle for audit and UI display.
+ *
+ * - `local-file`  — Loaded from a local filesystem path.
+ * - `remote-url`  — Fetched from a remote URL (managed infra).
+ * - `inline`      — Embedded directly in runtime configuration.
+ * - `test-fixture`— Created by test infrastructure; never production.
+ */
+export type ProvenanceSource = 'local-file' | 'remote-url' | 'inline' | 'test-fixture';
+/**
+ * A signed policy bundle as it appears on disk or over the wire.
+ *
+ * The `signature` field contains the hex-encoded HMAC-SHA256 digest of
+ * the canonical JSON serialisation of `{ bundleId, issuedAt, issuer, payload }`.
+ */
+export interface SignedPolicyBundle<T = unknown> {
+    /** Opaque bundle identifier (UUID or content hash). */
+    bundleId: PolicyBundleId;
+    /** ISO 8601 timestamp of when the bundle was signed. */
+    issuedAt: string;
+    /** The actual policy payload (rules array, metadata, etc.). */
+    payload: T;
+    /**
+     * Hex-encoded HMAC-SHA256 of the canonical JSON of `{ bundleId, issuedAt, issuer, payload }`.
+     * Absent when the bundle is unsigned.
+     */
+    signature?: string;
+    /** Human-readable hint about the signer or issuer. */
+    issuer?: string;
+}
+/**
+ * Result returned by `verifyBundle()`.
+ */
+export interface VerifyResult {
+    /** Whether the bundle signature is valid (false for missing/invalid). */
+    ok: boolean;
+    /** Validation outcome detail. */
+    status: SignatureStatus;
+    /** Human-readable explanation of the outcome. */
+    message: string;
+}
+/**
+ * canonicalise — Produces a deterministic JSON string for the given value.
+ *
+ * Keys are sorted recursively so that the representation is stable
+ * regardless of insertion order, ensuring consistent HMAC inputs.
+ *
+ * @param value — The value to serialise.
+ */
+export declare function canonicalise(value: unknown): string;
+/**
+ * signBundle — Creates a signed policy bundle from a payload.
+ *
+ * Generates a hex-encoded HMAC-SHA256 signature over the canonical JSON
+ * of the payload and embeds it in the returned `SignedPolicyBundle`.
+ *
+ * @param bundleId — Unique identifier for this bundle.
+ * @param payload  — The policy payload to sign.
+ * @param key      — Raw signing key (Buffer or hex string).
+ * @param issuer   — Optional human-readable issuer label.
+ */
+export declare function signBundle<T>(bundleId: PolicyBundleId, payload: T, key: Buffer | string, issuer?: string): SignedPolicyBundle<T>;
+/**
+ * verifyBundle — Validates the HMAC-SHA256 signature of a policy bundle.
+ *
+ * Computes the expected HMAC over the canonical payload and performs
+ * a constant-time comparison against the stored signature to prevent
+ * timing side-channel attacks.
+ *
+ * Returns `{ ok: false, status: 'missing' }` when the bundle carries no
+ * signature field. Callers decide whether to accept unsigned bundles.
+ *
+ * @param bundle — The bundle to verify.
+ * @param key    — The verification key (Buffer or hex string).
+ */
+export declare function verifyBundle<T>(bundle: SignedPolicyBundle<T>, key: Buffer | string): VerifyResult;
+//# sourceMappingURL=policy-signer.d.ts.map

package/dist/_internal/platform/runtime/permissions/policy-signer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-signer.d.ts","sourceRoot":"","sources":["../../../../../src/_internal/platform/runtime/permissions/policy-signer.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAiBrF;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC;;;;;;;;GAQG;AACH,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,SAAS,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvF;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,GAAG,YAAY,GAAG,YAAY,GAAG,QAAQ,GAAG,cAAc,CAAC;AAIvF;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC,GAAG,OAAO;IAC7C,uDAAuD;IACvD,QAAQ,EAAE,cAAc,CAAC;IACzB,wDAAwD;IACxD,QAAQ,EAAE,MAAM,CAAC;IACjB,+DAA+D;IAC/D,OAAO,EAAE,CAAC,CAAC;IACX;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,EAAE,EAAE,OAAO,CAAC;IACZ,iCAAiC;IACjC,MAAM,EAAE,eAAe,CAAC;IACxB,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAWnD;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,QAAQ,EAAE,cAAc,EACxB,OAAO,EAAE,CAAC,EACV,GAAG,EAAE,MAAM,GAAG,MAAM,EACpB,MAAM,CAAC,EAAE,MAAM,GACd,kBAAkB,CAAC,CAAC,CAAC,CAiBvB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,MAAM,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAC7B,GAAG,EAAE,MAAM,GAAG,MAAM,GACnB,YAAY,CAyEd"}