@b00dea/cockpit 0.0.0-stage → 0.1.0

package/dist/environment/generated-application/authorities.js

@@ -0,0 +1,61 @@
+import { resolve } from 'node:path';
+import { consumeWorkEnvironmentConfigProjection, loadCockpitConfig, projectWorkEnvironmentConfig } from '../../config/load.js';
+import { CORE_EVALUATOR_ASSET as EVALUATOR_ASSET } from '../../surfaces/core-declarations.js';
+import { nodeAuthority, readAnchoredFile } from '../../generated-environment/transaction.js';
+import { TESTING_GUIDE_REGISTRY, createGateRegistry } from '../../testing/gates.js';
+import { refusalOutcome as refuse } from '../../refusal.js';
+import { MAX_SURFACE_FILE_BYTES, SURFACE_ROOT, defaultAdapters, issuedApplicationProjections, issuedWorkApplicationAuthorities, projectedWorkApplicationAuthorities, readSurfaceAsset, sha256, } from './shared.js';
+import { commandInput } from './prepare.js';
+export function generatedApplicationProjection(value) {
+    return value !== null && typeof value === 'object' && issuedApplicationProjections.has(value)
+        ? value : undefined;
+}
+export function projectWorkApplicationAuthorities(application) {
+    if (application === null || typeof application !== 'object' || projectedWorkApplicationAuthorities.has(application))
+        return undefined;
+    const record = issuedApplicationProjections.get(application);
+    if (!record?.workApplication)
+        return undefined;
+    const projection = { kind: 'work-application-authorities' };
+    projectedWorkApplicationAuthorities.add(application);
+    issuedWorkApplicationAuthorities.set(projection, record.workApplication);
+    return projection;
+}
+export function consumeWorkApplicationAuthorities(projection) {
+    if (projection === null || typeof projection !== 'object')
+        return undefined;
+    const record = issuedWorkApplicationAuthorities.get(projection);
+    if (!record)
+        return undefined;
+    issuedWorkApplicationAuthorities.delete(projection);
+    return record;
+}
+export async function prepareWorkApplicationAuthorities(input) {
+    const request = commandInput(input);
+    if (!request)
+        return refuse('GENERATED_INPUT_INVALID', 'work application input is invalid', 'work');
+    const loaded = await loadCockpitConfig(request.configPath);
+    if (loaded.kind !== 'complete')
+        return {
+            kind: 'refusal', artifact: null, destination: null, result: null, status: 2,
+            diagnostics: [...loaded.diagnostics],
+        };
+    const configProjection = projectWorkEnvironmentConfig(loaded.result);
+    const workEnvironment = configProjection && consumeWorkEnvironmentConfigProjection(configProjection);
+    const node = await nodeAuthority();
+    if (!workEnvironment || !node)
+        return refuse('GENERATED_RENDER_UNAUTHENTICATED', 'work configuration or Node authority is unavailable', request.configPath);
+    const read = await readAnchoredFile(SURFACE_ROOT, EVALUATOR_ASSET, MAX_SURFACE_FILE_BYTES, node, defaultAdapters);
+    const evaluator = readSurfaceAsset(EVALUATOR_ASSET, read);
+    if (!evaluator)
+        return refuse('SURFACE_INPUT_INVALID', 'the shipped evaluator could not be authenticated', EVALUATOR_ASSET);
+    const projection = { kind: 'work-application-authorities' };
+    issuedWorkApplicationAuthorities.set(projection, Object.freeze({
+        workEnvironment,
+        evaluator: Object.freeze({ path: resolve(SURFACE_ROOT, evaluator.path), bytes: evaluator.bytes,
+            sha256: evaluator.sha256, identity: evaluator.identity, restriction: 'instructed' }),
+        installedSkills: Object.freeze([]),
+        testing: Object.freeze({ registry: workEnvironment.testing ? createGateRegistry(workEnvironment.testing.declarations) : TESTING_GUIDE_REGISTRY }),
+    }));
+    return projection;
+}

package/dist/environment/generated-application/bootstrap-skill.d.ts

