v0-format sessions fail to project after v0→v3 migration: unguarded message.content reads in stock projections

[3485078318-droid]

Environment

• dsh 0.1.5-rc.2 (source checkout, tag dsh-v0.1.5-rc.2, commit fb2c4b9)
• Windows 11 (22621)
• Sessions created on 0.1.1-rc.2, stored in the old log format v0

Symptom

Opening a historical v0-format session fails hard — the whole session becomes
unopenable:

failed to project session "session-…": Cannot read properties of undefined (reading 'content')

Other sessions (newer format) are unaffected, so this only bites the long tail
of pre-upgrade logs after the automatic v0→v3 migration.

Root cause

After the v0→v3 migration, some events carry no message body:

• assistant/message / tool/result events where data.message is undefined
• replace-shaped surfaceOp records with no resolvable start/end

Three stock projections assume the migrated shape is always complete and read
through it unguarded, so one legacy event aborts the entire hydrate():

1. session-turn-outline/src/projection.ts
   • event.data.source.kind and preview(event.data.content, …) (user/message)
   • preview(event.data.message.content, …) (assistant/message)
2. session-stats/src/projection.ts
   • event.data.message.source.callId (tool/result)
3. session-telemetry/src/coordinator.ts
   • event.data.message.content[0].isError (tool/result)

(The same shape also trips third-party projections, e.g. a live-token-usage
plugin that prices message.content; that part is the plugin author's to fix,
but the stock projections are what make the session unopenable.)

Suggested fix

Make the stock projections degrade gracefully on under-filled migrated events
instead of throwing — optional chaining plus a neutral fallback. A patch
against 0.1.5-rc.2 is attached (dsh-015-legacy-projection.patch); it only
touches the three projection files, no format/migration logic.

• turn-outline: message?.content ?? '', source?.kind, content ?? []
• session-stats: message?.source?.callId + treat a missing envelope as an
  unmatched call (skip the timing sample)
• session-telemetry: message?.content?.[0]?.isError, reason?.kind

Notes

• Happy to open a PR if this approach sounds right.
• Might also be worth deciding whether the v0 migrator should synthesize a
  minimal message envelope instead, so downstream consumers see a complete
  shape; the defensive reads above are the minimal-risk option either way.

---

附：补丁文件

dsh-015-legacy-projection.patch

[moonquake2004]

Independent confirmation of the two reads I could check on the installed 0.1.5-rc.2 tree, plus a tool-side consequence you may not have considered.

The unguarded reads are exactly where you say. I could verify two of the three directly:

dsh-session-stats/lib/index.js:135          const callId = event.data.message.source.callId
dsh-session-turn-outline/lib/index.js:112   preview(event.data.message.content, RESPONSE_PREVIEW_LIMIT)

Both are plain property chains with no optional chaining, in a hydrate()-time path — one under-filled legacy event aborts the whole projection, which matches your "session becomes unopenable" symptom. I could not confirm the third (session-telemetry) from the compiled output — its coordinator may be structured differently — and I have no Windows environment, so I am not vouching for your reproduction, only for these two lines.

A second consequence: this is also a robustness test for anything that reads session logs, including diagnostics. We build an offline doctor that scans session archives, so I took your root cause and built a fixture with both shapes (assistant/message and tool/result carrying no data.message). Result: our engine does not crash — it produces its normal verdicts, and our session reader walks every row. I mention it because the failure mode you are describing generalises: a tool that crashes on the very input it is meant to diagnose is worse than no tool, and we only know we are clear of it because your report specified the shape precisely enough to construct.

What we added as a result (released in dsh-doctor@0.4.28): your case is the one our session coverage was missing — we detect migration refusals (a pre-flight that runs the real migration chain), but not "migration succeeded, opening throws". Now:

• S14 (per session) fails on ① events whose type implies a message body but where data.message is absent or not an object — covering the three types the stock projections read through (assistant/message, tool/result, system/message); and ② replace-shaped surfaceOp ({op:'replace', start/end} or startSeq/endSeq) whose referenced position does not resolve anywhere in the log. It reports the line numbers and says the session will fail to open.
• The whole-store scan now counts this class as damaged too, so the thing your report makes necessary becomes answerable: which of my historical sessions will refuse to open — you can get the list before clicking any of them, and isolate the affected directories instead of discovering them one failure at a time.

To be explicit about the boundary: we detect the shape, we do not fix the projection. The graceful-degradation patch is yours to land upstream (and message?.content ?? '' plus treating a missing envelope as an unmatched call is the same fallback shape our own reader already uses, so that approach looks right to me from the outside).

One suggestion for the report itself: if the patch is against 0.1.5-rc.2, it is worth stating whether hydrate() is expected to become total over migrated logs (i.e. any under-filled event is tolerated) or only over the specific under-filled shapes the migration can currently produce. The two differ in what a future migration change is allowed to assume, and the projection files are the wrong place to discover that.

[PerryLink]

Confirmed on master (c291e79) — and I can add the third location moonquake2004 couldn't confirm from the build artifact.

The three unguarded reads:

1. session-turn-outline/src/projection.ts — event.data.source.kind (:110), event.data.content (:113), event.data.message.content (:119)
2. session-stats/src/projection.ts:174 — event.data.message.source.callId
3. session-telemetry/src/coordinator.ts:270 — event.data.message.content[0].isError

git diff dsh-v0.1.5-rc.2..HEAD over these three files: turn-outline and stats are byte-identical; coordinator.ts has exactly one added line, an oxlint-disable comment (no functional change). So the bug is live on master and your defensive patch applies as-is.

