@astrale-os/kernel-dsl 1.0.0-beta.12 → 1.0.0-beta.14

package/dist/v1/language/policy/analysis/typing.js

@@ -0,0 +1,338 @@
+import { Key } from '../../../addressing/index.js';
+import { definitionRefIndex } from '../../../addressing/ordering.js';
+import { branchesOf, branchProduct, capBranches, targetMode, termKey, UnionFind, } from './branches.js';
+import { MAX_REPEAT } from './budgets.js';
+import { admittedCheckClasses } from './checks.js';
+export class PolicyTyping {
+    scope;
+    // Expanded branches of each named Policy, cached by node identity. A Policy's expansion is reused
+    // across every composition path that reaches it (and across every use site and object contract,
+    // none of which the expansion depends on), so a shared-child composition DAG is expanded in work
+    // linear in the number of Policies instead of enumerating every path. The expansion result is
+    // independent of the reaching path up to the opaque term-namespace labels, which only ever
+    // disambiguate variables within one branch and leave targetMode and branch typing unchanged.
+    // Two occurrences of one Policy in a branch share labels only when a Policy reaches it by two
+    // paths; for that to merge distinct variables, the Policy expands deeper than MAX_PATTERN_DEPTH.
+    #expansions = new Map();
+    constructor(scope) {
+        this.scope = scope;
+    }
+    /** The normalized branches of a named Policy, `undefined` when it does not expand. */
+    expandedBranches(name, namespace) {
+        return this.#expandedBranches(name, new Set(), namespace);
+    }
+    policyAccepts(name, object) {
+        return this.#policyBranchTyping(name, object)?.every(Boolean) ?? false;
+    }
+    /** Whether the Policy accepts every concrete source and target pair the Edge Class accepts. */
+    policyAcceptsEdgeClass(name, declaration) {
+        const endpoints = declaration.orientation === 'directed'
+            ? [declaration.endpoints.source, declaration.endpoints.target]
+            : declaration.endpoints;
+        const sources = this.#concreteEndpointClasses(endpoints[0].accepts);
+        const targets = this.#concreteEndpointClasses(endpoints[1].accepts);
+        return sources.every((source) => targets.every((target) => this.#policyAcceptsEdge(name, { kind: 'exact', ref: source }, { kind: 'exact', ref: target })));
+    }
+    /**
+     * How a check of the Policy types against each contract of its object, `undefined` when the
+     * Policy does not expand or one of its branches is typed for no contract.
+     */
+    checkLeafClasses(name, contracts) {
+        const typings = new Map(contracts.map((contract) => [
+            contract.kind === 'exact' ? Key.of(contract.ref) : 'default',
+            this.#policyBranchTyping(name, contract),
+        ]));
+        const admitted = admittedCheckClasses(typings);
+        return admitted === undefined ? undefined : { accepted: [...typings.keys()], admitted };
+    }
+    endpointsOverlap(left, right) {
+        const seed = [{ kind: 'open', requirements: [] }];
+        const afterLeft = this.#applyEndpoint(seed, left);
+        return this.#applyEndpoint(afterLeft, right).length > 0;
+    }
+    branchIsTyped(branch, use) {
+        if (targetMode(branch) !== use.kind)
+            return false;
+        const alternatives = edgeAlternatives(branch.edges, this);
+        return alternatives.some((variants) => this.#constraintsAreSatisfiable(branch, variants, use));
+    }
+    /** Whether each normalized branch of the Policy is typed for an object of this contract. */
+    #policyBranchTyping(name, object) {
+        const branches = this.#expandedBranches(name, new Set(), `$use:${name}`);
+        const use = { kind: 'object', object };
+        return branches?.map((branch) => this.branchIsTyped(branch, use));
+    }
+    #policyAcceptsEdge(name, source, target) {
+        const branches = this.#expandedBranches(name, new Set(), `$edge-use:${name}`);
+        const use = { kind: 'edge', source, target };
+        return branches !== undefined && branches.every((branch) => this.branchIsTyped(branch, use));
+    }
+    #concreteEndpointClasses(accepts) {
+        return this.scope.concreteNodeClasses.filter((candidate) => this.#classSatisfiesEndpoint(candidate, accepts));
+    }
+    #expandedBranches(name, visiting, namespace) {
+        if (visiting.has(name))
+            return undefined;
+        const cached = this.#expansions.get(name);
+        if (cached !== undefined || this.#expansions.has(name))
+            return cached;
+        const expanded = this.#expandDeclaration(name, visiting, namespace);
+        this.#expansions.set(name, expanded);
+        return expanded;
+    }
+    #expandDeclaration(name, visiting, namespace) {
+        const declaration = this.scope.normalized.get(name);
+        if (declaration === undefined)
+            return undefined;
+        if ('match' in declaration)
+            return branchesOf(declaration.match, namespace);
+        const nested = new Set(visiting);
+        nested.add(name);
+        const refs = 'allOf' in declaration ? declaration.allOf : declaration.anyOf;
+        const children = [];
+        for (const [index, ref] of refs.entries()) {
+            if (!this.scope.isLocalPolicy(ref))
+                return undefined;
+            const expanded = this.#expandedBranches(ref.name, nested, `${namespace}/${index}:${ref.name}`);
+            if (expanded === undefined)
+                return undefined;
+            children.push(expanded);
+        }
+        return 'allOf' in declaration ? branchProduct(children) : capBranches(children.flat());
+    }
+    #constraintsAreSatisfiable(branch, variants, use) {
+        const terms = new Set(use.kind === 'object' ? ['subject', 'object'] : ['subject', 'source', 'target']);
+        for (const key of branch.variables.keys())
+            terms.add(key);
+        for (const key of branch.terms.keys())
+            terms.add(key);
+        for (const edge of branch.edges) {
+            terms.add(termKey(edge.pattern.source, edge.namespace));
+            terms.add(termKey(edge.pattern.target, edge.namespace));
+        }
+        const union = new UnionFind(terms);
+        for (const [left, right] of branch.equalities)
+            union.join(left, right);
+        for (const variant of variants) {
+            for (const [left, right] of variant.equalities)
+                union.join(left, right);
+        }
+        const constraints = new Map();
+        for (const variant of variants) {
+            for (const [term, accepts] of variant.constraints) {
+                const root = union.find(term);
+                const values = constraints.get(root) ?? [];
+                values.push(accepts);
+                constraints.set(root, values);
+            }
+        }
+        const groups = new Map();
+        for (const term of terms) {
+            const root = union.find(term);
+            const members = groups.get(root) ?? [];
+            members.push(term);
+            groups.set(root, members);
+        }
+        for (const [root, members] of groups) {
+            const endpointConstraints = constraints.get(root) ?? [];
+            let candidates = [{ kind: 'open', requirements: [] }];
+            for (const member of members) {
+                candidates = this.#applyInitial(candidates, member, branch, use);
+                if (candidates.length === 0)
+                    return false;
+            }
+            for (const endpoint of endpointConstraints) {
+                candidates = this.#applyEndpoint(candidates, endpoint);
+                if (candidates.length === 0)
+                    return false;
+            }
+        }
+        return true;
+    }
+    #applyInitial(candidates, term, branch, use) {
+        if (term === 'subject')
+            return this.#applyAnyNodeClass(candidates);
+        const contract = targetContract(term, use);
+        if (contract !== undefined) {
+            if (contract.kind === 'exact')
+                return this.#applyExact(candidates, contract.ref);
+            if (contract.kind === 'default') {
+                return uniqueCandidates(this.scope.allNodeClasses.flatMap((ref) => this.#applyExact(candidates, ref)));
+            }
+            return candidates;
+        }
+        const referenced = branch.terms.get(term);
+        if (referenced?.kind === 'ref') {
+            const contract = this.scope.referenceContract(referenced.ref);
+            return contract?.kind === 'exact' ? this.#applyExact(candidates, contract.ref) : [];
+        }
+        const selector = branch.variables.get(term);
+        if (selector === undefined)
+            return [];
+        if (selector.kind === 'exact')
+            return this.#applyExact(candidates, selector.class);
+        if (selector.kind === 'any')
+            return candidates;
+        return this.#applyRequirement(candidates, selector.class);
+    }
+    #applyExact(candidates, exact) {
+        const result = [];
+        for (const candidate of candidates) {
+            if (candidate.kind === 'exact') {
+                if (definitionRefIndex(candidate.ref) === definitionRefIndex(exact))
+                    result.push(candidate);
+            }
+            else if (candidate.requirements.every((required) => this.scope.classExtends(exact, required))) {
+                result.push({ kind: 'exact', ref: exact });
+            }
+        }
+        return uniqueCandidates(result);
+    }
+    #applyAnyNodeClass(candidates) {
+        return uniqueCandidates(candidates.flatMap((candidate) => candidate.kind === 'exact'
+            ? [candidate]
+            : this.scope.allNodeClasses
+                .filter((ref) => candidate.requirements.every((required) => this.scope.classExtends(ref, required)))
+                .map((ref) => ({ kind: 'exact', ref }))));
+    }
+    #applyRequirement(candidates, required) {
+        const result = [];
+        for (const candidate of candidates) {
+            if (candidate.kind === 'exact') {
+                if (this.scope.classExtends(candidate.ref, required))
+                    result.push(candidate);
+            }
+            else {
+                result.push({
+                    kind: 'open',
+                    requirements: uniqueClasses([...candidate.requirements, required]),
+                });
+            }
+        }
+        return uniqueCandidates(result);
+    }
+    #applyEndpoint(candidates, accepts) {
+        const result = [];
+        for (const candidate of candidates) {
+            if (candidate.kind === 'exact') {
+                if (this.#classSatisfiesEndpoint(candidate.ref, accepts))
+                    result.push(candidate);
+                continue;
+            }
+            for (const accept of accepts) {
+                result.push({
+                    kind: 'open',
+                    requirements: uniqueClasses([...candidate.requirements, accept]),
+                });
+            }
+        }
+        return uniqueCandidates(result);
+    }
+    #classSatisfiesEndpoint(candidate, accepts) {
+        return accepts.some((accept) => this.scope.classExtends(candidate, accept));
+    }
+}
+function targetContract(term, use) {
+    if (use.kind === 'object')
+        return term === 'object' ? use.object : undefined;
+    if (term === 'source')
+        return use.source;
+    if (term === 'target')
+        return use.target;
+    return undefined;
+}
+function edgeAlternatives(edges, typing) {
+    let result = [[]];
+    for (const edge of edges) {
+        const variants = variantsForEdge(edge, typing);
+        if (variants.length === 0)
+            return [];
+        const next = [];
+        for (const prefix of result) {
+            for (const variant of variants)
+                next.push([...prefix, variant]);
+        }
+        result = next;
+    }
+    return result;
+}
+function variantsForEdge(use, typing) {
+    const edge = use.pattern;
+    const declaration = typing.scope.edgeDeclaration(edge.class);
+    if (declaration === undefined)
+        return [];
+    const endpoints = declaration.orientation === 'directed'
+        ? [declaration.endpoints.source, declaration.endpoints.target]
+        : declaration.endpoints;
+    const bounds = edge.repeat ?? { min: 1, max: 1 };
+    if (!Number.isInteger(bounds.min) ||
+        !Number.isInteger(bounds.max) ||
+        bounds.min < 0 ||
+        bounds.max < bounds.min ||
+        bounds.max > MAX_REPEAT) {
+        return [];
+    }
+    const sourceKey = termKey(edge.source, use.namespace);
+    const targetKey = termKey(edge.target, use.namespace);
+    const variants = [];
+    for (let length = bounds.min; length <= bounds.max; length++) {
+        if (length === 0) {
+            variants.push({ constraints: [], equalities: [[sourceKey, targetKey]] });
+            continue;
+        }
+        const orientationCount = declaration.orientation === 'undirected' ? 2 ** length : 1;
+        for (let mask = 0; mask < orientationCount; mask++) {
+            const orientations = Array.from({ length }, (_, index) => declaration.orientation === 'undirected' && (mask & (1 << index)) !== 0);
+            let transitionsValid = true;
+            for (let index = 0; index + 1 < length; index++) {
+                const incoming = endEndpoint(endpoints, orientations[index] ?? false);
+                const outgoing = startEndpoint(endpoints, orientations[index + 1] ?? false);
+                if (!typing.endpointsOverlap(incoming.accepts, outgoing.accepts)) {
+                    transitionsValid = false;
+                    break;
+                }
+            }
+            if (!transitionsValid)
+                continue;
+            const first = startEndpoint(endpoints, orientations[0] ?? false);
+            const last = endEndpoint(endpoints, orientations[length - 1] ?? false);
+            variants.push({
+                constraints: [
+                    [sourceKey, first.accepts],
+                    [targetKey, last.accepts],
+                ],
+                equalities: [],
+            });
+        }
+    }
+    return uniqueEdgeVariants(variants);
+}
+function startEndpoint(endpoints, reversed) {
+    return reversed ? endpoints[1] : endpoints[0];
+}
+function endEndpoint(endpoints, reversed) {
+    return reversed ? endpoints[0] : endpoints[1];
+}
+function uniqueEdgeVariants(values) {
+    const result = new Map();
+    for (const value of values) {
+        const key = `${value.constraints
+            .map(([term, accepts]) => `${term}:${accepts.map(definitionRefIndex).sort().join(',')}`)
+            .join('|')}=${value.equalities.map(([left, right]) => `${left}:${right}`).join('|')}`;
+        result.set(key, value);
+    }
+    return [...result.values()];
+}
+function uniqueCandidates(values) {
+    const result = new Map();
+    for (const value of values) {
+        const key = value.kind === 'exact'
+            ? `exact:${definitionRefIndex(value.ref)}`
+            : `open:${value.requirements.map(definitionRefIndex).sort().join('|')}`;
+        result.set(key, value);
+    }
+    return [...result.values()];
+}
+function uniqueClasses(values) {
+    return [...new Map(values.map((value) => [definitionRefIndex(value), value])).values()];
+}

