@astrale-os/sdk 0.5.0-beta.13 → 0.5.0-beta.131

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

@@ -0,0 +1,48 @@
+import type { DefinedSchema, ResolvedDomainOfInput } from '@astrale-os/kernel-dsl/v1/builder';
+import type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
+import { defineSchema as kernelDefineSchema } from '@astrale-os/kernel-dsl/v1';
+type DomainSchemaInput = Parameters<typeof kernelDefineSchema>[1];
+declare const authoredGraph: unique symbol;
+/** Opaque legacy Schemas retain their witness; SDK Schemas retain authored input and edges. */
+type Entry = readonly [origin: string, schema: DomainSchema] | readonly [
+    origin: string,
+    input: DomainSchemaInput,
+    dependencies: Readonly<Record<string, string>>
+];
+type Dependencies<Input> = 'dependencies' extends keyof Input ? NonNullable<Input['dependencies']> : {};
+type GraphOf<Schema> = typeof authoredGraph extends keyof Schema ? Schema[typeof authoredGraph] extends infer Graph ? Graph extends Entry ? Graph : never : never : Schema extends DomainSchema<infer Origin> ? readonly [Origin, Schema] : never;
+type GraphOfInput<Origin extends string, Input extends DomainSchemaInput> = readonly [
+    Origin,
+    {
+        readonly [Key in keyof Input as Exclude<Key, 'dependencies'>]: Input[Key];
+    },
+    {
+        readonly [Alias in keyof Dependencies<Input>]: Dependencies<Input>[Alias] extends DomainSchema<infer DependencyOrigin> ? DependencyOrigin : never;
+    }
+] | {
+    [Alias in keyof Dependencies<Input>]: GraphOf<Dependencies<Input>[Alias]>;
+}[keyof Dependencies<Input>];
+type LastEntry<Graph> = (Graph extends unknown ? (entry: () => Graph) => void : never) extends (entry: infer Intersection) => void ? Intersection extends () => infer Last ? Last : never : never;
+type WithoutEquivalent<Graph, Selected> = Graph extends Selected ? Selected extends Graph ? never : Graph : Graph;
+type UniqueEntries<Graph, Selected = LastEntry<Graph>> = [Graph] extends [never] ? never : Selected | UniqueEntries<WithoutEquivalent<Graph, Selected>>;
+type InputOf<Origin extends string, Graph extends Entry> = Extract<Graph, readonly [Origin, DomainSchemaInput, Readonly<Record<string, string>>]> extends readonly [
+    string,
+    infer Input extends DomainSchemaInput,
+    infer Dependencies extends Readonly<Record<string, string>>
+] ? Input & {
+    readonly dependencies: {
+        readonly [Alias in keyof Dependencies]: SchemaOf<Dependencies[Alias], Graph>;
+    };
+} : never;
+type SchemaOf<Origin extends string, Graph extends Entry> = Extract<Graph, readonly [Origin, DomainSchema]> extends infer Legacy ? [Legacy] extends [never] ? AuthoredSchema<Origin, Graph> : Legacy extends readonly [string, infer Schema extends DomainSchema] ? Schema : never : never;
+/** Resolve a dependency graph without expanding a shared Schema at each dependency edge. */
+export interface AuthoredDomain<Origin extends string, Graph extends Entry> extends ResolvedDomainOfInput<Origin, InputOf<Origin, Graph>> {
+}
+/** A Schema retains each transitive author's input once, with dependency edges represented by origin. */
+export interface AuthoredSchema<Origin extends string, Graph extends Entry> extends DefinedSchema<Origin, AuthoredDomain<Origin, Graph>> {
+    readonly [authoredGraph]?: Graph;
+}
+type DefineSchema = <const Origin extends string, const Input extends DomainSchemaInput>(origin: Origin, input: Input) => string extends Origin | Extract<Dependencies<Input>[keyof Dependencies<Input>], DomainSchema>['origin'] ? DefinedSchema<Origin, ResolvedDomainOfInput<Origin, Input>> : AuthoredSchema<Origin, Extract<UniqueEntries<GraphOfInput<Origin, Input>>, Entry>>;
+/** The canonical implementation with a portable, automatically inferred declaration. */
+export declare const defineSchema: DefineSchema;
+export {};

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

