Skip to content

Ticket #226: contract the legacy direct-message transcript store — verification ​

  • Date: 2026-11-11
  • Branch: ticket/226-legacy-dm-contract
  • Spec: parent #209; ticket #226
  • ADRs: 0009, 0010
  • Unit gate: npm run verify (strict typecheck + full test suite)

Behavior ​

Direct conversations have one durable message store: the conversation channel dm:<agentID>[:<workspaceID>]. The per-binding dmTranscripts snapshot branch and the v2/dm/ read/write path are gone from normal operation.

  • chat.context reads the channel rows, attaches the surviving queue state by message id, and (before the native-first cutover) reads assistant text from the native session so a rollback cannot duplicate an answer.
  • Direct sends, queued-line removal, and the pre-cutover home-to-workspace move write and move channel rows only. There is no second transcript to sync.
  • Attachment-only rows keep their attachment metadata and render as a chip even when the transcript text is empty.
  • The client store no longer bounds or carries a separate direct transcript; direct rows use the same patch, window, bound, and retention path as a group.

Migration and backfill ​

V2Store.migrateLegacyDirectTranscripts() runs once during service.start() after load() and before any reader serves the direct chat.

  1. Scan v2/dm/ and group rows by binding (workspaceKey, agentID).
  2. For each channel, scan its existing v2/message/<channel>/ rows. A durable row wins over its legacy copy by message id, so a #212 dual-written row is never duplicated and the durable text is authoritative.
  3. Merge missing legacy lines, sort by the pre-channel transcript order (createdAt, user before other roles on a tie, then id), and assign contiguous sequence numbers. This preserves line order across rows written before #212 and rows written after it.
  4. Write every desired channel row first. Only then remove superseded sequence keys and the mapped v2/dm/ rows. A malformed legacy key that cannot be mapped to a channel is left in place rather than deleted unmigrated.
  5. Commit the channel rows as normal message upserts. A completed migration is a no-op and does not bump the version.

The two phases make an interrupted migration recoverable: a crash after the writes leaves both copies, and the next start merges by id and deletes the legacy keys. The worst case is a transient duplicate key, never a lost line. Rows written before the #212 dual-write are exercised directly in the store and service tests.

Queued state comes from the DmQueueEntry, which was already durable outside the transcript. The migration tests seed a pre-existing queued entry and prove the migrated line still renders queued, then clears when the entry settles. Attachment metadata (id, name, MIME, size, kind) is copied unchanged; the legacy row's queued display bit is not persisted on the message because the queue is the source of truth.

Snapshot and patch contract ​

  • SnapshotState has no dmTranscripts field, createInitialState no longer creates one, and the scoped shell projection no longer clears one.
  • A direct message is still a normal message entity patch keyed by its channel. Migration emits message upserts through the same feed; it never resets the feed.
  • The serialized snapshot is asserted to contain no dmTranscripts key.
  • The client store never allocates a direct transcript map, so reload and patch application cannot resurrect one.

Prune, reset, archive, rebind, retention ​

  • Prune workspace: removes the workspace group channel and every dm:<agentID>:<workspaceID> channel, plus their queue entries; home direct channels and their queues survive.
  • Prune agent: removes every direct channel and queue entry for that agent, leaving another agent's conversation intact.
  • Reset: clears every channel and queue entry. It also sweeps a leftover v2/dm/ prefix so an interrupted migration cannot survive a reset.
  • Agent archive: keeps the direct channel and its history; deletion prunes them.
  • Workspace archive: keeps the workspace direct channel and its history; deletion prunes them.
  • Rebind: agent.rebindSession moves only the binding; the conversation channel and its rows are untouched and remain readable.
  • Retention and bounds: direct rows use the same transcript window, client-message bound, and durable retention as group rows. The existing channel window/client-bound test now runs after the legacy store is removed.

Rollback path ​

The previous release (ticket #212) remains the rollback path. Its ENSEMBLE_DM_CHANNEL_READS=on mode reads the durable channel rows and merges the, now empty, legacy list. Because this release migrates every legacy line to the channel before removing the store, rolling back the release and leaving the channel-read flag on sees the complete transcript, including lines written after the cutover.

projectDirectLines is kept as the pure read contract the previous release uses; the rollback test asserts that projecting the migrated channel with an empty legacy list returns every line in order. After this release there is no in-process flag back to a second store. Rollback means returning to the previous release with channel reads enabled.

Tests ​

npm run verify on this branch: strict typecheck passed; 1770 tests passed, 0 failed, 0 skipped. Coverage includes:

  • pre-#212 legacy rows and #212 dual-written rows backfilled in transcript order with no duplicate, then the legacy keys removed;
  • migration idempotence and reload with no re-migration;
  • a queued pre-channel line surviving with its queue state;
  • text and attachment-only lines preserving attachment metadata;
  • workspace and home direct channels staying separate;
  • snapshot shape (dmTranscripts absent from state and serialized payload);
  • direct message patches staying message entities with no reset;
  • prune workspace/agent with queue coverage, reset, agent archive, workspace archive, workspace/agent deletion, direct-session rebind, and the pre-cutover home-to-workspace channel move;
  • the previous-release rollback projection and a current-release reload seeing the same lines without duplication.

No conversation content, attachment bytes, credentials, or private paths are used in the fixtures or logs.

Live check ​

No new live-host run was performed for this ticket. The change is a storage contract and read-path switch exercised at the service boundary with the existing fake host; the #227 cutover record owns the final live acceptance.

Released under the MIT License.