@noy-db/hub 0.3.0-pre.12 → 0.3.0-pre.13

package/dist/verify-ZASTRNPR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kernel/enclave/classify/verify.ts"],"sourcesContent":["/**\n * The enclave verify oracle (spec §3). Verdict-only egress: no path\n * distinguishes \"record missing\" / \"no digest\" / \"AAD-tamper\" / \"mismatch\"\n * beyond { ok: false } — existence oracles are oracles too. Every path that\n * cannot run a real comparison runs ONE dummy PBKDF2 + ONE dummy tag-compare\n * first (C4), so wall-clock cannot enumerate records/fields/answers. The\n * text door (verifyTextField) has no real PBKDF2 of its own, so it pays the\n * pad UNCONDITIONALLY — every outcome, including a real compare, costs the\n * same one PBKDF2 unit (no inverted exists-vs-absent oracle).\n * Elevated records (_tier > 0, with-audit tier moves) are non-comparable\n * through every door and pad-false exactly like missing records (#691) —\n * the tier-aware read surface is getAtTier, never verify.\n * Throws are reserved for caller/config bugs (ClassifiedVerifyError /\n * ClassifiedConfigError) and are exempt from the pad by design (R6 note).\n * @module\n */\nimport { generateSalt, base64ToBuffer, type EnclaveKey } from '../crypto.js'\nimport { pbkdf2VerifyDigest, VDIG_ITERATIONS } from './digest.js'\nimport { normalizeForVerify, type VerifyNormalizeMode } from './normalize.js'\nimport { blindedEqual } from './compare.js'\nimport { evaluateKofN } from './kofn.js'\nimport { openVdigPayload, type VdigPayload } from './vdig.js'\nimport { dualReadSealedSlot } from '../record-keys/sealed-slot.js'\nimport { ClassifiedConfigError, ClassifiedVerifyError } from '../../errors.js'\nimport type { EncryptedEnvelope, VdigFieldPolicy, ClassifiedVerdict } from '../../types.js'\n\nexport interface VerifyEngineCtx {\n  readonly collection: string\n  getEnvelope(id: string): Promise<EncryptedEnvelope | null>\n  resolveCek(env: EncryptedEnvelope): Promise<EnclaveKey | undefined>\n  getDEK(): Promise<EnclaveKey>\n  readonly now: () => number\n}\n\n/**\n * C4 pad: one full-cost dummy digest + one dummy compare; result discarded.\n * Pad at `iter` when the caller holds an AUTHENTICATED payload.iter, so pad\n * cost tracks the real compare cost across future iteration bumps; the\n * fully-absent paths (no payload to read an iter from) use VDIG_ITERATIONS.\n */\nasync function padOnce(iter: number = VDIG_ITERATIONS): Promise<void> {\n  const dummy = await pbkdf2VerifyDigest('noydb-classify-c4-pad', generateSalt(), iter)\n  await blindedEqual(dummy, dummy)\n}\n\nasync function padFalse(): Promise<ClassifiedVerdict> {\n  await padOnce()\n  return { ok: false }\n}\n\n/** R6 verify-side transition evidence — config bug, fail-loud, pad-exempt. */\nfunction refuseSealedResidue(collection: string, field: string): never {\n  throw new ClassifiedConfigError(collection,\n    `field \"${field}\" carries a recoverable _sealed slot but no _vdig — storage-form ` +\n    `transition detected (R6); refused fail-loud, never an ok:false masquerading as wrong-password`)\n}\n\nexport async function verifyDigestField(\n  ctx: VerifyEngineCtx,\n  id: string,\n  field: string,\n  candidate: string,\n  policy: VdigFieldPolicy,\n): Promise<ClassifiedVerdict> {\n  const env = await ctx.getEnvelope(id)\n  // #691: an elevated envelope (_tier > 0) is non-comparable through every\n  // tier-0 door — its key material is tier-DEK-wrapped and must never be\n  // resolved here (the elevating session's warm cekCache would otherwise\n  // leak past the tier audit). Exactly the missing-record pad path, checked\n  // BEFORE the R6 residue probe so tier-0 callers learn nothing.\n  if (env === null || (env._tier ?? 0) > 0) return padFalse()\n  const blob = env._vdig?.[field]\n  if (blob === undefined) {\n    if (env._sealed?.[field] !== undefined) refuseSealedResidue(ctx.collection, field)\n    return padFalse()\n  }\n  const cek = await ctx.resolveCek(env)\n  if (cek === undefined) return padFalse()\n\n  let payload: VdigPayload\n  try {\n    payload = await openVdigPayload(blob, cek, ctx.collection, id, field)\n  } catch {\n    return padFalse() // AAD/tamper (C1) → padded false; no tamper oracle to the caller\n  }\n\n  const normalized = normalizeForVerify(policy.normalize, candidate)\n  const digest = await pbkdf2VerifyDigest(normalized, base64ToBuffer(payload.cur.salt), payload.iter)\n  const ok = await blindedEqual(digest, base64ToBuffer(payload.cur.hash))\n  if (!ok) return { ok: false } // I1: bare false — mustRotate never computed here\n\n  if (policy.rotateDays !== undefined\n    && ctx.now() > Date.parse(payload.cur.at) + policy.rotateDays * 86_400_000) {\n    // Disclosing write-age-vs-policy to a SUCCESSFUL verifier is intended (audit F6).\n    return { ok: true, mustRotate: true }\n  }\n  return { ok: true }\n}\n\nexport async function verifyTextField(\n  ctx: VerifyEngineCtx,\n  id: string,\n  field: string,\n  candidate: string,\n  normalize: VerifyNormalizeMode,\n): Promise<ClassifiedVerdict> {\n  // C4, single code path: (a) attempt the unseal where a slot exists, then\n  // for EVERY outcome — present-correct, present-wrong, missing record,\n  // missing slot, tampered — (b) run the one constant-cost pad, (c) run one\n  // blindedEqual, (d) return the boolean. Unlike the digest door there is no\n  // real PBKDF2 here (unseal is sub-ms AES-GCM), so skipping the pad on the\n  // real compare would make exists-but-wrong ~100x FASTER than absent — an\n  // inverted existence oracle. No branch below skips the dominant cost.\n  const env = await ctx.getEnvelope(id)\n  const blob = env?._sealed?.[field]\n  let stored: string | undefined\n  if (env !== null && (env._tier ?? 0) === 0 && blob !== undefined) { // #691: elevated ≡ missing\n    const cek = await ctx.resolveCek(env)\n    const dek = await ctx.getDEK()\n    try {\n      // Plaintext exists microseconds inside this function; only the boolean leaves.\n      stored = String(JSON.parse(await dualReadSealedSlot(blob, field, ctx.collection, cek, dek)))\n    } catch {\n      stored = undefined // AAD/tamper (C1) → same padded compare tail as absent\n    }\n  }\n  await padOnce()\n  const a = new TextEncoder().encode(normalizeForVerify(normalize, candidate))\n  const b = stored !== undefined\n    ? new TextEncoder().encode(normalizeForVerify(normalize, stored))\n    : a // no-compare dummy comparand — the verdict is forced false below\n  const eq = await blindedEqual(a, b)\n  return { ok: stored !== undefined && eq }\n}\n\nexport async function matchGroupFields(\n  ctx: VerifyEngineCtx,\n  id: string,\n  answers: Record<string, string>,\n  members: ReadonlyArray<{ readonly field: string; readonly policy: VdigFieldPolicy }>,\n  opts: { readonly min: number },\n): Promise<{ readonly passed: boolean }> {\n  // I2 step 1 — validate EVERYTHING up front, before any PBKDF2, throwing\n  // uniformly at ~0 elapsed (no member-position leak via timing/throw type).\n  if (!Number.isInteger(opts.min) || opts.min < 1 || opts.min > members.length) {\n    throw new ClassifiedVerifyError(ctx.collection, '*',\n      `matchGroup min ${opts.min} out of range 1..${members.length}`)\n  }\n  const normalized = new Map<string, string>()\n  for (const m of members) {\n    const answer = answers[m.field] // non-member answer keys: silently ignored\n    if (answer === undefined) continue\n    if (typeof answer !== 'string') {\n      throw new ClassifiedVerifyError(ctx.collection, m.field, 'candidate must be a string')\n    }\n    normalized.set(m.field, normalizeForVerify(m.policy.normalize, answer))\n  }\n\n  const fetched = await ctx.getEnvelope(id)\n  // #691: elevated ≡ missing — nulling the view here also skips the R6\n  // residue probe (a tier-0 caller must not learn an elevated record's\n  // storage form) and forces the cek-undefined pad path for every member.\n  const env = fetched === null || (fetched._tier ?? 0) > 0 ? null : fetched\n  if (env !== null) {\n    for (const m of members) { // R6 evidence — uniform, before any PBKDF2\n      if (env._sealed?.[m.field] !== undefined && env._vdig?.[m.field] === undefined) {\n        refuseSealedResidue(ctx.collection, m.field)\n      }\n    }\n  }\n  const cek = env !== null ? await ctx.resolveCek(env) : undefined\n\n  // I2 step 2+3 — iterate RESOLVED GROUP MEMBERS (denominator = |members|),\n  // evaluate EVERY member (collect, never break), pad every no-compare slot.\n  const results: boolean[] = []\n  for (const m of members) {\n    const candidate = normalized.get(m.field)\n    const blob = env?._vdig?.[m.field]\n    if (env === null || cek === undefined || blob === undefined) {\n      await padOnce()\n      results.push(false)\n      continue\n    }\n    try {\n      const payload = await openVdigPayload(blob, cek, ctx.collection, id, m.field)\n      if (candidate === undefined) {\n        // Slot present, answer absent: the payload's authenticated iter is in\n        // hand — pad at IT (not the constant) so a future iteration bump\n        // cannot desync this pad's cost from the real compare's cost.\n        await padOnce(payload.iter)\n        results.push(false)\n        continue\n      }\n      const digest = await pbkdf2VerifyDigest(candidate, base64ToBuffer(payload.cur.salt), payload.iter)\n      results.push(await blindedEqual(digest, base64ToBuffer(payload.cur.hash)))\n    } catch {\n      await padOnce()\n      results.push(false)\n    }\n  }\n  // Per-member results never appear in any return, error, or audit payload.\n  return { passed: evaluateKofN(results, opts.min) }\n}\n"],"mappings":"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","names":[]}

package/dist/{walk-XQCBKSBW.js → walk-SVNDIZ62.js}

@@ -3,19 +3,19 @@ import {
 } from "./chunk-VYYM3MEN.js";
 import {
   derivePersistedSchema
-} from "./chunk-P2LJI6JE.js";
+} from "./chunk-W22IKJE2.js";
 import {
   loadPersistedSchema
-} from "./chunk-HK4XTXO4.js";
-import "./chunk-HA6ZQWA2.js";
-import "./chunk-J3JIYFYL.js";
-import "./chunk-XS6DLN67.js";
-import "./chunk-NM3IFKBL.js";
-import "./chunk-45QPICLE.js";
+} from "./chunk-VZRODIM3.js";
+import "./chunk-XDYREZWE.js";
+import "./chunk-7DSTRQIJ.js";
+import "./chunk-HB3RFQSC.js";
+import "./chunk-JKJOGPZN.js";
+import "./chunk-5M5DVGV7.js";
 import "./chunk-LP7BEXCT.js";
