@noy-db/hub 0.3.0-pre.9 → 0.4.0-pre.0

package/dist/chunk-QDPZWTN2.js

@@ -0,0 +1,74 @@
+import {
+  linkI18nVia
+} from "./chunk-GULTLPFB.js";
+
+// src/via/i18n/dictionary.ts
+function dictKey(name, keysOrMap, opts) {
+  linkI18nVia();
+  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;
+  }
+  const equiv = {
+    _viaBrand: "lookup",
+    dimension: name,
+    key: "id",
+    vocabulary: "open",
+    backing: "reserved",
+    onDelete: "restrict",
+    ...keys !== void 0 ? { keys } : {},
+    ...opts?.onMissing !== void 0 ? { onMissing: opts.onMissing } : {},
+    ...opts?.substitute !== void 0 ? { substitute: opts.substitute } : {},
+    ...labels !== void 0 ? { labels } : {}
+  };
+  return {
+    _noydbDictKey: true,
+    _viaBrand: "i18n",
+    name: equiv.dimension,
+    keys: equiv.keys,
+    ...equiv.onMissing !== void 0 ? { onMissing: equiv.onMissing } : {},
+    ...equiv.substitute !== void 0 ? { substitute: equiv.substitute } : {},
+    ...equiv.labels !== void 0 ? { labels: equiv.labels } : {}
+  };
+}
+function staticDict(name, table, opts) {
+  linkI18nVia();
+  const equiv = {
+    _viaBrand: "lookup",
+    dimension: name,
+    key: "id",
+    vocabulary: "closed",
+    backing: "static",
+    onDelete: "restrict",
+    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 } : {}
+  };
+  return {
+    _noydbStaticDict: true,
+    _viaBrand: "i18n",
+    name: equiv.dimension,
+    table: equiv.table,
+    keys: equiv.keys,
+    ...equiv.displayLocale !== void 0 ? { displayLocale: equiv.displayLocale } : {},
+    ...equiv.onMissing !== void 0 ? { onMissing: equiv.onMissing } : {},
+    ...equiv.substitute !== void 0 ? { substitute: equiv.substitute } : {},
+    ...opts?.validateCodes !== void 0 ? { validateCodes: opts.validateCodes } : {}
+  };
+}
+
+export {
+  dictKey,
+  staticDict
+};
+//# sourceMappingURL=chunk-QDPZWTN2.js.map

