mirror of https://github.com/deepseek-ai/deepseek-harness synced 2026-08-15 21:04:50 +00:00

Files

Tianyi Cui e6fad266a6 docs(rfc): define and enforce a uniform RFC format; adopt it across the corpus

Define the in-file RFC contract in docs/rfc/README.md § The file format:
the header block (`# RFC: <title>` plus a dateless Status enum
cross-checked against the lifecycle folder), the per-lifecycle body
skeleton (a Problem opener everywhere; Proposal/Alternatives considered/
Acceptance criteria/Risks in proposed/; present-tense Decision/
Consequences with proposal-era headings banned in implemented/; the
frozen proposal shape in rejected/), and a mandatory Alternatives
considered section with a date-fenced grandfather comment for pre-format
RFCs whose alternatives are not reconstructible from the record.

Enforce it with a new doc-sync gate, scripts/verify-rfc-format.ts, and
normalize all 112 RFCs to it: ~15 Status-line spellings collapse to the
enum, 29 Context openers become Problem, the 39 legacy-format XXX debt
markers are resolved and banned from reappearing, proposal-era sections
in implemented RFCs are rewritten to shipped reality (including the
web/fs/subagent seam RFCs' migration plans and test checklists, closing
the doc-tiers deferred-work item on the web seam), every RFC gains an
Alternatives considered section or the grandfather comment, and the
bilingual pair is re-mirrored and re-recorded.

Move the generated index tables out of README.md into a fully generated
docs/rfc/INDEX.md — gen-rfc-index now writes the whole file, and
verify-rfc-classification checks its freshness and rejects index-shaped
rows in the curated README — which makes room for the format contract to
live in the README front door instead of a separate FORMAT.md.

The decision record, and the first RFC written in the new format, is
docs/rfc/implemented/process/2026-07-05-uniform-rfc-format.md.

2026-07-05 22:58:25 +08:00

2.2 KiB

Raw Blame History

RFC: Deterministic tests, the replay invariant fixture, and race stress

Status: proposed

Problem

Several loop tests synchronize with setTimeout(30) sleeps — flakiness debt that wastes agent cycles on retries and can mask ordering bugs. Separately, our core architectural promise (any session log replays to identical derived history) is asserted in two tests but is cheap to assert everywhere. And the inbox wakeup race was verified by hand exactly once; nothing re-verifies it continuously.

Proposal

Three measures:

No wall-clock sleeps in tests. Replace setTimeout(N) waits with event-driven waits (the existing waitForIdle pattern, extended to waitForStatus, waitForEvent(n)) or vitest fake timers where time itself is under test. Enforce with a lint rule banning setTimeout in packages/*/tests outside an allowlisted helper module.
Universal replay fixture. A shared test helper wraps the loop harness so that after every test, the agent's session log is replayed into a fresh Session and deriveMessages() equality is asserted automatically. The invariant then gets checked hundreds of times per CI run across every scenario the suite produces, not twice.
Nightly race stress. A CI job running the agent-loop and inbox suites with vitest --repeat=200 (and --shuffle) to flush scheduling-dependent failures; any flake found is a bug to fix, never a retry.

Plan

Land 1 and 2 together (they touch the same helpers); add the nightly job after the suite is sleep-free so repeats are fast.

Acceptance criteria

No setTimeout remains in packages/*/tests outside the allowlisted helper module, enforced by the lint rule.
The shared harness replays every test's session log into a fresh Session and asserts deriveMessages() equality automatically, across the whole suite.
The nightly job runs the agent-loop and inbox suites with --repeat and --shuffle; a flake it finds is triaged as a bug, never retried away.

Risks

Fake timers interact subtly with Promise scheduling in the loop — prefer event-driven waits; reserve fake timers for timer-service behavior itself.

2.2 KiB Raw Blame History