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

package/dist/provision/types.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Public types of @hanamesh/lib-provision.
+ *
+ * The manifest is authored by the caller; this library only executes it.
+ * Nothing here is ever guessed from the host machine except the platform key.
+ */
+/** Normalised `${process.platform}-${process.arch}` (e.g. `darwin-arm64`). */
+export type PlatformKey = string;
+export type SourceKind = 'https' | 'file';
+export interface ManifestSource {
+    /** Stable id, referenced by `sourceOrder` / `--source`. */
+    id: string;
+    kind: SourceKind;
+    /** Base URL. `https:` or `file:` only. Item assets are resolved relative to it. */
+    base: string;
+}
+export type ArchiveKind = 'tar.gz' | 'zip';
+export interface PlatformAsset {
+    /** File name (or relative path) appended to each source base, unless `url` is given. */
+    asset: string;
+    /** Lower-case hex sha256 of the archive. Mandatory: an item without it is refused. */
+    sha256: string;
+    /** Expected byte size (informational; used for progress totals and sanity checks). */
+    size?: number;
+    /** Leading path components to strip on extraction (like `tar --strip-components`). */
+    strip?: number;
+    /** Absolute `https:`/`file:` URL overriding `sources` resolution for this asset. */
+    url?: string;
+}
+export interface VerifySpec {
+    /** Path inside the extracted tree (after strip) of the executable to run. */
+    exec: string;
+    args?: string[];
+    /** Exact expected stdout (trimmed). Omit to only require exit code 0. */
+    expect?: string;
+    /** Timeout in ms (default 60000). */
+    timeoutMs?: number;
+}
+export interface ManifestItem {
+    id: string;
+    version: string;
+    kind: ArchiveKind;
+    /** Target directory relative to root (POSIX separators). */
+    installTo: string;
+    platforms: Record<PlatformKey, PlatformAsset>;
+    verify?: VerifySpec;
+}
+export interface Manifest {
+    schema: 1;
+    sources: ManifestSource[];
+    items: ManifestItem[];
+}
+export type PlanState = 'absent' | 'installed' | 'stale' | 'unsupported';
+export interface PlanEntry {
+    item: string;
+    version: string;
+    platform: PlatformKey;
+    /** Undefined when `state === 'unsupported'`. */
+    asset?: string;
+    sha256?: string;
+    /** Absolute target path (external form, never `\\?\`-prefixed). */
+    target: string;
+    state: PlanState;
+    /** Ledger entry currently recorded for this item, if any. */
+    current?: LedgerEntry;
+}
+export interface LedgerEntry {
+    version: string;
+    sha256: string;
+    platform: PlatformKey;
+    /** ISO-8601 timestamp. */
+    installedAt: string;
+    /** Absolute target path at install time (external form). */
+    target: string;
+    /** `installTo` relative to root; this is what `verify`/`remove` resolve against. */
+    installTo: string;
+    /** Source id (or `url` when the asset carried its own URL). */
+    source: string;
+}
+export interface Ledger {
+    schema: 1;
+    items: Record<string, LedgerEntry>;
+}
+export interface OwnedFile {
+    /** Relative POSIX path inside the target. */
+    path: string;
+    size: number;
+    sha256: string;
+    /** POSIX mode bits (0o777 mask). */
+    mode: number;
+}
+export interface OwnedSymlink {
+    path: string;
+    target: string;
+}
+/** `<target>.manifest.json` — the deletion authority for `remove`. */
+export interface OwnershipManifest {
+    schema: 1;
+    item: string;
+    version: string;
+    platform: PlatformKey;
+    /** sha256 of the archive this tree came from. */
+    sha256: string;
+    source: string;
+    installTo: string;
+    files: OwnedFile[];
+    dirs: string[];
+    symlinks: OwnedSymlink[];
+}
+export type ProgressPhase = 'download' | 'verify' | 'extract' | 'check' | 'promote';
+export interface ProgressEvent {
+    item: string;
+    phase: ProgressPhase;
+    bytes?: number | undefined;
+    total?: number | undefined;
+    /** Source id in use (download phase). */
+    source?: string | undefined;
+    /** Free-form note (e.g. `resume`, `source-failed`), never containing URL queries. */
+    note?: string | undefined;
+}
+export interface ProvisionOptions {
+    root: string;
+    platform?: PlatformKey;
+    onProgress?: (event: ProgressEvent) => void;
+    signal?: AbortSignal;
+    /** Source ids to try, in order. Unlisted sources are not used. Default: manifest order. */
+    sourceOrder?: string[];
+    /** Restrict to these item ids. */
+    only?: string[];
+    /** Re-install even when the ledger says the same sha256 is installed. */
+    force?: boolean;
+}
+export interface PlanOptions {
+    root: string;
+    platform?: PlatformKey;
+    only?: string[];
+}
+export type ProvisionAction = 'installed' | 'skipped' | 'unsupported';
+export interface ProvisionResult {
+    item: string;
+    version: string;
+    platform: PlatformKey;
+    target: string;
+    action: ProvisionAction;
+    sha256?: string;
+    source?: string;
+}
+export interface RemoveResult {
+    item: string;
+    target: string;
+    removedFiles: number;
+    removedSymlinks: number;
+    removedDirs: number;
+    /** Paths that were present in the target but not in the ownership manifest; left untouched. */
+    kept: string[];
+}
+export type VerifyState = 'ok' | 'repaired' | 'missing' | 'corrupt' | 'unmanaged';
+export interface VerifyItem {
+    item: string;
+    target: string;
+    state: VerifyState;
+    /** Human-readable detail (what was repaired / which file mismatched). */
+    detail?: string;
+    version?: string;
+    sha256?: string;
+}
+export interface VerifyResult {
+    root: string;
+    items: VerifyItem[];
+    /** True when every item is `ok` or `repaired`. */
+    ok: boolean;
+    /** Leftovers cleaned under `.provision/` (staging, trash, temp files). */
+    cleaned: string[];
+}