@@ -0,0 +1,3 @@
+import { defineSchema as kernelDefineSchema } from '@astrale-os/kernel-dsl/v1';
+/** The canonical implementation with a portable, automatically inferred declaration. */
+export const defineSchema = kernelDefineSchema;

package/dist/platform/schema/state-property.d.ts

@@ -0,0 +1,11 @@
+import type { StateMachine } from '@astrale-os/kernel-dsl/v1/language/state';
+import { stateProperty as canonicalStateProperty, type PropertyOptions } from '@astrale-os/kernel-dsl/v1/builder';
+type StatePropertyOptions = Omit<PropertyOptions, 'required'>;
+/** Keep the machine's internal Zod schemas behind a portable public property handle. */
+export interface StateProperty<Machine extends StateMachine, Options extends StatePropertyOptions = Record<never, never>> extends ReturnType<typeof canonicalStateProperty<Machine, Options>> {
+}
+/** Canonical state-property authoring with a portable inferred return type. */
+export declare const stateProperty: <const Machine extends StateMachine, const Options extends StatePropertyOptions = Record<never, never>>(machine: Machine, options?: Options & Record<Exclude<keyof Options, 'description'>, never>) => StateProperty<Machine, {
+    [Key in keyof Options]: Options[Key];
+}>;
+export {};

package/dist/platform/schema/state-property.js

@@ -0,0 +1,3 @@
+import { stateProperty as canonicalStateProperty, } from '@astrale-os/kernel-dsl/v1/builder';
+/** Canonical state-property authoring with a portable inferred return type. */
+export const stateProperty = canonicalStateProperty;

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

@@ -0,0 +1,3 @@
+/** Portable values shared by Schema and execution contracts. */
+export * from '@astrale-os/kernel-dsl/value';
+export { assertDnsLabel, DNS_LABEL_RE, dnsLabelSchema, isDnsLabel, } from '@astrale-os/kernel-core/dns-label';

package/dist/platform/value/index.js

@@ -0,0 +1,3 @@
+/** Portable values shared by Schema and execution contracts. */
+export * from '@astrale-os/kernel-dsl/value';
+export { assertDnsLabel, DNS_LABEL_RE, dnsLabelSchema, isDnsLabel, } from '@astrale-os/kernel-core/dns-label';

package/dist/project/admit.d.ts

@@ -0,0 +1,4 @@
+import type { Project } from './project.js';
+export declare const PROJECT_EXPORT_HINT: string;
+/** Admit the module namespace of one loaded `astrale.config.ts`: exactly one default Project. */
+export declare function admitProjectModule(loaded: unknown): Project;

package/dist/project/admit.js

@@ -0,0 +1,22 @@
+import { isLegacyDeployment } from '../deployment/deploy.js';
+import { isProject } from './define.js';
+export const PROJECT_EXPORT_HINT = 'astrale.config.ts must export exactly one default Project:\n' +
+    "  import { defineProject } from '@astrale-os/sdk/project'\n" +
+    '  export default defineProject({ application, environments: { development: { deployment: adapter() } } })\n';
+/** Admit the module namespace of one loaded `astrale.config.ts`: exactly one default Project. */
+export function admitProjectModule(loaded) {
+    if (loaded === null ||
+        typeof loaded !== 'object' ||
+        Array.isArray(loaded) ||
+        !Object.hasOwn(loaded, 'default') ||
+        Object.keys(loaded).some((key) => key !== 'default')) {
+        throw new TypeError(PROJECT_EXPORT_HINT);
+    }
+    const value = Reflect.get(loaded, 'default');
+    if (isProject(value))
+        return value;
+    if (isLegacyDeployment(value)) {
+        throw new TypeError(`astrale.config.ts exports the legacy deploy() aggregate; migrate Application and Environments into defineProject().\n${PROJECT_EXPORT_HINT}`);
+    }
+    throw new TypeError(`Default export must be created by defineProject().\n${PROJECT_EXPORT_HINT}`);
+}

package/dist/project/define.d.ts

