dsh-plugin-effort-declare 0.1.1 → 0.1.3

package/src/client/load-drafts.ts

@@ -1,6 +1,12 @@
 /**
  * Load editable route drafts from llm.providers + the llm-pi-ai namespace.
  * Drafts come from the user layer; route protocol classification may use effective value.
+ *
+ * First paint uses `ensure()` (idle-only). Refresh never calls `ensure()`:
+ * wait until the mirror subscribe shows a namespace revision at least as new
+ * as the Host event, then `getSnapshot()`. Own mutate echoes are identified
+ * by revision (including older delayed echoes), not ignored as a generic
+ * document-updated.
  */
 import type { IApiClient, SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
 import type { SettingsDescribeFace } from '@deepseek-ai/dsh-client-ui-settings/client'
@@ -25,19 +31,115 @@ export interface LoadDraftsResult {
   error?: string
 }
 
+export type LoadDraftsMode = 'ensure' | 'snapshot'
+
+type MirrorSnapshot = ReturnType<SettingsDescribeFace['getSnapshot']>
+type MirrorDescribe = Pick<SettingsDescribeFace, 'getSnapshot' | 'subscribe'>
+
+/** Namespace revision on a describe snapshot, if that row exists. */
+export function namespaceRevision(snapshot: MirrorSnapshot, ns: string): number | undefined {
+  return snapshot.view?.namespaces.find(view => view.ns === ns)?.revision
+}
+
 /**
- * First paint: `ensure()` (reads only from idle). Never treat ensure as refresh.
- * Callers that must not apply a stale settlement compare generation themselves.
- *
- * `formats` is the live schema union only. Empty means the dropdown has no
- * writable choices (stored values stay visible via `thinkingFormatChoices`).
+ * True when `incoming` is the Host echo of a mutate this page already folded,
+ * or an older revision the snapshot has already passed. `echoed` is undefined
+ * until the first successful write.
  */
-export async function loadDrafts(
+export function isOwnDocumentEcho(echoed: number | undefined, incoming: number): boolean {
+  return echoed !== undefined && incoming <= echoed
+}
+
+/**
+ * After a preserve-dirty reload: conflicted cards get a conflict notice;
+ * live cards drop leftover conflict/error; saved notices stay; gone cards drop.
+ */
+export function foldReloadNotices<T extends { kind: string }>(
+  current: Record<string, T>,
+  args: {
+    conflicted: readonly string[]
+    conflictNotice: T
+    liveProviders: readonly string[]
+  },
+): Record<string, T> {
+  const live = new Set(args.liveProviders)
+  const conflicted = new Set(args.conflicted)
+  const next: Record<string, T> = {}
+  for (const [provider, notice] of Object.entries(current)) {
+    if (!live.has(provider)) continue
+    if (conflicted.has(provider)) continue
+    if (notice.kind === 'conflict' || notice.kind === 'error') continue
+    next[provider] = notice
+  }
+  for (const provider of args.conflicted) {
+    next[provider] = args.conflictNotice
+  }
+  return next
+}
+
+function waitUntil(
+  describe: MirrorDescribe,
+  predicate: () => boolean,
+  signal?: AbortSignal,
+): Promise<boolean> {
+  if (signal?.aborted) return Promise.resolve(false)
+  if (predicate()) return Promise.resolve(true)
+  return new Promise((resolve) => {
+    let settled = false
+    const finish = (ok: boolean) => {
+      if (settled) return
+      settled = true
+      stop()
+      signal?.removeEventListener('abort', onAbort)
+      resolve(ok)
+    }
+    const onAbort = () => { finish(false) }
+    const stop = describe.subscribe(() => {
+      if (predicate()) finish(true)
+    })
+    signal?.addEventListener('abort', onAbort)
+    if (predicate()) finish(true)
+    else if (signal?.aborted) finish(false)
+  })
+}
+
+/** Resolve when the mirror's namespace revision is at least `revision`, or abort. */
+export async function waitForNamespaceRevision(
+  describe: MirrorDescribe,
+  ns: string,
+  revision: number,
+  signal?: AbortSignal,
+): Promise<'matched' | 'aborted'> {
+  const matched = await waitUntil(
+    describe,
+    () => {
+      const current = namespaceRevision(describe.getSnapshot(), ns)
+      return current !== undefined && current >= revision
+    },
+    signal,
+  )
+  return matched ? 'matched' : 'aborted'
+}
+
+/** Resolve when the namespace revision differs from `previous`, or abort. */
+export async function waitForNamespaceRevisionChange(
+  describe: MirrorDescribe,
+  ns: string,
+  previous: number,
+  signal?: AbortSignal,
+): Promise<'changed' | 'aborted'> {
+  const changed = await waitUntil(describe, () => {
+    const current = namespaceRevision(describe.getSnapshot(), ns)
+    return current !== undefined && current !== previous
+  }, signal)
+  return changed ? 'changed' : 'aborted'
+}
+
+async function assembleDrafts(
   api: Pick<IApiClient, 'llm'>,
-  describe: Pick<SettingsDescribeFace, 'ensure' | 'getSnapshot'>,
+  describe: Pick<SettingsDescribeFace, 'getSnapshot'>,
   schema: SchemaOps,
 ): Promise<LoadDraftsResult> {
-  await describe.ensure()
   const mirrored = describe.getSnapshot()
   if (mirrored.view === undefined) {
     return { writable: false, formats: [], drafts: [], error: mirrored.error ?? undefined }
@@ -83,3 +185,17 @@ export async function loadDrafts(
   }
   return { writable: mirrored.view.writable, formats, drafts }
 }
+
+/**
+ * `ensure`: first paint / idle recovery (official ensure only reads from idle).
+ * `snapshot`: refresh after the mirror revision already moved — do not ensure.
+ */
+export async function loadDrafts(
+  api: Pick<IApiClient, 'llm'>,
+  describe: Pick<SettingsDescribeFace, 'ensure' | 'getSnapshot'>,
+  schema: SchemaOps,
+  mode: LoadDraftsMode = 'ensure',
+): Promise<LoadDraftsResult> {
+  if (mode === 'ensure') await describe.ensure()
+  return assembleDrafts(api, describe, schema)
+}

package/src/client/locales.ts

@@ -13,6 +13,7 @@ export type EffortDeclareKey =
   | 'readOnly'
   | 'save'
   | 'saving'
+  | 'saveBusy'
   | 'cancel'
   | 'saved'
   | 'conflict'
@@ -57,6 +58,7 @@ export const zh: Record<EffortDeclareKey, string> = {
   readOnly: '当前设置为只读，无法保存。',
   save: '保存',
   saving: '保存中…',
+  saveBusy: '另有路由正在保存，请稍候。',
   cancel: '取消',
   saved: '已保存。对话选择器会按新的能力声明显示 Effort 行。',
   conflict: '设置已被其他地方改过，请重新加载后再保存。',
@@ -100,6 +102,7 @@ export const en: Record<EffortDeclareKey, string> = {
   readOnly: 'Settings are read-only; saving is disabled.',
   save: 'Save',
   saving: 'Saving…',
+  saveBusy: 'Another route is saving. Wait, then save this card.',
   cancel: 'Cancel',
   saved: 'Saved. The composer Effort row follows this capability declaration.',
   conflict: 'Settings changed elsewhere. Reload, then save again.',

package/src/core/README.en.md

@@ -9,19 +9,20 @@
 
 Domain logic for the plugin: no React, no Cordis service instances. The settings page and Vitest both depend on these pure functions, so effort semantics can regress without booting DSH.
 
-Canonical level names and `thinkingFormat` values follow `@deepseek-ai/dsh-llm-pi-ai` (0.1.0-rc.8). A whitelist is pinned by tests; UI choices come only from the live schema union.
+Canonical level names and `thinkingFormat` values follow `@deepseek-ai/dsh-llm-pi-ai` (0.1.0-rc.8; 0.1.1-rc.2 uses the same level set). `thinkingFormat` is pinned to the live-schema snapshot in [`tests/fixtures/pi-ai-thinking-format-union.ts`](../../tests/fixtures/pi-ai-thinking-format-union.ts); effort keys stay a locally pinned whitelist. UI choices come only from the live schema union.
 
 ## What's in this directory
 
 | File | Role |
 | --- | --- |
 | [`catalog.ts`](./catalog.ts) | Canonical level order, `thinkingFormat` fallback list, `llm-pi-ai` / DeepSeek constants. |
-| [`efforts.ts`](./efforts.ts) | `reasoningEfforts` read/write, Off tri-state, validation (empty object / Off-only / unknown keys return an error code, never throw). |
+| [`efforts.ts`](./efforts.ts) | `reasoningEfforts` read/write, Off tri-state (value mode stores `trim()`), validation (empty object / Off-only / unknown keys return an error code, never throw). |
 | [`presets.ts`](./presets.ts) | DeepSeek, OpenAI, and on/off presets; each states all three dialect keys; spread onto existing model rows and route `compat`. |
 | [`path-ops.ts`](./path-ops.ts) | Same one-level key diff as the official Models page; `buildSaveOps` uses `settingsPath` and only submits that route’s full `models` table and dirty `compat` keys. |
-| [`drafts.ts`](./drafts.ts) | User-layer drafts, dirty aligned with pathOps, post-save revision bump, dirty merge, generation. |
+| [`drafts.ts`](./drafts.ts) | User-layer drafts, dirty aligned with pathOps, post-save revision. On refresh, latest user-layer model membership wins; unsaved `reasoningEfforts` (including a cleared key) overlay by id; `compat` is a per-key 3-way merge. Conflict only when a locally dirty field also moved in originals (revision-only bumps and sibling-card saves do not warn). |
 | [`paths.ts`](./paths.ts) | Nested reads; clones of objects and model tables (non-object rows skipped). |
 | [`filter.ts`](./filter.ts) | Which routes are editable: hand-declared `llm-pi-ai` + openai-completions; skip catalog and official DeepSeek. |
 | [`validate.ts`](./validate.ts) | Per-row `reasoningEfforts` validation. |
+| [`attribution.ts`](./attribution.ts) | Settings footer line: `version © year Stardust`. Start year is 2026; end year is the UTC year at pack time, not the user’s clock when DSH starts. |
 
 An **absent** field means default-off. Do not encode “undeclared” as `reasoningEfforts: false` — in official semantics `false` strips reasoning from a catalog model.

package/src/core/README.md

@@ -9,19 +9,20 @@
 
 本插件的领域逻辑：无 React、无 Cordis 服务实例。设置页与 Vitest 都只依赖这些纯函数，因此档位语义可以在不启动 DSH 的情况下回归。
 
-规范键名与 `thinkingFormat` 取值对齐 `@deepseek-ai/dsh-llm-pi-ai`（0.1.0-rc.8）。仓库内有测试钉白名单；UI 可选项只来自现场 schema union。
+规范键名与 `thinkingFormat` 取值对齐 `@deepseek-ai/dsh-llm-pi-ai`（0.1.0-rc.8；0.1.1-rc.2 档位集合相同）。`thinkingFormat` 由 [`tests/fixtures/pi-ai-thinking-format-union.ts`](../../tests/fixtures/pi-ai-thinking-format-union.ts) 钉现场 schema；档位键由测试钉本地白名单。UI 可选项只来自现场 schema union。
 
 ## 这个目录里有什么
 
 | 文件 | 说明 |
 | --- | --- |
 | [`catalog.ts`](./catalog.ts) | 规范档位顺序、`thinkingFormat` 回退列表、`llm-pi-ai` / DeepSeek 相关常量。 |
-| [`efforts.ts`](./efforts.ts) | `reasoningEfforts` 读写、Off 三态、校验（空对象 / 只开 Off / 未知键返回错误码，不抛异常）。 |
+| [`efforts.ts`](./efforts.ts) | `reasoningEfforts` 读写、Off 三态（value 模式写入 `trim()` 后的字符串）、校验（空对象 / 只开 Off / 未知键返回错误码，不抛异常）。 |
 | [`presets.ts`](./presets.ts) | DeepSeek、OpenAI、仅开/关三套预设；每套对三个方言键都表态；spread 到已有模型行与路由 `compat`。 |
 | [`path-ops.ts`](./path-ops.ts) | 与官方模型页相同的一层键 diff；`buildSaveOps` 使用 `settingsPath`，只提交该路由的 `models` 整表和有差异的 `compat` 键。 |
-| [`drafts.ts`](./drafts.ts) | 用户层草稿、dirty 与 pathOps 一致、保存后 revision、脏卡合并、generation。 |
+| [`drafts.ts`](./drafts.ts) | 用户层草稿、dirty 与 pathOps 一致、保存后 revision。刷新时以最新用户层模型名单为成员真理，按 id 贴回未保存的 `reasoningEfforts`（含已清除=删键）；`compat` 按键三路合并。冲突仅当本地脏字段的 originals 也变了（只 bump revision 或别的卡保存不报）。 |
 | [`paths.ts`](./paths.ts) | 嵌套读取、对象与模型表的 clone（非对象行跳过）。 |
 | [`filter.ts`](./filter.ts) | 哪些路由可编辑：手工 `llm-pi-ai` + openai-completions；排除 catalog 与官方 DeepSeek。 |
 | [`validate.ts`](./validate.ts) | 对单行 `reasoningEfforts` 调用校验。 |
+| [`attribution.ts`](./attribution.ts) | 设置页页脚：`version © 年 Stardust`。首年写死 2026，结束年由打包时的 UTC 年注入，不是用户打开 DSH 的日期。 |
 
 **缺席字段**表示默认关闭。不要把「未声明」写成 `reasoningEfforts: false`——`false` 在官方语义里是从 catalog 模型上剥掉推理。

package/src/core/attribution.ts

@@ -0,0 +1,24 @@
+/**
+ * Plugin footer attribution. Version and end-year are frozen into the client
+ * bundle at pack time; this module only formats the line.
+ */
+
+/** First publication year (LICENSE). Not the user's wall clock. */
+export const COPYRIGHT_FROM = 2026
+
+export const COPYRIGHT_HOLDER = 'Stardust'
+
+/**
+ * `0.1.2 © 2026 Stardust` or `0.1.2 © 2026–2027 Stardust`.
+ * Throws if version is empty or `to < from` — a bad stamp must not render.
+ */
+export function formatAttribution(version: string, from: number, to: number): string {
+  if (version.trim() === '') {
+    throw new Error('plugin version must be a non-empty string')
+  }
+  if (!Number.isInteger(from) || !Number.isInteger(to) || to < from) {
+    throw new Error(`invalid copyright range: ${String(from)}\u2013${String(to)}`)
+  }
+  const years = to === from ? String(from) : `${String(from)}\u2013${String(to)}`
+  return `${version} \u00a9 ${years} ${COPYRIGHT_HOLDER}`
+}

package/src/core/catalog.ts

@@ -3,9 +3,11 @@
  *
  * Levels match `@deepseek-ai/dsh-llm-pi-ai` catalog.ts `THINKING_LEVELS`.
  * Formats match `SUPPORTED_THINKING_FORMATS` in the same file (rc.8).
- * Tests pin these lists against llm-pi-ai. The settings page never offers
- * the handwritten thinkingFormat list as writable choices — only the live
- * schema union, plus a stored value that the union omitted.
+ * Tests pin these lists against a checked-in schema fixture
+ * (`tests/fixtures/pi-ai-thinking-format-union.ts`) and the local level
+ * whitelist. The settings page never offers the handwritten thinkingFormat
+ * list as writable choices — only the live schema union, plus a stored
+ * value that the union omitted.
  */
 
 /** Selectable reasoning levels, in pi-ai escalation order. */

package/src/core/drafts.ts

@@ -22,6 +22,16 @@ export interface RouteDraft {
   compatPresent: boolean
 }
 
+/** JSON-stable equality matching pathOps (key order included). */
+export function sliceEqual(left: unknown, right: unknown): boolean {
+  return JSON.stringify(left) === JSON.stringify(right)
+}
+
+/** Whether two settings slices differ. */
+export function sliceChanged(before: unknown, after: unknown): boolean {
+  return !sliceEqual(before, after)
+}
+
 /** Build a draft from the stored user subtree (never from effective `value`). */
 export function routeDraftFromUserProfile(args: {
   provider: string
@@ -89,9 +99,132 @@ export function applySaveSuccess(
   })
 }
 
+function modelRowId(row: Record<string, unknown>): string {
+  return String(row.id)
+}
+
+function indexById(rows: readonly Record<string, unknown>[]): Map<string, Record<string, unknown>> {
+  const map = new Map<string, Record<string, unknown>>()
+  for (const row of rows) {
+    const id = modelRowId(row)
+    if (!map.has(id)) map.set(id, row)
+  }
+  return map
+}
+
+function effortsPresence(row: Record<string, unknown> | undefined): { present: boolean; value: unknown } {
+  if (row === undefined || !Object.hasOwn(row, 'reasoningEfforts')) {
+    return { present: false, value: undefined }
+  }
+  return { present: true, value: row.reasoningEfforts }
+}
+
+function effortsEqual(
+  left: { present: boolean; value: unknown },
+  right: { present: boolean; value: unknown },
+): boolean {
+  if (left.present !== right.present) return false
+  if (!left.present) return true
+  return sliceEqual(left.value, right.value)
+}
+
+function overlayLocalEfforts(
+  incomingRow: Record<string, unknown>,
+  prevRow: Record<string, unknown>,
+): Record<string, unknown> {
+  const next = structuredClone(incomingRow)
+  if (Object.hasOwn(prevRow, 'reasoningEfforts')) {
+    next.reasoningEfforts = structuredClone(prevRow.reasoningEfforts)
+  } else {
+    delete next.reasoningEfforts
+  }
+  return next
+}
+
+function objectKeyChanged(
+  left: Record<string, unknown>,
+  right: Record<string, unknown>,
+  key: string,
+): boolean {
+  const leftHas = Object.hasOwn(left, key)
+  const rightHas = Object.hasOwn(right, key)
+  if (leftHas !== rightHas) return true
+  if (!leftHas) return false
+  return sliceChanged(left[key], right[key])
+}
+
+/**
+ * Membership follows the latest user-layer models list (Models page add/delete).
+ * Local unsaved `reasoningEfforts` (including a cleared key) overlay by id.
+ */
+export function mergeModelsById(args: {
+  prevModels: readonly Record<string, unknown>[]
+  prevOriginal: readonly Record<string, unknown>[]
+  incomingModels: readonly Record<string, unknown>[]
+  incomingOriginal: readonly Record<string, unknown>[]
+}): { models: Record<string, unknown>[]; conflicted: boolean } {
+  const prevById = indexById(args.prevModels)
+  const prevOrigById = indexById(args.prevOriginal)
+  const incomingOrigById = indexById(args.incomingOriginal)
+  const incomingIds = new Set(args.incomingModels.map(modelRowId))
+  let conflicted = false
+
+  const models = args.incomingModels.map((incomingRow) => {
+    const id = modelRowId(incomingRow)
+    const prevRow = prevById.get(id)
+    if (prevRow === undefined) return structuredClone(incomingRow)
+    const prevOrig = prevOrigById.get(id)
+    const localDirty = !effortsEqual(effortsPresence(prevRow), effortsPresence(prevOrig))
+    if (!localDirty) return structuredClone(incomingRow)
+    const incomingOrig = incomingOrigById.get(id)
+    if (!effortsEqual(effortsPresence(prevOrig), effortsPresence(incomingOrig))) {
+      conflicted = true
+    }
+    return overlayLocalEfforts(incomingRow, prevRow)
+  })
+
+  for (const [id, prevRow] of prevById) {
+    if (incomingIds.has(id)) continue
+    const prevOrig = prevOrigById.get(id)
+    if (effortsEqual(effortsPresence(prevRow), effortsPresence(prevOrig))) continue
+    if (!effortsEqual(effortsPresence(prevOrig), effortsPresence(incomingOrigById.get(id)))) {
+      conflicted = true
+    }
+  }
+
+  return { models, conflicted }
+}
+
 /**
- * Apply a freshly loaded table. Dirty cards keep models/compat; originals and
- * revision follow the incoming snapshot so a later save is against the new user layer.
+ * Three-way compat merge: locally changed keys stay local; everything else
+ * follows incoming. Conflict only when a locally dirty key also moved in originals.
+ */
+export function mergeCompat(args: {
+  prev: Record<string, unknown>
+  prevOriginal: Record<string, unknown>
+  incoming: Record<string, unknown>
+  incomingOriginal: Record<string, unknown>
+}): { compat: Record<string, unknown>; conflicted: boolean } {
+  if (!sliceChanged(args.prev, args.prevOriginal)) {
+    return { compat: cloneObject(args.incoming), conflicted: false }
+  }
+  const compat = cloneObject(args.incoming)
+  let conflicted = false
+  const keys = new Set([...Object.keys(args.prev), ...Object.keys(args.prevOriginal)])
+  for (const key of keys) {
+    if (!objectKeyChanged(args.prev, args.prevOriginal, key)) continue
+    if (objectKeyChanged(args.prevOriginal, args.incomingOriginal, key)) conflicted = true
+    if (Object.hasOwn(args.prev, key)) compat[key] = structuredClone(args.prev[key])
+    else delete compat[key]
+  }
+  return { compat, conflicted }
+}
+
+/**
+ * Apply a freshly loaded table. Membership and metadata follow incoming;
+ * unsaved reasoningEfforts / dirty compat keys overlay by id. Conflict only
+ * when a locally dirty field also changed in originals (revision-only bumps
+ * and sibling-card saves do not warn).
  */
 export function mergeLoadedDrafts(
   current: readonly RouteDraft[],
@@ -103,13 +236,27 @@ export function mergeLoadedDrafts(
   const drafts = incoming.map((next) => {
     const prev = currentByProvider.get(next.provider)
     if (prev === undefined || !options.preserveDirty || !draftDirty(prev)) return next
-    conflicted.push(next.provider)
+    const modelsMerge = mergeModelsById({
+      prevModels: prev.models,
+      prevOriginal: prev.originalModels,
+      incomingModels: next.models,
+      incomingOriginal: next.originalModels,
+    })
+    const compatMerge = mergeCompat({
+      prev: prev.compat,
+      prevOriginal: prev.originalCompat,
+      incoming: next.compat,
+      incomingOriginal: next.originalCompat,
+    })
+    if (modelsMerge.conflicted || compatMerge.conflicted) conflicted.push(next.provider)
     return {
-      ...prev,
+      provider: next.provider,
       displayName: next.displayName,
       settingsPath: next.settingsPath,
       revision: next.revision,
+      models: modelsMerge.models,
       originalModels: cloneModels(next.originalModels),
+      compat: compatMerge.compat,
       originalCompat: cloneObject(next.originalCompat),
       compatPresent: next.compatPresent,
     }

package/src/core/efforts.ts

@@ -26,7 +26,10 @@ export function writeOff(
   const next: ReasoningEfforts = { ...efforts }
   delete next.off
   if (mode === 'empty') next.off = null
-  else if (mode === 'value') next.off = value.trim().length > 0 ? value : 'none'
+  else if (mode === 'value') {
+    const trimmed = value.trim()
+    next.off = trimmed.length > 0 ? trimmed : 'none'
+  }
   return next
 }