@directive-run/core 1.10.0 → 1.12.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/dist/adapter-utils.d.cts +1 -1
  2. package/dist/adapter-utils.d.ts +1 -1
  3. package/dist/audit-ledger-9IElAHH9.d.ts +205 -0
  4. package/dist/audit-ledger-qMjEBqiP.d.cts +205 -0
  5. package/dist/chunk-26Z5VNPZ.js +16 -0
  6. package/dist/{chunk-FCOZCTLY.js.map → chunk-26Z5VNPZ.js.map} +1 -1
  7. package/dist/chunk-4VZOZWXM.cjs +2 -0
  8. package/dist/chunk-4VZOZWXM.cjs.map +1 -0
  9. package/dist/chunk-7NMXRATK.cjs +3 -0
  10. package/dist/chunk-7NMXRATK.cjs.map +1 -0
  11. package/dist/chunk-7TSYQEN3.js +2 -0
  12. package/dist/chunk-7TSYQEN3.js.map +1 -0
  13. package/dist/{chunk-2OS4RCLV.cjs → chunk-EX3XG667.cjs} +3 -3
  14. package/dist/{chunk-2OS4RCLV.cjs.map → chunk-EX3XG667.cjs.map} +1 -1
  15. package/dist/chunk-TPOKS4RY.js +3 -0
  16. package/dist/chunk-TPOKS4RY.js.map +1 -0
  17. package/dist/{helpers-BwAThjnJ.d.ts → helpers-D2pfb6vT.d.ts} +1 -1
  18. package/dist/{helpers-CG27mEGG.d.cts → helpers-hh6UanB1.d.cts} +1 -1
  19. package/dist/index.cjs +4 -4
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +344 -4
  22. package/dist/index.d.ts +344 -4
  23. package/dist/index.js +4 -4
  24. package/dist/index.js.map +1 -1
  25. package/dist/internals.cjs +1 -1
  26. package/dist/internals.d.cts +4 -4
  27. package/dist/internals.d.ts +4 -4
  28. package/dist/internals.js +1 -1
  29. package/dist/plugins/index.cjs +2 -2
  30. package/dist/plugins/index.cjs.map +1 -1
  31. package/dist/plugins/index.d.cts +2 -1
  32. package/dist/plugins/index.d.ts +2 -1
  33. package/dist/plugins/index.js +2 -2
  34. package/dist/plugins/index.js.map +1 -1
  35. package/dist/{plugins-DvrsPhzx.d.cts → plugins-Ykl_sAPE.d.cts} +1 -1
  36. package/dist/{plugins-DvrsPhzx.d.ts → plugins-Ykl_sAPE.d.ts} +1 -1
  37. package/dist/system-GK3NSFQH.cjs +2 -0
  38. package/dist/{system-DEMPYZHI.cjs.map → system-GK3NSFQH.cjs.map} +1 -1
  39. package/dist/system-VZWB6WXX.js +2 -0
  40. package/dist/{system-R4JL6U4S.js.map → system-VZWB6WXX.js.map} +1 -1
  41. package/dist/testing.cjs +1 -1
  42. package/dist/testing.d.cts +1 -1
  43. package/dist/testing.d.ts +1 -1
  44. package/dist/testing.js +1 -1
  45. package/dist/worker.cjs +1 -1
  46. package/dist/worker.d.cts +1 -1
  47. package/dist/worker.d.ts +1 -1
  48. package/dist/worker.js +1 -1
  49. package/package.json +1 -1
  50. package/dist/chunk-FCOZCTLY.js +0 -16
  51. package/dist/chunk-WIZHZF4G.cjs +0 -3
  52. package/dist/chunk-WIZHZF4G.cjs.map +0 -1
  53. package/dist/chunk-ZE2RY5KP.js +0 -3
  54. package/dist/chunk-ZE2RY5KP.js.map +0 -1
  55. package/dist/system-DEMPYZHI.cjs +0 -2
  56. package/dist/system-R4JL6U4S.js +0 -2
