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

package/dist/tooling/cli/list.js

@@ -1,8 +1,11 @@
 import { acceptDeploymentRecord } from '../../deployment/address/index.js';
 import { deploymentName } from '../../platform/versioning/name.js';
 import { selectDeployMode } from './deploy-mode.js';
+import { installationNotices, installedOn, installedOnCell, readInstallations, skippedInstallations, } from './installed-on.js';
 /**
- * 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
@@ -11,9 +14,17 @@ import { selectDeployMode } from './deploy-mode.js';
  * 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 async function listDeployments(input) {
-    const deployments = [];
+    const hosted = [];
     const unlisted = [];
     const notices = [];
     const failures = [];
@@ -62,58 +73,116 @@ export async function listDeployments(input) {
             continue;
         }
         for (const deployment of listed) {
-            const row = listedDeployment(deployment, { origin: input.origin, environment, adapter: name });
+            const row = hostedDeployment(deployment, { origin: input.origin, environment, adapter: name });
             if (row.recordRefusal !== undefined) {
                 notices.push(deployment.record === undefined
-                    ? `Deployment ${row.label} (${environment}) is listed from what its host knows: ` +
+                    ? `Deployment ${deployment.label} (${environment}) is listed from what its host knows: ` +
                         `${row.recordRefusal}`
-                    : `Deployment ${row.label} (${environment}) is listed from what its host knows: its ` +
+                    : `Deployment ${deployment.label} (${environment}) is listed from what its host knows: its ` +
                         `stored record is not admitted. ${row.recordRefusal}`);
             }
-            deployments.push(row);
+            hosted.push(row);
+        }
+    }
+    let publications = [];
+    let installations = skippedInstallations(input.instances ?? []);
+    let registryFailure;
+    if (hosted.length > 0) {
+        // One signal for every registry read, so that an unreadable index stops the others.
+        const reads = new AbortController();
+        const interrupt = () => reads.abort(input.signal.reason);
+        if (input.signal.aborted)
+            interrupt();
+        else
+            input.signal.addEventListener('abort', interrupt, { once: true });
+        try {
+            const registry = await input.registry(reads.signal);
+            // The index and every `--instance` are read together; the latter fail only when the reads
+            // are stopped, which is handled where they are awaited below.
+            const read = readInstallations(registry, input.origin, input.instances ?? [], reads.signal);
+            read.catch(() => undefined);
+            try {
+                publications = (await registry.index(input.origin))?.publications ?? [];
+            }
+            catch (cause) {
+                // Nothing is printed without the versions: stop the CLI processes still asking instances
+                // what they run, and wait only for them to end.
+                reads.abort(cause);
+                await read.catch(() => undefined);
+                throw cause;
+            }
+            installations = await read;
+        }
+        catch (cause) {
+            registryFailure = cause instanceof Error ? cause : new Error(String(cause));
+        }
+        finally {
+            input.signal.removeEventListener('abort', interrupt);
         }
     }
+    // INSTALLED ON is reported only for rows the listing prints.
+    if (hosted.length > 0 && registryFailure === undefined) {
+        notices.push(...installationNotices(installations.sources));
+    }
     return Object.freeze({
         result: Object.freeze({
             format: 'astrale.deployment-list',
             version: 1,
             origin: input.origin,
-            deployments: Object.freeze(deployments),
+            deployments: Object.freeze(hosted.map((row) => listedDeployment(row, publications, installations))),
             unlisted: Object.freeze(unlisted),
+            installations: installations.sources,
         }),
         notices: Object.freeze(notices),
         failures: Object.freeze(failures),
+        ...(registryFailure === undefined ? {} : { registryFailure }),
     });
 }
 /**
- * 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.
+ * One listed deployment's record, admitted when it describes exactly this deployment of this
+ * origin and Environment, else refused with why, or none when its host keeps none (`NO_RECORD`).
  */
