@astrale-os/kernel-dsl 0.2.0-beta.4 → 0.2.0-beta.41

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

@@ -0,0 +1,277 @@
+import { compareDefinitionRefs, compareUnicode, definitionRefIndex, } from '../../../addressing/ordering.js';
+import { DEPENDENCY_ALIAS_PATTERN } from '../../../addressing/patterns.js';
+import { isMethodExecutable } from '../../../language/callable/executable.js';
+import { policyObjectKey, policyObjectOrigin } from '../../../language/index.js';
+import { graphNodePathSchema } from '../../../language/value/syntax/node-path/schema.js';
+import { revisionOfDomainSchema } from '../../../schema/canonical/revision.js';
+import { requireDomainClosure } from '../../../schema/resolution/closure.js';
+import { collectUsedForeignOrigins } from '../../../schema/resolution/origins.js';
+import { fail } from '../../schema/diagnostic.js';
+import { resolveLazy } from '../../schema/lazy.js';
+import { OwnershipCapture } from './ownership.js';
+export class BuilderContext {
+    origin;
+    ownership = new OwnershipCapture();
+    localDefinitions = new Map();
+    localClassKinds = new Map();
+    policies = new Map();
+    policyObjects = new Map();
+    policyObjectRefs = new Set();
+    usedForeignOrigins = new Set();
+    #dependencies = new Map();
+    constructor(origin, dependencies) {
+        this.origin = origin;
+        for (const [alias, schema] of Object.entries(dependencies)) {
+            const pointer = `/dependencies/${escapePointer(alias)}`;
+            if (!DEPENDENCY_ALIAS_PATTERN.test(alias)) {
+                fail('BUILDER_DEPENDENCY_ALIAS', pointer, `Dependency alias ${JSON.stringify(alias)} must be an ASCII lower-camel identifier.`);
+            }
+            if (alias === '__proto__' || alias === 'prototype' || alias === 'constructor') {
+                fail('BUILDER_DEPENDENCY_ALIAS', pointer, `Dependency alias ${JSON.stringify(alias)} is reserved.`);
+            }
+            const dependency = {
+                origin: schema.origin,
+                revision: revisionOfDomainSchema(schema),
+            };
+            const previous = this.#dependencies.get(schema.origin);
+            if (previous !== undefined) {
+                fail('BUILDER_DEPENDENCY_CONFLICT', pointer, `Dependency origin ${schema.origin} is already declared as alias ${previous.alias}.`);
+            }
+            this.#dependencies.set(schema.origin, { alias, schema, dependency });
+        }
+    }
+    captureDefinition(value, ref, pointer) {
+        const key = definitionRefIndex(ref);
+        if (this.localDefinitions.has(key)) {
+            fail('BUILDER_DUPLICATE_MEMBER', pointer, `Definition ${ref.kind}.${ref.name} is duplicated.`);
+        }
+        this.localDefinitions.set(key, ref);
+        this.localClassKinds.set(key, value.kind);
+        this.ownership.captureDefinition(value, ref, pointer);
+        this.capturePolicyObject(value, ref);
+    }
+    capturePolicy(value, ref, pointer) {
+        this.ownership.captureDefinition(value, ref, pointer);
+        this.policies.set(value, ref);
+        this.capturePolicyObject(value, ref);
+    }
+    captureCoreNode(value, slug, pointer) {
+        const ref = { origin: this.origin, kind: 'core', name: slug };
+        this.ownership.captureDefinition(value, ref, pointer);
+        this.capturePolicyObject(value, ref);
+    }
+    captureFunction(value, ref, pointer) {
+        this.ownership.captureDefinition(value, ref, pointer);
+        this.capturePolicyObject(value, ref);
+    }
+    captureView(value, ref, pointer) {
+        this.ownership.captureDefinition(value, ref, pointer);
+        this.capturePolicyObject(value, ref);
+    }
+    resolveClass(input, kind, pointer) {
+        const value = resolveLazy(input, pointer);
+        const ref = isDefinitionRef(value)
+            ? value
+            : isResolvedClass(value)
+                ? value.ref
+                : typeof value === 'object' && value !== null
+                    ? this.ownership.definition(value)
+                    : undefined;
+        if (ref === undefined) {
+            fail('BUILDER_UNOWNED_REFERENCE', pointer, 'Definition reference has no captured Domain owner.');
+        }
+        if (ref.kind !== 'class') {
+            fail('BUILDER_REFERENCE_KIND', pointer, `Expected class, received ${ref.kind}.`);
+        }
+        this.assertVisible(ref, pointer);
+        const resolvedKind = this.classKind(ref);
+        if (resolvedKind !== kind) {
+            fail('BUILDER_REFERENCE_KIND', pointer, `Expected ${kind} Class, received ${resolvedKind ?? 'an unresolved Class'}.`);
+        }
+        return { ...ref };
+    }
+    resolveNodeClass(input, pointer) {
+        return this.resolveClass(input, 'node', pointer);
+    }
+    resolveEdgeClass(input, pointer) {
+        return this.resolveClass(input, 'edge', pointer);
+    }
+    resolvePolicy(input, pointer) {
+        const value = resolveLazy(input, pointer);
+        if (typeof value !== 'object' || value === null) {
+            fail('BUILDER_UNOWNED_REFERENCE', pointer, 'Policy reference has no captured local owner.');
+        }
+        const ref = this.policies.get(value);
+        if (ref === undefined) {
+            fail('BUILDER_FOREIGN_POLICY', pointer, 'V1 Policy references must name a local Policy.');
+        }
+        return { ...ref };
+    }
+    resolvePolicyObject(input, pointer) {
+        const ref = this.policyObjectRef(resolveLazy(input, pointer));
+        const origin = ref === undefined ? undefined : policyObjectOrigin(ref);
+        const dependency = origin === undefined ? undefined : this.#dependencies.get(origin)?.schema;
+        const admitted = ref !== undefined &&
+            (origin === this.origin
+                ? this.policyObjectRefs.has(policyObjectKey(ref))
+                : dependency !== undefined && hasPolicyObject(dependency, ref));
+        if (!admitted || ref === undefined) {
+            fail('BUILDER_POLICY_REF', pointer, 'Policy ref(...) must name one registered local or direct-dependency Definition, Function, Method, Policy, View, or Core Node.');
+        }
+        const admittedOrigin = policyObjectOrigin(ref);
+        if (admittedOrigin !== this.origin)
+            this.usedForeignOrigins.add(admittedOrigin);
+        return { ...ref };
+    }
+    /** A Core fact belongs to the Domain that declares it, so a dependency endpoint never resolves. */
+    resolveCoreEndpoint(input, pointer) {
+        const value = resolveLazy(input, pointer);
+        if (isDomainEndpointRef(value))
+            return { kind: 'domain' };
+        const ref = this.policyObjectRef(value);
+        if (ref === undefined ||
+            policyObjectOrigin(ref) !== this.origin ||
+            !this.policyObjectRefs.has(policyObjectKey(ref))) {
+            fail('BUILDER_CORE_REF', pointer, 'A Core Edge endpoint must name one registered local Definition, Function, Method, Policy, View, or Core Node.');
+        }
+        return { ...ref };
+    }
+    /**
+     * The shared lookup from one already-resolved authoring value to its ref; each caller owns its
+     * own admission rule and diagnostic.
+     */
+    policyObjectRef(value) {
+        if (isPolicyObjectRef(value))
+            return value;
+        return typeof value === 'object' && value !== null
+            ? (this.policyObjects.get(value) ?? this.ownership.definition(value))
+            : undefined;
+    }
+    dependencies() {
+        return Object.fromEntries([...this.#dependencies.values()]
+            .sort((left, right) => compareUnicode(left.alias, right.alias))
+            .map(({ alias, dependency }) => [alias, dependency]));
+    }
+    valueRegistry() {
+        const directOrigins = new Set(this.#dependencies.keys());
+        const closure = new Map();
+        for (const { schema } of this.#dependencies.values()) {
+            for (const entry of requireDomainClosure(schema)) {
+                if (!directOrigins.has(entry.schema.origin))
+                    closure.set(entry.schema.origin, entry.schema);
+            }
+        }
+        const registryDomain = (schema, revision) => ({
+            origin: schema.origin,
+            ...(revision === undefined ? {} : { revision }),
+            dependencies: Object.values(schema.dependencies),
+            nodeDefinitions: definitionRefsOf(schema),
+        });
+        return {
+            current: {
+                origin: this.origin,
+                dependencies: [...this.#dependencies.values()].map(({ dependency }) => dependency),
+                nodeDefinitions: [...this.localDefinitions.values()]
+                    .filter((ref) => ref.kind === 'class' && this.localClassKinds.get(definitionRefIndex(ref)) === 'node')
+                    .sort(compareDefinitionRefs),
+            },
+            directDependencies: [...this.#dependencies.values()].map(({ schema, dependency }) => ({
+                ...registryDomain(schema, dependency.revision),
+            })),
+            transitiveDependencies: [...closure.values()].map((schema) => registryDomain(schema, revisionOfDomainSchema(schema))),
+            graphNodePath: graphNodePathSchema,
+        };
+    }
+    noteDomainEndpointReferences(schema) {
+        for (const origin of collectUsedForeignOrigins(schema))
+            this.usedForeignOrigins.add(origin);
+    }
+    assertVisible(ref, pointer) {
+        if (ref.origin === this.origin) {
+            if (!this.localDefinitions.has(definitionRefIndex(ref))) {
+                fail('BUILDER_REFERENCE_MISSING', pointer, `Local Definition ${ref.kind}.${ref.name} is not declared.`);
+            }
+            return;
+        }
+        if (!this.#dependencies.has(ref.origin)) {
+            fail('BUILDER_DEPENDENCY_DIRECT', pointer, `Foreign Definition ${ref.origin}:${ref.kind}.${ref.name} is not in a direct dependency.`);
+        }
+        this.usedForeignOrigins.add(ref.origin);
+    }
+    classKind(ref) {
+        if (ref.origin === this.origin)
+            return this.localClassKinds.get(definitionRefIndex(ref));
+        const schema = this.#dependencies.get(ref.origin)?.schema;
+        if (schema === undefined)
+            return undefined;
+        return schema.classes[ref.name]?.kind;
+    }
+    capturePolicyObject(value, ref) {
+        this.policyObjects.set(value, ref);
+        this.policyObjectRefs.add(policyObjectKey(ref));
+    }
+}
+function escapePointer(value) {
+    return value.replaceAll('~', '~0').replaceAll('/', '~1');
+}
+function isResolvedClass(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return isDefinitionRef(candidate.ref) && (candidate.kind === 'node' || candidate.kind === 'edge');
+}
+function isDomainEndpointRef(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return candidate.kind === 'domain' && Object.keys(candidate).length === 1;
+}
+function isDefinitionRef(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return (typeof candidate.origin === 'string' &&
+        typeof candidate.name === 'string' &&
+        candidate.kind === 'class');
+}
+function isPolicyObjectRef(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    if (candidate.kind === 'method')
+        return isDefinitionRef(candidate.owner) && typeof candidate.name === 'string';
+    return (typeof candidate.origin === 'string' &&
+        typeof candidate.name === 'string' &&
+        (candidate.kind === 'class' ||
+            candidate.kind === 'function' ||
+            candidate.kind === 'policy' ||
+            candidate.kind === 'view' ||
+            candidate.kind === 'core'));
+}
+function definitionRefsOf(schema) {
+    const refs = [];
+    for (const [name, declaration] of Object.entries(schema.classes)) {
+        if (declaration.kind === 'node')
+            refs.push({ origin: schema.origin, kind: 'class', name });
+    }
+    return refs.sort(compareDefinitionRefs);
+}
+function hasPolicyObject(schema, ref) {
+    switch (ref.kind) {
+        case 'method': {
+            const owner = schema.classes[ref.owner.name];
+            const method = owner?.kind === 'node' ? owner.methods[ref.name] : undefined;
+            return method !== undefined && isMethodExecutable(owner, method);
+        }
+        case 'class':
+            return Object.hasOwn(schema.classes, ref.name);
+        case 'function':
+            return Object.hasOwn(schema.functions, ref.name);
+        case 'policy':
+            return Object.hasOwn(schema.policies, ref.name);
+        case 'view':
+            return Object.hasOwn(schema.views, ref.name);
+        case 'core':
+            return Object.hasOwn(schema.core.nodes, ref.name);
+    }
+}

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

@@ -0,0 +1,8 @@
+import type { PolicyObjectRef } from '../../../language/index.js';
+export declare class OwnershipCapture {
+    #private;
+    captureDefinition(value: object, ref: PolicyObjectRef, pointer: string): void;
+    capture(value: object, owner: string, pointer: string): void;
+    definition(value: object): PolicyObjectRef | undefined;
+    commit(): void;
+}

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

@@ -0,0 +1,30 @@
+import { policyObjectKey } from '../../../language/index.js';
+import { fail } from '../../schema/diagnostic.js';
+const definitionOwners = new WeakMap();
+const semanticOwners = new WeakMap();
+export class OwnershipCapture {
+    #definitions = new Map();
+    #owners = new Map();
+    captureDefinition(value, ref, pointer) {
+        this.capture(value, policyObjectKey(ref), pointer);
+        this.#definitions.set(value, ref);
+    }
+    capture(value, owner, pointer) {
+        const staged = this.#owners.get(value);
+        const stable = semanticOwners.get(value);
+        const previous = staged ?? stable;
+        if (previous !== undefined && previous !== owner) {
+            fail('BUILDER_AMBIGUOUS_OWNERSHIP', pointer, `One detached builder value cannot be owned by both ${previous} and ${owner}.`);
+        }
+        this.#owners.set(value, owner);
+    }
+    definition(value) {
+        return this.#definitions.get(value) ?? definitionOwners.get(value);
+    }
+    commit() {
+        for (const [value, owner] of this.#owners)
+            semanticOwners.set(value, owner);
+        for (const [value, ref] of this.#definitions)
+            definitionOwners.set(value, ref);
+    }
+}

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

@@ -0,0 +1,15 @@
+import type { PropertyRecord } from '../../../language/class/model/property.js';
+import type { JsonSchema, ValueSchemaContext } from '../../../language/value/model/schema.js';
+import type { ValueSchemaRegistry } from '../../../language/value/reference/registry.js';
+import type { PropertyRecordInput, ValueSchemaInput } from '../../class/property.js';
+import type { BuilderContext } from '../schema/context.js';
+export declare class BuilderValueSchemas {
+    readonly context: BuilderContext;
+    readonly registry: ValueSchemaRegistry;
+    constructor(context: BuilderContext);
+    schema(input: ValueSchemaInput, placement: ValueSchemaContext, pointer: string): JsonSchema;
+    properties(input: PropertyRecordInput | undefined, pointer: string): PropertyRecord;
+    private lower;
+    private resolvePathAccepts;
+    private assertValid;
+}

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

@@ -0,0 +1,143 @@
+import { accept as acceptJsonValue } from '@astrale-os/kernel-dsl/value';
+import { ZodType } from 'zod';
+import { compareDefinitionRefs } from '../../../addressing/ordering.js';
+import { canonicalizeValueSchema } from '../../../language/value/profile/canonicalize.js';
+import { validateValueSchema } from '../../../language/value/profile/validate.js';
+import { autoPropertyAuthoringInput, propertyAuthoringInput } from '../../class/property.js';
+import { BuilderError } from '../../schema/diagnostic.js';
+import { escapeToken, fail } from '../../schema/diagnostic.js';
+import { isAuthoringValue } from '../../schema/handle.js';
+import { lowerPathSchema } from './path.js';
+import { convertZodToValueSchema, zodObjectPropertyIsOptional } from './zod.js';
+export class BuilderValueSchemas {
+    context;
+    registry;
+    constructor(context) {
+        this.context = context;
+        this.registry = context.valueRegistry();
+    }
+    schema(input, placement, pointer) {
+        const schema = this.lower(input, 'callable-output', pointer);
+        this.assertValid(schema, placement, pointer);
+        return canonicalizeValueSchema(schema, placement, this.registry);
+    }
+    properties(input, pointer) {
+        const fields = input ?? {};
+        const compiled = {};
+        for (const [name, value] of Object.entries(fields)) {
+            const auto = isAutoProperty(value) ? value : undefined;
+            const autoInput = auto === undefined ? undefined : autoPropertyAuthoringInput(auto);
+            const authored = autoInput?.property ?? (isProperty(value) ? value : undefined);
+            const authoredInput = authored === undefined ? undefined : propertyAuthoringInput(authored);
+            const propertyPointer = `${pointer}/${escapeToken(name)}`;
+            const schemaInput = authoredInput === undefined ? value : authoredInput.schema;
+            const schema = this.lower(schemaInput, 'callable-output', `${propertyPointer}/schema`, 'object-property');
+            this.assertValid(schema, 'property-facet', `${propertyPointer}/schema`);
+            compiled[name] = {
+                schema: canonicalizeValueSchema(schema, 'property-facet', this.registry),
+                required: authoredInput?.options.required ?? isRequired(schemaInput),
+                ...(autoInput === undefined ? {} : { auto: autoInput.options }),
+                ...(authoredInput?.options.description === undefined
+                    ? {}
+                    : { description: authoredInput.options.description }),
+                ...(authoredInput?.machine === undefined
+                    ? {}
+                    : {
+                        state: {
+                            initial: authoredInput.machine.initial,
+                            transitions: authoredInput.machine.transitions,
+                        },
+                    }),
+            };
+        }
+        return compiled;
+    }
+    lower(input, conversionContext, pointer, zodPosition = 'value') {
+        let schema;
+        if (input instanceof ZodType) {
+            const converted = convertZodToValueSchema(input, conversionContext, this.registry, pointer, {
+                position: zodPosition,
+                validate: false,
+                override: (context) => lowerPathSchema(context, (accepts, markerPointer) => this.resolvePathAccepts(accepts, markerPointer), pointer),
+            });
+            if (!converted.ok)
+                throw new BuilderError(converted.diagnostics);
+            schema = closeZodObjects(converted.schema);
+        }
+        else {
+            schema = acceptJsonValue(input);
+        }
+        return schema;
+    }
+    resolvePathAccepts(inputs, pointer) {
+        const refs = inputs.map((input, index) => this.context.resolveNodeClass(input, `${pointer}/x-astrale-path/accepts/${index}`));
+        const seen = new Set();
+        for (const ref of refs) {
+            const key = `${ref.origin}\u0000${ref.kind}\u0000${ref.name}`;
+            if (seen.has(key)) {
+                fail('BUILDER_PATH_DUPLICATE', `${pointer}/x-astrale-path/accepts`, 'path(...) repeats one Node Definition.');
+            }
+            seen.add(key);
+        }
+        return refs.sort(compareDefinitionRefs);
+    }
+    assertValid(schema, placement, pointer) {
+        const diagnostics = validateValueSchema(schema, placement, this.registry, pointer);
+        if (diagnostics.length > 0)
+            throw new BuilderError(diagnostics);
+    }
+}
+function closeZodObjects(schema) {
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema))
+        return schema;
+    const result = { ...schema };
+    for (const keyword of ['$defs', 'dependentSchemas', 'patternProperties', 'properties']) {
+        const value = result[keyword];
+        if (value === null || typeof value !== 'object' || Array.isArray(value))
+            continue;
+        result[keyword] = Object.fromEntries(Object.entries(value).map(([name, nested]) => [name, closeZodObjects(nested)]));
+    }
+    for (const keyword of ['allOf', 'anyOf', 'oneOf', 'prefixItems']) {
+        const value = result[keyword];
+        if (Array.isArray(value))
+            result[keyword] = value.map((nested) => closeZodObjects(nested));
+    }
+    for (const keyword of [
+        'additionalProperties',
+        'contains',
+        'contentSchema',
+        'else',
+        'if',
+        'items',
+        'not',
+        'propertyNames',
+        'then',
+        'unevaluatedItems',
+        'unevaluatedProperties',
+    ]) {
+        const value = result[keyword];
+        if (typeof value === 'boolean' ||
+            (value !== null && typeof value === 'object' && !Array.isArray(value))) {
+            result[keyword] = closeZodObjects(value);
+        }
+    }
+    if (result.type === 'object' &&
+        result.properties !== null &&
+        typeof result.properties === 'object' &&
+        !Array.isArray(result.properties) &&
+        !Object.hasOwn(result, 'additionalProperties')) {
+        result.additionalProperties = false;
+    }
+    return result;
+}
+function isProperty(value) {
+    return isAuthoringValue(value, 'property');
+}
+function isAutoProperty(value) {
+    return isAuthoringValue(value, 'auto');
+}
+function isRequired(value) {
+    if (!(value instanceof ZodType))
+        return true;
+    return !zodObjectPropertyIsOptional(value);
+}

package/dist/v1/builder/lowering/value/path.d.ts

@@ -0,0 +1,3 @@
+import type { NodeClassReferenceInput } from '../../class/authoring.js';
+import type { ZodValueSchemaOverrideContext } from './zod.js';
+export declare function lowerPathSchema(context: ZodValueSchemaOverrideContext, resolveAccepts: (inputs: readonly NodeClassReferenceInput[], pointer: string) => readonly unknown[], pointer: string): void;

package/dist/v1/builder/lowering/value/path.js

@@ -0,0 +1,20 @@
+import { pathAccepts } from '../../value/path-metadata.js';
+export function lowerPathSchema(context, resolveAccepts, pointer) {
+    const inputs = pathAccepts(context.zodSchema);
+    if (inputs === undefined)
+        return;
+    const location = context.path.reduce((current, segment) => `${current}/${escapeToken(String(segment))}`, pointer);
+    for (const key of Object.keys(context.jsonSchema))
+        delete context.jsonSchema[key];
+    Object.assign(context.jsonSchema, {
+        $ref: 'https://schemas.astrale.ai/graph/1/node-path',
+        'x-astrale-path': {
+            target: 'node',
+            cardinality: 'one',
+            accepts: resolveAccepts(inputs, location),
+        },
+    });
+}
+function escapeToken(value) {
+    return value.replaceAll('~', '~0').replaceAll('/', '~1');
+}

package/dist/v1/builder/lowering/value/zod.d.ts

@@ -0,0 +1,32 @@
+import { ZodType } from 'zod';
+import type { JsonSchema, ValueSchemaContext } from '../../../language/value/model/schema.js';
+import type { ValueSchemaRegistry } from '../../../language/value/reference/registry.js';
+import type { BuilderDiagnostic } from '../../schema/diagnostic.js';
+export type ZodValueSchemaConversion = {
+    readonly ok: true;
+    readonly schema: JsonSchema;
+    readonly diagnostics: readonly [];
+} | {
+    readonly ok: false;
+    readonly diagnostics: readonly BuilderDiagnostic[];
+};
+export interface ZodValueSchemaConversionOptions {
+    /** Undefined is representable only as absence at a containing object-property boundary. */
+    readonly position?: 'value' | 'object-property';
+    /** Builder-only lowering hook keyed by the original Zod schema identity. */
+    readonly override?: (context: ZodValueSchemaOverrideContext) => void;
+    /** The builder validates the lowered schema once its final placement is known. */
+    readonly validate?: boolean;
+}
+export interface ZodValueSchemaOverrideContext {
+    readonly zodSchema: ZodType;
+    readonly jsonSchema: Record<string, unknown>;
+    readonly path: readonly (string | number)[];
+}
+/**
+ * Converts only Zod contracts whose JSON-value acceptance is represented
+ * without coercion, effects, custom predicates, or format assertions.
+ */
+export declare function convertZodToValueSchema(zodSchema: ZodType, context: ValueSchemaContext, registry: ValueSchemaRegistry, pointer?: string, options?: ZodValueSchemaConversionOptions): ZodValueSchemaConversion;
+/** Whether explicit Zod optionality makes a containing object property absent-able. */
+export declare function zodObjectPropertyIsOptional(schema: ZodType): boolean;