@noy-db/hub 0.2.0-pre.12 → 0.2.0-pre.14

package/dist/bundle/index.cjs

@@ -31,7 +31,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/errors.ts
-var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, UnknownShardError, ShardProvisioningError, VaultTemplateNotFoundError;
+var NoydbError, DecryptionError, TamperedError, InvalidKeyError, KeyringCorruptError, NoAccessError, ReadOnlyError, PermissionDeniedError, ExportCapabilityError, KeyringExpiredError, ImportCapabilityError, StoreCapabilityError, PrivilegeEscalationError, ReservedVaultNameError, FieldFrozenError, InvariantError, AmendmentForbiddenError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, NumberingUncertaintyError, BundleVersionConflictError, ValidationError, SchemaValidationError, SchemaUpdateError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, LocaleNotSpecifiedError, TranslatorNotConfiguredError, BackupLedgerError, BackupCorruptedError, PartitionExtractionError, TransferSealError, AdoptionStateError, AttestationError, JoinTooLargeError, CrossJoinTooLargeError, CrossJoinSourceUnknownError, DanglingReferenceError, DerivationCycleError, DerivationOutputShapeError, DerivationCapExceededError, MaterializedViewCycleError, MaterializedViewSourceUnknownError, MaterializedViewTooLargeError, OverlayBaseIsVirtualError, OverlayCollectionUnavailableError, OverlayNameCollisionError, OverlayIdMismatchError, UnknownShardError, ShardProvisioningError, CrossShardJoinError, VaultTemplateNotFoundError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -155,6 +155,18 @@ var init_errors = __esm({
         this.offendingCollection = offendingCollection;
       }
     };
+    ReservedVaultNameError = class extends NoydbError {
+      /** The rejected vault name. */
+      vaultName;
+      constructor(vaultName) {
+        super(
+          "RESERVED_VAULT_NAME",
+          `"${vaultName}" is a reserved internal vault name and cannot be used as a group name or partition key`
+        );
+        this.name = "ReservedVaultNameError";
+        this.vaultName = vaultName;
+      }
+    };
     FieldFrozenError = class extends NoydbError {
       collection;
       id;
@@ -288,6 +300,17 @@ var init_errors = __esm({
         this.name = "SequenceOfflineError";
       }
     };
+    NumberingUncertaintyError = class extends NoydbError {
+      series;
+      constructor(series) {
+        super(
+          "NUMBERING_UNCERTAINTY",
+          `Deferred numbering for series "${series}" cannot run: the store does not expose getStoreTime() (capabilities.serverWriteTime). Use a CAS sequence or a store with serverWriteTime.`
+        );
+        this.name = "NumberingUncertaintyError";
+        this.series = series;
+      }
+    };
     BundleVersionConflictError = class extends NoydbError {
       /** The bundle handle of the newer remote version that rejected the push. */
       remoteVersion;
@@ -723,6 +746,12 @@ Resolutions:
         this.vaultId = vaultId;
       }
     };
+    CrossShardJoinError = class extends NoydbError {
+      constructor(message) {
+        super("CROSS_SHARD_JOIN", message);
+        this.name = "CrossShardJoinError";
+      }
+    };
     VaultTemplateNotFoundError = class extends NoydbError {
       templateName;
       constructor(templateName) {
@@ -2716,6 +2745,15 @@ var init_store = __esm({
   }
 });
 
+// src/federation/constants.ts
+var STATE_VAULT_NAME;
+var init_constants2 = __esm({
+  "src/federation/constants.ts"() {
+    "use strict";
+    STATE_VAULT_NAME = "__noydb_state__";
+  }
+});
+
 // src/policy/errors.ts
 var PolicyDeniedError, RecoveryNotEnrolledError, ManagedRecoveryNotEnrolledError, RecoveryProfileNotImplementedError;
 var init_errors2 = __esm({
@@ -3712,10 +3750,10 @@ function shouldRoundUp(negative, lastKeptDigit, firstDiscarded, hasMoreNonZeroAf
   }
 }
 function parseToScaledInt(input, scale, rounding) {
-  const canonical = toCanonicalDecimalString(input);
-  if (canonical === null) return { ok: false, reason: "nonfinite" };
-  const negative = canonical.startsWith("-");
-  const unsigned = negative ? canonical.slice(1) : canonical;
+  const canonical2 = toCanonicalDecimalString(input);
+  if (canonical2 === null) return { ok: false, reason: "nonfinite" };
+  const negative = canonical2.startsWith("-");
+  const unsigned = negative ? canonical2.slice(1) : canonical2;
   const dot = unsigned.indexOf(".");
   const intPart = dot === -1 ? unsigned : unsigned.slice(0, dot);
   const fracPart = dot === -1 ? "" : unsigned.slice(dot + 1);
@@ -4869,7 +4907,7 @@ function serializeClause(clause) {
 }
 function canonicalCtxHash(ctx) {
   if (ctx === void 0) return "";
-  const canonical = JSON.stringify(ctx, (_key, value) => {
+  const canonical2 = JSON.stringify(ctx, (_key, value) => {
     if (value && typeof value === "object" && !Array.isArray(value)) {
       const sorted = {};
       for (const k of Object.keys(value).sort()) {
@@ -4880,8 +4918,8 @@ function canonicalCtxHash(ctx) {
     return value;
   });
   let h = 5381;
-  for (let i = 0; i < canonical.length; i++) {
-    h = (h << 5) + h ^ canonical.charCodeAt(i);
+  for (let i = 0; i < canonical2.length; i++) {
+    h = (h << 5) + h ^ canonical2.charCodeAt(i);
   }
   return (h >>> 0).toString(16).padStart(8, "0");
 }
@@ -4924,6 +4962,7 @@ var init_builder = __esm({
     init_live();
     init_strategy4();
     init_money_reducer();
+    init_normalize();
     EMPTY_PLAN = {
       clauses: [],
       orderBy: [],
@@ -5292,7 +5331,7 @@ var init_builder = __esm({
        * for the ordering rationale.
        */
       toArray() {
-        const base = executePlanWithSource(this.source, this.plan, this.joinContext);
+        const base = this.decodeMoney(executePlanWithSource(this.source, this.plan, this.joinContext));
         if (this.plan.joins.length === 0) return base;
         if (!this.joinContext) {
           throw new Error(
@@ -5301,6 +5340,23 @@ var init_builder = __esm({
         }
         return applyJoins(base, this.plan.joins, this.joinContext);
       }
+      /**
+       * Decode this source's money fields on read (stored scaled-int → canonical
+       * decimal), so `query().toArray()` agrees with `get()`/`sum()` on the value.
+       * No-op when the source declares no money fields.
+       *
+       * The query layer carries no locale context, so we decode with `'raw'` —
+       * canonical decimal, WITHOUT fabricating locale-formatted `<field>Formatted`
+       * / `<field>Number` virtuals. Producing a guessed-locale string here would
+       * just reintroduce #322's "two read paths disagree" failure on the virtual
+       * field (e.g. it-IT via `get()` vs en-US here). Consumers who need formatted
+       * money read through `get()`/`list()` with a locale.
+       */
+      decodeMoney(records) {
+        const moneyFields = this.source.moneyFields;
+        if (!moneyFields || Object.keys(moneyFields).length === 0) return records;
+        return records.map((r) => decodeMoneyFields(r, moneyFields, "raw"));
+      }
       /** Return the first matching record, or null. Joins are applied. */
       first() {
         const arr = this.limit(1).toArray();
@@ -5678,6 +5734,7 @@ var init_scan_builder = __esm({
     "use strict";
     init_predicate();
     init_errors();
+    init_normalize();
     DEFAULT_SCAN_PAGE_SIZE = 100;
     ScanBuilder = class _ScanBuilder {
       pageProvider;
@@ -5703,12 +5760,29 @@ var init_scan_builder = __esm({
        * context throws with an actionable error.
        */
       joinContext;
-      constructor(pageProvider, pageSize = DEFAULT_SCAN_PAGE_SIZE, clauses = [], joins = [], joinContext) {
+      /**
+       * Money field descriptors for the backing collection. When present, yielded
+       * records are decoded (stored scaled-int → canonical decimal) so `scan()`
+       * agrees with `get()`/`list()`/`query().toArray()` — #322. Decoded with
+       * `'raw'` (canonical decimal, no locale-formatted virtuals) since the scan
+       * stream carries no locale context, mirroring `Query.toArray()`.
+       */
+      moneyFields;
+      constructor(pageProvider, pageSize = DEFAULT_SCAN_PAGE_SIZE, clauses = [], joins = [], joinContext, moneyFields) {
         this.pageProvider = pageProvider;
         this.pageSize = pageSize;
         this.clauses = clauses;
         this.joins = joins;
         this.joinContext = joinContext;
+        this.moneyFields = moneyFields;
+      }
+      /**
+       * Decode this scan's money fields on a record (stored scaled-int → canonical
+       * decimal). No-op when no money fields are declared. See {@link moneyFields}.
+       */
+      decodeMoney(record) {
+        if (!this.moneyFields || Object.keys(this.moneyFields).length === 0) return record;
+        return decodeMoneyFields(record, this.moneyFields, "raw");
       }
       /**
        * Add a field comparison. Runs per record as the scan stream
@@ -5730,7 +5804,8 @@ var init_scan_builder = __esm({
           this.pageSize,
           [...this.clauses, clause],
           this.joins,
-          this.joinContext
+          this.joinContext,
+          this.moneyFields
         );
       }
       /**
@@ -5749,7 +5824,8 @@ var init_scan_builder = __esm({
           this.pageSize,
           [...this.clauses, clause],
           this.joins,
-          this.joinContext
+          this.joinContext,
+          this.moneyFields
         );
       }
       /**
@@ -5860,7 +5936,8 @@ var init_scan_builder = __esm({
           this.pageSize,
           this.clauses,
           [...this.joins, leg],
-          this.joinContext
+          this.joinContext,
+          this.moneyFields
         );
       }
       /**
@@ -5877,10 +5954,11 @@ var init_scan_builder = __esm({
         while (true) {
           for (const record of page.items) {
             if (!this.recordMatches(record)) continue;
+            const decoded = this.decodeMoney(record);
             if (joinResolvers === null) {
-              yield record;
+              yield decoded;
             } else {
-              let attached = record;
+              let attached = decoded;
               for (const resolver of joinResolvers) {
                 attached = this.applyOneJoinStreaming(attached, resolver);
               }
@@ -7048,12 +7126,12 @@ var init_dependency_analyzer = __esm({
 
 // src/materialized-views/query-hash.ts
 async function computeQueryHash(mvName, dependencies, queryPlanSummary) {
-  const canonical = JSON.stringify({
+  const canonical2 = JSON.stringify({
     mvName,
     dependencies: [...dependencies].sort(),
     queryPlanSummary
   });
-  const bytes = new TextEncoder().encode(canonical);
+  const bytes = new TextEncoder().encode(canonical2);
   const digest = await crypto.subtle.digest("SHA-256", bytes);
   return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -8914,9 +8992,17 @@ var init_collection = __esm({
         }
         await this.ensureHydrated();
         const records = [...this.cache.values()].map((e) => e.record);
-        if (!locale) return records;
+        if (!this.hasReadTransforms()) return records;
         return Promise.all(records.map((r) => this.applyLocaleToRecord(r, locale)));
       }
+      /**
+       * @internal — whether any read-side record transform is registered
+       * (money decode, i18nText resolution, dictKey labels). Gates the
+       * no-transform fast path in {@link list}.
+       */
+      hasReadTransforms() {
+        return this.moneyFields !== void 0 && Object.keys(this.moneyFields).length > 0 || this.i18nFields !== void 0 && Object.keys(this.i18nFields).length > 0 || this.dictKeyFields !== void 0 && Object.keys(this.dictKeyFields).length > 0;
+      }
       // ─── Bulk operations ─────────────────────────────────────
       /**
        * Put many records in one call. Each item is processed sequentially
@@ -9422,7 +9508,8 @@ var init_collection = __esm({
           pageSize,
           [],
           [],
-          joinContext
+          joinContext,
+          this.moneyFields
         );
       }
       /** Decrypt a page of envelopes returned by `adapter.listPage`. */
@@ -10790,6 +10877,168 @@ var init_sequence = __esm({
   }
 });
 
+// src/numbering/index.ts
+var NUMBERING_HEAD_COLLECTION, NUMBERING_PENDING_COLLECTION, DeferredNumberingStore;
+var init_numbering = __esm({
+  "src/numbering/index.ts"() {
+    "use strict";
+    init_types();
+    init_crypto();
+    init_errors();
+    NUMBERING_HEAD_COLLECTION = "_numbering_head";
+    NUMBERING_PENDING_COLLECTION = "_numbering_pending";
+    DeferredNumberingStore = class {
+      adapter;
+      vault;
+      encrypted;
+      getDEK;
+      actor;
+      configs;
+      /**
+       * Stamp a serial onto a USER record THROUGH the Collection layer (so the
+       * cache, indexes, and MVs stay coherent — the engine must NOT write user
+       * collections at the raw adapter level). Returns false if the record is
+       * gone (the engine then skips it without burning a serial). Provided by the
+       * vault; unit tests pass a Map-backed double.
+       */
+      stamp;
+      /** In-process registry: `${series}::${recordId}` → resolver for the live next() Promise. */
+      waiters = /* @__PURE__ */ new Map();
+      dekCache = /* @__PURE__ */ new Map();
+      constructor(opts) {
+        this.adapter = opts.adapter;
+        this.vault = opts.vault;
+        this.encrypted = opts.encrypted;
+        this.getDEK = opts.getDEK;
+        this.actor = opts.actor;
+        this.configs = opts.configs;
+        this.stamp = opts.stamp;
+      }
+      has(series) {
+        return this.configs.has(series);
+      }
+      dek(collection) {
+        let p = this.dekCache.get(collection);
+        if (!p) {
+          p = this.getDEK(collection);
+          this.dekCache.set(collection, p);
+        }
+        return p;
+      }
+      async readJson(collection, id) {
+        const env = await this.adapter.get(this.vault, collection, id);
+        if (!env) return { env: null, value: null };
+        const json = this.encrypted ? await decrypt(env._iv, env._data, await this.dek(collection)) : env._data;
+        return { env, value: JSON.parse(json) };
+      }
+      async writeJson(collection, id, value, expectedVersion) {
+        const json = JSON.stringify(value);
+        let env;
+        if (!this.encrypted) {
+          env = { _noydb: NOYDB_FORMAT_VERSION, _v: expectedVersion + 1, _ts: (/* @__PURE__ */ new Date()).toISOString(), _iv: "", _data: json, _by: this.actor };
+        } else {
+          const { iv, data } = await encrypt(json, await this.dek(collection));
+          env = { _noydb: NOYDB_FORMAT_VERSION, _v: expectedVersion + 1, _ts: (/* @__PURE__ */ new Date()).toISOString(), _iv: iv, _data: data, _by: this.actor };
+        }
+        await this.adapter.put(this.vault, collection, id, env, expectedVersion);
+      }
+      pendingId(series, recordId2) {
+        return `${series}::${recordId2}`;
+      }
+      /** Current last-assigned serial for a series (0 if none). */
+      async peek(series) {
+        const { value } = await this.readJson(NUMBERING_HEAD_COLLECTION, series);
+        return value?.lastSerial ?? 0;
+      }
+      /**
+       * Enqueue a record for numbering: stamp it with the current store clock and
+       * durably write a pending entry. The returned Promise resolves once the
+       * record is durably enqueued; its `assigned` field resolves with the serial
+       * 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, recordId2) {
+        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, recordId2);
+        const { env } = await this.readJson(NUMBERING_PENDING_COLLECTION, id);
+        const entry = {
+          series,
+          recordId: recordId2,
+          collection: cfg.collection,
+          field: cfg.field,
+          storeEarliest: st.earliest,
+          storeLatest: st.latest,
+          enqueuedAt: Date.now()
+        };
+        await this.writeJson(NUMBERING_PENDING_COLLECTION, id, entry, env?._v ?? 0);
+        const assigned = new Promise((resolve, reject) => {
+          this.waiters.set(id, { resolve, reject });
+        });
+        return { assigned };
+      }
+      async listPending(series) {
+        const ids = await this.adapter.list(this.vault, NUMBERING_PENDING_COLLECTION);
+        const prefix = `${series}::`;
+        const out = [];
+        for (const id of ids) {
+          if (!id.startsWith(prefix)) continue;
+          const { value } = await this.readJson(NUMBERING_PENDING_COLLECTION, id);
+          if (value) out.push({ id, entry: value });
+        }
+        return out;
+      }
+      /**
+       * Run a numbering pass for `series`: select entries provably settled
+       * (`storeLatest ≤ now.earliest` — commit-wait), order by
+       * `(storeEarliest, recordId)`, assign serials after the head, stamp each
+       * record's field, advance the head with one CAS, and consume the entries.
+       * Idempotent/convergent: a losing concurrent pass returns `[]` and the next
+       * pass reconciles. Resolves any in-process enqueue() `assigned` Promises.
+       */
+      async runPass(series) {
+        const cfg = this.configs.get(series);
+        if (!cfg) throw new NumberingUncertaintyError(series);
+        if (typeof this.adapter.getStoreTime !== "function") throw new NumberingUncertaintyError(series);
+        const now = await this.adapter.getStoreTime();
+        const settled = (await this.listPending(series)).filter((p) => p.entry.storeLatest <= now.earliest).sort(
+          (a, b) => a.entry.storeEarliest - b.entry.storeEarliest || (a.entry.recordId < b.entry.recordId ? -1 : a.entry.recordId > b.entry.recordId ? 1 : 0)
+        );
+        if (settled.length === 0) return [];
+        const { env: headEnv, value: head } = await this.readJson(NUMBERING_HEAD_COLLECTION, series);
+        let serial = head?.lastSerial ?? 0;
+        const assignments = [];
+        for (const { entry } of settled) {
+          serial += 1;
+          const ok = await this.stamp(entry.collection, entry.recordId, entry.field, serial);
+          if (!ok) {
+            serial -= 1;
+            continue;
+          }
+          assignments.push({ recordId: entry.recordId, serial });
+        }
+        try {
+          await this.writeJson(NUMBERING_HEAD_COLLECTION, series, { series, lastSerial: serial, watermark: now.earliest }, headEnv?._v ?? 0);
+        } catch (err) {
+          if (err instanceof ConflictError) return [];
+          throw err;
+        }
+        for (const { id, entry } of settled) {
+          await this.adapter.delete(this.vault, NUMBERING_PENDING_COLLECTION, id);
+          const a = assignments.find((x) => x.recordId === entry.recordId);
+          if (a) {
+            this.waiters.get(id)?.resolve(a.serial);
+            this.waiters.delete(id);
+          }
+        }
+        return assignments;
+      }
+    };
+  }
+});
+
 // src/shadow/strategy.ts
 var NOT_ENABLED3, NO_SHADOW;
 var init_strategy7 = __esm({
@@ -11598,8 +11847,8 @@ async function derivePersistedSchema(validator) {
   if (kind === "Zod") {
     const convert = await loadZodConverter();
     const jsonSchema = convert(validator);
-    const canonical = canonicalize(jsonSchema);
-    const hash = await sha256Hex2(new TextEncoder().encode(canonical));
+    const canonical2 = canonicalize(jsonSchema);
+    const hash = await sha256Hex2(new TextEncoder().encode(canonical2));
     return { _noydb_schema: 1, kind, jsonSchema, hash, derivedAt };
   }
   return {
@@ -12639,12 +12888,12 @@ var init_read_only_facade = __esm({
 
 // src/derivations/strategy-hash.ts
 async function computeStrategyHash(source, outputKeys, derive) {
-  const canonical = JSON.stringify({
+  const canonical2 = JSON.stringify({
     source,
     outputs: [...outputKeys].sort(),
     derive: derive.toString()
   });
-  const bytes = new TextEncoder().encode(canonical);
+  const bytes = new TextEncoder().encode(canonical2);
   const digest = await crypto.subtle.digest("SHA-256", bytes);
   return Array.from(new Uint8Array(digest)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
@@ -12919,6 +13168,7 @@ var init_vault = __esm({
     init_errors();
     init_archive();
     init_sequence();
+    init_numbering();
     init_constants();
     init_entry();
     init_strategy3();
@@ -13086,6 +13336,10 @@ var init_vault = __esm({
       ledgerStore = null;
       /** Lazily-built atomic-sequence store. See {@link sequence}. */
       sequenceStore = null;
+      /** Lazily-built deferred-numbering engine. See {@link runNumberingPass}. */
+      deferredNumbering = null;
+      /** Registered deferred-numbering series, keyed by series name. */
+      numberingConfigs;
       /**
        * Background writes for persisted-schema envelopes (#schema-dump v0
        * slice 1). One promise per `collection({ persistJsonSchema: true })`
@@ -13172,6 +13426,7 @@ var init_vault = __esm({
       constructor(opts) {
         this.adapter = opts.adapter;
         this.name = opts.name;
+        this.numberingConfigs = new Map((opts.numberingConfigs ?? []).map((c) => [c.series, c]));
         this.noydb = opts.noydb;
         this.keyring = opts.keyring;
         this.encrypted = opts.encrypted;
@@ -13846,6 +14101,18 @@ var init_vault = __esm({
        * ```
        */
       sequence(name) {
+        if (this.numberingConfigs.has(name)) {
+          const eng = this.deferred();
+          return {
+            next: async (opts) => {
+              if (!opts?.for) {
+                throw new ValidationError(`sequence("${name}") is a deferred-numbering series; call next({ for: recordId }).`);
+              }
+              return (await eng.enqueue(name, opts.for)).assigned;
+            },
+            peek: () => eng.peek(name)
+          };
+        }
         if (!this.sequenceStore) {
           this.sequenceStore = new SequenceStore({
             adapter: this.adapter,
@@ -13857,6 +14124,38 @@ var init_vault = __esm({
         }
         return this.sequenceStore.handle(name);
       }
+      /** @internal — lazily build the deferred-numbering engine with a cache-coherent stamp. */
+      deferred() {
+        if (!this.deferredNumbering) {
+          this.deferredNumbering = new DeferredNumberingStore({
+            adapter: this.adapter,
+            vault: this.name,
+            encrypted: this.encrypted,
+            getDEK: this.getDEK,
+            actor: this.keyring.userId,
+            configs: this.numberingConfigs,
+            // 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, recordId2, field, serial) => {
+              const coll = this.collection(collection);
+              const rec = await coll.get(recordId2);
+              if (!rec) return false;
+              await coll.put(recordId2, { ...rec, [field]: serial });
+              return true;
+            }
+          });
+        }
+        return this.deferredNumbering;
+      }
+      /**
+       * Run a deferred-numbering pass for `series`: assign gap-free serials to all
+       * records whose store-commit-time interval has settled, in store-time order.
+       * Returns the assignments made. See {@link sequence} / `withDeferredNumbering`.
+       */
+      async runNumberingPass(series) {
+        return this.deferred().runPass(series);
+      }
       async compact(options = {}) {
         return runCompaction({
           adapter: this.adapter,
@@ -16910,6 +17209,54 @@ var init_classify_skip = __esm({
   }
 });
 
+// src/federation/cross-shard-join.ts
+function coerceKey(value) {
+  if (value === null || value === void 0) return null;
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  return null;
+}
+function warnOnceBroadcastMiss(field, as, key) {
+  const dedup = `${field}\u2192${as}:${key}`;
+  if (warnedBroadcastKeys.has(dedup)) return;
+  warnedBroadcastKeys.add(dedup);
+  console.warn(
+    `[noy-db] broadcastJoin: no "${as}" dimension row for ${field}="${key}". Attaching null. Use mode: 'cascade' to silence.`
+  );
+}
+async function applyBroadcastLegs(rows, legs) {
+  if (legs.length === 0) return [...rows];
+  const indexes = [];
+  for (const leg of legs) {
+    const map = /* @__PURE__ */ new Map();
+    for (const rec of await leg.from.list()) {
+      const k = coerceKey(readPath(rec, leg.on));
+      if (k !== null && !map.has(k)) map.set(k, rec);
+    }
+    indexes.push({ leg, map });
+  }
+  return rows.map((row) => {
+    const out = { ...row };
+    for (const { leg, map } of indexes) {
+      const key = coerceKey(readPath(row, leg.field));
+      const match = key === null ? null : map.get(key) ?? null;
+      if (match === null && leg.mode === "warn") {
+        warnOnceBroadcastMiss(leg.field, leg.as, key ?? "<null>");
+      }
+      out[leg.as] = match;
+    }
+    return out;
+  });
+}
+var warnedBroadcastKeys;
+var init_cross_shard_join = __esm({
+  "src/federation/cross-shard-join.ts"() {
+    "use strict";
+    init_predicate();
+    warnedBroadcastKeys = /* @__PURE__ */ new Set();
+  }
+});
+
 // src/federation/cross-vault-live.ts
 var CrossVaultLive;
 var init_cross_vault_live = __esm({
@@ -17117,6 +17464,9 @@ function assertSafePartitionKey(partitionKey) {
   if (partitionKey.length === 0) {
     throw new ValidationError("partitionKey must be a non-empty string");
   }
+  if (partitionKey === STATE_VAULT_NAME) {
+    throw new ReservedVaultNameError(partitionKey);
+  }
   if (!SAFE_PARTITION_KEY.test(partitionKey)) {
     throw new ValidationError(
       `partitionKey "${partitionKey}" contains characters outside [A-Za-z0-9._-]. Map your records to a store-safe key in sharding.keyOf.`
@@ -17133,7 +17483,9 @@ var init_vault_group = __esm({
   "src/federation/vault-group.ts"() {
     "use strict";
     init_errors();
+    init_constants2();
     init_classify_skip();
+    init_cross_shard_join();
     init_cross_vault_live();
     init_aggregate_across();
     SHARD_SEPARATOR = "--";
@@ -17156,15 +17508,38 @@ var init_vault_group = __esm({
       registry;
       sharding;
       template;
+      /** @internal — set when the group is managed (no explicit registry). */
+      stateVault;
+      /** @internal */
+      _attachStateVault(sv) {
+        this.stateVault = sv;
+      }
       /** Deterministic vault name for a partition key, namespaced by the group. */
       shardVaultId(partitionKey) {
         assertSafePartitionKey(partitionKey);
         return `${this.name}${SHARD_SEPARATOR}${partitionKey}`;
       }
-      /** All registry rows (hydrates the registry collection first). */
+      /**
+       * @internal — group-qualified registry record key (avoids cross-group key
+       * collisions). Identical to the shard vault id by design — the registry row
+       * for a shard is keyed by that shard's vault id — so it delegates to
+       * `shardVaultId`, reusing its partition-key validation.
+       */
+      registryId(partitionKey) {
+        return this.shardVaultId(partitionKey);
+      }
+      /**
+       * Registry rows for THIS group (hydrates the registry collection first).
+       * The registry may be shared across groups (the auto-wired StateManagement
+       * vault holds one `vaultRegistry` for the whole instance), so rows are
+       * filtered by `group` — without this, a group's fan-out reads would leak
+       * across into other groups' shards. Mirrors the `${group}--` scoping that
+       * `liveBinding().isRelevant` already applies to the reactive path.
+       */
       async allRows() {
         await this.registry.list();
-        return this.registry.query().toArray();
+        const rows = this.registry.query().toArray();
+        return rows.filter((r) => r.group === this.name);
       }
       /** Open an existing shard and apply the template. */
       async openShard(partitionKey) {
@@ -17182,19 +17557,32 @@ var init_vault_group = __esm({
        */
       async createShard(partitionKey) {
         const vaultId = this.shardVaultId(partitionKey);
-        const row = await this.registry.get(partitionKey);
+        const row = await this.registry.get(this.registryId(partitionKey));
         const provisioned = await this.db._shardVaultProvisioned(vaultId);
         if (row && !provisioned) throw new ShardProvisioningError(vaultId, partitionKey);
         if (row && provisioned) return this.openShard(partitionKey);
         const vault = await this.db.openVault(vaultId);
         this.template.configure(vault);
-        await this.registry.put(partitionKey, {
+        await this.registry.put(this.registryId(partitionKey), {
           vaultId,
           partitionKey,
           templateName: this.sharding.vaultTemplate,
           schemaVersion: this.template.version,
-          createdAt: Date.now()
+          createdAt: Date.now(),
+          group: this.name
         });
+        if (this.stateVault) {
+          try {
+            await this.stateVault.appendEvent({
+              type: "shard-created",
+              group: this.name,
+              vaultId,
+              templateName: this.sharding.vaultTemplate,
+              version: this.template.version
+            });
+          } catch {
+          }
+        }
         return vault;
       }
       /**
@@ -17204,7 +17592,7 @@ var init_vault_group = __esm({
        */
       async shard(partitionKey) {
         const vaultId = this.shardVaultId(partitionKey);
-        const row = await this.registry.get(partitionKey);
+        const row = await this.registry.get(this.registryId(partitionKey));
         if (!row) throw new UnknownShardError(partitionKey, this.name);
         const provisioned = await this.db._shardVaultProvisioned(vaultId);
         if (!provisioned) throw new ShardProvisioningError(vaultId, partitionKey);
@@ -17243,7 +17631,7 @@ var init_vault_group = __esm({
       /** Route a write to the shard owning `keyOf(record)`. */
       async put(id, record) {
         const key = this.group.sharding.keyOf(record);
-        const row = await this.group.registry.get(key);
+        const row = await this.group.registry.get(this.group.registryId(key));
         let vault;
         if (!row) {
           if (this.group.sharding.autoCreate === false) {
@@ -17261,31 +17649,89 @@ var init_vault_group = __esm({
       }
     };
     ShardedQuery = class _ShardedQuery {
-      constructor(group, collectionName, clauses) {
+      constructor(group, collectionName, clauses, coPartitionedLegs = [], broadcastLegs = []) {
         this.group = group;
         this.collectionName = collectionName;
         this.clauses = clauses;
+        this.coPartitionedLegs = coPartitionedLegs;
+        this.broadcastLegs = broadcastLegs;
       }
       group;
       collectionName;
       clauses;
+      coPartitionedLegs;
+      broadcastLegs;
       where(field, op, value) {
-        return new _ShardedQuery(this.group, this.collectionName, [
-          ...this.clauses,
-          { field, op, value }
-        ]);
+        return new _ShardedQuery(
+          this.group,
+          this.collectionName,
+          [...this.clauses, { field, op, value }],
+          this.coPartitionedLegs,
+          this.broadcastLegs
+        );
+      }
+      /** Co-partitioned join: each shard joins its own same-vault right collection (resolved via ref()), then union. */
+      crossShardJoin(field, opts) {
+        const leg = { field, as: opts.as, maxRows: opts.maxRows, strategy: opts.strategy };
+        return new _ShardedQuery(
+          this.group,
+          this.collectionName,
+          this.clauses,
+          [...this.coPartitionedLegs, leg],
+          this.broadcastLegs
+        );
+      }
+      /** Broadcast dimension join: enrich every merged row from a single shared collection. */
+      broadcastJoin(field, opts) {
+        const leg = {
+          field,
+          as: opts.as,
+          from: opts.from,
+          on: opts.on ?? "id",
+          mode: opts.mode ?? "warn"
+        };
+        return new _ShardedQuery(
+          this.group,
+          this.collectionName,
+          this.clauses,
+          this.coPartitionedLegs,
+          [...this.broadcastLegs, leg]
+        );
       }
       /** @internal — fan out the where-filtered records across eligible shards. */
       async fanoutRecords(options = {}) {
         const { eligible, skipped } = await this.group.resolveEligible(options);
+        const probeRow = eligible[0];
+        if (this.coPartitionedLegs.length > 0 && probeRow) {
+          const probe = await this.group.openShard(probeRow.partitionKey);
+          this.group.template.configure(probe);
+          for (const leg of this.coPartitionedLegs) {
+            if (!probe.resolveRef(this.collectionName, leg.field)) {
+              throw new CrossShardJoinError(
+                `crossShardJoin("${leg.field}"): no ref() declared for "${leg.field}" on collection "${this.collectionName}" in template "${this.group.sharding.vaultTemplate}". Add refs: { ${leg.field}: ref('<target>') } to the template's collection options.`
+              );
+            }
+          }
+        }
         const across = await this.group.db.queryAcross(
           eligible.map((r) => r.vaultId),
           async (vault) => {
             this.group.template.configure(vault);
             const coll = vault.collection(this.collectionName);
             await coll.list();
+            for (const leg of this.coPartitionedLegs) {
+              const desc = vault.resolveRef(this.collectionName, leg.field);
+              if (desc) await vault.collection(desc.target).list();
+            }
             let q = coll.query();
             for (const c of this.clauses) q = q.where(c.field, c.op, c.value);
+            for (const leg of this.coPartitionedLegs) {
+              q = q.join(leg.field, {
+                as: leg.as,
+                ...leg.maxRows !== void 0 ? { maxRows: leg.maxRows } : {},
+                ...leg.strategy ? { strategy: leg.strategy } : {}
+              });
+            }
             return q.toArray();
           },
           { concurrency: options.concurrency ?? 1, create: false }
@@ -17297,10 +17743,11 @@ var init_vault_group = __esm({
         }
         return { records: results, skippedVaults: skipped };
       }
-      /** Fan out across eligible shards and merge results. */
+      /** Fan out across eligible shards, merge, then apply any broadcast dimension legs. */
       async toArray(options = {}) {
         const { records, skippedVaults } = await this.fanoutRecords(options);
-        return { results: records, skippedVaults };
+        const results = await applyBroadcastLegs(records, this.broadcastLegs);
+        return { results, skippedVaults };
       }
       /** @internal — build the change-subscription + relevance binding for this query's group+collection. */
       liveBinding() {
@@ -17314,8 +17761,17 @@ var init_vault_group = __esm({
           isRelevant: (e) => e.collection === collectionName && e.vault.startsWith(`${group.name}--`)
         };
       }
+      /** @internal — joined queries don't support reactive/aggregate surfaces in v1. */
+      assertNoJoinLegs(surface) {
+        if (this.coPartitionedLegs.length || this.broadcastLegs.length) {
+          throw new CrossShardJoinError(
+            `${surface}() is not supported on a ShardedQuery with crossShardJoin/broadcastJoin legs in v1. Use toArray() for joined cross-shard queries.`
+          );
+        }
+      }
       /** Returns a reactive cross-shard live query — a facade over CrossVaultLive. */
       live(options = {}) {
+        this.assertNoJoinLegs("live");
         const bind = this.liveBinding();
         const core = new CrossVaultLive({
           ...bind,
@@ -17343,10 +17799,12 @@ var init_vault_group = __esm({
       }
       /** One-shot distributed aggregate — central reduce over all shard records. */
       aggregate(spec) {
+        this.assertNoJoinLegs("aggregate");
         return new CrossVaultAggregation(this, spec, this.liveBinding());
       }
       /** Begin a grouped cross-shard aggregate. */
       groupBy(field) {
+        this.assertNoJoinLegs("groupBy");
         return new ShardedGroupedQuery(this, field);
       }
     };
@@ -17369,6 +17827,159 @@ var init_vault_group = __esm({
   }
 });
 
+// src/federation/schema-manifest.ts
+function captureBlueprint(configure) {
+  const recorded = [];
+  const collectionStub = new Proxy(
+    {},
+    {
+      get: () => () => collectionStub
+    }
+  );
+  const proxy = new Proxy(
+    {},
+    {
+      get: (_t, prop) => {
+        if (prop === "collection") {
+          return (name, opts) => {
+            recorded.push({
+              name,
+              indexes: opts?.indexes ?? [],
+              persistJsonSchema: !!opts?.persistJsonSchema
+            });
+            return collectionStub;
+          };
+        }
+        return () => proxy;
+      }
+    }
+  );
+  configure(proxy);
+  const sorted = [...recorded].sort((a, b) => a.name.localeCompare(b.name));
+  const indexes = {};
+  const persistJsonSchema = [];
+  for (const c of sorted) {
+    indexes[c.name] = c.indexes;
+    if (c.persistJsonSchema) persistJsonSchema.push(c.name);
+  }
+  return {
+    // `persistJsonSchema` is already name-sorted: it is populated while
+    // iterating `sorted` (collections in name order).
+    collections: sorted.map((c) => c.name),
+    indexes,
+    persistJsonSchema
+  };
+}
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  const obj = value;
+  const keys = Object.keys(obj).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(",")}}`;
+}
+async function fingerprintBlueprint(bp) {
+  return sha256Hex2(new TextEncoder().encode(canonical(bp)));
+}
+var init_schema_manifest = __esm({
+  "src/federation/schema-manifest.ts"() {
+    "use strict";
+    init_crypto();
+  }
+});
+
+// src/federation/state-vault.ts
+var state_vault_exports = {};
+__export(state_vault_exports, {
+  STATE_VAULT_NAME: () => STATE_VAULT_NAME,
+  StateManagementVault: () => StateManagementVault
+});
+var REGISTRY, MANIFEST, EVENTS, StateManagementVault;
+var init_state_vault = __esm({
+  "src/federation/state-vault.ts"() {
+    "use strict";
+    init_schema_manifest();
+    init_constants2();
+    init_ulid();
+    init_constants2();
+    REGISTRY = "vaultRegistry";
+    MANIFEST = "schemaManifest";
+    EVENTS = "deploymentEvents";
+    StateManagementVault = class _StateManagementVault {
+      constructor(registry, schemaManifest, events) {
+        this.registry = registry;
+        this.schemaManifest = schemaManifest;
+        this.#events = events;
+      }
+      registry;
+      schemaManifest;
+      /**
+       * The append-only deployment-events log is kept truly private so the raw
+       * mutable Collection is never surfaced — events may only be written via
+       * `appendEvent` and read via `queryEvents`. (`registry` and
+       * `schemaManifest` are deliberately public: consumers read and write them.)
+       */
+      #events;
+      /** Idempotently open the reserved state vault and bind the three control-plane collections. */
+      static async open(db) {
+        const vault = await db.openVault(STATE_VAULT_NAME);
+        return new _StateManagementVault(
+          vault.collection(REGISTRY),
+          vault.collection(MANIFEST),
+          vault.collection(EVENTS)
+        );
+      }
+      /** Read-only query over the append-only deployment-events log. */
+      queryEvents() {
+        return this.#events.query();
+      }
+      /**
+       * Append a deployment event with a fresh unique (ULID) id. This is the
+       * only write path to the events log; no update/delete is exposed.
+       * Callers should treat failures as non-fatal — this method does not
+       * swallow errors, so wrap the call site in try/catch where appropriate.
+       */
+      async appendEvent(event) {
+        const ts = event.ts ?? Date.now();
+        const id = generateULID();
+        await this.#events.put(id, { ...event, id, ts });
+      }
+      /**
+       * Ensure a manifest row exists for `(templateName, template.version)`.
+       * Safe to call repeatedly: the `fingerprint` is a deterministic hash of
+       * the template's declared shape (stable across calls), though each call
+       * refreshes `recordedAt`.
+       */
+      async recordManifest(templateName, template) {
+        const bp = captureBlueprint(template.configure);
+        const fingerprint = await fingerprintBlueprint(bp);
+        await this.schemaManifest.put(`${templateName}:${template.version}`, {
+          templateName,
+          version: template.version,
+          collections: bp.collections,
+          indexes: bp.indexes,
+          persistJsonSchema: bp.persistJsonSchema,
+          fingerprint,
+          recordedAt: Date.now()
+        });
+        return fingerprint;
+      }
+      /**
+       * True when `template`'s current declared shape does not match the recorded
+       * manifest for `(templateName, template.version)`. Because shards carry no
+       * schema state independent of their template, this catches "a template's
+       * shape changed without bumping `version`" — not independent per-shard drift.
+       * A missing manifest is treated as drift (nothing to verify against).
+       */
+      async detectDrift(templateName, template) {
+        const row = await this.schemaManifest.get(`${templateName}:${template.version}`);
+        if (!row) return true;
+        const current = await fingerprintBlueprint(captureBlueprint(template.configure));
+        return current !== row.fingerprint;
+      }
+    };
+  }
+});
+
 // src/noydb.ts
 var noydb_exports = {};
 __export(noydb_exports, {
@@ -17428,6 +18039,7 @@ var init_noydb = __esm({
   "src/noydb.ts"() {
     "use strict";
     init_errors();
+    init_constants2();
     init_storage3();
     init_rotate_recover();
     init_peer_recover();
@@ -17767,6 +18379,7 @@ var init_noydb = __esm({
           ...this.options.i18nStrategy !== void 0 ? { i18nStrategy: this.options.i18nStrategy } : {},
           ...this.options.syncStrategy !== void 0 ? { syncStrategy: this.options.syncStrategy } : {},
           ...this.options.guardStrategies !== void 0 ? { guardStrategies: this.options.guardStrategies } : {},
+          ...this.options.numbering !== void 0 ? { numberingConfigs: this.options.numbering } : {},
           locale: opts?.locale,
           // Thread the translator hook so Collection.put() can invoke it
           plaintextTranslator: this.options.plaintextTranslator ? (text, from, to, field, collection) => this.invokeTranslator(text, from, to, field, collection) : void 0,
@@ -17820,7 +18433,8 @@ var init_noydb = __esm({
             ...this.options.historyStrategy !== void 0 ? { historyStrategy: this.options.historyStrategy } : {},
             ...this.options.i18nStrategy !== void 0 ? { i18nStrategy: this.options.i18nStrategy } : {},
             ...this.options.syncStrategy !== void 0 ? { syncStrategy: this.options.syncStrategy } : {},
-            ...this.options.guardStrategies !== void 0 ? { guardStrategies: this.options.guardStrategies } : {}
+            ...this.options.guardStrategies !== void 0 ? { guardStrategies: this.options.guardStrategies } : {},
+            ...this.options.numbering !== void 0 ? { numberingConfigs: this.options.numbering } : {}
           });
           this.vaultCache.set(name, comp2);
           return comp2;
@@ -17850,6 +18464,7 @@ var init_noydb = __esm({
           ...this.options.i18nStrategy !== void 0 ? { i18nStrategy: this.options.i18nStrategy } : {},
           ...this.options.syncStrategy !== void 0 ? { syncStrategy: this.options.syncStrategy } : {},
           ...this.options.guardStrategies !== void 0 ? { guardStrategies: this.options.guardStrategies } : {},
+          ...this.options.numbering !== void 0 ? { numberingConfigs: this.options.numbering } : {},
           emitter: this.emitter
         });
         this.vaultCache.set(name, comp);
@@ -18168,10 +18783,39 @@ var init_noydb = __esm({
        */
       async openVaultGroup(name, opts) {
         if (this.closed) throw new ValidationError("Instance is closed");
+        if (name === STATE_VAULT_NAME) throw new ReservedVaultNameError(name);
         const template = this.vaultTemplates.get(opts.sharding.vaultTemplate);
         if (!template) throw new VaultTemplateNotFoundError(opts.sharding.vaultTemplate);
         const { VaultGroup: VaultGroup2 } = await Promise.resolve().then(() => (init_vault_group(), vault_group_exports));
-        return new VaultGroup2(this, name, opts.registry, opts.sharding, template);
+        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);
+        if (stateVault) {
+          group._attachStateVault(stateVault);
+          await stateVault.recordManifest(opts.sharding.vaultTemplate, template);
+          try {
+            await stateVault.appendEvent({
+              type: "manifest-recorded",
+              group: name,
+              templateName: opts.sharding.vaultTemplate,
+              version: template.version
+            });
+            await stateVault.appendEvent({ type: "group-opened", group: name });
+          } catch {
+          }
+        }
+        return group;
+      }
+      /**
+       * Open the reserved StateManagement control-plane vault (registry +
+       * schema-manifest + deployment-events). Lazy-loaded so the federation
+       * chunk stays out of the core graph until used.
+       */
+      async openStateManagementVault() {
+        if (this.closed) throw new ValidationError("Instance is closed");
+        const { StateManagementVault: StateManagementVault2 } = await Promise.resolve().then(() => (init_state_vault(), state_vault_exports));
+        return StateManagementVault2.open(this);
       }
       /**
        * @internal — true when an encrypted shard vault is provisioned