@deepseek-ai/dsh-session 0.0.1-rc.1 → 0.0.1-rc.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/session/README.md
-README.md: db477d94037d3463870fc8e66ea35d5e607fb6fe
-README.zh.md: 1ce1e823a7e0fdbcf7b6898764a89c52b74adf6a
+README.md: 57569e9c0dbfa7cb696e3a561a9ff108c2ac981f
+README.zh.md: 16629dc70c79ca838ba7088aeafcc5b38b124f87

package/README.md

@@ -76,10 +76,11 @@ Also defines `TurnEndReasonMap`, the merge-extensible `kind`-tagged sum type for
 
 An interrupted live turn ends with `{ kind: 'aborted', reason: AgentCancelCause }`, preserving the typed cancellation cause in the durable transcript. Persistence imports the coarse aborted outcome from the supported older format as `{ kind: 'aborted', reason: { kind: 'legacy' } }`, because that record did not retain its caller. A turn failure carries `{ kind: 'error', error }`; crash recovery alone synthesizes `{ kind: 'interrupted' }`.
 
-Every `SessionEvent` carries two optional top-level fields (structural metadata):
+Every `SessionEvent` carries three optional top-level fields (structural metadata):
 
 - `sourceEventSeqs?: number[]` — seq numbers of earlier events cited as sources (e.g., the `assistant/chunk` seqs behind an `assistant/message`, or the shadowed entries behind a compaction replacement entry). On `assistant/message`, a present `[]` records a known empty provider stream, while omission means a legacy or foreign event did not record the source stream; other surface events require a non-empty list when this field is present.
 - `surfaceOp?: SurfaceOp` — how this event entered the surface. Absent for non-surface events (boundaries, chunks, usage, errors).
+- `ignorable?: true` — marks an event a reader may safely skip when it does not recognize the type; absent means required, so an unknown-type event refuses session reconstruction ([mechanism](../../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)).
 
 ### Metadata types (`types.ts`)
 
@@ -139,5 +140,5 @@ Logging causes no invalidation, and exact reconstruction preserves request-prefi
 
 - **Session branching/tree** (pi-style entry tree) — deferred unless needed beyond boundary-based `fork()`.
 - **`fork()` cuts only at stable boundaries of live sessions** — the selected prefix must end outside an open turn and the source must be in the store; forking a persisted-but-unloaded session is excluded from the [fork API](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md).
-- **`SESSION_FORMAT_VERSION` stays pinned at `0`** — pre-release, no broad compatibility implied: `Session` accepts only current seed shapes and a backend rejects any other version. Narrow storage import upgrades belong to the persistence boundary ([policy](../../../AGENTS.md), [pre-identity message recovery](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)).
+- **`SESSION_FORMAT_VERSION` stays pinned at `0`** — pre-release, no broad compatibility implied: `Session` accepts only current seed shapes, and a backend refuses any other version naming the direction (newer: "written by a newer harness — upgrade"; older: no upgrade path ships yet). Unknown event types refuse the same way unless marked `ignorable` in the envelope; the versioning mechanism is the [session-log-version-mechanism note](../../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md). Narrow storage import upgrades belong to the persistence boundary ([policy](../../../AGENTS.md), [pre-identity message recovery](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)).
 - **`TurnEndReasonMap` omits the ACP-named `refusal` / `max_turn_requests` variants** — producer-gated: they land when an adapter or the loop first emits them.

package/README.zh.md

@@ -76,10 +76,11 @@
 
 被中断的实时轮次以 `{ kind: 'aborted', reason: AgentCancelCause }` 结束，在持久 transcript（文本记录）中保留类型化取消原因。持久化会将受支持旧格式中的粗粒度中止结果导入为 `{ kind: 'aborted', reason: { kind: 'legacy' } }`，因为该记录没有保留调用方。轮次失败携带 `{ kind: 'error', error }`；只有崩溃恢复会合成 `{ kind: 'interrupted' }`。
 