@@ -0,0 +1,12 @@
+import type { ApplicationIdentity } from '../application/index.js';
+import type { Tests } from '../testing/index.js';
+import type { Project, ProjectEnvironment, ProjectEntrypoints } from './project.js';
+export interface ProjectInput<ApplicationValue extends ApplicationIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined> {
+    readonly application: ApplicationValue;
+    readonly environments: EnvironmentsValue;
+    readonly entrypoints?: ProjectEntrypoints;
+    readonly tests?: TestsValue;
+}
+/** Capture one inert Project definition without loading entrypoints or performing effects. */
+export declare function defineProject<const ApplicationValue extends ApplicationIdentity, const EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>>, const TestsValue extends Tests | undefined = undefined>(input: ProjectInput<ApplicationValue, EnvironmentsValue, TestsValue>): Project<ApplicationValue, EnvironmentsValue, TestsValue>;
+export declare function isProject(input: unknown): input is Project;

package/dist/project/define.js

@@ -0,0 +1,106 @@
+import { isApplication } from '../application/index.js';
+import { isDeployment } from '../deployment/deployment.js';
+import { isTests } from '../testing/index.js';
+const admittedProjects = new WeakSet();
+const ENVIRONMENT_NAME = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u;
+/** Capture one inert Project definition without loading entrypoints or performing effects. */
+export function defineProject(input) {
+    const value = record(input, 'Project definition');
+    exact(value, ['application', 'environments'], ['entrypoints', 'tests'], invalid);
+    if (!isApplication(input.application))
+        throw new TypeError('Project Application is not admitted.');
+    const environments = record(input.environments, 'Project environments');
+    if (Reflect.ownKeys(environments).some((key) => typeof key !== 'string')) {
+        throw new TypeError('Project Environment names must be strings.');
+    }
+    const names = Object.keys(environments);
+    if (names.length === 0)
+        throw new TypeError('Project must declare at least one Environment.');
+    const captured = Object.create(null);
+    for (const name of names) {
+        if (!ENVIRONMENT_NAME.test(name)) {
+            throw new TypeError(`Project Environment name "${name}" is not normalized.`);
+        }
+        const environment = record(environments[name], `Project Environment ${name}`);
+        exact(environment, ['deployment'], ['installation'], () => invalidEnvironment(name));
+        if (!isDeployment(environment.deployment)) {
+            throw new TypeError(`Project Environment ${name} deployment is not admitted.`);
+        }
+        const installation = environment.installation === undefined
+            ? undefined
+            : admitInstallation(environment.installation, name);
+        environment.deployment.adapter.admit?.(environment.deployment.parameters, {
+            environment: name,
+            ...(installation === undefined ? {} : { installation }),
+        });
+        captured[name] = Object.freeze({
+            deployment: environment.deployment,
+            ...(installation === undefined ? {} : { installation }),
+        });
+    }
+    const entrypoints = input.entrypoints === undefined ? undefined : admitEntrypoints(input.entrypoints);
+    if (input.tests !== undefined && !isTests(input.tests)) {
+        throw new TypeError('Project tests must be created by tests().');
+    }
+    const project = Object.freeze({
+        kind: 'project',
+        application: input.application,
+        environments: Object.freeze(captured),
+        ...(entrypoints === undefined ? {} : { entrypoints }),
+        ...(input.tests === undefined ? {} : { tests: input.tests }),
+    });
+    admittedProjects.add(project);
+    return project;
+}
+export function isProject(input) {
+    return input !== null && typeof input === 'object' && admittedProjects.has(input);
+}
+function admitEntrypoints(input) {
+    const value = record(input, 'Project entrypoints');
+    exact(value, ['runtime'], [], () => {
+        throw new TypeError('Project entrypoints must contain exactly runtime.');
+    });
+    if (typeof input.runtime !== 'string' ||
+        input.runtime.length === 0 ||
+        input.runtime.trim() !== input.runtime ||
+        input.runtime.includes('\0')) {
+        throw new TypeError('Project Runtime entrypoint must be a non-empty stable module coordinate.');
+    }
+    return Object.freeze({ runtime: input.runtime });
+}
+function admitInstallation(input, environment) {
+    const value = record(input, `Project Environment ${environment} installation`);
+    exact(value, ['instance'], ['identity'], () => {
+        throw new TypeError(`Project Environment ${environment} installation may contain only instance and identity.`);
+    });
+    const instance = stableCoordinate(value.instance, 'installation instance');
+    const identity = value.identity === undefined
+        ? undefined
+        : stableCoordinate(value.identity, 'installation identity');
+    return Object.freeze({ instance, ...(identity === undefined ? {} : { identity }) });
+}
+function stableCoordinate(input, label) {
+    if (typeof input !== 'string' || input.length === 0 || input.trim() !== input) {
+        throw new TypeError(`Project ${label} must be a non-empty stable string.`);
+    }
+    return input;
+}
+function record(input, label) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError(`${label} must be an object.`);
+    }
+    return input;
+}
+function exact(input, required, optional, fail) {
+    const allowed = new Set([...required, ...optional]);
+    if (required.some((key) => !Object.hasOwn(input, key)) ||
+        Reflect.ownKeys(input).some((key) => !allowed.has(key))) {
+        fail();
+    }
+}
+function invalid() {
+    throw new TypeError('Project definition may contain only application, environments, entrypoints, and tests.');
+}
+function invalidEnvironment(name) {
+    throw new TypeError(`Project Environment ${name} may contain only deployment and installation.`);
+}

