@astrale-os/kernel-dsl 0.1.5 → 0.2.0-beta.10

package/dist/v1/builder/lowering/core-properties.d.ts

@@ -0,0 +1,10 @@
+import type { CoreContent } from '../../language/core/model/core.js';
+import type { DomainSchemaLookup } from '../../schema/dependency/lookup.js';
+import type { DomainSchemaIR } from '../../schema/model/schema.js';
+import type { UnqualifiedCoreContent } from './core.js';
+type UnqualifiedDomainSchema = Omit<DomainSchemaIR, 'core'> & {
+    readonly core: UnqualifiedCoreContent;
+};
+/** Lower rich builder shorthand to the canonical full-key Core representation. */
+export declare function canonicalizeCorePropertyKeys(candidate: UnqualifiedDomainSchema, lookup: DomainSchemaLookup): CoreContent;
+export {};

package/dist/v1/builder/lowering/core-properties.js

@@ -0,0 +1,76 @@
+import { PropertyKey as admitPropertyKey } from '../../addressing/index.js';
+import { definitionRefIndex } from '../../addressing/ordering.js';
+import { createPropertyValues } from '../../language/class/property-values.js';
+import { analyzeDefinitions } from '../../schema/analysis/class.js';
+import { buildDomainResolutionContext } from '../../schema/resolution/context.js';
+import { escapeToken, fail } from '../schema/diagnostic.js';
+/** Lower rich builder shorthand to the canonical full-key Core representation. */
+export function canonicalizeCorePropertyKeys(candidate, lookup) {
+    // Core Property values do not participate in Class composition. Analyze the
+    // already-canonical Definition surface, then admit Core values below.
+    const analysisCandidate = {
+        ...candidate,
+        core: { nodes: {}, edges: [] },
+    };
+    const definitions = analyzeDefinitions(buildDomainResolutionContext(analysisCandidate, lookup)).definitions;
+    const nodes = Object.fromEntries(Object.entries(candidate.core.nodes).map(([slug, node]) => {
+        const definition = definitions.get(definitionRefIndex(node.class));
+        if (definition === undefined) {
+            fail('BUILDER_CORE_PROPERTY', `/core/nodes/${escapeToken(slug)}/class`, 'Core property shorthand requires a resolvable concrete Class.');
+        }
+        return [
+            slug,
+            {
+                ...node,
+                properties: qualify(node.properties, definition, `/core/nodes/${escapeToken(slug)}/properties`),
+            },
+        ];
+    }));
+    const edges = candidate.core.edges.map((edge, index) => {
+        const definition = definitions.get(definitionRefIndex(edge.class));
+        if (definition === undefined) {
+            fail('BUILDER_CORE_PROPERTY', `/core/edges/${index}/class`, 'Core property shorthand requires a resolvable concrete Class.');
+        }
+        return {
+            ...edge,
+            properties: qualify(edge.properties, definition, `/core/edges/${index}/properties`),
+        };
+    });
+    return { nodes, edges };
+}
+function qualify(input, definition, pointer) {
+    const byName = new Map();
+    for (const [key, field] of definition.properties) {
+        const candidates = byName.get(field.name) ?? [];
+        candidates.push(key);
+        byName.set(field.name, candidates);
+    }
+    const result = {};
+    const sourceByKey = new Map();
+    for (const [inputKey, value] of Object.entries(input)) {
+        const key = resolveInputKey(inputKey, definition, byName, `${pointer}/${escapeToken(inputKey)}`);
+        const previous = sourceByKey.get(key);
+        if (previous !== undefined) {
+            fail('BUILDER_CORE_PROPERTY', `${pointer}/${escapeToken(inputKey)}`, `Property is supplied twice through ${JSON.stringify(previous)} and ${JSON.stringify(inputKey)}.`);
+        }
+        sourceByKey.set(key, inputKey);
+        result[key] = value;
+    }
+    return createPropertyValues(Object.entries(result).map(([key, value]) => [admitPropertyKey(key), value]));
+}
+function resolveInputKey(input, definition, byName, pointer) {
+    if (admitPropertyKey.is(input)) {
+        const key = admitPropertyKey(input);
+        if (!definition.properties.has(key)) {
+            fail('BUILDER_CORE_PROPERTY', pointer, `Property ${input} is not present on the Core Class.`);
+        }
+        return key;
+    }
+    const candidates = byName.get(input) ?? [];
+    if (candidates.length === 1)
+        return candidates[0];
+    if (candidates.length === 0) {
+        fail('BUILDER_CORE_PROPERTY', pointer, `Property ${JSON.stringify(input)} does not exist.`);
+    }
+    fail('BUILDER_CORE_PROPERTY', pointer, `Property ${JSON.stringify(input)} is ambiguous; use one of: ${candidates.join(', ')}.`);
+}