-每个 `SessionEvent` 都有两个可选顶层字段（结构元数据）：
+每个 `SessionEvent` 都有三个可选顶层字段（结构元数据）：
 
 - `sourceEventSeqs?: number[]`：被引用为来源的较早事件 seq（例如 `assistant/message` 引用的 `assistant/chunk` seq，或压缩替换条目引用的已遮蔽条目）。对于 `assistant/message`，存在的 `[]` 表示已知提供方流为空；省略则表示旧版或外部事件没有记录源流。其他 surface 事件若有此字段，则要求非空列表。
 - `surfaceOp?: SurfaceOp`：事件进入 surface 的方式。非 surface 事件（边界、分片、用量、错误）不含该字段。
+- `ignorable?: true`：标记读取器在不认识事件类型时可以安全跳过该事件；缺失表示必需，不认识的事件类型会使会话重建被拒绝（[机制](../../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)）。
 
 ### 元数据类型（`types.ts`）
 
@@ -139,5 +140,5 @@
 
 - **会话分支／树**（pi 风格条目树）：除非需要超越基于边界的 `fork()` 能力，否则暂缓。
 - **`fork()` 仅在实时会话的稳定边界处切分**：所选前缀结束时不得有开放轮次，且源会话必须位于存储中；[fork API](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) 不支持对已持久化但未加载的会话进行 fork。
