@legioncodeinc/nectar 0.0.1

package/dist/registration/disk-fs.js.map

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

package/dist/registration/fs-watch.d.ts

@@ -0,0 +1,114 @@
+import { type Timer } from "../poll-loop.js";
+import type { IgnorePredicate } from "./ignore.js";
+/** The watcher's own liveness state (PRD-018c AC-018c.6/7), independent of debounce state. */
+export type WatcherState = "stopped" | "running" | "restarting" | "degraded";
+/** The minimal shape `WatchIntake` needs from a watch handle - `node:fs`'s real `FSWatcher` satisfies this structurally. */
+export interface WatchHandle {
+    on(event: "error", listener: (err: unknown) => void): unknown;
+    close(): void;
+}
+/** The raw `fs.watch`-shaped constructor. Injectable (PRD-018c AC-018c.6/7) so a test can simulate a watcher error/restart cycle without a real filesystem. Defaults to `node:fs`'s `watch`. */
+export type WatchFn = (path: string, options: {
+    readonly recursive: boolean;
+}, listener: (eventType: string, filename: string | null) => void) => WatchHandle;
+export interface WatchIntakeOptions {
+    readonly root: string;
+    /** DEFAULT - confirm before implementation. Mirrors honeycomb's file-watcher debounce. */
+    readonly debounceMs?: number;
+    readonly onPathChanged: (relPath: string) => void;
+    /**
+     * Max total deferral for a single path (NEC-042 item 9 / AC-018l.16). A path
+     * written more often than `debounceMs` never settles under a pure debounce; a
+     * max-wait cap forces the change through once this window elapses since the
+     * FIRST observation of the burst, regardless of continuing events. Default:
+     * {@link DEFAULT_MAX_WAIT_MULTIPLIER} x `debounceMs`.
+     */
+    readonly maxWaitMs?: number;
+    /** Fired (debounced) when a null-filename observation demands a full workspace resync (AC-3). */
+    readonly onResync?: () => void;
+    /** Ignore contract; an ignored path never reaches the scheduler (AC-5). Defaults to allow-all. */
+    readonly isIgnored?: IgnorePredicate;
+    readonly timer?: Timer;
+    readonly onError?: (err: unknown) => void;
+    /** Fired whenever the watcher's liveness state changes (AC-018c.6/7). Defaults to a no-op. */
+    readonly onStateChange?: (state: WatcherState) => void;
+    /** Backoff floor for a restart-after-error (ms). DEFAULT 1000. */
+    readonly restartBackoffFloorMs?: number;
+    /** Backoff ceiling for a restart-after-error (ms). DEFAULT 30000. */
+    readonly restartBackoffCeilingMs?: number;
+    /** Consecutive restart failures before parking "degraded" (AC-018c.7). DEFAULT 5. */
+    readonly maxRestartAttempts?: number;
+    /** The raw watch constructor (default: `node:fs`'s `watch`). Injectable for deterministic error/restart tests (AC-018c.6/7). */
+    readonly watchFn?: WatchFn;
+}
+export declare const DEFAULT_DEBOUNCE_MS = 500;
+/** Default max-wait cap as a multiple of the debounce window (NEC-042 item 9 / AC-018l.16). */
+export declare const DEFAULT_MAX_WAIT_MULTIPLIER = 10;
+export declare const DEFAULT_RESTART_BACKOFF_FLOOR_MS = 1000;
+export declare const DEFAULT_RESTART_BACKOFF_CEILING_MS = 30000;
+export declare const DEFAULT_MAX_RESTART_ATTEMPTS = 5;
+export declare class WatchIntake {
+    private readonly root;
+    private readonly debounceMs;
+    private readonly maxWaitMs;
+    private readonly onPathChanged;
+    private readonly onResync;
+    private readonly isIgnored;
+    private readonly timer;
+    private readonly onError;
+    private readonly onStateChange;
+    private readonly restartBackoffFloorMs;
+    private readonly restartBackoffCeilingMs;
+    private readonly maxRestartAttempts;
+    private readonly watchFn;
+    private watcher;
+    private readonly pending;
+    /** Per-key max-wait timers (AC-018l.16): armed once per burst, NOT reset per observation. */
+    private readonly maxWaitPending;
+    /** Per-key burst guard so the debounce timer and the max-wait cap fire the settle at most once. */
+    private readonly bursts;
+    private state;
+    private restartAttempts;
+    private restartHandle;
+    /** Set by `stop()`; suppresses any restart scheduled by a since-superseded error. */
+    private stopped;
+    constructor(opts: WatchIntakeOptions);
+    /** The watcher's current liveness state (AC-018c.6/7). */
+    get watcherState(): WatcherState;
+    /**
+     * Route one raw `fs.watch` observation. A null/undefined filename (a
+     * directory-level event with no specific path on some platforms) requests a
+     * full resync; a concrete filename goes through the per-path debounce. Public
+     * so tests can drive both branches without a real filesystem.
+     */
+    observeRaw(filename: string | null | undefined): void;
+    /**
+     * Feed a concrete path observation into the debouncer. Ignored paths are
+     * dropped before scheduling. Public so tests can drive it without a real
+     * filesystem; `start()` wires `fs.watch` through `observeRaw` to call this.
+     */
+    observe(relPath: string): void;
+    /**
+     * Request a debounced full-workspace resync settle (AC-3). Collapses a burst
+     * of null-filename events into a single `onResync` the same way a per-path
+     * burst collapses into one signal.
+     */
+    requestResync(): void;
+    private schedule;
+    /** Begin watching the root recursively. Idempotent. */
+    start(): void;
+    private attach;
+    /**
+     * PRD-018c NEC-009 / AC-018c.6/7: an `fs.watch` error means the underlying
+     * `FSWatcher` is typically dead. Close it, log via `onError` (preserving the
+     * pre-018c logging behavior), and - unless `stop()` already superseded this
+     * error - schedule a backoff-guarded restart rather than leaving live
+     * updates dead while `/health` still reports the daemon healthy.
+     */
+    private handleWatcherError;
+    private scheduleRestart;
+    private setState;
+    /** Stop watching, cancel every pending debounce, and cancel any scheduled restart. Idempotent. */
+    stop(): void;
+}
+//# sourceMappingURL=fs-watch.d.ts.map

