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

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,7 @@
-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';
+/** @deprecated The contract before adapter interface v2; see `./legacy/index.ts`. */
+export type * from './legacy/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/legacy/adapter.d.ts

@@ -0,0 +1,40 @@
+import type { AdapterEnvironmentContext } from '../adapter.js';
+import type { Bundler } from '../bundle/index.js';
+import type { DeployContext, DeployResult } from './deploy/index.js';
+import type { ArtifactSource, PrepareContext } from './prepare/index.js';
+/**
+ * A provider adapter on the contract before adapter interface v2: `prepare` places a build at one
+ * stable target per Environment and `deploy` replaces that target's code in place. It declares no
+ * `deployRelease`, so every Environment it deploys is on the legacy direct-mode path (CT33). Like
+ * every adapter, it declares its `bundler`: `astrale-domain deploy` bundles first and `prepare`
+ * only places that Bundle.
+ *
+ * @deprecated Replacement: `Adapter` (adapter interface v2), whose `deployRelease` deploys one
+ * sealed release as one immutable deployment. See `./index.ts` for its consumers and removal.
+ */
+export interface LegacyAdapter<Parameters extends object = object> {
+    readonly kind: 'adapter';
+    readonly name: string;
+    readonly version: string;
+    /** Environment-free bytes `astrale-domain build` identifies by their build digest. */
+    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;
+}
+/**
+ * What `defineAdapter` admits for a `LegacyAdapter`.
+ *
+ * @deprecated Replacement: `AdapterInput` (adapter interface v2). See `./index.ts`.
+ */
+export interface LegacyAdapterInput<Parameters extends object> {
+    readonly name: string;
+    readonly version: string;
+    /** Environment-free bytes `astrale-domain build` identifies by their build digest. */
+    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;
+}

package/dist/deployment/adapter/{deploy → legacy/deploy}/context.d.ts

@@ -1,9 +1,13 @@
-import type { InstallationTarget } from '../adapter.js';
 import type { PreparedArtifact } from '../prepare/index.js';
