@noy-db/hub 0.2.0-pre.2 → 0.2.0-pre.21

package/dist/team/index.d.cts

@@ -1,10 +1,12 @@
-import { aO as NoydbStore, aM as UnlockedKeyring } from '../types-DJG8HG6F.cjs';
-export { bc as BundleRecipient, bW as EnrollAuthenticatorOptions, bX as EnrollAuthenticatorWrappingDEKsOptions, bY as EnrollAuthenticatorWrappingKEKOptions, cn as ListUsersOptions, cM as PaperRecoveryEntry, cU as PresenceHandle, dd as RecoverPassphraseInput, de as RecoverPassphraseResult, df as RecoverUserOptions, dg as RecoveryProof, dj as RotatePassphraseInput, du as SlotRewrapCeremony, dv as SlotRewrapContext, dC as SyncEngine, dK as SyncTransaction, dS as UpdateAuthenticatorOptions, e4 as WrappedDeksBlob, e6 as buildRecipientKeyringFile, e7 as burnPaperRecoveryEntry, eS as changeSecret, eT as createOwnerKeyring, ea as deriveMagicLinkContentKey, eb as enrollAuthenticator, eU as ensureCollectionDEK, ed as evaluateExportCapability, ee as evaluateImportCapability, ef as findAuthenticator, eV as grant, eg as hasExportCapability, eh as hasImportCapability, ej as isMagicLinkGrantExpired, eo as listMagicLinkGrants, ep as listUsers, eq as listUsersWithEnvelopes, eW as loadKeyring, es as loadPaperRecoveryEntries, ev as magicLinkGrantRecordId, ew as mintPaperRecoveryEntry, ey as mintWrappedDeksBlob, eX as persistKeyring, eA as readMagicLinkGrantRecord, em as recoverPassphrase, eB as recoverUser, eC as removeAuthenticator, eY as revoke, eF as revokeMagicLinkGrant, en as rotatePassphrase, eG as savePaperRecoveryEntries, eJ as unwrapDeksFromBlob, eK as unwrapDeksFromPaperEntry, eM as unwrapMagicLinkGrant, eZ as updateAuthenticator, e_ as updateKeyringIdentity, eR as writeMagicLinkGrant } from '../types-DJG8HG6F.cjs';
-import '../lazy-builder-C-rPfWG0.cjs';
-import '../predicate-Dnu81tsS.cjs';
-import '../strategy-DSTrsZ8t.cjs';
+import { aW as NoydbStore, aU as UnlockedKeyring } from '../types-DyOI6XZ_.cjs';
+export { be as BundleRecipient, ck as EnrollAuthenticatorOptions, cl as EnrollAuthenticatorWrappingDEKsOptions, cm as EnrollAuthenticatorWrappingKEKOptions, c$ as ListUsersOptions, ds as PaperRecoveryEntry, dA as PresenceHandle, dV as RecoverPassphraseInput, dW as RecoverPassphraseResult, dX as RecoverUserOptions, dY as RecoveryProof, e0 as RotatePassphraseInput, eo as SlotRewrapCeremony, ep as SlotRewrapContext, ey as SyncEngine, eG as SyncTransaction, eW as UpdateAuthenticatorOptions, fe as WrappedDeksBlob, fl as buildRecipientKeyringFile, fm as burnPaperRecoveryEntry, ge as changeSecret, gf as createOwnerKeyring, fq as deriveMagicLinkContentKey, fr as enrollAuthenticator, gg as ensureCollectionDEK, fu as evaluateExportCapability, fv as evaluateImportCapability, fw as findAuthenticator, gh as grant, fx as hasExportCapability, fy as hasImportCapability, fB as isMagicLinkGrantExpired, fG as listMagicLinkGrants, fH as listUsers, fI as listUsersWithEnvelopes, gi as loadKeyring, fK as loadPaperRecoveryEntries, fN as magicLinkGrantRecordId, fO as mintPaperRecoveryEntry, fQ as mintWrappedDeksBlob, gj as persistKeyring, fT as readMagicLinkGrantRecord, fE as recoverPassphrase, fU as recoverUser, fV as removeAuthenticator, gk as revoke, fZ as revokeMagicLinkGrant, fF as rotatePassphrase, f$ as savePaperRecoveryEntries, g3 as unwrapDeksFromBlob, g4 as unwrapDeksFromPaperEntry, g6 as unwrapMagicLinkGrant, gl as updateAuthenticator, gm as updateKeyringIdentity, gd as writeMagicLinkGrant } from '../types-DyOI6XZ_.cjs';
+import '../lazy-builder-eYZzLEL1.cjs';
+import '../predicate-BmhBSPCH.cjs';
+import '../strategy-WtB-jXYv.cjs';
+import '../errors-Dkc_fi-S.cjs';
 import '../strategy-BSxFXGzb.cjs';
