@tyroneross/navgator 0.2.2 → 0.9.0

package/dist/audit/index.d.ts

@@ -0,0 +1,69 @@
+/**
+ * NavGator audit orchestrator — Run 2 / D4
+ *
+ * Picks a sampling plan (AQL / SPRT / Cochran), stratifies the population,
+ * runs the six verifiers in parallel, aggregates into a single AuditReport.
+ *
+ * Hooked from scanner.ts after Phase 4 storage write, before Phase 5 timeline.
+ * Must NOT cause the scan to fail — only updates EWMA and sets `drift_breach`
+ * on the timeline entry, which the next scan reads to auto-promote.
+ */
+import type { ArchitectureComponent, ArchitectureConnection, NavGatorConfig } from '../types.js';
+import { type EwmaState } from './spc.js';
+import { type DefectClass, type SampleEvidence } from './verifiers.js';
+export type AuditPlan = 'AQL' | 'SPRT' | 'Cochran';
+export interface AuditReport {
+    plan: AuditPlan;
+    /** Total sample size requested by the plan (may differ from actual sampled). */
+    n: number;
+    /** Acceptance number (only meaningful for AQL). */
+    c: number;
+    /** Total facts actually inspected across all verifiers. */
+    sampled: number;
+    /** Total defects found across all verifiers. */
+    defects: number;
+    /** defects / sampled (or 0 if sampled=0). */
+    defect_rate: number;
+    by_class: Partial<Record<DefectClass, {
+        sampled: number;
+        defects: number;
+    }>>;
+    by_stratum: Record<string, {
+        sampled: number;
+        defects: number;
+        defect_rate: number;
+    }>;
+    /** True when MISSED_EDGE verifier was skipped (CLI mode). */
+    llm_skipped?: boolean;
+    /** Plan verdict: accept / reject / continue (SPRT only) / accept-on-c. */
+    verdict: 'accept' | 'reject' | 'continue';
+    /** EWMA breach detected on this run for at least one stratum. */
+    drift_breach?: boolean;
+    timestamp: number;
+    /** Compact evidence snippets for failures (capped to 20 to keep timeline.json small). */
+    defect_evidence?: SampleEvidence[];
+}
+export interface AuditOptions {
+    /** Override plan selection. */
+    plan?: AuditPlan;
+    /** Skip the audit entirely (returns null from runAudit). */
+    skip?: boolean;
+    /** Whether NavGator is running inside an MCP session (enables LLM-judge). */
+    isMcpMode?: boolean;
+    /** History — used to switch from AQL to SPRT and to seed EWMA. */
+    priorEwma?: Record<string, EwmaState>;
+    priorAuditCount?: number;
+    /** Set when previous run breached EWMA → forces Cochran. */
+    forceCochran?: boolean;
+    /** RNG injection for deterministic tests. */
+    rand?: () => number;
+}
+export declare function runAudit(scanResult: {
+    components: ReadonlyArray<ArchitectureComponent>;
+    connections: ReadonlyArray<ArchitectureConnection>;
+}, config: NavGatorConfig, projectRoot: string, opts?: AuditOptions): Promise<AuditReport | null>;
+export declare function updateEwmaForAudit(prior: Record<string, EwmaState> | undefined, report: AuditReport): {
+    ewma: Record<string, EwmaState>;
+    anyBreach: boolean;
+};
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,sBAAsB,EAGtB,cAAc,EACf,MAAM,aAAa,CAAC;AASrB,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,KAAK,WAAW,EAChB,KAAK,cAAc,EASpB,MAAM,gBAAgB,CAAC;AAMxB,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,CAAC;AAEnD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,gFAAgF;IAChF,CAAC,EAAE,MAAM,CAAC;IACV,mDAAmD;IACnD,CAAC,EAAE,MAAM,CAAC;IACV,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,gDAAgD;IAChD,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC,CAAC;IAC7E,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtF,6DAA6D;IAC7D,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,0EAA0E;IAC1E,OAAO,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;IAC1C,iEAAiE;IACjE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,yFAAyF;IACzF,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;CACpC;AAED,MAAM,WAAW,YAAY;IAC3B,+BAA+B;IAC/B,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB,4DAA4D;IAC5D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6EAA6E;IAC7E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IACtC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,MAAM,CAAC;CACrB;AAkFD,wBAAsB,QAAQ,CAC5B,UAAU,EAAE;IACV,UAAU,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;IACjD,WAAW,EAAE,aAAa,CAAC,sBAAsB,CAAC,CAAC;CACpD,EACD,MAAM,EAAE,cAAc,EACtB,WAAW,EAAE,MAAM,EACnB,IAAI,GAAE,YAAiB,GACtB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAiK7B;AAMD,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,SAAS,EAC5C,MAAM,EAAE,WAAW,GAClB;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAYzD"}

