agent-recall-core 3.4.31 → 3.4.36

package/dist/tools-logic/local-archive-backend.js

@@ -0,0 +1,124 @@
+// packages/core/src/tools-logic/local-archive-backend.ts
+//
+// LocalArchiveMemoryBackend — the reference MemoryBackend implementation.
+//
+// Purpose (two roles):
+//   1. TESTING: round-trip verification of the retain() contract without
+//      a live third-party service.
+//   2. ADAPTER TEMPLATE: fork this file to build a real backend adapter.
+//      Replace the JSON write with a client.retain() call; keep the
+//      scrub-upstream assumption and the RetainResult shape unchanged.
+//
+// Storage layout:
+//   <root>/exports/<backend-name>/YYYY-MM-DD.json
+//
+// Each daily file is an array of CorrectionExport objects. A second call on
+// the same day appends (unique by id — the seam is idempotent; a repeated
+// `ar corrections export --to-backend` run on the same set does not create
+// duplicate entries).
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getRoot } from "../types.js";
+/** Human-readable name surfaced in CLI output and log lines. */
+const BACKEND_NAME = "local-archive";
+/**
+ * Date string for today (YYYY-MM-DD) in the LOCAL timezone — injectable in
+ * tests via the fn arg.
+ *
+ * NOTE: uses local time, not UTC, so the archive file matches the operator's
+ * calendar day. toISOString() returns UTC and would produce the wrong date for
+ * operators running past midnight UTC in a positive-offset timezone.
+ */
+export function todayDateString() {
+    const d = new Date();
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
+/**
+ * LocalArchiveMemoryBackend — writes scrubbed CorrectionExport arrays to
+ * <root>/exports/local-archive/YYYY-MM-DD.json.
+ *
+ * CONTRACT:
+ *   - Assumes records are already scrubbed (exportCorrections() upstream).
+ *   - Idempotent: re-running with the same IDs does not duplicate entries.
+ *   - Never throws into session flow — errors map to rejected entries.
+ */
+export class LocalArchiveMemoryBackend {
+    /** Override in tests via the constructor to pin the date. */
+    _dateFn;
+    constructor(opts = {}) {
+        this._dateFn = opts.dateFn ?? todayDateString;
+    }
+    name() {
+        return BACKEND_NAME;
+    }
+    async available() {
+        // Always available — only needs a writable filesystem, same guarantee
+        // as the rest of the local store.
+        try {
+            const dir = this._archiveDir();
+            fs.mkdirSync(dir, { recursive: true });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async retain(records) {
+        const accepted = [];
+        const rejected = [];
+        if (records.length === 0) {
+            return { accepted, rejected };
+        }
+        try {
+            const dir = this._archiveDir();
+            fs.mkdirSync(dir, { recursive: true });
+            const file = path.join(dir, `${this._dateFn()}.json`);
+            // Load existing entries (idempotency — deduplicate by id).
+            let existing = [];
+            try {
+                if (fs.existsSync(file)) {
+                    const raw = fs.readFileSync(file, "utf-8");
+                    const parsed = JSON.parse(raw);
+                    if (Array.isArray(parsed)) {
+                        existing = parsed;
+                    }
+                }
+            }
+            catch {
+                // Malformed file — start fresh. A corrupt archive must not block new writes.
+                existing = [];
+            }
+            const existingIds = new Set(existing.map((e) => e.id));
+            const toWrite = [...existing];
+            for (const record of records) {
+                if (existingIds.has(record.id)) {
+                    // Already present — idempotent accept (not a rejection).
+                    accepted.push(record.id);
+                    continue;
+                }
+                toWrite.push(record);
+                existingIds.add(record.id);
+                accepted.push(record.id);
+            }
+            fs.writeFileSync(file, JSON.stringify(toWrite, null, 2), "utf-8");
+        }
+        catch (err) {
+            // A filesystem failure rejects ALL records in this batch.
+            const reason = `write failed: ${String(err)}`;
+            for (const r of records) {
+                if (!accepted.includes(r.id)) {
+                    rejected.push({ id: r.id, reason });
+                }
+            }
+        }
+        return { accepted, rejected };
+    }
+    /** Absolute path of the archive directory for this backend. */
+    _archiveDir() {
+        return path.join(getRoot(), "exports", BACKEND_NAME);
+    }
+}
+//# sourceMappingURL=local-archive-backend.js.map

package/dist/tools-logic/local-archive-backend.js.map

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

package/dist/tools-logic/memory-backend.d.ts

@@ -0,0 +1,74 @@
+import type { CorrectionExport } from "./export-corrections.js";
+/**
+ * RetainResult — structured response from a backend's retain() call.
+ * Mirrors the Hindsight `retain()` response shape so the local-archive
+ * reference backend and any third-party adapter speak the same dialect.
+ */
+export interface RetainResult {
+    /** IDs successfully written to the backend. */
+    accepted: string[];
+    /** IDs the backend refused, each with a machine-readable reason. */
+    rejected: {
+        id: string;
+        reason: string;
+    }[];
+}
+/**
+ * MemoryBackend — write seam for external belief stores.
+ *
+ * CONTRACT:
+ *   - retain() receives a CorrectionExport[] that has ALREADY been scrubbed by
+ *     exportCorrections(). The backend may assume every string field is clean.
+ *     Backends MUST NOT re-implement the scrub — that is a recipe for drift.
+ *   - records MUST come from exportCorrections(); the type system cannot
+ *     enforce this — which is exactly why the core barrel deliberately does
+ *     NOT export concrete backends (only this interface + the factory). The
+ *     sole supported path to a backend instance is getMemoryBackend(), and the
+ *     sole supported record source is exportCorrections().
+ *   - available() must never throw. Return false if the backend is misconfigured.
+ *   - name() returns a stable human-readable label for logging.
+ *   - Backend failure must be surfaced as a rejected entry or a thrown error that
+ *     the CLI catches and prints as a warning — never as a process crash.
+ */
+export interface MemoryBackend {
+    retain(records: CorrectionExport[]): Promise<RetainResult>;
+    available(): Promise<boolean>;
+    name(): string;
+}
+/**
+ * DisabledMemoryBackend — returned when AR_MEMORY_BACKEND is unset.
+ * available() is false so callers can gate on it cleanly.
+ */
+export declare class DisabledMemoryBackend implements MemoryBackend {
+    name(): string;
+    available(): Promise<boolean>;
+    retain(_records: CorrectionExport[]): Promise<RetainResult>;
+}
+/**
+ * Get the configured MemoryBackend.
+ *
+ * Selection order:
+ *   1. AR_MEMORY_BACKEND=local-archive → LocalArchiveMemoryBackend (built-in)
+ *   2. AR_MEMORY_BACKEND=<module>      → dynamic import of that module
+ *   3. (unset | "none" | "disabled")  → DisabledMemoryBackend
+ *
+ * Case handling: built-in keywords (none/disabled/local-archive) match
+ * case-insensitively — pure operator convenience, nothing is imported.
+ * A third-party module specifier is used VERBATIM (npm names are
+ * case-sensitive on registry lookup and lowercase-only for new packages);
+ * uppercase input is rejected by SAFE_MODULE_RE with a clear message rather
+ * than silently normalized to a different package name.
+ *
+ * Dynamic import contract: the module must export a default class satisfying
+ * MemoryBackend. If the import fails, the specifier is invalid, a Node builtin,
+ * or the backend reports unavailable, the factory logs a warning to stderr and
+ * falls back to DisabledMemoryBackend — it NEVER crashes the session flow.
+ *
+ * @agent_instruction Returns DisabledMemoryBackend when no backend is configured.
+ *   Check (await backend.available()) before calling retain(). If false, surface
+ *   a clear "no backend configured" error to the operator.
+ */
+export declare function getMemoryBackend(): Promise<MemoryBackend>;
+/** Reset the cached backend instance (for testing). */
+export declare function resetMemoryBackend(): void;
+//# sourceMappingURL=memory-backend.d.ts.map

package/dist/tools-logic/memory-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-backend.d.ts","sourceRoot":"","sources":["../../src/tools-logic/memory-backend.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAMhE;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,oEAAoE;IACpE,QAAQ,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC5C;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAC3D,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9B,IAAI,IAAI,MAAM,CAAC;CAChB;AAMD;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,aAAa;IACzD,IAAI,IAAI,MAAM;IAIR,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAI7B,MAAM,CAAC,QAAQ,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC,YAAY,CAAC;CASlE;AAmCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,gBAAgB,IAAI,OAAO,CAAC,aAAa,CAAC,CA+E/D;AAED,uDAAuD;AACvD,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}

package/dist/tools-logic/memory-backend.js

@@ -0,0 +1,172 @@
+// packages/core/src/tools-logic/memory-backend.ts
+//
+// MemoryBackend — symmetric WRITE seam for the RecallBackend READ abstraction.
+//
+// Design contract:
+//   - Records are ALWAYS the scrubbed CorrectionExport projection. The seam
+//     consumes exportCorrections() output (which runs fail-closed scrubForExport
+//     on every free-text field). Raw CorrectionRecord is NEVER passed through —
+//     the scrub guarantee is upstream by construction. Assert: callers must call
+//     exportCorrections() first; they MUST NOT build CorrectionExport manually
+//     and bypass the scrub.
+//   - Backend failure is a warning, not a session error. The seam is an explicit
+//     invocation path (ar corrections export --to-backend) — it never runs
+//     automatically on session_end in this version.
+//   - Zero-cloud default: the factory returns a DisabledMemoryBackend unless
+//     AR_MEMORY_BACKEND is set. No env var = no egress, unchanged.
+//
+// Environment selection (mirrors getRecallBackend()):
+//   AR_MEMORY_BACKEND=local-archive  → LocalArchiveMemoryBackend (reference)
+//   AR_MEMORY_BACKEND=<npm-module>   → dynamic import of third-party adapter
+//   (unset / "none" / "disabled")    → DisabledMemoryBackend
+//
+// Third-party adapters (e.g. a future hindsight-adapter package) must export a
+// default class that satisfies MemoryBackend via dynamic import.
+import { builtinModules } from "node:module";
+// ---------------------------------------------------------------------------
+// Disabled (default / zero-cloud) backend
+// ---------------------------------------------------------------------------
+/**
+ * DisabledMemoryBackend — returned when AR_MEMORY_BACKEND is unset.
+ * available() is false so callers can gate on it cleanly.
+ */
+export class DisabledMemoryBackend {
+    name() {
+        return "disabled";
+    }
+    async available() {
+        return false;
+    }
+    async retain(_records) {
+        return {
+            accepted: [],
+            rejected: _records.map((r) => ({
+                id: r.id,
+                reason: "no backend configured (AR_MEMORY_BACKEND not set)",
+            })),
+        };
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/** Cached backend instance. Reset via resetMemoryBackend() in tests. */
+let _cachedBackend = null;
+/**
+ * Allowlist for third-party module specifiers: bare npm package names only.
+ *   - unscoped: [a-z0-9][a-z0-9._-]*
+ *   - scoped:   @[a-z0-9][a-z0-9._-]* / [a-z0-9][a-z0-9._-]*
+ * LOWERCASE ONLY — npm forbids uppercase in new package names, and we do NOT
+ * case-normalize the value before import: silently lowercasing "MyAdapter" to
+ * "myadapter" would import a DIFFERENT package than the operator named (a
+ * squat-redirect hazard). Uppercase input is rejected with a clear message.
+ * No path separators, no "..", no leading dots — a crafted value cannot reach
+ * import() as a file path.
+ */
+const SAFE_MODULE_RE = /^(@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)$/;
+/**
+ * Denylist: Node builtin modules must never be import()ed as backends.
+ * They would fail the Ctor typecheck anyway (fail-safe), but the gate rejects
+ * them up front with a clear message instead of a confusing typecheck error.
+ * Explicit floor list + runtime builtinModules union for completeness across
+ * Node versions.
+ */
+const BUILTIN_DENYLIST = new Set([
+    "fs", "path", "os", "http", "https", "child_process", "net",
+    "crypto", "module", "process", "vm", "worker_threads",
+    ...(Array.isArray(builtinModules) ? builtinModules : []),
+]);
+/**
+ * Get the configured MemoryBackend.
+ *
+ * Selection order:
+ *   1. AR_MEMORY_BACKEND=local-archive → LocalArchiveMemoryBackend (built-in)
+ *   2. AR_MEMORY_BACKEND=<module>      → dynamic import of that module
+ *   3. (unset | "none" | "disabled")  → DisabledMemoryBackend
+ *
+ * Case handling: built-in keywords (none/disabled/local-archive) match
+ * case-insensitively — pure operator convenience, nothing is imported.
+ * A third-party module specifier is used VERBATIM (npm names are
+ * case-sensitive on registry lookup and lowercase-only for new packages);
+ * uppercase input is rejected by SAFE_MODULE_RE with a clear message rather
+ * than silently normalized to a different package name.
+ *
+ * Dynamic import contract: the module must export a default class satisfying
+ * MemoryBackend. If the import fails, the specifier is invalid, a Node builtin,
+ * or the backend reports unavailable, the factory logs a warning to stderr and
+ * falls back to DisabledMemoryBackend — it NEVER crashes the session flow.
+ *
+ * @agent_instruction Returns DisabledMemoryBackend when no backend is configured.
+ *   Check (await backend.available()) before calling retain(). If false, surface
+ *   a clear "no backend configured" error to the operator.
+ */
+export async function getMemoryBackend() {
+    if (_cachedBackend)
+        return _cachedBackend;
+    const rawSpec = (process.env.AR_MEMORY_BACKEND ?? "").trim();
+    // Keywords only — the verbatim rawSpec is what reaches import() below.
+    const keyword = rawSpec.toLowerCase();
+    if (!keyword || keyword === "none" || keyword === "disabled") {
+        _cachedBackend = new DisabledMemoryBackend();
+        return _cachedBackend;
+    }
+    if (keyword === "local-archive") {
+        try {
+            const mod = await import("./local-archive-backend.js");
+            _cachedBackend = new mod.LocalArchiveMemoryBackend();
+            return _cachedBackend;
+        }
+        catch (err) {
+            process.stderr.write(`[agent-recall] memory-backend: failed to load local-archive backend: ${String(err)}\n`);
+            _cachedBackend = new DisabledMemoryBackend();
+            return _cachedBackend;
+        }
+    }
+    // Third-party module path — dynamic import.
+    // SECURITY: AR_MEMORY_BACKEND is operator-controlled env input; treat as
+    // untrusted. Gate 1: allowlist shape (bare/scoped npm package name, verbatim).
+    if (!SAFE_MODULE_RE.test(rawSpec)) {
+        process.stderr.write(`[agent-recall] memory-backend: AR_MEMORY_BACKEND="${rawSpec}" is not a valid npm package name — ` +
+            `only lowercase bare package names (e.g. "ar-mem0-adapter") or scoped packages (@org/pkg) are accepted. ` +
+            `Path specifiers and uppercase are not allowed. Falling back to disabled.\n`);
+        _cachedBackend = new DisabledMemoryBackend();
+        return _cachedBackend;
+    }
+    // Gate 2: Node builtins are never valid backends — reject before import().
+    if (BUILTIN_DENYLIST.has(rawSpec) || rawSpec.startsWith("node:")) {
+        process.stderr.write(`[agent-recall] memory-backend: AR_MEMORY_BACKEND="${rawSpec}" is a Node builtin module, ` +
+            `not a memory backend — refusing to load it. Falling back to disabled.\n`);
+        _cachedBackend = new DisabledMemoryBackend();
+        return _cachedBackend;
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const mod = await import(rawSpec);
+        // The module must export a default class or a named MemoryBackend class.
+        const Ctor = mod.default ?? mod.MemoryBackend;
+        if (typeof Ctor !== "function") {
+            throw new TypeError(`module "${rawSpec}" does not export a default class or MemoryBackend — got ${typeof Ctor}`);
+        }
+        const backend = new Ctor();
+        if (!(await backend.available())) {
+            // Contract: a loaded-but-unavailable backend falls back to Disabled.
+            // Caching and returning the unavailable instance would silently swallow
+            // all rejections for any caller that skips the available() check.
+            process.stderr.write(`[agent-recall] memory-backend: "${rawSpec}" loaded but reported unavailable — falling back to disabled\n`);
+            _cachedBackend = new DisabledMemoryBackend();
+            return _cachedBackend;
+        }
+        _cachedBackend = backend;
+        return backend;
+    }
+    catch (err) {
+        process.stderr.write(`[agent-recall] memory-backend: failed to load "${rawSpec}": ${String(err)} — falling back to disabled\n`);
+        _cachedBackend = new DisabledMemoryBackend();
+        return _cachedBackend;
+    }
+}
+/** Reset the cached backend instance (for testing). */
+export function resetMemoryBackend() {
+    _cachedBackend = null;
+}
+//# sourceMappingURL=memory-backend.js.map

package/dist/tools-logic/memory-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-backend.js","sourceRoot":"","sources":["../../src/tools-logic/memory-backend.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,EAAE;AACF,+EAA+E;AAC/E,EAAE;AACF,mBAAmB;AACnB,4EAA4E;AAC5E,iFAAiF;AACjF,gFAAgF;AAChF,iFAAiF;AACjF,+EAA+E;AAC/E,4BAA4B;AAC5B,iFAAiF;AACjF,2EAA2E;AAC3E,oDAAoD;AACpD,6EAA6E;AAC7E,mEAAmE;AACnE,EAAE;AACF,sDAAsD;AACtD,6EAA6E;AAC7E,6EAA6E;AAC7E,6DAA6D;AAC7D,EAAE;AACF,+EAA+E;AAC/E,iEAAiE;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AA0C7C,8EAA8E;AAC9E,0CAA0C;AAC1C,8EAA8E;AAE9E;;;GAGG;AACH,MAAM,OAAO,qBAAqB;IAChC,IAAI;QACF,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,SAAS;QACb,OAAO,KAAK,CAAC;IACf,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,QAA4B;QACvC,OAAO;YACL,QAAQ,EAAE,EAAE;YACZ,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC7B,EAAE,EAAE,CAAC,CAAC,EAAE;gBACR,MAAM,EAAE,mDAAmD;aAC5D,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC;CACF;AAED,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E,wEAAwE;AACxE,IAAI,cAAc,GAAyB,IAAI,CAAC;AAEhD;;;;;;;;;;GAUG;AACH,MAAM,cAAc,GAAG,sEAAsE,CAAC;AAE9F;;;;;;GAMG;AACH,MAAM,gBAAgB,GAAwB,IAAI,GAAG,CAAC;IACpD,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,KAAK;IAC3D,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,EAAE,gBAAgB;IACrD,GAAG,CAAC,KAAK,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,CAAC;CACzD,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB;IACpC,IAAI,cAAc;QAAE,OAAO,cAAc,CAAC;IAE1C,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7D,uEAAuE;IACvE,MAAM,OAAO,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAEtC,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,MAAM,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC7D,cAAc,GAAG,IAAI,qBAAqB,EAAE,CAAC;QAC7C,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,IAAI,OAAO,KAAK,eAAe,EAAE,CAAC;QAChC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,4BAA4B,CAAC,CAAC;YACvD,cAAc,GAAG,IAAI,GAAG,CAAC,yBAAyB,EAAE,CAAC;YACrD,OAAO,cAAc,CAAC;QACxB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,wEAAwE,MAAM,CAAC,GAAG,CAAC,IAAI,CACxF,CAAC;YACF,cAAc,GAAG,IAAI,qBAAqB,EAAE,CAAC;YAC7C,OAAO,cAAc,CAAC;QACxB,CAAC;IACH,CAAC;IAED,4CAA4C;IAC5C,yEAAyE;IACzE,+EAA+E;IAC/E,IAAI,CAAC,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,qDAAqD,OAAO,sCAAsC;YAClG,yGAAyG;YACzG,4EAA4E,CAC7E,CAAC;QACF,cAAc,GAAG,IAAI,qBAAqB,EAAE,CAAC;QAC7C,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,2EAA2E;IAC3E,IAAI,gBAAgB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QACjE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,qDAAqD,OAAO,8BAA8B;YAC1F,yEAAyE,CAC1E,CAAC;QACF,cAAc,GAAG,IAAI,qBAAqB,EAAE,CAAC;QAC7C,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,IAAI,CAAC;QACH,8DAA8D;QAC9D,MAAM,GAAG,GAAG,MAAM,MAAM,CAAC,OAAO,CAAQ,CAAC;QACzC,yEAAyE;QACzE,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,aAAa,CAAC;QAC9C,IAAI,OAAO,IAAI,KAAK,UAAU,EAAE,CAAC;YAC/B,MAAM,IAAI,SAAS,CACjB,WAAW,OAAO,4DAA4D,OAAO,IAAI,EAAE,CAC5F,CAAC;QACJ,CAAC;QACD,MAAM,OAAO,GAAG,IAAI,IAAI,EAAmB,CAAC;QAC5C,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC;YACjC,qEAAqE;YACrE,wEAAwE;YACxE,kEAAkE;YAClE,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mCAAmC,OAAO,gEAAgE,CAC3G,CAAC;YACF,cAAc,GAAG,IAAI,qBAAqB,EAAE,CAAC;YAC7C,OAAO,cAAc,CAAC;QACxB,CAAC;QACD,cAAc,GAAG,OAAO,CAAC;QACzB,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,kDAAkD,OAAO,MAAM,MAAM,CAAC,GAAG,CAAC,+BAA+B,CAC1G,CAAC;QACF,cAAc,GAAG,IAAI,qBAAqB,EAAE,CAAC;QAC7C,OAAO,cAAc,CAAC;IACxB,CAAC;AACH,CAAC;AAED,uDAAuD;AACvD,MAAM,UAAU,kBAAkB;IAChC,cAAc,GAAG,IAAI,CAAC;AACxB,CAAC"}

package/dist/tools-logic/memory-query.d.ts

@@ -4,9 +4,13 @@
  * Unlike `recall` (general search), this is called mid-task:
  *   "I'm about to do X — what should I know?"
  *
- * Only returns high/medium confidence results. Designed for pull-on-demand
- * retrieval rather than push-on-start injection.
+ * Returns high/medium confidence results as the primary list. When the primary
+ * filter is empty (the match exists but is only low-confidence), the BRIDGE
+ * (Wave 4) attaches the verbatim drill-down source under `fallback` instead of
+ * silently suppressing it — so the agent gets the lossless source plus a
+ * "verify before relying" caution rather than a bare "nothing found" string.
  */
+import { type BridgedSource } from "./smart-recall.js";
 export interface MemoryQueryInput {
     /** Describe what you're about to do or decide. e.g. "push to npm" or "modify auth middleware" */
     intent: string;
@@ -28,9 +32,12 @@ export interface MemoryQueryResult {
     intent: string;
     project: string;
     results: MemoryQueryItem[];
-    /** True when no memory is relevant to this intent at the given confidence threshold. */
+    /** True when no memory passed the confidence threshold for the primary list. */
     empty: boolean;
     guidance?: string;
+    /** Verbatim drill-down source attached when the primary filter was empty but a
+     *  low-confidence match exists (Wave 4 bridge). */
+    fallback?: BridgedSource[];
 }
 export declare function memoryQuery(input: MemoryQueryInput): Promise<MemoryQueryResult>;
 //# sourceMappingURL=memory-query.d.ts.map

package/dist/tools-logic/memory-query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-query.d.ts","sourceRoot":"","sources":["../../src/tools-logic/memory-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AASH,MAAM,WAAW,gBAAgB;IAC/B,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC3C,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,wFAAwF;IACxF,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAgBD,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAgCrF"}
+{"version":3,"file":"memory-query.d.ts","sourceRoot":"","sources":["../../src/tools-logic/memory-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAe,KAAK,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAOpE,MAAM,WAAW,gBAAgB;IAC/B,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,cAAc,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;IAC3C,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,gFAAgF;IAChF,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;uDACmD;IACnD,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;CAC5B;AAgBD,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAuDrF"}

package/dist/tools-logic/memory-query.js

@@ -4,8 +4,11 @@
  * Unlike `recall` (general search), this is called mid-task:
  *   "I'm about to do X — what should I know?"
  *
- * Only returns high/medium confidence results. Designed for pull-on-demand
- * retrieval rather than push-on-start injection.
+ * Returns high/medium confidence results as the primary list. When the primary
+ * filter is empty (the match exists but is only low-confidence), the BRIDGE
+ * (Wave 4) attaches the verbatim drill-down source under `fallback` instead of
+ * silently suppressing it — so the agent gets the lossless source plus a
+ * "verify before relying" caution rather than a bare "nothing found" string.
  */
 import { smartRecall } from "./smart-recall.js";
 import { resolveProject } from "../storage/project.js";
@@ -28,6 +31,7 @@ export async function memoryQuery(input) {
         query: input.intent,
         project,
         limit: limit * 2, // over-fetch then filter by confidence
+        drilldown: true, // bridge: attach verbatim source for low-confidence hits
     });
     const filtered = recalled.results
         .filter((r) => r.score >= minScore)
@@ -40,14 +44,34 @@ export async function memoryQuery(input) {
         confidence: r.confidence,
         room: r.room,
     }));
+    if (filtered.length > 0) {
+        return {
+            intent: input.intent,
+            project,
+            results: filtered,
+            empty: false,
+        };
+    }
+    // Primary filter empty — fall back to the bridged verbatim source if the
+    // model tier had a low-confidence match worth drilling into.
+    const fallback = recalled.bridged;
+    if (fallback && fallback.length > 0) {
+        return {
+            intent: input.intent,
+            project,
+            results: [],
+            empty: true,
+            fallback,
+            guidance: `Low-confidence match — verbatim source attached; verify before relying.`,
+        };
+    }
     return {
         intent: input.intent,
         project,
-        results: filtered,
-        empty: filtered.length === 0,
-        guidance: filtered.length === 0
-            ? `No memory found relevant to: "${input.intent}". This may be a new area — proceed with standard caution.`
-            : undefined,
+        results: [],
+        empty: true,
+        fallback: [],
+        guidance: `No memory found relevant to: "${input.intent}". This may be a new area — proceed with standard caution.`,
     };
 }
 //# sourceMappingURL=memory-query.js.map

package/dist/tools-logic/memory-query.js.map

@@ -1 +1 @@
-{"version":3,"file":"memory-query.js","sourceRoot":"","sources":["../../src/tools-logic/memory-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAkCvD,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,MAAM,oBAAoB,GAA2B;IACnD,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,IAAI;CACV,CAAC;AAEF,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAuB;IACvD,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,cAAc,IAAI,QAAQ,CAAC,IAAI,IAAI,CAAC;IAChF,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;IAE/B,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC;QACjC,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,OAAO;QACP,KAAK,EAAE,KAAK,GAAG,CAAC,EAAG,uCAAuC;KAC3D,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO;SAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC;SAClC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,IAAI,EAAE,CAAC,CAAC,IAAI;KACb,CAAC,CAAC,CAAC;IAEN,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO;QACP,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC;QAC5B,QAAQ,EAAE,QAAQ,CAAC,MAAM,KAAK,CAAC;YAC7B,CAAC,CAAC,iCAAiC,KAAK,CAAC,MAAM,4DAA4D;YAC3G,CAAC,CAAC,SAAS;KACd,CAAC;AACJ,CAAC"}
+{"version":3,"file":"memory-query.js","sourceRoot":"","sources":["../../src/tools-logic/memory-query.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAsB,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAqCvD,8EAA8E;AAC9E,uCAAuC;AACvC,8EAA8E;AAE9E,MAAM,oBAAoB,GAA2B;IACnD,IAAI,EAAE,IAAI;IACV,MAAM,EAAE,IAAI;IACZ,GAAG,EAAE,IAAI;CACV,CAAC;AAEF,8EAA8E;AAC9E,OAAO;AACP,8EAA8E;AAE9E,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,KAAuB;IACvD,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACpD,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,cAAc,IAAI,QAAQ,CAAC,IAAI,IAAI,CAAC;IAChF,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,CAAC,CAAC;IAE/B,MAAM,QAAQ,GAAG,MAAM,WAAW,CAAC;QACjC,KAAK,EAAE,KAAK,CAAC,MAAM;QACnB,OAAO;QACP,KAAK,EAAE,KAAK,GAAG,CAAC,EAAG,uCAAuC;QAC1D,SAAS,EAAE,IAAI,EAAI,yDAAyD;KAC7E,CAAC,CAAC;IAEH,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO;SAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC;SAClC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;SACf,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACX,EAAE,EAAE,CAAC,CAAC,EAAE;QACR,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,IAAI,EAAE,CAAC,CAAC,IAAI;KACb,CAAC,CAAC,CAAC;IAEN,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO;YACP,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,6DAA6D;IAC7D,MAAM,QAAQ,GAAG,QAAQ,CAAC,OAAO,CAAC;IAClC,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO;YACL,MAAM,EAAE,KAAK,CAAC,MAAM;YACpB,OAAO;YACP,OAAO,EAAE,EAAE;YACX,KAAK,EAAE,IAAI;YACX,QAAQ;YACR,QAAQ,EAAE,yEAAyE;SACpF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO;QACP,OAAO,EAAE,EAAE;QACX,KAAK,EAAE,IAAI;QACX,QAAQ,EAAE,EAAE;QACZ,QAAQ,EAAE,iCAAiC,KAAK,CAAC,MAAM,4DAA4D;KACpH,CAAC;AACJ,CAAC"}

package/dist/tools-logic/mirror-builder.d.ts

@@ -0,0 +1,115 @@
+/**
+ * mirror.ts — "The Mirror" (Loop 9): a VISIBLE, CORRECTABLE self-model.
+ *
+ * For nine loops the system has accumulated a one-sided, HIDDEN model of the
+ * user (corrections, blind-spots, awareness insights). Loop 3 proved that model
+ * is weak at PREDICTION (0/13 keyword recall on a strict LOO). The Mirror flips
+ * the hidden model into a first-person reflection the human can READ and CORRECT:
+ *
+ *   "You've corrected me 8 times about X."
+ *   "I've noticed you tend to …" (with the corrections it's derived from)
+ *
+ * Each correction-OF-the-mirror is itself a high-value correction — the human
+ * pointing at the line and saying "no, that's not why" is exactly the signal the
+ * predict-the-correction loop needs.
+ *
+ * HARD RULES (enforced here and asserted in test/mirror.test.mjs):
+ *  1. NEVER fabricate a trait. Every rendered observation traces to ≥1 real
+ *     stored record — its `cites` array is non-empty and lists real ids.
+ *  2. Carry an explicit fallibility caveat on every reflection (Loop 3: this
+ *     model is NOT yet predictive — "what I've noticed", not "what's true").
+ *  3. Personal-tier, LOCAL-ONLY. Reads the same personal/ + awareness artifacts
+ *     the rest of Wave 5 reads. No network, no LLM, fully deterministic.
+ *
+ * Pure assembly: this module reads stored data via injected readers (so tests
+ * can feed a known store) and renders. It performs NO IO of its own beyond the
+ * default readers, which are the existing disk-backed functions.
+ */
+import { type CorrectionRecord } from "../storage/corrections.js";
+import { type BlindSpotProfile } from "../helpers/blind-spots.js";
+import { type AwarenessState } from "../palace/awareness.js";
+/**
+ * One first-person observation in the mirror. `text` is the rendered line;
+ * `cites` lists the REAL stored record ids it was derived from — NEVER empty
+ * for a real line (the no-fabrication invariant). `kind` tags the source tier.
+ */
+export interface MirrorObservation {
+    /** First-person line, e.g. "You've corrected me 8 times about: …". */
+    text: string;
+    /** Source tier this observation was assembled from. */
+    kind: "correction" | "tendency" | "insight" | "cross_project";
+    /** Real stored ids this line is grounded in (≥1; the anti-fabrication anchor). */
+    cites: string[];
+    /** Evidence weight — how many records back this line (for ordering / display). */
+    evidence_count: number;
+}
+export interface MirrorReflection {
+    /** ISO timestamp the reflection was assembled. */
+    generated_at: string;
+    /** Project this mirror reflects, or "_global" when assembled cross-project. */
+    project: string;
+    /** First-person observations, strongest-evidence first. Empty ⇒ empty mirror. */
+    observations: MirrorObservation[];
+    /**
+     * The fallibility caveat (Loop 3). ALWAYS present, even on an empty mirror —
+     * the mirror is "what I've noticed", explicitly NOT "what's true about you",
+     * and explicitly NOT yet predictive.
+     */
+    caveat: string;
+    /** True when there is no stored data to reflect — render an honest empty mirror. */
+    empty: boolean;
+    /** Headcount of the underlying corpus this was built from (for the header). */
+    basis: {
+        corrections: number;
+        tendencies: number;
+        insights: number;
+        cross_project_projects: number;
+    };
+}
+/** Injectable readers so tests can feed a known store; defaults read real disk. */
+export interface MirrorReaders {
+    corrections: (project: string) => CorrectionRecord[];
+    blindSpots: (project: string) => BlindSpotProfile | null;
+    awareness: () => AwarenessState | null;
+    /** Returns [slug, corrections] for every project (cross-project pass). */
+    allProjectCorrections: () => Array<{
+        slug: string;
+        corrections: CorrectionRecord[];
+    }>;
+}
+/**
+ * Assemble the mirror for a project (or "_global" when project is omitted).
+ *
+ * DETERMINISTIC: given the same stored data the output is byte-identical except
+ * `generated_at`. Ordering is fully specified (evidence desc, then severity,
+ * then a stable text tiebreak) so there is no Set/Map iteration nondeterminism.
+ *
+ * @param project — project slug; when omitted, assembles a cross-project mirror
+ *   keyed "_global" that also surfaces patterns recurring across ≥2 projects.
+ * @param readers — injectable for tests; defaults to the real disk-backed store.
+ */
+export declare function buildMirror(project?: string, readers?: Partial<MirrorReaders>): MirrorReflection;
+export interface CrossProjectPattern {
+    /** Representative topic (cleaned rule of the strongest member). */
+    topic: string;
+    /** Distinct project slugs the pattern spans (≥2). */
+    projects: string[];
+    /** Real correction ids backing the pattern. */
+    cites: string[];
+}
+/**
+ * Find correction clusters that recur across ≥2 projects. We tokenize each
+ * correction, greedily cluster by ≥2 shared content tokens, and keep clusters
+ * whose members span ≥2 distinct projects. Deterministic: corrections are
+ * pre-sorted by (date, id) before clustering.
+ */
+export declare function deriveCrossProjectPatterns(perProject: Array<{
+    slug: string;
+    corrections: CorrectionRecord[];
+}>): {
+    patterns: CrossProjectPattern[];
+    projectCount: number;
+};
+/** Render a reflection as first-person human-readable text (for `ar mirror`). */
+export declare function renderMirror(m: MirrorReflection): string;
+//# sourceMappingURL=mirror-builder.d.ts.map

package/dist/tools-logic/mirror-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror-builder.d.ts","sourceRoot":"","sources":["../../src/tools-logic/mirror-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EACtB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAoC,KAAK,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AACpG,OAAO,EAAsB,KAAK,cAAc,EAAgB,MAAM,wBAAwB,CAAC;AAQ/F;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,IAAI,EAAE,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,eAAe,CAAC;IAC9D,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kFAAkF;IAClF,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,kDAAkD;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,+EAA+E;IAC/E,OAAO,EAAE,MAAM,CAAC;IAChB,iFAAiF;IACjF,YAAY,EAAE,iBAAiB,EAAE,CAAC;IAClC;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,KAAK,EAAE,OAAO,CAAC;IACf,+EAA+E;IAC/E,KAAK,EAAE;QACL,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,sBAAsB,EAAE,MAAM,CAAC;KAChC,CAAC;CACH;AAED,mFAAmF;AACnF,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,gBAAgB,EAAE,CAAC;IACrD,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,gBAAgB,GAAG,IAAI,CAAC;IACzD,SAAS,EAAE,MAAM,cAAc,GAAG,IAAI,CAAC;IACvC,0EAA0E;IAC1E,qBAAqB,EAAE,MAAM,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,gBAAgB,EAAE,CAAA;KAAE,CAAC,CAAC;CACvF;AAuDD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,gBAAgB,CAqIhG;AAiDD,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,+CAA+C;IAC/C,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAC,GACnE;IAAE,QAAQ,EAAE,mBAAmB,EAAE,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CAmD3D;AAMD,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,CAAC,EAAE,gBAAgB,GAAG,MAAM,CA6BxD"}