@noy-db/hub 0.3.0-pre.9 → 0.4.0-pre.0

package/dist/chunk-JRBNCUNT.js

@@ -0,0 +1,371 @@
+import {
+  generateULID
+} from "./chunk-ZJADGNYF.js";
+import {
+  AmendmentForbiddenError,
+  ConflictError,
+  InvariantError,
+  ValidationError
+} from "./chunk-W2OG6JOL.js";
+
+// src/kernel/best-effort-revert.ts
+async function bestEffortRevert(executed, adapter, compensate) {
+  for (const leg of [...executed].reverse()) {
+    try {
+      if (leg.prior !== null) {
+        await adapter.put(leg.vaultName, leg.collectionName, leg.id, leg.prior);
+      } else {
+        await adapter.delete(leg.vaultName, leg.collectionName, leg.id);
+      }
+      if (compensate) await compensate(leg);
+    } catch {
+    }
+  }
+}
+
+// src/with-commit/tx/transaction.ts
+var TxContext = class {
+  /** Stable id for this transaction; shared by all writes it performs. */
+  txId = generateULID();
+  /** @internal */
+  _ops = [];
+  /**
+   * @internal — write log built up in Phase 2. Each entry records the
+   * envelope captured BEFORE the write so a mid-batch failure can
+   * restore prior state via `revertExecuted`. Side-effect writes (e.g.
+   * recursive derivation outputs fired inside `Collection.put`) are
+   * appended here in execution order so they roll back alongside the
+   * main staged ops.
+   */
+  _executed = [];
+  /** @internal */
+  _db;
+  /**
+   * @internal — true when this TxContext was opened in amendment
+   * mode. Toggles the lazy-`beginAmendment` + role-check path on first
+   * `tx.vault(name)` and unlocks the post-Phase-2 invariant + audit run.
+   */
+  _amendment;
+  /** @internal — vaults that have already had `beginAmendment` called. */
+  _amendmentVaults = /* @__PURE__ */ new Map();
+  /** @internal */
+  constructor(db, amendment = false) {
+    this._db = db;
+    this._amendment = amendment;
+  }
+  /** Scope subsequent `collection()` calls to the named vault. */
+  vault(name) {
+    const v = this._db.vault(name);
+    if (this._amendment && !this._amendmentVaults.has(name)) {
+      const role = v.role;
+      if (role !== "admin" && role !== "owner" && role !== "custodian") {
+        throw new AmendmentForbiddenError(v.userId, role);
+      }
+      const reg = v._getGuardRegistry();
+      if (reg === null) {
+        throw new ValidationError(
+          `Vault "${name}": amendment mode requires at least one guardStrategy registered via createNoydb({ guardStrategies }). Open the vault with guardStrategies before calling db.transaction({ amendment: true }).`
+        );
+      }
+      reg.beginAmendment();
+      this._amendmentVaults.set(name, v);
+    }
+    return new TxVault(this, v);
+  }
+};
+var TxVault = class {
+  /** @internal */
+  _ctx;
+  /** @internal */
+  _vault;
+  /** @internal */
+  constructor(ctx, vault) {
+    this._ctx = ctx;
+    this._vault = vault;
+  }
+  /** Scope subsequent op calls to the named collection. */
+  collection(name) {
+    const c = this._vault.collection(name);
+    return new TxCollection(this._ctx, this._vault, c, name);
+  }
+};
+var TxCollection = class {
+  /** @internal */
+  _ctx;
+  /** @internal */
+  _vault;
+  /** @internal */
+  _coll;
+  /** @internal */
+  _name;
+  /** @internal */
+  constructor(ctx, vault, coll, name) {
+    this._ctx = ctx;
+    this._vault = vault;
+    this._coll = coll;
+    this._name = name;
+  }
+  /**
+   * Read the current committed value, or the most-recently-staged
+   * value from the same transaction if one exists.
+   */
+  async get(id) {
+    for (let i = this._ctx._ops.length - 1; i >= 0; i--) {
+      const op = this._ctx._ops[i];
+      if (op.vaultName === this._vault.name && op.collectionName === this._name && op.id === id) {
+        if (op.type === "delete") return null;
+        return op.record;
+      }
+    }
+    return this._coll.get(id);
+  }
+  /**
+   * Stage a put. Does not write until the transaction body returns.
+   * Supply `{ expectedVersion }` to enforce optimistic concurrency
+   * during the commit pre-flight.
+   */
+  put(id, record, options) {
+    const op = {
+      type: "put",
+      vaultName: this._vault.name,
+      collectionName: this._name,
+      id,
+      record
+    };
+    if (options?.expectedVersion !== void 0) op.expectedVersion = options.expectedVersion;
+    if (options?.reason !== void 0) op.reason = options.reason;
+    this._ctx._ops.push(op);
+  }
+  /**
+   * Stage a delete. Does not write until the transaction body returns.
+   * Supply `{ expectedVersion }` to enforce optimistic concurrency
+   * during the commit pre-flight.
+   */
+  delete(id, options) {
+    const op = {
+      type: "delete",
+      vaultName: this._vault.name,
+      collectionName: this._name,
+      id
+    };
+    if (options?.expectedVersion !== void 0) op.expectedVersion = options.expectedVersion;
+    this._ctx._ops.push(op);
+  }
+};
+async function runTransaction(db, fn, options, txInvariants) {
+  if (options?.amendment) {
+    if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
+      throw new ValidationError(
+        "db.transaction({ amendment: true }) requires a non-empty `reason` string."
+      );
+    }
+  }
+  const ctx = new TxContext(db, options?.amendment === true);
+  const bodyResult = await fn(ctx);
+  if (ctx._ops.length === 0) {
+    if (ctx._amendment) {
+      for (const v of ctx._amendmentVaults.values()) {
+        const reg = v._getGuardRegistry();
+        if (reg !== null) {
+          reg.consumeChanges();
+          reg.consumeMeta();
+        }
+      }
+    }
+    return bodyResult;
+  }
+  const priorEnvelopes = /* @__PURE__ */ new Map();
+  const store = db._store;
+  const invariants = txInvariants ?? [];
+  const watchedScopes = new Set(invariants.map((i) => i.scope));
+  const plainBefore = /* @__PURE__ */ new Map();
+  for (const op of ctx._ops) {
+    const key = keyOf(op);
+    if (!priorEnvelopes.has(key)) {
+      const env = await store.get(op.vaultName, op.collectionName, op.id);
+      priorEnvelopes.set(key, env);
+    }
+    if (watchedScopes.has(op.collectionName) && !plainBefore.has(key)) {
+      const prior = await db.vault(op.vaultName).collection(op.collectionName).get(op.id);
+      plainBefore.set(key, prior ?? null);
+    }
+    if (op.expectedVersion !== void 0) {
+      const env = priorEnvelopes.get(key) ?? null;
+      const actual = env?._v ?? 0;
+      if (actual !== op.expectedVersion) {
+        throw new ConflictError(
+          actual,
+          `Transaction pre-flight: ${op.vaultName}/${op.collectionName}/${op.id} expected v${op.expectedVersion}, found v${actual}`
+        );
+      }
+    }
+  }
+  db._setActiveTxContext(ctx);
+  try {
+    try {
+      for (const op of ctx._ops) {
+        const coll = db.vault(op.vaultName).collection(op.collectionName);
+        const key = keyOf(op);
+        const prior = priorEnvelopes.get(key) ?? null;
+        ctx._executed.push({ op, priorEnvelope: prior });
+        if (op.type === "put") {
+          await coll.put(op.id, op.record, op.reason !== void 0 ? { reason: op.reason } : void 0);
+        } else {
+          await coll.delete(op.id);
+        }
+      }
+    } catch (err) {
+      await revertExecuted(ctx._executed, store, db);
+      if (ctx._amendment) {
+        for (const v of ctx._amendmentVaults.values()) {
+          const reg = v._getGuardRegistry();
+          if (reg !== null) {
+            reg.consumeChanges();
+            reg.consumeMeta();
+          }
+        }
+      }
+      throw err;
+    }
+  } finally {
+    db._clearActiveTxContext(ctx);
+  }
+  if (ctx._amendment) {
+    const { GuardExecutor } = await import("./executor-KGNLJD6M.js");
+    try {
+      for (const [vaultName, v] of ctx._amendmentVaults) {
+        const registry = v._getGuardRegistry();
+        if (registry === null) continue;
+        const changesByCollection = registry.consumeChanges();
+        const meta = registry.consumeMeta();
+        if (changesByCollection.size === 0) continue;
+        const readOnlyVault = v._getReadOnlyFacade();
+        if (readOnlyVault === null) continue;
+        const invariantsPassed = [];
+        for (const [collection, changes] of changesByCollection) {
+          const guards = registry.guardsFor(collection).filter((g) => g.amendment !== void 0);
+          for (const guard of guards) {
+            await GuardExecutor.runInvariant(guard, changes, {
+              existing: null,
+              vault: readOnlyVault,
+              userId: v.userId,
+              role: v.role
+            });
+          }
+          if (guards.length > 0) invariantsPassed.push(collection);
+        }
+        const ledger = v._getLedgerOrNull();
+        if (ledger) {
+          const role = v.role;
+          const amendment = {
+            reason: options.reason,
+            role,
+            changes: meta,
+            invariantsPassed
+          };
+          await ledger.append({
+            op: "amendment",
+            collection: "",
+            id: "",
+            version: 0,
+            actor: v.userId,
+            // No payload to hash — the per-record entries already
+            // captured `payloadHash` at their own append time. We use
+            // a sha256 of the canonical reason string so the field is
+            // populated with something deterministic and non-empty.
+            payloadHash: "",
+            amendment
+          });
+        }
+        void vaultName;
+      }
+    } catch (err) {
+      await revertExecuted(ctx._executed, store, db);
+      throw err instanceof InvariantError ? err : new InvariantError(
+        err instanceof Error ? err.message : `invariant violated: ${String(err)}`
+      );
+    }
+  }
+  if (invariants.length > 0) {
+    const lastOp = /* @__PURE__ */ new Map();
+    const order = [];
+    for (const op of ctx._ops) {
+      const key = keyOf(op);
+      if (!lastOp.has(key)) order.push(key);
+      lastOp.set(key, op);
+    }
+    const changesByScope = /* @__PURE__ */ new Map();
+    const scopeVault = /* @__PURE__ */ new Map();
+    for (const key of order) {
+      const op = lastOp.get(key);
+      if (!watchedScopes.has(op.collectionName)) continue;
+      const before = plainBefore.get(key) ?? null;
+      const after = op.type === "delete" ? null : op.record ?? null;
+      const change = { before, after };
+      const arr = changesByScope.get(op.collectionName);
+      if (arr) arr.push(change);
+      else changesByScope.set(op.collectionName, [change]);
+      scopeVault.set(op.collectionName, op.vaultName);
+    }
+    try {
+      for (const inv of invariants) {
+        const changes = changesByScope.get(inv.scope);
+        if (changes === void 0 || changes.length === 0) continue;
+        const vaultName = scopeVault.get(inv.scope);
+        const v = db.vault(vaultName);
+        const facade = v._getReadOnlyFacade() ?? {
+          collection(name) {
+            const c = v.collection(name);
+            return {
+              get: (id) => c.get(id),
+              list: () => c.list(),
+              query: () => c.query()
+            };
+          }
+        };
+        const ctxForInv = {
+          existing: null,
+          vault: facade,
+          userId: v.userId,
+          role: v.role
+        };
+        await inv.check(changes, ctxForInv);
+      }
+    } catch (err) {
+      await revertExecuted(ctx._executed, store, db);
+      throw err instanceof InvariantError ? err : new InvariantError(
+        err instanceof Error ? err.message : `invariant violated: ${String(err)}`
+      );
+    }
+  }
+  return bodyResult;
+}
+async function revertExecuted(executed, store, db) {
+  const legs = executed.map(({ op, priorEnvelope }) => ({
+    vaultName: op.vaultName,
+    collectionName: op.collectionName,
+    id: op.id,
+    prior: priorEnvelope
+  }));
+  await bestEffortRevert(
+    legs,
+    store,
+    db ? async (leg) => {
+      const coll = db.vault(leg.vaultName).collection(leg.collectionName);
+      await coll._invalidateCacheEntry(leg.id);
+    } : void 0
+  );
+}
+function keyOf(op) {
+  return `${op.vaultName}\0${op.collectionName}\0${op.id}`;
+}
+
+export {
+  bestEffortRevert,
+  TxContext,
+  TxVault,
+  TxCollection,
+  runTransaction,
+  revertExecuted
+};
+//# sourceMappingURL=chunk-JRBNCUNT.js.map

