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

package/dist/deployment/worker/response.js

@@ -0,0 +1,213 @@
+import { parseDeploymentLabel } from '../address/label.js';
+import { serviceName } from './address.js';
+import { decodeWorkerRecord } from './record.js';
+export const WORKER_DEPLOYMENT_REJECTIONS = Object.freeze([
+    'invalid-deployment',
+    'address-mismatch',
+    'build-mismatch',
+    'service-owned-elsewhere',
+    'deployment-conflict',
+    'deployment-retired',
+    'hosting-unavailable',
+    'service-unavailable',
+]);
+const STATES = Object.freeze([
+    'deploying',
+    'active',
+    'retiring',
+    'retired',
+    'failed',
+]);
+/** Which secret states each deployment state reports. */
+const SECRETS_BY_STATE = Object.freeze({
+    created: Object.freeze(['bound']),
+    reused: Object.freeze(['updated', 'unchanged']),
+});
+/**
+ * Admit the answer of a host's `hosting`: its routing domain. The `addressing: 'opaque'` an older
+ * Services answers beside it is admitted and dropped: every Service name is opaque.
+ */
+export function decodeWorkerHosting(input) {
+    const value = exact(input, ['routingDomain'], ['addressing'], 'hosting');
+    if (typeof value.routingDomain !== 'string' || !isDnsName(value.routingDomain)) {
+        invalid('hosting', 'routingDomain');
+    }
+    if (value.addressing !== undefined && value.addressing !== 'opaque') {
+        invalid('hosting', 'addressing');
+    }
+    return Object.freeze({ routingDomain: value.routingDomain });
+}
+/**
+ * Admit the answer of a deploy exactly: a deployment whose state reports the secret state it
+ * pairs with, or a refusal a host can give.
+ */
+export function decodeWorkerDeploymentResponse(input) {
+    const value = exact(input, ['kind'], ['state', 'secrets', 'deployment', 'reason', 'message', 'retryAfter'], 'deploy');
+    if (value.kind === 'rejected') {
+        exact(value, ['kind', 'reason', 'message'], ['retryAfter'], 'refusal');
+        if (!WORKER_DEPLOYMENT_REJECTIONS.includes(value.reason)) {
+            invalid('refusal', 'reason');
+        }
+        if (typeof value.message !== 'string' ||
+            value.message.length < 1 ||
+            value.message.length > 500) {
+            invalid('refusal', 'message');
+        }
+        if (value.retryAfter !== undefined && !isInstant(value.retryAfter)) {
+            invalid('refusal', 'retryAfter');
+        }
+        return Object.freeze({
+            kind: 'rejected',
+            reason: value.reason,
+            message: value.message,
+            ...(value.retryAfter === undefined ? {} : { retryAfter: value.retryAfter }),
+        });
+    }
+    exact(value, ['kind', 'state', 'secrets', 'deployment'], [], 'deploy');
+    if (value.kind !== 'deployed')
+        invalid('deploy', 'kind');
+    if (value.state !== 'created' && value.state !== 'reused')
+        invalid('deploy', 'state');
+    const secrets = exact(value.secrets, ['state'], [], 'secrets');
+    const allowed = SECRETS_BY_STATE[value.state];
+    if (typeof secrets.state !== 'string' || !allowed.includes(secrets.state)) {
+        invalid('deploy', 'secrets.state');
+    }
+    return Object.freeze({
+        kind: 'deployed',
+        state: value.state,
+        secrets: Object.freeze({ state: secrets.state }),
+        deployment: decodeWorkerDeploymentSummary(value.deployment),
+    });
+}
+/** Admit the answer of a host's `list`: the summaries of the caller's deployments, in its order. */
+export function decodeWorkerDeploymentList(input) {
+    const value = exact(input, ['deployments'], [], 'list');
+    if (!Array.isArray(value.deployments))
+        invalid('list', 'deployments');
+    return Object.freeze(value.deployments.map((deployment) => decodeWorkerDeploymentSummary(deployment)));
+}
+/**
+ * Admit one summary exactly: node ids and names a person can read, a label whose first part is
+ * the Service's name, the URL of that label, a known state, instants, digests, and a record that
+ * decodes.
+ */
+export function decodeWorkerDeploymentSummary(input) {
+    const value = exact(input, [
+        'id',
+        'url',
+        'label',
+        'serviceId',
+        'service',
+        'project',
+        'environment',
+        'owner',
+        'state',
+        'current',
+        'createdAt',
+        'buildDigest',
+        'configuration',
+    ], ['retiredAt', 'signingKeyId', 'record'], 'deployment');
+    for (const key of [
+        'id',
+        'url',
+        'label',
+        'serviceId',
+        'service',
+        'project',
+        'environment',
+        'owner',
+    ]) {
+        if (typeof value[key] !== 'string' || !isPrintable(value[key]))
+            invalid('deployment', key);
+    }
+    if (value.signingKeyId !== undefined) {
+        if (typeof value.signingKeyId !== 'string' || !isPrintable(value.signingKeyId)) {
+            invalid('deployment', 'signingKeyId');
+        }
+    }
+    let line;
+    try {
+        line = parseDeploymentLabel(value.label).line;
+    }
+    catch {
+        invalid('deployment', 'label');
+    }
+    if (value.service !== line)
+        invalid('deployment', 'service');
+    let named;
+    try {
+        named = serviceName(value.project, value.environment);
+    }
+    catch {
+        invalid('deployment', 'project');
+    }
+    if (named !== line)
+        invalid('deployment', 'service');
+    if (!isDeploymentUrl(value.url, value.label))
+        invalid('deployment', 'url');
+    if (!STATES.includes(value.state))
+        invalid('deployment', 'state');
+    if (typeof value.current !== 'boolean')
+        invalid('deployment', 'current');
+    if (!isInstant(value.createdAt))
+        invalid('deployment', 'createdAt');
+    if (value.retiredAt !== undefined && !isInstant(value.retiredAt))
+        invalid('deployment', 'retiredAt');
+    for (const key of ['buildDigest', 'configuration']) {
+        if (typeof value[key] !== 'string' || !/^sha256:[0-9a-f]{64}$/u.test(value[key])) {
+            invalid('deployment', key);
+        }
+    }
+    let record;
+    if (value.record !== undefined) {
+        try {
+            record = decodeWorkerRecord(value.record);
+        }
+        catch {
+            invalid('deployment', 'record');
+        }
+    }
+    const summary = { ...value };
+    delete summary.record;
+    return Object.freeze({
+        ...summary,
+        ...(record === undefined ? {} : { record }),
+    });
+}
+/** `https://<label>.<routing domain>`, nothing more. */
+function isDeploymentUrl(url, label) {
+    const prefix = `https://${label}.`;
+    return url.startsWith(prefix) && isDnsName(url.slice(prefix.length));
+}
+/** Text a person can read in a listing: at most 512 characters, none of them a control character. */
+function isPrintable(value) {
+    return value.length > 0 && value.length <= 512 && !/[\p{Cc}]/u.test(value);
+}
+function isInstant(value) {
+    return (typeof value === 'string' &&
+        value.length > 0 &&
+        value.length <= 64 &&
+        !Number.isNaN(Date.parse(value)));
+}
+function isDnsName(value) {
+    return (value.length <= 253 &&
+        value.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(label)));
+}
+function exact(input, required, optional, label) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        invalid(label);
+    const value = input;
+    for (const key of Reflect.ownKeys(value)) {
+        if (typeof key !== 'string' || (!required.includes(key) && !optional.includes(key))) {
+            invalid(label, String(key));
+        }
+    }
+    for (const key of required)
+        if (!Object.hasOwn(value, key))
+            invalid(label, key);
+    return value;
+}
+function invalid(label, member) {
+    throw new TypeError(`The Worker host returned an invalid ${label} answer${member === undefined ? '' : ` (${member})`}.`);
+}

