@astrale-os/sdk 0.6.0-beta.13 → 0.6.0-beta.14

package/dist/execution/service/release.d.ts

@@ -1,7 +1,7 @@
 import type { Runtime } from '../../application/runtime/index.js';
 import type { Build } from '../../deployment/build/build.js';
-import type { Release } from '../../deployment/release/legacy/release.js';
 import type { schema } from '../../platform/schema/index.js';
-export type ReleaseForRuntime<RuntimeValue extends Runtime> = Release<Build<schema.DomainSchema, RuntimeValue>>;
+import type { ServedRelease } from '../runtime/index.js';
+export type ReleaseForRuntime<RuntimeValue extends Runtime> = ServedRelease<Build<schema.DomainSchema, RuntimeValue>>;
 export type ReleaseLoader<Environment, RuntimeValue extends Runtime = Runtime> = (environment: Environment) => ReleaseForRuntime<RuntimeValue> | Promise<ReleaseForRuntime<RuntimeValue>>;
 export declare function loadRelease<Environment, RuntimeValue extends Runtime>(load: ReleaseLoader<Environment, RuntimeValue>, environment: Environment, runtime: RuntimeValue): Promise<ReleaseForRuntime<RuntimeValue>>;

package/dist/execution/service/release.js

@@ -1,10 +1,11 @@
-import { isRelease } from '../../deployment/release/legacy/admission.js';
+import { isServedRelease } from '../runtime/index.js';
 export async function loadRelease(load, environment, runtime) {
     if (typeof load !== 'function')
         throw new TypeError('Service Release loader is invalid.');
     const release = await load(environment);
-    if (!isRelease(release))
+    if (!isServedRelease(release)) {
         throw new TypeError('Service loader returned an unadmitted Release.');
+    }
     if (release.build.runtime !== runtime) {
         throw new TypeError('Service Release Runtime differs from the generated entrypoint Runtime.');
     }

package/dist/execution/service/service.d.ts

@@ -1,19 +1,23 @@
 import type { ApplicationHost, ServerCloseOptions, ServerOptions } from '@astrale-os/kernel-server';
-import type { publication } from '@astrale-os/kernel-server';
+import type { release } from '@astrale-os/kernel-server';
 import type { Runtime } from '../../application/runtime/index.js';
 import type { WorkflowRunner } from '../../application/workflow/runner/index.js';
-import type { Release } from '../../deployment/release/legacy/index.js';
 import type { Identity } from '../identity/index.js';
+import type { ServedRelease } from '../runtime/index.js';
 import type { DurableServing, DurableServingProvider } from '../workflows/index.js';
 import type { ReleaseLoader } from './release.js';
-export type ServiceServerOptions = Omit<ServerOptions, 'path' | 'invocation' | 'issuer' | 'publicOrigin' | 'tokenExchange' | 'publication' | 'delivery'>;
+export type ServiceServerOptions = Omit<ServerOptions, 'path' | 'invocation' | 'issuer' | 'publicOrigin' | 'tokenExchange' | 'release' | 'publication' | 'delivery'>;
 export interface ServiceInput<Environment, RuntimeValue extends Runtime = Runtime> {
     readonly runtime: RuntimeValue;
     readonly environment: Environment;
     readonly load: ReleaseLoader<Environment, RuntimeValue>;
     readonly identity: Identity;
     readonly server: ServiceServerOptions;
-    readonly delivery?: publication.delivery.Provider;
+    /**
+     * Answers Delivery in the request's version: v2 over an immutable deployment's release, v1 over
+     * the Publication (a release's frozen v3 projection). Defaults to the Identity's own.
+     */
+    readonly delivery?: release.delivery.Provider;
     readonly workflows?: WorkflowRunner;
     /**
      * Serve the Release's durable Workflows. A provider is resolved on the first engine request,
@@ -23,7 +27,7 @@ export interface ServiceInput<Environment, RuntimeValue extends Runtime = Runtim
 }
 export interface Service {
     fetch(request: Request, host?: ApplicationHost): Promise<Response>;
-    release(): Promise<Release>;
+    release(): Promise<ServedRelease>;
     drain(): void;
     close(options: ServerCloseOptions): Promise<void>;
 }

package/dist/execution/service/serving/delivery.d.ts

@@ -0,0 +1,6 @@
+import type { release } from '@astrale-os/kernel-server';
+/**
+ * Capture an explicit Delivery Provider. It answers in the request's version: v2 over an immutable
+ * deployment's release, v1 over the Publication (a release's frozen v3 projection).
+ */
+export declare function delivery(input: release.delivery.Provider | undefined): release.delivery.Provider | undefined;

package/dist/execution/service/{publication → serving}/delivery.js

@@ -1,8 +1,12 @@
+/**
+ * Capture an explicit Delivery Provider. It answers in the request's version: v2 over an immutable
+ * deployment's release, v1 over the Publication (a release's frozen v3 projection).
+ */
 export function delivery(input) {
     if (input === undefined)
         return undefined;
     if (input === null || typeof input !== 'object' || typeof input.create !== 'function') {
-        throw new TypeError('Publication delivery Provider is invalid.');
+        throw new TypeError('Delivery Provider is invalid.');
     }
     const create = input.create.bind(input);
     return Object.freeze({ create });

package/dist/execution/service/{publication → serving}/index.d.ts

@@ -1,3 +1,3 @@
 export { delivery } from './delivery.js';
 export { installation } from './installation.js';
-export { source } from './source.js';
+export { source, type ServingSource } from './source.js';

package/dist/execution/service/serving/installation.d.ts

@@ -0,0 +1,4 @@
+import type { release } from '@astrale-os/kernel-server';
+import type { Serving } from '../../runtime/index.js';
+/** A served document advertises Delivery exactly when the Service has a Provider for it. */
+export declare function installation(served: Serving['document'], provider: release.delivery.Provider | undefined): void;

package/dist/execution/service/serving/installation.js

@@ -0,0 +1,9 @@
+/** A served document advertises Delivery exactly when the Service has a Provider for it. */
+export function installation(served, provider) {
+    const advertised = served.delivery !== undefined;
+    if (advertised !== (provider !== undefined)) {
+        throw new TypeError(advertised
+            ? 'Release advertises delivery without a Provider.'
+            : 'Delivery Provider has no Release endpoint.');
+    }
+}

package/dist/execution/service/serving/legacy/index.d.ts

@@ -0,0 +1,15 @@
+import type { PublicationSource } from '@astrale-os/kernel-server';
+import type * as legacy from '../../../../deployment/release/legacy/index.js';
+import type { LoadedRuntime } from '../../../runtime/index.js';
+/**
+ * Serve a stable target's v3 Publication through the Kernel Server's v3-input source: `domain.json`
+ * only (404 at `release.json`), with the same-schema continuity of a stable Worker.
+ *
+ * @deprecated Replacement: the release source of `../source.ts`, which serves an immutable
+ * deployment's `DomainRelease` v4. Consumer: the stable Worker of the direct-mode path (the
+ * consumers of `deployment/release/legacy/index.ts`), whose host binds no build digest. Removal:
+ * D10, with `deployment/release/legacy/` and Kernel Server's `publication` source.
+ */
+export declare function publicationSource(runtime: LoadedRuntime, served: legacy.Release): {
+    readonly publication: PublicationSource;
+};

package/dist/execution/service/serving/legacy/index.js

@@ -0,0 +1,19 @@
+import { preparePublicationSnapshot } from '@astrale-os/kernel-server';
+/**
+ * Serve a stable target's v3 Publication through the Kernel Server's v3-input source: `domain.json`
+ * only (404 at `release.json`), with the same-schema continuity of a stable Worker.
+ *
+ * @deprecated Replacement: the release source of `../source.ts`, which serves an immutable
+ * deployment's `DomainRelease` v4. Consumer: the stable Worker of the direct-mode path (the
+ * consumers of `deployment/release/legacy/index.ts`), whose host binds no build digest. Removal:
+ * D10, with `deployment/release/legacy/` and Kernel Server's `publication` source.
+ */
+export function publicationSource(runtime, served) {
+    const snapshot = preparePublicationSnapshot({
+        publication: served.publication,
+        bundle: served.build.schema.bundle.bytes(),
+        table: served.routes,
+        domain: runtime.domain,
+    });
+    return Object.freeze({ publication: Object.freeze({ current: () => snapshot }) });
+}

package/dist/execution/service/serving/source.d.ts

@@ -0,0 +1,18 @@
+import type { PublicationSource, ReleaseSource } from '@astrale-os/kernel-server';
+import type { LoadedRuntime } from '../../runtime/index.js';
+/** The one source a Kernel Server serves, as `ServerOptions` takes it. */
+export type ServingSource = 
+/** The release of an immutable deployment: `release.json` and its v3 projection. */
+{
+    readonly release: ReleaseSource;
+}
+/** @deprecated A stable target's v3 Publication; see `legacy/index.ts`. */
+ | {
+    readonly publication: PublicationSource;
+};
+/**
+ * Prepare, once, the exact snapshot the loaded Release serves: an immutable deployment serves its
+ * `DomainRelease` through `prepareReleaseSnapshot`, which admits only routing naming that exact
+ * release or its exact v3 projection; a stable target keeps serving its v3 Publication.
+ */
+export declare function source(runtime: LoadedRuntime): ServingSource;

package/dist/execution/service/serving/source.js

@@ -0,0 +1,19 @@
+import { prepareReleaseSnapshot } from '@astrale-os/kernel-server';
+import { publicationSource } from './legacy/index.js';
+/**
+ * Prepare, once, the exact snapshot the loaded Release serves: an immutable deployment serves its
+ * `DomainRelease` through `prepareReleaseSnapshot`, which admits only routing naming that exact
+ * release or its exact v3 projection; a stable target keeps serving its v3 Publication.
+ */
+export function source(runtime) {
+    const served = runtime.release;
+    if (served.kind !== 'release')
+        return publicationSource(runtime, served);
+    const snapshot = prepareReleaseSnapshot({
+        release: served.document,
+        bundle: served.build.schema.bundle.bytes(),
+        table: served.routes,
+        domain: runtime.domain,
+    });
+    return Object.freeze({ release: Object.freeze({ current: () => snapshot }) });
+}

package/dist/project/define.js

@@ -2,7 +2,10 @@ import { isDomainDefinition } from '../application/index.js';
 import { isDeployment } from '../deployment/deployment.js';
 import { ENVIRONMENT_NAME } from '../deployment/environment.js';
 import { isTests } from '../testing/index.js';
+import { installCommand } from './install-command.js';
 const admittedProjects = new WeakSet();
+/** The adapter name of adapter-astrale, whose instance mode once read `installation`. */
+const ASTRALE_ADAPTER = 'astrale';
 /** Capture one inert Project definition without loading entrypoints or performing effects. */
 export function defineProject(input) {
     const value = record(input, 'Project definition');
@@ -19,27 +22,28 @@ export function defineProject(input) {
     const names = Object.keys(environments);
     if (names.length === 0)
         throw new TypeError('Project must declare at least one Environment.');
-    const captured = Object.create(null);
-    for (const name of names) {
+    const declared = names.map((name) => {
         if (!ENVIRONMENT_NAME.test(name)) {
             throw new TypeError(`Project Environment name "${name}" is not normalized.`);
         }
-        const environment = record(environments[name], `Project Environment ${name}`);
-        exact(environment, ['deployment'], ['installation'], () => invalidEnvironment(name));
+        return [name, record(environments[name], `Project Environment ${name}`)];
+    });
+    // One refusal names every Environment that declares installation, each with its own commands.
+    const installations = declared
+        .filter(([, environment]) => Object.hasOwn(environment, 'installation'))
+        .map(([name, environment]) => installationRefusal(environment, name));
+    if (installations.length > 0)
+        throw new TypeError(installations.join('\n'));
+    const captured = Object.create(null);
+    for (const [name, environment] of declared) {
+        exact(environment, ['deployment'], [], () => invalidEnvironment(name));
         if (!isDeployment(environment.deployment)) {
             throw new TypeError(`Project Environment ${name} deployment is not admitted.`);
         }
-        const installation = environment.installation === undefined
-            ? undefined
-            : admitInstallation(environment.installation, name);
         environment.deployment.adapter.admit?.(environment.deployment.parameters, {
             environment: name,
-            ...(installation === undefined ? {} : { installation }),
-        });
-        captured[name] = Object.freeze({
-            deployment: environment.deployment,
-            ...(installation === undefined ? {} : { installation }),
         });
+        captured[name] = Object.freeze({ deployment: environment.deployment });
     }
     const entrypoints = input.entrypoints === undefined ? undefined : admitEntrypoints(input.entrypoints);
     if (input.tests !== undefined && !isTests(input.tests)) {
@@ -71,22 +75,47 @@ function admitEntrypoints(input) {
     }
     return Object.freeze({ runtime: input.runtime });
 }
-function admitInstallation(input, environment) {
-    const value = record(input, `Project Environment ${environment} installation`);
-    exact(value, ['instance'], ['identity'], () => {
-        throw new TypeError(`Project Environment ${environment} installation may contain only instance and identity.`);
-    });
-    const instance = stableCoordinate(value.instance, 'installation instance');
-    const identity = value.identity === undefined
-        ? undefined
-        : stableCoordinate(value.identity, 'installation identity');
-    return Object.freeze({ instance, ...(identity === undefined ? {} : { identity }) });
-}
-function stableCoordinate(input, label) {
-    if (typeof input !== 'string' || input.length === 0 || input.trim() !== input) {
-        throw new TypeError(`Project ${label} must be a non-empty stable string.`);
+/**
+ * A deploy no longer installs (DX [.81399], AM-72): an Environment that still declares
+ * `installation` is refused before any effect, with the commands that replace it. Its only
+ * consumer pins an SDK older than this refusal.
+ *
+ * adapter-astrale took its Services instance, and the identity of its Services calls, from
+ * `installation` when `astrale({ instance })` named none. For such an Environment the guidance
+ * also moves the instance into the adapter and passes the identity to the deploy, so following
+ * it deploys exactly where and as the configuration did.
+ */
+function installationRefusal(environment, name) {
+    const declared = environment.installation;
+    if (declared === undefined) {
+        return (`Project Environment ${name} declares \`installation\`, which a deploy no longer reads: a ` +
+            'deploy never installs. Remove the key.');
     }
-    return input;
+    const installation = declared !== null && typeof declared === 'object'
+        ? declared
+        : {};
+    const instance = stable(installation.instance);
+    const identity = stable(installation.identity);
+    const deployment = environment.deployment;
+    const astrale = isDeployment(deployment) &&
+        deployment.adapter.name === ASTRALE_ADAPTER &&
+        deployment.parameters.instance === undefined;
+    const adapterInstance = astrale
+        ? `, name its instance in \`astrale({ instance: '${instance ?? '<instance>'}' })\``
+        : '';
+    const deployIdentity = astrale && identity !== undefined ? ` --as ${identity}` : '';
+    return (`Project Environment ${name} declares installation, and a deploy no longer installs. ` +
+        `Remove \`installation\`${adapterInstance}, run \`astrale-domain deploy ${name}${deployIdentity}\`, ` +
+        `then install the URL it prints with \`${installCommand(instance, identity)}\`.`);
+}
+/** A declared coordinate worth repeating in guidance: a non-empty single-line trimmed string. */
+function stable(input) {
+    return typeof input === 'string' &&
+        input.length > 0 &&
+        input.trim() === input &&
+        !/[\s`]/u.test(input)
+        ? input
+        : undefined;
 }
 function record(input, label) {
     if (input === null || typeof input !== 'object' || Array.isArray(input)) {
@@ -105,5 +134,5 @@ function invalid() {
     throw new TypeError('Project definition may contain only domain, environments, entrypoints, and tests.');
 }
 function invalidEnvironment(name) {
-    throw new TypeError(`Project Environment ${name} may contain only deployment and installation.`);
+    throw new TypeError(`Project Environment ${name} may contain only deployment.`);
 }

package/dist/project/install-command.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The command that installs a deployed URL on an instance, as every SDK refusal and help text
+ * names it. A deploy never installs (DX [.81399], AM-72): `astrale-domain deploy <environment>`
+ * prints a URL, and this command installs it.
+ *
+ * `--direct` sends a URL install to the instance Kernel, which the astrale CLI requires today and
+ * accepts until D13. When the CLI retires it, this is the one SDK text to change; the adapter and
+ * scaffold READMEs and templates repeat it as prose.
+ */
+export declare function installCommand(instance?: string, identity?: string): string;

package/dist/project/install-command.js

@@ -0,0 +1,13 @@
+/**
+ * The command that installs a deployed URL on an instance, as every SDK refusal and help text
+ * names it. A deploy never installs (DX [.81399], AM-72): `astrale-domain deploy <environment>`
+ * prints a URL, and this command installs it.
+ *
+ * `--direct` sends a URL install to the instance Kernel, which the astrale CLI requires today and
+ * accepts until D13. When the CLI retires it, this is the one SDK text to change; the adapter and
+ * scaffold READMEs and templates repeat it as prose.
+ */
+export function installCommand(instance = '<instance>', identity) {
+    return (`astrale domain install <url> --direct -i ${instance}` +
+        (identity === undefined ? '' : ` --as ${identity}`));
+}

package/dist/project/project.d.ts

@@ -1,12 +1,14 @@
 import type { DomainDefinitionIdentity } from '../application/index.js';
-import type { InstallationTarget } from '../deployment/adapter/index.js';
 import type { Tests } from '../testing/index.js';
 export interface ProjectEntrypoints {
     readonly runtime: string;
 }
+/**
+ * One Environment of a Project: where and how its deployments are made. It never names an
+ * instance: a deploy installs nothing, and `astrale domain install <url>` installs a deployment.
+ */
 export interface ProjectEnvironment<DeploymentValue = unknown> {
     readonly deployment: DeploymentValue;
-    readonly installation?: InstallationTarget;
 }
 /** The complete independently executable software-product definition in astrale.config.ts. */
 export interface Project<DomainDefinitionValue extends DomainDefinitionIdentity = DomainDefinitionIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>> = Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined = undefined> {

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

@@ -6,11 +6,9 @@ export interface ParsedArgs {
     readonly env: string;
     readonly fix?: boolean;
     readonly format?: LintReportFormat;
-    readonly deployOnly?: boolean;
     readonly identity?: string;
     readonly credentialFile?: string;
     readonly suite?: string;
-    readonly sessionFile?: string;
     readonly secretsFile?: string;
     readonly channel?: string;
     readonly check?: boolean;

package/dist/tooling/cli/arguments.js

@@ -1,4 +1,5 @@
 import { isAbsolute, normalize } from 'node:path';
+import { installCommand } from '../../project/install-command.js';
 export const COMMANDS = ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
@@ -8,7 +9,6 @@ export function parseArgs(argv) {
     const fix = rest.includes('--fix');
     const deployOnly = rest.includes('--deploy-only');
     const json = rest.includes('--json');
-    let sessionFile;
     let secretsFile;
     let credentialFile;
     let identity;
@@ -18,13 +18,7 @@ export function parseArgs(argv) {
     const cleaned = [];
     for (let index = 0; index < rest.length; index += 1) {
         const argument = rest[index];
-        if (argument === '--session-file') {
-            sessionFile = absoluteFilePath('--session-file', rest[++index]);
-        }
-        else if (argument.startsWith('--session-file=')) {
-            sessionFile = absoluteFilePath('--session-file', argument.slice('--session-file='.length));
-        }
-        else if (argument === '--credential-file') {
+        if (argument === '--credential-file') {
             credentialFile = absoluteFilePath('--credential-file', rest[++index]);
         }
         else if (argument.startsWith('--credential-file=')) {
@@ -78,15 +72,16 @@ export function parseArgs(argv) {
     if (format !== undefined && command !== 'lint') {
         throw new Error('`--format` is only valid for `lint`.');
     }
-    if ((sessionFile !== undefined || credentialFile !== undefined || secretsFile !== undefined) &&
-        command !== 'dev') {
-        throw new Error('`--session-file`, `--credential-file`, and `--secrets-file` are only valid for `dev`.');
+    if ((credentialFile !== undefined || secretsFile !== undefined) && command !== 'dev') {
+        throw new Error('`--credential-file` and `--secrets-file` are only valid for `dev`.');
     }
     if (identity !== undefined && credentialFile !== undefined) {
         throw new Error('Choose either `--as` or `--credential-file`, not both.');
     }
-    if ((deployOnly || identity !== undefined) && command !== 'dev' && command !== 'deploy') {
-        throw new Error('`--deploy-only` and `--as` are only valid for `dev` or `deploy`.');
+    if (deployOnly && command !== 'dev' && command !== 'deploy')
+        refuseDeployOnly(undefined);
+    if (identity !== undefined && command !== 'dev' && command !== 'deploy') {
+        throw new Error('`--as` is only valid for `dev` or `deploy`.');
     }
     if (environment !== undefined && command !== 'dev' && command !== 'deploy') {
         if (command !== 'test') {
@@ -110,14 +105,14 @@ export function parseArgs(argv) {
             if (!env) {
                 throw new Error(`\`${command}\` requires an Environment, e.g. \`${command} development\`.`);
             }
+            if (deployOnly)
+                refuseDeployOnly(command, env);
             return {
                 command,
                 env,
                 ...(json ? { json: true } : {}),
-                ...(deployOnly ? { deployOnly: true } : {}),
                 ...(identity === undefined ? {} : { identity }),
                 ...(credentialFile === undefined ? {} : { credentialFile }),
-                ...(sessionFile === undefined ? {} : { sessionFile }),
                 ...(secretsFile === undefined ? {} : { secretsFile }),
             };
         }
@@ -149,6 +144,18 @@ export function parseArgs(argv) {
             throw new Error(command ? `Unknown command "${command}".` : 'Missing command.');
     }
 }
+/**
+ * `--deploy-only` suppressed the installation a deploy used to make. A deploy never installs
+ * (DX [.81399], AM-72), so the flag is refused before any effect, naming the commands that
+ * replace it. Its only consumer pins an SDK older than this refusal.
+ */
+function refuseDeployOnly(command, environment) {
+    const refusal = '`--deploy-only` is no longer accepted: a deploy never installs.';
+    if (command === undefined || environment === undefined)
+        throw new Error(refusal);
+    throw new Error(`${refusal} Run \`astrale-domain ${command} ${environment}\` without it, then install the ` +
+        `URL it prints with \`${installCommand()}\`.`);
+}
 function parseUpgrade(args) {
     let channel = 'beta';
     let check = false;

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

@@ -0,0 +1,23 @@
+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>;