@zhushanwen/pi-scheduler 0.1.0 → 0.2.0

package/src/__tests__/cron.test.ts

@@ -58,11 +58,10 @@ describe('computeNextCronRuns', () => {
 })
 
 describe('parseSchedule (cron 分支)', () => {
-  it('5 字段 cron 表达式补秒字段并附带 note', async () => {
+  it('5 字段 cron 表达式补秒字段（note 不再透传到 parseSchedule 结果）', async () => {
     const result = await parseSchedule('*/10 * * * *')
     expect(result).toEqual({
       spec: { mode: 'cron', cronExpression: '0 */10 * * * *' },
-      note: 'Auto-prepended seconds field (0)',
     })
   })
 

package/src/__tests__/format.test.ts

@@ -9,6 +9,13 @@ describe('formatSchedule', () => {
     expect(formatSchedule({ mode: 'interval', intervalMs: 3_600_000 })).toBe('every 1h')
   })
 
+  it('formats once kind as "once in X" (not misleading "every X")', () => {
+    expect(formatSchedule({ mode: 'interval', intervalMs: 300_000 }, 'once')).toBe('once in 5m')
+    expect(formatSchedule({ mode: 'interval', intervalMs: 3_600_000 }, 'once')).toBe('once in 1h')
+    // recurring/缺省保持 every
+    expect(formatSchedule({ mode: 'interval', intervalMs: 300_000 }, 'recurring')).toBe('every 5m')
+  })
+
   it('formats cron spec', () => {
     expect(formatSchedule({ mode: 'cron', cronExpression: '*/10 * * * *' })).toBe('*/10 * * * *')
   })
@@ -83,6 +90,34 @@ describe('formatDuration', () => {
     expect(formatDuration(90_000)).toBe('90s')
     expect(formatDuration(1500)).toBe('2s')
   })
+
+  // TC7 边界值：最大单位整除优先（300000 → '5m' 而非 '300s'）
+  it('prefers largest unit when ms is evenly divisible', () => {
+    expect(formatDuration(300_000)).toBe('5m')
+    expect(formatDuration(3_600_000)).toBe('1h')
+    expect(formatDuration(86_400_000)).toBe('1d')
+    expect(formatDuration(60_000)).toBe('1m')
+    expect(formatDuration(1000)).toBe('1s')
+  })
+
+  it('handles zero and negative as 0s', () => {
+    expect(formatDuration(0)).toBe('0s')
+    expect(formatDuration(-1)).toBe('0s')
+    expect(formatDuration(-86_400_000)).toBe('0s')
+  })
+
+  // TC7 修正（design-review R1）：1500000 % 60000 === 0 → '25m'（最大单位优先），
+  // 而非 design 初稿误写的 '1500s'。非整除大单位落秒用例改用 1510000。
+  it('prefers even minute when ms is multiple of 60000 (1500000 → 25m)', () => {
+    expect(formatDuration(1_500_000)).toBe('25m')
+  })
+
+  it('falls back to seconds for large non-divisible values (1510000 → 1510s)', () => {
+    // 1510000 % 60000 = 10000 ≠ 0 → 不整除 m，落秒分支
+    expect(formatDuration(1_510_000)).toBe('1510s')
+    // 1500001 % 1000 ≠ 0 → Math.round 兜底
+    expect(formatDuration(1_500_001)).toBe('1500s')
+  })
 })
 
 describe('generateTaskId', () => {

package/src/__tests__/importer.test.ts

@@ -0,0 +1,283 @@
+import * as fs from 'node:fs'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { getLegacyStorePath, importLegacyStore } from '../importer.js'
+import type { ScheduledTask } from '../types.js'
+
+// vi.mock 必须在 import 之前提升。mock 工厂替换 node:fs 命名空间，
+// importer.ts 内 `import * as fs` 拿到的就是这 4 个 vi.fn()。
+vi.mock('node:fs', () => ({
+  renameSync: vi.fn(),
+  existsSync: vi.fn(),
+  readFileSync: vi.fn(),
+  unlinkSync: vi.fn(),
+}))
+
+const cwd = '/fake/workspace'
+const storePath = getLegacyStorePath(cwd)
+const importedPath = storePath + '.imported'
+const sessionFile = '/x/sess.json'
+
+/** 构造合法旧 store 任务（参考 types.ts ScheduleSpec / TaskKind 默认值）。 */
+function makeTask(overrides: Partial<ScheduledTask> = {}): ScheduledTask {
+  return {
+    id: 'task-1',
+    name: 'test task',
+    prompt: 'do something',
+    kind: 'recurring',
+    schedule: { mode: 'interval', intervalMs: 60000 },
+    enabled: true,
+    force: false,
+    createdAt: 1000,
+    nextRunAt: 2000,
+    runCount: 0,
+    history: [],
+    ...overrides,
+  }
+}
+
+/** 构造带 code 属性的 ENOENT 错误（模拟 fs.renameSync 源文件不存在）。 */
+function enoentError(): Error & { code: string } {
+  return Object.assign(new Error('ENOENT: no such file or directory'), { code: 'ENOENT' })
+}
+
+describe('importLegacyStore', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // 默认 implementation：rename 成功、existsSync false、readFileSync 空、unlink 无副作用
+    vi.mocked(fs.renameSync).mockImplementation(() => {})
+    vi.mocked(fs.existsSync).mockReturnValue(false)
+    vi.mocked(fs.readFileSync).mockReturnValue('{}')
+    vi.mocked(fs.unlinkSync).mockImplementation(() => {})
+    // 抑制 importer 的 console.log/warn 输出（断言用 spy）
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+    vi.spyOn(console, 'warn').mockImplementation(() => {})
+  })
+
+  afterEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  // ── TC1：rename 原子单成功 + 逐任务 append upsert + 删 .imported ──
+  it('TC1: rename 成功独占 + 2 任务逐个 appendEntry upsert + 删 .imported', () => {
+    const taskA = makeTask({ id: 'aaaa', name: 'A' })
+    const taskB = makeTask({ id: 'bbbb', name: 'B' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA, taskB] }),
+    )
+    const appendEntry = vi.fn()
+    // resumed session：sessionFile 已存在（pi flushed=true，append 即时落盘）→ 立即 unlink 安全
+    vi.mocked(fs.existsSync).mockImplementation(p => p === sessionFile)
+
+    importLegacyStore(cwd, { appendEntry }, sessionFile)
+    // 1) rename 原子独占：scheduler.json → scheduler.json.imported
+    expect(fs.renameSync).toHaveBeenCalledTimes(1)
+    expect(fs.renameSync).toHaveBeenCalledWith(storePath, importedPath)
+
+    // 2) appendEntry 调 2 次，customType + op 形状正确
+    expect(appendEntry).toHaveBeenCalledTimes(2)
+    expect(appendEntry).toHaveBeenNthCalledWith(1, 'pi-scheduler:task', {
+      op: 'upsert',
+      taskId: 'aaaa',
+      ownerSessionFile: sessionFile,
+      task: expect.objectContaining({ id: 'aaaa', name: 'A' }),
+    })
+    expect(appendEntry).toHaveBeenNthCalledWith(2, 'pi-scheduler:task', {
+      op: 'upsert',
+      taskId: 'bbbb',
+      ownerSessionFile: sessionFile,
+      task: expect.objectContaining({ id: 'bbbb', name: 'B' }),
+    })
+
+    // 3) task snapshot 不含 ownerSessionFile/pending（显式剥离）
+    const firstOp = appendEntry.mock.calls[0]![1] as { task: Record<string, unknown> }
+    expect(firstOp.task).not.toHaveProperty('ownerSessionFile')
+    expect(firstOp.task).not.toHaveProperty('pending')
+
+    // 4) unlinkSync 删 .imported
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+
+    // 5) 进度日志（console.warn，项目 convention 禁 console.log）
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining(`imported 2 legacy tasks from ${importedPath}`),
+    )
+  })
+
+  // ── TC2：.imported 残留崩溃恢复幂等 ──
+  it('TC2: scheduler.json 不存在(rename ENOENT) + .imported 残留 → 读 .imported 导入 + 删 .imported', () => {
+    // 实现A：scheduler.json 不存在时 renameSync 抛 ENOENT → 走 handleImportedResidue
+    vi.mocked(fs.renameSync).mockImplementation(() => {
+      throw enoentError()
+    })
+    // .imported 存在 + resumed session（sessionFile 已存在 → 已落盘 → 立即删）
+    vi.mocked(fs.existsSync).mockImplementation(p => p === importedPath || p === sessionFile)
+    const taskA = makeTask({ id: 'cccc' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA] }),
+    )
+    const appendEntry = vi.fn()
+
+    importLegacyStore(cwd, { appendEntry }, sessionFile)
+
+    expect(appendEntry).toHaveBeenCalledTimes(1)
+    expect(appendEntry).toHaveBeenCalledWith('pi-scheduler:task', {
+      op: 'upsert',
+      taskId: 'cccc',
+      ownerSessionFile: sessionFile,
+      task: expect.objectContaining({ id: 'cccc' }),
+    })
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+  })
+
+  // ── TC3：scheduler.json 与 .imported 都不存在 → no-op ──
+  it('TC3: 双不存在（rename ENOENT + .imported 不存在）→ no-op，不抛错', () => {
+    vi.mocked(fs.renameSync).mockImplementation(() => {
+      throw enoentError()
+    })
+    vi.mocked(fs.existsSync).mockReturnValue(false) // .imported 也不存在
+    const appendEntry = vi.fn()
+
+    expect(() => importLegacyStore(cwd, { appendEntry }, sessionFile)).not.toThrow()
+    expect(appendEntry).toHaveBeenCalledTimes(0)
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+  })
+
+  // ── TC4：并发单成功者——rename 抛 ENOENT + .imported 也不存在 → skip（S10 并发场景）──
+  it('TC4: 并发竞争——rename 抛 ENOENT + .imported 不存在 → 幂等 skip，不抛错', () => {
+    // 两进程并发：本进程 rename 时 scheduler.json 已被另一进程 rename 走 → ENOENT
+    vi.mocked(fs.renameSync).mockImplementation(() => {
+      throw enoentError()
+    })
+    vi.mocked(fs.existsSync).mockReturnValue(false) // 本进程也没看到 .imported
+    const appendEntry = vi.fn()
+
+    expect(() => importLegacyStore(cwd, { appendEntry }, sessionFile)).not.toThrow()
+    expect(appendEntry).toHaveBeenCalledTimes(0) // 别人已导入，本进程 skip
+  })
+
+  // ── TC5：currentSessionFile=undefined（--no-session 模式）→ 早 return skip ──
+  it('TC5: currentSessionFile=undefined → 整个 importer skip，不碰 fs', () => {
+    const appendEntry = vi.fn()
+
+    importLegacyStore(cwd, { appendEntry }, undefined)
+
+    expect(appendEntry).toHaveBeenCalledTimes(0)
+    expect(fs.renameSync).not.toHaveBeenCalled() // 早 return，不碰 fs
+    expect(fs.readFileSync).not.toHaveBeenCalled()
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+  })
+
+  // ── TC6：JSON 损坏降级（warn 不 rethrow）──
+  it('TC6: readFileSync 返回损坏 JSON → console.warn + 不 rethrow，appendEntry 0 次', () => {
+    vi.mocked(fs.readFileSync).mockReturnValue('not-json{')
+    const appendEntry = vi.fn()
+
+    expect(() => importLegacyStore(cwd, { appendEntry }, sessionFile)).not.toThrow()
+    expect(console.warn).toHaveBeenCalledWith(
+      expect.stringContaining('[scheduler] import failed'),
+    )
+    expect(appendEntry).toHaveBeenCalledTimes(0) // parse 失败，无 append
+  })
+
+  // ── TC7：owner 归属——upsert op.ownerSessionFile === currentSessionFile（非旧 store 路径）──
+  it('TC7: op.ownerSessionFile 严格等于传入的 currentSessionFile，非 getLegacyStorePath 推导路径', () => {
+    const ownSession = '/my/session.json'
+    const taskA = makeTask({ id: 'dddd' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA] }),
+    )
+    const appendEntry = vi.fn()
+
+    importLegacyStore(cwd, { appendEntry }, ownSession)
+
+    expect(appendEntry).toHaveBeenCalledTimes(1)
+    const op = appendEntry.mock.calls[0]![1] as { ownerSessionFile: string }
+    expect(op.ownerSessionFile).toBe(ownSession)
+    expect(op.ownerSessionFile).not.toBe(storePath)
+    expect(op.ownerSessionFile).not.toBe(importedPath)
+  })
+
+  // ── TC8：新 session 未 flush → 延迟 unlink（IMPORT-FLUSH-GUARD，MF-1）──
+  it('TC8: 新 session（sessionFile 不存在）→ 不立即 unlink，返回 cleanup；flush 后删，未 flush 保留', () => {
+    const taskA = makeTask({ id: 'eeee' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA] }),
+    )
+    vi.mocked(fs.existsSync).mockReturnValue(false) // 新 session：sessionFile 尚不存在（pi 未 flush，entries 仅内存）
+    const appendEntry = vi.fn()
+
+    const cleanup = importLegacyStore(cwd, { appendEntry }, sessionFile)
+
+    // append 已发生，但 unlink 未执行——数据可能仅内存，销毁源文件 = 永久丢失
+    expect(appendEntry).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+    expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('deferring'))
+
+    // 情形1：flush 已发生（sessionFile 出现，.imported 仍在）→ cleanup 删除 .imported
+    vi.mocked(fs.existsSync).mockImplementation(p => p === sessionFile || p === importedPath)
+    cleanup?.()
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+
+    // 情形2：从未 flush → cleanup 保留 .imported（不 unlink、不抛错，供崩溃恢复重导入）
+    vi.mocked(fs.unlinkSync).mockClear()
+    vi.mocked(fs.existsSync).mockReturnValue(false)
+    expect(() => cleanup?.()).not.toThrow()
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+  })
+
+  // ── TC8b：cleanup 幂等 + unlink ENOENT 守卫（MF-2，R2 修复）──
+  it('TC8b: cleanup 幂等（已删后 no-op）+ unlink 仅静默 ENOENT，其他 fs 错误向上抛', () => {
+    const taskA = makeTask({ id: 'ffff' })
+    vi.mocked(fs.readFileSync).mockReturnValue(
+      JSON.stringify({ version: 1, tasks: [taskA] }),
+    )
+    vi.mocked(fs.existsSync).mockReturnValue(false) // 新 session 未 flush → 延迟删除路径
+    const appendEntry = vi.fn()
+
+    const cleanup = importLegacyStore(cwd, { appendEntry }, sessionFile)!
+    expect(cleanup).toBeDefined()
+
+    // 情形1：flush 已发生 → 正常 unlink
+    vi.mocked(fs.existsSync).mockReturnValue(true)
+    cleanup()
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+
+    // 情形2（MF-2）：并发——另一进程已 unlink（unlinkSync 抛 ENOENT）→ 静默吞掉不抛
+    vi.mocked(fs.unlinkSync).mockClear()
+    vi.mocked(fs.unlinkSync).mockImplementation(() => {
+      throw enoentError()
+    })
+    expect(() => cleanup()).not.toThrow()
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+
+    // 情形3（MF-2）：非 ENOENT fs 错误（EACCES）→ 不吞，向上抛（index.ts try/finally 兜底复位）
+    vi.mocked(fs.unlinkSync).mockImplementation(() => {
+      throw Object.assign(new Error('EACCES: permission denied'), { code: 'EACCES' })
+    })
+    expect(() => cleanup()).toThrow(/EACCES/)
+
+    // 情形4：幂等——.imported 已不存在（本进程或并发已删）→ no-op，不抛
+    vi.mocked(fs.unlinkSync).mockClear()
+    vi.mocked(fs.existsSync).mockReturnValue(false)
+    expect(() => cleanup()).not.toThrow()
+    expect(fs.unlinkSync).not.toHaveBeenCalled()
+  })
+
+  // ── TC9：0 任务空 store → 无持久化依赖，仍立即 unlink ──
+  it('TC9: 空 store（tasks 空数组）→ 0 次 append，直接 unlink .imported（无数据可丢）', () => {
+    vi.mocked(fs.readFileSync).mockReturnValue(JSON.stringify({ version: 1, tasks: [] }))
+    vi.mocked(fs.existsSync).mockReturnValue(false) // 新 session 也不影响：0 任务无持久化依赖
+    const appendEntry = vi.fn()
+
+    const cleanup = importLegacyStore(cwd, { appendEntry }, sessionFile)
+
+    expect(appendEntry).toHaveBeenCalledTimes(0)
+    expect(fs.unlinkSync).toHaveBeenCalledTimes(1)
+    expect(fs.unlinkSync).toHaveBeenCalledWith(importedPath)
+    expect(cleanup).toBeUndefined()
+  })
+})

