structured-context 0.12.0 → 0.13.0

package/dist/validate.js

@@ -1,10 +1,12 @@
 import { isAbsolute, relative, resolve } from 'node:path';
-import { readSpace } from './read/read-space';
-import { extractEntityInfo } from './schema/schema';
-import { validateGraph } from './schema/validate-graph';
-import { validateRules } from './schema/validate-rules';
-import { createSpaceContext } from './space-context';
-import { buildSpaceGraph } from './space-graph';
+import { readSpace } from './read/read-space.js';
+import { computeHierarchyDepths, evaluateRulesWithGating } from './schema/gating.js';
+import { filterRules } from './schema/rule-filter.js';
+import { extractEntityInfo } from './schema/schema.js';
+import { validateGraph } from './schema/validate-graph.js';
+import { validateRules } from './schema/validate-rules.js';
+import { createSpaceContext } from './space-context.js';
+import { buildSpaceGraph } from './space-graph.js';
 /**
  * Format AJV errors for better readability.
  * Groups related errors and extracts helpful context like allowed values.
@@ -92,73 +94,101 @@ export function formatErrors(errors, schema, schemaRefRegistry, nodeData) {
     }
     return formatted;
 }
+/** One-line text for a rule violation: rule, description, and any evidence and verdict guidance. */
+export function ruleViolationMessage(v) {
+    const evidence = v.evidence ? ` (Evidence: ${v.evidence})` : '';
+    const guidance = v.guidance ? ` Guidance: ${v.guidance}` : '';
+    return `[${v.ruleId}] ${v.description}${evidence}${guidance}`;
+}
+const summariseTrim = (report) => ({
+    nodeCount: report.nodes.size,
+    ruleIds: [...report.ruleIds].sort(),
+});
 /**
- * Run full validation on a space and return a structured result.
- * Does not output to console or call process.exit.
+ * Evaluate a space's rules. With a main hierarchy, evaluation cascades: schema, hierarchy
+ * and gating-rule failures (the `seeds`) suppress rule evaluation for the failing node's subtree.
+ * Called by `validateNodes`, the core behind `validateSpace` and `validateFile`, so both report identical rule results for a node.
+ * Semantic rules run only when a `judge` is supplied.
  */
