mcp-usage-control 1.0.0

package/dist/reconciliation-conformance.js

@@ -0,0 +1,211 @@
+export class OperationReconciliationConformanceError extends Error {
+    report;
+    constructor(report) {
+        const failed = report.cases.filter(result => !result.passed);
+        super(`Operation reconciliation conformance failed: ${failed
+            .map(result => `${result.name}: ${result.error ?? 'unknown failure'}`)
+            .join('; ')}`);
+        this.report = report;
+        this.name = 'OperationReconciliationConformanceError';
+    }
+}
+/** Portable scalar-only read-only reconciliation contract for optional Store implementations. */
+export async function runOperationReconciliationStoreConformance(harness) {
+    const ttlMs = harness.leaseTtlMs ?? 40;
+    assertPositiveInteger(ttlMs, 'leaseTtlMs');
+    const cases = [];
+    await runCase(harness, cases, 'absent-active-liable-settled', async (store) => {
+        const input = reconciliationInput('lifecycle');
+        const absent = await store.reconcileOperation(input);
+        assert(absent.status === 'absent', 'new logical operation must be absent');
+        const reserved = await store.reserve({ ...input, ttlMs: 5_000 });
+        assertAccepted(reserved, 'lifecycle reserve');
+        const pending = await store.reconcileOperation(input);
+        assert(pending.status === 'active' && pending.state === 'pending', 'pending state not reconciled');
+        if (pending.status === 'active') {
+            assert(pending.reservation.id === reserved.reservation.id, 'reservation identity changed');
+        }
+        await store.markLiable({ reservationId: reserved.reservation.id });
+        const liable = await store.reconcileOperation(input);
+        assert(liable.status === 'active' && liable.state === 'liable', 'liable state not reconciled');
+        await store.settle({
+            reservationId: reserved.reservation.id,
+            actualUnits: 1,
+            outcome: 'conformance_completed',
+        });
+        const settled = await store.reconcileOperation(input);
+        assert(settled.status === 'settled' && settled.reservedUnits === 1 && settled.actualUnits === 1, 'settled state not reconciled');
+    });
+    await runCase(harness, cases, 'expired-read-only', async (store) => {
+        const input = reconciliationInput('expired');
+        const reserved = await store.reserve({ ...input, ttlMs });
+        assertAccepted(reserved, 'expiring reserve');
+        await harness.waitForLeaseExpiry(ttlMs, 'expired-read-only');
+        const first = await store.reconcileOperation(input);
+        const second = await store.reconcileOperation(input);
+        assert(first.status === 'expired' && first.state === 'pending', 'expired pending state not reported');
+        assert(second.status === 'expired' && second.state === 'pending', 'reconciliation mutated expired state');
+    });
+    await runCase(harness, cases, 'mismatched-quote-fails-closed', async (store) => {
+        const input = reconciliationInput('mismatch');
+        const reserved = await store.reserve({ ...input, ttlMs: 5_000 });
+        assertAccepted(reserved, 'mismatch seed reserve');
+        await assertRejects(() => store.reconcileOperation({ ...input, units: 2 }), 'mismatched reserved units must fail closed');
+        await assertRejects(() => store.reconcileOperation({
+            ...input,
+            budgets: [{ key: 'contract:reconcile:other', limit: 10 }],
+        }), 'mismatched budgets must fail closed');
+    });
+    return { passed: cases.every(result => result.passed), cases };
+}
+/** Portable read-only initial-vector-reserve reconciliation contract. */
+export async function runVectorOperationReconciliationStoreConformance(harness) {
+    const ttlMs = harness.leaseTtlMs ?? 40;
+    assertPositiveInteger(ttlMs, 'leaseTtlMs');
+    const cases = [];
+    await runVectorCase(harness, cases, 'vector-absent-active-liable-settled', async (store) => {
+        const input = vectorReconciliationInput('lifecycle');
+        assert((await store.reconcileVectorOperation(input)).status === 'absent', 'new vector operation must be absent');
+        const reserved = await store.reserveVector({ ...input, ttlMs: 5_000 });
+        assertVectorAccepted(reserved, 'vector lifecycle reserve');
+        const pending = await store.reconcileVectorOperation(input);
+        assert(pending.status === 'active' && pending.state === 'pending', 'vector pending state not reconciled');
+        await store.markLiable({ reservationId: reserved.reservation.id });
+        const liable = await store.reconcileVectorOperation(input);
+        assert(liable.status === 'active' && liable.state === 'liable', 'vector liable state not reconciled');
+        await store.settleVector({
+            reservationId: reserved.reservation.id,
+            actualByDimension: input.dimensions.map(dimension => ({ key: dimension.key, actualUnits: dimension.units })),
+            outcome: 'conformance_completed',
+        });
+        const settled = await store.reconcileVectorOperation(input);
+        assert(settled.status === 'settled', 'vector settled state not reconciled');
+        if (settled.status === 'settled') {
+            assert(settled.reservedByDimension.length === input.dimensions.length, 'settled vector reserved topology changed');
+            assert(settled.actualByDimension.length === input.dimensions.length, 'settled vector actual topology changed');
+        }
+    });
+    await runVectorCase(harness, cases, 'vector-expired-read-only', async (store) => {
+        const input = vectorReconciliationInput('expired');
+        const reserved = await store.reserveVector({ ...input, ttlMs });
+        assertVectorAccepted(reserved, 'expiring vector reserve');
+        await harness.waitForLeaseExpiry(ttlMs, 'vector-expired-read-only');
+        const first = await store.reconcileVectorOperation(input);
+        const second = await store.reconcileVectorOperation(input);
+        assert(first.status === 'expired' && first.state === 'pending', 'expired vector pending state not reported');
+        assert(second.status === 'expired' && second.state === 'pending', 'vector reconciliation mutated expired state');
+    });
+    await runVectorCase(harness, cases, 'vector-topology-mismatch-fails-closed', async (store) => {
+        const input = vectorReconciliationInput('mismatch');
+        const reserved = await store.reserveVector({ ...input, ttlMs: 5_000 });
+        assertVectorAccepted(reserved, 'vector mismatch seed reserve');
+        await assertRejects(() => store.reconcileVectorOperation({
+            ...input,
+            dimensions: [{ ...input.dimensions[0], units: input.dimensions[0].units + 1 }, input.dimensions[1]],
+        }), 'mismatched vector units must fail closed');
+        await assertRejects(() => store.reconcileVectorOperation({
+            ...input,
+            dimensions: [{ ...input.dimensions[0], budgets: [{ key: 'contract:vector:other', limit: 10 }] }, input.dimensions[1]],
+        }), 'mismatched vector budgets must fail closed');
+    });
+    return { passed: cases.every(result => result.passed), cases };
+}
+export async function assertVectorOperationReconciliationStoreConformance(harness) {
+    const report = await runVectorOperationReconciliationStoreConformance(harness);
+    if (!report.passed)
+        throw new OperationReconciliationConformanceError(report);
+}
+export async function assertOperationReconciliationStoreConformance(harness) {
+    const report = await runOperationReconciliationStoreConformance(harness);
+    if (!report.passed)
+        throw new OperationReconciliationConformanceError(report);
+}
+async function runCase(harness, results, name, body) {
+    try {
+        const store = await harness.createStore(name);
+        await body(store);
+        results.push({ name, passed: true });
+    }
+    catch (error) {
+        results.push({ name, passed: false, error: errorMessage(error) });
+    }
+    finally {
+        try {
+            await harness.cleanup?.(name);
+        }
+        catch (error) {
+            results.push({ name: `${name}:cleanup`, passed: false, error: errorMessage(error) });
+        }
+    }
+}
+async function runVectorCase(harness, results, name, body) {
+    try {
+        const store = await harness.createStore(name);
+        await body(store);
+        results.push({ name, passed: true });
+    }
+    catch (error) {
+        results.push({ name, passed: false, error: errorMessage(error) });
+    }
+    finally {
+        try {
+            await harness.cleanup?.(name);
+        }
+        catch (error) {
+            results.push({ name: `${name}:cleanup`, passed: false, error: errorMessage(error) });
+        }
+    }
+}
+function vectorReconciliationInput(operationId) {
+    const dimensions = [
+        { key: 'requests', units: 1, budgets: [{ key: `contract:vector:${operationId}:requests`, limit: 10 }] },
+        { key: 'tokens', units: 3, budgets: [{ key: `contract:vector:${operationId}:tokens`, limit: 100 }] },
+    ];
+    return { request: request(`vector-${operationId}`), dimensions };
+}
+function assertVectorAccepted(result, context) {
+    assert(result.accepted, `${context}: expected accepted reservation`);
+}
+function reconciliationInput(operationId) {
+    return {
+        request: request(operationId),
+        units: 1,
+        budgets: [{ key: `contract:reconcile:${operationId}`, limit: 10 }],
+    };
+}
+function request(operationId) {
+    return {
+        operationId,
+        principal: { id: 'user-1', tenantId: 'tenant-1' },
+        tool: 'contract-tool',
+        args: { conformance: true },
+    };
+}
+function assertAccepted(result, context) {
+    assert(result.accepted, `${context}: expected accepted reservation`);
+}
+async function assertRejects(action, message) {
+    let rejected = false;
+    try {
+        await action();
+    }
+    catch {
+        rejected = true;
+    }
+    assert(rejected, message);
+}
+function assert(condition, message) {
+    if (!condition)
+        throw new Error(message);
+}
+function assertPositiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new RangeError(`${name} must be a positive safe integer`);
+    }
+}
+function errorMessage(error) {
+    if (error instanceof Error)
+        return `${error.name}: ${error.message}`;
+    return String(error);
+}
+//# sourceMappingURL=reconciliation-conformance.js.map

