Files
deepseek-harness/packages/session
Tianyi Cui 11ef33b336 fix(session): reject unknown required V3 events before target interpretation
The physical V3 codec admits an unclassified event envelope without deciding
whether its type is required. The V3-to-V4 stage then used shared message
walkers and target vocabulary, so an invalid required developer/message could
acquire the V4 developer role although historical V3 restoration rejects it.
Generic required unknown events were also left to the wrong version's reader.

After preserving explicitly ignorable extensions, require every remaining
source type to belong to the fixed V3 vocabulary before interpreting payloads.
This is a fail-loud check for invalid or nonconforming source data, not new
compatibility handling for third-party events, which carry ignorable:true.
The approved plugin identifier conversion and native V4 readers are unchanged.

Exercise a complete developer-event sequence through direct migration,
historical/current catalogs, ignorable conversion and native V4 restoration;
add a generic unknown type. Both negative controls accepted the invalid source
before this guard. Plain/zstd read/write regressions verify refusal preserves
the source generation and never publishes a partial V4 successor.
2026-09-19 15:43:10 +08:00
..
2026-09-17 21:11:19 +08:00

description, kind
description kind
Package map for the durable session data plane: the persistence seam and its backends, checkpoint policy, projections, log-backed titles, and outbound session telemetry. package-group

session/ — durable session data plane

English | 中文

Summary

The session group keeps conversations durable, restores released log formats, and makes committed history available after restart. Its storage and checkpoint packages protect requests, tool side effects, and completed steps; projection packages derive client-ready values; title packages name sessions; telemetry packages report activity. Start with the shipped JSONL storage, then add checkpointing and only the projections, title policy, or telemetry your deployment needs. Each package README owns its guarantees and configuration, while a sibling query group provides independent read and tool access.

Table of Contents


Packages

The group splits into four families: durable storage (persistence seam, backends, checkpoint policy), projections, titles, and telemetry. Each package README owns its contract and configuration.

Persistence

Package Role ctx key
session-format/ Pure adjacent-format chain and artifact validation library library — no ctx key
session-format-v0-to-v1/ Frozen released-v0 decoder and identity migration into released v1 library — no ctx key
session-format-v1-to-v2/ Frozen released-v1 decoder and cardinality-changing Assistant-stream migration into released v2 library — no ctx key
session-format-v2-to-v3/ Frozen V2 decoder and system-prompt, envelope, and PTC migration into V3 library — no ctx key
session-format-v3-to-v4/ V3 identity migration and V4 codec with generation-aware delivery validation library — no ctx key
session-format-catalog/ Generated static catalog of shipped adjacent migrations library — no ctx key
session-persistence/ Defines the durable session-storage service and the shared write coordination every backend composes ctx.sessionPersistence
session-persistence-jsonl/ Shipped backend: immutable canonical generation filenames per Session with exclusive successor publication, optionally Zstandard-compressed registers on ctx.sessionPersistence
session-checkpoint-policy/ Makes model requests, top-level tool side effects, and completed steps durable before the next action wraps ctx.llm and ctx.tools
session-log-deepseek/ Uploads the incremental canonical log as optional official DeepSeek request metadata contributes dsh_session_log

Projection

Package Role ctx key
session-projection/ Defines and drives projection units that fold committed events into whole current values ctx.sessionProjections
session-projection-cache/ Persists projection checkpoints so cold reads skip full log loads ctx.sessionProjectionCache
session-stats/ Serves whole-log conversation counts and wall times through the sessionStats unit registers on ctx.sessionProjections
session-turn-outline/ Serves the whole-log turn outline (turn, turn/start seq, prompt preview) through the turnOutline unit registers on ctx.sessionProjections

Titles

Package Role ctx key
session-title/ Log-backed session titles with a deterministic fallback and one optional provider ctx.sessionTitle
session-title-llm/ Shared model-backed title-generation policy for the provider packages library — no ctx key
session-title-first-prompt-llm/ Titles a session from its first eligible human message registers on ctx.sessionTitle
session-title-all-prompts-llm/ Titles a session from all eligible human messages registers on ctx.sessionTitle

Telemetry

Package Role ctx key
session-telemetry/ Captures session activity and hands records to a configured reporting backend ctx.sessionTelemetry
session-telemetry-otel/ Delivers telemetry through OpenTelemetry logs in FEEDBACK_ONLY or DISABLED mode registers on ctx.sessionTelemetry

Only one title provider may register at a time; without one, the title service keeps its deterministic fallback. The subsystem pages below are the backend-neutral references for each family.


Dev Note

None.