-- **`SESSION_FORMAT_VERSION` 固定为 `0`**：预发布阶段不承诺广泛兼容性；`Session` 只接受当前 seed 形状，后端会拒绝其他任何版本。范围受限的存储导入升级应由持久化边界负责（[政策](../../../AGENTS.md)、[消息标识机制引入前的消息恢复](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。
+- **`SESSION_FORMAT_VERSION` 固定为 `0`**：预发布阶段不承诺广泛兼容性；`Session` 只接受当前 seed 形状，后端拒绝其他任何版本并说明方向（更新的版本提示"由更新的 harness 写入，请升级"；更旧的版本说明尚无升级路径）。不认识的事件类型同样被拒绝，除非信封带 `ignorable` 标记；版本机制见 [session-log 版本机制 Agent Note](../../../.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md)。范围受限的存储导入升级应由持久化边界负责（[政策](../../../AGENTS.md)、[消息标识机制引入前的消息恢复](../../../.agents/notes/implemented/bug-fix/2026-07-28-load-pre-identity-session-messages.md)）。
 - **`TurnEndReasonMap` 不含 ACP（Agent Client Protocol）命名的 `refusal`／`max_turn_requests` 变体**：受生产方约束；只有当适配器或循环首次产生这些变体时才加入。

package/lib/index.js

@@ -16,8 +16,23 @@ function SessionId(id) {
 * and enforced by every persistence backend on load. The single source of truth for the
 * version — write sites and the load-time check all read it.
 * While the harness is unreleased it is pinned at `0`: no compatibility is
-* implied, incompatible logs are rejected, and no migration is provided. A
-* monotonic version policy starts with the first tagged release.
+* implied, incompatible logs are rejected, and no migration is provided.
+*
+* The version is a single monotonic integer with no major/minor split. Whether
+* a bump is needed is decided by what the WRITER emits, never by what a newer
+* reader can accept: bump exactly when an older runtime could no longer handle
+* a new log with full semantic correctness ("parses without error" is not
+* correctness — silently skipping content that shapes reconstruction is a
+* wrong read). Only structural changes reach that bar: the header shape, the
+* {@link SessionEvent} envelope, core event semantics, or the surface
+* mechanism (the {@link SurfaceEventType} set and {@link SurfaceOp} variants).
+* Adding an ordinary event type does not bump — the per-event
+* {@link SessionEvent.ignorable} guard covers vocabulary growth instead. When
+* in doubt, bump: a near-identity upgrade step is almost free, a missed bump
+* makes older runtimes read new logs wrong silently. The full mechanism
+* (upgrade-step chain, in-memory view conversion, migrate-on-continue) is
+* recorded in the session-log-version-mechanism Agent Note
+* (`.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md`).
 */
 const SESSION_FORMAT_VERSION = 0;
 //#endregion
@@ -1036,6 +1051,71 @@ function decodeStorageRecord(value) {
 	return expandRow(validateRow(value, tag));
 }
 //#endregion
+//#region lib/types/known-event-types.js
+/**
+* GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
+* `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
+* `pnpm run verify-persistence-catalog`, part of `doc-sync`).
+* @module @deepseek-ai/dsh-session/known-event-types
+*/
+/**
+* Every `SessionEventMap` member declared in this repository — the event
+* vocabulary this build understands. The persistence read path refuses to
+* interpret a log containing a type outside this set unless the event
+* carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
+* in `./types.ts`): such a log was likely written by a newer harness, and
+* silently skipping a required event would reconstruct a wrong session.
+* Downstream (out-of-repo) plugin events are outside this list by
+* construction; a registration surface for them is deferred until such a
+* consumer exists.
+*/
+const KNOWN_SESSION_EVENT_TYPES = new Set([
+	"agent-preset/selected",
+	"agent/inbox/spliced",
+	"approval/asked",
+	"approval/decided",
+	"approval/policy",
+	"assistant/chunk",
+	"assistant/message",
+	"command/done",
+	"command/run",
+	"compact/end",
+	"compact/prune",
+	"compact/start",
+	"compact/summary",
+	"feedback/record",
+	"goal/change",
+	"hook/invoked",
+	"hook/result",
+	"llm/retry",
+	"llm/retry-started",
+	"permission/preset",
+	"plan/mode",
+	"request/context",
+	"request/header",
+	"sandbox/mode",
+	"schedule/change",
+	"session/end-seed",
+	"session/title",
+	"session/title-llm-request",
+	"step/end",
+	"step/start",
+	"subagent/descriptor",
+	"todo/write",
+	"tool-workflow/agent-end",
+	"tool-workflow/agent-start",
+	"tool-workflow/run-end",
+	"tool-workflow/run-start",
+	"tool/call",
+	"tool/code-dispatch",
+	"tool/code-dispatch-start",
+	"tool/result",
+	"turn/end",
+	"turn/start",
+	"user/message",
+	"web/deepseek-search-llm-request"
+]);
+//#endregion
 //#region lib/types/index.js
 /**
 * Event-sourced session service: append-only session log, in-memory store, and
@@ -1044,24 +1124,6 @@ function decodeStorageRecord(value) {
 *
 * @module @deepseek-ai/dsh-session
 */
-/**
-* Find the latest closed turn that entered at least one model step, ignoring
-* balanced no-step turns produced by rejection, empty input, or cancellation.
-* @param events - session events, or an owned suffix, to inspect.
-* @returns the latest matching turn end, or `undefined`.
-*/
-function findLastMessageTurnEnd(events) {
-	const steppedTurns = /* @__PURE__ */ new Set();
-	let latest;
-	for (const event of events) {
-		if (event.type === "step/start") {
-			steppedTurns.add(event.data.turn);
-			continue;
-		}
-		if (event.type === "turn/end" && steppedTurns.delete(event.data.turn)) latest = event;
-	}
-	return latest;
-}
 /** Validate and freeze one detached creation header in place. */
 function validateSessionHeader(id, input) {
 	if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error("session header is not a plain JSON record");
@@ -1151,13 +1213,14 @@ function assertSessionEventEnvelope(value, index) {
 		case "time":
 		case "data":
 		case "surfaceOp":
-		case "sourceEventSeqs": break;
+		case "sourceEventSeqs":
+		case "ignorable": break;
 		default: throw new Error(`seed event at index ${index} has an invalid event envelope`);
 	}
 	const type = event["type"];
 	const seq = event["seq"];
 	const time = event["time"];
-	if (typeof type !== "string" || typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0 || typeof time !== "number" || !Number.isSafeInteger(time) || event["data"] === void 0) throw new Error(`seed event at index ${index} has an invalid event envelope`);
+	if (typeof type !== "string" || typeof seq !== "number" || !Number.isSafeInteger(seq) || seq < 0 || typeof time !== "number" || !Number.isSafeInteger(time) || event["data"] === void 0 || event["ignorable"] !== void 0 && event["ignorable"] !== true) throw new Error(`seed event at index ${index} has an invalid event envelope`);
 	switch (type) {
 		case "request/header":
 		case "user/message":
@@ -1838,4 +1901,4 @@ var SessionStore = class extends Service {
 	}
 };
 //#endregion
-export { SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionPreparation, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, adoptSessionEvent, canonicalHeader, decodeStorageRecord, deriveEventMessage, findLastMessageTurnEnd, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isJsonValue, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, lastActivityTime, packChunkRuns, snapshotJsonValue, snapshotSessionEvent };
+export { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionPreparation, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, adoptSessionEvent, canonicalHeader, decodeStorageRecord, deriveEventMessage, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isJsonValue, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, lastActivityTime, packChunkRuns, snapshotJsonValue, snapshotSessionEvent };

package/lib/types/index.d.ts

@@ -24,13 +24,7 @@ export type { ChunkRow, StorageRecord } from './chunk-rows.ts';
 export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts';
 export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts';
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts';
-/**
- * Find the latest closed turn that entered at least one model step, ignoring
- * balanced no-step turns produced by rejection, empty input, or cancellation.
- * @param events - session events, or an owned suffix, to inspect.
- * @returns the latest matching turn end, or `undefined`.
- */
-export declare function findLastMessageTurnEnd(events: readonly SessionEvent[]): SessionEvent<'turn/end'> | undefined;
+export { KNOWN_SESSION_EVENT_TYPES } from './known-event-types.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         sessions: SessionStore;

package/lib/types/index.js

@@ -20,25 +20,7 @@ export { interruptedTurnClosers, lastActivityTime, TOOL_NOT_STARTED, TOOL_OUTCOM
 export { decodeStorageRecord, packChunkRuns } from "./chunk-rows.js";
 export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from "./surface.js";
 export { canonicalHeader, foldRequestHeader, headerEquals } from "./request-header.js";
-/**
- * Find the latest closed turn that entered at least one model step, ignoring
- * balanced no-step turns produced by rejection, empty input, or cancellation.
- * @param events - session events, or an owned suffix, to inspect.
- * @returns the latest matching turn end, or `undefined`.
- */
-export function findLastMessageTurnEnd(events) {
-    const steppedTurns = new Set();
-    let latest;
-    for (const event of events) {
-        if (event.type === 'step/start') {
-            steppedTurns.add(event.data.turn);
-            continue;
-        }
-        if (event.type === 'turn/end' && steppedTurns.delete(event.data.turn))
-            latest = event;
-    }
-    return latest;
-}
+export { KNOWN_SESSION_EVENT_TYPES } from "./known-event-types.js";
 /** Validate and freeze one detached creation header in place. */
 function validateSessionHeader(id, input) {
     if (input === null || typeof input !== 'object' || Array.isArray(input)) {
@@ -164,6 +146,7 @@ function assertSessionEventEnvelope(value, index) {
             case 'data':
             case 'surfaceOp':
             case 'sourceEventSeqs':
+            case 'ignorable':
                 break;
             default:
                 throw new Error(`seed event at index ${index} has an invalid event envelope`);
@@ -175,7 +158,8 @@ function assertSessionEventEnvelope(value, index) {
     if (typeof type !== 'string'
         || typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0
         || typeof time !== 'number' || !Number.isSafeInteger(time)
-        || event['data'] === undefined) {
+        || event['data'] === undefined
+        || (event['ignorable'] !== undefined && event['ignorable'] !== true)) {
         throw new Error(`seed event at index ${index} has an invalid event envelope`);
     }
     switch (type) {

package/lib/types/known-event-types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
+ * `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
+ * `pnpm run verify-persistence-catalog`, part of `doc-sync`).
+ * @module @deepseek-ai/dsh-session/known-event-types
+ */
+/**
+ * Every `SessionEventMap` member declared in this repository — the event
+ * vocabulary this build understands. The persistence read path refuses to
+ * interpret a log containing a type outside this set unless the event
+ * carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
+ * in `./types.ts`): such a log was likely written by a newer harness, and
+ * silently skipping a required event would reconstruct a wrong session.
+ * Downstream (out-of-repo) plugin events are outside this list by
+ * construction; a registration surface for them is deferred until such a
+ * consumer exists.
+ */
+export declare const KNOWN_SESSION_EVENT_TYPES: ReadonlySet<string>;
+//# sourceMappingURL=known-event-types.d.ts.map

package/lib/types/known-event-types.js

@@ -0,0 +1,64 @@
+/**
+ * GENERATED by `scripts/gen-persistence-catalog.ts` — do not edit by hand; run
+ * `pnpm run gen-persistence-catalog` to regenerate (verified fresh by
+ * `pnpm run verify-persistence-catalog`, part of `doc-sync`).
+ * @module @deepseek-ai/dsh-session/known-event-types
+ */
+/**
+ * Every `SessionEventMap` member declared in this repository — the event
+ * vocabulary this build understands. The persistence read path refuses to
+ * interpret a log containing a type outside this set unless the event
+ * carries the envelope's `ignorable` marker (see `SessionEvent.ignorable`
+ * in `./types.ts`): such a log was likely written by a newer harness, and
+ * silently skipping a required event would reconstruct a wrong session.
+ * Downstream (out-of-repo) plugin events are outside this list by
+ * construction; a registration surface for them is deferred until such a
+ * consumer exists.
+ */
+export const KNOWN_SESSION_EVENT_TYPES = new Set([
+    'agent-preset/selected',
+    'agent/inbox/spliced',
+    'approval/asked',
+    'approval/decided',
+    'approval/policy',
+    'assistant/chunk',
+    'assistant/message',
+    'command/done',
+    'command/run',
+    'compact/end',
+    'compact/prune',
+    'compact/start',
+    'compact/summary',
+    'feedback/record',
+    'goal/change',
+    'hook/invoked',
+    'hook/result',
+    'llm/retry',
+    'llm/retry-started',
+    'permission/preset',
+    'plan/mode',
+    'request/context',
+    'request/header',
+    'sandbox/mode',
+    'schedule/change',
+    'session/end-seed',
+    'session/title',
+    'session/title-llm-request',
+    'step/end',
+    'step/start',
+    'subagent/descriptor',
+    'todo/write',
+    'tool-workflow/agent-end',
+    'tool-workflow/agent-start',
+    'tool-workflow/run-end',
+    'tool-workflow/run-start',
+    'tool/call',
+    'tool/code-dispatch',
+    'tool/code-dispatch-start',
+    'tool/result',
+    'turn/end',
+    'turn/start',
+    'user/message',
+    'web/deepseek-search-llm-request',
+]);
+//# sourceMappingURL=known-event-types.js.map

package/lib/types/types.d.ts

@@ -1,6 +1,7 @@
 import type { Branded } from '@deepseek-ai/dsh-brand';
 import type { AssistantMessage, CallId, LlmCallConfig, LlmCallConfigAdapterDefaults, LlmFailure, StreamChunk, TokenUsage, ToolResultMessage, ToolSchema, UserMessage } from '@deepseek-ai/dsh-llm';
 import type { JsonValue } from './json.ts';
+export type { JsonValue } from './json.ts';
 /** Identifies one session in the store (and its persistence artifacts). */
 export type SessionId = Branded<'SessionId'>;
 /**
@@ -14,8 +15,23 @@ export declare function SessionId(id: string): SessionId;
  * and enforced by every persistence backend on load. The single source of truth for the
  * version — write sites and the load-time check all read it.
  * While the harness is unreleased it is pinned at `0`: no compatibility is
- * implied, incompatible logs are rejected, and no migration is provided. A
- * monotonic version policy starts with the first tagged release.
+ * implied, incompatible logs are rejected, and no migration is provided.
+ *
+ * The version is a single monotonic integer with no major/minor split. Whether
+ * a bump is needed is decided by what the WRITER emits, never by what a newer
+ * reader can accept: bump exactly when an older runtime could no longer handle
+ * a new log with full semantic correctness ("parses without error" is not
+ * correctness — silently skipping content that shapes reconstruction is a
+ * wrong read). Only structural changes reach that bar: the header shape, the
+ * {@link SessionEvent} envelope, core event semantics, or the surface
+ * mechanism (the {@link SurfaceEventType} set and {@link SurfaceOp} variants).
+ * Adding an ordinary event type does not bump — the per-event
+ * {@link SessionEvent.ignorable} guard covers vocabulary growth instead. When
+ * in doubt, bump: a near-identity upgrade step is almost free, a missed bump
+ * makes older runtimes read new logs wrong silently. The full mechanism
+ * (upgrade-step chain, in-memory view conversion, migrate-on-continue) is
+ * recorded in the session-log-version-mechanism Agent Note
+ * (`.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md`).
  */
 export declare const SESSION_FORMAT_VERSION = 0;
 /**
@@ -409,6 +425,17 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
         /** Unix epoch milliseconds. */
         time: number;
         data: SessionEventMap[K];
+        /**
+         * Marks an event a reader may safely skip when it does not recognize
+         * `type`. Absent means required: a reader meeting an unrecognized type
+         * without this marker MUST refuse to reconstruct the session instead of
+         * silently dropping the event, because an unrecognized required event may
+         * change how the rest of the log is interpreted. A writer sets `true` only
+         * on purely informational records whose loss cannot affect reconstruction;
+         * defaulting to required means a forgotten marker over-refuses (an
+         * inconvenience) rather than silently resuming a gutted session.
+         */
+        ignorable?: true;
     } & (K extends SurfaceEventType ? {
         /**
          * Seq numbers of earlier events that this event cites as sources

package/lib/types/types.js

@@ -11,8 +11,23 @@ export function SessionId(id) {
  * and enforced by every persistence backend on load. The single source of truth for the
  * version — write sites and the load-time check all read it.
  * While the harness is unreleased it is pinned at `0`: no compatibility is
- * implied, incompatible logs are rejected, and no migration is provided. A
- * monotonic version policy starts with the first tagged release.
+ * implied, incompatible logs are rejected, and no migration is provided.
+ *
+ * The version is a single monotonic integer with no major/minor split. Whether
+ * a bump is needed is decided by what the WRITER emits, never by what a newer
+ * reader can accept: bump exactly when an older runtime could no longer handle
+ * a new log with full semantic correctness ("parses without error" is not
+ * correctness — silently skipping content that shapes reconstruction is a
+ * wrong read). Only structural changes reach that bar: the header shape, the
+ * {@link SessionEvent} envelope, core event semantics, or the surface
+ * mechanism (the {@link SurfaceEventType} set and {@link SurfaceOp} variants).
+ * Adding an ordinary event type does not bump — the per-event
+ * {@link SessionEvent.ignorable} guard covers vocabulary growth instead. When
+ * in doubt, bump: a near-identity upgrade step is almost free, a missed bump
+ * makes older runtimes read new logs wrong silently. The full mechanism
+ * (upgrade-step chain, in-memory view conversion, migrate-on-continue) is
+ * recorded in the session-log-version-mechanism Agent Note
+ * (`.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md`).
  */
 export const SESSION_FORMAT_VERSION = 0;
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session",
   "description": "Event-sourced session store for the DeepSeek Harness",
-  "version": "0.0.1-rc.1",
+  "version": "0.0.1-rc.2",
   "publishConfig": {
     "access": "restricted"
   },
@@ -41,20 +41,20 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-scope": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-type-meta": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-type-meta": "^0.0.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-type-meta": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-typert-registry": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-scope": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-type-meta": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-typert-registry": "^0.0.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   }
 }