package/dist/index.d.cts CHANGED
@@ -1,8 +1,133 @@
1
- import { P as PatchSpec, C as ClauseResult, F as FactTemplate, a as FactPredicate, S as SchemaType, D as DefinitionMeta, M as ModuleSchema, b as Facts, T as TypedDerivationsDef, c as TypedEventsDef, E as EffectsDef, d as TypedConstraintsDef, e as TypedResolversDef, f as ModuleHooks, g as CrossModuleDeps, h as CrossModuleDerivationsDef, i as CrossModuleEffectsDef, j as CrossModuleConstraintsDef, k as ModuleDef, l as CreateSystemOptionsSingle, m as SingleModuleSystem, n as ModulesMap, o as CreateSystemOptionsNamed, N as NamespacedSystem, p as Plugin, q as TraceOption, r as ErrorBoundaryConfig, R as RequirementWithId, s as Requirement, t as RequirementKeyFn } from './plugins-DvrsPhzx.cjs';
2
- export { A as AnySystem, B as BatchConfig, u as DirectiveError, v as DistributableSnapshot, w as DistributableSnapshotOptions, x as DynamicConstraintDef, y as DynamicEffectDef, z as DynamicResolverDef, G as FactsSnapshot, H as HistoryAPI, I as HistoryOption, J as HistoryState, K as InferDerivations, L as InferEvents, O as InferFacts, Q as InferRequirementTypes, U as InferRequirements, V as InferSchemaType, W as InferSelectorState, X as KeySelector, Y as MetaAccessor, Z as MetaMatch, _ as ObservationEvent, $ as OperatorObject, 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-DvrsPhzx.cjs';
3
- export { D as DerivationDefWithMeta, t as typedConstraint, a as typedResolver } from './helpers-CG27mEGG.cjs';
1
+ 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';
2
+ 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';
3
+ export { D as DerivationDefWithMeta, t as typedConstraint, a as typedResolver } from './helpers-hh6UanB1.cjs';
4
+ 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';
4
5
  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';
5
6
 
7
+ /**
8
+ * Schema Introspection
9
+ *
10
+ * A runtime discriminant for every `t.*()` builder result, so downstream
11
+ * consumers (`predicateFromIntent`, `doctor`, future `predicateToZod`)
12
+ * can ask "what kind is this fact?" without grepping the source.
13
+ *
14
+ * The discriminant lives at `_kind?: SchemaKindNode` on `ExtendedSchemaType`.
15
+ * Base builders set it; chain mutators (`.nullable()`, `.brand()`, etc.)
16
+ * preserve / decorate it. When `_kind` is absent (legacy or third-party
17
+ * builder), the parser falls back to reading the freeform `_typeName`
18
+ * string. When even that fails: `{ kind: "unknown" }` — graceful close.
19
+ *
20
+ * This module has zero hot-path cost; it is only invoked when an
21
+ * introspecting caller asks for it.
22
+ */
23
+
24
+ /**
25
+ * The closed set of kinds a Directive schema field can be.
26
+ *
27
+ * Drives operator availability via {@link getOperatorsForKind}: e.g.
28
+ * `"number"` gets the orderable operators (`$gte`, `$lte`); `"boolean"`
29
+ * does not.
30
+ */
31
+ type SchemaKind = "number" | "string" | "boolean" | "bigint" | "date" | "array" | "object" | "record" | "tuple" | "enum" | "literal" | "union" | "branded" | "unknown";
32
+ /**
33
+ * A tree-shaped discriminator for a schema field. Composite kinds
34
+ * (array, object, tuple, etc.) carry their element / shape information
35
+ * so an LLM-prompt builder can show "cartTotal is a number" AND
36
+ * "items is an array of { sku: string, qty: number }".
37
+ *
38
+ * `nullable` / `hasDefault` flags appear on the inner node (NOT a
39
+ * wrapping kind) so operator-lookup on `t.number().nullable()` returns
40
+ * the number's operators unchanged — `$gte` works on the non-null arm.
41
+ */
42
+ type SchemaKindNode = ({
43
+ kind: "number" | "string" | "boolean" | "bigint" | "date" | "unknown";
44
+ } | {
45
+ kind: "literal";
46
+ value: string | number | boolean | null;
47
+ primitive: "string" | "number" | "boolean" | "null";
48
+ } | {
49
+ kind: "enum";
50
+ values: readonly (string | number)[];
51
+ primitive: "string" | "number";
52
+ } | {
53
+ kind: "array";
54
+ element: SchemaKindNode;
55
+ } | {
56
+ kind: "tuple";
57
+ elements: readonly SchemaKindNode[];
58
+ } | {
59
+ kind: "object";
60
+ shape: Record<string, SchemaKindNode>;
61
+ } | {
62
+ kind: "record";
63
+ value: SchemaKindNode;
64
+ } | {
65
+ kind: "union";
66
+ members: readonly SchemaKindNode[];
67
+ } | {
68
+ kind: "branded";
69
+ inner: SchemaKindNode;
70
+ }) & {
71
+ /** True if the schema accepts `null` (from `.nullable()` / `.optional()`). */
72
+ nullable?: boolean;
73
+ /** True if the schema has a `.default()`. */
74
+ hasDefault?: boolean;
75
+ };
76
+ /**
77
+ * Return the {@link SchemaKindNode} for a schema field. Prefers the
78
+ * explicit `_kind` discriminant set by the builder; falls back to
79
+ * parsing the freeform `_typeName` string for legacy / third-party
80
+ * builders that don't set `_kind`.
81
+ *
82
+ * @example
83
+ * ```ts
84
+ * getKind(t.number()) // → { kind: "number" }
85
+ * getKind(t.string().nullable()) // → { kind: "string", nullable: true }
86
+ * getKind(t.array(t.number())) // → { kind: "array", element: { kind: "number" } }
87
+ * ```
88
+ */
89
+ declare function getKind(schema: unknown): SchemaKindNode;
90
+ /**
91
+ * Walk the `facts` block of a module schema and emit a flat map from
92
+ * dotted path → kind node. Nested `t.object()` shapes flatten using
93
+ * `.` as the separator, matching the convention used by
94
+ * `OperatorObject<V>`'s nested-path support.
95
+ *
96
+ * Passing a top-level schema directly (without the `facts:` wrapper)
97
+ * also works — anything iterable as `Record<string, ExtendedSchemaType>`
98
+ * is acceptable.
99
+ */
100
+ declare function getSchemaFieldKinds(schema: unknown): Map<string, SchemaKindNode>;
101
+ /**
102
+ * Return the set of `PredicateOp` strings that are valid against a
103
+ * given {@link SchemaKindNode}.
104
+ *
105
+ * Mirrors the type-level matrix encoded in `OperatorObject<V>` in
106
+ * `types/predicate.ts` — drift between the two is enforced by the
107
+ * compile-time conformance test
108
+ * (`schema-introspection-conformance.test-d.ts`).
109
+ *
110
+ * - **Common to all kinds:** `$eq`, `$ne`, `$in`, `$nin`, `$exists`
111
+ * - **Orderable (`number`/`string`/`bigint`/`date`):** + `$gt`, `$gte`,
112
+ * `$lt`, `$lte`, `$between`
113
+ * - **String-specific:** + `$matches`, `$startsWith`, `$endsWith`, `$contains`
114
+ * - **Array:** + `$contains` (over the element type)
115
+ * - **Union:** *intersection* across members (the operand must be valid
116
+ * for every branch).
117
+ * - **Branded:** delegates to the inner kind.
118
+ * - **Literal / Enum:** operators of the primitive, with `$eq` / `$in`
119
+ * operand restricted at the LLM-prompt layer (not enforced here).
120
+ *
121
+ * `nullable` does not change operator availability — `$gte` on a
122
+ * nullable number is fine on the non-null arm; `$exists` handles null.
123
+ */
124
+ declare function getOperatorsForKind(node: SchemaKindNode): readonly PredicateOp[];
125
+ /**
126
+ * Return all known predicate operators — convenience for prompt builders
127
+ * that need to show the LLM the full set.
128
+ */
129
+ declare function listAllPredicateOperators(): readonly PredicateOp[];
130
+
6
131
  /**
7
132
  * Runtime for data-configuration predicates and templates.
8
133
  *
@@ -69,6 +194,57 @@ declare function isTemplate(v: unknown): v is FactTemplate;
69
194
  * ```
70
195
  */
71
196
  declare function validatePredicate(spec: unknown, path?: string): void;
197
+
198
+ interface SchemaValidationError {
199
+ /** Dotted path to the failing clause (e.g. `cartTotal`, `auth.token.$gte`). */
200
+ readonly path: string;
201
+ /** The operator that failed (or the literal-equality marker `$eq`). */
202
+ readonly op: string;
203
+ /** The kind of the fact at this path, or `undefined` when the fact wasn't in the kind map. */
204
+ readonly kind?: SchemaKindNode;
205
+ /** The operators that ARE allowed for this fact's kind. */
206
+ readonly allowedOps?: readonly string[];
207
+ /** Human-readable failure reason (suitable for feeding back to an LLM). */
208
+ readonly reason: string;
209
+ }
210
+ interface SchemaValidationOptions {
211
+ /** Reject predicates with more than this many operator clauses (DoS guard). Default unbounded. */
212
+ readonly maxOperatorCount?: number;
213
+ }
214
+ type SchemaValidationResult = {
215
+ ok: true;
216
+ operatorCount: number;
217
+ } | {
218
+ ok: false;
219
+ errors: readonly SchemaValidationError[];
220
+ operatorCount: number;
221
+ };
222
+ /**
223
+ * Cross-check an LLM-emitted (or otherwise externally-sourced) predicate
224
+ * against a schema's runtime kind map. Catches errors that
225
+ * {@link validatePredicate} cannot — operator-on-wrong-kind (`$gte` on a
226
+ * boolean fact), unknown fact paths, and (optionally) operator-count
227
+ * exhaustion DoS attempts.
228
+ *
229
+ * Pair with {@link validatePredicate} (structural / JSON safety) for full
230
+ * coverage. Use {@link getSchemaFieldKinds} to derive `kindMap` from a
231
+ * module schema.
232
+ *
233
+ * Designed for the LLM-emit retry loop: returns a list of errors with
234
+ * structured `{path, op, kind, allowedOps, reason}` rather than throwing,
235
+ * so the caller can feed the errors back to the model.
236
+ *
237
+ * @example
238
+ * ```ts
239
+ * const kindMap = getSchemaFieldKinds({ facts: { cartTotal: t.number(), active: t.boolean() } });
240
+ * const result = validatePredicateAgainstSchema(
241
+ * { cartTotal: { $gte: 50 }, active: { $gte: true } },
242
+ * kindMap,
243
+ * );
244
+ * // → { ok: false, errors: [{ path: "active", op: "$gte", reason: "..." }], operatorCount: 2 }
245
+ * ```
246
+ */
247
+ declare function validatePredicateAgainstSchema(spec: unknown, kindMap: Map<string, SchemaKindNode>, opts?: SchemaValidationOptions): SchemaValidationResult;
72
248
  /**
73
249
  * Evaluate a {@link FactPredicate} against a fact scope. `prev` (a previous
74
250
  * snapshot) is consulted only by the `$changed` operator.
@@ -648,6 +824,163 @@ declare function diffRules(options: DiffRulesOptions): RulesDiffReport;
648
824
  */
649
825
  declare function diffClauses(before: unknown, after: unknown): Change[];
650
826
 
827
+ /**
828
+ * predict() — "would this predicate fire against these facts, and if
829
+ * not, what facts must change to make it fire?"
830
+ *
831
+ * Closes the LLM-emit iteration loop: the model writes a rule,
832
+ * `predict()` says "this rule needs cartTotal ≥ 50 to fire; current
833
+ * value is 30," and the model rewrites accordingly. A predicate-aware
834
+ * preview that costs one walk of the predicate tree.
835
+ *
836
+ * Pure, sync, no engine dependency. Reuses `evaluatePredicateExplained`.
837
+ */
838
+
839
+ interface PredictMissingChange {
840
+ /** Dotted path to the fact. */
841
+ readonly path: string;
842
+ /** The operator that failed. */
843
+ readonly op: string;
844
+ /** What the predicate expected. */
845
+ readonly expected: unknown;
846
+ /** What the fact currently is. */
847
+ readonly actual: unknown;
848
+ /** Human-readable hint suitable for feeding back to an LLM or showing to a user. */
849
+ readonly suggestion: string;
850
+ }
851
+ interface PredictResult<F> {
852
+ /** True iff the predicate would fire against `facts`. */
853
+ readonly wouldFire: boolean;
854
+ /** Full clause-by-clause result (reuses the whenExplain payload). */
855
+ readonly whenExplain: readonly ClauseResult[];
856
+ /**
857
+ * List of failing clauses, each with a `suggestion` describing the
858
+ * smallest concrete change to `facts` that would make that clause pass.
859
+ * Empty when `wouldFire === true`.
860
+ */
861
+ readonly missingChanges: readonly PredictMissingChange[];
862
+ /** Reference to the predicate evaluated, for telemetry. */
863
+ readonly predicate: FactPredicate<F>;
864
+ }
865
+ /**
866
+ * Run a predicate against the current fact state and report whether it
867
+ * would fire — *and if not, which facts must change*.
868
+ *
869
+ * Designed for the LLM-iteration loop and for "preview the impact of this
870
+ * rule" UIs.
871
+ *
872
+ * @example
873
+ * ```ts
874
+ * const predicate = { cartTotal: { $gte: 50 }, region: { $in: ["US", "EU"] } };
875
+ * const facts = { cartTotal: 30, region: "US" };
876
+ *
877
+ * predict(predicate, facts);
878
+ * // → {
879
+ * // wouldFire: false,
880
+ * // whenExplain: [ {path: "cartTotal", op: "$gte", pass: false, ...}, ... ],
881
+ * // missingChanges: [
882
+ * // { path: "cartTotal", op: "$gte", expected: 50, actual: 30,
883
+ * // suggestion: "set cartTotal to at least 50 (currently 30)" },
884
+ * // ],
885
+ * // predicate: { cartTotal: { $gte: 50 }, region: { $in: ["US", "EU"] } },
886
+ * // }
887
+ * ```
888
+ */
889
+ declare function predict<F = Record<string, unknown>>(predicate: FactPredicate<F>, facts: F, prev?: F): PredictResult<F>;
890
+
891
+ /**
892
+ * doctor — "this rule contradicts an existing rule" gate (v1 stub).
893
+ *
894
+ * Walks a candidate FactPredicate against an existing system's
895
+ * constraint set (via `system.inspect().constraints`), flagging:
896
+ *
897
+ * - **direct contradiction:** same fact path, opposite-direction
898
+ * comparison (`$gte 50` vs `$lt 50` — they cannot both fire).
899
+ * - **subset:** candidate's range is a strict subset of an existing
900
+ * constraint's range (candidate `$gte 100` when existing already
901
+ * has `$gte 50`; the new rule never fires independently of the old).
902
+ * - **overlap:** shares ≥1 fact path with non-trivial intersection —
903
+ * a warning, not a hard error.
904
+ *
905
+ * Pairs with `predicateFromIntent`: an LLM-emitted predicate can be
906
+ * doctor-checked before assignment, and contradictions fed back into
907
+ * the LLM's retry prompt.
908
+ *
909
+ * This is a **structural** v1. Full SMT-lite (Z3.wasm) is deferred to
910
+ * a dedicated R4.B sprint; the primitive of "doctor says no" is what
911
+ * this slice ships. False negatives are acceptable (no contradiction
912
+ * reported when one exists in semantics that the structural checker
913
+ * can't see). False positives (contradiction reported where none
914
+ * exists) are NOT acceptable — every reported contradiction must be
915
+ * defensible.
916
+ *
917
+ * Pure, sync, no engine dependency.
918
+ */
919
+
920
+ type ContradictionType = "direct" | "subset" | "overlap";
921
+ interface Contradiction {
922
+ /** ID of the existing constraint that conflicts with the candidate. */
923
+ readonly constraintId: string;
924
+ /** Type of contradiction detected. */
925
+ readonly type: ContradictionType;
926
+ /** Human-readable explanation, suitable for showing to a user or LLM. */
927
+ readonly reason: string;
928
+ /** Path on the candidate predicate that triggered the finding. */
929
+ readonly candidatePath?: string;
930
+ /** Operator + value on the candidate side. */
931
+ readonly candidate?: {
932
+ op: string;
933
+ value: unknown;
934
+ };
935
+ /** Operator + value on the existing side. */
936
+ readonly existing?: {
937
+ op: string;
938
+ value: unknown;
939
+ };
940
+ }
941
+ interface CheckAgainstResult {
942
+ /** Hard contradictions — candidate never co-fires with existing rule. */
943
+ readonly contradictions: readonly Contradiction[];
944
+ /** Soft overlaps — shared facts with non-trivial intersection. */
945
+ readonly warnings: readonly Contradiction[];
946
+ }
947
+ /** Shape of `system.inspect().constraints[N]` we care about — accepts any superset. */
948
+ interface ExistingConstraint {
949
+ readonly id: string;
950
+ readonly whenSpec?: unknown;
951
+ }
952
+ declare const doctor: {
953
+ /**
954
+ * Check a candidate predicate against existing constraints. Returns
955
+ * contradictions (hard) + warnings (soft overlaps).
956
+ *
957
+ * @param candidate - The proposed predicate (typically LLM-emitted).
958
+ * @param existing - Either `system.inspect().constraints` directly,
959
+ * or any array of `{ id, whenSpec? }` shapes.
960
+ * Constraints without `whenSpec` (function-form
961
+ * `when:`) are skipped — they're opaque to us.
962
+ *
963
+ * @example
964
+ * ```ts
965
+ * const candidate = { cartTotal: { $gte: 100 } };
966
+ * const report = doctor.checkAgainst(
967
+ * candidate,
968
+ * system.inspect().constraints,
969
+ * );
970
+ * // → {
971
+ * // contradictions: [
972
+ * // { constraintId: "freeShipping", type: "subset",
973
+ * // reason: "Candidate's lower bound on cartTotal..." }
974
+ * // ],
975
+ * // warnings: []
976
+ * // }
977
+ * ```
978
+ */
979
+ checkAgainst<F = Record<string, unknown>>(candidate: FactPredicate<F>, existing: readonly ExistingConstraint[] | {
980
+ constraints: readonly ExistingConstraint[];
981
+ }): CheckAgainstResult;
982
+ };
983
+
651
984
  /**
652
985
  * Compile a `FactPredicate` to a parameterized Postgres-style SQL WHERE
653
986
  * clause. The same predicate that gates a constraint on the client can
@@ -835,6 +1168,13 @@ interface ExtendedSchemaType<T> extends SchemaType<T> {
835
1168
  _lastFailedIndex?: number;
836
1169
  /** Optional metadata for debugging and devtools (never read on hot path). */
837
1170
  readonly _meta?: DefinitionMeta;
1171
+ /**
1172
+ * Structured kind discriminant used by introspection-time consumers
1173
+ * (`predicateFromIntent`, `doctor`, `predicateToZod`). Optional for
1174
+ * back-compat with legacy / third-party builders; when absent, the
1175
+ * introspection layer parses `_typeName` instead.
1176
+ */
1177
+ readonly _kind?: SchemaKindNode;
838
1178
  }
