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

package/dist/v1/schema/index.js

@@ -2,6 +2,7 @@
 import { resolve as resolveDomainSchema } from './resolution/domain.js';
 export const resolve = resolveDomainSchema;
 export { acceptDomainSchema as accept } from './admission/accept.js';
+export { acceptCallable } from './admission/callable.js';
 export { decodeDomainSchema as decode, encodeDomainSchema as encode, serializeDomainSchema as serialize, } from './codec/schema.js';
 export { revisionOfDomainSchema as revision } from './canonical/revision.js';
 export { ANNOTATION_KEYWORDS, FIELD_ROLES, callableFingerprint } from './compatibility/index.js';
@@ -10,5 +11,8 @@ export { header } from './codec/header.js';
 export { DOMAIN_FORMAT as FORMAT, DOMAIN_VERSION as VERSION } from './model/format.js';
 export { compile, load } from '../compiled/index.js';
 export { SchemaError as Error } from './diagnostic.js';
+export { RULES } from './rule.js';
+export { limits } from '../language/limits.js';
+export { measurePolicies } from './validation/policy/budgets.js';
 /** The versioned value-schema grammar embedded in declarations. */
 export * as values from './validation/value-api.js';

package/dist/v1/schema/model/schema.d.ts

@@ -1,8 +1,10 @@
-import type { Key } from '../../addressing/index.js';
+import type { Value as JsonValue } from '@astrale-os/kernel-dsl/value';
+import type { Key, Revision } from '../../addressing/index.js';
 import type { DomainDependencyMap, ViewRef } from '../../addressing/index.js';
 import type { Domain, DomainOfSource, DomainSource } from '../../domain/model/domain.js';
 import type { FunctionDefinition } from '../../language/callable/model/callable.js';
 import type { ClassDefinition } from '../../language/class/model/class.js';
+import type { PropertyValues } from '../../language/class/property-values.js';
 import type { CoreContent } from '../../language/core/model/core.js';
 import type { PolicyDefinition } from '../../language/policy/model/policy.js';
 import type { ViewDefinition } from '../../language/view/model/view.js';
@@ -21,6 +23,23 @@ export interface DomainSchemaIR {
     readonly views: Readonly<Record<string, ViewDefinition>>;
     readonly core: CoreContent;
 }
+/**
+ * The JSON document of a Domain schema, as tools write and exchange it: `DomainSchemaIR` without
+ * its in-process proofs. The structure the Kernel enforces has this type, which the build checks
+ * (`validation/domain.structure.typecheck.ts`), and the published JSON Schema describes it.
+ */
+export interface DomainSchemaDocument extends DocumentOf<DomainSchemaIR> {
+}
+/**
+ * The JSON document a model type describes. A `Revision` and `PropertyValues` are in-process
+ * proofs: the document carries them as plain text and plain values.
+ */
+export type DocumentOf<Model> = [JsonValue] extends [Model] ? Model : DocumentOfEach<Model>;
+type DocumentOfEach<Model> = Model extends Revision ? string : Model extends PropertyValues ? {
+    readonly [Key in keyof Model as Key extends string ? Key : never]: DocumentOf<Model[Key]>;
+} : Model extends string | number | boolean | null | undefined ? Model : {
+    readonly [Key in keyof Model]: DocumentOf<Model[Key]>;
+};
 declare const DOMAIN_SCHEMA_BRAND: unique symbol;
 /**
  * Accepted canonical schema carrying its exact resolved Domain projection.

package/dist/v1/schema/model/schema.js

@@ -1,4 +1,4 @@
-import { deepFreeze } from '../canonical/freeze.js';
+import { deepFreeze } from '../../language/freeze.js';
 export function asDomainSchema(value) {
     return deepFreeze(value);
 }

package/dist/v1/schema/normalization/domain.d.ts

@@ -1,2 +1,4 @@
+import type { CallableDefinition } from '../../language/callable/model/callable.js';
 import type { DomainSchemaIR } from '../model/schema.js';
 export declare function normalizeDomainSchema(schema: DomainSchemaIR): DomainSchemaIR;
+export declare function canonicalizeCallable(value: CallableDefinition): CallableDefinition;

package/dist/v1/schema/normalization/domain.js

@@ -1,6 +1,8 @@
 import { json } from '@astrale-os/kernel-dsl/value';
 import { compareDefinitionRefs, compareUnicode } from '../../addressing/ordering.js';
 import { isBinaryInput } from '../../language/callable/model/callable.js';
+import { compareEdgeUniqueFields, compareEdgeUniqueTuples, compareNodeUniqueTuples, } from '../../language/class/unique.js';
+import { CLASS_OPERATIONS } from '../../language/policy/model/policy.js';
 import { normalizeClassRule, normalizePolicyChecks, normalizePolicyExpression, } from '../../language/policy/normalization/normalize.js';
 import { admitStateTopology } from '../../language/state/topology.js';
 import { canonicalizeValueSchema } from '../../language/value/profile/canonicalize.js';
@@ -61,6 +63,7 @@ function canonicalizeClass(value) {
         ref: value.ref,
         kind: value.kind,
         abstract: value.abstract,
+        ...(value.inheritance === undefined ? {} : { inheritance: value.inheritance }),
         extends: [...value.extends].sort(compareDefinitionRefs),
         properties: mapRecord(value.properties, canonicalizeProperty),
     };
@@ -70,7 +73,8 @@ function canonicalizeClass(value) {
             methods: mapRecord(value.methods, canonicalizeMethod),
             ...(value.data === undefined ? {} : { data: { mediaType: value.data.mediaType } }),
             ...(value.icon === undefined ? {} : { icon: value.icon }),
-            policies: canonicalizeNodePolicies(value.policies),
+            policies: canonicalizeClassPolicies(value.policies),
+            ...(value.unique === undefined ? {} : { unique: canonicalizeNodeUnique(value.unique) }),
         };
     }
     return value.orientation === 'directed'
@@ -78,23 +82,36 @@ function canonicalizeClass(value) {
             ...base,
             orientation: 'directed',
             endpoints: canonicalizeDirectedEndpoints(value.endpoints),
-            policies: value.policies,
+            policies: canonicalizeClassPolicies(value.policies),
             constraints: value.constraints,
+            ...(value.unique === undefined ? {} : { unique: canonicalizeUnique(value.unique) }),
         }
         : {
             ...base,
             orientation: 'undirected',
             endpoints: canonicalizeIncidentEndpoints(value.endpoints),
-            policies: value.policies,
+            policies: canonicalizeClassPolicies(value.policies),
             constraints: value.constraints,
         };
 }
+/** A set of Node key tuples, each a set of Property keys, both in their canonical order. */
+function canonicalizeNodeUnique(tuples) {
+    return tuples
+        .map((tuple) => [...tuple].sort(compareUnicode))
+        .sort(compareNodeUniqueTuples);
+}
+/** A set of key tuples, each a set of fields: fields and tuples take their canonical order. */
+function canonicalizeUnique(tuples) {
+    return tuples
+        .map((tuple) => [...tuple].sort(compareEdgeUniqueFields))
+        .sort(compareEdgeUniqueTuples);
+}
 /** A rule keeps one spelling: normalized checks, or the Policy a lone `self` check names. */
-function canonicalizeNodePolicies(value) {
-    return {
-        ...(value.read === undefined ? {} : { read: normalizeClassRule(value.read) }),
-        ...(value.traverse === undefined ? {} : { traverse: normalizeClassRule(value.traverse) }),
-    };
+function canonicalizeClassPolicies(value) {
+    return Object.fromEntries(CLASS_OPERATIONS.flatMap((operation) => {
+        const policy = value[operation];
+        return policy === undefined ? [] : [[operation, normalizeClassRule(policy)]];
+    }));
 }
 function canonicalizeFunction(value) {
     return {
@@ -102,7 +119,7 @@ function canonicalizeFunction(value) {
         ...canonicalizeCallable(value),
     };
 }
-function canonicalizeCallable(value) {
+export function canonicalizeCallable(value) {
     const base = {
         ...withDescription(value),
         input: isBinaryInput(value.input)
@@ -115,6 +132,8 @@ function canonicalizeCallable(value) {
         output: canonicalizeCallableOutput(value.output),
         // Ordinary execution has one canonical form, so existing revisions never move.
         ...(value.execution?.durable === true ? { execution: { durable: true } } : {}),
+        // Absence is the one spelling of a call admitted afresh; validation refuses any other.
+        ...(value.admission === undefined ? {} : { admission: { maxAge: value.admission.maxAge } }),
     };
     return value.auth === 'authorized'
         ? {
@@ -154,6 +173,7 @@ function canonicalizeProperty(value) {
             ? {}
             : {
                 auto: {
+                    // The distinct events of a non-empty list are a non-empty list.
                     on: [...new Set(value.auto.on)].sort(compareUnicode),
                     set: value.auto.set,
                 },

package/dist/v1/schema/resolution/closure.js

@@ -20,8 +20,9 @@ export function requireDomainClosure(schema) {
     const closure = knownDomainClosure(schema);
     if (closure !== undefined)
         return closure;
+    // What the value lacks is the exact closure of its dependencies, retained only by acceptance.
     throw new SchemaError([
-        diagnostic('DV_ACCEPTANCE_CONTEXT', '', `DomainSchema ${schema.origin} has no retained acceptance context; accept it again against its exact lookup.`),
+        diagnostic('DV_ACCEPTANCE_CONTEXT', '/dependencies', `DomainSchema ${schema.origin} has no retained acceptance context; accept it again against its exact lookup.`),
     ]);
 }
 export function lookupForDomainClosure(schema) {

package/dist/v1/schema/resolution/context.js

@@ -1,6 +1,7 @@
-import { dependencyLimits } from '../../addressing/domain-dependency.js';
 import { definitionRefIndex } from '../../addressing/ordering.js';
 import { DOMAIN_REVISION_PATTERN } from '../../addressing/patterns.js';
+import { limits } from '../../language/limits.js';
+import { escapePointerToken } from '../../language/value/syntax/pointer.js';
 import { revisionOfDomainSchema } from '../canonical/revision.js';
 import { diagnostic } from '../diagnostic.js';
 import { indexSchemaDefinitions } from './definition.index.js';
@@ -10,11 +11,11 @@ export function buildDomainResolutionContext(candidate, lookup) {
     const dependencies = new Map();
     const definitions = new Map();
     const directOrigins = new Set();
-    if (Object.keys(candidate.dependencies).length > dependencyLimits.direct) {
-        diagnostics.push(diagnostic('DV_DEPENDENCY_LIMITS', '/dependencies', `A Domain may declare at most ${dependencyLimits.direct} direct dependency aliases.`));
+    if (Object.keys(candidate.dependencies).length > limits.dependency.direct) {
+        diagnostics.push(diagnostic('DV_DEPENDENCY_LIMITS', '/dependencies', `A Domain may declare at most ${limits.dependency.direct} direct dependency aliases.`));
     }
     for (const [alias, dependency] of Object.entries(candidate.dependencies)) {
-        const pointer = `/dependencies/${escapeToken(alias)}`;
+        const pointer = `/dependencies/${escapePointerToken(alias)}`;
         if (!DOMAIN_REVISION_PATTERN.test(dependency.revision))
             continue;
         if (dependency.origin === candidate.origin) {
@@ -94,7 +95,7 @@ function loadDependencyClosure(candidate, dependencies, lookup, diagnostics) {
             continue;
         }
         const [alias, dependency] = edge;
-        const pointer = frames.length === 1 ? `/dependencies/${escapeToken(alias)}` : '/dependencies';
+        const pointer = frames.length === 1 ? `/dependencies/${escapePointerToken(alias)}` : '/dependencies';
         if (activeOrigins.has(dependency.origin)) {
             diagnostics.push(diagnostic('DV_DEPENDENCY_ACYCLIC', pointer, `Dependency cycle reaches ${dependency.origin}.`));
             continue;
@@ -120,16 +121,16 @@ function loadDependencyClosure(candidate, dependencies, lookup, diagnostics) {
             continue;
         }
         dependencies.set(nested.origin, nested);
-        if (dependencies.size + 1 > dependencyLimits.closure) {
+        if (dependencies.size + 1 > limits.dependency.closure) {
             if (!closureLimitReported) {
-                diagnostics.push(diagnostic('DV_DEPENDENCY_LIMITS', '/dependencies', `A dependency closure may contain at most ${dependencyLimits.closure} Domains.`));
+                diagnostics.push(diagnostic('DV_DEPENDENCY_LIMITS', '/dependencies', `A dependency closure may contain at most ${limits.dependency.closure} Domains.`));
                 closureLimitReported = true;
             }
             continue;
         }
         const depth = frame.depth + 1;
-        if (depth > dependencyLimits.depth) {
-            diagnostics.push(diagnostic('DV_DEPENDENCY_LIMITS', pointer, `Dependency depth ${depth} exceeds the maximum ${dependencyLimits.depth}.`));
+        if (depth > limits.dependency.depth) {
+            diagnostics.push(diagnostic('DV_DEPENDENCY_LIMITS', pointer, `Dependency depth ${depth} exceeds the maximum ${limits.dependency.depth}.`));
             continue;
         }
         const key = `${dependency.origin}\u0000${dependency.revision}`;
@@ -146,13 +147,12 @@ function loadDependencyClosure(candidate, dependencies, lookup, diagnostics) {
     }
 }
 function validateDependencyUse(candidate, directOrigins, diagnostics) {
+    // Each reference that cannot resolve is reported where it is written; the dependency it lacks
+    // belongs in the dependency map.
     const used = collectUsedForeignOrigins(candidate);
     for (const origin of used) {
         if (!directOrigins.has(origin)) {
-            diagnostics.push(diagnostic('DV_DEPENDENCY_DIRECT', '', `Foreign origin ${origin} is referenced without an exact direct dependency.`));
+            diagnostics.push(diagnostic('DV_DEPENDENCY_DIRECT', '/dependencies', `Foreign origin ${origin} is referenced without an exact direct dependency.`));
         }
     }
 }
-function escapeToken(value) {
-    return value.replaceAll('~', '~0').replaceAll('/', '~1');
-}

package/dist/v1/schema/resolution/domain.d.ts

@@ -1,7 +1,12 @@
 import type { SourceDomain } from '../../domain/model/domain.js';
+import type { CallableValidation } from '../../domain/validation/create.js';
+import type { JsonSchema } from '../../language/value/model/schema.js';
+import type { ValueSchemaRegistry } from '../../language/value/reference/registry.js';
 import type { DomainSchema } from '../model/schema.js';
+import { type PatternPool } from '../../language/value/evaluate/preparation.js';
 /**
  * Resolve one accepted Schema through its exact retained source closure. Acceptance validated it
  * against that closure, which is the only way a Schema retains one, so it is not validated again.
  */
 export declare function resolve<const S extends DomainSchema>(schema: S): SourceDomain<S>;
+export declare function callableValidation(input: JsonSchema, output: JsonSchema | undefined, registry: ValueSchemaRegistry, patterns: PatternPool): CallableValidation;

package/dist/v1/schema/resolution/domain.js

@@ -88,7 +88,7 @@ function sourceValidation(closure, registries) {
     }
     return createDomainValidation(properties, callables);
 }
-function callableValidation(input, output, registry, patterns) {
+export function callableValidation(input, output, registry, patterns) {
     const prepared = prepareValueSchema(input, registry, '', patterns);
     if (!prepared.compiled) {
         throw new TypeError(`Accepted callable input cannot be prepared: ${prepared.message}`);
@@ -97,7 +97,7 @@ function callableValidation(input, output, registry, patterns) {
     const fields = inputFieldNodes(inputProgram);
     return Object.freeze({
         ...(fields === undefined ? {} : { fields: Object.freeze(Object.keys(fields)) }),
-        validateInput: (value) => validatePreparedInstance(prepared.value, value),
+        validateInput: (value, options) => validatePreparedInstance(prepared.value, value, options),
         validateInputField(field, value) {
             const nodes = fields?.[field];
             return nodes === undefined

package/dist/v1/schema/resolution/origins.js

@@ -1,6 +1,6 @@
 import { compareDefinitionRefs, definitionRefIndex } from '../../addressing/ordering.js';
 import { isBinaryInput } from '../../language/callable/model/callable.js';
-import { isClassRuleChecks, policyVariableClass } from '../../language/policy/model/policy.js';
+import { CLASS_OPERATIONS, isClassRuleChecks, policyVariableClass, } from '../../language/policy/model/policy.js';
 import { isValueObject as isJsonObject } from '../../language/value/model/object.js';
 import { walkSchema } from '../../language/value/syntax/walk.js';
 /** Collect only semantic refs, never strings or objects embedded as JSON data. */
@@ -58,7 +58,8 @@ export function collectClassRefs(declaration, add) {
     Object.values(declaration.methods).forEach((method) => collectCallableRefs(method, add));
 }
 export function collectClassPolicyRefs(declaration, add) {
-    for (const policy of [declaration.policies.read, declaration.policies.traverse]) {
+    for (const operation of CLASS_OPERATIONS) {
+        const policy = declaration.policies[operation];
         if (isClassRuleChecks(policy))
             collectPolicyCheckRefs(policy, add);
         else if (typeof policy === 'object')

package/dist/v1/schema/rule.d.ts

@@ -0,0 +1,26 @@
+import type { DiagnosticRule } from '../language/validation/rule.js';
+import type { SchemaDiagnosticCode } from './diagnostic.js';
+/**
+ * What a rule reads to decide. `structure`: the shape of the document alone. `rule`: the whole
+ * document. `context`: the document and its environment, so one document can be accepted in one
+ * environment and refused in another. The environment is what the lookup serves for the pinned
+ * dependencies, their accepted Schemas or their absence, and, for a Schema already accepted, the
+ * closure its acceptance retained.
+ */
+export type SchemaRuleStage = 'structure' | 'rule' | 'context';
+/**
+ * The rule one Schema diagnostic code reports. A final `{/path*}` of its positions stands for any
+ * further tokens; `{endpoint}` is `source`, `target`, `0` or `1`; `{count}` is `outgoing`,
+ * `incoming` or `incident`; `{operation}` is `read` or `traverse`; `{key}` is a Property key. A
+ * condition is a fragment such as `#/$defs/edge-class/if`.
+ */
+export interface SchemaRule extends DiagnosticRule {
+    readonly stage: SchemaRuleStage;
+    /** What the feature the rule guards enforces on data or on calls, where it enforces something. */
+    readonly enforces?: string;
+}
+/**
+ * Every Schema diagnostic code with the rule it reports. A code added to the DSL does not compile
+ * until it is described here.
+ */
+export declare const RULES: Readonly<Record<SchemaDiagnosticCode, SchemaRule>>;