@wingsky-1/dsh-decision-gateway 0.2.6

package/lib/server/tools/impl/service.d.ts

@@ -0,0 +1,18 @@
+import type { CustomPreset, DecideOutput, ErrorEnvelope } from "../../../shared/interface.js";
+import type { DecideDeps } from "../deps.js";
+/** 执行一次决议（纯编排；副作用仅经注入 deps 发生）。 */
+export declare function decide(args: unknown, deps: DecideDeps): Promise<DecideOutput | ErrorEnvelope>;
+/** 预设清单（只读；frozen 规范 + 自建 customs，开关/上限取配置快照）。 */
+export declare function listPresets(deps: {
+    readonly isEnabled: (presetId: string) => boolean;
+    readonly capOf: (presetId: string) => number;
+    readonly customs?: readonly CustomPreset[];
+}): readonly {
+    readonly id: string;
+    readonly enabled: boolean;
+    readonly templateVersion: 1;
+    readonly automationCap: number;
+    readonly label: string;
+    readonly description: string;
+    readonly custom: boolean;
+}[];

package/lib/server/tools/impl/validate.d.ts

@@ -0,0 +1,17 @@
+import type { CustomPreset } from "../../../shared/interface.js";
+import type { ValidDecide } from "../deps.js";
+/** 校验失败（调用方映射为 400/ErrorEnvelope，不抛）。 */
+export interface DecideValidationFailure {
+    readonly errorCode: string;
+    readonly message: string;
+}
+type Invalid = {
+    readonly ok: false;
+    readonly failure: DecideValidationFailure;
+};
+/** ws_request_verdict 参数校验（成功即 ValidDecide，失败即 400 类错误；custom 自建 id 经第二参传入）。 */
+export declare function validateDecideArgs(args: unknown, custom?: ReadonlyMap<string, CustomPreset>): {
+    readonly ok: true;
+    readonly valid: ValidDecide;
+} | Invalid;
+export {};

package/lib/server/tools/interface.d.ts

@@ -0,0 +1,7 @@
+/** tools 域门面：只转出组合根实际用的符号（无逻辑）。probeConnection 见 impl/probe.ts。 */
+export type { DecideDeps, FetchImpl } from "./deps.js";
+export { callWithRetry, defaultFetchImpl } from "./impl/client.js";
+export { createSemaphore } from "./impl/semaphore.js";
+export { decide, listPresets } from "./impl/service.js";
+export { buildToolDefinitions, rootOf, sessionOf } from "./impl/define.js";
+export { probeConnection } from "./impl/probe.js";

package/lib/server/upgrade/deps.d.ts

@@ -0,0 +1,37 @@
+/** upgrade 域出口：注入面（纯类型，零运行时）。落盘原语由组合根从 store 域装配，本域不直引他域实现。 */
+/** 最小日志面。 */
+export interface LoggerPort {
+    readonly warn: (message: string) => void;
+    readonly info?: (message: string) => void;
+}
+/** 迁移所需落盘原语面。 */
+export interface UpgradeIoPorts {
+    readonly readJsonSync: (file: string) => {
+        readonly ok: true;
+        readonly value: unknown;
+    } | {
+        readonly ok: false;
+    };
+    readonly readTextSync: (file: string) => {
+        readonly ok: true;
+        readonly text: string;
+    } | {
+        readonly ok: false;
+    };
+    readonly atomicWrite0600Sync: (file: string, text: string) => void;
+    readonly listFilesSync: (dir: string) => string[];
+}
+/** 种子文件内容（默认值唯一事实源在 config 域 model，组合根装配时传入，本域不直引）。 */
+export interface SeedFiles {
+    readonly configJson: string;
+    readonly presetsJson: string;
+    readonly secretsJson: string;
+}
+/** upgrade 域运行所需注入（home 缺席即 DSH home；targetOverride 仅单测定版）。 */
+export interface UpgradeDeps {
+    readonly io: UpgradeIoPorts;
+    readonly logger: LoggerPort;
+    readonly home?: string;
+    readonly targetOverride?: string;
+    readonly seedDefaults: () => SeedFiles;
+}

