dsh-llm-fallbacks 0.4.4 → 0.5.1

package/dist/role-notice.d.ts

@@ -0,0 +1,156 @@
+/**
+ * In-session role notice row (plan role-based-subagent-adoption Task 3).
+ *
+ * The child of a role-carrying dispatch gets ONE durable transcript row naming
+ * the role it was dispatched as, so the role is visible where the work is read
+ * — inside the child's own session — without reaching for live plugin state.
+ *
+ * Channel: an `agent/pre-step` listener that appends EXACTLY ONE message to the
+ * decision the loop is about to enter (`decision.messages`), which the loop
+ * then commits durably on the step's first attempt
+ * (`agent-loop/src/agent.ts:373-378` — `if (firstAttempt) for (const message of
+ * decision.messages)` the loop commits each message to the session log as a
+ * `'user/message'`). The listener is registered with `{ prepend: true }` (the
+ * `modelSwitchNotice` precedent in
+ * `core/agent/src/model-selection.ts:108-125`), so it is the OUTERMOST layer:
+ * `await next()` yields the FINAL decision every other listener shaped. The
+ * contract is EXACTLY ONE row, not its position: a plugin that registers its
+ * own `{ prepend: true }` `agent/pre-step` listener AFTER this one sits outside
+ * it and may append after the notice, and the loop commits the decision's
+ * messages in order — so the row is appended to whatever the inner listeners
+ * shaped, not guaranteed to be the last one.
+ *
+ * NOT `agent.inject()`: that queue is documented as lossy — "It may miss a
+ * request whose pre-step already claimed its batch. Cancellation or disposal
+ * may discard pending context." (`core/agent/src/runtime-types.ts:231-241`), and
+ * with `wakeup: false` an idle child is never woken to receive it. The pre-step
+ * decision has neither failure mode.
+ *
+ * Session-write contract (plan Global Constraints, hard): the row is a
+ * `user/message` built with `createUserMessage` and the sanctioned plugin source
+ * `{ kind: 'plugin', plugin: 'dsh-llm-fallbacks', form: 'notice', summary: … }`.
+ * `plugin` is a member of the FROZEN released source-kind set the V2→V3 edge
+ * classifies (`dsh-session-format-v2-to-v3/lib/index.js:14-30`: 15 kinds,
+ * includes `plugin`); a bespoke kind would write fine and then refuse at the
+ * next frozen edge with `cannot safely transform unclassified message source`
+ * (`:125`). NO custom session event type, NO `ignorable` marker — a mount-only
+ * plugin cannot publish either (`.mstar/projects/_default/references/
+ * subagent-role-badge-visible/explore-role-seam-report.md` §Q3). The guard test
+ * in `tests/role-notice.spec.ts` pins that membership against a checked-in
+ * mirror of the set.
+ *
+ * Once per child SESSION: the emitter consumes the seam's per-child record
+ * marker (`firstNoticePending`) AND a per-agent `emitted` set (mirroring the
+ * existing `dispatchInjected` pattern), both written only AFTER the row is built
+ * — so a throwing producer degrades without consuming the child's one notice.
+ * Never for a root agent, never for `inherit`/unresolved (those never get a
+ * record), never twice across steps or within-step retries.
+ *
+ * CF-6 — the emitted marker is SESSION-stable and bounded. `Agent.id` IS the
+ * child session id, and a continuable child's durable session outlives its
+ * activation, so the caller (`src/index.ts`) keeps this marker across
+ * `agent/disposed` and clears it only when the plugin itself is disposed; that
+ * is what makes the documented "exactly one notice row per child session" hold
+ * across a dispose + re-activate resume. Because it is never per-activation
+ * cleared it must be bounded: {@link markNoticeEmitted} evicts the oldest entry
+ * once {@link NOTICE_EMITTED_LIMIT} sessions are remembered (a child evicted
+ * that way can at worst be announced a second time, and the projection fold is
+ * last-wins, so no wrong role is ever produced).
+ *
+ * Degrade-never-crash: any throw in the path is contained with ONE debug line
+ * and the decision is returned UNCHANGED — a step is never broken, and no
+ * partial row is ever published.
+ *
+ * @module dsh-llm-fallbacks/role-notice
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type UserMessage } from '@deepseek-ai/dsh-llm';
+import type { SubagentSeamRecord } from './subagents-seam.ts';
+/**
+ * The `plugin` field of every notice this plugin writes. Stable: the durable
+ * source's provenance label is read from it (`ui-conversation`
+ * `context-provenance.ts` — "the plugin id, or the bare source kind").
+ */
+export declare const ROLE_NOTICE_PLUGIN = "dsh-llm-fallbacks";
+/**
+ * The message source KIND the notice rides. `plugin` is the sanctioned kind for
+ * a plugin-authored notice and a member of the frozen released set (see the
+ * module header); the value is exported so the guard test asserts on the exact
+ * literal the emitter uses.
+ */
+export declare const ROLE_NOTICE_SOURCE_KIND = "plugin";
+/** Suffix appended when the role declares a persona that was NOT delivered. */
+export declare const ROLE_NOTICE_PERSONA_SKIPPED_SUFFIX = " (persona not applied)";
+/**
+ * How many child sessions whose notice was already emitted stay remembered
+ * (CF-6). The marker is session-stable — kept across `agent/disposed` so a
+ * re-activated continuable child is not announced twice — so it needs a bound:
+ * past this many sessions the oldest entry is evicted (worst case: a later
+ * re-activation of that evicted child writes a second identical row; the
+ * projection fold is last-wins, so the pill never names a wrong role).
+ */
+export declare const NOTICE_EMITTED_LIMIT = 256;
+/**
+ * Mark one child session as announced, evicting the oldest remembered session
+ * once {@link NOTICE_EMITTED_LIMIT} is reached (insertion-ordered `Set`
+ * semantics: the oldest entry is the first value). A session already marked
+ * keeps its position — its marker is only ever written once.
+ */
+export declare function markNoticeEmitted(emitted: Set<string>, childSessionId: string): void;
+/** One notice-message producer: role id + whether the declared persona was skipped. */
+export type RoleNoticeBuilder = (role: string, personaNotApplied: boolean) => UserMessage;
+/**
+ * Build the ONE role notice row (pure): `[role: <id>]`, with
+ * ` (persona not applied)` appended when the role declares a persona that Task
+ * 2's capability gate declined to deliver. The summary keeps `role: <id>` either
+ * way — it is the collapsed row's one-line account, and the durable role string
+ * must live there as well as in the content.
+ *
+ * @param role - the DECLARED RAW role id resolved at the dispatch seam.
+ * @param personaNotApplied - `true` only when a declared persona was skipped.
+ */
+export declare function buildRoleNotice(role: string, personaNotApplied: boolean): UserMessage;
+/** Options for {@link installRoleNotice}. */
+export interface RoleNoticeOptions {
+    /**
+     * The dispatch seam's per-child records, keyed by child SESSION id (which IS
+     * `Agent.id`). Read at each pre-step — never captured — so a record written by
+     * a dispatch that races the child's first step is still seen.
+     */
+    records: Map<string, SubagentSeamRecord>;
+    /**
+     * Per-agent marker of children whose notice was already emitted (mirrors the
+     * runtime's `dispatchInjected`): the in-memory half of the once-per-child
+     * guarantee, independent of the record's `firstNoticePending` (which a record
+     * rewrite preserves deliberately) and of the loop's retry bookkeeping.
+     *
+     * SESSION-stable and bounded (CF-6): the caller keeps it across
+     * `agent/disposed` so a re-activated child is never announced twice, and
+     * {@link markNoticeEmitted} bounds it. ROOT-shared across the fibers applied
+     * over one root (CF-5), so a second fiber's emitter cannot announce a child
+     * the first already announced.
+     */
+    emitted: Set<string>;
+    /**
+     * Message producer. Defaults to {@link buildRoleNotice}; the only reason to
+     * replace it is to pin the contained-degrade path (a throwing producer must
+     * publish no row and must NOT consume the child's one notice).
+     */
+    buildNotice?: RoleNoticeBuilder;
+    /** Contained debug sink (at most ONE line per contained degrade). */
+    debug?: (message: string) => void;
+}
+/**
+ * Register the `agent/pre-step` notice emitter on `ctx`; returns its disposer
+ * (the owning fiber's teardown registers it, exactly like the seam's other
+ * listeners).
+ *
+ * Emission order per pre-step (cheapest first, all read-only until the emit):
+ * `next()` → reject/abort → empty decision → `origin === 'subagent'` → already
+ * emitted → pending record. The empty-decision guard is NOT cosmetic: the loop
+ * skips a step whose admitted messages are empty (`phase.step === 0 &&
+ * decision.messages.length === 0` → turn completed, no model call), so a notice
+ * pushed into an empty decision would turn a no-op step into a model call whose
+ * only input is our row.
+ */
+export declare function installRoleNotice(ctx: Context, options: RoleNoticeOptions): () => void;

