@noy-db/hub 0.2.0-pre.17 → 0.2.0-pre.18

package/dist/bundle/index.cjs

@@ -4343,6 +4343,21 @@ function formatCurrency(decimal, currency, scale, locale) {
   });
   return fmt.format(decimal);
 }
+function moneyScaledValue(stored, desc) {
+  let raw;
+  if (desc.mode === "fixed") {
+    raw = stored;
+  } else {
+    if (!isMoneyValueObject(stored)) return null;
+    raw = stored.amount;
+  }
+  if (typeof raw !== "string" && typeof raw !== "number") return null;
+  try {
+    return BigInt(String(raw));
+  } catch {
+    return null;
+  }
+}
 function decodeValue(stored, desc) {
   let currency;
   let scaledIntString;
@@ -5300,7 +5315,7 @@ function executePlanWithSource(source, plan, joinContext) {
     result = remainingClauses.length === 0 ? [...candidates] : filterRecords(candidates, remainingClauses, fnViewDecoder(source));
   }
   if (plan.orderBy.length > 0) {
-    result = sortRecords(result, plan.orderBy);
+    result = sortRecords(result, plan.orderBy, source.moneyFields);
   }
   if (plan.offset > 0) {
     result = result.slice(plan.offset);
@@ -5439,17 +5454,25 @@ function applyCrossJoin(leftRel, clause, rightSource) {
   }
   return expanded;
 }
-function sortRecords(records, orderBy) {
+function sortRecords(records, orderBy, moneyFields) {
   return [...records].sort((a, b) => {
     for (const { field, direction } of orderBy) {
       const av = readField(a, field);
       const bv = readField(b, field);
-      const cmp = compareValues(av, bv);
+      const desc = moneyFields?.[field];
+      const cmp = desc ? compareMoney(av, bv, desc) : compareValues(av, bv);
       if (cmp !== 0) return direction === "asc" ? cmp : -cmp;
     }
     return 0;
   });
 }
+function compareMoney(a, b, desc) {
+  const av = moneyScaledValue(a, desc);
+  const bv = moneyScaledValue(b, desc);
+  if (av === null) return bv === null ? 0 : 1;
+  if (bv === null) return -1;
+  return av < bv ? -1 : av > bv ? 1 : 0;
+}
 function readField(record, field) {
   if (record === null || record === void 0) return void 0;
   if (!field.includes(".")) {
@@ -8272,6 +8295,15 @@ var init_fanout_sidecar = __esm({
 });
 
 // src/collection.ts
+function selfWriteFieldEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null || typeof a !== "object" || typeof b !== "object") return false;
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false;
+  }
+}
 function warnOnceFallback(adapterName) {
   if (fallbackWarned.has(adapterName)) return;
   fallbackWarned.add(adapterName);
@@ -9276,6 +9308,111 @@ var init_collection = __esm({
        * output (carries `_derivedFrom`) — defensive guard against missed
        * cycle detection.
        */
+      /**
+       * @internal #376 — the RAW stored record (canonical-money form, i18n maps
+       * intact), WITHOUT the locale resolution `get()` applies. Used as the
+       * patch base for self-write reverse-denorm so writing back never clobbers
+       * an i18n map or re-quantizes money incorrectly. Returns null for
+       * missing / tombstoned records.
+       */
+      async _getStoredRecord(id) {
+        let raw;
+        if (this.lazy && this.lru) {
+          const cached = this.lru.get(id);
+          if (cached) raw = cached.record;
+          else {
+            const env = await this.adapter.get(this.vault, this.name, id);
+            if (!env || isTombstone(env, this.encrypted)) return null;
+            raw = await this.decryptRecord(env, { id });
+            if (raw === null) return null;
+            this.lru.set(id, { record: raw, version: env._v }, estimateRecordBytes(raw));
+          }
+        } else {
+          await this.ensureHydrated();
+          raw = this.cache.get(id)?.record ?? null;
+        }
+        if (raw === null) return null;
+        return canonicalizeStoredMoney(raw, this.moneyFields);
+      }
+      /**
+       * @internal #376 — ids of records whose top-level `field` equals `value`.
+       * Uses the FK index when the field is indexed (O(matches)); otherwise a
+       * linear scan (O(N) — fine for small child sets; index the FK to scale).
+       */
+      async _findMatchingIds(field, value) {
+        const hit = this.getIndexes()?.lookupEqual(field, value);
+        if (hit) return [...hit];
+        const target = String(value);
+        const matches = (rec) => {
+          const fv = rec[field];
+          return (typeof fv === "string" || typeof fv === "number") && String(fv) === target;
+        };
+        if (!this.lazy) {
+          await this.ensureHydrated();
+          const out2 = [];
+          for (const [rid, e] of this.cache) {
+            if (matches(e.record)) out2.push(rid);
+          }
+          return out2;
+        }
+        const ids = await this.adapter.list(this.vault, this.name);
+        const out = [];
+        for (const rid of ids) {
+          const raw = await this._getStoredRecord(rid);
+          if (raw !== null && matches(raw)) out.push(rid);
+        }
+        return out;
+      }
+      /**
+       * @internal #376 slice 2 — recompute a rollup aggregate onto the parent.
+       * Gathers every child of `parentId`, runs `compute`, and patches only the
+       * rollup `field` onto the parent's raw stored record (value-equality
+       * guarded). No-op when the parent record does not exist.
+       */
+      async recomputeRollup(spec, parentId) {
+        if (this.derivationSource === void 0 || spec.rollup === void 0) return;
+        const { from, key, field, compute } = spec.rollup;
+        const into = spec.source;
+        const intoColl = this.derivationSource.getCollection(into);
+        const base = await intoColl._getStoredRecord(parentId);
+        if (base === null) return;
+        const fromColl = this.derivationSource.getCollection(from);
+        const childIds = await fromColl._findMatchingIds(key, parentId);
+        const children = [];
+        for (const cid of childIds) {
+          const c = await fromColl.get(cid);
+          if (c !== null && c !== void 0) children.push(c);
+        }
+        const newValue = compute(children);
+        if (selfWriteFieldEqual(base[field], newValue)) return;
+        const patched = { ...base, [field]: newValue };
+        const txCtx = this.derivationSource.getActiveTxContext();
+        if (txCtx !== null) {
+          const prior = await this.adapter.get(this.vault, into, parentId);
+          txCtx._executed.push({
+            op: { type: "put", vaultName: this.vault, collectionName: into, id: parentId },
+            priorEnvelope: prior
+          });
+        }
+        await intoColl.put(parentId, patched);
+      }
+      /**
+       * @internal #376 slice 2 — fire any rollups for which THIS collection is the
+       * child `from`, recomputing the affected parent after a child delete. Called
+       * from the delete path with the just-removed record's key value. Other
+       * derivation kinds do not react to deletes (unchanged).
+       */
+      async dispatchRollupsOnDelete(deleted) {
+        if (this.derivationSource === void 0) return;
+        const registry = this.derivationSource.registry();
+        const rec = deleted;
+        for (const { spec } of registry.strategiesForSource(this.name)) {
+          if (!spec.rollup || spec.rollup.from !== this.name) continue;
+          const kv = rec[spec.rollup.key];
+          if (typeof kv !== "string" && typeof kv !== "number") continue;
+          await this.recomputeRollup(spec, String(kv));
+        }
+      }
       async dispatchDerivations(id, record, version) {
         if (this.derivationSource === void 0) return;
         const incoming = canonicalizeStoredMoney(record, this.moneyFields);
@@ -9286,29 +9423,60 @@ var init_collection = __esm({
         let DerivationExecutor2 = null;
         for (const { spec, strategyHash } of strategies) {
           const mode = typeof spec.lifecycle === "string" ? spec.lifecycle : spec.lifecycle.mode;
-          if (mode === "eager") {
-            if (DerivationExecutor2 === null) {
-              ({ DerivationExecutor: DerivationExecutor2 } = await Promise.resolve().then(() => (init_executor(), executor_exports)));
-            }
-            let sourceWithId;
-            let sourceVersion = version;
-            if (spec.source === this.name) {
-              sourceWithId = { ...incoming, id };
+          if (spec.rollup) {
+            if (mode !== "eager") continue;
+            let parentId;
+            if (this.name === spec.rollup.from) {
+              const kv = incoming[spec.rollup.key];
+              parentId = typeof kv === "string" || typeof kv === "number" ? String(kv) : null;
             } else {
-              const primary = await this.derivationSource.getCollection(spec.source).get(id);
-              if (primary === null || primary === void 0) continue;
-              sourceWithId = { ...primary, id };
-              sourceVersion = 0;
+              parentId = id;
+            }
+            if (parentId !== null) await this.recomputeRollup(spec, parentId);
+            continue;
+          }
+          const isSource = spec.source === this.name;
+          const isSibling = !isSource && (spec.sources?.includes(this.name) ?? false);
+          const trigger = !isSource && !isSibling ? spec.triggerBy?.find((t) => t.collection === this.name) : void 0;
+          const runs = [];
+          if (isSource) {
+            runs.push({ input: { ...incoming, id }, base: incoming, runId: id, version });
+          } else if (isSibling) {
+            const p = await this.derivationSource.getCollection(spec.source).get(id);
+            if (p !== null && p !== void 0) {
+              const raw = await this.derivationSource.getCollection(spec.source)._getStoredRecord(id);
+              runs.push({ input: { ...p, id }, base: raw ?? p, runId: id, version: 0 });
             }
+          } else if (trigger) {
+            const srcColl = this.derivationSource.getCollection(spec.source);
+            const ids = await srcColl._findMatchingIds(trigger.on, id);
+            if (trigger.maxFanout !== void 0 && ids.length > trigger.maxFanout) {
+              throw new DerivationCapExceededError(`triggerBy ${this.name}\u2192${spec.source}`, ids.length, trigger.maxFanout);
+            }
+            for (const sid of ids) {
+              const raw = await srcColl._getStoredRecord(sid);
+              if (raw === null) continue;
+              runs.push({ input: { ...raw, id: sid }, base: raw, runId: sid, version: 0 });
+            }
+          }
+          if (runs.length === 0) continue;
+          if (mode !== "eager") {
+            for (const run of runs) await markStale(registry, spec, run.runId);
+            continue;
+          }
+          if (DerivationExecutor2 === null) {
+            ({ DerivationExecutor: DerivationExecutor2 } = await Promise.resolve().then(() => (init_executor(), executor_exports)));
+          }
+          for (const run of runs) {
             const ctx = { vault: this.derivationSource.getReadOnlyFacade() };
-            const result = await DerivationExecutor2.run(spec, sourceWithId, sourceVersion, strategyHash, ctx);
+            const result = await DerivationExecutor2.run(spec, run.input, run.version, strategyHash, ctx);
             for (const key of Object.keys(spec.outputs)) {
               const out = result.outputs[key];
               if (!out) continue;
               if (out.kind === "failed") {
                 const err = out.error;
                 if (spec.strict) throw err;
-                console.warn(`[derivation] output "${key}" for source "${spec.source}" id="${id}" failed:`, err);
+                console.warn(`[derivation] output "${key}" for source "${spec.source}" id="${run.runId}" failed:`, err);
                 continue;
               }
               const outSpec = spec.outputs[key];
@@ -9321,7 +9489,7 @@ var init_collection = __esm({
                   this.adapter,
                   this.vault,
                   spec.source,
-                  id,
+                  run.runId,
                   key
                 );
                 const prevKeys = new Set(prior?.keys ?? []);
@@ -9348,7 +9516,7 @@ var init_collection = __esm({
                 }
                 await saveFanoutSidecar2(this.adapter, this.vault, {
                   source: spec.source,
-                  sourceId: id,
+                  sourceId: run.runId,
                   outputKey: key,
                   outputCollection: outSpec.collection,
                   keys: newKeysList
@@ -9356,25 +9524,44 @@ var init_collection = __esm({
                 continue;
               }
               if (out.skipped === true) {
-                await outputCollection._internalDelete(id, txCtx);
+                await outputCollection._internalDelete(run.runId, txCtx);
+                continue;
+              }
+              if (outSpec.shape === "record" && outSpec.denorm !== void 0 && outSpec.collection === spec.source) {
+                const value = out.value;
+                const patched = { ...run.base };
+                let changed = false;
+                for (const f of outSpec.denorm) {
+                  if (!selfWriteFieldEqual(run.base[f], value[f])) {
+                    patched[f] = value[f];
+                    changed = true;
+                  }
+                }
+                if (!changed) continue;
+                if (txCtx !== null) {
+                  const prior = await this.adapter.get(this.vault, outSpec.collection, run.runId);
+                  txCtx._executed.push({
+                    op: { type: "put", vaultName: this.vault, collectionName: outSpec.collection, id: run.runId },
+                    priorEnvelope: prior
+                  });
+                }
+                await outputCollection.put(run.runId, patched);
                 continue;
               }
               if (txCtx !== null) {
-                const prior = await this.adapter.get(this.vault, outSpec.collection, id);
+                const prior = await this.adapter.get(this.vault, outSpec.collection, run.runId);
                 txCtx._executed.push({
                   op: {
                     type: "put",
                     vaultName: this.vault,
                     collectionName: outSpec.collection,
-                    id
+                    id: run.runId
                   },
                   priorEnvelope: prior
                 });
               }
-              await outputCollection.put(id, out.value);
+              await outputCollection.put(run.runId, out.value);
             }
-          } else {
-            await markStale(registry, spec, id);
           }
         }
       }
@@ -9591,6 +9778,7 @@ var init_collection = __esm({
         if (!internal) {
           await this.dispatchMaterializedViewsOnDelete(id);
           await this.dispatchArrayDerivationsOnDelete(id);
+          if (existing) await this.dispatchRollupsOnDelete(existing.record);
         }
       }
       /**
@@ -10645,14 +10833,15 @@ var init_collection = __esm({
           (d) => isStaticDictDescriptor(d) && d.displayLocale !== void 0
         );
         if (!locale && !hasStaticDisplay) return result;
+        const layer = localeOpts?._layer ?? "read";
         if (locale && hasI18n && this.i18nFields) {
-          result = this.i18nStrategy.applyI18nLocale(result, this.i18nFields, locale, localeOpts?.fallback);
+          result = this.i18nStrategy.applyI18nLocale(result, this.i18nFields, locale, localeOpts?.fallback, layer);
         }
         if (hasDict && this.dictKeyFields && this.dictLabelResolver && locale !== "raw") {
           const withLabels = { ...result };
           const resolver = this.dictLabelResolver;
           for (const [field, desc] of Object.entries(this.dictKeyFields)) {
-            const policy = desc.onMissing ? resolvePolicy(desc.onMissing, "read") : "null";
+            const policy = desc.onMissing ? resolvePolicy(desc.onMissing, layer) : "null";
             const fallback = policy === "substitute" ? localeOpts?.fallback ?? desc.substitute : localeOpts?.fallback;
             const effLocale = locale ?? (isStaticDictDescriptor(desc) ? desc.displayLocale : void 0);
             const resolveKey = async (key) => {
@@ -11672,6 +11861,35 @@ var init_archive = __esm({
 });
 
 // src/sequence/index.ts
+function compileSequenceFormat(format, series, partition) {
+  const parts = partition ?? [];
+  for (const m of format.matchAll(SEQ_FORMAT_TOKEN)) {
+    const token = m[1] ?? "";
+    if (token === "seq") continue;
+    if (SEQ_PAD_TOKEN.test(token)) continue;
+    const partMatch = SEQ_PARTITION_TOKEN.exec(token);
+    if (partMatch) {
+      const idx = Number(partMatch[1]);
+      if (idx >= parts.length) {
+        throw new ValidationError(
+          `sequence("${series}"): format token "{${token}}" references partition index ${idx}, but only ${parts.length} partition component(s) were supplied.`
+        );
+      }
+      continue;
+    }
+    throw new ValidationError(
+      `sequence("${series}"): format contains unknown token "{${token}}". Accepted tokens: {seq}, {seq:0N}, {partition.i}.`
+    );
+  }
+  return (serial) => format.replace(SEQ_FORMAT_TOKEN, (full, token) => {
+    if (token === "seq") return String(serial);
+    const padMatch = SEQ_PAD_TOKEN.exec(token);
+    if (padMatch) return String(serial).padStart(Number(padMatch[1]), "0");
+    const partMatch = SEQ_PARTITION_TOKEN.exec(token);
+    if (partMatch) return String(parts[Number(partMatch[1])]);
+    return full;
+  });
+}
 function resolveSequenceKey(series, opts) {
   const partition = opts?.partition;
   if (!partition || partition.length === 0) return series;
@@ -11692,7 +11910,7 @@ async function sleepBackoff2(attempt) {
   const ms = Math.floor(Math.random() * ceil);
   await new Promise((r) => setTimeout(r, ms));
 }
-var SEQUENCE_COLLECTION, MAX_NEXT_ATTEMPTS, SequenceStore;
+var SEQUENCE_COLLECTION, MAX_NEXT_ATTEMPTS, SEQ_FORMAT_TOKEN, SEQ_PAD_TOKEN, SEQ_PARTITION_TOKEN, SequenceStore;
 var init_sequence = __esm({
   "src/sequence/index.ts"() {
     "use strict";
@@ -11701,6 +11919,9 @@ var init_sequence = __esm({
     init_errors();
     SEQUENCE_COLLECTION = "_sequences";
     MAX_NEXT_ATTEMPTS = 16;
+    SEQ_FORMAT_TOKEN = /\{([^{}]*)\}/g;
+    SEQ_PAD_TOKEN = /^seq:0(\d+)$/;
+    SEQ_PARTITION_TOKEN = /^partition\.(\d+)$/;
     SequenceStore = class {
       adapter;
       vault;
@@ -12145,6 +12366,9 @@ var init_strategy10 = __esm({
 });
 
 // src/refs.ts
+function isRefArray(desc) {
+  return desc.isArray === true;
+}
 var RefIntegrityError, RefRegistry;
 var init_refs = __esm({
   "src/refs.ts"() {
@@ -12190,7 +12414,7 @@ var init_refs = __esm({
           for (const k of existingKeys) {
             const a = existing[k];
             const b = refs[k];
-            if (!a || !b || a.target !== b.target || a.mode !== b.mode) {
+            if (!a || !b || a.target !== b.target || a.mode !== b.mode || a.isArray !== b.isArray) {
               throw new Error(
                 `RefRegistry: conflicting ref declarations for collection "${collection}" field "${k}"`
               );
@@ -12201,7 +12425,7 @@ var init_refs = __esm({
         this.outbound.set(collection, { ...refs });
         for (const [field, desc] of Object.entries(refs)) {
           const list = this.inbound.get(desc.target) ?? [];
-          list.push({ collection, field, mode: desc.mode });
+          list.push({ collection, field, mode: desc.mode, ...desc.isArray ? { isArray: true } : {} });
           this.inbound.set(desc.target, list);
         }
       }
@@ -12231,6 +12455,150 @@ var init_refs = __esm({
   }
 });
 
+// src/links/link-set.ts
+function linkCollectionName(name) {
+  return `${LINK_COLLECTION_PREFIX}${name}`;
+}
+function isLinkCollectionName(name) {
+  return name.startsWith(LINK_COLLECTION_PREFIX);
+}
+function linkRowKey(aId, bId) {
+  return `${encodeURIComponent(aId)}|${encodeURIComponent(bId)}`;
+}
+var LINK_COLLECTION_PREFIX, LinkSet, LinkEndpointError, LinkIntegrityError;
+var init_link_set = __esm({
+  "src/links/link-set.ts"() {
+    "use strict";
+    init_types();
+    init_crypto();
+    init_errors();
+    LINK_COLLECTION_PREFIX = "_links_";
+    LinkSet = class {
+      constructor(adapter, vault, name, spec, encrypted, getDEK, actor, emitter, endpointExists) {
+        this.adapter = adapter;
+        this.vault = vault;
+        this.name = name;
+        this.spec = spec;
+        this.encrypted = encrypted;
+        this.getDEK = getDEK;
+        this.actor = actor;
+        this.emitter = emitter;
+        this.endpointExists = endpointExists;
+        this.collName = linkCollectionName(name);
+      }
+      adapter;
+      vault;
+      name;
+      spec;
+      encrypted;
+      getDEK;
+      actor;
+      emitter;
+      endpointExists;
+      collName;
+      dekPromise = null;
+      dek() {
+        if (!this.dekPromise) this.dekPromise = this.getDEK(this.collName);
+        return this.dekPromise;
+      }
+      async encryptEntry(entry, version) {
+        const json = JSON.stringify(entry);
+        const base = { _noydb: NOYDB_FORMAT_VERSION, _v: version, _ts: (/* @__PURE__ */ new Date()).toISOString(), _by: this.actor };
+        if (!this.encrypted) return { ...base, _iv: "", _data: json };
+        const { iv, data } = await encrypt(json, await this.dek());
+        return { ...base, _iv: iv, _data: data };
+      }
+      async decryptEntry(env) {
+        const json = this.encrypted ? await decrypt(env._iv, env._data, await this.dek()) : env._data;
+        return JSON.parse(json);
+      }
+      async connect(aId, bId, meta) {
+        if (!await this.endpointExists(this.spec.a, aId)) {
+          throw new LinkEndpointError(this.name, this.spec.a, aId);
+        }
+        if (!await this.endpointExists(this.spec.b, bId)) {
+          throw new LinkEndpointError(this.name, this.spec.b, bId);
+        }
+        const key = linkRowKey(aId, bId);
+        const entry = meta !== void 0 ? { a: aId, b: bId, meta } : { a: aId, b: bId };
+        const existing = await this.adapter.get(this.vault, this.collName, key);
+        const env = await this.encryptEntry(entry, (existing?._v ?? 0) + 1);
+        await this.adapter.put(this.vault, this.collName, key, env, existing?._v);
+        this.emitter.emit("change", { vault: this.vault, collection: this.collName, id: key, action: "put" });
+      }
+      async disconnect(aId, bId) {
+        const key = linkRowKey(aId, bId);
+        const existing = await this.adapter.get(this.vault, this.collName, key);
+        if (!existing) return;
+        await this.adapter.delete(this.vault, this.collName, key);
+        this.emitter.emit("change", { vault: this.vault, collection: this.collName, id: key, action: "delete" });
+      }
+      async has(aId, bId) {
+        return await this.adapter.get(this.vault, this.collName, linkRowKey(aId, bId)) !== null;
+      }
+      async of(id) {
+        const rows = await this.list();
+        return rows.filter((r) => r.a === id || r.b === id);
+      }
+      async list() {
+        const keys = await this.adapter.list(this.vault, this.collName);
+        const out = [];
+        for (const key of keys) {
+          const env = await this.adapter.get(this.vault, this.collName, key);
+          if (!env) continue;
+          const e = await this.decryptEntry(env);
+          out.push(e.meta !== void 0 ? { a: e.a, b: e.b, meta: e.meta } : { a: e.a, b: e.b });
+        }
+        return out;
+      }
+      // ── Vault-internal cascade helpers ──────────────────────────────────
+      /** @internal — rows where the deleted endpoint id matches the relevant slot. */
+      async _rowsTouchingEndpoint(collection, id) {
+        const rows = await this.list();
+        return rows.filter(
+          (r) => this.spec.a === collection && r.a === id || this.spec.b === collection && r.b === id
+        );
+      }
+      /** @internal — the storage collection name (for tx pre-image capture). */
+      get _collectionName() {
+        return this.collName;
+      }
+    };
+    LinkEndpointError = class extends NoydbError {
+      link;
+      endpoint;
+      missingId;
+      constructor(link, endpoint, missingId) {
+        super(
+          "LINK_ENDPOINT",
+          `link("${link}").connect: endpoint "${endpoint}" has no record "${missingId}".`
+        );
+        this.name = "LinkEndpointError";
+        this.link = link;
+        this.endpoint = endpoint;
+        this.missingId = missingId;
+      }
+    };
+    LinkIntegrityError = class extends NoydbError {
+      link;
+      endpoint;
+      id;
+      count;
+      constructor(link, endpoint, id, count) {
+        super(
+          "LINK_INTEGRITY",
+          `Cannot delete "${endpoint}"/"${id}": ${count} link(s) in "${link}" still reference it (onDelete: 'strict').`
+        );
+        this.name = "LinkIntegrityError";
+        this.link = link;
+        this.endpoint = endpoint;
+        this.id = id;
+        this.count = count;
+      }
+    };
+  }
+});
+
 // src/periods/periods.ts
 var PERIODS_COLLECTION;
 var init_periods = __esm({
@@ -13906,14 +14274,17 @@ var init_read_only_facade = __esm({
     "use strict";
     ReadOnlyVaultFacade = class {
       _vault;
-      constructor(vault) {
+      _layer;
+      constructor(vault, layer = "read") {
         this._vault = vault;
+        this._layer = layer;
       }
       collection(name) {
         const c = this._vault.collection(name);
+        const layer = this._layer;
         return {
-          get: (id) => c.get(id),
-          list: () => c.list(),
+          get: (id) => c.get(id, { _layer: layer }),
+          list: () => c.list({ _layer: layer }),
           query: () => c.query()
         };
       }
@@ -13969,6 +14340,16 @@ var init_registry3 = __esm({
           if (fromExtra) fromExtra.push(reg);
           else this._bySource.set(extra, [reg]);
         }
+        for (const t of spec.triggerBy ?? []) {
+          const fromTrigger = this._bySource.get(t.collection);
+          if (fromTrigger) fromTrigger.push(reg);
+          else this._bySource.set(t.collection, [reg]);
+        }
+        if (spec.rollup) {
+          const fromRollup = this._bySource.get(spec.rollup.from);
+          if (fromRollup) fromRollup.push(reg);
+          else this._bySource.set(spec.rollup.from, [reg]);
+        }
         for (const key of outputKeys) {
           const output = spec.outputs[key];
           if (!output) continue;
@@ -14022,6 +14403,9 @@ var init_registry3 = __esm({
               for (const key of Object.keys(s.spec.outputs)) {
                 const output = s.spec.outputs[key];
                 if (!output) continue;
+                if (output.shape === "record" && output.collection === s.spec.source && output.denorm !== void 0) {
+                  continue;
+                }
                 visit(output.collection);
               }
             }
@@ -14237,6 +14621,7 @@ var init_vault = __esm({
     init_strategy10();
     init_refs();
     init_dictionary();
+    init_link_set();
     init_core();
     init_strategy2();
     init_sync_strategy();
@@ -14329,13 +14714,17 @@ var init_vault = __esm({
        */
       overlayedViewRegistry = null;
       /**
-       * Cached read-only facade handed to guard callbacks via `ctx.vault`,
-       * and to derivation callbacks via `derive(source, ctx)`. Allocated
-       * eagerly inside `_initGuards()` and/or `_initDerivations()` so read
+       * Cached read-only facades handed to guard callbacks via `ctx.vault`
+       * and to derivation callbacks via `derive(source, ctx)`. Split by
+       * resolution layer (#285): the guard facade reads at `layer:'guard'`,
+       * the derivation facade at `layer:'derivation'`, so i18nText / dictKey
+       * fields resolve under that layer's `onMissing` policy. Allocated
+       * eagerly inside `_initGuards()` / `_initDerivations()` so read
        * accessors stay synchronous (callers in `tx/transaction.ts` rely on
-       * that). Stays `null` for vaults with neither subsystem configured.
+       * that). Each stays `null` for vaults without that subsystem.
        */
-      readOnlyFacade = null;
+      guardFacade = null;
+      derivationFacade = null;
       getDEK;
       /**
        * Per-principal user envelope API.
@@ -14497,6 +14886,10 @@ var init_vault = __esm({
       i18nFieldRegistry = /* @__PURE__ */ new Map();
       /** Cache of DictionaryHandle instances, one per dictionary name. */
       dictionaryCache = /* @__PURE__ */ new Map();
+      /** Registered link specs (#377-B), keyed by link name; set by `vault.link()`. */
+      linkRegistry = /* @__PURE__ */ new Map();
+      /** Cache of LinkSet handles, one per link name. */
+      linkSetCache = /* @__PURE__ */ new Map();
       /** — subscribers for cross-tier access events. */
       crossTierSubs = /* @__PURE__ */ new Set();
       /** — currently-active elevation, or null. One per vault. */
@@ -14613,6 +15006,9 @@ var init_vault = __esm({
         if (collectionName === SEQUENCE_COLLECTION) {
           throw new ReservedCollectionNameError(collectionName);
         }
+        if (isLinkCollectionName(collectionName)) {
+          throw new ReservedCollectionNameError(collectionName);
+        }
         let coll = this.collectionCache.get(collectionName);
         if (coll && options?.moneyFields) {
           coll._applyMoneyFields(options.moneyFields);
@@ -14684,6 +15080,7 @@ var init_vault = __esm({
             }));
             schemaUpdateGate = new SchemaUpdateGate(work);
           }
+          const effectiveHistoryConfig = options?.historyConfig ?? this.historyConfig;
           const collOpts = {
             adapter: this.adapter,
             vault: this.name,
@@ -14699,7 +15096,7 @@ var init_vault = __esm({
             schemaFence: this.schemaFence,
             getDEK: this.getDEK,
             onDirty: this.onDirty,
-            historyConfig: this.historyConfig,
+            historyConfig: effectiveHistoryConfig,
             // thread the vault-wide blob strategy into every
             // collection. `undefined` is intentionally preserved so the
             // Collection constructor uses its NO_BLOBS default.
@@ -14710,7 +15107,11 @@ var init_vault = __esm({
             historyStrategy: this.historyStrategy,
             i18nStrategy: this.i18nStrategy,
             syncStrategy: this.syncStrategy,
-            ledger: this.getLedgerOrNull() ?? void 0,
+            // Per-collection ledger opt-out (#361): when this collection sets
+            // `historyConfig.ledger: false`, withhold the ledger reference so all
+            // four `if (this.ledger)` append sites in Collection no-op. The chain
+            // stays valid — it simply never receives this collection's entries.
+            ledger: effectiveHistoryConfig.ledger === false ? void 0 : this.getLedgerOrNull() ?? void 0,
             refEnforcer: this,
             joinResolver: this,
             defaultLocale: this.locale,
@@ -15071,6 +15472,68 @@ var init_vault = __esm({
         }
         return handle;
       }
+      /**
+       * Declare a managed many-to-many link set (#377-B). Registers a
+       * `_links_<name>` junction between two endpoint collections; access its
+       * rows via `vault.links(name)`. Idempotent for an identical re-declaration;
+       * a conflicting one throws. See {@link links}.
+       *
+       * ```ts
+       * vault.link('saleLineLinks', { a: ref('saleLines'), b: ref('purchaseLines'), onDelete: 'cascade' })
+       * ```
+       *
+       * `a` / `b` accept either a collection name or a `ref(target)` descriptor
+       * (only its `target` is used — links manage their own integrity). `onDelete`
+       * governs what happens to link rows when an endpoint record is deleted
+       * (`'cascade'` default, `'strict'`, `'warn'`).
+       */
+      link(name, spec) {
+        const a = typeof spec.a === "string" ? spec.a : spec.a.target;
+        const b = typeof spec.b === "string" ? spec.b : spec.b.target;
+        for (const [slot, target] of [["a", a], ["b", b]]) {
+          if (!target || target.startsWith("_") || target.includes("/")) {
+            throw new ValidationError(
+              `vault.link("${name}"): endpoint "${slot}" must be a simple collection name, got "${target}".`
+            );
+          }
+        }
+        const resolved = { a, b, ...spec.onDelete ? { onDelete: spec.onDelete } : {} };
+        const existing = this.linkRegistry.get(name);
+        if (existing) {
+          if (existing.a !== resolved.a || existing.b !== resolved.b || (existing.onDelete ?? "cascade") !== (resolved.onDelete ?? "cascade")) {
+            throw new ValidationError(`vault.link("${name}"): conflicting re-declaration.`);
+          }
+          return;
+        }
+        this.linkRegistry.set(name, resolved);
+      }
+      /**
+       * Access a declared link set (#377-B). Throws if `name` was not first
+       * declared via {@link link}. Returns a cached {@link LinkSetHandle}:
+       * `connect(a, b, meta?)`, `disconnect(a, b)`, `has(a, b)`, `of(id)`, `list()`.
+       */
+      links(name) {
+        let handle = this.linkSetCache.get(name);
+        if (!handle) {
+          const spec = this.linkRegistry.get(name);
+          if (!spec) {
+            throw new ValidationError(`vault.links("${name}"): not declared. Call vault.link("${name}", { a, b }) first.`);
+          }
+          handle = new LinkSet(
+            this.adapter,
+            this.name,
+            name,
+            spec,
+            this.encrypted,
+            this.getDEK,
+            this.keyring.userId,
+            this.emitter,
+            async (collection, id) => await this.collection(collection).get(id) !== null
+          );
+          this.linkSetCache.set(name, handle);
+        }
+        return handle;
+      }
       /**
        * Build a `JoinableSource` for a dictKey field, for use in dict joins
        *. Returns a source whose snapshot contains `{ key, ...labels }`
@@ -15230,65 +15693,16 @@ var init_vault = __esm({
           });
         }
       }
-      /**
-       * Bulk blob extraction primitive.
-       *
-       * Returns an async-iterable handle over every blob attached to
-       * records in the vault. Single capability check (`plaintext/blob`)
-       * at handle creation; single audit entry to `_export_audit` before
-       * the first yield. Per-blob decryption happens lazily as the
-       * consumer pulls tuples.
-       *
-       * ```ts
-       * const handle = vault.exportBlobs({
-       *   collections: ['invoiceScans'],
-       *   where: (rec) => (rec as { clientId?: string }).clientId === 'c-123',
-       * })
-       * for await (const { bytes, meta, recordRef } of handle) {
-       *   await uploadToColdStorage(bytes, recordRef)
-       * }
-       * ```
-       *
-       * @see `@noy-db/hub/store/export-blobs` for the full option surface.
-       */
-      /**
-       * Evict blob slots per the per-collection `blobFields` retention
-       * policy.
-       *
-       * Iterates every collection declared with `{ blobFields: {...} }`.
-       * For each record, checks every configured slot against its
-       * policy — `retainDays` (age-based TTL) and/or `evictWhen(record)`
-       * (predicate) — and evicts matching slots. Every eviction writes
-       * one entry to `_blob_eviction_audit` (actor + eTag + reason +
-       * timestamp, no plaintext). Consumer-scheduled; noy-db never runs
-       * this on its own.
-       *
-       * ```ts
-       * await vault.compact()                                   // run full pass
-       * await vault.compact({ dryRun: true })                   // preview counts
-       * await vault.compact({ maxEvictions: 1000 })             // cap batch
-       * ```
-       */
-      /**
-       * Atomic, gap-free numbering. `vault.sequence('invoice-2026').next()`
-       * returns 1, 2, 3, … with no gaps or duplicates under concurrency, via
-       * an optimistic-CAS counter at `_sequences/<name>`. Each name is an
-       * independent sequence.
-       *
-       * **Online-only:** `next()` throws `SequenceOfflineError` unless the
-       * store advertises `capabilities.casAtomic` — gap-free numbering cannot
-       * be serialized by an offline / non-CAS writer.
-       *
-       * ```ts
-       * const n = await vault.sequence('invoice-2026').next()   // 1, then 2, …
-       * const cur = await vault.sequence('invoice-2026').peek()  // current value, no allocation
-       * ```
-       */
       sequence(series, opts) {
         if (series.includes("\0")) {
           throw new ValidationError(`sequence("${series}"): series name must not contain a null byte (\\x00).`);
         }
         if (this.numberingConfigs.has(series)) {
+          if (opts?.format !== void 0) {
+            throw new ValidationError(
+              `sequence("${series}") is a deferred-numbering series; the format option applies to CAS sequences only.`
+            );
+          }
           const eng = this.deferred();
           return {
             next: async (nextOpts) => {
@@ -15312,7 +15726,17 @@ var init_vault = __esm({
             actor: this.keyring.userId
           });
         }
-        return this.sequenceStore.handle(resolveSequenceKey(series, opts));
+        const handle = this.sequenceStore.handle(resolveSequenceKey(series, opts));
+        if (opts?.format === void 0) return handle;
+        const render = compileSequenceFormat(opts.format, series, opts.partition);
+        return {
+          next: async (nextOpts) => {
+            const serial = await handle.next(nextOpts);
+            return { serial, formatted: render(serial) };
+          },
+          peek: () => handle.peek(),
+          seedTo: (n) => handle.seedTo(n)
+        };
       }
       /** @internal — lazily build the deferred-numbering engine with a cache-coherent stamp. */
       deferred() {
@@ -15539,6 +15963,43 @@ var init_vault = __esm({
           if (descriptor.mode !== "strict") continue;
           const rawId = obj[field];
           if (rawId === null || rawId === void 0) continue;
+          if (isRefArray(descriptor)) {
+            if (!Array.isArray(rawId)) {
+              throw new RefIntegrityError({
+                collection: collectionName,
+                id: obj["id"] ?? "<unknown>",
+                field,
+                refTo: descriptor.target,
+                refId: null,
+                message: `Array ref field "${collectionName}.${field}" must be an array, got ${typeof rawId}.`
+              });
+            }
+            const arrTarget = this.collection(descriptor.target);
+            for (const el of rawId) {
+              if (typeof el !== "string" && typeof el !== "number") {
+                throw new RefIntegrityError({
+                  collection: collectionName,
+                  id: obj["id"] ?? "<unknown>",
+                  field,
+                  refTo: descriptor.target,
+                  refId: null,
+                  message: `Array ref "${collectionName}.${field}" elements must be strings or numbers, got ${typeof el}.`
+                });
+              }
+              const elId = String(el);
+              if (!await arrTarget.get(elId)) {
+                throw new RefIntegrityError({
+                  collection: collectionName,
+                  id: obj["id"] ?? "<unknown>",
+                  field,
+                  refTo: descriptor.target,
+                  refId: elId,
+                  message: `Strict array ref "${collectionName}.${field}" \u2192 "${descriptor.target}" cannot be satisfied: element id "${elId}" not found in "${descriptor.target}".`
+                });
+              }
+            }
+            continue;
+          }
           if (typeof rawId !== "string" && typeof rawId !== "number") {
             throw new RefIntegrityError({
               collection: collectionName,
@@ -15588,6 +16049,11 @@ var init_vault = __esm({
             const allRecords = await fromCollection.list();
             const matches = allRecords.filter((rec) => {
               const raw = rec[rule.field];
+              if (rule.isArray) {
+                return Array.isArray(raw) && raw.some(
+                  (el) => (typeof el === "string" || typeof el === "number") && String(el) === id
+                );
+              }
               if (typeof raw !== "string" && typeof raw !== "number") return false;
               return String(raw) === id;
             });
@@ -15626,10 +16092,45 @@ var init_vault = __esm({
               }
             }
           }
+          await this.enforceLinksOnDelete(collectionName, id);
         } finally {
           this.cascadeInProgress.delete(key);
         }
       }
+      /**
+       * @internal — apply link `onDelete` policy when an endpoint record is
+       * deleted (#377-B). `'strict'` throws (blocks the delete), `'cascade'`
+       * removes the touching link rows (tx-atomic when a transaction is active),
+       * `'warn'` leaves orphans for `checkIntegrity()`.
+       */
+      async enforceLinksOnDelete(collectionName, id) {
+        for (const [name, spec] of this.linkRegistry) {
+          if (spec.a !== collectionName && spec.b !== collectionName) continue;
+          const handle = this.links(name);
+          const touching = await handle._rowsTouchingEndpoint(collectionName, id);
+          if (touching.length === 0) continue;
+          const mode = spec.onDelete ?? "cascade";
+          if (mode === "warn") continue;
+          if (mode === "strict") {
+            throw new LinkIntegrityError(name, collectionName, id, touching.length);
+          }
+          const linkColl = handle._collectionName;
+          const txCtx = this.noydb._activeTxContextOrNull;
+          for (const row of touching) {
+            const rowKey = linkRowKey(row.a, row.b);
+            if (txCtx !== null) {
+              const prior = await this.adapter.get(this.name, linkColl, rowKey);
+              if (prior !== null) {
+                txCtx._executed.push({
+                  op: { type: "delete", vaultName: this.name, collectionName: linkColl, id: rowKey },
+                  priorEnvelope: prior
+                });
+              }
+            }
+            await handle.disconnect(row.a, row.b);
+          }
+        }
+      }
       // ─── Join resolver) ────────────────────
       /**
        * Look up the `RefDescriptor` the left collection declared for a
@@ -15690,6 +16191,23 @@ var init_vault = __esm({
             for (const [field, descriptor] of Object.entries(refs)) {
               const rawId = record[field];
               if (rawId === null || rawId === void 0) continue;
+              const target = this.collection(descriptor.target);
+              if (isRefArray(descriptor)) {
+                if (!Array.isArray(rawId)) {
+                  violations.push({ collection: collectionName, id: recId, field, refTo: descriptor.target, refId: rawId, mode: descriptor.mode });
+                  continue;
+                }
+                for (const el of rawId) {
+                  if (typeof el !== "string" && typeof el !== "number") {
+                    violations.push({ collection: collectionName, id: recId, field, refTo: descriptor.target, refId: el, mode: descriptor.mode });
+                    continue;
+                  }
+                  if (!await target.get(String(el))) {
+                    violations.push({ collection: collectionName, id: recId, field, refTo: descriptor.target, refId: el, mode: descriptor.mode });
+                  }
+                }
+                continue;
+              }
               if (typeof rawId !== "string" && typeof rawId !== "number") {
                 violations.push({
                   collection: collectionName,
@@ -15702,7 +16220,6 @@ var init_vault = __esm({
                 continue;
               }
               const refId = String(rawId);
-              const target = this.collection(descriptor.target);
               const exists = await target.get(refId);
               if (!exists) {
                 violations.push({
@@ -15717,6 +16234,19 @@ var init_vault = __esm({
             }
           }
         }
+        for (const [name, spec] of this.linkRegistry) {
+          const linkColl = linkCollectionName(name);
+          const rows = await this.links(name).list();
+          for (const row of rows) {
+            const rowKey = linkRowKey(row.a, row.b);
+            if (await this.collection(spec.a).get(row.a) === null) {
+              violations.push({ collection: linkColl, id: rowKey, field: "a", refTo: spec.a, refId: row.a, mode: spec.onDelete ?? "cascade" });
+            }
+            if (await this.collection(spec.b).get(row.b) === null) {
+              violations.push({ collection: linkColl, id: rowKey, field: "b", refTo: spec.b, refId: row.b, mode: spec.onDelete ?? "cascade" });
+            }
+          }
+        }
         return { violations };
       }
       /**
@@ -15992,7 +16522,7 @@ var init_vault = __esm({
         const registry = new GuardRegistry2();
         for (const h of handles) registry.register(h.spec);
         this.guardRegistry = registry;
-        this.readOnlyFacade = new ReadOnlyVaultFacade2(this);
+        this.guardFacade = new ReadOnlyVaultFacade2(this, "guard");
       }
       /**
        * @internal — The gate handler in Noydb.#registerGuardGate calls into
@@ -16023,8 +16553,8 @@ var init_vault = __esm({
         }
         registry.validate();
         this.derivationRegistry = registry;
-        if (this.readOnlyFacade === null) {
-          this.readOnlyFacade = new ReadOnlyVaultFacade2(this);
+        if (this.derivationFacade === null) {
+          this.derivationFacade = new ReadOnlyVaultFacade2(this, "derivation");
         }
       }
       /**
@@ -16141,7 +16671,7 @@ var init_vault = __esm({
         const { DerivationExecutor: DerivationExecutor2 } = await Promise.resolve().then(() => (init_executor(), executor_exports));
         const sourceColl = this.collection(sourceCollection);
         const records = await sourceColl.list();
-        const ctx = { vault: this.readOnlyFacade ?? new (await Promise.resolve().then(() => (init_read_only_facade(), read_only_facade_exports))).ReadOnlyVaultFacade(this) };
+        const ctx = { vault: this.derivationFacade ?? new (await Promise.resolve().then(() => (init_read_only_facade(), read_only_facade_exports))).ReadOnlyVaultFacade(this, "derivation") };
         let derived = 0;
         let failed = 0;
         for (const record of records) {
@@ -16206,17 +16736,18 @@ var init_vault = __esm({
        * never see null).
        */
       _getReadOnlyFacade() {
-        return this.readOnlyFacade;
+        return this.guardFacade;
       }
       /**
-       * Internal lazy-allocator for the read-only facade. Used as a
-       * defensive fallback; in practice `_initGuards()` eagerly
-       * instantiates this, so the lazy path is a no-op.
+       * Internal lazy-allocator for the derivation read-only facade
+       * (`layer:'derivation'`). Used as a defensive fallback; in practice
+       * `_initDerivations()` eagerly instantiates this, so the lazy path is
+       * a no-op.
        */
       _ensureReadOnlyFacade() {
-        if (this.readOnlyFacade !== null) return this.readOnlyFacade;
+        if (this.derivationFacade !== null) return this.derivationFacade;
         throw new Error(
-          "Vault: guard hook fired before _initGuards() completed. This typically means the vault was opened via the sync fallback path (Noydb.vault(name)) without first calling await db.openVault(name). See issue #132."
+          "Vault: derivation hook fired before _initDerivations() completed. This typically means the vault was opened via the sync fallback path (Noydb.vault(name)) without first calling await db.openVault(name). See issue #132."
         );
       }
       /**
@@ -18615,17 +19146,188 @@ var init_executor3 = __esm({
   }
 });
 
-// src/federation/classify-skip.ts
-function classifyShardSkip(err) {
-  return err instanceof NoAccessError ? "no-grant" : "error";
-}
-var init_classify_skip = __esm({
-  "src/federation/classify-skip.ts"() {
-    "use strict";
-    init_errors();
-  }
-});
-
+// src/federation/schema-manifest.ts
+function captureBlueprint(configure) {
+  const recorded = [];
+  const collectionStub = new Proxy(
+    {},
+    {
+      get: () => () => collectionStub
+    }
+  );
+  const proxy = new Proxy(
+    {},
+    {
+      get: (_t, prop) => {
+        if (prop === "collection") {
+          return (name, opts) => {
+            recorded.push({
+              name,
+              indexes: opts?.indexes ?? [],
+              persistJsonSchema: !!opts?.persistJsonSchema
+            });
+            return collectionStub;
+          };
+        }
+        return () => proxy;
+      }
+    }
+  );
+  configure(proxy);
+  const sorted = [...recorded].sort((a, b) => a.name.localeCompare(b.name));
+  const indexes = {};
+  const persistJsonSchema = [];
+  for (const c of sorted) {
+    indexes[c.name] = c.indexes;
+    if (c.persistJsonSchema) persistJsonSchema.push(c.name);
+  }
+  return {
+    // `persistJsonSchema` is already name-sorted: it is populated while
+    // iterating `sorted` (collections in name order).
+    collections: sorted.map((c) => c.name),
+    indexes,
+    persistJsonSchema
+  };
+}
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(",")}}`;
+}
+async function fingerprintBlueprint(bp) {
+  return sha256Hex2(new TextEncoder().encode(canonical(bp)));
+}
+var init_schema_manifest = __esm({
+  "src/federation/schema-manifest.ts"() {
+    "use strict";
+    init_crypto();
+  }
+});
+
+// src/federation/state-vault.ts
+var state_vault_exports = {};
+__export(state_vault_exports, {
+  STATE_VAULT_NAME: () => STATE_VAULT_NAME,
+  StateManagementVault: () => StateManagementVault
+});
+var REGISTRY, MANIFEST, EVENTS, MIGRATION_STATUS, StateManagementVault;
+var init_state_vault = __esm({
+  "src/federation/state-vault.ts"() {
+    "use strict";
+    init_schema_manifest();
+    init_constants2();
+    init_ulid();
+    init_constants2();
+    REGISTRY = "vaultRegistry";
+    MANIFEST = "schemaManifest";
+    EVENTS = "deploymentEvents";
+    MIGRATION_STATUS = "migrationStatus";
+    StateManagementVault = class _StateManagementVault {
+      constructor(registry, schemaManifest, events, migrationStatus) {
+        this.registry = registry;
+        this.schemaManifest = schemaManifest;
+        this.#events = events;
+        this.#migrationStatus = migrationStatus;
+      }
+      registry;
+      schemaManifest;
+      /**
+       * The append-only deployment-events log is kept truly private so the raw
+       * mutable Collection is never surfaced — events may only be written via
+       * `appendEvent` and read via `queryEvents`. (`registry` and
+       * `schemaManifest` are deliberately public: consumers read and write them.)
+       */
+      #events;
+      /** Per-shard fleet-migration progress (#271). Surfaced via typed methods only. */
+      #migrationStatus;
+      /** Idempotently open the reserved state vault and bind the control-plane collections. */
+      static async open(db) {
+        const vault = await db.openVault(STATE_VAULT_NAME);
+        return new _StateManagementVault(
+          vault.collection(REGISTRY),
+          vault.collection(MANIFEST),
+          vault.collection(EVENTS),
+          vault.collection(MIGRATION_STATUS)
+        );
+      }
+      /** Read one shard's migration status (or null). */
+      async getMigrationStatus(vaultId) {
+        return this.#migrationStatus.get(vaultId);
+      }
+      /** All migration-status rows (hydrates first). */
+      async listMigrationStatus() {
+        await this.#migrationStatus.list();
+        return this.#migrationStatus.query().toArray();
+      }
+      /** Upsert one shard's migration status (keyed by vaultId). */
+      async upsertMigrationStatus(row) {
+        await this.#migrationStatus.put(row.vaultId, row);
+      }
+      /** Read-only query over the append-only deployment-events log. */
+      queryEvents() {
+        return this.#events.query();
+      }
+      /**
+       * Append a deployment event with a fresh unique (ULID) id. This is the
+       * only write path to the events log; no update/delete is exposed.
+       * Callers should treat failures as non-fatal — this method does not
+       * swallow errors, so wrap the call site in try/catch where appropriate.
+       */
+      async appendEvent(event) {
+        const ts = event.ts ?? Date.now();
+        const id = generateULID();
+        await this.#events.put(id, { ...event, id, ts });
+      }
+      /**
+       * Ensure a manifest row exists for `(templateName, template.version)`.
+       * Safe to call repeatedly: the `fingerprint` is a deterministic hash of
+       * the template's declared shape (stable across calls), though each call
+       * refreshes `recordedAt`.
+       */
+      async recordManifest(templateName, template) {
+        const bp = captureBlueprint(template.configure);
+        const fingerprint = await fingerprintBlueprint(bp);
+        await this.schemaManifest.put(`${templateName}:${template.version}`, {
+          templateName,
+          version: template.version,
+          collections: bp.collections,
+          indexes: bp.indexes,
+          persistJsonSchema: bp.persistJsonSchema,
+          fingerprint,
+          recordedAt: Date.now()
+        });
+        return fingerprint;
+      }
+      /**
+       * True when `template`'s current declared shape does not match the recorded
+       * manifest for `(templateName, template.version)`. Because shards carry no
+       * schema state independent of their template, this catches "a template's
+       * shape changed without bumping `version`" — not independent per-shard drift.
+       * A missing manifest is treated as drift (nothing to verify against).
+       */
+      async detectDrift(templateName, template) {
+        const row = await this.schemaManifest.get(`${templateName}:${template.version}`);
+        if (!row) return true;
+        const current = await fingerprintBlueprint(captureBlueprint(template.configure));
+        return current !== row.fingerprint;
+      }
+    };
+  }
+});
+
+// src/federation/classify-skip.ts
+function classifyShardSkip(err) {
+  return err instanceof NoAccessError ? "no-grant" : "error";
+}
+var init_classify_skip = __esm({
+  "src/federation/classify-skip.ts"() {
+    "use strict";
+    init_errors();
+  }
+});
+
 // src/federation/cross-shard-join.ts
 function coerceKey(value) {
   if (value === null || value === void 0) return null;
@@ -18899,6 +19601,7 @@ var SHARD_SEPARATOR, SAFE_PARTITION_KEY, VaultGroup, ShardedCollection, ShardedQ
 var init_vault_group = __esm({
   "src/federation/vault-group.ts"() {
     "use strict";
+    init_state_vault();
     init_errors();
     init_constants2();
     init_classify_skip();
@@ -18908,12 +19611,13 @@ var init_vault_group = __esm({
     SHARD_SEPARATOR = "--";
     SAFE_PARTITION_KEY = /^[A-Za-z0-9._-]+$/;
     VaultGroup = class {
-      constructor(db, name, registry, sharding, template) {
+      constructor(db, name, registry, sharding, template, migrateOnOpen = false) {
         this.db = db;
         this.name = name;
         this.registry = registry;
         this.sharding = sharding;
         this.template = template;
+        this.migrateOnOpen = migrateOnOpen;
         if (name.includes(SHARD_SEPARATOR)) {
           throw new ValidationError(
             `VaultGroup name "${name}" must not contain "--" (reserved shard vault-id separator).`
@@ -18925,6 +19629,7 @@ var init_vault_group = __esm({
       registry;
       sharding;
       template;
+      migrateOnOpen;
       /** @internal — set when the group is managed (no explicit registry). */
       stateVault;
       /** @internal */
@@ -18958,8 +19663,22 @@ var init_vault_group = __esm({
         const rows = this.registry.query().toArray();
         return rows.filter((r) => r.group === this.name);
       }
-      /** Open an existing shard and apply the template. */
+      /**
+       * Open an existing shard and apply the template. When `migrateOnOpen` is set
+       * (#271) and the shard's registry version is behind the template, its cutover
+       * runs inline first — so a behind shard never surfaces a stale handle.
+       */
       async openShard(partitionKey) {
+        if (this.migrateOnOpen) {
+          const row = await this.registry.get(this.registryId(partitionKey));
+          if (row && row.schemaVersion < this.template.version) {
+            await this.migrateShard(partitionKey);
+          }
+        }
+        return this._openShardRaw(partitionKey);
+      }
+      /** @internal — open + configure with no migrate-on-open hook (used by the migration path itself to avoid recursion). */
+      async _openShardRaw(partitionKey) {
         const vault = await this.db.openVault(this.shardVaultId(partitionKey), { create: false });
         this.template.configure(vault);
         return vault;
@@ -19037,6 +19756,161 @@ var init_vault_group = __esm({
         });
         return { eligible, skipped };
       }
+      /** @internal — registered push-model cross-vault derivations (#271 Insight Vault). */
+      crossVaultDerivations = [];
+      /**
+       * Register a push-model cross-vault derivation — the Insight Vault pattern
+       * (#271, Layer 4). Drive it with {@link refreshInsights}.
+       *
+       * For each shard, `derive(records, ctx)` runs on that shard's `source`
+       * records and its return value is written into the analytics
+       * (`target.vault` / `target.collection`) vault, keyed by partition key —
+       * one summary row per shard. The derivation runs in-process under THIS
+       * group's `Noydb` (which already holds both the shard and Insight Vault
+       * keyrings); the shard's decrypted records are reduced to a summary that is
+       * re-encrypted under the Insight Vault's own DEK, so no shard ciphertext
+       * crosses a DEK boundary.
+       *
+       * **Zero-knowledge note:** the Insight Vault backend sees aggregated
+       * structure (totals, counts, timestamps) drawn from many shards — a weaker
+       * ZK profile than the per-shard vaults. Opt-in; keep summaries to aggregate
+       * scalars (no embeddings / no raw records).
+       *
+       * v1 is explicit-refresh (no write-path push); call `refreshInsights()`
+       * after a batch of writes, or on a schedule.
+       */
+      withCrossVaultDerivation(spec) {
+        this.crossVaultDerivations.push(spec);
+      }
+      /**
+       * Run every registered {@link withCrossVaultDerivation}: read each eligible
+       * shard's source records, derive a per-shard summary, and write it into the
+       * Insight Vault keyed by partition key. Shards behind `minVersion`,
+       * unprovisioned, or whose read errors are reported in `skippedVaults` and
+       * are not written (a stale summary is never left behind for a failed shard).
+       */
+      async refreshInsights(options = {}) {
+        if (this.crossVaultDerivations.length === 0) return { written: 0, skippedVaults: [] };
+        const { eligible, skipped } = await this.resolveEligible(
+          options.minVersion !== void 0 ? { minVersion: options.minVersion } : {}
+        );
+        let written = 0;
+        for (const spec of this.crossVaultDerivations) {
+          const results = await this.db.queryAcross(
+            eligible.map((r) => r.vaultId),
+            async (vault) => {
+              this.template.configure(vault);
+              return vault.collection(spec.source).list();
+            },
+            { create: false, ...options.concurrency !== void 0 ? { concurrency: options.concurrency } : {} }
+          );
+          const insight = await this.db.openVault(spec.target.vault);
+          const out = insight.collection(spec.target.collection);
+          for (let i = 0; i < eligible.length; i++) {
+            const row = eligible[i];
+            const res = results[i];
+            if (!res || res.result === void 0) {
+              skipped.push({ vaultId: row.vaultId, reason: "error", ...res?.error ? { error: res.error } : {} });
+              continue;
+            }
+            const ctx = {
+              vaultId: row.vaultId,
+              partitionKey: row.partitionKey,
+              schemaVersion: row.schemaVersion
+            };
+            const summary = spec.derive(res.result, ctx);
+            await out.put(row.partitionKey, summary);
+            written++;
+          }
+        }
+        return { written, skippedVaults: skipped };
+      }
+      /** @internal — the control-plane vault for migration status; lazily opened. */
+      async ensureStateVault() {
+        if (!this.stateVault) this.stateVault = await StateManagementVault.open(this.db);
+        return this.stateVault;
+      }
+      /**
+       * Migrate ONE shard to the template's current version (#271 fleet runner,
+       * per-shard step). Opens the shard (applying the template, which arms the
+       * M12 cutover), drains schema-write detection, runs `vault.runSchemaCutover()`
+       * (the per-vault drain-barrier-transform protocol), then advances the
+       * registry row's `schemaVersion` and records `migration-status`. A shard
+       * already at the template version is a no-op (`status: 'done'`, migrated 0).
+       * Never throws on a cutover failure — it records `status: 'failed'` and
+       * returns the row, so a fleet run continues past a bad shard.
+       */
+      async migrateShard(partitionKey) {
+        const vaultId = this.shardVaultId(partitionKey);
+        const row = await this.registry.get(this.registryId(partitionKey));
+        if (!row) throw new UnknownShardError(partitionKey, this.name);
+        const target = this.template.version;
+        const sv = await this.ensureStateVault();
+        const base = { vaultId, group: this.name, currentVersion: row.schemaVersion, targetVersion: target };
+        if (row.schemaVersion >= target) {
+          const done = { ...base, status: "done", migrated: 0, finishedAt: Date.now() };
+          await sv.upsertMigrationStatus(done);
+          return done;
+        }
+        await sv.upsertMigrationStatus({ ...base, status: "running", startedAt: Date.now() });
+        try {
+          await sv.appendEvent({ type: "migration-started", group: this.name, vaultId, version: target });
+        } catch {
+        }
+        try {
+          const vault = await this._openShardRaw(partitionKey);
+          await vault._drainPendingSchemaWrites();
+          const { migrated } = await vault.runSchemaCutover();
+          await this.registry.put(this.registryId(partitionKey), { ...row, schemaVersion: target });
+          const done = { ...base, currentVersion: target, status: "done", migrated, finishedAt: Date.now() };
+          await sv.upsertMigrationStatus(done);
+          try {
+            await sv.appendEvent({ type: "migration-completed", group: this.name, vaultId, version: target });
+          } catch {
+          }
+          return done;
+        } catch (err) {
+          const error = err instanceof Error ? err.message : String(err);
+          const failed = { ...base, status: "failed", error, finishedAt: Date.now() };
+          await sv.upsertMigrationStatus(failed);
+          try {
+            await sv.appendEvent({ type: "migration-failed", group: this.name, vaultId, version: target, detail: error });
+          } catch {
+          }
+          return failed;
+        }
+      }
+      /**
+       * Active batch runner (#271): migrate every shard behind the template version
+       * to it, in controlled batches. **Resumable + crash-safe** — shards already at
+       * the target are skipped (the registry version is the source of truth), so a
+       * re-run after a crash only picks up the unfinished + previously-failed shards.
+       *
+       * - `cohort` — restrict to these partition keys (the staged / canary rollout:
+       *   migrate a small cohort, verify the Insight Vault, then run the rest).
+       * - `batchSize` — max shards migrated concurrently per batch (back-pressure).
+       *   Default 4. Batches run sequentially; shards within a batch run in parallel.
+       */
+      async migrateFleet(options = {}) {
+        const target = this.template.version;
+        const rows = await this.allRows();
+        const cohort = options.cohort;
+        const todo = rows.filter(
+          (r) => r.schemaVersion < target && (cohort === void 0 || cohort.includes(r.partitionKey))
+        );
+        const batchSize = Math.max(1, options.batchSize ?? 4);
+        const migrated = [];
+        const failed = [];
+        for (let i = 0; i < todo.length; i += batchSize) {
+          const batch = todo.slice(i, i + batchSize);
+          const settled = await Promise.all(batch.map((r) => this.migrateShard(r.partitionKey)));
+          for (const res of settled) {
+            if (res.status === "done") migrated.push(res.vaultId);
+            else failed.push({ vaultId: res.vaultId, error: res.error ?? "unknown" });
+          }
+        }
+        return { target, migrated, failed };
+      }
     };
     ShardedCollection = class {
       constructor(group, collectionName) {
@@ -19244,159 +20118,6 @@ var init_vault_group = __esm({
   }
 });
 
-// src/federation/schema-manifest.ts
-function captureBlueprint(configure) {
-  const recorded = [];
-  const collectionStub = new Proxy(
-    {},
-    {
-      get: () => () => collectionStub
-    }
-  );
-  const proxy = new Proxy(
-    {},
-    {
-      get: (_t, prop) => {
-        if (prop === "collection") {
-          return (name, opts) => {
-            recorded.push({
-              name,
-              indexes: opts?.indexes ?? [],
-              persistJsonSchema: !!opts?.persistJsonSchema
-            });
-            return collectionStub;
-          };
-        }
-        return () => proxy;
-      }
-    }
-  );
-  configure(proxy);
-  const sorted = [...recorded].sort((a, b) => a.name.localeCompare(b.name));
-  const indexes = {};
-  const persistJsonSchema = [];
-  for (const c of sorted) {
-    indexes[c.name] = c.indexes;
-    if (c.persistJsonSchema) persistJsonSchema.push(c.name);
-  }
-  return {
-    // `persistJsonSchema` is already name-sorted: it is populated while
-    // iterating `sorted` (collections in name order).
-    collections: sorted.map((c) => c.name),
-    indexes,
-    persistJsonSchema
-  };
-}
-function canonical(value) {
-  if (value === null || typeof value !== "object") return JSON.stringify(value);
-  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
-  const obj = value;
-  const keys = Object.keys(obj).sort();
-  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(",")}}`;
-}
-async function fingerprintBlueprint(bp) {
-  return sha256Hex2(new TextEncoder().encode(canonical(bp)));
-}
-var init_schema_manifest = __esm({
-  "src/federation/schema-manifest.ts"() {
-    "use strict";
-    init_crypto();
-  }
-});
-
-// src/federation/state-vault.ts
-var state_vault_exports = {};
-__export(state_vault_exports, {
-  STATE_VAULT_NAME: () => STATE_VAULT_NAME,
-  StateManagementVault: () => StateManagementVault
-});
-var REGISTRY, MANIFEST, EVENTS, StateManagementVault;
-var init_state_vault = __esm({
-  "src/federation/state-vault.ts"() {
-    "use strict";
-    init_schema_manifest();
-    init_constants2();
-    init_ulid();
-    init_constants2();
-    REGISTRY = "vaultRegistry";
-    MANIFEST = "schemaManifest";
-    EVENTS = "deploymentEvents";
-    StateManagementVault = class _StateManagementVault {
-      constructor(registry, schemaManifest, events) {
-        this.registry = registry;
-        this.schemaManifest = schemaManifest;
-        this.#events = events;
-      }
-      registry;
-      schemaManifest;
-      /**
-       * The append-only deployment-events log is kept truly private so the raw
-       * mutable Collection is never surfaced — events may only be written via
-       * `appendEvent` and read via `queryEvents`. (`registry` and
-       * `schemaManifest` are deliberately public: consumers read and write them.)
-       */
-      #events;
-      /** Idempotently open the reserved state vault and bind the three control-plane collections. */
-      static async open(db) {
-        const vault = await db.openVault(STATE_VAULT_NAME);
-        return new _StateManagementVault(
-          vault.collection(REGISTRY),
-          vault.collection(MANIFEST),
-          vault.collection(EVENTS)
-        );
-      }
-      /** Read-only query over the append-only deployment-events log. */
-      queryEvents() {
-        return this.#events.query();
-      }
-      /**
-       * Append a deployment event with a fresh unique (ULID) id. This is the
-       * only write path to the events log; no update/delete is exposed.
-       * Callers should treat failures as non-fatal — this method does not
-       * swallow errors, so wrap the call site in try/catch where appropriate.
-       */
-      async appendEvent(event) {
-        const ts = event.ts ?? Date.now();
-        const id = generateULID();
-        await this.#events.put(id, { ...event, id, ts });
-      }
-      /**
-       * Ensure a manifest row exists for `(templateName, template.version)`.
-       * Safe to call repeatedly: the `fingerprint` is a deterministic hash of
-       * the template's declared shape (stable across calls), though each call
-       * refreshes `recordedAt`.
-       */
-      async recordManifest(templateName, template) {
-        const bp = captureBlueprint(template.configure);
-        const fingerprint = await fingerprintBlueprint(bp);
-        await this.schemaManifest.put(`${templateName}:${template.version}`, {
-          templateName,
-          version: template.version,
-          collections: bp.collections,
-          indexes: bp.indexes,
-          persistJsonSchema: bp.persistJsonSchema,
-          fingerprint,
-          recordedAt: Date.now()
-        });
-        return fingerprint;
-      }
-      /**
-       * True when `template`'s current declared shape does not match the recorded
-       * manifest for `(templateName, template.version)`. Because shards carry no
-       * schema state independent of their template, this catches "a template's
-       * shape changed without bumping `version`" — not independent per-shard drift.
-       * A missing manifest is treated as drift (nothing to verify against).
-       */
-      async detectDrift(templateName, template) {
-        const row = await this.schemaManifest.get(`${templateName}:${template.version}`);
-        if (!row) return true;
-        const current = await fingerprintBlueprint(captureBlueprint(template.configure));
-        return current !== row.fingerprint;
-      }
-    };
-  }
-});
-
 // src/noydb.ts
 var noydb_exports = {};
 __export(noydb_exports, {
@@ -20266,7 +20987,7 @@ var init_noydb = __esm({
         const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
         const stateVault = opts.registry ? void 0 : await StateManagementVault2.open(this);
         const registry = opts.registry ?? stateVault.registry;
-        const group = new VaultGroup2(this, name, registry, opts.sharding, template);
+        const group = new VaultGroup2(this, name, registry, opts.sharding, template, opts.migrateOnOpen ?? false);
         if (stateVault) {
           group._attachStateVault(stateVault);
           await stateVault.recordManifest(opts.sharding.vaultTemplate, template);