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

package/lib/types/index.d.ts

@@ -11,13 +11,13 @@ 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, SessionSeedEventState, SurfaceIntent, SurfaceEventType } from './types.ts';
-import type { SessionSurface } from './surface.ts';
+import type { SessionSurface, SessionMessageProjection } from './surface.ts';
 export * from './types.ts';
 export { SessionPreparation } from './preparation.ts';
 export type { SessionPreparationOptions } from './preparation.ts';
 export type { AssistantMessage, SystemMessage, ToolResultMessage, UserMessage } from '@deepseek-ai/dsh-llm';
 export { interruptedTurnClosers, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from './repair.ts';
-export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts';
+export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult, SessionMessageProjection, SessionMessageProjectionContext } from './surface.ts';
 export { deriveEventMessage, foldSurface, isAppendSurfaceEvent, isReplacementSurfaceEvent, isSurfaceEvent, isSurfaceEligibleType } from './surface.ts';
 export { canonicalHeader, foldRequestHeader, headerEquals } from './request-header.ts';
 export { KNOWN_SESSION_EVENT_TYPES } from './known-event-types.ts';
@@ -150,9 +150,11 @@ export declare class Session {
      * @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.
+     * @param projections - pure interpreters for plugin-owned message changes.
      * @returns a detached session.
+     * @throws when a seed event requires a missing message interpreter or fails validation.
      */
-    static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader, inheritedEventCount?: SessionLogOffset): Session;
+    static create(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader, inheritedEventCount?: SessionLogOffset, projections?: readonly SessionMessageProjection[]): Session;
     /**
      * Restore a detached session by adopting an independently owned or deeply frozen seed.
      * Runtime-required event fields, event envelopes, sequence continuity, surface
@@ -164,14 +166,18 @@ export declare class Session {
      * @param header - independently owned storage metadata.
      * @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
      * @param eventState - aliasing state carried from the operation that produced the seed.
+     * @param projections - pure interpreters for plugin-owned message changes.
      * @returns a restored detached session.
+     * @throws when a seed event requires a missing message interpreter or fails validation.
      */
-    static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader, inheritedEventCount: SessionLogOffset, eventState: SessionSeedEventState): Session;
+    static fromRestore(id: SessionId, seed: readonly SessionEvent[], header: SessionHeader, inheritedEventCount: SessionLogOffset, eventState: SessionSeedEventState, projections?: readonly SessionMessageProjection[]): Session;
     private constructor();
     /** Cached immutable full snapshot of the private append-only log. */
     private eventsSnapshot;
     /**
      * Return the immutable event stored at one exact sequence number.
+     * @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+     * See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
      * @param seq - event sequence number.
      * @returns the accepted event, or undefined when the log does not contain it.
      */
