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

package/dist/tooling/cli/build.js

@@ -0,0 +1,77 @@
+import { verifyBundle } from '../../deployment/index.js';
+/**
+ * The distinct bundlers of a Project's Environments, in declaration order. Environments whose
+ * adapters declare one bundler object share its build. Two copies of one bundler (two installed
+ * versions of its package) are two bundlers even under one id and version, since their code can
+ * differ.
+ */
+export function projectBundlers(project) {
+    const bundlers = new Map();
+    for (const [name, environment] of Object.entries(project.environments)) {
+        const adapter = environment.deployment.adapter;
+        const environments = bundlers.get(adapter.bundler) ?? [];
+        environments.push(Object.freeze({ name, adapter: `${adapter.name}@${adapter.version}` }));
+        bundlers.set(adapter.bundler, environments);
+    }
+    return Object.freeze([...bundlers].map(([bundler, environments]) => Object.freeze({ bundler, environments: Object.freeze(environments) })));
+}
+/** Bundle one Build without any Environment and identify the bytes by their build digest. */
+export async function bundleBuild(input) {
+    const source = await input.bundler.bundle({
+        projectDir: input.projectDir,
+        build: input.build,
+        runtime: input.runtime,
+        signal: input.signal,
+    });
+    return verifyBundle({
+        build: input.build,
+        runtime: input.runtime,
+        bundler: input.bundler,
+        source,
+    });
+}
+/**
+ * One entry per distinct build: copies of one bundler that produced the same bytes give one entry,
+ * copies that produced different bytes give one entry each.
+ */
+export function buildResult(build, bundles) {
+    const builds = new Map();
+    for (const bundle of bundles) {
+        const { id, version } = bundle.manifest.bundler;
+        const key = JSON.stringify([id, version, bundle.digest]);
+        if (builds.has(key))
+            continue;
+        builds.set(key, Object.freeze({ bundler: Object.freeze({ id, version }), digest: bundle.digest }));
+    }
+    return Object.freeze({
+        format: 'astrale.build-result',
+        version: 1,
+        origin: build.schema.compiled.root.origin,
+        schema: Object.freeze({ revision: build.schema.compiled.root.revision }),
+        builds: Object.freeze([...builds.values()]),
+    });
+}
+/**
+ * A warning for every bundler id and version whose copies produced different bytes: each copy's
+ * Environments deploy their own build, so the Project has more than one build for that bundler.
+ */
+export function bundlerCopyWarnings(built) {
+    const byBundler = new Map();
+    for (const { source, bundle } of built) {
+        const { id, version } = bundle.manifest.bundler;
+        const name = `${id}@${version}`;
+        const digests = byBundler.get(name) ?? new Map();
+        const environments = digests.get(bundle.digest) ?? [];
+        environments.push(...source.environments.map((environment) => `${environment.name}: ${environment.adapter}`));
+        digests.set(bundle.digest, environments);
+        byBundler.set(name, digests);
+    }
+    return Object.freeze([...byBundler]
+        .filter(([, digests]) => digests.size > 1)
+        .map(([name, digests]) => `Bundler ${name} gives ${digests.size} build digests for this tree: ` +
+        [...digests]
+            .map(([digest, environments]) => `${digest} (${environments.join(', ')})`)
+            .join('; ') +
+        '. These adapters load different copies of the bundler; align their versions ' +
+        '(`astrale-domain upgrade`) so that it gives one build.'));
+}

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

@@ -10,6 +10,5 @@ export type BunOutcome = {
 };
 /** Re-enter the published executable under Bun only when authored TypeScript must be imported. */
 export declare function runWithBun(executable: string, argv: readonly string[]): Promise<BunOutcome>;
-export declare function isolateDevelopmentProcessGroup(argv: readonly string[], platform?: NodeJS.Platform): boolean;
 /** Prefer the generated project's exact Bun package binary over an ambient executable or shim. */
 export declare function resolveBunExecutable(cwd: string): string;

package/dist/tooling/cli/bun.js

