@hanamesh/dsh-app-host 0.2.0-rc.2 → 0.6.12

package/dist/library/node-binding.js

@@ -0,0 +1,11 @@
+/** Each operation captures one delegate; consecutive operations share its writer until the binding changes. */
+export function nodeBinding(current,make){
+ const cache=new Map();
+ const delegate=()=>{const node=current();if(!cache.has(node))cache.set(node,make(node));return cache.get(node);};
+ return new Proxy({}, {get(_target,key){const value=delegate()[key];return typeof value==='function'?value.bind(delegate()):value;}});
+}
+export function nodeStatusBinding(current,make){
+ const cache=new Map();
+ const read=(...args)=>{const node=current();if(!cache.has(node))cache.set(node,make(node));return cache.get(node)(...args);};
+ read.close=async()=>{for(const reader of cache.values())await reader.close?.();cache.clear();};return read;
+}

package/dist/library/recovery.js

@@ -0,0 +1,66 @@
+/**
+ * rc.10 install recovery: what one market install changed in the profile and in the application runtime root, and the
+ * item-by-item readback that decides whether a compensation really restored the state before the operation.
+ * Nothing here writes profile files: package changes go back through the official `dsh plugin` command only.
+ */
+import { readFile, mkdir, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { join } from 'node:path';
+
+const DEPENDENCY_FIELDS=['devDependencies','dependencies','optionalDependencies'];
+const EXACT=/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+const digest=bytes=>bytes===null?null:createHash('sha256').update(bytes).digest('hex');
+const same=(a,b)=>JSON.stringify(a)===JSON.stringify(b);
+async function optional(path){try{return await readFile(path);}catch(error){if(error.code==='ENOENT')return null;throw error;}}
+
+/** The profile facts one package operation can change: its direct spec, bundle selection, lockfile and resolved module. */
+export async function profileSnapshot(profileDir,name){
+  const manifestBytes=await optional(join(profileDir,'package.json')),lockBytes=await optional(join(profileDir,'pnpm-lock.yaml'));
+  const manifest=manifestBytes===null?{}:JSON.parse(manifestBytes.toString('utf8'));
+  const direct=Object.assign({},...DEPENDENCY_FIELDS.map(field=>manifest[field]??{}));
+  const moduleBytes=await optional(join(profileDir,'node_modules',...name.split('/'),'package.json'));
+  return{manifestBytes,lockBytes,spec:direct[name]??null,others:Object.fromEntries(Object.entries(direct).filter(([key])=>key!==name)),
+    bundles:manifest.dsh?.profile?.bundles??[],lock:digest(lockBytes),module:moduleBytes===null?null:JSON.parse(moduleBytes.toString('utf8')).version??null};
+}
+
+/** Ledger entries of one runtime root, without the install timestamp (a re-provision of the same bytes is the same state). */
+export async function runtimeSnapshot(readLedger,root){
+  const ledger=await readLedger(root);
+  return Object.fromEntries(Object.entries(ledger?.items??{}).map(([id,entry])=>[id,{version:entry.version,sha256:entry.sha256,platform:entry.platform,installTo:entry.installTo}]));
+}
+
+/** Names of other direct dependencies that changed while this operation ran: a concurrent profile writer, never ours to undo. */
+export const concurrentChanges=(base,now)=>[...new Set([...Object.keys(base.others),...Object.keys(now.others)])].filter(key=>base.others[key]!==now.others[key]).sort();
+
+/** Item-by-item comparison of the profile with its baseline; every row carries expected, actual and ok. */
+export function profileChecks(base,now,name){
+  const concurrent=concurrentChanges(base,now);
+  const rows=[
+    {item:'dependency',expected:base.spec,actual:now.spec},
+    {item:'module',expected:base.module,actual:now.module},
+    {item:'bundle',expected:base.bundles.includes(name),actual:now.bundles.includes(name)},
+  ].map(row=>({...row,ok:same(row.expected,row.actual)}));
+  if(concurrent.length)rows.push({item:'lockfile',expected:base.lock,actual:now.lock,ok:false,reason:'CONCURRENT_PROFILE_WRITE',concurrent});
+  else rows.push({item:'lockfile',expected:base.lock,actual:now.lock,ok:base.lock===now.lock},{item:'bundles',expected:base.bundles,actual:now.bundles,ok:same(base.bundles,now.bundles)});
+  return rows;
+}
+
+export function runtimeChecks(base,now){
+  return [...new Set([...Object.keys(base),...Object.keys(now)])].sort().map(id=>({item:'runtime:'+id,expected:base[id]??null,actual:now[id]??null,ok:same(base[id]??null,now[id]??null)}));
+}
+
+/** The official CLI arguments that put one package back to its baseline spec, or none when nothing package-side changed. */
+export function packageRestoreArgs(base,now,name){
+  if(profileChecks(base,now,name).every(row=>row.ok||row.reason==='CONCURRENT_PROFILE_WRITE'))return null;
+  if(base.spec===null)return now.spec===null?['install']:['remove',name];
+  return['add',...(EXACT.test(base.spec)?['--save-exact']:[]),`${name}@${base.spec}`];
+}
+
+/** Keeps the pre-operation profile files and runtime ledger where the user (or a later operation) can restore them by hand. */
+export async function keepOriginals(dir,base,runtimeBase){
+  await mkdir(dir,{recursive:true,mode:0o700});const files=[];
+  if(base.manifestBytes!==null){await writeFile(join(dir,'package.json'),base.manifestBytes,{mode:0o600});files.push('package.json');}
+  if(base.lockBytes!==null){await writeFile(join(dir,'pnpm-lock.yaml'),base.lockBytes,{mode:0o600});files.push('pnpm-lock.yaml');}
+  if(runtimeBase){await writeFile(join(dir,'runtime-ledger.json'),JSON.stringify(runtimeBase,undefined,2)+'\n',{mode:0o600});files.push('runtime-ledger.json');}
+  return{dir,files,sha256:{...(base.manifestBytes===null?{}:{'package.json':digest(base.manifestBytes)}),...(base.lockBytes===null?{}:{'pnpm-lock.yaml':digest(base.lockBytes)})}};
+}

package/dist/library/routes.js

@@ -1,17 +1,93 @@
+import { installationStatusCors, serveInstallationStatus } from './installation-status-http.js';
 import { randomUUID } from 'node:crypto';
 import { AppHostError, requireCondition } from '../errors.js';
-import { loopbackOrigin } from '../descriptor.js';
+import { controlOrigins } from '../control-origin.js';
+import { HANDOFF_DEFAULTS, HANDOFF_RULES, HANDOFF_SETTING_NAMES, HANDOFF_BODY_MAX_BYTES } from './handoff.js';
 
-/** rc.28 adds `installedPlugins` (GET) and `plugins/install` / `plugins/uninstall` (POST, by package name); every older route is kept. */
-export const LIBRARY_ROUTES=['/hanamesh/library','/hanamesh/library/sources','/hanamesh/library/install','/hanamesh/library/provision','/hanamesh/library/uninstall','/hanamesh/library/events','/hanamesh/library/installedPlugins','/hanamesh/library/plugins/install','/hanamesh/library/plugins/uninstall'];
-async function jsonBody(req){const chunks=[];let total=0;for await(const chunk of req){total+=chunk.length;requireCondition(total<=65_536,'BODY_TOO_LARGE','Request body is too large.',{},413);chunks.push(chunk);}try{return JSON.parse(Buffer.concat(chunks).toString('utf8'));}catch{throw new AppHostError('INVALID_JSON','Malformed JSON.',{},400);}}
-function send(res,status,value){res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store','x-content-type-options':'nosniff','content-security-policy':"default-src 'none'; frame-ancestors 'none'"});res.end(JSON.stringify(value));}
-export function createLibraryHttpHandler(library,{parentOrigin,authenticate,authorize}){parentOrigin=loopbackOrigin(parentOrigin);return async(req,res)=>{const traceId=randomUUID();try{
-  requireCondition(req.headers.host===new URL(parentOrigin).host,'HOST_DENIED','Unrecognized request host.',{},403);const url=new URL(req.url,parentOrigin),path=url.pathname;requireCondition(LIBRARY_ROUTES.includes(path),'NOT_FOUND','Unknown library route.',{},404);
-  const readOnly=req.method==='GET'&&['/hanamesh/library','/hanamesh/library/sources','/hanamesh/library/events','/hanamesh/library/installedPlugins'].includes(path);requireCondition(readOnly||(req.method==='POST'&&path!=='/hanamesh/library/installedPlugins'),'METHOD_NOT_ALLOWED','Unsupported library method.',{},405);
-  requireCondition(!req.headers.origin||req.headers.origin===parentOrigin,'ORIGIN_DENIED','Unapproved browser origin.',{},403);requireCondition(req.headers['sec-fetch-dest']!=='iframe','FRAME_CONTROL_DENIED','An application frame cannot control the host.',{},403);
-  if(!readOnly)requireCondition(req.headers.origin===parentOrigin&&req.headers['x-hanamesh-client']==='workspace-v1','CSRF_DENIED','Workspace origin and explicit client header are required.',{},403);
-  const subject=await authenticate(req);requireCondition(subject&&typeof subject.principalId==='string','UNAUTHENTICATED','Host authentication is required.',{},401);const input=readOnly?Object.fromEntries(url.searchParams):await jsonBody(req);requireCondition(await authorize(subject,path,input)===true,'FORBIDDEN','Operation is not authorized.',{},403);
-  let result;if(path==='/hanamesh/library'&&readOnly){requireCondition(Object.keys(input).every(key=>['q','category','cursor'].includes(key)),'UNKNOWN_FIELDS','Unknown library parameters.');result=await library.list(input);}else if(path==='/hanamesh/library/sources'&&readOnly)result=library.sources();else if(path==='/hanamesh/library/sources')result=await library.replaceSources(input);else if(path==='/hanamesh/library/install')result=await library.install(input);else if(path==='/hanamesh/library/provision')result=await library.provision(input);else if(path==='/hanamesh/library/uninstall')result=await library.uninstall(input);else if(path==='/hanamesh/library/installedPlugins'){requireCondition(Object.keys(input).length===0,'UNKNOWN_FIELDS','installedPlugins takes no parameters.');result=await library.installedSnapshot();}else if(path==='/hanamesh/library/plugins/install')result=await library.installPlugin(input);else if(path==='/hanamesh/library/plugins/uninstall')result=await library.uninstallPlugin(input);else{requireCondition(Object.keys(input).every(key=>key==='after'),'UNKNOWN_FIELDS','Unknown event parameters.');result=library.events(Number(input.after??0));}
-  send(res,!readOnly&&path!=='/hanamesh/library/sources'?202:200,{...result,traceId});
-}catch(error){const trusted=error instanceof AppHostError;send(res,trusted?error.status:500,{error:{code:trusted?error.code:'INTERNAL_ERROR',message:trusted?error.message:'The operation could not be completed.',...(trusted?{details:error.details}:{})},traceId});}};}
+// Keep older route order; dsh.js registers each exact path on the public host API.
+export const LIBRARY_ROUTES=['/hanamesh/library','/hanamesh/library/sources','/hanamesh/library/install','/hanamesh/library/provision','/hanamesh/library/uninstall','/hanamesh/library/events','/hanamesh/library/installedPlugins','/hanamesh/library/plugins/install','/hanamesh/library/plugins/uninstall','/hanamesh/library/target','/hanamesh/library/install-target','/hanamesh/library/handoffs','/hanamesh/library/handoffs/state','/hanamesh/library/handoff-settings','/hanamesh/library/suite/upgrade','/hanamesh/library/installation-status'];
+export const NODE_RUNTIME_ROUTES=['/hanamesh/library/node-runtime','/hanamesh/library/node-runtime/settings','/hanamesh/library/node-runtime/plan','/hanamesh/library/node-runtime/prepare','/hanamesh/library/node-runtime/cancel'];
+LIBRARY_ROUTES.push(...NODE_RUNTIME_ROUTES,'/hanamesh/library/suite-source');
+const READ_ROUTES=new Set(['/hanamesh/library/suite-source','/hanamesh/library/node-runtime','/hanamesh/library','/hanamesh/library/sources','/hanamesh/library/events','/hanamesh/library/installedPlugins','/hanamesh/library/target','/hanamesh/library/handoffs','/hanamesh/library/handoff-settings']);
+async function jsonBody(req){
+  requireCondition(req.headers['content-type']?.split(';')[0].trim()==='application/json','CONTENT_TYPE_REQUIRED','Expected application/json.',{},415);
+  const chunks=[];let total=0;for await(const chunk of req){total+=chunk.length;requireCondition(total<=65_536,'BODY_TOO_LARGE','Request body is too large.',{},413);chunks.push(chunk);}
+  try{return JSON.parse(Buffer.concat(chunks).toString('utf8'));}catch{throw new AppHostError('INVALID_JSON','Malformed JSON.',{},400);}
+}
+function send(res,status,value,headers={}){
+  res.writeHead(status,{'content-type':'application/json; charset=utf-8','cache-control':'no-store','x-content-type-options':'nosniff','content-security-policy':"default-src 'none'; frame-ancestors 'none'",...headers});res.end(JSON.stringify(value));
+}
+/** `handoff` (optional): {queue, listener, restart} of the website handoff (handoff.js); the client window reads and reports through these authenticated routes. */
+export function createLibraryHttpHandler(library,{parentOrigin,transportOrigin,authenticate,authorize,handoff,nodeRuntime}){
+  const origins=controlOrigins(parentOrigin,transportOrigin);parentOrigin=origins.parent;
+  requireCondition(typeof authenticate==='function'&&typeof authorize==='function','AUTH_BINDING_REQUIRED','Host authentication and per-operation authorization callbacks are mandatory.');
+  const parent=new URL(origins.transport),hosts=new Set(origins.forwarded?[parent.host]:[parent.host,`localhost:${parent.port}`]);
+  return async(req,res)=>{const traceId=randomUUID();let cors={};try{
+    requireCondition(hosts.has(req.headers.host),'HOST_DENIED','Unrecognized request host.',{},403);
+    requireCondition(req.url?.startsWith('/')&&!req.url.startsWith('//')&&!req.url.includes('\\'),'BAD_TARGET','Invalid request target.');
+    const requestOrigin=`${parent.protocol}//${req.headers.host}`,url=new URL(req.url,requestOrigin),path=url.pathname;
+    requireCondition(LIBRARY_ROUTES.includes(path),'NOT_FOUND','Unknown library route.',{},404);
+    requireCondition(req.headers['sec-fetch-dest']!=='iframe','FRAME_CONTROL_DENIED','An application frame cannot control the host.',{},403);
+    if(path==='/hanamesh/library/installation-status'){
+      cors=installationStatusCors(req,[requestOrigin,origins.parent,...library.handoffSettings().allowedOrigins]);
+      await serveInstallationStatus(req,res,{read:library.installationStatus,maxBodyBytes:HANDOFF_BODY_MAX_BYTES,traceId,cors,send});return;
+    }
+    if(path==='/hanamesh/library/install-target'){
+      // Match the website handoff policy; same-origin workspace and non-browser local reads remain available.
+      const origin=req.headers.origin;
+      if(origin!==undefined){
+        requireCondition(origin===requestOrigin||origins.acceptsOrigin(origin)||library.handoffSettings().allowedOrigins.includes(origin),'ORIGIN_DENIED','Not available.',undefined,403);
+        cors={'access-control-allow-origin':origin,vary:'Origin','access-control-allow-private-network':'true'};
+      }
+      if(req.method==='OPTIONS'){send(res,204,undefined,{...cors,'access-control-allow-methods':'GET'});return;}
+      requireCondition(req.method==='GET','METHOD_NOT_ALLOWED','Discovery requires GET.',{},405);
+      requireCondition(!url.search,'UNKNOWN_FIELDS','Discovery takes no parameters.');
+      send(res,200,{...library.installTarget(),traceId},cors);return;
+    }
+    const readOnly=req.method==='GET'&&READ_ROUTES.has(path);
+    requireCondition(readOnly||(req.method==='POST'&&!['/hanamesh/library/installedPlugins','/hanamesh/library/target','/hanamesh/library/handoffs'].includes(path)),'METHOD_NOT_ALLOWED','Unsupported library method.',{},405);
+    requireCondition(!req.headers.origin||(origins.forwarded?origins.acceptsOrigin(req.headers.origin):req.headers.origin===requestOrigin),'ORIGIN_DENIED','Unapproved browser origin.',{},403);
+    if(!readOnly)requireCondition((origins.forwarded?origins.acceptsOrigin(req.headers.origin):req.headers.origin===requestOrigin)&&req.headers['x-hanamesh-client']==='workspace-v1','CSRF_DENIED','Workspace origin and explicit client header are required.',{},403);
+    const subject=await authenticate(req);
+    requireCondition(subject&&typeof subject.principalId==='string','UNAUTHENTICATED','Host authentication is required.',{},401);
+    if(readOnly)requireCondition(new Set(url.searchParams.keys()).size===[...url.searchParams.keys()].length,'INVALID_INPUT','Duplicate query fields are not accepted.');
+    const input=readOnly?Object.fromEntries(url.searchParams):await jsonBody(req);
+    requireCondition(await authorize(subject,path,input)===true,'FORBIDDEN','Operation is not authorized.',{},403);
+    let result;
+    if(NODE_RUNTIME_ROUTES.includes(path)){
+      requireCondition(nodeRuntime,'NODE_RUNTIME_UNAVAILABLE','本插件尚未提供安装环境管理。',{},503);
+      requireCondition(!url.search,'UNKNOWN_FIELDS','安装环境请求不接受查询参数。');
+      try{if(path==='/hanamesh/library/node-runtime'){requireCondition(readOnly,'METHOD_NOT_ALLOWED','请使用读取操作。',{},405);result=nodeRuntime.status();}
+      else if(path.endsWith('/settings'))result=await nodeRuntime.save(input);
+      else if(path.endsWith('/plan'))result=await nodeRuntime.plan(input);
+      else if(path.endsWith('/prepare'))result=nodeRuntime.prepare(input);
+      else result=nodeRuntime.cancel(input);
+      }catch(error){if(error instanceof AppHostError)throw error;throw new AppHostError('NODE_ENVIRONMENT_FAILED','无法读取或保存安装环境：'+String(error?.message??error).slice(0,1500),{cause:error?.code??'NODE_CHECK_FAILED'},500);}
+      send(res,path.endsWith('/prepare')?202:200,{...result,traceId});return;
+    }
+    if(path==='/hanamesh/library/suite-source'){
+      requireCondition(!url.search,'UNKNOWN_FIELDS','套件安装包来源不接受查询参数。');
+      requireCondition(!readOnly||Object.keys(input).length===0,'UNKNOWN_FIELDS','套件安装包来源读取不接受参数。');
+      const result=readOnly?library.suiteSourceSettings():await library.replaceSuiteSourceSettings(input);
+      send(res,200,{...result,traceId});return;
+    }
+    if(path==='/hanamesh/library/suite/upgrade'){send(res,202,{...await library.upgradeSuite(input),traceId});return;}
+    if(path.startsWith('/hanamesh/library/handoff'))requireCondition(handoff,'HANDOFF_UNAVAILABLE','Website handoff is not wired in this host.',{},503);
+    if(path==='/hanamesh/library/handoffs'){requireCondition(Object.keys(input).length===0,'UNKNOWN_FIELDS','handoffs takes no parameters.');handoff.queue.clientPolled();result={handoffs:handoff.queue.open(),listener:handoff.listener.state(),pollMs:library.handoffSettings().pollMs,live:library.live,client:library.installTarget().client};}
+    else if(path==='/hanamesh/library/handoffs/state'){send(res,200,{...handoff.queue.report(input),traceId});return;}
+    else if(path==='/hanamesh/library/handoff-settings'&&readOnly){requireCondition(Object.keys(input).length===0,'UNKNOWN_FIELDS','handoff-settings takes no parameters.');result={settings:library.handoffSettings(),defaults:HANDOFF_DEFAULTS,names:HANDOFF_SETTING_NAMES,rules:HANDOFF_RULES,listener:handoff.listener.state()};}
+    else if(path==='/hanamesh/library/handoff-settings'){const settings=await library.replaceHandoffSettings(input);send(res,200,{settings,defaults:HANDOFF_DEFAULTS,names:HANDOFF_SETTING_NAMES,rules:HANDOFF_RULES,listener:await handoff.restart(),traceId});return;}
+    else if(path==='/hanamesh/library/target')result=await library.resolveTarget(input);
+    else if(path==='/hanamesh/library'&&readOnly){requireCondition(Object.keys(input).every(key=>['q','category','cursor'].includes(key)),'UNKNOWN_FIELDS','Unknown library parameters.');result=await library.list(input);}
+    else if(path==='/hanamesh/library/sources'&&readOnly)result=library.sources();
+    else if(path==='/hanamesh/library/sources')result=await library.replaceSources(input);
+    else if(path==='/hanamesh/library/install')result=await library.install(input);
+    else if(path==='/hanamesh/library/provision')result=await library.provision(input);
+    else if(path==='/hanamesh/library/uninstall')result=await library.uninstall(input);
+    else if(path==='/hanamesh/library/installedPlugins'){requireCondition(Object.keys(input).length===0,'UNKNOWN_FIELDS','installedPlugins takes no parameters.');result=await library.installedSnapshot();}
+    else if(path==='/hanamesh/library/plugins/install')result=await library.installPlugin(input);
+    else if(path==='/hanamesh/library/plugins/uninstall')result=await library.uninstallPlugin(input);
+    else{requireCondition(Object.keys(input).every(key=>key==='after'),'UNKNOWN_FIELDS','Unknown event parameters.');result=library.events(Number(input.after??0));}
+    send(res,!readOnly&&path!=='/hanamesh/library/sources'&&result.status!=='already-installed'?202:200,{...result,traceId});
+  }catch(error){const trusted=error instanceof AppHostError;send(res,trusted?error.status:500,{error:{code:trusted?error.code:'INTERNAL_ERROR',message:trusted?error.message:'The operation could not be completed.',...(trusted?{details:error.details}:{})},traceId},cors);}};
+}

package/dist/library/service.js

@@ -1,56 +1,152 @@
 import { randomUUID } from 'node:crypto';
-import { AppHostError, requireCondition } from '../errors.js';
+import { AppHostError, requireCondition, SerialQueue } from '../errors.js';
 import { loadCatalog, isApplication, itemKind, upgradeAvailable, validateManifestUrl } from './catalog.js';
 import { scanInstalled, scanInstalledPlugins, snapshotProfileDependencies } from './installed.js';
+import {SUITE_TARGET,SUITE_PACKAGES,readSuiteStatus,SUITE_INSTALL_COMMAND,CORE_SUITE_DECLARATION_MISSING,readSuiteSourceState} from './suite.js';
 import { PROTECTED_PACKAGES } from './install.js';
+import { handoffSettings } from './handoff.js';
+import { INSTALLATION_STATUS_CAPABILITY } from '../installation-status.js';
 
+/** Install-target contract version this market implements (schemas/install-target.schema.json). */
+export const INSTALL_TARGET_CONTRACT_VERSION='1';
 const PACKAGE_NAME=/^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/;
 const text=(value,max)=>typeof value==='string'&&value.length>0&&value.length<=max;
 const RESTART_STATES=new Set(['installed-not-loaded','uninstalled-not-unloaded']);
 const protectedPackage=name=>PROTECTED_PACKAGES.includes(name);
+const present=row=>row&&['registered','installed','installed-not-loaded'].includes(row.state);
 
-export function createLibraryService({domain,host,config={},dataRoot,ledgerReader,installer}){
-  const events=[];let sequence=0;let state;const running=new Map();let bootDependencies;
-  const emit=event=>{const value={sequence:++sequence,at:Date.now(),...event};events.push(value);if(events.length>512)events.shift();return value;};
+/**
+ * `client`: which client this host is ('dsh' | 'hanamesh', see client-identity.js). `unavailable`: when there is no
+ * installer, the facts that are missing, in words a person can act on (`[{need, how}]`); probes and 503s carry them.
+ */
+export function createLibraryService({domain,host,config={},dataRoot,ledgerReader,installer,client='dsh',unavailable=()=>[],installationStatus,suiteSourceService=()=>undefined,logger}){
+  const warn=(message,...args)=>{if(typeof logger?.warn==='function')logger.warn(message,...args);else console.warn(message,...args);};
+  const ready=()=>typeof installer?.install==='function'&&installer.ready!==false;
+  let suiteStatus={status:'unknown',version:null,components:[]};
+  const suiteFacts=async()=>installer?.suiteFacts?await installer.suiteFacts():{...await readSuiteStatus(config.profileDir),status:'unknown',completeness:'unknown',blocked:[{code:'CORE_SUITE_DECLARATION_MISSING'}],suiteUpgradeUnavailable:CORE_SUITE_DECLARATION_MISSING};
+  const events=[];let sequence=0;let state;const running=new Map(),installing=new Map();let bootDependencies;
+  const eventRetention=config.eventRetention??512;
+  requireCondition(Number.isSafeInteger(eventRetention)&&eventRetention>0,'INVALID_INPUT','library.eventRetention must be a positive safe integer.');
+  const observers=new Set();
+  const emit=event=>{const value={sequence:++sequence,at:Date.now(),...event};events.push(value);if(events.length>eventRetention)events.shift();for(const observer of observers){try{observer(value);}catch(error){warn('hanamesh-app-host library: event observer failed (%s): %s',value.type,error?.message??error);}}return value;};
   // Real sources hold ~10k entries (2026-09-20: market.hanamesh.com 12,121). `/hanamesh/library` keeps its rc.16 default
   // (`category=hanamesh-app`, backward compatible); the rc.28 market page asks for `category=''` (everything) explicitly.
   const catalog=({q='',category='hanamesh-app',cursor}={})=>loadCatalog({fixture:config.fixture,sources:state.sources,fetchImpl:config.fetchImpl,query:q,category,cursor});
   async function installed(){return config.profileDir?await scanInstalled({profileDir:config.profileDir,host,ledgerReader,dataRoot}):[];}
   async function installedPlugins(){return config.profileDir?await scanInstalledPlugins({profileDir:config.profileDir,bootDependencies}):[];}
-  async function persist(next){next.revision=state.revision+1;await domain.global.set(next);state=next;}
-  async function operation(type,task){const operationId=randomUUID();emit({type:`library.${type}-started`,operationId});const work=Promise.resolve().then(task).then(result=>{emit({type:`library.${type}-done`,operationId,result});return result;},error=>{emit({type:`library.${type}-failed`,operationId,code:error.code??'LIBRARY_OPERATION_FAILED'});throw error;}).finally(()=>running.delete(operationId));running.set(operationId,work);work.catch(()=>{});return{operationId,status:'started'};}
-  const requireInstaller=(message)=>requireCondition(installer,'LIBRARY_INSTALL_UNAVAILABLE',message,{},503);
-  /** Find one catalog entry by id; a package name narrows the provider query (the catalog has no get-by-id, but `q=<package>` matches exactly). */
-  async function findItem({itemId,packageName}){
-    requireCondition(text(itemId,160),'INVALID_INPUT','itemId is required.');
+  const settingsWriter=new SerialQueue();
+  function persist(update){return settingsWriter.run(async()=>{const next={...update(state),revision:state.revision+1};await domain.global.set(next);state=next;});}
+  async function operation(type,task){const operationId=randomUUID();emit({type:`library.${type}-started`,operationId});const work=Promise.resolve().then(()=>task(operationId)).then(result=>{emit({type:`library.${type}-done`,operationId,result});return result;},error=>{emit({type:`library.${type}-failed`,operationId,code:error.code??'LIBRARY_OPERATION_FAILED',...(error.recovery?{recovery:error.recovery}:{}),...(error.details?.stage==='suite-upgrade'?{details:{stage:'suite-upgrade',actual:error.details.actual,command:SUITE_INSTALL_COMMAND}}:{})});throw error;}).finally(()=>running.delete(operationId));running.set(operationId,work);work.catch(()=>{});return{operationId,status:'started'};}
+  const requireInstaller=(message)=>requireCondition(ready(),'LIBRARY_INSTALL_UNAVAILABLE',message,{need:unavailable()},503);
+  /**
+   * The host itself loaded/unloaded a plugin (pluginManager `applied`): it no longer waits for a restart. When the profile
+   * cannot be read back, the result says so (`restartBaseline`) instead of the installed list silently showing 「需重启」.
+   */
+  let bootSnapshotError;
+  async function markLive(result){
+    if(result?.status!=='applied'||!config.profileDir)return result;
+    if(!bootDependencies)return{...result,restartBaseline:{updated:false,code:'BOOT_SNAPSHOT_UNREADABLE',cause:bootSnapshotError}};
+    let now;
+    try{now=await snapshotProfileDependencies(config.profileDir);}
+    catch(error){const code=error?.code??'PROFILE_READ_FAILED';warn('hanamesh-app-host library: profile read-back after live %s failed (%s)',result.packageName,code);return{...result,restartBaseline:{updated:false,code}};}
+    if(now[result.packageName])bootDependencies[result.packageName]=now[result.packageName];else delete bootDependencies[result.packageName];
+    return{...result,restartBaseline:{updated:true}};
+  }
+  async function resolveTarget(input){
+    requireCondition(input&&typeof input==='object'&&!Array.isArray(input),'INVALID_INPUT','Only itemId and packageName are accepted.');
+    // rc.8: optional install-target contract declaration. Absent keeps the v1 semantics; anything but '1' is refused explicitly, before field checks.
+    requireCondition(input.contractVersion===undefined||input.contractVersion===INSTALL_TARGET_CONTRACT_VERSION,'CONTRACT_VERSION_UNSUPPORTED','This market does not implement the requested install-target contract version.',{supported:[INSTALL_TARGET_CONTRACT_VERSION]});
+    requireCondition(Object.keys(input).every(key=>['itemId','packageName','contractVersion'].includes(key)),'INVALID_INPUT','Only itemId and packageName are accepted.');
+    const{itemId,packageName}=input;
+    if(itemId===SUITE_TARGET){
+      requireCondition(packageName===undefined,'INVALID_INPUT','套件升级不接受包名或任意替换参数。');
+      requireCondition(typeof installer?.prepareSuiteUpgrade==='function','SUITE_UPGRADE_UNAVAILABLE','当前客户端还不支持安全套件升级，请使用补齐命令。',{},503);
+      const plan=await installer.prepareSuiteUpgrade();
+      return{contractVersion:'1',source:{kind:'suite',manifestUrl:'https://github.com/yzsnstotz'},item:{id:SUITE_TARGET,displayName:'HanaMesh 套件',kind:'suite-upgrade',package:{registry:'npm',name:'hanamesh-core'},latestVersion:plan.components[0].to,installed:{state:'installed',version:suiteStatus.version},upgradeAvailable:plan.available,suiteUpgrade:plan}};
+    }
+    requireCondition(itemId!==undefined||packageName!==undefined,'INVALID_INPUT','itemId or packageName is required.');
+    requireCondition(itemId===undefined||(text(itemId,160)&&!/[\u0000-\u001f\u007f]/.test(itemId)),'INVALID_INPUT','itemId is invalid.');
     requireCondition(packageName===undefined||(text(packageName,214)&&PACKAGE_NAME.test(packageName)),'INVALID_INPUT','packageName is invalid.');
-    const page=packageName?await catalog({q:packageName,category:''}):await catalog();
-    const item=page.items.find(row=>row.id===itemId&&(packageName===undefined||row.package?.name===packageName));
-    requireCondition(item,'CATALOG_ITEM_MISSING','Catalog item was not found.',{itemId},404);return item;
+    let cursor;const seen=new Set(),matches=new Map();
+    do{
+      const page=await catalog({q:packageName??'',category:'',cursor});
+      const found=page.items.find(row=>(itemId===undefined||row.id===itemId)&&(packageName===undefined||row.package?.name===packageName));
+      if(found&&itemId===undefined&&page.schemaVersion==='hanamesh.catalog.v1'){
+        for(const row of page.items.filter(row=>row.package?.name===packageName))matches.set(row.id,{row,source:page.source});
+        requireCondition(matches.size<=1,'CATALOG_TARGET_AMBIGUOUS','Choose an itemId: this npm name belongs to multiple catalog identities.',{packageName},409);
+      }else if(found){
+        requireCondition(found.package?.registry==='npm','NOT_INSTALLABLE','This catalog entry cannot be installed.');
+        requireCondition(!protectedPackage(found.package.name),'PACKAGE_DENIED','The HanaMesh suite is not managed through the market.',{},403);
+        const rows=[...await installedPlugins(),...await installed()],row=rows.find(value=>value.packageName===found.package.name)??null;
+        return{contractVersion:INSTALL_TARGET_CONTRACT_VERSION,source:page.source,item:{...found,kind:itemKind(found),installed:row,upgradeAvailable:Boolean(row?.version&&row.state!=='uninstalled-not-unloaded'&&upgradeAvailable(found.latestVersion,row.version))}};
+      }
+      cursor=page.page?.nextCursor;
+      requireCondition(!cursor||!seen.has(cursor),'INVALID_CURSOR','Catalog cursor repeated.');if(cursor)seen.add(cursor);
+    }while(cursor);
+    if(matches.size===1){
+      const{row:found,source}=matches.values().next().value;
+      requireCondition(!protectedPackage(found.package.name),'PACKAGE_DENIED','The HanaMesh suite is not managed through the market.',{},403);
+      const rows=[...await installedPlugins(),...await installed()],row=rows.find(value=>value.packageName===found.package.name)??null;
+      return{contractVersion:INSTALL_TARGET_CONTRACT_VERSION,source,item:{...found,kind:itemKind(found),installed:row,upgradeAvailable:Boolean(row?.version&&row.state!=='uninstalled-not-unloaded'&&upgradeAvailable(found.latestVersion,row.version))}};
+    }
+    throw new AppHostError('CATALOG_ITEM_MISSING','The market catalog does not contain this target.',{},404);
+  }
+  function installItem(item){
+    const key=item.package.name;if(installing.has(key))return installing.get(key);
+    const started=operation('install',async operationId=>{try{return await markLive(await installer.install(item,{operationId}));}finally{installing.delete(key);}});
+    installing.set(key,started);return started;
   }
   async function findByPackage(packageName){
     requireCondition(text(packageName,214)&&PACKAGE_NAME.test(packageName),'INVALID_INPUT','packageName is required.');
     requireCondition(!protectedPackage(packageName),'PACKAGE_DENIED','The HanaMesh suite is not managed through the market.',{packageName},403);
-    const page=await catalog({q:packageName,category:''});const item=page.items.find(row=>row.package?.registry==='npm'&&row.package?.name===packageName);
-    requireCondition(item,'CATALOG_ITEM_MISSING','The catalog does not list this package.',{packageName},404);return item;
+    const{item}=await resolveTarget({packageName});return item;
   }
   const runningApp=appId=>host.instanceList().some(instance=>instance.appId===appId&&!['stopped','failed','interrupted'].includes(instance.status));
   return{
-    async init(){state=await domain.global.get();if(state.sources.length===0&&Array.isArray(config.sources)&&config.sources.length){const sources=config.sources.map((source,index)=>({manifestUrl:validateManifestUrl(source.manifestUrl).href,enabled:source.enabled===true||(source.enabled!==false&&index===0)}));requireCondition(sources.filter(source=>source.enabled).length===1,'CATALOG_SOURCE_REQUIRED','Exactly one catalog source must be enabled.');await persist({...state,sources});}
-      // rc.28: the dependency set at boot is the "loaded" baseline for plugin restart states; unreadable → everything counts as loaded.
-      if(config.profileDir){try{bootDependencies=await snapshotProfileDependencies(config.profileDir);}catch{bootDependencies=undefined;}}
-      return this;},
+    async init(){state=await domain.global.get();if(state.revision===0&&state.sources.length===0&&Array.isArray(config.sources)&&config.sources.length){const sources=config.sources.map((source,index)=>({manifestUrl:validateManifestUrl(source.manifestUrl).href,enabled:source.enabled===true||(source.enabled!==false&&index===0)}));requireCondition(sources.filter(source=>source.enabled).length===1,'CATALOG_SOURCE_REQUIRED','Exactly one catalog source must be enabled.');await persist(current=>({...current,sources}));}
+      // rc.28: the dependency set at boot is the "loaded" baseline for plugin restart states; unreadable → everything counts as
+      // loaded, logged and reported as `restartBaseline` on list() so the market can say restart states are unknown.
+      if(config.profileDir){try{bootDependencies=await snapshotProfileDependencies(config.profileDir);}catch(error){bootDependencies=undefined;bootSnapshotError=error?.code??'PROFILE_READ_FAILED';warn('hanamesh-app-host library: boot profile snapshot unreadable (%s); restart states cannot be told',bootSnapshotError);}}
+      suiteStatus=await suiteFacts();return this;},
     async list({q='',category,cursor}={}){requireCondition(typeof q==='string'&&q.length<=200,'INVALID_QUERY','q must be a string of at most 200 characters.');requireCondition(category===undefined||(typeof category==='string'&&category.length<=64&&/^[a-z0-9._:-]*$/.test(category)),'INVALID_QUERY','category is invalid.');requireCondition(cursor===undefined||(typeof cursor==='string'&&cursor.length>0&&cursor.length<=2048),'INVALID_CURSOR','cursor is invalid.');
       const page=await catalog({q,category,cursor});const installedRows=await installed();const pluginRows=await installedPlugins();
+      suiteStatus={...await suiteFacts(),...(suiteStatus.restartRequired?{restartRequired:true}:{}),...(suiteStatus.upgradeError?{upgradeError:suiteStatus.upgradeError}:{})};
       const byPackage=new Map([...pluginRows,...installedRows].map(row=>[row.packageName,row]));
-      const items=page.items.map(item=>{const row=byPackage.get(item.package?.name)??null;const kind=itemKind(item);
+      let items=page.items.filter(item=>!protectedPackage(item.package?.name)).map(item=>{const row=byPackage.get(item.package?.name)??null;const kind=itemKind(item);
         return{...item,kind,application:isApplication(item),installed:row,upgradeAvailable:Boolean(row&&row.version&&row.state!=='uninstalled-not-unloaded'&&upgradeAvailable(item.latestVersion,row.version))};});
+      if(config.profileDir&&!cursor&&(!category||category==='plugin')&&(!q||'hanamesh 套件'.includes(q.toLowerCase())))items.unshift({id:'hanamesh:suite',displayName:'HanaMesh 套件',summary:'官方 · 不计分。Core、使用记录与应用库一次装齐。',kind:'suite',official:true,latestVersion:suiteStatus.version,installed:suiteStatus.status==='installed'?{state:'installed',version:suiteStatus.version}:null,suite:suiteStatus,...((installer?.suiteUpgradeUnavailable??suiteStatus.suiteUpgradeUnavailable)?{suiteUpgradeUnavailable:installer?.suiteUpgradeUnavailable??suiteStatus.suiteUpgradeUnavailable}:{})});
       const categories=[...new Set(page.items.flatMap(item=>item.categories??[]))].sort();
-      return{source:page.source,items,categories,installed:installedRows,plugins:pluginRows,restartRequired:[...pluginRows,...installedRows].some(row=>RESTART_STATES.has(row.state)),page:page.page};},
+      return{source:page.source,items,categories,installed:installedRows,plugins:pluginRows,restartRequired:[...pluginRows,...installedRows].some(row=>RESTART_STATES.has(row.state)),...(bootSnapshotError?{restartBaseline:{known:false,code:bootSnapshotError}}:{}),page:page.page};},
     sources(){return{sources:structuredClone(state.sources),revision:state.revision};},
-    async replaceSources(input){requireCondition(Array.isArray(input?.sources)&&input.sources.length<=16,'INVALID_SOURCES','sources must be an array of at most 16 entries.');const sources=input.sources.map(source=>({manifestUrl:validateManifestUrl(source.manifestUrl).href,enabled:source.enabled===true}));requireCondition(sources.length===0||sources.filter(source=>source.enabled).length===1,'CATALOG_SOURCE_REQUIRED','Exactly one catalog source must be enabled.');await persist({...state,sources});return this.sources();},
+    /** Suite package registry selection is independent of catalog manifest sources. */
+    suiteSourceSettings(){
+      let observation;try{observation={observable:true,state:readSuiteSourceState(suiteSourceService())};}catch(error){observation={observable:false,code:error.code??'CORE_SUITE_SOURCE_INVALID'};}
+      return{mode:state.suiteSource?.mode??'configured',configuredRegistry:config.registry??'https://registry.npmjs.org',observation};
+    },
+    async replaceSuiteSourceSettings(input){
+      requireCondition(input&&typeof input==='object'&&!Array.isArray(input)&&Object.keys(input).length===1&&['configured','core'].includes(input.mode),'INVALID_SUITE_SOURCE_SETTINGS','只接受 mode: configured 或 core。');
+      const selection={mode:input.mode};
+      try{await persist(current=>({...current,suiteSource:selection}));}catch(error){throw new AppHostError('SUITE_SOURCE_SAVE_FAILED','套件安装包来源保存失败；原选择保持。',{},500);}
+      return this.suiteSourceSettings();
+    },
+    /** Effective website handoff settings: saved (library settings page) → plugin config `library.handoff` → proposed defaults. */
+    handoffSettings(){return handoffSettings(state.handoff??config.handoff??{});},
+    async replaceHandoffSettings(input){const next=handoffSettings(input);await persist(current=>({...current,handoff:next}));return next;},
+    observe(listener){observers.add(listener);return()=>observers.delete(listener);},
+    async replaceSources(input){requireCondition(Array.isArray(input?.sources)&&input.sources.length<=16,'INVALID_SOURCES','sources must be an array of at most 16 entries.');const sources=input.sources.map(source=>({manifestUrl:validateManifestUrl(source.manifestUrl).href,enabled:source.enabled===true}));requireCondition(sources.length===0||sources.filter(source=>source.enabled).length===1,'CATALOG_SOURCE_REQUIRED','Exactly one catalog source must be enabled.');await persist(current=>({...current,sources}));return this.sources();},
     /** `{itemId, packageName?}`: applications and plugins take the same path (`dsh plugin add --save-exact`); also the upgrade path. */
-    async install(input){requireInstaller('Install requires absolute profileDir, nodeBinary, dshBin and profileName.');const item=await findItem(input??{});return await operation('install',()=>installer.install(item));},
+    resolveTarget,
+    /** Public discovery is metadata only: no profile, authentication or installed rows. */
+    installationStatus,
+    installTarget(){const need=ready()?[]:unavailable();return{client,ready:ready(),...(typeof installationStatus==='function'?{installationStatus:INSTALLATION_STATUS_CAPABILITY}:{}),...((suiteStatus.status!=='unknown'||suiteStatus.restartRequired)&&!installer?.suiteUpgradeUnavailable?{suite:structuredClone(suiteStatus)}:{}),installTarget:{contract:'hanamesh.install-target',contractVersion:INSTALL_TARGET_CONTRACT_VERSION,supported:[INSTALL_TARGET_CONTRACT_VERSION],fragmentPrefix:'#hanamesh-install?'},
+      ...(!ready()?{error:{code:'INSTALL_TARGET_UNAVAILABLE',message:need.length?'应用库还不能安装：'+need.map(row=>row.need).join('；'):'Controlled installer is unavailable.',need}}:{})};},
+    /** Plugin changes load without a restart (the host's public plugin manager is present). */
+    get live(){return Boolean(installer?.live);},
+    async upgradeSuite(input){requireInstaller('Suite upgrade is unavailable.');
+      requireCondition(input&&Object.keys(input).length===1&&typeof input.planId==='string','INVALID_INPUT','Only the current planId is accepted.');
+      return await operation('install',async()=>{try{const result=await installer.upgradeSuite(input);suiteStatus={...await suiteFacts(),restartRequired:true};return result;}catch(error){if(error.details?.stage!=='suite-upgrade')throw error;const actual=await readSuiteStatus(config.profileDir);suiteStatus={...await suiteFacts(),restartRequired:true,upgradeError:error.code??'SUITE_UPGRADE_FAILED'};error.details={...error.details,stage:'suite-upgrade',actual,command:SUITE_INSTALL_COMMAND};emit({type:'library.install-failed',packageName:'hanamesh-core',code:error.code??'SUITE_UPGRADE_FAILED',details:{stage:'suite-upgrade',actual,command:SUITE_INSTALL_COMMAND}});throw error;}});
+    },
+    async install(input){requireCondition(input?.itemId!==SUITE_TARGET,'SUITE_CONFIRMATION_REQUIRED','请在客户端确认完整升级计划。',{},403);requireInstaller('Install requires absolute profileDir, nodeBinary, dshBin and profileName.');const{item}=await resolveTarget(input??{});if(present(item.installed)&&!item.upgradeAvailable)return{status:'already-installed',itemId:item.id,packageName:item.package.name};return await installItem(item);},
     async provision(input){requireInstaller('Runtime provision is unavailable.');
       // LIB-PROVISION-INPUT: a missing field is the caller's error (400), not an internal TypeError inside the operation.
       requireCondition(text(input?.appId,160),'INVALID_INPUT','appId is required.');requireCondition(text(input?.packageName,214)&&PACKAGE_NAME.test(input.packageName),'INVALID_INPUT','packageName is required.');requireCondition(text(input?.runtimeItem,160),'INVALID_INPUT','runtimeItem is required.');
@@ -59,18 +155,18 @@ export function createLibraryService({domain,host,config={},dataRoot,ledgerReade
       requireCondition(text(input?.appId,160),'INVALID_INPUT','appId is required.');requireCondition(text(input?.packageName,214)&&PACKAGE_NAME.test(input.packageName),'INVALID_INPUT','packageName is required.');requireCondition(input.runtimeItem===undefined||text(input.runtimeItem,160),'INVALID_INPUT','runtimeItem is invalid.');
       const{appId,packageName,runtimeItem}=input;return await operation('uninstall',()=>installer.uninstall({appId,packageName,runtimeItem,running:runningApp(appId)}));},
     /** rc.28 `{packageName}`: the package must be listed by the enabled catalog; an application package takes the application path. */
-    async installPlugin(input){requireInstaller('Plugin install requires absolute profileDir, nodeBinary, dshBin and profileName.');const item=await findByPackage(input?.packageName);return await operation('install',()=>installer.install(item));},
+    async installPlugin(input){requireInstaller('Plugin install requires absolute profileDir, nodeBinary, dshBin and profileName.');const item=await findByPackage(input?.packageName);return await installItem(item);},
     /** rc.28 `{packageName}`: `dsh plugin remove`; an installed application package is routed through the application uninstall (runtime + running check). */
     async uninstallPlugin(input){requireInstaller('Plugin uninstall is unavailable.');const packageName=input?.packageName;requireCondition(text(packageName,214)&&PACKAGE_NAME.test(packageName),'INVALID_INPUT','packageName is required.');requireCondition(!protectedPackage(packageName),'PACKAGE_DENIED','The HanaMesh suite is not managed through the market.',{packageName},403);
       const app=(await installed()).find(row=>row.packageName===packageName&&row.appId);
       if(app)return await operation('uninstall',()=>installer.uninstall({appId:app.appId,packageName,runtimeItem:app.runtimeItem,running:runningApp(app.appId)}));
-      return await operation('uninstall',()=>installer.uninstallPlugin({packageName}));},
+      return await operation('uninstall',async()=>{return await markLive(await installer.uninstallPlugin({packageName}));});},
     /** Installed application packages of the profile (empty without `profileDir`); rc.27 binds package names for usage evidence. */
     installed,
     /** rc.28: installed plugins (every non-application dependency of the profile) with restart states. */
     installedPlugins,
     async installedSnapshot(){const plugins=await installedPlugins(),apps=await installed();return{plugins,apps,restartRequired:[...plugins,...apps].some(row=>RESTART_STATES.has(row.state))};},
-    events(after=0){requireCondition(Number.isSafeInteger(after)&&after>=0,'INVALID_CURSOR','Invalid library event cursor.');return{events:events.filter(event=>event.sequence>after),sequence,operations:[...running.keys()]};},
-    async close(){await Promise.allSettled([...running.values()]);await domain.close();},emit,
+    events(after=0){requireCondition(Number.isSafeInteger(after)&&after>=0,'INVALID_CURSOR','Invalid library event cursor.');return{events:events.filter(event=>event.sequence>after),sequence,operations:[...running.keys()],resetRequired:after>sequence||(events.length>0&&after<events[0].sequence-1)};},
+    async close(){installationStatus?.close?.();await Promise.allSettled([...running.values()]);await settingsWriter.drained();await domain.close();},emit,
   };
 }

package/dist/library/suite.js

@@ -0,0 +1,130 @@
+import {readFile} from 'node:fs/promises';
+import {join} from 'node:path';
+import semver from 'semver';
+import {randomUUID} from 'node:crypto';
+import {requireCondition} from '../errors.js';
+
+export const SUITE_TARGET='hanamesh:suite-upgrade';
+export const SUITE_PACKAGES=Object.freeze([
+  {name:'hanamesh-core',label:'Core',repo:'hanamesh-core'},
+  {name:'hanamesh-usage',label:'使用记录',repo:'hanamesh-usage'},
+  {name:'@hanamesh/dsh-app-host',label:'应用库',repo:'hanamesh-plugin-app-host'},
+].map(Object.freeze));
+export const SUITE_INSTALL_COMMAND="env -u GIT_CONFIG_PARAMETERS -u GIT_ASKPASS -u SSH_ASKPASS GIT_CONFIG_NOSYSTEM=1 GIT_TERMINAL_PROMPT=0 GIT_CONFIG_COUNT=2 GIT_CONFIG_KEY_0=credential.helper GIT_CONFIG_VALUE_0= GIT_CONFIG_KEY_1=credential.helper GIT_CONFIG_VALUE_1='!gh auth git-credential' dsh plugin --profile desktop add --save-exact 'github:yzsnstotz/hanamesh-core#main' 'github:yzsnstotz/hanamesh-usage#main' 'github:yzsnstotz/hanamesh-plugin-app-host#main'";
+const json=async path=>JSON.parse(await readFile(path,'utf8'));
+/** Physical inventory only, never a compatibility declaration or permission to upgrade. */
+export async function readSuiteStatus(profileDir){
+  if(!profileDir)return{status:'unknown',version:null,components:[]};
+  try{
+    const profile=await json(join(profileDir,'package.json'));
+    if(!profile.dependencies||!Array.isArray(profile.dsh?.profile?.bundles))throw new Error('unreadable profile');
+    const components=await Promise.all(SUITE_PACKAGES.map(async({name,label})=>{
+      let pkg;try{pkg=await json(join(profileDir,'node_modules',name,'package.json'));}catch{}
+      return{name,label,version:pkg?.name===name&&semver.valid(pkg.version)?pkg.version:null,active:profile.dsh.profile.bundles.includes(name)};
+    }));
+    return{status:components.every(c=>c.version&&c.active)?'installed':'incomplete',version:components[0].version,components};
+  }catch{return{status:'unknown',version:null,components:[]};}
+}
+export const CORE_SUITE_DECLARATION_MISSING='Core 未提供套件声明';
+const object=value=>value!==null&&typeof value==='object'&&!Array.isArray(value);
+const text=value=>typeof value==='string'&&value.length>0;
+const exact=value=>typeof value==='string'&&semver.valid(value)===value;
+const digest=value=>typeof value==='string'&&/^[a-f0-9]{64}$/.test(value);
+const nullableText=value=>value===null||text(value);
+const invalid=()=>requireCondition(false,'CORE_SUITE_DECLARATION_INVALID','Core 套件声明无法用于精确安装。',{},503);
+function validateDeclaration(value){
+  if(!object(value)||value.schemaVersion!==1||!text(value.checkedAt)||!digest(value.declarationId)||!text(value.nodeVersion)||!nullableText(value.registry)||!['complete','incomplete','unknown'].includes(value.completeness))invalid();
+  const manifest=value.manifest;
+  if(!object(manifest)||manifest.schemaVersion!==1||!text(manifest.id)||!object(manifest.core)||manifest.core.name!==SUITE_PACKAGES[0].name||!exact(manifest.core.version)||!text(manifest.core.repository)||!Array.isArray(manifest.components)||manifest.components.length!==2)invalid();
+  const members=new Map();
+  for(const row of manifest.components){if(!object(row)||!text(row.id)||!SUITE_PACKAGES.slice(1).some(p=>p.name===row.moduleName)||members.has(row.moduleName)||!text(row.versionRange)||!text(row.repository))invalid();members.set(row.moduleName,row.id);}
+  if(!Array.isArray(value.installed)||value.installed.length!==3||!Array.isArray(value.upgrades)||!Array.isArray(value.blocked)||!object(value.peerFacts)||!object(value.metadataDigests))invalid();
+  const installed=new Map();
+  for(const row of value.installed){
+    if(!object(row)||!text(row.id)||!SUITE_PACKAGES.some(p=>p.name===row.moduleName)||installed.has(row.moduleName)||!text(row.requiredRange)||!text(row.repository)||!(row.actualVersion===null||exact(row.actualVersion))||!nullableText(row.actualRepository)||!text(row.status)||(row.runningVersion!==undefined&&!exact(row.runningVersion)))invalid();
+    installed.set(row.moduleName,row);
+  }
+  for(const row of value.blocked)if(!object(row)||!text(row.code)||(row.coreVersion!==undefined&&!text(row.coreVersion))||(row.moduleName!==undefined&&!text(row.moduleName)))invalid();
+  if(!Object.values(value.peerFacts).every(nullableText)||!Object.values(value.metadataDigests).every(text))invalid();
+  for(const upgrade of value.upgrades){
+    if(!object(upgrade)||!exact(upgrade.coreVersion)||!text(upgrade.registry)||!digest(upgrade.manifestDigest)||!Array.isArray(upgrade.targets)||upgrade.targets.length!==3)invalid();
+    const targets=new Set();
+    for(const row of upgrade.targets){if(!object(row)||!text(row.id)||!SUITE_PACKAGES.some(p=>p.name===row.moduleName)||targets.has(row.moduleName)||!exact(row.version)||!text(row.repository)||!digest(row.metadataDigest))invalid();targets.add(row.moduleName);}
+    if(upgrade.targets.find(row=>row.moduleName===SUITE_PACKAGES[0].name).version!==upgrade.coreVersion)invalid();
+  }
+  return structuredClone(value);
+}
+/** Read only the optional protocol-1 public state; absence is unobservable, never starting/ready. */
+export function readSuiteSourceState(source){
+
+  requireCondition(source!==undefined&&source!==null,'CORE_SUITE_SOURCE_MISSING','Core 本机套件来源尚不可观察；请检查 Core 插件及其来源设置。',{},503);
+  requireCondition(object(source)&&source.protocolVersion==='1'&&typeof source.getState==='function','CORE_SUITE_SOURCE_INVALID','Core 本机套件来源协议或读取接口无效。',{},503);
+  let state;try{state=source.getState();}catch{requireCondition(false,'CORE_SUITE_SOURCE_INVALID','Core 本机套件来源读取失败。',{},503);}
+  requireCondition(object(state)&&state.protocolVersion==='1'&&['disabled','ready','failed','disposed'].includes(state.status)&&['configured','custom','disabled'].includes(state.selection)&&(state.registry===null||text(state.registry))&&Number.isSafeInteger(state.archiveCount)&&state.archiveCount>=0&&(state.lastError===null||typeof state.lastError==='string'),'CORE_SUITE_SOURCE_INVALID','Core 本机套件来源状态无效。',{},503);
+  return{protocolVersion:state.protocolVersion,status:state.status,selection:state.selection,registry:state.registry,archiveCount:state.archiveCount,lastError:state.lastError};
+}
+/** Consume only the optional protocol-1 Cordis method and the public C-CORE section D DTO. */
+export function createCoreSuiteAdapter({core=()=>undefined,registry,suiteSourceMode=()=>'configured',suiteSourceService=()=>undefined}={}){
+  const current=()=>{const value=core();return value?.protocolVersion==='1'&&typeof value.getSuiteDeclaration==='function'?value:undefined;};
+  // AppHost-local service identity only: Core protocol 1 supplies no revision/generation.
+  const instances=new WeakMap();
+  function sourceBinding(){
+    const mode=suiteSourceMode();
+    requireCondition(['configured','core'].includes(mode),'INVALID_SUITE_SOURCE_SETTINGS','套件安装包来源选择无效。');
+    if(mode==='configured')return{mode,registry};
+    const source=suiteSourceService();
+    const state=readSuiteSourceState(source);
+    requireCondition(state.status==='ready'&&state.selection!=='disabled'&&text(state.registry),'CORE_SUITE_SOURCE_NOT_READY','Core 本机套件来源未就绪（'+state.status+'）。',{status:state.status,selection:state.selection,lastError:state.lastError},409);
+    let url;try{url=new URL(state.registry);}catch{}
+    requireCondition(url&&['http:','https:'].includes(url.protocol)&&!url.username&&!url.password&&!url.search&&!url.hash,'CORE_SUITE_SOURCE_INVALID','Core 本机套件来源 registry 无效。',{},503);
+    if(!instances.has(source))instances.set(source,randomUUID());
+    return{mode,registry:state.registry,selection:state.selection,serviceInstance:instances.get(source)};
+  }
+  async function read(request){
+    const service=current();
+    requireCondition(service,'CORE_SUITE_DECLARATION_MISSING',CORE_SUITE_DECLARATION_MISSING,{},503);
+    const result=request===undefined?await service.getSuiteDeclaration():await service.getSuiteDeclaration(request);
+    requireCondition(current()===service,'CORE_SUITE_DECLARATION_MISSING',CORE_SUITE_DECLARATION_MISSING,{},503);
+    return validateDeclaration(result);
+  }
+  const get=async()=>{
+    const binding=sourceBinding();
+    const declaration=await read({registry:binding.registry});
+    requireCondition(JSON.stringify(sourceBinding())===JSON.stringify(binding),'SUITE_PLAN_CHANGED','套件安装包来源已变化，请重新查看并确认。',{},409);
+    requireCondition(declaration.completeness==='complete','CORE_SUITE_CURRENT_INCOMPLETE','Core 套件完整性：'+declaration.completeness,{completeness:declaration.completeness,blocked:declaration.blocked},409);
+    let expected;try{const url=new URL(binding.registry);url.pathname=url.pathname.replace(/\/$/,'')+'/';expected=url.href;}catch{}
+    requireCondition(expected&&declaration.registry===expected,'CORE_SUITE_SOURCE_MISMATCH','Core 声明来源与执行 registry 不符。',{blocked:declaration.blocked},409);
+    requireCondition(declaration.upgrades.length>0,'CORE_SUITE_NO_COMPATIBLE_TUPLE','Core 未提供可执行升级组合。',{blocked:declaration.blocked},409);
+    // The first displayed Core tuple is the presentation default; App-host never ranks versions.
+    const selectedUpgrade=declaration.upgrades[0];
+    requireCondition(selectedUpgrade.registry===declaration.registry,'CORE_SUITE_SOURCE_MISMATCH','Core 升级组合来源与执行 registry 不符。',{},409);
+    const components=SUITE_PACKAGES.map(({name,label})=>{const from=declaration.installed.find(row=>row.moduleName===name).actualVersion;if(!exact(from))invalid();return{name,label,from,to:selectedUpgrade.targets.find(row=>row.moduleName===name).version};});
+    return{available:true,components,sourceBinding:binding,declarationId:declaration.declarationId,registry:declaration.registry,selectedUpgrade,physicalBaseline:declaration.installed,upgrades:declaration.upgrades,blocked:declaration.blocked};
+  };
+  Object.defineProperty(get,'unavailable',{get:()=>current()?null:CORE_SUITE_DECLARATION_MISSING});
+  get.readFacts=async()=>{
+    const declaration=await read();
+    return{status:declaration.completeness==='complete'?'installed':declaration.completeness,completeness:declaration.completeness,version:declaration.installed.find(row=>row.moduleName==='hanamesh-core').actualVersion,
+      components:declaration.installed.map(row=>({...row,name:row.moduleName,label:SUITE_PACKAGES.find(p=>p.name===row.moduleName).label,version:row.actualVersion})),blocked:declaration.blocked};
+  };
+  return get;
+}
+/**
+ * Internal App-host execution port. The public adapter above supplies this plan in production;
+ * injected normalized stand-ins remain useful for testing CLI/confirmation behavior in isolation.
+ * Core owns candidate selection, completeness, ranges and compatibility; this module only checks
+ * that an exact execution plan is well formed and confined to our three protected packages.
+ */
+export async function prepareSuiteUpgrade({coreSuitePlan}={}){
+  requireCondition(typeof coreSuitePlan==='function','CORE_SUITE_DECLARATION_MISSING',CORE_SUITE_DECLARATION_MISSING,{},503);
+  const plan=await coreSuitePlan();
+  requireCondition(plan!==undefined&&plan!==null,'CORE_SUITE_DECLARATION_MISSING',CORE_SUITE_DECLARATION_MISSING,{},503);
+  const invalid=()=>requireCondition(false,'CORE_SUITE_DECLARATION_INVALID','Core 套件声明无法用于精确安装。',{},503);
+  if(typeof plan!=='object'||Array.isArray(plan)||typeof plan.available!=='boolean'||!Array.isArray(plan.components)||plan.components.length!==SUITE_PACKAGES.length)invalid();
+  const rows=new Map();
+  for(const row of plan.components){
+    if(!row||typeof row!=='object'||!SUITE_PACKAGES.some(p=>p.name===row.name)||rows.has(row.name)||typeof row.from!=='string'||semver.valid(row.from)!==row.from||typeof row.to!=='string'||semver.valid(row.to)!==row.to)invalid();
+    rows.set(row.name,row);
+  }
+  return{...structuredClone(plan),available:plan.available,components:SUITE_PACKAGES.map(({name,label})=>({name,label,from:rows.get(name).from,to:rows.get(name).to}))};
+}