@astrale-os/kernel-core 0.9.0-beta.65 → 0.9.0-beta.67

package/dist/schema/kernel/projection/{keys.js → paths.js}

@@ -1,33 +1,32 @@
 import { Path } from '#graph/path';
 import { projectedMethodPath } from './callables.js';
 const encoder = new TextEncoder();
-export function managedKeys(domain) {
-    const keys = new Map();
-    add(keys, Path.domain(domain.origin).raw);
+/** Sorted Paths of the Domain Node, its local Definitions and their executable Methods. */
+export function managedPaths(domain) {
+    const paths = new Set([Path.domain(domain.origin).raw]);
     for (const definition of domain.definitions()) {
         if (definition.ref.origin !== domain.origin || definition.ref.kind === 'core')
             continue;
-        add(keys, Path.project(definition.ref).raw);
+        paths.add(Path.project(definition.ref).raw);
         if (!('methods' in definition) || definition.kind !== 'node')
             continue;
         for (const method of [...definition.methods, ...definition.static.methods]) {
             if (method.owner.ref.origin !== domain.origin || !method.executable) {
                 continue;
             }
-            add(keys, projectedMethodPath(domain, method));
+            paths.add(projectedMethodPath(domain, method));
         }
     }
-    return Object.freeze([...keys.values()].sort(compareNodePaths));
+    return Object.freeze([...paths].sort(compare));
 }
-export function coreKeys(domain) {
+/** Sorted Paths of the Domain's authored Core Nodes. */
+export function corePaths(domain) {
     return Object.freeze(Object.values(domain.core.nodes)
         .map((definition) => Path.project(definition.ref).raw)
-        .sort(compareNodePaths));
+        .sort(compare));
 }
-function add(keys, key) {
-    keys.set(key, key);
-}
-function compareNodePaths(left, right) {
+/** Byte order of the UTF-8 encodings, independent of the host's string collation. */
+function compare(left, right) {
     const a = encoder.encode(left);
     const b = encoder.encode(right);
     const length = Math.min(a.length, b.length);

package/dist/schema/kernel/projection/project.d.ts

@@ -1,4 +1,4 @@
-import { type SourceDomain, type schema } from '@astrale-os/kernel-dsl/v1';
+import type { SourceDomain, schema } from '@astrale-os/kernel-dsl/v1';
 import type { Projection, ProjectionTopology } from './types.js';
 /** Project a Domain into an installation-independent symbolic graph. */
 export declare function project(domain: SourceDomain<schema.DomainSchema>): Projection;

package/dist/schema/kernel/projection/project.js

@@ -1,13 +1,9 @@
-import { Key, } from '@astrale-os/kernel-dsl/v1';
-import { ClassKey as ClassKeyValue } from '@astrale-os/kernel-dsl/v1/addressing';
-import { LocalBinding as LocalBindingValue } from '#graph/graph';
-import { NodePath as NodePathValue, Path as PathValue } from '#graph/path';
-import { normalizeProperties } from '#graph/properties';
-import { K } from '../index.js';
-import { projectedMethodPath } from './callables.js';
-import { ProjectionError } from './diagnostics.js';
-import { coreKeys, managedKeys } from './keys.js';
-const EMPTY_PROPERTIES = normalizeProperties({});
+import { projectCore } from './core.js';
+import { projectDefinitions, projectDomain } from './definitions.js';
+import { projectMethods } from './methods.js';
+import { Part } from './part.js';
+import { corePaths, managedPaths } from './paths.js';
+import { projectRelations } from './relations.js';
 const NO_PAYLOAD = Object.freeze({});
 /** Project a Domain into an installation-independent symbolic graph. */
 export function project(domain) {
@@ -30,289 +26,19 @@ export function project(domain) {
 export function projectTopology(domain) {
     return walk(domain, () => NO_PAYLOAD);
 }
+/** Both projections take the same steps in the same order; only the payload differs. */
 function walk(domain, payload) {
-    // Consume payloads in argument position, before addNode's duplicate/binding checks and
-    // addEdge's Class conversion, preserving the full projection's original error order.
-    const domainSchema = domain.source;
-    const managedLocations = projectionLocations(managedKeys(domain));
-    const coreLocations = projectionLocations(coreKeys(domain));
-    const managedNodes = new Map();
-    const managedEdges = [];
-    const coreNodes = new Map();
-    const coreEdges = [];
-    const locators = [];
-    const domainPath = PathValue.domain(domain.origin).raw;
-    const domainEndpoint = endpoint(domainPath, managedLocations);
-    const persistedDomainEndpoint = Object.freeze({ path: NodePathValue(domainPath) });
-    addNode(managedNodes, domainPath, ClassKeyValue.of(K.classes.Domain.ref), payload(() => domainPropertiesFor(domain)), managedLocations);
-    for (const definition of domain.definitions()) {
-        if (definition.ref.origin !== domain.origin)
-            continue;
-        const projectedClass = projectionClassFor(definition);
-        if (projectedClass === undefined)
-            continue;
-        const definitionPath = PathValue.project(definition.ref).raw;
-        const definitionEndpoint = addNode(managedNodes, definitionPath, projectedClass, payload(() => definitionPropertiesFor(definition)), managedLocations);
-        addEdge(managedEdges, definitionEndpoint, domainEndpoint, K.classes.of_domain.ref, payload(() => normalizeProperties({
-            [K.classes.of_domain.self.properties.member.key]: memberKey(definition),
-        })));
-    }
-    for (const definition of domain.definitions()) {
-        if (definition.ref.origin !== domain.origin)
-            continue;
-        const projectedClass = projectionClassFor(definition);
-        if (projectedClass === undefined)
-            continue;
-        projectDefinitionRelations(domain, definition, endpoint(PathValue.project(definition.ref).raw, managedLocations), managedLocations, managedEdges, payload);
-    }
-    const methods = new Map();
-    for (const definition of Object.values(domain.classes)) {
-        for (const method of [...definition.methods, ...definition.static.methods]) {
-            if (method.owner.ref.origin === domain.origin && method.executable) {
-                methods.set(method.key, method);
-            }
-        }
-    }
-    for (const method of methods.values()) {
-        const methodPath = projectedMethodPath(domain, method);
-        const methodEndpoint = addNode(managedNodes, methodPath, ClassKeyValue.of(K.classes.Function.ref), payload(() => callablePropertiesFor(method.definition)), managedLocations);
-        const ownerPath = PathValue.project(method.owner.ref);
-        addEdge(managedEdges, methodEndpoint, endpoint(ownerPath.raw, managedLocations), K.classes.method_of.ref, payload(() => normalizeProperties({
-            [K.classes.method_of.self.properties.name.key]: method.name,
-            [K.classes.method_of.self.properties.static.key]: method.definition.static,
-        })));
-        // This structural check must also execute when no Property payload is requested.
-        const member = callableMemberKey(domain, method);
-        addEdge(managedEdges, methodEndpoint, domainEndpoint, K.classes.of_domain.ref, payload(() => normalizeProperties({
-            [K.classes.of_domain.self.properties.member.key]: member,
-        })));
-    }
-    for (const [slug, declaration] of Object.entries(domainSchema.core.nodes)) {
-        assertIdentityAuthenticationUnowned(domain, declaration.class, declaration.properties, slug);
-        const path = PathValue.project({ origin: domain.origin, kind: 'core', name: slug }).raw;
-        const created = addNode(coreNodes, path, ClassKeyValue.of(declaration.class), payload(() => declaration.properties), coreLocations);
-        addEdge(locators, created, persistedDomainEndpoint, K.classes.of_domain.ref, payload(() => normalizeProperties({
-            [K.classes.of_domain.self.properties.member.key]: `core.${slug}`,
-        })));
-    }
-    // Resolved edges carry each endpoint's own identity; the source IR only names it.
-    for (const edge of domain.core.edges) {
-        addEdge(coreEdges, coreEndpoint(edge.source, domain, persistedDomainEndpoint, coreLocations), coreEndpoint(edge.target, domain, persistedDomainEndpoint, coreLocations), edge.class.ref, payload(() => edge.properties));
-    }
+    const managed = new Part(managedPaths(domain));
+    const core = new Part(corePaths(domain));
+    const domainEndpoint = projectDomain(domain, managed, payload);
+    projectDefinitions(domain, managed, domainEndpoint, payload);
+    projectRelations(domain, managed, payload);
+    projectMethods(domain, managed, domainEndpoint, payload);
+    const locators = projectCore(domain, core, payload);
     return Object.freeze({
         origin: domain.origin,
         revision: domain.revision,
-        managed: Object.freeze({
-            nodes: Object.freeze([...managedNodes.values()]),
-            edges: Object.freeze(managedEdges),
-            paths: invert(managedLocations),
-        }),
-        core: Object.freeze({
-            nodes: Object.freeze([...coreNodes.values()]),
-            edges: Object.freeze(coreEdges),
-            paths: invert(coreLocations),
-            locators: Object.freeze(locators),
-        }),
+        managed: managed.done(),
+        core: Object.freeze({ ...core.done(), locators: Object.freeze(locators) }),
     });
 }
-function assertIdentityAuthenticationUnowned(domain, classRef, properties, slug) {
-    const definition = domain.definition(classRef);
-    if (definition?.ref.kind !== 'class' ||
-        definition.kind !== 'node' ||
-        !definition.satisfies(K.classes.Identity)) {
-        return;
-    }
-    const hasIssuer = Object.hasOwn(properties, K.classes.Identity.properties.iss.key);
-    const hasSubject = Object.hasOwn(properties, K.classes.Identity.properties.sub.key);
-    if (hasIssuer || hasSubject) {
-        throw new ProjectionError('PROJECTION_INVALID', `Core Identity ${domain.origin}:core.${slug} cannot declare protected Authentication properties iss or sub.`);
-    }
-}
-function projectionLocations(paths) {
-    return new Map(paths.map((path, index) => [NodePathValue(path), LocalBindingValue(`n${index}`)]));
-}
-function invert(locations) {
-    return new Map([...locations].map(([path, binding]) => [binding, path]));
-}
-/**
- * A Core Node binds inside the Core part; every other local Definition is already projected as a
- * managed declaration, so it is addressed by its canonical Path exactly like the owning Domain.
- */
-function coreEndpoint(value, domain, domainEndpoint, locations) {
-    if ('ref' in value)
-        return endpoint(PathValue.project(value.ref).raw, locations);
-    if ('owner' in value)
-        return endpoint(projectedMethodPath(domain, value), locations);
-    return domainEndpoint;
-}
-function projectDefinitionRelations(domain, definition, definitionEndpoint, locations, edges, payload) {
-    if (isResolvedClass(definition)) {
-        for (const parent of definition.definition.extends) {
-            const path = PathValue.project(parent);
-            addEdge(edges, definitionEndpoint, endpoint(path.raw, locations), K.classes.extends.ref, payload(() => EMPTY_PROPERTIES));
-        }
-    }
-    if (isResolvedClass(definition)) {
-        const declaration = definition.definition;
-        const assignments = [
-            ['read', declaration.policies.read],
-            ['traverse', declaration.policies.traverse],
-        ];
-        const policies = new Map();
-        for (const [operation, policy] of assignments) {
-            if (policy === undefined)
-                continue;
-            const key = Key.of(policy);
-            const existing = policies.get(key);
-            if (existing === undefined) {
-                policies.set(key, { policy, operations: new Set([operation]) });
-            }
-            else {
-                existing.operations.add(operation);
-            }
-        }
-        for (const { policy, operations } of policies.values()) {
-            addEdge(edges, definitionEndpoint, endpoint(PathValue.project(policy).raw, locations), K.classes.governed_by.ref, payload(() => normalizeProperties({
-                [K.classes.governed_by.self.properties.operations.key]: Object.freeze(['read', 'traverse'].filter((operation) => operations.has(operation))),
-            })));
-        }
-    }
-    if (isResolvedView(definition)) {
-        const target = definition.definition.target;
-        const paths = target.kind === 'domain'
-            ? [PathValue.domain(domain.origin)]
-            : target.definitions.map((reference) => {
-                if (reference.kind !== 'class') {
-                    throw new ProjectionError('PROJECTION_INVALID', `View target ${reference.origin}:${reference.kind}.${reference.name} is not a Class.`);
-                }
-                return PathValue.project({
-                    origin: reference.origin,
-                    kind: 'class',
-                    name: reference.name,
-                });
-            });
-        for (const path of paths) {
-            addEdge(edges, definitionEndpoint, endpoint(path.raw, locations), K.classes.view_for.ref, payload(() => EMPTY_PROPERTIES));
-        }
-    }
-}
-function projectionClassFor(definition) {
-    if (definition.ref.kind === 'class')
-        return ClassKeyValue.of(K.classes.Class.ref);
-    switch (definition.ref.kind) {
-        case 'function':
-            return ClassKeyValue.of(K.classes.Function.ref);
-        case 'policy':
-            return ClassKeyValue.of(K.classes.Policy.ref);
-        case 'view':
-            return ClassKeyValue.of(K.classes.View.ref);
-        case 'core':
-            return undefined;
-        default:
-            return undefined;
-    }
-}
-function definitionPropertiesFor(definition) {
-    const description = declarationDescription(definition);
-    const metadata = descriptionProperties(description);
-    if (isResolvedClass(definition)) {
-        const declaration = definition.definition;
-        const icon = declaration.kind === 'node' ? declaration.icon : undefined;
-        return normalizeProperties({
-            ...metadata,
-            [K.classes.Class.self.properties.kind.key]: declaration.kind,
-            [K.classes.Class.self.properties.abstract.key]: declaration.abstract,
-            ...(icon !== undefined ? { [K.classes.Iconable.self.properties.icon.key]: icon } : {}),
-        });
-    }
-    if (isResolvedFunction(definition)) {
-        return callablePropertiesFor(definition.definition);
-    }
-    if (definition.ref.kind === 'view') {
-        return normalizeProperties(metadata);
-    }
-    if (definition.ref.kind === 'policy')
-        return normalizeProperties(metadata);
-    return EMPTY_PROPERTIES;
-}
-function isResolvedClass(definition) {
-    return definition.ref.kind === 'class';
-}
-function isResolvedFunction(definition) {
-    return definition.ref.kind === 'function';
-}
-function isResolvedView(definition) {
-    return definition.ref.kind === 'view';
-}
-function callablePropertiesFor(declaration) {
-    const method = 'static' in declaration;
-    return normalizeProperties({
-        ...descriptionProperties(declaration.description),
-        [K.classes.Function.self.properties.kind.key]: method ? 'method' : 'function',
-        [K.classes.Function.self.properties.input.key]: declaration.input,
-        [K.classes.Function.self.properties.output.key]: declaration.output,
-        [K.classes.Function.self.properties.auth.key]: declaration.auth,
-        ...(declaration.policy === undefined
-            ? {}
-            : {
-                [K.classes.Function.self.properties.policy.key]: declaration.policy,
-            }),
-        ...(method
-            ? {
-                [K.classes.Function.self.properties.static.key]: declaration.static,
-                [K.classes.Function.self.properties.abstract.key]: declaration.abstract,
-            }
-            : {}),
-    });
-}
-function descriptionProperties(description) {
-    if (description === undefined)
-        return {};
-    return { [K.classes.Descriptable.self.properties.description.key]: description };
-}
-function declarationDescription(definition) {
-    if (definition.ref.kind === 'core')
-        return undefined;
-    return definition.definition.description;
-}
-function memberKey(definition) {
-    return `${definition.ref.kind}.${definition.ref.name}`;
-}
-function callableMemberKey(domain, method) {
-    const prefix = `${domain.origin}:`;
-    if (!method.key.startsWith(prefix)) {
-        throw new ProjectionError('PROJECTION_INVALID', 'Method key belongs to another Domain.');
-    }
-    return method.key.slice(prefix.length);
-}
-/** Identity properties are supplied atomically by trusted lifecycle materialization. */
-function domainPropertiesFor(domain) {
-    return normalizeProperties({
-        [K.classes.Domain.self.properties.origin.key]: domain.origin,
-        [K.classes.Domain.self.properties.schema.key]: domain.source,
-        [K.classes.Domain.self.properties.schemaRevision.key]: domain.revision,
-    });
-}
-function endpoint(path, locations) {
-    const created = locations.get(path);
-    return created === undefined ? Object.freeze({ path }) : Object.freeze({ created });
-}
-function addNode(nodes, path, classKey, payload, locations) {
-    const existing = nodes.get(path);
-    if (existing !== undefined)
-        return Object.freeze({ created: existing.as });
-    const as = locations.get(path);
-    if (as === undefined) {
-        throw new ProjectionError('PROJECTION_INVALID', `Projection has no binding for ${path}.`);
-    }
-    nodes.set(path, Object.freeze({ as, class: classKey, ...payload }));
-    return Object.freeze({ created: as });
-}
-function addEdge(edges, source, target, classRef, payload) {
-    edges.push(Object.freeze({
-        source,
-        target,
-        class: ClassKeyValue.of(classRef),
-        ...payload,
-    }));
-}

package/dist/schema/kernel/projection/properties.d.ts

@@ -0,0 +1,11 @@
+import type { FunctionDefinition, MethodDefinition } from '@astrale-os/kernel-dsl/v1';
+import type * as portable from '@astrale-os/kernel-dsl/value';
+import { type Properties } from '#graph/properties';
+/** The Properties of a declaration or relation that carries none. */
+export declare const EMPTY_PROPERTIES: import("@astrale-os/kernel-dsl/v1").PropertyValues;
+/** The of_domain Properties locating a declaration under its Domain member name. */
+export declare function memberProperties(member: string): Properties;
+/** The Descriptable Property of an authored description, if any. */
+export declare function descriptionProperties(description: string | undefined): Record<string, portable.Value>;
+/** The Function Node Properties carrying a Function's or Method's complete callable contract. */
+export declare function callableProperties(declaration: FunctionDefinition | MethodDefinition): Properties;

package/dist/schema/kernel/projection/properties.js

@@ -0,0 +1,36 @@
+import { normalizeProperties } from '#graph/properties';
+import { K } from '../index.js';
+/** The Properties of a declaration or relation that carries none. */
+export const EMPTY_PROPERTIES = normalizeProperties({});
+/** The of_domain Properties locating a declaration under its Domain member name. */
+export function memberProperties(member) {
+    return normalizeProperties({ [K.classes.of_domain.self.properties.member.key]: member });
+}
+/** The Descriptable Property of an authored description, if any. */
+export function descriptionProperties(description) {
+    if (description === undefined)
+        return {};
+    return { [K.classes.Descriptable.self.properties.description.key]: description };
+}
+/** The Function Node Properties carrying a Function's or Method's complete callable contract. */
+export function callableProperties(declaration) {
+    const method = 'static' in declaration;
+    return normalizeProperties({
+        ...descriptionProperties(declaration.description),
+        [K.classes.Function.self.properties.kind.key]: method ? 'method' : 'function',
+        [K.classes.Function.self.properties.input.key]: declaration.input,
+        [K.classes.Function.self.properties.output.key]: declaration.output,
+        [K.classes.Function.self.properties.auth.key]: declaration.auth,
+        ...(declaration.policy === undefined
+            ? {}
+            : {
+                [K.classes.Function.self.properties.policy.key]: declaration.policy,
+            }),
+        ...(method
+            ? {
+                [K.classes.Function.self.properties.static.key]: declaration.static,
+                [K.classes.Function.self.properties.abstract.key]: declaration.abstract,
+            }
+            : {}),
+    });
+}

package/dist/schema/kernel/projection/relations.d.ts

@@ -0,0 +1,7 @@
+import { type SourceDomain, type schema } from '@astrale-os/kernel-dsl/v1';
+import { type Part, type Payload } from './part.js';
+/**
+ * Relate each local Definition to its parent Classes and governing Policies, and the entrypoint
+ * View to its Domain.
+ */
+export declare function projectRelations<Extra extends object>(domain: SourceDomain<schema.DomainSchema>, managed: Part<Extra>, payload: Payload<Extra>): void;

package/dist/schema/kernel/projection/relations.js

@@ -0,0 +1,49 @@
+import { Key, } from '@astrale-os/kernel-dsl/v1';
+import { Path } from '#graph/path';
+import { normalizeProperties } from '#graph/properties';
+import { K } from '../index.js';
+import { is, projectedDefinitions } from './definitions.js';
+import { edge } from './part.js';
+import { EMPTY_PROPERTIES } from './properties.js';
+const OPERATIONS = ['read', 'traverse'];
+/**
+ * Relate each local Definition to its parent Classes and governing Policies, and the entrypoint
+ * View to its Domain.
+ */
+export function projectRelations(domain, managed, payload) {
+    for (const [definition] of projectedDefinitions(domain)) {
+        const source = managed.endpoint(Path.project(definition.ref).raw);
+        const relate = (target, classRef, extra) => managed.edges.push(edge(source, managed.endpoint(target), classRef, extra));
+        if (is(definition, 'class')) {
+            for (const parent of definition.definition.extends) {
+                relate(Path.project(parent).raw, K.classes.extends.ref, payload(() => EMPTY_PROPERTIES));
+            }
+            for (const [policy, operations] of governingPolicies(definition)) {
+                relate(Path.project(policy).raw, K.classes.governed_by.ref, payload(() => normalizeProperties({
+                    [K.classes.governed_by.self.properties.operations.key]: operations,
+                })));
+            }
+        }
+        // The one entrypoint View links to its own Domain; other Views relate to it only by of_domain.
+        if (is(definition, 'view') && domain.source.entrypoint?.name === definition.ref.name) {
+            relate(Path.domain(domain.origin).raw, K.classes.entrypoint.ref, payload(() => EMPTY_PROPERTIES));
+        }
+    }
+}
+/** Each distinct Policy of a Class, with the operations it governs in canonical order. */
+function governingPolicies(definition) {
+    const policies = definition.definition.policies;
+    const grouped = new Map();
+    for (const operation of OPERATIONS) {
+        const policy = policies[operation];
+        if (policy === undefined)
+            continue;
+        const key = Key.of(policy);
+        const existing = grouped.get(key);
+        if (existing === undefined)
+            grouped.set(key, { policy, operations: [operation] });
+        else
+            existing.operations.push(operation);
+    }
+    return [...grouped.values()].map(({ policy, operations }) => [policy, Object.freeze(operations)]);
+}

package/dist/schema/kernel/projection/types.d.ts

@@ -1,11 +1,11 @@
 import type { Key, Revision } from '@astrale-os/kernel-dsl/v1';
 import type { ClassKey } from '@astrale-os/kernel-dsl/v1/addressing';
-import type { GraphSpec, GraphSpecEdge, GraphSpecEndpoint, LocalBinding } from '#graph/graph';
+import type { GraphSpec, GraphSpecEdge, GraphSpecEndpoint, LocalAlias } from '#graph/graph';
 import type { NodePath } from '#graph/path';
 export interface ProjectionPart {
     readonly graph: GraphSpec;
     /** Canonical locator of every anonymous Node declared by the projection. */
-    readonly paths: ReadonlyMap<LocalBinding, NodePath>;
+    readonly paths: ReadonlyMap<LocalAlias, NodePath>;
 }
 export interface CoreProjection extends ProjectionPart {
     /** Runtime-owned locator relations that associate authored Core Nodes with their Domain. */
@@ -19,7 +19,7 @@ export interface Projection {
 }
 /** Declaration identity only; this is not a Graph Node with absent or defaulted Properties. */
 export interface ProjectionTopologyNode {
-    readonly as: LocalBinding;
+    readonly as: LocalAlias;
     readonly class: ClassKey;
 }
 export interface ProjectionTopologyEdge {
@@ -28,7 +28,7 @@ export interface ProjectionTopologyEdge {
     readonly class: ClassKey;
 }
 export interface ProjectionTopologyPart {
-    readonly paths: ReadonlyMap<LocalBinding, NodePath>;
+    readonly paths: ReadonlyMap<LocalAlias, NodePath>;
     readonly nodes: readonly ProjectionTopologyNode[];
     readonly edges: readonly ProjectionTopologyEdge[];
 }