structured-context 0.12.0 → 0.13.0

package/dist/schema/metadata-contract.d.ts

@@ -94,6 +94,81 @@ declare const HIERARCHY_LEVEL_SCHEMA: {
     readonly required: readonly ["type"];
     readonly additionalProperties: false;
 };
+/** The verdicts the evaluation reserves besides a rule's own; a verdict map may set a severity for them. */
+export declare const RESERVED_VERDICTS: readonly ["missing-context"];
+/** Related-node kinds a semantic rule's `scope` can add: main-hierarchy edges only. `branch` is ancestors plus descendants. */
+export declare const SEMANTIC_SCOPES: readonly ["parent", "siblings", "children", "ancestors", "descendants", "branch"];
+/** The semantic part of a rule: a model evaluates the node against a rubric and returns a verdict. */
+declare const SEMANTIC_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        /** What the model judges the node against. Falls back to the rule's `description`. */
+        readonly rubric: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        /**
+         * The closed set of verdicts the model may return. Each is a description (what the verdict means, for the
+         * model) or `{ description, guidance }`, where `guidance` is shown to the user when it fires.
+         * Defaults to `pass`/`fail`.
+         */
+        readonly verdicts: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly oneOf: readonly [{
+                    readonly type: "string";
+                    readonly minLength: 1;
+                }, {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly description: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly guidance: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                    };
+                    readonly required: readonly ["description"];
+                    readonly additionalProperties: false;
+                }];
+            };
+            readonly minProperties: 2;
+        };
+        /**
+         * Severity per verdict in effect (declared, default or reserved). A verdict mapped to `ignore` is judged but
+         * not reported, and a verdict left out passes. Required with `verdicts`; with the default verdicts, `fail`
+         * takes the rule's own `severity` instead.
+         */
+        readonly severity: {
+            readonly type: "object";
+            readonly additionalProperties: {
+                readonly enum: readonly ["error", "warning", "info", "ignore"];
+            };
+            readonly minProperties: 1;
+        };
+        /**
+         * Related nodes, along main-hierarchy edges, sent with the evaluated node. Additive; left out or empty means
+         * the evaluated node alone.
+         */
+        readonly scope: {
+            readonly type: "array";
+            readonly items: {
+                readonly enum: readonly ["parent", "siblings", "children", "ancestors", "descendants", "branch"];
+            };
+            readonly uniqueItems: true;
+        };
+        /**
+         * Which node bodies are sent: `nodeOnly` (the evaluated node's), `fullScope` (it and every related node's),
+         * or `true` for `fullScope`. Left out: no bodies.
+         */
+        readonly includeContent: {
+            readonly enum: readonly ["nodeOnly", "fullScope", true];
+        };
+    };
+    readonly additionalProperties: false;
+};
 declare const RULE_SCHEMA: {
     readonly type: "object";
     readonly properties: {
@@ -104,6 +179,9 @@ declare const RULE_SCHEMA: {
         readonly category: {
             readonly enum: readonly ["validation", "coherence", "workflow", "best-practice"];
         };
+        /**
+         * Severity of a failed `expression` and of the default `fail` verdict. Defaults from the category.
+         */
         readonly severity: {
             readonly enum: readonly ["error", "warning", "info"];
         };
@@ -111,23 +189,199 @@ declare const RULE_SCHEMA: {
             readonly type: "string";
             readonly minLength: 1;
         };
-        readonly check: {
+        /** JSONata test a node must pass. When the rule also has `semantic`, a failing node is reported without being evaluated by the model. */
+        readonly expression: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        /** Optional JSONata applicability condition, evaluated per node before the rule runs. The rule applies only when it returns true. */
+        readonly when: {
             readonly type: "string";
             readonly minLength: 1;
         };
+        /** A model evaluates the node against a rubric. `{}` takes every default; `true` means the same. */
+        readonly semantic: {
+            readonly oneOf: readonly [{
+                readonly const: true;
+            }, {
+                readonly type: "object";
+                readonly properties: {
+                    /** What the model judges the node against. Falls back to the rule's `description`. */
+                    readonly rubric: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    /**
+                     * The closed set of verdicts the model may return. Each is a description (what the verdict means, for the
+                     * model) or `{ description, guidance }`, where `guidance` is shown to the user when it fires.
+                     * Defaults to `pass`/`fail`.
+                     */
+                    readonly verdicts: {
+                        readonly type: "object";
+                        readonly additionalProperties: {
+                            readonly oneOf: readonly [{
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            }, {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly description: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly guidance: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                };
+                                readonly required: readonly ["description"];
+                                readonly additionalProperties: false;
+                            }];
+                        };
+                        readonly minProperties: 2;
+                    };
+                    /**
+                     * Severity per verdict in effect (declared, default or reserved). A verdict mapped to `ignore` is judged but
+                     * not reported, and a verdict left out passes. Required with `verdicts`; with the default verdicts, `fail`
+                     * takes the rule's own `severity` instead.
+                     */
+                    readonly severity: {
+                        readonly type: "object";
+                        readonly additionalProperties: {
+                            readonly enum: readonly ["error", "warning", "info", "ignore"];
+                        };
+                        readonly minProperties: 1;
+                    };
+                    /**
+                     * Related nodes, along main-hierarchy edges, sent with the evaluated node. Additive; left out or empty means
+                     * the evaluated node alone.
+                     */
+                    readonly scope: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly enum: readonly ["parent", "siblings", "children", "ancestors", "descendants", "branch"];
+                        };
+                        readonly uniqueItems: true;
+                    };
+                    /**
+                     * Which node bodies are sent: `nodeOnly` (the evaluated node's), `fullScope` (it and every related node's),
+                     * or `true` for `fullScope`. Left out: no bodies.
+                     */
+                    readonly includeContent: {
+                        readonly enum: readonly ["nodeOnly", "fullScope", true];
+                    };
+                };
+                readonly additionalProperties: false;
+            }];
+        };
         readonly type: {
             readonly type: "string";
             readonly minLength: 1;
         };
-        readonly scope: {
-            readonly enum: readonly ["global"];
+        /** Run once for the whole space instead of once per node. */
+        readonly global: {
+            readonly type: "boolean";
         };
         readonly override: {
             readonly type: "boolean";
         };
+        /** Whether a failure of this rule gates (suppresses) downstream rules on the node's hierarchy subtree. Defaults to true when the failure's severity is `error`. */
+        readonly gatesDescendants: {
+            readonly type: "boolean";
+        };
     };
-    readonly required: readonly ["id", "category", "description", "check"];
+    readonly required: readonly ["id", "category", "description"];
     readonly additionalProperties: false;
+    readonly allOf: readonly [{
+        readonly anyOf: readonly [{
+            readonly required: readonly ["expression"];
+        }, {
+            readonly required: readonly ["semantic"];
+        }];
+    }, {
+        readonly if: {
+            readonly required: readonly ["global"];
+            readonly properties: {
+                readonly global: {
+                    readonly const: true;
+                };
+            };
+        };
+        readonly then: {
+            readonly not: {
+                readonly anyOf: readonly [{
+                    readonly required: readonly ["when"];
+                }, {
+                    readonly required: readonly ["type"];
+                }, {
+                    readonly required: readonly ["semantic"];
+                }];
+            };
+        };
+    }, {
+        readonly if: {
+            readonly required: readonly ["semantic"];
+            readonly properties: {
+                readonly semantic: {
+                    readonly type: "object";
+                    readonly required: readonly ["verdicts"];
+                };
+            };
+        };
+        readonly then: {
+            readonly properties: {
+                readonly semantic: {
+                    readonly type: "object";
+                    readonly required: readonly ["severity"];
+                };
+            };
+        };
+    }, {
+        readonly if: {
+            readonly required: readonly ["semantic"];
+            readonly properties: {
+                readonly semantic: {
+                    readonly type: "object";
+                    readonly not: {
+                        readonly required: readonly ["verdicts"];
+                    };
+                };
+            };
+        };
+        readonly then: {
+            readonly properties: {
+                readonly semantic: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly severity: {
+                            readonly type: "object";
+                            readonly not: {
+                                readonly required: readonly ["fail"];
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    }, {
+        readonly if: {
+            readonly required: readonly ["semantic"];
+            readonly properties: {
+                readonly semantic: {
+                    readonly type: "object";
+                    readonly required: readonly ["verdicts"];
+                };
+            };
+            readonly not: {
+                readonly required: readonly ["expression"];
+            };
+        };
+        readonly then: {
+            readonly not: {
+                readonly required: readonly ["severity"];
+            };
+        };
+    }];
 };
 declare const REF_SCHEMA: {
     readonly type: "object";
@@ -435,6 +689,9 @@ export declare const METADATA_SCHEMA: {
                     readonly category: {
                         readonly enum: readonly ["validation", "coherence", "workflow", "best-practice"];
                     };
+                    /**
+                     * Severity of a failed `expression` and of the default `fail` verdict. Defaults from the category.
+                     */
                     readonly severity: {
                         readonly enum: readonly ["error", "warning", "info"];
                     };
@@ -442,23 +699,199 @@ export declare const METADATA_SCHEMA: {
                         readonly type: "string";
                         readonly minLength: 1;
                     };
-                    readonly check: {
+                    /** JSONata test a node must pass. When the rule also has `semantic`, a failing node is reported without being evaluated by the model. */
+                    readonly expression: {
                         readonly type: "string";
                         readonly minLength: 1;
                     };
+                    /** Optional JSONata applicability condition, evaluated per node before the rule runs. The rule applies only when it returns true. */
+                    readonly when: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    /** A model evaluates the node against a rubric. `{}` takes every default; `true` means the same. */
+                    readonly semantic: {
+                        readonly oneOf: readonly [{
+                            readonly const: true;
+                        }, {
+                            readonly type: "object";
+                            readonly properties: {
+                                /** What the model judges the node against. Falls back to the rule's `description`. */
+                                readonly rubric: {
+                                    readonly type: "string";
+                                    readonly minLength: 1;
+                                };
+                                /**
+                                 * The closed set of verdicts the model may return. Each is a description (what the verdict means, for the
+                                 * model) or `{ description, guidance }`, where `guidance` is shown to the user when it fires.
+                                 * Defaults to `pass`/`fail`.
+                                 */
+                                readonly verdicts: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: {
+                                        readonly oneOf: readonly [{
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        }, {
+                                            readonly type: "object";
+                                            readonly properties: {
+                                                readonly description: {
+                                                    readonly type: "string";
+                                                    readonly minLength: 1;
+                                                };
+                                                readonly guidance: {
+                                                    readonly type: "string";
+                                                    readonly minLength: 1;
+                                                };
+                                            };
+                                            readonly required: readonly ["description"];
+                                            readonly additionalProperties: false;
+                                        }];
+                                    };
+                                    readonly minProperties: 2;
+                                };
+                                /**
+                                 * Severity per verdict in effect (declared, default or reserved). A verdict mapped to `ignore` is judged but
+                                 * not reported, and a verdict left out passes. Required with `verdicts`; with the default verdicts, `fail`
+                                 * takes the rule's own `severity` instead.
+                                 */
+                                readonly severity: {
+                                    readonly type: "object";
+                                    readonly additionalProperties: {
+                                        readonly enum: readonly ["error", "warning", "info", "ignore"];
+                                    };
+                                    readonly minProperties: 1;
+                                };
+                                /**
+                                 * Related nodes, along main-hierarchy edges, sent with the evaluated node. Additive; left out or empty means
+                                 * the evaluated node alone.
+                                 */
+                                readonly scope: {
+                                    readonly type: "array";
+                                    readonly items: {
+                                        readonly enum: readonly ["parent", "siblings", "children", "ancestors", "descendants", "branch"];
+                                    };
+                                    readonly uniqueItems: true;
+                                };
+                                /**
+                                 * Which node bodies are sent: `nodeOnly` (the evaluated node's), `fullScope` (it and every related node's),
+                                 * or `true` for `fullScope`. Left out: no bodies.
+                                 */
+                                readonly includeContent: {
+                                    readonly enum: readonly ["nodeOnly", "fullScope", true];
+                                };
+                            };
+                            readonly additionalProperties: false;
+                        }];
+                    };
                     readonly type: {
                         readonly type: "string";
                         readonly minLength: 1;
                     };
-                    readonly scope: {
-                        readonly enum: readonly ["global"];
+                    /** Run once for the whole space instead of once per node. */
+                    readonly global: {
+                        readonly type: "boolean";
                     };
                     readonly override: {
                         readonly type: "boolean";
                     };
+                    /** Whether a failure of this rule gates (suppresses) downstream rules on the node's hierarchy subtree. Defaults to true when the failure's severity is `error`. */
+                    readonly gatesDescendants: {
+                        readonly type: "boolean";
+                    };
                 };
-                readonly required: readonly ["id", "category", "description", "check"];
+                readonly required: readonly ["id", "category", "description"];
                 readonly additionalProperties: false;
+                readonly allOf: readonly [{
+                    readonly anyOf: readonly [{
+                        readonly required: readonly ["expression"];
+                    }, {
+                        readonly required: readonly ["semantic"];
+                    }];
+                }, {
+                    readonly if: {
+                        readonly required: readonly ["global"];
+                        readonly properties: {
+                            readonly global: {
+                                readonly const: true;
+                            };
+                        };
+                    };
+                    readonly then: {
+                        readonly not: {
+                            readonly anyOf: readonly [{
+                                readonly required: readonly ["when"];
+                            }, {
+                                readonly required: readonly ["type"];
+                            }, {
+                                readonly required: readonly ["semantic"];
+                            }];
+                        };
+                    };
+                }, {
+                    readonly if: {
+                        readonly required: readonly ["semantic"];
+                        readonly properties: {
+                            readonly semantic: {
+                                readonly type: "object";
+                                readonly required: readonly ["verdicts"];
+                            };
+                        };
+                    };
+                    readonly then: {
+                        readonly properties: {
+                            readonly semantic: {
+                                readonly type: "object";
+                                readonly required: readonly ["severity"];
+                            };
+                        };
+                    };
+                }, {
+                    readonly if: {
+                        readonly required: readonly ["semantic"];
+                        readonly properties: {
+                            readonly semantic: {
+                                readonly type: "object";
+                                readonly not: {
+                                    readonly required: readonly ["verdicts"];
+                                };
+                            };
+                        };
+                    };
+                    readonly then: {
+                        readonly properties: {
+                            readonly semantic: {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly severity: {
+                                        readonly type: "object";
+                                        readonly not: {
+                                            readonly required: readonly ["fail"];
+                                        };
+                                    };
+                                };
+                            };
+                        };
+                    };
+                }, {
+                    readonly if: {
+                        readonly required: readonly ["semantic"];
+                        readonly properties: {
+                            readonly semantic: {
+                                readonly type: "object";
+                                readonly required: readonly ["verdicts"];
+                            };
+                        };
+                        readonly not: {
+                            readonly required: readonly ["expression"];
+                        };
+                    };
+                    readonly then: {
+                        readonly not: {
+                            readonly required: readonly ["severity"];
+                        };
+                    };
+                }];
             };
         };
     };
@@ -652,6 +1085,9 @@ export declare function buildDialectMetaSchema(id: string): {
                             readonly category: {
                                 readonly enum: readonly ["validation", "coherence", "workflow", "best-practice"];
                             };
+                            /**
+                             * Severity of a failed `expression` and of the default `fail` verdict. Defaults from the category.
+                             */
                             readonly severity: {
                                 readonly enum: readonly ["error", "warning", "info"];
                             };
@@ -659,23 +1095,199 @@ export declare function buildDialectMetaSchema(id: string): {
                                 readonly type: "string";
                                 readonly minLength: 1;
                             };
-                            readonly check: {
+                            /** JSONata test a node must pass. When the rule also has `semantic`, a failing node is reported without being evaluated by the model. */
+                            readonly expression: {
                                 readonly type: "string";
                                 readonly minLength: 1;
                             };
+                            /** Optional JSONata applicability condition, evaluated per node before the rule runs. The rule applies only when it returns true. */
+                            readonly when: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            /** A model evaluates the node against a rubric. `{}` takes every default; `true` means the same. */
+                            readonly semantic: {
+                                readonly oneOf: readonly [{
+                                    readonly const: true;
+                                }, {
+                                    readonly type: "object";
+                                    readonly properties: {
+                                        /** What the model judges the node against. Falls back to the rule's `description`. */
+                                        readonly rubric: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                        /**
+                                         * The closed set of verdicts the model may return. Each is a description (what the verdict means, for the
+                                         * model) or `{ description, guidance }`, where `guidance` is shown to the user when it fires.
+                                         * Defaults to `pass`/`fail`.
+                                         */
+                                        readonly verdicts: {
+                                            readonly type: "object";
+                                            readonly additionalProperties: {
+                                                readonly oneOf: readonly [{
+                                                    readonly type: "string";
+                                                    readonly minLength: 1;
+                                                }, {
+                                                    readonly type: "object";
+                                                    readonly properties: {
+                                                        readonly description: {
+                                                            readonly type: "string";
+                                                            readonly minLength: 1;
+                                                        };
+                                                        readonly guidance: {
+                                                            readonly type: "string";
+                                                            readonly minLength: 1;
+                                                        };
+                                                    };
+                                                    readonly required: readonly ["description"];
+                                                    readonly additionalProperties: false;
+                                                }];
+                                            };
+                                            readonly minProperties: 2;
+                                        };
+                                        /**
+                                         * Severity per verdict in effect (declared, default or reserved). A verdict mapped to `ignore` is judged but
+                                         * not reported, and a verdict left out passes. Required with `verdicts`; with the default verdicts, `fail`
+                                         * takes the rule's own `severity` instead.
+                                         */
+                                        readonly severity: {
+                                            readonly type: "object";
+                                            readonly additionalProperties: {
+                                                readonly enum: readonly ["error", "warning", "info", "ignore"];
+                                            };
+                                            readonly minProperties: 1;
+                                        };
+                                        /**
+                                         * Related nodes, along main-hierarchy edges, sent with the evaluated node. Additive; left out or empty means
+                                         * the evaluated node alone.
+                                         */
+                                        readonly scope: {
+                                            readonly type: "array";
+                                            readonly items: {
+                                                readonly enum: readonly ["parent", "siblings", "children", "ancestors", "descendants", "branch"];
+                                            };
+                                            readonly uniqueItems: true;
+                                        };
+                                        /**
+                                         * Which node bodies are sent: `nodeOnly` (the evaluated node's), `fullScope` (it and every related node's),
+                                         * or `true` for `fullScope`. Left out: no bodies.
+                                         */
+                                        readonly includeContent: {
+                                            readonly enum: readonly ["nodeOnly", "fullScope", true];
+                                        };
+                                    };
+                                    readonly additionalProperties: false;
+                                }];
+                            };
                             readonly type: {
                                 readonly type: "string";
                                 readonly minLength: 1;
                             };
-                            readonly scope: {
-                                readonly enum: readonly ["global"];
+                            /** Run once for the whole space instead of once per node. */
+                            readonly global: {
+                                readonly type: "boolean";
                             };
                             readonly override: {
                                 readonly type: "boolean";
                             };
+                            /** Whether a failure of this rule gates (suppresses) downstream rules on the node's hierarchy subtree. Defaults to true when the failure's severity is `error`. */
+                            readonly gatesDescendants: {
+                                readonly type: "boolean";
+                            };
                         };
-                        readonly required: readonly ["id", "category", "description", "check"];
+                        readonly required: readonly ["id", "category", "description"];
                         readonly additionalProperties: false;
+                        readonly allOf: readonly [{
+                            readonly anyOf: readonly [{
+                                readonly required: readonly ["expression"];
+                            }, {
+                                readonly required: readonly ["semantic"];
+                            }];
+                        }, {
+                            readonly if: {
+                                readonly required: readonly ["global"];
+                                readonly properties: {
+                                    readonly global: {
+                                        readonly const: true;
+                                    };
+                                };
+                            };
+                            readonly then: {
+                                readonly not: {
+                                    readonly anyOf: readonly [{
+                                        readonly required: readonly ["when"];
+                                    }, {
+                                        readonly required: readonly ["type"];
+                                    }, {
+                                        readonly required: readonly ["semantic"];
+                                    }];
+                                };
+                            };
+                        }, {
+                            readonly if: {
+                                readonly required: readonly ["semantic"];
+                                readonly properties: {
+                                    readonly semantic: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["verdicts"];
+                                    };
+                                };
+                            };
+                            readonly then: {
+                                readonly properties: {
+                                    readonly semantic: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["severity"];
+                                    };
+                                };
+                            };
+                        }, {
+                            readonly if: {
+                                readonly required: readonly ["semantic"];
+                                readonly properties: {
+                                    readonly semantic: {
+                                        readonly type: "object";
+                                        readonly not: {
+                                            readonly required: readonly ["verdicts"];
+                                        };
+                                    };
+                                };
+                            };
+                            readonly then: {
+                                readonly properties: {
+                                    readonly semantic: {
+                                        readonly type: "object";
+                                        readonly properties: {
+                                            readonly severity: {
+                                                readonly type: "object";
+                                                readonly not: {
+                                                    readonly required: readonly ["fail"];
+                                                };
+                                            };
+                                        };
+                                    };
+                                };
+                            };
+                        }, {
+                            readonly if: {
+                                readonly required: readonly ["semantic"];
+                                readonly properties: {
+                                    readonly semantic: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["verdicts"];
+                                    };
+                                };
+                                readonly not: {
+                                    readonly required: readonly ["expression"];
+                                };
+                            };
+                            readonly then: {
+                                readonly not: {
+                                    readonly required: readonly ["severity"];
+                                };
+                            };
+                        }];
                     };
                 };
             };
@@ -690,5 +1302,6 @@ export type MetadataContractRelationship = FromSchema<typeof RELATIONSHIP_SCHEMA
 export type SharedEdgeFields = FromSchema<typeof EDGE_SCHEMA>;
 export type SharedEmbeddingFields = FromSchema<typeof EMBEDDING_SCHEMA>;
 export type Rule = FromSchema<typeof RULE_SCHEMA>;
+export type RuleSemantic = FromSchema<typeof SEMANTIC_SCHEMA>;
 export type MetadataRef = FromSchema<typeof REF_SCHEMA>;
 export {};