@astrale-os/kernel-dsl 1.0.0-beta.2 → 1.0.0-beta.20

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
@@ -40,16 +40,16 @@ function normalizePatternOnce(value) {
     return normalizePatternNode(rewritten);
 }
 /**
- * The one spelling of a Node Class observation rule: normalized Policy checks without a composition
- * of one operand, or the Policy that a lone check of `self` names, which is how a Class has always
- * declared one. Callable checks keep their compositions of one operand: their revisions predate
- * this rule.
+ * The one spelling of a Class rule: normalized Policy checks without a composition of one operand,
+ * or the Policy that a lone check of `self` names, which is how a Class has always declared one.
+ * Callable checks keep their compositions of one operand: their revisions predate this rule. A
+ * create rule checks no `self`, so it keeps its checks.
  */
 export function normalizeClassRule(value) {
     if (!isClassRuleChecks(value))
         return value;
     const checks = unwrapSingleOperands(normalizePolicyChecks(value));
-    return 'check' in checks && checks.object.kind === 'self' ? checks.check : checks;
+    return ('check' in checks && checks.object.kind === 'self' ? checks.check : checks);
 }
 /** Replace each composition of one operand by that operand, merging what it then nests. */
 function unwrapSingleOperands(value) {
@@ -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';
+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,45 @@
+import type { LimitKey } from '../limits.js';
+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 diagnostic code reports, whatever it checks: what `schema.RULES` and `VALUE_RULES`
+ * say of every code, each with the stages of its own checks.
+ */
+export interface DiagnosticRule {
+    /**
+     * The positions the rule constrains, which its diagnostics point at: 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;
+    /** The limits of `schema.limits` the rule enforces, by key, where it enforces some. */
+    readonly limits?: readonly [LimitKey, ...LimitKey[]];
+    /**
+     * The conditions of the published JSON Schema of the document that state the rule, where some
+     * do: the URI fragment of each `if` or `not` subschema whose failure refuses the document with
+     * this rule's code.
+     */
+    readonly conditions?: readonly [string, ...string[]];
+}
+/**
+ * The rule one value diagnostic code reports. Its positions are relative to the value schema, the
+ * value or the Domain input it checks. A condition refuses a value schema of the document with
+ * `DV_VALUE_SCHEMA` and this rule's code as its `valueCode`.
+ */
+export interface ValueRule extends DiagnosticRule {
+    readonly stage: ValueRuleStage;
+}
+/**
+ * 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,109 @@
+import { deepFreeze } from '../freeze.js';
+/**
+ * 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 = deepFreeze({
+    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}', ''],
+        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.',
+        limits: ['regexp.maxCodePoints', 'regexp.maxNesting', 'regexp.maxRepeat', 'regexp.maxStates'],
+    },
+    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.',
+        conditions: ['#/$defs/value-location/anyOf/1/if'],
+    },
+    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.',
+    },
+});

package/dist/v1/language/value/compile/fields.js

@@ -1,3 +1,5 @@
+import { compareCodeUnits } from '../../../addressing/ordering.js';
+import { escapePointerToken } from '../syntax/pointer.js';
 /** Exact field constraints available for independent scalar route validation. */
 export function inputFieldNodes(program) {
     const fields = new Map();
@@ -34,7 +36,7 @@ export function inputFieldNodes(program) {
             Array.isArray(schema.properties))
             return;
         for (const name of Object.keys(schema.properties)) {
-            const child = node.children[`properties/${escapePointer(name)}`];
+            const child = node.children[`properties/${escapePointerToken(name)}`];
             if (child === undefined)
                 throw new TypeError(`Compiled input field ${name} is absent.`);
             const constraints = fields.get(name) ?? new Set();
@@ -46,15 +48,9 @@ export function inputFieldNodes(program) {
     if (!closed || unsupported)
         return undefined;
     return Object.freeze(Object.fromEntries([...fields]
-        .sort(([left], [right]) => compare(left, right))
+        .sort(([left], [right]) => compareCodeUnits(left, right))
         .map(([name, nodes]) => [
         name,
         Object.freeze([...nodes].sort((left, right) => left - right)),
     ])));
 }
-function escapePointer(value) {
-    return value.replaceAll('~', '~0').replaceAll('/', '~1');
-}
-function compare(left, right) {
-    return left < right ? -1 : left > right ? 1 : 0;
-}

package/dist/v1/language/value/evaluate/program.d.ts

@@ -1,3 +1,4 @@
+import type { Options } from '@astrale-os/kernel-dsl/value';
 import type { Diagnostic } from '../../validation/diagnostic.js';
 import type { ValueProgram } from '../compile/model.js';
-export declare function validateValueProgram(program: ValueProgram, input: unknown, roots?: readonly number[]): readonly Diagnostic[];
+export declare function validateValueProgram(program: ValueProgram, input: unknown, roots?: readonly number[], options?: Options): readonly Diagnostic[];

package/dist/v1/language/value/evaluate/program.js

@@ -1,8 +1,8 @@
 import { loadValueProgram } from '../compile/load.js';
 import { validateCanonicalJsonDomain } from '../profile/json.validate.js';
 import { evaluateInstance } from './evaluator.js';
-export function validateValueProgram(program, input, roots = [program.root]) {
-    const canonical = validateCanonicalJsonDomain(input, '');
+export function validateValueProgram(program, input, roots = [program.root], options) {
+    const canonical = validateCanonicalJsonDomain(input, '', options);
     if (canonical.length > 0)
         return canonical;
     return roots.flatMap((root) => {

package/dist/v1/language/value/evaluate/validate.d.ts

@@ -1,4 +1,4 @@
-import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
+import type { Value as JsonValue, Options } from '@astrale-os/kernel-dsl/value';
 import type { Diagnostic } from '../../validation/diagnostic.js';
 import type { JsonSchema } from '../model/schema.js';
 import type { ValueSchemaRegistry } from '../reference/registry.js';
@@ -13,4 +13,4 @@ import { type PatternPool } from './preparation.js';
  */
 export declare function validateJsonInstance(schema: JsonSchema, value: JsonValue, registry: ValueSchemaRegistry, pointer?: string, patterns?: PatternPool): Diagnostic[];
 /** Validate with the exact preparation already retained by a source-resolved Property or Callable. */
-export declare function validatePreparedInstance(compiled: CompiledInstanceSchema, value: unknown): Diagnostic[];
+export declare function validatePreparedInstance(compiled: CompiledInstanceSchema, value: unknown, options?: Options): Diagnostic[];

package/dist/v1/language/value/evaluate/validate.js

@@ -2,6 +2,7 @@ import { diagnostic } from '../../validation/diagnostic.js';
 import { validateCanonicalJsonDomain } from '../profile/json.validate.js';
 import { evaluateInstance } from './evaluator.js';
 import { prepareValueSchema, } from './preparation.js';
+import { satisfies } from './validity.optimization.js';
 const validatorCache = new WeakMap();
 /**
  * Validate one complete portable value with the admitted V1 Draft 2020-12 profile.
@@ -23,13 +24,16 @@ export function validateJsonInstance(schema, value, registry, pointer = '', patt
     return instanceDiagnostics(prepared.value, value, pointer);
 }
 /** Validate with the exact preparation already retained by a source-resolved Property or Callable. */
-export function validatePreparedInstance(compiled, value) {
-    const diagnostics = [...validateCanonicalJsonDomain(value, '')];
+export function validatePreparedInstance(compiled, value, options) {
+    const diagnostics = [...validateCanonicalJsonDomain(value, '', options)];
     return diagnostics.length > 0
         ? diagnostics
         : instanceDiagnostics(compiled, value, '');
 }
 function instanceDiagnostics(compiled, value, pointer) {
+    // A value the compiled check finds valid has nothing to report; any other is evaluated.
+    if (satisfies(compiled, value) === true)
+        return [];
     const result = evaluateInstance(compiled, value);
     if (result.valid)
         return [];

package/dist/v1/language/value/evaluate/validity.optimization.d.ts

@@ -0,0 +1,14 @@
+import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
+import type { CompiledInstanceSchema } from './types.js';
+/**
+ * Whether a value satisfies its prepared schema, as the evaluator decides it, without building a
+ * failure, an instance pointer or an annotation: the evaluator's verdict, or undefined when this
+ * check cannot give it. Only the evaluator reports why a value fails, so a caller keeps it for
+ * every value this check does not find valid.
+ *
+ * Each schema location is compiled once into a closure over its keywords, retained with the
+ * prepared schema. A schema whose closure holds an annotation-dependent keyword
+ * (`unevaluatedItems`, `unevaluatedProperties`) is left to the evaluator, as is a value nested
+ * deeper than this check follows, and any value whose check throws.
+ */
+export declare function satisfies(compiled: CompiledInstanceSchema, value: JsonValue): boolean | undefined;