openclaw - 💡(How to fix) Fix [Feature]: Add typed transcript projections and a documented companion rebuild contract [4 pull requests]

Summary

Add typed transcript projections/helpers for high-value read paths and document the supported companion rebuild path from canonical SQLite state.

Related:

• umbrella: #79902
• active refactor: #78595

Problem to solve

OpenClaw's canonical transcript store is event-first, which is the right runtime model. The remaining problem is that every serious consumer still has to recover useful read models from opaque event blobs and private branch logic.

The highest-value repeated needs are:

• message_role
• tool_call_id
• active-branch traversal / selection
• clear guidance for replaying canonical SQLite rows into a separate companion database

There are already signs in the schema that this kind of thin projection is acceptable:

• transcript_event_identities exists as a lightweight identity projection in openclaw-agent-schema.sql
• active-branch traversal already exists privately in session-transcript-readers.ts

The current issue is that consumers still have to recover useful message and tool structure by reparsing event_json or borrowing private runtime helpers.

Proposed solution

Add either lightweight write-time projections or stable helper accessors for:

• message_role
• tool_call_id
• active-branch traversal / selection

Also add documentation for the supported companion rebuild contract:

• canonical source is SQLite transcript/session state
• rebuild/replay should be idempotent
• consumers should not depend on legacy JSONL runtime compatibility
• canonical discovery should be anchored to session-row/session-key ownership, not raw transcript-id enumeration

This should remain a generic ecosystem seam, not a plugin-specific feature.

Possible acceptable forms:

• expand transcript_event_identities with a few additional generic columns
• expose helper functions over canonical transcript rows
• expose a branch-aware read helper that returns the active event slice and stable identities
• document which transcript ids are canonical runtime scopes versus snapshot/successor maintenance artifacts

Alternatives considered

1. Keep raw blobs as the only source and let each consumer parse them

This maximizes flexibility, but every consumer repeats risky parsing and tool-join logic.

2. Move companion semantic models into core

This would blur the runtime boundary and overfit core to specialized downstream needs.

Impact

Affected:

• companions that need structured message/tool reconstruction
• future export, audit, search, and indexing features

Severity:

• medium to high for correctness-sensitive consumers

Frequency:

• common for tool-heavy transcripts and long-lived sessions

Consequence:

• duplicated blob archaeology
• inconsistent tool/result joins
• unclear rebuild expectations for downstream consumers

Platform value:

• cleaner export, search, and audit implementations
• safer tool-heavy replay for first-party or third-party consumers
• fewer private runtime imports to get branch-safe message views

Evidence/examples

The current runtime already extracts a thin identity table, which suggests a small amount of additional projection or helper packaging would pay off broadly without turning the core schema into a companion-specific model.

Representative anchors:

• identity projection table: openclaw-agent-schema.sql
• private branch helper: session-transcript-readers.ts
• tool-call normalization exists in runtime code paths such as attempt.tool-call-normalization.ts
• raw transcript listing includes every stored session_id, including snapshot/successor transcripts: transcript-store.sqlite.ts

Additional information

Acceptance scenarios:

• tool-heavy transcripts round-trip without companion-side guesswork
• active-branch selection does not require private gateway helpers
• a populated install can rebuild a companion DB from canonical SQLite state without relying on JSONL files
• documented rebuild contract states what replay guarantees consumers may assume
• rebuild guidance clearly distinguishes canonical session scopes from maintenance/snapshot transcript ids

Non-goals:

• importing LCM's message_parts table into OpenClaw core
• turning the canonical transcript store into a fully denormalized companion schema