package/dist/project/index.d.ts

@@ -0,0 +1,4 @@
+export { admitProjectModule, PROJECT_EXPORT_HINT } from './admit.js';
+export { defineProject, isProject } from './define.js';
+export type { ProjectInput } from './define.js';
+export type { ApplicationOfProject, EnvironmentsOfProject, Project, ProjectEntrypoints, ProjectEnvironment, } from './project.js';

package/dist/project/index.js

@@ -0,0 +1,2 @@
+export { admitProjectModule, PROJECT_EXPORT_HINT } from './admit.js';
+export { defineProject, isProject } from './define.js';

package/dist/project/project.d.ts

@@ -0,0 +1,24 @@
+import type { ApplicationIdentity } from '../application/index.js';
+import type { InstallationTarget } from '../deployment/adapter/index.js';
+import type { Tests } from '../testing/index.js';
+export interface ProjectEntrypoints {
+    readonly runtime: string;
+}
+export interface ProjectEnvironment<DeploymentValue = unknown> {
+    readonly deployment: DeploymentValue;
+    readonly installation?: InstallationTarget;
+}
+/** The complete independently executable software-product definition in astrale.config.ts. */
+export interface Project<ApplicationValue extends ApplicationIdentity = ApplicationIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>> = Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined = undefined> {
+    readonly kind: 'project';
+    readonly application: ApplicationValue;
+    readonly environments: EnvironmentsValue;
+    readonly entrypoints?: ProjectEntrypoints;
+    readonly tests?: TestsValue;
+}
+export type ApplicationOfProject<Value> = Value extends {
+    readonly application: infer ApplicationValue;
+} ? Extract<ApplicationValue, ApplicationIdentity> : never;
+export type EnvironmentsOfProject<Value> = Value extends {
+    readonly environments: infer EnvironmentsValue;
+} ? EnvironmentsValue : never;

package/dist/project/project.js

@@ -0,0 +1 @@
+export {};

package/dist/testing/dataset/admission.d.ts

@@ -0,0 +1,13 @@
+import type { GraphAdmissionContext, GraphData, GraphDiagnostic } from '../../platform/graph/document/index.js';
+import type { Domain } from '../../platform/schema/index.js';
+import { Graph } from '../../platform/graph/document/index.js';
+export declare class DatasetAdmissionError extends TypeError {
+    readonly dataset: string;
+    readonly diagnostics: readonly GraphDiagnostic[];
+    readonly code: 'DATASET_REJECTED';
+    constructor(dataset: string, diagnostics: readonly GraphDiagnostic[]);
+}
+/** Admit Dataset facts through the canonical Kernel Graph admission over the resolved Domain. */
+export declare function admitDatasetGraph(id: string, domain: Domain, data: GraphData): Graph;
+/** Project one resolved Domain closure into the Class knowledge Graph admission requires. */
+export declare function admissionContext(domain: Domain): GraphAdmissionContext;

package/dist/testing/dataset/admission.js

