@astrale-os/sdk 0.5.0-beta.99 → 0.6.0-beta.0

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>;

package/dist/testing/dataset/codec.js

@@ -0,0 +1,113 @@
+import { GraphData } from '../../platform/graph/document/index.js';
+import { isNodeId } from '../../platform/graph/node/index.js';
+import { schema as schemaApi } from '../../platform/schema/index.js';
+import { admitDatasetGraph } from './admission.js';
+import { DATASET_FORMAT, DATASET_VERSION } from './dataset.js';
+import { admitId, admitText, admitVariableName, assembleDataset } from './define.js';
+import { decodeDatasetReferences } from './references.js';
+/** Encode exact portable Dataset bytes without retaining runtime object identity. */
+export function encodeDataset(dataset) {
+    const variables = Object.freeze(Object.fromEntries(Object.entries(dataset.variables)
+        .sort(([left], [right]) => compare(left, right))
+        .map(([name, value]) => [name, encodeVariable(value)])));
+    return Object.freeze({
+        format: DATASET_FORMAT,
+        version: DATASET_VERSION,
+        id: dataset.id,
+        ...(dataset.title === undefined ? {} : { title: dataset.title }),
+        ...(dataset.description === undefined ? {} : { description: dataset.description }),
+        domain: Object.freeze({
+            origin: dataset.schema.origin,
+            revision: schemaApi.revision(dataset.schema),
+        }),
+        graph: GraphData.encode({ nodes: dataset.nodes, edges: dataset.edges }),
+        variables,
+        references: dataset.references,
+    });
+}
+/** Decode one portable Dataset and re-admit its facts against the exact authored Schema. */
+export function decodeDataset(source, input) {
+    if (!isRecord(input))
+        invalid('Dataset must be an object.');
+    exactKeys(input, [
+        'format',
+        'version',
+        'id',
+        'title',
+        'description',
+        'domain',
+        'graph',
+        'variables',
+        'references',
+    ], ['format', 'version', 'id', 'domain', 'graph', 'variables', 'references'], 'Dataset');
+    if (input.format !== DATASET_FORMAT || input.version !== DATASET_VERSION) {
+        invalid('Dataset format or version is unsupported.');
+    }
+    const id = admitId(input.id);
+    const title = admitText(input.title, 'title');
+    const description = admitText(input.description, 'description');
+    if (!isRecord(input.domain))
+        invalid('Dataset domain must be an object.');
+    exactKeys(input.domain, ['origin', 'revision'], ['origin', 'revision'], 'Dataset domain');
+    if (input.domain.origin !== source.origin) {
+        invalid(`Dataset ${id} belongs to Domain ${String(input.domain.origin)}, not ${source.origin}.`);
+    }
+    const revision = schemaApi.revision(source);
+    if (input.domain.revision !== revision) {
+        invalid(`Dataset ${id} was encoded for Schema revision ${String(input.domain.revision)}.`);
+    }
+    const domain = schemaApi.resolve(source);
+    const graph = admitDatasetGraph(id, domain, GraphData.decode(input.graph));
+    const variables = decodeVariables(input.variables, graph);
+    const references = decodeDatasetReferences(input.references, domain, graph);
+    return assembleDataset({ schema: source, id, title, description, graph, variables, references });
+}
+function encodeVariable(value) {
+    return Array.isArray(value)
+        ? Object.freeze({ nodes: Object.freeze(value.map((node) => node.id)) })
+        : Object.freeze({ node: value.id });
+}
+function decodeVariables(input, graph) {
+    if (!isRecord(input))
+        invalid('Dataset variables must be an object.');
+    return Object.freeze(Object.fromEntries(Object.entries(input)
+        .sort(([left], [right]) => compare(left, right))
+        .map(([name, value]) => [name, decodeVariable(name, value, graph)])));
+}
+function decodeVariable(name, input, graph) {
+    admitVariableName(name);
+    if (!isRecord(input))
+        invalid(`Dataset variable ${name} is invalid.`);
+    if ('node' in input) {
+        exactKeys(input, ['node'], ['node'], `Dataset variable ${name}`);
+        return requiredNode(graph, input.node, name);
+    }
+    exactKeys(input, ['nodes'], ['nodes'], `Dataset variable ${name}`);
+    if (!Array.isArray(input.nodes))
+        invalid(`Dataset variable ${name} nodes must be an array.`);
+    return Object.freeze(input.nodes.map((id) => requiredNode(graph, id, name)));
+}
+function requiredNode(graph, input, name) {
+    if (!isNodeId(input))
+        invalid(`Dataset variable ${name} has an invalid Node ID.`);
+    const node = graph.nodes.byId(input);
+    if (node === undefined)
+        invalid(`Dataset variable ${name} references missing Node ${input}.`);
+    return node;
+}
+function exactKeys(input, allowed, required, label) {
+    const actual = Reflect.ownKeys(input);
+    if (actual.some((key) => typeof key !== 'string' || !allowed.includes(key)) ||
+        required.some((key) => !actual.includes(key))) {
+        invalid(`${label} has unknown or missing fields.`);
+    }
+}
+function isRecord(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input);
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalid(message) {
+    throw new TypeError(message);
+}

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

