deepseek-harness/docs/session-format-status.md

Session format version and release status

English | 中文

Summary

Use this reference to distinguish the checkout’s Session writer version from the latest published Session format. The code constant owns the writer version; the release record below owns the latest released format and its publication evidence. Other documentation links here instead of restating which version is current, next, or unreleased.

Table of Contents

• Sources of truth
• Release record
• Updating the record
• Dev Note

Sources of truth

• Checkout writer: SESSION_FORMAT_VERSION in core Session types is the only hand-maintained current-writer number in code. The catalog generator derives codec ordering and checks that adjacent migrations reach it. A package version, codec export name, fixture filename, or projection-cache version is not the writer authority.
• Latest released format: latestReleasedVersion in the following record identifies the published Session format. evidenceTag names a published product release whose tagged writer has that value; it need not be the first release carrying the format. The bilingual copy is checked against the same record, not maintained as a separate decision.
• Release status: compare the writer constant with the verified release record. Equality means the writer format has shipped. A greater writer version is a development target beyond the recorded release. When comparing an older checkout against a newer branch’s verified record, a lower writer version identifies an older writer format; the local consistency gate rejects that ordering within one checkout. No separate released boolean is maintained. Before declaring a greater version unreleased, verify that no published release has advanced the record.

An alpha, beta, or release-candidate product publication establishes released Session-format obligations. GitHub’s prerelease flag does not make persisted user data disposable. A missing release record is not evidence of non-publication. The versioning and authority decision owns compatibility decisions; released-format migration owns immutable generations and adjacent conversion.

Release record

latestReleasedVersion: 3
evidenceTag: dsh-v0.1.5-alpha.1

Evidence: published release and its tagged writer source.

Updating the record

When a structural writer change is implemented, update the code constant and adjacent catalog together; do not advance this release record before publication. When a product release first publishes a higher Session format, confirm publication and its tagged writer, then advance this record and both evidence links in the same bilingual update. Later product releases carrying the same format do not require changing the record. Never lower it on the development trunk.

The documentation-standard test checks record structure, bilingual equality, evidence-link consistency, and that the documented release does not exceed the checkout writer. This keyless check does not query GitHub or prove that the record is up to date; publication verification remains part of the release update.

Use “current format” and “next adjacent version” for general behavior. Keep explicit numbers for fixed migration inputs and outputs, wire schemas, historical evidence, and tests of those particular versions. The format-version cookbook uses N for the verified latest released format and N+1 for its successor.

Dev Note

None.