Refactor Runtime, Session, and output types

[ziflex]

This pull request introduces a major refactor to the output and content handling across the API, especially for query execution and debugger events. The core change is the migration from materialized output structs to a new model where Output is a one-shot handle, and actual data is accessed through explicit consumption (Consume, Collect) resulting in detached, immutable Content objects. This affects the Go API, JSON representations, and debugger event contracts. The changes clarify ownership, error handling, and concurrency, and provide new documentation and tests to support the new model.

API and Output Handling Refactor

• Runtime.Run and Session.Run now return a caller-owned, one-shot Output handle; actual data is accessed via Consume or Collect, and output presence/errors are handled separately from execution errors. The new model is thoroughly documented in README.md and doc.go. [1] [2] [3]
• The Output struct is replaced by a detached Content struct for materialized data, with clear rules for presence, absence, and error reporting. The JSON encoding for output is changed to a nested metadata/data object, and live output handles must not be serialized. [1] [2]

Debugger Event Model Update

• Debugger events now retain output as detached *Content, not live output handles, ensuring that reading an event does not consume output or require retaining a session. This is reflected in the Event struct and associated documentation. [1] [2] [3]
• Tests are added to verify that event JSON serialization preserves content presence, emptiness, and the ability to accompany errors, without requiring round-tripping of Go errors.

Options and Content Type Handling

• Output/content codec selection is clarified: WithOutputContentType and SetOutputContentType now refer to the encoded representation's media type, which is reported by Output.Metadata().ContentType. Codec availability is validated during encoding and surfaced through consumption errors. [1] [2] [3] [4]

Serialization and Migration Details

• The migration from the old materialized output model to the new detached content model is documented, including changes to the API and JSON encoding, with examples provided in the README.md. [1] [2]

These changes modernize and clarify output handling, making resource ownership and error propagation more explicit and robust.

[Copilot]

Copilot review overview

🟡 Changes recommended

The lifecycle contract cannot reliably combine terminal and close errors without either duplication or loss.

Review effort: Balanced
Findings: 1

Open (1)

• Lifecycle contract can duplicate or lose cleanup errors · New

What changed in this PR

Refactors execution output into one-shot handles with detached content, updating debugger events, serialization, documentation, and tests.

Changes:

• Adds Output consumption and collection contracts.
• Introduces detached Content, metadata, and lifecycle errors.
• Migrates debugger output and JSON tests.

File	Description
types.go	Exports new result aliases and errors.
session.go	Updates session execution contract.
runtime.go	Updates runtime execution ownership.
result/​types.go	Defines output and content contracts.
result/​types_test.go	Tests content JSON behavior.
result/​errors.go	Adds lifecycle sentinels.
result/​doc.go	Documents result package semantics.
README.md	Documents usage and migration.
output_examples_test.go	Tests streaming examples.
output_example_test.go	Adds executable usage examples.
output_contract_test.go	Verifies aliases and caller behavior.
output_contract_fixture_test.go	Adds scripted output fixtures.
options.go	Clarifies codec selection.
doc.go	Documents root output lifecycle.
debugger/​types.go	Migrates event output to content.
debugger/​session.go	Clarifies event ownership.
debugger/​doc.go	Documents detached event content.
debugger/​content_test.go	Tests debugger content serialization.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.