@astrale-os/sdk 0.6.0-beta.3 → 0.6.0-beta.30

package/dist/application/workflow/durable.d.ts

@@ -0,0 +1,87 @@
+import type { IssuerId } from '../../platform/auth/index.js';
+import type { BoundClientSession, ExecutionOutcome, ExecutionRef } from '../../platform/client/session/index.js';
+import type { NodeId } from '../../platform/graph/node/index.js';
+import type { CallableInputOf, Domain, ResolvedMethod } from '../../platform/schema/index.js';
+import type { Value } from '../../platform/value/index.js';
+import type { DeclaredErrorFactory, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
+import type { Mutation, MutationExecutor } from '../mutation/index.js';
+import type { QueryExecutor } from '../query/index.js';
+/** A callable whose Schema declares `execution: { durable: true }`. */
+export interface DurableCallable {
+    readonly execution: {
+        readonly durable: true;
+    };
+}
+/** Attested facts of the running Execution. They are data, never authority. */
+export interface DurableExecution {
+    /** The `K.Execution` node recording this call. */
+    readonly id: NodeId;
+    readonly function: {
+        readonly id: NodeId;
+        readonly version: `sha256:${string}`;
+    };
+    /** Kernel that recorded the Execution; every Step calls it back as the Domain. */
+    readonly kernel: IssuerId;
+    /** Who started the Execution. The Workflow never receives their credential. */
+    readonly initiator: {
+        readonly principal: NodeId;
+        readonly caller: NodeId;
+    };
+    /** Receiver of a durable instance Method. */
+    readonly receiver?: NodeId;
+}
+/**
+ * The Domain's own authority inside one Step. Kernel access exists only here, so every Kernel call
+ * belongs to a journaled Step and a replay never repeats it.
+ */
+export interface DurableStepAuthority<DomainValue extends Domain = Domain> {
+    /**
+     * Kernel Session acting as the Domain. Each `invoke` of a durable callable without an explicit
+     * `idempotencyKey` carries one derived from the Execution, the Step and its position, so a
+     * retried Step reaches the same durable child Execution. An `invoke` of any other callable
+     * carries no key, which the Kernel would refuse, and runs again when the Step is retried.
+     */
+    readonly kernel: BoundClientSession;
+    readonly query: QueryExecutor<DomainValue>;
+    /**
+     * Each Mutation carries a key derived from the Execution, the Step and its position. The Kernel
+     * commits a receipt with the write and answers a retried Step with its first result.
+     */
+    readonly mutate: MutationExecutor<DomainValue>;
+}
+export interface DurableStep<DomainValue extends Domain = Domain> {
+    /**
+     * Run `execute` once and journal its portable output; a replay returns the journaled output. A
+     * Step may run again when its outcome was not journaled: its Mutations and durable calls are
+     * answered from their keys, and any other effect must be idempotent.
+     */
+    run<Output>(id: string, execute: (authority: DurableStepAuthority<DomainValue>) => Output | Promise<Output>): Promise<Output>;
+    /**
+     * One journaled Mutation. A Step replayed after its commit receives the result of that commit
+     * from the Kernel's receipt instead of writing again.
+     */
+    mutate<Input, Output>(id: string, mutation: Mutation<DomainValue, Input, Output>, input: Input): Promise<Output>;
+}
+type DurableSelfOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {
+    readonly self: NodeId;
+} : {
+    readonly self?: never;
+};
+/** Context of a durable Workflow: engine-journaled, acting as its Domain. */
+export type DurableWorkflowContext<Callable, DomainValue extends Domain = Domain, Errors extends DeclaredErrors = NoDeclaredErrors> = {
+    readonly domain: DomainValue;
+    readonly input: CallableInputOf<Callable>;
+    readonly execution: DurableExecution;
+    /** Construct one implementation-declared safe business error for `throw error(...)`. */
+    readonly error: DeclaredErrorFactory<Errors>;
+    readonly step: DurableStep<DomainValue>;
+    /** Durable timer kept by the engine, even while the Domain is idle or down. */
+    sleep(durationMs: number): Promise<void>;
+    /** Resolve once `Execution.signal({ name, value })` delivers `name`, before or during the wait. */
+    promise<Signal extends Value = Value>(name: string): Promise<Signal>;
+    /** Whether `error` is the engine's cooperative cancellation, which the Workflow may compensate. */
+    cancelled(error: unknown): boolean;
+    /** Wait durably for another Execution to end, by journaled polling of its `result`. */
+    awaitExecution<Output>(execution: ExecutionRef<Output>): Promise<ExecutionOutcome<Output>>;
+} & DurableSelfOf<Callable>;
+export {};

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

@@ -1,6 +1,7 @@
 export { defineWorkflow, isWorkflow } from './define.js';
-export type { WorkflowContext } from './context.js';
-export type { CallableAtWorkflowAddress, Workflow, WorkflowAddress, WorkflowCallable, WorkflowDefinition, } from './workflow.js';
+export type { InlineWorkflowContext, WorkflowContext } from './context.js';
+export type { DurableCallable, DurableExecution, DurableStep, DurableStepAuthority, DurableWorkflowContext, } from './durable.js';
+export type { CallableAtWorkflowAddress, Workflow, WorkflowAddress, WorkflowCallable, WorkflowDefinition, WorkflowOptions, } from './workflow.js';
 export * as step from './step/index.js';
 export * as runner from './runner/index.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFactory, DeclaredErrorFamily, DeclaredErrorOptions, DeclaredErrors, } from '../error/index.js';

package/dist/application/workflow/runner/inline.js

@@ -1,11 +1,12 @@
-import * as value from '../../../platform/value/index.js';
 import { acceptStepId } from '../step/index.js';
+import { acceptStepOutput } from '../step/output.js';
 /** Process-local runner for tests and explicitly non-durable embeddings. */
 export function createInlineWorkflowRunner() {
     async function run(workflow, context) {
         const execution = createInlineStep(context.execution.signal);
         const complete = Object.freeze({ ...context, step: execution.step });
         try {
+            // Runtime dispatches only non-durable Workflows inline; durable ones run on the engine.
             return await workflow.run(complete);
         }
         finally {
@@ -37,10 +38,8 @@ function createInlineStep(signal) {
             started.add(accepted);
             execution = (async () => {
                 const output = await execute();
-                if (output === undefined)
-                    return output;
                 try {
-                    return value.accept(output);
+                    return acceptStepOutput(output);
                 }
                 catch (cause) {
                     throw new TypeError(`Workflow Step ${accepted} output must be portable.`, {

package/dist/application/workflow/runner/runner.d.ts

@@ -2,9 +2,9 @@ import type { Domain, schema } from '../../../platform/schema/index.js';
 import type { ActionOutputOf, ResolvedCallable, ResolvedDomainOf } from '../../action/index.js';
 import type { DeclaredErrors, NoDeclaredErrors } from '../../error/index.js';
 import type { Integrations } from '../../integration/index.js';
-import type { WorkflowContext } from '../context.js';
+import type { InlineWorkflowContext } from '../context.js';
 import type { CallableAtWorkflowAddress, WorkflowAddress, WorkflowDefinition } from '../workflow.js';
-export type WorkflowExecutionContext<Callable extends ResolvedCallable, Definitions extends Integrations, DomainValue extends Domain = Domain, Errors extends DeclaredErrors = NoDeclaredErrors> = Omit<WorkflowContext<Callable, DomainValue, Definitions, Errors>, 'step'>;
+export type WorkflowExecutionContext<Callable extends ResolvedCallable, Definitions extends Integrations, DomainValue extends Domain = Domain, Errors extends DeclaredErrors = NoDeclaredErrors> = Omit<InlineWorkflowContext<Callable, DomainValue, Definitions, Errors>, 'step'>;
 export interface WorkflowRunner {
     run<Schema extends schema.DomainSchema, Address extends WorkflowAddress<Schema>, Definitions extends Integrations, Errors extends DeclaredErrors, Callable extends CallableAtWorkflowAddress<Schema, Address> = CallableAtWorkflowAddress<Schema, Address>>(workflow: WorkflowDefinition<Schema, Address, Definitions, Errors>, context: WorkflowExecutionContext<Callable, Definitions, ResolvedDomainOf<Schema>, Errors>): Promise<ActionOutputOf<Callable>>;
 }

package/dist/application/workflow/step/output.d.ts

@@ -0,0 +1,2 @@
+/** Capture optional Object fields as absence without changing portable Array or scalar semantics. */
+export declare function acceptStepOutput<Output>(input: Output): Output;

package/dist/application/workflow/step/output.js

@@ -0,0 +1,73 @@
+import * as value from '../../../platform/value/index.js';
+/** Capture optional Object fields as absence without changing portable Array or scalar semantics. */
+export function acceptStepOutput(input) {
+    if (input === undefined)
+        return input;
+    const captured = new WeakMap();
+    const omitted = new WeakMap();
+    const pending = [];
+    let members = 0;
+    function capture(source, depth) {
+        if (source === null || typeof source !== 'object')
+            return source;
+        const retained = captured.get(source);
+        if (retained !== undefined)
+            return retained;
+        if (depth >= value.defaultLimits.maxDepth) {
+            throw new value.BoundaryError('VALUE_LIMIT', 'Workflow Step container depth exceeds the portable limit', '');
+        }
+        const array = Array.isArray(source);
+        const snapshot = array ? [] : Object.create(Object.getPrototypeOf(source));
+        captured.set(source, snapshot);
+        pending.push({ source, snapshot, depth, array });
+        return snapshot;
+    }
+    const snapshot = capture(input, 0);
+    for (let index = 0; index < pending.length; index += 1) {
+        const { source, snapshot: container, depth, array } = pending[index];
+        const descriptors = Object.getOwnPropertyDescriptors(source);
+        const keys = Reflect.ownKeys(descriptors);
+        // Bound this preparatory capture too; canonical admission subsequently checks each path.
+        members += keys.length - (array ? 1 : 0);
+        if (members > value.defaultLimits.maxMembers) {
+            throw new value.BoundaryError('VALUE_LIMIT', 'Workflow Step member count exceeds the portable limit', '');
+        }
+        const absent = new Set();
+        for (const key of keys) {
+            const descriptor = Object.getOwnPropertyDescriptor(descriptors, key)
+                .value;
+            if ('value' in descriptor) {
+                if (!array &&
+                    typeof key === 'string' &&
+                    descriptor.enumerable &&
+                    descriptor.value === undefined) {
+                    // Validate this member's key, descriptor and budget before interpreting its absence.
+                    descriptor.value = null;
+                    absent.add(key);
+                }
+                else {
+                    descriptor.value = capture(descriptor.value, depth + 1);
+                }
+            }
+            Object.defineProperty(container, key, descriptor);
+        }
+        if (absent.size > 0)
+            omitted.set(container, absent);
+    }
+    // The canonical owner still rejects cycles, invalid descriptors/prototypes/keys and lossy values.
+    const output = value.accept(snapshot);
+    const pruning = [{ snapshot, output }];
+    for (let index = 0; index < pruning.length; index += 1) {
+        const pair = pruning[index];
+        if (pair.output === null || typeof pair.output !== 'object')
+            continue;
+        const source = pair.snapshot;
+        const target = pair.output;
+        for (const key of omitted.get(source) ?? [])
+            delete target[key];
+        for (const key of Object.keys(target)) {
+            pruning.push({ snapshot: source[key], output: target[key] });
+        }
+    }
+    return output;
+}

package/dist/application/workflow/workflow.d.ts

@@ -3,20 +3,30 @@ import type { ActionAddressOf, ActionOutputOf, CallableAtAddress, LocalCallable,
 import type { DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { Integrations } from '../integration/index.js';
 import type { WorkflowContext } from './context.js';
-export type WorkflowCallable<Callable> = Callable extends ResolvedCallable ? Callable extends {
-    readonly auth: 'anonymous';
-} ? never : CallableOutputOf<Callable> extends {
+export type WorkflowCallable<Callable> = Callable extends ResolvedCallable ? CallableOutputOf<Callable> extends {
     readonly mode: 'value';
 } ? Callable : never : never;
 export type WorkflowAddress<Schema extends schema.DomainSchema> = ActionAddressOf<WorkflowCallable<LocalCallable<ResolvedDomainOf<Schema>>>>;
 export type CallableAtWorkflowAddress<Schema extends schema.DomainSchema, Address extends WorkflowAddress<Schema>> = WorkflowCallable<Extract<CallableAtAddress<Schema, Address>, ResolvedCallable>>;
 export type Workflow<Callable extends ResolvedCallable, Definitions extends Integrations = Readonly<Record<never, never>>, DomainValue extends Domain = Domain, Errors extends DeclaredErrors = NoDeclaredErrors> = (context: WorkflowContext<Callable, DomainValue, Definitions, Errors>) => Promise<ActionOutputOf<Callable>>;
 declare const WORKFLOW_SCHEMA: unique symbol;
+/** Options of one Workflow implementation. */
+export interface WorkflowOptions<out Errors extends DeclaredErrors = DeclaredErrors> {
+    readonly errors?: Errors;
+    /**
+     * Durable only. Compatibility token journaled first by every run: keep it while a redeployment
+     * can replay the journals of running Executions, change it when it cannot, and those runs pause
+     * until they are resumed on compatible code or cancelled.
+     */
+    readonly compat?: string;
+}
 /** Sealed multi-step Workflow awaiting canonical callable association by Runtime admission. */
 export interface WorkflowDefinition<Schema extends schema.DomainSchema = schema.DomainSchema, Address extends WorkflowAddress<Schema> = WorkflowAddress<Schema>, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> {
     readonly kind: 'workflow';
     readonly address: Address;
     readonly run: Workflow<CallableAtWorkflowAddress<Schema, Address>, Definitions, ResolvedDomainOf<Schema>, Errors>;
+    /** Durable compatibility token; absent means the default token. */
+    readonly compat?: string;
     /** Invariant type-only Schema witness; absent from emitted JavaScript. */
     readonly [WORKFLOW_SCHEMA]: (schema: Schema) => Schema;
 }

package/dist/deployment/adapter/adapter.d.ts

@@ -1,27 +1,69 @@
-import type { DeployContext, DeployResult } from './deploy/index.js';
-import type { ArtifactSource, PrepareContext } from './prepare/index.js';
-export interface InstallationTarget {
-    readonly instance: string;
-    readonly identity?: string;
-}
+import type { DeploymentConfiguration } from '../address/index.js';
+import type { Bundler } from './bundle/index.js';
+import type { AdapterCommand, ConfigureContext, ListContext, ListedDeployment, Placement, PlacementContext, ReleaseDeployContext, ReleaseDeployResult, RetainContext } from './release/index.js';
+/** What `admit` receives when `defineProject` binds an adapter to one Environment. */
 export interface AdapterEnvironmentContext {
     readonly environment: string;
-    readonly installation?: InstallationTarget;
 }
+/**
+ * A provider adapter (adapter interface v2). It bundles a Build without any Environment, freezes
+ * an Environment's configuration, says where the host places that Environment's deployments, and
+ * deploys one sealed release as one immutable deployment, created or reused. It never installs:
+ * `astrale domain install <url>` installs a deployment by its URL.
+ *
+ */
 export interface Adapter<Parameters extends object = object> {
     readonly kind: 'adapter';
     readonly name: string;
     readonly version: string;
+    /**
+     * Produces the environment-free bytes `astrale-domain build` identifies by their build digest
+     * and `deployRelease` receives as its Bundle. Adapters that share one bundler share one build.
+     */
+    readonly bundler: Bundler;
+    /** Refuse parameters that cannot serve this Environment, before any effect. */
     admit?(parameters: Parameters, context: AdapterEnvironmentContext): void;
-    prepare(parameters: Parameters, context: PrepareContext): Promise<ArtifactSource>;
-    deploy(parameters: Parameters, context: DeployContext): Promise<DeployResult>;
-    readonly secretsFile?: (parameters: Parameters) => string | undefined;
+    /**
+     * Freeze what a deployment of this Environment binds beside its build: a `FrozenConfigurationV1`
+     * for a host that binds a generated Worker's settings itself, a `WorkerConfigurationV1` for a
+     * Worker host that binds only what it is asked (Admin's Services). Pure.
+     */
+    configure(parameters: Parameters, context: ConfigureContext): DeploymentConfiguration;
+    /** Where the host places this Environment's deployments. No effect at the host. */
+    placement(parameters: Parameters, context: PlacementContext): Promise<Placement>;
+    /** Create, or reuse, the immutable deployment of one sealed release. */
+    deployRelease(parameters: Parameters, context: ReleaseDeployContext): Promise<ReleaseDeployResult>;
+    /**
+     * The deployments of one Environment of one origin the host keeps for the caller, each with
+     * where it is called. No effect at the host.
+     */
+    list?(parameters: Parameters, context: ListContext): Promise<readonly ListedDeployment[]>;
+    /**
+     * Keep one published deployment where the host has no registry principal to mark it (a platform
+     * namespace). Called only after its registry publication commits. Rejects with a `RetainRefusal` when the
+     * host can no longer keep it (absent or retired), which no rerun changes; any other rejection is
+     * transient. Absent: the registry marks it (Admin's Services).
+     */
+    retain?(parameters: Parameters, context: RetainContext): Promise<void>;
+    /**
+     * Provider commands, by name: `astrale-domain <adapter name> <command> <environment>` runs one
+     * on an Environment this adapter deploys (adapter-cloudflare's `plan` and `init` provision the
+     * host on the operator's own account). Every effect is the adapter's; the CLI only routes.
+     */
+    readonly commands?: Readonly<Record<string, AdapterCommand<Parameters>>>;
+    secretsFile?(parameters: Parameters): string | undefined;
 }
+/** What `defineAdapter` admits for an `Adapter` (adapter interface v2). */
 export interface AdapterInput<Parameters extends object> {
     readonly name: string;
     readonly version: string;
+    readonly bundler: Bundler;
     admit?(parameters: Parameters, context: AdapterEnvironmentContext): void;
-    prepare(parameters: Parameters, context: PrepareContext): Promise<ArtifactSource>;
-    deploy(parameters: Parameters, context: DeployContext): Promise<DeployResult>;
-    readonly secretsFile?: (parameters: Parameters) => string | undefined;
+    configure(parameters: Parameters, context: ConfigureContext): DeploymentConfiguration;
+    placement(parameters: Parameters, context: PlacementContext): Promise<Placement>;
+    deployRelease(parameters: Parameters, context: ReleaseDeployContext): Promise<ReleaseDeployResult>;
+    list?(parameters: Parameters, context: ListContext): Promise<readonly ListedDeployment[]>;
+    retain?(parameters: Parameters, context: RetainContext): Promise<void>;
+    readonly commands?: Readonly<Record<string, AdapterCommand<Parameters>>>;
+    secretsFile?(parameters: Parameters): string | undefined;
 }

package/dist/deployment/adapter/bundle/bundle.d.ts

@@ -0,0 +1,36 @@
+import type { Build, BuildDigest, BuildManifestV1 } from '../../build/index.js';
+import type { ResolvedRuntimeReference } from '../../runtime/index.js';
+import type { ArtifactFile, PreparedArtifactFile } from './file.js';
+/**
+ * Produces the environment-free bytes of one Build. It takes no Environment, address, key or
+ * secret, which is what makes its build digest identical in every Environment. Adapters that share
+ * a bundler share their build.
+ */
+export interface Bundler {
+    readonly id: string;
+    readonly version: string;
+    bundle(context: BundleContext): Promise<BundleSource>;
+}
+export interface BundleContext<BuildValue extends Build = Build> {
+    readonly projectDir: string;
+    readonly build: BuildValue;
+    readonly runtime: ResolvedRuntimeReference;
+    /** Parent-owned lifecycle cancellation shared by every bundling process. */
+    readonly signal: AbortSignal;
+    /** Optional observer of authored paths read outside the Domain/Runtime module graph. */
+    readonly recordSource?: (path: string) => void;
+}
+/** Untrusted bundler output admitted by verify/preflight. */
+export interface BundleSource {
+    readonly entrypoint: string;
+    readonly files: readonly ArtifactFile[];
+}
+/** Exact environment-free bytes of one Build, identified by their build digest. */
+export interface Bundle<BuildValue extends Build = Build> {
+    readonly kind: 'bundle';
+    readonly build: BuildValue;
+    readonly manifest: BuildManifestV1;
+    readonly digest: BuildDigest;
+    readonly entrypoint: string;
+    readonly files: readonly PreparedArtifactFile[];
+}

package/dist/deployment/adapter/bundle/file.d.ts

@@ -0,0 +1,10 @@
+/** One file a bundler produced, before admission. */
+export interface ArtifactFile {
+    readonly path: string;
+    readonly content: Uint8Array;
+}
+/** One admitted file: a detached copy of its bytes on every read. */
+export interface PreparedArtifactFile {
+    readonly path: string;
+    bytes(): Uint8Array;
+}

package/dist/deployment/adapter/bundle/index.d.ts

@@ -0,0 +1,2 @@
+export type { Bundle, BundleContext, BundleSource, Bundler } from './bundle.js';
+export type { ArtifactFile, PreparedArtifactFile } from './file.js';

package/dist/deployment/adapter/define.d.ts

@@ -1,7 +1,8 @@
 import type { Deployment } from '../deployment.js';
 import type { Adapter, AdapterInput } from './adapter.js';
-/** Capture one receiver-bound provider adapter. */
+/** Capture one receiver-bound adapter that deploys immutable DomainRelease v4 deployments. */
 export declare function defineAdapter<Parameters extends object>(input: AdapterInput<Parameters>): Adapter<Parameters>;
-/** Bind one provider adapter to the parameters of one Project Environment. */
-export declare function defineDeployment<const Parameters extends object>(adapter: Adapter<Parameters>, parameters: Parameters): Deployment<Parameters>;
+/** Bind one admitted adapter to the parameters of one Project Environment. */
+export declare function defineDeployment<const Parameters extends object>(adapter: Adapter<Parameters>, parameters: Parameters): Deployment<Parameters, Adapter<Parameters>>;
+/** Whether defineAdapter admitted this immutable-deployment adapter. */
 export declare function isAdapter(input: unknown): input is Adapter;

package/dist/deployment/adapter/define.js

@@ -1,29 +1,53 @@
 import { captureDeployment } from '../deployment.js';
 const admittedAdapters = new WeakSet();
-/** Capture one receiver-bound provider adapter. */
+const admittedBundlers = new WeakMap();
+/** Every field an immutable-deployment adapter may declare. */
+const FIELDS = [
+    'name',
+    'version',
+    'bundler',
+    'admit',
+    'configure',
+    'placement',
+    'deployRelease',
+    'list',
+    'retain',
+    'commands',
+    'secretsFile',
+];
+const RELEASE_OPERATIONS = ['configure', 'placement', 'deployRelease'];
+const OPERATIONS = ['admit', ...RELEASE_OPERATIONS, 'list', 'retain', 'secretsFile'];
+const COMMAND_NAME = /^[a-z][a-z0-9-]{0,31}$/u;
+/** Capture one receiver-bound adapter that deploys immutable DomainRelease v4 deployments. */
 export function defineAdapter(input) {
     const value = record(input, 'Adapter definition');
-    exact(value, ['name', 'version', 'prepare', 'deploy'], ['admit', 'secretsFile']);
+    if (Reflect.ownKeys(value).some((key) => !FIELDS.includes(key))) {
+        invalidFields();
+    }
     const name = stableName(input.name);
     const version = stableName(input.version);
+    const missing = RELEASE_OPERATIONS.filter((key) => value[key] === undefined);
+    if (missing.length > 0) {
+        throw new TypeError(`Adapter ${name} must declare ${missing.join(', ')} to deploy immutable releases.`);
+    }
+    if (value.bundler === undefined)
+        missingBundler(name);
+    const bundler = admitBundler(input.bundler);
     const receiver = Object.freeze({ ...input });
-    const admit = optional(receiver, 'admit');
-    const prepare = capture(receiver, 'prepare');
-    const deploy = capture(receiver, 'deploy');
-    const secretsFile = optional(receiver, 'secretsFile');
+    const operations = Object.fromEntries(OPERATIONS.filter((key) => RELEASE_OPERATIONS.includes(key) ||
+        value[key] !== undefined).map((key) => [key, capture(receiver, key)]));
     const adapter = Object.freeze({
         kind: 'adapter',
         name,
         version,
-        ...(admit === undefined ? {} : { admit }),
-        prepare,
-        deploy,
-        ...(secretsFile === undefined ? {} : { secretsFile }),
+        bundler,
+        ...operations,
+        ...(value.commands === undefined ? {} : { commands: admitCommands(name, value.commands) }),
     });
     admittedAdapters.add(adapter);
     return adapter;
 }
-/** Bind one provider adapter to the parameters of one Project Environment. */
+/** Bind one admitted adapter to the parameters of one Project Environment. */
 export function defineDeployment(adapter, parameters) {
     if (!isAdapter(adapter))
         throw new TypeError('Deployment Adapter is not admitted.');
@@ -32,12 +56,39 @@ export function defineDeployment(adapter, parameters) {
     }
     return captureDeployment(adapter, Object.freeze({ ...parameters }));
 }
+/** Whether defineAdapter admitted this immutable-deployment adapter. */
 export function isAdapter(input) {
     return input !== null && typeof input === 'object' && admittedAdapters.has(input);
 }
-function stableName(input) {
+/**
+ * Capture one receiver-bound bundler; its id and version name the bytes it produces. Adapters that
+ * declare one bundler object receive one admitted Bundler, so `astrale-domain build` bundles once
+ * for all of them.
+ */
+function admitBundler(input) {
+    const value = record(input, 'Bundler');
+    if (Reflect.ownKeys(value).some((key) => key !== 'id' && key !== 'version' && key !== 'bundle') ||
+        typeof input.bundle !== 'function') {
+        throw new TypeError('Bundler must declare exactly id, version and bundle.');
+    }
+    const admitted = admittedBundlers.get(value);
+    if (admitted !== undefined &&
+        admitted.declared === input.bundle &&
+        admitted.bundler.id === input.id &&
+        admitted.bundler.version === input.version) {
+        return admitted.bundler;
+    }
+    const bundler = Object.freeze({
+        id: stableName(input.id, 'Bundler id'),
+        version: stableName(input.version, 'Bundler version'),
+        bundle: input.bundle.bind(input),
+    });
+    admittedBundlers.set(value, { declared: input.bundle, bundler });
+    return bundler;
+}
+function stableName(input, label = 'Adapter name') {
     if (typeof input !== 'string' || input.length === 0 || input.trim() !== input) {
-        throw new TypeError('Adapter name must be a non-empty stable string.');
+        throw new TypeError(`${label} must be a non-empty stable string.`);
     }
     return input;
 }
@@ -47,20 +98,53 @@ function record(input, label) {
     }
     return input;
 }
-function exact(input, required, optional) {
-    const allowed = new Set([...required, ...optional]);
-    if (required.some((key) => !Object.hasOwn(input, key)) ||
-        Reflect.ownKeys(input).some((key) => !allowed.has(key))) {
-        throw new TypeError('Adapter definition contains missing or unknown fields.');
+/** Every adapter declares the bundler of the bytes it deploys. */
+function missingBundler(name) {
+    throw new TypeError(`Adapter ${name} declares no bundler. ` +
+        'Every adapter declares `bundler`: the bundler of the environment-free bytes ' +
+        '`astrale-domain build` identifies by their build digest and `astrale-domain deploy` hands ' +
+        'to the adapter as its Bundle (a Cloudflare Worker adapter declares ' +
+        '`cloudflareWorkerBundler` from `@astrale-os/adapter-cloudflare/build`).');
+}
+/**
+ * Capture the provider commands of one adapter: each a lower-case name, a one-line `summary`,
+ * optional `options` (name to one line of help) and a receiver-bound `run`.
+ */
+function admitCommands(adapter, input) {
+    const commands = record(input, `Adapter ${adapter} commands`);
+    const admitted = {};
+    for (const name of Reflect.ownKeys(commands)) {
+        if (typeof name !== 'string' || !COMMAND_NAME.test(name)) {
+            throw new TypeError(`Adapter ${adapter} declares an invalid command name.`);
+        }
+        const command = record(commands[name], `Adapter ${adapter} command ${name}`);
+        const options = command.options === undefined ? {} : record(command.options, 'Command options');
+        if (Reflect.ownKeys(command).some((key) => key !== 'summary' && key !== 'options' && key !== 'run') ||
+            typeof command.summary !== 'string' ||
+            command.summary.length === 0 ||
+            typeof command.run !== 'function' ||
+            Reflect.ownKeys(options).some((key) => typeof key !== 'string' ||
+                !COMMAND_NAME.test(key) ||
+                key === 'json' ||
+                typeof options[key] !== 'string')) {
+            throw new TypeError(`Adapter ${adapter} command ${name} must declare a summary, string options other than ` +
+                'json and run.');
+        }
+        admitted[name] = Object.freeze({
+            summary: command.summary,
+            options: Object.freeze({ ...options }),
+            run: command.run.bind(command),
+        });
     }
+    return Object.freeze(admitted);
+}
+function invalidFields() {
+    throw new TypeError('Adapter definition contains missing or unknown fields.');
 }
 function capture(receiver, key) {
-    const method = receiver[key];
+    const method = Reflect.get(receiver, key);
     if (typeof method !== 'function') {
-        throw new TypeError(`Adapter ${String(key)} operation is invalid.`);
+        throw new TypeError(`Adapter ${key} operation is invalid.`);
     }
     return method.bind(receiver);
 }
-function optional(receiver, key) {
-    return receiver[key] === undefined ? undefined : capture(receiver, key);
-}

package/dist/deployment/adapter/index.d.ts

@@ -1,4 +1,5 @@
-export type { Adapter, AdapterEnvironmentContext, AdapterInput, InstallationTarget, } from './adapter.js';
+export type { Adapter, AdapterEnvironmentContext, AdapterInput } from './adapter.js';
 export { defineAdapter, defineDeployment, isAdapter } from './define.js';
-export type * from './prepare/index.js';
-export type * from './deploy/index.js';
+export { RetainRefusal } from './release/refusal.js';
+export type * from './bundle/index.js';
+export type * from './release/index.js';

package/dist/deployment/adapter/index.js

@@ -1 +1,2 @@
 export { defineAdapter, defineDeployment, isAdapter } from './define.js';
+export { RetainRefusal } from './release/refusal.js';

package/dist/deployment/adapter/release/command.d.ts

@@ -0,0 +1,33 @@
+/**
+ * One command an adapter declares for its provider (`astrale-domain <adapter> <command>
+ * <environment>`), such as adapter-cloudflare's `plan` and `init`, which provision the host on the
+ * operator's own account. The CLI only routes: it loads the Project, selects the Environment, checks
+ * that its adapter is the one named and declares the command, and admits the options the command
+ * declares; everything the command does is the adapter's.
+ */
+export interface AdapterCommand<Parameters extends object = object> {
+    /** One line: what the command does, for help. */
+    readonly summary: string;
+    /** The options it takes, `--<name> <value>`, each with one line of help. */
+    readonly options?: Readonly<Record<string, string>>;
+    run(parameters: Parameters, context: AdapterCommandContext): Promise<AdapterCommandResult>;
+}
+/** What an adapter command receives. */
+export interface AdapterCommandContext {
+    readonly environment: string;
+    /** Parent-owned lifecycle cancellation. */
+    readonly signal: AbortSignal;
+    /** The options given, each one the command declares. */
+    readonly options: Readonly<Record<string, string>>;
+}
+/** What an adapter command answers; a command that cannot run rejects instead. */
+export interface AdapterCommandResult {
+    /** 0 done; 1 refused or blocked (the command ran, and says why in `warnings`). */
+    readonly exitCode: 0 | 1;
+    /** Lines for a person, printed on stdout without `--json`. */
+    readonly lines: readonly string[];
+    /** Lines for stderr, printed in either case. */
+    readonly warnings?: readonly string[];
+    /** The JSON-serializable result `--json` prints. */
+    readonly result: unknown;
+}