@@ -0,0 +1,16 @@
+import { type SurfaceTarget } from '../../surfaces/contract.js';
+import type { SurfacePriorOwnedEntry } from '../../surfaces/ownership.js';
+import type { ResolvedExecutable } from '../executable.js';
+import { type GeneratedEnvironmentCommandAdapters, type GeneratedEnvironmentSyncInput, type SelectedBootstrapPublicationAuthority, type SelectedBootstrapResumeInput, type SelectedBootstrapResumeOutcome, type SelectedBootstrapSurfaceInput, type SelectedBootstrapSurfaceOutcome } from './shared.js';
+export declare function prepareSelectedBootstrapSurface(input: SelectedBootstrapSurfaceInput, adapterOverrides?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<SelectedBootstrapSurfaceOutcome>;
+export declare function applySelectedBootstrapSurface(authority: SelectedBootstrapPublicationAuthority): Promise<SelectedBootstrapSurfaceOutcome>;
+export declare function resumeSelectedBootstrapSurface(input: SelectedBootstrapResumeInput, adapterOverrides?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<SelectedBootstrapResumeOutcome>;
+export declare function authenticatedBootstrapPriorSurfaces(root: string, state: NonNullable<GeneratedEnvironmentSyncInput['bootstrapState']>, node: ResolvedExecutable, adapters: GeneratedEnvironmentCommandAdapters): Promise<readonly SurfacePriorOwnedEntry[] | undefined>;
+export declare function unfinishedInitSurfaces(root: string, node: ResolvedExecutable, adapters: GeneratedEnvironmentCommandAdapters): Promise<UnfinishedInit | undefined>;
+export interface UnfinishedInit {
+    readonly root: string;
+    readonly target: SurfaceTarget;
+    readonly published: readonly string[];
+    /** Absent when the files no longer hold what init recorded, so sync cannot take them over. */
+    readonly surfaces: readonly SurfacePriorOwnedEntry[] | undefined;
+}

package/dist/environment/generated-application/bootstrap-skill.js

@@ -0,0 +1,328 @@
+import { lstat, realpath } from 'node:fs/promises';
+import { isAbsolute, join, resolve } from 'node:path';
+import { SURFACE_TARGETS } from '../../surfaces/contract.js';
+import { CORE_PROCEDURE_ASSETS as PROCEDURE_ASSETS, CORE_SKILL_ASSETS as SKILL_ASSETS, shippedSkillSources, } from '../../surfaces/core-declarations.js';
+import { SHIPPED_SETUP_SKILL, inspectSkillSet, projectInspectedSkillOutputs } from '../../surfaces/skill-contract.js';
+import { nodeAuthority, readAnchoredEntry, readAnchoredBatches, expectedState, admitPublicationPlan, runPublicationPlan, } from '../../generated-environment/transaction.js';
+import { errorCause, RefusalError } from '../contract.js';
+import { authenticateStatePublication, readState, selectBootstrapStateRoot } from '../state.js';
+import { exactKeys } from '../../exact-keys.js';
+import { refusalOutcome as refuse } from '../../refusal.js';
+import { MAX_OWNERSHIP_BYTES, MAX_SURFACE_FILE_BYTES, OWNERSHIP_PATH, SURFACE_ROOT, consumedBootstrapStatePublications, issuedSelectedBootstrapAuthorities, mergedAdapters, ownRecord, readSurfaceAsset, sha256, sourceIdentity, } from './shared.js';
+import { prepare, readOwnership } from './prepare.js';
+function selectedBootstrapInput(input) {
+    const record = ownRecord(input);
+    if (!record || !exactKeys(record, ['root', 'target', 'tools']) || typeof record.root !== 'string'
+        || !isAbsolute(record.root) || resolve(record.root) !== record.root
+        || !SURFACE_TARGETS.includes(record.target)
+        || !Array.isArray(record.tools) || record.tools[0] !== record.target
+        || new Set(record.tools).size !== record.tools.length
+        || record.tools.some(tool => !SURFACE_TARGETS.includes(tool)))
+        return undefined;
+    return { root: record.root, target: record.target, tools: [...record.tools] };
+}
+/** The shipped skill sources with the packaged collection and procedures that authenticate them. */
+function bootstrapSkillInput(assets, tools) {
+    const skills = shippedSkillSources(assets, tools);
+    const collection = assets.get('skills/collection.json');
+    const procedures = PROCEDURE_ASSETS.map(path => assets.get(path));
+    if (!skills || !collection || procedures.some(row => row === undefined))
+        return undefined;
+    const pick = ({ path, bytes, sha256: digest }) => ({ path, bytes, sha256: digest });
+    return { sources: skills.flatMap(skill => skill.sources), collection: pick(collection),
+        procedures: procedures.map(pick), tools };
+}
+async function selectedBootstrapAssets(node, adapters) {
+    const reads = await readAnchoredBatches(SURFACE_ROOT, SKILL_ASSETS.map(path => ({
+        path, maxBytes: MAX_SURFACE_FILE_BYTES, action: 'read-file',
+    })), node, adapters);
+    if (!reads || reads.kind !== 'complete' || reads.results.length !== SKILL_ASSETS.length)
+        return undefined;
+    const assets = SKILL_ASSETS.map((path, index) => readSurfaceAsset(path, reads.results[index]));
+    return assets.every((asset) => asset !== undefined) ? assets : undefined;
+}
+async function selectedBootstrapRecordCurrent(record) {
+    try {
+        const root = await lstat(record.root);
+        if (!root.isDirectory() || root.isSymbolicLink() || root.dev !== record.rootIdentity.dev || root.ino !== record.rootIdentity.ino)
+            return false;
+        const reads = await readAnchoredBatches(SURFACE_ROOT, record.assets.map(asset => ({
+            path: asset.path, maxBytes: MAX_SURFACE_FILE_BYTES, action: 'read-file',
+        })), record.node, record.adapters);
+        const state = record.bootstrapState && await readState(record.bootstrapState.address);
+        return (!record.bootstrapState || state?.kind === 'complete'
+            && JSON.stringify(state.value) === JSON.stringify(record.bootstrapState.record))
+            && !!reads && reads.kind === 'complete' && reads.results.length === record.assets.length
+            && reads.results.every((read, index) => read.kind === 'complete' && read.sha256 === record.assets[index].sha256
+                && sourceIdentity(read.identity) === sourceIdentity(record.assets[index].identity));
+    }
+    catch {
+        // a failed re-observation means the inputs are no longer authenticated; the caller refuses.
+        return false;
+    }
+}
+export async function prepareSelectedBootstrapSurface(input, adapterOverrides = {}) {
+    const captured = selectedBootstrapInput(input);
+    if (!captured)
+        return refuse('GENERATED_INPUT_INVALID', 'selected bootstrap input is invalid', 'bootstrap');
+    const adapters = mergedAdapters(adapterOverrides);
+    let root;
+    let rootIdentity;
+    try {
+        root = await realpath(captured.root);
+        const status = await lstat(root);
+        if (root !== captured.root || !status.isDirectory() || status.isSymbolicLink())
+            throw new RefusalError('root');
+        rootIdentity = { dev: status.dev, ino: status.ino };
+    }
+    catch (error) {
+        return refuse('GENERATED_INPUT_INVALID', `selected bootstrap root is not a canonical directory: ${errorCause(error)}`, captured.root);
+    }
+    const node = await nodeAuthority();
+    const assets = node && await selectedBootstrapAssets(node, adapters);
+    if (!node || !assets)
+        return refuse('SURFACE_INPUT_INVALID', 'packaged bootstrap assets could not be authenticated', 'bootstrap');
+    const skillInput = bootstrapSkillInput(new Map(assets.map(asset => [asset.path, asset])), captured.tools);
+    if (!skillInput)
+        return refuse('SURFACE_INPUT_INVALID', 'packaged bootstrap assets are incomplete', 'bootstrap');
+    const { sources } = skillInput;
+    const inspection = await inspectSkillSet(skillInput);
+    if (inspection.kind !== 'complete')
+        return refuse('SURFACE_INPUT_INVALID', 'packaged bootstrap skill set was refused', 'bootstrap');
+    const inspected = projectInspectedSkillOutputs(inspection, captured.tools, SHIPPED_SETUP_SKILL);
+    if (inspected.kind !== 'complete')
+        return refuse('SURFACE_INPUT_INVALID', 'selected bootstrap output set was refused', captured.target);
+    const reads = await readAnchoredBatches(root, inspected.files.map(file => ({
+        path: file.path, maxBytes: MAX_SURFACE_FILE_BYTES, action: 'read-entry',
+    })), node, adapters);
+    if (!reads || reads.kind !== 'complete' || reads.results.length !== inspected.files.length) {
+        return refuse('SURFACE_STATE_CONFLICT', 'selected bootstrap destinations could not be authenticated', captured.target);
+    }
+    const mutations = [];
+    for (const [index, file] of inspected.files.entries()) {
+        const current = reads.results[index];
+        if (current.kind !== 'missing' && current.kind !== 'file')
+            return refuse('SURFACE_STATE_CONFLICT', 'selected bootstrap destination is not a regular file or missing', file.path);
+        if (current.kind === 'file' && current.sha256 !== file.sha256)
+            return refuse('SURFACE_STATE_CONFLICT', 'selected bootstrap destination contains unmanaged bytes', file.path);
+        if (current.kind === 'missing')
+            mutations.push({ path: file.path, phase: 'desired', operation: 'write-file',
+                bytes: file.bytes, sha256: file.sha256, expected: { kind: 'missing' } });
+    }
+    const admitted = await admitPublicationPlan({ mode: 'bootstrap', root, rootIdentity, node, inspected,
+        mutations }, adapters);
+    if (admitted.kind !== 'complete')
+        return admitted;
+    const sourceRows = sources.map(source => ({ path: source.path, sha256: sha256(source.bytes) }));
+    const files = inspected.files.map(file => ({ path: file.path, sha256: file.sha256 }));
+    const previewSha256 = sha256(JSON.stringify({ target: captured.target, sources: sourceRows, files }));
+    const result = { root, target: captured.target, sources: sourceRows, files,
+        previewSha256, changes: admitted.plan.changes };
+    const authority = { kind: 'selected-bootstrap-publication-authority' };
+    issuedSelectedBootstrapAuthorities.set(authority, Object.freeze({ root, rootIdentity, target: captured.target, node,
+        assets: Object.freeze(assets.map(({ path, sha256: digest, identity }) => ({ path, sha256: digest, identity }))),
+        inspected, result, plan: admitted.plan, adapters }));
+    return { kind: 'complete', artifact: null, destination: null, diagnostics: [], result, authority, status: 0 };
+}
+export async function applySelectedBootstrapSurface(authority) {
+    const record = authority !== null && typeof authority === 'object' ? issuedSelectedBootstrapAuthorities.get(authority) : undefined;
+    if (!record)
+        return refuse('GENERATED_PUBLICATION_FAILED', 'selected bootstrap publication authority is unknown or already consumed', 'bootstrap');
+    issuedSelectedBootstrapAuthorities.delete(authority);
+    const outcome = await runPublicationPlan(record.plan, { execute: record.adapters.execute,
+        revalidate: async () => selectedBootstrapRecordCurrent(record) });
+    if (outcome.kind !== 'complete')
+        return outcome;
+    return { kind: 'complete', artifact: null, destination: null, diagnostics: [],
+        result: record.result, authority, status: 0 };
+}
+export async function resumeSelectedBootstrapSurface(input, adapterOverrides = {}) {
+    const captured = selectedBootstrapInput({ root: input.root, target: input.target, tools: input.tools });
+    const durable = await readState(input.address);
+    if (!captured || durable.kind !== 'complete' || durable.value.kind !== 'bootstrap'
+        || durable.value.value.checkoutRoot !== captured.root || durable.value.target !== captured.target
+        || input.address.checkoutRoot !== captured.root || input.address.target !== captured.target
+        || durable.value.value.stage === 'surface-previewed')
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'bootstrap resume requires the current durable state, root and target', 'bootstrap');
+    const adapters = mergedAdapters(adapterOverrides);
+    let rootIdentity;
+    try {
+        const status = await lstat(captured.root);
+        if (!status.isDirectory() || status.isSymbolicLink() || await realpath(captured.root) !== captured.root)
+            throw new RefusalError('root');
+        rootIdentity = { dev: status.dev, ino: status.ino };
+    }
+    catch (error) {
+        return refuse('GENERATED_INPUT_INVALID', `selected bootstrap root is not a canonical directory: ${errorCause(error)}`, captured.root);
+    }
+    const node = await nodeAuthority();
+    if (!node)
+        return refuse('SURFACE_INPUT_INVALID', 'bootstrap resume could not authenticate the node executable', 'bootstrap');
+    const ownership = await readAnchoredEntry(captured.root, OWNERSHIP_PATH, MAX_OWNERSHIP_BYTES, node, adapters);
+    if (ownership.kind !== 'missing' && ownership.kind !== 'file')
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'bootstrap resume ownership could not be read safely', OWNERSHIP_PATH);
+    const assets = await selectedBootstrapAssets(node, adapters);
+    if (!assets)
+        return refuse('SURFACE_INPUT_INVALID', 'bootstrap resume packaged assets could not be authenticated', 'bootstrap');
+    const skillInput = bootstrapSkillInput(new Map(assets.map(asset => [asset.path, asset])), captured.tools);
+    if (!skillInput)
+        return refuse('SURFACE_INPUT_INVALID', 'bootstrap resume packaged assets are incomplete', 'bootstrap');
+    const { sources } = skillInput;
+    const inspection = await inspectSkillSet(skillInput);
+    if (inspection.kind !== 'complete')
+        return refuse('SURFACE_INPUT_INVALID', 'bootstrap resume skill set was refused', 'bootstrap');
+    const inspected = projectInspectedSkillOutputs(inspection, captured.tools, SHIPPED_SETUP_SKILL);
+    if (inspected.kind !== 'complete')
+        return refuse('SURFACE_INPUT_INVALID', 'bootstrap resume output projection was refused', captured.target);
+    const sourceRows = sources.map(source => ({ path: source.path, sha256: sha256(source.bytes) }));
+    const files = inspected.files.map(file => ({ path: file.path, sha256: file.sha256 }));
+    const previewSha256 = sha256(JSON.stringify({ target: captured.target, sources: sourceRows, files }));
+    const state = durable.value.value;
+    const sourcesCurrent = JSON.stringify(state.sources) === JSON.stringify(sourceRows)
+        && JSON.stringify(state.published) === JSON.stringify(files) && state.previewSha256 === previewSha256;
+    if (ownership.kind === 'missing') {
+        if (sourcesCurrent)
+            return { kind: 'pending', status: 0, diagnostics: [],
+                result: null, canonicalOwnership: false };
+        const priorPreviewSha256 = sha256(JSON.stringify({ target: captured.target, sources: state.sources, files: state.published }));
+        if (input.expectedRevision !== durable.value.revision || input.expectedCommandSha256 !== state.commandSha256
+            || priorPreviewSha256 !== state.previewSha256 || state.stage !== 'surface-published'
+            || JSON.stringify(state.published.map(row => row.path)) !== JSON.stringify(files.map(row => row.path)))
+            return refuse('GENERATED_SOURCE_CHANGED', 'bootstrap resume package sources differ from the accepted durable preview', 'bootstrap');
+        const reads = await readAnchoredBatches(captured.root, inspected.files.map(file => ({
+            path: file.path, maxBytes: MAX_SURFACE_FILE_BYTES, action: 'read-entry',
+        })), node, adapters);
+        if (!reads || reads.kind !== 'complete' || reads.results.length !== inspected.files.length)
+            return refuse('SURFACE_STATE_CONFLICT', 'bootstrap refresh destinations could not be authenticated', captured.target);
+        const mutations = [];
+        for (const [index, file] of inspected.files.entries()) {
+            const current = reads.results[index];
+            const prior = state.published[index];
+            if (current.kind !== 'file' || current.sha256 !== prior.sha256 && current.sha256 !== file.sha256)
+                return refuse('SURFACE_STATE_CONFLICT', 'bootstrap refresh destination differs from its authenticated publication', file.path);
+            if (current.sha256 === file.sha256)
+                continue;
+            const expected = expectedState(current);
+            if (!expected)
+                return refuse('SURFACE_STATE_CONFLICT', 'bootstrap refresh destination could not be authenticated', file.path);
+            mutations.push({ path: file.path, phase: 'desired', operation: 'write-file',
+                bytes: file.bytes, sha256: file.sha256, expected });
+        }
+        const admitted = await admitPublicationPlan({ mode: 'bootstrap', root: captured.root, rootIdentity, node, inspected,
+            mutations, refresh: { address: input.address,
+                revision: durable.value.revision, commandSha256: state.commandSha256 } }, adapters);
+        if (admitted.kind !== 'complete')
+            return admitted;
+        const result = { root: captured.root, target: captured.target,
+            sources: sourceRows, files, previewSha256, changes: admitted.plan.changes };
+        const authority = { kind: 'selected-bootstrap-publication-authority' };
+        issuedSelectedBootstrapAuthorities.set(authority, Object.freeze({ root: captured.root, rootIdentity,
+            target: captured.target, node,
+            assets: Object.freeze(assets.map(({ path, sha256: digest, identity }) => ({ path, sha256: digest, identity }))),
+            inspected, result, plan: admitted.plan, adapters,
+            bootstrapState: Object.freeze({ address: input.address, record: durable.value }),
+        }));
+        return { kind: 'refresh', status: 0, diagnostics: [], result, authority,
+            canonicalOwnership: false };
+    }
+    if (ownership.kind !== 'file')
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'bootstrap resume ownership changed after classification', OWNERSHIP_PATH);
+    if (!sourcesCurrent)
+        return refuse('GENERATED_SOURCE_CHANGED', 'bootstrap resume package sources differ from the accepted durable preview', 'bootstrap');
+    const base = await prepare({ configPath: join(captured.root, 'cockpit.toml') }, adapters);
+    if ('status' in base)
+        return base;
+    const canonical = await readOwnership(base, adapters);
+    if (base.root !== captured.root || canonical.kind !== 'complete'
+        || canonical.manifest.format !== 'cockpit-generated-ownership/v3' || canonical.sha256 !== ownership.sha256)
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'bootstrap resume requires canonical ownership bound to the current checkout and configuration', OWNERSHIP_PATH);
+    const current = await readAnchoredEntry(captured.root, OWNERSHIP_PATH, MAX_OWNERSHIP_BYTES, node, adapters);
+    const refreshed = await readState(input.address);
+    if (current.kind !== 'file' || current.sha256 !== ownership.sha256
+        || sourceIdentity(current.identity) !== sourceIdentity(ownership.identity)
+        || refreshed.kind !== 'complete' || JSON.stringify(refreshed.value) !== JSON.stringify(durable.value))
+        return refuse('GENERATED_SOURCE_CHANGED', 'bootstrap resume ownership or state changed during checking', 'bootstrap');
+    return { kind: 'complete', status: 0, diagnostics: [], canonicalOwnership: true,
+        result: { root: captured.root, target: captured.target, sources: sourceRows, files, previewSha256,
+            changes: [] } };
+}
+export async function authenticatedBootstrapPriorSurfaces(root, state, node, adapters) {
+    const publication = state.publication;
+    if (publication === null || typeof publication !== 'object' || consumedBootstrapStatePublications.has(publication))
+        return undefined;
+    const authenticated = authenticateStatePublication(state);
+    if (!authenticated || authenticated.status !== 'complete' || authenticated.record.kind !== 'bootstrap')
+        return undefined;
+    const record = authenticated.record;
+    if (record.target !== state.address.target || state.address.checkoutRoot !== root)
+        return undefined;
+    const surfaces = await bootstrapPublishedSurfaces(root, record, node, adapters);
+    if (surfaces)
+        consumedBootstrapStatePublications.add(publication);
+    return surfaces;
+}
+// A plain sync between an interrupted init and its rerun met init's own setup skill files with no
+// ownership record and refused them, and its remedy had an agent delete them. The bootstrap record
+// sync reads here comes from this user's private state root, scoped to this cockpit root, and the
+// files must still hold exactly the bytes init published from the installed package.
+export async function unfinishedInitSurfaces(root, node, adapters) {
+    if (process.platform !== 'darwin' && process.platform !== 'linux')
+        return undefined;
+    for (const target of SURFACE_TARGETS) {
+        const namespace = await selectBootstrapStateRoot({ platform: process.platform, home: process.env.HOME,
+            xdgStateHome: process.env.XDG_STATE_HOME, checkoutRoot: root, target });
+        if (namespace.kind !== 'complete')
+            return undefined;
+        const read = await readState(namespace.value.paths.bootstrap(target));
+        if (read.kind === 'complete')
+            return { root, target, published: read.value.value.published.map(row => row.path),
+                surfaces: await bootstrapPublishedSurfaces(root, read.value, node, adapters) };
+    }
+    return undefined;
+}
+async function bootstrapPublishedSurfaces(root, record, node, adapters) {
+    if (record.kind !== 'bootstrap' || record.value.stage === 'surface-previewed' || record.value.checkoutRoot !== root
+        || record.value.target !== record.target)
+        return undefined;
+    const assets = await selectedBootstrapAssets(node, adapters);
+    if (!assets)
+        return undefined;
+    // The record names no tools, so they are the targets whose setup skill it published, in published order.
+    const allTools = bootstrapSkillInput(new Map(assets.map(asset => [asset.path, asset])), SURFACE_TARGETS);
+    const allInspection = allTools && await inspectSkillSet(allTools);
+    const allProjection = allInspection?.kind === 'complete'
+        ? projectInspectedSkillOutputs(allInspection, SURFACE_TARGETS, SHIPPED_SETUP_SKILL) : undefined;
+    if (allProjection?.kind !== 'complete')
+        return undefined;
+    const targetByPath = new Map(allProjection.files.map(file => [file.path, file.target]));
+    const tools = [...new Set(record.value.published.map(row => targetByPath.get(row.path)))];
+    if (tools.some(tool => tool === undefined))
+        return undefined;
+    const skillInput = bootstrapSkillInput(new Map(assets.map(asset => [asset.path, asset])), tools);
+    if (!skillInput)
+        return undefined;
+    const sourceRows = skillInput.sources.map(source => ({ path: source.path, sha256: sha256(source.bytes) }));
+    if (JSON.stringify(sourceRows) !== JSON.stringify(record.value.sources))
+        return undefined;
+    const inspection = await inspectSkillSet(skillInput);
+    if (inspection.kind !== 'complete')
+        return undefined;
+    const inspected = projectInspectedSkillOutputs(inspection, tools, SHIPPED_SETUP_SKILL);
+    if (inspected.kind !== 'complete')
+        return undefined;
+    const files = inspected.files;
+    const published = files.map(file => ({ path: file.path, sha256: file.sha256 }));
+    if (JSON.stringify(published) !== JSON.stringify(record.value.published))
+        return undefined;
+    const reads = await readAnchoredBatches(root, files.map(file => ({
+        path: file.path, maxBytes: MAX_SURFACE_FILE_BYTES, action: 'read-entry',
+    })), node, adapters);
+    if (!reads || reads.kind !== 'complete' || reads.results.length !== files.length
+        || reads.results.some((read, index) => read.kind !== 'file' || read.sha256 !== files[index].sha256))
+        return undefined;
+    return files.map(file => ({
+        kind: 'file', path: file.path, harnesses: [file.target], scope: 'always',
+        capability: 'instructed', writer: 'cockpit', schemaVersion: 1,
+        ownership: 'whole-file', sha256: file.sha256,
+    }));
+}