package/lib/server/upgrade/impl/service.d.ts

@@ -0,0 +1,13 @@
+import type { UpgradeDeps } from "../deps.js";
+/** 存储目标刻度（与包版本独立：它是磁盘形态刻度，不是发布版本）。 */
+export declare const STORAGE_TARGET = "0.2.6";
+/** 迁移报告。 */
+export interface MigrateReport {
+    readonly from: string;
+    readonly to: string;
+    readonly seeded: string[];
+}
+/** 跑迁移链（同步；抛错即装配失败，不写刻度，下次启动重跑同一步）。 */
+export declare function migrate(deps: UpgradeDeps): MigrateReport;
+/** 装配升级域（同步跑完迁移链；失败即抛，apply 随之失败）。门面只转出本函数。 */
+export declare function installUpgrade(deps: UpgradeDeps): MigrateReport;

package/lib/server/upgrade/impl/steps.d.ts

@@ -0,0 +1,3 @@
+import type { SeedFiles, UpgradeIoPorts } from "../deps.js";
+/** 缺失即种（返回新建文件名；已存在即跳过）。 */
+export declare function ensureSeeded(home: string | undefined, seed: SeedFiles, io: UpgradeIoPorts): string[];

package/lib/server/upgrade/interface.d.ts

@@ -0,0 +1,6 @@
+/**
+ * upgrade 域门面：只转出组合根实际用的符号（installUpgrade），无逻辑。
+ *
+ * 本域必须在各域装配之前跑（动磁盘者在先）：先跑完存储锚定，各域才读得到 canonical 形态。
+ */
+export { installUpgrade } from "./impl/service.js";

package/lib/shared/contract.d.ts