package/dist/audit/index.js

@@ -0,0 +1,255 @@
+/**
+ * NavGator audit orchestrator — Run 2 / D4
+ *
+ * Picks a sampling plan (AQL / SPRT / Cochran), stratifies the population,
+ * runs the six verifiers in parallel, aggregates into a single AuditReport.
+ *
+ * Hooked from scanner.ts after Phase 4 storage write, before Phase 5 timeline.
+ * Must NOT cause the scan to fail — only updates EWMA and sets `drift_breach`
+ * on the timeline entry, which the next scan reads to auto-promote.
+ */
+import { loadHashes } from '../storage.js';
+import { chooseAQLPlan, cochranSize, selectAuditSample, sprtNext, Z, } from './sampler.js';
+import { newEwmaState, updateEwma, } from './spc.js';
+import { verifyDedupCollision, verifyHallucinatedComponent, verifyHallucinatedEdge, verifyMissedEdge, verifyStaleReference, verifyWrongEndpoint, } from './verifiers.js';
+// ============================================================================
+// STRATA KEYS
+// ============================================================================
+const PACKAGE_TYPES = new Set([
+    'npm',
+    'pip',
+    'spm',
+    'cargo',
+    'go',
+    'gem',
+    'composer',
+]);
+const INFRA_TYPES = new Set([
+    'infra',
+    'database',
+    'queue',
+    'cron',
+    'config',
+]);
+function componentStratum(c) {
+    if (PACKAGE_TYPES.has(c.type))
+        return 'package';
+    if (INFRA_TYPES.has(c.type))
+        return 'infra';
+    if (c.type === 'llm')
+        return 'connection-llm';
+    if (c.type === 'service')
+        return 'connection-services';
+    return '__other';
+}
+function connectionStratum(c) {
+    const t = c.connection_type;
+    if (t === 'imports' || t === 'uses-package')
+        return 'connection-imports';
+    if (t === 'service-call')
+        return 'connection-services';
+    if (t === 'schema-relation' || t === 'api-calls-db' || t === 'field-reference')
+        return 'connection-prisma';
+    if (t === 'prompt-location' || t === 'prompt-usage')
+        return 'connection-llm';
+    return '__other';
+}
+// ============================================================================
+// PLAN SELECTION
+// ============================================================================
+function pickPlan(opts, lotSize) {
+    // Caller forced a plan
+    if (opts.plan) {
+        if (opts.plan === 'AQL') {
+            const p = chooseAQLPlan(lotSize);
+            return { plan: 'AQL', n: p.n, c: p.c };
+        }
+        if (opts.plan === 'Cochran') {
+            const n = cochranSize(0.05, 0.05, Z.Z_95, lotSize);
+            return { plan: 'Cochran', n, c: 0 };
+        }
+        // SPRT — initial batch sized like AQL; SPRT verdict computed on observations
+        const p = chooseAQLPlan(lotSize);
+        return { plan: 'SPRT', n: p.n, c: p.c };
+    }
+    // Auto: forceCochran (prior breach) > SPRT (≥3 audits in history) > AQL.
+    if (opts.forceCochran) {
+        const n = cochranSize(0.05, 0.05, Z.Z_95, lotSize);
+        return { plan: 'Cochran', n, c: 0 };
+    }
+    if ((opts.priorAuditCount ?? 0) >= 3) {
+        const p = chooseAQLPlan(lotSize);
+        return { plan: 'SPRT', n: p.n, c: p.c };
+    }
+    const p = chooseAQLPlan(lotSize);
+    return { plan: 'AQL', n: p.n, c: p.c };
+}
+// ============================================================================
+// ORCHESTRATOR
+// ============================================================================
+export async function runAudit(scanResult, config, projectRoot, opts = {}) {
+    if (opts.skip)
+        return null;
+    const { components, connections } = scanResult;
+    // Lot size = total facts (components + connections). Used to pick the plan.
+    const lotSize = components.length + connections.length;
+    if (lotSize === 0) {
+        // Empty scan — emit a minimal report so downstream tooling sees the slot.
+        return {
+            plan: 'AQL',
+            n: 0,
+            c: 0,
+            sampled: 0,
+            defects: 0,
+            defect_rate: 0,
+            by_class: {},
+            by_stratum: {},
+            llm_skipped: !opts.isMcpMode,
+            verdict: 'accept',
+            timestamp: Date.now(),
+        };
+    }
+    const { plan, n: planN, c: planC } = pickPlan(opts, lotSize);
+    // Stratified sample across components + connections (treated as one population).
+    const componentSamples = selectAuditSample(components, Math.ceil(planN * 0.5), componentStratum, undefined, opts.rand);
+    const connectionSamples = selectAuditSample(connections, Math.floor(planN * 0.5), connectionStratum, undefined, opts.rand);
+    // Build verifier context.
+    const componentById = new Map();
+    for (const c of components)
+        componentById.set(c.component_id, c);
+    const hashes = await loadHashes(config, projectRoot);
+    const ctx = {
+        projectRoot,
+        hashes,
+        componentById,
+        isMcpMode: !!opts.isMcpMode,
+    };
+    // Sample of files for stale-ref + missed-edge verifiers.
+    const allFiles = hashes ? Object.keys(hashes.files) : [];
+    const fileSampleCount = Math.min(Math.max(5, Math.floor(planN * 0.2)), allFiles.length);
+    const fileSamples = allFiles.length > 0
+        ? selectAuditSample(allFiles, fileSampleCount, () => '__files', undefined, opts.rand).samples
+        : [];
+    // Run all verifiers in parallel.
+    const [v1, v2, v3, v4, v6] = await Promise.all([
+        verifyHallucinatedComponent(componentSamples.samples, ctx),
+        Promise.resolve(verifyHallucinatedEdge(connectionSamples.samples, ctx)),
+        verifyWrongEndpoint(connectionSamples.samples, ctx),
+        verifyStaleReference(fileSamples, ctx),
+        Promise.resolve(verifyMissedEdge(fileSamples, connections, ctx)),
+    ]);
+    const v5 = verifyDedupCollision(components); // graph-wide invariant, always
+    const verifiers = [v1, v2, v3, v4, v5, v6];
+    // Aggregate by class.
+    const by_class = {};
+    for (const v of verifiers) {
+        by_class[v.class] = { sampled: v.sampledCount, defects: v.defectCount };
+    }
+    // Aggregate by stratum (components + connections).
+    const stratumAgg = {};
+    const compEvidenceById = new Map();
+    for (const e of v1.samples)
+        compEvidenceById.set(e.id, e);
+    for (const c of componentSamples.samples) {
+        const s = componentStratum(c);
+        if (!stratumAgg[s])
+            stratumAgg[s] = { sampled: 0, defects: 0 };
+        stratumAgg[s].sampled++;
+        if (compEvidenceById.get(c.component_id)?.ok === false)
+            stratumAgg[s].defects++;
+    }
+    const connEvidenceById = new Map();
+    for (const e of v2.samples)
+        connEvidenceById.set(e.id, e);
+    // Merge v3 evidence on top — a connection failing either is one defect for stratum.
+    const connDefectIds = new Set();
+    for (const e of v2.samples)
+        if (!e.ok)
+            connDefectIds.add(e.id);
+    for (const e of v3.samples)
+        if (!e.ok)
+            connDefectIds.add(e.id);
+    for (const c of connectionSamples.samples) {
+        const s = connectionStratum(c);
+        if (!stratumAgg[s])
+            stratumAgg[s] = { sampled: 0, defects: 0 };
+        stratumAgg[s].sampled++;
+        if (connDefectIds.has(c.connection_id))
+            stratumAgg[s].defects++;
+    }
+    const by_stratum = {};
+    for (const [k, v] of Object.entries(stratumAgg)) {
+        by_stratum[k] = {
+            sampled: v.sampled,
+            defects: v.defects,
+            defect_rate: v.sampled > 0 ? v.defects / v.sampled : 0,
+        };
+    }
+    // Total sampled count (sum of distinct facts inspected — DEDUP_COLLISION
+    // scans the whole population so we exclude its sampledCount from the totals
+    // to avoid double-counting; we DO count its defects).
+    const sampled = v1.sampledCount + v2.sampledCount + v3.sampledCount + v4.sampledCount + v6.sampledCount;
+    const defects = v1.defectCount + v2.defectCount + v3.defectCount + v4.defectCount + v5.defectCount + v6.defectCount;
+    const llm_skipped = !!v6.llm_skipped;
+    // Compute verdict.
+    let verdict;
+    if (plan === 'SPRT') {
+        // Build observation sequence from per-fact ok/defect across deterministic verifiers.
+        const obs = [];
+        for (const e of v1.samples)
+            obs.push(e.ok ? 0 : 1);
+        for (const e of v2.samples)
+            obs.push(e.ok ? 0 : 1);
+        for (const e of v3.samples)
+            obs.push(e.ok ? 0 : 1);
+        for (const e of v4.samples)
+            obs.push(e.ok ? 0 : 1);
+        const step = sprtNext(obs, 0.01, 0.05, 0.05, 0.05);
+        verdict = step.verdict;
+    }
+    else {
+        // AQL / Cochran: compare defects to acceptance number.
+        // Cochran has c=0 (any defect → reject); AQL has plan-specific c.
+        verdict = defects <= planC ? 'accept' : 'reject';
+    }
+    // Collect defect evidence (cap at 20).
+    const defect_evidence = [];
+    for (const v of verifiers) {
+        for (const e of v.samples) {
+            if (!e.ok && defect_evidence.length < 20)
+                defect_evidence.push(e);
+        }
+        if (defect_evidence.length >= 20)
+            break;
+    }
+    return {
+        plan,
+        n: planN,
+        c: planC,
+        sampled,
+        defects,
+        defect_rate: sampled > 0 ? defects / sampled : 0,
+        by_class,
+        by_stratum,
+        llm_skipped,
+        verdict,
+        timestamp: Date.now(),
+        ...(defect_evidence.length > 0 ? { defect_evidence } : {}),
+    };
+}
+// ============================================================================
+// EWMA UPDATE (called after runAudit returns; mutates and returns new state map)
+// ============================================================================
+export function updateEwmaForAudit(prior, report) {
+    const next = { ...(prior ?? {}) };
+    let anyBreach = false;
+    for (const [stratum, stats] of Object.entries(report.by_stratum)) {
+        const prev = next[stratum] ?? newEwmaState();
+        const result = updateEwma(prev, stats.defect_rate);
+        next[stratum] = result.state;
+        if (result.breach)
+            anyBreach = true;
+    }
+    return { ewma: next, anyBreach };
+}
+//# sourceMappingURL=index.js.map

