@gate-forge/witness 0.0.0-stage → 0.9.0

package/dist/witness/bin.js

@@ -0,0 +1,254 @@
+/**
+ * Witness process entry (`gateforge-witness`): derives configuration
+ * from CLI flags and the environment and starts the loopback witness
+ * service.
+ *
+ * Usage (every flag has an env fallback; the flag wins when both are
+ * given):
+ *
+ *   gateforge-witness [--help]
+ *     [--proxy-target <url>]       start the observation proxy against
+ *                                  this loopback base URL (ADR 0004 D7)
+ *     [--mount-path <prefix>]      browser-facing mount prefix the proxy
+ *                                  strips before forwarding AND recording
+ *                                  (e.g. /api; requires --proxy-target)
+ *     [--state-dir <dir>]          manifest append at shutdown
+ *     [--classifications <path>]   classifications YAML input
+ *     [--adapters-dir <dir>]       reviewed adapters (default .gateforge/adapters)
+ *     [--target-base-url <url>]    attestation subject (GF-10, loopback)
+ *     [--target-fingerprint <m>]   expected marker (GF-13)
+ *     [--adapter-base-url <url>]   default adapter read base
+ *
+ * Env surface:
+ *   GATEFORGE_RUN_ID, GATEFORGE_RUN_TOKEN        (required; CLI contract)
+ *   GATEFORGE_PROXY_TARGET, GATEFORGE_MOUNT_PATH (observation proxy)
+ *   GATEFORGE_STATE_DIR                          (manifest append at shutdown)
+ *   GATEFORGE_ADAPTERS_DIR                       (default .gateforge/adapters)
+ *   GATEFORGE_CLASSIFICATIONS                    (classifications YAML path)
+ *   GATEFORGE_TARGET_BASE_URL                    (attestation subject, GF-10)
+ *   GATEFORGE_TARGET_FINGERPRINT                 (expected marker, GF-13)
+ *   GATEFORGE_ADAPTER_BASE_URL                   (default adapter read base)
+ *   GATEFORGE_FIXTURE_PROVIDER                 (approved fixture provider)
+ *   GATEFORGE_WITNESS_VERIFIER_KEY               (attestation verifier key)
+ *
+ * SECRETS NEVER TRAVEL ON ARGV (a process's cmdline is world-readable
+ * via /proc — the same rule `gateforge test-gates` applies): the run
+ * id/token are env-only (set by 'gateforge test-gates'), and the
+ * verifier key is read from GATEFORGE_WITNESS_VERIFIER_KEY only. With a
+ * verifier key the witness serves the MAC-attested ledger surface;
+ * without one it stays unauthenticated and downstream evaluation fails
+ * closed.
+ *
+ * The wrapper prints `GATEFORGE_WITNESS_URL=<url>` once listening — and
+ * `GATEFORGE_WITNESS_PROXY_URL=<url>` when an observation proxy is
+ * active; the process serves until SIGTERM/SIGINT.
+ */
+import { startWitness, WitnessStartupError } from './server.js';
+import { loadFixtureProvider } from './fixture-provider.js';
+import { openConfiguredQueueChannel } from '../queue/observer.js';
+import { parseChaosOptions } from './chaos.js';
+import { parseTwinShapePlan } from './twin-shapes.js';
+import { ENV_ADAPTER_BASE_URL, ENV_ADAPTERS_DIR, ENV_CHAOS_MAX_DELAY_MS, ENV_CHAOS_REORDER, ENV_CHAOS_SEED, ENV_CLASSIFICATIONS, ENV_FIXTURE_PROVIDER, ENV_MOUNT_PATH, ENV_PROXY_TARGET, ENV_RUN_ID, ENV_RUN_TOKEN, ENV_STATE_DIR, ENV_TARGET_BASE_URL, ENV_TARGET_FINGERPRINT, ENV_TWIN_INVENTORY, ENV_TWIN_QUERY_KEYS, ENV_TWIN_SHAPES, ENV_WITNESS_VERIFIER_KEY, } from '../constants.js';
+import { createRequire } from 'node:module';
+/** One-line usage (the header comment above is the long form). */
+export const WITNESS_BIN_USAGE = 'usage: gateforge-witness [--proxy-target <url>] [--mount-path <prefix>] ' +
+    '[--state-dir <dir>] [--classifications <path>] [--adapters-dir <dir>] ' +
+    '[--target-base-url <url>] [--target-fingerprint <marker>] [--adapter-base-url <url>] ' +
+    '(run id/token via GATEFORGE_RUN_ID/GATEFORGE_RUN_TOKEN; verifier key via ' +
+    'GATEFORGE_WITNESS_VERIFIER_KEY)';
+/** Flags this bin accepts (values; `--help` is handled separately). */
+const VALUE_FLAGS = new Set([
+    'proxy-target',
+    'mount-path',
+    'state-dir',
+    'classifications',
+    'adapters-dir',
+    'target-base-url',
+    'target-fingerprint',
+    'adapter-base-url',
+    'adapter-read-authorization',
+]);
+/**
+ * Parses the bin argv (`--flag value` and `--flag=value` shapes).
+ * Unknown flags and missing values fail closed with the usage line —
+ * a mis-wired harness must never silently start a half-configured
+ * witness.
+ *
+ * Args:
+ *   argv: arguments after node/script.
+ *
+ * Returns:
+ *   WitnessBinFlags: parsed flag values.
+ *
+ * Throws:
+ *   WitnessStartupError: on any malformed argv.
+ */
+function parseFlags(argv) {
+    const values = new Map();
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? '';
+        if (!token.startsWith('--')) {
+            throw new WitnessStartupError(`unexpected argument '${token}'\n${WITNESS_BIN_USAGE}`);
+        }
+        const body = token.slice(2);
+        const eq = body.indexOf('=');
+        const name = eq >= 0 ? body.slice(0, eq) : body;
+        if (name.length === 0) {
+            throw new WitnessStartupError(`invalid flag '${token}'\n${WITNESS_BIN_USAGE}`);
+        }
+        if (name === 'help') {
+            continue; // handled by the caller before parsing matters
+        }
+        if (!VALUE_FLAGS.has(name)) {
+            throw new WitnessStartupError(`unknown flag '--${name}'\n${WITNESS_BIN_USAGE}`);
+        }
+        let value = eq >= 0 ? body.slice(eq + 1) : undefined;
+        if (value === undefined) {
+            const next = argv[index + 1];
+            if (next === undefined || next.startsWith('--')) {
+                throw new WitnessStartupError(`flag '--${name}' requires a value\n${WITNESS_BIN_USAGE}`);
+            }
+            value = next;
+            index += 1;
+        }
+        if (values.has(name)) {
+            throw new WitnessStartupError(`flag '--${name}' may only be given once\n${WITNESS_BIN_USAGE}`);
+        }
+        values.set(name, value);
+    }
+    return { values };
+}
+/** Flag value or its env fallback (undefined when neither is set). */
+function flagOrEnv(flags, name, envValue) {
+    const fromFlags = flags.values.get(name);
+    if (fromFlags !== undefined && fromFlags !== '')
+        return fromFlags;
+    if (envValue !== undefined && envValue !== '')
+        return envValue;
+    return undefined;
+}
+/**
+ * The twin shape plan, or a fail-closed startup error.
+ *
+ * A malformed switch or an empty allowlist entry is the owner's
+ * configuration speaking nonsense; starting anyway would produce a
+ * run whose findings quietly mean something else.
+ */
+function parseTwinShapePlanOrFail(input) {
+    try {
+        return parseTwinShapePlan(input);
+    }
+    catch (error) {
+        throw new WitnessStartupError(error.message);
+    }
+}
+/**
+ * Reads env + argv and starts the witness.
+ *
+ * Args:
+ *   argv: CLI flags (see the module header; `--help` prints usage and
+ *     returns a never-started handle).
+ *   env: process environment.
+ *
+ * Returns:
+ *   WitnessHandle once listening (or a handle with an empty `url` for
+ *   `--help`; the wrapper skips its URL banner in that case).
+ *
+ * Throws:
+ *   WitnessStartupError / AttestationError / AdapterRegistryError:
+ *     fail-closed startup problems (exit 2 via the wrapper).
+ */
+export async function main(argv, env) {
+    if (argv.includes('--help') || argv.includes('-h')) {
+        process.stdout.write(`${WITNESS_BIN_USAGE}\n`);
+        return Object.freeze({ url: '', proxyUrl: null, stop: async () => { } });
+    }
+    const flags = parseFlags(argv);
+    const runId = env[ENV_RUN_ID];
+    const token = env[ENV_RUN_TOKEN];
+    if (runId === undefined || runId === '') {
+        throw new WitnessStartupError(`${ENV_RUN_ID} is required (set by 'gateforge test-gates')`);
+    }
+    if (token === undefined || token === '') {
+        throw new WitnessStartupError(`${ENV_RUN_TOKEN} is required (set by 'gateforge test-gates')`);
+    }
+    // Environment-only, deliberately absent from argv (world-readable
+    // /proc cmdline): the suite must never see the verifier key either way.
+    const verifierKey = env[ENV_WITNESS_VERIFIER_KEY] ?? null;
+    return startWitness({
+        runId,
+        token,
+        proxyTarget: flagOrEnv(flags, 'proxy-target', env[ENV_PROXY_TARGET]),
+        // Timing chaos (E63): the seeded release plan for proxied
+        // responses. Environment-only (like the verifier key), absent in
+        // every run that did not ask for chaos, and parsed fail-closed: a
+        // seed the witness cannot read would produce a schedule the owner
+        // could never replay.
+        chaos: parseChaosOptions({
+            seed: env[ENV_CHAOS_SEED],
+            maxDelayMs: env[ENV_CHAOS_MAX_DELAY_MS],
+            reorder: env[ENV_CHAOS_REORDER],
+        }),
+        // Twin path coverage (E64): the observation-only shape recording,
+        // the owner's query-key allowlist, and the raw twins the supervisor
+        // marked observation-only. Environment-only and absent by default,
+        // so a run without `enforcement.twinPaths` is byte-identical; a
+        // malformed switch or allowlist is a startup error the owner must
+        // see rather than a silently key-only run.
+        twinShapes: parseTwinShapePlanOrFail({
+            shapes: env[ENV_TWIN_SHAPES],
+            queryKeys: env[ENV_TWIN_QUERY_KEYS],
+            inventoryPath: env[ENV_TWIN_INVENTORY],
+        }),
+        mountPath: flagOrEnv(flags, 'mount-path', env[ENV_MOUNT_PATH]),
+        stateDir: flagOrEnv(flags, 'state-dir', env[ENV_STATE_DIR]),
+        classificationsPath: flagOrEnv(flags, 'classifications', env[ENV_CLASSIFICATIONS]),
+        adaptersDir: flagOrEnv(flags, 'adapters-dir', env[ENV_ADAPTERS_DIR] ?? '.gateforge/adapters'),
+        targetBaseUrl: flagOrEnv(flags, 'target-base-url', env[ENV_TARGET_BASE_URL]),
+        targetFingerprint: flagOrEnv(flags, 'target-fingerprint', env[ENV_TARGET_FINGERPRINT]),
+        adapterBaseUrl: flagOrEnv(flags, 'adapter-base-url', env[ENV_ADAPTER_BASE_URL]),
+        adapterReadAuthorization: flagOrEnv(flags, 'adapter-read-authorization', env['GATEFORGE_ADAPTER_READ_AUTHORIZATION']) ?? null,
+        // Strong behavior cases mint their fixtures and actor credentials
+        // through the operator's approved provider, engine-side. Without one
+        // the witness still starts and every other surface works; the cases
+        // then block with a typed cause (never a suite-supplied fallback).
+        fixtureProvider: await loadFixtureProvider(env[ENV_FIXTURE_PROVIDER] ?? null),
+        // Engine-owned queue observer: the
+        // witness reads the delivery queue itself. Absent (no `queueObserver`
+        // block in .gateforge.yml) leaves the channel null and every
+        // `engine-task` case blocks fail-closed.
+        queueChannel: await openConfiguredQueueChannel(env),
+        verifierKey,
+        engineBrowserLauncher: resolveEngineBrowserLauncher(),
+    });
+}
+/**
+ * Resolves the engine-browser launcher for a SPAWNED witness.
+ *
+ * The library surface is runner-neutral: `startWitness` takes a
+ * launcher and never assumes one. This is the process entry point, and
+ * a `gateforge-witness` process started by a Playwright user's
+ * `test-gates` must launch that user's pinned Chromium exactly as
+ * before — the ENGINE-BROWSER proof channel is a Playwright journey,
+ * and losing it would be a silent downgrade of what a run can prove.
+ *
+ * The resolution is the same CONSUMER-FIRST one the supervised run uses
+ * for the Playwright CLI: the consumer's own installed `playwright`,
+ * not the engine's. When no Playwright is resolvable the witness still
+ * starts and serves every other surface; an engine-browser action then
+ * fails closed with a typed cause instead of a crash.
+ *
+ * Returns:
+ *   EngineBrowserLauncher | undefined: the launcher, or undefined when
+ *   no Playwright is resolvable on the module path.
+ */
+function resolveEngineBrowserLauncher() {
+    try {
+        const consumerRequire = createRequire(import.meta.url);
+        return consumerRequire('playwright').chromium;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=bin.js.map

package/dist/witness/bin.js.map

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

package/dist/witness/browser.d.ts

@@ -0,0 +1,221 @@
+/**
+ * The engine-owned browser (plan Phase 1 item 4): Chromium contexts the
+ * WITNESS process creates and drives itself — one isolated context per
+ * supervisor-opened test session, closed when the session seals.
+ *
+ * Test code NEVER touches these pages: the worker holds no handle, no
+ * URL, and no capability over them. The engine executes the constrained
+ * surface operations (create/read/update/archive) with the
+ * consumer-declared locators, and observes each step itself:
+ * - the rendered control it clicked and the values it typed;
+ * - the actual application request the action caused (captured from the
+ *   engine page's own network, app-origin only);
+ * - the resulting navigation and the rendered row/form it read back.
+ *
+ * Forgery resistance (why this channel is proof):
+ * - fabricated DOM (`page.evaluate` in the worker page) is irrelevant:
+ *   the engine reads its OWN page;
+ * - mocked responses (`page.route` in the worker) are irrelevant: the
+ *   worker cannot route the engine's traffic;
+ * - direct API/Node mutations bypass the engine page entirely: no
+ *   engine action runs, so no engine-observed action/visible records
+ *   exist for them — invented suite-submitted records never satisfy;
+ * - HTTP-200-while-error: the engine asserts the rendered status
+ *   itself (created/archived values) AND captures the app response
+ *   status — a displayed error fails the action fail-closed.
+ *
+ * Surface selectors are LOCATORS, never proof: a lying descriptor only
+ * makes the engine fail to find elements (fail closed).
+ */
+import type { Browser, Page } from 'playwright';
+import { type SurfaceDescriptor, type SurfaceStep } from '../surface.js';
+/** The UI operations the engine can perform (constrained subset). */
+export type EngineOperation = 'create' | 'read' | 'update' | 'delete';
+/** One app-origin exchange the engine captured during an action. */
+export interface EngineCapturedExchange {
+    /** Uppercase method (GET, POST, ...). */
+    method: string;
+    /** Canonical observed path (query/fragment stripped). */
+    path: string;
+    /** Response status the app answered. */
+    status: number;
+    /** Response body bytes (bounded snapshot for hashing). */
+    body: Buffer;
+}
+/** What the engine observed performing one action. */
+export interface EngineActionObservation {
+    /** Entity id OBSERVED from the rendered list (never declared). */
+    entityId: string;
+    /** The exact input values the engine typed (exact-value echo source). */
+    enteredFields: Record<string, string>;
+    /** The rendered fields the engine read back after the action. */
+    renderedFields: Record<string, string>;
+    /** App-origin exchanges captured inside the action window. */
+    exchanges: EngineCapturedExchange[];
+    /** Engine-side pre-observation marker (filled by the witness layer). */
+    preObservationId?: string;
+}
+/** Fail-closed engine browser error (surfaced as 409/503 downstream). */
+export declare class EngineBrowserError extends Error {
+    constructor(message: string);
+}
+/** The browser launcher the engine drives (default: pinned Chromium). */
+export interface EngineBrowserLauncher {
+    launch(options?: Record<string, unknown>): Promise<Browser>;
+}
+/**
+ * The minimal page surface the wizard step driver needs. A real
+ * Playwright Page satisfies it structurally, and stub pages in tests
+ * implement exactly this — no browser required to prove the walk.
+ */
+export interface StepPage {
+    goto(url: string, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    waitForSelector(selector: string, options?: {
+        timeout?: number;
+    }): Promise<unknown>;
+    locator(selector: string): {
+        click(options?: {
+            timeout?: number;
+        }): Promise<void>;
+        fill(value: string, options?: {
+            timeout?: number;
+        }): Promise<void>;
+        check(options?: {
+            timeout?: number;
+        }): Promise<void>;
+    };
+    keyboard: {
+        press(key: string): Promise<void>;
+    };
+}
+/**
+ * Walks one validated wizard step list on the engine-owned page
+ * (surface v2 create). Every interaction runs here, engine-side: the
+ * test supplies intent (field values) only. A step referencing an
+ * input field the journey did not provide fails closed — the engine
+ * never invents values. Unknown shapes are unreachable post-
+ * validation, but still refused defensively (never silently skipped).
+ *
+ * Args:
+ *   page: the engine-owned page (real or structural stub).
+ *   appBase: the trusted attested subject origin (never suite input).
+ *   steps: the validated wizard walk, in order.
+ *   fields: the journey's declared input values, keyed by field name.
+ */
+export declare function driveCreateSteps(page: StepPage, appBase: string, steps: readonly SurfaceStep[], fields: Record<string, string>): Promise<void>;
+/**
+ * Owns the engine Chromium instance and its per-session contexts.
+ *
+ * Args:
+ *   launcher: browser launcher (default: the pinned Chromium). Tests
+ *     inject a failing launcher to prove the fail-closed path; the
+ *     driving and observation below stay engine code regardless of
+ *     which executable launches.
+ */
+export declare class EngineBrowserManager {
+    private readonly launcher;
+    private browser;
+    private launching;
+    private readonly sessions;
+    /**
+     * Pinned `--host-resolver-rules` value binding every attested hostname
+     * to its startup-approved loopback IPs. Set once at witness startup
+     * (before any launch); the browser is then incapable of resolving
+     * those names anywhere but loopback, regardless of later DNS changes.
+     */
+    private dnsPinRules;
+    /**
+     * @param launcher - the browser launcher to use. REQUIRED: this
+     *   package is runner-neutral and must not assume a browser. The
+     *   Playwright-defaulting subclass lives in
+     *   `@gate-forge/pack-playwright`.
+     */
+    constructor(launcher: EngineBrowserLauncher);
+    /**
+     * Installs the DNS pin rules for the next (first) launch.
+     *
+     * Args:
+     *   rules: the `--host-resolver-rules` value, or null when nothing is
+     *     pinned (plain launch, previous behavior).
+     *
+     * Throws:
+     *   EngineBrowserError: when the browser already launched — pins must
+     *   precede every navigation (fail closed, never silently unbound).
+     */
+    setDnsPinRules(rules: string | null): void;
+    /**
+     * Returns the engine page for one session, creating the isolated
+     * context on first use.
+     *
+     * Args:
+     *   sessionId: the supervisor-opened session the context belongs to.
+     *
+     * Returns:
+     *   Promise<Page>: the session's engine-owned page.
+     *
+     * Throws:
+     *   EngineBrowserError: when Chromium cannot launch (fail closed —
+     *     the capability is honestly unavailable at runtime).
+     */
+    pageFor(sessionId: string): Promise<Page>;
+    /**
+     * Closes and forgets one session's engine context (session seal).
+     * Late engine calls for the session then recreate nothing — callers
+     * must refuse sealed sessions before driving (they do: every browser
+     * endpoint requires an OPEN session first).
+     *
+     * Args:
+     *   sessionId: the sealed session.
+     */
+    closeSession(sessionId: string): Promise<void>;
+    /** Closes every engine context and the browser (witness stop). */
+    closeAll(): Promise<void>;
+    /** Lazy Chromium launch (single flight; fail closed with the cause). */
+    private ensureBrowser;
+}
+/**
+ * Drives one constrained surface operation on the engine page and
+ * observes every step itself.
+ *
+ * Args:
+ *   page: the session's engine-owned page.
+ *   appBase: loopback app base the engine navigates (validated upstream).
+ *   surface: the validated consumer descriptor (locators only).
+ *   operation: the constrained operation to perform.
+ *   input: entered fields (create/update) and/or the target entity id.
+ *
+ * Returns:
+ *   Promise<EngineActionObservation>: the engine's own observation —
+ *   observed entity id, entered + rendered fields, captured exchanges.
+ *
+ * Throws:
+ *   EngineBrowserError: fail-closed on every untrusted outcome —
+ *   missing rows, ambiguous creation, wrong rendered status, no
+ *   application request, or an application error status.
+ */
+export declare function driveEngineAction(page: Page, appBase: string, surface: SurfaceDescriptor, operation: EngineOperation, input: {
+    fields?: Record<string, string>;
+    entityId?: string;
+}): Promise<EngineActionObservation>;
+/**
+ * Re-reads the rendered result for one entity on the engine page
+ * (the `visible.confirm` counterpart): row read for mutations, form
+ * read for reads.
+ *
+ * Args:
+ *   page: the session's engine-owned page.
+ *   appBase: loopback app base.
+ *   surface: the validated consumer descriptor.
+ *   operation: the original action (decides row vs form readback).
+ *   entityId: the engine-observed entity id.
+ *
+ * Returns:
+ *   Promise<Record<string, string>>: the rendered fields.
+ *
+ * Throws:
+ *   EngineBrowserError: when the UI no longer exposes the entity.
+ */
+export declare function readEngineVisible(page: Page, appBase: string, surface: SurfaceDescriptor, operation: EngineOperation, entityId: string): Promise<Record<string, string>>;
+//# sourceMappingURL=browser.d.ts.map

package/dist/witness/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/witness/browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAMH,OAAO,KAAK,EAAE,OAAO,EAA2B,IAAI,EAAY,MAAM,YAAY,CAAC;AACnF,OAAO,EAGL,KAAK,iBAAiB,EAGtB,KAAK,WAAW,EACjB,MAAM,eAAe,CAAC;AAEvB,qEAAqE;AACrE,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtE,oEAAoE;AACpE,MAAM,WAAW,sBAAsB;IACrC,yCAAyC;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sDAAsD;AACtD,MAAM,WAAW,uBAAuB;IACtC,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,iEAAiE;IACjE,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,8DAA8D;IAC9D,SAAS,EAAE,sBAAsB,EAAE,CAAC;IACpC,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,yEAAyE;AACzE,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,yEAAyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7D;AAKD;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpE,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACpF,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG;QACzB,KAAK,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACrD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;QACnE,KAAK,CAAC,OAAO,CAAC,EAAE;YAAE,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACtD,CAAC;IACF,QAAQ,EAAE;QAAE,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;KAAE,CAAC;CACjD;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,QAAQ,EACd,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,WAAW,EAAE,EAC7B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAoB;IAkBnB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAjBrC,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,SAAS,CAAiC;IAClD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8D;IACvF;;;;;OAKG;IACH,OAAO,CAAC,WAAW,CAAuB;IAE1C;;;;;OAKG;gBAC0B,QAAQ,EAAE,qBAAqB;IAQ5D;;;;;;;;;;OAUG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IAS1C;;;;;;;;;;;;;OAaG;IACG,OAAO,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C;;;;;;;;OAQG;IACG,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOpD,kEAAkE;IAC5D,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAU/B,wEAAwE;YAC1D,aAAa;CAuB5B;AAmPD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,eAAe,EAC1B,KAAK,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,GAC5D,OAAO,CAAC,uBAAuB,CAAC,CAWlC;AAwLD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,iBAAiB,EAC1B,SAAS,EAAE,eAAe,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAmBjC"}