Session log: out-of-repo plugins cannot emit a custom event type — append offers no ignorable marker, and the known-event set is repo-internal

[apexphere]

Summary

A downstream (out-of-repo) plugin cannot emit a custom session event type without making every session it touches unloadable after a restart. The persistence read path refuses unknown event types unless the envelope carries ignorable: true, but Session.append offers no way to set that marker, and the known-event set is built from the harness repository's own SessionEventMap merges. The deferred "registration surface for downstream plugin events" now has a consumer.

Observed (harness packages 0.1.0-rc.5, session format version 0)

• @deepseek-ai/dsh-session-persistence assertEventsSupported: for every stored event, KNOWN_SESSION_EVENT_TYPES.has(event.type) || event.ignorable === true, otherwise it throws SessionFormatUnsupportedError: session "…" contains event type "…" (seq N) unknown to this harness and not marked ignorable; refusing to interpret the log.
• @deepseek-ai/dsh-session known-event-types.d.ts: the set is "every SessionEventMap member declared in this repository"; "downstream (out-of-repo) plugin events are outside this list by construction; a registration surface for them is deferred until such a consumer exists."
• @deepseek-ai/dsh-session append(type, data, ...opts): builds { type, seq, time, data, ...surfaceMetadata }; the only caller-supplied metadata is sourceEventSeqs / surfaceOp for surface events. ignorable cannot be set by a caller.
• The in-repo @deepseek-ai/dsh-web-search-deepseek provider appends web/deepseek-search-llm-request before each search request; its declare module '@deepseek-ai/dsh-session/types' merge lands in the harness build, so its event is known.

Reproduction

1. Mount any out-of-repo plugin that, during a tool call, runs
   ctx.get('agents')?.currentInitiator()?.session.append('example/custom-event', { ok: true })
   (the same mechanism the DeepSeek search provider uses).
2. Trigger the tool once in a session; session.history reads fine while the session is in memory.
3. Restart the service (or otherwise make the session cold), then read that session's history or resume it.
4. Result: SessionFormatUnsupportedError … event type "example/custom-event" … not marked ignorable; history and resume both fail for that session.

We hit this with @apexphere/dsh-web-search-anthropic, a WebSearchProvider mirroring the DeepSeek provider's request event; we have removed the event from that package because no safe shape exists for it today.

Request (either would resolve it)

1. Let a caller mark an appended event ignorable — e.g. an options argument on append ({ ignorable: true }) that sets the envelope field the reader already honours; or
2. A registration surface that lets a mounted plugin declare its event types as known for this process (mirroring how in-repo SessionEventMap merges feed KNOWN_SESSION_EVENT_TYPES), so downstream events participate in the same read-side validation as first-party ones.

Option 1 is the smaller change and matches the envelope contract's own description of ignorable as the guard for vocabulary growth.

[argszero]

Verified every claim against current master (49a606b, the alpha.5 line) — your report is accurate. This is the seventh independent report of this exact gap, and yours is the cleanest statement of it so far. Some context that changes the calculus, plus a refinement of your Option 1:

1. One naming evolution on the read side. assertEventsSupported (rc.5) has since been renamed and relocated — it is now validateStoredEvents in @deepseek-ai/dsh-session-persistence/src/storage-contract.ts (:66, gate :72: !KNOWN_SESSION_EVENT_TYPES.has(event.type) && event.ignorable !== true → throw SessionFormatUnsupportedError). Same message text, same fail-closed semantics. The generated set you quote is @deepseek-ai/dsh-session/known-event-types, and its doc now carries an added sentence that is decisive for your Request 2: "event-name registration was rejected because it does not classify omission safety and would make reads composition-dependent" (rationale note: .agents/notes/implemented/architecture/2026-08-30-retain-ignorable-external-session-events.md).

2. Seven independent authors, and the deferral's precondition is saturated. Lineage, all out-of-repo plugin authors hitting the same wall: #1538 (2026-08-14), #1584 (2026-08-15), #1619 (2026-08-15), #2778 (2026-08-17), #3191 (2026-08-18), #5463 (2026-09-02, workspace-restore), and now #5474. Yours is the first to document the removal casualty (the event deleted from @apexphere/dsh-web-search-anthropic) and the first to reproduce the search-provider mechanism step-by-step. The deferred-registration quote you cite says "until such a consumer exists" — that precondition has now been met seven times over. The remaining obstacle is the upstream PR/issue channel (disabled on this repo; discussions are the working channel), not design ambiguity.

3. Request 2 is the option ruled out by design — your own quote contains the reason. The known-event set is generated from in-repo SessionEventMap merges; admitting out-of-repo types would make a session's readability depend on which plugins happened to be mounted at read time (composition-dependent reads), registrations wouldn't survive restarts, and the read path can run before a registering plugin mounts. That is exactly why the durable per-event envelope marker exists (SessionEvent.ignorable, types.ts) instead.

4. Request 1 is right — and the refined shape already exists. In #5463 (same week, same gap, a workspace-restore plugin author) we converged on a merge-extensible IgnorableSessionEventMap whose members are the only types allowed to take an { ignorable: true } append option. A free-form { ignorable: true } on any event would let a plugin mark a required event ignorable by accident and silently desync every read of that session; gating the option to a declared map makes the ignorable decision a typed, per-event author choice — over-marking becomes a compile error. Purely additive, type-level gate:

append<T extends SessionEventType>(
  type: T,
  data: SessionEventMap[T],
  ...opts: T extends SurfaceEventType
    ? [opts: SurfaceIntent]
    : T extends keyof IgnorableSessionEventMap
      ? [opts?: { ignorable: true }]
      : []
): SessionEvent<T>

Runtime is a passthrough — append is the only envelope producer (declaration merging erases at runtime), so the change is roughly: opts tuple + envelope passthrough + the mergeable map + two regression tests. The read side stays untouched and fail-closed (it already honours ignorable today; there are zero in-tree writers of the marker). Note the map must NOT be consulted on reads — that would re-introduce the composition-dependence upstream rejected; it exists only to classify which events may be marked.

5. Interim pattern until the channel reopens. antst's #5463 workaround is the safe one: encode the durable structured fact as a flat first-party event (e.g. command/done content) instead of a custom type. Your removal of the custom event is correct for today. One adjacent wart worth fixing with the same change: the silent-write/loud-read asymmetry — an unknown non-ignorable append succeeds in memory (no runtime type check at the append site) and only fails at the next cold load, so a plugin author discovers the poison at restart, not at authoring time. A warn-at-append for unknown, unmarked types would close that loop; and the refusal wording "likely written by a newer harness" misleads plugin authors — this is usually an out-of-repo plugin event, not a newer harness.