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

package/dist/client.js

@@ -0,0 +1,42 @@
+/** Workspace-side SDK only. Never inject this module into an application iframe. */
+export class WorkspaceAppClient {
+  constructor({origin=globalThis.location?.origin,fetch:fetcher=globalThis.fetch,headers=()=>({})}={}) {
+    const parsed=new URL(origin);
+    if(parsed.origin!==origin||parsed.protocol!=='http:'||parsed.hostname!=='127.0.0.1'||!parsed.port)throw new TypeError('Expected exact loopback workspace origin.');
+    if(typeof fetcher!=='function'||typeof headers!=='function')throw new TypeError('fetch and host headers provider are required.');
+    this.origin=origin;this.fetcher=fetcher;this.headers=headers;
+  }
+  async request(path,input,signal){
+    // Browsers refuse `fetch` invoked with a foreign `this`; keep the global receiver for the default fetcher.
+    const response=await this.fetcher.call(globalThis,this.origin+path,{method:input===undefined?'GET':'POST',credentials:'same-origin',redirect:'error',signal,
+      headers:{...await this.headers(),...(input===undefined?{}:{'content-type':'application/json','x-hanamesh-client':'workspace-v1'})},
+      ...(input===undefined?{}:{body:JSON.stringify(input)})});
+    const body=await response.json();
+    if(!response.ok){const error=new Error(body.error?.message??'App-host request failed.');error.code=body.error?.code??'HTTP_ERROR';error.details=body.error?.details;error.status=response.status;throw error;}
+    return body;
+  }
+  list(signal){return this.request('/hanamesh/apps',undefined,signal);}
+  open(input,signal){return this.request('/apps/open',input,signal);}
+  resume(lease,signal){return this.request('/apps/resume',lease,signal);}
+  recoverView(input,signal){return this.request('/apps/recover',input,signal);}
+  close(lease,signal){return this.request('/apps/close',lease,signal);}
+  heartbeat(lease,signal){return this.request('/apps/heartbeat',lease,signal);}
+  stop(instanceId,{confirm=false,signal}={}){return this.request('/apps/stop',{instanceId,confirm},signal);}
+  events(after=0,signal){if(!Number.isSafeInteger(after)||after<0)throw new TypeError('Invalid event cursor.');return this.request(`/apps/events?after=${after}`,undefined,signal);}
+  // A bounded explicit operation; never retries a new Open without the receipt's token.
+  async waitUntilReady(receipt,{timeoutMs=15_000,pollMs=100,signal}={}){
+    if(!Number.isFinite(timeoutMs)||timeoutMs<=0||!Number.isFinite(pollMs)||pollMs<20)throw new TypeError('Invalid polling bounds.');
+    const deadline=Date.now()+timeoutMs;let current=receipt;
+    while(current.instance.status!=='ready'){
+      signal?.throwIfAborted();
+      if(['failed','stopped','interrupted','stopping'].includes(current.instance.status))throw new Error(`Instance is ${current.instance.status}.`);
+      if(Date.now()>=deadline)throw new Error('Readiness wait timed out; use the receipt to close or inspect this view.');
+      await new Promise(resolve=>setTimeout(resolve,pollMs));
+      const listed=await this.list(signal),found=listed.instances.find(i=>i.id===receipt.instance.id);
+      if(!found)throw new Error('Persisted instance is missing.');
+      if(found.status==='ready')current=await this.resume({viewId:receipt.lease.viewId,leaseToken:receipt.leaseToken},signal);
+      else current={...current,instance:found};
+    }
+    return current;
+  }
+}

package/dist/consistency.js

@@ -0,0 +1,12 @@
+// These two orderings are used by the production manager AND the real SIGKILL tests.
+// Keep fault injection as a trusted constructor dependency, never a browser option.
+export async function reserveBeforeLaunch(publish, launch, checkpoint = async () => {}) {
+  await publish(); // ORDER:RESERVE
+  await checkpoint('reservation-durable');
+  return await launch(); // ORDER:LAUNCH
+}
+export async function stopBeforePublish(stop, publish, checkpoint = async () => {}) {
+  await stop(); // ORDER:STOP
+  await checkpoint('runtime-stopped');
+  return await publish(); // ORDER:STOPPED-PUBLISH
+}

package/dist/descriptor.js

