@deepseek-ai/dsh-session 0.1.2-alpha.3 → 0.1.2-alpha.5

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: 0d691b31c4918152ecf1092002646296c5d9984a
-README.zh.md: 2118def74c059f6637f12a9aeba20ff92a5d2363
+README.md: f5cf910854203021a619cc786dfd13705927ffc1
+README.zh.md: 385d7fd63a6e4dec9c23c9d38a352942d7dbc7f9

package/README.md

@@ -49,10 +49,18 @@ session.deriveMessages()         // the derived model history
 
 Surface events (`user/message`, `assistant/message`, `tool/result`) must declare how they join the ordered surface; raw chunks, boundaries, and other log-only events never produce a message.
 
+### Read the log
+
+`session.seq` reads the current log length without materializing an array, and `session.eventAt(seq)` reads one accepted, deeply frozen event by sequence number. `session.snapshotEvents(fromSeq?, toSeqExclusive?)` materializes a frozen, stable snapshot of a half-open range; a complete current snapshot is cached until the next append. Callers that only need a length or one event use `seq` or `eventAt()`.
+
+Session log positions use two numeric types. `SessionSeq` identifies an existing event or inclusive event watermark; `SessionLogOffset` identifies a gap, prefix length, or read boundary and may equal the event count. `SessionSeqCursor` adds the `-1` “no event yet” value, while `OptionalSessionSeq` uses `null` when absence is data. The constructors validate non-negative safe integers, and the brands disappear at runtime, so durable JSON and wire values remain ordinary numbers.
+
 ### Fork a session
 
 `ctx.sessions.fork(source, boundary?, childSessionId?)` selects source events through an inclusive `boundary` seq (default: the current last event), requires the prefix to end outside an open turn, and creates a live child session with lineage metadata. A tool-time delegation that must branch mid-turn clips to a completed prefix instead.
 
+The logical `SessionHeader.isSeeded` field reports whether fork history exists without exposing a positional integer. `Session.inheritedEventCount` retains the exact checked `SessionLogOffset`; `ownEvents()` returns events at and after that cut, and `isOwnSeq(seq)` accepts only an existing child-owned position. A low-level seeded constructor must supply an explicit `seed` and `inheritedEventCount` because the constructor seed can contain child-owned setup events after the inherited prefix.
+
 ### Flush durable state
 
 `ctx.sessions.flush(session)` dispatches the awaited durability checkpoint: every persistence listener flushes and the call settles after all of them. A producer that needs an immediate durability barrier awaits it instead of assuming the write-behind drained.
@@ -90,7 +98,7 @@ The package is built on event sourcing: a `Session` is an append-only log of typ
 
 ### Append validation
 
-Every append uses the shared iterative `snapshotJsonValue()` pass, which reads, validates, and copies each nested value once, so a stateful getter cannot supply one value to validation and another to storage. Non-lossless-JSON payloads (BigInt, cycles, sparse arrays, `-0`, exotic prototypes) are rejected at the append site, before any backend flush. Surface events additionally validate marker shape, cited source-event seqs, and complete shadowed-node coverage for replacements.
+Every append uses the shared iterative `snapshotJsonValue()` pass, which reads, validates, and copies each nested value once, so a stateful getter cannot supply one value to validation and another to storage. Non-lossless-JSON payloads (BigInt, cycles, sparse arrays, `-0`, exotic prototypes) are rejected at the append site, before any backend flush. The append path constructs each `SessionSeq`; surface events additionally validate marker shape, cited source-event sequences, and complete shadowed-node coverage for replacements.
 
 ### Derived history
 

package/README.zh.md

@@ -49,10 +49,18 @@ session.deriveMessages()         // the derived model history
 
 表层事件（`user/message`、`assistant/message`、`tool/result`）必须声明如何进入有序 surface；原始分片、边界与其他仅日志事件从不产生消息。
 
+### 读取日志
+
+`session.seq` 无需物化数组即可读取当前日志长度，`session.eventAt(seq)` 按序列号读取单个已接受且深度冻结的事件。`session.snapshotEvents(fromSeq?, toSeqExclusive?)` 会物化半开区间的冻结稳定快照；当前完整快照会缓存到下一次追加。只需要长度或单个事件的调用方使用 `seq` 或 `eventAt()`。
+
+会话日志位置使用两种数字类型。`SessionSeq` 标识已有事件或包含端点的事件水位；`SessionLogOffset` 标识间隙、前缀长度或读取边界，并且可以等于事件数量。`SessionSeqCursor` 添加 `-1` 这个“尚无事件”值，`OptionalSessionSeq` 则在缺失本身属于数据时使用 `null`。构造函数会校验非负安全整数，品牌在运行时会被擦除，因此持久 JSON 与 wire 值仍是普通数字。
+
 ### 派生会话的 fork
 
 `ctx.sessions.fork(source, boundary?, childSessionId?)` 选取截至 `boundary` 事件序号（含该事件）的源事件（默认：当前最后一个事件），要求所选前缀结束时没有开放轮次，再创建带谱系元数据的实时子会话。必须在轮次中途分支的工具时委派会裁剪到已完成前缀。
 
