@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/environment/application/services.js

@@ -0,0 +1,89 @@
+// One-service verbs on this checkout's own running stack: `ps`, `restart`, `rebuild` and `exec`. Each
+// reaches the stack through the topology its runtime readiness authenticated, so the agent never names
+// the hashed Compose project, its files or its profiles, and every step is one the runtime owner plans.
+import { constants as osConstants } from 'node:os';
+import { cockpitCommand } from '../../fix-catalogue.js';
+import { ENVIRONMENT_CODES, errorCause, forwardedRefusal } from '../contract.js';
+import { DeclarationRefusalError, serviceNotDeclared } from '../declaration.js';
+import { admitRuntimeServiceHealth, observeRuntimeServiceStates, planRuntimeServiceExec, restartRuntimeService, startRuntimeService, } from '../runtime.js';
+import { collectFailureLogs } from './lifecycle.js';
+import { lifecycleRefusal } from './shared.js';
+async function observeStack(verb, configPath, adapters, service) {
+    let observed;
+    try {
+        observed = await adapters.observe({ configPath });
+    }
+    catch (error) {
+        if (error instanceof DeclarationRefusalError)
+            return forwardedRefusal([error.diagnostic]);
+        return lifecycleRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `${verb} could not reach this checkout's running stack: ${errorCause(error)}`, verb, `start the stack with ${cockpitCommand('up', { config: configPath })}, then rerun ${verb}`);
+    }
+    const declared = observed.topology.services.map(({ id }) => id);
+    if (service !== undefined && !declared.includes(service)) {
+        return forwardedRefusal([serviceNotDeclared(service, declared)]);
+    }
+    return observed;
+}
+export async function runServicePs(input, adapters) {
+    const observed = await observeStack('ps', input.configPath, adapters);
+    if ('kind' in observed)
+        return observed;
+    const states = await observeRuntimeServiceStates({ topology: observed.topology, execute: adapters.execute });
+    if (states.kind !== 'complete')
+        return lifecycleRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `the stack's service states are unavailable: ${states.reason}`, 'ps');
+    return { kind: 'complete', status: 0, diagnostics: [], result: { services: states.services } };
+}
+/**
+ * `restart` restarts the container in place; `rebuild` builds the service's image and replaces its
+ * container, for a change baked into the image. Both then wait for the service as `up` does and
+ * report its logs when it does not become healthy.
+ */
+export async function runServiceRestart(input, adapters) {
+    const observed = await observeStack(input.verb, input.configPath, adapters, input.service);
+    if ('kind' in observed)
+        return observed;
+    const run = { topology: observed.topology, service: input.service, execute: adapters.execute };
+    const outcome = input.verb === 'rebuild' ? await startRuntimeService({ ...run, rebuild: true }) : await restartRuntimeService(run);
+    const evidence = outcome.kind === 'observed' ? admitRuntimeServiceHealth(outcome.observation) : undefined;
+    if (!evidence) {
+        const logs = await collectFailureLogs(outcome.kind === 'observed' ? outcome.observation
+            : outcome.kind === 'failure' ? outcome.logs : undefined, input.service, adapters);
+        return forwardedRefusal([
+            { severity: 'error', code: ENVIRONMENT_CODES.LIFECYCLE_EVIDENCE_INVALID, target: input.service,
+                message: `service ${input.service} did not become healthy after ${input.verb}`,
+                fix: `fix the error in the log excerpt, then rerun ${input.verb}` },
+            ...logs
+        ]);
+    }
+    const recorded = observed.completedServices.find(({ service }) => service === input.service);
+    if (recorded && recorded.containerId !== evidence.containerId) {
+        const refused = await observed.recordContainer(input.service, evidence.containerId);
+        if (refused.length > 0)
+            return forwardedRefusal(refused);
+    }
+    return { kind: 'complete', status: 0, diagnostics: [],
+        result: { service: input.service, containerId: evidence.containerId, change: input.verb === 'rebuild' ? 'rebuilt' : 'restarted' } };
+}
+/**
+ * Runs a command inside one service's container in the foreground. A command that exits nonzero
+ * is the command's answer, not a cockpit failure, so its status passes through as `session` does.
+ */
+export async function runServiceExec(input, adapters) {
+    const observed = await observeStack('exec', input.configPath, adapters, input.service);
+    if ('kind' in observed)
+        return observed;
+    const planned = planRuntimeServiceExec({ topology: observed.topology, service: input.service, argv: input.argv, tty: input.tty });
+    if (!planned)
+        return lifecycleRefusal(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `the command for service ${input.service} could not be planned from the stack's topology`, input.service);
+    const child = await adapters.executeForeground(planned);
+    if (child.kind === 'refusal')
+        return { kind: 'refusal', status: child.code === ENVIRONMENT_CODES.EXECUTION_ABORTED ? 130 : 2, result: null,
+            diagnostics: [{ severity: 'error', code: child.code, target: input.service,
+                    message: `the command in service ${input.service} could not be run to completion` }] };
+    const signalNumber = child.signal ? osConstants.signals[child.signal] : undefined;
+    const status = signalNumber !== undefined ? 128 + signalNumber : child.exitCode;
+    return { kind: 'complete', status, diagnostics: status === 0 ? [] : [{
+                severity: 'error', code: ENVIRONMENT_CODES.EXECUTION_STEP_FAILED, target: input.service,
+                message: `the command in service ${input.service} ${child.signal ? `was terminated by ${child.signal}` : `exited with status ${child.exitCode}`}`,
+            }], result: { exitCode: child.exitCode, signal: child.signal } };
+}