package/dist/reconciliation-conformance.js.map

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

package/dist/settlement-outcomes.d.ts

@@ -0,0 +1,24 @@
+export declare const CANONICAL_SETTLEMENT_OUTCOMES: readonly ["authorization_denied", "invalid_arguments", "pre_dispatch_rejected", "pre_dispatch_no_effect", "cancelled_before_dispatch", "completed", "proven_no_effect", "dispatched_conservative", "cancelled_after_dispatch"];
+export type CanonicalSettlementOutcome = (typeof CANONICAL_SETTLEMENT_OUTCOMES)[number];
+export type SettlementOutcomeAliases = Readonly<Record<string, CanonicalSettlementOutcome>>;
+export interface SettlementOutcomeDiagnosticSink {
+    onInvalidSettlementOutcome(): void | Promise<void>;
+}
+/**
+ * Compatibility aliases used by the built-in MCP adapter and older integrations.
+ * New integrations should emit the canonical vocabulary directly.
+ */
+export declare const DEFAULT_SETTLEMENT_OUTCOME_ALIASES: SettlementOutcomeAliases;
+/** Bounded diagnostic for integration vocabulary drift; raw input is deliberately not retained. */
+export declare class InvalidSettlementOutcomeError extends TypeError {
+    readonly code: "invalid_settlement_outcome";
+    constructor();
+}
+export declare function isCanonicalSettlementOutcome(value: unknown): value is CanonicalSettlementOutcome;
+/**
+ * Normalize a bounded consumer/domain outcome before it crosses the usage boundary.
+ * Invalid vocabulary fails before Store settlement and is distinguishable from backend failure.
+ * Diagnostic delivery is best-effort and can never replace the bounded normalization error.
+ */
+export declare function normalizeSettlementOutcome(value: unknown, aliases?: SettlementOutcomeAliases, diagnostics?: SettlementOutcomeDiagnosticSink): CanonicalSettlementOutcome;
+//# sourceMappingURL=settlement-outcomes.d.ts.map