package/dist/v1/builder/lowering/core.d.ts

@@ -0,0 +1,22 @@
+import type { Object as JsonObject } from '@astrale-os/kernel-dsl/value';
+import type { ClassRef, CoreRef } from '../../addressing/index.js';
+import type { CoreEndpointRef } from '../../language/core/model/core.js';
+import type { CoreInput } from '../core/authoring.js';
+import type { BuilderContext } from './schema/context.js';
+export declare function captureCore(input: CoreInput | undefined, context: BuilderContext): void;
+export interface UnqualifiedCoreDefinition {
+    readonly ref: CoreRef;
+    readonly class: ClassRef;
+    readonly properties: JsonObject;
+}
+export interface UnqualifiedCoreEdge {
+    readonly class: ClassRef;
+    readonly source: CoreEndpointRef;
+    readonly target: CoreEndpointRef;
+    readonly properties: JsonObject;
+}
+export interface UnqualifiedCoreContent {
+    readonly nodes: Readonly<Record<string, UnqualifiedCoreDefinition>>;
+    readonly edges: readonly UnqualifiedCoreEdge[];
+}
+export declare function compileCore(input: CoreInput | undefined, context: BuilderContext): UnqualifiedCoreContent;

package/dist/v1/builder/lowering/core.js

@@ -0,0 +1,50 @@
+import { coreEdgeConfiguration, coreNodeConfiguration } from '../core/authoring.js';
+import { escapeToken, fail } from '../schema/diagnostic.js';
+import { isAuthoringValue } from '../schema/handle.js';
+export function captureCore(input, context) {
+    for (const [slug, node] of Object.entries(input?.nodes ?? {})) {
+        if (!isAuthoringValue(node, 'core-node')) {
+            fail('BUILDER_CORE_NODE', `/core/nodes/${escapeToken(slug)}`, 'core.nodes entries are created by node(...).');
+        }
+        context.captureCoreNode(node, slug, `/core/nodes/${escapeToken(slug)}`);
+    }
+}
+export function compileCore(input, context) {
+    const nodes = Object.fromEntries(Object.entries(input?.nodes ?? {}).map(([slug, value]) => [
+        slug,
+        compileNode(slug, value, context, `/core/nodes/${escapeToken(slug)}`),
+    ]));
+    const edges = (input?.edges ?? []).map((value, index) => compileEdge(value, context, `/core/edges/${index}`));
+    return { nodes, edges };
+}
+function compileNode(slug, value, context, pointer) {
+    const configuration = coreNodeConfiguration(value);
+    const ref = context.resolveNodeClass(configuration.class, `${pointer}/class`);
+    if (ref.origin !== context.origin) {
+        fail('BUILDER_CORE_CLASS', `${pointer}/class`, 'A Core Node Class must be local to the owning Domain.');
+    }
+    return {
+        ref: { origin: context.origin, kind: 'core', name: slug },
+        class: ref,
+        properties: configuration.properties,
+    };
+}
+function compileEdge(value, context, pointer) {
+    if (!isAuthoringValue(value, 'core-edge')) {
+        fail('BUILDER_CORE_EDGE', pointer, 'core.edges entries are created by edge(...).');
+    }
+    const configuration = coreEdgeConfiguration(value);
+    const ref = context.resolveEdgeClass(configuration.class, `${pointer}/class`);
+    if (ref.origin !== context.origin) {
+        fail('BUILDER_CORE_CLASS', `${pointer}/class`, 'A Core Edge Class must be local to the owning Domain.');
+    }
+    return {
+        class: ref,
+        source: resolveEndpoint(configuration.source, context, `${pointer}/source`),
+        target: resolveEndpoint(configuration.target, context, `${pointer}/target`),
+        properties: configuration.properties,
+    };
+}
+function resolveEndpoint(value, context, pointer) {
+    return context.resolveCoreEndpoint(value, pointer);
+}

