DSH plugin capturedThroughSeq: a coordinate, not a position
In DSH plugin, reading capturedThroughSeq as the current session's message number is the easiest coordinate mistake in cross-session references. It records how far the snapshot read into the source session's original generation; without the source identity, the number means nothing.
DeepSeek Harness: A coordinate mix-up
The symptom looks like a misplaced reference; the cause is two numbering spaces used as one. (source) Scene:
Current session seq reaches 120
Reference snapshot capturedThroughSeq = 87
Host looks up 87 in the current session -> lands on an unrelated message
Nobody wrote wrong code; someone assumed seq is global.
Once that assumption takes hold, every recall, jump, and diff drifts.
The diagnostic is one question: which session does this number belong to? If the answer is unclear, it is already being used wrong.
DeepSeek Harness: Two sequence spaces
Each session has its own numbering space, with no cross-session ordering. (source) Comparison:
| Dimension | Source generation | Current session |
|---|---|---|
| Who assigns numbers | The source session | The current session |
Who owns capturedThroughSeq | The source session | Not the current one |
| Cross-session size comparison | Not possible | Not possible |
| Precondition for validity | Include the source sessionId | Include the current sessionId |
The last row is the point: a sequence is not a standalone key; it appears as a pair with session identity.
That is also why sessionId and capturedThroughSeq live in the same reference entry instead of two separate tables.
DeepSeek Harness: Three reading rules
Three constraints governing ownership, interpretation, and absence. (source) Content:
- Belongs to the source generation — the coordinate is valid inside that session's numbering space;
- Never reinterpreted — it is not taken as the enclosing session's seq;
- Optional — the field may be absent, and absence must not be treated as presence.
Rule 2 is a hard constraint, not advice. Any formula that converts a source seq into a current seq lacks a basis.
Rule 3 is often skipped: using 0 or -1 for "no coordinate" invites downstream code to treat it as a real position. Absent should stay absent.
DeepSeek Harness: Coordinates, compaction, counts
Three fields answer three questions; missing one causes misjudgment. (source) Decision table:
| Want to know | Read |
|---|---|
| Where the read stopped in the source | capturedThroughSeq |
| Whether the source already lost content | compacted |
| How much was lost | originalMessages / retainedMessages / omittedMessages |
| Whether this preparation omitted more | truncated |
A typical error is announcing "it read up to message 87" from the coordinate alone. If the source was compacted, what follows message 87 does not equal "what followed original message 87".
Another error infers position from counts. Counts describe scale, not boundaries.
The right order: locate the boundary with the coordinate, use compacted to see whether that boundary was reshaped by compaction, and use counts to size the gap.
DeepSeek Harness: How to store during splicing
Bind the coordinate to session identity and never convert it. (source) Three practices:
- Store a
(sessionId, capturedThroughSeq)pair and read them together; - Label the source in the UI, such as "from A, read through message 87";
- To jump, open the source session first, then locate by coordinate.
The third is the only safe jump. Switch sessions, then locate; never search the current session and try to correct afterward.
If a product needs clickable anchors for referenced spans, the anchor should encode both session identity and coordinate, not a bare number.
One more: log the session identity alongside the coordinate. A lone seq=87 is unattributable six months later.
DeepSeek Harness: Verifying the reading
Three steps plus one counterexample prove no reinterpretation. Steps:
- Reference a source session and record its
capturedThroughSeqandsessionId; - Open that coordinate with the source identity and confirm it lands on the snapshot's last message;
- Open the same number with the current session identity and confirm a different result (or an explicit absence).
Step 3 is the counterexample: identical results mean the host reinterpreted somewhere, or the two sessions happen to be isomorphic, so test with another dataset.
Add an absence case: build a reference without a coordinate and confirm the UI shows "position unknown" rather than message 0.
With coordinates settled, the next topic is format versions. Read DSH plugin capturedFormatVersion: missing means v0; for source-side gaps, read DSH plugin referencing a compacted session; for the record structure, read DSH plugin recall records.
Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts
FAQ
No, DSH plugin's capturedThroughSeq belongs to the referenced session's original generation and records how far the snapshot read. DSH plugin never reinterprets it as the enclosing session's seq.
No, DSH plugin sequence values from two sessions cannot be compared by size. Each session has its own generation and numbering space, so comparison is meaningless. A coordinate must be used together with its sessionId.
DSH plugin makes the coordinate optional because some references have no explicit position, such as records from an older format. DSH plugin allows the field to be absent, and callers must not assume it or use 0 as a placeholder.
A DSH plugin coordinate remains in the source generation and is never rewritten into the current session's numbering. compacted and message counts describe the gap; the coordinate says how far it read.
Related Terms
- capturedThroughSeq
- capturedThroughSeq is an optional sequence in the persistent source recording how far the snapshot read into the referenced session's original generation.— DeepSeek Harness reference - Session references
- generation
- A generation is a session's history version space; sequence numbers are valid inside it and do not transfer across sessions.— DeepSeek Harness reference - Session references
- seq reinterpretation
- Seq reinterpretation uses a source session's sequence as the current session's sequence, which is an explicit out-of-bounds read.— session-reference/src/types.ts
- cross-session splicing
- Cross-session splicing places several reference snapshots in one message context while each keeps its own source coordinate.— DeepSeek Harness reference - Session references
Sources
- DeepSeek Harness reference - Session references· deepseek-ai
- session-reference/src/types.ts· deepseek-ai