Baseline, Method, and Evidence Rules
Separating source facts, mechanism-level deductions, and design assessments
Why the commit must be pinned
DeepSeek Harness explicitly describes itself as pre-first-tag software: sound foundations take precedence over compatibility shims; the SQLite schema moves monotonically, while the session format remains version 0 without a compatibility promise. ROOT-PREVIEW
“How current master works” is therefore a high-drift statement. Every fact in this report is bound to a complete SHA. A future update will add a baseline-diff edition instead of silently replacing an old conclusion with a new implementation.
Evidence strength
Production source and effective configuration
The strongest evidence. Construction, callers, mutations, failures, and disposal all matter.
Behavioral tests and snapshots
They prove observable behavior for particular inputs, but only after verifying that the fixture traverses the production assembly path.
Generated documentation
Source-gated tool catalogs, module graphs, and event diagrams are excellent coverage maps, but they do not replace detailed control-flow analysis.
Manually maintained documentation
Useful for intent and vocabulary. When it conflicts with code, the pinned source baseline wins.
Plans and discussions
Evidence of direction and problem awareness, not proof of implemented runtime behavior.
Keep three kinds of statements separate
Example: “A tool call is appended as tool/call before execution, and the final result is appended as tool/result.” Production control flow and the generated sequence can prove this directly. TURN-SEQUENCE
Example: “The UI may show a pending tool card before completion, while final model history still derives from durable events.” This conclusion joins event ordering, presentation events, and history derivation.
Example: “Event sourcing reduces divergence among product surfaces but moves compatibility pressure into event vocabulary and projections.” This is an evaluation and must state benefits, costs, and assumptions together.
The standard dissection template
- Product role: Which user or runtime need does this module own?
- Entry and assembly: Which bundle/profile mounts it, and which services does it require?
- Types and data: Public interfaces, events, schemas, branded IDs, and durable representations.
- Real control flow: Happy path, branch conditions, and exact mutation points.
- Concurrency and lifecycle: Scope, owner, cancellation, disposal, cleanup, and races.
- Error semantics: Who classifies, retries, degrades, and preserves the original error?
- Replay and observability: Which facts are durable, which are live-only, and how recovery works.
- Verification: Unit, integration, snapshot, runtime invariant, and remaining evidence gaps.
- Assessment: Benefits, costs, constraints, operating boundaries, and transferable principles.
Completion gate for a chapter
A chapter moves from In progress to Verified only after it covers the entry point, core types, principal state machine, durable facts, error paths, and key tests, followed by at least one end-to-end review from entry to side effect. Failure to find a counterexample is not completion. Broad claims without direct evidence remain explicit open questions.
My Learning Notes
Autosaved only in this browser. Nothing is uploaded or committed. Export Markdown whenever you want to keep a copy.