package/dist/role-projection-key.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The session-projection contract of the subagent role pill (plan
+ * role-based-subagent-adoption Task 3b): the ONE key the host fold
+ * (`./role-projection.ts`) publishes and the session-header badge reads.
+ *
+ * PURE module — no `@deepseek-ai/*` import, no host-only dependency — because
+ * BOTH halves import it: the host through the seam's install point, the client
+ * through `SubagentRoleBadge`. Splitting the key (and the value guard) out of
+ * the host module is what keeps the client half free of the fold's host
+ * imports, and a single shared literal is what keeps the two halves from
+ * drifting into a silent "no pill".
+ *
+ * @module dsh-llm-fallbacks/role-projection-key
+ */
+/**
+ * The projection key the role pill reads (`useProjection(ROLE_PROJECTION_KEY)`).
+ * Lower-camel like the host's own session-scoped keys (`modelSelection`,
+ * `sessionListMetadata`); the `fallbacks` prefix keeps a third-party key
+ * unambiguous inside the shared `SessionProjectionMap`.
+ */
+export declare const ROLE_PROJECTION_KEY = "fallbacksSubagentRole";
+/**
+ * The client-visible value of the role projection: the DECLARED RAW role id the
+ * child was dispatched as (padding included — it is the id the settings
+ * document declares), or `null` while the child's log carries no role notice
+ * row (`./role-notice.ts`).
+ *
+ * A role id, NOT a record: the route is a SEPARATE host projection
+ * (`modelSelection`), because the notice row is written once at the child's
+ * first step while the route it ends up on can change afterwards.
+ */
+export type RoleProjectionValue = string | null;
+/**
+ * Read a projection value defensively (degrade-never-crash): only a non-blank
+ * string is a role. `undefined` — the key is not registered on this host, or no
+ * baseline/frame has carried it yet — and every foreign value read as "no
+ * role", so the pill collapses to nothing instead of naming something wrong.
+ *
+ * @param value - the raw `useProjection('<key>')` value.
+ */
+export declare function readRoleProjectionValue(value: unknown): string | undefined;

