docs(session): link deprecated readers to the history policy

.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.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 .agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md
-2026-09-09-deprecate-synchronous-session-event-reads.md: 1420227daf9a410e7db6a7a685bcf4433d7d7b0b
-2026-09-09-deprecate-synchronous-session-event-reads.zh.md: e546337bcb15cf6682935729de37aab0c579d2a2
+2026-09-09-deprecate-synchronous-session-event-reads.md: a2a86b0d6500269531ca1088738aaa612076bfb4
+2026-09-09-deprecate-synchronous-session-event-reads.zh.md: 38468708a5323b6ebf94377f3cc8f2c86dc95dde

.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md

@@ -16,7 +16,7 @@ All operations that synchronously read arbitrary positions or ranges of Session
 
 The three methods carry this rule in `@deprecated` JSDoc. This is an API-use decision; the current Session implementation still retains the complete event sequence in memory.
 
-Repository test files may call these three readers to inspect emitted events and exercise Session history behavior. Their existing lint override allows `snapshotEvents`, `eventAt`, and `ownEvents`; all other deprecated names remain errors. This allowance also covers unrelated declarations with the same three names under the current linter. It does not apply to production source or ordinary repository scripts.
+Repository test files, including `scripts/**/*.spec.{ts,tsx}`, may call these three readers to inspect emitted events and exercise Session history behavior. The test-file lint override allows `snapshotEvents`, `eventAt`, and `ownEvents`; all other deprecated names remain errors. This allowance also covers unrelated declarations with the same three names under the current linter. It does not apply to production source or non-test repository scripts.
 
 ### State needed after resume
 
@@ -44,7 +44,7 @@ Fork and a small number of operations may genuinely need a complete historical s
 
 New domain behavior must make its event data and projected state sufficient for resumed execution. User-requested history may still load progressively, and genuine full-history operations still have a storage path to design. This decision does not claim that resume or fork already avoids loading the complete log.
 
-Existing calls outside test files carry line-scoped `typescript/no-deprecated` waivers with a migration-deferral reason. Remove a waiver when its call migrates; copying a waiver to a new production call violates this policy. The executable lint check accepts test reads and existing waived reads, rejects unwaived production reads, and rejects unrelated deprecated APIs in tests. Documentation checks verify the source-equivalent API declarations and bilingual records.
+Calls outside test files carry line-scoped `typescript/no-deprecated` waivers that identify deferred migration or delegation between deprecated readers. Remove a waiver when its deprecated call is removed; copying a waiver to a new production call violates this policy. The executable lint check accepts test reads and existing waived reads, rejects unwaived production reads, and rejects unrelated deprecated APIs in tests. Documentation checks verify the source-equivalent API declarations and bilingual records.
 
 ## Related decisions
 

.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.zh.md

@@ -16,7 +16,7 @@ Status: implemented
 
 这三个方法通过 `@deprecated` JSDoc 声明该规则。这是 API 使用决策；当前 Session 实现仍在内存中保留完整事件序列。
 
-仓库测试文件可以调用这三个读取方法，以检查已发出的事件并验证 Session 历史行为。现有测试 lint override 允许 `snapshotEvents`、`eventAt` 和 `ownEvents`，其他弃用名称仍报错。在当前 linter 下，此豁免也覆盖使用这三个名称的其他声明。它不适用于生产源码或普通仓库脚本。
+仓库测试文件（包括 `scripts/**/*.spec.{ts,tsx}`）可以调用这三个读取方法，以检查已发出的事件并验证 Session 历史行为。测试文件 lint override 允许 `snapshotEvents`、`eventAt` 和 `ownEvents`，其他弃用名称仍报错。在当前 linter 下，此豁免也覆盖使用这三个名称的其他声明。它不适用于生产源码或非测试仓库脚本。
 
 ### 恢复后需要的状态
 
@@ -44,7 +44,7 @@ fork 等少数操作可能确实需要完整历史序列或继承前缀。它们
 
 新增领域行为必须使其事件数据与投影状态足以支持恢复后的执行。用户请求的历史仍可渐进式加载，确实需要完整历史的操作仍需设计存储读取路径。本决策不表示恢复或 fork 已经能够避免加载完整日志。
 
-测试文件之外的现有调用带有逐行的 `typescript/no-deprecated` 豁免，并说明暂缓迁移的理由。调用迁移后应删除豁免；将豁免复制到新增生产调用违反本策略。实际执行 lint 的检查允许测试读取和已有豁免调用，拒绝未豁免的生产读取，并拒绝测试中其他已弃用 API。文档检查校验与源码一致的 API 声明及双语记录。
+测试文件之外的调用带有逐行的 `typescript/no-deprecated` 豁免，说明暂缓迁移或已弃用读取方法之间的委托。删除已弃用调用时应一并删除其豁免；将豁免复制到新增生产调用违反本策略。实际执行 lint 的检查允许测试读取和已有豁免调用，拒绝未豁免的生产读取，并拒绝测试中其他已弃用 API。文档检查校验与源码一致的 API 声明及双语记录。
 
 ## 相关决策
 

docs/subsystems/session.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 docs/subsystems/session.md
-session.md: 077e90c66abe3b5f3f24d14c3fb25f356d887fa8
-session.zh.md: 6b9ceb85a276b0221c1e6ff474fbcdea77dff1fd
+session.md: 187578ac720dd3b7facba768491bd5fb867aa397
+session.zh.md: 3dae495b695c4ddec220c83d872c4f2c5f9b13c3

docs/subsystems/session.md

@@ -474,6 +474,7 @@ declare class Session {
   /**
    * 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.
    */
@@ -483,6 +484,7 @@ declare class Session {
    * 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.
@@ -494,6 +496,7 @@ declare 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(): readonly SessionEvent[];

docs/subsystems/session.zh.md

@@ -476,6 +476,7 @@ declare class Session {
   /**
    * 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 +486,7 @@ declare class Session {
    * 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.
@@ -496,6 +498,7 @@ declare 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(): readonly SessionEvent[];

packages/core/session/src/index.ts

@@ -616,6 +616,7 @@ export class Session {
   /**
    * 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.
    */
@@ -628,6 +629,7 @@ export class Session {
    * 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.
@@ -646,10 +648,11 @@ 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(): readonly SessionEvent[] {
-    // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+    // oxlint-disable-next-line typescript/no-deprecated -- Deprecated reader delegates to the deprecated range read.
     return this.snapshotEvents(this.inheritedEventCount)
   }
 

scripts/oxlint-contract.spec.ts

@@ -315,7 +315,7 @@ export function unrelatedRead(): void {
       expect(rejected.error).toBeUndefined()
       expect(rejected.signal).toBeNull()
       expect(rejected.status, output).toBe(1)
-      const diagnostics = output.split('\n').filter(line => line.includes('typescript(no-deprecated)'))
+      const diagnostics = output.split('\n').filter(line => /:\d+:\d+: `\w+` is deprecated\./.test(line))
       for (const path of testPaths) {
         const reported = diagnostics.filter(line => line.startsWith(`${path}:`))
         expect(reported, output).toHaveLength(1)
@@ -327,6 +327,9 @@ export function unrelatedRead(): void {
       for (const method of ['snapshotEvents', 'eventAt', 'ownEvents', 'oldApi']) {
         expect(output).toContain(`\`${method}\` is deprecated`)
       }
+      expect(output).toContain(
+        'See the [Agent Note](../../../../.agents/notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md).',
+      )
     } finally {
       await Promise.all([
         ...paths.map(path => rm(join(repositoryRoot, path), { force: true })),