dsh-llm-fallbacks 0.1.4 → 0.1.5

package/README.md

@@ -134,7 +134,8 @@ The plugin installs as a **pure mount** — it never modifies the dsh source tre
 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.
+- **Named cordis service**: while the plugin is applied, `ctx.get('llm-fallbacks')` returns a pure-function service (`{ name, version, resolveRole, resolveChain, validateFallbacksConfig, detectLegacyKeys, declareSeeds, getEffectiveRoles, revertSeededPersona }`); after the plugin is disposed it is `undefined`. Runtime state stays observable via `fallbacks/switch` events, not through the service.
+- **Role seeds**: companion plugins auto-provision role rows with zero operator hand-edit — `declareSeeds([{ id, persona }])` declares the full current seed set (re-declaring is a no-op; ids failing `/^[a-z0-9-]{1,32}$/` or equal to `inherit` are skipped per-id with a warn, never coerced), `getEffectiveRoles()` reads back which roles are seeded and whether the persona is overridden, and `revertSeededPersona(id)` restores the **currently declared** seed default. The settings card shows a seed-default / override badge with a revert button; seeds never write `chain` / `fallback`.
 
 Full contract (export inventory, minimal examples, lifecycle, typing) → [docs/consumer-api.md](docs/consumer-api.md).
 

package/README.zh-CN.md

@@ -129,7 +129,8 @@ fallbacks:
 除插件挂载外，`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` 事件，不走服务对象。
+- **具名 cordis service**：插件 apply 期间 `ctx.get('llm-fallbacks')` 返回纯函数服务（`{ name, version, resolveRole, resolveChain, validateFallbacksConfig, detectLegacyKeys, declareSeeds, getEffectiveRoles, revertSeededPersona }`），插件 dispose 后为 `undefined`。运行态（冷却、最近切换）请读 `fallbacks/switch` 事件，不走服务对象。
+- **角色 seeds（种子角色）**：伴随插件可**零手工配置**自动补全角色行——`declareSeeds([{ id, persona }])` 声明完整当前种子集（重复声明为 no-op；不匹配 `/^[a-z0-9-]{1,32}$/` 或等于保留字 `inherit` 的 id 按条跳过并告警，绝不改写），`getEffectiveRoles()` 回读哪些角色为 seeded、persona 是否被覆盖，`revertSeededPersona(id)` 恢复**当前声明**的 seed 默认 persona。设置卡显示 seed 默认 / override 徽标并带 revert 按钮；seeds 永不写 `chain` / `fallback`。
 
 完整契约（导出清单、最小示例、生命周期、类型说明）见 [docs/consumer-api.md](docs/consumer-api.md)。
 

package/dist/client/fallbacks-store.d.ts