-export async function validateSpace(context, options = {}) {
+async function evaluateSpaceRules(nodes, metadata, seeds, options = {}) {
+    const rules = metadata.rules && filterRules(metadata.rules, options.ruleFilter);
+    if (!rules)
+        return { violations: [], gates: [] };
+    const provider = options.judge;
+    if (!metadata.hierarchy) {
+        const result = await validateRules(nodes, rules, {
+            judge: provider,
+            judgeTarget: options.judgeTarget,
+            trimReport: options.trimReport,
+        });
+        return { violations: result, gates: [] };
+    }
+    const graph = buildSpaceGraph(nodes, metadata.hierarchy);
+    return evaluateRulesWithGating(nodes, rules, graph, seeds, {
+        includeGated: options.includeGated,
+        provider,
+        judgeTarget: options.judgeTarget,
+        trimReport: options.trimReport,
+    });
+}
+/**
+ * The one validation pipeline: type and schema checks, duplicate titles, reference and hierarchy
+ * checks, cascade-gated rules, and unresolved content links. Returns every entry; `validateSpace`
+ * and `validateFile` are views over it, so a file's results match its entry in a full run.
+ * `judgeTarget` limits judging to one file (and the ancestors that can gate it).
+ */
+async function validateNodes(context, nodes, unresolvedRefs, options = {}) {
     const { schema, schemaRefRegistry, schemaValidator } = context;
     const metadata = schema.metadata;
-    const readResult = options.readResult ?? (await readSpace(context));
-    const { nodes, parseIssues } = readResult;
     // Pre-extract valid types for early type validation
     const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : [];
     const result = {
         validCount: 0,
-        nodeErrorCount: 0,
-        nodeErrors: [],
+        nodeFailures: [],
         refErrors: [],
         duplicateErrors: [],
         ruleViolations: [],
         hierarchyViolations: [],
         orphans: [],
-        parseIssues,
         unresolvedContentLinks: [],
+        coverageGates: [],
+        contextTrimmed: { nodeCount: 0, ruleIds: [] },
     };
     for (const node of nodes) {
         // Early type validation - check before full AJV validation to prevent cascading errors
         const nodeType = node.schemaData.type;
         if (nodeType !== undefined && validTypes.length > 0 && !validTypes.includes(nodeType)) {
-            result.nodeErrorCount++;
-            result.nodeErrors.push({
-                file: node.source?.file ?? node.label,
-                ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
+            const sortedTypes = [...validTypes].sort();
+            result.nodeFailures.push({
+                node,
+                invalidType: { validTypes },
                 errors: [
                     {
                         instancePath: '/type',
                         keyword: 'enum',
-                        message: `Invalid type "${nodeType}". Valid types are: ${validTypes.sort().join(', ')}`,
-                        params: { allowedValues: validTypes },
+                        message: `Invalid type "${nodeType}". Valid types are: ${sortedTypes.join(', ')}`,
+                        params: { allowedValues: sortedTypes },
                         schemaPath: '#/oneOf',
                         data: nodeType,
                     },
                 ],
-                nodeData: node.schemaData,
             });
             continue;
         }
-        const valid = schemaValidator(node.schemaData);
-        if (valid) {
+        if (schemaValidator(node.schemaData)) {
             result.validCount++;
         }
         else {
-            result.nodeErrorCount++;
-            result.nodeErrors.push({
-                file: node.source?.file ?? node.label,
-                ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
-                errors: schemaValidator.errors || [],
-                nodeData: node.schemaData,
-            });
+            result.nodeFailures.push({ node, errors: schemaValidator.errors || [] });
         }
     }
     // Detect duplicate node keys (titles)
     const titleToFiles = new Map();
     for (const node of nodes) {
-        const title = node.title;
-        if (!titleToFiles.has(title)) {
-            titleToFiles.set(title, []);
+        if (!titleToFiles.has(node.title)) {
+            titleToFiles.set(node.title, []);
         }
-        titleToFiles.get(title).push(node.label);
+        titleToFiles.get(node.title).push(node.label);
     }
     for (const [title, files] of titleToFiles) {
         if (files.length > 1) {
@@ -166,16 +196,27 @@ export async function validateSpace(context, options = {}) {
         }
     }
     // Validate all hierarchy constraints (field references and structure)
-    const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
+    const hierarchyValidation = validateGraph(nodes, metadata, unresolvedRefs);
     result.refErrors.push(...hierarchyValidation.refErrors);
     result.hierarchyViolations = [...hierarchyValidation.violations];
     // Calculate orphans across every hierarchy (informational, not a validation error)
     for (const hierarchy of metadata.hierarchies ?? []) {
         result.orphans.push(...buildSpaceGraph(nodes, hierarchy).orphans);
     }
-    // Load and execute rules validation if schema defines rules
+    // Load and execute rules validation if schema defines rules (with cascade gating, see docs/rules.md).
     if (metadata.rules) {
-        result.ruleViolations = await validateRules(nodes, metadata.rules);
+        const seeds = [
+            ...result.nodeFailures.map(({ node }) => {
+                const file = node.source?.file ?? node.label;
+                return { file, title: String(node.schemaData.title ?? file), reason: 'schema' };
+            }),
+            ...result.hierarchyViolations.map((v) => ({ file: v.file, title: v.nodeTitle, reason: 'hierarchy' })),
+        ];
+        const trimReport = { nodes: new Set(), ruleIds: new Set() };
+        const { violations, gates } = await evaluateSpaceRules(nodes, metadata, seeds, { ...options, trimReport });
+        result.ruleViolations = violations;
+        result.coverageGates = gates;
+        result.contextTrimmed = summariseTrim(trimReport);
     }
     // Collect unresolved content links (warnings — not errors)
     const seen = new Set();
@@ -192,8 +233,61 @@ export async function validateSpace(context, options = {}) {
     }
     return result;
 }
+/**
+ * Run full validation on a space and return a structured result.
+ * Does not output to console or call process.exit.
+ */
+export async function validateSpace(context, options = {}) {
+    const metadata = context.schema.metadata;
+    const readResult = options.readResult ?? (await readSpace(context));
+    let nodes = readResult.nodes;
+    // Depth limiting: evaluate only hierarchy nodes within N breadth-first levels from the
+    // top. Non-hierarchy nodes are unaffected — depth scoping only applies to the hierarchy DAG.
+    const skippedByDepth = [];
+    if (options.depth !== undefined && metadata.hierarchy) {
+        const fullGraph = buildSpaceGraph(nodes, metadata.hierarchy);
+        const depths = computeHierarchyDepths(fullGraph);
+        const included = [];
+        for (const node of nodes) {
+            const nodeDepth = depths.get(node.title);
+            if (nodeDepth !== undefined && nodeDepth > options.depth) {
+                skippedByDepth.push({ file: node.label, title: node.title });
+            }
+            else {
+                included.push(node);
+            }
+        }
+        nodes = included;
+    }
+    const result = await validateNodes(context, nodes, readResult.unresolvedRefs, {
+        includeGated: options.includeGated,
+        ruleFilter: options.ruleFilter,
+        judge: options.judge,
+    });
+    return {
+        validCount: result.validCount,
+        nodeErrorCount: result.nodeFailures.length,
+        nodeErrors: result.nodeFailures.map(({ node, errors }) => ({
+            file: node.source?.file ?? node.label,
+            ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
+            errors,
+            nodeData: node.schemaData,
+        })),
+        refErrors: result.refErrors,
+        duplicateErrors: result.duplicateErrors,
+        ruleViolations: result.ruleViolations,
+        hierarchyViolations: result.hierarchyViolations,
+        orphans: result.orphans,
+        parseIssues: readResult.parseIssues,
+        unresolvedContentLinks: result.unresolvedContentLinks,
+        coverageGates: result.coverageGates,
+        contextTrimmed: result.contextTrimmed,
+        skippedByDepth,
+        depthLimit: options.depth,
+    };
+}
 /** Find which space a file belongs to by checking directory containment. */
-function resolveFileSpace(filePath, config) {
+export function resolveFileSpace(filePath, config) {
     const absFile = isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath);
     for (const space of config.spaces) {
         const absSpace = isAbsolute(space.path) ? space.path : resolve(process.cwd(), space.path);
@@ -206,117 +300,112 @@ function resolveFileSpace(filePath, config) {
     return null;
 }
 /**
- * Validate a single file within its space.
- *
- * Reads the full space (required for graph correctness) but filters all reported
- * errors to only those attributable to the target file.
- *
- * Returns a result object — does not output to console or call process.exit.
- * If the file is not in any configured space, returns a result with `inSpace: false`.
+ * Select one file's entries from a space's validation result: issues keyed and formatted, errors split from warnings.
+ * Pure — a file's entries are exactly its slice of the result.
  */
-export async function validateFile(filePath, config, options = {}) {
-    const resolved = resolveFileSpace(filePath, config);
-    if (!resolved) {
-        return {
-            file: filePath,
-            inSpace: false,
-            message: 'File does not belong to any configured space.',
-        };
-    }
-    const { space, label } = resolved;
-    const context = createSpaceContext(space.name, config, { configDir: options.configDir });
-    const { schema, schemaRefRegistry, schemaValidator } = context;
-    const metadata = schema.metadata;
-    const readResult = await readSpace(context);
-    const { nodes } = readResult;
-    // Pre-extract valid types for early type validation
-    const validTypes = Array.isArray(schema.oneOf) ? extractEntityInfo(schema, schemaRefRegistry).map((e) => e.type) : [];
+function issuesForFile(result, label, context, includeGated) {
+    const { schema, schemaRefRegistry } = context;
     const errors = {};
     const warnings = {};
-    // Schema validation errors for this node
-    for (const node of nodes) {
+    for (const { node, errors: ajvErrors, invalidType } of result.nodeFailures) {
         if (node.label !== label)
             continue;
-        // Early type validation - check before full AJV validation to prevent cascading errors
-        const nodeType = node.schemaData.type;
-        if (nodeType !== undefined && validTypes.length > 0 && !validTypes.includes(nodeType)) {
-            errors[`schema:type:${validTypes.join(',')}`] = {
+        const position = {
+            ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
+            ...(node.source?.column !== undefined ? { column: node.source.column } : {}),
+        };
+        if (invalidType) {
+            errors[`schema:type:${invalidType.validTypes.join(',')}`] = {
                 kind: 'schema',
-                message: `Invalid type "${nodeType}". Valid types are: ${validTypes.sort().join(', ')}`,
-                ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
-                ...(node.source?.column !== undefined ? { column: node.source.column } : {}),
+                message: ajvErrors[0].message,
+                ...position,
             };
             continue;
         }
-        const valid = schemaValidator(node.schemaData);
-        if (!valid) {
-            const formatted = formatErrors(schemaValidator.errors ?? [], schema, schemaRefRegistry, node.schemaData);
-            for (const { message, dedupeKey } of formatted) {
-                errors[`schema:${dedupeKey}`] = {
-                    kind: 'schema',
-                    message,
-                    ...(node.source?.line !== undefined ? { line: node.source.line } : {}),
-                    ...(node.source?.column !== undefined ? { column: node.source.column } : {}),
-                };
-            }
+        const formatted = formatErrors(ajvErrors, schema, schemaRefRegistry, node.schemaData);
+        for (const { message, dedupeKey } of formatted) {
+            errors[`schema:${dedupeKey}`] = { kind: 'schema', message, ...position };
         }
     }
     // Duplicate key errors — include if this file is one of the duplicates
-    const titleToFiles = new Map();
-    for (const node of nodes) {
-        if (!titleToFiles.has(node.title))
-            titleToFiles.set(node.title, []);
-        titleToFiles.get(node.title).push(node.label);
-    }
-    for (const [title, files] of titleToFiles) {
-        if (files.length > 1 && files.includes(label)) {
-            const others = files.filter((f) => f !== label);
-            errors[`duplicate:${title}`] = {
-                kind: 'duplicate',
-                message: `Duplicate title "${title}" also exists in: ${others.join(', ')}`,
-            };
-        }
+    for (const { title, files } of result.duplicateErrors) {
+        if (!files.includes(label))
+            continue;
+        const others = files.filter((f) => f !== label);
+        errors[`duplicate:${title}`] = {
+            kind: 'duplicate',
+            message: `Duplicate title "${title}" also exists in: ${others.join(', ')}`,
+        };
     }
     // Broken links and hierarchy violations from this file
-    const hierarchyValidation = validateGraph(nodes, metadata, readResult.unresolvedRefs);
-    for (const { file, parent, error } of hierarchyValidation.refErrors) {
+    for (const { file, parent, error } of result.refErrors) {
         if (file === label) {
             errors[`broken-link:${parent}`] = { kind: 'broken-link', message: `${parent} → ${error}` };
         }
     }
-    for (const v of hierarchyValidation.violations) {
+    for (const v of result.hierarchyViolations) {
         if (v.file === label) {
             errors[`hierarchy:${v.description}`] = { kind: 'hierarchy', message: v.description };
         }
     }
-    // Rule violations for this node — only error severity counts as an error
-    if (metadata.rules) {
-        const ruleViolations = await validateRules(nodes, metadata.rules);
-        for (const v of ruleViolations) {
-            if (v.file === label) {
-                const target = v.severity === 'error' ? errors : warnings;
-                target[`rule:${v.ruleId}`] = { kind: 'rule', message: `[${v.ruleId}] ${v.description}`, severity: v.severity };
-            }
+    // Rule violations — only error severity counts as an error.
+    for (const v of result.ruleViolations) {
+        if (v.file === label) {
+            const target = v.severity === 'error' ? errors : warnings;
+            target[`rule:${v.ruleId}`] = {
+                kind: 'rule',
+                message: ruleViolationMessage(v),
+                severity: v.severity,
+            };
         }
     }
-    // Unresolved content links for this node (warnings — do not affect errorCount)
-    const targetNode = nodes.find((n) => n.label === label);
-    if (targetNode) {
-        const seen = new Set();
-        for (const link of targetNode.resolvedLinks) {
-            if (link.location === 'internal' && !seen.has(link.target)) {
-                seen.add(link.target);
-                warnings[`content-link:${link.target}`] = {
-                    kind: 'content-link',
-                    message: `Unresolved content link: ${link.target}`,
-                };
-            }
+    // A gated file with no violations would otherwise look clean — say that its rules were not checked.
+    for (const gate of result.coverageGates) {
+        if (!gate.gatedFiles.includes(label))
+            continue;
+        const cause = gate.reason === 'rule' ? `blocking rule "${gate.ruleId}"` : `${gate.reason} failure`;
+        warnings[`gated:${gate.file}`] = {
+            kind: 'gated',
+            message: `Rule checks ${includeGated ? 'evaluated anyway' : 'not evaluated'}: gated by ${cause} on ${gate.file}`,
+            severity: 'info',
+        };
+    }
+    // Unresolved content links (warnings — do not affect errorCount)
+    for (const link of result.unresolvedContentLinks) {
+        if (link.file === label) {
+            warnings[`content-link:${link.target}`] = {
+                kind: 'content-link',
+                message: `Unresolved content link: ${link.target}`,
+            };
         }
     }
+    return { errors, warnings };
+}
+/** The result for a file that belongs to no configured space. */
+export function fileNotInSpace(filePath) {
+    return {
+        file: filePath,
+        inSpace: false,
+        message: 'File does not belong to any configured space.',
+    };
+}
+/**
+ * Validate a file in an already-resolved space. Checks the whole space (required for graph
+ * correctness), judging only the file, then selects the file's issues from the result.
+ */
+export async function validateResolvedFile(filePath, label, context, options = {}) {
+    const readResult = await readSpace(context);
+    const result = await validateNodes(context, readResult.nodes, readResult.unresolvedRefs, {
+        includeGated: options.includeGated,
+        ruleFilter: options.ruleFilter,
+        judge: options.judge,
+        judgeTarget: label,
+    });
+    const { errors, warnings } = issuesForFile(result, label, context, options.includeGated);
     return {
         file: isAbsolute(filePath) ? filePath : resolve(process.cwd(), filePath),
         label,
-        space: space.name,
+        space: context.space.name,
         errors,
         errorCount: Object.keys(errors).length,
         warnings,
@@ -324,3 +413,19 @@ export async function validateFile(filePath, config, options = {}) {
         inSpace: true,
     };
 }
+/**
+ * Validate a single file within its space.
+ *
+ * Reads the full space (required for graph correctness) but filters all reported
+ * errors to only those attributable to the target file.
+ *
+ * Returns a result object — does not output to console or call process.exit.
+ * If the file is not in any configured space, returns a result with `inSpace: false`.
+ */
+export async function validateFile(filePath, config, options = {}) {
+    const resolved = resolveFileSpace(filePath, config);
+    if (!resolved)
+        return fileNotInSpace(filePath);
+    const context = createSpaceContext(resolved.space.name, config, { configDir: options.configDir });
+    return validateResolvedFile(filePath, resolved.label, context, options);
+}

package/docs/concepts.md

@@ -1,4 +1,8 @@
-# Structured Context: Concepts and Terminology
+---
+title: "Concepts and Terminology"
+---
+
+# Concepts and Terminology
 
 This document is the canonical reference for concepts and terminology used in this project. It focuses on the meta-concepts the project supports, not the content of specific frameworks modelled in schemas. Before naming things in code, tests, comments, or documentation, check definitions here for consistency, and update them here when the project's "world view" changes, avoiding blurry terms as much as possible.
 
@@ -47,7 +51,7 @@ Each `.md` file with a `type` frontmatter field is a **typed page** — it repre
 
 - **Heading with `[type:: x]`** or **anchor-implied type** (e.g. `## My Goal ^goal1`) → becomes a child node.
 - **Relationship headings** (e.g. `### Assumptions`) → when matched to a relationship definition in the schema, signals that following content (list items or table rows) should be typed as that relationship's child type, without requiring explicit inline annotations.
-- **Untyped headings** → update the depth stack for parent resolution but do not become nodes.
+- **Untyped headings** → update the depth stack for parent resolution but do not become nodes. They stay in the content of the node whose section contains them; see [Node content](#node-content).
 - **Typed bullet items** (`- [type:: solution] Title`) → become child nodes at any nesting depth.
 - **Table rows** under a relationship heading → become child nodes of the relationship type.
 - **YAML blocks** and **unbracketed `key:: value` paragraph fields** → merged into the current node's `schemaData`.
@@ -83,7 +87,7 @@ Key properties:
 
 #### Preamble
 
-**Preamble** is content in a `space on a page` document that appears before the first heading. It is parsed but discarded — not associated with any node.
+**Preamble** is content in a `space on a page` document that appears before the first heading. It is parsed but discarded — not associated with any node, and not part of any node's `content`.
 
 ---
 
@@ -95,6 +99,8 @@ Node types are defined by the schema in use and may vary across schemas. Example
 
 Each node retains its physical `source` location (`file`, and `line` / `column` where available) so that validation diagnostics, edge errors, and downstream tooling pinpoint the exact location in the vault.
 
+A node's `content` is the markdown source of its body; see [Node content](#node-content).
+
 > `space_on_a_page` and `dashboard` are not `space node` types — they are `tooling types`.
 
 ### Embedded node
@@ -103,6 +109,20 @@ An **embedded node** is a `space node` defined *within* a containing document ra
 
 A `typed page` may contain embedded nodes in its body. Those nodes become full members of the parsed node set, with `parent references` wired to their containing page or enclosing heading.
 
+### Node content
+
+A node's `content` is the markdown of its body, copied unchanged from the file: blank lines, list looseness, line endings and code fences all stay as written. The content of a list item node is dedented by the item's content indent, so it reads as markdown on its own. Leading blank lines and trailing whitespace are trimmed.
+
+A node owns the source from its heading or list item up to the next heading that ends its section, with these parts removed:
+
+- Its own heading line or list marker text.
+- The sections of nested embedded nodes.
+- Field syntax that supplies data: frontmatter and other YAML blocks, and lines that hold only `key:: value` or `[key:: value]` fields. A field written inside a sentence stays in the prose, and its value is still read as a field.
+
+An untyped heading belongs to the content of the node whose section contains it. An untyped heading at the same level as an embedded node's heading, or at a higher level (fewer `#`), ends that node's section, so the heading and what follows it go to the enclosing node, or to the page. An untyped heading at a deeper level stays inside the section. Inline fields below an untyped heading are assigned the same way.
+
+In a `space_on_a_page` file, content before the first heading (the preamble) is not assigned to any node.
+
 ### Type alias
 
 A **type alias** is an alternative name accepted in the `type` field for a given `space node` type. Aliases allow teams to use their own vocabulary while still receiving schema validation. For example, a schema might accept `outcome` as an alias for `goal`.
@@ -113,7 +133,7 @@ A `space node`'s resolved type (`resolvedType`) is its canonical type after alia
 
 ## Typed page
 
-A **typed page** is a markdown file whose frontmatter declares a `space node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`. Body content appearing before any embedded headings (or the entire body when no embedded headings are present) is preserved as the page node's `content`.
+A **typed page** is a markdown file whose frontmatter declares a `space node` type (e.g. `type: goal`). The file itself represents one node, and its body may additionally contain `embedded nodes`. The page node's `content` is the body markdown outside any embedded node (the entire body when there are none).
 
 Typed pages are distinct from `space on a page` files: a typed page *is* a `space node`; a `space_on_a_page` file is merely a container.
 
@@ -143,10 +163,34 @@ Rules may be:
 
 Rules are distinct from schema validation: the schema checks structure; rules check meaning and quality.
 
+A rule's `when` is its **applicability condition**: a test that decides whether the rule applies to a node. Its `expression` is the test the node must pass.
+
 Each executable rule has a **category** (`validation`, `coherence`, `workflow`, `best-practice`) that supplies its default **severity** (`error`, `warning`, `info`). A rule may override its category's severity, but categories are the preferred grouping. Only `error` severity violations fail validation.
 
 See [docs/rules.md](rules.md) for the rules reference, including JSONata expression syntax and the full `$metadata` field reference.
 
+### Semantic rules
+
+A **semantic rule** is a rule with a `semantic` part. It asks a model to evaluate a node, for example whether an opportunity is a customer need. The `semantic` object can carry a `rubric`, `verdicts`, a verdict `severity` map, a `scope` and `includeContent`. A rule can also have an `expression`, a JSONata test that runs before the model.
+
+A **model provider** evaluates semantic rules: a decision model (Jev) or a chat model (Claude, OpenAI-compatible). It is a bundled provider or an entry in `modelProviders`. For each rule, the model gives one **verdict** from the rule's `semantic.verdicts`, for example `customer-need`, `vague` or `solution`. The rule's `semantic.severity` says which verdicts report a violation. Semantic rules cost money, so they are evaluated only when a run asks for it (`--semantic`); a rule's `expression` always runs. See [docs/semantic-rules.md](semantic-rules.md).
+
+The **evaluated node** is the node a semantic rule is judged on. A rule's `semantic.scope` adds **related nodes** (parent, siblings, children, ancestors, descendants, or the whole branch) along the main hierarchy's edges, and `semantic.includeContent` chooses whose body is sent. See [Related nodes and content](semantic-rules.md#related-nodes-and-content).
+
+A **node ruleset group** is the set of nodes that share the same semantic rules. It forms within one evaluation step of [cascade gating](#cascade-gating): one hierarchy depth, or the set of non-hierarchy nodes. Nodes are keyed on the rules left after `when` and `expression` filtering. A model provider on the `openrouter-decisions` or `typesafe-systemone` API evaluates one group in as few decision requests as it can.
+
+A **decision request** is one call to a decisions API. It carries the state of one or more nodes and a list of decision questions.
+
+A **decision question** is one choice question about one node under one semantic rule, inside a decision request.
+
+The **per-node input cap** limits the input for one evaluated node and its related nodes. See [Input size and trimming](semantic-rules.md#input-size-and-trimming).
+
+### Cascade gating
+
+**Cascade gating** is the mechanism by which a schema failure, hierarchy structure violation, or blocking rule violation on a node suppresses rule evaluation for that node's `hierarchy` subtree. It exists so downstream checks — especially costly semantic (model-judged) rules — aren't run against inputs already known to be invalid.
+
+A **coverage gate** records one instance of this: the gating node, what kind of failure triggered it (`schema`, `hierarchy`, or a specific rule `id`), and the set of nodes whose rules were suppressed as a result. `sctx validate` reports coverage gates so both humans and agents can see the validation "edge" — where evaluation stopped and why. See [docs/rules.md](rules.md#cascade-gating) for the full model, including the per-rule `gatesDescendants` field and the `--include-gated` / `--depth` CLI options.
+
 ---
 
 ## Tooling types
@@ -297,7 +341,7 @@ An **anchor** is a block anchor (e.g. `^goal1`) appended to a heading in a `type
 
 ## Filter expressions
 
-A **filter expression** is a string that selects a subset of nodes from a space. Filter expressions are used with the `--filter` flag on the `show` command and in named filter views in config.
+A **filter expression** is a string that selects a subset of nodes from a space. Filter expressions are used with the `--filter` flag on the `show` and `render` commands and in named filter views in config.
 
 ### Syntax
 
@@ -312,7 +356,7 @@ Keywords (`WHERE`, `SELECT`) are case-insensitive.
 
 ### Predicate context
 
-The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression evaluated per node. Node fields (from `schemaData`) are accessible directly — e.g. `resolvedType`, `status`, `title`. Additionally, two pre-computed traversal arrays are available:
+The WHERE predicate is a [JSONata](https://docs.jsonata.org/overview) expression evaluated per node. Node fields (from `schemaData`) are accessible directly — e.g. `resolvedType`, `status`. `label` (relative file path, e.g. `"solutions/My Solution.md"`) and `title` are always available regardless of schema. Additionally, two pre-computed traversal arrays are available:
 
 | Field | Description |
 |-------|-------------|
@@ -328,6 +372,8 @@ Each entry in `ancestors[]` or `descendants[]` includes all schema fields of the
 | `_hierarchy` | `string` | Hierarchy name; present only for hierarchy edges |
 | `_selfRef` | `boolean` | Whether the edge is a same-type (self-referential) link |
 
+Dates and datetimes are the strings written in frontmatter, so compare them with `$toMillis()` rather than as strings (offsets and precision vary), e.g. `WHERE $toMillis(updated) > $toMillis('2026-03-31T00:00:00Z')`. See [Rules: dates and times](rules.md#dates-and-times).
+
 ### SELECT spec
 
 The SELECT clause expands the result set by walking the graph from matched nodes. The spec is a comma-separated list of directives: