@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.40

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,15 +3,17 @@ 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;
+}
 /** 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';

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

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

@@ -0,0 +1,94 @@
+import type { DeploymentCommitV1, DeploymentConfiguration, LineAddressing } from '../../address/index.js';
+import type { Release } from '../../release/index.js';
+import type { Bundle } from '../bundle/index.js';
+/**
+ * What `configure` receives: the Environment whose configuration it freezes, and the names of the
+ * secrets its deployment binds. Never a secret value: a rotated value is not another configuration,
+ * a name added or removed is.
+ */
+export interface ConfigureContext {
+    readonly environment: string;
+    /**
+     * The names of the Environment's current secrets (the adapter's `secretsFile`), sorted and
+     * unique: exactly the secrets `deployRelease` receives, which the configuration declares.
+     */
+    readonly secrets: readonly string[];
+}
+/**
+ * Where the host places the deployments of one Environment. `routingDomain` is the DNS name every
+ * deployment URL ends with, `https://<label>.<routingDomain>`; `addressing` is how its line reads:
+ * `readable` for platform lines, `opaque` (the fingerprint alone) for tenant lines.
+ */
+export interface Placement {
+    readonly addressing: LineAddressing;
+    readonly routingDomain: string;
+}
+/** What `placement` receives. It answers without any effect at the host. */
+export interface PlacementContext {
+    readonly environment: string;
+    /** Parent-owned lifecycle cancellation. */
+    readonly signal: AbortSignal;
+    /** Optional command-scoped identity override (`--as`). */
+    readonly identity?: string;
+}
+/**
+ * Everything `deployRelease` deploys: one sealed release as one immutable deployment at
+ * `release.url`, which is `deploymentUrl(label, placement.routingDomain)` and the release's issuer.
+ * The SDK computes each value before the call, from the Build, `configure` and `placement`, so the
+ * adapter never derives an address or seals anything itself.
+ */
+export interface ReleaseDeployContext {
+    readonly projectDir: string;
+    readonly environment: string;
+    /** Optional command-scoped identity override (`--as`). */
+    readonly identity?: string;
+    /** Optional command-scoped credential; trusted adapters must neither retain nor disclose it. */
+    readonly credential?: string;
+    /**
+     * The Environment's current secrets. A new deployment binds them; a reused deployment has its
+     * own declared secrets rewritten in place. A deploy never writes another deployment's secrets.
+     */
+    readonly secrets: Readonly<Record<string, string>>;
+    /** The environment-free bytes of the adapter's `bundler`, identified by `bundle.digest`. */
+    readonly bundle: Bundle;
+    /** What `configure` froze for this Environment. */
+    readonly configuration: DeploymentConfiguration;
+    /** Where `placement` said the host places the deployment. */
+    readonly placement: Placement;
+    /**
+     * `<line>-<content>`: the DNS label of the deployment, which is also its provider script. Its
+     * content covers `bundle.digest` and `configuration`, so one label serves one release.
+     */
+    readonly label: string;
+    /**
+     * The release the SDK sealed for this deployment before the call: its `document` is the
+     * `DomainRelease` v4 the deployment serves at `release.json`, its `url` the deployment URL.
+     */
+    readonly release: Release;
+    /**
+     * The commit this deploy runs from, which the record of a deployment it creates declares. The
+     * label does not cover it: a reused deployment keeps the record, and so the commit, of the deploy
+     * that created it, and an adapter never refuses a reuse for another commit.
+     */
+    readonly commit: DeploymentCommitV1 | null;
+    /** Parent-owned lifecycle cancellation shared by every provider effect. */
+    readonly signal: AbortSignal;
+}
+/**
+ * What `list` receives: the origin and the Environment whose deployments the host lists for the
+ * caller. It answers without any effect at the host.
+ */
+export interface ListContext {
+    readonly origin: string;
+    readonly environment: string;
+    /** Parent-owned lifecycle cancellation. */
+    readonly signal: AbortSignal;
+    /** Optional command-scoped identity override (`--as`). */
+    readonly identity?: string;
+}
+/** What `retain` receives: the label of the published deployment to keep. */
+export interface RetainContext {
+    readonly label: string;
+    readonly signal: AbortSignal;
+    readonly identity?: string;
+}

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

