@noy-db/hub 0.2.0-pre.9 → 0.3.0-pre.10

package/dist/chunk-7P2SDJG3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-audit/tiers/active.ts","../src/with-audit/tiers/strategy.ts","../src/with-audit/tiers/index.ts"],"sourcesContent":["/**\n * Enable the hierarchical-tiers capability.\n * Pass to `createNoydb({ tiersStrategy: withTiers() })` to make a collection's\n * `putAtTier` / `getAtTier` / `listAtTier` / `elevate` / `demote` methods live.\n * The tier read/write/re-key engine is dynamically imported here, so it stays\n * out of the floor bundle until opted in.\n */\nimport type { TiersStrategy } from './strategy.js'\n\nexport function withTiers(): TiersStrategy {\n  return {\n    async putAtTier(ctx, id, record, tier, opts) {\n      const { putAtTier } = await import('./index.js')\n      return putAtTier(ctx, id, record, tier, opts)\n    },\n    async getAtTier(ctx, id) {\n      const { getAtTier } = await import('./index.js')\n      return getAtTier(ctx, id)\n    },\n    async listAtTier(ctx) {\n      const { listAtTier } = await import('./index.js')\n      return listAtTier(ctx)\n    },\n    async elevate(ctx, id, toTier) {\n      const { elevate } = await import('./index.js')\n      return elevate(ctx, id, toTier)\n    },\n    async demote(ctx, id, toTier) {\n      const { demote } = await import('./index.js')\n      return demote(ctx, id, toTier)\n    },\n  }\n}\n","/**\n * Tiers capability strategy — the five on-demand collection-level tier\n * operations the `Collection` routes through. The active engine\n * ({@link withTiers}) dynamically imports the tier cores (keeping them out of\n * the floor bundle); {@link NO_TIERS} throws. Collection always builds its\n * per-call {@link TiersContext} and delegates here, so an un-opted-in caller\n * hits `NO_TIERS`'s throw.\n * @internal\n */\nimport type { GhostRecord } from '../../kernel/types.js'\nimport type { TiersContext } from './index.js'\nimport { TiersNotEnabledError } from '../../kernel/errors.js'\n\nexport interface TiersStrategy {\n  putAtTier<T>(\n    ctx: TiersContext<T>,\n    id: string,\n    record: T,\n    tier: number,\n    opts?: { elevation?: { reason: string; fromTier: number }; source?: string; sourceTs?: string },\n  ): Promise<void>\n  getAtTier<T>(ctx: TiersContext<T>, id: string): Promise<T | GhostRecord | null>\n  listAtTier<T>(ctx: TiersContext<T>): Promise<Array<{ id: string; tier: number; readable: boolean }>>\n  elevate<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>\n  demote<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>\n}\n\n/**\n * No-op stub — the floor default. Every capability method throws\n * {@link TiersNotEnabledError}; opt in with `tiersStrategy: withTiers()` in\n * createNoydb. @internal\n */\nexport const NO_TIERS: TiersStrategy = {\n  async putAtTier() { throw new TiersNotEnabledError() },\n  async getAtTier() { throw new TiersNotEnabledError() },\n  async listAtTier() { throw new TiersNotEnabledError() },\n  async elevate() { throw new TiersNotEnabledError() },\n  async demote() { throw new TiersNotEnabledError() },\n}\n","/**\n * Hierarchical access — the collection-level tier operations\n * (`putAtTier` / `getAtTier` / `listAtTier` / `elevate` / `demote`).\n *\n * A collection opted into `{ tiers: [...] }` stamps `_tier: N` on each envelope\n * and encrypts its body under the tier-N DEK. These helpers are the read/write\n * surface for that scheme: write at a tier, read with tier-aware visibility\n * (invisibility vs. ghost), and move a record up (`elevate`) or down (`demote`)\n * the tier ladder by re-wrapping its body key.\n *\n * Each function takes a small {@link TiersContext} (the exact `this.*` the\n * moving methods touched) instead of `this`, mirroring the `record-keys/`\n * siblings. Behaviour is byte-identical to the inline code it replaced.\n *\n * The crux is `cekCache`: `elevate`/`demote`/`getAtTier` write the SAME `Lru`\n * reference `Collection` owns (never a copy) so a per-record CEK re-wrap stays\n * synchronous with the cache the kernel's write/read path also mutates. The\n * cross-tier event sink stays collection-resident and is reached via the\n * `emitCrossTierEvent` callback.\n *\n * Internal service — not exported as a `@noy-db/hub/*` subpath.\n */\nexport { withTiers } from './active.js'\nexport { NO_TIERS, type TiersStrategy } from './strategy.js'\nexport { TiersNotEnabledError } from '../../kernel/errors.js'\nimport { encrypt, decrypt, unwrapCek, rewrapBodyToDek, type RecordCodec, type EnclaveKey, type SealedShredSlot } from '../../kernel/enclave/index.js'\nimport { TierDemoteDeniedError } from '../../kernel/errors.js'\nimport { dekKey, assertTierAccess } from '../../with-party/team/tiers.js'\nimport type { UnlockedKeyring } from '../../with-party/team/keyring.js'\nimport type { Lru } from '../../kernel/cache/index.js'\nimport {\n  NOYDB_FORMAT_VERSION,\n  type NoydbStore,\n  type EncryptedEnvelope,\n  type GhostRecord,\n  type TierMode,\n  type CrossTierAccessEvent,\n} from '../../kernel/types.js'\n\n/** Everything the moving tier methods touched on `this.*`, as a flat context. */\nexport interface TiersContext<T> {\n  /** Collection name — the crypto AAD scope and tier-DEK key prefix. */\n  readonly name: string\n  /** Vault namespace the records live under. */\n  readonly vault: string\n  /** The ciphertext store. */\n  readonly adapter: NoydbStore\n  /** The caller's unlocked keyring (tier-DEK holdings + role + userId). */\n  readonly keyring: UnlockedKeyring\n  /** The record codec — decrypts a tier-0 envelope to T. */\n  readonly codec: RecordCodec<T>\n  /**\n   * The collection's per-record CEK cache (SHARED reference, not a copy).\n   * `elevate`/`demote`/`getAtTier` re-wrap a record's CEK and `set` it here so\n   * the move stays synchronous with the cache the kernel's read/write path\n   * owns. `null` → no caching.\n   */\n  readonly cekCache: Lru<string, EnclaveKey> | null\n  /** Emit `_source`/`_sourceTs` provenance fields when a source is supplied. */\n  readonly provenance: boolean\n  /** Declared tiers, or null when the feature is off. */\n  readonly tiers: ReadonlySet<number> | null\n  /** Above-tier read visibility mode (`'invisibility'` | `'ghost'`). */\n  readonly tierMode: TierMode\n  /** Resolve a tier DEK by its `dekKey(name, tier)`. */\n  getDEK(key: string): Promise<EnclaveKey>\n  /** Fire a cross-tier access event (sink stays collection-resident). */\n  emitCrossTierEvent(event: CrossTierAccessEvent): void\n}\n\nexport function assertTiersEnabled<T>(ctx: TiersContext<T>): void {\n  if (!ctx.tiers) {\n    throw new Error(\n      `Collection \"${ctx.name}\": hierarchical tiers are not enabled. ` +\n      `Pass { tiers: [0, 1, 2, …] } to vault.collection() to opt in.`,\n    )\n  }\n}\n\nexport function assertDeclaredTier<T>(ctx: TiersContext<T>, tier: number): void {\n  if (tier < 0 || !Number.isInteger(tier)) {\n    throw new Error(`Collection \"${ctx.name}\": tier must be a non-negative integer, got ${tier}`)\n  }\n  if (tier === 0) return\n  if (!ctx.tiers || !ctx.tiers.has(tier)) {\n    throw new Error(\n      `Collection \"${ctx.name}\": tier ${tier} is not declared in { tiers: [...] }`,\n    )\n  }\n}\n\nfunction isElevatorOrOwner<T>(ctx: TiersContext<T>): boolean {\n  return ctx.keyring.role === 'owner' || ctx.keyring.role === 'admin'\n}\n\n/**\n * tier-aware put. Encrypts the record with the collection's tier-N DEK and\n * stamps `_tier: N` on the envelope. The caller's keyring must hold the tier-N\n * DEK (directly, by delegation, or by virtue of being the grantor); otherwise\n * throws `TierNotGrantedError`.\n *\n * accepts an optional `elevation` context. When present, the emitted cross-tier\n * event is stamped with `authorization: 'elevation'`, the elevation's reason,\n * and the caller's pre-elevation tier. `vault.elevate(...).collection().put`\n * threads this through; direct `putAtTier` calls leave it undefined and fall\n * back to the inherent-write event shape.\n */\nexport async function putAtTier<T>(\n  ctx: TiersContext<T>,\n  id: string,\n  record: T,\n  tier: number,\n  opts?: { elevation?: { reason: string; fromTier: number }; source?: string; sourceTs?: string },\n): Promise<void> {\n  assertTiersEnabled(ctx)\n  assertDeclaredTier(ctx, tier)\n  assertTierAccess(ctx.keyring, ctx.name, tier)\n\n  const key = dekKey(ctx.name, tier)\n  const dek = await ctx.getDEK(key)\n\n  const existing = await ctx.adapter.get(ctx.vault, ctx.name, id)\n  const version = existing ? existing._v + 1 : 1\n  const json = JSON.stringify(record)\n  const { iv, data } = await encrypt(json, dek)\n  const envelope: EncryptedEnvelope = {\n    _noydb: NOYDB_FORMAT_VERSION,\n    _v: version,\n    _ts: new Date().toISOString(),\n    _iv: iv,\n    _data: data,\n    _by: ctx.keyring.userId,\n    ...(tier > 0 && { _tier: tier }),\n    ...(ctx.provenance && opts?.source !== undefined ? { _source: opts.source, _sourceTs: opts.sourceTs ?? new Date().toISOString() } : {}),\n  }\n\n  await ctx.adapter.put(ctx.vault, ctx.name, id, envelope)\n\n  if (tier > 0) {\n    ctx.emitCrossTierEvent({\n      actor: ctx.keyring.userId,\n      collection: ctx.name,\n      id,\n      tier,\n      authorization: opts?.elevation ? 'elevation' : 'inherent',\n      op: 'put',\n      ts: envelope._ts,\n      ...(opts?.elevation && {\n        reason: opts.elevation.reason,\n        elevatedFrom: opts.elevation.fromTier,\n      }),\n    })\n  }\n}\n\n/**\n * tier-aware get. When the stored record is at a tier the caller cannot\n * decrypt:\n *   - `'invisibility'` mode (default) → returns `null`.\n *   - `'ghost'` mode → returns a `GhostRecord` placeholder with the tier and\n *     the record id (the record exists but contents are withheld).\n *\n * Fully-cleared reads return the plaintext record and fire a cross-tier event\n * when `_tier > 0`.\n */\nexport async function getAtTier<T>(ctx: TiersContext<T>, id: string): Promise<T | GhostRecord | null> {\n  assertTiersEnabled(ctx)\n  const envelope = await ctx.adapter.get(ctx.vault, ctx.name, id)\n  if (!envelope) return null\n  const tier = envelope._tier ?? 0\n  if (tier === 0) {\n    return ctx.codec.decryptRecord(envelope, { id })\n  }\n\n  const key = dekKey(ctx.name, tier)\n  if (!ctx.keyring.deks.has(key)) {\n    if (ctx.tierMode === 'ghost') {\n      return { _ghost: true, _tier: tier } as GhostRecord\n    }\n    return null\n  }\n\n  const dek = await ctx.getDEK(key)\n  // A tiered record may carry a per-record CEK (e.g. a CEK record\n  // elevated via `elevate()`): the CEK is wrapped under the TIER DEK, so\n  // unwrap under the tier DEK then decrypt the body under the CEK. Legacy\n  // tiered records decrypt directly under the tier DEK.\n  let plaintext: string\n  let cek: EnclaveKey | undefined\n  if (envelope._cek !== undefined) {\n    cek = await unwrapCek(envelope._cek, dek)\n    ctx.cekCache?.set(id, cek, 1)\n    plaintext = await decrypt(envelope._iv, envelope._data, cek)\n  } else {\n    plaintext = await decrypt(envelope._iv, envelope._data, dek)\n  }\n  let record = JSON.parse(plaintext) as T\n\n  // #635: this manual-decrypt leg never went through `decryptRecord`, so it\n  // never processed `_sealed` slots — an elevated classified record read\n  // back through here would return the body WITHOUT its sealed fields\n  // (silent omission). `applySealedSlots` is the same post-processing\n  // `decryptRecord`'s tier-0 branch above gets for free, extracted so it can\n  // take OUR already-unwrapped `cek` (unwrapped under the TIER dek above)\n  // instead of resolving one itself under the collection DEK the way\n  // `decryptRecord`/`resolveEnvelopeCek` would — which would be the wrong\n  // key for a `_cek` wrapped under a tier DEK. `sealedAsHandles` is omitted\n  // (default false) to match this function's OWN tier-0 branch above\n  // (`ctx.codec.decryptRecord(envelope, { id })`, no `sealedAsHandles`) —\n  // both tiers return sealed fields inline-decrypted, not as handles.\n  if (envelope._sealed !== undefined) {\n    record = await ctx.codec.applySealedSlots(record, envelope._sealed, cek, { id })\n  }\n\n  ctx.emitCrossTierEvent({\n    actor: ctx.keyring.userId,\n    collection: ctx.name,\n    id,\n    tier,\n    authorization: isElevatorOrOwner(ctx) ? 'inherent' : 'delegation',\n    op: 'get',\n    ts: new Date().toISOString(),\n  })\n\n  return record\n}\n\n/**\n * list ids grouped by the caller's readability. Returns only ids whose tier the\n * caller can read. Above-tier ids are omitted in `'invisibility'` mode and\n * included (with tier metadata) in `'ghost'` mode.\n */\nexport async function listAtTier<T>(ctx: TiersContext<T>): Promise<Array<{ id: string; tier: number; readable: boolean }>> {\n  assertTiersEnabled(ctx)\n  const ids = await ctx.adapter.list(ctx.vault, ctx.name)\n  const out: Array<{ id: string; tier: number; readable: boolean }> = []\n  for (const id of ids) {\n    const env = await ctx.adapter.get(ctx.vault, ctx.name, id)\n    if (!env) continue\n    const tier = env._tier ?? 0\n    const readable = tier === 0 || ctx.keyring.deks.has(dekKey(ctx.name, tier))\n    if (!readable && ctx.tierMode === 'invisibility') continue\n    out.push({ id, tier, readable })\n  }\n  return out\n}\n\n/**\n * elevate a record to a higher tier. Re-encrypts with the target tier's DEK.\n * The caller must hold DEKs for both the current tier (to decrypt) and the\n * target tier (to re-encrypt). Stamps `_elevatedBy` with the caller id so\n * `demote()` can check the reverse operation.\n */\nexport async function elevate<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void> {\n  assertTiersEnabled(ctx)\n  assertDeclaredTier(ctx, toTier)\n  assertTierAccess(ctx.keyring, ctx.name, toTier)\n\n  const envelope = await ctx.adapter.get(ctx.vault, ctx.name, id)\n  if (!envelope) throw new Error(`Record \"${id}\" not found in collection \"${ctx.name}\"`)\n  const fromTier = envelope._tier ?? 0\n  if (toTier === fromTier) return\n  if (toTier < fromTier) {\n    throw new Error(`Use demote() to lower the tier of \"${id}\" from ${fromTier} to ${toTier}`)\n  }\n  // Caller must have access at the existing tier to decrypt.\n  if (fromTier > 0) assertTierAccess(ctx.keyring, ctx.name, fromTier)\n\n  const fromKey = dekKey(ctx.name, fromTier)\n  const toKey = dekKey(ctx.name, toTier)\n  const fromDek = await ctx.getDEK(fromKey)\n  const toDek = await ctx.getDEK(toKey)\n\n  // Per-record CEK composes with tiers: the body key is unchanged (history\n  // chain identity preserved); only the wrapping key moves with the tier.\n  // Legacy (no `_cek`) records take the direct-DEK path unchanged.\n  const now = new Date().toISOString()\n  const body = await rewrapBodyToDek(envelope, fromDek, toDek)\n  if (body.cek) ctx.cekCache?.set(id, body.cek, 1)\n  const next: EncryptedEnvelope = {\n    _noydb: NOYDB_FORMAT_VERSION,\n    _v: envelope._v + 1,\n    _ts: now,\n    _iv: body._iv,\n    _data: body._data,\n    _by: ctx.keyring.userId,\n    _tier: toTier,\n    _elevatedBy: ctx.keyring.userId,\n    ...(body._cek !== undefined ? { _cek: body._cek } : {}),\n  }\n  await ctx.adapter.put(ctx.vault, ctx.name, id, next)\n\n  ctx.emitCrossTierEvent({\n    actor: ctx.keyring.userId,\n    collection: ctx.name,\n    id,\n    tier: toTier,\n    authorization: 'elevation',\n    op: 'elevate',\n    ts: now,\n  })\n}\n\n/**\n * demote a record to a lower tier. Allowed only for the user who performed the\n * last elevation or an owner.\n */\nexport async function demote<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void> {\n  assertTiersEnabled(ctx)\n  if (toTier < 0) throw new Error(`Cannot demote to negative tier ${toTier}`)\n\n  const envelope = await ctx.adapter.get(ctx.vault, ctx.name, id)\n  if (!envelope) throw new Error(`Record \"${id}\" not found in collection \"${ctx.name}\"`)\n  const fromTier = envelope._tier ?? 0\n  if (toTier === fromTier) return\n  if (toTier > fromTier) {\n    throw new Error(`Use elevate() to raise the tier of \"${id}\" from ${fromTier} to ${toTier}`)\n  }\n  const isOwner = ctx.keyring.role === 'owner'\n  const isOriginalElevator = envelope._elevatedBy === ctx.keyring.userId\n  if (!isOwner && !isOriginalElevator) {\n    throw new TierDemoteDeniedError(id, fromTier)\n  }\n  // Caller must still hold the DEK of the current tier to decrypt.\n  assertTierAccess(ctx.keyring, ctx.name, fromTier)\n  if (toTier > 0) assertDeclaredTier(ctx, toTier)\n\n  const fromDek = await ctx.getDEK(dekKey(ctx.name, fromTier))\n  const toDek = await ctx.getDEK(dekKey(ctx.name, toTier))\n\n  // CEK re-wrap on demote — same body key, moved from the source tier\n  // DEK to the target tier DEK. Legacy records take the direct-DEK path.\n  const now = new Date().toISOString()\n  const body = await rewrapBodyToDek(envelope, fromDek, toDek)\n  if (body.cek) ctx.cekCache?.set(id, body.cek, 1)\n  const next: EncryptedEnvelope = {\n    _noydb: NOYDB_FORMAT_VERSION,\n    _v: envelope._v + 1,\n    _ts: now,\n    _iv: body._iv,\n    _data: body._data,\n    _by: ctx.keyring.userId,\n    ...(toTier > 0 && { _tier: toTier }),\n    ...(body._cek !== undefined ? { _cek: body._cek } : {}),\n  }\n  await ctx.adapter.put(ctx.vault, ctx.name, id, next)\n\n  ctx.emitCrossTierEvent({\n    actor: ctx.keyring.userId,\n    collection: ctx.name,\n    id,\n    tier: fromTier,\n    authorization: 'elevation',\n    op: 'demote',\n    ts: now,\n  })\n}\n\n/**\n * Classify a live envelope's `_sealed` slots for crypto-shred completeness\n * (#M-1). Thin delegate to {@link RecordCodec.classifySealedShred}; surfaced\n * here because `vault.ts` forget() reaches in via `collection._classifySealedShred`.\n */\nexport function classifySealedShred<T>(\n  ctx: TiersContext<T>,\n  live: EncryptedEnvelope,\n): Promise<{ readonly slots: readonly SealedShredSlot[] }> {\n  return ctx.codec.classifySealedShred(live)\n}\n"],"mappings":"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","names":["putAtTier","getAtTier","listAtTier","elevate","demote"]}

package/dist/chunk-ANB77BVV.js

@@ -0,0 +1,150 @@
+import {
+  openEnvelopeJson
+} from "./chunk-MCHVVJIA.js";
+import {
+  encrypt,
+  hmacSha256Hex,
+  sha256Hex
+} from "./chunk-3OPY6MK2.js";
+import {
+  NOYDB_FORMAT_VERSION
+} from "./chunk-YN5IAHN6.js";
+
+// src/with-audit/forget/strategy.ts
+var NO_FORGET = { subjects: {} };
+
+// src/with-audit/forget/subject-index.ts
+var SUBJECT_INDEX_COLLECTION = "_subject_index";
+var REF_LIST_BUCKET = 256;
+async function sha256HexString(input) {
+  return sha256Hex(new TextEncoder().encode(input));
+}
+async function subjectKeys(getDEK, encrypted, subjectId) {
+  const legacy = await sha256HexString(subjectId);
+  if (!encrypted) return [legacy];
+  const dek = await getDEK(SUBJECT_INDEX_COLLECTION);
+  const keyed = await hmacSha256Hex(dek, new TextEncoder().encode(subjectId));
+  return keyed === legacy ? [keyed] : [keyed, legacy];
+}
+async function primarySubjectKey(getDEK, encrypted, subjectId) {
+  return (await subjectKeys(getDEK, encrypted, subjectId))[0];
+}
+function parseRefs(json) {
+  const parsed = JSON.parse(json);
+  return Array.isArray(parsed) ? parsed : parsed.r;
+}
+function serializeRefs(refs) {
+  const base = JSON.stringify({ r: refs, p: "" });
+  const pad = Math.ceil(base.length / REF_LIST_BUCKET) * REF_LIST_BUCKET - base.length;
+  return JSON.stringify({ r: refs, p: " ".repeat(pad) });
+}
+async function readRefs(adapter, vault, getDEK, encrypted, key) {
+  const env = await adapter.get(vault, SUBJECT_INDEX_COLLECTION, key);
+  if (!env || !env._data) return [];
+  if (!encrypted) return parseRefs(env._data);
+  const dek = await getDEK(SUBJECT_INDEX_COLLECTION);
+  const json = await openEnvelopeJson(env, dek);
+  return parseRefs(json);
+}
+async function writeRefs(adapter, vault, getDEK, encrypted, key, refs) {
+  let env;
+  if (!encrypted) {
+    env = { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: (/* @__PURE__ */ new Date()).toISOString(), _iv: "", _data: JSON.stringify(refs) };
+  } else {
+    const dek = await getDEK(SUBJECT_INDEX_COLLECTION);
+    const { iv, data } = await encrypt(serializeRefs(refs), dek);
+    env = { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: (/* @__PURE__ */ new Date()).toISOString(), _iv: iv, _data: data };
+  }
+  await adapter.put(vault, SUBJECT_INDEX_COLLECTION, key, env);
+}
+async function addSubjectRef(adapter, vault, getDEK, encrypted, subjectId, ref) {
+  const key = await primarySubjectKey(getDEK, encrypted, subjectId);
+  const refs = await readRefs(adapter, vault, getDEK, encrypted, key);
+  if (refs.some((r) => r.collection === ref.collection && r.id === ref.id)) return;
+  refs.push(ref);
+  await writeRefs(adapter, vault, getDEK, encrypted, key, refs);
+}
+async function removeSubjectRef(adapter, vault, getDEK, encrypted, subjectId, ref) {
+  for (const key of await subjectKeys(getDEK, encrypted, subjectId)) {
+    const refs = await readRefs(adapter, vault, getDEK, encrypted, key);
+    const next = refs.filter((r) => !(r.collection === ref.collection && r.id === ref.id));
+    if (next.length === refs.length) continue;
+    if (next.length === 0) {
+      await adapter.delete(vault, SUBJECT_INDEX_COLLECTION, key);
+    } else {
+      await writeRefs(adapter, vault, getDEK, encrypted, key, next);
+    }
+  }
+}
+async function lookupSubject(adapter, vault, getDEK, encrypted, subjectId) {
+  const keys = await subjectKeys(getDEK, encrypted, subjectId);
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const key of keys) {
+    for (const ref of await readRefs(adapter, vault, getDEK, encrypted, key)) {
+      const dedup = `${ref.collection}\0${ref.id}`;
+      if (seen.has(dedup)) continue;
+      seen.add(dedup);
+      out.push(ref);
+    }
+  }
+  return out;
+}
+async function rebuildSubjectIndex(adapter, vault, getDEK, encrypted, subjects, decodeRecord) {
+  const existing = await adapter.list(vault, SUBJECT_INDEX_COLLECTION);
+  for (const k of existing) {
+    await adapter.delete(vault, SUBJECT_INDEX_COLLECTION, k);
+  }
+  const bySubject = /* @__PURE__ */ new Map();
+  for (const [collection, field] of Object.entries(subjects)) {
+    const ids = await adapter.list(vault, collection);
+    for (const id of ids) {
+      if (id.startsWith("_")) continue;
+      const env = await adapter.get(vault, collection, id);
+      if (!env || !env._data) continue;
+      const record = await decodeRecord(collection, id, env);
+      if (record === null) continue;
+      const subjectValue = readDottedPath(record, field);
+      if (subjectValue === void 0 || subjectValue === null) continue;
+      const subjectId = coerceSubjectId(subjectValue);
+      const list = bySubject.get(subjectId) ?? [];
+      list.push({ collection, id });
+      bySubject.set(subjectId, list);
+    }
+  }
+  let entries = 0;
+  for (const [subjectId, refs] of bySubject) {
+    const key = await primarySubjectKey(getDEK, encrypted, subjectId);
+    await writeRefs(adapter, vault, getDEK, encrypted, key, refs);
+    entries++;
+  }
+  return entries;
+}
+function coerceSubjectId(value) {
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") {
+    return String(value);
+  }
+  return JSON.stringify(value);
+}
+function readDottedPath(record, field) {
+  if (!field.includes(".")) return record[field];
+  let cursor = record;
+  for (const segment of field.split(".")) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+
+export {
+  NO_FORGET,
+  SUBJECT_INDEX_COLLECTION,
+  addSubjectRef,
+  removeSubjectRef,
+  lookupSubject,
+  rebuildSubjectIndex,
+  coerceSubjectId,
+  readDottedPath
+};
+//# sourceMappingURL=chunk-ANB77BVV.js.map

package/dist/chunk-ANB77BVV.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-audit/forget/strategy.ts","../src/with-audit/forget/subject-index.ts"],"sourcesContent":["/**\n * `withForgetCascade` — declaration surface for GDPR right-to-erasure via\n * per-record CEK crypto-shred.\n *\n * This file holds only the *declaration* shape and the disabled sentinel.\n * The actual erasure machinery lives in:\n *   - `subject-index.ts` — the encrypted `_subject_index` reserved collection\n *   - `vault.ts` `forget()` — the per-record tombstone + ledger flow\n *   - `collection.ts` `_writeTombstone` — the envelope rewrite\n *\n * A `ForgetStrategy` declares which collections carry erasable subject data\n * and the (dotted-path) field on each record that names the data subject.\n * Declaring a collection here ALSO forces `perRecordKeys: true` for it (a\n * shred can only erase a record whose body is keyed off a per-record CEK),\n * so adopters opt into the CEK foundation transitively.\n *\n * @module\n */\nimport type { LedgerEntry } from '../../with-commit/history/ledger/entry.js'\n\n/**\n * User-supplied declaration passed to {@link withForgetCascade}. Maps a\n * collection name to the record field (dotted path supported, e.g.\n * `'billing.buyerId'`) that identifies the data subject for erasure.\n *\n * ```ts\n * withForgetCascade({ subjects: { invoices: 'buyerId', contacts: 'id' } })\n * ```\n */\nexport interface SubjectDeclaration {\n  readonly subjects: Record<string, string>\n}\n\n/**\n * Resolved forget strategy threaded through Noydb → every Vault. Carries\n * the same `subjects` map the user declared. `NO_FORGET` (empty map) is the\n * off-by-default sentinel; `vault.forget()` throws\n * `ForgetStrategyNotConfiguredError` when the map is empty.\n */\nexport interface ForgetStrategy {\n  /** Collection → subject-field (dotted path). Empty under `NO_FORGET`. */\n  readonly subjects: Readonly<Record<string, string>>\n}\n\n/**\n * Disabled sentinel — no collections declare a subject field. `vault.forget()`\n * refuses with `ForgetStrategyNotConfiguredError`; no write hooks register; no\n * collection is forced into `perRecordKeys`. Non-adopters pay nothing.\n */\nexport const NO_FORGET: ForgetStrategy = { subjects: {} }\n\n// The `withForgetCascade` factory lives in `active.ts` (canonical\n// strategy.ts/active.ts/index.ts split); this file holds only the\n// declaration shape + disabled sentinel.\n\n/**\n * The outcome of a `vault.forget(subjectId)` call.\n *\n * `unmigratedRecords` lists `collection:id` pairs that were tombstoned but\n * whose body had NOT been migrated to a per-record CEK at shred time (legacy\n * body still under the shared collection DEK). Those records are tombstoned\n * (live envelope + history stripped) but their pre-shred ciphertext, if it\n * leaked into a backup before migration, remains decryptable under the\n * collection DEK — so erasure-completeness is NOT guaranteed for them. Run\n * the per-record-CEK migration pass, then re-forget, to close the gap.\n *\n * Blob attachments: a shredded record's **erasable** blobs (on a\n * `perRecordKeys` collection) are crypto-shredded inline — `blobsShredded`\n * counts those taken to refCount 0 (BlobObject deleted → chunks permanently\n * undecryptable), `blobsRetainedShared` counts those still referenced by\n * another record (shared content legitimately persists for its other owner).\n * `blobResidueCollections` now lists only collections with blobs that could\n * NOT be crypto-shredded: **legacy** blobs (no per-blob `_cek`, chunks under\n * the shared `_blob` DEK — migrate them), or a session without the blob\n * service loaded. An all-erasable subject yields an empty residue list.\n */\nexport interface ForgetResult {\n  /** The subject id passed to `forget()`. Echoed for caller convenience. */\n  readonly subject: string\n  /** Count of live records rewritten to a tombstone. */\n  readonly recordsShredded: number\n  /** Count of `_history` envelopes tombstoned across all shredded records. */\n  readonly historyVersionsShredded: number\n  /** Distinct collections that had at least one record shredded. */\n  readonly collections: readonly string[]\n  /** `collection:id` pairs shredded while still un-migrated (see type docs). */\n  readonly unmigratedRecords: readonly string[]\n  /** Count of erasable blobs crypto-shredded (refCount → 0, BlobObject deleted). */\n  readonly blobsShredded: number\n  /** Count of erasable blobs retained because still referenced elsewhere (shared). */\n  readonly blobsRetainedShared: number\n  /** Collections with blobs that could NOT be crypto-shredded — legacy (no `_cek`) or blobs disabled (see type docs). */\n  readonly blobResidueCollections: readonly string[]\n  /**\n   * Count of persisted `_idx/<field>/<recordId>` index side-cars hard-deleted\n   * across the shredded records. These live under the retained\n   * collection DEK, so crypto-shred alone would leave the indexed field VALUES\n   * readable — `forget()` must delete them.\n   */\n  readonly indexPostingsPurged: number\n  /**\n   * `collection:id:field` entries whose persisted `_idx` side-car could NOT be\n   * deleted — index residue that still leaks the indexed value under the\n   * retained collection DEK. Non-empty means erasure is INCOMPLETE: retry, or\n   * purge the side-car out of band.\n   */\n  readonly indexResidue: readonly string[]\n  /**\n   * Count of `_sealed[field]` slots dropped from the live store across the\n   * shredded records. For slots written under `sensitive` +\n   * `perRecordKeys` (the current path), the key derives off the per-record CEK,\n   * so tombstoning the record — which drops `_cek` and `_sealed` — also\n   * crypto-shreds the value. A legacy slot (written before per-record CEKs) keys\n   * off the collection DEK instead, so dropping it removes it from the live store but a\n   * pre-forget backup remains recoverable by a DEK holder (same caveat `_data`\n   * carries); migrate by re-`put`ting before forgetting for full crypto-shred.\n   */\n  readonly sealedFieldsShredded: number\n  /** Count of `_sealed_cek` host-delivery envelopes deleted (#H-1). A record sealed to an\n   * at-* host via sealRecordToHost persists its raw CEK there; forget() must destroy them. */\n  readonly sealedCekEnvelopesPurged: number\n  /** `collection:id` whose `_sealed_cek` purge failed (residue — the host-recoverable CEK may survive). */\n  readonly sealedCekResidue: readonly string[]\n  /** `collection:id:field` sealed slots that were DEK-derived (legacy, written before per-record CEKs) and thus NOT crypto-shredded\n   * by dropping `_cek` — the collection DEK is retained, so synced/backup copies stay decryptable (#M-1). */\n  readonly sealedResidue: readonly string[]\n  /** The single `op:'forget'` ledger entry appended for this erasure. */\n  readonly ledgerEntry: LedgerEntry\n  /** #622 — record-grain derived artifacts (MV rows, per-record derived copies) erased\n   *  because their source subject was forgotten. Overlay outputs are intentionally out of\n   *  scope here — an overlay is always sourced from an MV, never directly from a subject\n   *  collection, so the personal-data-bearing MV rows it reads are already erased above. */\n  readonly derivedRecordsErased: number\n  /** #622 — aggregate-grain targets (rollups) recomputed without the forgotten contribution. */\n  readonly derivedAggregatesRecomputed: number\n  /** #622 — `collection:id` derived writes SKIPPED because the target period is frozen\n   *  (recompute deferred; the aggregate retains the forgotten contribution — audited). */\n  readonly derivedResidueFrozen: readonly string[]\n  /** #650 Task 5 (#648) — referencing records tombstoned via a `'ref'` edge's `cascade` policy. */\n  readonly lookupReferencesCascaded: number\n  /** #650 Task 5 (#648) — referencing fields cleared via a `'ref'` edge's `nullify` policy. */\n  readonly lookupReferencesNullified: number\n  /** #650 Task 5 review (Important fix) — `'ref'` edges whose compare-key could NOT be resolved,\n   *  even from the LIVE pre-shred backing row — cascade/nullify propagation was SKIPPED for these.\n   *  Always empty in the ordinary case; non-empty means the skip is reported, never silent. */\n  readonly lookupReferencesResidue: readonly string[]\n}\n","/**\n * The encrypted subject index.\n *\n * GDPR crypto-shred needs to answer \"which records belong to data subject\n * X?\" portably (the index must travel with the vault/bundle) WITHOUT leaking\n * subject-equivalence to the store. The rejected alternative — an unencrypted\n * subject tag in envelope metadata — would let anyone with store access see\n * which records share a subject. Instead we keep a reserved `_subject_index`\n * collection, encrypted under its OWN DEK (`getDEK('_subject_index')`):\n *\n *   - record id  = `HMAC-SHA256(indexDEK, subjectId)` (M-2). A bare\n *     `sha256Hex(subjectId)` would be offline-computable: an attacker with\n *     store access and a candidate list (emails / customer ids are low-entropy)\n *     could dictionary the hash to confirm \"subject X is present here.\" Keying\n *     the id with the vault-only index DEK removes that capability — without the\n *     DEK the id cannot be derived. (Legacy entries written before M-2 used the\n *     bare sha256 id; the read/remove paths dual-look-up both forms.)\n *   - record body = AES-GCM(JSON `{ r: [{ collection, id }], p }`) under the\n *     index DEK, where `p` pads the plaintext to a bucketed length so the\n *     ciphertext `_data` length does not leak the approximate record count.\n *     Legacy bodies were a bare `[{ collection, id }]` array; reads accept both.\n *\n * ## Concurrency (RISK #3 — known v1 limitation)\n *\n * `addSubjectRef` / `removeSubjectRef` are read-modify-write with no CAS. The\n * design assumes a SINGLE WRITER (the noy-db single-process write model). Two\n * concurrent writers racing on the SAME subject can lose an entry (last-write\n * wins on the ref list). This is documented, not fixed in v1:\n * `rebuildSubjectIndex` performs a full scan to recover a correct index from\n * the canonical records, so a lost ref is recoverable. A CAS-backed index is\n * deferred to a later slice.\n *\n * @module\n */\nimport { encrypt, openEnvelopeJson, hmacSha256Hex, sha256Hex, type EnclaveKey } from '../../kernel/enclave/index.js'\nimport type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js'\nimport { NOYDB_FORMAT_VERSION } from '../../kernel/types.js'\n\n/** Reserved collection holding the encrypted subject → records index. */\nexport const SUBJECT_INDEX_COLLECTION = '_subject_index'\n\n/**\n * Bucket (bytes) the encrypted ref-list plaintext is padded up to, so the\n * ciphertext `_data` length leaks only `count` rounded up to a bucket — not the\n * exact record count. 256 keeps small subjects (the common case) indistinguishable.\n */\nconst REF_LIST_BUCKET = 256\n\n/** A single record reference held in a subject's index entry. */\nexport interface SubjectRef {\n  readonly collection: string\n  readonly id: string\n}\n\ntype GetDEK = (collectionName: string) => Promise<EnclaveKey>\n\n/** SHA-256 hex of a UTF-8 string. The LEGACY (pre-M-2) subject-index key. */\nasync function sha256HexString(input: string): Promise<string> {\n  return sha256Hex(new TextEncoder().encode(input))\n}\n\n/**\n * The subject-index record id(s) to consult for a subject, most-current first.\n *\n * - Encrypted vault: the PRIMARY id is `HMAC-SHA256(indexDEK, subjectId)` (M-2)\n *   — not offline-computable. The LEGACY `sha256Hex(subjectId)` id is also\n *   returned so reads/removes still find entries written before M-2 (dual-lookup).\n * - Plaintext/debug vault: no DEK to key with, so the only id is the legacy\n *   sha256 form (unchanged behaviour — plaintext mode is not zero-knowledge anyway).\n */\nasync function subjectKeys(getDEK: GetDEK, encrypted: boolean, subjectId: string): Promise<string[]> {\n  const legacy = await sha256HexString(subjectId)\n  if (!encrypted) return [legacy]\n  const dek = await getDEK(SUBJECT_INDEX_COLLECTION)\n  const keyed = await hmacSha256Hex(dek, new TextEncoder().encode(subjectId))\n  return keyed === legacy ? [keyed] : [keyed, legacy]\n}\n\n/** The id new writes land under (keyed when encrypted, else legacy sha256). */\nasync function primarySubjectKey(getDEK: GetDEK, encrypted: boolean, subjectId: string): Promise<string> {\n  return (await subjectKeys(getDEK, encrypted, subjectId))[0]!\n}\n\n/** Parse a stored ref-list body: new padded `{ r, p }` wrapper OR legacy bare array. */\nfunction parseRefs(json: string): SubjectRef[] {\n  const parsed = JSON.parse(json) as SubjectRef[] | { r: SubjectRef[] }\n  return Array.isArray(parsed) ? parsed : parsed.r\n}\n\n/** Serialize + pad the ref list to a bucket boundary (encrypted vaults only). */\nfunction serializeRefs(refs: SubjectRef[]): string {\n  const base = JSON.stringify({ r: refs, p: '' })\n  const pad = Math.ceil(base.length / REF_LIST_BUCKET) * REF_LIST_BUCKET - base.length\n  return JSON.stringify({ r: refs, p: ' '.repeat(pad) })\n}\n\n/** Read + decrypt the ref list at a SINGLE index key. Returns `[]` when absent. */\nasync function readRefs(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  key: string,\n): Promise<SubjectRef[]> {\n  const env = await adapter.get(vault, SUBJECT_INDEX_COLLECTION, key)\n  if (!env || !env._data) return []\n  if (!encrypted) return parseRefs(env._data)\n  const dek = await getDEK(SUBJECT_INDEX_COLLECTION)\n  const json = await openEnvelopeJson(env, dek)\n  return parseRefs(json)\n}\n\n/** Encrypt + write a ref list for a subject under its derived key. */\nasync function writeRefs(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  key: string,\n  refs: SubjectRef[],\n): Promise<void> {\n  let env: EncryptedEnvelope\n  if (!encrypted) {\n    // Plaintext/debug vault: keep the legacy bare-array form (no padding needed).\n    env = { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: new Date().toISOString(), _iv: '', _data: JSON.stringify(refs) }\n  } else {\n    const dek = await getDEK(SUBJECT_INDEX_COLLECTION)\n    const { iv, data } = await encrypt(serializeRefs(refs), dek)\n    env = { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: new Date().toISOString(), _iv: iv, _data: data }\n  }\n  await adapter.put(vault, SUBJECT_INDEX_COLLECTION, key, env)\n}\n\n/**\n * Add a `{ collection, id }` ref to a subject's index entry (idempotent —\n * a duplicate ref is not appended). Read-modify-write; see the concurrency\n * note in the module docstring.\n */\nexport async function addSubjectRef(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  subjectId: string,\n  ref: SubjectRef,\n): Promise<void> {\n  const key = await primarySubjectKey(getDEK, encrypted, subjectId)\n  const refs = await readRefs(adapter, vault, getDEK, encrypted, key)\n  if (refs.some((r) => r.collection === ref.collection && r.id === ref.id)) return\n  refs.push(ref)\n  await writeRefs(adapter, vault, getDEK, encrypted, key, refs)\n}\n\n/**\n * Remove a `{ collection, id }` ref from a subject's index entry. When the\n * last ref is removed the (now empty) entry is deleted so the store holds no\n * residual key for an erased subject.\n */\nexport async function removeSubjectRef(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  subjectId: string,\n  ref: SubjectRef,\n): Promise<void> {\n  // Dual-lookup: drop the ref from BOTH the keyed (M-2) and the legacy sha256\n  // entry, so a pre-M-2 subject is still fully erased.\n  for (const key of await subjectKeys(getDEK, encrypted, subjectId)) {\n    const refs = await readRefs(adapter, vault, getDEK, encrypted, key)\n    const next = refs.filter((r) => !(r.collection === ref.collection && r.id === ref.id))\n    if (next.length === refs.length) continue\n    if (next.length === 0) {\n      await adapter.delete(vault, SUBJECT_INDEX_COLLECTION, key)\n    } else {\n      await writeRefs(adapter, vault, getDEK, encrypted, key, next)\n    }\n  }\n}\n\n/**\n * Look up every record ref for a subject. Returns `[]` when none exist. Unions\n * the keyed (M-2) and legacy sha256 entries (dual-lookup), deduplicated, so a\n * subject indexed before M-2 is still fully found.\n */\nexport async function lookupSubject(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  subjectId: string,\n): Promise<SubjectRef[]> {\n  const keys = await subjectKeys(getDEK, encrypted, subjectId)\n  const seen = new Set<string>()\n  const out: SubjectRef[] = []\n  for (const key of keys) {\n    for (const ref of await readRefs(adapter, vault, getDEK, encrypted, key)) {\n      const dedup = `${ref.collection}\\u0000${ref.id}`\n      if (seen.has(dedup)) continue\n      seen.add(dedup)\n      out.push(ref)\n    }\n  }\n  return out\n}\n\n/**\n * Rebuild the entire subject index from the canonical records (the recovery\n * path for the documented read-modify-write race). Scans each declared\n * collection, reads `record[subjectField]` (dotted path), and rewrites the\n * index from scratch. Tombstoned (already-shredded) records contribute no\n * ref — their body is gone, so they cannot be re-indexed.\n *\n * `decodeRecord` decrypts an envelope to a plain object (or returns null for\n * a tombstone / unreadable record); supplied by the caller so this module\n * stays free of Collection internals.\n */\nexport async function rebuildSubjectIndex(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  subjects: Readonly<Record<string, string>>,\n  decodeRecord: (collection: string, id: string, env: EncryptedEnvelope) => Promise<Record<string, unknown> | null>,\n): Promise<number> {\n  // Drop every existing index entry first so removed refs don't linger.\n  const existing = await adapter.list(vault, SUBJECT_INDEX_COLLECTION)\n  for (const k of existing) {\n    await adapter.delete(vault, SUBJECT_INDEX_COLLECTION, k)\n  }\n\n  // subjectId → refs, accumulated across all declared collections.\n  const bySubject = new Map<string, SubjectRef[]>()\n  for (const [collection, field] of Object.entries(subjects)) {\n    const ids = await adapter.list(vault, collection)\n    for (const id of ids) {\n      if (id.startsWith('_')) continue\n      const env = await adapter.get(vault, collection, id)\n      if (!env || !env._data) continue // missing or tombstone\n      const record = await decodeRecord(collection, id, env)\n      if (record === null) continue\n      const subjectValue = readDottedPath(record, field)\n      if (subjectValue === undefined || subjectValue === null) continue\n      const subjectId = coerceSubjectId(subjectValue)\n      const list = bySubject.get(subjectId) ?? []\n      list.push({ collection, id })\n      bySubject.set(subjectId, list)\n    }\n  }\n\n  let entries = 0\n  for (const [subjectId, refs] of bySubject) {\n    const key = await primarySubjectKey(getDEK, encrypted, subjectId)\n    await writeRefs(adapter, vault, getDEK, encrypted, key, refs)\n    entries++\n  }\n  return entries\n}\n\n/**\n * Coerce a read subject-field value to a stable string id. Primitives use\n * their natural string form; objects/arrays are JSON-stringified so structural\n * subjects still get a deterministic key (avoids the `[object Object]` trap).\n */\nexport function coerceSubjectId(value: unknown): string {\n  if (typeof value === 'string') return value\n  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {\n    return String(value)\n  }\n  return JSON.stringify(value)\n}\n\n/** Read a (possibly dotted) field path from a plain record. */\nexport function readDottedPath(record: Record<string, unknown>, field: string): unknown {\n  if (!field.includes('.')) return record[field]\n  let cursor: unknown = record\n  for (const segment of field.split('.')) {\n    if (cursor === null || cursor === undefined) return undefined\n    cursor = (cursor as Record<string, unknown>)[segment]\n  }\n  return cursor\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-AURFOK3D.js

@@ -0,0 +1,35 @@
+// src/with-lookup/search/fuse.ts
+function fuseRetrieval(lists, opts = {}) {
+  const k = opts.k ?? 60;
+  const acc = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (const hit of list) {
+      const contribution = 1 / (k + hit.rank);
+      const prev = acc.get(hit.id);
+      if (prev === void 0) {
+        acc.set(hit.id, { score: contribution, hit });
+      } else {
+        prev.score += contribution;
+        prev.hit = mergePresentation(prev.hit, hit);
+      }
+    }
+  }
+  const merged = [...acc.values()].sort(
+    (a, b) => b.score - a.score || (a.hit.id < b.hit.id ? -1 : a.hit.id > b.hit.id ? 1 : 0)
+  );
+  const limited = opts.limit !== void 0 ? merged.slice(0, opts.limit) : merged;
+  return limited.map((m, i) => ({ ...m.hit, score: m.score, rank: i + 1 }));
+}
+function mergePresentation(a, b) {
+  const lexical = a.field !== "(vector)" ? a : b;
+  const other = lexical === a ? b : a;
+  return {
+    ...lexical,
+    ...lexical.record === void 0 && other.record !== void 0 ? { record: other.record } : {}
+  };
+}
+
+export {
+  fuseRetrieval
+};
+//# sourceMappingURL=chunk-AURFOK3D.js.map

package/dist/chunk-AURFOK3D.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-lookup/search/fuse.ts"],"sourcesContent":["/**\n * L3 — Reciprocal Rank Fusion. Merges N ranked `RetrieveHit` lists into\n * one, scoring each id by Σ 1/(k + rank) across the lists it appears in. Pure,\n * deterministic, no I/O — which is why it serves BOTH hybrid lexical⊕semantic\n * fusion AND klum-db's cross-vault federation (the lists are per-vault). The\n * fused `score` is the RRF score, NOT BM25 or cosine.\n */\nimport type { RetrieveHit } from './retrieve-types.js'\n\nexport interface FuseOptions {\n  /** Only 'rrf' in v1 (default). */\n  readonly strategy?: 'rrf'\n  /** RRF constant; larger flattens the rank weighting. Default 60. */\n  readonly k?: number\n  /** Truncate the fused output to this many hits. */\n  readonly limit?: number\n}\n\n/**\n * Callers must supply hits with `rank >= 1` (the retrieve contract guarantees\n * it; a federation caller passing `rank: 0` with `k: 0` would divide by zero).\n * Doc-only note — no runtime guard; rank ≥ 1 is the retrieve contract.\n */\nexport function fuseRetrieval<T>(\n  lists: ReadonlyArray<ReadonlyArray<RetrieveHit<T>>>,\n  opts: FuseOptions = {},\n): RetrieveHit<T>[] {\n  const k = opts.k ?? 60\n  const acc = new Map<string, { score: number; hit: RetrieveHit<T> }>()\n  for (const list of lists) {\n    for (const hit of list) {\n      const contribution = 1 / (k + hit.rank)\n      const prev = acc.get(hit.id)\n      if (prev === undefined) {\n        acc.set(hit.id, { score: contribution, hit })\n      } else {\n        prev.score += contribution\n        prev.hit = mergePresentation(prev.hit, hit)\n      }\n    }\n  }\n  const merged = [...acc.values()].sort(\n    (a, b) => b.score - a.score || (a.hit.id < b.hit.id ? -1 : a.hit.id > b.hit.id ? 1 : 0),\n  )\n  const limited = opts.limit !== undefined ? merged.slice(0, opts.limit) : merged\n  return limited.map((m, i) => ({ ...m.hit, score: m.score, rank: i + 1 }))\n}\n\n/**\n * When an id appears in multiple lists, prefer the more informative\n * presentation: a real `field`/`snippet`/`locale` (lexical) over the vector\n * placeholder (`'(vector)'` / `''`). Recover `record` from whichever hit has it.\n */\nfunction mergePresentation<T>(a: RetrieveHit<T>, b: RetrieveHit<T>): RetrieveHit<T> {\n  const lexical = a.field !== '(vector)' ? a : b\n  const other = lexical === a ? b : a\n  return {\n    ...lexical,\n    ...(lexical.record === undefined && other.record !== undefined ? { record: other.record } : {}),\n  }\n}\n"],"mappings":";AAuBO,SAAS,cACd,OACA,OAAoB,CAAC,GACH;AAClB,QAAM,IAAI,KAAK,KAAK;AACpB,QAAM,MAAM,oBAAI,IAAoD;AACpE,aAAW,QAAQ,OAAO;AACxB,eAAW,OAAO,MAAM;AACtB,YAAM,eAAe,KAAK,IAAI,IAAI;AAClC,YAAM,OAAO,IAAI,IAAI,IAAI,EAAE;AAC3B,UAAI,SAAS,QAAW;AACtB,YAAI,IAAI,IAAI,IAAI,EAAE,OAAO,cAAc,IAAI,CAAC;AAAA,MAC9C,OAAO;AACL,aAAK,SAAS;AACd,aAAK,MAAM,kBAAkB,KAAK,KAAK,GAAG;AAAA,MAC5C;AAAA,IACF;AAAA,EACF;AACA,QAAM,SAAS,CAAC,GAAG,IAAI,OAAO,CAAC,EAAE;AAAA,IAC/B,CAAC,GAAG,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,KAAK,EAAE,IAAI,KAAK,KAAK,EAAE,IAAI,KAAK,EAAE,IAAI,KAAK,IAAI;AAAA,EACvF;AACA,QAAM,UAAU,KAAK,UAAU,SAAY,OAAO,MAAM,GAAG,KAAK,KAAK,IAAI;AACzE,SAAO,QAAQ,IAAI,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,KAAK,OAAO,EAAE,OAAO,MAAM,IAAI,EAAE,EAAE;AAC1E;AAOA,SAAS,kBAAqB,GAAmB,GAAmC;AAClF,QAAM,UAAU,EAAE,UAAU,aAAa,IAAI;AAC7C,QAAM,QAAQ,YAAY,IAAI,IAAI;AAClC,SAAO;AAAA,IACL,GAAG;AAAA,IACH,GAAI,QAAQ,WAAW,UAAa,MAAM,WAAW,SAAY,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;AAAA,EAC/F;AACF;","names":[]}