@@ -0,0 +1,184 @@
+/**
+ * dsh-decision-gateway 双端共享契约（纯模块：零 import，宿主 tsc 直连、客户端 esbuild 直连）。
+ *
+ * 两端必须一致，谁也不许单方面改；缺口上报主代理。
+ * 主代理裁决（已落实）：automationCap 用 0|1|2（0=none,1=low,2=high）；
+ * GET /config 返回裸 v1 掩码体，两端同时兼容裸体与 {config}/{data} 包装；
+ * 失败体必须同时含 errorCode + category（error/code 可选）。
+ */
+/** 插件在 DSH home 下的独立命名空间目录（与其它插件隔离）。 */
+export declare const PACKAGE_DIR = "@wingsky-1/dsh-decision-gateway";
+/** 配置版本（config.json version 字段唯一合法值）。 */
+export declare const CONFIG_VERSION = 1;
+/** 预设模板版本（5 预设 frozen，templateVersion 恒为 1）。 */
+export declare const TEMPLATE_VERSION = 1;
+/** 官方 SystemOne 基址（写死常量；加载断言防篡改，PUT 拒收 baseUrl 类键；JEV_ 前缀专属首个提供方 JEV，网关通用概念已去 JEV 化，此标识符与值双写死保留）。 */
+export declare const JEV_BASE_URL = "https://api.typesafe.ai/v1/systemone";
+/** 官方 SystemOne 默认模型（冻结别名；与 JEV_BASE_URL 同等 pin 待遇，不接受配置覆盖；JEV_ 前缀专属首个提供方 JEV 的模型 pin 位，此标识符与值双写死保留）。 */
+export declare const JEV_MODEL = "jev-latest";
+/** 存储文件名（命名空间目录下独立四文件 + 版本刻度；custom-presets.json 缺席即空列表）。 */
+export declare const CONFIG_FILE_NAME = "config.json";
+export declare const PRESETS_FILE_NAME = "presets.json";
+export declare const SECRETS_FILE_NAME = "secrets.json";
+export declare const CUSTOM_PRESETS_FILE_NAME = "custom-presets.json";
+export declare const VERSION_FILE_NAME = "VERSION";
+/** 回环路由表（宿主 ROUTES 单一事实源经构建期注入客户端；此处常量是宿主侧定义）。 */
+export declare const ROUTES: {
+    readonly health: "/api/dsh-decision-gateway/health";
+    readonly config: "/api/dsh-decision-gateway/config";
+    readonly presets: "/api/dsh-decision-gateway/presets";
+    readonly history: "/api/dsh-decision-gateway/history";
+    readonly testConnection: "/api/dsh-decision-gateway/test-connection";
+};
+/** ENV 引用名形状（与客户端 validApiKeyRef 同正则）。 */
+export declare const API_KEY_REF_RE: RegExp;
+/** preset id 形状（ASCII 小写+数字+连字符；中文直接 400）。 */
+export declare const PRESET_ID_RE: RegExp;
+/** question id 形状（同上）。 */
+export declare const QUESTION_ID_RE: RegExp;
+/** 会话 id 形状（落盘文件名安全集）。 */
+export declare const SESSION_ID_RE: RegExp;
+/** CJK 探测（preset/question id 含中文即 400；state 正文不受此限）。 */
+export declare const CJK_RE: RegExp;
+/** 已退役配置键（加载迁移时剥离并告警；PUT 显式拒收 400）。 */
+export declare const RETIRED_KEYS: readonly ["baseUrl", "apiBaseUrl", "endpoint", "apiEndpoint", "url"];
+/** 单题文本上限（codepoints；超限 400）。 */
+export declare const MAX_QUESTION_TEXT = 255;
+/** 单次 override 最多题数。 */
+export declare const MAX_QUESTIONS = 20;
+/** 历史 snippet 上限（字；超限截断）。 */
+export declare const SNIPPET_MAX = 200;
+/** 状态语言（state.lang 全集；缺席默认为 unknown，仅非法值 400）。 */
+export type DecisionLang = "en" | "zh" | "unknown";
+/** 置信分层。 */
+export type DecisionTier = "none" | "high" | "low";
+/** 自动化上限/分级：0=none（只人工），1=low，2=high。 */
+export type AutomationCap = 0 | 1 | 2;
+/** 自动化实际等级（suggest-only：输入被截断时的强制降级，仅建议不执行；local-precheck 的 manual 不受影响）。 */
+export type AutomationLevel = "manual" | "assisted" | "auto" | "suggest-only";
+/** frozen 预设模板：只存英文出题规范（一段自由描述），不存固定考题。调用方每次经 questions_override 自带全量题目。 */
+export interface PresetTemplate {
+    readonly id: string;
+    readonly label: string;
+    /** English asking guide: goal, dimensions, mutual exclusion, good vs bad asking examples, prohibitions, how to call. Free-form prose, length-checked only. */
+    readonly description: string;
+    readonly defaultEnabled: boolean;
+    readonly automationCap: AutomationCap;
+}
+/** 5 预设 frozen 规范（secret-leak 默认关闭；模板零考题）。 */
+export declare const FROZEN_PRESETS: readonly PresetTemplate[];
+/** 自建自定义预设存储版本（custom-presets.json version 字段唯一合法值）。 */
+export declare const CUSTOM_PRESETS_VERSION = 1;
+/** 自定义预设上限（条）。 */
+export declare const MAX_CUSTOM_PRESETS = 50;
+/** 自定义名上限（codepoints）。 */
+export declare const MAX_CUSTOM_LABEL = 64;
+/** 自定义描述上限（codepoints，超限 400）。 */
+export declare const MAX_CUSTOM_DESCRIPTION = 2000;
+/** 用户自建预设（单 description 英文自由文本，可抄 frozen 写作约定，也可自由发挥；题目永随调用传入，不存）。 */
+export interface CustomPreset {
+    readonly id: string;
+    readonly label: string;
+    readonly description: string;
+    readonly enabled: boolean;
+    readonly automationCap: AutomationCap;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+}
+/** 按 id 取 frozen 模板（无则 undefined）。 */
+export declare function frozenPresetOf(id: string): PresetTemplate | undefined;
+/** 配置 v1（connection 无明文、无 BaseURL；密钥只经 secrets.json/ENV）。 */
+export interface ConfigV1 {
+    readonly version: 1;
+    readonly connection: {
+        readonly apiKeyRef?: string;
+        readonly hasPlaintextKey: boolean;
+        readonly timeoutMs: number;
+        readonly maxConcurrency: number;
+        readonly truncBudget: number;
+    };
+    readonly presets: readonly {
+        readonly id: string;
+        readonly enabled: boolean;
+        readonly automationCap: AutomationCap;
+    }[];
+    readonly history: {
+        readonly perSession: number;
+        readonly totalSessions: number;
+    };
+}
+/** 历史条目快照的问题（调用方传入原样存档；文本/选项/分档经同 snippet 的脱敏后存）。 */
+export interface HistoryQuestion {
+    readonly id: string;
+    readonly text: string;
+    readonly kind: "choice" | "score";
+    readonly options?: readonly string[];
+    readonly levels?: readonly string[];
+}
+/** 历史条目（任务契约；原始密钥永不入库，snippetRedacted≤200；questions 为调用题目快照）。 */
+export interface HistoryEntry {
+    readonly ts: number;
+    readonly rootHash: string;
+    /** 仅 basename。 */
+    readonly rootDisplay: string;
+    readonly sessionId: string;
+    readonly presetId: string;
+    readonly templateVersion: number;
+    readonly stateHash: string;
+    readonly snippetRedacted: string;
+    readonly lang: DecisionLang;
+    readonly truncated: boolean;
+    readonly originalLength: number;
+    readonly resultKind: string;
+    readonly choice?: string;
+    readonly score?: number;
+    readonly confidence: number;
+    readonly tier: DecisionTier;
+    readonly automation: AutomationLevel;
+    readonly provider: "official";
+    readonly latencyMs: number;
+    readonly errorCode?: string;
+    readonly questions?: readonly HistoryQuestion[];
+    /** 读取时 enrich 的展示标题（只存 id，缺失回退短 id）；永不落盘。 */
+    readonly presetTitle?: string;
+    /** 读取时 enrich 的会话标题（只读活会话快照，无标题/服务缺席回落短 id）；永不落盘。 */
+    readonly sessionTitle?: string;
+}
+/** 成功输出必带字段（provider/appliedSource/truncated/originalLength/tier/automation/计费 codepoints/重试次数）。 */
+export interface DecideOutput {
+    readonly ok: true;
+    readonly provider: "official";
+    readonly appliedSource: "override" | "custom" | "local-precheck";
+    readonly truncated: boolean;
+    readonly originalLength: number;
+    readonly tier: DecisionTier;
+    readonly automation: AutomationLevel;
+    readonly codepoints: number;
+    readonly retries: number;
+    readonly latencyMs: number;
+    readonly resultKind: string;
+    readonly choice?: string;
+    readonly score?: number;
+    readonly confidence: number;
+}
+/** 失败包络（无概率字段；必含 errorCode + category 供客户端 failureCategory 识别）。 */
+export interface ErrorEnvelope {
+    readonly ok: false;
+    readonly error: {
+        readonly errorCode: string;
+        readonly category: string;
+        readonly message: string;
+    };
+}
+/** 密钥形状类别（400 仅回此类别，原文永不回显）。 */
+export type KeyShapeCategory = "empty" | "too-short" | "charset";
+/** 密钥形状判定（有效：16-256 位可见字符集、含字母、非全大写长串；返回 null 即有效）。 */
+export declare function keyShapeCategory(key: string): KeyShapeCategory | null;
+/** 按 codepoints 截断（中文按字不断字节）。 */
+export declare function truncateCodePoints(text: string, budget: number): {
+    readonly text: string;
+    readonly truncated: boolean;
+    readonly originalLength: number;
+};
+/** id 是否含 CJK（含即中文 400）。 */
+export declare function containsCjk(text: string): boolean;