-import "./chunk-37WOJQWY.js";
-import "./chunk-JC75UBMT.js";
-import "./chunk-FZCGIJEJ.js";
+import "./chunk-CIE2BASH.js";
+import "./chunk-JNAI2HN2.js";
+import "./chunk-BIOUI4HL.js";
 import "./chunk-PZ5AY32C.js";
 
 // src/with-shape/introspection/walk.ts
@@ -238,4 +238,4 @@ function summariseAggregateOp(value) {
 export {
   dumpVaultSchema
 };
-//# sourceMappingURL=walk-XQCBKSBW.js.map
+//# sourceMappingURL=walk-SVNDIZ62.js.map

package/dist/with/index.js

@@ -6,18 +6,18 @@ import {
   assertCanImport,
   canExport,
   canImport
-} from "../chunk-K2DLLK34.js";
-import "../chunk-CCIR2OJH.js";
-import "../chunk-JGUZMC3I.js";
-import "../chunk-HA6ZQWA2.js";
-import "../chunk-J3JIYFYL.js";
-import "../chunk-XS6DLN67.js";
-import "../chunk-NM3IFKBL.js";
-import "../chunk-45QPICLE.js";
+} from "../chunk-6QTNZJBS.js";
+import "../chunk-J2ZX2XUV.js";
+import "../chunk-4JBYV75E.js";
+import "../chunk-XDYREZWE.js";
+import "../chunk-7DSTRQIJ.js";
+import "../chunk-HB3RFQSC.js";
+import "../chunk-JKJOGPZN.js";
+import "../chunk-5M5DVGV7.js";
 import "../chunk-LP7BEXCT.js";
