@gate-forge/pack-playwright 0.1.0

package/dist/supervisor/drain.js

@@ -0,0 +1,235 @@
+/**
+ * The supervisor's spool drain (enforcement-review fix 3): while the
+ * supervised runner executes, the trusted CLI polls the runner-side
+ * lifecycle spool and performs the witness's SUPERVISOR calls itself —
+ * session open on `testBegin`, session close with the observed outcome
+ * on `testEnd`. The runner child holds no supervisor rights at all: it
+ * writes spool events (identities and outcomes, no secrets), and the
+ * witness accepts session lifecycle ONLY from this verifier-key-
+ * authenticated channel. On stop, the drain performs a final sweep and
+ * force-closes any session the runner left open (a crashed worker can
+ * never leave the witness holding an open session past the run).
+ *
+ * SERVER-WITNESSED persistence channel: the drain also polls the
+ * persistence-intents spool (`persistence-intents.jsonl` — claim INTENTS
+ * the supervised suite may only WRITE) and forwards each one to the
+ * witness's verifier-key surface, where the adapter SERVER PROBE runs
+ * witness-side. When `serverE2eObligations` is supplied (the trusted
+ * mapping layer's `kind: server-e2e` declarations), the drain registers
+ * them BEFORE forwarding anything: the witness then stamps witnessed
+ * `channel: 'server'` persistence records for those obligations only.
+ * A refused/failed intent resolves to a typed failure recorded here and
+ * in the logs — never to satisfaction (fail closed; the claim simply
+ * stays blocking).
+ */
+import { CAUSE_NEXT_ACTIONS } from '@gate-forge/core';
+import { WitnessRequestError } from '../fixture/witness-client.js';
+import { SupervisorClient } from './client.js';
+import { persistenceIntentsPathFor, readPersistenceIntents, readSpoolEvents, spoolPathFor, } from './spool.js';
+/** Default cadence between spool polls (the fixture's resolve waits 5s). */
+export const DEFAULT_DRAIN_POLL_MS = 50;
+/**
+ * Starts the spool drain loop for one supervised run.
+ *
+ * Args:
+ *   options: stateDir + runId locate the spools; witnessUrl/runToken/
+ *     verifierKey authenticate the supervisor channel; pollMs tunes the
+ *     poll cadence (tests only); serverE2eObligations, when provided,
+ *     are registered BEFORE any intent forwarding (the trusted mapping
+ *     layer's `kind: server-e2e` declarations — the witness stamps
+ *     server-channel records for these obligations only).
+ *
+ * Returns:
+ *   SpoolDrainHandle: awaitable stop (final drain + force-close).
+ */
+export function startSupervisorSpoolDrain(options) {
+    const client = new SupervisorClient(options.witnessUrl, options.runToken, options.verifierKey);
+    const spoolFile = spoolPathFor(options.stateDir, options.runId);
+    const intentsFile = persistenceIntentsPathFor(options.stateDir, options.runId);
+    const pollMs = options.pollMs ?? DEFAULT_DRAIN_POLL_MS;
+    const openByWorker = new Map();
+    const endedTests = new Set();
+    const conflicts = [];
+    const intentFailures = [];
+    let offset = 0;
+    let intentsOffset = 0;
+    let running = true;
+    let settling = Promise.resolve();
+    const slotKey = (workerIndex, testId) => `${String(workerIndex)}\u0000${testId}`;
+    const openSessionFor = async (event) => {
+        const workerIndex = event.workerIndex;
+        const existing = openByWorker.get(workerIndex);
+        if (existing !== undefined && existing.testId === event.testId)
+            return; // idempotent re-begin
+        if (existing !== undefined) {
+            // A second begin over an open worker slot: genuine serial reporter
+            // events never do this (one test per worker at a time). The FIRST
+            // session stands (a forgery must not displace it); the collision is
+            // recorded and fails the run closed downstream.
+            conflicts.push(`lifecycle conflict: worker ${String(workerIndex)} began '${event.testId}' while ` +
+                `'${existing.testId}' was still open — a duplicate begin never occurs in a genuine ` +
+                'serial run (forged or confused lifecycle events fail closed)');
+            return;
+        }
+        if (endedTests.has(slotKey(workerIndex, event.testId))) {
+            conflicts.push(`lifecycle conflict: worker ${String(workerIndex)} re-began already-ended test ` +
+                `'${event.testId}' — a second lifecycle for the same test never occurs in a genuine ` +
+                'run (forged or confused lifecycle events fail closed)');
+            return;
+        }
+        const opened = await client.openSession({
+            testId: event.testId,
+            workerIndex,
+            ...(event.file !== null ? { file: event.file } : {}),
+            ...(event.titlePath.length > 0 ? { titlePath: event.titlePath } : {}),
+            ...(event.project !== null ? { project: event.project } : {}),
+            ...(event.claims !== undefined && event.claims.length > 0 ? { claims: event.claims } : {}),
+        });
+        openByWorker.set(workerIndex, { sessionId: opened.sessionId, testId: event.testId });
+    };
+    const sealQuietly = async (slot, outcome) => {
+        try {
+            await client.closeSession({ sessionId: slot.sessionId, ...(outcome !== undefined ? { outcome } : {}) });
+        }
+        catch (error) {
+            // Unknown/already-sealed sessions are re-delivery noise; anything
+            // else surfaces in the trace grading (an unsealable session never
+            // reads as passed).
+            if (!(error instanceof WitnessRequestError)) {
+                console.warn(`[gateforge] supervisor session close failed: ${error.message}`);
+            }
+        }
+    };
+    const handleEvent = async (event) => {
+        if (event.kind === 'testBegin') {
+            await openSessionFor(event);
+            return;
+        }
+        if (event.kind === 'testEnd') {
+            const slot = openByWorker.get(event.workerIndex);
+            if (slot !== undefined && slot.testId === event.testId) {
+                openByWorker.delete(event.workerIndex);
+                endedTests.add(slotKey(event.workerIndex, event.testId));
+                await sealQuietly(slot, event.outcome);
+                return;
+            }
+            // An end with no matching open begin: genuine reporter events are
+            // always begin/end paired. A lone end is forgery or confusion —
+            // record it and fail the run closed downstream (never open or seal
+            // anything for it).
+            conflicts.push(`lifecycle conflict: worker ${String(event.workerIndex)} ended '${event.testId}' with no ` +
+                'matching open begin — a lone end never occurs in a genuine run (forged or confused ' +
+                'lifecycle events fail closed)');
+        }
+    };
+    /**
+     * Resolves the typed witness cause of a refused intent into its §5.4
+     * next action (the witness returns the cause code on the error
+     * `detail`); unmapped causes still surface verbatim — never silently.
+     */
+    const nextActionFor = (cause) => {
+        if (cause === null)
+            return null;
+        return cause in CAUSE_NEXT_ACTIONS ? CAUSE_NEXT_ACTIONS[cause] : null;
+    };
+    /**
+     * Forwards one drained persistence intent to the witness. Every
+     * refusal is a TYPED failure recorded for the run report: the claim
+     * stays blocking (no witnessed record exists), and the failure text
+     * names the cause and next action — an intent never resolves to
+     * satisfaction on probe/adapter/declaration/replay trouble.
+     */
+    const handleIntent = async (intent) => {
+        try {
+            await client.verifyServerPersistence({
+                resourceId: intent.entity,
+                claimId: intent.claimId,
+                operation: intent.operation,
+                phase: intent.phase,
+                intent: intent.intent,
+                key: intent.key,
+                sequence: intent.sequence,
+                testId: intent.testId,
+            });
+        }
+        catch (error) {
+            const cause = error instanceof WitnessRequestError ? error.detail : null;
+            const nextAction = nextActionFor(cause);
+            const message = `server persistence intent (${intent.phase}, sequence ${String(intent.sequence)}) for ` +
+                `'${intent.claimId}' failed${cause !== null ? ` [${cause}]` : ''}: ` +
+                `${error instanceof Error ? error.message : String(error)}` +
+                `${nextAction !== null ? ` — next: ${nextAction}` : ''}`;
+            intentFailures.push(message);
+            console.warn(`[gateforge] ${message}`);
+        }
+    };
+    const drainOnce = async () => {
+        const { events, nextOffset } = readSpoolEvents(spoolFile, offset);
+        offset = nextOffset;
+        for (const event of events) {
+            const previous = settling;
+            settling = previous
+                .then(() => handleEvent(event))
+                .catch((error) => {
+                // A refused open (e.g. outside the registered expected set) is
+                // logged once; the witness-side refusal is the enforcement —
+                // the suite's submissions then fail closed on their own.
+                console.warn(`[gateforge] supervisor drain could not process a '${event.kind}' event for ` +
+                    `'${event.testId}': ${error.message}`);
+            });
+        }
+        // Persistence claim intents (server-witnessed channel): forwarded in
+        // file order under the same serialization as the lifecycle events,
+        // so per-claim sequences are enforced in order.
+        const drainedIntents = readPersistenceIntents(intentsFile, intentsOffset);
+        intentsOffset = drainedIntents.nextOffset;
+        for (const intent of drainedIntents.intents) {
+            const previous = settling;
+            settling = previous
+                .then(() => handleIntent(intent))
+                .catch((error) => {
+                console.warn(`[gateforge] supervisor drain could not forward a persistence intent for ` +
+                    `'${intent.claimId}': ${error.message}`);
+            });
+        }
+    };
+    // PRE-RUN fact: register the server-e2e declarations (the trusted
+    // mapping layer's kind resolution) before any intent can be forwarded.
+    // A refusal is a supervisor setup error and fails the run closed via
+    // the conflict channel.
+    if (options.serverE2eObligations !== undefined) {
+        const previous = settling;
+        settling = previous
+            .then(async () => {
+            await client.registerServerE2eDeclarations({
+                obligations: [...options.serverE2eObligations],
+            });
+        })
+            .catch((error) => {
+            const message = `supervisor drain could not register the server-e2e declarations: ${error.message}`;
+            conflicts.push(message);
+            console.warn(`[gateforge] ${message}`);
+        });
+    }
+    const loop = (async () => {
+        while (running) {
+            await drainOnce();
+            await new Promise((resolveSleep) => setTimeout(resolveSleep, pollMs));
+        }
+    })();
+    return {
+        stop: async () => {
+            running = false;
+            await loop.catch(() => undefined);
+            await drainOnce();
+            await settling;
+            // Force-close anything the runner left open (crash, lost contact):
+            // sealed with NO outcome — the trace grades it not-passed.
+            const leftover = [...openByWorker.values()];
+            openByWorker.clear();
+            await Promise.all(leftover.map((slot) => sealQuietly(slot, undefined)));
+            return { conflicts: [...conflicts], intentFailures: [...intentFailures] };
+        },
+    };
+}
+//# sourceMappingURL=drain.js.map

