@b00dea/cockpit 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,191 @@
+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) : [] },
+        mcpServers: prepared?.mcpServers ?? [],
+        ...(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) })),
+        profiles: config.environment.profiles,
+    });
+}
+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),
+        } };
+}

package/dist/environment/generated-application/custom-surface.d.ts

@@ -0,0 +1,26 @@
+import type { DerivedRegistry } from '../../registry-derivation.js';
+import type { SurfaceSourceFile } from '../../surfaces/contract.js';
+import type { OwnershipManifest } from '../../surfaces/ownership.js';
+import { type CustomSurfaceReceipt } from '../../surfaces/render.js';
+import { type CustomSourceIdentity, type GeneratedEnvironmentCommandAdapters, type PreparedEnvironment } from './shared.js';
+export declare function executeCustomCapability(prepared: PreparedEnvironment, adapters: GeneratedEnvironmentCommandAdapters, harness: string, capability: Extract<DerivedRegistry['config']['surfaces']['harnesses'][number]['capabilities'][number], {
+    state: 'enforced' | 'instructed';
+}>, sources: readonly SurfaceSourceFile[]): Promise<{
+    receipt: CustomSurfaceReceipt;
+    sources: readonly CustomSourceIdentity[];
+    evidence?: Readonly<{
+        reference: string;
+        sha256: string;
+    }>;
+} | undefined>;
+export declare function projectExplicitNativeHooks(prepared: PreparedEnvironment, manifest: OwnershipManifest | undefined, adapters: GeneratedEnvironmentCommandAdapters, policyDeclaration: Readonly<{
+    path: string;
+    sha256: string;
+}>, harnesses: readonly string[]): Promise<{
+    projection: import("../../testing/hooks.js").NativeHookProjection;
+    source: {
+        path: string;
+        sha256: string;
+        identity: import("../../generated-environment/transaction.js").FileIdentity;
+    };
+} | undefined>;

package/dist/environment/generated-application/custom-surface.js

@@ -0,0 +1,289 @@
+import { chmod, lstat, mkdtemp, realpath, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { authenticatedExecutionOutcome } from '../../environment-exec/execute.js';
+import { surfaceModelSha256 } from '../../surfaces/render.js';
+import { readAnchoredFile, readAnchoredBatches } from '../../generated-environment/transaction.js';
+import { snapshotExecutionStep, snapshotGeneratedJson, RefusalError, hasErrorCode } from '../contract.js';
+import { resolveExecutablePath, resolveGitExecutable } from '../executable.js';
+import { cockpitId } from '../identity.js';
+import { NATIVE_HOOK_COST_SCRIPT, projectNativeHooks } from '../../testing/hooks.js';
+import { exactKeys } from '../../exact-keys.js';
+import { HELPER_TIMEOUT_MS, MAX_EXECUTABLE_BYTES, MAX_GENERATED_BYTES, MAX_HELPER_FRAME_BYTES, MAX_SURFACE_FILE_BYTES, NATIVE_HOOK_COST_TIMEOUT_MS, SHA256, confined, ownRecord, sha256, } from './shared.js';
+// The worker runs in its own process and cannot import modules; `safe` mirrors safeSurfacePath in
+// surfaces/contract.ts, including its case-folded reserved segments.
+const CUSTOM_SURFACE_WORKER = String.raw `
+const fs = require('node:fs');
+const crypto = require('node:crypto');
+const path = require('node:path');
+const request = JSON.parse(process.argv[1]);
+const digest = value => crypto.createHash('sha256').update(value).digest('hex');
+const own = value => value && typeof value === 'object' && !Array.isArray(value) && Object.getPrototypeOf(value) === Object.prototype;
+const safe = value => typeof value === 'string' && value.length > 0 && !path.isAbsolute(value) && !value.includes('\\') && !value.includes('\0') && value.split('/').every(part => part && part !== '.' && part !== '..' && !['.GIT','NODE_MODULES'].includes(part.normalize('NFC').toUpperCase()));
+(async () => {
+  const source = fs.readFileSync(process.argv[2]);
+  if (digest(source) !== request.sourceSha256) throw new RefusalError('module changed');
+  const imported = await import('data:text/javascript;base64,' + source.toString('base64'));
+  const fn = imported[request.export]; if (typeof fn !== 'function') throw new RefusalError('export');
+  const result = await fn(request.input);
+  if (!own(result) || Object.keys(result).sort().join(',') !== 'files,kind' || result.kind !== 'complete' || !Array.isArray(result.files) || result.files.length === 0 || result.files.length > 256) throw new RefusalError('result');
+  let total = 0; let spelling = false; const files = [];
+  for (const [index, file] of result.files.entries()) {
+    if (!own(file) || Object.keys(file).sort().join(',') !== 'bytes,path,scope,sha256' || !safe(file.path) || typeof file.bytes !== 'string' || Buffer.byteLength(file.bytes) > 65536 || digest(file.bytes) !== file.sha256 || !['always','scoped'].includes(file.scope)) throw new RefusalError('file');
+    spelling = spelling || file.path === request.spelling || file.bytes.includes(request.spelling);
+    total += Buffer.byteLength(file.bytes); if (total > 4194304) throw new RefusalError('limit');
+    const output = path.join(request.output, String(index)); fs.writeFileSync(output, file.bytes, { flag: 'wx', mode: 0o600 });
+    files.push({ path: file.path, sha256: file.sha256, scope: file.scope, output: String(index) });
+  }
+  if (!spelling) throw new RefusalError('spelling');
+  process.stdout.write(JSON.stringify({ version: 1, files }) + '\n');
+})().catch(() => { process.stdout.write(JSON.stringify({ version: 1, refusal: true }) + '\n'); });
+`;
+export async function executeCustomCapability(prepared, adapters, harness, capability, sources) {
+    let evidenceSource;
+    if (capability.state === 'enforced') {
+        const evidenceRead = await readAnchoredFile(prepared.root, capability.evidence.reference, MAX_SURFACE_FILE_BYTES, prepared.node, adapters);
+        if (evidenceRead.kind !== 'complete' || evidenceRead.sha256 !== capability.evidence.sha256)
+            return undefined;
+        evidenceSource = { harness, feature: capability.feature, path: capability.evidence.reference,
+            sha256: evidenceRead.sha256, identity: evidenceRead.identity, maxBytes: MAX_SURFACE_FILE_BYTES };
+    }
+    const moduleRead = await readAnchoredFile(prepared.root, capability.mechanism.module, MAX_GENERATED_BYTES, prepared.node, adapters);
+    if (moduleRead.kind !== 'complete')
+        return undefined;
+    const permissionFlag = process.allowedNodeEnvironmentFlags.has('--permission') ? '--permission'
+        : process.allowedNodeEnvironmentFlags.has('--experimental-permission') ? '--experimental-permission' : undefined;
+    if (!permissionFlag || !process.allowedNodeEnvironmentFlags.has('--allow-fs-read')
+        || !process.allowedNodeEnvironmentFlags.has('--allow-fs-write'))
+        return undefined;
+    let scratch;
+    let scratchIdentity;
+    try {
+        scratch = await realpath(await mkdtemp(join(tmpdir(), 'cockpit-custom-surface-')));
+        const scratchStatus = await lstat(scratch);
+        if (!scratchStatus.isDirectory() || scratchStatus.isSymbolicLink())
+            return undefined;
+        scratchIdentity = { dev: scratchStatus.dev, ino: scratchStatus.ino };
+        const input = snapshotGeneratedJson({ harness, feature: capability.feature, sources });
+        if (!input)
+            return undefined;
+        const absoluteModule = confined(prepared.root, capability.mechanism.module);
+        if (!absoluteModule || [scratch, absoluteModule].some(path => path.includes('*')))
+            return undefined;
+        const request = { export: capability.mechanism.export, input, output: scratch,
+            sourceSha256: moduleRead.sha256, spelling: capability.spelling };
+        const raw = JSON.stringify(request);
+        if (Buffer.byteLength(raw) > MAX_HELPER_FRAME_BYTES)
+            return undefined;
+        const step = snapshotExecutionStep({
+            id: `custom-surface-${harness}-${capability.feature}`, argv: [prepared.node.canonicalPath, permissionFlag,
+                '--allow-fs-read', absoluteModule, `--allow-fs-read=${scratch}`, `--allow-fs-write=${scratch}`,
+                '-e', CUSTOM_SURFACE_WORKER, raw, absoluteModule],
+            argv0: prepared.node.invocationPath, cwd: scratch, env: {}, timeoutMs: HELPER_TIMEOUT_MS,
+            spawnNotAfter: new Date(Date.now() + HELPER_TIMEOUT_MS).toISOString(), stdoutLimitBytes: MAX_HELPER_FRAME_BYTES,
+            stderrLimitBytes: 16_384, paths: [prepared.root, scratch], ports: [], labels: { harness, feature: capability.feature }, expected: [],
+            consumedFiles: [
+                { path: prepared.node.canonicalPath, sha256: prepared.node.sha256, maxBytes: MAX_EXECUTABLE_BYTES, argvIndexes: [0], executable: true, executionMode: prepared.node.executionMode },
+                { path: absoluteModule, sha256: moduleRead.sha256, maxBytes: MAX_GENERATED_BYTES, argvIndexes: [3, 9], executable: false },
+            ], filesystemChecks: [{ path: scratch, expected: 'directory' }], compensation: [],
+        });
+        if (!step)
+            return undefined;
+        const outcome = authenticatedExecutionOutcome(await adapters.execute(step), step);
+        if (!outcome || outcome.kind !== 'complete' || outcome.stderr.byteLength !== 0)
+            return undefined;
+        const text = new TextDecoder('utf-8', { fatal: true }).decode(outcome.stdout);
+        const record = ownRecord(JSON.parse(text));
+        if (!record || !exactKeys(record, ['version', 'files']) || record.version !== 1 || !Array.isArray(record.files))
+            return undefined;
+        const descriptors = [];
+        for (const [index, value] of record.files.entries()) {
+            const row = ownRecord(value);
+            if (!row || !exactKeys(row, ['path', 'sha256', 'scope', 'output']) || row.output !== String(index)
+                || typeof row.path !== 'string' || typeof row.sha256 !== 'string' || !SHA256.test(row.sha256)
+                || row.scope !== 'always' && row.scope !== 'scoped')
+                return undefined;
+            descriptors.push({ path: row.path, sha256: row.sha256, scope: row.scope, output: row.output });
+        }
+        const reads = await readAnchoredBatches(scratch, descriptors.map(row => ({
+            path: row.output, maxBytes: MAX_SURFACE_FILE_BYTES, action: 'read-file',
+        })), prepared.node, adapters);
+        if (!reads || reads.kind !== 'complete' || reads.results.length !== descriptors.length)
+            return undefined;
+        const files = [];
+        for (const [index, row] of descriptors.entries()) {
+            const read = reads.results[index];
+            if (read.kind !== 'complete' || read.sha256 !== row.sha256
+                || read.identity.root.dev !== scratchIdentity.dev || read.identity.root.ino !== scratchIdentity.ino)
+                return undefined;
+            const bytes = new TextDecoder('utf-8', { fatal: true }).decode(read.bytes);
+            files.push({ path: row.path, bytes, sha256: row.sha256, scope: row.scope });
+        }
+        if (files.length === 0 || !files.some(file => file.path === capability.spelling || file.bytes.includes(capability.spelling)))
+            return undefined;
+        const resultSha256 = surfaceModelSha256(files);
+        if (!resultSha256)
+            return undefined;
+        return {
+            receipt: { harness, feature: capability.feature, state: capability.state, measuredOn: capability.measured_on,
+                module: capability.mechanism.module, export: capability.mechanism.export, sourceSha256: moduleRead.sha256,
+                resultSha256, files },
+            sources: [
+                { harness, feature: capability.feature, path: capability.mechanism.module,
+                    sha256: moduleRead.sha256, identity: moduleRead.identity, maxBytes: MAX_GENERATED_BYTES },
+                ...(evidenceSource ? [evidenceSource] : []),
+            ],
+            ...(capability.state === 'enforced' ? { evidence: { ...capability.evidence } } : {}),
+        };
+    }
+    catch { /* an unavailable authority is refused by the caller. */
+        return undefined;
+    }
+    finally {
+        if (scratch && scratchIdentity) {
+            try {
+                const current = await lstat(scratch);
+                if (current.isDirectory() && !current.isSymbolicLink()
+                    && current.dev === scratchIdentity.dev && current.ino === scratchIdentity.ino) {
+                    await rm(scratch, { recursive: true, force: true });
+                }
+            }
+            catch (error) {
+                if (!hasErrorCode(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+    }
+}
+export async function projectExplicitNativeHooks(prepared, manifest, adapters, policyDeclaration, harnesses) {
+    if (!manifest)
+        return undefined;
+    const policyRead = await readAnchoredFile(prepared.root, policyDeclaration.path, MAX_SURFACE_FILE_BYTES, prepared.node, adapters);
+    if (policyRead.kind !== 'complete' || policyRead.sha256 !== policyDeclaration.sha256)
+        return undefined;
+    let policyBytes;
+    try {
+        policyBytes = new TextDecoder('utf-8', { fatal: true }).decode(policyRead.bytes);
+    }
+    catch { /* undecodable bytes are malformed input the caller refuses. */
+        return undefined;
+    }
+    const policy = {
+        manifest,
+        authority: { root: prepared.root, cockpitId: prepared.cockpitId, configPath: prepared.configPath },
+        declarations: [],
+        path: policyDeclaration.path,
+        exists: true,
+        bytes: policyBytes,
+    };
+    const source = { path: policyDeclaration.path, sha256: policyRead.sha256, identity: policyRead.identity };
+    const git = await resolveGitExecutable(process.env);
+    if (git.state !== 'available')
+        return {
+            projection: { kind: 'refusal', reason: git.reason },
+            source,
+        };
+    const revisionStep = snapshotExecutionStep({
+        id: 'native-hook-revisions',
+        argv: [git.value.invocationPath, 'rev-list', '--max-count=2', 'HEAD'],
+        argv0: git.value.invocationPath,
+        cwd: prepared.root,
+        env: {},
+        timeoutMs: HELPER_TIMEOUT_MS,
+        spawnNotAfter: new Date(Date.now() + HELPER_TIMEOUT_MS).toISOString(),
+        stdoutLimitBytes: 256,
+        stderrLimitBytes: 4_096,
+        paths: [prepared.root],
+        ports: [],
+        labels: { action: 'native-hook-revisions' },
+        expected: [],
+        consumedFiles: [{ path: git.value.canonicalPath, sha256: git.value.sha256, maxBytes: MAX_EXECUTABLE_BYTES,
+                argvIndexes: [0], executable: true, executionMode: git.value.executionMode }],
+        filesystemChecks: [{ path: prepared.root, expected: 'directory' }],
+        compensation: [],
+    });
+    if (!revisionStep)
+        return undefined;
+    const revisionOutcome = authenticatedExecutionOutcome(await adapters.execute(revisionStep), revisionStep);
+    if (!revisionOutcome || revisionOutcome.kind !== 'complete' || revisionOutcome.stderr.byteLength !== 0)
+        return undefined;
+    let revisions;
+    try {
+        revisions = new TextDecoder('utf-8', { fatal: true }).decode(revisionOutcome.stdout).trim().split('\n');
+    }
+    catch { /* undecodable bytes are malformed input the caller refuses. */
+        return undefined;
+    }
+    if (revisions.length !== 2 || revisions[0] === revisions[1]
+        || revisions.some(value => !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(value) || !/[1-9a-f]/.test(value)))
+        return undefined;
+    let scratch;
+    let scratchIdentity;
+    try {
+        scratch = await realpath(await mkdtemp(join(tmpdir(), 'cockpit-native-hook-cost-')));
+        const status = await lstat(scratch);
+        if (!status.isDirectory() || status.isSymbolicLink())
+            return undefined;
+        scratchIdentity = { dev: status.dev, ino: status.ino };
+        const shell = await resolveExecutablePath('/bin/sh');
+        if (shell.state !== 'available')
+            return undefined;
+        const projection = await projectNativeHooks({
+            cockpitId: prepared.cockpitId,
+            harnesses,
+            install: 'explicit-native',
+            budget: {
+                policy,
+                prepareMeasurement: async (entry) => {
+                    const path = join(scratch, 'pre-push');
+                    await writeFile(path, entry.bytes, { flag: 'wx', mode: 0o700 });
+                    await chmod(path, 0o700);
+                    const step = snapshotExecutionStep({
+                        id: 'native-hook-cost',
+                        argv: [shell.value.canonicalPath, '-c', NATIVE_HOOK_COST_SCRIPT, 'native-hook-cost', path, revisions[0], revisions[1]],
+                        argv0: shell.value.canonicalPath,
+                        cwd: prepared.root,
+                        env: { PATH: dirname(git.value.canonicalPath) },
+                        timeoutMs: NATIVE_HOOK_COST_TIMEOUT_MS,
+                        spawnNotAfter: new Date(Date.now() + HELPER_TIMEOUT_MS).toISOString(),
+                        stdoutLimitBytes: 4_096,
+                        stderrLimitBytes: 4_096,
+                        paths: [prepared.root, scratch],
+                        ports: [],
+                        labels: { action: 'native-hook-cost' },
+                        expected: [],
+                        consumedFiles: [
+                            { path: shell.value.canonicalPath, sha256: shell.value.sha256, maxBytes: MAX_EXECUTABLE_BYTES,
+                                argvIndexes: [0], executable: true, executionMode: shell.value.executionMode },
+                            { path, sha256: entry.sha256, maxBytes: Buffer.byteLength(entry.bytes), argvIndexes: [4], executable: false },
+                        ],
+                        filesystemChecks: [{ path: prepared.root, expected: 'directory' }, { path: scratch, expected: 'directory' }],
+                        compensation: [],
+                    });
+                    if (!step)
+                        throw new RefusalError('native hook cost measurement could not be admitted');
+                    return step;
+                },
+            },
+        });
+        return {
+            projection,
+            source,
+        };
+    }
+    finally {
+        if (scratch && scratchIdentity) {
+            try {
+                const current = await lstat(scratch);
+                if (current.isDirectory() && !current.isSymbolicLink()
+                    && current.dev === scratchIdentity.dev && current.ino === scratchIdentity.ino) {
+                    await rm(scratch, { recursive: true, force: true });
+                }
+            }
+            catch (error) {
+                if (!hasErrorCode(error, 'ENOENT'))
+                    throw error;
+            }
+        }
+    }
+}

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

@@ -0,0 +1,29 @@
+import { type OwnershipManifest } from '../../surfaces/ownership.js';
+import { type FileIdentity } from '../../generated-environment/transaction.js';
+import { type GeneratedEnvironmentCommandAdapters, type GeneratedEnvironmentCommandInput, type GeneratedEnvironmentSyncInput, type PreparedEnvironment, type RefusalOutcome } from './shared.js';
+export declare function commandInput(input: unknown): GeneratedEnvironmentCommandInput | undefined;
+export declare function syncCommandInput(input: unknown): GeneratedEnvironmentSyncInput | undefined;
+export declare function safePath(root: string, path: string, allowMissing: boolean): Promise<string | undefined>;
+export type OwnershipState = {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'invalid';
+} | {
+    readonly kind: 'unsupported';
+    readonly format: string;
+} | {
+    readonly kind: 'complete';
+    readonly manifest: OwnershipManifest;
+    readonly bytes: string;
+    readonly sha256: string;
+    readonly identity: FileIdentity;
+};
+export declare function readOwnership(prepared: PreparedEnvironment, adapters: GeneratedEnvironmentCommandAdapters): Promise<OwnershipState>;
+export declare function expectedOutputExists(prepared: PreparedEnvironment): Promise<boolean>;
+export declare function renamedStackRefusal(prepared: PreparedEnvironment): Promise<RefusalOutcome | undefined>;
+/** Why no single Compose service publishes the endpoint's port on loopback, or undefined when exactly one does. */
+export declare function browserEndpointUnpublished(endpoint: string, sources: readonly Readonly<{
+    reference: string;
+    source: string;
+}>[], bases: Readonly<Record<string, number>>): string | undefined;
+export declare function prepare(input: unknown, adapters: GeneratedEnvironmentCommandAdapters): Promise<PreparedEnvironment | RefusalOutcome>;