package/dist/role-projection.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Durable role visibility for the session-header badge (plan
+ * role-based-subagent-adoption Task 3b) — ONE host-side session projection unit
+ * folding the role out of the child's OWN durable log.
+ *
+ * Data source = Task 3's notice row, the plugin's single write primitive: the
+ * fold reads the child's committed `user/message` events, keeps the one whose
+ * provenance is ours (`source.kind === 'plugin'` + `source.plugin ===
+ * ROLE_NOTICE_PLUGIN`), and parses the role out of its **content text**
+ * (`[role: <id>]`). No second write path, no new event type, no plugin-owned
+ * store: the projection is a pure READ of the log, and the host's projection
+ * cache checkpoints every registered unit at session creation, `turn/end` and
+ * disposal — so a settled child (served as an unpublished observation whose
+ * `projections` ride the follow opening snapshot) and a post-restart view both
+ * work with nothing of ours on disk.
+ *
+ * NEVER `source.summary`: summaries are truncated at
+ * `CONTEXT_SUMMARY_MAX_CHARS = 120` (`@deepseek-ai/dsh-llm` `message.ts`,
+ * applied by `boundContextSummary`) while a role id has no length bound in the
+ * settings schema — a long id would be CUT there and the pill would name a role
+ * that does not exist. The content blocks are unbounded, so the content text is
+ * the only correct source; the row's provenance is what makes the pre-filter
+ * cheap.
+ *
+ * Mount-only + STRUCTURAL: the registry and the unit contract are consumed as
+ * the local structural views below and this module value-imports no host seam,
+ * so the host calls INTO us. The declared
+ * `@deepseek-ai/dsh-session-projection` peerDependency (Task 3b L2 review M-2)
+ * serves the in-process Step-0 spec, which builds the REAL registry — being the
+ * real registry is the whole point of that proof — not a runtime import here
+ * (the badge reads its seat structurally for the same reason).
+ * The runtime shape relied on — `register({ key, stateSchema, init, apply,
+ * wire: { viewSchema, view }, stateVersion })` → unregister disposer — is the
+ * documented `ProjectionDefinition` contract of
+ * `@deepseek-ai/dsh-session-projection@0.1.5-rc.1`
+ * (`lib/types/index.d.ts:38-80,150-152`); only `.parse` is ever called on the
+ * schemas (`lib/index.js:255,305,433`).
+ *
+ * @module dsh-llm-fallbacks/role-projection
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import { type RoleProjectionValue } from './role-projection-key.ts';
+/**
+ * The `.parse` face the registry uses on a definition's `stateSchema` /
+ * `wire.viewSchema` (a structural stand-in for the peer's `ZodType`, so this
+ * module needs no zod import and no new peer).
+ */
+interface ProjectionValueSchema<T> {
+    parse(value: unknown): T;
+}
+/**
+ * One registered projection unit, as this plugin declares it (the consumed
+ * subset of the host's `ProjectionDefinition`): `init` and `apply` are PURE and
+ * SYNCHRONOUS, `state` is plain JSON (the persisted-checkpoint precondition),
+ * and `wire` publishes the client-visible value.
+ */
+export interface RoleProjectionUnit {
+    readonly key: string;
+    readonly stateSchema: ProjectionValueSchema<RoleProjectionState | null>;
+    init(header: unknown, inheritedEventCount: number): RoleProjectionState | null;
+    apply(state: RoleProjectionState | null, event: SessionEvent): RoleProjectionState | null;
+    readonly stateVersion: number;
+    readonly wire: {
+        readonly viewSchema: ProjectionValueSchema<RoleProjectionValue>;
+        view(state: RoleProjectionState | null): RoleProjectionValue;
+    };
+}
+/**
+ * The host fold state: the fork boundary the fold was initialized with, plus the
+ * resolved role once an OWN notice row has landed (`role` absent until then).
+ * An OBJECT, not a bare string, because the registry's publication rule is
+ * reference identity (`Object.is`) — the fold must be able to prove it left the
+ * state untouched, and that proof is only meaningful for a value the fold could
+ * otherwise re-allocate.
+ *
+ * `inheritedEventCount` is part of the state, not a closure constant: the
+ * registry hands `init` the exact fork-inherited prefix length and then folds
+ * the WHOLE log into `apply`, so the boundary has to survive into every `apply`
+ * call (and into a persisted checkpoint row) for the fold to skip an ancestor's
+ * events.
+ */
+export interface RoleProjectionState {
+    /**
+     * The exact fork-inherited prefix length `init` was handed: events with
+     * `seq < inheritedEventCount` belong to the ANCESTOR the child was seeded
+     * from, never to the child.
+     */
+    readonly inheritedEventCount: number;
+    /** The DECLARED RAW role id, verbatim (padding included); absent until then. */
+    readonly role?: string;
+}
+/**
+ * The registry face this plugin uses (`ctx.sessionProjections`): the
+ * client-visible `register` overload plus the read faces the in-process proof
+ * reads. Structural on purpose — see the module header.
+ */
+export interface RoleProjectionRegistryView {
+    register(unit: RoleProjectionUnit): () => void;
+}
+/**
+ * The projection state/version. Bump `stateVersion` whenever the fold changes —
+ * v2 added the fork boundary (`inheritedEventCount`), so a v1 checkpoint row is
+ * NOT re-usable and must be refolded from the log.
+ */
+export declare const ROLE_PROJECTION_STATE_VERSION = 2;
+/**
+ * The ONE role projection unit (plan Task 3b).
+ *
+ * `init` records the fork boundary and nothing else (a child's own log carries
+ * no role yet), `apply` skips every event BELOW that boundary — the seeded
+ * prefix is the ANCESTOR's log, and the plan pins "child whose notice never
+ * landed: no pill, never a wrong pill" — and otherwise folds last-wins over our
+ * own notice rows, returning the SAME state reference for every event it does
+ * not use (the registry's `Object.is` rule: an unchanged reference produces zero
+ * downstream work and no client publication) — including a repeated notice with
+ * the same role, which is what makes the fold idempotent under a replay.
+ *
+ * The boundary carries into the state because the registry calls `apply` with
+ * the WHOLE log (including the fork prefix) on every rung: `buildCell`,
+ * `drive`'s late-registration fold and `restore` all fold from `init` forward.
+ * The host's own sibling unit in the same tree does exactly this
+ * (`@deepseek-ai/dsh-subagent` `subagentCatalogProjectionDefinition`:
+ * `init: (_header, inheritedEventCount) => ({ inheritedEventCount })` and
+ * `apply: … || event.seq < state.inheritedEventCount → return state`).
+ */
+export declare const roleProjectionUnit: RoleProjectionUnit;
+/** Options for {@link installRoleProjection}. */
+export interface RoleProjectionOptions {
+    /** Contained debug sink (at most ONE line per contained degrade). */
+    debug?: (message: string) => void;
+}
+/**
+ * Register {@link roleProjectionUnit} on `ctx.sessionProjections` through the
+ * same conditional-inject idiom the plugin already uses for `settings` / `llm` /
+ * `typert`: the child activates only when the registry is composed, so a
+ * composition without it keeps the key absent and the badge renders nothing
+ * (capability absence — never a dispatch failure, never a crash).
+ *
+ * Registration is an effect on the child fiber: a second apply over the same
+ * root registers the SAME key at the SAME `stateVersion`, which the registry
+ * counts (one unit, the key survives until the last holder unloads) — so this
+ * needs no dedupe of its own, and a reshaped registry that refuses the
+ * registration degrades with one contained debug line.
+ *
+ * @param ctx - the plugin fiber's context.
+ * @param options - contained debug sink.
+ * @returns the disposer that withdraws the child (and with it the key).
+ */
+export declare function installRoleProjection(ctx: Context, options?: RoleProjectionOptions): () => void;
+export {};

