@noy-db/hub 0.7.0 → 0.8.0-pre.0

package/dist/with-lookup/search/serialize.d.ts

@@ -1,4 +1,30 @@
-/** (De)serialize an InvertedIndex to/from a JSON string for persistence (L1.5). */
-import { InvertedIndex } from './inverted-index.js';
+/**
+ * (De)serialize an InvertedIndex to/from a JSON string for persistence (L1.5).
+ *
+ * ## Why a validator, and why its failure mode is "rebuild" (#1354)
+ *
+ * Positional postings changed the persisted shape, so this module adopts the
+ * discipline #1359 established for the field-index sidecars: a blob is used
+ * only if it is EXACTLY the current format, and anything else is discarded
+ * whole and rebuilt from the record cache. There is no migration path and no
+ * partial load, because a half-trusted index answers confidently and wrongly —
+ * a pre-#1354 blob read leniently would report "no positions here", which a
+ * phrase query cannot distinguish from "your phrase is not in this record".
+ *
+ * ⭐ An out-of-order position list is REJECTED, not re-sorted. Re-sorting would
+ * launder a corrupt blob into a plausible-looking answer; the cache can always
+ * rebuild the truth.
+ */
+import { InvertedIndex, type IndexSnapshot } from './inverted-index.js';
 export declare function serializeIndex(idx: InvertedIndex): string;
-export declare function deserializeIndex(json: string): InvertedIndex;
+/** `null` ⇒ the blob is unusable and the caller must rebuild. Never throws. */
+export declare function deserializeIndex(json: string): InvertedIndex | null;
+/**
+ * Decode + structurally validate a persisted index snapshot. Returns `null` for
+ * anything that is not exactly the current format: torn JSON, a stamp from
+ * another release, a shape mismatch, a position list that is not strictly
+ * ascending or that names a token the doc does not have, or a `pos`/`posFields`
+ * disagreement (a doc whose field opted in but carries no positions would make
+ * every phrase query silently miss it).
+ */
+export declare function parseIndexSnapshot(json: string): IndexSnapshot | null;

package/dist/with-lookup/search/strategy.d.ts

@@ -16,15 +16,11 @@
  */
 import type { SearchContext } from './collection-facade.js';
 import type { SearchOptions, SearchResult } from './index.js';
-import type { RetrieveOptions, RetrieveHit } from './retrieve-types.js';
+import type { RetrieveOptions, RetrieveHit, SimilarToOptions } from './retrieve-types.js';
 export interface SearchStrategy {
     search<T>(ctx: SearchContext<T>, field: string, query: string, opts?: SearchOptions): Promise<SearchResult<T>[]>;
     retrieve<T>(ctx: SearchContext<T>, query: string, opts?: RetrieveOptions<T>): Promise<RetrieveHit<T>[]>;
-    similarTo<T>(ctx: SearchContext<T>, vector: Float32Array, opts?: {
-        k?: number;
-        minScore?: number;
-        includeRecord?: boolean;
-    }): Promise<RetrieveHit<T>[]>;
+    similarTo<T>(ctx: SearchContext<T>, vector: Float32Array, opts?: SimilarToOptions): Promise<RetrieveHit<T>[]>;
     warmIndex<T>(ctx: SearchContext<T>): Promise<void>;
     flushIndex<T>(ctx: SearchContext<T>): Promise<void>;
     embedOnWrite<T>(ctx: SearchContext<T>, id: string, record: T, version: number): Promise<void>;

package/dist/with-party/directory/cover/index.d.ts

@@ -2,7 +2,7 @@
  * Cover service — barrel export. (Formerly "public envelope"; the
  * old names remain as deprecated aliases for one pre-release window.)
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/public-envelope.md
  *
  * @module
  */

package/dist/with-party/directory/cover/storage.d.ts

@@ -50,6 +50,6 @@ export declare function resolveLocale(cover: Cover, locale: string): Cover;
  *   3. First non-empty value in the map.
  *   4. Empty string (only if every translation is empty — pathological).
  *
- * This deviation is documented in `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`.
+ * This deviation is documented in `https://github.com/noy-db/docs/blob/main/content/docs/services/public-envelope.md`.
  */
 export declare function pickLocale(value: string | Record<string, string>, locale: string, defaultLocale: string | undefined): string;

package/dist/with-party/directory/cover/types.d.ts

@@ -8,7 +8,7 @@
  * record still lives at `_meta/public-envelope` and carries the
  * `_noydb_public: 1` discriminator.)
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/public-envelope.md
  *
  * @module
  */

