@noy-db/hub 0.2.0-pre.2 → 0.2.0-pre.21

package/dist/executor-4IEW4KG5.js

@@ -0,0 +1,8 @@
+import {
+  DerivationExecutor
+} from "./chunk-6QAZ5O6X.js";
+import "./chunk-OTWT6BAJ.js";
+export {
+  DerivationExecutor
+};
+//# sourceMappingURL=executor-4IEW4KG5.js.map

package/dist/executor-KYJCJCIN.js

@@ -0,0 +1,12 @@
+import {
+  MaterializedViewExecutor
+} from "./chunk-5YTXYPES.js";
+import "./chunk-KOAJ3TZM.js";
+import "./chunk-JYNH4FIM.js";
+import "./chunk-U2XSUCDF.js";
+import "./chunk-TNH5SLCD.js";
+import "./chunk-OTWT6BAJ.js";
+export {
+  MaterializedViewExecutor
+};
+//# sourceMappingURL=executor-KYJCJCIN.js.map

package/dist/executor-W7VIBOBZ.js

@@ -0,0 +1,8 @@
+import {
+  GuardExecutor
+} from "./chunk-J6RGRZOY.js";
+import "./chunk-OTWT6BAJ.js";
+export {
+  GuardExecutor
+};
+//# sourceMappingURL=executor-W7VIBOBZ.js.map

package/dist/{fanout-sidecar-VJ52RIEY.js → fanout-sidecar-YXNAEZ33.js}

