@graphorin/memory 0.5.0 → 0.6.1

package/dist/internal/storage-adapter.d.ts

@@ -1,4 +1,4 @@
-import { EntityRole, Episode as Episode$1, EpisodicMemoryStore, Fact as Fact$1, GraphEntity, Insight as Insight$1, MemoryHit, MemoryStatus, MemoryStore, Message as Message$1, ProceduralMemoryStore, SemanticMemoryStore, SessionMemoryStore, SessionScope as SessionScope$1 } from "@graphorin/core";
+import { EntityRole, Episode as Episode$1, EpisodicMemoryStore, Fact as Fact$1, GraphEntity, Insight as Insight$1, MemoryHit, MemoryOwner, MemoryStatus, MemoryStore, Message as Message$1, ProceduralMemoryStore, Rule, SemanticMemoryStore, SessionMemoryStore, SessionScope as SessionScope$1 } from "@graphorin/core";
 
 //#region src/internal/storage-adapter.d.ts
 
@@ -37,11 +37,11 @@ interface EpisodicMemoryStoreExt extends EpisodicMemoryStore {
   searchVector?(scope: SessionScope$1, embedding: Float32Array, embedderId: string, topK: number, /** Point-in-time filter (`started_at <= asOf`, ISO-8601). P0-2. */
   asOf?: string, /** Include quarantined episodes (validation/inspector path). P1-4. */
   includeQuarantined?: boolean): Promise<ReadonlyArray<MemoryHit<Episode$1>>>;
-  /** Mark an episode archived. Soft-archive — the row stays for replay. */
+  /** Mark an episode archived. Soft-archive - the row stays for replay. */
   archive?(id: string, reason?: string): Promise<void>;
   /**
    * Most-recent episodes by end time (newest first), with no FTS / vector
-   * query — recency, not relevance (MCON-1). Powers `EpisodicMemory.recent()`
+   * query - recency, not relevance (MCON-1). Powers `EpisodicMemory.recent()`
    * and the deep-phase reflection gate. The default `@graphorin/store-sqlite`
    * adapter implements it.
    */
@@ -49,13 +49,13 @@ interface EpisodicMemoryStoreExt extends EpisodicMemoryStore {
     includeQuarantined?: boolean;
   }): Promise<ReadonlyArray<Episode$1>>;
   /**
-   * Set an episode's retrieval-trust `status` (MCON-2) — promote a quarantined
+   * Set an episode's retrieval-trust `status` (MCON-2) - promote a quarantined
    * (auto-formed) episode into default recall or re-quarantine an active one,
    * with a `memory_history` audit row. Powers {@link EpisodicMemory.validate}.
    */
   setStatus?(id: string, status: MemoryStatus, reason?: string): Promise<void>;
   /**
-   * Count the recall-eligible episodes for the scope (CE-5) — a `COUNT(*)`,
+   * Count the recall-eligible episodes for the scope (CE-5) - a `COUNT(*)`,
    * never materialising rows. Powers honest `metadata()` counts.
    */
   count?(scope: SessionScope$1): Promise<number>;
@@ -79,20 +79,30 @@ interface SemanticMemoryStoreExt extends SemanticMemoryStore {
    * Include quarantined facts in the KNN result (validation /
    * inspector path). Default reads exclude them. P1-4.
    */
-  includeQuarantined?: boolean): Promise<ReadonlyArray<MemoryHit<Fact$1>>>;
+  includeQuarantined?: boolean,
+  /**
+   * Include superseded / validity-expired facts. Default reads
+   * evaluate validity at NOW (memory-retrieval-01).
+   */
+  includeSuperseded?: boolean,
+  /**
+   * Retrieval-time principal filter (D3). Rows with no stored owner
+   * are treated as `'user'`. Absent ⇒ no owner filter.
+   */
+  owner?: MemoryOwner | ReadonlyArray<MemoryOwner>): Promise<ReadonlyArray<MemoryHit<Fact$1>>>;
   /** Lookup a single fact by id (returns `null` when absent or soft-deleted). */
   get?(id: string): Promise<Fact$1 | null>;
   /**
    * Set a fact's retrieval-trust `status` and write a `memory_history`
    * audit row (P1-4). Promotes a quarantined fact to `active` (the
    * validation path) or re-quarantines an active one. Never touches
-   * content / embedding / tombstone — quarantine is a retrieval gate.
+   * content / embedding / tombstone - quarantine is a retrieval gate.
    * Powers {@link SemanticMemory.validate}; the default
    * `@graphorin/store-sqlite` adapter implements it.
    */
   setStatus?(factId: string, status: MemoryStatus, reason?: string): Promise<void>;
   /**
-   * Count the recall-eligible facts for the scope (CE-5) — a `COUNT(*)` with
+   * Count the recall-eligible facts for the scope (CE-5) - a `COUNT(*)` with
    * the default recall filters (live, non-archived, non-quarantined), never
    * materialising rows. Powers honest `metadata()` counts.
    */
@@ -152,7 +162,7 @@ interface SessionMemoryStoreExt extends SessionMemoryStore {
    */
   listMessagesSince?(scope: SessionScope$1, lastMessageId: string | null, limit: number): Promise<ReadonlyArray<SessionMessageRecord>>;
   /**
-   * Count the live messages in the scoped session (CE-5) — a `COUNT(*)`, never
+   * Count the live messages in the scoped session (CE-5) - a `COUNT(*)`, never
    * materialising rows; `0` for a user-only scope. Powers honest `metadata()`
    * counts instead of `list(...)`-materialising up to 1000 rows.
    */
@@ -226,7 +236,7 @@ interface ConflictAuditInputLike {
   readonly detectedBy?: string;
 }
 /**
- * Pending-queue payload — Stage 5 (defer-to-deep) hands the row over
+ * Pending-queue payload - Stage 5 (defer-to-deep) hands the row over
  * to the deep-phase LLM judge (Phase 10c).
  *
  * @stable
@@ -281,7 +291,7 @@ interface ConflictMemoryStoreExt {
    * Stamp `attemptedAt` on a pending row whose judge call failed
    * (MCON-9). The deep phase closes the row as `'judge-unparseable'`
    * on the NEXT failure, so a poisoned row is billed at most twice.
-   * Optional — without it the deep phase falls back to skip-and-retry.
+   * Optional - without it the deep phase falls back to skip-and-retry.
    */
   markAttempted?(id: number, attemptedAt?: number): Promise<void>;
 }
