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

package/dist/index.cjs

@@ -46,7 +46,7 @@ var init_types = __esm({
 });
 
 // src/errors.ts
-var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, ReadOnlyAtInstantError, ReadOnlyFrameError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, PeriodClosedError, RecordLockedError, FieldFrozenError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, ScriptViolationError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, SnapshotNotFoundError, UnknownShardError, ShardProvisioningError, CrossShardJoinError, VaultTemplateNotFoundError, ForgetStrategyNotConfiguredError, SealedRecordExpiredError, SealedRecordMismatchError, RecordCekNotFoundError;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, ReadOnlyAtInstantError, ReadOnlyFrameError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, PeriodClosedError, RecordLockedError, FieldFrozenError, IllegalTransitionError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, ScriptViolationError, StaticDictReadonlyError, UnknownDictCodeError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, AttestationError, SessionExpiredError, SessionNotFoundError, SessionPolicyError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, FilenameSanitizationError, PathEscapeError, DerivationCycleError, DerivationDepthError, DerivationOutputUnknownError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, MaterializedViewConfigError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, SnapshotNotFoundError, UnknownShardError, ShardProvisioningError, CrossShardJoinError, VaultTemplateNotFoundError, ForgetStrategyNotConfiguredError, SealedRecordExpiredError, SealedRecordMismatchError, RecordCekNotFoundError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -245,6 +245,23 @@ var init_errors = __esm({
         this.fields = fields;
       }
     };
+    IllegalTransitionError = class extends NoydbError {
+      collection;
+      id;
+      from;
+      to;
+      constructor(collection, id, from, to) {
+        super(
+          "ILLEGAL_TRANSITION",
+          `Cannot transition ${collection}/${id} from "${from}" to "${to}" \u2014 not a declared arc. Use withTransactions({ amendment: true, reason }) with admin/owner role to override.`
+        );
+        this.name = "IllegalTransitionError";
+        this.collection = collection;
+        this.id = id;
+        this.from = from;
+        this.to = to;
+      }
+    };
     InvariantError = class extends NoydbError {
       constructor(message) {
         super("INVARIANT_VIOLATED", message);
@@ -496,14 +513,14 @@ var init_errors = __esm({
       recordId;
       fields;
       conflictingId;
-      constructor(collection, recordId3, fields, conflictingId) {
+      constructor(collection, recordId4, fields, conflictingId) {
         super(
           "UNIQUE_CONSTRAINT",
-          `Unique constraint on ${collection}.[${fields.join(", ")}] violated: record "${recordId3}" duplicates a value already held by "${conflictingId}".`
+          `Unique constraint on ${collection}.[${fields.join(", ")}] violated: record "${recordId4}" duplicates a value already held by "${conflictingId}".`
         );
         this.name = "UniqueConstraintError";
         this.collection = collection;
-        this.recordId = recordId3;
+        this.recordId = recordId4;
         this.fields = fields;
         this.conflictingId = conflictingId;
       }
@@ -4637,14 +4654,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()
         };
       }
@@ -4700,6 +4720,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;
@@ -4753,6 +4783,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);
               }
             }
