@nodetool-ai/reliability-harness 0.8.1

package/README.md

@@ -0,0 +1,34 @@
+# @nodetool-ai/reliability-harness
+
+Core of NodeTool's reliability harness: journey manifests, the `RunRecord`
+format, output normalization, and per-channel stream diffing.
+
+A journey replays a scripted workload against a driver and records everything
+it emitted as a `RunRecord`. Normalization strips the parts that legitimately
+change between runs (ids, timestamps, durations) so two records compare on
+behavior alone; the diff is per channel, so a change in log output does not
+mask a change in results.
+
+## Layout
+
+| Path | Holds |
+|---|---|
+| `core/journey.ts` | Journey manifest schema and loading |
+| `core/record.ts` | `RunRecord` — what one replay captured |
+| `core/normalize.ts` | Run-to-run variance stripped before comparison |
+| `core/diff.ts` | Per-channel stream diff |
+| `core/golden.ts` | Golden-record read/write |
+| `core/invariants/` | Assertions that must hold across every journey |
+| `drivers/` | What a journey drives |
+| `faults/` | Fault injection |
+
+## Usage
+
+```bash
+npm install @nodetool-ai/reliability-harness
+```
+
+The package also ships a CLI entry (`cli.ts`) used by the repo's Ring 0
+reliability journeys, which `nodetool harness gate` selects for diffs touching
+`packages/kernel/`.
+

package/dist/.nodetool-build-stamp

@@ -0,0 +1 @@
+2026-09-28T09:19:18.697Z

package/dist/cli.d.ts

@@ -0,0 +1,73 @@
+import { formatCompareReport, type CompareDriver, type CompareReport } from "./compare.js";
+import "./faults/index.js";
+/** Every surface `nodetool reliability run --surface` accepts, keyed to a
+ * fresh driver instance — fresh per call so two `runJourney` calls (e.g. the
+ * CLI's own `--json` and human-readable paths, or a test loop) never share
+ * driver-local state. */
+export declare const DRIVER_FACTORIES: Readonly<Record<string, () => CompareDriver>>;
+/**
+ * §9's fault seams, named — the full target vocabulary across D1 (provider,
+ * shipped)/D2 (ws)/D3 (bridge, host, client). `--faults` validates a
+ * requested name against this list (a typo is a CLI error, not a silent
+ * no-op); whether the name actually does anything at runtime depends on
+ * whether a `FaultModule` is registered for it (`faults/registry.ts`) — see
+ * `runJourney`'s `unknownFaults` handling for names in this list a module
+ * hasn't shipped for yet.
+ */
+export declare const KNOWN_FAULT_TYPES: readonly string[];
+export declare class ReliabilityCliError extends Error {
+}
+/** Walks up from this module to the checkout's `reliability/journeys` — works
+ * from both `src/` (tsx dev) and `dist/` (built) locations. */
+export declare function findJourneysDir(): string;
+interface JourneySummary {
+    name: string;
+    description?: string;
+    surfaces: string[];
+    invariants: string[];
+    timeoutMs: number;
+}
+/** Every journey directory under `journeysDir` (default: the repo's
+ * `reliability/journeys`), loaded and summarized for `nodetool reliability
+ * list`. */
+export declare function listJourneys(journeysDir?: string): Promise<JourneySummary[]>;
+interface RunJourneyOptions {
+    journeysDir?: string;
+    /** Overrides the journey manifest's own `surfaces` list. The oracle
+     * (`kernel`) is always included even if omitted — `compareJourney` needs it
+     * present to diff against. */
+    surfaces?: string[];
+    /**
+     * Fault names to inject (§9), replacing the journey's own declared `faults`
+     * block for this run — validated against `KNOWN_FAULT_TYPES`, then resolved
+     * to `FaultModule`s by `compareJourney` (task D1). A name the journey
+     * already declares (with a `surface` restriction or `params`) is reused
+     * as-is; a name given here that the journey doesn't declare runs
+     * unrestricted (every surface) with no params.
+     */
+    faults?: string[];
+}
+/** Runs one journey's differential compare across its (or the caller's
+ * override) surfaces. This is what `nodetool reliability run <journey>`
+ * calls. */
+export declare function runJourney(journeyName: string, options?: RunJourneyOptions): Promise<CompareReport>;
+/**
+ * Rewrites a journey's `expected/` fixtures from a fresh, unfaulted oracle
+ * (kernel) run — the maintainer path for a golden that legitimately moved.
+ *
+ * Only writes the fixtures the journey declares, and refuses a run that
+ * didn't complete: a golden captured from a broken run bakes the breakage in.
+ * Review the diff — that is what makes the fixture an assertion rather than a
+ * transcript.
+ */
+export declare function updateJourneyGoldens(journeyName: string, options?: {
+    journeysDir?: string;
+}): Promise<{
+    written: string[];
+}>;
+/** Every fault name a `FaultModule` is actually registered for right now —
+ * a subset of `KNOWN_FAULT_TYPES` until D2/D3 ship their seams. Exposed for
+ * `nodetool reliability list --faults`-style introspection. */
+export declare function listImplementedFaultTypes(): string[];
+export { formatCompareReport, type CompareReport };
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAYA,OAAO,EAAkB,mBAAmB,EAAE,KAAK,aAAa,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAY3G,OAAO,mBAAmB,CAAC;AAE3B;;;yBAGyB;AACzB,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,aAAa,CAAC,CAO1E,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,EAAE,SAAS,MAAM,EA0B9C,CAAC;AAEF,qBAAa,mBAAoB,SAAQ,KAAK;CAAG;AAEjD;+DAC+D;AAC/D,wBAAgB,eAAe,IAAI,MAAM,CAaxC;AAED,UAAU,cAAc;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;YAEY;AACZ,wBAAsB,YAAY,CAAC,WAAW,GAAE,MAA0B,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC,CAiBrG;AAED,UAAU,iBAAiB;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;kCAE8B;IAC9B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AA2BD;;YAEY;AACZ,wBAAsB,UAAU,CAC9B,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,aAAa,CAAC,CA6BxB;AAED;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAO,GACrC,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA+BhC;AAED;;+DAE+D;AAC/D,wBAAgB,yBAAyB,IAAI,MAAM,EAAE,CAEpD;AAED,OAAO,EAAE,mBAAmB,EAAE,KAAK,aAAa,EAAE,CAAC"}