-export function listedDeployment(deployment, listing) {
-    let record = null;
-    let recordRefusal;
+function hostedDeployment(deployment, listing) {
     if (deployment.record === undefined) {
-        recordRefusal = NO_RECORD;
+        return { deployment, listing, record: null, recordRefusal: NO_RECORD };
     }
-    else {
-        try {
-            const admitted = acceptDeploymentRecord(deployment.record);
-            recordRefusal = describesAnother(admitted, deployment.label, listing);
-            if (recordRefusal === undefined)
-                record = admitted;
-        }
-        catch (cause) {
-            recordRefusal = cause instanceof Error ? cause.message : String(cause);
-        }
+    try {
+        const admitted = acceptDeploymentRecord(deployment.record);
+        const recordRefusal = describesAnother(admitted, deployment.label, listing);
+        return recordRefusal === undefined
+            ? { deployment, listing, record: admitted }
+            : { deployment, listing, record: null, recordRefusal };
     }
-    // No Publication names a deployment yet: the registry is read by `list` once versions exist.
-    const name = deploymentName(record ?? canonicalParts(deployment.record, deployment.label, listing), []);
+    catch (cause) {
+        return {
+            deployment,
+            listing,
+            record: null,
+            recordRefusal: cause instanceof Error ? cause.message : String(cause),
+        };
+    }
+}
+/**
+ * One listed deployment, named and placed. With an admitted record, its name comes from the
+ * registry's Publications of the origin that name its release, else its build, else from its
+ * record (CT28). 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, and never by a
+ * version: a record the listing does not admit gives no digest to name.
+ */
+function listedDeployment(hosted, publications, installations) {
+    const { deployment, listing, record, recordRefusal } = hosted;
+    // A build digest names the row from any Publication of the origin, whatever its URL: the row is
+    // a deployment its own host lists for the caller, and the build of a version deployed elsewhere
+    // is another deployment at another URL (`1.5.0 · staging`, tech [.83533]). An instance's pin,
+    // which a frozen Worker's tenant may serve, is named only within its issuer (AM-73, AM-224).
+    const name = record === null
+        ? deploymentName(canonicalParts(deployment.record, deployment.label, listing), [])
+        : deploymentName(record, publications);
     return Object.freeze({
         environment: listing.environment,
         adapter: listing.adapter,
         name,
+        installedOn: installedOn(deployment.url, installations),
         id: deployment.id,
         url: deployment.url,
         label: deployment.label,
@@ -224,16 +293,25 @@ function members(input) {
         ? input
         : undefined;
 }
-const COLUMNS = ['RELEASE', 'VERSION', 'ENV', 'STATE', 'LAST CALL', 'EXPIRES', 'URL'];
+const COLUMNS = [
+    'RELEASE',
+    'VERSION',
+    'ENV',
+    'STATE',
+    'INSTALLED ON',
+    'LAST CALL',
+    'EXPIRES',
+    'URL',
+];
 const MINUTE = 60_000;
 const HOUR = 60 * MINUTE;
 const DAY = 24 * HOUR;
 /**
  * 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 function renderDeploymentList(result, now, failed = false) {
     if (result.deployments.length === 0) {
@@ -251,6 +329,7 @@ export function renderDeploymentList(result, now, failed = false) {
         deployment.name,
         deployment.environment,
         deployment.state,
+        installedOnCell(deployment.installedOn, result.installations),
         deployment.lastCallAt === undefined
             ? '—'
             : `${elapsed(now - Date.parse(deployment.lastCallAt))} ago`,

package/dist/tooling/cli/orchestrate.js

@@ -16,7 +16,7 @@ import { listDeployments, renderDeploymentList } from './list.js';
 import { error, info, progress, warn } from './log.js';
 import { importModule, loadProject, runtimeEntrypoint, selectEnvironment, } from './project.js';
 import { runPublish } from './publish/index.js';
-import { RegistryCliError } from './registry/index.js';
+import { MINIMUM_INSTALLATIONS_CLI_VERSION, openDomainRegistry, RegistryCliError, } from './registry/index.js';
 import { executeTests } from './test.js';
 import { yankPublication, yankSummary } from './yank.js';
 const CONFIG_NAMES = ['astrale.config.ts', 'astrale.config.js', 'astrale.config.mjs'];
@@ -68,7 +68,7 @@ export async function run(argv) {
     }
     const project = await loadProject(configPath);
     if (parsed.command === 'list')
-        return list(parsed, project);
+        return list(parsed, project, projectDir);
     if (parsed.command === 'yank')
         return yank(parsed, project);
     if (parsed.command === 'dev') {
@@ -235,10 +235,14 @@ export async function run(argv) {
 }
 /**
  * `astrale-domain list`: the deployments of every Environment, or of the one `--environment`
- * names, as their hosts keep them for the caller. With `--json`, stdout carries only the
- * ListResultV1, and only when every host answered; notices go to stderr.
+ * names, as their hosts keep them for the caller, named by the registry's versions and placed on
+ * the instances each `--instance` says pin them. With `--json`, stdout
+ * carries only the ListResultV1, and only when every host and the registry answered; notices go to
+ * stderr. A registry that cannot be read (no Astrale CLI, one older than the listing's floor, Admin
+ * out of reach, an unreadable index) prints nothing on stdout and exits 1: versions are never
+ * dropped silently (AM-224).
  */
-async function list(parsed, project) {
+async function list(parsed, project, projectDir) {
     const origin = compile(project.domain).schema.compiled.root.origin;
     const environments = parsed.env === ''
         ? Object.entries(project.environments)
@@ -250,6 +254,13 @@ async function list(parsed, project) {
             environments,
             ...(parsed.identity === undefined ? {} : { identity: parsed.identity }),
             signal: lifecycle.signal,
+            registry: (signal) => openDomainRegistry({
+                projectDir,
+                ...(parsed.identity === undefined ? {} : { identity: parsed.identity }),
+                signal,
+                minimum: MINIMUM_INSTALLATIONS_CLI_VERSION,
+            }),
+            ...(parsed.instances === undefined ? {} : { instances: parsed.instances }),
         });
         for (const notice of listing.notices)
             warn(notice);
@@ -257,6 +268,13 @@ async function list(parsed, project) {
             error(`Environment ${failure.environment} could not be listed (${failure.adapter}): ` +
                 failure.error.message);
         }
+        if (listing.registryFailure !== undefined) {
+            const failure = listing.registryFailure;
+            error(failure instanceof RegistryCliError
+                ? `Domain registry: ${failure.code}: ${failure.message}`
+                : `Domain registry: ${failure.message}`);
+            return 1;
+        }
         if (parsed.json === true) {
             if (listing.failures.length > 0)
                 return 1;

package/dist/tooling/cli/registry/client.d.ts

@@ -1,6 +1,8 @@
 import type { Version } from '../../../platform/versioning/index.js';
 import type { RegistryExecutableDependencies } from './executable.js';
+import type { InstanceListing } from './installations.js';
 import type { RegistryProcessInput, RegistryProcessResult } from './process.js';
+export { RegistryCliError } from './error.js';
 /** A `sha256:` digest as the registry stores it. */
 export type RegistryDigest = `sha256:${string}`;
 /**
@@ -77,17 +79,6 @@ export interface RegistryYank {
         readonly yanked: boolean;
     };
 }
-/**
- * One refusal the Astrale CLI printed as its CT29 `{ error: { code, message, details? } }`, or a
- * registry command this SDK cannot read: `REGISTRY_CLI_FAILED` when the command printed no
- * registry document or did not finish, `REGISTRY_CLI_PROTOCOL` when its document is not the
- * requested answer.
- */
-export declare class RegistryCliError extends Error {
-    readonly code: string;
-    readonly details?: Readonly<Record<string, unknown>>;
-    constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>);
-}
 /** The Admin registry, read and changed through the Astrale CLI with the caller's own credential. */
 export interface DomainRegistry {
     /** The Domain's index, or `undefined` when it is absent or not readable by the caller. */
@@ -107,11 +98,18 @@ export interface DomainRegistry {
     yank(origin: string, version: Version, options: {
         readonly undo: boolean;
     }): Promise<RegistryYank>;
+    /**
+     * What one instance the CLI knows by that name runs, as its Kernel lists it for the caller
+     * (`astrale domain list -i <instance> --json`, CT24), or why that is unknown. Never throws for a
+     * refusal of that instance: an instance that cannot tell is a partial answer (AM-198).
+     */
+    instance(name: string): Promise<InstanceListing>;
 }
 export interface DomainRegistryDependencies {
     readonly resolve: (input: {
         readonly projectDir: string;
         readonly signal: AbortSignal;
+        readonly minimum?: string;
     }, dependencies?: RegistryExecutableDependencies) => Promise<string>;
     readonly run: (input: RegistryProcessInput) => Promise<RegistryProcessResult>;
 }
@@ -124,4 +122,6 @@ export declare function openDomainRegistry(input: {
     readonly projectDir: string;
     readonly identity?: string;
     readonly signal: AbortSignal;
+    /** The first CLI release serving every read the command makes (default: the registry). */
+    readonly minimum?: string;
 }, dependencies?: DomainRegistryDependencies): Promise<DomainRegistry>;

package/dist/tooling/cli/registry/client.js

@@ -3,27 +3,15 @@ import { BUNDLE_MEDIA_TYPE } from '@astrale-os/kernel-protocol/release/bundle';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
+import { RegistryCliError } from './error.js';
 import { resolveRegistryExecutable } from './executable.js';
-import { runRegistryProcess } from './process.js';
-/**
- * One refusal the Astrale CLI printed as its CT29 `{ error: { code, message, details? } }`, or a
- * registry command this SDK cannot read: `REGISTRY_CLI_FAILED` when the command printed no
- * registry document or did not finish, `REGISTRY_CLI_PROTOCOL` when its document is not the
- * requested answer.
- */
-export class RegistryCliError extends Error {
-    code;
-    details;
-    constructor(code, message, details) {
-        super(message);
-        this.name = 'RegistryCliError';
-        this.code = code;
-        if (details !== undefined)
-            this.details = details;
-    }
-}
+import { decodeInstanceListing, instanceRefusal, instanceTimeout, instanceUnreadable, } from './installations.js';
+import { RegistryProcessTimeoutError, runRegistryProcess } from './process.js';
+export { RegistryCliError } from './error.js';
 const INDEX_LIMIT = 8 * 1024 * 1024;
 const DOCUMENT_LIMIT = 256 * 1024;
+/** The tail of an instance listing's stderr that is kept: its machine error is printed last. */
+const MACHINE_ERROR_LIMIT = 16 * 1024;
 /** Admin bounds a stored bundle to 16 MiB; the download writes it to a file, not to stdout. */
 const BUNDLE_TIMEOUT_MS = 120_000;
 const INDEX_TIMEOUT_MS = 60_000;
@@ -33,6 +21,8 @@ const CHANGE_TIMEOUT_MS = 120_000;
 const PUBLISH_TIMEOUT_MS = 180_000;
 /** CT29 bounds the publish request the CLI reads on stdin to 64 KiB. */
 const REQUEST_LIMIT = 64 * 1024;
+/** One instance Kernel, then the registry and the deployment records it names (CT24). */
+const INSTANCE_TIMEOUT_MS = 60_000;
 /**
  * Open the Domain registry through one admitted Astrale CLI (CT29 plumbing); the CLI's configured
  * Admin target answers. Reads and publish run under `--as` when the caller names an identity, a
@@ -45,6 +35,7 @@ export async function openDomainRegistry(input, dependencies = {
     const executable = await dependencies.resolve({
         projectDir: input.projectDir,
         signal: input.signal,
+        ...(input.minimum === undefined ? {} : { minimum: input.minimum }),
     });
     const authority = input.identity === undefined ? [] : ['--as', input.identity];
     // A read or a publish runs in machine mode without prompts: a document or a refusal on stdout,
@@ -152,6 +143,38 @@ export async function openDomainRegistry(input, dependencies = {
                 ],
             }, { stdout: DOCUMENT_LIMIT, timeoutMs: CHANGE_TIMEOUT_MS, change: true }), { reference, version, undo: options.undo });
         },
+        async instance(name) {
+            let result;
+            try {
+                result = await dependencies.run({
+                    executable,
+                    // `domain list -i` prints its refusal as a machine error on stderr, not as a document on
+                    // stdout: only that error's code is read, never relayed.
+                    args: ['--ci', '--no-prompt', 'domain', 'list', '-i', name, '--json', ...authority],
+                    projectDir: input.projectDir,
+                    signal: input.signal,
+                    timeoutMs: INSTANCE_TIMEOUT_MS,
+                    stdoutLimit: INDEX_LIMIT,
+                    stderrLimit: MACHINE_ERROR_LIMIT,
+                });
+            }
+            catch (cause) {
+                if (cause instanceof RegistryProcessTimeoutError)
+                    return instanceTimeout();
+                throw cause;
+            }
+            if (result.code !== 0)
+                return instanceRefusal(result.stderr ?? '');
+            const document = parseDocument(result.stdout);
+            if (document === undefined)
+                return instanceUnreadable();
+            try {
+                return decodeInstanceListing(document);
+            }
+            catch {
+                return instanceUnreadable();
+            }
+        },
     });
 }
 function parseDocument(stdout) {

package/dist/tooling/cli/registry/error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * One refusal the Astrale CLI printed as its CT29 `{ error: { code, message, details? } }`, or a
+ * registry command this SDK cannot read: `REGISTRY_CLI_FAILED` when the command printed no
+ * registry document or did not finish, `REGISTRY_CLI_PROTOCOL` when its document is not the
+ * requested answer.
+ */
+export declare class RegistryCliError extends Error {
+    readonly code: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+    constructor(code: string, message: string, details?: Readonly<Record<string, unknown>>);
+}

package/dist/tooling/cli/registry/error.js

@@ -0,0 +1,17 @@
+/**
+ * One refusal the Astrale CLI printed as its CT29 `{ error: { code, message, details? } }`, or a
+ * registry command this SDK cannot read: `REGISTRY_CLI_FAILED` when the command printed no
+ * registry document or did not finish, `REGISTRY_CLI_PROTOCOL` when its document is not the
+ * requested answer.
+ */
+export class RegistryCliError extends Error {
+    code;
+    details;
+    constructor(code, message, details) {
+        super(message);
+        this.name = 'RegistryCliError';
+        this.code = code;
+        if (details !== undefined)
+            this.details = details;
+    }
+}

package/dist/tooling/cli/registry/executable.d.ts

@@ -5,6 +5,13 @@ import type { RegistryProcessInput, RegistryProcessResult } from './process.js';
  * 1.0.0-beta.127 and older were released without them.
  */
 export declare const MINIMUM_REGISTRY_CLI_VERSION = "1.0.0-beta.128";
+/**
+ * The first Astrale CLI release that serves what `astrale-domain list` reads beside the registry
+ * index: the instance listing (`astrale domain list -i <instance> --json`, CT24). It shipped after
+ * the registry plumbing, so this floor is named on its own and is never below the registry's;
+ * 1.0.0-beta.128 and older were released without it.
+ */
+export declare const MINIMUM_INSTALLATIONS_CLI_VERSION = "1.0.0-beta.129";
 export interface RegistryExecutableDependencies {
     readonly candidates: () => Promise<readonly string[]>;
     readonly run: (input: RegistryProcessInput) => Promise<RegistryProcessResult>;
@@ -17,4 +24,6 @@ export interface RegistryExecutableDependencies {
 export declare function resolveRegistryExecutable(input: {
     readonly projectDir: string;
     readonly signal: AbortSignal;
+    /** The first CLI release serving what the command reads, never below the registry floor. */
+    readonly minimum?: string;
 }, dependencies?: RegistryExecutableDependencies): Promise<string>;

package/dist/tooling/cli/registry/executable.js

@@ -10,6 +10,13 @@ import { runRegistryProcess } from './process.js';
  * 1.0.0-beta.127 and older were released without them.
  */
 export const MINIMUM_REGISTRY_CLI_VERSION = '1.0.0-beta.128';
+/**
+ * The first Astrale CLI release that serves what `astrale-domain list` reads beside the registry
+ * index: the instance listing (`astrale domain list -i <instance> --json`, CT24). It shipped after
+ * the registry plumbing, so this floor is named on its own and is never below the registry's;
+ * 1.0.0-beta.128 and older were released without it.
+ */
+export const MINIMUM_INSTALLATIONS_CLI_VERSION = '1.0.0-beta.129';
 /**
  * Resolve one Astrale CLI for a whole command, the official installation before PATH, and admit
  * it only when it serves the registry plumbing, so an older CLI is refused by name instead of
@@ -29,11 +36,15 @@ export async function resolveRegistryExecutable(input, dependencies = {
         stdoutLimit: 4 * 1024,
     });
     const version = result.stdout.trim().replace(/^v/u, '');
+    // Never below the registry plumbing every caller of this executable reads.
+    const minimum = input.minimum === undefined || semver.lt(input.minimum, MINIMUM_REGISTRY_CLI_VERSION)
+        ? MINIMUM_REGISTRY_CLI_VERSION
+        : input.minimum;
     if (result.code !== 0 || semver.valid(version) === null) {
-        throw new TypeError(`Astrale CLI did not report its version; ${MINIMUM_REGISTRY_CLI_VERSION} or newer is required to read the Domain registry.`);
+        throw new TypeError(`Astrale CLI did not report its version; ${minimum} or newer is required to read the Domain registry.`);
     }
-    if (semver.lt(version, MINIMUM_REGISTRY_CLI_VERSION)) {
-        throw new TypeError(`Astrale CLI ${version} cannot read the Domain registry; ${MINIMUM_REGISTRY_CLI_VERSION} or newer is required (astrale update).`);
+    if (semver.lt(version, minimum)) {
+        throw new TypeError(`Astrale CLI ${version} cannot read the Domain registry; ${minimum} or newer is required (astrale update).`);
     }
     return executable;
 }

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

@@ -3,4 +3,7 @@
  * registry plumbing (CT29), with the caller's own credential and the CLI's configured Admin target.
  */
 export { RegistryCliError, openDomainRegistry, type DomainRegistry, type DomainRegistryDependencies, type RegistryBundle, type RegistryDigest, type RegistryIndex, type RegistryPublication, type RegistryPublishRequest, type RegistryPublishResult, type RegistryPublishRetention, type RegistryYank, } from './client.js';
-export { MINIMUM_REGISTRY_CLI_VERSION, resolveRegistryExecutable } from './executable.js';
+export { MINIMUM_INSTALLATIONS_CLI_VERSION, MINIMUM_REGISTRY_CLI_VERSION, resolveRegistryExecutable, } from './executable.js';
+export { isAdminFailure } from './installations.js';
+export type { InstallationUnknownReason, InstanceInstallation, InstanceListing, } from './installations.js';
+export { RegistryProcessTimeoutError } from './process.js';

package/dist/tooling/cli/registry/index.js

@@ -3,4 +3,6 @@
  * registry plumbing (CT29), with the caller's own credential and the CLI's configured Admin target.
  */
 export { RegistryCliError, openDomainRegistry, } from './client.js';
-export { MINIMUM_REGISTRY_CLI_VERSION, resolveRegistryExecutable } from './executable.js';
+export { MINIMUM_INSTALLATIONS_CLI_VERSION, MINIMUM_REGISTRY_CLI_VERSION, resolveRegistryExecutable, } from './executable.js';
+export { isAdminFailure } from './installations.js';
+export { RegistryProcessTimeoutError } from './process.js';

package/dist/tooling/cli/registry/installations.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Why the installations of one instance are unknown, as its listing's refusal says (CT24, AM-225):
+ * an unknown instance is a partial answer, never "not installed" (AM-198).
+ * - `timeout`: it did not answer in time;
+ * - `refused`: its Kernel refused the read;
+ * - `unavailable`: it could not be reached, or answered nothing readable;
+ * - `unsupported`: its Kernel does not list installed releases (before K14, such as the 1Pact Host
+ *   on beta.117).
+ */
+export type InstallationUnknownReason = 'timeout' | 'refused' | 'unavailable' | 'unsupported';
+/** One installation the instance Kernel lists, as `astrale domain list -i --json` prints it. */
+export interface InstanceInstallation {
+    readonly origin: string;
+    /** The deployment URL the Kernel lists the pin under. */
+    readonly url: string;
+}
+/** What one instance answered to `astrale domain list -i <instance> --json` (CT24). */
+export type InstanceListing = {
+    readonly kind: 'listed';
+    /** The instance Kernel URL that answered. */
+    readonly kernel: string;
+    /**
+     * The listing's own `partial`: true when an origin it does not list may still run there. A
+     * Kernel lists only the installations the caller reads in its Domain directory and says
+     * nothing of the rest (AM-83, AM-84), so C7 always answers true.
+     */
+    readonly partial: boolean;
+    readonly installations: readonly InstanceInstallation[];
+} | {
+    readonly kind: 'unknown';
+    readonly reason: InstallationUnknownReason;
+    /** The CLI's error code, or the SDK's own when the CLI answered nothing readable. */
+    readonly code: string;
+};
+/**
+ * Decode one `astrale.installed-list` v1 document: the instance Kernel that answered, whether the
+ * listing may omit installations (`partial`, required) and the deployment URL of each
+ * installation. Anything else is refused.
+ */
+export declare function decodeInstanceListing(document: Readonly<Record<string, unknown>>): Extract<InstanceListing, {
+    readonly kind: 'listed';
+}>;
+/**
+ * Why an instance listing failed, from the machine error the CLI printed on stderr (the last line
+ * that is a JSON object with an `error` code): only that code is read, never its message, since
+ * stderr may name the caller's credential. A Kernel without the listing is `unsupported`; a timeout
+ * at any phase is `timeout`; a Kernel refusal is `refused`; anything else, a command that printed
+ * no machine error and a failed read of Admin's registry (`isAdminFailure`) included, is
+ * `unavailable`.
+ */
+export declare function instanceRefusal(stderr: string): Extract<InstanceListing, {
+    readonly kind: 'unknown';
+}>;
+/**
+ * Whether an instance listing failed on Admin's side, not the instance's: the listing also reads
+ * Admin's registry to name what runs there, and fails as a whole when that read fails (CT24, C7).
+ * Its codes are Admin's (`REGISTRY_*`, `ADMIN_*`), never the SDK's own `REGISTRY_CLI_*`.
+ */
+export declare function isAdminFailure(code: string): boolean;
+/** The instance did not answer within the probe's time. */
+export declare function instanceTimeout(): Extract<InstanceListing, {
+    readonly kind: 'unknown';
+}>;
+/** The CLI answered the instance listing with something this SDK cannot read. */
+export declare function instanceUnreadable(): Extract<InstanceListing, {
+    readonly kind: 'unknown';
+}>;