package/dist/supervisor/drain.js.map

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

package/dist/supervisor/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Supervisor surface of the Playwright evidence pack (enforcement-
+ * review fixes 2a/3): the pieces the TRUSTED CLI process uses to hold
+ * the session-lifecycle authority the runner child must never have.
+ * The persistence-intents spool + forwarding add the server-witnessed
+ * persistence channel: the suite may only WRITE intents; the witness
+ * (verifier-key surface) probes and stamps.
+ */
+export { appendSpoolEvent, readSpoolEvents, spoolPathFor } from './spool.js';
+export type { SpoolEvent, SpoolEventKind } from './spool.js';
+export { appendPersistenceIntent, readPersistenceIntents, persistenceIntentsPathFor, } from './spool.js';
+export type { PersistenceIntent, PersistenceIntentOperation, PersistenceIntentPhase, PersistenceIntentExpectation, } from './spool.js';
+export { SupervisorClient } from './client.js';
+export { startSupervisorSpoolDrain, DEFAULT_DRAIN_POLL_MS } from './drain.js';
+export type { SpoolDrainHandle } from './drain.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/supervisor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/supervisor/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC7E,YAAY,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,iBAAiB,EACjB,0BAA0B,EAC1B,sBAAsB,EACtB,4BAA4B,GAC7B,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC9E,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC"}

