Adopt read_output controls on brief readers

Merged
UN
6d ago
+481-235

Universal context controls previously refused every pm-brief reader. This change opts all nine commands into the SDK 2026.10.13 read_output contract and returns structured results when canonical controls are requested. Ordinary documents and file-summary JSON/TOON keep their existing output; file writes refuse read controls before writing.

Design and before/after

  • Declare actual, non-overlapping row collections; align the development SDK, peer floor, manifest floor and version contract.
  • Use a scoped output service for ordinary rendered documents and file summaries, declining structured results so the host owns projection, omission receipts, budgets and continuation.
  • Before: pm brief next --output-budget refused usage. After: the installed host applies the requested budget and exposes advancing per-path cursors when rows are compacted.

Validation

  • env HOME=$(mktemp -d) GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1 npm run release:check: 390 passed, 0 failed/skipped.
  • env HOME=$(mktemp -d) GIT_CONFIG_GLOBAL=/dev/null GIT_CONFIG_NOSYSTEM=1 bun run release:check: 390 passed, 0 failed/skipped.
  • Coverage at unchanged thresholds: 100% lines, 98.27% branches, 100% functions across the configured source. All three packed-consumer scenarios (npm-current, bun-current, npm-minimum) pass under both gates.
  • Linked node --test test/read-output-host.test.ts: 13 passed, 0 failed/skipped. The packaged-host suite also passes on Node 22.23.1; archive discovery tolerates npm 10 lifecycle stdout. Strict tracker health with required merge drivers passes.
  • Declaration-only revert: rebuild an isolated snapshot after removing only all nine declarations; all nine reader regressions fail on the host refusal (zero passes or skips).
  • Real temporary trackers and the npm-packed extension verify all readers, projection, infeasible budgets, exact projected row-identity recovery, SDK transports, ordinary documents, all supported document file variants and writer refusal.

Adoption recipe

  1. Pin the development SDK to 2026.10.13 and synchronize the peer/manifest floors and package-specific constants.
  2. Add read_output: { row_keys: [...] } only to readers. Paths must name real, non-overlapping arrays/object maps; use [] for a singleton or nullable result shape.
  3. Return structured payloads for canonical controls. Route ordinary raw documents through a scoped output_format service that declines structured results. Guard hybrid file-writing flags before side effects.
  4. Test every reader through the packed extension and installed host over real trackers: projection, explicit omission, budget-fitting pages, cursor progress and exactly-once row recovery. Later pages may need a larger budget; retry the same cursor without changing semantic inputs.
  5. Remove only declarations in an isolated snapshot, rebuild and require the reader tests to fail; run unchanged npm/Bun release gates.

Tracker: pm-brief-ccwo.

SDK observation: generic budget-string compaction can shorten compound identifiers longer than 240 characters. Tests use ordinary stable IDs and allow disclosed detail compaction; SDK changes and upstream issue filing are outside this task.

Summary by Sourcery

Adopt the SDK 2026.10.13 read-output contract across pm-brief readers while preserving existing document rendering and safely rejecting incompatible file writes.

New Features:

  • Enable all nine pm-brief reader commands to support the SDK universal read-output controls with structured projections, budgets, and cursor-based continuation.

Bug Fixes:

  • Prevent read-output controls from being applied to file-writing commands before any file or tracker mutation occurs.
  • Preserve existing ordinary document, JSON, and TOON output behavior when canonical controls are not requested.

Enhancements:

  • Replace command-specific renderer ownership with a scoped output-format service that leaves structured results to the host.
  • Declare accurate row contracts for each reader and align the SDK, peer dependency, manifest, and version requirements with the read-output contract.

Documentation:

  • Document universal read-output controls, writer restrictions, cursor recovery, row contracts, and the adoption requirements.

Tests:

  • Add packaged-host coverage for projection, omissions, budget handling, cursor recovery, SDK transports, document output, and writer refusal.
  • Update output ownership tests to validate the scoped output service and structured-result fallback behavior.

Chores:

  • Add tracker fixtures and history for the read-output adoption work.

Summary by cubic

Adopts the SDK 2026.10.13 read_output contract on all nine brief read commands, so the host can now apply universal projection, amount, token-budget, and cursor-continuation controls. Previously the host refused these controls; now commands return structured results when canonical controls are requested, while ordinary documents and file summaries keep existing output and file writes refuse read controls before writing.

  • Declares read_output with real, non‑overlapping row paths on all nine readers.
  • Routes ordinary rendered documents through a scoped output service that declines structured results, leaving projection and continuation to the host.
  • Bumps the dev SDK pin, peer dependency floor, and manifest pm_min_version to 2026.10.13.
  • Adds host‑contract tests covering the full read path and verifies that removing the declarations makes the contract fail as expected.