@@ -4929,6 +4962,177 @@ var init_delegation = __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 sha256Hex(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_constants();
+    init_ulid();
+    init_constants();
+    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";
@@ -5213,6 +5417,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_constants();
     init_classify_skip();
@@ -5222,12 +5427,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).`
@@ -5239,6 +5445,7 @@ var init_vault_group = __esm({
       registry;
       sharding;
       template;
+      migrateOnOpen;
       /** @internal — set when the group is managed (no explicit registry). */
       stateVault;
       /** @internal */
@@ -5272,8 +5479,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;
@@ -5351,6 +5572,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) {
@@ -5558,159 +5934,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 sha256Hex(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_constants();
-    init_ulid();
-    init_constants();
-    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/index.ts
 var src_exports = {};
 __export(src_exports, {
@@ -5773,6 +5996,7 @@ __export(src_exports, {
   GroupedQuery: () => GroupedQuery,
   GroupedQueryN: () => GroupedQueryN,
   INDEXED_STORE_POLICY: () => INDEXED_STORE_POLICY,
+  IllegalTransitionError: () => IllegalTransitionError,
   ImportCapabilityError: () => ImportCapabilityError,
   IndexRequiredError: () => IndexRequiredError,
   IndexWriteFailureError: () => IndexWriteFailureError,
@@ -5785,6 +6009,8 @@ __export(src_exports, {
   LEDGER_DELTAS_COLLECTION: () => LEDGER_DELTAS_COLLECTION,
   LedgerContentionError: () => LedgerContentionError,
   LedgerStore: () => LedgerStore,
+  LinkEndpointError: () => LinkEndpointError,
+  LinkIntegrityError: () => LinkIntegrityError,
   LocaleNotSpecifiedError: () => LocaleNotSpecifiedError,
   Lru: () => Lru,
   MAGIC_LINK_CONTENT_INFO_PREFIX: () => MAGIC_LINK_CONTENT_INFO_PREFIX,
@@ -5916,6 +6142,7 @@ __export(src_exports, {
   canonicalJson: () => canonicalJson,
   checkGate: () => checkGate,
   clearDevUnlock: () => clearDevUnlock,
+  compileSequenceFormat: () => compileSequenceFormat,
   computePatch: () => computePatch,
   coordinatedCutover: () => coordinatedCutover,
   count: () => count,
@@ -5978,11 +6205,13 @@ __export(src_exports, {
   isDictKeyDescriptor: () => isDictKeyDescriptor,
   isDiscriminant: () => isDiscriminant,
   isI18nTextDescriptor: () => isI18nTextDescriptor,
+  isLinkCollectionName: () => isLinkCollectionName,
   isMagicLinkGrantExpired: () => isMagicLinkGrantExpired,
   isMoneyDescriptor: () => isMoneyDescriptor,
   isMoneyString: () => isMoneyString,
   isPreCompressed: () => isPreCompressed,
   isPublicEnvelope: () => isPublicEnvelope,
+  isRefArray: () => isRefArray,
   isSessionAlive: () => isSessionAlive,
   isStaticDictDescriptor: () => isStaticDictDescriptor,
   isULID: () => isULID,
@@ -6036,6 +6265,7 @@ __export(src_exports, {
   recoverUser: () => recoverUser,
   reduceRecords: () => reduceRecords,
   ref: () => ref,
+  refArray: () => refArray,
   removeAuthenticator: () => removeAuthenticator,
   resetBrotliSupportCache: () => resetBrotliSupportCache,
   resetJoinWarnings: () => resetJoinWarnings,
@@ -6063,6 +6293,7 @@ __export(src_exports, {
   sha256Hex: () => sha256Hex3,
   staticDict: () => staticDict,
   sum: () => sum,
+  transitionGuard: () => transitionGuard,
   unwrapDeksFromBlob: () => unwrapDeksFromBlob,
   unwrapDeksFromPaperEntry: () => unwrapDeksFromPaperEntry,
   unwrapDeksFromShamirEntry: () => unwrapDeksFromShamirEntry,
@@ -6086,6 +6317,7 @@ __export(src_exports, {
   withMetrics: () => withMetrics,
   withOverlayedView: () => withOverlayedView,
   withRetry: () => withRetry,
+  withRollup: () => withRollup,
   wrapBundleStore: () => wrapBundleStore,
   wrapStore: () => wrapStore,
   writeMagicLinkGrant: () => writeMagicLinkGrant,
@@ -8454,6 +8686,38 @@ init_crypto();
 init_errors();
 var SEQUENCE_COLLECTION = "_sequences";
 var MAX_NEXT_ATTEMPTS = 16;
+var SEQ_FORMAT_TOKEN = /\{([^{}]*)\}/g;
+var SEQ_PAD_TOKEN = /^seq:0(\d+)$/;
+var SEQ_PARTITION_TOKEN = /^partition\.(\d+)$/;
+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;
@@ -9476,15 +9740,15 @@ function isEquivalent(a, b) {
 
 // src/history/history.ts
 var HISTORY_COLLECTION = "_history";
-function matchesPrefix(id, collection, recordId3) {
-  if (recordId3) {
-    return id.startsWith(`${collection}:${recordId3}:`);
+function matchesPrefix(id, collection, recordId4) {
+  if (recordId4) {
+    return id.startsWith(`${collection}:${recordId4}:`);
   }
   return id.startsWith(`${collection}:`);
 }
-async function getHistory(adapter, vault, collection, recordId3, options) {
+async function getHistory(adapter, vault, collection, recordId4, options) {
   const allIds = await adapter.list(vault, HISTORY_COLLECTION);
-  const matchingIds = allIds.filter((id) => matchesPrefix(id, collection, recordId3)).sort().reverse();
+  const matchingIds = allIds.filter((id) => matchesPrefix(id, collection, recordId4)).sort().reverse();
   const entries = [];
   for (const id of matchingIds) {
     const envelope = await adapter.get(vault, HISTORY_COLLECTION, id);
@@ -9737,6 +10001,9 @@ init_ledger();
 
 // src/refs.ts
 init_errors();
+function isRefArray(desc) {
+  return desc.isArray === true;
+}
 var RefIntegrityError = class extends NoydbError {
   collection;
   id;
@@ -9773,6 +10040,17 @@ function ref(target, mode = "strict") {
   }
   return { target, mode };
 }
+function refArray(target, mode = "strict") {
+  if (target.includes("/")) {
+    throw new RefScopeError(target);
+  }
+  if (!target || target.startsWith("_")) {
+    throw new Error(
+      `refArray(): target collection name must be non-empty and cannot start with '_' (reserved for internal collections). Got "${target}".`
+    );
+  }
+  return { target, mode, isArray: true };
+}
 var RefRegistry = class {
   outbound = /* @__PURE__ */ new Map();
   inbound = /* @__PURE__ */ new Map();
@@ -9797,7 +10075,7 @@ var RefRegistry = class {
       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}"`
           );
