Session.append cannot set ignorable, so a plugin's own event type makes its sessions unloadable

[yuzisama224]

The envelope has a marker that lets a reader skip an event whose type it does not know, the restore path honours it, and the repository has committed to keeping it for out-of-repository plugins — but no plugin can write it, because Session.append has nowhere to put it.

Where it stops

Session.append constructs the event from a fixed literal (packages/core/session/src/index.ts:691-697):

const event = deepFreeze({
  type,
  seq: SessionSeq(this.log.length),
  time: Date.now(),
  data: dataSnapshot,
  ...(surfaceMetadataSnapshot as { surfaceOp?: unknown; sourceEventSeqs?: unknown }),
} as unknown as SessionEvent<T>)

There is no ignorable in it, and no way to get one in: the only optional argument is a SurfaceIntent, carrying surfaceOp and sourceEventSeqs (:668-672, the type at packages/core/session/src/types.ts:410-419), and on a non-surface type the compiler rejects an argument there at all.

Every other leg of the field works. The envelope declares it and documents what it means (types.ts:442-452). Seed validation allowlists the key and pins the value to true (index.ts:213-250, the key at :226, the check at :239). The JSONL log writes the whole envelope verbatim — eventLines stringifies the record and the only field rewritten on the way to disk is sourceEventSeqs (packages/session/session-persistence-jsonl/src/format.ts:254-257, :268-271) — and the wire form declares it (packages/api/session-controller/src/types.ts:431). The restore path reads it: PersistenceCoordinator refuses a whole log over any event type outside KNOWN_SESSION_EVENT_TYPES unless the event is marked (packages/session/session-persistence/src/coordinator.ts:1248-1252, the table at packages/core/session/src/known-event-types.ts:22-74), and a contract test asserts both halves — the refusal at packages/session/session-persistence/tests/coordinator-contract.ts:1464, the retention of a marked unknown event at :1478-1485.

Only the writer is missing, and the repository says so itself: "First-party writers do not set ignorable through Session.append, while a repository-external plugin is a current consumer" (.agents/notes/implemented/architecture/2026-08-10-session-log-version-mechanism.md:23). A tree sweep agrees — every ignorable: true literal is in a test or a fixture, and the one non-test reference is a projector passing an existing value through (packages/session/session-log-deepseek/src/index.ts:78).

All references are to dsh-v0.1.2-rc.1 (a66e470).

Why this matters to a composed plugin

The event vocabulary is explicitly open. SessionEventType is keyof SessionEventMap and is documented as "the appendable event-type keys of SessionEventMap, plugin-merged extensions included" (packages/core/session/src/types.ts:365-366), so a plugin declares its own type by module augmentation and append accepts it.

KNOWN_SESSION_EVENT_TYPES is generated from this repository's merges only, and says as much: "Downstream (out-of-repo) plugin events are outside this list by construction" (known-event-types.ts:8-22). So the moment a plugin appends its own type, every session it touched is unloadable on the next restart — and the append path will not warn, deliberately: the unknown-type guard is read-side only "because an append-time refusal would stall a live session's durability mid-flight" (coordinator.ts:768-777). A process runs all day and fails on its next load.

ignorable is exactly the escape hatch for this, and the repository has already decided to keep it for exactly this consumer. The retention decision was taken after a PR removed the field "after finding no first-party producer" and a third-party plugin turned out to depend on it; the field stays until a replacement covers "event production, persistence, reload, and transport" (.agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md:9, :11, :17). Event production is the leg that is not there.

We are one of those plugins. We append one informational record of our own to a session log — a short string, written once when the session is created, read back by folding the log. Nothing in the core has to interpret it; the core only has to not refuse the log because of it.

What we could not make work without a change

• Register the event type at runtime. Rejected here already, and we think correctly: a name "does not classify whether absence is safe" (2026-08-30-retain-ignorable-external-session-events.md:27).
• Write the event unmarked. Not a fallback, a delayed failure: every read path calls the same unknown-type guard (coordinator.ts:1248-1252).
• Seed the event through a SessionStore subclass. It works — SessionStore.prepare is public and non-final (index.ts:927-953) — but the price is replacing the store every session in the process is constructed by, and seeding happens once, so the record can never be superseded.
• Write straight to ctx.sessionPersistence. append is a public service method taking raw SessionEvent[] (coordinator.ts:755; create registers the header only), but it writes behind the live Session's back, so the in-memory log and the artifact diverge.

