Tianyi Cui
bf29247fad
V3 permits external event, source and content identities and additional request-tool fields. Copying those values into V4 can give an old plugin named tool a core source identity, turn old tool-addition content into a registry instruction, or activate formerly ignored deferLoading and delivery metadata. Rejecting such collisions would instead refuse valid source logs. Keep historical extensions in the existing extensible JSON representation. Prefix unknown content and ignorable event tags with plugin:, preserving all other content fields and opaque event payloads. Prefix external source identities with plugin:plugin: or plugin:source: so wrapper and direct kinds cannot collide even when original names already contain a category prefix. Known first-party mappings remain explicit and unchanged. Prefix extra request-tool field names and block-start field names with plugin:, retaining exact values and existing-prefix doubling. Core schema parameters, arguments, replay state and nested plugin data are not traversed. Keep future-generation delivery records inactive after header promotion. Pin the V3 event vocabulary independently of the current writer and provide an offline verifier against an explicitly selected historical source commit. Attachment authorization and export inspect declared event content only. Team checkpoints preserve all own keys of unknown JSON blocks while still rejecting malformed known content and retired core tool-result blocks. Exercise physical read/write/reopen, prefix injectivity, own __proto__ keys, provider opacity and retained source-identity snapshots. No generic extension block, metadata wrapper or new schema-tooling type is introduced. V4 type declarations, persistence schema, checkpoint and frozen V0-V3 codecs remain unchanged. Canonical tool-result lifting and incomplete child-catalog policy remain separate concerns. Adapted from the extension-preservation work in 7ba7e174dd1 by Tianyi Cui. Co-authored-by: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
5.7 KiB
Session format version and release status
English | 中文
Summary
Use this reference to distinguish the checkout writer, the accepted compatibility baseline, and the latest published Session format. The code constant owns the writer; the finalization and release records below separately identify accepted history and publication evidence. Other documentation links here instead of restating those values.
Table of Contents
Sources of truth
- Checkout writer:
SESSION_FORMAT_VERSIONin core Session types is the only hand-maintained current-writer number in code. The catalog generator derives codec ordering and checks that adjacent migrations reach it. A package version, codec export name, fixture filename, or projection-cache version is not the writer authority. - Latest released format:
latestReleasedVersionin the following record identifies the published Session format.evidenceTagnames a published product release whose tagged writer has that value; it need not be the first release carrying the format. The bilingual copy is checked against the same record, not maintained as a separate decision. - Release status: compare the writer constant with the verified release record. Equality means the writer format has shipped. A greater writer version is not yet recorded as published; its finalization record independently identifies the accepted compatibility baseline. When comparing an older checkout against a newer branch’s verified record, a lower writer version identifies an older writer format; the local consistency gate rejects that ordering within one checkout. No separate released boolean is maintained. Before declaring a greater version unreleased, verify that no published release has advanced the record.
An alpha, beta, or release-candidate product publication establishes released Session-format obligations. GitHub’s prerelease flag does not make persisted user data disposable. A missing release record is not evidence of non-publication. The versioning and authority decision owns compatibility decisions; released-format migration owns immutable generations and adjacent conversion.
The format references document every integer from zero through the checkout writer, with historical schemas and the existing current catalog.
Finalization record
latestFinalizedVersion: 4
V4 has an accepted compatibility baseline in the checkpoint. Backward-compatible schema changes may remain V4 through new acknowledgement records. Breaking changes require a higher writer version and their own header transition; they cannot reuse the accepted 3→4 transition. Accepted machine records and after schemas remain immutable. Checkpoint rules define the comparison.
Finalization does not freeze every future V4 addition and does not assert publication. The release record below retains the independently verified published version. Ordinary comments, aliases, source locations, and implementation fixes preserving the accepted meaning do not change this baseline.
Before the first V4 publication, every integration of a newer V3-writing master must pass the explicit V3 vocabulary check against the recorded local source commit. Verify the source pin’s freshness and review new event payload conversions before updating the migration-owned set. After publication, the final V3 vocabulary remains historical and independent of current V4 additions.
Release record
latestReleasedVersion: 3
evidenceTag: dsh-v0.1.5-alpha.1
Evidence: published product tag dsh-v0.1.5-alpha.1; tagged writer: packages/core/session/src/types.ts.
Updating the record
When a structural writer change is implemented, update the code constant and adjacent catalog together; do not advance this release record before publication. When a product release first publishes a higher Session format, confirm publication and its tagged writer, then advance this record and the evidence tag and tagged writer path in the same bilingual update. Later product releases carrying the same format do not require changing the record. Never lower it on the development trunk.
The documentation-standard test checks record structure, bilingual equality, evidence-tag and writer-path consistency, and that the documented release does not exceed the checkout writer. This keyless check does not query GitHub or prove that the record is up to date; publication verification remains part of the release update.
Use “current format” and “next adjacent version” for general behavior. Keep explicit numbers for fixed migration inputs and outputs, wire schemas, historical evidence, and tests of those particular versions. The format-version cookbook uses N for the latest finalized or released format and N+1 for its successor.
Dev Note
None.