package/dist/v1/builder/lowering/policy.d.ts

@@ -0,0 +1,16 @@
+import type { PolicyRef } from '../../addressing/index.js';
+import type { PolicyDefinition } from '../../language/policy/model/policy.js';
+import type { Policy } from '../policy/authoring.js';
+import type { Lazy } from '../schema/lazy.js';
+import type { BuilderContext } from './schema/context.js';
+export interface PolicyCompiler {
+    compile(value: Policy, name: string, pointer: string): PolicyDefinition;
+    ref(value: Lazy<unknown>, pointer: string): PolicyRef;
+}
+export declare class V1PolicyCompiler implements PolicyCompiler {
+    readonly context: BuilderContext;
+    constructor(context: BuilderContext);
+    ref(value: Lazy<unknown>, pointer: string): PolicyRef;
+    compile(value: Policy, name: string, pointer: string): PolicyDefinition;
+}
+export declare function assertPolicyCompositionAcyclic(declarations: Readonly<Record<string, PolicyDefinition>>, origin: string): void;

package/dist/v1/builder/lowering/policy.js

@@ -0,0 +1,59 @@
+import { normalizePolicyExpression } from '../../language/policy/normalization/normalize.js';
+import { createPatternContext, policyDeclaration } from '../policy/authoring.js';
+import { fail } from '../schema/diagnostic.js';
+export class V1PolicyCompiler {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    ref(value, pointer) {
+        return this.context.resolvePolicy(value, pointer);
+    }
+    compile(value, name, pointer) {
+        const input = policyDeclaration(value);
+        const ref = { origin: this.context.origin, kind: 'policy', name };
+        if ('operator' in input) {
+            const refs = input.policies.map((policy, index) => this.context.resolvePolicy(policy, `${pointer}/${input.operator}/${index}`));
+            return {
+                ref,
+                expression: normalizePolicyExpression(input.operator === 'allOf' ? { allOf: refs } : { anyOf: refs }),
+            };
+        }
+        const match = input.match(createPatternContext({
+            resolveEdgeClass: (definition, refPointer) => this.context.resolveEdgeClass(definition, refPointer),
+            resolveNodeClass: (definition, refPointer) => this.context.resolveNodeClass(definition, refPointer),
+            pointer,
+        }));
+        return {
+            ref,
+            ...(input.description === undefined ? {} : { description: input.description }),
+            expression: normalizePolicyExpression({ match }),
+        };
+    }
+}
+export function assertPolicyCompositionAcyclic(declarations, origin) {
+    const visiting = new Set();
+    const visited = new Set();
+    const visit = (name) => {
+        if (visiting.has(name)) {
+            fail('BUILDER_POLICY_CYCLE', `/policies/${name}`, `Policy composition cycle reaches ${origin}:policy.${name}.`);
+        }
+        if (visited.has(name))
+            return;
+        visiting.add(name);
+        const declaration = declarations[name];
+        const expression = declaration?.expression;
+        const refs = expression !== undefined && 'allOf' in expression
+            ? expression.allOf
+            : expression !== undefined && 'anyOf' in expression
+                ? expression.anyOf
+                : [];
+        for (const ref of refs)
+            if (ref.origin === origin)
+                visit(ref.name);
+        visiting.delete(name);
+        visited.add(name);
+    };
+    for (const name of Object.keys(declarations))
+        visit(name);
+}

package/dist/v1/builder/lowering/schema/capture.d.ts

@@ -0,0 +1,4 @@
+import type { DomainSchemaInput } from '../../schema/input.js';
+import { BuilderContext } from './context.js';
+export declare function captureSchema(input: DomainSchemaInput, context: BuilderContext): void;
+export declare function commitSchemaOwnership(input: DomainSchemaInput, origin: string): void;

package/dist/v1/builder/lowering/schema/capture.js

@@ -0,0 +1,70 @@
+import { MethodKey } from '../../../addressing/index.js';
+import { classConfiguration } from '../../class/authoring.js';
+import { escapeToken, fail } from '../../schema/diagnostic.js';
+import { isAuthoringValue } from '../../schema/handle.js';
+import { captureCore } from '../core.js';
+import { BuilderContext } from './context.js';
+export function captureSchema(input, context) {
+    captureDefinitions(input.classes ?? {}, context);
+    capturePolicies(input.policies ?? {}, context);
+    captureExecutables(input, context);
+    captureCore(input.core, context);
+}
+export function commitSchemaOwnership(input, origin) {
+    const context = new BuilderContext(origin, input.dependencies ?? {});
+    captureSchema(input, context);
+    context.ownership.commit();
+}
+function captureDefinitions(classes, context) {
+    for (const [name, value] of Object.entries(classes)) {
+        assertDefinition(value, `/classes/${escapeToken(name)}`);
+        context.captureDefinition(value, { origin: context.origin, kind: 'class', name }, `/classes/${escapeToken(name)}`);
+    }
+}
+function capturePolicies(policies, context) {
+    for (const [name, value] of Object.entries(policies)) {
+        if (!isAuthoringValue(value, 'policy')) {
+            fail('BUILDER_POLICY', `/policies/${escapeToken(name)}`, 'Policies are created by policy(...).');
+        }
+        context.capturePolicy(value, { origin: context.origin, kind: 'policy', name }, `/policies/${escapeToken(name)}`);
+    }
+}
+function captureExecutables(input, context) {
+    for (const [name, value] of Object.entries(input.functions ?? {})) {
+        const pointer = `/functions/${escapeToken(name)}`;
+        assertFunction(value, pointer);
+        context.captureFunction(value, { origin: context.origin, kind: 'function', name }, pointer);
+    }
+    for (const [definitionName, definition] of Object.entries(input.classes ?? {})) {
+        if (definition.kind !== 'node')
+            continue;
+        const methods = classConfiguration(definition).methods;
+        for (const [methodName, method] of Object.entries(methods ?? {})) {
+            const pointer = `/classes/${escapeToken(definitionName)}/methods/${escapeToken(methodName)}`;
+            assertMethod(method, pointer);
+            context.ownership.capture(method, MethodKey.of({ origin: context.origin, kind: 'class', name: definitionName }, methodName), pointer);
+        }
+    }
+    for (const [name, value] of Object.entries(input.views ?? {})) {
+        const pointer = `/views/${escapeToken(name)}`;
+        if (!isAuthoringValue(value, 'view')) {
+            fail('BUILDER_VIEW', pointer, 'Views are created by view(...).');
+        }
+        context.captureView(value, { origin: context.origin, kind: 'view', name }, pointer);
+    }
+}
+function assertDefinition(value, pointer) {
+    if (!isAuthoringValue(value, 'definition')) {
+        fail('BUILDER_DEFINITION', pointer, 'Definitions are created by a V1 Definition builder.');
+    }
+}
+function assertFunction(value, pointer) {
+    if (!isAuthoringValue(value, 'function')) {
+        fail('BUILDER_FUNCTION', pointer, 'Functions are created by func(...).');
+    }
+}
+function assertMethod(value, pointer) {
+    if (!isAuthoringValue(value, 'method')) {
+        fail('BUILDER_METHOD', pointer, 'Methods are created by method(...).');
+    }
+}

package/dist/v1/builder/lowering/schema/compile.d.ts