package/lib/shared/interface.d.ts

@@ -0,0 +1,7 @@
+/**
+ * dsh-decision-gateway 双端共享面门面（跨模块引用唯一入口；本文件只转出、不放实现）。
+ *
+ * 同级模块构建硬约束：本目录仅 contract.ts 一个纯模块（零 import）。
+ */
+export { API_KEY_REF_RE, CJK_RE, CONFIG_FILE_NAME, CONFIG_VERSION, CUSTOM_PRESETS_VERSION, JEV_BASE_URL, JEV_MODEL, MAX_CUSTOM_DESCRIPTION, MAX_CUSTOM_LABEL, MAX_CUSTOM_PRESETS, MAX_QUESTIONS, MAX_QUESTION_TEXT, PACKAGE_DIR, PRESETS_FILE_NAME, PRESET_ID_RE, QUESTION_ID_RE, RETIRED_KEYS, ROUTES, SECRETS_FILE_NAME, SESSION_ID_RE, SNIPPET_MAX, TEMPLATE_VERSION, CUSTOM_PRESETS_FILE_NAME, VERSION_FILE_NAME, FROZEN_PRESETS, containsCjk, frozenPresetOf, keyShapeCategory, truncateCodePoints, } from "./contract.js";
+export type { AutomationCap, AutomationLevel, ConfigV1, CustomPreset, DecideOutput, ErrorEnvelope, HistoryEntry, HistoryQuestion, DecisionLang, DecisionTier, KeyShapeCategory, PresetTemplate, } from "./contract.js";

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@wingsky-1/dsh-decision-gateway",
+  "version": "0.2.6",
+  "description": "Decision gateway for DSH agents: calibrated Choice/Score/Noul verdicts via ws_request_verdict + local secret precheck + dual-track keys. 通用辅助决策网关（JEV 为首个 provider）：frozen 预设模板 + 密钥双轨（ENV 引用优先）+ 本地密形预检 + SystemOne 官方调用，工具 ws_request_verdict / ws_list_verdict_guides",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml",
+      "bannerJs": "import { createRequire as __decisionGatewayRequire } from \"node:module\";\nconst require = __decisionGatewayRequire(import.meta.url);"
+    },
+    "catalog": {
+      "category": "tool",
+      "summary": {
+        "en": "Calibrated assistant decisions (Choice/Score/Noul) for DSH agents with local secret precheck; JEV is the first provider.",
+        "zh": "给 DSH agent 的校准辅助决策（Choice/Score/Noul），本地密形预检，双轨密钥；JEV 为首个提供方。"
+      },
+      "capabilities": [
+        "connection",
+        "decide"
+      ]
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection"
+      ],
+      "platform": "web"
+    }
+  },
+  "files": [
+    "lib",
+    "shared/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-host-webserver": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
+    "@typesafe-ai/sdk": "0.6.0"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.4",
+    "@deepseek-ai/dsh-host-webserver": "0.1.7-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-host-webserver": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-tools": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wingsky-1/dsh-plugin-hub.git",
+    "directory": "packages/dsh-decision-gateway"
+  },
+  "bugs": {
+    "url": "https://github.com/wingsky-1/dsh-plugin-hub/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "plugin",
+    "decision",
+    "gateway"
+  ],
+  "author": "wingsky-1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build/clean-lib.ts && tsc -p tsconfig.json && node ../../scripts/build/bundle-host.ts .",
+    "test": "node ../../scripts/test/run-vitest.mjs --min 23",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/shared/client/ensure-style.d.ts

