agentfootprint 8.19.0 → 8.20.0

package/dist/esm/recorders/observability/embeddingSummary.js

@@ -0,0 +1,114 @@
+/**
+ * embeddingSummary — what a recording keeps of a vector: its shape, not its
+ * bytes.
+ *
+ * Pattern: pure copy-on-write projection, in the `storedPreview` family —
+ *          "summarise structured values rather than serialize them", applied
+ *          to the one field measured to dominate a recording's size.
+ * Role:    recorders/observability layer. Applied at the RECORDING boundary
+ *          (BoundaryRecorder payload capture, `recordRun` freeze), never to
+ *          live run state — stages and stores keep their real vectors.
+ * Emits:   N/A.
+ *
+ * ── The measurement this exists for ─────────────────────────────────────────
+ * A single retrieval turn's recording measured 2.76 MB in a production RAG
+ * deployment — about 1.1 MB of it embedding floats, because the memory-read
+ * subflow's boundary output carries every retrieved entry, and every entry
+ * carries its full vector (1,024 floats serializing at ~19 bytes each). No
+ * consumer of a recording reads those floats: retrieval debugging needs the
+ * score, the passage, the document and the rejected candidates — all of which
+ * live in the retrieval evidence and none of which this touches. The vector's
+ * only recording-worthy facts are that it existed, its dimensionality, and a
+ * checksum-grade magnitude. That is exactly what `{ dims, norm }` keeps.
+ *
+ * The walk is copy-on-write: a value with no embeddings anywhere is returned
+ * BY REFERENCE, so the common payload costs one traversal and zero
+ * allocation. It never mutates its input — recordings share structure with
+ * live run state, and live state is borrowed, not owned.
+ *
+ * Two spellings are recognised, because the memory layer writes both:
+ *   - `embedding: number[]`     — a `MemoryEntry`'s vector (read side);
+ *   - `embeddings: number[][]`  — the write pipeline's per-message batch.
+ *
+ * Idempotent by construction: a summary is not a numeric array, so a value
+ * that has already been summarised passes through unchanged.
+ */
+/** Round to 4 decimals — a checksum, not an operand. */
+function l2norm(vector) {
+    let sum = 0;
+    for (const v of vector)
+        sum += v * v;
+    return Math.round(Math.sqrt(sum) * 1e4) / 1e4;
+}
+function isNumericVector(value) {
+    return Array.isArray(value) && value.length > 0 && value.every((v) => typeof v === 'number');
+}
+/** Summarise one vector. Exported for consumers that render recordings. */
+export function summarizeVector(vector) {
+    return { dims: vector.length, norm: l2norm(vector) };
+}
+/**
+ * Replace every `embedding` / `embeddings` field in a JSON-ish value with its
+ * `{ dims, norm }` summary. Copy-on-write: returns the SAME reference when
+ * nothing needed replacing; otherwise a structurally-shared copy. Never
+ * mutates the input.
+ *
+ * Shared nodes stay shared: a snapshot holds the same entry object at several
+ * paths (live state, stage writes, commit history), so results are memoized
+ * per input object — every path gets the SAME summarized copy, not one copy
+ * and one raw leak. Cycle-safe: an object seen again while still being walked
+ * resolves to its original reference (a cyclic value could not be serialized
+ * anyway).
+ */
+export function summarizeEmbeddings(value) {
+    return walk(value, new WeakMap());
+}
+function walk(value, memo) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (memo.has(value))
+        return memo.get(value);
+    // Placeholder for cycles: a back-edge met mid-walk resolves to the original.
+    memo.set(value, value);
+    if (Array.isArray(value)) {
+        let copy;
+        for (let i = 0; i < value.length; i++) {
+            const walked = walk(value[i], memo);
+            if (walked !== value[i]) {
+                copy ??= [...value];
+                copy[i] = walked;
+            }
+        }
+        const result = copy ?? value;
+        memo.set(value, result);
+        return result;
+    }
+    // Walk plain objects only. Class instances, Dates, Maps and the like are
+    // opaque values here — the recording layer stores POJOs, and reaching into
+    // somebody's live object to rewrite a field is what "never mutate" forbids.
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return value;
+    const record = value;
+    let copy;
+    for (const [key, field] of Object.entries(record)) {
+        let replacement = field;
+        if (key === 'embedding' && isNumericVector(field)) {
+            replacement = summarizeVector(field);
+        }
+        else if (key === 'embeddings' && Array.isArray(field) && field.some(isNumericVector)) {
+            replacement = field.map((v) => (isNumericVector(v) ? summarizeVector(v) : walk(v, memo)));
+        }
+        else {
+            replacement = walk(field, memo);
+        }
+        if (replacement !== field) {
+            copy ??= { ...record };
+            copy[key] = replacement;
+        }
+    }
+    const result = copy ?? value;
+    memo.set(value, result);
+    return result;
+}
+//# sourceMappingURL=embeddingSummary.js.map

package/dist/esm/recorders/observability/embeddingSummary.js.map

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

package/dist/esm/recorders/observability/recordRun.d.ts