@@ -180,6 +186,8 @@ export declare class Session {
      * 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.
+     * @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+     * See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
      * @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.
@@ -187,6 +195,8 @@ export declare class Session {
     snapshotEvents(fromSeq?: SessionLogOffset, toSeqExclusive?: SessionLogOffset): readonly SessionEvent[];
     /**
      * Return this Session's events after its fork-inherited prefix.
+     * @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+     * See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
      * @returns a fresh array containing child-owned events in log order.
      */
     ownEvents(): readonly SessionEvent[];
@@ -262,7 +272,7 @@ export declare class Session {
     private derived;
     /** Surface position (nodes projected) the cache has reached. */
     private derivedNodes;
-    /** {@link SurfaceManager.replaceGeneration} the cache was built under. */
+    /** {@link SurfaceManager.contentGeneration} the cache was built under. */
     private derivedGeneration;
     /**
      * Derive the LLM message history by walking the ordered sequences of
@@ -271,21 +281,21 @@ export declare class Session {
      * append records its `surfaceOp`, so a raw event with no marker (a chunk, a
      * turn boundary) is correctly absent, and a compaction `replace` deletes the
      * shadowed nodes from the derivation. The projection rules are
-     * {@link deriveEventMessage}, folded per node.
+     * {@link deriveEventMessage}, with logged message projections applied
+     * without changing node membership or message identity.
      *
-     * CACHED: each surface node is projected exactly once, when first seen — a
-     * call costs O(new nodes), and a surface rewrite (a `replace`;
-     * {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is
+     * CACHED: pure tail growth costs O(new nodes); a replacement or message projection
+     * ({@link SessionSurface.contentGeneration}) rebuilds. The returned array is
      * a fresh snapshot per call (later appends never grow an array a caller
      * already holds); the `Message` objects in it are SHARED and **deep-frozen**.
-     * Their content reuses the already frozen durable event data, so the cache
-     * needs no second deep clone and consumers still cannot mutate the log.
+     * Unchanged content reuses frozen event data; projected blocks are frozen
+     * derived copies. Consumers cannot mutate the log through either form.
      * @returns a fresh array of the shared, frozen derived history.
      */
     deriveMessages(): Message[];
     /**
-     * Instance face of the pure per-node `deriveEventMessage` export from
-     * `surface.ts`.
+     * Project one event with all committed message projections applied.
+     * The original durable event remains unchanged.
      * @param event - the event to project.
      * @returns the derived message, or null when the event produces none.
      */
@@ -317,6 +327,17 @@ export declare class SessionForkError extends Error {
 export declare class SessionStore extends Service {
     private store;
     private counter;
+    private readonly projections;
+    /** Borrowed definitions for detached replay; contributions live until their registering fibers unload. */
+    get messageProjections(): readonly SessionMessageProjection[];
+    /**
+     * Register one event interpreter for live creation, restore, and fork.
+     * Disposing the contribution makes sessions that used it refuse further derivation.
+     * @param projection - pure definition owned by the event's plugin.
+     * @returns the fiber-owned disposer.
+     * @throws when another definition already owns this event type.
+     */
+    registerMessageProjection(projection: SessionMessageProjection): () => Promise<void>;
     constructor(ctx: Context);
     /**
      * Create a session owned by the calling fiber: disposing that fiber stops

package/lib/types/index.js

@@ -11,7 +11,7 @@ import { brandString } from '@deepseek-ai/dsh-brand';
 import { assertNever, deepFreeze, snapshotJsonValue } from '@deepseek-ai/dsh-util-values';
 import { scopeOf, scopeTarget } from '@deepseek-ai/dsh-scope';
 import { SESSION_FORMAT_VERSION, SessionLogOffset, SessionSeq } from "./types.js";
-import { deriveEventMessage, SurfaceManager, validateSessionEventData, validateSurfaceMetadata } from "./surface.js";
+import { SurfaceManager, validateSessionEventData, validateSurfaceMetadata } from "./surface.js";
 import { foldRequestHeader } from "./request-header.js";
 export * from "./types.js";
 export { SessionPreparation } from "./preparation.js";
@@ -337,7 +337,7 @@ const attachments = new WeakMap();
 export class Session {
     log = [];
     /** Single incremental owner of surface acceptance and projection state. */
-    surfaceManager = new SurfaceManager(this.log);
+    surfaceManager;
     /** The ordered surface over this session's event log. */
     get surface() {
         return this.surfaceManager;
@@ -388,10 +388,12 @@ export class Session {
      * @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.
+     * @param projections - pure interpreters for plugin-owned message changes.
      * @returns a detached session.
+     * @throws when a seed event requires a missing message interpreter or fails validation.
      */
-    static create(id, seed, header, inheritedEventCount) {
-        return new Session(id, seed, header, 'snapshot', inheritedEventCount);
+    static create(id, seed, header, inheritedEventCount, projections) {
+        return new Session(id, seed, header, 'snapshot', inheritedEventCount, projections);
     }
     /**
      * Restore a detached session by adopting an independently owned or deeply frozen seed.
@@ -404,12 +406,15 @@ export class Session {
      * @param header - independently owned storage metadata.
      * @param inheritedEventCount - exact fork-inherited prefix length decoded from storage.
      * @param eventState - aliasing state carried from the operation that produced the seed.
+     * @param projections - pure interpreters for plugin-owned message changes.
      * @returns a restored detached session.
+     * @throws when a seed event requires a missing message interpreter or fails validation.
      */
-    static fromRestore(id, seed, header, inheritedEventCount, eventState) {
-        return new Session(id, seed, header, eventState, inheritedEventCount);
+    static fromRestore(id, seed, header, inheritedEventCount, eventState, projections) {
+        return new Session(id, seed, header, eventState, inheritedEventCount, projections);
     }
-    constructor(id, seed, header, mode = 'snapshot', suppliedInheritedEventCount) {
+    constructor(id, seed, header, mode = 'snapshot', suppliedInheritedEventCount, projections = []) {
+        this.surfaceManager = new SurfaceManager(this.log, SessionLogOffset(0), projections);
         const restoredHeader = mode === 'snapshot' ? undefined : validateRestoredSessionHeader(id, header);
         if (seed !== undefined) {
             // Validate the seed to the SAME invariants `append` enforces, so a
@@ -475,6 +480,8 @@ export class Session {
     eventsSnapshot;
     /**
      * Return the immutable event stored at one exact sequence number.
+     * @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+     * See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
      * @param seq - event sequence number.
      * @returns the accepted event, or undefined when the log does not contain it.
      */
@@ -485,6 +492,8 @@ export class Session {
      * 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.
+     * @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+     * See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
      * @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.
@@ -498,9 +507,12 @@ export class Session {
     }
     /**
      * Return this Session's events after its fork-inherited prefix.
+     * @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited.
+     * See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).
      * @returns a fresh array containing child-owned events in log order.
      */
     ownEvents() {
+        // oxlint-disable-next-line typescript/no-deprecated -- Deprecated reader delegates to the deprecated range read.
         return this.snapshotEvents(this.inheritedEventCount);
     }
     /**
@@ -647,7 +659,7 @@ export class Session {
     derived = [];
     /** Surface position (nodes projected) the cache has reached. */
     derivedNodes = 0;
-    /** {@link SurfaceManager.replaceGeneration} the cache was built under. */
+    /** {@link SurfaceManager.contentGeneration} the cache was built under. */
     derivedGeneration = 0;
     /**
      * Derive the LLM message history by walking the ordered sequences of
@@ -656,21 +668,21 @@ export class Session {
      * append records its `surfaceOp`, so a raw event with no marker (a chunk, a
      * turn boundary) is correctly absent, and a compaction `replace` deletes the
      * shadowed nodes from the derivation. The projection rules are
-     * {@link deriveEventMessage}, folded per node.
+     * {@link deriveEventMessage}, with logged message projections applied
+     * without changing node membership or message identity.
      *
-     * CACHED: each surface node is projected exactly once, when first seen — a
-     * call costs O(new nodes), and a surface rewrite (a `replace`;
-     * {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is
+     * CACHED: pure tail growth costs O(new nodes); a replacement or message projection
+     * ({@link SessionSurface.contentGeneration}) rebuilds. The returned array is
      * a fresh snapshot per call (later appends never grow an array a caller
      * already holds); the `Message` objects in it are SHARED and **deep-frozen**.
-     * Their content reuses the already frozen durable event data, so the cache
-     * needs no second deep clone and consumers still cannot mutate the log.
+     * Unchanged content reuses frozen event data; projected blocks are frozen
+     * derived copies. Consumers cannot mutate the log through either form.
      * @returns a fresh array of the shared, frozen derived history.
      */
     deriveMessages() {
         const surface = this.surface;
         const nodes = surface.nodes;
-        const generation = surface.replaceGeneration;
+        const generation = surface.contentGeneration;
         if (generation !== this.derivedGeneration) {
             this.derived = [];
             this.derivedNodes = 0;
@@ -691,13 +703,13 @@ export class Session {
         return [...this.derived];
     }
     /**
-     * Instance face of the pure per-node `deriveEventMessage` export from
-     * `surface.ts`.
+     * Project one event with all committed message projections applied.
+     * The original durable event remains unchanged.
      * @param event - the event to project.
      * @returns the derived message, or null when the event produces none.
      */
     deriveEventMessage(event) {
-        return deriveEventMessage(event);
+        return this.surfaceManager.deriveEventMessage(event);
     }
 }
 /** Typed error for session fork rejections. */
@@ -719,6 +731,27 @@ export class SessionForkError extends Error {
 export class SessionStore extends Service {
     store = new Map();
     counter = 0;
+    projections = [];
+    /** Borrowed definitions for detached replay; contributions live until their registering fibers unload. */
+    get messageProjections() {
+        return this.projections;
+    }
+    /**
+     * Register one event interpreter for live creation, restore, and fork.
+     * Disposing the contribution makes sessions that used it refuse further derivation.
+     * @param projection - pure definition owned by the event's plugin.
+     * @returns the fiber-owned disposer.
+     * @throws when another definition already owns this event type.
+     */
+    registerMessageProjection(projection) {
+        if (this.projections.some(item => item.type === projection.type)) {
+            throw new Error(`session message projection "${projection.type}" is already registered`);
+        }
+        return this.ctx.effect(() => {
+            this.projections.push(projection);
+            return () => { this.projections.splice(this.projections.indexOf(projection), 1); };
+        }, 'sessions.registerMessageProjection()');
+    }
     constructor(ctx) {
         super(ctx, 'sessions');
         ctx.inject(['typert'], (typeCtx) => {
@@ -800,7 +833,7 @@ export class SessionStore extends Service {
             switch (eventState) {
                 case 'detached':
                 case 'shared-frozen':
-                    return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState);
+                    return Session.fromRestore(sessionId, options.seed, options.meta, options.inheritedEventCount, eventState, this.projections);
                 case undefined:
                     break;
                 /* v8 ignore next -- closed-union exhaustiveness guard */
@@ -821,7 +854,7 @@ export class SessionStore extends Service {
             ...meta?.delegationDepth === undefined ? {} : { delegationDepth: meta.delegationDepth },
             ...meta?.agentPreset === undefined ? {} : { agentPreset: meta.agentPreset },
         };
-        return Session.create(sessionId, seed, header, options?.inheritedEventCount);
+        return Session.create(sessionId, seed, header, options?.inheritedEventCount, this.projections);
     }
     /**
      * Enter a {@link prepare}d session into the store: install the module-private
@@ -1032,6 +1065,7 @@ export class SessionStore extends Service {
         });
     }
     _forkSeed(session, requestedBoundary) {
+        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
         const lastEvent = session.snapshotEvents().at(-1);
         let boundary;
         if (requestedBoundary !== undefined) {
@@ -1049,10 +1083,12 @@ export class SessionStore extends Service {
             const lastSeq = lastEvent?.seq;
             throw new SessionForkError(`fork boundary ${boundary} does not exist in session "${session.id}" (last seq: ${lastSeq ?? 'none'})`, 'INVALID_BOUNDARY');
         }
+        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
         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');
         }
+        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
         const events = session.snapshotEvents(SessionLogOffset(0), SessionLogOffset(boundary + 1));
         const lastTurnBoundary = events
             .findLast(event => event.type === 'turn/start' || event.type === 'turn/end');

package/lib/types/invariant.js

@@ -163,6 +163,7 @@ const install = Object.assign((ctx, fail) => {
     const seedSession = (session) => {
         const trace = freshTrace();
         traces.set(session, trace);
+        // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
         for (const event of session.snapshotEvents()) {
             applyTransition(trace, validateEvent(trace, event, fail));
         }

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

@@ -19,4 +19,6 @@
  * `.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md`.
  */
 export declare const KNOWN_SESSION_EVENT_TYPES: ReadonlySet<string>;
+/** Event types whose model-visible effects require an explicit pure interpreter. */
+export declare const MESSAGE_PROJECTION_EVENT_TYPES: ReadonlySet<string>;
 //# sourceMappingURL=known-event-types.d.ts.map

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

@@ -39,6 +39,7 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'goal/change',
     'hook/invoked',
     'hook/result',
+    'image/offload',
     'llm/retry',
     'llm/retry-started',
     'model/selection',
@@ -75,5 +76,10 @@ export const KNOWN_SESSION_EVENT_TYPES = new Set([
     'turn/start',
     'user/message',
     'web/deepseek-search-llm-request',
+    'workspace/changes',
+]);
+/** Event types whose model-visible effects require an explicit pure interpreter. */
+export const MESSAGE_PROJECTION_EVENT_TYPES = new Set([
+    'image/offload',
 ]);
 //# sourceMappingURL=known-event-types.js.map

package/lib/types/surface.d.ts

@@ -9,7 +9,32 @@
  */
 import type { Message } from '@deepseek-ai/dsh-llm';
 import { SessionLogOffset, SessionSeq } from './types.ts';
-import type { SessionEvent, SurfaceEvent, SurfaceOp } from './types.ts';
+import type { SessionEvent, SessionEventType, SurfaceEvent, SurfaceOp } from './types.ts';
+/** Readonly history immediately before a message-projection event. */
+export interface SessionMessageProjectionContext {
+    /** Current message-producing event sequences in model-visible order. */
+    nodes: readonly SessionSeq[];
+    /** Contiguous event window; entries at or beyond the candidate seq are not committed inputs. */
+    events: readonly SessionEvent[];
+    /** Absolute sequence of the window's first event. */
+    baseSeq: SessionLogOffset;
+    /** Previously projected messages keyed by their original event sequences. */
+    messages: ReadonlyMap<SessionSeq, Message>;
+}
+/** Pure interpretation of one plugin-owned event that changes existing message content. */
+export interface SessionMessageProjection<T extends SessionEventType = SessionEventType> {
+    /** Event interpreted by this definition; declare it with `@messageProjection` in SessionEventMap. */
+    type: T;
+    /**
+     * Validate the complete durable decision before returning any updates. Preserve
+     * message identities and publish immutable copies without mutating the input.
+     * @param event - candidate event, not yet applied to the supplied history.
+     * @param context - history preceding this decision.
+     * @returns changed current messages keyed by their original sequences.
+     * @throws when the durable decision cannot be applied to this history.
+     */
+    project(event: SessionEvent<T>, context: SessionMessageProjectionContext): ReadonlyMap<SessionSeq, Message>;
+}
 /**
  * Whether an event type can join the model-visible surface.
  * @param type - event type to test.
@@ -51,17 +76,16 @@ export declare function isReplacementSurfaceEvent(event: SessionEvent): event is
 /**
  * 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 declare function deriveEventMessage(event: SessionEvent): Message | null;
+export declare function deriveEventMessage(event: SessionEvent, projectedMessages?: ReadonlyMap<SessionSeq, Message>): Message | null;
 /**
  * Reject noncanonical request-header fields and contradictory tool failure metadata.
  * This does not validate complete event payloads or embedded provider streams.
@@ -87,6 +111,8 @@ export interface SurfaceFoldResult {
     nodes: SessionSeq[];
     /** Replacement operations in event order. */
     replacements: SurfaceFoldReplacement[];
+    /** Immutable projected messages, keyed by their original event sequences. */
+    projectedMessages: ReadonlyMap<SessionSeq, Message>;
 }
 /** Readonly live projection of the message-producing session events. */
 export interface SessionSurface {
@@ -94,6 +120,8 @@ export interface SessionSurface {
     readonly nodes: readonly SessionSeq[];
     /** Monotonic count of committed positional replacements. */
     readonly replaceGeneration: number;
+    /** Monotonic count of committed replacements and plugin-owned message changes. */
+    readonly contentGeneration: number;
 }
 /**
  * Validate one event's surface metadata without checking membership in a log or surface.
@@ -106,14 +134,16 @@ export declare function validateSurfaceMetadata(event: SessionEvent): SurfaceOp
 /**
  * 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 declare function foldSurface(events: readonly SessionEvent[]): SurfaceFoldResult;
+export declare function foldSurface(events: readonly SessionEvent[], projections?: readonly SessionMessageProjection[]): SurfaceFoldResult;
 /** Incremental ordered surface view and append-boundary validator. */
 export declare class SurfaceManager implements SessionSurface {
     private log;
     private readonly baseSeq;
+    private readonly projections;
     /** Shared transition state; replacement history is not retained. */
     private _state;
     /** Last processed absolute seq. */
@@ -123,8 +153,9 @@ 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.
+     * @param projections - live borrowed definitions; removing a used definition invalidates further reads.
      */
-    constructor(log: readonly SessionEvent[], baseSeq?: SessionLogOffset);
+    constructor(log: readonly SessionEvent[], baseSeq?: SessionLogOffset, projections?: readonly SessionMessageProjection[]);
     /**
      * Validate the next candidate without mutating the committed surface.
      * @param event - candidate event that has not entered the log yet.
@@ -132,9 +163,19 @@ export declare class SurfaceManager implements SessionSurface {
     validateNext(event: SessionEvent): void;
     /** Monotonic count of folded positional replacements. */
     get replaceGeneration(): number;
+    /** Monotonic count of committed changes to existing model-visible content. */
+    get contentGeneration(): number;
+    /**
+     * 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: SessionEvent): Message | null;
     /** Surface event sequences in model-visible order. */
     get nodes(): readonly SessionSeq[];
     /** Fold events appended since the previous access. */
     private _processDelta;
+    /** Cached messages cannot outlive the definitions that interpreted their log. */
+    private _assertProjections;
 }
 //# sourceMappingURL=surface.d.ts.map