@@ -0,0 +1,21 @@
+/** ensureStyle 参数（issue #477 v2 契约）。 */
+export interface EnsureStyleOptions {
+  /** <style> 幂等键（package-owned 命名空间，统一 `dsh-<pkg>-style` 前缀隔离）。 */
+  id: string;
+  /** 样式文本（构建期 text-loader 内联的 style.css 内容）。 */
+  cssText: string;
+  /** 可选版本号：写入 dataset.version；变化时旧节点 remove 后重建（热更新失效）。 */
+  version?: string;
+}
+
+/**
+ * 按 id 幂等注入 <style> 节点（5 包统一样式注入入口，issue #477 收敛）。
+ *
+ * 行为契约：
+ * - head 缺失（document.head == null）静默早退 no-op 不抛；
+ * - 同 id 已存在且 version 未变（或未传）→ 不动现有节点；version 变化 → 重建；
+ * - 无 version 不写 dataset.version；
+ * - 返回 disposer（remove 该 id 节点；节点不存在时 no-op），卸载后再次调用
+ *   ensureStyle 重新注入。
+ */
+export declare function ensureStyle(options: EnsureStyleOptions): () => void;

package/shared/client/i18n.d.ts

@@ -0,0 +1,15 @@
+/** 翻译函数形态（与官方 Translate 一致：key + {name} 占位参数）。 */
+export declare type TranslateFn = (key: string, params?: Record<string, unknown>) => string;
+
+/**
+ * 当前翻译函数（apply 时由各包 index.ts 经 bindLocale 装配）。
+ * 未装配时回落 key 本体（行为零变化）。
+ */
+export declare let t: TranslateFn;
+
+/**
+ * 装配/重绑翻译函数（官方 ctx.locale.bind(ns) 产物；语言切换 subscribe 内重调）。
+ * @param locale 宿主 locale 服务（须实现 bind）。
+ * @param ns 本插件字典命名空间。
+ */
+export declare function bindLocale(locale: any, ns: string): void;