@@ -0,0 +1,107 @@
+import { Graph, GraphAdmissionError } from '../../platform/graph/document/index.js';
+import { ClassKey as ClassKeyValue, K } from '../../platform/schema/index.js';
+export class DatasetAdmissionError extends TypeError {
+    dataset;
+    diagnostics;
+    code = 'DATASET_REJECTED';
+    constructor(dataset, diagnostics) {
+        super(`Dataset ${dataset} rejected: ${diagnostics
+            .map((diagnostic) => `${diagnostic.code} at ${diagnostic.path} (${diagnostic.message})`)
+            .join('; ')}`);
+        this.dataset = dataset;
+        this.diagnostics = diagnostics;
+        this.name = 'DatasetAdmissionError';
+    }
+}
+/** Admit Dataset facts through the canonical Kernel Graph admission over the resolved Domain. */
+export function admitDatasetGraph(id, domain, data) {
+    try {
+        return Graph.admit(data, admissionContext(domain));
+    }
+    catch (error) {
+        if (error instanceof GraphAdmissionError) {
+            throw new DatasetAdmissionError(id, error.diagnostics);
+        }
+        throw error;
+    }
+}
+/** Project one resolved Domain closure into the Class knowledge Graph admission requires. */
+export function admissionContext(domain) {
+    return {
+        inspectClass(key) {
+            const definition = classAt(domain, key);
+            if (definition === undefined)
+                return undefined;
+            return definition.kind === 'node'
+                ? Object.freeze({ key, kind: 'node', abstract: definition.abstract })
+                : Object.freeze({
+                    key,
+                    kind: 'edge',
+                    abstract: definition.abstract,
+                    orientation: definition.definition.orientation,
+                });
+        },
+        validateProperties(key, props) {
+            const definition = classAt(domain, key);
+            if (definition === undefined)
+                return [];
+            return definition.validateProperties(props).map((diagnostic) => Object.freeze({
+                code: diagnostic.code,
+                path: diagnostic.pointer,
+                message: diagnostic.message,
+            }));
+        },
+        validateEndpoints(edgeKey, sourceKey, targetKey) {
+            const edge = classAt(domain, edgeKey);
+            if (edge?.kind !== 'edge')
+                return [];
+            const source = sourceKey === undefined ? undefined : classAt(domain, sourceKey);
+            const target = targetKey === undefined ? undefined : classAt(domain, targetKey);
+            if ((sourceKey !== undefined && source?.kind !== 'node') ||
+                (targetKey !== undefined && target?.kind !== 'node')) {
+                return [];
+            }
+            const accepts = (node, values) => values.some((value) => nodeSatisfies(domain, node, value));
+            if (edge.definition.orientation === 'directed') {
+                const diagnostics = [];
+                if (source?.kind === 'node' && !accepts(source, edge.definition.endpoints.source.accepts)) {
+                    diagnostics.push(endpointDiagnostic('/source', `${sourceKey} is not accepted at source.`));
+                }
+                if (target?.kind === 'node' && !accepts(target, edge.definition.endpoints.target.accepts)) {
+                    diagnostics.push(endpointDiagnostic('/target', `${targetKey} is not accepted at target.`));
+                }
+                return diagnostics;
+            }
+            const [first, second] = edge.definition.endpoints;
+            const sourceFirst = source?.kind !== 'node' || accepts(source, first.accepts);
+            const sourceSecond = source?.kind !== 'node' || accepts(source, second.accepts);
+            const targetFirst = target?.kind !== 'node' || accepts(target, first.accepts);
+            const targetSecond = target?.kind !== 'node' || accepts(target, second.accepts);
+            return (sourceFirst && targetSecond) || (sourceSecond && targetFirst)
+                ? []
+                : [endpointDiagnostic('/endpoints', `${sourceKey} and ${targetKey} are not assignable.`)];
+        },
+    };
+}
+function endpointDiagnostic(path, message) {
+    return Object.freeze({ code: 'GRAPH_ENDPOINT_CLASS', path, message });
+}
+function nodeSatisfies(domain, node, target) {
+    if (sameRef(node.ref, target) || sameRef(target, K.classes.Node.ref))
+        return true;
+    const selected = classAt(domain, ClassKeyValue.of(target));
+    return selected?.kind === 'node' && node.satisfies(selected);
+}
+function classAt(domain, key) {
+    const definition = domain.definition(ClassKeyValue.ref(key));
+    return definition !== undefined && isResolvedClass(definition) ? definition : undefined;
+}
+function isResolvedClass(input) {
+    return (typeof input === 'object' &&
+        input !== null &&
+        'ref' in input &&
+        input.ref.kind === 'class');
+}
+function sameRef(left, right) {
+    return left.origin === right.origin && left.kind === right.kind && left.name === right.name;
+}

