diff --git a/docs/subsystems/session.i18n.yaml b/docs/subsystems/session.i18n.yaml index 26fee2e323..4d4f5bc022 100644 --- a/docs/subsystems/session.i18n.yaml +++ b/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: de0930ea7effcba69bc1f9a4dd405ceda23919d7 -session.zh.md: ec15dbdec3a8887d8fa87c9698b8ad14699a534b +session.md: 077e90c66abe3b5f3f24d14c3fb25f356d887fa8 +session.zh.md: 6b9ceb85a276b0221c1e6ff474fbcdea77dff1fd diff --git a/docs/subsystems/session.md b/docs/subsystems/session.md index de0930ea7e..077e90c66a 100644 --- a/docs/subsystems/session.md +++ b/docs/subsystems/session.md @@ -473,6 +473,7 @@ declare class Session { ): Session; /** * Return the immutable event stored at one exact sequence number. + * @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited. * @param seq - event sequence number. * @returns the accepted event, or undefined when the log does not contain it. */ @@ -481,6 +482,7 @@ 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. * @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. @@ -491,6 +493,7 @@ declare class Session { ): 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. * @returns a fresh array containing child-owned events in log order. */ ownEvents(): readonly SessionEvent[]; diff --git a/docs/subsystems/session.zh.md b/docs/subsystems/session.zh.md index ec15dbdec3..6b9ceb85a2 100644 --- a/docs/subsystems/session.zh.md +++ b/docs/subsystems/session.zh.md @@ -475,6 +475,7 @@ declare class Session { ): Session; /** * Return the immutable event stored at one exact sequence number. + * @deprecated Existing logic may remain unmigrated for now, but new calls are prohibited. * @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 { * 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. * @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. @@ -493,6 +495,7 @@ declare class Session { ): 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. * @returns a fresh array containing child-owned events in log order. */ ownEvents(): readonly SessionEvent[]; diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml index fd052eb9f9..ed9b39bdff 100644 --- a/packages/core/session/README.i18n.yaml +++ b/packages/core/session/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/core/session/README.md -README.md: a06b22b5e8f48743047c68e883edd496fbc6eb77 -README.zh.md: 755894b4c30f0a3807f472cece32685d102efbeb +README.md: 402f3536402d78d0a70135290092cd7086706fb2 +README.zh.md: 303af9a878909f99e20dec1052b6592da7c8c415 diff --git a/packages/core/session/README.md b/packages/core/session/README.md index a06b22b5e8..402f353640 100644 --- a/packages/core/session/README.md +++ b/packages/core/session/README.md @@ -55,7 +55,7 @@ Append, seed/restore, and event adoption/snapshot reject any `header.system` and ### Read the log -`session.seq` reads the current log length without materializing an array, and `session.eventAt(seq)` reads one accepted, deeply frozen event by sequence number. `session.snapshotEvents(fromSeq?, toSeqExclusive?)` materializes a frozen, stable snapshot of a half-open range; a complete current snapshot is cached until the next append. Callers that only need a length or one event use `seq` or `eventAt()`. +`session.seq` reads the current log length without materializing an array, and `session.eventAt(seq)` reads one accepted, deeply frozen event by sequence number. `session.snapshotEvents(fromSeq?, toSeqExclusive?)` materializes a frozen, stable snapshot of a half-open range; a complete current snapshot is cached until the next append. `eventAt()`, `snapshotEvents()`, and `ownEvents()` are deprecated: existing logic may remain unmigrated for now, but new calls are prohibited. Callers that only need a length use `seq`. Session log positions use two numeric types. `SessionSeq` identifies an existing event or inclusive event watermark; `SessionLogOffset` identifies a gap, prefix length, or read boundary and may equal the event count. `SessionSeqCursor` adds the `-1` “no event yet” value, while `OptionalSessionSeq` uses `null` when absence is data. The constructors validate non-negative safe integers, and the brands disappear at runtime, so durable JSON and wire values remain ordinary numbers. diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md index 755894b4c3..303af9a878 100644 --- a/packages/core/session/README.zh.md +++ b/packages/core/session/README.zh.md @@ -55,7 +55,7 @@ session.deriveMessages() // the derived model history ### 读取日志 -`session.seq` 无需物化数组即可读取当前日志长度,`session.eventAt(seq)` 按序列号读取单个已接受且深度冻结的事件。`session.snapshotEvents(fromSeq?, toSeqExclusive?)` 会物化半开区间的冻结稳定快照;当前完整快照会缓存到下一次追加。只需要长度或单个事件的调用方使用 `seq` 或 `eventAt()`。 +`session.seq` 无需物化数组即可读取当前日志长度,`session.eventAt(seq)` 按序列号读取单个已接受且深度冻结的事件。`session.snapshotEvents(fromSeq?, toSeqExclusive?)` 会物化半开区间的冻结稳定快照;当前完整快照会缓存到下一次追加。`eventAt()`、`snapshotEvents()` 和 `ownEvents()` 已弃用:现有逻辑可以暂不迁移,但禁止新增调用。只需要长度的调用方使用 `seq`。 会话日志位置使用两种数字类型。`SessionSeq` 标识已有事件或包含端点的事件水位;`SessionLogOffset` 标识间隙、前缀长度或读取边界,并且可以等于事件数量。`SessionSeqCursor` 添加 `-1` 这个“尚无事件”值,`OptionalSessionSeq` 则在缺失本身属于数据时使用 `null`。构造函数会校验非负安全整数,品牌在运行时会被擦除,因此持久 JSON 与 wire 值仍是普通数字。 diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts index 9db8327409..68577578dd 100644 --- a/packages/core/session/src/index.ts +++ b/packages/core/session/src/index.ts @@ -615,6 +615,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. * @param seq - event sequence number. * @returns the accepted event, or undefined when the log does not contain it. */ @@ -626,6 +627,7 @@ 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. * @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. @@ -643,6 +645,7 @@ 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. * @returns a fresh array containing child-owned events in log order. */ ownEvents(): readonly SessionEvent[] {