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

package/dist/chunk-IFJTPAQQ.js

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

package/dist/chunk-IFJTPAQQ.js.map

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

package/dist/chunk-IGJCYUT5.js

@@ -0,0 +1,99 @@
+// src/kernel/query/predicate.ts
+function readPath(record, path) {
+  if (record === null || record === void 0) return void 0;
+  if (!path.includes(".")) {
+    return record[path];
+  }
+  const segments = path.split(".");
+  let cursor = record;
+  for (const segment of segments) {
+    if (cursor === null || cursor === void 0) return void 0;
+    cursor = cursor[segment];
+  }
+  return cursor;
+}
+function evaluateFieldClause(record, clause) {
+  const actual = readPath(record, clause.field);
+  const { op, value } = clause;
+  if (clause.via) return clause.via.evaluate(actual, op);
+  switch (op) {
+    case "==":
+      return actual === value;
+    case "!=":
+      return actual !== value;
+    case "<":
+      return isComparable(actual, value) && actual < value;
+    case "<=":
+      return isComparable(actual, value) && actual <= value;
+    case ">":
+      return isComparable(actual, value) && actual > value;
+    case ">=":
+      return isComparable(actual, value) && actual >= value;
+    case "in":
+      return Array.isArray(value) && value.includes(actual);
+    case "contains":
+      if (typeof actual === "string") return typeof value === "string" && actual.includes(value);
+      if (Array.isArray(actual)) return actual.includes(value);
+      return false;
+    case "startsWith":
+      return typeof actual === "string" && typeof value === "string" && actual.startsWith(value);
+    case "between": {
+      if (!Array.isArray(value) || value.length !== 2) return false;
+      const [lo, hi] = value;
+      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false;
+      return actual >= lo && actual <= hi;
+    }
+    default: {
+      const _exhaustive = op;
+      void _exhaustive;
+      return false;
+    }
+  }
+}
+function isComparable(a, b) {
+  if (typeof a === "number" && typeof b === "number") return true;
+  if (typeof a === "string" && typeof b === "string") return true;
+  if (a instanceof Date && b instanceof Date) return true;
+  return false;
+}
+function evaluateClause(record, clause, fnRecord) {
+  switch (clause.type) {
+    case "field":
+      return evaluateFieldClause(record, clause);
+    case "filter":
+      return clause.fn(fnRecord !== void 0 ? fnRecord : record);
+    case "wherePredicate":
+      return clause.fn(fnRecord !== void 0 ? fnRecord : record, clause.ctx);
+    case "crossJoin":
+      throw new Error(
+        `evaluateClause: 'crossJoin' clauses are expansion primitives and are not evaluated per-record. This is a query planner routing error \u2014 crossJoin clauses must be extracted from the clause list before calling evaluateClause or filterRecords.`
+      );
+    case "group":
+      if (clause.op === "and") {
+        for (const child of clause.clauses) {
+          if (!evaluateClause(record, child, fnRecord)) return false;
+        }
+        return true;
+      } else {
+        for (const child of clause.clauses) {
+          if (evaluateClause(record, child, fnRecord)) return true;
+        }
+        return false;
+      }
+  }
+}
+function hasFnClause(clauses) {
+  for (const c of clauses) {
+    if (c.type === "filter" || c.type === "wherePredicate") return true;
+    if (c.type === "group" && hasFnClause(c.clauses)) return true;
+  }
+  return false;
+}
+
+export {
+  readPath,
+  evaluateFieldClause,
+  evaluateClause,
+  hasFnClause
+};
+//# sourceMappingURL=chunk-IGJCYUT5.js.map