@@ -14,10 +14,6 @@ export function runWithBun(executable, argv) {
     return new Promise((resolve, reject) => {
         const child = spawn(resolveBunExecutable(process.cwd()), [executable, ...argv], {
             stdio: 'inherit',
-            // Keep a long-lived development runtime outside the launcher's terminal
-            // process group. The launcher receives Ctrl-C, forwards it exactly once,
-            // and remains alive until Bun finishes provider and Kernel cleanup.
-            detached: isolateDevelopmentProcessGroup(argv),
         });
         const handlers = FORWARDED_SIGNALS.map((signal) => [signal, () => child.kill(signal)]);
         for (const [signal, handler] of handlers)
@@ -44,9 +40,6 @@ export function runWithBun(executable, argv) {
         });
     });
 }
-export function isolateDevelopmentProcessGroup(argv, platform = process.platform) {
-    return platform !== 'win32' && argv[0] === 'dev';
-}
 /** Prefer the generated project's exact Bun package binary over an ambient executable or shim. */
 export function resolveBunExecutable(cwd) {
     const projectRequire = createRequire(join(cwd, 'package.json'));

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

@@ -0,0 +1,35 @@
+import type { DeploymentCommitV1 } from '../../deployment/address/index.js';
+/**
+ * The commit provenance a canonical deploy declares in its deployment record (CT18 `commit`): the
+ * commit of the repository the Project lives in, whether the working tree holds changes that
+ * commit does not, and the last release of the Domain before it, as `git describe` finds it.
+ *
+ * - `dirty` covers tracked changes and untracked files, over the whole working tree; ignored files
+ *   never count. Unlike `git describe --dirty`, an untracked file counts, since a build can import
+ *   it.
+ * - `base` is the nearest release tag of the package the Domain is released from: the
+ *   release-please package that holds the Domain's runtime module (see {@link releaseTagPrefixes}).
+ *   The tag prefix is stripped, and a tag whose rest is not a canonical SemVer version is left
+ *   out, so the record never carries a base a deployment name would refuse (AM-57). A Domain no
+ *   release line holds declares no base: it is never given another package's version.
+ * - Outside a git repository, without git, or in a repository whose commits are not SHA-1, the
+ *   deploy declares no commit (`null`); a deploy never fails for want of provenance.
+ */
+export declare function deploymentCommit(input: {
+    readonly projectDir: string;
+    /** The Domain's runtime module, as the Project's `entrypoints.runtime` resolves it. */
+    readonly runtimeModule: string;
+    readonly signal: AbortSignal;
+}): Promise<DeploymentCommitV1 | null>;
+/**
+ * Whether a remote-tracking branch of the repository already holds a commit. A Publication records
+ * the commit it was built from, and release-please computes the next number from the pushed
+ * history: publishing a commit nobody pushed risks the same number being computed again (tech
+ * Versioning [.73872]). Nothing when git cannot tell. Reads the local remote-tracking refs only,
+ * never the network.
+ */
+export declare function commitPushed(input: {
+    readonly projectDir: string;
+    readonly sha: string;
+    readonly signal: AbortSignal;
+}): Promise<boolean | undefined>;

package/dist/tooling/cli/commit.js

@@ -0,0 +1,235 @@
+import { execFile } from 'node:child_process';
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { isVersion } from '../../platform/versioning/version.js';
+/** A commit as `DeploymentCommitV1` holds it: the full SHA-1 git prints, in lower case. */
+const SHA = /^[0-9a-f]{40}$/u;
+/** `git describe --long` output: `<tag>-<commits since the tag>-g<abbreviated commit>`. */
+const DESCRIBED = /^(?<tag>.+)-(?<distance>\d+)-g[0-9a-f]+$/u;
+/** A tag prefix this module can hand to `git describe --match` without escaping a glob. */
+const LITERAL_PREFIX = /^[^*?[\]\\\s]*$/u;
+/** The configuration files release-please reads at a repository root, the dotted name first. */
+const RELEASE_PLEASE_CONFIGS = ['.release-please-config.json', 'release-please-config.json'];
+const GIT_TIMEOUT_MS = 30_000;
+/**
+ * The commit provenance a canonical deploy declares in its deployment record (CT18 `commit`): the
+ * commit of the repository the Project lives in, whether the working tree holds changes that
+ * commit does not, and the last release of the Domain before it, as `git describe` finds it.
+ *
+ * - `dirty` covers tracked changes and untracked files, over the whole working tree; ignored files
+ *   never count. Unlike `git describe --dirty`, an untracked file counts, since a build can import
+ *   it.
+ * - `base` is the nearest release tag of the package the Domain is released from: the
+ *   release-please package that holds the Domain's runtime module (see {@link releaseTagPrefixes}).
+ *   The tag prefix is stripped, and a tag whose rest is not a canonical SemVer version is left
+ *   out, so the record never carries a base a deployment name would refuse (AM-57). A Domain no
+ *   release line holds declares no base: it is never given another package's version.
+ * - Outside a git repository, without git, or in a repository whose commits are not SHA-1, the
+ *   deploy declares no commit (`null`); a deploy never fails for want of provenance.
+ */
+export async function deploymentCommit(input) {
+    const head = await git(input.projectDir, input.signal, ['rev-parse', '--verify', 'HEAD']);
+    if (head === undefined || !SHA.test(head))
+        return null;
+    const status = await git(input.projectDir, input.signal, [
+        'status',
+        '--porcelain',
+        '--untracked-files=normal',
+    ]);
+    if (status === undefined)
+        return null;
+    const prefixes = await releaseTagPrefixes(input);
+    const base = prefixes === undefined ? undefined : await describedBase(input, prefixes);
+    return Object.freeze({
+        sha: head,
+        dirty: status.length > 0,
+        ...(base === undefined ? {} : { base }),
+    });
+}
+/**
+ * Whether a remote-tracking branch of the repository already holds a commit. A Publication records
+ * the commit it was built from, and release-please computes the next number from the pushed
+ * history: publishing a commit nobody pushed risks the same number being computed again (tech
+ * Versioning [.73872]). Nothing when git cannot tell. Reads the local remote-tracking refs only,
+ * never the network.
+ */
+export async function commitPushed(input) {
+    if (!SHA.test(input.sha))
+        return undefined;
+    const branches = await git(input.projectDir, input.signal, [
+        'branch',
+        '--remotes',
+        '--contains',
+        input.sha,
+        '--format=%(refname)',
+    ]);
+    return branches === undefined ? undefined : branches.length > 0;
+}
+/**
+ * The prefixes of the release tags of the package the Domain is released from, or nothing when
+ * no release line holds the Domain.
+ *
+ * In a repository with a release-please configuration at its root, that package is the configured
+ * package whose path is the nearest one holding the runtime module's directory, unless one of its
+ * `exclude-paths` holds it. Its tags are named as release-please names them: `<component>`, its
+ * `tag-separator` (`-`) and `v` before the version, without the component when
+ * `include-component-in-tag` is false and without the `v` when `include-v-in-tag` is false; the
+ * component is the package's `component`, else its unscoped `package-name`, else the unscoped name
+ * in its `package.json`. Root-level options are the packages' defaults, as in release-please.
+ *
+ * Without a configuration, the tags are those `npm version` writes (`v<version>`) and
+ * `<name>-v<version>`, where the name is the unscoped one in the Project's `package.json`.
+ */
+async function releaseTagPrefixes(input) {
+    const root = await git(input.projectDir, input.signal, ['rev-parse', '--show-toplevel']);
+    if (root === undefined)
+        return undefined;
+    const config = await releasePleaseConfig(root);
+    if (config === undefined) {
+        const name = unscoped(await packageName(input.projectDir));
+        return literal(['v', ...(name === undefined ? [] : [`${name}-v`])]);
+    }
+    // Git names the module's directory relative to its repository, symbolic links resolved.
+    const located = await git(dirname(input.runtimeModule), input.signal, [
+        'rev-parse',
+        '--show-toplevel',
+        '--show-prefix',
+    ]);
+    const [moduleRoot, prefix = ''] = located?.split('\n') ?? [];
+    if (moduleRoot !== root)
+        return undefined;
+    const path = prefix.replace(/\/$/u, '');
+    const found = releasePackage(config, path);
+    if (found === undefined)
+        return undefined;
+    const option = (key) => found.options[key] ?? config[key];
+    const v = option('include-v-in-tag') === false ? '' : 'v';
+    if (option('include-component-in-tag') === false)
+        return literal([v]);
+    const separator = option('tag-separator') ?? '-';
+    const component = option('component') ??
+        unscoped(option('package-name')) ??
+        unscoped(await packageName(join(root, found.path)));
+    if (typeof component !== 'string' || component.length === 0 || typeof separator !== 'string') {
+        return undefined;
+    }
+    return literal([`${component}${separator}${v}`]);
+}
+/**
+ * The configured package that holds `path` (relative to the repository root, `''` for the root),
+ * the nearest one first, or nothing when none holds it or its `exclude-paths` do.
+ */
+function releasePackage(config, path) {
+    const packages = config.packages;
+    if (packages === null || typeof packages !== 'object' || Array.isArray(packages))
+        return undefined;
+    let found;
+    for (const [key, options] of Object.entries(packages)) {
+        if (options === null || typeof options !== 'object' || Array.isArray(options))
+            continue;
+        const packagePath = key === '.' ? '' : key.replace(/^\.\//u, '').replace(/\/$/u, '');
+        if (!holds(packagePath, path))
+            continue;
+        if (found === undefined || packagePath.length > found.path.length) {
+            found = { path: packagePath, options: options };
+        }
+    }
+    if (found === undefined)
+        return undefined;
+    const excluded = found.options['exclude-paths'] ?? config['exclude-paths'];
+    if (Array.isArray(excluded)) {
+        for (const exclusion of excluded) {
+            if (typeof exclusion !== 'string')
+                continue;
+            const relative = exclusion.replace(/^\.\//u, '').replace(/\/$/u, '');
+            if (holds(found.path === '' ? relative : `${found.path}/${relative}`, path))
+                return undefined;
+        }
+    }
+    return found;
+}
+/** Whether the directory `outer` holds `inner`, both relative to the repository root. */
+function holds(outer, inner) {
+    return outer === '' || inner === outer || inner.startsWith(`${outer}/`);
+}
+/** The canonical version and distance of the nearest tag with one of these prefixes, or nothing. */
+async function describedBase(input, prefixes) {
+    const described = await git(input.projectDir, input.signal, [
+        'describe',
+        '--tags',
+        '--long',
+        '--abbrev=40',
+        ...prefixes.flatMap((prefix) => ['--match', `${prefix}[0-9]*`]),
+        'HEAD',
+    ]);
+    const match = described === undefined ? null : DESCRIBED.exec(described);
+    if (match?.groups === undefined)
+        return undefined;
+    const tag = match.groups.tag;
+    const distance = Number(match.groups.distance);
+    const version = prefixes
+        .filter((prefix) => tag.startsWith(prefix))
+        .map((prefix) => tag.slice(prefix.length))
+        .find((rest) => isVersion(rest));
+    if (version === undefined || !Number.isSafeInteger(distance))
+        return undefined;
+    return Object.freeze({ version, distance });
+}
+/** The repository's release-please configuration, if its root has one that is a JSON object. */
+async function releasePleaseConfig(root) {
+    for (const name of RELEASE_PLEASE_CONFIGS) {
+        const config = await readJson(join(root, name));
+        if (config !== undefined)
+            return config;
+    }
+    return undefined;
+}
+/** The `name` of the `package.json` in a directory, if it has one. */
+async function packageName(directory) {
+    return (await readJson(join(directory, 'package.json')))?.name;
+}
+/** A package name without its npm scope, as release-please makes a component of it. */
+function unscoped(name) {
+    if (typeof name !== 'string' || name.length === 0)
+        return undefined;
+    return name.startsWith('@') ? name.slice(name.indexOf('/') + 1) || undefined : name;
+}
+/** The prefixes, unless one would be read as a glob by `git describe --match`. */
+function literal(prefixes) {
+    return prefixes.every((prefix) => LITERAL_PREFIX.test(prefix)) ? prefixes : undefined;
+}
+async function readJson(path) {
+    let value;
+    try {
+        value = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Run one read-only git command in a directory and return its trimmed stdout, or nothing when git
+ * is missing or the command fails. An interrupted deploy still stops here.
+ */
+function git(cwd, signal, args) {
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        execFile('git', [...args], {
+            cwd,
+            // Never take the index lock: a deploy only reads the repository.
+            env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' },
+            signal,
+            timeout: GIT_TIMEOUT_MS,
+            windowsHide: true,
+        }, (error, stdout) => {
+            if (signal.aborted) {
+                reject(signal.reason);
+                return;
+            }
+            resolve(error === null ? stdout.trim() : undefined);
+        });
+    });
+}

package/dist/tooling/cli/deploy-mode.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The deploy mode of one Environment for one command (CT33), chosen by the configuration itself:
+ * an unchanged configuration keeps its mode, and so its behaviour, across an SDK upgrade, as long as
+ * that mode still has a consumer (AM-16, AM-72).
+ *
+ * - `canonical`: an immutable deployment of one sealed release through the adapter's
+ *   `deployRelease`, with a key generated for it, and no call to any instance.
+ * - `legacy-direct`: today's stable target, replaced in place through `prepare` and `deploy`, which
+ *   serves a v3 Publication only. Its `reasons` name what selected it.
+ * - `refused`: a shape no deploy of this SDK serves, refused before any effect. Each refusal
+ *   carries the configuration or command to write instead.
+ *
+ * A deploy never installs, so two shapes are refused before a mode is selected at all: an
+ * Environment that declares `installation` by `defineProject`, and `--deploy-only` by the
+ * command-line parser (AM-72).
+ */
+export type DeployMode = {
+    readonly kind: 'canonical';
+} | {
+    readonly kind: 'legacy-direct';
+    readonly reasons: readonly LegacyDirectReason[];
+} | {
+    readonly kind: 'refused';
+    readonly refusals: readonly DeployRefusal[];
+};
+/** What puts an Environment on the legacy direct-mode path. */
+export type LegacyDirectReason = 
+/** An adapter-cloudflare parameter of direct mode. */
+{
+    readonly reason: 'direct-parameter';
+    readonly parameter: CloudflareDirectParameter;
+}
+/** adapter-cloudflare without a dispatch `namespace`: direct mode is its default. */
+ | {
+    readonly reason: 'no-namespace';
+}
+/** An adapter that declares no `deployRelease`: the contract before adapter interface v2. */
+ | {
+    readonly reason: 'no-deploy-release';
+};
+export type CloudflareDirectParameter = 'route' | 'workerName' | 'identityIssuer' | 'addressing' | 'signingIdentity';
+export interface DeployRefusal {
+    readonly reason: 'astrale-instance' | 'astrale-signing-identity' | 'mixed-parameters' | 'scheduled-triggers' | 'publish-legacy-direct';
+    /** The configuration or command to write instead, for the author. */
+    readonly guidance: string;
+}
+/**
+ * The commands that select a deploy mode. `publish` names only an immutable deployment, so it
+ * refuses every Environment that is not canonical (CT33, R-G03).
+ */
+export type DeployModeCommand = 'deploy' | 'publish';
+/**
+ * Select the deploy mode of one Environment (CT33). It reads the configuration and the command
+ * only, and has no effect.
+ *
+ * A refusal wins over every other reason. adapter-astrale deploys immutable deployments only
+ * (`deployRelease`): its removed instance mode's `instance` and `signingIdentity` are refused
+ * before any effect, since their one consumer pins an older SDK (AM-72). Otherwise the Environment
+ * is on the legacy direct-mode path when adapter-cloudflare names a direct-mode parameter or no
+ * `namespace`, or when its adapter declares no `deployRelease`. Everything else is canonical,
+ * and `publish` refuses the legacy direct-mode path: a stable target serves no release, so no
+ * version can name it.
+ *
+ * Within canonical adapter-cloudflare (with `namespace`), a direct-mode parameter is refused
+ * rather than silently selecting either mode, and so is `wrangler.triggers`: an immutable
+ * deployment runs no cron of its own (D13). The bundling-affecting `wrangler` keys are refused by
+ * adapter-cloudflare itself for every Environment (AM-51).
+ */
+export declare function selectDeployMode(input: {
+    readonly command: DeployModeCommand;
+    readonly environment: string;
+    /** The Environment's definition, of which selection reads only the adapter and its parameters. */
+    readonly definition: {
+        readonly deployment: {
+            readonly adapter: {
+                readonly name: string;
+                readonly deployRelease?: unknown;
+            };
+            readonly parameters: object;
+        };
+    };
+}): DeployMode;

package/dist/tooling/cli/deploy-mode.js

@@ -0,0 +1,135 @@
+import { installCommand } from '../../project/install-command.js';
+/** The adapter names of the first-party adapters whose parameters CT33 classifies. */
+const CLOUDFLARE = 'cloudflare';
+const ASTRALE = 'astrale';
+/** The parameters that named the stable Service of adapter-astrale's removed instance mode. */
+const ASTRALE_SERVICE_PARAMETERS = ['serviceKey', 'name'];
+const CLOUDFLARE_DIRECT_PARAMETERS = [
+    'route',
+    'workerName',
+    'identityIssuer',
+    'addressing',
+    'signingIdentity',
+];
+/**
+ * Select the deploy mode of one Environment (CT33). It reads the configuration and the command
+ * only, and has no effect.
+ *
+ * A refusal wins over every other reason. adapter-astrale deploys immutable deployments only
+ * (`deployRelease`): its removed instance mode's `instance` and `signingIdentity` are refused
+ * before any effect, since their one consumer pins an older SDK (AM-72). Otherwise the Environment
+ * is on the legacy direct-mode path when adapter-cloudflare names a direct-mode parameter or no
+ * `namespace`, or when its adapter declares no `deployRelease`. Everything else is canonical,
+ * and `publish` refuses the legacy direct-mode path: a stable target serves no release, so no
+ * version can name it.
+ *
+ * Within canonical adapter-cloudflare (with `namespace`), a direct-mode parameter is refused
+ * rather than silently selecting either mode, and so is `wrangler.triggers`: an immutable
+ * deployment runs no cron of its own (D13). The bundling-affecting `wrangler` keys are refused by
+ * adapter-cloudflare itself for every Environment (AM-51).
+ */
+export function selectDeployMode(input) {
+    const { command, environment, definition } = input;
+    const { adapter } = definition.deployment;
+    const parameters = definition.deployment.parameters;
+    const refusals = [];
+    const reasons = [];
+    const releases = 'deployRelease' in adapter && typeof adapter.deployRelease === 'function';
+    if (adapter.name === ASTRALE && releases) {
+        if (declares(parameters, 'instance')) {
+            refusals.push({
+                reason: 'astrale-instance',
+                guidance: astraleInstanceGuidance(parameters, environment),
+            });
+        }
+        if (declares(parameters, 'signingIdentity')) {
+            refusals.push({
+                reason: 'astrale-signing-identity',
+                guidance: 'astrale({ signingIdentity }) is no longer accepted: each deployment gets a signing key ' +
+                    'generated when it is deployed. Remove `signingIdentity`.',
+            });
+        }
+    }
+    if (adapter.name === CLOUDFLARE) {
+        const direct = CLOUDFLARE_DIRECT_PARAMETERS.filter((name) => declares(parameters, name));
+        if (declares(parameters, 'namespace')) {
+            if (direct.length > 0) {
+                refusals.push({
+                    reason: 'mixed-parameters',
+                    guidance: `cloudflare({ namespace }) deploys immutable deployments and cannot also name ` +
+                        `${direct.join(', ')}, which select the legacy direct mode. Keep \`namespace\` and ` +
+                        `remove ${direct.join(', ')}, or remove \`namespace\` to stay on the direct mode.`,
+                });
+            }
+            const wrangler = parameters.wrangler;
+            if (wrangler !== undefined && declares(wrangler, 'triggers')) {
+                refusals.push({
+                    reason: 'scheduled-triggers',
+                    guidance: 'cloudflare({ namespace }) refuses `wrangler.triggers`: an immutable deployment runs ' +
+                        'no cron of its own. Remove `wrangler.triggers`, or keep the cron on a direct-mode ' +
+                        'Environment.',
+                });
+            }
+        }
+        else {
+            reasons.push(...direct.map((parameter) => ({ reason: 'direct-parameter', parameter })), { reason: 'no-namespace' });
+        }
+    }
+    if (!releases)
+        reasons.push({ reason: 'no-deploy-release' });
+    if (refusals.length > 0)
+        return Object.freeze({ kind: 'refused', refusals: freeze(refusals) });
+    if (reasons.length > 0 && command === 'publish') {
+        return Object.freeze({
+            kind: 'refused',
+            refusals: freeze([
+                { reason: 'publish-legacy-direct', guidance: publishGuidance(environment, reasons) },
+            ]),
+        });
+    }
+    if (reasons.length > 0)
+        return Object.freeze({ kind: 'legacy-direct', reasons: freeze(reasons) });
+    return Object.freeze({ kind: 'canonical' });
+}
+/**
+ * How an adapter-astrale Environment of the removed instance mode deploys now: without `instance`
+ * (nor `serviceKey` and `name`, which named its stable Service), then installed by URL on the
+ * instance it used to deploy through.
+ */
+function astraleInstanceGuidance(parameters, environment) {
+    const instance = String(parameters.instance);
+    const service = ASTRALE_SERVICE_PARAMETERS.filter((name) => declares(parameters, name));
+    const removed = service.length === 0
+        ? 'Remove `instance`'
+        : `Remove \`instance\` with ${service.map((name) => `\`${name}\``).join(' and ')}, ` +
+            `which named its stable Service`;
+    return (`astrale({ instance: '${instance}' }) deployed through that instance's Services, which no ` +
+        `longer hosts deployments. ${removed}: \`astrale-domain deploy ${environment}\` ` +
+        `makes an immutable deployment on Admin's Services, and \`${installCommand(instance)}\` ` +
+        'installs it.');
+}
+/**
+ * Why a legacy direct-mode Environment cannot be published, and the configuration that makes it
+ * publishable: a version names an immutable deployment's release, which a stable target never
+ * serves.
+ */
+function publishGuidance(environment, reasons) {
+    const deploys = `\`astrale-domain publish ${environment}\` names an immutable deployment's release, and ${environment} deploys`;
+    if (reasons.some(({ reason }) => reason === 'no-deploy-release')) {
+        return (`${deploys} through an adapter without deployRelease, which replaces a stable target in ` +
+            'place and serves no release. Use an adapter that implements deployRelease (adapter ' +
+            "interface v2), such as astrale() on Admin's Services.");
+    }
+    const direct = reasons.flatMap((reason) => reason.reason === 'direct-parameter' ? [reason.parameter] : []);
+    return (`${deploys} on cloudflare()'s legacy direct mode, which serves no release. Deploy it into a ` +
+        'dispatch namespace with cloudflare({ namespace })' +
+        (direct.length === 0 ? '' : ` and remove ${direct.join(', ')}`) +
+        ", or on Admin's Services with astrale().");
+}
+/** A parameter is declared when its value is not `undefined`, as optional adapter parameters read. */
+function declares(parameters, name) {
+    return Object.hasOwn(parameters, name) && parameters[name] !== undefined;
+}
+function freeze(values) {
+    return Object.freeze(values.map((value) => Object.freeze(value)));
+}