@noy-db/hub 0.1.0-pre.9 → 0.2.0-pre.10

package/dist/team/index.d.cts

@@ -1,10 +1,11 @@
-import { at as NoydbStore, ar as UnlockedKeyring } from '../types-Bnb82f5R.cjs';
-export { c3 as PresenceHandle, cF as SyncEngine, cN as SyncTransaction, df as evaluateExportCapability, dg as evaluateImportCapability, di as hasExportCapability, dj as hasImportCapability } from '../types-Bnb82f5R.cjs';
-import '../lazy-builder-CZVLKh0Z.cjs';
-import '../predicate-SBHmi6D0.cjs';
-import '../strategy-D-SrOLCl.cjs';
+import { b3 as NoydbStore, b1 as UnlockedKeyring } from '../types-n2_IfwlQ.cjs';
+export { bt as BundleRecipient, cg as EnrollAuthenticatorOptions, ch as EnrollAuthenticatorWrappingDEKsOptions, ci as EnrollAuthenticatorWrappingKEKOptions, cN as ListUsersOptions, d9 as PaperRecoveryEntry, dh as PresenceHandle, dD as RecoverPassphraseInput, dE as RecoverPassphraseResult, dF as RecoverUserOptions, dG as RecoveryProof, dJ as RotatePassphraseInput, dV as SlotRewrapCeremony, dW as SlotRewrapContext, e1 as SyncEngine, e9 as SyncTransaction, em as UpdateAuthenticatorOptions, eB as WrappedDeksBlob, eH as buildRecipientKeyringFile, eI as burnPaperRecoveryEntry, fr as changeSecret, fs as createOwnerKeyring, eL as deriveMagicLinkContentKey, eM as enrollAuthenticator, ft as ensureCollectionDEK, eO as evaluateExportCapability, eP as evaluateImportCapability, eQ as findAuthenticator, fu as grant, eR as hasExportCapability, eS as hasImportCapability, eU as isMagicLinkGrantExpired, eZ as listMagicLinkGrants, e_ as listUsers, e$ as listUsersWithEnvelopes, fv as loadKeyring, f1 as loadPaperRecoveryEntries, f4 as magicLinkGrantRecordId, f5 as mintPaperRecoveryEntry, f7 as mintWrappedDeksBlob, fw as persistKeyring, f9 as readMagicLinkGrantRecord, eX as recoverPassphrase, fa as recoverUser, fb as removeAuthenticator, fx as revoke, fe as revokeMagicLinkGrant, eY as rotatePassphrase, ff as savePaperRecoveryEntries, fi as unwrapDeksFromBlob, fj as unwrapDeksFromPaperEntry, fl as unwrapMagicLinkGrant, fy as updateAuthenticator, fz as updateKeyringIdentity, fq as writeMagicLinkGrant } from '../types-n2_IfwlQ.cjs';
+import '../lazy-builder-Ci5_YG73.cjs';
+import '../predicate-Bt5ft-9c.cjs';
+import '../strategy-CT2LCKAX.cjs';
 import '../strategy-BSxFXGzb.cjs';
