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

Files

Tianyi Cui 605587e79c docs(rfc): classify RFCs by kind via path-encoded subdirectories

Add a second axis to every RFC — its class (feature, bug-fix,
simplification, architecture, process, testing) — encoded in the path
as docs/rfc/{lifecycle}/{class}/file.md. The folder is the label, so
the closed set is enforced by structure rather than a parsed field.

Two new doc-sync gates back it:
- verify-rfc-classification: every RFC sits in a valid class folder and
  the README index lists it under the matching lifecycle→class heading.
- verify-doc-refs: every docs/*.md path cited in a packages|examples TS
  comment resolves — closes a drift class verify-md-links can't see, and
  catches the four comment refs this reorg moved.

The README gains a Classification section explaining the taxonomy and
per-class index sub-sections. A self-referential process RFC records why
the scheme is path-encoded and gated.

2026-06-20 22:29:45 +08:00

2.6 KiB

Raw Blame History

RFC: Drop durable step boundary events

Status: rejected — step/end is the durable indication that a model step finished, and keeping the symmetric step/start / step/end pair makes crash repair, invariants, and transcript inspection clearer than inferring completion from adjacent step-scoped events.

Problem

The session log stores step/start and step/end events even though every step-scoped event already carries { turn, step }: assistant chunks, assistant messages, tool calls, tool results, usage, and errors. deriveMessages() ignores step boundaries, ACP ignores them for UI, and the main consumers are invariants, tests, snapshot goldens, and crash repair.

The rejected argument was that boundary events make the log more ceremonial than informative. In practice, step/end is concrete information: a reader can tell whether a model request finished, crashed, or is being repaired without deriving that state from the next event. A bare step/start is likewise useful for a model request that began but produced no chunks before failing.

Proposal

Make the turn the only durable boundary. Remove step/start and step/end from SessionEventMap; keep the numeric step field on events that need grouping. The loop increments the step counter and records step-scoped events with that number, but it no longer appends open/close boundary events. Consumers infer step groups from contiguous events sharing (turn, step).

The invariants plugin should enforce that step-scoped events have valid positive step numbers within an open turn, not that separate boundary records surround them. Crash repair should not synthesize step/end; if an interrupted turn is preserved, the repair path can still close the turn without inventing step boundary records.

Acceptance criteria

SessionEventMap no longer includes step/start or step/end.
The loop has no closeStep() finalization path.
ACP snapshots and persistence contract fixtures stop expecting step-boundary lines.
deriveMessages() and replay derive the same message history from step-scoped events.
The event taxonomy docs describe turns as the durable boundary and steps as a field on step-scoped records.
The session format version and recorded fixtures are refreshed; non-current stored logs are rejected per the pre-release format policy.

What we give up

The log no longer records "a model request started but produced no event before the process died" as a durable fact, and no longer has an explicit "this step completed" marker. That loss is not acceptable while the session log is the durable replay and audit surface.

2.6 KiB Raw Blame History