@directive-run/core 1.4.0 → 1.6.0

package/dist/{plugins-Dy1C8GtT.d.ts → plugins-DvrsPhzx.d.ts}

@@ -226,6 +226,264 @@ interface DefinitionMeta {
     [key: string]: unknown;
 }
 
+/**
+ * Data-configuration predicates and templates.
+ *
+ * A {@link FactPredicate} is a declarative, serializable boolean spec over a
+ * module's fact namespace — the data form of a constraint `when`, an effect
+ * `on`, or a boolean derivation. A {@link FactTemplate} is the value-producing
+ * counterpart: a fact-interpolating string.
+ *
+ * Convention: `$` marks an operator/expression node inside a predicate or
+ * template body (`$eq`, `$gte`, `$all`, `$template`, `$set`, `$ref`).
+ * Definition arms (`compute`, `handler`, `patch`) stay sigil-free.
+ *
+ * Operators are `$`-prefixed so they can never collide with a fact key —
+ * schema keys starting with `$` are rejected at registration.
+ */
+/** Comparison operator names — the `$`-prefixed keys inside an operator object. */
+type PredicateOp = "$eq" | "$ne" | "$in" | "$nin" | "$exists" | "$gt" | "$gte" | "$lt" | "$lte" | "$between" | "$matches" | "$startsWith" | "$endsWith" | "$contains" | "$changed";
+/** Combinator node keys. */
+type PredicateCombinatorKey = "$all" | "$any" | "$not";
+/**
+ * `true` when `V` supports relational operators (`$gt` … `$between`).
+ * `[V]` tuple-wrapping suppresses distribution over union-typed facts.
+ */
+type IsOrderable<V> = [V] extends [number | bigint | Date] ? true : [V] extends [string] ? true : false;
+/**
+ * The operator object permitted for a fact of type `V`. Built as a
+ * **per-operator union** (one operator per member) rather than an
+ * intersection — a typo'd operator (`$eqq`) then matches no member and is a
+ * compile error, and a relational operator on a non-orderable fact resolves
+ * to `never`.
+ *
+ * One operator per object — for two operators on the same fact, write the
+ * array form or `$all`. This is by design (the type is the source of truth).
+ *
+ * `$matches` requires `RegExp`. The runtime throws on string operands.
+ *
+ * @example
+ * ```ts
+ * const op1: OperatorObject<number> = { $gte: 30 };
+ * const op2: OperatorObject<string> = { $matches: /^J/i };
+ * const op3: OperatorObject<string> = { $in: ["red", "yellow"] };
+ * const op4: OperatorObject<string> = { $startsWith: "Ada" };
+ * const op5: OperatorObject<string> = { $endsWith: ".com" };
+ * ```
+ */
+type OperatorObject<V> = {
+    $eq: V;
+} | {
+    $ne: V;
+} | {
+    $in: readonly V[];
+} | {
+    $nin: readonly V[];
+} | {
+    $exists: boolean;
+} | {
+    $changed: true;
+} | (IsOrderable<V> extends true ? {
+    $gt: V;
+} | {
+    $gte: V;
+} | {
+    $lt: V;
+} | {
+    $lte: V;
+} | {
+    $between: readonly [V, V];
+} : never) | ([V] extends [string] ? {
+    $matches: RegExp;
+} | {
+    $contains: string;
+} | {
+    $startsWith: string;
+} | {
+    $endsWith: string;
+} : never) | ([V] extends [readonly (infer E)[]] ? {
+    $contains: E;
+} : never);
+/**
+ * The spec for a single fact key: a bare value (equality), an operator
+ * object, or — for an object-typed fact — a nested predicate (partial match).
+ */
+type PredicateField<V> = V | OperatorObject<V> | ([V] extends [readonly unknown[]] ? never : [V] extends [object] ? PredicateObject<V> : never);
+/**
+ * Object form — every key is a fact name, every value a
+ * {@link PredicateField}. Multiple keys are AND-ed. A nested object value
+ * recurses (partial match), which is how cross-module namespaced predicates
+ * (`{ self: { phase: "red" }, auth: { token: { $exists: true } } }`) work.
+ */
+type PredicateObject<F> = {
+    [K in keyof F]?: PredicateField<F[K]>;
+};
+/** Array form — explicit clauses, AND-ed. The codegen/devtools-friendly form. */
+type PredicateClause<F> = {
+    [K in keyof F]: {
+        readonly fact: K;
+        readonly op: PredicateOp;
+        readonly value: unknown;
+    };
+}[keyof F];
+/** Combinator node — exactly one of `$all` / `$any` / `$not`. */
+type PredicateCombinator<F> = {
+    $all: readonly FactPredicate<F>[];
+    $any?: never;
+    $not?: never;
+} | {
+    $any: readonly FactPredicate<F>[];
+    $all?: never;
+    $not?: never;
+} | {
+    $not: FactPredicate<F>;
+    $all?: never;
+    $any?: never;
+};
+/**
+ * A declarative boolean spec over a fact namespace `F`. The data form of a
+ * constraint `when`, an effect `on`, or a boolean derivation. Accepts an
+ * object form, an array-of-clauses form, or a combinator node.
+ *
+ * Keys are **fact names only** — derivations are not addressable from inside
+ * a predicate. To gate on a derivation, either reference the underlying fact
+ * the derivation reads, or fall back to the function form of `when` / `on`.
+ *
+ * @example
+ * ```ts
+ * // Object form (the common case)
+ * const p1: FactPredicate<{ phase: string; elapsed: number }> = {
+ *   phase: "red",
+ *   elapsed: { $gte: 30 },
+ * };
+ *
+ * // Combinator form
+ * const p2: FactPredicate<{ phase: string }> = {
+ *   $any: [{ phase: "red" }, { phase: "yellow" }],
+ * };
+ * ```
+ */
+type FactPredicate<F> = PredicateObject<F> | readonly PredicateClause<F>[] | PredicateCombinator<F>;
+/**
+ * A fact-interpolating string expression. `${key}` placeholders are replaced
+ * with the named fact's value; `$${` emits a literal `${`. The value-producing
+ * counterpart to {@link FactPredicate} — usable as a string derivation, a
+ * constraint `require` field value, or an event `patch` value.
+ *
+ * @example { $template: "Phase ${phase} for ${elapsed}s" }
+ */
+interface FactTemplate {
+    readonly $template: string;
+}
+/**
+ * *Note: despite the "Selector" name, this does not select from facts — it
+ * projects fields of the requirement payload for stable-stringification.*
+ *
+ * A resolver dedup key written as data: an ordered list of requirement-payload
+ * field names. `key: ["type", "to"]` dedupes requirements by those fields.
+ *
+ * @example
+ * ```ts
+ * resolvers: {
+ *   fetch: {
+ *     requirement: "FETCH",
+ *     key: ["url", "method"] satisfies KeySelector<{ url: string; method: string }>,
+ *     resolve: doFetch,
+ *   },
+ * }
+ * ```
+ */
+type KeySelector<R> = readonly (keyof R & string)[];
+/**
+ * *Note: Directive's `$ref` is **not** a JSON Pointer or JSON Schema `$ref`.
+ * It is a payload field copy — equivalent to `event.payload[key]`. Renaming
+ * to `$from` is tracked as a possible v1.6+ additive alias.*
+ *
+ * A typed single-field copy from an event payload. Lives in the patch-spec
+ * namespace — used inside a {@link PatchSpec} `$set` value.
+ *
+ * @example
+ * ```ts
+ * patch: { $set: { userId: { $ref: "id" } satisfies PayloadRef<{ id: string }> } }
+ * ```
+ */
+interface PayloadRef<P> {
+    readonly $ref: keyof P & string;
+}
+/**
+ * A patch value: a literal, a typed payload copy, or (for string facts) a
+ * template. Lives in the patch-spec namespace — used inside a {@link PatchSpec}
+ * `$set` block.
+ *
+ * @example
+ * ```ts
+ * const v1: PatchValue<boolean, { active: boolean }> = true;
+ * const v2: PatchValue<string, { name: string }> = { $ref: "name" };
+ * const v3: PatchValue<string, { name: string }> = { $template: "user ${name}" };
+ * ```
+ */
+type PatchValue<V, P> = V | PayloadRef<P> | ([V] extends [string] ? FactTemplate : never);
+/**
+ * An event handler written as data: assigns facts from literals, payload
+ * fields (`$ref`), or interpolated strings (`$template`).
+ *
+ * @example
+ * ```ts
+ * const spec: PatchSpec<{ status: string; label: string }, { name: string }> = {
+ *   $set: {
+ *     status: "active",
+ *     label: { $template: "user ${name}" },
+ *   },
+ * };
+ * ```
+ */
+interface PatchSpec<F, P> {
+    readonly $set: {
+        [K in keyof F]?: PatchValue<F[K], P>;
+    };
+}
+/**
+ * The per-clause result of an explained predicate evaluation. One entry per
+ * leaf operator (`$eq`, `$gte`, …); combinator nodes (`$all`, `$any`, `$not`)
+ * may also appear as headers when the runtime emits them — hence the union
+ * over {@link PredicateCombinatorKey}.
+ *
+ * @example
+ * ```ts
+ * const result: ClauseResult = {
+ *   path: "elapsed",
+ *   op: "$gte",
+ *   expected: 30,
+ *   actual: 20,
+ *   pass: false,
+ * };
+ * ```
+ */
+interface ClauseResult {
+    /** Dotted path to the fact (`elapsed`, `auth.token`). */
+    readonly path: string;
+    /** The operator applied (`$gte`, `$eq`, …) — `$eq` for a bare value. */
+    readonly op: PredicateOp | PredicateCombinatorKey;
+    /**
+     * The value the predicate expected. For combinator clauses (`$all`,
+     * `$any`, `$not`) this is the child count.
+     */
+    readonly expected: unknown;
+    /**
+     * The actual fact value at evaluation time. For combinator clauses this
+     * is the number of child clauses that passed.
+     */
+    readonly actual: unknown;
+    /** Whether this clause passed. */
+    readonly pass: boolean;
+    /**
+     * Children of a combinator clause (`$all`, `$any`, `$not`). Preserves the
+     * tree shape of the original predicate so renderers (devtools,
+     * `system.explain()`) can indent nested clauses.
+     */
+    readonly children?: ClauseResult[];
+}
+
 /**
  * Requirement Types - Type definitions for requirements and constraints
  */
