@synopackageland/cli 0.38.0 → 0.40.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 0.40.0 (2026-10-29)
+
+- `daemon.backend: true` runs the App's own native backend
+  (`ui/cgi/api.cgi`) as the package daemon with `args`, instead of a separate
+  `exec`. The binary keeps the route audit and build digests of the CGI
+  build. `targets` becomes optional; with `daemon.node` the CLI writes its
+  Node launcher and passes `SYNOPKGLAND_NODE` and
+  `SYNOPKGLAND_DAEMON_PAYLOAD` so the backend can start Node children itself.
+  It needs an SDK whose daemon controller supports backend daemons
+  (`STANDALONE_DAEMON_BUILD_FAILED` otherwise) and cannot be combined with
+  `identity_gateway`. `inspect` verifies the `backend` config and the
+  backend's mode.
+- New skill reference `daemon-mode`: when a resident backend daemon pays off
+  and when to stay with the CGI, with a decision table, the factors to
+  measure and decision steps.
+- The route audit accepts `api.ServeIngress` (SDK) like `cgi.Serve`: called
+  directly, and never with a private or raw HTTP handler.
+- Pin templates 0.35.0 and its SDK/App 0.37.0 defaults. `daemon.backend` and
+  `api.ServeIngress` need SDK/App 0.37.0.
+
+## 0.39.0 (2026-10-29)
+
+- Add schema-2 `dependencies.packages` for DSM package dependencies independent
+  of the App language or daemon interpreter. Each entry has a validated `name`
+  and optional quoted numeric `min_version`. Build merges, sorts and
+  deduplicates these with Node backend and `daemon.node` requirements into
+  one INFO `install_dep_packages` field; distinct specified minimum versions
+  for one package fail validation. Daemon executable, arguments, environment
+  and supervision are unchanged. Native layouts and Compose are supported.
+  `check --json` reports normalized dependencies, build metadata records them,
+  and `inspect` verifies normalization, INFO agreement and inferred Node
+  requirements. Document `/var/packages/<name>/target`, the manifest field
+  and the difference from `daemon.node` in the manifest/daemon guides and App
+  skill. Add parser, merge/conflict, compiled CLI, artifact and mutation tests.
+- Make the native gateway listener-wait test assert both listeners close,
+  without assuming a scheduling-dependent minimum number of polls.
+
 ## 0.38.0 (2026-10-29)
 
 - Audit direct `ipc.StartPeerUnix` calls and reject constructor aliases.

package/README.md

