spawnfile 0.1.14 → 0.1.18

package/dist/cli/targetConfigResolverDocker.js

@@ -0,0 +1,47 @@
+import { SpawnfileError } from "../shared/index.js";
+import { parseContext, runtimeFailure } from "./targetConfigResolverValidation.js";
+const MAX_DOCKER_OUTPUT_BYTES = 64 * 1_024;
+export const exactJson = (source, keys, failureMessage) => {
+    if (Buffer.byteLength(source, "utf8") > MAX_DOCKER_OUTPUT_BYTES) {
+        return runtimeFailure(failureMessage);
+    }
+    try {
+        const parsed = JSON.parse(source);
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)
+            || Object.keys(parsed).sort().join("\0") !== [...keys].sort().join("\0")) {
+            return runtimeFailure(failureMessage);
+        }
+        return parsed;
+    }
+    catch {
+        return runtimeFailure(failureMessage);
+    }
+};
+export const executeDocker = async (execFile, command, context, args, timeout, signal, failureMessage) => {
+    try {
+        const result = await execFile(command, ["--context", context, ...args], { signal, timeout });
+        if (Buffer.byteLength(result.stdout, "utf8") > MAX_DOCKER_OUTPUT_BYTES) {
+            return runtimeFailure(failureMessage);
+        }
+        return result.stdout;
+    }
+    catch {
+        return runtimeFailure(failureMessage);
+    }
+};
+export const resolveCurrentDockerContext = async (execFile, dockerCommand, timeoutMs, signal) => {
+    try {
+        const result = await execFile(dockerCommand, ["context", "show"], {
+            signal, timeout: timeoutMs,
+        });
+        if (Buffer.byteLength(result.stdout, "utf8") > 4_096) {
+            return runtimeFailure("Current Docker context is invalid");
+        }
+        return parseContext(result.stdout.trim());
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        return runtimeFailure("Unable to resolve the current Docker context");
+    }
+};

package/dist/cli/targetConfigResolverValidation.d.ts

@@ -0,0 +1,10 @@
+import type { TargetConfigResolution } from "./targetConfigResolverContracts.js";
+export declare const validationFailure: (message: string) => never;
+export declare const runtimeFailure: (message: string) => never;
+export declare const parseContext: (value: unknown) => string;
+export declare const parseDockerCommand: (value: unknown) => string;
+export declare const parseTimeout: (value: unknown) => number;
+export declare const parseBaseImage: (value: unknown) => string;
+export declare const validateEvidenceDestination: (value: unknown) => Promise<string>;
+export declare const classifyEndpoint: (endpoint: string) => TargetConfigResolution["endpoint"];
+export declare const normalizeArchitecture: (value: unknown) => "amd64" | "arm64";

package/dist/cli/targetConfigResolverValidation.js

