@astrale-os/sdk 0.6.0-beta.3 → 0.6.0-beta.30

package/dist/execution/workflows/run.js

@@ -0,0 +1,223 @@
+import { declaredErrorFactory } from '../../application/error/index.js';
+import { bindMutation } from '../../application/mutation/execution/executor.js';
+import { bindQuery } from '../../application/query/execution/executor.js';
+import { acceptStepId } from '../../application/workflow/step/index.js';
+import { acceptStepOutput } from '../../application/workflow/step/output.js';
+import { ResponseError } from '../../platform/client/index.js';
+import { bindSession, execution as executionMethods } from '../../platform/client/session/index.js';
+import { validateOutput } from '../invocation/result/index.js';
+import { decodeEnvelope } from './envelope.js';
+import { replayedFailure, terminalFailure } from './failure.js';
+/** Token of a Workflow that declares none. */
+const DEFAULT_COMPAT = '0';
+const MAXIMUM_SLEEP_MS = 365 * 24 * 60 * 60_000;
+const MAXIMUM_PROMISE_NAME = 128;
+/** Bounds of one `result` wait and of the durable pause between two of them. */
+const AWAIT_WAIT_MS = 10_000;
+const AWAIT_MAXIMUM_PAUSE_MS = 5 * 60_000;
+/** Engine handlers of one durable Workflow: the `run` and the shared `signal`. */
+export function durableHandlers(input) {
+    const { engine } = input.serving;
+    return Object.freeze({
+        run: (context, raw) => run(input, context, raw),
+        async signal(context, raw) {
+            const request = signalRequest(raw);
+            try {
+                await context.promise(request.name).resolve(request.value);
+                return { accepted: true };
+            }
+            catch (cause) {
+                // The engine refuses to resolve a promise twice with a terminal failure.
+                if (cause instanceof engine.TerminalError)
+                    return { accepted: false };
+                throw cause;
+            }
+        },
+    });
+}
+async function run(input, context, raw) {
+    const { workflow, serving } = input;
+    const { engine } = serving;
+    const definition = workflow.definition;
+    // Journaled first. A redeployment that changed the token cannot replay this run: it fails every
+    // attempt with this reason until the engine pauses it, then `resume` on compatible code or cancel.
+    const token = definition.compat ?? DEFAULT_COMPAT;
+    const recorded = await context.run('compat', async () => token);
+    if (recorded !== token) {
+        throw new Error(`Workflow ${workflow.address} started under compat token ${JSON.stringify(recorded)}; ` +
+            `this deployment declares ${JSON.stringify(token)}.`);
+    }
+    // Code that cannot read what the Kernel recorded pauses the run the same way.
+    const envelope = admitted(workflow, raw, input.kernel);
+    const durable = durableContext(input, context, envelope);
+    let output;
+    try {
+        output = await definition.run(durable);
+    }
+    catch (cause) {
+        throw terminalFailure(engine, cause, definition) ?? cause;
+    }
+    return validateOutput(workflow.callable, output);
+}
+function admitted(workflow, raw, kernel) {
+    const envelope = decodeEnvelope(raw);
+    if (envelope.execution.kernel !== kernel) {
+        throw new TypeError('Durable envelope Kernel differs from its authenticated endpoint.');
+    }
+    const diagnostics = workflow.callable.validateInput(envelope.input);
+    if (diagnostics.length > 0) {
+        throw new TypeError(`Workflow ${workflow.address} cannot read the recorded input.`);
+    }
+    const instance = 'static' in workflow.callable && workflow.callable.static === false;
+    if (instance !== (envelope.execution.receiver !== undefined)) {
+        throw new TypeError(`Workflow ${workflow.address} cannot use the recorded receiver.`);
+    }
+    return envelope;
+}
+function durableContext(input, context, envelope) {
+    const { serving, domain, workflow } = input;
+    const { engine } = serving;
+    const definition = workflow.definition;
+    const execution = envelope.execution;
+    const signal = context.request().attemptCompletedSignal;
+    const steps = new Set();
+    /** One journaled unit of work acting as the Domain, with keys derived from its name. */
+    const journal = (name, execute) => Promise.resolve(context.run(name, async () => {
+        const deadline = Date.now() + serving.stepTimeoutMs;
+        const session = input.executor(execution.kernel, execution.id, { deadline, signal });
+        try {
+            const kernel = keyed(bindSessionOf(session, deadline, signal), domain, await keySequence(execution.id, name));
+            const output = await execute(Object.freeze({
+                kernel,
+                query: bindQuery(kernel, domain),
+                mutate: bindMutation(kernel, domain),
+            }));
+            try {
+                return acceptStepOutput(output);
+            }
+            catch (cause) {
+                throw new TypeError(`Workflow ${name} output must be portable.`, { cause });
+            }
+        }
+        catch (cause) {
+            throw terminalFailure(engine, cause, definition) ?? cause;
+        }
+        finally {
+            session.close();
+        }
+    })).catch((cause) => {
+        throw replayedFailure(engine, cause, definition) ?? cause;
+    });
+    const step = (id, execute) => {
+        let accepted;
+        try {
+            accepted = acceptStepId(id);
+            if (steps.has(accepted))
+                throw new TypeError(`Workflow Step ${accepted} occurs more than once.`);
+        }
+        catch (cause) {
+            return Promise.reject(cause);
+        }
+        steps.add(accepted);
+        return journal(`step:${accepted}`, execute);
+    };
+    return Object.freeze({
+        domain,
+        input: envelope.input,
+        execution,
+        error: declaredErrorFactory(definition),
+        step: Object.freeze({
+            run: step,
+            mutate: (id, mutation, value) => step(id, (authority) => authority.mutate(mutation, value)),
+        }),
+        async sleep(durationMs) {
+            if (!Number.isSafeInteger(durationMs) || durationMs < 0 || durationMs > MAXIMUM_SLEEP_MS) {
+                throw new TypeError(`Durable sleep must be an integer between 0 and ${MAXIMUM_SLEEP_MS} ms.`);
+            }
+            await context.sleep(durationMs);
+        },
+        async promise(name) {
+            if (typeof name !== 'string' || name.length === 0 || name.length > MAXIMUM_PROMISE_NAME) {
+                throw new TypeError('Durable promise name must have 1 to 128 characters.');
+            }
+            return (await context.promise(name).get());
+        },
+        cancelled: (error) => error instanceof engine.CancelledError,
+        async awaitExecution(target) {
+            for (let poll = 1;; poll++) {
+                const polled = await journal(`await:${target.id}:${poll}`, async ({ kernel }) => {
+                    try {
+                        const outcome = await kernel.invoke(executionMethods.result(target), {
+                            waitMs: Math.min(AWAIT_WAIT_MS, Math.floor(serving.stepTimeoutMs / 2)),
+                        });
+                        return { ended: true, outcome };
+                    }
+                    catch (cause) {
+                        if (cause instanceof ResponseError && cause.reason?.code === 'EXECUTION_PENDING') {
+                            return { ended: false };
+                        }
+                        throw cause;
+                    }
+                });
+                if (polled.ended)
+                    return polled.outcome;
+                await context.sleep(Math.min(AWAIT_MAXIMUM_PAUSE_MS, 1_000 * 2 ** Math.min(poll, 16)));
+            }
+        },
+        ...(execution.receiver === undefined ? {} : { self: execution.receiver }),
+    });
+}
+function bindSessionOf(session, deadline, signal) {
+    return bindSession(session, { deadline, signal });
+}
+/**
+ * Every Mutation and every `invoke` of a durable callable of one Step without its own key carries
+ * the next key of the Step's sequence. The sequence restarts with every attempt, so a retried Step
+ * replays the same keys: the Kernel answers a Mutation with its receipt and a durable call with the
+ * Execution it started, or refuses a request that changed under its key. Any other `invoke` carries
+ * no key, because the Kernel accepts one only for a durable Function, and runs again with the Step.
+ */
+function keyed(session, domain, next) {
+    const invokeSource = session.invoke;
+    const mutateSource = session.mutate;
+    const invoke = ((reference, value, options) => invokeSource(reference, value, declaredDurable(domain, reference) ? withKey(options, next) : options));
+    const mutate = ((author, options) => mutateSource(author, withKey(options, next)));
+    return Object.freeze({ ...session, invoke, mutate });
+}
+/**
+ * Whether the Domain's Schema closure declares the referenced callable durable. An untyped Path
+ * names no declaration and a callable outside the closure has none here: both need their own key.
+ */
+function declaredDurable(domain, reference) {
+    if (reference === null || typeof reference !== 'object')
+        return false;
+    const key = reference.callable;
+    return (typeof key === 'string' && domain.callable(key)?.execution?.durable === true);
+}
+function withKey(options, next) {
+    if (options?.idempotencyKey !== undefined || options?.body !== undefined)
+        return options;
+    return { ...options, idempotencyKey: next() };
+}
+async function keySequence(execution, name) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(name)));
+    const prefix = `${execution}.${Array.from(digest.subarray(0, 12), hex).join('')}`;
+    let position = 0;
+    return () => `${prefix}.${++position}`;
+}
+function hex(byte) {
+    return byte.toString(16).padStart(2, '0');
+}
+function signalRequest(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        typeof input.name !== 'string') {
+        throw new TypeError('Durable signal request is invalid.');
+    }
+    const { name, value } = input;
+    if (name.length === 0 || name.length > MAXIMUM_PROMISE_NAME) {
+        throw new TypeError('Durable signal name must have 1 to 128 characters.');
+    }
+    return { name, value: value ?? null };
+}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 /** Curated SDK authoring journey. Semantic values remain available from focused subpaths. */
 export { defineAction } from './application/action/index.js';
 export type { Action, ActionContext, ActionOutputOf, Caller, DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from './application/action/index.js';
-export { defineApplication, defineFrontend, external, requirements, route, routes, vite, } from './application/index.js';
-export type { Application, Frontend, Requirements, Route, Routes } from './application/index.js';
+export { defineDomain, defineFrontend, external, requirements, route, routes, vite, } from './application/index.js';
+export type { DomainDefinition, Frontend, Requirements, Route, Routes, } from './application/index.js';
 export { defineIntegration, defineProvider } from './application/integration/index.js';
 export type { IntegrationClient, IntegrationDefinition, Provider, } from './application/integration/index.js';
 export { defineMutation, executeMutation } from './application/mutation/index.js';
@@ -13,9 +13,9 @@ export { defineRuntime } from './application/runtime/index.js';
 export type { Runtime } from './application/runtime/index.js';
 export { defineWorkflow } from './application/workflow/index.js';
 export type { Workflow, WorkflowContext } from './application/workflow/index.js';
-export { compile, deploy, runtime } from './deployment/index.js';
+export { compile, runtime } from './deployment/index.js';
 export type { Build, Deployment, Release } from './deployment/index.js';
 export { defineProject } from './project/index.js';
 export type { Project } from './project/index.js';
 export { serve } from './execution/index.js';
-export type { ServedApplication } from './execution/index.js';
+export type { ServedDomain } from './execution/index.js';

package/dist/index.js

@@ -1,11 +1,11 @@
 /** Curated SDK authoring journey. Semantic values remain available from focused subpaths. */
 export { defineAction } from './application/action/index.js';
-export { defineApplication, defineFrontend, external, requirements, route, routes, vite, } from './application/index.js';
+export { defineDomain, defineFrontend, external, requirements, route, routes, vite, } from './application/index.js';
 export { defineIntegration, defineProvider } from './application/integration/index.js';
 export { defineMutation, executeMutation } from './application/mutation/index.js';
 export { defineCollectionQuery, defineCompositeQuery, defineQuery, executeQuery, } from './application/query/index.js';
 export { defineRuntime } from './application/runtime/index.js';
 export { defineWorkflow } from './application/workflow/index.js';
-export { compile, deploy, runtime } from './deployment/index.js';
+export { compile, runtime } from './deployment/index.js';
 export { defineProject } from './project/index.js';
 export { serve } from './execution/index.js';

package/dist/platform/graph/alias.d.ts

@@ -1,6 +1,2 @@
 /** Graph-local names retain the canonical Kernel type and constructor identity. */
-export { LocalBinding as LocalAlias, isLocalBinding as isLocalAlias, } from '@astrale-os/kernel-core/graph/graph';
-/** @deprecated Use LocalAlias. */
-export { LocalBinding } from '@astrale-os/kernel-core/graph/graph';
-/** @deprecated Use isLocalAlias. */
-export { isLocalBinding } from '@astrale-os/kernel-core/graph/graph';
+export { LocalAlias, isLocalAlias } from '@astrale-os/kernel-core/graph/graph';

package/dist/platform/graph/alias.js

@@ -1,6 +1,2 @@
 /** Graph-local names retain the canonical Kernel type and constructor identity. */
-export { LocalBinding as LocalAlias, isLocalBinding as isLocalAlias, } from '@astrale-os/kernel-core/graph/graph';
-/** @deprecated Use LocalAlias. */
-export { LocalBinding } from '@astrale-os/kernel-core/graph/graph';
-/** @deprecated Use isLocalAlias. */
-export { isLocalBinding } from '@astrale-os/kernel-core/graph/graph';
+export { LocalAlias, isLocalAlias } from '@astrale-os/kernel-core/graph/graph';

package/dist/platform/graph/document/index.d.ts

@@ -1,3 +1,3 @@
 /** Canonical graph documents and local aliases. */
 export * from '@astrale-os/kernel-core/graph/graph';
-export { LocalAlias, isLocalAlias, LocalBinding, isLocalBinding } from '../alias.js';
+export { LocalAlias, isLocalAlias } from '../alias.js';

package/dist/platform/graph/document/index.js

@@ -1,3 +1,3 @@
 /** Canonical graph documents and local aliases. */
 export * from '@astrale-os/kernel-core/graph/graph';
-export { LocalAlias, isLocalAlias, LocalBinding, isLocalBinding } from '../alias.js';
+export { LocalAlias, isLocalAlias } from '../alias.js';

package/dist/platform/graph/index.d.ts

@@ -1,6 +1,6 @@
 /** Curated aggregate over canonical graph values. */
 export { GraphData, GraphDataDecodeError, GraphSpec, GraphSpecDecodeError, } from '@astrale-os/kernel-core/graph/graph';
-export { LocalAlias, isLocalAlias, LocalBinding, isLocalBinding } from './alias.js';
+export { LocalAlias, isLocalAlias } from './alias.js';
 export type { AnonymousNodeSpec, GraphDataJson, GraphSpecEdge, GraphSpecEndpoint, GraphSpecJson, GraphSpecNode, } from '@astrale-os/kernel-core/graph/graph';
 export * from './edge/index.js';
 export * from './node/index.js';

package/dist/platform/graph/index.js

@@ -1,6 +1,6 @@
 /** Curated aggregate over canonical graph values. */
 export { GraphData, GraphDataDecodeError, GraphSpec, GraphSpecDecodeError, } from '@astrale-os/kernel-core/graph/graph';
-export { LocalAlias, isLocalAlias, LocalBinding, isLocalBinding } from './alias.js';
+export { LocalAlias, isLocalAlias } from './alias.js';
 export * from './edge/index.js';
 export * from './node/index.js';
 export * from './path/index.js';

package/dist/platform/release/index.d.ts

@@ -0,0 +1,2 @@
+/** Canonical DomainRelease v4 and Delivery v2 wire contracts. */
+export * from '@astrale-os/kernel-protocol/release';

package/dist/platform/release/index.js

@@ -0,0 +1,2 @@
+/** Canonical DomainRelease v4 and Delivery v2 wire contracts. */
+export * from '@astrale-os/kernel-protocol/release';

package/dist/platform/schema/callable-authoring.d.ts

@@ -0,0 +1,21 @@
+import { func as kernelFunc, method as kernelMethod, type CallablePolicyBuilder, type FunctionInput, type Method, type MethodInput } from '@astrale-os/kernel-dsl/v1/builder';
+/** Who may call an authorized callable: Policy checks, or the constant `true` or `false`. */
+export type CallerRule = CallablePolicyBuilder | boolean;
+/**
+ * An executable `authorized` callable declares its caller rule. An abstract Method is a contract
+ * on an abstract Class and executable on a concrete one, so its rule is settled by the Class that
+ * declares it.
+ */
+export type DeclaredCallerRule<Config> = Config extends {
+    readonly auth: 'authorized';
+} ? Config extends {
+    readonly abstract: true;
+} ? unknown : {
+    readonly policy: CallerRule;
+} : unknown;
+/** Author a Function. An `authorized` Function declares its caller rule. */
+export declare function func<const Config extends FunctionInput>(config: Config & DeclaredCallerRule<Config>): ReturnType<typeof kernelFunc<Config>>;
+/** Author a Method. An executable `authorized` Method declares its caller rule. */
+export declare function method<const Config extends MethodInput>(config: Config & DeclaredCallerRule<Config>): ReturnType<typeof kernelMethod<Config>>;
+/** A concrete Class executes every Method it declares, abstract contracts included. */
+export declare function assertNoUndeclaredCallerRule(methods: Readonly<Record<string, Method>> | undefined): void;

package/dist/platform/schema/callable-authoring.js

@@ -0,0 +1,27 @@
+import { func as kernelFunc, method as kernelMethod, } from '@astrale-os/kernel-dsl/v1/builder';
+/** Authorized abstract Methods authored without a caller rule, until a Class declares them. */
+const undeclared = new WeakSet();
+export function func(config) {
+    if (config.auth === 'authorized' && config.policy === undefined)
+        undeclaredCallerRule('Function');
+    return kernelFunc(config);
+}
+export function method(config) {
+    const value = kernelMethod(config);
+    if (config.auth === 'authorized' && config.policy === undefined) {
+        if (config.abstract !== true)
+            undeclaredCallerRule('Method');
+        undeclared.add(value);
+    }
+    return value;
+}
+/** A concrete Class executes every Method it declares, abstract contracts included. */
+export function assertNoUndeclaredCallerRule(methods) {
+    for (const [name, value] of Object.entries(methods ?? {})) {
+        if (undeclared.has(value))
+            undeclaredCallerRule(`Method ${name}`);
+    }
+}
+function undeclaredCallerRule(subject) {
+    throw new TypeError(`${subject} is authorized and executable: declare its policy with Policy checks, true or false.`);
+}

package/dist/platform/schema/class-authoring.d.ts

@@ -1,36 +1,86 @@
-import { nodeClass as kernelNodeClass, type DirectedEdgeClass, type DirectedEdgeInput, type NodeClass, type NodeClassInput as KernelNodeClassInput, type UndirectedEdgeClass, type UndirectedEdgeInput } from '@astrale-os/kernel-dsl/v1/builder';
+import { edgeClass as kernelEdgeClass, nodeClass as kernelNodeClass, type DirectedEdgeClass, type DirectedEdgeInput, type Lazy, type NodeClass, type NodeClassInput as KernelNodeClassInput, type NodeClassPolicyInput, type Policy, type UndirectedEdgeClass, type UndirectedEdgeInput } from '@astrale-os/kernel-dsl/v1/builder';
 import { type ClassIcon } from './class-icon.js';
-/** SDK Node Class input: every author must make an explicit, admitted icon choice. */
+/**
+ * SDK Node Class input: every author must make an explicit, admitted icon choice, and every
+ * concrete Class must declare its read rule.
+ */
 export type NodeClassInput = Omit<KernelNodeClassInput, 'icon'> & {
     readonly icon: ClassIcon;
 };
+/** Who may read or traverse an Edge Class: a named Policy, or the constant `true` or `false`. */
+export type ClassReadRule = Lazy<Policy> | boolean;
+/**
+ * Who may read or traverse a Node Class: a named Policy, the constant `true` or `false`, or Policy
+ * checks over the observed Node (`self`) and fixed members (`ref(...)`), composed as the checks of
+ * an authorized callable.
+ */
+export type NodeClassReadRule = NodeClassPolicyInput;
+/**
+ * The observation rules of a concrete Class. A Node stays traversable through either rule, so a
+ * read rule other than `true` leaves every caller able to reach it, and to select its reference,
+ * until the traverse rule is declared too.
+ */
+export type DeclaredObservation<Rule = ClassReadRule> = {
+    readonly read: true;
+    readonly traverse?: Rule;
+} | {
+    readonly read: Exclude<Rule, true>;
+    readonly traverse: Rule;
+};
+/**
+ * A concrete Class declares its read rule, and its traverse rule whenever the read rule is not
+ * `true`. An abstract Class is never observed directly, so it declares neither.
+ */
+export type DeclaredReadRule<Config, Rule = ClassReadRule> = Config extends {
+    readonly abstract: true;
+} ? unknown : {
+    readonly policies: DeclaredObservation<Rule>;
+};
 /** Preserve authored input instead of serializing expanded inheritance projections in consumers. */
 export interface AuthoredNodeClass<Config extends NodeClassInput> extends ReturnType<typeof kernelNodeClass<Config>> {
 }
+type DirectedOptions = Omit<DirectedEdgeInput, 'orientation'>;
+type UndirectedOptions = Omit<UndirectedEdgeInput, 'orientation'>;
+/** The two states `defineClass` admits: abstract, or concrete with declared observation rules. */
+type Declared<Input, Rule = ClassReadRule> = (Input & {
+    readonly abstract: true;
+}) | (Input & {
+    readonly abstract: false;
+} & {
+    readonly policies: DeclaredObservation<Rule>;
+});
 type NodeInput = {
     readonly kind: 'node';
-    readonly abstract: boolean;
-} & NodeClassInput;
+} & Declared<NodeClassInput, NodeClassReadRule>;
 type DirectedInput = {
     readonly kind: 'edge';
     readonly orientation: 'directed';
-    readonly abstract: boolean;
-} & Omit<DirectedEdgeInput, 'orientation'>;
+} & Declared<DirectedOptions>;
 type UndirectedInput = {
     readonly kind: 'edge';
     readonly orientation: 'undirected';
-    readonly abstract: boolean;
-} & Omit<UndirectedEdgeInput, 'orientation'>;
+} & Declared<UndirectedOptions>;
 /**
  * Author a Node Class whose materialized configuration always carries an explicitly selected,
- * admitted SVG icon. The mapped input retains inference while expanding package-private
- * Config interface names into portable structure for downstream declaration emit.
+ * admitted SVG icon and, when concrete, a declared read rule. The mapped input retains inference
+ * while expanding package-private Config interface names into portable structure for downstream
+ * declaration emit.
  */
-export declare function nodeClass<const Config extends NodeClassInput>(config: Config & Record<Exclude<keyof Config, keyof NodeClassInput>, never>): AuthoredNodeClass<{
+export declare function nodeClass<const Config extends NodeClassInput>(config: Config & Record<Exclude<keyof Config, keyof NodeClassInput>, never> & DeclaredReadRule<Config, NodeClassReadRule>): AuthoredNodeClass<{
     [Key in keyof Config]: Key extends 'properties' | 'methods' | 'policies' ? {
         [Member in keyof NonNullable<Config[Key]>]: NonNullable<Config[Key]>[Member];
     } | Extract<Config[Key], undefined> : Key extends 'extends' ? Config[Key] extends infer Parents extends NodeClassInput['extends'] ? Parents extends readonly unknown[] ? readonly [...Parents] : Parents : never : Config[Key];
 }>;
+declare function directed<const Input extends DirectedOptions>(input: Input & Parameters<typeof kernelEdgeClass.directed<Input>>[0] & DeclaredReadRule<Input>): ReturnType<typeof kernelEdgeClass.directed<Input>>;
+declare function undirected<const Input extends UndirectedOptions>(input: Input & Parameters<typeof kernelEdgeClass.undirected<Input>>[0] & DeclaredReadRule<Input>): ReturnType<typeof kernelEdgeClass.undirected<Input>>;
+/**
+ * Author an Edge Class. A concrete Edge Class declares its read rule exactly as a Node Class
+ * does; the handle is the canonical DSL handle.
+ */
+export declare const edgeClass: Readonly<{
+    directed: typeof directed;
+    undirected: typeof undirected;
+}>;
 export declare function defineClass(config: NodeInput): NodeClass;
 export declare function defineClass(config: DirectedInput): DirectedEdgeClass;
 export declare function defineClass(config: UndirectedInput): UndirectedEdgeClass;

package/dist/platform/schema/class-authoring.js

@@ -1,20 +1,53 @@
-import { defineClass as defineKernelClass, nodeClass as kernelNodeClass, } from '@astrale-os/kernel-dsl/v1/builder';
+import { edgeClass as kernelEdgeClass, nodeClass as kernelNodeClass, } from '@astrale-os/kernel-dsl/v1/builder';
+import { assertNoUndeclaredCallerRule } from './callable-authoring.js';
 import { classIcon } from './class-icon.js';
 export function nodeClass(config) {
     if (config === undefined || config.icon === undefined) {
         throw new TypeError('Node Class icon is required; use classIcon.neutral to make an explicit neutral choice.');
     }
+    assertDeclaredReadRule('Node', config);
+    if (config.abstract !== true)
+        assertNoUndeclaredCallerRule(config.methods);
     return kernelNodeClass({
         ...config,
         icon: classIcon.svg(config.icon),
     });
 }
+function directed(input) {
+    assertDeclaredReadRule('Edge', input);
+    return kernelEdgeClass.directed(input);
+}
+function undirected(input) {
+    assertDeclaredReadRule('Edge', input);
+    return kernelEdgeClass.undirected(input);
+}
+/**
+ * Author an Edge Class. A concrete Edge Class declares its read rule exactly as a Node Class
+ * does; the handle is the canonical DSL handle.
+ */
+export const edgeClass = Object.freeze({ directed, undirected });
 export function defineClass(config) {
     if (config.kind === 'node') {
         const { kind: _, ...input } = config;
         return nodeClass(input);
     }
-    if (config.orientation === 'directed')
-        return defineKernelClass(config);
-    return defineKernelClass(config);
+    if (config.orientation === 'directed') {
+        const { kind: _, orientation: __, ...input } = config;
+        return edgeClass.directed(input);
+    }
+    const { kind: _, orientation: __, ...input } = config;
+    return edgeClass.undirected(input);
+}
+/** The authoring boundary restates the type contract for untyped and widened configurations. */
+function assertDeclaredReadRule(kind, config) {
+    if (config.abstract === true)
+        return;
+    const rule = kind === 'Node' ? 'a Policy, Policy checks, true or false' : 'a Policy, true or false';
+    const read = config.policies?.read;
+    if (read === undefined) {
+        throw new TypeError(`${kind} Class read rule is required; declare policies.read with ${rule}.`);
+    }
+    if (read !== true && config.policies?.traverse === undefined) {
+        throw new TypeError(`${kind} Class traverse rule is required when its read rule is not true; declare policies.traverse with ${rule}.`);
+    }
 }

package/dist/platform/schema/class-icon-svg.d.ts

@@ -0,0 +1,9 @@
+declare const CLASS_ICON: unique symbol;
+/** An admitted, self-contained SVG suitable for a Node Class presentation icon. */
+export type ClassIcon = string & {
+    readonly [CLASS_ICON]: true;
+};
+/** Stable empty SVG used when an author explicitly chooses to render no icon glyph. */
+export declare const NEUTRAL_CLASS_ICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"></svg>";
+export declare function admitClassIconSvg(source: string): ClassIcon;
+export {};

package/dist/platform/schema/class-icon-svg.js

@@ -0,0 +1,29 @@
+const MAX_CLASS_ICON_LENGTH = 8_000;
+const SVG_ROOT = /^<svg(?:\s[^>]*)?>[\s\S]*<\/svg>$/u;
+const SVG_ROOT_OPEN = /<svg(?:\s|>)/gu;
+const SVG_ROOT_CLOSE = /<\/svg\s*>/gu;
+const SVG_GRAPHIC = /<(?:circle|ellipse|line|path|polygon|polyline|rect)\b/iu;
+const UNSAFE_SVG = /<\s*(?:animate|discard|embed|foreignObject|iframe|image|object|script|set|style|use)\b|<!DOCTYPE\b|<!ENTITY\b|\son[a-z][\w:.-]*\s*=|(?:href|xlink:href)\s*=|javascript\s*:|url\s*\(/iu;
+/** Stable empty SVG used when an author explicitly chooses to render no icon glyph. */
+export const NEUTRAL_CLASS_ICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>';
+export function admitClassIconSvg(source) {
+    if (typeof source !== 'string') {
+        throw new TypeError('Class icon must be an inline SVG string.');
+    }
+    const value = source.trim();
+    if (Array.from(value).length > MAX_CLASS_ICON_LENGTH) {
+        throw new TypeError(`Class icon must contain at most ${MAX_CLASS_ICON_LENGTH} characters.`);
+    }
+    if (!SVG_ROOT.test(value) ||
+        (value.match(SVG_ROOT_OPEN)?.length ?? 0) !== 1 ||
+        (value.match(SVG_ROOT_CLOSE)?.length ?? 0) !== 1) {
+        throw new TypeError('Class icon must be one complete inline <svg> element.');
+    }
+    if (UNSAFE_SVG.test(value)) {
+        throw new TypeError('Class icon SVG must be self-contained and contain no executable content.');
+    }
+    if (value !== NEUTRAL_CLASS_ICON_SVG && !SVG_GRAPHIC.test(value)) {
+        throw new TypeError('Class icon SVG must contain a visible vector element.');
+    }
+    return value;
+}

package/dist/platform/schema/class-icon.d.ts

@@ -1,15 +1,10 @@
 import type { LucideIconData } from '@lucide/icons';
-declare const CLASS_ICON: unique symbol;
-/** An admitted, self-contained SVG suitable for a Node Class presentation icon. */
-export type ClassIcon = string & {
-    readonly [CLASS_ICON]: true;
-};
-/** Stable empty SVG used when an author explicitly chooses to render no icon glyph. */
-export declare const NEUTRAL_CLASS_ICON_SVG = "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\"></svg>";
+import type { ClassIcon } from './class-icon-svg.js';
+export type { ClassIcon } from './class-icon-svg.js';
+export { NEUTRAL_CLASS_ICON_SVG } from './class-icon-svg.js';
 /** Framework-neutral constructors for canonical Node Class icons. */
 export declare const classIcon: Readonly<{
     readonly neutral: ClassIcon;
     svg(source: string): ClassIcon;
     lucide(icon: LucideIconData): ClassIcon;
 }>;
-export {};

package/dist/platform/schema/class-icon.js

@@ -1,33 +1,6 @@
 import { buildLucideSvg } from '@lucide/icons/build';
-const MAX_CLASS_ICON_LENGTH = 8_000;
-const SVG_ROOT = /^<svg(?:\s[^>]*)?>[\s\S]*<\/svg>$/u;
-const SVG_ROOT_OPEN = /<svg(?:\s|>)/gu;
-const SVG_ROOT_CLOSE = /<\/svg\s*>/gu;
-const SVG_GRAPHIC = /<(?:circle|ellipse|line|path|polygon|polyline|rect)\b/iu;
-const UNSAFE_SVG = /<\s*(?:animate|discard|embed|foreignObject|iframe|image|object|script|set|style|use)\b|<!DOCTYPE\b|<!ENTITY\b|\son[a-z][\w:.-]*\s*=|(?:href|xlink:href)\s*=|javascript\s*:|url\s*\(/iu;
-/** Stable empty SVG used when an author explicitly chooses to render no icon glyph. */
-export const NEUTRAL_CLASS_ICON_SVG = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"></svg>';
-function svg(source) {
-    if (typeof source !== 'string') {
-        throw new TypeError('Class icon must be an inline SVG string.');
-    }
-    const value = source.trim();
-    if (Array.from(value).length > MAX_CLASS_ICON_LENGTH) {
-        throw new TypeError(`Class icon must contain at most ${MAX_CLASS_ICON_LENGTH} characters.`);
-    }
-    if (!SVG_ROOT.test(value) ||
-        (value.match(SVG_ROOT_OPEN)?.length ?? 0) !== 1 ||
-        (value.match(SVG_ROOT_CLOSE)?.length ?? 0) !== 1) {
-        throw new TypeError('Class icon must be one complete inline <svg> element.');
-    }
-    if (UNSAFE_SVG.test(value)) {
-        throw new TypeError('Class icon SVG must be self-contained and contain no executable content.');
-    }
-    if (value !== NEUTRAL_CLASS_ICON_SVG && !SVG_GRAPHIC.test(value)) {
-        throw new TypeError('Class icon SVG must contain a visible vector element.');
-    }
-    return value;
-}
+import { admitClassIconSvg as svg, NEUTRAL_CLASS_ICON_SVG } from './class-icon-svg.js';
+export { NEUTRAL_CLASS_ICON_SVG } from './class-icon-svg.js';
 function lucide(icon) {
     let source;
     try {