@noy-db/hub 0.2.0-pre.3 → 0.2.0-pre.31

package/dist/{chunk-G7PAZ3TD.js → chunk-SHJ3BRTZ.js}

@@ -1,22 +1,27 @@
 import {
   wrapDbWithPredicates
-} from "./chunk-GDTCGIPX.js";
+} from "./chunk-RCB6GWTC.js";
 import {
   canonicalGroupKey,
   groupAndReduce
-} from "./chunk-KYKMKLJ6.js";
+} from "./chunk-K6NVSHAH.js";
 import {
+  applyI18nLocale
+} from "./chunk-QXWJQ7UU.js";
+import {
+  LocaleNotSpecifiedError,
   MaterializedViewTooLargeError
-} from "./chunk-YDLAFP36.js";
+} from "./chunk-JZ5DS4DP.js";
 
 // src/materialized-views/executor.ts
 var DEFAULT_MAX_ROWS = 1e5;
-async function materializeQueryResult(q, mvName) {
+async function materializeQueryResult(q, mvName, i18nLocale, i18nFields) {
   if (typeof q?.toArray === "function") {
     return await q.toArray();
   }
   if (typeof q?.run === "function") {
-    const result = await Promise.resolve(q.run());
+    const runOpts = i18nLocale !== void 0 ? { locale: i18nLocale, i18nFields } : void 0;
+    const result = await Promise.resolve(q.run(runOpts));
     if (Array.isArray(result)) {
       return result;
     }
@@ -30,13 +35,44 @@ async function materializeUnionResult(spec, db) {
   const unified = [];
   for (const arm of spec.unionSources) {
     const coll = db.collection(arm.collection);
-    const sourceRows = coll.query().toArray();
+    let q = coll.query();
+    if (arm.join?.length) {
+      for (const leg of arm.join) {
+        q = q.join(leg.field, { as: leg.as, maxRows: leg.maxRows, strategy: leg.strategy });
+      }
+    }
+    const sourceRows = q.toArray();
     for (const r of sourceRows) {
-      unified.push(arm.map(r));
+      const mapped = arm.map(r);
+      if (mapped == null) continue;
+      unified.push(mapped);
     }
   }
   if (!spec.groupBy) return unified;
   const groupFields = typeof spec.groupBy === "string" ? [spec.groupBy] : spec.groupBy;
+  if (spec.i18nLocale !== void 0 && spec.i18nFields !== void 0) {
+    const groupI18n = {};
+    for (const f of groupFields) {
+      const d = spec.i18nFields[f];
+      if (d !== void 0) groupI18n[f] = d;
+    }
+    if (Object.keys(groupI18n).length > 0) {
+      for (let i = 0; i < unified.length; i++) {
+        unified[i] = applyI18nLocale(unified[i], groupI18n, spec.i18nLocale, void 0, "mv");
+      }
+    }
+  }
+  for (const f of groupFields) {
+    for (const row of unified) {
+      const v = row[f];
+      if (v !== null && typeof v === "object") {
+        throw new LocaleNotSpecifiedError(
+          f,
+          `Materialized view "${spec.name}" groups by "${f}", whose value is a raw i18n locale map \u2014 an unstable object group key. Declare { i18nLocale, i18nFields } on the MV to resolve it at the 'mv' layer, or group by a dictKey/staticDict code (the stable key) and resolve the label at read time.`
+        );
+      }
+    }
+  }
   if (!spec.aggregate) {
     const seen = /* @__PURE__ */ new Map();
     for (const row of unified) {
@@ -45,7 +81,7 @@ async function materializeUnionResult(spec, db) {
     }
     return [...seen.values()];
   }
-  return groupAndReduce(unified, groupFields, spec.aggregate);
+  return groupAndReduce(unified, groupFields, spec.aggregate, spec.moneyFields);
 }
 var MaterializedViewExecutor = {
   async refresh(reg, accessor) {
@@ -61,7 +97,7 @@ var MaterializedViewExecutor = {
       rows = await materializeUnionResult(spec, ctxForQuery);
     } else {
       const q = spec.query(ctxForQuery);
-      rows = await materializeQueryResult(q, spec.name);
+      rows = await materializeQueryResult(q, spec.name, spec.i18nLocale, spec.i18nFields);
     }
     if (rows.length > maxRows) {
       throw new MaterializedViewTooLargeError(spec.name, rows.length, maxRows);
@@ -142,4 +178,4 @@ async function listOutputIds(outputColl) {
 export {
   MaterializedViewExecutor
 };
-//# sourceMappingURL=chunk-G7PAZ3TD.js.map
+//# sourceMappingURL=chunk-SHJ3BRTZ.js.map

package/dist/chunk-SHJ3BRTZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/materialized-views/executor.ts"],"sourcesContent":["import type { Collection } from '../collection.js'\nimport type { TxContext } from '../tx/transaction.js'\nimport type { EncryptedEnvelope } from '../types.js'\nimport { MaterializedViewTooLargeError, LocaleNotSpecifiedError } from '../errors.js'\nimport type { MaterializedFromMeta, MVQueryContext, MaterializedViewStrategy } from './types.js'\nimport type { RegisteredMV } from './registry.js'\nimport { wrapDbWithPredicates } from './registry.js'\nimport { groupAndReduce } from '../aggregate/groupby.js'\nimport { canonicalGroupKey } from '../aggregate/canonical-key.js'\nimport { applyI18nLocale, type I18nTextDescriptor } from '../i18n/core.js'\n\n/**\n * Accessor shape passed in from the owning Vault. Mirrors v1's\n * `DerivationStaleAccessor` — provides the per-collection resolver\n * and the active TxContext so refresh writes/tombstones register on\n * `_executed` for rollback symmetry.\n */\nexport interface MVExecutorAccessor {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  getCollection(name: string): Collection<any>\n  getActiveTxContext(): TxContext | null\n  /**\n   * Vault-shaped accessor passed to the MV's `query()` callback at\n   * each refresh. Same instance the registry used at registration\n   * time; threading through the executor lets the refresh path\n   * re-evaluate the closure against the live vault state.\n   */\n  getQueryContext(): MVQueryContext\n}\n\nexport interface RefreshResult {\n  /** Rows newly written / overwritten. */\n  written: number\n  /** Rows tombstoned via `_internalDelete` (only when `onEmpty: 'delete'`). */\n  deleted: number\n  /** Failed row writes (non-strict mode). */\n  failed: number\n}\n\n/** Default cost ceiling — overridable per-MV via `spec.maxRows`. */\nconst DEFAULT_MAX_ROWS = 100_000\n\n/**\n * Materialize a query terminal that may be a `Query<T>` (call\n * `.toArray()`), an `Aggregation<R>` (call `.run()` returning a\n * single object — wrap as a one-row array), or a `GroupedAggregation<R>`\n * (call `.run()` returning an array of grouped rows). Branches on\n * available terminal at runtime — no type-discrimination at registration.\n */\nasync function materializeQueryResult(\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  q: any,\n  mvName: string,\n  i18nLocale?: string,\n  i18nFields?: Record<string, I18nTextDescriptor>,\n): Promise<ReadonlyArray<Record<string, unknown>>> {\n  if (typeof q?.toArray === 'function') {\n    // Query<T> — non-aggregate path. `.toArray()` returns Promise<T[]>.\n    return await q.toArray()\n  }\n  if (typeof q?.run === 'function') {\n    // Aggregation<R> or GroupedAggregation<R>. `.run()` is synchronous\n    // and returns either a single object (Aggregation) or an array of\n    // rows (GroupedAggregation). Promise.resolve() normalizes both\n    // sync and async (future) variants.\n    // #285 query-form MV grouping: when the MV declares i18nLocale, pass it +\n    // i18nFields so a GroupedAggregation resolves i18n group keys before\n    // bucketing (the Aggregation path ignores the extra arg).\n    const runOpts = i18nLocale !== undefined ? { locale: i18nLocale, i18nFields } : undefined\n    const result: unknown = await Promise.resolve(q.run(runOpts))\n    if (Array.isArray(result)) {\n      return result as ReadonlyArray<Record<string, unknown>>\n    }\n    // Single-aggregate result — wrap as one-row array. The consumer's\n    // `rowKey()` should return a stable identity (often a literal\n    // constant like `'total'`) since there's only one row.\n    return [result as Record<string, unknown>]\n  }\n  throw new Error(\n    `MV \"${mvName}\": query() must return a Query<T>, Aggregation, or GroupedAggregation. ` +\n      `Got something without a .toArray() or .run() terminal.`,\n  )\n}\n\n/**\n * Materialize a UNION-form MV: read every arm's source\n * collection, apply each arm's `map` to project rows into the unified\n * MV row shape, concatenate the mapped streams, then optionally run\n * `groupBy` + `aggregate` over the result.\n *\n * Modes (driven by `spec.groupBy` / `spec.aggregate`):\n *\n *   - No `groupBy` → return the concatenated mapped rows unchanged.\n *   - `groupBy` without `aggregate` → dedupe by composite group key,\n *     keep the first row seen per key (later arms don't overwrite\n *     earlier arms — Map insertion order rules).\n *   - `groupBy` + `aggregate` → delegate to the shared `groupAndReduce`\n *     pipeline used by `Query.groupBy().aggregate()`.\n *\n * Per-arm `map` is the schema-unification boundary; the strategy's\n * `TRow` type parameter enforces that every arm projects into the\n * same shape at compile time.\n *\n * @internal\n */\nasync function materializeUnionResult<TRow extends Record<string, unknown>>(\n  spec: MaterializedViewStrategy<TRow>,\n  db: MVQueryContext,\n): Promise<ReadonlyArray<Record<string, unknown>>> {\n  const unified: TRow[] = []\n  for (const arm of spec.unionSources!) {\n    const coll = db.collection<Record<string, unknown>>(arm.collection)\n    // Optional per-arm FK joins: chain `.join(field, { as, ... })` for\n    // each declared leg before terminating. The aliased right-side\n    // record lands at `sourceRow[leg.as]`, where the arm's `map` reads\n    // it. Cast to `any` because the chained join widens the row type but\n    // the executor treats every row as `Record<string, unknown>` — same\n    // pattern the query-form join path uses.\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    let q: any = coll.query()\n    if (arm.join?.length) {\n      for (const leg of arm.join) {\n        q = q.join(leg.field, { as: leg.as, maxRows: leg.maxRows, strategy: leg.strategy })\n      }\n    }\n    const sourceRows = q.toArray() as ReadonlyArray<Record<string, unknown>>\n    for (const r of sourceRows) {\n      const mapped = arm.map(r)\n      // null / undefined means \"omit this source row\" — skip without\n      // pushing so groupBy/aggregate never see a null entry (#297).\n      if (mapped == null) continue\n      unified.push(mapped)\n    }\n  }\n\n  if (!spec.groupBy) return unified\n\n  const groupFields: readonly string[] =\n    typeof spec.groupBy === 'string' ? [spec.groupBy] : spec.groupBy\n\n  // #285 §2/§4 — i18n-aware group keys. An `i18nText` group field carries a raw\n  // `{ locale: string }` map, an unstable object key. When `i18nLocale` is\n  // declared (with `i18nFields` describing those fields), resolve the declared\n  // group-key i18n fields to it at the `mv` layer FIRST — the same unified-rows\n  // boundary where money is threaded — so buckets are stable strings and the\n  // `mv`-layer `onMissing` policy fires here.\n  if (spec.i18nLocale !== undefined && spec.i18nFields !== undefined) {\n    const groupI18n: Record<string, I18nTextDescriptor> = {}\n    for (const f of groupFields) {\n      const d = spec.i18nFields[f]\n      if (d !== undefined) groupI18n[f] = d\n    }\n    if (Object.keys(groupI18n).length > 0) {\n      for (let i = 0; i < unified.length; i++) {\n        unified[i] = applyI18nLocale(unified[i] as Record<string, unknown>, groupI18n, spec.i18nLocale, undefined, 'mv') as TRow\n      }\n    }\n  }\n  // Guard (always): a remaining object-valued group key — an undeclared i18n\n  // field or a locale-less MV — would bucket on a map. Refuse, don't bucket wrong.\n  for (const f of groupFields) {\n    for (const row of unified) {\n      const v = (row as Record<string, unknown>)[f]\n      if (v !== null && typeof v === 'object') {\n        throw new LocaleNotSpecifiedError(\n          f,\n          `Materialized view \"${spec.name}\" groups by \"${f}\", whose value is a raw i18n locale map — ` +\n            `an unstable object group key. Declare { i18nLocale, i18nFields } on the MV to resolve it at ` +\n            `the 'mv' layer, or group by a dictKey/staticDict code (the stable key) and resolve the label at read time.`,\n        )\n      }\n    }\n  }\n\n  // groupBy without aggregate — dedupe by composite key, keep first\n  // seen row per key. Useful for cross-arm uniqueness (e.g. unify two\n  // sibling collections, keeping one row per natural key).\n  if (!spec.aggregate) {\n    const seen = new Map<string, TRow>()\n    for (const row of unified) {\n      const k = canonicalGroupKey(groupFields, row as Record<string, unknown>)\n      if (!seen.has(k)) seen.set(k, row)\n    }\n    return [...seen.values()]\n  }\n\n  // groupBy + aggregate — delegate to the shared pipeline used by\n  // `Query.groupBy().aggregate()`. Result rows carry each grouped\n  // field in declaration order followed by the spec's reducer outputs.\n  return groupAndReduce<Record<string, unknown>>(unified, groupFields, spec.aggregate, spec.moneyFields)\n}\n\n/**\n * Run an MV's `query()` and write the result rows to the output\n * collection. Same-DEK encryption: routes through the standard\n * `Collection.put` pipeline, so the output collection's DEK is what\n * gets used (matches the v2 spec's \"same DEK as the left-most source\"\n * invariant — `Collection.put` looks up the DEK by collection name,\n * and the output collection IS the MV's owned collection).\n *\n * Stamps `_materializedFrom` onto every emitted row.\n *\n * **Tombstoning:** when `spec.onEmpty: 'delete'` (default), rows\n * that existed in a prior refresh but no longer appear in the new\n * materialized result are deleted via `Collection._internalDelete` —\n * the housekeeping bypass primitive prevents user\n * `onDelete` guards on the output collection from firing on these\n * system-internal deletes. `onEmpty: 'keep'` opts out (rows from\n * prior refreshes linger even when the new result lacks them).\n *\n * **Cost ceiling:** if the materialized row count exceeds\n * `spec.maxRows` (default 100k), throws `MaterializedViewTooLargeError`\n * before any writes hit the store — so strict-mode rollback is\n * clean.\n *\n * **Strict mode:** `spec.strict === true` re-throws on any\n * row-write failure; the active TxContext registration means the\n * source-write rolls back atomically via `revertExecuted`.\n *\n * @internal\n */\nexport const MaterializedViewExecutor = {\n  async refresh(\n    reg: RegisteredMV,\n    accessor: MVExecutorAccessor,\n  ): Promise<RefreshResult> {\n    const spec = reg.spec\n    const outputColl = accessor.getCollection(reg.outputCollection)\n    const maxRows = spec.maxRows ?? DEFAULT_MAX_ROWS\n    const onEmpty = spec.onEmpty ?? 'delete'\n    const strict = spec.strict ?? false\n\n    // 1. Materialize the query (branches on terminal shape). If the\n    //    MV declared predicates, wrap the query context the same way\n    //    the registry did at registration time so `.wherePredicate()`\n    //    calls resolve to the registered functions.\n    const baseCtx = accessor.getQueryContext()\n    const ctxForQuery: MVQueryContext = spec.predicates\n      ? wrapDbWithPredicates(baseCtx, spec.predicates)\n      : baseCtx\n    // UNION-form strategies: read every arm, map to the unified\n    // row shape, concatenate, then optionally groupBy + aggregate. The\n    // single-source `query()` path is untouched.\n    let rows: ReadonlyArray<Record<string, unknown>>\n    if (spec.unionSources) {\n      rows = await materializeUnionResult(spec, ctxForQuery)\n    } else {\n      const q = spec.query!(ctxForQuery)\n      rows = await materializeQueryResult(q, spec.name, spec.i18nLocale, spec.i18nFields)\n    }\n\n    // 2. Cost ceiling check BEFORE any writes — keeps the rollback\n    //    clean if the source-write is wrapped in a transaction.\n    if (rows.length > maxRows) {\n      throw new MaterializedViewTooLargeError(spec.name, rows.length, maxRows)\n    }\n\n    const txCtx = accessor.getActiveTxContext()\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const adapter = (outputColl as any).adapter as {\n      get(v: string, c: string, i: string): Promise<EncryptedEnvelope | null>\n    }\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    const vaultName = (outputColl as any).vault as string\n\n    // 3. Compute the post-refresh id set so we can diff against the\n    //    prior-emitted id set for tombstoning (when onEmpty === 'delete').\n    const newIds = new Set<string>()\n    const enrichedRows: Array<{ id: string; record: Record<string, unknown> }> = []\n    for (const row of rows) {\n      const id = spec.rowKey(row)\n      newIds.add(id)\n      const meta: MaterializedFromMeta = {\n        mvName: spec.name,\n        queryHash: reg.queryHash,\n        sourceVersions: {},\n        materializedAt: new Date().toISOString(),\n      }\n      enrichedRows.push({ id, record: { ...row, _materializedFrom: meta } })\n    }\n\n    // 4. Write the new rows.\n    let written = 0\n    let failed = 0\n    for (const { id, record } of enrichedRows) {\n      try {\n        if (txCtx !== null) {\n          const prior = await adapter.get(vaultName, reg.outputCollection, id)\n          txCtx._executed.push({\n            op: { type: 'put', vaultName, collectionName: reg.outputCollection, id },\n            priorEnvelope: prior,\n          })\n        }\n        await outputColl.put(id, record)\n        written++\n      } catch (err) {\n        failed++\n        if (strict) throw err\n         \n        console.warn(`[mv] \"${spec.name}\" row write failed:`, err)\n      }\n    }\n\n    // 5. Tombstone rows that existed before but don't appear now.\n    //    `onEmpty: 'keep'` skips this pass entirely. Uses\n    //    `_internalDelete` so a user-registered `onDelete` on the\n    //    output collection does NOT fire on housekeeping (composition fix).\n    let deleted = 0\n    if (onEmpty === 'delete') {\n      const priorIds = await listOutputIds(outputColl)\n      for (const priorId of priorIds) {\n        if (newIds.has(priorId)) continue\n        try {\n          // eslint-disable-next-line @typescript-eslint/no-explicit-any\n          const outAny = outputColl as any\n          if (typeof outAny._internalDelete === 'function') {\n            await outAny._internalDelete(priorId, txCtx)\n            deleted++\n          } else {\n            // Defensive fallback — should never hit in real flow since\n            // every Collection has `_internalDelete`.\n            await outputColl.delete(priorId)\n            deleted++\n          }\n        } catch (err) {\n          failed++\n          if (strict) throw err\n           \n          console.warn(`[mv] \"${spec.name}\" tombstone failed for id=\"${priorId}\":`, err)\n        }\n      }\n    }\n\n    return { written, deleted, failed }\n  },\n}\n\n/**\n * List ids currently present in the MV's output collection via the\n * adapter directly (avoids triggering the lazy resolve-on-read path\n * we're INSIDE). Returns an empty array if the collection doesn't\n * exist or the adapter doesn't surface a list method.\n *\n * @internal\n */\nasync function listOutputIds(\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  outputColl: Collection<any>,\n): Promise<string[]> {\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const cAny = outputColl as any\n  const adapter = cAny.adapter as { list?: (v: string, c: string) => Promise<readonly string[]> }\n  const vault = cAny.vault as string\n  const name = cAny.name as string\n  if (typeof adapter?.list !== 'function') return []\n  try {\n    const ids = await adapter.list(vault, name)\n    return [...ids]\n  } catch {\n    return []\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-SQXTKZL7.js

@@ -0,0 +1,125 @@
+import {
+  NOYDB_FORMAT_VERSION
+} from "./chunk-A7DNZVAV.js";
+import {
+  decrypt,
+  encrypt
+} from "./chunk-E2MDPPOC.js";
+
+// src/forget/strategy.ts
+var NO_FORGET = { subjects: {} };
+function withForgetCascade(opts) {
+  return { subjects: { ...opts.subjects } };
+}
+
+// src/forget/subject-index.ts
+var SUBJECT_INDEX_COLLECTION = "_subject_index";
+async function sha256HexString(input) {
+  const bytes = new TextEncoder().encode(input);
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", bytes);
+  return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+async function subjectKey(subjectId) {
+  return sha256HexString(subjectId);
+}
+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 JSON.parse(env._data);
+  const dek = await getDEK(SUBJECT_INDEX_COLLECTION);
+  const json = await decrypt(env._iv, env._data, dek);
+  return JSON.parse(json);
+}
+async function writeRefs(adapter, vault, getDEK, encrypted, key, refs) {
+  const json = JSON.stringify(refs);
+  let env;
+  if (!encrypted) {
+    env = { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: (/* @__PURE__ */ new Date()).toISOString(), _iv: "", _data: json };
+  } else {
+    const dek = await getDEK(SUBJECT_INDEX_COLLECTION);
+    const { iv, data } = await encrypt(json, 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 subjectKey(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) {
+  const key = await subjectKey(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) return;
+  if (next.length === 0) {
+    await adapter.delete(vault, SUBJECT_INDEX_COLLECTION, key);
+    return;
+  }
+  await writeRefs(adapter, vault, getDEK, encrypted, key, next);
+}
+async function lookupSubject(adapter, vault, getDEK, encrypted, subjectId) {
+  const key = await subjectKey(subjectId);
+  return readRefs(adapter, vault, getDEK, encrypted, key);
+}
+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 subjectKey(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,
+  withForgetCascade,
+  SUBJECT_INDEX_COLLECTION,
+  addSubjectRef,
+  removeSubjectRef,
+  lookupSubject,
+  rebuildSubjectIndex,
+  coerceSubjectId,
+  readDottedPath
+};
+//# sourceMappingURL=chunk-SQXTKZL7.js.map

package/dist/chunk-SQXTKZL7.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/forget/strategy.ts","../src/forget/subject-index.ts"],"sourcesContent":["/**\n * `withForgetCascade` — declaration surface for GDPR right-to-erasure via\n * per-record CEK crypto-shred (#304, step 2 of the CEK security epic).\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 '../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/**\n * Declare GDPR crypto-shred for one or more collections.\n *\n * Each declared collection is forced to `perRecordKeys: true` (a shred can\n * only guarantee erasure of a record whose body is keyed off a per-record\n * CEK). On write, Noydb extracts `record[subjectField]` and maintains an\n * encrypted `_subject_index` mapping `subject → [{collection, id}]`, so\n * `vault.forget(subjectId)` can find every record for a subject and rewrite\n * each to a tombstone (body + history permanently undecryptable) while the\n * collection DEK and every other record stay intact.\n *\n * @example\n * ```ts\n * createNoydb({\n *   secret, user,\n *   forgetStrategy: withForgetCascade({ subjects: { invoices: 'buyerId' } }),\n * })\n * const result = await vault.forget('buyer-123')\n * // → { subject, recordsShredded, historyVersionsShredded, collections, … }\n * ```\n */\nexport function withForgetCascade(opts: SubjectDeclaration): ForgetStrategy {\n  return { subjects: { ...opts.subjects } }\n}\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 (#365): 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 * subsystem 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 (#401). 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 (#401) — 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  /** The single `op:'forget'` ledger entry appended for this erasure. */\n  readonly ledgerEntry: LedgerEntry\n}\n","/**\n * The encrypted subject index (#304).\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  = `sha256Hex(subjectId)` — the raw subject id never appears\n *     as a key, so the store can't correlate index entries to a known subject.\n *   - record body = AES-GCM(JSON `[{ collection, id }]`) under the index DEK.\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, decrypt } from '../crypto.js'\nimport type { NoydbStore, EncryptedEnvelope } from '../types.js'\nimport { NOYDB_FORMAT_VERSION } from '../types.js'\n\n/** Reserved collection holding the encrypted subject → records index. */\nexport const SUBJECT_INDEX_COLLECTION = '_subject_index'\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<CryptoKey>\n\n/** SHA-256 hex of a UTF-8 string. The subject-index record key derivation. */\nasync function sha256HexString(input: string): Promise<string> {\n  const bytes = new TextEncoder().encode(input)\n  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)\n  return Array.from(new Uint8Array(digest))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n\n/** Stable subject-index record id for a subject id. */\nexport async function subjectKey(subjectId: string): Promise<string> {\n  return sha256HexString(subjectId)\n}\n\n/** Read + decrypt the ref list for a subject. 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 JSON.parse(env._data) as SubjectRef[]\n  const dek = await getDEK(SUBJECT_INDEX_COLLECTION)\n  const json = await decrypt(env._iv, env._data, dek)\n  return JSON.parse(json) as SubjectRef[]\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  const json = JSON.stringify(refs)\n  let env: EncryptedEnvelope\n  if (!encrypted) {\n    env = { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: new Date().toISOString(), _iv: '', _data: json }\n  } else {\n    const dek = await getDEK(SUBJECT_INDEX_COLLECTION)\n    const { iv, data } = await encrypt(json, 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 subjectKey(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  const key = await subjectKey(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) return\n  if (next.length === 0) {\n    await adapter.delete(vault, SUBJECT_INDEX_COLLECTION, key)\n    return\n  }\n  await writeRefs(adapter, vault, getDEK, encrypted, key, next)\n}\n\n/** Look up every record ref for a subject. Returns `[]` when none exist. */\nexport async function lookupSubject(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  subjectId: string,\n): Promise<SubjectRef[]> {\n  const key = await subjectKey(subjectId)\n  return readRefs(adapter, vault, getDEK, encrypted, key)\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 subjectKey(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-STNPB3UM.js

@@ -0,0 +1,9 @@
+// src/util/discriminant.ts
+function isDiscriminant(record, key, value) {
+  return record[key] === value;
+}
+
+export {
+  isDiscriminant
+};
+//# sourceMappingURL=chunk-STNPB3UM.js.map

package/dist/chunk-STNPB3UM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/util/discriminant.ts"],"sourcesContent":["/**\n * Type-guard helper for narrowing discriminated-union records.\n *\n * `Collection<T>` correctly threads `T` through `get` / `query` / `scan`, but\n * accessing member-specific fields after reading from a `Collection<Union>`\n * still requires a narrowing step in application code. In regular `.ts` files\n * a simple `if (r.kind === 'IV')` block narrows correctly; in vue-tsc /\n * template contexts the inline comparison is sometimes not enough, and the\n * helper below makes the guard portable and avoids `as unknown as …` casts.\n *\n * **Usage with Collection<T>**\n *\n * ```ts\n * import { isDiscriminant } from '@noy-db/hub'\n *\n * type IV = { kind: 'IV'; invoiceNo: string; amount: number }\n * type RE = { kind: 'RE'; receiptNo: string; paidAt: string }\n * type Receipt = IV | RE | ...\n *\n * const receipts = await vault.collection<Receipt>('receipts').query().toArray()\n *\n * // Filter approach — result is IV[], invoiceNo accessible without cast:\n * const ivs = receipts.filter(r => isDiscriminant(r, 'kind', 'IV'))\n * console.log(ivs[0].invoiceNo)\n *\n * // Branch approach:\n * for (const r of receipts) {\n *   if (isDiscriminant(r, 'kind', 'IV')) {\n *     console.log(r.invoiceNo)  // r: IV here\n *   }\n * }\n * ```\n *\n * @module\n */\n\n/**\n * Type-guard for narrowing a discriminated-union record by its discriminant.\n *\n * Returns `true` when `record[key] === value`, and narrows `record` to\n * `Extract<T, Record<K, V>>` — the exact union member(s) that carry that\n * discriminant value.\n *\n * The discriminant key is a parameter (not hardcoded to `'kind'`), so this\n * works with any field name: `'kind'`, `'type'`, `'tag'`, etc.\n *\n * @example\n *   const ivs = receipts.filter(r => isDiscriminant(r, 'kind', 'IV'))\n *   // ivs: IV[]  — invoiceNo accessible, no cast needed\n *\n * @typeParam T - The union type of the record (e.g. `Receipt`). Both type-alias\n *   unions and interface-extended unions work; use a `type` alias (`type Receipt = IV | RE`) for best\n *   results.\n * @typeParam K - The discriminant key (must be a key of `T`).\n * @typeParam V - The discriminant value to match. The `const` modifier ensures\n *   TypeScript infers the string literal (e.g. `'IV'`), not the full union\n *   `T[K]`, so the predicate resolves to the exact member type.\n */\nexport function isDiscriminant<\n  T,\n  K extends keyof T,\n  const V extends T[K],\n>(record: T, key: K, value: V): record is Extract<T, Record<K, V>> {\n  return (record as Record<PropertyKey, unknown>)[key as PropertyKey] === value\n}\n"],"mappings":";AA0DO,SAAS,eAId,QAAW,KAAQ,OAA8C;AACjE,SAAQ,OAAwC,GAAkB,MAAM;AAC1E;","names":[]}

package/dist/{chunk-NSLTPGEN.js → chunk-TMUMMAWV.js}

@@ -2,7 +2,7 @@ import {
   OverlayBaseIsVirtualError,
   OverlayCollectionUnavailableError,
   OverlayNameCollisionError
-} from "./chunk-YDLAFP36.js";
+} from "./chunk-JZ5DS4DP.js";
 
 // src/overlay-views/registry.ts
 var OverlayedViewRegistry = class {
@@ -37,6 +37,16 @@ var OverlayedViewRegistry = class {
   isOverlay(name) {
     return this._byName.has(name);
   }
+  /**
+   * All registered overlay strategies as a flat array.
+   * Each strategy carries `name`, `base`, and `overlay` fields that
+   * `describeOverlays()` in the introspection walker reads directly.
+   *
+   * Used by `dumpSchema()` to populate the `overlayViews` map.
+   */
+  all() {
+    return [...this._byName.values()];
+  }
   /**
    * Resolve the `rowKey` function for an overlay's base MV. Returns
    * `undefined` if the base isn't an MV (raw source collection) or
@@ -58,4 +68,4 @@ var OverlayedViewRegistry = class {
 export {
   OverlayedViewRegistry
 };
-//# sourceMappingURL=chunk-NSLTPGEN.js.map
+//# sourceMappingURL=chunk-TMUMMAWV.js.map

package/dist/{chunk-NSLTPGEN.js.map → chunk-TMUMMAWV.js.map}

@@ -1 +1 @@
-{"version":3,"sources":["../src/overlay-views/registry.ts"],"sourcesContent":["import {\n  OverlayBaseIsVirtualError,\n  OverlayCollectionUnavailableError,\n  OverlayNameCollisionError,\n} from '../errors.js'\nimport type { MaterializedViewRegistry } from '../materialized-views/registry.js'\nimport type { OverlayedViewStrategy } from './types.js'\n\n/**\n * Vault-internal registry of overlay strategies. Resolves the base\n * MV's `rowKey` lazily so virtual-collection writes can derive ids\n * from the row.\n *\n * @internal\n */\nexport class OverlayedViewRegistry {\n  private readonly _byName = new Map<string, OverlayedViewStrategy>()\n\n  /**\n   * Register an overlay. Validates name uniqueness, base concreteness,\n   * and overlay availability AGAINST the MV registry — overlays\n   * declared without the MV registry context skip cross-registry\n   * checks but still validate self-consistency.\n   */\n  register(\n    spec: OverlayedViewStrategy,\n    options: {\n      isOverlayName?: (name: string) => boolean\n      isMVOutput?: (name: string) => boolean\n      isKnownCollection?: (name: string) => boolean\n    },\n  ): void {\n    const { isOverlayName, isMVOutput, isKnownCollection } = options\n\n    // 1. Virtual name must not collide with an MV output or a concrete\n    //    source collection. Concrete-source detection is best-effort:\n    //    if `isKnownCollection` is supplied, a hit there + no MV match\n    //    is treated as a collision.\n    if (isMVOutput?.(spec.name) || isOverlayName?.(spec.name)) {\n      throw new OverlayNameCollisionError(spec.name)\n    }\n    // (We don't check isKnownCollection for `name` collision because\n    // virtual names are typically NOT pre-existing — they're created\n    // by the overlay declaration itself. Future versions may tighten.)\n\n    // 2. base must be concrete: NOT another overlay's virtual name.\n    if (isOverlayName?.(spec.base)) {\n      throw new OverlayBaseIsVirtualError(spec.name, spec.base)\n    }\n\n    // 3. overlay must be available: a real, vault-known collection\n    //    that is NOT an MV output (since MVs own their outputs).\n    if (isMVOutput?.(spec.overlay)) {\n      throw new OverlayCollectionUnavailableError(spec.name, spec.overlay)\n    }\n    // Best-effort known-collection check — when the vault can answer\n    // it. Unknown collections aren't a hard failure (the overlay may\n    // be implicitly created on first write), so we only throw on the\n    // MV-output case above.\n    void isKnownCollection\n\n    this._byName.set(spec.name, spec)\n  }\n\n  byName(name: string): OverlayedViewStrategy | undefined {\n    return this._byName.get(name)\n  }\n\n  /** All overlay virtual names. */\n  names(): ReadonlySet<string> {\n    return new Set(this._byName.keys())\n  }\n\n  isOverlay(name: string): boolean {\n    return this._byName.has(name)\n  }\n\n  /**\n   * Resolve the `rowKey` function for an overlay's base MV. Returns\n   * `undefined` if the base isn't an MV (raw source collection) or\n   * if the MV registry isn't supplied. Used by the virtual-collection\n   * proxy to derive ids from `put(record)` calls.\n   */\n  resolveBaseRowKey(\n    name: string,\n    mvRegistry: MaterializedViewRegistry | null,\n  ): ((row: Record<string, unknown>) => string) | undefined {\n    const spec = this._byName.get(name)\n    if (!spec || !mvRegistry) return undefined\n    // The base might be an MV's `output.collection` OR the MV's `name`\n    // (when no output.collection is declared). Search by both.\n    for (const reg of mvRegistry.all()) {\n      if (reg.outputCollection === spec.base || reg.spec.name === spec.base) {\n        return (row) => reg.spec.rowKey(row)\n      }\n    }\n    return undefined\n  }\n}\n"],"mappings":";;;;;;;AAeO,IAAM,wBAAN,MAA4B;AAAA,EAChB,UAAU,oBAAI,IAAmC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQlE,SACE,MACA,SAKM;AACN,UAAM,EAAE,eAAe,YAAY,kBAAkB,IAAI;AAMzD,QAAI,aAAa,KAAK,IAAI,KAAK,gBAAgB,KAAK,IAAI,GAAG;AACzD,YAAM,IAAI,0BAA0B,KAAK,IAAI;AAAA,IAC/C;AAMA,QAAI,gBAAgB,KAAK,IAAI,GAAG;AAC9B,YAAM,IAAI,0BAA0B,KAAK,MAAM,KAAK,IAAI;AAAA,IAC1D;AAIA,QAAI,aAAa,KAAK,OAAO,GAAG;AAC9B,YAAM,IAAI,kCAAkC,KAAK,MAAM,KAAK,OAAO;AAAA,IACrE;AAKA,SAAK;AAEL,SAAK,QAAQ,IAAI,KAAK,MAAM,IAAI;AAAA,EAClC;AAAA,EAEA,OAAO,MAAiD;AACtD,WAAO,KAAK,QAAQ,IAAI,IAAI;AAAA,EAC9B;AAAA;AAAA,EAGA,QAA6B;AAC3B,WAAO,IAAI,IAAI,KAAK,QAAQ,KAAK,CAAC;AAAA,EACpC;AAAA,EAEA,UAAU,MAAuB;AAC/B,WAAO,KAAK,QAAQ,IAAI,IAAI;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,kBACE,MACA,YACwD;AACxD,UAAM,OAAO,KAAK,QAAQ,IAAI,IAAI;AAClC,QAAI,CAAC,QAAQ,CAAC,WAAY,QAAO;AAGjC,eAAW,OAAO,WAAW,IAAI,GAAG;AAClC,UAAI,IAAI,qBAAqB,KAAK,QAAQ,IAAI,KAAK,SAAS,KAAK,MAAM;AACrE,eAAO,CAAC,QAAQ,IAAI,KAAK,OAAO,GAAG;AAAA,MACrC;AAAA,IACF;AACA,WAAO;AAAA,EACT;AACF;","names":[]}
+{"version":3,"sources":["../src/overlay-views/registry.ts"],"sourcesContent":["import {\n  OverlayBaseIsVirtualError,\n  OverlayCollectionUnavailableError,\n  OverlayNameCollisionError,\n} from '../errors.js'\nimport type { MaterializedViewRegistry } from '../materialized-views/registry.js'\nimport type { OverlayedViewStrategy } from './types.js'\n\n/**\n * Vault-internal registry of overlay strategies. Resolves the base\n * MV's `rowKey` lazily so virtual-collection writes can derive ids\n * from the row.\n *\n * @internal\n */\nexport class OverlayedViewRegistry {\n  private readonly _byName = new Map<string, OverlayedViewStrategy>()\n\n  /**\n   * Register an overlay. Validates name uniqueness, base concreteness,\n   * and overlay availability AGAINST the MV registry — overlays\n   * declared without the MV registry context skip cross-registry\n   * checks but still validate self-consistency.\n   */\n  register(\n    spec: OverlayedViewStrategy,\n    options: {\n      isOverlayName?: (name: string) => boolean\n      isMVOutput?: (name: string) => boolean\n      isKnownCollection?: (name: string) => boolean\n    },\n  ): void {\n    const { isOverlayName, isMVOutput, isKnownCollection } = options\n\n    // 1. Virtual name must not collide with an MV output or a concrete\n    //    source collection. Concrete-source detection is best-effort:\n    //    if `isKnownCollection` is supplied, a hit there + no MV match\n    //    is treated as a collision.\n    if (isMVOutput?.(spec.name) || isOverlayName?.(spec.name)) {\n      throw new OverlayNameCollisionError(spec.name)\n    }\n    // (We don't check isKnownCollection for `name` collision because\n    // virtual names are typically NOT pre-existing — they're created\n    // by the overlay declaration itself. Future versions may tighten.)\n\n    // 2. base must be concrete: NOT another overlay's virtual name.\n    if (isOverlayName?.(spec.base)) {\n      throw new OverlayBaseIsVirtualError(spec.name, spec.base)\n    }\n\n    // 3. overlay must be available: a real, vault-known collection\n    //    that is NOT an MV output (since MVs own their outputs).\n    if (isMVOutput?.(spec.overlay)) {\n      throw new OverlayCollectionUnavailableError(spec.name, spec.overlay)\n    }\n    // Best-effort known-collection check — when the vault can answer\n    // it. Unknown collections aren't a hard failure (the overlay may\n    // be implicitly created on first write), so we only throw on the\n    // MV-output case above.\n    void isKnownCollection\n\n    this._byName.set(spec.name, spec)\n  }\n\n  byName(name: string): OverlayedViewStrategy | undefined {\n    return this._byName.get(name)\n  }\n\n  /** All overlay virtual names. */\n  names(): ReadonlySet<string> {\n    return new Set(this._byName.keys())\n  }\n\n  isOverlay(name: string): boolean {\n    return this._byName.has(name)\n  }\n\n  /**\n   * All registered overlay strategies as a flat array.\n   * Each strategy carries `name`, `base`, and `overlay` fields that\n   * `describeOverlays()` in the introspection walker reads directly.\n   *\n   * Used by `dumpSchema()` to populate the `overlayViews` map.\n   */\n  all(): ReadonlyArray<OverlayedViewStrategy> {\n    return [...this._byName.values()]\n  }\n\n  /**\n   * Resolve the `rowKey` function for an overlay's base MV. Returns\n   * `undefined` if the base isn't an MV (raw source collection) or\n   * if the MV registry isn't supplied. Used by the virtual-collection\n   * proxy to derive ids from `put(record)` calls.\n   */\n  resolveBaseRowKey(\n    name: string,\n    mvRegistry: MaterializedViewRegistry | null,\n  ): ((row: Record<string, unknown>) => string) | undefined {\n    const spec = this._byName.get(name)\n    if (!spec || !mvRegistry) return undefined\n    // The base might be an MV's `output.collection` OR the MV's `name`\n    // (when no output.collection is declared). Search by both.\n    for (const reg of mvRegistry.all()) {\n      if (reg.outputCollection === spec.base || reg.spec.name === spec.base) {\n        return (row) => reg.spec.rowKey(row)\n      }\n    }\n    return undefined\n  }\n}\n"],"mappings":";;;;;;;AAeO,IAAM,wBAAN,MAA4B;AAAA,EAChB,UAAU,oBAAI,IAAmC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQlE,SACE,MACA,SAKM;AACN,UAAM,EAAE,eAAe,YAAY,kBAAkB,IAAI;AAMzD,QAAI,aAAa,KAAK,IAAI,KAAK,gBAAgB,KAAK,IAAI,GAAG;AACzD,YAAM,IAAI,0BAA0B,KAAK,IAAI;AAAA,IAC/C;AAMA,QAAI,gBAAgB,KAAK,IAAI,GAAG;AAC9B,YAAM,IAAI,0BAA0B,KAAK,MAAM,KAAK,IAAI;AAAA,IAC1D;AAIA,QAAI,aAAa,KAAK,OAAO,GAAG;AAC9B,YAAM,IAAI,kCAAkC,KAAK,MAAM,KAAK,OAAO;AAAA,IACrE;AAKA,SAAK;AAEL,SAAK,QAAQ,IAAI,KAAK,MAAM,IAAI;AAAA,EAClC;AAAA,EAEA,OAAO,MAAiD;AACtD,WAAO,KAAK,QAAQ,IAAI,IAAI;AAAA,EAC9B;AAAA;AAAA,EAGA,QAA6B;AAC3B,WAAO,IAAI,IAAI,KAAK,QAAQ,KAAK,CAAC;AAAA,EACpC;AAAA,EAEA,UAAU,MAAuB;AAC/B,WAAO,KAAK,QAAQ,IAAI,IAAI;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,MAA4C;AAC1C,WAAO,CAAC,GAAG,KAAK,QAAQ,OAAO,CAAC;AAAA,EAClC;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,kBACE,MACA,YACwD;AACxD,UAAM,OAAO,KAAK,QAAQ,IAAI,IAAI;AAClC,QAAI,CAAC,QAAQ,CAAC,WAAY,QAAO;AAGjC,eAAW,OAAO,WAAW,IAAI,GAAG;AAClC,UAAI,IAAI,qBAAqB,KAAK,QAAQ,IAAI,KAAK,SAAS,KAAK,MAAM;AACrE,eAAO,CAAC,QAAQ,IAAI,KAAK,OAAO,GAAG;AAAA,MACrC;AAAA,IACF;AACA,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/{chunk-LS3JLEIB.js → chunk-TZGWI5AX.js}

@@ -3,17 +3,17 @@ import {
 } from "./chunk-2QR2PQTT.js";
 import {
   NOYDB_SYNC_VERSION
-} from "./chunk-FXQYZNOW.js";
+} from "./chunk-A7DNZVAV.js";
 import {
   bufferToBase64,
   decrypt,
   derivePresenceKey,
   encrypt,
   generateIV
-} from "./chunk-UOF74WQY.js";
+} from "./chunk-E2MDPPOC.js";
 import {
   ConflictError
-} from "./chunk-YDLAFP36.js";
+} from "./chunk-JZ5DS4DP.js";
 
 // src/team/presence.ts
 var PresenceHandle = class {
@@ -719,4 +719,4 @@ export {
   SyncEngine,
   SyncTransaction
 };
-//# sourceMappingURL=chunk-LS3JLEIB.js.map
+//# sourceMappingURL=chunk-TZGWI5AX.js.map

package/dist/{chunk-GD3BGKAR.js → chunk-UBF5JEOJ.js}

@@ -1,13 +1,17 @@
 import {
   DerivationCycleError
-} from "./chunk-YDLAFP36.js";
+} from "./chunk-JZ5DS4DP.js";
 
 // src/derivations/strategy-hash.ts
-async function computeStrategyHash(source, outputKeys, derive) {
+async function computeStrategyHash(source, outputKeys, derive, sources) {
   const canonical = JSON.stringify({
     source,
     outputs: [...outputKeys].sort(),
-    derive: derive.toString()
+    derive: derive.toString(),
+    // Declared sibling sources (#344) — adding/removing a trigger
+    // collection invalidates cached derived records. Omitted when empty
+    // so strategies without siblings keep their existing hash.
+    ...sources?.length ? { sources: [...sources].sort() } : {}
   });
   const bytes = new TextEncoder().encode(canonical);
   const digest = await crypto.subtle.digest("SHA-256", bytes);
@@ -21,11 +25,26 @@ var DerivationRegistry = class {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   async register(spec) {
     const outputKeys = Object.keys(spec.outputs);
-    const strategyHash = await computeStrategyHash(spec.source, outputKeys, spec.derive);
+    const strategyHash = await computeStrategyHash(spec.source, outputKeys, spec.derive, spec.sources);
     const reg = { spec, strategyHash };
     const fromSource = this._bySource.get(spec.source);
     if (fromSource) fromSource.push(reg);
     else this._bySource.set(spec.source, [reg]);
+    for (const extra of spec.sources ?? []) {
+      const fromExtra = this._bySource.get(extra);
+      if (fromExtra) fromExtra.push(reg);
+      else this._bySource.set(extra, [reg]);
+    }
+    for (const t of spec.triggerBy ?? []) {
+      const fromTrigger = this._bySource.get(t.collection);
+      if (fromTrigger) fromTrigger.push(reg);
+      else this._bySource.set(t.collection, [reg]);
+    }
+    if (spec.rollup) {
+      const fromRollup = this._bySource.get(spec.rollup.from);
+      if (fromRollup) fromRollup.push(reg);
+      else this._bySource.set(spec.rollup.from, [reg]);
+    }
     for (const key of outputKeys) {
       const output = spec.outputs[key];
       if (!output) continue;
@@ -41,6 +60,23 @@ var DerivationRegistry = class {
   strategiesProducingOutput(collection) {
     return this._byOutput.get(collection) ?? [];
   }
+  /**
+   * All registered strategies as a flat, deduplicated array.
+   * Each strategy is indexed once per source (not once per output key),
+   * so iterating `_bySource.values()` naturally yields each strategy
+   * exactly once per source — deduplication is handled by flattening
+   * the per-source arrays and collecting into a Set by identity.
+   *
+   * Used by `dumpSchema()` / `describeDerivations()` in the introspection
+   * walker to populate the derivations map.
+   */
+  all() {
+    const seen = /* @__PURE__ */ new Set();
+    for (const strategies of this._bySource.values()) {
+      for (const s of strategies) seen.add(s);
+    }
+    return [...seen];
+  }
   /**
    * Cycle detection over the source → output → … graph. Call after all
    * `register()` calls complete (i.e. at vault open). Throws
@@ -62,6 +98,9 @@ var DerivationRegistry = class {
           for (const key of Object.keys(s.spec.outputs)) {
             const output = s.spec.outputs[key];
             if (!output) continue;
+            if (output.shape === "record" && output.collection === s.spec.source && output.denorm !== void 0) {
+              continue;
+            }
             visit(output.collection);
           }
         }
@@ -76,4 +115,4 @@ var DerivationRegistry = class {
 export {
   DerivationRegistry
 };
-//# sourceMappingURL=chunk-GD3BGKAR.js.map
+//# sourceMappingURL=chunk-UBF5JEOJ.js.map

package/dist/chunk-UBF5JEOJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/derivations/strategy-hash.ts","../src/derivations/registry.ts"],"sourcesContent":["/**\n * Deterministic hash of a derivation strategy's \"shape\": source\n * collection, declared sibling sources, output keys, derive function\n * source. Used to detect\n * strategy drift: a record whose `_derivedFrom.strategyHash` doesn't\n * match the current strategy is considered stale.\n *\n * Web Crypto SHA-256 — no extra deps.\n */\nexport async function computeStrategyHash(\n  source: string,\n  outputKeys: readonly string[],\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  derive: (...args: any[]) => any,\n  sources?: ReadonlyArray<string>,\n): Promise<string> {\n  const canonical = JSON.stringify({\n    source,\n    outputs: [...outputKeys].sort(),\n    derive: derive.toString(),\n    // Declared sibling sources (#344) — adding/removing a trigger\n    // collection invalidates cached derived records. Omitted when empty\n    // so strategies without siblings keep their existing hash.\n    ...(sources?.length ? { sources: [...sources].sort() } : {}),\n  })\n  const bytes = new TextEncoder().encode(canonical)\n  const digest = await crypto.subtle.digest('SHA-256', bytes)\n  return Array.from(new Uint8Array(digest))\n    .map(b => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n","import { DerivationCycleError } from '../errors.js'\nimport { computeStrategyHash } from './strategy-hash.js'\nimport type { DerivationStrategy } from './types.js'\n\ninterface RegisteredStrategy {\n  // Type-erased to allow the registry to hold heterogeneous strategies.\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  spec: DerivationStrategy<any, any>\n  strategyHash: string\n}\n\n/**\n * Vault-internal registry of derivation strategies. Owned by `Vault`;\n * not exported.\n *\n * @internal\n */\nexport class DerivationRegistry {\n  private readonly _bySource = new Map<string, RegisteredStrategy[]>()\n  private readonly _byOutput = new Map<string, RegisteredStrategy[]>()\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  async register(spec: DerivationStrategy<any, any>): Promise<void> {\n    const outputKeys = Object.keys(spec.outputs)\n    const strategyHash = await computeStrategyHash(spec.source, outputKeys, spec.derive, spec.sources)\n    const reg: RegisteredStrategy = { spec, strategyHash }\n\n    const fromSource = this._bySource.get(spec.source)\n    if (fromSource) fromSource.push(reg)\n    else this._bySource.set(spec.source, [reg])\n\n    // Declared sibling sources (#344) index the SAME `reg` under each\n    // extra collection so `strategiesForSource(extra)` returns it and a\n    // sibling write re-fires the derivation. Sibling keys also enter\n    // `_bySource`, so `validate()`'s cycle DFS walks them automatically.\n    for (const extra of spec.sources ?? []) {\n      const fromExtra = this._bySource.get(extra)\n      if (fromExtra) fromExtra.push(reg)\n      else this._bySource.set(extra, [reg])\n    }\n\n    // FK triggers (#376) index the SAME `reg` under each parent collection so\n    // a parent write re-fires the derivation (fanned out to matching source\n    // records in `dispatchDerivations`). Like sources[], these keys enter\n    // `_bySource` so the cycle DFS walks the trigger→output edge.\n    for (const t of spec.triggerBy ?? []) {\n      const fromTrigger = this._bySource.get(t.collection)\n      if (fromTrigger) fromTrigger.push(reg)\n      else this._bySource.set(t.collection, [reg])\n    }\n\n    // Rollup (#376 slice 2): a write to the child `from` collection recomputes\n    // the parent (= spec.source = into) at id child[key]. Index under `from`\n    // so a child write fires it; spec.source (into) is already indexed above,\n    // so a parent write also recomputes its own aggregate (covers the\n    // parent-created-after-children case). The from→into edge enters the cycle\n    // DFS automatically.\n    if (spec.rollup) {\n      const fromRollup = this._bySource.get(spec.rollup.from)\n      if (fromRollup) fromRollup.push(reg)\n      else this._bySource.set(spec.rollup.from, [reg])\n    }\n\n    for (const key of outputKeys) {\n      const output = spec.outputs[key]\n      if (!output) continue\n      const outputCollection = output.collection\n      const arr = this._byOutput.get(outputCollection)\n      if (arr) arr.push(reg)\n      else this._byOutput.set(outputCollection, [reg])\n    }\n  }\n\n  strategiesForSource(source: string): ReadonlyArray<RegisteredStrategy> {\n    return this._bySource.get(source) ?? []\n  }\n\n  strategiesProducingOutput(collection: string): ReadonlyArray<RegisteredStrategy> {\n    return this._byOutput.get(collection) ?? []\n  }\n\n  /**\n   * All registered strategies as a flat, deduplicated array.\n   * Each strategy is indexed once per source (not once per output key),\n   * so iterating `_bySource.values()` naturally yields each strategy\n   * exactly once per source — deduplication is handled by flattening\n   * the per-source arrays and collecting into a Set by identity.\n   *\n   * Used by `dumpSchema()` / `describeDerivations()` in the introspection\n   * walker to populate the derivations map.\n   */\n  all(): ReadonlyArray<RegisteredStrategy> {\n    const seen = new Set<RegisteredStrategy>()\n    for (const strategies of this._bySource.values()) {\n      for (const s of strategies) seen.add(s)\n    }\n    return [...seen]\n  }\n\n  /**\n   * Cycle detection over the source → output → … graph. Call after all\n   * `register()` calls complete (i.e. at vault open). Throws\n   * `DerivationCycleError` on the first cycle found.\n   */\n  validate(): void {\n    const visited = new Set<string>()\n    const stack: string[] = []\n\n    const visit = (node: string): void => {\n      if (stack.includes(node)) {\n        const cycle = stack.slice(stack.indexOf(node)).concat(node)\n        throw new DerivationCycleError(cycle)\n      }\n      if (visited.has(node)) return\n      stack.push(node)\n      const strategies = this._bySource.get(node)\n      if (strategies) {\n        for (const s of strategies) {\n          for (const key of Object.keys(s.spec.outputs)) {\n            const output = s.spec.outputs[key]\n            if (!output) continue\n            // Self-write reverse-denorm (#376): an output back to its own\n            // source is intentional, not an infinite cycle — the value-equality\n            // guard in dispatch terminates it. Skip this edge so it isn't\n            // flagged. (Self-write outputs are required to declare `denorm`.)\n            if (\n              output.shape === 'record' &&\n              output.collection === s.spec.source &&\n              output.denorm !== undefined\n            ) {\n              continue\n            }\n            visit(output.collection)\n          }\n        }\n      }\n      stack.pop()\n      visited.add(node)\n    }\n\n    for (const src of this._bySource.keys()) visit(src)\n  }\n}\n"],"mappings":";;;;;AASA,eAAsB,oBACpB,QACA,YAEA,QACA,SACiB;AACjB,QAAM,YAAY,KAAK,UAAU;AAAA,IAC/B;AAAA,IACA,SAAS,CAAC,GAAG,UAAU,EAAE,KAAK;AAAA,IAC9B,QAAQ,OAAO,SAAS;AAAA;AAAA;AAAA;AAAA,IAIxB,GAAI,SAAS,SAAS,EAAE,SAAS,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC;AAAA,EAC5D,CAAC;AACD,QAAM,QAAQ,IAAI,YAAY,EAAE,OAAO,SAAS;AAChD,QAAM,SAAS,MAAM,OAAO,OAAO,OAAO,WAAW,KAAK;AAC1D,SAAO,MAAM,KAAK,IAAI,WAAW,MAAM,CAAC,EACrC,IAAI,OAAK,EAAE,SAAS,EAAE,EAAE,SAAS,GAAG,GAAG,CAAC,EACxC,KAAK,EAAE;AACZ;;;ACbO,IAAM,qBAAN,MAAyB;AAAA,EACb,YAAY,oBAAI,IAAkC;AAAA,EAClD,YAAY,oBAAI,IAAkC;AAAA;AAAA,EAGnE,MAAM,SAAS,MAAmD;AAChE,UAAM,aAAa,OAAO,KAAK,KAAK,OAAO;AAC3C,UAAM,eAAe,MAAM,oBAAoB,KAAK,QAAQ,YAAY,KAAK,QAAQ,KAAK,OAAO;AACjG,UAAM,MAA0B,EAAE,MAAM,aAAa;AAErD,UAAM,aAAa,KAAK,UAAU,IAAI,KAAK,MAAM;AACjD,QAAI,WAAY,YAAW,KAAK,GAAG;AAAA,QAC9B,MAAK,UAAU,IAAI,KAAK,QAAQ,CAAC,GAAG,CAAC;AAM1C,eAAW,SAAS,KAAK,WAAW,CAAC,GAAG;AACtC,YAAM,YAAY,KAAK,UAAU,IAAI,KAAK;AAC1C,UAAI,UAAW,WAAU,KAAK,GAAG;AAAA,UAC5B,MAAK,UAAU,IAAI,OAAO,CAAC,GAAG,CAAC;AAAA,IACtC;AAMA,eAAW,KAAK,KAAK,aAAa,CAAC,GAAG;AACpC,YAAM,cAAc,KAAK,UAAU,IAAI,EAAE,UAAU;AACnD,UAAI,YAAa,aAAY,KAAK,GAAG;AAAA,UAChC,MAAK,UAAU,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC;AAAA,IAC7C;AAQA,QAAI,KAAK,QAAQ;AACf,YAAM,aAAa,KAAK,UAAU,IAAI,KAAK,OAAO,IAAI;AACtD,UAAI,WAAY,YAAW,KAAK,GAAG;AAAA,UAC9B,MAAK,UAAU,IAAI,KAAK,OAAO,MAAM,CAAC,GAAG,CAAC;AAAA,IACjD;AAEA,eAAW,OAAO,YAAY;AAC5B,YAAM,SAAS,KAAK,QAAQ,GAAG;AAC/B,UAAI,CAAC,OAAQ;AACb,YAAM,mBAAmB,OAAO;AAChC,YAAM,MAAM,KAAK,UAAU,IAAI,gBAAgB;AAC/C,UAAI,IAAK,KAAI,KAAK,GAAG;AAAA,UAChB,MAAK,UAAU,IAAI,kBAAkB,CAAC,GAAG,CAAC;AAAA,IACjD;AAAA,EACF;AAAA,EAEA,oBAAoB,QAAmD;AACrE,WAAO,KAAK,UAAU,IAAI,MAAM,KAAK,CAAC;AAAA,EACxC;AAAA,EAEA,0BAA0B,YAAuD;AAC/E,WAAO,KAAK,UAAU,IAAI,UAAU,KAAK,CAAC;AAAA,EAC5C;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYA,MAAyC;AACvC,UAAM,OAAO,oBAAI,IAAwB;AACzC,eAAW,cAAc,KAAK,UAAU,OAAO,GAAG;AAChD,iBAAW,KAAK,WAAY,MAAK,IAAI,CAAC;AAAA,IACxC;AACA,WAAO,CAAC,GAAG,IAAI;AAAA,EACjB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,WAAiB;AACf,UAAM,UAAU,oBAAI,IAAY;AAChC,UAAM,QAAkB,CAAC;AAEzB,UAAM,QAAQ,CAAC,SAAuB;AACpC,UAAI,MAAM,SAAS,IAAI,GAAG;AACxB,cAAM,QAAQ,MAAM,MAAM,MAAM,QAAQ,IAAI,CAAC,EAAE,OAAO,IAAI;AAC1D,cAAM,IAAI,qBAAqB,KAAK;AAAA,MACtC;AACA,UAAI,QAAQ,IAAI,IAAI,EAAG;AACvB,YAAM,KAAK,IAAI;AACf,YAAM,aAAa,KAAK,UAAU,IAAI,IAAI;AAC1C,UAAI,YAAY;AACd,mBAAW,KAAK,YAAY;AAC1B,qBAAW,OAAO,OAAO,KAAK,EAAE,KAAK,OAAO,GAAG;AAC7C,kBAAM,SAAS,EAAE,KAAK,QAAQ,GAAG;AACjC,gBAAI,CAAC,OAAQ;AAKb,gBACE,OAAO,UAAU,YACjB,OAAO,eAAe,EAAE,KAAK,UAC7B,OAAO,WAAW,QAClB;AACA;AAAA,YACF;AACA,kBAAM,OAAO,UAAU;AAAA,UACzB;AAAA,QACF;AAAA,MACF;AACA,YAAM,IAAI;AACV,cAAQ,IAAI,IAAI;AAAA,IAClB;AAEA,eAAW,OAAO,KAAK,UAAU,KAAK,EAAG,OAAM,GAAG;AAAA,EACpD;AACF;","names":[]}