@microwiseai/snapshot 0.6.0 → 0.7.0

package/dist/lib/install-verify.d.ts

@@ -0,0 +1,101 @@
+/**
+ * S1 — Post-install verification & convergence (SSOT enforcement).
+ *
+ * The manifest (snapshot.json) is the single source of truth: it pins every npm
+ * package to one exact version. But `npm install -g` is non-deterministic — a
+ * later batch/step can silently re-dedupe an earlier explicit pin to a different
+ * version on disk (see architecture/beta-pipeline-robustness-2026-08-30 §1 E2/E4).
+ *
+ * This module answers ONE question fail-loud: after install finishes, does the
+ * disk actually match the manifest pins? If not, we report `expected X, got Y`
+ * and the caller exits non-zero (no more "green on broken").
+ */
+export interface VersionMismatch {
+    /** Package name, e.g. "@ist/sesh". */
+    name: string;
+    /** The exact version the manifest pinned. */
+    expected: string;
+    /** The actual version found on disk, or null if the package is missing. */
+    got: string | null;
+}
+export interface VerificationResult {
+    /** True iff every package in the map matches its pin on disk. */
+    ok: boolean;
+    /** Every package whose disk version != pin (or is missing). */
+    mismatches: VersionMismatch[];
+    /** Count of packages whose disk version == pin. */
+    verifiedCount: number;
+    /** Total packages checked. */
+    total: number;
+}
+/** A function that returns the on-disk version of a global npm package, or null. */
+export type VersionReader = (name: string) => string | null;
+/** Test seam: reset the cached global npm root (used by unit tests). */
+export declare function _resetGlobalRootCache(): void;
+/**
+ * Read the ACTUAL on-disk version of a globally-installed npm package by reading
+ * its installed package.json directly from the global root. This reflects what
+ * `require()`/the runtime will actually load — unlike `npm ls` which reports the
+ * resolution tree. One `npm root -g` call is amortized across all packages
+ * (cached), so this is O(1) process spawns regardless of package count.
+ *
+ * Returns the version string, or null if the package is not installed on disk.
+ */
+export declare function readInstalledNpmVersion(name: string): string | null;
+/**
+ * Verify that every package in `installMap` (name → exact pin) is present on
+ * disk at exactly that version.
+ *
+ * Pure & side-effect free (aside from the injected reader): pass a custom
+ * `readVersion` for unit tests; defaults to reading the real global npm tree.
+ */
+export declare function verifyInstallMap(installMap: Record<string, string>, opts?: {
+    readVersion?: VersionReader;
+}): VerificationResult;
+/**
+ * S1 — convergence. Dependency-injected & pure (no console, no direct npm) so it
+ * is fully unit-testable and the integrator (install.ts) owns logging/exit.
+ *
+ * Given the manifest npm install-map and any FB pin overrides:
+ *   1. compute the effective map (pins with overrides applied),
+ *   2. verify it against the disk,
+ *   3. while unverified and within `maxRounds`, call `install(name, expected)`
+ *      for each mismatched package (exact, isolated re-pin) then re-verify.
+ *
+ * Returns the FINAL VerificationResult (ok=true iff the disk converged). The
+ * integrator decides how to react (exit non-zero, log, fold into the ledger).
+ *
+ * @param installMap manifest npm pins (name → exact version)
+ * @param overrides  FB pin overrides (name → version); {} for none
+ * @param deps.install     re-pin one package to an exact version (side-effecting)
+ * @param deps.readVersion disk reader (defaults to readInstalledNpmVersion)
+ * @param deps.maxRounds   max convergence rounds (default 3)
+ */
+export declare function runConverge(installMap: Record<string, string>, overrides: Record<string, string>, deps: {
+    install: (name: string, version: string) => void;
+    readVersion?: VersionReader;
+    maxRounds?: number;
+}): VerificationResult;
+/**
+ * Minimal read-only view of the install ledger. The ledger SCHEMA is owned by
+ * lib/ledger.ts (S3); this is a structural subset used only to read `expected`
+ * pins for offline verification (e.g. `snapshot doctor`) without importing the
+ * ledger module — so verify stays dependency-light and merge-clean.
+ */
+export interface LedgerLike {
+    packages?: Array<{
+        name?: unknown;
+        expected?: unknown;
+    }>;
+}
+/**
+ * Extract a `name → expected pin` map from a parsed ledger, defensively (unknown
+ * shapes / missing fields are skipped rather than throwing). Returns {} when the
+ * ledger has no usable expected pins.
+ */
+export declare function expectedMapFromLedger(ledger: LedgerLike | null | undefined): Record<string, string>;
+/**
+ * Format mismatches into a fail-loud, multi-line `expected X, got Y` report.
+ */
+export declare function formatVerificationFailure(mismatches: VersionMismatch[]): string;
+//# sourceMappingURL=install-verify.d.ts.map

package/dist/lib/install-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-verify.d.ts","sourceRoot":"","sources":["../../src/lib/install-verify.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;GAWG;AAEH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,iEAAiE;IACjE,EAAE,EAAE,OAAO,CAAC;IACZ,+DAA+D;IAC/D,UAAU,EAAE,eAAe,EAAE,CAAC;IAC9B,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;CACf;AAED,oFAAoF;AACpF,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAmB5D,wEAAwE;AACxE,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAYnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,IAAI,GAAE;IAAE,WAAW,CAAC,EAAE,aAAa,CAAA;CAAO,GACzC,kBAAkB,CAsBpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CACzB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACjC,IAAI,EAAE;IACJ,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,kBAAkB,CAapB;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAC1D;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAUnG;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,eAAe,EAAE,GAAG,MAAM,CAU/E"}

package/dist/lib/install-verify.js

@@ -0,0 +1,143 @@
+import { execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { applyPinOverrides } from './pin-override.js';
+let cachedGlobalRoot;
+/**
+ * Resolve the global npm `node_modules` root once (`npm root -g`) and cache it.
+ * Returns null if npm is unavailable.
+ */
+function getGlobalNpmRoot() {
+    if (cachedGlobalRoot !== undefined)
+        return cachedGlobalRoot;
+    try {
+        const root = execSync('npm root -g', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        cachedGlobalRoot = root || null;
+    }
+    catch {
+        cachedGlobalRoot = null;
+    }
+    return cachedGlobalRoot;
+}
+/** Test seam: reset the cached global npm root (used by unit tests). */
+export function _resetGlobalRootCache() {
+    cachedGlobalRoot = undefined;
+}
+/**
+ * Read the ACTUAL on-disk version of a globally-installed npm package by reading
+ * its installed package.json directly from the global root. This reflects what
+ * `require()`/the runtime will actually load — unlike `npm ls` which reports the
+ * resolution tree. One `npm root -g` call is amortized across all packages
+ * (cached), so this is O(1) process spawns regardless of package count.
+ *
+ * Returns the version string, or null if the package is not installed on disk.
+ */
+export function readInstalledNpmVersion(name) {
+    const root = getGlobalNpmRoot();
+    if (!root)
+        return null;
+    // Scoped names ("@ist/sesh") join correctly into "<root>/@ist/sesh".
+    const pkgJsonPath = join(root, name, 'package.json');
+    if (!existsSync(pkgJsonPath))
+        return null;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgJsonPath, 'utf-8'));
+        return typeof pkg.version === 'string' ? pkg.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Verify that every package in `installMap` (name → exact pin) is present on
+ * disk at exactly that version.
+ *
+ * Pure & side-effect free (aside from the injected reader): pass a custom
+ * `readVersion` for unit tests; defaults to reading the real global npm tree.
+ */
+export function verifyInstallMap(installMap, opts = {}) {
+    const readVersion = opts.readVersion ?? readInstalledNpmVersion;
+    const mismatches = [];
+    let verifiedCount = 0;
+    const names = Object.keys(installMap).sort((a, b) => a.localeCompare(b));
+    for (const name of names) {
+        const expected = installMap[name];
+        const got = readVersion(name);
+        if (got === expected) {
+            verifiedCount++;
+        }
+        else {
+            mismatches.push({ name, expected, got });
+        }
+    }
+    return {
+        ok: mismatches.length === 0,
+        mismatches,
+        verifiedCount,
+        total: names.length,
+    };
+}
+/**
+ * S1 — convergence. Dependency-injected & pure (no console, no direct npm) so it
+ * is fully unit-testable and the integrator (install.ts) owns logging/exit.
+ *
+ * Given the manifest npm install-map and any FB pin overrides:
+ *   1. compute the effective map (pins with overrides applied),
+ *   2. verify it against the disk,
+ *   3. while unverified and within `maxRounds`, call `install(name, expected)`
+ *      for each mismatched package (exact, isolated re-pin) then re-verify.
+ *
+ * Returns the FINAL VerificationResult (ok=true iff the disk converged). The
+ * integrator decides how to react (exit non-zero, log, fold into the ledger).
+ *
+ * @param installMap manifest npm pins (name → exact version)
+ * @param overrides  FB pin overrides (name → version); {} for none
+ * @param deps.install     re-pin one package to an exact version (side-effecting)
+ * @param deps.readVersion disk reader (defaults to readInstalledNpmVersion)
+ * @param deps.maxRounds   max convergence rounds (default 3)
+ */
+export function runConverge(installMap, overrides, deps) {
+    const effectiveMap = applyPinOverrides(installMap, overrides);
+    const readVersion = deps.readVersion ?? readInstalledNpmVersion;
+    const maxRounds = deps.maxRounds ?? 3;
+    let verification = verifyInstallMap(effectiveMap, { readVersion });
+    for (let round = 1; round <= maxRounds && !verification.ok; round++) {
+        for (const m of verification.mismatches) {
+            deps.install(m.name, m.expected);
+        }
+        verification = verifyInstallMap(effectiveMap, { readVersion });
+    }
+    return verification;
+}
+/**
+ * Extract a `name → expected pin` map from a parsed ledger, defensively (unknown
+ * shapes / missing fields are skipped rather than throwing). Returns {} when the
+ * ledger has no usable expected pins.
+ */
+export function expectedMapFromLedger(ledger) {
+    const map = {};
+    const pkgs = ledger?.packages;
+    if (!Array.isArray(pkgs))
+        return map;
+    for (const p of pkgs) {
+        if (p && typeof p.name === 'string' && typeof p.expected === 'string') {
+            map[p.name] = p.expected;
+        }
+    }
+    return map;
+}
+/**
+ * Format mismatches into a fail-loud, multi-line `expected X, got Y` report.
+ */
+export function formatVerificationFailure(mismatches) {
+    const lines = [
+        `Install verification failed: ${mismatches.length} package(s) do not match the manifest pin.`,
+        `The disk state diverged from the snapshot (SSOT). Re-run with --converge to auto-repair.`,
+    ];
+    for (const m of mismatches) {
+        const got = m.got === null ? '(not installed)' : m.got;
+        lines.push(`  ✗ ${m.name}: expected ${m.expected}, got ${got}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=install-verify.js.map

package/dist/lib/install-verify.js.map

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

package/dist/lib/ledger.d.ts

@@ -0,0 +1,212 @@
+/**
+ * ============================================================
+ * Install Ledger (S3 — beta-pipeline-robustness-2026-08-30 §4)
+ * ============================================================
+ *
+ * Records, at the END of an install, the provenance of every npm package that
+ * was installed: the manifest pin we asked for (`expected`), the version that
+ * actually landed on disk (`resolved`), the tarball URL it came from, the
+ * installer/step that produced it, and the ordered list of install steps.
+ *
+ * Goal (AC3.1): after any install, "이 버전이 어디서 왔나" ("where did this
+ * version come from?") is answerable from the ledger ALONE — no reverse
+ * engineering of the global node_modules.
+ *
+ * SCHEMA OWNERSHIP (manager freeze 2026-08-30): this file is the SSOT for the
+ * ledger schema; ledger.json is owned by S3 (this worker). Field names follow
+ * the 기획서. S1 (verify) and FB (pin override) live in verify-owned libs and
+ * do NOT own this schema. Dependency direction is one-way (verify → ledger):
+ * ledger.ts imports NOTHING from install-verify.ts / pin-override.ts.
+ *
+ * Writing the ledger MUST NOT break an install — every entry point here is
+ * best-effort and swallows its own errors.
+ */
+/** Current ledger schema version. Bump on breaking field changes. */
+export declare const LEDGER_SCHEMA_VERSION: 1;
+/** One recorded install step, in execution order. */
+export interface LedgerStep {
+    /** 1-based execution order across the whole install. */
+    order: number;
+    /**
+     * Which phase of the install produced this step. Stable identifiers:
+     *   'pre-install-batch'     — the single up-front `npm install -g` batch
+     *   'pre-install-fallback'  — per-package retry after the pre-install batch failed
+     *   'layer-batch'           — a per-snapshot-layer npm batch (installSnapshot)
+     *   'layer-fallback'        — per-package retry after a layer batch failed
+     *   'layer-parallel'        — non-npm (glpkg/generic) parallel install
+     *   'skit'                  — skit-adapter install
+     */
+    phase: string;
+    /** Installer name: 'npm-proxy' | 'glpkg' | 'skit' | ... */
+    installer: string;
+    /** The exact command executed (or a synthetic label for non-shell installers). */
+    command: string;
+    /** name@version specs this step targeted. */
+    specs: string[];
+    /** Outcome of the step. */
+    result: 'ok' | 'fallback' | 'failed';
+}
+/** Provenance for a single npm package, resolved after install. */
+export interface LedgerPackage {
+    /** Package name, e.g. "@ist/sesh". */
+    name: string;
+    /** Manifest pin we requested (SSOT intent). null if not declared as npm here. */
+    expected: string | null;
+    /** Version actually on disk after install (from `npm ls -g`). null if absent. */
+    resolved: string | null;
+    /** Tarball URL the resolved version was fetched from (from `npm ls -g`). */
+    tarballUrl: string | null;
+    /** Human/structured summary answering "where did this version come from?". */
+    resolutionSource: string;
+    /** Installer that handled this package. */
+    installer: string;
+}
+/**
+ * S1 (verify) verdict, folded into the ledger so verification and provenance
+ * live in one artifact. WRITTEN BY THE VERIFY WIRING (install.ts integrator),
+ * shaped to verifyInstallMap()'s return contract. Optional: absent until the
+ * verify pass runs.
+ */
+export interface LedgerVerification {
+    ok: boolean;
+    verifiedCount: number;
+    total: number;
+    mismatches: Array<{
+        name: string;
+        expected: string | null;
+        got: string | null;
+    }>;
+}
+/**
+ * AC1.4 — core-floor verdict folded into the ledger. Records every below-floor
+ * copy of the singleton package (@ist/adapters-core) found in the nested tree.
+ * Written by the install.ts integrator (coreFloorAssert lives in core-floor.ts).
+ */
+export interface LedgerCoreFloor {
+    ok: boolean;
+    pkg: string;
+    minVersion: string;
+    offenders: Array<{
+        path: string;
+        version: string;
+    }>;
+}
+/** The install ledger written to ~/.config/ist-snapshot/ledger.json. */
+export interface InstallLedger {
+    schemaVersion: typeof LEDGER_SCHEMA_VERSION;
+    snapshot: {
+        name: string;
+        version: string;
+    };
+    /** ISO timestamp the ledger was recorded. */
+    recordedAt: string;
+    /** snapshot CLI version that produced this ledger. */
+    cliVersion: string;
+    /** Registry the packages were fetched through (registry-proxy URL). */
+    registry: string;
+    packages: LedgerPackage[];
+    installSteps: LedgerStep[];
+    /** FB pin overrides applied this install (name → version). Empty unless FB used. */
+    overrides: Record<string, string>;
+    /** S1 verification verdict, if the verify pass ran. */
+    verification?: LedgerVerification;
+    /** AC1.4 core-floor verdict (nested singleton floor), if the assert ran. */
+    coreFloor?: LedgerCoreFloor;
+    /**
+     * DEEP (NOT --depth=0) `npm ls -g <names> --json --all` output captured
+     * post-install, stored verbatim. Scoped to the install's npm packages +
+     * @ist/adapters-core so NESTED copies are visible — this both (a) recovers
+     * "who required version X?" and (b) feeds coreFloorAssert (AC1.4). null if the
+     * query failed.
+     */
+    dependencyTreeRaw: unknown | null;
+}
+/**
+ * Accumulates install steps in execution order. One instance per install;
+ * threaded through installSnapshot via InstallSnapshotOptions.recorder.
+ */
+export declare class StepRecorder {
+    private steps;
+    record(step: Omit<LedgerStep, 'order'>): void;
+    getSteps(): LedgerStep[];
+}
+/** Path to the ledger file (sits next to current.json). */
+export declare function getLedgerPath(): string;
+export interface ResolvedQuery {
+    /** name → { version, tarballUrl } as read from the global tree. */
+    map: Map<string, {
+        version: string | null;
+        tarballUrl: string | null;
+    }>;
+    /** The raw parsed `npm ls` JSON (for dependencyTreeRaw), or null on failure. */
+    raw: unknown | null;
+}
+/**
+ * Query the globally-installed version + tarball URL for the given package
+ * names via a single `npm ls -g ... --json` call, and return the raw tree too.
+ * Best-effort: on total failure returns an all-null map and raw=null.
+ *
+ * NOTE: this is provenance extraction (version + tarball + raw tree), NOT the
+ * verify worker's single-name readInstalledNpmVersion(). No duplication of
+ * that helper — S3 never imports install-verify.
+ */
+export declare function queryResolvedVersions(names: string[]): ResolvedQuery;
+/**
+ * Derive the canonical npm tarball URL for a resolved package.
+ *
+ * npm 7+ does NOT persist the fetched tarball URL for global installs
+ * (`npm ls -g --json` omits `resolved`, package.json is stripped of `_resolved`,
+ * and there is no global lockfile). So when the authoritative URL is missing we
+ * reconstruct the standard registry path — the same one npm would fetch from the
+ * scope's configured registry:  `<registry>/<name>/-/<unscoped>-<version>.tgz`.
+ *
+ * Returns null when the version is unknown (nothing to point at). Best-effort:
+ * the registry is the one configured for the scope during install (registry-proxy).
+ */
+export declare function deriveTarballUrl(registry: string, name: string, version: string | null): string | null;
+/**
+ * Capture a DEEP dependency tree (`npm ls -g <names> --json --all`) for the
+ * ledger's `dependencyTreeRaw` and for coreFloorAssert (AC1.4).
+ *
+ * ★ Deliberately NOT `--depth=0`: nested copies must be visible (an old
+ * @ist/adapters-core buried under another package is exactly what re-fragments
+ * the registry). To avoid the cost of dumping the ENTIRE global tree, we scope
+ * the query to the install's npm packages + the singleton package — with filter
+ * args, `npm ls` prunes to the paths that reach those names (full depth), which
+ * is bounded yet still surfaces every nested copy of the targets.
+ *
+ * Best-effort: returns null on failure (ledger writing never fails an install).
+ */
+export declare function queryDependencyTree(names: string[]): unknown | null;
+export interface BuildLedgerInput {
+    snapshotName: string;
+    snapshotVersion: string;
+    cliVersion: string;
+    registry: string;
+    /** Manifest pins for npm packages: name -> version. The "expected" set. */
+    expected: Record<string, string>;
+    /** Installer used for the npm packages (typically 'npm-proxy'). */
+    installer: string;
+    steps: LedgerStep[];
+    /** FB pin overrides (name -> version), if any. */
+    overrides?: Record<string, string>;
+    /**
+     * DEEP dependency tree for `dependencyTreeRaw` (from queryDependencyTree).
+     * When provided it takes precedence over the resolver's shallow tree — the
+     * integrator captures a nested-visible tree (AC1.4). null/undefined → fall
+     * back to the resolver's tree.
+     */
+    dependencyTreeRaw?: unknown | null;
+}
+/**
+ * Assemble the ledger: query disk for resolved versions/tarballs, then join
+ * against the expected pins and install steps to explain each package's origin.
+ * `now` is injected (callers stamp the timestamp) to keep this pure/testable.
+ * `resolver` is injectable for tests; defaults to the real `npm ls -g` query.
+ */
+export declare function buildLedger(input: BuildLedgerInput, now: string, resolver?: (names: string[]) => ResolvedQuery): InstallLedger;
+/** Write the ledger to disk. Best-effort — never throws into the caller. */
+export declare function writeLedger(ledger: InstallLedger): boolean;
+/** Read the ledger from disk, or null if absent/unreadable. */
+export declare function readLedger(): InstallLedger | null;
+//# sourceMappingURL=ledger.d.ts.map

package/dist/lib/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../../src/lib/ledger.ts"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,qEAAqE;AACrE,eAAO,MAAM,qBAAqB,EAAG,CAAU,CAAC;AAEhD,qDAAqD;AACrD,MAAM,WAAW,UAAU;IACzB,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,6CAA6C;IAC7C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,2BAA2B;IAC3B,MAAM,EAAE,IAAI,GAAG,UAAU,GAAG,QAAQ,CAAC;CACtC;AAED,mEAAmE;AACnE,MAAM,WAAW,aAAa;IAC5B,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,iFAAiF;IACjF,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,OAAO,CAAC;IACZ,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;CAClF;AAED;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,OAAO,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACrD;AAED,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,aAAa,EAAE,OAAO,qBAAqB,CAAC;IAC5C,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAC;IACnB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,aAAa,EAAE,CAAC;IAC1B,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,oFAAoF;IACpF,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,uDAAuD;IACvD,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAClC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;;;OAMG;IACH,iBAAiB,EAAE,OAAO,GAAG,IAAI,CAAC;CACnC;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAoB;IAEjC,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,GAAG,IAAI;IAI7C,QAAQ,IAAI,UAAU,EAAE;CAGzB;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,IAAI,MAAM,CAGtC;AAQD,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,GAAG,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE,CAAC,CAAC;IACxE,gFAAgF;IAChF,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,aAAa,CAsCpE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GAAG,IAAI,GACrB,MAAM,GAAG,IAAI,CAOf;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,OAAO,GAAG,IAAI,CAoBnE;AAyBD,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,MAAM,CAAC;IACrB,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,2EAA2E;IAC3E,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,UAAU,EAAE,CAAC;IACpB,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnC;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CACpC;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,gBAAgB,EACvB,GAAG,EAAE,MAAM,EACX,QAAQ,GAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,aAAqC,GACnE,aAAa,CAyDf;AAED,4EAA4E;AAC5E,wBAAgB,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAU1D;AAED,+DAA+D;AAC/D,wBAAgB,UAAU,IAAI,aAAa,GAAG,IAAI,CAQjD"}