Required downstream Session events need an instance-scoped persistence recognition seam

[hAcKlyc]

Summary

This is a focused follow-up to #802, #1584, and #1748.

Those discussions correctly identify that downstream plugins cannot safely persist custom Session events and propose an ignorable append option and/or event registration. Our downstream distribution has a second, stricter use case: required, non-surface domain events that must not be skipped during recovery.

We are building MyAgents-dsh, a product distribution in which DSH remains the only AgentLoop and the DSH Session remains the only durable conversation authority. We intentionally do not want a parallel product transcript or recovery database. To reconstruct a safe Runtime after restart, our DSH plugins need required events for operation admission/terminal state, TaskGraph transitions, component generation receipts, and managed checkpoint/mutation correlation.

Marking these events ignorable would make an old or incomplete Runtime silently reconstruct the wrong state. We therefore need a public persistence recognition seam for required downstream event types.

Audited against master at 47f943859bef60e4160492346772ded9b24f765a / 0.1.0-rc.5.

Concrete product events

Representative non-surface facts are:

myagents/operation/accepted
myagents/operation/claimed
myagents/operation/terminal
myagents/task/created
myagents/task/updated
myagents/component/committed
myagents/checkpoint/prepared
myagents/mutation/committed

These do not produce model messages, but they are not informational:

• skipping operation/accepted or operation/terminal can duplicate an RPC operation or produce two terminals after restart;
• skipping TaskGraph events changes dependency/cycle/state reconstruction;
• skipping checkpoint or mutation receipts can restore the wrong file/Session generation;
• skipping component receipts can bind resumed work to the wrong effective catalog.

The desired failure mode when the owning product plugin/profile is absent is exactly the current one: refuse to resume. The desired success mode is that an installed, version-compatible profile can declare these required types before persistence prepares the Session.

Current extensibility gap

At compile time, SessionEventMap supports declaration merging, and at runtime Session.append() accepts the resulting log-only event. On cold read, however, PersistenceCoordinator.assertEventsSupported() checks only the repository-generated KNOWN_SESSION_EVENT_TYPES plus event.ignorable === true.

This creates an incomplete extension contract:

downstream event is type-safe and appendable
  -> flush succeeds
  -> next process refuses load/inspect/prepare/resume

For required events, an ignorable: true writer option is intentionally not a solution.

Suggested minimal seam

The smallest implementation we currently need is an optional known-event predicate supplied directly to the public PersistenceCoordinator:

interface PersistenceCoordinatorOptions {
  readonly preparedSessionCacheSize: number
  readonly writeBatchMaxDelayMs: number
  readonly isKnownEventType?: (type: string) => boolean
}

Semantics:

const known = options.isKnownEventType
  ?? ((type: string) => KNOWN_SESSION_EVENT_TYPES.has(type))

if (known(event.type) || event.ignorable === true) continue
throw unsupportedUnknownRequiredEvent(...)

A product persistence Provider can pass a frozen predicate over the union of built-in and product event names. The default remains byte-for-byte equivalent for every existing backend/profile.

We prefer passing the predicate into each coordinator over mutating a process-global exported Set because:

• it avoids the multiple-physical-package-copy problem described in 下游插件会话事件类型的注册面：append() 无法标 ignorable，未知类型连环炸 #1748;
• the exact persistence instance owns the recognition policy used for its read path;
• a distribution can freeze the event vocabulary before any Session load, inspect, or prepare;
• tests can prove that removing the product profile restores fail-closed behavior.

A richer future API could register { type, schemaVersion, validate } through an effect-scoped service. The predicate is only the minimum seam required to close the current type-recognition mismatch; product folds still validate payload shapes and state transitions before Agent publication.

Relationship to ignorable plugin events

We support the separate session.append(..., { ignorable: true }) proposal for genuinely informational downstream records. The two capabilities serve different compatibility contracts:

Event kind	Writer intent	Reader without plugin
informational	explicitly ignorable: true	skip safely
required domain event	registered/recognized by active profile	refuse safely

Automatically treating every declaration-merged event as known would be unsafe. TypeScript declaration merging is not a runtime trust decision, and a removed or incompatible plugin must not cause silent partial recovery.

Required lifecycle

For a required-event registry/predicate to be sound:

1. the complete event vocabulary is installed before persistence reads or prepares a Session;
2. it is frozen for the persistence/profile generation and cannot disappear while a Session is live;
3. HMR/adoption uses the same recognition set;
4. event payloads and cross-event invariants are validated before Agent publication;
5. a missing/incompatible owner fails closed with the exact event type and sequence;
6. registration does not imply that an unknown surface event is safe to derive.

This fits a batteries-included distribution well: the official composition knows its product event vocabulary at startup, while DSH still owns append ordering, Session surface/history, crash repair, and persistence orchestration.

Suggested acceptance coverage

• registered required event passes load, inspect, prepare, resume, readFrom, live adoption, and HMR;
• the same stored event refuses when the product predicate/registry is absent;
• unknown required events still refuse;
• unknown ignorable: true events still skip under the existing contract;
• registration is isolated to the intended coordinator/profile instance;
• built-in default behavior is unchanged with no option;
• generated/product event-set changes are reflected in persistence/profile digests;
• malformed product payload/state transitions remain a product recovery error, not silently accepted state.

Would the maintainers consider an instance-scoped recognition hook on PersistenceCoordinator (or an equivalent pre-load registry) for required downstream events? This would let product distributions keep one DSH Session authority without weakening the current forward-compatibility refusal rule.