package/dist/provision/types.js

@@ -0,0 +1,7 @@
+/**
+ * Public types of @hanamesh/lib-provision.
+ *
+ * The manifest is authored by the caller; this library only executes it.
+ * Nothing here is ever guessed from the host machine except the platform key.
+ */
+export {};

package/dist/provision/zip.d.ts

@@ -0,0 +1,4 @@
+import type { ArchiveEntry } from './archive.js';
+export declare function crc32Update(crc: number, buf: Uint8Array): number;
+/** Read a zip via its central directory (the only trustworthy index). Store and deflate only. */
+export declare function readZip(file: string, item: string): AsyncGenerator<ArchiveEntry>;

package/dist/provision/zip.js

@@ -0,0 +1,194 @@
+import { createReadStream } from 'node:fs';
+import fs from 'node:fs/promises';
+import { createInflateRaw } from 'node:zlib';
+import { ProvisionError } from './errors.js';
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+export function crc32Update(crc, buf) {
+    let c = ~crc >>> 0;
+    for (let i = 0; i < buf.length; i++)
+        c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+    return ~c >>> 0;
+}
+const EOCD_SIG = 0x06054b50;
+const CEN_SIG = 0x02014b50;
+const LOC_SIG = 0x04034b50;
+const Z64_EOCD_SIG = 0x06064b50;
+const Z64_LOC_SIG = 0x07064b50;
+async function readRange(handle, offset, length) {
+    const buf = Buffer.alloc(length);
+    let done = 0;
+    while (done < length) {
+        const { bytesRead } = await handle.read(buf, done, length - done, offset + done);
+        if (bytesRead === 0)
+            break;
+        done += bytesRead;
+    }
+    return done === length ? buf : buf.subarray(0, done);
+}
+function parseZip64Extra(extra, need) {
+    let pos = 0;
+    while (pos + 4 <= extra.length) {
+        const id = extra.readUInt16LE(pos);
+        const len = extra.readUInt16LE(pos + 2);
+        if (id === 0x0001) {
+            const out = {};
+            let p = pos + 4;
+            if (need.size) {
+                out.size = Number(extra.readBigUInt64LE(p));
+                p += 8;
+            }
+            if (need.csize) {
+                out.compressedSize = Number(extra.readBigUInt64LE(p));
+                p += 8;
+            }
+            if (need.offset) {
+                out.localHeaderOffset = Number(extra.readBigUInt64LE(p));
+                p += 8;
+            }
+            return out;
+        }
+        pos += 4 + len;
+    }
+    return {};
+}
+async function readCentralDirectory(handle, fileSize, item) {
+    const tailLen = Math.min(fileSize, 65557);
+    const tail = await readRange(handle, fileSize - tailLen, tailLen);
+    let eocd = -1;
+    for (let i = tail.length - 22; i >= 0; i--) {
+        if (tail.readUInt32LE(i) === EOCD_SIG) {
+            eocd = i;
+            break;
+        }
+    }
+    if (eocd === -1)
+        throw new ProvisionError('E_ARCHIVE', 'zip: end of central directory not found', { item });
+    let count = tail.readUInt16LE(eocd + 10);
+    let cdSize = tail.readUInt32LE(eocd + 12);
+    let cdOffset = tail.readUInt32LE(eocd + 16);
+    if (count === 0xffff || cdSize === 0xffffffff || cdOffset === 0xffffffff) {
+        // ZIP64: locator sits right before the EOCD.
+        const locPos = eocd - 20;
+        if (locPos < 0 || tail.readUInt32LE(locPos) !== Z64_LOC_SIG)
+            throw new ProvisionError('E_ARCHIVE', 'zip64: locator missing', { item });
+        const z64Offset = Number(tail.readBigUInt64LE(locPos + 8));
+        const z64 = await readRange(handle, z64Offset, 56);
+        if (z64.readUInt32LE(0) !== Z64_EOCD_SIG)
+            throw new ProvisionError('E_ARCHIVE', 'zip64: EOCD record missing', { item });
+        count = Number(z64.readBigUInt64LE(32));
+        cdSize = Number(z64.readBigUInt64LE(40));
+        cdOffset = Number(z64.readBigUInt64LE(48));
+    }
+    const cd = await readRange(handle, cdOffset, cdSize);
+    const entries = [];
+    let pos = 0;
+    for (let i = 0; i < count; i++) {
+        if (pos + 46 > cd.length || cd.readUInt32LE(pos) !== CEN_SIG)
+            throw new ProvisionError('E_ARCHIVE', 'zip: central directory corrupt', { item });
+        const madeByHost = cd.readUInt16LE(pos + 4) >> 8;
+        const flags = cd.readUInt16LE(pos + 8);
+        const method = cd.readUInt16LE(pos + 10);
+        const crc32 = cd.readUInt32LE(pos + 16);
+        let compressedSize = cd.readUInt32LE(pos + 20);
+        let size = cd.readUInt32LE(pos + 24);
+        const nameLen = cd.readUInt16LE(pos + 28);
+        const extraLen = cd.readUInt16LE(pos + 30);
+        const commentLen = cd.readUInt16LE(pos + 32);
+        const externalAttrs = cd.readUInt32LE(pos + 38);
+        let localHeaderOffset = cd.readUInt32LE(pos + 42);
+        const nameBytes = cd.subarray(pos + 46, pos + 46 + nameLen);
+        const name = (flags & 0x800) !== 0 ? nameBytes.toString('utf8') : nameBytes.toString('latin1');
+        const extra = cd.subarray(pos + 46 + nameLen, pos + 46 + nameLen + extraLen);
+        const need = { size: size === 0xffffffff, csize: compressedSize === 0xffffffff, offset: localHeaderOffset === 0xffffffff };
+        if (need.size || need.csize || need.offset) {
+            const z = parseZip64Extra(extra, need);
+            if (z.size !== undefined)
+                size = z.size;
+            if (z.compressedSize !== undefined)
+                compressedSize = z.compressedSize;
+            if (z.localHeaderOffset !== undefined)
+                localHeaderOffset = z.localHeaderOffset;
+        }
+        entries.push({ name, method, crc32, compressedSize, size, localHeaderOffset, externalAttrs, madeByHost, flags });
+        pos += 46 + nameLen + extraLen + commentLen;
+    }
+    return entries;
+}
+const S_IFMT = 0o170000;
+const S_IFLNK = 0o120000;
+const S_IFDIR = 0o040000;
+/** Read a zip via its central directory (the only trustworthy index). Store and deflate only. */
+export async function* readZip(file, item) {
+    const handle = await fs.open(file, 'r');
+    try {
+        const { size: fileSize } = await handle.stat();
+        const entries = await readCentralDirectory(handle, fileSize, item);
+        for (const e of entries) {
+            if ((e.flags & 0x1) !== 0)
+                throw new ProvisionError('E_ARCHIVE', `zip: encrypted entry ${e.name}`, { item });
+            if (e.method !== 0 && e.method !== 8)
+                throw new ProvisionError('E_ARCHIVE', `zip: unsupported compression method ${e.method} for ${e.name}`, { item });
+            const local = await readRange(handle, e.localHeaderOffset, 30);
+            if (local.length < 30 || local.readUInt32LE(0) !== LOC_SIG)
+                throw new ProvisionError('E_ARCHIVE', `zip: local header corrupt for ${e.name}`, { item });
+            const dataOffset = e.localHeaderOffset + 30 + local.readUInt16LE(26) + local.readUInt16LE(28);
+            if (dataOffset + e.compressedSize > fileSize)
+                throw new ProvisionError('E_ARCHIVE', `zip: entry ${e.name} extends past end of file`, { item });
+            const unixMode = e.madeByHost === 3 ? (e.externalAttrs >>> 16) & 0o177777 : 0;
+            let kind;
+            if (e.name.endsWith('/') || (unixMode & S_IFMT) === S_IFDIR || (e.externalAttrs & 0x10) !== 0)
+                kind = 'dir';
+            else if ((unixMode & S_IFMT) === S_IFLNK)
+                kind = 'symlink';
+            else
+                kind = 'file';
+            const expectedCrc = e.crc32;
+            const expectedSize = e.size;
+            const makeBody = () => (async function* () {
+                if (kind === 'dir' || e.compressedSize === 0 && expectedSize === 0)
+                    return;
+                const raw = createReadStream(file, { start: dataOffset, end: dataOffset + e.compressedSize - 1, highWaterMark: 1 << 20 });
+                const stream = e.method === 8 ? raw.pipe(createInflateRaw()) : raw;
+                let crc = 0;
+                let n = 0;
+                for await (const chunk of stream) {
+                    const c = chunk;
+                    crc = crc32Update(crc, c);
+                    n += c.length;
+                    yield c;
+                }
+                if (n !== expectedSize)
+                    throw new ProvisionError('E_ARCHIVE', `zip: size mismatch for ${e.name}`, { item });
+                if (crc !== expectedCrc)
+                    throw new ProvisionError('E_ARCHIVE', `zip: crc32 mismatch for ${e.name}`, { item });
+            })();
+            const entry = {
+                kind,
+                name: kind === 'dir' && e.name.endsWith('/') ? e.name.slice(0, -1) : e.name,
+                mode: unixMode & 0o7777,
+                size: kind === 'file' ? expectedSize : 0,
+                body: makeBody(),
+            };
+            if (kind === 'symlink') {
+                const parts = [];
+                for await (const c of entry.body)
+                    parts.push(c);
+                entry.linkTarget = Buffer.concat(parts).toString('utf8');
+                entry.body = (async function* () { })();
+            }
+            yield entry;
+        }
+    }
+    finally {
+        await handle.close();
+    }
+}

