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

package/dist/kernel/enclave/record-envelope.d.ts

@@ -0,0 +1,76 @@
+import type { EncryptedEnvelope } from '../types.js';
+import type { RecordIdentity } from './record-aad.js';
+/** The body an envelope carries, independent of who is writing it. */
+export interface RecordEnvelopeBody {
+    /** AES-GCM IV, base64. Empty string for a plaintext or tombstone envelope. */
+    readonly iv: string;
+    /** Ciphertext (or plaintext JSON when the collection stores plaintext). */
+    readonly data: string;
+    /** ISO timestamp. Defaults to now — pass it when the caller has a real one. */
+    readonly ts?: string | undefined;
+    /** Wrapped per-record CEK, when the record has one. */
+    readonly cek?: string | undefined;
+    readonly provenance?: {
+        readonly source: string;
+        readonly sourceTs: string;
+    } | undefined;
+    /**
+     * Slots the envelope may additionally carry.
+     *
+     * `_tier`, `_by` and `_v` are deliberately NOT here — they come from
+     * `identity`, which is the single source for all three. See
+     * {@link buildRecordEnvelope}.
+     */
+    readonly extra?: Partial<Pick<EncryptedEnvelope, '_det' | '_sealed' | '_vdig' | '_bidx'>> | undefined;
+}
+/**
+ * Build an envelope for `identity`.
+ *
+ * ## `identity` is the SINGLE SOURCE for `_by`, `_tier` and `_v`
+ *
+ * All three are stamped from it, and `RecordEnvelopeBody` deliberately cannot
+ * carry them. That is not tidiness — it is what makes the AAD binding safe.
+ *
+ * The caller encrypts the body under AAD derived from `{collection, id, tier,
+ * by, version}`. A reader recomputes that AAD from the address it fetched from
+ * plus `_tier`/`_by`/`_v` read back **off the envelope** (`recordAadFor`). So if the
+ * identity a writer *declares* could differ from the fields it *stamps*, the
+ * AAD would not reproduce and the record would be undecryptable — silently, at
+ * write time, discoverable only on the next read, and invisible to every gate
+ * because the envelope is perfectly well-formed.
+ *
+ * An earlier draft took both and asserted they agreed. The assertion fired 230
+ * times on the existing tree, which is the argument against it: a rule that can
+ * be violated is a rule someone must remember. Taking one source removes the
+ * violation instead of reporting it.
+ */
+export declare function buildRecordEnvelope(identity: RecordIdentity, body: RecordEnvelopeBody): EncryptedEnvelope;
+/**
+ * Build an envelope from an already-sealed body — the output of
+ * `writeEnvelopeBody` — **without the caller ever naming `_iv`/`_data`/`_cek`**.
+ *
+ * This exists because of a guard, and the guard was right. Migrating
+ * `writeEnvelopeBody` callers to {@link buildRecordEnvelope} meant rewriting
+ * `...body` (a spread, which names nothing) into `iv: body._iv, data:
+ * body._data, cek: body._cek` — and `enclave-body-only` failed it: three new
+ * protected-body accesses in files that previously had zero.
+ *
+ * That is the correct outcome rather than an obstacle. #1051 exists to move
+ * knowledge of the envelope's shape *inward*; a migration that spreads the
+ * protected field names outward to every caller would have defeated its own
+ * purpose while looking like progress. The pairing belongs here.
+ *
+ * ## It takes a SEALER, not a sealed body — and that is load-bearing (#1041)
+ *
+ * The obvious shape is `(identity, alreadySealedBody, rest)`. That requires the
+ * caller to name the identity TWICE — once for `writeEnvelopeBody` and once
+ * here — and the two must agree byte for byte or the record is sealed under
+ * AAD no reader can reproduce.
+ *
+ * They did not agree. `with-party/broker/seed.ts` sealed against
+ * `{collection, id}` and stamped `{collection, id, by}`, so every broker seed
+ * became unreadable the moment AAD switched on. Taking the sealer means the
+ * identity is written once and handed to both — divergence stops being
+ * possible rather than being something to remember.
+ */
+export declare function buildSealedRecordEnvelope(identity: RecordIdentity, seal: (identity: RecordIdentity) => Promise<Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>>, body: Omit<RecordEnvelopeBody, 'iv' | 'data' | 'cek'>): Promise<EncryptedEnvelope>;

package/dist/kernel/enclave/record-keys/envelope-body.d.ts

@@ -13,6 +13,7 @@
  * per-function doc for its oracle call site) — this file introduces no new
  * crypto or semantics, only a narrower door onto what already runs.
  */
+import { type RecordIdentity, type RecordRef } from '../record-aad.js';
 import { type EnclaveKey } from '../crypto.js';
 import type { EncryptedEnvelope } from '../../types.js';
 /**
@@ -27,7 +28,7 @@ import type { EncryptedEnvelope } from '../../types.js';
  *    (the collection DEK), decrypt the body under the unwrapped CEK.
  *  - `env._cek` absent → legacy path, decrypt the body directly under `key`.
  */
-export declare function openEnvelopeJson(env: EncryptedEnvelope, key: EnclaveKey, opts?: {
+export declare function openEnvelopeJson(ref: RecordRef, env: EncryptedEnvelope, key: EnclaveKey, opts?: {
     encrypted?: boolean;
 }): Promise<string>;
 /**
@@ -43,7 +44,7 @@ export declare function openEnvelopeJson(env: EncryptedEnvelope, key: EnclaveKey
  *    generated here rather than supplied by the caller).
  *  - otherwise → legacy path, body encrypted directly under `key`.
  */
-export declare function writeEnvelopeBody(json: string, key: EnclaveKey, opts?: {
+export declare function writeEnvelopeBody(identity: RecordIdentity, json: string, key: EnclaveKey, opts?: {
     encrypted?: boolean;
     perRecordKey?: boolean;
 }): Promise<Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>>;
@@ -85,3 +86,34 @@ export declare function hasPerRecordKey(env: EncryptedEnvelope): boolean;
  * `envelope-body.test.ts`).
  */
 export declare function envelopeBodyForHash(env: EncryptedEnvelope): string;
+/**
+ * Does `env` carry an AEAD-sealed body at all?
+ *
+ * The one question callers outside the enclave legitimately need to ask about
+ * `_iv` — a tombstone and a plaintext-collection record have none, so there is
+ * nothing to authenticate and nothing to re-seal. Both {@link
+ * verifyRecordIdentity} (which treats them as vacuously authentic) and the
+ * merge authority's `advance` (which stamps them without re-sealing) turn on
+ * it, and asking it here keeps `_iv` from leaking back out to the callers —
+ * which `enclave-body-only` refused, correctly, when `advance` tested it inline.
+ */
+export declare function hasSealedBody(env: Pick<EncryptedEnvelope, '_iv'>): boolean;
+/**
+ * Does `env` authenticate at the identity `ref` claims, under `key`? (#1042)
+ *
+ * The merge's fail-closed check, living here because it is envelope surgery:
+ * deciding "is there a sealed body at all" reads `_iv`, which
+ * `enclave-body-only` reserves to this folder. An earlier draft did that test
+ * in `kernel/noydb.ts` and the guard refused it — correctly, since a caller
+ * outside the enclave inspecting protected fields is how envelope knowledge
+ * leaks back out.
+ *
+ * Returns a boolean rather than throwing: `applyRemote` must be able to reject
+ * one poisoned record without halting an entire sync, and a hostile store
+ * would very much like the opposite.
+ *
+ * **A record with no sealed body is vacuously authentic** — a tombstone carries
+ * none, and a plaintext collection has no AEAD to verify. Those are pass-through
+ * by construction, not by omission.
+ */
+export declare function verifyRecordIdentity(ref: RecordRef, env: EncryptedEnvelope, key: EnclaveKey): Promise<boolean>;

package/dist/kernel/enclave/record-keys/lifecycle.d.ts

@@ -21,6 +21,7 @@
  */
 import { type EnclaveKey } from '../crypto.js';
 import type { EncryptedEnvelope } from '../../types.js';
+import { type RecordIdentity } from '../record-aad.js';
 import type { Lru } from '../../cache/index.js';
 /** Dependencies {@link resolveStableCek} needs from its collection. */
 export interface StableCekDeps {
@@ -46,15 +47,31 @@ export interface RewrappedBody {
     readonly cek: EnclaveKey | null;
 }
 /**
- * Move a record body from `fromDek` to `toDek`.
+ * Move a record body from `fromDek`/`from` to `toDek`/`to`.
  *
  * - Per-record-key record (`_cek` present): unwrap the CEK under `fromDek`,
  *   re-encrypt the body under the SAME CEK, re-wrap the CEK under `toDek`. The
  *   body key is unchanged → history-chain identity preserved.
  * - Legacy record (no `_cek`): decrypt under `fromDek`, re-encrypt under `toDek`
- *   directly — byte-for-byte the pre-CEK behaviour.
+ *   directly.
+ *
+ * ## Why it takes TWO identities (#1041)
+ *
+ * A rewrap is the one operation where the identity genuinely **changes**. A
+ * tier move rewrites `_tier`; a history snapshot lands at a different
+ * `(collection, id)` entirely. Since AAD binds both, the body must be opened
+ * under the identity it currently has and re-sealed under the one it is moving
+ * to. A single identity would be wrong for one end or the other.
+ *
+ * ⚠️ **This retires an optimisation, deliberately.** Callers used to compute
+ * ONE rewrap and reuse the bytes for both a tier move's live write and its
+ * `_history` snapshot (#728). Those now have different destination identities,
+ * so they need different AAD and therefore different ciphertext — the same
+ * bytes cannot satisfy both. Reusing one rewrap for two destinations is now a
+ * silent corruption, not a saving: it produces a record that opens at one
+ * address and not the other.
  */
-export declare function rewrapBodyToDek(envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>, fromDek: EnclaveKey, toDek: EnclaveKey): Promise<RewrappedBody>;
+export declare function rewrapBodyToDek(from: RecordIdentity, to: RecordIdentity, envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek' | '_tier' | '_by'>, fromDek: EnclaveKey, toDek: EnclaveKey): Promise<RewrappedBody>;
 /**
  * Merge an ALREADY-rewrapped {@link RewrappedBody} into `envelope`, keeping
  * every field but the re-keyed body (`_iv`/`_data`/`_cek`) unchanged.
@@ -76,7 +93,7 @@ export declare function applyRewrappedBody(envelope: EncryptedEnvelope, body: Re
  * envelope, generalized to any envelope shape (history callers don't bump
  * `_v`/`_ts`/`_tier` the way a tier move does).
  */
-export declare function rewrapEnvelope(envelope: EncryptedEnvelope, fromDek: EnclaveKey, toDek: EnclaveKey): Promise<EncryptedEnvelope>;
+export declare function rewrapEnvelope(identity: RecordIdentity, envelope: EncryptedEnvelope, fromDek: EnclaveKey, toDek: EnclaveKey): Promise<EncryptedEnvelope>;
 /**
  * Is `envelope` ALREADY wrapped under `dek` (a per-record CEK wrapped under
  * `dek`, or — legacy, no `_cek` — the body itself decryptable under `dek`)?
@@ -104,4 +121,4 @@ export declare function rewrapEnvelope(envelope: EncryptedEnvelope, fromDek: Enc
  * those fields themselves, preserving the check-architecture body-access
  * ratchet.
  */
-export declare function isRewrappedUnder(envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>, dek: EnclaveKey): Promise<boolean>;
+export declare function isRewrappedUnder(identity: RecordIdentity, envelope: Pick<EncryptedEnvelope, '_iv' | '_data' | '_cek'>, dek: EnclaveKey): Promise<boolean>;

package/dist/kernel/enclave/record-keys/record-codec.d.ts

@@ -18,6 +18,7 @@
  */
 import { type EnclaveKey } from '../crypto.js';
 import { type EncryptedEnvelope, type CrdtMode, type CrdtStrategy, type VdigFieldPolicy, type SealedHandle } from '../../types.js';
+import { type RecordIdentity, type RecordRef } from '../record-aad.js';
 import { type StandardSchemaV1 } from '../../schema.js';
 import type { Lru } from '../../cache/index.js';
 import type { ViaCryptoCtx } from '../../via/index.js';
@@ -127,11 +128,9 @@ export declare class RecordCodec<T> {
      * parts. Pure, no crypto. Each call stamps its own `_ts` — provenance carries
      * a SEPARATE timestamp (computed by the caller), so the two never share one.
      */
-    static buildEnvelope(p: {
-        version: number;
+    static buildEnvelope(identity: RecordIdentity, p: {
         iv: string;
         data: string;
-        by?: string;
         cek?: string;
         provenance?: {
             source: string;
@@ -140,10 +139,8 @@ export declare class RecordCodec<T> {
         extra?: Partial<Pick<EncryptedEnvelope, '_tier' | '_det' | '_sealed'>>;
     }): EncryptedEnvelope;
     /** Plaintext (`_iv:''`) body envelope — the `!storeCiphertext` shape. */
-    static buildPlaintextEnvelope(p: {
-        version: number;
+    static buildPlaintextEnvelope(identity: RecordIdentity, p: {
         data: string;
-        by?: string;
         provenance?: {
             source: string;
             sourceTs: string;
@@ -157,7 +154,7 @@ export declare class RecordCodec<T> {
      * (see {@link encryptRecord}). Rejects `_`-prefixed record fields, which
      * would collide with the reserved metadata namespace.
      */
-    buildDebugEnvelope(record: T, version: number, source?: string, sourceTs?: string): EncryptedEnvelope;
+    buildDebugEnvelope(id: string, record: T, version: number, source?: string, sourceTs?: string): EncryptedEnvelope;
     /**
      * Encrypt a JSON body into an envelope.
      *
@@ -167,11 +164,41 @@ export declare class RecordCodec<T> {
      * path encrypts the body directly under the collection DEK — byte-identical
      * to pre-CEK behaviour, so non-adopting collections pay nothing.
      */
-    encryptJsonString(json: string, version: number, cek?: EnclaveKey, source?: string, sourceTs?: string): Promise<EncryptedEnvelope>;
-    encryptRecord(record: T, version: number, cek?: EnclaveKey, source?: string, sourceTs?: string, vdig?: {
+    /**
+     * `ref` is the identity the envelope is sealed against, and it is **the
+     * location the bytes are stored at** — not necessarily this codec's own
+     * collection (#1051).
+     *
+     * That distinction was discovered here rather than assumed. Several callers
+     * put the result somewhere else entirely: search's vector sidecar lands in
+     * `_vec` under `encodeVecId(name, id)`, the lexical index under `_ft/<name>`,
+     * indexing's entries under a synthetic `idxId`. A codec that supplied
+     * `this.ctx.name` for those would seal them against a collection they are not
+     * in, and once AAD binds identity every one of them would fail to verify.
+     *
+     * ⚠️ **`_history` is the open case, and it is #1041's to settle.** Snapshots
+     * are produced with the LIVE record's identity here and then re-homed by
+     * `saveHistory` into `_history/<historyId(collection,id,_v)>`. Both readings
+     * are defensible — bind where it lives, or bind what it is a copy of — and
+     * the choice must be made before AAD is switched on, not inferred from this
+     * migration.
+     */
+    encryptJsonString(ref: RecordRef, json: string, version: number, cek?: EnclaveKey, source?: string, sourceTs?: string): Promise<EncryptedEnvelope>;
+    /**
+     * `ref` is FIRST and required (#1051). It was previously a trailing optional
+     * `id?: string`, which TypeScript cannot promote to required because it sits
+     * after other optionals — so the migration would have needed an `id ?? ''`
+     * fallback. That is exactly the silent default this issue exists to remove:
+     * once identity is bound into the AEAD, every record written with an empty id
+     * binds to the SAME identity and becomes interchangeable with the others.
+     * An object, not a bare string, so a swap with `version`/`source` cannot
+     * compile on the hottest write path. Carries the collection too — see
+     * {@link encryptJsonString} for why the codec must not assume its own.
+     */
+    encryptRecord(ref: RecordRef, record: T, version: number, cek?: EnclaveKey, source?: string, sourceTs?: string, vdig?: {
         readonly id: string;
         readonly prev: EncryptedEnvelope | null;
-    }, id?: string): Promise<EncryptedEnvelope>;
+    }): Promise<EncryptedEnvelope>;
     /**
      * Resolve the per-record CEK for a stored envelope, or `undefined` for a
      * legacy (`_cek`-absent) envelope. Unwraps `_cek` under the collection DEK and
@@ -195,7 +222,14 @@ export declare class RecordCodec<T> {
      * The optional `id` lets reads populate the CEK cache; it is omitted by
      * callers (history, conflict merge) that have only the envelope.
      */
-    decryptJsonString(envelope: EncryptedEnvelope, id?: string): Promise<string | null>;
+    /**
+     * `ref` must be the SAME identity the writer sealed against — which is the
+     * storage address, not necessarily this codec's own collection. Search's
+     * vector sidecar lives in `_vec`, its lexical index in `_ft`; passing
+     * `this.ctx.name` for those would recompute the wrong AAD and fail to open a
+     * perfectly good record (#1041).
+     */
+    decryptJsonString(ref: RecordRef, envelope: EncryptedEnvelope): Promise<string | null>;
     /**
      * Unseal a single `_sealed[field]` slot to its plaintext value: derive the
      * per-field key off the collection DEK, AES-GCM-decrypt the `iv:data` blob,
@@ -304,7 +338,7 @@ export declare class RecordCodec<T> {
      * output-recompute path, not the public per-record read surface schema
      * validation guards.
      */
-    decryptRecordAtDek(envelope: EncryptedEnvelope, dek: EnclaveKey, id?: string): Promise<T | null>;
+    decryptRecordAtDek(ref: RecordRef, envelope: EncryptedEnvelope, dek: EnclaveKey): Promise<T | null>;
     /**
      * Decrypt an envelope into a record of type `T`.
      *
@@ -320,9 +354,8 @@ export declare class RecordCodec<T> {
      * that may predate a schema change, so validating it would be a
      * false positive. Every non-history read leaves this flag `false`.
      */
-    decryptRecord(envelope: EncryptedEnvelope, opts?: {
+    decryptRecord(ref: RecordRef, envelope: EncryptedEnvelope, opts?: {
         skipValidation?: boolean;
-        id?: string;
         sealedAsHandles?: boolean;
     }): Promise<T | null>;
 }

package/dist/kernel/enclave/record-keys/rekey-blob.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Re-key a vault's blob set from an old `_blob` DEK to a new one (#1122).
+ *
+ * ## The defect this closes
+ *
+ * `rotateKeys` re-keys `store.list(vault, <slot>)` plus the derived refs
+ * `derivedRefsFor` declares. That assumes a DEK slot named `X` protects data
+ * filed under collection `X`. For `_blob` it is false: the slot is `_blob`, but
+ * every byte it protects lives in `_blob_index` and `_blob_chunks`. So rotating
+ * `_blob` minted a fresh DEK, re-encrypted **nothing**, and made every blob in
+ * the vault permanently unreadable — reported to the user as `TamperedError`,
+ * i.e. as an attack, when it was self-inflicted. An ordinary `revoke` of a
+ * whole-vault grantee reaches it, because such a grantee's DEK map contains
+ * `_blob`.
+ *
+ * ## Why this cannot be done by `rekeyEnvelopeIfNeeded` alone
+ *
+ * Two of the three surfaces do not have the shape that helper assumes:
+ *
+ * - a **chunk** envelope is sealed over raw bytes under a bespoke AAD
+ *   (`{eTag}:{index}:{count}`), not under the record AAD, so the generic
+ *   helper cannot open it;
+ * - an **index** envelope's body is JSON that may itself carry a wrapped
+ *   per-blob content CEK (`_cek` / `_cekPending`). Re-encrypting the body under
+ *   the new DEK without re-wrapping that CEK leaves a blob whose metadata opens
+ *   and whose bytes never will.
+ *
+ * ## Why it lives in the enclave
+ *
+ * It reads and writes protected body slots and it unwraps/re-wraps keys — the
+ * two things `enclave-body-only` reserves to `kernel/enclave/**`, and the same
+ * reason `rekeyEnvelopeToDek` moved here in #1074. `with-party` orchestrates
+ * the rotation and must not touch a body to do it.
+ *
+ * The blob layout below is duplicated from its owner rather than imported:
+ * `with-shape/blobs/blob-set.ts` already imports `with-party/team/tiers.js`, so
+ * a `with-party → with-shape` import would close a cycle, and the kernel may
+ * not depend on a service. `BlobObject` itself is a kernel type, so only the
+ * three collection/id string layouts are copied, with their owner named.
+ *
+ * @packageDocumentation
+ */
+import { type EnclaveKey } from '../crypto.js';
+import type { NoydbStore } from '../../types.js';
+/**
+ * What a rotation did to the blob set.
+ *
+ * Deliberately NOT on the enclave barrel: no caller outside this module binds
+ * it, and that surface is the fork-swap trust boundary, so exporting a type
+ * nobody consumes is pure widening.
+ *
+ * It is a return value rather than a log line because `foreign` and `blobs`
+ * are the only way to tell "left alone, correctly" from "left alone, because
+ * the caller passed a wrong `otherDeks` set". Both re-key nothing and both
+ * return successfully. `rotate-preserves-blobs.test.ts` asserts these counts
+ * against a direct call for exactly that reason.
+ */
+export interface BlobRekeyReport {
+    /** Index envelopes moved onto the new DEK. */
+    readonly blobs: number;
+    /** Chunk envelopes re-encrypted under the new DEK. */
+    readonly chunks: number;
+    /**
+     * Index envelopes left alone because they open under a DEK the caller holds
+     * for a DIFFERENT slot — an elevated blob, sealed under `_blob#<tier>`. Those
+     * are that slot's rotation to do, not this one's.
+     */
+    readonly foreign: number;
+    /** Index envelopes already under the new DEK — a resumed rotation. */
+    readonly alreadyMoved: number;
+}
+/**
+ * Move every blob sealed under `oldDek` onto `newDek`.
+ *
+ * Chunks are re-encrypted BEFORE their index entry is re-sealed, and that order
+ * is the resume property: an index entry still readable under `oldDek` means
+ * its chunks may be half-moved (each one is probed individually), and an index
+ * entry readable under `newDek` means its chunks are already done. An
+ * interrupted rotation is finished by re-running it with the same `newDek`.
+ *
+ * `otherDeks` is what keeps a tier-elevated blob from being mistaken for a
+ * damaged one. Membership in `_blob_index` is by DEK, not by collection name:
+ * a record elevated to tier N has its blob metadata sealed under `_blob#N`. An
+ * envelope that opens under NONE of the keys the caller holds is genuinely
+ * unreadable and throws, exactly as `rekeyEnvelopeIfNeeded` does — silently
+ * walking past it would turn a loud failure into permanent quiet loss.
+ */
+export declare function rekeyBlobSet(adapter: NoydbStore, vault: string, oldDek: EnclaveKey, newDek: EnclaveKey, otherDeks?: readonly EnclaveKey[]): Promise<BlobRekeyReport>;

package/dist/kernel/enclave/record-keys/rekey.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Re-key one envelope from an old collection DEK to a new one (#1074).
+ *
+ * Lives in the enclave because it is envelope surgery: it reads and writes the
+ * protected body slots (`_iv`/`_data`/`_cek`), which `enclave-body-only`
+ * reserves to `kernel/enclave/**`. `rotateKeys` previously did this inline in
+ * `with-party/team/keyring.ts` and got it wrong in two ways that the guard
+ * would have caught had the code lived here.
+ *
+ * @packageDocumentation
+ */
+import { type EnclaveKey } from '../crypto.js';
+import type { EncryptedEnvelope } from '../../types.js';
+/**
+ * Produce the envelope `envelope` becomes once its collection's DEK rotates
+ * from `oldDek` to `newDek`.
+ *
+ * **Every slot is carried forward except `_bidx`.** The previous inline version
+ * built a fresh literal holding only `_noydb/_v/_ts/_iv/_data`, silently
+ * discarding `_by`, `_tier`, `_cek`, `_sealed`, `_vdig` and `_source`. Losing
+ * `_tier` was the worst of those: tier-0 reads treat elevated as missing, so an
+ * elevated record did not error after a rotation — it simply disappeared.
+ *
+ * `_bidx` is dropped deliberately. It is a DEK-rooted equality tag, so a tag
+ * carried across a DEK rotation can never be re-derived to match a query again
+ * while still leaking the old equality partition. Index coverage regrows
+ * per-record on the next `put()` under the new DEK.
+ *
+ * Two shapes, and picking the wrong one is why this needed a helper:
+ *
+ * - **per-record CEK** (`_cek` present) — the body is sealed under the CEK and
+ *   the CEK is wrapped under the collection DEK, so rotation re-wraps the CEK
+ *   and leaves the body **untouched**. The old inline code instead ran
+ *   `decrypt(body, oldDek)` on these, which throws: rotation could not complete
+ *   on a collection containing any CEK record.
+ * - **bare** — body sealed directly under the DEK, so decrypt and re-encrypt.
+ *
+ * Idempotence is the caller's problem, not this function's: it assumes
+ * `envelope` is still under `oldDek`. A resumable rotation must know which side
+ * of the migration each record is on before calling.
+ */
+export declare function rekeyEnvelopeToDek(ref: {
+    readonly collection: string;
+    readonly id: string;
+}, envelope: EncryptedEnvelope, oldDek: EnclaveKey, newDek: EnclaveKey): Promise<EncryptedEnvelope>;
+/**
+ * Resumable variant: returns the re-keyed envelope, or `null` when `envelope`
+ * is **already** under `newDek` and needs no work (#1074 part 2).
+ *
+ * A rotation interrupted mid-collection leaves records on both sides of the
+ * migration. Resuming means re-running the rotation with the *same* new DEK,
+ * which requires distinguishing "not yet moved" from "already moved" without
+ * the caller touching protected slots.
+ *
+ * Detection is by trial decryption under `oldDek`. There is no metadata that
+ * says which DEK sealed a record — deliberately, since such a marker would be
+ * store-writable and therefore a downgrade lever (the same reasoning that
+ * keeps the reader from branching on `_noydb`).
+ *
+ * A record that opens under *neither* key is genuinely damaged and rethrows,
+ * rather than being silently skipped: a rotation that quietly walked past
+ * unreadable records would convert a loud failure into permanent silent loss,
+ * which is the defect this whole issue is about.
+ */
+export declare function rekeyEnvelopeIfNeeded(ref: {
+    readonly collection: string;
+    readonly id: string;
+}, envelope: EncryptedEnvelope, oldDek: EnclaveKey, newDek: EnclaveKey): Promise<EncryptedEnvelope | null>;

package/dist/kernel/enclave/record-keys/tombstone.d.ts

@@ -16,6 +16,7 @@
  * vault; it calls into these.
  */
 import { type EncryptedEnvelope } from '../../types.js';
+import type { RecordRef } from '../record-aad.js';
 /**
  * Shape-only tombstone recognition for layers that have no per-collection
  * context (the sync engine, #590): a tombstone carries an empty `_data` and
@@ -45,7 +46,7 @@ export declare function isTombstone(envelope: EncryptedEnvelope, encrypted: bool
  * Deliberately omits `_iv`/`_data`/`_cek`/`_det` — that omission *is* the
  * erasure.
  */
-export declare function buildTombstone(version: number, actor: string): EncryptedEnvelope;
+export declare function buildTombstone(ref: RecordRef, version: number, actor: string): EncryptedEnvelope;
 /** #589: is this envelope an ordinary-delete marker (version-ordered, reads as absent)? */
 export declare function isDeleteMarker(envelope: EncryptedEnvelope): boolean;
 /**
@@ -54,4 +55,4 @@ export declare function isDeleteMarker(envelope: EncryptedEnvelope): boolean;
  * keeps the displaced `_v` — so it wins convergence over the pre-delete copy and a
  * re-create can still win over it at a higher version.
  */
-export declare function buildDeleteMarker(version: number, actor: string): EncryptedEnvelope;
+export declare function buildDeleteMarker(ref: RecordRef, version: number, actor: string): EncryptedEnvelope;

package/dist/kernel/errors.d.ts

@@ -10,7 +10,9 @@
  *       ├─ Crypto errors
  *       │    ├─ DecryptionError        — AES-GCM tag failure
  *       │    ├─ TamperedError          — ciphertext modified after write
- *       │    └─ InvalidKeyError        — wrong secret / corrupt keyring
+ *       │    ├─ InvalidKeyError        — wrong secret / corrupt keyring
+ *       │    ├─ KeyringCorruptError    — partial DEK corruption, KEK correct
+ *       │    └─ KeyringTamperedError   — keyring roster failed authentication (#1096)
  *       ├─ Access errors
  *       │    ├─ NoAccessError          — no DEK for this collection
  *       │    ├─ ReadOnlyError          — ro permission, write attempted
@@ -52,7 +54,7 @@
  *       │    ├─ BackupLedgerError      — hash-chain verification failed
  *       │    └─ BackupCorruptedError   — envelope hash mismatch in dump
  *       ├─ Bundle errors
- *       │    └─ BundleIntegrityError   — .noydb body sha256 mismatch
+ *       │    └─ PodIntegrityError   — .noydb body sha256 mismatch
  *       ├─ Session errors
  *       │    ├─ SessionExpiredError
  *       │    ├─ SessionNotFoundError
@@ -143,7 +145,23 @@ export declare class DecryptionError extends NoydbError {
  * Treat it as a security alert: the stored bytes are not what NOYDB wrote.
  */
 export declare class TamperedError extends NoydbError {
-    constructor(message?: string);
+    /**
+     * Why the tag check failed, when the enclave could tell (#1103).
+     *
+     * `'unbound-legacy-format'` — the body opens under an EMPTY AAD, so it was
+     * sealed before identity binding (#1041) and this is a format transition, not
+     * an attack. Positive evidence, not a guess: producing a body that decrypts
+     * under this DEK requires the DEK, which an untrusted store does not hold.
+     *
+     * Absent — no benign explanation was found. Treat as the security alert this
+     * error has always been.
+     *
+     * The field is additive and the throw is unchanged, so
+     * `catch (e) { if (e instanceof TamperedError) … }` keeps working; callers
+     * that want to tell a migration from a breach can now read this.
+     */
+    readonly reason?: 'unbound-legacy-format';
+    constructor(message?: string, reason?: 'unbound-legacy-format');
 }
 /**
  * Thrown when key unwrapping fails, typically because the secret is wrong
@@ -177,6 +195,51 @@ export declare class KeyringCorruptError extends NoydbError {
         message?: string;
     });
 }
+/**
+ * #1096 — the keyring's plaintext AUTHORITY half failed authentication.
+ *
+ * Thrown by `loadKeyring` when the canary is absent, when the reserved
+ * roster-key DEK entry is absent, or when the keys check out (KEK proven
+ * correct) but `roster_tag` is missing or does not match the file.
+ *
+ * Distinct from {@link KeyringCorruptError}: the KEYS are fine; the ROSTER —
+ * `role`, `permissions`, `granted_by`, the capability grants — is what cannot
+ * be trusted. A `_keyring` file is stored plaintext so admins can edit a
+ * member's authority without holding that member's credential, which left
+ * those fields authenticated by nothing; this error is what a hostile store
+ * editing them now produces.
+ *
+ * Deliberately raised only AFTER the key-unwrap epilogue, so a plain
+ * wrong-secret keeps reporting as `InvalidKeyError` and is never
+ * misannounced to the user as an attack.
+ */
+/**
+ * Why a `_keyring` file failed roster authentication (#1096).
+ *
+ * Named rather than inlined because a third consumer now reports it without
+ * throwing: `RotateResult.unverified` (#1114) lists the members a rotation
+ * skipped, and a union duplicated per call site drifts.
+ */
+export type KeyringTamperedReason = 'canary-missing' | 'roster-key-missing' | 'roster-tag-missing' | 'roster-tag-mismatch'
+/**
+ * The file did not parse at all (#1121). Never thrown by
+ * `assertRosterAuthenticated` — which cannot reach a file it could not read —
+ * but reported by `verifyRoster` and accepted by `quarantineKeyring`, because
+ * truncation and bitrot produce the most literally unauthenticatable file
+ * there is and the tools for unauthenticatable files must not be the ones
+ * that choke on it.
+ */
+ | 'unparseable';
+export declare class KeyringTamperedError extends NoydbError {
+    readonly details: {
+        readonly userId: string;
+        readonly reason: KeyringTamperedReason;
+    };
+    constructor(details: {
+        readonly userId: string;
+        readonly reason: KeyringTamperedReason;
+    });
+}
 /**
  * Thrown when the authenticated user does not have a DEK for the requested
  * collection — i.e. the collection is not in their keyring at all.
@@ -277,7 +340,7 @@ export declare class ExportCapabilityError extends NoydbError {
  * can show a precise "this bundle slot has expired" message instead
  * of the generic decryption-failure UX.
  *
- * Used predominantly on `BundleRecipient` slots produced by
+ * Used predominantly on `PodRecipient` slots produced by
  * `writePod({ recipients: [...] })` to time-box audit access.
  */
 export declare class KeyringExpiredError extends NoydbError {
@@ -759,10 +822,6 @@ export declare class PodVersionConflictError extends NoydbError {
     readonly remoteVersion: string;
     constructor(remoteVersion: string, message?: string);
 }
-/** @deprecated Use `PodVersionConflictError`. */
-export declare const BundleVersionConflictError: typeof PodVersionConflictError;
-/** @deprecated Use `PodVersionConflictError`. */
-export type BundleVersionConflictError = PodVersionConflictError;
 /**
  * Thrown when a sync operation (push or pull) fails due to a network error.
  *
@@ -1012,7 +1071,7 @@ export declare class FieldNotQueryableError extends NoydbError {
  * format violations like a missing magic prefix or malformed
  * header JSON) so consumers can pattern-match the corruption case
  * and handle it differently from a producer bug. A
- * `BundleIntegrityError` indicates "the bytes you got are not
+ * `PodIntegrityError` indicates "the bytes you got are not
  * what was written"; a plain `Error` from `parsePrefixAndHeader`
  * indicates "what was written wasn't a valid bundle in the first
  * place."
@@ -1022,7 +1081,7 @@ export declare class FieldNotQueryableError extends NoydbError {
  * written) but it surfaces with the same error class because the
  * end result is "the body cannot be turned back into a dump."
  */
-export declare class BundleIntegrityError extends NoydbError {
+export declare class PodIntegrityError extends NoydbError {
     constructor(message: string);
 }
 /**
@@ -1046,7 +1105,7 @@ export declare class PodHeaderVerificationError extends NoydbError {
  * surface an actionable prompt:
  *
  * ```
- * BundleSealMismatchError: bundle carries sealed secret for user "alice"
+ * PodSealMismatchError: bundle carries sealed secret for user "alice"
  *   under provider "macos-keychain:com.acme.app/alice@acme.example",
  *   but no registered provider matches that pid.
  * ```
@@ -1059,7 +1118,7 @@ export declare class PodHeaderVerificationError extends NoydbError {
  * 3. Inspect without unsealing — pass no `sealingProviders` to
  *    receive the sealed entries unmodified for offline analysis.
  */
-export declare class BundleSealMismatchError extends NoydbError {
+export declare class PodSealMismatchError extends NoydbError {
     readonly userId: string;
     readonly pid: string;
     constructor(userId: string, pid: string);