@noy-db/hub 0.2.0-pre.16 → 0.2.0-pre.17

package/dist/i18n/index.d.cts

@@ -1,10 +1,12 @@
-import { I as I18nStrategy } from '../types-Bze6vkwm.cjs';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nMap, f as I18nTextDescriptor, g as I18nTextOptions, L as Layer, O as OnMissing, h as OnMissingPolicy, R as ResolveI18nOptions, S as ScriptWarning, i as applyI18nLocale, j as dictCollectionName, k as dictKey, l as enforceScript, m as getAtPath, n as i18nText, o as inferScripts, p as isDictCollectionName, q as isDictKeyDescriptor, r as isI18nTextDescriptor, s as resolveI18nText, t as resolvePolicy, u as setAtPathInPlace, v as validateI18nTextValue } from '../types-Bze6vkwm.cjs';
-export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, T as TranslatorNotConfiguredError } from '../strategy-BtW8fAjz.cjs';
+import { I as I18nStrategy } from '../types-CrSpRDuG.cjs';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nMap, f as I18nTextDescriptor, g as I18nTextOptions, L as Layer, O as OnMissing, h as OnMissingPolicy, R as ResolveI18nOptions, S as ScriptWarning, i as StaticDictDescriptor, j as applyI18nLocale, k as dictCollectionName, l as dictKey, m as enforceScript, n as getAtPath, o as i18nText, p as inferScripts, q as isDictCollectionName, r as isDictKeyDescriptor, s as isI18nTextDescriptor, t as isStaticDictDescriptor, u as resolveI18nText, v as resolvePolicy, w as setAtPathInPlace, x as staticDict, y as validateI18nTextValue } from '../types-CrSpRDuG.cjs';
+export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-Dz64FA65.cjs';
 import '../lazy-builder-eYZzLEL1.cjs';
 import '../predicate-BmhBSPCH.cjs';
+import '../strategy-CLC1j79g.cjs';
 import '../strategy-BSxFXGzb.cjs';
