@astrale-os/sdk 0.5.0-beta.2 → 0.5.0-beta.21

package/dist/application/integration/define.js

@@ -0,0 +1,101 @@
+import { acceptReplay } from './replay.js';
+const operations = new WeakSet();
+const definitions = new WeakSet();
+const providers = new WeakMap();
+function integration(input) {
+    const source = record(input, 'Integration definition');
+    exactKeys(source, ['id', 'operations'], 'Integration definition');
+    if (typeof input.id !== 'string' || input.id.length === 0 || input.id.trim() !== input.id) {
+        throw new TypeError('Integration id must be non-empty stable text.');
+    }
+    const authored = record(input.operations, 'Integration operations');
+    const names = Object.keys(authored);
+    if (names.length === 0)
+        throw new TypeError('Integration must declare at least one operation.');
+    const retained = Object.create(null);
+    for (const name of names) {
+        if (name.length === 0 || name.trim() !== name) {
+            throw new TypeError('Integration operation name must be stable text.');
+        }
+        const operation = authored[name];
+        if (operation === null || typeof operation !== 'object' || !operations.has(operation)) {
+            throw new TypeError(`Integration operation ${name} is not admitted.`);
+        }
+        retained[name] = operation;
+    }
+    const definition = Object.freeze({
+        kind: 'integration',
+        id: input.id,
+        operations: Object.freeze(retained),
+    });
+    definitions.add(definition);
+    return definition;
+}
+function operation(input) {
+    const source = record(input, 'Integration operation');
+    exactKeys(source, ['replay'], 'Integration operation');
+    const replay = typeof input.replay === 'function'
+        ? input.replay
+        : acceptReplay(input.replay);
+    const value = Object.freeze({ replay });
+    operations.add(value);
+    return value;
+}
+export const defineIntegration = Object.assign(integration, { operation });
+export function defineProvider(definition, implementation) {
+    if (!definitions.has(definition)) {
+        throw new TypeError('Provider requires an admitted Integration.');
+    }
+    const source = record(implementation, 'Provider implementation');
+    const names = Object.keys(definition.operations);
+    exactKeys(source, names, 'Provider implementation');
+    const retained = Object.create(null);
+    for (const name of names) {
+        const candidate = source[name];
+        if (typeof candidate !== 'function') {
+            throw new TypeError(`Provider operation ${name} must be a function.`);
+        }
+        retained[name] = candidate;
+    }
+    const provider = Object.freeze({ integration: definition });
+    providers.set(provider, Object.freeze({
+        integration: definition,
+        implementation: Object.freeze(retained),
+    }));
+    return provider;
+}
+export function admitIntegrations(input) {
+    const source = record(input, 'Runtime integrations');
+    const captured = Object.create(null);
+    for (const name of Object.keys(source))
+        captured[name] = requireIntegration(source[name]);
+    return Object.freeze(captured);
+}
+export function requireIntegration(input) {
+    if (input === null || typeof input !== 'object' || !definitions.has(input)) {
+        throw new TypeError('Integration is not admitted.');
+    }
+    return input;
+}
+export function requireProvider(input) {
+    if (input === null || typeof input !== 'object')
+        throw new TypeError('Provider is not admitted.');
+    const binding = providers.get(input);
+    if (binding === undefined)
+        throw new TypeError('Provider is not admitted.');
+    return binding;
+}
+function record(input, label) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        throw new TypeError(`${label} must be an object.`);
+    }
+    return input;
+}
+function exactKeys(input, expected, label) {
+    const keys = Reflect.ownKeys(input);
+    const accepted = new Set(expected);
+    if (keys.length !== expected.length ||
+        keys.some((key) => typeof key !== 'string' || !accepted.has(key))) {
+        throw new TypeError(`${label} must contain exactly: ${expected.join(', ') || '(none)'}.`);
+    }
+}

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

@@ -0,0 +1,7 @@
+export { createIntegrationClients, bindProviders } from './client.js';
+export type { IntegrationAttempt, IntegrationCallCoordinates, IntegrationClientFactory, IntegrationInvocationOwner, } from './client.js';
+export { admitIntegrations, defineIntegration, defineProvider, requireIntegration, requireProvider, } from './define.js';
+export type { DefineIntegration, ProviderBinding } from './define.js';
+export type { IntegrationClient, IntegrationClients, IntegrationDefinition, Integrations, } from './integration.js';
+export type { IntegrationExecution, IntegrationInput, IntegrationOperation, IntegrationOperations, IntegrationOutput, IntegrationReplay, IntegrationReplayDecision, } from './operation.js';
+export type { Provider, ProviderImplementation, Providers } from './provider.js';