package/dist/chunk-QDPZWTN2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/via/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 * The storage engine (`DictionaryHandle`, `DictEntry`, `DictionaryOptions`,\n * `DICT_COLLECTION_PREFIX`, `dictCollectionName`) moved to\n * `via/lookup/handle.ts` (#650 Task 1 — via-lookup extraction, phase\n * D of the Via port) and is renamed `LookupHandle` there; re-exported here\n * under the original names for one release so existing importers of this\n * module compile unchanged. This file keeps only the descriptor factories\n * (`dictKey`/`staticDict`), which are locale/i18n-coupled and stay put.\n */\n\nimport type { OnMissingPolicy } from './policy.js'\nimport { linkI18nVia } from './binding.js'\n// #650 Task 2 — type-only: dictKey()/staticDict() construct the equivalent\n// LookupDescriptor shape internally (the reserved/static tiers via-lookup's\n// dict()/lookup(static) also produce) before adapting it to their own\n// legacy public return shape. No runtime dependency on via/lookup.\nimport type { LookupDescriptor } from '../lookup/descriptor.js'\n\n// `isDictCollectionName` now lives on the kernel port (#623 Task 7,\n// port/with/i18n-strategy.ts) — re-exported here for compat. Its `'_dict_'`\n// check is a duplicate of DICT_COLLECTION_PREFIX (now on\n// via/lookup/handle.ts, not an import, to avoid a port→feature value\n// dependency); keep the two in sync.\nexport { isDictCollectionName } from '../../port/with/i18n-strategy.js'\n\n// Storage-engine re-exports (#650 Task 1 — moved to via/lookup/handle.ts).\nexport {\n  DictionaryHandle,\n  DICT_COLLECTION_PREFIX,\n  dictCollectionName,\n  type DictEntry,\n  type DictionaryOptions,\n} from '../lookup/handle.js'\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  /** Via port brand marker (#623 Task 9) — dictKey shares the i18n binding brand. */\n  readonly _viaBrand: 'i18n'\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  // The declaration is the Via binding's opt-in unit (#553) — same pattern\n  // as i18nText()/money().\n  linkI18nVia()\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  // #650 Task 2 — dictKey is the reserved-backing tier of via-lookup\n  // (dict()'s alias); construct the equivalent LookupDescriptor shape so\n  // the two tiers' field semantics stay in lockstep, then adapt it to\n  // dictKey's legacy public return shape. `_viaBrand` stays `'i18n'` for\n  // one release (see task-2-report.md's alias-brand decision) —\n  // mergeViaFields/compileViaBindings's existing i18nFields+dictKeyFields\n  // path is untouched.\n  const equiv: LookupDescriptor<Keys> = {\n    _viaBrand: 'lookup',\n    dimension: name,\n    key: 'id',\n    vocabulary: 'open',\n    backing: 'reserved',\n    onDelete: 'restrict',\n    ...(keys !== undefined ? { keys } : {}),\n    ...(opts?.onMissing !== undefined ? { onMissing: opts.onMissing } : {}),\n    ...(opts?.substitute !== undefined ? { substitute: opts.substitute } : {}),\n    ...(labels !== undefined ? { labels } : {}),\n  }\n  return {\n    _noydbDictKey: true,\n    _viaBrand: 'i18n',\n    name: equiv.dimension,\n    keys: equiv.keys,\n    ...(equiv.onMissing !== undefined ? { onMissing: equiv.onMissing } : {}),\n    ...(equiv.substitute !== undefined ? { substitute: equiv.substitute } : {}),\n    ...(equiv.labels !== undefined ? { labels: equiv.labels } : {}),\n  }\n}\n\n// `isDictKeyDescriptor` now lives on the kernel port (#623 Task 11,\n// port/with/i18n-strategy.ts, alongside `isStaticDictDescriptor`) —\n// re-exported here for compat with existing importers of this module.\nexport { isDictKeyDescriptor } from '../../port/with/i18n-strategy.js'\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  /** Via port brand marker (#623 Task 9) — staticDict shares the i18n binding brand. */\n  readonly _viaBrand: 'i18n'\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  // The declaration is the Via binding's opt-in unit (#553) — same pattern\n  // as i18nText()/dictKey()/money().\n  linkI18nVia()\n  type K = Extract<keyof T, string>\n  // #650 Task 2 — staticDict is the static-backing tier of via-lookup\n  // (lookup(dimension, {backing:'static', table, ...})'s alias); construct\n  // the equivalent LookupDescriptor shape, then adapt it to staticDict's\n  // legacy public return shape. `validateCodes` has no LookupDescriptor\n  // equivalent (a dictKey-family-only put-time knob) — applied directly\n  // below. `_viaBrand` stays `'i18n'` for one release — see\n  // task-2-report.md's alias-brand decision.\n  const equiv: LookupDescriptor<K> = {\n    _viaBrand: 'lookup',\n    dimension: name,\n    key: 'id',\n    vocabulary: 'closed',\n    backing: 'static',\n    onDelete: 'restrict',\n    table: table as Readonly<Record<string, Readonly<Record<string, string>>>>,\n    keys: Object.keys(table) as K[],\n    ...(opts?.displayLocale !== undefined ? { displayLocale: opts.displayLocale } : {}),\n    ...(opts?.onMissing !== undefined ? { onMissing: opts.onMissing } : {}),\n    ...(opts?.substitute !== undefined ? { substitute: opts.substitute } : {}),\n  }\n  return {\n    _noydbStaticDict: true,\n    _viaBrand: 'i18n',\n    name: equiv.dimension,\n    table: equiv.table as Readonly<Record<K, Readonly<Record<string, string>>>>,\n    keys: equiv.keys as readonly K[],\n    ...(equiv.displayLocale !== undefined ? { displayLocale: equiv.displayLocale } : {}),\n    ...(equiv.onMissing !== undefined ? { onMissing: equiv.onMissing } : {}),\n    ...(equiv.substitute !== undefined ? { substitute: equiv.substitute } : {}),\n    ...(opts?.validateCodes !== undefined ? { validateCodes: opts.validateCodes } : {}),\n  }\n}\n\n// `isStaticDictDescriptor` now lives on the kernel port (#623 Task 7,\n// port/with/i18n-strategy.ts) — re-exported here for compat.\nexport { isStaticDictDescriptor } from '../../port/with/i18n-strategy.js'\n\n"],"mappings":";;;;;AAwIO,SAAS,QACd,MACA,WACA,MACyB;AAGzB,cAAY;AACZ,MAAI;AACJ,MAAI;AACJ,MAAI,MAAM,QAAQ,SAAS,GAAG;AAC5B,WAAO;AACP,aAAS,MAAM;AAAA,EACjB,WAAW,aAAa,OAAO,cAAc,UAAU;AACrD,WAAO,OAAO,KAAK,SAAS;AAC5B,aAAS;AAAA,EACX,OAAO;AACL,WAAO;AACP,aAAS,MAAM;AAAA,EACjB;AAQA,QAAM,QAAgC;AAAA,IACpC,WAAW;AAAA,IACX,WAAW;AAAA,IACX,KAAK;AAAA,IACL,YAAY;AAAA,IACZ,SAAS;AAAA,IACT,UAAU;AAAA,IACV,GAAI,SAAS,SAAY,EAAE,KAAK,IAAI,CAAC;AAAA,IACrC,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,KAAK,UAAU,IAAI,CAAC;AAAA,IACrE,GAAI,MAAM,eAAe,SAAY,EAAE,YAAY,KAAK,WAAW,IAAI,CAAC;AAAA,IACxE,GAAI,WAAW,SAAY,EAAE,OAAO,IAAI,CAAC;AAAA,EAC3C;AACA,SAAO;AAAA,IACL,eAAe;AAAA,IACf,WAAW;AAAA,IACX,MAAM,MAAM;AAAA,IACZ,MAAM,MAAM;AAAA,IACZ,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,UAAU,IAAI,CAAC;AAAA,IACtE,GAAI,MAAM,eAAe,SAAY,EAAE,YAAY,MAAM,WAAW,IAAI,CAAC;AAAA,IACzE,GAAI,MAAM,WAAW,SAAY,EAAE,QAAQ,MAAM,OAAO,IAAI,CAAC;AAAA,EAC/D;AACF;AAsFO,SAAS,WACd,MACA,OACA,MAMgD;AAGhD,cAAY;AASZ,QAAM,QAA6B;AAAA,IACjC,WAAW;AAAA,IACX,WAAW;AAAA,IACX,KAAK;AAAA,IACL,YAAY;AAAA,IACZ,SAAS;AAAA,IACT,UAAU;AAAA,IACV;AAAA,IACA,MAAM,OAAO,KAAK,KAAK;AAAA,IACvB,GAAI,MAAM,kBAAkB,SAAY,EAAE,eAAe,KAAK,cAAc,IAAI,CAAC;AAAA,IACjF,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,KAAK,UAAU,IAAI,CAAC;AAAA,IACrE,GAAI,MAAM,eAAe,SAAY,EAAE,YAAY,KAAK,WAAW,IAAI,CAAC;AAAA,EAC1E;AACA,SAAO;AAAA,IACL,kBAAkB;AAAA,IAClB,WAAW;AAAA,IACX,MAAM,MAAM;AAAA,IACZ,OAAO,MAAM;AAAA,IACb,MAAM,MAAM;AAAA,IACZ,GAAI,MAAM,kBAAkB,SAAY,EAAE,eAAe,MAAM,cAAc,IAAI,CAAC;AAAA,IAClF,GAAI,MAAM,cAAc,SAAY,EAAE,WAAW,MAAM,UAAU,IAAI,CAAC;AAAA,IACtE,GAAI,MAAM,eAAe,SAAY,EAAE,YAAY,MAAM,WAAW,IAAI,CAAC;AAAA,IACzE,GAAI,MAAM,kBAAkB,SAAY,EAAE,eAAe,KAAK,cAAc,IAAI,CAAC;AAAA,EACnF;AACF;","names":[]}

package/dist/chunk-R3BLCFD2.js

@@ -0,0 +1,130 @@
+import {
+  linkCollectionName,
+  linkRowKey
+} from "./chunk-RTEK4C4I.js";
+import {
+  openEnvelopeJson
+} from "./chunk-W4TCUGQR.js";
+import {
+  encrypt
+} from "./chunk-HOONYZY2.js";
+import {
+  NOYDB_FORMAT_VERSION
+} from "./chunk-VCTXU4AT.js";
+import {
+  NoydbError
+} from "./chunk-W2OG6JOL.js";
+
+// src/with-shape/links/link-set.ts
+var LinkSet = class {
+  constructor(adapter, vault, name, spec, encrypted, getDEK, actor, emitter, endpointExists) {
+    this.adapter = adapter;
+    this.vault = vault;
+    this.name = name;
+    this.spec = spec;
+    this.encrypted = encrypted;
+    this.getDEK = getDEK;
+    this.actor = actor;
+    this.emitter = emitter;
+    this.endpointExists = endpointExists;
+    this.collName = linkCollectionName(name);
+  }
+  adapter;
+  vault;
+  name;
+  spec;
+  encrypted;
+  getDEK;
+  actor;
+  emitter;
+  endpointExists;
+  collName;
+  dekPromise = null;
+  dek() {
+    if (!this.dekPromise) this.dekPromise = this.getDEK(this.collName);
+    return this.dekPromise;
+  }
+  async encryptEntry(entry, version) {
+    const json = JSON.stringify(entry);
+    const base = { _noydb: NOYDB_FORMAT_VERSION, _v: version, _ts: (/* @__PURE__ */ new Date()).toISOString(), _by: this.actor };
+    if (!this.encrypted) return { ...base, _iv: "", _data: json };
+    const { iv, data } = await encrypt(json, await this.dek());
+    return { ...base, _iv: iv, _data: data };
+  }
+  async decryptEntry(env) {
+    const json = this.encrypted ? await openEnvelopeJson(env, await this.dek()) : env._data;
+    return JSON.parse(json);
+  }
+  async connect(aId, bId, meta) {
+    if (!await this.endpointExists(this.spec.a, aId)) {
+      throw new LinkEndpointError(this.name, this.spec.a, aId);
+    }
+    if (!await this.endpointExists(this.spec.b, bId)) {
+      throw new LinkEndpointError(this.name, this.spec.b, bId);
+    }
+    const key = linkRowKey(aId, bId);
+    const entry = meta !== void 0 ? { a: aId, b: bId, meta } : { a: aId, b: bId };
+    const existing = await this.adapter.get(this.vault, this.collName, key);
+    const env = await this.encryptEntry(entry, (existing?._v ?? 0) + 1);
+    await this.adapter.put(this.vault, this.collName, key, env, existing?._v);
+    this.emitter.emit("change", { vault: this.vault, collection: this.collName, id: key, action: "put" });
+  }
+  async disconnect(aId, bId) {
+    const key = linkRowKey(aId, bId);
+    const existing = await this.adapter.get(this.vault, this.collName, key);
+    if (!existing) return;
+    await this.adapter.delete(this.vault, this.collName, key);
+    this.emitter.emit("change", { vault: this.vault, collection: this.collName, id: key, action: "delete" });
+  }
+  async has(aId, bId) {
+    return await this.adapter.get(this.vault, this.collName, linkRowKey(aId, bId)) !== null;
+  }
+  async of(id) {
+    const rows = await this.list();
+    return rows.filter((r) => r.a === id || r.b === id);
+  }
+  async list() {
+    const keys = await this.adapter.list(this.vault, this.collName);
+    const out = [];
+    for (const key of keys) {
+      const env = await this.adapter.get(this.vault, this.collName, key);
+      if (!env) continue;
+      const e = await this.decryptEntry(env);
+      out.push(e.meta !== void 0 ? { a: e.a, b: e.b, meta: e.meta } : { a: e.a, b: e.b });
+    }
+    return out;
+  }
+  // ── Vault-internal cascade helpers ──────────────────────────────────
+  /** @internal — rows where the deleted endpoint id matches the relevant slot. */
+  async _rowsTouchingEndpoint(collection, id) {
+    const rows = await this.list();
+    return rows.filter(
+      (r) => this.spec.a === collection && r.a === id || this.spec.b === collection && r.b === id
+    );
+  }
+  /** @internal — the storage collection name (for tx pre-image capture). */
+  get _collectionName() {
+    return this.collName;
+  }
+};
+var LinkEndpointError = class extends NoydbError {
+  link;
+  endpoint;
+  missingId;
+  constructor(link, endpoint, missingId) {
+    super(
+      "LINK_ENDPOINT",
+      `link("${link}").connect: endpoint "${endpoint}" has no record "${missingId}".`
+    );
+    this.name = "LinkEndpointError";
+    this.link = link;
+    this.endpoint = endpoint;
+    this.missingId = missingId;
+  }
+};
+
+export {
+  LinkSet,
+  LinkEndpointError
+};
+//# sourceMappingURL=chunk-R3BLCFD2.js.map

package/dist/chunk-RA5VTXXG.js

@@ -0,0 +1,173 @@
+import {
+  readPath
+} from "./chunk-IGJCYUT5.js";
+import {
+  DanglingReferenceError,
+  JoinTooLargeError
+} from "./chunk-W2OG6JOL.js";
+
+// src/kernel/query/join.ts
+var DEFAULT_JOIN_MAX_ROWS = 5e4;
+var JOIN_WARN_FRACTION = 0.8;
+function coerceRefKey(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return null;
+}
+var warnedDanglingKeys = /* @__PURE__ */ new Set();
+function warnOnceDangling(field, target, refId) {
+  const key = `${field}\u2192${target}:${refId}`;
+  if (warnedDanglingKeys.has(key)) return;
+  warnedDanglingKeys.add(key);
+  console.warn(
+    `[noy-db] .join() encountered dangling ref in 'warn' mode: field "${field}" \u2192 "${target}:${refId}" not found. Attaching null.`
+  );
+}
+var warnedCeilingKeys = /* @__PURE__ */ new Set();
+function warnCeilingApproaching(target, side, rows, maxRows) {
+  const key = `${target}:${side}`;
+  if (warnedCeilingKeys.has(key)) return;
+  warnedCeilingKeys.add(key);
+  const pct = Math.round(rows / maxRows * 100);
+  console.warn(
+    `[noy-db] .join() ${side} side is at ${pct}% of the ${maxRows}-row ceiling for target "${target}" (${rows} rows). Streaming joins over scan() are not yet supported for collections that need to exceed this.`
+  );
+}
+function applyJoins(rows, joins, context, locale) {
+  if (joins.length === 0) return [...rows];
+  let result = [...rows];
+  for (const leg of joins) {
+    result = applyOneJoin(result, leg, context, locale);
+  }
+  return result;
+}
+function applyOneJoin(leftRows, leg, context, locale) {
+  if (leg.isDictJoin) {
+    const dictSource = context.resolveDictSource?.(leg.field);
+    if (!dictSource) {
+      throw new Error(
+        `.join() field "${leg.field}" on "${context.leftCollection}" is declared as a dictKey join but the dict source could not be resolved. Ensure the dictionary has at least one entry.`
+      );
+    }
+    const out = [];
+    const snapshot = dictSource.snapshot();
+    const dictMap = /* @__PURE__ */ new Map();
+    for (const entry of snapshot) {
+      const k = readPath(entry, "key");
+      if (typeof k === "string") dictMap.set(k, entry);
+    }
+    for (const left of leftRows) {
+      const rawId = readPath(left, leg.field);
+      const key = coerceRefKey(rawId);
+      const dictEntry = key === null ? void 0 : dictMap.get(key);
+      out.push({ ...left, [leg.as]: dictEntry ?? null });
+    }
+    return out;
+  }
+  const source = context.resolveSource(leg.target);
+  if (!source) {
+    throw new Error(
+      `.join() cannot resolve target collection "${leg.target}" (referenced from field "${leg.field}" on "${context.leftCollection}"). Make sure the target collection has been opened via vault.collection() at least once before running the query.`
+    );
+  }
+  const maxRows = leg.maxRows ?? DEFAULT_JOIN_MAX_ROWS;
+  if (leftRows.length > maxRows) {
+    throw new JoinTooLargeError({
+      leftRows: leftRows.length,
+      rightRows: -1,
+      maxRows,
+      side: "left",
+      message: `.join() left side has ${leftRows.length} rows, exceeding the ${maxRows}-row ceiling for target "${leg.target}". Filter the left side further with where()/limit() before joining, or raise the ceiling via { maxRows }. Streaming joins over scan() are not yet supported.`
+    });
+  }
+  if (leftRows.length > maxRows * JOIN_WARN_FRACTION) {
+    warnCeilingApproaching(leg.target, "left", leftRows.length, maxRows);
+  }
+  const rightSnapshot = source.snapshot();
+  if (rightSnapshot.length > maxRows) {
+    throw new JoinTooLargeError({
+      leftRows: leftRows.length,
+      rightRows: rightSnapshot.length,
+      maxRows,
+      side: "right",
+      message: `.join() right side "${leg.target}" has ${rightSnapshot.length} rows, exceeding the ${maxRows}-row ceiling. Raise the ceiling via { maxRows } if the data genuinely fits in memory, or track  for streaming joins.`
+    });
+  }
+  if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {
+    warnCeilingApproaching(leg.target, "right", rightSnapshot.length, maxRows);
+  }
+  const effLocale = locale ?? context.defaultLocale;
+  const presentResolve = effLocale !== void 0 && source.presentForJoin !== void 0 ? (right) => right !== null && typeof right === "object" ? source.presentForJoin(right, effLocale) : right : void 0;
+  const strategy = leg.strategy ?? (source.lookupById ? "nested" : "hash");
+  if (strategy === "nested" && source.lookupById) {
+    const lookup = (id) => source.lookupById?.(id);
+    return nestedLoopJoin(leftRows, leg, lookup, presentResolve);
+  }
+  return hashJoin(leftRows, leg, rightSnapshot, presentResolve);
+}
+function nestedLoopJoin(leftRows, leg, lookupById, presentResolve) {
+  const out = [];
+  for (const left of leftRows) {
+    const rawId = readPath(left, leg.field);
+    const key = coerceRefKey(rawId);
+    let right = key === null ? void 0 : lookupById(key);
+    if (presentResolve && right !== void 0) right = presentResolve(right);
+    out.push(attachJoin(left, leg, right, rawId));
+  }
+  return out;
+}
+function hashJoin(leftRows, leg, rightSnapshot, presentResolve) {
+  const rightMap = /* @__PURE__ */ new Map();
+  for (const record of rightSnapshot) {
+    const rawId = readPath(record, "id");
+    const key = coerceRefKey(rawId);
+    if (key !== null) {
+      rightMap.set(key, record);
+    }
+  }
+  const out = [];
+  for (const left of leftRows) {
+    const rawId = readPath(left, leg.field);
+    const key = coerceRefKey(rawId);
+    let right = key === null ? void 0 : rightMap.get(key);
+    if (presentResolve && right !== void 0) right = presentResolve(right);
+    out.push(attachJoin(left, leg, right, rawId));
+  }
+  return out;
+}
+function attachJoin(left, leg, right, rawId) {
+  if (left === null || typeof left !== "object") {
+    return left;
+  }
+  const merged = { ...left };
+  const refKey = coerceRefKey(rawId);
+  if (right === void 0) {
+    if (refKey !== null && leg.mode === "strict") {
+      throw new DanglingReferenceError({
+        field: leg.field,
+        target: leg.target,
+        refId: refKey,
+        message: `.join() strict dangling: record references "${leg.target}:${refKey}" via field "${leg.field}", but no such record exists. Use ref() mode 'warn' or 'cascade' if dangling refs are acceptable, or run vault.checkIntegrity() to find and fix the orphans.`
+      });
+    }
+    if (refKey !== null && leg.mode === "warn") {
+      warnOnceDangling(leg.field, leg.target, refKey);
+    }
+    merged[leg.as] = null;
+  } else {
+    merged[leg.as] = right;
+  }
+  return merged;
+}
+function resetJoinWarnings() {
+  warnedDanglingKeys.clear();
+  warnedCeilingKeys.clear();
+}
+
+export {
+  DEFAULT_JOIN_MAX_ROWS,
+  applyJoins,
+  resetJoinWarnings
+};
+//# sourceMappingURL=chunk-RA5VTXXG.js.map

package/dist/chunk-RA5VTXXG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kernel/query/join.ts"],"sourcesContent":["/**\n * Query DSL `.join()` — eager, single-FK, intra-vault joins.\n *\n * resolves a ref()-declared foreign key into an attached\n * right-side record under an alias, using one of two planner paths\n * selected automatically:\n *\n *   - **nested-loop** — right-side source exposes `lookupById`, so\n *     each left row costs O(1). This is the common path for joins\n *     against a Collection, which backs `lookupById` with a Map\n *     lookup.\n *   - **hash** — right-side has only `snapshot()`. Build a\n *     `Map<id, record>` once, probe per left row. Same asymptotic\n *     cost for our collections, but the path exists as a fallback\n *     for custom QuerySource implementations and as an explicit\n *     test-only override via `{ strategy: 'hash' }`.\n *\n * Scope:\n *\n *   - Equi-joins on declared `ref()` fields only. Joins on\n *     undeclared fields throw at plan time with an actionable error\n *     naming the field and collection.\n *   - Same-vault only. Cross-vault correlation goes\n *     through `queryAcross`; this is an architectural\n *     invariant, not a limitation we plan to lift.\n *   - Hard row ceiling via `JoinTooLargeError` — default 50k per\n *     side, override via `{ maxRows }`. Warns at 80% of the ceiling\n *     on the existing warn channel.\n *   - Three ref-mode behaviors on dangling refs:\n *     strict → `DanglingReferenceError`,\n *     warn → attach `null` with a one-shot warning,\n *     cascade → attach `null` silently (cascade is a delete-time\n *     mode; any dangling refs still present at read time are\n *     mid-flight cascades or orphans from earlier, not a DSL error).\n *\n * Partition-awareness seam:\n *\n * Every `JoinLeg` carries a `partitionScope` field that is always\n * `'all'` in. The executor never reads this field.\n * partition-aware joins will start populating it from `where()`\n * predicates on the partition key without changing the planner's\n * external shape — this is the whole reason it exists now.\n *\n * Joins stay OUT of the ledger: reads don't touch `_ledger/`,\n * including joined reads.\n */\n\nimport type { RefDescriptor, RefMode } from '../refs.js'\nimport { readPath } from './predicate.js'\nimport { JoinTooLargeError, DanglingReferenceError } from '../errors.js'\n\n/** Planner strategy for a single join leg. Auto-selected unless overridden. */\nexport type JoinStrategy = 'hash' | 'nested'\n\n/** Default per-side row ceiling before `.join()` throws `JoinTooLargeError`. */\nexport const DEFAULT_JOIN_MAX_ROWS = 50_000\n\n/**\n * Fraction of the row ceiling at which a one-shot warning is emitted.\n * At 80% we warn; at 100% we throw. The warn gives consumers a\n * heads-up before the hard error so they can raise the ceiling or\n * filter further without first hitting a broken query.\n */\nconst JOIN_WARN_FRACTION = 0.8\n\n/**\n * Internal representation of a single join leg in the query plan.\n *\n * This is the primary place where  constraint #1 is honored:\n * every leg carries a `partitionScope` field that is always `'all'`\n * in and is never read by the executor. partition-aware\n * joins will start populating it from `where()` predicates on the\n * partition key without changing the planner's external shape.\n */\nexport interface JoinLeg {\n  /** Field on the left-side record holding the foreign key value. */\n  readonly field: string\n  /** Alias key under which the joined right-side record attaches. */\n  readonly as: string\n  /** Target collection name, resolved from the `ref()` declaration. */\n  readonly target: string\n  /** Ref mode controlling behavior on dangling refs at read time. */\n  readonly mode: RefMode\n  /** Manual planner strategy override. `undefined` → auto-select. */\n  readonly strategy: JoinStrategy | undefined\n  /** Per-side row ceiling override. `undefined` → DEFAULT_JOIN_MAX_ROWS. */\n  readonly maxRows: number | undefined\n  /**\n   * Partition scope for future partition-aware joins. Always `'all'`\n   * today — the executor never reads this field. Future versions will\n   * populate it from `where()` predicates without breaking the\n   * planner's external shape. Do not remove even though it looks\n   * unused today — that's the whole point of having it.\n   */\n  readonly partitionScope: 'all' | readonly string[]\n  /**\n   * When `true`, this is a dictionary join. The executor\n   * resolves the left-field value against the dict snapshot and\n   * attaches `{ ...labels, key }` rather than a right-side record.\n   * `target` holds the dictionary name (not a collection name).\n   */\n  readonly isDictJoin?: true\n}\n\n/**\n * Minimal shape of a joinable right-side record source.\n *\n * Collections implement this structurally via their `QuerySource`;\n * sources without `lookupById` force the hash-join fallback. Kept as\n * a thin interface so tests can wire up plain-object sources without\n * pulling in the full Collection class.\n *\n * The optional `subscribe` is used by `Query.live()` to merge\n * right-side change streams into the live re-run trigger. Sources\n * that omit `subscribe` still work for live joins — they just\n * don't drive re-fires when their right side mutates. Collection\n * implements `subscribe` by hooking into the existing per-\n * vault event emitter.\n */\nexport interface JoinableSource {\n  snapshot(): readonly unknown[]\n  lookupById?(id: string): unknown\n  /**\n   * Default locale a label-resolving query falls back to when the query\n   * itself is locale-less. Set by a `staticDict()`-backed source from its\n   * `displayLocale` so `{ by: 'label' }` resolves under a locale-less read.\n   * Plain `_dict_*`-backed sources omit it.\n   */\n  readonly displayLocale?: string\n  /**\n   * Sync present-for-join dressing (#626 retirement, #650 Task 6) — when\n   * present and the query carries a locale, each joined right-side record\n   * is passed through this hook (built by the right-side `Collection` from\n   * its own i18n-text + lookup-label bindings) BEFORE it is attached under\n   * the leg's alias — so a joined `i18nText` field resolves to a string\n   * (not a raw `{ locale }` map) and a joined lookup field gains its\n   * `<field>Label`. Locale-less queries leave joined fields raw\n   * (consistent with a locale-less read). Replaces the old `i18nFields`\n   * data field — the join executor no longer resolves i18n locale itself,\n   * it just calls this hook.\n   */\n  readonly presentForJoin?: (record: unknown, locale: string) => unknown\n  /**\n   * Subscribe to mutations on this source. The callback fires\n   * AFTER the underlying record set has been updated. Returns an\n   * unsubscribe function. Optional — sources without this method\n   * cannot trigger live-join re-fires from their side.\n   */\n  subscribe?(cb: () => void): () => void\n}\n\n/**\n * Join resolution context attached to a `Query` when it's constructed\n * from a `Collection`. Holds everything the `.join()` method needs to\n * translate a field name into a target collection + ref mode, and\n * everything the executor needs to read the right side.\n *\n * Kept as a structural interface so `Vault` can implement it\n * without `Query` needing to import `Vault` (circular-import\n * avoid). The Collection wires this up in its `query()` method using\n * the `joinResolver` back-reference the Vault passes in.\n */\nexport interface JoinContext {\n  /** Name of the left-side (owning) collection. */\n  readonly leftCollection: string\n  /**\n   * The owning collection's default locale. Used to resolve joined\n   * i18n fields at the `join` layer when a terminal call doesn't pass an\n   * explicit locale — so `openVault({ locale })` flows to joins like it does\n   * to `get`/`list`. A per-call `toArray({ locale })` overrides it.\n   */\n  readonly defaultLocale?: string\n  /** Look up a `RefDescriptor` by field name on the left collection. */\n  resolveRef(field: string): RefDescriptor | null\n  /** Resolve a right-side source by target collection name. */\n  resolveSource(collectionName: string): JoinableSource | null\n  /**\n   * Resolve a dictKey join source. Returns a `JoinableSource`\n   * whose snapshot exposes `{ key, ...labels }` records, keyed by the\n   * stable dictionary key. `null` when the field is not a dictKey.\n   *\n   * The source is built from the compartment's in-memory dictionary\n   * snapshot — same data as `DictionaryHandle.list()`, O(1) per lookup.\n   */\n  resolveDictSource?(field: string): JoinableSource | null\n}\n\n/**\n * Coerce an unknown FK value into a lookup key string.\n *\n * Legitimate ref values are strings or numbers — the same narrowing\n * the write-time `enforceRefsOnPut` path applies. Anything else\n * (objects, arrays, booleans, null, undefined) is treated as \"no\n * ref\" and returns `null`, so the join attaches `null` instead of\n * running `String({})` and producing `'[object Object]'` as a\n * bucket key. This matches the lint rule guidance and keeps\n * bizarre FK values from producing silently-wrong lookups.\n */\nfunction coerceRefKey(value: unknown): string | null {\n  if (value === null || value === undefined) return null\n  if (typeof value === 'string') return value\n  if (typeof value === 'number' || typeof value === 'bigint') return String(value)\n  return null\n}\n\n/**\n * Warn-channel deduplication for dangling-ref `'warn'` mode. Keyed\n * by `field → target:refId` so the same dangling ref only produces\n * one warning even across many rows or repeated queries.\n */\nconst warnedDanglingKeys = new Set<string>()\nfunction warnOnceDangling(field: string, target: string, refId: string): void {\n  const key = `${field}→${target}:${refId}`\n  if (warnedDanglingKeys.has(key)) return\n  warnedDanglingKeys.add(key)\n  console.warn(\n    `[noy-db] .join() encountered dangling ref in 'warn' mode: ` +\n      `field \"${field}\" → \"${target}:${refId}\" not found. Attaching null.`,\n  )\n}\n\n/**\n * Track row-ceiling warnings to fire only once per (target, side).\n * Prevents per-query spam when a consumer is running the same query\n * repeatedly (e.g. in a reactive loop).\n */\nconst warnedCeilingKeys = new Set<string>()\nfunction warnCeilingApproaching(\n  target: string,\n  side: 'left' | 'right',\n  rows: number,\n  maxRows: number,\n): void {\n  const key = `${target}:${side}`\n  if (warnedCeilingKeys.has(key)) return\n  warnedCeilingKeys.add(key)\n  const pct = Math.round((rows / maxRows) * 100)\n  console.warn(\n    `[noy-db] .join() ${side} side is at ${pct}% of the ${maxRows}-row ` +\n      `ceiling for target \"${target}\" (${rows} rows). Streaming joins over ` +\n      `scan() are not yet supported for collections that need to exceed this.`,\n  )\n}\n\n/**\n * Apply every join leg in the plan against a base set of left-side\n * rows. Called by the query executor after `where` / `orderBy` /\n * `offset` / `limit` have narrowed the left set.\n *\n * Each leg attaches a `leg.as` field to every row. Returns a new\n * array of plain objects — the original left rows are not mutated\n * (structural sharing is fine for the inner fields, but the\n * top-level object is a fresh clone so consumers can further mutate\n * safely).\n *\n * **Ordering:** joins run AFTER orderBy / limit / offset in v1.\n * This keeps the planner simple and means queries like \"top 10\n * invoices with client\" sort and paginate the left side first, then\n * join. Sorting *by* a joined field is out of scope for  — users\n * can post-sort the result array in userland or wait for \n * (multi-FK chaining) which can be layered on top.\n *\n * **Multi-FK chaining:** each leg's `maxRows` is enforced\n * against the current left-row count independently. Because\n * joins are equi-joins on the target's primary key (one-to-one or\n * one-to-null), the left row count is constant across legs — no\n * cartesian blowup. The per-leg left-side check is still necessary\n * so that a later leg with a tighter ceiling correctly fires on a\n * query like `.join('a', { maxRows: 100_000 }).join('b', { maxRows: 50 })`,\n * which should throw on the second leg if the left set exceeds 50.\n */\nexport function applyJoins(\n  rows: readonly unknown[],\n  joins: readonly JoinLeg[],\n  context: JoinContext,\n  locale?: string,\n): unknown[] {\n  if (joins.length === 0) return [...rows]\n\n  let result: unknown[] = [...rows]\n  for (const leg of joins) {\n    result = applyOneJoin(result, leg, context, locale)\n  }\n  return result\n}\n\nfunction applyOneJoin(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  context: JoinContext,\n  locale?: string,\n): unknown[] {\n  // Dict join path — resolve left-field value against the\n  // dictionary snapshot and attach { key, ...labels } under leg.as.\n  if (leg.isDictJoin) {\n    const dictSource = context.resolveDictSource?.(leg.field)\n    if (!dictSource) {\n      throw new Error(\n        `.join() field \"${leg.field}\" on \"${context.leftCollection}\" is declared as a ` +\n          `dictKey join but the dict source could not be resolved. ` +\n          `Ensure the dictionary has at least one entry.`,\n      )\n    }\n    const out: unknown[] = []\n    const snapshot = dictSource.snapshot()\n    const dictMap = new Map<string, unknown>()\n    for (const entry of snapshot) {\n      const k = readPath(entry, 'key')\n      if (typeof k === 'string') dictMap.set(k, entry)\n    }\n    for (const left of leftRows) {\n      const rawId = readPath(left, leg.field)\n      const key = coerceRefKey(rawId)\n      const dictEntry = key === null ? undefined : dictMap.get(key)\n      out.push({ ...(left as Record<string, unknown>), [leg.as]: dictEntry ?? null })\n    }\n    return out\n  }\n\n  const source = context.resolveSource(leg.target)\n  if (!source) {\n    throw new Error(\n      `.join() cannot resolve target collection \"${leg.target}\" ` +\n        `(referenced from field \"${leg.field}\" on \"${context.leftCollection}\"). ` +\n        `Make sure the target collection has been opened via vault.collection() ` +\n        `at least once before running the query.`,\n    )\n  }\n\n  const maxRows = leg.maxRows ?? DEFAULT_JOIN_MAX_ROWS\n\n  // Per-leg left-side ceiling check. In a\n  // multi-FK chain, each leg's `maxRows` is enforced independently\n  // against the current left-row count, so\n  // `.join('a', { maxRows: 100_000 }).join('b', { maxRows: 50 })`\n  // correctly throws on the second leg if the left set exceeds 50.\n  if (leftRows.length > maxRows) {\n    throw new JoinTooLargeError({\n      leftRows: leftRows.length,\n      rightRows: -1,\n      maxRows,\n      side: 'left',\n      message:\n        `.join() left side has ${leftRows.length} rows, exceeding the ${maxRows}-row ` +\n        `ceiling for target \"${leg.target}\". Filter the left side further with ` +\n        `where()/limit() before joining, or raise the ceiling via { maxRows }. ` +\n        `Streaming joins over scan() are not yet supported.`,\n    })\n  }\n  if (leftRows.length > maxRows * JOIN_WARN_FRACTION) {\n    warnCeilingApproaching(leg.target, 'left', leftRows.length, maxRows)\n  }\n\n  const rightSnapshot = source.snapshot()\n  if (rightSnapshot.length > maxRows) {\n    throw new JoinTooLargeError({\n      leftRows: leftRows.length,\n      rightRows: rightSnapshot.length,\n      maxRows,\n      side: 'right',\n      message:\n        `.join() right side \"${leg.target}\" has ${rightSnapshot.length} rows, ` +\n        `exceeding the ${maxRows}-row ceiling. Raise the ceiling via { maxRows } ` +\n        `if the data genuinely fits in memory, or track  for streaming joins.`,\n    })\n  }\n  if (rightSnapshot.length > maxRows * JOIN_WARN_FRACTION) {\n    warnCeilingApproaching(leg.target, 'right', rightSnapshot.length, maxRows)\n  }\n\n  // `join`-layer dressing (#650 Task 6, #626 retirement). When the query\n  // carries a locale (per-call or the owning collection's default) and the\n  // right side declares a `presentForJoin` hook, resolve each matched right\n  // record through it before it's attached. Locale-less → leave raw.\n  const effLocale = locale ?? context.defaultLocale\n  const presentResolve: ((right: unknown) => unknown) | undefined =\n    effLocale !== undefined && source.presentForJoin !== undefined\n      ? (right) =>\n          right !== null && typeof right === 'object'\n            ? source.presentForJoin!(right, effLocale)\n            : right\n      : undefined\n\n  // Strategy selection: explicit override wins; otherwise prefer\n  // nested-loop when the source exposes lookupById (O(1) per row),\n  // falling back to hash join when it doesn't.\n  const strategy: JoinStrategy =\n    leg.strategy ?? (source.lookupById ? 'nested' : 'hash')\n\n  if (strategy === 'nested' && source.lookupById) {\n    // Bind through an arrow so the `this` context of lookupById\n    // doesn't drift — same pattern as the existing candidateRecords\n    // helper in builder.ts.\n    const lookup = (id: string): unknown => source.lookupById?.(id)\n    return nestedLoopJoin(leftRows, leg, lookup, presentResolve)\n  }\n  return hashJoin(leftRows, leg, rightSnapshot, presentResolve)\n}\n\nfunction nestedLoopJoin(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  lookupById: (id: string) => unknown,\n  presentResolve?: (right: unknown) => unknown,\n): unknown[] {\n  const out: unknown[] = []\n  for (const left of leftRows) {\n    const rawId = readPath(left, leg.field)\n    const key = coerceRefKey(rawId)\n    let right = key === null ? undefined : lookupById(key)\n    if (presentResolve && right !== undefined) right = presentResolve(right)\n    out.push(attachJoin(left, leg, right, rawId))\n  }\n  return out\n}\n\nfunction hashJoin(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  rightSnapshot: readonly unknown[],\n  presentResolve?: (right: unknown) => unknown,\n): unknown[] {\n  // Build the right-side hash once per query execution. We key on\n  // the `id` field because ref() always points to a target's primary\n  // key — non-equi and non-id joins are out of scope for.\n  const rightMap = new Map<string, unknown>()\n  for (const record of rightSnapshot) {\n    const rawId = readPath(record, 'id')\n    const key = coerceRefKey(rawId)\n    if (key !== null) {\n      rightMap.set(key, record)\n    }\n  }\n  const out: unknown[] = []\n  for (const left of leftRows) {\n    const rawId = readPath(left, leg.field)\n    const key = coerceRefKey(rawId)\n    let right = key === null ? undefined : rightMap.get(key)\n    if (presentResolve && right !== undefined) right = presentResolve(right)\n    out.push(attachJoin(left, leg, right, rawId))\n  }\n  return out\n}\n\n/**\n * Attach the resolved right-side record (or null) to the left row\n * under the alias, applying ref-mode semantics for the dangling\n * case.\n *\n * A left-side record whose FK field is null/undefined is NOT a\n * dangling ref — it's \"no reference at all\", which is always\n * allowed regardless of mode. This matches the write-time\n * `enforceRefsOnPut` behavior: \"Nullish ref values are allowed —\n * treat them as 'no reference'.\"\n *\n * Only non-null FKs pointing at non-existent targets trigger the\n * mode behavior.\n */\nfunction attachJoin(\n  left: unknown,\n  leg: JoinLeg,\n  right: unknown,\n  rawId: unknown,\n): unknown {\n  if (left === null || typeof left !== 'object') {\n    // Pathological input — return as-is. Shouldn't happen in\n    // practice because QuerySource yields objects, but defensive\n    // because plan execution is untyped at this layer.\n    return left\n  }\n  const merged: Record<string, unknown> = { ...(left as Record<string, unknown>) }\n\n  // \"No ref at all\" — null/undefined FK value, or a non-string/non-\n  // number FK that coerceRefKey treated as no-ref. Never throws\n  // regardless of mode; matches the write-time policy that nullish\n  // refs are allowed.\n  const refKey = coerceRefKey(rawId)\n  if (right === undefined) {\n    if (refKey !== null && leg.mode === 'strict') {\n      throw new DanglingReferenceError({\n        field: leg.field,\n        target: leg.target,\n        refId: refKey,\n        message:\n          `.join() strict dangling: record references \"${leg.target}:${refKey}\" ` +\n          `via field \"${leg.field}\", but no such record exists. Use ref() mode 'warn' ` +\n          `or 'cascade' if dangling refs are acceptable, or run ` +\n          `vault.checkIntegrity() to find and fix the orphans.`,\n      })\n    }\n    if (refKey !== null && leg.mode === 'warn') {\n      warnOnceDangling(leg.field, leg.target, refKey)\n    }\n    // For 'cascade' and null refs we attach null silently. Cascade\n    // is a delete-time mode; any dangling refs visible at read time\n    // are either mid-flight or pre-existing orphans, not a DSL error.\n    merged[leg.as] = null\n  } else {\n    merged[leg.as] = right\n  }\n  return merged\n}\n\n/**\n * Test-only: reset the join warning deduplication state between\n * tests. Production code never calls this — the dedup state is\n * intentionally process-scoped so a noisy query doesn't spam the\n * console once per component render.\n */\nexport function resetJoinWarnings(): void {\n  warnedDanglingKeys.clear()\n  warnedCeilingKeys.clear()\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-RDXW3OBQ.js

@@ -0,0 +1,21 @@
+import {
+  SealedRecordNotEnabledError
+} from "./chunk-W2OG6JOL.js";
+
+// src/with-audit/sealed-record/strategy.ts
+var NO_SEALED_RECORD = {
+  async sealRecordToHost() {
+    throw new SealedRecordNotEnabledError();
+  },
+  async revokeSealedRecord() {
+    throw new SealedRecordNotEnabledError();
+  },
+  async rotateRecordCek() {
+    throw new SealedRecordNotEnabledError();
+  }
+};
+
+export {
+  NO_SEALED_RECORD
+};
+//# sourceMappingURL=chunk-RDXW3OBQ.js.map