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

package/dist/v1/schema/validation/policy/uses.js

@@ -1,119 +1,92 @@
 import { Key } from '../../../addressing/index.js';
 import { definitionRefIndex } from '../../../addressing/ordering.js';
 import { isBinaryInput } from '../../../language/callable/model/callable.js';
-import { admittedCheckClasses, neverAdmittedClasses, } from '../../../language/policy/analysis/checks.js';
-import { checksNameTheCaller, isClassRuleChecks } from '../../../language/policy/model/policy.js';
+import { neverAdmittedClasses, } from '../../../language/policy/analysis/checks.js';
+import { CLASS_OPERATIONS, checksNameTheCaller, isClassRuleChecks, } from '../../../language/policy/model/policy.js';
 import { normalizePolicyChecks } from '../../../language/policy/normalization/normalize.js';
 import { GRAPH_NODE_PATH_SCHEMA_ID } from '../../../language/value/syntax/node-path/schema.js';
-import { MAX_BRANCHES, MAX_CHECK_DEPTH, MAX_CHECK_LEAVES, measureChecks } from './budgets.js';
-import { escapePointer } from './context.js';
+import { escapePointerToken } from '../../../language/value/syntax/pointer.js';
+import { declaredContracts } from '../callable.js';
 import { referenceContracts } from './objects.js';
 import { contractOfNodeDefinition } from './typing.js';
 const formatDefinitionRef = Key.of;
 /** How a refusal names the checks of each site and the contract of their objects. */