-import '../index-C8Bk3-VF.cjs';
+import '../index-C-SSRIxP.cjs';
+import '../index-u-kWzSrL.cjs';
 import '@noy-db/attestation';
 
 /**

package/dist/i18n/index.d.ts

@@ -1,10 +1,12 @@
-import { I as I18nStrategy } from '../types-DrmBTscX.js';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nMap, f as I18nTextDescriptor, g as I18nTextOptions, L as Layer, O as OnMissing, h as OnMissingPolicy, R as ResolveI18nOptions, S as ScriptWarning, i as applyI18nLocale, j as dictCollectionName, k as dictKey, l as enforceScript, m as getAtPath, n as i18nText, o as inferScripts, p as isDictCollectionName, q as isDictKeyDescriptor, r as isI18nTextDescriptor, s as resolveI18nText, t as resolvePolicy, u as setAtPathInPlace, v as validateI18nTextValue } from '../types-DrmBTscX.js';
-export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, T as TranslatorNotConfiguredError } from '../strategy-BtW8fAjz.js';
+import { I as I18nStrategy } from '../types-CljIHm_J.js';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nMap, f as I18nTextDescriptor, g as I18nTextOptions, L as Layer, O as OnMissing, h as OnMissingPolicy, R as ResolveI18nOptions, S as ScriptWarning, i as StaticDictDescriptor, j as applyI18nLocale, k as dictCollectionName, l as dictKey, m as enforceScript, n as getAtPath, o as i18nText, p as inferScripts, q as isDictCollectionName, r as isDictKeyDescriptor, s as isI18nTextDescriptor, t as isStaticDictDescriptor, u as resolveI18nText, v as resolvePolicy, w as setAtPathInPlace, x as staticDict, y as validateI18nTextValue } from '../types-CljIHm_J.js';
+export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, S as ScriptViolationError, b as StaticDictReadonlyError, T as TranslatorNotConfiguredError, U as UnknownDictCodeError } from '../errors-Dz64FA65.js';
 import '../lazy-builder-ChSqcF5t.js';
 import '../predicate-BmhBSPCH.js';
+import '../strategy-4M9jo172.js';
 import '../strategy-BSxFXGzb.js';
-import '../index-nP99bXLg.js';
+import '../index-C-SSRIxP.js';
+import '../index-DpU6KWof.js';
 import '@noy-db/attestation';
 
 /**

package/dist/i18n/index.js

@@ -1,7 +1,7 @@
 import {
   enforceScript,
   inferScripts
-} from "../chunk-AAVWKNZW.js";
+} from "../chunk-JDWE6JMX.js";
 import {
   DICT_COLLECTION_PREFIX,
   DictionaryHandle,
@@ -13,15 +13,17 @@ import {
   isDictCollectionName,
   isDictKeyDescriptor,
   isI18nTextDescriptor,
+  isStaticDictDescriptor,
   resolveI18nText,
   resolvePolicy,
   setAtPathInPlace,
+  staticDict,
   validateI18nTextValue
-} from "../chunk-7BQ4QWYX.js";
-import "../chunk-6H2ZUNR7.js";
-import "../chunk-Z6FNBOTC.js";
-import "../chunk-F3BPIPLS.js";
-import "../chunk-YULZKK4F.js";
+} from "../chunk-ROPJVUG3.js";
+import "../chunk-BSZOCSDZ.js";
+import "../chunk-PDVP3C2I.js";
+import "../chunk-SISBMAPO.js";
+import "../chunk-UNTGHX5A.js";
 import {
   DictKeyInUseError,
   DictKeyMissingError,
@@ -29,8 +31,10 @@ import {
   MissingTranslationError,
   ReservedCollectionNameError,
   ScriptViolationError,
-  TranslatorNotConfiguredError
-} from "../chunk-535SSHBS.js";
+  StaticDictReadonlyError,
+  TranslatorNotConfiguredError,
+  UnknownDictCodeError
+} from "../chunk-ZEGSDPB7.js";
 
 // src/i18n/active.ts
 function withI18n() {
@@ -63,7 +67,9 @@ export {
   MissingTranslationError,
   ReservedCollectionNameError,
   ScriptViolationError,
+  StaticDictReadonlyError,
   TranslatorNotConfiguredError,
+  UnknownDictCodeError,
   applyI18nLocale,
   dictCollectionName,
   dictKey,
@@ -74,9 +80,11 @@ export {
   isDictCollectionName,
   isDictKeyDescriptor,
   isI18nTextDescriptor,
+  isStaticDictDescriptor,
   resolveI18nText,
   resolvePolicy,
   setAtPathInPlace,
+  staticDict,
   validateI18nTextValue,
   withI18n
 };

package/dist/i18n/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/i18n/active.ts"],"sourcesContent":["/**\n * Active i18n strategy — `withI18n()` returns the real implementation\n * that wires multi-locale resolution, i18nText validation, and the\n * `DictionaryHandle` for `dictKey` fields into the core read/write\n * paths.\n *\n * Consumers opt in by:\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withI18n } from '@noy-db/hub/i18n'\n *\n * const db = await createNoydb({\n *   store: ...,\n *   user: ...,\n *   i18nStrategy: withI18n(),\n * })\n * ```\n *\n * The factory delegates to the existing `core.ts` and `dictionary.ts`\n * modules. Splitting the import chain through this file is what lets\n * tsup tree-shake the `~854 LOC` of dictionary + locale resolution\n * out of the default bundle when no `withI18n()` import is present.\n *\n * @public\n */\n\nimport type { I18nStrategy, BuildDictionaryHandleOptions } from './strategy.js'\nimport { applyI18nLocale, validateI18nTextValue } from './core.js'\nimport { enforceScript } from './script.js'\nimport { DictionaryHandle } from './dictionary.js'\n\nexport function withI18n(): I18nStrategy {\n  return {\n    applyI18nLocale,\n    validateI18nTextValue,\n    enforceScript,\n    buildDictionaryHandle<Keys extends string = string>(\n      opts: BuildDictionaryHandleOptions<Keys>,\n    ): DictionaryHandle<Keys> {\n      return new DictionaryHandle<Keys>(\n        opts.adapter,\n        opts.compartmentName,\n        opts.dictionaryName,\n        opts.keyring,\n        opts.getDEK,\n        opts.encrypted,\n        opts.ledger,\n        opts.options,\n        opts.findAndUpdateReferences,\n        opts.emitter,\n      )\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCO,SAAS,WAAyB;AACvC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA,sBACE,MACwB;AACxB,aAAO,IAAI;AAAA,QACT,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,MACP;AAAA,IACF;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../../src/i18n/active.ts"],"sourcesContent":["/**\n * Active i18n strategy — `withI18n()` returns the real implementation\n * that wires multi-locale resolution, i18nText validation, and the\n * `DictionaryHandle` for `dictKey` fields into the core read/write\n * paths.\n *\n * Consumers opt in by:\n *\n * ```ts\n * import { createNoydb } from '@noy-db/hub'\n * import { withI18n } from '@noy-db/hub/i18n'\n *\n * const db = await createNoydb({\n *   store: ...,\n *   user: ...,\n *   i18nStrategy: withI18n(),\n * })\n * ```\n *\n * The factory delegates to the existing `core.ts` and `dictionary.ts`\n * modules. Splitting the import chain through this file is what lets\n * tsup tree-shake the `~854 LOC` of dictionary + locale resolution\n * out of the default bundle when no `withI18n()` import is present.\n *\n * @public\n */\n\nimport type { I18nStrategy, BuildDictionaryHandleOptions } from './strategy.js'\nimport { applyI18nLocale, validateI18nTextValue } from './core.js'\nimport { enforceScript } from './script.js'\nimport { DictionaryHandle } from './dictionary.js'\n\nexport function withI18n(): I18nStrategy {\n  return {\n    applyI18nLocale,\n    validateI18nTextValue,\n    enforceScript,\n    buildDictionaryHandle<Keys extends string = string>(\n      opts: BuildDictionaryHandleOptions<Keys>,\n    ): DictionaryHandle<Keys> {\n      return new DictionaryHandle<Keys>(\n        opts.adapter,\n        opts.compartmentName,\n        opts.dictionaryName,\n        opts.keyring,\n        opts.getDEK,\n        opts.encrypted,\n        opts.ledger,\n        opts.options,\n        opts.findAndUpdateReferences,\n        opts.emitter,\n      )\n    },\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgCO,SAAS,WAAyB;AACvC,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA;AAAA,IACA,sBACE,MACwB;AACxB,aAAO,IAAI;AAAA,QACT,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,QACL,KAAK;AAAA,MACP;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/{immutable-guard-Dov3WvwF.d.ts → immutable-guard-B5M95nbq.d.ts}

@@ -1,4 +1,4 @@
-import { as as GuardStrategy, aw as GuardStrategyHandle, at as GuardChange, au as GuardContext } from './types-DrmBTscX.js';
+import { av as GuardStrategy, az as GuardStrategyHandle, aw as GuardChange, ax as GuardContext } from './types-CljIHm_J.js';
 
 /**
  * Register a guard for a collection. Guards run on every `put()` /

package/dist/{immutable-guard-CRPvu24K.d.cts → immutable-guard-qN3zF8o1.d.cts}

@@ -1,4 +1,4 @@
-import { as as GuardStrategy, aw as GuardStrategyHandle, at as GuardChange, au as GuardContext } from './types-Bze6vkwm.cjs';
+import { av as GuardStrategy, az as GuardStrategyHandle, aw as GuardChange, ax as GuardContext } from './types-CrSpRDuG.cjs';
 
 /**
  * Register a guard for a collection. Guards run on every `put()` /

package/dist/index-C-SSRIxP.d.cts

@@ -0,0 +1,348 @@
+/**
+ * Ledger entry shape + canonical JSON + sha256 helpers.
+ *
+ * This file holds the PURE primitives used by the hash-chained ledger:
+ * the entry type, the deterministic (sort-stable) JSON encoder, and
+ * the sha256 hasher that produces `prevHash` and `ledger.head()`.
+ *
+ * Everything here is validator-free and side-effect free — the only
+ * runtime dep is Web Crypto's `subtle.digest` for the sha256 call,
+ * which we already use for every other hashing operation in the core.
+ *
+ * The hash chain property works like this:
+ *
+ *   hash(entry[i])       = sha256(canonicalJSON(entry[i]))
+ *   entry[i+1].prevHash  = hash(entry[i])
+ *
+ * Any modification to `entry[i]` (field values, field order, whitespace)
+ * produces a different `hash(entry[i])`, which means `entry[i+1]`'s
+ * stored `prevHash` no longer matches the recomputed hash, which means
+ * `verify()` returns `{ ok: false, divergedAt: i + 1 }`. The chain is
+ * append-only and tamper-evident without external anchoring.
+ */
+/**
+ * A single ledger entry in its plaintext form — what gets serialized,
+ * hashed, and then encrypted with the ledger DEK before being written
+ * to the `_ledger/` adapter collection.
+ *
+ * ## Why hash the ciphertext, not the plaintext?
+ *
+ * `payloadHash` is the sha256 of the record's ENCRYPTED envelope bytes,
+ * not its plaintext. This matters:
+ *
+ *   1. **Zero-knowledge preserved.** A user (or a third party) can
+ *      verify the ledger against the stored envelopes without any
+ *      decryption keys. The adapter layer already holds only
+ *      ciphertext, so hashing the ciphertext keeps the ledger at the
+ *      same privacy level as the adapter.
+ *
+ *   2. **Determinism.** Plaintext → ciphertext is randomized by the
+ *      fresh per-write IV, so `hash(plaintext)` would need extra
+ *      normalization. `hash(ciphertext)` is already deterministic and
+ *      unique per write.
+ *
+ *   3. **Detection property.** If an attacker modifies even one byte of
+ *      the stored ciphertext (trying to flip a record), the hash
+ *      changes, the ledger's recorded `payloadHash` no longer matches,
+ *      and a data-integrity check fails. We don't do that check in
+ *      `verify()` today, but the
+ *      hook is there for a future `verifyIntegrity()` follow-up.
+ *
+ * Fields marked `op`, `collection`, `id`, `version`, `ts`, `actor` are
+ * plaintext METADATA about the operation — NOT the record itself. The
+ * entry is still encrypted at rest via the ledger DEK, but adapters
+ * could theoretically infer operation patterns from the sizes and
+ * timestamps. This is an accepted trade-off for the tamper-evidence
+ * property; full ORAM-level privacy is out of scope for noy-db.
+ */
+interface LedgerEntry {
+    /**
+     * Zero-based sequential position of this entry in the chain. The
+     * canonical adapter key is this number zero-padded to 10 digits
+     * (`"0000000001"`) so lexicographic ordering matches numeric order.
+     */
+    readonly index: number;
+    /**
+     * Hex-encoded sha256 of the canonical JSON of the PREVIOUS entry.
+     * The genesis entry (index 0) has `prevHash === ''` — the first
+     * entry in a fresh vault has nothing to point back to.
+     */
+    readonly prevHash: string;
+    /**
+     * Which kind of mutation this entry records. only supports
+     * data operations (`put`, `delete`, `amendment`). Access-control
+     * operations (`grant`, `revoke`, `rotate`) will be added in a
+     * follow-up once the keyring write path is instrumented — that's
+     * tracked in the epic issue.
+     *
+     * `'amendment'` is the multi-record audit entry written by the
+     * guards subsystem when an admin/owner uses `withTransactions(...)`
+     * to repair a constraint-violating state. See `amendment` field
+     * below for the structured payload.
+     *
+     * `'lifecycle'` records a non-data audit event (e.g. partition
+     * handover) — `collection`/`id` are empty and the event detail
+     * lives in `reason` (e.g. `'partition-handed-over:<sealId>'`). Like
+     * `amendment`, it carries no data envelope, so `verifyBackupIntegrity`
+     * skips it in the data cross-check (it still participates in the
+     * tamper-evident chain).
+     *
+     * `'forget'` is the single summary entry written by `vault.forget()`
+     * (#304 GDPR crypto-shred). `collection`/`id` are empty and `version`
+     * is 0 — a forget is not scoped to one record. `payloadHash` carries
+     * `sha256Hex(subjectId)` so the ledger PROVES "subject X existed and
+     * was erased on date D" without retaining the subject id or any
+     * plaintext; `reason` holds a JSON summary of the shred counts. Like
+     * `amendment`/`lifecycle` it carries no data envelope and is skipped
+     * by the reconstruct walker (it still participates in the chain, so
+     * `verify()` passes after a shred).
+     */
+    readonly op: 'put' | 'delete' | 'amendment' | 'lifecycle' | 'migration' | 'forget';
+    /** The collection the mutation targeted. */
+    readonly collection: string;
+    /** The record id the mutation targeted. */
+    readonly id: string;
+    /**
+     * The record version AFTER this mutation. For `put` this is the
+     * newly assigned version; for `delete` this is the version that
+     * was deleted (the last version visible to reads).
+     */
+    readonly version: number;
+    /** ISO timestamp of the mutation. */
+    readonly ts: string;
+    /** User id of the actor who performed the mutation. */
+    readonly actor: string;
+    /**
+     * Hex-encoded sha256 of the encrypted envelope's `_data` field.
+     * For `put`, this is the hash of the new ciphertext. For `delete`,
+     * it's the hash of the last visible ciphertext at deletion time,
+     * or the empty string if nothing was there to delete. Hashing the
+     * ciphertext (not the plaintext) preserves zero-knowledge — see
+     * the file docstring.
+     */
+    readonly payloadHash: string;
+    /**
+     * Optional human-readable tag describing why this mutation happened.
+     * Threaded through `collection.put(_, _, { reason })`. Common
+     * values include `'import:csv'`, `'import:json'`, `'import:xlsx'` from
+     * `as-*` ImportPlan.apply(), but consumers can use any string for
+     * domain-specific audit filtering. Auto-strip via `canonicalJson` —
+     * absent on the wire, never serialized as `null`.
+     *
+     * Audit consumers filter: `entries.filter(e => e.reason?.startsWith('import:'))`.
+     */
+    readonly reason?: string;
+    /**
+     * Optional hex-encoded sha256 of the encrypted JSON Patch delta
+     * blob stored alongside this entry in `_ledger_deltas/`. Present
+     * only for `put` operations that had a previous version — the
+     * genesis put of a new record, and every `delete`, leave this
+     * field undefined.
+     *
+     * The delta payload itself lives in a sibling internal collection
+     * (`_ledger_deltas/<paddedIndex>`) and is encrypted with the
+     * ledger DEK. Callers use `ledger.loadDelta(index)` to decrypt and
+     * deserialize it when reconstructing a historical version.
+     *
+     * Why optional instead of always-present: the first put of a
+     * record has no previous version to diff against, so storing an
+     * empty patch would be noise. For deletes there's no "next" state
+     * to describe with a delta. Both cases set this field to undefined.
+     *
+     * Note: the canonical-JSON hasher treats `undefined` as invalid
+     * (it's one of the guard rails), so on the wire this field is
+     * either `{ deltaHash: '<hex>' }` or absent from the JSON
+     * entirely — never `{ deltaHash: undefined }`.
+     */
+    readonly deltaHash?: string;
+    /**
+     * Present only when `op === 'amendment'`. Records the human reason,
+     * the role of the actor, the (collection, id, vBefore, vAfter) tuple
+     * for every record touched, and which guard invariants passed.
+     *
+     * See docs/superpowers/specs/2026-05-18-guards-design.md.
+     */
+    readonly amendment?: {
+        readonly reason: string;
+        readonly role: 'admin' | 'owner';
+        readonly changes: ReadonlyArray<{
+            readonly collection: string;
+            readonly id: string;
+            readonly vBefore: number;
+            readonly vAfter: number;
+        }>;
+        readonly invariantsPassed: ReadonlyArray<string>;
+    };
+}
+/**
+ * Canonical (sort-stable) JSON encoder.
+ *
+ * This function is the load-bearing primitive of the hash chain:
+ * `sha256(canonicalJSON(entry))` must produce the same hex string
+ * every time, on every machine, for the same logical entry — otherwise
+ * `verify()` would return `{ ok: false }` on cross-platform reads.
+ *
+ * JavaScript's `JSON.stringify` is almost canonical, but NOT quite:
+ * it preserves the insertion order of object keys, which means
+ * `{a:1,b:2}` and `{b:2,a:1}` serialize differently. We fix this by
+ * recursively walking objects and sorting their keys before
+ * concatenation.
+ *
+ * Arrays keep their original order (reordering them would change
+ * semantics). Numbers, strings, booleans, and `null` use the default
+ * JSON encoding. `undefined` and functions are rejected — ledger
+ * entries are plain data, and silently dropping `undefined` would
+ * break the "same input → same hash" property if a caller forgot to
+ * omit a field.
+ *
+ * Performance: one pass per nesting level; O(n log n) for key sorting
+ * at each object. Entries are small (< 1 KB) so this is negligible
+ * compared to the sha256 call.
+ */
+declare function canonicalJson(value: unknown): string;
+/**
+ * Compute a hex-encoded sha256 of a string via Web Crypto's subtle API.
+ *
+ * We use hex (not base64) for hashes because hex is case-insensitive,
+ * fixed-length (64 chars), and easier to compare visually in debug
+ * output. Base64 would save a few bytes in storage but every encrypted
+ * ledger entry is already much larger than the hash itself.
+ */
+declare function sha256Hex(input: string): Promise<string>;
+/**
+ * Compute the canonical hash of a ledger entry. Short wrapper around
+ * `canonicalJson` + `sha256Hex`; callers use this instead of composing
+ * the two functions every time, so any future change to the hashing
+ * pipeline (e.g., adding a domain-separation prefix) lives in one place.
+ */
+declare function hashEntry(entry: LedgerEntry): Promise<string>;
+/**
+ * Pad an index to the canonical 10-digit form used as the adapter key.
+ * Ten digits is enough for ~10 billion ledger entries per vault
+ * — far beyond any realistic use case, but cheap enough that the extra
+ * digits don't hurt storage.
+ */
+declare function paddedIndex(index: number): string;
+/** Parse a padded adapter key back into a number. Returns NaN on malformed input. */
+declare function parseIndex(key: string): number;
+
+/**
+ * `withForgetCascade` — declaration surface for GDPR right-to-erasure via
+ * per-record CEK crypto-shred (#304, step 2 of the CEK security epic).
+ *
+ * This file holds only the *declaration* shape and the disabled sentinel.
+ * The actual erasure machinery lives in:
+ *   - `subject-index.ts` — the encrypted `_subject_index` reserved collection
+ *   - `vault.ts` `forget()` — the per-record tombstone + ledger flow
+ *   - `collection.ts` `_writeTombstone` — the envelope rewrite
+ *
+ * A `ForgetStrategy` declares which collections carry erasable subject data
+ * and the (dotted-path) field on each record that names the data subject.
+ * Declaring a collection here ALSO forces `perRecordKeys: true` for it (a
+ * shred can only erase a record whose body is keyed off a per-record CEK),
+ * so adopters opt into the CEK foundation transitively.
+ *
+ * @module
+ */
+
+/**
+ * User-supplied declaration passed to {@link withForgetCascade}. Maps a
+ * collection name to the record field (dotted path supported, e.g.
+ * `'billing.buyerId'`) that identifies the data subject for erasure.
+ *
+ * ```ts
+ * withForgetCascade({ subjects: { invoices: 'buyerId', contacts: 'id' } })
+ * ```
+ */
+interface SubjectDeclaration {
+    readonly subjects: Record<string, string>;
+}
+/**
+ * Resolved forget strategy threaded through Noydb → every Vault. Carries
+ * the same `subjects` map the user declared. `NO_FORGET` (empty map) is the
+ * off-by-default sentinel; `vault.forget()` throws
+ * `ForgetStrategyNotConfiguredError` when the map is empty.
+ */
+interface ForgetStrategy {
+    /** Collection → subject-field (dotted path). Empty under `NO_FORGET`. */
+    readonly subjects: Readonly<Record<string, string>>;
+}
+/**
+ * Disabled sentinel — no collections declare a subject field. `vault.forget()`
+ * refuses with `ForgetStrategyNotConfiguredError`; no write hooks register; no
+ * collection is forced into `perRecordKeys`. Non-adopters pay nothing.
+ */
+declare const NO_FORGET: ForgetStrategy;
+/**
+ * Declare GDPR crypto-shred for one or more collections.
+ *
+ * Each declared collection is forced to `perRecordKeys: true` (a shred can
+ * only guarantee erasure of a record whose body is keyed off a per-record
+ * CEK). On write, Noydb extracts `record[subjectField]` and maintains an
+ * encrypted `_subject_index` mapping `subject → [{collection, id}]`, so
+ * `vault.forget(subjectId)` can find every record for a subject and rewrite
+ * each to a tombstone (body + history permanently undecryptable) while the
+ * collection DEK and every other record stay intact.
+ *
+ * @example
+ * ```ts
+ * createNoydb({
+ *   secret, user,
+ *   forgetStrategy: withForgetCascade({ subjects: { invoices: 'buyerId' } }),
+ * })
+ * const result = await vault.forget('buyer-123')
+ * // → { subject, recordsShredded, historyVersionsShredded, collections, … }
+ * ```
+ */
+declare function withForgetCascade(opts: SubjectDeclaration): ForgetStrategy;
+/**
+ * The outcome of a `vault.forget(subjectId)` call.
+ *
+ * `unmigratedRecords` lists `collection:id` pairs that were tombstoned but
+ * whose body had NOT been migrated to a per-record CEK at shred time (legacy
+ * body still under the shared collection DEK). Those records are tombstoned
+ * (live envelope + history stripped) but their pre-shred ciphertext, if it
+ * leaked into a backup before migration, remains decryptable under the
+ * collection DEK — so erasure-completeness is NOT guaranteed for them. Run
+ * the per-record-CEK migration pass, then re-forget, to close the gap.
+ *
+ * Blob attachments (#365): a shredded record's **erasable** blobs (on a
+ * `perRecordKeys` collection) are crypto-shredded inline — `blobsShredded`
+ * counts those taken to refCount 0 (BlobObject deleted → chunks permanently
+ * undecryptable), `blobsRetainedShared` counts those still referenced by
+ * another record (shared content legitimately persists for its other owner).
+ * `blobResidueCollections` now lists only collections with blobs that could
+ * NOT be crypto-shredded: **legacy** blobs (no per-blob `_cek`, chunks under
+ * the shared `_blob` DEK — migrate them), or a session without the blob
+ * subsystem loaded. An all-erasable subject yields an empty residue list.
+ */
+interface ForgetResult {
+    /** The subject id passed to `forget()`. Echoed for caller convenience. */
+    readonly subject: string;
+    /** Count of live records rewritten to a tombstone. */
+    readonly recordsShredded: number;
+    /** Count of `_history` envelopes tombstoned across all shredded records. */
+    readonly historyVersionsShredded: number;
+    /** Distinct collections that had at least one record shredded. */
+    readonly collections: readonly string[];
+    /** `collection:id` pairs shredded while still un-migrated (see type docs). */
+    readonly unmigratedRecords: readonly string[];
+    /** Count of erasable blobs crypto-shredded (refCount → 0, BlobObject deleted). */
+    readonly blobsShredded: number;
+    /** Count of erasable blobs retained because still referenced elsewhere (shared). */
+    readonly blobsRetainedShared: number;
+    /** Collections with blobs that could NOT be crypto-shredded — legacy (no `_cek`) or blobs disabled (see type docs). */
+    readonly blobResidueCollections: readonly string[];
+    /** The single `op:'forget'` ledger entry appended for this erasure. */
+    readonly ledgerEntry: LedgerEntry;
+}
+
+/** Reserved collection holding the encrypted subject → records index. */
+declare const SUBJECT_INDEX_COLLECTION = "_subject_index";
+/** A single record reference held in a subject's index entry. */
+interface SubjectRef {
+    readonly collection: string;
+    readonly id: string;
+}
+
+export { type ForgetStrategy as F, type LedgerEntry as L, NO_FORGET as N, type SubjectRef as S, parseIndex as a, type ForgetResult as b, canonicalJson as c, SUBJECT_INDEX_COLLECTION as d, type SubjectDeclaration as e, hashEntry as h, paddedIndex as p, sha256Hex as s, withForgetCascade as w };