package/dist/chunk-IGJCYUT5.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kernel/query/predicate.ts"],"sourcesContent":["/**\n * Operator implementations for the query DSL.\n *\n * All predicates run client-side, AFTER decryption — they never see ciphertext.\n * Field clauses over a Via-covered field (e.g. money) carry their own\n * evaluator closure (see {@link FieldClause.via}), so this module has no\n * dependency on any Via feature's implementation — still tree-shakeable.\n */\n\n/** Comparison operators supported by the where() builder. */\nexport type Operator =\n  | '=='\n  | '!='\n  | '<'\n  | '<='\n  | '>'\n  | '>='\n  | 'in'\n  | 'contains'\n  | 'startsWith'\n  | 'between'\n\n/**\n * A single field comparison clause inside a query plan.\n * Plans are JSON-serializable, so this type uses primitives only.\n */\nexport interface FieldClause {\n  readonly type: 'field'\n  readonly field: string\n  readonly op: Operator\n  readonly value: unknown\n  /**\n   * Present when `field` is covered by a Via feature binding (e.g. a\n   * declared money field): the opaque payload built by the binding's\n   * `buildClause` at query BUILD time, plus a closure that evaluates it\n   * per record via the binding's `evaluateClause`. Attached by\n   * `Query.where()` / `ScanBuilder.where()` when `source.via` covers the\n   * field. The closure keeps this module free of any dependency on a\n   * Via feature's implementation — clauses are in-memory only, never\n   * serialized, so carrying a function here is safe.\n   */\n  readonly via?: {\n    readonly brand: string\n    readonly payload: unknown\n    readonly evaluate: (actual: unknown, op: string) => boolean\n    /**\n     * The binding's `indexProbe` result for this clause's op/payload\n     * (#625) — the STORED-form operand `candidateRecords()` (`kernel/\n     * query/builder.ts`) can hand to `CollectionIndexes.lookupEqual`/\n     * `lookupIn` for a fast path. `undefined` (no `indexProbe` hook, or\n     * the binding declined to probe this op) means the field must fall\n     * back to a linear scan via `evaluate` above.\n     */\n    readonly indexValue?: unknown\n  }\n}\n\n/**\n * A user-supplied predicate function escape hatch. Not serializable.\n *\n * The predicate accepts `unknown` at the type level so the surrounding\n * Clause type can stay non-parametric — this keeps Collection<T> covariant\n * in T at the public API surface. Builder methods cast user predicates\n * (typed `(record: T) => boolean`) into this shape on the way in.\n */\nexport interface FilterClause {\n  readonly type: 'filter'\n  readonly fn: (record: unknown) => boolean\n}\n\n/**\n * A declared deterministic predicate reference. The query\n * builder produces this via `.wherePredicate(name, ctx?)` when a\n * Query has been augmented with a predicates map (typically by the\n * materialized-view registry).\n *\n * `predicateHash` is the consumer-supplied stable hash for the\n * function body; `ctxHash` is the canonical-JSON SHA-256 of `ctx`.\n * Both fold into the MV's `queryHash` so a function or ctx change\n * forces refresh on next visit.\n *\n * `fn` is resolved at builder time from the predicates map and\n * embedded directly — so `evaluateClause` can fire it without a\n * runtime lookup.\n */\nexport interface WherePredicateClause {\n  readonly type: 'wherePredicate'\n  readonly name: string\n  readonly ctx: unknown\n  readonly predicateHash: string\n  readonly ctxHash: string\n  readonly fn: (record: unknown, ctx?: unknown) => boolean\n}\n\n/** A logical group of clauses combined by AND or OR. */\nexport interface GroupClause {\n  readonly type: 'group'\n  readonly op: 'and' | 'or'\n  readonly clauses: readonly Clause[]\n}\n\n/**\n * Cartesian-product expansion clause. Appended to `QueryPlan.clauses`\n * by `Query.crossJoin()`. Processed in declaration order by\n * `executeClausePipeline` — NOT by `evaluateClause` (which is a\n * per-record predicate and throws on this type).\n */\nexport interface CrossJoinClause {\n  readonly type: 'crossJoin'\n  /** Target collection name to cross-join against. */\n  readonly target: string\n  /** Alias under which the right-side record is exposed on each result row. */\n  readonly as: string\n  /**\n   * Lateral filter callback. `undefined` → full cartesian product.\n   * Two call shapes:\n   *   - Subset:    `(left) => TTarget[]`            — returns the right rows for this left row\n   *   - Predicate: `(left) => (right) => boolean`   — executor materializes then filters\n   */\n  readonly on?: (left: unknown) => unknown[] | ((right: unknown) => boolean)\n  /** When `on:` was supplied as `{ predicate: name }`, the name is stored here for queryHash. */\n  readonly onPredicateName?: string\n  /** Per-clause row ceiling override. `undefined` → `DEFAULT_CROSS_JOIN_MAX_ROWS`. */\n  readonly maxRows?: number\n}\n\nexport type Clause = FieldClause | FilterClause | WherePredicateClause | GroupClause | CrossJoinClause\n\n/**\n * Read a possibly nested field path like \"address.city\" from a record.\n * Returns undefined if any segment is missing.\n */\nexport function readPath(record: unknown, path: string): unknown {\n  if (record === null || record === undefined) return undefined\n  if (!path.includes('.')) {\n    return (record as Record<string, unknown>)[path]\n  }\n  const segments = path.split('.')\n  let cursor: unknown = record\n  for (const segment of segments) {\n    if (cursor === null || cursor === undefined) return undefined\n    cursor = (cursor as Record<string, unknown>)[segment]\n  }\n  return cursor\n}\n\n/**\n * Evaluate a single field clause against a record.\n * Returns false on type mismatches rather than throwing — query results\n * exclude non-matching records by definition.\n */\nexport function evaluateFieldClause(record: unknown, clause: FieldClause): boolean {\n  const actual = readPath(record, clause.field)\n  const { op, value } = clause\n\n  // A Via-covered field (e.g. money) may store a transformed\n  // representation (money: BigInt-exact in scaled-integer space) that the\n  // generic paths below can't compare correctly — the operand was\n  // pre-built at query BUILD time and the binding's own evaluator knows\n  // how to compare it against the raw stored value.\n  if (clause.via) return clause.via.evaluate(actual, op)\n\n  switch (op) {\n    case '==':\n      return actual === value\n    case '!=':\n      return actual !== value\n    case '<':\n      return isComparable(actual, value) && (actual as number) < (value as number)\n    case '<=':\n      return isComparable(actual, value) && (actual as number) <= (value as number)\n    case '>':\n      return isComparable(actual, value) && (actual as number) > (value as number)\n    case '>=':\n      return isComparable(actual, value) && (actual as number) >= (value as number)\n    case 'in':\n      return Array.isArray(value) && value.includes(actual)\n    case 'contains':\n      if (typeof actual === 'string') return typeof value === 'string' && actual.includes(value)\n      if (Array.isArray(actual)) return actual.includes(value)\n      return false\n    case 'startsWith':\n      return typeof actual === 'string' && typeof value === 'string' && actual.startsWith(value)\n    case 'between': {\n      if (!Array.isArray(value) || value.length !== 2) return false\n      const [lo, hi] = value\n      if (!isComparable(actual, lo) || !isComparable(actual, hi)) return false\n      return (actual as number) >= (lo as number) && (actual as number) <= (hi as number)\n    }\n    default: {\n      // Exhaustiveness — TS will error if a new operator is added without a case.\n      const _exhaustive: never = op\n      void _exhaustive\n      return false\n    }\n  }\n}\n\n/**\n * Two values are \"comparable\" if they share an order-defined runtime type.\n * Strings compare lexicographically; numbers and Dates numerically; otherwise false.\n */\nfunction isComparable(a: unknown, b: unknown): boolean {\n  if (typeof a === 'number' && typeof b === 'number') return true\n  if (typeof a === 'string' && typeof b === 'string') return true\n  if (a instanceof Date && b instanceof Date) return true\n  return false\n}\n\n/**\n * Evaluate any clause (field / filter / group) against a record.\n * The recursion depth is bounded by the user's query expression — no risk of\n * blowing the stack on a 50K-record collection.\n *\n * `fnRecord`, when provided, is the view handed to USER CALLBACK clauses\n * (`filter` / `wherePredicate`) instead of `record` — the executor passes\n * the money-decoded view there so user code never sees the stored\n * scaled-int form, while field clauses keep evaluating against the raw\n * record (their money operands are pre-quantized to that space).\n */\nexport function evaluateClause(record: unknown, clause: Clause, fnRecord?: unknown): boolean {\n  switch (clause.type) {\n    case 'field':\n      return evaluateFieldClause(record, clause)\n    case 'filter':\n      return clause.fn(fnRecord !== undefined ? fnRecord : record)\n    case 'wherePredicate':\n      return clause.fn(fnRecord !== undefined ? fnRecord : record, clause.ctx)\n    case 'crossJoin':\n      throw new Error(\n        `evaluateClause: 'crossJoin' clauses are expansion primitives and are not ` +\n          `evaluated per-record. This is a query planner routing error — ` +\n          `crossJoin clauses must be extracted from the clause list before calling ` +\n          `evaluateClause or filterRecords.`,\n      )\n    case 'group':\n      if (clause.op === 'and') {\n        for (const child of clause.clauses) {\n          if (!evaluateClause(record, child, fnRecord)) return false\n        }\n        return true\n      } else {\n        for (const child of clause.clauses) {\n          if (evaluateClause(record, child, fnRecord)) return true\n        }\n        return false\n      }\n  }\n}\n\n/**\n * Does the clause list contain any user-callback clause (filter /\n * wherePredicate), at any group nesting depth? Used by executors to\n * decide whether the per-record decoded view needs materializing.\n */\nexport function hasFnClause(clauses: readonly Clause[]): boolean {\n  for (const c of clauses) {\n    if (c.type === 'filter' || c.type === 'wherePredicate') return true\n    if (c.type === 'group' && hasFnClause(c.clauses)) return true\n  }\n  return false\n}\n"],"mappings":"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","names":[]}