+/**
+ * What a legacy `deploy` receives to replace one Environment's stable target in place.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement:
+ * `ReleaseDeployContext`, which `deployRelease` receives.
+ */
 export interface DeployContext {
     readonly projectDir: string;
     readonly environment: string;
-    readonly installation?: InstallationTarget;
     /** Optional command-scoped identity override (`--as`). */
     readonly identity?: string;
     /** Optional command-scoped credential; trusted adapters must neither retain nor disclose it. */

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

@@ -0,0 +1,2 @@
+export type { DeployContext } from './context.js';
+export type { AppliedProviderDeployment, DeploymentPhase, DeploymentProgress, DeployResult, FailedDeployResult, ProviderDeploymentEvidence, ReadyDeployResult, } from './result.js';

package/dist/deployment/adapter/legacy/deploy/index.js

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

package/dist/deployment/adapter/legacy/deploy/result.d.ts

@@ -0,0 +1,89 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+import type { BuildDigest } from '../../../build/index.js';
+import type { Addressing } from '../../../release/index.js';
+import type { Release } from '../../../release/legacy/index.js';
+import type { MutationKnowledge } from '../../release/index.js';
+/**
+ * Where a legacy `deploy` stopped.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement:
+ * `ReleaseDeploymentPhase`; an immutable deployment is neither addressed nor installed by its deploy.
+ */
+export type DeploymentPhase = 'prerequisite' | 'provider' | 'addressing' | 'release' | 'configuration' | 'readiness';
+/**
+ * What a provider reports for the stable target it replaced.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement: the
+ * `DeploymentRecordV1` of `ReadyReleaseDeployResult`; a provider deployment or version id never
+ * identifies an immutable deployment.
+ */
+export interface ProviderDeploymentEvidence {
+    readonly provider: string;
+    readonly deployment: string;
+    readonly artifact: Digest;
+    /**
+     * Build digest of the portable upload (modules and assets) this deployment was made from, which
+     * `astrale-domain deploy` compares with the Bundle it passed as `PrepareContext.bundle`. Present
+     * only when preparation placed that Bundle. A provider that bundles the upload again (Wrangler in
+     * direct mode) runs other bytes than these. Legacy prepare/deploy surface: deleted with it.
+     */
+    readonly build?: BuildDigest;
+    readonly issuer?: Addressing['issuer'];
+    /** Optional provider-side check before promotion; distinct from public readiness. */
+    readonly preflight?: 'passed' | 'unavailable';
+}
+/** @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). */
+export type AppliedProviderDeployment = {
+    readonly kind: 'applied';
+    readonly evidence: ProviderDeploymentEvidence & {
+        readonly issuer: Addressing['issuer'];
+    };
+};
+/**
+ * What a legacy `deploy` changed, effect by effect.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement:
+ * `FailedReleaseDeployResult.provider`.
+ */
+export interface DeploymentProgress {
+    readonly prerequisite: MutationKnowledge;
+    readonly provider: MutationKnowledge<ProviderDeploymentEvidence>;
+    readonly configuration: MutationKnowledge;
+}
+/**
+ * A stable target replaced in place and ready.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement:
+ * `ReadyReleaseDeployResult`, the immutable deployment `deployRelease` created or reused.
+ */
+export interface ReadyDeployResult {
+    readonly status: 'ready';
+    readonly phase: 'complete';
+    readonly progress: DeploymentProgress & {
+        readonly provider: AppliedProviderDeployment;
+    };
+    /**
+     * The stable-target Release (v3 Publication) of the legacy `deploy` operation. A canonical deploy
+     * reaches its adapter through `deployRelease` with the v4 Release (CT23); D10 deletes `deploy`
+     * and this result with the direct-mode path.
+     */
+    readonly release: Release;
+}
+/**
+ * A legacy `deploy` that did not reach a ready stable target.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement:
+ * `FailedReleaseDeployResult`.
+ */
+export interface FailedDeployResult {
+    readonly status: 'failed';
+    readonly phase: DeploymentPhase;
+    readonly progress: DeploymentProgress;
+    readonly error: Error;
+    readonly release?: Release;
+}
+/**
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement:
+ * `ReleaseDeployResult`.
+ */
+export type DeployResult = ReadyDeployResult | FailedDeployResult;

package/dist/deployment/adapter/legacy/deploy/result.js

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

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

@@ -0,0 +1,24 @@
+/**
+ * The adapter contract before adapter interface v2: `prepare` places a build at one stable target
+ * per Environment, `deploy` replaces that target's code in place, and the stable target serves a
+ * v3 Publication under an issuer bound to it for life. Neither installs anything.
+ *
+ * @deprecated Replacement: `Adapter` (adapter interface v2): beside the same `bundler`, `configure`,
+ * `placement` and `deployRelease`, which deploys one sealed release as one immutable deployment,
+ * created or reused, and installs nothing.
+ *
+ * Short-term consumers: the legacy direct-mode path (CT33), which `astrale-domain deploy`
+ * runs through these operations: adapter-cloudflare direct mode (`route`,
+ * `workerName`, `identityIssuer`, `addressing`, `signingIdentity`, or no `namespace`), which serves
+ * the configurations of domains ai-gateway, closing, grc, integrations and issues (until SV15),
+ * domains organization (until it leaves direct mode, AM-147), the Services `beta` and `prod` (until
+ * SV12), `development` (until SV9) and frozen `admin-beta` (until D19) environments, shell (until
+ * SH2) and its frozen `legacy-v3` (until D22), and ui:domain (until UI1).
+ *
+ * Removal: D10, once no configuration on any repository's main selects the direct-mode path
+ * (CT33, AM-147); it deletes these types with `prepare`/`deploy`, `src/deployment/release/legacy`
+ * and the stable-target CLI path.
+ */
+export type { LegacyAdapter, LegacyAdapterInput } from './adapter.js';
+export type * from './prepare/index.js';
+export type * from './deploy/index.js';

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

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

package/dist/deployment/adapter/legacy/prepare/artifact.d.ts

@@ -0,0 +1,43 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+import type { Build } from '../../../build/index.js';
+import type { Addressing } from '../../../release/index.js';
+import type { ArtifactFile, PreparedArtifactFile } from '../../bundle/index.js';
+/**
+ * Where the stable target of one Environment answers: configured by the author or assigned by the
+ * provider.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement: `Placement`,
+ * from which `deploymentUrl(label, placement.routingDomain)` derives an immutable deployment's URL.
+ */
+export type AddressingPlan = {
+    readonly kind: 'configured';
+    readonly addressing: Addressing;
+} | {
+    readonly kind: 'provider-assigned';
+    readonly claim: string;
+};
+/**
+ * Untrusted provider-specific preparation output admitted by verify/preflight.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement: the `Bundle`
+ * the adapter's `bundler` produces, which `deployRelease` receives.
+ */
+export interface ArtifactSource {
+    readonly entrypoint: string;
+    readonly files: readonly ArtifactFile[];
+    readonly addressing: AddressingPlan;
+}
+/**
+ * Exact detached input supplied to every provider deployment effect.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement: the `Bundle`
+ * and `FrozenConfigurationV1` that `deployRelease` receives.
+ */
+export interface PreparedArtifact<BuildValue extends Build = Build> {
+    readonly kind: 'prepared-artifact';
+    readonly build: BuildValue;
+    readonly digest: Digest;
+    readonly entrypoint: string;
+    readonly files: readonly PreparedArtifactFile[];
+    readonly addressing: AddressingPlan;
+}

package/dist/deployment/adapter/legacy/prepare/artifact.js

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

package/dist/deployment/adapter/legacy/prepare/context.d.ts

@@ -0,0 +1,33 @@
+import type { Build } from '../../../build/index.js';
+import type { ResolvedRuntimeReference } from '../../../runtime/index.js';
+import type { Bundle } from '../../bundle/index.js';
+/**
+ * What `prepare` receives to produce the artifact of one Environment's stable target.
+ *
+ * @deprecated Legacy `prepare`/`deploy` contract (see `../index.ts`). Replacement: `configure`,
+ * `placement` and the Bundle of the adapter's `bundler`, which `deployRelease` receives.
+ */
+export interface PrepareContext<BuildValue extends Build = Build> {
+    readonly projectDir: string;
+    readonly environment: string;
+    /**
+     * Preparation purpose. One-shot deployment prepares complete release artifacts. Omitted by
+     * older custom callers means release for compatibility during the beta migration.
+     */
+    readonly mode?: 'release';
+    /**
+     * Optional preparation-input observer used by tooling that must rebuild when
+     * an adapter reads authored paths outside the Domain/Runtime module graph.
+     */
+    readonly recordSource?: (path: string) => void;
+    /** Parent-owned lifecycle cancellation shared by every preparation process/effect. */
+    readonly signal: AbortSignal;
+    readonly build: BuildValue;
+    readonly runtime: ResolvedRuntimeReference;
+    /**
+     * The environment-free Bundle of the adapter's own `bundler`, which `astrale-domain deploy`
+     * always produces first so that preparation only places it. Absent for a custom caller, the
+     * adapter bundles by itself. Legacy prepare/deploy surface: deleted with it.
+     */
+    readonly bundle?: Bundle<BuildValue>;
+}

package/dist/deployment/adapter/legacy/prepare/context.js

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

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

@@ -0,0 +1,2 @@
+export type { PrepareContext } from './context.js';
+export type { AddressingPlan, ArtifactSource, PreparedArtifact } from './artifact.js';

package/dist/deployment/adapter/legacy/prepare/index.js

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

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

@@ -0,0 +1,95 @@
+import type { DeploymentCommitV1, FrozenConfigurationV1, 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 in
+     * `bindings.secrets`.
+     */
+    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: FrozenConfigurationV1;
+    /** 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/context.js

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

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

@@ -0,0 +1,3 @@
+export type { ConfigureContext, ListContext, Placement, PlacementContext, ReleaseDeployContext, RetainContext, } from './context.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 platform dispatch namespace, which has no Services node: the
+ *   namespace and the script the per-script tooling of that namespace takes.
+ */
+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. `lastCallAt`, and a preview's `expiresAt`, are as of the
+ * listing: an adapter whose host records calls only now and then reads the calls counted since, and
+ * one that cannot read them for want of a permission omits both rather than print stale values.
+ * Admin's Services keeps every deployment until it is retired and counts no call: its deployments
+ * are `published`, `withdrawn` once retiring, and carry neither 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 platform namespace keeps none until
+     * it activates the deployment.
+     */
+    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 platform 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);
+}

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

@@ -0,0 +1,14 @@
+/**
+ * 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 class RetainRefusal extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = 'RetainRefusal';
+        this.reason = reason;
+    }
+}