@synopackageland/cli 0.13.1 → 0.15.0

package/dist/standalone/api-description.js

@@ -0,0 +1,73 @@
+import { readFileSync } from 'node:fs';
+import { goChildEnv } from '../runtime/go-env.js';
+import { makeDescriptor, validateDescriptor, flowMethods } from '../ctl/descriptor.js';
+import { sdkBackend } from './manifest.js';
+import { readApiPermissions } from './api-permissions.js';
+import { isBridgeBackend } from './bridge-backend.js';
+import { StandaloneBuildError } from './spk.js';
+import { join } from 'node:path';
+export async function buildApiDescription(m, bridgeMethods, run) {
+    if (!m.ctl?.enabled)
+        return undefined;
+    if (m.backend.kind === 'binary' || m.compose)
+        throw new StandaloneBuildError('CTL_UNSUPPORTED_BACKEND', 'Automatic API descriptions require a standard SDK native App.');
+    let methods;
+    const policy = readApiPermissions(sdkBackend(m), m.capabilities);
+    if (isBridgeBackend(m.backend)) {
+        methods = [...(bridgeMethods ?? []), ...Object.keys(m.apiPermissions?.methods ?? {}).filter(name => Object.values(policy.sdk).some(group => Object.hasOwn(group, name)))].map(method => ({ method, permission: m.apiPermissions?.methods[method] ?? 'administrators' }));
+    }
+    else {
+        if (!readFileSync(join(m.backend.dir, m.backend.main, 'main.go'), 'utf8').includes('--describe'))
+            throw new StandaloneBuildError('CTL_DESCRIBE_REQUIRED', 'Go CGI must support build-only --describe; update its template.');
+        const flags = [`-X main.packageID=${m.package}`, `-X main.version=${m.spkVersion}`, ...(m.capabilities.files || m.capabilities.delegate ? ['-X main.fileStation=session'] : []), ...(m.portal ? ['-X main.portal=on'] : [])].join(' ');
+        const response = await run('go', ['run', '-trimpath', '-buildvcs=false', '-ldflags', flags, m.backend.main, '--describe'], { cwd: m.backend.dir, env: goChildEnv({ ...process.env, GOOS: undefined, GOARCH: undefined, GOARM: undefined, CGO_ENABLED: '0' }), capture: true });
+        if (response.status !== 0)
+            throw new StandaloneBuildError('CTL_DESCRIBE_FAILED', 'Go route metadata export failed.');
+        try {
+            methods = JSON.parse(response.stdout ?? '');
+        }
+        catch {
+            throw new StandaloneBuildError('CTL_DESCRIBE_FAILED', 'Go route exporter returned invalid JSON.');
+        }
+    }
+    if (!Array.isArray(methods) || methods.some(item => typeof item.method !== 'string' || typeof item.permission !== 'string'))
+        throw new StandaloneBuildError('CTL_DESCRIBE_FAILED', 'Invalid registry snapshot.');
+    const registry = new Map(methods.map(item => [item.method, item.permission]));
+    // Identity transport routes are outside the business registry but have immutable SDK ownership.
+    if (m.capabilities.identity) {
+        registry.set('identity.session', 'public');
+        registry.set('identity.logout', 'public');
+    }
+    const bindings = {};
+    const commands = {};
+    const weights = { read: 0, write: 1, destructive: 2 };
+    for (const [id, declared] of Object.entries(m.ctl.commands)) {
+        const command = structuredClone(declared);
+        const names = flowMethods(command.flow);
+        let permission = 'public';
+        for (const name of names) {
+            if (!registry.has(name))
+                throw new StandaloneBuildError('CTL_COMMAND_UNREGISTERED', `Command ${id} references unregistered method ${name}.`);
+            const effective = m.entry === 'admin-only' ? 'administrators' : registry.get(name);
+            registry.set(name, effective);
+            const effect = command.flow.type === 'job' && name !== command.flow.start ? 'read' : command.effect;
+            const previous = bindings[name];
+            if (!previous || weights[effect] > weights[previous.effect])
+                bindings[name] = { permission: effective, effect };
+            if (effective === 'administrators' || effective === 'authenticated' && permission === 'public')
+                permission = effective;
+        }
+        commands[id] = { ...command, permission };
+    }
+    if (m.capabilities.identity) {
+        for (const method of ['identity.session', 'identity.logout'])
+            bindings[method] = { permission: 'public', effect: 'write' };
+    }
+    const description = makeDescriptor({ package: { id: m.package, version: m.spkVersion, displayName: m.displayname }, aliases: m.ctl.aliases ?? [m.package.toLowerCase()], provenance: { developedBy: m.ctl.developedBy ?? 'unknown', generator: 'synopkgland-cli' }, entry: m.entry ?? 'policy', transport: { path: `/webman/3rdparty/${m.package}/cgi/api.cgi`, auth: m.capabilities.identity ? 'dsm-app-session' : 'dsm-session' }, commands, bindings });
+    try {
+        return { description: validateDescriptor(description, m.package, m.spkVersion), registry: Object.fromEntries(registry) };
+    }
+    catch (error) {
+        throw new StandaloneBuildError('CTL_DESCRIPTOR_INVALID', error.message);
+    }
+}