@@ -0,0 +1,94 @@
+import { lstat, realpath } from "node:fs/promises";
+import path from "node:path";
+import { SpawnfileError } from "../shared/index.js";
+import { parseDockerBaseImageReference } from "../target/dockerBaseImage.js";
+const CONTEXT = /^[a-z][a-z0-9_-]{0,63}$/u;
+const COMMAND_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/u;
+const MAX_PATH_BYTES = 4_096;
+export const validationFailure = (message) => {
+    throw new SpawnfileError("validation_error", message);
+};
+export const runtimeFailure = (message) => {
+    throw new SpawnfileError("runtime_error", message);
+};
+export const parseContext = (value) => typeof value === "string" && CONTEXT.test(value)
+    ? value
+    : validationFailure("Docker context must be an explicit bounded context name");
+export const parseDockerCommand = (value) => {
+    if (typeof value !== "string" || value.includes("\0")
+        || Buffer.byteLength(value, "utf8") > 1_024) {
+        return validationFailure("Docker command is invalid");
+    }
+    if (COMMAND_NAME.test(value))
+        return value;
+    if (path.isAbsolute(value) && path.normalize(value) === value)
+        return value;
+    return validationFailure("Docker command is invalid");
+};
+export const parseTimeout = (value) => typeof value === "number" && Number.isSafeInteger(value) && value >= 1 && value <= 120_000
+    ? value
+    : validationFailure("Target timeout must be an integer from 1 to 120000 milliseconds");
+export const parseBaseImage = (value) => parseDockerBaseImageReference(value)
+    ?? validationFailure("Base image must be an explicit portable image reference");
+export const validateEvidenceDestination = async (value) => {
+    if (typeof value !== "string" || value.includes("\0")
+        || Buffer.byteLength(value, "utf8") > MAX_PATH_BYTES
+        || !path.isAbsolute(value) || path.normalize(value) !== value) {
+        return validationFailure("Evidence destination must be an absolute normalized path");
+    }
+    const parent = path.dirname(value);
+    const owner = process.getuid?.();
+    try {
+        const parentInfo = await lstat(parent);
+        if (!parentInfo.isDirectory() || parentInfo.isSymbolicLink()
+            || (parentInfo.mode & 0o777) !== 0o700
+            || owner !== undefined && parentInfo.uid !== owner
+            || await realpath(parent) !== parent) {
+            return validationFailure("Evidence destination parent must be a private physical directory");
+        }
+        try {
+            const destinationInfo = await lstat(value);
+            if (!destinationInfo.isFile() || destinationInfo.isSymbolicLink()
+                || (destinationInfo.mode & 0o777) !== 0o600
+                || owner !== undefined && destinationInfo.uid !== owner) {
+                return validationFailure("Existing evidence destination must be a private regular file");
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    catch (error) {
+        if (error instanceof SpawnfileError)
+            throw error;
+        return validationFailure("Evidence destination parent is unavailable");
+    }
+    return value;
+};
+export const classifyEndpoint = (endpoint) => {
+    if (Buffer.byteLength(endpoint, "utf8") > 4_096 || /\s/u.test(endpoint)) {
+        return runtimeFailure("Docker context returned an invalid endpoint");
+    }
+    const match = /^(fd|http|https|npipe|ssh|tcp|unix):\/\/.+$/u.exec(endpoint);
+    if (!match)
+        return runtimeFailure("Docker context returned an unsupported endpoint transport");
+    const transport = match[1];
+    return Object.freeze({
+        class: transport === "fd" || transport === "npipe" || transport === "unix"
+            ? "local" : "remote",
+        transport,
+    });
+};
+export const normalizeArchitecture = (value) => {
+    if (typeof value !== "string")
+        return runtimeFailure("Docker architecture is invalid");
+    switch (value.trim()) {
+        case "amd64":
+        case "x64":
+        case "x86_64": return "amd64";
+        case "aarch64":
+        case "arm64": return "arm64";
+        default: return runtimeFailure("Docker architecture is unsupported");
+    }
+};

package/dist/cli/targetDefaultAuthorities.d.ts

@@ -1,4 +1,5 @@
 import { type DockerArtifactIdentityBinding, type DockerArtifactIdentityStore, type DockerArtifactMapping } from "../target/dockerArtifactsProvider.js";
+import type { DockerArtifactExecutor } from "../target/dockerArtifactsProvider.js";
 import { type DockerTargetExecutors } from "../target/dockerCommandExecutor.js";
 import { type TargetSecretVersionAuthorityStore } from "../target/dockerSecretsAuthority.js";
 import { type WorldServiceResolver } from "../target/dockerWorldServiceAuthority.js";
@@ -32,6 +33,7 @@ export interface TargetDefaultAuthorities {
     readonly evidenceExportAuthorityStore: EvidenceExportAuthorityStore;
     readonly executors: DockerTargetExecutors;
     readonly handoffResolver: OrganizationAttachmentResolver;
+    readonly helperExecutor: DockerArtifactExecutor;
     /** Omitted when this invocation cannot export evidence. */
     readonly helperArtifactResolver?: HelperArtifactResolver;
     readonly journals: TargetJournalResolver;

package/dist/cli/targetDefaultAuthorities.js

@@ -1,4 +1,5 @@
 import { initializeDockerArtifactIdentityStore } from "../target/dockerArtifactsProvider.js";
+import { createPreparedEvidenceHelperExecutor } from "../evidenceExportHelper/index.js";
 import { createDockerTargetExecutors } from "../target/dockerCommandExecutor.js";
 import { initializeTargetSecretVersionAuthorityStore } from "../target/dockerSecretsAuthority.js";
 import { parseWorldServiceAuthorization, parseWorldServiceResolution } from "../target/dockerWorldServiceAuthority.js";
@@ -37,6 +38,7 @@ export const initializeTargetDefaultAuthoritySession = async (config) => {
         handoffAuthority = await initializeOrganizationHandoffAuthorityStore();
         const handoffResolver = handoffAuthority.resolver;
         const executors = createDockerTargetExecutors({ dockerCommand: config.dockerCommand });
+        const helperExecutor = createPreparedEvidenceHelperExecutor(config.dockerCommand);
         const preparedBuilder = createDockerTargetLocalBundleBuilder({ context: config.context,
             executor: executors.artifact, timeoutMs: config.timeoutMs });
         const preparedStore = await initializeFilesystemTargetLocalBundleStore(config.paths.containerBundles);
@@ -185,6 +187,7 @@ export const initializeTargetDefaultAuthoritySession = async (config) => {
             evidenceExportAuthorityStore,
             executors,
             handoffResolver,
+            helperExecutor,
             ...(helperArtifactResolver ? { helperArtifactResolver } : {}),
             journals,
             secretAuthorityStore,

package/dist/cli/targetDefaultConfig.d.ts

@@ -1,3 +1,4 @@
+import { type PreparedEvidenceHelperReceipt } from "../evidenceExportHelper/index.js";
 import { type DockerArtifactMapping } from "../target/dockerArtifactsProvider.js";
 export { resolveTargetDefaultJournalRoot } from "../target/journalRoot.js";
 export declare const TARGET_DEFAULT_CONFIG_ERROR = "Target configuration failed";
@@ -14,6 +15,8 @@ export interface TargetDefaultConfigInputs {
     readonly containerBundleStoreRoot?: string;
     readonly context: string;
     readonly dockerCommand: string;
+    readonly evidenceHelperBaseImage?: string;
+    readonly preparedEvidenceHelper?: PreparedEvidenceHelperReceipt;
     readonly evidenceDestination: string;
     readonly helperArtifactManifestDigest?: string;
     /** Local-Daemon prepared images, admitted only by manifest/bundle/policy. */
@@ -39,6 +42,8 @@ export interface TargetDefaultConfig {
     readonly artifactMappings: readonly DockerArtifactMapping[];
     readonly context: string;
     readonly dockerCommand: string;
+    readonly evidenceHelperBaseImage?: string;
+    readonly preparedEvidenceHelper?: PreparedEvidenceHelperReceipt;
     readonly evidenceDestination: string;
     /** Present only when the private evidence-export helper was configured. */
     readonly helperArtifact?: DockerArtifactMapping;
@@ -47,6 +52,7 @@ export interface TargetDefaultConfig {
         readonly artifactIdentities: string;
         readonly attachmentAuthority: string;
         readonly evidenceExport: string;
+        readonly evidenceHelper: string;
         readonly containerBundles: string;
         readonly journals: string;
         readonly root: string;
@@ -63,6 +69,7 @@ export interface TargetDefaultWorldReadinessConfig {
     };
     readonly timeoutMs: number;
 }
+export declare const parseTargetPreparedArtifactMappings: (raw: unknown) => readonly PreparedArtifactMapping[];
 export declare const loadTargetDefaultConfig: (raw: TargetDefaultConfigInputs) => Promise<TargetDefaultConfig>;
 /** Resolves only the paths required by a world-readiness query; performs no I/O. */
 export declare const resolveTargetDefaultWorldReadinessConfig: (raw: TargetDefaultConfigInputs) => TargetDefaultWorldReadinessConfig;

package/dist/cli/targetDefaultConfig.js

@@ -3,6 +3,8 @@ import { lstat, mkdir, open, realpath } from "node:fs/promises";
 import path from "node:path";
 import { types as nodeTypes } from "node:util";
 import { resolveSpawnfileHome } from "../auth/index.js";
+import { parsePreparedEvidenceHelperReceipt, } from "../evidenceExportHelper/index.js";
+import { parseDockerBaseImageReference } from "../target/dockerBaseImage.js";
 import { parseDockerArtifactMappings } from "../target/dockerArtifactsProvider.js";
 export { resolveTargetDefaultJournalRoot } from "../target/journalRoot.js";
 export const TARGET_DEFAULT_CONFIG_ERROR = "Target configuration failed";
@@ -16,7 +18,8 @@ const CHILD_ROOTS = Object.freeze([
     "secret-authority",
     "attachment-authority",
     "world-authority",
-    "evidence-export"
+    "evidence-export",
+    "evidence-helper"
 ]);
 const fail = () => { throw new Error(TARGET_DEFAULT_CONFIG_ERROR); };
 const byteLength = (value) => Buffer.byteLength(value, "utf8");
@@ -25,7 +28,7 @@ const descriptorValues = (raw) => {
         || Object.getPrototypeOf(raw) !== Object.prototype)
         return fail();
     const expected = [
-        "artifactMappings", "containerBundleStoreRoot", "context", "dockerCommand", "evidenceDestination",
+        "artifactMappings", "containerBundleStoreRoot", "context", "dockerCommand", "evidenceDestination", "evidenceHelperBaseImage", "preparedEvidenceHelper",
         "helperArtifactManifestDigest", "preparedArtifactMappings", "timeoutMs"
     ];
     const required = ["context", "dockerCommand", "evidenceDestination", "timeoutMs"];
@@ -38,7 +41,7 @@ const descriptorValues = (raw) => {
         return fail();
     return Object.fromEntries(expected.filter((key) => Object.hasOwn(descriptors, key)).map((key) => [key, descriptors[key].value]));
 };
-const preparedMappings = (raw) => {
+export const parseTargetPreparedArtifactMappings = (raw) => {
     if (raw === undefined)
         return Object.freeze([]);
     if (!Array.isArray(raw) || raw.length > 32)
@@ -211,7 +214,7 @@ const prepareRoots = async (containerBundleStoreRoot) => {
         : CHILD_ROOTS;
     const created = await Promise.all(childRoots.map((name) => ensureOwnedRoot(path.join(root, name))));
     const containerBundles = containerBundleStoreRoot === undefined
-        ? created[6]
+        ? created[7]
         : await prepareExplicitContainerBundleRoot(containerBundleStoreRoot, root);
     return Object.freeze({
         root,
@@ -221,6 +224,7 @@ const prepareRoots = async (containerBundleStoreRoot) => {
         attachmentAuthority: created[3],
         worldAuthority: created[4],
         evidenceExport: created[5],
+        evidenceHelper: created[6],
         containerBundles
     });
 };
@@ -270,6 +274,17 @@ export const loadTargetDefaultConfig = async (raw) => {
                 || !DIGEST.test(value.helperArtifactManifestDigest))))
         return fail();
     const dockerCommand = command(value.dockerCommand);
+    const evidenceHelperBaseImage = value.evidenceHelperBaseImage === undefined ? undefined
+        : parseDockerBaseImageReference(value.evidenceHelperBaseImage) ?? fail();
+    const preparedEvidenceHelper = value.preparedEvidenceHelper === undefined ? undefined
+        : (() => { try {
+            return parsePreparedEvidenceHelperReceipt(value.preparedEvidenceHelper);
+        }
+        catch {
+            return fail();
+        } })();
+    if ((evidenceHelperBaseImage === undefined) !== (preparedEvidenceHelper === undefined))
+        return fail();
     let artifactMappings;
     try {
         artifactMappings = value.artifactMappings === undefined
@@ -278,7 +293,7 @@ export const loadTargetDefaultConfig = async (raw) => {
     catch {
         return fail();
     }
-    const preparedArtifactMappings = preparedMappings(value.preparedArtifactMappings);
+    const preparedArtifactMappings = parseTargetPreparedArtifactMappings(value.preparedArtifactMappings);
     if (preparedArtifactMappings.some((prepared) => artifactMappings.some((artifact) => artifact.artifact_manifest_digest === prepared.artifact_manifest_digest)))
         return fail();
     const evidenceDestination = await validateDestination(value.evidenceDestination);
@@ -290,6 +305,8 @@ export const loadTargetDefaultConfig = async (raw) => {
         artifactMappings,
         context: value.context,
         dockerCommand,
+        ...(evidenceHelperBaseImage === undefined ? {} : { evidenceHelperBaseImage }),
+        ...(preparedEvidenceHelper === undefined ? {} : { preparedEvidenceHelper }),
         evidenceDestination,
         ...(matches.length === 1 ? { helperArtifact: matches[0] } : {}),
         preparedArtifactMappings,

package/dist/cli/targetDefaultConfigStdin.js

@@ -92,7 +92,7 @@ const exactDefaultConfigObject = (raw) => {
         || Object.getPrototypeOf(raw) !== Object.prototype)
         return fail();
     const expected = [
-        "artifactMappings", "container_bundle_store_root", "context", "dockerCommand", "evidenceDestination",
+        "artifactMappings", "container_bundle_store_root", "context", "dockerCommand", "evidenceDestination", "evidenceHelperBaseImage", "preparedEvidenceHelper",
         "helperArtifactManifestDigest", "preparedArtifactMappings", "timeoutMs", "version"
     ];
     const required = ["context", "dockerCommand", "evidenceDestination", "timeoutMs", "version"];
@@ -193,6 +193,12 @@ const defaultConfigInputs = (raw) => ({
     context: raw.context,
     dockerCommand: raw.dockerCommand,
     evidenceDestination: raw.evidenceDestination,
+    ...(Object.hasOwn(raw, "evidenceHelperBaseImage") ? {
+        evidenceHelperBaseImage: raw.evidenceHelperBaseImage
+    } : {}),
+    ...(Object.hasOwn(raw, "preparedEvidenceHelper") ? {
+        preparedEvidenceHelper: raw.preparedEvidenceHelper
+    } : {}),
     ...(Object.hasOwn(raw, "helperArtifactManifestDigest") ? {
         helperArtifactManifestDigest: raw.helperArtifactManifestDigest
     } : {}),

package/dist/cli/targetDefaultHandlerFactory.js

@@ -9,7 +9,8 @@ import { createDockerSecretOperations } from "../target/dockerSecrets.js";
 import { selectTarget } from "../target/dockerTarget.js";
 import { createDockerWorldServiceOperations } from "../target/dockerWorldService.js";
 import { createEvidenceExportOperations } from "../target/evidenceExport.js";
-import { EVIDENCE_EXPORT_HELPER_CONTRACT } from "../target/evidenceExportProvider.js";
+import { createEvidenceExportHelper, EVIDENCE_EXPORT_HELPER_CONTRACT } from "../target/evidenceExportProvider.js";
+import { resolvePreparedEvidenceHelperImage } from "../evidenceExportHelper/index.js";
 import { createDockerOrganizationAttachmentOperations } from "../target/organizationAttachment.js";
 import { createTargetEvidenceHelperResolutionRequest } from "./targetEvidenceHelperResolution.js";
 export const targetDefaultHandlerFactories = Object.freeze({
@@ -69,7 +70,7 @@ const requireAuthorities = (raw) => {
     const names = [
         "artifactIdentityStore", "attachmentAuthorityStore",
         "evidenceExportAuthorityStore", "executors", "handoffResolver",
-        "helperArtifactResolver", "journals", "secretAuthorityStore",
+        "helperArtifactResolver", "helperExecutor", "journals", "secretAuthorityStore",
         "secretResolver", "topologyAttestor", "worldAuthorityStore", "worldResolver"
     ];
     if (!raw || typeof raw !== "object" || Array.isArray(raw) || nodeTypes.isProxy(raw)
@@ -95,6 +96,9 @@ const requireAuthorities = (raw) => {
     if (executorNames.some((name) => typeof executors[name] !== "function")) {
         throw new Error("Target handler initialization failed");
     }
+    if (typeof values.helperExecutor !== "function") {
+        throw new Error("Target handler initialization failed");
+    }
     for (const name of [
         "handoffResolver", "journals", "secretResolver", "worldResolver"
     ]) {
@@ -180,6 +184,23 @@ const execute = async (expected, factories, authorities, config, raw) => {
                 }).execute(request);
             case "export_evidence_volume":
             case "recover_operation": {
+                if (config.evidenceHelperBaseImage && config.preparedEvidenceHelper) {
+                    const helperInput = { baseImage: config.evidenceHelperBaseImage, context: config.context,
+                        executor: authorities.helperExecutor, privateRoot: config.paths.evidenceHelper,
+                        timeoutMs: config.timeoutMs };
+                    const image = await resolvePreparedEvidenceHelperImage(helperInput, config.preparedEvidenceHelper);
+                    const localHelper = createEvidenceExportHelper({ artifactManifestDigest: config.preparedEvidenceHelper.digest,
+                        imageDigest: image.configDigest, imageReference: image.imageReference, resultHandle: config.preparedEvidenceHelper.handle });
+                    const operations = factories.evidence({
+                        ...common, artifactIdentityStore: authorities.artifactIdentityStore,
+                        authorityStore: authorities.evidenceExportAuthorityStore, executor: authorities.executors.resource,
+                        exportExecutor: authorities.executors.evidenceExport, helperArtifactContract: EVIDENCE_EXPORT_HELPER_CONTRACT,
+                        helperArtifactManifestDigest: config.preparedEvidenceHelper.digest, localHelper
+                    });
+                    return request.operation === "recover_operation"
+                        ? operations.recover(request, config.evidenceDestination)
+                        : operations.execute(request, config.evidenceDestination);
+                }
                 if (!config.helperArtifact || !authorities.helperArtifactResolver) {
                     throw new Error("Target evidence helper is not configured");
                 }

package/dist/cli/targetDefaultHandlers.d.ts

@@ -1,6 +1,6 @@
 import type { TargetTopologyAttestationRequest } from "../target/contracts.js";
 import type { TargetTopologyAttestationResult } from "../target/topologyAttestation.js";
-import type { TargetPublicArtifactSnapshot, TargetPublicArtifactSnapshotRequest } from "../target/publicArtifactSnapshot.js";
+import type { TargetPublicArtifactSnapshotRequest, TargetPublicArtifactSnapshotResult } from "../target/publicArtifactSnapshot.js";
 import type { TargetTopologyActivationResult } from "../target/topologyActivation.js";
 import type { TargetDefaultConfig } from "./targetDefaultConfig.js";
 import type { TargetCommandHandlers } from "./targetCommands.js";
@@ -15,7 +15,7 @@ export declare const withTargetDefaultHandlerSession: <Result>(config: TargetDef
 /** The read-only attestor owns the same private authority graph as mutations. */
 export declare const attestTargetDefaultTopology: (config: TargetDefaultConfig, request: TargetTopologyAttestationRequest) => Promise<TargetTopologyAttestationResult>;
 /** Read one exact, bounded public projection from an attested world service. */
-export declare const snapshotTargetDefaultPublicArtifact: (config: TargetDefaultConfig, request: TargetPublicArtifactSnapshotRequest) => Promise<TargetPublicArtifactSnapshot>;
+export declare const snapshotTargetDefaultPublicArtifact: (config: TargetDefaultConfig, request: TargetPublicArtifactSnapshotRequest) => Promise<TargetPublicArtifactSnapshotResult>;
 export declare const activateTargetDefaultTopology: (config: TargetDefaultConfig, request: TargetTopologyAttestationRequest) => Promise<TargetTopologyActivationResult>;
 /** Internal lifecycle primitive; not re-exported from the package surface. */
 export declare const runTargetDefaultHandlerSession: <Result>(session: TargetDefaultHandlerSession, invoke: (handlers: TargetCommandHandlers) => Promise<Result>, signal?: AbortSignal) => Promise<Result>;

package/dist/cli/targetProductionCommands.d.ts

@@ -0,0 +1,5 @@
+import type { Command } from "commander";
+import type { TargetDefaultConfig } from "./targetDefaultConfig.js";
+import { type SetTargetCommandExitCode, type TargetCommandHandlerSession, type TargetCommandStreams } from "./targetCommands.js";
+export declare const createProductionTargetCommandSession: (config: TargetDefaultConfig) => TargetCommandHandlerSession;
+export declare const registerProductionTargetCommands: (program: Command, streams: TargetCommandStreams, stdin: AsyncIterable<unknown>, setExitCode: SetTargetCommandExitCode) => void;

package/dist/cli/targetProductionCommands.js

@@ -0,0 +1,45 @@
+import { registerContainerBundleCommand } from "./containerBundleCommand.js";
+import { readTargetDefaultConfigStdin, readTargetWorldReadinessConfigStdin, } from "./targetDefaultConfigStdin.js";
+import { createProductionTargetWorldQuerySession } from "./targetDefaultWorldQueries.js";
+import { registerTargetConfigResolverCommand, TARGET_CONFIG_RESOLVER_COMMAND, } from "./targetConfigResolverCommand.js";
+import { createProductionTargetLookupLoader } from "./targetLookupCommands.js";
+import { registerTargetCommands, } from "./targetCommands.js";
+export const createProductionTargetCommandSession = (config) => Object.freeze({
+    activateTopology: async (request) => {
+        const { activateTargetDefaultTopology } = await import("./targetDefaultHandlers.js");
+        return activateTargetDefaultTopology(config, request);
+    },
+    run: async (invokeHandlers) => {
+        const { withTargetDefaultHandlerSession } = await import("./targetDefaultHandlers.js");
+        return withTargetDefaultHandlerSession(config, invokeHandlers);
+    },
+    attestTopology: async (request) => {
+        const { attestTargetDefaultTopology } = await import("./targetDefaultHandlers.js");
+        return attestTargetDefaultTopology(config, request);
+    },
+    queryWorldReadiness: async (request) => {
+        const { queryTargetDefaultWorldReadiness } = await import("./targetDefaultWorldReadiness.js");
+        return queryTargetDefaultWorldReadiness(config, request);
+    },
+    queryWorldClock: async (request) => {
+        const { queryTargetDefaultWorldClock } = await import("./targetDefaultWorldClock.js");
+        return queryTargetDefaultWorldClock(config, request);
+    },
+    snapshotPublicArtifact: async (request) => {
+        const { snapshotTargetDefaultPublicArtifact } = await import("./targetDefaultHandlers.js");
+        return snapshotTargetDefaultPublicArtifact(config, request);
+    },
+});
+export const registerProductionTargetCommands = (program, streams, stdin, setExitCode) => {
+    const target = registerTargetCommands(program, async (configInput) => {
+        if (configInput !== "-")
+            throw new TypeError("Invalid target configuration");
+        return createProductionTargetCommandSession(await readTargetDefaultConfigStdin(stdin));
+    }, streams, setExitCode, createProductionTargetLookupLoader(stdin), async (configInput) => {
+        if (configInput !== "-")
+            throw new TypeError("Invalid target configuration");
+        return createProductionTargetWorldQuerySession(await readTargetWorldReadinessConfigStdin(stdin));
+    }, [TARGET_CONFIG_RESOLVER_COMMAND]);
+    registerContainerBundleCommand(target, stdin, streams, setExitCode);
+    registerTargetConfigResolverCommand(target, streams, setExitCode);
+};

package/dist/cli/trainCommand.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+import type { CliHandlers, CliStreams } from "./runCli.js";
+export declare const registerTrainCommand: (program: Command, handlers: CliHandlers, streams: CliStreams, packageVersion: string, setExitCode: (code: number) => void, signal?: AbortSignal) => void;

package/dist/cli/trainCommand.js

@@ -0,0 +1,114 @@
+import { SpawnfileError } from "../shared/index.js";
+const forwarded = ["train", "validation", "test", "editable", "resource", "judge", "judge-citation-repairs", "validation-group", "optimizer-model",
+    "bridge-command", "out", "max-trials", "max-proposals", "seed", "timeout-ms", "experiment-timeout-ms", "trial-timeout-ms", "view", "cost-config", "concurrency"];
+const repeated = new Set(["editable", "resource", "judge", "judge-citation-repairs", "validation-group"]);
+const key = (name) => name.replace(/-([a-z])/gu, (_, letter) => letter.toUpperCase());
+export const registerTrainCommand = (program, handlers, streams, packageVersion, setExitCode, signal) => {
+    const command = program.command("train")
+        .description("Plan, rewind, or train one canonical agent through its declared training inputs")
+        .argument("[path]", "Canonical project directory or Spawnfile path", process.cwd())
+        .option("--agent <id>", "Canonical agent id or unambiguous short name (inferred for one agent)")
+        .option("--paideia-command <executable>", "Installed Paideia executable; no shell or automatic install", "paideia")
+        .option("--training-image <immutable-image>", "Pinned image containing the complete training environment")
+        .option("--training-config <json>", "V2 image recipe and declared inputs, or advanced v1 local bindings")
+        .option("--plan", "Print the resolved training authoring plan without executing training")
+        .option("--materialize <example>", "Rewind an authored example into --out without running training")
+        .option("--history <directory>", "Local recorded history for --materialize")
+        .option("--dry-run", "Validate and estimate without compiling, authenticating or starting models")
+        .option("--repair-measurements <parent-out>", "Fork captured work into a fresh output for authorized measurement repair")
+        .option("--repair-witness <manifest>", "Explicit verified image witness for a legacy parent")
+        .option("--resume", "Resume the exact persisted training experiment in --out");
+    for (const name of forwarded) {
+        const flag = `--${name} <value>`;
+        if (repeated.has(name))
+            command.option(flag, `Paideia ${name}; repeatable`, (value, previous) => [...previous, value], []);
+        else
+            command.option(flag, name === "out" ? "Output directory for training or moment materialization" : `Paideia ${name}`);
+    }
+    command.action(async (inputPath, options) => {
+        if (typeof options.materialize === "string") {
+            if (options.plan === true) {
+                throw new SpawnfileError("validation_error", "--materialize and --plan are mutually exclusive");
+            }
+            if (typeof options.out !== "string") {
+                throw new SpawnfileError("validation_error", "--materialize requires --out");
+            }
+            const project = await handlers.loadTrainingProject(inputPath);
+            const plan = handlers.resolveTrainingPlan(project, options.agent, packageVersion);
+            const moment = await handlers.materializeTrainingMoment({ plan, project, example: options.materialize,
+                historyDir: options.history, out: options.out });
+            if (moment.status === "refused") {
+                streams.stderr(`error: Moment refused: ${moment.inputs.filter((input) => input.refusal !== null).length} input refusal(s), ${moment.leakCheck.findings} leak finding(s); see moment.json in --out`);
+                setExitCode(1);
+            }
+            else {
+                streams.stdout(JSON.stringify(moment, null, 2));
+                setExitCode(0);
+            }
+            return;
+        }
+        if (options.history !== undefined) {
+            throw new SpawnfileError("validation_error", "--history requires --materialize");
+        }
+        if (options.plan === true) {
+            const plan = await handlers.createTrainingPlan(inputPath, {
+                agent: options.agent, packageVersion
+            });
+            streams.stdout(JSON.stringify(plan, null, 2));
+            setExitCode(0);
+            return;
+        }
+        for (const name of ["timeout-ms", "experiment-timeout-ms", "trial-timeout-ms"]) {
+            const value = options[key(name)], maximum = name === "trial-timeout-ms" ? 86_400_000 : 604_800_000;
+            if (value !== undefined && (!/^\d+$/u.test(String(value)) || !Number.isSafeInteger(Number(value)) || Number(value) < 1 || Number(value) > maximum)) {
+                throw new SpawnfileError("validation_error", `--${name} must be an integer from 1 to ${maximum}`);
+            }
+        }
+        const args = [];
+        for (const name of forwarded) {
+            const value = options[key(name)];
+            if (typeof value === "string")
+                args.push(`--${name}`, value);
+            else if (Array.isArray(value))
+                for (const item of value)
+                    args.push(`--${name}`, item);
+        }
+        if (options.dryRun === true)
+            args.push("--dry-run");
+        if (options.resume === true)
+            args.push("--resume");
+        const project = await handlers.loadTrainingProject(inputPath);
+        const plan = handlers.resolveTrainingPlan(project, options.agent, packageVersion);
+        const timeout = Number(options.experimentTimeoutMs ?? options.timeoutMs ?? plan.deadlines?.experiment_ms ?? 43_200_000);
+        if (options.experimentTimeoutMs === undefined && options.timeoutMs === undefined)
+            args.push("--experiment-timeout-ms", String(timeout));
+        if (options.trialTimeoutMs === undefined && plan.deadlines?.trial_ms !== undefined)
+            args.push("--trial-timeout-ms", String(plan.deadlines.trial_ms));
+        const lowered = plan.targets.length > 0 ? await handlers.lowerTrainingExecution({ project, plan, args,
+            trainingConfig: options.trainingConfig, trainingImage: options.trainingImage }) : undefined;
+        if (lowered && options.dryRun === true) {
+            streams.stdout(JSON.stringify({ ...lowered.execution, container: { configPath: lowered.trainingConfig,
+                    declaration: lowered.declaration, ...(lowered.trainingImage ? { imageOverride: lowered.trainingImage } : {}) } }, null, 2));
+            setExitCode(0);
+            return;
+        }
+        if (!lowered && typeof options.train !== "string") {
+            throw new SpawnfileError("validation_error", `Agent ${plan.agent.id} has no executable training targets; supply --train`);
+        }
+        if (!lowered && options.dryRun !== true && typeof options.out !== "string") {
+            throw new SpawnfileError("validation_error", "Actual training requires --out when no training targets are declared");
+        }
+        if (!lowered && options.dryRun !== true && typeof options.trainingConfig !== "string") {
+            throw new SpawnfileError("validation_error", "Actual training requires --training-config when no training targets are declared; host execution is disabled");
+        }
+        const context = await handlers.createTrainingContext(inputPath, { agent: plan.agent.id, packageVersion });
+        if (lowered)
+            await handlers.allocateTrainingOutputParent(lowered.execution.output);
+        setExitCode(await handlers.delegatePaideiaTraining({ context, args: lowered?.execution.args ?? args, execution: lowered?.execution,
+            repairMeasurements: options.repairMeasurements, repairWitness: options.repairWitness,
+            trainingImage: lowered?.trainingImage ?? options.trainingImage,
+            trainingConfig: lowered?.trainingConfig ?? options.trainingConfig,
+            command: options.paideiaCommand, dryRun: options.dryRun === true,
+            timeoutMs: timeout + 5000, streams, signal }));
+    });
+};