package/dist/application/integration/index.js

@@ -0,0 +1,2 @@
+export { createIntegrationClients, bindProviders } from './client.js';
+export { admitIntegrations, defineIntegration, defineProvider, requireIntegration, requireProvider, } from './define.js';

package/dist/application/integration/integration.d.ts

@@ -0,0 +1,19 @@
+import type { IntegrationOperation, IntegrationOperations } from './operation.js';
+declare const INTEGRATION_DEFINITION: unique symbol;
+export interface IntegrationDefinition<Id extends string = string, Operations extends IntegrationOperations = IntegrationOperations> {
+    readonly kind: 'integration';
+    readonly id: Id;
+    readonly operations: Operations;
+    readonly [INTEGRATION_DEFINITION]: Readonly<{
+        id: Id;
+        operations: Operations;
+    }>;
+}
+export type Integrations = Readonly<Record<string, IntegrationDefinition<string, IntegrationOperations>>>;
+export type IntegrationClient<Definition extends IntegrationDefinition> = Readonly<{
+    [Name in keyof Definition['operations']]: Definition['operations'][Name] extends IntegrationOperation<infer Input, infer Output> ? [Input] extends [void] ? () => Promise<Output> : (input: Input) => Promise<Output> : never;
+}>;
+export type IntegrationClients<Definitions extends Integrations> = Readonly<{
+    [Name in keyof Definitions]: IntegrationClient<Definitions[Name]>;
+}>;
+export {};

package/dist/application/integration/integration.js

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

package/dist/application/integration/operation.d.ts

@@ -0,0 +1,32 @@
+declare const INTEGRATION_OPERATION: unique symbol;
+export type IntegrationReplayDecision = {
+    readonly kind: 'safe';
+} | {
+    readonly kind: 'keyed';
+    readonly source: 'execution';
+} | {
+    readonly kind: 'keyed';
+    readonly source: 'input';
+    readonly key: string;
+} | {
+    readonly kind: 'unsafe';
+};
+export type IntegrationReplay<Input> = IntegrationReplayDecision | ((input: Input) => IntegrationReplayDecision);
+export interface IntegrationExecution {
+    readonly callId: string;
+    readonly signal: AbortSignal;
+    readonly deadline: number;
+    readonly idempotencyKey?: string;
+}
+export interface IntegrationOperation<Input = unknown, Output = unknown> {
+    readonly replay: IntegrationReplay<Input>;
+    readonly [INTEGRATION_OPERATION]: (input: Input) => Output;
+}
+export type IntegrationOperations = Readonly<Record<string, IntegrationOperation<never, unknown>>>;
+export type IntegrationInput<Operation> = Operation extends {
+    readonly [INTEGRATION_OPERATION]: (input: infer Input) => unknown;
+} ? Input : never;
+export type IntegrationOutput<Operation> = Operation extends {
+    readonly [INTEGRATION_OPERATION]: (input: never) => infer Output;
+} ? Output : never;
+export {};

package/dist/application/integration/operation.js

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

package/dist/application/integration/provider.d.ts

@@ -0,0 +1,14 @@
+import type { IntegrationDefinition, Integrations } from './integration.js';
+import type { IntegrationExecution, IntegrationOperation } from './operation.js';
+declare const INTEGRATION_PROVIDER: unique symbol;
+export type ProviderImplementation<Definition extends IntegrationDefinition> = Readonly<{
+    [Name in keyof Definition['operations']]: Definition['operations'][Name] extends IntegrationOperation<infer Input, infer Output> ? [Input] extends [void] ? (execution: IntegrationExecution) => Promise<Output> : (input: Input, execution: IntegrationExecution) => Promise<Output> : never;
+}>;
+export interface Provider<Definition extends IntegrationDefinition = IntegrationDefinition> {
+    readonly integration: Definition;
+    readonly [INTEGRATION_PROVIDER]: Definition;
+}
+export type Providers<Definitions extends Integrations> = Readonly<{
+    [Name in keyof Definitions]: Provider<Definitions[Name]>;
+}>;
+export {};

package/dist/application/integration/provider.js

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

package/dist/application/integration/replay.d.ts

@@ -0,0 +1,3 @@
+import type { IntegrationOperation, IntegrationReplayDecision } from './operation.js';
+export declare function resolveReplay(operation: IntegrationOperation<never, unknown>, input: unknown): IntegrationReplayDecision;
+export declare function acceptReplay(input: unknown): IntegrationReplayDecision;

package/dist/application/integration/replay.js