package/dist/router/broker.js

@@ -0,0 +1,161 @@
+// Migrated from hanamesh-plugin-auth-apikey 8bb7ba7d2ac18a4dc3004674b5fc2b9aa5e3b0f5
+// source sha256 e903802b3d1473b643693634a0e3ffcf506b6006d2522c44553a6dc8b4a9e00e.
+// Detection, adoption and key mutation were intentionally not migrated: Router only grants existing providers.
+import { providerOf } from './sources.js';
+
+const REF=/^[A-Za-z_][A-Za-z_0-9]*$/, APP=/^[a-z0-9][a-z0-9-]*$/;
+const KEY=/^hanamesh-auth-oauth\/([a-z0-9-]+)--app-([a-z0-9-]+)$/;
+const error=code=>Object.assign(new Error(code),{code});
+export const entryId=entry=>entry.projection==='file'?`file:${entry.base??'home'}:${entry.path}`:`env:${entry.env}`;
+const emptyApp=()=>({mode:'managed',grants:{},ledger:{},revoked:{}});
+
+/** `onInject` (T6): called once per credentialResolver run that resolved at least one env route, with the routes in
+ *  declaration order `{providerId, model|null}` — the receipt ledger binds the instance to the first one. Never sees values. */
+export function createRouter({credentials,domain,apps,sources,oauth=()=>undefined,onInject=()=>{},receiptLedger}) {
+  let writing=Promise.resolve(); const instancePending=new Map();
+  const snapshot=()=>domain.global.get();
+  const appState=appId=>snapshot().apps[appId]??emptyApp();
+  function updateApp(appId,change){
+    const next=writing.then(async()=>{const old=snapshot(),app=structuredClone(old.apps[appId]??emptyApp());change(app);
+      await domain.global.set({...old,apps:{...old.apps,[appId]:app}});});writing=next.catch(()=>{});return next;
+  }
+  function declaration(appId){
+    if(!APP.test(appId))throw error('INVALID_APP');
+    const app=apps.list().apps.find(item=>item.id===appId);if(!app)throw error('APP_NOT_FOUND');
+    return app.deployments.filter(d=>d.mode==='owned').flatMap(d=>d.credentialEnv??[]);
+  }
+  const declared=(appId,id)=>declaration(appId).find(entry=>entryId(entry)===id);
+  function validSubject(entry,subject,appId){
+    if(!subject||!['api-key','provider','grant'].includes(subject.kind))throw error('INVALID_SUBJECT');
+    if(entry.kind&&entry.kind!==(subject.kind==='provider'?'api-key':subject.kind))throw error('SUBJECT_KIND_MISMATCH');
+    let provider;
+    if(subject.kind==='api-key'){if(!REF.test(subject.ref))throw error('INVALID_REF');provider=providerOf(subject.ref);}
+    if(subject.kind==='provider'){if(!/^[a-z0-9][a-z0-9-]*$/.test(subject.providerId))throw error('INVALID_PROVIDER');provider=subject.providerId;}
+    if(subject.kind==='grant'){
+      const match=KEY.exec(subject.key);if(!match||match[2]!==appId)throw error('CONSUMER_MISMATCH');provider=match[1];
+    }
+    if(!accepts(entry,provider))throw error('PROVIDER_MISMATCH');
+  }
+  async function providerDirectory(){return await sources.list();}
+  /** Providers an api-key entry accepts: its declared ids, plus the OpenAI-compatible Coding OAuth
+   *  gateway wherever `openai` is accepted (same wire protocol, `{{baseUrl}}` carries the difference). */
+  const accepts=(entry,providerId)=>!entry.providers?.length||entry.providers.includes(providerId)
+    ||(providerId==='coding-oauth-gateway'&&entry.providers.includes('openai'));
+  /** Auto-route (2026-09-21 contract): when the profile already holds a configured provider the entry accepts
+   *  and the user has not revoked it, the Router grants it without a click. Declared order wins; the gateway
+   *  is the last resort. Explicit grants and `app-owned` mode always take precedence. */
+  function autoSubject(entry,app,providers){
+    const id=entryId(entry);if(entry.kind!=='api-key'||entry.projection==='file'||app.revoked?.[id])return undefined;
+    // A slot that names no provider is filled by a sibling's `sets` (or by the app itself); the Router never guesses for it.
+    if(!entry.providers?.length)return undefined;
+    const configured=providers.filter(p=>p.state==='configured'&&accepts(entry,p.id));
+    const ordered=[...(entry.providers??[]).map(pid=>configured.find(p=>p.id===pid)).filter(Boolean),...configured.filter(p=>p.id==='coding-oauth-gateway')];
+    const found=ordered[0]??configured[0];if(!found)return undefined;
+    return found.ref?{kind:'api-key',ref:found.ref}:{kind:'provider',providerId:found.id};
+  }
+  /** The app's own default from `sets: {X:'{{model|<default>}}'}` — shown as「应用默认」in the routing table. */
+  function declaredDefaultModel(entry){
+    for(const value of Object.values(entry.sets??{})){const match=/\{\{model\|([^}]*)\}\}/.exec(value);if(match)return match[1];}
+    return undefined;
+  }
+  function template(value,vars){
+    return value.replace(/\{\{(provider|baseUrl|model)(?:\|([^}]*))?\}\}/g,(_,name,fallback)=>vars[name]||fallback||'');
+  }
+  const api={
+    providers:providerDirectory,
+    async enableGateway(enabled){return await sources.enableGateway(enabled);},
+    async mode(appId){declaration(appId);return appState(appId).mode;},
+    async setMode(appId,mode){declaration(appId);if(!['managed','app-owned'].includes(mode))throw error('INVALID_MODE');
+      await updateApp(appId,app=>{app.mode=mode;});},
+    async plan(appId){
+      const entries=declaration(appId),app=appState(appId),oauthProvider=oauth(),providers=await providerDirectory();
+      const oauthInfos=oauthProvider?await oauthProvider.providers():[];
+      const derived=new Set(entries.flatMap(entry=>Object.keys(entry.sets??{})));
+      const items=await Promise.all(entries.map(async entry=>{
+        const id=entryId(entry),grant=app.grants[id],item={entry,state:'missing'};
+        if(entry.env&&derived.has(entry.env))item.derived=true;
+        const defaultModel=declaredDefaultModel(entry);if(defaultModel)item.defaultModel=defaultModel;
+        if(app.mode==='app-owned'){item.state='app-owned';return item;}
+        if(grant){item.granted=grant.subject;if(grant.model)item.model=grant.model;
+          let present=false;
+          if(grant.subject.kind==='api-key')present=(await credentials.describe(grant.subject.ref)).configured;
+          if(grant.subject.kind==='provider')present=providers.some(p=>p.id===grant.subject.providerId&&p.state==='configured');
+          if(grant.subject.kind==='grant')present=!!oauthProvider&&(await credentials.describeRecord(grant.subject.key)).configured;
+          item.state=present?'granted':'missing';
+          if(grant.subject.kind==='grant'){item.riskNotice=oauthInfos.find(x=>x.id===KEY.exec(grant.subject.key)?.[1])?.riskNotice;item.projectedVersion=app.ledger[id]?.projectedVersion;}
+        }else{
+          const auto=autoSubject(entry,app,providers);
+          if(auto){item.granted=auto;item.auto=true;item.state='auto';}
+          else if(app.revoked?.[id])item.state='revoked';
+        }
+        const routed=item.granted&&(item.granted.kind==='provider'?providers.find(p=>p.id===item.granted.providerId):item.granted.kind==='api-key'?providers.find(p=>p.ref===item.granted.ref):undefined);
+        if(routed?.models?.length)item.models=routed.models;
+        return item;
+      }));return{appId,mode:app.mode,items};
+    },
+    async grant(appId,id,subject,opts={}){
+      const entry=declared(appId,id);if(!entry)throw error('ENTRY_UNKNOWN');validSubject(entry,subject,appId);
+      if(subject.kind==='grant'&&opts.riskAcknowledged!==true)throw error('RISK_NOT_ACKNOWLEDGED');
+      if(subject.kind==='provider'&&!((await providerDirectory()).some(p=>p.id===subject.providerId)))throw error('ROUTER_PROVIDER_ABSENT');
+      await updateApp(appId,app=>{app.grants[id]={subject,...(opts.model?{model:opts.model}:{}),grantedAt:new Date().toISOString(),riskAcknowledged:opts.riskAcknowledged===true};delete app.revoked?.[id];});
+      return await api.plan(appId);
+    },
+    /** Model rides with the route: set it on the routed slot (an auto-routed slot becomes an explicit grant of the same provider). '' = app default. */
+    async setModel(appId,id,model){
+      const entry=declared(appId,id);if(!entry)throw error('ENTRY_UNKNOWN');
+      if(typeof model!=='string'||model.length>200||/[\s]/.test(model))throw error('INVALID_MODEL');
+      const app=appState(appId),subject=app.grants[id]?.subject??autoSubject(entry,app,await providerDirectory());
+      if(!subject)throw error('ENTRY_NOT_ROUTED');
+      await updateApp(appId,app=>{const grant=app.grants[id]??{subject,grantedAt:new Date().toISOString(),riskAcknowledged:false};if(model)grant.model=model;else delete grant.model;app.grants[id]=grant;delete app.revoked?.[id];});
+      return await api.plan(appId);
+    },
+    /** T6: local receipt rows (hourly, content-free) for one app or all apps. */
+    receipts(appId){if(appId!==undefined)declaration(appId);return {items:receiptLedger?receiptLedger.list(appId===undefined?{}:{appId}):[]};},
+    async revoke(appId,id){if(!declared(appId,id))throw error('ENTRY_UNKNOWN');await updateApp(appId,app=>{delete app.grants[id];app.revoked??={};app.revoked[id]=true;});return await api.plan(appId);},
+    async credentialResolver(input){
+      await writing;const{appId,instanceId}=input,current=declaration(appId),byId=new Map(current.map(e=>[entryId(e),e]));
+      const app=appState(appId),env={},files=[],secrets=[],pending=new Map(),routes=[];
+      if(app.mode==='app-owned'){
+        for(const[id,ledger]of Object.entries(app.ledger))if(byId.has(id)&&id.startsWith('file:')&&(ledger.pendingVersion??ledger.projectedVersion)!==undefined&&ledger.removedForVersion!==(ledger.pendingVersion??ledger.projectedVersion))files.push({path:byId.get(id).path,policy:'remove'});
+        return files.length?{files}:undefined;
+      }
+      const applySets=(entry,vars)=>{for(const[name,value]of Object.entries(entry.sets??{}))if(byId.has('env:'+name)){const expanded=template(value,vars);if(expanded)env[name]=expanded;}};
+      const directory=await providerDirectory();
+      for(const entry of input.credentialEnv){
+        const id=entryId(entry),matched=byId.get(id);if(!matched||JSON.stringify(matched)!==JSON.stringify(entry))continue;
+        const auto=app.grants[id]?undefined:autoSubject(matched,app,directory),grant=app.grants[id]??(auto?{subject:auto}:undefined);if(!grant)continue;validSubject(entry,grant.subject,appId);
+        if(entry.projection==='file'){
+          if(grant.subject.kind!=='grant'||!oauth())continue;if(!(await credentials.describeRecord(grant.subject.key)).configured)continue;
+          const projection=await oauth().project(grant.subject.key,entry.format);if(typeof projection.content!=='string')continue;
+          const version=projection.version,old=app.ledger[id];files.push({path:entry.path,content:projection.content,policy:(old?.pendingVersion??old?.projectedVersion)===version?'if-absent':'overwrite'});
+          pending.set(id,version);secrets.push(projection.content);applySets(entry,{provider:KEY.exec(grant.subject.key)?.[1]??'',baseUrl:'',model:grant.model??''});
+        }else if(entry.env&&['api-key','provider'].includes(grant.subject.kind)){
+          const resolved=await sources.resolve(grant.subject);if(!resolved?.value)continue;
+          env[entry.env]=resolved.value;secrets.push(resolved.value);
+          // Model choice belongs to the app (`{{model|<app default>}}`); the Router only carries an explicitly granted model.
+          const provider=resolved.provider??{};
+          applySets(entry,{provider:provider.id??'',baseUrl:provider.baseUrl??'',model:grant.model??''});
+          if(provider.id)routes.push({providerId:provider.id,model:grant.model??declaredDefaultModel(entry)??null});
+        }else if(entry.env&&grant.subject.kind==='grant'&&oauth()){
+          const projection=await oauth().project(grant.subject.key,'env');if(projection.format==='env'&&typeof projection.env[entry.env]==='string'){
+            env[entry.env]=projection.env[entry.env];secrets.push(projection.env[entry.env]);applySets(entry,{provider:KEY.exec(grant.subject.key)?.[1]??'',baseUrl:'',model:grant.model??''});
+            const oauthProvider=KEY.exec(grant.subject.key)?.[1];if(oauthProvider)routes.push({providerId:oauthProvider,model:grant.model??declaredDefaultModel(entry)??null});
+          }
+        }
+      }
+      for(const[id,ledger]of Object.entries(app.ledger))if(id.startsWith('file:')&&byId.has(id)&&!app.grants[id]&&(ledger.pendingVersion??ledger.projectedVersion)!==undefined&&ledger.removedForVersion!==(ledger.pendingVersion??ledger.projectedVersion))files.push({path:byId.get(id).path,policy:'remove'});
+      if(pending.size){await updateApp(appId,app=>{for(const[id,version]of pending)app.ledger[id]={...app.ledger[id],pendingVersion:version,pendingInstanceId:instanceId};});instancePending.set(instanceId,{appId,pending});}
+      // T6: receipts learn the route here, never the value. A failing observer must not block the launch.
+      if(routes.length){try{onInject({appId,instanceId,routes});}catch{}}
+      return Object.keys(env).length||files.length?{env,files,secrets}:undefined;
+    },
+    async observe(event){
+      if(!['credential.injected','credential.file-removed'].includes(event.type))return;
+      const pending=instancePending.get(event.instanceId),appId=pending?.appId??Object.keys(snapshot().apps).find(id=>Object.entries(appState(id).ledger).some(([key,ledger])=>key.startsWith('file:')&&(ledger.pendingInstanceId===event.instanceId||event.names?.includes(`file:${key.split(':').slice(2).join(':')}`))));
+      if(!appId)return;
+      for(const name of event.names??[]){if(!name.startsWith('file:'))continue;const id=Object.keys(appState(appId).ledger).concat([...pending?.pending.keys()??[]]).find(key=>key.startsWith('file:')&&`file:${key.split(':').slice(2).join(':')}`===name);if(!id)continue;
+        await updateApp(appId,app=>{const ledger=app.ledger[id]??{};if(event.type==='credential.injected'&&ledger.pendingInstanceId===event.instanceId){ledger.projectedVersion=ledger.pendingVersion;delete ledger.removedForVersion;}if(event.type==='credential.file-removed')ledger.removedForVersion=ledger.pendingVersion??ledger.projectedVersion;app.ledger[id]=ledger;});}
+    },
+  };
+  return api;
+}