package/dist/with-party/directory/index.d.ts

@@ -2,7 +2,7 @@
  * User-list visibility — barrel export for the
  * `@noy-db/hub/directory` surface.
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
  *
  * @module
  */

package/dist/with-party/directory/types.d.ts

@@ -14,7 +14,7 @@
  * flags exist to keep admin-UI listings tidy, not to hide principals
  * from a determined attacker.
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/user-envelope.md → Directory visibility
  *
  * @module
  */

package/dist/with-party/directory/user-envelope/api.d.ts

@@ -130,7 +130,7 @@ export declare class UserApi implements VaultUserApi {
      * Honest caveat: this is a UX flag, not a privacy guarantee. The
      * envelope ciphertext at `_users/<keyringId>` and the keyring file at
      * `_keyring/<userId>` are both still observable to anyone with direct
-     * store read access. See `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md` →
+     * store read access. See `https://github.com/noy-db/docs/blob/main/content/docs/services/user-envelope.md` →
      * "Directory visibility".
      */
     setMyVisibility(visibility: UserVisibility): Promise<void>;

package/dist/with-party/policy/engine.d.ts

@@ -7,7 +7,7 @@
  * a stable {@link PolicyDenyReason} so consumers can branch in error
  * UIs.
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → checkGate() API
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/session-tiers.md → checkGate() API
  *
  * @module
  */

package/dist/with-party/policy/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * Policy gate DSL — barrel export for the `@noy-db/hub/policy` surface.
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Policy gates DSL
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/session-tiers.md → Policy gates DSL
  *
  * @module
  */

package/dist/with-party/policy/presets.d.ts

@@ -9,7 +9,7 @@ import type { VaultPolicy } from '../../kernel/types.js';
  * The unspecified gates (e.g. `view-user-auth`) inherit the engine
  * default of `{ enabled: false, minTier: 1 }` — they fail closed.
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Built-in gates
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/session-tiers.md → Built-in gates
  */
 export declare const PERSONAL_POLICY: VaultPolicy;
 /**

package/dist/with-party/team/authenticators.d.ts

@@ -9,12 +9,14 @@
  * (`on-webauthn`, `on-oidc`, `on-password`); this module accepts the
  * package's `wrapped_kek` ciphertext + `meta` payload and persists it.
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Tier 2 — Authenticate
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/session-tiers.md → Tier 2 — Authenticate
  *
  * @module
  */
 import type { NoydbStore, KeyringAuthenticator } from '../../kernel/types.js';
 import type { UnlockedKeyring } from './keyring.js';
+import { type SlotRewrapCeremony } from './rotate-recover.js';
+import type { RotateSecretInput } from './rotate-recover.js';
 /** Fields shared across both wrap-KEK and wrap-DEKs enroll inputs. */
 interface EnrollAuthenticatorBase {
     readonly id: string;
@@ -84,6 +86,29 @@ export declare function updateAuthenticator(store: NoydbStore, vault: string, ke
 /**
  * Drop a slot by id. No-op if the slot doesn't exist (idempotent —
  * removing a non-existent slot is a recoverable retry, not an error).
+ *
+ * ⛔ **THIS HIDES A CREDENTIAL. IT DOES NOT REVOKE ONE.** (#1445) The slot
+ * leaves the keyring file and nothing else happens — no key material moves. A
+ * slot blob captured before removal, or cached by an honest client earlier in
+ * the same session, still unwraps the FULL LIVE DEK SET and reads every record,
+ * for as long as those DEKs remain current.
+ *
+ * That is not a leak in one `on-*` package. `@noy-db/on-password`'s
+ * `unwrapDeksWithPassword` and `@noy-db/on-webauthn`'s `unwrapKeyringSummary`
+ * both carry the DEK map inside the blob and need no store, no keyring and no
+ * network — the blob authenticates itself. A membership check inside a verifier
+ * cannot close it, because a blob holder calls the primitive directly and never
+ * reaches the verifier.
+ *
+ * ⭐ To actually revoke, see {@link revokeAuthenticator} — removal, then a DEK
+ * rotation, then a re-wrap of the slots that stay. Every step is required and
+ * the reasons are measured, not assumed; read that doc before assembling the
+ * sequence by hand.
+ *
+ * ⚠️ Idempotency is only sound when the slot list is actually
+ * visible — see {@link assertSlotListVisible} (#1426).
+ *
+ * @throws `ValidationError` when the session cannot see the slot list.
  */
 export declare function removeAuthenticator(store: NoydbStore, vault: string, keyring: UnlockedKeyring, slotId: string): Promise<UnlockedKeyring>;
 /**
@@ -92,4 +117,69 @@ export declare function removeAuthenticator(store: NoydbStore, vault: string, ke
  * before invoking the method-specific verifier.
  */
 export declare function findAuthenticator(keyring: UnlockedKeyring, slotId: string): KeyringAuthenticator | undefined;
+/** Inputs for {@link revokeAuthenticator}. */
+export interface RevokeAuthenticatorOptions {
+    /** The slot to revoke. */
+    readonly slotId: string;
+    /**
+     * The vault owner's CURRENT secret. Passed as both `oldSecret` and
+     * `newSecret` to `rotateSecret`, which accepts them being equal — measured,
+     * so revoking one credential does not force everyone onto a new phrase.
+     */
+    readonly secret: RotateSecretInput['oldSecret'];
+    /**
+     * A re-wrap ceremony for EVERY slot that stays, keyed by slot id.
+     *
+     * ⛔ A slot with no ceremony is DROPPED, not preserved — that is
+     * `rotateSecret`'s existing behaviour (#29 / PR5: "without `slotCeremonies`,
+     * rotation drops every slot"), and it is the honest outcome, because after
+     * step 2 its blob wraps DEKs that no longer exist. Supplying one requires
+     * that credential to be present: the password for `on-password`, a live
+     * assertion for `on-webauthn`. There is no way around that — re-wrapping a
+     * credential is the credential's own operation.
+     */
+    readonly slotCeremonies?: {
+        readonly [slotId: string]: SlotRewrapCeremony;
+    };
+}
+/**
+ * Actually revoke an authenticator slot: remove it, mint fresh DEKs, and
+ * re-wrap the slots that stay (#1445).
+ *
+ * ## Why this is three steps and not one
+ *
+ * Each was measured, because the composition looks obvious and the obvious
+ * compositions do not work:
+ *
+ * 1. **{@link removeAuthenticator}** hides the slot. On its own it revokes
+ *    nothing — the captured blob carries its own DEKs.
+ * 2. **`rotateKeys`** is the step that revokes. It is the ONLY one that calls
+ *    `generateDEK()`. Measured: a collection's DEK is byte-identical across a
+ *    `rotateSecret` and different across a `rotateKeys`.
+ *    ⚠️ `rotateSecret` alone does NOT revoke, however it reads:
+ *    it unwraps every DEK with the old KEK and rewraps THE SAME KEY MATERIAL
+ *    under the new one. A captured blob holds DEK VALUES and records are
+ *    encrypted with DEKs, so rewrapping them changes nothing the holder needs.
+ * 3. **`rotateSecret` with `slotCeremonies`** re-wraps the remaining slots
+ *    around the new DEKs. Without it they survive step 2 BYTE-IDENTICAL
+ *    (measured: `rotateKeys` never touches `authenticators[]`) and therefore
+ *    silently wrap keys that no longer exist — every other credential in the
+ *    vault dies quietly. This step is what makes the operation safe for
+ *    everyone who was not being revoked.
+ *
+ * ⭐ Neither primitive is sufficient alone and they are not interchangeable:
+ * `rotateKeys` mints keys but cannot re-wrap slots; `rotateSecret` re-wraps
+ * slots but cannot mint keys.
+ *
+ * ## Cost
+ *
+ * Step 2 re-encrypts every record in every affected collection, and every
+ * remaining credential holder must be present for step 3. This is expensive on
+ * purpose: it is what revocation costs when the credential is a bearer token.
+ *
+ * @throws `ValidationError` when the session cannot see the slot list
+ *   ({@link assertSlotListVisible}) — a tier-1 unlock is required, and #1432
+ *   guarantees the KEK rotation needs is present at this point.
+ */
+export declare function revokeAuthenticator(store: NoydbStore, vault: string, keyring: UnlockedKeyring, options: RevokeAuthenticatorOptions): Promise<UnlockedKeyring>;
 export {};

package/dist/with-party/team/index.d.ts

@@ -19,8 +19,9 @@ export type { UnlockedKeyring } from './keyring.js';
 export { loadKeyring, createOwnerKeyring, grant, revoke, changeSecret, listUsers, listUsersWithEnvelopes, ensureCollectionDEK, persistKeyring, updateKeyringIdentity, buildRecipientKeyringFile, } from './keyring.js';
 export type { PodRecipient, ListUsersOptions } from './keyring.js';
 export type { LoadKeyringOptions, CreateOwnerKeyringOptions, RotateKeysOptions, ChangeSecretOptions, } from './keyring.js';
-export { enrollAuthenticator, removeAuthenticator, updateAuthenticator, findAuthenticator, } from './authenticators.js';
-export type { EnrollAuthenticatorOptions, EnrollAuthenticatorWrappingKEKOptions, EnrollAuthenticatorWrappingDEKsOptions, UpdateAuthenticatorOptions, } from './authenticators.js';
+export { enrollAuthenticator, removeAuthenticator, revokeAuthenticator, // #1445 — the three-step revocation; removeAuthenticator alone only hides
+updateAuthenticator, findAuthenticator, } from './authenticators.js';
+export type { EnrollAuthenticatorOptions, EnrollAuthenticatorWrappingKEKOptions, EnrollAuthenticatorWrappingDEKsOptions, UpdateAuthenticatorOptions, RevokeAuthenticatorOptions, } from './authenticators.js';
 export { rotateSecret, recoverSecret, } from './rotate-recover.js';
 export type { RotateSecretInput, RecoverSecretInput, RecoverSecretResult, RecoveryProof, SlotRewrapContext, SlotRewrapCeremony, } from './rotate-recover.js';
 export { recoverUser } from './peer-recover.js';

package/dist/with-party/team/keyring.d.ts

@@ -16,14 +16,21 @@ export interface UnlockedKeyring {
      */
     readonly pendingDeks?: Map<string, EnclaveKey> | undefined;
     /**
-     * The KEK, when this keyring was unlocked via tier 1 (secret) or
-     * a wrap-KEK tier-2 method (WebAuthn / OIDC). `null` when the
-     * keyring was opened via:
+     * The KEK, when this keyring was unlocked via tier 1 (secret).
+     * `null` for every other path:
      *
      *   - Unencrypted mode (no KEK exists)
+     *   - **Every shipped tier-2 unlock** — `@noy-db/on-webauthn`,
+     *     `@noy-db/on-oidc` and `@noy-db/on-password` all rebuild the
+     *     DEK set from their own slot and return `kek: null`. A slot
+     *     being wrap-KEK on disk (`wrapped_kek`, see
+     *     `KeyringAuthenticatorWrappingKEK`) is what lets `rotateSecret`
+     *     re-wrap it via the slot ceremony; it does not mean the unlock
+     *     surfaces the KEK. (Measured against on-webauthn / on-oidc
+     *     source and the published 0.7.0 dist, 2026-09-02 — an earlier
+     *     version of this comment claimed both yield the KEK; neither
+     *     ever did.)
      *   - Tier-3 PIN quick-resume (`@noy-db/on-pin`)
-     *   - Wrap-DEKs tier-2 unlock (`@noy-db/on-password`'s
-     *     `verifyPasswordSlot`)
      *   - Session-state restore (`session/session.ts`)
      *   - Dev-unlock fixture (`session/dev-unlock.ts`)
      *
@@ -490,7 +497,7 @@ export interface ListUsersOptions {
  * strong as the role the calling layer passes in. The hub-level wrapper
  * on `Vault` sources `callerRole` from the unlocked keyring's `role`
  * field, which is signed-by-construction (it lives in the user's own
- * keyring file). See `https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/user-envelope.md` →
+ * keyring file). See `https://github.com/noy-db/docs/blob/main/content/docs/services/user-envelope.md` →
  * "Directory visibility".
  *
  * Principals without a persisted envelope (legacy keyrings predating

package/dist/with-party/team/managed-secret.d.ts

@@ -43,7 +43,7 @@
  *   - Mandatory strong-recovery enforcement.
  *   - Recovery flow under managed mode (generates fresh sealed phrase).
  *
- * @see https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/session-tiers.md → Managed-secret mode
+ * @see https://github.com/noy-db/docs/blob/main/content/docs/services/session-tiers.md → Managed-secret mode
  *
  * @module
  */

package/dist/with-party/team/noydb-facade.d.ts

@@ -19,7 +19,7 @@
  * Internal service — reached through `noydb.team.rotateSecret(...)` etc.
  */
 import type { NoydbOptions, NoydbStore, KeyringAuthenticator } from '../../kernel/types.js';
-import type { RotateResult, RotateKeysOptions, RosterVerifyResult, QuarantineResult } from './keyring.js';
+import { type RotateResult, type RotateKeysOptions, type RosterVerifyResult, type QuarantineResult } from './keyring.js';
 import { type RotateSecretInput, type RecoverSecretInput, type RecoverSecretResult, type RotateRecoveryOptions, type RotateRecoveryResult, type EnrollRecoveryResult, type RecoveryEnrollmentInput, type RecoveryProof } from './rotate-recover.js';
 import { type RecoverUserOptions } from './peer-recover.js';
 import { type PaperRecoveryEntry, type ShamirRecoveryEntry } from './recovery.js';
@@ -92,9 +92,18 @@ export declare class TeamFacade {
      */
     enrollAuthenticator(vault: string, options: EnrollAuthenticatorOptions, factors?: FactorProofBundle): Promise<void>;
     /**
-     * Remove a tier-2 authenticator slot. Idempotent — removing a
-     * non-existent slot is a successful no-op. Gated by
+     * Remove a tier-2 authenticator slot. Idempotent — removing a slot
+     * that is not in the keyring is a successful no-op. Gated by
      * `remove-authenticator`.
+     *
+     * ⚠️ Idempotency needs the slot list to be VISIBLE, and a tier-3
+     * PIN-resumed / session-restored keyring carries an empty one
+     * (#1426). Such a session throws `ValidationError` rather than
+     * reporting a removal it did not perform — re-authenticate at tier 1
+     * first.
+     *
+     * @throws `ValidationError` when the active keyring cannot see its
+     *   slot list (`kek === null`).
      */
     removeAuthenticator(vault: string, slotId: string, factors?: FactorProofBundle): Promise<void>;
     /** Read the slot list for a vault. Internal — `describeAuthConfig` consumes this. */

package/dist/with-party/team/wrapped-deks.d.ts

@@ -66,10 +66,10 @@ export interface WrappedDeksBlob {
  * PIN). Caller normalization rules apply (e.g. paper
  * recovery uppercase-strips the code before reaching this function).
  *
- * @param deks - DEK set to wrap. Each DEK must be exportable via
- *               `subtle.exportKey('raw', dek)` (the hub mints DEKs
- *               this way; consumers feeding non-extractable keys
- *               will get `InvalidAccessError` from WebCrypto).
+ * @param deks - DEK set to wrap. Serialized through the enclave's
+ *               `exportDekSet` door (the hub mints DEKs extractable;
+ *               consumers feeding non-extractable keys will get
+ *               `InvalidAccessError` from WebCrypto).
  * @param credential - String input the consumer minted (paper code,
  *               password, PIN). Treated as opaque bytes by PBKDF2.
  */

package/dist/with-pod/format.d.ts

@@ -113,7 +113,7 @@ export interface NoydbPodHeader {
     /** SHA-256 of the compressed body bytes (lowercase hex). Lets readers verify integrity without decompressing. */
     readonly bodySha256: string;
     /**
-     * Owner-curated cover (`https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`).
+     * Owner-curated cover (`https://github.com/noy-db/docs/blob/main/content/docs/services/public-envelope.md`).
      * Optional — present only when the source vault has a
      * `_meta/public-envelope` document AND the writer's hub is opted
      * into the feature. Treat as **untrusted hint**; the body's

package/dist/with-pod/pod.d.ts

@@ -27,7 +27,7 @@
  * *unwrapped JSON string*, not a Vault object. The caller
  * is responsible for piping that JSON into
  * `vault.load(json, secret)`. Splitting the layers
- * keeps the bundle module free of any crypto/secret
+ * keeps `format.ts` free of any crypto/secret
  * concerns — it's purely a format layer. The same `readPod`
  * call can also feed verification tools, format inspectors, or
  * archive utilities that don't care about decryption.
@@ -51,7 +51,7 @@ export type AutoCredentialKind = 'secret' | 'password' | 'pin';
  * correct login/prefill path rather than treating all credentials
  * as secrets.
  *
- * `bundle.ts` is a pure format layer — it carries the credential
+ * `format.ts` is a pure format layer — it carries the credential
  * without interpreting it. The consumer is responsible for
  * dispatching on `kind`.
  */
@@ -274,7 +274,7 @@ export interface WritePodOptions {
  * bundle that is missing something, and the defect surfaces later — in
  * whoever imports it — with nothing left to trace it back to.
  *
- * `bundle-option-keys.test.ts` parses `WritePodOptions` out of this file and
+ * `pod-option-keys.test.ts` parses `WritePodOptions` out of this file and
  * fails if the two ever drift, so adding an option is enough; you do not have
  * to remember to update this list, only to keep the interface shape parseable.
  *
@@ -285,7 +285,7 @@ export declare const WRITE_POD_OPTION_KEYS: readonly ["compression", "collection
  * Result returned by `readPod`. The caller is expected to
  * pass `dumpJson` into `vault.load(json, secret)` to
  * actually restore a vault. Splitting the layers keeps the
- * bundle module free of crypto concerns — see file-level docs.
+ * `format.ts` free of crypto concerns — see file-level docs.
  */
 export interface PodReadResult {
     readonly header: NoydbPodHeader;
@@ -471,7 +471,7 @@ export interface PodVerifyResult {
  */
 export declare function verifyPodHeader(bytes: Uint8Array, trustedKeys: Readonly<Record<string, string>>): Promise<PodVerifyResult>;
 /**
- * Read just the bundle's cover (`https://github.com/vLannaAi/noy-db-docs/blob/main/content/docs/services/public-envelope.md`)
+ * Read just the bundle's cover (`https://github.com/noy-db/docs/blob/main/content/docs/services/public-envelope.md`)
  * — without verifying the body or even parsing the dump JSON. Pass
  * the raw bundle bytes; receive the owner-curated metadata or
  * `undefined` if the bundle was written without one.

package/dist/with-shape/blobs/blob-compaction.d.ts

@@ -31,6 +31,7 @@
 import type { NoydbStore, SlotInfo } from '../../kernel/types.js';
 import { type EnclaveKey } from '../../kernel/enclave/index.js';
 import { type OrphanChunkReport } from './orphan-report.js';
+import { type UnreferencedLegacyBlobReport } from './legacy-sweep.js';
 export interface BlobFieldPolicy<T = unknown> {
     /**
      * Via port brand marker — lets a `BlobFieldPolicy` satisfy the kernel's
@@ -158,6 +159,15 @@ export interface CompactionResult {
      * is the expected reading everywhere else.
      */
     readonly orphanBlobChunks: OrphanChunkReport;
+    /**
+     * #1453 — legacy (no `_cek`) blobs at `refCount <= 0`: released by every
+     * reference-drop path but never reclaimed, because a legacy chunk has no
+     * eager shred. Counted on every run; deleted only with
+     * `reclaimLegacyBlobs: true`. Not an orphan in the `orphanBlobChunks`
+     * sense — these rows keep their index entry, which is exactly why that
+     * report could not see them.
+     */
+    readonly unreferencedLegacyBlobs: UnreferencedLegacyBlobReport;
 }
 export interface CompactRunOptions {
     /** Override "now" for deterministic testing. */
@@ -189,6 +199,12 @@ export interface CompactRunOptions {
     readonly cacheBudget?: {
         readonly maxBytes: number;
     };
+    /**
+     * #1453 — reclaim unreferenced legacy blobs (chunks first, then the index
+     * row). Off by default: reclaiming is irreversible and the default posture
+     * for a maintenance pass is to report. Ignored under `dryRun`.
+     */
+    readonly reclaimLegacyBlobs?: boolean;
 }
 export interface CompactionContext {
     readonly adapter: NoydbStore;

package/dist/with-shape/blobs/blob-set.d.ts

@@ -82,6 +82,8 @@ export declare class BlobSet {
      * a cleared view: see `ownerRecordElevated()`/`ownerTier()`.
      */
     private readonly clearedTier;
+    /** #1452 — see `BlobsStrategyOpenArgs.assertOwnerWritable`. */
+    private readonly assertOwnerWritable;
     constructor(opts: {
         store: NoydbStore;
         vault: string;
@@ -99,6 +101,7 @@ export declare class BlobSet {
         keyring?: UnlockedKeyring;
         clearedTier?: number;
         pinCache?: BlobPinCache;
+        assertOwnerWritable?: () => Promise<void>;
     });
     /**
      * #724 I1 completion: a legacy (non-`perRecordKeys`) blob has no per-blob
@@ -1275,10 +1278,26 @@ export declare class BlobSet {
      */
     list(): Promise<SlotInfo[]>;
     /**
-     * Delete the named slot from this record.
-     * Decrements refCount on the blob. Chunks are GC'd by `vault.blobGC()`.
+     * Delete the named slot from this record and decrement the blob's refCount.
+     * At refCount 0 an erasable blob (`perRecordKeys`) is crypto-shredded on the
+     * spot; a legacy blob keeps its chunks until
+     * `vault.compact({ reclaimLegacyBlobs: true })` reclaims them (#1453), or
+     * `blob(id).migrate()` makes it erasable first.
+     *
+     * Gated on the owning record (#1452): refused where an update of the record
+     * would be refused.
      */
     delete(slotName: string): Promise<void>;
+    /**
+     * #1451 — release EVERY slot this record holds. Called by
+     * `Collection.delete()` after the record is gone, so "the record is deleted"
+     * and "its attachments are released" are one operation. Ungated: the record
+     * delete itself already passed the gate bus. Ref-counted like any release —
+     * content another record still holds survives.
+     */
+    releaseAll(): Promise<void>;
+    /** The body of {@link delete}, minus the owner gate. */
+    private releaseSlot;
     /**
      * Pin the named slot for offline availability ON THIS DEVICE.
      *

package/dist/with-shape/blobs/legacy-sweep.d.ts

@@ -0,0 +1,35 @@
+/**
+ * #1453 — count, and optionally reclaim, legacy blobs nothing references.
+ *
+ * A legacy blob (no per-blob `_cek`) is left at refCount 0 "for deferred GC"
+ * by `releaseRef`; before this the deferred GC had no verb outside
+ * `forget()` (which needs `withForget`), and `orphanBlobChunks` could not see
+ * these rows because they keep their index entry — so `vault.compact()`
+ * reported clean over a vault whose blob storage grew on every overwrite.
+ *
+ * Reclaiming here is SAFE where reclaiming orphans is not (see
+ * `orphan-report.ts`): the decision reads `refCount` off an AAD-bound index
+ * row the hub decrypted itself, never the store's `list()`. A withholding
+ * store cannot make a live blob look unreferenced; it can only hide a row from
+ * this sweep, which then does nothing to it.
+ *
+ * Rows sealed at an elevated tier do not open under the flat `_blob` DEK and
+ * are skipped, not counted: this is a tier-0 pass.
+ */
+import type { NoydbStore } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
+/** What `vault.compact()` reports (and, on request, reclaims) about legacy blobs. */
+export interface UnreferencedLegacyBlobReport {
+    /** `_blob_index` rows with no `_cek` (legacy) and `refCount <= 0`. */
+    readonly blobs: number;
+    /** Chunk rows those blobs still hold. */
+    readonly chunks: number;
+    /** How many of those blobs this run deleted (chunks first, then the index row). */
+    readonly reclaimed: number;
+}
+export declare function sweepUnreferencedLegacyBlobs(ctx: {
+    adapter: NoydbStore;
+    vault: string;
+    getDEK: (name: string) => Promise<EnclaveKey>;
+    encrypted: boolean;
+}, reclaim: boolean): Promise<UnreferencedLegacyBlobReport>;

package/dist/with-shape/introspection/describe.d.ts

@@ -48,6 +48,12 @@ export interface DescribedField {
     readonly semanticType?: string;
     readonly unit?: string;
     readonly sensitivity?: 'public' | 'pii' | 'secret';
+    /**
+     * Read-shape sensitivity (#1363) — orthogonal to {@link DescribedField.sensitivity}.
+     * Telemetry plumbing, never a control: it tells a sensor which collections
+     * have a coverage worth accounting for. See `FieldMeta.bulk`.
+     */
+    readonly bulk?: 'sensitive';
     readonly aggregate?: 'sum' | 'count' | 'distinct' | 'none';
     readonly aliases?: readonly string[];
     readonly ref?: {

package/dist/with-shape/introspection/field-meta.d.ts

@@ -19,6 +19,24 @@ export interface FieldMeta {
     unit?: string;
     /** Data classification driving redaction/inspector masking. */
     sensitivity?: 'public' | 'pii' | 'secret';
+    /**
+     * Sensitivity that is a property of the READ SHAPE, not the value (#1251).
+     *
+     * ⚠️ Declaring this prevents nothing. Against an insider holding the device
+     * and local keys it is TELEMETRY: it lets an opt-in sensor make bulk
+     * extraction visible early, attributable and loud. The real remediation is
+     * key custody — tiers and per-collection DEKs — not this label.
+     *
+     * Reads as: *this field's collection is a corpus whose COVERAGE is a
+     * protected quantity.* Deliberately ORTHOGONAL to {@link FieldMeta.sensitivity}:
+     * a company tax id stays `'public'` (it is public by law) and is still
+     * `bulk: 'sensitive'`, because the book of business is the set, not the value.
+     *
+     * The kernel does NOTHING with it beyond carrying it through introspection
+     * (`describe()` / `dumpSchema()`), so a sensor can discover which
+     * collections to account for. Zero runtime cost when unused.
+     */
+    bulk?: 'sensitive';
     /** Default aggregation for this field. */
     aggregate?: 'sum' | 'count' | 'distinct' | 'none';
     /** Canonical search synonyms (data vocabulary, not UI). */