@@ -0,0 +1,37 @@
+export function resolveReplay(operation, input) {
+    const authored = typeof operation.replay === 'function'
+        ? Reflect.apply(operation.replay, undefined, [input])
+        : operation.replay;
+    return acceptReplay(authored);
+}
+export function acceptReplay(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    const decision = input;
+    if (decision.kind === 'safe' || decision.kind === 'unsafe') {
+        exactKeys(decision, ['kind']);
+        return Object.freeze({ kind: decision.kind });
+    }
+    if (decision.kind !== 'keyed')
+        invalid();
+    if (decision.source === 'execution') {
+        exactKeys(decision, ['kind', 'source']);
+        return Object.freeze({ kind: 'keyed', source: 'execution' });
+    }
+    if (decision.source === 'input' &&
+        typeof decision.key === 'string' &&
+        decision.key.trim().length > 0) {
+        exactKeys(decision, ['kind', 'source', 'key']);
+        return Object.freeze({ kind: 'keyed', source: 'input', key: decision.key });
+    }
+    invalid();
+}
+function exactKeys(input, expected) {
+    const keys = Reflect.ownKeys(input);
+    const accepted = new Set(expected);
+    if (keys.length !== expected.length || keys.some((key) => !accepted.has(key)))
+        invalid();
+}
+function invalid() {
+    throw new TypeError('Integration replay decision is invalid.');
+}

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

@@ -0,0 +1,53 @@
+import type { EdgeSlug } from '@astrale-os/kernel-core/graph/edge';
+import type { MutationBuilder } from '@astrale-os/kernel-core/graph/mutate';
+import type { QueryEdgeAST, QueryNodeAST } from '@astrale-os/kernel-core/graph/query';
+import type { ResolvedClass } from '../../../platform/schema/index.js';
+import type { CreatedNode, ExistingEndpoint, MutationEndpoint } from './endpoint.js';
+import type { QueryPrecondition } from './precondition.js';
+import type { RichPropertyConditions, RichPropertyDelta, RichPropertyInput } from './properties.js';
+export interface RichMutationBuilder {
+    readonly expect: {
+        node<Class extends ResolvedClass<'node'>>(input: {
+            readonly node: ExistingEndpoint;
+            readonly class: Class;
+            readonly props?: RichPropertyConditions<Class>;
+        }): RichMutationBuilder;
+        edge<Class extends ResolvedClass<'edge'>>(input: EdgeSelector<Class> & {
+            readonly slug?: EdgeSlug | null;
+            readonly props?: RichPropertyConditions<Class>;
+        }): RichMutationBuilder;
+        query<Query extends QueryNodeAST | QueryEdgeAST>(input: QueryPrecondition<Query>): RichMutationBuilder;
+    };
+    createNode<Class extends ResolvedClass<'node'>>(input: {
+        readonly as: string;
+        readonly class: Class;
+        readonly props?: RichPropertyInput<Class>;
+    }): CreatedNode<Class>;
+    updateNode<Class extends ResolvedClass<'node'>>(input: {
+        readonly node: ExistingEndpoint;
+        readonly class: Class;
+        readonly props: RichPropertyDelta<Class>;
+    }): this;
+    deleteNode<Class extends ResolvedClass<'node'>>(input: {
+        readonly node: ExistingEndpoint;
+        readonly class: Class;
+    }): this;
+    createEdge<Class extends ResolvedClass<'edge'>>(input: {
+        readonly class: Class;
+        readonly source: MutationEndpoint;
+        readonly target: MutationEndpoint;
+        readonly slug?: EdgeSlug;
+        readonly props?: RichPropertyInput<Class>;
+    }): this;
+    updateEdge<Class extends ResolvedClass<'edge'>>(input: EdgeSelector<Class> & {
+        readonly slug?: EdgeSlug | null;
+        readonly props?: RichPropertyDelta<Class>;
+    }): this;
+    deleteEdge<Class extends ResolvedClass<'edge'>>(input: EdgeSelector<Class>): this;
+}
+export interface EdgeSelector<Class extends ResolvedClass<'edge'>> {
+    readonly source: ExistingEndpoint;
+    readonly target: ExistingEndpoint;
+    readonly class: Class;
+}
+export declare function richMutationBuilder(core: MutationBuilder): RichMutationBuilder;

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