@@ -0,0 +1,10 @@
+import type { DomainSchema } from '../../../schema/model/schema.js';
+import type { DomainSchemaInput } from '../../schema/input.js';
+import type { ResolvedDomainOfInput } from '../../schema/projection.js';
+/**
+ * Compile the V1 TypeScript builder graph through the same semantic acceptance
+ * path used for untrusted decoded schemas.
+ *
+ * This is the private implementation behind defineSchema.
+ */
+export declare function compileSchema<const Origin extends string, const Input extends DomainSchemaInput>(origin: Origin, input: Input): DomainSchema<Origin, ResolvedDomainOfInput<Origin, Input>>;

package/dist/v1/builder/lowering/schema/compile.js

@@ -0,0 +1,80 @@
+import { acceptDomainSchema } from '../../../schema/admission/accept.js';
+import { canonicalizeDomainSchema } from '../../../schema/canonical/domain.js';
+import { deepFreeze } from '../../../schema/canonical/freeze.js';
+import { MemoryDomainSchemaLookup } from '../../../schema/dependency/lookup.js';
+import { lookupEntriesForDependencies } from '../../../schema/resolution/closure.js';
+import { parseDomainSchemaStructure } from '../../../schema/validation/domain.structure.js';
+import { assertKnownKeys, escapeToken } from '../../schema/diagnostic.js';
+import { V1CallableCompiler } from '../callable.js';
+import { V1DefinitionCompiler } from '../class.js';
+import { canonicalizeCorePropertyKeys } from '../core-properties.js';
+import { compileCore } from '../core.js';
+import { assertPolicyCompositionAcyclic, V1PolicyCompiler } from '../policy.js';
+import { BuilderValueSchemas } from '../value/compile.js';
+import { V1ViewCompiler } from '../view.js';
+import { captureSchema, commitSchemaOwnership } from './capture.js';
+import { BuilderContext } from './context.js';
+/**
+ * Compile the V1 TypeScript builder graph through the same semantic acceptance
+ * path used for untrusted decoded schemas.
+ *
+ * This is the private implementation behind defineSchema.
+ */
+export function compileSchema(origin, input) {
+    const lookup = new MemoryDomainSchemaLookup(lookupEntriesForDependencies(input.dependencies ?? {}));
+    const candidate = assembleDomainSchema(origin, input, lookup);
+    const accepted = acceptDomainSchema(candidate, lookup);
+    commitSchemaOwnership(input, origin);
+    return accepted;
+}
+/** Structural assembly before whole-Domain semantic acceptance. */
+function assembleDomainSchema(origin, input, lookup) {
+    assertKnownKeys(input, ['dependencies', 'classes', 'functions', 'policies', 'views', 'core']);
+    if (input.core !== undefined)
+        assertKnownKeys(input.core, ['nodes', 'edges'], '/core');
+    const context = new BuilderContext(origin, input.dependencies ?? {});
+    captureSchema(input, context);
+    const values = new BuilderValueSchemas(context);
+    const policyCompiler = new V1PolicyCompiler(context);
+    const callableCompiler = new V1CallableCompiler(context, values);
+    const definitionCompiler = new V1DefinitionCompiler(context, values, callableCompiler, policyCompiler);
+    const viewCompiler = new V1ViewCompiler(context);
+    const classes = mapRecord(input.classes ?? {}, (value, name) => definitionCompiler.compileClass(value, name, `/classes/${escapeToken(name)}`));
+    const functions = mapRecord(input.functions ?? {}, (value, name) => callableCompiler.compile(value, {
+        kind: 'function',
+        ref: { origin, kind: 'function', name },
+        pointer: `/functions/${escapeToken(name)}`,
+    }));
+    const policies = mapRecord(input.policies ?? {}, (value, name) => policyCompiler.compile(value, name, `/policies/${escapeToken(name)}`));
+    assertPolicyCompositionAcyclic(policies, origin);
+    const views = mapRecord(input.views ?? {}, (value, name) => viewCompiler.compile(value, name, `/views/${escapeToken(name)}`));
+    const core = compileCore(input.core, context);
+    const semanticContent = {
+        format: 'astrale.dsl',
+        version: 'v1',
+        origin,
+        // Class/Property resolution needs every dependency already referenced by
+        // authored Definitions. Core endpoint refs are added immediately below.
+        dependencies: context.dependencies(),
+        classes,
+        functions,
+        policies,
+        views,
+        core,
+    };
+    const qualifiedContent = {
+        ...semanticContent,
+        core: canonicalizeCorePropertyKeys(semanticContent, lookup),
+    };
+    context.noteDomainEndpointReferences(qualifiedContent);
+    const candidate = {
+        ...qualifiedContent,
+        dependencies: context.dependencies(),
+    };
+    const structured = parseDomainSchemaStructure(candidate);
+    const canonical = parseDomainSchemaStructure(canonicalizeDomainSchema(structured));
+    return deepFreeze(canonical);
+}
+function mapRecord(record, map) {
+    return Object.fromEntries(Object.entries(record).map(([name, value]) => [name, map(value, name)]));
+}