@@ -1,6 +1,6 @@
 import {
   NOYDB_FORMAT_VERSION
-} from "./chunk-YS3POABP.js";
+} from "./chunk-TA6HPKWQ.js";
 
 // src/derivations/fanout-sidecar.ts
 function recordId(source, sourceId, outputKey) {
@@ -48,4 +48,4 @@ export {
   loadFanoutSidecar,
   saveFanoutSidecar
 };
-//# sourceMappingURL=fanout-sidecar-VJ52RIEY.js.map
+//# sourceMappingURL=fanout-sidecar-YXNAEZ33.js.map

package/dist/fanout-sidecar-YXNAEZ33.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/derivations/fanout-sidecar.ts"],"sourcesContent":["/**\n * Per-source-row fanout sidecar for `shape: 'array'` derivations.\n *\n * Each `(sourceCollection, sourceId, outputKey)` triple gets its own\n * envelope at:\n *\n *     _meta/derivations-fanout/<sourceCollection>/<sourceId>/<outputKey>\n *\n * The envelope records the last-emitted derived row ids so the\n * dispatcher can compute the diff on every source-row update in O(1):\n * read prior keys, compute `toDelete = prev \\ new`, write new, persist\n * back.\n *\n * Stored as plain JSON with AES-GCM bypassed (same pattern as\n * `_meta/policy`, `_meta/recovery-paper`, `_meta/sealed-passphrase`,\n * etc.): the sidecar is system metadata, not user data, and the\n * derived outputs themselves carry their own encryption envelopes.\n *\n * @module\n */\nimport type { NoydbStore, EncryptedEnvelope } from '../types.js'\nimport { NOYDB_FORMAT_VERSION } from '../types.js'\n\n/** Magic-prefixed JSON payload at `_meta/<recordId>`. */\nexport interface FanoutSidecar {\n  readonly _noydb_fanout: 1\n  /** Source collection name. */\n  readonly source: string\n  /** Source record id. */\n  readonly sourceId: string\n  /** Strategy output key (the key in `strategy.outputs`). */\n  readonly outputKey: string\n  /** Output collection name (audit / forensics). */\n  readonly outputCollection: string\n  /** Derived-row ids last emitted for this (source, output) pair. */\n  readonly keys: ReadonlyArray<string>\n  /** ISO timestamp of last dispatch. */\n  readonly emittedAt: string\n}\n\n/**\n * Build the canonical `_meta` record id for a fanout sidecar.\n *\n * The full path inside the store is `_meta/<this-string>`. We pack the\n * full triple into the id so a single `_meta` collection holds all\n * sidecars (collection-per-source would proliferate names; the\n * existing `_meta` flat namespace is cheaper).\n */\nfunction recordId(source: string, sourceId: string, outputKey: string): string {\n  // Use `/` as a separator. None of the components is supposed to\n  // contain it (collection names + output keys are bare identifiers;\n  // source ids are typically ULIDs / UUIDs / app-chosen strings\n  // without slashes). If a future source carries `/` in its id, we'd\n  // need an escape; deferred until that's a real case.\n  return `derivations-fanout/${source}/${sourceId}/${outputKey}`\n}\n\n/** Read the sidecar; returns empty if absent. */\nexport async function loadFanoutSidecar(\n  store: NoydbStore,\n  vault: string,\n  source: string,\n  sourceId: string,\n  outputKey: string,\n): Promise<FanoutSidecar | undefined> {\n  const envelope = await store.get(vault, '_meta', recordId(source, sourceId, outputKey))\n  if (!envelope) return undefined\n  try {\n    const parsed = JSON.parse(envelope._data) as FanoutSidecar\n    if (parsed._noydb_fanout !== 1) return undefined\n    if (!Array.isArray(parsed.keys)) return undefined\n    return parsed\n  } catch {\n    return undefined\n  }\n}\n\n/** Persist (insert/replace) the sidecar with a fresh key set. */\nexport async function saveFanoutSidecar(\n  store: NoydbStore,\n  vault: string,\n  payload: {\n    readonly source: string\n    readonly sourceId: string\n    readonly outputKey: string\n    readonly outputCollection: string\n    readonly keys: ReadonlyArray<string>\n  },\n): Promise<void> {\n  const doc: FanoutSidecar = {\n    _noydb_fanout: 1,\n    source: payload.source,\n    sourceId: payload.sourceId,\n    outputKey: payload.outputKey,\n    outputCollection: payload.outputCollection,\n    keys: payload.keys,\n    emittedAt: new Date().toISOString(),\n  }\n  const id = recordId(payload.source, payload.sourceId, payload.outputKey)\n  const prior = await store.get(vault, '_meta', id)\n  const envelope: EncryptedEnvelope = {\n    _noydb: NOYDB_FORMAT_VERSION,\n    _v: (prior?._v ?? 0) + 1,\n    _ts: new Date().toISOString(),\n    // AES-GCM bypassed — sidecar is system metadata, no user data inside.\n    _iv: '',\n    _data: JSON.stringify(doc),\n  }\n  await store.put(vault, '_meta', id, envelope)\n}\n\n/** Delete the sidecar (used on source-row delete cascade). */\nexport async function deleteFanoutSidecar(\n  store: NoydbStore,\n  vault: string,\n  source: string,\n  sourceId: string,\n  outputKey: string,\n): Promise<void> {\n  await store.delete(vault, '_meta', recordId(source, sourceId, outputKey))\n}\n"],"mappings":";;;;;AAgDA,SAAS,SAAS,QAAgB,UAAkB,WAA2B;AAM7E,SAAO,sBAAsB,MAAM,IAAI,QAAQ,IAAI,SAAS;AAC9D;AAGA,eAAsB,kBACpB,OACA,OACA,QACA,UACA,WACoC;AACpC,QAAM,WAAW,MAAM,MAAM,IAAI,OAAO,SAAS,SAAS,QAAQ,UAAU,SAAS,CAAC;AACtF,MAAI,CAAC,SAAU,QAAO;AACtB,MAAI;AACF,UAAM,SAAS,KAAK,MAAM,SAAS,KAAK;AACxC,QAAI,OAAO,kBAAkB,EAAG,QAAO;AACvC,QAAI,CAAC,MAAM,QAAQ,OAAO,IAAI,EAAG,QAAO;AACxC,WAAO;AAAA,EACT,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGA,eAAsB,kBACpB,OACA,OACA,SAOe;AACf,QAAM,MAAqB;AAAA,IACzB,eAAe;AAAA,IACf,QAAQ,QAAQ;AAAA,IAChB,UAAU,QAAQ;AAAA,IAClB,WAAW,QAAQ;AAAA,IACnB,kBAAkB,QAAQ;AAAA,IAC1B,MAAM,QAAQ;AAAA,IACd,YAAW,oBAAI,KAAK,GAAE,YAAY;AAAA,EACpC;AACA,QAAM,KAAK,SAAS,QAAQ,QAAQ,QAAQ,UAAU,QAAQ,SAAS;AACvE,QAAM,QAAQ,MAAM,MAAM,IAAI,OAAO,SAAS,EAAE;AAChD,QAAM,WAA8B;AAAA,IAClC,QAAQ;AAAA,IACR,KAAK,OAAO,MAAM,KAAK;AAAA,IACvB,MAAK,oBAAI,KAAK,GAAE,YAAY;AAAA;AAAA,IAE5B,KAAK;AAAA,IACL,OAAO,KAAK,UAAU,GAAG;AAAA,EAC3B;AACA,QAAM,MAAM,IAAI,OAAO,SAAS,IAAI,QAAQ;AAC9C;AAGA,eAAsB,oBACpB,OACA,OACA,QACA,UACA,WACe;AACf,QAAM,MAAM,OAAO,OAAO,SAAS,SAAS,QAAQ,UAAU,SAAS,CAAC;AAC1E;","names":[]}

package/dist/forget/index.cjs

@@ -0,0 +1,43 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/forget/index.ts
+var forget_exports = {};
+__export(forget_exports, {
+  NO_FORGET: () => NO_FORGET,
+  SUBJECT_INDEX_COLLECTION: () => SUBJECT_INDEX_COLLECTION,
+  withForgetCascade: () => withForgetCascade
+});
+module.exports = __toCommonJS(forget_exports);
+
+// src/forget/strategy.ts
+var NO_FORGET = { subjects: {} };
+function withForgetCascade(opts) {
+  return { subjects: { ...opts.subjects } };
+}
+
+// src/forget/subject-index.ts
+var SUBJECT_INDEX_COLLECTION = "_subject_index";
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  NO_FORGET,
+  SUBJECT_INDEX_COLLECTION,
+  withForgetCascade
+});
+//# sourceMappingURL=index.cjs.map

