dsh-llm-fallbacks 0.7.0 → 0.8.0

package/dist/config.d.ts

@@ -4,32 +4,27 @@
  * module must stay free of `@deepseek-ai/*` value imports so the client
  * bundle never reaches schemastery).
  *
- * Two-block config model (plan fallbacks-role-config-model): block 1
- * `rootChain` — the root agent's single fallback chain (empty = no
- * degradation) — plus block 2 declared role entities: `roles.list`
- * (id/persona/prompt?/permissions?/chain?/fallback) and
- * `roles.rules` enum references into the declared ids (or the built-in
- * `'inherit'` role). The legacy `chains` / `roles.default` keys are gone
- * from the schema and type (zero residual, migration table excepted); the
- * runtime consumes the new shape directly and flags surviving legacy keys
- * at startup via `detectLegacyKeys` (see `src/index.ts` apply()).
+ * Named virtual chains (config v2, plan named-virtual-chains): N named
+ * chains each selectable as `FallbacksChain/<chain id>`, carrying their own
+ * `entries` (默认降级链 + 链尾) and `timeSlots`. Declared roles keep identity
+ * (`id`/`persona`/`prompt?`/`permissions?`) plus an OPTIONAL `chain`
+ * POINTER — a manually specified chain id (「指定降级链」), never an auto
+ * mode: absent/empty = NOT SPECIFIED, the plugin does not intervene and the
+ * child inherits the delegating agent's route. The v1 two-block model
+ * (`rootChain` + per-role inline chains + `roles.rules`) is deleted; the
+ * runtime consumes the v2 shape directly and flags surviving v1 keys at
+ * startup via `detectLegacyKeys` (warn-only migration — no auto-write).
  *
- * Spec §4 is authoritative for field names and default values — notably
+ * Spec §1 is authoritative for field names and default values — notably
  * `triggerCodes` defaults to dsh's stable failure codes `['AUTH', 'QUOTA',
- * 'RATE_LIMIT']` (there is no `QUOTA_EXCEEDED` code in dsh), and an
- * unconfigured install (empty `rootChain`, no time slots, empty roles) is a
- * no-op pass-through exactly like an uninstalled plugin (AC-8 —
- * {@link isFallbackActive}). There is NO config-level `enabled` switch
- * (plan fallbacks-web-ux-alignment T2): the Plugins-page row toggle is the
- * master switch (row disable = fiber destroy), and the runtime gates re-key
- * to content presence. A stored profile still carrying the removed
- * `enabled:` key loads cleanly — the gateway tolerates and strips it (the
- * advisor LEGACY_KEYS mechanism), it is never read and never re-persisted.
+ * 'RATE_LIMIT']`. An unconfigured install (empty `chains`) is a no-op
+ * pass-through exactly like an uninstalled plugin — there is NO config-level
+ * `enabled` switch: the Plugins-page row toggle is the master switch and the
+ * runtime gates re-key to `isFallbackActive` (`chains.length > 0`). Nothing
+ * pre-creates a default chain: empty `chains` is the ONLY first-run state.
  *
  * This module is pure logic: it must not import any `@deepseek-ai/*` package
- * (types included) — `FallbacksConfig` is the plugin's own type. Task 3
- * registers the schemastery schema (see `./schema.ts`) with
- * `installSettingsSection` under the `fallbacks` settings namespace.
+ * (types included) — `FallbacksConfig` is the plugin's own type.
  *
  * @module dsh-llm-fallbacks/config
  */
@@ -38,31 +33,31 @@ import type { SlotRowConfig } from './time-slots.ts';
 export type RecoveryPolicy = 'timer' | 'half-open';
 /** How a cooled-down model comes back (spec §4). */
 export type RevertPolicy = 'cooldown-expiry' | 'never';
-/** A single role rule: match on provider/model patterns (spec §3). */
-export interface FallbacksRoleRule {
-    /**
-     * Legacy persisted wire field (PR #62 feedback): rules are subagent-only,
-     * so this constraint is IGNORED at match time — root requests never
-     * match rules. Kept in the type/schema so pre-feedback `settings.yaml`
-     * files that carry `origin` still parse, validate, and save unchanged.
-     */
-    origin?: 'root' | 'subagent';
-    provider?: string;
-    model?: string;
-    role: string;
-}
+/** Chain id format (v2): case-sensitive, uppercase allowed so the migrated
+ * default id is exactly `Auto`. Deliberately NOT {@link ROLE_ID_PATTERN},
+ * which keeps governing role ids. */
+export declare const CHAIN_ID_PATTERN: RegExp;
 /**
- * Chain-append strategy of a declared role entity: `inherit-root` (the
- * default) runs the role's own chain and then appends `rootChain`;
- * `none` uses only the role's own chain.
+ * One named virtual chain (v2). `id` doubles as the picker model id —
+ * renaming it would orphan every saved selection, so only `label` is
+ * editable in the UI. The LAST `entries` element is the 链尾: exactly one
+ * official model. The FIRST matching `timeSlots` row REPLACES `entries`.
  */
-export type FallbackStrategy = 'inherit-root' | 'none';
+export interface NamedChain {
+    id: string;
+    /** Settings tab title + picker display prefix (display-only). */
+    label: string;
+    /** 默认降级链 + 链尾. */
+    entries: string[];
+    /** 分时 rows scoped to this chain; first match replaces {@link entries}. */
+    timeSlots?: SlotRowConfig[];
+}
 /**
- * A declared role entity (plan fallbacks-role-config-model Task 1).
+ * A declared role entity (v2): identity + an optional chain POINTER.
  *
  * `prompt` / `permissions` are schema-reserved for the next iteration
- * (fallbacks-explicit-role-tool) — no consumer this round, and writing them
- * does NOT change this round's degradation behavior.
+ * — no consumer this round, and writing them does NOT change this
+ * round's degradation behavior.
  */
 export interface FallbacksRole {
     id: string;
@@ -75,21 +70,45 @@ export interface FallbacksRole {
         allow?: string[];
         deny?: string[];
     };
-    chain?: string[];
-    fallback?: FallbackStrategy;
+    /**
+     * Manually specified named chain id for children dispatched under this
+     * role (「指定降级链」) — a POINTER into `chains[]`, never a chain
+     * definition. Absent or empty ⇒ NOT SPECIFIED: the plugin does not
+     * intervene and the child inherits the delegating agent's route. The
+     * plugin never picks a chain on its own.
+     */
+    chain?: string;
 }
-/** Role grouping for fallback chains: declared entities + enum references. */
+/** Role grouping (v2): declared entities only — `rules` is deleted. */
 export interface FallbacksRoles {
     list: FallbacksRole[];
-    rules: FallbacksRoleRule[];
 }
 /**
- * The full `fallbacks` settings shape (two-block config model, verbatim
+ * One declared role as the SCHEMA may compose it: identical to
+ * {@link FallbacksRole} except that a v1 profile still carries the ARRAY form
+ * of `chain`. The schema must accept it (composition happens in cordis BEFORE
+ * `apply()`, so a rejection there kills the fiber and no migration can run);
+ * {@link migrateLegacyConfig} narrows it to the string pointer.
+ */
+export interface FallbacksRoleSource extends Omit<FallbacksRole, 'chain'> {
+    chain?: string | string[];
+}
+/**
+ * The composed settings shape produced by the schemastery `Config` — the input
+ * of {@link migrateLegacyConfig}, not the shape the runtime consumes.
+ */
+export interface FallbacksConfigSource extends Omit<FallbacksConfig, 'roles'> {
+    roles: {
+        list: FallbacksRoleSource[];
+    };
+}
+/**
+ * The full `fallbacks` settings shape (named virtual chains, verbatim
  * field names).
  */
 export interface FallbacksConfig {
     triggerCodes: string[];
-    rootChain: string[];
+    chains: NamedChain[];
     roles: FallbacksRoles;
     cooldownMs: number;
     revertPolicy: RevertPolicy;
@@ -98,21 +117,12 @@ export interface FallbacksConfig {
      * Preset-role injection switch: `'bundled'` declares the 5 preset roles
      * (spec §9.2) as seed rows on apply; `'none'` disables declaration.
      * Optional on purpose — a required field would break library consumers
-     * that construct `FallbacksConfig` literals with the existing 8 keys
-     * (additive, non-breaking). The value domain is guarded by the schema
-     * (`Config` in `src/schema.ts`), NOT by `validateFallbacksConfig`, and
-     * every resolved config carries a value via the schema default.
+     * that construct `FallbacksConfig` literals. The value domain is guarded
+     * by the schema (`Config` in `src/schema.ts`), NOT by
+     * `validateFallbacksConfig`, and every resolved config carries a value
+     * via the schema default.
      */
     presets?: 'bundled' | 'none';
-    /**
-     * Extra time-slot rows (plan fallbacks-timeslots Task 1, P5): the FIRST
-     * matching row's chain becomes the effective root chain at request time;
-     * `rootChain` (the all-day chain) is always the last row.
-     * Optional on purpose, mirroring `presets` — additive, non-breaking for
-     * library consumers. Malformed rows warn once and are skipped by the
-     * resolver; the gateway rejects them on save (Task 3).
-     */
-    timeSlots?: SlotRowConfig[];
     /**
      * Config-level timezone for slot matching (default `Asia/Shanghai`,
      * UTC+8). Not per-slot.
@@ -123,41 +133,40 @@ export interface FallbacksConfig {
      * 1): `'timer'` restores the preferred candidate when the cooldown
      * expires (today's behavior); `'half-open'` leaves the route half-open
      * for one logged probe instead. Optional on purpose, mirroring
-     * `presets` — a required field would break library consumers that
-     * construct `FallbacksConfig` literals with the existing keys
-     * (additive, non-breaking). The value domain is guarded by the schema
-     * (`Config` in `src/schema.ts`), NOT by `validateFallbacksConfig`, and
-     * every resolved config carries a value via the schema default.
+     * `presets`. The value domain is guarded by the schema, NOT by
+     * `validateFallbacksConfig`, and every resolved config carries a value
+     * via the schema default.
      */
     recovery?: RecoveryPolicy;
 }
 /**
- * Spec §4 defaults — `Config({})` must equal this (no-op install).
- * There is no `enabled` default (the key is removed — the Plugins-page row
- * toggle is the master switch): an unconfigured install (empty rootChain,
- * no time slots, empty roles) behaves exactly like an uninstalled plugin
- * (AC-3 / no-op invariant, {@link isFallbackActive}).
+ * Spec §1 defaults — `Config({})` must equal this (no-op install).
+ * Empty `chains` is the ONLY first-run state: nothing pre-creates an
+ * `Auto` chain and nothing seeds `entries` — the picker row appears only
+ * after the user creates a chain in the card. The migrated/seeded default
+ * chain (`{ id: 'Auto', label: '默认链', entries, timeSlots }`) exists only
+ * in the migration table (docs) applied by hand — warn-only migration.
  */
 export declare const defaultFallbacksConfig: FallbacksConfig;
+/** Role id format (aligned with yet-another-subagent `isValidProfileId`). */
+export declare const ROLE_ID_PATTERN: RegExp;
 /**
- * Reserved role id: legal as a rule target (`roles.rules[].role`) and as
- * the no-rule-match fallback, but FORBIDDEN in `roles.list[].id`.
+ * Reserved role id: FORBIDDEN in `roles.list[].id` (the validator's reserved
+ * warn) and in seed declarations (`seeds.ts` reserved-id skip). `rules` that
+ * could target it are deleted (v2), but the id itself stays reserved so a
+ * declared role can never shadow the "no specific role" meaning.
  */
 export declare const INHERIT_ROLE_ID = "inherit";
 /**
- * The no-op gate (AC-8), re-keyed from the removed `enabled` switch to
- * CONTENT PRESENCE (plan fallbacks-web-ux-alignment T2): the plugin
- * intervenes exactly when something is configured — a non-empty `rootChain`
- * (the all-day chain), at least one time-slot row, or at least one declared
- * role. An inactive config is a pass-through exactly like an uninstalled
- * plugin; the Plugins-page row toggle remains the master switch (row
- * disable = fiber destroy). ONE helper for every runtime gate — the former
- * `config.enabled` sites (request waterfalls, picker-row registration, TUI
- * summary, General-row badge) all read through this.
+ * The no-op gate (AC-8): the plugin intervenes exactly when at least one
+ * named chain is configured. Roles alone no longer activate (a role
+ * without a chain is pure identity). An inactive config is a pass-through
+ * exactly like an uninstalled plugin; the Plugins-page row toggle remains
+ * the master switch (row disable = fiber destroy). A non-empty chain with
+ * empty `entries` still registers the picker row (content presence) but
+ * refuses to delegate (conformance gate in the walk).
  */
 export declare function isFallbackActive(config: FallbacksConfig): boolean;
-/** Role id format (aligned with yet-another-subagent `isValidProfileId`). */
-export declare const ROLE_ID_PATTERN: RegExp;
 /**
  * Minimal logger surface {@link validateFallbacksConfig} warns through —
  * keeps this module free of `@deepseek-ai/*` imports (a cordis Logger is
@@ -168,29 +177,67 @@ 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,
- * `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). `persona` is free text and is 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).
+ * mutates). Per chain: id format (case-sensitive, {@link CHAIN_ID_PATTERN})
+ * + cross-chain uniqueness, tail conformance (the LAST entry must be
+ * exactly one official model — a non-conforming chain's slot rows and
+ * delegate stay inert), selector legality per entry, and the slot-row
+ * guards (unknown preset, duplicate preset per chain, preset rows carrying
+ * their own windows). Per role (after the chain loop, so the declared id
+ * set is complete): the existing id format/reserved/duplicate warns, and a
+ * non-empty `chain` pointer naming no declared chain id earns ONE warn and
+ * behaves as NOT SPECIFIED. Each violation emits one `llm-fallbacks: ...`
+ * warn — the config stays usable (warn-not-crash semantics). `persona` and
+ * `label` are free text and deliberately not validated.
  */
 export declare function validateFallbacksConfig(config: FallbacksConfig, logger: FallbacksConfigLogger): void;
 /**
- * Detect legacy (two-block-era) leftovers in a config SOURCE — the composed
- * object `source()` returns, or a raw settings document. Recognizes the
- * removed `chains` key, the removed always-mode retry cap and dispatch
- * role-auto-match keys (`alwaysModeRetryCap` / `roleAutoMatch` — direction
- * C, virtual-chain-only fallback), the removed `roles.default` field, the
- * removed role-entity fields `roles.list[].label` / `roles.list[].description`
- * (renamed to `persona`), and `roles.rules[].role` values that reference no
- * declared `roles.list` id and are not the built-in `'inherit'`. Returns
- * descriptive key/role names; the gateway attaches them as `get().legacyKeys`
- * so the client can show a migration banner (spec §9 — the source is read
- * directly because schemastery retains unknown keys, verified plan Task 1
- * Step 1).
+ * Detect legacy config leftovers in a config SOURCE — the composed object
+ * `source()` returns, or a raw settings document. Two generations:
+ *
+ * - Older removals: `alwaysModeRetryCap`, `roleAutoMatch` (direction C),
+ *   `roles.default`, and the renamed role-entity fields
+ *   `roles.list[].label` / `roles.list[].description`.
+ * - v1 two-block keys (named-virtual-chains): `rootChain`, top-level
+ *   `timeSlots`, `roles.rules`, `roles.list[].fallback`, and the v1 ARRAY
+ *   form of `roles.list[].chain` (an array where v2 declares a string —
+ *   stripped rather than coerced).
+ *
+ * Returns descriptive key names; the gateway attaches them as
+ * `get().legacyKeys` so the client can show a migration banner. Warn-only:
+ * no legacy value is ever read or re-persisted.
  */
 export declare function detectLegacyKeys(source: Record<string, unknown>): string[];
+/**
+ * The chain a v1 `rootChain` migrates into (plan fallbacks-v1-auto-migration):
+ * the id is stable so an already-selected `FallbacksChain/Auto` route keeps
+ * resolving, and the label is display-only.
+ */
+export declare const MIGRATED_CHAIN_ID = "Auto";
+/** Display label of {@link MIGRATED_CHAIN_ID}. */
+export declare const MIGRATED_CHAIN_LABEL = "\u9ED8\u8BA4\u94FE";
+/**
+ * Upgrade a config SOURCE to the v2 named-chain shape — in memory, at every
+ * read. Pure, total, idempotent: a v2 config comes back unchanged, a v1 one is
+ * converted, and any malformed shape degrades to the defaults instead of
+ * throwing (the banner keeps reporting the raw leftovers, so honesty survives
+ * the coercion).
+ *
+ * Conversion rules (plan §Goal):
+ * 1. v1 `rootChain` + top-level `timeSlots` become chain #0
+ *    (`{ id: 'Auto', label: '默认链', entries, timeSlots }`), so the picker
+ *    route the user already selected keeps working.
+ * 2. `roles.list[]` survive as identity rows (`id` / `persona` / reserved
+ *    `prompt` / `permissions`); a v1 ARRAY `chain` is dropped (NOT SPECIFIED —
+ *    the card's 指定降级链 select takes over) and `fallback` is dropped;
+ *    `roles.rules` / `roles.default` / `enabled` never reach the output.
+ * 3. A config that already carries a non-empty `chains` array keeps it and only
+ *    loses the v1 leftovers. An EMPTY `chains` alongside a v1 `rootChain` is a
+ *    profile that never had v2 content, so it migrates (otherwise the user's
+ *    chain would silently vanish).
+ *
+ * No file is rewritten here — the next explicit save persists the v2 shape.
+ * @param source - the composed config (schema defaults → plugin row → user
+ *   layer) or any raw document.
+ * @returns a complete {@link FallbacksConfig}; never the input object itself.
+ */
+export declare function migrateLegacyConfig(source: unknown): FallbacksConfig;

package/dist/gateway.d.ts

@@ -66,7 +66,7 @@
  * @module dsh-llm-fallbacks/gateway
  */
 import type { Context } from '@deepseek-ai/cordis';
-import { type SettingsNamespace } from '@deepseek-ai/dsh-settings';
+import SettingsForms, { type SettingsNamespace } from '@deepseek-ai/dsh-settings';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 import type { TypertContribution } from '@deepseek-ai/dsh-typert-registry';
 import type { FallbacksConfig } from './config';
@@ -91,63 +91,6 @@ export declare const FALLBACKS_SETTINGS_NAMESPACE: SettingsNamespace;
  * reference `apply()` reads — no separate registration step.
  */
 export declare const FALLBACKS_PROFILE_ENTRY = "llm-fallbacks";
-/** One exact child LLM route on the additive `subagentPolicy` wire field (T5). */
-export type SubagentPolicyRoute = {
-    provider: string;
-    model: string;
-};
-/** Settings namespace of the host's subagent-model-selection policy. */
-export declare const SUBAGENT_POLICY_SETTINGS_NS = "subagent-model-selection-settings";
-/**
- * Additive `/api/fallbacks/get` host-policy snapshot (spec D4 / T5).
- * Omitted only when the snapshot is unwired (3-arg constructor) so older
- * clients and gateway unit tests keep a byte-identical `{ config,
- * legacyKeys, seeds }` payload. A wired snapshot always emits the field —
- * `{ state: 'disabled' }` included — so a write after an enabled get cannot
- * keep-last an allowlist. Never written through `set`/`reset`.
- */
-export type SubagentPolicyWire = {
-    state: 'enabled';
-    allowedModels: SubagentPolicyRoute[];
-    head?: {
-        route: SubagentPolicyRoute;
-        source: 'authorized' | 'injected';
-    };
-    blockedAttempt?: {
-        at: number;
-        route: SubagentPolicyRoute;
-        reason: string;
-    };
-} | {
-    state: 'disabled';
-} | {
-    state: 'unprovable';
-};
-/**
- * Live host-policy snapshot the gateway projects onto the wire. Built in
- * `apply()` from the SAME T1 reader the override paths use — no second
- * policy source. Optional: the 3-arg constructor (gateway unit tests)
- * omits the field entirely.
- */
-export type SubagentPolicySnapshotFn = () => {
-    policy: {
-        state: 'disabled';
-    } | {
-        state: 'enabled';
-        allowedModels: readonly SubagentPolicyRoute[];
-    } | {
-        state: 'unprovable';
-    };
-    head?: {
-        route: SubagentPolicyRoute;
-        source: 'authorized' | 'injected';
-    };
-    blockedAttempt?: {
-        at: number;
-        route: SubagentPolicyRoute;
-        reason: string;
-    };
-};
 /**
  * The live configuration source for the gateway (guide §7 — the same bridge
  * shape the runtime reads through). `source()` returns the live composed
@@ -157,7 +100,15 @@ export type SubagentPolicySnapshotFn = () => {
  * `onChange` fan-out was removed in the QC fix wave — nothing subscribed).
  */
 export interface FallbacksSettingsBridge {
+    /** The EFFECTIVE config the runtime reads (v1 already upgraded in memory). */
     source(): FallbacksConfig;
+    /**
+     * The STORED view, before the in-memory upgrade. Legacy detection reads it,
+     * so the migration banner keeps reporting keys the effective config no
+     * longer carries (plan fallbacks-v1-auto-migration). Optional: a caller
+     * without one is assumed to hold the raw shape itself.
+     */
+    rawSource?(): FallbacksConfig;
 }
 /** Patch shape accepted by `fallbacks.set` — any subset of the config keys. */
 export type FallbacksConfigPatch = Partial<FallbacksConfig>;
@@ -170,13 +121,6 @@ export interface FallbacksReadResult {
     config: FallbacksConfig;
     legacyKeys: string[];
     seeds: SeedsWireStatus[];
-    /**
-     * Host subagent-model-selection policy (spec D4). Additive — old readers
-     * ignore it; omitted only when no snapshot is wired. A wired snapshot
-     * always carries the field (`disabled` included) so keep-last cannot
-     * retain an allowlist after policy-off.
-     */
-    subagentPolicy?: SubagentPolicyWire;
 }
 /** The `fallbacks/revert-seed` response — a read result plus the revert outcome. */
 export interface FallbacksRevertResult extends FallbacksReadResult {
@@ -200,12 +144,6 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
     private readonly seeds;
     /** The live settings service once the optional inject child activates. */
     private settings;
-    /**
-     * Optional host-policy snapshot (T5). When omitted the additive
-     * `subagentPolicy` field is absent on every read — the 3-arg constructor
-     * used by gateway unit tests stays byte-identical to the pre-T5 payload.
-     */
-    private readonly subagentPolicy;
     /**
      * @param ctx - owning context (the plugin fiber's ctx inside `apply`).
      * @param bridge - the same `FallbacksSettingsBridge` the runtime reads, so
@@ -213,22 +151,21 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      * @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.
-     * @param subagentPolicy - live host-policy snapshot from `apply()`; omit
-     *   to leave the additive field off the wire.
      */
-    constructor(ctx: Context, bridge: FallbacksSettingsBridge, seeds: FallbacksSeedManager, subagentPolicy?: SubagentPolicySnapshotFn);
+    constructor(ctx: Context, bridge: FallbacksSettingsBridge, seeds: FallbacksSeedManager);
     /**
      * Read the current composed config (schema defaults → entry base → profile
      * patch). No hard-gate resolver (ADR-2): the raw composed config is
      * the wire value. The removed `enabled` key never crosses the wire (the
      * read whitelist drops it — the snapshot-strip half of LEGACY_KEYS).
-     * @returns the wire-normalized composed config plus `legacyKeys` — legacy
-     *   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) — plus the additive
-     *   `seeds` badge state (spec §9.4, legacyKeys precedent — old clients
-     *   ignore it).
+     * @returns the wire-normalized composed config plus `legacyKeys` — every
+     *   v1 field detected on the composed source (`rootChain`, top-level
+     *   `timeSlots`, `roles.rules`, `roles.default`, `roles.list[].fallback`,
+     *   the v1 ARRAY form of `roles.list[].chain`, plus the older
+     *   `alwaysModeRetryCap` / `roleAutoMatch` / renamed role fields —
+     *   schemastery retains them), so the client can show a migration banner
+     *   (incremental field — old clients ignore it) — plus the additive `seeds`
+     *   badge state (legacyKeys precedent — old clients ignore it).
      */
     get(): FallbacksReadResult;
     /**
@@ -277,22 +214,6 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      *   write channel is unavailable (KD-G5).
      */
     revertSeed(id: string): Promise<FallbacksRevertResult>;
-    /**
-     * Merge the CURRENT host allowlist with the exact routes configured in this
-     * plugin's chains (every `roles.list[].chain` entry plus `rootChain`), plus
-     * the virtual `FallbacksChain/Auto` route. De-duplicated by exact
-     * provider+model with first-seen order kept (the current allowlist first).
-     * Wildcard (`provider/*`) and unparseable entries are skipped — never
-     * expanded into routes. This is the only allowlist write face; it runs
-     * exclusively from the explicit card button (never silently) and writes
-     * ONLY `allowedModels` — never `enabled`.
-     * @returns the post-write read result (the fresh `subagentPolicy` snapshot
-     *   reflects the new allowlist).
-     * @throws when no live policy snapshot is wired, the policy is not proven
-     *   enabled (`disabled` / `unprovable`), or no settings service is composed
-     *   (KD-G5: no allowlist write without a proven-enabled policy).
-     */
-    syncAllowlist(): Promise<FallbacksReadResult>;
     /**
      * Read the live composed config and normalize it to the typertGateway JSON
      * wire boundary. Containment (guide §10): a malformed stored patch section
@@ -318,26 +239,59 @@ export declare class FallbacksConfigGateway extends TypertRemoteService {
      */
     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 plugin's profile-entry section — both
-     * arrays always computed from a fresh composed read, so the write stays
-     * correct under the settings merge's 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).
+     * The io seam the seed manager writes through (spec §9.1): `read` walks the
+     * same live bridge source the gateway reads; `writeRoles` persists the
+     * declared roles as `{ list }` — the v2 shape, whose rows are `{ id,
+     * persona, chain? }` — computed from a fresh composed read, so the write
+     * stays correct under the settings merge's replace-whole-array semantics
+     * and every operator-specified `chain` pointer survives verbatim. It goes
+     * through {@link writeSection}, so a seed write also drops any stored v1
+     * field. 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;
+    /**
+     * Write a CLEANED patch and, in the same save, remove v1 fields the
+     * persisted section may still carry. `settings.update` is merge-only, so a
+     * stored `rootChain` / top-level `timeSlots` / `roles.rules` /
+     * `roles.list[].fallback` would otherwise survive every v2 save; the
+     * removals ride `settings.mutate`'s `unset` path ops, which touch only the
+     * named fields (unrelated configuration, foreign keys and redacted secrets
+     * are preserved — a wholesale `replace` rebuilt from a descriptor would not
+     * be).
+     * @param patch - already stripped of v1 fields and null values.
+     */
+    private writeSection;
 }
+/**
+ * Persist a CLEANED patch and, in the same operation, remove the v1 fields the
+ * ACTIVE PROFILE's persisted section still holds. `settings.update` is
+ * merge-only, so a stored `rootChain` / top-level `timeSlots` / `roles.rules` /
+ * `roles.list[].fallback` would otherwise survive every v2 save; the removals
+ * ride `settings.mutate`'s path ops, which touch only the named fields
+ * (unrelated configuration, foreign keys and redacted secrets are preserved —
+ * a wholesale `replace` rebuilt from a descriptor would delete them).
+ *
+ * Exported because the plugin has TWO write entry points — the gateway
+ * (`set` / `writeRoles`) and the apply-level `SeedsIo` (`declareSeeds`,
+ * `revertSeededPersona`, the bundled preset self-declaration) — and the same
+ * logical operation must clean the same way through both.
+ * @param settings - the live settings service.
+ * @param patch - a patch; v1 fields are stripped here, callers need not.
+ * @param ns - profile entry id (defaults to the plugin's own).
+ */
+export declare function writeFallbacksSection(settings: SettingsForms, patch: Record<string, unknown>, ns?: string): Promise<void>;
 /**
  * Reject a patch the `Config` schema cannot express: non-object input, unknown
  * top-level keys (schemastery merges them silently — the settings service
  * would accept them), and schema type violations — plus the Task 3 semantic
  * guards the permissive schema deliberately does not carry: nested `roles`
- * keys, `timeSlots` row shapes (unknown preset ids, duplicate presets, preset
- * rows carrying windows, non-`HH:mm` custom bounds, out-of-range days, empty
- * chains), and the all-day `rootChain` head conformance.
+ * keys, `chains[]` row shape (id pattern, case-sensitive uniqueness, label),
+ * per-chain `timeSlots` row shapes (unknown preset ids, duplicate presets,
+ * preset rows carrying windows, non-`HH:mm` custom bounds, out-of-range days,
+ * empty chains), and each chain's non-empty `entries` tail conformance.
  *
  * Exported (plan fallbacks-tui-settings Task 1): the TUI settings section's
  * JSON-field `parse` mirrors the gateway save rules through this single