structured-context 0.11.0 → 0.13.0

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

@@ -1,5 +1,12 @@
 import type { FromSchema } from 'json-schema-to-ts';
-export declare const SCHEMA_META_ID = "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json";
+/** The JSON Schema dialect the structured-context dialect extends. */
+export declare const JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema";
+export declare const SCHEMA_META_BASE_URL = "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated";
+export declare const SCHEMA_META_FILE = "_structured_context_schema_meta.json";
+/** Meta-schema `$id` for a dialect version folder, e.g. `.../generated/0.12.0/_structured_context_schema_meta.json`. */
+export declare function schemaMetaId(folder: string): string;
+/** The URL schemas set as `$schema` to follow the newest dialect. Resolves to the newest versioned meta-schema. */
+export declare const SCHEMA_META_ID: string;
 /** Schema objects wrapping each prop group for type derivation via FromSchema. */
 declare const EDGE_SCHEMA: {
     readonly type: "object";
@@ -87,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: {
@@ -97,29 +179,211 @@ 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"];
+        };
         readonly description: {
             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 RULE_REF_SCHEMA: {
+declare const REF_SCHEMA: {
     readonly type: "object";
     readonly properties: {
         readonly $ref: {
@@ -130,9 +394,84 @@ declare const RULE_REF_SCHEMA: {
     readonly required: readonly ["$ref"];
     readonly additionalProperties: false;
 };
+declare const HIERARCHY_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly name: {
+            readonly type: "string";
+            readonly minLength: 1;
+        };
+        readonly override: {
+            readonly type: "boolean";
+        };
+        readonly levels: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly items: {
+                readonly oneOf: readonly [{
+                    readonly type: "string";
+                    readonly minLength: 1;
+                }, {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly selfRef: {
+                            readonly type: "boolean";
+                        };
+                        readonly selfRefField: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly templateFormat: {
+                            readonly enum: readonly ["heading", "list", "table", "page"];
+                        };
+                        readonly matchers: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly minItems: 1;
+                        };
+                        readonly embeddedTemplateFields: {
+                            readonly type: "array";
+                            readonly items: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                        };
+                        readonly field: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                        readonly fieldOn: {
+                            readonly enum: readonly ["child", "parent"];
+                        };
+                        readonly multiple: {
+                            readonly type: "boolean";
+                        };
+                        readonly type: {
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        };
+                    };
+                    readonly required: readonly ["type"];
+                    readonly additionalProperties: false;
+                }];
+            };
+        };
+        readonly allowSkipLevels: {
+            readonly type: "boolean";
+        };
+    };
+    readonly required: readonly ["levels"];
+    readonly additionalProperties: false;
+};
 declare const RELATIONSHIP_SCHEMA: {
     readonly type: "object";
     readonly properties: {
+        readonly override: {
+            readonly type: "boolean";
+        };
         readonly templateFormat: {
             readonly enum: readonly ["heading", "list", "table", "page"];
         };
@@ -176,76 +515,105 @@ declare const RELATIONSHIP_SCHEMA: {
 export declare const METADATA_SCHEMA: {
     readonly type: "object";
     readonly properties: {
+        readonly imports: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
         readonly hierarchy: {
-            readonly type: "object";
-            readonly properties: {
-                readonly levels: {
-                    readonly type: "array";
-                    readonly minItems: 1;
-                    readonly items: {
-                        readonly oneOf: readonly [{
-                            readonly type: "string";
-                            readonly minLength: 1;
-                        }, {
-                            readonly type: "object";
-                            readonly properties: {
-                                readonly selfRef: {
-                                    readonly type: "boolean";
-                                };
-                                readonly selfRefField: {
-                                    readonly type: "string";
-                                    readonly minLength: 1;
-                                };
-                                readonly templateFormat: {
-                                    readonly enum: readonly ["heading", "list", "table", "page"];
-                                };
-                                readonly matchers: {
-                                    readonly type: "array";
-                                    readonly items: {
+            readonly oneOf: readonly [{
+                readonly type: "object";
+                readonly properties: {
+                    readonly name: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly override: {
+                        readonly type: "boolean";
+                    };
+                    readonly levels: {
+                        readonly type: "array";
+                        readonly minItems: 1;
+                        readonly items: {
+                            readonly oneOf: readonly [{
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            }, {
+                                readonly type: "object";
+                                readonly properties: {
+                                    readonly selfRef: {
+                                        readonly type: "boolean";
+                                    };
+                                    readonly selfRefField: {
                                         readonly type: "string";
                                         readonly minLength: 1;
                                     };
-                                    readonly minItems: 1;
-                                };
-                                readonly embeddedTemplateFields: {
-                                    readonly type: "array";
-                                    readonly items: {
+                                    readonly templateFormat: {
+                                        readonly enum: readonly ["heading", "list", "table", "page"];
+                                    };
+                                    readonly matchers: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                        readonly minItems: 1;
+                                    };
+                                    readonly embeddedTemplateFields: {
+                                        readonly type: "array";
+                                        readonly items: {
+                                            readonly type: "string";
+                                            readonly minLength: 1;
+                                        };
+                                    };
+                                    readonly field: {
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    };
+                                    readonly fieldOn: {
+                                        readonly enum: readonly ["child", "parent"];
+                                    };
+                                    readonly multiple: {
+                                        readonly type: "boolean";
+                                    };
+                                    readonly type: {
                                         readonly type: "string";
                                         readonly minLength: 1;
                                     };
                                 };
-                                readonly field: {
-                                    readonly type: "string";
-                                    readonly minLength: 1;
-                                };
-                                readonly fieldOn: {
-                                    readonly enum: readonly ["child", "parent"];
-                                };
-                                readonly multiple: {
-                                    readonly type: "boolean";
-                                };
-                                readonly type: {
-                                    readonly type: "string";
-                                    readonly minLength: 1;
-                                };
-                            };
-                            readonly required: readonly ["type"];
-                            readonly additionalProperties: false;
-                        }];
+                                readonly required: readonly ["type"];
+                                readonly additionalProperties: false;
+                            }];
+                        };
+                    };
+                    readonly allowSkipLevels: {
+                        readonly type: "boolean";
                     };
                 };
-                readonly allowSkipLevels: {
-                    readonly type: "boolean";
+                readonly required: readonly ["levels"];
+                readonly additionalProperties: false;
+            }, {
+                readonly type: "object";
+                readonly properties: {
+                    readonly $ref: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
                 };
-            };
-            readonly required: readonly ["levels"];
-            readonly additionalProperties: false;
+                readonly required: readonly ["$ref"];
+                readonly additionalProperties: false;
+            }];
         };
         readonly relationships: {
             readonly type: "array";
             readonly items: {
                 readonly type: "object";
                 readonly properties: {
+                    readonly override: {
+                        readonly type: "boolean";
+                    };
                     readonly templateFormat: {
                         readonly enum: readonly ["heading", "list", "table", "page"];
                     };
@@ -290,143 +658,358 @@ export declare const METADATA_SCHEMA: {
         readonly aliases: {
             readonly type: "object";
             readonly additionalProperties: {
-                readonly type: "string";
-                readonly minLength: 1;
-            };
-        };
-        readonly rules: {
-            readonly type: "array";
-            readonly items: {
                 readonly oneOf: readonly [{
+                    readonly type: "string";
+                    readonly minLength: 1;
+                }, {
                     readonly type: "object";
                     readonly properties: {
-                        readonly id: {
+                        readonly type: {
                             readonly type: "string";
                             readonly minLength: 1;
                         };
-                        readonly category: {
-                            readonly enum: readonly ["validation", "coherence", "workflow", "best-practice"];
+                        readonly override: {
+                            readonly type: "boolean";
                         };
-                        readonly description: {
-                            readonly type: "string";
-                            readonly minLength: 1;
+                    };
+                    readonly required: readonly ["type"];
+                    readonly additionalProperties: false;
+                }];
+            };
+        };
+        readonly rules: {
+            readonly type: "array";
+            readonly items: {
+                readonly type: "object";
+                readonly properties: {
+                    readonly id: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    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"];
+                    };
+                    readonly description: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    /** 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;
+                    };
+                    /** 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"];
+                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 check: {
-                            readonly type: "string";
-                            readonly minLength: 1;
+                    };
+                    readonly then: {
+                        readonly not: {
+                            readonly anyOf: readonly [{
+                                readonly required: readonly ["when"];
+                            }, {
+                                readonly required: readonly ["type"];
+                            }, {
+                                readonly required: readonly ["semantic"];
+                            }];
                         };
-                        readonly type: {
-                            readonly type: "string";
-                            readonly minLength: 1;
+                    };
+                }, {
+                    readonly if: {
+                        readonly required: readonly ["semantic"];
+                        readonly properties: {
+                            readonly semantic: {
+                                readonly type: "object";
+                                readonly required: readonly ["verdicts"];
+                            };
                         };
-                        readonly scope: {
-                            readonly enum: readonly ["global"];
+                    };
+                    readonly then: {
+                        readonly properties: {
+                            readonly semantic: {
+                                readonly type: "object";
+                                readonly required: readonly ["severity"];
+                            };
                         };
-                        readonly override: {
-                            readonly type: "boolean";
+                    };
+                }, {
+                    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 required: readonly ["id", "category", "description", "check"];
-                    readonly additionalProperties: false;
                 }, {
-                    readonly type: "object";
-                    readonly properties: {
-                        readonly $ref: {
-                            readonly type: "string";
-                            readonly minLength: 1;
+                    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"];
                         };
                     };
-                    readonly required: readonly ["$ref"];
-                    readonly additionalProperties: false;
                 }];
             };
         };
     };
     readonly additionalProperties: false;
 };
-export declare const DIALECT_META_SCHEMA: {
-    readonly $schema: "http://json-schema.org/draft-07/schema#";
-    readonly $id: "https://raw.githubusercontent.com/mindsocket/structured-context/main/schemas/generated/_structured_context_schema_meta.json";
+/** The dialect meta-schema, published under `$id`. */
+export declare function buildDialectMetaSchema(id: string): {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly $id: string;
     readonly title: "structured-context schema dialect";
-    readonly description: "Extends JSON Schema Draft-07 with top-level $metadata for hierarchy and rule metadata.";
+    readonly description: "Extends JSON Schema 2020-12 with top-level $metadata for imports, hierarchy, relationships, aliases and rules.";
     readonly type: "object";
     readonly allOf: readonly [{
-        readonly $ref: "http://json-schema.org/draft-07/schema#";
+        readonly $ref: "https://json-schema.org/draft/2020-12/schema";
     }];
     readonly properties: {
         readonly $metadata: {
             readonly type: "object";
             readonly properties: {
+                readonly imports: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                };
                 readonly hierarchy: {
-                    readonly type: "object";
-                    readonly properties: {
-                        readonly levels: {
-                            readonly type: "array";
-                            readonly minItems: 1;
-                            readonly items: {
-                                readonly oneOf: readonly [{
-                                    readonly type: "string";
-                                    readonly minLength: 1;
-                                }, {
-                                    readonly type: "object";
-                                    readonly properties: {
-                                        readonly selfRef: {
-                                            readonly type: "boolean";
-                                        };
-                                        readonly selfRefField: {
-                                            readonly type: "string";
-                                            readonly minLength: 1;
-                                        };
-                                        readonly templateFormat: {
-                                            readonly enum: readonly ["heading", "list", "table", "page"];
-                                        };
-                                        readonly matchers: {
-                                            readonly type: "array";
-                                            readonly items: {
+                    readonly oneOf: readonly [{
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly name: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly override: {
+                                readonly type: "boolean";
+                            };
+                            readonly levels: {
+                                readonly type: "array";
+                                readonly minItems: 1;
+                                readonly items: {
+                                    readonly oneOf: readonly [{
+                                        readonly type: "string";
+                                        readonly minLength: 1;
+                                    }, {
+                                        readonly type: "object";
+                                        readonly properties: {
+                                            readonly selfRef: {
+                                                readonly type: "boolean";
+                                            };
+                                            readonly selfRefField: {
                                                 readonly type: "string";
                                                 readonly minLength: 1;
                                             };
-                                            readonly minItems: 1;
-                                        };
-                                        readonly embeddedTemplateFields: {
-                                            readonly type: "array";
-                                            readonly items: {
+                                            readonly templateFormat: {
+                                                readonly enum: readonly ["heading", "list", "table", "page"];
+                                            };
+                                            readonly matchers: {
+                                                readonly type: "array";
+                                                readonly items: {
+                                                    readonly type: "string";
+                                                    readonly minLength: 1;
+                                                };
+                                                readonly minItems: 1;
+                                            };
+                                            readonly embeddedTemplateFields: {
+                                                readonly type: "array";
+                                                readonly items: {
+                                                    readonly type: "string";
+                                                    readonly minLength: 1;
+                                                };
+                                            };
+                                            readonly field: {
+                                                readonly type: "string";
+                                                readonly minLength: 1;
+                                            };
+                                            readonly fieldOn: {
+                                                readonly enum: readonly ["child", "parent"];
+                                            };
+                                            readonly multiple: {
+                                                readonly type: "boolean";
+                                            };
+                                            readonly type: {
                                                 readonly type: "string";
                                                 readonly minLength: 1;
                                             };
                                         };
-                                        readonly field: {
-                                            readonly type: "string";
-                                            readonly minLength: 1;
-                                        };
-                                        readonly fieldOn: {
-                                            readonly enum: readonly ["child", "parent"];
-                                        };
-                                        readonly multiple: {
-                                            readonly type: "boolean";
-                                        };
-                                        readonly type: {
-                                            readonly type: "string";
-                                            readonly minLength: 1;
-                                        };
-                                    };
-                                    readonly required: readonly ["type"];
-                                    readonly additionalProperties: false;
-                                }];
+                                        readonly required: readonly ["type"];
+                                        readonly additionalProperties: false;
+                                    }];
+                                };
+                            };
+                            readonly allowSkipLevels: {
+                                readonly type: "boolean";
                             };
                         };
-                        readonly allowSkipLevels: {
-                            readonly type: "boolean";
+                        readonly required: readonly ["levels"];
+                        readonly additionalProperties: false;
+                    }, {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly $ref: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
                         };
-                    };
-                    readonly required: readonly ["levels"];
-                    readonly additionalProperties: false;
+                        readonly required: readonly ["$ref"];
+                        readonly additionalProperties: false;
+                    }];
                 };
                 readonly relationships: {
                     readonly type: "array";
                     readonly items: {
                         readonly type: "object";
                         readonly properties: {
+                            readonly override: {
+                                readonly type: "boolean";
+                            };
                             readonly templateFormat: {
                                 readonly enum: readonly ["heading", "list", "table", "page"];
                             };
@@ -471,54 +1054,239 @@ export declare const DIALECT_META_SCHEMA: {
                 readonly aliases: {
                     readonly type: "object";
                     readonly additionalProperties: {
-                        readonly type: "string";
-                        readonly minLength: 1;
-                    };
-                };
-                readonly rules: {
-                    readonly type: "array";
-                    readonly items: {
                         readonly oneOf: readonly [{
+                            readonly type: "string";
+                            readonly minLength: 1;
+                        }, {
                             readonly type: "object";
                             readonly properties: {
-                                readonly id: {
+                                readonly type: {
                                     readonly type: "string";
                                     readonly minLength: 1;
                                 };
-                                readonly category: {
-                                    readonly enum: readonly ["validation", "coherence", "workflow", "best-practice"];
+                                readonly override: {
+                                    readonly type: "boolean";
                                 };
-                                readonly description: {
-                                    readonly type: "string";
-                                    readonly minLength: 1;
+                            };
+                            readonly required: readonly ["type"];
+                            readonly additionalProperties: false;
+                        }];
+                    };
+                };
+                readonly rules: {
+                    readonly type: "array";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly properties: {
+                            readonly id: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            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"];
+                            };
+                            readonly description: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            /** 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;
+                            };
+                            /** 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"];
+                        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 check: {
-                                    readonly type: "string";
-                                    readonly minLength: 1;
+                            };
+                            readonly then: {
+                                readonly not: {
+                                    readonly anyOf: readonly [{
+                                        readonly required: readonly ["when"];
+                                    }, {
+                                        readonly required: readonly ["type"];
+                                    }, {
+                                        readonly required: readonly ["semantic"];
+                                    }];
                                 };
-                                readonly type: {
-                                    readonly type: "string";
-                                    readonly minLength: 1;
+                            };
+                        }, {
+                            readonly if: {
+                                readonly required: readonly ["semantic"];
+                                readonly properties: {
+                                    readonly semantic: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["verdicts"];
+                                    };
                                 };
-                                readonly scope: {
-                                    readonly enum: readonly ["global"];
+                            };
+                            readonly then: {
+                                readonly properties: {
+                                    readonly semantic: {
+                                        readonly type: "object";
+                                        readonly required: readonly ["severity"];
+                                    };
                                 };
-                                readonly override: {
-                                    readonly type: "boolean";
+                            };
+                        }, {
+                            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 required: readonly ["id", "category", "description", "check"];
-                            readonly additionalProperties: false;
                         }, {
-                            readonly type: "object";
-                            readonly properties: {
-                                readonly $ref: {
-                                    readonly type: "string";
-                                    readonly minLength: 1;
+                            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"];
                                 };
                             };
-                            readonly required: readonly ["$ref"];
-                            readonly additionalProperties: false;
                         }];
                     };
                 };
@@ -528,11 +1296,12 @@ export declare const DIALECT_META_SCHEMA: {
     };
 };
 export type MetadataContract = FromSchema<typeof METADATA_SCHEMA>;
+export type MetadataContractHierarchy = FromSchema<typeof HIERARCHY_SCHEMA>;
 export type MetadataContractHierarchyLevel = FromSchema<typeof HIERARCHY_LEVEL_SCHEMA>;
 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 RuleRef = FromSchema<typeof RULE_REF_SCHEMA>;
-export type RuleEntry = Rule | RuleRef;
+export type RuleSemantic = FromSchema<typeof SEMANTIC_SCHEMA>;
+export type MetadataRef = FromSchema<typeof REF_SCHEMA>;
 export {};