package/dist/testing/dataset/builder.d.ts

@@ -0,0 +1,42 @@
+import type { Edge } from '../../platform/graph/edge/index.js';
+import type { Node, NodeId } from '../../platform/graph/node/index.js';
+import type { PropertyInputOf, ResolvedClass, schema } from '../../platform/schema/index.js';
+import type { DatasetNode, DatasetReferences } from './dataset.js';
+import { type DatasetReferenceInput } from './references.js';
+/** Resolved Classes of the exact authored Schema, keyed by their authored names. */
+export type DatasetClasses<Schema extends schema.DomainSchema> = schema.DomainOf<Schema>['classes'];
+/** One Dataset Node, or one Node identity that names a Node already added to the same Dataset. */
+export type DatasetEndpoint = Node | NodeId | string;
+export interface DatasetNodeInput<Class extends ResolvedClass<'node'>> {
+    /** Stable identity within the Dataset; derived from the Class name and insertion order when omitted. */
+    readonly id?: string;
+    readonly props?: PropertyInputOf<Class>;
+}
+export interface DatasetEdgeInput<Class extends ResolvedClass<'edge'>> {
+    readonly slug?: string;
+    readonly props?: PropertyInputOf<Class>;
+}
+/** Graph authoring surface handed to one Dataset definition. Facts are canonical Kernel values. */
+export interface DatasetGraph<Schema extends schema.DomainSchema> {
+    /** The exact resolved Domain, including dependency Domains under their authored aliases. */
+    readonly domain: schema.DomainOf<Schema>;
+    readonly classes: DatasetClasses<Schema>;
+    /** Materialize one local or direct-dependency projected Node, retaining its reference identity. */
+    ref(input: DatasetReferenceInput): DatasetNode;
+    node<Class extends ResolvedClass<'node'>>(definition: Class, input?: DatasetNodeInput<Class>): DatasetNode<Class>;
+    edge<Class extends ResolvedClass<'edge'>>(definition: Class, source: DatasetEndpoint, target: DatasetEndpoint, input?: DatasetEdgeInput<Class>): Edge;
+}
+export interface DatasetFacts {
+    readonly references: DatasetReferences;
+    readonly nodes: readonly Node[];
+    readonly edges: readonly Edge[];
+    /** Exact Node values handed out by `node()`, for variable admission by identity. */
+    readonly created: ReadonlySet<Node>;
+}
+export interface DatasetGraphSession<Schema extends schema.DomainSchema> {
+    readonly graph: DatasetGraph<Schema>;
+    /** Reject any later fact authoring and return the authored facts in insertion order. */
+    seal(): DatasetFacts;
+}
+/** Open one authoring session over a resolved Domain. Authored facts stay un-admitted until sealed. */
+export declare function openDatasetGraph<Schema extends schema.DomainSchema>(domain: schema.ResolvedDomainOf<Schema>): DatasetGraphSession<Schema>;

package/dist/testing/dataset/builder.js

