e6fad266a6
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.
2.6 KiB
RFC: Fold the persistence interface into dsh-session
Status: rejected — the separate persistence interface package is the intended modular capability seam for durable backends. Folding it into dsh-session would reduce package count at the cost of a cleaner backend boundary.
Problem
dsh-session-persistence is an interface package whose main concepts are already owned by dsh-session: SessionHeader, SessionEvent, SessionId, session/event, and session/flush. The package adds the abstract SessionPersistence service, the shared write coordinator, and contract helpers. Backend packages depend on it, and agent-loop has to optionally find a sibling service for resume.
The capability-seam split made sense when persistence was a new swappable backend design. After the mutable summary was removed, the interface package mostly wraps the session log's own storage concern. Keeping it separate may be more ceremony than clarity.
Proposal
Move the abstract SessionPersistence service, the coordinator, and persistence contract helpers into dsh-session. Keep JSONL and SQLite as separate backend packages that register the session-owned service. This preserves backend swappability while deleting one support package and one cross-package seam.
The implementing PR should update the capability seams guidance with the exception: persistence is not like bash or LLM because its vocabulary and lifecycle events are already the session package's core domain.
Acceptance criteria
@deepseek-ai/dsh-session-persistenceis removed as a package.dsh-sessionexports the persistence service type, coordinator, and contract helpers.- JSONL and SQLite backend packages depend on
dsh-sessiondirectly. agent-loopresume uses the session-owned service key.- Session persistence, shared persistence write coordinator, and package docs explain why backend implementations remain separate.
What we give up
dsh-session becomes heavier: it owns both the in-memory log and the persistence interface. That is the trade. If third-party persistence backends were already a public ecosystem, the separate interface package would be a cleaner SDK boundary; pre-release, the extra package looks like abstraction before there is an external consumer.