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

package/dist/platform/release/index.js

@@ -0,0 +1,27 @@
+/**
+ * Canonical `DomainRelease` v4 wire contract and admission owned by the Astrale platform: the
+ * document a deployment serves at `release.json`, its release digest and `ReleaseRef`.
+ */
+export * from '@astrale-os/kernel-protocol/release';
+/**
+ * The Kernel's Publication v2/v3 codec (`@astrale-os/kernel-protocol/release/legacy`): `accept`,
+ * `seal`, `encode`, `url`/`PATH`, the bundle helpers, `PublicationError` and Delivery v1, which
+ * stable targets and pre-v4 Kernels still serve and read.
+ *
+ * @deprecated Read and seal `DomainRelease` v4 with this module's root exports.
+ *
+ * Short-term consumers, which took it from the removed `@astrale-os/sdk/publication`:
+ * - cli `src/lib/domain-publication.ts` and its test (C1a: `accept`, `PATH`, `PublicationError`);
+ * - admin `domain/providers/http-publication/resolver.ts`,
+ *   `domain/providers/remote-kernel/instance-gateway.ts`,
+ *   `domain/providers/scaleway/machine-provider.ts`, `domain/scripts/admin-bootstrap/cli.ts`,
+ *   `domain/scripts/e2e/install-domain-set.ts`, their tests and two `worker/src` tests, which also
+ *   seal v2/v3 fixtures (A10a);
+ * - domains issues `tests/deployment/archived-errors.test.ts` (SV16).
+ *
+ * Removal, in a breaking SDK release: once those consumers no longer import it (the CLI and Admin
+ * read `release.json`), at the latest with the Kernel folder it re-exports, which the Kernel
+ * removes once no supported Kernel predates v4, no installation pins a v2/v3 document and no
+ * stable Worker serves one (D10).
+ */
+export { legacy } from '@astrale-os/kernel-protocol/release';

package/dist/platform/schema/index.d.ts

@@ -13,9 +13,10 @@ export { error } from './error.js';
 export type { DeclaredErrorDefinition, DeclaredErrorFamily } from './error.js';
 export { classIcon } from './class-icon.js';
 export type { ClassIcon } from './class-icon.js';
+export type { StoredPropertyInputOf } from './property-input.js';
 export type { CallablePolicyBuilder, CallablePolicyContext, CallableProjection, AuthoredMethodProjection, AuthoredPropertyProjection, ClassIdentityProjection, ClassOwnerProjection, CoreEdge, CoreEndpoint, CoreNode, DefinedSchema, DirectedEdgeClass, ClassReferenceProjection, ClassProjection, FunctionProjection, EdgeClass, Function, Method, MethodProjection, Lazy, NodeClass, Policy, PolicyExistsContext, PolicyNodeBinder, PolicyPatternContext, Property, PropertyProjection, ResolvedDomainOfInput, View, } from '@astrale-os/kernel-dsl/v1/builder';
 export type { Array, Object, Value } from '@astrale-os/kernel-dsl/value';