package/dist/settlement-outcomes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-outcomes.d.ts","sourceRoot":"","sources":["../src/settlement-outcomes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,6BAA6B,gOAUhC,CAAC;AAEX,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAExF,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC,CAAC;AAE5F,MAAM,WAAW,+BAA+B;IAC9C,0BAA0B,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACpD;AAED;;;GAGG;AACH,eAAO,MAAM,kCAAkC,EAAE,wBAQ/C,CAAC;AAEH,mGAAmG;AACnG,qBAAa,6BAA8B,SAAQ,SAAS;IAC1D,QAAQ,CAAC,IAAI,EAAG,4BAA4B,CAAU;;CAMvD;AAED,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAKhG;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,wBAA6D,EACtE,WAAW,CAAC,EAAE,+BAA+B,GAC5C,0BAA0B,CAU5B"}

package/dist/settlement-outcomes.js

@@ -0,0 +1,68 @@
+export const CANONICAL_SETTLEMENT_OUTCOMES = [
+    'authorization_denied',
+    'invalid_arguments',
+    'pre_dispatch_rejected',
+    'pre_dispatch_no_effect',
+    'cancelled_before_dispatch',
+    'completed',
+    'proven_no_effect',
+    'dispatched_conservative',
+    'cancelled_after_dispatch',
+];
+/**
+ * Compatibility aliases used by the built-in MCP adapter and older integrations.
+ * New integrations should emit the canonical vocabulary directly.
+ */
+export const DEFAULT_SETTLEMENT_OUTCOME_ALIASES = Object.freeze({
+    success: 'completed',
+    tool_error: 'completed',
+    error: 'dispatched_conservative',
+    unsupported_input_required: 'dispatched_conservative',
+    input_required_round_limit: 'dispatched_conservative',
+    invalid_input_required_state: 'dispatched_conservative',
+    input_required_suspend_failed: 'dispatched_conservative',
+});
+/** Bounded diagnostic for integration vocabulary drift; raw input is deliberately not retained. */
+export class InvalidSettlementOutcomeError extends TypeError {
+    code = 'invalid_settlement_outcome';
+    constructor() {
+        super('Settlement outcome is not part of the canonical usage vocabulary');
+        this.name = 'InvalidSettlementOutcomeError';
+    }
+}
+export function isCanonicalSettlementOutcome(value) {
+    return (typeof value === 'string' &&
+        CANONICAL_SETTLEMENT_OUTCOMES.includes(value));
+}
+/**
+ * Normalize a bounded consumer/domain outcome before it crosses the usage boundary.
+ * Invalid vocabulary fails before Store settlement and is distinguishable from backend failure.
+ * Diagnostic delivery is best-effort and can never replace the bounded normalization error.
+ */
+export function normalizeSettlementOutcome(value, aliases = DEFAULT_SETTLEMENT_OUTCOME_ALIASES, diagnostics) {
+    if (isCanonicalSettlementOutcome(value))
+        return value;
+    if (typeof value !== 'string' || value.length === 0 || value.length > 128) {
+        return rejectInvalidSettlementOutcome(diagnostics);
+    }
+    const normalized = aliases[value];
+    if (normalized === undefined || !isCanonicalSettlementOutcome(normalized)) {
+        return rejectInvalidSettlementOutcome(diagnostics);
+    }
+    return normalized;
+}
+function rejectInvalidSettlementOutcome(diagnostics) {
+    if (diagnostics !== undefined) {
+        try {
+            const result = diagnostics.onInvalidSettlementOutcome();
+            if (result && typeof result.catch === 'function') {
+                void result.catch(() => undefined);
+            }
+        }
+        catch {
+            // Diagnostics are not part of settlement normalization or enforcement.
+        }
+    }
+    throw new InvalidSettlementOutcomeError();
+}
+//# sourceMappingURL=settlement-outcomes.js.map

