@gate-forge/core 0.1.0

package/dist/verdict/cause.d.ts

@@ -0,0 +1,99 @@
+import { type CauseCode } from '../schemas/verdict.js';
+/** Cause plus its plan §5.4 next action, attached to a report entry. */
+export interface VerdictCause {
+    /** Stable cause code, or null when Phase 0 has no honest mapping. */
+    cause: CauseCode | null;
+    /** Human next action for the cause, or null when unmapped. */
+    nextAction: string | null;
+}
+/**
+ * Maps one blocking verdict to its cause and next action (plan §5.4).
+ * Deterministic and pure: identical inputs produce identical output.
+ *
+ * Mapping (Phase 0, extended in Phase 1):
+ * - clean verdicts (`satisfied`, `waived`) → null cause;
+ * - no capability record for the contract's namespace →
+ *   VERIFIER_UNSUPPORTED (nothing is registered to prove it with);
+ * - a registered namespace that does not implement the contract (e.g.
+ *   `http:frontend-request-observed`, unknown `crud:*`/`http:*` names)
+ *   or an unavailable namespace (the five domain namespaces) →
+ *   VERIFIER_UNSUPPORTED;
+ * - a supported contract whose reason reports the §3.6 exact-value echo
+ *   violation → EVIDENCE_VALUE_MISMATCH;
+ * - a crud claim whose session exchange cannot be attributed because the
+ *   host supplied no route inventory → VERIFIER_UNSUPPORTED (the setup
+ *   lacks the derived inventory the proof channel needs);
+ * - a supported contract whose reason reports absent required
+ *   observations (including the crud session-channel rules: direct
+ *   mutation outside the session channel, no visible result, no
+ *   session-bound anchor) → EVIDENCE_NOT_COLLECTED;
+ * - `no claim declares '<id>'` → TEST_MAPPING_MISSING (no existing test
+ *   is connected to the obligation; the Phase 2-3 mapping subsystem
+ *   refines this into catalog-backed causes);
+ * - anything else → null (precise single-cause reason; no guessed code).
+ *
+ * Args:
+ *   params: obligationId, contract, verdict value, and engine reason of
+ *     the report entry being rendered.
+ *
+ * Returns:
+ *   VerdictCause: `{cause, nextAction}` — cause/nextAction are null when
+ *   the verdict is clean or no honest mapping exists yet.
+ */
+export declare function causeForVerdict(params: {
+    obligationId: string;
+    contract: string;
+    verdict: string;
+    reason: string | null;
+}): VerdictCause;
+/**
+ * One precise capability gap (plan Phase 0 item 4, ADR 0005 D1/D5): a
+ * required contract whose proof channel is unavailable. `detail` names
+ * the contract, the missing observer, and the fail-closed consequence;
+ * `nextAction` is always the plan §5.4 `VERIFIER_UNSUPPORTED` action.
+ */
+export interface CapabilityGap {
+    /** The unsupported contract name. */
+    contract: string;
+    /** The independent observer channel whose absence blocks this contract. */
+    observer: string;
+    /** Single-cause precise explanation (fail-closed wording). */
+    detail: string;
+    /** Always `VERIFIER_UNSUPPORTED` (plan §5.4). */
+    cause: Extract<CauseCode, 'VERIFIER_UNSUPPORTED'>;
+    /** Plan §5.4 next action for an unsupported proof channel. */
+    nextAction: string;
+}
+/**
+ * Computes the capability gap for one contract, or null when the
+ * contract's namespace is registered, available, and implements the
+ * contract. Pure; reads only the capability registry (single source of
+ * truth — no duplicated contract lists at call sites).
+ *
+ * Args:
+ *   contract: the required contract name, e.g. `http:request-observed`.
+ *
+ * Returns:
+ *   CapabilityGap | null: the gap, or null when the contract is provable.
+ */
+export declare function capabilityGap(contract: string): CapabilityGap | null;
+/**
+ * Preflight for strict setups (plan Phase 0 item 4): returns one gap per
+ * obligation whose contract cannot be proven. A strict setup demanding an
+ * unavailable contract must fail closed with these precise errors — it
+ * cannot advertise an operational blocking E2E gate.
+ *
+ * Args:
+ *   obligations: the obligations to preflight (`id` + `contract`).
+ *
+ * Returns:
+ *   Array<CapabilityGap & {obligationId: string}>: one entry per
+ *   unsupported obligation, sorted by obligation id (deterministic).
+ */
+export declare function strictCapabilityGaps(obligations: readonly {
+    id: string;
+    contract: string;
+}[]): Array<CapabilityGap & {
+    obligationId: string;
+}>;
+//# sourceMappingURL=cause.d.ts.map