package/dist/environment/generated-application/check.d.ts

@@ -0,0 +1,13 @@
+import { type PublicationPlan } from '../../generated-environment/transaction.js';
+import { type GeneratedEnvironmentCommandAdapters, type GeneratedEnvironmentCommandInput, type GeneratedEnvironmentCommandOutcome, type GeneratedEnvironmentCurrentness, type GeneratedEnvironmentRepairAuthority, type PreparedEnvironment } from './shared.js';
+interface RepairRecord {
+    readonly prepared: PreparedEnvironment;
+    readonly plan: PublicationPlan;
+    readonly adapters: GeneratedEnvironmentCommandAdapters;
+}
+export declare const issuedRepairs: WeakMap<GeneratedEnvironmentRepairAuthority, RepairRecord>;
+export declare function issueRepairAuthority(record: RepairRecord): GeneratedEnvironmentRepairAuthority;
+export declare function prepareGeneratedEnvironmentCurrentness(input: GeneratedEnvironmentCommandInput, adapterOverrides?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<GeneratedEnvironmentCurrentness>;
+export declare function checkCanonicalGeneratedEnvironment(input: GeneratedEnvironmentCommandInput, seed?: PreparedEnvironment, adapters?: GeneratedEnvironmentCommandAdapters): Promise<GeneratedEnvironmentCommandOutcome>;
+export declare function checkGeneratedEnvironment(input: GeneratedEnvironmentCommandInput, adapterOverrides?: Partial<GeneratedEnvironmentCommandAdapters>): Promise<GeneratedEnvironmentCommandOutcome>;
+export {};

package/dist/environment/generated-application/check.js

@@ -0,0 +1,189 @@
+import { installedPackageMetadata } from '../../package-metadata.js';
+import { proposeGeneratedEnvironmentRepair } from '../../repair.js';
+import { dirname, join, resolve } from 'node:path';
+import { loadCockpitConfig, observeConfigSource } from '../../config/load.js';
+import { classifyGeneratedPaths, encodeOwnershipManifest } from '../../surfaces/ownership.js';
+import { SIBLING_GUIDE_MARKER } from '../../surfaces/projection.js';
+import { nodeAuthority, readAnchoredFile, readAnchoredBatches } from '../../generated-environment/transaction.js';
+import { errorCause, RefusalError } from '../contract.js';
+import { resolveDockerExecutable } from '../executable.js';
+import { assessComposeTopology, composeProjectDirectory, observeComposeTopology } from '../compose-topology.js';
+import { declaredRuntime } from '../declaration.js';
+import { refusalOutcome as refuse } from '../../refusal.js';
+import { MAX_GENERATED_BYTES, OWNERSHIP_PATH, compareCodeUnits, complete, defaultAdapters, generatedPathFacts, mergedAdapters, overrideChangedRefusal, sha256, sourceIdentity, } from './shared.js';
+import { prepare, readOwnership } from './prepare.js';
+import { classifyOwnedState, inputSourcesCurrent, observeSurfaceState, ownedInputOverlap, planObservedSurfaces, preparePublication, surfacePlanRefusal, } from './publication.js';
+import { prepareSurfaces } from './surfaces.js';
+export const issuedRepairs = new WeakMap();
+export function issueRepairAuthority(record) {
+    const authority = { kind: 'generated-environment-repair' };
+    issuedRepairs.set(authority, record);
+    return authority;
+}
+export async function prepareGeneratedEnvironmentCurrentness(input, adapterOverrides = {}) {
+    const adapters = mergedAdapters(adapterOverrides);
+    const base = await prepare(input, adapters);
+    const ownership = 'status' in base ? undefined : await readOwnership(base, adapters);
+    const publication = 'status' in base ? base : await preparePublication(input, adapters, base, ownership);
+    const prepared = 'prepared' in publication ? publication.prepared : undefined;
+    const outcome = 'status' in publication ? publication : await checkCanonicalGeneratedEnvironment(input, prepared, adapters);
+    const authority = prepared && 'plan' in publication
+        ? issueRepairAuthority({ prepared, plan: publication.plan, adapters }) : undefined;
+    return {
+        outcome,
+        changes: 'plan' in publication ? publication.plan.changes : [],
+        storedProducer: ownership?.kind === 'complete' ? ownership.manifest.producer : null,
+        currentProducer: { package: installedPackageMetadata.name, version: installedPackageMetadata.version,
+            sourceRevision: installedPackageMetadata.cockpitSourceRevision },
+        fixContext: { resolvedConfigPath: prepared?.configPath ?? null,
+            generatedTargets: prepared ? [...prepared.owned, ...prepared.surfaces].map(row => row.path) : [] },
+        ...(authority ? { repairAuthority: authority } : {}),
+        ...('status' in publication ? { repairRefusal: publication }
+            : 'refusal' in publication ? { repairRefusal: publication.refusal } : {}),
+    };
+}
+// Each copied guide carries a marker naming its sibling, path and digest, so the guides whose copy in
+// the AGENTS.md on disk differs from the one sync would write can be named rather than the file alone.
+function staleSiblingGuides(prepared, observed) {
+    const desired = prepared.surfaces.find(entry => entry.path === 'AGENTS.md');
+    const current = observed.find(entry => entry.path === 'AGENTS.md');
+    const markers = (text) => new Map([...text.matchAll(SIBLING_GUIDE_MARKER)].map(match => [`${match[1]}/${match[2]}`, match[3]]));
+    const want = markers(desired?.kind === 'shared-region' && desired.region.format === 'markdown-delimited' ? desired.region.bytes : '');
+    const have = markers(current?.kind === 'file' ? current.bytes : '');
+    return [...new Set([...want.keys(), ...have.keys()])].filter(key => want.get(key) !== have.get(key)).sort(compareCodeUnits);
+}
+export async function checkCanonicalGeneratedEnvironment(input, seed, adapters = defaultAdapters) {
+    const base = seed ?? await prepare(input, adapters);
+    if ('status' in base)
+        return base;
+    const ownership = await readOwnership(base, adapters);
+    if (ownership.kind === 'unsupported')
+        return refuse('GENERATED_OWNERSHIP_FORMAT_UNSUPPORTED', `generated ownership format ${ownership.format} is not supported`, OWNERSHIP_PATH);
+    if (ownership.kind !== 'complete')
+        return refuse(ownership.kind === 'missing' ? 'GENERATED_OWNERSHIP_MISSING' : 'GENERATED_OWNERSHIP_INVALID', 'durable generated ownership metadata is missing or invalid', OWNERSHIP_PATH, 'restore trusted ownership metadata or run npx --no cockpit sync --config <your cockpit.toml>');
+    const priorSurfaces = ownership.manifest.entries.filter((row) => 'harnesses' in row);
+    const prepared = seed?.surfaceSelftest ? seed : await prepareSurfaces(base, priorSurfaces, adapters, ownership.manifest);
+    if ('status' in prepared)
+        return prepared;
+    if (prepared.changedOverrideOriginals[0])
+        return overrideChangedRefusal(prepared.changedOverrideOriginals[0]);
+    const ownedInput = await ownedInputOverlap(prepared, ownership.manifest.entries);
+    if (ownedInput.kind === 'invalid')
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'authenticated input identity could not be compared with generated ownership metadata', OWNERSHIP_PATH, 'restore trusted ownership metadata or run npx --no cockpit sync --config <your cockpit.toml>');
+    if (ownedInput.path)
+        return refuse('GENERATED_OWNERSHIP_INVALID', 'generated ownership metadata overlaps an authenticated input', ownedInput.path, 'restore trusted ownership metadata or run npx --no cockpit sync --config <your cockpit.toml>');
+    const surfaceState = await observeSurfaceState(prepared, priorSurfaces, adapters);
+    if (!surfaceState)
+        return refuse('SURFACE_STATE_CONFLICT', 'surface state could not be observed safely', 'surfaces');
+    const classified = await classifyOwnedState(prepared, ownership.manifest, surfaceState.raw);
+    if (classified.kind !== 'complete')
+        return refuse(classified.diagnostic.code, classified.diagnostic.message, classified.diagnostic.target);
+    const unknown = classified.paths.find(row => row.state === 'unknown');
+    if (unknown)
+        return refuse('SURFACE_STATE_CONFLICT', 'owned surface identity or confinement is unknown', unknown.fact.path);
+    const effectivePriorSurfaces = priorSurfaces;
+    const surfacePaths = new Set(prepared.surfaces.map(row => row.path));
+    const staleEnvironment = ownership.manifest.entries.filter(row => !('harnesses' in row) && !surfacePaths.has(row.path)
+        && !prepared.owned.some(file => file.path === row.path));
+    if (staleEnvironment.length > 0)
+        return refuse('GENERATED_STALE_ARTIFACT', 'a formerly owned generated artifact remains in durable ownership metadata', staleEnvironment[0].path, 'a person runs npx --no cockpit sync --config <your cockpit.toml> --interactive in a terminal and approves the stale-removal digest it shows');
+    const required = generatedPathFacts(prepared, 'required-after-sync');
+    if (required.kind !== 'complete')
+        return refuse(required.diagnostic.code, required.diagnostic.message, required.diagnostic.target);
+    const canonicalReads = await readAnchoredBatches(prepared.root, prepared.generated.map(file => ({
+        path: file.path, maxBytes: MAX_GENERATED_BYTES, action: 'read-file',
+    })), prepared.node, adapters);
+    // An indexed refusal omits the prefix receipts. Reobserve only that prefix to retain
+    // first-failure ordering; the failed row remains fatal even if a later read could succeed.
+    for (const [index, file] of prepared.generated.entries()) {
+        try {
+            const read = canonicalReads?.kind === 'complete' ? canonicalReads.results[index]
+                : canonicalReads?.kind === 'invalid' && index < canonicalReads.index
+                    ? await readAnchoredFile(prepared.root, file.path, MAX_GENERATED_BYTES, prepared.node, adapters)
+                    : undefined;
+            if (!read || read.kind !== 'complete')
+                throw new RefusalError('generated artifact unavailable');
+            const fact = required.facts.find(fact => fact.path === file.path);
+            const classification = classifyGeneratedPaths([fact], [{ path: file.path, kind: 'file', bytes: read.bytes,
+                    confinement: 'confined', identity: sourceIdentity(read.identity) }]);
+            if (classification.kind !== 'complete' || classification.paths[0]?.state === 'unknown')
+                return refuse('GENERATED_ARTIFACT_MISSING', 'owned generated artifact could not be classified safely', file.path, 'run npx --no cockpit sync --config <your cockpit.toml>');
+            if (classification.paths[0]?.state !== 'unchanged')
+                return refuse('GENERATED_ARTIFACT_DRIFT', 'owned generated artifact differs from canonical bytes', file.path, 'run npx --no cockpit sync --config <your cockpit.toml>');
+        }
+        catch (error) {
+            return refuse('GENERATED_ARTIFACT_MISSING', `owned generated artifact became unreadable: ${errorCause(error)}`, file.path, 'run npx --no cockpit sync --config <your cockpit.toml>');
+        }
+    }
+    const comparison = planObservedSurfaces(prepared, effectivePriorSurfaces, surfaceState);
+    if (comparison.kind !== 'complete')
+        return surfacePlanRefusal(prepared, comparison.diagnostic);
+    const drift = comparison.actions.map(action => action.path);
+    // Removing a formerly owned path is plain sync's to do only where [autonomy] stale_delete is agent;
+    // otherwise it needs a person's approval of its exact digest, so send the reader to the one command that can.
+    const stale = comparison.actions.find(action => action.kind === 'remove');
+    if (stale)
+        return prepared.workEnvironment.policy.autonomy.stale_delete === 'agent'
+            ? refuse('GENERATED_ARTIFACT_DRIFT', 'a formerly generated path is still on disk and in the ownership record', stale.path, 'run npx --no cockpit sync --config <your cockpit.toml>')
+            : refuse('GENERATED_ARTIFACT_DRIFT', 'a formerly generated path is still on disk and in the ownership record', stale.path, 'a person runs npx --no cockpit sync --config <your cockpit.toml> --interactive in a terminal and approves the stale-removal digest it shows');
+    const staleGuides = drift.includes('AGENTS.md') ? staleSiblingGuides(prepared, surfaceState.observed) : [];
+    if (staleGuides.length > 0)
+        return refuse('GENERATED_ARTIFACT_DRIFT', `AGENTS.md holds an out-of-date copy of ${staleGuides.join(', ')}: the guide changed in its sibling, or the declared guides changed, since the last sync`, 'AGENTS.md', 'run npx --no cockpit sync --config <your cockpit.toml>, then commit AGENTS.md together with the guide change');
+    if (drift.length > 0)
+        return refuse('GENERATED_ARTIFACT_DRIFT', 'owned surface state differs from the canonical model', drift[0], 'run npx --no cockpit sync --config <your cockpit.toml>');
+    if (ownership.bytes !== encodeOwnershipManifest(prepared).bytes)
+        return refuse('GENERATED_OWNERSHIP_DRIFT', 'generated ownership metadata differs from the current canonical manifest', OWNERSHIP_PATH, 'run npx --no cockpit sync --config <your cockpit.toml>');
+    const source = await observeConfigSource(prepared.configPath);
+    if (source.state !== 'available' || source.sha256 !== prepared.sourceSha256
+        || !await inputSourcesCurrent(prepared, adapters)) {
+        return refuse('GENERATED_SOURCE_CHANGED', 'a generated input changed during generated environment checking', 'generated-environment');
+    }
+    return complete('check', prepared);
+}
+// A cockpit running its own Compose files owns that topology, so check reads it as Compose resolves
+// it and reports what would break parallel stacks.
+async function composeTopologyDiagnostics(configPath, sourceSha256, adapters) {
+    const loaded = await loadCockpitConfig(configPath);
+    if (loaded.kind !== 'complete' || loaded.result.source.sha256 !== sourceSha256)
+        return [{ severity: 'error',
+                code: 'GENERATED_SOURCE_CHANGED', message: 'the configuration changed while check was reading the Compose topology', target: configPath }];
+    const config = loaded.result.config;
+    if (declaredRuntime(config.environment) !== 'compose')
+        return [];
+    const env = { PATH: process.env.PATH, DOCKER_HOST: process.env.DOCKER_HOST, DOCKER_CONTEXT: process.env.DOCKER_CONTEXT,
+        DOCKER_TLS_VERIFY: process.env.DOCKER_TLS_VERIFY, DOCKER_CERT_PATH: process.env.DOCKER_CERT_PATH };
+    const [docker, node] = await Promise.all([resolveDockerExecutable(process.env), nodeAuthority()]);
+    const observed = docker.state !== 'available' ? { kind: 'unavailable', reason: docker.reason }
+        : !node ? { kind: 'unavailable', reason: 'the current Node executable could not be authenticated' }
+            : await observeComposeTopology({ root: dirname(loaded.result.source.path), references: config.environment.compose_files,
+                projectName: config.cockpit.name, docker: docker.value, node, env }, adapters.execute);
+    if (observed.kind !== 'complete')
+        return [{ severity: 'error', code: 'COMPOSE_TOPOLOGY_UNAVAILABLE',
+                message: `check could not read the declared Compose topology, so its ports, healthchecks and images are unverified: ${observed.reason}`,
+                target: config.environment.compose_files.join(', '),
+                fix: 'install Docker with the Compose plugin on PATH and make `docker compose config` succeed for environment.compose_files' }];
+    const root = dirname(loaded.result.source.path);
+    const siblingsRoot = resolve(root, config.cockpit.siblings_root);
+    return assessComposeTopology(observed.services, {
+        projectDirectory: composeProjectDirectory(root, config.environment.compose_files),
+        portVariables: Object.keys(config.ports.bases),
+        siblings: config.sibling.map(sibling => ({
+            slug: sibling.slug, var: sibling.var, mount: sibling.mount, path: resolve(siblingsRoot, sibling.dir)
+        })),
+        hostPaths: config.environment.generated_host_paths.map(declared => ({ declared, path: resolve(root, declared) })),
+    });
+}
+export async function checkGeneratedEnvironment(input, adapterOverrides = {}) {
+    const adapters = mergedAdapters(adapterOverrides);
+    const currentness = await prepareGeneratedEnvironmentCurrentness(input, adapters);
+    const findings = currentness.outcome.kind === 'complete'
+        ? await composeTopologyDiagnostics(input.configPath, currentness.outcome.result.sourceSha256, adapters) : [];
+    const diagnostics = [...currentness.outcome.diagnostics, ...findings];
+    const outcome = findings.some(row => row.severity === 'error')
+        ? { kind: 'refusal', artifact: null, destination: null, result: null, status: 2, diagnostics }
+        : { ...currentness.outcome, diagnostics };
+    return { ...outcome, fixContext: currentness.fixContext, report: {
+            storedProducer: currentness.storedProducer, currentProducer: currentness.currentProducer,
+            repair: proposeGeneratedEnvironmentRepair(currentness),
+        } };
+}