@@ -0,0 +1,58 @@
+import type { Graph, GraphDataJson } from '../../platform/graph/document/index.js';
+import type { Edge } from '../../platform/graph/edge/index.js';
+import type { Node, NodeId } from '../../platform/graph/node/index.js';
+import type { ResolvedClass, schema } from '../../platform/schema/index.js';
+export declare const DATASET_FORMAT: 'astrale.sdk.dataset';
+export declare const DATASET_VERSION: 1;
+declare const DATASET_NODE_CLASS: unique symbol;
+/** One canonical Node fact retaining its exact authored Class as a type-only witness. */
+export type DatasetNode<Class extends ResolvedClass<'node'> = ResolvedClass<'node'>> = Node & {
+    readonly [DATASET_NODE_CLASS]: Class;
+};
+/** Canonical projected NodePath → explicit Dataset Node identity. */
+export type DatasetReferences = Readonly<Record<string, NodeId>>;
+export type DatasetVariable = DatasetNode | readonly DatasetNode[];
+export type DatasetVariables = Readonly<Record<string, DatasetVariable>>;
+/**
+ * One named, self-contained set of demo graph facts admitted against one exact Schema.
+ * It owns no deployment, authority, or execution policy; it is inert authoring material that
+ * tooling may render, encode, or seed.
+ */
+export interface Dataset<Schema extends schema.DomainSchema = schema.DomainSchema, Variables extends DatasetVariables = DatasetVariables> {
+    readonly kind: 'dataset';
+    readonly schema: Schema;
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    /** Immutable indexed Kernel Graph over exactly the admitted facts below. */
+    readonly graph: Graph;
+    readonly nodes: readonly Node[];
+    readonly edges: readonly Edge[];
+    /** Named entry points into the facts, for tooling and tests. */
+    readonly references: DatasetReferences;
+    readonly variables: Variables;
+}
+export type DatasetVariableJson = {
+    readonly node: string;
+} | {
+    readonly nodes: readonly string[];
+};
+/** Portable Dataset bytes; decoding re-admits the facts against the exact same Schema revision. */
+export interface DatasetJson {
+    readonly format: typeof DATASET_FORMAT;
+    readonly version: typeof DATASET_VERSION;
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    readonly domain: {
+        readonly origin: string;
+        readonly revision: string;
+    };
+    readonly graph: GraphDataJson;
+    readonly references: Readonly<Record<string, string>>;
+    readonly variables: Readonly<Record<string, DatasetVariableJson>>;
+}
+export type SchemaOfDataset<Value> = Value extends {
+    readonly schema: infer Schema;
+} ? Extract<Schema, schema.DomainSchema> : never;
+export {};

package/dist/testing/dataset/dataset.js

@@ -0,0 +1,2 @@
+export const DATASET_FORMAT = 'astrale.sdk.dataset';
+export const DATASET_VERSION = 1;

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

