@deepseek-ai/dsh-session-persistence 0.0.1-rc.1 → 0.0.1-rc.2

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/session/session-persistence/README.md
-README.md: 391548b1b896dca14cbe4f4ae55cf4180c4e0ac2
-README.zh.md: 7213e1ee71ba418ffacc3685df371dcba33588a7
+README.md: 6e1898f8a49e54f8fe90ff27cf8571c5959f27e9
+README.zh.md: 901c41b6894d86bdc4ffb345314a3dd506e4a770

package/README.md

@@ -11,12 +11,14 @@ The persisted unit IS the existing `SessionEvent` (event-sourced model — the l
 | Method | Contract |
 |---|---|
 | `locate(meta): SessionLocation \| undefined` | Resolve an absolute per-session artifact target without I/O or materialization. Backends without an independent local artifact return `undefined`. |
+| `supportsRawArtifacts: boolean` | State explicitly whether this backend exposes one verbatim artifact per session. Consumers check this capability before calling `readRaw`; `false` is not session absence. |
+| `readRaw(id, signal?): Promise<SessionRawArtifact \| undefined>` | Read a supported backend's own artifact text verbatim, decoded from its physical encoding but never reconstructed from events. `undefined` means only that the requested artifact is absent; an unsupported backend rejects. |
 | `create(meta): Promise<void>` | Register a new session's metadata. MAY defer the physical write until the first `append` (lazy materialization). |
 | `append(id, events): Promise<void>` | Durably persist a batch. Append-only; first event `seq` == stored next-seq after any repair; rejects non-JSON-serializable data naming the offending type. |
 | `prepare(id, signal?): Promise<SessionPreparation>` | Reserve the exact unpublished Session used by resume. A coordinator reuses an earlier inspection when available, commits pending recovery, and releases an unpublished reservation back to its bounded cache on disposal. |
-| `load(id): Promise<{ meta; events }>` | Return an immutable balanced logical log after converting supported older records from the same format version and committing cold recovery. A live load first flushes its snapshot and rejects while its turn is open; a cold load preserves an interrupted final turn and durably closes it with synthetic `tool/result`/`step/end?`/`turn/end {interrupted}` events. Only a torn tail fragment is dropped; committed corruption, malformed records, and unknown `version` reject. |
+| `load(id): Promise<{ meta; events }>` | Return an immutable balanced logical log after converting supported older records from the same format version and committing cold recovery. A live load first flushes its snapshot and rejects while its turn is open; a cold load preserves an interrupted final turn and durably closes it with synthetic `tool/result`/`step/end?`/`turn/end {interrupted}` events. Only a torn tail fragment is dropped; committed corruption and malformed records reject as `SessionPersistenceCorruptionError`, while an unsupported format `version` or an event type unknown to this build (without the envelope's `ignorable` marker) refuses as `SessionFormatUnsupportedError`, naming the refusal direction and the raw log path when the backend keeps one artifact per session. |
 | `inspect(id, signal?): Promise<{ meta; events }>` | Return an upgraded, validated, deeply frozen logical view without committing recovery or publishing a Session. A cold view receives in-memory synthetic recovery closers while its physical torn tail remains untouched; an already-live view is its current immutable snapshot and may contain an open turn. Coordinator-backed implementations retain the exact cold unpublished Session in a bounded LRU for later `prepare`, but discard and reload it when the stored revision changes. Same-id inspections share an in-flight read. |
-| `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | Return valid stored events with `seq >= fromSeq` without preparation caching, truncation, closers, or coordinator state. A `fromSeq` at or past the stored end returns an empty event list; a negative or non-safe-integer `fromSeq` rejects. Seek-capable backends (SQLite) read only the suffix unless converting a supported older record requires earlier records; sequential backends (JSONL) parse the whole artifact and skip forward. Intended for checkpoint consumers that apply only events after a stored sequence number. |
+| `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | Return valid stored events with `seq >= fromSeq` without preparation caching, truncation, closers, or coordinator state. A `fromSeq` at or past the stored end returns an empty event list; a negative or non-safe-integer `fromSeq` rejects. Seek-capable backends (SQLite) read only the suffix unless converting a supported older record requires earlier records; sequential backends (JSONL) parse the whole artifact and skip forward. Unknown-type refusal follows that access pattern: a seek read checks only the returned suffix, while the sequential fallback also refuses on an unknown required event below the window. Intended for checkpoint consumers that apply only events after a stored sequence number. |
 | `list(signal?): Promise<SessionHeader[]>` | Lightweight listing from metadata, no full-log parse. The optional signal cancels backend listing work. A zero-event lazily-materialized session is absent from `list`. |
 | `listSnapshots(signal?): Promise<SessionPersistenceSnapshot[]>` | Lightweight metadata plus an opaque branded per-log revision, without loading event logs. A revision stays equal while that log and its backing store are unchanged, changes after append or mutating load repair, and cannot collide solely because two stores use the same local counter. The optional signal requests cancellation of backend discovery work; first-party backends settle any started listing work before rejecting so an awaited call is quiescent. |
 
@@ -78,6 +80,6 @@ Persistence does not mutate live request prefixes. A resumed loop can reuse prov
 
 ## Known Limitations and Deferred Work
 
-- **No deletion or retention surface** — pruning stored sessions is out-of-band backend maintenance.
+- **No deletion or retention API** — pruning stored sessions is out-of-band backend maintenance.
 - **`list()` is unpaginated and unfiltered** — it returns every stored session's header; fine for local stores, unindexed at scale.
 - **Repair-time synthetic closers are the only crash story** — a backend must synthesize `tool/result`/`step/end`/`turn/end` closers on load; there is no partial-turn resume that continues an interrupted turn instead of closing it.

package/README.zh.md

@@ -11,12 +11,14 @@
 | 方法 | 约定 |
 |---|---|
 | `locate(meta): SessionLocation \| undefined` | 在不执行 I/O 或实体化的情况下解析绝对的每会话产物目标。没有独立本地产物的后端返回 `undefined`。 |
+| `supportsRawArtifacts: boolean` | 明确说明该后端是否为每个会话暴露一份逐字工件。Consumer 在调用 `readRaw` 前检查此能力；`false` 并不表示会话缺失。 |
+| `readRaw(id, signal?): Promise<SessionRawArtifact \| undefined>` | 读取受支持后端自身的逐字工件文本；只解码物理编码，绝不从事件重建。`undefined` 仅表示所请求工件缺失；不支持的后端会拒绝。 |
 | `create(meta): Promise<void>` | 注册新会话元数据。可以将物理写入延迟到第一次 `append`（延迟实体化）。 |
 | `append(id, events): Promise<void>` | 持久保存一个批次。仅追加；任何修复后，第一个事件 `seq` == 已存储 next-seq；非 JSON 可序列化数据会被拒绝，并命名违规类型。 |
 | `prepare(id, signal?): Promise<SessionPreparation>` | 预留恢复所使用的那个未发布 Session。协调器会尽可能复用之前的检查结果、提交待处理恢复，并在 dispose 时将未发布 reservation 释放回有界缓存。 |
-| `load(id): Promise<{ meta; events }>` | 转换同一格式版本中受支持的旧记录后，返回不可变、平衡的逻辑日志，并提交冷恢复。实时 load 先 flush 其快照，并在轮次开放时拒绝；冷 load 保留中断的最终轮次，并用合成 `tool/result`/`step/end?`/`turn/end {interrupted}` 事件持久关闭它。只丢弃撕裂尾部碎片；已提交损坏、格式错误的记录和未知 `version` 会被拒绝。 |
+| `load(id): Promise<{ meta; events }>` | 转换同一格式版本中受支持的旧记录后，返回不可变、平衡的逻辑日志，并提交冷恢复。实时 load 先 flush 其快照，并在轮次开放时拒绝；冷 load 保留中断的最终轮次，并用合成 `tool/result`/`step/end?`/`turn/end {interrupted}` 事件持久关闭它。只丢弃撕裂尾部碎片；已提交损坏和格式错误的记录以 `SessionPersistenceCorruptionError` 拒绝，不支持的格式 `version` 或本构建不认识且信封未带 `ignorable` 标记的事件类型以 `SessionFormatUnsupportedError` 拒绝，消息说明拒绝方向，并在后端为每个会话保留独立文件时给出原始日志路径。 |
 | `inspect(id, signal?): Promise<{ meta; events }>` | 返回已经升级、验证和深度冻结的逻辑视图，但不提交恢复或发布 Session。冷视图会获得仅存在于内存的合成恢复 closer，物理撕裂尾部保持不变；实时状态下的视图则是当前不可变快照，可能包含开放的轮次。基于协调器的实现会在有界 LRU 中保留该冷状态下未发布的 Session 本身，供后续 `prepare` 使用，但已存储修订值变化后会丢弃并重新读取。同 id 检查共享进行中的读取。 |
-| `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | 返回 `seq >= fromSeq` 的有效已存储事件，不进入 preparation 缓存、不截断、不合成 closer，也不发布协调器状态。`fromSeq` 达到或超过已存储末尾时返回空事件列表；负数或非安全整数 `fromSeq` 会被拒绝。可寻址后端（SQLite）只读后缀，除非转换受支持的旧记录需要读取更早的记录；顺序后端（JSONL）解析整个产物并向前跳过。供 checkpoint 消费方只应用已存序号之后的事件。 |
+| `readFrom(id, fromSeq, signal?): Promise<{ meta; events }>` | 返回 `seq >= fromSeq` 的有效已存储事件，不进入 preparation 缓存、不截断、不合成 closer，也不发布协调器状态。`fromSeq` 达到或超过已存储末尾时返回空事件列表；负数或非安全整数 `fromSeq` 会被拒绝。可寻址后端（SQLite）只读后缀，除非转换受支持的旧记录需要读取更早的记录；顺序后端（JSONL）解析整个产物并向前跳过。未知类型拒绝遵循同一读取方式：寻址读取只检查返回的后缀，顺序回退路径还会拒绝窗口以下的未知必需事件。供 checkpoint 消费方只应用已存序号之后的事件。 |
 | `list(signal?): Promise<SessionHeader[]>` | 从元数据轻量列出，不解析完整日志。可选信号取消后端列表工作。零事件延迟实体化会话不在 `list` 中。 |
 | `listSnapshots(signal?): Promise<SessionPersistenceSnapshot[]>` | 返回轻量元数据和每份日志一个不透明、带品牌类型的修订值，不加载事件日志。日志及其后端存储不变时，修订保持相等；append 或变更性 load 修复后会改变；不会仅因两个存储使用相同本地计数器而冲突。可选信号请求取消后端发现工作；第一方后端会先等待所有已启动的列出工作结束，再予以拒绝，因此调用返回拒绝时，相关工作已完全停稳。 |
 

package/lib/index.js

@@ -1,5 +1,5 @@
 import { Service } from "@deepseek-ai/cordis";
-import { SESSION_FORMAT_VERSION, SessionPreparation, adoptSessionEvent, interruptedTurnClosers, snapshotJsonValue, snapshotSessionEvent } from "@deepseek-ai/dsh-session";
+import { KNOWN_SESSION_EVENT_TYPES, SESSION_FORMAT_VERSION, SessionPreparation, adoptSessionEvent, interruptedTurnClosers, snapshotJsonValue, snapshotSessionEvent } from "@deepseek-ai/dsh-session";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
 //#region lib/types/revision.js
 /** Opaque revision identity for lightweight persistence observations. */
@@ -447,6 +447,40 @@ var SessionPersistenceCorruptionError = class extends Error {
 		this.name = "SessionPersistenceCorruptionError";
 	}
 };
+/**
+* The stored log is intact but this runtime cannot faithfully interpret it:
+* the header carries an unsupported format version, or an event's type is
+* unknown to this build and the event is not marked ignorable. Distinct from
+* {@link SessionPersistenceCorruptionError} — nothing is damaged; the raw log
+* remains readable at {@link location} when the backend keeps one artifact
+* per session.
+*/
+var SessionFormatUnsupportedError = class extends Error {
+	location;
+	/**
+	* @param message - stable reason the log cannot be interpreted, already
+	*   including the raw-log path when one exists.
+	* @param location - the backend's artifact location, when one exists.
+	*/
+	constructor(message, location) {
+		super(message);
+		this.location = location;
+		this.name = "SessionFormatUnsupportedError";
+	}
+};
+/**
+* Direction-aware refusal text for a stored session whose format version this
+* build does not read. Shared by the coordinator's load-time check and by
+* backends that must refuse BEFORE decoding version-dependent structure (a
+* future format may not satisfy today's structural checks at all, and the
+* user must see "upgrade the harness", never "corrupt").
+* @param id - the stored session id, for message context.
+* @param version - the stored format version.
+* @returns the stable refusal text, without a raw-log path suffix.
+*/
+function sessionFormatVersionRefusal(id, version) {
+	return version > SESSION_FORMAT_VERSION ? `session "${id}" uses log format v${version}, but this harness reads only v${SESSION_FORMAT_VERSION}: the log was written by a newer harness — upgrade the harness to open it` : `session "${id}" uses log format v${version}, older than the supported v${SESSION_FORMAT_VERSION}, and this build ships no upgrade path for it`;
+}
 /** Collect the rejection reasons from a set of promises (none-throwing). */
 async function settledErrors(promises) {
 	const settled = await Promise.allSettled([...promises]);
@@ -920,9 +954,11 @@ var PersistenceCoordinator = class {
 					events: whole.events.filter((event) => event.seq >= fromSeq)
 				};
 			}
+			const events = snapshotStoredEvents(suffix.events, id);
+			this.assertEventsSupported(suffix.meta, events);
 			return {
 				meta: structuredClone(suffix.meta),
-				events: snapshotStoredEvents(suffix.events, id)
+				events
 			};
 		}
 		const whole = await this.readStoredPrefix(id, signal);
@@ -939,9 +975,11 @@ var PersistenceCoordinator = class {
 		if (stored === void 0) throw new Error(`session "${id}" not found`);
 		this.assertStoredId(id, stored.meta);
 		this.assertVersion(stored.meta);
+		const events = snapshotStoredEvents(stored.events, id);
+		this.assertEventsSupported(stored.meta, events);
 		return {
 			meta: structuredClone(stored.meta),
-			events: snapshotStoredEvents(stored.events, id)
+			events
 		};
 	}
 	/** Read, repair in memory, validate, and freeze one cold source once. */
@@ -953,6 +991,7 @@ var PersistenceCoordinator = class {
 			this.assertStoredId(id, meta);
 			this.assertVersion(meta);
 			const storedEvents = adoptStoredEvents(events, id);
+			this.assertEventsSupported(meta, storedEvents);
 			const closers = interruptedTurnClosers(storedEvents).map(adoptSessionEvent);
 			const balanced = [...storedEvents, ...closers];
 			const session = this.ctx.sessions.prepare(id, {
@@ -972,6 +1011,7 @@ var PersistenceCoordinator = class {
 				closers
 			};
 		} catch (error) {
+			if (error instanceof SessionFormatUnsupportedError) throw error;
 			throw new SessionPersistenceCorruptionError(`stored session "${id}" failed validation: ${String(error)}`, { cause: error });
 		}
 	}
@@ -1061,7 +1101,29 @@ var PersistenceCoordinator = class {
 		}
 	}
 	assertVersion(meta) {
-		if (meta.version !== SESSION_FORMAT_VERSION) throw new Error(`unsupported session format version ${meta.version} for "${meta.id}" (only v${SESSION_FORMAT_VERSION} is supported)`);
+		if (meta.version === SESSION_FORMAT_VERSION) return;
+		throw this.unsupported(meta, sessionFormatVersionRefusal(meta.id, meta.version));
+	}
+	/**
+	* Refuse a log containing an event type this build does not know, unless the
+	* writer marked the event ignorable: an unrecognized required event may
+	* change how the rest of the log must be interpreted, so silently skipping
+	* it would reconstruct a wrong session (the envelope contract on
+	* `SessionEvent.ignorable`). Runs on NORMALIZED events — after
+	* `snapshotStoredEvents`/`adoptStoredEvents` has upgraded the legacy shapes
+	* this build still reads and rejected the ones it does not, so those keep
+	* their specific diagnostics.
+	*/
+	assertEventsSupported(meta, events) {
+		for (const event of events) {
+			if (KNOWN_SESSION_EVENT_TYPES.has(event.type) || event.ignorable === true) continue;
+			throw this.unsupported(meta, `session "${meta.id}" contains event type "${event.type}" (seq ${event.seq}) unknown to this harness and not marked ignorable; refusing to interpret the log — it was likely written by a newer harness`);
+		}
+	}
+	/** Build a format refusal that points at the raw artifact when the backend has one. */
+	unsupported(meta, reason) {
+		const location = this.backend.locate?.(meta);
+		return new SessionFormatUnsupportedError(location === void 0 ? reason : `${reason} (raw log: ${location.path})`, location);
 	}
 	/** Reject backend metadata that is not bound to the requested session id. */
 	assertStoredId(id, meta) {
@@ -1226,6 +1288,7 @@ var PersistenceCoordinator = class {
 		if (meta.cwd !== session.header.cwd) throw new Error(`session "${session.header.id}" is already persisted at a different cwd (persisted: ${String(meta.cwd)}, live: ${String(session.header.cwd)}) (id collision)`);
 		this.assertVersion(meta);
 		const storedEvents = snapshotStoredEvents(events, session.header.id);
+		this.assertEventsSupported(meta, storedEvents);
 		if (!seedCoversPrefix(seed, storedEvents)) throw new Error(`session "${session.header.id}" already has a persisted log on disk that does not match this live session (id collision)`);
 		if (tornMarker !== void 0) await this.backend.commitRepair(meta, tornMarker, []);
 		this.states.set(session.header.id, {
@@ -1288,6 +1351,25 @@ var SessionPersistence = class extends Service {
 		super(ctx, "sessionPersistence");
 	}
 	/**
+	* Read a session's backend-owned artifact text verbatim — the exact durable
+	* bytes the backend wrote (decoded from its physical encoding, e.g. a
+	* decompressed JSONL). The returned `content` is the raw text, not a
+	* reconstruction from parsed events, so it preserves backend-specific
+	* serialization (chunk packing, key order, line breaks). Callers first test
+	* {@link supportsRawArtifacts}; `undefined` then means only that the requested
+	* session has no materialized artifact.
+	* @param _id - the persisted session to read (unused by the default: no
+	* per-session artifact).
+	* @param signal - optional cancellation for backend read work.
+	* @returns the raw artifact plus its parsed header, or `undefined` when the
+	* session is absent.
+	* @throws when this backend does not expose per-session raw artifacts.
+	*/
+	readRaw(_id, signal) {
+		if (signal?.aborted === true) return Promise.reject(signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("aborted"));
+		return Promise.reject(/* @__PURE__ */ new Error("this session persistence backend does not expose raw artifacts"));
+	}
+	/**
 	* Prepare the exact unpublished Session used by resume. Implementations may
 	* reuse object graphs retained by an earlier {@link inspect} after confirming
 	* their durable revision is still current; disposal releases an unpublished
@@ -1311,4 +1393,4 @@ var SessionPersistence = class extends Service {
 	}
 };
 //#endregion
-export { DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS, PersistenceCoordinator, SessionPersistence, SessionPersistence as default, SessionPersistenceCorruptionError, SessionPersistenceRevision };
+export { DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS, PersistenceCoordinator, SessionFormatUnsupportedError, SessionPersistence, SessionPersistence as default, SessionPersistenceCorruptionError, SessionPersistenceRevision, sessionFormatVersionRefusal };

package/lib/types/coordinator.d.ts

@@ -7,7 +7,7 @@
 import { Context } from '@deepseek-ai/cordis';
 import { SessionPreparation } from '@deepseek-ai/dsh-session';
 import type { SessionEvent, SessionId, SessionHeader } from '@deepseek-ai/dsh-session';
-import type { SessionInspection } from './index.ts';
+import type { SessionInspection, SessionLocation } from './index.ts';
 import type { SessionPersistenceRevision } from './revision.ts';
 /** Default number of detached session preparations retained by a coordinator. */
 export declare const DEFAULT_PREPARED_SESSION_CACHE_SIZE = 5;
@@ -23,6 +23,34 @@ export declare class SessionPersistenceCorruptionError extends Error {
      */
     constructor(message: string, options: ErrorOptions);
 }
+/**
+ * The stored log is intact but this runtime cannot faithfully interpret it:
+ * the header carries an unsupported format version, or an event's type is
+ * unknown to this build and the event is not marked ignorable. Distinct from
+ * {@link SessionPersistenceCorruptionError} — nothing is damaged; the raw log
+ * remains readable at {@link location} when the backend keeps one artifact
+ * per session.
+ */
+export declare class SessionFormatUnsupportedError extends Error {
+    readonly location?: SessionLocation | undefined;
+    /**
+     * @param message - stable reason the log cannot be interpreted, already
+     *   including the raw-log path when one exists.
+     * @param location - the backend's artifact location, when one exists.
+     */
+    constructor(message: string, location?: SessionLocation | undefined);
+}
+/**
+ * Direction-aware refusal text for a stored session whose format version this
+ * build does not read. Shared by the coordinator's load-time check and by
+ * backends that must refuse BEFORE decoding version-dependent structure (a
+ * future format may not satisfy today's structural checks at all, and the
+ * user must see "upgrade the harness", never "corrupt").
+ * @param id - the stored session id, for message context.
+ * @param version - the stored format version.
+ * @returns the stable refusal text, without a raw-log path suffix.
+ */
+export declare function sessionFormatVersionRefusal(id: string, version: number): string;
 /** Coordinator policy supplied by a concrete persistence backend. */
 export interface PersistenceCoordinatorOptions {
     /** Maximum completed unpublished preparations retained for reuse. */
@@ -100,6 +128,11 @@ export interface PersistenceBackend<TornMarker = unknown> {
      * contains a supported legacy shape whose normalization needs earlier
      * message-identity facts, in which case the coordinator falls back
      * to the complete stored prefix.
+     * Unknown-type refusal follows the same suffix scope: a seek-capable
+     * backend's `readFrom` checks only the returned suffix, while the
+     * sequential fallback parses the whole artifact and refuses on an unknown
+     * required event anywhere in it — over-refusal on the sequential side is
+     * accepted rather than widening the seek read.
      * @param id - persisted session id to resolve.
      * @param fromSeq - first event seq to include (non-negative safe integer,
      *   validated by the coordinator before this hook runs).
@@ -126,6 +159,13 @@ export interface PersistenceBackend<TornMarker = unknown> {
      * @param signal - optional cancellation for backend listing work.
      */
     list(signal?: AbortSignal): Promise<SessionHeader[]>;
+    /**
+     * Optional side-effect-free artifact locator, used to point refusal
+     * diagnostics ({@link SessionFormatUnsupportedError}) at the raw log.
+     * Backends without one artifact per session omit it or return `undefined`.
+     * @param meta - the header whose artifact is requested.
+     */
+    locate?(meta: SessionHeader): SessionLocation | undefined;
     /**
      * Optional lifecycle teardown (e.g. close a database handle). Awaited by the
      * coordinator's dispose effect AFTER the quiescence drain. A stateless file
@@ -248,6 +288,19 @@ export declare class PersistenceCoordinator<TornMarker = unknown> {
     /** Build a state for a session discovered in storage but not yet in memory. */
     private adopt;
     private assertVersion;
+    /**
+     * Refuse a log containing an event type this build does not know, unless the
+     * writer marked the event ignorable: an unrecognized required event may
+     * change how the rest of the log must be interpreted, so silently skipping
+     * it would reconstruct a wrong session (the envelope contract on
+     * `SessionEvent.ignorable`). Runs on NORMALIZED events — after
+     * `snapshotStoredEvents`/`adoptStoredEvents` has upgraded the legacy shapes
+     * this build still reads and rejected the ones it does not, so those keep
+     * their specific diagnostics.
+     */
+    private assertEventsSupported;
+    /** Build a format refusal that points at the raw artifact when the backend has one. */
+    private unsupported;
     /** Reject backend metadata that is not bound to the requested session id. */
     private assertStoredId;
     private installWritePath;

package/lib/types/index.d.ts

@@ -24,7 +24,16 @@ export interface SessionInspection {
     /** Validated contiguous logical event log. */
     readonly events: readonly SessionEvent[];
 }
-export { DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS, PersistenceCoordinator, SessionPersistenceCorruptionError, } from './coordinator.ts';
+/** A backend's own raw artifact text for one session, verbatim. */
+export interface SessionRawArtifact {
+    /** The session header parsed from the artifact's own first line. */
+    readonly meta: SessionHeader;
+    /** The artifact's base filename on disk, without any physical encoding suffix. */
+    readonly filename: string;
+    /** The artifact's full text content, decoded from the backend's physical encoding. */
+    readonly content: string;
+}
+export { DEFAULT_PREPARED_SESSION_CACHE_SIZE, DEFAULT_WRITE_BATCH_MAX_DELAY_MS, MAX_WRITE_BATCH_DELAY_MS, PersistenceCoordinator, SessionFormatUnsupportedError, SessionPersistenceCorruptionError, sessionFormatVersionRefusal, } from './coordinator.ts';
 export type { PersistenceBackend, PersistenceCoordinatorOptions, StoredPrefix, StoredSuffix, } from './coordinator.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -58,6 +67,27 @@ export declare abstract class SessionPersistence extends Service {
      * @returns the backend-specific absolute location, when one exists.
      */
     abstract locate(meta: SessionHeader): SessionLocation | undefined;
+    /**
+     * Whether this backend exposes one verbatim raw artifact per session.
+     * A backend that declares `true` must override {@link readRaw}.
+     */
+    abstract readonly supportsRawArtifacts: boolean;
+    /**
+     * Read a session's backend-owned artifact text verbatim — the exact durable
+     * bytes the backend wrote (decoded from its physical encoding, e.g. a
+     * decompressed JSONL). The returned `content` is the raw text, not a
+     * reconstruction from parsed events, so it preserves backend-specific
+     * serialization (chunk packing, key order, line breaks). Callers first test
+     * {@link supportsRawArtifacts}; `undefined` then means only that the requested
+     * session has no materialized artifact.
+     * @param _id - the persisted session to read (unused by the default: no
+     * per-session artifact).
+     * @param signal - optional cancellation for backend read work.
+     * @returns the raw artifact plus its parsed header, or `undefined` when the
+     * session is absent.
+     * @throws when this backend does not expose per-session raw artifacts.
+     */
+    readRaw(_id: SessionId, signal?: AbortSignal): Promise<SessionRawArtifact | undefined>;
     /**
      * Register a new session's metadata. A backend MAY defer the physical write
      * until the first {@link append} (lazy materialization), in which case a

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-session-persistence",
   "description": "Abstract durable session persistence seam (ctx.sessionPersistence) for the DeepSeek Harness",
-  "version": "0.0.1-rc.1",
+  "version": "0.0.1-rc.2",
   "publishConfig": {
     "access": "restricted"
   },
@@ -32,18 +32,18 @@
   ],
   "license": "BSD-3-Clause",
   "peerDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-scope": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
-    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-brand": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.2",
+    "@deepseek-ai/dsh-timeout": "^0.0.1-rc.2",
     "@deepseek-ai/cordis": "^4.0.1-rc.1"
   }
 }