package/dist/supervisor/index.js

@@ -0,0 +1,13 @@
+/**
+ * Supervisor surface of the Playwright evidence pack (enforcement-
+ * review fixes 2a/3): the pieces the TRUSTED CLI process uses to hold
+ * the session-lifecycle authority the runner child must never have.
+ * The persistence-intents spool + forwarding add the server-witnessed
+ * persistence channel: the suite may only WRITE intents; the witness
+ * (verifier-key surface) probes and stamps.
+ */
+export { appendSpoolEvent, readSpoolEvents, spoolPathFor } from './spool.js';
+export { appendPersistenceIntent, readPersistenceIntents, persistenceIntentsPathFor, } from './spool.js';
+export { SupervisorClient } from './client.js';
+export { startSupervisorSpoolDrain, DEFAULT_DRAIN_POLL_MS } from './drain.js';
+//# sourceMappingURL=index.js.map

package/dist/supervisor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/supervisor/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7E,OAAO,EACL,uBAAuB,EACvB,sBAAsB,EACtB,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AAOpB,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,yBAAyB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC"}

package/dist/supervisor/spool.d.ts

@@ -0,0 +1,137 @@
+/** Which runner lifecycle transition the event represents. */
+export type SpoolEventKind = 'testBegin' | 'testEnd';
+/** One runner lifecycle event (spool line). */
+export interface SpoolEvent {
+    /** The transition: a test started or ended. */
+    kind: SpoolEventKind;
+    /** The runner-assigned test id. */
+    testId: string;
+    /** The worker running (or that ran) the test. */
+    workerIndex: number;
+    /** Repo-relative posix file of the test (identity join key). */
+    file: string | null;
+    /** Catalog-identity title path (describes + title). */
+    titlePath: string[];
+    /** Runner project name, or null when the runner exposes none. */
+    project: string | null;
+    /** testEnd only: the observed outcome ('passed' | 'failed' | …). */
+    outcome?: string;
+    /** testEnd only: 1-based attempt number (1 = first attempt). */
+    attempt?: number;
+    /** The mapped/annotated obligation claims declared for this test. */
+    claims?: string[];
+}
+/**
+ * Resolves the spool events file for one run.
+ *
+ * Args:
+ *   stateDir: absolute run-state directory.
+ *   runId: the run identity both sides agree on (env-carried).
+ *
+ * Returns:
+ *   string: absolute `<stateDir>/spool/<runId>/events.jsonl` path.
+ */
+export declare function spoolPathFor(stateDir: string, runId: string): string;
+/**
+ * Appends one lifecycle event to the run's spool (runner-side; the
+ * reporter calls this). The event is sanitized: string fields are
+ * coerced/validated, unknown statuses ride as strings, and canonical
+ * JSON escapes every control character (NUL included) — the line is
+ * NUL-safe by construction. A failed append never crashes the run: the
+ * CLI drain then simply never opens that session and the witness
+ * rejects the suite's submissions fail-closed.
+ *
+ * Args:
+ *   spoolFile: absolute spool events file (see {@link spoolPathFor}).
+ *   event: the lifecycle event to append.
+ */
+export declare function appendSpoolEvent(spoolFile: string, event: SpoolEvent): void;
+/**
+ * Reads every COMPLETE spool line past the given byte offset (CLI-side
+ * drain). A trailing fragment without its terminating newline is left
+ * for the next poll — partial writes are never parsed.
+ *
+ * Args:
+ *   spoolFile: absolute spool events file.
+ *   offset: byte offset to read from (0 = from the start).
+ *
+ * Returns:
+ *   {events, nextOffset}: parsed events in file order and the offset to
+ *   resume from (equal to `offset` when nothing complete was added).
+ */
+export declare function readSpoolEvents(spoolFile: string, offset: number): {
+    events: SpoolEvent[];
+    nextOffset: number;
+};
+/** Which CRUD operation a persistence intent serves. */
+export type PersistenceIntentOperation = 'create' | 'read' | 'update' | 'delete';
+/** Whether the intent precedes the mutation (witness before-state) or follows it (the graded observation). */
+export type PersistenceIntentPhase = 'pre' | 'post';
+/** What the suite expects the witness to observe (expectations never grade — observations do). */
+export type PersistenceIntentExpectation = 'expect-present' | 'expect-absent';
+/**
+ * One persistence claim intent (spool line). `sequence` is 1-based and
+ * strictly increasing PER `claimId` — the witness refuses replayed or
+ * out-of-order sequences, so a duplicated line can never re-drive a
+ * stale observation. `testId` must be the claiming test's identity (the
+ * claim join key: the runner test id for native claims, the sidecar
+ * logical key for mapped tests).
+ *
+ * TIMING CONTRACT for `pre` intents: the trusted drain observes the
+ * state at its NEXT poll (bounded by `pollMs`, default 50ms), so a suite
+ * writes the pre intent, allows one drain tick, THEN mutates — the
+ * witness records whatever is true when IT looks, so a mutation racing
+ * ahead of the probe honestly grades absent-before=false (the create
+ * postcondition then fails closed; it never silently passes).
+ */
+export interface PersistenceIntent {
+    /** The obligated resource id, e.g. `tenant.lead_push_outbox`. */
+    entity: string;
+    /** The persistence operation the claim requires. */
+    operation: PersistenceIntentOperation;
+    /** `pre` = before the mutation (create/update); `post` = the graded observation. */
+    phase: PersistenceIntentPhase;
+    /** The suite's expectation; the witness records what it ACTUALLY observes. */
+    intent: PersistenceIntentExpectation;
+    /** The entity key: scalar for single-column primary keys, column-keyed object for composite. */
+    key: unknown;
+    /** The claimed obligation id `<entity>:persistence:<operation>`. */
+    claimId: string;
+    /** The claiming test's id (the claim join key). */
+    testId: string;
+    /** 1-based, strictly increasing per claimId. */
+    sequence: number;
+}
+/** Resolves the intents spool file for one run (`<stateDir>/spool/<runId>/persistence-intents.jsonl`). */
+export declare function persistenceIntentsPathFor(stateDir: string, runId: string): string;
+/**
+ * Appends one persistence intent to the run's intents spool (test-side
+ * helper; the CONTRACT is the JSONL line, this writer only keeps it
+ * canonical and NUL-safe). A failed append never crashes the test: the
+ * drain then simply never forwards the intent and the claim grades
+ * fail-closed without its witnessed record.
+ *
+ * Args:
+ *   intentsFile: absolute intents spool file (see {@link persistenceIntentsPathFor}).
+ *   intent: the claim intent to append.
+ */
+export declare function appendPersistenceIntent(intentsFile: string, intent: PersistenceIntent): void;
+/**
+ * Reads every COMPLETE intent line past the given byte offset (CLI-side
+ * drain). Trailing fragments without their newline are left for the next
+ * poll; structurally invalid lines are skipped (the claim simply never
+ * resolves — fail closed, never crash the drain).
+ *
+ * Args:
+ *   intentsFile: absolute intents spool file.
+ *   offset: byte offset to read from (0 = from the start).
+ *
+ * Returns:
+ *   {intents, nextOffset}: parsed intents in file order and the offset to
+ *   resume from.
+ */
+export declare function readPersistenceIntents(intentsFile: string, offset: number): {
+    intents: PersistenceIntent[];
+    nextOffset: number;
+};
+//# sourceMappingURL=spool.d.ts.map