+逻辑 `SessionHeader.isSeeded` 字段报告是否存在 fork 历史，而不公开位置整数。`Session.inheritedEventCount` 保留经过校验的精确 `SessionLogOffset`；`ownEvents()` 返回从该切点开始的事件，`isOwnSeq(seq)` 只接受已存在且由 child 拥有的位置。底层带 seed 构造必须显式提供 `seed` 与 `inheritedEventCount`，因为构造 seed 可以在继承前缀之后包含 child 自有的设置事件。
+
 ### 刷新持久状态
 
 `ctx.sessions.flush(session)` 分发需等待完成的持久性检查点：每个持久化监听器都会刷新，调用在所有监听器结算后完成。需要立即持久性屏障的生产方应等待它，而不是假定写后刷新已完成。
@@ -90,7 +98,7 @@ session.deriveMessages()         // the derived model history
 
 ### 追加校验
 
-每次追加都会使用共享的迭代式 `snapshotJsonValue()` 流程，对每个嵌套值只读取、校验并复制一次，因此有状态的 getter 无法给校验提供一个值、给存储提供另一个值。非无损 JSON 载荷（BigInt、循环、稀疏数组、`-0`、特殊原型）会在追加位置被拒绝，先于任何后端刷新。表层事件还会校验标记形态、被引用的源事件 seq，以及替换的完整遮蔽节点覆盖。
+每次追加都会使用共享的迭代式 `snapshotJsonValue()` 流程，对每个嵌套值只读取、校验并复制一次，因此有状态的 getter 无法给校验提供一个值、给存储提供另一个值。非无损 JSON 载荷（BigInt、循环、稀疏数组、`-0`、特殊原型）会在追加位置被拒绝，先于任何后端刷新。追加路径会构造每个 `SessionSeq`；surface 事件还会校验标记形态、被引用的源事件序号，以及替换的完整遮蔽节点覆盖。
 
 ### 派生历史
 

package/lib/index.js

@@ -1,6 +1,6 @@
 import { Service } from "@deepseek-ai/cordis";
 import { isAbsolute } from "node:path";
-import { brandString } from "@deepseek-ai/dsh-brand";
+import { brandNumber, brandString } from "@deepseek-ai/dsh-brand";
 import { deepFreeze, snapshotJsonValue } from "@deepseek-ai/dsh-util-values";
 import { scopeOf, scopeTarget } from "@deepseek-ai/dsh-scope";
 import { callConfigEquals } from "@deepseek-ai/dsh-llm";
