ChatGPTClaudeGrok / X / CursorGemini

DeepSeek Harness Persistence Catalog: What Gets Written

Concepts & ArchitecturePublished 2026-11-18Author: DeepSeek Plugin Market
DeepSeek HarnessDSH pluginpersistenceSessionEventMapsession log
The DeepSeek Harness persistence catalog shows which events are written and what enters model history. Learn the envelope, surface vs log-only, and limits.

The DeepSeek Harness persistence catalog answers a narrow question: will this event be written into the session log, and will the model see it? The catalog covers every persistent Session event, the logical and physical header, the event envelope, and all SessionEventMap merges (source). Reading it prevents “real-time broadcast” from being mistaken for “persisted.”

DeepSeek Harness: What the persistence catalog covers

Formal events and experimental records live in separate catalogs. Experimental records are listed separately; the formal catalog covers the repository's persistent events (source).

Three scope points:

  1. This repository only — external plugin types are not included and must be declared separately.
  2. Header and envelope included — not just event data.
  3. Generated and verified — gen-persistence-catalog builds it, verify-persistence-catalog checks freshness.

The catalog is a contract list for the repository, not a live list of events on your machine. A third-party plugin can extend events, but its types will not appear automatically.

Decide whether an event is formal or experimental before reading. Experimental records can change with a release and are a poor external contract; formal events carry migration and replay rules.

DeepSeek Harness: The envelope fields

Every persistent event uses the same envelope. The fields are type, seq, time, data, optional ignorable, and the conditional surfaceOp / sourceEventSeqs (source).

FieldJobDebug use
typeEvent typeFilter and look up
seqSession sequenceDetect gaps, duplicates, order
timeRecord timeAlign external logs
dataEvent payloadInspect fields and types
ignorableWhether an old reader may skipCompatibility
surfaceOpConditional surface operationModel-history impact
sourceEventSeqsConditional source sequenceDerived relationships

seq is the most useful field for corruption. A gap, duplicate, or regression can mean a damaged or concurrent log; check continuity before reading data.

ignorable means “can an old version skip this,” not “this is unimportant.” If skipping causes state inconsistency, do not mark it ignorable.

DeepSeek Harness: Surface vs log-only

The split is whether the event produces model history. Surface events do; log-only events do not (source).

Three consequences:

  1. The model must see it → surface — log-only will not reach the next request.
  2. A fact must not pollute history → log-only — diagnostics and internal state changes.
  3. Surface needs more care — it enters replay, compaction, references, and billing.

A common error is treating “persisted” as “surface.” Persistence only requires a write; surface also requires inclusion in model context.

Ask: does the next request need this record? If yes, surface; if not, log-only.

DeepSeek Harness: Why external events are absent

The official catalog covers this repository; external SessionEventMap extensions declare themselves. The docs say external plugin types are not part of this catalog (source).

An external plugin must do three things:

  1. Declare the type — merge SessionEventMap with type and data shape.
  2. Handle migration — provide old-to-new conversion when the shape changes.
  3. Mark surface or log-only — decide whether it enters model history.

Declare without migration and old sessions may fail after an upgrade; mark surface without projection and the model may see content it cannot render.

The catalog's verify covers this repository only. A plugin's type errors surface at runtime or in tests, not in the official check.

DeepSeek Harness: Type fingerprints and migrations

A fingerprint is for migration and review, not business code. The machine-readable catalog includes reachable normalized types with SHA-256 digests; comments, source locations, aliases, erased brands, readonly markers, and non-semantic reordering do not affect it, while tuple order, property names, value types, and optionality do (source).

Two conclusions:

  • Text diff changed, fingerprint may not — comments and locations do not break compatibility.
  • Text looks unchanged, fingerprint may change — optionality or tuple order can change semantics.

When a fingerprint changes, check the change notes and historical formats before declaring incompatibility. Compatibility comes from parsing and migration, not from a diff.

Avoid renaming properties or changing optionality without a migration. Letting old logs fail naturally is not a strategy.

DeepSeek Harness: Tracing one event

Walk one event instead of memorizing fields. Use tool/result (source):

  1. Search the formal catalog — confirm it is a persistent event.
  2. Read the envelope — the data holds the tool result.
  3. Classify surface vs log-only — decide whether it enters model history and later projection.
  4. Check the fingerprint — if a plugin parses it, confirm the version matches.
  5. Check migration notes — if reading old logs, confirm the format path.

Five steps answer “is it written, does the model see it, can a new version read it.” That is faster than grepping a session log.

The existing dsh-session-persistence-explained covers the mechanism and develop-session-log covers extension; this article covers the official catalog lookup. Use all three and persistence stops being “whatever is in the log.”

ChatGPTClaudeGrok / X / CursorGemini

FAQ

What is the difference between the DeepSeek Harness persistence catalog and a session log?

The DeepSeek Harness persistence catalog is a type list showing what can be written and how; a session log is the actual record. The catalog answers “can this be stored,” the log answers “what was stored.”

How do surface and log-only events differ in DeepSeek Harness?

A surface event produces model history in DeepSeek Harness; a log-only event is recorded without entering model history. The class decides whether the model can see it.

Why are external plugin events missing from the DeepSeek Harness catalog?

The official DeepSeek Harness catalog covers this repository. An external plugin that extends SessionEventMap must declare its own types and migrations rather than relying on the official list.

Does a changed DeepSeek Harness type fingerprint always mean incompatibility?

DeepSeek Harness does not work that way. The DeepSeek Harness fingerprint ignores comments, locations, aliases, and non-semantic reordering; tuple order, property names, value types, and optionality do change it.

Related Terms

persistence catalog
The persistence catalog is the generated DeepSeek Harness type list covering persistent Session events, the envelope, and all SessionEventMap merges.— DeepSeek Harness reference - Persistence event catalog
event envelope
The event envelope is the common DeepSeek Harness wrapper with type, seq, time, data, optional ignorable, and conditional surfaceOp and sourceEventSeqs.— DeepSeek Harness reference - Persistence event catalog
surface event
A surface event is a DeepSeek Harness event that produces model history; the visible context is projected from these events.— DeepSeek Harness reference - Persistence event catalog
log-only event
A log-only event is a DeepSeek Harness event written to the log without entering model history.— DeepSeek Harness reference - Persistence event catalog

Sources