@noy-db/hub 0.10.0-pre.0 → 0.10.0-pre.2

package/dist/chunk-RKBCUP5D.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/with-shape/persisted-schemas/field-ids.ts","../src/with-shape/manifest/writer.ts","../src/with-shape/manifest/sync.ts","../src/with-shape/persisted-schemas/register.ts"],"sourcesContent":["/**\n * Stable field-identifier minting (#946).\n *\n * A field's `id` is opaque and permanent — minted once, from randomness\n * only, with no timestamp and no name-derivation. A name-derived id would\n * change when the field is renamed, defeating the whole point (identity\n * must survive a rename). See `PersistedSchemaEnvelope.fieldIds`.\n *\n * @module\n */\n\nconst BASE32URL_ALPHABET = 'abcdefghijklmnopqrstuvwxyz234567'\n\n/** Unpadded RFC 4648 §7 base32url encoding of an arbitrary byte string. */\nfunction encodeBase32Url(bytes: Uint8Array): string {\n  let bits = 0\n  let value = 0\n  let out = ''\n  for (const byte of bytes) {\n    value = (value << 8) | byte\n    bits += 8\n    while (bits >= 5) {\n      out += BASE32URL_ALPHABET[(value >>> (bits - 5)) & 31]\n      bits -= 5\n    }\n  }\n  if (bits > 0) {\n    out += BASE32URL_ALPHABET[(value << (5 - bits)) & 31]\n  }\n  return out\n}\n\n/**\n * Mint a fresh opaque field id: 12 random bytes (96 bits) from\n * `crypto.getRandomValues`, encoded as a 20-character base32url token.\n * Not exported — Task 2/3 (#946) may need to export this later; keep it\n * module-internal until an external consumer exists.\n */\nfunction mintFieldId(): string {\n  const bytes = new Uint8Array(12)\n  crypto.getRandomValues(bytes)\n  return encodeBase32Url(bytes)\n}\n\n/** Top-level property names of a Draft 2020-12 object JSON Schema, or `[]` when not an object schema. */\nfunction topLevelFieldNames(jsonSchema: object | null): readonly string[] {\n  if (jsonSchema === null) return []\n  const props = (jsonSchema as { properties?: unknown }).properties\n  if (props === null || typeof props !== 'object') return []\n  return Object.keys(props as Record<string, unknown>)\n}\n\n/**\n * Resolve the `fieldIds` map for a freshly-derived schema against the\n * previously-stored envelope's map (if any). Existing ids are preserved by\n * name — a field keeps its id across re-derivation as long as its name is\n * unchanged; a genuinely new field name mints a fresh id. Returns\n * `undefined` when the fresh schema has no derivable top-level field set\n * (e.g. a stub envelope, or a non-object root schema).\n *\n * `renamed` (#946 Task 2) — unambiguous rename pairs from\n * `computeSchemaDelta`'s `SchemaDelta.renamed`. When the fresh name is a\n * rename target (`to`), the id is looked up under its OLD name (`from`)\n * instead of the fresh name itself — the whole point of a stable field id\n * is that it survives exactly this case; without it, a rename would mint a\n * fresh id for the new name and silently drop the old one.\n */\nexport function resolveFieldIds(\n  freshJsonSchema: object | null,\n  priorFieldIds: Record<string, string> | undefined,\n  renamed?: readonly { readonly from: string; readonly to: string }[],\n): Record<string, string> | undefined {\n  const names = topLevelFieldNames(freshJsonSchema)\n  if (names.length === 0) return undefined\n  const priorNameFor = new Map<string, string>()\n  if (renamed) for (const { from, to } of renamed) priorNameFor.set(to, from)\n  const out: Record<string, string> = {}\n  for (const name of names) {\n    const priorName = priorNameFor.get(name) ?? name\n    out[name] = priorFieldIds?.[priorName] ?? mintFieldId()\n  }\n  return out\n}\n","/**\n * Strict-CAS schema-manifest writer (#941, AC #1).\n *\n * Every other reserved-collection writer in the hub (`persisted-schemas`'s\n * `savePersistedSchema` callers, the classified/satellite marker writers)\n * retries on a CAS conflict: re-read, re-apply, try again. The schema\n * manifest deliberately does NOT — two concurrent *direct* edits to the\n * manifest must be refused and surfaced, never silently merged or\n * retry-resolved, because a manifest write encodes a specific point-in-time\n * claim about the pod's schema generation/content-hash set. A caller that\n * lost the race must re-derive against the fresh state and decide what to\n * do, not have its stale write quietly re-applied on top of someone else's.\n *\n * Ledger audit: this writer does not have a `LedgerStore` handle at this\n * seam (mirroring `persisted-schemas`, whose `_schemas/<collection>` writes\n * are likewise not ledger-audited today). Wiring `LedgerStore.append({ op:\n * 'migration', ... })` around a manifest write belongs at the call site\n * where a ledger handle is already in scope (the open/write integration —\n * #941 Task 3/4), not here.\n *\n * @module\n */\n\nimport { isConflictError, ManifestConflictError } from '../../kernel/errors.js'\nimport { saveSchemaManifest, type GetManifestDEK } from './storage.js'\nimport type { NoydbStore } from '../../kernel/types.js'\nimport type { SchemaManifest } from './types.js'\n\n/**\n * Write the schema manifest as a strict CAS: `expectedVersion` must match\n * the stored envelope's `_v` (0 when no manifest exists yet). On a\n * conflict, throws {@link ManifestConflictError} — this function never\n * retries.\n */\nexport async function writeSchemaManifest(\n  store: NoydbStore,\n  vault: string,\n  manifest: SchemaManifest,\n  expectedVersion: number,\n  getDEK: GetManifestDEK,\n): Promise<void> {\n  try {\n    await saveSchemaManifest(store, vault, manifest, expectedVersion, getDEK)\n  } catch (err) {\n    if (isConflictError(err)) {\n      throw new ManifestConflictError(err.version, expectedVersion)\n    }\n    throw err\n  }\n}\n","/**\n * Keep the persisted `_manifest/schema` record in sync with the\n * per-collection `_schemas/<collection>` source of truth (#941 Task 3).\n *\n * Called from `persisted-schemas/register.ts`'s `persistSchemaIfNeeded`\n * right after a `_schemas/<collection>` write succeeds.\n *\n * ## Reconciling strict-CAS-refuse with the derived nature of the manifest\n *\n * `writer.ts`'s `writeSchemaManifest` is deliberately strict-CAS: a\n * concurrent *direct* edit to the manifest is refused, never retried (AC\n * #1). But this call site is not a direct edit — it is a re-derivation\n * from the source of truth, triggered as a side effect of a `_schemas`\n * write that has ALREADY succeeded. When N collections are declared\n * together (one `openVault()` call registering several `persistJsonSchema:\n * true` collections), their `persistSchemaIfNeeded` calls run CONCURRENTLY\n * — each one's own `_schemas/<collection>` write lands independently, and\n * each then calls this function. A single derive-then-write with no\n * feedback loop is NOT enough here: a call whose `deriveSchemaManifest`\n * snapshot ran before a sibling's `_schemas` write landed would persist a\n * manifest that's missing that sibling forever (nothing re-triggers it) —\n * this was a REAL bug (not a test-isolation artifact — reproduced with 0\n * shared state, purely from concurrent `_schemas` writes racing the derive\n * snapshot; see #941 flake fix commit). `syncSchemaManifest` therefore\n * loops (bounded by {@link MAX_SYNC_ATTEMPTS}):\n *\n *   1. Derive fresh, compare to what's persisted. Already converged → done.\n *   2. Write via strict-CAS. `ManifestConflictError` (another writer moved\n *      the manifest first) → loop: re-derive against the NEW state and\n *      retry, exactly like a normal optimistic-CAS retry.\n *   3. On a successful write, derive ONE more time. If a sibling's\n *      `_schemas` write landed while we were deriving/writing, the state\n *      has already moved past what we just wrote — loop again to catch it\n *      up. If the re-derive matches what we wrote, we're the last writer\n *      and the manifest is provably converged: return.\n *\n * This guarantees that whichever collection's `_schemas` write is the LAST\n * to land (in real wall-clock order — there is always exactly one, even\n * though no single caller knows which) ends up running a sync whose own\n * derive sees every sibling's write already committed, and whose\n * recheck-after-write confirms nothing moved further — so it converges the\n * manifest deterministically, regardless of interleaving. If attempts are\n * exhausted under pathological contention, the loop gives up — with a\n * `console.warn` (see cap-exhaustion note below), not silently — leaving\n * the last successful write in place; the manifest is a derivable cache\n * (not a correctness invariant), so a next schema write or `open()`'s\n * re-derive still converges it, matching how `persistSchemaIfNeeded`\n * already treats its own write failures.\n * Any error OTHER than `ManifestConflictError` (store failure, DEK\n * resolution failure, etc.) is NOT swallowed — it propagates to the\n * caller immediately, matching how `persistSchemaIfNeeded` already treats\n * its own write failures as a visible (not silently discarded) fingerprint\n * failure.\n *\n * ## CRITICAL fix (#941 review): a scoped principal must never write a\n * partial manifest\n *\n * `deriveSchemaManifest` returns `undecodableCollections` for any\n * `_schemas/<collection>` entry this principal's `lookupDEK` couldn't\n * resolve — e.g. a member `grant()`-scoped to one collection can decrypt\n * `_manifest` itself (system-prefixed DEKs propagate to every role) but\n * NOT a sibling data collection's `_schemas/<sibling>` entry. Before this\n * fix, `deriveSchemaManifest` silently treated \"can't decrypt\" the same as\n * \"no derivable content\" and omitted the sibling — so a scoped member's\n * OWN schema declare would derive a manifest missing every collection they\n * can't see, load the real (complete) persisted manifest as a valid CAS\n * token, observe a hash mismatch, and OVERWRITE it — permanently dropping\n * the siblings, silently, ledger-audited as a legitimate migration. The\n * converging recheck loop above made this WORSE, not better: re-deriving\n * from the same restricted view just re-confirms the same partial result\n * and declares it \"stable.\"\n *\n * Fix: if `undecodableCollections` is non-empty, `syncSchemaManifest`\n * `SKIP`s entirely — no read-compare, no write, no audit, no loop. It does\n * NOT try to merge-preserve the undecodable entries from what's currently\n * persisted: an `aggregateHash` computed over entries this principal can't\n * verify would be a hash asserting something it never actually checked,\n * which is worse than not writing at all. This is safe because:\n *\n *   - The source of truth, `_schemas/<their-collection>`, was ALREADY\n *     updated by their declare — nothing about their own change is lost.\n *   - The pod-wide `_manifest` cache simply isn't rewritten by a principal\n *     who'd corrupt it by omission — it stays whatever a full-visibility\n *     principal (owner/admin/custodian) last wrote.\n *   - `open()` re-derives from `_schemas` directly (not from the cached\n *     manifest) for whoever opens it, so a stale cache is never load-bearing.\n *   - The NEXT full-visibility principal's declare (or any subsequent sync\n *     by someone with complete access) naturally refreshes the cache,\n *     including the scoped member's own just-landed change.\n *\n * ## Ledger audit (AC #5)\n *\n * Schema-generation transitions are not ledger-audited anywhere else today\n * (neither the `_schemas/<collection>` write in `register.ts` nor the fence\n * bump in `schema-update/fence-controller.ts#runCutover`). This is the\n * first ledger-audited signal for a schema change: every manifest write\n * that actually happens (i.e. every time the derived manifest differs from\n * what's stored) appends an `op: 'migration'` entry via the optional\n * `getLedgerOrNull` callback — `null`/absent when the history strategy\n * isn't opted in, matching every other optional-ledger call site\n * (`vault._getLedgerOrNull()?.append(...)`, see `liberate.ts`,\n * `with-audit/periods/vault-facade.ts`). No audit fires on the no-op path\n * (derived manifest unchanged), on a swallowed conflict (the winning\n * writer's own sync already audits its write), or on the scoped-principal\n * SKIP path above (nothing was written).\n *\n * @module\n */\n\nimport type { LedgerStore } from '../../with-commit/history/ledger/store.js'\nimport { envelopePayloadHash } from '../../with-commit/history/ledger/hash.js'\nimport type { NoydbStore } from '../../kernel/types.js'\nimport { ManifestConflictError } from '../../kernel/errors.js'\nimport { deriveSchemaManifest, type LookupDEK } from './derive.js'\nimport { loadSchemaManifestEntry, type GetManifestDEK } from './storage.js'\nimport { writeSchemaManifest } from './writer.js'\nimport { MANIFEST_COLLECTION } from './reserved-collections.js'\nimport { MANIFEST_SCHEMA_RECORD_ID, type SchemaManifest } from './types.js'\n\nexport interface ManifestSyncDeps {\n  /** Resolver for `_manifest`'s OWN DEK — mints if absent (this principal's declare is about to write it). */\n  readonly getDEK: GetManifestDEK\n  /**\n   * NON-MINTING lookup for every OTHER (sibling data) collection's DEK,\n   * used by `deriveSchemaManifest` to build the index — see `derive.ts`'s\n   * `LookupDEK` doc for why minting here would be actively harmful.\n   */\n  readonly lookupDEK: LookupDEK\n  /** Optional ledger handle — absent when the history strategy isn't opted in (no-op audit). */\n  readonly getLedgerOrNull?: () => LedgerStore | null\n}\n\n/**\n * Bound on the derive→write→recheck loop (see module doc). Headroom above\n * what any realistic `openVault()` batch (a handful of collections) needs —\n * a 40-way concurrent-declare stress repro converged within single digits.\n */\nconst MAX_SYNC_ATTEMPTS = 16\n\n/**\n * Re-derive the schema manifest and write it if it changed, looping until\n * the write is provably stable against concurrent sibling `_schemas`\n * writes (see module doc). SKIPS entirely (no write, no audit) when this\n * principal's view is incomplete (`undecodableCollections` non-empty) —\n * see the module doc's CRITICAL fix section. Swallows a\n * {@link ManifestConflictError} by retrying against the fresher state; any\n * other error propagates. Ledger-audits (`op: 'migration'`) once per\n * successful write.\n */\nexport async function syncSchemaManifest(\n  store: NoydbStore,\n  vault: string,\n  deps: ManifestSyncDeps,\n): Promise<void> {\n  for (let attempt = 0; attempt < MAX_SYNC_ATTEMPTS; attempt++) {\n    const { manifest: derived, undecodableCollections } = await deriveSchemaManifest(store, vault, deps.lookupDEK)\n    if (undecodableCollections.length > 0) {\n      // Scoped principal — see module doc's CRITICAL fix. Never write a\n      // manifest we know is missing collections we couldn't decrypt.\n      return\n    }\n\n    const existing = await loadSchemaManifestEntry(store, vault, deps.getDEK)\n\n    if (\n      existing &&\n      existing.manifest.generation === derived.generation &&\n      existing.manifest.aggregateHash === derived.aggregateHash\n    ) {\n      return // already converged — no write, no audit\n    }\n\n    const expectedVersion = existing?.version ?? 0\n    try {\n      await writeSchemaManifest(store, vault, derived, expectedVersion, deps.getDEK)\n    } catch (err) {\n      if (err instanceof ManifestConflictError) continue // another writer moved it first — re-derive + retry\n      throw err\n    }\n\n    await auditManifestWrite(store, vault, deps, derived, expectedVersion)\n\n    // A sibling's `_schemas` write can land while WE were deriving/writing\n    // (#941 flake fix — see module doc). Re-derive once more: if the truth\n    // has already moved past what we just wrote, loop again to catch it up\n    // instead of leaving a permanently-partial manifest. (A principal with\n    // full visibility at the top of this iteration cannot lose that\n    // visibility mid-call — the keyring doesn't change during one sync —\n    // so this recheck is never itself subject to the undecodable-skip; the\n    // `for` loop's own guard covers it defensively regardless.)\n    const recheck = await deriveSchemaManifest(store, vault, deps.lookupDEK)\n    if (recheck.undecodableCollections.length > 0) return // defensive — see comment above\n    if (recheck.manifest.generation === derived.generation && recheck.manifest.aggregateHash === derived.aggregateHash) {\n      return // stable — we were the last writer\n    }\n  }\n  // Attempts exhausted under pathological contention — see module doc:\n  // the manifest is a derivable cache, not a correctness invariant, so a\n  // later schema write or open()'s re-derive still converges it. Warn\n  // rather than fail silently — a silent give-up on a completeness\n  // invariant is exactly what hid the original concurrent-declare race.\n  console.warn(\n    `[noy-db] schema-manifest sync did not converge after ${MAX_SYNC_ATTEMPTS} attempts; ` +\n      'the persisted manifest may be stale until the next schema write or open()\\'s re-derive.',\n  )\n}\n\nasync function auditManifestWrite(\n  store: NoydbStore,\n  vault: string,\n  deps: ManifestSyncDeps,\n  derived: SchemaManifest,\n  expectedVersion: number,\n): Promise<void> {\n  const ledger = deps.getLedgerOrNull?.()\n  if (!ledger) return\n  // `_manifest/schema` has a real, individually-addressable envelope (unlike\n  // a `lifecycle` entry's empty collection/id) — `verifyBackupIntegrity`'s\n  // data cross-check (`with-pod/backup.ts`) treats any non-amendment,\n  // non-lifecycle entry's `collection`/`id` as \"the latest write to this\n  // record\" and recomputes+compares its ciphertext hash, so `payloadHash`\n  // must be the real `envelopePayloadHash` of the just-written envelope\n  // (ciphertext domain), NOT `derived.aggregateHash` (plaintext domain) —\n  // using the wrong domain here trips a false-positive tamper failure on\n  // restore.\n  const envelope = await store.get(vault, MANIFEST_COLLECTION, MANIFEST_SCHEMA_RECORD_ID)\n  await ledger.append({\n    op: 'migration',\n    collection: MANIFEST_COLLECTION,\n    id: MANIFEST_SCHEMA_RECORD_ID,\n    version: expectedVersion + 1,\n    actor: '',\n    payloadHash: await envelopePayloadHash(envelope),\n    reason: `schema-manifest-sync:generation=${derived.generation}`,\n  })\n}\n","/**\n * Orchestrate the derive → hash → skip-or-write cycle for a collection's\n * persisted JSON Schema. Called by the Vault at collection-registration\n * time when the developer opts in via `collection({ persistJsonSchema:\n * true })`.\n *\n * Skip semantics:\n *\n *   - Zod validators: skip when the new hash equals the stored hash.\n *   - Non-Zod (stub envelopes have hash=null): skip when the stored\n *     envelope's `kind` matches the freshly-detected kind (since there's\n *     no body to compare yet — a kind change is the only signal).\n *\n * @module\n */\n\nimport { derivePersistedSchema } from './derive.js'\nimport { loadPersistedSchemaEntry, savePersistedSchema } from './storage.js'\nimport { resolveFieldIds } from './field-ids.js'\nimport { computeSchemaDelta } from '../schema-update/delta.js'\nimport { evaluateStrategies } from '../schema-update/dispatch.js'\nimport { loadFence, saveFence } from '../schema-update/fence.js'\nimport { isConflictError } from '../../kernel/errors.js'\nimport { syncSchemaManifest, type ManifestSyncDeps } from '../manifest/sync.js'\nimport type { SchemaUpdateStrategy, UpdateDecision, SchemaDelta } from '../schema-update/types.js'\nimport type { NoydbStore, ClassifiedMarker } from '../../kernel/types.js'\nimport type { PersistedSchemaEnvelope } from './types.js'\nimport type { PairingMarker } from '../satellites/types.js'\nimport type { EnclaveKey } from '../../capsule/index.js'\n\n/**\n * Max optimistic-CAS retries for the shared `_schemas/<collection>` record\n * (#583). Only two writers ever contend (the JSON-Schema writer and the\n * classified-marker writer), so one retry suffices; the headroom covers a\n * pathological re-order. Exhausting it rethrows the {@link ConflictError}\n * rather than silently losing a write.\n */\nconst MAX_SCHEMA_CAS_RETRIES = 5\n\nexport interface PersistSchemaResult {\n  /** True when a fresh envelope was written to storage. */\n  readonly written: boolean\n  /** True when an existing envelope matched and the write was skipped. */\n  readonly skipped: boolean\n  /** The envelope that was either written or matched. */\n  readonly envelope: PersistedSchemaEnvelope\n  /** The update-strategy decision, present when strategies ran. */\n  readonly decision?: UpdateDecision\n}\n\nexport async function persistSchemaIfNeeded(opts: {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly collectionName: string\n  readonly validator: unknown\n  readonly dek: EnclaveKey\n  readonly strategies?: readonly SchemaUpdateStrategy[]\n  /** #941 Task 3: re-derive + sync the `_manifest/schema` INDEX after a write. Omitted → no sync (e.g. tests that don't care). */\n  readonly manifestSync?: ManifestSyncDeps\n}): Promise<PersistSchemaResult> {\n  const fresh = await derivePersistedSchema(opts.validator)\n\n  // The `_schemas/<collection>` record is shared with the classified-marker\n  // writer, so a plain load→save loses whichever writer put first (#583). Read\n  // the version at load time and CAS on it; on conflict re-read (picking up the\n  // other writer's field), re-evaluate, and retry.\n  for (let attempt = 0; ; attempt++) {\n    const { version, payload: stored } = await loadPersistedSchemaEntry(\n      opts.store, opts.vault, opts.collectionName, opts.dek,\n    )\n\n    if (stored && isEquivalent(stored, fresh)) {\n      return { written: false, skipped: true, envelope: stored, decision: { action: 'allow' } }\n    }\n\n    // Changed (or first registration). Compute the delta whenever we have a\n    // comparable JSON-Schema baseline — independent of whether strategies\n    // were registered (#946: the rename pairing it carries feeds the\n    // fieldIds id-carry below even on a bare re-declare with no\n    // `schemaUpdate` strategies configured). Strategies only run when\n    // registered.\n    let decision: UpdateDecision = { action: 'allow' }\n    const strategies = opts.strategies ?? []\n    let delta: SchemaDelta | undefined\n    if (\n      stored &&\n      stored.kind === fresh.kind &&\n      isPlainObject(stored.jsonSchema) &&\n      isPlainObject(fresh.jsonSchema)\n    ) {\n      delta = computeSchemaDelta(stored.jsonSchema, fresh.jsonSchema, opts.collectionName)\n      if (strategies.length > 0) {\n        decision = await evaluateStrategies(delta, strategies, { collection: opts.collectionName })\n      }\n    }\n\n    if (decision.action !== 'allow') {\n      // reject (or cutover): do NOT overwrite the baseline — the\n      // old schema stays the source of truth until the change is resolved.\n      return { written: false, skipped: false, envelope: stored ?? fresh, decision }\n    }\n\n    // Preserve a previously-persisted classified marker (C-A / R10) and\n    // satellite pairing marker (R-S9) — the schema derivation knows nothing\n    // about them, so a naive overwrite here would drop the config-drift\n    // guards' cross-session signals.\n    let toSave: PersistedSchemaEnvelope = fresh\n    if (stored?.classified !== undefined) toSave = { ...toSave, classified: stored.classified }\n    if (stored?.satellite !== undefined) toSave = { ...toSave, satellite: stored.satellite }\n\n    // #946: mint/preserve stable per-field ids (by name, carrying a\n    // detected rename's id from its old name — see `delta.renamed`) and\n    // stamp the vault-wide schema-fence generation this write happened at —\n    // binds \"generation N\" to this envelope's content hash\n    // (schemaFenceState() + loadPersistedSchema agree).\n    const fieldIds = resolveFieldIds(fresh.jsonSchema, stored?.fieldIds, delta?.renamed)\n    if (fieldIds !== undefined) toSave = { ...toSave, fieldIds }\n    const fence = await loadFence(opts.store, opts.vault)\n    toSave = { ...toSave, generation: fence.currentSchemaVersion }\n\n    try {\n      await savePersistedSchema(opts.store, opts.vault, opts.collectionName, opts.dek, toSave, version)\n      if (toSave.hash !== null) {\n        // This is the FIRST non-barrier writer to `_meta/schema-fence` —\n        // previously only SchemaFenceController.#setState wrote it, and only\n        // sequentially, under the drain barrier. There is no CAS on the fence\n        // doc (out of scope to add here), so re-read it immediately before\n        // writing rather than reusing the `fence` snapshot captured above\n        // (before the potentially-slow `savePersistedSchema` call): spreading\n        // a stale snapshot here would roll back `currentSchemaVersion`/\n        // `fenceState` if a concurrent cutover (on a different collection)\n        // advanced the fence in between — corrupting the vault-wide gate the\n        // whole barrier + MigrationRequiredError check depends on. Re-reading\n        // narrows (does not eliminate) that window to just this one overlay.\n        const freshFence = await loadFence(opts.store, opts.vault)\n        await saveFence(opts.store, opts.vault, { ...freshFence, schemaHash: toSave.hash })\n      }\n      // #941 Task 3: keep the `_manifest/schema` INDEX in sync with the\n      // `_schemas/<collection>` write that just landed. Opt-in via\n      // `opts.manifestSync` (threaded from vault.ts, which is the only\n      // caller with a general-purpose `getDEK` resolver + ledger handle).\n      if (opts.manifestSync) {\n        await syncSchemaManifest(opts.store, opts.vault, opts.manifestSync)\n      }\n      return { written: true, skipped: false, envelope: toSave, decision }\n    } catch (err) {\n      if (isConflictError(err) && attempt < MAX_SCHEMA_CAS_RETRIES) continue\n      throw err\n    }\n  }\n}\n\n/**\n * Persist (or refresh) the C-A / R10 classified marker into the collection's\n * `_schemas/<collection>` record, preserving any existing derived JSON-Schema\n * body. Idempotent — a no-op when an equivalent marker is already stored.\n * Independent of `persistJsonSchema`: called on the first classified write so a\n * later naive handle can detect the drift cross-session.\n */\nexport async function persistClassifiedMarker(opts: {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly collectionName: string\n  readonly dek: EnclaveKey\n  readonly marker: ClassifiedMarker\n}): Promise<void> {\n  // Shares the `_schemas/<collection>` record with the JSON-Schema writer;\n  // CAS on the loaded version so a concurrent schema (re)registration can't\n  // silently drop the marker (and vice-versa) — see #583.\n  for (let attempt = 0; ; attempt++) {\n    const { version, payload: stored } = await loadPersistedSchemaEntry(\n      opts.store, opts.vault, opts.collectionName, opts.dek,\n    )\n    if (stored?.classified !== undefined && markersEqual(stored.classified, opts.marker)) return\n    const payload: PersistedSchemaEnvelope =\n      stored !== undefined\n        ? { ...stored, classified: opts.marker }\n        : {\n            _noydb_schema: 1,\n            kind: 'Unknown',\n            jsonSchema: null,\n            hash: null,\n            derivedAt: new Date().toISOString(),\n            classified: opts.marker,\n          }\n    try {\n      await savePersistedSchema(opts.store, opts.vault, opts.collectionName, opts.dek, payload, version)\n      return\n    } catch (err) {\n      if (isConflictError(err) && attempt < MAX_SCHEMA_CAS_RETRIES) continue\n      throw err\n    }\n  }\n}\n\n/**\n * Persist (or refresh) the R-S9 satellite pairing marker into the collection's\n * `_schemas/<collection>` record, preserving any existing derived JSON-Schema\n * body. Idempotent — a no-op when an equivalent marker is already stored.\n * Independent of `persistJsonSchema`: called on satellite declaration so a\n * later divergent re-declaration can be detected cross-session.\n */\nexport async function persistSatelliteMarker(opts: {\n  readonly store: NoydbStore\n  readonly vault: string\n  readonly collectionName: string\n  readonly dek: EnclaveKey\n  readonly marker: PairingMarker\n}): Promise<void> {\n  // Shares the `_schemas/<collection>` record with the JSON-Schema writer;\n  // CAS on the loaded version so a concurrent schema (re)registration can't\n  // silently drop the marker (and vice-versa) — see #583.\n  for (let attempt = 0; ; attempt++) {\n    const { version, payload: stored } = await loadPersistedSchemaEntry(\n      opts.store, opts.vault, opts.collectionName, opts.dek,\n    )\n    if (stored?.satellite !== undefined && satelliteMarkersEqual(stored.satellite, opts.marker)) return\n    const payload: PersistedSchemaEnvelope =\n      stored !== undefined\n        ? { ...stored, satellite: opts.marker }\n        : {\n            _noydb_schema: 1,\n            kind: 'Unknown',\n            jsonSchema: null,\n            hash: null,\n            derivedAt: new Date().toISOString(),\n            satellite: opts.marker,\n          }\n    try {\n      await savePersistedSchema(opts.store, opts.vault, opts.collectionName, opts.dek, payload, version)\n      return\n    } catch (err) {\n      if (isConflictError(err) && attempt < MAX_SCHEMA_CAS_RETRIES) continue\n      throw err\n    }\n  }\n}\n\n// #597: both equality checks below deliberately do NOT compare `epoch`. A\n// live collection re-opening itself computes a fresh epoch candidate on\n// every declare (marker.ts / config-drift.ts) that must still be treated as\n// \"the same marker\" so the no-op fast path fires and the already-persisted\n// epoch is left untouched — that's what makes epoch stable across re-opens.\n// Comparing epoch here would break that fast path today, with no\n// corresponding benefit: there is no delete-collection API yet, so a\n// mismatched epoch can't (yet) mean \"this name was reused for a genuinely\n// new collection.\" Wiring an epoch-mismatch REJECTION is a deferred\n// follow-up for whenever collection deletion ships.\n\nfunction satelliteMarkersEqual(a: PairingMarker, b: PairingMarker): boolean {\n  return a.base === b.base && a.fieldsHash === b.fieldsHash && (a.joined ?? null) === (b.joined ?? null)\n}\n\nfunction markersEqual(a: ClassifiedMarker, b: ClassifiedMarker): boolean {\n  return sameSet(a.digestOnly, b.digestOnly) && sameSet(a.equatable, b.equatable)\n}\n\nfunction sameSet(a: readonly string[], b: readonly string[]): boolean {\n  if (a.length !== b.length) return false\n  const s = new Set(a)\n  return b.every((x) => s.has(x))\n}\n\nfunction isPlainObject(v: unknown): v is object {\n  return typeof v === 'object' && v !== null && !Array.isArray(v)\n}\n\nfunction isEquivalent(a: PersistedSchemaEnvelope, b: PersistedSchemaEnvelope): boolean {\n  if (a.kind !== b.kind) return false\n  // Zod path: real hashes — compare directly.\n  if (a.hash && b.hash) return a.hash === b.hash\n  // Stub path: both have hash=null. Kind equality is the only signal we have.\n  if (a.hash === null && b.hash === null) return true\n  // Mixed (one has a hash, the other doesn't) — treat as changed.\n  return false\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-T5EXREMW.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/with-shape/manifest/types.ts","../src/with-shape/manifest/storage.ts","../src/with-shape/manifest/derive.ts"],"sourcesContent":["/**\n * The pod-wide **schema manifest** record type (#941).\n *\n * This is an INDEX, not a full-inline manifest: `SchemaManifest.collections`\n * carries per-collection *metadata* (generation / content hash / field ids),\n * never the JSON Schema body itself. The JSON Schema stays the source of\n * truth at `_schemas/<collection>`, encrypted under that collection's own\n * DEK (see `with-shape/persisted-schemas`). Inlining full schemas into one\n * pod-wide manifest record would either leak every collection's schema to a\n * principal scoped to a single collection, or force the manifest itself\n * onto a collection-DEK it has no business holding — the index preserves\n * per-collection DEK isolation while still giving a single place to answer\n * \"what schema generation is this pod at, and does collection X's stored\n * schema match its declared content hash.\"\n *\n * `aggregateHash` binds the whole per-collection index's content: it is\n * `sha256Hex(canonicalJson(collections))`, so any change to any collection's\n * entry (a new generation, a changed hash, added/renamed field ids) changes\n * `aggregateHash` too. Canonical JSON (sorted object keys, no whitespace)\n * makes the hash independent of the map's key insertion order.\n *\n * @module\n */\n\n/** Per-collection entry inside a {@link SchemaManifest}'s `collections` index. */\nexport interface SchemaManifestEntry {\n  /** The vault-wide schema-fence generation this collection's schema was last written at. */\n  readonly generation: number\n  /** SHA-256 (hex) of the collection's canonicalised JSON Schema (see `persisted-schemas/derive.ts`). */\n  readonly contentHash: string\n  /** Stable per-field ids (#946), keyed by the field's current name. Absent when the collection has none. */\n  readonly fieldIds?: Record<string, string>\n}\n\n/**\n * The pod-wide schema manifest — one record per pod, stored at\n * `_manifest/schema` (see `storage.ts`). An INDEX over the per-collection\n * `_schemas/<collection>` entries, not the schemas themselves.\n */\nexport interface SchemaManifest {\n  readonly v: 1\n  readonly kind: 'schema'\n  /** Pod-wide schema-fence generation (`FenceDoc.currentSchemaVersion`) as of this manifest's derivation. */\n  readonly generation: number\n  /** Per-collection index: collection name → its manifest entry. */\n  readonly collections: Record<string, SchemaManifestEntry>\n  /** `sha256Hex(canonicalJson(collections))` — the pod-wide content binding over the index. */\n  readonly aggregateHash: string\n}\n\n/** The record id the schema manifest is stored under inside `_manifest`. */\nexport const MANIFEST_SCHEMA_RECORD_ID = 'schema' as const\n","/**\n * Read / write the pod-wide `_manifest/schema` envelope.\n *\n * Mirrors `with-shape/persisted-schemas/storage.ts`'s shape: the same\n * standard noy-db record envelope, AES-GCM encrypted with a collection DEK\n * (here, the `_manifest` collection's own DEK — the manifest INDEX\n * discloses collection names + hashes + generations + field ids, metadata\n * rather than schema bodies, so it gets the same encryption grain as\n * `_schemas` itself).\n *\n * Storage layout:\n *\n *   <vault>/_manifest/schema   →   EncryptedEnvelope\n *\n * Unlike `persisted-schemas/storage.ts` (which takes an already-resolved\n * `EnclaveKey`), these functions take a `getDEK` resolver and call\n * `getDEK(MANIFEST_COLLECTION)` themselves — there is exactly one manifest\n * record per pod, so there is no per-collection DEK the caller needs to\n * pick; resolving it here keeps every manifest call-site symmetric.\n *\n * @module\n */\n\nimport { buildSealedRecordEnvelope, openEnvelopeJson, writeEnvelopeBody, type EnclaveKey } from '../../capsule/index.js'\nimport { canonicalJson, sha256Hex } from '../../with-commit/history/ledger/index.js'\nimport type { NoydbStore } from '../../kernel/types.js'\nimport { MANIFEST_COLLECTION } from './reserved-collections.js'\nimport { MANIFEST_SCHEMA_RECORD_ID, type SchemaManifest, type SchemaManifestEntry } from './types.js'\n\n/** A resolver for a collection's DEK — the same shape as `Vault`'s internal `getDEK`. */\nexport type GetManifestDEK = (collectionName: string) => Promise<EnclaveKey>\n\n/**\n * A decrypted schema-manifest read paired with the wrapping envelope's `_v`\n * — the optimistic-concurrency token. Pass `version` back to\n * {@link saveSchemaManifest} (via `writeSchemaManifest`'s `expectedVersion`)\n * to make the write a strict CAS.\n */\nexport interface LoadedSchemaManifest {\n  /** Wrapping envelope `_v`. */\n  readonly version: number\n  /** Decrypted schema manifest. */\n  readonly manifest: SchemaManifest\n}\n\n/**\n * Read the `_manifest/schema` envelope together with its wrapping `_v`.\n * Returns `undefined` when no manifest has ever been written, when the\n * envelope fails to decrypt (wrong DEK), or when it doesn't parse as a\n * `v: 1, kind: 'schema'` manifest.\n */\nexport async function loadSchemaManifestEntry(\n  store: NoydbStore,\n  vault: string,\n  getDEK: GetManifestDEK,\n): Promise<LoadedSchemaManifest | undefined> {\n  const envelope = await store.get(vault, MANIFEST_COLLECTION, MANIFEST_SCHEMA_RECORD_ID)\n  if (!envelope) return undefined\n  const dek = await getDEK(MANIFEST_COLLECTION)\n  try {\n    const plaintext = await openEnvelopeJson({ collection: MANIFEST_COLLECTION, id: MANIFEST_SCHEMA_RECORD_ID }, envelope, dek)\n    const parsed = JSON.parse(plaintext) as SchemaManifest\n    if (parsed.v !== 1 || parsed.kind !== 'schema') return undefined\n    return { version: envelope._v, manifest: parsed }\n  } catch {\n    return undefined\n  }\n}\n\n/**\n * Encrypt and persist the schema manifest as a strict CAS write:\n * `expectedVersion` must match the stored envelope's `_v` (0 when no\n * envelope exists yet) or `store.put` throws `ConflictError` — surfaced by\n * `writer.ts`'s `writeSchemaManifest` as `ManifestConflictError` rather than\n * retried.\n */\nexport async function saveSchemaManifest(\n  store: NoydbStore,\n  vault: string,\n  manifest: SchemaManifest,\n  expectedVersion: number,\n  getDEK: GetManifestDEK,\n): Promise<void> {\n  const dek = await getDEK(MANIFEST_COLLECTION)\n  const json = JSON.stringify(manifest)\n  const env = await buildSealedRecordEnvelope(\n    { collection: MANIFEST_COLLECTION, id: MANIFEST_SCHEMA_RECORD_ID, version: expectedVersion + 1 },\n    (identity) => writeEnvelopeBody(identity, json, dek),\n    {},\n  )\n  await store.put(vault, MANIFEST_COLLECTION, MANIFEST_SCHEMA_RECORD_ID, env, expectedVersion)\n}\n\n/**\n * `sha256Hex(canonicalJson(collections))` — the pod-wide content binding\n * over a schema manifest's per-collection index. Canonical JSON sorts\n * object keys at every depth, so the result is independent of the map's\n * key insertion order. Shared by the writer's tests and (#941 Task 3) the\n * derivation path, so the hash is computed identically everywhere.\n */\nexport async function computeAggregateHash(\n  collections: Record<string, SchemaManifestEntry>,\n): Promise<string> {\n  return sha256Hex(canonicalJson(collections))\n}\n","/**\n * Derive the pod-wide {@link SchemaManifest} from the per-collection\n * `_schemas/<collection>` records — the source of truth (#941 Task 3).\n *\n * The manifest is an INDEX, never a cache with independent state: every\n * field in a {@link SchemaManifestEntry} is a direct projection of the\n * matching `PersistedSchemaEnvelope` (`hash` → `contentHash`, `fieldIds` →\n * `fieldIds`, `generation` → `generation`, falling back to the live fence's\n * `currentSchemaVersion` for a legacy pre-#946 envelope that never got a\n * generation stamp). Re-running this function against the same stored state\n * always produces the same manifest — that's what makes round-trip identity\n * (AC #2: dump → restore → re-derive matches the original) hold for free,\n * with no special-cased restore logic.\n *\n * A collection whose `_schemas/<collection>` envelope decrypts successfully\n * but has no derivable content (`hash === null` — a stub envelope for a\n * non-Zod validator) is legitimately omitted from the index: there is no\n * content hash to bind.\n *\n * ## Scoped principals: \"cannot decrypt\" is NOT \"doesn't exist\"\n *\n * A `_schemas/<collection>` envelope is encrypted under **that data\n * collection's own DEK** — the same key its records use — NOT a shared\n * `_schemas`-wide key. In a team vault, a collection-scoped grantee (e.g.\n * `grant(..., { role: 'operator', permissions: { invoices: 'rw' } })`) holds\n * only the DEKs their `permissions` name, plus every system-prefixed (`_*`)\n * collection's DEK — `_manifest` included, by `grant()`'s \"propagate system\n * collections to every role\" rule (`keyring.ts`). So a member scoped to\n * `invoices` CAN decrypt `_manifest/schema` (the pod-wide index) but CANNOT\n * decrypt a sibling's `_schemas/customers` envelope — even though that\n * envelope is right there in `store.list(vault, SCHEMAS_COLLECTION)`.\n *\n * `lookupDEK` (the {@link LookupDEK} passed in) reflects this: it returns\n * `undefined` for a collection name whose DEK the caller does not hold —\n * deliberately NEVER minting a fresh one (see the module doc on\n * `LookupDEK` for why). This function distinguishes that case\n * (`undecodableCollections`) from \"the schema envelope legitimately has no\n * derivable content\" (`hash === null`) — the caller (`sync.ts`) MUST treat\n * an incomplete view differently: writing a manifest derived from a\n * partial view would silently drop every collection this principal can't\n * see. See `sync.ts`'s module doc for how the sync path handles this.\n *\n * @module\n */\n\nimport type { EnclaveKey } from '../../capsule/index.js'\nimport { loadFence } from '../schema-update/fence.js'\nimport { loadPersistedSchema, SCHEMAS_COLLECTION } from '../persisted-schemas/storage.js'\nimport { computeAggregateHash } from './storage.js'\nimport type { NoydbStore } from '../../kernel/types.js'\nimport type { SchemaManifest, SchemaManifestEntry } from './types.js'\n\n/**\n * A NON-MINTING DEK lookup: returns the collection's DEK if the caller\n * already holds it, `undefined` otherwise. Deliberately distinct from\n * `storage.ts`'s `GetManifestDEK` (which mints+persists a fresh DEK for an\n * absent collection — correct for a caller about to WRITE that collection,\n * e.g. `_manifest` itself). `deriveSchemaManifest` only ever READS sibling\n * collections it never created and has no business minting keys for — an\n * absent DEK here means \"not my collection to see,\" never \"new collection\n * that needs a key.\" Minting here would be worse than a no-op: it would\n * silently persist a garbage DEK into the caller's OWN `_keyring/<user>`\n * file (via `ensureCollectionDEK`'s `persistKeyring` side effect) that\n * still can't decrypt anything — see `sync.ts` / `with-pod/open.ts`'s\n * fix notes (#941 review).\n */\nexport type LookupDEK = (collectionName: string) => Promise<EnclaveKey | undefined>\n\nexport interface DeriveSchemaManifestResult {\n  /** The derived manifest — an index over every collection this principal could decrypt. */\n  readonly manifest: SchemaManifest\n  /**\n   * Names present in `_schemas` (per `store.list`) whose envelope this\n   * principal could NOT decrypt — either no DEK held for that collection,\n   * or the DEK held failed to decrypt/parse it (treated the same: the\n   * caller cannot verify what's there, so it cannot safely be omitted or\n   * asserted). Empty for a principal with full visibility (typically the\n   * owner/admin/custodian). Non-empty means `manifest.collections` is\n   * DEFINITELY INCOMPLETE relative to the pod's true collection set —\n   * see `sync.ts` for why that must gate whether the manifest gets written.\n   */\n  readonly undecodableCollections: readonly string[]\n}\n\n/**\n * Read the fence generation + every `_schemas/<collection>` envelope this\n * principal can decrypt, and project them into a fresh {@link SchemaManifest}.\n * `lookupDEK` is called once per collection found under `_schemas` (never\n * mints — see {@link LookupDEK}). Names whose DEK isn't held, or whose\n * envelope fails to decrypt/parse despite holding a DEK, are reported via\n * `undecodableCollections` rather than silently dropped from the result.\n */\nexport async function deriveSchemaManifest(\n  store: NoydbStore,\n  vault: string,\n  lookupDEK: LookupDEK,\n): Promise<DeriveSchemaManifestResult> {\n  const fence = await loadFence(store, vault)\n  const collectionNames = await store.list(vault, SCHEMAS_COLLECTION)\n\n  const collections: Record<string, SchemaManifestEntry> = {}\n  const undecodableCollections: string[] = []\n  for (const name of collectionNames) {\n    const dek = await lookupDEK(name)\n    if (dek === undefined) {\n      undecodableCollections.push(name) // present in _schemas, but not decodable by this principal\n      continue\n    }\n\n    const payload = await loadPersistedSchema(store, vault, name, dek)\n    if (!payload) {\n      // Held a DEK but still couldn't decrypt/parse — cannot distinguish\n      // \"wrong key after all\" from real corruption from here; treat as\n      // undecodable (never silently drop) rather than \"no content.\"\n      undecodableCollections.push(name)\n      continue\n    }\n    if (payload.hash === null) continue // legitimately no derivable content (stub envelope)\n\n    const entry: SchemaManifestEntry = {\n      generation: payload.generation ?? fence.currentSchemaVersion,\n      contentHash: payload.hash,\n    }\n    collections[name] = payload.fieldIds !== undefined ? { ...entry, fieldIds: payload.fieldIds } : entry\n  }\n\n  const aggregateHash = await computeAggregateHash(collections)\n  const manifest: SchemaManifest = { v: 1, kind: 'schema', generation: fence.currentSchemaVersion, collections, aggregateHash }\n  return { manifest, undecodableCollections }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAmDO,IAAM,4BAA4B;;;ACAzC,eAAsB,wBACpB,OACA,OACA,QAC2C;AAC3C,QAAM,WAAW,MAAM,MAAM,IAAI,OAAO,qBAAqB,yBAAyB;AACtF,MAAI,CAAC,SAAU,QAAO;AACtB,QAAM,MAAM,MAAM,OAAO,mBAAmB;AAC5C,MAAI;AACF,UAAM,YAAY,MAAM,iBAAiB,EAAE,YAAY,qBAAqB,IAAI,0BAA0B,GAAG,UAAU,GAAG;AAC1H,UAAM,SAAS,KAAK,MAAM,SAAS;AACnC,QAAI,OAAO,MAAM,KAAK,OAAO,SAAS,SAAU,QAAO;AACvD,WAAO,EAAE,SAAS,SAAS,IAAI,UAAU,OAAO;AAAA,EAClD,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AASA,eAAsB,mBACpB,OACA,OACA,UACA,iBACA,QACe;AACf,QAAM,MAAM,MAAM,OAAO,mBAAmB;AAC5C,QAAM,OAAO,KAAK,UAAU,QAAQ;AACpC,QAAM,MAAM,MAAM;AAAA,IAChB,EAAE,YAAY,qBAAqB,IAAI,2BAA2B,SAAS,kBAAkB,EAAE;AAAA,IAC/F,CAAC,aAAa,kBAAkB,UAAU,MAAM,GAAG;AAAA,IACnD,CAAC;AAAA,EACH;AACA,QAAM,MAAM,IAAI,OAAO,qBAAqB,2BAA2B,KAAK,eAAe;AAC7F;AASA,eAAsB,qBACpB,aACiB;AACjB,SAAO,UAAU,cAAc,WAAW,CAAC;AAC7C;;;ACZA,eAAsB,qBACpB,OACA,OACA,WACqC;AACrC,QAAM,QAAQ,MAAM,UAAU,OAAO,KAAK;AAC1C,QAAM,kBAAkB,MAAM,MAAM,KAAK,OAAO,kBAAkB;AAElE,QAAM,cAAmD,CAAC;AAC1D,QAAM,yBAAmC,CAAC;AAC1C,aAAW,QAAQ,iBAAiB;AAClC,UAAM,MAAM,MAAM,UAAU,IAAI;AAChC,QAAI,QAAQ,QAAW;AACrB,6BAAuB,KAAK,IAAI;AAChC;AAAA,IACF;AAEA,UAAM,UAAU,MAAM,oBAAoB,OAAO,OAAO,MAAM,GAAG;AACjE,QAAI,CAAC,SAAS;AAIZ,6BAAuB,KAAK,IAAI;AAChC;AAAA,IACF;AACA,QAAI,QAAQ,SAAS,KAAM;AAE3B,UAAM,QAA6B;AAAA,MACjC,YAAY,QAAQ,cAAc,MAAM;AAAA,MACxC,aAAa,QAAQ;AAAA,IACvB;AACA,gBAAY,IAAI,IAAI,QAAQ,aAAa,SAAY,EAAE,GAAG,OAAO,UAAU,QAAQ,SAAS,IAAI;AAAA,EAClG;AAEA,QAAM,gBAAgB,MAAM,qBAAqB,WAAW;AAC5D,QAAM,WAA2B,EAAE,GAAG,GAAG,MAAM,UAAU,YAAY,MAAM,sBAAsB,aAAa,cAAc;AAC5H,SAAO,EAAE,UAAU,uBAAuB;AAC5C;","names":[]}

package/dist/chunk-TBVDI3LY.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/kernel/query/relate/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 `'all'`.\n * The executor never reads it. See {@link JoinLeg.partitionScope} for the\n * two constraints (#1342) that decide how it may ever be populated — one of\n * them silently invalidates stored materialized views.\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 type { Clause } from '../predicate.js'\nimport type { ViaPipeline } from '../../via/pipeline.js'\nimport { readPath } from '../predicate.js'\nimport { matchDeclaredJoin, type JoinOnPlan } from './join-on.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/**\n * Which side of a join leg is preserved (#1289).\n *\n *   - `'left'`  — every left row survives, `null` under the alias when the\n *     FK resolves to nothing. This is what `.join()` has always done, and it\n *     is the default for a leg that names no direction.\n *   - `'right'` — every RIGHT record survives, including one nothing points\n *     at; a left row whose FK matches nothing is dropped.\n *   - `'full'`  — the union of the two.\n *\n * `'right'` and `'full'` are the only two that need the reverse index — see\n * {@link outerJoinFromRight}. A forward leg is driven by the left row's FK\n * and never has to ask \"did anything point at this\".\n */\nexport type JoinDirection = 'left' | 'right' | 'full'\n\n/** Default per-side row ceiling before `.join()` throws `JoinTooLargeError`. */\nexport const DEFAULT_JOIN_MAX_ROWS = 50_000\n\n/**\n * Default row ceiling for cross-join expansion. Matches JoinTooLargeError's ceiling.\n *\n * ⭐ #1458 — moved here from `kernel/query/builder.ts`. Find carries no\n * cross-join concept, and a constant is the cheapest thing to leave behind by\n * accident: it would have kept `builder.ts` as the const's home while every\n * reader of it lived in `relate/`.\n */\nexport const DEFAULT_CROSS_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 the partition seam is honored: every leg carries\n * a `partitionScope` field that is always `'all'` and is never read by the\n * executor. See {@link JoinLeg.partitionScope}.\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'` today —\n   * the executor never reads this field. Do not remove even though it looks\n   * unused: it is a plan-shape seam.\n   *\n   * ⛔ TWO CONSTRAINTS BEFORE POPULATING THIS (#1342):\n   *\n   * 1. **It is a `queryHash` input on a HAND-COMPOSED path only — NOT for a\n   *    registered materialized view.** ⚠️ This paragraph asserted the\n   *    opposite until 2026-09-04; the correction is the measurement.\n   *    `MaterializedViewRegistry` feeds `computeQueryHash` from\n   *    `summarizeQueryPlan()` (`materialized-views/registry.ts:201,243`),\n   *    and that summary has never emitted `partitionScope`. `serializePlan()`\n   *    *does* emit `plan.joins` verbatim, and `canonicalizeQueryPlan` is\n   *    exported, so a consumer composing\n   *    `computeQueryHash(name, deps, canonicalizeQueryPlan(serializePlan(q)))`\n   *    by hand does carry the field in their hash. **That composition, and\n   *    only that one, is what this constraint binds** — it is also the\n   *    composition `__tests__/query-partition-scope.test.ts` builds, which is\n   *    why the file read as evidence for the stronger claim.\n   *    ⭐ So populating this field does NOT invalidate registered MVs. The\n   *    reason to leave it alone is smaller and still sufficient: it is a\n   *    DERIVED value — storing it buys nothing, and it is the one leg key\n   *    emitted UNCONDITIONALLY rather than omitted-at-default, so any later\n   *    move to summarise it (see #1389's rule) would shift every joined MV's\n   *    hash at once, for zero gain. Derive the scope in the EXECUTOR from\n   *    clauses the plan already carries. Pinned by\n   *    `__tests__/query-partition-scope.test.ts`, which now pins BOTH paths.\n   *\n   * 2. **The seam-change route was RULED OUT, and the pruning shipped\n   *    anyway** — ADR 0007, \"partitioning is collection-shaped\". Pruning only\n   *    pays on the `scan()` path (`query()` runs over an in-memory,\n   *    already-decrypted cache where `candidateRecords()`'s hash / sorted /\n   *    compound dispatch (#1344, #1345) narrows better than a partition ever\n   *    could). Buying it by teaching `NoydbStore.listPage` a filter would\n   *    have meant lifting the partition key out of the ciphertext into a\n   *    storage key or cleartext metadata — a permanent per-record\n   *    classification handed to the backend, and a change to the published\n   *    `@noy-db/hub/to` contract across every `to-*` adapter. **Ruled no.**\n   *    ⭐ The pruning was bought instead with information the store already\n   *    has: `listPage(vault, **collection**, …)` names the collection in\n   *    cleartext, so a partition modelled as its own collection is never\n   *    fetched because it is never asked for.\n   *\n   * ⭐ **THE SCOPE IS NOW DERIVED, IN THE EXECUTOR, AND THIS FIELD IS STILL\n   * DORMANT.** `kernel/query/relate/partition.ts`'s `resolvePartitionScope()` is the\n   * one decision function — `with-store/partitioned/` and `explain()` both\n   * call it — and it takes the plan's top-level clause list, never a stored\n   * leg. It is sound in one direction only: narrow ONLY on a whitelist of\n   * provable shapes (`==` / `in` on the declared key at the top level of the\n   * AND-ed clause list), and fall back to `'all'` for everything else —\n   * `or` groups, negations, callback clauses, and any Via-covered clause\n   * (its operand is in STORED form, not partition-key space, which is why\n   * `candidateRecords` refuses the index for it too). A partition wrongly\n   * excluded is silently missing data.\n   */\n  readonly partitionScope: 'all' | readonly string[]\n  /**\n   * Which side is preserved (#1289). `undefined` reads as `'left'` — the\n   * pre-#1289 behaviour — so every plan built before this field existed, and\n   * every serialized plan that omits it, keeps its meaning exactly.\n   */\n  readonly direction?: JoinDirection\n  /**\n   * INNER join (#1361) — drop every left row whose alias resolves to nothing,\n   * instead of attaching `null` under it.\n   *\n   * Only `.join()` sets it (a right/full leg already drops on its own side),\n   * and only when the caller passes `{ mode: 'inner' }`. Omitted rather than\n   * written as `false` for the same reason `direction` is: a plan built\n   * without it must serialize byte-identically to a pre-#1361 one, or every\n   * stored `queryHash` moves.\n   */\n  readonly inner?: true\n  /**\n   * A DECLARED, deterministic join predicate (#1339) — composite equality or\n   * a range — instead of the `ref()`-declared FK the rest of this file\n   * resolves. Set only by `.joinOn()`, always through\n   * {@link normalizeJoinOn}, and OMITTED on every other leg: a plan built by\n   * `.join()` must serialize byte-identically to a pre-#1339 one, or every\n   * stored `queryHash` moves (the same discipline `direction` and `inner`\n   * follow above).\n   *\n   * ⭐ This is the field that separates `.joinOn()` from `.crossJoin({ on })`.\n   * It is plain JSON, so it survives `serializePlan()` and\n   * `summarizeQueryPlan()` and a materialized view can therefore DEPEND on\n   * it. A closure cannot. See `join-on.ts`.\n   */\n  readonly on?: JoinOnPlan\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   * The id-paired view of {@link snapshot} (#1289).\n   *\n   * ⚠️ A `Collection` snapshot record does NOT carry its own id — the id is\n   * the cache key, not a field. The forward join never noticed, because it\n   * reads the id off the LEFT row's FK and calls `lookupById`. A right/full\n   * outer join has to ask each RIGHT record \"what is your id, and did\n   * anything point at you\", and there is no field to read it from.\n   *\n   * Optional so a plain-object test source stays valid; `outerJoinFromRight`\n   * falls back to an `id` FIELD on the record, which is what such sources\n   * carry. A real Collection supplies this and the fallback never runs.\n   */\n  snapshotEntries?(): readonly { readonly id: string; readonly record: unknown }[]\n  /**\n   * Via RESULT decode for this source's own records (#1289) — the same\n   * `via.decodeResults` a top-level `toArray()` applies (money's stored\n   * scaled-int → canonical decimal, etc.).\n   *\n   * It exists because Via dressing keys by BARE FIELD NAME: the moment a\n   * record moves under an alias (`{ client: { amount } }`, or both sides of\n   * `crossJoinWith`) the top-level decode cannot see it, and the row silently\n   * serves raw money. Distinct from `presentForJoin`, which is the LOCALE\n   * half (i18n text + lookup labels) and only runs for a locale-carrying\n   * query — this half is locale-free and always applies.\n   */\n  readonly decodeResults?: (record: unknown) => unknown\n  /**\n   * This source's own compiled Via pipeline (#1337 / #1338).\n   *\n   * The two halves above (`presentForJoin`, `decodeResults`) dress a record\n   * that is ON ITS WAY OUT. Ordering, grouping and reduction happen while it\n   * is still under an alias mid-plan, and they need the pipeline itself:\n   * `compareForOrder` to sort an aliased money field by MAGNITUDE rather than\n   * lexically over its stored scaled integer, and `wrapReducers` to rewrite\n   * `sum('client.credit')` into the exact-BigInt money reducer (which also\n   * applies the RIGHT collection's `queryable: 'none'` posture gate — the\n   * gate whose silent absence is why joined aggregation was refused).\n   *\n   * A THUNK, not a property: `_applyMoneyFields` can rebuild a collection's\n   * pipeline after this source object has been handed out, and a copied\n   * reference would go quietly stale — the same discipline `decodeResults`\n   * above already follows.\n   *\n   * Optional: a plain-object test source declares none, and every consumer\n   * treats absence as \"no binding covers anything here\".\n   */\n  readonly via?: () => ViaPipeline | undefined\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 * Does this clause address a field that only exists once join legs are\n * attached — i.e. is its path rooted at a join alias?\n *\n * Only `FieldClause` is inspectable. A `FilterClause` carries an opaque\n * function and a `WherePredicateClause` a named one, so neither can be\n * classified; both stay on the pre-join side, which is where they have\n * always run. See `splitAroundJoins`.\n */\nfunction referencesJoinAlias(clause: Clause, aliases: ReadonlySet<string>): boolean {\n  if (clause.type !== 'field') return false\n  // `where('client.name', …)` addresses the alias; so does the anti-join\n  // form `where('client', '==', null)`, where the path IS the alias.\n  return aliases.has(clause.field.split('.')[0]!)\n}\n\n/**\n * Split a plan's clauses into those evaluable before the join legs run and\n * those that need the joined shape (#1030).\n *\n * Join legs attach after `where` so the left set can be narrowed (and\n * index-driven) first. That is the right default, but it silently broke any\n * predicate addressing a joined alias: the field did not exist yet, so\n * `readPath` returned `undefined`, nothing matched, and the query returned an\n * empty result with no error.\n *\n * The split is deliberately narrow. When no clause addresses an alias — every\n * query written against the previous behaviour — `postJoin` is empty and the\n * caller takes its original path unchanged. The reordered pipeline therefore\n * only ever runs for queries that match nothing today.\n *\n * KNOWN RESIDUAL: `.filter(r => r.client?.name === 'Ann')` cannot be\n * classified (the predicate is a closure), so it still runs pre-join and still\n * sees no alias. Prefer `.where()` for anything addressing a joined field.\n *\n * Shared by the eager `Query` and the streaming `ScanBuilder` so the two\n * cannot drift on which side a clause belongs to.\n */\nexport function splitAroundJoins(\n  clauses: readonly Clause[],\n  joins: readonly JoinLeg[],\n): { readonly preJoin: readonly Clause[]; readonly postJoin: readonly Clause[] } {\n  if (joins.length === 0 || clauses.length === 0) return { preJoin: clauses, postJoin: [] }\n  const aliases = new Set(joins.map(leg => leg.as))\n  const preJoin: Clause[] = []\n  const postJoin: Clause[] = []\n  for (const clause of clauses) {\n    ;(referencesJoinAlias(clause, aliases) ? postJoin : preJoin).push(clause)\n  }\n  return { preJoin, postJoin }\n}\n\n/**\n * Does any `orderBy` entry address a field that only exists once the legs are\n * attached (#1337)?\n *\n * The ordering half of {@link splitAroundJoins}, kept beside it because the\n * two answer the same question about different parts of the plan, and because\n * `Query.toArray()` and `Query.explain()` must not drift on the answer — one\n * decides when the sort runs, the other reports it.\n *\n * ⚠️ Only `plan.joins` legs count. A `crossJoin` alias lives in the CLAUSE\n * list and its expansion already runs before ordering, so an ordering over\n * one has never needed moving.\n */\nexport function orderReferencesJoinAlias(\n  orderBy: readonly { readonly field: string }[],\n  joins: readonly JoinLeg[],\n): boolean {\n  if (joins.length === 0 || orderBy.length === 0) return false\n  const aliases = new Set(joins.map(leg => leg.as))\n  return orderBy.some(entry => aliases.has(entry.field.split('.')[0]!))\n}\n\n/**\n * Does any leg drop left rows (#1361)?\n *\n * The entry condition for every terminal that must run the legs even though\n * nothing addresses an alias: an inner leg is no longer projection-only, so\n * `count()`, `exists()` and the ordering placement in `toArray()` all have to\n * ask. Kept beside {@link splitAroundJoins} and {@link orderReferencesJoinAlias}\n * because the three answer the same family of question, and because\n * `Query.toArray()` and `Query.explain()` must not drift on the answer.\n */\nexport function joinsDropLeftRows(joins: readonly JoinLeg[]): boolean {\n  return joins.some(leg => leg.inner === true)\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 */\nexport function 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 by DEFAULT, so\n * \"top 10 invoices with client\" sorts and paginates the left side first\n * (index-driven) and joins only the page. Two things flip that, and both\n * are decided by the plan, never by a flag: a `where` addressing an alias\n * (#1030, {@link splitAroundJoins}) and an `orderBy` addressing one (#1337,\n * {@link orderReferencesJoinAlias}). Either one moves the sort and the page\n * to AFTER the legs, because neither can be evaluated against a row where\n * the alias does not exist yet. ⚠️ That query necessarily loses the\n * index-driven ordering fast path — the cost of sorting on a field the\n * index does not hold. `Query.explain()` names which placement a plan gets.\n *\n * An INNER leg (#1361) moves only the PAGE, not the sort: the drop removes\n * rows, so `limit` must observe it, but the ordering is on a left-side field\n * that the drop cannot reorder. `toArray()` therefore sorts pre-join, joins,\n * and slices after — and `explain()` reports `pre-join` on the sort and\n * `post-join` on the page rather than one word for both.\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\n/**\n * One leg, plus the #1361 inner-join drop.\n *\n * The drop is applied to the leg's OUTPUT rather than threaded through the\n * three producers (nested-loop, hash, dict) — an unmatched row is `null` under\n * the alias in all three by construction, and `attachJoin` has already run, so\n * a strict-mode `DanglingReferenceError` still fires for a dangling ref that\n * `inner` would otherwise hide.\n */\nfunction applyOneJoin(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  context: JoinContext,\n  locale?: string,\n): unknown[] {\n  const rows = applyOneJoinRaw(leftRows, leg, context, locale)\n  if (leg.inner !== true) return rows\n  return rows.filter(row => row !== null && typeof row === 'object' && (row as Record<string, unknown>)[leg.as] != null)\n}\n\nfunction applyOneJoinRaw(\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  // #1339 — a declared `on` replaces the FK lookup entirely: there is no\n  // ref, so neither `lookupById` nor the id-keyed hash means anything. It\n  // runs BEFORE the strategy/direction selection below because it answers\n  // both questions itself (see `join-on.ts` for which strategy serves which\n  // shape, and at what cost).\n  if (leg.on !== undefined) {\n    return declaredJoin(leftRows, leg, leg.on, rightSnapshot, maxRows, presentResolve)\n  }\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  // #1289 — a right/full outer join cannot be driven by the left row's FK,\n  // because the rows it must produce are exactly the ones no FK names. It\n  // reverses the index instead: bucket the LEFT rows by their FK value, then\n  // walk the right snapshot asking each record \"did anything point at me\".\n  const direction = leg.direction ?? 'left'\n  if (direction !== 'left') {\n    return outerJoinFromRight(leftRows, leg, source, direction, presentResolve)\n  }\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\n/**\n * Execute a declared-`on` leg (#1339).\n *\n * The match set comes from `join-on.ts`; this function is only the part that\n * has to agree with the rest of `.join()` — the alias attachment, the\n * present/decode dressing, and the OUTPUT ceiling.\n *\n * ⚠️ The output ceiling is not redundant with the two side ceilings above. A\n * ref join is one-to-one, so `output === leftRows`; a declared join is\n * many-to-many, so 1,000 × 1,000 rows both comfortably under a 50,000-row\n * side ceiling can produce a million rows. Checking as rows are produced is\n * what makes an unbounded theta join an error rather than a hang.\n */\nfunction declaredJoin(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  on: JoinOnPlan,\n  rightSnapshot: readonly unknown[],\n  maxRows: number,\n  presentResolve?: (right: unknown) => unknown,\n): unknown[] {\n  const matches = matchDeclaredJoin(leftRows, on, rightSnapshot, maxRows, produced => {\n    throw new JoinTooLargeError({\n      leftRows: leftRows.length,\n      rightRows: rightSnapshot.length,\n      maxRows,\n      side: 'output',\n      message:\n        `.joinOn(\"${leg.target}\") produced more than ${maxRows} rows (${produced} and counting) from ` +\n        `${leftRows.length} left x ${rightSnapshot.length} right. A declared \\`on\\` is many-to-many, so ` +\n        `the per-side ceilings do not bound the result. Narrow the predicate, filter the left side ` +\n        `with where()/limit() before joining, or raise the ceiling via { maxRows }.`,\n    })\n  })\n  const out: unknown[] = []\n  for (const { left, right } of matches) {\n    const dressed = presentResolve && right !== undefined ? presentResolve(right) : right\n    // `rawId` is `undefined` on purpose: a declared join has no ref, so\n    // \"matched nothing\" is never a DANGLING ref — `attachJoin` reads a null\n    // key as \"no reference at all\" and attaches null without consulting the\n    // ref mode. An unmatched row is data, not corruption.\n    out.push(attachJoin(left, leg, dressed, undefined))\n  }\n  return out\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 * Bucket the left rows by the FK value they carry, so the right side can be\n * asked \"did anything point at this record\" in O(1).\n *\n * This IS the reverse index #1289 names. It is built per execution and lives\n * only for the length of the join: nothing is persisted, no store is touched,\n * and it costs one pass over the left set that the forward path does not pay.\n * Left rows with a null/uncoercible FK are absent from every bucket — they are\n * \"no reference at all\", never a match.\n */\nfunction reverseIndex(leftRows: readonly unknown[], field: string): Map<string, unknown[]> {\n  return bucketByRefKey(leftRows, left => readPath(left, field))\n}\n\n/**\n * The reverse-FK index, generalised over what sits in the bucket (#1352).\n *\n * `outerJoinFromRight` buckets bare left ROWS by their FK; `traverse()`\n * buckets id-paired ENTRIES, because a child row alone cannot say what its\n * own id is (a Collection snapshot record carries no `id` field — the id is\n * the cache key). Same question — \"who points at this?\" — same coercion\n * rules, so it is deliberately one implementation rather than two that can\n * drift on what counts as a usable FK value.\n *\n * `readKey` extracts the raw FK from an item; `coerceRefKey` then decides\n * whether it is a key at all. An item whose FK is nullish, or is neither a\n * string nor a number, is dropped — \"no reference\", not \"a reference to\n * `[object Object]`\".\n */\nexport function bucketByRefKey<V>(\n  items: readonly V[],\n  readKey: (item: V) => unknown,\n): Map<string, V[]> {\n  const buckets = new Map<string, V[]>()\n  for (const item of items) {\n    const key = coerceRefKey(readKey(item))\n    if (key === null) continue\n    const bucket = buckets.get(key)\n    if (bucket) bucket.push(item)\n    else buckets.set(key, [item])\n  }\n  return buckets\n}\n\n/**\n * Right / full outer join (#1289).\n *\n * Walks the RIGHT snapshot as the driving relation. A right record with a\n * non-empty bucket emits one row per left row in it (identical in shape to\n * what the forward path would have produced); a right record nothing points\n * at emits a LEFT-LESS row — `{ [leg.as]: right }` and nothing else, which is\n * SQL's \"the left columns are NULL\" rendered in an object language.\n *\n * `'full'` then appends the left rows the right side never claimed, in their\n * original order, with `null` under the alias — i.e. exactly the rows the\n * forward left-outer path would emit for them, ref-mode behaviour included.\n * `'right'` drops those rows, but still runs the ref-mode check on them: a\n * strict dangling ref is a data-integrity finding, and hiding it behind a\n * change of join direction would make corruption depend on which method the\n * caller happened to type.\n */\nfunction outerJoinFromRight(\n  leftRows: readonly unknown[],\n  leg: JoinLeg,\n  source: JoinableSource,\n  direction: JoinDirection,\n  presentResolve?: (right: unknown) => unknown,\n): unknown[] {\n  const byRight = reverseIndex(leftRows, leg.field)\n  const matchedLeft = new Set<unknown>()\n  const out: unknown[] = []\n\n  // Prefer the id-paired view: a Collection record has no `id` field, so\n  // reading one off the record would leave every bucket unmatched and turn a\n  // right join into \"every right record is an orphan\" — wrong, and quietly so\n  // in `cascade`/`warn` mode. The field fallback serves plain-object sources.\n  const entries: readonly { id: string | null; record: unknown }[] =\n    source.snapshotEntries?.() ??\n    source.snapshot().map(record => ({ id: coerceRefKey(readPath(record, 'id')), record }))\n\n  for (const { id: rid, record: right } of entries) {\n    const dressed = presentResolve ? presentResolve(right) : right\n    const bucket = rid === null ? undefined : byRight.get(rid)\n    if (bucket === undefined || bucket.length === 0) {\n      // Nothing points at this record — the row that only a right/full outer\n      // join can produce.\n      out.push({ [leg.as]: dressed })\n      continue\n    }\n    for (const left of bucket) {\n      matchedLeft.add(left)\n      out.push(attachJoin(left, leg, dressed, readPath(left, leg.field)))\n    }\n  }\n\n  for (const left of leftRows) {\n    if (matchedLeft.has(left)) continue\n    // Unmatched left row: `attachJoin` with an undefined right applies the\n    // ref mode (strict throws, warn warns once) and attaches null.\n    const row = attachJoin(left, leg, undefined, readPath(left, leg.field))\n    if (direction === 'full') out.push(row)\n  }\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":[]}