package/src/__tests__/parsing.test.ts

@@ -1,6 +1,9 @@
 import { describe, expect, it } from 'vitest'
 
 import {
+  computeNextCronRunAt,
+  computeNextCronRuns,
+  computeNextRunAt,
   computeNextRuns,
   formatDuration,
   normalizeCronExpression,
@@ -130,6 +133,32 @@ describe('parseSchedule', () => {
   })
 })
 
+describe('computeNextRunAt', () => {
+  it('interval 模式 → from + intervalMs（精确相等）', async () => {
+    const from = Date.now()
+    const next = await computeNextRunAt({ mode: 'interval', intervalMs: 60_000 }, from)
+    expect(next).toBe(from + 60_000)
+  })
+
+  it('interval 模式 from 缺省用当前时间', async () => {
+    const before = Date.now()
+    const next = await computeNextRunAt({ mode: 'interval', intervalMs: 60_000 })
+    expect(next!).toBeGreaterThanOrEqual(before + 60_000)
+  })
+
+  it('cron 有效 → 返回未来时间戳（> from）', async () => {
+    const from = Date.now()
+    const next = await computeNextRunAt({ mode: 'cron', cronExpression: '*/10 * * * *' }, from)
+    expect(next).not.toBeUndefined()
+    expect(next!).toBeGreaterThan(from)
+  })
+
+  it('cron 无效 → undefined', async () => {
+    const next = await computeNextRunAt({ mode: 'cron', cronExpression: 'invalid * *' }, Date.now())
+    expect(next).toBeUndefined()
+  })
+})
+
 describe('computeNextRuns', () => {
   it('computes interval runs', async () => {
     const from = Date.now()

package/src/__tests__/property.test.ts

@@ -0,0 +1,131 @@
+import fc from 'fast-check'
+import { describe, expect, it } from 'vitest'
+
+import { computeNextRunAt, computeNextRuns, formatDuration, parseDuration, parseSchedule } from '../parsing.js'
+
+/**
+ * property-based 测试（fast-check）：纯函数不变量回归保护。
+ *
+ * 生成器范围契约（与 m3-design C1 一致）：
+ * - intervalMs ∈ [1, 86_400_000]（1ms..1d，贴近 parseDuration 现实域）
+ * - from ∈ [0, 2^48]（from + intervalMs*count ≈ 2.8e14 << 2^53，无 Number 溢出）
+ * - count ∈ [1, 10]
+ *
+ * 不变量边界（C3）：
+ * - formatDuration↔parseDuration round-trip 恒等仅对「精确域」成立
+ *   （ms % 1000 === 0 且 ms >= 1000，s 分支整除保证）；
+ * - 全域只断言输出可解析且 >= 0（Math.round 兜底会破坏非整除域恒等，禁止断言恒等）。
+ */
+
+describe('property: computeNextRunAt interval 精确不变量', () => {
+  it('恒等于 from + intervalMs 且 > from', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.integer({ min: 1, max: 86_400_000 }),
+        fc.integer({ min: 0, max: 2 ** 48 }),
+        async (intervalMs, from) => {
+          const r = await computeNextRunAt({ mode: 'interval', intervalMs }, from)
+          expect(r).toBe(from + intervalMs)
+          expect(r!).toBeGreaterThan(from)
+        },
+      ),
+    )
+  })
+})
+
+describe('property: computeNextRuns interval 等间隔递增', () => {
+  it('长度 === count、严格递增、等间隔、runs[0] 与 computeNextRunAt 一致', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.integer({ min: 1, max: 86_400_000 }),
+        fc.integer({ min: 0, max: 2 ** 48 }),
+        fc.integer({ min: 1, max: 10 }),
+        async (intervalMs, from, count) => {
+          const runs = await computeNextRuns({ mode: 'interval', intervalMs }, from, count)
+          expect(runs).toHaveLength(count)
+          for (let i = 0; i < count; i++) {
+            expect(runs[i]).toBe(from + intervalMs * (i + 1))
+            if (i > 0) expect(runs[i]!).toBeGreaterThan(runs[i - 1]!)
+          }
+          // 两入口同源不变量：runs[0] 必须与单次计算入口一致
+          const single = await computeNextRunAt({ mode: 'interval', intervalMs }, from)
+          expect(runs[0]).toBe(single)
+        },
+      ),
+    )
+  })
+})
+
+// ── TC4 grammar 生成：duration 单位表（与 parsing.ts DURATION_MULTIPLIERS 语义一致） ──
+
+const UNITS = ['s', 'sec', 'second', 'seconds', 'm', 'min', 'minute', 'minutes', 'h', 'hr', 'hour', 'hours', 'd', 'day', 'days']
+const UNIT_VARIANTS = [...UNITS, ...UNITS.map(u => u.toUpperCase()), 'Sec', 'MIN', 'Hours', 'Day']
+
+const MULTIPLIERS: Record<string, number> = {
+  s: 1000, sec: 1000, second: 1000, seconds: 1000,
+  m: 60_000, min: 60_000, minute: 60_000, minutes: 60_000,
+  h: 3_600_000, hr: 3_600_000, hour: 3_600_000, hours: 3_600_000,
+  d: 86_400_000, day: 86_400_000, days: 86_400_000,
+}
+
+describe('property: parseDuration/parseSchedule round-trip', () => {
+  it('合法 duration（value×unit grammar 生成）恒精确解析且 parseSchedule 恒 interval mode', async () => {
+    await fc.assert(
+      fc.asyncProperty(
+        fc.record({
+          value: fc.integer({ min: 0, max: 1_000_000 }),
+          unit: fc.constantFrom(...UNIT_VARIANTS),
+        }),
+        async ({ value, unit }) => {
+          const text = `${value}${unit}`
+          const expectedMs = value * MULTIPLIERS[unit.toLowerCase()]!
+          expect(parseDuration(text)).toBe(expectedMs)
+
+          // 无空格字符串 → 恒走 duration 分支 → interval mode + 同一 intervalMs
+          const parsed = await parseSchedule(text)
+          expect(parsed).toBeDefined()
+          expect(parsed!.spec).toEqual({ mode: 'interval', intervalMs: expectedMs })
+        },
+      ),
+    )
+  })
+
+  it('非法输入（裸数字/未知单位/空串/负值/小数）恒 undefined', async () => {
+    const invalid = ['123', '5x', '', '-5m', 'm', '1.5m', '5m 5s']
+    for (const input of invalid) {
+      expect(parseDuration(input)).toBeUndefined()
+      expect(await parseSchedule(input)).toBeUndefined()
+    }
+  })
+})
+
+describe('property: formatDuration↔parseDuration round-trip', () => {
+  // 精确域：ms 为 1000 正整数倍且 >= 1000 → 恒等（整除路径或 s 分支兜底均精确）。
+  // 用 k*1000 生成（而非 filter）避免 fc 对 1/1000 通过率的 filter 重试浪费。
+  it('精确域 round-trip 恒等', () => {
+    fc.assert(
+      fc.property(
+        fc.integer({ min: 1, max: 1_000_000 }).map(k => k * 1000),
+        ms => {
+          expect(parseDuration(formatDuration(ms))).toBe(ms)
+        },
+      ),
+    )
+  })
+
+  // 全域：Math.round 兜底会破坏非整除域恒等（如 1500 → '2s'），
+  // 只断言输出可解析且解析值 >= 0（C3 不变量边界）。
+  it('全域输出恒可解析且 >= 0（不断言恒等）', () => {
+    fc.assert(
+      fc.property(
+        fc.integer({ min: 1, max: 1_000_000_000 }),
+        ms => {
+          const out = formatDuration(ms)
+          const parsed = parseDuration(out)
+          expect(parsed).toBeDefined()
+          expect(parsed!).toBeGreaterThanOrEqual(0)
+        },
+      ),
+    )
+  })
+})