-import '../index-6xNpPsxR.cjs';
+import '../index-B8bjExET.cjs';
+import '@noy-db/attestation';
 
 /**
  * _sync_credentials reserved collection —

package/dist/team/index.d.ts

@@ -1,10 +1,11 @@
-import { at as NoydbStore, ar as UnlockedKeyring } from '../types-Bo7NSXJr.js';
-export { c3 as PresenceHandle, cF as SyncEngine, cN as SyncTransaction, df as evaluateExportCapability, dg as evaluateImportCapability, di as hasExportCapability, dj as hasImportCapability } from '../types-Bo7NSXJr.js';
-import '../lazy-builder-BwEoBQZ9.js';
-import '../predicate-SBHmi6D0.js';
-import '../strategy-D-SrOLCl.js';
+import { b3 as NoydbStore, b1 as UnlockedKeyring } from '../types-CaNQm4i8.js';
+export { bt as BundleRecipient, cg as EnrollAuthenticatorOptions, ch as EnrollAuthenticatorWrappingDEKsOptions, ci as EnrollAuthenticatorWrappingKEKOptions, cN as ListUsersOptions, d9 as PaperRecoveryEntry, dh as PresenceHandle, dD as RecoverPassphraseInput, dE as RecoverPassphraseResult, dF as RecoverUserOptions, dG as RecoveryProof, dJ as RotatePassphraseInput, dV as SlotRewrapCeremony, dW as SlotRewrapContext, e1 as SyncEngine, e9 as SyncTransaction, em as UpdateAuthenticatorOptions, eB as WrappedDeksBlob, eH as buildRecipientKeyringFile, eI as burnPaperRecoveryEntry, fr as changeSecret, fs as createOwnerKeyring, eL as deriveMagicLinkContentKey, eM as enrollAuthenticator, ft as ensureCollectionDEK, eO as evaluateExportCapability, eP as evaluateImportCapability, eQ as findAuthenticator, fu as grant, eR as hasExportCapability, eS as hasImportCapability, eU as isMagicLinkGrantExpired, eZ as listMagicLinkGrants, e_ as listUsers, e$ as listUsersWithEnvelopes, fv as loadKeyring, f1 as loadPaperRecoveryEntries, f4 as magicLinkGrantRecordId, f5 as mintPaperRecoveryEntry, f7 as mintWrappedDeksBlob, fw as persistKeyring, f9 as readMagicLinkGrantRecord, eX as recoverPassphrase, fa as recoverUser, fb as removeAuthenticator, fx as revoke, fe as revokeMagicLinkGrant, eY as rotatePassphrase, ff as savePaperRecoveryEntries, fi as unwrapDeksFromBlob, fj as unwrapDeksFromPaperEntry, fl as unwrapMagicLinkGrant, fy as updateAuthenticator, fz as updateKeyringIdentity, fq as writeMagicLinkGrant } from '../types-CaNQm4i8.js';
+import '../lazy-builder-D5GU14TS.js';
+import '../predicate-Bt5ft-9c.js';
+import '../strategy-CT2LCKAX.js';
 import '../strategy-BSxFXGzb.js';
-import '../index-DJTf9yxn.js';
+import '../index-DfUbNad8.js';
+import '@noy-db/attestation';
 
 /**
  * _sync_credentials reserved collection —

package/dist/team/index.js

@@ -5,35 +5,104 @@ import {
   getCredential,
   listCredentials,
   putCredential
-} from "../chunk-4PWAI7Q4.js";
+} from "../chunk-5OX6XVNS.js";
+import {
+  burnPaperRecoveryEntry,
+  deriveMagicLinkContentKey,
+  enrollAuthenticator,
+  findAuthenticator,
+  isMagicLinkGrantExpired,
+  listMagicLinkGrants,
+  loadPaperRecoveryEntries,
+  magicLinkGrantRecordId,
+  mintPaperRecoveryEntry,
+  mintWrappedDeksBlob,
+  readMagicLinkGrantRecord,
+  recoverPassphrase,
+  recoverUser,
+  removeAuthenticator,
+  revokeMagicLinkGrant,
+  rotatePassphrase,
+  savePaperRecoveryEntries,
+  unwrapDeksFromBlob,
+  unwrapDeksFromPaperEntry,
+  unwrapMagicLinkGrant,
+  updateAuthenticator,
+  writeMagicLinkGrant
+} from "../chunk-PXTQPZO4.js";
+import "../chunk-CXFOITNS.js";
 import {
   PresenceHandle,
   SyncEngine,
   SyncTransaction
-} from "../chunk-AVVPZ4BC.js";
+} from "../chunk-DJRWA3Q5.js";
 import {
+  buildRecipientKeyringFile,
+  changeSecret,
+  createOwnerKeyring,
+  ensureCollectionDEK,
   evaluateExportCapability,
   evaluateImportCapability,
+  grant,
   hasExportCapability,
-  hasImportCapability
-} from "../chunk-WDM5XGGS.js";
+  hasImportCapability,
+  listUsers,
+  listUsersWithEnvelopes,
+  loadKeyring,
+  persistKeyring,
+  revoke,
+  updateKeyringIdentity
+} from "../chunk-HQSQC2XL.js";
 import "../chunk-2QR2PQTT.js";
-import "../chunk-RKJ6OL7K.js";
-import "../chunk-MR4424N3.js";
-import "../chunk-ACLDOTNQ.js";
+import "../chunk-WIRRPTFH.js";
+import "../chunk-R233SLY3.js";
+import "../chunk-O6EJ6WTI.js";
 export {
   PresenceHandle,
   SYNC_CREDENTIALS_COLLECTION,
   SyncEngine,
   SyncTransaction,
+  buildRecipientKeyringFile,
+  burnPaperRecoveryEntry,
+  changeSecret,
+  createOwnerKeyring,
   credentialStatus,
   deleteCredential,
+  deriveMagicLinkContentKey,
+  enrollAuthenticator,
+  ensureCollectionDEK,
   evaluateExportCapability,
   evaluateImportCapability,
+  findAuthenticator,
   getCredential,
+  grant,
   hasExportCapability,
   hasImportCapability,
+  isMagicLinkGrantExpired,
   listCredentials,
-  putCredential
+  listMagicLinkGrants,
+  listUsers,
+  listUsersWithEnvelopes,
+  loadKeyring,
+  loadPaperRecoveryEntries,
+  magicLinkGrantRecordId,
+  mintPaperRecoveryEntry,
+  mintWrappedDeksBlob,
+  persistKeyring,
+  putCredential,
+  readMagicLinkGrantRecord,
+  recoverPassphrase,
+  recoverUser,
+  removeAuthenticator,
+  revoke,
+  revokeMagicLinkGrant,
+  rotatePassphrase,
+  savePaperRecoveryEntries,
+  unwrapDeksFromBlob,
+  unwrapDeksFromPaperEntry,
+  unwrapMagicLinkGrant,
+  updateAuthenticator,
+  updateKeyringIdentity,
+  writeMagicLinkGrant
 };
 //# sourceMappingURL=index.js.map

package/dist/tx/index.cjs

@@ -3,6 +3,9 @@ var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
@@ -17,6 +20,147 @@ var __copyProps = (to, from, except, desc) => {
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
+// src/errors.ts
+var NoydbError, FieldFrozenError, InvariantError, AmendmentForbiddenError, ConflictError, ValidationError;
+var init_errors = __esm({
+  "src/errors.ts"() {
+    "use strict";
+    NoydbError = class extends Error {
+      /** Machine-readable error code. Stable across library versions. */
+      code;
+      constructor(code, message) {
+        super(message);
+        this.name = "NoydbError";
+        this.code = code;
+      }
+    };
+    FieldFrozenError = class extends NoydbError {
+      collection;
+      id;
+      fields;
+      constructor(collection, id, fields) {
+        super(
+          "FIELD_FROZEN",
+          `Cannot change frozen field(s) on ${collection}/${id}: ${fields.join(", ")}. Use withTransactions({ amendment: true, reason }) with admin/owner role to override.`
+        );
+        this.name = "FieldFrozenError";
+        this.collection = collection;
+        this.id = id;
+        this.fields = fields;
+      }
+    };
+    InvariantError = class extends NoydbError {
+      constructor(message) {
+        super("INVARIANT_VIOLATED", message);
+        this.name = "InvariantError";
+      }
+    };
+    AmendmentForbiddenError = class extends NoydbError {
+      userId;
+      role;
+      constructor(userId, role) {
+        super(
+          "AMENDMENT_FORBIDDEN",
+          `User "${userId}" with role "${role}" cannot open an amendment transaction. Amendments require admin or owner role.`
+        );
+        this.name = "AmendmentForbiddenError";
+        this.userId = userId;
+        this.role = role;
+      }
+    };
+    ConflictError = class extends NoydbError {
+      /** The actual stored version at the time of conflict. */
+      version;
+      constructor(version, message = "Version conflict") {
+        super("CONFLICT", message);
+        this.name = "ConflictError";
+        this.version = version;
+      }
+    };
+    ValidationError = class extends NoydbError {
+      constructor(message = "Validation error") {
+        super("VALIDATION_ERROR", message);
+        this.name = "ValidationError";
+      }
+    };
+  }
+});
+
+// src/guards/executor.ts
+var executor_exports = {};
+__export(executor_exports, {
+  GuardExecutor: () => GuardExecutor
+});
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (a === null || b === null) return a === b;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return a === b;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) {
+    const aa = a;
+    const bb = b;
+    if (aa.length !== bb.length) return false;
+    for (let i = 0; i < aa.length; i++) if (!deepEqual(aa[i], bb[i])) return false;
+    return true;
+  }
+  const ao = a;
+  const bo = b;
+  const ak = Object.keys(ao);
+  const bk = Object.keys(bo);
+  if (ak.length !== bk.length) return false;
+  for (const k of ak) {
+    if (!Object.prototype.hasOwnProperty.call(bo, k)) return false;
+    if (!deepEqual(ao[k], bo[k])) return false;
+  }
+  return true;
+}
+var GuardExecutor;
+var init_executor = __esm({
+  "src/guards/executor.ts"() {
+    "use strict";
+    init_errors();
+    GuardExecutor = {
+      /**
+       * Compare existing vs incoming for each `frozenFields.fields` entry
+       * when `frozenFields.when(existing)` is true. Throws
+       * `FieldFrozenError` listing every changed frozen field.
+       */
+      async checkFrozenFields(guard, id, existing, incoming) {
+        const ff = guard.frozenFields;
+        if (!ff) return;
+        if (existing === null) return;
+        if (!ff.when(existing)) return;
+        const changed = [];
+        for (const f of ff.fields) {
+          if (existing[f] !== incoming[f]) {
+            if (!deepEqual(existing[f], incoming[f])) changed.push(String(f));
+          }
+        }
+        if (changed.length > 0) {
+          throw new FieldFrozenError(guard.collection, id, changed);
+        }
+      },
+      /**
+       * Run a single guard's invariant over its slice of the change-set.
+       * Any throw is converted to `InvariantError` unless it already is one.
+       */
+      async runInvariant(guard, changes, ctx) {
+        const amendment = guard.amendment;
+        if (!amendment) return;
+        try {
+          await amendment.invariant(changes, ctx);
+        } catch (err) {
+          if (err instanceof InvariantError) throw err;
+          throw new InvariantError(
+            err instanceof Error ? err.message : `invariant violated: ${String(err)}`
+          );
+        }
+      }
+    };
+  }
+});
+
 // src/tx/index.ts
 var tx_exports = {};
 __export(tx_exports, {
@@ -28,39 +172,80 @@ __export(tx_exports, {
 });
 module.exports = __toCommonJS(tx_exports);
 
-// src/errors.ts
-var NoydbError = class extends Error {
-  /** Machine-readable error code. Stable across library versions. */
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "NoydbError";
-    this.code = code;
-  }
-};
-var ConflictError = class extends NoydbError {
-  /** The actual stored version at the time of conflict. */
-  version;
-  constructor(version, message = "Version conflict") {
-    super("CONFLICT", message);
-    this.name = "ConflictError";
-    this.version = version;
+// src/tx/transaction.ts
+init_errors();
+
+// src/bundle/ulid.ts
+var CROCKFORD_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function encodeBase32(value, length) {
+  let out = "";
+  let v = value;
+  for (let i = 0; i < length; i++) {
+    out = CROCKFORD_ALPHABET[v % 32] + out;
+    v = Math.floor(v / 32);
   }
-};
+  return out;
+}
+function generateULID() {
+  const now = Date.now();
+  const timestampHigh = Math.floor(now / 16777216);
+  const timestampLow = now & 16777215;
+  const tsPart = encodeBase32(timestampHigh, 5) + encodeBase32(timestampLow, 5);
+  const randBytes = new Uint8Array(10);
+  crypto.getRandomValues(randBytes);
+  const rand1 = randBytes[0] * 2 ** 32 + (randBytes[1] << 24 >>> 0) + (randBytes[2] << 16) + (randBytes[3] << 8) + randBytes[4];
+  const rand2 = randBytes[5] * 2 ** 32 + (randBytes[6] << 24 >>> 0) + (randBytes[7] << 16) + (randBytes[8] << 8) + randBytes[9];
+  const randPart = encodeBase32(rand1, 8) + encodeBase32(rand2, 8);
+  return tsPart + randPart;
+}
 
 // src/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) {
+  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") {
+        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);
   }
 };
