@deepseek-ai/dsh-session 0.1.5-rc.2 → 0.1.6-alpha.2

package/lib/types/surface.js

@@ -8,7 +8,7 @@
  * @module @deepseek-ai/dsh-session/surface
  */
 import { SessionLogOffset, SessionSeq } from "./types.js";
-import { KNOWN_SESSION_EVENT_TYPES } from "./known-event-types.js";
+import { KNOWN_SESSION_EVENT_TYPES, MESSAGE_PROJECTION_EVENT_TYPES } from "./known-event-types.js";
 /** Runtime counterpart of the message-producing event union. */
 const SURFACE_EVENT_TYPES = new Set([
     'system/message',
@@ -62,17 +62,19 @@ export function isReplacementSurfaceEvent(event) {
 /**
  * Project a single event into the LLM message it derives to, or null when it
  * produces none — a non-surface event (attempt, boundary, log-only record) or an
- * empty-content assistant/message (which exists only to host usage). This is
- * THE per-node projection rule: `Session.deriveMessages` folds it over the
- * live surface, external reconstructors and pure projections fold the same
- * function over a log prefix's surface to rebuild the exact messages any
- * request was built from. The returned message is the already frozen message
- * nested in the event wrapper and shared by delivery, durable history, and
- * model requests.
+ * empty-content assistant/message (which exists only to host usage). A caller
+ * reconstructing model input supplies the same prefix's `projectedMessages`
+ * from {@link foldSurface}; without that map this function reads original
+ * event content. Session instance methods apply the live projection. Messages
+ * are immutable and unchanged content retains its durable identity.
  * @param event - the event to project.
+ * @param projectedMessages - message projections from the same log prefix's surface fold.
  * @returns the derived message, or null when the event produces none.
  */
-export function deriveEventMessage(event) {
+export function deriveEventMessage(event, projectedMessages) {
+    const projected = projectedMessages?.get(event.seq);
+    if (projected !== undefined)
+        return projected;
     // Intentionally non-exhaustive: only message-producing events derive
     // history; turn/step boundaries, failed attempts, and errors are trace/replay
     // data.
@@ -152,7 +154,7 @@ export function validateSessionEventData(event, subject) {
 }
 /** Create an empty surface fold state. */
 function createFoldState() {
-    return { nodes: [], replaceGeneration: 0 };
+    return { nodes: [], replaceGeneration: 0, contentGeneration: 0, projectedMessages: new Map(), projections: new Set() };
 }
 /** Whether a runtime value is a non-negative safe event sequence. */
 function isEventSeq(value) {
@@ -202,7 +204,7 @@ function surfaceOpOf(event) {
     return op;
 }
 /** Validate cited source-event seqs against prior log entries and the replacement range. */
-function assertProvenance(event, shadowedSeqs) {
+function assertSourceEventReferences(event, shadowedSeqs) {
     const raw = event.sourceEventSeqs;
     if (event.type === 'assistant/message' && raw !== undefined) {
         throw new Error('assistant/message embeds its source stream and cannot carry sourceEventSeqs');
@@ -250,7 +252,7 @@ export function validateSurfaceMetadata(event) {
         throw new Error(`surface replace at seq ${event.seq}: startSeq and endSeq must reference earlier events`);
     }
     if (op !== undefined)
-        assertProvenance(event, []);
+        assertSourceEventReferences(event, []);
     return op;
 }
 /** Locate one replacement range without mutating the current fold state. */
@@ -339,18 +341,27 @@ function assertSystemHeadRewrite(event, state, startIdx, shadowedSeqs, events, b
     }
 }
 /** Validate one event at its replay boundary and prepare its atomic fold transition. */
-function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
+function planSurfaceEvent(state, event, expectedSeq, events, baseSeq, projections) {
     if (event.seq !== expectedSeq) {
         throw new Error(`session event seq ${event.seq} is not contiguous; expected ${expectedSeq}`);
     }
     const surfaceOp = validateSurfaceMetadata(event);
+    const projection = projections.find(item => item.type === event.type);
+    if (projection !== undefined) {
+        return { kind: 'project', projection, messages: projection.project(event, {
+                nodes: state.nodes, events, baseSeq, messages: state.projectedMessages,
+            }) };
+    }
+    if (MESSAGE_PROJECTION_EVENT_TYPES.has(event.type)) {
+        throw new Error(`session event "${event.type}" requires a message projection; load its owning plugin or supply its projection definition`);
+    }
     if (surfaceOp === undefined)
         return;
     if (surfaceOp === 'append') {
         return { kind: 'append', seq: event.seq };
     }
     const range = replacementRange(state, surfaceOp);
-    assertProvenance(event, range.shadowedSeqs);
+    assertSourceEventReferences(event, range.shadowedSeqs);
     assertToolResultRewrite(event, range.shadowedSeqs, events, baseSeq);
     assertSystemHeadRewrite(event, state, range.startIdx, range.shadowedSeqs, events, baseSeq);
     return {
@@ -362,8 +373,8 @@ function planSurfaceEvent(state, event, expectedSeq, events, baseSeq) {
     };
 }
 /** Apply one event and return replacement metadata only when one occurred. */
-function applySurfaceEvent(state, event, expectedSeq, events, baseSeq) {
-    const plan = planSurfaceEvent(state, event, expectedSeq, events, baseSeq);
+function applySurfaceEvent(state, event, expectedSeq, events, baseSeq, projections) {
+    const plan = planSurfaceEvent(state, event, expectedSeq, events, baseSeq, projections);
     return applySurfacePlan(state, plan);
 }
 /** Commit one previously validated surface transition. */
@@ -374,6 +385,13 @@ function applySurfacePlan(state, plan) {
     else if (plan?.kind === 'replace') {
         state.nodes.splice(plan.startIdx, plan.endIdx - plan.startIdx + 1, plan.seq);
         state.replaceGeneration += 1;
+        state.contentGeneration += 1;
+    }
+    else if (plan?.kind === 'project') {
+        for (const [seq, message] of plan.messages)
+            state.projectedMessages.set(seq, message);
+        state.projections.add(plan.projection);
+        state.contentGeneration += 1;
     }
     if (plan?.kind !== 'replace')
         return;
@@ -387,23 +405,25 @@ function applySurfacePlan(state, plan) {
 /**
  * Replay a complete session log through the canonical surface fold.
  * @param events - session events in contiguous seq order.
+ * @param projections - pure interpreters for plugin-owned message changes; required definitions must be supplied.
  * @returns detached current sequences and replacement history.
- * @throws when an event violates surface metadata, source-event references, range, or tool-result rewrite rules.
+ * @throws when an interpreter is missing or an event violates its projection, surface metadata, source attribution, or replacement rules.
  */
-export function foldSurface(events) {
+export function foldSurface(events, projections = []) {
     const state = createFoldState();
     const replacements = [];
     for (const [index, event] of events.entries()) {
-        const replacement = applySurfaceEvent(state, event, SessionSeq(index), events, SessionLogOffset(0));
+        const replacement = applySurfaceEvent(state, event, SessionSeq(index), events, SessionLogOffset(0), projections);
         if (replacement !== undefined)
             replacements.push(replacement);
     }
-    return { nodes: [...state.nodes], replacements };
+    return { nodes: [...state.nodes], replacements, projectedMessages: new Map(state.projectedMessages) };
 }
 /** Incremental ordered surface view and append-boundary validator. */
 export class SurfaceManager {
     log;
     baseSeq;
+    projections;
     /** Shared transition state; replacement history is not retained. */
     _state = createFoldState();
     /** Last processed absolute seq. */
@@ -413,10 +433,12 @@ export class SurfaceManager {
     /**
      * @param log - Contiguous complete log or loaded event window.
      * @param baseSeq - Absolute sequence of the window's first event.
+     * @param projections - live borrowed definitions; removing a used definition invalidates further reads.
      */
-    constructor(log, baseSeq = SessionLogOffset(0)) {
+    constructor(log, baseSeq = SessionLogOffset(0), projections = []) {
         this.log = log;
         this.baseSeq = baseSeq;
+        this.projections = projections;
         this._lastProcessedSeq = baseSeq === 0 ? -1 : SessionSeq(baseSeq - 1);
     }
     /**
@@ -424,23 +446,44 @@ export class SurfaceManager {
      * @param event - candidate event that has not entered the log yet.
      */
     validateNext(event) {
+        this._assertProjections();
         if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1)
             this._processDelta();
         const expectedSeq = SessionSeq(this.baseSeq + this.log.length);
         this._pendingPlan = {
             event,
             expectedSeq,
-            plan: planSurfaceEvent(this._state, event, expectedSeq, this.log, this.baseSeq),
+            plan: planSurfaceEvent(this._state, event, expectedSeq, this.log, this.baseSeq, this.projections),
         };
     }
     /** Monotonic count of folded positional replacements. */
     get replaceGeneration() {
+        this._assertProjections();
         if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1)
             this._processDelta();
         return this._state.replaceGeneration;
     }
+    /** Monotonic count of committed changes to existing model-visible content. */
+    get contentGeneration() {
+        this._assertProjections();
+        if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1)
+            this._processDelta();
+        return this._state.contentGeneration;
+    }
+    /**
+     * Project one message with every committed message projection applied.
+     * @param event - message-producing or log-only event.
+     * @returns its immutable projected message, or null when it produces none.
+     */
+    deriveEventMessage(event) {
+        this._assertProjections();
+        if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1)
+            this._processDelta();
+        return deriveEventMessage(event, this._state.projectedMessages);
+    }
     /** Surface event sequences in model-visible order. */
     get nodes() {
+        this._assertProjections();
         if (this._lastProcessedSeq < this.baseSeq + this.log.length - 1)
             this._processDelta();
         return this._state.nodes;
@@ -457,12 +500,26 @@ export class SurfaceManager {
                 applySurfacePlan(this._state, pending.plan);
             }
             else {
-                applySurfaceEvent(this._state, event, SessionSeq(seq), this.log, this.baseSeq);
+                applySurfaceEvent(this._state, event, SessionSeq(seq), this.log, this.baseSeq, this.projections);
             }
             if (pending !== undefined && pending.expectedSeq <= seq)
                 this._pendingPlan = undefined;
             this._lastProcessedSeq = SessionSeq(seq);
         }
     }
+    /** Cached messages cannot outlive the definitions that interpreted their log. */
+    _assertProjections() {
+        const candidate = this._pendingPlan;
+        const pending = candidate !== undefined && this.log[candidate.expectedSeq - this.baseSeq] === candidate.event
+            ? candidate.plan : undefined;
+        const required = pending?.kind === 'project'
+            ? [...this._state.projections, pending.projection]
+            : this._state.projections;
+        for (const projection of required) {
+            if (!this.projections.includes(projection)) {
+                throw new Error(`session message projection "${projection.type}" was removed or replaced; restore the session with its owning plugin`);
+            }
+        }
+    }
 }
 //# sourceMappingURL=surface.js.map

package/lib/types/types.d.ts

@@ -339,7 +339,9 @@ export interface SessionEventMap {
     };
     /**
      * A completed tool call's model-facing result, optional internal failure
-     * identity, and optional tool-private `meta` presentation payload. `meta` is
+     * identity and user-facing reason, and optional tool-private `meta`
+     * presentation payload. The reason remains outside the model-facing message.
+     * `meta` is
      * opaque to the core (the producing tool owns its shape and reads it back in
      * `presentResult`) but MUST be JSON-serializable: `Session.append`
      * runtime-validates all event data with `isJsonValue`, so a non-serializable
@@ -352,10 +354,14 @@ export interface SessionEventMap {
         turn: number;
         step: number;
         message: ToolResultMessage;
-        /** Optional failure identity; allowed only when the tool-result block has `isError: true`. */
+        /**
+         * Optional failure identity and raw user-facing reason, outside model content;
+         * allowed only when the tool-result block has `isError: true`.
+         */
         error?: {
             name: string;
             code: string;
+            reason?: string;
         };
         meta?: JsonValue;
     };

package/package.json

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