@directive-run/core 1.7.0 → 1.9.0

package/dist/index.d.cts

@@ -526,6 +526,295 @@ declare const MAX_SWEEP_POINTS = 10000;
  */
 declare function sweepUnder<F = Record<string, unknown>>(options: SweepUnderOptions<F>): SweepReport;
 
+/**
+ * Structural diff between two snapshots of a system's constraint `whenSpec`
+ * map. The "git diff for business rules" — operates on the predicate AST
+ * instead of source-text lines.
+ *
+ * A predicate is a tree of leaf clauses (`{ fact: operator(value) }`) and
+ * combinators (`$all` / `$any` / `$not`). `diffRules` flattens both trees
+ * into path-keyed leaf lists and compares: missing path → added/removed,
+ * same path with different operand → changed (with relaxed/tightened
+ * classification for numeric thresholds).
+ *
+ * Pure module — imports only utils. No engine / store / predicate-runtime
+ * dependency: predicates are walked as plain JSON.
+ */
+/** A leaf clause extracted from a predicate tree, keyed by its dotted path. */
+interface LeafClause {
+    /** Dotted path through the predicate. E.g. `phase`, `$all[0].elapsed`, `$not.paused`. */
+    path: string;
+    /** Operator name. `$eq` is implied for bare-value equality. */
+    op: string;
+    /** Operand. */
+    value: unknown;
+}
+/** Kind of change observed for a single clause. */
+type ChangeKind = "added" | "removed" | "changed" | "relaxed" | "tightened";
+/** A single change between two predicates at a specific path. */
+interface Change {
+    path: string;
+    kind: ChangeKind;
+    before?: {
+        op: string;
+        value: unknown;
+    };
+    after?: {
+        op: string;
+        value: unknown;
+    };
+}
+/** Status of a single constraint across the two snapshots. */
+type ConstraintStatus = "added" | "removed" | "changed" | "unchanged";
+interface ConstraintDiff {
+    id: string;
+    status: ConstraintStatus;
+    /** Empty for `unchanged`. For `added` / `removed`, every leaf is listed once. */
+    changes: Change[];
+}
+interface RulesDiffReport {
+    constraints: ConstraintDiff[];
+    summary: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+        totalClauseChanges: number;
+    };
+}
+interface DiffRulesOptions {
+    before: RulesMapInput;
+    after: RulesMapInput;
+}
+/**
+ * Accepted shapes for the `before` / `after` predicate maps:
+ *   - A plain map `{ [constraintId]: whenSpec }`
+ *   - The `system.inspect().constraints` array form `Array<{ id, whenSpec? }>`
+ *   - Either wrapped as `{ constraints: <one-of-the-above> }`
+ *
+ * Anything else throws at `toRulesMap` so a bad input fails loud.
+ */
+type RulesMapInput = unknown;
+/**
+ * Coerce supported input shapes into a flat `Record<constraintId, whenSpec>`.
+ * Constraints without a `whenSpec` (function-form `when`) are dropped with
+ * an undefined entry so callers can distinguish them from absent constraints
+ * if they care; the diff treats `undefined` as "no data" and skips clause
+ * walking.
+ */
+declare function toRulesMap(raw: RulesMapInput): Record<string, unknown>;
+/**
+ * Walk a predicate tree and emit every leaf clause with its dotted path.
+ * Combinators (`$all` / `$any` / `$not`) become indexed path segments.
+ * Bare-value equality (`{ phase: "red" }`) emits as `op: "$eq"`.
+ *
+ * Array-form predicates (`[{ fact, op, value }, ...]`) are also accepted —
+ * each clause's `fact` becomes the path, the operator is `op`, and the
+ * value is `value`.
+ *
+ * **What gets dropped:** non-object combinator children (e.g. `$not: "red"`
+ * with a string operand instead of a predicate object), function-form
+ * predicates (the engine accepts a function for `when`; this walker only
+ * sees data), and bare primitive predicates (a top-level `true` or `"x"`).
+ * The walker is a tree visitor — anything not shaped like a predicate node
+ * is silently skipped, never thrown on.
+ */
+declare function flattenPredicate(spec: unknown, pathPrefix?: string, out?: LeafClause[]): LeafClause[];
+/**
+ * Diff two snapshots of a system's constraint whenSpec map.
+ *
+ * @example
+ * ```ts
+ * const report = diffRules({
+ *   before: { blockCheckout: { cartTotal: { $gte: 100 } } },
+ *   after:  { blockCheckout: { cartTotal: { $gte: 50 } } },
+ * });
+ *
+ * report.constraints[0].status;          // "changed"
+ * report.constraints[0].changes[0].kind; // "relaxed"
+ * report.summary.totalClauseChanges;     // 1
+ * ```
+ *
+ * The input shape is forgiving — either a flat `{ id: whenSpec }` map, the
+ * `system.inspect().constraints` array form, or either wrapped as
+ * `{ constraints: ... }`. Constraints whose `when` is a function (no
+ * `whenSpec`) are tracked as added/removed but cannot be clause-diffed
+ * (the function form is opaque).
+ */
+declare function diffRules(options: DiffRulesOptions): RulesDiffReport;
+/**
+ * Diff two predicate trees and return the list of leaf-level changes.
+ * Exported for reuse beyond the full per-constraint report.
+ */
+declare function diffClauses(before: unknown, after: unknown): Change[];
+
+/**
+ * Compile a `FactPredicate` to a parameterized Postgres-style SQL WHERE
+ * clause. The same predicate that gates a constraint on the client can
+ * filter rows on the server — *one source of truth, two execution sites*.
+ *
+ * Pure transformation. No engine, no driver, no string concatenation of
+ * user values (all operands flow through the parameter array → safe
+ * against SQL injection by construction).
+ */
+
+interface PredicateToSqlOptions {
+    /** Table to query. Validated against the same identifier rule as columns. */
+    table: string;
+    /**
+     * Allowlist of fact / column keys the predicate may reference. STRONGLY
+     * RECOMMENDED for any predicate that crosses a trust boundary (AI
+     * generation, user input, JSON-over-the-wire). Without an allowlist, a
+     * predicate may reference any column the table has.
+     */
+    allowedKeys?: readonly string[];
+    /**
+     * Customize the `SELECT` projection. Default `"*"`. Accepts:
+     *   - `"*"`
+     *   - a column identifier (`"id"` or `"users.id"`)
+     *   - an array of column identifiers (`["id", "name"]`) — joined with `,`
+     * Free-form strings (e.g. `"COUNT(*)"`) are rejected — build the wrapper
+     * SQL manually with {@link predicateToWhere} for those cases.
+     */
+    select?: string | readonly string[];
+    /**
+     * Parameter placeholder generator. Default is Postgres-style `$1`, `$2`.
+     * Pass `() => "?"` for MySQL/SQLite, or supply your own scheme.
+     */
+    placeholder?: (oneBasedIndex: number) => string;
+}
+interface PredicateToSqlResult {
+    /** Full `SELECT … FROM table WHERE …` statement. */
+    sql: string;
+    /** Just the `WHERE` clause body (without the literal `WHERE`). */
+    where: string;
+    /** Parameters, in `$1`-then-`$2`-then-… order. */
+    params: unknown[];
+}
+/**
+ * Compile a {@link FactPredicate} to a parameterized SQL statement.
+ *
+ * Operand values **never** appear in the SQL string — they flow through
+ * the `params` array. Table and column identifiers are regex-validated.
+ *
+ * @example
+ * ```ts
+ * const where = { age: { $gte: 18 }, status: { $in: ["active", "pending"] } };
+ *
+ * predicateToSQL(where, { table: "users" });
+ * // → { sql: "SELECT * FROM users WHERE (age >= $1 AND status = ANY($2))",
+ * //     where: "(age >= $1 AND status = ANY($2))",
+ * //     params: [18, ["active", "pending"]] }
+ *
+ * // MySQL/SQLite placeholder:
+ * predicateToSQL(where, { table: "users", placeholder: () => "?" });
+ *
+ * // Recommended for AI/user-supplied predicates:
+ * predicateToSQL(where, { table: "users", allowedKeys: ["age", "status"] });
+ * ```
+ */
+declare function predicateToSQL<F = Record<string, unknown>>(predicate: FactPredicate<F>, options: PredicateToSqlOptions): PredicateToSqlResult;
+/**
+ * Lower-level variant — returns just the `WHERE` clause body and the
+ * `params` array, no `SELECT ... FROM` wrapper. Use this when you need
+ * to embed the WHERE in a larger query (JOIN, UPDATE, DELETE, COUNT).
+ *
+ * @example
+ * ```ts
+ * const { where, params } = predicateToWhere({ age: { $gte: 18 } });
+ * await db.query(`UPDATE users SET tier = 'adult' WHERE ${where}`, params);
+ * ```
+ */
+declare function predicateToWhere<F = Record<string, unknown>>(predicate: FactPredicate<F>, options?: Omit<PredicateToSqlOptions, "table" | "select">): {
+    where: string;
+    params: unknown[];
+};
+
+/**
+ * Compile a `FactPredicate` to a MongoDB query document. Most of
+ * Directive's predicate operator set is already Mongo-compatible by
+ * design — this translator handles the few ops that need rewriting
+ * (`$startsWith`/`$endsWith`/`$contains` → `$regex`, `$between` →
+ * `$gte`+`$lte`, `$matches` → `$regex`/`$options`).
+ *
+ * Combinators map cleanly: `$all` → `$and`, `$any` → `$or`, `$not` → `$nor`.
+ *
+ * Pure transformation. No driver dependency.
+ */
+
+interface PredicateToMongoOptions {
+    /**
+     * Allowlist of fact / field keys the predicate may reference. STRONGLY
+     * RECOMMENDED for any predicate that crosses a trust boundary.
+     */
+    allowedKeys?: readonly string[];
+    /**
+     * Allow `.` in field names (for sub-document traversal: `"user.role"`).
+     * Default is `false` — `.` is rejected so the predicate cannot
+     * accidentally read sub-document fields the developer did not anticipate.
+     */
+    allowDottedPaths?: boolean;
+}
+/**
+ * Compile a {@link FactPredicate} to a MongoDB query document.
+ *
+ * Field names are validated to NOT start with `$` (which would land
+ * `$where` and other server-side JS evaluation operators directly in the
+ * query — an injection vector for AI/user-generated predicates).
+ *
+ * @example
+ * ```ts
+ * predicateToMongo({ age: { $gte: 18 }, status: { $in: ["active", "pending"] } })
+ * // → { age: { $gte: 18 }, status: { $in: ["active", "pending"] } }
+ *
+ * predicateToMongo({ name: { $startsWith: "Al" } })
+ * // → { name: { $regex: "^Al" } }
+ *
+ * predicateToMongo({ $any: [{ tier: "gold" }, { score: { $gte: 100 } }] })
+ * // → { $or: [{ tier: "gold" }, { score: { $gte: 100 } }] }
+ * ```
+ */
+declare function predicateToMongo<F = Record<string, unknown>>(predicate: FactPredicate<F>, options?: PredicateToMongoOptions): Record<string, unknown>;
+
+/**
+ * Compile a `FactPredicate` to a PostgREST querystring.
+ *
+ * PostgREST's filter grammar is column-scoped: `?age=gte.18&status=in.(active,pending)`.
+ * Logical groups use `and=(...)` / `or=(...)` / `not.and=(...)`.
+ *
+ * Reference: https://postgrest.org/en/stable/api.html#operators
+ */
+
+interface PredicateToPostgrestOptions {
+    /** Allowlist of column keys the predicate may reference. */
+    allowedKeys?: readonly string[];
+    /**
+     * Encoding mode for the returned string.
+     *  - `"querystring"` (default): a full querystring without a leading `?`,
+     *    with each clause value URL-encoded — drops straight into `fetch`.
+     *  - `"raw"`: the same content, leaving `(`, `)`, `,` unencoded for
+     *    readability. Use this only when you'll encode the result yourself.
+     */
+    mode?: "querystring" | "raw";
+}
+/**
+ * Compile a {@link FactPredicate} to a PostgREST querystring.
+ *
+ * @example
+ * ```ts
+ * predicateToPostgrest({ age: { $gte: 18 }, status: { $in: ["active", "pending"] } })
+ * // → "age=gte.18&status=in.%28active%2Cpending%29"
+ *
+ * // Raw mode for debugging / building URLs by hand:
+ * predicateToPostgrest({ age: { $gte: 18 } }, { mode: "raw" })
+ * // → "age=gte.18"
+ *
+ * predicateToPostgrest({ $any: [{ tier: "gold" }, { score: { $gte: 100 } }] }, { mode: "raw" })
+ * // → "or=(tier.eq.gold,score.gte.100)"
+ * ```
+ */
+declare function predicateToPostgrest<F = Record<string, unknown>>(predicate: FactPredicate<F>, options?: PredicateToPostgrestOptions): string;
+
 /** Brand symbol for branded types */
 declare const Brand: unique symbol;
 /** Branded type - adds a unique brand to a base type */