package/dist/v1/builder/lowering/schema/context.d.ts

@@ -0,0 +1,44 @@
+import type { CoreRef, ClassRef, DefinitionRef, FunctionRef, PolicyRef, ViewRef } from '../../../addressing/index.js';
+import type { DomainDependency } from '../../../addressing/index.js';
+import type { ClassKind } from '../../../language/class/model/class.js';
+import type { CoreEndpointRef } from '../../../language/core/model/core.js';
+import type { PolicyObjectRef } from '../../../language/policy/model/policy.js';
+import type { ValueSchemaRegistry } from '../../../language/value/reference/registry.js';
+import type { DomainSchema, DomainSchemaIR } from '../../../schema/model/schema.js';
+import type { Function, PolicyObjectInput } from '../../callable/authoring.js';
+import type { Class, ClassReferenceInput } from '../../class/authoring.js';
+import type { CoreNode } from '../../core/authoring.js';
+import type { Policy } from '../../policy/authoring.js';
+import type { View } from '../../view/authoring.js';
+import { type Lazy } from '../../schema/lazy.js';
+import { OwnershipCapture } from './ownership.js';
+export declare class BuilderContext {
+    #private;
+    readonly origin: string;
+    readonly ownership: OwnershipCapture;
+    readonly localDefinitions: Map<string, DefinitionRef<import("../../../addressing/definition-ref.js").Definition.Kind, string>>;
+    readonly localClassKinds: Map<string, ClassKind>;
+    readonly policies: Map<object, PolicyRef>;
+    readonly coreNodes: Map<CoreNode, CoreRef>;
+    readonly policyObjects: Map<object, PolicyObjectRef>;
+    readonly policyObjectRefs: Set<string>;
+    readonly usedForeignOrigins: Set<string>;
+    constructor(origin: string, dependencies: Readonly<Record<string, DomainSchema>>);
+    captureDefinition(value: Class, ref: ClassRef, pointer: string): void;
+    capturePolicy(value: Policy, ref: PolicyRef, pointer: string): void;
+    captureCoreNode(value: CoreNode, slug: string, pointer: string): void;
+    captureFunction(value: Function, ref: FunctionRef, pointer: string): void;
+    captureView(value: View, ref: ViewRef, pointer: string): void;
+    resolveClass(input: ClassReferenceInput, kind: ClassKind, pointer: string): ClassRef;
+    resolveNodeClass(input: ClassReferenceInput, pointer: string): ClassRef;
+    resolveEdgeClass(input: ClassReferenceInput, pointer: string): ClassRef;
+    resolvePolicy(input: Lazy<unknown>, pointer: string): PolicyRef;
+    resolvePolicyObject(input: PolicyObjectInput | PolicyObjectRef, pointer: string): PolicyObjectRef;
+    resolveCoreEndpoint(value: CoreNode | CoreEndpointRef, pointer: string): CoreEndpointRef;
+    dependencies(): Readonly<Record<string, DomainDependency>>;
+    valueRegistry(): ValueSchemaRegistry;
+    noteDomainEndpointReferences(schema: DomainSchemaIR): void;
+    private assertVisible;
+    private classKind;
+    private capturePolicyObject;
+}