The change we would propose

One new options interface, and one more optional field on the call.

export interface AppendIntent {
  ignorable?: true
}

export interface SurfaceIntent extends AppendIntent {
  surfaceOp: SurfaceOp
  sourceEventSeqs?: SessionSeq[]
}

append<T extends SessionEventType>(
  type: T,
  data: SessionEventMap[T],
  ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : [opts?: AppendIntent]
): SessionEvent<T>

and one line in the event literal, spreading { ignorable: true } in only when the caller asked for it. A caller that passes nothing gets the literal it gets today, so a composition without such a plugin is unchanged.

The diff is two files and about 30 lines, most of it documentation. It touches no schema, no persistence path, no surface validation, and no part of the restore guard — the reader already does the right thing with the marker, and this only lets a writer set it.

The one visible widening is that opts becomes optional on a non-surface type rather than absent. Surface metadata stays rejected there: AppendIntent does not declare surfaceOp, so append('turn/start', { turn: 1 }, { surfaceOp: 'append' }) still fails to compile. We checked that specifically, along with the surface types still requiring their metadata.

Two things worth flagging.

The signature is mirrored in three generated or gated places, and this diff does not update them: packages/extensions/tool-cordis/src/api-catalog.ts:4799 and :5575 are generated (pnpm run gen-cordis-api), and the ts type-equiv blocks in docs/subsystems/session.md:298-306 and :517 — with docs/subsystems/session.zh.md:307 and :519 — are checked by scripts/verify-type-equiv.ts. They are mechanical, and we would rather agree the shape before regenerating anything.

ignorable means "informational", and only a writer can honestly say that. The envelope's own wording is that a writer sets it "only on purely informational records whose loss cannot affect reconstruction" (types.ts:442-452). Putting the option on append keeps that judgement with the writer, which is where the retention decision already put it — as opposed to any scheme that infers skippability from the type's provenance, which the same decision rejected because "a reader cannot infer that an unknown durable event is informational" (2026-08-30-retain-ignorable-external-session-events.md:25).

What we are asking

1. Is a writer for ignorable something this repository wants to offer, or is the field meant to stay first-party-unreachable and reach plugins some other way?
2. If yes, is an options argument the shape you would want — and is a separate AppendIntent that SurfaceIntent extends the right factoring, or would you rather put ignorable on SurfaceIntent directly and require the argument everywhere?
3. Making opts optional rather than absent on non-surface types is the only signature widening. Is that acceptable, or would you prefer a separate method that never touches append's signature?

We run this as a local patch over the published 0.1.2-rc.1 package today, so we are not blocked on an answer. We would rather not carry a patch over a core package, and this is the smallest of the three we carry — one field, one spread, and a reader that already knows what to do with it. Happy to write it in whatever shape you would accept, or to hear that you would not, which is also a useful answer.

diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index c55cc5fb6a..4c5685d365 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -15,7 +15,7 @@ import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { Message } from '@deepseek-ai/dsh-llm'
 import { SESSION_FORMAT_VERSION, SessionLogOffset, SessionSeq } from './types.ts'
 import type { TypertLookup } from '@deepseek-ai/dsh-typert-protocol'
-import type { CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SurfaceIntent, SurfaceEventType } from './types.ts'
+import type { AppendIntent, CreateSessionOptions, EpochHeader, PrepareSessionOptions, RequestContext, SessionEvent, SessionEventMap, SessionEventType, SessionHeader, SessionId, SurfaceIntent, SurfaceEventType } from './types.ts'
 import { deriveEventMessage, SurfaceManager } from './surface.ts'
 import type { SessionSurface } from './surface.ts'
 import { foldRequestHeader } from './request-header.ts'
