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

package/lib/types/types.d.ts

@@ -1,4 +1,4 @@
-import { type Branded } from '@deepseek-ai/dsh-brand';
+import { type Branded, type BrandedNumber } from '@deepseek-ai/dsh-brand';
 import type { AssistantMessage, ToolCallId, LlmCallConfig, LlmCallConfigAdapterDefaults, LlmFailure, StreamChunk, TokenUsage, ToolResultMessage, ToolSchema, UserMessage } from '@deepseek-ai/dsh-llm';
 import type { JsonValue } from '@deepseek-ai/dsh-util-values';
 /** Identifies one session in the store (and its persistence artifacts). */
@@ -9,6 +9,26 @@ export type SessionId = Branded<'SessionId'>;
  * @returns the same string with the session-id brand.
  */
 export declare function SessionId(id: string): SessionId;
+/** Sequence number of one existing event in a Session log. */
+export type SessionSeq = BrandedNumber<'SessionSeq'>;
+/**
+ * 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.
+ */
+export declare function SessionSeq(value: number): SessionSeq;
+/** A Session log gap, prefix length, or read offset, which may equal the event count. */
+export type SessionLogOffset = BrandedNumber<'SessionLogOffset'>;
+/**
+ * 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.
+ */
+export declare function SessionLogOffset(value: number): SessionLogOffset;
+/** Inclusive Session event watermark, or `-1` before any event exists. */
+export type SessionSeqCursor = SessionSeq | -1;
+/** One existing Session event position, or explicit absence. */
+export type OptionalSessionSeq = SessionSeq | null;
 /**
  * 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
@@ -52,10 +72,10 @@ export interface SessionHeader {
     /** The session this one was forked from (seed lineage), if any. */
     readonly parentSession?: SessionId;
     /**
-     * How many leading events were inherited through a seed. Persisting this
-     * boundary lets resume and replay distinguish parent history from child work.
+     * Whether this Session contains a fork-inherited event prefix. The exact prefix
+     * length is Session state rather than ordinary header metadata.
      */
-    readonly seedLength?: number;
+    readonly isSeeded: boolean;
     /**
      * Coarse product classification for a session created as a subagent child.
      * This is presentation metadata, not proof that the child is continuable.
@@ -84,14 +104,19 @@ export interface CreateSessionOptions {
     /** Initial replay or fork history supplied at construction. */
     readonly seed?: readonly SessionEvent[];
     /**
-     * Storage metadata read once before publication. `seedLength` is explicit
-     * because a resumed seed contains the full stored log, not only its inherited prefix.
+     * Exact fork-inherited prefix length when `meta.isSeeded` is true. A
+     * constructor seed may also contain child-owned setup events after this cut.
+     */
+    readonly inheritedEventCount?: SessionLogOffset;
+    /**
+     * Storage metadata read once before publication. `isSeeded` marks fork
+     * lineage; supplying replay history alone does not make it inherited.
      */
     readonly meta?: {
         readonly cwd?: string;
         readonly parentSession?: SessionId;
         readonly createdAt?: number;
-        readonly seedLength?: number;
+        readonly isSeeded?: boolean;
         readonly origin?: 'subagent';
         readonly delegationDepth?: number;
         readonly agentPreset?: string;
@@ -106,6 +131,8 @@ export interface RestoredSessionOptions {
     readonly seed: SessionEvent[];
     /** Fresh detached storage metadata to validate and freeze in place. */
     readonly meta: SessionHeader;
+    /** Exact number of fork-inherited leading events decoded from storage. */
+    readonly inheritedEventCount: SessionLogOffset;
     /** Select the persistence ownership-transfer path. */
     readonly seedSource: 'persistence';
 }
@@ -375,8 +402,8 @@ export type SurfaceEvent = SessionEvent<SurfaceEventType> & {
  */
 export type SurfaceOp = 'append' | {
     op: 'replace';
-    start: number;
-    end: number;
+    start: SessionSeq;
+    end: SessionSeq;
 };
 /**
  * Surface placement and cited source-event seqs for {@link Session.append}. Required on
@@ -390,7 +417,7 @@ export interface SurfaceIntent {
      * absent, the event does not record which earlier events produced the message.
      * Other surface events require a non-empty set when this field is present.
      */
-    sourceEventSeqs?: number[];
+    sourceEventSeqs?: SessionSeq[];
 }
 /**
  * One immutable entry in the session log.
@@ -409,7 +436,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
     [K in SessionEventType]: {
         type: K;
         /** Monotonic sequence number within the session. */
-        seq: number;
+        seq: SessionSeq;
         /** Unix epoch milliseconds. */
         time: number;
         data: SessionEventMap[K];
@@ -433,7 +460,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
          * provider stream; when the field is absent, the event does not record which
          * earlier events produced the message.
          */
-        sourceEventSeqs?: number[];
+        sourceEventSeqs?: SessionSeq[];
         /** How this event entered the surface; absent for non-surface events. */
         surfaceOp?: SurfaceOp;
     } : object);

package/lib/types/types.js

@@ -1,4 +1,4 @@
-import { brandString } from '@deepseek-ai/dsh-brand';
+import { brandNumber, brandString } from '@deepseek-ai/dsh-brand';
 /**
  * Brand a string as a {@link SessionId}.
  * @param id - the raw session id string.
@@ -7,6 +7,28 @@ import { brandString } from '@deepseek-ai/dsh-brand';
 export 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.
+ */
+export 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.
+ */
+export 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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session",
   "description": "Event-sourced session store for the DeepSeek Harness",
-  "version": "0.1.2-alpha.2",
+  "version": "0.1.2-alpha.4",
   "publishConfig": {
     "access": "public"
   },
@@ -45,19 +45,19 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.4"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-typert-registry": "^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-scope": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-typert-registry": "^0.1.2-alpha.4",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
-    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
-    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.2"
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.4",
+    "@deepseek-ai/dsh-util-values": "^0.1.2-alpha.4"
   }
 }