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

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, PeriodClosedError, RecordLockedError, FieldFrozenError, InvariantError, AmendmentForbiddenError, DirectoryDisabledError, TierNotGrantedError, ElevationExpiredError, AlreadyElevatedError, TierDemoteDeniedError, DelegationTargetMissingError, ConflictError, LedgerContentionError, SequenceContentionError, SequenceOfflineError, BundleVersionConflictError, NetworkError, NotFoundError, ValidationError, SchemaValidationError, SchemaUpdateError, NonAdditiveSchemaChangeError, SchemaLockedError, SchemaFenceError, MigrationRequiredError, QuiesceTimeoutError, GroupCardinalityError, IndexRequiredError, UniqueConstraintError, UnsupportedIndexOptionError, IndexWriteFailureError, BundleIntegrityError, BundleSealMismatchError, ReservedCollectionNameError, DictKeyMissingError, DictKeyInUseError, MissingTranslationError, LocaleNotSpecifiedError, ScriptViolationError, 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, VaultTemplateNotFoundError;
+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, 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, VaultTemplateNotFoundError;
 var init_errors = __esm({
   "src/errors.ts"() {
     "use strict";
@@ -188,6 +188,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;
+      }
+    };
     PeriodClosedError = class extends NoydbError {
       periodName;
       endDate;
@@ -362,6 +374,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;
@@ -1255,6 +1278,15 @@ var init_crypto = __esm({
   }
 });
 
+// src/federation/constants.ts
+var STATE_VAULT_NAME;
+var init_constants = __esm({
+  "src/federation/constants.ts"() {
+    "use strict";
+    STATE_VAULT_NAME = "__noydb_state__";
+  }
+});
+
 // src/meta/public-envelope/schema.ts
 function validatePublicEnvelopeInput(input, schema) {
   const allowed = new Set(schema.fields);
@@ -1719,7 +1751,7 @@ var init_patch = __esm({
 
 // src/history/ledger/constants.ts
 var LEDGER_COLLECTION, LEDGER_DELTAS_COLLECTION;
-var init_constants = __esm({
+var init_constants2 = __esm({
   "src/history/ledger/constants.ts"() {
     "use strict";
     LEDGER_COLLECTION = "_ledger";
@@ -1754,7 +1786,7 @@ var init_store = __esm({
     init_errors();
     init_entry();
     init_patch();
-    init_constants();
+    init_constants2();
     init_hash();
     MAX_APPEND_ATTEMPTS = 8;
     LedgerStore = class {
@@ -2330,10 +2362,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);
@@ -3466,12 +3498,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("");
 }
@@ -4310,12 +4342,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("");
 }
@@ -4794,6 +4826,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.`
@@ -4810,6 +4845,7 @@ var init_vault_group = __esm({
   "src/federation/vault-group.ts"() {
     "use strict";
     init_errors();
+    init_constants();
     init_classify_skip();
     init_cross_vault_live();
     init_aggregate_across();
@@ -4833,15 +4869,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) {
@@ -4859,19 +4918,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;
       }
       /**
@@ -4881,7 +4953,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);
@@ -4920,7 +4992,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) {
@@ -5046,6 +5118,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 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, {
@@ -5150,6 +5375,7 @@ __export(src_exports, {
   NotFoundError: () => NotFoundError,
   Noydb: () => Noydb,
   NoydbError: () => NoydbError,
+  NumberingUncertaintyError: () => NumberingUncertaintyError,
   OverlayBaseIsVirtualError: () => OverlayBaseIsVirtualError,
   OverlayCollectionUnavailableError: () => OverlayCollectionUnavailableError,
   OverlayIdMismatchError: () => OverlayIdMismatchError,
@@ -5179,8 +5405,10 @@ __export(src_exports, {
   RefRegistry: () => RefRegistry,
   RefScopeError: () => RefScopeError,
   ReservedCollectionNameError: () => ReservedCollectionNameError,
+  ReservedVaultNameError: () => ReservedVaultNameError,
   SCHEMAS_COLLECTION: () => SCHEMAS_COLLECTION,
   SEALED_PASSPHRASE_RECORD_ID: () => SEALED_PASSPHRASE_RECORD_ID,
+  STATE_VAULT_NAME: () => STATE_VAULT_NAME,
   STRICT_POLICY: () => STRICT_POLICY,
   SYNC_CREDENTIALS_COLLECTION: () => SYNC_CREDENTIALS_COLLECTION,
   ScanBuilder: () => ScanBuilder,
@@ -5392,6 +5620,7 @@ __export(src_exports, {
   withArchive: () => withArchive,
   withCache: () => withCache,
   withCircuitBreaker: () => withCircuitBreaker,
+  withDeferredNumbering: () => withDeferredNumbering,
   withDerivation: () => withDerivation,
   withGuard: () => withGuard,
   withHealthCheck: () => withHealthCheck,
@@ -7543,8 +7772,20 @@ var SequenceStore = class {
   }
 };
 
+// src/numbering/descriptor.ts
+function withDeferredNumbering(config) {
+  return {
+    series: config.series,
+    collection: config.collection,
+    field: config.field,
+    settleWindowMs: config.settleWindowMs ?? 0
+  };
+}
+
 // src/index.ts
 init_errors();
+init_constants();
+init_errors();
 
 // src/bundle/format.ts
 var NOYDB_BUNDLE_MAGIC = new Uint8Array([78, 68, 66, 49]);
@@ -8351,8 +8592,8 @@ async function derivePersistedSchema(validator) {
   if (kind === "Zod") {
     const convert = await loadZodConverter();
     const jsonSchema = convert(validator);
-    const canonical = canonicalize(jsonSchema);
-    const hash = await sha256Hex(new TextEncoder().encode(canonical));
+    const canonical2 = canonicalize(jsonSchema);
+    const hash = await sha256Hex(new TextEncoder().encode(canonical2));
     return { _noydb_schema: 1, kind, jsonSchema, hash, derivedAt };
   }
   return {
@@ -10983,6 +11224,7 @@ init_errors();
 
 // src/noydb.ts
 init_errors();
+init_constants();
 init_ulid();
 init_public_envelope();
 
@@ -12009,7 +12251,7 @@ var Query = class _Query {
    * 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(
@@ -12018,6 +12260,23 @@ var Query = class _Query {
     }
     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();
@@ -12502,7 +12761,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()) {
@@ -12513,8 +12772,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");
 }
@@ -12820,12 +13079,29 @@ var ScanBuilder = class _ScanBuilder {
    * 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
@@ -12847,7 +13123,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       [...this.clauses, clause],
       this.joins,
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -12866,7 +13143,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       [...this.clauses, clause],
       this.joins,
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -12977,7 +13255,8 @@ var ScanBuilder = class _ScanBuilder {
       this.pageSize,
       this.clauses,
       [...this.joins, leg],
-      this.joinContext
+      this.joinContext,
+      this.moneyFields
     );
   }
   /**
@@ -12994,10 +13273,11 @@ var ScanBuilder = class _ScanBuilder {
     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);
           }
@@ -15332,9 +15612,17 @@ var Collection = class {
     }
     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
@@ -15840,7 +16128,8 @@ var Collection = class {
       pageSize,
       [],
       [],
-      joinContext
+      joinContext,
+      this.moneyFields
     );
   }
   /** Decrypt a page of envelopes returned by `adapter.listPage`. */
@@ -17064,7 +17353,165 @@ var OverlayedCollection = class {
 // src/vault.ts
 init_errors();
 init_errors();
-init_constants();
+
+// src/numbering/index.ts
+init_types();
+init_crypto();
+init_errors();
+var NUMBERING_HEAD_COLLECTION = "_numbering_head";
+var NUMBERING_PENDING_COLLECTION = "_numbering_pending";
+var 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, recordId3) {
+    return `${series}::${recordId3}`;
+  }
+  /** 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, recordId3) {
+    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 { env } = await this.readJson(NUMBERING_PENDING_COLLECTION, id);
+    const entry = {
+      series,
+      recordId: recordId3,
+      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/vault.ts
+init_constants2();
 init_entry();
 
 // src/shadow/strategy.ts
@@ -18495,6 +18942,10 @@ var Vault = class {
   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 })`
@@ -18581,6 +19032,7 @@ var Vault = class {
   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;
@@ -19255,6 +19707,18 @@ var Vault = class {
    * ```
    */
   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,
@@ -19266,6 +19730,38 @@ var Vault = class {
     }
     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, recordId3, field, serial) => {
+          const coll = this.collection(collection);
+          const rec = await coll.get(recordId3);
+          if (!rec) return false;
+          await coll.put(recordId3, { ...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,
@@ -22329,6 +22825,7 @@ var Noydb = class {
       ...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,
@@ -22382,7 +22879,8 @@ var Noydb = class {
         ...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;
@@ -22412,6 +22910,7 @@ var Noydb = class {
       ...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);
@@ -22730,10 +23229,39 @@ var Noydb = class {
    */
   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
@@ -26074,6 +26602,7 @@ function shortJSON(value) {
   NotFoundError,
   Noydb,
   NoydbError,
+  NumberingUncertaintyError,
   OverlayBaseIsVirtualError,
   OverlayCollectionUnavailableError,
   OverlayIdMismatchError,
@@ -26103,8 +26632,10 @@ function shortJSON(value) {
   RefRegistry,
   RefScopeError,
   ReservedCollectionNameError,
+  ReservedVaultNameError,
   SCHEMAS_COLLECTION,
   SEALED_PASSPHRASE_RECORD_ID,
+  STATE_VAULT_NAME,
   STRICT_POLICY,
   SYNC_CREDENTIALS_COLLECTION,
   ScanBuilder,
@@ -26316,6 +26847,7 @@ function shortJSON(value) {
   withArchive,
   withCache,
   withCircuitBreaker,
+  withDeferredNumbering,
   withDerivation,
   withGuard,
   withHealthCheck,