package/dist/chunk-JRBNCUNT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kernel/best-effort-revert.ts","../src/with-commit/tx/transaction.ts"],"sourcesContent":["/**\n * Best-effort reverse-revert — the shape shared by two independent rollback\n * paths that used to duplicate it: satellite fan-out\n * (`with-shape/satellites/fanout.ts`'s `revertAndCompensate`) and\n * multi-record transactions (`with-commit/tx/transaction.ts`'s\n * `revertExecuted`). Both revert a list of already-executed writes on\n * failure by walking them in REVERSE order and, per leg, restoring the\n * captured prior envelope straight through the raw adapter — `put(prior)`\n * when one existed, `delete` when the leg was a fresh insert — bypassing\n * the Collection layer so the revert itself doesn't re-fire\n * encryption/ledger/change-event machinery. Each leg's raw-adapter revert\n * is best-effort: a throw is swallowed so a revert-path failure never masks\n * the original error that triggered the rollback, and the loop moves on to\n * the next leg.\n *\n * An optional per-leg `compensate` callback runs immediately after a\n * successful raw-adapter revert (still inside the same try, so a throwing\n * callback is swallowed the same way as a throwing raw revert). What the\n * callback does is entirely caller-defined — satellites' fan-out fires\n * `_compensateRevertedWrite` only for legs whose write actually landed\n * (#596); with-commit's transaction executor invalidates the Collection\n * cache. Neither concern belongs here: this helper only knows the generic\n * reverse/best-effort/raw-revert shape.\n *\n * Lives in `kernel/` — not a `with-*` service — so both consumers (one a\n * gated service, `with-commit`; one an always-on schema feature,\n * `with-shape/satellites`) can import it without creating a\n * `with-* → with-*` edge, which would force either family to always bundle\n * the other and defeat the opt-in tree-shaking both are built around.\n *\n * @internal — implementation-sharing only, not part of the public surface.\n */\nimport type { EncryptedEnvelope } from './types.js'\n\n/** One already-executed write a revert pass needs to unwind. */\nexport interface BestEffortRevertLeg {\n  readonly vaultName: string\n  readonly collectionName: string\n  readonly id: string\n  /** Envelope captured before the write, or `null` if the id didn't exist yet. */\n  readonly prior: EncryptedEnvelope | null\n}\n\n/** The subset of `NoydbStore` a raw-adapter revert needs. */\nexport interface BestEffortRevertAdapter {\n  put(vaultName: string, collectionName: string, id: string, envelope: EncryptedEnvelope): Promise<void>\n  delete(vaultName: string, collectionName: string, id: string): Promise<void>\n}\n\n/**\n * Revert `executed` in reverse order via the raw adapter, best-effort.\n * `compensate`, when supplied, runs once per leg immediately after that\n * leg's own raw revert succeeds.\n */\nexport async function bestEffortRevert<T extends BestEffortRevertLeg>(\n  executed: readonly T[],\n  adapter: BestEffortRevertAdapter,\n  compensate?: (leg: T) => Promise<void> | void,\n): Promise<void> {\n  for (const leg of [...executed].reverse()) {\n    try {\n      if (leg.prior !== null) {\n        await adapter.put(leg.vaultName, leg.collectionName, leg.id, leg.prior)\n      } else {\n        await adapter.delete(leg.vaultName, leg.collectionName, leg.id)\n      }\n      if (compensate) await compensate(leg)\n    } catch {\n      // best-effort — a revert-path failure must not mask the original\n      // error that triggered the rollback (matches both callers' prior\n      // independent implementations).\n    }\n  }\n}\n","/**\n * Multi-record atomic transactions.\n *\n * Lets an application stage writes across two or more collections (or\n * vaults) and commit them all-or-nothing.\n *\n * ```ts\n * await db.transaction(async (tx) => {\n *   const inv = tx.vault('acme').collection<Invoice>('invoices')\n *   const pay = tx.vault('acme').collection<Payment>('payments')\n *   await inv.put(invoiceId, { ...invoice, status: 'paid' })\n *   await pay.put(paymentId, { invoiceId, amount, paidAt })\n * })\n * // If the body throws before returning: nothing persisted.\n * // If the body returns: all puts committed; any CAS mismatch rolls\n * // the batch back and surfaces as ConflictError.\n * ```\n *\n * ## Atomicity semantics\n *\n * Ops are buffered during the body. On body-return the hub:\n *\n * 1. **Pre-flight** — re-reads every touched envelope and enforces\n *    any caller-supplied `expectedVersion`. A mismatch throws\n *    `ConflictError` with *no* writes performed.\n * 2. **Execute** — calls `Collection.put()` / `.delete()` for each\n *    staged op in declaration order. History snapshots, ledger\n *    appends, and change events fire as normal per op.\n * 3. **Unwind on failure** — if step 2 throws mid-batch, each\n *    already-committed op is reverted via the raw store (restoring\n *    the captured prior envelope, or deleting if none existed). The\n *    ledger is NOT rewritten — audit history preserves the partial\n *    commit and the revert.\n *\n * **Crash window.** Steps 2–3 are not a storage-layer transaction —\n * if the process dies between two executed ops, the on-disk state is\n * partial. True all-or-nothing atomicity requires a store that\n * implements `NoydbStore.tx()` (DynamoDB `TransactWriteItems`,\n * IndexedDB `readwrite` transaction, …). This executor declares\n * that future integration point via the `tx?()` method + the\n * `StoreCapabilities.txAtomic` bit, but does not yet delegate\n * to it — the cascade into `Fork · Stores` tracks the per-adapter\n * wire-up.\n *\n * ## Not covered\n *\n * - Cross-sync-peer atomicity. Transactions commit against the\n *   primary store only; the sync engine pushes on its normal\n *   schedule. For cross-peer two-phase commit use `SyncTransaction`\n * via `db.transaction(vaultName)`.\n * - Read-your-writes within the body. `tx.collection().get(id)`\n *   returns the most-recently-staged value for that id when one\n *   exists; if no staged op has touched the id, it reads the current\n *   committed state. Version numbers returned by `get` reflect the\n *   pre-transaction state (staged puts have no version yet).\n *\n * @module\n */\n\nimport type { Noydb } from '../../kernel/noydb.js'\nimport type { Vault } from '../../kernel/vault.js'\nimport type { Collection } from '../../kernel/collection.js'\nimport type { EncryptedEnvelope } from '../../kernel/types.js'\nimport {\n  AmendmentForbiddenError,\n  ConflictError,\n  InvariantError,\n  ValidationError,\n} from '../../kernel/errors.js'\nimport { generateULID } from '../../with-pod/ulid.js'\nimport type { GuardExecutor as GuardExecutorModule } from '../../with-audit/guards/executor.js'\nimport type { LedgerEntry } from '../history/ledger/entry.js'\nimport type { TransactionInvariant } from './invariants.js'\nimport type { GuardChange, GuardContext, ReadOnlyVaultFacade } from '../../with-audit/guards/types.js'\nimport { bestEffortRevert } from '../../kernel/best-effort-revert.js'\n\n/** One op buffered inside a running `TxContext`. @internal */\nexport interface StagedOp {\n  type: 'put' | 'delete'\n  vaultName: string\n  collectionName: string\n  id: string\n  record?: unknown\n  expectedVersion?: number\n  /**\n   * Optional human-readable tag forwarded to the resulting ledger\n   * entry's `reason` field. Set by callers via\n   * `tx.vault(v).collection(c).put(id, record, { reason })`.\n   */\n  reason?: string\n}\n\n/**\n * One executed op (main staged op or recursive side-effect like a\n * derivation output) paired with the envelope captured before the write.\n * `revertExecuted` walks this array in reverse on rollback.\n * @internal\n */\nexport interface ExecutedOp {\n  op: StagedOp\n  priorEnvelope: EncryptedEnvelope | null\n}\n\n/**\n * Options accepted by `db.transaction({ amendment, reason }, fn)`.\n * Only the amendment variant uses these — a plain `db.transaction(fn)`\n * never sees this shape.\n */\nexport interface AmendmentTxOptions {\n  /** Opt into amendment mode. Required to be `true`. */\n  readonly amendment: true\n  /** Human-readable rationale recorded in the ledger entry. Required. */\n  readonly reason: string\n}\n\n/**\n * Transaction handle passed to the user's body. Use\n * `tx.vault(name).collection<T>(name)` to get a per-collection\n * facade; its `put`/`delete`/`get` calls stage ops against the tx.\n */\nexport class TxContext {\n  /** Stable id for this transaction; shared by all writes it performs. */\n  readonly txId: string = generateULID()\n  /** @internal */\n  readonly _ops: StagedOp[] = []\n  /**\n   * @internal — write log built up in Phase 2. Each entry records the\n   * envelope captured BEFORE the write so a mid-batch failure can\n   * restore prior state via `revertExecuted`. Side-effect writes (e.g.\n   * recursive derivation outputs fired inside `Collection.put`) are\n   * appended here in execution order so they roll back alongside the\n   * main staged ops.\n   */\n  readonly _executed: ExecutedOp[] = []\n  /** @internal */\n  readonly _db: Noydb\n  /**\n   * @internal — true when this TxContext was opened in amendment\n   * mode. Toggles the lazy-`beginAmendment` + role-check path on first\n   * `tx.vault(name)` and unlocks the post-Phase-2 invariant + audit run.\n   */\n  readonly _amendment: boolean\n  /** @internal — vaults that have already had `beginAmendment` called. */\n  readonly _amendmentVaults = new Map<string, Vault>()\n\n  /** @internal */\n  constructor(db: Noydb, amendment = false) {\n    this._db = db\n    this._amendment = amendment\n  }\n\n  /** Scope subsequent `collection()` calls to the named vault. */\n  vault(name: string): TxVault {\n    const v = this._db.vault(name)\n    if (this._amendment && !this._amendmentVaults.has(name)) {\n      // Role check is per-vault. The task spec (\"only admin or owner\n      // can open an amendment\") is implemented lazy-on-first-touch\n      // because the role lives on the vault's keyring, and `tx.vault()`\n      // is the first place we know which vault we're addressing. The\n      // observable effect is identical to an eager check in the single-\n      // vault case the tests exercise; multi-vault amendments check\n      // each touched vault as they first appear.\n      const role = v.role\n      // FR-6: custodian is admin-rank for operational mutations, and an\n      // amendment is an operational (data-correcting) act — not an ownership\n      // meta-capability — so custodian is allowed alongside owner/admin.\n      if (role !== 'admin' && role !== 'owner' && role !== 'custodian') {\n        throw new AmendmentForbiddenError(v.userId, role)\n      }\n      // Amendments require an initialised guard registry — they\n      // produce a structured invariant + change-set audit. A vault\n      // opened without `guardStrategies` (or via the sync fallback\n      // path) has a null registry and cannot run an amendment.\n      const reg = v._getGuardRegistry()\n      if (reg === null) {\n        throw new ValidationError(\n          `Vault \"${name}\": amendment mode requires at least one ` +\n          `guardStrategy registered via createNoydb({ guardStrategies }). ` +\n          `Open the vault with guardStrategies before calling ` +\n          `db.transaction({ amendment: true }).`,\n        )\n      }\n      reg.beginAmendment()\n      this._amendmentVaults.set(name, v)\n    }\n    return new TxVault(this, v)\n  }\n}\n\n/** Per-vault facade inside a running transaction. */\nexport class TxVault {\n  /** @internal */\n  readonly _ctx: TxContext\n  /** @internal */\n  readonly _vault: Vault\n\n  /** @internal */\n  constructor(ctx: TxContext, vault: Vault) {\n    this._ctx = ctx\n    this._vault = vault\n  }\n\n  /** Scope subsequent op calls to the named collection. */\n  collection<T>(name: string): TxCollection<T> {\n    const c = this._vault.collection<T>(name)\n    return new TxCollection<T>(this._ctx, this._vault, c, name)\n  }\n}\n\n/** Per-collection facade inside a running transaction. */\nexport class TxCollection<T> {\n  /** @internal */\n  readonly _ctx: TxContext\n  /** @internal */\n  readonly _vault: Vault\n  /** @internal */\n  readonly _coll: Collection<T>\n  /** @internal */\n  readonly _name: string\n\n  /** @internal */\n  constructor(ctx: TxContext, vault: Vault, coll: Collection<T>, name: string) {\n    this._ctx = ctx\n    this._vault = vault\n    this._coll = coll\n    this._name = name\n  }\n\n  /**\n   * Read the current committed value, or the most-recently-staged\n   * value from the same transaction if one exists.\n   */\n  async get(id: string): Promise<T | null> {\n    for (let i = this._ctx._ops.length - 1; i >= 0; i--) {\n      const op = this._ctx._ops[i]!\n      if (\n        op.vaultName === this._vault.name &&\n        op.collectionName === this._name &&\n        op.id === id\n      ) {\n        if (op.type === 'delete') return null\n        return op.record as T\n      }\n    }\n    return this._coll.get(id)\n  }\n\n  /**\n   * Stage a put. Does not write until the transaction body returns.\n   * Supply `{ expectedVersion }` to enforce optimistic concurrency\n   * during the commit pre-flight.\n   */\n  put(id: string, record: T, options?: { expectedVersion?: number; reason?: string }): void {\n    const op: StagedOp = {\n      type: 'put',\n      vaultName: this._vault.name,\n      collectionName: this._name,\n      id,\n      record,\n    }\n    if (options?.expectedVersion !== undefined) op.expectedVersion = options.expectedVersion\n    if (options?.reason !== undefined) op.reason = options.reason\n    this._ctx._ops.push(op)\n  }\n\n  /**\n   * Stage a delete. Does not write until the transaction body returns.\n   * Supply `{ expectedVersion }` to enforce optimistic concurrency\n   * during the commit pre-flight.\n   */\n  delete(id: string, options?: { expectedVersion?: number }): void {\n    const op: StagedOp = {\n      type: 'delete',\n      vaultName: this._vault.name,\n      collectionName: this._name,\n      id,\n    }\n    if (options?.expectedVersion !== undefined) op.expectedVersion = options.expectedVersion\n    this._ctx._ops.push(op)\n  }\n}\n\n/**\n * Commit plan: pre-flight check + execution + revert plan.\n *\n * @internal — driven by `withTransactions()` (via `tx/active.ts`) for\n * user-facing `db.transaction(...)` calls and by the `amendment` path\n * in `noydb.ts`. `Collection.putManyAtomic` runs its own Phase 2 loop\n * but shares the `_activeTxContext` mechanism (and the `revertExecuted`\n * helper) so nested side-effect derivation writes get registered for\n * revert alongside the bulk-put source ops.\n */\nexport async function runTransaction<T>(\n  db: Noydb,\n  fn: (tx: TxContext) => Promise<T> | T,\n  options?: AmendmentTxOptions,\n  txInvariants?: ReadonlyArray<TransactionInvariant>,\n): Promise<T> {\n  // ─── Amendment-mode pre-flight ───────────────────────────────\n  // `reason` is the only thing we can validate before the body runs;\n  // the per-vault role check happens lazily on first `tx.vault(name)`\n  // because we don't know which vaults the body will touch ahead of\n  // time. Throwing here keeps the failure mode close to the call site\n  // so the developer doesn't have to walk an async stack to find the\n  // missing-reason mistake.\n  if (options?.amendment) {\n    if (typeof options.reason !== 'string' || options.reason.trim().length === 0) {\n      throw new ValidationError(\n        'db.transaction({ amendment: true }) requires a non-empty `reason` string.',\n      )\n    }\n  }\n\n  const ctx = new TxContext(db, options?.amendment === true)\n  const bodyResult = await fn(ctx)\n\n  if (ctx._ops.length === 0) {\n    // Body produced no ops. If amendment mode was active we still\n    // need to close any opened windows so a subsequent (unrelated)\n    // write doesn't surprise-collect into a stale change-set. Each\n    // `beginAmendment` is matched by exactly one `consumeChanges`.\n    if (ctx._amendment) {\n      for (const v of ctx._amendmentVaults.values()) {\n        // Registry is guaranteed non-null here — `tx.vault(name)`\n        // threw above if it was null before adding to\n        // `_amendmentVaults`.\n        const reg = v._getGuardRegistry()\n        if (reg !== null) {\n          reg.consumeChanges()\n          reg.consumeMeta()\n        }\n      }\n    }\n    return bodyResult\n  }\n\n  // Phase 1 — pre-flight: snapshot every touched envelope and enforce\n  // any caller-supplied expectedVersion. Same (vault, coll, id) touched\n  // more than once in one tx snapshots only the *initial* committed\n  // state; the in-order replay in Phase 2 takes care of successor ops.\n  const priorEnvelopes = new Map<string, EncryptedEnvelope | null>()\n  const store = db._store\n\n  // Commit-time changeset invariants need PLAINTEXT prior records\n  // for `before`, but `priorEnvelopes` holds ENCRYPTED envelopes. So for\n  // ops in a watched scope we additionally decrypt the prior record here,\n  // in Phase 1, BEFORE Phase 2 overwrites it. Snapshots only the initial\n  // committed state per (vault, coll, id), matching the envelope snapshot.\n  const invariants = txInvariants ?? []\n  const watchedScopes = new Set(invariants.map(i => i.scope))\n  const plainBefore = new Map<string, unknown>()\n\n  for (const op of ctx._ops) {\n    const key = keyOf(op)\n    if (!priorEnvelopes.has(key)) {\n      const env = await store.get(op.vaultName, op.collectionName, op.id)\n      priorEnvelopes.set(key, env)\n    }\n    if (watchedScopes.has(op.collectionName) && !plainBefore.has(key)) {\n      const prior = await db\n        .vault(op.vaultName)\n        .collection(op.collectionName)\n        .get(op.id)\n      plainBefore.set(key, prior ?? null)\n    }\n    if (op.expectedVersion !== undefined) {\n      const env = priorEnvelopes.get(key) ?? null\n      const actual = env?._v ?? 0\n      if (actual !== op.expectedVersion) {\n        throw new ConflictError(\n          actual,\n          `Transaction pre-flight: ${op.vaultName}/${op.collectionName}/${op.id} ` +\n            `expected v${op.expectedVersion}, found v${actual}`,\n        )\n      }\n    }\n  }\n\n  // Phase 2 — execute via the Collection layer so history snapshots,\n  // ledger entries, and change events fire normally. We capture each\n  // successful op so a mid-batch throw can revert in Phase 3.\n  //\n  // `_activeTxContext` is published on the Noydb instance for the\n  // duration of Phase 2 so recursive writes triggered inside\n  // `Collection.put` (today: eager derivation outputs) can register\n  // their own envelopes onto `ctx._executed` and roll back alongside\n  // the main staged ops. The `finally` clears it before the\n  // amendment commit phase runs.\n  db._setActiveTxContext(ctx)\n  try {\n    try {\n      for (const op of ctx._ops) {\n        const coll = db.vault(op.vaultName).collection(op.collectionName)\n        const key = keyOf(op)\n        const prior = priorEnvelopes.get(key) ?? null\n        // Record the revert plan BEFORE the call so a mid-`coll.put` throw\n        // (e.g. strict-mode derivation failure firing after `store.put`\n        // has already committed the envelope) still has its source write\n        // reverted. `revertExecuted` is best-effort: putting prior back is\n        // idempotent when the failing op never actually wrote, and\n        // `_invalidateCacheEntry` is a no-op when the collection isn't\n        // hydrated.\n        ctx._executed.push({ op, priorEnvelope: prior })\n        if (op.type === 'put') {\n          // eslint-disable-next-line @typescript-eslint/no-explicit-any\n          await coll.put(op.id, op.record as any, op.reason !== undefined ? { reason: op.reason } : undefined)\n        } else {\n          await coll.delete(op.id)\n        }\n      }\n    } catch (err) {\n      // Phase 3 — best-effort revert. See helper docstring.\n      await revertExecuted(ctx._executed, store, db)\n      // Drain amendment windows so the next transaction starts clean.\n      if (ctx._amendment) {\n        for (const v of ctx._amendmentVaults.values()) {\n          const reg = v._getGuardRegistry()\n          if (reg !== null) {\n            reg.consumeChanges()\n            reg.consumeMeta()\n          }\n        }\n      }\n      throw err\n    }\n  } finally {\n    db._clearActiveTxContext(ctx)\n  }\n\n  // ─── Amendment commit phase (only if amendment === true) ────\n  // Body succeeded — now run each touched vault's invariants over the\n  // collected change-set, then append a structured ledger entry. If\n  // any invariant throws, treat it exactly like a mid-Phase-2 failure:\n  // revert every executed op and re-throw the InvariantError.\n  if (ctx._amendment) {\n    // Lazy-load GuardExecutor at the dispatch site — keeps the floor\n    // bundle free of the guards service when amendments aren't used.\n    // Mirrors the deferred-load pattern from elsewhere in this module.\n    const { GuardExecutor } = (await import('../../with-audit/guards/executor.js')) as {\n      GuardExecutor: typeof GuardExecutorModule\n    }\n    try {\n      for (const [vaultName, v] of ctx._amendmentVaults) {\n        const registry = v._getGuardRegistry()\n        // Registry is guaranteed non-null at this point — the\n        // `tx.vault(name)` path that populates `_amendmentVaults`\n        // throws if the registry is null. The defensive check here\n        // is for TypeScript's narrowing.\n        if (registry === null) continue\n        const changesByCollection = registry.consumeChanges()\n        const meta = registry.consumeMeta()\n        if (changesByCollection.size === 0) continue\n\n        const readOnlyVault = v._getReadOnlyFacade()\n        if (readOnlyVault === null) continue\n\n        // Build the invariant ctx once per vault — it's the same shape\n        // every guard sees on the normal `check` path, just with a\n        // synthetic `existing: null` (invariants get the full change\n        // set in their first parameter; `existing` is a per-record\n        // concept that doesn't apply here).\n        const invariantsPassed: string[] = []\n        for (const [collection, changes] of changesByCollection) {\n          const guards = registry.guardsFor(collection).filter(g => g.amendment !== undefined)\n          for (const guard of guards) {\n            await GuardExecutor.runInvariant(guard, changes, {\n              existing: null,\n              vault: readOnlyVault,\n              userId: v.userId,\n              role: v.role,\n            })\n          }\n          if (guards.length > 0) invariantsPassed.push(collection)\n        }\n\n        // Append the audit ledger entry. Silent no-op when the\n        // history strategy isn't configured — the records still\n        // committed, only the multi-record summary is unavailable.\n        const ledger = v._getLedgerOrNull()\n        if (ledger) {\n          const role = v.role as 'admin' | 'owner'\n          const amendment: NonNullable<LedgerEntry['amendment']> = {\n            reason: options!.reason,\n            role,\n            changes: meta,\n            invariantsPassed,\n          }\n          await ledger.append({\n            op: 'amendment',\n            collection: '',\n            id: '',\n            version: 0,\n            actor: v.userId,\n            // No payload to hash — the per-record entries already\n            // captured `payloadHash` at their own append time. We use\n            // a sha256 of the canonical reason string so the field is\n            // populated with something deterministic and non-empty.\n            payloadHash: '',\n            amendment,\n          })\n        }\n        void vaultName\n      }\n    } catch (err) {\n      await revertExecuted(ctx._executed, store, db)\n      throw err instanceof InvariantError ? err : new InvariantError(\n        err instanceof Error ? err.message : `invariant violated: ${String(err)}`,\n      )\n    }\n  }\n\n  // ─── Commit-time changeset invariant phase ───────────\n  // Runs for BOTH ordinary and amendment transactions (placed after the\n  // amendment phase so an amendment commit is still subject to these\n  // set-level constraints). Assemble the changeset from the executed\n  // staged ops, deduped to the LAST write per (vault, coll, id) while\n  // preserving write order, then group `GuardChange` by collection\n  // (scope) and run each matching invariant. A throw mirrors the\n  // amendment-phase failure mode exactly: revert every executed op and\n  // re-throw as `InvariantError`.\n  if (invariants.length > 0) {\n    // Dedup ctx._ops to the last write per key, preserving first-seen\n    // (write) order so the changeset is stable and order-meaningful.\n    const lastOp = new Map<string, StagedOp>()\n    const order: string[] = []\n    for (const op of ctx._ops) {\n      const key = keyOf(op)\n      if (!lastOp.has(key)) order.push(key)\n      lastOp.set(key, op)\n    }\n\n    // Group {before, after} pairs by collection name (the invariant\n    // scope). `before` is the plaintext prior captured in Phase 1 (null\n    // for inserts / unwatched — only watched scopes were captured, and\n    // every grouped key belongs to a watched scope). `after` is the\n    // written record, null for a delete.\n    const changesByScope = new Map<string, GuardChange<unknown>[]>()\n    // Parallel map: scope → the vault name of its (last-seen) op, used to\n    // build the per-invariant read-only ctx (facade + userId + role).\n    const scopeVault = new Map<string, string>()\n    for (const key of order) {\n      const op = lastOp.get(key)!\n      if (!watchedScopes.has(op.collectionName)) continue\n      const before = plainBefore.get(key) ?? null\n      const after = op.type === 'delete' ? null : (op.record ?? null)\n      const change = { before, after } as GuardChange<unknown>\n      const arr = changesByScope.get(op.collectionName)\n      if (arr) arr.push(change)\n      else changesByScope.set(op.collectionName, [change])\n\n      // Stash the vault name alongside so we can build a per-vault ctx.\n      // (All ops in a scope group could span vaults; we resolve the\n      // vault per change below via a parallel map keyed the same way.)\n      scopeVault.set(op.collectionName, op.vaultName)\n    }\n\n    try {\n      for (const inv of invariants) {\n        const changes = changesByScope.get(inv.scope)\n        if (changes === undefined || changes.length === 0) continue\n        const vaultName = scopeVault.get(inv.scope)!\n        const v = db.vault(vaultName)\n        // Prefer the real read-only facade so the invariant can read\n        // sibling collections; fall back to a minimal read-only stub.\n        const facade: ReadOnlyVaultFacade =\n          v._getReadOnlyFacade() ?? {\n            collection<R = unknown>(name: string) {\n              const c = v.collection<R>(name)\n              return {\n                get: (id: string) => c.get(id),\n                list: () => c.list(),\n                query: () => c.query(),\n              }\n            },\n          }\n        const ctxForInv: GuardContext<unknown> = {\n          existing: null,\n          vault: facade,\n          userId: v.userId,\n          role: v.role,\n        }\n        await inv.check(changes, ctxForInv)\n      }\n    } catch (err) {\n      await revertExecuted(ctx._executed, store, db)\n      throw err instanceof InvariantError ? err : new InvariantError(\n        err instanceof Error ? err.message : `invariant violated: ${String(err)}`,\n      )\n    }\n  }\n\n  return bodyResult\n}\n\n/**\n * Phase 3 helper — restore captured prior envelopes via the raw store\n * to avoid re-firing Collection-level side effects (we don't want a\n * cascade of change events undoing themselves). The ledger is left\n * as-is: each committed op appended an entry; the revert is\n * deliberately NOT recorded as a compensating entry because the\n * caller-facing contract is \"atomic or not at all,\" not \"every write\n * visible in the audit trail.\" Auditors who need the intermediate\n * state can still reconstruct it by walking the ledger through the\n * failed-tx timestamp.\n *\n * Delegates the reverse/best-effort/raw-revert shape to the shared\n * `bestEffortRevert` helper (`kernel/best-effort-revert.ts`); the cache\n * invalidation below rides along as that helper's per-leg `compensate`\n * callback, gated on `db` exactly as before.\n *\n * @internal — shared between `runTransaction` and\n * `Collection.putManyAtomic`. Both register source ops + nested\n * derivation side-effect ops onto `_executed`; this helper unwinds the\n * combined list in reverse on rollback.\n */\nexport async function revertExecuted(\n  executed: ReadonlyArray<ExecutedOp>,\n  store: Noydb['_store'],\n  db?: Noydb,\n): Promise<void> {\n  const legs = executed.map(({ op, priorEnvelope }) => ({\n    vaultName: op.vaultName,\n    collectionName: op.collectionName,\n    id: op.id,\n    prior: priorEnvelope,\n  }))\n  await bestEffortRevert(\n    legs,\n    store,\n    db\n      ? async (leg) => {\n          // Sync the Collection-layer cache with what we just wrote at\n          // the raw store. Without this, eager-mode `get` would still\n          // return the rolled-back record from its in-memory map. The\n          // Collection's `_invalidateCacheEntry` is a no-op when the\n          // collection hasn't yet been hydrated.\n          const coll = db.vault(leg.vaultName).collection(leg.collectionName)\n          // eslint-disable-next-line @typescript-eslint/no-explicit-any\n          await (coll as any)._invalidateCacheEntry(leg.id)\n        }\n      : undefined,\n  )\n}\n\nfunction keyOf(op: StagedOp): string {\n  return `${op.vaultName}\\x00${op.collectionName}\\x00${op.id}`\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-JVBO4SZL.js

@@ -0,0 +1,29 @@
+import {
+  NoydbError
+} from "./chunk-W2OG6JOL.js";
+
+// src/kernel/via/index.ts
+var binders = /* @__PURE__ */ new Map();
+function installViaBinder(brand, binder) {
+  if (!binders.has(brand)) binders.set(brand, binder);
+}
+function isViaInstalled(brand) {
+  return binders.has(brand);
+}
+function viaBinder(brand) {
+  const b = binders.get(brand);
+  if (!b) {
+    throw new NoydbError(
+      "VIA_NOT_LINKED",
+      `via feature "${brand}" requires descriptors created via its declaration factory from @noy-db/hub`
+    );
+  }
+  return b;
+}
+
+export {
+  installViaBinder,
+  isViaInstalled,
+  viaBinder
+};
+//# sourceMappingURL=chunk-JVBO4SZL.js.map

package/dist/chunk-JVBO4SZL.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/kernel/via/index.ts"],"sourcesContent":["// kernel/via/index.ts — the ONLY kernel-resident via surface.\nimport { NoydbError } from '../errors.js'\nimport type { EncryptedEnvelope } from '../types.js'\n\n/** Awaitable type for potentially async results. */\ntype Awaitable<T> = T | Promise<T>\n\n/** Declared security posture — a property the kernel enforces (enforcement activates in phases B/C). */\nexport interface ViaPosture {\n  readonly encryptedAtRest: 'envelope' | 'sealed'\n  readonly queryable: 'none' | 'det-exact' | 'ordered' | 'full'\n  readonly exportable: boolean\n  readonly forgettable: boolean\n}\n\n/** Opaque marker every feature descriptor extends; the kernel never sees concrete descriptor types. */\nexport interface ViaDescriptor { readonly _viaBrand: string }\n\n/** Per-call write context (A: minimal; B/C extend). */\nexport interface ViaWriteCtx {\n  readonly id: string\n  /** Owning vault name (event payload identity — e.g. i18n:script-violation). */\n  readonly vault: string\n  /** Prior stored record (decoded), lazily resolved. Null when creating. */\n  readonly prior: () => Promise<Record<string, unknown> | null>\n  /** Typed event emission (e.g. i18n:script-violation). */\n  readonly emit: (event: string, payload: unknown) => void\n}\n\n/** Per-call read context — mirrors LocaleReadOptions loosely; features narrow. */\nexport interface ViaReadCtx {\n  readonly locale?: unknown\n  readonly fallback?: unknown\n  readonly layer: string\n}\n\n/** One sealed slot's ciphertext — matches the existing `iv:data` sealed map entries (seam map §2 step 2). */\nexport interface SealedSlotRef { readonly iv: string; readonly data: string }\n\n/**\n * A scoped crypto capability handed to a `via` feature's `encodeAtRest`/\n * `decodeAtRest`/`erase` hooks — never the keyring, never the enclave.\n * `sealedSlots` is pre-bound to one `(collection, recordId)`; `reservedEnvelopes`\n * is a whole-envelope encrypt/decrypt door scoped to collection names under a\n * declared prefix (e.g. `_dict_`).\n */\nexport interface ViaCryptoCtx {\n  readonly sealedSlots: {\n    seal(field: string, plaintext: unknown): Promise<SealedSlotRef>\n    unseal(field: string, ref: SealedSlotRef): Promise<unknown>\n    delete(field: string): Promise<void>\n  }\n  reservedEnvelopes(prefix: string): {\n    encrypt(collection: string, json: string, v: number): Promise<EncryptedEnvelope>\n    decrypt(collection: string, env: EncryptedEnvelope): Promise<string>\n  }\n}\n\n/** Per-call erase context — `forget()`'s per-ref participation door (phase C). */\nexport interface ViaEraseCtx { readonly id: string; readonly vault: string; readonly live: unknown /* EncryptedEnvelope */; readonly crypto: ViaCryptoCtx }\n/**\n * What an `erase` hook reports back to `forget()`'s summary ledger entry.\n * `retainedShared` is additive (#629 Task 10) — content NOT erased because\n * still referenced by another live record (blob's shared-chunk dual\n * accounting, `shredAllForRecord()`'s `retainedShared` count). Absent/0 for\n * bindings with no such concept (a sealed field is never \"shared\").\n */\nexport interface ViaEraseReport { readonly shredded: number; readonly residue: readonly unknown[]; readonly retainedShared?: number }\n\n/**\n * A feature bound to one collection's declared config. Record-grain hooks —\n * every hook receives the whole record (matches the real engine signatures,\n * e.g. quantizeMoneyFields(record, moneyFields)). All hooks optional;\n * absent = passthrough. Query-participation hooks are SYNC (#553).\n */\nexport interface ViaBinding {\n  readonly brand: string\n  readonly posture: ViaPosture\n  /** Declared dependencies (field paths / cross-record specs). MANDATORY for any future\n   *  derive-bearing binding — phase C validates well-formedness (strings, non-empty,\n   *  reference declared fields) and graph-registers a derived edge for each covered\n   *  field at declare time, right after `compileViaBindings` builds the bindings\n   *  (unknown source field throws `ValidationError`). See\n   *  `kernel/collection-config.ts`'s `resolveViaBindingDepsEdges`. */\n  readonly deps?: readonly string[]\n  /** Collection-name prefixes this binding's `reservedEnvelopes` capability may address (e.g. `_dict_`). */\n  readonly reservedPrefixes?: readonly string[]\n  /**\n   * Does this binding own `field`? Backs `ViaPipeline.postureFor` (#629 Task\n   * 8's posture consumer) — a passive coverage check, independent of\n   * `buildClause`/`compareForOrder` (which some bindings, e.g. classified and\n   * blob, never define). SYNC, no side effects.\n   *\n   * Contract (documentation only — not enforced at runtime, future work):\n   * any binding declaring a non-default posture value — `queryable: 'none'`\n   * (#629 Task 8) or `exportable: false` (#629 Task 9's `redactForExport`)\n   * — MUST implement `covers()`. `postureFor`'s consumers only engage for\n   * fields a binding actively claims via `covers()`; a binding that omits\n   * it would silently fall through to the generic (unrefused/unredacted)\n   * path instead.\n   */\n  covers?(field: string): boolean\n  // NOTE: phase C adds a `derive` hook ADDITIVELY — do not stub it now.\n  // ── write pipeline ──\n  /** Refuse a write before crypto runs (classified step-3 slot: storage:'never' rejection + validators). Throws to refuse. */\n  enforceWrite?(record: Record<string, unknown>, ctx: ViaWriteCtx): void | Promise<void>\n  /** First pipeline stage (money canonicalizeIncomingMoney). SYNC. */\n  ingest?(record: Record<string, unknown>): Record<string, unknown>\n  /** Decode STORED form to canonical for internal boundaries (gates, derivations, patch bases). SYNC. */\n  canonicalizeStored?(record: Record<string, unknown>): Record<string, unknown>\n  /** Post-validation write encoding (money quantize; i18n translate→script→validate→densify). May be async. */\n  encodeWrite?(record: Record<string, unknown>, ctx: ViaWriteCtx): Awaitable<Record<string, unknown>>\n  /** Final write-pipeline stage: seal/encrypt declared fields via `crypto` before the envelope body is built (classified step-2 slot). */\n  encodeAtRest?(record: Record<string, unknown>, crypto: ViaCryptoCtx): Promise<{ record: Record<string, unknown>; sealed?: Record<string, SealedSlotRef> }>\n  // ── read pipeline ──\n  /** First read-pipeline stage: unseal/decrypt declared fields via `crypto` before `present` runs (classified sealed-handle slot). */\n  decodeAtRest?(record: Record<string, unknown>, sealed: Record<string, SealedSlotRef>, crypto: ViaCryptoCtx, opts: { asHandles: boolean }): Promise<Record<string, unknown>>\n  /** Read-time presentation (money decode+virtuals; i18n locale/labels/strip). May be async. */\n  present?(record: Record<string, unknown>, ctx: ViaReadCtx): Awaitable<Record<string, unknown>>\n  /**\n   * Late read-time presentation (#669) — runs AFTER every binding's `present()` in the\n   * money+computed present-order segment (`ViaPipeline`'s `_presentOrder`, `kernel/via/\n   * pipeline.ts`), BEFORE the \"everything else\" segment (i18n/lookup dressing, taint\n   * redaction) runs. Exists for a binding that needs to react to a virtual computed\n   * field's fresh OWN-field output before anything dresses it (money's MAJOR-UNITS\n   * quantize-and-present for a field that is BOTH money AND `mode:'virtual'` computed) —\n   * `present()` alone can't express \"run after computed for THESE fields only, before\n   * computed for all others\", since it's a per-BINDING fold, not per-field. Folded over\n   * `bindings` in declaration order (mirrors every other per-binding fold), so lookup/\n   * i18n dressing and taint/redaction (both in the \"everything else\" segment) still see\n   * the already-dressed value.\n   */\n  presentLate?(record: Record<string, unknown>, ctx: ViaReadCtx): Awaitable<Record<string, unknown>>\n  // ── query participation (ALL SYNC — #553) ──\n  /** Returns an opaque clause payload when this binding covers `field`, else undefined. */\n  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents\n  buildClause?(field: string, op: string, value: unknown): unknown | undefined\n  /** Evaluate a payload produced by buildClause against a raw stored value. */\n  evaluateClause?(actual: unknown, op: string, payload: unknown): boolean\n  /**\n   * Optional: the STORED-form operand for a direct secondary-index probe\n   * against a payload produced by `buildClause` (#625) — lets\n   * `candidateRecords()` (`query/builder.ts`) hit `CollectionIndexes.\n   * lookupEqual`/`lookupIn` for `==`/`in` clauses instead of falling back\n   * to a linear scan + per-record `evaluateClause`. Returning `undefined`\n   * means \"no sound probe for this op/payload\" (e.g. a comparison whose\n   * stored form isn't a single index-bucketable value, or an op the index\n   * can't serve) — the caller falls back to the scan. A binding that\n   * never implements this hook always falls back, unchanged from before\n   * this hook existed.\n   */\n  // eslint-disable-next-line @typescript-eslint/no-redundant-type-constituents\n  indexProbe?(op: string, payload: unknown): unknown | undefined\n  /**\n   * Optional: canonicalize a raw STORED field value into the bucket key an\n   * eager index should use (#672) — lets `CollectionIndexes` group a\n   * pre-declaration / non-canonical stored value (e.g. a money field's\n   * leftover `'0100'` written before its `money()` declaration) under the\n   * SAME key a canonical write produces (`'100'`), so the index-probe fast\n   * path (`indexProbe` above) and the fallback scan (`evaluateClause`)\n   * agree on which records match. `undefined` means \"not mine / can't\n   * canonicalize this value\" — the caller buckets the raw stringified\n   * value, unchanged from before this hook existed. MUST agree with what\n   * this binding's own `evaluateClause`/`indexProbe` treat as equal, or\n   * the fast path and the scan will disagree.\n   */\n  canonicalizeIndexKey?(field: string, rawValue: unknown): string | undefined\n  /** Decode a raw stored record for query/scan results and callback views ('raw' — no virtuals). */\n  decodeResults?(record: unknown): unknown\n  /** Exact ordering for a covered field; undefined when the field is not covered. */\n  compareForOrder?(field: string, a: unknown, b: unknown): number | undefined\n  /**\n   * Per-key, PER-CALL-locale label resolution for `orderBy(field, dir,\n   * { by: 'label' })` (#650 Task 7) — the sibling `compareForOrder` above\n   * structurally cannot serve, since it carries no locale parameter.\n   * `locale` is the query's per-call locale (`undefined` for a locale-less\n   * query — a binding may fall back to its own descriptor-level default,\n   * mirroring `present`'s displayLocale hinge). `undefined` return = this\n   * binding doesn't resolve a label for `key` at `field` — caller falls\n   * back to the raw stored value, same graceful-degrade discipline every\n   * other via query hook uses. SYNC (#553 — query participation).\n   */\n  resolveOrderLabel?(field: string, key: string, locale: string | undefined): string | undefined\n  /** Rewrite an aggregate spec (money exact reducers). */\n  wrapReducers?(spec: unknown): unknown\n  // ── forget participation ──\n  /** `forget()`'s per-ref erasure door — shred/report this binding's residue for one record (classified/blob forget participation). */\n  erase?(ctx: ViaEraseCtx): Promise<ViaEraseReport>\n  // ── introspection ──\n  describeFragment?(): Record<string, unknown>\n}\n\n/** Binder: constructs a binding from a collection's declared config. Installed by the feature's declaration factory. */\nexport type ViaBinder = (config: unknown) => ViaBinding\n\nconst binders = new Map<string, ViaBinder>()\n\n/** @internal — called (idempotently, first-wins) by a feature's declaration factory, e.g. money(). */\nexport function installViaBinder(brand: string, binder: ViaBinder): void {\n  if (!binders.has(brand)) binders.set(brand, binder)\n}\n\n/** @internal — registry presence check. Used by tests (mirrors isMoneyEngineInstalled) and by vault's i18n validator delegators as a no-i18n-ever-declared fast path. */\nexport function isViaInstalled(brand: string): boolean {\n  return binders.has(brand)\n}\n\n/** @internal — resolve a binder; throws when the declaration factory never ran (hand-rolled descriptors). */\nexport function viaBinder(brand: string): ViaBinder {\n  const b = binders.get(brand)\n  if (!b) {\n    throw new NoydbError(\n      'VIA_NOT_LINKED',\n      `via feature \"${brand}\" requires descriptors created via its declaration factory from @noy-db/hub`,\n    )\n  }\n  return b\n}\n"],"mappings":";;;;;AAmMA,IAAM,UAAU,oBAAI,IAAuB;AAGpC,SAAS,iBAAiB,OAAe,QAAyB;AACvE,MAAI,CAAC,QAAQ,IAAI,KAAK,EAAG,SAAQ,IAAI,OAAO,MAAM;AACpD;AAGO,SAAS,eAAe,OAAwB;AACrD,SAAO,QAAQ,IAAI,KAAK;AAC1B;AAGO,SAAS,UAAU,OAA0B;AAClD,QAAM,IAAI,QAAQ,IAAI,KAAK;AAC3B,MAAI,CAAC,GAAG;AACN,UAAM,IAAI;AAAA,MACR;AAAA,MACA,gBAAgB,KAAK;AAAA,IACvB;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/chunk-KPZS5QAQ.js

@@ -0,0 +1,151 @@
+import {
+  readPath
+} from "./chunk-IGJCYUT5.js";
+
+// src/with-lookup/indexing/eager-indexes.ts
+var CollectionIndexes = class {
+  indexes = /* @__PURE__ */ new Map();
+  /**
+   * Per-field bucket-key canonicalizer (#672 review C1), registered ONCE
+   * via {@link setCanonicalizer} when the collection wires indexing up
+   * (money-aware via `ViaPipeline.canonicalizeIndexKey`). Consulted by
+   * EVERY bucket-mutation site — `build`/`upsert`/`remove` — so bucket
+   * membership is symmetric by construction: a value can never be added
+   * under a canonical key and later removed under the raw one (or vice
+   * versa), which is what stranded ids on `put`/`delete` before this fix.
+   */
+  canonicalize;
+  /**
+   * Register the bucket-key canonicalizer. Called once, where the
+   * collection constructs its indexing state — safe to call again (the
+   * closure is simply replaced) but there is normally only one caller.
+   */
+  setCanonicalizer(fn) {
+    this.canonicalize = fn;
+  }
+  /**
+   * Declare an index. Subsequent record additions are tracked under it.
+   * Calling this twice for the same field is a no-op (idempotent).
+   */
+  declare(field) {
+    if (this.indexes.has(field)) return;
+    this.indexes.set(field, { field, buckets: /* @__PURE__ */ new Map() });
+  }
+  /** True if the given field has a declared index. */
+  has(field) {
+    return this.indexes.has(field);
+  }
+  /** All declared field names, in declaration order. */
+  fields() {
+    return [...this.indexes.keys()];
+  }
+  /**
+   * Build all declared indexes from a snapshot of records.
+   * Called once per hydration. O(N × indexes.size). Buckets through the
+   * registered {@link setCanonicalizer} closure, same as `upsert`/`remove`.
+   */
+  build(records) {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+      for (const { id, record } of records) {
+        addToIndex(idx, id, record, this.canonicalize);
+      }
+    }
+  }
+  /**
+   * Insert or update a single record across all indexes.
+   * Called by `Collection.put()` after the encrypted write succeeds.
+   *
+   * If `previousRecord` is provided, the record is removed from any old
+   * buckets first — this is the update path. Pass `null` for fresh adds.
+   */
+  upsert(id, newRecord, previousRecord) {
+    if (this.indexes.size === 0) return;
+    if (previousRecord !== null) {
+      this.remove(id, previousRecord);
+    }
+    for (const idx of this.indexes.values()) {
+      addToIndex(idx, id, newRecord, this.canonicalize);
+    }
+  }
+  /**
+   * Remove a record from all indexes. Called by `Collection.delete()`
+   * (and as the first half of `upsert` for the update path).
+   */
+  remove(id, record) {
+    if (this.indexes.size === 0) return;
+    for (const idx of this.indexes.values()) {
+      removeFromIndex(idx, id, record, this.canonicalize);
+    }
+  }
+  /** Drop all index data. Called when the collection is invalidated. */
+  clear() {
+    for (const idx of this.indexes.values()) {
+      idx.buckets.clear();
+    }
+  }
+  /**
+   * Equality lookup: return the set of record ids whose `field` matches
+   * the given value. Returns `null` if no index covers the field — the
+   * caller should fall back to a linear scan.
+   *
+   * The returned Set is a reference to the index's internal storage —
+   * callers must NOT mutate it.
+   */
+  lookupEqual(field, value) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    const key = stringifyKey(value);
+    return idx.buckets.get(key) ?? EMPTY_SET;
+  }
+  /**
+   * Set lookup: return the union of record ids whose `field` matches any
+   * of the given values. Returns `null` if no index covers the field.
+   */
+  lookupIn(field, values) {
+    const idx = this.indexes.get(field);
+    if (!idx) return null;
+    const out = /* @__PURE__ */ new Set();
+    for (const value of values) {
+      const key = stringifyKey(value);
+      const bucket = idx.buckets.get(key);
+      if (bucket) {
+        for (const id of bucket) out.add(id);
+      }
+    }
+    return out;
+  }
+};
+var EMPTY_SET = /* @__PURE__ */ new Set();
+function stringifyKey(value) {
+  if (value === null || value === void 0) return "\0NULL\0";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (value instanceof Date) return value.toISOString();
+  return "\0OBJECT\0";
+}
+function addToIndex(idx, id, record, canonicalize) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = canonicalize?.(idx.field, value) ?? stringifyKey(value);
+  let bucket = idx.buckets.get(key);
+  if (!bucket) {
+    bucket = /* @__PURE__ */ new Set();
+    idx.buckets.set(key, bucket);
+  }
+  bucket.add(id);
+}
+function removeFromIndex(idx, id, record, canonicalize) {
+  const value = readPath(record, idx.field);
+  if (value === null || value === void 0) return;
+  const key = canonicalize?.(idx.field, value) ?? stringifyKey(value);
+  const bucket = idx.buckets.get(key);
+  if (!bucket) return;
+  bucket.delete(id);
+  if (bucket.size === 0) idx.buckets.delete(key);
+}
+
+export {
+  CollectionIndexes
+};
+//# sourceMappingURL=chunk-KPZS5QAQ.js.map