@synopackageland/cli 0.7.3 → 0.9.0

package/dist/reproducible.js

@@ -0,0 +1,121 @@
+/**
+ * `build --verify-reproducible`: build once more from a clean state and compare
+ * the SPKs. Projects may declare the dependency files whose fingerprint decides
+ * when the check needs to run again; the last passing one is recorded.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { extractSpk, walkFiles } from "./build-spk/generator.js";
+import { invalid, readReproducible } from "./reproducible-config.js";
+import { CLI_VERSION } from "./cli-version.js";
+export { readReproducible, validateReproducible } from "./reproducible-config.js";
+export const FINGERPRINT_RECORD = "reproducible-fingerprint.json";
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+function insideProject(root, path) {
+    const rel = relative(realpathSync(root), realpathSync(path));
+    return rel !== ".." && !rel.startsWith("../") && !isAbsolute(rel);
+}
+/** SHA-256 of each declared input plus the CLI version and `extra` pins, and one digest over all of them. */
+export function dependencyFingerprint(root, config, extra = {}) {
+    const digests = { synopkgland: CLI_VERSION, ...extra };
+    for (const path of config.inputs) {
+        const full = join(root, path);
+        if (!existsSync(full) || !lstatSync(full).isFile() || !insideProject(root, full))
+            invalid(`reproducible input ${path} is not a regular file in the project.`);
+        digests[path] = sha256(readFileSync(full));
+    }
+    const inputs = Object.fromEntries(Object.entries(digests).sort(([a], [b]) => a.localeCompare(b)));
+    return { fingerprint: sha256(JSON.stringify(inputs)), inputs };
+}
+function readRecord(path) {
+    try {
+        const record = JSON.parse(readFileSync(path, "utf8"));
+        return typeof record.fingerprint === "string" && record.inputs && Array.isArray(record.arches) ? record : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function cleanPaths(root, clean, arches) {
+    for (const pattern of clean) {
+        for (const path of new Set(arches.length ? arches.map((arch) => pattern.replaceAll("{arch}", arch)) : [pattern])) {
+            const full = resolve(root, path);
+            if (!existsSync(dirname(full)) || !insideProject(root, dirname(full)))
+                continue;
+            rmSync(full, { recursive: true, force: true });
+        }
+    }
+}
+function fileDigests(dir) {
+    return new Map(walkFiles(dir).map((file) => [file, sha256(readFileSync(join(dir, file)))]));
+}
+async function compareSpks(first, second) {
+    const digests = [sha256(readFileSync(first)), sha256(readFileSync(second))];
+    const result = { output: first, identical: digests[0] === digests[1], sha256: digests, payload: [], metadata: [] };
+    if (result.identical)
+        return result;
+    const work = mkdtempSync(join(tmpdir(), "synopkgland-compare-"));
+    try {
+        const [a, b] = [join(work, "1"), join(work, "2")];
+        await extractSpk(first, a);
+        await extractSpk(second, b);
+        const [left, right] = [fileDigests(a), fileDigests(b)];
+        for (const file of [...new Set([...left.keys(), ...right.keys()])].sort()) {
+            if (left.get(file) === right.get(file) || file === "package.tgz")
+                continue;
+            if (file.startsWith("package/"))
+                result.payload.push(file.slice("package/".length));
+            else
+                result.metadata.push(file);
+        }
+        return result;
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
+/**
+ * Builds the project again with `rebuild` into a temporary folder, after removing
+ * the declared `clean` paths and with an empty GOCACHE, and compares each SPK with
+ * `outputs`, the SPKs of this build. With declared inputs, mode `changed` skips
+ * while the fingerprint and architectures match the last passing record, and a
+ * passing check updates that record.
+ */
+export async function checkReproducible(options) {
+    const { root, outputs, arches } = options;
+    const config = readReproducible(options.manifestPath);
+    const recordPath = join(root, FINGERPRINT_RECORD);
+    const current = config.inputs.length ? dependencyFingerprint(root, config, options.extraInputs) : undefined;
+    const recorded = current && readRecord(recordPath);
+    const changed = current && Object.keys({ ...current.inputs, ...recorded?.inputs }).filter((key) => current.inputs[key] !== recorded?.inputs[key]).sort();
+    if (current && options.mode === "changed" && recorded?.fingerprint === current.fingerprint && arches.every((arch) => recorded.arches.includes(arch))) {
+        return { skipped: true, identical: true, fingerprint: current.fingerprint, changed, results: [] };
+    }
+    cleanPaths(root, config.clean, arches);
+    const outDir = mkdtempSync(join(tmpdir(), "synopkgland-reproducible-"));
+    const gocache = mkdtempSync(join(tmpdir(), "synopkgland-gocache-"));
+    const saved = process.env.GOCACHE;
+    process.env.GOCACHE = gocache;
+    try {
+        const second = await options.rebuild(outDir);
+        const results = [];
+        for (const [index, output] of outputs.entries())
+            results.push(await compareSpks(output, second[index]));
+        const identical = results.length === outputs.length && results.every((result) => result.identical);
+        if (current && identical) {
+            const known = recorded?.fingerprint === current.fingerprint ? recorded.arches : [];
+            writeFileSync(recordPath, `${JSON.stringify({ ...current, arches: [...new Set([...known, ...arches])].sort() }, null, 2)}\n`);
+        }
+        return { skipped: false, identical, ...(current ? { fingerprint: current.fingerprint, changed } : {}), results };
+    }
+    finally {
+        if (saved === undefined)
+            delete process.env.GOCACHE;
+        else
+            process.env.GOCACHE = saved;
+        for (const dir of [outDir, gocache])
+            rmSync(dir, { recursive: true, force: true });
+    }
+}

package/dist/runtime/delegate-contract.d.ts

@@ -37,9 +37,22 @@ export interface MoveFromStaging {
     delegation_id: string;
     job_id: string;
     staging: string;
+    /**
+     * File name, or folders below the destination and a file name, for example
+     * `Album/CD1/01.flac`. Missing folders are created as the user, at most
+     * `DELEGATE_LIMITS.maxDestinationFolders` deep and `maxDestinationBytes` long.
+     */
     name: string;
     size: number;
+    /**
+     * When the name is taken: `fail` (default) refuses with `destination-exists`,
+     * `overwrite` atomically replaces a regular file the user can write, `rename`
+     * publishes `name (n).ext` (n up to 99) and the receipt reports that path.
+     */
+    conflict?: DelegateConflictPolicy;
 }
+export declare const DELEGATE_CONFLICT_POLICIES: readonly ["fail", "overwrite", "rename"];
+export type DelegateConflictPolicy = typeof DELEGATE_CONFLICT_POLICIES[number];
 export interface OperationRef {
     delegation_id: string;
     job_id: string;
@@ -76,4 +89,6 @@ export declare const DELEGATE_LIMITS: {
     readonly maxOperationBytes: number;
     readonly maxAuditBytes: number;
     readonly revalidateSeconds: 5;
+    readonly maxDestinationFolders: 16;
+    readonly maxDestinationBytes: 1024;
 };

package/dist/runtime/delegate-contract.js

@@ -7,6 +7,7 @@ export const DELEGATE_EXTENSION_OPERATIONS = [
 export const DELEGATE_OPERATION_STATES = [
     'queued', 'copying', 'committed', 'canceled', 'interrupted', 'uncertain',
 ];
+export const DELEGATE_CONFLICT_POLICIES = ['fail', 'overwrite', 'rename'];
 export const DELEGATE_ROUTES = {
     'delegate.example.export': 'authenticated',
     'delegate.destination': 'authenticated',
@@ -24,4 +25,5 @@ export const DELEGATE_LIMITS = {
     maxFileBytes: 16 * 1024 ** 3, maxQueued: 16, maxActive: 1,
     maxCopySeconds: 86400, maxOperationBytes: 10 * 1024 ** 2,
     maxAuditBytes: 50 * 1024 ** 2, revalidateSeconds: 5,
+    maxDestinationFolders: 16, maxDestinationBytes: 1024,
 };

package/dist/runtime/executor-build.d.ts

@@ -3,6 +3,7 @@ import type { CommandRunner } from '../standalone/build.js';
 import type { StandaloneManifest } from '../standalone/manifest.js';
 import { type ExecutorPolicy } from './executor-policy.js';
 import { type ExecutorPins, type ExecutorTask } from './executor-tasks.js';
+import { type ExecutorDigestTable } from './executor-source.js';
 export interface ExecutorArtifact extends ExecutorPins {
     binary: string;
     lifecycleBinary: string;
@@ -10,8 +11,20 @@ export interface ExecutorArtifact extends ExecutorPins {
     policyText: string;
     tasks: ExecutorTask[];
     implementation: 'executor';
+    /** The SDK version the executor was built from; inspect regenerates the tasks from it. */
+    sdk: string;
+    warnings: string[];
 }
-export declare function buildExecutor(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner): ExecutorArtifact | undefined;
+export interface ExecutorSourceOptions {
+    env?: NodeJS.ProcessEnv;
+    download?: (spec: string) => string;
+    digests?: ExecutorDigestTable;
+}
+/**
+ * Build the executor and lifecycle helper from the App's SDK version: a copy of
+ * the module directory, `go build .` and `./cmd/lifecycle` inside it.
+ */
+export declare function buildExecutor(m: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner, options?: ExecutorSourceOptions): Promise<ExecutorArtifact | undefined>;
 export declare function executorPlan(a: ExecutorArtifact): {
     package: string;
     executorDigest: string;
@@ -19,4 +32,5 @@ export declare function executorPlan(a: ExecutorArtifact): {
     policy: ExecutorPolicy;
     tasks: ExecutorTask[];
     implementation: "executor";
+    sdk: string;
 };

package/dist/runtime/executor-build.js

@@ -1,28 +1,51 @@
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { mkdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { templatesRoot } from '../template-paths.js';
 import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem } from '../build-spk/go-toolchain.js';
 import { StandaloneBuildError } from '../standalone/spk.js';
 import { checkCgiBinary } from '../standalone/binary.js';
 import { executorPolicy, executorPolicyText, sha256 } from './executor-policy.js';
 import { executorTasks } from './executor-tasks.js';
-export function buildExecutor(m, arch, work, run) {
+import { copyModule, verifyExecutorDigests } from './executor-source.js';
+import { requiredSdk } from './sdk-source.js';
+/** CLI-owned build flags; the release digest table is computed the same way, so they must not change within an SDK minor. */
+const GO_BUILD = ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o'];
+function failure(error) {
+    const message = error.message;
+    const code = /^\[([A-Z0-9_]+)\]/.exec(message)?.[1] ?? 'EXECUTOR_BUILD_FAILED';
+    return new StandaloneBuildError(code, message.replace(/^\[[A-Z0-9_]+\] /, ''));
+}
+/**
+ * Build the executor and lifecycle helper from the App's SDK version: a copy of
+ * the module directory, `go build .` and `./cmd/lifecycle` inside it.
+ */
+export async function buildExecutor(m, arch, work, run, options = {}) {
     if (!m.capabilities.delegate && !m.capabilities.rootOps)
         return undefined;
+    let sdk;
+    try {
+        sdk = requiredSdk(m.backend.kind === 'go' ? m.backend.dir : m.root, options.env, options.download);
+    }
+    catch (error) {
+        throw failure(error);
+    }
     const dir = join(work, `executor-${arch}`);
     mkdirSync(dir);
-    const source = join(templatesRoot(), '_executor');
-    if (!existsSync(join(source, 'go.mod')))
-        throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', 'Executor sources are missing.');
+    const source = join(dir, 'source');
+    try {
+        copyModule(sdk.executorDir, source);
+    }
+    catch (error) {
+        throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Executor sources of SDK ${sdk.version} are missing: ${error.message}`);
+    }
     const binary = join(dir, 'executor');
-    const result = run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', binary, '.'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
+    const result = await run('go', [...GO_BUILD, binary, '.'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
     if (result.missing || result.status !== 0)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Executor build failed (${arch}). ${PINNED_GO_HINT}\n${result.stderr}`);
     const problem = checkCgiBinary(work, binary, arch);
     if (problem)
         throw new StandaloneBuildError(problem.code, problem.message);
     const lifecycleBinary = join(dir, 'lifecycle');
-    const lifecycleResult = run('go', ['build', '-trimpath', '-buildvcs=false', '-ldflags', '-s -w -buildid=', '-o', lifecycleBinary, './cmd/lifecycle'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
+    const lifecycleResult = await run('go', [...GO_BUILD, lifecycleBinary, './cmd/lifecycle'], { cwd: source, env: { ...process.env, ...pinnedGoBuildEnv(arch) } });
     if (lifecycleResult.missing || lifecycleResult.status !== 0)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', `Lifecycle helper build failed (${arch}). ${PINNED_GO_HINT}\n${lifecycleResult.stderr}`);
     const lifecycleProblem = checkCgiBinary(work, lifecycleBinary, arch);
@@ -31,10 +54,18 @@ export function buildExecutor(m, arch, work, run) {
     const toolchainProblem = pinnedGoProblem(binary) ?? pinnedGoProblem(lifecycleBinary);
     if (toolchainProblem)
         throw new StandaloneBuildError('EXECUTOR_BUILD_FAILED', toolchainProblem);
+    const executorDigest = sha256(readFileSync(binary));
+    let warnings;
+    try {
+        warnings = verifyExecutorDigests(sdk, arch, { executor: executorDigest, lifecycle: sha256(readFileSync(lifecycleBinary)) }, options.digests);
+    }
+    catch (error) {
+        throw failure(error);
+    }
     const policy = executorPolicy(m), policyText = executorPolicyText(policy);
-    const pins = { package: m.package, executorDigest: sha256(readFileSync(binary)), policyDigest: sha256(policyText) };
-    return { ...pins, binary, lifecycleBinary, policy, policyText, tasks: executorTasks(pins), implementation: 'executor' };
+    const pins = { package: m.package, executorDigest, policyDigest: sha256(policyText) };
+    return { ...pins, binary, lifecycleBinary, policy, policyText, tasks: executorTasks(pins, sdk.executorDir), implementation: 'executor', sdk: sdk.version, warnings };
 }
 export function executorPlan(a) {
-    return { package: a.package, executorDigest: a.executorDigest, policyDigest: a.policyDigest, policy: a.policy, tasks: a.tasks, implementation: a.implementation };
+    return { package: a.package, executorDigest: a.executorDigest, policyDigest: a.policyDigest, policy: a.policy, tasks: a.tasks, implementation: a.implementation, sdk: a.sdk };
 }

package/dist/runtime/executor-digests.json

@@ -0,0 +1,13 @@
+{
+    "0.9.0": {
+        "x86_64": "e009eb882e79e001fa8e6faf43e58525948c132f01f873562353284e5ac53b69",
+        "aarch64": "f9b84fb9b4a945abf28af6efe1bee0e11067dd0cc5ae26e53f8a949175d519a9",
+        "armv7": "05b670757c9a6cdea17596769ddd471c0563c044af75a564e1570caac8e37bd2",
+        "lifecycle": {
+            "x86_64": "819459580135e016184ad80c258350d57194d6134e8aa4cf1caf5237085b1004",
+            "aarch64": "5abcfc21403e84a0af15d972bcb819ac6fedfd9aaf5898ddc8c4bb06130f9f59",
+            "armv7": "b65a14f0fc77a1d3221c7dc6781eb66059aa200956b094d58a62bd1cad10f116"
+        },
+        "goToolchain": "go1.26.9"
+    }
+}

package/dist/runtime/executor-inspect.d.ts

@@ -8,6 +8,7 @@ export interface ExecutorInspection {
     policyDigest: string;
     policy: ExecutorPolicy;
     implementation: string;
+    sdk: string;
     tasks: Array<ExecutorTask & {
         state: 'unknown' | 'ready' | 'needs-admin-approval' | 'blocked';
     }>;

package/dist/runtime/executor-inspect.js

@@ -3,6 +3,7 @@ import { join } from 'node:path';
 import { validExecutorPolicy, sha256 } from './executor-policy.js';
 import { parseDocument } from 'yaml';
 import { executorTasks } from './executor-tasks.js';
+import { sdkSource } from './sdk-source.js';
 import { familyOfArchToken } from '../build-spk/dsm-arch.js';
 import { ELF_MACHINE } from '../standalone/binary.js';
 /** INFO key that anchors the executor digest; Package Center writes INFO as root. */
@@ -27,10 +28,12 @@ export function inspectExecutor(dir, pkg, arch) {
                 throw new Error('Root script digest mismatch.');
         }
         const executorDigest = sha256(binary), policyDigest = sha256(text);
-        const tasks = executorTasks({ package: pkg, policyDigest });
+        if (typeof plan.sdk !== 'string' || !/^\d+\.\d+\.\d+$/.test(plan.sdk))
+            throw new Error('Executor setup does not name its SDK version.');
+        const tasks = executorTasks({ package: pkg, policyDigest }, sdkSource(plan.sdk).executorDir);
         if (plan.package !== pkg || plan.executorDigest !== executorDigest || plan.policyDigest !== policyDigest || JSON.stringify(plan.policy) !== JSON.stringify(policy) || JSON.stringify(plan.tasks) !== JSON.stringify(tasks) || plan.implementation !== 'executor')
             throw new Error('Executor pins or task binding mismatch.');
-        return { executor: { executorDigest, policyDigest, policy, implementation: plan.implementation, tasks: tasks.map(task => ({ ...task, state: 'unknown' })) }, findings: [] };
+        return { executor: { executorDigest, policyDigest, policy, implementation: plan.implementation, sdk: plan.sdk, tasks: tasks.map(task => ({ ...task, state: 'unknown' })) }, findings: [] };
     }
     catch (e) {
         return { findings: ['Executor inventory invalid: ' + e.message] };

package/dist/runtime/executor-policy.d.ts

@@ -1,6 +1,8 @@
 import type { RootOp } from '../standalone/root-ops.js';
 import type { EntryMode } from '../standalone/manifest.js';
-export declare const FILE_OPERATIONS: readonly ["files.list", "files.info", "files.createFolder", "files.checkPermission", "files.write"];
+export declare const FILE_OPERATIONS: readonly ["files.list", "files.info", "files.createFolder", "files.checkPermission", "files.write", "files.read", "files.rename", "files.copy", "files.move", "files.delete"];
+/** Started File Station tasks are followed with these; they are implied, never declared. */
+export declare const FILE_TASK_OPERATIONS: readonly ["files.taskStatus", "files.taskCancel"];
 export interface DelegateCapability {
     operations: string[];
     scope: string;

package/dist/runtime/executor-policy.js

@@ -1,6 +1,9 @@
 import { createHash } from 'node:crypto';
 import { MOVE_FROM_STAGING, DELEGATE_EXTENSION_OPERATIONS } from './delegate-contract.js';
-export const FILE_OPERATIONS = ['files.list', 'files.info', 'files.createFolder', 'files.checkPermission', 'files.write'];
+export const FILE_OPERATIONS = ['files.list', 'files.info', 'files.createFolder', 'files.checkPermission', 'files.write', 'files.read', 'files.rename', 'files.copy', 'files.move', 'files.delete'];
+/** Started File Station tasks are followed with these; they are implied, never declared. */
+export const FILE_TASK_OPERATIONS = ['files.taskStatus', 'files.taskCancel'];
+const TASK_STARTING_OPERATIONS = ['files.copy', 'files.move', 'files.delete'];
 export function validDelegate(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
         return false;
@@ -24,6 +27,8 @@ export function executorPolicy(m) {
     const operations = ['status'];
     if (m.capabilities.delegate) {
         operations.push('delegate.create', 'delegate.list', 'delegate.revoke', ...m.capabilities.delegate.operations);
+        if (m.capabilities.delegate.operations.some(op => TASK_STARTING_OPERATIONS.includes(op)))
+            operations.push(...FILE_TASK_OPERATIONS);
         if (m.capabilities.delegate.lifetime === 'until-revoked')
             operations.push(...DELEGATE_EXTENSION_OPERATIONS);
     }
@@ -50,7 +55,7 @@ export function validExecutorPolicy(value, pkg) {
         || !p.root || typeof p.root !== 'object' || Array.isArray(p.root))
         return false;
     const base = ['status', 'root.run', 'delegate.create', 'delegate.list', 'delegate.revoke'];
-    if (p.operations.some(op => ![...base, ...FILE_OPERATIONS, ...DELEGATE_EXTENSION_OPERATIONS].includes(op)))
+    if (p.operations.some(op => ![...base, ...FILE_OPERATIONS, ...FILE_TASK_OPERATIONS, ...DELEGATE_EXTENSION_OPERATIONS].includes(op)))
         return false;
     const delegated = p.operations.some(op => op.startsWith('files.') || op.startsWith('delegate.'));
     if (!delegated)

package/dist/runtime/executor-source.d.ts

@@ -0,0 +1,21 @@
+import type { NativeArchFamily } from '../build-spk/dsm-arch.js';
+import type { SdkSource } from './sdk-source.js';
+type ArchDigests = Record<NativeArchFamily, string>;
+/** Released SDK versions: the sha256 of the executor and lifecycle helper built from them, per architecture. */
+export type ExecutorDigestTable = Record<string, ArchDigests & {
+    lifecycle: ArchDigests;
+    goToolchain: string;
+}>;
+export declare const SHIPPED_EXECUTOR_DIGESTS: ExecutorDigestTable;
+/** Copy a module directory (the module cache is read-only) so the build owns a writable tree. */
+export declare function copyModule(source: string, target: string): void;
+/**
+ * A released SDK's executor is only shipped when its bytes equal the digest
+ * table; a local SDK checkout (SYNOPKGLAND_SDK_DIR) is built unverified.
+ * Returns the warnings to show.
+ */
+export declare function verifyExecutorDigests(sdk: SdkSource, arch: NativeArchFamily, built: {
+    executor: string;
+    lifecycle: string;
+}, table?: ExecutorDigestTable): string[];
+export {};

package/dist/runtime/executor-source.js

@@ -0,0 +1,35 @@
+import { chmodSync, cpSync, lstatSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import EXECUTOR_DIGESTS from './executor-digests.json' with { type: 'json' };
+export const SHIPPED_EXECUTOR_DIGESTS = EXECUTOR_DIGESTS;
+/** Copy a module directory (the module cache is read-only) so the build owns a writable tree. */
+export function copyModule(source, target) {
+    cpSync(source, target, { recursive: true });
+    const writable = (path) => {
+        const stat = lstatSync(path);
+        if (stat.isSymbolicLink())
+            return;
+        chmodSync(path, stat.mode | 0o200);
+        if (stat.isDirectory())
+            for (const name of readdirSync(path))
+                writable(join(path, name));
+    };
+    writable(target);
+}
+/**
+ * A released SDK's executor is only shipped when its bytes equal the digest
+ * table; a local SDK checkout (SYNOPKGLAND_SDK_DIR) is built unverified.
+ * Returns the warnings to show.
+ */
+export function verifyExecutorDigests(sdk, arch, built, table = SHIPPED_EXECUTOR_DIGESTS) {
+    if (sdk.local)
+        return [`[EXECUTOR_DIGEST_UNVERIFIED] executor built from the local SDK checkout SYNOPKGLAND_SDK_DIR (${arch}, sha256 ${built.executor}); the digest table was not checked. Do not publish this SPK.`];
+    const expected = table[sdk.version];
+    if (!expected)
+        throw new Error(`[EXECUTOR_DIGEST_MISMATCH] This CLI has no recorded executor digest for SDK ${sdk.version}; it knows ${Object.keys(table).join(', ') || 'no released SDK'}.`);
+    if (expected[arch] !== built.executor)
+        throw new Error(`[EXECUTOR_DIGEST_MISMATCH] SDK ${sdk.version} executor (${arch}) built to sha256 ${built.executor}, not the released ${expected[arch]}.`);
+    if (expected.lifecycle[arch] !== built.lifecycle)
+        throw new Error(`[EXECUTOR_DIGEST_MISMATCH] SDK ${sdk.version} lifecycle helper (${arch}) built to sha256 ${built.lifecycle}, not the released ${expected.lifecycle[arch]}.`);
+    return [];
+}

package/dist/runtime/executor-tasks.d.ts

@@ -11,7 +11,10 @@ export interface ExecutorTask {
     script: string;
 }
 export declare function validateTaskScript(script: string, limit: number): string;
-/** Tasks pin only the approved policy; the SPK's root-owned INFO anchors executor bytes. */
-export declare function executorTasks(pins: Pick<ExecutorPins, 'package' | 'policyDigest'>): ExecutorTask[];
+/**
+ * Tasks pin only the approved policy; the SPK's root-owned INFO anchors executor bytes.
+ * The task scripts come from the SDK executor module the App builds with.
+ */
+export declare function executorTasks(pins: Pick<ExecutorPins, 'package' | 'policyDigest'>, executorDir: string): ExecutorTask[];
 export declare function bootDefinition(task: ExecutorTask): Record<string, unknown>;
 export declare function controlDefinition(task: ExecutorTask): Record<string, unknown>;

package/dist/runtime/executor-tasks.js

@@ -1,6 +1,5 @@
 import { readFileSync } from 'node:fs';
 import { join } from 'node:path';
-import { templatesRoot } from '../template-paths.js';
 export function validateTaskScript(script, limit) {
     if (script.includes('%'))
         throw new Error('[EXECUTOR_TASK_PERCENT] Task scripts must not contain percent characters.');
@@ -8,14 +7,17 @@ export function validateTaskScript(script, limit) {
         throw new Error('[EXECUTOR_TASK_LENGTH] Task script exceeds DSM byte limit.');
     return script;
 }
-/** Tasks pin only the approved policy; the SPK's root-owned INFO anchors executor bytes. */
-export function executorTasks(pins) {
+/**
+ * Tasks pin only the approved policy; the SPK's root-owned INFO anchors executor bytes.
+ * The task scripts come from the SDK executor module the App builds with.
+ */
+export function executorTasks(pins, executorDir) {
     if (!/^[A-Za-z][A-Za-z0-9]{1,63}$/.test(pins.package))
         throw new Error('[EXECUTOR_PACKAGE] Invalid package identity.');
     if (!/^[a-f0-9]{64}$/.test(pins.policyDigest))
         throw new Error('[EXECUTOR_DIGEST] Invalid sha256 pin.');
     return ['boot', 'control'].map(kind => {
-        const script = readFileSync(join(templatesRoot(), '_executor', 'internal', 'taskscript', `${kind}.sh`), 'utf8')
+        const script = readFileSync(join(executorDir, 'internal', 'taskscript', `${kind}.sh`), 'utf8')
             .replaceAll('@PACKAGE@', pins.package).replaceAll('@POLICY_DIGEST@', pins.policyDigest);
         return { kind, name: `${pins.package} executor ${kind}`, header: `#!/bin/sh\n# synopkgland executor ${kind}\n`, script: validateTaskScript(script, kind === 'boot' ? 1024 : 6000) };
     });

package/dist/runtime/sdk-source.d.ts

@@ -0,0 +1,31 @@
+export declare const SDK_PACKAGE = "@synopackageland/sdk";
+export declare const SDK_MODULE = "github.com/synopackageland/syno-pkg-land-sdk";
+export declare const EXECUTOR_MODULE = "github.com/synopackageland/syno-pkg-land-sdk/executor";
+/** Where one SDK version's Go client and executor sources are read from. */
+export interface SdkSource {
+    version: string;
+    goDir: string;
+    executorDir: string;
+    local: boolean;
+}
+/** The SDK version an App requires: `require github.com/synopackageland/syno-pkg-land-sdk vX.Y.Z` in backend/go.mod, the only version source. */
+export declare function sdkRequirement(backendDir: string): string | undefined;
+/** The App's own Go module path, the prefix of every `-X` that targets its packages. */
+export declare function goModulePath(backendDir: string): string | undefined;
+/**
+ * The module directories of one SDK version. SYNOPKGLAND_SDK_DIR names a
+ * local sdk checkout (development and gates only); otherwise both modules
+ * come from `go mod download` of exactly that version.
+ */
+export declare function sdkSource(version: string, env?: NodeJS.ProcessEnv, download?: (spec: string) => string): SdkSource;
+/** The module cache directory of module@version; the cache is read-only, so builds copy it first. */
+export declare function goModDownload(spec: string, env?: NodeJS.ProcessEnv): string;
+/** The SDK an App builds its executor with; delegate and rootOps cannot build without one. */
+export declare function requiredSdk(backendDir: string, env?: NodeJS.ProcessEnv, download?: (spec: string) => string): SdkSource;
+/**
+ * The SDK repositories are private: Go must fetch them with git, not from
+ * proxy.golang.org and sum.golang.org. Says which of the two is missing.
+ */
+export declare function privateSdkHint(env?: NodeJS.ProcessEnv): string;
+/** Whether a comma-separated GOPRIVATE-style glob list matches a module path or one of its prefixes, as go does. */
+export declare function goPrivateCovers(patterns: string, modulePath: string): boolean;

package/dist/runtime/sdk-source.js

@@ -0,0 +1,92 @@
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+export const SDK_PACKAGE = '@synopackageland/sdk';
+export const SDK_MODULE = 'github.com/synopackageland/syno-pkg-land-sdk';
+export const EXECUTOR_MODULE = `${SDK_MODULE}/executor`;
+/** The SDK version an App requires: `require github.com/synopackageland/syno-pkg-land-sdk vX.Y.Z` in backend/go.mod, the only version source. */
+export function sdkRequirement(backendDir) {
+    const module = SDK_MODULE.replaceAll('.', '\\.');
+    return new RegExp(`^\\s*(?:require\\s+)?${module}\\s+v(\\S+)`, 'm').exec(goMod(backendDir))?.[1];
+}
+/** The App's own Go module path, the prefix of every `-X` that targets its packages. */
+export function goModulePath(backendDir) {
+    return /^\s*module\s+(\S+)/m.exec(goMod(backendDir))?.[1];
+}
+/** backend/go.mod without comments; empty when the backend has none. */
+function goMod(backendDir) {
+    try {
+        return readFileSync(join(backendDir, 'go.mod'), 'utf8').replace(/\/\/.*$/gm, '');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * The module directories of one SDK version. SYNOPKGLAND_SDK_DIR names a
+ * local sdk checkout (development and gates only); otherwise both modules
+ * come from `go mod download` of exactly that version.
+ */
+export function sdkSource(version, env = process.env, download = (spec) => goModDownload(spec, env)) {
+    const dir = env.SYNOPKGLAND_SDK_DIR;
+    if (dir)
+        return { version, goDir: dir, executorDir: join(dir, 'executor'), local: true };
+    return { version, goDir: download(`${SDK_MODULE}@v${version}`), executorDir: download(`${EXECUTOR_MODULE}@v${version}`), local: false };
+}
+const downloaded = new Map();
+/** The module cache directory of module@version; the cache is read-only, so builds copy it first. */
+export function goModDownload(spec, env = process.env) {
+    const key = [spec, env.GOPROXY, env.GOMODCACHE, env.GOPATH].join('\0');
+    const cached = downloaded.get(key);
+    if (cached)
+        return cached;
+    const result = spawnSync('go', ['mod', 'download', '-json', spec], { cwd: tmpdir(), env: { ...env, GOWORK: 'off', GOFLAGS: '' }, encoding: 'utf8' });
+    let info = {};
+    try {
+        info = JSON.parse(result.stdout);
+    }
+    catch { /* reported below */ }
+    if (result.error || result.status !== 0 || !info.Dir) {
+        throw new Error(`[SDK_DOWNLOAD_FAILED] go mod download ${spec} failed: ${info.Error ?? result.stderr ?? result.error?.message}${privateSdkHint(env)}`);
+    }
+    downloaded.set(key, info.Dir);
+    return info.Dir;
+}
+/** The SDK an App builds its executor with; delegate and rootOps cannot build without one. */
+export function requiredSdk(backendDir, env = process.env, download) {
+    const version = sdkRequirement(backendDir);
+    if (!version)
+        throw new Error(`[SDK_REQUIRED] capabilities.delegate and rootOps need the SDK: add \`require ${SDK_MODULE} v<version>\` to backend/go.mod.`);
+    return download ? sdkSource(version, env, download) : sdkSource(version, env);
+}
+/**
+ * The SDK repositories are private: Go must fetch them with git, not from
+ * proxy.golang.org and sum.golang.org. Says which of the two is missing.
+ */
+export function privateSdkHint(env = process.env) {
+    const result = spawnSync('go', ['env', '-json', 'GONOPROXY', 'GONOSUMDB'], { cwd: tmpdir(), env: { ...env, GOFLAGS: '' }, encoding: 'utf8' });
+    let goEnv = {};
+    try {
+        goEnv = JSON.parse(result.stdout);
+    }
+    catch { /* treated as not covered */ }
+    if (goPrivateCovers(goEnv.GONOPROXY ?? '', SDK_MODULE) && goPrivateCovers(goEnv.GONOSUMDB ?? '', SDK_MODULE)) {
+        return ` GOPRIVATE covers the SDK, so Go fetches it with git: check that \`git ls-remote https://${SDK_MODULE}\` works with your git credential.`;
+    }
+    return ' The SDK repositories are private, and Go looks up modules outside GOPRIVATE on proxy.golang.org and sum.golang.org.'
+        + ' Set GOPRIVATE=github.com/synopackageland/* (for example `go env -w GOPRIVATE=github.com/synopackageland/*`) and give git a credential for github.com.';
+}
+/** Whether a comma-separated GOPRIVATE-style glob list matches a module path or one of its prefixes, as go does. */
+export function goPrivateCovers(patterns, modulePath) {
+    const elements = modulePath.split('/');
+    return patterns.split(',').map(glob => glob.trim().replace(/\/+$/, '')).filter(Boolean).some(glob => {
+        const prefix = elements.slice(0, glob.split('/').length).join('/');
+        return globRegExp(glob).test(prefix);
+    });
+}
+/** path.Match syntax: `*` and `?` never cross a slash. */
+function globRegExp(glob) {
+    const body = glob.replace(/[.+^${}()|\\]/g, '\\$&').replaceAll('*', '[^/]*').replaceAll('?', '[^/]');
+    return new RegExp(`^${body}$`);
+}

package/dist/spk/check-info.d.ts

@@ -0,0 +1,5 @@
+import type { Findings } from "./findings.js";
+/** INFO lines are `key="value"` (or unquoted `key=value`); quotes may escape `\"` and `\\`. */
+export declare function parseInfo(text: string, findings?: Findings): Map<string, string>;
+/** Checks INFO fields; `payloadPath` is package.tgz on disk, for the checksum. */
+export declare function checkInfoFields(fields: Map<string, string>, payloadPath: string | undefined, findings: Findings): void;