docs: state accessor ownership contract

jalehman · jalehman · commit 9a55d1b2f400 · 2026-06-14T05:58:50.000-07:00
diff --git a/src/config/sessions/session-accessor.ts b/src/config/sessions/session-accessor.ts
@@ -37,6 +37,13 @@ import type { SessionEntry } from "./types.js";
  * depending on the persisted store layout. Callers provide stable session
  * identity, and this module resolves the current entry/transcript target while
  * preserving canonical-key, transcript-linking, and update-notification rules.
+ *
+ * Ownership contract (#88838): this accessor is the permanent storage-neutral
+ * domain boundary for session/transcript runtime access; the SQLite storage
+ * flip implements this interface. The entry workflow helpers in store.ts are
+ * the file-backend implementation it delegates to plus the plugin-SDK
+ * deprecation-window surface (RFC 0007); they become internal as direct
+ * callers migrate here. New runtime callers use this module, not store.ts.
  */
 export type SessionAccessScope = {
   /** Agent owner used when the session key does not already encode one. */
diff --git a/src/config/sessions/store.ts b/src/config/sessions/store.ts
@@ -188,6 +188,10 @@ type SingleEntryPersistencePatch = {
   entry: SessionEntry;
 };
 
+// The entry workflow helpers below are the file-backend implementation behind
+// the session-accessor domain boundary and the plugin-SDK compatibility
+// surface (RFC 0007). Internal runtime callers use session-accessor.ts; these
+// become internal as direct callers migrate (#88838).
 type SessionEntryWorkflowOptions = {
   agentId?: string;
   env?: NodeJS.ProcessEnv;