package/shared/dsh-home.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 用户 home 目录（`~` 的展开目标）：`HOME` 非空白原样采用，未设置或空白回落
+ * `os.homedir()`；Windows 以 `USERPROFILE` 优先（对齐 libuv）。显式读 env 而非
+ * 直接 `os.homedir()`，是因为后者读进程级 environ，在 worker_threads（Stryker
+ * 的 vitest-runner 强制 `pool: 'threads'`）下无法被测试的 `process.env.HOME` 隔离；
+ * 取值次序与 libuv 一致，默认形态逐字节不变。
+ */
+export declare function userHome(): string;
+
+/**
+ * DSH home 解析（单一事实源）：`DSH_HOME` 非空白原样采用；未设置或空白回落
+ * `~/.dsh`（默认形态路径逐字节不变）。语义对齐官方
+ * `@deepseek-ai/dsh-home-paths#resolveDshHome`（空白 env 视同未设置）。
+ */
+export declare function dshHome(): string;

package/shared/host-utils.d.ts

@@ -0,0 +1,65 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LoopbackOptions } from "./loopback.d.ts";
+
+/** 写 JSON 响应（统一带 referrer-policy 头，防 referrer 泄露）。 */
+export declare function writeJson(res: ServerResponse, status: number, payload: unknown): void;
+
+/**
+ * 序列化一帧 SSE data 行（输出形如 `data: <json>\n\n`）。
+ * undefined / 含换行 payload 行为对齐三包历史实现、非承诺契约（#472）。
+ */
+export declare function sseData(payload: unknown): string;
+
+/** 请求体读不出来的具体成因：供端点在失败文案里说清是哪一种。 */
+export type JsonBodyInvalidReason = "too-large" | "unreadable" | "malformed" | "not-object";
+
+/** `readJsonBodyOutcome` 的成因可辨结果：缺席（可选 body 未给）/ 合法对象 / 非法（带具体成因）。 */
+export type JsonBodyOutcome =
+  | { kind: "absent" }
+  | { kind: "json"; value: object }
+  | { kind: "invalid"; reason: JsonBodyInvalidReason };
+
+/**
+ * 读请求 body（JSON）并保留失败成因：需要 fail-closed 的端点用它（畸形 body 不能被当成「没有 body」，
+ * 否则有副作用的端点会拿垃圾输入触发真实动作）。
+ * @param limit 字节上限（默认 2MB）。
+ */
+export declare function readJsonBodyOutcome(
+  req: IncomingMessage,
+  limit?: number,
+): Promise<JsonBodyOutcome>;
+
+/**
+ * 宽松读请求 body（JSON）：解析失败或超限返回 undefined（不抛错），由调用方决定响应。
+ * 成因不可辨——要区分「缺席」与「非法」用 `readJsonBodyOutcome`。
+ * @param limit 字节上限（默认 2MB）。
+ */
+export declare function readJsonBody(
+  req: IncomingMessage,
+  limit?: number,
+): Promise<object | undefined>;
+
+/** 把任意抛出的值转成可读错误消息。 */
+export declare function errorMessage(error: unknown): string;
+
+/**
+ * 读请求 body（JSON，限长防滥用）。
+ * 兼容 Node 事件流（data/end）与 async-iterator 桩两种形态。
+ * @param limit 字节上限（默认 256KB）。
+ */
+export declare function readBody(req: IncomingMessage, limit?: number): Promise<object>;
+
+/**
+ * Loopback + 方法白名单低阶路由守卫：非 loopback → 403，方法不在白名单 → 405，
+ * 否则放行（403 先于 405 为本守卫执行顺序，仅对套守卫端点成立）。
+ * @param methods 允许的 HTTP 方法白名单。
+ * @param loopbackOptions 透传给 isLoopbackRequest 的可选判定参数（#549：仅
+ *   serve 资源路由放行 cross-site no-cors 子资源时使用；其余路由不得传）。
+ * @returns 是否放行（true 时调用方继续处理请求）。
+ */
+export declare function guardLoopbackMethod(
+  req: IncomingMessage,
+  res: ServerResponse,
+  methods: string[],
+  loopbackOptions?: LoopbackOptions,
+): boolean;