@@ -0,0 +1,33 @@
+import type { Graph } from '../../platform/graph/document/index.js';
+import type { schema as schemaLanguage } from '../../platform/schema/index.js';
+import type { DatasetGraph } from './builder.js';
+import type { Dataset, DatasetReferences, DatasetVariables } from './dataset.js';
+/** Variables returned by one graph author; `void` means the Dataset names no entry point. */
+export type AuthoredDatasetVariables = DatasetVariables | void;
+/** The exact variables record retained by a Dataset for one authored return type. */
+export type DatasetVariablesOf<Value> = [Value] extends [void] ? Readonly<Record<never, never>> : Value extends DatasetVariables ? Value : never;
+export interface DatasetInput<Schema extends schemaLanguage.DomainSchema, Variables extends AuthoredDatasetVariables> {
+    /** Stable lowercase identity, unique within one Application. */
+    readonly id: string;
+    readonly title?: string;
+    readonly description?: string;
+    /** Author every fact through the canonical graph surface; returned entries become named variables. */
+    readonly graph: (graph: DatasetGraph<Schema>) => Variables;
+}
+/** Define one inert, schema-admitted demo Dataset. Facts are validated exactly once, here. */
+export declare function defineDataset<const Schema extends schemaLanguage.DomainSchema, Variables extends AuthoredDatasetVariables = void>(source: Schema, input: DatasetInput<Schema, Variables>): Dataset<Schema, DatasetVariablesOf<Variables>>;
+/** True only for a Dataset produced by defineDataset or decodeDataset in this SDK package root. */
+export declare function isDataset(input: unknown): input is Dataset;
+/** Freeze one admitted Dataset value; shared by definition and decoding. */
+export declare function assembleDataset<Schema extends schemaLanguage.DomainSchema>(input: {
+    readonly schema: Schema;
+    readonly id: string;
+    readonly title: string | undefined;
+    readonly description: string | undefined;
+    readonly graph: Graph;
+    readonly references: DatasetReferences;
+    readonly variables: DatasetVariables;
+}): Dataset<Schema>;
+export declare function admitId(input: unknown): string;
+export declare function admitText(input: unknown, label: string): string | undefined;
+export declare function admitVariableName(input: string): string;

package/dist/testing/dataset/define.js

