@synopackageland/cli 0.6.0 → 0.7.0

package/dist/templates/native-go-vue/frontend/test/apps.test.ts

@@ -41,3 +41,17 @@ test('failed status loading offers a retry and releases the mounting class',asyn
   f.app.unmount();expect(f.root.classList.contains('dsmapp-vue-root')).toBe(false)
  }finally{f.close()}
 })
+test('a portal app shows the Application Portal section on the status page',async()=>{
+ const without=fixture('Plain')
+ const f=fixture('Portal')
+ try{
+  await settle();expect(without.root.textContent).not.toContain('Application Portal')
+  f.app.unmount()
+  const status={state:'active',alias:'portal',url:'https://nas.example/portal/',canManage:false,controlPanel:false,defaultAlias:'portal'} as const
+  f.ctx.portal={messages:{title:'Application Portal',link:'Direct link:'},status:vi.fn(async()=>status),apply:vi.fn(),disable:vi.fn(),openControlPanel:vi.fn(),mountPanel:vi.fn()}
+  const app=mount(f.root,f.ctx);await settle()
+  expect(f.root.textContent).toContain('Application Portal')
+  expect(f.root.querySelector('a[href="https://nas.example/portal/"]')).not.toBeNull()
+  app.unmount()
+ }finally{without.close();f.root.remove()}
+})

package/dist/templates/native-go-vue/frontend/test/portal-settings.test.ts

@@ -0,0 +1,71 @@
+// @vitest-environment jsdom
+import {expect,test,vi} from 'vitest'
+import {createApp,h,nextTick} from 'vue'
+import {AppRoot} from '@synopackageland/ui'
+import PortalSettings from '../src/portal/PortalSettings.vue'
+import type {PortalAccess,PortalStatus} from '../src/context'
+
+const messages={title:'Application Portal',link:'Direct link:',inactive:'Not active.',askAdmin:'Ask an administrator',alias:'Alias',apply:'Apply',disable:'Turn off',advanced:'Advanced',controlPanel:'Open Control Panel',portal_alias_in_use:'Alias in use',portal_unavailable:'DSM refused'}
+const base:PortalStatus={state:'inactive',canManage:false,controlPanel:false,defaultAlias:'my-app'}
+function access(status:PortalStatus,overrides:Partial<PortalAccess>={}):PortalAccess{
+ return {messages,status:vi.fn(async()=>status),apply:vi.fn(async()=>status),disable:vi.fn(async()=>status),openControlPanel:vi.fn(),mountPanel:vi.fn(),...overrides}
+}
+async function mount(portal:PortalAccess){
+ const root=document.createElement('div');document.body.append(root)
+ const app=createApp({render:()=>h(AppRoot,{},()=>h(PortalSettings,{portal}))})
+ app.mount(root);await nextTick();await nextTick();await new Promise(r=>setTimeout(r));await nextTick()
+ return {root,unmount(){app.unmount();root.remove()}}
+}
+const buttons=(root:HTMLElement)=>[...root.querySelectorAll('button')].map(b=>b.textContent?.trim())
+
+test('an ordinary user sees the active link and nothing to change',async()=>{
+ const {root,unmount}=await mount(access({...base,state:'active',alias:'my-app',url:'https://nas.example/my-app/'}))
+ try{
+  expect(root.querySelector('a')?.getAttribute('href')).toBe('https://nas.example/my-app/')
+  expect(root.querySelector('input')).toBeNull();expect(root.querySelector('button')).toBeNull()
+ }finally{unmount()}
+})
+
+test('an ordinary user without an active alias is asked to contact an administrator',async()=>{
+ const {root,unmount}=await mount(access({...base,state:'unavailable'}))
+ try{
+  expect(root.textContent).toContain('Ask an administrator')
+  expect(root.querySelector('a,input,button')).toBeNull()
+ }finally{unmount()}
+})
+
+test('an administrator applies the prefilled alias and sees DSM refusals as portal text',async()=>{
+ const apply=vi.fn(async()=>Promise.reject({code:'portal_alias_in_use'}))
+ const portal=access({...base,canManage:true},{apply})
+ const {root,unmount}=await mount(portal)
+ try{
+  const input=root.querySelector('input')!
+  expect(input.value).toBe('my-app')
+  root.querySelector('form')!.dispatchEvent(new Event('submit',{cancelable:true}))
+  await new Promise(r=>setTimeout(r));await nextTick()
+  expect(apply).toHaveBeenCalledWith('my-app')
+  expect(root.querySelector('[role="alert"]')?.textContent).toContain('Alias in use')
+  ;[...root.querySelectorAll('button')].find(b=>b.textContent?.includes('Advanced'))!.click()
+  expect(portal.openControlPanel).toHaveBeenCalled()
+ }finally{unmount()}
+})
+
+test('an administrator turns an active alias off',async()=>{
+ const portal=access({...base,state:'active',alias:'my-app',url:'https://nas.example/my-app/',canManage:true})
+ const {root,unmount}=await mount(portal)
+ try{
+  expect(root.querySelector('a')?.getAttribute('href')).toBe('https://nas.example/my-app/')
+  ;[...root.querySelectorAll('button')].find(b=>b.textContent?.includes('Turn off'))!.click()
+  await nextTick()
+  expect(portal.disable).toHaveBeenCalled()
+ }finally{unmount()}
+})
+
+test('an administrator without DSM portal support gets only the Control Panel shortcut',async()=>{
+ const portal=access({...base,state:'unavailable',controlPanel:true})
+ const {root,unmount}=await mount(portal)
+ try{
+  expect(root.querySelector('input')).toBeNull()
+  expect(buttons(root)).toEqual(['Open Control Panel'])
+ }finally{unmount()}
+})

package/dist/templates/native-go-vue/frontend/test/shell-i18n.test.ts

@@ -0,0 +1,50 @@
+// @vitest-environment jsdom
+// @vitest-environment-options {"url":"https://nas.test"}
+import {expect,test,vi} from 'vitest'
+import {nextTick} from 'vue'
+import {mount} from '../src/main'
+import type {Context} from '../src/context'
+import {appCopy} from '../src/i18n'
+import {identityCopy} from '../src/identity/i18n'
+async function settle(){for(let i=0;i<20;i++){await Promise.resolve();await nextTick()}}
+const buttons=(root:HTMLElement)=>[...root.querySelectorAll('button')].map(b=>b.textContent?.trim())
+function start(locale:string,call:(method:string)=>Promise<unknown>){
+ const ctx={locale,call:vi.fn(call),reopen(){return ()=>{}}} as unknown as Context
+ const root=document.createElement('div');document.body.append(root)
+ const app=mount(root,ctx)
+ return {root,close(){app.unmount();root.remove()}}
+}
+test('the status page and its errors follow the DSM language',async()=>{
+ const copy=appCopy('ger')
+ const {root,close}=start('de',async method=>{
+  if(method==='app.status')return {package:'Pkg',version:'1',user:'admin',admin:true}
+  if(method==='greeting.get')throw {code:'admin_required'}
+  throw {code:'unknown_method'}
+ })
+ try{
+  await settle()
+  expect(buttons(root)).toContain(copy.refresh)
+  expect(root.textContent).toContain(copy.statusTitle)
+  expect(root.textContent).toContain(copy.greeting)
+  expect(root.textContent).toContain(copy.errors.admin_required)
+  expect(root.querySelector('[aria-label]')?.getAttribute('aria-label')).not.toBe('Package settings')
+ }finally{close()}
+})
+test('unknown failures name the code in the DSM language',()=>{
+ expect(appCopy('ja').errors.request_failed).toContain('{code}')
+})
+test('the sign-in page and its session notices follow the DSM language',async()=>{
+ const copy=identityCopy('jpn')
+ const {root,close}=start('ja',async method=>{
+  if(method==='identity.status')return {enabled:true}
+  if(method==='identity.session')return {user:'alice',uid:'1',expiresAt:new Date(Date.now()-1000).toISOString()}
+  throw {code:'session_required'}
+ })
+ try{
+  await settle()
+  expect(root.textContent).toContain(copy.title)
+  expect(buttons(root)).toEqual(expect.arrayContaining([copy.signIn,copy.continueDSM]))
+  expect(root.querySelector('[role="status"]')?.textContent).toBe(copy.notices.expired)
+  expect(root.textContent).not.toMatch(/Sign in|Account|Password|session/)
+ }finally{close()}
+})

package/dist/validate.js