@@ -9808,31 +10086,169 @@ var RefRegistry = class {
     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);
     }
   }
-  /** Get the outbound refs declared by a collection (or `{}` if none). */
-  getOutbound(collection) {
-    return this.outbound.get(collection) ?? {};
+  /** Get the outbound refs declared by a collection (or `{}` if none). */
+  getOutbound(collection) {
+    return this.outbound.get(collection) ?? {};
+  }
+  /** Get the inbound refs that target a given collection (or `[]`). */
+  getInbound(target) {
+    return this.inbound.get(target) ?? [];
+  }
+  /**
+   * Iterate every (collection → refs) pair that has at least one
+   * declared reference. Used by `checkIntegrity` to walk the full
+   * universe of outbound refs without needing to track collection
+   * names elsewhere.
+   */
+  entries() {
+    return [...this.outbound.entries()];
+  }
+  /** Clear the registry. Test-only escape hatch; never called from production code. */
+  clear() {
+    this.outbound.clear();
+    this.inbound.clear();
+  }
+};
+
+// src/links/link-set.ts
+init_types();
+init_crypto();
+init_errors();
+var LINK_COLLECTION_PREFIX = "_links_";
+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 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
+    );
   }
-  /** Get the inbound refs that target a given collection (or `[]`). */
-  getInbound(target) {
-    return this.inbound.get(target) ?? [];
+  /** @internal — the storage collection name (for tx pre-image capture). */
+  get _collectionName() {
+    return this.collName;
   }
-  /**
-   * Iterate every (collection → refs) pair that has at least one
-   * declared reference. Used by `checkIntegrity` to walk the full
-   * universe of outbound refs without needing to track collection
-   * names elsewhere.
-   */
-  entries() {
-    return [...this.outbound.entries()];
+};
+var 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;
   }
-  /** Clear the registry. Test-only escape hatch; never called from production code. */
-  clear() {
-    this.outbound.clear();
-    this.inbound.clear();
+};
+var LinkIntegrityError = class extends NoydbError {
+  link;
+  endpoint;
+  id;
+  count;
+  constructor(link, endpoint, id, count2) {
+    super(
+      "LINK_INTEGRITY",
+      `Cannot delete "${endpoint}"/"${id}": ${count2} link(s) in "${link}" still reference it (onDelete: 'strict').`
+    );
+    this.name = "LinkIntegrityError";
+    this.link = link;
+    this.endpoint = endpoint;
+    this.id = id;
+    this.count = count2;
   }
 };
 