package/dist/settlement-outcomes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settlement-outcomes.js","sourceRoot":"","sources":["../src/settlement-outcomes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,6BAA6B,GAAG;IAC3C,sBAAsB;IACtB,mBAAmB;IACnB,uBAAuB;IACvB,wBAAwB;IACxB,2BAA2B;IAC3B,WAAW;IACX,kBAAkB;IAClB,yBAAyB;IACzB,0BAA0B;CAClB,CAAC;AAUX;;;GAGG;AACH,MAAM,CAAC,MAAM,kCAAkC,GAA6B,MAAM,CAAC,MAAM,CAAC;IACxF,OAAO,EAAE,WAAW;IACpB,UAAU,EAAE,WAAW;IACvB,KAAK,EAAE,yBAAyB;IAChC,0BAA0B,EAAE,yBAAyB;IACrD,0BAA0B,EAAE,yBAAyB;IACrD,4BAA4B,EAAE,yBAAyB;IACvD,6BAA6B,EAAE,yBAAyB;CACzD,CAAC,CAAC;AAEH,mGAAmG;AACnG,MAAM,OAAO,6BAA8B,SAAQ,SAAS;IACjD,IAAI,GAAG,4BAAqC,CAAC;IAEtD;QACE,KAAK,CAAC,kEAAkE,CAAC,CAAC;QAC1E,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;IAC9C,CAAC;CACF;AAED,MAAM,UAAU,4BAA4B,CAAC,KAAc;IACzD,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACxB,6BAAmD,CAAC,QAAQ,CAAC,KAAK,CAAC,CACrE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,KAAc,EACd,UAAoC,kCAAkC,EACtE,WAA6C;IAE7C,IAAI,4BAA4B,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACtD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,GAAG,EAAE,CAAC;QAC1E,OAAO,8BAA8B,CAAC,WAAW,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,4BAA4B,CAAC,UAAU,CAAC,EAAE,CAAC;QAC1E,OAAO,8BAA8B,CAAC,WAAW,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED,SAAS,8BAA8B,CACrC,WAAwD;IAExD,IAAI,WAAW,KAAK,SAAS,EAAE,CAAC;QAC9B,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,WAAW,CAAC,0BAA0B,EAAE,CAAC;YACxD,IAAI,MAAM,IAAI,OAAQ,MAAwB,CAAC,KAAK,KAAK,UAAU,EAAE,CAAC;gBACpE,KAAM,MAAwB,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YACxD,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,uEAAuE;QACzE,CAAC;IACH,CAAC;IACD,MAAM,IAAI,6BAA6B,EAAE,CAAC;AAC5C,CAAC"}