package/dist/environment/application/siblings.d.ts

@@ -0,0 +1,43 @@
+import type { ExecuteProbeOutcome } from '../../environment-exec/execute.js';
+import { type Diagnostic, type EnvironmentDiagnostic, type ExecutionStep } from '../contract.js';
+import type { LoadedCockpitConfigResult } from './health.js';
+type Execute = (step: ExecutionStep) => Promise<ExecuteProbeOutcome>;
+interface SiblingCommandOutcome {
+    readonly status: number;
+    readonly diagnostics: readonly Diagnostic[];
+    readonly result: unknown;
+    readonly artifact?: string | null;
+    readonly destination?: null;
+}
+export interface UseCommandInput {
+    readonly configPath: string;
+    readonly slug: string;
+    /** Absolute; absent with `clear`. */
+    readonly checkout?: string;
+    readonly clear: boolean;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export declare function runUse(input: UseCommandInput, dependencies: Readonly<{
+    execute: Execute;
+}>): Promise<SiblingCommandOutcome>;
+export interface PullCommandInput {
+    readonly configPath: string;
+    readonly env: Readonly<Record<string, string | undefined>>;
+}
+export declare function runPull(input: PullCommandInput, dependencies: Readonly<{
+    execute: Execute;
+}>): Promise<SiblingCommandOutcome>;
+/**
+ * What doctor and preflight report about the served checkouts: each override and where it came
+ * from, an override that no longer names a checkout of its sibling, the environment files a worktree
+ * lacks, and a running stack whose siblings' dependencies or migrations moved since it came up.
+ */
+export declare function inspectServedSiblings(input: Readonly<{
+    configPath: string;
+    env: Readonly<Record<string, string | undefined>>;
+    /** The configuration the command already loaded; read again from `configPath` when absent. */
+    loaded?: LoadedCockpitConfigResult;
+}>, dependencies: Readonly<{
+    execute: Execute;
+}>): Promise<readonly EnvironmentDiagnostic[]>;
+export {};

package/dist/environment/application/siblings.js

@@ -0,0 +1,269 @@
+/**
+ * Sequences the commands that choose and refresh the checkouts a stack serves: `use` points a
+ * sibling at another checkout of its repository for this cockpit checkout, `pull` fast-forwards
+ * every checkout to its upstream, and doctor and preflight read the findings both leave behind.
+ * The decisions live in `sibling-checkouts.ts`, `sibling-pull.ts` and `stack-inputs.ts`.
+ */
+import { realpath } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { loadCockpitConfig } from '../../config/load.js';
+import { cockpitCommand } from '../../fix-catalogue.js';
+import { refusalOutcome } from '../../refusal.js';
+import { mounted } from '../../schema.js';
+import { listedSurfaceTargets } from '../../surfaces/harness-registry.js';
+import { ENVIRONMENT_CODES, errorCause, isMissing } from '../contract.js';
+import { createGitRunner, inspectSiblingCheckout, loadServedSiblings, missingEnvironmentFileDiagnostics, missingEnvironmentFiles, readSiblingCheckouts, SIBLING_CHECKOUTS_PATH, servedSiblings, vanishedServedCheckouts, writeSiblingCheckouts, } from '../sibling-checkouts.js';
+import { fastForwardCheckout } from '../sibling-pull.js';
+import { mapLimit } from '../map-limit.js';
+import { applyAgentGrants, inside, planAgentGrants } from '../served-checkout-grants.js';
+import { staleStackDiagnostics } from '../stack-inputs.js';
+async function gitOrRefusal(env, execute) {
+    const git = await createGitRunner(env, execute);
+    return 'unavailable' in git
+        ? refusalOutcome(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `Git is needed to read the checkouts and is unavailable: ${git.unavailable}`, 'git', 'install Git and put it on PATH, then rerun this command')
+        : git;
+}
+export async function runUse(input, dependencies) {
+    const loaded = await loadCockpitConfig(input.configPath);
+    if (loaded.kind !== 'complete')
+        return { status: 2, result: null, diagnostics: loaded.diagnostics };
+    const configPath = loaded.result.source.path;
+    const config = loaded.result.config;
+    const root = dirname(configPath);
+    const recorded = await readSiblingCheckouts(root);
+    if (recorded.kind !== 'complete')
+        return { status: 2, result: null, diagnostics: [recorded.diagnostic] };
+    const sibling = config.sibling.find(row => row.slug === input.slug);
+    // A sibling removed from cockpit.toml can still be forgotten, or doctor would name it forever.
+    if (!sibling && input.clear && Object.hasOwn(recorded.checkouts, input.slug)) {
+        const { [input.slug]: forgotten, ...others } = recorded.checkouts;
+        const grants = await planAgentGrants({ root, slug: input.slug, declared: undefined, served: undefined, targets: [] });
+        if (grants.kind !== 'complete')
+            return { status: 2, result: null, diagnostics: [grants.diagnostic] };
+        const written = await writeSiblingCheckouts(root, others);
+        if (written.kind !== 'complete')
+            return recordUnwritable(configPath, root, written.message);
+        const granted = await applyAgentGrants(root, grants.plan);
+        if (granted.kind !== 'complete')
+            return { status: 2, result: null, diagnostics: [granted.diagnostic] };
+        return { status: 0, diagnostics: [], destination: null, artifact: `Forgot the checkout recorded for ${input.slug}, which cockpit.toml no longer declares.\n`,
+            result: { slug: input.slug, overridden: false, previous: forgotten } };
+    }
+    if (!sibling) {
+        return refusalOutcome(ENVIRONMENT_CODES.SIBLING_CHECKOUT_UNKNOWN, `cockpit.toml declares no sibling ${input.slug}; it declares ${config.sibling.map(row => row.slug).join(', ')}`, input.slug, `name a declared sibling, or declare this one with ${cockpitCommand('sibling add', { operand: input.slug, config: configPath })}`);
+    }
+    const declaredPath = servedSiblings(root, config, {}).get(sibling.slug).declared;
+    // Compared with a resolved candidate, so a siblings root reached through a link still matches. A
+    // declared checkout not cloned yet stays as declared; one that cannot be resolved is not guessed at.
+    let declared = declaredPath;
+    try {
+        declared = await realpath(declaredPath);
+    }
+    catch (error) {
+        if (!isMissing(error))
+            return refusalOutcome(ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE, `the declared checkout of sibling ${sibling.slug}, ${declaredPath}, could not be resolved: ${errorCause(error)}`, declaredPath, 'make that directory and every directory above it readable, or correct sibling.dir in cockpit.toml, then run this command again');
+    }
+    const previous = recorded.checkouts[sibling.slug];
+    let served = declared;
+    let evidence;
+    if (!input.clear) {
+        const git = await gitOrRefusal(input.env, dependencies.execute);
+        if ('status' in git)
+            return git;
+        const inspected = await inspectSiblingCheckout({ sibling, declared, candidate: input.checkout, git });
+        if (inspected.kind === 'refusal')
+            return { status: 2, result: null, diagnostics: [inspected.diagnostic] };
+        served = inspected.directory;
+        evidence = inspected.evidence;
+    }
+    const { [sibling.slug]: _cleared, ...others } = recorded.checkouts;
+    // Naming the declared checkout is the same as clearing: it is what serves the sibling by default.
+    const checkouts = served === declared ? others : { ...others, [sibling.slug]: served };
+    // The tools that hold a committed grant for this sibling, as sync writes them.
+    const targets = mounted(config, config.environment.profiles).some(row => row.slug === sibling.slug) ? listedSurfaceTargets(config.surfaces.tools) : [];
+    const grants = await planAgentGrants({ root, slug: sibling.slug, declared, served, targets });
+    if (grants.kind !== 'complete')
+        return { status: 2, result: null, diagnostics: [grants.diagnostic] };
+    const written = previous === checkouts[sibling.slug] ? { kind: 'complete' } : await writeSiblingCheckouts(root, checkouts);
+    if (written.kind !== 'complete')
+        return recordUnwritable(configPath, root, written.message);
+    const granted = await applyAgentGrants(root, grants.plan);
+    if (granted.kind !== 'complete')
+        return { status: 2, result: null, diagnostics: [{ ...granted.diagnostic,
+                    message: `${served} was recorded for sibling ${sibling.slug}, but ${granted.diagnostic.message}` }] };
+    const current = servedSiblings(root, config, checkouts);
+    const entry = current.get(sibling.slug);
+    const diagnostics = [
+        ...missingEnvironmentFileDiagnostics(entry, entry.overridden ? await missingEnvironmentFiles(entry, sibling) : []),
+        // A running stack keeps the checkout it mounted until it is brought down and up again.
+        ...await staleStackDiagnostics(root, current),
+    ];
+    const covered = inside(served, declared);
+    const artifact = [
+        entry.overridden ? `Sibling ${sibling.slug} is now served from ${served} (${evidence === 'object-store' ? 'a worktree of' : 'a clone with the same origin as'} ${declared}).`
+            : `Sibling ${sibling.slug} is served from its declared checkout ${declared}${previous === undefined ? '' : ` again, no longer from ${previous}`}.`,
+        `Recorded for this cockpit checkout only, in ${SIBLING_CHECKOUTS_PATH}; up, the guard, doctor and preflight read it.`,
+        ...(grants.plan.lines.length > 0 ? [`${served} lies outside ${declared}, which the committed directory grants name:`, ...grants.plan.lines.map(line => `  ${line}`)] : []),
+        '',
+    ].join('\n');
+    return { status: 0, diagnostics, destination: null, artifact,
+        result: { slug: sibling.slug, declared, served, overridden: entry.overridden, ...(evidence ? { evidence } : {}),
+            ...(previous === undefined ? {} : { previous }), insideDeclared: covered, ...(grants.plan.report ? { agentGrants: grants.plan.report } : {}) } };
+}
+function recordUnwritable(configPath, root, reason) {
+    return refusalOutcome(ENVIRONMENT_CODES.SIBLING_CHECKOUT_RECORD_INVALID, `the sibling checkout record could not be written: ${reason}`, SIBLING_CHECKOUTS_PATH, `run ${cockpitCommand('sync', { config: configPath })} first if ${root}/.cockpit does not exist yet, or make it a plain directory you can write; then run this command again`);
+}
+const PULL_CONCURRENCY = 4;
+export async function runPull(input, dependencies) {
+    const loaded = await loadCockpitConfig(input.configPath);
+    if (loaded.kind !== 'complete')
+        return { status: 2, result: null, diagnostics: loaded.diagnostics };
+    const config = loaded.result.config;
+    const root = dirname(loaded.result.source.path);
+    const served = await loadServedSiblings(root, config);
+    if (served.kind !== 'complete')
+        return { status: 2, result: null, diagnostics: [served.diagnostic] };
+    const git = await gitOrRefusal(input.env, dependencies.execute);
+    if ('status' in git)
+        return git;
+    // The cockpit root first, then each sibling's declared checkout and any checkout `use` put in its
+    // place. A sibling that is not a repository (acquire = "none") is expected to have no Git history,
+    // and a cockpit root outside Git is doctor's readiness finding, not pull's.
+    const targets = [{ label: 'cockpit', path: root, expected: false }];
+    for (const sibling of config.sibling) {
+        const entry = served.siblings.get(sibling.slug);
+        targets.push({ label: sibling.slug, path: entry.declared, expected: sibling.acquire !== 'none' });
+        if (entry.overridden)
+            targets.push({ label: `${sibling.slug} (served)`, path: entry.served, expected: true });
+    }
+    // Where Git puts each target's repository: a string, nothing when there is no checkout there, or
+    // why a toplevel Git named could not be resolved, which is reported against the target's label.
+    const located = await Promise.all(targets.map(async (target) => {
+        const output = await git.run(target.path, 'pull:root', ['rev-parse', '--show-toplevel']);
+        if (output.kind !== 'complete')
+            return undefined;
+        try {
+            return await realpath(output.stdout);
+        }
+        catch (error) {
+            return isMissing(error) ? undefined : { unresolved: `its repository at ${output.stdout} could not be resolved: ${errorCause(error)}` };
+        }
+    }));
+    // Two targets in one repository (an in-repo cockpit is its own sibling) move once, under the first one's label.
+    const distinct = new Map();
+    located.forEach((toplevel, index) => { if (typeof toplevel === 'string' && !distinct.has(toplevel))
+        distinct.set(toplevel, targets[index]); });
+    const advanced = new Map(await mapLimit([...distinct], PULL_CONCURRENCY, async ([toplevel, target]) => [toplevel, { label: target.label, ...await fastForwardCheckout(git, toplevel) }]));
+    const rows = [];
+    const diagnostics = [];
+    const reported = new Set();
+    located.forEach((toplevel, index) => {
+        const target = targets[index];
+        if (toplevel === undefined) {
+            const row = { label: target.label, state: 'skipped', path: target.path, reason: 'there is no Git checkout there',
+                fix: `run ${cockpitCommand('setup', { config: loaded.result.source.path })} to clone it`, blocked: target.expected };
+            rows.push(row);
+            if (row.blocked)
+                diagnostics.push(skippedDiagnostic(row));
+            return;
+        }
+        if (typeof toplevel !== 'string') {
+            const row = { label: target.label, state: 'skipped', path: target.path, reason: toplevel.unresolved,
+                fix: 'make that directory and every directory above it readable, then run pull again', blocked: true };
+            rows.push(row);
+            diagnostics.push(skippedDiagnostic(row));
+            return;
+        }
+        if (reported.has(toplevel))
+            return;
+        reported.add(toplevel);
+        const row = advanced.get(toplevel);
+        rows.push(row);
+        if (row.state === 'skipped' && row.blocked)
+            diagnostics.push(skippedDiagnostic(row));
+    });
+    // A pulled lockfile or migration behind a running stack is the next thing to go wrong.
+    if (rows.some(row => row.state === 'advanced'))
+        diagnostics.push(...await staleStackDiagnostics(root, served.siblings));
+    const line = (row) => row.state === 'advanced'
+        ? `${row.label}: ${row.branch} fast-forwarded ${row.from.slice(0, 12)} -> ${row.to.slice(0, 12)} (${row.commits} commit${row.commits === 1 ? '' : 's'} from ${row.upstream})`
+        : row.state === 'current' ? `${row.label}: ${row.branch} is up to date with ${row.upstream}${row.ahead > 0 ? ` (${row.ahead} ahead)` : ''}`
+            : `${row.label}: skipped, ${row.reason}`;
+    return { status: 0, diagnostics, destination: null, artifact: `${rows.map(line).join('\n')}\n`, result: { repositories: rows } };
+}
+function skippedDiagnostic(row) {
+    return {
+        severity: 'warning',
+        code: 'PULL_SKIPPED',
+        message: `${row.label} at ${row.path} was left as it was: ${row.reason}`,
+        target: row.path,
+        fix: row.fix,
+    };
+}
+/**
+ * What doctor and preflight report about the served checkouts: each override and where it came
+ * from, an override that no longer names a checkout of its sibling, the environment files a worktree
+ * lacks, and a running stack whose siblings' dependencies or migrations moved since it came up.
+ */
+export async function inspectServedSiblings(input, dependencies) {
+    try {
+        return await servedSiblingFindings(input, dependencies);
+    }
+    catch (error) {
+        return [{ severity: 'warning', code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                message: `the checkouts serving the siblings could not be inspected: ${errorCause(error)}`, target: SIBLING_CHECKOUTS_PATH,
+                fix: 'rerun this command; if it persists, check that the sibling checkouts and .cockpit/local are readable' }];
+    }
+}
+async function servedSiblingFindings(input, dependencies) {
+    const loaded = input.loaded ?? await loadCockpitConfig(input.configPath);
+    // An unloadable cockpit.toml is reported by the command itself.
+    if (loaded.kind !== 'complete')
+        return [];
+    const config = loaded.result.config;
+    const root = dirname(loaded.result.source.path);
+    const recorded = await readSiblingCheckouts(root);
+    // `up` refuses an unreadable record, so the served-checkouts row fails on it too; this says why.
+    if (recorded.kind !== 'complete')
+        return [recorded.diagnostic];
+    const served = servedSiblings(root, config, recorded.checkouts);
+    const findings = [];
+    for (const slug of Object.keys(recorded.checkouts).filter(slug => !served.has(slug)))
+        findings.push({
+            severity: 'warning', code: 'SIBLING_CHECKOUT_UNKNOWN',
+            message: `${SIBLING_CHECKOUTS_PATH} names a checkout for ${slug}, which cockpit.toml no longer declares, so nothing serves it`,
+            target: SIBLING_CHECKOUTS_PATH,
+            fix: `forget it with ${cockpitCommand('use', { operand: slug, args: '--clear' })}`,
+        });
+    // A directory that is gone is the served-checkouts row's finding, which `up` refuses as well; it is not repeated here.
+    const gone = new Set((await vanishedServedCheckouts(served)).map(entry => entry.slug));
+    const overridden = [...served.values()].filter(entry => entry.overridden && !gone.has(entry.slug));
+    const git = overridden.length === 0 ? undefined : await createGitRunner(input.env, dependencies.execute);
+    const perEntry = await Promise.all(overridden.map(async (entry) => {
+        const sibling = config.sibling.find(row => row.slug === entry.slug);
+        const rows = [{
+                severity: 'info', code: 'SIBLING_CHECKOUT_OVERRIDDEN',
+                message: `sibling ${entry.slug} is served from ${entry.served}, recorded by use in ${SIBLING_CHECKOUTS_PATH}, instead of its declared checkout ${entry.declared}`,
+                target: `sibling:${entry.slug}`,
+                fix: `serve the declared checkout again with ${cockpitCommand('use', { operand: entry.slug, args: '--clear' })}`,
+            }];
+        if (git === undefined)
+            return rows;
+        if ('unavailable' in git) {
+            rows.push({ severity: 'warning', code: ENVIRONMENT_CODES.EVIDENCE_UNAVAILABLE,
+                message: `whether ${entry.served} is still a checkout of sibling ${entry.slug} could not be checked: ${git.unavailable}`,
+                target: entry.served, fix: 'install Git and put it on PATH, then rerun this command' });
+            return rows;
+        }
+        const inspected = await inspectSiblingCheckout({ sibling, declared: entry.declared, candidate: entry.served, git });
+        // `up` does not refuse a checkout of another repository, so these commands report it as a warning.
+        if (inspected.kind === 'refusal')
+            rows.push({ ...inspected.diagnostic, severity: 'warning' });
+        else
+            rows.push(...missingEnvironmentFileDiagnostics(entry, await missingEnvironmentFiles(entry, sibling)));
+        return rows;
+    }));
+    findings.push(...perEntry.flat());
+    findings.push(...await staleStackDiagnostics(root, served));
+    return findings;
+}

package/dist/environment/claims.d.ts

@@ -24,7 +24,7 @@ export declare function observeClaimState(input: {
     readonly stackId: StackId;
     readonly observedAt: string;
 }): Promise<EnvironmentObservation>;
-export interface ClaimHolder {
+interface ClaimHolder {
     readonly holderId: HolderId;
     readonly checkoutId: CheckoutId;
     readonly claimedAt: string;
@@ -47,8 +47,8 @@ export interface CoordinationRecord {
     readonly lastReleasedHolder: HolderId | null;
     readonly drain?: DrainReservation | null;
 }
-export type DrainPurpose = 'sleep' | 'down' | 'reset';
-export type DrainAction = {
+type DrainPurpose = 'sleep' | 'down' | 'reset';
+type DrainAction = {
     readonly stage: 'runtime-stop';
     readonly targetId: string;
     readonly validForMs: number;
@@ -84,7 +84,7 @@ export interface DrainReservation extends DrainReservationRequest {
     readonly progressRevision: number;
     readonly attempt: DrainAttempt | null;
 }
-export interface DrainAttempt {
+interface DrainAttempt {
     readonly attemptId: string;
     readonly reservationId: string;
     readonly purpose: DrainPurpose;
@@ -100,7 +100,7 @@ export interface DrainAttempt {
     readonly failedRevision: number | null;
     readonly failedAt: string | null;
 }
-export interface FailedReclaimRecoveryTarget {
+interface FailedReclaimRecoveryTarget {
     readonly targetId: string;
     readonly targetCommitment: DrainTargetCommitment;
 }
@@ -168,7 +168,7 @@ type ClaimMutationRefusal = {
     readonly kind: 'refusal';
     readonly diagnostics: readonly EnvironmentDiagnostic[];
 };
-export type ReleaseClaimResult = {
+type ReleaseClaimResult = {
     readonly kind: 'complete';
     readonly change: 'released' | 'unchanged';
     readonly decision: 'stop' | 'retain';
@@ -215,7 +215,7 @@ export declare function observeProcessStart(pid: number, host: ProcessHost): Pro
 /** The production `ProcessHost`: signal 0 and ps cross the executor, and /proc is read directly. */
 export declare function processHost(execute: (step: ExecutionStep) => Promise<ExecuteProbeOutcome>): ProcessHost;
 export declare function liveHolderMessage(holders: readonly ClaimHolder[]): string;
-export type ReleaseDeadSessionHoldersResult = {
+type ReleaseDeadSessionHoldersResult = {
     readonly kind: 'complete';
     readonly released: readonly ClaimHolder[];
 } | ClaimMutationRefusal;
@@ -264,7 +264,7 @@ export declare function addCoordinationHolder(value: CoordinationRecord, holder:
 export declare function removeExactCoordinationHolder(value: CoordinationRecord, holderId: HolderId): CoordinationRecord | undefined;
 export declare function coordinationStateRecord(namespace: StateNamespace, stackId: StackId, current: StateRecord | null, now: string, value: CoordinationRecord): StateRecord;
 export declare function isDrainActive(value: CoordinationRecord): boolean;
-export type DrainReservationResult = {
+type DrainReservationResult = {
     readonly kind: 'complete';
     readonly reservation: DrainReservation;
 } | ClaimMutationRefusal;
@@ -315,7 +315,7 @@ export declare function matchReclaimDrainContinuation(input: {
     readonly continuation: ReclaimDrainStep | null;
     readonly record: StateRecord;
 }): 'progressed' | 'failed' | 'unmatched';
-export type SleepDrainRecoveryInspection = {
+type SleepDrainRecoveryInspection = {
     readonly kind: 'none';
 } | {
     readonly kind: 'repairable';
@@ -328,7 +328,7 @@ export type SleepDrainRecoveryInspection = {
     /** The record inspected; recovery acts only while the stored record is still exactly this one. */
     readonly record: StateRecord;
 } | ClaimMutationRefusal;
-export type DestructiveDrainRecoveryInspection = {
+type DestructiveDrainRecoveryInspection = {
     readonly kind: 'none';
 } | {
     readonly kind: 'repairable';

package/dist/environment/claims.js

@@ -4,6 +4,7 @@ import { dirname, isAbsolute, join, normalize } from 'node:path';
 import { createHash, randomBytes } from 'node:crypto';
 import { platform } from 'node:os';
 import { STRUCTURED_INPUT_ENTRY_LIMIT } from '../schema.js';
+import { canonicalJson } from '../canonical-json.js';
 import { hasErrorCode, RefusalError, ENVIRONMENT_CODES, errorCause, isCanonicalTimestamp, snapshotJson, snapshotExecutionPlan, snapshotEnvironmentObservation, } from './contract.js';
 import { authenticatedExecutionOutcome, consumeFencedExecutionTermination } from '../environment-exec/execute.js';
 import { resolveExecutablePath } from './executable.js';
@@ -108,18 +109,9 @@ const DrainAttemptSchema = z.object({
         context.addIssue({ code: 'custom', message: 'drain attempt targets are not canonical' });
     }
 });
-function canonicalJsonValue(value) {
-    if (Array.isArray(value))
-        return value.map(canonicalJsonValue);
-    if (value !== null && typeof value === 'object') {
-        return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
-            .map(([key, item]) => [key, canonicalJsonValue(item)]));
-    }
-    return value;
-}
 function isCanonicalJson(body) {
     try {
-        return JSON.stringify(canonicalJsonValue(JSON.parse(body))) === body;
+        return canonicalJson(JSON.parse(body)) === body;
     }
     catch {
         // Unparseable JSON is simply not canonical.
@@ -907,7 +899,7 @@ function exactRecordFingerprint(record) {
         || typeof candidate.updatedAt !== 'string' || !isCanonicalTimestamp(candidate.updatedAt)
         || !z.json().safeParse(candidate.value).success)
         return undefined;
-    return JSON.stringify(canonicalJsonValue(snapshot));
+    return canonicalJson(snapshot);
 }
 export function isDrainActive(value) {
     return value.drain != null;

package/dist/environment/compose-topology.d.ts

@@ -8,7 +8,7 @@ import type { ResolvedExecutable } from './executable.js';
  * repository's Compose file names `./api` relative to the repository.
  */
 export declare function composeProjectDirectory(root: string, references: readonly string[]): string;
-export interface ComposeTopologyInput {
+interface ComposeTopologyInput {
     /** Canonical absolute cockpit root. */
     readonly root: string;
     /** The declared `environment.compose_files`, relative to `root`. */
@@ -20,7 +20,7 @@ export interface ComposeTopologyInput {
     /** Filtered to the Docker connection variables before it reaches the probe. */
     readonly env: Readonly<Record<string, string | undefined>>;
 }
-export interface ComposePublishedPort {
+interface ComposePublishedPort {
     /** The host side exactly as written, `null` when Compose picks an ephemeral host port. */
     readonly published: string | null;
     /** The host interface exactly as written, `null` when none is given, so Docker binds every interface. */
@@ -33,20 +33,24 @@ export interface ComposeServiceTopology {
     readonly healthcheck: boolean;
     readonly image: string | null;
     readonly build: boolean;
+    /** The service's fixed `container_name`, `null` when Compose names the container itself. */
+    readonly containerName: string | null;
     /**
      * Each volume source as Compose reports it without interpolation: the absolute host path of a
      * bind, or the raw `${VAR}` text of a source still waiting for its variable.
      */
     readonly mountSources: readonly string[];
+    /** The Compose profiles that enable the service; absent or empty when it always runs. */
+    readonly profiles?: readonly string[];
 }
 /** A `[[sibling]]` row as the mount detector needs it: its absolute checkout path and variable. */
-export interface ComposeSiblingMount {
+interface ComposeSiblingMount {
     readonly slug: string;
     readonly var: string;
     readonly mount: string;
     readonly path: string;
 }
-export type ComposeTopologyObservation = Readonly<{
+type ComposeTopologyObservation = Readonly<{
     kind: 'complete';
     services: readonly ComposeServiceTopology[];
 }> | Readonly<{
@@ -93,11 +97,11 @@ export declare function compareBindSources(binds: readonly string[], declared: r
  * Docker follows a symbolic link in the bind source, so `./api/cache -> /` would otherwise hand
  * the host root to a container under a mount = "always" checkout.
  */
-export declare function redirectedBindSources(binds: readonly string[], declared: readonly string[]): Promise<readonly Readonly<{
+export declare function redirectedBindSources(binds: readonly string[], declared: readonly string[], resolve?: (path: string) => Promise<string>): Promise<readonly Readonly<{
     bind: string;
     holder: string;
 }>[]>;
-export interface ComposeTopologyDeclarations {
+interface ComposeTopologyDeclarations {
     /** From composeProjectDirectory; a relative bind source, or a variable's relative default, resolves against it. */
     readonly projectDirectory: string;
     readonly portVariables: readonly string[];
@@ -107,11 +111,15 @@ export interface ComposeTopologyDeclarations {
         declared: string;
         path: string;
     }>[];
+    /** The `environment.profiles` every `up` activates. */
+    readonly profiles?: readonly string[];
 }
 /**
  * Judges a cockpit's own Compose topology. A host port that is not drawn from a leased
  * `ports.bases` variable is the same number in every worktree and parallel stack, so the second
- * stack to start fails to bind it; the remaining findings are warnings about what cockpit can
+ * stack to start fails to bind it; a fixed `container_name` fails the same way, and a fixed tag on a
+ * built image is shared the same way. The remaining findings are warnings about what cockpit can
  * then promise, not about whether the stack runs.
  */
 export declare function assessComposeTopology(services: readonly ComposeServiceTopology[], declarations: ComposeTopologyDeclarations): Promise<readonly Diagnostic[]>;
+export {};