package/dist/router/domain.js

@@ -0,0 +1,18 @@
+import { z } from 'zod';
+import { defineDomain } from '@deepseek-ai/dsh-storage-domain';
+
+const subject = z.union([
+  z.object({ kind:z.literal('api-key'), ref:z.string() }),
+  z.object({ kind:z.literal('provider'), providerId:z.string() }),
+  z.object({ kind:z.literal('grant'), key:z.string() }),
+]);
+const ledger = z.object({ projectedVersion:z.number().optional(), pendingVersion:z.number().optional(),
+  pendingInstanceId:z.string().optional(), removedForVersion:z.number().optional() });
+export const routerDomainSpec = defineDomain({
+  name:'hanamesh_router', version:1, layout:'single', tables:{},
+  global:{ schema:z.object({ schema:z.literal(1), apps:z.record(z.string(),z.object({
+    mode:z.enum(['managed','app-owned']), grants:z.record(z.string(),z.object({
+      subject, model:z.string().optional(), grantedAt:z.string(), riskAcknowledged:z.boolean(),
+    })), ledger:z.record(z.string(),ledger), revoked:z.record(z.string(),z.boolean()).optional(),
+  })) }), initial:{ schema:1, apps:{} } },
+});

package/dist/router/receipts-domain.js

@@ -0,0 +1,8 @@
+import { defineDomain } from '@deepseek-ai/dsh-storage-domain';
+import { receiptsGlobalSchema, receiptsGlobalInitial } from './receipts.js';
+
+/** DSH-only: opened by the plugin entry (`src/dsh.js`), never by the library entry. */
+export const receiptsDomainSpec = defineDomain({
+  name:'hanamesh_router_receipts', version:1, layout:'single', tables:{},
+  global:{ schema:receiptsGlobalSchema, initial:receiptsGlobalInitial },
+});