-import '../index-BMjrzNZr.cjs';
+import '../index-BMmajblo.cjs';
+import '../index-tZqVB9g5.cjs';
 import '@noy-db/attestation';
 
 /**

package/dist/team/index.d.ts

@@ -1,10 +1,12 @@
-import { aO as NoydbStore, aM as UnlockedKeyring } from '../types-BoFFiskX.js';
-export { bc as BundleRecipient, bW as EnrollAuthenticatorOptions, bX as EnrollAuthenticatorWrappingDEKsOptions, bY as EnrollAuthenticatorWrappingKEKOptions, cn as ListUsersOptions, cM as PaperRecoveryEntry, cU as PresenceHandle, dd as RecoverPassphraseInput, de as RecoverPassphraseResult, df as RecoverUserOptions, dg as RecoveryProof, dj as RotatePassphraseInput, du as SlotRewrapCeremony, dv as SlotRewrapContext, dC as SyncEngine, dK as SyncTransaction, dS as UpdateAuthenticatorOptions, e4 as WrappedDeksBlob, e6 as buildRecipientKeyringFile, e7 as burnPaperRecoveryEntry, eS as changeSecret, eT as createOwnerKeyring, ea as deriveMagicLinkContentKey, eb as enrollAuthenticator, eU as ensureCollectionDEK, ed as evaluateExportCapability, ee as evaluateImportCapability, ef as findAuthenticator, eV as grant, eg as hasExportCapability, eh as hasImportCapability, ej as isMagicLinkGrantExpired, eo as listMagicLinkGrants, ep as listUsers, eq as listUsersWithEnvelopes, eW as loadKeyring, es as loadPaperRecoveryEntries, ev as magicLinkGrantRecordId, ew as mintPaperRecoveryEntry, ey as mintWrappedDeksBlob, eX as persistKeyring, eA as readMagicLinkGrantRecord, em as recoverPassphrase, eB as recoverUser, eC as removeAuthenticator, eY as revoke, eF as revokeMagicLinkGrant, en as rotatePassphrase, eG as savePaperRecoveryEntries, eJ as unwrapDeksFromBlob, eK as unwrapDeksFromPaperEntry, eM as unwrapMagicLinkGrant, eZ as updateAuthenticator, e_ as updateKeyringIdentity, eR as writeMagicLinkGrant } from '../types-BoFFiskX.js';
-import '../lazy-builder-Rpd-V3jP.js';
-import '../predicate-Dnu81tsS.js';
-import '../strategy-DSTrsZ8t.js';
+import { aW as NoydbStore, aU as UnlockedKeyring } from '../types-DLfWFr6U.js';
+export { be as BundleRecipient, ck as EnrollAuthenticatorOptions, cl as EnrollAuthenticatorWrappingDEKsOptions, cm as EnrollAuthenticatorWrappingKEKOptions, c$ as ListUsersOptions, ds as PaperRecoveryEntry, dA as PresenceHandle, dV as RecoverPassphraseInput, dW as RecoverPassphraseResult, dX as RecoverUserOptions, dY as RecoveryProof, e0 as RotatePassphraseInput, eo as SlotRewrapCeremony, ep as SlotRewrapContext, ey as SyncEngine, eG as SyncTransaction, eW as UpdateAuthenticatorOptions, fe as WrappedDeksBlob, fl as buildRecipientKeyringFile, fm as burnPaperRecoveryEntry, ge as changeSecret, gf as createOwnerKeyring, fq as deriveMagicLinkContentKey, fr as enrollAuthenticator, gg as ensureCollectionDEK, fu as evaluateExportCapability, fv as evaluateImportCapability, fw as findAuthenticator, gh as grant, fx as hasExportCapability, fy as hasImportCapability, fB as isMagicLinkGrantExpired, fG as listMagicLinkGrants, fH as listUsers, fI as listUsersWithEnvelopes, gi as loadKeyring, fK as loadPaperRecoveryEntries, fN as magicLinkGrantRecordId, fO as mintPaperRecoveryEntry, fQ as mintWrappedDeksBlob, gj as persistKeyring, fT as readMagicLinkGrantRecord, fE as recoverPassphrase, fU as recoverUser, fV as removeAuthenticator, gk as revoke, fZ as revokeMagicLinkGrant, fF as rotatePassphrase, f$ as savePaperRecoveryEntries, g3 as unwrapDeksFromBlob, g4 as unwrapDeksFromPaperEntry, g6 as unwrapMagicLinkGrant, gl as updateAuthenticator, gm as updateKeyringIdentity, gd as writeMagicLinkGrant } from '../types-DLfWFr6U.js';
+import '../lazy-builder-ChSqcF5t.js';
+import '../predicate-BmhBSPCH.js';
+import '../strategy-54eIwox5.js';
+import '../errors-Dkc_fi-S.js';
 import '../strategy-BSxFXGzb.js';
-import '../index-BCKdioeh.js';
+import '../index-BMmajblo.js';
+import '../index-Bm9hIY7t.js';
 import '@noy-db/attestation';
 
 /**

package/dist/team/index.js

@@ -5,7 +5,7 @@ import {
   getCredential,
   listCredentials,
   putCredential
-} from "../chunk-NWZ3I6R6.js";
+} from "../chunk-EYK72OTL.js";
 import {
   burnPaperRecoveryEntry,
   deriveMagicLinkContentKey,
@@ -29,13 +29,13 @@ import {
   unwrapMagicLinkGrant,
   updateAuthenticator,
   writeMagicLinkGrant
-} from "../chunk-EUYOGYGV.js";
-import "../chunk-7BUTTVMR.js";
+} from "../chunk-HYJMAV53.js";
+import "../chunk-F5GWNSE2.js";
 import {
   PresenceHandle,
   SyncEngine,
   SyncTransaction
-} from "../chunk-3Y53S2SA.js";
+} from "../chunk-UU6M64HI.js";
 import {
   buildRecipientKeyringFile,
   changeSecret,
@@ -52,11 +52,11 @@ import {
   persistKeyring,
   revoke,
   updateKeyringIdentity
-} from "../chunk-Q6W2CMEJ.js";
+} from "../chunk-FRRJIUSI.js";
 import "../chunk-2QR2PQTT.js";
-import "../chunk-YS3POABP.js";
-import "../chunk-2PAQNPE3.js";
-import "../chunk-W3XXT26A.js";
+import "../chunk-TA6HPKWQ.js";
+import "../chunk-37VGJM3T.js";
+import "../chunk-OTWT6BAJ.js";
 export {
   PresenceHandle,
   SYNC_CREDENTIALS_COLLECTION,

package/dist/transition-guard-D4bfIAiW.d.ts

@@ -0,0 +1,165 @@
+import { an as GuardStrategy, ar as GuardStrategyHandle, ao as GuardChange, ap as GuardContext } from './types-DLfWFr6U.js';
+
+/**
+ * Register a guard for a collection. Guards run on every `put()` /
+ * `delete()` for the named collection (after permissions, before
+ * encryption) and may:
+ *
+ *   - `check` — block writes by throwing (typically `RecordLockedError`)
+ *   - `frozenFields` — freeze specific fields once a condition is true
+ *   - `amendment` — declare an authorized-override path with invariant
+ *
+ * Pass the returned handle to `createNoydb({ strategies: [...] })`.
+ *
+ * @see docs/superpowers/specs/2026-05-18-guards-design.md
+ */
+declare function withGuard<T extends Record<string, unknown>>(strategy: GuardStrategy<T>): GuardStrategyHandle<T>;
+
+/**
+ * `immutableGuard` — declarative WORM / append-only sugar over the guard
+ * subsystem.
+ *
+ * Issued fiscal documents (invoices, DDTs) must be immutable after issue.
+ * That is expressible today with a hand-rolled `withGuard` (block on
+ * `check`/`onDelete`, allow an admin `amendment`), but the boilerplate is
+ * repetitive and easy to get subtly wrong. `immutableGuard` generates
+ * exactly that guard from a declarative config, reusing the guard
+ * machinery wholesale — `check`/`onDelete` rejection, the ledgered
+ * `amendment` override, and composition with `periods`/`history`.
+ *
+ * ```ts
+ * createNoydb({ guardStrategies: [
+ *   immutableGuard({
+ *     collection: 'invoices',
+ *     after: (r) => r.status === 'issued',   // immutable once issued
+ *   }),
+ * ] })
+ * ```
+ *
+ * A record is mutable until `after(record)` holds; from then on, updates
+ * and deletes throw `RecordLockedError` unless performed inside an
+ * `amendment` transaction by an authorized role (the override is
+ * ledgered by the guard amendment mechanism). `appendOnly: true` is
+ * shorthand for `after: () => true` — immutable from creation.
+ */
+
+interface ImmutableGuardConfig<T extends Record<string, unknown>> {
+    /** The collection to make WORM. */
+    collection: string;
+    /**
+     * A record becomes immutable once this predicate holds. Evaluated on
+     * the *existing* (already-persisted) record, so the write that first
+     * makes it true is still allowed; subsequent writes are blocked.
+     * Mutually exclusive with `appendOnly`.
+     */
+    after?: (record: T) => boolean;
+    /** Shorthand for `after: () => true` — immutable from creation. */
+    appendOnly?: boolean;
+    /** Roles permitted to override via an amendment transaction. Default `['admin', 'owner']`. */
+    amendmentRoles?: ReadonlyArray<'admin' | 'owner'>;
+    /**
+     * Optional set-level invariant run over the amendment change-set after
+     * the writes execute. Signature matches `GuardStrategy.amendment.invariant`
+     * exactly: it receives every {before, after} pair touching this
+     * collection in the amendment plus the guard context; throwing reverts
+     * the whole amendment and surfaces as `InvariantError`.
+     *
+     * Use this to keep a constraint inviolable EVEN under amendment — e.g.
+     * forbid deleting an issued document by re-throwing on any
+     * `before !== null && after === null` change, or assert a cross-record
+     * sum is preserved. When omitted the amendment is unconditionally
+     * allowed (the amendment itself is the sanctioned, ledgered override) —
+     * this is the backward-compatible default.
+     */
+    amendmentInvariant?: (changes: ReadonlyArray<GuardChange<T>>, ctx: GuardContext<T>) => Promise<void> | void;
+}
+/**
+ * Build an immutability guard. Pass the returned handle to
+ * `createNoydb({ guardStrategies: [...] })`.
+ */
+declare function immutableGuard<T extends Record<string, unknown>>(config: ImmutableGuardConfig<T>): GuardStrategyHandle<T>;
+
+/**
+ * `transitionGuard` — declarative state-machine sugar over the guard
+ * subsystem.
+ *
+ * Any record with a lifecycle field (invoice `status`, order state,
+ * ticket workflow, subscription phase) needs transition validation: a
+ * write may only move the field along a declared arc. That is expressible
+ * with a hand-rolled `withGuard({ check })`, but every consumer
+ * re-implements the same graph lookup + error. `transitionGuard`
+ * generates exactly that guard from a state graph, reusing the guard
+ * machinery wholesale — `check` rejection, the ledgered `amendment`
+ * override, and composition with `periods`/`history`.
+ *
+ * It generalizes {@link immutableGuard}: WORM is the special case "every
+ * state has no outgoing arcs", i.e. `transitions` mapping each state to `[]`.
+ *
+ * ```ts
+ * createNoydb({ guardStrategies: [
+ *   transitionGuard<Sale>({
+ *     collection: 'sales', field: 'status',
+ *     transitions: {                          // absence of an arc = forbidden
+ *       draft: ['to_verify', 'cancelled'],
+ *       to_verify: ['proforma', 'draft', 'cancelled'],
+ *       proforma: ['invoiced', 'cancelled'],
+ *       invoiced: ['paid'], paid: [], cancelled: [],
+ *     },
+ *     initial: ['draft', 'to_verify'],        // allowed status on insert
+ *   }),
+ * ] })
+ * ```
+ *
+ * Semantics:
+ * - **Insert** (`ctx.existing === null`): `incoming[field]` must be in
+ *   `initial`. When `initial` is omitted, any value is allowed on insert.
+ * - **Update**: the arc `(existing[field] → incoming[field])` must be
+ *   listed in `transitions[from]`, else `IllegalTransitionError`. A
+ *   same-value write (`from === to`) is allowed when `allowIdempotent`
+ *   (default `true`) — so writes that touch other fields without moving
+ *   state pass.
+ * - **Override**: inside an `amendment` transaction by an authorized role
+ *   the check is skipped and the change is ledgered (mirrors every guard).
+ *
+ * The status graph is caller-supplied data — no UI, no domain logic.
+ */
+
+interface TransitionGuardConfig<T extends Record<string, unknown>> {
+    /** The collection whose state field is governed. */
+    collection: string;
+    /** The state field on the record (e.g. `'status'`). */
+    field: keyof T & string;
+    /**
+     * The transition graph: each state maps to the states it may move to.
+     * A state absent from the map (or mapped to `[]`) is terminal — no
+     * outgoing arc, so any non-idempotent write from it is rejected.
+     */
+    transitions: Readonly<Record<string, readonly string[]>>;
+    /**
+     * States allowed as the initial value on insert (`existing === null`).
+     * Omit to allow any value on insert.
+     */
+    initial?: readonly string[];
+    /**
+     * Allow a same-value write (`from === to`) on update. Default `true` —
+     * lets a put that changes other fields, but not the state, through.
+     */
+    allowIdempotent?: boolean;
+    /** Roles permitted to override via an amendment transaction. Default `['admin', 'owner']`. */
+    amendmentRoles?: ReadonlyArray<'admin' | 'owner'>;
+    /**
+     * Optional set-level invariant run over the amendment change-set after
+     * the writes execute. Signature matches `GuardStrategy.amendment.invariant`
+     * exactly. When omitted the amendment is unconditionally allowed (the
+     * amendment itself is the sanctioned, ledgered override) — the
+     * backward-compatible default. Mirrors {@link immutableGuard}.
+     */
+    amendmentInvariant?: (changes: ReadonlyArray<GuardChange<T>>, ctx: GuardContext<T>) => Promise<void> | void;
+}
+/**
+ * Build a state-machine transition guard. Pass the returned handle to
+ * `createNoydb({ guardStrategies: [...] })`.
+ */
+declare function transitionGuard<T extends Record<string, unknown>>(config: TransitionGuardConfig<T>): GuardStrategyHandle<T>;
+
+export { type ImmutableGuardConfig as I, type TransitionGuardConfig as T, immutableGuard as i, transitionGuard as t, withGuard as w };