package/shared/loopback.d.ts

@@ -0,0 +1,21 @@
+import type { IncomingMessage } from "node:http";
+
+/**
+ * Loopback 围栏判定参数。
+ * - allowCrossSiteNoCors（#549）：仅 serve 类资源伺服路由使用——放行「显式
+ *   sec-fetch-mode: no-cors」的跨站子资源请求（sandbox iframe opaque origin
+ *   的相对路径 css/js/img 加载）；cors fetch/XHR 与 navigate 仍拒绝。
+ *   普通 /api 路由必须保持默认（不传 options）拒绝一切 cross-site。
+ */
+export interface LoopbackOptions {
+  allowCrossSiteNoCors?: boolean;
+}
+
+/**
+ * Loopback 围栏：请求必须来自回环地址 + 回环 Host，且满足跨站/来源约束，
+ * 否则拒绝（DNS 重绑定 + 跨站防御）。
+ */
+export declare function isLoopbackRequest(
+  request: IncomingMessage,
+  options?: LoopbackOptions,
+): boolean;

package/shared/paths.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 插件主目录拼装（单一事实源，实现见 `./paths.js`）：等同
+ * `join(base, ...segments)`，默认形态路径逐字节不变。
+ *
+ * 只收敛「包主目录」直拼；以下 7 类排除：legacy/旧根（旧版迁移读面）、
+ * settings 文档（宿主文档读面）、resolve 对比（比较/候选命中顺序是语义）、
+ * 用户输入解析（`~`/相对路径展开）、credentials-userHome（DSH_HOME 域外凭据）、
+ * 展示脱敏（字符串替换不落盘）、包内反推（随包分发不在 DSH home 下）。
+ * provider-registry 的旧 `pluginHome` 保留为包内 facade（公开签名不变）。
+ * 完整理由见 `./paths.js` 函数 JSDoc。
+ */
+export declare function pluginHome(base: string, ...segments: string[]): string;

package/shared/settings-namespace.d.ts

