DSH plugin capturedFormatVersion: missing means format v0
After an upgrade, an old reference record may simply have no capturedFormatVersion. Two intuitions follow: unknown format, or some old version. DSH plugin's answer is unambiguous: missing means the published format v0.
DeepSeek Harness: Two wrong conclusions when the field is missing
Opposite directions, same outcome: the old record gets read wrong. (source) Scene:
record: kind: 'session-reference', form: 'recall', version: 1
references[0]: no capturedFormatVersion
The first wrong conclusion treats it as unknown and refuses to read, so users see "reference record unavailable".
The second treats it as the current format and forces the newest parser, producing field meanings that do not line up while nobody notices.
The first is over-cautious, the second over-optimistic. The right move is to interpret it as v0 and touch only fields v0 guarantees.
DeepSeek Harness: Two version lines
Two version numbers with different owners; mixing them breaks compatibility checks. (source) Comparison:
| Version | Describes | Upgraded by | When absent |
|---|---|---|---|
Record version | The persisted source structure | Record format evolution | Treat as the lowest known version |
capturedFormatVersion | The source format at capture | Source format evolution | Interpret as format v0 |
The first column is often mistaken for "one version number rules everything". In reality they evolve separately: the record structure can change while the source format does not.
That is how one record can carry version: 1 and capturedFormatVersion: 2 at the same time.
Check both for compatibility: the record structure decides how to read the record, and the captured version decides how to interpret the source content inside it.
DeepSeek Harness: What v0 actually is
A published format, not a placeholder. (source) Three implications:
- It has a definite field set and semantics, so readers can implement it completely;
- Absence equals v0, so no extra "this is an old record" marker is needed;
- It is not "unknown", so it must not trigger a refusal.
Treating v0 as unknown converts a handleable state into an error state.
The reverse is also wrong: treating v0 as a simplified latest format. v0 may have fewer fields, and forcing the current shape yields empty values that get misread as "empty content".
DeepSeek Harness: Branching by version
Dispatch first, then parse; fail loudly on unknown versions. (source) Skeleton:
const format = ref.capturedFormatVersion ?? 0; // missing means v0
switch (format) {
case 0: return parseV0(ref);
case 1: return parseV1(ref);
default: throw new UnsupportedCapturedFormat(format);
}
Three details matter:
?? 0rather than clever truthiness checks, so 0 is never bypassed as falsy;- Each branch reads only fields that version guarantees, with no cross-version guessing;
- The default branch must throw, never
return parseLatest(ref).
The last is defensive design: silently parsing with the newest format disguises "this record is newer than me" as "this record is odd".
DeepSeek Harness: Reading vs migration
Migration changes storage; version branching changes reading. Neither replaces the other. (source) Division:
| Scenario | Action |
|---|---|
| Record written by an older implementation | Read through the v0 branch |
| Whole-store structure upgrade | Run the migration flow |
| Record written by a newer implementation | Recognize it as unsupported and error |
The first needs no data write, only correct reading.
The second should not casually backfill capturedFormatVersion to the current value, which erases the source's real format.
The third is a blind spot in many implementations: backward compatibility is considered, forward compatibility is not.
DeepSeek Harness: Verifying version handling
Three cases cover absent, current, and future. Steps:
- Remove
capturedFormatVersionand confirm the v0 branch runs with the same result as an explicit 0; - Write the current version and confirm the matching branch parses all fields;
- Write a larger version and confirm an explicit error rather than silent success.
Step 1's "same as an explicit 0" matters: it proves absence is a real path, not something that merely failed to crash.
Step 3 prevents the default branch from silently falling back to the newest parser.
Add one regression check: read the same record twice and require identical results. If version dispatch depends on global mutable state, the second read may take a different branch.
With versions correct, coordinates matter too. Read DSH plugin capturedThroughSeq belongs to the source generation; for whole-store upgrades, read DSH plugin session migration after an update; for the record structure, read DSH plugin recall records.
Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts
FAQ
No, DSH plugin treats the missing field as published format v0. Missing means the published format v0, a compatibility convention rather than an anomaly. DSH plugin does not treat it as unknown, and readers do not need to reject the record.
No, DSH plugin keeps the record version and capturedFormatVersion separate. version describes the record's own structure, while capturedFormatVersion describes the source session's format at capture time. DSH plugin keeps them separate, and upgrades must not collapse them.
Do not silently parse it with the latest logic in DSH plugin. The record came from a newer writer, so DSH plugin's correct behavior is to report an unsupported version instead of guessing field meanings.
DSH plugin does not require backfilling just to make the field exist. Absence is a valid expression of v0; DSH plugin's record semantics reflect capture time, and backfilling would erase the real source version.
Related Terms
- capturedFormatVersion
- capturedFormatVersion records the source session's format at capture time and selects how to interpret it across versions.— DeepSeek Harness reference - Session references
- format v0
- Format v0 is the published format implied when capturedFormatVersion is absent; it is not an unknown state.— DeepSeek Harness reference - Session references
- record version
- The record version describes the persisted source structure and is independent of the source session's format version.— session-reference/src/types.ts
- version branching
- Version branching chooses parsing logic by the record's format version instead of forcing every record through the current implementation.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/types.ts· deepseek-ai