package/dist/role-resolution.d.ts

@@ -51,6 +51,17 @@ export interface ResolveRoleAtDispatchOptions {
     automatch?: (agent: AgentLike) => Promise<string | null>;
     /** Warning sink — the decision path injects the plugin logger. */
     warn: (message: string) => void;
+    /**
+     * The route the agent's request was actually SERVED by, when that differs
+     * from the pair recorded on the agent (the virtual `FallbacksChain/Auto`
+     * row). Rule matching accepts either, so a rule keyed on the real chain head
+     * keeps matching a child whose recorded route is the virtual pair (QC1 I-1).
+     * `undefined` for every real route.
+     */
+    servedRoute?: {
+        provider: string;
+        model: string;
+    };
 }
 /**
  * Resolve the dispatch-time role for an agent across three ordered stages

package/dist/roles.d.ts

@@ -82,4 +82,7 @@ export interface AgentLike {
  * decision path injects the cordis `logger.warn` so every plugin warning
  * flows through the plugin log namespace (qc2 F-002 / qc3 S-3).
  */
-export declare function resolveRole(agent: AgentLike, rules: FallbacksRoleRule[], roleIds: ReadonlyMap<string, string>, warn?: (message: string) => void): string;
+export declare function resolveRole(agent: AgentLike, rules: FallbacksRoleRule[], roleIds: ReadonlyMap<string, string>, warn?: (message: string) => void, servedRoute?: {
+    provider: string;
+    model: string;
+}): string;