@@ -0,0 +1,97 @@
+import { LocalBinding } from '@astrale-os/kernel-core/graph/graph';
+import { ClassKey } from '@astrale-os/kernel-dsl/v1/addressing';
+import { endpoint, existingEndpoint } from './endpoint.js';
+import { precondition } from './precondition.js';
+import { conditions, delta, properties } from './properties.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: LocalBinding(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;
+        },
+        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 { LocalBinding } from '@astrale-os/kernel-core/graph/graph';
+import type { NodeId } from '@astrale-os/kernel-core/graph/node';
+import type { NodeTarget } from '@astrale-os/kernel-core/path';
+import type { ResolvedClass } from '../../../platform/schema/index.js';
+export interface CreatedNode<Class extends ResolvedClass<'node'> = ResolvedClass<'node'>> {
+    readonly created: LocalBinding;
+    readonly class: Class;
+}
+export type ExistingEndpoint = NodeTarget | Readonly<{
+    id: NodeId;
+}>;
+export type MutationEndpoint = ExistingEndpoint | CreatedNode;
+export declare function endpoint(input: MutationEndpoint): NodeTarget | {
+    readonly created: LocalBinding;
+};
+export declare function existingEndpoint(input: ExistingEndpoint): NodeTarget;

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

@@ -0,0 +1,13 @@
+export function endpoint(input) {
+    if (isCreated(input))
+        return Object.freeze({ created: input.created });
+    return existingEndpoint(input);
+}
+export function existingEndpoint(input) {
+    return typeof input === 'object' && input !== null && 'id' in input
+        ? input.id
+        : 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,21 @@
+import type { MutationPropsInput } from '@astrale-os/kernel-core/graph/mutate';
+import type { PropertyInputOf, ResolvedClass } from '../../../platform/schema/index.js';
+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("../../../platform/schema/index.js").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("../../../platform/schema/index.js").Value>>;
+    unset: readonly `${string}:class.${string}.property.${string}`[];
+}>;

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

@@ -0,0 +1,27 @@
+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) => property(selected, name).key)) }),
+    });
+}
+export function delta(selected, input) {
+    return Object.freeze({
+        set: properties(selected, input.set ?? {}),
+        unset: Object.freeze((input.unset ?? []).map((name) => property(selected, name).key)),
+    });
+}
+function property(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/define.d.ts

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

package/dist/application/mutation/define.js

@@ -0,0 +1,17 @@
+export function defineMutation(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.change !== 'function' ||
+        (definition.project !== undefined && typeof definition.project !== 'function') ||
+        (definition.reject !== undefined && typeof definition.reject !== 'function') ||
+        Reflect.ownKeys(definition).some((key) => key !== 'id' && key !== 'change' && key !== 'project' && key !== 'reject')) {
+        invalid();
+    }
+    return Object.freeze({ ...definition });
+}
+function invalid() {
+    throw new TypeError('Mutation definition is invalid.');
+}

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

@@ -0,0 +1,6 @@
+import { MutationAST, type MutationResult } from '@astrale-os/kernel-core/graph/mutate';
+import type { Mutation } from '../mutation.js';
+export interface MutationClient {
+    mutate(ast: ReturnType<typeof MutationAST.build>): Promise<MutationResult>;
+}
+export declare function executeMutation<Input, Output>(client: MutationClient, definition: Mutation<Input, Output>, input: Input): Promise<Output>;

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

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

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

@@ -0,0 +1,8 @@
+import type { Mutation } from '../mutation.js';
+import type { MutationClient } from './execute.js';
+/** Invocation-bound executor for authored Mutation definitions. */
+export interface MutationExecutor {
+    <Input, Output>(definition: Mutation<Input, Output>, input: Input): Promise<Output>;
+}
+/** Private Runtime binding; public consumers use executeMutation(client, definition, input). */
+export declare function bindMutation(client: MutationClient): MutationExecutor;

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

@@ -0,0 +1,5 @@
+import { executeMutation } from './execute.js';
+/** Private Runtime binding; public consumers use executeMutation(client, definition, input). */
+export function bindMutation(client) {
+    return (definition, input) => executeMutation(client, definition, input);
+}

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 { Mutation } from '../mutation.js';
+export declare function projectMutation<Input, Output>(definition: Mutation<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,5 @@
+export interface MutationFailure extends Error {
+    readonly code: string;
+    readonly outcomeKnown: boolean;
+}
+export declare function mutationFailure(input: unknown): MutationFailure | undefined;

package/dist/application/mutation/failure.js

@@ -0,0 +1,28 @@
+const UNKNOWN_OUTCOME_CODES = new Set(['MUTATION_OUTCOME_UNKNOWN']);
+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;
+    return Object.assign(input, {
+        code,
+        outcomeKnown: explicit !== false && !UNKNOWN_OUTCOME_CODES.has(code),
+    });
+}
+function mutationCode(input) {
+    const value = input;
+    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,7 @@
+export { defineMutation } from './define.js';
+export { executeMutation, type MutationClient, type MutationExecutor } from './execution/index.js';
+export type { MutationFailure } from './failure.js';
+export type { Mutation, 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';

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