package/dist/verdict/cause.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cause.d.ts","sourceRoot":"","sources":["../../src/verdict/cause.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAsB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAE3E,wEAAwE;AACxE,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IACxB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AA2CD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB,GAAG,YAAY,CAqBf;AAOD;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC;IACjB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,iDAAiD;IACjD,KAAK,EAAE,OAAO,CAAC,SAAS,EAAE,sBAAsB,CAAC,CAAC;IAClD,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,IAAI,CAiDpE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,SAAS;IACzD,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CAClB,EAAE,GAAG,KAAK,CAAC,aAAa,GAAG;IAAE,YAAY,EAAE,MAAM,CAAA;CAAE,CAAC,CAcpD"}

package/dist/verdict/cause.js

@@ -0,0 +1,206 @@
+/**
+ * Cause mapping for the shared report model (plan 2026-09-13 §5.4, ADR
+ * 0005): derives a stable cause code plus its next action from a
+ * blocking verdict's contract and reason. Mapped today: unsupported
+ * proof channels (VERIFIER_UNSUPPORTED — including a crud claim whose
+ * session exchange cannot be attributed for lack of a route inventory),
+ * a connected test whose required observations are absent
+ * (EVIDENCE_NOT_COLLECTED — including the crud session-channel rules:
+ * direct mutation outside the supervised channel, no visible result, no
+ * session-bound anchor), an obligation no test is connected to
+ * (TEST_MAPPING_MISSING), and the §3.6 exact-value echo violation
+ * (EVIDENCE_VALUE_MISMATCH). Remaining causes are populated by the
+ * phases that build their subsystems (catalog/mapping: Phase 2-3;
+ * execution results: Phase 4); an unmapped blocking verdict carries a
+ * null cause rather than a guess.
+ *
+ * The mapping matches the verifier reasons verbatim — those strings are
+ * engine-owned (single grading sites, kept in lockstep by tests), never
+ * adversary-controlled input.
+ */
+import { capabilityFor } from './registry.js';
+import { CAUSE_NEXT_ACTIONS } from '../schemas/verdict.js';
+/** Verdicts that never carry a cause: clean runs have nothing to explain. */
+const CLEAN_VERDICTS = new Set(['satisfied', 'waived']);
+/**
+ * Evidence-absence reasons produced by the built-in verifiers for a
+ * CONNECTED test (a claim exists) whose required observations are
+ * missing — the plan §5.4 `EVIDENCE_NOT_COLLECTED` shape ("a mapped test
+ * lacks required observations"). Matched verbatim; each is emitted from
+ * exactly one grading site. The last two are the crud session-channel
+ * rules (plan Phase 1 item 8): a mutation performed outside the
+ * supervised session channel (direct API/Node-side) and a journey that
+ * never read the rendered result back.
+ */
+const EVIDENCE_NOT_COLLECTED_PATTERNS = [
+    'produced no evidence records',
+    "no 'ui.action' anchor from the declaring test",
+    'the witness observed no matching HTTP exchange',
+    "no witnessed session-bound 'http.request' exchange",
+    'no witnessed visible-result record',
+    "no session-bound 'ui.action' anchor from the declaring test",
+    "carries no witness session binding",
+];
+/**
+ * The plan §5.4 exact-value echo violation (plan §3.6, implemented in
+ * Phase 1): the persisted state does not echo the journey's entered
+ * input on the same entity. Matched verbatim from the single grading
+ * site in the persistence verifier (reused verbatim by the crud
+ * session-channel verifier).
+ */
+const EVIDENCE_VALUE_MISMATCH_PATTERN = 'exact-value echo violation (EVIDENCE_VALUE_MISMATCH)';
+/**
+ * A crud session exchange that cannot be attributed because the host
+ * supplied no route inventory (plan §9, D2): the proof channel the
+ * contract needs is not wired into this setup. Scoped to the crud
+ * namespace's wording so the http transport grader's own inventory
+ * reason keeps its existing (unmapped) cause.
+ */
+const CRUD_INVENTORY_UNSUPPORTED_PATTERN = "no route inventory context for 'crud:";
+/**
+ * Maps one blocking verdict to its cause and next action (plan §5.4).
+ * Deterministic and pure: identical inputs produce identical output.
+ *
+ * Mapping (Phase 0, extended in Phase 1):
+ * - clean verdicts (`satisfied`, `waived`) → null cause;
+ * - no capability record for the contract's namespace →
+ *   VERIFIER_UNSUPPORTED (nothing is registered to prove it with);
+ * - a registered namespace that does not implement the contract (e.g.
+ *   `http:frontend-request-observed`, unknown `crud:*`/`http:*` names)
+ *   or an unavailable namespace (the five domain namespaces) →
+ *   VERIFIER_UNSUPPORTED;
+ * - a supported contract whose reason reports the §3.6 exact-value echo
+ *   violation → EVIDENCE_VALUE_MISMATCH;
+ * - a crud claim whose session exchange cannot be attributed because the
+ *   host supplied no route inventory → VERIFIER_UNSUPPORTED (the setup
+ *   lacks the derived inventory the proof channel needs);
+ * - a supported contract whose reason reports absent required
+ *   observations (including the crud session-channel rules: direct
+ *   mutation outside the session channel, no visible result, no
+ *   session-bound anchor) → EVIDENCE_NOT_COLLECTED;
+ * - `no claim declares '<id>'` → TEST_MAPPING_MISSING (no existing test
+ *   is connected to the obligation; the Phase 2-3 mapping subsystem
+ *   refines this into catalog-backed causes);
+ * - anything else → null (precise single-cause reason; no guessed code).
+ *
+ * Args:
+ *   params: obligationId, contract, verdict value, and engine reason of
+ *     the report entry being rendered.
+ *
+ * Returns:
+ *   VerdictCause: `{cause, nextAction}` — cause/nextAction are null when
+ *   the verdict is clean or no honest mapping exists yet.
+ */
+export function causeForVerdict(params) {
+    if (CLEAN_VERDICTS.has(params.verdict))
+        return { cause: null, nextAction: null };
+    const capability = capabilityFor(params.contract);
+    const implemented = capability?.contracts.includes(params.contract) ?? false;
+    if (capability === null || capability.availability.status === 'unavailable' || !implemented) {
+        return nextActionFor('VERIFIER_UNSUPPORTED');
+    }
+    const reason = params.reason ?? '';
+    if (reason.includes(EVIDENCE_VALUE_MISMATCH_PATTERN)) {
+        return nextActionFor('EVIDENCE_VALUE_MISMATCH');
+    }
+    if (reason.includes(CRUD_INVENTORY_UNSUPPORTED_PATTERN)) {
+        return nextActionFor('VERIFIER_UNSUPPORTED');
+    }
+    if (EVIDENCE_NOT_COLLECTED_PATTERNS.some((pattern) => reason.includes(pattern))) {
+        return nextActionFor('EVIDENCE_NOT_COLLECTED');
+    }
+    if (reason === `no claim declares '${params.obligationId}'`) {
+        return nextActionFor('TEST_MAPPING_MISSING');
+    }
+    return { cause: null, nextAction: null };
+}
+/** Pairs a cause with its frozen plan §5.4 next action. */
+function nextActionFor(cause) {
+    return { cause, nextAction: CAUSE_NEXT_ACTIONS[cause] };
+}
+/**
+ * Computes the capability gap for one contract, or null when the
+ * contract's namespace is registered, available, and implements the
+ * contract. Pure; reads only the capability registry (single source of
+ * truth — no duplicated contract lists at call sites).
+ *
+ * Args:
+ *   contract: the required contract name, e.g. `http:request-observed`.
+ *
+ * Returns:
+ *   CapabilityGap | null: the gap, or null when the contract is provable.
+ */
+export function capabilityGap(contract) {
+    const capability = capabilityFor(contract);
+    if (capability === null) {
+        return {
+            contract,
+            observer: 'a registered semantic verifier and its independent observation channel',
+            detail: `contract '${contract}' has no registered verifier or capability record: no honest ` +
+                'proof channel exists, so obligations requiring it can never be satisfied',
+            cause: 'VERIFIER_UNSUPPORTED',
+            nextAction: CAUSE_NEXT_ACTIONS['VERIFIER_UNSUPPORTED'],
+        };
+    }
+    if (capability.availability.status === 'unavailable') {
+        return {
+            contract,
+            observer: capability.observer,
+            detail: `contract '${contract}' is unprovable: its namespace '${capability.namespace}' is ` +
+                `fail-closed (${capability.availability.reason}). Required observer: ${capability.observer}.`,
+            cause: 'VERIFIER_UNSUPPORTED',
+            nextAction: CAUSE_NEXT_ACTIONS['VERIFIER_UNSUPPORTED'],
+        };
+    }
+    const unavailable = capability.unavailableContracts.find((entry) => entry.contract === contract);
+    if (unavailable !== undefined) {
+        return {
+            contract,
+            observer: capability.observer,
+            detail: `contract '${contract}' is registered but unavailable: ${unavailable.reason}. ` +
+                `Required observer: ${capability.observer}.`,
+            cause: 'VERIFIER_UNSUPPORTED',
+            nextAction: CAUSE_NEXT_ACTIONS['VERIFIER_UNSUPPORTED'],
+        };
+    }
+    if (!capability.contracts.includes(contract)) {
+        return {
+            contract,
+            observer: capability.observer,
+            detail: `contract '${contract}' is not implemented by its namespace '${capability.namespace}': ` +
+                `the namespace implements [${capability.contracts.join(', ')}]. No honest proof ` +
+                'channel exists for this name',
+            cause: 'VERIFIER_UNSUPPORTED',
+            nextAction: CAUSE_NEXT_ACTIONS['VERIFIER_UNSUPPORTED'],
+        };
+    }
+    return null;
+}
+/**
+ * Preflight for strict setups (plan Phase 0 item 4): returns one gap per
+ * obligation whose contract cannot be proven. A strict setup demanding an
+ * unavailable contract must fail closed with these precise errors — it
+ * cannot advertise an operational blocking E2E gate.
+ *
+ * Args:
+ *   obligations: the obligations to preflight (`id` + `contract`).
+ *
+ * Returns:
+ *   Array<CapabilityGap & {obligationId: string}>: one entry per
+ *   unsupported obligation, sorted by obligation id (deterministic).
+ */
+export function strictCapabilityGaps(obligations) {
+    const gaps = [];
+    for (const obligation of obligations) {
+        const gap = capabilityGap(obligation.contract);
+        if (gap === null)
+            continue;
+        gaps.push({
+            ...gap,
+            detail: `obligation '${obligation.id}': ${gap.detail}`,
+            obligationId: obligation.id,
+        });
+    }
+    return gaps.sort((a, b) => a.obligationId < b.obligationId ? -1 : a.obligationId > b.obligationId ? 1 : 0);
+}
+//# sourceMappingURL=cause.js.map