package/dist/store-conformance.d.ts

@@ -0,0 +1,50 @@
+export * from './reconciliation-conformance.js';
+export * from './progressive-store-conformance.js';
+export * from './vector-store-conformance.js';
+import type { UsageStore } from './index.js';
+type MaybePromise<T> = T | Promise<T>;
+export interface UsageStoreConformanceHarness {
+    /**
+     * Return an isolated store transaction domain for one conformance scenario.
+     * The scenario name is stable and may be used to derive a Redis prefix,
+     * Durable Object name, Firestore collection prefix, database schema, etc.
+     */
+    createStore(scenario: string): MaybePromise<UsageStore>;
+    /**
+     * Wait until a lease with the supplied TTL is authoritatively expired for the
+     * tested store. Real stores may sleep; emulator/fake-clock harnesses may advance
+     * their store clock instead. Include any configured expiry grace here.
+     */
+    waitForLeaseExpiry(ttlMs: number, scenario: string): MaybePromise<void>;
+    /** Optional cleanup for the isolated scenario domain. */
+    cleanup?(scenario: string): MaybePromise<void>;
+    /** Lease TTL used by expiry cases. Defaults to 40 ms. */
+    leaseTtlMs?: number;
+    /** Parallel contenders used by the admission race case. Defaults to 16. */
+    concurrency?: number;
+}
+export interface UsageStoreConformanceCaseResult {
+    name: string;
+    passed: boolean;
+    error?: string;
+}
+export interface UsageStoreConformanceReport {
+    passed: boolean;
+    cases: UsageStoreConformanceCaseResult[];
+}
+export declare class UsageStoreConformanceError extends Error {
+    readonly report: UsageStoreConformanceReport;
+    constructor(report: UsageStoreConformanceReport);
+}
+/**
+ * Run the portable, provider-neutral behavioral contract for a UsageStore.
+ *
+ * Passing this suite means that the public store semantics are compatible. It
+ * does not by itself prove persistence/HA, store-time authority, network ACK
+ * ambiguity behavior, or platform-specific fault tolerance. Those production
+ * safety requirements need adapter-specific evidence in addition to this suite.
+ */
+export declare function runUsageStoreConformance(harness: UsageStoreConformanceHarness): Promise<UsageStoreConformanceReport>;
+/** Run the suite and throw a single detailed error if any case fails. */
+export declare function assertUsageStoreConformance(harness: UsageStoreConformanceHarness): Promise<UsageStoreConformanceReport>;
+//# sourceMappingURL=store-conformance.d.ts.map

package/dist/store-conformance.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-conformance.d.ts","sourceRoot":"","sources":["../src/store-conformance.ts"],"names":[],"mappings":"AAAA,cAAc,iCAAiC,CAAC;AAChD,cAAc,oCAAoC,CAAC;AACnD,cAAc,+BAA+B,CAAC;AAC9C,OAAO,KAAK,EAA4C,UAAU,EAAE,MAAM,YAAY,CAAC;AAEvF,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,4BAA4B;IAC3C;;;;OAIG;IACH,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC;IAExD;;;;OAIG;IACH,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAExE,yDAAyD;IACzD,OAAO,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAE/C,yDAAyD;IACzD,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,+BAA+B;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,2BAA2B;IAC1C,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,+BAA+B,EAAE,CAAC;CAC1C;AAED,qBAAa,0BAA2B,SAAQ,KAAK;aACvB,MAAM,EAAE,2BAA2B;gBAAnC,MAAM,EAAE,2BAA2B;CAShE;AAED;;;;;;;GAOG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CA6WtC;AAED,yEAAyE;AACzE,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,4BAA4B,GACpC,OAAO,CAAC,2BAA2B,CAAC,CAItC"}