package/dist/v1/language/policy/model/policy.d.ts

@@ -65,20 +65,20 @@ export interface PolicyEdgePattern {
 }
 export type PolicyPatternExpression = PolicyEdgePattern | PolicySameNode<PolicyPatternTerm> | {
     readonly exists: {
-        readonly nodes: readonly PolicyVariable[];
+        readonly nodes: readonly [PolicyVariable, ...PolicyVariable[]];
         readonly where: PolicyPatternExpression;
     };
 } | {
-    readonly allOf: readonly PolicyPatternExpression[];
+    readonly allOf: readonly [PolicyPatternExpression, ...PolicyPatternExpression[]];
 } | {
-    readonly anyOf: readonly PolicyPatternExpression[];
+    readonly anyOf: readonly [PolicyPatternExpression, ...PolicyPatternExpression[]];
 };
 export type PolicyExpression = {
     readonly match: PolicyPatternExpression;
 } | {
-    readonly allOf: readonly PolicyRef[];
+    readonly allOf: readonly [PolicyRef, ...PolicyRef[]];
 } | {
-    readonly anyOf: readonly PolicyRef[];
+    readonly anyOf: readonly [PolicyRef, ...PolicyRef[]];
 };
 export interface PolicyDefinition extends DefinitionBase<PolicyRef> {
     readonly expression: PolicyExpression;

package/dist/v1/language/policy/normalization/normalize.js

@@ -6,9 +6,9 @@ export function normalizePolicyExpression(value) {
         return { match: normalizePolicyPattern(value.match) };
     }
     if ('allOf' in value) {
-        return { allOf: uniqueRefs(value.allOf) };
+        return { allOf: operands(uniqueRefs(value.allOf)) };
     }
-    return { anyOf: uniqueRefs(value.anyOf) };
+    return { anyOf: operands(uniqueRefs(value.anyOf)) };
 }
 /**
  * Passes after the first, while one still changes the Pattern. A pass numbers variables by the
@@ -66,8 +66,7 @@ function unwrapSingleOperands(value) {
     }));
     if (children.length === 1)
         return children[0];
-    const operands = policyCheckComposition(children);
-    return all ? { allOf: operands } : { anyOf: operands };
+    return all ? { allOf: operands(children) } : { anyOf: operands(children) };
 }
 export function normalizePolicyChecks(value) {
     if ('check' in value)
@@ -79,17 +78,19 @@ export function normalizePolicyChecks(value) {
             const normalized = normalizePolicyChecks(child);
             return 'allOf' in normalized ? normalized.allOf : [normalized];
         });
-        return { allOf: policyCheckComposition(uniqueJson(children)) };
+        return { allOf: operands(uniqueJson(children)) };
     }
     const children = value.anyOf.flatMap((child) => {
         const normalized = normalizePolicyChecks(child);
         return 'anyOf' in normalized ? normalized.anyOf : [normalized];
     });
-    return { anyOf: policyCheckComposition(uniqueJson(children)) };
+    return { anyOf: operands(uniqueJson(children)) };
 }
-function policyCheckComposition(values) {
-    // Structural routing may carry an invalid empty array into semantic validation;
-    // validateChecks reports it before the DomainSchema can be accepted.
+/**
+ * The operands of a non-empty list, mapped, flattened, deduplicated or sorted one by one: still at
+ * least one. The structure and compiled admission refuse an empty list.
+ */
+function operands(values) {
     return values;
 }
 function normalizePatternNode(value) {
@@ -106,7 +107,7 @@ function normalizePatternNode(value) {
     if ('exists' in value) {
         return {
             exists: {
-                nodes: [...value.exists.nodes].sort((left, right) => left.variable.id - right.variable.id),
+                nodes: operands([...value.exists.nodes].sort((left, right) => left.variable.id - right.variable.id)),
                 where: normalizePatternNode(value.exists.where),
             },
         };
@@ -116,13 +117,13 @@ function normalizePatternNode(value) {
             const normalized = normalizePatternNode(child);
             return 'allOf' in normalized ? normalized.allOf : [normalized];
         });
-        return { allOf: uniqueJson(children) };
+        return { allOf: operands(uniqueJson(children)) };
     }
     const children = value.anyOf.flatMap((child) => {
         const normalized = normalizePatternNode(child);
         return 'anyOf' in normalized ? normalized.anyOf : [normalized];
     });
-    return { anyOf: uniqueJson(children) };
+    return { anyOf: operands(uniqueJson(children)) };
 }
 function canonicalVariableIds(value) {
     const declarations = new Map();
@@ -297,7 +298,7 @@ function rewriteVariables(value, ids) {
     if ('exists' in value) {
         return {
             exists: {
-                nodes: value.exists.nodes.map((node) => {
+                nodes: operands(value.exists.nodes.map((node) => {
                     const variable = {
                         kind: 'variable',
                         id: ids.get(node.variable.id) ?? node.variable.id,
@@ -305,14 +306,14 @@ function rewriteVariables(value, ids) {
                     return 'class' in node
                         ? { variable, class: node.class }
                         : { variable, selector: node.selector };
-                }),
+                })),
                 where: rewriteVariables(value.exists.where, ids),
             },
         };
     }
     if ('allOf' in value)
-        return { allOf: value.allOf.map((child) => rewriteVariables(child, ids)) };
-    return { anyOf: value.anyOf.map((child) => rewriteVariables(child, ids)) };
+        return { allOf: operands(value.allOf.map((child) => rewriteVariables(child, ids))) };
+    return { anyOf: operands(value.anyOf.map((child) => rewriteVariables(child, ids))) };
 }
 function selectorSignature(node) {
     const selector = policyVariableSelector(node);

package/dist/v1/language/validation/diagnostic.d.ts

@@ -1,4 +1,4 @@
-export type DiagnosticCode = 'CALLABLE_INPUT_FIELD_UNKNOWN' | 'DOMAIN_CLASS_ABSTRACT' | 'DOMAIN_PROPERTY_INPUT_INVALID' | 'DOMAIN_PROPERTY_REQUIRED' | 'DOMAIN_PROPERTY_UNKNOWN' | 'DOMAIN_VALIDATION_TARGET_UNKNOWN' | 'VALUE_SCHEMA_INSTANCE_INVALID' | 'VS_DIALECT' | 'VS_DYNAMIC_FORBIDDEN' | 'VS_KEYWORD_CLOSED' | 'VS_META_SCHEMA' | 'VS_NUMBER_DOMAIN' | 'VS_PATH_EXTENSION' | 'VS_RECURSION_PRODUCTIVE' | 'VS_REFERENCE_FORM' | 'VS_REFERENCE_RESOLUTION' | 'VS_REGEX_PORTABLE' | 'VS_RESOURCE_ID' | 'VS_VALUE_KIND' | 'VS_VALUE_KIND_JSON';
+export type DiagnosticCode = 'CALLABLE_INPUT_FIELD_UNKNOWN' | 'DOMAIN_CLASS_ABSTRACT' | 'DOMAIN_PROPERTY_INPUT_INVALID' | 'DOMAIN_PROPERTY_REQUIRED' | 'DOMAIN_PROPERTY_UNKNOWN' | 'VALUE_SCHEMA_INSTANCE_INVALID' | 'VS_DIALECT' | 'VS_DYNAMIC_FORBIDDEN' | 'VS_KEYWORD_CLOSED' | 'VS_META_SCHEMA' | 'VS_NUMBER_DOMAIN' | 'VS_PATH_EXTENSION' | 'VS_RECURSION_PRODUCTIVE' | 'VS_REFERENCE_FORM' | 'VS_REFERENCE_RESOLUTION' | 'VS_REGEX_PORTABLE' | 'VS_RESOURCE_ID' | 'VS_VALUE_KIND' | 'VS_VALUE_KIND_JSON';
 export interface Diagnostic<out Code extends DiagnosticCode = DiagnosticCode> {
     readonly code: Code;
     readonly pointer: string;
@@ -6,3 +6,17 @@ export interface Diagnostic<out Code extends DiagnosticCode = DiagnosticCode> {
     readonly ref?: string;
 }
 export declare function diagnostic<const Code extends DiagnosticCode>(code: Code, pointer: string, message: string, ref?: string): Diagnostic<Code>;
+/** The fields every diagnostic family shares. */
+interface DiagnosticFields {
+    readonly code: string;
+    readonly pointer: string;
+    readonly message: string;
+    readonly ref?: string;
+}
+/** Order diagnostics by pointer, then code, then message. */
+export declare function orderDiagnostics<Value extends DiagnosticFields>(diagnostics: readonly Value[]): Value[];
+/** Keep one of each pointer, code, ref and message, then order them. */
+export declare function orderAndDeduplicate<Value extends DiagnosticFields>(diagnostics: readonly Value[]): Value[];
+/** One line per diagnostic: its pointer (`/` for the root), its code and its message. */
+export declare function formatDiagnostics(diagnostics: readonly DiagnosticFields[]): string;
+export {};

package/dist/v1/language/validation/diagnostic.js

@@ -1,3 +1,24 @@
+import { compareUnicode } from '../../addressing/ordering.js';
 export function diagnostic(code, pointer, message, ref) {
     return Object.freeze({ code, pointer, message, ...(ref === undefined ? {} : { ref }) });
 }
+/** Order diagnostics by pointer, then code, then message. */
+export function orderDiagnostics(diagnostics) {
+    return [...diagnostics].sort((left, right) => compareUnicode(left.pointer, right.pointer) ||
+        compareUnicode(left.code, right.code) ||
+        compareUnicode(left.message, right.message));
+}
+/** Keep one of each pointer, code, ref and message, then order them. */
+export function orderAndDeduplicate(diagnostics) {
+    const unique = new Map();
+    for (const value of diagnostics) {
+        unique.set(`${value.pointer}\u0000${value.code}\u0000${value.ref ?? ''}\u0000${value.message}`, value);
+    }
+    return orderDiagnostics([...unique.values()]);
+}
+/** One line per diagnostic: its pointer (`/` for the root), its code and its message. */
+export function formatDiagnostics(diagnostics) {
+    return diagnostics
+        .map(({ code, pointer, message }) => `${pointer || '/'} [${code}] ${message}`)
+        .join('\n');
+}

package/dist/v1/language/validation/rule.d.ts

@@ -0,0 +1,26 @@
+import type { DiagnosticCode } from './diagnostic.js';
+/**
+ * What a rule reads to decide. `schema`: a value schema alone, with its place in the declaration
+ * that holds it (a Property, a callable input or output). `context`: a value schema and what its
+ * Domain can reach, the Node Classes of the Domain and of its direct dependencies and the exact
+ * dependency closure. `value`: a value, under an accepted schema or a contract of the Domain.
+ * `warning`: a value schema, which the rule reports without refusing it.
+ */
+export type ValueRuleStage = 'schema' | 'context' | 'value' | 'warning';
+/** The rule one value diagnostic code reports. */
+export interface ValueRule {
+    readonly stage: ValueRuleStage;
+    /**
+     * The positions the rule constrains, which its diagnostics point at, relative to the value
+     * schema, the value or the Domain input it checks: JSON Pointer templates in which a `{name}`
+     * token stands for one token of the kind it names and `{/path*}` for any number of tokens.
+     */
+    readonly positions: readonly [string, ...string[]];
+    /** The rule, in one plain sentence. */
+    readonly statement: string;
+}
+/**
+ * Every value diagnostic code with the rule it reports. A code added to the language does not
+ * compile until it is described here.
+ */
+export declare const VALUE_RULES: Readonly<Record<DiagnosticCode, ValueRule>>;

package/dist/v1/language/validation/rule.js

@@ -0,0 +1,116 @@
+/**
+ * Every value diagnostic code with the rule it reports. A code added to the language does not
+ * compile until it is described here.
+ */
+export const VALUE_RULES = frozen({
+    CALLABLE_INPUT_FIELD_UNKNOWN: {
+        stage: 'value',
+        positions: [''],
+        statement: 'An input field validated on its own is a field of the Callable input, which has fields only when it is a closed object.',
+    },
+    DOMAIN_CLASS_ABSTRACT: {
+        stage: 'value',
+        positions: ['/class'],
+        statement: 'Properties are validated for a concrete Class only.',
+    },
+    DOMAIN_PROPERTY_INPUT_INVALID: {
+        stage: 'value',
+        positions: ['/properties'],
+        statement: 'The Properties of a Class are a canonical map of Property keys to portable values.',
+    },
+    DOMAIN_PROPERTY_REQUIRED: {
+        stage: 'value',
+        positions: ['/properties/{key}'],
+        statement: 'Every required Property of the Class has a value.',
+    },
+    DOMAIN_PROPERTY_UNKNOWN: {
+        stage: 'value',
+        positions: ['/properties/{key}'],
+        statement: 'Every Property given a value is a Property of the Class, its own or inherited.',
+    },
+    VALUE_SCHEMA_INSTANCE_INVALID: {
+        stage: 'value',
+        positions: ['{/path*}'],
+        statement: 'A value satisfies its complete value schema.',
+    },
+    VS_DIALECT: {
+        stage: 'schema',
+        positions: ['{/path*}/$schema'],
+        statement: 'A value schema names $schema at its root only, and there names the dialect https://schemas.astrale.ai/dsl/v1/value-schema.',
+    },
+    VS_DYNAMIC_FORBIDDEN: {
+        stage: 'schema',
+        positions: [
+            '{/path*}/$anchor',
+            '{/path*}/$dynamicAnchor',
+            '{/path*}/$dynamicRef',
+            '{/path*}/$vocabulary',
+        ],
+        statement: 'A value schema names none of $anchor, $dynamicAnchor, $dynamicRef and $vocabulary.',
+    },
+    VS_KEYWORD_CLOSED: {
+        stage: 'schema',
+        positions: ['{/path*}/{keyword}'],
+        statement: 'Every keyword of a value schema is one of the closed V1 vocabulary.',
+    },
+    VS_META_SCHEMA: {
+        stage: 'schema',
+        positions: ['{/path*}'],
+        statement: 'A value schema is JSON valid under the meta-schema of the dialect, with fullMatch a string and no two equal values in an enum, at every location.',
+    },
+    VS_NUMBER_DOMAIN: {
+        stage: 'value',
+        positions: ['{/path*}'],
+        statement: 'A value, like a value schema, is portable JSON: its numbers are finite and not negative zero, its strings well formed, and its size within the value limits.',
+    },
+    VS_PATH_EXTENSION: {
+        stage: 'schema',
+        positions: ['{/path*}/x-astrale-path{/path*}', '{/path*}'],
+        statement: 'x-astrale-path annotates only a direct Property of a callable input object, beside exactly the $ref of the graph NodePath schema, and reads target node, cardinality one and a non-empty set of Node Class refs it accepts.',
+    },
+    VS_RECURSION_PRODUCTIVE: {
+        stage: 'schema',
+        positions: ['{/path*}'],
+        statement: 'Every reference cycle of a value schema crosses a keyword that steps into the value: to a member, a member name or an item.',
+    },
+    VS_REFERENCE_FORM: {
+        stage: 'schema',
+        positions: ['{/path*}/$ref'],
+        statement: 'A $ref is a JSON Pointer fragment into its own value schema, or the id of the graph NodePath schema beside x-astrale-path.',
+    },
+    VS_REFERENCE_RESOLUTION: {
+        stage: 'context',
+        positions: [
+            '{/path*}/$ref',
+            '{/path*}/x-astrale-path/accepts/{index}',
+            '',
+            '/registry{/path*}',
+        ],
+        statement: 'A $ref resolves to a location of its own value schema, x-astrale-path accepts Node Classes of the Domain or of a direct dependency, and the schema is checked with the exact dependency closure of its Domain.',
+    },
+    VS_REGEX_PORTABLE: {
+        stage: 'schema',
+        positions: ['{/path*}/pattern', '{/path*}/fullMatch', '{/path*}/patternProperties/{pattern}'],
+        statement: 'Every pattern, fullMatch and patternProperties name is an RFC 9485 I-Regexp within the regular-expression limits.',
+    },
+    VS_RESOURCE_ID: {
+        stage: 'schema',
+        positions: ['{/path*}/$id'],
+        statement: 'A value schema declares no $id: it is embedded, not a resource of its own.',
+    },
+    VS_VALUE_KIND: {
+        stage: 'schema',
+        positions: ['{/path*}/x-astrale-value-kind'],
+        statement: 'x-astrale-value-kind declares instant beside type string at any location, or blob as the whole schema of a Property, exactly as values.blob writes it.',
+    },
+    VS_VALUE_KIND_JSON: {
+        stage: 'warning',
+        positions: ['/classes/{class}/properties/{property}'],
+        statement: 'A Property of value kind json is filtered by equality only, so its author is warned.',
+    },
+});
+function frozen(rules) {
+    for (const rule of Object.values(rules))
+        Object.freeze(Object.freeze(rule).positions);
+    return Object.freeze(rules);
+}