@@ -0,0 +1,141 @@
+import { isAbsolute } from 'node:path';
+import { createHash } from 'node:crypto';
+import { requireCondition, copy } from './errors.js';
+export function identifier(value, name = 'id') {
+  requireCondition(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(value) &&
+    !['__proto__','prototype','constructor'].includes(value), 'INVALID_ID', `Invalid ${name}.`);
+  return value;
+}
+export function loopbackOrigin(value) {
+  let url;
+  try { url = new URL(value); } catch { requireCondition(false, 'INVALID_ORIGIN', 'Expected an explicit loopback origin.'); }
+  requireCondition(url.protocol === 'http:' && url.hostname === '127.0.0.1' && url.port &&
+    !url.username && !url.password && url.pathname === '/' && !url.search && !url.hash,
+    'INVALID_ORIGIN', 'Only an explicit http://127.0.0.1:<port> origin is supported by this candidate.');
+  return url.origin;
+}
+/** npm package name (optionally scoped), at most 128 characters — the same shape the usage plugin accepts as `hanaRef`. */
+export const packageName = value => typeof value === 'string' && value.length <= 128 && /^(?:@[a-z0-9][a-z0-9._-]*\/)?[a-z0-9][a-z0-9._-]*$/.test(value);
+export function validateDefinition(input) {
+  const d = copy(input);
+  identifier(d.id, 'appId');
+  requireCondition(typeof d.name === 'string' && d.name.length > 0 && d.name.length <= 160, 'INVALID_DEFINITION', 'Application name is required.');
+  // rc.27: the npm package that ships this app (usage evidence `hanaRef`). Optional — the installed scan supplies it otherwise.
+  if (d.packageName !== undefined) requireCondition(packageName(d.packageName), 'INVALID_DEFINITION', 'packageName must be an npm package name.');
+  d.singleInstanceOnly ??= true;
+  requireCondition(typeof d.singleInstanceOnly === 'boolean' && Array.isArray(d.deployments) && d.deployments.length > 0,
+    'INVALID_DEFINITION', 'Expected deployment definitions.');
+  const ids = new Set();
+  for (const p of d.deployments) {
+    identifier(p.id, 'deploymentId'); identifier(p.dataId, 'dataId');
+    requireCondition(!ids.has(p.id), 'INVALID_DEFINITION', 'Duplicate deploymentId.'); ids.add(p.id);
+    requireCondition(['owned','attach'].includes(p.mode), 'INVALID_DEFINITION', 'mode must be owned or attach.');
+    p.embedding ??= 'direct';
+    requireCondition(['direct','gateway'].includes(p.embedding), 'INVALID_DEFINITION', 'Unknown embedding mode.');
+    const r = p.readiness;
+    requireCondition(r && typeof r.path === 'string' && r.path.startsWith('/') && !r.path.startsWith('//') &&
+      !r.path.includes('\\') && Number.isInteger(r.status) && r.status >= 200 && r.status < 500 &&
+      ((typeof r.bodyIncludes === 'string' && r.bodyIncludes.length > 0) ||
+       (r.header && typeof r.header.name === 'string' && typeof r.header.value === 'string' && r.header.value.length > 0)),
+      'INVALID_READINESS', 'Readiness requires an exact status and nonempty application identity marker.');
+    p.startTimeoutMs ??= 10_000; p.stopGraceMs ??= 1_000;
+    requireCondition(Number.isInteger(p.startTimeoutMs) && p.startTimeoutMs >= 100 && p.startTimeoutMs <= 120_000 &&
+      Number.isInteger(p.stopGraceMs) && p.stopGraceMs >= 50 && p.stopGraceMs <= 30_000,
+      'INVALID_DEFINITION', 'Lifecycle timeouts are outside the allowed bounds.');
+    if (p.mode === 'owned') {
+      if (p.runtime !== undefined) {
+        requireCondition(p.runtime && typeof p.runtime === 'object' && !Array.isArray(p.runtime) && p.command === undefined,
+          'INVALID_RUNTIME', 'A runtime deployment must omit command and declare a runtime object.');
+        const { manifest, item, exec } = p.runtime;
+        requireCondition(manifest && typeof manifest === 'object' && !Array.isArray(manifest) && manifest.schema === 1 &&
+          Array.isArray(manifest.sources) && Array.isArray(manifest.items) && typeof item === 'string',
+          'INVALID_RUNTIME', 'runtime.manifest must be a schema 1 provision manifest.');
+        requireCondition(manifest.sources.every(source => source && typeof source === 'object' &&
+          typeof source.id === 'string' && ['https','file'].includes(source.kind) && typeof source.base === 'string'),
+          'INVALID_RUNTIME', 'runtime manifest sources are invalid.');
+        const selected = manifest.items.find(entry => entry?.id === item);
+        requireCondition(selected && typeof selected.version === 'string' && selected.version.length > 0 &&
+          typeof selected.installTo === 'string' && safeRelativePosix(selected.installTo) &&
+          selected.platforms && typeof selected.platforms === 'object' && !Array.isArray(selected.platforms),
+          'INVALID_RUNTIME', 'runtime.item must select a valid manifest item.');
+        requireCondition(typeof exec === 'string' && safeRelativePosix(exec),
+          'INVALID_RUNTIME', 'runtime.exec must be a relative POSIX path inside the selected runtime tree.');
+      } else {
+        requireCondition(typeof p.command === 'string' && isAbsolute(p.command) && !p.command.includes('\0'),
+          'INVALID_COMMAND', 'An absolute, trusted executable path is required.');
+      }
+      requireCondition(Array.isArray(p.args) && p.args.every(a => typeof a === 'string' && !a.includes('\0')),
+        'INVALID_COMMAND', 'args must be an explicit string array; shell execution is not supported.');
+      if (p.cwd) requireCondition(isAbsolute(p.cwd), 'INVALID_COMMAND', 'cwd must be absolute.');
+      p.env ??= {}; p.envAllowlist ??= [];
+      requireCondition(p.env && !Array.isArray(p.env) && Array.isArray(p.envAllowlist) &&
+        Object.entries(p.env).every(([k, v]) => /^[A-Z_][A-Z0-9_]*$/.test(k) && p.envAllowlist.includes(k) &&
+          typeof v === 'string' && !v.includes('\0') && !/^(DSH_|NODE_OPTIONS$|LD_|DYLD_)/.test(k)),
+        'INVALID_ENV', 'Every environment entry must be explicitly allowlisted; host control variables are forbidden.');
+      // rc.4: an app declares WHICH credentials it needs (env names / home files), never where they come from.
+      p.credentialEnv ??= [];
+      requireCondition(Array.isArray(p.credentialEnv), 'INVALID_CREDENTIAL_ENV', 'credentialEnv must be an array.');
+      const seen = new Set();
+      for (const c of p.credentialEnv) {
+        requireCondition(c && typeof c === 'object' && !Array.isArray(c), 'INVALID_CREDENTIAL_ENV', 'credentialEnv entries must be objects.');
+        c.kind ??= 'api-key'; c.required ??= false; c.projection ??= 'env'; c.providers ??= [];
+        if (c.projection === 'file') { c.base ??= 'home'; }
+        requireCondition((c.projection !== 'file' || ['home','dataDir'].includes(c.base)) &&
+          (c.format === undefined || (typeof c.format === 'string' && /^[a-z0-9][a-z0-9.-]{0,63}$/.test(c.format))),
+          'INVALID_CREDENTIAL_ENV', 'credentialEnv file base must be home or dataDir; format is an opaque lowercase id.');
+        requireCondition(['api-key','grant'].includes(c.kind) && ['env','file'].includes(c.projection) && typeof c.required === 'boolean' &&
+          Array.isArray(c.providers) && c.providers.every(x => typeof x === 'string' && /^[a-z0-9][a-z0-9_.-]{0,63}$/.test(x)) &&
+          (c.purpose === undefined || (typeof c.purpose === 'string' && c.purpose.length <= 120)),
+          'INVALID_CREDENTIAL_ENV', 'credentialEnv entry has an unknown kind, projection, provider id or purpose.');
+        if (c.projection === 'env') {
+          requireCondition(typeof c.env === 'string' && /^[A-Z_][A-Z0-9_]*$/.test(c.env) && !/^(DSH_|NODE_OPTIONS$|LD_|DYLD_|PATH$|HOME$|TMPDIR$|XDG_)/.test(c.env),
+            'INVALID_CREDENTIAL_ENV', 'credentialEnv env must be a POSIX identifier and not a host control variable.');
+          requireCondition(!(c.env in p.env), 'INVALID_CREDENTIAL_ENV', 'credentialEnv must not repeat a static env entry.');
+          requireCondition(!seen.has('env:' + c.env), 'INVALID_CREDENTIAL_ENV', 'Duplicate credentialEnv env name.'); seen.add('env:' + c.env);
+        } else {
+          requireCondition(typeof c.path === 'string' && c.path.length > 0 && c.path.length <= 200 && !c.path.startsWith('/') &&
+            !c.path.includes('\0') && c.path.split('/').every(seg => seg && seg !== '.' && seg !== '..'),
+            'INVALID_CREDENTIAL_ENV', 'credentialEnv file path must be relative to the app HOME and contain no "." or ".." segments.');
+          requireCondition(!seen.has(`file:${c.base}:` + c.path), 'INVALID_CREDENTIAL_ENV', 'Duplicate credentialEnv file path.'); seen.add(`file:${c.base}:` + c.path);
+        }
+        // rc.8 `sets`: non-secret companion values the broker applies when THIS slot is granted (e.g. the app's own
+        // provider id). Each target must be a declared env slot of this deployment, so the injection allowlist holds.
+        if (c.sets !== undefined) {
+          requireCondition(c.sets && typeof c.sets === 'object' && !Array.isArray(c.sets) && Object.entries(c.sets).every(([k, v]) =>
+            /^[A-Z_][A-Z0-9_]*$/.test(k) && typeof v === 'string' && v.length <= 256 && !/[\0\r\n]/.test(v)),
+            'INVALID_CREDENTIAL_ENV', 'credentialEnv sets must map POSIX env names to short single-line strings.');
+        }
+      }
+      for (const c of p.credentialEnv) for (const k of Object.keys(c.sets ?? {}))
+        requireCondition(seen.has('env:' + k), 'INVALID_CREDENTIAL_ENV', `credentialEnv sets "${k}", which is not a declared env slot of this deployment.`);
+      const bindings = [...p.args, ...Object.values(p.env)];
+      requireCondition(bindings.some(v => v.includes('{{dataDir}}')) && bindings.some(v => v.includes('{{port}}')),
+        'MISSING_RUNTIME_BINDING', 'Application adapter must explicitly bind its data directory and loopback port.');
+      for (const s of bindings) for (const match of s.matchAll(/\{\{(.*?)\}\}/g)) {
+        requireCondition(['dataDir','port','instanceId','runtimeId','appId','deploymentId','dataId'].includes(match[1]),
+          'INVALID_TEMPLATE', 'Unknown launch template.');
+      }
+    } else {
+      p.url = loopbackOrigin(p.url);
+      requireCondition(!p.command && !p.args && !p.env, 'INVALID_DEFINITION', 'Attach deployments cannot include launch instructions.');
+    }
+    p.gateway ??= {};
+    p.gateway.cookieAllowlist ??= [];
+    requireCondition(Array.isArray(p.gateway.cookieAllowlist) && p.gateway.cookieAllowlist.every(x =>
+      typeof x === 'string' && /^[A-Za-z0-9_-]+$/.test(x) && !/^dsh|^hm_/i.test(x)),
+      'INVALID_DEFINITION', 'Gateway cookie allowlist must contain explicit application cookie names.');
+    p.gateway.allowAppAuthorization ??= false;
+    requireCondition(typeof p.gateway.allowAppAuthorization === 'boolean', 'INVALID_DEFINITION', 'Invalid Authorization policy.');
+  }
+  return d;
+}
+function safeRelativePosix(value) {
+  if (typeof value !== 'string' || value.length === 0 || value.startsWith('/') || /^[A-Za-z]:/.test(value) ||
+    value.includes('\\') || value.includes('\0')) return false;
+  const segments = value.split('/');
+  return segments.every(segment => segment.length > 0 && segment !== '.' && segment !== '..');
+}
+export const fingerprint = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export function expand(template, values) {
+  return template.replace(/\{\{(dataDir|port|instanceId|runtimeId|appId|deploymentId|dataId)\}\}/g, (_, k) => String(values[k]));
+}

