@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.
- package/dist/adapter-utils.d.cts +1 -1
- package/dist/adapter-utils.d.ts +1 -1
- package/dist/audit-ledger-9IElAHH9.d.ts +205 -0
- package/dist/audit-ledger-qMjEBqiP.d.cts +205 -0
- package/dist/chunk-26Z5VNPZ.js +16 -0
- package/dist/{chunk-FCOZCTLY.js.map → chunk-26Z5VNPZ.js.map} +1 -1
- package/dist/chunk-4VZOZWXM.cjs +2 -0
- package/dist/chunk-4VZOZWXM.cjs.map +1 -0
- package/dist/chunk-7NMXRATK.cjs +3 -0
- package/dist/chunk-7NMXRATK.cjs.map +1 -0
- package/dist/chunk-7TSYQEN3.js +2 -0
- package/dist/chunk-7TSYQEN3.js.map +1 -0
- package/dist/{chunk-2OS4RCLV.cjs → chunk-EX3XG667.cjs} +3 -3
- package/dist/{chunk-2OS4RCLV.cjs.map → chunk-EX3XG667.cjs.map} +1 -1
- package/dist/chunk-TPOKS4RY.js +3 -0
- package/dist/chunk-TPOKS4RY.js.map +1 -0
- package/dist/{helpers-BwAThjnJ.d.ts → helpers-D2pfb6vT.d.ts} +1 -1
- package/dist/{helpers-CG27mEGG.d.cts → helpers-hh6UanB1.d.cts} +1 -1
- package/dist/index.cjs +4 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +344 -4
- package/dist/index.d.ts +344 -4
- package/dist/index.js +4 -4
- package/dist/index.js.map +1 -1
- package/dist/internals.cjs +1 -1
- package/dist/internals.d.cts +4 -4
- package/dist/internals.d.ts +4 -4
- package/dist/internals.js +1 -1
- package/dist/plugins/index.cjs +2 -2
- package/dist/plugins/index.cjs.map +1 -1
- package/dist/plugins/index.d.cts +2 -1
- package/dist/plugins/index.d.ts +2 -1
- package/dist/plugins/index.js +2 -2
- package/dist/plugins/index.js.map +1 -1
- package/dist/{plugins-DvrsPhzx.d.cts → plugins-Ykl_sAPE.d.cts} +1 -1
- package/dist/{plugins-DvrsPhzx.d.ts → plugins-Ykl_sAPE.d.ts} +1 -1
- package/dist/system-GK3NSFQH.cjs +2 -0
- package/dist/{system-DEMPYZHI.cjs.map → system-GK3NSFQH.cjs.map} +1 -1
- package/dist/system-VZWB6WXX.js +2 -0
- package/dist/{system-R4JL6U4S.js.map → system-VZWB6WXX.js.map} +1 -1
- package/dist/testing.cjs +1 -1
- package/dist/testing.d.cts +1 -1
- package/dist/testing.d.ts +1 -1
- package/dist/testing.js +1 -1
- package/dist/worker.cjs +1 -1
- package/dist/worker.d.cts +1 -1
- package/dist/worker.d.ts +1 -1
- package/dist/worker.js +1 -1
- package/package.json +1 -1
- package/dist/chunk-FCOZCTLY.js +0 -16
- package/dist/chunk-WIZHZF4G.cjs +0 -3
- package/dist/chunk-WIZHZF4G.cjs.map +0 -1
- package/dist/chunk-ZE2RY5KP.js +0 -3
- package/dist/chunk-ZE2RY5KP.js.map +0 -1
- package/dist/system-DEMPYZHI.cjs +0 -2
- 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,
|
|
2
|
-
export { A as AnySystem, B as BatchConfig,
|
|
3
|
-
export { D as DerivationDefWithMeta, t as typedConstraint, a as typedResolver } from './helpers-
|
|
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 };
|