ChatGPTClaudeGrok / X / CursorGemini

DSH plugin capturedFormatVersion: missing means format v0

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnesssession referencecapturedFormatVersioncompatibility
Old records may lack capturedFormatVersion. Two wrong readings, two version lines, and how to branch so v0 is a format rather than an error.

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:

text
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:

VersionDescribesUpgraded byWhen absent
Record versionThe persisted source structureRecord format evolutionTreat as the lowest known version
capturedFormatVersionThe source format at captureSource format evolutionInterpret 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:

  1. It has a definite field set and semantics, so readers can implement it completely;
  2. Absence equals v0, so no extra "this is an old record" marker is needed;
  3. 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:

text
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:

  • ?? 0 rather 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:

ScenarioAction
Record written by an older implementationRead through the v0 branch
Whole-store structure upgradeRun the migration flow
Record written by a newer implementationRecognize 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:

  1. Remove capturedFormatVersion and confirm the v0 branch runs with the same result as an explicit 0;
  2. Write the current version and confirm the matching branch parses all fields;
  3. 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

ChatGPTClaudeGrok / X / CursorGemini

FAQ

In DSH plugin, a reference record has no capturedFormatVersion. Is the data corrupted?

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.

For DSH plugin, is capturedFormatVersion the same as the record's version field?

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.

With DSH plugin, what should happen when reading a newer capturedFormatVersion than the implementation supports?

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.

In DSH plugin, should a full migration backfill capturedFormatVersion on old records?

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