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

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

package/dist/testing/dataset/references.js

@@ -0,0 +1,56 @@
+import { graph as schemaGraph } from '@astrale-os/kernel-core/schema';
+import { isNodeId } from '../../platform/graph/node/index.js';
+import { Path } from '../../platform/graph/path/index.js';
+import { bundle, schema as schemaApi } from '../../platform/schema/index.js';
+/** Symbolic projection supplies facts; only an explicit Dataset reference supplies identity. */
+export function datasetReferenceNodes(domain) {
+    const result = new Map();
+    const direct = new Set([
+        domain.origin,
+        ...Object.values(domain.dependencies).map(({ origin }) => origin),
+    ]);
+    const sourceBundle = bundle.create(domain.source);
+    for (const source of [sourceBundle.root, ...sourceBundle.closure]) {
+        if (!direct.has(source.origin))
+            continue;
+        const owner = schemaApi.resolve(source);
+        const projection = schemaGraph.project(owner);
+        const allowed = new Set(owner
+            .definitions()
+            .filter(({ ref }) => ref.origin === owner.origin &&
+            ['class', 'function', 'policy', 'view', 'core'].includes(ref.kind))
+            .map(({ ref }) => Path.project(ref).raw));
+        for (const part of [projection.managed, projection.core]) {
+            for (const node of part.graph.nodes) {
+                if (!('as' in node))
+                    continue;
+                const path = part.paths.get(node.as);
+                if (path !== undefined && allowed.has(path))
+                    result.set(path, node);
+            }
+        }
+    }
+    return result;
+}
+/** Serialized reference associations lose their proof and must match the exact projection again. */
+export function decodeDatasetReferences(input, domain, graph) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError('Dataset references must be an object.');
+    }
+    const entries = Object.entries(input);
+    const projected = entries.length === 0 ? new Map() : datasetReferenceNodes(domain);
+    const identities = new Set();
+    for (const [path, id] of entries) {
+        const expected = projected.get(path);
+        const actual = isNodeId(id) ? graph.nodes.byId(id) : undefined;
+        if (expected === undefined ||
+            actual === undefined ||
+            identities.has(actual.id) ||
+            expected.class !== actual.class ||
+            JSON.stringify(expected.props) !== JSON.stringify(actual.props)) {
+            throw new TypeError(`Dataset reference ${path} does not identify its projected Node.`);
+        }
+        identities.add(actual.id);
+    }
+    return Object.freeze(Object.fromEntries(entries));
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,9 @@
+/** Development and test resources: schema-admitted demo Datasets and their lazy project references. */
+export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset, defineDataset, encodeDataset, isDataset, } from './dataset/index.js';
+export type { AuthoredDatasetVariables, Dataset, DatasetClasses, DatasetEdgeInput, DatasetEndpoint, DatasetGraph, DatasetInput, DatasetJson, DatasetNode, DatasetNodeInput, DatasetReferences, DatasetReferenceInput, DatasetVariable, DatasetVariableJson, DatasetVariables, DatasetVariablesOf, SchemaOfDataset, } from './dataset/index.js';
+export { loadDataset, loadDatasets } from './load.js';
+export type { DatasetModuleLoader, LoadedDataset } from './load.js';
+export { dataset, isDatasetReference } from './reference.js';
+export type { DatasetReference } from './reference.js';
+export { isTests, tests } from './tests.js';
+export type { Tests, TestsInput } from './tests.js';

package/dist/testing/index.js

@@ -0,0 +1,5 @@
+/** Development and test resources: schema-admitted demo Datasets and their lazy project references. */
+export { DATASET_FORMAT, DATASET_VERSION, DatasetAdmissionError, decodeDataset, defineDataset, encodeDataset, isDataset, } from './dataset/index.js';
+export { loadDataset, loadDatasets } from './load.js';
+export { dataset, isDatasetReference } from './reference.js';
+export { isTests, tests } from './tests.js';

package/dist/testing/load.d.ts

@@ -0,0 +1,14 @@
+import type { schema } from '../platform/schema/index.js';
+import type { Dataset } from './dataset/index.js';
+import type { DatasetReference } from './reference.js';
+import type { Tests } from './tests.js';
+/** Import one referenced module; tooling owns path resolution against `astrale.config.ts`. */
+export type DatasetModuleLoader = (path: string) => unknown | Promise<unknown>;
+export interface LoadedDataset {
+    readonly reference: DatasetReference;
+    readonly dataset: Dataset;
+}
+/** Load the one default Dataset of a referenced module and prove it targets the exact Schema. */
+export declare function loadDataset(reference: DatasetReference, load: DatasetModuleLoader, source: schema.DomainSchema): Promise<LoadedDataset>;
+/** Load every referenced Dataset of one Tests value in declared order, rejecting duplicate ids. */
+export declare function loadDatasets(value: Tests, load: DatasetModuleLoader, source: schema.DomainSchema): Promise<readonly LoadedDataset[]>;

package/dist/testing/load.js

