@astrale-os/sdk 0.6.0-beta.10 → 0.6.0-beta.11

package/README.md

@@ -1,8 +1,8 @@
 # SDK
 
-Schema-first SDK for authoring and deploying Astrale Applications. The public surface separates
+Schema-first SDK for authoring and deploying Astrale Domains. 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
+authoring, Domain 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)
@@ -17,7 +17,7 @@ npm install @astrale-os/sdk
 ```
 
 Zod schemas cross the SDK and Kernel compiler boundary by runtime identity. The SDK therefore
-declares one exact, non-optional Zod peer. If an Application declares Zod directly, it must use the
+declares one exact, non-optional Zod peer. If a Domain declares Zod directly, it must use the
 same exact version rather than a range; a second physical Zod runtime is not an admitted authoring
 environment.
 
@@ -67,9 +67,10 @@ original issuer discovery endpoints and keys available; unadopted instances cont
 previous bindings. Deployment readiness checks the exact new Worker version separately from issuer
 discovery. No uninstall or identity rotation is involved.
 
-At the provider-neutral release boundary, use
-`addressing('https://services.example.com', { publicUrl: 'https://services-v2.example.com' })`.
-The one-argument form continues to use the issuer as the public URL.
+At the provider-neutral release boundary, this stable-target path uses
+`addressing('https://services.example.com', { publicUrl: 'https://services-v2.example.com' })` with
+`legacy.assemble`. That split is deprecated with direct mode and goes with it: an immutable
+deployment's URL is its issuer, so `assemble(build, buildDigest, url)` takes the URL alone.
 
 ## Handler authority and dependencies
 
@@ -135,7 +136,7 @@ Error declarations are not yet published in the installed Kernel Schema.
 ### Core Identity requirements
 
 Use `requirements({ core: [{ subject, functions, classes, authority }] })` to declare capabilities
-for an Identity in the Application's local Core. `subject` is the resolved Core Node; each entry
+for an Identity in the Domain's local Core. `subject` is the resolved Core Node; each entry
 must request at least one capability. The top-level `functions`, `classes`, and `authority` members
 describe capabilities for the Domain principal.
 
@@ -316,6 +317,48 @@ await session.graph.get('@order-id') // Kernel callable: the source credential
 | Session with `exchange` | the declaring Domain, for Domain callables | ✅ with the source credential | ✅ Policy evaluated against the identity |
 | `session.exchange(issuer)` held by a second Session | that Domain | ✅ as that Domain | only what that Domain may use |
 
+## Deployment addresses
+
+`@astrale-os/sdk/deployment/address` derives the one immutable URL of a deployment,
+`https://<line>-<content>.<routingDomain>`, from its inputs alone. Whoever deploys and whoever
+hosts compute it with the same pure, runtime-safe functions, so a host can refuse an address it
+did not derive.
+
+- **Line.** `deploymentLine({ origin, environment, addressing })` is shared by every deployment of
+  an origin in an environment. Its 16-character fingerprint, the first 80 bits of
+  `sha256(origin ‖ 0x00 ‖ environment)` in base32, makes it unique. A `readable` line (platform
+  Domains) prefixes it with a cosmetic part, so `agencies.example.com` in `staging` gives
+  `agencies-staging-354iwg4avm6wdmrs`. An `opaque` line (tenant Domains) is the fingerprint alone.
+- **Content.** `deploymentContent(buildDigest, configuration)` covers the build and the
+  `FrozenConfigurationV1`: the plain variables and execution settings (with the durable Workflow
+  options, when declared), the services and dispatch namespaces it binds, and the names of the
+  bound secrets, never their values. A changed variable or binding gives another URL, and a rotated
+  secret keeps the URL. `configurationDigest` gives the full digest that a deployment record keeps. It checks
+  canonical form only: the host refuses settings no Worker runs under when it encodes
+  `ASTRALE_SETTINGS` (`encodeWorkerSettings`), before it uploads anything.
+- **Label.** `deploymentLabel(line, content)` is at most 57 characters. `DEPLOYMENT_LABEL`
+  recognizes it, never a legacy UUID or stable Worker name, and `parseDeploymentLabel` splits it
+  and refuses anything longer than 57 characters.
+- **Record.** `acceptDeploymentRecord` admits a `DeploymentRecordV1` only when its provider
+  script is the label that its own fields derive. A host admits the record a deploy declares with
+  it before storing it, so every stored record decodes.
+
+```ts
+import {
+  deploymentContent,
+  deploymentLabel,
+  deploymentLine,
+  deploymentUrl,
+} from '@astrale-os/sdk/deployment/address'
+
+const line = deploymentLine({ origin, environment, addressing: 'opaque' })
+const url = deploymentUrl(deploymentLabel(line, deploymentContent(build, configuration)), routingDomain)
+```
+
+`@astrale-os/sdk/deployment/address/vectors` holds the conformance vectors: Worker uploads and
+configurations with the manifest, build digest, label and URL each one gives. Every host that
+recomputes an address tests against them.
+
 ## License
 
 Apache License 2.0 — see [LICENSE](LICENSE) for details.