@@ -268,47 +526,23 @@ type RequirementsSchema = Record<string, RequirementPayloadSchema>;
  * - No requirements: `null` or `[]`
  */
 type RequirementOutput$1<R extends Requirement = Requirement> = R | R[] | null;
-/**
- * Resolver-to-constraint binding mode (RFC-1: Resolver Constraint-Binding).
- *
- * Controls whether fact writes from a resolver are *bound* to the constraint
- * that triggered them. When the binding is `'auto'`, every write performed by
- * the resolver re-evaluates the constraint's `when()` predicate against the
- * latest facts; if `when()` no longer holds, the write is dropped, the
- * resolver's {@link AbortController} is aborted, and `ctx.signal.aborted`
- * becomes `true` so the resolver can early-exit on its next checkpoint.
- *
- * Binding is **one-shot per resolver invocation**: once `when()` flips to
- * `false`, the binding stays deactivated even if `when()` would later flip
- * back to `true` mid-resolver. This prevents a resolver from "resurrecting"
- * a stale intent after the user has moved past it.
- *
- * - `'none'` (default): Current behavior. Every fact write succeeds.
- * - `'auto'`: Writes are gated by the constraint's `when()` predicate. The
- *   predicate **must be synchronous** for `bind: 'auto'`; async constraints
- *   cannot be bound (their `when()` cannot be re-evaluated cheaply on every
- *   set).
- *
- * @example
- * ```ts
- * constraints: {
- *   leaveParty: {
- *     when: (f) => f.status === 'mutating',
- *     require: { type: 'EXECUTE_ACTION' },
- *     bind: 'auto', // resolver tail won't clobber `status = 'left'`
- *   },
- * }
- * ```
- */
-type ConstraintBindMode = "none" | "auto";
 /** Constraint definition */
 interface ConstraintDef<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>;