package/dist/dsh.d.ts

@@ -0,0 +1,25 @@
+import type { AppHost, AppDefinition, AuthenticatedSubject, Awaitable, DshStorageBinding } from './index.js';
+export const name: 'hanamesh-app-host';
+export const DSH_TARGET: '0.2.0-rc.2';
+export const inject: readonly ['webServer', 'storageDomain', 'connection'];
+export const BROWSER_PRINCIPAL: 'dsh-browser';
+export const ROUTES: readonly string[];
+export const Config: unknown;
+export const appHostDomainSpec: { readonly name: 'hanamesh_app_host'; readonly version: 1; readonly layout: 'single' };
+export interface DshPluginConfig {
+  dataRoot?: string; parentOrigin?: string; nodeBinary?: string; router?:{codingOauth?:{mode?:'http'|'file'}};
+  /** `sources` undefined → the HanaMesh catalog source; explicit `[]` → none. `profileDir`/`profileName`/`dshBin` (and
+   *  `nodeBinary`) are inferred on plain DSH when undefined — see docs/CONTRACT.md 「应用库配置」; explicit values win. */
+  /** rc.28: the same keys serve the HanaMesh market (plugins + applications; routes `/hanamesh/library*`, see docs/CONTRACT.md「市场」). */
+  library?:{fixture?:string;sources?:Array<{manifestUrl:string;enabled?:boolean}>;profileDir?:string;profileName?:string;dshBin?:string;registry?:string;allowPrerelease?:boolean};
+  applications?: AppDefinition[]; leaseTtlMs?: number; sweepIntervalMs?: number;
+}
+/** Adapt an open `ctx.storageDomain` handle (single layout, global snapshot) to the store binding. */
+export function domainBinding(domain: { global: { get(): unknown; set(value: unknown): Promise<void> }; close(): Promise<void> }): DshStorageBinding;
+/** Authentication through `ctx.connection.requestRejection`; DSH web is single-user. */
+export function browserAuthentication(connection: { requestRejection(request: { headers: Record<string, unknown> }): unknown }): {
+  authenticate(request: unknown): Awaitable<AuthenticatedSubject | null>;
+  authorize(subject: AuthenticatedSubject, path: string, input: unknown): Awaitable<boolean>;
+};
+/** Cordis plugin entry; activates once webServer, storageDomain and connection are provided. */
+export function apply(ctx: unknown, config: DshPluginConfig): Promise<void>;

package/dist/dsh.js

@@ -0,0 +1,194 @@
+/**
+ * DSH plugin entry for @hanamesh/dsh-app-host, bound to the PINNED public APIs
+ * of the official DSH 0.2.0-rc.2 release:
+ *
+ *   ctx.storageDomain.open(spec)      @deepseek-ai/dsh-storage-domain  — `single` layout, one
+ *                                     global snapshot; `global.set()` is one whole-image publish
+ *   ctx.webServer.register(route)     @deepseek-ai/dsh-host-webserver  — exact routes + disposer
+ *   ctx.connection.requestRejection() @deepseek-ai/dsh-client-connection — Host/Origin fence and
+ *                                     the browser session cookie; the same gate the /api channel uses
+ *   ctx.provide / ctx.effect          @deepseek-ai/cordis — service seat and disposal
+ *   ctx.inject([optional], child)     @deepseek-ai/cordis — optional sibling services (credentials, llm,
+ *                                     hanameshOAuth, hanameshUsage) are read duck-typed when/if they appear
+ *
+ * `inject` lists all three services, so the plugin only activates once they exist: without the
+ * connection service there is no authentication and therefore no route (H11/H14 fail closed).
+ * Nothing here guesses an API name; every call above has a type declaration in the pinned package.
+ */
+import z from '@deepseek-ai/schemastery';
+import { z as zod } from 'zod';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import { defineDomain } from '@deepseek-ai/dsh-storage-domain';
+import { AppHost } from './manager.js';
+import { DshDomainSnapshotStore, emptySnapshot } from './store.js';
+import { createHttpHandler } from './routes.js';
+import { requireCondition } from './errors.js';
+import { routerDomainSpec } from './router/domain.js';
+import { createProviderSources } from './router/sources.js';
+import { createRouter } from './router/broker.js';
+import { createRouterHttpHandler, ROUTER_ROUTES } from './router/routes.js';
+import { libraryDomainSpec } from './library/domain.js';
+import { createLibraryService } from './library/service.js';
+import { createLibraryInstaller } from './library/install.js';
+import { resolveLibraryLocations } from './library/locate.js';
+import { createLibraryHttpHandler, LIBRARY_ROUTES } from './library/routes.js';
+import { createUsageEvidence } from './usage-evidence.js';
+import { createReceiptLedger } from './router/receipts.js';
+import { receiptsDomainSpec } from './router/receipts-domain.js';
+
+export const name = 'hanamesh-app-host';
+export const DSH_TARGET = '0.2.0-rc.2';
+export const inject = ['webServer', 'storageDomain', 'connection'];
+/** One authenticated local browser session per profile; DSH web has no per-user principals. */
+export const BROWSER_PRINCIPAL = 'dsh-browser';
+/** Every route the HTTP handler answers; registered individually so nothing else is shadowed. */
+export const ROUTES = Object.freeze(['/hanamesh/apps', '/apps/open', '/apps/resume', '/apps/recover',
+  '/apps/close', '/apps/heartbeat', '/apps/stop', '/apps/events']);
+
+export const Config = z.object({
+  /** Absolute canonical directory that owns every instance data root (secureDirectory refuses symlinks). */
+  dataRoot: z.string().default(join(process.env.DSH_HOME ?? process.env.HOME ?? '.', 'data', 'hanamesh-apps')),
+  /** Exact loopback workspace origin; defaults to the running web server's own origin. */
+  parentOrigin: z.string(),
+  /** Extra origins allowed as frame ancestors of app views — the desktop shell's own webview origin
+   *  (e.g. `tauri://localhost`) when the DSH workspace itself runs inside the shell's iframe. */
+  frameAncestors: z.array(z.string()),
+  /** Standalone Node executable used for guardian/launcher processes; required under Electron. */
+  nodeBinary: z.string(),
+  router: z.object({ codingOauth: z.object({ mode:z.string() }) }),
+  library: z.object({
+    fixture:z.string(),
+    /** Undefined (not configured) → the HanaMesh catalog source; an explicit `[]` → no source. schemastery would
+     *  coerce a missing array to `[]`, so the union keeps "unset" distinguishable from "deliberately empty". */
+    sources:z.union([z.array(z.any()),z.const(undefined)]),
+    /** All four are set by the desktop shell overlay; on plain DSH they are inferred (see library/locate.js). */
+    profileDir:z.string(),profileName:z.string(),dshBin:z.string(),
+    registry:z.string(),allowPrerelease:z.boolean(),
+  }),
+  applications: z.array(z.any()).default([]),
+  leaseTtlMs: z.number(),
+  sweepIntervalMs: z.number(),
+});
+
+/** Domain declaration: the whole app-host snapshot is ONE global value, published atomically. */
+const snapshotSchema = zod.object({
+  schema: zod.literal(1), revision: zod.number().int().nonnegative(), sequence: zod.number().int().nonnegative(),
+  instances: zod.array(zod.record(zod.string(), zod.unknown())),
+  leases: zod.array(zod.record(zod.string(), zod.unknown())),
+  events: zod.array(zod.record(zod.string(), zod.unknown())),
+});
+export const appHostDomainSpec = defineDomain({
+  name: 'hanamesh_app_host', version: 1, layout: 'single', tables: {},
+  global: { schema: snapshotSchema, initial: emptySnapshot() },
+});
+
+/** Adapt an open storage-domain handle to the store's single-image binding port. */
+export function domainBinding(domain) {
+  return Object.freeze({
+    layout: 'single', domain: appHostDomainSpec.name,
+    readSnapshot: async () => domain.global.get(),
+    publishSnapshot: async snapshot => { await domain.global.set(snapshot); },
+    // Single-open per domain name is enforced by the facility at open(); nothing extra to take here.
+    acquireExclusive: async () => {},
+    releaseExclusive: async () => { await domain.close(); },
+  });
+}
+
+/** The authentication port: connection's fence + cookie decide, the plugin never parses a token. */
+export function browserAuthentication(connection) {
+  requireCondition(typeof connection?.requestRejection === 'function', 'DSH_BINDING_REQUIRED',
+    'ctx.connection.requestRejection is required for authenticated app-host routes.');
+  return {
+    authenticate: async request => connection.requestRejection(request) === undefined
+      ? { principalId: BROWSER_PRINCIPAL } : null,
+    // DSH web is single-user: an authenticated browser session may perform every app-host operation.
+    authorize: async (subject) => subject?.principalId === BROWSER_PRINCIPAL,
+  };
+}
+
+export async function apply(ctx, config) {
+  requireCondition(ctx && typeof ctx.get === 'function' && typeof ctx.provide === 'function' && typeof ctx.effect === 'function',
+    'DSH_BINDING_REQUIRED', 'apply() needs a Cordis plugin context; it cannot be called bare.');
+  const webServer = ctx.get('webServer'), facility = ctx.get('storageDomain'), connection = ctx.get('connection');
+  requireCondition(webServer && facility && connection, 'DSH_BINDING_REQUIRED', 'webServer, storageDomain and connection services are required.');
+  config ??= {};
+  const dataRoot = config.dataRoot ?? join(process.env.DSH_HOME ?? process.env.HOME ?? '.', 'data', 'hanamesh-apps');
+  requireCondition(typeof dataRoot === 'string', 'INVALID_ROOT', 'dataRoot is required.');
+  const parentOrigin = config.parentOrigin ?? `http://127.0.0.1:${webServer.port}`;
+  const domain = await facility.open(appHostDomainSpec);
+  let routerDomain,receiptsDomain,receipts,libraryDomain,library;
+  const store = new DshDomainSnapshotStore(domainBinding(domain));
+  const host = new AppHost({ store, dataRoot, parentOrigin, frameAncestors: config.frameAncestors ?? [],
+    ...(config.nodeBinary === undefined ? {} : { nodeBinary: config.nodeBinary }),
+    ...(config.leaseTtlMs === undefined ? {} : { leaseTtlMs: config.leaseTtlMs }),
+    ...(config.sweepIntervalMs === undefined ? {} : { sweepIntervalMs: config.sweepIntervalMs }) });
+  let initialized = false;
+  try {
+    for (const definition of config.applications ?? []) host.register(definition);
+    await host.init(); initialized = true;
+    const auth = { parentOrigin, ...browserAuthentication(connection) };
+    const handler = createHttpHandler(host, auth);
+    const disposers = ROUTES.map(path => webServer.register({ kind: 'exact', path, handler }));
+    let credentialService, llmService, oauthService, usageService;
+    ctx.inject(['credentials'], injected => { credentialService=injected.get('credentials');return()=>{credentialService=undefined;}; });
+    // rc.27: usage evidence goes through the usage plugin's record seat when (and only when) that plugin is loaded.
+    ctx.inject(['hanameshUsage'], injected => { usageService=injected.get('hanameshUsage');return()=>{usageService=undefined;}; });
+    // T6: hourly usage receipts live in app-host's own domain; the usage `use` event carries the hour's receipt.
+    receiptsDomain = await facility.open(receiptsDomainSpec);
+    receipts = createReceiptLedger({ domain:receiptsDomain });
+    const evidence = createUsageEvidence({ host, seat:()=>usageService, receipts, logger:ctx.logger });
+    ctx.effect(() => async () => { evidence.close(); await evidence.settle(); await receipts.close(); await receiptsDomain.close(); }, 'hanameshApps.usage');
+    ctx.inject(['llm'], injected => { llmService=injected.get('llm');return()=>{llmService=undefined;}; });
+    ctx.inject(['hanameshOAuth'], injected => { oauthService=injected.get('hanameshOAuth');return()=>{oauthService=undefined;}; });
+    const credentials = {
+      describe: async ref => credentialService ? await credentialService.describe(ref) : { configured:false,writable:false },
+      resolve: async ref => credentialService ? await credentialService.resolve(ref) : undefined,
+      describeRecord: async key => credentialService ? await credentialService.describeRecord(key) : { configured:false,writable:false },
+    };
+    routerDomain = await facility.open(routerDomainSpec);
+    const sources = createProviderSources({ credentials, apps:host, llm:()=>llmService,
+      webOrigin:`http://127.0.0.1:${webServer.port}`, codingOauth:config.router?.codingOauth });
+    const router = createRouter({ credentials, domain:routerDomain, apps:host, sources, oauth:()=>oauthService, receiptLedger:receipts,
+      onInject:({ appId, instanceId, routes }) => { receipts.inject({ appId, instanceId, routes }); } });
+    const detachResolver=host.setCredentialResolver(router.credentialResolver),detachObserver=host.subscribe(router.observe);
+    const routerHandler=createRouterHttpHandler(router,auth);
+    const routerDisposers=ROUTER_ROUTES.map(path=>webServer.register({kind:'exact',path,handler:routerHandler}));
+    libraryDomain=await facility.open(libraryDomainSpec);
+    // Explicit config wins; on plain DSH (no shell overlay) the profile, DSH bin and Node are inferred from this process.
+    const locations=await resolveLibraryLocations(config.library??{},{nodeBinary:config.nodeBinary});
+    const libraryConfig={...(config.library??{}),sources:locations.sources,profileDir:locations.profileDir,profileName:locations.profileName};
+    if(locations.inferred.length&&typeof ctx.logger?.info==='function')ctx.logger.info('hanamesh-app-host library: inferred %s',JSON.stringify(Object.fromEntries(
+      locations.inferred.map(key=>[key,key==='sources'?locations.sources.map(source=>source.manifestUrl):locations[key]]))));
+    let provisionApi,installer;
+    if(locations.profileDir&&locations.profileName&&locations.nodeBinary){
+      let dshBin=locations.dshBin;
+      if(!dshBin)try{dshBin=createRequire(join(locations.profileDir,'package.json')).resolve('@deepseek-ai/dsh/lib/bin.js');}catch{dshBin=undefined;}
+      if(dshBin){
+        provisionApi=await import('./provision/index.js');
+        installer=createLibraryInstaller({profileDir:locations.profileDir,profileName:locations.profileName,dataRoot,nodeBinary:locations.nodeBinary,
+          dshBin,registry:libraryConfig.registry,allowPrerelease:libraryConfig.allowPrerelease,provision:provisionApi.provision,remove:provisionApi.remove,
+          emit:event=>library?.emit(event)});
+      }
+    }
+    library=createLibraryService({domain:libraryDomain,host,config:libraryConfig,dataRoot,ledgerReader:provisionApi?.ledger??(async()=>({schema:1,items:{}})),installer});
+    await library.init();
+    // rc.27: app bundles register plain `app.json` (no package name); the installed scan knows which npm package ships
+    // which appId, and that package name is the usage-evidence `hanaRef`. Scan failure only costs evidence, never startup.
+    try { for (const row of await library.installed()) if (row.appId && row.packageName) { try { host.bindPackageName(row.appId,row.packageName); } catch {} } }
+    catch (error) { if (typeof ctx.logger?.debug === 'function') ctx.logger.debug('hanamesh-app-host usage: installed scan unavailable (%s)', error?.code ?? error?.message); }
+    const libraryHandler=createLibraryHttpHandler(library,auth);
+    const libraryDisposers=LIBRARY_ROUTES.map(path=>webServer.register({kind:'exact',path,handler:libraryHandler}));
+    ctx.effect(() => () => { for (const dispose of disposers.splice(0)) dispose(); }, 'hanameshApps.routes');
+    ctx.effect(() => async () => { for(const dispose of routerDisposers.splice(0))dispose();detachResolver();detachObserver();await routerDomain.close(); }, 'hanameshApps.router');
+    ctx.effect(() => async () => { for(const dispose of libraryDisposers.splice(0))dispose();await library.close(); }, 'hanameshApps.library');
+    ctx.provide('hanameshApps', host);
+  } catch (error) {
+    await library?.close().catch(()=>{});await libraryDomain?.close().catch(()=>{});await routerDomain?.close().catch(()=>{});await receipts?.close().catch(()=>{});await receiptsDomain?.close().catch(()=>{});
+    if (initialized) await host.dispose().catch(() => {}); else await store.close().catch(() => {});
+    throw error;
+  }
+  // Disposal order: routes go first (registered later, disposed earlier by Cordis), then the host
+  // stops every owned instance and closes the domain. An attached instance is never signalled.
+  ctx.effect(() => async () => { await host.dispose(); }, 'hanameshApps.dispose');
+}

package/dist/errors.js

@@ -0,0 +1,25 @@
+export class AppHostError extends Error {
+  constructor(code, message, details = {}, status = 409) {
+    super(message); this.name = 'AppHostError'; this.code = code;
+    this.details = details; this.status = status;
+  }
+}
+export function requireCondition(ok, code, message, details = {}, status = 400) {
+  if (!ok) throw new AppHostError(code, message, details, status);
+}
+export const copy = value => structuredClone(value);
+export class SerialQueue {
+  #tail = Promise.resolve();
+  run(fn) {
+    const result = this.#tail.then(fn);
+    this.#tail = result.catch(() => {});
+    return result;
+  }
+  async drained() { await this.#tail; }
+}
+export function bounded(promise, ms, label = 'Operation') {
+  let timer;
+  return Promise.race([promise, new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new AppHostError('TIMEOUT', `${label} timed out.`, {}, 504)), ms);
+  })]).finally(() => clearTimeout(timer));
+}