package/dist/audit/index.js.map

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

package/dist/audit/sampler.d.ts

@@ -0,0 +1,98 @@
+/**
+ * NavGator audit sampler — Run 2 / D1
+ *
+ * Pure-math statistical sampling helpers. Zero deps.
+ *
+ * References:
+ *   - NIST/SEMATECH e-Handbook §6.2.2-3 (acceptance sampling, attributes)
+ *   - Wald 1945 — Sequential analysis (SPRT)
+ *   - Cochran 1977 — Sampling techniques (FPC, Neyman allocation)
+ */
+/** Standard normal quantiles for common confidence levels. */
+export declare const Z: {
+    /** 90% two-sided CI / 95% one-sided */
+    readonly Z_90: 1.645;
+    /** 95% two-sided CI */
+    readonly Z_95: 1.96;
+    /** 99% two-sided CI */
+    readonly Z_99: 2.576;
+};
+/**
+ * Binomial CDF P(X ≤ c) where X ~ Binomial(n, p).
+ * Used for OC-curve calc: probability of acceptance at proportion-defective p.
+ */
+export declare function binomialCDF(n: number, p: number, c: number): number;
+interface AQLPlan {
+    n: number;
+    c: number;
+    plan: 'AQL';
+    codeLetter: string;
+    lotRange: string;
+}
+/** Pick an AQL=2.5% sampling plan based on lot size. */
+export declare function chooseAQLPlan(lotSize: number): AQLPlan;
+export type SprtVerdict = 'accept' | 'reject' | 'continue';
+export interface SprtStep {
+    verdict: SprtVerdict;
+    /** ln of the likelihood ratio after the latest observation. */
+    logLR: number;
+    /** Upper bound A = (1-β)/α. */
+    A: number;
+    /** Lower bound B = β/(1-α). */
+    B: number;
+}
+/**
+ * Run SPRT given the full observation sequence (1 = defect, 0 = clean).
+ * Continue while B < Λ < A. Accept H0 (p=p0) when Λ ≤ B; reject (p=p1) when Λ ≥ A.
+ *
+ * @param observations  array of 0/1 outcomes
+ * @param p0  null-hypothesis defect rate (e.g. 0.01)
+ * @param p1  alternative defect rate (e.g. 0.05)
+ * @param alpha  type-I error (default 0.05)
+ * @param beta  type-II error (default 0.05)
+ */
+export declare function sprtNext(observations: ReadonlyArray<0 | 1>, p0: number, p1: number, alpha?: number, beta?: number): SprtStep;
+/**
+ * Cochran's sample-size formula:  n = Z² · p(1-p) / e²
+ *   With finite-population correction (FPC) when populationSize given:
+ *   n_adj = n / (1 + (n-1) / N)
+ *
+ * @param p  expected proportion (use 0.5 for max variance / worst-case)
+ * @param e  margin of error (e.g., 0.05 for ±5%)
+ * @param z  z-score for desired confidence (default 1.96 for 95%)
+ * @param populationSize  optional finite-N for FPC adjustment
+ */
+export declare function cochranSize(p: number, e: number, z?: number, populationSize?: number): number;
+/**
+ * Neyman optimal allocation:
+ *   n_h = n · (N_h · σ_h) / Σ (N_i · σ_i)
+ *
+ * Returns per-stratum sample sizes. Rounds in a way that preserves Σ n_h = n.
+ *
+ * @param n  total sample size
+ * @param strataSizes  N_h per stratum
+ * @param strataStdDevs  σ_h per stratum (use √(p(1-p)) for proportions)
+ */
+export declare function neymanAllocate(n: number, strataSizes: ReadonlyArray<number>, strataStdDevs: ReadonlyArray<number>): number[];
+/**
+ * Pick `count` items from `items` without replacement (Fisher-Yates partial shuffle).
+ */
+export declare function sampleWithoutReplacement<T>(items: ReadonlyArray<T>, count: number, rand?: () => number): T[];
+/**
+ * Stratified sample selection.
+ *
+ * @param items        full population
+ * @param totalN       desired total sample
+ * @param strataKey    function (item) → stratum label
+ * @param priorRates   optional Record<stratum, defectRate> for variance estimation
+ * @param rand         RNG (test injection)
+ */
+export declare function selectAuditSample<T>(items: ReadonlyArray<T>, totalN: number, strataKey: (item: T) => string, priorRates?: Record<string, number>, rand?: () => number): {
+    samples: T[];
+    byStratum: Record<string, {
+        sampled: number;
+        total: number;
+    }>;
+};
+export {};
+//# sourceMappingURL=sampler.d.ts.map

