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

package/dist/application/mutation/authoring/builder.js

@@ -0,0 +1,102 @@
+import { ClassKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import { LocalAlias } from '../../../platform/graph/alias.js';
+import { endpoint, existingEndpoint } from './endpoint.js';
+import { precondition } from './precondition.js';
+import { conditions, delta, properties } from './properties.js';
+import { authorStateTransition, } from './transition.js';
+export function richMutationBuilder(core) {
+    const expectation = Object.freeze({
+        node(input) {
+            core.expect.node({
+                node: existingEndpoint(input.node),
+                class: classKey(input.class),
+                ...(input.props === undefined ? {} : { props: conditions(input.class, input.props) }),
+            });
+            return rich;
+        },
+        edge(input) {
+            core.expect.edge({
+                source: existingEndpoint(input.source),
+                target: existingEndpoint(input.target),
+                class: classKey(input.class),
+                ...(Object.hasOwn(input, 'slug') ? { slug: input.slug ?? null } : {}),
+                ...(input.props === undefined ? {} : { props: conditions(input.class, input.props) }),
+            });
+            return rich;
+        },
+        query(input) {
+            precondition(core, input);
+            return rich;
+        },
+    });
+    const rich = Object.freeze({
+        expect: expectation,
+        createNode(input) {
+            const created = core.createNode({
+                as: LocalAlias(input.as),
+                class: classKey(input.class),
+                ...(input.props === undefined ? {} : { props: properties(input.class, input.props) }),
+            });
+            return Object.freeze({ ...created, class: input.class });
+        },
+        updateNode(input) {
+            core.updateNode({
+                node: existingEndpoint(input.node),
+                class: classKey(input.class),
+                props: delta(input.class, input.props),
+            });
+            return rich;
+        },
+        transition(input) {
+            authorStateTransition(core, input);
+            return rich;
+        },
+        deleteNode(input) {
+            core.deleteNode({ node: existingEndpoint(input.node), class: classKey(input.class) });
+            return rich;
+        },
+        createEdge(input) {
+            core.createEdge({
+                class: classKey(input.class),
+                source: endpoint(input.source),
+                target: endpoint(input.target),
+                ...(input.slug === undefined ? {} : { slug: input.slug }),
+                ...(input.props === undefined ? {} : { props: properties(input.class, input.props) }),
+            });
+            return rich;
+        },
+        updateEdge(input) {
+            const selector = {
+                source: existingEndpoint(input.source),
+                target: existingEndpoint(input.target),
+                class: classKey(input.class),
+            };
+            const patch = input.props === undefined ? undefined : delta(input.class, input.props);
+            if (Object.hasOwn(input, 'slug')) {
+                core.updateEdge({
+                    ...selector,
+                    slug: input.slug ?? null,
+                    ...(patch === undefined ? {} : { props: patch }),
+                });
+            }
+            else {
+                if (patch === undefined)
+                    throw new TypeError('Edge update must change slug or properties.');
+                core.updateEdge({ ...selector, props: patch });
+            }
+            return rich;
+        },
+        deleteEdge(input) {
+            core.deleteEdge({
+                source: existingEndpoint(input.source),
+                target: existingEndpoint(input.target),
+                class: classKey(input.class),
+            });
+            return rich;
+        },
+    });
+    return rich;
+}
+function classKey(selected) {
+    return ClassKey(selected.key);
+}

package/dist/application/mutation/authoring/endpoint.d.ts

@@ -0,0 +1,16 @@
+import type { NodeId } from '@astrale-os/kernel-core/graph/node';
+import type { NodeTarget } from '@astrale-os/kernel-core/path';
+import type { ResolvedClass } from '@astrale-os/kernel-dsl/v1';
+import type { LocalAlias } from '../../../platform/graph/alias.js';
+export interface CreatedNode<Class extends ResolvedClass<'node'> = ResolvedClass<'node'>> {
+    readonly created: LocalAlias;
+    readonly class: Class;
+}
+export type ExistingEndpoint = NodeTarget | Readonly<{
+    id: NodeId;
+}>;
+export type MutationEndpoint = ExistingEndpoint | CreatedNode;
+export declare function endpoint(input: MutationEndpoint): NodeTarget | {
+    readonly created: LocalAlias;
+};
+export declare function existingEndpoint(input: ExistingEndpoint): NodeTarget;

package/dist/application/mutation/authoring/endpoint.js

@@ -0,0 +1,22 @@
+export function endpoint(input) {
+    if (isDefinitionRefCandidate(input))
+        return input;
+    if (isCreated(input))
+        return Object.freeze({ created: input.created });
+    return existingEndpoint(input);
+}
+export function existingEndpoint(input) {
+    if (isDefinitionRefCandidate(input))
+        return input;
+    return typeof input === 'object' && input !== null && 'id' in input
+        ? input.id
+        : input;
+}
+// Keep DefinitionRef candidates intact for Kernel admission: an extra id/created
+// field must not silently redirect the operation to a different Node.
+function isDefinitionRefCandidate(input) {
+    return typeof input === 'object' && input !== null && 'kind' in input;
+}
+function isCreated(input) {
+    return typeof input === 'object' && input !== null && 'created' in input;
+}

package/dist/application/mutation/authoring/index.d.ts

@@ -0,0 +1,4 @@
+export { richMutationBuilder, type EdgeSelector, type RichMutationBuilder } from './builder.js';
+export type { CreatedNode, ExistingEndpoint, MutationEndpoint } from './endpoint.js';
+export type { RichPropertyConditions, RichPropertyDelta, RichPropertyInput, RichPropertyName, } from './properties.js';
+export type { QueryPrecondition } from './precondition.js';

package/dist/application/mutation/authoring/index.js

@@ -0,0 +1 @@
+export { richMutationBuilder } from './builder.js';

package/dist/application/mutation/authoring/precondition.d.ts

@@ -0,0 +1,7 @@
+import type { MutationBuilder } from '@astrale-os/kernel-core/graph/mutate';
+import type { QueryEdgeAST, QueryNodeAST, QueryResultFor, QuerySelectionFor } from '@astrale-os/kernel-core/graph/query';
+export interface QueryPrecondition<Query extends QueryNodeAST | QueryEdgeAST> {
+    readonly query: Query;
+    readonly equals: QuerySelectionFor<QueryResultFor<Query>>;
+}
+export declare function precondition<Query extends QueryNodeAST | QueryEdgeAST>(core: MutationBuilder, input: QueryPrecondition<Query>): void;

package/dist/application/mutation/authoring/precondition.js

@@ -0,0 +1,8 @@
+export function precondition(core, input) {
+    if (input.equals.kind === 'node') {
+        core.expect.query({ query: input.query, equals: input.equals });
+    }
+    else {
+        core.expect.query({ query: input.query, equals: input.equals });
+    }
+}

package/dist/application/mutation/authoring/properties.d.ts

@@ -0,0 +1,22 @@
+import type { MutationPropsInput } from '@astrale-os/kernel-core/graph/mutate';
+import type { PropertyInputOf, ResolvedClass, ResolvedProperty } from '@astrale-os/kernel-dsl/v1';
+export type RichPropertyInput<Class> = PropertyInputOf<Class>;
+export type RichPropertyName<Class> = Extract<keyof PropertyInputOf<Class>, string>;
+export interface RichPropertyConditions<Class> {
+    readonly equals?: RichPropertyInput<Class>;
+    readonly absent?: readonly RichPropertyName<Class>[];
+}
+export interface RichPropertyDelta<Class> {
+    readonly set?: RichPropertyInput<Class>;
+    readonly unset?: readonly RichPropertyName<Class>[];
+}
+export declare function properties<Class extends ResolvedClass>(selected: Class, input: RichPropertyInput<Class>): MutationPropsInput;
+export declare function conditions<Class extends ResolvedClass>(selected: Class, input: RichPropertyConditions<Class>): Readonly<{
+    equals?: Readonly<Record<`${string}:class.${string}.property.${string}`, import("@astrale-os/kernel-dsl/value").Value>> | undefined;
+    absent?: readonly `${string}:class.${string}.property.${string}`[] | undefined;
+}>;
+export declare function delta<Class extends ResolvedClass>(selected: Class, input: RichPropertyDelta<Class>): Readonly<{
+    set: Readonly<Record<`${string}:class.${string}.property.${string}`, import("@astrale-os/kernel-dsl/value").Value>>;
+    unset: readonly `${string}:class.${string}.property.${string}`[];
+}>;
+export declare function resolvedProperty<Class extends ResolvedClass>(selected: Class, name: RichPropertyName<Class>): ResolvedProperty;

package/dist/application/mutation/authoring/properties.js

@@ -0,0 +1,29 @@
+import { PropertyKey } from '@astrale-os/kernel-dsl/v1/addressing';
+export function properties(selected, input) {
+    return selected.properties.from(input);
+}
+export function conditions(selected, input) {
+    return Object.freeze({
+        ...(input.equals === undefined ? {} : { equals: properties(selected, input.equals) }),
+        ...(input.absent === undefined
+            ? {}
+            : {
+                absent: Object.freeze(input.absent.map((name) => resolvedProperty(selected, name).key)),
+            }),
+    });
+}
+export function delta(selected, input) {
+    return Object.freeze({
+        set: properties(selected, input.set ?? {}),
+        unset: Object.freeze((input.unset ?? []).map((name) => resolvedProperty(selected, name).key)),
+    });
+}
+export function resolvedProperty(selected, name) {
+    const value = PropertyKey.is(name)
+        ? selected.properties.get(PropertyKey(name))
+        : Reflect.get(selected.properties, name);
+    if (value === undefined || value === null || typeof value !== 'object' || !('key' in value)) {
+        throw new TypeError(`Property ${name} is absent or ambiguous on ${selected.key}.`);
+    }
+    return value;
+}

package/dist/application/mutation/authoring/transition.d.ts

@@ -0,0 +1,26 @@
+import type { MutationBuilder } from '@astrale-os/kernel-core/graph/mutate';
+import type { ResolvedClass, ResolvedProperty } from '@astrale-os/kernel-dsl/v1';
+import type { StateTopology } from '@astrale-os/kernel-dsl/v1/language/state';
+import type { ExistingEndpoint } from './endpoint.js';
+import type { RichPropertyConditions, RichPropertyDelta, RichPropertyName } from './properties.js';
+type PropertyEntry<Class extends ResolvedClass<'node'>> = Class['properties']['byKey'][keyof Class['properties']['byKey']];
+type TopologyOfProperty<Property> = Property extends ResolvedProperty<unknown, boolean, infer Topology extends StateTopology | undefined> ? Extract<Topology, StateTopology> : never;
+type StatePropertyEntry<Property> = Property extends ResolvedProperty ? [TopologyOfProperty<Property>] extends [never] ? never : Property : never;
+export type StatePropertyName<Class extends ResolvedClass<'node'>> = Extract<StatePropertyEntry<PropertyEntry<Class>>['name'], RichPropertyName<Class>>;
+export type StatePropertyTopology<Class extends ResolvedClass<'node'>, Property extends StatePropertyName<Class>> = TopologyOfProperty<Extract<StatePropertyEntry<PropertyEntry<Class>>, {
+    readonly name: Property;
+}>>;
+export type StateOfTopology<Topology extends StateTopology> = Extract<keyof Topology['transitions'], string>;
+export type EventOfTopology<Topology extends StateTopology, State extends StateOfTopology<Topology>> = State extends StateOfTopology<Topology> ? Extract<keyof Topology['transitions'][State], string> : never;
+export interface StateTransitionInput<Class extends ResolvedClass<'node'>, Property extends StatePropertyName<Class>, From extends StateOfTopology<StatePropertyTopology<Class, Property>>, Event extends EventOfTopology<StatePropertyTopology<Class, Property>, From>> {
+    readonly node: ExistingEndpoint;
+    readonly class: Class;
+    readonly property: Property;
+    readonly from: From;
+    readonly event: Event;
+    readonly props?: RichPropertyConditions<Class>;
+    /** Auxiliary property changes committed in the same compare-and-set as the state transition. */
+    readonly update?: RichPropertyDelta<Class>;
+}
+export declare function authorStateTransition<Class extends ResolvedClass<'node'>, Property extends StatePropertyName<Class>, From extends StateOfTopology<StatePropertyTopology<Class, Property>>, Event extends EventOfTopology<StatePropertyTopology<Class, Property>, From>>(core: MutationBuilder, input: StateTransitionInput<Class, Property, From, Event>): void;
+export {};

package/dist/application/mutation/authoring/transition.js

@@ -0,0 +1,63 @@
+import { ClassKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import { stateTransitionFailure } from '../failure.js';
+import { existingEndpoint } from './endpoint.js';
+import { conditions, delta, resolvedProperty } from './properties.js';
+export function authorStateTransition(core, input) {
+    const node = existingEndpoint(input.node);
+    const selectedClass = input.class;
+    const property = input.property;
+    const fromState = input.from;
+    const event = input.event;
+    const suppliedProps = input.props;
+    const suppliedUpdate = input.update;
+    const equals = suppliedProps?.equals;
+    const absent = suppliedProps?.absent;
+    const set = suppliedUpdate?.set;
+    const unset = suppliedUpdate?.unset;
+    const suppliedEquals = equals === undefined ? undefined : { ...equals };
+    const suppliedAbsent = absent === undefined ? undefined : [...absent];
+    const suppliedSet = set === undefined ? undefined : { ...set };
+    const suppliedUnset = unset === undefined ? undefined : [...unset];
+    const selected = resolvedProperty(selectedClass, property);
+    const selectedClassKey = ClassKey(selectedClass.key);
+    const topology = selected.definition.state;
+    if (topology === undefined) {
+        throw new TypeError(`State transition requires StateProperty ${selectedClassKey}.${String(property)} on the selected Class.`);
+    }
+    if (typeof fromState !== 'string' || !Object.hasOwn(topology.transitions, fromState)) {
+        throw new TypeError(`State machine does not declare state "${String(fromState)}".`);
+    }
+    if (typeof event !== 'string' ||
+        !Object.values(topology.transitions).some((events) => Object.hasOwn(events, event))) {
+        throw new TypeError(`State machine does not declare event "${String(event)}".`);
+    }
+    const target = topology.transitions[fromState]?.[event];
+    if (target === undefined)
+        throw stateTransitionFailure(fromState, event);
+    const from = { [property]: fromState };
+    const to = { [property]: target };
+    if ((suppliedEquals !== undefined &&
+        Object.hasOwn(suppliedEquals, property) &&
+        suppliedEquals[property] !== fromState) ||
+        suppliedAbsent?.includes(property) === true ||
+        (suppliedSet !== undefined && Object.hasOwn(suppliedSet, property)) ||
+        suppliedUnset?.includes(property) === true) {
+        throw new TypeError(`StateMachine transition conditions conflict with property ${String(property)}.`);
+    }
+    core.expect.node({
+        node,
+        class: selectedClassKey,
+        props: conditions(selectedClass, {
+            ...(suppliedAbsent === undefined ? {} : { absent: suppliedAbsent }),
+            equals: { ...suppliedEquals, ...from },
+        }),
+    });
+    core.updateNode({
+        node,
+        class: selectedClassKey,
+        props: delta(selectedClass, {
+            set: { ...suppliedSet, ...to },
+            ...(suppliedUnset === undefined ? {} : { unset: suppliedUnset }),
+        }),
+    });
+}

package/dist/application/mutation/define.d.ts

@@ -0,0 +1,12 @@
+import type { MutationResult } from '@astrale-os/kernel-core/graph/mutate';
+import type { Domain, schema } from '../../platform/schema/index.js';
+import type { Mutation, MutationDefinition } from './mutation.js';
+type ResolvedDomainOf<Schema extends schema.DomainSchema> = Extract<schema.DomainOf<Schema>, Domain>;
+type AuthoringDomainOf<Schema extends schema.DomainSchema> = ResolvedDomainOf<Schema>;
+interface MutationProjector<Schema extends schema.DomainSchema> {
+    <Input, Output = MutationResult>(project: (domain: AuthoringDomainOf<Schema>) => MutationDefinition<Input, Output>): Mutation<ResolvedDomainOf<Schema>, Input, Output>;
+}
+/** Define one inert Mutation recipe projected from its exact loaded Domain. */
+export declare function defineMutation<Schema extends schema.DomainSchema>(): MutationProjector<Schema>;
+export declare function realizeMutation<DomainValue extends Domain, Input, Output>(mutation: Mutation<DomainValue, Input, Output>, domain: DomainValue): MutationDefinition<Input, Output>;
+export {};

package/dist/application/mutation/define.js

@@ -0,0 +1,56 @@
+import { isDomain } from '@astrale-os/kernel-dsl/v1/domain';
+const projectors = new WeakMap();
+const realized = new WeakMap();
+/** Define one inert Mutation recipe projected from its exact loaded Domain. */
+export function defineMutation() {
+    return ((project) => {
+        if (typeof project !== 'function')
+            throw new TypeError('Mutation projection must be a function.');
+        const mutation = Object.freeze({ kind: 'mutation' });
+        projectors.set(mutation, project);
+        return mutation;
+    });
+}
+export function realizeMutation(mutation, domain) {
+    const project = projectors.get(mutation);
+    if (project === undefined)
+        throw new TypeError('Mutation must be produced by defineMutation.');
+    if (!isDomain(domain))
+        throw new TypeError('Mutation projection requires an admitted Domain.');
+    let byDomain = realized.get(mutation);
+    const cached = byDomain?.get(domain);
+    if (cached !== undefined)
+        return cached;
+    const authored = project(domain);
+    if (isPromiseLike(authored))
+        throw new TypeError('Mutation projection must be synchronous.');
+    const admitted = admitMutation(authored);
+    if (byDomain === undefined) {
+        byDomain = new WeakMap();
+        realized.set(mutation, byDomain);
+    }
+    byDomain.set(domain, admitted);
+    return admitted;
+}
+function admitMutation(definition) {
+    if (definition === null || typeof definition !== 'object' || Array.isArray(definition))
+        invalid();
+    if (typeof definition.id !== 'string' ||
+        definition.id.length === 0 ||
+        definition.id.trim() !== definition.id ||
+        typeof definition.build !== 'function' ||
+        (definition.project !== undefined && typeof definition.project !== 'function') ||
+        (definition.reject !== undefined && typeof definition.reject !== 'function') ||
+        Reflect.ownKeys(definition).some((key) => key !== 'id' && key !== 'build' && key !== 'project' && key !== 'reject')) {
+        invalid();
+    }
+    return Object.freeze({ ...definition });
+}
+function invalid() {
+    throw new TypeError('Mutation definition is invalid.');
+}
+function isPromiseLike(input) {
+    return (input !== null &&
+        (typeof input === 'object' || typeof input === 'function') &&
+        typeof input.then === 'function');
+}

package/dist/application/mutation/execution/execute.d.ts

@@ -0,0 +1,9 @@
+import { type MutationAST as MutationASTValue, type MutationResult } from '@astrale-os/kernel-core/graph/mutate';
+import type { GraphMutationOptions } from '../../../platform/client/index.js';
+import type { Domain } from '../../../platform/schema/index.js';
+import type { Mutation } from '../mutation.js';
+/** Exact caller-scoped canonical document capability required by Mutation execution. */
+export type MutationClient = Readonly<{
+    mutate(ast: MutationASTValue, options?: GraphMutationOptions): Promise<MutationResult>;
+}>;
+export declare function executeMutation<DomainValue extends Domain, Input, Output>(client: MutationClient, domain: DomainValue, definition: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;

package/dist/application/mutation/execution/execute.js

@@ -0,0 +1,21 @@
+import { MutationAST, } from '@astrale-os/kernel-core/graph/mutate';
+import { richMutationBuilder } from '../authoring/index.js';
+import { realizeMutation } from '../define.js';
+import { mutationFailure } from '../failure.js';
+import { projectMutation } from './projection.js';
+export async function executeMutation(client, domain, definition, input) {
+    if (client === null || typeof client !== 'object' || typeof client.mutate !== 'function') {
+        throw new TypeError('Mutation execution requires a Client mutate capability.');
+    }
+    const operation = realizeMutation(definition, domain);
+    try {
+        const ast = MutationAST.build((builder) => operation.build(input, richMutationBuilder(builder)));
+        return projectMutation(operation, await client.mutate(ast, { expected: domain.closure }), input);
+    }
+    catch (cause) {
+        const expected = mutationFailure(cause);
+        if (operation.reject !== undefined && expected !== undefined)
+            return operation.reject(expected);
+        throw cause;
+    }
+}

package/dist/application/mutation/execution/executor.d.ts

@@ -0,0 +1,13 @@
+import type { Domain, schema } from '../../../platform/schema/index.js';
+import type { Mutation } from '../mutation.js';
+import type { MutationClient } from './execute.js';
+/** Invocation-bound executor for authored Mutation definitions. */
+export interface MutationExecutor<DomainValue extends Domain = Domain> {
+    <Input, Output>(definition: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;
+}
+type ExecutableDomain<DomainValue extends Domain> = DomainValue extends {
+    readonly source: infer Source extends schema.DomainSchema;
+} ? Extract<schema.DomainOf<Source>, Domain> : DomainValue;
+/** Private Runtime binding to one Client and the exact loaded root Domain. */
+export declare function bindMutation<DomainValue extends Domain>(client: MutationClient, domain: DomainValue): MutationExecutor<ExecutableDomain<DomainValue>>;
+export {};

package/dist/application/mutation/execution/executor.js

@@ -0,0 +1,7 @@
+import { executeMutation } from './execute.js';
+/** Private Runtime binding to one Client and the exact loaded root Domain. */
+export function bindMutation(client, domain) {
+    const executable = domain;
+    const execute = (definition, input) => executeMutation(client, executable, definition, input);
+    return execute;
+}

package/dist/application/mutation/execution/index.d.ts

@@ -0,0 +1,2 @@
+export { executeMutation, type MutationClient } from './execute.js';
+export type { MutationExecutor } from './executor.js';

package/dist/application/mutation/execution/index.js

@@ -0,0 +1 @@
+export { executeMutation } from './execute.js';

package/dist/application/mutation/execution/projection.d.ts

@@ -0,0 +1,3 @@
+import type { MutationResult } from '@astrale-os/kernel-core/graph/mutate';
+import type { MutationDefinition } from '../mutation.js';
+export declare function projectMutation<Input, Output>(definition: MutationDefinition<Input, Output>, result: MutationResult, input: Input): Output;

package/dist/application/mutation/execution/projection.js

@@ -0,0 +1,3 @@
+export function projectMutation(definition, result, input) {
+    return (definition.project === undefined ? result : definition.project(result, input));
+}

package/dist/application/mutation/failure.d.ts

@@ -0,0 +1,13 @@
+export interface KernelMutationFailure extends Error {
+    readonly code: `MUTATION_${string}`;
+    readonly outcomeKnown: boolean;
+}
+export interface StateTransitionFailure extends Error {
+    readonly code: 'STATE_TRANSITION_ILLEGAL';
+    readonly outcomeKnown: true;
+    readonly from: string;
+    readonly event: string;
+}
+export type MutationFailure = KernelMutationFailure | StateTransitionFailure;
+export declare function stateTransitionFailure(from: string, event: string): StateTransitionFailure;
+export declare function mutationFailure(input: unknown): MutationFailure | undefined;

package/dist/application/mutation/failure.js

@@ -0,0 +1,51 @@
+const UNKNOWN_OUTCOME_CODES = new Set(['MUTATION_OUTCOME_UNKNOWN']);
+const localStateTransitionFailures = new WeakSet();
+export function stateTransitionFailure(from, event) {
+    const failure = Object.assign(new Error(`State transition is illegal: ${from} + ${event}.`), {
+        code: 'STATE_TRANSITION_ILLEGAL',
+        outcomeKnown: true,
+        from,
+        event,
+    });
+    localStateTransitionFailures.add(failure);
+    return failure;
+}
+export function mutationFailure(input) {
+    if (!(input instanceof Error))
+        return undefined;
+    const code = mutationCode(input);
+    if (code === undefined)
+        return undefined;
+    const explicit = input.outcomeKnown;
+    if (explicit !== undefined && typeof explicit !== 'boolean')
+        return undefined;
+    if (code === 'STATE_TRANSITION_ILLEGAL') {
+        if (!localStateTransitionFailures.has(input))
+            return undefined;
+        const from = Reflect.get(input, 'from');
+        const event = Reflect.get(input, 'event');
+        if (typeof from !== 'string' || typeof event !== 'string' || explicit === false)
+            return undefined;
+        return input;
+    }
+    return Object.assign(new Error(input.message, { cause: input }), {
+        code,
+        outcomeKnown: explicit !== false && !UNKNOWN_OUTCOME_CODES.has(code),
+    });
+}
+function mutationCode(input) {
+    const value = input;
+    if (value.code === 'STATE_TRANSITION_ILLEGAL')
+        return value.code;
+    for (const candidate of [value.code, nestedCode(value.reason), nestedCode(value.data)]) {
+        if (typeof candidate === 'string' && candidate.startsWith('MUTATION_')) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+function nestedCode(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input)
+        ? Reflect.get(input, 'code')
+        : undefined;
+}

package/dist/application/mutation/index.d.ts

@@ -0,0 +1,8 @@
+export { defineMutation } from './define.js';
+export { executeMutation, type MutationClient, type MutationExecutor } from './execution/index.js';
+export type { MutationFailure } from './failure.js';
+export type { Mutation, MutationDefinition, MutationInputOf, MutationOutputOf } from './mutation.js';
+export type { CreatedNode, EdgeSelector, ExistingEndpoint, MutationEndpoint, QueryPrecondition, RichMutationBuilder, RichPropertyConditions, RichPropertyDelta, RichPropertyInput, RichPropertyName, } from './authoring/index.js';
+/** Canonical low-level Mutation documents remain available as the explicit escape hatch. */
+export * from '@astrale-os/kernel-core/graph/mutate';
+export type { LocalAlias, LocalBinding } from '../../platform/graph/alias.js';

package/dist/application/mutation/index.js

@@ -0,0 +1,4 @@
+export { defineMutation } from './define.js';
+export { executeMutation } from './execution/index.js';
+/** Canonical low-level Mutation documents remain available as the explicit escape hatch. */
+export * from '@astrale-os/kernel-core/graph/mutate';

package/dist/application/mutation/mutation.d.ts

@@ -0,0 +1,24 @@
+import type { MutationResult } from '@astrale-os/kernel-core/graph/mutate';
+import type { Domain } from '../../platform/schema/index.js';
+import type { RichMutationBuilder } from './authoring/index.js';
+import type { MutationFailure } from './failure.js';
+declare const MUTATION_DOMAIN: unique symbol;
+declare const MUTATION_INPUT: unique symbol;
+declare const MUTATION_OUTPUT: unique symbol;
+/** Inert Domain-bound Mutation recipe. Its projector is retained privately by the SDK. */
+export interface Mutation<DomainValue extends Domain = Domain, Input = unknown, Output = MutationResult> {
+    readonly kind: 'mutation';
+    readonly [MUTATION_DOMAIN]: (domain: DomainValue) => DomainValue;
+    readonly [MUTATION_INPUT]?: Input;
+    readonly [MUTATION_OUTPUT]?: Output;
+}
+/** Canonical admitted operation produced by realizing one Mutation recipe. */
+export interface MutationDefinition<Input, Output = MutationResult> {
+    readonly id: string;
+    build(input: Input, mutation: RichMutationBuilder): undefined;
+    project?(result: MutationResult, input: NoInfer<Input>): Output;
+    reject?(failure: MutationFailure): Output;
+}
+export type MutationInputOf<Value> = Value extends Mutation<infer _Domain, infer Input, infer _Output> ? Input : Value extends MutationDefinition<infer Input, infer _Output> ? Input : never;
+export type MutationOutputOf<Value> = Value extends Mutation<infer _Domain, infer _Input, infer Output> ? Output : Value extends MutationDefinition<infer _Input, infer Output> ? Output : never;
+export {};

package/dist/application/mutation/mutation.js

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

package/dist/application/query/collection/identity.d.ts

@@ -0,0 +1,4 @@
+import type { Edge } from '../../../platform/graph/edge/index.js';
+import type { Node } from '../../../platform/graph/node/index.js';
+export declare function collectionIdentityOf(value: Node | Edge): string;
+export declare function requireUniqueCollectionValues<Value extends Node | Edge>(values: readonly Value[], context: string): readonly Value[];

package/dist/application/query/collection/identity.js

@@ -0,0 +1,15 @@
+import { edgeKeyOf, encodeEdgeKey } from '@astrale-os/kernel-core/graph/edge';
+export function collectionIdentityOf(value) {
+    return 'id' in value ? `node:${value.id}` : `edge:${encodeEdgeKey(edgeKeyOf(value))}`;
+}
+export function requireUniqueCollectionValues(values, context) {
+    const identities = new Set();
+    for (const value of values) {
+        const identity = collectionIdentityOf(value);
+        if (identities.has(identity)) {
+            throw new TypeError(`${context} returned duplicate identity ${identity}.`);
+        }
+        identities.add(identity);
+    }
+    return values;
+}

package/dist/application/query/collection/limits.d.ts

@@ -0,0 +1,5 @@
+export declare const COLLECTION_QUERY_LIMITS: Readonly<{
+    pageSize: 256;
+    maximumPages: 1024;
+    maximumLogicalAssignments: 262144;
+}>;

package/dist/application/query/collection/limits.js

@@ -0,0 +1,5 @@
+export const COLLECTION_QUERY_LIMITS = Object.freeze({
+    pageSize: 256,
+    maximumPages: 1_024,
+    maximumLogicalAssignments: 262_144,
+});

package/dist/application/query/collection/metadata.d.ts

@@ -0,0 +1,11 @@
+import type { AnyResolvedClass } from '@astrale-os/kernel-dsl/v1';
+import type { Domain } from '../../../platform/schema/index.js';
+export interface CollectionQuerySpec<Class extends AnyResolvedClass = AnyResolvedClass> {
+    readonly id: string;
+    readonly class: Class;
+}
+type CollectionProject = (domain: Domain) => CollectionQuerySpec;
+export declare function registerCollectionQuery(definition: object, project: CollectionProject): void;
+export declare function isCollectionQueryDefinition(definition: unknown): definition is object;
+export declare function realizeCollectionQuery(definition: object, domain: Domain, memberPath?: string): CollectionQuerySpec;
+export {};