package/dist/execution/workflows/run.js

@@ -86,7 +86,7 @@ function durableContext(input, context, envelope) {
         const deadline = Date.now() + serving.stepTimeoutMs;
         const session = input.executor(execution.kernel, execution.id, { deadline, signal });
         try {
-            const kernel = keyed(bindSessionOf(session, deadline, signal), await keySequence(execution.id, name));
+            const kernel = keyed(bindSessionOf(session, deadline, signal), domain, await keySequence(execution.id, name));
             const output = await execute(Object.freeze({
                 kernel,
                 query: bindQuery(kernel, domain),
@@ -171,17 +171,29 @@ 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.
+ * Every Mutation and every `invoke` of a durable callable 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: the Kernel answers a Mutation with its receipt and a durable call with the
+ * Execution it started, or refuses a request that changed under its key. Any other `invoke` carries
+ * no key, because the Kernel accepts one only for a durable Function, and runs again with the Step.
  */
-function keyed(session, next) {
+function keyed(session, domain, next) {
     const invokeSource = session.invoke;
     const mutateSource = session.mutate;
-    const invoke = ((reference, value, options) => invokeSource(reference, value, withKey(options, next)));
+    const invoke = ((reference, value, options) => invokeSource(reference, value, declaredDurable(domain, reference) ? withKey(options, next) : options));
     const mutate = ((author, options) => mutateSource(author, withKey(options, next)));
     return Object.freeze({ ...session, invoke, mutate });
 }
+/**
+ * Whether the Domain's Schema closure declares the referenced callable durable. An untyped Path
+ * names no declaration and a callable outside the closure has none here: both need their own key.
+ */
+function declaredDurable(domain, reference) {
+    if (reference === null || typeof reference !== 'object')
+        return false;
+    const key = reference.callable;
+    return (typeof key === 'string' && domain.callable(key)?.execution?.durable === true);
+}
 function withKey(options, next) {
     if (options?.idempotencyKey !== undefined || options?.body !== undefined)
         return options;

package/dist/tooling/cli/adapter-command.d.ts

@@ -0,0 +1,35 @@
+import type { LoadedEnvironment } from './project.js';
+/**
+ * `astrale-domain <adapter> <command> <environment> --json` on stdout: what one provider command
+ * of the Environment's adapter answered (adapter-cloudflare: `cloudflare plan` and
+ * `cloudflare init`, which provision its host on the operator's own account).
+ */
+export interface AdapterCommandReportV1 {
+    readonly format: 'astrale.adapter-command';
+    readonly version: 1;
+    /** `<adapter name>@<adapter version>` */
+    readonly adapter: string;
+    readonly command: string;
+    readonly environment: string;
+    /** 0 done; 1 refused or blocked. */
+    readonly exitCode: 0 | 1;
+    /** What the adapter's command answered, as it answered it. */
+    readonly result: unknown;
+}
+/**
+ * `astrale-domain <adapter> <command> <environment> [--<option> <value>]... [--json]`: run one
+ * provider command an adapter declares, on an Environment that adapter deploys. The CLI only
+ * routes: it refuses an Environment whose adapter has another name, a command the adapter does
+ * not declare and an option the command does not declare, each before any effect, and prints what
+ * the command answers. Exit status: the command's (0 done, 1 refused or blocked), 1 when it could
+ * not run.
+ */
+export declare function runAdapterCommand(input: {
+    readonly adapter: string;
+    readonly command: string;
+    readonly environment: string;
+    readonly definition: LoadedEnvironment;
+    readonly options: Readonly<Record<string, string>>;
+    readonly json: boolean;
+    readonly signal: AbortSignal;
+}): Promise<number>;

package/dist/tooling/cli/adapter-command.js

@@ -0,0 +1,66 @@
+import { error, info, warn } from './log.js';
+/**
+ * `astrale-domain <adapter> <command> <environment> [--<option> <value>]... [--json]`: run one
+ * provider command an adapter declares, on an Environment that adapter deploys. The CLI only
+ * routes: it refuses an Environment whose adapter has another name, a command the adapter does
+ * not declare and an option the command does not declare, each before any effect, and prints what
+ * the command answers. Exit status: the command's (0 done, 1 refused or blocked), 1 when it could
+ * not run.
+ */
+export async function runAdapterCommand(input) {
+    const { adapter, parameters } = input.definition.deployment;
+    const name = `${adapter.name}@${adapter.version}`;
+    if (adapter.name !== input.adapter) {
+        error(`Environment ${input.environment} deploys through adapter ${adapter.name}, not ` +
+            `${input.adapter}: run \`astrale-domain ${adapter.name} <command> ${input.environment}\`.`);
+        return 1;
+    }
+    const commands = 'commands' in adapter ? adapter.commands : undefined;
+    const command = commands?.[input.command];
+    if (command === undefined) {
+        const declared = Object.entries(commands ?? {}).map(([candidate, { summary }]) => `${candidate} (${summary})`);
+        error(`Adapter ${name} declares no command ${input.command}` +
+            (declared.length === 0 ? '.' : `; its commands: ${declared.join('; ')}.`));
+        return 1;
+    }
+    const declaredOptions = command.options ?? {};
+    const unknown = Object.keys(input.options).filter((option) => !Object.hasOwn(declaredOptions, option));
+    if (unknown.length > 0) {
+        const known = Object.entries(declaredOptions).map(([option, description]) => `--${option} (${description})`);
+        error(`${input.adapter} ${input.command} takes no option ${unknown.map((option) => `--${option}`).join(', ')}` +
+            (known.length === 0 ? '.' : `; its options: ${known.join('; ')}.`));
+        return 1;
+    }
+    let answered;
+    try {
+        answered = await command.run(parameters, {
+            environment: input.environment,
+            signal: input.signal,
+            options: Object.freeze({ ...input.options }),
+        });
+    }
+    catch (cause) {
+        error(`${input.adapter} ${input.command} ${input.environment} (${name}) failed: ` +
+            (cause instanceof Error ? cause.message : String(cause)));
+        return 1;
+    }
+    for (const line of answered.warnings ?? [])
+        warn(line);
+    if (input.json) {
+        const report = Object.freeze({
+            format: 'astrale.adapter-command',
+            version: 1,
+            adapter: name,
+            command: input.command,
+            environment: input.environment,
+            exitCode: answered.exitCode,
+            result: answered.result,
+        });
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        for (const line of answered.lines)
+            info(line);
+    }
+    return answered.exitCode;
+}

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

@@ -3,7 +3,8 @@ import { type Version } from '../../platform/versioning/index.js';
 export declare const COMMANDS: readonly ['build', 'deploy', 'diff', 'list', 'publish', 'test', 'lint', 'package', 'upgrade', 'yank'];
 export type Command = (typeof COMMANDS)[number];
 export interface ParsedArgs {
-    readonly command: Command;
+    /** `adapter`: a provider command of an Environment's adapter (`<adapter> <command> <env>`). */
+    readonly command: Command | 'adapter';
     readonly env: string;
     readonly fix?: boolean;
     readonly format?: LintReportFormat;
@@ -19,6 +20,11 @@ export interface ParsedArgs {
     readonly allowDirty?: boolean;
     /** `list`: instances to ask what they run, in argument order. */
     readonly instances?: readonly string[];
+    /** `<adapter> <command> <env>`: the adapter name and its command. */
+    readonly adapter?: string;
+    readonly adapterCommand?: string;
+    /** `<adapter> <command> <env> --<option> <value>`: the options, by name. */
+    readonly options?: Readonly<Record<string, string>>;
 }
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export declare function parseArgs(argv: readonly string[]): ParsedArgs;

package/dist/tooling/cli/arguments.js

@@ -12,11 +12,18 @@ export const COMMANDS = [
     'upgrade',
     'yank',
 ];
+/** An adapter name or one of its command and option names, as `defineAdapter` admits them. */
+const PROVIDER_NAME = /^[a-z][a-z0-9-]{0,31}$/u;
 /** Parse the frozen `astrale-domain` command grammar without performing effects. */
 export function parseArgs(argv) {
     const [command, ...rest] = argv;
     if (command === 'upgrade')
         return parseUpgrade(rest);
+    if (command !== undefined && !COMMANDS.includes(command)) {
+        const provider = parseAdapterCommand(command, rest);
+        if (provider !== undefined)
+            return provider;
+    }
     const fix = rest.includes('--fix');
     const deployOnly = rest.includes('--deploy-only');
     const json = rest.includes('--json');
@@ -84,7 +91,7 @@ export function parseArgs(argv) {
         command !== 'list' &&
         command !== 'publish' &&
         command !== 'yank') {
-        throw new Error('`--json` is only valid for `build`, `deploy`, `diff`, `list`, `publish` or `yank`.');
+        throw new Error('`--json` is only valid for `build`, `deploy`, `diff`, `list`, `publish`, `yank` or an adapter command.');
     }
     if (allowDirty && command !== 'publish') {
         throw new Error('`--allow-dirty` is only valid for `publish`.');
@@ -222,6 +229,51 @@ function refuseDeployOnly(command, environment) {
     throw new Error(`${refusal} Run \`astrale-domain ${command} ${environment}\` without it, then install the ` +
         `URL it prints with \`${installCommand()}\`.`);
 }
+/**
+ * `astrale-domain <adapter> <command> <environment> [--<option> <value>]... [--json]`: a provider
+ * command, routed once the Project is loaded to the adapter of that Environment. Anything that is
+ * not exactly an adapter name, a command and an Environment is no command at all (undefined).
+ */
+function parseAdapterCommand(adapter, args) {
+    if (!PROVIDER_NAME.test(adapter))
+        return undefined;
+    const positionals = [];
+    const options = {};
+    let json = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--json') {
+            json = true;
+            continue;
+        }
+        if (!argument.startsWith('-')) {
+            positionals.push(argument);
+            continue;
+        }
+        const equals = argument.indexOf('=');
+        const name = argument.slice(2, equals === -1 ? undefined : equals);
+        if (!argument.startsWith('--') || !PROVIDER_NAME.test(name)) {
+            throw new Error(`Unknown flag "${argument}".`);
+        }
+        if (Object.hasOwn(options, name))
+            throw new Error(`--${name} is given twice.`);
+        options[name] =
+            equals === -1
+                ? requiredValue(`--${name}`, args[++index])
+                : requiredValue(`--${name}`, argument.slice(equals + 1));
+    }
+    const [adapterCommand, env] = positionals;
+    if (positionals.length !== 2 || !PROVIDER_NAME.test(adapterCommand))
+        return undefined;
+    return {
+        command: 'adapter',
+        env: env,
+        adapter,
+        adapterCommand: adapterCommand,
+        options,
+        ...(json ? { json: true } : {}),
+    };
+}
 function parseUpgrade(args) {
     let channel = 'beta';
     let check = false;

package/dist/tooling/cli/help.js

@@ -30,11 +30,15 @@ Commands:
   package                 Prepare public declarations for publication.
   upgrade                 Update Astrale dependencies through pnpm (default: beta).
   yank <version>          Take a published version out of resolution, or put it back.
+  <adapter> <command> <environment>
+                          Run a command the Environment's adapter declares for its provider,
+                          such as cloudflare plan production or cloudflare init production.
 
 Options:
   -h, --help              Show help.
 
-Run "astrale-domain <command> --help" for command-specific help.
+Run "astrale-domain <command> --help" for command-specific help. An adapter command that
+does not exist names the commands and options the Environment's adapter declares.
 `;
 const COMMAND_HELP = Object.freeze({
     upgrade: `Update existing Astrale dependencies in a pnpm project or workspace.
@@ -140,19 +144,18 @@ Behavior:
   The registry and the instances are read through the Astrale CLI (${MINIMUM_INSTALLATIONS_CLI_VERSION} or
   newer) with the caller's identity, only once a deployment is listed.
   A registry that cannot be read fails the listing; an unknown instance never does.
-  A preview expires 30 days after its activation or its last call, whichever is
-  later; a published deployment never does. Last calls are read from the host as it
-  counts them, so a host whose last calls cannot be read is not listed. A platform
-  dispatch namespace reads them from its calls dataset, and without Account Analytics
-  Read lists its deployments without last calls or expiries.
+  Admin's Services and a Cloudflare dispatch namespace keep every deployment until its
+  owner retires it, and report no last call or expiry; LAST CALL and EXPIRES show one
+  only when an older adapter reports it.
   Listing changes nothing, at any host, registry or instance.
   An Environment in legacy direct mode, refused by deploy, or whose adapter lists no
   deployments is reported on stderr and, with --json, under unlisted. A deployment
   whose record this SDK does not admit is still listed, from what its host knows.
   With --json, each deployment carries its installedOn and its call target: the path of
   its node on Admin's Services, for astrale call "<path>.method.setSecret" --admin, or the
-  namespace and script of a platform dispatch namespace, which its operator tooling
-  takes; installations says what of INSTALLED ON is unknown.
+  namespace and script of a dispatch namespace, which the hosting kit
+  (@astrale-os/adapter-cloudflare/hosting) retires; installations says what of
+  INSTALLED ON is unknown.
   Exit status: 0 listed, 1 a host or the registry could not be read (with --json,
   nothing on stdout), 2 usage error.
 `,

package/dist/tooling/cli/immutable-deployment.d.ts

@@ -1,4 +1,4 @@
-import type { DeploymentCommitV1, FrozenConfigurationV1 } from '../../deployment/address/index.js';
+import type { DeploymentCommitV1, DeploymentConfiguration } from '../../deployment/address/index.js';
 import type { Adapter, Build, Bundle, LegacyAdapter, Placement, Release, ResolvedRuntimeReference } from '../../deployment/index.js';
 import type { DeployResultV1 } from './deploy-result.js';
 /**
@@ -15,7 +15,7 @@ export interface ImmutableDeploymentPlan {
     readonly identity?: string;
     readonly bundle: Bundle;
     readonly secrets: Readonly<Record<string, string>>;
-    readonly configuration: FrozenConfigurationV1;
+    readonly configuration: DeploymentConfiguration;
     readonly placement: Placement;
     /** `<line>-<content>`: the deployment's DNS label and provider script. */
     readonly label: string;

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

@@ -1,7 +1,8 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (build | deploy | diff | list | publish | test | lint | package | upgrade | yank), its JSON results,
- * the deploy mode each command selects for an Environment (CT33), and the explicit dotenv boundary.
+ * (build | deploy | diff | list | publish | test | lint | package | upgrade | yank, and the
+ * provider commands adapters declare), its JSON results, the deploy mode each command selects for an Environment (CT33), and the explicit
+ * dotenv boundary.
  *
  * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
  * Bun (it imports the project's `astrale.config.ts` directly). This subpath is
@@ -14,6 +15,7 @@ export { run } from './run.js';
 export type { BuildResultV1 } from './build.js';
 export type { DeployResultV1, DeploymentSecretsState } from './deploy-result.js';
 export type { DiffChangeV1, DiffReportV1 } from './diff/index.js';
+export type { AdapterCommandReportV1 } from './adapter-command.js';
 export type { InstallationSourcesV1, InstallationUnknownReason, InstalledOnV1, InstanceSourceV1, ListedDeploymentV1, ListResultV1, UnlistedEnvironmentV1, } from './list.js';
 export type { PublishReportV1 } from './publish/index.js';
 export type { YankReportV1 } from './yank.js';

package/dist/tooling/cli/index.js

@@ -1,7 +1,8 @@
 /**
  * `@astrale-os/sdk/cli` — the `astrale-domain` CLI
- * (build | deploy | diff | list | publish | test | lint | package | upgrade | yank), its JSON results,
- * the deploy mode each command selects for an Environment (CT33), and the explicit dotenv boundary.
+ * (build | deploy | diff | list | publish | test | lint | package | upgrade | yank, and the
+ * provider commands adapters declare), its JSON results, the deploy mode each command selects for an Environment (CT33), and the explicit
+ * dotenv boundary.
  *
  * Node-only: the CLI imports `node:fs`/`node:module`/`node:url` and runs under
  * Bun (it imports the project's `astrale.config.ts` directly). This subpath is

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

@@ -26,11 +26,11 @@ export interface ListResultV1 {
 }
 /**
  * One deployment: what its host knows (`DeploymentSummaryV1`), the Environment it was listed for
- * and its adapter, its computed name, and its call target. `lastCallAt` and a preview's `expiresAt`
- * are as of the listing: a platform namespace (adapter-cloudflare) reads every call from its calls
- * dataset, and omits both without Account Analytics Read. Admin's Services (adapter-astrale) keeps
- * every deployment until it is retired and counts no call: its rows are `published`, with neither
- * clock, and say whether their Service serves them (`current`).
+ * and its adapter, its computed name, and its call target. Admin's Services (adapter-astrale) keeps
+ * every deployment until it is retired: its rows are `published` and say whether their Service
+ * serves them (`current`). A Cloudflare dispatch namespace (adapter-cloudflare) keeps no
+ * retention, and knows a deployment's creation instant and key only while its script exists. A
+ * last call and an expiry are printed only when an older adapter still reports them.
  */
 export type ListedDeploymentV1 = Omit<DeploymentSummaryV1, 'record'> & {
     /** The Project Environment whose line holds the deployment, as its host listed it. */

package/dist/tooling/cli/list.js

@@ -189,13 +189,13 @@ function listedDeployment(hosted, publications, installations) {
         line: deployment.line,
         owner: deployment.owner,
         state: deployment.state,
-        retention: deployment.retention,
-        createdAt: deployment.createdAt,
+        ...(deployment.retention === undefined ? {} : { retention: deployment.retention }),
+        ...(deployment.createdAt === undefined ? {} : { createdAt: deployment.createdAt }),
         ...(deployment.lastCallAt === undefined ? {} : { lastCallAt: deployment.lastCallAt }),
         ...(deployment.expiresAt === undefined ? {} : { expiresAt: deployment.expiresAt }),
         ...(deployment.retiredAt === undefined ? {} : { retiredAt: deployment.retiredAt }),
         ...(deployment.retirement === undefined ? {} : { retirement: deployment.retirement }),
-        signingKeyId: deployment.signingKeyId,
+        ...(deployment.signingKeyId === undefined ? {} : { signingKeyId: deployment.signingKeyId }),
         record,
         ...(recordRefusal === undefined ? {} : { recordRefusal }),
         ...(deployment.current === undefined ? {} : { current: deployment.current }),
@@ -203,11 +203,11 @@ function listedDeployment(hosted, publications, installations) {
     });
 }
 /**
- * Why a deployment its host keeps no record of has none: the adapter lists it without `record`, as a
- * platform namespace lists a deployment it has not activated.
+ * Why a deployment its host keeps no record of has none: the adapter lists it without `record`, as
+ * a dispatch namespace lists a label it retired and never activated.
  */
-const NO_RECORD = 'Its host keeps no record of it: it has not been activated (a deploy still in progress, or one ' +
-    'that stopped before activating it).';
+const NO_RECORD = 'Its host keeps no record of it: it was never activated (a deploy still in progress, one that ' +
+    'stopped before activating it, or a label retired before it served).';
 /** Why an admitted record does not describe the listed deployment, if it does not. */
 function describesAnother(record, label, listing) {
     if (record.providerScript !== label) {
@@ -259,18 +259,21 @@ function admitListed(deployment, adapter) {
         throw new TypeError(`Adapter ${adapter} listed an invalid deployment (${member}).`);
     };
     const value = members(deployment) ?? invalid('deployment');
-    for (const key of ['id', 'url', 'label', 'line', 'owner', 'createdAt', 'signingKeyId']) {
+    for (const key of ['id', 'url', 'label', 'line', 'owner']) {
         if (!text(value[key]))
             invalid(key);
     }
-    for (const key of ['lastCallAt', 'expiresAt', 'retiredAt']) {
+    for (const key of ['createdAt', 'signingKeyId', 'lastCallAt', 'expiresAt', 'retiredAt']) {
         if (value[key] !== undefined && !text(value[key]))
             invalid(key);
     }
     if (!STATES.includes(value.state))
         invalid('state');
-    if (value.retention !== 'preview' && value.retention !== 'published')
+    if (value.retention !== undefined &&
+        value.retention !== 'preview' &&
+        value.retention !== 'published') {
         invalid('retention');
+    }
     if (value.retirement !== undefined &&
         value.retirement !== 'expired' &&
         value.retirement !== 'withdrawn') {
@@ -352,10 +355,9 @@ function shortDigest(digest) {
     return `${digest.slice(0, 'sha256:'.length + 7)}…`;
 }
 /**
- * When a deployment stops serving: `never` once published, else its preview expiry as its host
- * keeps it, 30 days after its activation or its last call, whichever is later (AM-123), with the
- * calls counted since the host recorded them; `due` once that instant passed but the host has not
- * retired it yet; for a retired deployment, why it was retired.
+ * When a deployment stops serving: `never` once published, else the expiry an older adapter
+ * reports (`due` once that instant passed), else `—` (a dispatch namespace keeps a deployment
+ * until its owner retires it); for a retired deployment, why it was retired.
  */
 function expiry(deployment, now) {
     if (deployment.state === 'retiring')