-export type { ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PolicyObjectRef, PropertyFacet, StateTopology, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';
+export type { CallableExecution, ClassKind, DirectedEdgeContract, EdgeClassPolicies, NodeClassDefinition, PolicyCheckObject, PolicyObjectRef, PropertyFacet, StateTopology, UndirectedEdgeContract, } from '@astrale-os/kernel-dsl/v1/language';
 export type { DomainSchema } from '@astrale-os/kernel-dsl/v1/schema';
 /** Kernel-owned Schema values used by authored product Schemas and graph operations. */
 export { AuthorityOperationOrder, AuthorityOperations, AuthorityRelations, KernelRootFunctions, OperationCore, operationOf, } from '@astrale-os/kernel-core/schema';

package/dist/platform/schema/property-input.d.ts

@@ -0,0 +1,15 @@
+import type { ResolvedPropertyCollection } from '@astrale-os/kernel-dsl/v1/language';
+type StoredValueOf<Property> = Property extends {
+    readonly __value?: infer Value;
+} ? Value : never;
+/** Values already held by graph Properties, including a blob's Ref rather than its write receipt. */
+export type StoredPropertyInputOf<Class> = Class extends {
+    readonly properties: infer Collection;
+} ? Collection extends {
+    readonly byKey: infer ByKey;
+} ? Readonly<{
+    [Key in keyof ByKey]?: StoredValueOf<ByKey[Key]>;
+} & {
+    [Name in Exclude<keyof Collection, keyof ResolvedPropertyCollection>]?: StoredValueOf<Collection[Name]>;
+}> : never : never;
+export {};

package/dist/platform/schema/property-input.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/schema/property.d.ts

@@ -3,6 +3,11 @@ import { type Property as CanonicalProperty, type ValueSchemaInput } from '@astr
 export interface PropertyOptions {
     readonly required?: boolean;
     readonly description?: string;
+    /**
+     * `create` freezes the value when its node or edge is created. `once` admits one write while the
+     * value is absent; neither can be changed or unset afterwards, only removed with the element.
+     */
+    readonly immutable?: 'create' | 'once';
 }
 /** Keep canonical generic inference: ordinary properties carry no state machine. */
 export type AuthoredProperty<Schema extends ValueSchemaInput, Options extends PropertyOptions = Record<never, never>> = CanonicalProperty<Schema, Options, never>;

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

@@ -0,0 +1,18 @@
+import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import { type Version } from './version.js';
+/**
+ * The highest stable, non-yanked version of a dependent Domain whose dependencies contain the target
+ * exactly, by origin and revision: the version to install beside that dependency. Semver is never a
+ * compatibility rule; only the exact revision a release was built against is.
+ */
+export declare function compatibleDependentVersion(index: readonly {
+    readonly version: Version;
+    readonly yanked: boolean;
+    readonly dependencies: readonly {
+        readonly origin: string;
+        readonly revision: Revision;
+    }[];
+}[], target: {
+    readonly origin: string;
+    readonly revision: Revision;
+}): Version | undefined;

package/dist/platform/versioning/dependents.js

@@ -0,0 +1,15 @@
+import semver from 'semver';
+import { isStable } from './version.js';
+/**
+ * The highest stable, non-yanked version of a dependent Domain whose dependencies contain the target
+ * exactly, by origin and revision: the version to install beside that dependency. Semver is never a
+ * compatibility rule; only the exact revision a release was built against is.
+ */
+export function compatibleDependentVersion(index, target) {
+    const compatible = index
+        .filter(({ version, yanked, dependencies }) => !yanked &&
+        isStable(version) &&
+        dependencies.some(({ origin, revision }) => origin === target.origin && revision === target.revision))
+        .map(({ version }) => version);
+    return semver.rsort(compatible)[0];
+}

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

@@ -0,0 +1,5 @@
+/** Semver policy of Domain versions, shared by `diff`, `publish` and install resolution. */
+export { compatibleDependentVersion } from './dependents.js';
+export { deploymentName } from './name.js';
+export { parseReference, resolveVersion, type Reference } from './reference.js';
+export { acceptVersion, baselineVersion, effectiveLevel, judgeVersion, minimumVersion, type BumpLevel, type PublishedVersion, type Version, type VersionVerdict, } from './version.js';

package/dist/platform/versioning/index.js

@@ -0,0 +1,5 @@
+/** Semver policy of Domain versions, shared by `diff`, `publish` and install resolution. */
+export { compatibleDependentVersion } from './dependents.js';
+export { deploymentName } from './name.js';
+export { parseReference, resolveVersion } from './reference.js';
+export { acceptVersion, baselineVersion, effectiveLevel, judgeVersion, minimumVersion, } from './version.js';

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

@@ -0,0 +1,38 @@
+import type { Digest } from '@astrale-os/kernel-protocol/artifact';
+/**
+ * The computed, never stored, name of one deployment. A version naming its release names it
+ * (`1.5.0`); a version naming its build elsewhere names it in its environment (`1.5.0 · staging`).
+ * Otherwise its recorded commit describes it from the last release tag, like `git describe` and Go
+ * pseudo-versions (`1.4.2 + 7 commits · a1b2c3d · staging`). A modified tree suffixes the commit
+ * token with `-dirty` and keeps the base and the environment (`a1b2c3d-dirty · staging`), as
+ * `git describe --dirty` does. When several published versions name one release or build, the
+ * highest that is not yanked names it, else the highest yanked one. Every name but a release's
+ * carries its environment, and listings print the name as returned, never shortened.
+ *
+ * The deployer declares the record and anyone may read it, so only the `DeploymentCommitV1` shape
+ * enters the name. A base enters only as a canonical version, the release tag without its `v` or
+ * `<component>-v` prefix, with a non-negative integer distance. A commit whose SHA is not 40
+ * hexadecimal digits names a plain preview, and the commit token is always printed in lower case,
+ * like `git describe`. An environment outside the `defineProject` grammar is rendered as `?`, so no
+ * record can put control characters or a ` · ` of its own in the name. Likewise only canonical
+ * published versions name a deployment. A deployment named without its digests (one whose record
+ * is not admitted) is never named by a published version.
+ */
+export declare function deploymentName(deployment: {
+    readonly environment: string;
+    readonly releaseDigest?: Digest;
+    readonly buildDigest?: Digest;
+    readonly commit: {
+        readonly sha: string;
+        readonly dirty: boolean;
+        readonly base?: {
+            readonly version: string;
+            readonly distance: number;
+        };
+    } | null;
+}, publications: readonly {
+    readonly version: string;
+    readonly releaseDigest: Digest;
+    readonly buildDigest: Digest;
+    readonly yanked: boolean;
+}[]): string;

package/dist/platform/versioning/name.js

@@ -0,0 +1,58 @@
+import semver from 'semver';
+import { ENVIRONMENT_NAME } from '../../deployment/environment.js';
+import { isVersion } from './version.js';
+/** A commit as `DeploymentCommitV1` records it: the full hexadecimal SHA-1, in either case. */
+const SHA = /^[0-9a-f]{40}$/iu;
+/** Stands for an environment outside the project environment-name grammar. */
+const UNKNOWN_ENVIRONMENT = '?';
+/**
+ * The computed, never stored, name of one deployment. A version naming its release names it
+ * (`1.5.0`); a version naming its build elsewhere names it in its environment (`1.5.0 · staging`).
+ * Otherwise its recorded commit describes it from the last release tag, like `git describe` and Go
+ * pseudo-versions (`1.4.2 + 7 commits · a1b2c3d · staging`). A modified tree suffixes the commit
+ * token with `-dirty` and keeps the base and the environment (`a1b2c3d-dirty · staging`), as
+ * `git describe --dirty` does. When several published versions name one release or build, the
+ * highest that is not yanked names it, else the highest yanked one. Every name but a release's
+ * carries its environment, and listings print the name as returned, never shortened.
+ *
+ * The deployer declares the record and anyone may read it, so only the `DeploymentCommitV1` shape
+ * enters the name. A base enters only as a canonical version, the release tag without its `v` or
+ * `<component>-v` prefix, with a non-negative integer distance. A commit whose SHA is not 40
+ * hexadecimal digits names a plain preview, and the commit token is always printed in lower case,
+ * like `git describe`. An environment outside the `defineProject` grammar is rendered as `?`, so no
+ * record can put control characters or a ` · ` of its own in the name. Likewise only canonical
+ * published versions name a deployment. A deployment named without its digests (one whose record
+ * is not admitted) is never named by a published version.
+ */
+export function deploymentName(deployment, publications) {
+    const { commit } = deployment;
+    const environment = typeof deployment.environment === 'string' && ENVIRONMENT_NAME.test(deployment.environment)
+        ? deployment.environment
+        : UNKNOWN_ENVIRONMENT;
+    const release = highest(publications.filter(({ releaseDigest }) => deployment.releaseDigest !== undefined && releaseDigest === deployment.releaseDigest));
+    if (release !== undefined)
+        return release;
+    const build = highest(publications.filter(({ buildDigest }) => deployment.buildDigest !== undefined && buildDigest === deployment.buildDigest));
+    if (build !== undefined)
+        return `${build} · ${environment}`;
+    if (commit === null || typeof commit.sha !== 'string' || !SHA.test(commit.sha)) {
+        return `preview · ${environment}`;
+    }
+    const sha = `${commit.sha.slice(0, 7).toLowerCase()}${commit.dirty === true ? '-dirty' : ''}`;
+    const base = describeBase(commit.base);
+    return base === undefined ? `${sha} · ${environment}` : `${base} · ${sha} · ${environment}`;
+}
+function describeBase(base) {
+    if (base === undefined || !isVersion(base.version))
+        return undefined;
+    const { version, distance } = base;
+    if (!Number.isSafeInteger(distance) || distance < 0)
+        return undefined;
+    return distance === 0 ? version : `${version} + ${distance} commit${distance === 1 ? '' : 's'}`;
+}
+function highest(publications) {
+    const versions = (yanked) => publications
+        .filter((publication) => publication.yanked === yanked && isVersion(publication.version))
+        .map(({ version }) => version);
+    return semver.rsort(versions(false))[0] ?? semver.rsort(versions(true))[0];
+}

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

@@ -0,0 +1,48 @@
+import { type PublishedVersion, type Version } from './version.js';
+/**
+ * One install reference. The syntax decides: a version goes to the registry, a deployment URL is
+ * installed as is, without any lookup.
+ */
+export type Reference = {
+    readonly kind: 'url';
+    readonly url: string;
+} | {
+    readonly kind: 'exact';
+    readonly origin: string;
+    readonly version: Version;
+} | {
+    readonly kind: 'line';
+    readonly origin: string;
+    readonly line: `${number}.${number}`;
+};
+/**
+ * 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 declare function parseReference(input: string): Reference;
+/**
+ * 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 declare function resolveVersion(published: readonly PublishedVersion[], reference: Exclude<Reference, {
+    kind: 'url';
+}>): {
+    readonly kind: 'resolved';
+    readonly version: Version;
+    readonly yanked: boolean;
+} | {
+    readonly kind: 'unresolved';
+    readonly reason: 'unknown-version' | 'no-stable-match' | 'yanked-only';
+};

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

@@ -2,7 +2,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 ||
@@ -16,7 +16,7 @@ export function admitProjectModule(loaded) {
     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(`astrale.config.ts exports the legacy deploy() aggregate; migrate the Domain 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;