@@ -49,6 +49,10 @@ See the [upstream scaffold and release checklist](skills/reference/upstream-fork
 Existing native products with their own payload layout use `backend: {kind: native}` in
 `dsm-package.yaml`.
 
+Declare language-independent DSM installation requirements with
+[`dependencies.packages`](docs/manifest.md). They merge with inferred Node
+requirements without changing the App's executable or runtime.
+
 A backend in Python, Node or Rust uses `backend: {runtime: python|node|rust, ...}`: the CGI is
 the SDK's Go runtime, which checks the DSM session and `permissions.json` and starts the App
 from `target/app` as the package account for each request (see `skills/reference/create.md`).
@@ -74,7 +78,7 @@ alongside npm lockfiles. Do not disable checksum verification for public SDK
 packages. Private mirrors can use explicitly configured Go authentication and
 checksum settings; a failed fetch reports `SDK_DOWNLOAD_FAILED`.
 
-CLI 0.38.0 uses templates ~0.34.0, whose default SDK pin is 0.36.0. Compose import and SDK defaults
+CLI 0.40.0 uses templates ~0.35.0, whose default SDK pin is 0.37.0. Compose import and SDK defaults
 read the SDK pin from the installed templates; explicit App SDK declarations take precedence.
 Every App method must be declared in the permissions table. Dynamic names and
 custom HTTP dispatchers are rejected. With SDK 0.33.0, use fixed
@@ -85,8 +89,8 @@ unimported development commands are excluded. Use
 authentication. See [App entry and registration](docs/app-entry.md).
 
 `init` and `add` read their templates from the locally installed
-`@synopackageland/templates`. CLI 0.38.0 depends on `~0.34.0`: npm installation or
-update can select the latest templates patch in the 0.34 minor line. Templates
+`@synopackageland/templates`. CLI 0.40.0 depends on `~0.35.0`: npm installation or
+update can select the latest templates patch in the 0.35 minor line. Templates
 patches need only a templates release; update the npm installation to receive them.
 The CLI never fetches templates at runtime, so offline use works after installation;
 commit a lockfile and use `npm ci` to reproduce a chosen dependency tree.

package/assets/go/route-audit/main.go

@@ -600,6 +600,10 @@ func main() {
 					if !direct[selector] {
 						problem(selector.Pos(), "route constructor aliases cannot be audited; register methods directly")
 					}
+				case "ServeIngress":
+					if !direct[selector] {
+						problem(selector.Pos(), "ingress constructor aliases cannot be audited")
+					}
 				}
 			}
 			if module == "net/http" {
@@ -659,6 +663,10 @@ func main() {
 			if module == "net/http/cgi" && selector.Sel.Name == "Serve" && len(call.Args) > 0 && reusesBoundary(call.Args[0], src, sources, safe, map[ast.Node]bool{}) {
 				problem(call.Pos(), "private or raw HTTP handler reused outside its SDK boundary")
 			}
+			// The daemon ingress serves the same browser requests as cgi.Serve.
+			if module == sdkModule+"/api" && selector.Sel.Name == "ServeIngress" && len(call.Args) > 1 && reusesBoundary(call.Args[1], src, sources, safe, map[ast.Node]bool{}) {
+				problem(call.Pos(), "private or raw HTTP handler reused outside its SDK boundary")
+			}
 			if module == "github.com/synopackageland/syno-pkg-land-sdk/dsm" && selector.Sel.Name == "NewEntryGate" {
 				out.EntryGate = true
 			}

package/dist/cli.js

@@ -405,6 +405,7 @@ async function runCliWithin(argv) {
             emit("check", {
                 package: loaded.manifest.package,
                 warnings: validation.warnings ?? [],
+                ...("dependencies" in loaded.manifest && loaded.manifest.dependencies ? { dependencies: loaded.manifest.dependencies } : {}),
                 ...("installSettings" in loaded.manifest && loaded.manifest.installSettings ? { installSettings: loaded.manifest.installSettings } : {}),
                 ...("hyperBackup" in loaded.manifest && loaded.manifest.hyperBackup ? { hyperBackup: backupRecord(loaded.manifest.hyperBackup) } : {}),
                 ...("identityGateway" in loaded.manifest && gatewayAdmissionReport(loaded.manifest.identityGateway, loaded.manifest.entry) ? { identityGateway: gatewayAdmissionReport(loaded.manifest.identityGateway, loaded.manifest.entry) } : {}),

package/dist/error-registry.js

@@ -283,6 +283,11 @@ export const ERROR_REGISTRY = {
             description: "dsm-package.yaml contains an unsupported field.",
             suggestion: "Remove the field; a Standalone Package does not accept custom lifecycle scripts or DSM conf.",
         },
+        STANDALONE_DEPENDENCIES_INVALID: {
+            code: "STANDALONE_DEPENDENCIES_INVALID",
+            description: "The DSM package dependencies are invalid or conflict with an inferred dependency.",
+            suggestion: "Use dependencies.packages entries with only name and optional quoted numeric min_version; use one identical minimum version per package, including daemon.node.",
+        },
         STANDALONE_SCHEMA_INVALID: {
             code: "STANDALONE_SCHEMA_INVALID",
             description: "The schema version in dsm-package.yaml is not supported.",

package/dist/skill.js

@@ -57,6 +57,11 @@ const SKILL_CATALOG = [
         file: "reference/backup.md",
         when: "Change or opt out of Hyper Backup application backup",
     },
+    {
+        id: "daemon-mode",
+        file: "reference/daemon-mode.md",
+        when: "Decide whether the backend should run as a resident daemon (daemon.backend)",
+    },
     { id: "deploy", file: "reference/deploy.md", when: "Deploy to a NAS" },
     {
         id: "diagnose",

package/dist/standalone/daemon.d.ts

@@ -7,8 +7,13 @@ import type { StandaloneError, StandaloneManifest } from "./manifest.js";
 export interface Daemon {
     /** Optional bounded recovery; omitted means off. SDK 0.26.0 or later. */
     restart?: DaemonRestart;
-    /** Fixed foreground executable relative to daemon/payload. */
+    /** Fixed foreground executable relative to daemon/payload; empty for a backend daemon. */
     exec: string;
+    /**
+     * The App's own audited backend (ui/cgi/api.cgi) runs as the daemon with
+     * `args`; `node`, if set, is then only a runtime for the backend's children.
+     */
+    backend?: true;
     /** Architecture-specific project directories, copied without links. */
     targets: Partial<Record<NativeArchFamily, string>>;
     args: string[];
@@ -56,6 +61,10 @@ export declare function daemonConfig(manifest: StandaloneManifest): string;
  * launcher with its entry first, and ingress names the socket to listen on.
  */
 export declare function runnableDaemon(pkg: string, daemon: Daemon): Daemon;
+/** What a backend daemon learns about the Node runtime it may start children with. */
+export declare const backendNodeEnv: () => Record<string, string>;
+/** daemonctl runs ui/cgi/api.cgi (`"backend": true`) from SDK/App 0.37.0. */
+export declare function requireBackendDaemonSource(source: string, daemon: Daemon | undefined): void;
 export declare function buildDaemonControl(manifest: StandaloneManifest, arch: NativeArchFamily, work: string, run: CommandRunner): Promise<string | undefined>;
 export declare function copyDaemonPayload(manifest: StandaloneManifest, arch: NativeArchFamily, target: string, controller: string): void;
 /** Copies a bounded, link-free package-account payload tree. */

package/dist/standalone/daemon.js

@@ -1,6 +1,6 @@
 import { operationBudgetSeconds, runtimeBudgetSdkSupported } from "../runtime/runtime-budgets.js";
 import { goChildEnv } from "../runtime/go-env.js";
-import { chmodSync, existsSync, copyFileSync, lstatSync, mkdirSync, readdirSync, realpathSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, copyFileSync, lstatSync, mkdirSync, readdirSync, readFileSync, realpathSync, writeFileSync, } from "node:fs";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { PINNED_GO_HINT, pinnedGoBuildEnv, pinnedGoProblem, } from "../build-spk/go-toolchain.js";
 import { sdkSource, appSdkVersion } from "../runtime/sdk-source.js";
@@ -35,6 +35,7 @@ exec "$node" "$@"
 }
 const fields = new Set([
     "exec",
+    "backend",
     "targets",
     "args",
     "env",
@@ -69,19 +70,25 @@ export function readDaemon(value, root, arches, fail) {
     const invalid = () => {
         fail({
             code: "STANDALONE_DAEMON_INVALID",
-            message: "daemon accepts only fixed exec, targets, args, env and timeouts; paths must be inside the project, and the environment does not accept loader/shell/system variables.",
+            message: "daemon accepts only fixed exec (or backend: true), targets, args, env and timeouts; paths must be inside the project, and the environment does not accept loader/shell/system variables.",
         });
         return undefined;
     };
     if (!record(value) || Object.keys(value).some((k) => !fields.has(k)))
         return invalid();
-    if (!(value.node === undefined ? relativeExec(value.exec) : relativeEntry(value.exec)))
+    const backend = value.backend === true;
+    if (value.backend !== undefined && !backend)
         return invalid();
-    if (!record(value.targets) ||
-        Object.keys(value.targets).length !== arches.length)
+    if (backend ? value.exec !== undefined : !(value.node === undefined ? relativeExec(value.exec) : relativeEntry(value.exec)))
+        return invalid();
+    // A backend daemon needs a payload only for its children's files.
+    const payload = !backend || value.targets !== undefined;
+    if (payload &&
+        (!record(value.targets) ||
+            Object.keys(value.targets).length !== arches.length))
         return invalid();
     const targets = {};
-    for (const arch of arches) {
+    for (const arch of payload ? arches : []) {
         const path = value.targets[arch];
         if (typeof path !== "string" ||
             !path.trim() ||
@@ -123,8 +130,11 @@ export function readDaemon(value, root, arches, fail) {
         return undefined;
     if (ingress && Object.keys(env).some((key) => key in ingressEnv("", ingress)))
         return invalid();
+    if (backend && node && Object.keys(env).some((key) => key in backendNodeEnv()))
+        return invalid();
     return {
-        exec: value.exec,
+        exec: backend ? "" : value.exec,
+        ...(backend ? { backend: true } : {}),
         targets,
         args,
         ...(uninstall ? { uninstall_args: uninstall } : {}),
@@ -171,7 +181,7 @@ export function daemonConfig(manifest) {
             : runnableDaemon(manifest.package, manifest.daemon);
     return (JSON.stringify({
         package: manifest.package,
-        exec,
+        ...(!manifest.compose && manifest.daemon?.backend ? { backend: true } : { exec }),
         args,
         ...(uninstall_args ? { uninstall_args } : {}),
         ...(restart ? { restart } : {}),
@@ -187,8 +197,12 @@ export function daemonConfig(manifest) {
  * launcher with its entry first, and ingress names the socket to listen on.
  */
 export function runnableDaemon(pkg, daemon) {
-    const entry = daemon.node && [`\${SYNOPKG_PKGDEST}/daemon/payload/${daemon.exec}`];
-    const env = daemon.ingress ? { ...daemon.env, ...ingressEnv(pkg, daemon.ingress) } : daemon.env;
+    const entry = daemon.node && !daemon.backend && [`\${SYNOPKG_PKGDEST}/daemon/payload/${daemon.exec}`];
+    const env = {
+        ...daemon.env,
+        ...(daemon.ingress ? ingressEnv(pkg, daemon.ingress) : {}),
+        ...(daemon.backend && daemon.node ? backendNodeEnv() : {}),
+    };
     return {
         ...daemon,
         ...(entry ? { exec: NODE_LAUNCHER, args: [...entry, ...daemon.args] } : {}),
@@ -196,6 +210,19 @@ export function runnableDaemon(pkg, daemon) {
         env: Object.fromEntries(Object.keys(env).sort().map((key) => [key, env[key]])),
     };
 }
+/** What a backend daemon learns about the Node runtime it may start children with. */
+export const backendNodeEnv = () => ({
+    SYNOPKGLAND_DAEMON_PAYLOAD: "${SYNOPKG_PKGDEST}/daemon/payload",
+    SYNOPKGLAND_NODE: `\${SYNOPKG_PKGDEST}/daemon/payload/${NODE_LAUNCHER}`,
+});
+/** daemonctl runs ui/cgi/api.cgi (`"backend": true`) from SDK/App 0.37.0. */
+export function requireBackendDaemonSource(source, daemon) {
+    if (!daemon?.backend)
+        return;
+    const main = join(source, "daemonctl/main.go");
+    if (!existsSync(main) || !readFileSync(main, "utf8").includes("backendExecutable"))
+        throw new StandaloneBuildError("STANDALONE_DAEMON_BUILD_FAILED", "daemon.backend needs an SDK whose daemon controller can run the backend (SDK/App 0.37.0 or later); upgrade the App SDK.");
+}
 export async function buildDaemonControl(manifest, arch, work, run) {
     if (!manifest.daemon && !(manifest.compose && manifest.identityGateway))
         return undefined;
@@ -203,6 +230,7 @@ export async function buildDaemonControl(manifest, arch, work, run) {
     const sdk = daemonSdkVersion(manifest);
     const source = runtimeBudgetSource(sdkSource(sdk).goDir, manifest);
     requireDaemonRestartSource(source, sdk, manifest.daemon?.restart);
+    requireBackendDaemonSource(source, manifest.daemon);
     const result = await run("go", [
         "build",
         "-trimpath",
@@ -233,16 +261,16 @@ export function copyDaemonPayload(manifest, arch, target, controller) {
         copyPayloadTree(manifest.root, source, join(target, "payload"));
     else
         mkdirSync(join(target, "payload"), { recursive: true });
-    if (!manifest.compose && manifest.daemon?.node) {
+    if (!manifest.compose && manifest.daemon?.backend) {
+        // The CLI installs the backend itself at ui/cgi/api.cgi.
+        if (manifest.daemon.node)
+            writeNodeLauncher(source, target, manifest.daemon.node);
+    }
+    else if (!manifest.compose && manifest.daemon?.node) {
         const exec = join(source, daemon.exec);
         if (!existsSync(exec) || !lstatSync(exec).isFile())
             throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", `daemon.exec must name the Node entry file inside the payload: ${exec}`);
-        if (existsSync(join(source, NODE_LAUNCHER.split("/")[0])))
-            throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", `The daemon payload must not contain ${NODE_LAUNCHER.split("/")[0]}/; the CLI writes its Node launcher there.`);
-        mkdirSync(join(target, "payload", dirname(NODE_LAUNCHER)), { recursive: true });
-        chmodSync(join(target, "payload", dirname(NODE_LAUNCHER)), 0o755);
-        writeFileSync(join(target, "payload", NODE_LAUNCHER), renderNodeLauncher(manifest.daemon.node));
-        chmodSync(join(target, "payload", NODE_LAUNCHER), 0o755);
+        writeNodeLauncher(source, target, manifest.daemon.node);
     }
     else if (!manifest.compose) {
         const exec = join(source, daemon.exec);
@@ -257,6 +285,14 @@ export function copyDaemonPayload(manifest, arch, target, controller) {
         mode: 0o644,
     });
 }
+function writeNodeLauncher(source, target, node) {
+    if (source && existsSync(join(source, NODE_LAUNCHER.split("/")[0])))
+        throw new StandaloneBuildError("STANDALONE_DAEMON_PAYLOAD_INVALID", `The daemon payload must not contain ${NODE_LAUNCHER.split("/")[0]}/; the CLI writes its Node launcher there.`);
+    mkdirSync(join(target, "payload", dirname(NODE_LAUNCHER)), { recursive: true });
+    chmodSync(join(target, "payload", dirname(NODE_LAUNCHER)), 0o755);
+    writeFileSync(join(target, "payload", NODE_LAUNCHER), renderNodeLauncher(node));
+    chmodSync(join(target, "payload", NODE_LAUNCHER), 0o755);
+}
 /** Copies a bounded, link-free package-account payload tree. */
 export function copyPayloadTree(root, source, target) {
     const invalid = (message) => {

package/dist/standalone/inspect-spk.d.ts

@@ -1,3 +1,4 @@
+import { type PackageDependencies } from "./package-dependencies.js";
 import { type InstallSettings } from './install-settings.js';
 import { type WebLaunchMode } from "../contract/web-launch.js";
 import { type ComposeApp } from "./compose.js";
@@ -9,6 +10,7 @@ import type { EntryMode } from "./manifest.js";
 import { type UninstallCleanupItem } from "../runtime/uninstall-cleanup.js";
 export type SpkKind = "native-go" | "native-python" | "native-node" | "native-rust" | "binary" | "container" | "native-layout";
 export interface SpkInspection {
+    dependencies?: PackageDependencies;
     installSettings?: InstallSettings;
     /** Hyper Backup application backup, as sdk-package.json records it. */
     hyperBackup?: HyperBackup;

package/dist/standalone/inspect-spk.js

@@ -1,3 +1,4 @@
+import { inspectPackageDependencies, dependencyInfo } from "./package-dependencies.js";
 import { readInstallSettings, settingsInstallSteps, settingsConfig, renderSettingsHook } from './install-settings.js';
 import { MODULE_UI_ENTRY, uiTreeDigest } from "./ui-assets.js";
 import { nativePortal } from "./portal.js";
@@ -23,7 +24,7 @@ import { familyOfArchToken, NATIVE_ARCH_FAMILIES, } from "../build-spk/dsm-arch.
 import { CONTAINER_MIN_DSM, isDsmAtLeast, PORTAL_EXECUTOR_MIN_DSM, PORTAL_MIN_DSM, PORTAL_MIN_DSM_REASON, } from "../build-spk/dsm-version.js";
 import { ELF_MACHINE } from "./binary.js";
 import { CGI_PAYLOAD_PATH, entryLauncherAccess } from "./dsm-window.js";
-import { daemonConfig, readDaemon, readLifecycleTimeouts, renderNodeLauncher, nodeDependency, NODE_LAUNCHER } from "./daemon.js";
+import { backendNodeEnv, daemonConfig, readDaemon, readLifecycleTimeouts, renderNodeLauncher, nodeDependency, NODE_LAUNCHER } from "./daemon.js";
 import { DAEMON_INGRESS_CONFIG, daemonIngressMinDsmProblem, readDaemonIngress, renderDaemonIngressConfig } from "./daemon-ingress.js";
 import { daemonRestartSdkProblem, readDaemonRestart } from "./daemon-restart.js";
 import { ROOT_SCRIPT_HINTS } from "./root-ops.js";
@@ -66,7 +67,12 @@ export async function inspectSpk(spkPath, expectedKind) {
         await tar.x({ file: spkPath, cwd: dir });
         const findings = [];
         if (!expectedKind && existsSync(join(dir, "native-layout.json"))) {
-            const info = readInfo(join(dir, "INFO"), findings, "native-layout");
+            let dependencies;
+            try {
+                dependencies = inspectPackageDependencies(JSON.parse(readFileSync(join(dir, "native-layout.json"), "utf8")).dependencies, findings);
+            }
+            catch { /* inspectNativeLayout reports a malformed inventory. */ }
+            const info = readInfo(join(dir, "INFO"), findings, "native-layout", false, undefined, dependencies);
             const payload = await listPayload(join(dir, "package.tgz"), findings);
             const target = join(dir, "layout-inspection");
             mkdirSync(target);
@@ -83,6 +89,7 @@ export async function inspectSpk(spkPath, expectedKind) {
                     findings.push(`Missing INFO ${key}`);
             const icon = inspectPackageIcons(dir, findings);
             return {
+                ...(dependencies ? { dependencies } : {}),
                 kind: "native-layout",
                 package: info.package,
                 version: info.version,
@@ -134,6 +141,7 @@ export async function inspectSpk(spkPath, expectedKind) {
                 findings.push("sdk-package.json does not match the schema 2 capability inventory.");
             }
         }
+        const dependencies = inspectPackageDependencies(metadata.dependencies, findings);
         const daemonRestart = recoverDaemonRestart(metadata.daemon_restart, metadata.daemon_sdk, findings);
         await inspectModuleUi(dir, paths, metadata.ui_module, findings);
         if (metadata.daemon_restart !== undefined && (metadata.compose !== undefined || !paths.has("daemon/control")))
@@ -152,6 +160,9 @@ export async function inspectSpk(spkPath, expectedKind) {
         const integrations = metadata.integrations ?? [];
         if (metadata.compose !== undefined) {
             const result = await inspectUnifiedCompose(dir, payload, { ...metadata, installSettings }, findings);
+            if (dependencies) {
+                result.dependencies = dependencies;
+            }
             if (installSettings)
                 result.installSettings = installSettings;
             if (hyperBackup)
@@ -181,7 +192,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             ? undefined
             : await recoverCompose(dir, metadata.compose, findings);
         const daemonNode = recoverDaemonNode(metadata.daemon_node, findings);
-        const info = readInfo(join(dir, "INFO"), findings, kind, Boolean(combined), daemonNode);
+        const info = readInfo(join(dir, "INFO"), findings, kind, Boolean(combined), daemonNode, dependencies);
         if (combined &&
             (!info.os_min_ver || !isDsmAtLeast(info.os_min_ver, CONTAINER_MIN_DSM)))
             findings.push("compose identity_gateway requires DSM >= 7.2.1");
@@ -230,6 +241,8 @@ export async function inspectSpk(spkPath, expectedKind) {
         const bridge = compiledKind && kind !== "native-go"
             ? await checkBridgeApp(dir, metadata.backend, info, payload, findings)
             : undefined;
+        if (dependencies && bridge?.node?.package && !dependencies.packages.some(d => d.name === bridge.node.package))
+            findings.push("DEPENDENCIES_INVALID build metadata dependencies omit the Node backend package.");
         const hasExecutor = (metadata.capabilities ?? []).some((name) => name === "rootOps" || name === "delegate" || name === "webapi") || paths.has("executor/executor");
         if (standalone && portal)
             findings.push(...inspectPortalInfo(info, hasExecutor));
@@ -315,6 +328,7 @@ export async function inspectSpk(spkPath, expectedKind) {
             findings.push(`${CGI_PAYLOAD_PATH} has mode ${cgiEntry.mode}; it should be 0755`);
         }
         return {
+            ...(dependencies ? { dependencies } : {}),
             kind,
             ...(identityGateway ? { identityGateway } : {}),
             ...(installSettings ? { installSettings } : {}),
@@ -691,7 +705,7 @@ async function checkArch(dir, info, kind, hasCgi, findings) {
 }
 /** Replay the SDK planner over archived source bytes, not merely a mutable lock. */
 async function inspectUnifiedCompose(dir, payload, metadata, findings) {
-    const info = readInfo(join(dir, "INFO"), findings, "binary", true);
+    const info = readInfo(join(dir, "INFO"), findings, "binary", true, undefined, inspectPackageDependencies(metadata.dependencies, findings));
     const base = {
         kind: "container",
         package: info.package,
@@ -956,6 +970,7 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             Object.keys(config).some((key) => ![
                 "package",
                 "exec",
+                "backend",
                 "args",
                 "env",
                 "timeouts",
@@ -967,8 +982,11 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             throw new Error("package/config mismatch");
         if (!isDeepStrictEqual(config.restart, extras.restart))
             throw new Error("daemon restart differs from its build declaration");
+        const backend = config.backend === true;
+        if (config.backend !== undefined && !backend)
+            throw new Error("invalid backend flag");
         const daemon = readDaemon({
-            exec: config.exec,
+            ...(backend ? { backend: true } : { exec: config.exec }),
             args: config.args,
             uninstall_args: config.uninstall_args,
             env: config.env,
@@ -980,6 +998,12 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
             throw new Error("invalid config");
         // The packaged config already carries the launcher argv; only the launcher itself is checked here.
         if (extras.node &&
+            backend &&
+            (daemon.env.SYNOPKGLAND_NODE !== backendNodeEnv().SYNOPKGLAND_NODE ||
+                readOptional(join(unpacked, "daemon/payload", NODE_LAUNCHER)) !== renderNodeLauncher(extras.node)))
+            throw new Error("Node launcher differs from its build declaration");
+        if (extras.node &&
+            !backend &&
             (daemon.exec !== NODE_LAUNCHER ||
                 !daemon.args[0]?.startsWith("${SYNOPKG_PKGDEST}/daemon/payload/") ||
                 readOptional(join(unpacked, "daemon/payload", NODE_LAUNCHER)) !== renderNodeLauncher(extras.node)))
@@ -993,7 +1017,8 @@ async function checkDaemon(dir, info, paths, payload, findings, executor, backgr
                 JSON.stringify(daemon.args) !== '["run"]' ||
                 daemon.uninstall_args))
             throw new Error("compose gateway must run without a child");
-        if (payload.find((p) => p.path === `daemon/payload/${daemon.exec}`)?.mode !==
+        // A backend daemon runs the audited CGI binary.
+        if (payload.find((p) => p.path === (backend ? CGI_PAYLOAD_PATH : `daemon/payload/${daemon.exec}`))?.mode !==
             "0755")
             throw new Error("missing executable");
         const manifest = {
@@ -1064,7 +1089,7 @@ function archivedInfoTranslations(info) {
     }
     return translations;
 }
-function readInfo(path, findings, kind, compose = false, daemonNode) {
+function readInfo(path, findings, kind, compose = false, daemonNode, dependencies) {
     if (!existsSync(path)) {
         findings.push("INFO is missing");
         return {};
@@ -1073,6 +1098,8 @@ function readInfo(path, findings, kind, compose = false, daemonNode) {
     for (const line of readFileSync(path, "utf8").split("\n")) {
         const match = line.match(/^([a-z_]+)="(.*)"$/);
         if (match) {
+            if (match[1] === "install_dep_packages" && Object.hasOwn(info, match[1]))
+                findings.push("INFO install_dep_packages must appear only once");
             info[match[1]] = match[2];
         }
     }
@@ -1098,7 +1125,14 @@ function readInfo(path, findings, kind, compose = false, daemonNode) {
             : kind === "native-node"
                 ? /^Node\.js_v[0-9]{2}([><=].*)?$/
                 : undefined;
-    if (daemonNode && info.install_dep_packages !== nodeDependency(daemonNode))
+    if (dependencies) {
+        if ((info.install_dep_packages ?? "") !== dependencyInfo(dependencies))
+            findings.push("INFO install_dep_packages does not match build metadata dependencies");
+        const inferred = daemonNode && dependencies.packages.find(d => d.name === daemonNode.package);
+        if (daemonNode && (!inferred || daemonNode.min_version !== undefined && inferred.min_version !== daemonNode.min_version))
+            findings.push("DEPENDENCIES_INVALID build metadata dependencies conflict with daemon.node");
+    }
+    else if (daemonNode && info.install_dep_packages !== nodeDependency(daemonNode))
         findings.push(`daemon.node requires INFO install_dep_packages="${nodeDependency(daemonNode)}"`);
     else if (!daemonNode &&
         info.install_dep_packages &&
@@ -1453,7 +1487,7 @@ async function inspectInstallSettings(dir, payload, metadata, findings) {
     const root = join(dir, 'install-settings-inspection');
     mkdirSync(root);
     await tar.x({ file: join(dir, 'package.tgz'), cwd: root });
-    const info = readInfo(join(dir, 'INFO'), findings, 'binary', Boolean(metadata.compose));
+    const info = readInfo(join(dir, 'INFO'), findings, 'binary', Boolean(metadata.compose), undefined, inspectPackageDependencies(metadata.dependencies, findings));
     const gateway = metadata.compose?.gateway ?? metadata.native_gateway;
     const m = { package: info.package, os_min_ver: info.os_min_ver, capabilities: {}, installSettings: settings, identityGateway: gateway };
     try {

package/dist/standalone/manifest.d.ts

@@ -1,3 +1,4 @@
+import { type PackageDependencies } from "./package-dependencies.js";
 import { type InstallSettings } from './install-settings.js';
 import { type WebLaunchMode } from "../contract/web-launch.js";
 import { type WebAPIProfiles } from "../runtime/webapi-profile.js";
@@ -51,6 +52,7 @@ export interface StandaloneManifest {
         commands: Record<string, import("../ctl/descriptor.js").Operation>;
     };
     metadata?: PackageMetadata;
+    dependencies?: PackageDependencies;
     root: string;
     package: string;
     version: string;

package/dist/standalone/manifest.js

@@ -1,3 +1,4 @@
+import { readPackageDependencies, packageDependencies, dependencyError } from "./package-dependencies.js";
 import { readInstallSettings } from './install-settings.js';
 import { auditGoRoutes } from './route-audit.js';
 import { BACKGROUND_WORKER_MAIN } from './background.js';
@@ -55,6 +56,7 @@ export const KNOWN_FIELDS = new Set([
     "capabilities",
     "i18n",
     "daemon",
+    "dependencies",
     "identity_gateway",
     "compose",
     "install",
@@ -247,6 +249,19 @@ function readManifest(raw, c) {
     const lifecycleTimeouts = timeoutOnly ? readLifecycleTimeouts(raw.daemon.timeouts, (e) => c.fail(e.code, e.message)) : undefined;
     const daemon = arches &&
         readDaemon(timeoutOnly ? undefined : raw.daemon, c.root, arches, (e) => c.fail(e.code, e.message));
+    let dependencies;
+    try {
+        const explicit = readPackageDependencies(raw.dependencies);
+        if (backend) {
+            const effective = packageDependencies({ backend, daemon, dependencies: explicit });
+            if (explicit || effective.packages.length)
+                dependencies = effective;
+        }
+    }
+    catch (error) {
+        const problem = dependencyError(error);
+        c.fail(problem.code, problem.message);
+    }
     const gatewayRaw = isRecord(raw.identity_gateway) ? raw.identity_gateway : {};
     if (raw.compose !== undefined && isRecord(raw.ctl) && raw.ctl.enabled === true)
         c.fail("CTL_UNSUPPORTED_BACKEND", "Compose does not support automatic ctl descriptions; disable ctl.");
@@ -297,8 +312,8 @@ function readManifest(raw, c) {
         if (problem)
             c.fail("STANDALONE_DAEMON_RESTART_SDK_REQUIRED", problem);
     }
-    if ((daemon?.ingress || daemon?.node) && raw.identity_gateway !== undefined)
-        c.fail("STANDALONE_DAEMON_INVALID", "daemon.node and daemon.ingress run the App's own daemon; identity_gateway runs its gateway as the daemon. Use one or the other.");
+    if ((daemon?.ingress || daemon?.node || daemon?.backend) && raw.identity_gateway !== undefined)
+        c.fail("STANDALONE_DAEMON_INVALID", "daemon.backend, daemon.node and daemon.ingress run the App's own daemon; identity_gateway runs its gateway as the daemon. Use one or the other.");
     if (compose && identityGateway && compose.sdk !== identityGateway.sdk)
         c.fail("STANDALONE_IDENTITY_GATEWAY_INVALID", "compose and identity_gateway must use the same SDK release.");
     if (compose &&
@@ -507,6 +522,7 @@ function readManifest(raw, c) {
         ...(rootOps ? { rootOps } : {}),
         ...(rootPrograms ? { rootPrograms } : {}),
         ...(daemon ? { daemon } : {}),
+        ...(dependencies ? { dependencies } : {}),
         ...(lifecycleTimeouts ? { lifecycleTimeouts } : {}),
         ...(identityGateway ? { identityGateway } : {}),
         ...(compose ? { compose } : {}),

package/dist/standalone/native-layout.d.ts

@@ -1,3 +1,4 @@
+import { type PackageDependencies } from "./package-dependencies.js";
 import { type PackageMetadata } from "../package-metadata.js";
 import type { CommandRunner } from './build.js';
 import { type Toolkit } from './toolkit.js';
@@ -21,6 +22,7 @@ type Binary = {
 };
 export interface NativeLayout {
     metadata?: PackageMetadata;
+    dependencies?: PackageDependencies;
     root: string;
     package: string;
     version: string;

package/dist/standalone/native-layout.js

@@ -1,3 +1,4 @@
+import { readPackageDependencies, dependencyInfo, inspectPackageDependencies } from "./package-dependencies.js";
 import { portalInfoFields } from "../portal/info.js";
 import { validateMetadata, metadataInfoFields } from "../package-metadata.js";
 /** Existing native products: the CLI owns archives/INFO, the project owns its layout. */
@@ -106,13 +107,15 @@ export function isNativeLayout(root) {
 }
 export function loadNativeLayout(root) {
     try {
-        const m = object(parse(readFileSync(join(root, 'dsm-package.yaml'), 'utf8')), ['schema', 'backend', 'package', 'version', 'build', 'displayname', 'description', 'maintainer', 'metadata', 'os_min_ver', 'privilege', 'arches', 'layout', 'native', 'icon', 'reproducible', 'portal']);
+        const m = object(parse(readFileSync(join(root, 'dsm-package.yaml'), 'utf8')), ['schema', 'backend', 'package', 'version', 'build', 'displayname', 'description', 'maintainer', 'metadata', 'os_min_ver', 'privilege', 'arches', 'layout', 'native', 'icon', 'reproducible', 'portal', 'dependencies']);
         if (m.schema !== 2)
             fail('schema 2 required; migrate schema: 1 to schema: 2 and add backend: {kind: native}');
         const backend = object(m.backend, ['kind']);
         if (backend.kind !== 'native' || (m.privilege !== undefined && m.privilege !== 'none'))
             fail('backend.kind: native and package-only privilege required');
         m.privilege = 'none';
+        if (m.dependencies !== undefined)
+            m.dependencies = readPackageDependencies(m.dependencies);
         if (m.metadata !== undefined)
             m.metadata = validateMetadata(m.metadata);
         if (existsSync(join(root, 'compose.yaml')))
@@ -330,11 +333,12 @@ export async function buildNativeLayout(options) {
             await createReproducibleTar(target, join(stage, 'package.tgz'), { gzip: true });
             rmSync(target, { recursive: true });
             const fields = { package: m.package, version, arch: layoutInfoArch(arch), os_min_ver: m.os_min_ver, displayname: m.displayname, description: m.description, maintainer: m.maintainer, dsmuidir: 'ui', dsmappname: `SYNO.SDS.${m.package}.Instance`, startable: 'yes', thirdparty: 'yes', checksum: createHash('md5').update(readFileSync(join(stage, 'package.tgz'))).digest('hex') };
-            const info = portalInfoFields([...Object.entries(fields), ...metadataInfoFields(m.metadata), ...anchorFields(m.layout.anchors ?? {}, files), ...portalFields(m.portal)], Boolean(m.portal));
+            const deps = dependencyInfo(m.dependencies ?? { packages: [] });
+            const info = portalInfoFields([...Object.entries(fields), ...(deps ? [["install_dep_packages", deps]] : []), ...metadataInfoFields(m.metadata), ...anchorFields(m.layout.anchors ?? {}, files), ...portalFields(m.portal)], Boolean(m.portal));
             if (new Set(info.map(([k]) => k)).size !== info.length)
                 fail('INFO anchor collides with an INFO field');
             writeFileSync(join(stage, 'INFO'), info.map(([k, v]) => `${k}="${v.replace(/([\\"$`])/g, '\\$1')}"\n`).join(''));
-            writeFileSync(join(stage, 'native-layout.json'), JSON.stringify({ format: 1, arch, binaries: binaries.map(({ path, linkage }) => ({ path, linkage })), files, ...(m.layout.anchors ? { anchors: m.layout.anchors } : {}), ...(m.portal ? { portal: m.portal } : {}) }));
+            writeFileSync(join(stage, 'native-layout.json'), JSON.stringify({ format: 1, arch, dependencies: m.dependencies ?? { packages: [] }, binaries: binaries.map(({ path, linkage }) => ({ path, linkage })), files, ...(m.layout.anchors ? { anchors: m.layout.anchors } : {}), ...(m.portal ? { portal: m.portal } : {}) }));
             const output = join(outDir, `${m.package}-${version}-${arch}.spk`);
             await createReproducibleTar(stage, output);
             return output;
@@ -351,9 +355,15 @@ export function inspectNativeLayout(dir, payload, info) {
     try {
         if (!/^[A-Za-z][A-Za-z0-9]{1,63}$/.test(info.package ?? '') || !/^\d+(\.\d+){0,3}-\d+$/.test(info.version ?? '') || !/^7\.\d+(\.\d+)?-\d+$/.test(info.os_min_ver ?? ''))
             fail('invalid native INFO identity/version/DSM');
-        const inv = object(JSON.parse(readFileSync(join(dir, 'native-layout.json'), 'utf8')), ['format', 'arch', 'binaries', 'files', 'anchors', 'portal']);
+        const inv = object(JSON.parse(readFileSync(join(dir, 'native-layout.json'), 'utf8')), ['format', 'arch', 'binaries', 'files', 'anchors', 'portal', 'dependencies']);
         if (inv.format !== 1 || !Object.hasOwn(LAYOUT_ARCHES, inv.arch) || layoutInfoArch(inv.arch) !== info.arch)
             fail('invalid native layout inventory');
+        const errors = [];
+        const dependencies = inspectPackageDependencies(inv.dependencies, errors);
+        if (errors.length)
+            fail(errors.join("; "));
+        if ((info.install_dep_packages ?? "") !== dependencyInfo(dependencies ?? { packages: [] }))
+            fail("INFO install_dep_packages differs from native layout dependencies");
         checkLayoutMetadata(dir, true, info.package);
         const actual = layoutFiles(payload);
         if (JSON.stringify(actual) !== JSON.stringify(inv.files))

package/dist/standalone/package-dependencies.d.ts

@@ -0,0 +1,17 @@
+import type { StandaloneManifest, StandaloneError } from "./manifest.js";
+export interface PackageDependency {
+    name: string;
+    min_version?: string;
+}
+export interface PackageDependencies {
+    packages: PackageDependency[];
+}
+/** Fixed INFO tokens, never shell expressions or dependency operators. */
+export declare function readPackageDependencies(value: unknown): PackageDependencies | undefined;
+/** Unversioned requirements accept a specified minimum; distinct minima conflict. */
+export declare function mergePackageDependencies(...groups: PackageDependency[][]): PackageDependency[];
+export declare function packageDependencies(manifest: Pick<StandaloneManifest, "backend" | "daemon" | "dependencies">): PackageDependencies;
+export declare function dependencyInfo(dependencies: PackageDependencies): string;
+/** Old build records have no field; new records must already be normalized. */
+export declare function inspectPackageDependencies(value: unknown, findings: string[]): PackageDependencies | undefined;
+export declare function dependencyError(error: unknown): StandaloneError;

package/dist/standalone/package-dependencies.js

@@ -0,0 +1,57 @@
+import { isDeepStrictEqual } from "node:util";
+const record = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const NAME = /^[A-Za-z][A-Za-z0-9_.-]{0,63}$/;
+const VERSION = /^\d+(?:\.\d+){0,3}(?:-\d+)?$/;
+/** Fixed INFO tokens, never shell expressions or dependency operators. */
+export function readPackageDependencies(value) {
+    if (value === undefined)
+        return undefined;
+    if (!record(value) || Object.keys(value).some(k => k !== "packages") || !Array.isArray(value.packages))
+        throw new Error("dependencies accepts only packages: an array of {name, min_version?}.");
+    const packages = value.packages.map((entry, i) => {
+        if (!record(entry) || Object.keys(entry).some(k => k !== "name" && k !== "min_version") ||
+            typeof entry.name !== "string" || !NAME.test(entry.name))
+            throw new Error(`dependencies.packages[${i}].name must start with a letter and contain only ASCII letters, digits, _, . or - (1-64 characters); only name and min_version are accepted.`);
+        if (entry.min_version !== undefined && (typeof entry.min_version !== "string" || entry.min_version.length > 64 || !VERSION.test(entry.min_version)))
+            throw new Error(`dependencies.packages[${i}].min_version must be a quoted numeric version with 1-4 components and an optional numeric -build (at most 64 characters).`);
+        return { name: entry.name, ...(entry.min_version !== undefined ? { min_version: entry.min_version } : {}) };
+    });
+    return { packages: mergePackageDependencies(packages) };
+}
+/** Unversioned requirements accept a specified minimum; distinct minima conflict. */
+export function mergePackageDependencies(...groups) {
+    const byName = new Map();
+    for (const dep of groups.flat()) {
+        const prev = byName.get(dep.name);
+        if (prev?.min_version !== undefined && dep.min_version !== undefined && prev.min_version !== dep.min_version)
+            throw new Error(`Conflicting min_version for package ${dep.name}: ${prev.min_version} and ${dep.min_version}. Use one identical minimum version.`);
+        byName.set(dep.name, { name: dep.name, ...(prev?.min_version !== undefined ? { min_version: prev.min_version } : dep.min_version !== undefined ? { min_version: dep.min_version } : {}) });
+    }
+    return [...byName.values()].sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+}
+export function packageDependencies(manifest) {
+    const node = "node" in manifest.backend ? manifest.backend.node : undefined;
+    const daemonNode = manifest.daemon?.node;
+    return { packages: mergePackageDependencies(readPackageDependencies(manifest.dependencies)?.packages ?? [], node ? [{ name: node.package }] : [], daemonNode ? [{ name: daemonNode.package, ...(daemonNode.min_version ? { min_version: daemonNode.min_version } : {}) }] : []) };
+}
+export function dependencyInfo(dependencies) {
+    return dependencies.packages.map(d => d.name + (d.min_version === undefined ? "" : `>=${d.min_version}`)).join(":");
+}
+/** Old build records have no field; new records must already be normalized. */
+export function inspectPackageDependencies(value, findings) {
+    if (value === undefined)
+        return undefined;
+    try {
+        const normalized = readPackageDependencies(value);
+        if (!isDeepStrictEqual(normalized, value))
+            throw new Error("dependencies must be sorted, deduplicated and normalized.");
+        return normalized;
+    }
+    catch (error) {
+        findings.push(`DEPENDENCIES_INVALID build metadata dependencies: ${error.message}`);
+        return { packages: [] };
+    }
+}
+export function dependencyError(error) {
+    return { code: "STANDALONE_DEPENDENCIES_INVALID", message: error.message };
+}

package/dist/standalone/spk.js

@@ -1,3 +1,4 @@
+import { packageDependencies, dependencyInfo } from "./package-dependencies.js";
 import { settingsInstallSteps, settingsConfig } from './install-settings.js';
 import { backupConfig, backupHookProblem, backupRecord, renderBackupScripts, BACKUP_PAYLOAD_DIR, BACKUP_SCRIPTS_DIR, BACKUP_SCRIPT_MODES } from './hyper-backup.js';
 import { nativeGatewaySupported, nativeGatewaySdk, renderNativeGatewayConfig, NATIVE_GATEWAY_CONFIG, legacyGatewayNotice, gatewayEntryPath } from './native-gateway.js';
@@ -31,7 +32,7 @@ import { copyAppTree } from "./bridge-app.js";
 import { isBridgeBackend } from "./bridge-backend.js";
 import { hostScriptName, renderHostAdapterScript } from "./host-adapter.js";
 import { writeComposePayload } from "./compose.js";
-import { copyDaemonPayload, daemonSdkVersion, nodeDependency } from "./daemon.js";
+import { copyDaemonPayload, daemonSdkVersion } from "./daemon.js";
 import { DAEMON_INGRESS_CONFIG, renderDaemonIngressConfig } from "./daemon-ingress.js";
 import { gatewayCgiPaths, gatewayExternalAccess, GATEWAY_CONFIG_PATH, GATEWAY_EXEC, identityGatewayConfig, identityGatewayDeclaration, } from "./identity-gateway.js";
 import { BACKGROUND_UNIT_DIR, BACKGROUND_WORKER_PAYLOAD, backgroundUnitName, renderBackgroundUnit, BRIDGE_WORKER_ARGS, } from "./background.js";
@@ -244,6 +245,7 @@ export async function assembleStandaloneSpk(options) {
             .digest("hex");
         writeFile(join(staging, "sdk-package.json"), JSON.stringify({
             schema: 2,
+            dependencies: packageDependencies(manifest),
             ...(moduleVersion ? { ui_module: moduleVersion } : {}),
             ...(manifest.installSettings ? { installSettings: manifest.installSettings } : {}),
             ...(backup ? { hyperBackup: backupRecord(backup) } : {}),
@@ -389,11 +391,9 @@ export function renderInfo(manifest, arch, checksum, executorDigest) {
             "adminurl",
             gatewayEntryPath(manifest),
         ]);
-    const backend = manifest.backend;
-    if (isBridgeBackend(backend) && backend.node)
-        fields.push(["install_dep_packages", backend.node.package]);
-    if (manifest.daemon?.node)
-        fields.push(["install_dep_packages", nodeDependency(manifest.daemon.node)]);
+    const dependencies = dependencyInfo(packageDependencies(manifest));
+    if (dependencies)
+        fields.push(["install_dep_packages", dependencies]);
     fields.push(...metadataInfoFields(manifest.metadata));
     // Background packages need prestart: it runs before DSM's systemd-user-unit acquire.
     if (manifest.daemon || manifest.compose || manifest.capabilities.jobs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@napi-rs/keyring": "^2.1.1",
-    "@synopackageland/templates": "~0.34.0",
+    "@synopackageland/templates": "~0.35.0",
     "ajv": "^8.17.1",
     "commander": "^13.1.0",
     "json-canonicalize": "^3.0.1",

package/skills/SKILL.md

@@ -5,7 +5,7 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-The CLI installs templates through `~0.34.0`. A templates patch needs only a
+The CLI installs templates through `~0.35.0`. A templates patch needs only a
 templates release; npm install/update selects a patch in that minor line. The CLI
 uses the locally installed templates and reads their SDK pin for defaults; it
 never downloads templates at runtime. Preserve the lockfile and use `npm ci` for
@@ -24,7 +24,7 @@ Use this guide to initialize, build and inspect own applications or upstream OSS
 
 For an existing open-source App, first read [reference/upstream-fork.md](reference/upstream-fork.md): upstream fork/history + untouched upstream files + all packaging in `synology/`, official container images pinned by tag/index digest, native official release binaries pinned by SHA-256 or a source build hook, and a single tag-merge upgrade command. Use `init --upstream-fork`; never rewrite the App as a component. Integrated upstream Apps require direct DSM administrator entry without a separate App password or an OIDC/SSO server: supported trusted headers first, disabling native login second; the shipped OpenList pattern uses the existing SDK 0.17.3 token adapter (`mode: token`, `access: dsm-admins`, `entry: admin-only`) with server-side Authorization injection. All DSM admins share one upstream admin; token reset requires package restart; WebDAV retains its native credentials.
 
-Use SDK/App 0.36.0 and CLI 0.38.0 for App entry enforcement. Declare every App method
+Use SDK/App 0.37.0 and CLI 0.40.0 for App entry enforcement. Declare every App method
 in the permissions table; dynamic names and unregistered HTTP dispatchers are rejected.
 Use fixed SDK routes and `identity_gateway.upstream_auth_paths` for client API
 paths that rely on upstream authentication. Read
@@ -99,8 +99,27 @@ Never install, uninstall, publish or modify NAS data without task authorization.
 
 Native projects use schema 2 capabilities and `--with files,jobs,login,root-ops,delegate`; use `add` for existing projects. Prefer `check --json`, `build --json`, `inspect <spk> --json`, `deploy --dry-run --json`, and `status --host <profile> --json` for structured results. Read the conflict policy in reference/create.md before adding overlays.
 
+For DSM Package Center dependencies independent of the App language, declare
+`dependencies: {packages: [{name: Node.js_v22, min_version: "22.19.0"}]}` in
+`dsm-package.yaml`; `min_version` is optional. Names are 1-64 ASCII letters,
+digits, `_`, `.` or `-`, starting with a letter. Versions are quoted numeric
+strings with 1-4 dotted components and optional numeric `-build` (64 characters
+maximum); other keys and unsafe INFO syntax fail validation. Requirements
+merge with a Node backend or `daemon.node`, sort and deduplicate; two distinct
+specified minimum versions for one package fail. `check --json` reports them;
+build records them and `inspect` verifies exact agreement with INFO. This
+works with native layouts and Compose too (host packages are not container
+mounts). It leaves daemon exec/args/env/supervision unchanged. Use
+`daemon.node` only for a JavaScript daemon: it replaces exec with the Node
+launcher. For a Go daemon spawning Node children, keep the Go exec and use
+`dependencies.packages`; call `/var/packages/Node.js_v22/target/usr/local/bin/node`.
+Any dependency's target is `/var/packages/<name>/target`; no env vars or PATH
+entries are injected, and the declaration grants no private-data access.
+
 Read reference/portal.md before declaring or changing a DSM Application Portal alias (`add portal`); DSM owns the saved setting; DSM 7.2-64570+ supports schema-2 Portal without an executor, while DSM 7.1 requires executor registration. Read reference/files.md and reference/identity.md for capability boundaries. RootOps and delegate share one-time protected executor boot/control setup with digest approval. Existing native products can explicitly use the separate native runtimes in @synopackageland/sdk/native; do not mix its tasks with generated executor capabilities. App sessions alone do not grant NAS file authority.
 
+Before choosing `daemon.backend` (the backend as a resident daemon behind `daemon.ingress`) for speed, read [reference/daemon-mode.md](reference/daemon-mode.md): measure the CGI first; the daemon pays off only for repeated, cacheable per-request work on a NAS with memory to spare.
+
 Read [reference/lifecycle.md](reference/lifecycle.md) before editing `dsm-scripts/` (preinst, postinst, preupgrade, postupgrade, preuninst, postuninst, start-stop-status): the SDK runs them inside its generated scripts as the package account; never add root work or repeat SDK steps there.
 
 Native Apps appear in Hyper Backup as applications by default. Read [reference/backup.md](reference/backup.md) before changing `backup` in dsm-package.yaml (opt out with `hyper_backup: false`, online mode, data version, hook). Hyper Backup runs the generated `scripts/backup/` as root; it is a fixed template that only switches to the package account, so never add or edit files there.

package/skills/reference/daemon-mode.md

@@ -0,0 +1,90 @@
+# When to run the backend as a daemon
+
+A native App's backend normally runs as a CGI: DSM starts `ui/cgi/api.cgi`
+for every request, and the process exits when the request ends. With
+`daemon.backend: true` and `daemon.ingress` ([docs/daemon.md](../../docs/daemon.md)),
+the same binary runs once as the package daemon and serves the pages through
+DSM's nginx. The CGI stays for integrations, transfers and fallback.
+
+Daemon mode is not the default recommendation. It removes work that repeats
+on every request. It does not make a single expensive request cheaper, and it
+costs memory for as long as the package runs. Measure first, then decide.
+
+## Decision table
+
+| Factor | Daemon helps | Stay with CGI |
+| --- | --- | --- |
+| Fixed cost per request | High: each request loads or compiles many definitions, opens several stores or runs sign-in checks that could be remembered | Low: the handler reads a row or two and returns |
+| Request rate | Pages send many calls; many users at once | A few calls per page; few users |
+| Repeated, cacheable work | Most of the time goes to work whose result does not change between requests (compiled definitions, permission answers, zone data) | Each request does new work (one-off reports, large exports) |
+| Long connections | Streams, server-sent events, long polling | None |
+| Background work | A tick, outbox sending or polling that should run within seconds | A scheduled task every few minutes is enough |
+| App size | Many Apps, large definitions | One small App |
+| NAS memory | Enough room for the base process plus a bounded cache | Small models (2–4 GB) that already swap; every resident MB competes with DSM and other packages |
+| Idle cost | Acceptable: the process stays up when nobody uses the App | Not acceptable: the App is opened rarely |
+
+The base process is usually small: an idle Go daemon is typically 10–30 MB
+RSS. Measure your own binary. The real variable is the cache, so give every
+cache an upper bound and measure it filled.
+
+## Factors and example numbers
+
+These numbers come from Studio Office. Use them as an example of what
+to measure, not as a budget.
+
+- **CGI cost per request.** On a DS SA3400 with 25 Apps, every Studio call
+  spent 100–140 ms before the handler did any work: process start, the DSM
+  sign-in check (`authenticate.cgi`), the App Privileges check and schema
+  checks. Recompiling App definitions on each request took about 70% of
+  `studio.apps.list`. Measure this on the NAS: time an empty call (for
+  example `app.status`) and the slowest common page calls.
+- **Resident memory.** Measured on macOS arm64 in a Go test process, not
+  on the NAS: 37 MB RSS with the routes built and the store opened, and
+  81 MB after 23 compiled template Apps were kept (about 1.1 MB of
+  heap per App).
+  The Node AI child has not been measured. Measure on the target NAS with your
+  real data before you choose cache sizes.
+- **Cache bounds.** Bound each cache by entry count (LRU) and derive the bound
+  from the measured size per entry. Studio keeps 32 compiled releases, about
+  35 MB at the measured size. Cache only results that are pure functions of
+  their key, such as compiled definitions keyed by a hash of the stored plan,
+  and cache only successes.
+- **Sign-in cache.** `dsm.CacheSessions` remembers verified sessions for a
+  TTL you choose (Studio: 10 minutes). The cost is staleness: a sign-out, a
+  disabled account or a lost administrator role takes effect up to the TTL
+  later. App Privileges keep their own 30-second check.
+- **Crash and restart.** The SDK daemon controller restarts the daemon
+  (`daemon.restart`). Children of the daemon, such as a Node service, are the
+  backend's own job: start them, restart them with backoff and stop them on
+  SIGTERM. Keep the CGI as fallback, so pages still work when the daemon is
+  down. Retry only reads automatically, plus calls the daemon cannot have seen.
+- **Upgrade.** DSM stops the old daemon and starts the new one. In-memory
+  caches start empty and fill on first use. Migrations still run at start.
+  The CGI is the same binary, so both paths always run the same version.
+- **Security boundary.** The daemon serves the same handler as the CGI. Origin,
+  App entry, DSM session and route permission are checked on every request.
+  The ingress socket is mode 0666 because nginx runs as another account, so
+  a local process can connect directly and choose `X-Real-IP`. A valid DSM
+  session is still required, but IP-based App Privileges rules can be
+  bypassed this way. The route audit treats `api.ServeIngress` like
+  `cgi.Serve`.
+
+## Decision steps
+
+1. Measure the CGI. Time an empty authenticated call and the 3–5 calls a
+   common page makes, on the target NAS, a few times each. Count how many
+   calls one page sends.
+2. Find where the time goes. Split fixed cost (process start, sign-in, entry
+   checks) from handler work. Then split handler work into repeated,
+   cacheable work and work that changes per request.
+3. Optimize inside the CGI first, if that is enough:
+   - Send fewer requests: batch reads, and return all items in one page instead
+     of serial paging.
+   - Use disk caches keyed by content hash (for example compiled definitions
+     next to the store).
+   - Avoid loading what the call does not use.
+4. Choose the daemon only when, after step 3, most of the remaining time is
+   fixed cost or cacheable repeated work, and the NAS has memory for the
+   measured base plus the bounded cache.
+5. After switching, measure idle RSS and RSS with a full cache on the NAS, and
+   the same page calls as in step 1. Write the numbers into the App's docs.