package/dist/forget/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/forget/index.ts","../../src/forget/strategy.ts","../../src/forget/subject-index.ts"],"sourcesContent":["/**\n * `@noy-db/hub/forget` — GDPR right-to-erasure via per-record CEK crypto-shred\n * (#304). Import `withForgetCascade` and pass it to `createNoydb`:\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withForgetCascade } from '@noy-db/hub/forget'\n *\n * const db = createNoydb({\n *   secret, user,\n *   historyStrategy: withHistory(),               // ledger for the erasure proof\n *   forgetStrategy: withForgetCascade({ subjects: { invoices: 'buyerId' } }),\n * })\n * const result = await db.vault('main').forget('buyer-123')\n * ```\n *\n * The erasure flow (`vault.forget`), the subject-index maintenance hooks, and\n * the tombstone rewrite live in core (`vault.ts` / `collection.ts`) because\n * they touch the write path directly; this subpath only exposes the\n * declaration factory + result types.\n *\n * @module\n */\nexport {\n  withForgetCascade,\n  NO_FORGET,\n} from './strategy.js'\nexport type {\n  SubjectDeclaration,\n  ForgetStrategy,\n  ForgetResult,\n} from './strategy.js'\nexport type { SubjectRef } from './subject-index.js'\nexport { SUBJECT_INDEX_COLLECTION } from './subject-index.js'\n","/**\n * `withForgetCascade` — declaration surface for GDPR right-to-erasure via\n * per-record CEK crypto-shred (#304, step 2 of the CEK security epic).\n *\n * This file holds only the *declaration* shape and the disabled sentinel.\n * The actual erasure machinery lives in:\n *   - `subject-index.ts` — the encrypted `_subject_index` reserved collection\n *   - `vault.ts` `forget()` — the per-record tombstone + ledger flow\n *   - `collection.ts` `_writeTombstone` — the envelope rewrite\n *\n * A `ForgetStrategy` declares which collections carry erasable subject data\n * and the (dotted-path) field on each record that names the data subject.\n * Declaring a collection here ALSO forces `perRecordKeys: true` for it (a\n * shred can only erase a record whose body is keyed off a per-record CEK),\n * so adopters opt into the CEK foundation transitively.\n *\n * @module\n */\nimport type { LedgerEntry } from '../history/ledger/entry.js'\n\n/**\n * User-supplied declaration passed to {@link withForgetCascade}. Maps a\n * collection name to the record field (dotted path supported, e.g.\n * `'billing.buyerId'`) that identifies the data subject for erasure.\n *\n * ```ts\n * withForgetCascade({ subjects: { invoices: 'buyerId', contacts: 'id' } })\n * ```\n */\nexport interface SubjectDeclaration {\n  readonly subjects: Record<string, string>\n}\n\n/**\n * Resolved forget strategy threaded through Noydb → every Vault. Carries\n * the same `subjects` map the user declared. `NO_FORGET` (empty map) is the\n * off-by-default sentinel; `vault.forget()` throws\n * `ForgetStrategyNotConfiguredError` when the map is empty.\n */\nexport interface ForgetStrategy {\n  /** Collection → subject-field (dotted path). Empty under `NO_FORGET`. */\n  readonly subjects: Readonly<Record<string, string>>\n}\n\n/**\n * Disabled sentinel — no collections declare a subject field. `vault.forget()`\n * refuses with `ForgetStrategyNotConfiguredError`; no write hooks register; no\n * collection is forced into `perRecordKeys`. Non-adopters pay nothing.\n */\nexport const NO_FORGET: ForgetStrategy = { subjects: {} }\n\n/**\n * Declare GDPR crypto-shred for one or more collections.\n *\n * Each declared collection is forced to `perRecordKeys: true` (a shred can\n * only guarantee erasure of a record whose body is keyed off a per-record\n * CEK). On write, Noydb extracts `record[subjectField]` and maintains an\n * encrypted `_subject_index` mapping `subject → [{collection, id}]`, so\n * `vault.forget(subjectId)` can find every record for a subject and rewrite\n * each to a tombstone (body + history permanently undecryptable) while the\n * collection DEK and every other record stay intact.\n *\n * @example\n * ```ts\n * createNoydb({\n *   secret, user,\n *   forgetStrategy: withForgetCascade({ subjects: { invoices: 'buyerId' } }),\n * })\n * const result = await vault.forget('buyer-123')\n * // → { subject, recordsShredded, historyVersionsShredded, collections, … }\n * ```\n */\nexport function withForgetCascade(opts: SubjectDeclaration): ForgetStrategy {\n  return { subjects: { ...opts.subjects } }\n}\n\n/**\n * The outcome of a `vault.forget(subjectId)` call.\n *\n * `unmigratedRecords` lists `collection:id` pairs that were tombstoned but\n * whose body had NOT been migrated to a per-record CEK at shred time (legacy\n * body still under the shared collection DEK). Those records are tombstoned\n * (live envelope + history stripped) but their pre-shred ciphertext, if it\n * leaked into a backup before migration, remains decryptable under the\n * collection DEK — so erasure-completeness is NOT guaranteed for them. Run\n * the per-record-CEK migration pass, then re-forget, to close the gap.\n *\n * Blob attachments (#365): a shredded record's **erasable** blobs (on a\n * `perRecordKeys` collection) are crypto-shredded inline — `blobsShredded`\n * counts those taken to refCount 0 (BlobObject deleted → chunks permanently\n * undecryptable), `blobsRetainedShared` counts those still referenced by\n * another record (shared content legitimately persists for its other owner).\n * `blobResidueCollections` now lists only collections with blobs that could\n * NOT be crypto-shredded: **legacy** blobs (no per-blob `_cek`, chunks under\n * the shared `_blob` DEK — migrate them), or a session without the blob\n * subsystem loaded. An all-erasable subject yields an empty residue list.\n */\nexport interface ForgetResult {\n  /** The subject id passed to `forget()`. Echoed for caller convenience. */\n  readonly subject: string\n  /** Count of live records rewritten to a tombstone. */\n  readonly recordsShredded: number\n  /** Count of `_history` envelopes tombstoned across all shredded records. */\n  readonly historyVersionsShredded: number\n  /** Distinct collections that had at least one record shredded. */\n  readonly collections: readonly string[]\n  /** `collection:id` pairs shredded while still un-migrated (see type docs). */\n  readonly unmigratedRecords: readonly string[]\n  /** Count of erasable blobs crypto-shredded (refCount → 0, BlobObject deleted). */\n  readonly blobsShredded: number\n  /** Count of erasable blobs retained because still referenced elsewhere (shared). */\n  readonly blobsRetainedShared: number\n  /** Collections with blobs that could NOT be crypto-shredded — legacy (no `_cek`) or blobs disabled (see type docs). */\n  readonly blobResidueCollections: readonly string[]\n  /**\n   * Count of persisted `_idx/<field>/<recordId>` index side-cars hard-deleted\n   * across the shredded records (#401). These live under the retained\n   * collection DEK, so crypto-shred alone would leave the indexed field VALUES\n   * readable — `forget()` must delete them.\n   */\n  readonly indexPostingsPurged: number\n  /**\n   * `collection:id:field` entries whose persisted `_idx` side-car could NOT be\n   * deleted (#401) — index residue that still leaks the indexed value under the\n   * retained collection DEK. Non-empty means erasure is INCOMPLETE: retry, or\n   * purge the side-car out of band.\n   */\n  readonly indexResidue: readonly string[]\n  /** The single `op:'forget'` ledger entry appended for this erasure. */\n  readonly ledgerEntry: LedgerEntry\n}\n","/**\n * The encrypted subject index (#304).\n *\n * GDPR crypto-shred needs to answer \"which records belong to data subject\n * X?\" portably (the index must travel with the vault/bundle) WITHOUT leaking\n * subject-equivalence to the store. The rejected alternative — an unencrypted\n * subject tag in envelope metadata — would let anyone with store access see\n * which records share a subject. Instead we keep a reserved `_subject_index`\n * collection, encrypted under its OWN DEK (`getDEK('_subject_index')`):\n *\n *   - record id  = `sha256Hex(subjectId)` — the raw subject id never appears\n *     as a key, so the store can't correlate index entries to a known subject.\n *   - record body = AES-GCM(JSON `[{ collection, id }]`) under the index DEK.\n *\n * ## Concurrency (RISK #3 — known v1 limitation)\n *\n * `addSubjectRef` / `removeSubjectRef` are read-modify-write with no CAS. The\n * design assumes a SINGLE WRITER (the noy-db single-process write model). Two\n * concurrent writers racing on the SAME subject can lose an entry (last-write\n * wins on the ref list). This is documented, not fixed in v1:\n * `rebuildSubjectIndex` performs a full scan to recover a correct index from\n * the canonical records, so a lost ref is recoverable. A CAS-backed index is\n * deferred to a later slice.\n *\n * @module\n */\nimport { encrypt, decrypt } from '../crypto.js'\nimport type { NoydbStore, EncryptedEnvelope } from '../types.js'\nimport { NOYDB_FORMAT_VERSION } from '../types.js'\n\n/** Reserved collection holding the encrypted subject → records index. */\nexport const SUBJECT_INDEX_COLLECTION = '_subject_index'\n\n/** A single record reference held in a subject's index entry. */\nexport interface SubjectRef {\n  readonly collection: string\n  readonly id: string\n}\n\ntype GetDEK = (collectionName: string) => Promise<CryptoKey>\n\n/** SHA-256 hex of a UTF-8 string. The subject-index record key derivation. */\nasync function sha256HexString(input: string): Promise<string> {\n  const bytes = new TextEncoder().encode(input)\n  const digest = await globalThis.crypto.subtle.digest('SHA-256', bytes)\n  return Array.from(new Uint8Array(digest))\n    .map((b) => b.toString(16).padStart(2, '0'))\n    .join('')\n}\n\n/** Stable subject-index record id for a subject id. */\nexport async function subjectKey(subjectId: string): Promise<string> {\n  return sha256HexString(subjectId)\n}\n\n/** Read + decrypt the ref list for a subject. Returns `[]` when absent. */\nasync function readRefs(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  key: string,\n): Promise<SubjectRef[]> {\n  const env = await adapter.get(vault, SUBJECT_INDEX_COLLECTION, key)\n  if (!env || !env._data) return []\n  if (!encrypted) return JSON.parse(env._data) as SubjectRef[]\n  const dek = await getDEK(SUBJECT_INDEX_COLLECTION)\n  const json = await decrypt(env._iv, env._data, dek)\n  return JSON.parse(json) as SubjectRef[]\n}\n\n/** Encrypt + write a ref list for a subject under its derived key. */\nasync function writeRefs(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  key: string,\n  refs: SubjectRef[],\n): Promise<void> {\n  const json = JSON.stringify(refs)\n  let env: EncryptedEnvelope\n  if (!encrypted) {\n    env = { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: new Date().toISOString(), _iv: '', _data: json }\n  } else {\n    const dek = await getDEK(SUBJECT_INDEX_COLLECTION)\n    const { iv, data } = await encrypt(json, dek)\n    env = { _noydb: NOYDB_FORMAT_VERSION, _v: 1, _ts: new Date().toISOString(), _iv: iv, _data: data }\n  }\n  await adapter.put(vault, SUBJECT_INDEX_COLLECTION, key, env)\n}\n\n/**\n * Add a `{ collection, id }` ref to a subject's index entry (idempotent —\n * a duplicate ref is not appended). Read-modify-write; see the concurrency\n * note in the module docstring.\n */\nexport async function addSubjectRef(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  subjectId: string,\n  ref: SubjectRef,\n): Promise<void> {\n  const key = await subjectKey(subjectId)\n  const refs = await readRefs(adapter, vault, getDEK, encrypted, key)\n  if (refs.some((r) => r.collection === ref.collection && r.id === ref.id)) return\n  refs.push(ref)\n  await writeRefs(adapter, vault, getDEK, encrypted, key, refs)\n}\n\n/**\n * Remove a `{ collection, id }` ref from a subject's index entry. When the\n * last ref is removed the (now empty) entry is deleted so the store holds no\n * residual key for an erased subject.\n */\nexport async function removeSubjectRef(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  subjectId: string,\n  ref: SubjectRef,\n): Promise<void> {\n  const key = await subjectKey(subjectId)\n  const refs = await readRefs(adapter, vault, getDEK, encrypted, key)\n  const next = refs.filter((r) => !(r.collection === ref.collection && r.id === ref.id))\n  if (next.length === refs.length) return\n  if (next.length === 0) {\n    await adapter.delete(vault, SUBJECT_INDEX_COLLECTION, key)\n    return\n  }\n  await writeRefs(adapter, vault, getDEK, encrypted, key, next)\n}\n\n/** Look up every record ref for a subject. Returns `[]` when none exist. */\nexport async function lookupSubject(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  subjectId: string,\n): Promise<SubjectRef[]> {\n  const key = await subjectKey(subjectId)\n  return readRefs(adapter, vault, getDEK, encrypted, key)\n}\n\n/**\n * Rebuild the entire subject index from the canonical records (the recovery\n * path for the documented read-modify-write race). Scans each declared\n * collection, reads `record[subjectField]` (dotted path), and rewrites the\n * index from scratch. Tombstoned (already-shredded) records contribute no\n * ref — their body is gone, so they cannot be re-indexed.\n *\n * `decodeRecord` decrypts an envelope to a plain object (or returns null for\n * a tombstone / unreadable record); supplied by the caller so this module\n * stays free of Collection internals.\n */\nexport async function rebuildSubjectIndex(\n  adapter: NoydbStore,\n  vault: string,\n  getDEK: GetDEK,\n  encrypted: boolean,\n  subjects: Readonly<Record<string, string>>,\n  decodeRecord: (collection: string, id: string, env: EncryptedEnvelope) => Promise<Record<string, unknown> | null>,\n): Promise<number> {\n  // Drop every existing index entry first so removed refs don't linger.\n  const existing = await adapter.list(vault, SUBJECT_INDEX_COLLECTION)\n  for (const k of existing) {\n    await adapter.delete(vault, SUBJECT_INDEX_COLLECTION, k)\n  }\n\n  // subjectId → refs, accumulated across all declared collections.\n  const bySubject = new Map<string, SubjectRef[]>()\n  for (const [collection, field] of Object.entries(subjects)) {\n    const ids = await adapter.list(vault, collection)\n    for (const id of ids) {\n      if (id.startsWith('_')) continue\n      const env = await adapter.get(vault, collection, id)\n      if (!env || !env._data) continue // missing or tombstone\n      const record = await decodeRecord(collection, id, env)\n      if (record === null) continue\n      const subjectValue = readDottedPath(record, field)\n      if (subjectValue === undefined || subjectValue === null) continue\n      const subjectId = coerceSubjectId(subjectValue)\n      const list = bySubject.get(subjectId) ?? []\n      list.push({ collection, id })\n      bySubject.set(subjectId, list)\n    }\n  }\n\n  let entries = 0\n  for (const [subjectId, refs] of bySubject) {\n    const key = await subjectKey(subjectId)\n    await writeRefs(adapter, vault, getDEK, encrypted, key, refs)\n    entries++\n  }\n  return entries\n}\n\n/**\n * Coerce a read subject-field value to a stable string id. Primitives use\n * their natural string form; objects/arrays are JSON-stringified so structural\n * subjects still get a deterministic key (avoids the `[object Object]` trap).\n */\nexport function coerceSubjectId(value: unknown): string {\n  if (typeof value === 'string') return value\n  if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {\n    return String(value)\n  }\n  return JSON.stringify(value)\n}\n\n/** Read a (possibly dotted) field path from a plain record. */\nexport function readDottedPath(record: Record<string, unknown>, field: string): unknown {\n  if (!field.includes('.')) return record[field]\n  let cursor: unknown = record\n  for (const segment of field.split('.')) {\n    if (cursor === null || cursor === undefined) return undefined\n    cursor = (cursor as Record<string, unknown>)[segment]\n  }\n  return cursor\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACiDO,IAAM,YAA4B,EAAE,UAAU,CAAC,EAAE;AAuBjD,SAAS,kBAAkB,MAA0C;AAC1E,SAAO,EAAE,UAAU,EAAE,GAAG,KAAK,SAAS,EAAE;AAC1C;;;AC3CO,IAAM,2BAA2B;","names":[]}

package/dist/forget/index.d.cts

@@ -0,0 +1 @@
+export { b as ForgetResult, F as ForgetStrategy, N as NO_FORGET, d as SUBJECT_INDEX_COLLECTION, e as SubjectDeclaration, S as SubjectRef, w as withForgetCascade } from '../index-BMmajblo.cjs';

package/dist/forget/index.d.ts

@@ -0,0 +1 @@
+export { b as ForgetResult, F as ForgetStrategy, N as NO_FORGET, d as SUBJECT_INDEX_COLLECTION, e as SubjectDeclaration, S as SubjectRef, w as withForgetCascade } from '../index-BMmajblo.js';

package/dist/forget/index.js

@@ -0,0 +1,14 @@
+import {
+  NO_FORGET,
+  SUBJECT_INDEX_COLLECTION,
+  withForgetCascade
+} from "../chunk-CQYEDODS.js";
+import "../chunk-TA6HPKWQ.js";
+import "../chunk-37VGJM3T.js";
+import "../chunk-OTWT6BAJ.js";
+export {
+  NO_FORGET,
+  SUBJECT_INDEX_COLLECTION,
+  withForgetCascade
+};
+//# sourceMappingURL=index.js.map

package/dist/guards/index.cjs

@@ -24,9 +24,12 @@ __export(guards_exports, {
   FieldFrozenError: () => FieldFrozenError,
   GuardExecutor: () => GuardExecutor,
   GuardRegistry: () => GuardRegistry,
+  IllegalTransitionError: () => IllegalTransitionError,
   InvariantError: () => InvariantError,
   ReadOnlyVaultFacade: () => ReadOnlyVaultFacade,
   RecordLockedError: () => RecordLockedError,
+  immutableGuard: () => immutableGuard,
+  transitionGuard: () => transitionGuard,
   withGuard: () => withGuard
 });
 module.exports = __toCommonJS(guards_exports);
@@ -71,6 +74,23 @@ var FieldFrozenError = class extends NoydbError {
     this.fields = fields;
   }
 };