+    /**
+     * Condition the constraint requires. Either:
+     * - a function (sync or async) `(facts) => boolean`, or
+     * - a declarative {@link FactPredicate} spec — serializable, inspectable,
+     *   always synchronous; e.g. `{ phase: "red", elapsed: { $gte: 30 } }`.
+     *
+     * A data `when` is normalized to a wrapper function at registration; the
+     * wrapper still reads through the tracked facts proxy, so auto-tracking
+     * captures both fact and derivation deps correctly.
+     */
+    when: ((facts: Facts<S>) => boolean | Promise<boolean>) | FactPredicate<InferSchema<S>>;
     /**
      * Requirement(s) to produce when condition is met.
      * - Single requirement: `{ type: "RESTOCK", sku: "ABC" }`
@@ -320,21 +554,26 @@ interface ConstraintDef<S extends Schema, R extends Requirement = Requirement> {
     /** Timeout for async constraints (ms) */
     timeout?: number;
     /**
-     * Resolver-to-constraint binding mode (RFC-1).
-     *
-     * When `'auto'`, fact writes from the resolver triggered by this
-     * constraint are dropped (and the resolver is aborted) once `when()`
-     * flips to false. Defaults to `'none'` (current behavior preserved).
+     * Fact keys whose **value the resolver compare-and-swaps**. Writes to
+     * these facts land only if they still hold the snapshot value taken at
+     * resolver dispatch; otherwise the write is dropped and the resolver
+     * aborted.
      *
-     * **Forbidden on async constraints** (`async: true`): the binding
-     * checker re-evaluates `when()` synchronously on every fact write,
-     * which is incompatible with async predicates. Setting `bind: 'auto'`
-     * on an async constraint logs a dev-mode warning and is treated as
-     * `'none'`.
+     * This is value-based per-fact compare-and-swap with one-shot
+     * fact-level poisoning — not a lock, not document versioning. Writes
+     * to facts not listed always land; `when()` is not consulted. Omit for
+     * no binding (default). Ignored on async constraints.
      *
-     * @see {@link ConstraintBindMode}
+     * @example
+     * ```ts
+     * executeAction: {
+     *   when: (f) => f.status === 'mutating',
+     *   require: { type: 'EXECUTE_ACTION' },
+     *   owns: ['status'], // the resolver owns `status`
+     * }
+     * ```
      */