package/dist/audit/sampler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampler.d.ts","sourceRoot":"","sources":["../../src/audit/sampler.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,8DAA8D;AAC9D,eAAO,MAAM,CAAC;IACZ,uCAAuC;;IAEvC,uBAAuB;;IAEvB,uBAAuB;;CAEf,CAAC;AAmCX;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAiBnE;AAUD,UAAU,OAAO;IACf,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,KAAK,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAwBD,wDAAwD;AACxD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAetD;AAMD,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAE3D,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,WAAW,CAAC;IACrB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,CAAC,EAAE,MAAM,CAAC;IACV,+BAA+B;IAC/B,CAAC,EAAE,MAAM,CAAC;CACX;AAED;;;;;;;;;GASG;AACH,wBAAgB,QAAQ,CACtB,YAAY,EAAE,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,EAClC,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,KAAK,SAAO,EACZ,IAAI,SAAO,GACV,QAAQ,CAyBV;AAMD;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,MAAM,EACT,CAAC,EAAE,MAAM,EACT,CAAC,GAAE,MAAe,EAClB,cAAc,CAAC,EAAE,MAAM,GACtB,MAAM,CAWR;AAMD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,CAAC,EAAE,MAAM,EACT,WAAW,EAAE,aAAa,CAAC,MAAM,CAAC,EAClC,aAAa,EAAE,aAAa,CAAC,MAAM,CAAC,GACnC,MAAM,EAAE,CAmDV;AAMD;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,eAAc,GAAG,CAAC,EAAE,CAc3G;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,MAAM,EAC9B,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACnC,IAAI,eAAc,GACjB;IAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAwCjF"}