@astrale-os/sdk 0.6.0-beta.2 → 0.6.0-beta.20

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

@@ -2,8 +2,14 @@ import type { Domain } from '../../platform/schema/index.js';
 import type { ActionContext, ResolvedCallable } from '../action/index.js';
 import type { DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { Integrations } from '../integration/index.js';
+import type { DurableCallable, DurableWorkflowContext } from './durable.js';
 import type { WorkflowStep } from './step/index.js';
-/** Exact multi-step Workflow context for one authenticated value-output callable. */
-export type WorkflowContext<Callable extends ResolvedCallable, DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> = ActionContext<Callable, DomainValue, Definitions, Errors> & {
+/** Multi-step context of one authenticated value-output callable run inside its invocation. */
+export type InlineWorkflowContext<Callable extends ResolvedCallable, DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> = ActionContext<Callable, DomainValue, Definitions, Errors> & {
     readonly step: WorkflowStep;
 };
+/**
+ * Exact Workflow context for one callable: engine-journaled when its Schema declares
+ * `execution: { durable: true }`, otherwise run inside its invocation.
+ */
+export type WorkflowContext<Callable extends ResolvedCallable, DomainValue extends Domain = Domain, Definitions extends Integrations = Readonly<Record<never, never>>, Errors extends DeclaredErrors = NoDeclaredErrors> = Callable extends DurableCallable ? DurableWorkflowContext<Callable, DomainValue, Errors> : InlineWorkflowContext<Callable, DomainValue, Definitions, Errors>;

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

@@ -1,11 +1,11 @@
 import type { schema } from '../../platform/schema/index.js';
 import type { ResolvedDomainOf } from '../action/index.js';
-import type { DeclaredErrorOptions, DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
+import type { DeclaredErrors, NoDeclaredErrors } from '../error/index.js';
 import type { Integrations } from '../integration/index.js';
-import type { CallableAtWorkflowAddress, Workflow, WorkflowAddress, WorkflowDefinition } from './workflow.js';
+import type { CallableAtWorkflowAddress, Workflow, WorkflowAddress, WorkflowDefinition, WorkflowOptions } from './workflow.js';
 /** Define one authenticated multi-step value-output implementation by its SDK Action address. */
 export declare function defineWorkflow<Schema extends schema.DomainSchema, Definitions extends Integrations = Readonly<Record<never, never>>>(): {
     <const Address extends WorkflowAddress<Schema>>(address: Address, run: Workflow<CallableAtWorkflowAddress<Schema, Address>, Definitions, ResolvedDomainOf<Schema>, NoDeclaredErrors>): WorkflowDefinition<Schema, Address, Definitions, NoDeclaredErrors>;
-    <const Address extends WorkflowAddress<Schema>, const Errors extends DeclaredErrors>(address: Address, options: DeclaredErrorOptions<Errors>, run: Workflow<CallableAtWorkflowAddress<Schema, Address>, Definitions, ResolvedDomainOf<Schema>, Errors>): WorkflowDefinition<Schema, Address, Definitions, Errors>;
+    <const Address extends WorkflowAddress<Schema>, const Errors extends DeclaredErrors = NoDeclaredErrors>(address: Address, options: WorkflowOptions<Errors>, run: Workflow<CallableAtWorkflowAddress<Schema, Address>, Definitions, ResolvedDomainOf<Schema>, Errors>): WorkflowDefinition<Schema, Address, Definitions, Errors>;
 };
 export declare function isWorkflow(input: unknown): input is WorkflowDefinition;

package/dist/application/workflow/define.js

@@ -1,11 +1,12 @@
 import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
 import { rememberDeclaredErrors } from '../error/index.js';
 const admittedWorkflows = new WeakSet();
+const COMPAT_TOKEN = /^[A-Za-z0-9._~-]{1,64}$/u;
 /** Define one authenticated multi-step value-output implementation by its SDK Action address. */
 export function defineWorkflow() {
     return function define(address, optionsOrRun, possibleRun) {
         acceptWorkflowAddress(address);
-        const options = possibleRun === undefined ? undefined : optionsOrRun;
+        const options = possibleRun === undefined ? undefined : acceptOptions(optionsOrRun);
         const run = possibleRun ?? optionsOrRun;
         if (typeof run !== 'function')
             throw new TypeError('Workflow run must be a function.');
@@ -13,13 +14,28 @@ export function defineWorkflow() {
             kind: 'workflow',
             address,
             run,
+            ...(options?.compat === undefined ? {} : { compat: options.compat }),
         });
-        if (options !== undefined)
-            rememberDeclaredErrors(workflow, options);
+        if (options?.errors !== undefined)
+            rememberDeclaredErrors(workflow, { errors: options.errors });
         admittedWorkflows.add(workflow);
         return workflow;
     };
 }
+function acceptOptions(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        Reflect.ownKeys(input).some((key) => key !== 'errors' && key !== 'compat')) {
+        throw new TypeError('Workflow options accept only errors and compat.');
+    }
+    const options = input;
+    if (options.compat !== undefined &&
+        (typeof options.compat !== 'string' || !COMPAT_TOKEN.test(options.compat))) {
+        throw new TypeError(`Invalid Workflow compat token: ${JSON.stringify(options.compat)}.`);
+    }
+    return options;
+}
 export function isWorkflow(input) {
     return input !== null && typeof input === 'object' && admittedWorkflows.has(input);
 }

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

@@ -0,0 +1,83 @@
+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` 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.
+     */
+    readonly kernel: BoundClientSession;
+    readonly query: QueryExecutor<DomainValue>;
+    /** Each Mutation carries a key derived from the Execution, the Step and its position. */
+    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, so its effects must be idempotent.
+     */
+    run<Output>(id: string, execute: (authority: DurableStepAuthority<DomainValue>) => Output | Promise<Output>): Promise<Output>;
+    /**
+     * One journaled Mutation. Give it a zero-match precondition on a natural key (for example the
+     * Execution id) and map that failure in `reject`, so a Step replayed after its commit finds its
+     * own effect instead of repeating it.
+     */
+    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

@@ -12,11 +12,23 @@ export type WorkflowAddress<Schema extends schema.DomainSchema> = ActionAddressO
 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,75 @@
-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 { FrozenConfigurationV1 } from '../address/index.js';
+import type { Bundler } from './bundle/index.js';
+import type { ArtifactSource, DeployContext, DeployResult, PrepareContext } from './legacy/index.js';
+import type { 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.
+ *
+ * `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 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 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>;
+    /**
+     * @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 ListedDeployment[]>;
+    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;