@@ -12840,6 +13256,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;
@@ -13923,7 +14354,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);
@@ -14080,17 +14511,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(".")) {
@@ -14879,8 +15318,8 @@ function coerceRefKey2(value) {
 
 // src/indexing/persisted-indexes.ts
 var IDX_PREFIX = "_idx/";
-function encodeIdxId(field, recordId3) {
-  return `${IDX_PREFIX}${field}/${recordId3}`;
+function encodeIdxId(field, recordId4) {
+  return `${IDX_PREFIX}${field}/${recordId4}`;
 }
 function decodeIdxId(id) {
   if (!id.startsWith(IDX_PREFIX)) return null;
@@ -14888,9 +15327,9 @@ function decodeIdxId(id) {
   const firstSlash = rest.indexOf("/");
   if (firstSlash <= 0) return null;
   const field = rest.slice(0, firstSlash);
-  const recordId3 = rest.slice(firstSlash + 1);
-  if (recordId3.length === 0) return null;
-  return { field, recordId: recordId3 };
+  const recordId4 = rest.slice(firstSlash + 1);
+  if (recordId4.length === 0) return null;
+  return { field, recordId: recordId4 };
 }
 
 // src/indexing/lazy-builder.ts
@@ -15780,6 +16219,15 @@ async function resolveStaleOnRead(accessor, outputCollection, id) {
 }
 
 // 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;
+  }
+}
 var fallbackWarned = /* @__PURE__ */ new Set();
 function warnOnceFallback(adapterName) {
   if (fallbackWarned.has(adapterName)) return;
@@ -16714,6 +17162,111 @@ var Collection = class {
    * 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);
@@ -16724,29 +17277,60 @@ var Collection = class {
     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_executor2(), executor_exports2)));
-        }
-        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_executor2(), executor_exports2)));
+      }
+      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];
@@ -16759,7 +17343,7 @@ var Collection = class {
               this.adapter,
               this.vault,
               spec.source,
-              id,
+              run.runId,
               key
             );
             const prevKeys = new Set(prior?.keys ?? []);
@@ -16786,7 +17370,7 @@ var Collection = class {
             }
             await saveFanoutSidecar2(this.adapter, this.vault, {
               source: spec.source,
-              sourceId: id,
+              sourceId: run.runId,
               outputKey: key,
               outputCollection: outSpec.collection,
               keys: newKeysList
@@ -16794,25 +17378,44 @@ var Collection = class {
             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);
       }
     }
   }
