@linxin666/dsh-client-ui-task-board 0.1.14 → 0.1.16

package/src/client/settings-form.ts

@@ -1,10 +1,11 @@
+// Generated by scripts/sync-shared.mjs from shared/client/settings/settings-form.ts. Do not edit this copy; edit the shared source and run "node scripts/sync-shared.mjs".
 /**
  * Staged form model behind the plugin settings card. A card stages what the
  * user types and writes it only when they save — the settings write is a
  * durable, revision-fenced document mutation, so staging keeps what is on
- * screen exactly what a save would store. Mirrors the official
- * ui-plugin-config card-store pattern in a self-contained slice: this
- * package must not depend on a sibling UI package.
+ * screen exactly what a save would store. Family-shared slice inlined into
+ * each plugin's client bundle; mirrors the official ui-plugin-config
+ * card-store pattern.
  */
 
 import type { SettingsScope, SettingsScopeSnapshot, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
@@ -19,6 +20,14 @@ export type FieldWrite =
 export interface FieldSpec {
   /** Field name inside the namespace section. */
   field: string
+  /**
+   * Whether the Host treats this field as a secret and redacts its value from
+   * the read-back (role('secret') in the section schema). Redacted secrets are
+   * never compared against the draft on save; the field lands when the scope
+   * reports the write succeeded (its secret-set marker under the bridge), so
+   * a successful secret save is not misreported as failed.
+   */
+  secret?: boolean
   /** Render a stored value as draft text; the empty string when the section carries none. */
   format: (value: unknown) => string
   /**
@@ -60,6 +69,12 @@ export interface CardShell {
   saving: boolean
   /** Whether the last save did not land as staged; cleared by the next edit or save. */
   failed: boolean
+  /**
+   * The rejection code/message the Host returned for the last failed save,
+   * surfaced next to the generic failure text. Undefined while no save has
+   * failed (or the failure carried no server reason).
+   */
+  failedReason?: string
 }
 
 /** The write actions the card's slot entry injects. */
@@ -86,12 +101,63 @@ interface StagedEdit {
 interface PlannedWrite {
   /** Field this entry writes. */
   field: string
+  /** The durable write this entry performs, described for a batched scope. */
+  op: BatchedWrite
   /** Perform the write and report whether the Host holds the staged value afterwards. */
   run: (() => Promise<boolean>) | undefined
 }
 
-/** A whole-number field. An empty draft clears the field; any other draft that is not a finite number blocks the save. */
-export function numberField(field: string): FieldSpec {
+/** One durable write a batched settings scope performs. */
+export interface BatchedWrite {
+  /** Field this entry writes. */
+  field: string
+  /** set stores a value; unset drops the leaf. */
+  op: 'set' | 'unset'
+  /** Value for op set (absent for unset). */
+  value?: unknown
+}
+
+/** Per-field outcome of one batched scope write. */
+export interface BatchedFieldResult {
+  /** Field this entry writes. */
+  field: string
+  /** Whether the Host accepted this field's write (per the read-back view). */
+  landed: boolean
+}
+
+/**
+ * Result of a batched scope write. The bridge scope posts every planned write
+ * in one /mutate so the Host validate hook judges baseURL+model together; a
+ * batched refusal fails the whole save rather than per-field.
+ */
+export interface BatchResult {
+  /** Whether the whole mutate was accepted. */
+  ok: boolean
+  /** Per-field success, in the request order (always present when ok). */
+  fields: BatchedFieldResult[]
+  /** Host rejection code (mutate refused). */
+  code?: string
+  /** Host rejection message (mutate refused). */
+  message?: string
+}
+
+/** The optional batch surface the bridge scope adds over the SettingsScope contract. */
+interface BatchedSettingsScope {
+  /** Write every operation in one scope mutation, reporting per-field success. */
+  mutate: (writes: BatchedWrite[]) => Promise<BatchResult>
+}
+
+/** Constraints a numeric field's accepted drafts must satisfy, mirroring the host schema. */
+export interface NumberConstraints {
+  /** The accepted value must be a whole number. */
+  integer?: boolean
+  /** The accepted value must be at least this. */
+  min?: number
+}
+
+/** A whole- or decimal-number field. An empty draft clears the field; any other draft that is not a finite number within the constraints blocks the save. */
+export function numberField(field: string, constraints: NumberConstraints = {}): FieldSpec {
+  const { integer = false, min } = constraints
   return {
     field,
     format: value => typeof value === 'number' ? String(value) : '',
@@ -99,7 +165,10 @@ export function numberField(field: string): FieldSpec {
       const trimmed = text.trim()
       if (trimmed === '') return { kind: 'clear' }
       const parsed = Number(trimmed)
-      return Number.isFinite(parsed) ? { kind: 'set', value: parsed } : undefined
+      if (!Number.isFinite(parsed)) return undefined
+      if (integer && !Number.isInteger(parsed)) return undefined
+      if (min !== undefined && parsed < min) return undefined
+      return { kind: 'set', value: parsed }
     },
   }
 }
@@ -116,19 +185,43 @@ export function textField(field: string): FieldSpec {
   }
 }
 
+/**
+ * A free-text field the Host treats as a secret and redacts from the read-back
+ * (role('secret') in the section schema). The card still edits it like text,
+ * but a save never compares the redacted value back and relies on the scope
+ * reporting the write landed.
+ */
+export function secretField(field: string): FieldSpec {
+  return { ...textField(field), secret: true }
+}
+
 /** A boolean field, edited through true/false draft text. */
 export function booleanField(field: string): FieldSpec {
   return {
     field,
     format: value => typeof value === 'boolean' ? String(value) : '',
     parse: (text) => {
-      if (text === 'true') return { kind: 'set', value: true }
-      if (text === 'false') return { kind: 'set', value: false }
+      const trimmed = text.trim()
+      if (trimmed === '') return { kind: 'clear' }
+      if (trimmed === 'true') return { kind: 'set', value: true }
+      if (trimmed === 'false') return { kind: 'set', value: false }
       return undefined
     },
   }
 }
 
+/** An enumerated string field; only the listed choices are accepted. An empty draft clears the field. */
+export function choiceField(field: string, choices: readonly string[]): FieldSpec {
+  return {
+    field,
+    format: value => typeof value === 'string' && choices.includes(value) ? value : '',
+    parse: (text) => {
+      if (text === '') return { kind: 'clear' }
+      return choices.includes(text) ? { kind: 'set', value: text } : undefined
+    },
+  }
+}
+
 /**
  * Stages one card's edits over one settings namespace and writes them on save.
  *
@@ -143,6 +236,7 @@ export class CardForm<T> {
   private readonly listeners = new Set<() => void>()
   private saving = false
   private failed = false
+  private failedReason: string | undefined
 
   /** @param scope - the bound settings scope for this card's namespace. */
   constructor(
@@ -172,6 +266,7 @@ export class CardForm<T> {
       invalid: plan.some(item => item.run === undefined),
       saving: this.saving,
       failed: this.failed,
+      ...this.failedReason === undefined ? {} : { failedReason: this.failedReason },
     }
   }
 
@@ -202,6 +297,7 @@ export class CardForm<T> {
         if (this.staged.size === 0 && !this.failed) return
         this.staged.clear()
         this.failed = false
+        this.failedReason = undefined
         this.publish()
       },
     }
@@ -209,25 +305,57 @@ export class CardForm<T> {
 
   /**
    * Write every staged edit, then re-seed from what the Host accepted.
+   *
+   * When the scope carries the optional batch surface (the dsh-web-ui
+   * bridge scope), every planned write rides one mutation so cross-field
+   * validate hooks (baseURL+model) judge the batch as a unit instead of
+   * deadlocking on per-field writes. Otherwise the per-field loop runs.
+   * A field lands only when the Host reports it held the staged value; a
+   * landed field's draft is dropped, a failed one stays staged for the user.
    * @returns settlement after every write and the read-back.
    */
   async save(): Promise<void> {
     const plan = this.plan()
-    const writes = plan.flatMap(item => item.run === undefined ? [] : [item.run])
-    if (plan.length === 0 || this.saving || writes.length !== plan.length) return
+    const valid = plan.filter(item => item.run !== undefined)
+    if (plan.length === 0 || this.saving || valid.length !== plan.length) return
+    const plannedWrites = valid.map(item => item.op)
+    // Snapshot the fields this save writes, so edits staged while it is in
+    // flight survive: only the staged keys this save actually wrote are cleared.
+    const fields = new Set(plan.map(item => item.field))
     this.saving = true
     this.failed = false
+    this.failedReason = undefined
     this.publish()
-    let landed = true
-    for (const write of writes) {
-      landed = await write() && landed
+    const landed = new Set<string>()
+    const batch = this.batchedScope()
+    if (batch !== undefined) {
+      const result = await batch.mutate(plannedWrites)
+      if (result.ok) {
+        for (const field of result.fields) {
+          if (field.landed) landed.add(field.field)
+        }
+      } else {
+        this.failedReason = result.message
+      }
+    } else {
+      for (const item of valid) {
+        if (await item.run!()) landed.add(item.field)
+      }
+    }
+    for (const field of fields) {
+      if (landed.has(field)) this.staged.delete(field)
     }
-    if (landed) this.staged.clear()
     this.saving = false
-    this.failed = !landed
+    this.failed = landed.size !== fields.size
     this.publish()
   }
 
+  /** The scope's batch surface when it supports one; undefined conservatively otherwise. */
+  private batchedScope(): BatchedSettingsScope | undefined {
+    const candidate = this.scope as unknown as BatchedSettingsScope | undefined
+    return typeof candidate?.mutate === 'function' ? candidate : undefined
+  }
+
   /**
    * Every staged edit a save would write. An entry whose draft is not a value
    * its field accepts carries no write: the form is still dirty, and the save
@@ -240,14 +368,14 @@ export class CardForm<T> {
     for (const [field, staged] of this.staged) {
       const spec = this.specOf(field)
       if (staged.clear) {
-        if (this.stored(field)) plan.push({ field, run: () => this.clear(field) })
+        if (this.stored(field)) plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) })
         continue
       }
       if (staged.text === spec.format(this.sectionValue(field))) continue
       const write = spec.parse(staged.text)
-      if (write === undefined) plan.push({ field, run: undefined })
-      else if (write.kind === 'clear') plan.push({ field, run: () => this.clear(field) })
-      else plan.push({ field, run: () => this.store(field, write.value) })
+      if (write === undefined) plan.push({ field, op: { field, op: 'unset' }, run: undefined })
+      else if (write.kind === 'clear') plan.push({ field, op: { field, op: 'unset' }, run: () => this.clear(field) })
+      else plan.push({ field, op: { field, op: 'set', value: write.value }, run: () => this.store(field, write.value) })
     }
     return plan
   }
@@ -259,12 +387,18 @@ export class CardForm<T> {
 
   private async store(field: string, value: unknown): Promise<boolean> {
     await this.scope.set(field, value)
+    // A redacted secret never appears in the user layer read-back; judging it
+    // by value would misreport a successful secret save as failed. The bridge
+    // reports secret writes through its secret-set markers (batch path); on
+    // the per-field path the scope resolved, so the write is landed.
+    if (this.specOf(field).secret) return true
     return this.userLayer()?.[field] === value
   }
 
   private stage(field: string, edit: StagedEdit): void {
     this.staged.set(field, edit)
     this.failed = false
+    this.failedReason = undefined
     this.publish()
   }
 

package/src/core/controller.ts

@@ -7,14 +7,22 @@
  * navigates to a session (the sessions-list `current` selection changes).
  * Framework-free (structural runtime faces) so the whole orchestration is
  * unit-testable with fakes.
+ *
+ * The per use-case domain transitions (create/update/delete/schedule) live in
+ * dedicated modules under core/use-cases and are applied here; the controller
+ * owns only the orchestration seam (state, persistence, notify, execution,
+ * navigation, reconciliation).
  */
 import { ExecutionService, type ExecutionEvent } from './execution.ts'
-import { isValidCron, nextRunAtMs } from './schedule.ts'
 import type { TaskStore } from './store.ts'
 import {
-  createTask, settleExecution, startExecution, withSchedule, withStatus,
+  settleExecution, startExecution, withStatus,
   type NewTaskInput, type TaskRecord, type TaskStatus,
 } from './tasks.ts'
+import { applyCreateTask } from './use-cases/task-create.ts'
+import { applyDeleteTask } from './use-cases/task-delete.ts'
+import { applyScheduleNextRun as applyScheduleRollForward, applySetSchedule } from './use-cases/task-schedule.ts'
+import { applyUpdateTask } from './use-cases/task-update.ts'
 
 /** The sessions face the controller needs for navigation awareness. */
 export interface SessionsControllerFace {
@@ -168,21 +176,18 @@ export class BoardController {
     this.notify()
   }
 
-  // --- task mutations ---------------------------------------------------------
+  // --- task mutations (use-case transitions in core/use-cases) -----------------
 
   createTask(input: NewTaskInput): TaskRecord | undefined {
-    const title = input.title.trim()
-    if (title === '') return undefined
-    const task = createTask(input, this.now(), this.uuid())
-    this.tasks = [...this.tasks, task]
+    const { task, tasks } = applyCreateTask(this.tasks, input, this.now(), this.uuid())
+    if (task === undefined) return undefined
+    this.tasks = [...tasks]
     this.persistAndNotify()
     return task
   }
 
   updateTask(id: string, patch: Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt'>>): void {
-    this.tasks = this.tasks.map(task => task.id === id
-      ? { ...task, ...patch, updatedAt: this.now() }
-      : task)
+    this.tasks = [...applyUpdateTask(this.tasks, id, patch, this.now())]
     this.persistAndNotify()
   }
 
@@ -192,8 +197,9 @@ export class BoardController {
   }
 
   deleteTask(id: string): void {
-    this.tasks = this.tasks.filter(task => task.id !== id)
-    if (this.selectedTaskId === id) this.selectedTaskId = undefined
+    const { tasks, selectionCleared } = applyDeleteTask(this.tasks, this.selectedTaskId, id)
+    this.tasks = [...tasks]
+    if (selectionCleared) this.selectedTaskId = undefined
     this.persistAndNotify()
   }
 
@@ -203,21 +209,15 @@ export class BoardController {
    * Update a task's schedule rule. A blank or invalid cron expression is
    * rejected (returns false, state untouched). When the rule ends up enabled
    * the next run instant is computed immediately; a disabled rule carries no
-   * next-run instant.
+   * next-run instant. Delegates the domain transition to the schedule use case.
    * @param id - the task to schedule.
    * @param patch - fields to change (absent fields keep their current value).
    * @returns true when applied, false when rejected (invalid cron / unknown task).
    */
   setSchedule(id: string, patch: { enabled?: boolean; cron?: string }): boolean {
-    const task = this.tasks.find(candidate => candidate.id === id)
-    if (task === undefined) return false
-    const current = task.schedule
-    const cron = (patch.cron ?? current?.cron ?? '').trim()
-    if (cron === '' || !isValidCron(cron)) return false
-    const enabled = patch.enabled ?? current?.enabled ?? false
-    const nextRunAt = enabled ? nextRunAtMs(cron, this.now()) : undefined
-    this.tasks = this.tasks.map(candidate =>
-      candidate.id === id ? withSchedule(candidate, { enabled, cron, nextRunAt }, this.now()) : candidate)
+    const { tasks, applied } = applySetSchedule(this.tasks, id, patch, this.now())
+    if (!applied) return false
+    this.tasks = [...tasks]
     this.persistAndNotify()
     return true
   }
@@ -228,10 +228,8 @@ export class BoardController {
    * schedule rule (it was deleted mid-tick, for example).
    */
   applyScheduleNextRun(id: string, nextRunAt: number | undefined, lastTriggeredAt: number | undefined): void {
-    this.tasks = this.tasks.map(task =>
-      task.id === id && task.schedule !== undefined
-        ? withSchedule(task, { nextRunAt, lastTriggeredAt }, this.now())
-        : task)
+    const next = applyScheduleRollForward(this.tasks, id, nextRunAt, lastTriggeredAt, this.now())
+    this.tasks = [...next]
     this.persistAndNotify()
   }
 
@@ -392,3 +390,4 @@ function attachSessionId(
       execution.id === executionId ? { ...execution, sessionId } : execution),
   }
 }
+

package/src/core/scheduler.ts

@@ -9,6 +9,12 @@
  * a task still running at its due instant is skipped by the controller's
  * runTask guard and simply waits for the next cron match.
  *
+ * The ticker is controlled: `start` arms a single interval guarded by an
+ * idempotence check (a second start while running is a no-op, so wiring can
+ * never leak a duplicate timer), and `stop`/`dispose` clear the timer and
+ * drop the environment listeners. The board unmount path calls stop/dispose,
+ * so no interval or listener outlives the board.
+ *
  * Framework-free: all runtime access flows through the injected deps
  * (structural faces), so tests drive ticks directly without timers.
  */
@@ -47,27 +53,54 @@ export interface SchedulerDeps {
  */
 export class SchedulerService {
   private timer: ReturnType<typeof setInterval> | undefined
+  private environmentListener: (() => void) | undefined
   private disposed = false
+  private started = false
 
   /** @param deps - tasks/clock/trigger/apply faces (see {@link SchedulerDeps}). */
   constructor(private readonly deps: SchedulerDeps) {}
 
-  /** Start ticking: one immediate check (catch-up after reload) + the interval. */
+  /**
+   * Start ticking: one immediate check (catch-up after reload) + the interval.
+   * Single-instance: a second start while already armed is a no-op, so a
+   * re-entrant mount can never stack a duplicate timer.
+   */
   start(): void {
     if (this.disposed) return
+    if (this.started) return
+    this.started = true
     // Immediate catch-up tick: schedules whose due instant passed while the
     // tab was closed are triggered as soon as the runtime is ready.
     this.tick()
     this.timer = setInterval(() => { this.tick() }, this.deps.tickMs ?? 60_000)
-    this.deps.environment?.addEventListener('visibilitychange', this.onVisibility)
+    if (this.deps.environment !== undefined) {
+      this.environmentListener = () => { this.tick() }
+      this.deps.environment.addEventListener('visibilitychange', this.environmentListener)
+    }
+  }
+
+  /**
+   * Stop ticking and drop listeners (idempotent). Preferred shutdown verb for
+   * callers that treat the scheduler as a controlled ticker; `dispose` is an
+   * alias.
+   */
+  stop(): void {
+    this.dispose()
   }
 
   /** Stop ticking and drop listeners (idempotent). */
   dispose(): void {
+    if (this.disposed && this.timer === undefined && this.environmentListener === undefined) return
     this.disposed = true
-    if (this.timer !== undefined) clearInterval(this.timer)
-    this.timer = undefined
-    this.deps.environment?.removeEventListener('visibilitychange', this.onVisibility)
+    this.started = false
+    if (this.timer !== undefined) {
+      clearInterval(this.timer)
+      this.timer = undefined
+    }
+    if (this.environmentListener !== undefined && this.deps.environment !== undefined) {
+      this.deps.environment.removeEventListener('visibilitychange', this.environmentListener)
+      this.environmentListener = undefined
+    }
   }
 
   /**
@@ -99,6 +132,5 @@ export class SchedulerService {
       if (accepted) this.deps.applySchedule(task.id, next, now)
     }
   }
-
-  private readonly onVisibility = (): void => { this.tick() }
 }
+

package/src/core/use-cases/task-create.ts

@@ -0,0 +1,33 @@
+/**
+ * Create-task use case: mint a new task from user input, rejecting a blank
+ * title. Pure ledger transition (no persistence or notify — the controller
+ * orchestrates those), so it is unit-testable without any runtime face.
+ */
+import { createTask, type NewTaskInput, type TaskRecord } from '../tasks.ts'
+
+/** Result of a create transition: the new task (when accepted) + the next ledger. */
+export interface CreateTaskResult {
+  /** The minted task, or undefined when the input was rejected (blank title). */
+  task: TaskRecord | undefined
+  /** The next ledger; identical reference when rejected. */
+  tasks: readonly TaskRecord[]
+}
+
+/**
+ * Apply a create against the current ledger. Returns the new task and the
+ * appended ledger, or the unchanged ledger when the title is blank.
+ * @param tasks - current ledger.
+ * @param input - raw user input (title/description/prompt).
+ * @param now - clock instant (ms epoch).
+ * @param id - minted task id.
+ */
+export function applyCreateTask(
+  tasks: readonly TaskRecord[],
+  input: NewTaskInput,
+  now: number,
+  id: string,
+): CreateTaskResult {
+  if (input.title.trim() === '') return { task: undefined, tasks }
+  const task = createTask(input, now, id)
+  return { task, tasks: [...tasks, task] }
+}

package/src/core/use-cases/task-delete.ts

@@ -0,0 +1,33 @@
+/**
+ * Delete-task use case: drop a task from the ledger and clear the selection
+ * when it pointed at the removed task. Pure ledger transition (no persistence
+ * or notify — the controller orchestrates those).
+ */
+import type { TaskRecord } from '../tasks.ts'
+
+/** Result of a delete transition. */
+export interface DeleteTaskResult {
+  /** The next ledger (the removed task absent). */
+  tasks: readonly TaskRecord[]
+  /** Whether the previous selection referenced the removed task. */
+  selectionCleared: boolean
+}
+
+/**
+ * Apply a delete across the ledger. The selection (a task id) is cleared when
+ * it matches the removed task, so the UI never lingers on a vanished detail.
+ * @param tasks - current ledger.
+ * @param selectedTaskId - the currently selected task id (may be undefined).
+ * @param id - the task to remove.
+ */
+export function applyDeleteTask(
+  tasks: readonly TaskRecord[],
+  selectedTaskId: string | undefined,
+  id: string,
+): DeleteTaskResult {
+  const next = tasks.filter(task => task.id !== id)
+  return {
+    tasks: next,
+    selectionCleared: selectedTaskId === id,
+  }
+}

package/src/core/use-cases/task-schedule.ts

@@ -0,0 +1,74 @@
+/**
+ * Schedule use case: arm/disarm a task's cron rule and roll a rule forward.
+ * Pure ledger transitions (no persistence or notify — the controller
+ * orchestrates those). Validation and next-run computation live here, sharing
+ * the core cron parser (schedule.ts) and the withSchedule transition.
+ */
+import { isValidCron, nextRunAtMs } from '../schedule.ts'
+import { withSchedule, type TaskRecord } from '../tasks.ts'
+
+/** Fields the schedule use case may change on a rule. */
+export interface SetSchedulePatch {
+  enabled?: boolean
+  cron?: string
+}
+
+/** Result of arming/disarming a rule. */
+export interface SetScheduleResult {
+  /** The next ledger; unchanged reference when rejected. */
+  tasks: readonly TaskRecord[]
+  /** Whether the rule was applied (false on unknown task / invalid cron). */
+  applied: boolean
+}
+
+/**
+ * Set a task's schedule rule. A blank or invalid cron is rejected (state
+ * untouched); an enabled rule computes the next run instant immediately, a
+ * disabled or invalid one carries no next-run instant.
+ * @param tasks - current ledger.
+ * @param id - the task to schedule.
+ * @param patch - rule fields to change (absent fields keep their current value).
+ * @param now - clock instant (ms epoch).
+ */
+export function applySetSchedule(
+  tasks: readonly TaskRecord[],
+  id: string,
+  patch: SetSchedulePatch,
+  now: number,
+): SetScheduleResult {
+  const task = tasks.find(candidate => candidate.id === id)
+  if (task === undefined) return { tasks, applied: false }
+  const current = task.schedule
+  const cron = (patch.cron ?? current?.cron ?? '').trim()
+  if (cron === '' || !isValidCron(cron)) return { tasks, applied: false }
+  const enabled = patch.enabled ?? current?.enabled ?? false
+  const nextRunAt = enabled ? nextRunAtMs(cron, now) : undefined
+  return {
+    tasks: tasks.map(candidate =>
+      candidate.id === id ? withSchedule(candidate, { enabled, cron, nextRunAt }, now) : candidate),
+    applied: true,
+  }
+}
+
+/**
+ * Roll a task's schedule rule forward (scheduler callback): persist the next
+ * due instant and the trigger instant. No-op for tasks without a rule (deleted
+ * mid-tick, for example).
+ * @param tasks - current ledger.
+ * @param id - the task to roll forward.
+ * @param nextRunAt - next due instant (may be undefined to clear).
+ * @param lastTriggeredAt - the trigger instant of this run.
+ * @param now - clock instant (ms epoch).
+ */
+export function applyScheduleNextRun(
+  tasks: readonly TaskRecord[],
+  id: string,
+  nextRunAt: number | undefined,
+  lastTriggeredAt: number | undefined,
+  now: number,
+): readonly TaskRecord[] {
+  return tasks.map(task =>
+    task.id === id && task.schedule !== undefined
+      ? withSchedule(task, { nextRunAt, lastTriggeredAt }, now)
+      : task)
+}

package/src/core/use-cases/task-update.ts

@@ -0,0 +1,26 @@
+/**
+ * Update-task use case: apply an editable-field patch (title/description/
+ * prompt) with a fresh updatedAt. Pure ledger transition (no persistence or
+ * notify — the controller orchestrates those).
+ */
+import type { TaskRecord } from '../tasks.ts'
+
+/** Editable fields on a task (the update patch surface). */
+export type TaskUpdatePatch = Partial<Pick<TaskRecord, 'title' | 'description' | 'prompt'>>
+
+/**
+ * Apply an update across the ledger. Tasks that do not match the id are left
+ * untouched; the matched task receives the patch plus a fresh updatedAt.
+ * @param tasks - current ledger.
+ * @param id - the task to update.
+ * @param patch - editable-field changes.
+ * @param now - clock instant (ms epoch).
+ */
+export function applyUpdateTask(
+  tasks: readonly TaskRecord[],
+  id: string,
+  patch: TaskUpdatePatch,
+  now: number,
+): readonly TaskRecord[] {
+  return tasks.map(task => task.id === id ? { ...task, ...patch, updatedAt: now } : task)
+}