Define evidence-linked session view profiles

[Sinity]

Purpose

Define shared session-view profiles so CLI, web, MCP/API, and exports render large sessions consistently. A view profile declares what a view includes, what it omits, whether it is lossy, what raw/evidence refs it carries, and which formats are supported.

Current implementation reality

polylogue read --view already exposes multiple views through polylogue/cli/query_verbs.py and adjacent command modules:

• public/current views include summary, transcript, messages, raw, context, context-pack, recovery, neighbors, and correlation;
• recovery uses polylogue.insights.transforms.compile_recovery_digest(session) on demand and exposes continue/blame report presets;
• messages has typed JSON/NDJSON payloads and generated schemas;
• context-pack, neighbors, and correlation have separate command modules and output behavior;
• web/API ambitions need the same semantics but should not invent another view vocabulary.

The problem is not that views are missing. The problem is that their semantics are scattered across renderers, Click options, docs, payload schemas, and future web/API plans. A caller cannot inspect one profile record to learn whether a view is lossy, evidence-linked, raw, redacted, browse-only, or suitable for agent handoff.

Rationale

Polylogue sessions can be huge. Different users need different readings: raw transcript, compact handoff, forensic drilldown, tool audit, neighbor sessions, GitHub correlation, or a browser preview. These views should be honest about lossiness and evidence.

A summary-like view without raw refs is fine if labeled as a browse aid. It is not fine if later agents treat it as complete evidence. Conversely, a raw view should be explicit about privacy/access posture.

Profile fields

A SessionViewSpec or equivalent live model should include:

• stable view id and human label;
• owning module/renderer;
• purpose and primary user workflow;
• required input: session id, query set, project scope, archive root, external repo, or daemon/API context;
• included object kinds: messages, blocks, tools, files, subagents, assertions, events, refs, raw payload;
• lossiness: raw, normalized, filtered, summarized, sampled, derived, or browse-only;
• raw/evidence-ref policy: required, optional, unavailable, or intentionally omitted;
• privacy/redaction policy: path redaction, raw payload gating, secret handling;
• supported output formats and destinations;
• machine payload/schema when available;
• degraded/unsupported states and the exact caveat exposed to callers;
• whether the view is suitable for successor-agent handoff.

Initial profile inventory

The first implementation should profile existing views before adding new ones:

• raw: raw provider/archive record where available; unambiguously raw and access-gated.
• messages: normalized message/block view with filters for role/type/prose/tool/file-read suppression; typed JSON/NDJSON schemas already exist.
• summary / transcript: human-readable query/read outputs; define whether these are browse aids, normalized transcripts, or evidence-bearing views.
• context: seed-session preamble plus related sessions; lossy handoff aid.
• context-pack: project/query-scoped bundle; lossy and redacted by default.
• recovery: deterministic on-demand transform over a hydrated session; lossy but evidence-linked and intended for successor-agent handoff when caveats are explicit.
• neighbors: time-window related-session view; relationship evidence rather than content summary.
• correlation: Git/issue/check/span correlation; explicitly external-observation-backed.

Future names such as tool-audit, subagents, forensic, resume, digest, and work-packet should be added only when backed by concrete renderers and acceptance fixtures.

Implementation plan

Implement profiles as live surface metadata, not a documentation inventory.

1. Add a profile/spec model close to the read/render surface, not a new archive tier.
2. Inventory existing read --view implementations against the profile fields and make every public view declare its contract.
3. Route CLI help/docs/profile listing through the same profile records where practical.
4. Ensure recovery/work-packet profiles cite Transform raw agent sessions into on-demand recovery views #1880/Render work packets as on-demand evidence bundles #1838 and describe raw-ref/lossiness semantics honestly.
5. Add explicit degraded/unsupported markers for views whose current implementation cannot satisfy a promised profile.
6. Add fixtures comparing representative CLI and API/web JSON semantics where a machine payload exists.
7. Make docs/help/profile listings derive from or check against the profile records so stale view names disappear automatically.

Acceptance criteria

• Every public read view has a profile that declares lossiness, input requirements, supported formats, and raw-ref policy.
• Lossy views that make claims include ObjectRef/EvidenceRef/raw-ref links or explicitly state that they are browse-only.
• Recovery and work-packet outputs declare whether they are successor-agent handoff views and what caveats/missing-evidence markers mean.
• CLI and web/API render or expose the same profile semantics for representative fixtures.
• Unsupported/degraded views say so explicitly instead of implying completeness.
• Docs and help text are generated from or checked against the profile inventory so view names do not drift.

Non-goals

• No new storage tier.
• No LLM summary as truth.
• No deletion of raw transcript/drilldown.
• No separate renderer ontology beyond what real views consume.
• No view names that are only parser/help vocabulary without execution.