@@ -640,14 +640,18 @@ export class Session {
    *
    * @param type - The event type (key of {@link SessionEventMap}).
    * @param data - The event payload; must be JSON-serializable.
-   * @param opts - Surface metadata: `surfaceOp` controls how the event enters
-   *   the ordered surface; `sourceEventSeqs` lists the seq numbers of earlier
-   *   events this one derives from. REQUIRED for
+   * @param opts - Surface metadata and reader guidance: `surfaceOp` controls
+   *   how the event enters the ordered surface; `sourceEventSeqs` lists the
+   *   seq numbers of earlier events this one derives from. The surface
+   *   metadata is REQUIRED for
    *   {@link SurfaceEventType} events (every message-producing event must
    *   declare how it joins the surface, the sole source of derived model
    *   history) and
    *   rejected by the compiler for non-surface types like `turn/start` or
-   *   `assistant/chunk`.
+   *   `assistant/chunk`. {@link AppendIntent}'s `ignorable` is accepted for
+   *   every type, which is why the argument is optional rather than absent on
+   *   a non-surface type; a call that omits it logs exactly what it logs
+   *   today.
    * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
    *   `data` that entered the log, so reading `event.data` back sees the logged
    *   value, never the caller's still-mutable input.
@@ -668,12 +672,12 @@ export class Session {
   append<T extends SessionEventType>(
     type: T,
     data: SessionEventMap[T],
-    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []
+    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : [opts?: AppendIntent]
   ): SessionEvent<T> {
-    const surfaceOpts: SurfaceIntent | undefined = opts[0]
+    const appendOpts: Partial<SurfaceIntent> | undefined = opts[0]
     const surfaceMetadata = {
-      ...surfaceOpts?.sourceEventSeqs === undefined ? {} : { sourceEventSeqs: surfaceOpts.sourceEventSeqs },
-      ...surfaceOpts?.surfaceOp === undefined ? {} : { surfaceOp: surfaceOpts.surfaceOp },
+      ...appendOpts?.sourceEventSeqs === undefined ? {} : { sourceEventSeqs: appendOpts.sourceEventSeqs },
+      ...appendOpts?.surfaceOp === undefined ? {} : { surfaceOp: appendOpts.surfaceOp },
     }
     const dataSnapshot = snapshotJsonValue(data)
     if (dataSnapshot === undefined) {
@@ -693,6 +697,7 @@ export class Session {
       seq: SessionSeq(this.log.length),
       time: Date.now(),
       data: dataSnapshot,
+      ...appendOpts?.ignorable === true ? { ignorable: true } : {},
       ...(surfaceMetadataSnapshot as { surfaceOp?: unknown; sourceEventSeqs?: unknown }),
     } as unknown as SessionEvent<T>)
     this.surfaceManager.validateNext(event as SessionEvent)
diff --git a/packages/core/session/src/types.ts b/packages/core/session/src/types.ts
index 461c31ad36..611c7f7660 100644
--- a/packages/core/session/src/types.ts
+++ b/packages/core/session/src/types.ts
@@ -403,11 +403,30 @@ export type SurfaceOp =
   | 'append'
   | { op: 'replace'; start: SessionSeq; end: SessionSeq }
 
+/**
+ * Reader guidance for {@link Session.append}, accepted for every event type.
+ * {@link SurfaceIntent} extends it, so a surface event declares placement and
+ * guidance in one options object.
+ */
+export interface AppendIntent {
+  /**
+   * Stamp {@link SessionEvent.ignorable} on the appended event. Only the
+   * writer of an event knows whether losing its record is safe, so the writer
+   * is the only party that can classify it; omitting this leaves the
+   * envelope's default of required, which is what a first-party event wants.
+   * An event type outside `KNOWN_SESSION_EVENT_TYPES` — by construction, every
+   * type an out-of-repository plugin declares — is unreadable to this build
+   * unless its writer set this, so a plugin appending its own informational
+   * record sets it here rather than making the whole log refuse to load.
+   */
+  ignorable?: true
+}
+
 /**
  * Surface placement and cited source-event seqs for {@link Session.append}. Required on
  * message-producing events and forbidden on log-only events.
  */
-export interface SurfaceIntent {
+export interface SurfaceIntent extends AppendIntent {
   surfaceOp: SurfaceOp
   /**
    * Complete set of known source-event seqs. `assistant/message` may use a

[argszero]

This is the 9th independent report of the same write-side gap, and your mechanism analysis matches current master exactly — I verified both halves on d347e70390 (v0.1.3-alpha.1-era):

• Write side: Session.append in packages/core/session/src/index.ts builds the envelope from surface metadata only (surfaceOp/sourceEventSeqs); there is no path for an ignorable stamp, and on a non-surface type the compiler rejects an options argument at all.
• Read side: validateStoredEvents (packages/session/session-persistence/src/storage-contract.ts:75) throws SessionFormatUnsupportedError for any type outside KNOWN_SESSION_EVENT_TYPES unless event.ignorable === true.

Prior threads from plugin authors who hit the same wall: #1538, #1584, #1619, #2778, #3191, #5463, #5474, and #5769 (a plugin whose custom session event made its log unloadable — the same delayed failure you describe). The consistent root cause across all of them: the read side honours ignorable, but append is the only sanctioned write path and has nowhere to put it — so a composed plugin declaring its own SessionEventType is forced to carry a core patch, subclass SessionStore, or write behind the live session's back. Every alternative the repo's own retention note rules out, or diverges the in-memory log from the artifact.

Your proposed shape (AppendIntent base extended by SurfaceIntent, opts optional rather than absent on non-surface types) is the convergent one. #5463 and #5474 independently converged on a write-side seam keyed to the same doctrine the envelope already states (types.ts:442-452) and the 2026-08-30 retention decision reaffirmed: only the writer can classify its own event as informational. A plain optional ignorable: true is the minimal expression of that, and your two-file/30-line diff (with the opts-becomes-optional widening being the only visible change) is the smallest shape that gets there.

Two notes from the family history:

1. Expect a possible counter-proposal on the widening. In earlier threads the alternative was a map-gated overload — a per-type opt-in declaration (an IgnorableSessionEventMap-style augmentation) so a plugin must explicitly register each ignorable type, turning accidental over-marking into a compile error rather than a silent read-side skip. If that comes up, the trade-off to argue is: compile-time safety for the marker vs. a runtime registry that duplicates what the module-augmentation merge already gives you. Your "writer honesty" framing is the strongest argument for the plain flag.

2. Detection-side help already exists as a published community plugin while this waits on a core decision: @argszero/cordis-plugin-session-audit (github.com/argszero/cordis-plugin-session-audit · npm @argszero/cordis-plugin-session-audit ≥ 0.1.2). It audits session logs and reports UNKNOWN_REQUIRED_TYPE — the exact signature of this failure: a type outside the known vocabulary, not marked ignorable, whose log the read path will hard-refuse (SessionFormatUnsupportedError). It is diagnostic only (it does not fix the write path), but it converts your "process runs all day and fails on its next load" into an attributable, pre-replay error instead of a mystery unloadable session.

On your three questions: (1) the retention note already commits the field to staying for out-of-repo plugins, and names event production as the leg that is missing — by the repo's own accounting, a writer is wanted; (3) making opts optional on non-surface types is the smallest widening and keeps append as the single sanctioned write path, which I'd prefer over a second method. Flagging the generated api-catalog.ts + type-equiv doc blocks before touching them is the right order.

[Saidoua]

Every citation in this report checks out against d347e703, including the ones that make the case: the envelope declares the field, seed validation allowlists it and pins it to true, JSONL writes it verbatim, and validateStoredEvents honours it — only the writer is missing. Your closing point is the one that decided it for me: the repository already says so itself, in the external-plugin retention decision, which kept ignorable for an out-of-repository plugin and listed every representation that preserves it — without the one that produces it.

Implemented on a fork, since this repository takes no pull requests: a3e00b2, merged into Saidoua/deepseek-harness:master. The fix shape is not mine — #1538 proposed it first and @argszero has restated it across several of these threads. This is that proposal, built and gated.

...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : [opts?: LogIntent]

LogIntent carries ignorable?: true and the envelope omits the key when unset, so an unmarked event stays byte-identical to what the previous writer produced and remains required-on-read.

Two decisions in it worth disagreeing with if you see it differently:

A surface event cannot be marked. The envelope permits the field on any type, so allowing it everywhere would have been one conditional less. But a SurfaceEventType event produces derived model history, and a reader skipping one would change exactly the reconstruction the marker exists to leave intact. The read-side guard never consults the marker for a known type anyway, so the permission would buy nothing and mislead. SurfaceIntent and LogIntent are therefore disjoint at the call site.

The option carries no runtime check. append is a typed same-process boundary, and the repository's own rule is to trust TypeScript there; seed validation and the persistence seam keep owning the durable-boundary checks that pin the value to true.

The test I care about most is in storage-contract.spec.ts, because it covers the gap rather than either side of it: a plugin-typed event appended with the marker survives validateStoredEvents, and the same event without it refuses the log. The existing contract test hand-builds that envelope, so nothing until now proved a real Session.append could produce one.

Checks: typecheck and lint clean, 1455 tests passing across core/session, session/* and tool-cordis, and doc-sync at 30 passed / 3 failed — those three (verify-cordis-inspect-catalog, verify-export-jsdoc, verify-config-catalog) fail identically on master, so they are not from this change. Generated catalogs, the docs/subsystems/session JSDoc copies, and the bilingual pairing records are regenerated in the same commit, plus an Agent Note under implemented/bug-fix/.

On the larger alternative: a registration surface for out-of-tree event types (#3191, #4204) is the better long-term answer, and this does not compete with it — it decides ownership, versioning, and uninstall behaviour, none of which this defect needs, and all of which would sit undecided while sessions keep breaking. If a maintainer takes the registration route, this patch is five lines to drop.

---

这份报告里的每一处引用我都对照 d347e703 核过，包括真正支撑论点的那些：信封声明了该字段，seed 校验允许该键并把值固定为 true，JSONL 原样写入，validateStoredEvents 也遵守它——唯独缺写入方。真正让我下决心的是你最后那一点：仓库自己就是这么说的——外部插件保留决策为一个仓库外插件保留了 ignorable，并列出了每一种保留它的表示——却没有产生它的那一种。

已在 fork 上实现，因为本仓库不接受 pull request：a3e00b2，已并入 Saidoua/deepseek-harness:master。修法不是我提出的——#1538 最早提出，@argszero 在多条相关讨论中反复重申。这是把那个提案建出来并过了各道门。

...opts: T extends SurfaceEventType ? [opts: SurfaceIntent<T>] : [opts?: LogIntent]

LogIntent 携带 ignorable?: true，未设置时信封不写入该键，因此未标记事件与此前写入方产出的字节完全一致，并继续保持读取时必需。

其中有两处决定，如果你有不同看法值得提出来：

surface 事件不可被标记。 信封允许该字段出现在任何类型上，全面放开可以少一个条件分支。但 SurfaceEventType 事件产出派生的模型历史，读取方跳过它，改变的恰恰是该标记本应保持不变的重建结果。而读取侧的守卫对已知类型从不查阅该标记，因此这项许可毫无收益且具有误导性。于是 SurfaceIntent 与 LogIntent 在调用点互斥。

该选项不带运行时检查。 append 是同进程内的类型化边界，仓库自身的规则是在那里信任 TypeScript；seed 校验与持久化接缝继续负责把值固定为 true 的持久边界检查。

我最看重的测试在 storage-contract.spec.ts，因为它覆盖的是缺口本身而不是缺口的任一侧：带标记追加的插件类型事件通过 validateStoredEvents，同一事件不带标记则使日志被拒。既有的契约测试是手工构造那个信封的，所以在此之前没有任何东西证明真实的 Session.append 能产出一个。

检查结果：typecheck 与 lint 干净，core/session、session/* 和 tool-cordis 共 1455 个测试通过，doc-sync 30 通过 / 3 失败——这三项（verify-cordis-inspect-catalog、verify-export-jsdoc、verify-config-catalog）在 master 上同样失败，与本次改动无关。生成目录、docs/subsystems/session 的 JSDoc 副本以及双语配对记录都在同一提交中重新生成，另有一份位于 implemented/bug-fix/ 的 Agent Note。

关于那个更大的备选方案：为树外事件类型提供注册面（#3191、#4204）是更好的长期答案，本改动并不与之竞争——注册面需要决定归属、版本化和卸载后的行为，这些都不是本缺陷所必需的，而在它们悬而未决期间会话会持续损坏。若维护者选择注册面这条路，这个补丁删掉五行即可。