-    bind?: ConstraintBindMode;
+    owns?: readonly string[];
     /**
      * Constraint IDs whose resolvers must complete before this constraint is evaluated.
      * If a dependency's `when()` returns false (no requirements), this constraint proceeds.
@@ -435,6 +674,15 @@ interface EffectDef<S extends Schema> {
     run(facts: Facts<S>, prev: InferSchema<S> | null): void | EffectCleanup | Promise<void | EffectCleanup>;
     /** Optional explicit dependencies for optimization */
     deps?: Array<keyof InferSchema<S>>;
+    /**
+     * Optional declarative trigger — a {@link FactPredicate} that gates whether
+     * `run()` fires: even when a dependency changes, the effect runs only if
+     * the predicate currently holds. Mutually exclusive with `deps` — the
+     * predicate supplies its own deps via static extraction.
+     *
+     * @example on: { phase: "red", elapsed: { $gte: 30 } }
+     */
+    on?: FactPredicate<InferSchema<S>>;
     /** Optional metadata for debugging and devtools (never read on hot path). */
     meta?: DefinitionMeta;
 }
@@ -620,8 +868,13 @@ interface ResolverDef<S extends Schema, R extends Requirement = Requirement> {
      * - Function: type guard predicate (e.g., `requirement: (req) => req.type === "FETCH_USER"`)
      */
     requirement: string | ((req: Requirement) => req is R);
-    /** Custom key function for deduplication */
-    key?: RequirementKeyFn<R>;
+    /**
+     * Custom dedup key for the resolver. Either:
+     * - a `RequirementKeyFn<R>` function, or
+     * - a {@link KeySelector} array of requirement-payload field names:
+     *   `key: ["type", "to"]` builds a stable dedup key from those fields.
+     */
+    key?: RequirementKeyFn<R> | KeySelector<R>;
     /** Retry policy */
     retry?: RetryPolicy;
     /** Timeout for resolver execution (ms) */
@@ -1388,9 +1641,10 @@ type TypedDerivationFn<M extends ModuleSchema, K extends keyof GetDerivationsSch
  * Typed derivations definition using the module schema.
  * Each derivation key must match schema.derivations and return the declared type.
  */
+type TypedDerivationT<M extends ModuleSchema, K extends keyof GetDerivationsSchema<M>> = InferSchemaType<GetDerivationsSchema<M>[K]>;
 type TypedDerivationsDef<M extends ModuleSchema> = {
     [K in keyof GetDerivationsSchema<M>]: TypedDerivationFn<M, K> | {
-        compute: TypedDerivationFn<M, K>;
+        compute: TypedDerivationFn<M, K> | ([TypedDerivationT<M, K>] extends [boolean] ? FactPredicate<InferFacts<M>> : never) | ([TypedDerivationT<M, K>] extends [string] ? FactTemplate : never);
         meta?: DefinitionMeta;
     };
 };
@@ -1407,6 +1661,15 @@ type TypedEventsDef<M extends ModuleSchema> = {
     [K in keyof GetEventsSchema<M>]: TypedEventHandlerFn<M, K> | {
         handler: TypedEventHandlerFn<M, K>;
         meta?: DefinitionMeta;
+    } | {
+        /**
+         * Declarative event body: assigns facts from literals, payload
+         * fields ({@link KeySelector}), or interpolated strings
+         * ({@link FactTemplate}). Use instead of `handler` for simple
+         * "set facts from event payload" events.
+         */
+        patch: PatchSpec<InferFacts<M>, InferEventPayloadFromSchema<GetEventsSchema<M>[K]>>;
+        meta?: DefinitionMeta;
     };
 };
 /**
@@ -1421,8 +1684,12 @@ interface TypedConstraintDef<M extends ModuleSchema> {
     priority?: number;
     /** Mark this constraint as async */
     async?: boolean;
-    /** Condition function */
-    when: (facts: Facts<M["facts"]>) => boolean | Promise<boolean>;
+    /**
+     * Condition the constraint requires. Either a function (sync or async)
+     * `(facts) => boolean`, or a declarative {@link FactPredicate} spec
+     * (e.g. `{ phase: "red", elapsed: { $gte: 30 } }`).
+     */
+    when: ((facts: Facts<M["facts"]>) => boolean | Promise<boolean>) | FactPredicate<InferFacts<M>>;
     /**
      * Requirement(s) to produce when condition is met.
      */
@@ -1430,10 +1697,12 @@ interface TypedConstraintDef<M extends ModuleSchema> {
     /** Timeout for async constraints (ms) */
     timeout?: number;
     /**
-     * Resolver-to-constraint binding mode (RFC-1).
-     * Defaults to `'none'`. See {@link ConstraintBindMode}.
+     * Fact keys whose **value the resolver compare-and-swaps**. Writes to
+     * these facts land only if they still hold the snapshot value taken at
+     * resolver dispatch; otherwise the write is dropped and the resolver
+     * aborted. Omit for no binding (default). Ignored on async constraints.
      */
-    bind?: ConstraintBindMode;
+    owns?: readonly string[];
     /**
      * Constraint IDs whose resolvers must complete before this constraint is evaluated.
      * If a dependency's `when()` returns false (no requirements), this constraint proceeds.
@@ -1466,8 +1735,12 @@ interface CrossModuleConstraintDef<M extends ModuleSchema, Deps extends CrossMod
     priority?: number;
     /** Mark this constraint as async */
     async?: boolean;
-    /** Condition function with cross-module facts access */
-    when: (facts: CrossModuleFactsWithSelf<M, Deps>) => boolean | Promise<boolean>;
+    /**
+     * Condition the constraint requires. Either a function (sync or async)
+     * with cross-module facts access, or a nested {@link FactPredicate}:
+     * `{ self: { phase: "red" }, auth: { token: { $exists: true } } }`.
+     */
+    when: ((facts: CrossModuleFactsWithSelf<M, Deps>) => boolean | Promise<boolean>) | FactPredicate<CrossModuleFactsWithSelf<M, Deps>>;
     /**
      * Requirement(s) to produce when condition is met.
      */
@@ -1475,10 +1748,12 @@ interface CrossModuleConstraintDef<M extends ModuleSchema, Deps extends CrossMod
     /** Timeout for async constraints (ms) */
     timeout?: number;
     /**
-     * Resolver-to-constraint binding mode (RFC-1).
-     * Defaults to `'none'`. See {@link ConstraintBindMode}.
+     * Fact keys whose **value the resolver compare-and-swaps**. Writes to
+     * these facts land only if they still hold the snapshot value taken at
+     * resolver dispatch; otherwise the write is dropped and the resolver
+     * aborted. Omit for no binding (default). Ignored on async constraints.
      */
-    bind?: ConstraintBindMode;
+    owns?: readonly string[];
     /**
      * Constraint IDs whose resolvers must complete before this constraint is evaluated.
      * If a dependency's `when()` returns false (no requirements), this constraint proceeds.
@@ -1511,6 +1786,11 @@ interface CrossModuleEffectDef<M extends ModuleSchema, Deps extends CrossModuleD
     run: (facts: CrossModuleFactsWithSelf<M, Deps>, prev: CrossModuleFactsWithSelf<M, Deps> | undefined) => void | EffectCleanup | Promise<void | EffectCleanup>;
     /** Optional dependency keys to filter when effect runs */
     deps?: string[];
+    /**
+     * Optional declarative trigger — a {@link FactPredicate} that gates whether
+     * `run()` fires. Mutually exclusive with `deps`.
+     */
+    on?: FactPredicate<CrossModuleFactsWithSelf<M, Deps>>;
     /** Optional metadata for debugging and devtools (never read on hot path). */
     meta?: DefinitionMeta;
 }
@@ -1532,7 +1812,7 @@ type CrossModuleDerivationFn<M extends ModuleSchema, Deps extends CrossModuleDep
  */
 type CrossModuleDerivationsDef<M extends ModuleSchema, Deps extends CrossModuleDeps> = {
     [K in keyof GetDerivationsSchema<M>]: CrossModuleDerivationFn<M, Deps, K> | {
-        compute: CrossModuleDerivationFn<M, Deps, K>;
+        compute: CrossModuleDerivationFn<M, Deps, K> | ([TypedDerivationT<M, K>] extends [boolean] ? FactPredicate<CrossModuleFactsWithSelf<M, Deps>> : never) | ([TypedDerivationT<M, K>] extends [string] ? FactTemplate : never);
         meta?: DefinitionMeta;
     };
 };
@@ -1583,8 +1863,12 @@ type ExtractRequirement<M extends ModuleSchema, T extends keyof GetRequirementsS
 interface TypedResolverDef<M extends ModuleSchema, T extends keyof GetRequirementsSchema<M> & string> {
     /** Requirement type to handle */
     requirement: T;
-    /** Custom key function for deduplication */
-    key?: (req: ExtractRequirement<M, T>) => string;
+    /**
+     * Custom dedup key. Either a `(req) => string` function, or a
+     * {@link KeySelector} array of requirement-payload field names
+     * (`["type", "to"]`) that builds a stable key from those fields.
+     */
+    key?: ((req: ExtractRequirement<M, T>) => string) | KeySelector<ExtractRequirement<M, T>>;
     /** Retry policy */
     retry?: RetryPolicy;
     /** Timeout for resolver execution (ms) */
@@ -1845,6 +2129,11 @@ interface SystemInspection {
         hitCount: number;
         lastActiveAt: number | null;
         meta?: DefinitionMeta;
+        /**
+         * The data-form predicate spec (when the constraint's `when` is declarative),
+         * exposed for devtools and `explain()` rendering.
+         */
+        whenSpec?: FactPredicate<Record<string, unknown>>;
     }>;
     resolvers: Record<string, ResolverStatus>;
     /** All defined resolver names and their requirement types */
@@ -2095,7 +2384,7 @@ interface ResolversControl<M extends ModuleSchema = ModuleSchema> {
 interface DynamicConstraintDef<M extends ModuleSchema = ModuleSchema> {
     priority?: number;
     async?: boolean;
-    when: (facts: Readonly<InferSchema<M["facts"]>>) => boolean | Promise<boolean>;
+    when: ((facts: Readonly<InferSchema<M["facts"]>>) => boolean | Promise<boolean>) | FactPredicate<InferSchema<M["facts"]>>;
     require: {
         type: string;
         [key: string]: unknown;
@@ -2118,15 +2407,27 @@ interface DynamicConstraintDef<M extends ModuleSchema = ModuleSchema> {
 interface DynamicEffectDef<M extends ModuleSchema = ModuleSchema> {
     run: (facts: Readonly<InferSchema<M["facts"]>>, prev: InferSchema<M["facts"]> | null) => void | (() => void) | Promise<void | (() => void)>;
     deps?: Array<string & keyof InferSchema<M["facts"]>>;
+    /**
+     * Optional declarative trigger — a {@link FactPredicate} that gates whether
+     * `run()` fires. Mutually exclusive with `deps`.
+     */
+    on?: FactPredicate<InferSchema<M["facts"]>>;
     meta?: DefinitionMeta;
 }
 /** Resolver definition for dynamic registration — typed context.facts, relaxed requirement */
 interface DynamicResolverDef<M extends ModuleSchema = ModuleSchema> {
     requirement: string;
-    key?: (req: {
+    /**
+     * Custom dedup key. Either a `(req) => string` function, or a
+     * {@link KeySelector} array of requirement-payload field names.
+     */
+    key?: ((req: {
+        type: string;
+        [key: string]: unknown;
+    }) => string) | KeySelector<{
         type: string;
         [key: string]: unknown;
-    }) => string;
+    }>;
     retry?: RetryPolicy;
     timeout?: number;
     batch?: BatchConfig;
@@ -2185,6 +2486,11 @@ type ObservationEvent = {
     type: "constraint.evaluate";
     id: string;
     active: boolean;
+    /**
+     * Per-clause breakdown of a data-form predicate evaluation. Present
+     * only when the constraint's `when` is a {@link FactPredicate}.
+     */
+    whenExplain?: ClauseResult[];
 } | {
     type: "constraint.error";
     id: string;
@@ -2214,6 +2520,53 @@ type ObservationEvent = {
     resolver: string;
     requirementId: string;
     error: unknown;
+} | {
+    /**
+     * A real per-write rejection. A bound resolver's owned-fact write was
+     * dropped because the fact was changed by something outside the
+     * resolver between the resolver's baseline and its next write (RFC-0003
+     * optimistic-concurrency check). `reason` keeps the observation protocol
+     * backend-neutral — future write-rejecting backends can report other
+     * reasons without a new event type.
+     *
+     * `kind` discriminates this `"rejection"` arm from the `"summary"` arm:
+     * `fact`/`expected`/`actual` exist only here; `dropped` only on the
+     * summary. TypeScript forces the narrow.
+     *
+     * @example
+     * ```ts
+     * system.observe((e) => {
+     *   if (e.type === "resolver.write.rejected") {
+     *     if (e.kind === "summary") {
+     *       console.warn(`[rejected] ${e.resolver}: ${e.dropped} more writes dropped`);
+     *     } else {
+     *       console.warn(`[rejected] ${e.resolver} dropped ${e.fact}`);
+     *     }
+     *   }
+     * });
+     * ```
+     */
+    type: "resolver.write.rejected";
+    kind: "rejection";
+    resolver: string;
+    requirementId: string;
+    reason: "clobbered";
+    fact: string;
+    expected: unknown;
+    actual: unknown;
+} | {
+    /**
+     * The per-resolver suppression summary: emitted once when a single
+     * resolver instance exceeds the per-instance write-rejection cap (10).
+     * Further per-write `"rejection"` events for that instance are dropped;
+     * `dropped` reports how many were suppressed.
+     */
+    type: "resolver.write.rejected";
+    kind: "summary";
+    resolver: string;
+    requirementId: string;
+    reason: "clobbered";
+    dropped: number;
 } | {
     type: "effect.run";
     id: string;
@@ -2517,8 +2870,11 @@ interface Plugin<M extends ModuleSchema = ModuleSchema> {
      * Called after a constraint's `when` function is evaluated.
      * @param id - The constraint ID
      * @param active - Whether the constraint is active (when returned true)
+     * @param whenExplain - For data-form constraints, the per-clause breakdown
+     *   (which clauses passed, which failed, against what fact values). Omitted
+     *   for function-form `when`.
      */
-    onConstraintEvaluate?: (id: string, active: boolean) => void;
+    onConstraintEvaluate?: (id: string, active: boolean, whenExplain?: ClauseResult[]) => void;
     /**
      * Called when a constraint's `when` function throws an error.
      * @param id - The constraint ID
@@ -2574,6 +2930,53 @@ interface Plugin<M extends ModuleSchema = ModuleSchema> {
      * @param req - The requirement that was canceled
      */
     onResolverCancel?: (resolver: string, req: RequirementWithId) => void;
+    /**
+     * Called when a resolver's write is rejected by the runtime. The only
+     * `reason` today is `"clobbered"`: a bound resolver (RFC-0003) dropped a
+     * write to an owned fact because the fact was changed by something outside
+     * the resolver between the resolver's baseline and its next write — the
+     * resolver's `AbortController` is aborted in the same step. See
+     * {@link createBoundFacts} for the per-fact optimistic-concurrency model.
+     * `reason` keeps the hook backend-neutral.
+     *
+     * The `event` is a discriminated union on `kind`:
+     * - `"rejection"` — a real per-write rejection; carries
+     *   `fact`/`expected`/`actual`.
+     * - `"summary"` — the per-resolver suppression summary, emitted once when a
+     *   single resolver instance exceeds the per-instance write-rejection cap
+     *   (10); carries `dropped` (the count of suppressed `"rejection"` events).
+     *
+     * @param event - The write-rejection event (discriminated on `kind`).
+     *
+     * @example
+     * ```ts
+     * const myPlugin: Plugin = {
+     *   name: "write-rejection-logger",
+     *   onResolverWriteRejected(event) {
+     *     if (event.kind === "summary") {
+     *       console.warn(`[${event.resolver}] suppressed ${event.dropped} write rejections`);
+     *       return;
+     *     }
+     *     console.warn(`[clobber] ${event.resolver}: ${event.fact} expected=${JSON.stringify(event.expected)} actual=${JSON.stringify(event.actual)}`);
+     *   },
+     * };
+     * ```
+     */
+    onResolverWriteRejected?: (event: {
+        kind: "rejection";
+        resolver: string;
+        req: RequirementWithId;
+        reason: "clobbered";
+        fact: string;
+        expected: unknown;
+        actual: unknown;
+    } | {
+        kind: "summary";
+        resolver: string;
+        req: RequirementWithId;
+        reason: "clobbered";
+        dropped: number;
+    }) => void;
     /**
      * Called when an effect runs.
      * @param id - The effect ID
@@ -2643,4 +3046,4 @@ interface Plugin<M extends ModuleSchema = ModuleSchema> {
     onTraceComplete?: (entry: TraceEntry) => void;
 }
 
-export { type SystemInspection as $, type AnySystem as A, type BatchConfig as B, type CrossModuleDeps as C, type DefinitionMeta as D, type EffectsDef as E, type Facts as F, type InferFacts as G, type HistoryAPI as H, type InferDerivations as I, type InferRequirementTypes as J, type InferRequirements as K, type InferSchemaType as L, type ModuleSchema as M, type NamespacedSystem as N, type InferSelectorState as O, type Plugin as P, type MetaAccessor as Q, type RequirementWithId as R, type SchemaType as S, type TypedDerivationsDef as T, type MetaMatch as U, type ObservationEvent as V, type RetryPolicy as W, type Schema as X, type Snapshot as Y, type System as Z, type SystemConfig as _, type TypedEventsDef as a, type SystemMode as a0, type SystemSnapshot as a1, type TraceEntry as a2, isNamespacedSystem as a3, isSingleModuleSystem as a4, type FactsStore as a5, type ConstraintsDef as a6, type ConstraintState as a7, type ResolversDef as a8, type ConstraintBindMode as a9, type FactKeys as aA, type FactReturnType as aB, type FlexibleEventHandler as aC, type HistoryConfig as aD, type InferEventPayloadFromSchema as aE, type InferRequirementPayloadFromSchema as aF, type InferSchema as aG, type MutableNamespacedFacts as aH, type NamespacedDerivations as aI, type NamespacedEventsAccessor as aJ, type NamespacedFacts as aK, type ObservableKeys as aL, type RequirementExplanation as aM, type RequirementOutput as aN, type RequirementPayloadSchema$1 as aO, type RequirementsSchema as aP, type ResolverContext as aQ, type ResolversControl as aR, type SnapshotMeta as aS, type SystemEvent as aT, type TraceConfig as aU, type TypedConstraintDef as aV, type TypedResolverContext as aW, type TypedResolverDef as aX, type UnionEvents as aY, type RequirementOutput$1 as aZ, type ResolverStatus as aa, type FactChange as ab, type ReconcileResult as ac, type RecoveryStrategy as ad, type ErrorSource as ae, type RetryLaterConfig as af, type BatchItemResult as ag, type BatchResolveResults as ah, type ConstraintsControl as ai, type CrossModuleConstraintDef as aj, type CrossModuleDerivationFn as ak, type CrossModuleEffectDef as al, type CrossModuleFactsWithSelf as am, type DerivationKeys as an, type DerivationReturnType as ao, type DerivationsControl as ap, type DerivationsSchema as aq, type DeriveAccessor as ar, type DispatchEventsFromSchema as as, type EffectCleanup as at, type EffectsControl as au, type EventPayloadSchema as av, type EventsAccessor as aw, type EventsAccessorFromSchema as ax, type EventsDef as ay, type EventsSchema as az, type TypedConstraintsDef as b, type TypedResolversDef as c, type ModuleHooks as d, type CrossModuleDerivationsDef as e, type CrossModuleEffectsDef as f, type CrossModuleConstraintsDef as g, type ModuleDef as h, type CreateSystemOptionsSingle as i, type SingleModuleSystem as j, type ModulesMap as k, type CreateSystemOptionsNamed as l, type TraceOption as m, type ErrorBoundaryConfig as n, type Requirement as o, type RequirementKeyFn as p, DirectiveError as q, type DistributableSnapshot as r, type DistributableSnapshotOptions as s, type DynamicConstraintDef as t, type DynamicEffectDef as u, type DynamicResolverDef as v, type FactsSnapshot as w, type HistoryOption as x, type HistoryState as y, type InferEvents as z };
+export { type OperatorObject as $, type AnySystem as A, type BatchConfig as B, type ClauseResult as C, type DefinitionMeta as D, type EffectsDef as E, type FactTemplate as F, type FactsSnapshot as G, type HistoryAPI as H, type HistoryOption as I, type HistoryState as J, type InferDerivations as K, type InferEvents as L, type ModuleSchema as M, type NamespacedSystem as N, type InferFacts as O, type PatchSpec as P, type InferRequirementTypes as Q, type RequirementWithId as R, type SchemaType as S, type TypedDerivationsDef as T, type InferRequirements as U, type InferSchemaType as V, type InferSelectorState as W, type KeySelector as X, type MetaAccessor as Y, type MetaMatch as Z, type ObservationEvent as _, type FactPredicate as a, type RequirementsSchema as a$, type PatchValue as a0, type PayloadRef as a1, type PredicateClause as a2, type PredicateCombinator as a3, type PredicateCombinatorKey as a4, type PredicateObject as a5, type PredicateOp as a6, type RetryPolicy as a7, type Schema as a8, type Snapshot as a9, type DerivationReturnType as aA, type DerivationsControl as aB, type DerivationsSchema as aC, type DeriveAccessor as aD, type DispatchEventsFromSchema as aE, type EffectCleanup as aF, type EffectsControl as aG, type EventPayloadSchema as aH, type EventsAccessor as aI, type EventsAccessorFromSchema as aJ, type EventsDef as aK, type EventsSchema as aL, type FactKeys as aM, type FactReturnType as aN, type FlexibleEventHandler as aO, type HistoryConfig as aP, type InferEventPayloadFromSchema as aQ, type InferRequirementPayloadFromSchema as aR, type InferSchema as aS, type MutableNamespacedFacts as aT, type NamespacedDerivations as aU, type NamespacedEventsAccessor as aV, type NamespacedFacts as aW, type ObservableKeys as aX, type RequirementExplanation as aY, type RequirementOutput as aZ, type RequirementPayloadSchema$1 as a_, type System as aa, type SystemConfig as ab, type SystemInspection as ac, type SystemMode as ad, type SystemSnapshot as ae, type TraceEntry as af, isNamespacedSystem as ag, isSingleModuleSystem as ah, type FactsStore as ai, type ConstraintsDef as aj, type ConstraintState as ak, type ResolversDef as al, type ResolverStatus as am, type FactChange as an, type ReconcileResult as ao, type RecoveryStrategy as ap, type ErrorSource as aq, type RetryLaterConfig as ar, type BatchItemResult as as, type BatchResolveResults as at, type ConstraintsControl as au, type CrossModuleConstraintDef as av, type CrossModuleDerivationFn as aw, type CrossModuleEffectDef as ax, type CrossModuleFactsWithSelf as ay, type DerivationKeys as az, type Facts as b, type ResolverContext as b0, type ResolversControl as b1, type SnapshotMeta as b2, type SystemEvent as b3, type TraceConfig as b4, type TypedConstraintDef as b5, type TypedResolverContext as b6, type TypedResolverDef as b7, type UnionEvents as b8, type RequirementOutput$1 as b9, type TypedEventsDef as c, type TypedConstraintsDef as d, type TypedResolversDef as e, type ModuleHooks as f, type CrossModuleDeps as g, type CrossModuleDerivationsDef as h, type CrossModuleEffectsDef as i, type CrossModuleConstraintsDef as j, type ModuleDef as k, type CreateSystemOptionsSingle as l, type SingleModuleSystem as m, type ModulesMap as n, type CreateSystemOptionsNamed as o, type Plugin as p, type TraceOption as q, type ErrorBoundaryConfig as r, type Requirement as s, type RequirementKeyFn as t, DirectiveError as u, type DistributableSnapshot as v, type DistributableSnapshotOptions as w, type DynamicConstraintDef as x, type DynamicEffectDef as y, type DynamicResolverDef as z };