@astrale-os/sdk 0.6.0-beta.0 → 0.6.0-beta.10

package/dist/execution/workflows/receiver.js

@@ -0,0 +1,99 @@
+import { workflowEngineDiscovery, WorkflowEngineUnavailable } from './discovery.js';
+import { durableRoute } from './route.js';
+import { durableHandlers } from './run.js';
+const MAXIMUM_ENDPOINTS = 256;
+/**
+ * Route `…/invoke/restate/<Kernel issuer>/<declaration key>/<service>/{discover,invoke/…}` to one
+ * engine endpoint. Retained services registered before issuer-prefixed paths keep their old
+ * `<declaration key>/<service>` route with explicit legacy signing keys. Canonical routes discover
+ * their signing authority at the named Kernel; that issuer also binds the run envelope. Each
+ * endpoint serves exactly that service with the declared Workflow. A declaration this Release does not
+ * serve durably is refused, so an endpoint never runs code it does not declare.
+ */
+export function createDurableReceiver(input) {
+    const executor = input.identity.executor;
+    if (executor === undefined) {
+        throw new TypeError('Durable Workflows require an execution Identity that can act as the Domain.');
+    }
+    const bound = executor.bind(input.identity);
+    const declared = new Map(input.workflows
+        .filter((workflow) => workflow.durable)
+        .map((workflow) => [workflow.callable.key, workflow]));
+    const endpoints = new Map();
+    const { engine } = input.serving;
+    const discovery = workflowEngineDiscovery(input.serving.fetch);
+    return Object.freeze({
+        async fetch(request) {
+            const route = durableRoute(request);
+            if (route === undefined)
+                return refused();
+            const { kernel, declaration, service } = route;
+            const workflow = declared.get(declaration);
+            if (workflow === undefined)
+                return refused();
+            let identityKeys = input.serving.identityKeys;
+            if (kernel !== undefined) {
+                try {
+                    identityKeys = (await discovery.resolve(kernel)).identity_keys;
+                }
+                catch (cause) {
+                    if (!(cause instanceof WorkflowEngineUnavailable))
+                        throw cause;
+                    return unavailable();
+                }
+            }
+            else if (identityKeys.length === 0)
+                return refused();
+            request.signal.throwIfAborted();
+            const cacheKey = JSON.stringify([kernel ?? null, declaration, service, identityKeys]);
+            let endpoint = endpoints.get(cacheKey);
+            if (endpoint === undefined) {
+                const definition = engine.workflow({
+                    name: service,
+                    handlers: durableHandlers({
+                        workflow,
+                        domain: input.domain,
+                        executor: bound,
+                        serving: input.serving,
+                        ...(kernel === undefined ? {} : { kernel }),
+                    }),
+                    options: {
+                        workflowRetention: input.serving.retentionMs,
+                        retryPolicy: input.serving.retryPolicy,
+                    },
+                });
+                try {
+                    endpoint = engine.createEndpointHandler({
+                        identityKeys: [...identityKeys],
+                        services: [definition],
+                    });
+                }
+                catch (cause) {
+                    if (kernel === undefined)
+                        throw cause;
+                    discovery.forget(kernel, identityKeys);
+                    return unavailable();
+                }
+                if (endpoints.size >= MAXIMUM_ENDPOINTS)
+                    endpoints.delete(endpoints.keys().next().value);
+                endpoints.set(cacheKey, endpoint);
+            }
+            const response = await endpoint(request);
+            if (kernel !== undefined && response.status === 401)
+                discovery.invalidate(kernel, identityKeys);
+            return response;
+        },
+    });
+}
+function refused() {
+    return new Response('{"error":"Unknown durable declaration."}', {
+        status: 404,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+}
+function unavailable() {
+    return new Response('{"error":"Workflow engine authority is unavailable."}', {
+        status: 503,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+}

package/dist/execution/workflows/route.d.ts

@@ -0,0 +1,14 @@
+import type { IssuerId } from '../../platform/auth/index.js';
+export interface DurableRoute {
+    readonly kernel?: IssuerId;
+    readonly declaration: string;
+    readonly service: string;
+}
+/** Whether the request is owned by the durable receiver, including malformed paths. */
+export declare function isDurableRequest(request: Request): boolean;
+/** Canonical requests discover authority at the HTTPS Kernel named by this admitted route. */
+export declare function isCanonicalDurableRequest(request: Request): boolean;
+/** Retained callbacks need explicit legacy signing authority before an engine module is loaded. */
+export declare function isLegacyDurableRequest(request: Request): boolean;
+/** One wire decoder shared by the receiver and platform lazy-load eligibility. */
+export declare function durableRoute(request: Request): DurableRoute | undefined;

package/dist/execution/workflows/route.js

@@ -0,0 +1,40 @@
+import { Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import { invocationPath } from '../../deployment/release/invocation.js';
+import { AuthValueError } from '../../platform/auth/index.js';
+import { httpIssuer } from '../identity/errors.js';
+const PREFIX = `${invocationPath()}/restate/`;
+const SERVICE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/u;
+/** Whether the request is owned by the durable receiver, including malformed paths. */
+export function isDurableRequest(request) {
+    return new URL(request.url).pathname.startsWith(PREFIX);
+}
+/** Canonical requests discover authority at the HTTPS Kernel named by this admitted route. */
+export function isCanonicalDurableRequest(request) {
+    return durableRoute(request)?.kernel !== undefined;
+}
+/** Retained callbacks need explicit legacy signing authority before an engine module is loaded. */
+export function isLegacyDurableRequest(request) {
+    const route = durableRoute(request);
+    return route !== undefined && route.kernel === undefined;
+}
+/** One wire decoder shared by the receiver and platform lazy-load eligibility. */
+export function durableRoute(request) {
+    const pathname = new URL(request.url).pathname;
+    if (!pathname.startsWith(PREFIX))
+        return undefined;
+    const parts = pathname.slice(PREFIX.length).split('/');
+    try {
+        const first = decodeURIComponent(parts[0] ?? '');
+        const kernel = Key.is(first) ? undefined : httpIssuer(first, false);
+        const declaration = kernel === undefined ? first : decodeURIComponent(parts[1] ?? '');
+        const service = parts[kernel === undefined ? 1 : 2] ?? '';
+        if (!Key.is(declaration) || !SERVICE.test(service))
+            return undefined;
+        return Object.freeze({ ...(kernel === undefined ? {} : { kernel }), declaration, service });
+    }
+    catch (cause) {
+        if (cause instanceof URIError || cause instanceof AuthValueError || cause instanceof TypeError)
+            return undefined;
+        throw cause;
+    }
+}

package/dist/execution/workflows/run.d.ts

@@ -0,0 +1,22 @@
+import type { RuntimeWorkflow } from '../../application/runtime/workflows.js';
+import type { IssuerId } from '../../platform/auth/index.js';
+import type { Domain } from '../../platform/schema/index.js';
+import type { Identity } from '../identity/index.js';
+import type { EngineSharedContext, EngineWorkflowContext } from './engine.js';
+import type { AdmittedDurableServing } from './options.js';
+type Executor = NonNullable<Identity['executor']>;
+export interface DurableRun {
+    readonly kernel?: IssuerId;
+    readonly workflow: RuntimeWorkflow;
+    readonly domain: Domain;
+    readonly executor: Executor;
+    readonly serving: AdmittedDurableServing;
+}
+/** Engine handlers of one durable Workflow: the `run` and the shared `signal`. */
+export declare function durableHandlers(input: DurableRun): Readonly<{
+    run: (context: EngineWorkflowContext, raw: unknown) => Promise<import("../../platform/schema/index.js").Value>;
+    signal(context: EngineSharedContext, raw: unknown): Promise<{
+        accepted: boolean;
+    }>;
+}>;
+export {};

package/dist/execution/workflows/run.js

@@ -0,0 +1,211 @@
+import { declaredErrorFactory } from '../../application/error/index.js';
+import { bindMutation } from '../../application/mutation/execution/executor.js';
+import { bindQuery } from '../../application/query/execution/executor.js';
+import { acceptStepId } from '../../application/workflow/step/index.js';
+import { acceptStepOutput } from '../../application/workflow/step/output.js';
+import { ResponseError } from '../../platform/client/index.js';
+import { bindSession, execution as executionMethods } from '../../platform/client/session/index.js';
+import { validateOutput } from '../invocation/result/index.js';
+import { decodeEnvelope } from './envelope.js';
+import { replayedFailure, terminalFailure } from './failure.js';
+/** Token of a Workflow that declares none. */
+const DEFAULT_COMPAT = '0';
+const MAXIMUM_SLEEP_MS = 365 * 24 * 60 * 60_000;
+const MAXIMUM_PROMISE_NAME = 128;
+/** Bounds of one `result` wait and of the durable pause between two of them. */
+const AWAIT_WAIT_MS = 10_000;
+const AWAIT_MAXIMUM_PAUSE_MS = 5 * 60_000;
+/** Engine handlers of one durable Workflow: the `run` and the shared `signal`. */
+export function durableHandlers(input) {
+    const { engine } = input.serving;
+    return Object.freeze({
+        run: (context, raw) => run(input, context, raw),
+        async signal(context, raw) {
+            const request = signalRequest(raw);
+            try {
+                await context.promise(request.name).resolve(request.value);
+                return { accepted: true };
+            }
+            catch (cause) {
+                // The engine refuses to resolve a promise twice with a terminal failure.
+                if (cause instanceof engine.TerminalError)
+                    return { accepted: false };
+                throw cause;
+            }
+        },
+    });
+}
+async function run(input, context, raw) {
+    const { workflow, serving } = input;
+    const { engine } = serving;
+    const definition = workflow.definition;
+    // Journaled first. A redeployment that changed the token cannot replay this run: it fails every
+    // attempt with this reason until the engine pauses it, then `resume` on compatible code or cancel.
+    const token = definition.compat ?? DEFAULT_COMPAT;
+    const recorded = await context.run('compat', async () => token);
+    if (recorded !== token) {
+        throw new Error(`Workflow ${workflow.address} started under compat token ${JSON.stringify(recorded)}; ` +
+            `this deployment declares ${JSON.stringify(token)}.`);
+    }
+    // Code that cannot read what the Kernel recorded pauses the run the same way.
+    const envelope = admitted(workflow, raw, input.kernel);
+    const durable = durableContext(input, context, envelope);
+    let output;
+    try {
+        output = await definition.run(durable);
+    }
+    catch (cause) {
+        throw terminalFailure(engine, cause, definition) ?? cause;
+    }
+    return validateOutput(workflow.callable, output);
+}
+function admitted(workflow, raw, kernel) {
+    const envelope = decodeEnvelope(raw);
+    if (kernel !== undefined && envelope.execution.kernel !== kernel) {
+        throw new TypeError('Durable envelope Kernel differs from its authenticated endpoint.');
+    }
+    const diagnostics = workflow.callable.validateInput(envelope.input);
+    if (diagnostics.length > 0) {
+        throw new TypeError(`Workflow ${workflow.address} cannot read the recorded input.`);
+    }
+    const instance = 'static' in workflow.callable && workflow.callable.static === false;
+    if (instance !== (envelope.execution.receiver !== undefined)) {
+        throw new TypeError(`Workflow ${workflow.address} cannot use the recorded receiver.`);
+    }
+    return envelope;
+}
+function durableContext(input, context, envelope) {
+    const { serving, domain, workflow } = input;
+    const { engine } = serving;
+    const definition = workflow.definition;
+    const execution = envelope.execution;
+    const signal = context.request().attemptCompletedSignal;
+    const steps = new Set();
+    /** One journaled unit of work acting as the Domain, with keys derived from its name. */
+    const journal = (name, execute) => Promise.resolve(context.run(name, async () => {
+        const deadline = Date.now() + serving.stepTimeoutMs;
+        const session = input.executor(execution.kernel, { deadline, signal });
+        try {
+            const kernel = keyed(bindSessionOf(session, deadline, signal), await keySequence(execution.id, name));
+            const output = await execute(Object.freeze({
+                kernel,
+                query: bindQuery(kernel, domain),
+                mutate: bindMutation(kernel, domain),
+            }));
+            try {
+                return acceptStepOutput(output);
+            }
+            catch (cause) {
+                throw new TypeError(`Workflow ${name} output must be portable.`, { cause });
+            }
+        }
+        catch (cause) {
+            throw terminalFailure(engine, cause, definition) ?? cause;
+        }
+        finally {
+            session.close();
+        }
+    })).catch((cause) => {
+        throw replayedFailure(engine, cause, definition) ?? cause;
+    });
+    const step = (id, execute) => {
+        let accepted;
+        try {
+            accepted = acceptStepId(id);
+            if (steps.has(accepted))
+                throw new TypeError(`Workflow Step ${accepted} occurs more than once.`);
+        }
+        catch (cause) {
+            return Promise.reject(cause);
+        }
+        steps.add(accepted);
+        return journal(`step:${accepted}`, execute);
+    };
+    return Object.freeze({
+        domain,
+        input: envelope.input,
+        execution,
+        error: declaredErrorFactory(definition),
+        step: Object.freeze({
+            run: step,
+            mutate: (id, mutation, value) => step(id, (authority) => authority.mutate(mutation, value)),
+        }),
+        async sleep(durationMs) {
+            if (!Number.isSafeInteger(durationMs) || durationMs < 0 || durationMs > MAXIMUM_SLEEP_MS) {
+                throw new TypeError(`Durable sleep must be an integer between 0 and ${MAXIMUM_SLEEP_MS} ms.`);
+            }
+            await context.sleep(durationMs);
+        },
+        async promise(name) {
+            if (typeof name !== 'string' || name.length === 0 || name.length > MAXIMUM_PROMISE_NAME) {
+                throw new TypeError('Durable promise name must have 1 to 128 characters.');
+            }
+            return (await context.promise(name).get());
+        },
+        cancelled: (error) => error instanceof engine.CancelledError,
+        async awaitExecution(target) {
+            for (let poll = 1;; poll++) {
+                const polled = await journal(`await:${target.id}:${poll}`, async ({ kernel }) => {
+                    try {
+                        const outcome = await kernel.invoke(executionMethods.result(target), {
+                            waitMs: Math.min(AWAIT_WAIT_MS, Math.floor(serving.stepTimeoutMs / 2)),
+                        });
+                        return { ended: true, outcome };
+                    }
+                    catch (cause) {
+                        if (cause instanceof ResponseError && cause.reason?.code === 'EXECUTION_PENDING') {
+                            return { ended: false };
+                        }
+                        throw cause;
+                    }
+                });
+                if (polled.ended)
+                    return polled.outcome;
+                await context.sleep(Math.min(AWAIT_MAXIMUM_PAUSE_MS, 1_000 * 2 ** Math.min(poll, 16)));
+            }
+        },
+        ...(execution.receiver === undefined ? {} : { self: execution.receiver }),
+    });
+}
+function bindSessionOf(session, deadline, signal) {
+    return bindSession(session, { deadline, signal });
+}
+/**
+ * Every `invoke` and Mutation of one Step without its own key carries the next key of the Step's
+ * sequence. The sequence restarts with every attempt, so a retried Step replays the same keys and
+ * the Kernel answers with the first outcome, or `IDEMPOTENCY_KEY_CONFLICT` if the request changed.
+ */
+function keyed(session, next) {
+    const invokeSource = session.invoke;
+    const mutateSource = session.mutate;
+    const invoke = ((reference, value, options) => invokeSource(reference, value, withKey(options, next)));
+    const mutate = ((author, options) => mutateSource(author, withKey(options, next)));
+    return Object.freeze({ ...session, invoke, mutate });
+}
+function withKey(options, next) {
+    if (options?.idempotencyKey !== undefined || options?.body !== undefined)
+        return options;
+    return { ...options, idempotencyKey: next() };
+}
+async function keySequence(execution, name) {
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(name)));
+    const prefix = `${execution}.${Array.from(digest.subarray(0, 12), hex).join('')}`;
+    let position = 0;
+    return () => `${prefix}.${++position}`;
+}
+function hex(byte) {
+    return byte.toString(16).padStart(2, '0');
+}
+function signalRequest(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        Array.isArray(input) ||
+        typeof input.name !== 'string') {
+        throw new TypeError('Durable signal request is invalid.');
+    }
+    const { name, value } = input;
+    if (name.length === 0 || name.length > MAXIMUM_PROMISE_NAME) {
+        throw new TypeError('Durable signal name must have 1 to 128 characters.');
+    }
+    return { name, value: value ?? null };
+}

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/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,37 @@
+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.
+ */
+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,57 @@
+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.
+ */
+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 }) => releaseDigest === deployment.releaseDigest));
+    if (release !== undefined)
+        return release;
+    const build = highest(publications.filter(({ buildDigest }) => 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';
+};