dsh-llm-fallbacks 0.1.0-alpha.1 → 0.1.0-alpha.2

package/README.md

@@ -9,10 +9,10 @@
 
 Automatic provider/model fallback chains for dsh (DeepSeek Harness): when an agent's LLM requests keep failing — retries exhausted, auth errors, quota exceeded, rate limiting (429) — the plugin switches provider/model along the fallback chain for the current role, and the current step/turn continues on the target model: tasks are not interrupted by model problems.
 
-Install with a single command (pnpm ≥ 10 needs one build-allow step — see [Install](#install)):
+Install with a single command (see [Install](#install)):
 
 ```sh
-dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # pin a commit with #<sha>
+dsh plugin --profile web add dsh-llm-fallbacks   # pin a version with @<version>
 ```
 
 ## Features
@@ -27,13 +27,31 @@ dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # pin a commit
 
 ## Install
 
-### One-line git install
+### One-line install
 
 ```sh
-dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # pin a commit with #<sha>
+dsh plugin --profile web add dsh-llm-fallbacks   # pin a version with @<version>
 ```
 
-A git install fetches **sources, not built artifacts**, so the bundle builds itself on install (`prepare` self-build). The plugin is **mount-only**: it never modifies the dsh source tree, and no patch / postinstall step exists — dsh upgrades never require re-patching. pnpm ≥ 10 blocks a git dependency's `prepare` by default: the first `add` fails with `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`, and pnpm prints the exact package key. Allow the build in the profile's `pnpm-workspace.yaml` (`onlyBuiltDependencies: [dsh-llm-fallbacks]`, or run `dsh plugin --profile web approve-builds`), then re-run the `add`. Treat that allowance as permission to execute the package's code on your machine at install time, and pin a commit (`github:btspoony/dsh-llm-fallbacks#<sha>`) so a later push cannot silently change what runs. The full URL form works equivalently: `dsh plugin --profile web add https://github.com/btspoony/dsh-llm-fallbacks.git`.
+A registry install fetches the **built package** (`dist/`) — nothing is built on the target machine. The plugin is **mount-only**: it never modifies the dsh source tree, and no patch / postinstall step exists — dsh upgrades never require re-patching. Versioning follows npm dist-tags (`latest` by default); pin an exact version with `dsh plugin --profile web add dsh-llm-fallbacks@<version>`.
+
+> **Release status**: the package is **not on the npm registry yet** — the first release (`0.1.0-alpha.2`) is pending (the release pipeline is in place; the first publish uses a one-time `NODE_AUTH_TOKEN` bootstrap secret, with Trusted Publishing configured afterwards for tokenless releases). All registry-based commands in this section are **preview** until the first release PR is merged; until then use the [git install](#git-install-works-today) channel.
+
+### Registry package (npm / pnpm)
+
+```sh
+npm install dsh-llm-fallbacks   # or: pnpm add dsh-llm-fallbacks
+```
+
+> **Preview**: effective after `dsh-llm-fallbacks@0.1.0-alpha.2` is published. Release process → [docs/release.md](docs/release.md).
+
+### Git install (works today)
+
+```sh
+dsh plugin --profile web add github:omdsh-dev/dsh-llm-fallbacks   # pin a commit with #<sha>
+```
+
+A git install fetches **sources, not built artifacts** — the bundle builds itself on install (`prepare` self-build), so the target machine needs node + pnpm. pnpm ≥ 10 blocks a git dependency's `prepare` by default (`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`); allow the build in the profile's `pnpm-workspace.yaml` and re-run the `add` (details in [docs/install.md](docs/install.md)).
 
 ### Local directory install (recommended for development / verification)
 
@@ -77,7 +95,7 @@ fallbacks:
         role: reviewer
 ```
 
-Roles are declared entities: `roles.list` holds role cards (id/label/description + optional chain/fallback), and `roles.rules` match origin/provider/model in order to a declared role id or the built-in `inherit` (first match wins) — **no rule match → `inherit` → `rootChain`**. A declared role is only ever hit when a rule references it. The legacy chain-key namespace and role-default field are gone (migration table: [docs/configuration.md](docs/configuration.md)).
+Roles are declared entities: `roles.list` holds role cards (id/label/description + chain/fallback), and `roles.rules` match origin/provider/model in order to a declared role id or the built-in `inherit` (first match wins) — **no rule match → `inherit` → `rootChain`**. A declared role is only ever hit when a rule references it. A role without a chain is meaningless — the settings card blocks saving it and the host warns at startup; give every declared role a chain, or point its rules at the built-in `inherit`. (A hand-written YAML role with a missing/empty chain is not fatal: with `fallback: inherit-root` (the default) an empty chain still falls back to `rootChain`; with `fallback: none` an empty chain leaves no candidates and the request passes through untouched — either way it is only a startup warn.) The legacy chain-key namespace and role-default field are gone (migration table: [docs/configuration.md](docs/configuration.md)).
 
 Save and restart the web session for the changes to take effect. The feature switch `fallbacks.enabled` **defaults to off (`false`)** — the plugin only engages once it is turned on; `triggerCodes` defaults to `AUTH` / `QUOTA` / `RATE_LIMIT`; and with **no `rootChain`/role chains configured the behavior is identical to not having the plugin installed**. More examples (role entities, fallback strategies, rules referencing `inherit`) → [docs/configuration.md](docs/configuration.md).
 
@@ -103,7 +121,7 @@ The plugin installs as a **pure mount** — it never modifies the dsh source tre
   the Fallbacks card on the Settings → 插件配置 page, and settings read/write/reset
   go through the plugin's own gateway channel (`/api/fallbacks/get|set|reset`).
 - **No patches, no auto-apply step**: there are no dsh-body patch files and no install
-  lifecycle step that applies one. A one-line git install works as-is.
+  lifecycle step that applies one. A one-line registry install works as-is.
 - **dsh upgrades never require re-patching**: a dsh upgrade that resets the source
   tree changes nothing for this plugin — it keeps working without any re-apply step.
 - **Stale leftover patches are harmless**: the plugin never depends on a patch
@@ -111,12 +129,23 @@ The plugin installs as a **pure mount** — it never modifies the dsh source tre
   was removed), so a previously patched dsh tree can be left as-is or manually
   reverted — neither is required.
 
+## Developer consumption
+
+Beyond the dsh plugin mount, `dsh-llm-fallbacks` exposes a programmable consumer surface — both faces share the same function implementations (single point of truth, no copied logic):
+
+- **Library API**: import the runtime functions and types from the package root — `import { resolveRole, resolveChain, validateFallbacksConfig } from 'dsh-llm-fallbacks'`.
+- **Named cordis service**: while the plugin is applied, `ctx.get('llm-fallbacks')` returns a pure-function service (`{ name, version, resolveRole, resolveChain, validateFallbacksConfig, detectLegacyKeys }`); after the plugin is disposed it is `undefined`. Runtime state stays observable via `fallbacks/switch` events, not through the service.
+
+Full contract (export inventory, minimal examples, lifecycle, typing) → [docs/consumer-api.md](docs/consumer-api.md).
+
 ## Documentation
 
 | Doc | Content |
 |---|---|
-| [docs/install.md](docs/install.md) | profile install / git install / uninstall / `--dump-config` verification |
+| [docs/install.md](docs/install.md) | profile install / registry install / uninstall / `--dump-config` verification |
+| [docs/release.md](docs/release.md) | release process: Trusted Publishing setup, Release prep SOP, fragment format, rollback |
 | [docs/configuration.md](docs/configuration.md) | full `fallbacks` namespace reference, selector syntax, example YAML, plugin-config card usage, behavior notes |
+| [docs/consumer-api.md](docs/consumer-api.md) | developer consumption contract: export inventory, minimal examples, lifecycle, typing |
 | [docs/verification.md](docs/verification.md) | verification records (test matrix, bundle layer order, runtime contracts, QA gate script) |
 
 ## License

package/README.zh-CN.md

@@ -9,10 +9,10 @@
 
 dsh（DeepSeek Harness）的自动模型降级插件：当 root agent 或 subagent 的模型请求持续失败（重试耗尽、权限、配额超限、限流 429）时，按角色/模型 fallback 链自动切换 provider/model，当前 step/turn 在目标模型上继续完成——任务不因模型问题中断。
 
-一句话安装（pnpm ≥ 10 需一次构建放行，见 [安装](#安装)）：
+一句话安装（见 [安装](#安装)）：
 
 ```sh
-dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # 钉 commit：加 #<sha>
+dsh plugin --profile web add dsh-llm-fallbacks   # 钉版本：加 @<version>
 ```
 
 ## 能力一览
@@ -27,13 +27,31 @@ dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # 钉 commit：
 
 ## 安装
 
-### 一句话 git 安装
+### 一句话安装
 
 ```sh
-dsh plugin --profile web add github:btspoony/dsh-llm-fallbacks   # 钉 commit：加 #<sha>
+dsh plugin --profile web add dsh-llm-fallbacks   # 钉版本：加 @<version>
 ```
 
-git 安装拉取的是**源码而非构建产物**，安装时由包自行构建（`prepare` 自构建）。插件为**纯挂载**：对 dsh 源码树零修改，无任何补丁 / postinstall 步骤——dsh 升级无需重打。pnpm ≥ 10 默认不执行 git 依赖的 `prepare`：第一次 `add` 会失败并打印 `ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`，同时给出精确的包 key。在该 profile 的 `pnpm-workspace.yaml` 中放行构建（`onlyBuiltDependencies: [dsh-llm-fallbacks]`，或运行 `dsh plugin --profile web approve-builds`），然后重跑 `add`。请把这次放行当作它本来的样子：允许该包代码在安装期于你的机器上执行——建议钉 commit（`github:btspoony/dsh-llm-fallbacks#<sha>`），防止后续 push 悄悄改变实际运行的代码。完整 URL 形式等价：`dsh plugin --profile web add https://github.com/btspoony/dsh-llm-fallbacks.git`。
+registry 安装拉取的是**已构建产物**（`dist/`），目标机无需构建。插件为**纯挂载**：对 dsh 源码树零修改，无任何补丁 / postinstall 步骤——dsh 升级无需重打。版本跟随 npm dist-tag（默认 `latest`）；钉精确版本：`dsh plugin --profile web add dsh-llm-fallbacks@<version>`。
+
+> **发布状态**：包**尚未发布到 npm registry**——首个版本（`0.1.0-alpha.2`）待发布（发布流水线已就绪；首次发布用一次性 `NODE_AUTH_TOKEN`，Trusted Publishing 在首次发布后配置）。本节的 registry 安装命令在首个 release PR merge 前均为**预告**；在此之前请用 [git 安装](#git-安装当前可用)。
+
+### registry 包安装（npm / pnpm）
+
+```sh
+npm install dsh-llm-fallbacks   # 或：pnpm add dsh-llm-fallbacks
+```
+
+> **预告**：`dsh-llm-fallbacks@0.1.0-alpha.2` 发布后生效。发布流程见 [docs/release.md](docs/release.md)。
+
+### git 安装（当前可用）
+
+```sh
+dsh plugin --profile web add github:omdsh-dev/dsh-llm-fallbacks   # 钉 commit：加 #<sha>
+```
+
+git 安装拉取的是**源码而非构建产物**——安装时由 `prepare` 自构建，目标机需要 node 与 pnpm。pnpm ≥ 10 默认拦截 git 依赖的 `prepare`（`ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED`）；在 profile 的 `pnpm-workspace.yaml` 中放行构建后重跑 `add`（详见 [docs/install.md](docs/install.md)）。
 
 ### 本地目录安装（开发/验证推荐）
 
@@ -75,7 +93,7 @@ fallbacks:
         role: reviewer
 ```
 
-角色是声明式实体：`roles.list` 存放角色卡（id/label/description + 可选 chain/fallback），`roles.rules` 按 origin/provider/model 顺序匹配到**已声明角色 id 或内置 `inherit`**（首个命中即停）——**未命中 → `inherit` → `rootChain`**。只声明不写规则的角色永不命中。旧链键命名空间与角色兜底字段已删除（迁移表见 [docs/configuration.md](docs/configuration.md)）。
+角色是声明式实体：`roles.list` 存放角色卡（id/label/description + chain/fallback），`roles.rules` 按 origin/provider/model 顺序匹配到**已声明角色 id 或内置 `inherit`**（首个命中即停）——**未命中 → `inherit` → `rootChain`**。只声明不写规则的角色永不命中。角色无 chain 无意义——设置卡拦截保存、启动时告警；请为每个声明角色配置 chain，或让规则直接引用内置 `inherit`。（手写 YAML 角色链缺省/为空不致命：`fallback: inherit-root`（默认）时空链仍按防御语义回退 `rootChain`；`fallback: none` 时空链无候选 → no-op 透传；两种情况都仅启动告警。）旧链键命名空间与角色兜底字段已删除（迁移表见 [docs/configuration.md](docs/configuration.md)）。
 
 保存并重启 web 会话后生效。功能级开关 `fallbacks.enabled` **默认关闭（`false`）**——打开开关后插件才会介入；`triggerCodes` 默认覆盖 `AUTH` / `QUOTA` / `RATE_LIMIT`；**未配置任何 `rootChain`/角色链时行为与未安装插件完全一致**。更多示例（角色实体、fallback 策略、引用 `inherit` 的规则）见 [docs/configuration.md](docs/configuration.md)。
 
@@ -101,17 +119,28 @@ fallbacks:
   Fallbacks 卡片，设置读写/重置
   走插件自有 gateway 通道（`/api/fallbacks/get|set|reset`）。
 - **无补丁、无自动打补丁**：没有 dsh 本体 patch 文件，也没有任何安装期 apply 步骤；
-  一句话 git 安装即可用。
+  一句话 registry 安装即可用。
 - **dsh 升级永不需重打**：dsh 升级重置源码树对本插件无影响——无需任何重打步骤。
 - **残留旧补丁无害**：插件不依赖任何补丁导出（角色解析 rules-only；model-selection
   标记协调已移除）——已打过旧补丁的 dsh 树可原样保留或手动回滚，均非必需。
 
+## 开发者消费面
+
+除插件挂载外，`dsh-llm-fallbacks` 还暴露可编程消费面——两个入口共享同一函数实现（单点真相，无复制逻辑）：
+
+- **库 API**：从包根直接 import 运行时函数与类型——`import { resolveRole, resolveChain, validateFallbacksConfig } from 'dsh-llm-fallbacks'`。
+- **具名 cordis service**：插件 apply 期间 `ctx.get('llm-fallbacks')` 返回纯函数服务（`{ name, version, resolveRole, resolveChain, validateFallbacksConfig, detectLegacyKeys }`），插件 dispose 后为 `undefined`。运行态（冷却、最近切换）请读 `fallbacks/switch` 事件，不走服务对象。
+
+完整契约（导出清单、最小示例、生命周期、类型说明）见 [docs/consumer-api.md](docs/consumer-api.md)。
+
 ## 文档
 
 | 文档 | 内容 |
 |---|---|
-| [docs/install.md](docs/install.md) | profile 安装 / git 安装 / 卸载 / `--dump-config` 验证 |
+| [docs/install.md](docs/install.md) | profile 安装 / registry 安装 / 卸载 / `--dump-config` 验证 |
+| [docs/release.md](docs/release.md) | 发布流程：Trusted Publishing 前置、Release prep SOP、fragment 格式、回滚 |
 | [docs/configuration.md](docs/configuration.md) | `fallbacks` 命名空间全字段、selector 语法、示例 YAML、插件配置卡使用、行为说明 |
+| [docs/consumer-api.md](docs/consumer-api.md) | 开发者消费契约：导出清单、最小示例、生命周期、类型说明 |
 | [docs/verification.md](docs/verification.md) | 验证记录（测试矩阵、bundle 层序、运行契约、QA gate 剧本） |
 
 ## 许可

package/dist/client/ConversationFallbackSwitch.d.ts

@@ -74,13 +74,13 @@ export type ConversationFallbackSwitchProps = PropsRuntime<'conversation.chat.no
  * Render one fallback switch as a compact system-style transcript line.
  *
  * Geometry follows the upstream chat system rows (the compaction boundary
- * notice: dim title + separator + ellipsized summary — `chat/MessageItem
- * .module.css:38-122`); every color resolves through a `--dsw-alias-*`
- * token. A reason outside the current union renders raw (forward-compatible
+ * notice: warning-toned title + separator + ellipsized summary —
+ * `chat/MessageItem .module.css:38-122`); every color resolves through a
+ * `--dsw-alias-*` token. A reason outside the current union renders raw (forward-compatible
  * durable log, same rule as the card/general row summaries). A malformed or
  * partial payload (version skew) degrades to the title-only line instead of
- * throwing during interpolation — the transcript slot stays visible with a
- * truthful "a switch happened" notice and no summary details.
+ * throwing during interpolation — the transcript slot stays visible with the
+ * warning-toned "model downgraded" title (T1 copy) and no summary details.
  * @param props - composed keyed seat props.
  * @returns the switch line element tree.
  */

package/dist/client/FallbacksCard.d.ts

@@ -26,8 +26,9 @@
  * `roles.rules`, whose role field is a dropdown bound to the declared ids
  * + the built-in `inherit`, same-page live). Saving runs `validateDraft`
  * first — id format/reserved word/duplicates, undeclared rule role
- * references, and illegal selectors block the write with a validation
- * banner + inline red borders (never touching the store error path); a
+ * references, illegal selectors, and a role with no chain entries (no
+ * model config) block the write with a validation banner + inline red
+ * borders / hints (never touching the store error path); a
  * non-empty `state.legacyKeys` renders the migration banner at the top of
  * the card body. The row editors keep their filled editorCard surface
  * inside the card, with `--dsw-alias-*` tokens throughout. The reset-

package/dist/client/index.js

@@ -1887,6 +1887,7 @@ window.__ModuleLoader__.load({
 			"validation.roleIdDuplicate": "角色 id \"{id}\" 重复",
 			"validation.ruleRoleUndeclared": "规则引用了未声明的角色 \"{role}\"",
 			"validation.ruleRoleRequired": "规则未选择角色：请选择目标角色，或删除该行",
+			"validation.roleChainRequired": "角色 \"{id}\" 未配置模型：请至少添加一条链选择器（模型配置）",
 			"validation.selector": "选择器 \"{entry}\" 非法：{message}",
 			"legacy.banner": "检测到旧格式配置字段（{keys}）：已按新模型展示，请按 docs/configuration.md 迁移表手工改写；插件不会自动改写配置。",
 			"catalog.empty": "暂无可用模型：请先在模型页添加模型，添加后此处将自动可选。",
@@ -1915,7 +1916,7 @@ window.__ModuleLoader__.load({
 			"general.switch": "最近切换：{from} → {to}（{role} · {reason}）",
 			"general.switch.empty": "本会话暂无切换",
 			"general.error": "状态读取失败：{message}",
-			"chat.switch.title": "模型切换",
+			"chat.switch.title": "模型已降级",
 			"chat.switch.summary": "{from} → {to}（{role} · {reason}）",
 			"defaults.prefix": "默认值",
 			"save": "保存",
@@ -2013,6 +2014,7 @@ window.__ModuleLoader__.load({
 			"validation.roleIdDuplicate": "Duplicate role id \"{id}\"",
 			"validation.ruleRoleUndeclared": "Rule references undeclared role \"{role}\"",
 			"validation.ruleRoleRequired": "Rule has no role selected: pick a target role, or remove the row",
+			"validation.roleChainRequired": "Role \"{id}\" has no model config: add at least one chain entry",
 			"validation.selector": "Invalid selector \"{entry}\": {message}",
 			"legacy.banner": "Legacy config fields detected ({keys}): now shown in the new model — rewrite them manually following the migration table in docs/configuration.md (the plugin will not rewrite them automatically).",
 			"catalog.empty": "No models yet: add a model on the Models page first; options will appear here automatically.",
@@ -2041,7 +2043,7 @@ window.__ModuleLoader__.load({
 			"general.switch": "Last switch: {from} → {to} ({role} · {reason})",
 			"general.switch.empty": "No switches this session",
 			"general.error": "Status read failed: {message}",
-			"chat.switch.title": "Model switch",
+			"chat.switch.title": "Model downgraded",
 			"chat.switch.summary": "{from} → {to} ({role} · {reason})",
 			"defaults.prefix": "Default",
 			"save": "Save",
@@ -2091,7 +2093,7 @@ window.__ModuleLoader__.load({
 			return [...next];
 		}
 		//#endregion
-		//#region \0dsh-css:/Users/bibi/workspace/ai/deepseek/dsh-llm-fallbacks/src/client/FallbacksCard.module.css.mjs
+		//#region \0dsh-css:/home/runner/work/dsh-llm-fallbacks/dsh-llm-fallbacks/src/client/FallbacksCard.module.css.mjs
 		const css$2 = "\n\n\n._8827595f_card {\n  list-style: none;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 12px;\n  background: var(--dsw-alias-bg-layer-3);\n  transition: border-color .16s, background .16s;\n}\n\n._8827595f_card:hover {\n  border-color: var(--dsw-alias-label-dimmed);\n}\n\n\n._06704203_cardOpen {\n  background: var(--dsw-alias-bg-layer-2);\n  border-color: var(--dsw-alias-label-dimmed);\n}\n\n\n._e488d460_header {\n  width: 100%;\n  appearance: none;\n  border: 0;\n  background: none;\n  font: inherit;\n  color: inherit;\n  text-align: left;\n  cursor: pointer;\n  display: flex;\n  align-items: center;\n  gap: 12px;\n  padding: 14px 16px;\n  border-radius: 12px;\n}\n\n._e488d460_header:focus-visible {\n  outline: 2px solid var(--dsw-alias-brand-primary);\n  outline-offset: -2px;\n}\n\n\n._f5dfe084_headText {\n  flex: 1;\n  min-width: 0;\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n}\n\n._8d39bde6_name {\n  font-size: 15px;\n  font-weight: 600;\n  line-height: 1.4;\n  color: var(--dsw-alias-label-primary);\n}\n\n._346f3b69_description {\n  font-size: 13px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-tertiary);\n}\n\n._631094a0_chevron {\n  flex: none;\n  color: var(--dsw-alias-label-tertiary);\n  transition: transform .16s;\n}\n\n._44836ce8_chevronOpen {\n  transform: rotate(180deg);\n}\n\n\n._dbaa7975_body {\n  border-top: 1px solid var(--dsw-alias-border-l2);\n  margin: 0 16px;\n  padding-bottom: 8px;\n}\n\n._4e39cf17_readOnly {\n  margin: 12px 0 0;\n  font-size: 12px;\n  line-height: 1.5;\n  color: var(--dsw-alias-label-tertiary);\n}\n\n\n._99bf7f3c_pending {\n  flex: none;\n  border-radius: 999px;\n  padding: 1px 8px;\n  font-size: 11px;\n  line-height: 17px;\n  font-weight: 500;\n  white-space: nowrap;\n  background: var(--dsw-alias-bg-module-platform);\n  color: var(--dsw-alias-label-secondary);\n}\n\n._114985b2_footer {\n  display: flex;\n  align-items: center;\n  justify-content: flex-end;\n  gap: 8px;\n  padding: 12px 0 4px;\n  border-top: 1px solid var(--dsw-alias-border-l2);\n}\n\n\n._9860a5b1_notice {\n  margin: 12px 0 0;\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-state-business-primary);\n}\n\n\n._5006d43e_legacyNotice {\n  margin: 12px 0 0;\n  padding: 10px 12px;\n  border-radius: 8px;\n  background: var(--dsw-alias-bg-module-platform);\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-state-business-primary);\n}\n\n._21918751_error {\n  margin: 12px 0 0;\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-state-error-primary);\n}\n\n\n._7cea4b2f_noticeRow {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  margin: 12px 0 0;\n}\n\n._7cea4b2f_noticeRow ._21918751_error {\n  flex: 1;\n  min-width: 0;\n  margin: 0;\n}\n\n\n._4058c747_form {\n  display: flex;\n  flex-direction: column;\n  gap: 12px;\n  padding: 12px 0 0;\n}\n\n\n._9998065c_checkboxRow {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n}\n\n._02c2f6df_checkLabel {\n  flex: 1;\n  min-width: 0;\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n  font-size: 14px;\n  line-height: 22px;\n  font-weight: 400;\n  color: var(--dsw-alias-label-primary);\n  cursor: pointer;\n}\n\n._f2d47237_checkLabelTitle {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  font-weight: 400;\n}\n\n._c1bed8ea_checkLabelDesc {\n  font-size: 12px;\n  line-height: 18px;\n  font-weight: 400;\n  color: var(--dsw-alias-label-tertiary);\n}\n\n\n._06389b18_checkbox {\n  flex: none;\n  width: 16px;\n  height: 16px;\n  margin: 0;\n  accent-color: var(--dsw-alias-brand-primary);\n  cursor: pointer;\n}\n\n._06389b18_checkbox:disabled {\n  opacity: 0.4;\n  cursor: default;\n}\n\n\n._94c91bfd_fieldset {\n  margin: 0;\n  padding: 0;\n  border: none;\n  display: flex;\n  flex-direction: column;\n  gap: 12px;\n}\n\n\n._67826267_field {\n  display: flex;\n  flex-direction: column;\n  gap: 6px;\n  margin: 0;\n  padding: 0;\n  border: none;\n  min-width: 0;\n}\n\n._13e68c3f_fieldLabel {\n  \n  display: inline-flex;\n  align-items: center;\n  gap: 10px;\n  padding: 0;\n  font-size: 12px;\n  line-height: 18px;\n  font-weight: 500;\n  color: var(--dsw-alias-label-secondary);\n}\n\n._4bc809b8_hint {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  flex-wrap: wrap;\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-tertiary);\n}\n\n._579f813a_defaultNote {\n  font-size: 12px;\n  line-height: 18px;\n  font-weight: 400;\n  color: var(--dsw-alias-label-tertiary);\n}\n\n\n._a6244318_infoHint {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  flex: none;\n  width: 16px;\n  height: 16px;\n  border-radius: 50%;\n  font-size: 14px;\n  line-height: 1;\n  color: var(--dsw-alias-label-tertiary);\n  background: var(--dsw-alias-interactive-bg-hover);\n  cursor: help;\n  user-select: none;\n}\n\n._a6244318_infoHint:focus-visible {\n  outline: none;\n  box-shadow: 0 0 0 2px var(--dsw-alias-border-l3);\n}\n\n\n._e655c840_infoHintDisabled {\n  opacity: 0.4;\n  cursor: default;\n}\n\n\n._a2521bb0_optionRow {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 6px 8px;\n  border-radius: 6px;\n  font-size: 14px;\n  line-height: 22px;\n  color: var(--dsw-alias-label-primary);\n  cursor: pointer;\n}\n\n._a2521bb0_optionRow:hover:has(input:not(:disabled)) {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n\n\n._06389b18_checkbox,\n._a2521bb0_optionRow input,\n._929f3ef3_wildcardCell input {\n  flex: none;\n  width: 16px;\n  height: 16px;\n  margin: 0;\n  accent-color: var(--dsw-alias-brand-primary);\n  cursor: pointer;\n}\n\n._06389b18_checkbox:focus-visible,\n._a2521bb0_optionRow input:focus-visible,\n._929f3ef3_wildcardCell input:focus-visible {\n  outline: none;\n  box-shadow: 0 0 0 2px var(--dsw-alias-border-l3);\n}\n\n._a2521bb0_optionRow input:disabled,\n._929f3ef3_wildcardCell input:disabled {\n  cursor: default;\n}\n\n\n._f9d86f7b_input {\n  box-sizing: border-box;\n  width: 100%;\n  height: 32px;\n  padding: 0 10px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 8px;\n  font: inherit;\n  font-size: 14px;\n  line-height: 22px;\n  background: var(--dsw-alias-bg-layer-1);\n  color: var(--dsw-alias-label-primary);\n}\n\n._f9d86f7b_input:focus {\n  outline: none;\n  border-color: var(--dsw-alias-brand-primary);\n}\n\n._f9d86f7b_input::placeholder {\n  color: var(--dsw-alias-label-dimmed);\n}\n\n._f9d86f7b_input:disabled {\n  opacity: 0.6;\n  cursor: default;\n}\n\n\n._7b60337a_inputInvalid,\n._7b60337a_inputInvalid:focus {\n  border-color: var(--dsw-alias-state-error-primary);\n}\n\n\nselect._f9d86f7b_input {\n  max-width: 240px;\n  cursor: pointer;\n}\n\n\n._16eb7153_selectInput {\n  appearance: none;\n  padding-right: 32px;\n  \n  background-image: url(\"data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12' fill='none'%3E%3Cpath d='M3 4.5L6 7.5L9 4.5' stroke='%2381858C' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E\");\n  background-repeat: no-repeat;\n  background-position: right 12px center;\n  background-size: 12px 12px;\n}\n\n\n._3e95886d_numberFields {\n  display: grid;\n  grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));\n  gap: 8px;\n}\n\n._0cfb5881_list {\n  display: flex;\n  flex-direction: column;\n  gap: 8px;\n  margin-top: 4px;\n}\n\n\n._f5c620d6_editorCard {\n  display: flex;\n  flex-direction: column;\n  gap: 14px;\n  padding: 14px 16px;\n  border-radius: 12px;\n  background: var(--dsw-alias-bg-module-platform);\n}\n\n._224b1387_cardFoot {\n  display: flex;\n  justify-content: flex-end;\n}\n\n._8e220e07_ruleGrid {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 8px;\n}\n\n._24a12a2f_ruleCell {\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n  min-width: 120px;\n  flex: 1;\n}\n\n._1014c097_ruleCellLabel {\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-secondary);\n}\n\n\n._15a12620_chainSelectors {\n  display: flex;\n  flex-direction: column;\n  gap: 10px;\n}\n\n._240cbbf8_selectorRow {\n  display: flex;\n  flex-direction: column;\n  gap: 6px;\n}\n\n\n._929f3ef3_wildcardCell {\n  flex-direction: row;\n  align-items: center;\n  gap: 8px;\n  min-width: 200px;\n  align-self: center;\n  padding: 6px 8px;\n  border-radius: 6px;\n  cursor: pointer;\n}\n\n._929f3ef3_wildcardCell:hover:has(input:not(:disabled)) {\n  background: var(--dsw-alias-interactive-bg-hover);\n}\n\n\n._70effa64_iconButton {\n  position: relative;\n  box-sizing: border-box;\n  appearance: none;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  width: 28px;\n  height: 28px;\n  padding: 0;\n  border: 0;\n  border-radius: 6px;\n  background: none;\n  color: var(--dsw-alias-label-tertiary);\n  cursor: pointer;\n}\n\n._70effa64_iconButton:disabled {\n  opacity: 0.4;\n  cursor: default;\n}\n\n._70effa64_iconButton:hover:not(:disabled) {\n  background: var(--dsw-alias-interactive-bg-hover);\n  color: var(--dsw-alias-label-primary);\n}\n\n._70effa64_iconButton:focus-visible {\n  outline: none;\n  box-shadow: 0 0 0 2px var(--dsw-alias-border-l3);\n}\n\n._70effa64_iconButton::after {\n  content: attr(data-tip);\n  position: absolute;\n  bottom: calc(100% + 6px);\n  left: 50%;\n  transform: translateX(-50%);\n  padding: 3px 8px;\n  border-radius: 6px;\n  background: var(--dsw-alias-label-primary);\n  color: var(--dsw-alias-bg-layer-3);\n  font-size: 11px;\n  line-height: 17px;\n  white-space: nowrap;\n  opacity: 0;\n  pointer-events: none;\n  transition: opacity .12s;\n}\n\n._70effa64_iconButton:hover::after,\n._70effa64_iconButton:focus-visible::after {\n  opacity: 1;\n}\n\n\n._a0968257_iconButtonDanger:hover:not(:disabled) {\n  background: var(--dsw-alias-interactive-bg-hover-danger);\n  color: var(--dsw-alias-state-error-primary);\n}\n\n\n._28202c90_addButton {\n  align-self: flex-start;\n}\n\n\n._747fd56d_primaryButton,\n._7e855445_secondaryButton {\n  box-sizing: border-box;\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  gap: 4px;\n  height: 36px;\n  padding: 0 14px;\n  border: none;\n  border-radius: 18px;\n  font: inherit;\n  font-size: 14px;\n  line-height: 22px;\n  cursor: pointer;\n}\n\n._747fd56d_primaryButton {\n  background: var(--dsw-alias-button-primary-fill);\n  color: var(--dsw-alias-label-primary-foreground);\n}\n\n._747fd56d_primaryButton:hover:not(:disabled) {\n  background: var(--dsw-alias-button-primary-hover);\n}\n\n._7e855445_secondaryButton {\n  border: 1px solid var(--dsw-alias-border-l2);\n  background: transparent;\n  color: var(--dsw-alias-label-primary);\n}\n\n._7e855445_secondaryButton:hover:not(:disabled) {\n  background: var(--dsw-alias-interactive-bg-hover-solid);\n}\n\n._747fd56d_primaryButton:disabled,\n._7e855445_secondaryButton:disabled {\n  opacity: 0.4;\n  cursor: default;\n}\n\n._747fd56d_primaryButton:focus-visible,\n._7e855445_secondaryButton:focus-visible {\n  outline: none;\n  box-shadow: 0 0 0 2px var(--dsw-alias-border-l3);\n}\n\n\n._fbd045e0_statusBlock {\n  display: flex;\n  flex-direction: column;\n  gap: 12px;\n  padding: 12px 14px;\n  margin-top: 12px;\n  border: 1px solid var(--dsw-alias-border-l2);\n  border-radius: 12px;\n}\n\n._d4f70367_statusTitle {\n  font-size: 12px;\n  line-height: 18px;\n  font-weight: 500;\n  color: var(--dsw-alias-label-secondary);\n}\n\n\n._8ab300ed_statusLine {\n  margin: 0;\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-secondary);\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n\n._e8cedbf5_statusLineLabel {\n  font-weight: 500;\n  color: var(--dsw-alias-label-secondary);\n}\n\n\n._b48dfcba_offNotice {\n  margin: 0;\n  padding: 12px;\n  border: 1px dashed var(--dsw-alias-border-l3);\n  border-radius: 8px;\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-tertiary);\n  text-align: center;\n}\n\n\n._ec8bd970_resetDialog {\n  width: min(480px, 100%);\n}\n\n._8677165c_confirmDanger:not(:disabled) {\n  border-color: var(--dsw-alias-state-error-primary);\n  color: var(--dsw-alias-state-error-primary);\n}\n\n._8677165c_confirmDanger:hover:not(:disabled) {\n  background: var(--dsw-alias-interactive-bg-hover-danger);\n}\n\n@media (prefers-reduced-motion: reduce) {\n  ._70effa64_iconButton::after {\n    transition: none;\n  }\n}\n";
 		const tagId$2 = "dsh-llm-fallbacks/FallbacksCard.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId$2) + "]") === null) {
@@ -2188,8 +2190,9 @@ window.__ModuleLoader__.load({
 		* `roles.rules`, whose role field is a dropdown bound to the declared ids
 		* + the built-in `inherit`, same-page live). Saving runs `validateDraft`
 		* first — id format/reserved word/duplicates, undeclared rule role
-		* references, and illegal selectors block the write with a validation
-		* banner + inline red borders (never touching the store error path); a
+		* references, illegal selectors, and a role with no chain entries (no
+		* model config) block the write with a validation banner + inline red
+		* borders / hints (never touching the store error path); a
 		* non-empty `state.legacyKeys` renders the migration banner at the top of
 		* the card body. The row editors keep their filled editorCard surface
 		* inside the card, with `--dsw-alias-*` tokens throughout. The reset-
@@ -2283,6 +2286,7 @@ window.__ModuleLoader__.load({
 						message: error.message
 					}));
 				}
+				if ((role.chain ?? []).length === 0) errors.push(t("validation.roleChainRequired", { id: role.id }));
 			}
 			for (const entry of draft.rootChain) try {
 				parseSelector(entry);
@@ -3180,9 +3184,9 @@ window.__ModuleLoader__.load({
 																			})
 																		]
 																	}),
-																	/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+																	/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 																		className: FallbacksCard_module_css_default.chainSelectors,
-																		children: row.selectors.map((selector, selectorIndex) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ChainSelectorEditor, {
+																		children: [row.selectors.map((selector, selectorIndex) => /* @__PURE__ */ (0, react_jsx_runtime.jsx)(ChainSelectorEditor, {
 																			selector,
 																			catalog: catalogOf(state),
 																			configuredProviders: state.configuredProviders,
@@ -3194,7 +3198,10 @@ window.__ModuleLoader__.load({
 																			onRemove: () => {
 																				removeRoleSelector(index, selectorIndex);
 																			}
-																		}, selectorIndex))
+																		}, selectorIndex)), row.selectors.every((selector) => selectorRowToRaw(selector) === "") && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+																			className: FallbacksCard_module_css_default.hint,
+																			children: t("validation.roleChainRequired", { id: row.id })
+																		})]
 																	}),
 																	/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
 																		className: FallbacksCard_module_css_default.ruleGrid,
@@ -3560,7 +3567,7 @@ window.__ModuleLoader__.load({
 			});
 		}
 		//#endregion
-		//#region \0dsh-css:/Users/bibi/workspace/ai/deepseek/dsh-llm-fallbacks/src/client/GeneralFallbacksRow.module.css.mjs
+		//#region \0dsh-css:/home/runner/work/dsh-llm-fallbacks/dsh-llm-fallbacks/src/client/GeneralFallbacksRow.module.css.mjs
 		const css$1 = "\n\n._440e1d7b_row {\n  display: flex;\n  align-items: center;\n  gap: 8px;\n  padding: 16px 0;\n  border-bottom: 1px solid var(--dsw-alias-border-l2);\n}\n\n._a4f2ceec_rowText {\n  flex: 1;\n  min-width: 0;\n  display: flex;\n  flex-direction: column;\n  gap: 4px;\n  padding-right: 48px;\n}\n\n._9865b509_title {\n  font-size: 14px;\n  font-weight: 400;\n  line-height: 22px;\n  color: var(--dsw-alias-label-primary);\n}\n\n\n._10a44713_summary {\n  font-size: 12px;\n  line-height: 18px;\n  color: var(--dsw-alias-label-tertiary);\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n\n\n._35648278_badge {\n  flex: none;\n  padding: 2px 10px;\n  border-radius: 9px;\n  font-size: 12px;\n  line-height: 18px;\n  background: var(--dsw-alias-bg-module-platform);\n  color: var(--dsw-alias-label-tertiary);\n}\n\n._3b9e8609_badgeEnabled {\n  color: var(--dsw-alias-state-success-primary);\n}\n";
 		const tagId$1 = "dsh-llm-fallbacks/GeneralFallbacksRow.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId$1) + "]") === null) {
@@ -3684,8 +3691,8 @@ window.__ModuleLoader__.load({
 			return typeof from?.provider === "string" && typeof from?.model === "string" && typeof to?.provider === "string" && typeof to?.model === "string";
 		}
 		//#endregion
-		//#region \0dsh-css:/Users/bibi/workspace/ai/deepseek/dsh-llm-fallbacks/src/client/ConversationFallbackSwitch.module.css.mjs
-		const css = "\n\n._ea99bbef_switchRow {\n  display: flex;\n  align-items: center;\n  padding: 2px 0;\n  font-size: 14px;\n  line-height: 24px;\n}\n\n\n._02580bfd_switchTitle {\n  flex: none;\n  color: var(--dsw-alias-label-primary-dimmed);\n}\n\n._88b2d18b_switchSep {\n  flex: none;\n  width: 2px;\n  height: 2px;\n  margin: 0 8px;\n  border-radius: 1px;\n  background: var(--dsw-alias-label-caption);\n}\n\n\n._7c8c1b6f_switchSummary {\n  flex: 1 1 auto;\n  min-width: 0;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  color: var(--dsw-alias-label-tertiary);\n}\n";
+		//#region \0dsh-css:/home/runner/work/dsh-llm-fallbacks/dsh-llm-fallbacks/src/client/ConversationFallbackSwitch.module.css.mjs
+		const css = "\n\n._ea99bbef_switchRow {\n  display: flex;\n  align-items: center;\n  padding: 2px 0;\n  font-size: 14px;\n  line-height: 24px;\n}\n\n\n._02580bfd_switchTitle {\n  flex: none;\n  color: var(--dsw-alias-state-warn-primary);\n}\n\n._88b2d18b_switchSep {\n  flex: none;\n  width: 2px;\n  height: 2px;\n  margin: 0 8px;\n  border-radius: 1px;\n  background: var(--dsw-alias-label-caption);\n}\n\n\n._7c8c1b6f_switchSummary {\n  flex: 1 1 auto;\n  min-width: 0;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n  color: var(--dsw-alias-label-tertiary);\n}\n";
 		const tagId = "dsh-llm-fallbacks/ConversationFallbackSwitch.module.css";
 		if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
 			const tag = document.createElement("style");
@@ -3753,13 +3760,13 @@ window.__ModuleLoader__.load({
 		* Render one fallback switch as a compact system-style transcript line.
 		*
 		* Geometry follows the upstream chat system rows (the compaction boundary
-		* notice: dim title + separator + ellipsized summary — `chat/MessageItem
-		* .module.css:38-122`); every color resolves through a `--dsw-alias-*`
-		* token. A reason outside the current union renders raw (forward-compatible
+		* notice: warning-toned title + separator + ellipsized summary —
+		* `chat/MessageItem .module.css:38-122`); every color resolves through a
+		* `--dsw-alias-*` token. A reason outside the current union renders raw (forward-compatible
 		* durable log, same rule as the card/general row summaries). A malformed or
 		* partial payload (version skew) degrades to the title-only line instead of
-		* throwing during interpolation — the transcript slot stays visible with a
-		* truthful "a switch happened" notice and no summary details.
+		* throwing during interpolation — the transcript slot stays visible with the
+		* warning-toned "model downgraded" title (T1 copy) and no summary details.
 		* @param props - composed keyed seat props.
 		* @returns the switch line element tree.
 		*/

package/dist/client/locales.d.ts

@@ -80,6 +80,7 @@ export declare const zh: {
     'validation.roleIdDuplicate': string;
     'validation.ruleRoleUndeclared': string;
     'validation.ruleRoleRequired': string;
+    'validation.roleChainRequired': string;
     'validation.selector': string;
     'legacy.banner': string;
     'catalog.empty': string;
@@ -208,6 +209,7 @@ export declare const en: {
     'validation.roleIdDuplicate': string;
     'validation.ruleRoleUndeclared': string;
     'validation.ruleRoleRequired': string;
+    'validation.roleChainRequired': string;
     'validation.selector': string;
     'legacy.banner': string;
     'catalog.empty': string;

package/dist/config.d.ts

@@ -106,11 +106,14 @@ export interface FallbacksConfigLogger {
 /**
  * Validate a fallbacks config (pure, warn-only — never throws, never
  * mutates): role id format/uniqueness/reserved word, rule role references
- * (declared ids + the built-in `'inherit'`), the `fallback` enum, and
- * `rootChain`/role-chain selector legality. `label`/`description` are free
- * text and are deliberately not validated. Each violation emits one
- * `llm-fallbacks: ...` warn and "does not take effect" — the config stays
- * usable (spec §4 / AC-4 warn-not-crash semantics).
+ * (declared ids + the built-in `'inherit'`), the `fallback` enum,
+ * `rootChain`/role-chain selector legality, and the role model-config
+ * requirement (a declared role with a missing/empty chain warns — a role
+ * without a model config is meaningless, plan fallbacks-feedback-round
+ * T2). `label`/`description` are free text and are deliberately not
+ * validated. Each violation emits one `llm-fallbacks: ...` warn and "does
+ * not take effect" — the config stays usable (spec §4 / AC-4
+ * warn-not-crash semantics).
  */
 export declare function validateFallbacksConfig(config: FallbacksConfig, logger: FallbacksConfigLogger): void;
 /**

package/dist/index.d.ts

@@ -29,15 +29,51 @@
  */
 import type { Context } from '@deepseek-ai/cordis';
 import type { Session } from '@deepseek-ai/dsh-session';
-import { Config, type FallbacksConfig } from './config.ts';
+import { Config, detectLegacyKeys, validateFallbacksConfig, type FallbacksConfig } from './config.ts';
+import { resolveChain } from './chains.ts';
+import { resolveRole } from './roles.ts';
 import { FallbackStateStore } from './state.ts';
 /** The plugin row id mounted by the profile bundle patch. */
 export declare const name = "llm-fallbacks";
+/**
+ * Declarative service metadata (cordis `Plugin.Base.provide`, read by
+ * loaders/tooling). The actual registration happens in `apply()` via
+ * `ctx.provide('llm-fallbacks', …)` — the static array never registers
+ * anything by itself.
+ */
+export declare const provide: readonly ["llm-fallbacks"];
+/**
+ * The named cordis service `ctx.get('llm-fallbacks')` exposes while the
+ * plugin is applied: the pure-function library surface + `name`/`version`
+ * metadata. Deliberately NO runtime state (no stateStore, no event
+ * emitters, no filter helpers) — state stays observable via `fallbacks/switch`
+ * events and the library API.
+ */
+export interface FallbacksService {
+    /** Matches the plugin `name`. */
+    name: 'llm-fallbacks';
+    /** Package.json version string (module-load snapshot). */
+    version: string;
+    resolveRole: typeof resolveRole;
+    resolveChain: typeof resolveChain;
+    validateFallbacksConfig: typeof validateFallbacksConfig;
+    detectLegacyKeys: typeof detectLegacyKeys;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The fallbacks service while the plugin is applied; `undefined` otherwise. */
+        'llm-fallbacks'?: FallbacksService;
+    }
+}
 export { Config };
 /** The plugin's composition config — the `fallbacks` settings schema (spec §4). */
 export type Config = FallbacksConfig;
 export type { FallbackSwitchReason, FallbacksSwitchEventData } from './events.ts';
 export type { AgentFallbackState, FallbackStateStore, PendingSwitch, StepFailures } from './state.ts';
+export { resolveRole, type AgentLike, type Origin, } from './roles.ts';
+export { annotateCandidates, createCandidateFilter, hasWildcardEntry, resolveCandidate, resolveChain, resolveChainViews, selectCandidates, type AnnotatedCandidate, type CandidateFilterOptions, type CandidateSkipReason, type FailingModel, } from './chains.ts';
+export { defaultFallbacksConfig, detectLegacyKeys, INHERIT_ROLE_ID, ROLE_ID_PATTERN, validateFallbacksConfig, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRole, type FallbacksRoles, type FallbacksRoleRule, type FallbackStrategy, type RevertPolicy, } from './config.ts';
+export { parseSelector, SelectorError, type Selector, } from './selectors.ts';
 /**
  * @internal Test seam (T3 review Minor 3): the per-agent fallback state store
  * of the plugin applied to `ctx` — last apply wins. Not part of the plugin's

package/dist/index.js

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module";
 import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
 import { TypertRemoteService } from "@deepseek-ai/dsh-typert-protocol";
 //#region \0rolldown/runtime.js
@@ -1081,6 +1082,7 @@ function validateFallbacksConfig(config, logger) {
 		} catch (error) {
 			logger.warn(`llm-fallbacks: ignoring invalid chain entry "${entry}" in role "${role.id}": ${error.message}`);
 		}
+		if ((role.chain ?? []).length === 0) logger.warn(`llm-fallbacks: role "${role.id}" has no model config — declare at least one chain entry, or use the built-in "inherit" rule target instead`);
 		if (role.fallback !== void 0 && role.fallback !== "inherit-root" && role.fallback !== "none") logger.warn(`llm-fallbacks: role "${role.id}" has invalid fallback "${String(role.fallback)}" — expected "inherit-root" or "none"`);
 	}
 	for (const entry of config.rootChain) try {
@@ -1204,6 +1206,10 @@ function selectCandidates(all, wildcard, filter, modelExists) {
 	}
 	return surviving;
 }
+function resolveChain(roles, rootChain, role, provider, model, filter, modelExists, warn = console.warn) {
+	const { all, wildcard } = resolveChainViews(roles, rootChain, role, provider, model, warn);
+	return selectCandidates(all, wildcard, filter, modelExists);
+}
 function hasWildcardEntry(roles, rootChain, role) {
 	const entries = buildRoleEntries(roles, rootChain, role);
 	for (const entry of entries) try {
@@ -1650,6 +1656,8 @@ function registerFallbacksCommands(registry, controller, locale = "zh") {
 //#endregion
 //#region .build/host/index.js
 const name = "llm-fallbacks";
+const provide = ["llm-fallbacks"];
+const { version } = createRequire(import.meta.url)("../package.json");
 const stateStores = new WeakMap();
 function stateStore(ctx) {
 	return stateStores.get(ctx);
@@ -1697,6 +1705,19 @@ function overrideConfig(seed, to) {
 function apply(ctx, config = defaultFallbacksConfig) {
 	const logger = ctx.logger("llm-fallbacks");
 	const entry = Config(config);
+	try {
+		ctx.provide("llm-fallbacks", {
+			name: "llm-fallbacks",
+			version,
+			resolveRole,
+			resolveChain,
+			validateFallbacksConfig,
+			detectLegacyKeys
+		});
+	} catch (error) {
+		if (!(error instanceof Error) || !error.message.includes("has been registered")) throw error;
+		ctx.logger("llm-fallbacks").debug("fallbacks service already registered — no service on this fiber (multi-fiber dedupe)");
+	}
 	let source = () => entry;
 	validateFallbacksConfig(entry, logger);
 	const legacyKeys = detectLegacyKeys(source());
@@ -1850,4 +1871,4 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	});
 }
 //#endregion
-export { Config, apply, countRetryEvents, name, stateStore };
+export { Config, INHERIT_ROLE_ID, ROLE_ID_PATTERN, SelectorError, annotateCandidates, apply, countRetryEvents, createCandidateFilter, defaultFallbacksConfig, detectLegacyKeys, hasWildcardEntry, name, parseSelector, provide, resolveCandidate, resolveChain, resolveChainViews, resolveRole, selectCandidates, stateStore, validateFallbacksConfig };

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -46,6 +46,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && tsdown && pnpm run build-client && tsc && node scripts/verify-dist.mjs",
     "build-client": "tsx scripts/build-client.ts",
+    "release:prepare": "tsx scripts/prepare-release.ts",
+    "release:validate": "tsx scripts/validate-release-version.ts",
     "test": "vitest run",
     "prepare": "pnpm run build"
   },
@@ -87,5 +89,9 @@
     "tsx": "^4.22.4",
     "typescript": "^5.9.3",
     "vitest": "^4.1.8"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/omdsh-dev/dsh-llm-fallbacks.git"
   }
 }

package/scripts/prepare-release.ts

@@ -0,0 +1,231 @@
+/**
+ * prepare-release.ts — resolve the next version, assemble changelog fragments,
+ * insert the changelog section, bump package.json, archive fragments.
+ *
+ * Usage (from the repo root, via tsx — the package.json `release:prepare`
+ * script):
+ *   pnpm release:prepare -- <version>    # explicit version, used as-is
+ *   pnpm release:prepare -- --patch      # auto patch bump
+ *
+ * Exactly one of the two forms is required: running with no arguments exits
+ * with a usage hint instead of silently auto-bumping.
+ *
+ * Version resolution:
+ *   - Explicit version must match /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/ and
+ *     is used as-is (prerelease suffixes allowed, e.g. 0.1.0-alpha.2).
+ *   - `--patch` auto bump:
+ *       * current has a numeric prerelease tail (`X.Y.Z-pre.N`) -> bump only N
+ *         (0.1.0-alpha.1 -> 0.1.0-alpha.2; never jumps to a stable release);
+ *       * no prerelease -> patch + 1 (0.1.0 -> 0.1.1);
+ *       * prerelease with a non-numeric tail -> exit 1, use an explicit
+ *         version instead.
+ *
+ * What it does:
+ *   1. Reads `.changes/unreleased/*.md` fragments (README.md / .gitkeep are
+ *      skipped). Optional frontmatter `category:` groups bullets under a
+ *      `### <category>` heading (default: `Changed`); the body is one or more
+ *      English bullet lines, rendered verbatim.
+ *   2. Inserts a `## [<version>] - <date>` section into CHANGELOG.md directly
+ *      under `## [Unreleased]`.
+ *   3. Bumps the `version` field in package.json.
+ *   4. Moves consumed fragments to `.changes/archive/<version>/`.
+ *
+ * All paths are resolved relative to the current working directory, so the
+ * script works both from the repo root (`pnpm release:prepare`) and from a
+ * throwaway fixture directory (used by the release tooling verification).
+ *
+ * This script only edits the working tree. Commit + PR is the caller's job
+ * (the `release-prep` workflow commits and opens the `release vX.Y.Z` PR).
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { VERSION_RE } from './release-version.ts'
+
+const CHANGES_DIR = '.changes'
+const UNRELEASED_DIR = join(CHANGES_DIR, 'unreleased')
+const ARCHIVE_DIR = join(CHANGES_DIR, 'archive')
+
+const DEFAULT_CATEGORY = 'Changed'
+
+type Fragment = {
+  file: string
+  category?: string
+  bullets: string[]
+}
+
+export function parseArgs(argv: string[]): { version?: string; autoBump: boolean } {
+  const rest = argv.slice(2).filter((a) => a !== '--')
+  let version: string | undefined
+  let autoBump = false
+  for (const arg of rest) {
+    if (VERSION_RE.test(arg)) version = arg
+    else if (arg === '--patch') autoBump = true
+    else if (arg.startsWith('-')) throw new Error(`Unknown argument: ${arg} (expected <version> or --patch)`)
+    else
+      throw new Error(
+        `Invalid version "${arg}". Expected X.Y.Z or X.Y.Z-pre.N (e.g. 0.1.0-alpha.2)`,
+      )
+  }
+  if (version !== undefined && autoBump) {
+    throw new Error('Pass either an explicit <version> or --patch, not both')
+  }
+  return { version, autoBump }
+}
+
+/**
+ * Auto patch bump. Deliberately NOT the naive split+parseInt mstar approach
+ * (which turns `0.1.0-alpha.1 --patch` into stable `0.1.1`): a prerelease
+ * version stays in its prerelease line, bumping only the numeric tail.
+ */
+export function autoBumpPatch(current: string): string {
+  const m = /^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/.exec(current)
+  if (!m) throw new Error(`Cannot auto-bump "${current}": not a parseable X.Y.Z[-pre] version`)
+  const [, major, minor, patch, pre] = m
+  if (pre === undefined) return `${major}.${minor}.${Number(patch) + 1}`
+  const tail = pre.split('.').at(-1)
+  if (tail === undefined || !/^\d+$/.test(tail)) {
+    throw new Error(
+      `Cannot auto-bump "${current}": prerelease tail "${pre}" is not numeric. ` +
+        'Pass an explicit version instead (e.g. `pnpm release:prepare -- <version>`).',
+    )
+  }
+  const prefix = pre.slice(0, pre.length - tail.length) // "alpha." for "alpha.1"
+  return `${major}.${minor}.${patch}-${prefix}${Number(tail) + 1}`
+}
+
+export function parseFrontmatter(text: string): { fm: Record<string, string>; body: string } {
+  const fm: Record<string, string> = {}
+  if (!text.startsWith('---')) return { fm, body: text }
+  const end = text.indexOf('\n---', 3)
+  if (end === -1) return { fm, body: text }
+  const fmText = text.slice(3, end)
+  const body = text.slice(end + 4).replace(/^\n/, '')
+  for (const line of fmText.split('\n')) {
+    const m = line.match(/^([A-Za-z0-9 _-]+):\s*(.*)$/)
+    if (m) fm[m[1].trim()] = m[2].trim()
+  }
+  return { fm, body }
+}
+
+export function parseFragment(file: string, text: string): Fragment {
+  const { fm, body } = parseFrontmatter(text)
+  const bullets = body
+    .split('\n')
+    .map((line) => line.trimEnd())
+    .filter((line) => line.trim().length > 0)
+  return {
+    file,
+    category: fm.category?.trim() || undefined,
+    bullets,
+  }
+}
+
+export function readFragments(): Fragment[] {
+  if (!existsSync(UNRELEASED_DIR)) return []
+  return readdirSync(UNRELEASED_DIR)
+    .filter((f) => f.endsWith('.md') && f !== 'README.md')
+    .sort()
+    .map((f) => parseFragment(f, readFileSync(join(UNRELEASED_DIR, f), 'utf8')))
+}
+
+/** Bullets between the version header and the next section, grouped by category. */
+export function buildSectionBody(frags: Fragment[]): string {
+  const groups: { category: string; bullets: string[] }[] = []
+  for (const frag of frags) {
+    const category = frag.category ?? DEFAULT_CATEGORY
+    let group = groups.find((g) => g.category === category)
+    if (!group) {
+      group = { category, bullets: [] }
+      groups.push(group)
+    }
+    group.bullets.push(...frag.bullets)
+  }
+  const lines: string[] = []
+  for (const group of groups) {
+    lines.push(`### ${group.category}`, '', ...group.bullets, '')
+  }
+  return lines.join('\n').replace(/\n{3,}/g, '\n\n').trim()
+}
+
+/** Insert `## [<version>] - <date>` directly under the `## [Unreleased]` header. */
+export function insertSection(changelog: string, version: string, date: string, body: string): string {
+  const unreleased = changelog.indexOf('## [Unreleased]')
+  if (unreleased === -1) throw new Error('CHANGELOG.md has no "## [Unreleased]" header')
+  const afterLine = changelog.indexOf('\n', unreleased) + 1
+  const tail = changelog.slice(afterLine).replace(/^\n+/, '')
+  const section = [`## [${version}] - ${date}`]
+  if (body.trim()) section.push('', body)
+  return `${changelog.slice(0, afterLine)}\n${section.join('\n')}\n\n${tail}`
+}
+
+export function bumpPackageJson(oldVersion: string, newVersion: string): void {
+  const path = 'package.json'
+  const text = readFileSync(path, 'utf8')
+  const re = new RegExp(`("version"\\s*:\\s*")${oldVersion.replace(/\./g, '\\.')}(")`)
+  if (!re.test(text)) throw new Error(`${path}: could not find version field "${oldVersion}"`)
+  writeFileSync(path, text.replace(re, `$1${newVersion}$2`))
+}
+
+export function archiveFragments(version: string, frags: Fragment[]): void {
+  if (!frags.length) return
+  const dest = join(ARCHIVE_DIR, version)
+  mkdirSync(dest, { recursive: true })
+  for (const frag of frags) {
+    renameSync(join(UNRELEASED_DIR, frag.file), join(dest, frag.file))
+  }
+}
+
+export function main(): void {
+  const { version: explicit, autoBump } = parseArgs(process.argv)
+  if (explicit === undefined && !autoBump) {
+    console.error('Usage: pnpm release:prepare -- <version> | pnpm release:prepare -- --patch')
+    console.error('Pass an explicit <version> (e.g. 0.1.0-alpha.2) or --patch for an auto bump.')
+    process.exit(1)
+  }
+  const pkg = JSON.parse(readFileSync('package.json', 'utf8')) as { version?: string }
+  const current = pkg.version
+  if (!current) throw new Error('package.json has no version')
+
+  const version = explicit ?? autoBumpPatch(current)
+  if (!VERSION_RE.test(version)) {
+    throw new Error(`Invalid version "${version}". Expected X.Y.Z or X.Y.Z-pre.N (e.g. 0.1.0-alpha.2)`)
+  }
+  const date = new Date().toISOString().slice(0, 10)
+
+  console.log(`Preparing release ${current} -> ${version}\n`)
+
+  const frags = readFragments()
+  console.log(`Fragments: ${frags.length}`)
+  for (const frag of frags) {
+    console.log(`  - ${frag.file}${frag.category ? `  [category: ${frag.category}]` : ''}`)
+  }
+  if (!frags.length) console.log('  (no fragments — section will be empty)')
+
+  const body = buildSectionBody(frags)
+  const changelogPath = 'CHANGELOG.md'
+  const changelog = readFileSync(changelogPath, 'utf8')
+  writeFileSync(changelogPath, insertSection(changelog, version, date, body))
+  console.log(`changelog: ${changelogPath} (## [${version}] - ${date})`)
+
+  bumpPackageJson(current, version)
+  console.log('bump: package.json')
+
+  archiveFragments(version, frags)
+  console.log(`archive: ${frags.length} fragment(s) -> ${join(ARCHIVE_DIR, version)}`)
+
+  console.log(`\nDone. Next: commit and open PR "release v${version}".`)
+  console.log(`Validate with: pnpm release:validate -- v${version}`)
+}
+
+// Run only when executed directly (tsx scripts/prepare-release.ts) —
+// importing the module (verification fixtures) must not start the release flow.
+const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : ''
+if (import.meta.url === entry) {
+  try {
+    main()
+  } catch (err) {
+    console.error(`\nprepare-release failed: ${err instanceof Error ? err.message : err}`)
+    process.exit(1)
+  }
+}

package/scripts/release-version.ts

@@ -0,0 +1,8 @@
+/**
+ * release-version.ts — shared release-version constants for the release
+ * scripts (prepare-release.ts and validate-release-version.ts). Single home
+ * for the semver contract so the two scripts cannot drift apart.
+ */
+
+/** Architect-approved loose semver: numeric core, optional prerelease suffix. */
+export const VERSION_RE = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/

package/scripts/validate-release-version.ts

@@ -0,0 +1,118 @@
+/**
+ * validate-release-version.ts — gate: the package version matches the release
+ * tag and the tag is not already released.
+ *
+ * Usage (from the repo root, via tsx — the package.json `release:validate`
+ * script):
+ *   pnpm release:validate -- v<version>    # e.g. v0.1.0-alpha.2
+ *
+ * Checks (single-package repo — one version surface):
+ *   1. Tag format: `v` prefix + /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.
+ *   2. package.json `version` equals the tag version (v prefix stripped).
+ *   3. Git tag `v<version>` does not exist yet (`git rev-parse` probe; exit 1
+ *      with "already released" when it does). Outside a git repository the
+ *      tag check is skipped with a note (fixture verification scenario).
+ *
+ * All paths are resolved relative to the current working directory, so the
+ * script works both from the repo root (`pnpm release:validate`) and from a
+ * throwaway fixture directory.
+ *
+ * The pure validation logic is exported (`validateReleaseVersion`,
+ * `tagExists`) so the committed vitest suite can cover the positive and
+ * negative cases; `main()` only runs when the file is executed directly.
+ */
+import { execFileSync } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { pathToFileURL } from 'node:url'
+import { VERSION_RE } from './release-version.ts'
+
+/**
+ * @returns true when the tag exists, false when it does not, null when the
+ * directory is not inside a git work tree.
+ */
+export function tagExists(version: string, cwd = process.cwd()): boolean | null {
+  try {
+    execFileSync('git', ['rev-parse', '--is-inside-work-tree'], { stdio: 'ignore', cwd })
+  } catch {
+    return null
+  }
+  try {
+    execFileSync('git', ['rev-parse', '--verify', '--quiet', `refs/tags/v${version}`], { stdio: 'ignore', cwd })
+    return true
+  } catch {
+    return false
+  }
+}
+
+export type ValidationResult = {
+  ok: boolean
+  errors: string[]
+  notes: string[]
+}
+
+/**
+ * Pure gate used by `main()` and by the test suite: the version matches
+ * package.json and the git tag is free. `tagState` is the result of
+ * `tagExists` (true / false / null when not a git repo).
+ */
+export function validateReleaseVersion(
+  version: string,
+  pkgVersion: string | undefined,
+  tagState: boolean | null,
+): ValidationResult {
+  const errors: string[] = []
+  const notes: string[] = []
+
+  if (pkgVersion !== version) {
+    errors.push(`MISMATCH package.json: tag v${version} => ${version}, package.json has ${pkgVersion ?? '<missing>'}`)
+  } else {
+    notes.push(`OK package.json: ${pkgVersion}`)
+  }
+
+  if (tagState === null) {
+    notes.push('note: not a git repository — skipping tag-exists check')
+  } else if (tagState) {
+    errors.push(`FAIL already released: git tag v${version} already exists`)
+  } else {
+    notes.push(`OK git tag v${version} does not exist`)
+  }
+
+  return { ok: errors.length === 0, errors, notes }
+}
+
+function main(): void {
+  // Strip a leading `--` (pnpm forwards `pnpm release:validate -- vX.Y.Z`
+  // as argv [`tsx`, `scripts/validate-release-version.ts`, `--`, `vX.Y.Z`])
+  // so direct `tsx scripts/validate-release-version.ts -- vX.Y.Z` matches the
+  // prepare-release argument handling.
+  const tag = process.argv.slice(2).find((a) => a !== '--')
+  if (!tag) {
+    console.error('Usage: tsx scripts/validate-release-version.ts v<version>')
+    console.error('Example: pnpm release:validate -- v0.1.0-alpha.2')
+    process.exit(1)
+  }
+
+  const version = tag.startsWith('v') ? tag.slice(1) : tag
+  if (!VERSION_RE.test(version)) {
+    console.error(`Invalid release tag "${tag}". Expected vX.Y.Z or vX.Y.Z-pre.N (e.g. v0.1.0-alpha.2).`)
+    process.exit(1)
+  }
+
+  const pkg = JSON.parse(readFileSync('package.json', 'utf8')) as { version?: string }
+  const result = validateReleaseVersion(version, pkg.version, tagExists(version))
+
+  for (const note of result.notes) console.log(note)
+  for (const error of result.errors) console.error(error)
+  if (!result.ok) {
+    console.error(`\nRelease tag ${tag} failed validation.`)
+    process.exit(1)
+  }
+  console.log(`\nAll checks passed for ${tag}.`)
+}
+
+// Run only when executed directly (tsx scripts/validate-release-version.ts) —
+// importing the module (the committed test suite) must not run the gate.
+const entry = process.argv[1] ? pathToFileURL(process.argv[1]).href : ''
+if (import.meta.url === entry) {
+  main()
+}