@@ -1786,4 +2075,4 @@ declare const Backoff: {
     readonly Exponential: "exponential";
 };
 
-export { Backoff, type Branded, type ChainableSchemaType, ClauseResult, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleDeps, DefinitionMeta, ErrorBoundaryConfig, type ExtendedSchemaType, FactPredicate, FactTemplate, Facts, MAX_REPLAY_FRAMES, MAX_SWEEP_POINTS, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, PatchSpec, Plugin, type PredicateBacktestReport, type ReplayDiffSample, type ReplayFrame, type ReplayUnderOptions, Requirement, RequirementSet, type RequirementTypeStatus, RequirementWithId, SchemaType, type SignalClock, SingleModuleSystem, type SweepHole, type SweepPoint, type SweepReport, type SweepUnderOptions, type TimerFactOpts, type TimerFactState, TraceOption, applyPatch, completeTimer, createModule, createModuleFactory, createRequirementStatusPlugin, createStatusHook, createSystem, createSystemWithStatus, defaultClock, elapsedMs, evaluateKeySelector, evaluatePredicate, evaluatePredicateExplained, evaluateTemplate, extractDeps, extractTemplateKeys, forType, framesFromHistory, framesFromSnapshots, generateRequirementId, initialTimerState, isPredicate, isRequirementType, isTemplate, memoizePredicate, pauseTimer, realClock, registerRepeat, remainingMs, replayUnder, req, resetTimer, resumeTimer, startTimer, sweepUnder, t, tickTimer, timerOps, toReplayFrames, validatePredicate, virtualClock };
+export { Backoff, type Branded, type ChainableSchemaType, type Change, type ChangeKind, ClauseResult, type ConstraintDiff, type ConstraintStatus, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleDeps, DefinitionMeta, type DiffRulesOptions, ErrorBoundaryConfig, type ExtendedSchemaType, FactPredicate, FactTemplate, Facts, type LeafClause, MAX_REPLAY_FRAMES, MAX_SWEEP_POINTS, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, PatchSpec, Plugin, type PredicateBacktestReport, type PredicateToMongoOptions, type PredicateToPostgrestOptions, type PredicateToSqlOptions, type PredicateToSqlResult, type ReplayDiffSample, type ReplayFrame, type ReplayUnderOptions, Requirement, RequirementSet, type RequirementTypeStatus, RequirementWithId, type RulesDiffReport, type RulesMapInput, SchemaType, type SignalClock, SingleModuleSystem, type SweepHole, type SweepPoint, type SweepReport, type SweepUnderOptions, type TimerFactOpts, type TimerFactState, TraceOption, applyPatch, completeTimer, createModule, createModuleFactory, createRequirementStatusPlugin, createStatusHook, createSystem, createSystemWithStatus, defaultClock, diffClauses, diffRules, elapsedMs, evaluateKeySelector, evaluatePredicate, evaluatePredicateExplained, evaluateTemplate, extractDeps, extractTemplateKeys, flattenPredicate, forType, framesFromHistory, framesFromSnapshots, generateRequirementId, initialTimerState, isPredicate, isRequirementType, isTemplate, memoizePredicate, pauseTimer, predicateToMongo, predicateToPostgrest, predicateToSQL, predicateToWhere, realClock, registerRepeat, remainingMs, replayUnder, req, resetTimer, resumeTimer, startTimer, sweepUnder, t, tickTimer, timerOps, toReplayFrames, toRulesMap, validatePredicate, virtualClock };