@@ -124,6 +309,7 @@ var TxCollection = class {
       record
     };
     if (options?.expectedVersion !== void 0) op.expectedVersion = options.expectedVersion;
+    if (options?.reason !== void 0) op.reason = options.reason;
     this._ctx._ops.push(op);
   }
   /**
@@ -142,10 +328,28 @@ var TxCollection = class {
     this._ctx._ops.push(op);
   }
 };
-async function runTransaction(db, fn) {
-  const ctx = new TxContext(db);
+async function runTransaction(db, fn, options) {
+  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) return bodyResult;
+  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;
   for (const op of ctx._ops) {
@@ -165,41 +369,169 @@ async function runTransaction(db, fn) {
       }
     }
   }
-  const executed = [];
+  db._setActiveTxContext(ctx);
   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;
-      if (op.type === "put") {
-        await coll.put(op.id, op.record);
-      } else {
-        await coll.delete(op.id);
+    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);
+        }
       }
-      executed.push({ op, priorEnvelope: prior });
+    } 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;
     }
-    return bodyResult;
-  } catch (err) {
-    for (const { op, priorEnvelope } of executed.slice().reverse()) {
-      try {
-        if (priorEnvelope) {
-          await store.put(op.vaultName, op.collectionName, op.id, priorEnvelope);
-        } else {
-          await store.delete(op.vaultName, op.collectionName, op.id);
+  } finally {
+    db._clearActiveTxContext(ctx);
+  }
+  if (ctx._amendment) {
+    const { GuardExecutor: GuardExecutor2 } = await Promise.resolve().then(() => (init_executor(), executor_exports));
+    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 GuardExecutor2.runInvariant(guard, changes, {
+              existing: null,
+              vault: readOnlyVault,
+              userId: v.userId,
+              role: v.role
+            });
+          }
+          if (guards.length > 0) invariantsPassed.push(collection);
         }
-      } catch {
+        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)}`
+      );
+    }
+  }
+  return bodyResult;
+}
+async function revertExecuted(executed, store, db) {
+  for (const { op, priorEnvelope } of executed.slice().reverse()) {
+    try {
+      if (priorEnvelope) {
+        await store.put(op.vaultName, op.collectionName, op.id, priorEnvelope);
+      } else {
+        await store.delete(op.vaultName, op.collectionName, op.id);
+      }
+      if (db) {
+        const coll = db.vault(op.vaultName).collection(op.collectionName);
+        await coll._invalidateCacheEntry(op.id);
+      }
+    } catch {
     }
-    throw err;
   }
 }
 function keyOf(op) {
   return `${op.vaultName}\0${op.collectionName}\0${op.id}`;
 }
 
+// src/tx/dry-run.ts
+var SEP = " ";
+var keyOf2 = (op) => `${op.vaultName}${SEP}${op.collectionName}${SEP}${op.id}`;
+async function runDryRun(db, fn) {
+  const ctx = new TxContext(db);
+  await fn(ctx);
+  const lastOp = /* @__PURE__ */ new Map();
+  for (const op of ctx._ops) lastOp.set(keyOf2(op), op);
+  const affected = [];
+  const guardViolations = [];
+  for (const op of lastOp.values()) {
+    const v = db.vault(op.vaultName);
+    const coll = v.collection(op.collectionName);
+    const before = await coll.get(op.id);
+    if (op.type === "delete") {
+      affected.push({ vault: op.vaultName, op: "delete", collection: op.collectionName, docId: op.id, before, after: null });
+      continue;
+    }
+    const after = op.record ?? null;
+    affected.push({
+      vault: op.vaultName,
+      op: before === null ? "create" : "update",
+      collection: op.collectionName,
+      docId: op.id,
+      before,
+      after
+    });
+    const registry = v._getGuardRegistry();
+    if (!registry) continue;
+    const guards = registry.guardsFor(op.collectionName);
+    if (guards.length === 0) continue;
+    const facade = v._getReadOnlyFacade();
+    if (!facade) continue;
+    const gctx = { existing: before, vault: facade, userId: v.userId, role: v.role };
+    try {
+      await registry.runChecks(op.collectionName, after, gctx);
+      const { GuardExecutor: GuardExecutor2 } = await Promise.resolve().then(() => (init_executor(), executor_exports));
+      for (const g of guards) {
+        await GuardExecutor2.checkFrozenFields(g, op.id, before, after);
+      }
+    } catch (err) {
+      guardViolations.push({
+        vault: op.vaultName,
+        collection: op.collectionName,
+        docId: op.id,
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return { affected, guardViolations };
+}
+
 // src/tx/active.ts
 function withTransactions() {
-  return { runTransaction };
+  return { runTransaction, runDryRun };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {