@directive-run/core 1.11.0 → 1.13.0

package/dist/index.d.cts

@@ -1,386 +1,9 @@
-import { P as PredicateOp, a as PatchSpec, C as ClauseResult, F as FactTemplate, b as FactPredicate, S as SchemaType, D as DefinitionMeta, M as ModuleSchema, c as Facts, T as TypedDerivationsDef, d as TypedEventsDef, E as EffectsDef, e as TypedConstraintsDef, f as TypedResolversDef, g as ModuleHooks, h as CrossModuleDeps, i as CrossModuleDerivationsDef, j as CrossModuleEffectsDef, k as CrossModuleConstraintsDef, l as ModuleDef, m as CreateSystemOptionsSingle, n as SingleModuleSystem, o as ModulesMap, p as CreateSystemOptionsNamed, N as NamespacedSystem, q as Plugin, r as TraceOption, s as ErrorBoundaryConfig, R as RequirementWithId, t as Requirement, u as RequirementKeyFn } from './plugins-Ykl_sAPE.cjs';
-export { A as AnySystem, B as BatchConfig, v as DirectiveError, w as DistributableSnapshot, x as DistributableSnapshotOptions, y as DynamicConstraintDef, z as DynamicEffectDef, G as DynamicResolverDef, H as FactsSnapshot, I as HistoryAPI, J as HistoryOption, K as HistoryState, L as InferDerivations, O as InferEvents, Q as InferFacts, U as InferRequirementTypes, V as InferRequirements, W as InferSchemaType, X as InferSelectorState, Y as KeySelector, Z as MetaAccessor, _ as MetaMatch, $ as ObservationEvent, a0 as OperatorObject, a1 as PatchValue, a2 as PayloadRef, a3 as PredicateClause, a4 as PredicateCombinator, a5 as PredicateCombinatorKey, a6 as PredicateObject, a7 as RetryPolicy, a8 as Schema, a9 as Snapshot, aa as System, ab as SystemConfig, ac as SystemInspection, ad as SystemMode, ae as SystemSnapshot, af as TraceEntry, ag as isNamespacedSystem, ah as isSingleModuleSystem } from './plugins-Ykl_sAPE.cjs';
-export { D as DerivationDefWithMeta, t as typedConstraint, a as typedResolver } from './helpers-hh6UanB1.cjs';
-export { A as AuditEntry, a as AuditEntryKind, b as AuditLedger, c as AuditLedgerOptions, d as AuditLedgerSink, Q as QueryFilter, e as createAuditLedger, m as memorySink } from './audit-ledger-qMjEBqiP.cjs';
-export { D as DistributableSnapshotLike, S as SignedSnapshot, a as SnapshotDiff, b as SnapshotDiffEntry, d as diffSnapshots, i as isSignedSnapshot, c as isSnapshotExpired, s as shallowEqual, e as signSnapshot, v as validateSnapshot, f as verifySnapshotSignature } from './utils-BnQajqPu.cjs';
-
-/**
- * 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`.
- *
- * @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.
- */
-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;
-}
-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;
+import { C as ClauseResult, F as FactPredicate, S as SchemaType, D as DefinitionMeta, M as ModuleSchema, a as Facts, T as TypedDerivationsDef, b as TypedEventsDef, E as EffectsDef, c as TypedConstraintsDef, d as TypedResolversDef, e as ModuleHooks, f as CrossModuleDeps, g as CrossModuleDerivationsDef, h as CrossModuleEffectsDef, i as CrossModuleConstraintsDef, j as ModuleDef, k as CreateSystemOptionsSingle, l as SingleModuleSystem, m as ModulesMap, n as CreateSystemOptionsNamed, N as NamespacedSystem, P as Plugin, o as TraceOption, p as ErrorBoundaryConfig, R as RequirementWithId, q as Requirement, r as RequirementKeyFn } from './plugins-BIzXaYbg.cjs';
+export { A as AnySystem, B as BatchConfig, s as DirectiveError, t as DistributableSnapshot, u as DistributableSnapshotOptions, v as DynamicConstraintDef, w as DynamicEffectDef, x as DynamicResolverDef, y as FactTemplate, z as FactsSnapshot, H as HistoryAPI, G as HistoryOption, I as HistoryState, J as InferDerivations, K as InferEvents, L as InferFacts, O as InferRequirementTypes, Q as InferRequirements, U as InferSchemaType, V as InferSelectorState, W as KeySelector, X as MetaAccessor, Y as MetaMatch, Z as ObservationEvent, _ as OperatorObject, $ as PatchSpec, a0 as PatchValue, a1 as PayloadRef, a2 as PredicateClause, a3 as PredicateCombinator, a4 as PredicateCombinatorKey, a5 as PredicateObject, a6 as PredicateOp, a7 as RetryPolicy, a8 as Schema, a9 as Snapshot, aa as System, ab as SystemConfig, ac as SystemInspection, ad as SystemMode, ae as SystemSnapshot, af as TraceEntry, ag as isNamespacedSystem, ah as isSingleModuleSystem } from './plugins-BIzXaYbg.cjs';
+import { S as SchemaKindNode } from './predicate-Bnx3LN7P.cjs';
+export { D as DerivationDefWithMeta, a as SchemaKind, b as SchemaValidationError, c as SchemaValidationOptions, d as SchemaValidationResult, e as applyPatch, f as evaluateKeySelector, g as evaluatePredicate, h as evaluatePredicateExplained, i as evaluateTemplate, j as extractDeps, k as extractTemplateKeys, l as getKind, m as getOperatorsForKind, n as getSchemaFieldKinds, o as isPredicate, p as isTemplate, q as listAllPredicateOperators, r as memoizePredicate, t as typedConstraint, s as typedResolver, v as validatePredicate, u as validatePredicateAgainstSchema } from './predicate-Bnx3LN7P.cjs';
+export { A as AuditEntry, a as AuditEntryKind, b as AuditLedger, c as AuditLedgerOptions, d as AuditLedgerSink, Q as QueryFilter, V as VerifyResult, e as createAuditLedger, m as memorySink } from './audit-ledger-Dc6hAXam.cjs';
+export { D as DistributableSnapshotLike, S as SignedSnapshot, a as SnapshotDiff, b as SnapshotDiffEntry, d as diffSnapshots, i as isSignedSnapshot, c as isSnapshotExpired, s as shallowEqual, e as signSnapshot, v as validateSnapshot, f as verifySnapshotSignature } from './utils-Mg55IerF.cjs';
 
 /**
  * Predicate backtest — rule-change impact.
@@ -824,6 +447,40 @@ declare function diffRules(options: DiffRulesOptions): RulesDiffReport;
  */
 declare function diffClauses(before: unknown, after: unknown): Change[];
 
+/**
+ * `predicateHash` — content-addressed fingerprint for a {@link FactPredicate}.
+ *
+ * Canonicalized via `stableStringify` so semantically-identical predicates
+ * (different key order, different whitespace) produce the same hash.
+ * Uses djb2 32-bit (8-character hex). SHA-256 reserved for v2.
+ *
+ * @module
+ */
+
+/**
+ * Compute a content-addressed hash for a {@link FactPredicate}. Canonicalised
+ * via `stableStringify` so two semantically-identical predicates emitted
+ * with different key order or whitespace produce the same hash.
+ *
+ * Suitable for:
+ * - Cache keys, dedupe in `sweepUnder`
+ * - Audit-ledger entry indexing (the `whenSpec` field has its own hash chain)
+ * - Provenance records (`predicateFromIntentWithProvenance.predicateHash`)
+ *
+ * **NOT suitable for cryptographic use** — 32-bit djb2 is collision-prone
+ * against an adversary. SHA-256 is reserved for v2.
+ *
+ * @example
+ * ```ts
+ * predicateHash({ cartTotal: { $gte: 50 } });
+ * // → "a1b2c3d4" (stable across runs and runtimes)
+ *
+ * // Two semantically-identical predicates → same hash
+ * predicateHash({ a: 1, b: 2 }) === predicateHash({ b: 2, a: 1 }); // true
+ * ```
+ */
+declare function predicateHash<F = Record<string, unknown>>(spec: FactPredicate<F>): string;
+
 /**
  * predict() — "would this predicate fire against these facts, and if
  * not, what facts must change to make it fire?"
@@ -848,7 +505,7 @@ interface PredictMissingChange {
     /** Human-readable hint suitable for feeding back to an LLM or showing to a user. */
     readonly suggestion: string;
 }
-interface PredictResult<F> {
+interface PredictResult<_F = unknown> {
     /** True iff the predicate would fire against `facts`. */
     readonly wouldFire: boolean;
     /** Full clause-by-clause result (reuses the whenExplain payload). */
@@ -857,10 +514,12 @@ interface PredictResult<F> {
      * List of failing clauses, each with a `suggestion` describing the
      * smallest concrete change to `facts` that would make that clause pass.
      * Empty when `wouldFire === true`.
+     *
+     * If the predicate contains a `$changed` clause AND `prev` was not
+     * passed, a synthetic warning is included here (the `$changed` clause
+     * cannot be evaluated without a `prev` snapshot).
      */
     readonly missingChanges: readonly PredictMissingChange[];
-    /** Reference to the predicate evaluated, for telemetry. */
-    readonly predicate: FactPredicate<F>;
 }
 /**
  * Run a predicate against the current fact state and report whether it
@@ -869,6 +528,12 @@ interface PredictResult<F> {
  * Designed for the LLM-iteration loop and for "preview the impact of this
  * rule" UIs.
  *
+ * **`$changed` and `prev`:** the `$changed` operator compares the current
+ * value of a fact against the `prev` snapshot. If the predicate uses
+ * `$changed` and `prev` is not supplied, the missing-changes list includes
+ * a synthetic warning indicating that the clause cannot be evaluated —
+ * pass `predict(predicate, facts, prev)` to get a real result.
+ *
  * @example
  * ```ts
  * const predicate = { cartTotal: { $gte: 50 }, region: { $in: ["US", "EU"] } };
@@ -882,7 +547,6 @@ interface PredictResult<F> {
  * //       { path: "cartTotal", op: "$gte", expected: 50, actual: 30,
  * //         suggestion: "set cartTotal to at least 50 (currently 30)" },
  * //     ],
- * //     predicate: { cartTotal: { $gte: 50 }, region: { $in: ["US", "EU"] } },
  * //   }
  * ```
  */
@@ -896,9 +560,11 @@ declare function predict<F = Record<string, unknown>>(predicate: FactPredicate<F
  *
  *   - **direct contradiction:** same fact path, opposite-direction
  *     comparison (`$gte 50` vs `$lt 50` — they cannot both fire).
+ *     Reported under `contradictions`.
  *   - **subset:** candidate's range is a strict subset of an existing
  *     constraint's range (candidate `$gte 100` when existing already
- *     has `$gte 50`; the new rule never fires independently of the old).
+ *     has `$gte 50`; the new rule is redundant). Reported under
+ *     `warnings` — a redundant rule is not a contradiction, just noise.
  *   - **overlap:** shares ≥1 fact path with non-trivial intersection —
  *     a warning, not a hard error.
  *
@@ -914,6 +580,16 @@ declare function predict<F = Record<string, unknown>>(predicate: FactPredicate<F
  * exists) are NOT acceptable — every reported contradiction must be
  * defensible.
  *
+ * **v1 scope LIMITATION (M4):** `checkAgainst` operates on predicate
+ * logic only. It does NOT consult `bind:` / `owns:` resolver metadata —
+ * a candidate that would *write* to a fact owned by another constraint
+ * will not be flagged here. Use `doctor.checkOwns()` for that gate.
+ *
+ * **INVARIANT (M11):** `checkAgainst` depends on `flattenPredicate`
+ * emitting `{ path, op, value }` LeafClause shape — if that shape ever
+ * changes, every comparison below silently breaks. See
+ * `doctor-leaf-shape.contract.test.ts`.
+ *
  * Pure, sync, no engine dependency.
  */
 
@@ -939,15 +615,70 @@ interface Contradiction {
     };
 }
 interface CheckAgainstResult {
-    /** Hard contradictions — candidate never co-fires with existing rule. */
+    /**
+     * Hard contradictions — candidate never co-fires with existing rule.
+     * Includes only `type: "direct"` findings. Redundancy (`type: "subset"`)
+     * lives under `warnings` — a redundant rule is noise, not a conflict.
+     */
     readonly contradictions: readonly Contradiction[];
-    /** Soft overlaps — shared facts with non-trivial intersection. */
+    /**
+     * Soft findings — shared facts with non-trivial intersection
+     * (`type: "overlap"`) AND subset redundancy (`type: "subset"`).
+     */
     readonly warnings: readonly Contradiction[];
 }
 /** Shape of `system.inspect().constraints[N]` we care about — accepts any superset. */
 interface ExistingConstraint {
     readonly id: string;
     readonly whenSpec?: unknown;
+    /**
+     * Fact paths the constraint's resolver(s) write to, if exposed by the
+     * inspect API. Consulted by {@link doctor.checkOwns} to flag candidates
+     * that would write to fields owned elsewhere. Optional — older inspect
+     * payloads omit it.
+     */
+    readonly owns?: readonly string[];
+    /** Same as {@link owns} but for the bind: side of binding metadata. */
+    readonly bind?: readonly string[];
+}
+/**
+ * Returned by {@link doctor.checkOwns}.
+ *
+ * `severity` matches the {@link Contradiction} discriminator on
+ * {@link CheckAgainstResult} so callers can route both shapes
+ * uniformly: by default, owns-collisions are `"warning"` (the engine
+ * still has a runtime gate), but a caller can promote them to
+ * `"error"` for stricter pre-deploy linting. (M5)
+ */
+interface CheckOwnsFinding {
+    readonly constraintId: string;
+    /** The fact path on the candidate predicate that triggered the finding. */
+    readonly candidatePath: string;
+    /** The owner side it would collide with: "owns" or "bind". */
+    readonly source: "owns" | "bind";
+    readonly reason: string;
+    /**
+     * Severity discriminator — `"warning"` by default (the engine has
+     * its own runtime gate), `"error"` reserved for callers that want
+     * strict pre-deploy lints. (M5)
+     */
+    readonly severity?: "error" | "warning";
+}
+/**
+ * Result of {@link doctor.checkOwns}.
+ *
+ * Owns-/bind- collisions are warnings, not contradictions — the engine
+ * itself enforces the runtime binding gate, so a pre-deploy doctor pass
+ * treats them as advisory. The {@link CheckOwnsFinding.severity}
+ * discriminator anticipates v2 promotion of findings to errors. (M5, F-3)
+ */
+interface CheckOwnsResult {
+    /**
+     * Owns-/bind- collisions surfaced by {@link doctor.checkOwns}. Empty
+     * when constraints expose no `owns:` / `bind:` metadata or the
+     * candidate's fact paths don't overlap.
+     */
+    readonly warnings: readonly CheckOwnsFinding[];
 }
 declare const doctor: {
     /**
@@ -979,8 +710,100 @@ declare const doctor: {
     checkAgainst<F = Record<string, unknown>>(candidate: FactPredicate<F>, existing: readonly ExistingConstraint[] | {
         constraints: readonly ExistingConstraint[];
     }): CheckAgainstResult;
+    /**
+     * Flag a candidate predicate whose referenced fact paths overlap with
+     * fields *owned* (or `bind:`-bound) by an existing constraint's
+     * resolvers. A v1 stub: relies on `inspect()` exposing `owns:` / `bind:`
+     * on each constraint snapshot. When that metadata is absent, this
+     * returns `{ findings: [] }` — no false positives.
+     *
+     * **TODO (v2):** wire the engine's resolver-ownership graph through
+     * `system.inspect()` so this returns real findings without manual
+     * `owns:` annotations on inspect payloads.
+     *
+     * @example
+     * ```ts
+     * doctor.checkOwns(
+     *   { cartTotal: { $gte: 100 } },
+     *   system.inspect(),
+     * );
+     * // → { findings: [
+     * //     { constraintId: "applyDiscount", candidatePath: "cartTotal",
+     * //       source: "owns",
+     * //       reason: "Constraint applyDiscount already owns cartTotal." }
+     * //   ] }
+     * ```
+     */
+    checkOwns<F = Record<string, unknown>>(candidate: FactPredicate<F>, existing: readonly ExistingConstraint[] | {
+        constraints: readonly ExistingConstraint[];
+    }): CheckOwnsResult;
 };
 
+/**
+ * `describePredicate` — turn any {@link FactPredicate} into a precise,
+ * human-readable English sentence (or algebraic expression).
+ *
+ * Closes the LLM-emit round-trip:
+ *
+ *   intent (NL) → predicate (AST) → describePredicate (NL) → reprompt
+ *
+ * Pure tree walker. No side effects. No throws on a valid predicate. On
+ * an invalid input (cyclic spec, non-object) returns a sentinel string
+ * rather than throwing, so it is safe to call on user/LLM input.
+ *
+ * Reuses no traversal infrastructure from `walkPredicate` directly because
+ * `walkPredicate` is a callback walker (flat) and English rendering needs a
+ * recursive return-value walker (tree). The two are isomorphic — same
+ * structural rules, same depth cap, same cycle guard. Operator/value
+ * formatting mirrors `rules-diff.ts`'s prose style.
+ *
+ * @module
+ */
+
+/**
+ * Options controlling how {@link describePredicate} renders a predicate.
+ */
+interface DescribeOptions {
+    /** Locale for number formatting (default: `"en-US"`). */
+    locale?: string;
+    /** Wrap each clause in parens when there's > 1 clause. Default `true`. */
+    parenthesize?: boolean;
+    /** Style: `"natural"` (English prose) or `"formal"` (algebraic). Default `"natural"`. */
+    style?: "natural" | "formal";
+    /**
+     * Friendly fact-name renderer. Default: pass-through. Use to map e.g.
+     * `cartTotal` → `"cart total"`. Only consulted in `"natural"` style — the
+     * formal style preserves the raw dotted path so output stays algebraic.
+     */
+    factName?: (path: string) => string;
+}
+/**
+ * Render a {@link FactPredicate} as a precise human-readable sentence.
+ *
+ * Renders a `FactPredicate` as English by default (`style: 'natural'`);
+ * pass `style: 'formal'` for algebraic notation (`≥`, `∈`, `∧`, etc.).
+ *
+ * @remarks
+ * Exported as `describePredicate` (not `describe`) to avoid collision with
+ * vitest's `describe()`.
+ *
+ * @example
+ * ```ts
+ * describePredicate({ cartTotal: { $gte: 50 } });
+ * // → "cartTotal is at least 50"
+ *
+ * describePredicate(
+ *   { $any: [{ region: "US" }, { region: "EU" }] },
+ *   { factName: (p) => p.replace(/([A-Z])/g, " $1").toLowerCase() },
+ * );
+ * // → "(region is US) OR (region is E U)"
+ *
+ * describePredicate({ cartTotal: { $gte: 50 } }, { style: "formal" });
+ * // → "cartTotal ≥ 50"
+ * ```
+ */
+declare function describePredicate<F = Record<string, unknown>>(predicate: FactPredicate<F>, opts?: DescribeOptions): string;
+
 /**
  * Compile a `FactPredicate` to a parameterized Postgres-style SQL WHERE
  * clause. The same predicate that gates a constraint on the client can
@@ -2415,4 +2238,4 @@ declare const Backoff: {
     readonly Exponential: "exponential";
 };
 
-export { Backoff, type Branded, type ChainableSchemaType, type Change, type ChangeKind, type CheckAgainstResult, ClauseResult, type ConstraintDiff, type ConstraintStatus, type Contradiction, type ContradictionType, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleDeps, DefinitionMeta, type DiffRulesOptions, ErrorBoundaryConfig, type ExistingConstraint, 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, PredicateOp, type PredicateToMongoOptions, type PredicateToPostgrestOptions, type PredicateToSqlOptions, type PredicateToSqlResult, type PredictMissingChange, type PredictResult, type ReplayDiffSample, type ReplayFrame, type ReplayUnderOptions, Requirement, RequirementSet, type RequirementTypeStatus, RequirementWithId, type RulesDiffReport, type RulesMapInput, type SchemaKind, type SchemaKindNode, SchemaType, type SchemaValidationError, type SchemaValidationOptions, type SchemaValidationResult, 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, doctor, elapsedMs, evaluateKeySelector, evaluatePredicate, evaluatePredicateExplained, evaluateTemplate, extractDeps, extractTemplateKeys, flattenPredicate, forType, framesFromHistory, framesFromSnapshots, generateRequirementId, getKind, getOperatorsForKind, getSchemaFieldKinds, initialTimerState, isPredicate, isRequirementType, isTemplate, listAllPredicateOperators, memoizePredicate, pauseTimer, predicateToMongo, predicateToPostgrest, predicateToSQL, predicateToWhere, predict, realClock, registerRepeat, remainingMs, replayUnder, req, resetTimer, resumeTimer, startTimer, sweepUnder, t, tickTimer, timerOps, toReplayFrames, toRulesMap, validatePredicate, validatePredicateAgainstSchema, virtualClock };
+export { Backoff, type Branded, type ChainableSchemaType, type Change, type ChangeKind, type CheckAgainstResult, type CheckOwnsFinding, type CheckOwnsResult, ClauseResult, type ConstraintDiff, type ConstraintStatus, type Contradiction, type ContradictionType, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleDeps, DefinitionMeta, type DescribeOptions, type DiffRulesOptions, ErrorBoundaryConfig, type ExistingConstraint, type ExtendedSchemaType, FactPredicate, Facts, type LeafClause, MAX_REPLAY_FRAMES, MAX_SWEEP_POINTS, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, Plugin, type PredicateBacktestReport, type PredicateToMongoOptions, type PredicateToPostgrestOptions, type PredicateToSqlOptions, type PredicateToSqlResult, type PredictMissingChange, type PredictResult, type ReplayDiffSample, type ReplayFrame, type ReplayUnderOptions, Requirement, RequirementSet, type RequirementTypeStatus, RequirementWithId, type RulesDiffReport, type RulesMapInput, SchemaKindNode, SchemaType, type SignalClock, SingleModuleSystem, type SweepHole, type SweepPoint, type SweepReport, type SweepUnderOptions, type TimerFactOpts, type TimerFactState, TraceOption, completeTimer, createModule, createModuleFactory, createRequirementStatusPlugin, createStatusHook, createSystem, createSystemWithStatus, defaultClock, describePredicate, diffClauses, diffRules, doctor, elapsedMs, flattenPredicate, forType, framesFromHistory, framesFromSnapshots, generateRequirementId, initialTimerState, isRequirementType, pauseTimer, predicateHash, predicateToMongo, predicateToPostgrest, predicateToSQL, predicateToWhere, predict, realClock, registerRepeat, remainingMs, replayUnder, req, resetTimer, resumeTimer, startTimer, sweepUnder, t, tickTimer, timerOps, toReplayFrames, toRulesMap, virtualClock };