@noy-db/hub 0.3.0-pre.8 → 0.3.0

package/dist/kernel/collection.d.ts

@@ -0,0 +1,1522 @@
+import type { EncryptedEnvelope, HistoryOptions, HistoryEntry, PruneOptions, LocaleReadOptions, PutManyItemOptions, PutManyOptions, PutManyResult, DeleteManyResult, SealedView, ClassifiedVerdict } from './types.js';
+import type { FieldMeta } from '../with-shape/introspection/field-meta.js';
+import type { CollectionMeta } from '../with-shape/introspection/meta.js';
+import { type ClassifiedEntry } from '../port/with/classified-strategy.js';
+import type { CrdtState } from '../with-commit/crdt/crdt.js';
+import type { I18nTextDescriptor, DictKeyDescriptor, StaticDictDescriptor, DictionaryHandle } from '../port/with/i18n-strategy.js';
+import type { LookupDescriptor } from '../port/with/lookup-strategy.js';
+import { ViaPipeline } from './via/pipeline.js';
+import { type ViaDescriptor, type ViaEraseReport } from './via/index.js';
+import type { MutationOrigin } from './mutation.js';
+import { type WaveContext, type RollupOutcome, type RollupDeleteIntent } from './via/dispatch.js';
+import type { ComputedFields } from '../with-formula/computed/index.js';
+import { type SealedShredSlot } from './enclave/index.js';
+import { type TierMoveResult } from '../with-audit/tiers/index.js';
+import type { GhostRecord } from './types.js';
+import type { StandardSchemaV1 } from './schema.js';
+import type { DiffEntry } from '../with-commit/history/diff.js';
+import { Query, ScanBuilder } from './query/index.js';
+import type { JoinableSource } from './query/index.js';
+import type { CollectionIndexes } from '../with-lookup/indexing/eager-indexes.js';
+import { LazyQuery } from '../with-lookup/indexing/lazy-builder.js';
+import type { SearchOptions, SearchResult } from '../with-lookup/search/index.js';
+import type { RetrieveOptions, RetrieveHit } from '../with-lookup/search/retrieve-types.js';
+import { type CollectionDescription, type DescribeOptions } from '../with-shape/introspection/describe.js';
+import type { CollectionConfig } from '../with-shape/introspection/types.js';
+import { type LruStats } from './cache/index.js';
+import type { PresenceHandle } from '../with-party/team/presence.js';
+import type { BlobSet } from '../with-shape/blobs/blob-set.js';
+import type { TxContext } from '../with-commit/tx/transaction.js';
+import { type CollectionOpts } from './collection-config.js';
+/**
+ * Callback for dirty tracking (sync engine integration). `action: 'revert'`
+ * (spec #591) means "un-dirty" — the fan-out wiring in `noydb.ts` routes it
+ * to `SyncEngine.removeDirty` instead of `trackChange`; `version` is unused
+ * for that action.
+ */
+export type OnDirtyCallback = (collection: string, id: string, action: 'put' | 'delete' | 'revert', version: number) => Promise<void>;
+/**
+ * Event delivered to a `collection.subscribe()` callback. Distinct
+ * from the hub-level `ChangeEvent` — this one is bound to a single
+ * collection's type `T` and hydrates the record from cache on put.
+ *
+ * - `type: 'put'` — `record` is the current decrypted value, or
+ *   `null` in the rare case where another op deleted the record
+ *   between the emit and the handler firing.
+ * - `type: 'delete'` — `record` is always `null`; the deletion is
+ *   the only information.
+ */
+export interface CollectionChangeEvent<T> {
+    readonly type: 'put' | 'delete';
+    readonly id: string;
+    readonly record: T | null;
+}
+/**
+ * Per-collection cache configuration. Only meaningful when paired with
+ * `prefetch: false` (lazy mode); eager mode keeps the entire decrypted
+ * cache in memory and ignores these bounds.
+ */
+export interface CacheOptions {
+    /** Maximum number of records to keep in memory before LRU eviction. */
+    maxRecords?: number;
+    /**
+     * Maximum total decrypted byte size before LRU eviction. Accepts a raw
+     * number or a human-friendly string: `'50KB'`, `'50MB'`, `'1GB'`.
+     * Eviction picks the least-recently-used entry until both budgets
+     * (maxRecords AND maxBytes, if both are set) are satisfied.
+     */
+    maxBytes?: number | string;
+}
+/** Statistics exposed via `Collection.cacheStats()`. */
+export interface CacheStats extends LruStats {
+    /** True if this collection is in lazy mode. */
+    lazy: boolean;
+}
+/** A typed collection of records within a vault. */
+export declare class Collection<T, S extends keyof T = never, Q extends keyof T & string = never, M extends keyof T & string = never> {
+    #private;
+    private readonly adapter;
+    private readonly vault;
+    private readonly name;
+    private readonly keyring;
+    private readonly storeCiphertext;
+    private readonly ramCiphertext;
+    private readonly emitter;
+    private readonly writeQueue;
+    private readonly schemaUpdateGate;
+    private readonly schemaFence;
+    private readonly writeHooks;
+    private readonly subsystemBus;
+    private readonly activeTxId;
+    private readonly getDEK;
+    private readonly onDirty;
+    /** #693: live check — true when multi-tab write-propagation is active; gates the #606 marker-id-set fallback read. */
+    private readonly tabCoordinated;
+    private readonly historyConfig;
+    /** True when the caller explicitly provided a `historyConfig` option (vs. inheriting the vault default). */
+    private readonly historyConfigExplicit;
+    /**
+     * tree-shake seam — the strategy that backs `collection.blob(id)`.
+     * Defaults to `NO_BLOBS`, a ~10-line stub that throws with an actionable
+     * message. Consumers opt into real blob storage by importing
+     * `{ blobs }` from `@noy-db/hub/blobs` and passing the returned
+     * strategy to `createNoydb({ blobStrategy: blobs() })`. With the
+     * default stub, none of the BlobSet / chunk / MIME-magic machinery
+     * reaches the bundle.
+     */
+    private readonly blobStrategy;
+    private readonly objectStore;
+    private readonly blobFields;
+    private readonly blobTierPolicy;
+    private readonly aggregateStrategy;
+    private readonly crdtStrategy;
+    private readonly tiersStrategy;
+    private readonly searchStrategy;
+    private readonly historyStrategy;
+    private readonly syncStrategy;
+    private readonly cache;
+    private hydrated;
+    /**
+     * #606: ids known to carry a delete marker in the store — lets the #589
+     * re-create version-continuity gate in `_putInternal` read the store ONLY
+     * for a known marker prior, instead of unconditionally on every insert.
+     * Populated on hydration (`ensureHydrated`/`hydrateFromSnapshot`), local
+     * delete (`_doDelete`), and the sync/tab/cutover choke point
+     * (`_invalidateCacheEntry`). Accepted drift: `vault._purgeDeleteMarkers`/
+     * `_purgeMarkersOn` remove markers directly on the raw store, bypassing
+     * Collection, so this set can hold stale ids after a purge on an
+     * already-loaded collection — perf-only and self-healing (a stale id just
+     * costs one `adapter.get` that returns non-marker/null, and version
+     * resolution falls back to 1 correctly). Do not try to wire purge into it.
+     */
+    private readonly markerIds;
+    /**
+     * Lazy mode flag. `true` when constructed with `prefetch: false`.
+     * In lazy mode the cache is bounded by an LRU and `list()`/`query()`
+     * throw — callers must use `scan()` or per-id `get()` instead.
+     */
+    private readonly lazy;
+    /**
+     * LRU cache for lazy mode. Only allocated when `prefetch: false` is set.
+     * Stores `{ record, version }` entries the same shape as `this.cache`.
+     * Tree-shaking note: importing Collection without setting `prefetch:false`
+     * still pulls in the Lru class today; future bundle-size work could
+     * lazy-import the cache module.
+     */
+    private readonly lru;
+    /**
+     * tree-shake seam — per-Collection indexing state. Owned by the
+     * `IndexStrategy` passed through from `createNoydb({ indexStrategy })`.
+     * Defaults to a disabled state (both accessors return null) so the
+     * `CollectionIndexes` / `PersistedCollectionIndex` / `LazyQuery`
+     * classes never reach the bundle when indexing is unused.
+     *
+     * Accessor helpers below (`get indexes()`, `get persistedIndexes()`)
+     * preserve the field-access ergonomics without changing every
+     * caller site.
+     */
+    private readonly indexState;
+    /**
+     * In-memory unique-constraint enforcement for eager mode.
+     * `null` when no `unique:true` indexes are declared on this collection, or when the collection is in lazy mode (which throws at registration).
+     */
+    private readonly uniqueConstraints;
+    /**
+     * True once `_idx/*` side-cars have been bulk-loaded into
+     * `persistedIndexes`. Flipped by `ensurePersistedIndexesLoaded()` on
+     * first lazy-mode query so subsequent queries skip the adapter round
+     * trip. Invalidation (remote sync, rotation) resets it alongside
+     * `persistedIndexes.clear()`.
+     */
+    private persistedIndexesLoaded;
+    /**
+     * Accessor for the in-memory eager-mode index mirror. Returns `null`
+     * when indexing is disabled on this Noydb instance (the
+     * `NO_INDEXING` default) or when the collection is in lazy mode
+     * (which uses the persisted mirror instead).
+     */
+    private get indexes();
+    /**
+     * Accessor for the persisted-mirror (lazy-mode) index. Returns `null` when indexing is disabled or the collection is in eager mode.
+     */
+    private get persistedIndexes();
+    /**
+     * per-collection reconcile-on-open policy. Read once
+     * from `CollectionOptions.reconcileOnOpen` and applied by
+     * `ensurePersistedIndexesLoaded()` on the first lazy-mode query.
+     */
+    private readonly reconcileOnOpen;
+    /**
+     * Re-entrancy guard for the auto-reconcile path. `reconcileIndex`
+     * reloads the mirror after applying fixes, which re-enters
+     * `ensurePersistedIndexesLoaded`; without this flag we'd trigger a
+     * second auto-reconcile pass and potentially infinite recursion.
+     */
+    private autoReconciling;
+    /**
+     * Optional Standard Schema v1 validator. When set, every `put()` runs
+     * the input through `validateSchemaInput` before encryption, and every
+     * record coming OUT of `decryptRecord` runs through
+     * `validateSchemaOutput`. A rejected input throws
+     * `SchemaValidationError` with `direction: 'input'`; drifted stored
+     * data throws with `direction: 'output'`. Both carry the rich issue
+     * list from the validator so UI code can render field-level messages.
+     *
+     * The schema is stored as `StandardSchemaV1<unknown, T>` because the
+     * collection type parameter `T` is the OUTPUT type — whatever the
+     * validator produces after transforms and coercion. Users who pass a
+     * schema to `defineNoydbStore` (or `Collection.constructor`) get their
+     * `T` inferred automatically via `InferOutput<Schema>`.
+     */
+    private readonly schema;
+    /**
+     * Vault-default locale. Used as the fallback when no per-call
+     * locale option is passed to `get()`/`list()`. Provided by Vault
+     * at collection construction time via the `collection({ locale })` or
+     * `openVault(name, { locale })` path.
+     *
+     * `undefined` means "no default locale set" — i18nText fields will
+     * throw `LocaleNotSpecifiedError` unless a per-call locale is passed.
+     */
+    private readonly defaultLocale;
+    /** Field name → `I18nTextDescriptor` for `i18nText()` fields (`i18nFields` option); write/read runs through the compiled `via` i18n binding — this remains for `describe()` and the search-index build path. Mutable — see {@link _reconcileReadState} (#671 item 2). */
+    private i18nFields;
+    /** The configured string fields exposed to `retrieve()`; `undefined` for ordinary collections (zero-cost). */
+    private readonly textIndexes;
+    /** Session-scoped lexical index store; `undefined` (zero-cost) unless `textIndexes` is non-empty. */
+    private readonly searchIndexStore;
+    /** Embedding config for write-time vector derivation; `undefined` (zero-cost) for ordinary
+     *  collections. When set, `put()` encodes the source field(s) and stores an encrypted `_vec` sidecar. */
+    private readonly embeddings;
+    /** In-memory vector set, populated lazily from `_vec` sidecars; `undefined` when no embedding config is declared. */
+    private vectorSet;
+    /** Field name → `DictKeyDescriptor` for `dictKey()` fields; used by `get()`/`list()` to add `<field>Label` virtual fields when a locale is requested. Mutable — see {@link _reconcileReadState} (#671 item 2). */
+    private dictKeyFields;
+    /** Field name → `LookupDescriptor` for native `lookup()`/`enumOf()`/`dict()` fields (#650 Task 2) — describe()-only in this task. Mutable — see {@link _reconcileReadState} (#671 item 2). */
+    private lookupFields;
+    /** Sync join-dressing hook (#650 Task 6, #626 retirement) — `querySourceForJoin()`'s `presentForJoin`. Mutable — see {@link _reconcileReadState} (#671 item 3). */
+    private presentForJoin;
+    /** Consumer-neutral per-field descriptors declared via `fieldMeta`; read by `getFieldMeta()`, merged by `describe()`. */
+    private fieldMeta;
+    /** Collection-level descriptive metadata declared via `meta`; read by `getMeta()`, surfaced in `describe()`. */
+    private meta;
+    /** Outbound ref declarations (snapshot from vault refRegistry at construction time); used by `describe()`. */
+    private readonly _refs;
+    /** Money field descriptors keyed by field path, typed as the opaque {@link ViaDescriptor} marker
+     *  (the kernel never inspects the concrete shape); `put()` quantizes to a scaled-int string,
+     *  `get()`/`list()` decode back. Mutable so {@link _applyMoneyFields} can attach. */
+    private moneyFields;
+    private via;
+    /**
+     * Computed scalar fields, evaluated first on every `put()`. Mutable for
+     * the same MV-pre-creation reconcile as {@link moneyFields}.
+     */
+    private computed;
+    /**
+     * Resolved classified() sensitive-field descriptors, declared via the
+     * `classifiedFields` collection option. Mutable so {@link _applyClassifiedFields}
+     * can attach a declaration to a collection MV-analysis pre-created.
+     */
+    private classified;
+    /**
+     * Frozen construction-time facts the refusal matrix (R1-R5) checks against.
+     * Stored so {@link _applyClassifiedFields} — door 2, the reconcile seam —
+     * can re-run the SAME guard the config resolver ran at door 1 (C5's lesson:
+     * crdt/conflictPolicy/perRecordKeys are construction-only but
+     * classifiedFields can attach later).
+     */
+    private readonly classifiedGuardCtx;
+    /**
+     * Digest-only classified fields (`storage: 'digest-only'`), keyed by field
+     * name — the enclave-consumable policy map the codec's write path carries
+     * `_vdig` forward under (C6). `null` when the collection declares none.
+     */
+    private readonly vdigFields;
+    /** C-A/R10 memoization: marker declared-set lookup (undefined=unresolved) + classified-handle persist-once flag. */
+    private _markerDigestOnlyCache;
+    private _markerPersisted;
+    /**
+     * Tree-shake seam for `reveal()` — defaults to `NO_CLASSIFIED`, which
+     * throws `ClassifiedNotEnabledError`. Set via the `classifiedStrategy`
+     * `createNoydb()` option (opt in with `withClassified()`).
+     */
+    private readonly classifiedStrategy;
+    /** Async callback provided by the Vault to open a dynamic dictionary handle (for label-map pre-computation in the search index). Only used in `resolveDictLabelMaps()`; static dicts bypass this entirely. Mutable, assign-once — see {@link _reconcileReadState} (#671 item 1). */
+    private getDictionary;
+    /**
+     * declared deterministic fields. `null` when the feature
+     * is inactive for this collection; a frozen `Set` otherwise.
+     */
+    private readonly deterministicFields;
+    /**
+     * Declared structural-group-encryption fields (`sensitive`). Each is
+     * sealed into its own `_sealed[field]` slot under a per-field key and kept
+     * out of the open `_data` blob. Empty set ⇒ feature off (byte-identical
+     * output). See {@link encryptRecord} / {@link decryptRecord}.
+     */
+    private readonly sensitiveFields;
+    /**
+     * Per-record CEK opt-in (`perRecordKeys: true`). When set, writes mint /
+     * reuse a per-record content-encryption key and stamp `_cek` on the
+     * envelope (see {@link EncryptedEnvelope._cek}). OFF by default — a
+     * non-adopting collection takes the byte-identical legacy path. The READ
+     * path does not consult this flag: `_cek` presence on the envelope is the
+     * format discriminant, so a mixed vault (and a recipient that never set the
+     * flag) still decrypts CEK records.
+     */
+    private readonly perRecordCek;
+    /**
+     * Per-record provenance opt-in (`provenance: true`). When set, `put()` calls
+     * that supply a `source` option stamp `_source`/`_sourceTs` onto the
+     * unencrypted envelope metadata. Off by default — zero cost for collections
+     * that don't need lineage tracking.
+     */
+    private readonly provenance;
+    /**
+     * Session-scoped `(id) → CEK` cache for this collection. Lets updates
+     * reuse a record's stable CEK and lets repeated reads skip the AES-KW
+     * unwrap. Bounded by LRU; never persisted. Dropped when the owning
+     * collection instance is discarded — `vault.load()` clears the
+     * collectionCache, so a keyring refresh drops every CEK alongside the
+     * DEK cache. `null` unless `perRecordCek` is set.
+     */
+    private readonly cekCache;
+    /**
+     * The per-record envelope build + encrypt/decrypt + per-record-CEK +
+     * sealed-field crypto, extracted off this god-object. Holds no mutable
+     * state of its own — it shares this collection's `cekCache` reference (so
+     * tier methods and `vault.invalidateRecordCaches` evictions stay visible to
+     * it) and reads the rest of its dependencies as a frozen context snapshot.
+     */
+    private readonly codec;
+    /**
+     * declared tiers for this collection. `null` when
+     * tier-aware methods are disabled. Tier 0 is implicit and never
+     * stored here.
+     */
+    private readonly tiers;
+    private readonly tierMode;
+    private readonly onCrossTierAccess;
+    private readonly addSubjectRef;
+    /**
+     * Optional reference to the vault-level hash-chained audit log. When present, every successful `put()` and `delete()` appends an entry to the ledger AFTER the adapter write succeeds (so a failed adapter write never produces an orphan ledger entry).
+     *
+     * The ledger is always a vault-wide singleton — all
+     * collections in the same vault share the same LedgerStore.
+     * Vault.ledger() does the lazy init; this field just holds
+     * the reference so Collection doesn't need to reach back up to the
+     * vault on every mutation.
+     *
+     * `undefined` means "no ledger attached" — supported for tests that
+     * construct a Collection directly without a vault, and for
+     * future backwards-compat scenarios. Production usage always has a
+     * ledger because Vault.collection() passes one through.
+     */
+    private readonly ledger;
+    /** — per-collection CRDT mode, or undefined for normal LWW-at-record-level. */
+    private readonly crdtMode;
+    /** — optional remote/sync adapter for presence broadcasting. */
+    private readonly syncAdapter;
+    /** — consent-audit hook, no-op when no scope is active. */
+    private readonly onAccess;
+    /**
+     * Vault-internal hook for derivation dispatch. When set,
+     * `Collection.put` consults the registry after the source-write
+     * commits and writes derived outputs through `getCollection(name).put`.
+     */
+    private readonly derivationSource;
+    /**
+     * Vault-internal hook for materialized-view dispatch.
+     * Parallel to `derivationSource` — when set, `Collection.put` fires
+     * `MaterializedViewRegistry.onSourceWrite` after the source-write
+     * commits + after `dispatchDerivations` has run.
+     */
+    private readonly materializedViewSource;
+    /** #638 Task 4 — `Vault._collectGraphTouch`; a no-op absent an open batch. `collectDelete` (#640) is the sync-apply delete socket. */
+    private readonly graphDispatch;
+    /**
+     * Optional back-reference to the owning compartment's ref
+     * enforcer. When present, `Collection.put` calls
+     * `refEnforcer.enforceRefsOnPut(name, record)` before the adapter
+     * write, and `Collection.delete` calls
+     * `refEnforcer.enforceRefsOnDelete(name, id)` before its own
+     * adapter delete. The Vault handles the actual registry
+     * lookup and cross-collection enforcement — Collection just
+     * notifies it at the right points in the lifecycle.
+     *
+     * Typed as a structural interface rather than `Vault`
+     * directly to avoid a circular import. Vault implements
+     * these two methods; any other object with the same shape would
+     * work too (used only in unit tests).
+     */
+    private readonly refEnforcer;
+    /**
+     * Optional back-reference to the owning compartment's join resolver
+     *`). When present,
+     * `Collection.query()` builds a `JoinContext` that lets the Query
+     * resolve `.join(field)` calls into target collections via this
+     * resolver.
+     *
+     * Two methods:
+     *   - `resolveSource(name)` — fetch a `JoinableSource` for the
+     *     right-side collection by name. Returning `null` means "no
+     *     such collection in this compartment" — the executor then
+     *     throws an actionable error naming the missing target.
+     *   - `resolveRef(leftCollection, field)` — look up the ref
+     *     descriptor the left collection declared for this field.
+     *     `null` when the field has no ref, which makes `.join()`
+     *     throw at plan time before any records are touched.
+     *
+     * Typed structurally rather than as `Vault` to avoid a
+     * circular import. Vault implements these two methods; any
+     * other object with the same shape works too (used only in unit
+     * tests against a plain object).
+     */
+    private readonly joinResolver;
+    constructor(opts: CollectionOpts<T>);
+    /**
+     * Return the Standard Schema validator attached to this collection,
+     * or `undefined` if none was provided at construction time.
+     *
+     * Exposed (read-only) for the Vault-level export primitive,
+     * which surfaces each collection's schema in the per-chunk metadata
+     * so downstream serializers (`@noy-db/as-*` packages, custom
+     * exporters) can produce schema-aware output without poking at
+     * collection internals. The validator object is returned by
+     * reference — callers must treat it as immutable.
+     */
+    getSchema(): StandardSchemaV1<unknown, T> | undefined;
+    /** The declared consumer-neutral field metadata channel (canonical). */
+    getFieldMeta(): Record<string, FieldMeta> | undefined;
+    /** The collection's declared descriptive metadata. */
+    getMeta(): CollectionMeta | undefined;
+    /**
+     * Aggregate all collection-level configuration options that are actively set
+     * into a {@link CollectionConfig} snapshot. Returns `undefined` when no options
+     * are configured (omitting the `config` block from `dumpSchema()` output).
+     * Consumed by `walk.ts` to populate `CollectionDescriptor.config`.
+     */
+    getConfig(): CollectionConfig | undefined;
+    /**
+     * Describe the collection's field schema from in-memory config — zero store I/O.
+     * Sync overload (no args): merges moneyFields/dictKeyFields/refs/computed/fieldMeta/
+     * taint into a {@link CollectionDescription} (types inferred from config; the async
+     * overload also derives validator-exact types and resolves dynamic dict labels).
+     */
+    describe(): CollectionDescription;
+    describe(opts: DescribeOptions): Promise<CollectionDescription>;
+    /**
+     * Async describe implementation. Derives validator-exact types via deriveZodFields
+     * (lazy, no static zod import), optionally resolves dynamic-dict labels from vault.dictionary(name).list(),
+     * then delegates to buildDescription (which also runs fieldMeta key-validation).
+     */
+    private describeAsync;
+    /** JSON Schema for this collection with describe() metadata as x- extensions. */
+    toJSONSchema(): Promise<object>;
+    /** Single-point audited reveal of one classified field. Requires withClassified(). */
+    reveal(id: string, field: string): Promise<unknown>;
+    /** Verify-without-reveal: verdict-only oracle for one classified field. Requires withClassified(). */
+    verify(id: string, field: string, candidate: string): Promise<ClassifiedVerdict>;
+    /** k-of-n challenge over the collection's secretAnswer members. Requires withClassified(). */
+    verifyGroup(id: string, answers: Record<string, string>, opts: {
+        readonly min: number;
+    }): Promise<{
+        readonly passed: boolean;
+    }>;
+    private _classifiedVerifyCtx;
+    /**
+     * Equatable blind-index lookup: the ids whose classified digest-only
+     * `equatable` field carries a `_bidx` tag matching `candidate` AND whose
+     * `_vdig` payload confirms it. Requires the field to be declared
+     * `classified.password({ equatable: true })` (or `secretAnswer`) and the
+     * collection to have opened its `acknowledgeEquatableRisk` door.
+     *
+     * The algorithm order is load-bearing (spec §3):
+     *  1. Caller-bug refusals thrown at ~0 elapsed, BEFORE any PBKDF2 (R9 /
+     *     Oracle #6): the three field mis-declarations share ONE constant,
+     *     field-name-free message so the refusal text cannot enumerate which
+     *     fields are classified / digest-only / equatable.
+     *  2. Derive the ONE blind-index target UNCONDITIONALLY (I-1 / F1): an empty
+     *     collection still pays exactly one 600K PBKDF2, so wall-time can never
+     *     distinguish "no records" from "no match". No early return may precede
+     *     this line.
+     *  3. Scan `list + one get` per id, string-comparing the stored `_bidx` tag —
+     *     decrypting NOTHING — and retain each hit's already-fetched envelope.
+     *  4. Emit the single sweep consent op (`onAccess('find', '*')`) now — after
+     *     the scan, before confirm (Oracle #5) — fixing its store-write timestamp
+     *     independent of hit count.
+     *  5. Confirm-by-verify against the ALREADY-FETCHED envelope (C-B): run the
+     *     enclave `verifyDigestField` on an in-memory `getEnvelope` closure so the
+     *     confirm reads ZERO additional envelopes. A tag-hit whose `_vdig` fails
+     *     to confirm is dropped silently (a splice is indistinguishable from a
+     *     stale tag). Store-shape law: the only store calls are `list + N get`.
+     */
+    findByDigest(field: string, candidate: string): Promise<readonly string[]>;
+    /**
+     * Retire a field's equatable blind-index (`_bidx`) coverage across every
+     * live record — the SOLE lazy-write-independent drop-path for a still-live
+     * record's tag (besides clear / `forget()` / DEK-rotation). For each envelope
+     * carrying `_bidx[field]`, rewrite it WITHOUT that slot (dropping the whole
+     * `_bidx` map when it becomes empty), leaving `_vdig[field]` and everything
+     * else INTACT — the field stays `digest-only`, only the index coverage is
+     * retired. NO crypto, NO re-mint, NO re-encrypt: a targeted envelope rewrite.
+     * Returns the count of records scrubbed.
+     *
+     * This is a maintenance write, not a read-egress: it emits NO `'find'` op and
+     * no consent. The field is validated to a declared equatable digest-only
+     * classified field (only such a field ever carries `_bidx`).
+     *
+     * **Ledger consistency**: dropping `_bidx[field]` changes the envelope's
+     * payload hash (`_bidx` is bound into `envelopeBodyForHash`), so a raw
+     * `adapter.put` of the scrubbed envelope WITHOUT a matching ledger entry would
+     * desync the chain and make a future integrity cross-check flag false
+     * tampering. After each rewrite we therefore append an `op:'migration'` entry
+     * recording the NEW payloadHash at the SAME version — this is index retirement,
+     * not a new record version, so `_v` is NOT bumped; the migration op is
+     * reverse-delta-inert (`ledger.reconstruct` skips non-put/delete ops) yet
+     * keeps the hash chain and the record's latest recorded payloadHash correct.
+     */
+    scrubEquatableTags(field: string): Promise<number>;
+    /**
+     * @internal — attach money descriptors post-construction. MV dependency
+     * analysis auto-creates a source collection (without options) during
+     * `openVault`, before the user's `collection(name, { moneyFields })`
+     * declaration; this reconciles that ordering. First-wins. Not public.
+     *
+     * PREPENDS money rather than appending: {@link compileViaBindings} always
+     * compiles money before i18n (money-first pipeline order — see its
+     * docstring), and by the time this reconcile runs an i18n binding may
+     * already be sitting in `this.via.bindings` (declared at construction).
+     * Appending here would yield `[i18n, money]` on this path vs `[money,
+     * i18n]` from compile — prepending keeps both paths money-first.
+     */
+    _applyMoneyFields(moneyFields: Record<string, ViaDescriptor>): void;
+    /** @internal — attach computed fields post-construction. See {@link _applyMoneyFields}. */
+    _applyComputed(computed: ComputedFields): void;
+    /** @internal — attach fieldMeta post-construction. See {@link _applyMoneyFields}. First-wins. */
+    _applyFieldMeta(fieldMeta: Record<string, FieldMeta>): void;
+    /** @internal — attach collection-level meta post-construction. See {@link _applyMoneyFields}. First-wins. */
+    _applyMeta(meta: CollectionMeta): void;
+    /**
+     * @internal — attach classified fields post-construction. See {@link _applyMoneyFields}.
+     * First-wins. Note: unlike money/computed/meta, this cannot retro-seal a
+     * collection that was already auto-created — `sensitiveFields` is frozen at
+     * construction time. A reconciled declaration is only accepted when none of
+     * its members are `storage: 'recoverable'` (those require sealing at first
+     * open); otherwise this throws rather than silently persisting the value as
+     * inline plaintext while `describe()` advertises protection.
+     */
+    _applyClassifiedFields(classifiedFields: Record<string, ClassifiedEntry>): void;
+    get _ramCiphertext(): boolean;
+    /**
+     * Get a single record by ID.
+     *
+     * @param id      Record identifier.
+     * @param locale  Optional locale options. When provided,
+     *                `i18nText` fields are resolved to the requested locale
+     *                string, and `dictKey` fields get a `<field>Label`
+     *                virtual field added. Pass `{ locale: 'raw' }` to
+     *                return the full `{ [locale]: string }` map instead.
+     *
+     * @returns The decrypted (and optionally locale-resolved) record, or
+     *          `null` if not found.
+     */
+    get(id: string, locale?: LocaleReadOptions): Promise<SealedView<T, S> | null>;
+    /**
+     * Return the raw CRDT state for a record.
+     * Only available on collections configured with `crdt: 'lww-map' | 'rga' | 'yjs'`.
+     * Use this for merge operations or to pass to `@noy-db/yjs`.
+     * Throws if the collection is not in CRDT mode.
+     */
+    getRaw(id: string): Promise<CrdtState | null>;
+    /**
+     * Read a record's unencrypted envelope metadata (version, timestamps,
+     * provenance) without decrypting the body.
+     *
+     * Returns `null` when no envelope exists for `id` (record absent or never
+     * written). Only `_source`/`_sourceTs` fields are populated when the
+     * collection was opened with `provenance: true` AND the record was written
+     * with a `source` option — but this method works on any collection because
+     * it reads the raw envelope directly.
+     *
+     * @returns `{ version, timestamp, by?, source?, sourceTs? }` or `null`.
+     *
+     * @example
+     * const meta = await clients.getMetadata('c1')
+     * if (meta) console.log(meta.source, meta.timestamp)
+     */
+    getMetadata(id: string): Promise<{
+        readonly version: number;
+        readonly timestamp: string;
+        readonly by?: string;
+        readonly source?: string;
+        readonly sourceTs?: string;
+    } | null>;
+    /**
+     * Return a presence handle for this collection.
+     *
+     * The handle manages an encrypted ephemeral presence channel keyed by an
+     * HKDF derivation of this collection's DEK. Presence payloads are invisible
+     * to the adapter.
+     *
+     * @param opts.staleMs       Milliseconds before a peer is considered inactive.
+     *                           Default: 30 000.
+     * @param opts.pollIntervalMs Milliseconds between storage polls (fallback mode).
+     *                           Default: 5 000.
+     */
+    presence<P = unknown>(opts?: {
+        staleMs?: number;
+        pollIntervalMs?: number;
+    }): PresenceHandle<P>;
+    /**
+     * Create or update a record. Runs inside the hub's write-queue tracker
+     * so `hub.writeQueue.pending` reflects this write.
+     *
+     * @param id      Record identifier.
+     * @param record  The record body (validated by the collection's schema
+     *                if one was attached at `vault.collection(...)` time).
+     * @param options Optional metadata for audit + import workflows.
+     *                `reason` is stamped onto the resulting ledger entry
+     *                so audit consumers can filter via
+     *                `entries.filter(e => e.reason?.startsWith('import:'))`.
+     *                `source` is an opaque source id (e.g. `'crm-sync'`, `'firm-A'`)
+     *                stamped onto the envelope as `_source`/`_sourceTs` when
+     *                the collection has `provenance: true`. Ignored otherwise
+     *                (zero cost).
+     *                `sourceTs` is an optional ISO-8601 origin timestamp override;
+     *                when supplied together with `source` on a provenance collection,
+     *                replaces the machine-stamped `now()` so re-merges preserve the
+     *                ORIGIN refresh time across vaults. (FR-4)
+     */
+    put(id: string, record: T, options?: {
+        readonly reason?: string;
+        readonly source?: string;
+        readonly sourceTs?: string;
+    }): Promise<void>;
+    /**
+     * Resolve the prior stored record (with its `_i18nFilled` marker) for
+     * densify. Eager: in-memory cache; lazy: LRU then adapter. undefined if absent.
+     */
+    private resolveDensifyPrior;
+    /**
+     * Densify provenance for a record: which i18n slots were auto-filled,
+     * e.g. `{ name: ['en'] }`. undefined when nothing was filled. The marker is
+     * stripped from ordinary reads; this is the sanctioned audit accessor.
+     */
+    i18nProvenance(id: string): Promise<Record<string, readonly string[]> | undefined>;
+    /**
+     * Validate a record against this collection's schema WITHOUT writing it.
+     * Returns the (possibly coerced) record on success; throws
+     * {@link SchemaValidationError} (direction: `'input'`) on violation.
+     * A no-op pass-through when no schema is declared.
+     *
+     * Used by FR-8 migrate-then-merge to pre-validate all staged records
+     * before `mergeDecryptedRecords` writes anything — so a failed upgrade
+     * never half-writes the receiver.
+     */
+    validateInput(record: T): Promise<T>;
+    /**
+     * Resolve the prior record as REAL VALUES for the eager write/delete paths
+     * (history snapshot, ledger patch, index upkeep). The eager cache holds
+     * {@link Sealed} handles for sensitive fields (non-residency), so when the
+     * collection seals anything we re-decrypt the stored envelope to materialise
+     * real values — re-encrypting a handle would otherwise persist the marker
+     * `'[sealed]'` in place of the value. `via?.hasAtRestHooks` (#642) catches
+     * hook-only sealing (taint/classified, no local `sensitiveFields`).
+     */
+    private resolvePriorValues;
+    /** Resolves the prior envelope/record for a gate event; elides the read (#267) when no handler at `point` needs it (`elided: true`, `env`/`record` null). */
+    private resolveGatePrior;
+    /**
+     * Wraps {@link RecordCodec.toCacheRecord} with an additional strip for
+     * digest-only classified fields: the codec already omits them from `_data`
+     * on write, but the write path caches the pre-encrypt `record` object
+     * directly (to skip a redundant decrypt) — without this, a vdig field's
+     * plaintext would sit in the working-set cache and `get()` would leak it
+     * right back out, defeating C6.
+     */
+    private _toCacheableRecord;
+    /** @internal Untracked put body — call {@link put}, not this. */
+    private _putInternal;
+    /**
+     * Fire registered MV strategies whose dependency set includes this
+     * collection. Eager-mode MVs re-materialize inline via
+     * `MaterializedViewExecutor.refresh`; lazy / manual modes are
+     * no-ops in the foundation; wired in the lazy-mode implementation.
+     *
+     * Skips entirely when the record being written is itself an
+     * MV-emitted row (carries `_materializedFrom`) — defensive guard
+     * against missed cycle detection.
+     *
+     * @internal `wave` (#638 Task 4): when present (the sync/cutover/restore dispatch wave),
+     * an eager MV already refreshed this wave is skipped (per-target dedup, keyed on spec name).
+     */
+    dispatchMaterializedViews(id: string, record: T, wave?: WaveContext): Promise<void>;
+    /**
+     * Fire registered derivation strategies for this source collection.
+     * Eager mode runs `derive` inline and writes each output via the
+     * sibling `Collection.put`; lazy mode marks dependent outputs stale
+     * (D11 stub today). Errors in non-strict mode are logged and
+     * skipped; strict mode propagates the first failing output's error.
+     *
+     * Skips entirely when the record being written is itself a derived
+     * output (carries `_derivedFrom`) — defensive guard against missed
+     * cycle detection.
+     */
+    /**
+     * @internal The RAW stored record (canonical-money form, i18n maps
+     * intact), WITHOUT the locale resolution `get()` applies. Used as the
+     * patch base for self-write reverse-denorm so writing back never clobbers
+     * an i18n map or re-quantizes money incorrectly. Returns null for
+     * missing / tombstoned records.
+     */
+    _getStoredRecord(id: string): Promise<T | null>;
+    /** @internal #638 Task 4 — decrypted STORED-form record + envelope version for the sync/cutover/
+     *  restore dispatch wave (id threaded into decrypt, matching `_invalidateCacheEntry`'s contract). */
+    _getStoredRecordForDispatch(id: string): Promise<{
+        record: T;
+        version: number;
+    } | null>;
+    /**
+     * @internal Ids of records whose top-level `field` equals `value`.
+     * Uses the FK index when the field is indexed (O(matches)); otherwise a
+     * linear scan (O(N) — fine for small child sets; index the FK to scale).
+     */
+    _findMatchingIds(field: string, value: unknown): Promise<string[]>;
+    /** @internal Recompute a rollup aggregate onto the parent from `parentId`'s current children (value-equality guarded; no-op absent parent).
+     *  `wave` (#638 T4, #640): per-target dedup. Returns the `putDerivedOutput` outcome, or `'noop'` (no parent/no-op/deduped) — `dispatchRollupsOnDelete`'s forget-fanout caller + #640's `_recomputeDeletedRollups` need this to fill their reports. */
+    private recomputeRollup;
+    /** @internal #640 — this deleted child's rollup PARENT intents (see via/dispatch.ts#resolveRollupDeleteIntents). */
+    _rollupDeleteIntents(deleted: T): RollupDeleteIntent[];
+    /**
+     * @internal Fire any rollups for which THIS collection is the child `from`, recomputing the
+     * affected parent after a child delete/forget. Called from the delete path (return discarded)
+     * and from `forgetDerivedFanout` (#638 Task 6), which needs the per-target outcome to fill
+     * `ForgetResult.derivedAggregatesRecomputed`/`derivedResidueFrozen`). `wave` (#640): per-target dedup for the sync-apply path; `undefined` on local-delete (byte-identical).
+     */
+    dispatchRollupsOnDelete(id: string, deleted: T, wave?: WaveContext): Promise<ReadonlyArray<{
+        readonly into: string;
+        readonly parentId: string;
+        readonly outcome: RollupOutcome;
+    }>>;
+    /** @internal #640 — the wave's per-id driver: recompute each sync-apply delete's rollup parent. */
+    _recomputeDeletedRollups(intents: readonly RollupDeleteIntent[], wave: WaveContext): Promise<void>;
+    /** @internal `wave` (#638 Task 4) — threaded to `recomputeRollup` for the sync/cutover/restore
+     *  dispatch wave's per-target dedup; `undefined` on the local-write path (byte-identical). */
+    dispatchDerivations(id: string, record: T, version: number, wave?: WaveContext): Promise<void>;
+    /**
+     * Delete a record by ID. Runs inside the hub's write-queue tracker
+     * so `hub.writeQueue.pending` reflects this write.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * @internal — bulk-rewrite every record through a cutover transform. Raw adapter path (bypasses the write gate + guards — the transform is trusted and runs only during the `migrating` phase). Bumps each record's `_v` and appends a ledger `op:'migration'` entry. #708: refuses BEFORE any rewrite if a live record is elevated (assertCutoverTierSafe) — demote it first.
+     */
+    _applyCutoverTransform(transform: (doc: Record<string, unknown>) => Record<string, unknown>): Promise<number>;
+    /** @internal Untracked delete body — call {@link delete}, not this. */
+    private _deleteInternal;
+    /**
+     * @internal — system-internal delete that bypasses user-facing
+     * delete hooks (`onDelete`, FK ref enforcer). Used by derivation tombstones and MV refresh
+     * (Dim 14 v2) — system housekeeping shouldn't trip user invariants
+     * registered against the output collection. The ledger entry and
+     * history snapshot still fire so backup integrity and time-travel
+     * reconstruction stay consistent.
+     *
+     * Returns `true` when it erased a live record, `false` for delete-of-absent (idempotent
+     * contract — both txCtx-aware and txCtx===null callers honour this, short-circuiting before any side-effect).
+     *
+     * When a `txCtx` is supplied, the prior envelope is captured and
+     * pushed onto `txCtx._executed` BEFORE the delete fires — mirrors
+     * the rollback hardening for puts. Callers outside a
+     * multi-record transaction pass `null` and skip the tracking.
+     *
+     * Amendment composition: if `_internalDelete` runs while a vault's
+     * `GuardRegistry` has an amendment window open, the `{before, after:
+     * null}` change pair is pushed onto the amendment change-set the
+     * same way a user-initiated delete would. The `onDelete` user-hook
+     * is still skipped (housekeeping must not trip user invariants in
+     * normal mode), but the amendment's invariant DOES see the change
+     * — so a `RCT-CANCEL-001`-style invariant pairing can reject a
+     * derivation-driven tombstone fired during an admin amendment.
+     *
+     * Constraint to surface to consumers: output collections of
+     * derivations with `optional: true` outputs should not be the
+     * targets of `strict` or `cascade` inbound foreign-key refs —
+     * `_internalDelete` bypasses the ref enforcer by design (the
+     * `onDelete` bypass primitive). Treat the housekeeping path as
+     * "system can tombstone its own emissions regardless of FK shape."
+     *
+     * Permission handling is unchanged: the caller must still hold
+     * write permission on the collection (derivations run under the
+     * user's keyring).
+     */
+    _internalDelete(id: string, txCtx?: TxContext | null): Promise<boolean>;
+    private _doDelete;
+    /**
+     * @internal — GDPR crypto-shred a LIVE record to a tombstone.
+     *
+     * Rewrites the on-disk envelope to `{ _noydb, _v, _ts, _by, _iv:'', _data:'' }`,
+     * dropping `_iv`/`_data`/`_cek`/`_det`. The wrapped per-record CEK is gone, so
+     * the body — and (via {@link tombstoneHistory}) every history version under
+     * the same CEK — is permanently undecryptable; the collection DEK and every
+     * other record are untouched. `_det` is stripped too, so `findByDet` no
+     * longer matches the shredded record (avoiding a post-shred TamperedError).
+     *
+     * Unlike `delete()`/`_internalDelete`, this:
+     *   - does NOT fire onDelete guards / MV / derivation dispatch (a shred is an
+     *     erasure, not a domain delete — re-running those would be wrong),
+     *   - does NOT append a per-record ledger entry (`vault.forget()` appends a
+     *     single `op:'forget'` summary for the whole subject),
+     *   - keeps the record KEY present (it's an overwrite, not an adapter delete)
+     *     so the version counter + "record existed" survive for audit.
+     *
+     * Idempotent: returns `null` when the record is absent or already a tombstone.
+     * Otherwise returns `{ previousVersion }`. Invalidates the eager cache, the
+     * lazy LRU, and the per-record CEK cache for this id.
+     */
+    /**
+     * @internal — decrypt an envelope to a plain record for subject-index
+     * rebuild. Returns `null` for a tombstone or unreadable envelope.
+     * Skips schema validation — the rebuild only reads the subject field.
+     */
+    _decodeEnvelope(envelope: EncryptedEnvelope, id: string): Promise<Record<string, unknown> | null>;
+    _writeTombstone(id: string, actor: string): Promise<{
+        previousVersion: number;
+    } | null>;
+    /**
+     * Cascade deletes of array-shape derived rows when a source row is deleted. Reads each
+     * registered strategy's fanout sidecar for this source id, deletes every listed derived
+     * row, then deletes the sidecar itself. Returns the REAL erased count (#622 review Finding 1).
+     *
+     * Record-shape derivations are skipped on the ordinary delete path (see _doDelete's comment).
+     * `eraseRecordShapeToo` (#638 T6, default `false`) opts a same-id record-shape copy into
+     * erasure too — forget()'s fanout, GDPR residue. A delete-of-absent contributes 0 either way.
+     * @internal
+     */
+    dispatchArrayDerivationsOnDelete(id: string, eraseRecordShapeToo?: boolean): Promise<number>;
+    /**
+     * Mirror of {@link dispatchMaterializedViews} for the delete/forget path — no `_materializedFrom`
+     * skip (record's gone); the `internal` gate at `_doDelete` is the recursion guard. Returns the
+     * row count TOMBSTONED across EVERY MV sourced here (#638 T6 — `forgetDerivedFanout`'s
+     * `derivedRecordsErased`) — eager AND lazy/manual `invalidateMVAtRest` purges both contribute now
+     * (#761 item 1, previously eager-only); lazy persists a stale mark for cold-session recompute;
+     * manual serves empty until `refreshView()`. `residueUndecodable`/`residueDeclined` (#776/#785) carry `outputCollection:id` entries whose ownership stamp `invalidateMVAtRest` could not decode, resp. decoded+stamp-matched but declined erasure — surfaced, not erased.
+     * @internal
+     */
+    dispatchMaterializedViewsOnDelete(id: string): Promise<{
+        deleted: number;
+        residueUndecodable: string[];
+        residueDeclined: string[];
+    }>;
+    /**
+     * List all records in the collection.
+     *
+     * Throws in lazy mode — bulk listing defeats the purpose of lazy
+     * hydration. Use `scan()` to iterate over the full collection
+     * page-by-page without holding more than `pageSize` records in memory.
+     *
+     * @param locale  Optional locale options. When provided,
+     *                each record is locale-resolved before being returned.
+     */
+    list(locale?: LocaleReadOptions): Promise<T[]>;
+    /**
+     * Scan-mode full-text search over a plain-text `field`. Decrypts the
+     * collection in memory and ranks records by BM25 against the tokenized query.
+     * **Zero added store leakage** — pure client-side scan; nothing searchable is
+     * written to the store. (A store-usable blind index for at-scale search is a
+     * separate, gated opt-in.) Eager mode only.
+     *
+     * `opts.match` (`'any'` default | `'all'`), `opts.prefix` (last query term as
+     * a prefix → typeahead), `opts.limit` (top-N). Returns `{ id, score, record }`
+     * ranked by descending score. The default tokenizer is word-boundary based —
+     * see `src/search/tokenize.ts` for the Thai/CJK caveat.
+     */
+    search(field: string, query: string, opts?: SearchOptions): Promise<SearchResult<T>[]>;
+    /** Force-persist the lexical index now — gated behind `searchStrategy: withSearch()`. */
+    flushIndex(): Promise<void>;
+    /** Pre-build the lexical index — gated behind `searchStrategy: withSearch()`. */
+    warmIndex(): Promise<void>;
+    /** Retrieval (lexical | semantic | hybrid) — gated behind `searchStrategy: withSearch()`. */
+    retrieve(query: string, opts?: RetrieveOptions<T>): Promise<RetrieveHit<T>[]>;
+    /** Raw-vector kNN — gated behind `searchStrategy: withSearch()`. */
+    similarTo(vector: Float32Array, opts?: {
+        k?: number;
+        minScore?: number;
+        includeRecord?: boolean;
+    }): Promise<RetrieveHit<T>[]>;
+    /** Opt-in bulk `_vec` re-derive (#788) — a plain collection has nothing to rebuild; gated behind `searchStrategy: withSearch()` otherwise. */
+    rebuildEmbeddings(): Promise<{
+        rebuilt: number;
+        skipped: number;
+    }>;
+    /**
+     * Bind the {@link SearchContext} the search/retrieval surface needs. The
+     * `cache` is the SAME `Map` reference the eager read/write path owns (passed
+     * by reference, never copied) so the index always builds over the live set.
+     */
+    private searchContext;
+    /**
+     * Put many records in one call. Each item is processed sequentially
+     * through the normal `put()` path — meaning per-item validation,
+     * history snapshots, ledger appends, and change events all still
+     * fire. The round-trip saving comes from the adapter staying hot
+     * across the batch (no connection re-open, no keyring re-unlock).
+     *
+     * ## Semantics
+     *
+     * **Best-effort with per-item results.** If item 5 of 10 fails, items
+     * 1–4 are already persisted and items 6–10 are still attempted.
+     * The returned {@link PutManyResult} lists every success and failure
+     * individually so the caller can decide whether to roll forward
+     * (retry the failures) or roll back (manually delete the successes).
+     *
+     * **True tx-atomic putMany** — pass `{ atomic: true }` to switch
+     * to the  transaction executor: pre-flight CAS against every
+     * item's `expectedVersion`, then commit all ops with best-effort
+     * revert on mid-batch failure. Atomic mode throws on failure rather
+     * than returning a mixed-results object.
+     *
+     * ## Change events
+     *
+     * One `change` event per successfully-written record, same as N
+     * single-record puts. Subscribers don't need to special-case bulk.
+     */
+    putMany(entries: ReadonlyArray<readonly [id: string, record: T, opts?: PutManyItemOptions]>, options?: PutManyOptions): Promise<PutManyResult>;
+    /**
+     * Atomic-mode implementation of {@link putMany}. Pre-flights every
+     * `expectedVersion`, executes all puts in declaration order, and
+     * reverts executed ops via the raw adapter on mid-batch failure.
+     * See `runTransaction` for the shared semantics + crash-window caveat.
+     *
+     * @internal
+     */
+    private putManyAtomic;
+    /**
+     * Get many records in one call. Returns a `Map<id, T | null>` —
+     * missing records surface as `null` entries so the caller can
+     * distinguish "not found" from "lookup failed". Order-stable
+     * iteration (Map preserves insertion order = input `ids` order).
+     *
+     * Reads go through the per-id `get()` path, which means the cache
+     * / hydration logic stays consistent with single-record reads.
+     */
+    getMany(ids: readonly string[]): Promise<Map<string, T | null>>;
+    /**
+     * Delete many records in one call. Same best-effort contract as
+     * {@link putMany}: if item 5 fails, items 1–4 are already deleted
+     * and items 6–10 are still attempted.
+     *
+     * Deleting a non-existent id is not a failure — matches the
+     * idempotent semantics of single-record `delete()`.
+     */
+    deleteMany(ids: readonly string[]): Promise<DeleteManyResult>;
+    /**
+     * Build a chainable query against the collection. Returns a `Query<T>`
+     * builder when called with no arguments.
+     *
+     * Backward-compatible overload: passing a predicate function returns
+     * the filtered records directly (the API). Prefer the chainable
+     * form for new code.
+     *
+     * **Lazy-MV gap:** `query()` is synchronous and does NOT
+     * trigger lazy materialized-view resolve-on-read. If this
+     * collection is a lazy MV's output and the MV is currently stale,
+     * `query().toArray()` returns the pre-stale snapshot. To force a
+     * fresh read on a lazy MV, either call `list()` (which DOES
+     * trigger resolve) or `vault.refreshView(mvName)` before querying.
+     * The proper fix — extending `QuerySource` with an async prepare
+     * hook — is a separate PR.
+     *
+     * @example
+     * ```ts
+     * // New chainable API:
+     * const overdue = invoices.query()
+     *   .where('status', '==', 'open')
+     *   .where('dueDate', '<', new Date())
+     *   .orderBy('dueDate')
+     *   .toArray();
+     *
+     * // Legacy predicate form (still supported):
+     * const drafts = invoices.query(i => i.status === 'draft');
+     * ```
+     */
+    query(): Query<T, S, Q, M>;
+    query(predicate: (record: T) => boolean): T[];
+    /**
+     * Subscribe to every put/delete on this collection. Returns an
+     * unsubscribe function.
+     *
+     * Fires **after** the store write has committed — subscribers see
+     * only materialised state, never in-flight or rolled-back writes.
+     *
+     * This is an event stream, not a reactive value. For reactive
+     * "current array state" semantics use `query().live()`. Typical
+     * use cases for `subscribe()`:
+     *   - audit-trail / activity-feed UI that lists events as they happen
+     *   - Pinia-per-collection wiring where each store subscribes once
+     *   - outbox-style workers that process every new record
+     *
+     * The callback receives a `CollectionChangeEvent<T>`:
+     *   - `{ type: 'put', id, record }` — record is the current
+     *     decrypted value. May be `null` if another op deleted the
+     *     record between the emit and the handler firing (rare race).
+     *   - `{ type: 'delete', id, record: null }` — deletion event;
+     *     the record content is gone by the time the handler runs.
+     *
+     * The callback is invoked synchronously *with respect to the emit
+     * moment*, but the record lookup is async (cache hit for eager
+     * collections; one `get()` for lazy collections). If your handler
+     * does not need the record, cast it away and ignore — the lookup
+     * is still performed, but it's cheap on the hydrated path.
+     *
+     * ergonomic wrapper over `db.on('change', …)` that
+     * filters to this collection and hydrates the record.
+     */
+    subscribe(cb: (event: CollectionChangeEvent<T>) => void): () => void;
+    /**
+     * Return a minimal JoinableSource view of this collection's
+     * in-memory cache. Used by the Vault's `resolveSource`
+     * method when another collection's `.join()` needs to probe this
+     * one as the right side.
+     *
+     * The returned object captures the cache reference through a
+     * closure, so subsequent mutations to the cache are visible to
+     * the joined query. That's intentional: a join that fires after
+     * the right-side collection has been updated should see the
+     * fresh data.
+     *
+     * Throws in lazy mode because the cache is bounded and could
+     * silently miss records — consistent with the `query()` /
+     * `list()` lazy-mode policy. If this becomes a blocker for a
+     * real consumer, the fix is to add an async `scan()`-backed
+     * variant of this method, which is exactly what streaming joins will need anyway.
+     */
+    querySourceForJoin(): JoinableSource;
+    /**
+     * Cache statistics — useful for devtools, monitoring, and verifying
+     * that LRU eviction is happening as expected in lazy mode.
+     *
+     * In eager mode, returns size only (no hits/misses are tracked because
+     * every read is a cache hit by construction). In lazy mode, returns
+     * the full LRU stats: `{ hits, misses, evictions, size, bytes }`.
+     */
+    cacheStats(): CacheStats;
+    /** Get version history for a record, newest first. */
+    history(id: string, options?: HistoryOptions): Promise<HistoryEntry<T>[]>;
+    /**
+     * Get a specific past version of a record.
+     *
+     * History reads intentionally **skip schema validation** — historical
+     * records predate the current schema by definition, so validating them
+     * against today's shape would be a false positive on any schema
+     * evolution. If a caller needs validated history, they should filter
+     * and re-put the records through the normal `put()` path.
+     */
+    getVersion(id: string, version: number): Promise<T | null>;
+    /** Revert a record to a past version. Creates a new version with the old content. */
+    revert(id: string, version: number): Promise<void>;
+    /**
+     * Compare two versions of a record and return the differences.
+     * Use version 0 to represent "before creation" (empty).
+     * Omit versionB to compare against the current version.
+     */
+    diff(id: string, versionA: number, versionB?: number): Promise<DiffEntry[]>;
+    /** Resolve a version: try history first, then check if it's the current version. */
+    private resolveVersion;
+    private resolveCurrentOrVersion;
+    /** Prune history entries for a record (or all records if id is undefined). */
+    pruneRecordHistory(id: string | undefined, options: PruneOptions): Promise<number>;
+    /** Clear all history for this collection (or a specific record). */
+    clearHistory(id?: string): Promise<number>;
+    /**
+     * Count records in the collection.
+     *
+     * In eager mode this returns the in-memory cache size (instant). In lazy
+     * mode it counts only LIVE tier-0 envelopes via envelope inspection — no
+     * record bodies loaded — matching eager's tombstone/tier exclusion (#706).
+     */
+    count(): Promise<number>;
+    /**
+     * Fetch a single page of records via the adapter's optional `listPage`
+     * extension. Returns the decrypted records for this page plus an opaque
+     * cursor for the next page.
+     *
+     * Pass `cursor: undefined` (or omit it) to start from the beginning.
+     * The final page returns `nextCursor: null`.
+     *
+     * If the adapter does NOT implement `listPage`, this falls back to a
+     * synthetic implementation: it loads all ids via `list()`, sorts them,
+     * and slices a window. The first call emits a one-time console.warn so
+     * developers can spot adapters that should opt into the fast path.
+     */
+    listPage(opts?: {
+        cursor?: string;
+        limit?: number;
+    }): Promise<{
+        items: T[];
+        nextCursor: string | null;
+    }>;
+    /**
+     * Stream every record in the collection page-by-page as an async
+     * iterable, with chainable `.where()` / `.filter()` clauses and a
+     * memory-bounded `.aggregate(spec)` terminal.
+     *
+     * The whole point: process collections larger than RAM without
+     * ever holding more than `pageSize` records decrypted at once.
+     *
+     * @example
+     * ```ts
+     * // Backward-compatible iteration — unchanged from the previous
+     * // async-generator shape. `ScanBuilder` implements AsyncIterable.
+     * for await (const record of invoices.scan({ pageSize: 500 })) {
+     *   await processOne(record)
+     * }
+     *
+     * // — streaming aggregation with O(reducers) memory.
+     * const { total, n } = await invoices.scan()
+     *   .where('year', '==', 2025)
+     *   .aggregate({ total: sum('amount'), n: count() })
+     * ```
+     *
+     * **Lazy-MV gap:** `scan()` is synchronous-build and does
+     * NOT trigger lazy materialized-view resolve-on-read. For lazy
+     * MVs, call `list()` (which DOES resolve) or `vault.refreshView(name)`
+     * before scanning. Same shape as the `query()` limitation.
+     *
+     * Returns a `ScanBuilder<T>` instead of the raw async iterator
+     * that previous versions used. The builder implements
+     * `AsyncIterable<T>`, so every existing `for await … of` call
+     * continues to work unchanged. Direct `.next()` calls on the
+     * iterator — not idiomatic, not used in the codebase — are no
+     * longer supported; upgrade to `for await` or call the new
+     * `.aggregate()` terminal.
+     *
+     * Uses `adapter.listPage` when available; otherwise falls back
+     * to the synthetic pagination path with the same one-time
+     * warning (`listPage()` routes through that fallback internally).
+     */
+    scan(opts?: {
+        pageSize?: number;
+    }): ScanBuilder<T, S, M>;
+    /** Decrypt a page of envelopes returned by `adapter.listPage`. */
+    private decryptPage;
+    /** Load all records from adapter into memory cache. */
+    /**
+     * @internal — refresh the in-memory cache entry for a single id by
+     * re-reading from the adapter. Used by the transaction executor's
+     * Phase-3 revert path: that path writes the prior envelope directly
+     * via the raw store (to avoid re-firing Collection-level side
+     * effects), which would otherwise leave this Collection's eager
+     * cache holding the rolled-back value. After revert, the executor
+     * calls this hook so subsequent `get` / `query` reads see the
+     * actual on-disk state.
+     *
+     * Lazy mode: drops the LRU entry; the next `get` repopulates from
+     * the adapter. Eager mode: re-reads the envelope and either sets
+     * the cache entry (record still present) or deletes it (record was
+     * gone before the tx and the revert deleted it again).
+     */
+    /**
+     * @internal — evict ONLY the per-record CEK cache entry for `id`. Used by
+     * `vault.rotateRecordCek()`: after a hard CEK rotation the cached unwrapped
+     * CEK is stale (it would decrypt the pre-rotation body and fail GCM auth on
+     * the post-rotation body). Eviction must be synchronous with the live-envelope
+     * rewrite so no concurrent read observes the old CEK. Paired with
+     * {@link _invalidateCacheEntry} (which refreshes the decrypted-record cache).
+     * No-op when the collection is not `perRecordKeys`.
+     */
+    _invalidateCekCacheEntry(id: string): void;
+    /** @internal Satellite fan-out revert cleanup (spec #591): drop the sync dirty entry ('revert' is
+     *  onDirty-channel-only) and re-announce the RESTORED state as a plain put/delete — `subscribe()`
+     *  only understands those two actions, and the restored record may exist again. */
+    _compensateRevertedWrite(id: string): Promise<void>;
+    _invalidateCacheEntry(id: string): Promise<void>;
+    /**
+     * Apply a peer tab's committed write to THIS tab's in-memory view:
+     * re-read the (already-persisted) envelope from the shared store + refresh
+     * cache/indexes, then emit a `change` event so reactive consumers re-render.
+     * Never writes to the store and never fires write hooks, so it cannot loop.
+     */
+    _applyRemoteChange(id: string, action: 'put' | 'delete'): Promise<void>;
+    /**
+     * Origin-tagged mutation choke point (#623 task 10) — the single dispatch
+     * point every put/delete path funnels through, AFTER its own store write,
+     * to fire the side-effects that path performs today. Each case below
+     * performs EXACTLY the side-effect set the seam-map Part-3 table
+     * (`.superpowers/sdd/seam-map-i18n-pipeline.md`) records for `origin` —
+     * this is a pure parity extraction of existing tails, not a behavior
+     * change. Phase C (#621, #622) plugs the dependency-graph dispatch into
+     * this socket, keyed off `origin`, without every call site having to
+     * learn the graph.
+     *
+     * `restore` is never reached: `Vault.load` / `backup.ts#loadVault` drops
+     * the whole `collectionCache` instead of dispatching per record — the
+     * origin is reserved for phase C.
+     *
+     * @internal
+     */
+    _onRecordMutated(id: string, action: 'put' | 'delete', origin: MutationOrigin, ctx?: {
+        readonly record?: T;
+        readonly version?: number;
+    }): Promise<void>;
+    /** @internal — the current in-memory record without a store read (for conflict capture); also the #640 FK-recovery read on a sync-applied delete — misses on a cold or evicted child (lazy LRU eviction OR an un-hydrated eager collection whose first sync op is a delete), not "lazy-mode" only. */
+    _peekCached(id: string): T | null;
+    private ensureHydrated;
+    /** Hydrate from a pre-loaded snapshot (used by Vault). */
+    hydrateFromSnapshot(records: Record<string, EncryptedEnvelope>): Promise<void>;
+    /**
+     * Rebuild secondary indexes from the current in-memory cache.
+     *
+     * Called after any bulk hydration. Incremental put/delete updates
+     * are handled by `indexes.upsert()` / `indexes.remove()` directly,
+     * so this only fires for full reloads.
+     *
+     * Synchronous and O(N × indexes.size); for the target scale of
+     * 1K–50K records this completes in single-digit milliseconds.
+     */
+    private rebuildEagerIndexesFromCache;
+    /**
+     * Rebuild unique-constraint maps from the current in-memory cache.
+     * Called after any bulk hydration alongside `rebuildEagerIndexesFromCache`.
+     */
+    private rebuildUniqueConstraintsFromCache;
+    /**
+     * Rebuild every declared index from scratch.
+     *
+     * Eager mode: refreshes the in-memory `CollectionIndexes` from the
+     * current cache — O(records × declaredFields).
+     *
+     * Lazy mode: tears down every `_idx/<field>/<recordId>`
+     * side-car, walks the canonical record namespace, and materialises
+     * fresh side-cars for every declared field. The in-memory mirror is
+     * cleared and re-ingested. Intended for two scenarios:
+     *   1. Adding a new indexed field to a collection that already holds
+     *      records — after the schema change, call `rebuildIndexes()` to
+     *      backfill the side-cars.
+     *   2. Recovery from a catastrophic drift (audit noticed many
+     *      `index:write-partial` events, operator wants a clean slate).
+     *
+     * The rebuild is NOT incremental — it's a full bulk-replace. For
+     * per-field drift repair, use `reconcileIndex(field)` instead.
+     */
+    rebuildIndexes(): Promise<void>;
+    /**
+     * Compare the persisted `_idx/<field>/*` side-cars against the
+     * canonical records for a single field, reporting the drift (and
+     * optionally repairing it).
+     *
+     * Lazy mode only. Eager mode throws — the in-memory index cannot
+     * drift.
+     *
+     * `missing` — record ids whose value is indexable but no side-car
+     *   exists. Happens when a `put()` succeeded but the side-car put
+     *   failed (surfaced as `index:write-partial`).
+     * `stale` — side-car ids pointing to a record that no longer exists
+     *   or whose current value no longer matches the side-car body.
+     * `applied` — number of writes that were actually applied (always 0
+     *   when `dryRun: true`).
+     *
+     * Design reference: acceptance criteria.
+     */
+    reconcileIndex(field: string, opts?: {
+        dryRun?: boolean;
+    }): Promise<{
+        field: string;
+        missing: string[];
+        stale: string[];
+        applied: number;
+    }>;
+    /**
+     * Get the in-memory index store. Used by `Query` to short-circuit
+     * `==` and `in` lookups when an index covers the where clause.
+     *
+     * Returns `null` if no indexes are declared on this collection.
+     */
+    getIndexes(): CollectionIndexes | null;
+    /**
+     * Return a `BlobSet` for the given record id.
+     *
+     * No I/O is performed until you call a method on the handle.
+     *
+     * ```ts
+     * const blobs = invoices.blob('inv-001')
+     *
+     * // Upload a PDF (deduplicates automatically, MIME auto-detected)
+     * await blobs.put('receipt.pdf', pdfBytes)
+     *
+     * // List slots
+     * const files = await blobs.list()   // SlotInfo[]
+     *
+     * // Serve as HTTP response (Content-Type, ETag, streaming body)
+     * const res = await blobs.response('receipt.pdf', { inline: true })
+     *
+     * // Publish a named version (amendment versioning)
+     * await blobs.publish('receipt.pdf', 'issued-2025-01')
+     *
+     * // Raw bytes
+     * const bytes = await blobs.get('receipt.pdf')
+     * ```
+     *
+     * Blobs are stored in internal collections (`_blob_slots_*`, `_blob_index`,
+     * `_blob_chunks`, `_blob_versions_*`) that are excluded from queries and
+     * `list()`. Slot metadata uses this collection's DEK; chunk data uses a
+     * vault-shared `_blob` DEK (enabling cross-collection deduplication).
+     */
+    blob(id: string): BlobSet;
+    /** Get all records as encrypted envelopes (for dump). */
+    dumpEnvelopes(): Promise<Record<string, EncryptedEnvelope>>;
+    /**
+     * Apply locale resolution to a record.
+     *
+     * Called from `get()` and `list()` when locale options are present.
+     * Uses the effective locale: per-call `locale` takes precedence over
+     * `this.defaultLocale`.
+     *
+     * - i18nText fields: replaced with the resolved string (or the full
+     *   map when `locale === 'raw'`).
+     * - dictKey fields: `<field>Label` virtual fields added.
+     *
+     * Returns the record unchanged when no Via pipeline is compiled (#638 Task 7:
+     * was money/i18n/dictKey-flag-gated — missed any OTHER binding's `present`
+     * hook, e.g. the `computed` via-binding's virtual-mode read-time compute;
+     * `this.via` truthiness is the general condition every binding's presence
+     * already implies).
+     */
+    private applyLocaleToRecord;
+    /**
+     * Low-level: encrypt a pre-serialised JSON string into an EncryptedEnvelope.
+     * Used by both the normal record path and the CRDT path (which serialises
+     * a CrdtState rather than a T).
+     */
+    /**
+     * Write / update / delete the `_idx/<field>/<recordId>` side-cars for
+     * every declared persistence-index field on this collection after a
+     * successful main-record `put()`.
+     *
+     * Timing: called AFTER `adapter.put()` of the main record succeeds, so
+     * a failed main write never leaves a stale index entry. Side-car write
+     * failures do NOT fail the overall `put()` — the main record is already
+     * durably committed. Per-field failures surface as
+     * `IndexWriteFailureError` on the emitter's `index:write-partial`
+     * channel and the operator runs a reconcile pass later.
+     *
+     * Null/undefined field values are not indexed — matches the
+     * `PersistedCollectionIndex.stringifyKey` contract. If the prior value
+     * was non-null and the new value is null, the side-car is deleted.
+     */
+    private maintainPersistedIndexesOnPut;
+    /**
+     * Tear down `_idx/<field>/<recordId>` side-cars for a deleted record.
+     * Mirror state updates regardless of adapter outcome; adapter failures
+     * surface on `index:write-partial` the same way put does.
+     */
+    private maintainPersistedIndexesOnDelete;
+    /**
+     * @internal — hard-delete this record's persisted `_idx/<field>/<recordId>`
+     * side-cars for the erasure path. `forget()` crypto-shreds the body but
+     * keeps the collection DEK, under which these side-cars are encrypted — so
+     * without this they leave the indexed field VALUES readable after a "forget".
+     *
+     * Content-free: the side-car id is `encodeIdxId(def.key, id)`, so it needs no
+     * body decode (the body is being shredded). Eager mode has no durable side-car
+     * → no-op. The in-memory mirror is left as-is: it is ephemeral (rebuilt from
+     * the now-deleted side-cars on reopen) and live reads skip the tombstone, so a
+     * stale mirror hit cannot surface the erased record. Returns the count deleted
+     * + the `def.key`s whose delete FAILED (residue that still leaks the value).
+     */
+    _purgePersistedIndexes(id: string): Promise<{
+        purged: number;
+        residue: string[];
+    }>;
+    /** Drop a record's encrypted _vec sidecar on erasure (a vector is text-invertible).
+     *  Called by vault.ts forget() inside a resilient try/catch; residue is reported in ForgetResult. */
+    _purgeVector(id: string): Promise<void>;
+    /** Drop the persisted lexical-index blob (forget/erasure): an opaque
+     *  all-records index must not survive crypto-shred. Idempotent; no-op without persist. */
+    _purgeSearchIndex(): Promise<void>;
+    /**
+     * Bulk-load the persisted-index mirror from `_idx/<field>/*` side-cars
+     * on first lazy-mode query. Idempotent — subsequent calls short-circuit
+     * on the `persistedIndexesLoaded` flag.
+     *
+     * Listing the whole id namespace is acceptable here because the caller
+     * has already decided to pay a first-query cost (this is the indexed
+     * equivalent of lazy-mode hydration, not a per-query scan).
+     */
+    private ensurePersistedIndexesLoaded;
+    /**
+     * Walk every declared persisted-index field, run `reconcileIndex`
+     * per the configured policy, and emit `index:reconciled` for each.
+     * Called internally by `ensurePersistedIndexesLoaded()` — exposed as
+     * a private helper for readability, not as a public API (the public
+     * entry points are `reconcileIndex` and `rebuildIndexes`).
+     */
+    private autoReconcile;
+    /**
+     * Construct a `LazyQuery<T>` bound to this collection. Used by the
+     * lazy-mode branch of `query()` and kept private because callers should
+     * always go through `query()` to pick up the eager/lazy dispatch.
+     */
+    /**
+     * Build a chainable indexed-read query against a lazy-mode collection.
+     *
+     * Companion to `query()`, which is eager-mode only and materialises a
+     * snapshot. `lazyQuery()` dispatches every read through the persisted
+     * index side-cars — no bulk decrypt, no snapshot. Every field touched by
+     * `.where(...)` or `.orderBy(...)` MUST be declared in `indexes`;
+     * otherwise `.toArray()` throws `IndexRequiredError`.
+     *
+     * The returned builder is always Promise-returning on its terminals
+     * (`toArray`, `first`, `count`) because candidate records are decrypted
+     * from the adapter on demand.
+     *
+     * @example
+     * ```ts
+     * const disbursements = vault.collection<Disbursement>('disbursements', {
+     *   prefetch: false,
+     *   cache: { maxRecords: 1000 },
+     *   indexes: ['clientId', 'period'],
+     * })
+     * const rows = await disbursements.lazyQuery()
+     *   .where('clientId', '==', 'c-42')
+     *   .orderBy('period', 'desc')
+     *   .limit(50)
+     *   .toArray()
+     * ```
+     *
+     * Throws at call time when the collection is in eager mode — use
+     * `query()` there. Throws if no index is declared, because a lazy
+     * query with no index would need to enumerate the whole collection.
+     */
+    lazyQuery(): LazyQuery<T, S, Q>;
+    /**
+     * Resolve the stable CEK for a record on the WRITE path — see
+     * {@link resolveStableCek}. Thin delegate that supplies the collection's
+     * CEK cache, live-envelope reader, and DEK resolver.
+     */
+    private resolveRecordCek;
+    /** C-A/R10: persist the classified marker once per classified handle (store I/O in config-drift.ts). */
+    private _ensureClassifiedMarker;
+    /** C-A/R10 drift signal — the marker's declared digest-only set, memoized to one store read per handle (see config-drift.ts). */
+    private _classifiedMarkerDigestOnly;
+    /**
+     * find the first record whose deterministic field matches
+     * the given plaintext. Returns `null` when no match exists.
+     *
+     * Reads every envelope via the adapter and compares the stored
+     * `_det[field]` to a freshly computed deterministic ciphertext — no
+     * record bodies are decrypted during the search, which is the whole
+     * point of a deterministic index.
+     *
+     * Throws when the field is not declared in `deterministicFields`, so a
+     * typo fails loudly at the call site rather than silently returning
+     * null forever.
+     */
+    findByDet(field: string, value: unknown): Promise<T | null>;
+    /**
+     * return every record whose deterministic field matches.
+     * Same semantics as {@link findByDet} but without the short-circuit.
+     */
+    queryByDet(field: string, value: unknown): Promise<T[]>;
+    /** Bind the {@link DeterministicContext} this collection's det lookups need. */
+    private detContext;
+    /** tier-aware put — gated behind `tiersStrategy: withTiers()`. `searchResidue: true` = stuck search compensation (#774, mirroring #764's elevate/demote posture); the write itself always completes. */
+    putAtTier(id: string, record: T, tier: number, opts?: {
+        elevation?: {
+            reason: string;
+            fromTier: number;
+        };
+        source?: string;
+        sourceTs?: string;
+    }): Promise<TierMoveResult>;
+    /** tier-aware get — gated behind `tiersStrategy: withTiers()`. */
+    getAtTier(id: string): Promise<T | GhostRecord | null>;
+    /** list ids grouped by the caller's readability — gated behind `withTiers()`. */
+    listAtTier(): Promise<Array<{
+        id: string;
+        tier: number;
+        readable: boolean;
+    }>>;
+    /** elevate a record to a higher tier — gated behind `withTiers()`. `searchResidue: true` = stuck search compensation (#764); the move itself always completes. */
+    elevate(id: string, toTier: number): Promise<TierMoveResult>;
+    /** demote a record to a lower tier — gated behind `withTiers()`. Same `searchResidue` posture as {@link elevate} (#764). */
+    demote(id: string, toTier: number): Promise<TierMoveResult>;
+    /**
+     * Emit a cross-tier access event. The subscriber sink stays collection-resident (it captures `onCrossTierAccess`); the tiers module reaches it via the {@link TiersContext.emitCrossTierEvent} callback.
+     */
+    private emitCrossTierEvent;
+    /**
+     * Classify a live envelope's `_sealed` slots for crypto-shred completeness
+     * (#M-1, 2026-06-30 security review). Kept as a `_`-prefixed method on
+     * Collection because `vault.ts` forget() reaches in via this name.
+     */
+    _classifySealedShred(live: EncryptedEnvelope): Promise<{
+        readonly slots: readonly SealedShredSlot[];
+    }>;
+    _onViaErase(id: string, live: EncryptedEnvelope): Promise<ViaEraseReport | undefined>;
+    get _via(): ViaPipeline | undefined;
+    _setVia(pipeline: ViaPipeline | undefined): void;
+    get _viaFieldsSnapshot(): {
+        i18nFields: Record<string, I18nTextDescriptor> | undefined;
+        lookupFields: Record<string, LookupDescriptor> | undefined;
+    };
+    _reconcileReadState(patch: {
+        dictKeyFields?: Record<string, DictKeyDescriptor | StaticDictDescriptor>;
+        i18nFields?: Record<string, I18nTextDescriptor>;
+        lookupFields?: Record<string, LookupDescriptor>;
+        getDictionary?: (name: string) => Promise<DictionaryHandle>;
+        presentForJoin?: (record: unknown, locale: string) => unknown;
+    }): void;
+    /**
+     * Bind the {@link TiersContext} the tier ops need — `cekCache` by reference (same `Lru` the read/write path owns) for a synchronous re-wrap; `syncDerived` closes over `this` for {@link syncDerivedOutputs} (#722).
+     */
+    private tiersContext;
+    /**
+     * Bind the {@link IndexingContext} the index-maintenance surface needs. The
+     * eager `cache` Map and the index / unique-constraint / persisted mirrors are
+     * passed by reference (the SAME instances the query path reads, never
+     * copied); the `persistedIndexesLoaded` flag and `ensure*` hydration stay collection-resident, reached via callbacks.
+     */
+    private indexingContext;
+}