@@ -0,0 +1,105 @@
+import { schema as schemaApi } from '../../platform/schema/index.js';
+import { admitDatasetGraph } from './admission.js';
+import { openDatasetGraph } from './builder.js';
+const DATASET_ID = /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)*$/u;
+const VARIABLE_NAME = /^[A-Za-z][A-Za-z0-9_]*$/u;
+const admittedDatasets = new WeakSet();
+/** Define one inert, schema-admitted demo Dataset. Facts are validated exactly once, here. */
+export function defineDataset(source, input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    const allowed = new Set(['id', 'title', 'description', 'graph']);
+    if (Reflect.ownKeys(input).some((key) => !allowed.has(key)))
+        invalid();
+    const id = admitId(input.id);
+    const title = admitText(input.title, 'title');
+    const description = admitText(input.description, 'description');
+    if (typeof input.graph !== 'function')
+        throw new TypeError('Dataset graph must be a function.');
+    const domain = schemaApi.resolve(source);
+    const session = openDatasetGraph(domain);
+    const returned = input.graph(session.graph);
+    const facts = session.seal();
+    const graph = admitDatasetGraph(id, domain, { nodes: facts.nodes, edges: facts.edges });
+    const variables = admitVariables(returned, facts.created, graph);
+    return assembleDataset({
+        schema: source,
+        id,
+        title,
+        description,
+        graph,
+        variables,
+        references: facts.references,
+    });
+}
+/** True only for a Dataset produced by defineDataset or decodeDataset in this SDK package root. */
+export function isDataset(input) {
+    return input !== null && typeof input === 'object' && admittedDatasets.has(input);
+}
+/** Freeze one admitted Dataset value; shared by definition and decoding. */
+export function assembleDataset(input) {
+    const data = input.graph.toData();
+    const dataset = Object.freeze({
+        kind: 'dataset',
+        schema: input.schema,
+        id: input.id,
+        ...(input.title === undefined ? {} : { title: input.title }),
+        ...(input.description === undefined ? {} : { description: input.description }),
+        graph: input.graph,
+        nodes: data.nodes,
+        edges: data.edges,
+        variables: input.variables,
+        references: input.references,
+    });
+    admittedDatasets.add(dataset);
+    return dataset;
+}
+export function admitId(input) {
+    if (typeof input !== 'string' || !DATASET_ID.test(input)) {
+        throw new TypeError(`Dataset id ${JSON.stringify(input)} is invalid.`);
+    }
+    return input;
+}
+export function admitText(input, label) {
+    if (input === undefined)
+        return undefined;
+    if (typeof input !== 'string' || input.trim().length === 0) {
+        throw new TypeError(`Dataset ${label} must be a non-empty string.`);
+    }
+    return input;
+}
+export function admitVariableName(input) {
+    if (!VARIABLE_NAME.test(input))
+        throw new TypeError(`Dataset variable ${input} is invalid.`);
+    return input;
+}
+/** Resolve authored variables to the admitted Node values of the sealed Graph. */
+function admitVariables(input, created, graph) {
+    if (input === undefined)
+        return Object.freeze({});
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Dataset graph must return named variables or nothing.');
+    }
+    const entries = Object.entries(input)
+        .sort(([left], [right]) => compare(left, right))
+        .map(([name, value]) => {
+        admitVariableName(name);
+        const resolve = (candidate) => {
+            if (!created.has(candidate)) {
+                throw new TypeError(`Dataset variable ${name} must reference Nodes of this Dataset.`);
+            }
+            return graph.nodes.byId(candidate.id);
+        };
+        const variable = Array.isArray(value)
+            ? Object.freeze(value.map(resolve))
+            : resolve(value);
+        return [name, variable];
+    });
+    return Object.freeze(Object.fromEntries(entries));
+}
+function compare(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function invalid() {
+    throw new TypeError('Dataset definition may contain only id, title, description, and graph.');
+}

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

@@ -0,0 +1,8 @@
+export { DatasetAdmissionError } from './admission.js';
+export type { DatasetClasses, DatasetEdgeInput, DatasetEndpoint, DatasetGraph, DatasetNodeInput, } from './builder.js';
+export { decodeDataset, encodeDataset } from './codec.js';
+export { DATASET_FORMAT, DATASET_VERSION } from './dataset.js';
+export type { Dataset, DatasetJson, DatasetNode, DatasetReferences, DatasetVariable, DatasetVariableJson, DatasetVariables, SchemaOfDataset, } from './dataset.js';
+export { defineDataset, isDataset } from './define.js';
+export type { AuthoredDatasetVariables, DatasetInput, DatasetVariablesOf } from './define.js';
+export type { DatasetReferenceInput } from './references.js';

package/dist/testing/dataset/index.js

@@ -0,0 +1,4 @@
+export { DatasetAdmissionError } from './admission.js';
+export { decodeDataset, encodeDataset } from './codec.js';
+export { DATASET_FORMAT, DATASET_VERSION } from './dataset.js';
+export { defineDataset, isDataset } from './define.js';

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

@@ -0,0 +1,14 @@
+import type { Graph } from '../../platform/graph/document/index.js';
+import type { Node } from '../../platform/graph/node/index.js';
+import type { ClassRef, CoreRef, FunctionRef, PolicyRef, ViewRef, schema } from '../../platform/schema/index.js';
+import type { DatasetReferences } from './dataset.js';
+type DatasetProjectionRef = ClassRef | FunctionRef | PolicyRef | ViewRef | CoreRef;
+export type DatasetReferenceInput = DatasetProjectionRef | {
+    readonly ref: DatasetProjectionRef;
+};
+type ReferenceNode = Pick<Node, 'class' | 'props'>;
+/** Symbolic projection supplies facts; only an explicit Dataset reference supplies identity. */
+export declare function datasetReferenceNodes(domain: schema.ResolvedDomainOf<schema.DomainSchema>): ReadonlyMap<string, ReferenceNode>;
+/** Serialized reference associations lose their proof and must match the exact projection again. */
+export declare function decodeDatasetReferences(input: unknown, domain: schema.ResolvedDomainOf<schema.DomainSchema>, graph: Graph): DatasetReferences;
+export {};