@deepseek-ai/dsh-session 0.1.2-alpha.2 → 0.1.2-alpha.4

package/lib/types/index.d.ts

@@ -8,6 +8,7 @@
 import { Context, Service } from '@deepseek-ai/cordis';
 import type { Scoped } from '@deepseek-ai/dsh-scope';
 import type { Message } from '@deepseek-ai/dsh-llm';
+import { SessionLogOffset, SessionSeq } from './types.ts';
 import type { TypertLookup } from '@deepseek-ai/dsh-typert-protocol';
 import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SurfaceIntent, SurfaceEventType } from './types.ts';
 import type { SessionSurface } from './surface.ts';
@@ -108,13 +109,15 @@ export declare class Session {
     get surface(): SessionSurface;
     /**
      * 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.
      */
     readonly header: SessionHeader;
+    /** Number of leading events inherited from this Session's fork parent. */
+    readonly inheritedEventCount: SessionLogOffset;
     /** The session identity, derived from its durable header's single copy. */
     get id(): SessionId;
     /**
@@ -123,9 +126,9 @@ export declare 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
@@ -139,16 +142,17 @@ export declare class Session {
      * store attaches and therefore does not publish either. Otherwise this seq
      * holds an ordinary published write.
      */
-    readonly firstLiveSeq: number;
+    readonly firstLiveSeq: SessionLogOffset;
     /**
      * Create a detached session by validating and snapshotting borrowed seed
      * events and storage metadata.
      * @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: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader): Session;
+    static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader, inheritedEventCount?: SessionLogOffset): Session;
     /**
      * Restore a detached session by taking ownership of fresh persistence values.
      * The storage format, event envelopes, sequence continuity, surface transitions,
@@ -156,21 +160,41 @@ export declare 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: SessionId, seed: readonly SessionEvent[], header: SessionHeader): Session;
+    static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader, inheritedEventCount: SessionLogOffset): Session;
     private constructor();
-    /** Cached immutable public snapshot of the private append-only log. */
+    /** Cached immutable full snapshot of the private append-only log. */
     private 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.
      */
-    get events(): readonly SessionEvent[];
+    eventAt(seq: SessionSeq): SessionEvent | undefined;
+    /**
+     * 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, toSeqExclusive?: SessionLogOffset): readonly SessionEvent[];
+    /**
+     * Return this Session's events after its fork-inherited prefix.
+     * @returns a fresh array containing child-owned events in log order.
+     */
+    ownEvents(): readonly SessionEvent[];
+    /**
+     * 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.
+     */
+    isOwnSeq(seq: SessionSeq): boolean;
     /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
-    get seq(): number;
+    get seq(): SessionLogOffset;
     /**
      * Append one typed event to the log and synchronously notify observers via
      * the store-owned, module-private publication hooks. The hot path never blocks
@@ -215,7 +239,7 @@ export declare 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.
      */
@@ -407,7 +431,7 @@ export declare class SessionStore extends Service {
      *   `SessionStore`'s id policy.
      * @returns The created live child session.
      */
-    fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session;
+    fork(source: SessionForkSource, boundary?: SessionSeq, childSessionId?: SessionId): Session;
     private _forkSeed;
     private _resolveForkSource;
 }

package/lib/types/index.js

@@ -10,7 +10,7 @@ import { isAbsolute } from 'node:path';
 import { brandString } from '@deepseek-ai/dsh-brand';
 import { deepFreeze, snapshotJsonValue } from '@deepseek-ai/dsh-util-values';
 import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope';
-import { SESSION_FORMAT_VERSION } from "./types.js";
+import { SESSION_FORMAT_VERSION, SessionLogOffset, SessionSeq } from "./types.js";
 import { deriveEventMessage, SurfaceManager } from "./surface.js";
 import { foldRequestHeader } from "./request-header.js";
 export * from "./types.js";
@@ -26,6 +26,9 @@ function validateSessionHeader(id, 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 !== SESSION_FORMAT_VERSION) {
         throw new Error(`session header version must be ${SESSION_FORMAT_VERSION}, got ${String(record.version)}`);
     }
@@ -47,9 +50,8 @@ function validateSessionHeader(id, input) {
     if (record.parentSession !== undefined && typeof record.parentSession !== 'string') {
         throw new Error('session header parentSession must be a string');
     }
-    if (record.seedLength !== undefined
-        && (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 !== undefined && record.origin !== 'subagent') {
         throw new Error('session header origin must be "subagent"');
@@ -76,7 +78,7 @@ function validateRestoredSessionHeader(id, input) {
 /** Detach, validate, and freeze the creation metadata published by a session. */
 function snapshotSessionHeader(id, source) {
     const input = source === undefined
-        ? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now() }
+        ? { version: SESSION_FORMAT_VERSION, id, createdAt: Date.now(), isSeeded: false }
         : source;
     const snapshot = snapshotJsonValue(input);
     if (snapshot === undefined)
@@ -155,7 +157,7 @@ function assertSessionEventEnvelope(value, index) {
     const seq = event['seq'];
     const time = event['time'];
     if (typeof type !== 'string'
-        || typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0
+        || typeof seq !== 'number' || !Number.isSafeInteger(seq) || seq < 0 || Object.is(seq, -0)
         || typeof time !== 'number' || !Number.isSafeInteger(time)
         || event['data'] === undefined
         || (event['ignorable'] !== undefined && event['ignorable'] !== true)) {
@@ -326,13 +328,15 @@ export 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;
@@ -343,9 +347,9 @@ export 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
@@ -366,10 +370,11 @@ export 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.
@@ -378,12 +383,13 @@ export 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)
             : undefined;
@@ -419,8 +425,22 @@ export 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 === undefined) {
+            throw new Error('seeded session requires an explicit constructor seed');
+        }
+        if (this.header.isSeeded && suppliedInheritedEventCount === undefined) {
+            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;
         // Appended here so the marker is already in `events` when a backend
         // captures the creation seed: no load-time write. Re-marking is skipped
         // because a cold session is resumed on first touch, so repeatedly opening
@@ -429,21 +449,49 @@ export class Session {
             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
@@ -501,7 +549,7 @@ export class Session {
         }
         const event = deepFreeze({
             type,
-            seq: this.log.length,
+            seq: SessionSeq(this.log.length),
             time: Date.now(),
             data: dataSnapshot,
             ...surfaceMetadataSnapshot,
@@ -538,7 +586,7 @@ export 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.
      */
@@ -724,7 +772,7 @@ export class SessionStore extends Service {
         if (this.store.has(sessionId))
             throw new Error(`session "${sessionId}" already exists`);
         if (options?.seedSource === 'persistence') {
-            return Session.fromRestore(sessionId, options.seed, options.meta);
+            return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount);
         }
         const seed = options?.seed;
         const meta = options?.meta;
@@ -734,12 +782,12 @@ export class SessionStore extends Service {
             createdAt: meta?.createdAt ?? Date.now(),
             ...meta?.cwd === undefined ? {} : { cwd: meta.cwd },
             ...meta?.parentSession === undefined ? {} : { parentSession: meta.parentSession },
-            ...meta?.seedLength === undefined ? {} : { seedLength: meta.seedLength },
+            isSeeded: meta?.isSeeded ?? false,
             ...meta?.origin === undefined ? {} : { origin: meta.origin },
             ...meta?.delegationDepth === undefined ? {} : { delegationDepth: meta.delegationDepth },
             ...meta?.agentPreset === undefined ? {} : { 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
@@ -941,16 +989,16 @@ export class SessionStore extends Service {
         const seed = this._forkSeed(liveSource, boundary);
         return this.create(childSessionId, {
             seed,
+            inheritedEventCount: SessionLogOffset(seed.length),
             meta: {
                 ...liveSource.header.cwd !== undefined ? { 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 !== undefined) {
             boundary = requestedBoundary;
@@ -963,20 +1011,21 @@ export class SessionStore extends Service {
         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 === undefined || 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)
+        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') {

package/lib/types/invariant.js

@@ -159,7 +159,7 @@ const install = Object.assign((ctx, fail) => {
     const seedSession = (session) => {
         const trace = freshTrace();
         traces.set(session, trace);
-        for (const event of session.events) {
+        for (const event of session.snapshotEvents()) {
             applyTransition(trace, validateEvent(trace, event, fail));
         }
         return trace;

package/lib/types/repair.js

@@ -6,6 +6,7 @@
  */
 import { brandString } from '@deepseek-ai/dsh-brand';
 import { deepFreeze } from '@deepseek-ai/dsh-util-values';
+import { SessionSeq } from "./types.js";
 /** Recovery code for an assistant tool request that never reached a recorded call start. */
 export const TOOL_NOT_STARTED = 'TOOL_NOT_STARTED';
 /** Recovery code for a recorded tool call whose completed outcome was not durably recorded. */
@@ -102,7 +103,7 @@ export function interruptedTurnClosers(events) {
         });
         closers.push({
             type: 'tool/result',
-            seq: seq++,
+            seq: SessionSeq(seq++),
             time,
             data: {
                 turn: openTurn,
@@ -119,9 +120,9 @@ export function interruptedTurnClosers(events) {
     // Close an open step next — a turn/end while a step is open is an invariant
     // violation, so the step's boundary must be synthesized before the turn's.
     if (openStep !== null) {
-        closers.push({ type: 'step/end', seq: seq++, time, data: { turn: openTurn, step: openStep } });
+        closers.push({ type: 'step/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, step: openStep } });
     }
-    closers.push({ type: 'turn/end', seq: seq++, time, data: { turn: openTurn, reason: { kind: 'interrupted' } } });
+    closers.push({ type: 'turn/end', seq: SessionSeq(seq++), time, data: { turn: openTurn, reason: { kind: 'interrupted' } } });
     return closers;
 }
 //# sourceMappingURL=repair.js.map

package/lib/types/seq-ranges.d.ts

@@ -1,4 +1,5 @@
 /** Lossless range encoding for JSONL `sourceEventSeqs` arrays. */
+import type { SessionSeq as SessionSeqType } from './types.ts';
 /** A stored source sequence or inclusive consecutive range. */
 export type EncodedSeq = number | [number, number];
 /**
@@ -6,12 +7,12 @@ export type EncodedSeq = number | [number, number];
  * @param values - validated in-memory source sequences.
  * @returns a lossless JSON storage form.
  */
-export declare function encodeSeqRanges(values: readonly number[]): EncodedSeq[];
+export declare function encodeSeqRanges(values: readonly SessionSeqType[]): EncodedSeq[];
 /**
  * Expand a JSON storage-form source sequence array.
  * @param value - parsed storage value.
  * @param maxEntries - largest list permitted by the owning event.
  * @returns the in-memory source sequences.
  */
-export declare function decodeSeqRanges(value: unknown, maxEntries?: number): number[];
+export declare function decodeSeqRanges(value: unknown, maxEntries?: number): SessionSeqType[];
 //# sourceMappingURL=seq-ranges.d.ts.map

package/lib/types/seq-ranges.js

@@ -1,4 +1,5 @@
 /** Lossless range encoding for JSONL `sourceEventSeqs` arrays. */
+import { SessionSeq } from "./types.js";
 function isStrictlyIncreasing(values) {
     return values.every((value, index) => index === 0 || value > values[index - 1]);
 }
@@ -40,7 +41,7 @@ export function decodeSeqRanges(value, maxEntries = Number.MAX_SAFE_INTEGER) {
             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) {
@@ -57,7 +58,7 @@ export function decodeSeqRanges(value, maxEntries = Number.MAX_SAFE_INTEGER) {
             throw new TypeError('sourceEventSeqs range exceeds its event sequence');
         }
         for (let seq = start; seq <= end; seq += 1)
-            decoded.push(seq);
+            decoded.push(SessionSeq(seq));
         hasRange = true;
     }
     if (hasRange && !isStrictlyIncreasing(decoded)) {

package/lib/types/surface.d.ts

@@ -8,6 +8,7 @@
  * @module @deepseek-ai/dsh-session/surface
  */
 import type { Message } from '@deepseek-ai/dsh-llm';
+import { SessionLogOffset, SessionSeq } from './types.ts';
 import type { SessionEvent, SurfaceEvent, SurfaceOp } from './types.ts';
 /**
  * Whether an event type can join the model-visible surface.
@@ -64,25 +65,25 @@ export declare function deriveEventMessage(event: SessionEvent): Message | null;
 /** One replacement operation observed while folding a session surface. */
 export interface SurfaceFoldReplacement {
     /** Seq of the event that replaced the prior surface range. */
-    seq: number;
+    seq: SessionSeq;
     /** Declared inclusive start seq of the replaced surface range. */
-    start: number;
+    start: SessionSeq;
     /** Declared inclusive end seq of the replaced surface range. */
-    end: number;
+    end: SessionSeq;
     /** Actual surface entries removed by the operation, in surface order. */
-    shadowedSeqs: number[];
+    shadowedSeqs: SessionSeq[];
 }
 /** Complete result of replaying the surface operations in a session log. */
 export interface SurfaceFoldResult {
     /** Current surface event sequences in model-visible order. */
-    nodes: number[];
+    nodes: SessionSeq[];
     /** Replacement operations in event order. */
     replacements: SurfaceFoldReplacement[];
 }
 /** Readonly live projection of the message-producing session events. */
 export interface SessionSurface {
     /** Current surface event sequences in model-visible order. */
-    readonly nodes: readonly number[];
+    readonly nodes: readonly SessionSeq[];
     /** Monotonic count of committed positional replacements. */
     readonly replaceGeneration: number;
 }
@@ -107,7 +108,7 @@ export declare class SurfaceManager implements SessionSurface {
      * @param log - Contiguous complete log or loaded event window.
      * @param baseSeq - Absolute sequence of the window's first event.
      */
-    constructor(log: readonly SessionEvent[], baseSeq?: number);
+    constructor(log: readonly SessionEvent[], baseSeq?: SessionLogOffset);
     /**
      * Validate the next candidate without mutating the committed surface.
      * @param event - candidate event that has not entered the log yet.
@@ -116,7 +117,7 @@ export declare class SurfaceManager implements SessionSurface {
     /** Monotonic count of folded positional replacements. */
     get replaceGeneration(): number;
     /** Surface event sequences in model-visible order. */
-    get nodes(): readonly number[];
+    get nodes(): readonly SessionSeq[];
     /** Fold events appended since the previous access. */
     private _processDelta;
 }

package/lib/types/surface.js

@@ -7,6 +7,7 @@
  *
  * @module @deepseek-ai/dsh-session/surface
  */
+import { SessionLogOffset, SessionSeq } from "./types.js";
 /** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set([
     'user/message',
@@ -107,7 +108,10 @@ 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) {
@@ -303,7 +307,7 @@ export 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 !== undefined)
             replacements.push(replacement);
     }
@@ -323,10 +327,10 @@ export class SurfaceManager {
      * @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.
@@ -335,7 +339,7 @@ export class SurfaceManager {
     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,
@@ -366,11 +370,11 @@ export class SurfaceManager {
                 applySurfacePlan(this._state, pending.plan);
             }
             else {
-                applySurfaceEvent(this._state, event, seq, this.log, this.baseSeq);
+                applySurfaceEvent(this._state, event, SessionSeq(seq), this.log, this.baseSeq);
             }
             if (pending !== undefined && pending.expectedSeq <= seq)
                 this._pendingPlan = undefined;
-            this._lastProcessedSeq = seq;
+            this._lastProcessedSeq = SessionSeq(seq);
         }
     }
 }