package/dist/transition-guard-Dmpqzg-_.d.cts

@@ -0,0 +1,165 @@
+import { an as GuardStrategy, ar as GuardStrategyHandle, ao as GuardChange, ap as GuardContext } from './types-DyOI6XZ_.cjs';
+
+/**
+ * Register a guard for a collection. Guards run on every `put()` /
+ * `delete()` for the named collection (after permissions, before
+ * encryption) and may:
+ *
+ *   - `check` — block writes by throwing (typically `RecordLockedError`)
+ *   - `frozenFields` — freeze specific fields once a condition is true
+ *   - `amendment` — declare an authorized-override path with invariant
+ *
+ * Pass the returned handle to `createNoydb({ strategies: [...] })`.
+ *
+ * @see docs/superpowers/specs/2026-05-18-guards-design.md
+ */
+declare function withGuard<T extends Record<string, unknown>>(strategy: GuardStrategy<T>): GuardStrategyHandle<T>;
+
+/**
+ * `immutableGuard` — declarative WORM / append-only sugar over the guard
+ * subsystem.
+ *
+ * Issued fiscal documents (invoices, DDTs) must be immutable after issue.
+ * That is expressible today with a hand-rolled `withGuard` (block on
+ * `check`/`onDelete`, allow an admin `amendment`), but the boilerplate is
+ * repetitive and easy to get subtly wrong. `immutableGuard` generates
+ * exactly that guard from a declarative config, reusing the guard
+ * machinery wholesale — `check`/`onDelete` rejection, the ledgered
+ * `amendment` override, and composition with `periods`/`history`.
+ *
+ * ```ts
+ * createNoydb({ guardStrategies: [
+ *   immutableGuard({
+ *     collection: 'invoices',
+ *     after: (r) => r.status === 'issued',   // immutable once issued
+ *   }),
+ * ] })
+ * ```
+ *
+ * A record is mutable until `after(record)` holds; from then on, updates
+ * and deletes throw `RecordLockedError` unless performed inside an
+ * `amendment` transaction by an authorized role (the override is
+ * ledgered by the guard amendment mechanism). `appendOnly: true` is
+ * shorthand for `after: () => true` — immutable from creation.
+ */
+
+interface ImmutableGuardConfig<T extends Record<string, unknown>> {
+    /** The collection to make WORM. */
+    collection: string;
+    /**
+     * A record becomes immutable once this predicate holds. Evaluated on
+     * the *existing* (already-persisted) record, so the write that first
+     * makes it true is still allowed; subsequent writes are blocked.
+     * Mutually exclusive with `appendOnly`.
+     */
+    after?: (record: T) => boolean;
+    /** Shorthand for `after: () => true` — immutable from creation. */
+    appendOnly?: boolean;
+    /** Roles permitted to override via an amendment transaction. Default `['admin', 'owner']`. */
+    amendmentRoles?: ReadonlyArray<'admin' | 'owner'>;
+    /**
+     * Optional set-level invariant run over the amendment change-set after
+     * the writes execute. Signature matches `GuardStrategy.amendment.invariant`
+     * exactly: it receives every {before, after} pair touching this
+     * collection in the amendment plus the guard context; throwing reverts
+     * the whole amendment and surfaces as `InvariantError`.
+     *
+     * Use this to keep a constraint inviolable EVEN under amendment — e.g.
+     * forbid deleting an issued document by re-throwing on any
+     * `before !== null && after === null` change, or assert a cross-record
+     * sum is preserved. When omitted the amendment is unconditionally
+     * allowed (the amendment itself is the sanctioned, ledgered override) —
+     * this is the backward-compatible default.
+     */
+    amendmentInvariant?: (changes: ReadonlyArray<GuardChange<T>>, ctx: GuardContext<T>) => Promise<void> | void;
+}
+/**
+ * Build an immutability guard. Pass the returned handle to
+ * `createNoydb({ guardStrategies: [...] })`.
+ */
+declare function immutableGuard<T extends Record<string, unknown>>(config: ImmutableGuardConfig<T>): GuardStrategyHandle<T>;
+
+/**
+ * `transitionGuard` — declarative state-machine sugar over the guard
+ * subsystem.
+ *
+ * Any record with a lifecycle field (invoice `status`, order state,
+ * ticket workflow, subscription phase) needs transition validation: a
+ * write may only move the field along a declared arc. That is expressible
+ * with a hand-rolled `withGuard({ check })`, but every consumer
+ * re-implements the same graph lookup + error. `transitionGuard`
+ * generates exactly that guard from a state graph, reusing the guard
+ * machinery wholesale — `check` rejection, the ledgered `amendment`
+ * override, and composition with `periods`/`history`.
+ *
+ * It generalizes {@link immutableGuard}: WORM is the special case "every
+ * state has no outgoing arcs", i.e. `transitions` mapping each state to `[]`.
+ *
+ * ```ts
+ * createNoydb({ guardStrategies: [
+ *   transitionGuard<Sale>({
+ *     collection: 'sales', field: 'status',
+ *     transitions: {                          // absence of an arc = forbidden
+ *       draft: ['to_verify', 'cancelled'],
+ *       to_verify: ['proforma', 'draft', 'cancelled'],
+ *       proforma: ['invoiced', 'cancelled'],
+ *       invoiced: ['paid'], paid: [], cancelled: [],
+ *     },
+ *     initial: ['draft', 'to_verify'],        // allowed status on insert
+ *   }),
+ * ] })
+ * ```
+ *
+ * Semantics:
+ * - **Insert** (`ctx.existing === null`): `incoming[field]` must be in
+ *   `initial`. When `initial` is omitted, any value is allowed on insert.
+ * - **Update**: the arc `(existing[field] → incoming[field])` must be
+ *   listed in `transitions[from]`, else `IllegalTransitionError`. A
+ *   same-value write (`from === to`) is allowed when `allowIdempotent`
+ *   (default `true`) — so writes that touch other fields without moving
+ *   state pass.
+ * - **Override**: inside an `amendment` transaction by an authorized role
+ *   the check is skipped and the change is ledgered (mirrors every guard).
+ *
+ * The status graph is caller-supplied data — no UI, no domain logic.
+ */
+
+interface TransitionGuardConfig<T extends Record<string, unknown>> {
+    /** The collection whose state field is governed. */
+    collection: string;
+    /** The state field on the record (e.g. `'status'`). */
+    field: keyof T & string;
+    /**
+     * The transition graph: each state maps to the states it may move to.
+     * A state absent from the map (or mapped to `[]`) is terminal — no
+     * outgoing arc, so any non-idempotent write from it is rejected.
+     */
+    transitions: Readonly<Record<string, readonly string[]>>;
+    /**
+     * States allowed as the initial value on insert (`existing === null`).
+     * Omit to allow any value on insert.
+     */
+    initial?: readonly string[];
+    /**
+     * Allow a same-value write (`from === to`) on update. Default `true` —
+     * lets a put that changes other fields, but not the state, through.
+     */
+    allowIdempotent?: boolean;
+    /** Roles permitted to override via an amendment transaction. Default `['admin', 'owner']`. */
+    amendmentRoles?: ReadonlyArray<'admin' | 'owner'>;
+    /**
+     * Optional set-level invariant run over the amendment change-set after
+     * the writes execute. Signature matches `GuardStrategy.amendment.invariant`
+     * exactly. When omitted the amendment is unconditionally allowed (the
+     * amendment itself is the sanctioned, ledgered override) — the
+     * backward-compatible default. Mirrors {@link immutableGuard}.
+     */
+    amendmentInvariant?: (changes: ReadonlyArray<GuardChange<T>>, ctx: GuardContext<T>) => Promise<void> | void;
+}
+/**
+ * Build a state-machine transition guard. Pass the returned handle to
+ * `createNoydb({ guardStrategies: [...] })`.
+ */
+declare function transitionGuard<T extends Record<string, unknown>>(config: TransitionGuardConfig<T>): GuardStrategyHandle<T>;
+
+export { type ImmutableGuardConfig as I, type TransitionGuardConfig as T, immutableGuard as i, transitionGuard as t, withGuard as w };