@@ -0,0 +1,82 @@
+/**
+ * 宿主端「设置命名空间」注册（单一事实源）。
+ *
+ * 背景与语义见 settings-namespace.js 顶部注释。要点：宿主 settings 服务按 `ns`
+ * 定位描述项并合成 `base + user`（无层字段时兼容取 `value`）；写经
+ * update/replace/mutate；热更新经 document-updated 订阅（内部直连，不对外暴露 watch 面）。
+ * 本文件只收窄能力面（全 unknown 结构面，无官方包导入）。
+ */
+
+/** `installSettingsNamespace` 的 hooks 面。 */
+export interface SettingsNamespaceHooks {
+  /** 把插件对该命名空间的读取来源指向返回的 scope（`scope.get()`）。 */
+  setSource(source: () => unknown): void;
+  /** 来源切换或命名空间值变化时触发，插件据此刷新/落盘。 */
+  onChange(): void;
+  /**
+   * 可选；owning fiber ACTIVE 且 canonical namespace 被 settings 服务描述后回调一次。
+   * 供存量配置迁移 / 写路径装配使用；fiber / 服务 / namespace 未就绪时不触发。
+   */
+  onScope?(scope: unknown, service: unknown): void;
+}
+
+/** 描述项窄面（按 ns 定位，合成 base + user，兼容 value 回退）。 */
+export interface SettingsFormsDescriptor {
+  /** 命名空间键。 */
+  ns?: unknown;
+  /** 运行时解析值（缺少分层字段时的兼容回退）。 */
+  value?: unknown;
+  /** 基础配置层。 */
+  base?: unknown;
+  /** 原始 user 覆盖层。 */
+  user?: unknown;
+  /** 乐观并发修订号。 */
+  revision?: unknown;
+}
+
+/** owner scope 窄面（describe 定位读＋写委托；订阅由接缝内部直连）。 */
+export interface SettingsFormsScope {
+  /** 当前有效值（describe base + user，缺席回落 entry）。 */
+  get(): unknown;
+  /** 委托 settings.update(ns, …)。 */
+  update(patch: object, expectedRevision?: number): Promise<unknown>;
+  /** 委托 settings.replace(ns, …)。 */
+  replace(section: object, expectedRevision?: number): Promise<unknown>;
+  /** 委托 settings.mutate(ns, …)；服务缺失时返回拒绝。 */
+  mutate(ops: readonly unknown[], expectedRevision?: number): Promise<unknown>;
+}
+
+/** settings 服务窄面（describe/写）。 */
+export interface SettingsFormsService {
+  /** 按 entry id 定位描述项。 */
+  describe(options?: { redactSecrets?: boolean }): SettingsFormsDescriptor[];
+  /** 合并写。 */
+  update?(ns: string, patch: object, expectedRevision?: number): Promise<unknown>;
+  /** 整节写。 */
+  replace?(ns: string, section: object, expectedRevision?: number): Promise<unknown>;
+  /** 路径写（可选）。 */
+  mutate?(ns: string, ops: readonly unknown[], expectedRevision?: number): Promise<unknown>;
+}
+
+/**
+ * 日志兜底：logger 可能确实没有（极端降级），全部可选调用。
+ * 单一事实源（#436）：notifier / lan-proxy 曾各复刻一份，现统一引用本导出。
+ */
+export declare function warnLog(ctx: unknown, message: string): void;
+
+/**
+ * 注册插件自有 settings 命名空间（服务面注入，无包依赖）。
+ * 对外签名保持不变（调用方零改）。
+ * @param ctx - 插件宿主端 apply 收到的 cordis 上下文。
+ * @param ns - 插件自有命名空间（小写 kebab，须唯一）。
+ * @param schema - 占位：schema 由宿主持有，本函数不注册。
+ * @param entry - 组合层配置（describe 缺席时的回落值）。
+ * @param hooks - source 收藏与变更通知。
+ */
+export declare function installSettingsNamespace(
+  ctx: unknown,
+  ns: string,
+  schema: unknown,
+  entry: unknown,
+  hooks: SettingsNamespaceHooks,
+): void;