package/dist/supervisor/spool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spool.d.ts","sourceRoot":"","sources":["../../src/supervisor/spool.ts"],"names":[],"mappings":"AAqBA,8DAA8D;AAC9D,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,SAAS,CAAC;AAErD,+CAA+C;AAC/C,MAAM,WAAW,UAAU;IACzB,+CAA+C;IAC/C,IAAI,EAAE,cAAc,CAAC;IACrB,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,uDAAuD;IACvD,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iEAAiE;IACjE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,GAAG,IAAI,CAkC3E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb;IAAE,MAAM,EAAE,UAAU,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAuC9C;AAWD,wDAAwD;AACxD,MAAM,MAAM,0BAA0B,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEjF,8GAA8G;AAC9G,MAAM,MAAM,sBAAsB,GAAG,KAAK,GAAG,MAAM,CAAC;AAEpD,kGAAkG;AAClG,MAAM,MAAM,4BAA4B,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAE9E;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,iBAAiB;IAChC,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,SAAS,EAAE,0BAA0B,CAAC;IACtC,oFAAoF;IACpF,KAAK,EAAE,sBAAsB,CAAC;IAC9B,8EAA8E;IAC9E,MAAM,EAAE,4BAA4B,CAAC;IACrC,gGAAgG;IAChG,GAAG,EAAE,OAAO,CAAC;IACb,oEAAoE;IACpE,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0GAA0G;AAC1G,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAuB5F;AAyBD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,GACb;IAAE,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAkCtD"}