✨ feat(derive): project transcript-only sessions

[yeazelm]

Summary

• Materialize transcript-only uploads as historical sessions and queue them for asynchronous projection.
• Select the active transcript branch, coalesce assistant fragments, and preserve tools, usage, context, titles, timestamps, and subagent relationships.
• Use transcript fallback only when the session has no successfully parsed main-conversation wire call.
• Replace transcript-derived turns automatically when authoritative wire capture arrives later.

How it works

Transcript records are normalized into canonical full-history TurnChains and merged chronologically with any shadow or compaction wire calls. Both sources enter the shared Deriver.addChainTurn fold, so node deduplication, tool attachment, reporting, and span construction follow the same path.

The raw transcript row, historical session identity, and derive queue entry are committed atomically. Projection remains asynchronous and reports its provenance at trace level.

Relationship to #330

This supersedes draft #330 while retaining its central architectural approach: canonical TurnChain construction and a shared addChainTurn derivation seam. It extends that design with active-branch resolution, fragment coalescing, stable identities, mixed shadow-call ordering, late-wire replacement, atomic session materialization, and broader corpus and PostgreSQL coverage.

Behavior matrix

Session data	Result
Transcript only	Project the selected transcript conversation
Transcript plus shadow/compaction wire calls	Merge chronologically through the shared derivation seam
Transcript plus parsed main wire call	Suppress transcript fallback
Transcript first, main wire later	Replace and prune transcript-derived projection
Re-uploaded transcript version	Deduplicate raw content and queue re-projection

Test plan

• golangci-lint v2.8.0
• All non-PostgreSQL Go package tests with GOEXPERIMENT=jsonv2
• PostgreSQL storage suite: 128 specs
• Transcript corpus, equivalent-wire parity, branch, timing, attachment, and late-wire replacement tests
• git diff --check

Part of PCC-1278

[linear-code]

PCC-1278

[greptile-apps]

Greptile Summary

Materializes transcript-only uploads as historical sessions and derives stable transcript-backed traces until authoritative main wire capture becomes available.

• Adds causal branch selection, assistant-fragment coalescing, stable transcript identities, tool/subagent attachment, and transcript provenance.
• Chronologically combines transcript fallback with compatible shadow and compaction wire calls.
• Atomically persists transcript rows, session identity, and dirty-session work while enabling later wire-derived replacement and pruning.

Confidence Score: 5/5

The pull request appears safe to merge; no concrete blocking or independently actionable non-blocking defects were identified.

Transcript ingestion, fallback derivation, authoritative-wire replacement, and projection pruning remain transactionally and causally aligned across the changed paths.

Important Files Changed

Filename	Overview
pkg/derive/transcript_projection.go	Adds transcript branch selection, normalization, fragment coalescing, stable identities, and mixed-source fallback preparation without an accepted defect.
pkg/derive/deriver.go	Introduces a shared wire/transcript chain fold and session-scoped authoritative-wire probing while preserving existing derivation behavior.
pkg/derive/spans.go	Extends trace and span projection with transcript identities, provenance, timing, and prompt fallback handling.
pkg/storage/postgres/derive.go	Selects current transcript versions, probes wire authority, merges calls chronologically, and relies on existing transactional pruning.
pkg/storage/postgres/raw_turns.go	Materializes transcript session identity and timestamps in the same transaction as raw persistence and queue marking.
pkg/storage/postgres/queries/sessions.sql	Adds an idempotent transcript-session upsert that widens observed time bounds and preserves existing optional metadata.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    U[Transcript upload] --> T[Atomic raw row and session upsert]
    T --> Q[Dirty derive queue]
    Q --> P{Parsed main wire call exists?}
    P -- No --> F[Select active transcript branches]
    F --> N[Normalize transcript TurnChains]
    P -- Yes --> W[Use authoritative wire conversation]
    N --> M[Chronologically merge shadow and compaction wire calls]
    W --> D[Shared derivation fold]
    M --> D
    D --> R[Transactional trace and span projection]
    R --> X[Prune obsolete transcript projection]

Loading

_{Reviews (1): Last reviewed commit: "✨ feat(derive): project transcript-only ..." | Re-trigger Greptile}