@astrale-os/sdk 0.5.0-beta.9 → 0.5.0-beta.91

package/README.md

@@ -1,26 +1,18 @@
 # SDK
 
-Schema-first SDK for defining, composing, and deploying Astrale Domains. The public authoring
-surface covers Domain handlers, provider-neutral Capabilities, Workflows, Query, Mutation, State,
-and deployment adapters without coupling business code to one host runtime.
+Schema-first SDK for authoring and deploying Astrale Applications. The public surface separates
+single-step Actions, explicit multi-step Workflows, provider-neutral Integrations, concrete Providers, graph
+authoring, Application composition, Deployment, and Execution without exposing DSL callable
+topology in implementation files.
 
 [![CI](https://github.com/astrale-os/sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/astrale-os/sdk/actions/workflows/ci.yml)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
 ## Install
 
-Configure the Astrale scope for GitHub Packages and provide a token with `read:packages`; the SDK's
-Kernel dependencies are intentionally distributed there:
-
-```ini
-# ~/.npmrc
-registry=https://registry.npmjs.org/
-@astrale-os:registry=https://npm.pkg.github.com/
-//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
-```
+The SDK and its complete runtime dependency graph are public on npm and require no GitHub token:
 
 ```bash
-export NODE_AUTH_TOKEN="$(gh auth token)"
 npm install @astrale-os/sdk
 ```
 
@@ -31,7 +23,7 @@ npm install @astrale-os/sdk@beta
 npx -y create-astrale-domain@beta my-domain --yes
 ```
 
-See [the release lifecycle](docs/release.md) for package-cohort versioning, verification, and stable
+See [the release lifecycle](docs/release.md) for package-set versioning, verification, and stable
 promotion.
 
 ## Development
@@ -39,11 +31,19 @@ promotion.
 ### Prerequisites
 
 - Node.js 26.7.0 (default) or Node.js 24; published packages remain compatible with Node.js 22+
-- pnpm 11.13.1
+- pnpm 12.0.0
 
 ### Setup
 
-The SDK is consumed as a submodule of the main Astrale workspace:
+The repository installs autonomously from its versioned npm-only lockfile:
+
+```bash
+git clone https://github.com/astrale-os/sdk.git
+cd sdk
+STANDALONE=true pnpm install --frozen-lockfile
+```
+
+It can also be consumed as a submodule of the main Astrale workspace:
 
 ```bash
 git clone --recursive https://github.com/astrale-os/workspace.git
@@ -65,26 +65,42 @@ pnpm check:issues    # Validate structured cross-repository issues
 The structured [Domain authoring knowledge](knowledge/README.md) is the source for contributor
 guidance and the generated linter policy.
 
-### Domain lint layout overrides
+### Domain lint configuration
 
-`astrale-domain lint` defaults to the canonical layer roots and aliases, including `functions/`,
-`#functions`, and `#functions/*`. A Domain that uses different physical vocabulary can remap a
+`astrale-domain lint` defaults to the canonical layer roots and aliases, including `actions/`,
+`#actions`, and `#actions/*`. A Domain that uses different physical vocabulary can remap a
 semantic layer in `astrale.lint.json` without changing the rules attached to that layer:
 
 ```json
 {
   "layers": {
-    "functions": {
-      "sourcePath": "actions/",
-      "alias": "#actions"
+    "actions": {
+      "sourcePath": "operations/",
+      "alias": "#operations"
     }
   }
 }
 ```
 
-The linter then expects `actions/`, `#actions`, and `#actions/*` in the source tree,
+The linter then expects `operations/`, `#operations`, and `#operations/*` in the source tree,
 `compilerOptions.paths`, and `package.json#imports`. Omit the file to keep the canonical defaults.
 
+If a Domain rule has a known false positive or evaluator defect, disable that exact rule for the
+whole project with a committed reason:
+
+```json
+{
+  "disabledRules": {
+    "PRV-XDOM-REQ": "False positive for a generated Provider wrapper; reported upstream."
+  }
+}
+```
+
+Disabled rules are skipped before evaluation and remain visible in lint coverage and reports. Use
+`// astrale-disable-next-line RULE-ID -- reason` for an isolated conclusive violation instead. A
+project rule disable does not bypass generic Oxlint, project admission, type-universe checks, or
+linter tool failures.
+
 Structured review [issues](issues/README.md) retain observation-first evidence and later governance
 attachments without becoming current contract authority.
 

package/dist/application/action/action.d.ts

@@ -0,0 +1,40 @@
+import type { Domain, ResolvedMethod, schema } from '../../platform/schema/index.js';
+import type { Integrations } from '../integration/index.js';
+import type { ActionContext, ResolvedCallable } from './context.js';
+import type { ActionOutputOf } from './output.js';
+export type Values<Value> = Value[keyof Value];
+type MethodValues<Class> = Class extends {
+    readonly self: {
+        readonly methods: {
+            readonly byKey: infer Instance extends Readonly<Record<string, unknown>>;
+        };
+        readonly static: {
+            readonly methods: {
+                readonly byKey: infer Static extends Readonly<Record<string, unknown>>;
+            };
+        };
+    };
+} ? Values<Instance> | Values<Static> : never;
+type Executable<Callable> = Callable extends ResolvedMethod<unknown, unknown, boolean, infer Inheritance> ? Inheritance extends 'abstract' ? never : Callable : Callable;
+/** Every root-owned callable implementation contract, independent of Function or Method topology. */
+export type LocalCallable<DomainValue extends Domain> = Extract<Values<DomainValue['functions']>, ResolvedCallable> | Extract<Executable<MethodValues<Values<DomainValue['classes']>>>, ResolvedCallable>;
+export type ActionAddressOf<Callable> = Callable extends {
+    readonly key: `${string}:function.${infer Name}`;
+} ? Name : Callable extends {
+    readonly key: `${string}:class.${infer Owner}.method.${infer Name}`;
+} ? `${Owner}.${Name}` : never;
+export type ResolvedDomainOf<Schema extends schema.DomainSchema> = Extract<schema.DomainOf<Schema>, Domain>;
+/** SDK Action address derived mechanically from the canonical local callable key. */
+export type ActionAddress<Schema extends schema.DomainSchema> = ActionAddressOf<LocalCallable<ResolvedDomainOf<Schema>>>;
+export type CallableAtAddress<Schema extends schema.DomainSchema, Address extends string> = LocalCallable<ResolvedDomainOf<Schema>> extends infer Callable ? Callable extends unknown ? ActionAddressOf<Callable> extends Address ? Callable : never : never : never;
+export type Action<Callable extends ResolvedCallable, Definitions extends Integrations = Readonly<Record<never, never>>, DomainValue extends Domain = Domain> = (context: ActionContext<Callable, DomainValue, Definitions>) => Promise<ActionOutputOf<Callable>>;
+declare const ACTION_SCHEMA: unique symbol;
+/** Sealed standalone Action awaiting canonical callable association by Runtime admission. */
+export interface ActionDefinition<Schema extends schema.DomainSchema = schema.DomainSchema, Address extends ActionAddress<Schema> = ActionAddress<Schema>, Definitions extends Integrations = Readonly<Record<never, never>>> {
+    readonly kind: 'action';
+    readonly address: Address;
+    readonly run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>>;
+    /** Invariant type-only Schema witness; absent from emitted JavaScript. */
+    readonly [ACTION_SCHEMA]: (schema: Schema) => Schema;
+}
+export {};

package/dist/application/action/action.js

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

package/dist/application/action/authoring.d.ts

@@ -0,0 +1,4 @@
+export { defineAction } from './define.js';
+export type { Action, ActionDefinition } from './action.js';
+export type { ActionContext, ActionExecution, Caller, DomainGraphExecutor, DomainGraphExecutors, } from './context.js';
+export type { ActionBinary, ActionOutputOf } from './output.js';

package/dist/application/action/authoring.js

@@ -0,0 +1 @@
+export { defineAction } from './define.js';

package/dist/application/action/context.d.ts

@@ -0,0 +1,71 @@
+import type { AuthenticationEvidence, Grant, IdentityId } from '../../platform/auth/index.js';
+import type { BoundClientSession } from '../../platform/client/session/index.js';
+import type { NodeId } from '../../platform/graph/node/index.js';
+import type { CallableInputOf, Domain, ResolvedFunction, ResolvedMethod } from '../../platform/schema/index.js';
+import type { IntegrationClients, Integrations } from '../integration/index.js';
+import type { MutationExecutor } from '../mutation/index.js';
+import type { QueryExecutor } from '../query/index.js';
+export type ResolvedCallable = ResolvedFunction | ResolvedMethod;
+/** Bearer-free caller evidence established before an Action or Workflow runs. */
+export interface AuthenticatedCaller {
+    readonly kind: 'authenticated';
+    readonly principal: IdentityId;
+    readonly authority: Grant;
+    readonly authentication: AuthenticationEvidence;
+}
+export interface AnonymousCaller {
+    readonly kind: 'anonymous';
+}
+export type Caller = AuthenticatedCaller | AnonymousCaller;
+/** One invocation lifetime, retained without exposing Server implementation details. */
+export interface ActionExecution {
+    readonly signal: AbortSignal;
+    /** Absolute Unix time in milliseconds. */
+    readonly deadline: number;
+    readonly idempotencyKey?: string;
+    readonly background: (task: () => void | PromiseLike<unknown>) => void;
+    readonly sleep: (durationMs: number) => Promise<void>;
+    readonly request?: {
+        body(): Uint8Array;
+    };
+}
+export interface DomainGraphExecutor<DomainValue extends Domain = Domain> {
+    readonly query: QueryExecutor<DomainValue>;
+    readonly mutate: MutationExecutor<DomainValue>;
+}
+export type DomainGraphExecutors<DomainValue extends Domain = Domain> = Readonly<Record<'caller' | 'self' | 'union', DomainGraphExecutor<DomainValue>>>;
+type AuthorityOf<Callable, DomainValue extends Domain> = Callable extends {
+    readonly auth: 'anonymous';
+} ? {
+    readonly caller: AnonymousCaller;
+    readonly client: null;
+    readonly graph: null;
+    readonly query?: never;
+    readonly mutate?: never;
+} | {
+    readonly caller: AuthenticatedCaller;
+    readonly client: BoundClientSession;
+    readonly graph: DomainGraphExecutors<DomainValue>;
+    readonly query: QueryExecutor<DomainValue>;
+    readonly mutate: MutationExecutor<DomainValue>;
+} : {
+    readonly caller: AuthenticatedCaller;
+    readonly client: BoundClientSession;
+    readonly graph: DomainGraphExecutors<DomainValue>;
+    readonly query: QueryExecutor<DomainValue>;
+    readonly mutate: MutationExecutor<DomainValue>;
+};
+type SelfOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {
+    readonly self: NodeId;
+} : {
+    readonly self?: never;
+};
+/** Exact single-step Action context derived from one resolved callable. */
+export type ActionContext<Callable extends ResolvedCallable, DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>> = {
+    /** Exact admitted Domain retained by the Build being executed. */
+    readonly domain: DomainValue;
+    readonly input: CallableInputOf<Callable>;
+    readonly integrations: IntegrationClients<Definitions>;
+    readonly execution: ActionExecution;
+} & AuthorityOf<Callable, DomainValue> & SelfOf<Callable>;
+export {};

package/dist/application/action/context.js

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

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

@@ -0,0 +1,8 @@
+import type { schema } from '../../platform/schema/index.js';
+import type { Integrations } from '../integration/index.js';
+import type { Action, ActionAddress, ActionDefinition, CallableAtAddress, ResolvedDomainOf } from './action.js';
+import type { ResolvedCallable } from './context.js';
+/** Define one simple single-step implementation by its SDK Action address. */
+export declare function defineAction<Schema extends schema.DomainSchema, Definitions extends Integrations = Readonly<Record<never, never>>>(): <const Address extends ActionAddress<Schema>>(address: Address, run: Action<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>, Definitions, ResolvedDomainOf<Schema>>) => ActionDefinition<Schema, Address, Definitions>;
+/** True only for an Action produced by defineAction in this SDK package root. */
+export declare function isAction(input: unknown): input is ActionDefinition;

package/dist/application/action/define.js

@@ -0,0 +1,29 @@
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+const admittedActions = new WeakSet();
+/** Define one simple single-step implementation by its SDK Action address. */
+export function defineAction() {
+    return function define(address, run) {
+        acceptActionAddress(address);
+        if (typeof run !== 'function')
+            throw new TypeError('Action run must be a function.');
+        const action = Object.freeze({ kind: 'action', address, run });
+        admittedActions.add(action);
+        return action;
+    };
+}
+/** True only for an Action produced by defineAction in this SDK package root. */
+export function isAction(input) {
+    return input !== null && typeof input === 'object' && admittedActions.has(input);
+}
+function acceptActionAddress(input) {
+    if (typeof input !== 'string')
+        invalidAddress(input);
+    const members = input.split('.');
+    if ((members.length !== 1 && members.length !== 2) ||
+        members.some((member) => !patterns.memberName.test(member))) {
+        invalidAddress(input);
+    }
+}
+function invalidAddress(input) {
+    throw new TypeError(`Invalid Action address: ${JSON.stringify(input)}.`);
+}

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

@@ -0,0 +1,4 @@
+export { defineAction, isAction } from './define.js';
+export type { Action, ActionAddress, ActionAddressOf, ActionDefinition, CallableAtAddress, LocalCallable, ResolvedDomainOf, } from './action.js';
+export type { ActionContext, ActionExecution, AnonymousCaller, AuthenticatedCaller, Caller, DomainGraphExecutor, DomainGraphExecutors, ResolvedCallable, } from './context.js';
+export type { ActionBinary, ActionOutputOf } from './output.js';

package/dist/application/action/index.js

@@ -0,0 +1 @@
+export { defineAction, isAction } from './define.js';

package/dist/application/action/output.d.ts

@@ -0,0 +1,6 @@
+import type { BinaryOutput, BufferedBinaryResult, StreamingBinaryResult } from '@astrale-os/kernel-core/callable';
+import type { CallableResultOf } from '../../platform/schema/index.js';
+import type { ResolvedCallable } from './context.js';
+/** Logical output authored for the callable's exact value, stream, or binary mode. */
+export type ActionOutputOf<Callable extends ResolvedCallable> = CallableResultOf<Callable, BinaryOutput>;
+export type { BinaryOutput as ActionBinary, BufferedBinaryResult, StreamingBinaryResult };

package/dist/application/action/output.js

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

package/dist/application/application.d.ts

@@ -0,0 +1,28 @@
+import type { schema } from '../platform/schema/index.js';
+import type { Requirements } from './requirements/index.js';
+import type { Routes } from './routes/index.js';
+import type { Runtime, SchemaOfRuntime as RuntimeSchemaOf } from './runtime/index.js';
+import type { Frontend } from './view/index.js';
+declare const APPLICATION_IDENTITY: unique symbol;
+declare const APPLICATION_SCHEMA: unique symbol;
+/** Schema-independent type witness shared by every admitted Application declaration. */
+export interface ApplicationIdentity {
+    readonly [APPLICATION_IDENTITY]: true;
+}
+/** Inert source/build composition for one exact Schema and authored Runtime. */
+export interface Application<Schema extends schema.DomainSchema = schema.DomainSchema, RuntimeValue extends Runtime<Schema> = Runtime<Schema>, FrontendValue extends Frontend<Schema> | undefined = undefined, RoutesValue extends Routes | undefined = undefined, RequirementsValue extends Requirements | undefined = undefined> extends ApplicationIdentity {
+    readonly schema: Schema;
+    readonly runtime: RuntimeValue;
+    readonly frontend?: FrontendValue;
+    readonly routes?: RoutesValue;
+    readonly requirements?: RequirementsValue;
+    readonly [APPLICATION_SCHEMA]: (schema: Schema) => Schema;
+}
+export type SchemaOfApplication<Value> = Value extends {
+    readonly schema: infer Schema;
+} ? Extract<Schema, schema.DomainSchema> : never;
+export type RuntimeOfApplication<Value> = Value extends {
+    readonly runtime: infer RuntimeValue;
+} ? Extract<RuntimeValue, Runtime> : never;
+export type SchemaOfRuntime<Value> = RuntimeSchemaOf<Value>;
+export {};

package/dist/application/application.js

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

package/dist/application/define.d.ts

@@ -0,0 +1,16 @@
+import type { schema } from '../platform/schema/index.js';
+import type { Application } from './application.js';
+import type { Requirements } from './requirements/index.js';
+import type { Routes } from './routes/index.js';
+import type { Runtime } from './runtime/index.js';
+import type { Frontend } from './view/index.js';
+export interface ApplicationInput<Schema extends schema.DomainSchema, RuntimeValue extends Runtime<Schema>, FrontendValue extends Frontend<Schema> | undefined, RoutesValue extends Routes | undefined, RequirementsValue extends Requirements | undefined> {
+    readonly schema: Schema;
+    readonly runtime: RuntimeValue;
+    readonly frontend?: FrontendValue;
+    readonly routes?: RoutesValue;
+    readonly requirements?: RequirementsValue;
+}
+/** Capture one inert authored Application without resolving, compiling, loading, or deploying it. */
+export declare function defineApplication<const Schema extends schema.DomainSchema, const RuntimeValue extends Runtime<Schema>, const FrontendValue extends Frontend<Schema> | undefined = undefined, const RoutesValue extends Routes | undefined = undefined, const RequirementsValue extends Requirements | undefined = undefined>(input: ApplicationInput<Schema, RuntimeValue, FrontendValue, RoutesValue, RequirementsValue>): Application<Schema, RuntimeValue, FrontendValue, RoutesValue, RequirementsValue>;
+export declare function isApplication(input: unknown): input is Application;

package/dist/application/define.js

@@ -0,0 +1,40 @@
+import { isRequirements } from './requirements/index.js';
+import { isRoutes } from './routes/index.js';
+import { isRuntime } from './runtime/index.js';
+import { isFrontend } from './view/index.js';
+const admittedApplications = new WeakSet();
+/** Capture one inert authored Application without resolving, compiling, loading, or deploying it. */
+export function defineApplication(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid();
+    const allowed = new Set(['schema', 'runtime', 'frontend', 'routes', 'requirements']);
+    if (Reflect.ownKeys(input).some((key) => !allowed.has(key)))
+        invalid();
+    if (!isRuntime(input.runtime))
+        throw new TypeError('Application Runtime is not admitted.');
+    if (input.frontend !== undefined &&
+        (!isFrontend(input.frontend) || input.frontend.schema !== input.schema)) {
+        throw new TypeError('Application Frontend is not admitted for its exact Schema.');
+    }
+    if (input.routes !== undefined && !isRoutes(input.routes)) {
+        throw new TypeError('Application routes are not admitted.');
+    }
+    if (input.requirements !== undefined && !isRequirements(input.requirements)) {
+        throw new TypeError('Application requirements are not admitted.');
+    }
+    const application = Object.freeze({
+        schema: input.schema,
+        runtime: input.runtime,
+        ...(input.frontend === undefined ? {} : { frontend: input.frontend }),
+        ...(input.routes === undefined ? {} : { routes: input.routes }),
+        ...(input.requirements === undefined ? {} : { requirements: input.requirements }),
+    });
+    admittedApplications.add(application);
+    return application;
+}
+export function isApplication(input) {
+    return input !== null && typeof input === 'object' && admittedApplications.has(input);
+}
+function invalid() {
+    throw new TypeError('Application definition may contain only schema, runtime, frontend, routes, and requirements.');
+}

package/dist/application/index.d.ts

@@ -0,0 +1,9 @@
+export { defineApplication, isApplication } from './define.js';
+export type { ApplicationInput } from './define.js';
+export { requirements } from './requirements/index.js';
+export type { AdministrationRequirements, AdministrationRequirementsInput, CallableRequirementTarget, ClassOperation, ClassRequirement, ClassRequirementInput, Requirements, RequirementsInput, } from './requirements/index.js';
+export { route, routes } from './routes/index.js';
+export type { Route, RouteInput, RouteTarget, Routes } from './routes/index.js';
+export { defineFrontend, external, vite } from './view/index.js';
+export type { Frontend, FrontendInput, FrontendSource, IframeRequirements } from './view/index.js';
+export type { Application, ApplicationIdentity, RuntimeOfApplication, SchemaOfApplication, SchemaOfRuntime, } from './application.js';

package/dist/application/index.js

@@ -0,0 +1,4 @@
+export { defineApplication, isApplication } from './define.js';
+export { requirements } from './requirements/index.js';
+export { route, routes } from './routes/index.js';
+export { defineFrontend, external, vite } from './view/index.js';

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

@@ -0,0 +1,9 @@
+import type { ProviderBinding } from './define.js';
+import type { Integrations } from './integration.js';
+import type { Providers } from './provider.js';
+export interface AdmittedProvider {
+    readonly name: string;
+    readonly binding: ProviderBinding;
+}
+/** Admit exact Provider coverage and Integration identity before any invocation. */
+export declare function admitProviders<Definitions extends Integrations>(integrations: Definitions, providers: Providers<Definitions>): readonly AdmittedProvider[];

package/dist/application/integration/admission.js

@@ -0,0 +1,21 @@
+import { admitIntegrations, requireProvider } from './define.js';
+/** Admit exact Provider coverage and Integration identity before any invocation. */
+export function admitProviders(integrations, providers) {
+    const required = admitIntegrations(integrations);
+    if (providers === null || typeof providers !== 'object' || Array.isArray(providers)) {
+        throw new TypeError('Runtime providers must be an object.');
+    }
+    const expected = Object.keys(required);
+    const actual = Reflect.ownKeys(providers);
+    if (actual.length !== expected.length ||
+        actual.some((key) => typeof key !== 'string' || !expected.includes(key))) {
+        throw new TypeError(`Runtime providers must contain exactly: ${expected.join(', ') || '(none)'}.`);
+    }
+    return Object.freeze(expected.map((name) => {
+        const binding = requireProvider(providers[name]);
+        if (binding.integration !== required[name]) {
+            throw new TypeError(`Provider ${name} implements another Integration.`);
+        }
+        return Object.freeze({ name, binding });
+    }));
+}

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

@@ -0,0 +1,25 @@
+import type { BoundClientSession } from '../../platform/client/session/index.js';
+import type { IntegrationClients, Integrations } from './integration.js';
+import type { IntegrationReplayDecision } from './operation.js';
+import type { Providers } from './provider.js';
+export interface IntegrationCallCoordinates {
+    readonly callId: string;
+    readonly signal: AbortSignal;
+    readonly deadline: number;
+    readonly invoke?: BoundClientSession['invoke'];
+}
+export interface IntegrationAttempt<Output> {
+    readonly integration: string;
+    readonly operation: string;
+    readonly replay: IntegrationReplayDecision;
+    attempt(coordinates: IntegrationCallCoordinates): Promise<Output>;
+}
+export interface IntegrationInvocationOwner {
+    invoke<Output>(call: IntegrationAttempt<Output>): Promise<Output>;
+}
+export interface IntegrationClientFactory<Definitions extends Integrations> {
+    (owner: IntegrationInvocationOwner): IntegrationClients<Definitions>;
+}
+/** Bind exact Providers once, then create invocation-scoped Integration clients. */
+export declare function bindProviders<Definitions extends Integrations>(integrations: Definitions, providers: Providers<Definitions>): IntegrationClientFactory<Definitions>;
+export declare function createIntegrationClients<Definitions extends Integrations>(integrations: Definitions, providers: Providers<Definitions>, owner: IntegrationInvocationOwner): IntegrationClients<Definitions>;

package/dist/application/integration/client.js

@@ -0,0 +1,100 @@
+import { admitProviders } from './admission.js';
+import { resolveReplay } from './replay.js';
+/** Bind exact Providers once, then create invocation-scoped Integration clients. */
+export function bindProviders(integrations, providers) {
+    const admitted = admitProviders(integrations, providers);
+    return (owner) => createClients(admitted, owner);
+}
+export function createIntegrationClients(integrations, providers, owner) {
+    return bindProviders(integrations, providers)(owner);
+}
+function createClients(providers, owner) {
+    if (owner === null || typeof owner !== 'object' || typeof owner.invoke !== 'function') {
+        throw new TypeError('Integration invocation owner is invalid.');
+    }
+    const invoke = owner.invoke.bind(owner);
+    const clients = Object.create(null);
+    for (const { name, binding } of providers) {
+        const operations = Object.create(null);
+        for (const operationName of Object.keys(binding.integration.operations)) {
+            const operation = binding.integration.operations[operationName];
+            const implementation = binding.implementation[operationName];
+            operations[operationName] = async (...input) => {
+                if (input.length > 1) {
+                    throw new TypeError('Integration operations accept at most one semantic input.');
+                }
+                const value = input[0];
+                const replay = resolveReplay(operation, value);
+                let attempts = 0;
+                let logicalCall;
+                let active = true;
+                try {
+                    return await invoke({
+                        integration: binding.integration.id,
+                        operation: operationName,
+                        replay,
+                        async attempt(coordinates) {
+                            if (!active) {
+                                throw new TypeError('Settled Integration operation cannot be attempted again.');
+                            }
+                            if (replay.kind === 'unsafe' && attempts > 0) {
+                                throw new TypeError('Unsafe Integration operation cannot be attempted again.');
+                            }
+                            const admitted = admitCoordinates(coordinates);
+                            attempts += 1;
+                            if (logicalCall === undefined)
+                                logicalCall = admitted.callId;
+                            else if (logicalCall !== admitted.callId) {
+                                throw new TypeError('Integration replay must retain the logical call id.');
+                            }
+                            const execution = executionFor(admitted, replay);
+                            return input.length === 0
+                                ? Reflect.apply(implementation, undefined, [execution])
+                                : Reflect.apply(implementation, undefined, [value, execution]);
+                        },
+                    });
+                }
+                finally {
+                    active = false;
+                }
+            };
+        }
+        clients[name] = Object.freeze(operations);
+    }
+    return Object.freeze(clients);
+}
+function executionFor(coordinates, replay) {
+    const idempotencyKey = replay.kind !== 'keyed'
+        ? undefined
+        : replay.source === 'execution'
+            ? coordinates.callId
+            : replay.key;
+    return Object.freeze({
+        ...coordinates,
+        ...(idempotencyKey === undefined ? {} : { idempotencyKey }),
+    });
+}
+function admitCoordinates(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalidCoordinates();
+    const keys = Reflect.ownKeys(input);
+    if ((keys.length !== 3 && keys.length !== 4) ||
+        !keys.every((key) => key === 'callId' || key === 'signal' || key === 'deadline' || key === 'invoke') ||
+        typeof input.callId !== 'string' ||
+        input.callId.length === 0 ||
+        input.callId.trim() !== input.callId ||
+        !(input.signal instanceof AbortSignal) ||
+        !Number.isFinite(input.deadline) ||
+        (input.invoke !== undefined && typeof input.invoke !== 'function')) {
+        invalidCoordinates();
+    }
+    return Object.freeze({
+        callId: input.callId,
+        signal: input.signal,
+        deadline: input.deadline,
+        ...(input.invoke === undefined ? {} : { invoke: input.invoke }),
+    });
+}
+function invalidCoordinates() {
+    throw new TypeError('Integration call coordinates are invalid.');
+}

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

@@ -0,0 +1,24 @@
+import type { IntegrationDefinition, Integrations } from './integration.js';
+import type { IntegrationOperation, IntegrationOperations, IntegrationReplay } from './operation.js';
+import type { Provider, ProviderImplementation } from './provider.js';
+type RuntimeDefinition = IntegrationDefinition<string, IntegrationOperations>;
+type ProviderOperations = Readonly<Record<string, (...input: readonly unknown[]) => unknown>>;
+export interface ProviderBinding {
+    readonly integration: RuntimeDefinition;
+    readonly implementation: ProviderOperations;
+}
+export interface DefineIntegration {
+    <Id extends string, Operations extends IntegrationOperations>(input: {
+        readonly id: Id;
+        readonly operations: Operations;
+    }): IntegrationDefinition<Id, Operations>;
+    operation<Input = void, Output = void>(input: {
+        readonly replay: IntegrationReplay<Input>;
+    }): IntegrationOperation<Input, Output>;
+}
+export declare const defineIntegration: DefineIntegration;
+export declare function defineProvider<Definition extends IntegrationDefinition>(definition: Definition, implementation: ProviderImplementation<Definition>): Provider<Definition>;
+export declare function admitIntegrations<Definitions extends Integrations>(input: Definitions): Definitions;
+export declare function requireIntegration(input: unknown): RuntimeDefinition;
+export declare function requireProvider(input: unknown): ProviderBinding;
+export {};