@astrale-os/sdk 0.6.0-beta.4 → 0.6.0-beta.41

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,26 @@
+/** A supported immutable deployment, or a configuration refused before provider effects. */
+export type DeployMode = {
+    readonly kind: 'canonical';
+} | {
+    readonly kind: 'refused';
+    readonly refusals: readonly DeployRefusal[];
+};
+export interface DeployRefusal {
+    readonly reason: 'invalid-parameters' | 'missing-namespace' | 'scheduled-triggers' | 'unsupported-adapter';
+    readonly guidance: string;
+}
+export type DeployModeCommand = 'deploy' | 'publish';
+/** Inspect one Environment's deployment contract without building or changing any provider. */
+export declare function selectDeployMode(input: {
+    readonly command: DeployModeCommand;
+    readonly environment: string;
+    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,59 @@
+/** Inspect one Environment's deployment contract without building or changing any provider. */
+export function selectDeployMode(input) {
+    const { adapter, parameters } = input.definition.deployment;
+    const values = parameters;
+    const refusals = [];
+    if (typeof adapter.deployRelease !== 'function') {
+        refusals.push({
+            reason: 'unsupported-adapter',
+            guidance: `Adapter ${adapter.name} must implement configure, placement and deployRelease for immutable deployments.`,
+        });
+    }
+    if (adapter.name === 'cloudflare') {
+        if (values.namespace === undefined) {
+            refusals.push({
+                reason: 'missing-namespace',
+                guidance: 'cloudflare requires namespace: { name, routingDomain }. Use astrale() for managed deployments.',
+            });
+        }
+        const allowed = [
+            'namespace',
+            'secrets',
+            'vars',
+            'maximumRequestBytes',
+            'invocationTimeoutMs',
+            'tokenExchange',
+            'durable',
+            'wrangler',
+            'router',
+        ];
+        const unknown = Reflect.ownKeys(values).filter((key) => typeof key !== 'string' || !allowed.includes(key));
+        if (unknown.length > 0)
+            refusals.push({
+                reason: 'invalid-parameters',
+                guidance: `Cloudflare Environment ${input.environment} declares unknown parameters ${unknown.map(String).join(', ')}.`,
+            });
+        const wrangler = values.wrangler;
+        if (wrangler !== undefined && Object.hasOwn(wrangler, 'triggers')) {
+            refusals.push({
+                reason: 'scheduled-triggers',
+                guidance: 'Immutable deployments run no cron of their own. Remove wrangler.triggers.',
+            });
+        }
+    }
+    if (adapter.name === 'astrale') {
+        const allowed = ['admin', 'secrets', 'vars', 'maximumRequestBytes', 'tokenExchange', 'durable'];
+        const unknown = Reflect.ownKeys(values).filter((key) => typeof key !== 'string' || !allowed.includes(key));
+        if (unknown.length > 0)
+            refusals.push({
+                reason: 'invalid-parameters',
+                guidance: `Astrale Environment ${input.environment} declares unknown parameters ${unknown.map(String).join(', ')}.`,
+            });
+    }
+    return refusals.length === 0
+        ? Object.freeze({ kind: 'canonical' })
+        : Object.freeze({
+            kind: 'refused',
+            refusals: Object.freeze(refusals.map((r) => Object.freeze(r))),
+        });
+}

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

@@ -0,0 +1,80 @@
+import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { ReleaseDigest } from '@astrale-os/kernel-protocol/release';
+import type { DeploymentCommitV1 } from '../../deployment/address/index.js';
+import type { BuildDigest, DeploymentSecretsState, ReadyReleaseDeployResult, Release } from '../../deployment/index.js';
+export type { DeploymentSecretsState } from '../../deployment/index.js';
+/**
+ * `astrale-domain deploy <environment> --json` on stdout: the one deployment the deploy made or
+ * reused, which CI installs by its URL. Progress and warnings go to stderr. It names no instance
+ * and no version: a deploy numbers nothing and installs nothing.
+ */
+export interface DeployResultV1 {
+    readonly format: 'astrale.deploy-result';
+    readonly version: 1;
+    readonly origin: string;
+    readonly environment: string;
+    /**
+     * The URL `astrale domain install <url>` takes: an immutable deployment's URL, which is also its
+     * issuer.
+     */
+    readonly url: string;
+    /**
+     * The digest of the DomainRelease v4 served at release.json.
+     */
+    readonly release: {
+        readonly digest: ReleaseDigest;
+    };
+    /**
+     * The build digest of the code the deployment runs, as astrale-domain build prints it.
+     */
+    readonly build: {
+        readonly digest: BuildDigest;
+    };
+    readonly schema: {
+        readonly revision: Revision;
+    };
+    readonly deployment: {
+        /** `<adapter name>@<adapter version>` */
+        readonly adapter: string;
+        /**
+         * The provider script that serves this deployment: an immutable deployment's label, which is
+         * also the first label of its URL.
+         */
+        readonly script: string;
+        /**
+         * `created`: a new immutable deployment. `reused`: the immutable deployment of this exact
+         * release already existed.
+         */
+        readonly state: 'created' | 'reused';
+    };
+    /**
+     * Immutable deployments only: the environment's current secrets were `bound` to a new
+     * deployment, or `updated` or left `unchanged` in place on the reused one. A deploy never writes
+     * the secrets of any other deployment.
+     */
+    readonly secrets: {
+        readonly state: DeploymentSecretsState;
+    };
+    /**
+     * The commit the deployment was built from, as its deployment record declares it: the commit of
+     * the deploy that created it. A reused deployment keeps its record, so this can be an earlier
+     * commit than the one the deploy ran from; the label covers the release, never the commit.
+     */
+    readonly commit: DeploymentCommitV1 | null;
+}
+/**
+ * The deploy result of one immutable deployment, from the ready result of the adapter's
+ * `deployRelease`. Its release, build, Schema revision and URL are those the SDK sealed before
+ * deploying; the deployment record the adapter returned must declare exactly that release at that
+ * URL, so the result never names a release the deployment does not serve. Its commit is the
+ * record's, which a reused deployment kept from the deploy that created it.
+ */
+export declare function deployResult(input: {
+    readonly environment: string;
+    readonly adapter: {
+        readonly name: string;
+        readonly version: string;
+    };
+    readonly release: Release;
+    readonly deployment: ReadyReleaseDeployResult;
+}): DeployResultV1;

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

@@ -0,0 +1,64 @@
+import { acceptDeploymentRecord } from '../../deployment/address/index.js';
+import { addressing, isRelease } from '../../deployment/index.js';
+const SECRETS_BY_STATE = Object.freeze({
+    created: Object.freeze(['bound']),
+    reused: Object.freeze(['updated', 'unchanged']),
+});
+/**
+ * The deploy result of one immutable deployment, from the ready result of the adapter's
+ * `deployRelease`. Its release, build, Schema revision and URL are those the SDK sealed before
+ * deploying; the deployment record the adapter returned must declare exactly that release at that
+ * URL, so the result never names a release the deployment does not serve. Its commit is the
+ * record's, which a reused deployment kept from the deploy that created it.
+ */
+export function deployResult(input) {
+    const { release, deployment } = input;
+    if (!isRelease(release))
+        throw new TypeError('Deploy result requires a sealed Release.');
+    if (deployment.status !== 'ready') {
+        throw new TypeError('Deploy result requires the ready result of deployRelease.');
+    }
+    const record = acceptDeploymentRecord(deployment.record);
+    const { document } = release;
+    expectSame('origin', record.origin, document.origin);
+    expectSame('environment', record.environment, input.environment);
+    expectSame('release digest', record.releaseDigest, document.digest);
+    expectSame('build digest', record.buildDigest, release.buildDigest);
+    expectSame('Schema revision', record.schemaRevision, document.schema.revision);
+    const url = addressing(deployment.url).issuer;
+    expectSame('URL', url, release.url);
+    if (new URL(url).hostname.split('.')[0] !== record.providerScript) {
+        throw new TypeError(`Deployment URL ${url} is not addressed by its provider script ${record.providerScript}.`);
+    }
+    const allowed = Object.hasOwn(SECRETS_BY_STATE, deployment.state)
+        ? SECRETS_BY_STATE[deployment.state]
+        : undefined;
+    if (allowed === undefined)
+        throw new TypeError('Deployment state must be created or reused.');
+    const secrets = deployment.secrets?.state;
+    if (!allowed.includes(secrets)) {
+        throw new TypeError(`A ${deployment.state} deployment has its secrets ${allowed.join(' or ')}, not ${String(secrets)}.`);
+    }
+    return Object.freeze({
+        format: 'astrale.deploy-result',
+        version: 1,
+        origin: document.origin,
+        environment: record.environment,
+        url,
+        release: Object.freeze({ digest: document.digest }),
+        build: Object.freeze({ digest: release.buildDigest }),
+        schema: Object.freeze({ revision: record.schemaRevision }),
+        deployment: Object.freeze({
+            adapter: `${input.adapter.name}@${input.adapter.version}`,
+            script: record.providerScript,
+            state: deployment.state,
+        }),
+        secrets: Object.freeze({ state: secrets }),
+        commit: record.commit,
+    });
+}
+function expectSame(member, declared, expected) {
+    if (declared !== expected) {
+        throw new TypeError(`Deployment declares ${member} ${declared}, not ${expected}.`);
+    }
+}

package/dist/tooling/cli/diff/declared.d.ts

@@ -0,0 +1,7 @@
+import type { Version } from '../../../platform/versioning/index.js';
+/**
+ * The version the author declares for the next release: `package.json` `version` in the Project
+ * directory, as release-please and `npm version` write it (tech Versioning [.21210]). No command
+ * takes a version number.
+ */
+export declare function declaredVersion(projectDir: string): Promise<Version>;

package/dist/tooling/cli/diff/declared.js

@@ -0,0 +1,27 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { acceptVersion } from '../../../platform/versioning/index.js';
+/**
+ * The version the author declares for the next release: `package.json` `version` in the Project
+ * directory, as release-please and `npm version` write it (tech Versioning [.21210]). No command
+ * takes a version number.
+ */
+export async function declaredVersion(projectDir) {
+    const path = join(projectDir, 'package.json');
+    let manifest;
+    try {
+        manifest = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch (cause) {
+        throw new TypeError(`Cannot read the Domain's version: ${path} is not a readable JSON file.`, {
+            cause,
+        });
+    }
+    const version = typeof manifest === 'object' && manifest !== null && !Array.isArray(manifest)
+        ? manifest.version
+        : undefined;
+    if (typeof version !== 'string') {
+        throw new TypeError(`${path} declares no version. The Domain's version is the package.json version, for example written by npm version minor.`);
+    }
+    return acceptVersion(version);
+}