839
1179
  /** Chainable schema type with all common methods */
840
1180
  interface ChainableSchemaType<T> extends ExtendedSchemaType<T> {
@@ -2075,4 +2415,4 @@ declare const Backoff: {
2075
2415
  readonly Exponential: "exponential";
2076
2416
  };
2077
2417
 
2078
- export { Backoff, type Branded, type ChainableSchemaType, type Change, type ChangeKind, ClauseResult, type ConstraintDiff, type ConstraintStatus, CreateSystemOptionsNamed, CreateSystemOptionsSingle, CrossModuleDeps, DefinitionMeta, type DiffRulesOptions, ErrorBoundaryConfig, type ExtendedSchemaType, FactPredicate, FactTemplate, Facts, type LeafClause, MAX_REPLAY_FRAMES, MAX_SWEEP_POINTS, type ModuleConfig, type ModuleConfigWithDeps, ModuleDef, ModuleHooks, ModuleSchema, ModulesMap, NamespacedSystem, PatchSpec, Plugin, type PredicateBacktestReport, type PredicateToMongoOptions, type PredicateToPostgrestOptions, type PredicateToSqlOptions, type PredicateToSqlResult, type ReplayDiffSample, type ReplayFrame, type ReplayUnderOptions, Requirement, RequirementSet, type RequirementTypeStatus, RequirementWithId, type RulesDiffReport, type RulesMapInput, SchemaType, type SignalClock, SingleModuleSystem, type SweepHole, type SweepPoint, type SweepReport, type SweepUnderOptions, type TimerFactOpts, type TimerFactState, TraceOption, applyPatch, completeTimer, createModule, createModuleFactory, createRequirementStatusPlugin, createStatusHook, createSystem, createSystemWithStatus, defaultClock, diffClauses, diffRules, elapsedMs, evaluateKeySelector, evaluatePredicate, evaluatePredicateExplained, evaluateTemplate, extractDeps, extractTemplateKeys, flattenPredicate, forType, framesFromHistory, framesFromSnapshots, generateRequirementId, initialTimerState, isPredicate, isRequirementType, isTemplate, memoizePredicate, pauseTimer, predicateToMongo, predicateToPostgrest, predicateToSQL, predicateToWhere, realClock, registerRepeat, remainingMs, replayUnder, req, resetTimer, resumeTimer, startTimer, sweepUnder, t, tickTimer, timerOps, toReplayFrames, toRulesMap, validatePredicate, virtualClock };
2418
+ 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 };