@@ -0,0 +1,4 @@
+export type { ConfigureContext, ListContext, Placement, PlacementContext, ReleaseDeployContext, RetainContext, } from './context.js';
+export type { AdapterCommand, AdapterCommandContext, AdapterCommandResult } from './command.js';
+export type { DeploymentCallTarget, ListedDeployment } from './list.js';
+export type { DeploymentSecretsState, FailedReleaseDeployResult, MutationKnowledge, ReadyReleaseDeployResult, ReleaseDeploymentPhase, ReleaseDeployResult, } from './result.js';

package/dist/deployment/adapter/release/index.js

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

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

@@ -0,0 +1,53 @@
+import type { DeploymentSummaryV1 } from '../../address/index.js';
+/**
+ * Where one listed deployment is called on its host, so that an operator can act on it:
+ *
+ * - `services`: a deployment Admin's Services hosts, called on the Admin instance with
+ *   `astrale call "<node>.method.<method>" --admin` (`--admin=<admin>` when `admin` names the
+ *   Admin bookmark). `path` is the deployment's node, `@<id>`, qualified by its class,
+ *   `@<id>::services.astrale.ai:class.CloudflareDeployment`, whose only Method is `retire`.
+ *   `service` is the node of the Service it is a version of,
+ *   `@<serviceId>::services.astrale.ai:class.CloudflareService`, whose Methods act on the Service
+ *   and the deployment it currently serves: `promote` (this deployment's label rolls the Service
+ *   back or forward to it), `setSecret` and `secrets`, `setSchedule` and `schedules`, `logs`,
+ *   `transfer` and `delete`.
+ * - `namespace`: a deployment of a Cloudflare dispatch namespace (adapter-cloudflare's namespace
+ *   mode), which has no Services node: the namespace and the script, which the hosting kit
+ *   (`@astrale-os/adapter-cloudflare/hosting`) retires, points a name at or schedules.
+ */
+export type DeploymentCallTarget = {
+    readonly kind: 'services';
+    readonly path: string;
+    readonly service: string;
+    /** The Admin bookmark the deployment is reached through; the CLI's own Admin target when absent. */
+    readonly admin?: string;
+} | {
+    readonly kind: 'namespace';
+    readonly namespace: string;
+    readonly script: string;
+};
+/**
+ * One deployment as an adapter's `list` returns it: what its host knows of it, its record as the
+ * host stores it, and where it is called. Admin's Services keeps every deployment until it is
+ * retired and counts no call: its deployments are `published` and `withdrawn` once retiring. A
+ * Cloudflare dispatch namespace keeps no retention: its rows carry none, and carry their creation
+ * instant and key only while their script exists. Deployments have no last-call or expiry clock.
+ *
+ * The adapter does not admit the record. The listing admits it with `acceptDeploymentRecord`, and a
+ * record it refuses (one a host on an older SDK still admits, say) never fails the listing: that
+ * deployment is listed from the facts its host owns.
+ */
+export interface ListedDeployment extends Omit<DeploymentSummaryV1, 'record'> {
+    /**
+     * The record as the host stores it, unadmitted, whatever value that is (JSON `null` included).
+     * Absent when the host keeps no record of the deployment: a dispatch namespace keeps none for a
+     * label it only retired.
+     */
+    readonly record?: unknown;
+    /**
+     * Whether the stable URL of the deployment's Service serves it. Present only where the host has
+     * Services (Admin's Services); a dispatch namespace has none.
+     */
+    readonly current?: boolean;
+    readonly callTarget: DeploymentCallTarget;
+}

package/dist/deployment/adapter/release/list.js

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

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

@@ -0,0 +1,10 @@
+/**
+ * Why the host can no longer keep one published deployment (`Adapter.retain`): it is `absent`
+ * (the host holds no deployment of that label, or it was deleted) or `retired` (withdrawn, never
+ * served again). No rerun keeps it; a new version publishes a new deployment. Any other rejection
+ * of `retain` is transient: once it has passed, a rerun keeps the deployment.
+ */
+export declare class RetainRefusal extends Error {
+    readonly reason: 'absent' | 'retired';
+    constructor(reason: RetainRefusal['reason'], message: string);
+}