@@ -399,7 +409,7 @@ interface DlqBatchRow {
  * for Phase 10c. Mirrors the `consolidator_state`,
  * `consolidator_runs`, and `consolidator_failed_batches` tables
  * shipped in Phase 05's migration 009. Adapters that do not
- * implement the surface degrade gracefully — the consolidator runs
+ * implement the surface degrade gracefully - the consolidator runs
  * in stateless mode (no DLQ, no cursor persistence) and emits a
  * one-shot WARN.
  *
@@ -437,7 +447,7 @@ interface ConsolidatorMemoryStoreExt {
    * oldest backlog drains first.
    */
   claimReadyBatches(scope: SessionScope$1, now: number, limit?: number): Promise<ReadonlyArray<DlqBatchRow>>;
-  /** Mark the row succeeded — removes it from the DLQ. */
+  /** Mark the row succeeded - removes it from the DLQ. */
   markBatchSucceeded(id: string): Promise<void>;
   /**
    * Schedule the next retry attempt. The caller computes
@@ -462,7 +472,7 @@ interface ConsolidatorMemoryStoreExt {
  * 10c's light phase reads the strength + last-accessed columns and
  * archives facts whose retention curve falls below the configured
  * threshold. Adapters that do not maintain decay columns may omit
- * the surface entirely — the light phase skips the archive step
+ * the surface entirely - the light phase skips the archive step
  * with an INFO log.
  *
  * @stable
@@ -473,7 +483,7 @@ interface DecayMemoryStoreExt {
    * caller can apply Ebbinghaus retention without scanning the
    * whole table. `limit` defaults to `1000`.
    *
-   * Archived rows are EXCLUDED by default (MCON-6) — they never receive
+   * Archived rows are EXCLUDED by default (MCON-6) - they never receive
    * access bumps, so they would pin the LRU head and saturate the decay
    * window, structurally stopping threshold-archiving and capacity
    * eviction for live facts. Inspection paths pass
@@ -497,6 +507,12 @@ interface DecayMemoryStoreExt {
     readonly status: string;
     /** Trust-provenance tag (P1-4); `null` for first-party rows. */
     readonly provenance: string | null;
+    /**
+     * Monotonic retrieval-access counter (D3, migration 027). Feeds
+     * the opt-in `accessReinforcement` salience weight. Optional -
+     * adapters without the column omit it (treated as `0`).
+     */
+    readonly accessCount?: number;
   }>>;
   /**
    * Soft-archive a fact (sets `archived = 1`). The audit row in
@@ -506,13 +522,13 @@ interface DecayMemoryStoreExt {
   /**
    * Record a retrieval access for the given facts (MRET-7): stamp
    * `lastAccessedAt` and reinforce `strength` (implementation-capped).
-   * Optional — adapters without decay columns may omit it; callers
+   * Optional - adapters without decay columns may omit it; callers
    * MUST treat failures as non-fatal (the read path never breaks on a
    * bookkeeping write).
    */
   markAccessed?(ids: ReadonlyArray<string>, accessedAt?: number): Promise<void>;
   /**
-   * Narrow decay-column read for exactly the given fact ids (MRET-8) —
+   * Narrow decay-column read for exactly the given fact ids (MRET-8) -
    * powers per-search decay re-ranking without the old O(scope)
    * 1000-row window read. Optional; absent ⇒ the tier falls back to
    * `listForDecay`.
@@ -541,7 +557,7 @@ interface InsightSearchStoreOptions {
  * (P1-1). The consolidator's reflection pass inserts quarantined,
  * cited insights here; the thin `InsightMemory` read surface lists /
  * searches them; the ExpeL salience loop bumps + prunes them. Search is
- * FTS-only by design — insights are a soft, rank-capped inspector
+ * FTS-only by design - insights are a soft, rank-capped inspector
  * surface, not primary recall.
  *
  * Adapters that opt out leave the property undefined; reflection then
@@ -561,7 +577,7 @@ interface InsightMemoryStoreExt {
   /** Lookup a single insight by id (`null` when absent / pruned). */
   get?(id: string): Promise<Insight$1 | null>;
   /**
-   * Set an insight's retrieval-trust `status` (MCON-2) — promote a quarantined
+   * Set an insight's retrieval-trust `status` (MCON-2) - promote a quarantined
    * (reflection) insight or re-quarantine an active one, with a
    * `memory_history` audit row. Powers {@link InsightMemory.validate}.
    */
@@ -573,7 +589,7 @@ interface InsightMemoryStoreExt {
   bumpSalience(id: string, delta: number, reason?: string): Promise<void>;
   /**
    * Soft-delete every salience-0 insight for the scope (the ExpeL
-   * forgetting step). Returns the number pruned. Tombstone only —
+   * forgetting step). Returns the number pruned. Tombstone only -
    * pruned insights stay auditable.
    */
   prune(scope: SessionScope$1): Promise<number>;
@@ -586,16 +602,28 @@ interface InsightMemoryStoreExt {
  */
 interface ProceduralMemoryStoreExt extends ProceduralMemoryStore {
   /**
-   * Set a rule's retrieval-trust `status` — promote a quarantined (induced)
+   * Set a rule's retrieval-trust `status` - promote a quarantined (induced)
    * procedure into `activate()` or re-quarantine an active one, with a
    * `memory_history` audit row. Powers {@link ProceduralMemory.validate}.
    */
   setStatus?(id: string, status: MemoryStatus, reason?: string): Promise<void>;
+  /**
+   * Lexical runbook search over rule text (D3, migration 028) - content
+   * recall for "find the procedure for this task", as opposed to
+   * predicate activation. Quarantined (unvalidated induced) procedures
+   * are excluded unless the inspector opts in. Optional - adapters
+   * without the index omit it and {@link ProceduralMemory.search} falls
+   * back to an in-memory lexical scan over `list(...)`.
+   */
+  search?(scope: SessionScope$1, query: string, opts?: {
+    readonly topK?: number;
+    readonly includeQuarantined?: boolean;
+  }): Promise<ReadonlyArray<MemoryHit<Rule>>>;
   /**
    * Record one demonstrated successful reuse of a rule and return the
    * new counter value (MCON-2 part 4). Powers
    * promotion-by-demonstrated-success via
-   * {@link ProceduralMemory.recordOutcome}. Optional — adapters without
+   * {@link ProceduralMemory.recordOutcome}. Optional - adapters without
    * the counter simply never auto-promote.
    */
   recordSuccess?(id: string): Promise<number>;
@@ -639,6 +667,11 @@ interface ExpandHopsStoreOptions {
   readonly includeQuarantined?: boolean;
   /** Point-in-time filter, ISO-8601 (same semantics as fact search). */
   readonly asOf?: string;
+  /**
+   * Include superseded / validity-expired neighbours. Default reads
+   * evaluate validity at NOW (memory-retrieval-01).
+   */
+  readonly includeSuperseded?: boolean;
 }
 /**
  * Optional storage extension for the lightweight in-SQLite relation
@@ -686,6 +719,22 @@ interface GraphMemoryStoreExt {
   }): Promise<ReadonlyArray<EntityMergeRecord>>;
   /** Expand seed facts to neighbours sharing a canonical entity (one-hop CTE). */
   expandOneHop(scope: SessionScope$1, seedFactIds: ReadonlyArray<string>, opts?: ExpandHopsStoreOptions): Promise<ReadonlyArray<Fact$1>>;
+  /**
+   * PPR-lite graded expansion (D5): like {@link expandOneHop} but returns
+   * each neighbour with its minimum hop `depth` from the seeds, so the
+   * tier can weight it by damped spreading activation. Optional - stores
+   * without it fall back to flat one-hop expansion.
+   */
+  expandActivation?(scope: SessionScope$1, seedFactIds: ReadonlyArray<string>, opts?: ExpandHopsStoreOptions): Promise<ReadonlyArray<{
+    readonly fact: Fact$1;
+    readonly depth: number;
+  }>>;
+  /**
+   * Exact entity-match retriever (D5): facts linked to the canonical
+   * entity for `normalizedName`. Optional. Powers a precise
+   * "facts about <entity>" candidate leg.
+   */
+  factsForEntityName?(scope: SessionScope$1, normalizedName: string, opts?: ExpandHopsStoreOptions): Promise<ReadonlyArray<Fact$1>>;
 }
 /**
  * Composite shape every `@graphorin/memory` consumer must supply at

package/dist/internal/storage-adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"storage-adapter.d.ts","names":[],"sources":["../../src/internal/storage-adapter.ts"],"sourcesContent":[],"mappings":"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"}
+{"version":3,"file":"storage-adapter.d.ts","names":[],"sources":["../../src/internal/storage-adapter.ts"],"sourcesContent":[],"mappings":"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"}

package/dist/migration/embedder-migration.d.ts

@@ -6,12 +6,12 @@ import { EmbedderProvider } from "@graphorin/core";
 /**
  * Coexistence policy for embedder swaps.
  *
- *  - `'lock-on-first'` (default) — refuses to register a second active
+ *  - `'lock-on-first'` (default) - refuses to register a second active
  *    embedder; surfaces an actionable error pointing at the planned
  *    migration runner.
- *  - `'multi-active'` — keeps both embedders alive (read union, write
+ *  - `'multi-active'` - keeps both embedders alive (read union, write
  *    to active); used while a long migration is in flight.
- *  - `'auto-migrate'` — re-embeds existing rows in resumable batches
+ *  - `'auto-migrate'` - re-embeds existing rows in resumable batches
  *    until the source embedder has zero rows, then retires it.
  *
  * @stable
@@ -23,7 +23,7 @@ type EmbedderMigrationStrategy = 'lock-on-first' | 'multi-active' | 'auto-migrat
  * @stable
  */
 interface MigrationProgress {
-  /** `'fact'`, `'episode'`, or `'message'` — which entity is being migrated. */
+  /** `'fact'`, `'episode'`, or `'message'` - which entity is being migrated. */
   readonly kind: 'fact' | 'episode' | 'message';
   /** Number of records processed so far. */
   readonly processed: number;
@@ -35,7 +35,7 @@ interface MigrationProgress {
   readonly target: string;
   /**
    * Identifier for this migration run. MST-12: this is an in-memory id for
-   * the current run — there is no persisted `migration_state` cursor today, so
+   * the current run - there is no persisted `migration_state` cursor today, so
    * a migration does not resume across processes.
    */
   readonly migrationId: string;
@@ -66,12 +66,12 @@ interface MigrateEmbedderOptions {
   readonly maxRecordsPerKind?: number;
   /**
    * Hook that returns the next batch of rows to re-embed for a given kind.
-   * MST-12: this is **caller-supplied** — there is no store-side helper that
+   * MST-12: this is **caller-supplied** - there is no store-side helper that
    * auto-wires it today, and `auto-migrate` throws without it. Pass a paging
    * function over your source rows to drive the migration.
    */
   readonly nextBatch?: NextBatchHook;
-  /** Optional abort signal — aborting yields one final progress event. */
+  /** Optional abort signal - aborting yields one final progress event. */
   readonly signal?: AbortSignal;
 }
 /**

package/dist/migration/embedder-migration.js.map

@@ -1 +1 @@
-{"version":3,"file":"embedder-migration.js","names":["cursor: string | null"],"sources":["../../src/migration/embedder-migration.ts"],"sourcesContent":["import type { EmbedderProvider } from '@graphorin/core';\nimport {\n  EmbedderMigrationAbortedError,\n  EmbedderMigrationLockedError,\n  EmbedderMigrationStateError,\n} from '../errors/index.js';\nimport { bindEmbedder } from '../internal/embedder-binding.js';\nimport type { EmbeddingMetaRegistryLike } from '../internal/storage-adapter.js';\n\n/**\n * Coexistence policy for embedder swaps.\n *\n *  - `'lock-on-first'` (default) — refuses to register a second active\n *    embedder; surfaces an actionable error pointing at the planned\n *    migration runner.\n *  - `'multi-active'` — keeps both embedders alive (read union, write\n *    to active); used while a long migration is in flight.\n *  - `'auto-migrate'` — re-embeds existing rows in resumable batches\n *    until the source embedder has zero rows, then retires it.\n *\n * @stable\n */\nexport type EmbedderMigrationStrategy = 'lock-on-first' | 'multi-active' | 'auto-migrate';\n\n/**\n * Per-iteration progress snapshot yielded by {@link migrateEmbedder}.\n *\n * @stable\n */\nexport interface MigrationProgress {\n  /** `'fact'`, `'episode'`, or `'message'` — which entity is being migrated. */\n  readonly kind: 'fact' | 'episode' | 'message';\n  /** Number of records processed so far. */\n  readonly processed: number;\n  /** Total records expected for this entity (when known). */\n  readonly total: number;\n  /** Identifier of the source embedder (`'<adapter>:<model>@<dim>'`). */\n  readonly source: string;\n  /** Identifier of the target embedder. */\n  readonly target: string;\n  /**\n   * Identifier for this migration run. MST-12: this is an in-memory id for\n   * the current run — there is no persisted `migration_state` cursor today, so\n   * a migration does not resume across processes.\n   */\n  readonly migrationId: string;\n  /** Phase discriminator. */\n  readonly phase: 'planning' | 'running' | 'paused' | 'committed' | 'aborted';\n}\n\n/**\n * Options accepted by {@link migrateEmbedder}.\n *\n * @stable\n */\nexport interface MigrateEmbedderOptions {\n  /** Source embedder (currently active). */\n  readonly source: EmbedderProvider;\n  /** Target embedder (becomes active when migration commits). */\n  readonly target: EmbedderProvider;\n  /** Storage layer's embedder registry. */\n  readonly embeddings: EmbeddingMetaRegistryLike;\n  /** Strategy applied per `embedding_meta` row. Default `'lock-on-first'`. */\n  readonly strategy?: EmbedderMigrationStrategy;\n  /**\n   * Threshold for `auto-migrate`. The runner streams source rows in\n   * batches of `batchSize` (default `512`) and yields progress after\n   * each batch.\n   */\n  readonly batchSize?: number;\n  /** Optional cap on the number of rows to migrate per kind. */\n  readonly maxRecordsPerKind?: number;\n  /**\n   * Hook that returns the next batch of rows to re-embed for a given kind.\n   * MST-12: this is **caller-supplied** — there is no store-side helper that\n   * auto-wires it today, and `auto-migrate` throws without it. Pass a paging\n   * function over your source rows to drive the migration.\n   */\n  readonly nextBatch?: NextBatchHook;\n  /** Optional abort signal — aborting yields one final progress event. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Per-batch loader. Returns up to `batchSize` rows for the supplied\n * `kind` whose `embedder_id` is the source embedder. Returning an\n * empty array signals end-of-stream.\n *\n * @stable\n */\nexport type NextBatchHook = (args: {\n  readonly kind: 'fact' | 'episode' | 'message';\n  readonly source: string;\n  readonly target: string;\n  readonly batchSize: number;\n  readonly cursor: string | null;\n}) => Promise<{ readonly rows: ReadonlyArray<MigrationRow>; readonly nextCursor: string | null }>;\n\n/**\n * Single row exposed to the migration runner. The runner re-embeds\n * `text` with the target embedder; the storage adapter is responsible\n * for committing the new vector + updating `embedder_id`.\n *\n * @stable\n */\nexport interface MigrationRow {\n  readonly id: string;\n  readonly text: string;\n  readonly write: (vector: Float32Array) => Promise<void>;\n}\n\n/**\n * Stream embedder migrations as `AsyncIterable<MigrationProgress>`.\n *\n * The function is the universal entry point for every migration\n * strategy:\n *\n *  - `'lock-on-first'`: surfaces the locked error eagerly so the\n *    operator can act before any work happens.\n *  - `'multi-active'`: registers the target alongside the source and\n *    yields a single `'committed'` progress event.\n *  - `'auto-migrate'`: streams batches until the source is fully\n *    drained, then retires the source row.\n *\n * @stable\n */\nexport async function* migrateEmbedder(\n  options: MigrateEmbedderOptions,\n): AsyncGenerator<MigrationProgress, void, unknown> {\n  const { source, target, embeddings } = options;\n  const strategy = options.strategy ?? 'lock-on-first';\n  const sourceId = source.id();\n  const targetId = target.id();\n  const migrationId = `migration_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;\n\n  if (sourceId === targetId) {\n    throw new EmbedderMigrationStateError(\n      `source and target embedders must differ; both resolved to '${sourceId}'.`,\n    );\n  }\n\n  const sourceMeta = embeddings.get(sourceId);\n  if (sourceMeta === null) {\n    throw new EmbedderMigrationStateError(\n      `source embedder '${sourceId}' is not registered. Run createMemory({ embedder: source }) first.`,\n    );\n  }\n\n  if (strategy === 'lock-on-first') {\n    throw new EmbedderMigrationLockedError(sourceId, targetId);\n  }\n\n  bindEmbedder(target, embeddings);\n\n  if (strategy === 'multi-active') {\n    yield {\n      kind: 'fact',\n      processed: 0,\n      total: 0,\n      source: sourceId,\n      target: targetId,\n      migrationId,\n      phase: 'committed',\n    };\n    return;\n  }\n\n  // strategy === 'auto-migrate'\n  if (options.nextBatch === undefined) {\n    throw new EmbedderMigrationStateError(\n      \"'auto-migrate' requires a `nextBatch` hook supplied by the storage adapter.\",\n    );\n  }\n\n  const batchSize = options.batchSize ?? 512;\n  const cap = options.maxRecordsPerKind ?? Number.POSITIVE_INFINITY;\n\n  for (const kind of ['fact', 'episode', 'message'] as const) {\n    let cursor: string | null = null;\n    let processed = 0;\n    while (processed < cap) {\n      if (options.signal?.aborted === true) {\n        yield {\n          kind,\n          processed,\n          total: processed,\n          source: sourceId,\n          target: targetId,\n          migrationId,\n          phase: 'aborted',\n        };\n        throw new EmbedderMigrationAbortedError(migrationId);\n      }\n      const batch = await options.nextBatch({\n        kind,\n        source: sourceId,\n        target: targetId,\n        batchSize,\n        cursor,\n      });\n      if (batch.rows.length === 0) break;\n      const texts = batch.rows.map((r) => r.text);\n      const vectors = await target.embed(texts, {\n        ...(options.signal !== undefined ? { signal: options.signal } : {}),\n      });\n      for (let i = 0; i < batch.rows.length; i++) {\n        const row = batch.rows[i];\n        const vector = vectors[i];\n        if (row === undefined || vector === undefined) continue;\n        await row.write(vector);\n      }\n      processed += batch.rows.length;\n      cursor = batch.nextCursor;\n      yield {\n        kind,\n        processed,\n        total: processed,\n        source: sourceId,\n        target: targetId,\n        migrationId,\n        phase: 'running',\n      };\n      if (cursor === null) break;\n    }\n  }\n\n  embeddings.retire(sourceId);\n  yield {\n    kind: 'fact',\n    processed: 0,\n    total: 0,\n    source: sourceId,\n    target: targetId,\n    migrationId,\n    phase: 'committed',\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA8HA,gBAAuB,gBACrB,SACkD;CAClD,MAAM,EAAE,QAAQ,QAAQ,eAAe;CACvC,MAAM,WAAW,QAAQ,YAAY;CACrC,MAAM,WAAW,OAAO,IAAI;CAC5B,MAAM,WAAW,OAAO,IAAI;CAC5B,MAAM,cAAc,aAAa,KAAK,KAAK,CAAC,SAAS,GAAG,CAAC,GAAG,KAAK,QAAQ,CAAC,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE;AAElG,KAAI,aAAa,SACf,OAAM,IAAI,4BACR,8DAA8D,SAAS,IACxE;AAIH,KADmB,WAAW,IAAI,SAAS,KACxB,KACjB,OAAM,IAAI,4BACR,oBAAoB,SAAS,oEAC9B;AAGH,KAAI,aAAa,gBACf,OAAM,IAAI,6BAA6B,UAAU,SAAS;AAG5D,cAAa,QAAQ,WAAW;AAEhC,KAAI,aAAa,gBAAgB;AAC/B,QAAM;GACJ,MAAM;GACN,WAAW;GACX,OAAO;GACP,QAAQ;GACR,QAAQ;GACR;GACA,OAAO;GACR;AACD;;AAIF,KAAI,QAAQ,cAAc,OACxB,OAAM,IAAI,4BACR,8EACD;CAGH,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,MAAM,QAAQ,qBAAqB,OAAO;AAEhD,MAAK,MAAM,QAAQ;EAAC;EAAQ;EAAW;EAAU,EAAW;EAC1D,IAAIA,SAAwB;EAC5B,IAAI,YAAY;AAChB,SAAO,YAAY,KAAK;AACtB,OAAI,QAAQ,QAAQ,YAAY,MAAM;AACpC,UAAM;KACJ;KACA;KACA,OAAO;KACP,QAAQ;KACR,QAAQ;KACR;KACA,OAAO;KACR;AACD,UAAM,IAAI,8BAA8B,YAAY;;GAEtD,MAAM,QAAQ,MAAM,QAAQ,UAAU;IACpC;IACA,QAAQ;IACR,QAAQ;IACR;IACA;IACD,CAAC;AACF,OAAI,MAAM,KAAK,WAAW,EAAG;GAC7B,MAAM,QAAQ,MAAM,KAAK,KAAK,MAAM,EAAE,KAAK;GAC3C,MAAM,UAAU,MAAM,OAAO,MAAM,OAAO,EACxC,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,QAAQ,GAAG,EAAE,EACnE,CAAC;AACF,QAAK,IAAI,IAAI,GAAG,IAAI,MAAM,KAAK,QAAQ,KAAK;IAC1C,MAAM,MAAM,MAAM,KAAK;IACvB,MAAM,SAAS,QAAQ;AACvB,QAAI,QAAQ,UAAa,WAAW,OAAW;AAC/C,UAAM,IAAI,MAAM,OAAO;;AAEzB,gBAAa,MAAM,KAAK;AACxB,YAAS,MAAM;AACf,SAAM;IACJ;IACA;IACA,OAAO;IACP,QAAQ;IACR,QAAQ;IACR;IACA,OAAO;IACR;AACD,OAAI,WAAW,KAAM;;;AAIzB,YAAW,OAAO,SAAS;AAC3B,OAAM;EACJ,MAAM;EACN,WAAW;EACX,OAAO;EACP,QAAQ;EACR,QAAQ;EACR;EACA,OAAO;EACR"}
+{"version":3,"file":"embedder-migration.js","names":["cursor: string | null"],"sources":["../../src/migration/embedder-migration.ts"],"sourcesContent":["import type { EmbedderProvider } from '@graphorin/core';\nimport {\n  EmbedderMigrationAbortedError,\n  EmbedderMigrationLockedError,\n  EmbedderMigrationStateError,\n} from '../errors/index.js';\nimport { bindEmbedder } from '../internal/embedder-binding.js';\nimport type { EmbeddingMetaRegistryLike } from '../internal/storage-adapter.js';\n\n/**\n * Coexistence policy for embedder swaps.\n *\n *  - `'lock-on-first'` (default) - refuses to register a second active\n *    embedder; surfaces an actionable error pointing at the planned\n *    migration runner.\n *  - `'multi-active'` - keeps both embedders alive (read union, write\n *    to active); used while a long migration is in flight.\n *  - `'auto-migrate'` - re-embeds existing rows in resumable batches\n *    until the source embedder has zero rows, then retires it.\n *\n * @stable\n */\nexport type EmbedderMigrationStrategy = 'lock-on-first' | 'multi-active' | 'auto-migrate';\n\n/**\n * Per-iteration progress snapshot yielded by {@link migrateEmbedder}.\n *\n * @stable\n */\nexport interface MigrationProgress {\n  /** `'fact'`, `'episode'`, or `'message'` - which entity is being migrated. */\n  readonly kind: 'fact' | 'episode' | 'message';\n  /** Number of records processed so far. */\n  readonly processed: number;\n  /** Total records expected for this entity (when known). */\n  readonly total: number;\n  /** Identifier of the source embedder (`'<adapter>:<model>@<dim>'`). */\n  readonly source: string;\n  /** Identifier of the target embedder. */\n  readonly target: string;\n  /**\n   * Identifier for this migration run. MST-12: this is an in-memory id for\n   * the current run - there is no persisted `migration_state` cursor today, so\n   * a migration does not resume across processes.\n   */\n  readonly migrationId: string;\n  /** Phase discriminator. */\n  readonly phase: 'planning' | 'running' | 'paused' | 'committed' | 'aborted';\n}\n\n/**\n * Options accepted by {@link migrateEmbedder}.\n *\n * @stable\n */\nexport interface MigrateEmbedderOptions {\n  /** Source embedder (currently active). */\n  readonly source: EmbedderProvider;\n  /** Target embedder (becomes active when migration commits). */\n  readonly target: EmbedderProvider;\n  /** Storage layer's embedder registry. */\n  readonly embeddings: EmbeddingMetaRegistryLike;\n  /** Strategy applied per `embedding_meta` row. Default `'lock-on-first'`. */\n  readonly strategy?: EmbedderMigrationStrategy;\n  /**\n   * Threshold for `auto-migrate`. The runner streams source rows in\n   * batches of `batchSize` (default `512`) and yields progress after\n   * each batch.\n   */\n  readonly batchSize?: number;\n  /** Optional cap on the number of rows to migrate per kind. */\n  readonly maxRecordsPerKind?: number;\n  /**\n   * Hook that returns the next batch of rows to re-embed for a given kind.\n   * MST-12: this is **caller-supplied** - there is no store-side helper that\n   * auto-wires it today, and `auto-migrate` throws without it. Pass a paging\n   * function over your source rows to drive the migration.\n   */\n  readonly nextBatch?: NextBatchHook;\n  /** Optional abort signal - aborting yields one final progress event. */\n  readonly signal?: AbortSignal;\n}\n\n/**\n * Per-batch loader. Returns up to `batchSize` rows for the supplied\n * `kind` whose `embedder_id` is the source embedder. Returning an\n * empty array signals end-of-stream.\n *\n * @stable\n */\nexport type NextBatchHook = (args: {\n  readonly kind: 'fact' | 'episode' | 'message';\n  readonly source: string;\n  readonly target: string;\n  readonly batchSize: number;\n  readonly cursor: string | null;\n}) => Promise<{ readonly rows: ReadonlyArray<MigrationRow>; readonly nextCursor: string | null }>;\n\n/**\n * Single row exposed to the migration runner. The runner re-embeds\n * `text` with the target embedder; the storage adapter is responsible\n * for committing the new vector + updating `embedder_id`.\n *\n * @stable\n */\nexport interface MigrationRow {\n  readonly id: string;\n  readonly text: string;\n  readonly write: (vector: Float32Array) => Promise<void>;\n}\n\n/**\n * Stream embedder migrations as `AsyncIterable<MigrationProgress>`.\n *\n * The function is the universal entry point for every migration\n * strategy:\n *\n *  - `'lock-on-first'`: surfaces the locked error eagerly so the\n *    operator can act before any work happens.\n *  - `'multi-active'`: registers the target alongside the source and\n *    yields a single `'committed'` progress event.\n *  - `'auto-migrate'`: streams batches until the source is fully\n *    drained, then retires the source row.\n *\n * @stable\n */\nexport async function* migrateEmbedder(\n  options: MigrateEmbedderOptions,\n): AsyncGenerator<MigrationProgress, void, unknown> {\n  const { source, target, embeddings } = options;\n  const strategy = options.strategy ?? 'lock-on-first';\n  const sourceId = source.id();\n  const targetId = target.id();\n  const migrationId = `migration_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 7)}`;\n\n  if (sourceId === targetId) {\n    throw new EmbedderMigrationStateError(\n      `source and target embedders must differ; both resolved to '${sourceId}'.`,\n    );\n  }\n\n  const sourceMeta = embeddings.get(sourceId);\n  if (sourceMeta === null) {\n    throw new EmbedderMigrationStateError(\n      `source embedder '${sourceId}' is not registered. Run createMemory({ embedder: source }) first.`,\n    );\n  }\n\n  if (strategy === 'lock-on-first') {\n    throw new EmbedderMigrationLockedError(sourceId, targetId);\n  }\n\n  bindEmbedder(target, embeddings);\n\n  if (strategy === 'multi-active') {\n    yield {\n      kind: 'fact',\n      processed: 0,\n      total: 0,\n      source: sourceId,\n      target: targetId,\n      migrationId,\n      phase: 'committed',\n    };\n    return;\n  }\n\n  // strategy === 'auto-migrate'\n  if (options.nextBatch === undefined) {\n    throw new EmbedderMigrationStateError(\n      \"'auto-migrate' requires a `nextBatch` hook supplied by the storage adapter.\",\n    );\n  }\n\n  const batchSize = options.batchSize ?? 512;\n  const cap = options.maxRecordsPerKind ?? Number.POSITIVE_INFINITY;\n\n  for (const kind of ['fact', 'episode', 'message'] as const) {\n    let cursor: string | null = null;\n    let processed = 0;\n    while (processed < cap) {\n      if (options.signal?.aborted === true) {\n        yield {\n          kind,\n          processed,\n          total: processed,\n          source: sourceId,\n          target: targetId,\n          migrationId,\n          phase: 'aborted',\n        };\n        throw new EmbedderMigrationAbortedError(migrationId);\n      }\n      const batch = await options.nextBatch({\n        kind,\n        source: sourceId,\n        target: targetId,\n        batchSize,\n        cursor,\n      });\n      if (batch.rows.length === 0) break;\n      const texts = batch.rows.map((r) => r.text);\n      const vectors = await target.embed(texts, {\n        ...(options.signal !== undefined ? { signal: options.signal } : {}),\n      });\n      for (let i = 0; i < batch.rows.length; i++) {\n        const row = batch.rows[i];\n        const vector = vectors[i];\n        if (row === undefined || vector === undefined) continue;\n        await row.write(vector);\n      }\n      processed += batch.rows.length;\n      cursor = batch.nextCursor;\n      yield {\n        kind,\n        processed,\n        total: processed,\n        source: sourceId,\n        target: targetId,\n        migrationId,\n        phase: 'running',\n      };\n      if (cursor === null) break;\n    }\n  }\n\n  embeddings.retire(sourceId);\n  yield {\n    kind: 'fact',\n    processed: 0,\n    total: 0,\n    source: sourceId,\n    target: targetId,\n    migrationId,\n    phase: 'committed',\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AA8HA,gBAAuB,gBACrB,SACkD;CAClD,MAAM,EAAE,QAAQ,QAAQ,eAAe;CACvC,MAAM,WAAW,QAAQ,YAAY;CACrC,MAAM,WAAW,OAAO,IAAI;CAC5B,MAAM,WAAW,OAAO,IAAI;CAC5B,MAAM,cAAc,aAAa,KAAK,KAAK,CAAC,SAAS,GAAG,CAAC,GAAG,KAAK,QAAQ,CAAC,SAAS,GAAG,CAAC,MAAM,GAAG,EAAE;AAElG,KAAI,aAAa,SACf,OAAM,IAAI,4BACR,8DAA8D,SAAS,IACxE;AAIH,KADmB,WAAW,IAAI,SAAS,KACxB,KACjB,OAAM,IAAI,4BACR,oBAAoB,SAAS,oEAC9B;AAGH,KAAI,aAAa,gBACf,OAAM,IAAI,6BAA6B,UAAU,SAAS;AAG5D,cAAa,QAAQ,WAAW;AAEhC,KAAI,aAAa,gBAAgB;AAC/B,QAAM;GACJ,MAAM;GACN,WAAW;GACX,OAAO;GACP,QAAQ;GACR,QAAQ;GACR;GACA,OAAO;GACR;AACD;;AAIF,KAAI,QAAQ,cAAc,OACxB,OAAM,IAAI,4BACR,8EACD;CAGH,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,MAAM,QAAQ,qBAAqB,OAAO;AAEhD,MAAK,MAAM,QAAQ;EAAC;EAAQ;EAAW;EAAU,EAAW;EAC1D,IAAIA,SAAwB;EAC5B,IAAI,YAAY;AAChB,SAAO,YAAY,KAAK;AACtB,OAAI,QAAQ,QAAQ,YAAY,MAAM;AACpC,UAAM;KACJ;KACA;KACA,OAAO;KACP,QAAQ;KACR,QAAQ;KACR;KACA,OAAO;KACR;AACD,UAAM,IAAI,8BAA8B,YAAY;;GAEtD,MAAM,QAAQ,MAAM,QAAQ,UAAU;IACpC;IACA,QAAQ;IACR,QAAQ;IACR;IACA;IACD,CAAC;AACF,OAAI,MAAM,KAAK,WAAW,EAAG;GAC7B,MAAM,QAAQ,MAAM,KAAK,KAAK,MAAM,EAAE,KAAK;GAC3C,MAAM,UAAU,MAAM,OAAO,MAAM,OAAO,EACxC,GAAI,QAAQ,WAAW,SAAY,EAAE,QAAQ,QAAQ,QAAQ,GAAG,EAAE,EACnE,CAAC;AACF,QAAK,IAAI,IAAI,GAAG,IAAI,MAAM,KAAK,QAAQ,KAAK;IAC1C,MAAM,MAAM,MAAM,KAAK;IACvB,MAAM,SAAS,QAAQ;AACvB,QAAI,QAAQ,UAAa,WAAW,OAAW;AAC/C,UAAM,IAAI,MAAM,OAAO;;AAEzB,gBAAa,MAAM,KAAK;AACxB,YAAS,MAAM;AACf,SAAM;IACJ;IACA;IACA,OAAO;IACP,QAAQ;IACR,QAAQ;IACR;IACA,OAAO;IACR;AACD,OAAI,WAAW,KAAM;;;AAIzB,YAAW,OAAO,SAAS;AAC3B,OAAM;EACJ,MAAM;EACN,WAAW;EACX,OAAO;EACP,QAAQ;EACR,QAAQ;EACR;EACA,OAAO;EACR"}

package/dist/package.js

@@ -0,0 +1,6 @@
+//#region package.json
+var version = "0.6.1";
+
+//#endregion
+export { version };
+//# sourceMappingURL=package.js.map

package/dist/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","names":[],"sources":["../package.json"],"sourcesContent":["{\n  \"name\": \"@graphorin/memory\",\n  \"version\": \"0.6.1\",\n  \"description\": \"Six-tier memory system for the Graphorin framework: createMemory() facade with working / session / episodic / semantic / procedural / shared sub-modules, eleven memory tools wired into @graphorin/tools, hybrid vector + FTS5 search composed through Reciprocal Rank Fusion (k=60 default) with a pluggable reranker hook, a multi-stage conflict resolution pipeline (exact dedup → embedding three-zone → heuristic regex → subject/predicate → defer-to-deep) with an English locale pack default + plug-in locales, an embedder migration runner with three coexistence policies (lock-on-first / multi-active / auto-migrate), per-record embedder_id enforcement, multi-agent attribution, append-only writes with soft-delete + supersede semantics, default-on bi-temporal storage, provenance + quarantine safety gate for synthesized memory, AISpan emission for every operation, and tier-aware memory-modification guard wiring.\",\n  \"license\": \"MIT\",\n  \"author\": \"Oleksiy Stepurenko\",\n  \"homepage\": \"https://github.com/o-stepper/graphorin/tree/main/packages/memory\",\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/o-stepper/graphorin.git\",\n    \"directory\": \"packages/memory\"\n  },\n  \"bugs\": {\n    \"url\": \"https://github.com/o-stepper/graphorin/issues\"\n  },\n  \"keywords\": [\n    \"graphorin\",\n    \"ai\",\n    \"agents\",\n    \"framework\",\n    \"memory\",\n    \"long-term-memory\",\n    \"working-memory\",\n    \"session-memory\",\n    \"episodic-memory\",\n    \"semantic-memory\",\n    \"procedural-memory\",\n    \"shared-memory\",\n    \"rrf\",\n    \"hybrid-search\",\n    \"rerank\",\n    \"conflict-resolution\",\n    \"embedder-migration\",\n    \"bi-temporal\",\n    \"multi-agent\"\n  ],\n  \"type\": \"module\",\n  \"engines\": {\n    \"node\": \">=22.0.0\"\n  },\n  \"main\": \"./dist/index.js\",\n  \"module\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"import\": \"./dist/index.js\"\n    },\n    \"./facade\": {\n      \"types\": \"./dist/facade.d.ts\",\n      \"import\": \"./dist/facade.js\"\n    },\n    \"./tiers\": {\n      \"types\": \"./dist/tiers/index.d.ts\",\n      \"import\": \"./dist/tiers/index.js\"\n    },\n    \"./tools\": {\n      \"types\": \"./dist/tools/index.d.ts\",\n      \"import\": \"./dist/tools/index.js\"\n    },\n    \"./search\": {\n      \"types\": \"./dist/search/index.d.ts\",\n      \"import\": \"./dist/search/index.js\"\n    },\n    \"./conflict\": {\n      \"types\": \"./dist/conflict/index.d.ts\",\n      \"import\": \"./dist/conflict/index.js\"\n    },\n    \"./migration\": {\n      \"types\": \"./dist/migration/index.d.ts\",\n      \"import\": \"./dist/migration/index.js\"\n    },\n    \"./errors\": {\n      \"types\": \"./dist/errors/index.d.ts\",\n      \"import\": \"./dist/errors/index.js\"\n    },\n    \"./package.json\": \"./package.json\"\n  },\n  \"files\": [\n    \"dist\",\n    \"README.md\",\n    \"CHANGELOG.md\",\n    \"LICENSE\"\n  ],\n  \"scripts\": {\n    \"build\": \"tsdown\",\n    \"typecheck\": \"tsc --noEmit && tsc -p tsconfig.tests.json\",\n    \"test\": \"vitest run\",\n    \"lint\": \"biome check .\",\n    \"clean\": \"rimraf dist .turbo *.tsbuildinfo\"\n  },\n  \"dependencies\": {\n    \"@graphorin/core\": \"workspace:*\",\n    \"@graphorin/observability\": \"workspace:*\",\n    \"@graphorin/security\": \"workspace:*\",\n    \"@graphorin/tools\": \"workspace:*\"\n  },\n  \"peerDependencies\": {\n    \"zod\": \"^3.23.0 || ^4.0.0\"\n  },\n  \"peerDependenciesMeta\": {\n    \"zod\": {\n      \"optional\": false\n    }\n  },\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"provenance\": true\n  },\n  \"devDependencies\": {\n    \"@graphorin/store-sqlite\": \"workspace:*\",\n    \"@graphorin/embedder-transformersjs\": \"workspace:*\",\n    \"@graphorin/triggers\": \"workspace:*\",\n    \"@types/better-sqlite3\": \"^7.6.13\",\n    \"better-sqlite3\": \"^12.9.0\",\n    \"fast-check\": \"^3.23.0\",\n    \"zod\": \"^3.25.0\"\n  }\n}\n"],"mappings":";cAEa"}

package/dist/search/explain.d.ts

@@ -22,8 +22,11 @@ interface RecalledMemoryExplanation {
   /**
    * Raw per-signal scores contributing to `score`, exactly as the
    * pipeline recorded them on the hit: FTS (`bm25`), vector similarity
-   * (`vector`), the fused reciprocal-rank terms (`rrf` + per-list
-   * `rrf.list_N`), and the decay multiplier (`decay`) when decay ran.
+   * (`vector`), the fused reciprocal-rank terms (`rrf` plus one
+   * `rrf.<label>` entry per fused list keyed by the retriever kind,
+   * e.g. `rrf.fts` / `rrf.vector`, with `rrf.list_N` as the fallback
+   * when a list carries no label), and the decay multiplier (`decay`)
+   * when decay ran.
    */
   readonly signals: Readonly<Record<string, number>>;
 }
@@ -31,7 +34,7 @@ interface RecalledMemoryExplanation {
  * Structured "why was this recalled?" explanation for one
  * {@link SemanticMemory.search} call: the query, the reranker that
  * fused the candidate lists, and the per-memory signal breakdown in
- * final-rank order. Pure data — safe to attach to a span, log, or
+ * final-rank order. Pure data - safe to attach to a span, log, or
  * render. X-3.
  *
  * @stable
@@ -61,7 +64,7 @@ declare function explainRecall<TRecord extends MemoryRecord>(hits: ReadonlyArray
   readonly rerankerId: string;
 }): RecallExplanation;
 /**
- * Render a {@link RecallExplanation} as a compact ASCII block — a
+ * Render a {@link RecallExplanation} as a compact ASCII block - a
  * header line plus one line per recalled memory with its signal
  * breakdown. Pure (returns a string, no I/O); used by operator tooling
  * and trace inspectors.

package/dist/search/explain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"explain.d.ts","names":[],"sources":["../../src/search/explain.ts"],"sourcesContent":[],"mappings":";;;;AAwGA;;;;;;;;UA9EiB,yBAAA;;;;iBAIA;;;;;;;;;;;oBAWG,SAAS;;;;;;;;;;;UAYZ,iBAAA;;;;;;;;oBAQG,cAAc;;;;;;;;;;;;iBAalB,8BAA8B,oBACtC,cAAc,UAAU;;;IAE7B;;;;;;;;;iBA2Ba,uBAAA,cAAqC"}
+{"version":3,"file":"explain.d.ts","names":[],"sources":["../../src/search/explain.ts"],"sourcesContent":[],"mappings":";;;;AA2GA;;;;;;;;UAjFiB,yBAAA;;;;iBAIA;;;;;;;;;;;;;;oBAcG,SAAS;;;;;;;;;;;UAYZ,iBAAA;;;;;;;;oBAQG,cAAc;;;;;;;;;;;;iBAalB,8BAA8B,oBACtC,cAAc,UAAU;;;IAE7B;;;;;;;;;iBA2Ba,uBAAA,cAAqC"}

package/dist/search/explain.js

@@ -25,7 +25,7 @@ function explainRecall(hits, opts) {
 	});
 }
 /**
-* Render a {@link RecallExplanation} as a compact ASCII block — a
+* Render a {@link RecallExplanation} as a compact ASCII block - a
 * header line plus one line per recalled memory with its signal
 * breakdown. Pure (returns a string, no I/O); used by operator tooling
 * and trace inspectors.

package/dist/search/explain.js.map

@@ -1 +1 @@
-{"version":3,"file":"explain.js","names":[],"sources":["../../src/search/explain.ts"],"sourcesContent":["/**\n * Recall explainability for `@graphorin/memory` — \"why was this\n * recalled?\" (X-3). Turns the per-signal scores the hybrid pipeline\n * already records on each {@link MemoryHit} (FTS `bm25`, vector\n * similarity, the fused reciprocal-rank term, the decay multiplier,\n * future graph-hop terms) into a structured, renderable explanation.\n *\n * Pure data: the builder re-uses whatever {@link MemoryHit.signals} the\n * pipeline left behind rather than re-deriving them, so the explanation\n * always matches the ranking that actually happened. The renderer\n * returns a string and performs no I/O, so the explanation can be\n * attached to a span, logged, or surfaced by operator tooling.\n *\n * @packageDocumentation\n */\n\nimport type { MemoryHit, MemoryKind, MemoryRecord } from '@graphorin/core';\n\n/**\n * Per-memory contribution breakdown for one recalled record: the\n * decomposed signals the hybrid pipeline summed into the final score,\n * plus the record's final rank. Surfaces *why* a single memory was\n * recalled and how it ranked relative to its siblings.\n *\n * @stable\n */\nexport interface RecalledMemoryExplanation {\n  /** Record id (fact / episode / insight / …). */\n  readonly id: string;\n  /** Memory kind of the recalled record. */\n  readonly kind: MemoryKind;\n  /** 1-based position in the final fused + decayed ranking. */\n  readonly rank: number;\n  /** Final score after fusion and (optional) decay. */\n  readonly score: number;\n  /**\n   * Raw per-signal scores contributing to `score`, exactly as the\n   * pipeline recorded them on the hit: FTS (`bm25`), vector similarity\n   * (`vector`), the fused reciprocal-rank terms (`rrf` + per-list\n   * `rrf.list_N`), and the decay multiplier (`decay`) when decay ran.\n   */\n  readonly signals: Readonly<Record<string, number>>;\n}\n\n/**\n * Structured \"why was this recalled?\" explanation for one\n * {@link SemanticMemory.search} call: the query, the reranker that\n * fused the candidate lists, and the per-memory signal breakdown in\n * final-rank order. Pure data — safe to attach to a span, log, or\n * render. X-3.\n *\n * @stable\n */\nexport interface RecallExplanation {\n  /** The query the recall ran for. */\n  readonly query: string;\n  /** Stable id of the reranker that fused the candidate lists. */\n  readonly rerankerId: string;\n  /** Number of recalled memories explained. */\n  readonly count: number;\n  /** Per-memory breakdown, in final-rank order (rank 1 first). */\n  readonly results: ReadonlyArray<RecalledMemoryExplanation>;\n}\n\n/**\n * Build a {@link RecallExplanation} from a ranked hit list. Pure and\n * deterministic: it surfaces whatever per-signal scores the hybrid\n * pipeline left on each {@link MemoryHit.signals} (FTS, vector, RRF,\n * decay, future graph-hop terms) without re-deriving them, so the\n * explanation always matches what actually drove the ranking. Hits are\n * assumed to be in final-rank order (as returned by `search`).\n *\n * @stable\n */\nexport function explainRecall<TRecord extends MemoryRecord>(\n  hits: ReadonlyArray<MemoryHit<TRecord>>,\n  opts: { readonly query: string; readonly rerankerId: string },\n): RecallExplanation {\n  const results = hits.map(\n    (hit, idx): RecalledMemoryExplanation =>\n      Object.freeze({\n        id: hit.record.id,\n        kind: hit.record.kind,\n        rank: idx + 1,\n        score: hit.score,\n        signals: Object.freeze({ ...(hit.signals ?? {}) }),\n      }),\n  );\n  return Object.freeze({\n    query: opts.query,\n    rerankerId: opts.rerankerId,\n    count: results.length,\n    results: Object.freeze(results),\n  });\n}\n\n/**\n * Render a {@link RecallExplanation} as a compact ASCII block — a\n * header line plus one line per recalled memory with its signal\n * breakdown. Pure (returns a string, no I/O); used by operator tooling\n * and trace inspectors.\n *\n * @stable\n */\nexport function formatRecallExplanation(explanation: RecallExplanation): string {\n  const header = `recall ${JSON.stringify(explanation.query)} via ${explanation.rerankerId} -> ${explanation.count} result(s)`;\n  if (explanation.results.length === 0) return header;\n  const lines = explanation.results.map((r) => {\n    const signals = Object.entries(r.signals)\n      .map(([key, value]) => `${key}=${formatScore(value)}`)\n      .join(' ');\n    const suffix = signals === '' ? '' : ` (${signals})`;\n    return `  #${r.rank} ${r.id} [${r.kind}] score=${formatScore(r.score)}${suffix}`;\n  });\n  return [header, ...lines].join('\\n');\n}\n\nfunction formatScore(value: number): string {\n  return Number.isFinite(value) ? value.toFixed(4) : String(value);\n}\n"],"mappings":";;;;;;;;;;;AA0EA,SAAgB,cACd,MACA,MACmB;CACnB,MAAM,UAAU,KAAK,KAClB,KAAK,QACJ,OAAO,OAAO;EACZ,IAAI,IAAI,OAAO;EACf,MAAM,IAAI,OAAO;EACjB,MAAM,MAAM;EACZ,OAAO,IAAI;EACX,SAAS,OAAO,OAAO,EAAE,GAAI,IAAI,WAAW,EAAE,EAAG,CAAC;EACnD,CAAC,CACL;AACD,QAAO,OAAO,OAAO;EACnB,OAAO,KAAK;EACZ,YAAY,KAAK;EACjB,OAAO,QAAQ;EACf,SAAS,OAAO,OAAO,QAAQ;EAChC,CAAC;;;;;;;;;;AAWJ,SAAgB,wBAAwB,aAAwC;CAC9E,MAAM,SAAS,UAAU,KAAK,UAAU,YAAY,MAAM,CAAC,OAAO,YAAY,WAAW,MAAM,YAAY,MAAM;AACjH,KAAI,YAAY,QAAQ,WAAW,EAAG,QAAO;AAQ7C,QAAO,CAAC,QAAQ,GAPF,YAAY,QAAQ,KAAK,MAAM;EAC3C,MAAM,UAAU,OAAO,QAAQ,EAAE,QAAQ,CACtC,KAAK,CAAC,KAAK,WAAW,GAAG,IAAI,GAAG,YAAY,MAAM,GAAG,CACrD,KAAK,IAAI;EACZ,MAAM,SAAS,YAAY,KAAK,KAAK,KAAK,QAAQ;AAClD,SAAO,MAAM,EAAE,KAAK,GAAG,EAAE,GAAG,IAAI,EAAE,KAAK,UAAU,YAAY,EAAE,MAAM,GAAG;GACxE,CACuB,CAAC,KAAK,KAAK;;AAGtC,SAAS,YAAY,OAAuB;AAC1C,QAAO,OAAO,SAAS,MAAM,GAAG,MAAM,QAAQ,EAAE,GAAG,OAAO,MAAM"}
+{"version":3,"file":"explain.js","names":[],"sources":["../../src/search/explain.ts"],"sourcesContent":["/**\n * Recall explainability for `@graphorin/memory` - \"why was this\n * recalled?\" (X-3). Turns the per-signal scores the hybrid pipeline\n * already records on each {@link MemoryHit} (FTS `bm25`, vector\n * similarity, the fused reciprocal-rank term, the decay multiplier,\n * future graph-hop terms) into a structured, renderable explanation.\n *\n * Pure data: the builder re-uses whatever {@link MemoryHit.signals} the\n * pipeline left behind rather than re-deriving them, so the explanation\n * always matches the ranking that actually happened. The renderer\n * returns a string and performs no I/O, so the explanation can be\n * attached to a span, logged, or surfaced by operator tooling.\n *\n * @packageDocumentation\n */\n\nimport type { MemoryHit, MemoryKind, MemoryRecord } from '@graphorin/core';\n\n/**\n * Per-memory contribution breakdown for one recalled record: the\n * decomposed signals the hybrid pipeline summed into the final score,\n * plus the record's final rank. Surfaces *why* a single memory was\n * recalled and how it ranked relative to its siblings.\n *\n * @stable\n */\nexport interface RecalledMemoryExplanation {\n  /** Record id (fact / episode / insight / …). */\n  readonly id: string;\n  /** Memory kind of the recalled record. */\n  readonly kind: MemoryKind;\n  /** 1-based position in the final fused + decayed ranking. */\n  readonly rank: number;\n  /** Final score after fusion and (optional) decay. */\n  readonly score: number;\n  /**\n   * Raw per-signal scores contributing to `score`, exactly as the\n   * pipeline recorded them on the hit: FTS (`bm25`), vector similarity\n   * (`vector`), the fused reciprocal-rank terms (`rrf` plus one\n   * `rrf.<label>` entry per fused list keyed by the retriever kind,\n   * e.g. `rrf.fts` / `rrf.vector`, with `rrf.list_N` as the fallback\n   * when a list carries no label), and the decay multiplier (`decay`)\n   * when decay ran.\n   */\n  readonly signals: Readonly<Record<string, number>>;\n}\n\n/**\n * Structured \"why was this recalled?\" explanation for one\n * {@link SemanticMemory.search} call: the query, the reranker that\n * fused the candidate lists, and the per-memory signal breakdown in\n * final-rank order. Pure data - safe to attach to a span, log, or\n * render. X-3.\n *\n * @stable\n */\nexport interface RecallExplanation {\n  /** The query the recall ran for. */\n  readonly query: string;\n  /** Stable id of the reranker that fused the candidate lists. */\n  readonly rerankerId: string;\n  /** Number of recalled memories explained. */\n  readonly count: number;\n  /** Per-memory breakdown, in final-rank order (rank 1 first). */\n  readonly results: ReadonlyArray<RecalledMemoryExplanation>;\n}\n\n/**\n * Build a {@link RecallExplanation} from a ranked hit list. Pure and\n * deterministic: it surfaces whatever per-signal scores the hybrid\n * pipeline left on each {@link MemoryHit.signals} (FTS, vector, RRF,\n * decay, future graph-hop terms) without re-deriving them, so the\n * explanation always matches what actually drove the ranking. Hits are\n * assumed to be in final-rank order (as returned by `search`).\n *\n * @stable\n */\nexport function explainRecall<TRecord extends MemoryRecord>(\n  hits: ReadonlyArray<MemoryHit<TRecord>>,\n  opts: { readonly query: string; readonly rerankerId: string },\n): RecallExplanation {\n  const results = hits.map(\n    (hit, idx): RecalledMemoryExplanation =>\n      Object.freeze({\n        id: hit.record.id,\n        kind: hit.record.kind,\n        rank: idx + 1,\n        score: hit.score,\n        signals: Object.freeze({ ...(hit.signals ?? {}) }),\n      }),\n  );\n  return Object.freeze({\n    query: opts.query,\n    rerankerId: opts.rerankerId,\n    count: results.length,\n    results: Object.freeze(results),\n  });\n}\n\n/**\n * Render a {@link RecallExplanation} as a compact ASCII block - a\n * header line plus one line per recalled memory with its signal\n * breakdown. Pure (returns a string, no I/O); used by operator tooling\n * and trace inspectors.\n *\n * @stable\n */\nexport function formatRecallExplanation(explanation: RecallExplanation): string {\n  const header = `recall ${JSON.stringify(explanation.query)} via ${explanation.rerankerId} -> ${explanation.count} result(s)`;\n  if (explanation.results.length === 0) return header;\n  const lines = explanation.results.map((r) => {\n    const signals = Object.entries(r.signals)\n      .map(([key, value]) => `${key}=${formatScore(value)}`)\n      .join(' ');\n    const suffix = signals === '' ? '' : ` (${signals})`;\n    return `  #${r.rank} ${r.id} [${r.kind}] score=${formatScore(r.score)}${suffix}`;\n  });\n  return [header, ...lines].join('\\n');\n}\n\nfunction formatScore(value: number): string {\n  return Number.isFinite(value) ? value.toFixed(4) : String(value);\n}\n"],"mappings":";;;;;;;;;;;AA6EA,SAAgB,cACd,MACA,MACmB;CACnB,MAAM,UAAU,KAAK,KAClB,KAAK,QACJ,OAAO,OAAO;EACZ,IAAI,IAAI,OAAO;EACf,MAAM,IAAI,OAAO;EACjB,MAAM,MAAM;EACZ,OAAO,IAAI;EACX,SAAS,OAAO,OAAO,EAAE,GAAI,IAAI,WAAW,EAAE,EAAG,CAAC;EACnD,CAAC,CACL;AACD,QAAO,OAAO,OAAO;EACnB,OAAO,KAAK;EACZ,YAAY,KAAK;EACjB,OAAO,QAAQ;EACf,SAAS,OAAO,OAAO,QAAQ;EAChC,CAAC;;;;;;;;;;AAWJ,SAAgB,wBAAwB,aAAwC;CAC9E,MAAM,SAAS,UAAU,KAAK,UAAU,YAAY,MAAM,CAAC,OAAO,YAAY,WAAW,MAAM,YAAY,MAAM;AACjH,KAAI,YAAY,QAAQ,WAAW,EAAG,QAAO;AAQ7C,QAAO,CAAC,QAAQ,GAPF,YAAY,QAAQ,KAAK,MAAM;EAC3C,MAAM,UAAU,OAAO,QAAQ,EAAE,QAAQ,CACtC,KAAK,CAAC,KAAK,WAAW,GAAG,IAAI,GAAG,YAAY,MAAM,GAAG,CACrD,KAAK,IAAI;EACZ,MAAM,SAAS,YAAY,KAAK,KAAK,KAAK,QAAQ;AAClD,SAAO,MAAM,EAAE,KAAK,GAAG,EAAE,GAAG,IAAI,EAAE,KAAK,UAAU,YAAY,EAAE,MAAM,GAAG;GACxE,CACuB,CAAC,KAAK,KAAK;;AAGtC,SAAS,YAAY,OAAuB;AAC1C,QAAO,OAAO,SAAS,MAAM,GAAG,MAAM,QAAQ,EAAE,GAAG,OAAO,MAAM"}

package/dist/search/fit-weights.d.ts

@@ -0,0 +1,48 @@
+import { MemoryHit, MemoryRecord } from "@graphorin/core";
+
+//#region src/search/fit-weights.d.ts
+
+/** One labelled query: per-kind candidate lists + the relevant ids. */
+interface FitFusionCase<TRecord extends MemoryRecord = MemoryRecord> {
+  /** FTS candidate list, best-first (as the store returns it). */
+  readonly fts: ReadonlyArray<MemoryHit<TRecord>>;
+  /** Vector candidate list, best-first. */
+  readonly vector: ReadonlyArray<MemoryHit<TRecord>>;
+  /** Ids judged relevant for this query (binary gain). */
+  readonly relevantIds: ReadonlyArray<string>;
+}
+/** Options for {@link fitFusionWeights}. */
+interface FitFusionOptions {
+  /** Candidate weight values per axis. Default `[0.25, 0.5, 1, 2, 4]`. */
+  readonly grid?: ReadonlyArray<number>;
+  /** nDCG cutoff. Default `10`. */
+  readonly k?: number;
+  /** RRF constant forwarded to the fuse. Default `60`. */
+  readonly rrfK?: number;
+}
+/** Result of a fit: the winning weights + its score and the RRF baseline. */
+interface FitFusionResult {
+  readonly weights: {
+    readonly fts: number;
+    readonly vector: number;
+  };
+  /** Mean nDCG@k of the winning weights across the cases. */
+  readonly score: number;
+  /** Mean nDCG@k of unit weights (plain RRF) - compare before adopting. */
+  readonly baseline: number;
+}
+/**
+ * Binary-gain nDCG@k over a ranked id list.
+ *
+ * @stable
+ */
+declare function ndcgAtK(rankedIds: ReadonlyArray<string>, relevant: ReadonlySet<string>, k: number): number;
+/**
+ * Grid-search fusion weights against labelled cases (C5).
+ *
+ * @stable
+ */
+declare function fitFusionWeights<TRecord extends MemoryRecord = MemoryRecord>(cases: ReadonlyArray<FitFusionCase<TRecord>>, options?: FitFusionOptions): FitFusionResult;
+//#endregion
+export { FitFusionCase, FitFusionOptions, FitFusionResult, fitFusionWeights, ndcgAtK };
+//# sourceMappingURL=fit-weights.d.ts.map

package/dist/search/fit-weights.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fit-weights.d.ts","names":[],"sources":["../../src/search/fit-weights.ts"],"sourcesContent":[],"mappings":";;;;AA4EA;AAAiD,UAvDhC,aAuDgC,CAAA,gBAvDF,YAuDE,GAvDa,YAuDb,CAAA,CAAA;EAAe;EAC3B,SAAA,GAAA,EAtDrB,aAsDqB,CAtDP,SAsDO,CAtDG,OAsDH,CAAA,CAAA;EAAd;EAAd,SAAA,MAAA,EApDU,aAoDV,CApDwB,SAoDxB,CApDkC,OAoDlC,CAAA,CAAA;EACE;EACR,SAAA,WAAA,EApDqB,aAoDrB,CAAA,MAAA,CAAA;;;UAhDc,gBAAA;;kBAEC;;;;;;;UAQD,eAAA;;;;;;;;;;;;;;;iBAaD,OAAA,YACH,iCACD;;;;;;iBAoBI,iCAAiC,eAAe,qBACvD,cAAc,cAAc,qBAC1B,mBACR"}

package/dist/search/fit-weights.js

@@ -0,0 +1,70 @@
+import { fuseWeighted } from "./rrf.js";
+
+//#region src/search/fit-weights.ts
+/**
+* Binary-gain nDCG@k over a ranked id list.
+*
+* @stable
+*/
+function ndcgAtK(rankedIds, relevant, k) {
+	const cutoff = Math.min(k, rankedIds.length);
+	let dcg = 0;
+	for (let i = 0; i < cutoff; i++) {
+		const id = rankedIds[i];
+		if (id !== void 0 && relevant.has(id)) dcg += 1 / Math.log2(i + 2);
+	}
+	const idealHits = Math.min(relevant.size, k);
+	let idcg = 0;
+	for (let i = 0; i < idealHits; i++) idcg += 1 / Math.log2(i + 2);
+	return idcg === 0 ? 0 : dcg / idcg;
+}
+/**
+* Grid-search fusion weights against labelled cases (C5).
+*
+* @stable
+*/
+function fitFusionWeights(cases, options = {}) {
+	if (cases.length === 0) throw new TypeError("[graphorin/memory] fitFusionWeights: at least one labelled case required");
+	const grid = options.grid ?? [
+		.25,
+		.5,
+		1,
+		2,
+		4
+	];
+	const k = options.k ?? 10;
+	const rrfK = options.rrfK ?? 60;
+	const meanNdcg = (wFts, wVector) => {
+		let total = 0;
+		for (const c of cases) {
+			const rankedIds = fuseWeighted([c.fts, c.vector], [wFts, wVector], rrfK).map((h) => h.record.id);
+			total += ndcgAtK(rankedIds, new Set(c.relevantIds), k);
+		}
+		return total / cases.length;
+	};
+	const baseline = meanNdcg(1, 1);
+	let best = {
+		weights: {
+			fts: 1,
+			vector: 1
+		},
+		score: baseline,
+		baseline
+	};
+	for (const wFts of grid) for (const wVector of grid) {
+		const score = meanNdcg(wFts, wVector);
+		if (score > best.score + 1e-12) best = {
+			weights: {
+				fts: wFts,
+				vector: wVector
+			},
+			score,
+			baseline
+		};
+	}
+	return best;
+}
+
+//#endregion
+export { fitFusionWeights, ndcgAtK };
+//# sourceMappingURL=fit-weights.js.map

package/dist/search/fit-weights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fit-weights.js","names":["best: FitFusionResult"],"sources":["../../src/search/fit-weights.ts"],"sourcesContent":["/**\n * C5: offline fusion-weight fitting. Tuned convex/weighted fusion beats\n * RRF with a handful of labelled queries (Bruch et al., TOIS 2023) - this\n * module turns that into a small, pure routine: grid-search\n * {@link FusionWeights} over labelled cases and return the setting that\n * maximizes mean nDCG@k, together with the plain-RRF baseline so the\n * caller can see whether tuning actually paid.\n *\n * Pure and I/O-free: the caller supplies per-kind candidate lists (run\n * your FTS and vector retrievers once per query, offline) plus the ids\n * judged relevant. Feed the winning weights to\n * `search(..., { fusion: { strategy: 'weighted', weights } })` or a\n * process-default `WeightedRRFReranker`.\n *\n * @packageDocumentation\n */\n\nimport type { MemoryHit, MemoryRecord } from '@graphorin/core';\nimport { fuseWeighted } from './rrf.js';\n\n/** One labelled query: per-kind candidate lists + the relevant ids. */\nexport interface FitFusionCase<TRecord extends MemoryRecord = MemoryRecord> {\n  /** FTS candidate list, best-first (as the store returns it). */\n  readonly fts: ReadonlyArray<MemoryHit<TRecord>>;\n  /** Vector candidate list, best-first. */\n  readonly vector: ReadonlyArray<MemoryHit<TRecord>>;\n  /** Ids judged relevant for this query (binary gain). */\n  readonly relevantIds: ReadonlyArray<string>;\n}\n\n/** Options for {@link fitFusionWeights}. */\nexport interface FitFusionOptions {\n  /** Candidate weight values per axis. Default `[0.25, 0.5, 1, 2, 4]`. */\n  readonly grid?: ReadonlyArray<number>;\n  /** nDCG cutoff. Default `10`. */\n  readonly k?: number;\n  /** RRF constant forwarded to the fuse. Default `60`. */\n  readonly rrfK?: number;\n}\n\n/** Result of a fit: the winning weights + its score and the RRF baseline. */\nexport interface FitFusionResult {\n  readonly weights: { readonly fts: number; readonly vector: number };\n  /** Mean nDCG@k of the winning weights across the cases. */\n  readonly score: number;\n  /** Mean nDCG@k of unit weights (plain RRF) - compare before adopting. */\n  readonly baseline: number;\n}\n\n/**\n * Binary-gain nDCG@k over a ranked id list.\n *\n * @stable\n */\nexport function ndcgAtK(\n  rankedIds: ReadonlyArray<string>,\n  relevant: ReadonlySet<string>,\n  k: number,\n): number {\n  const cutoff = Math.min(k, rankedIds.length);\n  let dcg = 0;\n  for (let i = 0; i < cutoff; i++) {\n    const id = rankedIds[i];\n    if (id !== undefined && relevant.has(id)) dcg += 1 / Math.log2(i + 2);\n  }\n  const idealHits = Math.min(relevant.size, k);\n  let idcg = 0;\n  for (let i = 0; i < idealHits; i++) idcg += 1 / Math.log2(i + 2);\n  return idcg === 0 ? 0 : dcg / idcg;\n}\n\n/**\n * Grid-search fusion weights against labelled cases (C5).\n *\n * @stable\n */\nexport function fitFusionWeights<TRecord extends MemoryRecord = MemoryRecord>(\n  cases: ReadonlyArray<FitFusionCase<TRecord>>,\n  options: FitFusionOptions = {},\n): FitFusionResult {\n  if (cases.length === 0) {\n    throw new TypeError('[graphorin/memory] fitFusionWeights: at least one labelled case required');\n  }\n  const grid = options.grid ?? [0.25, 0.5, 1, 2, 4];\n  const k = options.k ?? 10;\n  const rrfK = options.rrfK ?? 60;\n\n  const meanNdcg = (wFts: number, wVector: number): number => {\n    let total = 0;\n    for (const c of cases) {\n      const fused = fuseWeighted([c.fts, c.vector], [wFts, wVector], rrfK);\n      const rankedIds = fused.map((h) => h.record.id);\n      total += ndcgAtK(rankedIds, new Set(c.relevantIds), k);\n    }\n    return total / cases.length;\n  };\n\n  const baseline = meanNdcg(1, 1);\n  let best: FitFusionResult = { weights: { fts: 1, vector: 1 }, score: baseline, baseline };\n  for (const wFts of grid) {\n    for (const wVector of grid) {\n      const score = meanNdcg(wFts, wVector);\n      if (score > best.score + 1e-12) {\n        best = { weights: { fts: wFts, vector: wVector }, score, baseline };\n      }\n    }\n  }\n  return best;\n}\n"],"mappings":";;;;;;;;AAsDA,SAAgB,QACd,WACA,UACA,GACQ;CACR,MAAM,SAAS,KAAK,IAAI,GAAG,UAAU,OAAO;CAC5C,IAAI,MAAM;AACV,MAAK,IAAI,IAAI,GAAG,IAAI,QAAQ,KAAK;EAC/B,MAAM,KAAK,UAAU;AACrB,MAAI,OAAO,UAAa,SAAS,IAAI,GAAG,CAAE,QAAO,IAAI,KAAK,KAAK,IAAI,EAAE;;CAEvE,MAAM,YAAY,KAAK,IAAI,SAAS,MAAM,EAAE;CAC5C,IAAI,OAAO;AACX,MAAK,IAAI,IAAI,GAAG,IAAI,WAAW,IAAK,SAAQ,IAAI,KAAK,KAAK,IAAI,EAAE;AAChE,QAAO,SAAS,IAAI,IAAI,MAAM;;;;;;;AAQhC,SAAgB,iBACd,OACA,UAA4B,EAAE,EACb;AACjB,KAAI,MAAM,WAAW,EACnB,OAAM,IAAI,UAAU,2EAA2E;CAEjG,MAAM,OAAO,QAAQ,QAAQ;EAAC;EAAM;EAAK;EAAG;EAAG;EAAE;CACjD,MAAM,IAAI,QAAQ,KAAK;CACvB,MAAM,OAAO,QAAQ,QAAQ;CAE7B,MAAM,YAAY,MAAc,YAA4B;EAC1D,IAAI,QAAQ;AACZ,OAAK,MAAM,KAAK,OAAO;GAErB,MAAM,YADQ,aAAa,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,MAAM,QAAQ,EAAE,KAAK,CAC5C,KAAK,MAAM,EAAE,OAAO,GAAG;AAC/C,YAAS,QAAQ,WAAW,IAAI,IAAI,EAAE,YAAY,EAAE,EAAE;;AAExD,SAAO,QAAQ,MAAM;;CAGvB,MAAM,WAAW,SAAS,GAAG,EAAE;CAC/B,IAAIA,OAAwB;EAAE,SAAS;GAAE,KAAK;GAAG,QAAQ;GAAG;EAAE,OAAO;EAAU;EAAU;AACzF,MAAK,MAAM,QAAQ,KACjB,MAAK,MAAM,WAAW,MAAM;EAC1B,MAAM,QAAQ,SAAS,MAAM,QAAQ;AACrC,MAAI,QAAQ,KAAK,QAAQ,MACvB,QAAO;GAAE,SAAS;IAAE,KAAK;IAAM,QAAQ;IAAS;GAAE;GAAO;GAAU;;AAIzE,QAAO"}