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

package/dist/platform/versioning/reference.js

@@ -0,0 +1,95 @@
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import semver from 'semver';
+import { acceptVersion, isStable } from './version.js';
+const URL_SCHEMES = ['https://', 'http://'];
+const MAJOR = /^(?:0|[1-9]\d*)$/u;
+const LINE = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/u;
+/**
+ * Parse `<origin>@<major>.<minor>.<patch>[-<pre>]`, `<origin>@<major>.<minor>` or a deployment URL.
+ * Ranges are not references: `@1`, `^1.5` and `1.5.x` are refused, since only the exact version and
+ * the highest stable version of one minor line are ever resolved. A URL with credentials is refused:
+ * `https://issues.astrale.ai@1.5.0` would otherwise name the host `1.5.0`, not a version.
+ *
+ * A deployment URL is returned as written, so it must already be the URL the Kernel fetches: one the
+ * URL parser keeps as is, up to the `/` of an empty path. Whitespace and control characters (which
+ * the parser strips), an upper-case host, a default port or a missing `//` host are refused, as are a
+ * query and a fragment, which no deployment URL carries.
+ */
+export function parseReference(input) {
+    if (URL_SCHEMES.some((scheme) => input.startsWith(scheme))) {
+        if (!URL.canParse(input))
+            throw invalid(input);
+        const url = new URL(input);
+        if (url.username !== '' || url.password !== '') {
+            throw new TypeError(`Reference ${JSON.stringify(input)} is not admitted: a deployment URL carries no credentials, and a version reference has no scheme (<origin>@<version>).`);
+        }
+        if (!isWrittenAsParsed(input, url)) {
+            throw new TypeError(`Reference ${JSON.stringify(input)} is not admitted: a deployment URL is written as the Kernel reads it, without whitespace, control characters, a query or a fragment, with a lower-case host and no default port.`);
+        }
+        return Object.freeze({ kind: 'url', url: input });
+    }
+    const at = input.indexOf('@');
+    if (at === -1)
+        throw invalid(input);
+    const origin = input.slice(0, at);
+    const selector = input.slice(at + 1);
+    if (!patterns.origin.test(origin))
+        throw invalid(input);
+    if (MAJOR.test(selector)) {
+        throw new TypeError(`Reference ${JSON.stringify(input)} names a major version only: name a minor line (${origin}@${selector}.<minor>) or an exact version (${origin}@${selector}.<minor>.<patch>).`);
+    }
+    if (isLine(selector))
+        return Object.freeze({ kind: 'line', origin, line: selector });
+    try {
+        return Object.freeze({ kind: 'exact', origin, version: acceptVersion(selector) });
+    }
+    catch (cause) {
+        throw invalid(input, cause);
+    }
+}
+/**
+ * Translate a version reference into one published version. An exact reference names any published
+ * version, a pre-release or a yanked one included (the caller warns on yanked). A line resolves to
+ * its highest stable version that is not yanked.
+ *
+ * A reference built from data rather than by `parseReference` is checked the same way: an exact
+ * version must be canonical and a line must be `<major>.<minor>`, so `1` never resolves as a major
+ * range and `1.5.3` never as an exact pin. Anything else throws a `TypeError`.
+ */
+export function resolveVersion(published, reference) {
+    if (reference.kind === 'exact') {
+        const exact = acceptVersion(reference.version);
+        const match = published.find(({ version }) => version === exact);
+        if (match === undefined)
+            return Object.freeze({ kind: 'unresolved', reason: 'unknown-version' });
+        return Object.freeze({ kind: 'resolved', version: match.version, yanked: match.yanked });
+    }
+    const { kind, line: selector } = reference;
+    if (kind !== 'line') {
+        throw new TypeError(`Reference kind ${String(kind)} is not resolved: only an exact version or a minor line resolves.`);
+    }
+    if (!isLine(selector)) {
+        throw new TypeError(`Line ${typeof selector === 'string' ? JSON.stringify(selector) : typeof selector} is not admitted: expected <major>.<minor>, such as 1.5; a major version or an exact version is not a line.`);
+    }
+    const line = published.filter(({ version }) => isStable(version) && semver.satisfies(version, selector));
+    const version = semver.maxSatisfying(line.filter(({ yanked }) => !yanked).map(({ version }) => version), selector);
+    if (version !== null)
+        return Object.freeze({ kind: 'resolved', version, yanked: false });
+    return Object.freeze({
+        kind: 'unresolved',
+        reason: line.length === 0 ? 'no-stable-match' : 'yanked-only',
+    });
+}
+/** Whether a selector is one minor line, `<major>.<minor>`, whose versions semver can represent. */
+function isLine(selector) {
+    return (typeof selector === 'string' && LINE.test(selector) && semver.valid(`${selector}.0`) !== null);
+}
+/** Whether the URL parser keeps `input` as written, the `/` of an empty path aside. */
+function isWrittenAsParsed(input, url) {
+    if (/[?#]/u.test(input))
+        return false;
+    return url.href === input || (url.pathname === '/' && url.href === `${input}/`);
+}
+function invalid(input, cause) {
+    return new TypeError(`Reference ${JSON.stringify(input)} is not admitted: expected <origin>@<major>.<minor>.<patch>[-<pre>], <origin>@<major>.<minor> or a deployment URL.`, cause === undefined ? undefined : { cause });
+}

package/dist/platform/versioning/version.d.ts

@@ -0,0 +1,72 @@
+/** One SemVer 2.0.0 version as an author declares it: no leading `v`, no build metadata. */
+export type Version = string & {
+    readonly __version: unique symbol;
+};
+/** Semver level a change requires. */
+export type BumpLevel = 'major' | 'minor' | 'patch';
+/** One version of a Domain's registry index. Yanked versions stay in the index. */
+export interface PublishedVersion {
+    readonly version: Version;
+    readonly yanked: boolean;
+}
+/** Outcome of checking a declared version against the stable version before it. */
+export interface VersionVerdict {
+    readonly declared: Version;
+    /** Absent: no stable version before the declared one, nothing to check. */
+    readonly previous?: Version;
+    /** Level the change requires, before the 0.x rule. */
+    readonly level?: BumpLevel;
+    /** Level after the 0.x rule. */
+    readonly effective?: BumpLevel;
+    /** First pre-release of the required version, such as `2.0.0-0`. */
+    readonly minimum?: Version;
+    /** Stable form of the required version, such as `2.0.0`. */
+    readonly next?: Version;
+    /** For a refused pre-release, the first pre-release of the required version on its channel. */
+    readonly suggestion?: Version;
+    readonly accepted: boolean;
+}
+/**
+ * Admit one declared version. Build metadata is refused because it takes no part in precedence
+ * (`1.5.0+x` equals `1.5.0`), so it could not name a distinct version of the registry.
+ */
+export declare function acceptVersion(input: unknown): Version;
+/**
+ * The highest published stable version below (`<`, publish) or up to (`<=`, diff) the declared one.
+ * Yanked versions count, since their installations keep running. Pre-releases never do: a
+ * pre-release is a draft of its version and is compared with the last stable one. An index entry
+ * that is not a canonical version (`v1.4.2`, `1.4.3+b`) is no version and never a baseline; a
+ * declared version that is not canonical is refused, so the check never passes for want of one.
+ */
+export declare function baselineVersion(published: readonly PublishedVersion[], declared: Version, bound: '<' | '<='): Version | undefined;
+/**
+ * Below 1.0.0 a breaking change raises the minor and an addition raises the patch, as
+ * release-please `bump-minor-pre-major` and `bump-patch-for-minor-pre-major` do.
+ */
+export declare function effectiveLevel(level: BumpLevel, previous: Version): BumpLevel;
+/**
+ * The smallest version a change of `level` admits after `previous`, the first pre-release of the
+ * required version: `inc(previous, 'pre' + effective)`.
+ */
+export declare function minimumVersion(previous: Version, level: BumpLevel): Version;
+/**
+ * Check a declared version against the stable version before it and the level its change requires.
+ * Without a previous stable version there is nothing to check. Otherwise the declared version must
+ * reach the minimum, so `2.0.0-rc.1` passes where `1.5.0-beta.1` does not. The check never guesses:
+ * a previous version comes with the level its change requires, which the input type enforces, and a
+ * call that still omits it throws a `TypeError`, as do a declared version that is not canonical and
+ * a previous version that is not stable.
+ */
+export declare function judgeVersion(input: {
+    readonly declared: Version;
+    readonly previous?: undefined;
+    readonly level?: BumpLevel;
+} | {
+    readonly declared: Version;
+    readonly previous: Version | undefined;
+    readonly level: BumpLevel;
+}): VersionVerdict;
+/** Whether a value is a version `acceptVersion` admits: canonical, without `v` or build metadata. */
+export declare function isVersion(input: unknown): input is Version;
+/** Whether a value is a canonical version (`isVersion`) that is not a pre-release. */
+export declare function isStable(version: string): boolean;

package/dist/platform/versioning/version.js

@@ -0,0 +1,98 @@
+import semver from 'semver';
+const PRERELEASE = { major: 'premajor', minor: 'preminor', patch: 'prepatch' };
+/**
+ * Admit one declared version. Build metadata is refused because it takes no part in precedence
+ * (`1.5.0+x` equals `1.5.0`), so it could not name a distinct version of the registry.
+ */
+export function acceptVersion(input) {
+    if (isVersion(input))
+        return input;
+    throw new TypeError(`Version ${typeof input === 'string' ? JSON.stringify(input) : typeof input} is not admitted: expected SemVer 2.0.0 such as 1.5.0 or 2.0.0-rc.1, without a leading "v" or build metadata.`);
+}
+/**
+ * The highest published stable version below (`<`, publish) or up to (`<=`, diff) the declared one.
+ * Yanked versions count, since their installations keep running. Pre-releases never do: a
+ * pre-release is a draft of its version and is compared with the last stable one. An index entry
+ * that is not a canonical version (`v1.4.2`, `1.4.3+b`) is no version and never a baseline; a
+ * declared version that is not canonical is refused, so the check never passes for want of one.
+ */
+export function baselineVersion(published, declared, bound) {
+    acceptVersion(declared);
+    const stables = published.filter(({ version }) => isStable(version)).map(({ version }) => version);
+    return semver.maxSatisfying(stables, `${bound}${declared}`) ?? undefined;
+}
+/**
+ * Below 1.0.0 a breaking change raises the minor and an addition raises the patch, as
+ * release-please `bump-minor-pre-major` and `bump-patch-for-minor-pre-major` do.
+ */
+export function effectiveLevel(level, previous) {
+    if (!Object.hasOwn(PRERELEASE, level)) {
+        throw new TypeError(`Bump level ${JSON.stringify(level)} is not admitted: expected major, minor or patch.`);
+    }
+    if (semver.major(acceptVersion(previous)) !== 0)
+        return level;
+    return level === 'major' ? 'minor' : 'patch';
+}
+/**
+ * The smallest version a change of `level` admits after `previous`, the first pre-release of the
+ * required version: `inc(previous, 'pre' + effective)`.
+ */
+export function minimumVersion(previous, level) {
+    assertBaseline(previous);
+    return increment(previous, PRERELEASE[effectiveLevel(level, previous)]);
+}
+/**
+ * Check a declared version against the stable version before it and the level its change requires.
+ * Without a previous stable version there is nothing to check. Otherwise the declared version must
+ * reach the minimum, so `2.0.0-rc.1` passes where `1.5.0-beta.1` does not. The check never guesses:
+ * a previous version comes with the level its change requires, which the input type enforces, and a
+ * call that still omits it throws a `TypeError`, as do a declared version that is not canonical and
+ * a previous version that is not stable.
+ */
+export function judgeVersion(input) {
+    const { declared, previous, level } = input;
+    acceptVersion(declared);
+    if (previous === undefined)
+        return Object.freeze({ declared, accepted: true });
+    if (level === undefined) {
+        throw new TypeError(`Version ${JSON.stringify(declared)} cannot be checked against ${JSON.stringify(previous)} without the level its change requires.`);
+    }
+    assertBaseline(previous);
+    const effective = effectiveLevel(level, previous);
+    const minimum = minimumVersion(previous, level);
+    const accepted = semver.gte(declared, minimum);
+    const channel = semver.prerelease(declared)?.[0];
+    const suggestion = accepted || channel === undefined
+        ? undefined
+        : increment(previous, PRERELEASE[effective], typeof channel === 'string' ? channel : undefined);
+    return Object.freeze({
+        declared,
+        previous,
+        level,
+        effective,
+        minimum,
+        next: increment(previous, effective),
+        ...(suggestion === undefined ? {} : { suggestion }),
+        accepted,
+    });
+}
+/** Whether a value is a version `acceptVersion` admits: canonical, without `v` or build metadata. */
+export function isVersion(input) {
+    return typeof input === 'string' && semver.valid(input) === input;
+}
+/** Whether a value is a canonical version (`isVersion`) that is not a pre-release. */
+export function isStable(version) {
+    return isVersion(version) && semver.prerelease(version) === null;
+}
+/** The version before a declared one is the highest stable version that `baselineVersion` finds. */
+function assertBaseline(previous) {
+    if (isStable(previous))
+        return;
+    throw new TypeError(`Previous version ${JSON.stringify(previous)} is not admitted: it must be a stable version, the highest stable version before the declared one.`);
+}
+function increment(version, release, channel) {
+    const next = semver.inc(version, release, undefined, channel);
+    if (next === null)
+        throw new TypeError(`Version ${JSON.stringify(version)} is not admitted.`);
+    return next;
+}

package/dist/project/admit.js

@@ -1,8 +1,7 @@
-import { isLegacyDeployment } from '../deployment/deploy.js';
 import { isProject } from './define.js';
 export const PROJECT_EXPORT_HINT = 'astrale.config.ts must export exactly one default Project:\n' +
     "  import { defineProject } from '@astrale-os/sdk/project'\n" +
-    '  export default defineProject({ application, environments: { development: { deployment: adapter() } } })\n';
+    '  export default defineProject({ domain, environments: { development: { deployment: adapter() } } })\n';
 /** Admit the module namespace of one loaded `astrale.config.ts`: exactly one default Project. */
 export function admitProjectModule(loaded) {
     if (loaded === null ||
@@ -15,8 +14,5 @@ export function admitProjectModule(loaded) {
     const value = Reflect.get(loaded, 'default');
     if (isProject(value))
         return value;
-    if (isLegacyDeployment(value)) {
-        throw new TypeError(`astrale.config.ts exports the legacy deploy() aggregate; migrate Application and Environments into defineProject().\n${PROJECT_EXPORT_HINT}`);
-    }
     throw new TypeError(`Default export must be created by defineProject().\n${PROJECT_EXPORT_HINT}`);
 }

package/dist/project/define.d.ts

@@ -1,12 +1,12 @@
-import type { ApplicationIdentity } from '../application/index.js';
+import type { DomainDefinitionIdentity } from '../application/index.js';
 import type { Tests } from '../testing/index.js';
 import type { Project, ProjectEnvironment, ProjectEntrypoints } from './project.js';
-export interface ProjectInput<ApplicationValue extends ApplicationIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined> {
-    readonly application: ApplicationValue;
+export interface ProjectInput<DomainDefinitionValue extends DomainDefinitionIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined> {
+    readonly domain: DomainDefinitionValue;
     readonly environments: EnvironmentsValue;
     readonly entrypoints?: ProjectEntrypoints;
     readonly tests?: TestsValue;
 }
 /** Capture one inert Project definition without loading entrypoints or performing effects. */
-export declare function defineProject<const ApplicationValue extends ApplicationIdentity, const EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>>, const TestsValue extends Tests | undefined = undefined>(input: ProjectInput<ApplicationValue, EnvironmentsValue, TestsValue>): Project<ApplicationValue, EnvironmentsValue, TestsValue>;
+export declare function defineProject<const DomainDefinitionValue extends DomainDefinitionIdentity, const EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>>, const TestsValue extends Tests | undefined = undefined>(input: ProjectInput<DomainDefinitionValue, EnvironmentsValue, TestsValue>): Project<DomainDefinitionValue, EnvironmentsValue, TestsValue>;
 export declare function isProject(input: unknown): input is Project;

package/dist/project/define.js

@@ -1,14 +1,18 @@
-import { isApplication } from '../application/index.js';
+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();
-const ENVIRONMENT_NAME = /^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/u;
 /** Capture one inert Project definition without loading entrypoints or performing effects. */
 export function defineProject(input) {
     const value = record(input, 'Project definition');
-    exact(value, ['application', 'environments'], ['entrypoints', 'tests'], invalid);
-    if (!isApplication(input.application))
-        throw new TypeError('Project Application is not admitted.');
+    if (Object.hasOwn(value, 'application')) {
+        throw new TypeError('Project `application` is now `domain`: defineProject({ domain, environments }).');
+    }
+    exact(value, ['domain', 'environments'], ['entrypoints', 'tests'], invalid);
+    if (!isDomainDefinition(input.domain))
+        throw new TypeError('Project Domain is not admitted.');
     const environments = record(input.environments, 'Project environments');
     if (Reflect.ownKeys(environments).some((key) => typeof key !== 'string')) {
         throw new TypeError('Project Environment names must be strings.');
@@ -16,27 +20,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)) {
@@ -44,7 +49,7 @@ export function defineProject(input) {
     }
     const project = Object.freeze({
         kind: 'project',
-        application: input.application,
+        domain: input.domain,
         environments: Object.freeze(captured),
         ...(entrypoints === undefined ? {} : { entrypoints }),
         ...(input.tests === undefined ? {} : { tests: input.tests }),
@@ -68,22 +73,37 @@ 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 deploys on Admin's Services, never through the installation's instance. The
+ * installation's instance and identity move to the install command.
+ */
+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);
+    return (`Project Environment ${name} declares installation, and a deploy no longer installs. ` +
+        `Remove \`installation\`, run \`astrale-domain deploy ${name}\`, ` +
+        `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)) {
@@ -99,8 +119,8 @@ function exact(input, required, optional, fail) {
     }
 }
 function invalid() {
-    throw new TypeError('Project definition may contain only application, environments, entrypoints, and tests.');
+    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/index.d.ts

@@ -1,4 +1,4 @@
 export { admitProjectModule, PROJECT_EXPORT_HINT } from './admit.js';
 export { defineProject, isProject } from './define.js';
 export type { ProjectInput } from './define.js';
-export type { ApplicationOfProject, EnvironmentsOfProject, Project, ProjectEntrypoints, ProjectEnvironment, } from './project.js';
+export type { DomainDefinitionOfProject, EnvironmentsOfProject, Project, ProjectEntrypoints, ProjectEnvironment, } from './project.js';

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

@@ -0,0 +1,6 @@
+/**
+ * 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.
+ */
+export declare function installCommand(instance?: string, identity?: string): string;

package/dist/project/install-command.js

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export function installCommand(instance = '<instance>', identity) {
+    return (`astrale domain install <url> -i ${instance}` +
+        (identity === undefined ? '' : ` --as ${identity}`));
+}

package/dist/project/project.d.ts

@@ -1,24 +1,26 @@
-import type { ApplicationIdentity } from '../application/index.js';
-import type { InstallationTarget } from '../deployment/adapter/index.js';
+import type { DomainDefinitionIdentity } from '../application/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<ApplicationValue extends ApplicationIdentity = ApplicationIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>> = Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined = undefined> {
+export interface Project<DomainDefinitionValue extends DomainDefinitionIdentity = DomainDefinitionIdentity, EnvironmentsValue extends Readonly<Record<string, ProjectEnvironment>> = Readonly<Record<string, ProjectEnvironment>>, TestsValue extends Tests | undefined = undefined> {
     readonly kind: 'project';
-    readonly application: ApplicationValue;
+    readonly domain: DomainDefinitionValue;
     readonly environments: EnvironmentsValue;
     readonly entrypoints?: ProjectEntrypoints;
     readonly tests?: TestsValue;
 }
-export type ApplicationOfProject<Value> = Value extends {
-    readonly application: infer ApplicationValue;
-} ? Extract<ApplicationValue, ApplicationIdentity> : never;
+export type DomainDefinitionOfProject<Value> = Value extends {
+    readonly domain: infer DomainDefinitionValue;
+} ? Extract<DomainDefinitionValue, DomainDefinitionIdentity> : never;
 export type EnvironmentsOfProject<Value> = Value extends {
     readonly environments: infer EnvironmentsValue;
 } ? EnvironmentsValue : never;

package/dist/testing/dataset/define.d.ts

@@ -7,7 +7,7 @@ export type AuthoredDatasetVariables = DatasetVariables | void;
 /** The exact variables record retained by a Dataset for one authored return type. */
 export type DatasetVariablesOf<Value> = [Value] extends [void] ? Readonly<Record<never, never>> : Value extends DatasetVariables ? Value : never;
 export interface DatasetInput<Schema extends schemaLanguage.DomainSchema, Variables extends AuthoredDatasetVariables> {
-    /** Stable lowercase identity, unique within one Application. */
+    /** Stable lowercase identity, unique within one Domain. */
     readonly id: string;
     readonly title?: string;
     readonly description?: string;

package/dist/testing/durable/engine.d.ts

@@ -0,0 +1,128 @@
+import type { ActionOutputOf, ResolvedDomainOf } from '../../application/action/index.js';
+import type { DeclaredErrors } from '../../application/error/index.js';
+import type { Integrations, Providers } from '../../application/integration/index.js';
+import type { CallableAtWorkflowAddress, DurableStepRetry, WorkflowAddress, WorkflowDefinition } from '../../application/workflow/index.js';
+import type { ExecutionOutcome, ExecutionState } from '../../platform/client/session/index.js';
+import type { NodeId } from '../../platform/graph/node/index.js';
+import type { CallableInputOf, ResolvedMethod, schema } from '../../platform/schema/index.js';
+import type { Value } from '../../platform/value/index.js';
+import type { TestStepCapabilities } from './steps.js';
+export interface TestWorkflowEngineOptions {
+    /** Start of the virtual clock, in Unix milliseconds; the current time by default. */
+    readonly now?: number;
+    /**
+     * The deployment's `durable.retry`: the budget of every Step that declares none, and with
+     * `maxAttempts` the attempts of a run failing outside any Step before it pauses.
+     */
+    readonly retry?: DurableStepRetry;
+}
+/**
+ * An in-memory workflow engine that runs durable Workflows with the receiver a Host serves: it
+ * journals each Step attempt, replays the journal on every attempt, keeps timers on a virtual clock,
+ * buffers signals, pauses a run failing outside any Step after its last attempt and cancels
+ * cooperatively. A Step retries as on a Host: a failure of its own code spends its budget, and a
+ * Kernel or a transport that is unavailable makes it wait without spending it. The wait after the
+ * Step's own failure is not waited out, but counts toward its `maxDurationMs`; a wait for the
+ * platform is a timer, which `advance` moves past.
+ */
+export interface TestWorkflowEngine {
+    /** The virtual clock, in Unix milliseconds. */
+    readonly now: number;
+    /** Start one durable Execution and settle it: it ends, waits, or pauses. */
+    start<Schema extends schema.DomainSchema, Address extends WorkflowAddress<Schema>, Definitions extends Integrations, Errors extends DeclaredErrors>(workflow: WorkflowDefinition<Schema, Address, Definitions, Errors>, options: TestStartOptions<CallableAtWorkflowAddress<Schema, Address>, ResolvedDomainOf<Schema>, Definitions>): Promise<TestExecution<ActionOutputOf<CallableAtWorkflowAddress<Schema, Address>>>>;
+    /** Move the virtual clock forward and settle every waiting Execution. */
+    advance(durationMs: number): Promise<void>;
+}
+export type TestStartOptions<Callable, DomainValue, Definitions extends Integrations> = {
+    /** The resolved Schema the Workflow belongs to. */
+    readonly schema: DomainValue;
+    readonly input: CallableInputOf<Callable>;
+    /** The `K.Execution` id; a fresh one by default. */
+    readonly id?: NodeId;
+    /** Who started the Execution; test Identities by default. */
+    readonly initiator?: {
+        readonly principal: NodeId;
+        readonly caller: NodeId;
+    };
+    readonly capabilities?: TestStepCapabilities;
+    /** Steps whose first completion is lost before the journal records it; see `interruptAfter`. */
+    readonly interruptAfter?: readonly string[];
+} & ReceiverOf<Callable> & ProvidersOf<Definitions>;
+type ReceiverOf<Callable> = Callable extends ResolvedMethod<unknown, unknown, false> ? {
+    readonly self: NodeId;
+} : {
+    readonly self?: never;
+};
+type ProvidersOf<Definitions extends Integrations> = keyof Definitions extends never ? {
+    readonly providers?: never;
+} : {
+    readonly providers: Providers<Definitions>;
+};
+/** One durable Execution on a test workflow engine. */
+export interface TestExecution<Output> {
+    readonly id: NodeId;
+    readonly state: Extract<ExecutionState, 'running' | 'waiting' | 'paused' | 'completed' | 'failed' | 'cancelled'>;
+    /** Present once the Execution ended, as `Execution.result` answers it. */
+    readonly outcome: ExecutionOutcome<Output> | undefined;
+    /**
+     * What the last failed attempt threw: why a paused Execution paused, or what the last attempt of
+     * an exhausted Step threw, which its `STEP_EXHAUSTED` outcome does not carry.
+     */
+    readonly failure: unknown;
+    /** Attempts made so far, replays included. */
+    readonly attempts: number;
+    /** The run's journal, in order. */
+    readonly journal: readonly TestJournalEntry[];
+    /**
+     * Deliver `Execution.signal({ name, value })`, then settle. False when a signal already resolved
+     * that name.
+     */
+    signal(name: string, value?: Value): Promise<boolean>;
+    /** Request cooperative cancellation, as `Execution.cancel()`, then settle. */
+    cancel(): Promise<void>;
+    /** Attempt a paused Execution again, as `Execution.resume()`, then settle. */
+    resume(): Promise<void>;
+    /**
+     * Run the Workflow once more from its journal alone, as a restart does, and fail if it runs a Step
+     * again, diverges from the journal, or reaches another outcome.
+     */
+    replay(): Promise<void>;
+    /**
+     * The next time Step `id` completes, lose its result before the journal records it, as a crash
+     * between its effect and the journal does. The engine then retries the Step.
+     */
+    interruptAfter(id: string): void;
+}
+/** One entry of a run's journal. */
+export type TestJournalEntry = {
+    readonly kind: 'run';
+    readonly name: string;
+    readonly settled: boolean;
+    /**
+     * Times this entry's work ran, interruptions included; a replay runs it no more. Each retry of
+     * a Step is an entry of its own, after the wait its failure prescribes.
+     */
+    readonly attempts: number;
+    readonly value?: unknown;
+    readonly error?: unknown;
+} | {
+    readonly kind: 'sleep';
+    /** The wait's name, if it has one: `retry:` or `unavailable:` and what it retries. */
+    readonly name?: string;
+    readonly until: number;
+    readonly settled: boolean;
+} | {
+    readonly kind: 'signal';
+    readonly name: string;
+    readonly settled: boolean;
+    readonly value?: unknown;
+} | {
+    readonly kind: 'race';
+    readonly name: string;
+    readonly until: number;
+    readonly settled: boolean;
+    readonly outcome?: 'signal' | 'timeout' | 'cancelled';
+};
+/** Create an in-memory workflow engine for tests. */
+export declare function createTestWorkflowEngine(options?: TestWorkflowEngineOptions): TestWorkflowEngine;
+export {};