package/dist/seeds.d.ts

@@ -11,20 +11,34 @@
  * 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, { persona, set }>` —
- *    the declared default persona plus its provenance label), declare =
- *    replacement (the batch is the companion's full current set).
+ * 2. an in-memory per-apply seed registry keyed by PRODUCER LABEL
+ *    (`bundled` | set name | `external`), each slice holding that
+ *    producer's current id → `{ persona, set }` declarations. Declare =
+ *    replacement PER PRODUCER: a declare replaces only its own slice, so
+ *    the plugin's bundled presets stay `bundled` even when a companion
+ *    merge-preserves them into its own batch (plan
+ *    seeds-source-and-persona-width, Decisions #1).
  * `seeded` / `personaOverridden` / `source` are DERIVED at read time, never
  * stored — a config round-trip cannot orphan an override (AC-3), and
  * provenance rides the in-memory registry only, so it can never churn a
  * settings write.
  *
+ * Resolution precedence (Decisions #2): `bundled` wins for any id the
+ * plugin's own preset self-declare currently declares; otherwise the most
+ * recent non-bundled producer declaring the id wins (its set name, or
+ * `external` when unnamed); no live declaration ⇒ `user`. Unnamed producers
+ * share the `external` slice (Decisions #3); `{ set }` is the remedy.
+ *
  * 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).
+ * `'persona-source'` conflict / omitted id drops from the declaring
+ * producer's slice while the row stays (R2). Tracking is driven by the
+ * id's RESOLVED effective default — `prior` = resolved before the
+ * declare, `incoming` = resolved after the candidate slice commit — so a
+ * producer that is not the resolution winner for an id it declares never
+ * rewrites the row (F-001). 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
  */
@@ -151,13 +165,22 @@ export interface SeedsIo {
  */
 export declare class FallbacksSeedManager {
     private readonly logger;
-    /** Per-apply declaration registry: declared default persona + provenance label. */
+    /**
+     * Per-producer declaration registry: producer label (`bundled` | set
+     * name | `external`) → that producer's current slice. A declare replaces
+     * only its own slice; an empty batch drops the slice.
+     */
     private registry;
+    /** Monotonic declare counter — "most recent producer" for resolution precedence. */
+    private declareSeq;
     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).
+     * Declare seeds with replacement semantics PER PRODUCER — the batch is
+     * the producer's FULL current declaration set; ids omitted from the
+     * batch drop out of that producer's slice while their rows remain (R2).
+     * Other producers' slices are untouched, so a companion merge-preserving
+     * the bundled presets into its own batch never re-labels them (Decisions
+     * #1).
      *
      * `options` labels the whole batch's provenance (spec §2), resolved once
      * per call: an invalid set name warns once and degrades to the unnamed
@@ -165,27 +188,46 @@ export declare class FallbacksSeedManager {
      *
      * 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).
+     * still apply (AC-5). Materializes per spec §9.2 against the id's
+     * RESOLVED effective default before/after the candidate slice commit
+     * (at-default tracking follows the resolution winner — a producer that
+     * is not the winner for an id it declares never rewrites the row),
+     * writes only when the computed `{ list, rules }` differs from the
+     * current composed roles (idempotent, AC-1), and commits the slice only
+     * after a successful write (compute → write → commit; retry-safe). An
+     * empty batch drops the producer's slice.
      */
     declare(seeds: readonly SeedDeclaration[], io: SeedsIo, options?: SeedsInternalDeclareOptions): Promise<SeedDeclareOutcome>;
+    /**
+     * Resolve one id's live declaration across producer slices (spec §2,
+     * Decisions #2): the bundled preset self-declare wins for any id it
+     * currently declares; otherwise the most recent non-bundled producer
+     * declaring the id wins (its set name, or `external` when unnamed); no
+     * live declaration ⇒ `undefined` (the row reads `user`). Single place —
+     * `effectiveRoles`, `wireStatus`, and `revert` can never disagree. The
+     * optional `registry` argument resolves against a CANDIDATE registry
+     * (the declaring slice already replaced) — the same precedence, used by
+     * `declare` to compute the post-commit effective default for tracking.
+     */
+    private resolveDeclared;
     /**
      * Readback (b) — sync, derived: every config row annotated with
      * `seeded` / `personaOverridden` / `seedPersona` (trimmed row-id
      * membership in the live declaration set; persona inequality) plus the
-     * row's provenance `source` (spec §2): the declaring set's label, or
-     * `user` when no live declaration covers the row. Nothing
-     * override-shaped is stored, so a config round-trip cannot orphan state.
+     * row's provenance `source` (spec §2): the winning producer's label per
+     * `resolveDeclared`, or `user` when no live declaration covers the row.
+     * 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 and the provenance label. */
     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`)
+     * Revert one id to the CURRENT declared seed default (AC-3) — resolved
+     * through the same precedence as the readbacks, so a preserved bundled id
+     * reverts to the bundled persona, never a companion's copy. Writes
+     * persona only — the row is otherwise copied verbatim (R4). Ids with no
+     * live declaration (`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).
      */