-const SITE = {
+export const SITE = {
     callable: { checks: 'Callable checks', objects: 'the callable object contract' },
     class: { checks: 'Class rule checks', objects: 'the Class rule object contract' },
 };
-export function validateReadUses(context, typing) {
-    validateClassPolicyUses(context, typing, 'read');
-}
-export function validateTraverseUses(context, typing) {
-    validateClassPolicyUses(context, typing, 'traverse');
+/** Type every Class slot: its Policy against the instance it decides, or its Policy checks. */
+export function validateClassUses(context, typing) {
+    for (const operation of CLASS_OPERATIONS)
+        validateClassPolicyUses(context, typing, operation);
 }
 function validateClassPolicyUses(context, typing, operation) {
     for (const [name, declaration] of Object.entries(context.environment.candidate.classes)) {
         const ref = declaration.policies[operation];
         if (typeof ref !== 'object')
             continue;
-        const pointer = `/classes/${escapePointer(name)}/policies/${operation}`;
+        const pointer = `/classes/${escapePointerToken(name)}/policies/${operation}`;
+        const self = { origin: context.environment.candidate.origin, kind: 'class', name };
         if (isClassRuleChecks(ref)) {
-            // A rule decides the caller the way a named Policy does, so, as a Policy connects its
-            // subject, each way the rule holds must pass through a check of the caller.
-            if (!checksNameTheCaller(ref)) {
-                context.add('PL_CONNECTIVITY', pointer, `Every branch of the ${operation} rule of Node Class ${name} must check a Policy: sameNode alone names no caller.`);
-            }
-            // Structure admits Policy checks only on a Node Class: `self` is the observed exact Class.
+            // Structure admits `self` everywhere but in a Node create rule: there is no Node yet.
             validateChecks(context, typing, ref, {
                 site: 'class',
                 pointer,
                 input: {},
-                receiver: { origin: context.environment.candidate.origin, kind: 'class', name },
-                instanceMethod: true,
+                ...(declaration.kind === 'node'
+                    ? { receiver: self }
+                    : { edge: { ref: self, declaration } }),
             });
             continue;
         }
         if (!context.resolvePolicy(ref, pointer))
             continue;
         if (declaration.kind === 'node') {
-            const object = {
-                kind: 'exact',
-                ref: { origin: context.environment.candidate.origin, kind: 'class', name },
-            };
+            const object = { kind: 'exact', ref: self };
             if (typing.policyAccepts(ref.name, object))
                 continue;
             context.add('PL_USE', pointer, `${formatDefinitionRef(ref)} is not valid for every normalized branch of ${operation} Node Class ${name}.`, formatDefinitionRef(ref));
             continue;
         }
-        const endpoints = declaration.orientation === 'directed'
-            ? [declaration.endpoints.source, declaration.endpoints.target]
-            : declaration.endpoints;
-        const sources = typing.concreteEndpointClasses(endpoints[0].accepts);
-        const targets = typing.concreteEndpointClasses(endpoints[1].accepts);
-        const accepted = sources.every((source) => targets.every((target) => typing.policyAcceptsEdge(ref.name, { kind: 'exact', ref: source }, { kind: 'exact', ref: target })));
-        if (!accepted) {
+        if (!typing.policyAcceptsEdgeClass(ref.name, declaration)) {
             context.add('PL_USE', pointer, `${formatDefinitionRef(ref)} is not valid for every concrete source/target pair of ${operation} Edge Class ${name}.`, formatDefinitionRef(ref));
         }
     }
 }
 export function validateCallableUses(context, typing) {
-    for (const [name, declaration] of Object.entries(context.environment.candidate.functions)) {
-        if (typeof declaration.policy !== 'object')
-            continue;
-        validateChecks(context, typing, declaration.policy, {
-            site: 'callable',
-            pointer: `/functions/${escapePointer(name)}/policy`,
-            input: isBinaryInput(declaration.input) ? declaration.input.metadata : declaration.input,
-            instanceMethod: false,
-        });
-    }
-    for (const [name, declaration] of Object.entries(context.environment.candidate.classes)) {
-        if (declaration.kind !== 'node')
-            continue;
-        validateDeclaredMethods(context, typing, 'classes', name, declaration.methods, {
-            origin: context.environment.candidate.origin,
-            kind: 'class',
-            name,
-        });
+    for (const { contract, pointer, receiver, method } of declaredContracts(context.environment.candidate)) {
+        // Definition analysis is the authority for the effective callable. A missing Method is already
+        // a definition diagnostic, so avoid inventing a second Policy interpretation for it.
+        if (method !== undefined) {
+            const owner = context.analysis.definitions.get(definitionRefIndex(method.owner));
+            if (owner !== undefined && !owner.methods.has(method.name))
+                continue;
+        }
+        validateContractPolicy(context, typing, contract, pointer, receiver);
     }
 }
-function validateDeclaredMethods(context, typing, namespace, name, methods, receiver) {
-    const ownerAnalysis = context.analysis.definitions.get(definitionRefIndex(receiver));
-    for (const [methodName, method] of Object.entries(methods)) {
-        if (typeof method.policy !== 'object')
-            continue;
-        // Definition analysis is the authority for the effective callable. A
-        // missing entry is already a definition diagnostic, so avoid inventing a
-        // second Policy interpretation for it.
-        if (ownerAnalysis !== undefined && !ownerAnalysis.methods.has(methodName))
-            continue;
-        validateChecks(context, typing, method.policy, {
-            site: 'callable',
-            pointer: `/${namespace}/${escapePointer(name)}/methods/${escapePointer(methodName)}/policy`,
-            input: method.input,
-            receiver,
-            instanceMethod: !method.static,
-        });
-    }
+/**
+ * Validate the Policy of one callable contract written at `pointer`, wherever it is declared:
+ * `self` names the Node of the `receiver` Class, and nothing where the call has no receiver.
+ */
+export function validateContractPolicy(context, typing, contract, pointer, receiver) {
+    if (typeof contract.policy !== 'object')
+        return;
+    validateChecks(context, typing, contract.policy, {
+        site: 'callable',
+        pointer: `${pointer}/policy`,
+        input: isBinaryInput(contract.input) ? contract.input.metadata : contract.input,
+        ...(receiver === undefined ? {} : { receiver }),
+    });
 }
-function validateChecks(validation, typing, expression, context) {
-    const normalized = normalizePolicyChecks(expression);
-    const measure = measureChecks(normalized);
-    if (measure.depth > MAX_CHECK_DEPTH ||
-        measure.branches > MAX_BRANCHES ||
-        measure.leaves > MAX_CHECK_LEAVES) {
-        validation.add('PL_BUDGET', context.pointer, `${SITE[context.site].checks} require depth <= ${MAX_CHECK_DEPTH}, branches <= ${MAX_BRANCHES}, and leaves <= ${MAX_CHECK_LEAVES}; got ${measure.depth}, ${measure.branches}, ${measure.leaves}.`);
+export function validateChecks(validation, typing, expression, context) {
+    // Checks decide the caller the way a named Policy does, so, as a Policy connects its subject,
+    // each way they hold must pass through a check of the caller.
+    if (!checksNameTheCaller(expression)) {
+        validation.add('PL_CONNECTIVITY', context.pointer, `${SITE[context.site].checks} must check a Policy on every branch: sameNode alone names no caller.`);
     }
+    // Their budget is checked with the named Policies', from the same measure (`budgets.ts`).
+    const normalized = normalizePolicyChecks(expression);
     const leaves = new Map();
     visitChecks(validation, typing, normalized, context, context.pointer, leaves);
     for (const [object, className] of neverAdmittedClasses(normalized, leaves)) {
@@ -124,7 +97,11 @@ function visitChecks(validation, typing, expression, context, pointer, leaves) {
     if ('sameNode' in expression) {
         for (const [side, object] of Object.entries(expression.sameNode)) {
             const objectPointer = `${pointer}/sameNode/${side}`;
-            if (object.kind === 'self')
+            if (object.kind === 'self' && context.edge !== undefined) {
+                // `self` is an Edge there, and sameNode compares Nodes.
+                validation.add('PL_USE', objectPointer, 'sameNode compares Nodes: self is an Edge here.');
+            }
+            else if (object.kind === 'self')
                 selfContracts(validation, context, objectPointer);
             else if (object.kind === 'input')
                 inputContracts(validation, context, object.field, objectPointer);
@@ -136,6 +113,16 @@ function visitChecks(validation, typing, expression, context, pointer, leaves) {
     if ('check' in expression) {
         if (!validation.resolvePolicy(expression.check, `${pointer}/check`))
             return;
+        if (expression.object.kind === 'self' && context.edge !== undefined) {
+            // An Edge is checked as an Edge Class Policy is: over every concrete endpoint pair.
+            if (!typing.policyAcceptsEdgeClass(expression.check.name, context.edge.declaration)) {
+                validation.add('PL_USE', pointer, `${formatDefinitionRef(expression.check)} is not valid for every concrete source/target pair of Edge Class ${context.edge.ref.name}.`, formatDefinitionRef(expression.check));
+                return;
+            }
+            const edge = formatDefinitionRef(context.edge.ref);
+            leaves.set(expression, { accepted: [edge], admitted: new Set([edge]) });
+            return;
+        }
         const objectPointer = `${pointer}/object`;
         const contracts = expression.object.kind === 'self'
             ? selfContracts(validation, context, objectPointer)
@@ -144,30 +131,20 @@ function visitChecks(validation, typing, expression, context, pointer, leaves) {
                 : referenceContracts(validation, expression.object.ref, objectPointer);
         if (contracts === undefined)
             return;
-        const typings = new Map(contracts.map((contract) => [
-            contractName(contract),
-            typing.policyBranchTyping(expression.check.name, contract),
-        ]));
-        const admitted = admittedCheckClasses(typings);
-        if (admitted === undefined) {
+        const classes = typing.checkLeafClasses(expression.check.name, contracts);
+        if (classes === undefined) {
             validation.add('PL_USE', pointer, `${formatDefinitionRef(expression.check)} is incompatible with ${SITE[context.site].objects}.`, formatDefinitionRef(expression.check));
             return;
         }
-        leaves.set(expression, { accepted: [...typings.keys()], admitted });
+        leaves.set(expression, classes);
         return;
     }
     const { key, values } = checkOperands(expression);
-    if (values.length === 0) {
-        validation.add('PL_COMPOSITION', `${pointer}/${key}`, `${key} must be non-empty.`);
-    }
     values.forEach((child, index) => visitChecks(validation, typing, child, context, `${pointer}/${key}/${index}`, leaves));
 }
-function contractName(contract) {
-    return contract.kind === 'exact' ? formatDefinitionRef(contract.ref) : 'default';
-}
 function selfContracts(validation, context, pointer) {
-    if (!context.instanceMethod || context.receiver === undefined) {
-        validation.add('PL_USE', pointer, 'self is valid only for a Node instance Method.');
+    if (context.receiver === undefined) {
+        validation.add('PL_USE', pointer, 'self is valid only where a Node receives the call: a Node instance Method, or a Function instance, whose Node carries the contract.');
         return undefined;
     }
     return [contractOfNodeDefinition(context.receiver)];

package/dist/v1/schema/validation/policy/validate.js

@@ -1,8 +1,9 @@
+import { PolicyTyping } from '../../../language/policy/analysis/typing.js';
 import { validatePolicyBudgets } from './budgets.js';
 import { PolicyValidationContext } from './context.js';
 import { validatePolicyReferences } from './references.js';
-import { PolicyTyping } from './typing.js';
-import { validateCallableUses, validateReadUses, validateTraverseUses } from './uses.js';
+import { validatePolicyTyping } from './typing.js';
+import { validateCallableUses, validateClassUses } from './uses.js';
 /**
  * Validates the closed V1 Policy language after structural parsing.
  *
@@ -15,9 +16,8 @@ export function validatePolicies(environment, analysis) {
     validatePolicyReferences(context);
     validatePolicyBudgets(context);
     const typing = new PolicyTyping(context);
-    typing.validatePolicies();
-    validateReadUses(context, typing);
-    validateTraverseUses(context, typing);
+    validatePolicyTyping(context, typing);
+    validateClassUses(context, typing);
     validateCallableUses(context, typing);
     return Object.freeze(context.diagnostics);
 }

package/dist/v1/schema/validation/value-api.d.ts

@@ -1,4 +1,5 @@
 /** The exact V1 value-schema grammar embedded in DomainSchema declarations. */
+import type { ValueKind } from '@astrale-os/kernel-dsl/value';
 import type { Diagnostic } from '../../language/validation/diagnostic.js';
 import type { JsonSchema } from '../../language/value/model/schema.js';
 import type { OrderingKind } from '../../language/value/ordering.js';
@@ -9,7 +10,28 @@ export type { BlobOptions, BlobReceipt, BlobRef, BlobSchema, } from '../../langu
 export type { JsonSchema as Schema, JsonSchemaObject as SchemaObject, PathAnnotation, PropertyObjectSchema as PropertySchema, ValueSchemaContext as Context, } from '../../language/value/model/schema.js';
 export { instant } from '../../language/value/model/instant.js';
 export type { OrderingKind } from '../../language/value/ordering.js';
+export { VALUE_KINDS } from '../../language/value/ordering.js';
+export { GRAPH_NODE_PATH_SCHEMA_ID as NODE_PATH } from '../../language/value/syntax/node-path/schema.js';
+export { DECLARED_VALUE_KINDS as DECLARED_KINDS, FORBIDDEN_KEYWORDS, SUBSCHEMA_KEYWORDS, VALUE_KEYWORDS as KEYWORDS, } from '../../language/value/profile/vocabulary.js';
+export type { DeclaredValueKind as DeclaredKind, ValueKeyword as Keyword, } from '../../language/value/profile/vocabulary.js';
+export { VALUE_RULES as RULES } from '../../language/validation/rule.js';
+export type { ValueRule as Rule, ValueRuleStage as RuleStage, } from '../../language/validation/rule.js';
 /** Validate one complete JSON value under the exact accepted schema that owns the contract. */
 export declare function validate(owner: DomainSchema, contract: JsonSchema, input: unknown, pointer?: string): readonly Diagnostic[];
 /** Return the one portable scalar ordering domain admitted by a property schema, if any. */
 export declare function classifyOrdering(owner: DomainSchema, contract: JsonSchema): OrderingKind | undefined;
+/**
+ * The value kind of a property schema: what a graph language may test on the property (Y4). It is
+ * the one kind of every non-null value the schema admits: `text` for strings, `number` for numbers
+ * and integers, `instant` for strings declared `x-astrale-value-kind: instant`, `enum` for a finite
+ * set of strings (`const` or `enum`), `boolean`, and `set` for arrays of `uniqueItems`. An
+ * ambiguous union, an object, an array with repetitions, a blob or a schema that admits no value is
+ * `json`. `$ref`, `allOf`, `anyOf` and `oneOf` are followed; `null` is a point of every kind.
+ */
+export declare function classifyValueKind(owner: DomainSchema, contract: JsonSchema): ValueKind;
+/**
+ * A warning for each class property whose value kind is `json` (an ambiguous union, an object, an
+ * array with repetitions): a Query filters it by equality only. Nothing refuses such a property;
+ * the CLI shows the warning to its author.
+ */
+export declare function valueKindWarnings(owner: DomainSchema): readonly Diagnostic<'VS_VALUE_KIND_JSON'>[];

package/dist/v1/schema/validation/value-api.js

@@ -1,11 +1,17 @@
 /** The exact V1 value-schema grammar embedded in DomainSchema declarations. */
+import { diagnostic } from '../../language/validation/diagnostic.js';
 import { validateJsonInstance } from '../../language/value/evaluate/validate.js';
-import { classifyOrdering as classifyOrderingWithRegistry } from '../../language/value/ordering.js';
+import { classifyOrdering as classifyOrderingWithRegistry, classifyValueKind as classifyValueKindWithRegistry, } from '../../language/value/ordering.js';
+import { escapePointerToken } from '../../language/value/syntax/pointer.js';
 import { createDomainValueSchemaRegistry } from '../resolution/value.registry.js';
 const registries = new WeakMap();
 export { VALUE_SCHEMA_DIALECT as DIALECT, VALUE_SCHEMA_VOCABULARY as VOCABULARY, } from '../../language/value/model/schema.js';
 export { blob, isBlobValueSchema as isBlob } from '../../language/value/model/blob.js';
 export { instant } from '../../language/value/model/instant.js';
+export { VALUE_KINDS } from '../../language/value/ordering.js';
+export { GRAPH_NODE_PATH_SCHEMA_ID as NODE_PATH } from '../../language/value/syntax/node-path/schema.js';
+export { DECLARED_VALUE_KINDS as DECLARED_KINDS, FORBIDDEN_KEYWORDS, SUBSCHEMA_KEYWORDS, VALUE_KEYWORDS as KEYWORDS, } from '../../language/value/profile/vocabulary.js';
+export { VALUE_RULES as RULES } from '../../language/validation/rule.js';
 /** Validate one complete JSON value under the exact accepted schema that owns the contract. */
 export function validate(owner, contract, input, pointer = '') {
     return validateJsonInstance(contract, input, registryFor(owner), pointer);
@@ -14,6 +20,33 @@ export function validate(owner, contract, input, pointer = '') {
 export function classifyOrdering(owner, contract) {
     return classifyOrderingWithRegistry(contract, registryFor(owner));
 }
+/**
+ * The value kind of a property schema: what a graph language may test on the property (Y4). It is
+ * the one kind of every non-null value the schema admits: `text` for strings, `number` for numbers
+ * and integers, `instant` for strings declared `x-astrale-value-kind: instant`, `enum` for a finite
+ * set of strings (`const` or `enum`), `boolean`, and `set` for arrays of `uniqueItems`. An
+ * ambiguous union, an object, an array with repetitions, a blob or a schema that admits no value is
+ * `json`. `$ref`, `allOf`, `anyOf` and `oneOf` are followed; `null` is a point of every kind.
+ */
+export function classifyValueKind(owner, contract) {
+    return classifyValueKindWithRegistry(contract, registryFor(owner));
+}
+/**
+ * A warning for each class property whose value kind is `json` (an ambiguous union, an object, an
+ * array with repetitions): a Query filters it by equality only. Nothing refuses such a property;
+ * the CLI shows the warning to its author.
+ */
+export function valueKindWarnings(owner) {
+    const warnings = [];
+    for (const [className, definition] of Object.entries(owner.classes)) {
+        for (const [name, property] of Object.entries(definition.properties)) {
+            if (classifyValueKind(owner, property.schema) !== 'json')
+                continue;
+            warnings.push(diagnostic('VS_VALUE_KIND_JSON', `/classes/${escapePointerToken(className)}/properties/${escapePointerToken(name)}`, `The value kind of ${className}.${name} is json: a Query filters it by equality only.`));
+        }
+    }
+    return warnings;
+}
 function registryFor(owner) {
     let registry = registries.get(owner);
     if (registry === undefined) {

package/dist/v1/schema/validation/value.d.ts

@@ -1,4 +1,7 @@
+import type { CallableDefinition } from '../../language/callable/model/callable.js';
 import type { ValueSchemaRegistry } from '../../language/value/reference/registry.js';
 import type { SchemaDiagnostic } from '../diagnostic.js';
 import type { DomainSchemaIR } from '../model/schema.js';
 export declare function validateEmbeddedValueSchemas(schema: DomainSchemaIR, registry: ValueSchemaRegistry): readonly SchemaDiagnostic[];
+/** Validate the value schemas of one callable contract at `pointer`. */
+export declare function validateCallable(declaration: CallableDefinition, pointer: string, registry: ValueSchemaRegistry, diagnostics: SchemaDiagnostic[]): void;

package/dist/v1/schema/validation/value.js

@@ -1,27 +1,22 @@
 import { isBinaryInput } from '../../language/callable/model/callable.js';
 import { validateValueSchema } from '../../language/value/profile/validate.js';
-import { diagnostic } from '../diagnostic.js';
+import { escapePointerToken } from '../../language/value/syntax/pointer.js';
+import { valueDiagnostic } from '../diagnostic.js';
 export function validateEmbeddedValueSchemas(schema, registry) {
     const diagnostics = [];
     for (const [name, declaration] of Object.entries(schema.classes)) {
-        validateDefinition(declaration, `/classes/${escapePointer(name)}`, registry, diagnostics);
-    }
-    for (const [name, declaration] of Object.entries(schema.functions)) {
-        validateCallable(declaration, `/functions/${escapePointer(name)}`, registry, diagnostics);
+        validateDefinition(declaration, `/classes/${escapePointerToken(name)}`, registry, diagnostics);
     }
+    // Callable contracts are validated at their site, as one contract (`validateContracts`).
     return Object.freeze(diagnostics);
 }
 function validateDefinition(declaration, pointer, registry, diagnostics) {
     for (const [name, property] of Object.entries(declaration.properties)) {
-        validate(property.schema, 'property-facet', `${pointer}/properties/${escapePointer(name)}/schema`, registry, diagnostics);
-    }
-    if ('methods' in declaration) {
-        for (const [name, method] of Object.entries(declaration.methods)) {
-            validateCallable(method, `${pointer}/methods/${escapePointer(name)}`, registry, diagnostics);
-        }
+        validate(property.schema, 'property-facet', `${pointer}/properties/${escapePointerToken(name)}/schema`, registry, diagnostics);
     }
 }
-function validateCallable(declaration, pointer, registry, diagnostics) {
+/** Validate the value schemas of one callable contract at `pointer`. */
+export function validateCallable(declaration, pointer, registry, diagnostics) {
     if (isBinaryInput(declaration.input)) {
         validate(declaration.input.metadata, 'callable-input', `${pointer}/input/metadata`, registry, diagnostics);
     }
@@ -36,10 +31,7 @@ function validateCallable(declaration, pointer, registry, diagnostics) {
     }
 }
 function validate(schema, context, pointer, registry, diagnostics) {
-    for (const failure of validateValueSchema(schema, context, registry, pointer)) {
-        diagnostics.push(diagnostic('DV_VALUE_SCHEMA', failure.pointer, `[${failure.code}] ${failure.message}`, failure.ref));
+    for (const refusal of validateValueSchema(schema, context, registry, pointer)) {
+        diagnostics.push(valueDiagnostic('DV_VALUE_SCHEMA', refusal));
     }
 }
-function escapePointer(value) {
-    return value.replaceAll('~', '~0').replaceAll('/', '~1');
-}

package/dist/v1/schema/validation/value.json-schema.d.ts

@@ -0,0 +1,49 @@
+import { type JsonSchema } from './json.json-schema.js';
+/**
+ * The checks on value schemas JSON Schema cannot state, which the published document names with
+ * the positions it constrains. The Kernel reports each as `DV_VALUE_SCHEMA`, with its value code.
+ */
+export declare const valueSchemaRules: {
+    readonly 'value-blob': {
+        readonly code: 'DV_VALUE_SCHEMA';
+        readonly valueCode: 'VS_VALUE_KIND';
+        readonly statement: 'A blob is declared only by the whole schema of a Property, exactly as values.blob writes it.';
+    };
+    readonly 'value-path': {
+        readonly code: 'DV_VALUE_SCHEMA';
+        readonly valueCode: 'VS_PATH_EXTENSION';
+        readonly statement: 'x-astrale-path annotates only a direct Property of a callable input object, beside exactly the $ref of the graph NodePath schema.';
+    };
+    readonly 'value-recursion': {
+        readonly code: 'DV_VALUE_SCHEMA';
+        readonly valueCode: 'VS_RECURSION_PRODUCTIVE';
+        readonly statement: string;
+    };
+    readonly 'value-reference-form': {
+        readonly code: 'DV_VALUE_SCHEMA';
+        readonly valueCode: 'VS_REFERENCE_FORM';
+        readonly statement: string;
+    };
+    readonly 'value-reference-resolution': {
+        readonly code: 'DV_VALUE_SCHEMA';
+        readonly valueCode: 'VS_REFERENCE_RESOLUTION';
+        readonly statement: 'A $ref resolves to a location of its own value schema, and x-astrale-path accepts Node Classes of the Domain or of a direct dependency.';
+    };
+    readonly 'value-regexp': {
+        readonly code: 'DV_VALUE_SCHEMA';
+        readonly valueCode: 'VS_REGEX_PORTABLE';
+        readonly statement: string;
+    };
+};
+export type ValueSchemaRule = keyof typeof valueSchemaRules;
+/**
+ * The value language in JSON Schema, for the document that embeds value schemas: `root` constrains
+ * the `value-schema` definition with the published dialect and what the profile adds to it,
+ * `definitions` holds the locations it reaches and the members of the Path annotation, and
+ * `nodeProperty` constrains a Node Property definition. A named check leaves `x-astrale-rule` at the positions it constrains.
+ */
+export declare function valueSchemaJsonSchema(): {
+    readonly root: readonly JsonSchema[];
+    readonly definitions: Readonly<Record<string, JsonSchema>>;
+    readonly nodeProperty: JsonSchema;
+};

package/dist/v1/schema/validation/value.json-schema.js

@@ -0,0 +1,137 @@
+import { VALUE_RULES } from '../../language/validation/rule.js';
+import { VALUE_SCHEMA_DIALECT } from '../../language/value/model/schema.js';
+import { FORBIDDEN_KEYWORDS, SUBSCHEMA_KEYWORDS, VALUE_KEYWORDS, } from '../../language/value/profile/vocabulary.js';
+import { named } from './json.json-schema.js';
+/**
+ * The checks on value schemas JSON Schema cannot state, which the published document names with
+ * the positions it constrains. The Kernel reports each as `DV_VALUE_SCHEMA`, with its value code.
+ */
+export const valueSchemaRules = {
+    'value-blob': {
+        code: 'DV_VALUE_SCHEMA',
+        valueCode: 'VS_VALUE_KIND',
+        statement: 'A blob is declared only by the whole schema of a Property, exactly as values.blob writes it.',
+    },
+    // Its members are stated (`path-annotation`); where it stands is named.
+    'value-path': {
+        code: 'DV_VALUE_SCHEMA',
+        valueCode: 'VS_PATH_EXTENSION',
+        statement: 'x-astrale-path annotates only a direct Property of a callable input object, beside exactly the $ref of the graph NodePath schema.',
+    },
+    'value-recursion': {
+        code: 'DV_VALUE_SCHEMA',
+        valueCode: 'VS_RECURSION_PRODUCTIVE',
+        statement: VALUE_RULES.VS_RECURSION_PRODUCTIVE.statement,
+    },
+    'value-reference-form': {
+        code: 'DV_VALUE_SCHEMA',
+        valueCode: 'VS_REFERENCE_FORM',
+        statement: VALUE_RULES.VS_REFERENCE_FORM.statement,
+    },
+    'value-reference-resolution': {
+        code: 'DV_VALUE_SCHEMA',
+        valueCode: 'VS_REFERENCE_RESOLUTION',
+        statement: 'A $ref resolves to a location of its own value schema, and x-astrale-path accepts Node Classes of the Domain or of a direct dependency.',
+    },
+    'value-regexp': {
+        code: 'DV_VALUE_SCHEMA',
+        valueCode: 'VS_REGEX_PORTABLE',
+        statement: VALUE_RULES.VS_REGEX_PORTABLE.statement,
+    },
+};
+const KIND = 'x-astrale-value-kind';
+const LOCATION = '#/$defs/value-location';
+const SUBSCHEMA = '#/$defs/value-subschema';
+const PATH = '#/$defs/path-annotation';
+/**
+ * The value language in JSON Schema, for the document that embeds value schemas: `root` constrains
+ * the `value-schema` definition with the published dialect and what the profile adds to it,
+ * `definitions` holds the locations it reaches and the members of the Path annotation, and
+ * `nodeProperty` constrains a Node Property definition. A named check leaves `x-astrale-rule` at the positions it constrains.
+ */
+export function valueSchemaJsonSchema() {
+    return {
+        root: [
+            { $ref: VALUE_SCHEMA_DIALECT },
+            { $ref: LOCATION },
+            objectOrBoolean({
+                properties: {
+                    $schema: { const: VALUE_SCHEMA_DIALECT },
+                    [KIND]: named({ enum: ['instant', 'blob'] }, 'value-blob'),
+                },
+            }),
+        ],
+        definitions: {
+            // Every location, the root included: the closed vocabulary and the subschemas it holds.
+            'value-location': objectOrBoolean({
+                propertyNames: {
+                    enum: VALUE_KEYWORDS.filter((keyword) => !FORBIDDEN_KEYWORDS.includes(keyword)),
+                },
+                properties: {
+                    $id: false,
+                    $ref: named({ type: 'string' }, 'value-recursion', 'value-reference-form', 'value-reference-resolution'),
+                    enum: { type: 'array', uniqueItems: true },
+                    fullMatch: named({ type: 'string' }, 'value-regexp'),
+                    pattern: named({ type: 'string' }, 'value-regexp'),
+                    'x-astrale-path': named({ $ref: PATH }, 'value-path'),
+                    ...Object.fromEntries(SUBSCHEMA_KEYWORDS.single.map((keyword) => [keyword, { $ref: SUBSCHEMA }])),
+                    ...Object.fromEntries(SUBSCHEMA_KEYWORDS.array.map((keyword) => [
+                        keyword,
+                        { type: 'array', items: { $ref: SUBSCHEMA } },
+                    ])),
+                    ...Object.fromEntries(SUBSCHEMA_KEYWORDS.map.map((keyword) => {
+                        const members = {
+                            type: 'object',
+                            additionalProperties: { $ref: SUBSCHEMA },
+                        };
+                        if (keyword !== 'patternProperties')
+                            return [keyword, members];
+                        return [keyword, named(members, 'value-regexp')];
+                    })),
+                },
+                // An instant is a string.
+                if: { required: [KIND], properties: { [KIND]: { const: 'instant' } } },
+                // oxlint-disable-next-line unicorn/no-thenable -- the JSON Schema keyword
+                then: { required: ['type'], properties: { type: { const: 'string' } } },
+            }),
+            // The Path annotation: the one Node a Path field resolves, of a Node Class it accepts.
+            'path-annotation': {
+                type: 'object',
+                properties: {
+                    target: { type: 'string', const: 'node' },
+                    cardinality: { type: 'string', const: 'one' },
+                    accepts: {
+                        type: 'array',
+                        minItems: 1,
+                        uniqueItems: true,
+                        items: named({ $ref: '#/$defs/class-ref' }, 'value-reference-resolution'),
+                    },
+                },
+                required: ['target', 'cardinality', 'accepts'],
+                additionalProperties: false,
+            },
+            // A location below the root: no $schema, and no blob.
+            'value-subschema': {
+                allOf: [
+                    { $ref: LOCATION },
+                    objectOrBoolean({ properties: { $schema: false, [KIND]: { const: 'instant' } } }),
+                ],
+            },
+        },
+        // An automatic or State Property holds no blob.
+        nodeProperty: {
+            if: { anyOf: [{ required: ['auto'] }, { required: ['state'] }] },
+            // oxlint-disable-next-line unicorn/no-thenable -- the JSON Schema keyword
+            then: {
+                properties: {
+                    schema: {
+                        not: { type: 'object', required: [KIND], properties: { [KIND]: { const: 'blob' } } },
+                    },
+                },
+            },
+        },
+    };
+}
+function objectOrBoolean(object) {
+    return { anyOf: [{ type: 'boolean' }, { type: 'object', ...object }] };
+}

package/dist/v1/schema/validation/view.js

@@ -1,12 +1,14 @@
+import { equalDefinitionRefs } from '../../addressing/definition-ref.js';
 import { Key } from '../../addressing/key.js';
+import { escapePointerToken } from '../../language/value/syntax/pointer.js';
 import { diagnostic } from '../diagnostic.js';
 const formatDefinitionRef = Key.of;
 export function validateViews(environment) {
     const diagnostics = [];
     for (const [name, view] of Object.entries(environment.candidate.views)) {
-        const pointer = `/views/${escapePointer(name)}`;
+        const pointer = `/views/${escapePointerToken(name)}`;
         const ref = { origin: environment.candidate.origin, kind: 'view', name };
-        if (!sameRef(view.ref, ref)) {
+        if (!equalDefinitionRefs(view.ref, ref)) {
             diagnostics.push(diagnostic('DV_REF_RESOLVES', `${pointer}/ref`, `View ref must be exactly ${formatDefinitionRef(ref)}.`, formatDefinitionRef(view.ref)));
         }
     }
@@ -26,9 +28,3 @@ function validateEntrypoint(environment, diagnostics) {
         diagnostics.push(diagnostic('DV_ENTRYPOINT', '/entrypoint', `Entrypoint ${formatDefinitionRef(entrypoint)} is not a Domain-targeted View of ${origin}.`, formatDefinitionRef(entrypoint)));
     }
 }
-function sameRef(left, right) {
-    return left.origin === right.origin && left.kind === right.kind && left.name === right.name;
-}
-function escapePointer(value) {
-    return value.replaceAll('~', '~0').replaceAll('/', '~1');
-}

package/dist/value/canonical.d.ts

@@ -5,3 +5,9 @@ export declare function serialize(input: unknown, options?: Options): string;
 /** Serialize a trusted portable value whose default structural admission proof is still valid. */
 export declare function serializeAdmitted(input: Value): string;
 export declare function encode(input: unknown, options?: Options): Uint8Array;
+/**
+ * The UTF-8 byte length of a trusted Value's canonical JSON, `encode(input).byteLength`, without
+ * serializing it: an admission-owned immutable root counted its bytes when it was admitted, and any
+ * other container is counted member by member.
+ */
+export declare function byteLength(input: Value): number;