@@ -6,6 +6,7 @@ import { validateContract } from "./contract/validate.js";
 import { findListingUnsupportedInstallTypes } from "./contract/unsupported-types.js";
 import { classifyComposeRoute, collectComposeInterpolations, collectVolumeSourceInterpolations, loadCompose, validateAdminPortMapping, validateComposeHostBinds, validateComposeNumericCommandArgs, validateComposeRunAs, validateComposeSecurity, validateGatewayPortLoopback, } from "./compose/analyze.js";
 import { usesAuthGateway } from "./contract/web-launch.js";
+import { isNativeLayout, loadNativeLayout } from "./standalone/native-layout.js";
 import { loadStandaloneManifest } from "./standalone/manifest.js";
 import { COMPOSE_FILENAME, CONTRACT_FILENAME, DSM_PACKAGE_FILENAME, } from "./discovery.js";
 import { declaredPrivilegeFlags } from "./compose/privilege.js";
@@ -26,7 +27,7 @@ export function validateProject(project, options = {}) {
                 }] };
     }
     if (hasStandalone) {
-        const loaded = loadStandaloneManifest(project.root);
+        const loaded = isNativeLayout(project.root) ? loadNativeLayout(project.root) : loadStandaloneManifest(project.root);
         return loaded.ok ? { ok: true, errors: [] } : { ok: false, errors: loaded.errors.map(error => ({
                 ...error, span: { file: DSM_PACKAGE_FILENAME, line: 1, column: 1 },
                 suggestion: "請修正 dsm-package.yaml 的 schema 2 欄位與能力宣告。",

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@synopackageland/cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Syno Package Land Developer Kit CLI",
   "type": "module",
   "bin": {
     "synopkgland": "./dist/bin.js"
   },
+  "engines": {
+    "node": ">=22.12"
+  },
   "files": [
     "dist",
+    "CHANGELOG.md",
     "templates",
     "schema",
     "skills"
@@ -32,5 +36,11 @@
     "access": "public",
     "registry": "https://registry.npmjs.org"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "exports": {
+    "./authorization-sdk": "./dist/authorization-sdk.js",
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json",
+    "./native-layout": "./dist/standalone/native-layout.js"
+  }
 }

package/schema/package-metadata.schema.json

@@ -0,0 +1,101 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "changelog": {
+      "oneOf": [
+        {
+          "type": "string",
+          "maxLength": 16000
+        },
+        {
+          "type": "object",
+          "maxProperties": 32,
+          "additionalProperties": {
+            "type": "string",
+            "maxLength": 16000
+          }
+        }
+      ]
+    },
+    "contact_email": {
+      "type": "string",
+      "maxLength": 16000,
+      "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
+    },
+    "support_email": {
+      "type": "string",
+      "maxLength": 16000,
+      "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
+    },
+    "homepage": {
+      "type": "string",
+      "maxLength": 16000,
+      "pattern": "^https?://"
+    },
+    "source_url": {
+      "type": "string",
+      "maxLength": 16000,
+      "pattern": "^https?://"
+    },
+    "issues_url": {
+      "type": "string",
+      "maxLength": 16000,
+      "pattern": "^https?://"
+    },
+    "license": {
+      "type": "string",
+      "maxLength": 16000
+    },
+    "maintainer_url": {
+      "type": "string",
+      "maxLength": 16000,
+      "pattern": "^https?://"
+    },
+    "distributor": {
+      "type": "string",
+      "maxLength": 16000
+    },
+    "distributor_url": {
+      "type": "string",
+      "maxLength": 16000,
+      "pattern": "^https?://"
+    },
+    "support_url": {
+      "type": "string",
+      "maxLength": 16000,
+      "pattern": "^(https?://|mailto:)"
+    },
+    "helpurl": {
+      "type": "string",
+      "maxLength": 16000,
+      "pattern": "^https?://"
+    },
+    "long_description": {
+      "oneOf": [
+        {
+          "type": "string",
+          "maxLength": 16000
+        },
+        {
+          "type": "object",
+          "maxProperties": 32,
+          "additionalProperties": {
+            "type": "string",
+            "maxLength": 16000
+          }
+        }
+      ]
+    },
+    "screenshots": {
+      "type": "array",
+      "maxItems": 12,
+      "items": {
+        "type": "string",
+        "pattern": "^https?://",
+        "maxLength": 2048
+      }
+    }
+  }
+}

package/schema/synology-app.schema.json

@@ -118,6 +118,18 @@
                 "pattern": "^(?:[A-Za-z0-9._-]{1,64}|[A-Za-z0-9._-]{1,64}\\\\[A-Za-z0-9._-](?:[A-Za-z0-9._ -]{0,126}[A-Za-z0-9._-])?|[A-Za-z0-9._-](?:[A-Za-z0-9._ -]{0,126}[A-Za-z0-9._-])?@[A-Za-z0-9._-]{1,64})$(?![\\s\\S])"
               },
               "description": "DSM group names allowed in; only with access: dsm-groups."
+            },
+            "portal": {
+              "type": "object",
+              "properties": {
+                "alias": {
+                  "type": "string",
+                  "pattern": "^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$",
+                  "description": "Default DSM Application Portal alias (https://<nas>/<alias>/). Omit to use the package name. An administrator still applies it."
+                }
+              },
+              "additionalProperties": false,
+              "description": "Register the App in DSM Control Panel > Login Portal > Applications. Needs launch: dsm-window behind the DSM gateway (access other than public) and os_min_ver 7.3.2-86009 or later. Registration alone exposes nothing."
             }
           },
           "additionalProperties": true
@@ -149,6 +161,106 @@
           "type": "boolean"
         }
       }
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "changelog": {
+          "oneOf": [
+            {
+              "type": "string",
+              "maxLength": 16000
+            },
+            {
+              "type": "object",
+              "maxProperties": 32,
+              "additionalProperties": {
+                "type": "string",
+                "maxLength": 16000
+              }
+            }
+          ]
+        },
+        "contact_email": {
+          "type": "string",
+          "maxLength": 16000,
+          "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
+        },
+        "support_email": {
+          "type": "string",
+          "maxLength": 16000,
+          "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
+        },
+        "homepage": {
+          "type": "string",
+          "maxLength": 16000,
+          "pattern": "^https?://"
+        },
+        "source_url": {
+          "type": "string",
+          "maxLength": 16000,
+          "pattern": "^https?://"
+        },
+        "issues_url": {
+          "type": "string",
+          "maxLength": 16000,
+          "pattern": "^https?://"
+        },
+        "license": {
+          "type": "string",
+          "maxLength": 16000
+        },
+        "maintainer_url": {
+          "type": "string",
+          "maxLength": 16000,
+          "pattern": "^https?://"
+        },
+        "distributor": {
+          "type": "string",
+          "maxLength": 16000
+        },
+        "distributor_url": {
+          "type": "string",
+          "maxLength": 16000,
+          "pattern": "^https?://"
+        },
+        "support_url": {
+          "type": "string",
+          "maxLength": 16000,
+          "pattern": "^(https?://|mailto:)"
+        },
+        "helpurl": {
+          "type": "string",
+          "maxLength": 16000,
+          "pattern": "^https?://"
+        },
+        "long_description": {
+          "oneOf": [
+            {
+              "type": "string",
+              "maxLength": 16000
+            },
+            {
+              "type": "object",
+              "maxProperties": 32,
+              "additionalProperties": {
+                "type": "string",
+                "maxLength": 16000
+              }
+            }
+          ]
+        },
+        "screenshots": {
+          "type": "array",
+          "maxItems": 12,
+          "items": {
+            "type": "string",
+            "pattern": "^https?://",
+            "maxLength": 2048
+          }
+        }
+      }
     }
   },
   "additionalProperties": true

package/skills/SKILL.md

@@ -5,15 +5,15 @@ description: Initialize, extend, check, build, inspect, and deploy Synology appl
 
 # Independent Synology SPKs
 
-Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 為 P2 整合中，禁止發明已完成的離線委託或新身分平台。
+Use this guide to initialize, build and inspect own applications or upstream OSS as independent packages. 依已實作能力區分 DSM session 檔案、私有 jobs 與 App 登入；delegate 已實作並隨 CLI 提供固定操作的離線委託（預設 `files.moveFromStaging`）；共用 delegate／rootOps executor 的完整裝置生命週期驗收仍待完成，不得宣稱已通過；支援邊界依 delegate guide／support matrix，禁止發明新的身分平台。
 
 Start with `synopkgland init -t native-go`, `synopkgland init -t binary`, or `synopkgland init -t compose`. Read reference/create.md or reference/wrap.md, then reference/deploy.md. Native CGI session checks belong to the package. Container authentication belongs to upstream; fixed service credentials govern mounted data access.
 
 Never install, uninstall, publish or modify NAS data without task authorization. Prefer check, inspect and deploy --dry-run for reviewable artifacts.
 
-Native projects use schema 2 capabilities and `--with files,jobs,login,root-ops`; 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.
+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.
 
-Read reference/files.md and reference/identity.md for capability boundaries. RootOps currently uses individual administrator task approval; P2 will share one-time protected executor setup with delegate. App sessions alone do not grant NAS file authority.
+Read reference/portal.md before declaring or changing a DSM Application Portal alias (`add portal`); DSM owns the saved setting. 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 authorization-sdk build-time adapter; do not mix its tasks with generated executor capabilities. App sessions alone do not grant NAS file authority.
 
 Read [reference/ui-vue.md](reference/ui-vue.md) when editing Vue components in the native-go Vue template; use the installed SDK contracts, keep DSM embedding boundaries, and verify the actual app.
 
@@ -23,3 +23,109 @@ For UI discovery, run `npx --no syno-pkg-land-ui catalog --json` and
 `npx --no syno-pkg-land-ui describe Button --json` from the installed frontend.
 Read its prompt and exported Vue docs/types before choosing component APIs.
 Use `syno-pkg-land-ui` directly in npm scripts; keep AI guidance version-independent.
+
+For existing native products, schema 2 `backend: {kind: native}` preserves project-owned payload/metadata, prepare/compile argv hooks and pinned toolkits. See the native-layout guide; run `check`, `build`, then `inspect <spk>` locally. Keep lifecycle/systemd as the package account and preserve product-owned digest approval/revocation. Native layouts do not opt into generated Go capabilities.
+
+
+## Permanent destination integration
+
+`init --with delegate` / `add delegate` default to `operations: [files.moveFromStaging]`,
+`destinations: [save]`, `lifetime: until-revoked`, `scope: install-selected`. Existing legacy
+TTL declarations retain their 1–3600 second service / 30-day wire ceiling and
+64 MiB / 60-second URL example. Do not apply those limits to the new move API.
+Delegate can coexist with daemon; ordinary standalone jobs cannot. Preserve
+App business route floors. Binary/compose remain unsupported.
+
+Use File Station `/home[/...]`, never `/homes/<user>`. The SDK destination picker
+selection itself grants access after fresh DSM session/UID/write verification,
+without a second consent dialog. Ordinary and administrator subjects use their
+own nonzero UID/current groups, never root. An online App can create an in-scope
+grant using a valid session; there is no trusted external consent or notification.
+
+Use the default `createBackgroundSaveFacade(ctx)` / CapabilityPanels management
+page. `delegate.status` exposes verified `disabled` and manifest mode; missing
+protected evidence must not imply enabled. `delegate.operations.list` accepts
+only `{}`, uses the backend move mirrors, and returns the caller's username+UID
+operations only, including for admins. Mirrors are not completion receipts:
+query original `delegate.operations.get` and show Saved only for committed with
+a receipt. Cancel by the same reference; revoke by grant ID. Never resubmit
+uncertain/interrupted work. Admin disable is protected and revokes grants;
+enable/mailbox start does not resurrect them. Keep IDs, never session credentials.
+
+App-owned daemon completion and scheduled CSV export call configured Go
+`Service.MoveFromStaging` with `delegation_id`, stable `job_id`, private relative
+`staging`, `name`, `size`. No owner/UID selector. Bounds: 16 GiB/file, queued16,
+active1/package, 24-hour attempt, 5-second revalidation ticks (one check at a time, 30-second complete-check deadline; proven timeouts retain private copying, publication still revalidates), 10 MiB operation records,
+50 MiB audit. Scope is a usage restriction, not hard subtree confinement.
+Local production-executor fixtures use fake DSM/peer/bulk writer; do not claim
+NAS ACL, actual writer UID, logout/reboot or full lifecycle acceptance from them.
+Gopeed product wiring remains a separate task.
+
+Admission recovery (per job): on `EXECUTOR_UNAVAILABLE`, `EXECUTOR_TIMEOUT`,
+`EXECUTOR_PROTOCOL`, `canceled`, `EXECUTOR_PAUSED`, `queue-full`,
+`STORAGE_ERROR`, `ADMISSION_PENDING`, `jobs_busy` or `jobs_unavailable` (the
+package journal was busy or failed transiently; a caller deadline or cancel
+spent waiting for it is `canceled`), call `MoveFromStaging` again later with
+the same exact params. It queries the original reference first and re-sends
+admission only when the executor does not know it and the pinned source is
+unchanged; executor tuple deduplication keeps one operation, so a lost reply or a
+racing caller never copies twice. At most 10 possibly-delivered sends, 2 s
+backoff doubling to 5 min; the worker sweep does the same. Terminal, do not
+retry: `APP_DENIED`, `DELEGATION_DENIED`, `operation-conflict`, `disabled`,
+`SCOPE_DENIED` and other executor refusals, `STAGING_CHANGED`,
+`ADMISSION_EXHAUSTED`, `spool_unsafe` and `journal_corrupt` (repair the package
+spool first), and `operation-not-found` for an accepted operation.
+Never change job/grant IDs, delete mirrors or call the socket directly to retry.
+
+Cancellation (per job): `CancelOperation` / `delegate.operations.cancel` with the
+original ref is idempotent; repeat it with the same ref after any retryable
+error or a lost reply. A reply `queued`→`canceled` is final at once. A copy in
+flight answers `copying` with code `CANCEL_REQUESTED`: the cancel is accepted and
+durable, not finished; poll `OperationStatus` on the same ref until terminal
+(repeating the cancel is harmless). `canceled` (`OPERATION_CANCELED`) guarantees the writer
+stopped, its part file is removed, nothing was published and staging is kept; it
+stays canceled across executor crash, package stop/start and logout. Revoke, scope change and disable store their reason (`grant-revoked`,
+`scope-changed`, `integration-disabled`) the same way: a copy in flight answers
+`CANCEL_REQUESTED` with it and settles `canceled` with it across a restart. A
+copy the executor stops without a cancel ends `interrupted`/`EXECUTOR_PAUSED`
+(`interrupted`/`interrupted` after a crash), never `WRITE_FAILED`. `committed`
+means publication won the race: the file stays (cancel never removes it) and only
+the app record may be dropped. `uncertain` means a publish attempt failed before
+the cancel; keep querying. A cancel of a ref the executor has not admitted yet
+(reserved/sent mirror) returns `canceled` and leaves a tombstone, so a late or
+recovered admission of that ref returns `canceled` and never copies; a producer
+cancel is also written to the mirror first, so `MoveFromStaging` and the worker
+sweep forward the cancel instead of admitting it.
+
+
+### Install-selected scope and the destination API
+
+- The DSM install wizard dynamically lists local shares (`SYNO.Core.Share list`
+  via `api_store`) and offers home. It saves only a package-owned pre-selection
+  in `var/delegate-install.json`; never trust that file for authority.
+- The existing administrator PasswordConfirm form displays this pre-selection
+  at first enable. `ctx.executor.authorize(password, selectedScope)` confirms it
+  through a pinned, exact-readback one-time root task. Settings changes use the
+  same form/password path; no App CGI route may set protected scope directly.
+- The executor trusts `/usr/local/etc/synopkgland/<pkg>/delegations/selected-scope.record`
+  only. Its scope/generation are runtime protected state; shipped policy pins
+  lock the selection mode and operations. Changes revoke old grants and cancel
+  pending writes. Change-away-and-back never revives an old grant.
+- Follow `selection` from verified `delegate.status` / `sdk.destination(key)`.
+  If the draft differs, display the difference and follow the protected value.
+  Home and fixed `shared:<name>` manifests stay compatible.
+- Frontend: `const sdk = createBackgroundSaveFacade(ctx); const current = await
+  sdk.destination('save')` returns typed `{key, selection, destination, status}`.
+  `selection` contains `{scope, root, generation}`; `destination` is this caller's
+  grant or null. Handle active/missing/reselection-required/needs-scope-confirmation/disabled.
+- Go: `Service.Destination(ctx, caller, request, key)` verifies the fresh DSM
+  session and username+UID. Capture its active grant ID into the App job. The
+  offline producer uses existing `Service.MoveFromStaging`; no user/UID selector,
+  cookie, token, or browser path cache. Executor revalidates at use/publication.
+- The generated Background saves page includes a working **Save example file**
+  (`sdk.exportExample({key, job_id})`, `delegate.example.export`). Go
+  `ExportExample` creates a private JSON file, calls `MoveFromStaging` once, and
+  repeats the original request on repeated IDs. Review `example.go` to
+  adapt a real producer; show Saved only from a protected committed receipt.
+- Wizard support is measured on vt-nas DSM 7.4 via a session-only SSH local
+  forward. This is not proof of other DSM releases or full writer/reboot behavior.