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

package/dist/i18n/index.d.cts

@@ -1,10 +1,12 @@
-import { I as I18nStrategy } from '../types-DJG8HG6F.cjs';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nTextDescriptor, f as I18nTextOptions, g as applyI18nLocale, h as dictCollectionName, i as dictKey, j as i18nText, k as isDictCollectionName, l as isDictKeyDescriptor, m as isI18nTextDescriptor, r as resolveI18nText, v as validateI18nTextValue } from '../types-DJG8HG6F.cjs';
-export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, T as TranslatorNotConfiguredError } from '../index-BMjrzNZr.cjs';
-import '../lazy-builder-C-rPfWG0.cjs';
-import '../predicate-Dnu81tsS.cjs';
-import '../strategy-DSTrsZ8t.cjs';
+export { I as I18nMap, a as I18nTextDescriptor, b as I18nTextOptions, L as Layer, O as OnMissing, c as OnMissingPolicy, R as ResolveI18nOptions, d as applyI18nLocale, g as getAtPath, i as i18nText, e as isI18nTextDescriptor, r as resolveI18nText, f as resolvePolicy, s as setAtPathInPlace, v as validateI18nTextValue } from '../strategy-WtB-jXYv.cjs';
+import { I as I18nStrategy } from '../types-DyOI6XZ_.cjs';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, S as ScriptWarning, e as StaticDictDescriptor, f as dictCollectionName, g as dictKey, h as enforceScript, i as inferScripts, j as isDictCollectionName, k as isDictKeyDescriptor, l as isStaticDictDescriptor, s as staticDict } from '../types-DyOI6XZ_.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-Dkc_fi-S.cjs';
+import '../lazy-builder-eYZzLEL1.cjs';
+import '../predicate-BmhBSPCH.cjs';
 import '../strategy-BSxFXGzb.cjs';
+import '../index-BMmajblo.cjs';
+import '../index-tZqVB9g5.cjs';
 import '@noy-db/attestation';
 
 /**

package/dist/i18n/index.d.ts

@@ -1,10 +1,12 @@
-import { I as I18nStrategy } from '../types-BoFFiskX.js';
-export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, e as I18nTextDescriptor, f as I18nTextOptions, g as applyI18nLocale, h as dictCollectionName, i as dictKey, j as i18nText, k as isDictCollectionName, l as isDictKeyDescriptor, m as isI18nTextDescriptor, r as resolveI18nText, v as validateI18nTextValue } from '../types-BoFFiskX.js';
-export { D as DictKeyInUseError, a as DictKeyMissingError, L as LocaleNotSpecifiedError, M as MissingTranslationError, R as ReservedCollectionNameError, T as TranslatorNotConfiguredError } from '../index-BCKdioeh.js';
-import '../lazy-builder-Rpd-V3jP.js';
-import '../predicate-Dnu81tsS.js';
-import '../strategy-DSTrsZ8t.js';
+export { I as I18nMap, a as I18nTextDescriptor, b as I18nTextOptions, L as Layer, O as OnMissing, c as OnMissingPolicy, R as ResolveI18nOptions, d as applyI18nLocale, g as getAtPath, i as i18nText, e as isI18nTextDescriptor, r as resolveI18nText, f as resolvePolicy, s as setAtPathInPlace, v as validateI18nTextValue } from '../strategy-54eIwox5.js';
+import { I as I18nStrategy } from '../types-DLfWFr6U.js';
+export { D as DICT_COLLECTION_PREFIX, a as DictEntry, b as DictKeyDescriptor, c as DictionaryHandle, d as DictionaryOptions, S as ScriptWarning, e as StaticDictDescriptor, f as dictCollectionName, g as dictKey, h as enforceScript, i as inferScripts, j as isDictCollectionName, k as isDictKeyDescriptor, l as isStaticDictDescriptor, s as staticDict } from '../types-DLfWFr6U.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-Dkc_fi-S.js';
+import '../lazy-builder-ChSqcF5t.js';
+import '../predicate-BmhBSPCH.js';
 import '../strategy-BSxFXGzb.js';
+import '../index-BMmajblo.js';
+import '../index-Bm9hIY7t.js';
 import '@noy-db/attestation';
 
 /**

package/dist/i18n/index.js

@@ -1,36 +1,47 @@
-import {
-  applyI18nLocale,
-  i18nText,
-  isI18nTextDescriptor,
-  resolveI18nText,
-  validateI18nTextValue
-} from "../chunk-3XHOCQK4.js";
 import {
   DICT_COLLECTION_PREFIX,
   DictionaryHandle,
   dictCollectionName,
   dictKey,
   isDictCollectionName,
-  isDictKeyDescriptor
-} from "../chunk-LRAZDV5X.js";
-import "../chunk-Q6W2CMEJ.js";
-import "../chunk-XG3PTSCD.js";
-import "../chunk-YS3POABP.js";
-import "../chunk-2PAQNPE3.js";
+  isDictKeyDescriptor,
+  isStaticDictDescriptor,
+  staticDict
+} from "../chunk-O5XKZCUD.js";
+import {
+  applyI18nLocale,
+  enforceScript,
+  getAtPath,
+  i18nText,
+  inferScripts,
+  isI18nTextDescriptor,
+  resolveI18nText,
+  resolvePolicy,
+  setAtPathInPlace,
+  validateI18nTextValue
+} from "../chunk-TNH5SLCD.js";
+import "../chunk-FRRJIUSI.js";
+import "../chunk-PDVP3C2I.js";
+import "../chunk-TA6HPKWQ.js";
+import "../chunk-37VGJM3T.js";
 import {
   DictKeyInUseError,
   DictKeyMissingError,
   LocaleNotSpecifiedError,
   MissingTranslationError,
   ReservedCollectionNameError,
-  TranslatorNotConfiguredError
-} from "../chunk-W3XXT26A.js";
+  ScriptViolationError,
+  StaticDictReadonlyError,
+  TranslatorNotConfiguredError,
+  UnknownDictCodeError
+} from "../chunk-OTWT6BAJ.js";
 
 // src/i18n/active.ts
 function withI18n() {
   return {
     applyI18nLocale,
     validateI18nTextValue,
+    enforceScript,
     buildDictionaryHandle(opts) {
       return new DictionaryHandle(
         opts.adapter,
@@ -55,15 +66,25 @@ export {
   LocaleNotSpecifiedError,
   MissingTranslationError,
   ReservedCollectionNameError,
+  ScriptViolationError,
+  StaticDictReadonlyError,
   TranslatorNotConfiguredError,
+  UnknownDictCodeError,
   applyI18nLocale,
   dictCollectionName,
   dictKey,
+  enforceScript,
+  getAtPath,
   i18nText,
+  inferScripts,
   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 { DictionaryHandle } from './dictionary.js'\n\nexport function withI18n(): I18nStrategy {\n  return {\n    applyI18nLocale,\n    validateI18nTextValue,\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+BO,SAAS,WAAyB;AACvC,SAAO;AAAA,IACL;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/index-BMmajblo.d.cts

@@ -0,0 +1,362 @@
+/**
+ * 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[];
+    /**
+     * Count of persisted `_idx/<field>/<recordId>` index side-cars hard-deleted
+     * across the shredded records (#401). These live under the retained
+     * collection DEK, so crypto-shred alone would leave the indexed field VALUES
+     * readable — `forget()` must delete them.
+     */
+    readonly indexPostingsPurged: number;
+    /**
+     * `collection:id:field` entries whose persisted `_idx` side-car could NOT be
+     * deleted (#401) — index residue that still leaks the indexed value under the
+     * retained collection DEK. Non-empty means erasure is INCOMPLETE: retry, or
+     * purge the side-car out of band.
+     */
+    readonly indexResidue: 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 };