@@ -338,10 +381,13 @@ routes: {
 ```
 
 These requirements are publication metadata, so changing them updates the publication ETag without
-changing the Application's business Schema. They require the `shell` handshake. Origins must use
+changing the Domain's business Schema. They require the `shell` handshake. Origins must use
 HTTPS without credentials, paths, queries, fragments, or wildcards; authoring normalizes and sorts
 them. Supporting hosts admit them per mount and execute the existing `browser.openExternal`
 intent. Nested Views cannot expand their parent's grant.
 
 For the unified authentication facade and coordinated consumer update, see
 [the Auth API migration guide](docs/auth-api-migration.md).
+
+The authored composition formerly called an Application is now a Domain definition: see
+[the Domain definition migration guide](docs/domain-definition-migration.md).

package/dist/application/define.d.ts

@@ -1,16 +1,16 @@
 import type { schema } from '../platform/schema/index.js';
-import type { Application } from './application.js';
+import type { DomainDefinition } from './domain.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> {
+export interface DomainDefinitionInput<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;
+/** Capture one inert authored Domain without resolving, compiling, loading, or deploying it. */
+export declare function defineDomain<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: DomainDefinitionInput<Schema, RuntimeValue, FrontendValue, RoutesValue, RequirementsValue>): DomainDefinition<Schema, RuntimeValue, FrontendValue, RoutesValue, RequirementsValue>;
+export declare function isDomainDefinition(input: unknown): input is DomainDefinition;

package/dist/application/define.js

@@ -2,39 +2,39 @@ 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) {
+const admittedDomainDefinitions = new WeakSet();
+/** Capture one inert authored Domain without resolving, compiling, loading, or deploying it. */
+export function defineDomain(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.');
+        throw new TypeError('Domain 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.');
+        throw new TypeError('Domain Frontend is not admitted for its exact Schema.');
     }
     if (input.routes !== undefined && !isRoutes(input.routes)) {
-        throw new TypeError('Application routes are not admitted.');
+        throw new TypeError('Domain routes are not admitted.');
     }
     if (input.requirements !== undefined && !isRequirements(input.requirements)) {
-        throw new TypeError('Application requirements are not admitted.');
+        throw new TypeError('Domain requirements are not admitted.');
     }
-    const application = Object.freeze({
+    const domain = 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;
+    admittedDomainDefinitions.add(domain);
+    return domain;
 }
-export function isApplication(input) {
-    return input !== null && typeof input === 'object' && admittedApplications.has(input);
+export function isDomainDefinition(input) {
+    return input !== null && typeof input === 'object' && admittedDomainDefinitions.has(input);
 }
 function invalid() {
-    throw new TypeError('Application definition may contain only schema, runtime, frontend, routes, and requirements.');
+    throw new TypeError('Domain definition may contain only schema, runtime, frontend, routes, and requirements.');
 }

package/dist/application/domain.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 DOMAIN_DEFINITION_IDENTITY: unique symbol;
+declare const DOMAIN_DEFINITION_SCHEMA: unique symbol;
+/** Schema-independent type witness shared by every admitted Domain definition. */
+export interface DomainDefinitionIdentity {
+    readonly [DOMAIN_DEFINITION_IDENTITY]: true;
+}
+/** Inert source/build composition of one Domain: its exact Schema and authored Runtime. */
+export interface DomainDefinition<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 DomainDefinitionIdentity {
+    readonly schema: Schema;
+    readonly runtime: RuntimeValue;
+    readonly frontend?: FrontendValue;
+    readonly routes?: RoutesValue;
+    readonly requirements?: RequirementsValue;
+    readonly [DOMAIN_DEFINITION_SCHEMA]: (schema: Schema) => Schema;
+}
+export type SchemaOfDomainDefinition<Value> = Value extends {
+    readonly schema: infer Schema;
+} ? Extract<Schema, schema.DomainSchema> : never;
+export type RuntimeOfDomainDefinition<Value> = Value extends {
+    readonly runtime: infer RuntimeValue;
+} ? Extract<RuntimeValue, Runtime> : never;
+export type SchemaOfRuntime<Value> = RuntimeSchemaOf<Value>;
+export {};

package/dist/application/index.d.ts

@@ -1,9 +1,9 @@
-export { defineApplication, isApplication } from './define.js';
-export type { ApplicationInput } from './define.js';
+export { defineDomain, isDomainDefinition } from './define.js';
+export type { DomainDefinitionInput } from './define.js';
 export { requirements } from './requirements/index.js';
 export type { AuthorityRequirements, AuthorityRequirementsInput, ClassOperation, ClassRequirement, ClassRequirementInput, CoreRequirement, CoreRequirementInput, FunctionRequirementTarget, 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, ViewHostRequirements, } from './view/index.js';
-export type { Application, ApplicationIdentity, RuntimeOfApplication, SchemaOfApplication, SchemaOfRuntime, } from './application.js';
+export type { DomainDefinition, DomainDefinitionIdentity, RuntimeOfDomainDefinition, SchemaOfDomainDefinition, SchemaOfRuntime, } from './domain.js';

package/dist/application/index.js

@@ -1,4 +1,4 @@
-export { defineApplication, isApplication } from './define.js';
+export { defineDomain, isDomainDefinition } 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/routes/admission.d.ts

@@ -1,5 +1,5 @@
-import type { publication } from '@astrale-os/kernel-protocol';
+import type { release } from '@astrale-os/kernel-protocol';
 import type { RuntimeRegistry } from '../runtime/index.js';
 import type { Routes } from './collection.js';
 /** Lower recipe identities to canonical callable keys after Runtime admission. */
-export declare function admit(input: Routes | undefined, registry: RuntimeRegistry): readonly publication.HttpRouteDeclaration[];
+export declare function admit(input: Routes | undefined, registry: RuntimeRegistry): readonly release.HttpRouteDeclaration[];

package/dist/application/routes/admission.js

@@ -4,7 +4,7 @@ export function admit(input, registry) {
     if (input === undefined)
         return Object.freeze([]);
     if (!isRoutes(input))
-        throw new TypeError('Application routes are not admitted.');
+        throw new TypeError('Domain routes are not admitted.');
     return Object.freeze(input.entries.map(({ target, ...declaration }) => {
         const implementation = registry.implementations.find(({ definition }) => definition === target);
         if (implementation === undefined) {

package/dist/application/routes/route.d.ts

@@ -1,9 +1,9 @@
-import type { publication } from '@astrale-os/kernel-protocol';
+import type { release } from '@astrale-os/kernel-protocol';
 export interface RouteTarget {
     readonly kind: 'action' | 'workflow';
     readonly address: string;
 }
-export type RouteInput = Omit<publication.HttpRouteDeclaration, 'callable'>;
+export type RouteInput = Omit<release.HttpRouteDeclaration, 'callable'>;
 /** One provider-neutral HTTP route targeting an admitted Action or Workflow recipe. */
 export interface Route<Target extends RouteTarget = RouteTarget> extends RouteInput {
     readonly target: Target;

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

@@ -1,27 +1,76 @@
-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 { DeploymentSummaryV1, FrozenConfigurationV1 } from '../address/index.js';
+import type { Bundler } from './bundle/index.js';
+import type { ArtifactSource, DeployContext, DeployResult, InstallationTarget, PrepareContext } from './legacy/index.js';
+import type { ConfigureContext, ListContext, 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;
+    /**
+     * @deprecated Deploy-time installation, which the canonical path refuses (CT33). Replacement:
+     * `astrale domain install <url> -i <instance>` after `astrale-domain deploy <environment>`.
+     */
     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.
+ *
+ * `prepare` and `deploy` remain only for an adapter that also serves Environments on the legacy
+ * direct-mode path (CT33); an adapter declares both or neither.
+ */
 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>;
+    /** Freeze what a deployment of this Environment binds beside its build. Pure. */
+    configure(parameters: Parameters, context: ConfigureContext): FrozenConfigurationV1;
+    /** 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 origin the host keeps for the caller. */
+    list?(parameters: Parameters, context: ListContext): Promise<readonly DeploymentSummaryV1[]>;
+    /**
+     * Keep one published deployment where the host has no registry principal to mark it (a platform
+     * namespace). Called only after its Publication commits. Absent: the registry marks it (Admin's
+     * Services).
+     */
+    retain?(parameters: Parameters, context: RetainContext): Promise<void>;
+    /**
+     * @deprecated Legacy direct-mode path (CT33) only: place a build at a stable target. Replacement:
+     * `bundler`, `configure` and `placement`. Deleted with the legacy path (D10).
+     */
+    prepare?(parameters: Parameters, context: PrepareContext): Promise<ArtifactSource>;
+    /**
+     * @deprecated Legacy direct-mode path (CT33) only: replace a stable target's code in place.
+     * Replacement: `deployRelease`. Deleted with the legacy path (D10).
+     */
+    deploy?(parameters: Parameters, context: DeployContext): Promise<DeployResult>;
     readonly 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>;
+    configure(parameters: Parameters, context: ConfigureContext): FrozenConfigurationV1;
+    placement(parameters: Parameters, context: PlacementContext): Promise<Placement>;
+    deployRelease(parameters: Parameters, context: ReleaseDeployContext): Promise<ReleaseDeployResult>;
+    list?(parameters: Parameters, context: ListContext): Promise<readonly DeploymentSummaryV1[]>;
+    retain?(parameters: Parameters, context: RetainContext): Promise<void>;
+    /** @deprecated Legacy direct-mode path (CT33) only. Replacement: `configure`, `placement`. */
+    prepare?(parameters: Parameters, context: PrepareContext): Promise<ArtifactSource>;
+    /** @deprecated Legacy direct-mode path (CT33) only. Replacement: `deployRelease`. */
+    deploy?(parameters: Parameters, context: DeployContext): Promise<DeployResult>;
     readonly 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 or a legacy preparation 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,29 @@
 import type { Deployment } from '../deployment.js';
 import type { Adapter, AdapterInput } from './adapter.js';
-/** Capture one receiver-bound provider adapter. */
+import type { LegacyAdapter, LegacyAdapterInput } from './legacy/index.js';
+/**
+ * Capture one receiver-bound provider adapter (adapter interface v2): a required `bundler`,
+ * `configure`, `placement` and `deployRelease`, optionally `list` and `retain`, and `prepare` with
+ * `deploy` only while it also serves the legacy direct-mode path.
+ */
 export declare function defineAdapter<Parameters extends object>(input: AdapterInput<Parameters>): Adapter<Parameters>;
+/**
+ * Capture one receiver-bound adapter on the contract before interface v2: its required `bundler`,
+ * `prepare` and `deploy`.
+ *
+ * @deprecated Every Environment such an adapter deploys is on the legacy direct-mode path (CT33).
+ * Declare adapter interface v2 instead: `configure`, `placement` and `deployRelease` beside the
+ * same `bundler`.
+ */
+export declare function defineAdapter<Parameters extends object>(input: LegacyAdapterInput<Parameters>): LegacyAdapter<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>;
-export declare function isAdapter(input: unknown): input is Adapter;
+export declare function defineDeployment<const Parameters extends object>(adapter: Adapter<Parameters>, parameters: Parameters): Deployment<Parameters, Adapter<Parameters>>;
+/**
+ * Bind one adapter on the contract before interface v2 to the parameters of one Environment.
+ *
+ * @deprecated The Environment is on the legacy direct-mode path (CT33). Replacement: an adapter
+ * that implements adapter interface v2.
+ */
+export declare function defineDeployment<const Parameters extends object>(adapter: LegacyAdapter<Parameters>, parameters: Parameters): Deployment<Parameters, LegacyAdapter<Parameters>>;
+/** Whether `defineAdapter` admitted this value, on either contract. */
+export declare function isAdapter(input: unknown): input is Adapter | LegacyAdapter;

package/dist/deployment/adapter/define.js

@@ -1,29 +1,78 @@
 import { captureDeployment } from '../deployment.js';
 const admittedAdapters = new WeakSet();
-/** Capture one receiver-bound provider adapter. */
+const admittedBundlers = new WeakMap();
+/** Every field an adapter definition may declare, in either contract. */
+const FIELDS = [
+    'name',
+    'version',
+    'bundler',
+    'admit',
+    'configure',
+    'placement',
+    'deployRelease',
+    'list',
+    'retain',
+    'prepare',
+    'deploy',
+    'secretsFile',
+];
+/** The operations that make a definition adapter interface v2. */
+const RELEASE_OPERATIONS = ['configure', 'placement', 'deployRelease'];
+const OPTIONAL_RELEASE_OPERATIONS = ['list', 'retain'];
+/** The operations of the legacy direct-mode path. */
+const STABLE_TARGET_OPERATIONS = ['prepare', 'deploy'];
+/** Every operation an adapter may declare, in the order an admitted adapter lists them. */
+const OPERATIONS = FIELDS.filter((key) => key !== 'name' && key !== 'version' && key !== 'bundler');
 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 declared = (key) => value[key] !== undefined;
+    const release = [...RELEASE_OPERATIONS, ...OPTIONAL_RELEASE_OPERATIONS].some(declared);
+    // A legacy definition names both operations, as it always had to; v2 treats undefined as absent.
+    const stableTarget = STABLE_TARGET_OPERATIONS.filter((key) => release ? declared(key) : Object.hasOwn(value, key));
+    if (!release && stableTarget.length !== STABLE_TARGET_OPERATIONS.length)
+        invalidFields();
     const name = stableName(input.name);
     const version = stableName(input.version);
+    if (release)
+        admitRelease(name, value, stableTarget.length);
+    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 required = new Set([...(release ? RELEASE_OPERATIONS : []), ...stableTarget]);
+    const operations = Object.fromEntries(OPERATIONS.filter((key) => required.has(key) || declared(key)).map((key) => [
+        key,
+        capture(receiver, key),
+    ]));
     const adapter = Object.freeze({
         kind: 'adapter',
         name,
         version,
-        ...(admit === undefined ? {} : { admit }),
-        prepare,
-        deploy,
-        ...(secretsFile === undefined ? {} : { secretsFile }),
+        bundler,
+        ...operations,
     });
     admittedAdapters.add(adapter);
     return adapter;
 }
-/** Bind one provider adapter to the parameters of one Project Environment. */
+/**
+ * An adapter interface v2 definition implements configure, placement and deployRelease, and keeps
+ * prepare with deploy, or neither.
+ */
+function admitRelease(name, value, stableTargetOperations) {
+    const missing = RELEASE_OPERATIONS.filter((key) => value[key] === undefined);
+    if (missing.length > 0) {
+        throw new TypeError(`Adapter ${name} declares part of adapter interface v2 without ${missing.join(', ')}: ` +
+            'an adapter that deploys immutable deployments implements configure, placement and ' +
+            'deployRelease.');
+    }
+    if (stableTargetOperations === 1) {
+        throw new TypeError(`Adapter ${name} declares only one of prepare and deploy: an adapter that keeps the legacy ` +
+            'direct-mode path declares both.');
+    }
+}
 export function defineDeployment(adapter, parameters) {
     if (!isAdapter(adapter))
         throw new TypeError('Deployment Adapter is not admitted.');
@@ -32,12 +81,39 @@ export function defineDeployment(adapter, parameters) {
     }
     return captureDeployment(adapter, Object.freeze({ ...parameters }));
 }
+/** Whether `defineAdapter` admitted this value, on either contract. */
 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 +123,21 @@ 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, on either contract, 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`).');
+}
+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,6 @@
-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 type * from './bundle/index.js';
+export type * from './release/index.js';
+/** @deprecated The contract before adapter interface v2; see `./legacy/index.ts`. */
+export type * from './legacy/index.js';