Tianyi Cui
a3cb678875
Integrate the observed master checkpoint 7ab215e23e5d977aae7eb5d4fb91782d39969dbb without rewriting the earlier published checkpoints. Master adds current-directory events, directory-aware consumers, and retained Git worktrees; its old subagent startup paths overlapped the unified activation implementation. Resolve directory selection within managed startup after acquiring parent ownership. Preserve the original Session origin while setting each new local child directory, retain persisted directory state on cold resume, and pass a required absolute cwd to external providers. Keep unified local/external ownership, full completion notices, parked-input host completion, SDK wait/error/shutdown behavior, and ACP cancellation semantics. Retain removal of the old in-process driver and continuation managers. Combine SDK wait with the new directory requests, preserve the new master directory/worktree fixtures, regenerate derived catalogs from the combined sources, and refresh only the four stale prompt/schema sidecars. Preserve every protected historical schema, archived note, catalog-v2 acknowledgement, and recorded predecessor input. Validation: full build; 59 CI static gates; 855 subagent tests with 100% coverage on changed core/external sources; affected consumer suites including 119 repaired-fixture tests; SDK 11 and headless 16 recorded scenarios; two local headless expected cases; six built nested SDK/ACP cases; lint, strict cast inventory, workspace constraints, and whitespace checks. Native Windows worker diagnostics remain additive and require the next CI run to classify the original crash.
5.3 KiB
description
| description |
|---|
| Find the complete declared persistence types for every Session format from V0 through the checkout writer. |
Session persistence formats
English | 中文
Summary
Use this reference to inspect a stored Session generation’s headers, event envelopes, and payload types. Every format below the checkout writer has a bilingual document and a complete schema snapshot. The current format uses the generated persistence catalog. The version authority owns the writer constant and release status.
Table of Contents
Format references
The index is generated from validated snapshots and the current writer constant. Each historical reference identifies its source checkpoint; a Session format number does not identify every event payload revision within that format.
| Format | Source | Reference | Machine schema | Roots / types |
|---|---|---|---|---|
| 0 | dsh-v0.1.2-rc.1 |
V0 | JSON | 54 / 415 |
| 1 | PR #3349 | V1 | JSON | 54 / 415 |
| 2 | dsh-v0.1.3-alpha.2 |
V2 | JSON | 56 / 435 |
| 3 | PR #4320 | V3 | JSON | 60 / 467 |
| 4 | Current checkout | Current catalog | JSON | 63 / 597 |
Scope and evidence
Each vN.md / vN.zh.md pair has kind: persistence-format, an identical yaml persistence-format declaration binding every root key to its captured digest, a pairing sidecar, and a complete vN.schema.json. The template defines these records. Roots cover the logical Session header, physical JSONL header, event envelope, and all first-party events at the selected checkpoint; each root includes every reachable declared type. Packed physical body records have separate codec owners linked from each page.
V0 and V2 use the latest matching tags in the captured prerelease archive. V1 uses an intermediate source tree identified in its reference because the captured tags contain no V1 writer. V3 captures the verified inventory before the V4 writer change in PR #4320. Historical sources retain file paths without line numbers. Snapshots preserve historical optional fields and opaque values; they do not substitute current types into older formats. Historical identifiers remain intact only in schema JSON and the verified generated schema regions; authored prose follows current terminology rules.
These references describe selected schemas, not historical application replay or migration safety. Same-version event additions and optional payload changes can produce other valid inventories. The prerelease archive retains tag-by-tag differences; change records retain current compatibility acknowledgements. Neither history is replaced by these format snapshots.
Maintain coverage
verify-persistence-formats derives the required integer range from SESSION_FORMAT_VERSION. Every older integer needs its own complete record. The current catalog and schema must exist and match the writer version. The check rejects missing, extra, misnumbered, incomplete, or inconsistent records and stale generated regions without fetching Git history or querying a service.
Before advancing the writer, verify the current catalog and archive the outgoing format. For a V3-to-V4 change, run these commands while the writer and current schema still describe V3:
pnpm run verify-persistence-catalog
pnpm run verify-persistence-formats --archive 3
Replace 3 with the outgoing writer version for other transitions. --archive N creates vN.schema.json from the current inventory, retains exactly the types reachable from its roots, and removes source line numbers. It refuses an existing destination, a version other than the current writer, invalid or incomplete schemas, and combination with --write. Add the snapshot’s bilingual record and source evidence using the template. Retain all earlier records. The successor uses the current catalog; copying a new current catalog cannot satisfy the archived predecessor requirement. Follow the format-version cookbook for runtime changes.
The schema definitions and index inside comment markers are generated. After advancing the writer and completing the machine data and authored evidence, refresh their tables and pairing records, then verify:
pnpm run verify-persistence-formats --write
pnpm run verify-persistence-formats
pnpm run doc-sync
--write validates the machine data before updating generated Markdown and pairing records. It preserves authored explanations, machine declarations, and schemas. Default verification also rejects stale pairing records; the standard documentation checks validate translations and local links. Current catalog freshness remains owned by verify-persistence-catalog.
Dev Note
None.