+var IllegalTransitionError = class extends NoydbError {
+  collection;
+  id;
+  from;
+  to;
+  constructor(collection, id, from, to) {
+    super(
+      "ILLEGAL_TRANSITION",
+      `Cannot transition ${collection}/${id} from "${from}" to "${to}" \u2014 not a declared arc. Use withTransactions({ amendment: true, reason }) with admin/owner role to override.`
+    );
+    this.name = "IllegalTransitionError";
+    this.collection = collection;
+    this.id = id;
+    this.from = from;
+    this.to = to;
+  }
+};
 var InvariantError = class extends NoydbError {
   constructor(message) {
     super("INVARIANT_VIOLATED", message);
@@ -108,6 +128,106 @@ function withGuard(strategy) {
   };
 }
 
+// src/guards/immutable-guard.ts
+function recordId(record) {
+  const id = record?.id;
+  return typeof id === "string" ? id : "";
+}
+function immutableGuard(config) {
+  const { collection, after, appendOnly, amendmentRoles, amendmentInvariant } = config;
+  if (appendOnly && after !== void 0) {
+    throw new ValidationError("immutableGuard: `after` and `appendOnly` are mutually exclusive");
+  }
+  if (!appendOnly && after === void 0) {
+    throw new ValidationError("immutableGuard: provide `after` or `appendOnly: true`");
+  }
+  const isImmutable = appendOnly ? () => true : after;
+  const reason = appendOnly ? "append-only collection" : "record is immutable after issue";
+  const spec = {
+    collection,
+    // Block updates to an already-immutable record. Inserts (existing
+    // null) and the transition write that first makes the record
+    // immutable are allowed — `after` reads the prior state.
+    check: (incoming, ctx) => {
+      if (ctx.existing !== null && isImmutable(ctx.existing)) {
+        throw new RecordLockedError(collection, recordId(incoming), reason);
+      }
+    },
+    // Block deletes of an immutable record.
+    onDelete: (existing) => {
+      if (isImmutable(existing)) {
+        throw new RecordLockedError(collection, recordId(existing), reason);
+      }
+    },
+    // The authorized override: inside an amendment transaction the
+    // check/onDelete are skipped and the change is ledgered. By default
+    // there is no extra invariant — the amendment itself is the
+    // sanctioned exception. Callers may supply `amendmentInvariant` to
+    // keep a constraint inviolable even under amendment (e.g. forbid
+    // deletes, or preserve a cross-record sum); a throw reverts the
+    // amendment and surfaces as `InvariantError`.
+    amendment: {
+      roles: amendmentRoles ?? ["admin", "owner"],
+      invariant: amendmentInvariant ?? (() => {
+      })
+    }
+  };
+  return withGuard(spec);
+}
+
+// src/guards/transition-guard.ts
+function recordId2(record) {
+  const id = record?.id;
+  return typeof id === "string" ? id : "";
+}
+function stateOf(record, field) {
+  const v = record[field];
+  return typeof v === "string" ? v : String(v);
+}
+function transitionGuard(config) {
+  const { collection, field, transitions, initial, amendmentRoles, amendmentInvariant } = config;
+  const allowIdempotent = config.allowIdempotent ?? true;
+  if (!field) {
+    throw new ValidationError("transitionGuard: `field` is required");
+  }
+  if (transitions === void 0 || typeof transitions !== "object") {
+    throw new ValidationError("transitionGuard: `transitions` must be a state\u2192states map");
+  }
+  const spec = {
+    collection,
+    check: (incoming, ctx) => {
+      const rec = incoming;
+      const to = stateOf(rec, field);
+      if (ctx.existing === null) {
+        if (initial !== void 0 && !initial.includes(to)) {
+          throw new IllegalTransitionError(collection, recordId2(rec), "(none)", to);
+        }
+        return;
+      }
+      const from = stateOf(ctx.existing, field);
+      if (from === to) {
+        if (allowIdempotent) return;
+        throw new IllegalTransitionError(collection, recordId2(rec), from, to);
+      }
+      const allowed = transitions[from] ?? [];
+      if (!allowed.includes(to)) {
+        throw new IllegalTransitionError(collection, recordId2(rec), from, to);
+      }
+    },
+    // The authorized override: inside an amendment transaction the check
+    // is skipped and the change is ledgered. By default no extra invariant
+    // — the amendment itself is the sanctioned exception. Callers may
+    // supply `amendmentInvariant` to keep a constraint inviolable even
+    // under amendment; a throw reverts the amendment as `InvariantError`.
+    amendment: {
+      roles: amendmentRoles ?? ["admin", "owner"],
+      invariant: amendmentInvariant ?? (() => {
+      })
+    }
+  };
+  return withGuard(spec);
+}
+
 // src/guards/registry.ts
 var GuardRegistry = class {
   _byCollection = /* @__PURE__ */ new Map();
@@ -123,6 +243,13 @@ var GuardRegistry = class {
   guardsFor(collection) {
     return this._byCollection.get(collection) ?? [];
   }
+  /** Per-collection guard counts, for introspection. */
+  summary() {
+    return [...this._byCollection.entries()].map(([collection, guards]) => ({
+      collection,
+      count: guards.length
+    }));
+  }
   /**
    * Run every guard's `check` for this collection. First throw wins —
    * remaining guards are not invoked. Guards without a `check` skip.
@@ -228,14 +355,21 @@ var GuardExecutor = {
    * Compare existing vs incoming for each `frozenFields.fields` entry
    * when `frozenFields.when(existing)` is true. Throws
    * `FieldFrozenError` listing every changed frozen field.
+   *
+   * @param skipFields — field names that are schema-owned computed fields.
+   *   These are excluded from the comparison because `incoming` carries the
+   *   raw user input (computed fields not yet evaluated), so comparing
+   *   `existing[field]` vs `incoming[field]` would always look like a
+   *   change even when the computed result is unchanged.
    */
-  async checkFrozenFields(guard, id, existing, incoming) {
+  async checkFrozenFields(guard, id, existing, incoming, skipFields) {
     const ff = guard.frozenFields;
     if (!ff) return;
     if (existing === null) return;
     if (!ff.when(existing)) return;
     const changed = [];
     for (const f of ff.fields) {
+      if (skipFields?.has(String(f))) continue;
       if (existing[f] !== incoming[f]) {
         if (!deepEqual(existing[f], incoming[f])) changed.push(String(f));
       }
@@ -289,14 +423,17 @@ function deepEqual(a, b) {
 // src/guards/read-only-facade.ts
 var ReadOnlyVaultFacade = class {
   _vault;
-  constructor(vault) {
+  _layer;
+  constructor(vault, layer = "read") {
     this._vault = vault;
+    this._layer = layer;
   }
   collection(name) {
     const c = this._vault.collection(name);
+    const layer = this._layer;
     return {
-      get: (id) => c.get(id),
-      list: () => c.list(),
+      get: (id) => c.get(id, { _layer: layer }),
+      list: () => c.list({ _layer: layer }),
       query: () => c.query()
     };
   }
@@ -307,9 +444,12 @@ var ReadOnlyVaultFacade = class {
   FieldFrozenError,
   GuardExecutor,
   GuardRegistry,
+  IllegalTransitionError,
   InvariantError,
   ReadOnlyVaultFacade,
   RecordLockedError,
+  immutableGuard,
+  transitionGuard,
   withGuard
 });
 //# sourceMappingURL=index.cjs.map