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

package/dist/deployment/adapter/adapter.d.ts

@@ -1,7 +1,7 @@
-import type { DeploymentSummaryV1, FrozenConfigurationV1 } from '../address/index.js';
+import type { FrozenConfigurationV1 } from '../address/index.js';
 import type { Bundler } from './bundle/index.js';
 import type { ArtifactSource, DeployContext, DeployResult, PrepareContext } from './legacy/index.js';
-import type { ConfigureContext, ListContext, Placement, PlacementContext, ReleaseDeployContext, ReleaseDeployResult, RetainContext } from './release/index.js';
+import type { ConfigureContext, ListContext, ListedDeployment, Placement, PlacementContext, ReleaseDeployContext, ReleaseDeployResult, RetainContext } from './release/index.js';
 /** What `admit` receives when `defineProject` binds an adapter to one Environment. */
 export interface AdapterEnvironmentContext {
     readonly environment: string;
@@ -32,8 +32,11 @@ export interface Adapter<Parameters extends object = object> {
     placement(parameters: Parameters, context: PlacementContext): Promise<Placement>;
     /** Create, or reuse, the immutable deployment of one sealed release. */
     deployRelease(parameters: Parameters, context: ReleaseDeployContext): Promise<ReleaseDeployResult>;
-    /** The deployments of one origin the host keeps for the caller. */
-    list?(parameters: Parameters, context: ListContext): Promise<readonly DeploymentSummaryV1[]>;
+    /**
+     * The deployments of one Environment of one origin the host keeps for the caller, each with
+     * where it is called. No effect at the host.
+     */
+    list?(parameters: Parameters, context: ListContext): Promise<readonly ListedDeployment[]>;
     /**
      * Keep one published deployment where the host has no registry principal to mark it (a platform
      * namespace). Called only after its Publication commits. Absent: the registry marks it (Admin's
@@ -61,7 +64,7 @@ export interface AdapterInput<Parameters extends object> {
     configure(parameters: Parameters, context: ConfigureContext): FrozenConfigurationV1;
     placement(parameters: Parameters, context: PlacementContext): Promise<Placement>;
     deployRelease(parameters: Parameters, context: ReleaseDeployContext): Promise<ReleaseDeployResult>;
-    list?(parameters: Parameters, context: ListContext): Promise<readonly DeploymentSummaryV1[]>;
+    list?(parameters: Parameters, context: ListContext): Promise<readonly ListedDeployment[]>;
     retain?(parameters: Parameters, context: RetainContext): Promise<void>;
     /** @deprecated Legacy direct-mode path (CT33) only. Replacement: `configure`, `placement`. */
     prepare?(parameters: Parameters, context: PrepareContext): Promise<ArtifactSource>;

package/dist/deployment/adapter/legacy/index.d.ts

@@ -8,14 +8,12 @@
  * created or reused, and installs nothing.
  *
  * Short-term consumers: the legacy direct-mode path (CT33), which `astrale-domain deploy` and
- * `astrale-domain dev` run through these operations:
- * - adapter-cloudflare direct mode (`route`, `workerName`, `identityIssuer`, `addressing`,
- *   `signingIdentity`, or no `namespace`), which serves the configurations of domains ai-gateway,
- *   closing, grc, integrations and issues (until SV15), domains organization (until it leaves
- *   direct mode, AM-147), the Services `beta` and `prod` (until SV12), `development` (until SV9)
- *   and frozen `admin-beta` (until D19) environments, shell (until SH2) and its frozen `legacy-v3`
- *   (until D22), and ui:domain (until UI1);
- * - adapter-astrale, until S8 gives it `deployRelease`.
+ * `astrale-domain dev` run through these operations: adapter-cloudflare direct mode (`route`,
+ * `workerName`, `identityIssuer`, `addressing`, `signingIdentity`, or no `namespace`), which serves
+ * the configurations of domains ai-gateway, closing, grc, integrations and issues (until SV15),
+ * domains organization (until it leaves direct mode, AM-147), the Services `beta` and `prod` (until
+ * SV12), `development` (until SV9) and frozen `admin-beta` (until D19) environments, shell (until
+ * SH2) and its frozen `legacy-v3` (until D22), and ui:domain (until UI1).
  *
  * Removal: D10, once no configuration on any repository's main selects the direct-mode path
  * (CT33, AM-147); it deletes these types with `prepare`/`deploy`, `src/deployment/release/legacy`

package/dist/deployment/adapter/release/context.d.ts

@@ -75,10 +75,16 @@ export interface ReleaseDeployContext {
     /** Parent-owned lifecycle cancellation shared by every provider effect. */
     readonly signal: AbortSignal;
 }
-/** What `list` receives: the origin whose deployments the host lists for the caller. */
+/**
+ * What `list` receives: the origin and the Environment whose deployments the host lists for the
+ * caller. It answers without any effect at the host.
+ */
 export interface ListContext {
     readonly origin: string;
+    readonly environment: string;
+    /** Parent-owned lifecycle cancellation. */
     readonly signal: AbortSignal;
+    /** Optional command-scoped identity override (`--as`). */
     readonly identity?: string;
 }
 /** What `retain` receives: the label of the published deployment to keep. */

package/dist/deployment/adapter/release/index.d.ts

@@ -1,2 +1,3 @@
 export type { ConfigureContext, ListContext, Placement, PlacementContext, ReleaseDeployContext, RetainContext, } from './context.js';
+export type { DeploymentCallTarget, ListedDeployment } from './list.js';
 export type { DeploymentSecretsState, FailedReleaseDeployResult, MutationKnowledge, ReadyReleaseDeployResult, ReleaseDeploymentPhase, ReleaseDeployResult, } from './result.js';

package/dist/deployment/adapter/release/list.d.ts

@@ -0,0 +1,41 @@
+import type { DeploymentSummaryV1 } from '../../address/index.js';
+/**
+ * Where one listed deployment is called on its host, so that an operator can act on that
+ * deployment alone, such as rotating one of its secrets in place (AM-4'):
+ *
+ * - `services`: a deployment Admin's Services hosts, called on the Admin instance with
+ *   `astrale call "<path>.method.setSecret" --admin` (`--admin=<admin>` when `admin` names the
+ *   Admin bookmark). `path` is the deployment's node, `@<id>`, qualified by its class:
+ *   `@<id>::services.astrale.ai:class.CloudflareDeployment`.
+ * - `namespace`: a deployment of a platform dispatch namespace, which has no Services node: the
+ *   namespace and the script the per-script tooling of that namespace takes.
+ */
+export type DeploymentCallTarget = {
+    readonly kind: 'services';
+    readonly path: string;
+    /** The Admin bookmark the deployment is reached through; the CLI's own Admin target when absent. */
+    readonly admin?: string;
+} | {
+    readonly kind: 'namespace';
+    readonly namespace: string;
+    readonly script: string;
+};
+/**
+ * One deployment as an adapter's `list` returns it: what its host knows of it, its record as the
+ * host stores it, and where it is called. `lastCallAt`, and a preview's `expiresAt`, are as of the
+ * listing: an adapter whose host records calls only now and then reads the calls counted since, and
+ * one that cannot read them for want of a permission omits both rather than print stale values.
+ *
+ * The adapter does not admit the record. The listing admits it with `acceptDeploymentRecord`, and a
+ * record it refuses (one a host on an older SDK still admits, say) never fails the listing: that
+ * deployment is listed from the facts its host owns.
+ */
+export interface ListedDeployment extends Omit<DeploymentSummaryV1, 'record'> {
+    /**
+     * The record as the host stores it, unadmitted, whatever value that is (JSON `null` included).
+     * Absent when the host keeps no record of the deployment: a platform namespace keeps none until
+     * it activates the deployment.
+     */
+    readonly record?: unknown;
+    readonly callTarget: DeploymentCallTarget;
+}

package/dist/deployment/adapter/release/list.js

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

package/dist/deployment/address/summary.d.ts

@@ -17,7 +17,7 @@ export interface DeploymentSummaryV1 {
     readonly retention: 'preview' | 'published';
     readonly createdAt: string;
     readonly lastCallAt?: string;
-    /** A preview's: 30 days after its creation or its last call, whichever is later. */
+    /** A preview's: 30 days after its activation or its last call, whichever is later (AM-123). */
     readonly expiresAt?: string;
     readonly retiredAt?: string;
     readonly retirement?: 'expired' | 'withdrawn';

package/dist/deployment/index.d.ts

@@ -1,5 +1,5 @@
 export { defineAdapter, defineDeployment, isAdapter } from './adapter/index.js';
-export type { Adapter, AdapterEnvironmentContext, AdapterInput, AddressingPlan, ArtifactFile, ArtifactSource, Bundle, BundleContext, Bundler, BundleSource, ConfigureContext, DeployContext, DeploymentPhase, DeploymentProgress, DeploymentSecretsState, DeployResult, FailedDeployResult, FailedReleaseDeployResult, LegacyAdapter, LegacyAdapterInput, ListContext, MutationKnowledge, Placement, PlacementContext, PreparedArtifact, PreparedArtifactFile, PrepareContext, ReadyDeployResult, ReadyReleaseDeployResult, ReleaseDeployContext, ReleaseDeploymentPhase, ReleaseDeployResult, RetainContext, } from './adapter/index.js';
+export type { Adapter, AdapterEnvironmentContext, AdapterInput, AddressingPlan, ArtifactFile, ArtifactSource, Bundle, BundleContext, Bundler, BundleSource, ConfigureContext, DeployContext, DeploymentCallTarget, DeploymentPhase, DeploymentProgress, DeploymentSecretsState, DeployResult, FailedDeployResult, FailedReleaseDeployResult, LegacyAdapter, LegacyAdapterInput, ListContext, ListedDeployment, MutationKnowledge, Placement, PlacementContext, PreparedArtifact, PreparedArtifactFile, PrepareContext, ReadyDeployResult, ReadyReleaseDeployResult, ReleaseDeployContext, ReleaseDeploymentPhase, ReleaseDeployResult, RetainContext, } from './adapter/index.js';
 export { compile, isBuild } from './build/index.js';
 export type { Build, BuildBundle, BuildDigest, BuildManifestV1, BuildSchema, } from './build/index.js';
 export { deploy } from './deploy.js';

package/dist/deployment/release/legacy/index.d.ts

@@ -8,8 +8,8 @@
  * seal the `DomainRelease` v4 of an immutable deployment from its build digest and URL.
  *
  * Short-term consumers:
- * - the direct-mode deploy path (`prepare`/`deploy` of adapter-cloudflare and adapter-astrale,
- *   whose `DeployResult.release` is this Release) and the stable Worker that assembles its Release
+ * - the direct-mode deploy path (`prepare`/`deploy` of adapter-cloudflare, whose
+ *   `DeployResult.release` is this Release) and the stable Worker that assembles its Release
  *   at runtime, which serve the direct-mode configurations of domains ai-gateway, closing, grc,
  *   integrations and issues (until SV15), domains organization (until it leaves direct mode,
  *   AM-147), the Services `beta` and `prod` (until SV12), `development` (until SV9) and frozen

package/dist/deployment/release/legacy/index.js

@@ -8,8 +8,8 @@
  * seal the `DomainRelease` v4 of an immutable deployment from its build digest and URL.
  *
  * Short-term consumers:
- * - the direct-mode deploy path (`prepare`/`deploy` of adapter-cloudflare and adapter-astrale,
- *   whose `DeployResult.release` is this Release) and the stable Worker that assembles its Release
+ * - the direct-mode deploy path (`prepare`/`deploy` of adapter-cloudflare, whose
+ *   `DeployResult.release` is this Release) and the stable Worker that assembles its Release
  *   at runtime, which serve the direct-mode configurations of domains ai-gateway, closing, grc,
  *   integrations and issues (until SV15), domains organization (until it leaves direct mode,
  *   AM-147), the Services `beta` and `prod` (until SV12), `development` (until SV9) and frozen

package/dist/deployment/verify/readiness/legacy/publication.d.ts

@@ -6,7 +6,7 @@ import type { ReadinessOptions } from '../fetch.js';
  *
  * @deprecated Replacement: `verifyRelease`, the readiness of an immutable deployment at
  * `release.json` (release digest and build digest). Consumer: the direct-mode deploy path of
- * adapter-cloudflare and adapter-astrale (the consumers of `deployment/release/legacy/index.ts`).
+ * adapter-cloudflare (the consumers of `deployment/release/legacy/index.ts`).
  * Removal: D10, with that path.
  */
 export declare function verifyPublication(release: legacy.Release, options?: ReadinessOptions): Promise<publication.Publication>;

package/dist/deployment/verify/readiness/legacy/publication.js

@@ -5,7 +5,7 @@ import { bounded, fetchRequired, MAXIMUM_BUNDLE_BYTES, MAXIMUM_DOCUMENT_BYTES, t
  *
  * @deprecated Replacement: `verifyRelease`, the readiness of an immutable deployment at
  * `release.json` (release digest and build digest). Consumer: the direct-mode deploy path of
- * adapter-cloudflare and adapter-astrale (the consumers of `deployment/release/legacy/index.ts`).
+ * adapter-cloudflare (the consumers of `deployment/release/legacy/index.ts`).
  * Removal: D10, with that path.
  */
 export async function verifyPublication(release, options = {}) {

package/dist/execution/identity/authentication.d.ts

@@ -5,6 +5,7 @@ import type { InvocationAdmissionInput } from '../invocation/index.js';
 import type { IdentityNetworkPolicy, VerificationBasis, VerificationBasisResolver } from './jwks.js';
 import type { SigningMaterial } from './signing.js';
 import { ClientSession } from '../../platform/client/session/index.js';
+import { NodeId } from '../../platform/graph/node/index.js';
 /**
  * How long a callback Session reuses a learned route. It stays at most the Kernel's in-flight
  * issuer window (`KERNEL_INFLIGHT_ISSUER_MS`, Host default 300 s; CT11): a route learned to a
@@ -26,10 +27,13 @@ export declare function authenticate(credentialInput: CredentialInput, expectedK
     readonly signal: AbortSignal;
 }, configuration: AuthenticationConfiguration): Promise<AuthenticatedInvocation>;
 /**
- * The Domain's own authority toward one Kernel, for work no caller credential carries: a durable
- * run acts as its executor, never as its initiator. The caller owns the returned Session.
+ * The Domain's own authority toward one Kernel for a step of the durable Execution `executionId`,
+ * which no caller credential carries: the run acts as its executor, never as its initiator. Every
+ * credential names `executionId` in `EXECUTION_CLAIM`, so the Kernel can accept a replaced issuer
+ * for the steps of a run in flight at a consented issuer change. The caller owns the returned
+ * Session.
  */
-export declare function executorSession(kernel: IssuerId, execution: {
+export declare function executorSession(kernel: IssuerId, executionId: NodeId, execution: {
     readonly deadline: number;
     readonly signal: AbortSignal;
 }, configuration: AuthenticationConfiguration): ClientSession;

package/dist/execution/identity/authentication.js

@@ -79,16 +79,19 @@ export async function authenticate(credentialInput, expectedKernel, execution, c
     });
 }
 /**
- * The Domain's own authority toward one Kernel, for work no caller credential carries: a durable
- * run acts as its executor, never as its initiator. The caller owns the returned Session.
+ * The Domain's own authority toward one Kernel for a step of the durable Execution `executionId`,
+ * which no caller credential carries: the run acts as its executor, never as its initiator. Every
+ * credential names `executionId` in `EXECUTION_CLAIM`, so the Kernel can accept a replaced issuer
+ * for the steps of a run in flight at a consented issuer change. The caller owns the returned
+ * Session.
  */
-export function executorSession(kernel, execution, configuration) {
+export function executorSession(kernel, executionId, execution, configuration) {
     const admitted = httpIssuer(kernel, configuration.policy.allowInsecureHttp === true);
     admitEndpoint(invocationUrl(admitted), configuration.policy);
-    return callbackSession(admitted, selfIdentity, undefined, execution, configuration);
+    return callbackSession(admitted, selfIdentity, undefined, execution, configuration, executionId);
 }
-function callbackSession(kernel, expression, carrier, execution, configuration) {
-    const resolveCallback = createCallbackCredentialResolver(configuration.signing, configuration.issuer, configuration.subject, kernel, expression, carrier, execution);
+function callbackSession(kernel, expression, carrier, execution, configuration, executionId) {
+    const resolveCallback = createCallbackCredentialResolver(configuration.signing, configuration.issuer, configuration.subject, kernel, expression, carrier, execution, executionId);
     return new ClientSession({
         kernel,
         fetch: boundedFetch(configuration.fetch, execution.signal),

package/dist/execution/identity/callback.d.ts

@@ -1,4 +1,5 @@
 import type { IssuerId, UnresolvedIdentityExpr, VerifiedCredential } from '../../platform/auth/index.js';
+import type { NodeId } from '../../platform/graph/node/index.js';
 import type { SigningMaterial } from './signing.js';
 export declare const maximumCallbackTtlSeconds = 120;
 export declare const maximumCallbackDelegationTtlSeconds = 60;
@@ -34,9 +35,11 @@ export declare function signCallback(signing: SigningMaterial, issuer: IssuerId,
 }): Promise<string>;
 /**
  * Reuse one exact callback authority partition, refreshing only near its bounded expiry. Without a
- * carrier the callback is the Domain's own authority, bounded by the execution alone.
+ * carrier the callback is the Domain's own authority, bounded by the execution alone. An
+ * `executionId` is the durable Execution a step's executor credential names in `EXECUTION_CLAIM`;
+ * no caller-bound callback names one.
  */
 export declare function createCallbackCredentialResolver(signing: SigningMaterial, issuer: IssuerId, subject: string, audience: IssuerId, expression: UnresolvedIdentityExpr, carrier: VerifiedCredential | undefined, execution: {
     readonly deadline: number;
     readonly signal: AbortSignal;
-}): (signal: AbortSignal) => Promise<SignedCallback>;
+}, executionId?: NodeId): (signal: AbortSignal) => Promise<SignedCallback>;

package/dist/execution/identity/callback.js

@@ -1,3 +1,4 @@
+import { EXECUTION_CLAIM } from '@astrale-os/kernel-protocol/issuer/claims';
 import { SignJWT } from 'jose';
 import { protocolError } from '../invocation/result/index.js';
 import { requireLive } from './errors.js';
@@ -22,9 +23,11 @@ export async function signCallback(signing, issuer, subject, audience, expressio
 }
 /**
  * Reuse one exact callback authority partition, refreshing only near its bounded expiry. Without a
- * carrier the callback is the Domain's own authority, bounded by the execution alone.
+ * carrier the callback is the Domain's own authority, bounded by the execution alone. An
+ * `executionId` is the durable Execution a step's executor credential names in `EXECUTION_CLAIM`;
+ * no caller-bound callback names one.
  */
-export function createCallbackCredentialResolver(signing, issuer, subject, audience, expression, carrier, execution) {
+export function createCallbackCredentialResolver(signing, issuer, subject, audience, expression, carrier, execution, executionId) {
     const maximum = carrier?.exp ?? Number.POSITIVE_INFINITY;
     let cached;
     let pending;
@@ -37,7 +40,7 @@ export function createCallbackCredentialResolver(signing, issuer, subject, audie
             return cached;
         }
         if (pending === undefined) {
-            const current = sign(signing, issuer, subject, audience, expression, execution, maximum).then((signed) => {
+            const current = sign(signing, issuer, subject, audience, expression, execution, maximum, executionId).then((signed) => {
                 const delegateTtlSeconds = Math.min(maximumCallbackDelegationTtlSeconds, signed.expiresAt - signed.issuedAt - CALLBACK_DELEGATION_SKEW_SECONDS);
                 if (delegateTtlSeconds < 1) {
                     throw protocolError('AUTH_INVALID', 'Credential is invalid.');
@@ -60,7 +63,7 @@ export function createCallbackCredentialResolver(signing, issuer, subject, audie
         return withSignal(pending, signal);
     };
 }
-async function sign(signing, issuer, subject, audience, expression, execution, maximum = Number.POSITIVE_INFINITY) {
+async function sign(signing, issuer, subject, audience, expression, execution, maximum = Number.POSITIVE_INFINITY, executionId) {
     requireLive(execution);
     const privateKey = await withSignal(signing.privateKey, execution.signal);
     requireLive(execution);
@@ -69,7 +72,10 @@ async function sign(signing, issuer, subject, audience, expression, execution, m
     if (!Number.isFinite(expiresAt) || expiresAt <= now) {
         throw protocolError('AUTH_INVALID', 'Credential is invalid.');
     }
-    const credential = await withSignal(new SignJWT({ grant: { v: 1, expr: expression } })
+    const credential = await withSignal(new SignJWT({
+        grant: { v: 1, expr: expression },
+        ...(executionId === undefined ? {} : { [EXECUTION_CLAIM]: executionId }),
+    })
         .setProtectedHeader({
         alg: signing.algorithm,
         ...(signing.keyId === undefined ? {} : { kid: signing.keyId }),

package/dist/execution/identity/identity.d.ts

@@ -3,6 +3,7 @@ import type * as releaseProtocol from '@astrale-os/kernel-protocol/release';
 import type { Issuer, exchange, release } from '@astrale-os/kernel-server';
 import type { IssuerId, JsonWebKey } from '../../platform/auth/index.js';
 import type { ClientSession } from '../../platform/client/session/index.js';
+import type { NodeId } from '../../platform/graph/node/index.js';
 import type { InvocationAuthority } from '../invocation/index.js';
 import type { ExchangeOptions } from './exchange.js';
 import type { IdentityNetworkPolicy } from './jwks.js';
@@ -16,10 +17,11 @@ export interface Identity extends Issuer, InvocationAuthority {
      */
     delivery(served: releaseProtocol.DomainRelease | releaseProtocol.legacy.Publication): release.delivery.Provider;
     /**
-     * The Domain's own authority toward one Kernel for work no caller credential carries, such as a
-     * durable run. Required to serve durable Workflows; the caller closes the Session.
+     * The Domain's own authority toward one Kernel for a step of the durable Execution `executionId`
+     * (`ctx.execution.id`), which no caller credential carries; its credentials name `executionId` in
+     * `EXECUTION_CLAIM`. Required to serve durable Workflows; the caller closes the Session.
      */
-    executor?(kernel: IssuerId, execution: {
+    executor?(kernel: IssuerId, executionId: NodeId, execution: {
         readonly deadline: number;
         readonly signal: AbortSignal;
     }): ClientSession;

package/dist/execution/identity/identity.js

@@ -51,7 +51,7 @@ export function createIdentity(input) {
         ...(exchangeProvider === undefined ? {} : { tokenExchange: exchangeProvider }),
         delivery: (served) => releaseDelivery(material, issuer, input.subject, served),
         admit: (request) => admit(request, configuration),
-        executor: (kernel, execution) => executorSession(kernel, execution, configuration),
+        executor: (kernel, executionId, execution) => executorSession(kernel, executionId, execution, configuration),
         authenticate: (request) => authenticate(request.credential, request.via.issuer, request.context.execution, configuration),
     });
 }

package/dist/execution/workflows/run.js

@@ -84,7 +84,7 @@ function durableContext(input, context, envelope) {
     /** 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 });
+        const session = input.executor(execution.kernel, execution.id, { deadline, signal });
         try {
             const kernel = keyed(bindSessionOf(session, deadline, signal), await keySequence(execution.id, name));
             const output = await execute(Object.freeze({

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

@@ -15,12 +15,13 @@ import type { Digest } from '@astrale-os/kernel-protocol/artifact';
  * 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.
+ * 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 releaseDigest?: Digest;
+    readonly buildDigest?: Digest;
     readonly commit: {
         readonly sha: string;
         readonly dirty: boolean;

package/dist/platform/versioning/name.js

@@ -21,17 +21,18 @@ const UNKNOWN_ENVIRONMENT = '?';
  * 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.
+ * 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 }) => releaseDigest === deployment.releaseDigest));
+    const release = highest(publications.filter(({ releaseDigest }) => deployment.releaseDigest !== undefined && releaseDigest === deployment.releaseDigest));
     if (release !== undefined)
         return release;
-    const build = highest(publications.filter(({ buildDigest }) => buildDigest === deployment.buildDigest));
+    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)) {

package/dist/project/define.js

@@ -4,8 +4,10 @@ import { ENVIRONMENT_NAME } from '../deployment/environment.js';
 import { isTests } from '../testing/index.js';
 import { installCommand } from './install-command.js';
 const admittedProjects = new WeakSet();
-/** The adapter name of adapter-astrale, whose instance mode once read `installation`. */
+/** The adapter name of adapter-astrale, whose removed instance mode once read `installation`. */
 const ASTRALE_ADAPTER = 'astrale';
+/** The one Environment adapter-astrale deploys without an explicit organisation (AM-7). */
+const ASTRALE_DEFAULT_ORGANIZATION_ENVIRONMENT = 'development';
 /** Capture one inert Project definition without loading entrypoints or performing effects. */
 export function defineProject(input) {
     const value = record(input, 'Project definition');
@@ -80,10 +82,10 @@ function admitEntrypoints(input) {
  * `installation` is refused before any effect, with the commands that replace it. Its only
  * consumer pins an SDK older than this refusal.
  *
- * adapter-astrale took its Services instance, and the identity of its Services calls, from
- * `installation` when `astrale({ instance })` named none. For such an Environment the guidance
- * also moves the instance into the adapter and passes the identity to the deploy, so following
- * it deploys exactly where and as the configuration did.
+ * adapter-astrale deploys on Admin's Services, never through the installation's instance: outside
+ * development its Environment also names the organisation that holds its deployment line (AM-7),
+ * which the guidance adds when the adapter names none. The installation's instance and identity
+ * move to the install command.
  */
 function installationRefusal(environment, name) {
     const declared = environment.installation;
@@ -97,15 +99,14 @@ function installationRefusal(environment, name) {
     const instance = stable(installation.instance);
     const identity = stable(installation.identity);
     const deployment = environment.deployment;
-    const astrale = isDeployment(deployment) &&
+    const organization = isDeployment(deployment) &&
         deployment.adapter.name === ASTRALE_ADAPTER &&
-        deployment.parameters.instance === undefined;
-    const adapterInstance = astrale
-        ? `, name its instance in \`astrale({ instance: '${instance ?? '<instance>'}' })\``
+        name !== ASTRALE_DEFAULT_ORGANIZATION_ENVIRONMENT &&
+        deployment.parameters.organization === undefined
+        ? ", name the organisation that holds its deployment line in `astrale({ organization: '<Identity id>' })`"
         : '';
-    const deployIdentity = astrale && identity !== undefined ? ` --as ${identity}` : '';
     return (`Project Environment ${name} declares installation, and a deploy no longer installs. ` +
-        `Remove \`installation\`${adapterInstance}, run \`astrale-domain deploy ${name}${deployIdentity}\`, ` +
+        `Remove \`installation\`${organization}, 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. */

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

@@ -1,5 +1,5 @@
 import type { LintReportFormat } from '../linter/index.js';
-export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
+export declare const COMMANDS: readonly ['dev', 'build', 'deploy', 'list', 'test', 'lint', 'package', 'upgrade'];
 export type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
     readonly command: Command;

package/dist/tooling/cli/arguments.js

@@ -1,6 +1,15 @@
 import { isAbsolute, normalize } from 'node:path';
 import { installCommand } from '../../project/install-command.js';
-export const COMMANDS = ['dev', 'build', 'deploy', 'test', 'lint', 'package', 'upgrade'];
+export const COMMANDS = [
+    'dev',
+    'build',
+    'deploy',
+    'list',
+    'test',
+    'lint',
+    'package',
+    'upgrade',
+];
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
@@ -66,8 +75,8 @@ export function parseArgs(argv) {
     }
     if (fix && command !== 'lint')
         throw new Error('`--fix` is only valid for `lint`.');
-    if (json && command !== 'build' && command !== 'deploy') {
-        throw new Error('`--json` is only valid for `build` or `deploy`.');
+    if (json && command !== 'build' && command !== 'deploy' && command !== 'list') {
+        throw new Error('`--json` is only valid for `build`, `deploy` or `list`.');
     }
     if (format !== undefined && command !== 'lint') {
         throw new Error('`--format` is only valid for `lint`.');
@@ -80,13 +89,15 @@ export function parseArgs(argv) {
     }
     if (deployOnly && command !== 'dev' && command !== 'deploy')
         refuseDeployOnly(undefined);
-    if (identity !== undefined && command !== 'dev' && command !== 'deploy') {
-        throw new Error('`--as` is only valid for `dev` or `deploy`.');
+    if (identity !== undefined && command !== 'dev' && command !== 'deploy' && command !== 'list') {
+        throw new Error('`--as` is only valid for `dev`, `deploy` or `list`.');
     }
-    if (environment !== undefined && command !== 'dev' && command !== 'deploy') {
-        if (command !== 'test') {
-            throw new Error('`--environment` is only valid for `dev`, `deploy`, or `test`.');
-        }
+    if (environment !== undefined &&
+        command !== 'dev' &&
+        command !== 'deploy' &&
+        command !== 'list' &&
+        command !== 'test') {
+        throw new Error('`--environment` is only valid for `dev`, `deploy`, `list` or `test`.');
     }
     if (suite !== undefined && command !== 'test') {
         throw new Error('`--suite` is only valid for `test`.');
@@ -116,6 +127,17 @@ export function parseArgs(argv) {
                 ...(secretsFile === undefined ? {} : { secretsFile }),
             };
         }
+        case 'list':
+            // Every Environment of the Project, or the one `--environment` names.
+            if (positionals.length > 0) {
+                throw new Error('`list` does not accept positional arguments; use `--environment`.');
+            }
+            return {
+                command: 'list',
+                env: environment ?? '',
+                ...(json ? { json: true } : {}),
+                ...(identity === undefined ? {} : { identity }),
+            };
         case 'build':
         case 'package':
             if (positionals.length > 0) {

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

@@ -5,7 +5,7 @@ import type { LoadedEnvironment } from './project.js';
  * that mode still has a consumer (AM-16, AM-72).
  *
  * - `canonical`: an immutable deployment of one sealed release through the adapter's
- *   `deployRelease`, with a key generated for it, and zero Kernel calls.
+ *   `deployRelease`, with a key generated for it, and no call to any instance.
  * - `legacy-direct`: today's stable target, replaced in place through `prepare` and `deploy`, which
  *   serves a v3 Publication only. Its `reasons` name what selected it.
  * - `refused`: a shape no deploy of this SDK serves, refused before any effect. Each refusal
@@ -35,10 +35,7 @@ export type LegacyDirectReason =
  | {
     readonly reason: 'no-namespace';
 }
-/**
- * An adapter that declares no `deployRelease` (the contract before adapter interface v2),
- * adapter-astrale's instance mode among them until adapter-astrale implements it.
- */
+/** An adapter that declares no `deployRelease`: the contract before adapter interface v2. */
  | {
     readonly reason: 'no-deploy-release';
 };
@@ -54,13 +51,12 @@ export type DeployModeCommand = 'deploy' | 'dev';
  * Select the deploy mode of one Environment (CT33). It reads the configuration and the command
  * only, and has no effect.
  *
- * A refusal wins over every other reason. Once adapter-astrale deploys immutable deployments
- * (`deployRelease`), its `instance` and `signingIdentity` are refused before any effect: their one
- * consumer pins an older SDK (AM-72). Until then they select its instance mode, on the legacy path
- * with every adapter that declares no `deployRelease`. Otherwise the Environment is on the legacy
- * direct-mode path when adapter-cloudflare names a direct-mode parameter or no `namespace`, or
- * when its adapter declares no `deployRelease`. Everything else is canonical, except under `dev`,
- * which serves the legacy direct-mode path only.
+ * A refusal wins over every other reason. adapter-astrale deploys immutable deployments only
+ * (`deployRelease`): its removed instance mode's `instance` and `signingIdentity` are refused
+ * before any effect, since their one consumer pins an older SDK (AM-72). Otherwise the Environment
+ * is on the legacy direct-mode path when adapter-cloudflare names a direct-mode parameter or no
+ * `namespace`, or when its adapter declares no `deployRelease`. Everything else is canonical,
+ * except under `dev`, which serves the legacy direct-mode path only.
  *
  * Within canonical adapter-cloudflare (with `namespace`), a direct-mode parameter is refused
  * rather than silently selecting either mode, and so is `wrangler.triggers`: an immutable