package/dist/verdict/cause.js.map

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

package/dist/verdict/evaluate.d.ts

@@ -0,0 +1,135 @@
+import { type HttpRouteCandidate } from './registry.js';
+import { type Obligation } from '../schemas/obligation.js';
+import type { TrustTier } from '../schemas/common.js';
+import type { CauseCode, Verdict } from '../schemas/verdict.js';
+import { type Waiver } from '../schemas/waiver.js';
+/** Verdicts that block a run (exit code 1). Clean: satisfied, waived. */
+export declare const BLOCKING_VERDICTS: readonly Verdict[];
+/**
+ * Fail-closed verdict-engine error: raised only for engine-internal
+ * contract violations (malformed obligation, invalid `now`) — never for
+ * adversary-controlled evidence, which must degrade to a verdict.
+ */
+export declare class GateforgeVerdictError extends Error {
+    constructor(message: string);
+}
+/** A waiver plus the engine-only stale-owner flag (GF-17). */
+export type WaiverRef = Waiver & {
+    readonly ownerStale?: boolean;
+};
+/** The pinned pin-#9 result shape for one obligation. */
+export interface VerdictOutcome {
+    /** One of the seven verdicts (ADR 0001 D1). */
+    verdict: Verdict;
+    /**
+     * Single-cause human explanation. `null` only for `satisfied`;
+     * every other verdict explains itself (invariant 8).
+     */
+    reason: string | null;
+    /**
+     * Record ids that drove the verdict — the satisfying witnessed set for
+     * `satisfied`; all considered records for `missing`/`invalid`; empty for
+     * verdicts decided before evidence is consulted. Sorted, deduplicated.
+     */
+    recordIds: string[];
+}
+/**
+ * A per-obligation verdict enriched for reporting: the batch wrapper adds
+ * the obligation identity, the highest trust tier among considered
+ * records, optional detector provenance (invariant 8 trace), and the
+ * stable cause code + next action for the shared report model (plan
+ * §5.4). Cause/nextAction are null when the verdict is clean or no
+ * honest mapping exists yet (later phases populate).
+ */
+export interface ObligationVerdict extends VerdictOutcome {
+    /** The obligation this verdict is about. */
+    obligation: Obligation;
+    /** Highest trust tier among the obligation's records; null when none. */
+    trustTier: TrustTier | null;
+    /** Detector provenance for the trace; attached by the caller when known. */
+    detector?: {
+        id: string;
+        version: string;
+    } | null;
+    /** Stable plan §5.4 cause code; null when unmapped or clean. */
+    readonly cause?: CauseCode | null;
+    /** Human next action for the cause; null when unmapped or clean. */
+    readonly nextAction?: string | null;
+}
+/** Pin-#9 evaluation context. Malformed entries degrade, never crash. */
+export interface VerdictContext {
+    /** Reporter claims (Claim-shaped); entries failing the schema are ignored. */
+    claims: readonly unknown[];
+    /**
+     * Witness records — deliberately lenient input: records that fail the
+     * EvidenceRecord shape or lack service-issued provenance are treated as
+     * claimed-tier (GF-23), never rejected.
+     */
+    records: readonly unknown[];
+    /** Loaded waivers; `ownerStale: true` entries yield `stale` (GF-17). */
+    waivers: readonly WaiverRef[];
+    /** Classification of `obligation.resourceId`; null ⇒ `unclassified`. */
+    classification: unknown;
+    /** The obligation's graph resource (kind + attributes), when the host can supply it. Verifiers use it to bind evidence to identity. */
+    resource?: {
+        kind: string;
+        attributes: Record<string, unknown>;
+    } | null;
+    /**
+     * The COMPLETE runtime route inventory for HTTP attribution (plan
+     * §9, D2). Host-derived from the graph; absent blocks HTTP
+     * satisfaction (no any-endpoint fallback).
+     */
+    httpRoutes?: readonly HttpRouteCandidate[] | null;
+    /** Injected clock instant (invariant 7) — the only time source. */
+    now: Date | string;
+}
+/**
+ * Normalizes the injected clock to a Date. Accepts Date or ISO-8601
+ * string; anything else is an engine-internal contract violation.
+ *
+ * Args:
+ *   now: the injected clock instant.
+ *
+ * Returns:
+ *   Date: the parsed instant.
+ *
+ * Throws:
+ *   GateforgeVerdictError: when `now` is not a valid ISO-8601 instant.
+ */
+export declare function parseInstant(now: Date | string): Date;
+/**
+ * Evaluates ONE obligation against the run's claims, records, waivers,
+ * classification, and injected clock (pin #9). Pure and deterministic:
+ * identical inputs produce identical outcomes.
+ *
+ * Args:
+ *   obligation: the obligation under evaluation (validated schema shape).
+ *   context: claims, records, waivers, classification, and `now`.
+ *
+ * Returns:
+ *   VerdictOutcome: {verdict, reason, recordIds} — reason is null only
+ *   for `satisfied`; recordIds is always a sorted array.
+ *
+ * Throws:
+ *   GateforgeVerdictError: when the obligation or `now` violates the
+ *   engine-internal contract (evidence problems NEVER throw — they
+ *   produce `invalid`/`missing` verdicts).
+ */
+export declare function evaluateObligation(obligation: Obligation, context: VerdictContext): VerdictOutcome;
+/**
+ * Evaluates a batch of obligations against one context and returns
+ * report-ready entries sorted by obligation id, each enriched with the
+ * highest trust tier among its records (SARIF properties), optional
+ * detector provenance passthrough, and the plan §5.4 cause code +
+ * next action for the shared report model.
+ *
+ * Args:
+ *   obligations: obligations to evaluate.
+ *   context: the shared pin-#9 evaluation context.
+ *
+ * Returns:
+ *   ObligationVerdict[]: sorted by obligation id; deterministic.
+ */
+export declare function evaluateObligations(obligations: readonly Obligation[], context: VerdictContext): ObligationVerdict[];
+//# sourceMappingURL=evaluate.d.ts.map

