@directive-run/core 1.12.0 → 1.13.0

package/dist/predicate-Bnx3LN7P.d.cts

@@ -0,0 +1,655 @@
+import { a8 as Schema, a as Facts, F as FactPredicate, aS as InferSchema, y as FactTemplate, D as DefinitionMeta, q as Requirement, b9 as RequirementOutput, a7 as RetryPolicy, B as BatchConfig, b0 as ResolverContext, a6 as PredicateOp, $ as PatchSpec, C as ClauseResult } from './plugins-BIzXaYbg.cjs';
+
+/**
+ * Derivation Types - Type definitions for derivations
+ */
+
+/** Derivation definition function signature. */
+interface DerivationDef<S extends Schema, T, D extends DerivationsDef<S>> {
+    (facts: Facts<S>, derived: DerivedValues<S, D>): T;
+}
+/**
+ * Derivation definition with metadata (object form).
+ * Use this when you want to attach debugging metadata to a derivation.
+ *
+ * @example
+ * ```typescript
+ * derive: {
+ *   displayName: {
+ *     compute: (facts) => `${facts.firstName} ${facts.lastName}`,
+ *     meta: { label: "Display Name", description: "Full name for UI" },
+ *   },
+ * },
+ * ```
+ */
+interface DerivationDefWithMeta<S extends Schema, T, D extends DerivationsDef<S>> {
+    /**
+     * The derivation body. Either:
+     * - a function `(facts, derived) => T` (original form), or
+     * - a {@link FactPredicate} data spec — boolean derivations only, or
+     * - a {@link FactTemplate} `{ $template: "..." }` — string derivations only.
+     *
+     * Data forms are normalized to a wrapper function at registration; the
+     * wrapper reads through the facts proxy so existing auto-tracking
+     * captures dependencies.
+     */
+    compute: DerivationDef<S, T, D> | ([T] extends [boolean] ? FactPredicate<InferSchema<S>> : never) | ([T] extends [string] ? FactTemplate : never);
+    meta?: DefinitionMeta;
+}
+/** Map of derivation definitions (internal — always bare functions after unwrap). */
+type DerivationsDef<S extends Schema> = Record<string, DerivationDef<S, unknown, DerivationsDef<S>>>;
+/** Computed derived values. */
+type DerivedValues<S extends Schema, D extends DerivationsDef<S>> = {
+    readonly [K in keyof D]: ReturnType<D[K]>;
+};
+/** Internal derivation state */
+interface DerivationState<T> {
+    id: string;
+    compute: () => T;
+    cachedValue: T | undefined;
+    dependencies: Set<string>;
+    isStale: boolean;
+    isComputing: boolean;
+    /** Consecutive runs producing the same deps (auto-tracked only) */
+    stableRunCount: number;
+    /** Once true, skip withTracking() overhead until a tracked fact mutates */
+    depsStable: boolean;
+}
+
+/**
+ * Type Helpers - External typed constraint and resolver definitions
+ *
+ * These types enable defining constraints and resolvers with full type safety
+ * outside of module definitions, while maintaining proper type inference.
+ */
+
+/**
+ * External constraint definition with full typing.
+ * Use this when defining constraints outside of createModule().
+ *
+ * @typeParam S - The schema type
+ * @typeParam R - The requirement type (defaults to Requirement)
+ *
+ * @example
+ * ```typescript
+ * // Define a typed constraint factory
+ * const createMaxCountConstraint = <S extends Schema>(
+ *   maxCount: number
+ * ): TypedConstraint<S, { type: "RESET_COUNT" }> => ({
+ *   priority: 10,
+ *   when: (facts) => (facts as { count: number }).count > maxCount,
+ *   require: { type: "RESET_COUNT" },
+ * });
+ *
+ * // Use in module
+ * const module = createModule("counter", {
+ *   schema: { count: t.number() },
+ *   constraints: {
+ *     maxCount: createMaxCountConstraint(100),
+ *   },
+ * });
+ * ```
+ */
+interface TypedConstraint<S extends Schema, R extends Requirement = Requirement> {
+    /** Priority for ordering (higher runs first) */
+    priority?: number;
+    /** Mark this constraint as async (avoids runtime detection) */
+    async?: boolean;
+    /** Condition function (sync or async) */
+    when: (facts: Facts<S>) => boolean | Promise<boolean>;
+    /**
+     * Requirement(s) to produce when condition is met.
+     */
+    require: RequirementOutput<R> | ((facts: Facts<S>) => RequirementOutput<R>);
+    /** Timeout for async constraints (ms) */
+    timeout?: number;
+    /**
+     * Constraint IDs whose resolvers must complete before this constraint is evaluated.
+     * - If dependency's `when()` returns false, this constraint proceeds (nothing to wait for)
+     * - If dependency's resolver fails, this constraint remains blocked until it succeeds
+     * - Cross-module: use the constraint ID as it appears in the merged system
+     */
+    after?: string[];
+}
+/**
+ * External resolver definition with full typing.
+ * Use this when defining resolvers outside of createModule().
+ *
+ * @typeParam S - The schema type
+ * @typeParam R - The requirement type (defaults to Requirement)
+ *
+ * @example
+ * ```typescript
+ * // Define a typed resolver factory
+ * interface FetchUserReq extends Requirement {
+ *   type: "FETCH_USER";
+ *   userId: string;
+ * }
+ *
+ * const createFetchUserResolver = <S extends Schema>(
+ *   fetchFn: (userId: string) => Promise<User>
+ * ): TypedResolver<S, FetchUserReq> => ({
+ *   requirement: (req): req is FetchUserReq => req.type === "FETCH_USER",
+ *   key: (req) => `fetch-user-${req.userId}`,
+ *   retry: { attempts: 3, backoff: "exponential" },
+ *   resolve: async (req, ctx) => {
+ *     const user = await fetchFn(req.userId);
+ *     (ctx.facts as { user: User }).user = user;
+ *   },
+ * });
+ * ```
+ */
+interface TypedResolver<S extends Schema, R extends Requirement = Requirement> {
+    /**
+     * Requirement type to handle.
+     * - String: matches `req.type` directly (e.g., `requirement: "FETCH_USER"`)
+     * - Function: type guard predicate (e.g., `requirement: (req) => req.type === "FETCH_USER"`)
+     */
+    requirement: R["type"] | ((req: Requirement) => req is R);
+    /** Custom key function for deduplication */
+    key?: (req: R) => string;
+    /** Retry policy */
+    retry?: RetryPolicy;
+    /** Timeout for resolver execution (ms) */
+    timeout?: number;
+    /** Batch configuration */
+    batch?: BatchConfig;
+    /** Resolve function for single requirement */
+    resolve?: (req: R, ctx: ResolverContext<S>) => Promise<void>;
+    /** Resolve function for batched requirements */
+    resolveBatch?: (reqs: R[], ctx: ResolverContext<S>) => Promise<void>;
+}
+/**
+ * Create a typed constraint factory for a specific schema.
+ * This enables creating reusable constraint definitions with proper typing.
+ *
+ * @example
+ * ```typescript
+ * const schema = { count: t.number(), threshold: t.number() };
+ * const factory = createConstraintFactory<typeof schema>();
+ *
+ * const maxCountConstraint = factory.create({
+ *   when: (facts) => facts.count > facts.threshold,
+ *   require: { type: "RESET" },
+ * });
+ * ```
+ */
+declare function createConstraintFactory<S extends Schema>(): {
+    /**
+     * Create a typed constraint
+     */
+    create<R extends Requirement = Requirement>(constraint: TypedConstraint<S, R>): TypedConstraint<S, R>;
+};
+/**
+ * Create a typed resolver factory for a specific schema.
+ * This enables creating reusable resolver definitions with proper typing.
+ *
+ * @example
+ * ```typescript
+ * const schema = { user: t.object<User>() };
+ * const factory = createResolverFactory<typeof schema>();
+ *
+ * const fetchUserResolver = factory.create<FetchUserReq>({
+ *   requirement: (req): req is FetchUserReq => req.type === "FETCH_USER",
+ *   resolve: async (req, ctx) => {
+ *     ctx.facts.user = await fetchUser(req.userId);
+ *   },
+ * });
+ * ```
+ */
+declare function createResolverFactory<S extends Schema>(): {
+    /**
+     * Create a typed resolver
+     */
+    create<R extends Requirement = Requirement>(resolver: TypedResolver<S, R>): TypedResolver<S, R>;
+};
+/**
+ * Type-safe constraint creator.
+ * Simpler alternative to createConstraintFactory when you don't need a factory pattern.
+ *
+ * @example
+ * ```typescript
+ * const constraint = typedConstraint<typeof schema, { type: "RESET" }>({
+ *   when: (facts) => facts.count > 100,
+ *   require: { type: "RESET" },
+ * });
+ * ```
+ */
+declare function typedConstraint<S extends Schema, R extends Requirement = Requirement>(constraint: TypedConstraint<S, R>): TypedConstraint<S, R>;
+/**
+ * Type-safe resolver creator.
+ * Simpler alternative to createResolverFactory when you don't need a factory pattern.
+ *
+ * @example
+ * ```typescript
+ * const resolver = typedResolver<typeof schema, FetchUserReq>({
+ *   requirement: (req): req is FetchUserReq => req.type === "FETCH_USER",
+ *   resolve: async (req, ctx) => {
+ *     ctx.facts.user = await fetchUser(req.userId);
+ *   },
+ * });
+ * ```
+ */
+declare function typedResolver<S extends Schema, R extends Requirement = Requirement>(resolver: TypedResolver<S, R>): TypedResolver<S, R>;
+
+/**
+ * Schema Introspection
+ *
+ * A runtime discriminant for every `t.*()` builder result, so downstream
+ * consumers (`predicateFromIntent`, `doctor`, future `predicateToZod`)
+ * can ask "what kind is this fact?" without grepping the source.
+ *
+ * The discriminant lives at `_kind?: SchemaKindNode` on `ExtendedSchemaType`.
+ * Base builders set it; chain mutators (`.nullable()`, `.brand()`, etc.)
+ * preserve / decorate it. When `_kind` is absent (legacy or third-party
+ * builder), the parser falls back to reading the freeform `_typeName`
+ * string. When even that fails: `{ kind: "unknown" }` — graceful close.
+ *
+ * This module has zero hot-path cost; it is only invoked when an
+ * introspecting caller asks for it.
+ */
+
+/**
+ * The closed set of kinds a Directive schema field can be.
+ *
+ * Drives operator availability via {@link getOperatorsForKind}: e.g.
+ * `"number"` gets the orderable operators (`$gte`, `$lte`); `"boolean"`
+ * does not.
+ */
+type SchemaKind = "number" | "string" | "boolean" | "bigint" | "date" | "array" | "object" | "record" | "tuple" | "enum" | "literal" | "union" | "branded" | "unknown";
+/**
+ * A tree-shaped discriminator for a schema field. Composite kinds
+ * (array, object, tuple, etc.) carry their element / shape information
+ * so an LLM-prompt builder can show "cartTotal is a number" AND
+ * "items is an array of { sku: string, qty: number }".
+ *
+ * `nullable` / `hasDefault` flags appear on the inner node (NOT a
+ * wrapping kind) so operator-lookup on `t.number().nullable()` returns
+ * the number's operators unchanged — `$gte` works on the non-null arm.
+ */
+type SchemaKindNode = ({
+    kind: "number" | "string" | "boolean" | "bigint" | "date" | "unknown";
+} | {
+    kind: "literal";
+    value: string | number | boolean | null;
+    primitive: "string" | "number" | "boolean" | "null";
+} | {
+    kind: "enum";
+    values: readonly (string | number)[];
+    primitive: "string" | "number";
+} | {
+    kind: "array";
+    element: SchemaKindNode;
+} | {
+    kind: "tuple";
+    elements: readonly SchemaKindNode[];
+} | {
+    kind: "object";
+    shape: Record<string, SchemaKindNode>;
+} | {
+    kind: "record";
+    value: SchemaKindNode;
+} | {
+    kind: "union";
+    members: readonly SchemaKindNode[];
+} | {
+    kind: "branded";
+    inner: SchemaKindNode;
+}) & {
+    /** True if the schema accepts `null` (from `.nullable()` / `.optional()`). */
+    nullable?: boolean;
+    /** True if the schema has a `.default()`. */
+    hasDefault?: boolean;
+};
+/**
+ * Return the {@link SchemaKindNode} for a schema field. Prefers the
+ * explicit `_kind` discriminant set by the builder; falls back to
+ * parsing the freeform `_typeName` string for legacy / third-party
+ * builders that don't set `_kind`.
+ *
+ * Hostile-getter safe: `_kind` / `_typeName` reads are wrapped — a builder
+ * that throws on property access returns `{ kind: "unknown" }` instead of
+ * propagating the throw to introspecting callers.
+ *
+ * In dev mode, a function input (`typeof schema === "function"`) emits a
+ * warning — common foot-gun where the caller forgot to invoke a builder
+ * factory (e.g. wrote `t.number` instead of `t.number()`).
+ *
+ * @example
+ * ```ts
+ * getKind(t.number())              // → { kind: "number" }
+ * getKind(t.string().nullable())   // → { kind: "string", nullable: true }
+ * getKind(t.array(t.number()))     // → { kind: "array", element: { kind: "number" } }
+ * ```
+ */
+declare function getKind(schema: unknown): SchemaKindNode;
+/**
+ * Walk the `facts` block of a module schema and emit a flat map from
+ * dotted path → kind node. Nested `t.object()` shapes flatten using
+ * `.` as the separator, matching the convention used by
+ * `OperatorObject<V>`'s nested-path support.
+ *
+ * Passing a top-level schema directly (without the `facts:` wrapper)
+ * also works — anything iterable as `Record<string, ExtendedSchemaType>`
+ * is acceptable.
+ *
+ * Hostile-getter safe: a builder whose `_kind` / `_typeName` throws is
+ * silently skipped (treated as `{ kind: "unknown" }` for that field)
+ * rather than aborting the whole walk.
+ *
+ * In dev mode, a top-level schema that yields an empty map (no
+ * introspectable keys) emits a warning — common foot-gun where the
+ * caller passed `myModule` instead of `myModule.schema`.
+ */
+declare function getSchemaFieldKinds(schema: unknown): Map<string, SchemaKindNode>;
+/**
+ * Return the set of `PredicateOp` strings that are valid against a
+ * given {@link SchemaKindNode}.
+ *
+ * Mirrors the type-level matrix encoded in `OperatorObject<V>` in
+ * `types/predicate.ts` — drift between the two is enforced by the
+ * compile-time conformance test
+ * (`schema-introspection-conformance.test-d.ts`).
+ *
+ * - **Common to all kinds:** `$eq`, `$ne`, `$in`, `$nin`, `$exists`
+ * - **Orderable (`number`/`string`/`bigint`/`date`):** + `$gt`, `$gte`,
+ *   `$lt`, `$lte`, `$between`
+ * - **String-specific:** + `$matches`, `$startsWith`, `$endsWith`, `$contains`
+ * - **Array:** + `$contains` (over the element type)
+ * - **Union:** *intersection* across members (the operand must be valid
+ *   for every branch).
+ * - **Branded:** delegates to the inner kind.
+ * - **Literal / Enum:** operators of the primitive, with `$eq` / `$in`
+ *   operand restricted at the LLM-prompt layer (not enforced here).
+ *
+ * `nullable` does not change operator availability — `$gte` on a
+ * nullable number is fine on the non-null arm; `$exists` handles null.
+ */
+declare function getOperatorsForKind(node: SchemaKindNode): readonly PredicateOp[];
+/**
+ * Return all known predicate operators — convenience for prompt builders
+ * that need to show the LLM the full set.
+ */
+declare function listAllPredicateOperators(): readonly PredicateOp[];
+
+/**
+ * Runtime for data-configuration predicates and templates.
+ *
+ * Pure module — imports only its own types. Reads facts through whatever
+ * object it is handed (the reactive `Facts` proxy in production, a plain
+ * snapshot in tests), so it never depends on the engine, store, or tracking.
+ */
+
+/** A readable scope — the `Facts` proxy and a plain snapshot both satisfy it. */
+type Scope = Record<string, unknown>;
+/**
+ * True when `v` is a data-form spec (predicate object/array) rather than a
+ * function. Excludes class instances (Date, RegExp, Map, Set, Promise, etc.)
+ * — only plain `{}` literals and arrays of plain clause shapes qualify.
+ *
+ * @example
+ * ```ts
+ * isPredicate({ phase: "red" }); // true
+ * isPredicate((f) => f.phase === "red"); // false
+ * isPredicate([{ fact: "phase", op: "$eq", value: "red" }]); // true
+ * ```
+ */
+declare function isPredicate(v: unknown): boolean;
+/**
+ * True when `v` is a {@link FactTemplate} (`{ $template: string }`).
+ *
+ * @example
+ * ```ts
+ * isTemplate({ $template: "Hi ${name}" }); // true
+ * isTemplate({ $set: { name: "x" } }); // false
+ * ```
+ */
+declare function isTemplate(v: unknown): v is FactTemplate;
+/**
+ * Throw when a predicate spec contains an operand that cannot survive a
+ * JSON round-trip — i.e. that would silently mis-evaluate if the spec was
+ * loaded from `JSON.parse`.
+ *
+ * Three failure classes are detected:
+ *
+ * - **Lost `RegExp` operand.** A `$matches` operand that is not a
+ *   `RegExp` instance. `JSON.parse` reconstructs a serialized regex as
+ *   `{}`, so a `$matches` clause with an empty-object operand is the
+ *   signature of a regex that did not survive serialization. Reify it
+ *   with `new RegExp(pattern, flags)` before installing the predicate.
+ * - **`bigint` operand.** `JSON.stringify` throws on `bigint`, so a
+ *   `bigint` operand cannot have been produced by a JSON pipeline and
+ *   cannot be persisted by one either.
+ * - **`Set` / `Map` operand.** Both serialize to `{}` and lose all
+ *   members; a predicate carrying one is not JSON-safe.
+ *
+ * This is an opt-in helper — the engine does not call it automatically.
+ * Users who load predicates from JSON should call it after `JSON.parse`
+ * to fail loud rather than silently mis-evaluate. See the
+ * "Serialization" section of RFC-0004.
+ *
+ * @example
+ * ```ts
+ * validatePredicate({ phase: { $matches: {} } });
+ * // throws — empty object where a RegExp is required
+ *
+ * validatePredicate({ phase: "red", elapsed: { $gte: 30 } });
+ * // ok — JSON-clean operands
+ * ```
+ */
+declare function validatePredicate(spec: unknown, path?: string): void;
+
+interface SchemaValidationError {
+    /** Dotted path to the failing clause (e.g. `cartTotal`, `auth.token.$gte`). */
+    readonly path: string;
+    /** The operator that failed (or the literal-equality marker `$eq`). */
+    readonly op: string;
+    /** The kind of the fact at this path, or `undefined` when the fact wasn't in the kind map. */
+    readonly kind?: SchemaKindNode;
+    /** The operators that ARE allowed for this fact's kind. */
+    readonly allowedOps?: readonly string[];
+    /** Human-readable failure reason (suitable for feeding back to an LLM). */
+    readonly reason: string;
+}
+interface SchemaValidationOptions {
+    /** Reject predicates with more than this many operator clauses (DoS guard). Default unbounded. */
+    readonly maxOperatorCount?: number;
+    /**
+     * Reject `$in` / `$nin` operands that contain more than this many elements
+     * (query-planner DoS guard). Default unbounded. A typical safe cap is 1000
+     * — beyond that, a downstream query compiler may degrade quadratically.
+     */
+    readonly maxArrayOperandLength?: number;
+}
+/**
+ * Heuristic: flag a regex source string that has obvious nested quantifiers
+ * (e.g. `(.+)+`, `(.*)*`, `(\w+)+`, `(a|a)+`) — the classic ReDoS shapes.
+ * Not a full ReDoS prover; intentionally conservative so a string-rehydrated
+ * `$matches` operand can be rejected before it ever reaches `RegExp.test`.
+ *
+ * Callers MUST NOT treat a `false` result as "safe" — a determined adversary
+ * can craft patterns this heuristic misses. The right answer for untrusted
+ * regex is "don't accept untrusted regex"; this helper exists to catch the
+ * obvious foot-guns.
+ *
+ * @example
+ * ```ts
+ * dangerousRegex("(a+)+");      // → true
+ * dangerousRegex("(.*)*");      // → true
+ * dangerousRegex("(\\w+)+");    // → true
+ * dangerousRegex("^[a-z]+$");   // → false
+ * ```
+ */
+declare function dangerousRegex(source: string): boolean;
+type SchemaValidationResult = {
+    ok: true;
+    operatorCount: number;
+} | {
+    ok: false;
+    errors: readonly SchemaValidationError[];
+    operatorCount: number;
+};
+/**
+ * Cross-check an LLM-emitted (or otherwise externally-sourced) predicate
+ * against a schema's runtime kind map. Catches errors that
+ * {@link validatePredicate} cannot — operator-on-wrong-kind (`$gte` on a
+ * boolean fact), unknown fact paths, and (optionally) operator-count
+ * exhaustion DoS attempts.
+ *
+ * Pair with {@link validatePredicate} (structural / JSON safety) for full
+ * coverage. Use {@link getSchemaFieldKinds} to derive `kindMap` from a
+ * module schema.
+ *
+ * Designed for the LLM-emit retry loop: returns a list of errors with
+ * structured `{path, op, kind, allowedOps, reason}` rather than throwing,
+ * so the caller can feed the errors back to the model.
+ *
+ * @example
+ * ```ts
+ * const kindMap = getSchemaFieldKinds({ facts: { cartTotal: t.number(), active: t.boolean() } });
+ * const result = validatePredicateAgainstSchema(
+ *   { cartTotal: { $gte: 50 }, active: { $gte: true } },
+ *   kindMap,
+ * );
+ * // → { ok: false, errors: [{ path: "active", op: "$gte", reason: "..." }], operatorCount: 2 }
+ * ```
+ */
+declare function validatePredicateAgainstSchema(spec: unknown, kindMap: Map<string, SchemaKindNode>, opts?: SchemaValidationOptions): SchemaValidationResult;
+/**
+ * Evaluate a {@link FactPredicate} against a fact scope. `prev` (a previous
+ * snapshot) is consulted only by the `$changed` operator.
+ *
+ * @example
+ * ```ts
+ * evaluatePredicate({ phase: "red", elapsed: { $gte: 30 } }, { phase: "red", elapsed: 45 });
+ * // → true
+ * evaluatePredicate({ $any: [{ phase: "red" }, { phase: "yellow" }] }, { phase: "green" });
+ * // → false
+ * ```
+ */
+declare function evaluatePredicate(spec: unknown, facts: Scope, prev?: Scope, depth?: number): boolean;
+/**
+ * Evaluate a predicate and return a per-clause breakdown — the data feed for
+ * devtools, `system.explain()`, and `directive explain`.
+ *
+ * @example
+ * ```ts
+ * evaluatePredicateExplained(
+ *   { phase: "red", elapsed: { $gte: 30 } },
+ *   { phase: "red", elapsed: 20 },
+ * );
+ * // → [
+ * //   { path: "phase",   op: "$eq",  expected: "red", actual: "red", pass: true  },
+ * //   { path: "elapsed", op: "$gte", expected: 30,    actual: 20,    pass: false },
+ * // ]
+ * ```
+ */
+declare function evaluatePredicateExplained(spec: unknown, facts: Scope, prev?: Scope, pathPrefix?: string): ClauseResult[];
+/**
+ * Memoize a predicate as a reusable evaluation closure.
+ *
+ * The returned function accepts any `facts` scope (the reactive proxy in
+ * production, a plain object in tests) plus an optional `prev` snapshot for
+ * `$changed`. The closure is cached **by predicate identity** in a
+ * `WeakMap`, so passing the same `predicate` reference repeatedly is
+ * allocation-free; cleanup is automatic once the predicate is no longer
+ * reachable.
+ *
+ * Note: no actual compilation happens — the returned closure re-walks the
+ * spec on every call via `evaluatePredicate`. The name reflects what the
+ * function does (closure memoization keyed by predicate identity), not a
+ * bytecode/AST compile step.
+ *
+ * Intended for advanced users who want a stable function reference per
+ * predicate (custom devtools, batched analyses). Regular module code does
+ * not need to call this — the engine wraps data-form `when` / `on` specs
+ * automatically at registration.
+ *
+ * @example
+ * ```ts
+ * const predicate = { phase: "red", elapsed: { $gte: 30 } };
+ * const check = memoizePredicate(predicate);
+ * check({ phase: "red", elapsed: 45 }); // → true
+ * check({ phase: "red", elapsed: 5  }); // → false
+ * ```
+ */
+declare function memoizePredicate(predicate: object): (facts: Scope, prev?: Scope) => boolean;
+/**
+ * Collect the fact keys a predicate references. Used for static analysis,
+ * devtools, and effect `on` dependency wiring. Nested predicates contribute
+ * dotted keys (`auth.token`).
+ *
+ * @example
+ * ```ts
+ * extractDeps({ phase: "red", elapsed: { $gte: 30 } });
+ * // → Set { "phase", "elapsed" }
+ * extractDeps({ self: { phase: "red" }, auth: { token: { $exists: true } } });
+ * // → Set { "self.phase", "auth.token" }
+ * ```
+ */
+declare function extractDeps(spec: unknown, prefix?: string): Set<string>;
+/**
+ * Interpolate a {@link FactTemplate} against a scope. Single-pass character
+ * scanner: `${ident}` interpolates `scope[ident]`; `$${` emits a literal
+ * `${`; unknown keys dev-warn and yield an empty string.
+ *
+ * @example
+ * ```ts
+ * evaluateTemplate({ $template: "Hi ${name}!" }, { name: "Ada" });
+ * // → "Hi Ada!"
+ * evaluateTemplate({ $template: "$${price}" }, {});
+ * // → "${price}"
+ * ```
+ */
+declare function evaluateTemplate(spec: FactTemplate, scope: Scope): string;
+/**
+ * Collect the placeholder keys referenced by a template. The static-analysis
+ * counterpart to {@link extractDeps} — useful for devtools, codegen, and
+ * "which facts does this template read" inspections. Only valid identifier
+ * placeholders are collected; malformed ones are ignored.
+ *
+ * @example
+ * ```ts
+ * extractTemplateKeys({ $template: "${firstName} ${lastName}" });
+ * // → Set { "firstName", "lastName" }
+ * extractTemplateKeys({ $template: "$${literal}" });
+ * // → Set {} (escaped — not a placeholder)
+ * ```
+ */
+declare function extractTemplateKeys(spec: FactTemplate): Set<string>;
+/**
+ * Build a stable dedup key by selecting fields from a requirement payload.
+ * Order-as-declared; values are stable-stringified (keys sorted recursively)
+ * so two payloads with the same fields in different orders dedupe to the
+ * same key.
+ *
+ * @example
+ * ```ts
+ * evaluateKeySelector(["url", "method"], { url: "/a", method: "GET" });
+ * // → '"/a"|"GET"'
+ * evaluateKeySelector(["id"], { id: 42 });
+ * // → '42'
+ * ```
+ */
+declare function evaluateKeySelector(selector: readonly string[], source: Record<string, unknown>): string;
+/**
+ * Apply a {@link PatchSpec} — assign facts from literals, payload copies
+ * (`$ref`), or interpolated strings (`$template`). Mutates through the passed
+ * `facts` proxy so change-tracking and downstream invalidation fire.
+ *
+ * @example
+ * ```ts
+ * const spec = {
+ *   $set: {
+ *     active: true,
+ *     userId: { $ref: "id" },
+ *     label: { $template: "user ${name}" },
+ *   },
+ * };
+ * applyPatch(spec, facts, { id: "u_1", name: "Ada" });
+ * // facts.active = true; facts.userId = "u_1"; facts.label = "user Ada"
+ * ```
+ */
+declare function applyPatch(spec: PatchSpec<Record<string, unknown>, Record<string, unknown>>, facts: Record<string, unknown>, payload: Record<string, unknown>): void;
+
+export { createConstraintFactory as A, createResolverFactory as B, dangerousRegex as C, type DerivationDefWithMeta as D, type SchemaKindNode as S, type TypedConstraint as T, type SchemaKind as a, type SchemaValidationError as b, type SchemaValidationOptions as c, type SchemaValidationResult as d, applyPatch as e, evaluateKeySelector as f, evaluatePredicate as g, evaluatePredicateExplained as h, evaluateTemplate as i, extractDeps as j, extractTemplateKeys as k, getKind as l, getOperatorsForKind as m, getSchemaFieldKinds as n, isPredicate as o, isTemplate as p, listAllPredicateOperators as q, memoizePredicate as r, typedResolver as s, typedConstraint as t, validatePredicateAgainstSchema as u, validatePredicate as v, type DerivationsDef as w, type DerivedValues as x, type DerivationState as y, type TypedResolver as z };