From 5931afaf87f4db69bc15a6220efacdf9e8e2587a Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 11 Aug 2026 18:10:28 +0800
Subject: [PATCH] docs(session-persistence): bind raw capability to its reader

The abstract capability flag forces every backend to state whether it owns per-session raw artifacts, but TypeScript cannot express that a true flag requires replacing the concrete unsupported default. Without an implementer-facing obligation, a backend could advertise support and then fail with a contradictory unsupported diagnostic on first use.\n\nDocument the required pairing at the capability declaration. Keep readRaw concrete so backends that correctly report false inherit one fail-loud implementation instead of duplicating rejection code.
---
 packages/session/session-persistence/src/index.ts | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/packages/session/session-persistence/src/index.ts b/packages/session/session-persistence/src/index.ts
index 07a8819ca1..d579dc46d9 100644
--- a/packages/session/session-persistence/src/index.ts
+++ b/packages/session/session-persistence/src/index.ts
@@ -95,7 +95,10 @@ export abstract class SessionPersistence extends Service {
    */
   abstract locate(meta: SessionHeader): SessionLocation | undefined
 
-  /** Whether this backend exposes one verbatim raw artifact per session. */
+  /**
+   * Whether this backend exposes one verbatim raw artifact per session.
+   * A backend that declares `true` must override {@link readRaw}.
+   */
   abstract readonly supportsRawArtifacts: boolean
 
   /**