-import "../chunk-37WOJQWY.js";
-import "../chunk-JC75UBMT.js";
-import "../chunk-FZCGIJEJ.js";
+import "../chunk-CIE2BASH.js";
+import "../chunk-JNAI2HN2.js";
+import "../chunk-BIOUI4HL.js";
 import "../chunk-PZ5AY32C.js";
 export {
   ServiceBus,

package/dist/with-audit/forget/strategy.d.ts

@@ -138,6 +138,13 @@ export interface ForgetResult {
     /** `collection:id:field` sealed slots that were DEK-derived (legacy, written before per-record CEKs) and thus NOT crypto-shredded
      * by dropping `_cek` — the collection DEK is retained, so synced/backup copies stay decryptable (#M-1). */
     readonly sealedResidue: readonly string[];
+    /** Count of `_ledger_deltas` rows hard-deleted across the shredded records (#734) — the
+     * erasure twin of #729's elevate-side purge. Entry metadata (that the record was mutated,
+     * at which version/timestamp/actor) is retained; only the plaintext delta content is removed. */
+    readonly ledgerDeltasPurged: number;
+    /** `collection:id` refs whose `_ledger_deltas` purge failed — plaintext delta residue still
+     * readable under the retained ledger DEK. Non-empty means erasure is INCOMPLETE. */
+    readonly ledgerDeltaResidue: readonly string[];
     /** The single `op:'forget'` ledger entry appended for this erasure. */
     readonly ledgerEntry: LedgerEntry;
     /** #622 — record-grain derived artifacts (MV rows, per-record derived copies) erased
@@ -162,6 +169,21 @@ export interface ForgetResult {
      *  Always empty under the unconditional default. Non-empty means a `_sealed_cek` entry or a
      *  blob scan was skipped for an undeclared collection — reported, never a silent skip. */
     readonly scopedPurgeResidue: readonly ScopedPurgeResidueNotice[];
+    /** #776/#782/#785 — `collection:id` MV-output rows that survived erasure invalidation (eager
+     *  tombstone leg AND lazy/manual `invalidateMVAtRest`) despite belonging to the forgotten
+     *  subject, because the `_materializedFrom` ownership stamp could NOT be decoded (undecodable
+     *  under the collection's default DEK — e.g. elevated above tier 0 on a tiered output
+     *  collection; ownership unconfirmed — could be a plain user record on a same-collection
+     *  partition MV). Never erased, but surfaced here rather than silently skipped (the #724
+     *  posture). Non-empty means the row may still hold the forgotten/pre-elevation contribution,
+     *  decryptable by tier-holders. */
+    readonly derivedResidueUndecodable: readonly string[];
+    /** #782/#785 — `collection:id` MV-output rows that DID decode and stamp-match via
+     *  `_materializedFrom`, but whose erasure was declined by the #718 tier-elevation gate
+     *  (`_internalDelete` returned false). Ownership CONFIRMED here — a real silent survival,
+     *  not a stamp-mismatch skip — surfaced rather than dropped. Non-empty means a live,
+     *  tier-holder-decryptable copy of the forgotten contribution was deliberately retained. */
+    readonly derivedResidueDeclined: readonly string[];
 }
 /** #633 — the two `scopedPurgeResidue` skip reasons. Single source of truth: `purge-scope.ts`
  *  (the port-internal partition helpers) imports this rather than redeclaring it. */

package/dist/with-audit/tiers/index.d.ts

@@ -26,6 +26,7 @@ export { TiersNotEnabledError } from '../../kernel/errors.js';
 import { type RecordCodec, type EnclaveKey, type SealedShredSlot } from '../../kernel/enclave/index.js';
 import type { UnlockedKeyring } from '../../with-party/team/keyring.js';
 import type { Lru } from '../../kernel/cache/index.js';
+import type { BlobFieldsConfig } from '../../with-shape/blobs/blob-compaction.js';
 import { type NoydbStore, type EncryptedEnvelope, type GhostRecord, type TierMode, type CrossTierAccessEvent } from '../../kernel/types.js';
 /** Everything the moving tier methods touched on `this.*`, as a flat context. */
 export interface TiersContext<T> {
@@ -46,6 +47,168 @@ export interface TiersContext<T> {
      * owns. `null` → no caching.
      */
     readonly cekCache: Lru<string, EnclaveKey> | null;
+    /**
+     * Sync the collection's decoded-record cache after a tier move rewraps the
+     * envelope (#691). The lazy LRU is evicted on EVERY call — it is never
+     * re-seeded, since a lazy `#getRaw` miss refetches and decodes the fresh
+     * envelope via its adapter fallback (a stale LRU entry after a tier-0
+     * `putAtTier` overwrite was the #702 lazy-mode gap). `null` → also evict
+     * the eager cache entry; an `entry` → set the eager cache to the given
+     * decoded record/version (used by `demote()` landing back at tier 0 and
+     * `putAtTier`'s tier-0 write, #702 — the record is tier-0, so it must stay
+     * plain-`get()`-readable in-session).
+     */
+    syncCache(id: string, entry: {
+        record: T;
+        version: number;
+    } | null): void;
+    /**
+     * Sync the collection's indexes after a tier move rewraps the envelope
+     * (#709). Persisted `_idx/<field>/<recordId>` side-cars hold the indexed
+     * field's PLAINTEXT value and are always encrypted under the tier-0 DEK,
+     * whatever the record's own tier — the same leak class `forget()` fixed
+     * via `purgePersistedIndexes` ("forget() crypto-shreds the body but keeps
+     * the collection DEK, under which these side-cars are encrypted — so
+     * without this they leave the indexed field VALUES readable"). `null` →
+     * the record just left tier 0: purge its persisted side-cars and drop its
+     * in-memory index entries. A record → it is tier-0 again: (re)build its
+     * entries from that record. Call this BEFORE {@link syncCache} — the
+     * implementation reads the pre-write cached value as "previous" to clean
+     * up stale index buckets, so it must run while that entry is still live.
+     * `version` stamps a rebuilt side-car's own envelope version — every
+     * caller has one in scope (the envelope it just wrote), including the
+     * purge (`null`) branches, which pass it along even though it's ignored
+     * there (#720: keeps the parameter honestly required, no dead default).
+     * `priorEnvelope` (#720) — the RAW envelope read BEFORE this call's own
+     * overwrite (already in scope as `existing`/`envelope` at every record-
+     * branch call site), so a lazy same-tier value change (a `putAtTier(0)`
+     * dropping an indexed field, a `demote(0)` off an elevated record) can
+     * still be tier-gate-decoded as "previous" once the live envelope itself
+     * has already moved past it. The `null`-record branches never pass one —
+     * see the implementation's doc comment for why they don't need to.
+     */
+    syncIndexes(id: string, record: T | null, version: number, priorEnvelope?: EncryptedEnvelope): Promise<void>;
+    /** Sync the collection's SEARCH artifacts after a tier move (#721). Both the
+     *  lexical `_ftindex` blob and the `_vec/<id>` embedding are encrypted under
+     *  the tier-0 DEK and hold the record's derived plaintext (full field text /
+     *  a text-invertible vector), so leaving them means elevation never hid what
+     *  the record was searchable by — the `forget()` precedent, unapplied to
+     *  elevate. `null` → the record left tier 0: purge its `_vec`, and
+     *  invalidate the `_ftindex` blob (the cache-driven rebuild then excludes
+     *  it). A record → it is tier-0 again: re-embed it, and invalidate
+     *  `_ftindex` (rebuild includes it). No-op fast when the collection has no
+     *  search. */
+    syncSearch(id: string, record: T | null, version?: number): Promise<void>;
+    /**
+     * Sync a record's `_history` snapshots after a tier move rewraps the live
+     * envelope (#712, at-rest hardening). Each snapshot carries its own key
+     * material (a direct DEK wrap, or a per-record `_cek` itself wrapped under
+     * the tier DEK) — `elevate()`'s live-body rewrap moves only the live
+     * envelope, leaving prior versions decryptable at rest under the tier the
+     * record has moved away from (the same leak class `forget()`'s
+     * `tombstoneHistory` closed for erasure). `fromDek`/`toDek` are the SAME
+     * DEKs the caller already resolved for the live rewrap — reuse them, don't
+     * recompute. No-op when the strategy is `NO_HISTORY`.
+     */
+    syncHistory(id: string, fromDek: EnclaveKey, toDek: EnclaveKey): Promise<void>;
+    /**
+     * Save a raw pre-move envelope as a `_history` snapshot (#728). Tier moves
+     * (`putAtTier`/`elevate`/`demote`) bump `_v` and overwrite the live
+     * envelope without ever snapshotting the version that existed just before
+     * the move — so `history()` silently lost it. The caller (`tiers/index.ts`)
+     * builds `envelope` by reusing the SAME `rewrapBodyToDek(envelope, fromDek,
+     * toDek)` result it already computed for the live write, so the snapshot
+     * lands wrapped under the DESTINATION tier's DEK — never `ctx.codec.
+     * encryptRecord`, which always resolves the tier-0 DEK and would leak the
+     * pre-move body whenever `fromTier > 0`. No-op when history is disabled
+     * (folds the `historyConfig.enabled` gate so `tiers/index.ts` stays simple).
+     */
+    saveHistorySnapshot(id: string, envelope: EncryptedEnvelope): Promise<void>;
+    /**
+     * `true` iff a real history strategy is wired (not `NO_HISTORY`) AND not
+     * explicitly disabled via `historyConfig.enabled`. `putAtTier` checks this
+     * BEFORE decrypting `existing` to build a snapshot (#728, #737 regression
+     * fix) — unlike elevate/demote, which reuse a `body` rewrap their live
+     * write needs unconditionally, putAtTier's live write never decrypts the
+     * prior envelope, so building a snapshot is the ONLY reason it would
+     * touch (and potentially throw decrypting) `existing`'s ciphertext. A
+     * derivation-free, history-disabled collection must not pay that decode —
+     * or risk it, on a corrupted/inaccessible prior body — same law
+     * `hasDerivedOutputs` already enforces for the derived-outputs decode.
+     */
+    readonly historyEnabled: boolean;
+    /**
+     * Rehome a record's blob attachments after a tier move (#724 Arc 10 Task
+     * 2, at-rest hardening). A blob's home tier is its owning record's tier —
+     * the `_blob` DEK is tier-scoped (`dekKey('_blob', tier)`), so a solo-
+     * owned blob's content CEK must move with the record or it stays
+     * tier-0-unwrappable at rest even once the live body has moved (the same
+     * leak class `syncHistory` closes for `_history` snapshots). Delegates to
+     * `BlobSet.rehomeForTier`; no-op fast when the collection has no blob
+     * fields. Order-independent with the other sync hooks — touches only
+     * blob side structures, not this collection's own cache/indexes.
+     */
+    syncBlobs(id: string, fromTier: number, toTier: number): Promise<void>;
+    /**
+     * Purge a record's tier-0-era plaintext ledger deltas after a tier move
+     * lands it above tier 0 (#729). The audit ledger is a flat, vault-wide,
+     * hash-chained log — a record's reverse-JSON-Patch deltas in
+     * `_ledger_deltas` are encrypted under one collection-wide `_ledger` DEK
+     * (not the record's own tier DEK), so `elevate()`/`putAtTier()`'s live-body
+     * rewrap never moves them: they stay readable at rest to any tier-0
+     * caller, the same leak class `syncHistory` closed for `_history`
+     * snapshots. Chain-safe: `verify()` reads only `_ledger` entry fields
+     * (including `deltaHash`, which lives on the entry, not the deleted delta
+     * row), never `_ledger_deltas`, so a purge cannot break it.
+     * **Irreversible** — the deleted plaintext cannot be restored by
+     * `demote()`. **Metadata-retained** — the `_ledger` entries (that the
+     * record was mutated, at which version/timestamp/actor) are untouched;
+     * only the delta *content* is purged. No-op when the collection has no
+     * ledger (`withHistory()` not enabled).
+     */
+    syncLedger(id: string): Promise<void>;
+    /**
+     * Sync a record's derived outputs (materialized-view rows, rollup
+     * contributions, `withDerivation` outputs) after a tier move (#722).
+     * Those outputs are computed from this record and written to OTHER
+     * (output) collections via a plain `put` at tier 0 — `elevate()`'s live-
+     * body rewrap moves only the source envelope, so the output rows keep
+     * holding the source's tier-0-era plaintext, the same leak class
+     * `syncSearch`/`syncIndexes` closed for THIS collection's own artifacts.
+     * `elevated` (landing tier > 0) reuses the SAME onDelete fanout
+     * `forgetDerivedFanout` drives for `forget()` (`kernel/via/dispatch.ts`)
+     * — minus its `'ref'` cascade edge (elevate/demote never erase a
+     * *different* record) — to recompute this record's derived outputs as
+     * REMOVED. Recompute is tier-safe: the fanout's own source scan reads
+     * the elevated-excluding cache (#701/#709/#712), so it naturally omits
+     * the now-elevated record instead of re-embedding its plaintext. Landing
+     * back at tier 0 (`elevated === false`) is the reverse (Task 2, #722):
+     * `syncDerivedOutputs` instead runs the ordinary local-write add-
+     * dispatchers (`dispatchDerivations`/`dispatchMaterializedViews`, the
+     * same ones a plain `put()` fires) to restore the contribution —
+     * reversible, since the source's plaintext survives the elevate/demote
+     * rewrap round-trip. `record` is the decoded source record (PRE-move on
+     * the remove side, POST-move on the add side); only the rollup edge
+     * consumes it on remove, both add-dispatchers require it on add; `null`
+     * (tombstone/delete-marker) skips both. `version` stamps the add-
+     * dispatchers' `_derivedFrom.sourceVersion` metadata — reuses the version
+     * the tier op already has, no re-read; unused on the remove side. No-op
+     * fast when the collection has no MV/derivation source — each dispatcher
+     * below checks its own source before doing any work.
+     */
+    syncDerived(id: string, record: T | null, elevated: boolean, version?: number): Promise<void>;
+    /**
+     * `true` iff the collection has a materialized-view or derivation source
+     * attached. Gates the {@link syncDerived} pre-move decode on the remove
+     * direction (`elevate()`, `putAtTier(tier>0)`, `demote()`'s intermediate-
+     * tier branch): those sites decode the record SOLELY to feed
+     * `syncDerived(..., true)`, whose dispatchers no-op immediately when the
+     * collection has no MV/derivation source — so a no-derivation collection
+     * would otherwise pay a full record-body decrypt on every tier move for
+     * nothing (#722 perf regression). `false` short-circuits the decode to
+     * `null`, which `syncDerivedOutputs` already treats safely.
+     */
+    readonly hasDerivedOutputs: boolean;
     /** Emit `_source`/`_sourceTs` provenance fields when a source is supplied. */
     readonly provenance: boolean;
     /** Declared tiers, or null when the feature is off. */
@@ -56,9 +219,108 @@ export interface TiersContext<T> {
     getDEK(key: string): Promise<EnclaveKey>;
     /** Fire a cross-tier access event (sink stays collection-resident). */
     emitCrossTierEvent(event: CrossTierAccessEvent): void;
+    /**
+     * Register this record's ref in the encrypted `_subject_index` (#766).
+     * `putAtTier`'s raw `ctx.adapter.put` bypasses `Collection.put()`'s write-
+     * hook pipeline — the `onAfterWrite` hook that normally does this — so a
+     * record whose FIRST persistence is `putAtTier` (sensitive from birth, a
+     * documented legitimate use) would otherwise never enter the index and
+     * stay unreachable by `vault.forget()`. Idempotent (safe on every call,
+     * including a repeat write of an already-registered record) and a no-op
+     * when the collection declares no forget-subject field.
+     */
+    addSubjectRef(id: string, record: T): Promise<void>;
 }
 export declare function assertTiersEnabled<T>(ctx: TiersContext<T>): void;
 export declare function assertDeclaredTier<T>(ctx: TiersContext<T>, tier: number): void;
+/**
+ * Tier-composition guard (#724 / Arc 7 of the tier-invisibility campaign).
+ *
+ * Refuses `tiers` declared together with a derived-artifact feature whose
+ * crypto has not yet been made tier-aware — i.e. a feature `elevate()` /
+ * `demote()` does not re-key when a record moves tiers, so an elevated
+ * record's data for that feature would stay readable at tier 0.
+ *
+ * **Status:** the original call site (`Collection` constructor, beside
+ * `buildUniqueConstraintSet`) was removed by Arc 10 Task 1 (#724) — the
+ * `tiers + blobFields` refusal below was superseded by a runtime read gate
+ * on `collection.blob(id)` (`with-shape/blobs/blob-set.ts`), so this
+ * function currently has no caller. Relocated here from
+ * `with-lookup/indexing/unique-constraints.ts` (#733) so the tier-domain
+ * guard lives in the tier domain, rather than an indexing file it only
+ * borrowed for a grandfathered import specifier.
+ *
+ * ## #724 verified: `tiers + blobFields` leaks
+ *
+ * `collection.blob(id)` (`Collection.blob()`) never checks the live
+ * record's tier before returning a `BlobSet` handle, and `BlobSet`'s crypto
+ * is entirely orthogonal to the tier ladder:
+ *  - the slot map (`_blob_slots_{collection}/{id}`) is encrypted under the
+ *    collection's TIER-0 DEK (`getDEK(name)` ≡ `dekKey(name, 0)` — see
+ *    `dekKey` in `with-party/team/tiers.ts`), never a tier-N DEK;
+ *  - chunk content (`_blob_index` / `_blob_chunks`) is encrypted under the
+ *    vault-shared `_blob` DEK (`BLOB_COLLECTION`), which has no tier
+ *    dimension at all.
+ * `elevate()`/`demote()` (this file) rewrap only the live record body,
+ * `_history` snapshots (#712), and index side-cars — blob slots and chunks
+ * are untouched. A caller whose keyring never held the record's elevated
+ * tier DEK can still open `collection.blob(id).get(slot)` and read full
+ * plaintext, even though `collection.get(id)` correctly reports the same
+ * record as invisible. See `__tests__/tier-composition-guard.test.ts` for
+ * the reproduction.
+ *
+ * ## Safe today — no check needed here
+ *
+ * Field indexes, search (`textIndexes`/`embeddings`), `withHistory`
+ * (snapshot keys are rewrapped by `elevate()`/`demote()`, #712), and the
+ * decoded-record cache (evicted on tier moves) are already tier-safe. They
+ * are not enumerated below; only known-unsafe features are refused, so any
+ * combination not named here passes silently by default.
+ *
+ * ## Deliberately NOT handled here
+ *
+ * - `ledger` — `withHistory` threads a ledger writer onto every tiered
+ *   collection by default in shipped usage; refusing `tiers + ledger` would
+ *   break that default. A ledger-specific tier-rekey handler (rewrap ledger
+ *   entries, or scope ledger visibility to tier) is a separate arc.
+ * - materialized-view (MV) output — an MV's fanout spec lives on the
+ *   SOURCE collection, not on the MV collection's own config, so it is not
+ *   visible at `vault.collection()` registration time and this guard cannot
+ *   detect it structurally.
+ */
+export declare function assertTierComposition(collectionName: string, cfg: {
+    readonly tiers: boolean;
+    readonly blobFields: BlobFieldsConfig | undefined;
+}): void;
+/**
+ * Structural surface {@link syncDerivedOutputs} needs from the owning
+ * collection — the SAME onDelete dispatchers `forgetDerivedFanout` already
+ * drives (`kernel/via/dispatch.ts`), reused as-is (#722). Narrower than
+ * `Collection<T>` (avoids an import cycle: collection.ts constructs
+ * `TiersContext` FROM `this`, which already satisfies this shape
+ * structurally — no cast needed at the `tiersContext()` call site).
+ */
+export interface DerivedOutputsHost<T> {
+    dispatchMaterializedViewsOnDelete(id: string): Promise<{
+        deleted: number;
+        residueUndecodable: string[];
+        residueDeclined: string[];
+    }>;
+    dispatchArrayDerivationsOnDelete(id: string, eraseRecordShapeToo?: boolean): Promise<number>;
+    dispatchRollupsOnDelete(id: string, deleted: T): Promise<unknown>;
+    /** Task 2 (#722) add-direction: the same local-write dispatchers an ordinary `put()` fires. */
+    dispatchMaterializedViews(id: string, record: T): Promise<void>;
+    dispatchDerivations(id: string, record: T, version: number): Promise<void>;
+}
+/**
+ * The {@link TiersContext.syncDerived} implementation collection.ts's
+ * `tiersContext()` binds `this` into (#722). See that field's doc comment
+ * for the design; `host` is `this` — every dispatcher below is a public
+ * Collection method, already self-guarding (no-op) when the collection has
+ * no materialized-view/derivation source, so no separate fast-path check is
+ * needed here.
+ */
+export declare function syncDerivedOutputs<T>(host: DerivedOutputsHost<T>, id: string, record: T | null, elevated: boolean, version?: number): Promise<void>;
 /**
  * tier-aware put. Encrypts the record with the collection's tier-N DEK and
  * stamps `_tier: N` on the envelope. The caller's keyring must hold the tier-N
@@ -78,7 +340,7 @@ export declare function putAtTier<T>(ctx: TiersContext<T>, id: string, record: T
     };
     source?: string;
     sourceTs?: string;
-}): Promise<void>;
+}): Promise<TierMoveResult>;
 /**
  * tier-aware get. When the stored record is at a tier the caller cannot
  * decrypt:
@@ -100,18 +362,28 @@ export declare function listAtTier<T>(ctx: TiersContext<T>): Promise<Array<{
     tier: number;
     readable: boolean;
 }>>;
+/**
+ * Result of a completed `elevate()`/`demote()` (#764). The record move
+ * (put + indexes/cache/ledger/derived/history/blobs sync) always completes —
+ * `searchResidue: true` means only the search-index side (`_vec`/`_ftindex`)
+ * was left in a needs-retry state (a stuck `PersistedIndexCompensationError`),
+ * mirroring `forget()`'s `indexResidue` posture rather than aborting the move.
+ */
+export interface TierMoveResult {
+    readonly searchResidue: boolean;
+}
 /**
  * elevate a record to a higher tier. Re-encrypts with the target tier's DEK.
  * The caller must hold DEKs for both the current tier (to decrypt) and the
  * target tier (to re-encrypt). Stamps `_elevatedBy` with the caller id so
  * `demote()` can check the reverse operation.
  */
-export declare function elevate<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>;
+export declare function elevate<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<TierMoveResult>;
 /**
  * demote a record to a lower tier. Allowed only for the user who performed the
  * last elevation or an owner.
  */
-export declare function demote<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>;
+export declare function demote<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<TierMoveResult>;
 /**
  * Classify a live envelope's `_sealed` slots for crypto-shred completeness
  * (#M-1). Thin delegate to {@link RecordCodec.classifySealedShred}; surfaced

package/dist/with-audit/tiers/strategy.d.ts

@@ -8,7 +8,8 @@
  * @internal
  */
 import type { GhostRecord } from '../../kernel/types.js';
-import type { TiersContext } from './index.js';
+import type { TiersContext, TierMoveResult } from './index.js';
+export type { TierMoveResult };
 export interface TiersStrategy {
     putAtTier<T>(ctx: TiersContext<T>, id: string, record: T, tier: number, opts?: {
         elevation?: {
@@ -17,15 +18,15 @@ export interface TiersStrategy {
         };
         source?: string;
         sourceTs?: string;
-    }): Promise<void>;
+    }): Promise<TierMoveResult>;
     getAtTier<T>(ctx: TiersContext<T>, id: string): Promise<T | GhostRecord | null>;
     listAtTier<T>(ctx: TiersContext<T>): Promise<Array<{
         id: string;
         tier: number;
         readable: boolean;
     }>>;
-    elevate<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>;
-    demote<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<void>;
+    elevate<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<TierMoveResult>;
+    demote<T>(ctx: TiersContext<T>, id: string, toTier: number): Promise<TierMoveResult>;
 }
 /**
  * No-op stub — the floor default. Every capability method throws

package/dist/with-cargo/describe-extraction.d.ts

@@ -7,7 +7,7 @@
  * @module
  */
 import type { Vault } from '../kernel/vault.js';
-import { type WalkClosureOptions } from './walk-closure.js';
+import { type WalkClosureOptions, type DanglingRefNotice } from './walk-closure.js';
 export interface ExtractionPreview {
     readonly totalRecords: number;
     /** Sum of serialized encrypted-envelope sizes (bytes). */
@@ -29,5 +29,13 @@ export interface ExtractionPreview {
         readonly collection: string;
         readonly id: string;
     }>;
+    /**
+     * #772: outbound FK edges whose referenced parent was excluded from the
+     * closure (missing, or tier-elevated and therefore invisible) — mirrors
+     * `ExtractPartitionResult.danglingRefs` (#759) so a preview/extract pair
+     * gives the SAME signal. A parent excluded this way never appears in
+     * `byCollection` at all; this is the only preview-time indicator.
+     */
+    readonly danglingRefs: ReadonlyArray<DanglingRefNotice>;
 }
 export declare function describeExtraction(vault: Vault, opts: WalkClosureOptions): Promise<ExtractionPreview>;

package/dist/with-cargo/extract-partition.d.ts

@@ -9,7 +9,7 @@
 import type { Vault } from '../kernel/vault.js';
 import type { EncryptedEnvelope } from '../kernel/types.js';
 import { type EnclaveKey } from '../kernel/enclave/index.js';
-import { type WalkClosureOptions } from './walk-closure.js';
+import { type WalkClosureOptions, type DanglingRefNotice } from './walk-closure.js';
 import { type TransferSealPayload } from '../with-pod/bundle.js';
 /** Re-keyed collections snapshot + the fresh DEKs used. */
 export interface ReKeyResult {
@@ -113,6 +113,14 @@ export interface ExtractPartitionResult {
     /** Raw 32-byte transfer key — deliver out-of-band; required to adopt. */
     readonly transferKey: Uint8Array;
     readonly sealId: string;
+    /**
+     * #759: outbound FK edges whose referenced parent was excluded from the
+     * partition (missing, or tier-elevated and therefore invisible). The
+     * child record still carries its FK value; the parent did not travel —
+     * callers should surface this to the operator rather than assume
+     * referential completeness.
+     */
+    readonly danglingRefs: ReadonlyArray<DanglingRefNotice>;
 }
 /**
  * Extract a re-keyed, transfer-sealed partition. Owner-only

package/dist/with-cargo/walk-closure.d.ts

@@ -8,9 +8,10 @@
  *   1. INBOUND expansion: from selected records, pull every record
  *      that references them (children travel with parents), to a
  *      fixed point.
- *   2. OUTBOUND completion: pull every parent the selected set
- *      references (no dangling FKs), transitively, WITHOUT
- *      re-expanding inbound from those parents (bounds the closure).
+ *   2. OUTBOUND completion: pull every VISIBLE parent the selected set
+ *      references, transitively, WITHOUT re-expanding inbound from those
+ *      parents (bounds the closure). A tier-elevated (or missing) parent is
+ *      excluded rather than admitted — see `danglingRefs` on the result.
  *
  * The FK graph is auto-derived from the vault's existing RefRegistry
  * (the `ref('target')` declarations on collections) — no hand-written
@@ -25,6 +26,32 @@ export interface WalkClosureOptions {
     /** Max fixed-point iterations before throwing. Default 16. */
     readonly maxDepth?: number;
 }
+/**
+ * #759: an outbound FK edge whose referenced parent was excluded from the
+ * closure — either because it doesn't exist, or because it is tier-elevated
+ * and therefore invisible (same "elevated ≡ missing" semantics as root
+ * selection / inbound expansion). The child keeps its FK value; the parent
+ * does not travel. Callers (extract-partition) surface this as a residue
+ * notice rather than silently dropping it.
+ */
+export interface DanglingRefNotice {
+    /** Collection of the child record that holds the dangling FK. */
+    readonly collection: string;
+    /** Id of the child record. */
+    readonly id: string;
+    /** FK field on the child that references the missing/elevated parent. */
+    readonly field: string;
+    /** Target collection the FK points at. */
+    readonly target: string;
+    /** Id of the missing/elevated parent. */
+    readonly targetId: string;
+    /**
+     * #772: distinguishes an intentional tier boundary (`'elevated'` — the
+     * parent exists but is above the caller's readable tier) from a genuine
+     * data-integrity gap (`'missing'` — no envelope for `targetId` at all).
+     */
+    readonly reason: 'missing' | 'elevated';
+}
 export interface ClosureResult {
     /** collection → set of record ids that travel together. */
     readonly closure: Map<string, Set<string>>;
@@ -34,5 +61,7 @@ export interface ClosureResult {
         /** True if an edge pointed back to an already-selected node. */
         readonly cyclesDetected: boolean;
     };
+    /** #759: outbound FK edges whose parent was excluded (missing or elevated). */
+    readonly danglingRefs: ReadonlyArray<DanglingRefNotice>;
 }
 export declare function walkClosure(vault: Vault, opts: WalkClosureOptions): Promise<ClosureResult>;

package/dist/with-commit/history/history.d.ts

@@ -1,4 +1,5 @@
 import type { NoydbStore, EncryptedEnvelope, HistoryOptions, PruneOptions } from '../../kernel/types.js';
+import { type EnclaveKey } from '../../kernel/enclave/index.js';
 /** Save a history entry (a complete encrypted envelope snapshot). */
 export declare function saveHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, envelope: EncryptedEnvelope): Promise<void>;
 /** Get history entries for a record, sorted newest-first. */
@@ -25,3 +26,48 @@ export declare function clearHistory(adapter: NoydbStore, vault: string, collect
  * Returns the number of history versions newly tombstoned.
  */
 export declare function tombstoneHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, actor: string, encrypted: boolean): Promise<number>;
+/**
+ * Re-key every `_history` snapshot of a record from `fromDek` to `toDek`.
+ * Mirrors what `rewrapBodyToDek` already does for a record's LIVE body on a
+ * tier move (elevate/demote/putAtTier) — each `_history` envelope also
+ * carries its own `_cek`, wrapped under the collection's tier-0 DEK at write
+ * time (`record-codec.ts`), so a tier move that rewraps only the live
+ * envelope leaves prior versions decryptable at rest under the tier the
+ * record left. This is defense-in-depth *beneath* the read-gate
+ * (`history()`/`getVersion()` already return empty for an elevated record;
+ * this protects the ciphertext even if that gate is bypassed).
+ *
+ * Rewraps content in place — unlike `tombstoneHistory`, it does NOT blank
+ * `_iv`/`_data`/`_cek` — so a subsequent `demote()` restores tier-0
+ * readability. Tombstone-shaped entries (a forgotten/shredded version —
+ * blanked `_data`, no `_cek`) are skipped: there is no key material left to
+ * rewrap.
+ *
+ * **Legacy fallback.** A snapshot written before this fix stays wrapped
+ * under the tier-0 DEK even after its live record has since moved tiers, so
+ * a rewrap attempted with a tier-N `fromDek` fails to unwrap/decrypt. When
+ * the caller supplies `tier0Dek`, a failed rewrap is retried once with
+ * `tier0Dek` as `fromDek` (the only other key a pre-fix snapshot can be
+ * wrapped under — history is written only by tier-0 `put()`). The output is
+ * always wrapped under `toDek` regardless of which `fromDek` succeeded. A
+ * rewrap that fails under BOTH keys re-throws — that is real corruption, not
+ * a tier mismatch, and must not be swallowed.
+ *
+ * **Crash-atomicity / idempotency (#712 whole-branch-fix-3).** This loop has
+ * no transaction around it: a crash after some entries have been rewritten
+ * under `toDek` but before the loop finishes leaves the record's history
+ * split across two keys. A retry of the SAME call must not re-fail on the
+ * entries that already made it — so each entry is probed with
+ * `isRewrappedUnder(env, toDek)` FIRST; a match means it's already at the
+ * target key and is skipped (put nothing). This makes same-target retries
+ * and demote-after-crash fully self-healing. It does NOT close every crash
+ * window: a crash that lands SOME entries under `toDek` while the record's
+ * NEXT move target differs from this call's `toDek` (an intermediate-tier
+ * crash — e.g. elevate 0→1 crashes mid-loop, then the record is moved 1→2)
+ * still finds those entries unreadable under either `fromDek` or the
+ * tier-0 fallback, since `toDek` is a third key the next call never probes
+ * for. That residual window is an accepted, fail-closed limitation (see
+ * `.changeset/history-at-rest.md` and the design doc) — availability is
+ * lost, never confidentiality.
+ */
+export declare function rewrapHistory(adapter: NoydbStore, vault: string, collection: string, recordId: string, fromDek: EnclaveKey, toDek: EnclaveKey, tier0Dek?: EnclaveKey): Promise<void>;