@@ -28,6 +28,7 @@ import type { ClientConnectionRpc, ConfigurableProviderView, HistoryEntry, IApiC
 import { type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client';
 import { type FallbackStrategy, type FallbacksConfig, type FallbacksRole, type FallbacksRoleRule, type FallbacksRoles } from '../config.ts';
 import type { FallbacksSwitchEventData } from '../events.ts';
+import type { SeedsWireStatus } from '../seeds.ts';
 /** The plugin's settings namespace on the host wire (settings/document-updated ns filter). */
 export declare const FALLBACKS_SETTINGS_NS = "fallbacks";
 /** Single-page history read for the status block (spec §2.5 D-5: `HISTORY_PAGE_MESSAGES`-sized). */
@@ -92,6 +93,13 @@ export interface FallbacksSettingsState {
      * over the user layer, so it cannot delete legacy keys).
      */
     legacyKeys: string[];
+    /**
+     * Seeded-role badge state (spec §9.4): one entry per live seed, with the
+     * gateway's override verdict. The wire field is authoritative — absent on
+     * an old response it keeps the last accepted value (the `legacyKeys`
+     * honest rule: only a `get` may settle seed truth).
+     */
+    seeds: SeedsWireStatus[];
     /** Provider/model directory snapshot (spec §2.5 D-4). */
     catalogStatus: 'idle' | 'loading' | 'ready' | 'error';
     /** Catalog read diagnostic: whole-load failure or per-provider lookups. */
@@ -345,6 +353,20 @@ export declare class FallbacksSettingsController {
      * merge cannot express). Same error handling as {@link save} (KD-G3).
      */
     resetToDefaults(): Promise<void>;
+    /**
+     * Revert one seeded role to its CURRENT declared seed default (spec §9.4,
+     * AC-3) through the gateway channel (`/api/fallbacks/revert-seed`). Same
+     * write guards as {@link save} — writable / saving / write-generation —
+     * and the same KD-G3 error handling: any business rejection or transport
+     * failure surfaces its message in `state.error` for the error banner and
+     * the form stays editable for retry. A business `{ reverted: false,
+     * reason }` outcome is still a successful RPC — the post-write read
+     * result (config / legacyKeys / seeds) lands either way, and the revert
+     * button stays disabled while the write is in flight.
+     * @param id - the seeded role id; the host matches it by trimmed id
+     *   against the seed registry (spec §9.3).
+     */
+    revertSeed(id: string): Promise<void>;
     /** Stop in-flight responses from publishing after plugin disposal. */
     dispose(): void;
     /**
@@ -358,7 +380,10 @@ export declare class FallbacksSettingsController {
      * same publish: the wire field drives the migration banner. save/reset
      * pass the POST-WRITE value (W-1/F-1) — or the previous value when the
      * response omits the field, so a write can never clear the banner
-     * against server truth; only a real `get` may.
+     * against server truth; only a real `get` may. `seeds` (spec §9.4)
+     * follows the same honest rule: the wire badge field is authoritative
+     * only when a real config resolved — a transient channel-down keeps the
+     * last accepted badge state.
      */
     private accept;
     private fail;

package/dist/client/index.js

@@ -100,6 +100,20 @@ window.__ModuleLoader__.load({
 			return current;
 		}
 		/**
+		* Shape-guard the wire `seeds` badge field (spec §9.4): only `{ id,
+		* overridden }` entries survive — the `legacyKeys` element-filter
+		* precedent. A non-array value resolves to `[]`; malformed entries are
+		* dropped, so an all-bad array also lands `[]`. The store never trusts a
+		* misshapen badge field.
+		*/
+		function parseSeedsWire(value) {
+			if (!Array.isArray(value)) return [];
+			return value.filter((entry) => {
+				if (!isRecord(entry)) return false;
+				return typeof entry.id === "string" && typeof entry.overridden === "boolean";
+			});
+		}
+		/**
 		* The provider dropdown's offer set (spec §2.5 D-4): catalog providers whose
 		* settings profile resolves in the describe namespaces — the Models page's
 		* `configured` predicate (`ui-models` store.ts): a provider is configured
@@ -410,6 +424,7 @@ window.__ModuleLoader__.load({
 				config: defaultFallbacksConfig,
 				present: false,
 				legacyKeys: [],
+				seeds: [],
 				catalogStatus: "idle",
 				catalogError: null,
 				providers: [],
@@ -473,14 +488,16 @@ window.__ModuleLoader__.load({
 					const writable = describeResult.result.value.writable;
 					let config;
 					let legacyKeys = [];
+					let seeds = [];
 					if (getResult !== void 0 && getResult.ok && getResult.value !== null && typeof getResult.value === "object") {
 						if ("config" in getResult.value) config = getResult.value.config;
 						if ("legacyKeys" in getResult.value) {
 							const wireLegacyKeys = getResult.value.legacyKeys;
 							if (Array.isArray(wireLegacyKeys)) legacyKeys = wireLegacyKeys.filter((key) => typeof key === "string");
 						}
+						if ("seeds" in getResult.value) seeds = parseSeedsWire(getResult.value.seeds);
 					}
-					this.accept(config, writable, legacyKeys);
+					this.accept(config, writable, legacyKeys, seeds);
 				} catch (error) {
 					if (generation !== this.readGeneration) return;
 					if (writeGenerationAtStart !== this.writeGeneration) return;
@@ -616,7 +633,12 @@ window.__ModuleLoader__.load({
 						const wireLegacyKeys = value.legacyKeys;
 						if (Array.isArray(wireLegacyKeys)) legacyKeys = wireLegacyKeys.filter((key) => typeof key === "string");
 					}
-					this.accept(config, true, legacyKeys);
+					let seeds = this.store.getSnapshot().seeds;
+					if (value !== null && typeof value === "object" && "seeds" in value) {
+						const wireSeeds = value.seeds;
+						if (Array.isArray(wireSeeds)) seeds = parseSeedsWire(wireSeeds);
+					}
+					this.accept(config, true, legacyKeys, seeds);
 				} catch (error) {
 					if (generation !== this.writeGeneration) return;
 					this.fail(error);
@@ -647,7 +669,55 @@ window.__ModuleLoader__.load({
 						const wireLegacyKeys = value.legacyKeys;
 						if (Array.isArray(wireLegacyKeys)) legacyKeys = wireLegacyKeys.filter((key) => typeof key === "string");
 					}
-					this.accept(config, true, legacyKeys);
+					let seeds = this.store.getSnapshot().seeds;
+					if (value !== null && typeof value === "object" && "seeds" in value) {
+						const wireSeeds = value.seeds;
+						if (Array.isArray(wireSeeds)) seeds = parseSeedsWire(wireSeeds);
+					}
+					this.accept(config, true, legacyKeys, seeds);
+				} catch (error) {
+					if (generation !== this.writeGeneration) return;
+					this.fail(error);
+				}
+			}
+			/**
+			* Revert one seeded role to its CURRENT declared seed default (spec §9.4,
+			* AC-3) through the gateway channel (`/api/fallbacks/revert-seed`). Same
+			* write guards as {@link save} — writable / saving / write-generation —
+			* and the same KD-G3 error handling: any business rejection or transport
+			* failure surfaces its message in `state.error` for the error banner and
+			* the form stays editable for retry. A business `{ reverted: false,
+			* reason }` outcome is still a successful RPC — the post-write read
+			* result (config / legacyKeys / seeds) lands either way, and the revert
+			* button stays disabled while the write is in flight.
+			* @param id - the seeded role id; the host matches it by trimmed id
+			*   against the seed registry (spec §9.3).
+			*/
+			async revertSeed(id) {
+				const state = this.store.getSnapshot();
+				if (!state.writable || state.status === "saving") return;
+				const generation = ++this.writeGeneration;
+				this.store.update((draft) => {
+					draft.status = "saving";
+					draft.error = null;
+				});
+				try {
+					const result = await this.rpc.call("/api", "fallbacks/revert-seed", { args: { id } });
+					if (generation !== this.writeGeneration) return;
+					if (!result.ok) throw result.error;
+					const value = result.value;
+					const config = value !== null && typeof value === "object" && "config" in value ? value.config : void 0;
+					let legacyKeys = this.store.getSnapshot().legacyKeys;
+					if (value !== null && typeof value === "object" && "legacyKeys" in value) {
+						const wireLegacyKeys = value.legacyKeys;
+						if (Array.isArray(wireLegacyKeys)) legacyKeys = wireLegacyKeys.filter((key) => typeof key === "string");
+					}
+					let seeds = this.store.getSnapshot().seeds;
+					if (value !== null && typeof value === "object" && "seeds" in value) {
+						const wireSeeds = value.seeds;
+						if (Array.isArray(wireSeeds)) seeds = parseSeedsWire(wireSeeds);
+					}
+					this.accept(config, true, legacyKeys, seeds);
 				} catch (error) {
 					if (generation !== this.writeGeneration) return;
 					this.fail(error);
@@ -672,9 +742,12 @@ window.__ModuleLoader__.load({
 			* same publish: the wire field drives the migration banner. save/reset
 			* pass the POST-WRITE value (W-1/F-1) — or the previous value when the
 			* response omits the field, so a write can never clear the banner
-			* against server truth; only a real `get` may.
+			* against server truth; only a real `get` may. `seeds` (spec §9.4)
+			* follows the same honest rule: the wire badge field is authoritative
+			* only when a real config resolved — a transient channel-down keeps the
+			* last accepted badge state.
 			*/
-			accept(config, writable, legacyKeys) {
+			accept(config, writable, legacyKeys, seeds) {
 				const parsed = config === void 0 ? void 0 : parseFallbacksConfig(config);
 				this.store.update((state) => {
 					state.status = "ready";
@@ -682,6 +755,7 @@ window.__ModuleLoader__.load({
 					state.writable = writable;
 					state.present = parsed !== void 0;
 					state.legacyKeys = parsed === void 0 ? state.legacyKeys : legacyKeys;
+					state.seeds = parsed === void 0 ? state.seeds : seeds;
 					if (parsed !== void 0) state.config = parsed;
 					state.configuredProviders = configuredProvidersOf(state.providers, this.namespaces);
 				});
@@ -789,6 +863,10 @@ window.__ModuleLoader__.load({
 			"roles.idPlaceholder": "例如 reviewer",
 			"roles.persona": "人格提示",
 			"roles.personaPlaceholder": "例如：你是资深代码审查员",
+			"roles.seedDefault": "seed 默认",
+			"roles.seedOverride": "seed 覆盖",
+			"roles.revertPersona": "还原 Seed 默认",
+			"roles.seedChainOptional": "角色 \"{id}\" 为 seed 角色：链可留空，保存不会被拦截",
 			"roles.fallback": "链拼接策略",
 			"roles.fallback.inherit-root": "继承 root（角色链后追加 rootChain）",
 			"roles.fallback.none": "仅角色链（不追加 rootChain）",
@@ -919,6 +997,10 @@ window.__ModuleLoader__.load({
 			"roles.idPlaceholder": "e.g. reviewer",
 			"roles.persona": "Persona",
 			"roles.personaPlaceholder": "e.g. you are a senior code reviewer",
+			"roles.seedDefault": "Seed default",
+			"roles.seedOverride": "Seed override",
+			"roles.revertPersona": "Revert to seed default",
+			"roles.seedChainOptional": "Role \"{id}\" is a seed role: the chain may stay empty",
 			"roles.fallback": "Chain append",
 			"roles.fallback.inherit-root": "Inherit root (append rootChain after the role chain)",
 			"roles.fallback.none": "Role chain only (no rootChain)",
@@ -1205,8 +1287,14 @@ window.__ModuleLoader__.load({
 		* rootChain and role chains. Returns one localized message per violation;
 		* a non-empty result blocks {@link save} — the draft is never written.
 		* `persona` is free text and never validated.
+		*
+		* `seededIds` is the live trimmed-id → overridden map derived from
+		* `state.seeds` (spec §9.4): the empty-chain block relaxes for seeded ids
+		* only (spec §9.6 / AC-3 — a seeded role's chain is legitimately empty by
+		* design, R4, and its persona edits must stay persistable); non-seeded
+		* behavior is byte-identical.
 		*/
-		function validateDraft(draft, t) {
+		function validateDraft(draft, t, seededIds) {
 			const errors = [];
 			const declaredIds = /* @__PURE__ */ new Set();
 			for (const role of draft.roles.list) {
@@ -1222,7 +1310,7 @@ window.__ModuleLoader__.load({
 						message: error.message
 					}));
 				}
-				if ((role.chain ?? []).length === 0) errors.push(t("validation.roleChainRequired", { id: role.id }));
+				if ((role.chain ?? []).length === 0 && !seededIds.has(role.id.trim())) errors.push(t("validation.roleChainRequired", { id: role.id }));
 			}
 			for (const entry of draft.rootChain) try {
 				parseSelector(entry);
@@ -1572,6 +1660,8 @@ window.__ModuleLoader__.load({
 			const unknownCodes = scalars.triggerCodes.filter((code) => !KNOWN_TRIGGER_CODES.includes(code));
 			const roleOptions = ruleRoleOptions({ list: roleRows });
 			const invalidRoleIds = validationAttempted ? collectInvalidRoleIds(roleRows) : null;
+			const seededIds = /* @__PURE__ */ new Map();
+			for (const seed of state.seeds) seededIds.set(seed.id.trim(), seed.overridden);
 			const effectiveModel = deriveEffectiveModel(state.config, state.switches);
 			const effectiveModelLine = effectiveModel.kind === "unavailable" ? t("status.effectiveModel.unavailable") : `${effectiveModel.provider}/${effectiveModel.model} · ${t("status.effectiveModel.note")}`;
 			const latestSwitch = state.switches[0];
@@ -1605,7 +1695,7 @@ window.__ModuleLoader__.load({
 				dirty
 			]);
 			const save = () => {
-				const errors = validateDraft(draft, t);
+				const errors = validateDraft(draft, t, seededIds);
 				if (hasEmptyRuleRows) errors.push(t("validation.ruleRoleRequired"));
 				if (errors.length > 0) {
 					setValidationErrors(errors);
@@ -1626,7 +1716,7 @@ window.__ModuleLoader__.load({
 			};
 			(0, react.useEffect)(() => {
 				if (!validationAttempted) return;
-				if (validateDraft(draft, t).length === 0 && !ruleRows.some((row) => row.role === "")) {
+				if (validateDraft(draft, t, seededIds).length === 0 && !ruleRows.some((row) => row.role === "")) {
 					setValidationErrors([]);
 					setValidationAttempted(false);
 				}
@@ -1849,6 +1939,7 @@ window.__ModuleLoader__.load({
 														className: FallbacksCard_module_css_default.list,
 														children: roleRows.map((row, index) => {
 															const invalid = invalidRoleIds?.has(row.id.trim()) ?? false;
+															const seed = seededIds.get(row.id.trim());
 															return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 																className: FallbacksCard_module_css_default.editorCard,
 																children: [
@@ -1883,20 +1974,38 @@ window.__ModuleLoader__.load({
 																		className: FallbacksCard_module_css_default.ruleGrid,
 																		children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 																			className: FallbacksCard_module_css_default.ruleCell,
-																			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
-																				className: FallbacksCard_module_css_default.ruleCellLabel,
-																				children: t("roles.persona")
-																			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("textarea", {
-																				rows: 3,
-																				className: `${FallbacksCard_module_css_default.input} ${FallbacksCard_module_css_default.inputTextarea}`,
-																				value: row.persona,
-																				placeholder: t("roles.personaPlaceholder"),
-																				"aria-label": t("roles.persona"),
-																				disabled: !writable,
-																				onChange: (event) => {
-																					updateRoleRow(index, { persona: event.target.value });
-																				}
-																			})]
+																			children: [
+																				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+																					className: FallbacksCard_module_css_default.ruleCellLabel,
+																					children: t("roles.persona")
+																				}),
+																				/* @__PURE__ */ (0, react_jsx_runtime.jsx)("textarea", {
+																					rows: 3,
+																					className: `${FallbacksCard_module_css_default.input} ${FallbacksCard_module_css_default.inputTextarea}`,
+																					value: row.persona,
+																					placeholder: t("roles.personaPlaceholder"),
+																					"aria-label": t("roles.persona"),
+																					disabled: !writable,
+																					onChange: (event) => {
+																						updateRoleRow(index, { persona: event.target.value });
+																					}
+																				}),
+																				seed !== void 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+																					className: FallbacksCard_module_css_default.hint,
+																					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+																						className: FallbacksCard_module_css_default.pending,
+																						children: t(seed ? "roles.seedOverride" : "roles.seedDefault")
+																					}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+																						variant: "outline",
+																						size: "sm",
+																						disabled: !writable || saving,
+																						onClick: () => {
+																							controller.revertSeed(row.id.trim());
+																						},
+																						children: t("roles.revertPersona")
+																					})]
+																				})
+																			]
 																		})
 																	}),
 																	/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
@@ -1915,7 +2024,7 @@ window.__ModuleLoader__.load({
 																			}
 																		}, 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 })
+																			children: seed !== void 0 ? t("roles.seedChainOptional", { id: row.id }) : t("validation.roleChainRequired", { id: row.id })
 																		})]
 																	}),
 																	/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {

package/dist/client/locales.d.ts

@@ -54,6 +54,10 @@ export declare const zh: {
     'roles.idPlaceholder': string;
     'roles.persona': string;
     'roles.personaPlaceholder': string;
+    'roles.seedDefault': string;
+    'roles.seedOverride': string;
+    'roles.revertPersona': string;
+    'roles.seedChainOptional': string;
     'roles.fallback': string;
     'roles.fallback.inherit-root': string;
     'roles.fallback.none': string;
@@ -186,6 +190,10 @@ export declare const en: {
     'roles.idPlaceholder': string;
     'roles.persona': string;
     'roles.personaPlaceholder': string;
+    'roles.seedDefault': string;
+    'roles.seedOverride': string;
+    'roles.revertPersona': string;
+    'roles.seedChainOptional': string;
     'roles.fallback': string;
     'roles.fallback.inherit-root': string;
     'roles.fallback.none': string;

package/dist/gateway.d.ts

@@ -1,7 +1,8 @@
 /**
- * T1 (plan llm-fallbacks-settings-gateway) — host-side `fallbacks` config
- * gateway: the `/api/fallbacks/get` + `/api/fallbacks/set` +
- * `/api/fallbacks/reset` endpoints.
+ * T1 (plan llm-fallbacks-settings-gateway) + T3 (plan fallbacks-role-seeds) —
+ * host-side `fallbacks` config gateway: the `/api/fallbacks/get` +
+ * `/api/fallbacks/set` + `/api/fallbacks/reset` + `/api/fallbacks/revert-seed`
+ * endpoints.
  *
  * Transport: the typertGateway `/api` interceptor is the single host-wide RPC
  * slot (a plugin must NOT `connection.rpc.intercept('/api')` again — it would
@@ -37,7 +38,11 @@
  * method — advisor has only get/set) clears the user layer via
  * `ctx.settings.replace(ns, {})`: `set` is merge-only and cannot express
  * "reset to composition defaults" (sending default VALUES as a patch would
- * pin stale defaults into the user layer).
+ * pin stale defaults into the user layer). Every read response (get/set/reset)
+ * carries the additive `seeds: SeedsWireStatus[]` badge state (spec §9.4) and
+ * `revert-seed` exposes revert-to-current-seed-default for one id — both
+ * delegate to the per-apply `FallbacksSeedManager` passed into the
+ * constructor (single point of truth, no copied manager logic).
  *
  * The settings service is OPTIONAL (no settings service → the bridge source
  * stays the entry, `get` still works; `set`/`reset` fail with a clear
@@ -57,6 +62,7 @@ import type { Context } from '@deepseek-ai/cordis';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { TypertContribution } from '@deepseek-ai/dsh-typert-registry';
 import type { FallbacksConfig } from './config';
+import type { FallbacksSeedManager, SeedRevertOutcome, SeedsWireStatus } from './seeds';
 /** The `fallbacks` settings namespace (registered when a settings service exists). */
 export declare const FALLBACKS_SETTINGS_NAMESPACE: import("@deepseek-ai/dsh-settings").SettingsNamespace;
 /**
@@ -72,6 +78,20 @@ export interface FallbacksSettingsBridge {
 }
 /** Patch shape accepted by `fallbacks.set` — any subset of the config keys. */
 export type FallbacksConfigPatch = Partial<FallbacksConfig>;
+/**
+ * The wire response of every read (get/set/reset — W-1/F-1): the normalized
+ * config plus `legacyKeys` plus the additive `seeds` badge state (spec §9.4,
+ * legacyKeys precedent — old clients ignore it).
+ */
+export interface FallbacksReadResult {
+    config: FallbacksConfig;
+    legacyKeys: string[];
+    seeds: SeedsWireStatus[];
+}
+/** The `fallbacks/revert-seed` response — a read result plus the revert outcome. */
+export interface FallbacksRevertResult extends FallbacksReadResult {
+    outcome: SeedRevertOutcome;
+}
 /**
  * The host-side `fallbacks` config gateway (`/api/fallbacks/get` +
  * `/api/fallbacks/set` + `/api/fallbacks/reset`). Registered as the cordis
@@ -86,14 +106,19 @@ export type FallbacksConfigPatch = Partial<FallbacksConfig>;
  */
 export declare class FallbacksConfigGateway extends TypertRemoteService {
     private readonly bridge;
+    /** The per-apply seed manager — single point of truth for seed state (spec §9.4). */
+    private readonly seeds;
     /** The live settings service once the optional inject child activates. */
     private settings;
     /**
      * @param ctx - owning context (the plugin fiber's ctx inside `apply`).
      * @param bridge - the same `FallbacksSettingsBridge` the runtime reads, so
      *   get/set/reset always operate on the live composed config.
+     * @param seeds - the per-apply `FallbacksSeedManager` constructed in
+     *   `apply()` — the gateway delegates badge state and revert to it (no
+     *   copied manager logic), through the io seam built over this bridge.
      */
-    constructor(ctx: Context, bridge: FallbacksSettingsBridge);
+    constructor(ctx: Context, bridge: FallbacksSettingsBridge, seeds: FallbacksSeedManager);
     /**
      * Read the current composed config (schema defaults → entry base → settings
      * user layer). No hard-gate resolver (ADR-2): the raw composed config is
@@ -102,12 +127,11 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      *   two-block-era fields (`chains` / `roles.default` / undeclared rule
      *   role refs) detected on the composed source (schemastery retains them,
      *   plan Task 1 Step 1), so the client can show a migration banner (spec
-     *   §9, incremental field — old clients ignore it).
+     *   §9, incremental field — old clients ignore it) — plus the additive
+     *   `seeds` badge state (spec §9.4, legacyKeys precedent — old clients
+     *   ignore it).
      */
-    get(): {
-        config: FallbacksConfig;
-        legacyKeys: string[];
-    };
+    get(): FallbacksReadResult;
     /**
      * Validate a config patch and write it to the settings USER layer (live —
      * the runtime re-reads the same bridge source; no restart needed).
@@ -117,28 +141,42 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      *   POST-WRITE composed source (W-1/F-1): `set` is a settings MERGE, so a
      *   legacy user layer (`chains` / `roles.default`) survives a new-shape
      *   save — the response must keep reporting it, or the client banner
-     *   would clear against server truth. Same shape as `get`.
+     *   would clear against server truth — plus the post-write `seeds` badge
+     *   state (same W-1/F-1 rule as `legacyKeys`). Same shape as `get`.
      * @throws when the patch fails `Config` validation, or when no settings
      *   service is composed (KD-G5: the write channel is unavailable).
      */
-    set(patch: FallbacksConfigPatch): Promise<{
-        config: FallbacksConfig;
-        legacyKeys: string[];
-    }>;
+    set(patch: FallbacksConfigPatch): Promise<FallbacksReadResult>;
     /**
      * Clear the fallbacks settings USER layer so the composition defaults
      * reapply (`settings.replace(ns, {})` — the in-process removal path a
      * merge-only `set` cannot express).
      * @returns the new composed config plus `legacyKeys` on the post-write
      *   source — `replace` drops the user layer, but legacy keys carried by
-     *   the entry base survive and are correctly re-reported (W-1/F-1).
+     *   the entry base survive and are correctly re-reported (W-1/F-1) — plus
+     *   the post-write `seeds` badge state (clearing the user layer also
+     *   clears the materialized seed rows, so the honest response reports the
+     *   emptied state; the registry survives and the next declare re-materializes).
      * @throws when no settings service is composed (KD-G5: the write channel
      *   is unavailable).
      */
-    reset(): Promise<{
-        config: FallbacksConfig;
-        legacyKeys: string[];
-    }>;
+    reset(): Promise<FallbacksReadResult>;
+    /**
+     * Revert one seeded role to its CURRENT declared seed default (AC-3, spec
+     * §9.4) — the gateway half of surface (c), delegating to the same manager
+     * the service method uses (single point of truth). Business failures are
+     * values, never throws: a non-seeded id or a deleted row returns
+     * `{ reverted: false, reason }` without writing. The only throw is the
+     * KD-G5 settings-unavailable path, and only when a write is actually
+     * needed (an idempotent revert at the default needs no channel).
+     * @param id - the seeded role id; matched by trimmed id against the
+     *   registry (row matching, spec §9.3).
+     * @returns the post-write read result (config / legacyKeys / seeds — the
+     *   write happened before this read, W-1/F-1) plus the revert `outcome`.
+     * @throws TypeError when `id` is not a string; Error when the settings
+     *   write channel is unavailable (KD-G5).
+     */
+    revertSeed(id: string): Promise<FallbacksRevertResult>;
     /**
      * Read the live composed config and normalize it to the typertGateway JSON
      * wire boundary. Containment (guide §10): a malformed stored user layer
@@ -156,11 +194,25 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
     /**
      * The wire response of every read (get/set/reset — W-1/F-1): the
      * normalized config plus `legacyKeys` detected on the live composed
-     * source. set/reset must report the POST-WRITE source: the settings
-     * merge retains legacy user-layer keys, so a save cannot clear them —
-     * the honest response keeps the migration banner until a get agrees.
+     * source plus the additive `seeds` badge state. set/reset must report the
+     * POST-WRITE source: the settings merge retains legacy user-layer keys,
+     * so a save cannot clear them — the honest response keeps the migration
+     * banner until a get agrees; `seeds` follows the same rule (post-write
+     * badge state, W-1/F-1).
      */
     private readResult;
+    /**
+     * The io seam the seed manager writes through (spec §9.1): `read` walks
+     * the same live bridge source the gateway reads; `writeRoles` persists a
+     * full `{ list, rules }` to the settings user layer — both arrays always
+     * computed from a fresh composed read, so the write stays correct under
+     * dsh-settings `mergeLayers` array-replace semantics and never touches
+     * operator rules. The write channel fails with the same KD-G5 message as
+     * set/reset when no settings service is composed. Built fresh per call so
+     * the mutable settings capture is read at call time (the inject child
+     * swaps it when the settings service appears/disappears).
+     */
+    private seedsIo;
 }
 /**
  * The explicit typert contribution for the `fallbacks` gateway endpoints —

package/dist/index.d.ts

@@ -34,6 +34,7 @@ import { Config } from './schema.ts';
 import { resolveChain } from './chains.ts';
 import { resolveRole } from './roles.ts';
 import { FallbackStateStore } from './state.ts';
+import { type EffectiveRolesReadback, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertOutcome } from './seeds.ts';
 /** The plugin row id mounted by the profile bundle patch. */
 export declare const name = "llm-fallbacks";
 /**
@@ -46,9 +47,11 @@ 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.
+ * metadata, plus the three ADDITIVE role-seed methods (spec §9.1, plan
+ * fallbacks-role-seeds T2). Deliberately no state BEARING FIELDS (no
+ * stateStore, no event emitters, no filter helpers) — the seed methods are
+ * closures over the per-apply `FallbacksSeedManager`, so state stays behind
+ * the closure and dies with the fiber (spec §9.5).
  */
 export interface FallbacksService {
     /** Matches the plugin `name`. */
@@ -59,6 +62,12 @@ export interface FallbacksService {
     resolveChain: typeof resolveChain;
     validateFallbacksConfig: typeof validateFallbacksConfig;
     detectLegacyKeys: typeof detectLegacyKeys;
+    /** (a) Declare the companion's FULL current seed set (replacement semantics, spec §9.1). */
+    declareSeeds(seeds: readonly SeedDeclaration[]): Promise<SeedDeclareOutcome>;
+    /** (b) Sync readback — effective taxonomy with seed annotations. */
+    getEffectiveRoles(): EffectiveRolesReadback;
+    /** (c) Revert one id to the CURRENT declared seed default. */
+    revertSeededPersona(id: string): Promise<SeedRevertOutcome>;
 }
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -75,6 +84,7 @@ 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';
+export { FallbacksSeedManager, type EffectiveRole, type EffectiveRolesReadback, type SeedConflict, type SeedDeclaration, type SeedDeclareOutcome, type SeedRevertFailReason, type SeedRevertOutcome, type SeedSkipReason, type SeedsIo, type SeedsWireStatus, } from './seeds.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

@@ -403,10 +403,12 @@ const ROLES_KEYS = {
 };
 var FallbacksConfigGateway = class extends TypertRemoteService {
 	bridge;
+	seeds;
 	settings;
-	constructor(ctx, bridge) {
+	constructor(ctx, bridge, seeds) {
 		super(ctx, "fallbacks");
 		this.bridge = bridge;
+		this.seeds = seeds;
 		ctx.inject(["settings"], (sctx) => {
 			this.settings = sctx.settings;
 			return () => {
@@ -433,6 +435,14 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 		await settings.replace(FALLBACKS_SETTINGS_NAMESPACE, {});
 		return this.readResult();
 	}
+	async revertSeed(id) {
+		if (typeof id !== "string") throw new TypeError("dsh-llm-fallbacks: seed revert id must be a string");
+		const outcome = await this.seeds.revert(id, this.seedsIo());
+		return {
+			...this.readResult(),
+			outcome
+		};
+	}
 	readConfig(source = this.bridge.source()) {
 		const wire = {};
 		for (const key of Object.keys(CONFIG_KEYS)) {
@@ -446,7 +456,18 @@ var FallbacksConfigGateway = class extends TypertRemoteService {
 		const source = this.bridge.source();
 		return {
 			config: this.readConfig(source),
-			legacyKeys: detectLegacyKeys(source)
+			legacyKeys: detectLegacyKeys(source),
+			seeds: this.seeds.wireStatus(this.seedsIo())
+		};
+	}
+	seedsIo() {
+		const settings = this.settings;
+		return {
+			read: () => this.bridge.source(),
+			writeRoles: (roles) => {
+				if (settings === void 0) throw new Error("fallbacks: settings service is unavailable — configuration cannot be written");
+				return settings.update(FALLBACKS_SETTINGS_NAMESPACE, { roles });
+			}
 		};
 	}
 };
@@ -514,6 +535,21 @@ function fallbacksTypertContribution() {
 				invocation: { kind: "direct" },
 				parameters: [],
 				result: { mode: "src-json" }
+			},
+			{
+				id: "dsh-llm-fallbacks#fallbacks/revert-seed",
+				service: "fallbacks",
+				namespace: "fallbacks",
+				method: "revert-seed",
+				implementation: "revertSeed",
+				invocation: { kind: "direct" },
+				parameters: [{
+					name: "id",
+					wire: "id",
+					source: "json",
+					codec: { mode: "src-json" }
+				}],
+				result: { mode: "src-json" }
 			}
 		]
 	};
@@ -644,6 +680,188 @@ function registerFallbacksCommands(registry, controller, locale = "zh") {
 	});
 }
 //#endregion
+//#region .build/host/seeds.js
+var FallbacksSeedManager = class {
+	logger;
+	registry = new Map();
+	constructor(logger) {
+		this.logger = logger;
+	}
+	async declare(seeds, io) {
+		const outcome = {
+			applied: [],
+			skipped: [],
+			conflicts: []
+		};
+		const registry = new Map();
+		for (const seed of seeds) {
+			if (typeof seed.id !== "string" || !ROLE_ID_PATTERN.test(seed.id)) {
+				outcome.skipped.push({
+					id: String(seed.id),
+					reason: "invalid-id"
+				});
+				this.warnSkip(seed.id, "invalid-id");
+				continue;
+			}
+			if (seed.id === "inherit") {
+				outcome.skipped.push({
+					id: seed.id,
+					reason: "reserved-id"
+				});
+				this.warnSkip(seed.id, "reserved-id");
+				continue;
+			}
+			if (registry.has(seed.id)) {
+				outcome.skipped.push({
+					id: seed.id,
+					reason: "duplicate-in-batch"
+				});
+				this.warnSkip(seed.id, "duplicate-in-batch");
+				continue;
+			}
+			registry.set(seed.id, seed.persona);
+			outcome.applied.push(seed.id);
+		}
+		const config = io.read();
+		const currentList = roleRows(config);
+		const currentRules = roleRules(config);
+		const newList = materialize(currentList, registry, this.registry, outcome.conflicts);
+		for (const conflict of outcome.conflicts) this.logger.warn(`llm-fallbacks: seeds: persona-source conflict for seed id ${JSON.stringify(conflict.id)} — operator row persona kept (never overwritten)`);
+		const computed = {
+			list: newList,
+			rules: currentRules
+		};
+		if (!deepEqual(newList, currentList)) await io.writeRoles(computed);
+		this.registry = registry;
+		return outcome;
+	}
+	effectiveRoles(io) {
+		return { roles: roleRows(io.read()).map((row) => {
+			const seedPersona = this.registry.get(row.id.trim());
+			const seeded = seedPersona !== void 0;
+			const effective = {
+				id: row.id,
+				persona: row.persona,
+				seeded,
+				personaOverridden: seeded && row.persona !== seedPersona
+			};
+			if (seeded) effective.seedPersona = seedPersona;
+			if (row.chain !== void 0) effective.chain = row.chain;
+			if (row.fallback !== void 0) effective.fallback = row.fallback;
+			return effective;
+		}) };
+	}
+	wireStatus(io) {
+		const status = [];
+		for (const row of roleRows(io.read())) {
+			const seedPersona = this.registry.get(row.id.trim());
+			if (seedPersona === void 0) continue;
+			status.push({
+				id: row.id,
+				overridden: row.persona !== seedPersona
+			});
+		}
+		return status;
+	}
+	async revert(id, io) {
+		const seedId = id.trim();
+		const seedPersona = this.registry.get(seedId);
+		if (seedPersona === void 0) return {
+			reverted: false,
+			reason: "not-seeded"
+		};
+		const config = io.read();
+		const rows = roleRows(config);
+		const rules = roleRules(config);
+		const index = rows.findIndex((row) => row.id.trim() === seedId);
+		if (index === -1) return {
+			reverted: false,
+			reason: "row-absent"
+		};
+		if (rows[index].persona === seedPersona) return {
+			reverted: true,
+			persona: seedPersona
+		};
+		const nextList = rows.map((row, i) => i === index ? {
+			...row,
+			persona: seedPersona
+		} : row);
+		await io.writeRoles({
+			list: nextList,
+			rules
+		});
+		return {
+			reverted: true,
+			persona: seedPersona
+		};
+	}
+	warnSkip(id, reason) {
+		const shown = typeof id === "string" ? JSON.stringify(id) : String(id);
+		if (reason === "invalid-id") this.logger.warn(`llm-fallbacks: seeds: skipping seed id ${shown} — invalid-id (must match ${String(ROLE_ID_PATTERN)} as declared)`);
+		else if (reason === "reserved-id") this.logger.warn(`llm-fallbacks: seeds: skipping seed id ${shown} — reserved-id ("${INHERIT_ROLE_ID}" is not a legal seed target)`);
+		else this.logger.warn(`llm-fallbacks: seeds: skipping seed id ${shown} — duplicate-in-batch (first wins)`);
+	}
+};
+function materialize(rows, registry, previous, conflicts) {
+	const next = [];
+	for (const row of rows) {
+		const seedId = row.id.trim();
+		const incoming = registry.get(seedId);
+		if (incoming === void 0) {
+			next.push(row);
+			continue;
+		}
+		const prior = previous.get(seedId);
+		if (prior === void 0) {
+			if (row.persona !== incoming) conflicts.push({
+				id: seedId,
+				kind: "persona-source"
+			});
+			next.push(row);
+			continue;
+		}
+		if (row.persona === prior) {
+			next.push({
+				...row,
+				persona: incoming
+			});
+			continue;
+		}
+		if (row.persona !== incoming) conflicts.push({
+			id: seedId,
+			kind: "persona-source"
+		});
+		next.push(row);
+	}
+	for (const [id, persona] of registry) if (!rows.some((row) => row.id.trim() === id)) next.push({
+		id,
+		persona
+	});
+	return next;
+}
+function roleRows(config) {
+	const list = config.roles?.list;
+	return Array.isArray(list) ? list : [];
+}
+function roleRules(config) {
+	const rules = config.roles?.rules;
+	return Array.isArray(rules) ? rules : [];
+}
+function deepEqual(a, b) {
+	if (a === b) return true;
+	if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false;
+	if (Array.isArray(a) !== Array.isArray(b)) return false;
+	if (Array.isArray(a)) {
+		const aa = a;
+		const bb = b;
+		return aa.length === bb.length && aa.every((item, index) => deepEqual(item, bb[index]));
+	}
+	const aKeys = Object.keys(a);
+	const bKeys = Object.keys(b);
+	if (aKeys.length !== bKeys.length) return false;
+	return aKeys.every((key) => deepEqual(a[key], b[key]));
+}
+//#endregion
 //#region .build/host/index.js
 const name = "llm-fallbacks";
 const provide = ["llm-fallbacks"];
@@ -695,6 +913,23 @@ function overrideConfig(seed, to) {
 function apply(ctx, config = defaultFallbacksConfig) {
 	const logger = ctx.logger("llm-fallbacks");
 	const entry = Config(config);
+	const seeds = new FallbacksSeedManager(logger);
+	const seedsSettingsUnavailable = "llm-fallbacks: seeds: settings service is unavailable — seed roles cannot be written";
+	let writeRoles = () => {
+		throw new Error(seedsSettingsUnavailable);
+	};
+	ctx.inject(["settings"], (sctx) => {
+		writeRoles = (roles) => sctx.settings.update(FALLBACKS_SETTINGS_NAMESPACE, { roles });
+		return () => {
+			writeRoles = () => {
+				throw new Error(seedsSettingsUnavailable);
+			};
+		};
+	});
+	const seedsIo = {
+		read: () => source(),
+		writeRoles: (roles) => writeRoles(roles)
+	};
 	try {
 		ctx.provide("llm-fallbacks", {
 			name: "llm-fallbacks",
@@ -702,7 +937,10 @@ function apply(ctx, config = defaultFallbacksConfig) {
 			resolveRole,
 			resolveChain,
 			validateFallbacksConfig,
-			detectLegacyKeys
+			detectLegacyKeys,
+			declareSeeds: (declarations) => seeds.declare(declarations, seedsIo),
+			getEffectiveRoles: () => seeds.effectiveRoles(seedsIo),
+			revertSeededPersona: (id) => seeds.revert(id, seedsIo)
 		});
 	} catch (error) {
 		if (!(error instanceof Error) || !error.message.includes("has been registered")) throw error;
@@ -726,7 +964,7 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	});
 	const bridge = { source: () => source() };
 	try {
-		new FallbacksConfigGateway(ctx, bridge);
+		new FallbacksConfigGateway(ctx, bridge, seeds);
 	} catch (error) {
 		if (!(error instanceof Error) || !error.message.includes("has been registered")) throw error;
 		ctx.logger("llm-fallbacks").debug("fallbacks gateway already registered — no gateway on this fiber (multi-fiber dedupe)");
@@ -861,4 +1099,4 @@ function apply(ctx, config = defaultFallbacksConfig) {
 	});
 }
 //#endregion
-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 };
+export { Config, FallbacksSeedManager, 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/dist/seeds.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Role-seeds domain module (plan fallbacks-role-seeds Task 1).
+ *
+ * A companion plugin declares `[{ id, persona }]` seeds; this module
+ * validates each id AS DECLARED (`ROLE_ID_PATTERN`, reserved `inherit`),
+ * merges the declarations into the role taxonomy with immutable-id /
+ * override / revert semantics, and writes through a narrow IO seam
+ * (`SeedsIo`). It is free of `@deepseek-ai/*` value imports (bundle
+ * purity gate) — the client may type-only import from here.
+ *
+ * State model (spec §9.2) — two stores, strictly separated:
+ * 1. operator config rows (persisted; a seeded role is a plain
+ *    `roles.list` row `{ id, persona }`), and
+ * 2. an in-memory per-apply seed registry (`Map<id, seedPersona>`),
+ *    declare = replacement (the batch is the companion's full current set).
+ * `seeded` / `personaOverridden` are DERIVED at read time, never stored —
+ * a config round-trip cannot orphan an override (AC-3).
+ *
+ * Materialization (spec §9.2): append `{ id, persona }` (two keys only,
+ * R4) / attach row untouched / at-default tracking / override preserved +
+ * `'persona-source'` conflict / omitted id drops from the registry while
+ * the row stays (R2). No delta → no settings write (idempotent, AC-1).
+ * Compute → write → commit registry: a failed write throws and leaves the
+ * registry unchanged (retry-safe).
+ *
+ * @module dsh-llm-fallbacks/seeds
+ */
+import { type FallbackStrategy, type FallbacksConfig, type FallbacksConfigLogger, type FallbacksRoles } from './config.ts';
+/** A seed declaration from a companion plugin (spec §9.1). */
+export interface SeedDeclaration {
+    id: string;
+    persona: string;
+}
+/**
+ * Why one declared id was skipped (spec §9.1). Per-id skip + warn, never
+ * coercion — valid siblings in the same batch still apply (AC-5).
+ */
+export type SeedSkipReason = 'invalid-id' | 'reserved-id' | 'duplicate-in-batch';
+/**
+ * A loud, non-destructive conflict (AC-2): never silently duplicated or
+ * merged.
+ */
+export interface SeedConflict {
+    id: string;
+    /** Existing row persona differs from the seed default — operator override retained, never overwritten. */
+    kind: 'persona-source';
+}
+/** Structured result of one `declare()` (spec §9.1) — the readable status channel. */
+export interface SeedDeclareOutcome {
+    applied: string[];
+    skipped: Array<{
+        id: string;
+        reason: SeedSkipReason;
+    }>;
+    conflicts: SeedConflict[];
+}
+/** Effective role readback entry (spec §9.1) — `chain`/`fallback` passthrough (R4). */
+export interface EffectiveRole {
+    /** The config row id (raw declared form). */
+    id: string;
+    /** Effective row persona. */
+    persona: string;
+    /** Passthrough — never touched by seeds (R4). */
+    chain?: string[];
+    /** Passthrough — never touched by seeds (R4). */
+    fallback?: FallbackStrategy;
+    /** Id is in the live declaration set (trimmed row-id match). */
+    seeded: boolean;
+    /** `seeded` && row persona !== current seed default. */
+    personaOverridden: boolean;
+    /** Present iff seeded. */
+    seedPersona?: string;
+}
+/** Service readback (b): effective taxonomy with seed annotations. */
+export interface EffectiveRolesReadback {
+    roles: EffectiveRole[];
+}
+export type SeedRevertFailReason = 'not-seeded' | 'row-absent' | 'settings-unavailable';
+export interface SeedRevertOutcome {
+    reverted: boolean;
+    /** Restored current seed default — present iff reverted. */
+    persona?: string;
+    reason?: SeedRevertFailReason;
+}
+/** Gateway wire entry (card badge state, spec §9.4). */
+export interface SeedsWireStatus {
+    id: string;
+    overridden: boolean;
+}
+/**
+ * The narrow IO seam this module writes through — keeps `src/seeds.ts`
+ * free of `@deepseek-ai/*` value imports (bundle purity gate).
+ */
+export interface SeedsIo {
+    /** Fresh composed config read (the same source the gateway reads). */
+    read(): FallbacksConfig;
+    /** Persist a full `{ list, rules }` to the settings user layer. */
+    writeRoles(roles: FallbacksRoles): Promise<void>;
+}
+/**
+ * In-memory per-apply seed manager (spec §9.2): declare / readback /
+ * revert over the operator config through a `SeedsIo` seam. Created in
+ * `apply()` (per-apply, no module-level global) with a structured logger;
+ * warn messages carry the `llm-fallbacks: seeds:` prefix (spec §9.7).
+ */
+export declare class FallbacksSeedManager {
+    private readonly logger;
+    private registry;
+    constructor(logger: FallbacksConfigLogger);
+    /**
+     * Declare seeds with replacement semantics — the batch is the
+     * companion's FULL current declaration set; ids omitted from the batch
+     * drop out of the registry while their rows remain (R2).
+     *
+     * Per-id validation AS DECLARED (spec §9.3): non-string / pattern miss /
+     * reserved `inherit` / duplicate-in-batch → skip + warn; valid siblings
+     * still apply (AC-5). Materializes per spec §9.2, writes only when the
+     * computed `{ list, rules }` differs from the current composed roles
+     * (idempotent, AC-1), and commits the registry only after a successful
+     * write (compute → write → commit; retry-safe).
+     */
+    declare(seeds: readonly SeedDeclaration[], io: SeedsIo): Promise<SeedDeclareOutcome>;
+    /**
+     * Readback (b) — sync, derived: every config row annotated with
+     * `seeded` / `personaOverridden` / `seedPersona` (trimmed row-id
+     * membership in the live declaration set; persona inequality). Nothing
+     * override-shaped is stored, so a config round-trip cannot orphan state.
+     */
+    effectiveRoles(io: SeedsIo): EffectiveRolesReadback;
+    /** Card badge state (spec §9.4): seeded rows, with the override flag. */
+    wireStatus(io: SeedsIo): SeedsWireStatus[];
+    /**
+     * Revert one id to the CURRENT declared seed default (AC-3). Writes
+     * persona only — the row is otherwise copied verbatim (R4). Ids absent
+     * from the registry (`not-seeded`) or with a deleted row (`row-absent`)
+     * return a non-reverted outcome without throwing; a failed settings
+     * write propagates loudly (spec §9.1).
+     */
+    revert(id: string, io: SeedsIo): Promise<SeedRevertOutcome>;
+    private warnSkip;
+}

package/package.json

@@ -5,7 +5,7 @@
     "dsh",
     "dsh-plugin"
   ],
-  "version": "0.1.4",
+  "version": "0.1.5",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",