package/dist/registration/fs-watch.d.ts.map

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

package/dist/registration/fs-watch.js

@@ -0,0 +1,266 @@
+/**
+ * File-watch intake with debounce (PRD-006a).
+ *
+ * Wraps `node:fs.watch` (directory-level, recursive) and debounces per path with
+ * `setTimeout`/`clearTimeout`: multiple uncorrelated `(eventType, filename)`
+ * observations on the same path within the window collapse to one "path changed"
+ * signal, which then enters the re-association ladder. This mirrors honeycomb's
+ * `file-watcher.ts` pattern; chokidar is deliberately NOT a dependency (decision #4).
+ *
+ * Two intake behaviors beyond the plain per-path debounce:
+ *   - A `null`/`undefined` filename observation (some platforms emit null on a
+ *     directory-level event, per honeycomb `file-watcher.ts:342-345`) triggers a
+ *     debounced FULL resync settle via `onResync`, not a dropped event (AC-3).
+ *   - Every observation is filtered through the injected ignore contract before
+ *     it reaches the debounce scheduler, so ignored paths (`.git/`,
+ *     `node_modules/`, the per-repo `graph-ignore.json` set) never trigger a
+ *     cycle (AC-5). No nectar-specific ignore list is invented.
+ *
+ * PRD-018c NEC-009 / AC-018c.6/7: a raw `fs.watch` error (Linux `ENOSPC`,
+ * `EPERM`/`EBUSY` on a renamed/recreated root) no longer kills live updates
+ * permanently. The watcher is closed and re-`watch()`ed with exponential
+ * backoff; a successful re-attach requests a full resync (via the SAME
+ * debounced `requestResync` path AC-3 already established) so the outage
+ * window is reconciled; repeated failures beyond `maxRestartAttempts` park the
+ * intake in a "degraded" state instead of looping hot. `onStateChange`
+ * surfaces "running" / "restarting" / "degraded" / "stopped" so `/health` can
+ * show watcher liveness (AC-018c.6/7).
+ *
+ * The timer seam is injected so tests are deterministic under a manual clock.
+ */
+import { watch } from "node:fs";
+import { realTimer } from "../poll-loop.js";
+import { isSafeRelPath } from "./paths-safe.js";
+export const DEFAULT_DEBOUNCE_MS = 500;
+/** Default max-wait cap as a multiple of the debounce window (NEC-042 item 9 / AC-018l.16). */
+export const DEFAULT_MAX_WAIT_MULTIPLIER = 10;
+export const DEFAULT_RESTART_BACKOFF_FLOOR_MS = 1_000;
+export const DEFAULT_RESTART_BACKOFF_CEILING_MS = 30_000;
+export const DEFAULT_MAX_RESTART_ATTEMPTS = 5;
+/** The sentinel debounce key for the full-resync settle (kept distinct from any real path). */
+const RESYNC_KEY = "\u0000resync";
+export class WatchIntake {
+    root;
+    debounceMs;
+    maxWaitMs;
+    onPathChanged;
+    onResync;
+    isIgnored;
+    timer;
+    onError;
+    onStateChange;
+    restartBackoffFloorMs;
+    restartBackoffCeilingMs;
+    maxRestartAttempts;
+    watchFn;
+    watcher = null;
+    pending = new Map();
+    /** Per-key max-wait timers (AC-018l.16): armed once per burst, NOT reset per observation. */
+    maxWaitPending = new Map();
+    /** Per-key burst guard so the debounce timer and the max-wait cap fire the settle at most once. */
+    bursts = new Map();
+    state = "stopped";
+    restartAttempts = 0;
+    restartHandle = null;
+    /** Set by `stop()`; suppresses any restart scheduled by a since-superseded error. */
+    stopped = true;
+    constructor(opts) {
+        this.root = opts.root;
+        this.debounceMs = Math.max(0, opts.debounceMs ?? DEFAULT_DEBOUNCE_MS);
+        // The cap never sits below the debounce window (a cap shorter than the
+        // debounce would defeat the debounce entirely).
+        this.maxWaitMs = Math.max(this.debounceMs, opts.maxWaitMs ?? this.debounceMs * DEFAULT_MAX_WAIT_MULTIPLIER);
+        this.onPathChanged = opts.onPathChanged;
+        this.onResync = opts.onResync ?? (() => { });
+        this.isIgnored = opts.isIgnored ?? (() => false);
+        this.timer = opts.timer ?? realTimer;
+        this.onError = opts.onError ?? (() => { });
+        this.onStateChange = opts.onStateChange ?? (() => { });
+        this.restartBackoffFloorMs = Math.max(1, opts.restartBackoffFloorMs ?? DEFAULT_RESTART_BACKOFF_FLOOR_MS);
+        this.restartBackoffCeilingMs = Math.max(this.restartBackoffFloorMs, opts.restartBackoffCeilingMs ?? DEFAULT_RESTART_BACKOFF_CEILING_MS);
+        this.maxRestartAttempts = Math.max(1, opts.maxRestartAttempts ?? DEFAULT_MAX_RESTART_ATTEMPTS);
+        this.watchFn = opts.watchFn ?? watch;
+    }
+    /** The watcher's current liveness state (AC-018c.6/7). */
+    get watcherState() {
+        return this.state;
+    }
+    /**
+     * Route one raw `fs.watch` observation. A null/undefined filename (a
+     * directory-level event with no specific path on some platforms) requests a
+     * full resync; a concrete filename goes through the per-path debounce. Public
+     * so tests can drive both branches without a real filesystem.
+     */
+    observeRaw(filename) {
+        if (filename === null || filename === undefined) {
+            this.requestResync();
+            return;
+        }
+        this.observe(String(filename));
+    }
+    /**
+     * Feed a concrete path observation into the debouncer. Ignored paths are
+     * dropped before scheduling. Public so tests can drive it without a real
+     * filesystem; `start()` wires `fs.watch` through `observeRaw` to call this.
+     */
+    observe(relPath) {
+        if (relPath === "")
+            return;
+        const normalized = relPath.replace(/\\/g, "/");
+        // Containment first (CWE-22): an absolute path or a `..` traversal is dropped
+        // before it can be ignore-tested, scheduled, or ever reach a stat/read.
+        if (!isSafeRelPath(normalized))
+            return;
+        if (this.isIgnored(normalized))
+            return;
+        this.schedule(normalized, () => this.onPathChanged(normalized));
+    }
+    /**
+     * Request a debounced full-workspace resync settle (AC-3). Collapses a burst
+     * of null-filename events into a single `onResync` the same way a per-path
+     * burst collapses into one signal.
+     */
+    requestResync() {
+        this.schedule(RESYNC_KEY, () => this.onResync());
+    }
+    schedule(key, fire) {
+        // One guard per burst, shared by the debounce timer AND the max-wait cap so
+        // whichever elapses first fires the settle exactly once and the other becomes
+        // a no-op (even if a test timer fires both from one snapshot).
+        let burst = this.bursts.get(key);
+        if (burst === undefined) {
+            burst = { fired: false };
+            this.bursts.set(key, burst);
+        }
+        const guard = burst;
+        const fireOnce = () => {
+            if (guard.fired)
+                return;
+            guard.fired = true;
+            const debounceHandle = this.pending.get(key);
+            if (debounceHandle !== undefined) {
+                this.timer.clear(debounceHandle);
+                this.pending.delete(key);
+            }
+            const maxWaitHandle = this.maxWaitPending.get(key);
+            if (maxWaitHandle !== undefined) {
+                this.timer.clear(maxWaitHandle);
+                this.maxWaitPending.delete(key);
+            }
+            this.bursts.delete(key);
+            try {
+                fire();
+            }
+            catch (err) {
+                this.onError(err);
+            }
+        };
+        // (Re)arm the per-observation debounce timer.
+        const existing = this.pending.get(key);
+        if (existing !== undefined)
+            this.timer.clear(existing);
+        this.pending.set(key, this.timer.set(fireOnce, this.debounceMs));
+        // Arm the max-wait cap ONCE per burst (AC-018l.16): it is NOT reset by later
+        // observations, so a path written faster than the debounce still settles when
+        // the cap elapses. Only meaningful when the cap exceeds the debounce window.
+        if (this.maxWaitMs > this.debounceMs && !this.maxWaitPending.has(key)) {
+            this.maxWaitPending.set(key, this.timer.set(fireOnce, this.maxWaitMs));
+        }
+    }
+    /** Begin watching the root recursively. Idempotent. */
+    start() {
+        if (this.watcher !== null)
+            return;
+        this.stopped = false;
+        this.restartAttempts = 0;
+        if (this.restartHandle !== null) {
+            this.timer.clear(this.restartHandle);
+            this.restartHandle = null;
+        }
+        this.attach();
+    }
+    attach() {
+        this.watcher = this.watchFn(this.root, { recursive: true }, (_eventType, filename) => {
+            this.observeRaw(filename === null ? null : String(filename));
+        });
+        this.watcher.on("error", (err) => this.handleWatcherError(err));
+        this.setState("running");
+    }
+    /**
+     * PRD-018c NEC-009 / AC-018c.6/7: an `fs.watch` error means the underlying
+     * `FSWatcher` is typically dead. Close it, log via `onError` (preserving the
+     * pre-018c logging behavior), and - unless `stop()` already superseded this
+     * error - schedule a backoff-guarded restart rather than leaving live
+     * updates dead while `/health` still reports the daemon healthy.
+     */
+    handleWatcherError(err) {
+        this.onError(err);
+        if (this.watcher !== null) {
+            try {
+                this.watcher.close();
+            }
+            catch {
+                // already dead; nothing to clean up
+            }
+            this.watcher = null;
+        }
+        if (this.stopped)
+            return; // an owner-initiated stop() wins; never restart after that
+        this.scheduleRestart();
+    }
+    scheduleRestart() {
+        this.restartAttempts += 1;
+        if (this.restartAttempts > this.maxRestartAttempts) {
+            // AC-018c.7: repeated failures park the watcher degraded instead of
+            // looping hot. The periodic resync backstop (service.ts) is the
+            // remaining reconciliation path while degraded.
+            this.setState("degraded");
+            return;
+        }
+        this.setState("restarting");
+        const delay = Math.min(this.restartBackoffCeilingMs, Math.round(this.restartBackoffFloorMs * Math.pow(2, this.restartAttempts - 1)));
+        this.restartHandle = this.timer.set(() => {
+            this.restartHandle = null;
+            if (this.stopped)
+                return;
+            try {
+                this.attach();
+                this.restartAttempts = 0; // a successful re-attach resets the backoff
+                // AC-018c.6: reconcile the outage window through the SAME debounced
+                // resync path a null-filename observation already uses (AC-3).
+                this.requestResync();
+            }
+            catch (err) {
+                this.onError(err);
+                this.scheduleRestart(); // still failing; keep backing off
+            }
+        }, delay);
+    }
+    setState(next) {
+        if (this.state === next)
+            return;
+        this.state = next;
+        this.onStateChange(next);
+    }
+    /** Stop watching, cancel every pending debounce, and cancel any scheduled restart. Idempotent. */
+    stop() {
+        this.stopped = true;
+        for (const handle of this.pending.values())
+            this.timer.clear(handle);
+        this.pending.clear();
+        for (const handle of this.maxWaitPending.values())
+            this.timer.clear(handle);
+        this.maxWaitPending.clear();
+        this.bursts.clear();
+        if (this.restartHandle !== null) {
+            this.timer.clear(this.restartHandle);
+            this.restartHandle = null;
+        }
+        if (this.watcher !== null) {
+            this.watcher.close();
+            this.watcher = null;
+        }
+        this.setState("stopped");
+    }
+}
+//# sourceMappingURL=fs-watch.js.map