@@ -94,6 +94,22 @@ export interface RecordRunOptions {
      *     consumer reading the bundle's `meta.mode` can say so.
      */
     readonly boundaryDetail?: 'full' | 'lean';
+    /**
+     * Keep raw embedding vectors in the recording (8.20.0). Default `false`:
+     * every `embedding` / `embeddings` field — in boundary payloads, in the
+     * snapshot's subflow results, in tool results riding the event stream —
+     * is replaced with its `{ dims, norm }` summary when the recording is
+     * frozen.
+     *
+     * Field measurement behind the default: one retrieval turn's recording
+     * weighed 2.76 MB, ~1.1 MB of it embedding floats, because the
+     * memory-read subflow's boundary output carries each retrieved entry's
+     * full vector. Nothing that renders a recording reads those floats; the
+     * retrieval evidence a debugger needs (score, passage, document,
+     * rejected candidates) carries no vectors and is untouched. Set `true`
+     * only when a consumer genuinely replays raw vectors offline.
+     */
+    readonly recordEmbeddings?: boolean;
 }
 /** A recording in progress. Keep it until the run ends, then freeze it. */
 export interface RunRecorder {

package/dist/esm/recorders/observability/recordRun.js

@@ -58,6 +58,7 @@
  */
 import { DEFAULT_MAX_EVENTS, eventTail } from '../../events/eventTail.js';
 import { boundaryRecorder } from './BoundaryRecorder.js';
+import { summarizeEmbeddings } from './embeddingSummary.js';
 /**
  * Start recording a runner. Call BEFORE `run()` — a recording is
  * collected as the run happens and cannot be reconstructed after it.
@@ -90,9 +91,11 @@ export function recordRun(runner, options = {}) {
     //    to call this instead of wiring it yourself. `getCommitCount` reads
     //    through the runner on every boundary, so it reports the count at
     //    that moment rather than a number captured now (when it is 0).
+    const keepEmbeddings = options.recordEmbeddings ?? false;
     const boundary = boundaryRecorder({
         getCommitCount: () => runner.getCommitCount(),
         ...(options.boundaryDetail === 'lean' ? { snapshot: 'lean' } : {}),
+        ...(keepEmbeddings ? { recordEmbeddings: true } : {}),
     });
     const offAttach = runner.attach(boundary);
     const offTyped = boundary.subscribe(runner);
@@ -100,9 +103,20 @@ export function recordRun(runner, options = {}) {
     return {
         toRecording: () => ({
             // Read at freeze time. Before the run there is no snapshot; during
-            // one it grows; after it, it is the finished run's.
-            snapshot: runner.getLastSnapshot(),
-            events: tail.snapshot().events,
+            // one it grows; after it, it is the finished run's. Unless
+            // `recordEmbeddings` asked for them, raw vectors are summarised to
+            // `{ dims, norm }` here — the snapshot's subflow results carry every
+            // retrieved entry's full vector otherwise, which is what made a
+            // single retrieval turn's recording weigh 2.76 MB in the field. The
+            // summarisation is copy-on-write: parts of the snapshot without
+            // embeddings are the runner's own objects, held by reference, as
+            // before — serialize to detach.
+            snapshot: keepEmbeddings
+                ? runner.getLastSnapshot()
+                : summarizeEmbeddings(runner.getLastSnapshot()),
+            events: keepEmbeddings
+                ? tail.snapshot().events
+                : summarizeEmbeddings(tail.snapshot().events),
             // The one piece a run does not leave behind — it lives on the
             // chart, which is built once and never changes.
             structure: runner.getSpec().buildTimeStructure,

package/dist/esm/recorders/observability/recordRun.js.map

@@ -1 +1 @@
-{"version":3,"file":"recordRun.js","sourceRoot":"","sources":["../../../../src/recorders/observability/recordRun.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAKH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAyB,MAAM,uBAAuB,CAAC;AAqEhF;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,UAA4B,EAAE;IACtE,oEAAoE;IACpE,sEAAsE;IACtE,qEAAqE;IACrE,+DAA+D;IAC/D,sEAAsE;IACtE,iDAAiD;IACjD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC,CAAC;IAChE,MAAM,SAAS,GAAgB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAA0B,EAAE,EAAE;QAC3E,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;IAEH,uEAAuE;IACvE,wEAAwE;IACxE,sEAAsE;IACtE,mEAAmE;IACnE,MAAM,QAAQ,GAAG,gBAAgB,CAAC;QAChC,cAAc,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,EAAE;QAC7C,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5E,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAE5C,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACL,WAAW,EAAE,GAAc,EAAE,CAAC,CAAC;YAC7B,mEAAmE;YACnE,oDAAoD;YACpD,QAAQ,EAAE,MAAM,CAAC,eAAe,EAAE;YAClC,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM;YAC9B,8DAA8D;YAC9D,gDAAgD;YAChD,SAAS,EAAG,MAAM,CAAC,OAAO,EAAuC,CAAC,kBAAkB;SACrF,CAAC;QACF,QAAQ;QACR,IAAI,UAAU;YACZ,OAAO,IAAI,CAAC,KAAK,CAAC;QACpB,CAAC;QACD,IAAI,aAAa;YACf,OAAO,IAAI,CAAC,OAAO,CAAC;QACtB,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACT,mEAAmE;YACnE,mEAAmE;YACnE,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,SAAS,EAAE,CAAC;YACZ,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"recordRun.js","sourceRoot":"","sources":["../../../../src/recorders/observability/recordRun.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyDG;AAKH,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAyB,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAqF5D;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,SAAS,CAAC,MAAc,EAAE,UAA4B,EAAE;IACtE,oEAAoE;IACpE,sEAAsE;IACtE,qEAAqE;IACrE,+DAA+D;IAC/D,sEAAsE;IACtE,iDAAiD;IACjD,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,SAAS,IAAI,kBAAkB,CAAC,CAAC;IAChE,MAAM,SAAS,GAAgB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,KAA0B,EAAE,EAAE;QAC3E,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC,CAAC,CAAC;IAEH,uEAAuE;IACvE,wEAAwE;IACxE,sEAAsE;IACtE,mEAAmE;IACnE,MAAM,cAAc,GAAG,OAAO,CAAC,gBAAgB,IAAI,KAAK,CAAC;IACzD,MAAM,QAAQ,GAAG,gBAAgB,CAAC;QAChC,cAAc,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,cAAc,EAAE;QAC7C,GAAG,CAAC,OAAO,CAAC,cAAc,KAAK,MAAM,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC3E,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,gBAAgB,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACtD,CAAC,CAAC;IACH,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAE5C,IAAI,OAAO,GAAG,KAAK,CAAC;IAEpB,OAAO;QACL,WAAW,EAAE,GAAc,EAAE,CAAC,CAAC;YAC7B,mEAAmE;YACnE,2DAA2D;YAC3D,mEAAmE;YACnE,qEAAqE;YACrE,gEAAgE;YAChE,oEAAoE;YACpE,gEAAgE;YAChE,iEAAiE;YACjE,gCAAgC;YAChC,QAAQ,EAAE,cAAc;gBACtB,CAAC,CAAC,MAAM,CAAC,eAAe,EAAE;gBAC1B,CAAC,CAAC,mBAAmB,CAAC,MAAM,CAAC,eAAe,EAAE,CAAC;YACjD,MAAM,EAAE,cAAc;gBACpB,CAAC,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM;gBACxB,CAAC,CAAE,mBAAmB,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAoC;YACnF,8DAA8D;YAC9D,gDAAgD;YAChD,SAAS,EAAG,MAAM,CAAC,OAAO,EAAuC,CAAC,kBAAkB;SACrF,CAAC;QACF,QAAQ;QACR,IAAI,UAAU;YACZ,OAAO,IAAI,CAAC,KAAK,CAAC;QACpB,CAAC;QACD,IAAI,aAAa;YACf,OAAO,IAAI,CAAC,OAAO,CAAC;QACtB,CAAC;QACD,IAAI,EAAE,GAAG,EAAE;YACT,mEAAmE;YACnE,mEAAmE;YACnE,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,SAAS,EAAE,CAAC;YACZ,QAAQ,EAAE,CAAC;YACX,SAAS,EAAE,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/lib/rag/defineRAG.js.map

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

package/dist/memory/retrieval/topK.js.map

@@ -1 +1 @@
-{"version":3,"file":"topK.js","sourceRoot":"","sources":["../../../src/memory/retrieval/topK.ts"],"names":[],"mappings":";;;AAqDA;;;;;;;;;;;;;;GAcG;AACH,SAAgB,IAAI,CAAC,UAAuB,EAAE;IAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,qDAAqD,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,oEAAoE,MAAM,CACxE,OAAO,CAAC,YAAY,CACrB,GAAG,CACL,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IACpF,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,kEAAkE,MAAM,CACtE,OAAO,CAAC,SAAS,CAClB,GAAG,CACL,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,CAAC;QACD,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,YAAY;QACZ,MAAM,CAAC,IAAgC;YACrC,MAAM,QAAQ,GAAuB,EAAE,CAAC;YACxC,IAAI,QAAQ,GAAG,CAAC,CAAC;YACjB,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;gBAC7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,GAAG,SAAS,EAAE,CAAC;oBAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;oBAC9D,SAAS;gBACX,CAAC;gBACD,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;oBAClB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;oBAC/D,SAAS;gBACX,CAAC;gBACD,QAAQ,IAAI,CAAC,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC;AA7CD,oBA6CC"}
+{"version":3,"file":"topK.js","sourceRoot":"","sources":["../../../src/memory/retrieval/topK.ts"],"names":[],"mappings":";;;AA2DA;;;;;;;;;;;;;;GAcG;AACH,SAAgB,IAAI,CAAC,UAAuB,EAAE;IAC5C,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,qDAAqD,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7F,CAAC;IACD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QACxD,MAAM,IAAI,KAAK,CACb,oEAAoE,MAAM,CACxE,OAAO,CAAC,YAAY,CACrB,GAAG,CACL,CAAC;IACJ,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,IAAI,GAAG,CAAC;IACpF,IAAI,SAAS,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CACb,kEAAkE,MAAM,CACtE,OAAO,CAAC,SAAS,CAClB,GAAG,CACL,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,CAAC;QACD,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,YAAY;QACZ,MAAM,CAAC,IAAgC;YACrC,MAAM,QAAQ,GAAuB,EAAE,CAAC;YACxC,IAAI,QAAQ,GAAG,CAAC,CAAC;YACjB,KAAK,MAAM,SAAS,IAAI,IAAI,EAAE,CAAC;gBAC7B,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,GAAG,SAAS,EAAE,CAAC;oBAC3D,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,CAAC,CAAC;oBAC9D,SAAS;gBACX,CAAC;gBACD,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;oBAClB,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,kBAAkB,EAAE,CAAC,CAAC;oBAC/D,SAAS;gBACX,CAAC;gBACD,QAAQ,IAAI,CAAC,CAAC;gBACd,QAAQ,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC;YACpC,CAAC;YACD,OAAO,QAAQ,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC;AA7CD,oBA6CC"}

package/dist/memory/store/index.js

@@ -1,6 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.InMemoryStore = void 0;
+exports.CORPUS_BUNDLE_FORMAT = exports.bundleEntryToMemoryEntry = exports.assertCorpusBundle = exports.staticVectorStore = exports.InMemoryStore = void 0;
 var InMemoryStore_js_1 = require("./InMemoryStore.js");
 Object.defineProperty(exports, "InMemoryStore", { enumerable: true, get: function () { return InMemoryStore_js_1.InMemoryStore; } });
+var staticVectorStore_js_1 = require("./staticVectorStore.js");
+Object.defineProperty(exports, "staticVectorStore", { enumerable: true, get: function () { return staticVectorStore_js_1.staticVectorStore; } });
+Object.defineProperty(exports, "assertCorpusBundle", { enumerable: true, get: function () { return staticVectorStore_js_1.assertCorpusBundle; } });
+Object.defineProperty(exports, "bundleEntryToMemoryEntry", { enumerable: true, get: function () { return staticVectorStore_js_1.bundleEntryToMemoryEntry; } });
+Object.defineProperty(exports, "CORPUS_BUNDLE_FORMAT", { enumerable: true, get: function () { return staticVectorStore_js_1.CORPUS_BUNDLE_FORMAT; } });
 //# sourceMappingURL=index.js.map

package/dist/memory/store/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/store/index.ts"],"names":[],"mappings":";;;AASA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/memory/store/index.ts"],"names":[],"mappings":";;;AASA,uDAAmD;AAA1C,iHAAA,aAAa,OAAA;AACtB,+DAQgC;AAP9B,yHAAA,iBAAiB,OAAA;AACjB,0HAAA,kBAAkB,OAAA;AAClB,gIAAA,wBAAwB,OAAA;AACxB,4HAAA,oBAAoB,OAAA"}

package/dist/memory/store/staticVectorStore.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.staticVectorStore = exports.bundleEntryToMemoryEntry = exports.assertCorpusBundle = exports.CORPUS_BUNDLE_FORMAT = void 0;
+const index_js_1 = require("../identity/index.js");
+const cosine_js_1 = require("../embedding/cosine.js");
+/** The bundle format marker. Version the FORMAT, not the library. */
+exports.CORPUS_BUNDLE_FORMAT = 'agentfootprint-corpus-v1';
+/**
+ * Validate a value as a `CorpusBundle`, teachingly. Shared by
+ * `staticVectorStore` and `importCorpus`, so a truncated file or a
+ * hand-edited bundle fails the same way at every door.
+ */
+function assertCorpusBundle(bundle, caller) {
+    const b = bundle;
+    if (b === null || typeof b !== 'object') {
+        throw new Error(`${caller}: expected a corpus bundle object, received ${b === null ? 'null' : typeof b}. ` +
+            `A bundle comes from exportCorpus() — typically JSON.parse of the file it was saved to.`);
+    }
+    if (b.format !== exports.CORPUS_BUNDLE_FORMAT) {
+        throw new Error(`${caller}: this is not a corpus bundle — \`format\` is ${JSON.stringify(b.format)}, expected '${exports.CORPUS_BUNDLE_FORMAT}'. Bundles are produced by exportCorpus(); a raw ` +
+            `entries array or a different artifact cannot be served as one.`);
+    }
+    const dims = b.embedder?.dimensions;
+    if (typeof b.embedder?.id !== 'string' || typeof dims !== 'number' || dims < 1) {
+        throw new Error(`${caller}: the bundle does not name its embedding space — \`embedder\` must carry a ` +
+            `string \`id\` and a positive \`dimensions\`. Without them nothing can refuse a wrong ` +
+            `embedder at load, which is the silent failure this format exists to prevent.`);
+    }
+    if (typeof b.namespace !== 'string' || b.namespace.length === 0) {
+        throw new Error(`${caller}: the bundle carries no \`namespace\`. Re-export with exportCorpus().`);
+    }
+    if (!Array.isArray(b.entries)) {
+        throw new Error(`${caller}: \`entries\` must be an array. Re-export with exportCorpus().`);
+    }
+    b.entries.forEach((entry, i) => {
+        const where = `entries[${i}]${entry?.id ? ` ('${entry.id}')` : ''}`;
+        if (!entry || typeof entry.id !== 'string' || entry.id.length === 0) {
+            throw new Error(`${caller}: ${where} has no \`id\`.`);
+        }
+        if (typeof entry.text !== 'string' || entry.text.trim().length === 0) {
+            throw new Error(`${caller}: ${where} has no passage on \`text\`. A citable id with nothing to cite is ` +
+                `the blank-citation bug; a bundle never carries one.`);
+        }
+        if (!Array.isArray(entry.vector) || entry.vector.length !== dims) {
+            throw new Error(`${caller}: ${where} carries a vector of length ` +
+                `${Array.isArray(entry.vector) ? entry.vector.length : 'none'}, but the bundle's ` +
+                `embedder declares ${dims} dimensions. The bundle is corrupt or hand-edited — ` +
+                `re-export it.`);
+        }
+    });
+}
+exports.assertCorpusBundle = assertCorpusBundle;
+/**
+ * The `MemoryEntry` a bundle entry seeds — in the exact shape the retrieval
+ * formatter reads: passage on `value.content`, provenance under
+ * `value.metadata`. Shared with `importCorpus` so a static corpus and an
+ * imported one render identically.
+ */
+function bundleEntryToMemoryEntry(entry, bundle) {
+    return {
+        id: entry.id,
+        value: {
+            id: entry.id,
+            content: entry.text,
+            ...(entry.metadata !== undefined && { metadata: { ...entry.metadata } }),
+        },
+        version: 1,
+        createdAt: bundle.exportedAt,
+        updatedAt: bundle.exportedAt,
+        lastAccessedAt: bundle.exportedAt,
+        accessCount: 0,
+        embedding: [...entry.vector],
+        embeddingModel: bundle.embedder.id,
+    };
+}
+exports.bundleEntryToMemoryEntry = bundleEntryToMemoryEntry;
+const READ_ONLY_FIX = `A static corpus is a build artifact: change it by re-indexing at build time and ` +
+    `re-exporting (exportCorpus), or load the bundle into a writable store with ` +
+    `importCorpus(store, bundle). For conversation memory alongside a static corpus, ` +
+    `register a SEPARATE defineMemory with its own writable store.`;
+function refuseWrite(method) {
+    throw new Error(`staticVectorStore.${method}: this store is read-only — accepting the write and losing ` +
+        `it with the process would be the quiet version of data loss. ${READ_ONLY_FIX}`);
+}
+/**
+ * Serve an exported corpus bundle as a read-only, vector-capable
+ * `MemoryStore`.
+ *
+ * @param bundle   a `CorpusBundle` from `exportCorpus` (usually
+ *                 `JSON.parse` of the shipped file).
+ * @param embedder optional — the embedder the RUNTIME will query with (or
+ *                 just `{ id, dimensions }`). When given, a fingerprint
+ *                 mismatch is refused HERE, at load, instead of surfacing as
+ *                 an empty retrieval at the first question. Recommended.
+ *
+ * @example
+ * ```ts
+ * import { staticVectorStore } from 'agentfootprint/memory';
+ * import corpus from './corpus.json';
+ *
+ * const store = staticVectorStore(corpus, embedder);
+ * const docs = defineRAG({ id: 'docs', store, embedder });
+ * ```
+ */
+function staticVectorStore(bundle, embedder) {
+    assertCorpusBundle(bundle, 'staticVectorStore');
+    if (embedder !== undefined) {
+        // The sqliteVectorStore rule, applied at load: dimensions ALWAYS decide;
+        // ids decide only when both sides named themselves.
+        if (embedder.dimensions !== bundle.embedder.dimensions) {
+            throw new Error(`staticVectorStore: this bundle was built in '${bundle.embedder.id}@` +
+                `${bundle.embedder.dimensions}' and the configured embedder produces ` +
+                `${embedder.dimensions}-dimensional vectors. Vectors of different lengths cannot ` +
+                `be compared at all. Re-export the corpus with the runtime's embedder, or ` +
+                `configure the embedder the corpus was built with.`);
+        }
+        if (embedder.id !== undefined && embedder.id !== bundle.embedder.id) {
+            throw new Error(`staticVectorStore: this bundle was built in '${bundle.embedder.id}@` +
+                `${bundle.embedder.dimensions}' and the configured embedder is '${embedder.id}'. ` +
+                `Cosine similarity between two embedding spaces is not a weak signal — it is not ` +
+                `a signal, and it comes back as a confident number in the same range as a real ` +
+                `one. Re-export the corpus with '${embedder.id}', or configure ` +
+                `'${bundle.embedder.id}'.`);
+        }
+    }
+    const entries = new Map();
+    for (const entry of bundle.entries) {
+        entries.set(entry.id, bundleEntryToMemoryEntry(entry, bundle));
+    }
+    const namespace = bundle.namespace;
+    const inNamespace = (identity) => (0, index_js_1.identityNamespace)(identity) === namespace;
+    return {
+        // Vectors in, ranked vectors out — the cosine scan below ranks the
+        // embeddings the bundle carries. Declared, so corpus builders can tell
+        // this apart from a server-side store (and refuse to INDEX into it —
+        // which they will anyway, at the first write).
+        supportsVectorSearch: true,
+        async get(identity, id) {
+            if (!inNamespace(identity))
+                return null;
+            // No access-count bump: the store is read-only, decay signals frozen
+            // at export.
+            return entries.get(id) ?? null;
+        },
+        async put() {
+            refuseWrite('put');
+        },
+        async putMany() {
+            refuseWrite('putMany');
+        },
+        async putIfVersion() {
+            refuseWrite('putIfVersion');
+        },
+        async delete() {
+            refuseWrite('delete');
+        },
+        async forget() {
+            refuseWrite('forget');
+        },
+        async recordSignature() {
+            refuseWrite('recordSignature');
+        },
+        async feedback() {
+            refuseWrite('feedback');
+        },
+        async list(identity, options) {
+            if (!inNamespace(identity))
+                return { entries: [] };
+            const limit = Math.max(1, Math.min(options?.limit ?? 100, 1000));
+            const all = [...entries.values()];
+            const offset = options?.cursor ? parseInt(options.cursor, 10) : 0;
+            const safeOffset = Number.isFinite(offset) && offset >= 0 ? offset : 0;
+            const page = all.slice(safeOffset, safeOffset + limit);
+            const next = safeOffset + page.length;
+            return {
+                entries: page,
+                ...(next < all.length && { cursor: String(next) }),
+            };
+        },
+        async seen() {
+            return false; // no signature set was exported; recognition is a write-side concern
+        },
+        async getFeedback() {
+            return null;
+        },
+        async search(identity, query, options) {
+            // A wrong-space query is refused BY NAME rather than ranked to an empty
+            // page — the loud version of the mismatch machinery, because on a
+            // static corpus "no results" reads as "the corpus has nothing to say".
+            if (query.length !== bundle.embedder.dimensions) {
+                throw new Error(`staticVectorStore.search: the query vector has ${query.length} dimensions, but ` +
+                    `this bundle was built in '${bundle.embedder.id}@${bundle.embedder.dimensions}'. ` +
+                    `The query was embedded with a different embedder than the corpus. Configure the ` +
+                    `embedder the corpus was built with, or re-export the corpus.`);
+            }
+            if (options?.embedderId !== undefined && options.embedderId !== bundle.embedder.id) {
+                throw new Error(`staticVectorStore.search: the retriever declares embedderId '${options.embedderId}' ` +
+                    `but this bundle was built in '${bundle.embedder.id}@` +
+                    `${bundle.embedder.dimensions}'. Silently skipping every entry would look like an ` +
+                    `empty corpus. Align the retriever's \`embedderId\` with the bundle, or re-export ` +
+                    `the corpus with the new embedder.`);
+            }
+            if (!inNamespace(identity))
+                return [];
+            const k = options?.k ?? 10;
+            const tierFilter = options?.tiers ? new Set(options.tiers) : undefined;
+            const minScore = options?.minScore;
+            const scored = [];
+            for (const entry of entries.values()) {
+                if (tierFilter && (!entry.tier || !tierFilter.has(entry.tier)))
+                    continue;
+                const emb = entry.embedding;
+                if (!emb || emb.length !== query.length)
+                    continue;
+                const score = (0, cosine_js_1.cosineSimilarity)(emb, query);
+                if (minScore !== undefined && score < minScore)
+                    continue;
+                scored.push({ entry: entry, score });
+            }
+            scored.sort((a, b) => {
+                if (b.score !== a.score)
+                    return b.score - a.score;
+                return a.entry.id < b.entry.id ? -1 : a.entry.id > b.entry.id ? 1 : 0;
+            });
+            return scored.slice(0, k);
+        },
+    };
+}
+exports.staticVectorStore = staticVectorStore;
+//# sourceMappingURL=staticVectorStore.js.map

package/dist/memory/store/staticVectorStore.js.map

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

package/dist/observe.js

@@ -47,7 +47,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ledgerGated = exports.ledgerEntryScorer = exports.ledgerToolGate = exports.contextLedger = exports.formatRouteHop = exports.routeRecorder = exports.toolChoiceRecorder = exports.buildChoiceContext = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.resilienceRecorder = exports.skillRecorder = exports.permissionRecorder = exports.embeddingRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.attachLocalObservability = exports.traceToStepGraph = exports.redactContent = exports.serializeTrace = exports.recordRun = exports.buildStepGraphFromEvents = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
+exports.ledgerGated = exports.ledgerEntryScorer = exports.ledgerToolGate = exports.contextLedger = exports.formatRouteHop = exports.routeRecorder = exports.toolChoiceRecorder = exports.buildChoiceContext = exports.typedEmit = exports.agentThinkingTrace = exports.toolLineageRecorder = exports.attachStatus = exports.LoggingDomains = exports.attachLogging = exports.resilienceRecorder = exports.skillRecorder = exports.permissionRecorder = exports.embeddingRecorder = exports.memoryRecorder = exports.evalRecorder = exports.contextEvaluatedRecorder = exports.toolsRecorder = exports.costRecorder = exports.LiveAgentTurnTracker = exports.LiveToolTracker = exports.LiveLLMTracker = exports.LiveStateRecorder = exports.liveStateRecorder = exports.attachLocalObservability = exports.traceToStepGraph = exports.redactContent = exports.serializeTrace = exports.summarizeVector = exports.summarizeEmbeddings = exports.recordRun = exports.buildStepGraphFromEvents = exports.buildStepGraph = exports.attachFlowchart = exports.runStepRecorder = exports.RunStepRecorder = exports.buildRunSteps = exports.BoundaryRecorder = exports.boundaryRecorder = exports.agentRecorder = exports.compositionRecorder = exports.streamRecorder = exports.ContextRecorder = void 0;
 // Tier 1 — context + stream
 var ContextRecorder_js_1 = require("./recorders/core/ContextRecorder.js");
 Object.defineProperty(exports, "ContextRecorder", { enumerable: true, get: function () { return ContextRecorder_js_1.ContextRecorder; } });
@@ -75,6 +75,13 @@ Object.defineProperty(exports, "buildStepGraphFromEvents", { enumerable: true, g
 // every integration used to assemble by hand, each missing a different piece.
 var recordRun_js_1 = require("./recorders/observability/recordRun.js");
 Object.defineProperty(exports, "recordRun", { enumerable: true, get: function () { return recordRun_js_1.recordRun; } });
+// What a recording keeps of a vector: `{ dims, norm }`, not the bytes (8.20.0).
+// Applied by BoundaryRecorder and recordRun unless `recordEmbeddings: true`;
+// exported so consumers that render or post-process recordings can apply or
+// recognise the same projection.
+var embeddingSummary_js_1 = require("./recorders/observability/embeddingSummary.js");
+Object.defineProperty(exports, "summarizeEmbeddings", { enumerable: true, get: function () { return embeddingSummary_js_1.summarizeEmbeddings; } });
+Object.defineProperty(exports, "summarizeVector", { enumerable: true, get: function () { return embeddingSummary_js_1.summarizeVector; } });
 // Offline replay: freeze a live run model into a UI-free, JSON-lossless Trace
 // (redaction applied at the serialize boundary). agentfootprint-lens's <Replay>
 // rehydrates it. See docs/design/local-observability-and-pii.md.

package/dist/observe.js.map

@@ -1 +1 @@
-{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;;;;;;;;;;;;;;;AAEH,4BAA4B;AAC5B,0EAAmG;AAA1F,qHAAA,eAAe,OAAA;AACxB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AAEvB,+BAA+B;AAC/B,kFAGiD;AAF/C,6HAAA,mBAAmB,OAAA;AAGrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,qFAoBuD;AAnBrD,uHAAA,gBAAgB,OAAA;AAChB,uHAAA,gBAAgB,OAAA;AAmBlB,mFAWsD;AAVpD,mHAAA,aAAa,OAAA;AACb,qHAAA,eAAe,OAAA;AACf,qHAAA,eAAe,OAAA;AASjB,uFAWwD;AAVtD,uHAAA,eAAe,OAAA;AACf,sHAAA,cAAc,OAAA;AACd,gIAAA,wBAAwB,OAAA;AAU1B,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAC9E,uEAKgD;AAJ9C,yGAAA,SAAS,OAAA;AAMX,8EAA8E;AAC9E,gFAAgF;AAChF,iEAAiE;AACjE,+DAQ4C;AAP1C,0GAAA,cAAc,OAAA;AACd,yGAAA,aAAa,OAAA;AACb,4GAAA,gBAAgB,OAAA;AAOlB,mEAAmE;AACnE,4EAA4E;AAC5E,mDAAmD;AACnD,yFAIyD;AAHvD,iIAAA,wBAAwB,OAAA;AAK1B,uFAUwD;AATtD,yHAAA,iBAAiB,OAAA;AACjB,yHAAA,iBAAiB,OAAA;AACjB,sHAAA,cAAc,OAAA;AACd,uHAAA,eAAe,OAAA;AACf,4HAAA,oBAAoB,OAAA;AAOtB,6BAA6B;AAC7B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,4FAGsD;AAFpD,uIAAA,wBAAwB,OAAA;AAG1B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AACvB,8EAG+C;AAF7C,yHAAA,iBAAiB,OAAA;AAGnB,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,qEAAqE;AACrE,0EAA0E;AAC1E,wEAAwE;AACxE,oDAAoD;AACpD,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,mFAMsD;AALpD,mHAAA,aAAa,OAAA;AACb,oHAAA,cAAc,OAAA;AAKhB,iFAIqD;AAHnD,iHAAA,YAAY,OAAA;AAId,4EAA4E;AAC5E,gFAAgF;AAChF,2FAO0D;AANxD,6HAAA,mBAAmB,OAAA;AAOrB,gFAAgF;AAChF,gFAAgF;AAChF,yGASiE;AAR/D,mIAAA,kBAAkB,OAAA;AAUpB,uDAAuD;AACvD,8DAA0D;AAAjD,yGAAA,SAAS,OAAA;AAElB,kEAAkE;AAClE,uEAAuE;AACvE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,wEAAwE;AACxE,6CAA2B;AAC3B,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,yFASyD;AARvD,2HAAA,kBAAkB,OAAA;AAClB,2HAAA,kBAAkB,OAAA;AASpB,+EASoD;AARlD,iHAAA,aAAa,OAAA;AACb,kHAAA,cAAc,OAAA;AAShB,sEAAsE;AACtE,4EAA4E;AAC5E,+CAA+C;AAC/C,0DAKuC;AAJrC,yGAAA,aAAa,OAAA;AACb,0GAAA,cAAc,OAAA;AACd,6GAAA,iBAAiB,OAAA;AACjB,uGAAA,WAAW,OAAA"}
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;;;;;;;;;;;;;;;;;AAEH,4BAA4B;AAC5B,0EAAmG;AAA1F,qHAAA,eAAe,OAAA;AACxB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AAEvB,+BAA+B;AAC/B,kFAGiD;AAF/C,6HAAA,mBAAmB,OAAA;AAGrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,qFAoBuD;AAnBrD,uHAAA,gBAAgB,OAAA;AAChB,uHAAA,gBAAgB,OAAA;AAmBlB,mFAWsD;AAVpD,mHAAA,aAAa,OAAA;AACb,qHAAA,eAAe,OAAA;AACf,qHAAA,eAAe,OAAA;AASjB,uFAWwD;AAVtD,uHAAA,eAAe,OAAA;AACf,sHAAA,cAAc,OAAA;AACd,gIAAA,wBAAwB,OAAA;AAU1B,yEAAyE;AACzE,6EAA6E;AAC7E,6EAA6E;AAC7E,8EAA8E;AAC9E,uEAKgD;AAJ9C,yGAAA,SAAS,OAAA;AAMX,gFAAgF;AAChF,6EAA6E;AAC7E,4EAA4E;AAC5E,iCAAiC;AACjC,qFAIuD;AAHrD,0HAAA,mBAAmB,OAAA;AACnB,sHAAA,eAAe,OAAA;AAIjB,8EAA8E;AAC9E,gFAAgF;AAChF,iEAAiE;AACjE,+DAQ4C;AAP1C,0GAAA,cAAc,OAAA;AACd,yGAAA,aAAa,OAAA;AACb,4GAAA,gBAAgB,OAAA;AAOlB,mEAAmE;AACnE,4EAA4E;AAC5E,mDAAmD;AACnD,yFAIyD;AAHvD,iIAAA,wBAAwB,OAAA;AAK1B,uFAUwD;AATtD,yHAAA,iBAAiB,OAAA;AACjB,yHAAA,iBAAiB,OAAA;AACjB,sHAAA,cAAc,OAAA;AACd,uHAAA,eAAe,OAAA;AACf,4HAAA,oBAAoB,OAAA;AAOtB,6BAA6B;AAC7B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,4FAGsD;AAFpD,uIAAA,wBAAwB,OAAA;AAG1B,oEAA0F;AAAjF,+GAAA,YAAY,OAAA;AACrB,wEAAgG;AAAvF,mHAAA,cAAc,OAAA;AACvB,8EAG+C;AAF7C,yHAAA,iBAAiB,OAAA;AAGnB,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,sEAA6F;AAApF,iHAAA,aAAa,OAAA;AACtB,qEAAqE;AACrE,0EAA0E;AAC1E,wEAAwE;AACxE,oDAAoD;AACpD,gFAGgD;AAF9C,2HAAA,kBAAkB,OAAA;AAGpB,mFAMsD;AALpD,mHAAA,aAAa,OAAA;AACb,oHAAA,cAAc,OAAA;AAKhB,iFAIqD;AAHnD,iHAAA,YAAY,OAAA;AAId,4EAA4E;AAC5E,gFAAgF;AAChF,2FAO0D;AANxD,6HAAA,mBAAmB,OAAA;AAOrB,gFAAgF;AAChF,gFAAgF;AAChF,yGASiE;AAR/D,mIAAA,kBAAkB,OAAA;AAUpB,uDAAuD;AACvD,8DAA0D;AAAjD,yGAAA,SAAS,OAAA;AAElB,kEAAkE;AAClE,uEAAuE;AACvE,4EAA4E;AAC5E,6EAA6E;AAC7E,4EAA4E;AAC5E,wEAAwE;AACxE,6CAA2B;AAC3B,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,oEAAoE;AACpE,yFASyD;AARvD,2HAAA,kBAAkB,OAAA;AAClB,2HAAA,kBAAkB,OAAA;AASpB,+EASoD;AARlD,iHAAA,aAAa,OAAA;AACb,kHAAA,cAAc,OAAA;AAShB,sEAAsE;AACtE,4EAA4E;AAC5E,+CAA+C;AAC/C,0DAKuC;AAJrC,yGAAA,aAAa,OAAA;AACb,0GAAA,cAAc,OAAA;AACd,6GAAA,iBAAiB,OAAA;AACjB,uGAAA,WAAW,OAAA"}