On "should the migrator synthesize envelopes": it already partially does — normalizeLegacyMessage synthesizes message for assistant/message and tool/result (session-format-v0-to-v1/src/migration.ts:364-410), but each case has an explicit pass-through branch when a needed key is present/missing (:353-355,:365-366,:386-388). So "the migrator guarantees a complete envelope" is NOT today's contract; defensive guards in projections are the minimal-risk fix and I'd support that PR. If you'd rather fix migration-side, you'd first have to decide whether hydrate should be "total" (all events) — that's a contract question for the maintainers.

(Your Windows repro I can't run; the source-level confirmation above is what I can honestly offer.)

[moonquake2004]

Thanks for closing the third location — that is precisely the part I could not do: I was reading the build artifact and could only confirm two of the three, while you read src/*.ts and checked it against master. The git diff dsh-v0.1.5-rc.2..HEAD result (two files byte-identical, one added lint comment) is exactly the evidence I was missing.

One piece of data we can add: the shape does not appear in every store. Using the real migration chain (sessionFormatCatalog.createRestore → decodeRow per row → finish) over the logs on this machine:

101 session logs total
 52 walked the v0 → v3 chain successfully
  0 produced an under-filled event (assistant/message | tool/result | system/message without data.message)

So it is not "every migrated session" — it depends on the specific v0 content, which fits your symptom being reproducible on your store and not universal. If you can say which v0 event kinds were involved when it does happen (even one sanitized excerpt), the discriminator would be pinned down — and it would tell us whether our check needs a second trigger. Ours is macOS with sessions from that era, so a Windows-only path looks unlikely; a specific v0 shape (a cancelled step, or one of the pass-through branches you identified at migration.ts:353-355 / :365-366 / :386-388) seems the better hypothesis.

Your report has now improved our detection twice, and the second time was a correction to ourselves. I added S14 off the back of your root cause — and its first version inspected on-disk rows, which is the wrong place if the under-filling happens during migration: the projection reads the migrated stream, so a disk scan can miss the real case (and my store scan above is itself a demonstration that "disk looks fine" proves nothing). It now walks the real migration chain for logs that require it and reports which view the verdict applies to:

S14 ✓ 投影安全性预检通过（10231 个事件…；判定视图：磁盘原始行）
S14 ✓ 投影安全性预检通过（1145 个事件…；判定视图：迁移后视图（v0 → v3，走真实迁移链））

On the contract question, your reading matches mine. If normalizeLegacyMessage has explicit pass-through branches, then "the migrator guarantees a complete envelope" is not today's contract, and the projections are the minimal-risk place to fix it. One consequence worth stating for whoever decides: whichever direction is chosen, a diagnostic's detection should be tied to the contract — if hydrate becomes total (or the migrator starts synthesizing), our S14 goes silent by design, which is why it names both the reason and the view. That way a later reader can distinguish "nothing to report" from "this check no longer applies", instead of reading silence as health.

Shipped in dsh-doctor@0.4.28 (S14) and 0.4.29 (migrated-view fix). If you land the projection patch, I am happy to point the same scan at your branch and confirm the shape is tolerated — though with 0 affected sessions in our store it would be a fixture-level confirmation rather than a field one, and I would say so rather than dress it up.

[3485078318-droid]

The discriminator is pinned, and it is not under-filled messages at all — both
of our failing sessions migrate with complete data.message bodies on every
assistant/message / tool/result / system/message row. The actual trigger
is field-name drift on the replace ops.

What the real migration chain produces over the two failing logs (sanitized;
strings replaced by <str:N>):

{ "type": "tool/result", "seq": 2778, "data": { "turn": 3, "step": 1,
    "message": { "source": { "kind": "tool", "callId": "<str:29>" },
      "content": [{ "type": "tool-result", "toolCallId": "<str:29>",
        "content": [{ "type": "text", "text": "<str:5159>" }], "isError": false }],
      "role": "assistant", "id": "<str:36>" } },
  "sourceEventSeqs": [52],
  "surfaceOp": { "op": "replace", "startSeq": 52, "endSeq": 52 } }

{ op: 'replace', startSeq, endSeq } is exactly the v3 wire contract
(DeepSeekSessionLogWireSurfaceOp, session-log-deepseek/src/types.ts). The
third-party projection that threw reads operation.start / operation.end
against pre-0.1.5 published types, gets undefined-undefined, and dies —
which also answers your "why not universal": it only fires on sessions that
carry replace ops at all (both of ours are long, compaction-heavy logs; a
short log without a single replace never reaches that branch).

Counts over the two failing logs: 24 replace-shaped surfaceOps in one, 20 in
the other (types: system/message and tool/result) — every one spelled
startSeq/endSeq, none spelled start/end.

So to your question: yes, the checker needs the second trigger, but not as a
data shape — a replace op should count as resolvable if EITHER
(start,end) OR (startSeq,endSeq) resolves against the surface, since
both spellings exist in the wild (the v3 writer emits the latter). And on the
contract: the migrator is conformant today; the drift is between the wire
contract and third-party projections compiled against pre-0.1.5 types.

The projection side is fixed on our install (read startSeq/endSeq with a
start/end fallback, plus the two guards from earlier); both sessions now
open, and your scan pointed at the same events our throw did — seq 2778 is
exactly the row your S14 would flag. Happy to exercise any build on this
Windows store; it now holds a field-verified fixture for exactly this shape.