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

package/dist/tooling/cli/dotenv.d.ts

@@ -7,6 +7,8 @@
  * runtime in dev, pushed to a secret store in prod). No `process.env` mutation,
  * no interpolation magic beyond `${VAR}` against earlier keys in the same file.
  */
+/** Parse one dotenv document into a flat record; `${VAR}` reads only earlier keys. */
+export declare function parseDotenv(contents: string): Record<string, string>;
 /**
  * Read + parse a dotenv file the preset explicitly DECLARED (`secrets:`).
  * Declared-but-absent is a wiring error (the gitignored file was never created
@@ -15,5 +17,3 @@
  * that exists but holds no keys is legitimate (a domain with no secrets yet).
  */
 export declare function loadDeclaredSecrets(path: string, declaration: string): Record<string, string>;
-/** Load one explicit development-session secret snapshot without following a leaf symlink. */
-export declare function loadPrivateSecretsFile(path: string, platform?: NodeJS.Platform): Record<string, string>;

package/dist/tooling/cli/dotenv.js

@@ -7,8 +7,9 @@
  * runtime in dev, pushed to a secret store in prod). No `process.env` mutation,
  * no interpolation magic beyond `${VAR}` against earlier keys in the same file.
  */
-import { closeSync, constants, fstatSync, openSync, readFileSync } from 'node:fs';
-function parseDotenv(contents) {
+import { readFileSync } from 'node:fs';
+/** Parse one dotenv document into a flat record; `${VAR}` reads only earlier keys. */
+export function parseDotenv(contents) {
     const out = {};
     for (const raw of contents.split('\n')) {
         const line = raw.trim();
@@ -52,34 +53,3 @@ export function loadDeclaredSecrets(path, declaration) {
     }
     return parseDotenv(contents);
 }
-/** Load one explicit development-session secret snapshot without following a leaf symlink. */
-export function loadPrivateSecretsFile(path, platform = process.platform) {
-    if (platform === 'win32') {
-        throw new Error('--secrets-file is unavailable on Windows until private no-reparse file admission is supported.');
-    }
-    let descriptor;
-    try {
-        descriptor = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
-    }
-    catch (cause) {
-        if (cause instanceof Error && 'code' in cause && cause.code === 'ENOENT') {
-            throw new Error(`Secrets file '${path}' is missing.`, { cause });
-        }
-        if (cause instanceof Error && 'code' in cause && cause.code === 'ELOOP') {
-            throw new Error(`Secrets file '${path}' must be a regular file and not a symlink.`, { cause });
-        }
-        throw cause;
-    }
-    try {
-        const info = fstatSync(descriptor);
-        if (!info.isFile())
-            throw new Error(`Secrets file '${path}' must be a regular file.`);
-        if ((info.mode & 0o077) !== 0) {
-            throw new Error(`Secrets file '${path}' must not be accessible by group or other users.`);
-        }
-        return parseDotenv(readFileSync(descriptor, 'utf8'));
-    }
-    finally {
-        closeSync(descriptor);
-    }
-}

package/dist/tooling/cli/help.js

@@ -1,4 +1,6 @@
+import { installCommand } from '../../project/install-command.js';
 import { COMMANDS } from './arguments.js';
+import { MINIMUM_INSTALLATIONS_CLI_VERSION } from './registry/executable.js';
 /** Resolve help without parsing a project or performing any command effects. */
 export function helpRequest(argv) {
     if (!argv.some((argument) => argument === '--help' || argument === '-h'))
@@ -12,19 +14,22 @@ export function helpText(command) {
 export const ERROR_USAGE = `Usage: astrale-domain <command> [options]
 Run "astrale-domain --help" for available commands.
 `;
-const GLOBAL_HELP = `Build, develop, deploy, test, lint, and package Astrale Domains.
+const GLOBAL_HELP = `Build, deploy, list, test, lint, and package Astrale Domains.
 
 Usage:
   astrale-domain <command> [options]
 
 Commands:
-  dev [environment]       Remotely deploy and watch one Project Environment.
-  build                   Build and verify without deploying.
-  deploy <environment>    Deploy and optionally install one Environment.
+  build                   Build, verify and print the build digest.
+  deploy <environment>    Deploy one Environment; never installs.
+  diff                    Show the changes since the published version and the minimum.
+  list                    List the deployments of the Project's Environments.
+  publish <environment>   Deploy, verify and publish the package.json version; never installs.
   test                    Run Project tests, optionally against one Environment.
   lint                    Check Domain source and architecture.
   package                 Prepare public declarations for publication.
   upgrade                 Update Astrale dependencies through pnpm (default: beta).
+  yank <version>          Take a published version out of resolution, or put it back.
 
 Options:
   -h, --help              Show help.
@@ -51,88 +56,178 @@ Behavior:
   unchanged with a warning.
   Local links, catalogs, aliases, peers, and overrides are not rewritten.
   Does not load astrale.config.ts, require Bun, run project checks, commit, or deploy.
-  Stop development watchers before upgrading. Review changes and run your project's
-  checks afterwards. Failed installations leave local changes available for repair.
+  Review changes and run your project's checks afterwards. Failed installations leave
+  local changes available for repair.
   For an older SDK without this command: pnpm dlx @astrale-os/sdk@beta upgrade.
 `,
-    dev: `Build, verify, remotely deploy, and watch one Project Environment.
+    build: `Build and verify a Domain without deploying it, and print its build digest.
 
 Usage:
-  astrale-domain dev [environment] [options]
+  astrale-domain build [--json]
+
+Options:
+  --json                  Print one BuildResultV1 document on stdout.
+  -h, --help              Show help for build.
+
+Behavior:
+  Compiles the Domain and verifies that the conventional or configured Runtime
+  module exports the exact Runtime owned by it. Then bundles it once per distinct
+  bundler of the Project's adapters and prints each build digest: the hash of the
+  produced modules, assets, Schema and requirements. It does not select an Environment,
+  load secrets, deploy, or install the Domain, so every Environment whose adapter
+  shares a bundler deploys the code of that one digest.
+`,
+    deploy: `Build, verify, and deploy a Domain through its configured adapter.
+
+Usage:
+  astrale-domain deploy <environment> [--json]
+  astrale-domain deploy --environment <name> [--json]
 
 Arguments:
-  environment             Project Environment name; defaults to development.
+  environment             Required adapter environment key.
 
 Options:
   --environment <name>    Select the environment without a positional argument.
-  --deploy-only           Suppress this run's configured Kernel installation.
-  --as <identity>         Select the Astrale identity for Services and installation calls.
-  --session-file <path>   Write one retained DevelopmentSessionFileV1 snapshot at an
-                          absolute path in a caller-owned private directory.
-  --credential-file <path>
-                          Use one private operator credential for provider and Kernel
-                          calls without exposing it in Project configuration.
-  --secrets-file <path>   Load one private, absolute secrets file for this development
-                          session instead of the adapter-declared secrets file.
-  -h, --help              Show help for dev.
+  --json                  Print one DeployResultV1 on stdout; progress goes to stderr.
+  --as <identity>         Select the Astrale identity for the adapter's provider calls.
+  -h, --help              Show help for deploy.
 
 Behavior:
-  The selected Environment must exist; no other Environment is chosen as a fallback.
-  Builds and verifies the Application, Runtime, frontend, and adapter artifact, then
-  deploys it through the selected Environment. It never starts a local Worker,
-  Vite server, or tunnel. Imported source changes produce serialized remote updates;
-  configuration changes require restarting the command.
-  A shared direct-provider target additionally requires an external single-writer
-  boundary such as a CI/CD concurrency group.
-  The session file is machine-readable and authoritative when requested; human
-  stdout/stderr remains diagnostic. It requires an adapter that reports exact
-  installed Release evidence, so it is rejected for an Environment without an
-  installation and when --deploy-only suppresses installation.
-  A credential file is admitted and read once. Its value is passed only to the
-  deployment adapter, configured Kernel installation, and default View; it never
-  enters Domain Runtime secrets, diagnostics, deployment evidence, or the session
-  file. It is currently unavailable on Windows because private no-reparse file
-  admission is absent.
-  A secrets-file override is read once, passed to the Domain runtime as secrets,
-  never mutates the authored project, and is not watched for later changes. It is
-  also unavailable on Windows because private no-reparse admission is absent.
-
-  Stopping the watcher stops only local build orchestration. The remote deployment
-  and optional Kernel installation remain available.
+  Builds and verifies the Domain and Runtime, rebuilds the Bundle exactly as build
+  does, loads declared secrets, and deploys through the selected adapter. It never
+  installs the Domain: install the URL it prints with
+  ${installCommand()}.
+  The Environment's configuration selects how it deploys. An adapter that implements
+  deployRelease makes one immutable deployment per release and calls no instance: the
+  SDK seals the release for the deployment's URL, records the commit it was built
+  from, and the adapter creates that deployment or reuses it (adapter-astrale on
+  Admin's Services, through astrale call --admin). A new deployment binds the
+  Environment's current secrets; a reused one has its own secrets updated in place,
+  served once propagated; no other deployment's secrets change. Any other Environment
+  replaces its stable target in place (legacy direct mode, deprecated), warns on
+  stderr, serves a v3 Publication only, and warns when the uploaded code has another
+  build digest than the Bundle.
+  With --json, stdout holds only one DeployResultV1: the deployment's URL, which
+  astrale domain install takes, its digests, adapter and state. Exit status: 0 deployed,
+  1 failed or refused, 2 usage error; a failed run prints nothing on stdout.
 `,
-    build: `Build and verify a Domain without deploying it.
+    list: `List the deployments of the Project's Environments, their versions and where they run.
 
 Usage:
-  astrale-domain build
+  astrale-domain list [--environment <name>] [--instance <name>]... [--json]
 
 Options:
-  -h, --help              Show help for build.
+  --environment <name>    List one Environment instead of every Environment.
+  --instance <name>       Ask this instance what it runs, for INSTALLED ON (repeatable).
+  --json                  Print one ListResultV1 on stdout; notices go to stderr.
+  --as <identity>         Select the Astrale identity for the hosts, the registry and the
+                          instances.
+  -h, --help              Show help for list.
 
 Behavior:
-  Compiles the Application and verifies that the conventional or configured Runtime
-  module exports the exact Runtime owned by it. It does not select an Environment,
-  load secrets, deploy, or install the Domain.
+  Asks the adapter of each Environment that deploys immutable deployments for the
+  deployments its host keeps for the caller, and prints each one's release, its version
+  or name, Environment and state, the instances it is installed on, its last call and
+  its expiry, and the URL ${installCommand()} takes.
+  A deployment is named by the registry's version of its release (1.5.0) or of its build
+  (1.5.0 · staging), else from its record's commit, such as 1.4.2 + 7 commits · a1b2c3d ·
+  staging. Names are computed, never stored, and printed whole.
+  INSTALLED ON names each --instance whose Kernel pins the deployment. ? marks what is
+  unknown: no instance was asked, an instance could not tell (such as one whose Kernel
+  does not list installed releases), or its listing shows only what you can read there;
+  stderr says which and why. An unknown instance is never shown as running nothing; —
+  means every instance asked listed all it runs and none runs it.
+  The registry and the instances are read through the Astrale CLI (${MINIMUM_INSTALLATIONS_CLI_VERSION} or
+  newer) with the caller's identity, only once a deployment is listed.
+  A registry that cannot be read fails the listing; an unknown instance never does.
+  A preview expires 30 days after its activation or its last call, whichever is
+  later; a published deployment never does. Last calls are read from the host as it
+  counts them, so a host whose last calls cannot be read is not listed. A platform
+  dispatch namespace reads them from its calls dataset, and without Account Analytics
+  Read lists its deployments without last calls or expiries.
+  Listing changes nothing, at any host, registry or instance.
+  An Environment in legacy direct mode, refused by deploy, or whose adapter lists no
+  deployments is reported on stderr and, with --json, under unlisted. A deployment
+  whose record this SDK does not admit is still listed, from what its host knows.
+  With --json, each deployment carries its installedOn and its call target: the path of
+  its node on Admin's Services, for astrale call "<path>.method.setSecret" --admin, or the
+  namespace and script of a platform dispatch namespace, which its operator tooling
+  takes; installations says what of INSTALLED ON is unknown.
+  Exit status: 0 listed, 1 a host or the registry could not be read (with --json,
+  nothing on stdout), 2 usage error.
 `,
-    deploy: `Build, verify, and deploy a Domain through its configured adapter.
+    diff: `Show the changes since the last published version and the version they require.
+
+Usage:
+  astrale-domain diff [--as <identity>] [--json]
+
+Options:
+  --as <identity>         Select the Astrale identity that reads the Domain registry.
+  --json                  Print one DiffReportV1 on stdout; the summary goes to stderr.
+  -h, --help              Show help for diff.
+
+Behavior:
+  Reads the declared version from package.json and compares the Domain with the
+  highest published stable version up to it, yanked versions included. The level
+  the changes require is a floor: removing or changing a member is major, adding
+  one minor, anything else (code, descriptions) patch; below 1.0.0 a breaking
+  change raises the minor. Callable authorization is outside the floor: raise the
+  version yourself when you narrow it.
+  When package.json still names a published version, as on a feature branch, the
+  report is informational and exits 0. Otherwise the declared version must reach
+  the minimum: a version that is too low exits 1 and names what requires more, as
+  on a release PR, where Release-As: 2.0.0 or a feat!: commit raises the number.
+  Nothing to compare (no published stable version, or a Domain absent from the
+  registry or not readable by the caller) exits 0.
+  Reads the registry through the Astrale CLI (domain versions) with the caller's
+  own credential, and the stored bundle of the compared version only when its
+  Schema differs. Builds the Domain when the Schema is unchanged, to compare build
+  digests. Deploys, publishes and installs nothing.
+  Exit status: 0 accepted, published or nothing to compare; 1 too low or failed
+  (with --json, a failure prints nothing on stdout); 2 usage error.
+`,
+    publish: `Deploy one Environment, verify it, and publish the version package.json declares.
 
 Usage:
-  astrale-domain deploy <environment>
-  astrale-domain deploy --environment <name>
+  astrale-domain publish <environment> [--allow-dirty] [--as <identity>] [--json]
 
 Arguments:
-  environment             Required adapter environment key.
+  environment             Required adapter environment key, usually production.
 
 Options:
-  --environment <name>    Select the environment without a positional argument.
-  --deploy-only           Suppress this run's configured Kernel installation.
-  --as <identity>         Select the Astrale identity for Services and installation calls.
-  -h, --help              Show help for deploy.
+  --allow-dirty           Publish from a working tree with changes, or outside git; the
+                          Publication is marked dirty.
+  --as <identity>         Select the Astrale identity that reads and writes the Domain
+                          registry and deploys.
+  --json                  Print one PublishReportV1 on stdout; progress goes to stderr.
+  -h, --help              Show help for publish.
 
 Behavior:
-  Builds and verifies the Application, Runtime, and provider artifact, loads declared
-  secrets, and invokes the selected adapter. It then verifies the resulting Release.
-  When the Environment declares installation, reconciles it after provider readiness.
-  An Environment without installation performs zero Kernel calls.
+  Names one immutable deployment's release with the version in package.json, in
+  this order, deploying only once the registry allows the version:
+  1. Before any effect: refuses an Environment that does not deploy immutable
+     deployments, a working tree with changes or no git commit (unless
+     --allow-dirty), and warns when no remote branch holds the commit; then builds,
+     freezes the configuration, places the deployment and seals its release.
+  2. Reads the version from package.json and the registry through the Astrale CLI.
+     A version already published with this release succeeds without effect; with
+     another release it is refused: a published version never changes.
+  3. Compares with the highest stable version below it, yanked versions included,
+     as diff does, and refuses a version that is too low.
+  4. Deploys the release, or reuses its deployment, as deploy does.
+  5. Verifies that the deployment serves the sealed release, within 60 seconds.
+  6. Asks Admin for the Publication, which Admin creates under the Domain's lock. A
+     version published meanwhile with another release is refused, and this
+     deployment stays a preview. On a platform dispatch namespace the published
+     deployment is then kept from expiry; Admin keeps those of its Services itself.
+  A failure leaves at most a deployment without a version, and says whether a rerun
+  can help: when it can, rerun publish, which reuses it; a refusal Admin repeats
+  (a missing domain_admin right, a release it will not name) names its cause.
+  Admin unavailable or the Domain absent from the registry: nothing is deployed.
+  It never installs the Domain: install the URL it prints with
+  ${installCommand()}.
+  Exit status: 0 published or already published; 1 refused or failed (with --json,
+  a failure prints nothing on stdout); 2 usage error.
 `,
     test: `Run Project tests locally or against one selected Environment.
 
@@ -160,6 +255,28 @@ Options:
   --fix                   Apply supported fixes.
   --format <format>       Select stylish or json output (default: stylish).
   -h, --help              Show help for lint.
+`,
+    yank: `Take one published version of the Domain out of resolution, or put it back.
+
+Usage:
+  astrale-domain yank <version> [--undo] [--json]
+
+Arguments:
+  version                 One published version of this Project's Domain, e.g. 1.5.0.
+
+Options:
+  --undo                  Let line references choose the version again.
+  --json                  Print one YankReportV1 on stdout.
+  -h, --help              Show help for yank.
+
+Behavior:
+  Changes the version in the Admin registry through the Astrale CLI, with its configured
+  Admin target and identity; yanking requires administering the Domain. A line reference
+  such as @1.5 never chooses a yanked version, and an exact reference installs it with a
+  warning. Installations keep running and the deployment keeps serving: yanking only
+  changes resolution. A version already in the requested state answers unchanged, so a
+  rerun is safe. Exit status: 0 done, 1 refused or failed, 2 usage error; a refused or
+  failed run prints nothing on stdout.
 `,
     package: `Prepare public TypeScript declarations for package publication.
 

package/dist/tooling/cli/immutable-deployment.d.ts

@@ -0,0 +1,83 @@
+import type { DeploymentCommitV1, FrozenConfigurationV1 } from '../../deployment/address/index.js';
+import type { Adapter, Build, Bundle, LegacyAdapter, Placement, Release, ResolvedRuntimeReference } from '../../deployment/index.js';
+import type { DeployResultV1 } from './deploy-result.js';
+/**
+ * Everything the deploy of one canonical Environment derives before its only effectful call: the
+ * Bundle, the Environment's current secrets, the frozen configuration, where the host places the
+ * deployment, its label, the sealed release it serves and the commit it is built from. Planning has
+ * no effect at the host: `placement` only reads, and nothing is created, reused or written.
+ */
+export interface ImmutableDeploymentPlan {
+    readonly projectDir: string;
+    readonly environment: string;
+    readonly adapter: Adapter<object>;
+    readonly parameters: object;
+    readonly identity?: string;
+    readonly bundle: Bundle;
+    readonly secrets: Readonly<Record<string, string>>;
+    readonly configuration: FrozenConfigurationV1;
+    readonly placement: Placement;
+    /** `<line>-<content>`: the deployment's DNS label and provider script. */
+    readonly label: string;
+    /** The `DomainRelease` v4 the deployment serves at its URL, `release.url`. */
+    readonly release: Release;
+    /** The commit this deploy runs from, which a deployment it creates declares. */
+    readonly commit: DeploymentCommitV1 | null;
+}
+/**
+ * Plan the immutable deployment of one canonical Environment (CT33), without any effect.
+ *
+ * The SDK bundles exactly as `astrale-domain build` does, asks the adapter to freeze the
+ * Environment's configuration and say where its host places deployments, derives the deployment
+ * label and URL from them (S3), seals the `DomainRelease` v4 the deployment serves at that URL
+ * (S4a), and reads the commit it is built from. `deploy` deploys the plan at once; `publish`
+ * checks the registry against the sealed release first, and deploys only when it may name it.
+ */
+export declare function planImmutableDeployment(input: {
+    readonly projectDir: string;
+    readonly environment: string;
+    /** A canonical Environment's adapter (CT33), which implements adapter interface v2. */
+    readonly adapter: Adapter<object> | LegacyAdapter<object>;
+    readonly parameters: object;
+    readonly build: Build;
+    readonly runtime: ResolvedRuntimeReference;
+    readonly identity?: string;
+    /** The commit provenance the caller already read (`publish` checks it first); read otherwise. */
+    readonly commit?: DeploymentCommitV1 | null;
+    readonly signal: AbortSignal;
+}): Promise<ImmutableDeploymentPlan>;
+/**
+ * The commit the Project's runtime module is built from, as a deployment declares it (CT18
+ * `commit`): its sha, whether the tree holds changes it does not, and the last release tag before
+ * it. `null` outside git.
+ */
+export declare function runtimeCommit(projectDir: string, runtime: ResolvedRuntimeReference, signal: AbortSignal): Promise<DeploymentCommitV1 | null>;
+/**
+ * Create, or reuse, the immutable deployment a plan describes: the adapter's `deployRelease` is
+ * its only effectful call. The SDK makes no Kernel call, the deploy calls no instance and installs
+ * nothing: `astrale domain install <url>` installs the URL it prints.
+ *
+ * Returns the deploy result, or nothing once a failure is reported on stderr.
+ */
+export declare function deployPlannedRelease(plan: ImmutableDeploymentPlan, input: {
+    readonly signal: AbortSignal;
+    readonly report: (line: string) => void;
+}): Promise<DeployResultV1 | undefined>;
+/**
+ * Deploy one canonical Environment (CT33) as the immutable deployment of one sealed release: plan
+ * it without effect, then make the adapter's one effectful call.
+ *
+ * Returns the deploy result, or nothing once a failure is reported on stderr.
+ */
+export declare function deployImmutable(input: {
+    readonly projectDir: string;
+    readonly environment: string;
+    /** A canonical Environment's adapter (CT33), which implements adapter interface v2. */
+    readonly adapter: Adapter<object> | LegacyAdapter<object>;
+    readonly parameters: object;
+    readonly build: Build;
+    readonly runtime: ResolvedRuntimeReference;
+    readonly identity?: string;
+    readonly signal: AbortSignal;
+    readonly report: (line: string) => void;
+}): Promise<DeployResultV1 | undefined>;

package/dist/tooling/cli/immutable-deployment.js

@@ -0,0 +1,135 @@
+import { resolve } from 'node:path';
+import { deploymentContent, deploymentLabel, deploymentLine, deploymentUrl, } from '../../deployment/address/index.js';
+import { assemble } from '../../deployment/index.js';
+import { bundleBuild } from './build.js';
+import { deploymentCommit } from './commit.js';
+import { deployResult } from './deploy-result.js';
+import { error } from './log.js';
+import { environmentSecrets } from './secrets.js';
+/**
+ * Plan the immutable deployment of one canonical Environment (CT33), without any effect.
+ *
+ * The SDK bundles exactly as `astrale-domain build` does, asks the adapter to freeze the
+ * Environment's configuration and say where its host places deployments, derives the deployment
+ * label and URL from them (S3), seals the `DomainRelease` v4 the deployment serves at that URL
+ * (S4a), and reads the commit it is built from. `deploy` deploys the plan at once; `publish`
+ * checks the registry against the sealed release first, and deploys only when it may name it.
+ */
+export async function planImmutableDeployment(input) {
+    const { parameters, environment, build, signal } = input;
+    const adapter = releaseAdapter(input.adapter);
+    const identity = input.identity === undefined ? {} : { identity: input.identity };
+    const bundle = await bundleBuild({
+        bundler: adapter.bundler,
+        projectDir: input.projectDir,
+        build,
+        runtime: input.runtime,
+        signal,
+    });
+    const secrets = environmentSecrets(adapter, parameters, input.projectDir, input.runtime.runtime);
+    const configuration = adapter.configure(parameters, {
+        environment,
+        secrets: Object.freeze(Object.keys(secrets).sort()),
+    });
+    const placement = await adapter.placement(parameters, { environment, signal, ...identity });
+    const origin = build.schema.compiled.root.origin;
+    const label = deploymentLabel(deploymentLine({ origin, environment, addressing: placement.addressing }), deploymentContent(bundle.digest, configuration));
+    const release = assemble(build, bundle.digest, deploymentUrl(label, placement.routingDomain));
+    const commit = input.commit !== undefined
+        ? input.commit
+        : await runtimeCommit(input.projectDir, input.runtime, signal);
+    return Object.freeze({
+        projectDir: input.projectDir,
+        environment,
+        adapter,
+        parameters,
+        ...identity,
+        bundle,
+        secrets,
+        configuration,
+        placement,
+        label,
+        release,
+        commit,
+    });
+}
+/**
+ * The commit the Project's runtime module is built from, as a deployment declares it (CT18
+ * `commit`): its sha, whether the tree holds changes it does not, and the last release tag before
+ * it. `null` outside git.
+ */
+export function runtimeCommit(projectDir, runtime, signal) {
+    return deploymentCommit({
+        projectDir,
+        // The configuration sits in the Project directory, and names its runtime relative to it.
+        runtimeModule: resolve(projectDir, runtime.reference.path),
+        signal,
+    });
+}
+/**
+ * Create, or reuse, the immutable deployment a plan describes: the adapter's `deployRelease` is
+ * its only effectful call. The SDK makes no Kernel call, the deploy calls no instance and installs
+ * nothing: `astrale domain install <url>` installs the URL it prints.
+ *
+ * Returns the deploy result, or nothing once a failure is reported on stderr.
+ */
+export async function deployPlannedRelease(plan, input) {
+    const { adapter, environment, label, release } = plan;
+    const deployed = await adapter.deployRelease(plan.parameters, {
+        projectDir: plan.projectDir,
+        environment,
+        ...(plan.identity === undefined ? {} : { identity: plan.identity }),
+        secrets: plan.secrets,
+        bundle: plan.bundle,
+        configuration: plan.configuration,
+        placement: plan.placement,
+        label,
+        release,
+        commit: plan.commit,
+        signal: input.signal,
+    });
+    if (deployed.status !== 'ready') {
+        error(`Deployment failed during ${deployed.phase}: ${deployed.error.message}`);
+        return undefined;
+    }
+    const result = deployResult({ environment, adapter, release, deployment: deployed });
+    input.report(`Domain: ${result.origin}`);
+    input.report(`Environment: ${environment}`);
+    input.report(`Adapter: ${result.deployment.adapter}`);
+    input.report(`Deployment: ${label} · ${result.deployment.state}`);
+    input.report(`URL: ${result.url}`);
+    input.report(`Release: ${release.document.digest}`);
+    input.report(`Build: ${release.buildDigest}`);
+    input.report(secretsLine(label, result.secrets.state));
+    input.report('Ready: deployment verified');
+    return result;
+}
+/**
+ * Deploy one canonical Environment (CT33) as the immutable deployment of one sealed release: plan
+ * it without effect, then make the adapter's one effectful call.
+ *
+ * Returns the deploy result, or nothing once a failure is reported on stderr.
+ */
+export async function deployImmutable(input) {
+    const plan = await planImmutableDeployment(input);
+    return deployPlannedRelease(plan, { signal: input.signal, report: input.report });
+}
+/**
+ * What the deploy did to the secrets of the one deployment it made or reused: `bound` to the new
+ * deployment, or `updated` or left `unchanged` in place on the reused one. No other deployment's
+ * secrets are ever written. A value rewritten in place is served once the host propagated it,
+ * which is eventually consistent (about 4 s on Workers for Platforms, AM-114).
+ */
+function secretsLine(label, state) {
+    return state === 'updated'
+        ? `Secrets: updated in place on ${label}; the new values are served once propagated ` +
+            '(eventually consistent, about 4 s)'
+        : `Secrets: ${state}`;
+}
+/** The adapter of a canonical Environment: CT33 selects canonical only beside `deployRelease`. */
+function releaseAdapter(adapter) {
+    if (!('deployRelease' in adapter) || typeof adapter.deployRelease !== 'function') {
+        throw new TypeError(`Adapter ${adapter.name}@${adapter.version} implements no deployRelease and deploys no immutable deployment.`);
+    }
+    return adapter;
+}

package/dist/tooling/cli/index.d.ts

@@ -1,7 +1,7 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (dev | build | deploy | test | lint | package), explicit dotenv boundary, and admitted
- * development-session file representation.
+ * (build | deploy | diff | list | publish | test | lint | package | upgrade | yank), its JSON results,
+ * the deploy mode each command selects for an Environment (CT33), and the explicit dotenv boundary.
  *
  * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
  * Bun (it imports the project's `astrale.config.ts` directly). This subpath is
@@ -11,6 +11,12 @@
  * The bin lives at `./bin`.
  */
 export { run } from './run.js';
+export type { BuildResultV1 } from './build.js';
+export type { DeployResultV1, DeploymentSecretsState } from './deploy-result.js';
+export type { DiffChangeV1, DiffReportV1 } from './diff/index.js';
+export type { InstallationSourcesV1, InstallationUnknownReason, InstalledOnV1, InstanceSourceV1, ListedDeploymentV1, ListResultV1, UnlistedEnvironmentV1, } from './list.js';
+export type { PublishReportV1 } from './publish/index.js';
+export type { YankReportV1 } from './yank.js';
+export { selectDeployMode } from './deploy-mode.js';
+export type { CloudflareDirectParameter, DeployMode, DeployModeCommand, DeployRefusal, LegacyDirectReason, } from './deploy-mode.js';
 export { loadDeclaredSecrets } from './dotenv.js';
-export { DEVELOPMENT_SESSION_FILE_VERSION, acceptDevelopmentSessionFileV1, } from './development/session-file.js';
-export type { DevelopmentSessionFileV1, DevelopmentSessionPhaseV1, DevelopmentSessionProjectV1, DevelopmentSessionReleaseV1, } from './development/session-file.js';

package/dist/tooling/cli/index.js

@@ -1,7 +1,7 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (dev | build | deploy | test | lint | package), explicit dotenv boundary, and admitted
- * development-session file representation.
+ * (build | deploy | diff | list | publish | test | lint | package | upgrade | yank), its JSON results,
+ * the deploy mode each command selects for an Environment (CT33), and the explicit dotenv boundary.
  *
  * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
  * Bun (it imports the project's `astrale.config.ts` directly). This subpath is
@@ -11,5 +11,7 @@
  * The bin lives at `./bin`.
  */
 export { run } from './run.js';
+// The domain-publish Action asks the selection `publish` makes before it runs it, to skip an
+// Environment that is not canonical with a notice instead of failing on its refusal.
+export { selectDeployMode } from './deploy-mode.js';
 export { loadDeclaredSecrets } from './dotenv.js';
-export { DEVELOPMENT_SESSION_FILE_VERSION, acceptDevelopmentSessionFileV1, } from './development/session-file.js';