@@ -0,0 +1,44 @@
+import { isDataset } from './dataset/index.js';
+import { isDatasetReference } from './reference.js';
+import { isTests } from './tests.js';
+/** Load the one default Dataset of a referenced module and prove it targets the exact Schema. */
+export async function loadDataset(reference, load, source) {
+    if (!isDatasetReference(reference)) {
+        throw new TypeError('Dataset reference must be created by dataset(path).');
+    }
+    if (typeof load !== 'function')
+        throw new TypeError('Dataset module loader must be a function.');
+    const loaded = await load(reference.path);
+    if (loaded === null ||
+        typeof loaded !== 'object' ||
+        Array.isArray(loaded) ||
+        !Object.hasOwn(loaded, 'default') ||
+        Object.keys(loaded).some((key) => key !== 'default')) {
+        throw new TypeError(`Dataset module ${reference.path} must export exactly one default Dataset.`);
+    }
+    const dataset = Reflect.get(loaded, 'default');
+    if (!isDataset(dataset)) {
+        throw new TypeError(`Dataset module ${reference.path} default export is not an admitted Dataset.`);
+    }
+    if (dataset.schema !== source) {
+        throw new TypeError(`Dataset ${dataset.id} (${reference.path}) targets Schema ${dataset.schema.origin}, not the exact Application Schema.`);
+    }
+    return Object.freeze({ reference, dataset });
+}
+/** Load every referenced Dataset of one Tests value in declared order, rejecting duplicate ids. */
+export async function loadDatasets(value, load, source) {
+    if (!isTests(value))
+        throw new TypeError('Tests value must be created by tests().');
+    const loaded = [];
+    const ids = new Map();
+    for (const reference of value.datasets) {
+        const entry = await loadDataset(reference, load, source);
+        const previous = ids.get(entry.dataset.id);
+        if (previous !== undefined) {
+            throw new TypeError(`Dataset id ${entry.dataset.id} is defined by both ${previous} and ${reference.path}.`);
+        }
+        ids.set(entry.dataset.id, reference.path);
+        loaded.push(entry);
+    }
+    return Object.freeze(loaded);
+}

package/dist/testing/reference.d.ts

@@ -0,0 +1,11 @@
+/** One stable Dataset module coordinate relative to the project configuration. */
+export interface DatasetReference {
+    readonly kind: 'dataset-reference';
+    readonly path: string;
+}
+/**
+ * Reference one Dataset module lazily. Importing the project configuration never loads the
+ * referenced module; tooling resolves the path against `astrale.config.ts` on demand.
+ */
+export declare function dataset(path: string): DatasetReference;
+export declare function isDatasetReference(input: unknown): input is DatasetReference;

package/dist/testing/reference.js

@@ -0,0 +1,19 @@
+const references = new WeakSet();
+/**
+ * Reference one Dataset module lazily. Importing the project configuration never loads the
+ * referenced module; tooling resolves the path against `astrale.config.ts` on demand.
+ */
+export function dataset(path) {
+    if (typeof path !== 'string' ||
+        path.length === 0 ||
+        path.trim() !== path ||
+        path.includes('\0')) {
+        throw new TypeError('Dataset path must be a non-empty stable module coordinate.');
+    }
+    const reference = Object.freeze({ kind: 'dataset-reference', path });
+    references.add(reference);
+    return reference;
+}
+export function isDatasetReference(input) {
+    return input !== null && typeof input === 'object' && references.has(input);
+}

package/dist/testing/tests.d.ts

@@ -0,0 +1,12 @@
+import type { DatasetReference } from './reference.js';
+/** Development and test resources of one project. Never part of a Build, Release, or install. */
+export interface Tests {
+    readonly kind: 'tests';
+    readonly datasets: readonly DatasetReference[];
+}
+export interface TestsInput {
+    readonly datasets?: readonly DatasetReference[];
+}
+/** Capture the inert test resources of a project; Dataset modules stay unloaded. */
+export declare function tests(input?: TestsInput): Tests;
+export declare function isTests(input: unknown): input is Tests;

package/dist/testing/tests.js

@@ -0,0 +1,31 @@
+import { isDatasetReference } from './reference.js';
+const admittedTests = new WeakSet();
+/** Capture the inert test resources of a project; Dataset modules stay unloaded. */
+export function tests(input = {}) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    if (Reflect.ownKeys(input).some((key) => key !== 'datasets'))
+        invalid();
+    const datasets = input.datasets ?? [];
+    if (!Array.isArray(datasets))
+        throw new TypeError('Tests datasets must be an array.');
+    const paths = new Set();
+    for (const reference of datasets) {
+        if (!isDatasetReference(reference)) {
+            throw new TypeError('Tests datasets must contain only references created by dataset(path).');
+        }
+        if (paths.has(reference.path)) {
+            throw new TypeError(`Dataset ${reference.path} is referenced more than once.`);
+        }
+        paths.add(reference.path);
+    }
+    const value = Object.freeze({ kind: 'tests', datasets: Object.freeze([...datasets]) });
+    admittedTests.add(value);
+    return value;
+}
+export function isTests(input) {
+    return input !== null && typeof input === 'object' && admittedTests.has(input);
+}
+function invalid() {
+    throw new TypeError('Tests definition may contain only datasets.');
+}

package/dist/tooling/cli/arguments.d.ts

@@ -0,0 +1,17 @@
+import type { LintReportFormat } from '../linter/index.js';
+export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'test', 'lint', 'package'];
+export type Command = (typeof COMMANDS)[number];
+export interface ParsedArgs {
+    readonly command: Command;
+    readonly env: string;
+    readonly fix?: boolean;
+    readonly format?: LintReportFormat;
+    readonly deployOnly?: boolean;
+    readonly identity?: string;
+    readonly credentialFile?: string;
+    readonly suite?: string;
+    readonly sessionFile?: string;
+    readonly secretsFile?: string;
+}
+/** Parse the frozen `astrale-domain` command grammar without performing effects. */
+export declare function parseArgs(argv: readonly string[]): ParsedArgs;