package/dist/verdict/evaluate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluate.d.ts","sourceRoot":"","sources":["../../src/verdict/evaluate.ts"],"names":[],"mappings":"AAuDA,OAAO,EAML,KAAK,kBAAkB,EACxB,MAAM,eAAe,CAAC;AASvB,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC7E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,EAAgB,KAAK,MAAM,EAAE,MAAM,sBAAsB,CAAC;AA+BjE,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,EAAE,SAAS,OAAO,EAM/C,CAAC;AAEF;;;;GAIG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,OAAO,EAAE,MAAM;CAI5B;AAED,8DAA8D;AAC9D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAEnE,yDAAyD;AACzD,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD,4CAA4C;IAC5C,UAAU,EAAE,UAAU,CAAC;IACvB,yEAAyE;IACzE,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAC5B,4EAA4E;IAC5E,QAAQ,CAAC,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAClD,gEAAgE;IAChE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG,IAAI,CAAC;IAClC,oEAAoE;IACpE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,8EAA8E;IAC9E,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;IAC3B;;;;OAIG;IACH,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;IAC5B,wEAAwE;IACxE,OAAO,EAAE,SAAS,SAAS,EAAE,CAAC;IAC9B,wEAAwE;IACxE,cAAc,EAAE,OAAO,CAAC;IACxB,uIAAuI;IACvI,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IACxE;;;;OAIG;IACH,UAAU,CAAC,EAAE,SAAS,kBAAkB,EAAE,GAAG,IAAI,CAAC;IAClD,mEAAmE;IACnE,GAAG,EAAE,IAAI,GAAG,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAcrD;AA62CD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,UAAU,EACtB,OAAO,EAAE,cAAc,GACtB,cAAc,CAiLhB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,WAAW,EAAE,SAAS,UAAU,EAAE,EAClC,OAAO,EAAE,cAAc,GACtB,iBAAiB,EAAE,CAuBrB"}