@@ -14,6 +14,24 @@ function SessionId(id) {
 	return brandString(id);
 }
 /**
+* Admit a numeric value as an existing Session event position.
+* @param value - non-negative safe integer admitted by the owning log operation.
+* @returns the same number with the Session-sequence brand.
+*/
+function SessionSeq(value) {
+	if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new TypeError(`SessionSeq must be a non-negative safe integer, got ${String(value)}`);
+	return brandNumber(value);
+}
+/**
+* Admit a numeric value as a Session log offset.
+* @param value - non-negative safe integer used as a gap or prefix length.
+* @returns the same number with the Session-log-offset brand.
+*/
+function SessionLogOffset(value) {
+	if (!Number.isSafeInteger(value) || value < 0 || Object.is(value, -0)) throw new TypeError(`SessionLogOffset must be a non-negative safe integer, got ${String(value)}`);
+	return brandNumber(value);
+}
+/**
 * The on-disk session format version, stamped into every newly-written {@link SessionHeader}
 * 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.
@@ -127,7 +145,7 @@ function createFoldState() {
 }
 /** Whether a runtime value is a non-negative safe event sequence. */
 function isEventSeq(value) {
-	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 && !Object.is(value, -0);
 }
 /** Whether a runtime value is the exact positional-replacement shape. */
 function isReplaceOp(value) {
@@ -278,7 +296,7 @@ function foldSurface(events) {
 	const state = createFoldState();
 	const replacements = [];
 	for (const [index, event] of events.entries()) {
-		const replacement = applySurfaceEvent(state, event, index, events, 0);
+		const replacement = applySurfaceEvent(state, event, SessionSeq(index), events, SessionLogOffset(0));
 		if (replacement !== void 0) replacements.push(replacement);
 	}
 	return {
@@ -300,10 +318,10 @@ var SurfaceManager = class {
 	* @param log - Contiguous complete log or loaded event window.
 	* @param baseSeq - Absolute sequence of the window's first event.
 	*/
-	constructor(log, baseSeq = 0) {
+	constructor(log, baseSeq = SessionLogOffset(0)) {
 		this.log = log;
 		this.baseSeq = baseSeq;
-		this._lastProcessedSeq = baseSeq - 1;
+		this._lastProcessedSeq = baseSeq === 0 ? -1 : SessionSeq(baseSeq - 1);
 	}
 	/**
 	* Validate the next candidate without mutating the committed surface.
@@ -311,7 +329,7 @@ var SurfaceManager = class {
 	*/
 	validateNext(event) {
 		if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1) this._processDelta();
-		const expectedSeq = this.baseSeq + this.log.length;
+		const expectedSeq = SessionSeq(this.baseSeq + this.log.length);
 		this._pendingPlan = {
 			event,
 			expectedSeq,
@@ -336,9 +354,9 @@ var SurfaceManager = class {
 			const event = this.log[index];
 			const pending = this._pendingPlan;
 			if (pending?.event === event && pending.expectedSeq === seq) applySurfacePlan(this._state, pending.plan);
-			else applySurfaceEvent(this._state, event, seq, this.log, this.baseSeq);
+			else applySurfaceEvent(this._state, event, SessionSeq(seq), this.log, this.baseSeq);
 			if (pending !== void 0 && pending.expectedSeq <= seq) this._pendingPlan = void 0;
-			this._lastProcessedSeq = seq;
+			this._lastProcessedSeq = SessionSeq(seq);
 		}
 	}
 };
@@ -518,7 +536,7 @@ function interruptedTurnClosers(events) {
 		});
 		closers.push({
 			type: "tool/result",
-			seq: seq++,
+			seq: SessionSeq(seq++),
 			time,
 			data: {
 				turn: openTurn,
@@ -538,7 +556,7 @@ function interruptedTurnClosers(events) {
 	}
 	if (openStep !== null) closers.push({
 		type: "step/end",
-		seq: seq++,
+		seq: SessionSeq(seq++),
 		time,
 		data: {
 			turn: openTurn,
@@ -547,7 +565,7 @@ function interruptedTurnClosers(events) {
 	});
 	closers.push({
 		type: "turn/end",
-		seq: seq++,
+		seq: SessionSeq(seq++),
 		time,
 		data: {
 			turn: openTurn,
@@ -567,7 +585,7 @@ function interruptedTurnClosers(events) {
 * `tool-call-chunks` — and expands rows back to the exact original events.
 *
 * Packed rows are an encoding vocabulary, NOT session events: they never enter
-* `Session.events`, have no `SessionEventMap` entry, and use bare (slash-less)
+* `Session.snapshotEvents()`, have no `SessionEventMap` entry, and use bare (slash-less)
 * type tags so a reader cannot confuse them with the event taxonomy
 * (precedent: the JSONL header line's `session` tag). Persistence and bounded
 * history transport both use the codec. The encoder whitelists exact shapes —
@@ -607,7 +625,7 @@ function classify(event) {
 		"time",
 		"data"
 	])) return void 0;
-	if (!Number.isSafeInteger(event.seq) || event.seq < 0 || !Number.isSafeInteger(event.time)) return void 0;
+	if (!Number.isSafeInteger(event.seq) || event.seq < 0 || Object.is(event.seq, -0) || !Number.isSafeInteger(event.time)) return void 0;
 	const data = event.data;
 	if (!isRecord(data) || !hasExactKeys(data, [
 		"turn",
@@ -760,7 +778,7 @@ function validateRow(value, tag) {
 		"time0",
 		"data"
 	])) malformed(tag, "envelope must be exactly {type, seq0, time0, data}");
-	if (!Number.isSafeInteger(value.seq0) || value.seq0 < 0) malformed(tag, "seq0 must be a non-negative safe integer");
+	if (!Number.isSafeInteger(value.seq0) || value.seq0 < 0 || Object.is(value.seq0, -0)) malformed(tag, "seq0 must be a non-negative safe integer");
 	if (!Number.isSafeInteger(value.time0)) malformed(tag, "time0 must be a safe integer");
 	const data = value.data;
 	if (!isRecord(data)) malformed(tag, "data must be an object");
@@ -801,6 +819,7 @@ function validateRow(value, tag) {
 		time += gap;
 		if (!Number.isSafeInteger(time)) malformed(tag, "member times must stay safe integers");
 	}
+	SessionSeq(value.seq0);
 	return value;
 }
 /** Expand a validated row back into its exact original events, in order. */
@@ -840,7 +859,7 @@ function expandRow(row) {
 		}
 		events.push({
 			type: "assistant/chunk",
-			seq: row.seq0 + k,
+			seq: SessionSeq(row.seq0 + k),
 			time,
 			data: {
 				turn: row.data.turn,
@@ -855,7 +874,8 @@ function expandRow(row) {
 * Decode one parsed JSONL line value into the session event(s) it stores.
 * Chunk-row-tagged values validate and expand (a malformed row throws — it is
 * corrupt storage, and treating it as an event would silently drop a whole
-* run); every other value passes through as a single event, unvalidated.
+* run); every other value passes through as a single event after admitting a
+* numeric `seq` through the Session-sequence constructor.
 *
 * @param value - one line's `JSON.parse` result.
 * @returns the stored events, in log order.
@@ -863,7 +883,10 @@ function expandRow(row) {
 function decodeStorageRecord(value) {
 	if (!isRecord(value)) return [value];
 	const tag = value.type;
-	if (tag !== "text-chunks" && tag !== "reasoning-chunks" && tag !== "tool-call-chunks") return [value];
+	if (tag !== "text-chunks" && tag !== "reasoning-chunks" && tag !== "tool-call-chunks") {
+		if (typeof value.seq === "number") SessionSeq(value.seq);
+		return [value];
+	}
 	return expandRow(validateRow(value, tag));
 }
 //#endregion
@@ -978,7 +1001,7 @@ function decodeSeqRanges(value, maxEntries = Number.MAX_SAFE_INTEGER) {
 		if (typeof entry === "number") {
 			assertSeq(entry);
 			if (decoded.length >= maxEntries) throw new TypeError("sourceEventSeqs exceeds its event sequence");
-			decoded.push(entry);
+			decoded.push(SessionSeq(entry));
 			continue;
 		}
 		if (!Array.isArray(entry) || entry.length !== 2) throw new TypeError("sourceEventSeqs range entries must be [start, end] pairs");
@@ -988,7 +1011,7 @@ function decodeSeqRanges(value, maxEntries = Number.MAX_SAFE_INTEGER) {
 		assertSeq(end);
 		if (end < start) throw new TypeError("sourceEventSeqs ranges require start <= end");
 		if (end - start + 1 > maxEntries - decoded.length) throw new TypeError("sourceEventSeqs range exceeds its event sequence");
-		for (let seq = start; seq <= end; seq += 1) decoded.push(seq);
+		for (let seq = start; seq <= end; seq += 1) decoded.push(SessionSeq(seq));
 		hasRange = true;
 	}
 	if (hasRange && !isStrictlyIncreasing(decoded)) throw new TypeError("sourceEventSeqs ranges must be strictly increasing");
@@ -1010,6 +1033,7 @@ function assertSeq(value) {
 function validateSessionHeader(id, input) {
 	if (input === null || typeof input !== "object" || Array.isArray(input)) throw new Error("session header is not a plain JSON record");
 	const record = input;
+	if (Object.hasOwn(record, "seedLength")) throw new Error("session header has invalid field \"seedLength\"");
 	if (record.version !== 0) throw new Error(`session header version must be 0, got ${String(record.version)}`);
 	if (record.id !== id) throw new Error(`session header id "${String(record.id)}" does not match session id "${id}"`);
 	if (typeof record.createdAt !== "number" || !Number.isSafeInteger(record.createdAt) || record.createdAt < 0) throw new Error("session header createdAt must be a non-negative safe integer");
@@ -1018,7 +1042,7 @@ function validateSessionHeader(id, input) {
 		if (!isAbsolute(record.cwd)) throw new Error(`session header cwd must be an absolute path, got "${record.cwd}"`);
 	}
 	if (record.parentSession !== void 0 && typeof record.parentSession !== "string") throw new Error("session header parentSession must be a string");
-	if (record.seedLength !== void 0 && (typeof record.seedLength !== "number" || !Number.isSafeInteger(record.seedLength) || record.seedLength < 0)) throw new Error("session header seedLength must be a non-negative safe integer");
+	if (typeof record.isSeeded !== "boolean") throw new Error("session header isSeeded must be a boolean");
 	if (record.origin !== void 0 && record.origin !== "subagent") throw new Error("session header origin must be \"subagent\"");
 	if (record.delegationDepth !== void 0 && (typeof record.delegationDepth !== "number" || !Number.isSafeInteger(record.delegationDepth) || record.delegationDepth < 0)) throw new Error("session header delegationDepth must be a non-negative safe integer");
 	if (record.agentPreset !== void 0 && typeof record.agentPreset !== "string") throw new Error("session header agentPreset must be a string");
@@ -1037,7 +1061,8 @@ function snapshotSessionHeader(id, source) {
 	const snapshot = snapshotJsonValue(source === void 0 ? {
 		version: 0,
 		id,
-		createdAt: Date.now()
+		createdAt: Date.now(),
+		isSeeded: false
 	} : source);
 	if (snapshot === void 0) throw new Error("session header is not losslessly JSON-serializable");
 	return validateSessionHeader(id, snapshot);
@@ -1102,7 +1127,7 @@ function assertSessionEventEnvelope(value, index) {
 	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 || event["ignorable"] !== void 0 && event["ignorable"] !== true) 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 || Object.is(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":
@@ -1210,13 +1235,15 @@ var Session = class Session {
 	}
 	/**
 	* Detached, deep-frozen creation metadata (format version, cwd, lineage,
-	* seed boundary). Supplied by the store via `ctx.sessions.create()`. When a
+	* and whether fork history exists). Supplied by the store via `ctx.sessions.create()`. When a
 	* `Session` is created without a store-owned header, a minimal header is
 	* synthesized (stamped with the current {@link SESSION_FORMAT_VERSION}) so
 	* `session.header` is always present. Kept out of the event log — it is a
 	* storage concern, not replayable conversation state.
 	*/
 	header;
+	/** Number of leading events inherited from this Session's fork parent. */
+	inheritedEventCount;
 	/** The session identity, derived from its durable header's single copy. */
 	get id() {
 		return this.header.id;
@@ -1227,9 +1254,9 @@ var Session = class Session {
 	* construction — replay, fork, or resume — and were never published on the
 	* `session/event` firehose (constructor seeds do not emit), so consumers
 	* that replay the log as a publication substitute (telemetry adoption)
-	* start here. Distinct from `header.seedLength`, the DURABLE fork-lineage
-	* boundary: a resumed session's constructor seed is its full stored log,
-	* while its header keeps the original fork value — this field is the
+	* start here. Distinct from {@link inheritedEventCount}, the DURABLE
+	* fork-lineage cut: a resumed session's constructor seed is its full stored
+	* log, while the inherited count keeps the original fork value — this field is the
 	* in-process construction fact.
 	*
 	* Not persisted itself: a seeded session projects it into the log as the
@@ -1250,10 +1277,11 @@ var Session = class Session {
 	* @param id - session identity.
 	* @param seed - optional borrowed replay or fork events.
 	* @param header - optional borrowed storage metadata.
+	* @param inheritedEventCount - exact fork-inherited prefix length for a seeded header.
 	* @returns a detached session.
 	*/
-	static create(id, seed, header) {
-		return new Session(id, seed, header);
+	static create(id, seed, header, inheritedEventCount) {
+		return new Session(id, seed, header, "snapshot", inheritedEventCount);
 	}
 	/**
 	* Restore a detached session by taking ownership of fresh persistence values.
@@ -1262,12 +1290,13 @@ var Session = class Session {
 	* @param id - restored session identity.
 	* @param seed - fresh detached events whose ownership is transferred.
 	* @param header - fresh detached metadata whose ownership is transferred.
+	* @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
 	* @returns a restored detached session.
 	*/
-	static fromRestore(id, seed, header) {
-		return new Session(id, seed, header, "restore");
+	static fromRestore(id, seed, header, inheritedEventCount) {
+		return new Session(id, seed, header, "restore", inheritedEventCount);
 	}
-	constructor(id, seed, header, mode = "snapshot") {
+	constructor(id, seed, header, mode = "snapshot", suppliedInheritedEventCount) {
 		const restoredHeader = mode === "restore" ? validateRestoredSessionHeader(id, header) : void 0;
 		if (seed !== void 0) for (const [index, source] of seed.entries()) {
 			const snapshot = mode === "restore" ? source : snapshotJsonValue(source);
@@ -1282,25 +1311,59 @@ var Session = class Session {
 			}
 			this.log.push(mode === "restore" ? freezeRestoredObject(snapshot) : deepFreeze(snapshot));
 		}
-		this.firstLiveSeq = this.log.length;
+		this.firstLiveSeq = SessionLogOffset(this.log.length);
 		this.header = restoredHeader ?? snapshotSessionHeader(id, header);
+		if (this.header.isSeeded && seed === void 0) throw new Error("seeded session requires an explicit constructor seed");
+		if (this.header.isSeeded && suppliedInheritedEventCount === void 0) throw new Error("seeded session requires an inherited event count");
+		const inheritedEventCount = SessionLogOffset(suppliedInheritedEventCount ?? 0);
+		if (!this.header.isSeeded && inheritedEventCount !== 0) throw new Error("unseeded session inherited event count must be 0");
+		if (inheritedEventCount > this.log.length) throw new Error("session inherited event count exceeds its event log");
+		this.inheritedEventCount = inheritedEventCount;
 		if (seed !== void 0 && this.log.at(-1)?.type !== "session/end-seed") this.append("session/end-seed", {});
 	}
-	/** Cached immutable public snapshot of the private append-only log. */
+	/** Cached immutable full snapshot of the private append-only log. */
 	eventsSnapshot;
 	/**
-	* An immutable snapshot of the append-only event log. The snapshot is reused
-	* until the next append; a previously returned array does not grow later.
-	* Events and their nested data are deep-frozen at acceptance, so neither a
-	* cast nor ordinary JavaScript can rewrite durable history.
+	* Return the immutable event stored at one exact sequence number.
+	* @param seq - event sequence number.
+	* @returns the accepted event, or undefined when the log does not contain it.
+	*/
+	eventAt(seq) {
+		return this.log[seq];
+	}
+	/**
+	* Materialize an immutable snapshot of a half-open event sequence range.
+	* A full current snapshot is reused until the next append; every previously
+	* returned snapshot remains stable after later appends.
+	* @param fromSeq - non-negative inclusive sequence number; defaults to the log start.
+	* @param toSeqExclusive - non-negative exclusive sequence number; defaults to the current end.
+	* @returns a frozen array of the selected deeply frozen events.
+	*/
+	snapshotEvents(fromSeq = SessionLogOffset(0), toSeqExclusive = this.seq) {
+		if (fromSeq === 0 && toSeqExclusive === this.log.length) {
+			this.eventsSnapshot ??= Object.freeze([...this.log]);
+			return this.eventsSnapshot;
+		}
+		return Object.freeze(this.log.slice(fromSeq, toSeqExclusive));
+	}
+	/**
+	* Return this Session's events after its fork-inherited prefix.
+	* @returns a fresh array containing child-owned events in log order.
+	*/
+	ownEvents() {
+		return this.snapshotEvents(this.inheritedEventCount);
+	}
+	/**
+	* Whether one existing event position is outside the fork-inherited prefix.
+	* @param seq - event position in this Session.
+	* @returns true when the event belongs to this Session rather than its parent.
 	*/
-	get events() {
-		this.eventsSnapshot ??= Object.freeze([...this.log]);
-		return this.eventsSnapshot;
+	isOwnSeq(seq) {
+		return seq >= this.inheritedEventCount && seq < this.seq;
 	}
 	/** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
 	get seq() {
-		return this.log.length;
+		return SessionLogOffset(this.log.length);
 	}
 	/**
 	* Append one typed event to the log and synchronously notify observers via
@@ -1352,7 +1415,7 @@ var Session = class Session {
 		if (entry?.appending) throw new Error("session append cannot reenter while another append is being published");
 		const event = deepFreeze({
 			type,
-			seq: this.log.length,
+			seq: SessionSeq(this.log.length),
 			time: Date.now(),
 			data: dataSnapshot,
 			...surfaceMetadataSnapshot
@@ -1386,7 +1449,7 @@ var Session = class Session {
 	* The {@link EpochHeader} in force after the log's last header event — the
 	* header the NEXT request will be compared against — or undefined before
 	* the first `request/header` snapshot. The live, incrementally-maintained
-	* form of `foldRequestHeader(session.events)`: each header event is folded
+	* form of `foldRequestHeader(session.snapshotEvents())`: each header event is folded
 	* once, when first seen, so a per-step read costs O(new events).
 	* @returns the folded header, or undefined when no header event exists yet.
 	*/
@@ -1548,7 +1611,7 @@ var SessionStore = class extends Service {
 		while (this.store.has(sessionId));
 		else sessionId = brandString(id);
 		if (this.store.has(sessionId)) throw new Error(`session "${sessionId}" already exists`);
-		if (options?.seedSource === "persistence") return Session.fromRestore(sessionId, options.seed, options.meta);
+		if (options?.seedSource === "persistence") return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount);
 		const seed = options?.seed;
 		const meta = options?.meta;
 		const header = {
@@ -1557,12 +1620,12 @@ var SessionStore = class extends Service {
 			createdAt: meta?.createdAt ?? Date.now(),
 			...meta?.cwd === void 0 ? {} : { cwd: meta.cwd },
 			...meta?.parentSession === void 0 ? {} : { parentSession: meta.parentSession },
-			...meta?.seedLength === void 0 ? {} : { seedLength: meta.seedLength },
+			isSeeded: meta?.isSeeded ?? false,
 			...meta?.origin === void 0 ? {} : { origin: meta.origin },
 			...meta?.delegationDepth === void 0 ? {} : { delegationDepth: meta.delegationDepth },
 			...meta?.agentPreset === void 0 ? {} : { agentPreset: meta.agentPreset }
 		};
-		return Session.create(sessionId, seed, header);
+		return Session.create(sessionId, seed, header, options?.inheritedEventCount);
 	}
 	/**
 	* Enter a {@link prepare}d session into the store: install the module-private
@@ -1743,16 +1806,16 @@ var SessionStore = class extends Service {
 		const seed = this._forkSeed(liveSource, boundary);
 		return this.create(childSessionId, {
 			seed,
+			inheritedEventCount: SessionLogOffset(seed.length),
 			meta: {
 				...liveSource.header.cwd !== void 0 ? { cwd: liveSource.header.cwd } : {},
 				parentSession: liveSource.id,
-				seedLength: seed.length
+				isSeeded: true
 			}
 		});
 	}
 	_forkSeed(session, requestedBoundary) {
-		const events = session.events;
-		const lastEvent = events.at(-1);
+		const lastEvent = session.snapshotEvents().at(-1);
 		let boundary;
 		if (requestedBoundary !== void 0) boundary = requestedBoundary;
 		else {
@@ -1760,15 +1823,16 @@ var SessionStore = class extends Service {
 			boundary = lastEvent.seq;
 		}
 		if (!Number.isSafeInteger(boundary) || boundary < 0) throw new SessionForkError(`fork boundary for session "${session.id}" must be a non-negative safe integer, got ${String(boundary)}`, "INVALID_BOUNDARY");
-		if (boundary >= events.length) {
-			const lastSeq = events.at(-1)?.seq;
+		if (boundary >= session.seq) {
+			const lastSeq = lastEvent?.seq;
 			throw new SessionForkError(`fork boundary ${boundary} does not exist in session "${session.id}" (last seq: ${lastSeq ?? "none"})`, "INVALID_BOUNDARY");
 		}
-		const boundaryEvent = events[boundary];
+		const boundaryEvent = session.eventAt(boundary);
 		if (boundaryEvent === void 0 || boundaryEvent.seq !== boundary) throw new SessionForkError(`fork boundary ${boundary} does not match a contiguous event seq in session "${session.id}"`, "INVALID_BOUNDARY");
-		const lastTurnBoundary = events.slice(0, boundary + 1).findLast((event) => event.type === "turn/start" || event.type === "turn/end");
+		const events = session.snapshotEvents(SessionLogOffset(0), SessionLogOffset(boundary + 1));
+		const lastTurnBoundary = events.findLast((event) => event.type === "turn/start" || event.type === "turn/end");
 		if (lastTurnBoundary?.type === "turn/start") throw new SessionForkError(`fork boundary ${boundary} in session "${session.id}" ends inside open turn ${lastTurnBoundary.data.turn}`, "OPEN_TURN");
-		return events.slice(0, boundary + 1);
+		return events;
 	}
 	_resolveForkSource(source) {
 		if (typeof source === "string") {
@@ -1783,4 +1847,4 @@ var SessionStore = class extends Service {
 	}
 };
 //#endregion
-export { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionPreparation, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, adoptSessionEvent, canonicalHeader, decodeSeqRanges, decodeStorageRecord, deriveEventMessage, encodeSeqRanges, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, packChunkRuns, snapshotSessionEvent };
+export { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, Session, SessionForkError, SessionId, SessionLogOffset, SessionPreparation, SessionSeq, SessionStore, SessionStore as default, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN, adoptSessionEvent, canonicalHeader, decodeSeqRanges, decodeStorageRecord, deriveEventMessage, encodeSeqRanges, foldRequestHeader, foldSurface, headerEquals, interruptedTurnClosers, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEligibleType, isSurfaceEvent, packChunkRuns, snapshotSessionEvent };

package/lib/invariant.js

@@ -130,7 +130,7 @@ const install = Object.assign((ctx, fail) => {
 	const seedSession = (session) => {
 		const trace = freshTrace();
 		traces.set(session, trace);
-		for (const event of session.events) applyTransition(trace, validateEvent(trace, event, fail));
+		for (const event of session.snapshotEvents()) applyTransition(trace, validateEvent(trace, event, fail));
 		return trace;
 	};
 	/* v8 ignore next -- session/event always follows list() or session/created seeding */

package/lib/types/chunk-rows.d.ts

@@ -7,7 +7,7 @@
  * `tool-call-chunks` — and expands rows back to the exact original events.
  *
  * Packed rows are an encoding vocabulary, NOT session events: they never enter
- * `Session.events`, have no `SessionEventMap` entry, and use bare (slash-less)
+ * `Session.snapshotEvents()`, have no `SessionEventMap` entry, and use bare (slash-less)
  * type tags so a reader cannot confuse them with the event taxonomy
  * (precedent: the JSONL header line's `session` tag). Persistence and bounded
  * history transport both use the codec. The encoder whitelists exact shapes —
@@ -19,7 +19,7 @@
  * @module @deepseek-ai/dsh-session/chunk-rows
  */
 import type { ToolCallId } from '@deepseek-ai/dsh-llm/brand';
-import type { SessionEvent } from './types.ts';
+import type { SessionEvent, SessionSeq as SessionSeqType } from './types.ts';
 /**
  * Fields shared by every packed run: placement, block correlation, and member
  * timestamps as gaps. Member `k` reconstructs as seq `seq0 + k` and time
@@ -52,17 +52,17 @@ interface ToolCallRunData extends RunDataBase {
  */
 export type ChunkRow = {
     type: 'text-chunks';
-    seq0: number;
+    seq0: SessionSeqType;
     time0: number;
     data: TextRunData;
 } | {
     type: 'reasoning-chunks';
-    seq0: number;
+    seq0: SessionSeqType;
     time0: number;
     data: TextRunData;
 } | {
     type: 'tool-call-chunks';
-    seq0: number;
+    seq0: SessionSeqType;
     time0: number;
     data: ToolCallRunData;
 };
@@ -95,7 +95,8 @@ export declare function packChunkRuns(events: readonly SessionEvent[]): StorageR
  * Decode one parsed JSONL line value into the session event(s) it stores.
  * Chunk-row-tagged values validate and expand (a malformed row throws — it is
  * corrupt storage, and treating it as an event would silently drop a whole
- * run); every other value passes through as a single event, unvalidated.
+ * run); every other value passes through as a single event after admitting a
+ * numeric `seq` through the Session-sequence constructor.
  *
  * @param value - one line's `JSON.parse` result.
  * @returns the stored events, in log order.

package/lib/types/chunk-rows.js

@@ -7,7 +7,7 @@
  * `tool-call-chunks` — and expands rows back to the exact original events.
  *
  * Packed rows are an encoding vocabulary, NOT session events: they never enter
- * `Session.events`, have no `SessionEventMap` entry, and use bare (slash-less)
+ * `Session.snapshotEvents()`, have no `SessionEventMap` entry, and use bare (slash-less)
  * type tags so a reader cannot confuse them with the event taxonomy
  * (precedent: the JSONL header line's `session` tag). Persistence and bounded
  * history transport both use the codec. The encoder whitelists exact shapes —
@@ -19,6 +19,7 @@
  * @module @deepseek-ai/dsh-session/chunk-rows
  */
 import { brandString } from '@deepseek-ai/dsh-brand';
+import { SessionSeq } from "./types.js";
 /**
  * Test whether an encoded record is a packed chunk row rather than a Session event.
  * @param record - one persistence or bounded-history encoding record.
@@ -63,7 +64,8 @@ function classify(event) {
         return undefined;
     if (!hasExactKeys(event, ['type', 'seq', 'time', 'data']))
         return undefined;
-    if (!Number.isSafeInteger(event.seq) || event.seq < 0 || !Number.isSafeInteger(event.time))
+    if (!Number.isSafeInteger(event.seq) || event.seq < 0 || Object.is(event.seq, -0)
+        || !Number.isSafeInteger(event.time))
         return undefined;
     const data = event.data;
     if (!isRecord(data) || !hasExactKeys(data, ['turn', 'step', 'chunk']))
@@ -219,7 +221,7 @@ function validateRow(value, tag) {
     if (!hasExactKeys(value, ['type', 'seq0', 'time0', 'data'])) {
         malformed(tag, 'envelope must be exactly {type, seq0, time0, data}');
     }
-    if (!Number.isSafeInteger(value.seq0) || value.seq0 < 0) {
+    if (!Number.isSafeInteger(value.seq0) || value.seq0 < 0 || Object.is(value.seq0, -0)) {
         malformed(tag, 'seq0 must be a non-negative safe integer');
     }
     if (!Number.isSafeInteger(value.time0)) {
@@ -259,6 +261,7 @@ function validateRow(value, tag) {
         if (!Number.isSafeInteger(time))
             malformed(tag, 'member times must stay safe integers');
     }
+    SessionSeq(value.seq0);
     return value;
 }
 /** Expand a validated row back into its exact original events, in order. */
@@ -294,7 +297,7 @@ function expandRow(row) {
         }
         events.push({
             type: 'assistant/chunk',
-            seq: row.seq0 + k,
+            seq: SessionSeq(row.seq0 + k),
             time,
             data: { turn: row.data.turn, step: row.data.step, chunk },
         });
@@ -305,7 +308,8 @@ function expandRow(row) {
  * Decode one parsed JSONL line value into the session event(s) it stores.
  * Chunk-row-tagged values validate and expand (a malformed row throws — it is
  * corrupt storage, and treating it as an event would silently drop a whole
- * run); every other value passes through as a single event, unvalidated.
+ * run); every other value passes through as a single event after admitting a
+ * numeric `seq` through the Session-sequence constructor.
  *
  * @param value - one line's `JSON.parse` result.
  * @returns the stored events, in log order.
@@ -315,6 +319,8 @@ export function decodeStorageRecord(value) {
         return [value];
     const tag = value.type;
     if (tag !== 'text-chunks' && tag !== 'reasoning-chunks' && tag !== 'tool-call-chunks') {
+        if (typeof value.seq === 'number')
+            SessionSeq(value.seq);
         return [value];
     }
     return expandRow(validateRow(value, tag));