@astrale-os/sdk 0.6.0-beta.16 → 0.6.0-beta.17

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

@@ -30,8 +30,9 @@ export declare const PLATFORM_OWNER = "platform";
  * `summary:<label>` in the routing KV of a platform dispatch namespace (CT20, AM-131): the
  * `DeploymentSummaryV1` of one deployment without its record, which stays at `record:<label>`.
  *
- * Its writers are the deployer (`cloudflare({ namespace })`), which writes it once at activation,
- * before `record:<label>`, then marks it published (`retain`), and the platform retirement tooling
+ * Its writers are the deployer (`cloudflare({ namespace })`), which writes it at activation,
+ * before `record:<label>`, names in it the new key of a script it recreates under the label after
+ * an operator deleted it, and marks it published (`retain`), and the platform retirement tooling
  * (SV6), which records a withdrawal. So it names the deployment by its label (`id` is the label),
  * is owned by `platform`, is `active` until withdrawn, and carries no `lastCallAt` or `expiresAt`:
  * nothing on the platform namespace keeps those clocks, and listings read them from the calls

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

@@ -19,6 +19,8 @@ export interface ParsedArgs {
     /** `yank --undo`: restore the version instead of yanking it. */
     readonly undo?: boolean;
     readonly allowDirty?: boolean;
+    /** `list`: instances to ask what they run, in argument order. */
+    readonly instances?: readonly 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

@@ -30,6 +30,7 @@ export function parseArgs(argv) {
     let suite;
     let format;
     let environment;
+    const instances = [];
     const cleaned = [];
     for (let index = 0; index < rest.length; index += 1) {
         const argument = rest[index];
@@ -63,6 +64,13 @@ export function parseArgs(argv) {
         else if (argument.startsWith('--environment=')) {
             environment = requiredValue('--environment', argument.slice('--environment='.length));
         }
+        else if (command === 'list' && argument === '--instance') {
+            // Only `list` asks instances; elsewhere `--instance` stays unknown, as deploy removed it.
+            instances.push(requiredValue('--instance', rest[++index]));
+        }
+        else if (command === 'list' && argument.startsWith('--instance=')) {
+            instances.push(requiredValue('--instance', argument.slice('--instance='.length)));
+        }
         else if (argument === '--suite') {
             suite = requiredValue('--suite', rest[++index]);
         }
@@ -163,6 +171,7 @@ export function parseArgs(argv) {
                 env: environment ?? '',
                 ...(json ? { json: true } : {}),
                 ...(identity === undefined ? {} : { identity }),
+                ...(instances.length === 0 ? {} : { instances: [...new Set(instances)] }),
             };
         case 'build':
         case 'package':

package/dist/tooling/cli/help.js

@@ -1,5 +1,6 @@
 import { installCommand } from '../../project/install-command.js';
 import { COMMANDS } from './arguments.js';
+import { MINIMUM_INSTALLATIONS_CLI_VERSION } from './registry/executable.js';
 /** Resolve help without parsing a project or performing any command effects. */
 export function helpRequest(argv) {
     if (!argv.some((argument) => argument === '--help' || argument === '-h'))
@@ -157,39 +158,50 @@ Behavior:
   astrale domain install takes, its digests, adapter and state. Exit status: 0 deployed,
   1 failed or refused, 2 usage error; a failed run prints nothing on stdout.
 `,
-    list: `List the deployments of the Project's Environments that their hosts keep.
+    list: `List the deployments of the Project's Environments, their versions and where they run.
 
 Usage:
-  astrale-domain list [--environment <name>] [--json]
+  astrale-domain list [--environment <name>] [--instance <name>]... [--json]
 
 Options:
   --environment <name>    List one Environment instead of every Environment.
+  --instance <name>       Ask this instance what it runs, for INSTALLED ON (repeatable).
   --json                  Print one ListResultV1 on stdout; notices go to stderr.
-  --as <identity>         Select the Astrale identity whose deployments the hosts list.
+  --as <identity>         Select the Astrale identity for the hosts, the registry and the
+                          instances.
   -h, --help              Show help for list.
 
 Behavior:
   Asks the adapter of each Environment that deploys immutable deployments for the
-  deployments its host keeps for the caller, and prints each one's release, its name,
-  Environment and state, its last call and its expiry, and the URL
-  ${installCommand()} takes. A name is computed
-  from the deployment's record and never stored, such as 1.4.2 + 7 commits · a1b2c3d ·
-  staging.
+  deployments its host keeps for the caller, and prints each one's release, its version
+  or name, Environment and state, the instances it is installed on, its last call and
+  its expiry, and the URL ${installCommand()} takes.
+  A deployment is named by the registry's version of its release (1.5.0) or of its build
+  (1.5.0 · staging), else from its record's commit, such as 1.4.2 + 7 commits · a1b2c3d ·
+  staging. Names are computed, never stored, and printed whole.
+  INSTALLED ON names each --instance whose Kernel pins the deployment. ? marks what is
+  unknown: no instance was asked, an instance could not tell (such as one whose Kernel
+  does not list installed releases), or its listing shows only what you can read there;
+  stderr says which and why. An unknown instance is never shown as running nothing; —
+  means every instance asked listed all it runs and none runs it.
+  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.
-  Listing changes nothing, at any host or instance.
+  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 call target: the path of its node on
-  Admin's Services, for astrale call "<path>.method.setSecret" --admin, or the
+  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.
-  Exit status: 0 listed, 1 a host could not be listed (with --json, nothing on
-  stdout), 2 usage error.
+  takes; 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.
 `,
     diff: `Show the changes since the last published version and the version they require.
 

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

@@ -15,7 +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 { ListedDeploymentV1, ListResultV1, UnlistedEnvironmentV1 } from './list.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';
 export { selectDeployMode } from './deploy-mode.js';

package/dist/tooling/cli/installed-on.d.ts

@@ -0,0 +1,83 @@
+import type { DomainRegistry, InstallationUnknownReason, InstanceInstallation } from './registry/index.js';
+/**
+ * One instance known to pin a deployment (INSTALLÉ SUR, DX [.83795]): an instance named with
+ * `--instance`, as its Kernel lists it (CT24). Admin does not say which instances pin a release
+ * (A15 is deferred, AM-241), so an instance is known only when it is asked.
+ */
+export interface InstalledOnV1 {
+    readonly source: 'instance';
+    /** The instance as `--instance` named it. */
+    readonly instance: string;
+    /** The instance Kernel URL that answered. */
+    readonly kernel: string;
+}
+/**
+ * Where INSTALLÉ SUR comes from and what of it is unknown. An instance whose installations are
+ * unknown is partial, never "not installed" (AM-198); an instance is known only when `--instance`
+ * names it ([.59528], AM-241).
+ */
+export interface InstallationSourcesV1 {
+    /**
+     * True when an instance may run a deployment that no source names: an `--instance` that could
+     * not say or whose listing is itself partial (a Kernel lists only what the caller reads, AM-83,
+     * AM-84), or no `--instance` at all. False only when every `--instance` listed all it runs.
+     */
+    readonly partial: boolean;
+    /** One entry per distinct `--instance`, in argument order. */
+    readonly instances: readonly InstanceSourceV1[];
+}
+/**
+ * One `--instance`: what its Kernel answered, why that is unknown, or that it was not asked. A
+ * `read` listing names the deployments it pins; with `partial` (always, from C7) one it does not
+ * name may still run there.
+ */
+export type InstanceSourceV1 = {
+    readonly instance: string;
+    readonly state: 'read';
+    readonly kernel: string;
+    readonly partial: boolean;
+} | {
+    readonly instance: string;
+    readonly state: 'unknown';
+    readonly reason: InstallationUnknownReason;
+    readonly code: string;
+} | {
+    readonly instance: string;
+    readonly state: 'skipped';
+};
+/** What the sources answered, kept to join each listed deployment to the instances that pin it. */
+export interface InstallationsRead {
+    readonly sources: InstallationSourcesV1;
+    readonly instances: readonly {
+        readonly instance: string;
+        readonly kernel: string;
+        readonly installations: readonly InstanceInstallation[];
+    }[];
+}
+/** Nothing was listed: no source is asked. */
+export declare function skippedInstallations(instances: readonly string[]): InstallationsRead;
+/**
+ * Ask every `--instance` whether it pins a deployment of the origin. An instance that cannot tell
+ * is recorded as unknown, with why, and the listing stays partial for it (AM-198); a refusal's
+ * message is never relayed, only its code. Only a stop of `signal`, the one every registry read
+ * follows, fails it: an interrupted listing is never printed as a partial one.
+ */
+export declare function readInstallations(registry: Pick<DomainRegistry, 'instance'>, origin: string, instances: readonly string[], signal: AbortSignal): Promise<InstallationsRead>;
+/**
+ * The instances known to pin the deployment served at `url`: an installation whose Kernel lists
+ * its pin under that deployment URL runs that deployment, since one immutable deployment has one
+ * URL. In `--instance` argument order.
+ */
+export declare function installedOn(url: string, read: InstallationsRead): readonly InstalledOnV1[];
+/**
+ * The INSTALLED ON cell: the instances known to pin the deployment, then `?` when an instance may
+ * run it unnamed (the notices say which); `—` only when every `--instance` listed all it runs and
+ * none pins it.
+ */
+export declare function installedOnCell(installed: readonly InstalledOnV1[], sources: InstallationSourcesV1): string;
+/**
+ * One line for stderr per source that could not tell, or one when no instance was asked: an
+ * unknown instance is partial, never "not installed" (AM-198). Only codes the CLI reported are
+ * named, never its messages.
+ */
+export declare function installationNotices(sources: InstallationSourcesV1): readonly string[];

package/dist/tooling/cli/installed-on.js

@@ -0,0 +1,156 @@
+import { isAdminFailure } from './registry/index.js';
+/** `--instance` listings run at once; each is one CLI process reading one instance Kernel. */
+const INSTANCE_READS = 4;
+/** Nothing was listed: no source is asked. */
+export function skippedInstallations(instances) {
+    return Object.freeze({
+        sources: Object.freeze({
+            partial: false,
+            instances: Object.freeze(distinct(instances).map((instance) => Object.freeze({ instance, state: 'skipped' }))),
+        }),
+        instances: Object.freeze([]),
+    });
+}
+/**
+ * Ask every `--instance` whether it pins a deployment of the origin. An instance that cannot tell
+ * is recorded as unknown, with why, and the listing stays partial for it (AM-198); a refusal's
+ * message is never relayed, only its code. Only a stop of `signal`, the one every registry read
+ * follows, fails it: an interrupted listing is never printed as a partial one.
+ */
+export async function readInstallations(registry, origin, instances, signal) {
+    const listed = await mapBounded(distinct(instances), INSTANCE_READS, async (instance) => {
+        try {
+            return { instance, listing: await registry.instance(instance) };
+        }
+        catch (cause) {
+            if (signal.aborted)
+                throw cause;
+            // The CLI could not run for this instance: unknown, never a failure of the listing.
+            return {
+                instance,
+                listing: {
+                    kind: 'unknown',
+                    reason: 'unavailable',
+                    code: 'REGISTRY_CLI_FAILED',
+                },
+            };
+        }
+    });
+    const instanceSources = [];
+    const read = [];
+    for (const { instance, listing } of listed) {
+        if (listing.kind === 'listed') {
+            instanceSources.push(Object.freeze({
+                instance,
+                state: 'read',
+                kernel: listing.kernel,
+                partial: listing.partial,
+            }));
+            read.push(Object.freeze({
+                instance,
+                kernel: listing.kernel,
+                installations: listing.installations.filter((entry) => entry.origin === origin),
+            }));
+        }
+        else {
+            instanceSources.push(Object.freeze({ instance, state: 'unknown', reason: listing.reason, code: listing.code }));
+        }
+    }
+    const partial = instanceSources.length === 0 ||
+        instanceSources.some((entry) => entry.state === 'unknown' || (entry.state === 'read' && entry.partial));
+    return Object.freeze({
+        sources: Object.freeze({ partial, instances: Object.freeze(instanceSources) }),
+        instances: Object.freeze(read),
+    });
+}
+/**
+ * The instances known to pin the deployment served at `url`: an installation whose Kernel lists
+ * its pin under that deployment URL runs that deployment, since one immutable deployment has one
+ * URL. In `--instance` argument order.
+ */
+export function installedOn(url, read) {
+    const deployment = urlOrigin(url);
+    if (deployment === undefined)
+        return Object.freeze([]);
+    const asked = read.instances
+        .filter((entry) => entry.installations.some((installation) => urlOrigin(installation.url) === deployment))
+        .map((entry) => Object.freeze({
+        source: 'instance',
+        instance: entry.instance,
+        kernel: entry.kernel,
+    }));
+    return Object.freeze(asked);
+}
+/** Names shown before the cell counts the rest; the JSON keeps them all. */
+const CELL_NAMES = 3;
+/**
+ * The INSTALLED ON cell: the instances known to pin the deployment, then `?` when an instance may
+ * run it unnamed (the notices say which); `—` only when every `--instance` listed all it runs and
+ * none pins it.
+ */
+export function installedOnCell(installed, sources) {
+    const names = distinct(installed.map((entry) => entry.instance));
+    const shown = names.length > CELL_NAMES
+        ? `${names.slice(0, CELL_NAMES).join(', ')} +${names.length - CELL_NAMES}`
+        : names.join(', ');
+    if (!sources.partial)
+        return names.length === 0 ? '—' : shown;
+    return names.length === 0 ? '?' : `${shown}, ?`;
+}
+const INSTANCE_REASONS = {
+    timeout: 'it did not answer in time',
+    refused: 'its Kernel refused the read',
+    unavailable: 'it could not be reached',
+    unsupported: 'its Kernel does not list installed releases',
+};
+/**
+ * One line for stderr per source that could not tell, or one when no instance was asked: an
+ * unknown instance is partial, never "not installed" (AM-198). Only codes the CLI reported are
+ * named, never its messages.
+ */
+export function installationNotices(sources) {
+    const notices = [];
+    if (sources.instances.length === 0) {
+        notices.push('INSTALLED ON is unknown: no instance was asked, and Admin does not say which instances ' +
+            'pin a deployment. Ask an instance with --instance <name>.');
+    }
+    for (const entry of sources.instances) {
+        if (entry.state === 'read') {
+            if (entry.partial) {
+                notices.push(`INSTALLED ON is partial: instance ${entry.instance} lists only what its Kernel shows ` +
+                    'this caller, so a deployment it does not list may still run there.');
+            }
+            continue;
+        }
+        if (entry.state !== 'unknown')
+            continue;
+        notices.push(`INSTALLED ON is partial: what instance ${entry.instance} runs is unknown (${entry.code}): ` +
+            (isAdminFailure(entry.code)
+                ? "the Astrale CLI could not read Admin's registry, which names what the instance runs."
+                : `${INSTANCE_REASONS[entry.reason]}.`));
+    }
+    return Object.freeze(notices);
+}
+function urlOrigin(input) {
+    try {
+        return new URL(input).origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function distinct(values) {
+    return [...new Set(values)];
+}
+async function mapBounded(inputs, limit, map) {
+    const outputs = Array.from({ length: inputs.length });
+    let next = 0;
+    const worker = async () => {
+        while (next < inputs.length) {
+            const index = next++;
+            outputs[index] = await map(inputs[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, inputs.length) }, worker));
+    return outputs;
+}

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

@@ -1,10 +1,14 @@
 import type { DeploymentRecordV1, DeploymentSummaryV1 } from '../../deployment/address/index.js';
-import type { DeploymentCallTarget, ListedDeployment } from '../../deployment/index.js';
+import type { DeploymentCallTarget } from '../../deployment/index.js';
+import type { InstallationSourcesV1, InstalledOnV1 } from './installed-on.js';
 import type { LoadedEnvironment } from './project.js';
+import type { DomainRegistry } from './registry/index.js';
+export type { InstallationSourcesV1, InstalledOnV1, InstanceSourceV1 } from './installed-on.js';
+export type { InstallationUnknownReason } from './registry/index.js';
 /**
  * `astrale-domain list --json` on stdout: the deployments of the Project's Environments that their
- * hosts keep for the caller, each with its computed name and where it is called. It changes
- * nothing, at any host or instance.
+ * hosts keep for the caller, each with its computed name, the instances known to pin it and where
+ * it is called. It changes nothing, at any host, registry or instance.
  */
 export interface ListResultV1 {
     readonly format: 'astrale.deployment-list';
@@ -17,6 +21,8 @@ export interface ListResultV1 {
      * complete exactly when this is empty.
      */
     readonly unlisted: readonly UnlistedEnvironmentV1[];
+    /** Where every `installedOn` comes from, and what of it is unknown (AM-198). */
+    readonly installations: InstallationSourcesV1;
 }
 /**
  * One deployment: what its host knows (`DeploymentSummaryV1`), the Environment it was listed for
@@ -31,10 +37,19 @@ export type ListedDeploymentV1 = Omit<DeploymentSummaryV1, 'record'> & {
     /** `<adapter name>@<adapter version>` */
     readonly adapter: string;
     /**
-     * The deployment's name (`deploymentName`, CT28), computed from its record and never stored:
-     * `1.4.2 + 7 commits · a1b2c3d · staging`. Print it as it is, environment included (AM-57).
+     * The deployment's name (`deploymentName`, CT28), computed and never stored: the version of the
+     * registry that names its release (`1.5.0`), or its build elsewhere (`1.5.0 · staging`), else
+     * from its record's commit (`1.4.2 + 7 commits · a1b2c3d · staging`). Print it as it is,
+     * environment included (AM-57).
      */
     readonly name: string;
+    /**
+     * The instances known to pin this deployment: those `--instance` asked, as their Kernels list
+     * them (CT24). Partial by nature: an instance is known only when asked, and one whose
+     * installations are unknown is under `installations`, never absent from here as "not installed"
+     * (AM-198).
+     */
+    readonly installedOn: readonly InstalledOnV1[];
     /**
      * The record its deployer declared, as `acceptDeploymentRecord` admits it. `null` when there is
      * no admitted record: the host returns a record this SDK refuses or one that describes another
@@ -66,7 +81,10 @@ export interface UnlistedEnvironmentV1 {
 /** What a listing found, beside the result: what to tell a person, and what failed. */
 export interface DeploymentListing {
     readonly result: ListResultV1;
-    /** One line for each Environment not listed and each record not admitted, for stderr. */
+    /**
+     * One line for each Environment not listed, each record not admitted and each source of
+     * INSTALLED ON that could not tell, for stderr.
+     */
     readonly notices: readonly string[];
     /** Environments whose host could not be listed: their deployments are missing from the result. */
     readonly failures: readonly {
@@ -74,9 +92,21 @@ export interface DeploymentListing {
         readonly adapter: string;
         readonly error: Error;
     }[];
+    /**
+     * The Domain registry could not be read, so no deployment can be named by its version and the
+     * result is not to be printed: versions are never dropped silently (AM-224). That is a missing
+     * Astrale CLI, one older than the listing's floor, no identity it may use, an Admin it cannot
+     * reach, an index it cannot read, or an interruption while it reads; never a source of
+     * INSTALLED ON, which only makes the listing partial.
+     */
+    readonly registryFailure?: Error;
 }
+/** What the listing reads through the Astrale CLI: the registry index and the instances. */
+export type DeploymentRegistry = Pick<DomainRegistry, 'index' | 'instance'>;
 /**
- * List the deployments of the selected Environments, one adapter `list` call each.
+ * List the deployments of the selected Environments, one adapter `list` call each, then name them
+ * and say where they are installed (tech [.59528]: the records, the registry's versions and the
+ * instances' pins).
  *
  * Only an Environment that deploys immutable deployments (CT33 canonical) is listed; the others are
  * `unlisted`, with the reason. A record the host returns but `acceptDeploymentRecord` refuses never
@@ -85,6 +115,14 @@ export interface DeploymentListing {
  * record itself may fail its own list (Admin's Services does, AM-152). An Environment whose host
  * cannot be listed, or whose adapter answers anything but deployments, is a failure, and the others
  * are still listed.
+ *
+ * Once a deployment is listed, the registry is opened once: its index of the origin names each
+ * deployment by the version of its release or build (CT28; none when the origin is unregistered or
+ * not readable), and the instances that pin each deployment come from each `--instance` (CT24);
+ * Admin does not say which instances pin a release (AM-241). A registry that cannot be opened or
+ * whose index cannot be read is `registryFailure`, and the instance reads still running are
+ * stopped at once; an instance that cannot tell never fails the listing: it is partial (AM-198,
+ * AM-224).
  */
 export declare function listDeployments(input: {
     readonly origin: string;
@@ -92,23 +130,19 @@ export declare function listDeployments(input: {
     readonly environments: readonly (readonly [string, LoadedEnvironment])[];
     readonly identity?: string;
     readonly signal: AbortSignal;
+    /**
+     * Opens the Domain registry, once, and only when at least one deployment is listed. Every read
+     * it makes follows `signal`, which also stops when the index cannot be read.
+     */
+    readonly registry: (signal: AbortSignal) => Promise<DeploymentRegistry>;
+    /** Instances to ask what they run (`--instance`, repeatable). */
+    readonly instances?: readonly string[];
 }): Promise<DeploymentListing>;
-/**
- * One listed deployment, its record admitted when it describes exactly this deployment of this
- * origin and Environment. Its name comes from the admitted record; otherwise it is named in the
- * listed Environment, with the commit of the stored record only when that record names this
- * deployment, origin and Environment, as `deploymentName` reads a commit.
- */
-export declare function listedDeployment(deployment: ListedDeployment, listing: {
-    readonly origin: string;
-    readonly environment: string;
-    readonly adapter: string;
-}): ListedDeploymentV1;
 /**
  * The listing as a table for a person, at `now`: each deployment's release, its name as computed
- * (never shortened, AM-57), its Environment and state, its last call and its expiry, and the URL
- * `astrale domain install` takes. Without deployments, it says so only for what was listed: nothing
- * when a host `failed` (stderr says which), and that some Environments were not listed when any
- * was not.
+ * (never shortened, AM-57), its Environment and state, the instances known to pin it (`?` when a
+ * source could not tell, AM-198), its last call and its expiry, and the URL `astrale domain
+ * install` takes. Without deployments, it says so only for what was listed: nothing when a host
+ * `failed` (stderr says which), and that some Environments were not listed when any was not.
  */
 export declare function renderDeploymentList(result: ListResultV1, now: number, failed?: boolean): readonly string[];