package/dist/cli.js

@@ -0,0 +1,201 @@
+/**
+ * `nodetool reliability` orchestration (§12's package-diagram `cli.ts`).
+ * `packages/cli/src/commands/reliability.ts` is a thin Commander wrapper over
+ * this module — same split as the debug harness (`packages/cli/src/debug/`
+ * does the work, `commands/debug.ts` just parses flags and prints).
+ */
+import { existsSync } from "node:fs";
+import { readdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadJourney } from "./core/journey.js";
+import { streamShapeOf, terminalOutputsOf } from "./core/golden.js";
+import { compareJourney, formatCompareReport } from "./compare.js";
+import { KernelDriver } from "./drivers/kernel.js";
+import { WsServerDriver } from "./drivers/ws-server.js";
+import { CliDriver } from "./drivers/cli.js";
+import { BrowserDriver } from "./drivers/browser.js";
+import { AppHeadlessDriver } from "./drivers/app-headless.js";
+import { PackagedDriver } from "./drivers/packaged.js";
+import { listFaultModuleNames } from "./faults/registry.js";
+// Side-effecting import: registers every built-in fault module, same
+// contract as `compare.ts`'s own import — needed here too since
+// `listFaultModuleNames()`/name validation below run before `compareJourney`
+// would otherwise trigger it.
+import "./faults/index.js";
+/** Every surface `nodetool reliability run --surface` accepts, keyed to a
+ * fresh driver instance — fresh per call so two `runJourney` calls (e.g. the
+ * CLI's own `--json` and human-readable paths, or a test loop) never share
+ * driver-local state. */
+export const DRIVER_FACTORIES = {
+    kernel: () => new KernelDriver(),
+    "ws-server": () => new WsServerDriver(),
+    cli: () => new CliDriver(),
+    browser: () => new BrowserDriver(),
+    "app-headless": () => new AppHeadlessDriver(),
+    packaged: () => new PackagedDriver()
+};
+/**
+ * §9's fault seams, named — the full target vocabulary across D1 (provider,
+ * shipped)/D2 (ws)/D3 (bridge, host, client). `--faults` validates a
+ * requested name against this list (a typo is a CLI error, not a silent
+ * no-op); whether the name actually does anything at runtime depends on
+ * whether a `FaultModule` is registered for it (`faults/registry.ts`) — see
+ * `runJourney`'s `unknownFaults` handling for names in this list a module
+ * hasn't shipped for yet.
+ */
+export const KNOWN_FAULT_TYPES = [
+    "provider-429",
+    "provider-500",
+    "provider-timeout",
+    "provider-truncated-stream",
+    "provider-malformed-sse",
+    "provider-slow-drip",
+    "provider-cost-omission",
+    "ws-drop-no-fin",
+    "ws-delay",
+    "ws-reorder",
+    "ws-fragment",
+    "ws-stall-reads",
+    "ws-abrupt-close",
+    "bridge-exit-mid-request",
+    "bridge-framing-violation",
+    "bridge-never-ready",
+    "bridge-epipe",
+    "bridge-version-mismatch",
+    "host-sigkill-restart",
+    "host-disk-full",
+    "host-db-locked",
+    "client-cancel-storm",
+    "client-reconnect-storm",
+    "client-duplicate-command",
+    "client-out-of-order-end-stream"
+];
+export class ReliabilityCliError extends Error {
+}
+/** Walks up from this module to the checkout's `reliability/journeys` — works
+ * from both `src/` (tsx dev) and `dist/` (built) locations. */
+export function findJourneysDir() {
+    const start = dirname(fileURLToPath(import.meta.url));
+    let dir = start;
+    for (let i = 0; i < 12; i++) {
+        const candidate = join(dir, "reliability", "journeys");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new ReliabilityCliError(`could not locate reliability/journeys above ${start} — pass journeysDir explicitly`);
+}
+/** Every journey directory under `journeysDir` (default: the repo's
+ * `reliability/journeys`), loaded and summarized for `nodetool reliability
+ * list`. */
+export async function listJourneys(journeysDir = findJourneysDir()) {
+    const entries = await readdir(journeysDir, { withFileTypes: true });
+    const names = entries.filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    const summaries = [];
+    for (const name of names) {
+        const dir = join(journeysDir, name);
+        if (!existsSync(join(dir, "journey.json")))
+            continue;
+        const journey = await loadJourney(dir);
+        summaries.push({
+            name: journey.manifest.name,
+            description: journey.manifest.description,
+            surfaces: journey.manifest.surfaces,
+            invariants: journey.manifest.assertions.invariants,
+            timeoutMs: journey.manifest.timeoutMs
+        });
+    }
+    return summaries;
+}
+/** Resolves `--faults` names against the journey's own declared `faults`
+ * block: reuse a matching entry (keeping its `surface`/`params`) when one
+ * exists, else synthesize an unrestricted, param-less entry. Passing no
+ * `--faults` at all keeps the journey's full declared matrix unchanged. */
+function resolveFaultSelection(journey, requestedNames) {
+    if (!requestedNames || requestedNames.length === 0) {
+        return journey.manifest.faults;
+    }
+    return requestedNames.map((type) => {
+        const declared = journey.manifest.faults.find((f) => f.type === type);
+        return declared ?? { type };
+    });
+}
+async function resolveJourney(journeyName, journeysDir) {
+    const dir = join(journeysDir, journeyName);
+    if (!existsSync(join(dir, "journey.json"))) {
+        throw new ReliabilityCliError(`no journey named "${journeyName}" in ${journeysDir}`);
+    }
+    return loadJourney(dir);
+}
+/** Runs one journey's differential compare across its (or the caller's
+ * override) surfaces. This is what `nodetool reliability run <journey>`
+ * calls. */
+export async function runJourney(journeyName, options = {}) {
+    const journeysDir = options.journeysDir ?? findJourneysDir();
+    const journey = await resolveJourney(journeyName, journeysDir);
+    const requested = options.surfaces && options.surfaces.length > 0
+        ? options.surfaces
+        : journey.manifest.surfaces;
+    const surfaceNames = requested.includes("kernel") ? requested : ["kernel", ...requested];
+    for (const name of surfaceNames) {
+        if (!DRIVER_FACTORIES[name]) {
+            throw new ReliabilityCliError(`unknown surface "${name}" — valid surfaces: ${Object.keys(DRIVER_FACTORIES).join(", ")}`);
+        }
+    }
+    for (const fault of options.faults ?? []) {
+        if (!KNOWN_FAULT_TYPES.includes(fault)) {
+            throw new ReliabilityCliError(`unknown fault "${fault}" — known fault names: ${KNOWN_FAULT_TYPES.join(", ")}`);
+        }
+    }
+    const drivers = surfaceNames.map((name) => DRIVER_FACTORIES[name]());
+    const faults = resolveFaultSelection(journey, options.faults);
+    const report = await compareJourney(journey, drivers, { faults });
+    return report;
+}
+/**
+ * Rewrites a journey's `expected/` fixtures from a fresh, unfaulted oracle
+ * (kernel) run — the maintainer path for a golden that legitimately moved.
+ *
+ * Only writes the fixtures the journey declares, and refuses a run that
+ * didn't complete: a golden captured from a broken run bakes the breakage in.
+ * Review the diff — that is what makes the fixture an assertion rather than a
+ * transcript.
+ */
+export async function updateJourneyGoldens(journeyName, options = {}) {
+    const journeysDir = options.journeysDir ?? findJourneysDir();
+    const journey = await resolveJourney(journeyName, journeysDir);
+    const { assertions } = journey.manifest;
+    if (!assertions.outputs && !assertions.streamShape) {
+        throw new ReliabilityCliError(`journey "${journeyName}" declares no golden assertions to update`);
+    }
+    const record = await new KernelDriver().run(journey);
+    if (record.status !== "completed") {
+        throw new ReliabilityCliError(`journey "${journeyName}" ended "${record.status}" (${record.error ?? "no error"}) — ` +
+            "refusing to capture goldens from a run that didn't complete");
+    }
+    const expectedDir = join(journeysDir, journeyName, "expected");
+    const written = [];
+    if (assertions.outputs) {
+        const file = join(expectedDir, "outputs.json");
+        await writeFile(file, `${JSON.stringify(terminalOutputsOf(record), null, 2)}\n`);
+        written.push(file);
+    }
+    if (assertions.streamShape) {
+        const file = join(expectedDir, "stream.shape.json");
+        await writeFile(file, `${JSON.stringify(streamShapeOf(record), null, 2)}\n`);
+        written.push(file);
+    }
+    return { written };
+}
+/** Every fault name a `FaultModule` is actually registered for right now —
+ * a subset of `KNOWN_FAULT_TYPES` until D2/D3 ship their seams. Exposed for
+ * `nodetool reliability list --faults`-style introspection. */
+export function listImplementedFaultTypes() {
+    return listFaultModuleNames();
+}
+export { formatCompareReport };
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/compare.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Cross-surface differential compare (§12): runs one journey on N drivers,
+ * normalizes every record, diffs each non-oracle surface against the kernel
+ * oracle (§12: "the kernel surface is the oracle... every-surface-vs-kernel,
+ * not all-pairs"), and aggregates the journey's declared §6 invariant checks
+ * per surface. Produces one structured report plus a human-readable
+ * formatter for `nodetool reliability run`.
+ */
+import type { Journey, JourneyFault } from "./core/journey.js";
+import { type StreamDiff } from "./core/diff.js";
+import { type GoldenCheckResult } from "./core/golden.js";
+import { type Violation } from "./core/invariants/index.js";
+import type { RunDriver } from "./drivers/types.js";
+import "./faults/index.js";
+/** A `RunDriver` that additionally knows whether it applies to a given
+ * journey (added additively by C4 — `supports` is optional on the base
+ * `RunDriver` interface so C2's kernel/ws-server drivers need no change). */
+export interface CompareDriver extends RunDriver {
+    supports?(journey: Journey): boolean;
+}
+interface SurfaceCompareResult {
+    surface: string;
+    /** False when the driver declared (via `supports`) that this journey does
+     * not apply to it, or when the driver's `run()` threw. */
+    ran: boolean;
+    /** Why this surface didn't run — either "not applicable" (`supports`
+     * returned false) or the driver's thrown error. Only set when `!ran`. */
+    skipReason?: string;
+    status?: string;
+    error?: string | null;
+    /** §6 invariant violations from the journey's declared `assertions.invariants`. */
+    violations: Violation[];
+    /**
+     * Golden comparisons the journey declared (`assertions.outputs`,
+     * `assertions.streamShape`), one entry each. A skipped entry (faulted run)
+     * carries its reason — the fixtures are never silently ignored.
+     */
+    goldens: GoldenCheckResult[];
+    /** Diff against the oracle's normalized `server_to_client` frames — `null`
+     * for the oracle surface itself, or when the surface didn't run. */
+    diffVsOracle: StreamDiff | null;
+    diffVsOracleEmpty: boolean;
+    /** True when this surface is not applicable to the journey (a `supports`
+     * check said no) — distinct from a real failure so a report can render it
+     * as "n/a" rather than "FAIL". */
+    notApplicable: boolean;
+    /** Fault names actually configured for this surface's run (task D1) — a
+     * subset of the journey's declared/`--faults`-selected faults, filtered by
+     * each fault's optional `surface` restriction and by module availability. */
+    faultsApplied: string[];
+    ok: boolean;
+}
+export interface CompareReport {
+    journeyId: string;
+    oracle: string;
+    /** Invariant names the journey declared that no `INVARIANT_CHECKS` entry
+     * recognizes — a journey-authoring mistake, surfaced instead of silently
+     * skipped. */
+    unknownInvariants: string[];
+    /** Fault names requested (via the journey's `faults` block or `--faults`)
+     * that no `FaultModule` is registered for (task D1) — surfaced the same
+     * way `unknownInvariants` is, instead of silently no-oping the fault. */
+    unknownFaults: string[];
+    surfaces: SurfaceCompareResult[];
+    verdict: {
+        ok: boolean;
+        issues: string[];
+    };
+}
+/**
+ * Runs `journey` on every driver in `drivers`, diffing each non-oracle
+ * surface's normalized `server_to_client` stream against the oracle's (the
+ * one driver named `options.oracleName`, default `"kernel"` — §12's "the
+ * kernel surface is the oracle"). `drivers` must include the oracle driver
+ * itself; it both anchors the diff and is reported as its own (trivially
+ * clean) surface.
+ *
+ * `options.faults` (task D1) selects the fault matrix for this run — default
+ * is the journey's own declared `faults` block (`journey.json`), so callers
+ * that don't care about fault injection get the journey's authored behavior
+ * unchanged. Each applicable fault (its `surface` restriction, if any,
+ * matched against the driver about to run) is configured immediately before
+ * that driver's `run()` and torn down immediately after, so faults never
+ * leak across drivers or across `compareJourney` calls.
+ */
+export declare function compareJourney(journey: Journey, drivers: CompareDriver[], options?: {
+    oracleName?: string;
+    faults?: JourneyFault[];
+}): Promise<CompareReport>;
+/** Human-readable rendering of a `CompareReport` for `nodetool reliability run`.
+ * `showDiff` (default `true`) controls whether a diverging surface's full
+ * per-channel stream diff is inlined under its summary line, or just noted —
+ * `nodetool reliability run`'s `--diff` flag maps straight to this. */
+export declare function formatCompareReport(report: CompareReport, options?: {
+    showDiff?: boolean;
+}): string;
+export {};
+//# sourceMappingURL=compare.d.ts.map

package/dist/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC/D,OAAO,EAA8D,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC7G,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AACxE,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAG9E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAOpD,OAAO,mBAAmB,CAAC;AAE3B;;6EAE6E;AAC7E,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,QAAQ,CAAC,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CACtC;AAED,UAAU,oBAAoB;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB;8DAC0D;IAC1D,GAAG,EAAE,OAAO,CAAC;IACb;6EACyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mFAAmF;IACnF,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB;;;;OAIG;IACH,OAAO,EAAE,iBAAiB,EAAE,CAAC;IAC7B;wEACoE;IACpE,YAAY,EAAE,UAAU,GAAG,IAAI,CAAC;IAChC,iBAAiB,EAAE,OAAO,CAAC;IAC3B;;sCAEkC;IAClC,aAAa,EAAE,OAAO,CAAC;IACvB;;iFAE6E;IAC7E,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,EAAE,EAAE,OAAO,CAAC;CACb;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;kBAEc;IACd,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B;;6EAEyE;IACzE,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,OAAO,EAAE;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAC5C;AAqDD;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,aAAa,EAAE,EACxB,OAAO,GAAE;IAAE,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,YAAY,EAAE,CAAA;CAAO,GAC7D,OAAO,CAAC,aAAa,CAAC,CA0JxB;AAED;;;uEAGuE;AACvE,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,aAAa,EACrB,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAO,GACnC,MAAM,CAwDR"}