@@ -0,0 +1,127 @@
+import { edge as graphEdge, EdgeSlug } from '../../platform/graph/edge/index.js';
+import { node as graphNode, NodeId as admitNodeId } from '../../platform/graph/node/index.js';
+import { Path } from '../../platform/graph/path/index.js';
+import { ClassKey } from '../../platform/schema/index.js';
+import { datasetReferenceNodes } from './references.js';
+/** Open one authoring session over a resolved Domain. Authored facts stay un-admitted until sealed. */
+export function openDatasetGraph(domain) {
+    const nodes = [];
+    const edges = [];
+    const byId = new Map();
+    const created = new Set();
+    const ordinals = new Map();
+    const references = {};
+    let projected;
+    let referenceOrdinal = 0;
+    let sealed = false;
+    const graph = Object.freeze({
+        domain,
+        classes: domain.classes,
+        ref(input) {
+            open();
+            const ref = 'ref' in input ? input.ref : input;
+            const path = Path.project(ref).raw;
+            const existing = references[path];
+            if (existing !== undefined)
+                return byId.get(existing);
+            projected ??= datasetReferenceNodes(domain);
+            const facts = projected.get(path);
+            if (facts === undefined)
+                throw new TypeError(`Dataset reference ${path} is not local or a direct dependency member.`);
+            let id;
+            do {
+                id = admitNodeId(`reference-${++referenceOrdinal}`);
+            } while (byId.has(id));
+            const value = graphNode({ id, class: facts.class, props: facts.props });
+            nodes.push(value);
+            byId.set(id, value);
+            created.add(value);
+            references[path] = id;
+            return value;
+        },
+        node(definition, input = {}) {
+            open();
+            acceptClass(definition, 'node');
+            acceptInput(input, ['id', 'props'], 'Dataset node input');
+            const id = admitNodeId(input.id ?? nextId(definition));
+            if (byId.has(id))
+                throw new TypeError(`Dataset Node ${id} is already defined.`);
+            const value = graphNode({
+                id,
+                class: ClassKey.of(definition.ref),
+                props: definition.properties.from(input.props ?? {}),
+            });
+            nodes.push(value);
+            byId.set(id, value);
+            created.add(value);
+            return value;
+        },
+        edge(definition, source, target, input = {}) {
+            open();
+            acceptClass(definition, 'edge');
+            acceptInput(input, ['slug', 'props'], 'Dataset edge input');
+            const value = graphEdge({
+                source: endpoint(source, 'source'),
+                target: endpoint(target, 'target'),
+                class: ClassKey.of(definition.ref),
+                ...(input.slug === undefined ? {} : { slug: EdgeSlug(input.slug) }),
+                props: definition.properties.from(input.props ?? {}),
+            });
+            edges.push(value);
+            return value;
+        },
+    });
+    return Object.freeze({
+        graph,
+        seal() {
+            sealed = true;
+            return Object.freeze({
+                nodes: Object.freeze([...nodes]),
+                edges: Object.freeze([...edges]),
+                created,
+                references: Object.freeze({ ...references }),
+            });
+        },
+    });
+    function open() {
+        if (sealed)
+            throw new TypeError('Dataset graph cannot change after its definition completes.');
+    }
+    function nextId(definition) {
+        const name = definition.ref.name;
+        const ordinal = (ordinals.get(name) ?? 0) + 1;
+        ordinals.set(name, ordinal);
+        return `${name}-${ordinal}`;
+    }
+    function endpoint(input, role) {
+        const id = typeof input === 'string'
+            ? admitNodeId(input)
+            : input !== null && typeof input === 'object' && typeof input.id === 'string'
+                ? admitNodeId(input.id)
+                : invalidEndpoint(role);
+        if (!byId.has(id)) {
+            throw new TypeError(`Dataset edge ${role} ${id} is not a Node of this Dataset.`);
+        }
+        return id;
+    }
+}
+function acceptClass(definition, kind) {
+    if (definition === null ||
+        typeof definition !== 'object' ||
+        definition.kind !== kind ||
+        definition.ref?.kind !== 'class') {
+        throw new TypeError(`Dataset ${kind} requires a resolved ${kind} Class.`);
+    }
+}
+function acceptInput(input, allowed, label) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError(`${label} must be an object.`);
+    }
+    const unknown = Reflect.ownKeys(input).find((key) => typeof key !== 'string' || !allowed.includes(key));
+    if (unknown !== undefined) {
+        throw new TypeError(`${label} may contain only ${allowed.join(' and ')}.`);
+    }
+}
+function invalidEndpoint(role) {
+    throw new TypeError(`Dataset edge ${role} must be a Dataset Node or a Node identity.`);
+}

package/dist/testing/dataset/codec.d.ts

@@ -0,0 +1,6 @@
+import type { schema as schemaLanguage } from '../../platform/schema/index.js';
+import type { Dataset, DatasetJson } from './dataset.js';
+/** Encode exact portable Dataset bytes without retaining runtime object identity. */
+export declare function encodeDataset(dataset: Dataset): DatasetJson;
+/** Decode one portable Dataset and re-admit its facts against the exact authored Schema. */
+export declare function decodeDataset<const Schema extends schemaLanguage.DomainSchema>(source: Schema, input: unknown): Dataset<Schema>;