package/dist/index.d.ts

@@ -526,6 +526,295 @@ declare const MAX_SWEEP_POINTS = 10000;
  */
 declare function sweepUnder<F = Record<string, unknown>>(options: SweepUnderOptions<F>): SweepReport;
 
+/**
+ * Structural diff between two snapshots of a system's constraint `whenSpec`
+ * map. The "git diff for business rules" — operates on the predicate AST
+ * instead of source-text lines.
+ *
+ * A predicate is a tree of leaf clauses (`{ fact: operator(value) }`) and
+ * combinators (`$all` / `$any` / `$not`). `diffRules` flattens both trees
+ * into path-keyed leaf lists and compares: missing path → added/removed,
+ * same path with different operand → changed (with relaxed/tightened
+ * classification for numeric thresholds).
+ *
+ * Pure module — imports only utils. No engine / store / predicate-runtime
+ * dependency: predicates are walked as plain JSON.
+ */
+/** A leaf clause extracted from a predicate tree, keyed by its dotted path. */
+interface LeafClause {
+    /** Dotted path through the predicate. E.g. `phase`, `$all[0].elapsed`, `$not.paused`. */
+    path: string;
+    /** Operator name. `$eq` is implied for bare-value equality. */
+    op: string;
+    /** Operand. */
+    value: unknown;
+}
+/** Kind of change observed for a single clause. */
+type ChangeKind = "added" | "removed" | "changed" | "relaxed" | "tightened";
+/** A single change between two predicates at a specific path. */
+interface Change {
+    path: string;
+    kind: ChangeKind;
+    before?: {
+        op: string;
+        value: unknown;
+    };
+    after?: {
+        op: string;
+        value: unknown;
+    };
+}
+/** Status of a single constraint across the two snapshots. */
+type ConstraintStatus = "added" | "removed" | "changed" | "unchanged";
+interface ConstraintDiff {
+    id: string;
+    status: ConstraintStatus;
+    /** Empty for `unchanged`. For `added` / `removed`, every leaf is listed once. */
+    changes: Change[];
+}
+interface RulesDiffReport {
+    constraints: ConstraintDiff[];
+    summary: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+        totalClauseChanges: number;
+    };
+}
+interface DiffRulesOptions {
+    before: RulesMapInput;
+    after: RulesMapInput;
+}
+/**
+ * Accepted shapes for the `before` / `after` predicate maps:
+ *   - A plain map `{ [constraintId]: whenSpec }`
+ *   - The `system.inspect().constraints` array form `Array<{ id, whenSpec? }>`
+ *   - Either wrapped as `{ constraints: <one-of-the-above> }`
+ *
+ * Anything else throws at `toRulesMap` so a bad input fails loud.
+ */
+type RulesMapInput = unknown;
+/**
+ * Coerce supported input shapes into a flat `Record<constraintId, whenSpec>`.
+ * Constraints without a `whenSpec` (function-form `when`) are dropped with
+ * an undefined entry so callers can distinguish them from absent constraints
+ * if they care; the diff treats `undefined` as "no data" and skips clause
+ * walking.
+ */
+declare function toRulesMap(raw: RulesMapInput): Record<string, unknown>;
+/**
+ * Walk a predicate tree and emit every leaf clause with its dotted path.
+ * Combinators (`$all` / `$any` / `$not`) become indexed path segments.
+ * Bare-value equality (`{ phase: "red" }`) emits as `op: "$eq"`.
+ *
+ * Array-form predicates (`[{ fact, op, value }, ...]`) are also accepted —
+ * each clause's `fact` becomes the path, the operator is `op`, and the
+ * value is `value`.
+ *
+ * **What gets dropped:** non-object combinator children (e.g. `$not: "red"`
+ * with a string operand instead of a predicate object), function-form
+ * predicates (the engine accepts a function for `when`; this walker only
+ * sees data), and bare primitive predicates (a top-level `true` or `"x"`).
+ * The walker is a tree visitor — anything not shaped like a predicate node
+ * is silently skipped, never thrown on.
+ */
+declare function flattenPredicate(spec: unknown, pathPrefix?: string, out?: LeafClause[]): LeafClause[];
+/**
+ * Diff two snapshots of a system's constraint whenSpec map.
+ *
+ * @example
+ * ```ts
+ * const report = diffRules({
+ *   before: { blockCheckout: { cartTotal: { $gte: 100 } } },
+ *   after:  { blockCheckout: { cartTotal: { $gte: 50 } } },
+ * });
+ *
+ * report.constraints[0].status;          // "changed"
+ * report.constraints[0].changes[0].kind; // "relaxed"
+ * report.summary.totalClauseChanges;     // 1
+ * ```
+ *
+ * The input shape is forgiving — either a flat `{ id: whenSpec }` map, the
+ * `system.inspect().constraints` array form, or either wrapped as
+ * `{ constraints: ... }`. Constraints whose `when` is a function (no
+ * `whenSpec`) are tracked as added/removed but cannot be clause-diffed
+ * (the function form is opaque).
+ */
+declare function diffRules(options: DiffRulesOptions): RulesDiffReport;
+/**
+ * Diff two predicate trees and return the list of leaf-level changes.
+ * Exported for reuse beyond the full per-constraint report.
+ */
+declare function diffClauses(before: unknown, after: unknown): Change[];
+
+/**
+ * Compile a `FactPredicate` to a parameterized Postgres-style SQL WHERE
+ * clause. The same predicate that gates a constraint on the client can
+ * filter rows on the server — *one source of truth, two execution sites*.
+ *
+ * Pure transformation. No engine, no driver, no string concatenation of
+ * user values (all operands flow through the parameter array → safe
+ * against SQL injection by construction).
+ */
+
+interface PredicateToSqlOptions {
+    /** Table to query. Validated against the same identifier rule as columns. */
+    table: string;
+    /**
+     * Allowlist of fact / column keys the predicate may reference. STRONGLY
+     * RECOMMENDED for any predicate that crosses a trust boundary (AI
+     * generation, user input, JSON-over-the-wire). Without an allowlist, a
+     * predicate may reference any column the table has.
+     */
+    allowedKeys?: readonly string[];
+    /**
+     * Customize the `SELECT` projection. Default `"*"`. Accepts:
+     *   - `"*"`
+     *   - a column identifier (`"id"` or `"users.id"`)
+     *   - an array of column identifiers (`["id", "name"]`) — joined with `,`
+     * Free-form strings (e.g. `"COUNT(*)"`) are rejected — build the wrapper
+     * SQL manually with {@link predicateToWhere} for those cases.
+     */
+    select?: string | readonly string[];
+    /**
+     * Parameter placeholder generator. Default is Postgres-style `$1`, `$2`.
+     * Pass `() => "?"` for MySQL/SQLite, or supply your own scheme.
+     */
+    placeholder?: (oneBasedIndex: number) => string;
+}
+interface PredicateToSqlResult {
+    /** Full `SELECT … FROM table WHERE …` statement. */
+    sql: string;
+    /** Just the `WHERE` clause body (without the literal `WHERE`). */
+    where: string;
+    /** Parameters, in `$1`-then-`$2`-then-… order. */
+    params: unknown[];
+}
+/**
+ * Compile a {@link FactPredicate} to a parameterized SQL statement.
+ *
+ * Operand values **never** appear in the SQL string — they flow through
+ * the `params` array. Table and column identifiers are regex-validated.
+ *
+ * @example
+ * ```ts
+ * const where = { age: { $gte: 18 }, status: { $in: ["active", "pending"] } };
+ *
+ * predicateToSQL(where, { table: "users" });
+ * // → { sql: "SELECT * FROM users WHERE (age >= $1 AND status = ANY($2))",
+ * //     where: "(age >= $1 AND status = ANY($2))",
+ * //     params: [18, ["active", "pending"]] }
+ *
+ * // MySQL/SQLite placeholder:
+ * predicateToSQL(where, { table: "users", placeholder: () => "?" });
+ *
+ * // Recommended for AI/user-supplied predicates:
+ * predicateToSQL(where, { table: "users", allowedKeys: ["age", "status"] });
+ * ```
+ */
+declare function predicateToSQL<F = Record<string, unknown>>(predicate: FactPredicate<F>, options: PredicateToSqlOptions): PredicateToSqlResult;
+/**
+ * Lower-level variant — returns just the `WHERE` clause body and the
+ * `params` array, no `SELECT ... FROM` wrapper. Use this when you need
+ * to embed the WHERE in a larger query (JOIN, UPDATE, DELETE, COUNT).
+ *
+ * @example
+ * ```ts
+ * const { where, params } = predicateToWhere({ age: { $gte: 18 } });
+ * await db.query(`UPDATE users SET tier = 'adult' WHERE ${where}`, params);
+ * ```
+ */
+declare function predicateToWhere<F = Record<string, unknown>>(predicate: FactPredicate<F>, options?: Omit<PredicateToSqlOptions, "table" | "select">): {
+    where: string;
+    params: unknown[];
+};
+
+/**
+ * Compile a `FactPredicate` to a MongoDB query document. Most of
+ * Directive's predicate operator set is already Mongo-compatible by
+ * design — this translator handles the few ops that need rewriting
+ * (`$startsWith`/`$endsWith`/`$contains` → `$regex`, `$between` →
+ * `$gte`+`$lte`, `$matches` → `$regex`/`$options`).
+ *
+ * Combinators map cleanly: `$all` → `$and`, `$any` → `$or`, `$not` → `$nor`.
+ *
+ * Pure transformation. No driver dependency.
+ */
+
+interface PredicateToMongoOptions {
+    /**
+     * Allowlist of fact / field keys the predicate may reference. STRONGLY
+     * RECOMMENDED for any predicate that crosses a trust boundary.
+     */
+    allowedKeys?: readonly string[];
+    /**
+     * Allow `.` in field names (for sub-document traversal: `"user.role"`).
+     * Default is `false` — `.` is rejected so the predicate cannot
+     * accidentally read sub-document fields the developer did not anticipate.
+     */
+    allowDottedPaths?: boolean;
+}
+/**
+ * Compile a {@link FactPredicate} to a MongoDB query document.
+ *
+ * Field names are validated to NOT start with `$` (which would land
+ * `$where` and other server-side JS evaluation operators directly in the
+ * query — an injection vector for AI/user-generated predicates).
+ *
+ * @example
+ * ```ts
+ * predicateToMongo({ age: { $gte: 18 }, status: { $in: ["active", "pending"] } })
+ * // → { age: { $gte: 18 }, status: { $in: ["active", "pending"] } }
+ *
+ * predicateToMongo({ name: { $startsWith: "Al" } })
+ * // → { name: { $regex: "^Al" } }
+ *
+ * predicateToMongo({ $any: [{ tier: "gold" }, { score: { $gte: 100 } }] })
+ * // → { $or: [{ tier: "gold" }, { score: { $gte: 100 } }] }
+ * ```
+ */
+declare function predicateToMongo<F = Record<string, unknown>>(predicate: FactPredicate<F>, options?: PredicateToMongoOptions): Record<string, unknown>;
+
+/**
+ * Compile a `FactPredicate` to a PostgREST querystring.
+ *
+ * PostgREST's filter grammar is column-scoped: `?age=gte.18&status=in.(active,pending)`.
+ * Logical groups use `and=(...)` / `or=(...)` / `not.and=(...)`.
+ *
+ * Reference: https://postgrest.org/en/stable/api.html#operators
+ */
+
+interface PredicateToPostgrestOptions {
+    /** Allowlist of column keys the predicate may reference. */
+    allowedKeys?: readonly string[];
+    /**
+     * Encoding mode for the returned string.
+     *  - `"querystring"` (default): a full querystring without a leading `?`,
+     *    with each clause value URL-encoded — drops straight into `fetch`.
+     *  - `"raw"`: the same content, leaving `(`, `)`, `,` unencoded for
+     *    readability. Use this only when you'll encode the result yourself.
+     */
+    mode?: "querystring" | "raw";
+}
+/**
+ * Compile a {@link FactPredicate} to a PostgREST querystring.
+ *
+ * @example
+ * ```ts
+ * predicateToPostgrest({ age: { $gte: 18 }, status: { $in: ["active", "pending"] } })
+ * // → "age=gte.18&status=in.%28active%2Cpending%29"
+ *
+ * // Raw mode for debugging / building URLs by hand:
+ * predicateToPostgrest({ age: { $gte: 18 } }, { mode: "raw" })
+ * // → "age=gte.18"
+ *
+ * predicateToPostgrest({ $any: [{ tier: "gold" }, { score: { $gte: 100 } }] }, { mode: "raw" })
+ * // → "or=(tier.eq.gold,score.gte.100)"
+ * ```
+ */
+declare function predicateToPostgrest<F = Record<string, unknown>>(predicate: FactPredicate<F>, options?: PredicateToPostgrestOptions): string;
+
 /** Brand symbol for branded types */
 declare const Brand: unique symbol;
 /** Branded type - adds a unique brand to a base type */