package/dist/registration/fs-watch.js.map

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

package/dist/registration/ignore.d.ts

@@ -0,0 +1,77 @@
+/** A predicate over a repo-relative (forward-slashed) path: true means "drop, never register". */
+export type IgnorePredicate = (relPath: string) => boolean;
+/** Path segments always dropped, independent of any ignore file. */
+export declare const ALWAYS_IGNORED_SEGMENTS: readonly string[];
+/** The per-repo ignore file the CodeGraph discovery convention uses (relative to the workspace root). */
+export declare const GRAPH_IGNORE_FILE = ".honeycomb/graph-ignore.json";
+/**
+ * Read the per-repo ignore file (a JSON array of prefixes, or `{ "ignore": [...] }`).
+ * Missing or malformed files yield an empty list (fail-open to the built-in
+ * segment rules); a hard read error other than "not found" is swallowed so the
+ * intake never crashes on a bad ignore file.
+ */
+export declare function loadIgnorePrefixes(root: string, readFile?: (p: string) => string | null): readonly string[];
+/**
+ * Build the default ignore predicate for a workspace root. Combines the built-in
+ * segment rules with any prefixes declared in the repo's `graph-ignore.json`.
+ * A path is ignored if it (a) contains an always-ignored segment, or (b) equals
+ * or sits under one of the declared ignore prefixes.
+ */
+export declare function createDefaultIgnore(root: string, readFile?: (p: string) => string | null): IgnorePredicate;
+/**
+ * The 3-way result NEC-039 requires: git may be genuinely absent (no `.git`,
+ * no `git` on PATH - degrading to the segment/graph-ignore-only predicate is
+ * correct and silent), or present but ERRORING (non-zero exit, `ENOBUFS` -
+ * this must never silently collapse the predicate), or a clean snapshot.
+ */
+export type GitLsFilesProbe = {
+    readonly status: "absent";
+} | {
+    readonly status: "error";
+    readonly reason: string;
+} | {
+    readonly status: "ok";
+    readonly paths: readonly string[];
+};
+export type GitLsFilesRunner = (root: string) => GitLsFilesProbe;
+/** The real `git ls-files` runner: spawns synchronously, never throws. */
+export declare const runGitLsFiles: GitLsFilesRunner;
+/** Per-path `git check-ignore` fallback for a snapshot cache miss. Returns null when it cannot be determined (git errored/absent). */
+export type GitCheckIgnoreRunner = (root: string, relPath: string) => boolean | null;
+export declare const runGitCheckIgnore: GitCheckIgnoreRunner;
+/** The composed shared predicate (PRD-018c AC-018c.1) plus its resync-refresh and observability seams. */
+export interface SharedIgnore {
+    /** segments ∪ graph-ignore ∪ gitignore semantics. The SAME function reference every consumer shares. */
+    readonly isIgnored: IgnorePredicate;
+    /** Refresh the cached gitignore snapshot (call once per resync, NEC-007 point 1). */
+    refresh(): void;
+    /** Whether git participates at all in this workspace right now (false => the predicate is segments+graph-ignore only). */
+    isGitAvailable(): boolean;
+    /** The reason the last refresh degraded (git present but errored), or null when healthy or git is absent. */
+    lastGitError(): string | null;
+}
+export interface SharedIgnoreOptions {
+    /** Read the per-repo ignore file (default: real disk read). */
+    readonly readFile?: (p: string) => string | null;
+    /** The git ls-files snapshot runner (default: {@link runGitLsFiles}). Injectable for tests. */
+    readonly gitLsFiles?: GitLsFilesRunner;
+    /** The git check-ignore per-path fallback runner (default: {@link runGitCheckIgnore}). Injectable for tests. */
+    readonly gitCheckIgnore?: GitCheckIgnoreRunner;
+    /**
+     * Called whenever a refresh finds git PRESENT but ERRORING (NEC-039): the
+     * last good snapshot (if any) is kept rather than silently discarded, and
+     * this hook lets the caller log or otherwise surface the degradation loudly.
+     * Defaults to a no-op.
+     */
+    readonly onGitError?: (reason: string) => void;
+}
+/**
+ * Build the ONE shared ignore predicate for a workspace (PRD-018c AC-018c.1):
+ * {@link createDefaultIgnore}'s segments+graph-ignore UNION gitignore
+ * semantics, approximated by a cached `git ls-files` snapshot with a
+ * per-path `git check-ignore` fallback for cache misses. Call {@link
+ * SharedIgnore.refresh} once per resync to keep the snapshot warm without
+ * spawning git on every watch event.
+ */
+export declare function createSharedIgnore(root: string, opts?: SharedIgnoreOptions): SharedIgnore;
+//# sourceMappingURL=ignore.d.ts.map

package/dist/registration/ignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignore.d.ts","sourceRoot":"","sources":["../../src/registration/ignore.ts"],"names":[],"mappings":"AAsCA,kGAAkG;AAClG,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;AAE3D,oEAAoE;AACpE,eAAO,MAAM,uBAAuB,EAAE,SAAS,MAAM,EAA2C,CAAC;AAEjG,yGAAyG;AACzG,eAAO,MAAM,iBAAiB,iCAAiC,CAAC;AAqBhE;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAsB,GACvD,SAAS,MAAM,EAAE,CAoBnB;AAWD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,EACZ,QAAQ,GAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAsB,GACvD,eAAe,CAWjB;AAUD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAA;CAAE,GAC7B;IAAE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrD;IAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,CAAC;AAEjE,MAAM,MAAM,gBAAgB,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,eAAe,CAAC;AAEjE,0EAA0E;AAC1E,eAAO,MAAM,aAAa,EAAE,gBA+B3B,CAAC;AAEF,sIAAsI;AACtI,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;AAErF,eAAO,MAAM,iBAAiB,EAAE,oBAY/B,CAAC;AAEF,0GAA0G;AAC1G,MAAM,WAAW,YAAY;IAC3B,wGAAwG;IACxG,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,qFAAqF;IACrF,OAAO,IAAI,IAAI,CAAC;IAChB,0HAA0H;IAC1H,cAAc,IAAI,OAAO,CAAC;IAC1B,6GAA6G;IAC7G,YAAY,IAAI,MAAM,GAAG,IAAI,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;IACjD,+FAA+F;IAC/F,QAAQ,CAAC,UAAU,CAAC,EAAE,gBAAgB,CAAC;IACvC,gHAAgH;IAChH,QAAQ,CAAC,cAAc,CAAC,EAAE,oBAAoB,CAAC;IAC/C;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAChD;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,YAAY,CA8D7F"}