package/dist/tx/index.cjs

@@ -125,14 +125,21 @@ var init_executor = __esm({
        * Compare existing vs incoming for each `frozenFields.fields` entry
        * when `frozenFields.when(existing)` is true. Throws
        * `FieldFrozenError` listing every changed frozen field.
+       *
+       * @param skipFields — field names that are schema-owned computed fields.
+       *   These are excluded from the comparison because `incoming` carries the
+       *   raw user input (computed fields not yet evaluated), so comparing
+       *   `existing[field]` vs `incoming[field]` would always look like a
+       *   change even when the computed result is unchanged.
        */
-      async checkFrozenFields(guard, id, existing, incoming) {
+      async checkFrozenFields(guard, id, existing, incoming, skipFields) {
         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 (skipFields?.has(String(f))) continue;
           if (existing[f] !== incoming[f]) {
             if (!deepEqual(existing[f], incoming[f])) changed.push(String(f));
           }
@@ -174,7 +181,35 @@ module.exports = __toCommonJS(tx_exports);
 
 // 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 = [];
   /**
@@ -183,7 +218,7 @@ var TxContext = class {
    * 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 (#133).
+   * main staged ops.
    */
   _executed = [];
   /** @internal */
@@ -300,7 +335,7 @@ var TxCollection = class {
     this._ctx._ops.push(op);
   }
 };
-async function runTransaction(db, fn, options) {
+async function runTransaction(db, fn, options, txInvariants) {
   if (options?.amendment) {
     if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
       throw new ValidationError(
@@ -324,12 +359,19 @@ async function runTransaction(db, fn, options) {
   }
   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;
@@ -427,6 +469,58 @@ async function runTransaction(db, fn, options) {
       );
     }
   }
+  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) {
@@ -449,9 +543,65 @@ 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 };
+function withTransactions(opts) {
+  const invariants = opts?.invariants ?? [];
+  return {
+    runTransaction: (db, fn, options) => runTransaction(db, fn, options, invariants),
+    runDryRun
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {