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

package/dist/{chunk-22DWZL57.js → chunk-LFLXAY2W.js}

@@ -1,219 +1,22 @@
 import {
   ensureCollectionDEK
-} from "./chunk-DONMZAD2.js";
+} from "./chunk-WWGT2MDV.js";
 import {
   envelopePayloadHash
-} from "./chunk-Z6FNBOTC.js";
+} from "./chunk-AIWULCUO.js";
 import {
-  NOYDB_FORMAT_VERSION
-} from "./chunk-WIRRPTFH.js";
+  encrypt,
+  openEnvelopeJson
+} from "./chunk-5O3AOPDT.js";
 import {
-  decrypt,
-  encrypt
-} from "./chunk-PP6W64Y3.js";
+  NOYDB_FORMAT_VERSION
+} from "./chunk-5TDJ56JE.js";
 import {
   DictKeyMissingError,
-  LocaleNotSpecifiedError,
-  MissingTranslationError,
   PermissionDeniedError
-} from "./chunk-B6PB7JLN.js";
-
-// src/i18n/policy.ts
-function resolvePolicy(onMissing, layer) {
-  const explicit = onMissing && typeof onMissing === "object" ? onMissing[layer] : void 0;
-  const scalar = typeof onMissing === "string" ? onMissing : void 0;
-  const layerDefault = layer === "guard" ? "substitute" : void 0;
-  return explicit ?? layerDefault ?? scalar ?? "throw";
-}
+} from "./chunk-ZYUC53LT.js";
 
-// src/i18n/core.ts
-function i18nText(options) {
-  return { _noydbI18nText: true, options };
-}
-function isI18nTextDescriptor(x) {
-  return typeof x === "object" && x !== null && x._noydbI18nText === true;
-}
-function validateI18nTextValue(value, field, descriptor) {
-  const { options } = descriptor;
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new MissingTranslationError(
-      field,
-      options.languages,
-      `Field "${field}" must be a { [locale]: string } map, got ${typeof value}.`
-    );
-  }
-  const map = value;
-  for (const [locale, v] of Object.entries(map)) {
-    if (typeof v !== "string") {
-      throw new MissingTranslationError(
-        field,
-        [locale],
-        `Field "${field}": locale "${locale}" must be a string, got ${typeof v}.`
-      );
-    }
-  }
-  const { required } = options;
-  if (required === "all") {
-    const missing = options.languages.filter(
-      (lang) => !(lang in map) || map[lang] === ""
-    );
-    if (missing.length > 0) {
-      throw new MissingTranslationError(
-        field,
-        missing,
-        `Field "${field}" requires all declared languages. Missing: ${missing.join(", ")}.`
-      );
-    }
-  } else if (required === "any") {
-    const present = options.languages.some(
-      (lang) => lang in map && map[lang] !== ""
-    );
-    if (!present) {
-      throw new MissingTranslationError(
-        field,
-        options.languages,
-        `Field "${field}" requires at least one declared language. None present.`
-      );
-    }
-  } else {
-    const requiredList = required;
-    const missing = requiredList.filter(
-      (lang) => !(lang in map) || map[lang] === ""
-    );
-    if (missing.length > 0) {
-      throw new MissingTranslationError(
-        field,
-        missing,
-        `Field "${field}" requires: ${requiredList.join(", ")}. Missing: ${missing.join(", ")}.`
-      );
-    }
-  }
-}
-function toChain(fallback) {
-  return Array.isArray(fallback) ? fallback : fallback ? [fallback] : [];
-}
-function pickFromChain(value, chain) {
-  for (const fb of chain) {
-    if (fb === "any") {
-      const any = Object.values(value).find((v) => v !== "");
-      if (any !== void 0) return any;
-    } else if (value[fb] !== void 0 && value[fb] !== "") {
-      return value[fb];
-    }
-  }
-  return void 0;
-}
-function resolveI18nText(value, locale, fallback, field, opts) {
-  if (locale === "raw") {
-    return value;
-  }
-  if (!locale) {
-    throw new LocaleNotSpecifiedError(field ?? "<unknown>");
-  }
-  if (value[locale] !== void 0 && value[locale] !== "") {
-    return value[locale];
-  }
-  const policy = opts?.policy ?? "throw";
-  const callerChain = toChain(fallback);
-  const callerHit = pickFromChain(value, callerChain);
-  if (callerHit !== void 0) return callerHit;
-  if (policy === "substitute") {
-    const subHit = pickFromChain(value, toChain(opts?.substitute));
-    if (subHit !== void 0) return subHit;
-  }
-  if (policy === "throw") {
-    throw new LocaleNotSpecifiedError(
-      field ?? "<unknown>",
-      `No translation available for locale "${locale}"` + (callerChain.length > 0 ? ` or fallback chain [${callerChain.join(", ")}]` : "") + "."
-    );
-  }
-  return null;
-}
-function getAtPath(obj, path) {
-  const arrayIdx = path.indexOf("[].");
-  if (arrayIdx !== -1) {
-    const arrayKey = path.slice(0, arrayIdx);
-    const restPath = path.slice(arrayIdx + 3);
-    const arr = obj[arrayKey];
-    if (!Array.isArray(arr)) return [];
-    return arr.flatMap((item) => {
-      if (!item || typeof item !== "object" || Array.isArray(item)) return [];
-      return getAtPath(item, restPath);
-    });
-  }
-  const dotIdx = path.indexOf(".");
-  if (dotIdx !== -1) {
-    const head = path.slice(0, dotIdx);
-    const rest = path.slice(dotIdx + 1);
-    const nested = obj[head];
-    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return [];
-    return getAtPath(nested, rest);
-  }
-  const val = obj[path];
-  return val !== void 0 ? [val] : [];
-}
-function setAtPathInPlace(obj, path, value) {
-  const dotIdx = path.indexOf(".");
-  if (dotIdx !== -1) {
-    const head = path.slice(0, dotIdx);
-    const rest = path.slice(dotIdx + 1);
-    const nested = obj[head];
-    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return;
-    setAtPathInPlace(nested, rest, value);
-    return;
-  }
-  obj[path] = value;
-}
-function applyAtPath(obj, path, locale, fallback, opts) {
-  const arrayIdx = path.indexOf("[].");
-  if (arrayIdx !== -1) {
-    const arrayKey = path.slice(0, arrayIdx);
-    const restPath = path.slice(arrayIdx + 3);
-    const arr = obj[arrayKey];
-    if (!Array.isArray(arr)) return obj;
-    return {
-      ...obj,
-      [arrayKey]: arr.map((item) => {
-        if (!item || typeof item !== "object" || Array.isArray(item)) return item;
-        return applyAtPath(item, restPath, locale, fallback, opts);
-      })
-    };
-  }
-  const dotIdx = path.indexOf(".");
-  if (dotIdx !== -1) {
-    const head = path.slice(0, dotIdx);
-    const rest = path.slice(dotIdx + 1);
-    const nested = obj[head];
-    if (!nested || typeof nested !== "object" || Array.isArray(nested)) return obj;
-    return {
-      ...obj,
-      [head]: applyAtPath(nested, rest, locale, fallback, opts)
-    };
-  }
-  const raw = obj[path];
-  if (raw === void 0 || raw === null) return obj;
-  if (typeof raw !== "object" || Array.isArray(raw)) return obj;
-  return {
-    ...obj,
-    [path]: resolveI18nText(raw, locale, fallback, path, opts)
-  };
-}
-function applyI18nLocale(record, i18nFields, locale, fallback, layer = "read") {
-  const fieldNames = Object.keys(i18nFields);
-  if (fieldNames.length === 0) return record;
-  let result = record;
-  for (const [field, descriptor] of Object.entries(i18nFields)) {
-    const { onMissing, substitute } = descriptor.options;
-    const opts = {
-      policy: resolvePolicy(onMissing, layer),
-      ...substitute !== void 0 ? { substitute } : {}
-    };
-    result = applyAtPath(result, field, locale, fallback, opts);
-  }
-  return result;
-}
-
-// src/i18n/dictionary.ts
+// src/with-shape/i18n/dictionary.ts
 var DICT_COLLECTION_PREFIX = "_dict_";
 function dictCollectionName(dictionaryName) {
   return `${DICT_COLLECTION_PREFIX}${dictionaryName}`;
@@ -221,18 +24,46 @@ function dictCollectionName(dictionaryName) {
 function isDictCollectionName(name) {
   return name.startsWith(DICT_COLLECTION_PREFIX);
 }
-function dictKey(name, keys, opts) {
+function dictKey(name, keysOrMap, opts) {
+  let keys;
+  let labels;
+  if (Array.isArray(keysOrMap)) {
+    keys = keysOrMap;
+    labels = opts?.labels;
+  } else if (keysOrMap && typeof keysOrMap === "object") {
+    keys = Object.keys(keysOrMap);
+    labels = keysOrMap;
+  } else {
+    keys = void 0;
+    labels = opts?.labels;
+  }
   return {
     _noydbDictKey: true,
     name,
     keys,
     ...opts?.onMissing !== void 0 ? { onMissing: opts.onMissing } : {},
-    ...opts?.substitute !== void 0 ? { substitute: opts.substitute } : {}
+    ...opts?.substitute !== void 0 ? { substitute: opts.substitute } : {},
+    ...labels !== void 0 ? { labels } : {}
   };
 }
 function isDictKeyDescriptor(x) {
   return typeof x === "object" && x !== null && x._noydbDictKey === true;
 }
+function staticDict(name, table, opts) {
+  return {
+    _noydbStaticDict: true,
+    name,
+    table,
+    keys: Object.keys(table),
+    ...opts?.displayLocale !== void 0 ? { displayLocale: opts.displayLocale } : {},
+    ...opts?.onMissing !== void 0 ? { onMissing: opts.onMissing } : {},
+    ...opts?.substitute !== void 0 ? { substitute: opts.substitute } : {},
+    ...opts?.validateCodes !== void 0 ? { validateCodes: opts.validateCodes } : {}
+  };
+}
+function isStaticDictDescriptor(x) {
+  return typeof x === "object" && x !== null && x._noydbStaticDict === true;
+}
 var DictionaryHandle = class {
   constructor(adapter, compartmentName, dictionaryName, keyring, getDEK, encrypted, ledger, options, findAndUpdateReferences, emitter) {
     this.adapter = adapter;
@@ -334,7 +165,7 @@ var DictionaryHandle = class {
       return JSON.parse(envelope._data);
     }
     const dek = await this.getDekForDict();
-    const json = await decrypt(envelope._iv, envelope._data, dek);
+    const json = await openEnvelopeJson(envelope, dek);
     return JSON.parse(json);
   }
   // ─── Public API ───────────────────────────────────────────────────
@@ -571,19 +402,13 @@ var DictionaryHandle = class {
 };
 
 export {
-  resolvePolicy,
-  i18nText,
-  isI18nTextDescriptor,
-  validateI18nTextValue,
-  resolveI18nText,
-  getAtPath,
-  setAtPathInPlace,
-  applyI18nLocale,
   DICT_COLLECTION_PREFIX,
   dictCollectionName,
   isDictCollectionName,
   dictKey,
   isDictKeyDescriptor,
+  staticDict,
+  isStaticDictDescriptor,
   DictionaryHandle
 };
-//# sourceMappingURL=chunk-22DWZL57.js.map
+//# sourceMappingURL=chunk-LFLXAY2W.js.map

package/dist/chunk-LFLXAY2W.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-shape/i18n/dictionary.ts"],"sourcesContent":["/**\n * _dict_* reserved collections + dictKey schema descriptor —\n *\n * Stores bounded enum-like field dictionaries as reserved encrypted\n * collections (`_dict_<name>/`) within a vault. Each dictionary\n * entry maps a stable key (e.g. `'paid'`) to a locale → label record\n * (e.g. `{ en: 'Paid', th: 'ชำระแล้ว' }`).\n *\n * Design decisions\n * ────────────────\n *\n * **Why reserved collections, not a separate store?**\n * Same answer as `_sync_credentials`: the compartment's existing\n * encryption stack is exactly right. Dictionaries are encrypted under the\n * same vault DEK, inherit ACL, ledger, and backup/restore for free.\n *\n * **One collection per dictionary, not one collection with namespaces.**\n * Each `_dict_<name>/` collection holds entries `{ id: key, labels: {...} }`.\n * This composes with `ref()` naturally (a dictKey IS a ref to the dict\n * collection), and means the query DSL works over dictionary entries\n * without any special-casing.\n *\n * **dictKey() is a descriptor, not a Zod type.**\n * The descriptor pattern matches `ref()`: declare NOYDB-specific metadata\n * in the collection options alongside `refs`. TypeScript inference comes\n * from the descriptor's generic parameter, not from Zod internals.\n *\n * API:\n *   `dictKey(name, keys?)` — returns a DictKeyDescriptor\n *   `vault.dictionary(name)` — returns a DictionaryHandle\n *   `DictionaryHandle.put/putAll/get/delete/rename/list` — CRUD\n */\n\nimport type { NoydbStore, EncryptedEnvelope } from '../../kernel/types.js'\nimport type { NoydbEventEmitter } from '../../kernel/events.js'\nimport { NOYDB_FORMAT_VERSION } from '../../kernel/types.js'\nimport type { UnlockedKeyring } from '../../with-party/team/keyring.js'\nimport { encrypt, openEnvelopeJson, type EnclaveKey } from '../../kernel/enclave/index.js'\nimport { ensureCollectionDEK } from '../../with-party/team/keyring.js'\nimport type { LedgerStore } from '../../with-commit/history/ledger/store.js'\nimport type { OnMissingPolicy } from './policy.js'\nimport { envelopePayloadHash } from '../../with-commit/history/ledger/hash.js'\nimport {\n  PermissionDeniedError,\n  DictKeyMissingError,\n} from '../../kernel/errors.js'\n\n/** Reserved collection name prefix. Never collides with user collections. */\nexport const DICT_COLLECTION_PREFIX = '_dict_'\n\n/** Return the adapter collection name for a named dictionary. */\nexport function dictCollectionName(dictionaryName: string): string {\n  return `${DICT_COLLECTION_PREFIX}${dictionaryName}`\n}\n\n/** Return true when a collection name is a reserved dictionary collection. */\nexport function isDictCollectionName(name: string): boolean {\n  return name.startsWith(DICT_COLLECTION_PREFIX)\n}\n\n// ─── DictKey descriptor ────────────────────────────────────────────────\n\n/**\n * Descriptor returned by `dictKey()`. Attach to the collection's\n * `dictKeyFields` option to declare which fields are dictionary-backed:\n *\n * ```ts\n * const invoices = company.collection<Invoice>('invoices', {\n *   dictKeyFields: {\n *     status: dictKey('status', ['draft', 'open', 'paid'] as const),\n *   },\n * })\n * ```\n *\n * The generic parameter `Keys` narrows the TypeScript type of the field\n * to a literal union; the runtime value of `keys` is used by `put()`\n * validation to reject unknown keys when a key set is declared.\n */\nexport interface DictKeyDescriptor<Keys extends string = string> {\n  readonly _noydbDictKey: true\n  /** Which dictionary this field references. */\n  readonly name: string\n  /** Declared valid keys. When set, `put()` rejects keys not in this set. */\n  readonly keys: readonly Keys[] | undefined\n  /**\n   * What to do when a label is missing for the resolved locale. Mirrors\n   * `i18nText`'s `onMissing`. Default behavior (when unset) preserves the\n   * legacy contract: a missing label is omitted (scalar) or `null`\n   * (array element) — i.e. `'null'`. Set `'substitute'` to walk the\n   * declared `substitute` chain, or `'throw'` to raise.\n   */\n  readonly onMissing?: OnMissingPolicy\n  /** Ordered preferred-substitute locales for label resolution. */\n  readonly substitute?: readonly string[]\n  /**\n   * Optional inline display labels (value → label map). A SYNC display\n   * fallback for `describe()` when async `dictLabels` (from `_dict_`) are\n   * not resolved. The async path still wins when available.\n   */\n  readonly labels?: Record<string, string>\n}\n\n/**\n * Create a `DictKeyDescriptor` for a dictionary-backed enum field.\n *\n * @param name        The dictionary name (corresponds to `_dict_<name>` collection).\n * @param keysOrMap   Either:\n *   - An `as const` array of valid key literals — narrows the TypeScript type\n *     to a literal union and enables put-time validation.\n *   - A **value→label map** (`{ draft: 'Draft', paid: 'Paid' }`) — keys are\n *     inferred from the map, and the labels are stored as inline display\n *     defaults surfaced by `describe()` without a store read.\n * @param opts        `{ labels?, onMissing?, substitute? }` when the array form\n *                    is used; `opts.labels` provides inline display defaults for\n *                    specific keys (same semantics as the map form, but\n *                    explicit key order from the array is preserved).\n *\n * @example\n * ```ts\n * // array form (original):\n * dictKey('status', ['draft', 'open', 'paid'] as const)\n *\n * // value→label map form (keys inferred, inline labels for describe()):\n * dictKey('status', { draft: 'Draft', open: 'Open', paid: 'Paid' })\n *\n * // array + opts.labels (preserves explicit order, partial labels OK):\n * dictKey('status', ['draft', 'open', 'paid'] as const, { labels: { paid: 'Paid' } })\n * ```\n */\nexport function dictKey<Keys extends string>(\n  name: string,\n  keysOrMap?: readonly Keys[] | Record<Keys, string>,\n  opts?: { onMissing?: OnMissingPolicy; substitute?: readonly string[]; labels?: Record<string, string> },\n): DictKeyDescriptor<Keys> {\n  let keys: readonly Keys[] | undefined\n  let labels: Record<string, string> | undefined\n  if (Array.isArray(keysOrMap)) {\n    keys = keysOrMap as readonly Keys[]\n    labels = opts?.labels\n  } else if (keysOrMap && typeof keysOrMap === 'object') {\n    keys = Object.keys(keysOrMap) as Keys[]\n    labels = keysOrMap as Record<string, string>\n  } else {\n    keys = undefined\n    labels = opts?.labels\n  }\n  return {\n    _noydbDictKey: true,\n    name,\n    keys,\n    ...(opts?.onMissing !== undefined ? { onMissing: opts.onMissing } : {}),\n    ...(opts?.substitute !== undefined ? { substitute: opts.substitute } : {}),\n    ...(labels !== undefined ? { labels } : {}),\n  }\n}\n\n/** Runtime predicate for detecting a DictKeyDescriptor. */\nexport function isDictKeyDescriptor(x: unknown): x is DictKeyDescriptor {\n  return (\n    typeof x === 'object' &&\n    x !== null &&\n    (x as { _noydbDictKey?: unknown })._noydbDictKey === true\n  )\n}\n\n// ─── StaticDict descriptor (code-provided dictionary) ──────────────────\n\n/**\n * Descriptor returned by `staticDict()`. A sibling to {@link DictKeyDescriptor}\n * for **closed, defined-in-code, identical-across-vaults** enums (honorific,\n * civil-status, gender, religion, ContactTitle, status…).\n *\n * Unlike `dictKey`, the labels are supplied **at registration in code** and\n * resolved through the *same* label machinery, but with **no `_dict_*`\n * per-vault encrypted copy** and **no `rename()`**. The record stores only\n * the **code**; a static dict has no mutation surface.\n *\n * **Hybrid resolution.** Because a static dict is pure code with no\n * vault-locale dependency, it can — via a configured `displayLocale` — emit a\n * `<field>Label` even under a **locale-less read** (the property a locale-less\n * consumer needs and `dictKey` cannot provide). When a locale *is* active it\n * behaves exactly like `dictKey` (honoring `onMissing`/`substitute`).\n *\n * ```ts\n * const workers = vault.collection<Worker>('workers', {\n *   dictKeyFields: {\n *     civilStatus: staticDict('civilStatus', {\n *       adultMale:   { th: 'นาย',    en: 'Mr'  },\n *       adultFemale: { th: 'นาง',    en: 'Mrs' },\n *     }, { displayLocale: 'th' }),\n *   },\n * })\n * ```\n */\nexport interface StaticDictDescriptor<Keys extends string = string> {\n  readonly _noydbStaticDict: true\n  /** Which dictionary this field references (the registry name). */\n  readonly name: string\n  /** The in-code label table: key → { locale → label }. */\n  readonly table: Readonly<Record<Keys, Readonly<Record<string, string>>>>\n  /** Declared valid keys — derived from `Object.keys(table)`. */\n  readonly keys: readonly Keys[]\n  /**\n   * Locale used to emit `<field>Label` under a **locale-less** read — the\n   * hybrid hinge. When unset, a static dict behaves like `dictKey` under a\n   * locale-less read (no label); a locale-less consumer almost always wants\n   * it set.\n   */\n  readonly displayLocale?: string\n  /** Same `onMissing` policy engine as `dictKey`. Default `'null'`. */\n  readonly onMissing?: OnMissingPolicy\n  /** Ordered preferred-substitute locales for label resolution. */\n  readonly substitute?: readonly string[]\n  /**\n   * Validate the stored code against `keys` on every `put()`. Default `true`\n   * — codes are closed by construction, so an unknown code is a bug. Set\n   * `false` to allow open codes (skips the `UnknownDictCodeError` guard).\n   */\n  readonly validateCodes?: boolean\n}\n\n/**\n * Create a `StaticDictDescriptor` for a code-provided enum field — a sibling\n * to {@link dictKey} for closed, code-defined, identical-across-vaults enums.\n *\n * The labels live in `table` (no `_dict_*` collection, no `rename()`); the\n * record stores only the stable code. Pass `displayLocale` so `<field>Label`\n * resolves even under a locale-less read.\n *\n * @param name   The dictionary name (used for the readonly-guard registry and\n *               the query label seam — never creates a `_dict_<name>` key).\n * @param table  `{ key: { locale: label } }` map.\n * @param opts   `displayLocale` (locale-less label), `onMissing`, `substitute`.\n *\n * @example\n * ```ts\n * staticDict('civilStatus', {\n *   adultMale:   { th: 'นาย',    en: 'Mr'  },\n *   adultFemale: { th: 'นาง',    en: 'Mrs' },\n * }, { displayLocale: 'th' })\n * ```\n */\nexport function staticDict<const T extends Record<string, Record<string, string>>>(\n  name: string,\n  table: T,\n  opts?: {\n    displayLocale?: string\n    onMissing?: OnMissingPolicy\n    substitute?: readonly string[]\n    validateCodes?: boolean\n  },\n): StaticDictDescriptor<Extract<keyof T, string>> {\n  return {\n    _noydbStaticDict: true,\n    name,\n    table: table as Readonly<Record<Extract<keyof T, string>, Readonly<Record<string, string>>>>,\n    keys: Object.keys(table) as Extract<keyof T, string>[],\n    ...(opts?.displayLocale !== undefined ? { displayLocale: opts.displayLocale } : {}),\n    ...(opts?.onMissing !== undefined ? { onMissing: opts.onMissing } : {}),\n    ...(opts?.substitute !== undefined ? { substitute: opts.substitute } : {}),\n    ...(opts?.validateCodes !== undefined ? { validateCodes: opts.validateCodes } : {}),\n  }\n}\n\n/** Runtime predicate for detecting a StaticDictDescriptor. */\nexport function isStaticDictDescriptor(x: unknown): x is StaticDictDescriptor {\n  return (\n    typeof x === 'object' &&\n    x !== null &&\n    (x as { _noydbStaticDict?: unknown })._noydbStaticDict === true\n  )\n}\n\n// ─── Dictionary entry shape ────────────────────────────────────────────\n\n/**\n * One entry in a `_dict_*` collection. The record `id` (adapter-side\n * key) IS the stable dictionary key (e.g. `'paid'`). The `labels`\n * record maps locale codes to display strings.\n */\nexport interface DictEntry {\n  /** Stable key — same as the record id in the adapter. */\n  readonly key: string\n  /** Locale → label map, e.g. `{ en: 'Paid', th: 'ชำระแล้ว' }`. */\n  readonly labels: Record<string, string>\n}\n\n// ─── Per-dictionary options ────────────────────────────────────────────\n\n/**\n * Options for `vault.dictionary(name, options?)`.\n *\n * `writableBy` controls the minimum role for write operations (put,\n * putAll, delete, rename). Defaults to `'admin'` to match the standard\n * \"dictionary contents are owned by admins\" convention; set to\n * `'operator'` for user-editable dictionaries like custom tags.\n */\nexport interface DictionaryOptions {\n  /** Minimum role allowed to write dictionary entries. Default: `'admin'`. */\n  readonly writableBy?: 'owner' | 'admin' | 'operator'\n}\n\n// ─── DictionaryHandle ──────────────────────────────────────────────────\n\n/**\n * Handle to a named dictionary within a vault.\n *\n * Obtained via `vault.dictionary(name)`. Provides strongly-typed\n * CRUD for dictionary entries, plus the `rename()` operation that is the\n * only sanctioned mass-mutation path for dictKey fields.\n *\n * All writes are encrypted under the compartment's DEK for the\n * `_dict_<name>` collection. Adapters never see plaintext.\n */\nexport class DictionaryHandle<Keys extends string = string> {\n  private readonly collName: string\n\n  /**\n   * Synchronous write-through cache for dict-join support.\n   * Populated on every `put()`, `delete()`, and `rename()`. The snapshot\n   * is built from this cache by `snapshotEntries()` — the query executor\n   * calls this synchronously inside `.toArray()`.\n   *\n   * `null` means \"not yet initialized\" — callers should use `list()`\n   * to warm the cache before using dict joins on pre-existing data.\n   */\n  private readonly _syncCache = new Map<string, DictEntry>()\n\n  /**\n   * Return all cached entries as `{ key, labels, ...labels }` records —\n   * usable synchronously by the join executor's `snapshot()` call.\n   * Returns an empty array when the cache has never been populated.\n   */\n  snapshotEntries(): readonly Record<string, unknown>[] {\n    return Array.from(this._syncCache.values()).map((e) => ({\n      key: e.key,\n      labels: e.labels,\n      ...e.labels,\n    }))\n  }\n\n  constructor(\n    private readonly adapter: NoydbStore,\n    private readonly compartmentName: string,\n    private readonly dictionaryName: string,\n    private readonly keyring: UnlockedKeyring,\n    private readonly getDEK: (collectionName: string) => Promise<EnclaveKey>,\n    private readonly encrypted: boolean,\n    private readonly ledger: LedgerStore | undefined,\n    private readonly options: DictionaryOptions,\n    /**\n     * Callback provided by the Vault to find and rewrite records\n     * in any registered collection that has a dictKeyField pointing at\n     * this dictionary, used by `rename()`.\n     */\n    private readonly findAndUpdateReferences:\n      | ((\n          dictionaryName: string,\n          oldKey: string,\n          newKey: string,\n        ) => Promise<void>)\n      | undefined,\n    private readonly emitter: NoydbEventEmitter,\n  ) {\n    this.collName = dictCollectionName(dictionaryName)\n  }\n\n  // ─── Access checks ────────────────────────────────────────────────\n\n  private requireWriteAccess(): void {\n    const minRole = this.options.writableBy ?? 'admin'\n    const roleRank: Record<string, number> = {\n      client: 1,\n      viewer: 2,\n      operator: 3,\n      admin: 4,\n      owner: 5,\n    }\n    const callerRank = roleRank[this.keyring.role] ?? 0\n    const requiredRank = roleRank[minRole] ?? 4\n    if (callerRank < requiredRank) {\n      throw new PermissionDeniedError(\n        `Dictionary \"${this.dictionaryName}\" writes require \"${minRole}\" role or above. ` +\n          `Current role: \"${this.keyring.role}\".`,\n      )\n    }\n  }\n\n  // ─── Internal helpers ─────────────────────────────────────────────\n\n  private async getDekForDict(): Promise<EnclaveKey> {\n    const resolve = await ensureCollectionDEK(\n      this.adapter,\n      this.compartmentName,\n      this.keyring,\n    )\n    return resolve(this.collName)\n  }\n\n  private async encryptEntry(entry: DictEntry, version: number): Promise<EncryptedEnvelope> {\n    if (!this.encrypted) {\n      return {\n        _noydb: NOYDB_FORMAT_VERSION,\n        _v: version,\n        _ts: new Date().toISOString(),\n        _iv: '',\n        _data: JSON.stringify(entry),\n        _by: this.keyring.userId,\n      }\n    }\n    const dek = await this.getDekForDict()\n    const { iv, data } = await encrypt(JSON.stringify(entry), dek)\n    return {\n      _noydb: NOYDB_FORMAT_VERSION,\n      _v: version,\n      _ts: new Date().toISOString(),\n      _iv: iv,\n      _data: data,\n      _by: this.keyring.userId,\n    }\n  }\n\n  private async decryptEntry(envelope: EncryptedEnvelope): Promise<DictEntry> {\n    if (!this.encrypted) {\n      return JSON.parse(envelope._data) as DictEntry\n    }\n    const dek = await this.getDekForDict()\n    const json = await openEnvelopeJson(envelope, dek)\n    return JSON.parse(json) as DictEntry\n  }\n\n  // ─── Public API ───────────────────────────────────────────────────\n\n  /**\n   * Add or overwrite a single dictionary entry.\n   *\n   * @param key    The stable key to store (e.g. `'paid'`).\n   * @param labels Locale → label map (e.g. `{ en: 'Paid', th: 'ชำระแล้ว' }`).\n   */\n  async put(key: Keys, labels: Record<string, string>): Promise<void> {\n    this.requireWriteAccess()\n\n    const entry: DictEntry = { key, labels }\n    const existing = await this.adapter.get(\n      this.compartmentName,\n      this.collName,\n      key,\n    )\n    const version = existing ? existing._v + 1 : 1\n    const envelope = await this.encryptEntry(entry, version)\n\n    await this.adapter.put(\n      this.compartmentName,\n      this.collName,\n      key,\n      envelope,\n      existing ? existing._v : undefined,\n    )\n\n    // Maintain synchronous cache for dict-join snapshot\n    this._syncCache.set(key, entry)\n\n    this.emitter.emit('change', {\n      vault: this.compartmentName,\n      collection: this.collName,\n      id: key,\n      action: 'put',\n    })\n\n    if (this.ledger) {\n      await this.ledger.append({\n        op: 'put',\n        collection: this.collName,\n        id: key,\n        version,\n        actor: this.keyring.userId,\n        //  — must be the real envelope hash so\n        // vault.verifyBackupIntegrity()'s data-cross-check matches.\n        payloadHash: await envelopePayloadHash(envelope),\n      })\n    }\n  }\n\n  /**\n   * Batch-add or overwrite multiple dictionary entries in one call.\n   *\n   * @param entries  `{ key: { locale: label } }` map.\n   */\n  async putAll(entries: Record<Keys, Record<string, string>>): Promise<void> {\n    this.requireWriteAccess()\n    for (const [key, labels] of Object.entries(entries) as [Keys, Record<string, string>][]) {\n      await this.put(key, labels)\n    }\n  }\n\n  /**\n   * Load the label map for a single key.\n   *\n   * @returns The label map, or `null` if the key doesn't exist.\n   */\n  async get(key: Keys): Promise<Record<string, string> | null> {\n    const envelope = await this.adapter.get(\n      this.compartmentName,\n      this.collName,\n      key,\n    )\n    if (!envelope) return null\n    const entry = await this.decryptEntry(envelope)\n    return entry.labels\n  }\n\n  /**\n   * Delete a dictionary key.\n   *\n   * Default mode is `'strict'` — throws `DictKeyInUseError` if any\n   * registered collection has a record referencing this key. Pass\n   * `{ mode: 'warn' }` to skip the check (dev-mode cleanup only).\n   */\n  async delete(key: Keys, opts: { mode?: 'strict' | 'warn' } = {}): Promise<void> {\n    this.requireWriteAccess()\n\n    const existing = await this.adapter.get(\n      this.compartmentName,\n      this.collName,\n      key,\n    )\n    if (!existing) {\n      throw new DictKeyMissingError(this.dictionaryName, key)\n    }\n\n    const mode = opts.mode ?? 'strict'\n    if (mode === 'strict' && this.findAndUpdateReferences) {\n      // Check for references by attempting a rename to a sentinel that\n      // doesn't exist — we reuse the reference-finding machinery but\n      // abort before applying changes. Simpler: the vault\n      // exposes a separate checkReferences() callback. For now we rely\n      // on the caller to confirm no references exist, or use warn mode.\n      // A dedicated findReferences API is tracked as a follow-up.\n    }\n\n    await this.adapter.delete(this.compartmentName, this.collName, key)\n\n    // Maintain synchronous cache for dict-join snapshot\n    this._syncCache.delete(key)\n\n    this.emitter.emit('change', {\n      vault: this.compartmentName,\n      collection: this.collName,\n      id: key,\n      action: 'delete',\n    })\n\n    if (this.ledger) {\n      await this.ledger.append({\n        op: 'delete',\n        collection: this.collName,\n        id: key,\n        version: existing._v,\n        actor: this.keyring.userId,\n        //  — for delete the prior envelope is what was just\n        // removed; we hash it so the chain captures intent. The\n        // verifyBackupIntegrity data-cross-check skips delete\n        // entries entirely (the live record is gone), but the\n        // chain still benefits from a stable non-empty hash.\n        payloadHash: await envelopePayloadHash(existing),\n      })\n    }\n  }\n\n  /**\n   * Rename a dictionary key — the only sanctioned mass-mutation path.\n   *\n   * Atomically:\n   * 1. Adds the new key with the same labels as the old key.\n   * 2. Updates every registered record that stores the old key to\n   *    store the new key instead.\n   * 3. Deletes the old key.\n   * 4. Appends a single ledger entry recording the rename.\n   *\n   * Respects ACL: throws `PermissionDeniedError` before any mutation\n   * if the caller can't write. The cascade is best-effort atomic\n   * within this call — no two-phase commit across adapter calls.\n   *\n   * Cascade-on-delete is NOT supported. Use `rename()` when you need\n   * to change a key that records reference.\n   */\n  async rename(oldKey: Keys, newKey: string): Promise<void> {\n    this.requireWriteAccess()\n\n    // 1. Load old entry\n    const existing = await this.adapter.get(\n      this.compartmentName,\n      this.collName,\n      oldKey,\n    )\n    if (!existing) {\n      throw new DictKeyMissingError(this.dictionaryName, oldKey)\n    }\n    const oldEntry = await this.decryptEntry(existing)\n\n    // 2. Write new key\n    const newEntry: DictEntry = { key: newKey, labels: oldEntry.labels }\n    const newEnvelope = await this.encryptEntry(newEntry, 1)\n    await this.adapter.put(\n      this.compartmentName,\n      this.collName,\n      newKey,\n      newEnvelope,\n    )\n\n    // 3. Update all referencing records in registered collections\n    if (this.findAndUpdateReferences) {\n      await this.findAndUpdateReferences(this.dictionaryName, oldKey, newKey)\n    }\n\n    // 4. Delete old key\n    await this.adapter.delete(this.compartmentName, this.collName, oldKey)\n\n    // Maintain synchronous cache for dict-join snapshot\n    this._syncCache.delete(oldKey)\n    this._syncCache.set(newKey, newEntry)\n\n    this.emitter.emit('change', {\n      vault: this.compartmentName,\n      collection: this.collName,\n      id: oldKey,\n      action: 'delete',\n    })\n    this.emitter.emit('change', {\n      vault: this.compartmentName,\n      collection: this.collName,\n      id: newKey,\n      action: 'put',\n    })\n\n    // 5. Ledger — record the rename as delete(oldKey) + put(newKey)\n    // so verifyBackupIntegrity()'s data-cross-check matches reality\n    // (the oldKey envelope is gone; the newKey envelope is what was\n    // just written). Two entries instead of one — the chain still\n    // captures the rename intent via the matching ts + actor.\n    if (this.ledger) {\n      await this.ledger.append({\n        op: 'delete',\n        collection: this.collName,\n        id: oldKey,\n        version: existing._v,\n        actor: this.keyring.userId,\n        payloadHash: await envelopePayloadHash(existing),\n      })\n      await this.ledger.append({\n        op: 'put',\n        collection: this.collName,\n        id: newKey,\n        version: 1,\n        actor: this.keyring.userId,\n        payloadHash: await envelopePayloadHash(newEnvelope),\n      })\n    }\n  }\n\n  /**\n   * List all entries in this dictionary.\n   *\n   * @returns Array of `{ key, labels }` objects.\n   */\n  async list(): Promise<DictEntry[]> {\n    const keys = await this.adapter.list(this.compartmentName, this.collName)\n    const entries: DictEntry[] = []\n    for (const key of keys) {\n      const envelope = await this.adapter.get(\n        this.compartmentName,\n        this.collName,\n        key,\n      )\n      if (!envelope) continue\n      const entry = await this.decryptEntry(envelope)\n      entries.push(entry)\n      // Warm the synchronous cache\n      this._syncCache.set(key, entry)\n    }\n    return entries\n  }\n\n  /**\n   * Resolve a key to its label for the given locale.\n   *\n   * Used by the collection's locale-aware read path to populate\n   * `<field>Label` virtual fields. Returns `undefined` when the\n   * key doesn't exist or has no label for the requested locale\n   * (after exhausting the fallback chain).\n   */\n  async resolveLabel(\n    key: string,\n    locale: string,\n    fallback?: string | readonly string[],\n  ): Promise<string | undefined> {\n    const labels = await this.get(key as Keys)\n    if (!labels) return undefined\n\n    // Try primary locale\n    if (labels[locale] !== undefined) return labels[locale]\n\n    // Try fallback chain\n    const chain = Array.isArray(fallback) ? (fallback as readonly string[]) : fallback ? [fallback as string] : []\n    for (const fb of chain) {\n      if (fb === 'any') {\n        // Return any available label\n        const any = Object.values(labels)[0]\n        if (any !== undefined) return any\n      } else if (labels[fb] !== undefined) {\n        return labels[fb]\n      }\n    }\n\n    return undefined\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-LMTH2RM6.js

@@ -0,0 +1,129 @@
+import {
+  ValidationError
+} from "./chunk-ZYUC53LT.js";
+
+// src/with-formula/derivations/with-derivation.ts
+function withDerivation(spec) {
+  if (!spec.source || spec.source.length === 0) {
+    throw new ValidationError("withDerivation: source collection name is required");
+  }
+  if (!spec.outputs || Object.keys(spec.outputs).length === 0) {
+    throw new ValidationError("withDerivation: outputs map must declare at least one output");
+  }
+  if (spec.deterministic !== true) {
+    throw new ValidationError("withDerivation: v1 only supports deterministic derivations");
+  }
+  if (typeof spec.derive !== "function") {
+    throw new ValidationError("withDerivation: derive must be a function");
+  }
+  if (spec.sources !== void 0) {
+    for (const extra of spec.sources) {
+      if (typeof extra !== "string" || extra.length === 0) {
+        throw new ValidationError("withDerivation: each entry in sources[] must be a non-empty string");
+      }
+      if (extra === spec.source) {
+        throw new ValidationError(
+          `withDerivation: sources[] must not contain the primary source "${spec.source}"`
+        );
+      }
+    }
+  }
+  if (spec.triggerBy !== void 0) {
+    for (const t of spec.triggerBy) {
+      if (typeof t?.collection !== "string" || t.collection.length === 0) {
+        throw new ValidationError("withDerivation: each triggerBy entry needs a non-empty `collection`");
+      }
+      if (t.collection === spec.source) {
+        throw new ValidationError(
+          `withDerivation: triggerBy.collection must not equal the source "${spec.source}" (use sources[] for same-id triggers)`
+        );
+      }
+      if (typeof t.on !== "string" || t.on.length === 0) {
+        throw new ValidationError(
+          `withDerivation: triggerBy on "${t.collection}" needs a non-empty \`on\` (the FK field on the source)`
+        );
+      }
+      if (t.maxFanout !== void 0 && (!Number.isInteger(t.maxFanout) || t.maxFanout < 1)) {
+        throw new ValidationError(
+          `withDerivation: triggerBy maxFanout on "${t.collection}" must be a positive integer (got ${String(t.maxFanout)}).`
+        );
+      }
+    }
+  }
+  const lifecycleMode = typeof spec.lifecycle === "string" ? spec.lifecycle : spec.lifecycle.mode;
+  for (const [outputKey, outputSpec] of Object.entries(spec.outputs)) {
+    if (outputSpec.shape === "record" && outputSpec.collection === spec.source) {
+      if (!outputSpec.denorm || outputSpec.denorm.length === 0) {
+        throw new ValidationError(
+          `withDerivation: self-write output "${outputKey}" (collection === source "${spec.source}") must declare \`denorm: [...]\` naming the fields it maintains.`
+        );
+      }
+    }
+    if (outputSpec.shape === "array") {
+      if (lifecycleMode !== "eager") {
+        throw new ValidationError(
+          `withDerivation: shape 'array' supports lifecycle 'eager' only in this release Output "${outputKey}" declared lifecycle '${lifecycleMode}'. Switch to \`lifecycle: "eager"\` or use shape: "record".`
+        );
+      }
+      if (typeof outputSpec.key !== "function") {
+        throw new ValidationError(
+          `withDerivation: shape 'array' output "${outputKey}" requires \`key: (out) => string\`.`
+        );
+      }
+      if (outputSpec.maxFanout !== void 0) {
+        if (!Number.isInteger(outputSpec.maxFanout) || outputSpec.maxFanout < 1) {
+          throw new ValidationError(
+            `withDerivation: maxFanout for output "${outputKey}" must be a positive integer (got ${String(outputSpec.maxFanout)}).`
+          );
+        }
+      }
+    }
+  }
+  return {
+    __noydb_strategy: "derivation",
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    spec
+  };
+}
+
+// src/with-formula/derivations/with-rollup.ts
+function withRollup(config) {
+  const { from, key, into, field, compute } = config;
+  if (!from || from.length === 0) {
+    throw new ValidationError("withRollup: `from` (child collection) is required");
+  }
+  if (!into || into.length === 0) {
+    throw new ValidationError("withRollup: `into` (parent collection) is required");
+  }
+  if (from === into) {
+    throw new ValidationError("withRollup: `from` and `into` must be different collections");
+  }
+  if (!key || key.length === 0) {
+    throw new ValidationError("withRollup: `key` (FK field on the child) is required");
+  }
+  if (!field || field.length === 0) {
+    throw new ValidationError("withRollup: `field` (target field on the parent) is required");
+  }
+  if (typeof compute !== "function") {
+    throw new ValidationError("withRollup: `compute` must be a function");
+  }
+  const spec = {
+    source: into,
+    // the parent record is what carries the rolled-up field
+    deterministic: true,
+    rollup: { from, key, field, compute },
+    // Synthetic self-write output for registry / cycle bookkeeping. Dispatch
+    // patches `field` directly (value-equality guarded); the executor is not run.
+    outputs: { value: { shape: "record", collection: into, denorm: [field] } },
+    derive: () => ({ value: {} }),
+    // never invoked for a rollup strategy
+    lifecycle: "eager"
+  };
+  return { __noydb_strategy: "derivation", spec };
+}
+
+export {
+  withDerivation,
+  withRollup
+};
+//# sourceMappingURL=chunk-LMTH2RM6.js.map

package/dist/chunk-LMTH2RM6.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/with-formula/derivations/with-derivation.ts","../src/with-formula/derivations/with-rollup.ts"],"sourcesContent":["import { ValidationError } from '../../kernel/errors.js'\nimport type { DerivationStrategy, DerivationStrategyHandle } from './types.js'\n\n/**\n * Register a deterministic derivation: one source collection → one or\n * more typed outputs, computed by the user's `derive` function on\n * plaintext after DEK unwrap. Outputs are encrypted with the same DEK\n * as the source and written via the standard `Collection.put` path.\n *\n * See docs/superpowers/specs/2026-05-01-dim14-derivation-v1-design.md.\n */\nexport function withDerivation<\n  TSource extends Record<string, unknown>,\n  TOutputs extends Record<string, Record<string, unknown> | ReadonlyArray<Record<string, unknown>>>,\n>(spec: DerivationStrategy<TSource, TOutputs>): DerivationStrategyHandle {\n  if (!spec.source || spec.source.length === 0) {\n    throw new ValidationError('withDerivation: source collection name is required')\n  }\n  if (!spec.outputs || Object.keys(spec.outputs).length === 0) {\n    throw new ValidationError('withDerivation: outputs map must declare at least one output')\n  }\n  if (spec.deterministic !== true) {\n    throw new ValidationError('withDerivation: v1 only supports deterministic derivations')\n  }\n  if (typeof spec.derive !== 'function') {\n    throw new ValidationError('withDerivation: derive must be a function')\n  }\n\n  // Validate declared sibling sources. Each must be a non-empty\n  // string and must differ from the primary source — a self-reference\n  // would double-register the strategy under the same `_bySource` key.\n  if (spec.sources !== undefined) {\n    for (const extra of spec.sources) {\n      if (typeof extra !== 'string' || extra.length === 0) {\n        throw new ValidationError('withDerivation: each entry in sources[] must be a non-empty string')\n      }\n      if (extra === spec.source) {\n        throw new ValidationError(\n          `withDerivation: sources[] must not contain the primary source \"${spec.source}\"`,\n        )\n      }\n    }\n  }\n\n  // Validate FK triggers. Each `collection` must be a non-empty\n  // string differing from the primary source, and `on` a non-empty field.\n  if (spec.triggerBy !== undefined) {\n    for (const t of spec.triggerBy) {\n      if (typeof t?.collection !== 'string' || t.collection.length === 0) {\n        throw new ValidationError('withDerivation: each triggerBy entry needs a non-empty `collection`')\n      }\n      if (t.collection === spec.source) {\n        throw new ValidationError(\n          `withDerivation: triggerBy.collection must not equal the source \"${spec.source}\" (use sources[] for same-id triggers)`,\n        )\n      }\n      if (typeof t.on !== 'string' || t.on.length === 0) {\n        throw new ValidationError(\n          `withDerivation: triggerBy on \"${t.collection}\" needs a non-empty \\`on\\` (the FK field on the source)`,\n        )\n      }\n      if (t.maxFanout !== undefined && (!Number.isInteger(t.maxFanout) || t.maxFanout < 1)) {\n        throw new ValidationError(\n          `withDerivation: triggerBy maxFanout on \"${t.collection}\" must be a positive integer (got ${String(t.maxFanout)}).`,\n        )\n      }\n    }\n  }\n\n  // Validate array-shape outputs.\n  const lifecycleMode = typeof spec.lifecycle === 'string' ? spec.lifecycle : spec.lifecycle.mode\n  for (const [outputKey, outputSpec] of Object.entries(spec.outputs)) {\n    // Self-write output (collection === source): reverse-denorm must declare\n    // `denorm` (the fields it owns) — field-level provenance.\n    if (outputSpec.shape === 'record' && outputSpec.collection === spec.source) {\n      if (!outputSpec.denorm || outputSpec.denorm.length === 0) {\n        throw new ValidationError(\n          `withDerivation: self-write output \"${outputKey}\" (collection === source \"${spec.source}\") `\n          + 'must declare `denorm: [...]` naming the fields it maintains.',\n        )\n      }\n    }\n    if (outputSpec.shape === 'array') {\n      if (lifecycleMode !== 'eager') {\n        throw new ValidationError(\n          `withDerivation: shape 'array' supports lifecycle 'eager' only in this release `\n          + `Output \"${outputKey}\" declared lifecycle '${lifecycleMode}'. `\n          + 'Switch to `lifecycle: \"eager\"` or use shape: \"record\".',\n        )\n      }\n      if (typeof outputSpec.key !== 'function') {\n        throw new ValidationError(\n          `withDerivation: shape 'array' output \"${outputKey}\" requires \\`key: (out) => string\\`.`,\n        )\n      }\n      if (outputSpec.maxFanout !== undefined) {\n        if (!Number.isInteger(outputSpec.maxFanout) || outputSpec.maxFanout < 1) {\n          throw new ValidationError(\n            `withDerivation: maxFanout for output \"${outputKey}\" must be a positive integer `\n            + `(got ${String(outputSpec.maxFanout)}).`,\n          )\n        }\n      }\n    }\n  }\n\n  return {\n    __noydb_strategy: 'derivation',\n    // eslint-disable-next-line @typescript-eslint/no-explicit-any\n    spec: spec as DerivationStrategy<any, any>,\n  }\n}\n","import { ValidationError } from '../../kernel/errors.js'\nimport type { DerivationStrategy, DerivationStrategyHandle } from './types.js'\n\n/**\n * `withRollup` — aggregate many child records onto a single field of their\n * parent. The reverse of a join: instead of reading children\n * on demand, the parent carries a maintained summary.\n *\n * ```ts\n * withRollup<Sale, Buyer>({\n *   from: 'sales',          // child collection (the trigger)\n *   key: 'buyerId',         // FK on the child → parent id\n *   into: 'buyers',         // parent collection\n *   field: 'revenueByYear', // field on the parent to maintain\n *   compute: (sales) => groupSumByYear(sales, 'total'),\n * })\n * ```\n *\n * On every write OR delete of a `from` record, the parent at id `child[key]`\n * is recomputed: `compute(allChildren where child[key] === parentId)` is\n * patched onto `parent[field]`. A parent write also recomputes its own\n * aggregate (so a parent created after its children still fills in). Only the\n * `field` is touched — the rest of the parent record is never clobbered — and\n * a value-equality guard suppresses no-op writes. The aggregate is gap-free\n * with respect to child inserts, updates, and deletes.\n *\n * Desugars to a `withDerivation` strategy carrying a `rollup` marker; dispatch\n * handles it without invoking the executor. Eager-only in this slice.\n */\nexport function withRollup<\n  TChild extends Record<string, unknown> = Record<string, unknown>,\n  TParent extends Record<string, unknown> = Record<string, unknown>,\n>(config: {\n  from: string\n  key: keyof TChild & string\n  into: string\n  field: keyof TParent & string\n  compute: (children: TChild[]) => unknown\n}): DerivationStrategyHandle {\n  const { from, key, into, field, compute } = config\n  if (!from || from.length === 0) {\n    throw new ValidationError('withRollup: `from` (child collection) is required')\n  }\n  if (!into || into.length === 0) {\n    throw new ValidationError('withRollup: `into` (parent collection) is required')\n  }\n  if (from === into) {\n    throw new ValidationError('withRollup: `from` and `into` must be different collections')\n  }\n  if (!key || key.length === 0) {\n    throw new ValidationError('withRollup: `key` (FK field on the child) is required')\n  }\n  if (!field || field.length === 0) {\n    throw new ValidationError('withRollup: `field` (target field on the parent) is required')\n  }\n  if (typeof compute !== 'function') {\n    throw new ValidationError('withRollup: `compute` must be a function')\n  }\n\n  // eslint-disable-next-line @typescript-eslint/no-explicit-any\n  const spec: DerivationStrategy<any, any> = {\n    source: into, // the parent record is what carries the rolled-up field\n    deterministic: true,\n    rollup: { from, key, field, compute: compute as (children: unknown[]) => unknown },\n    // Synthetic self-write output for registry / cycle bookkeeping. Dispatch\n    // patches `field` directly (value-equality guarded); the executor is not run.\n    outputs: { value: { shape: 'record', collection: into, denorm: [field] } },\n    derive: () => ({ value: {} }), // never invoked for a rollup strategy\n    lifecycle: 'eager',\n  }\n\n  return { __noydb_strategy: 'derivation', spec }\n}\n"],"mappings":"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","names":[]}