package/dist/standalone/build.d.ts

@@ -23,6 +23,9 @@ export interface StandaloneBuildOptions {
     /** Architectures built at once; defaults to 1. */
     jobs?: number;
     run?: CommandRunner;
+    /** Saved anonymous image manifests/config for an offline Compose rebuild. */
+    composeImageProofs?: Record<string, unknown>;
+    composeImageProofsByArch?: Partial<Record<NativeArchFamily, Record<string, unknown>>>;
 }
 /** Argv only, never a shell; output streams to the terminal except stderr, which is also kept, and captured stdout. */
 export declare const runCommand: CommandRunner;

package/dist/standalone/build.js

@@ -1,14 +1,16 @@
+import { buildApiDescription } from "./api-description.js";
 import { goChildEnv } from "../runtime/go-env.js";
 import { spawn } from "node:child_process";
-import { goModulePath, privateSdkHint, SDK_MODULE, sdkSource } from "../runtime/sdk-source.js";
+import { goModulePath, privateSdkHint, SDK_MODULE, sdkSource, } from "../runtime/sdk-source.js";
 import { existsSync, mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { goBuildEnv } from "../build-spk/dsm-arch.js";
-import { resolveMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM, portalByExecutor, portalMinDsmMessage } from "../build-spk/dsm-version.js";
+import { resolveMinDsm, DEFAULT_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM, portalByExecutor, portalMinDsmMessage, } from "../build-spk/dsm-version.js";
 import { checkCgiBinary } from "./binary.js";
-import { loadStandaloneManifest } from "./manifest.js";
+import { loadStandaloneManifest, } from "./manifest.js";
 import { assembleStandaloneSpk, StandaloneBuildError } from "./spk.js";
+import { buildComposeControl, lockComposeImages, dsmComposeProblem, } from "./compose.js";
 import { buildDaemonControl } from "./daemon.js";
 import { buildIdentityGateway } from "./identity-gateway.js";
 import { buildExecutor } from "../runtime/executor-build.js";
@@ -17,7 +19,7 @@ import { readApiPermissions } from "./api-permissions.js";
 import { checkJobs, commitOutputs, forEachArch } from "./arch-jobs.js";
 import { isBridgeBackend } from "./bridge-backend.js";
 import { requestTimeoutSeconds } from "./request-timeout.js";
-import { buildBridge, prepareBridge } from "./bridge-build.js";
+import { buildBridge, prepareBridge, } from "./bridge-build.js";
 import { portalCatalogs } from "./portal-window.js";
 /** Argv only, never a shell; output streams to the terminal except stderr, which is also kept, and captured stdout. */
 export const runCommand = (command, args, options) => new Promise((done) => {
@@ -29,24 +31,37 @@ export const runCommand = (command, args, options) => new Promise((done) => {
     let stderr = "";
     let stdout = "";
     child.stdout?.setEncoding("utf8");
-    child.stdout?.on("data", (chunk) => { stdout += chunk; });
+    child.stdout?.on("data", (chunk) => {
+        stdout += chunk;
+    });
     child.stderr.setEncoding("utf8");
     child.stderr.on("data", (chunk) => {
         stderr += chunk;
         process.stderr.write(chunk);
     });
     child.on("error", (error) => done({ status: null, stderr, missing: error.code === "ENOENT" }));
-    child.on("close", (status) => done({ status, stderr, missing: false, ...(options.capture ? { stdout } : {}) }));
+    child.on("close", (status) => done({
+        status,
+        stderr,
+        missing: false,
+        ...(options.capture ? { stdout } : {}),
+    }));
 });
 /** `runCommand` for concurrent builds: every output line goes to stderr behind `prefix`, so architectures stay apart. */
 export function prefixedRunner(prefix) {
     return (command, args, options) => new Promise((done) => {
-        const child = spawn(command, args, { cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"] });
+        const child = spawn(command, args, {
+            cwd: options.cwd,
+            env: options.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
         let stderr = "";
         let stdout = "";
         if (options.capture) {
             child.stdout.setEncoding("utf8");
-            child.stdout.on("data", (chunk) => { stdout += chunk; });
+            child.stdout.on("data", (chunk) => {
+                stdout += chunk;
+            });
         }
         const relay = (stream, keep) => {
             let partial = "";
@@ -59,14 +74,21 @@ export function prefixedRunner(prefix) {
                 for (const line of lines)
                     process.stderr.write(`${prefix}${line}\n`);
             });
-            stream.on("end", () => { if (partial)
-                process.stderr.write(`${prefix}${partial}\n`); });
+            stream.on("end", () => {
+                if (partial)
+                    process.stderr.write(`${prefix}${partial}\n`);
+            });
         };
         if (!options.capture)
             relay(child.stdout, false);
         relay(child.stderr, true);
         child.on("error", (error) => done({ status: null, stderr, missing: error.code === "ENOENT" }));
-        child.on("close", (status) => done({ status, stderr, missing: false, ...(options.capture ? { stdout } : {}) }));
+        child.on("close", (status) => done({
+            status,
+            stderr,
+            missing: false,
+            ...(options.capture ? { stdout } : {}),
+        }));
     });
 }
 /** The runner one architecture uses: the caller's, or a labelled one while several architectures share the terminal. */
@@ -83,14 +105,19 @@ export async function buildStandalone(options) {
     const manifest = options.minDsm === undefined
         ? loaded.manifest
         : { ...loaded.manifest, os_min_ver: resolveMinDsm(options.minDsm) };
-    if (manifest.capabilities.rootOps === true && !isDsmAtLeast(manifest.os_min_ver, DEFAULT_MIN_DSM)) {
+    if (manifest.capabilities.rootOps === true &&
+        !isDsmAtLeast(manifest.os_min_ver, DEFAULT_MIN_DSM)) {
         throw new StandaloneBuildError("STANDALONE_OS_MIN_VER_INVALID", `root templates require DSM ${DEFAULT_MIN_DSM} or later.`);
     }
-    if (manifest.portal && !isDsmAtLeast(manifest.os_min_ver, PORTAL_EXECUTOR_MIN_DSM)) {
+    if (manifest.portal &&
+        !isDsmAtLeast(manifest.os_min_ver, PORTAL_EXECUTOR_MIN_DSM)) {
         throw new StandaloneBuildError("STANDALONE_PORTAL_MIN_DSM", `[STANDALONE_PORTAL_MIN_DSM] ${portalMinDsmMessage(manifest.os_min_ver, "portal")}`);
     }
     if (manifest.compose && !isDsmAtLeast(manifest.os_min_ver, "7.2.1-69057"))
         throw new StandaloneBuildError("STANDALONE_IDENTITY_GATEWAY_INVALID", "compose identity_gateway requires DSM >= 7.2.1.");
+    const composeProblem = manifest.compose && dsmComposeProblem(manifest.compose);
+    if (composeProblem)
+        throw new StandaloneBuildError(composeProblem.code, composeProblem.message);
     const jobs = checkJobs(options.jobs);
     const arches = options.arches ?? manifest.arches;
     for (const arch of arches) {
@@ -104,20 +131,42 @@ export async function buildStandalone(options) {
     const warnings = new Set();
     try {
         const bridge = await prepareBridge(manifest, work);
+        const apiArtifact = await buildApiDescription(manifest, bridge?.methods, options.run ?? runCommand);
+        const apiDescription = apiArtifact?.description;
+        const sourceManifest = manifest;
         const outputs = await commitOutputs(outDir, (stage) => forEachArch(arches, jobs, async (arch) => {
+            const manifest = lockComposeImages(sourceManifest, arch, true, options.composeImageProofsByArch?.[arch] ??
+                options.composeImageProofs);
             const run = runnerFor(options.run, jobs, arch);
             const archWork = join(work, arch);
             mkdirSync(archWork);
             const executor = await buildExecutor(manifest, arch, archWork, run);
-            executor?.warnings.forEach(warning => warnings.add(warning));
+            executor?.warnings.forEach((warning) => warnings.add(warning));
             const builtManifest = executor ? { ...manifest, executor } : manifest;
-            const { cgi: cgiPath, worker: backgroundWorker, app } = await backendFor(builtManifest, arch, archWork, run, bridge);
+            const { cgi: cgiPath, worker: backgroundWorker, app, } = await backendFor(builtManifest, arch, archWork, run, bridge);
             const outputPath = join(stage, `${manifest.package}-${manifest.spkVersion}-${arch}.spk`);
             const daemonControl = await buildDaemonControl(manifest, arch, archWork, run);
             const identityGateway = await buildIdentityGateway(manifest, arch, archWork, run);
+            const composeControl = await buildComposeControl(manifest, arch, archWork, run);
             // A portal needs the executor, so the executor's SDK carries the panel text.
-            const portalText = manifest.portal && executor ? portalCatalogs(sdkSource(executor.sdk).goDir) : undefined;
-            await assembleStandaloneSpk({ manifest: builtManifest, arch, cgiPath, outputPath, daemonControl, identityGateway, backgroundWorker, executor, app, portalText });
+            const portalText = manifest.portal && executor
+                ? portalCatalogs(sdkSource(executor.sdk).goDir)
+                : undefined;
+            await assembleStandaloneSpk({
+                manifest: builtManifest,
+                arch,
+                cgiPath,
+                outputPath,
+                daemonControl,
+                identityGateway,
+                composeControl,
+                backgroundWorker,
+                executor,
+                app,
+                portalText,
+                apiDescription,
+                apiRegistry: apiArtifact?.registry,
+            });
             return outputPath;
         }));
         return { outputs, warnings: [...warnings] };
@@ -132,9 +181,14 @@ async function buildUi(manifest, run) {
         return;
     }
     const [command, ...args] = build.command;
-    const result = await run(command, args, { cwd: build.cwd, env: { ...process.env } });
+    const result = await run(command, args, {
+        cwd: build.cwd,
+        env: { ...process.env },
+    });
     if (result.missing || result.status !== 0) {
-        const installHint = command === "npm" && existsSync(join(build.cwd, "package.json")) && !existsSync(join(build.cwd, "node_modules"))
+        const installHint = command === "npm" &&
+            existsSync(join(build.cwd, "package.json")) &&
+            !existsSync(join(build.cwd, "node_modules"))
             ? `\nThe UI dependencies are not installed. Run npm ${existsSync(join(build.cwd, "package-lock.json")) ? "ci" : "install"} in ${build.cwd}, then run build again.`
             : "";
         throw new StandaloneBuildError("STANDALONE_UI_BUILD_FAILED", `UI build (${build.command.join(" ")}) failed. ${installHint}\n${result.stderr}`);
@@ -143,19 +197,29 @@ async function buildUi(manifest, run) {
 /** The checked CGI of one architecture and, with capabilities.jobs, its fixed worker; or the runtime and App of a bridge App. */
 async function backendFor(manifest, arch, work, run, bridge) {
     const backend = manifest.backend;
+    if (manifest.compose)
+        return {};
     if (isBridgeBackend(backend))
         return buildBridge(manifest, bridge, arch, work, run);
-    const cgi = backend.kind === "binary" ? backend.files[arch] : await buildGoCgi(manifest, backend, arch, work, run);
+    const cgi = backend.kind === "binary"
+        ? backend.files[arch]
+        : await buildGoCgi(manifest, backend, arch, work, run);
     const problem = checkCgiBinary(backend.kind === "go" ? work : manifest.root, cgi, arch);
     if (problem) {
         throw new StandaloneBuildError(problem.code, problem.message);
     }
-    return { cgi, worker: await buildBackgroundWorker(manifest, arch, work, run) };
+    return {
+        cgi,
+        worker: await buildBackgroundWorker(manifest, arch, work, run),
+    };
 }
 async function buildGoCgi(manifest, backend, arch, work, run) {
     // UI build hooks run after validation. Refuse policy changes rather than
     // compiling CGI permissions different from the launcher metadata snapshot.
-    if (readApiPermissions(backend, manifest.capabilities).digest !== manifest.apiPermissionsDigest || readApiPermissions(backend, manifest.capabilities).sdkDigest !== manifest.apiSDKPermissionsDigest) {
+    if (readApiPermissions(backend, manifest.capabilities).digest !==
+        manifest.apiPermissionsDigest ||
+        readApiPermissions(backend, manifest.capabilities).sdkDigest !==
+            manifest.apiSDKPermissionsDigest) {
         throw new StandaloneBuildError("STANDALONE_API_PERMISSIONS_CHANGED", "API permissions changed during build; check and rebuild.");
     }
     const module = goModulePath(backend.dir);
@@ -172,13 +236,35 @@ async function buildGoCgi(manifest, backend, arch, work, run) {
         `-X ${module}/internal/api.expectedPermissionsDigest=${manifest.apiPermissionsDigest}`,
         `-X ${SDK_MODULE}/api.expectedSDKPermissionsDigest=${manifest.apiSDKPermissionsDigest}`,
         ...delegateBuildFlags(manifest),
-        ...(manifest.executor ? [`-X main.executorDigest=${manifest.executor.executorDigest}`, `-X main.policyDigest=${manifest.executor.policyDigest}`] : []),
-        ...(manifest.capabilities.identity ? [`-X main.identity=${manifest.capabilities.identity}`] : []),
-        ...(manifest.capabilities.files || manifest.capabilities.delegate ? [`-X main.fileStation=session`] : []),
+        ...(manifest.executor
+            ? [
+                `-X main.executorDigest=${manifest.executor.executorDigest}`,
+                `-X main.policyDigest=${manifest.executor.policyDigest}`,
+            ]
+            : []),
+        ...(manifest.capabilities.identity
+            ? [`-X main.identity=${manifest.capabilities.identity}`]
+            : []),
+        ...(manifest.capabilities.files || manifest.capabilities.delegate
+            ? [`-X main.fileStation=session`]
+            : []),
         ...(manifest.entry ? [`-X main.entry=${manifest.entry}`] : []),
-        ...(manifest.portal ? [`-X main.portal=${portalByExecutor(manifest.os_min_ver) ? "executor" : "on"}`] : []),
+        ...(manifest.portal
+            ? [
+                `-X main.portal=${portalByExecutor(manifest.os_min_ver) ? "executor" : "on"}`,
+            ]
+            : []),
     ].join(" ");
-    const result = await run("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, backend.main], {
+    const result = await run("go", [
+        "build",
+        "-trimpath",
+        "-buildvcs=false",
+        "-ldflags",
+        ldflags,
+        "-o",
+        out,
+        backend.main,
+    ], {
         cwd: backend.dir,
         env: goChildEnv({ ...process.env, ...goBuildEnv(arch) }),
     });
@@ -186,7 +272,9 @@ async function buildGoCgi(manifest, backend, arch, work, run) {
         throw new StandaloneBuildError("STANDALONE_GO_MISSING", "The go command was not found. Install Go 1.25 or later (https://go.dev/dl/), or package an existing executable with backend.binary.");
     }
     if (result.status !== 0) {
-        const fetchingSdk = result.stderr.includes(`${SDK_MODULE}@`) ? privateSdkHint() : "";
+        const fetchingSdk = result.stderr.includes(`${SDK_MODULE}@`)
+            ? privateSdkHint()
+            : "";
         throw new StandaloneBuildError("STANDALONE_GO_BUILD_FAILED", `go build (${arch}) failed.\n${result.stderr}${fetchingSdk}`);
     }
     return out;
@@ -196,10 +284,29 @@ async function buildBackgroundWorker(manifest, arch, work, run) {
     if (!manifest.capabilities.jobs || manifest.backend.kind !== "go")
         return undefined;
     const out = join(work, `background-worker-${arch}`);
-    const ldflags = ["-s", "-w", "-buildid=", `-X main.packageID=${manifest.package}`, ...delegateBuildFlags(manifest),
-        ...(manifest.executor ? [`-X main.executorDigest=${manifest.executor.executorDigest}`, `-X main.policyDigest=${manifest.executor.policyDigest}`] : []),
+    const ldflags = [
+        "-s",
+        "-w",
+        "-buildid=",
+        `-X main.packageID=${manifest.package}`,
+        ...delegateBuildFlags(manifest),
+        ...(manifest.executor
+            ? [
+                `-X main.executorDigest=${manifest.executor.executorDigest}`,
+                `-X main.policyDigest=${manifest.executor.policyDigest}`,
+            ]
+            : []),
     ].join(" ");
-    const result = await run("go", ["build", "-trimpath", "-buildvcs=false", "-ldflags", ldflags, "-o", out, BACKGROUND_WORKER_MAIN], {
+    const result = await run("go", [
+        "build",
+        "-trimpath",
+        "-buildvcs=false",
+        "-ldflags",
+        ldflags,
+        "-o",
+        out,
+        BACKGROUND_WORKER_MAIN,
+    ], {
         cwd: manifest.backend.dir,
         env: goChildEnv({ ...process.env, ...goBuildEnv(arch) }),
     });
@@ -219,7 +326,7 @@ function delegateBuildFlags(manifest) {
         delegateScope: d.scope,
         delegateOperationsJSON: JSON.stringify([...d.operations].sort()),
         delegateDestinationsJSON: JSON.stringify(d.destinations ? [...d.destinations].sort() : []),
-        delegateLifetime: d.lifetime ?? '',
+        delegateLifetime: d.lifetime ?? "",
     };
     // Go's quoted.Split does not process backslash escapes. Interior JSON quotes
     // in a whitespace-free argument are literal; never shell-escape this string.
@@ -231,6 +338,6 @@ function delegateBuildFlags(manifest) {
             return `-X '${arg}'`;
         if (!arg.includes('"'))
             return `-X "${arg}"`;
-        throw new StandaloneBuildError('STANDALONE_GO_BUILD_FAILED', 'Delegate scope with whitespace and both quote types cannot be represented in Go linker flags.');
+        throw new StandaloneBuildError("STANDALONE_GO_BUILD_FAILED", "Delegate scope with whitespace and both quote types cannot be represented in Go linker flags.");
     });
 }

package/dist/standalone/compose-errors.d.ts

@@ -0,0 +1,3 @@
+import type { ErrorCodeEntry } from "../error-registry.js";
+/** SDK planner errors accepted at this versioned tool boundary. */
+export declare const COMPOSE_ERRORS: Record<string, ErrorCodeEntry>;

package/dist/standalone/compose-errors.js

@@ -0,0 +1,243 @@
+/** SDK planner errors accepted at this versioned tool boundary. */
+export const COMPOSE_ERRORS = {
+    COMPOSE_SUBNET_STATE_INVALID: {
+        code: "COMPOSE_SUBNET_STATE_INVALID",
+        description: "The private ingress history is invalid or has foreign ownership.",
+        suggestion: "Inspect the package private state; do not bypass route checks or claim network ownership.",
+    },
+    COMPOSE_SUBNET_INVALID: {
+        code: "COMPOSE_SUBNET_INVALID",
+        description: "Invalid ingress subnet candidate.",
+        suggestion: "Set compose.network.ingress_candidate to an integer from 0 through 255.",
+    },
+    COMPOSE_SUBNET_CONFLICT: {
+        code: "COMPOSE_SUBNET_CONFLICT",
+        description: "The fixed ingress subnet overlaps a NAS route.",
+        suggestion: "Choose a different compose.network.ingress_candidate and rebuild; do not change NAS networks.",
+    },
+    COMPOSE_SUBNET_INVENTORY_UNAVAILABLE: {
+        code: "COMPOSE_SUBNET_INVENTORY_UNAVAILABLE",
+        description: "Kernel route inventory is unavailable.",
+        suggestion: "Use a supported Linux package-account environment; never borrow Docker socket or administrator credentials.",
+    },
+    COMPOSE_PRIVATE_BIND_TIMING_UNSUPPORTED: {
+        code: "COMPOSE_PRIVATE_BIND_TIMING_UNSUPPORTED",
+        description: "DSM private-bind initialization is unavailable before official worker acquire.",
+        suggestion: "Use an explicitly selected arbitrary-UID-compatible named volume or keep the configuration unsupported; never initialize pkgvar as root.",
+    },
+    COMPOSE_HEALTH_REQUIRED: {
+        code: "COMPOSE_HEALTH_REQUIRED",
+        description: "Bridge ingress requires a declared App health endpoint.",
+        suggestion: "Set compose.web.health.path and its expected 2xx status.",
+    },
+    COMPOSE_READINESS_INVALID: {
+        code: "COMPOSE_READINESS_INVALID",
+        description: "Bridge readiness configuration is invalid.",
+        suggestion: "Rebuild with the matching SDK and declare a local health path and expected 2xx status.",
+    },
+    COMPOSE_ACQUIRE_GENERATION_INVALID: {
+        code: "COMPOSE_ACQUIRE_GENERATION_INVALID",
+        description: "The lifecycle acquire generation is missing, released or stale.",
+        suggestion: "Start the installed package through Package Center; this record does not attest Docker identity.",
+    },
+    COMPOSE_TCP_NOT_READY: {
+        code: "COMPOSE_TCP_NOT_READY",
+        description: "The declared ingress TCP endpoint is unavailable.",
+        suggestion: "Inspect the official project's startup result; do not expose upstream ports to the LAN.",
+    },
+    COMPOSE_HEALTH_NOT_READY: {
+        code: "COMPOSE_HEALTH_NOT_READY",
+        description: "The App health endpoint did not return the expected status.",
+        suggestion: "Check the declared App health path/status and upstream health; redirects are not followed.",
+    },
+    COMPOSE_REQUEST_INVALID: {
+        code: "COMPOSE_REQUEST_INVALID",
+        description: "The unified Compose request is invalid.",
+        suggestion: "Declare schema-2 files, web and supported DSM differences; see the Compose reference.",
+    },
+    COMPOSE_PROJECT_CONTROL_UNAVAILABLE: {
+        code: "COMPOSE_PROJECT_CONTROL_UNAVAILABLE",
+        description: "Protected official Compose project control is unavailable.",
+        suggestion: "Keep the project disabled until an official protected ACL/project Adapter has been verified; do not use host root or a destination grant.",
+    },
+    COMPOSE_ANONYMOUS_VOLUME_UNSUPPORTED: {
+        code: "COMPOSE_ANONYMOUS_VOLUME_UNSUPPORTED",
+        description: "The declared value:the declared value needs a stable declared volume.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_BASE_PATH_UNSUPPORTED: {
+        code: "COMPOSE_BASE_PATH_UNSUPPORTED",
+        description: "Use the upstream's dedicated origin at /; automatic subpath asset rewriting is not supported.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_BUILD_UNSUPPORTED: {
+        code: "COMPOSE_BUILD_UNSUPPORTED",
+        description: "The declared value must use an upstream prebuilt image.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_EGRESS_ALLOWLIST_UNSUPPORTED: {
+        code: "COMPOSE_EGRESS_ALLOWLIST_UNSUPPORTED",
+        description: "Choose isolated or internet; destination allowlists are not implemented.",
+        suggestion: "Declare isolated or internet; destination allowlists are unsupported.",
+    },
+    COMPOSE_ENV_INVALID: {
+        code: "COMPOSE_ENV_INVALID",
+        description: "Invalid service environment.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_EXTERNAL_VOLUME_UNVERIFIED: {
+        code: "COMPOSE_EXTERNAL_VOLUME_UNVERIFIED",
+        description: "External volume the declared value needs trusted admin ownership/driver readback; no official controller is configured.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_FILE_RESOURCE_UNSUPPORTED: {
+        code: "COMPOSE_FILE_RESOURCE_UNSUPPORTED",
+        description: "Secret/config resource delivery is not implemented; use explicit package-owned configuration.",
+        suggestion: "Use bounded regular project-local files without symlink or remote dependencies, then rebuild from unchanged bytes.",
+    },
+    COMPOSE_IMAGE_INVALID: {
+        code: "COMPOSE_IMAGE_INVALID",
+        description: "Service the declared value needs an image.",
+        suggestion: "Use the intended anonymous registry repository and verified Linux platform digest; recheck source/image proofs and rebuild.",
+    },
+    COMPOSE_IMAGE_LOCK_INVALID: {
+        code: "COMPOSE_IMAGE_LOCK_INVALID",
+        description: "Unsafe image VOLUME target.",
+        suggestion: "Use the intended anonymous registry repository and verified Linux platform digest; recheck source/image proofs and rebuild.",
+    },
+    COMPOSE_IMAGE_PLATFORM_UNSUPPORTED: {
+        code: "COMPOSE_IMAGE_PLATFORM_UNSUPPORTED",
+        description: "The declared value has no Linux the declared value image.",
+        suggestion: "Use the intended anonymous registry repository and verified Linux platform digest; recheck source/image proofs and rebuild.",
+    },
+    COMPOSE_IMAGE_RESOLVE_FAILED: {
+        code: "COMPOSE_IMAGE_RESOLVE_FAILED",
+        description: "Registry mirror must be an HTTPS origin.",
+        suggestion: "Use the intended anonymous registry repository and verified Linux platform digest; recheck source/image proofs and rebuild.",
+    },
+    COMPOSE_INPUT_CHANGED: {
+        code: "COMPOSE_INPUT_CHANGED",
+        description: "Compose input bytes changed after planning.",
+        suggestion: "Use bounded regular project-local files without symlink or remote dependencies, then rebuild from unchanged bytes.",
+    },
+    COMPOSE_LEGACY_MANIFEST_REMOVED: {
+        code: "COMPOSE_LEGACY_MANIFEST_REMOVED",
+        description: "Compose requires a schema-2 dsm-package.yaml declaration.",
+        suggestion: "Run init -t compose and declare differences in schema-2 dsm-package.yaml while retaining upstream bytes.",
+    },
+    COMPOSE_LOCK_INVALID: {
+        code: "COMPOSE_LOCK_INVALID",
+        description: "Private storage inventory is invalid.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_MODEL_INVALID: {
+        code: "COMPOSE_MODEL_INVALID",
+        description: "The declared value.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_NETWORK_UNSUPPORTED: {
+        code: "COMPOSE_NETWORK_UNSUPPORTED",
+        description: "Network the declared value must be a managed bridge without custom driver/IPAM options.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_OIDC_TOPOLOGY_UNSUPPORTED: {
+        code: "COMPOSE_OIDC_TOPOLOGY_UNSUPPORTED",
+        description: "Host service the declared value requires oidc Web ingress and a verified address_env.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_PACKAGE_INVALID: {
+        code: "COMPOSE_PACKAGE_INVALID",
+        description: "Package must be 2-64 alphanumerics starting with a letter.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_PRIVILEGE_UNSUPPORTED: {
+        code: "COMPOSE_PRIVILEGE_UNSUPPORTED",
+        description: "Container root capability the declared value is not supported.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_ROOT_FORBIDDEN: {
+        code: "COMPOSE_ROOT_FORBIDDEN",
+        description: "Prepare must run as the package account.",
+        suggestion: "Use the package identity; container-root requires explicit reason, bridge and no host bind. Never elevate the App on the host.",
+    },
+    COMPOSE_ROOT_HOST_MOUNT_FORBIDDEN: {
+        code: "COMPOSE_ROOT_HOST_MOUNT_FORBIDDEN",
+        description: "Container-root service the declared value cannot bind host files or Shares.",
+        suggestion: "Use the package identity; container-root requires explicit reason, bridge and no host bind. Never elevate the App on the host.",
+    },
+    COMPOSE_ROOT_OPT_IN_INVALID: {
+        code: "COMPOSE_ROOT_OPT_IN_INVALID",
+        description: "Container root needs a reason and bridge networking.",
+        suggestion: "Use the package identity; container-root requires explicit reason, bridge and no host bind. Never elevate the App on the host.",
+    },
+    COMPOSE_RUN_AS_INVALID: {
+        code: "COMPOSE_RUN_AS_INVALID",
+        description: "Service the declared value run_as must be package or container-root.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_SCALE_UNSUPPORTED: {
+        code: "COMPOSE_SCALE_UNSUPPORTED",
+        description: "The declared value deploy/replicas need an explicit local runtime contract.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_SERVICE_UNKNOWN: {
+        code: "COMPOSE_SERVICE_UNKNOWN",
+        description: "Services.the declared value is not active.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_SHARE_INVALID: {
+        code: "COMPOSE_SHARE_INVALID",
+        description: "Shares.the declared value needs admin selection, ro/rw and fixed mounts.",
+        suggestion: "Keep the project disabled until an official protected mount/project adapter is verified; never use a destination grant or host root workaround.",
+    },
+    COMPOSE_SHARE_NEEDS_APPROVAL: {
+        code: "COMPOSE_SHARE_NEEDS_APPROVAL",
+        description: "Declare capabilities.composeMounts: true; user destination grants cannot authorize package mounts.",
+        suggestion: "Keep the project disabled until an official protected mount/project adapter is verified; never use a destination grant or host root workaround.",
+    },
+    COMPOSE_SOURCE_UNSAFE: {
+        code: "COMPOSE_SOURCE_UNSAFE",
+        description: "Files must contain 1-32 local Compose files.",
+        suggestion: "Use bounded regular project-local files without symlink or remote dependencies, then rebuild from unchanged bytes.",
+    },
+    COMPOSE_STORAGE_INVALID: {
+        code: "COMPOSE_STORAGE_INVALID",
+        description: "Data.the declared value needs an active service, target, storage: package and safe path.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_STORAGE_NOT_READY: {
+        code: "COMPOSE_STORAGE_NOT_READY",
+        description: "Invalid package var path.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_STORAGE_UNMAPPED: {
+        code: "COMPOSE_STORAGE_UNMAPPED",
+        description: "The declared value:the declared value needs package data or an approved Share mapping.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_VOLUME_DRIVER_UNSUPPORTED: {
+        code: "COMPOSE_VOLUME_DRIVER_UNSUPPORTED",
+        description: "Reserved image volume namespace collision.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    COMPOSE_WEB_INVALID: {
+        code: "COMPOSE_WEB_INVALID",
+        description: "Compose web ingress is invalid.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    SDK_COMPOSE_BUILD_FAILED: {
+        code: "SDK_COMPOSE_BUILD_FAILED",
+        description: "The trusted SDK Compose tool could not be compiled.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    SDK_COMPOSE_FAILED: {
+        code: "SDK_COMPOSE_FAILED",
+        description: "The SDK Compose tool could not return a valid plan.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+    SDK_COMPOSE_UNSUPPORTED: {
+        code: "SDK_COMPOSE_UNSUPPORTED",
+        description: "This SDK release does not contain the unified Compose planner.",
+        suggestion: "Correct the reported declaration in dsm-package.yaml; see the Compose support matrix.",
+    },
+};