@@ -17029,6 +17632,7 @@ var Collection = class {
     if (!internal) {
       await this.dispatchMaterializedViewsOnDelete(id);
       await this.dispatchArrayDerivationsOnDelete(id);
+      if (existing) await this.dispatchRollupsOnDelete(existing.record);
     }
   }
   /**
@@ -17883,12 +18487,12 @@ var Collection = class {
       }
     }
     persisted.clear();
-    for (const recordId3 of canonicalIds) {
-      const envelope = await this.adapter.get(this.vault, this.name, recordId3);
+    for (const recordId4 of canonicalIds) {
+      const envelope = await this.adapter.get(this.vault, this.name, recordId4);
       if (!envelope) continue;
       const record = await this.decryptRecord(envelope, { skipValidation: true });
       if (record === null) continue;
-      await this.maintainPersistedIndexesOnPut(recordId3, record, null, envelope._v);
+      await this.maintainPersistedIndexesOnPut(recordId4, record, null, envelope._v);
     }
     this.persistedIndexesLoaded = true;
   }
@@ -18083,14 +18687,15 @@ var Collection = class {
       (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) => {
@@ -19124,8 +19729,8 @@ var DeferredNumberingStore = class {
     }
     await this.adapter.put(this.vault, collection, id, env, expectedVersion);
   }
-  pendingId(series, recordId3) {
-    return `${series}::${recordId3}`;
+  pendingId(series, recordId4) {
+    return `${series}::${recordId4}`;
   }
   /** Current last-assigned serial for a series (0 if none). */
   async peek(series) {
@@ -19139,16 +19744,16 @@ var DeferredNumberingStore = class {
    * at the next pass (the record's `field` is the durable source of truth —
    * `assigned` is an in-process convenience that a crash may drop).
    */
-  async enqueue(series, recordId3) {
+  async enqueue(series, recordId4) {
     const cfg = this.configs.get(series);
     if (!cfg) throw new NumberingUncertaintyError(series);
     if (typeof this.adapter.getStoreTime !== "function") throw new NumberingUncertaintyError(series);
     const st = await this.adapter.getStoreTime();
-    const id = this.pendingId(series, recordId3);
+    const id = this.pendingId(series, recordId4);
     const { env } = await this.readJson(NUMBERING_PENDING_COLLECTION, id);
     const entry = {
       series,
-      recordId: recordId3,
+      recordId: recordId4,
       collection: cfg.collection,
       field: cfg.field,
       storeEarliest: st.earliest,
@@ -19505,13 +20110,13 @@ async function runCompaction(ctx, options = {}) {
     collectionsWithPolicy += 1;
     byCollection[collectionName] = { records: 0, evicted: 0 };
     const ids = await ctx.listRecords(collectionName);
-    for (const recordId3 of ids) {
+    for (const recordId4 of ids) {
       if (evicted >= maxEvictions) break outer;
-      const record = await ctx.getRecord(collectionName, recordId3).catch(() => null);
+      const record = await ctx.getRecord(collectionName, recordId4).catch(() => null);
       if (record === null) continue;
       records += 1;
       byCollection[collectionName].records += 1;
-      const slots = await ctx.listSlots(collectionName, recordId3).catch(() => []);
+      const slots = await ctx.listSlots(collectionName, recordId4).catch(() => []);
       for (const slot of slots) {
         if (evicted >= maxEvictions) break outer;
         const policy = config[slot.name];
@@ -19523,11 +20128,11 @@ async function runCompaction(ctx, options = {}) {
           continue;
         }
         if (!dryRun) {
-          await ctx.deleteSlot(collectionName, recordId3, slot.name);
+          await ctx.deleteSlot(collectionName, recordId4, slot.name);
           await writeAuditEntry(ctx, {
-            id: generateEvictionId(collectionName, recordId3, slot.name),
+            id: generateEvictionId(collectionName, recordId4, slot.name),
             collection: collectionName,
-            recordId: recordId3,
+            recordId: recordId4,
             slotName: slot.name,
             blobHash: slot.eTag,
             reason,
@@ -19594,11 +20199,11 @@ function evaluatePolicy(policy, record, slot, now) {
   if (predicateTriggered) return "predicate";
   return null;
 }
-function generateEvictionId(collection, recordId3, slotName) {
+function generateEvictionId(collection, recordId4, slotName) {
   const rand = globalThis.crypto.getRandomValues(new Uint8Array(8));
   let suffix = "";
   for (const b of rand) suffix += b.toString(16).padStart(2, "0");
-  return `${collection}__${recordId3}__${slotName}__${suffix}`;
+  return `${collection}__${recordId4}__${slotName}__${suffix}`;
 }
 async function writeAuditEntry(ctx, entry) {
   const json = JSON.stringify(entry);
@@ -19649,7 +20254,7 @@ async function deriveMagicLinkContentKey(serverSecret, token, vault) {
     ["encrypt", "decrypt"]
   );
 }
-async function writeMagicLinkGrant(store, vault, grantor, contentKey, grantKek, recordId3, opts) {
+async function writeMagicLinkGrant(store, vault, grantor, contentKey, grantKek, recordId4, opts) {
   const collectionName = opts.collection ?? null;
   const sourceKey = collectionName ? dekKey(collectionName, opts.tier) : `__any#${opts.tier}`;
   const sourceDek = grantor.deks.get(sourceKey);
@@ -19662,7 +20267,7 @@ async function writeMagicLinkGrant(store, vault, grantor, contentKey, grantKek,
   const until = typeof opts.until === "string" ? opts.until : opts.until.toISOString();
   const createdAt = (/* @__PURE__ */ new Date()).toISOString();
   const payload = {
-    id: recordId3,
+    id: recordId4,
     toUser: opts.toUser,
     fromUser: grantor.userId,
     tier: opts.tier,
@@ -19682,11 +20287,11 @@ async function writeMagicLinkGrant(store, vault, grantor, contentKey, grantKek,
     _data: data,
     _by: grantor.userId
   };
-  await store.put(vault, MAGIC_LINK_GRANTS_COLLECTION, recordId3, envelope);
-  return { recordId: recordId3, payload };
+  await store.put(vault, MAGIC_LINK_GRANTS_COLLECTION, recordId4, envelope);
+  return { recordId: recordId4, payload };
 }
-async function readMagicLinkGrantRecord(store, vault, contentKey, recordId3) {
-  const env = await store.get(vault, MAGIC_LINK_GRANTS_COLLECTION, recordId3);
+async function readMagicLinkGrantRecord(store, vault, contentKey, recordId4) {
+  const env = await store.get(vault, MAGIC_LINK_GRANTS_COLLECTION, recordId4);
   if (!env) return null;
   try {
     const json = await decrypt(env._iv, env._data, contentKey);
@@ -20342,13 +20947,17 @@ var Vault = class {
    */
   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.
@@ -20510,6 +21119,10 @@ var Vault = class {
   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. */
@@ -20626,6 +21239,9 @@ var Vault = class {
     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);
@@ -20697,6 +21313,7 @@ var Vault = class {
         }));
         schemaUpdateGate = new SchemaUpdateGate(work);
       }
+      const effectiveHistoryConfig = options?.historyConfig ?? this.historyConfig;
       const collOpts = {
         adapter: this.adapter,
         vault: this.name,
@@ -20712,7 +21329,7 @@ var Vault = class {
         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.
@@ -20723,7 +21340,11 @@ var Vault = class {
         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,
@@ -21084,6 +21705,68 @@ var Vault = class {
     }
     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 }`
@@ -21243,65 +21926,16 @@ var Vault = class {
       });
     }
   }
-  /**
-   * 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) => {
@@ -21325,7 +21959,17 @@ var Vault = class {
         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() {
@@ -21340,11 +21984,11 @@ var Vault = class {
         // Stamp THROUGH the Collection layer so cache/indexes/MVs stay coherent —
         // `this.collection(name)` returns the shared cached instance, so a
         // subsequent user `collection.get(id)` sees the assigned serial.
-        stamp: async (collection, recordId3, field, serial) => {
+        stamp: async (collection, recordId4, field, serial) => {
           const coll = this.collection(collection);
-          const rec = await coll.get(recordId3);
+          const rec = await coll.get(recordId4);
           if (!rec) return false;
-          await coll.put(recordId3, { ...rec, [field]: serial });
+          await coll.put(recordId4, { ...rec, [field]: serial });
           return true;
         }
       });
@@ -21552,6 +22196,43 @@ var Vault = class {
       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,
@@ -21601,6 +22282,11 @@ var Vault = class {
         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;
         });
@@ -21639,10 +22325,45 @@ var Vault = class {
           }
         }
       }
+      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
@@ -21703,6 +22424,23 @@ var Vault = class {
         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,
@@ -21715,7 +22453,6 @@ var Vault = class {
             continue;
           }
           const refId = String(rawId);
-          const target = this.collection(descriptor.target);
           const exists = await target.get(refId);
           if (!exists) {
             violations.push({
@@ -21730,6 +22467,19 @@ var Vault = class {
         }
       }
     }
+    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 };
   }
   /**
@@ -22005,7 +22755,7 @@ var Vault = class {
     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
@@ -22036,8 +22786,8 @@ var Vault = class {
     }
     registry.validate();
     this.derivationRegistry = registry;
-    if (this.readOnlyFacade === null) {
-      this.readOnlyFacade = new ReadOnlyVaultFacade2(this);
+    if (this.derivationFacade === null) {
+      this.derivationFacade = new ReadOnlyVaultFacade2(this, "derivation");
     }
   }
   /**
@@ -22154,7 +22904,7 @@ var Vault = class {
     const { DerivationExecutor: DerivationExecutor2 } = await Promise.resolve().then(() => (init_executor2(), executor_exports2));
     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) {
@@ -22219,17 +22969,18 @@ var Vault = class {
    * 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."
     );
   }
   /**
@@ -22350,7 +23101,7 @@ var Vault = class {
    *
    * @internal
    */
-  async _logConsent(op, collection, recordId3) {
+  async _logConsent(op, collection, recordId4) {
     const ctx = this.consentContext;
     if (!ctx) return;
     await this.consentStrategy.write(
@@ -22363,7 +23114,7 @@ var Vault = class {
         consentHash: ctx.consentHash,
         op,
         collection,
-        recordId: recordId3
+        recordId: recordId4
       },
       this.getDEK
     );
@@ -22546,14 +23297,14 @@ var Vault = class {
    * the HKDF derivation, record-id composition, and batch logic so the
    * grantor doesn't touch this method directly.
    */
-  async writeMagicLinkGrant(contentKey, grantKek, recordId3, opts) {
+  async writeMagicLinkGrant(contentKey, grantKek, recordId4, opts) {
     return writeMagicLinkGrant(
       this.adapter,
       this.name,
       this.keyring,
       contentKey,
       grantKek,
-      recordId3,
+      recordId4,
       opts
     );
   }
@@ -25117,7 +25868,7 @@ var Noydb = class {
     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);
@@ -27461,6 +28212,60 @@ function immutableGuard(config) {
   return withGuard(spec);
 }
 
+// src/guards/transition-guard.ts
+init_errors();
+function recordId3(record) {
+  const id = record?.id;
+  return typeof id === "string" ? id : "";
+}
+function stateOf(record, field) {
+  const v = record[field];
+  return typeof v === "string" ? v : String(v);
+}
+function transitionGuard(config) {
+  const { collection, field, transitions, initial, amendmentRoles, amendmentInvariant } = config;
+  const allowIdempotent = config.allowIdempotent ?? true;
+  if (!field) {
+    throw new ValidationError("transitionGuard: `field` is required");
+  }
+  if (transitions === void 0 || typeof transitions !== "object") {
+    throw new ValidationError("transitionGuard: `transitions` must be a state\u2192states map");
+  }
+  const spec = {
+    collection,
+    check: (incoming, ctx) => {
+      const rec = incoming;
+      const to = stateOf(rec, field);
+      if (ctx.existing === null) {
+        if (initial !== void 0 && !initial.includes(to)) {
+          throw new IllegalTransitionError(collection, recordId3(rec), "(none)", to);
+        }
+        return;
+      }
+      const from = stateOf(ctx.existing, field);
+      if (from === to) {
+        if (allowIdempotent) return;
+        throw new IllegalTransitionError(collection, recordId3(rec), from, to);
+      }
+      const allowed = transitions[from] ?? [];
+      if (!allowed.includes(to)) {
+        throw new IllegalTransitionError(collection, recordId3(rec), from, to);
+      }
+    },
+    // The authorized override: inside an amendment transaction the check
+    // is skipped and the change is ledgered. By default no extra invariant
+    // — the amendment itself is the sanctioned exception. Callers may
+    // supply `amendmentInvariant` to keep a constraint inviolable even
+    // under amendment; a throw reverts the amendment as `InvariantError`.
+    amendment: {
+      roles: amendmentRoles ?? ["admin", "owner"],
+      invariant: amendmentInvariant ?? (() => {
+      })
+    }
+  };
+  return withGuard(spec);
+}
+
 // src/derivations/with-derivation.ts
 init_errors();
 function withDerivation(spec) {
@@ -27488,8 +28293,37 @@ function withDerivation(spec) {
       }
     }
   }
+  if (spec.triggerBy !== void 0) {
+    for (const t of spec.triggerBy) {
+      if (typeof t?.collection !== "string" || t.collection.length === 0) {
+        throw new ValidationError("withDerivation: each triggerBy entry needs a non-empty `collection`");
+      }
+      if (t.collection === spec.source) {
+        throw new ValidationError(
+          `withDerivation: triggerBy.collection must not equal the source "${spec.source}" (use sources[] for same-id triggers)`
+        );
+      }
+      if (typeof t.on !== "string" || t.on.length === 0) {
+        throw new ValidationError(
+          `withDerivation: triggerBy on "${t.collection}" needs a non-empty \`on\` (the FK field on the source)`
+        );
+      }
+      if (t.maxFanout !== void 0 && (!Number.isInteger(t.maxFanout) || t.maxFanout < 1)) {
+        throw new ValidationError(
+          `withDerivation: triggerBy maxFanout on "${t.collection}" must be a positive integer (got ${String(t.maxFanout)}).`
+        );
+      }
+    }
+  }
   const lifecycleMode = typeof spec.lifecycle === "string" ? spec.lifecycle : spec.lifecycle.mode;
   for (const [outputKey, outputSpec] of Object.entries(spec.outputs)) {
+    if (outputSpec.shape === "record" && outputSpec.collection === spec.source) {
+      if (!outputSpec.denorm || outputSpec.denorm.length === 0) {
+        throw new ValidationError(
+          `withDerivation: self-write output "${outputKey}" (collection === source "${spec.source}") must declare \`denorm: [...]\` naming the fields it maintains.`
+        );
+      }
+    }
     if (outputSpec.shape === "array") {
       if (lifecycleMode !== "eager") {
         throw new ValidationError(
@@ -27517,6 +28351,43 @@ function withDerivation(spec) {
   };
 }
 
+// src/derivations/with-rollup.ts
+init_errors();
+function withRollup(config) {
+  const { from, key, into, field, compute } = config;
+  if (!from || from.length === 0) {
+    throw new ValidationError("withRollup: `from` (child collection) is required");
+  }
+  if (!into || into.length === 0) {
+    throw new ValidationError("withRollup: `into` (parent collection) is required");
+  }
+  if (from === into) {
+    throw new ValidationError("withRollup: `from` and `into` must be different collections");
+  }
+  if (!key || key.length === 0) {
+    throw new ValidationError("withRollup: `key` (FK field on the child) is required");
+  }
+  if (!field || field.length === 0) {
+    throw new ValidationError("withRollup: `field` (target field on the parent) is required");
+  }
+  if (typeof compute !== "function") {
+    throw new ValidationError("withRollup: `compute` must be a function");
+  }
+  const spec = {
+    source: into,
+    // the parent record is what carries the rolled-up field
+    deterministic: true,
+    rollup: { from, key, field, compute },
+    // Synthetic self-write output for registry / cycle bookkeeping. Dispatch
+    // patches `field` directly (value-equality guarded); the executor is not run.
+    outputs: { value: { shape: "record", collection: into, denorm: [field] } },
+    derive: () => ({ value: {} }),
+    // never invoked for a rollup strategy
+    lifecycle: "eager"
+  };
+  return { __noydb_strategy: "derivation", spec };
+}
+
 // src/index.ts
 init_errors();
 
@@ -28578,6 +29449,7 @@ function shortJSON(value) {
   GroupedQuery,
   GroupedQueryN,
   INDEXED_STORE_POLICY,
+  IllegalTransitionError,
   ImportCapabilityError,
   IndexRequiredError,
   IndexWriteFailureError,
@@ -28590,6 +29462,8 @@ function shortJSON(value) {
   LEDGER_DELTAS_COLLECTION,
   LedgerContentionError,
   LedgerStore,
+  LinkEndpointError,
+  LinkIntegrityError,
   LocaleNotSpecifiedError,
   Lru,
   MAGIC_LINK_CONTENT_INFO_PREFIX,
@@ -28721,6 +29595,7 @@ function shortJSON(value) {
   canonicalJson,
   checkGate,
   clearDevUnlock,
+  compileSequenceFormat,
   computePatch,
   coordinatedCutover,
   count,
@@ -28783,11 +29658,13 @@ function shortJSON(value) {
   isDictKeyDescriptor,
   isDiscriminant,
   isI18nTextDescriptor,
+  isLinkCollectionName,
   isMagicLinkGrantExpired,
   isMoneyDescriptor,
   isMoneyString,
   isPreCompressed,
   isPublicEnvelope,
+  isRefArray,
   isSessionAlive,
   isStaticDictDescriptor,
   isULID,
@@ -28841,6 +29718,7 @@ function shortJSON(value) {
   recoverUser,
   reduceRecords,
   ref,
+  refArray,
   removeAuthenticator,
   resetBrotliSupportCache,
   resetJoinWarnings,
@@ -28868,6 +29746,7 @@ function shortJSON(value) {
   sha256Hex,
   staticDict,
   sum,
+  transitionGuard,
   unwrapDeksFromBlob,
   unwrapDeksFromPaperEntry,
   unwrapDeksFromShamirEntry,
@@ -28891,6 +29770,7 @@ function shortJSON(value) {
   withMetrics,
   withOverlayedView,
   withRetry,
+  withRollup,
   wrapBundleStore,
   wrapStore,
   writeMagicLinkGrant,