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

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

@@ -0,0 +1,346 @@
+import * as artifact from '@astrale-os/kernel-protocol/artifact';
+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 { 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;
+/** One change is a token exchange and one Admin call, each bounded by the CLI itself. */
+const CHANGE_TIMEOUT_MS = 120_000;
+/** Admin re-reads the release at the deployment and verifies it before it commits. */
+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
+ * yank under the CLI's default identity.
+ */
+export async function openDomainRegistry(input, dependencies = {
+    resolve: resolveRegistryExecutable,
+    run: runRegistryProcess,
+}) {
+    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,
+    // never an interactive sign-in.
+    const machine = (args) => Object.freeze({
+        command: args.slice(0, 2).join(' '),
+        args: ['--ci', '--no-prompt', ...args, '--json', ...authority],
+    });
+    const command = async (invocation, limits) => {
+        let result;
+        try {
+            result = await dependencies.run({
+                executable: invocation.executable,
+                args: invocation.args,
+                projectDir: input.projectDir,
+                signal: input.signal,
+                timeoutMs: limits.timeoutMs,
+                stdoutLimit: limits.stdout,
+                ...(invocation.stdin === undefined ? {} : { stdin: invocation.stdin }),
+            });
+        }
+        catch (cause) {
+            // An interruption is the caller's own stop, never a registry answer.
+            if (input.signal.aborted)
+                throw cause;
+            throw unfinished(invocation, limits.change, cause);
+        }
+        const document = parseDocument(result.stdout);
+        if (result.code === 0 && document !== undefined)
+            return document;
+        throw refusal(invocation, result.code, document);
+    };
+    return Object.freeze({
+        async index(origin) {
+            try {
+                return decodeIndex(await command({ executable, ...machine(['domain', 'versions', origin]) }, { stdout: INDEX_LIMIT, timeoutMs: INDEX_TIMEOUT_MS, change: false }), origin);
+            }
+            catch (cause) {
+                if (cause instanceof RegistryCliError && cause.code === 'REGISTRY_DOMAIN_NOT_FOUND') {
+                    return undefined;
+                }
+                throw cause;
+            }
+        },
+        async bundle(origin, publication) {
+            const directory = await mkdtemp(join(tmpdir(), 'astrale-registry-'));
+            try {
+                const output = join(directory, 'bundle.json');
+                const reference = `${origin}@${publication.version}`;
+                const downloaded = decodeBundleDocument(await command({
+                    executable,
+                    ...machine(['__domain-registry', 'bundle', reference, '--output', output]),
+                    // The private download directory is gone after the run, and the CLI refuses an
+                    // output it cannot write before any read: a rerun by hand names its own file.
+                    rerun: machine(['__domain-registry', 'bundle', reference, '--output', 'bundle.json'])
+                        .args,
+                }, { stdout: DOCUMENT_LIMIT, timeoutMs: BUNDLE_TIMEOUT_MS, change: false }), origin, publication);
+                const bytes = new Uint8Array(await readFile(output));
+                const identified = artifact.identify(bytes, BUNDLE_MEDIA_TYPE);
+                if (identified.digest !== downloaded.digest ||
+                    identified.size !== downloaded.size ||
+                    identified.mediaType !== downloaded.mediaType) {
+                    throw protocolError(`The bundle of ${origin}@${publication.version} does not match its digest.`);
+                }
+                return bytes;
+            }
+            finally {
+                await rm(directory, { recursive: true, force: true });
+            }
+        },
+        async publish(request) {
+            const stdin = JSON.stringify({
+                format: 'astrale.registry-publish-request',
+                version: 1,
+                publication: {
+                    origin: request.origin,
+                    version: request.version,
+                    url: request.url,
+                    releaseDigest: request.releaseDigest,
+                    ...(request.commit === undefined ? {} : { commit: request.commit }),
+                    dirty: request.dirty,
+                },
+            });
+            if (Buffer.byteLength(stdin) > REQUEST_LIMIT) {
+                throw new TypeError(`The publish request of ${request.origin}@${request.version} is too large.`);
+            }
+            const invocation = { executable, ...machine(['__domain-registry', 'publish']), stdin };
+            return decodePublishResult(await command(invocation, {
+                stdout: DOCUMENT_LIMIT,
+                timeoutMs: PUBLISH_TIMEOUT_MS,
+                change: true,
+            }), request);
+        },
+        async yank(origin, version, options) {
+            const reference = `${origin}@${version}`;
+            return decodeYank(await command({
+                executable,
+                command: '__domain-registry yank',
+                args: [
+                    '__domain-registry',
+                    'yank',
+                    reference,
+                    ...(options.undo ? ['--undo'] : []),
+                    '--json',
+                ],
+            }, { 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) {
+    try {
+        const value = JSON.parse(stdout);
+        return isRecord(value) ? value : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function refusal(invocation, code, document) {
+    const error = document === undefined ? undefined : document.error;
+    if (isRecord(error) && typeof error.code === 'string' && typeof error.message === 'string') {
+        const details = isRecord(error.details) ? error.details : undefined;
+        return new RegistryCliError(admittedCode(error.code), printable(error.message), details);
+    }
+    return new RegistryCliError('REGISTRY_CLI_FAILED', `${code === 0
+        ? `Astrale CLI ${invocation.command} answered no registry document.`
+        : `Astrale CLI ${invocation.command} failed (exit ${code}) without a registry document.`} ${diagnosticHint(invocation)}`);
+}
+/**
+ * The command was stopped or could not run (start failure, time or output bound). A change may
+ * still have reached Admin; CT29 changes are idempotent, so the same command is safe to rerun.
+ */
+function unfinished(invocation, change, cause) {
+    const reason = cause instanceof Error ? cause.message : 'Astrale CLI command failed.';
+    const delivery = change ? ' The change may have applied; rerunning the same command is safe.' : '';
+    const error = new RegistryCliError('REGISTRY_CLI_FAILED', `${reason}${delivery} ${diagnosticHint(invocation)}`);
+    error.cause = cause;
+    return error;
+}
+/**
+ * The CLI's stderr is never relayed (it may name the caller's credential), so a failure names the
+ * exact command a person runs by hand to read the CLI's own diagnostic.
+ */
+function diagnosticHint(invocation) {
+    return `To read the Astrale CLI's own diagnostic, run: ${commandLine(invocation)}`;
+}
+/** One invocation as a person runs it by hand in a POSIX shell. */
+function commandLine(invocation) {
+    const words = [invocation.executable, ...(invocation.rerun ?? invocation.args)].map(shellWord);
+    // A command that reads a document on stdin is rerun with that same document.
+    const input = invocation.stdin === undefined ? '' : `printf '%s' ${shellWord(invocation.stdin)} | `;
+    return `${input}${words.join(' ')}`;
+}
+function shellWord(word) {
+    return /^[\w@%+=:,./-]+$/u.test(word) ? word : `'${word.replaceAll("'", `'\\''`)}'`;
+}
+function decodeIndex(document, origin) {
+    if (document.format !== 'astrale.registry-index' ||
+        document.version !== 1 ||
+        document.origin !== origin ||
+        !Array.isArray(document.publications)) {
+        throw protocolError(`Astrale CLI answered no registry index of ${origin}.`);
+    }
+    return Object.freeze({
+        origin,
+        publications: Object.freeze(document.publications.map((entry) => publication(entry, origin))),
+    });
+}
+function publication(input, origin) {
+    if (!isRecord(input) ||
+        typeof input.version !== 'string' ||
+        typeof input.yanked !== 'boolean' ||
+        !isDigest(input.releaseDigest) ||
+        !isDigest(input.buildDigest) ||
+        !isDigest(input.schemaRevision)) {
+        throw protocolError(`Astrale CLI answered a malformed Publication of ${origin}.`);
+    }
+    return Object.freeze({
+        version: input.version,
+        yanked: input.yanked,
+        releaseDigest: input.releaseDigest,
+        buildDigest: input.buildDigest,
+        schemaRevision: input.schemaRevision,
+    });
+}
+/**
+ * Admit the CT29 `PublishResultV1` only as the answer to this request: the same version, URL and
+ * release digest, so a CLI that answered for another Publication is never reported as published.
+ * Any other key is ignored, such as the `retention` mark an Admin before admin#455 still answers:
+ * Admin keeps no Services mark any more, since Services keeps every deployment until it is retired.
+ */
+function decodePublishResult(document, request) {
+    const named = document.publication;
+    if (document.format !== 'astrale.registry-publish-result' ||
+        document.version !== 1 ||
+        (document.status !== 'created' && document.status !== 'unchanged') ||
+        !isRecord(named) ||
+        typeof named.url !== 'string') {
+        throw protocolError(`Astrale CLI answered no publish result of ${request.origin}@${request.version}.`);
+    }
+    const published = publication(named, request.origin);
+    if (published.version !== request.version ||
+        published.releaseDigest !== request.releaseDigest ||
+        named.url !== request.url) {
+        throw protocolError(`Astrale CLI answered another Publication than ${request.origin}@${request.version} at ${request.url}.`);
+    }
+    return Object.freeze({
+        status: document.status,
+        publication: Object.freeze({ ...published, url: named.url }),
+    });
+}
+function decodeBundleDocument(document, origin, expected) {
+    const named = document.publication;
+    if (document.format !== 'astrale.registry-bundle' ||
+        document.version !== 1 ||
+        !isRecord(named) ||
+        named.origin !== origin ||
+        named.version !== expected.version) {
+        throw protocolError(`Astrale CLI answered no bundle of ${origin}@${expected.version}.`);
+    }
+    return bundle(document.bundle, origin, expected.version);
+}
+function bundle(input, origin, version) {
+    if (!isRecord(input) ||
+        !isDigest(input.digest) ||
+        typeof input.mediaType !== 'string' ||
+        !Number.isSafeInteger(input.size) ||
+        input.size < 0) {
+        throw protocolError(`Astrale CLI answered a malformed bundle of ${origin}@${version}.`);
+    }
+    return Object.freeze({
+        digest: input.digest,
+        mediaType: input.mediaType,
+        size: input.size,
+    });
+}
+/**
+ * The answered version must be the one named, and its state the one requested: a yank answers
+ * `yanked: true` and `--undo` answers `yanked: false`, whether it `changed` or was `unchanged`.
+ */
+function decodeYank(document, expected) {
+    const { status, publication } = document;
+    if (document.format !== 'astrale.registry-yank-result' ||
+        document.version !== 1 ||
+        (status !== 'changed' && status !== 'unchanged') ||
+        !isRecord(publication) ||
+        publication.version !== expected.version ||
+        typeof publication.yanked !== 'boolean') {
+        throw protocolError(`Astrale CLI answered no yank result of ${expected.reference}.`);
+    }
+    if (publication.yanked === expected.undo) {
+        throw protocolError(`Astrale CLI answered ${expected.reference} ${publication.yanked ? 'still yanked' : 'not yanked'} after ${expected.undo ? 'yank --undo' : 'yank'}.`);
+    }
+    return Object.freeze({
+        status,
+        publication: Object.freeze({ version: expected.version, yanked: publication.yanked }),
+    });
+}
+function protocolError(message) {
+    return new RegistryCliError('REGISTRY_CLI_PROTOCOL', message);
+}
+function isDigest(input) {
+    return typeof input === 'string' && /^sha256:[0-9a-f]{64}$/u.test(input);
+}
+function admittedCode(input) {
+    return /^[A-Z][A-Z0-9_]{0,63}$/u.test(input) ? input : 'REGISTRY_CLI_FAILED';
+}
+/** A CLI message enters a terminal and a CI log: control characters are dropped, length bounded. */
+function printable(input) {
+    // oxlint-disable-next-line no-control-regex
+    const text = input.replace(/[\u0000-\u001f\u007f-\u009f]+/gu, ' ').trim();
+    return text.length > 500 ? `${text.slice(0, 499)}…` : text;
+}
+function isRecord(input) {
+    return typeof input === 'object' && input !== null && !Array.isArray(input);
+}

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

@@ -0,0 +1,29 @@
+import type { RegistryProcessInput, RegistryProcessResult } from './process.js';
+/**
+ * The first Astrale CLI release that serves the registry plumbing these commands read (CT29):
+ * `astrale domain versions --json` and the hidden `astrale __domain-registry` commands.
+ * 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>;
+}
+/**
+ * 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
+ * answering an unknown command.
+ */
+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

@@ -0,0 +1,90 @@
+import { constants } from 'node:fs';
+import { access, readFile, realpath } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { delimiter, isAbsolute, join } from 'node:path';
+import semver from 'semver';
+import { runRegistryProcess } from './process.js';
+/**
+ * The first Astrale CLI release that serves the registry plumbing these commands read (CT29):
+ * `astrale domain versions --json` and the hidden `astrale __domain-registry` commands.
+ * 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
+ * answering an unknown command.
+ */
+export async function resolveRegistryExecutable(input, dependencies = {
+    candidates: executableCandidates,
+    run: runRegistryProcess,
+}) {
+    const executable = await firstExecutable(await dependencies.candidates());
+    const result = await dependencies.run({
+        executable,
+        args: ['--version'],
+        projectDir: input.projectDir,
+        signal: input.signal,
+        timeoutMs: 10_000,
+        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} or newer is required to read the Domain registry.`);
+    }
+    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;
+}
+async function firstExecutable(candidates) {
+    for (const candidate of candidates) {
+        try {
+            await access(candidate, constants.X_OK);
+            return await realpath(candidate);
+        }
+        catch {
+            // Continue through the recorded installation and PATH candidates.
+        }
+    }
+    throw new TypeError('Astrale CLI is unavailable. Install it with the official Astrale installer.');
+}
+/** The installer's recorded binary (`$ASTRALE_HOME/install.json`), then every `astrale` on PATH. */
+async function executableCandidates() {
+    const path = (process.env.PATH ?? '')
+        .split(delimiter)
+        .filter(Boolean)
+        .map((directory) => join(directory, 'astrale'));
+    const installed = await recordedInstallation();
+    return installed === undefined ? path : [installed, ...path];
+}
+async function recordedInstallation() {
+    const home = process.env.ASTRALE_HOME ?? join(homedir(), '.astrale');
+    try {
+        const decoded = JSON.parse(await readFile(join(home, 'install.json'), 'utf8'));
+        if (typeof decoded !== 'object' ||
+            decoded === null ||
+            !('method' in decoded) ||
+            decoded.method !== 'script' ||
+            !('bin' in decoded) ||
+            typeof decoded.bin !== 'string' ||
+            !isAbsolute(decoded.bin)) {
+            return undefined;
+        }
+        return decoded.bin;
+    }
+    catch {
+        return undefined;
+    }
+}

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

@@ -0,0 +1,9 @@
+/**
+ * The Admin Domain registry as Project commands read and change it: through the Astrale CLI's
+ * 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 RegistryYank, } from './client.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

@@ -0,0 +1,8 @@
+/**
+ * The Admin Domain registry as Project commands read and change it: through the Astrale CLI's
+ * registry plumbing (CT29), with the caller's own credential and the CLI's configured Admin target.
+ */
+export { RegistryCliError, openDomainRegistry, } from './client.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';
+}>;