@@ -1786,4 +2075,4 @@ declare const Backoff: {
     readonly Exponential: "exponential";
 };
 
-export { Backoff, type Branded, type ChainableSchemaType, ClauseResult, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleDeps, DefinitionMeta, ErrorBoundaryConfig, type ExtendedSchemaType, FactPredicate, FactTemplate, Facts, MAX_REPLAY_FRAMES, MAX_SWEEP_POINTS, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, PatchSpec, Plugin, type PredicateBacktestReport, type ReplayDiffSample, type ReplayFrame, type ReplayUnderOptions, Requirement, RequirementSet, type RequirementTypeStatus, RequirementWithId, SchemaType, type SignalClock, SingleModuleSystem, type SweepHole, type SweepPoint, type SweepReport, type SweepUnderOptions, type TimerFactOpts, type TimerFactState, TraceOption, applyPatch, completeTimer, createModule, createModuleFactory, createRequirementStatusPlugin, createStatusHook, createSystem, createSystemWithStatus, defaultClock, elapsedMs, evaluateKeySelector, evaluatePredicate, evaluatePredicateExplained, evaluateTemplate, extractDeps, extractTemplateKeys, forType, framesFromHistory, framesFromSnapshots, generateRequirementId, initialTimerState, isPredicate, isRequirementType, isTemplate, memoizePredicate, pauseTimer, realClock, registerRepeat, remainingMs, replayUnder, req, resetTimer, resumeTimer, startTimer, sweepUnder, t, tickTimer, timerOps, toReplayFrames, validatePredicate, virtualClock };
+export { Backoff, type Branded, type ChainableSchemaType, type Change, type ChangeKind, ClauseResult, type ConstraintDiff, type ConstraintStatus, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleDeps, DefinitionMeta, type DiffRulesOptions, ErrorBoundaryConfig, type ExtendedSchemaType, FactPredicate, FactTemplate, Facts, type LeafClause, MAX_REPLAY_FRAMES, MAX_SWEEP_POINTS, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, PatchSpec, Plugin, type PredicateBacktestReport, type PredicateToMongoOptions, type PredicateToPostgrestOptions, type PredicateToSqlOptions, type PredicateToSqlResult, type ReplayDiffSample, type ReplayFrame, type ReplayUnderOptions, Requirement, RequirementSet, type RequirementTypeStatus, RequirementWithId, type RulesDiffReport, type RulesMapInput, SchemaType, type SignalClock, SingleModuleSystem, type SweepHole, type SweepPoint, type SweepReport, type SweepUnderOptions, type TimerFactOpts, type TimerFactState, TraceOption, applyPatch, completeTimer, createModule, createModuleFactory, createRequirementStatusPlugin, createStatusHook, createSystem, createSystemWithStatus, defaultClock, diffClauses, diffRules, elapsedMs, evaluateKeySelector, evaluatePredicate, evaluatePredicateExplained, evaluateTemplate, extractDeps, extractTemplateKeys, flattenPredicate, forType, framesFromHistory, framesFromSnapshots, generateRequirementId, initialTimerState, isPredicate, isRequirementType, isTemplate, memoizePredicate, pauseTimer, predicateToMongo, predicateToPostgrest, predicateToSQL, predicateToWhere, realClock, registerRepeat, remainingMs, replayUnder, req, resetTimer, resumeTimer, startTimer, sweepUnder, t, tickTimer, timerOps, toReplayFrames, toRulesMap, validatePredicate, virtualClock };