@noy-db/hub 0.7.1-pre.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

@@ -497,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-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

@@ -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). */

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

@@ -46,6 +46,16 @@ export interface FieldDescriptor {
     readonly optional?: boolean;
     /** Foreign-key target as `<collection>.<field>` when declared. */
     readonly references?: string;
+    /**
+     * Read-shape sensitivity, declared as `FieldMeta.bulk` (#1363). Present only
+     * when the collection is live in this process (the declaration lives in the
+     * `fieldMeta` channel, which is not persisted with the schema).
+     *
+     * ⚠️ Telemetry, never a control: it tells a coverage sensor which
+     * collections have a corpus worth accounting for. Against an insider holding
+     * the device and local keys it prevents nothing — key custody does.
+     */
+    readonly bulk?: 'sensitive';
 }
 export interface CollectionStats {
     readonly records: number;
@@ -113,6 +123,23 @@ export interface CollectionDescriptor {
     readonly stats?: CollectionStats;
     readonly meta?: CollectionMeta;
     readonly config?: CollectionConfig;
+    /**
+     * #1447 — fields the datastore itself computes or resolves, as
+     * `field → the via brands covering it` (`money`, `computed`, `i18n`,
+     * `lookup`, `geo`, `classified`, `blob`). Absent when the collection
+     * declares no via pipeline.
+     *
+     * Exists so a consumer can gate documentation against what the vault
+     * actually enforces. The reported case: a rulebook described three
+     * vault-computed fields as app-owned — the UNDERSTATING direction, which is
+     * silent, because it produces app-side reimplementation of a guarantee that
+     * already exists rather than a missing behaviour someone trips over.
+     *
+     * ⛔ Brand and field only. A binding's CONFIGURATION is deliberately absent:
+     * a dump saying "this field is classified, sensitivity pii" is a map of the
+     * columns worth attacking, in an artefact that by design leaves the vault.
+     */
+    readonly via?: Record<string, readonly string[]>;
 }
 export interface MaterializedViewDescriptor {
     readonly sources: ReadonlyArray<string>;
@@ -134,8 +161,37 @@ export interface InternalCollectionStats {
     readonly records: number;
     readonly bytes: number;
 }
+/**
+ * A report section `dumpSchema()` is capable of emitting (#1447).
+ *
+ * ⛔ CAPABILITY OF THE EMITTER, NEVER CONTENT OF THIS DUMP. `reports` lists
+ * what this hub *would* have reported, not what it found — a vault that
+ * genuinely declares no via fields still lists `'via'`.
+ *
+ * That distinction is the entire point. A content-based list reintroduces the
+ * ambiguity it exists to remove: a consumer could not tell "no via fields
+ * here" from "this hub cannot report them", which is exactly how a
+ * documentation gate switching to the live report passes VACUOUSLY on a hub
+ * too old to answer. Measured by a consumer attempting that adoption.
+ */
+export type SnapshotReport = 'via' | 'stats';
 export interface VaultSchemaSnapshot {
-    readonly _noydb_snapshot: 1;
+    readonly _noydb_snapshot: 2;
+    /**
+     * Which report sections this snapshot's emitter can produce (#1447).
+     *
+     * Check this before concluding anything from an ABSENT section:
+     *
+     * ```ts
+     * if (!snap.reports.includes('via')) throw new Error('hub cannot report via')
+     * // only now is a missing `via` key evidence that a collection declares none
+     * ```
+     *
+     * Required, and required deliberately: an optional field would leave
+     * `undefined` meaning "old emitter", which is the same ambiguity one level up.
+     * Every snapshot states what it can say.
+     */
+    readonly reports: readonly SnapshotReport[];
     readonly vault: string;
     readonly emittedAt: string;
     readonly subsystems: Record<string, boolean>;

package/dist/with-shape/links/vault-facade.d.ts

@@ -16,7 +16,7 @@
  */
 import { type RefDescriptor, type RefViolation, type RefRegistry } from '../../kernel/refs.js';
 import { type LinkSpec, type LinkSetHandle } from './names.js';
-import type { JoinableSource } from '../../kernel/query/index.js';
+import type { JoinableSource } from '../../kernel/query/relate/join.js';
 import type { Collection } from '../../kernel/collection.js';
 import type { NoydbStore } from '../../kernel/types.js';
 import type { TxContext } from '../../with-commit/tx/transaction.js';