@tokenfactory/acc-runner 0.44.0 → 0.44.2

package/dist/memory-context.js

@@ -0,0 +1,220 @@
+/**
+ * MEMORY-2 (Curation) — operational memory injection on the TASK/RUNNER path.
+ *
+ * MEMORY-1 established the read half of the loop here: `renderTaskPrompt` built
+ * a prompt from the task row alone, so an agent started every run with no
+ * recollection of what earlier runs had learned, and this module closed that.
+ * Its four founding properties are UNCHANGED and every one of them is still
+ * enforced below:
+ *
+ *   • OPERATIONAL ONLY. `p_data_class` is the module constant {@link OPERATIONAL}
+ *     at the single RPC call site, and {@link selectOperationalMemories} drops
+ *     any row that comes back with another class anyway. docs/acc/
+ *     AGENT_MEMORY_PRIVACY.md attaches GDPR export/erasure duties to
+ *     `personal_data` and `sensitive`; neither may ever reach a prompt from
+ *     here, and no argument to any function below could put one there.
+ *   • BOUNDED. See the budget section.
+ *   • NO-OP ON EMPTY. No rows, no agent id, nothing relevant, or any error at
+ *     all ⇒ the empty string, and the prompt is byte-identical to what it was
+ *     before. An unavailable memory store must never fail a task.
+ *   • LABELLED. The section says what it is and where it came from, so the
+ *     agent treats it as prior belief rather than as instruction.
+ *
+ * ── WHAT MEMORY-2 CHANGES ──────────────────────────────────────────────────
+ *
+ * MEMORY-1's own docblock named its two compromises, and this is the phase that
+ * pays them off.
+ *
+ * RANKING. "Most relevant" used to mean the RPC's own `is_pinned desc,
+ * created_at desc`, because the only other signal `acc.read_agent_memory`
+ * offers is a substring ILIKE. It now means the weighted score in
+ * ./memory-curation.ts — pinned ≫ recency-decay > confidence > read/merge
+ * signal — computed against an INJECTED clock, over a candidate window
+ * ({@link MAX_MEMORY_CANDIDATES}) wider than the injection itself, with
+ * near-identical rows collapsed. Still no embeddings: `p_query` stays the RPC's
+ * ILIKE parameter and nothing here computes or stores a vector.
+ *
+ * BUDGET. The bound was a row count plus a character cap. It is now a TOKEN
+ * budget ({@link MAX_INJECTED_TOKENS}) — the unit the thing being bounded is
+ * actually denominated in — with the row count and the character cap retained
+ * underneath as belt-and-braces ceilings.
+ *
+ * RELEVANCE GATE. Injection used to be unconditional: whatever the agent's five
+ * most recent notes happened to be, they went into every prompt. A memory now
+ * has to share a topical term with the task (or be PINNED, which is an operator
+ * saying "this applies regardless") to be injected at all. When nothing
+ * qualifies, the section is empty and the prompt is untouched — a task about the
+ * webhook no longer carries five notes about the visual-regression suite.
+ *
+ * When the caller supplies NO task text, the gate is inert and every memory is
+ * relevant. That is deliberate: a gate that emptied the injection whenever it
+ * had nothing to match against would be a regression wearing a feature's name.
+ */
+import { dropNearDuplicates, estimateTokens, isRelevantMemory, rankMemories, relevanceTerms, } from "./memory-curation.js";
+/** The ONLY `acc.memory_data_class` value this module will read. */
+export const OPERATIONAL = "operational";
+/** Hard ceiling on injected rows. */
+export const MAX_INJECTED_MEMORIES = 5;
+/**
+ * How many rows to ASK the RPC for. Wider than the injection because ranking,
+ * dedup and the relevance gate all run after the fetch: gating a 5-row window
+ * would usually leave 0-1 rows, which reads as "memory does nothing".
+ */
+export const MAX_MEMORY_CANDIDATES = 30;
+/** Longest single memory rendered; longer bodies are cut with an ellipsis. */
+export const MAX_MEMORY_CHARS = 400;
+/** Longest whole section, in characters. The secondary ceiling under the budget. */
+export const MAX_SECTION_CHARS = 2_000;
+/**
+ * The PRIMARY bound: estimated tokens of the rendered section, heading and
+ * preamble included. A prompt budget is denominated in tokens, so this is what
+ * the cap has to be expressed in; ~500 tokens is a few percent of a task prompt.
+ */
+export const MAX_INJECTED_TOKENS = 500;
+/** The heading the section is emitted under — the label the agent reads. */
+export const MEMORY_SECTION_HEADING = "## Prior operational memory (from earlier runs)";
+function intOr0(v) {
+    const n = Number(v);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+/**
+ * Keep only genuinely operational rows, rank them, collapse near-identical
+ * ones, and bound the count.
+ *
+ * Pure. Re-applies the class filter the RPC argument already made because this
+ * is the last gate before a row reaches a model's context: if the definer RPC
+ * ever changes under us, the failure mode must be "nothing is injected", never
+ * "a sensitive row is".
+ *
+ * `nowMs` is a parameter and never `Date.now()` read inline — the ranking is a
+ * pure function of (rows, clock), which is what makes it testable without a
+ * fixture that expires (the SWEEP-FIX-1 lesson).
+ */
+export function selectOperationalMemories(rows, limit = MAX_INJECTED_MEMORIES, nowMs = Date.now()) {
+    const list = Array.isArray(rows) ? rows : [];
+    const kept = [];
+    for (const raw of list) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const rec = raw;
+        if (rec.data_class !== OPERATIONAL)
+            continue;
+        const content = typeof rec.content === "string" ? rec.content.trim() : "";
+        if (content.length === 0)
+            continue;
+        kept.push({
+            id: typeof rec.id === "string" ? rec.id : "",
+            data_class: OPERATIONAL,
+            content,
+            is_pinned: rec.is_pinned === true,
+            created_at: typeof rec.created_at === "string" ? rec.created_at : "",
+            updated_at: typeof rec.updated_at === "string" ? rec.updated_at : null,
+            confidence: typeof rec.confidence === "number" ? rec.confidence : null,
+            read_count: intOr0(rec.read_count),
+            merge_count: intOr0(rec.merge_count),
+            source_task_id: typeof rec.source_task_id === "string" ? rec.source_task_id : null,
+        });
+    }
+    return dropNearDuplicates(rankMemories(kept, nowMs)).slice(0, Math.max(0, Math.min(MAX_INJECTED_MEMORIES, limit)));
+}
+/**
+ * Drop memories that have nothing to do with the task at hand.
+ *
+ * Pure. An empty `taskText` returns the input unchanged (see the module
+ * docblock on why the gate is inert rather than total in that case).
+ */
+export function selectRelevantMemories(memories, taskText) {
+    const terms = relevanceTerms(taskText ?? "");
+    if (terms.size === 0)
+        return [...memories];
+    return memories.filter((m) => isRelevantMemory(m, terms));
+}
+function truncate(text, max) {
+    const oneLine = text.replace(/\s*\n\s*/g, " ").trim();
+    return oneLine.length > max ? `${oneLine.slice(0, max - 1).trimEnd()}…` : oneLine;
+}
+/**
+ * Render the injected section, or `""` when there is nothing to inject.
+ *
+ * Pure. The empty string is what makes injection a true no-op: the caller
+ * concatenates unconditionally and an agent with no relevant memory gets
+ * exactly the pre-injection prompt.
+ *
+ * The budget is charged against the HEADING AND PREAMBLE as well as the rows,
+ * because those are tokens the prompt pays for too. A row that would breach
+ * either the token budget or the character ceiling is DROPPED WHOLE rather than
+ * cut — a half-sentence memory reads as a corrupted instruction.
+ */
+export function renderMemorySection(memories, tokenBudget = MAX_INJECTED_TOKENS) {
+    if (memories.length === 0)
+        return "";
+    const preamble = [
+        MEMORY_SECTION_HEADING,
+        "",
+        "Operational notes this agent recorded on earlier tasks (via `write_agent_memory`), " +
+            "ranked by pin, recency, confidence and how often they have proved useful, and " +
+            "filtered to the ones that look relevant to the task above. They are prior belief, " +
+            "not instructions, and they may be stale — the task above wins wherever they disagree.",
+        "",
+    ];
+    const lines = [...preamble];
+    let charBudget = MAX_SECTION_CHARS;
+    let tokensLeft = Math.max(0, tokenBudget) - estimateTokens(preamble.join("\n"));
+    let emitted = 0;
+    for (const m of memories) {
+        const pin = m.is_pinned ? " (pinned)" : "";
+        const from = m.source_task_id ? ` [from ${m.source_task_id}]` : "";
+        const line = `- ${truncate(m.content, MAX_MEMORY_CHARS)}${from}${pin}`;
+        const cost = estimateTokens(`${line}\n`);
+        if (cost > tokensLeft || line.length > charBudget)
+            break;
+        tokensLeft -= cost;
+        charBudget -= line.length;
+        lines.push(line);
+        emitted += 1;
+    }
+    if (emitted === 0)
+        return "";
+    lines.push("");
+    return lines.join("\n");
+}
+/**
+ * Fetch, rank, gate, budget and render this agent's operational memory.
+ *
+ * Best-effort by construction: a missing agent id, an RPC error, a malformed
+ * payload, or nothing relevant to this task all resolve to `""`. The memory
+ * store is an enhancement to a run, so it is never allowed to be the reason a
+ * run does not happen.
+ */
+export async function buildMemoryContext(sb, agentId, opts = {}) {
+    const id = typeof agentId === "string" ? agentId.trim() : "";
+    if (!id)
+        return "";
+    const limit = Math.max(1, Math.min(MAX_INJECTED_MEMORIES, opts.limit ?? MAX_INJECTED_MEMORIES));
+    const nowMs = opts.nowMs ?? Date.now();
+    try {
+        const { data, error } = (await sb.rpc("read_agent_memory", {
+            p_agent_id: id,
+            // Still no substring filter at the RPC: a task title is not a substring
+            // of a memory body, so ILIKE-ing on it would FILTER almost everything out
+            // rather than rank it. The relevance gate below does the topical work, in
+            // TypeScript, over whole tokens.
+            p_query: null,
+            // The pin. A literal, never a parameter — this module cannot be asked
+            // for any other class.
+            p_data_class: OPERATIONAL,
+            p_pinned_only: false,
+            p_limit: MAX_MEMORY_CANDIDATES,
+            p_offset: 0,
+        }));
+        if (error)
+            return "";
+        const ranked = selectOperationalMemories(data, MAX_INJECTED_MEMORIES, nowMs);
+        const relevant = selectRelevantMemories(ranked, opts.taskText).slice(0, limit);
+        return renderMemorySection(relevant, opts.tokenBudget ?? MAX_INJECTED_TOKENS);
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=memory-context.js.map

package/dist/memory-context.js.map

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

package/dist/memory-curation.d.ts

@@ -0,0 +1,172 @@
+/**
+ * MEMORY-2 (Curation) — the pure ranking / dedup / budget primitives for
+ * operational agent memory.
+ *
+ * ── THIS FILE IS THE MIRROR ────────────────────────────────────────────────
+ * The canonical copy is api/_lib/memory-curation.ts. This one exists because
+ * the runner is published to npm and builds with `include: ["src/**"]`, so it
+ * cannot import out of `api/_lib`. Keep the two byte-compatible: any change
+ * here must land in the canonical copy too, and
+ * tests/unit/memory2-agent-memory-curation.test.ts imports BOTH and fails if
+ * they disagree on any exported constant or on any fixture.
+ *
+ * MEMORY-1 shipped the loop (write tool, read tool, prompt injection) but no
+ * curation: `acc.record_agent_memory` is a plain INSERT, so an agent that
+ * learns the same thing on ten tasks writes ten near-identical rows; and both
+ * read paths took the RPC's own `is_pinned desc, created_at desc` order, which
+ * knows nothing about how confident the agent was or how often the note has
+ * actually proved useful. This module is the arithmetic that fixes both halves.
+ * It is deliberately ALL PURE — no client, no clock, no I/O — because every
+ * caller needs to test it against a fixed clock (the SWEEP-FIX-1 lesson: a
+ * suite that reads the real `Date.now()` is a time bomb, not a test).
+ *
+ * ── MIRRORED, ON PURPOSE ───────────────────────────────────────────────────
+ *
+ * `packages/acc-runner/src/memory-curation.ts` is a verbatim mirror of this
+ * file. The runner is published to npm as `@tokenfactory/acc-runner` and builds
+ * from `packages/acc-runner/tsconfig.build.json` with `include: ["src/**"]`, so
+ * it CANNOT import out of `api/_lib` — the same constraint that already makes
+ * `api/_lib/alerts-git-auth.ts` a documented mirror of
+ * `packages/acc-runner/src/git-auth`. The drift guard is a real test, not a
+ * comment: tests/unit/memory2-agent-memory-curation.test.ts imports BOTH copies
+ * and asserts every exported constant and every function output agrees over a
+ * shared fixture corpus. Change one, change the other, or that test fails.
+ *
+ * A THIRD copy of the normalisation lives in SQL
+ * (`acc._normalize_memory_content` / `acc._memory_similarity`, migration 0335),
+ * because the write-time dedup has to happen inside the RPC that does the merge.
+ * That is why {@link normalizeMemoryContent} uses the ASCII class `[^a-z0-9]+`
+ * rather than a Unicode property escape: `[:alnum:]` in Postgres is
+ * collation-dependent, and for a dedup KEY, "the two sides disagree on this
+ * input" means "sometimes merges, sometimes duplicates". The documented cost is
+ * that a body with no ASCII alphanumerics normalises to `""`, which every caller
+ * treats as NOT COMPARABLE (never as a match).
+ *
+ * Nothing here reads or writes a `data_class`. Class enforcement is the pin at
+ * the RPC call sites in api/_lib/agent-memory-tools.ts and the row filters in
+ * that module and in the runner's memory-context.ts; a scoring function that
+ * could not see the class also cannot widen it.
+ */
+/**
+ * The canonical dedup normalisation: lowercase, every run of non-`[a-z0-9]`
+ * collapsed to a single space, trimmed. Mirror of SQL
+ * `acc._normalize_memory_content` (0335 §1).
+ */
+export declare function normalizeMemoryContent(text: unknown): string;
+/** The DISTINCT normalized tokens of a body. Empty for an uncomparable body. */
+export declare function memoryTokenSet(text: unknown): Set<string>;
+/**
+ * Dice coefficient over the distinct normalized token sets: `2|A∩B| / (|A|+|B|)`.
+ * Mirror of SQL `acc._memory_similarity` (0335 §2).
+ *
+ * Returns 0 when either side has no tokens — the "not comparable" rule. 0 can
+ * never clear a threshold, so an unnormalisable body is never a duplicate.
+ */
+export declare function memorySimilarity(a: unknown, b: unknown): number;
+/** The Dice threshold at which two operational memories count as the same one. */
+export declare const NEAR_DUPLICATE_SIMILARITY = 0.9;
+/**
+ * Are these two bodies the SAME memory?
+ *
+ * Exact normalized equality first — that is the overwhelmingly common duplicate
+ * (the same note re-emitted with different capitalisation or punctuation) and it
+ * is the case SQL can answer from `content_hash` alone. Then the Dice gate.
+ */
+export declare function isNearDuplicate(a: unknown, b: unknown, threshold?: number): boolean;
+/**
+ * The signals a memory carries into the ranking. Every field but `content` is
+ * optional and nullable, because a row read back through a definer RPC may be
+ * missing any of them (and rows written before 0335 have no `updated_at` or
+ * `merge_count` at all).
+ */
+export interface CurationSignals {
+    content: string;
+    is_pinned?: boolean | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+    confidence?: number | null;
+    read_count?: number | null;
+    merge_count?: number | null;
+}
+/** Half-life of the recency term, in days. */
+export declare const RECENCY_HALF_LIFE_DAYS = 14;
+/**
+ * Component weights. They are SEPARATED BY AN ORDER OF MAGNITUDE on purpose,
+ * which is what makes one weighted sum express the priority the task asks for
+ * — pinned, then recency, then confidence, then the read/merge signal. Each
+ * component is normalised into [0,1] first, so `W_PINNED` (1000) exceeds the
+ * largest possible sum of the other three (111): a pinned memory is ALWAYS
+ * ranked above an unpinned one, never merely usually.
+ */
+export declare const W_PINNED = 1000;
+export declare const W_RECENCY = 100;
+export declare const W_CONFIDENCE = 10;
+export declare const W_READ = 1;
+/** Read+merge count at which the usefulness signal is considered saturated. */
+export declare const READ_SIGNAL_SATURATION = 20;
+/**
+ * When this memory was last ASSERTED: `updated_at` when a merge refreshed it,
+ * else `created_at`. `0` for a row with no parseable timestamp, which scores as
+ * maximally stale rather than as "now".
+ */
+export declare function memoryTimestampMs(m: CurationSignals): number;
+/** Exponential recency decay in (0,1]. `nowMs` is always injected — never read. */
+export declare function recencyDecay(m: CurationSignals, nowMs: number): number;
+/** Log-saturating usefulness signal in [0,1] over `read_count + merge_count`. */
+export declare function readSignal(m: CurationSignals): number;
+/** The weighted relevance score. Higher ranks first. */
+export declare function memoryScore(m: CurationSignals, nowMs: number): number;
+/**
+ * Rank a batch, highest score first.
+ *
+ * The tie-breaks are the point of the `sort` comparator, not an afterthought:
+ * newest-first, then content order. Without them, two memories whose recency
+ * terms have both decayed to ~0 would compare equal and the resulting order
+ * would depend on `nowMs` and on input order — exactly the drift that makes a
+ * suite pass in August and fail in September. With them the order is TOTAL and
+ * the ranking is a pure function of the rows plus the injected clock.
+ */
+export declare function rankMemories<T extends CurationSignals>(rows: readonly T[], nowMs: number): T[];
+/**
+ * Collapse near-identical hits, keeping the FIRST occurrence of each cluster.
+ *
+ * Call it on an already-ranked list: "first" then means "the highest-scoring
+ * member of the cluster survives". Read-time dedup is needed even with
+ * write-time dedup in place, because rows written before 0335, rows written by
+ * the Memory tab, and rows belonging to two different agents in an org fan-out
+ * were never routed through the merging RPC.
+ *
+ * O(n²) against the KEPT list only, and every caller bounds n at <= 50.
+ */
+export declare function dropNearDuplicates<T extends CurationSignals>(ranked: readonly T[], threshold?: number): T[];
+/** Characters per token for the budget estimate. */
+export declare const CHARS_PER_TOKEN = 4;
+/**
+ * Estimated tokens in a string.
+ *
+ * A deliberate over-approximation of a real tokeniser: the runner must not ship
+ * a tokenizer dependency, and a budget that guesses HIGH spends less of the
+ * prompt than it promised, which is the safe direction to be wrong in.
+ */
+export declare function estimateTokens(text: string): number;
+/** Shortest token that can carry topical signal in the relevance gate. */
+export declare const RELEVANCE_MIN_TERM_CHARS = 4;
+/**
+ * The topical terms of a task (or a query): normalized tokens of at least
+ * {@link RELEVANCE_MIN_TERM_CHARS} characters that are not stopwords.
+ *
+ * An empty set means "no task context supplied", and every caller treats that
+ * as "everything is relevant" rather than as "nothing is" — a gate that
+ * silently emptied the injection whenever the caller had no query would be a
+ * regression dressed as a feature.
+ */
+export declare function relevanceTerms(text: unknown): Set<string>;
+/**
+ * Is this memory relevant to the current task?
+ *
+ * Pinned memories are ALWAYS relevant: an operator pinned the row precisely to
+ * say "this applies regardless of what the agent happens to be doing", and the
+ * gate must not override that.
+ */
+export declare function isRelevantMemory(m: CurationSignals, terms: ReadonlySet<string>): boolean;
+//# sourceMappingURL=memory-curation.d.ts.map

package/dist/memory-curation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-curation.d.ts","sourceRoot":"","sources":["../src/memory-curation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAMH;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAG5D;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAIzD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,MAAM,CAO/D;AAED,kFAAkF;AAClF,eAAO,MAAM,yBAAyB,MAAM,CAAC;AAE7C;;;;;;GAMG;AACH,wBAAgB,eAAe,CAC7B,CAAC,EAAE,OAAO,EACV,CAAC,EAAE,OAAO,EACV,SAAS,GAAE,MAAkC,GAC5C,OAAO,CAMT;AAMD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAED,8CAA8C;AAC9C,eAAO,MAAM,sBAAsB,KAAK,CAAC;AACzC;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,OAAQ,CAAC;AAC9B,eAAO,MAAM,SAAS,MAAM,CAAC;AAC7B,eAAO,MAAM,YAAY,KAAK,CAAC;AAC/B,eAAO,MAAM,MAAM,IAAI,CAAC;AACxB,+EAA+E;AAC/E,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAUzC;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAO5D;AAED,mFAAmF;AACnF,wBAAgB,YAAY,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAKtE;AAED,iFAAiF;AACjF,wBAAgB,UAAU,CAAC,CAAC,EAAE,eAAe,GAAG,MAAM,CAOrD;AAED,wDAAwD;AACxD,wBAAgB,WAAW,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOrE;AAED;;;;;;;;;GASG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,eAAe,EAAE,IAAI,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,EAAE,CAQ9F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,eAAe,EAC1D,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,SAAS,GAAE,MAAkC,GAC5C,CAAC,EAAE,CAOL;AAMD,oDAAoD;AACpD,eAAO,MAAM,eAAe,IAAI,CAAC;AAEjC;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED,0EAA0E;AAC1E,eAAO,MAAM,wBAAwB,IAAI,CAAC;AAgB1C;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAQzD;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,eAAe,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO,CAKxF"}