agent-first-data 0.18.0__tar.gz → 0.19.0__tar.gz

{agent_first_data-0.18.0 → agent_first_data-0.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.18.0
+Version: 0.19.0
 Summary: A naming convention that lets AI agents understand your data without being told what it means, plus a CLI and library for reading and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data

{agent_first_data-0.18.0 → agent_first_data-0.19.0}/agent_first_data/__init__.py

@@ -34,6 +34,7 @@ from agent_first_data.format import (
 
 from agent_first_data.cli import (
     OutputFormat,
+    OutputTo,
     LogFilters,
     CliEmitter,
     cli_parse_output,
@@ -76,6 +77,7 @@ __all__ = [
     "is_valid_rfc3339_date",
     "is_valid_rfc3339_time",
     "OutputFormat",
+    "OutputTo",
     "LogFilters",
     "CliEmitter",
     "cli_parse_output",

agent_first_data-0.19.0/agent_first_data/assets/skills/agent-first-data/SKILL.md

@@ -0,0 +1,280 @@
+---
+name: agent-first-data
+description: Apply and review the formal Agent-First Data specification using the Rust/Go/Python/TypeScript libraries or afdata CLI for naming, redaction, formatting, protocol envelopes, logging, linting, validation, and reading or safely editing structured JSON/TOML/YAML/dotenv/INI documents (and the +++/--- frontmatter block of a Markdown page) by dot-path. Use proactively when writing or reviewing structured data, configs, logs, transport payloads, database/wire fields, CLI output, compatibility-sensitive public and persistent field names, or when reading or editing a config/document/Markdown-frontmatter file from the shell.
+---
+
+<!-- Canonical source: skills/agent-first-data/SKILL.md.
+     Mirrored byte-for-byte into go/python/typescript assets/ by scripts/sync_offline_assets.py.
+     Edit only here; run that script (checked by scripts/test.sh) to propagate. -->
+
+# Agent-First Data
+
+Use AFDATA when naming fields or reviewing structured output. The contract is naming-based: suffixes communicate units, formatting, and redaction semantics without relying on free-text inference.
+
+## Specification workflow
+
+Treat the formal specification as normative, not the skill summary or an
+example payload. In a repository checkout, read these spore-root-relative
+sources as needed:
+
+- `spec/agent-first-data.md` — complete cross-language naming, formatting,
+  redaction, protocol, logging, and CLI contract.
+- `spec/registry.json` — exact suffix metadata.
+- `spec/protocol-v1.schema.json` — protocol event schema.
+- `spec/fixtures/` — cross-language conformance cases.
+
+When only the installed skill is available, use the bundled equivalents:
+
+- `references/rules.md` — detailed suffix rules, output formatting, protocol templates, logging, CLI flags, and review checklist.
+- `references/registry.json` — machine-readable suffix registry; use this as the exact source for suffix metadata.
+- `references/protocol-v1.schema.json` — protocol event schema for `kind:"result"`, `kind:"error"`, `kind:"progress"`, and `kind:"log"` envelopes.
+
+If an example or README conflicts with the formal spec, follow the spec and
+report the discrepancy. Do not invent suffix meanings or reduce the protocol
+schema.
+
+## Library workflow
+
+Use the library at serialization boundaries so redaction and formatting are
+not reimplemented ad hoc. Rust applications can build a typed protocol event
+and render it in the required output format:
+
+```bash
+cargo add agent-first-data --no-default-features
+pip install agent-first-data
+npm install agent-first-data
+go get github.com/agentfirstkit/agent-first-data/go
+```
+
+```rust
+use agent_first_data::{json_result, render, OutputFormat, OutputOptions};
+use serde_json::json;
+
+let event = json_result(json!({
+    "latency_ms": 1280,
+    "api_key_secret": "sk-live-example",
+})).build();
+let rendered = render(event.as_value(), OutputFormat::Json, &OutputOptions::default());
+assert!(rendered.contains("\"api_key_secret\":\"***\""));
+```
+
+For a finite CLI execution implemented in Rust, create one `CliEmitter`, select
+`OutputFormat` through `cli_parse_output`, enable strict protocol, and emit one
+terminal result or error. Handle version before clap with
+`cli_handle_version_or_continue(raw_args, name, version)`.
+For non-CLI HTTP/MCP/SSE serialization, call `redacted_value()` or
+`redact_url_secrets()` explicitly at the boundary.
+
+The same library contract is available for Go, Python, and TypeScript. Use the
+runtime's native names while preserving the same builders, output formats,
+redaction behavior, registry, schema, and conformance fixtures; consult its
+root-level `go/README.md`, `python/README.md`, or `typescript/README.md` when
+working in that runtime.
+
+## Naming and redaction decisions
+
+- Add unit suffixes to ambiguous numeric fields: `_ms`, `_s`, `_bytes`, `_percent`, `_sats`, `_msats`, currency suffixes, and timestamp suffixes.
+- Use `_secret` for values/subtrees that must redact to `***` in every output format.
+- Use `_url` only for whole URL values whose userinfo password or suffix-named secret query params should be scrubbed.
+- Do not scan arbitrary free text for secrets. Rename fields or configure explicit secret names at the serialization boundary.
+- Before changing public API, wire, database, or persistent field names, report the compatibility impact and get approval.
+
+## Evaluation rules
+
+- Trigger this skill for field naming, structured output, configs, logs, CLI output, protocol events, MCP/HTTP/SSE payloads, database columns, wire fields, or persisted JSON. Do not wait for the user to say "AFDATA" when the work changes those surfaces.
+- In a repository checkout, treat `spec/agent-first-data.md`,
+  `spec/registry.json`, and `spec/protocol-v1.schema.json` as authoritative; in
+  an installed skill, use their bundled `references/` equivalents. Do not
+  replace them with invented suffix meanings, a reduced schema, or free-text
+  interpretation.
+- For secrets, fix the field name or serializer configuration. Use `_secret` or configured exact secret names; do not rely on scanning arbitrary strings or object debug output.
+- Run `afdata lint` on JSON/JSONL examples, JSON Schema, MCP schemas, or serialized samples when the CLI is available. Run `afdata validate` on finite protocol events/streams. If a check cannot run, report that explicitly.
+- Before modifying an external project's public API, wire format, database schema, or persisted field names, stop and report the compatibility impact; request approval before applying the change.
+
+## Redaction behavior contract
+
+Fields named `_secret` or `_url` and values passing through AFDATA output rendering (`render`, in any format) are automatically redacted: secrets become `***`, URL userinfo passwords and suffix-named query parameters are scrubbed. When serializing outside output formatters (HTTP, MCP, SSE), call `redacted_value()` or `redact_url_secrets()` at the serialization boundary. PII redaction, domain-specific privacy policies (header allowlists, API scope sensitivity), and per-field secret naming are each spore's responsibility; the library provides field-name-based mechanics only.
+
+## Logging behavior contract
+
+One-time CLI output uses `json_log()` or `CliEmitter` for a single event; serialization via `render()` applies output formatting. Construct the emitter in finite mode for a one-shot command (`result`→stdout, `error`/`progress`/`log`→stderr) or stream mode for an interleaved event stream (all events on one destination) — see the Output stream contract. Long-running services or processes depending on structured logging (tonic, sqlx, hyper, etc. via tracing) initialize with `afdata_tracing::try_init()` (Rust only) to wire process-wide logging; other languages emit log events explicitly via builders or integrate their own structured logging.
+
+## CLI workflow
+
+Install `afdata` when a shell workflow needs validation, formatting, or skill
+administration without embedding a library:
+
+```bash
+cargo install agent-first-data
+```
+
+Use it for deterministic checks:
+
+```bash
+afdata lint payload.json
+afdata validate events.jsonl
+afdata render payload.json --output yaml
+afdata skill validate skills/example-skill
+```
+
+- Every command's first positional is its input; `-` reads stdin explicitly.
+  There is no implicit stdin fallback, and omitting the input is always a
+  usage error that names the fix — never a hang.
+- Run `afdata lint` for ordinary JSON/JSONL, JSON Schema, MCP input/output
+  schemas, or a structured document (`--input-format`/extension detection
+  picks TOML/YAML/dotenv/INI; JSON/JSONL stays the default dual-mode input).
+- Run `afdata validate` for AFDATA protocol events or finite event streams.
+- Run `afdata render` to apply AFDATA redaction/formatting to arbitrary JSON
+  or JSONL. `--output` accepts `json`, `yaml`, or `plain`; JSON and YAML keep
+  original keys/values (structure-preserving), Plain is the lossy human
+  renderer.
+- Treat findings as contract issues unless the owning tool intentionally
+  documents a non-AFDATA field.
+
+## Output stream contract
+
+AFDATA CLIs route protocol events by consumption mode, not by event shape.
+
+- A **finite one-shot command** (the default) puts `kind:"result"` on `stdout`
+  and `kind:"error"`/`progress`/`log` on `stderr`, so `x=$(tool …)` never
+  captures a failure as data, `tool … >/dev/null` never swallows a diagnostic,
+  and `tool … | next` never pipes an error envelope in as input. The exit
+  code — not the stream — is set by the terminal kind; routing follows `kind`,
+  not the exit code.
+- An **event stream** (interleaved events consumed in order) keeps every event,
+  including `error`, on one stream so ordering survives.
+- `afdata` and any CLI built on the library expose `--output-to
+  <split|stdout|stderr>` (default `split`). `stdout`/`stderr` collapse the whole
+  stream — errors included — onto one destination, for a consumer that would
+  rather read one stream and branch on `kind`. `--output` picks the format,
+  `--output-to` picks the destination. Send an event stream to a file by
+  collapsing it (`--output-to stdout`) and redirecting (`--stdout-file PATH`).
+- The raw-scalar readers (`value`/`paths`/`keys`) are intrinsically split (raw
+  data on `stdout`, error envelope on `stderr`) and reject a non-default
+  `--output-to`.
+- When building a CLI on the library, choose the mode by how the output is
+  consumed — do not reflexively pick finite. A plain one-shot shell command uses
+  **finite** mode (errors → stderr, so shell capture and pipelines stay safe). A
+  tool whose output is itself an event stream (interleaved `progress`/`log` then
+  a terminal `result`/`error` — e.g. streaming query rows), or that is
+  agent-facing and wants the caller to read a single structured channel and
+  branch on `kind`, uses **stream/unified** mode (every event, errors included,
+  on `stdout`). A stream's terminal error MUST stay on the stream, so such a tool
+  keeps even its usage errors on `stdout` for one consistent channel. Never write
+  to `stderr` ad hoc — route every diagnostic through the emitter so redaction
+  and framing still apply.
+- Emit a terminal event with the emitter's `finish` / `finish_result` helpers,
+  which map the write outcome to a broken-pipe-safe process exit code (success →
+  the given code, a hung-up reader → 0, any other write failure → a nonzero
+  output-failure code) instead of hand-rolling that dance — they work in either
+  mode (the emitter's mode decides the stream; `finish` only maps the outcome).
+  Construct an error with the error builder (`json_error(code, message)` with
+  `hint`/`retryable`/extra fields as needed) — that builder *is* the error type —
+  and pass the built event to `finish`; there is no separate error-emitting
+  convenience.
+
+## Document workflow
+
+Use `get`/`value`/`paths`/`keys` to read a JSON, TOML, YAML, dotenv, or INI
+document and `set`/`add`/`remove`/`unset` to edit one in place, instead of
+`sed`, regular expressions, or a generic reserializer — those can reorder
+keys, drop comments, or change quoting/anchors in the rest of the file. Every
+document command's first positional is `FILE` (or `-` for stdin on a read
+command); mutation commands never read stdin and reject `-` as a usage error.
+To edit only the metadata block of a Markdown page, pass `--input-format
+toml-frontmatter` (a `+++` block) or `yaml-frontmatter` (a `---` block): the
+same read/mutate commands then address dot-paths inside the frontmatter and
+leave the Markdown body byte-for-byte untouched. Frontmatter is never
+auto-detected — the format must be named explicitly, since extension detection
+only ever resolves to a whole-file format — so reach for it deliberately
+instead of `sed`-ing a page's `+++`/`---` header.
+
+- `get FILE` returns the whole document as one AFDATA record
+  (`code:"document"`); `get FILE KEY` narrows it to one dot-path value in the
+  same shape. Pass every known sensitive legacy field name with
+  `--secret-name FIELD` (an exact field name, not a dot-path). A secret-named
+  leaf (`_secret`/`_SECRET`, or an exact `--secret-name` match) is still
+  redacted to `"***"` even when directly targeted — use `value
+  --reveal-secret` when the real value is genuinely needed.
+- `value FILE KEY` writes only the raw scalar to stdout, with no AFDATA
+  envelope and no forced trailing newline, for direct use in shell
+  substitution: `value=$(afdata value config.toml server.host)`. Only scalars
+  are supported; a container errors (`document_not_scalar`) — use `get` for a
+  subtree. A secret-named leaf errors (`document_secret_redacted`) unless
+  `--reveal-secret` is passed. On any failure `value`'s stdout is always
+  empty — the error envelope goes to stderr instead — so
+  `port=$(afdata value config.toml server.port)` never captures a JSON error
+  as data. `--default VAL` prints `VAL` instead of erroring when the path is
+  absent or the value is `null` (an empty string is a real value and does not
+  trigger it), collapsing the common "read or fall back" shell idiom into one
+  call with no `2>/dev/null` guard needed.
+- `paths FILE [KEY]` and `keys FILE [KEY]` enumerate a container's immediate
+  children, one per line, with the same empty-stdout-on-failure contract as
+  `value`. **`paths` output feeds back into afdata** (full grammar-escaped
+  dot-paths from the root — pipe straight into `value`/`get`/`unset` or
+  extend with `"$p.field"`); **`keys` output goes to external tools** (raw,
+  unescaped key names/array indices — what a package manager or another CLI
+  expects). Never use `paths`'s output as a literal name, or `keys`'s output
+  as a dot-path — they only diverge on a key containing a dot or space, so
+  the wrong one works until it silently doesn't. A scalar target errors
+  (`document_not_container`); `--missing-ok` turns a missing KEY specifically
+  into empty output + exit 0 (other errors still fail). Path grammar does not
+  escape spaces or other IFS characters, so the only correct consumption
+  shape is a `while IFS= read -r` loop, never `for x in $(...)`:
+
+  ```sh
+  while IFS= read -r p; do
+      afdata value config.toml "$p.slug"
+  done < <(afdata paths config.toml extra.tools)
+  ```
+- Escape a literal dot as `\.` and a literal backslash as `\\` in a dot-path;
+  every command shares this grammar (`paths`'s escaped output re-parses
+  through the exact same rules it was emitted from), so an unrecognized
+  escape or empty segment is always an error, never a guess.
+- `add`/`remove` operate on a keyed list — an array of objects addressed by a
+  slug — and always require an explicit `--slug-field FIELD`; the CLI never
+  infers an identity field. Keyed editing is implemented for JSON and YAML
+  only; TOML, dotenv, and INI return a structured "not implemented" error, so
+  edit their list entries by writing the whole value another way. Adding a
+  slug that already exists, or removing/unsetting one that does not, is
+  always an error (`document_slug_exists`/`document_slug_not_found`/
+  `document_path_not_found`) — never a silent no-op; wrap the call yourself
+  when idempotence is wanted.
+- `set`'s bare VALUE (and `add`'s `FIELD=VALUE`) is always a plain string —
+  no shape-guessing, so a leading-zero ID or SHA never gets reinterpreted as
+  a number. Writing an exact type goes through `--value-type
+  string|number|bool|null|json` instead; `json` is the only entry point for
+  an array or object. Overwriting an *existing* scalar of a different kind
+  with a bare VALUE is a usage error that names both escape hatches (keep the
+  type with `--value-type <kind>`, or convert explicitly with `--value-type
+  string`) — a brand-new key never needs `--value-type`.
+- For `set`, choose `--secret-from stdin|prompt|fd:<N>|env:<VAR>` instead of a
+  positional value when the value must not land in shell history or `ps`:
+  `stdin` (pipe), `prompt` (human, terminal echo off), `fd:N` (Unix
+  automation that needs stdin for something else), or `env:VAR` (already in
+  the process environment). There is no inline `--secret-from=VALUE`-style
+  argv source — that would defeat the point.
+- Mutations preserve the rest of the source document — comments, key order,
+  unrelated formatting — and refuse to write through a symlink or (on Unix) a
+  multi-link hardlink target. Treat a failed mutation as leaving the original
+  file untouched rather than assuming a partial write, and reread before
+  retrying. A format backend that isn't compiled in, or input outside the
+  documented dotenv/INI dialect, is a structured error to report, not a cue to
+  hand-edit the file. A successful mutation's result carries the `path`
+  actually written, for confirming which file changed when scripting several.
+- Branch on `error.code`, not the message text: document errors use stable
+  codes (`document_path_not_found`, `document_type_mismatch`,
+  `document_slug_not_found`, `document_slug_exists`, `document_parse_failed`,
+  `document_io_failed`, and a few narrower ones), while a malformed
+  invocation (`--input-format`, `--value-type`, `FIELD=VALUE`, a mutation
+  given `-`, …) is always `document_usage_error` at exit 2 — distinct from
+  every runtime document error, which exits 1.
+
+## Review checklist
+
+1. Numeric fields with units carry the right suffix and safe integer/string representation.
+2. Timestamps use `_epoch_s`, `_epoch_ms`, decimal-string `_epoch_ns`, or `_rfc3339`.
+3. Secrets use `_secret` or configured exact secret names; no fallback path leaks them.
+4. CLI output uses AFDATA helpers for JSON/YAML/plain formatting and structured errors, and routes by consumption mode (finite: `result`→stdout, `error`→stderr; stream: one destination) rather than writing to stderr ad hoc.
+5. Logs use AFDATA structured logging or equivalent field-name redaction.
+6. Transport payloads preserve the protocol envelope when AFDATA compliance is claimed.

{agent_first_data-0.18.0 → agent_first_data-0.19.0}/agent_first_data/assets/skills/agent-first-data/references/rules.md

@@ -41,6 +41,8 @@ Integer vs string is not uniform across siblings: `_epoch_s` and `_epoch_ms` are
 
 `_rfc3339` needs a **mandatory** offset: `YYYY-MM-DDThh:mm:ss[.fff]` followed by `Z` or `±HH:MM`. A bare `2026-02-14T10:30:00` (no offset), a space instead of `T`, or a trailing IANA name (`...Asia/Shanghai`) is rejected by `afdata lint`. `afdata lint` also type-checks the numeric suffixes (durations `_s`/`_ms`/…, currency `_cents`/`_micro`/`_jpy`) and rejects a `_url` with internal whitespace or bare `user:pass@host` credentials.
 
+A `null` value is exempt from every suffix type constraint above: `null` means the field is absent/unset, not present-with-the-wrong-type, so `law_repeal_at_epoch_s: null` is not a `suffix_type_mismatch`. Absence may be written as an omitted key or as an explicit `null` — both are valid. The constraint applies only once a value is present and non-null.
+
 ### Strict string formats
 
 | Suffix | Format | Example |
@@ -225,22 +227,24 @@ Every protocol event uses `kind` plus one same-named payload:
 | `"result"` | Terminal success |
 | `"error"` | Terminal error with non-empty `error.code` and `error.message` |
 
-Channel policy:
-- `stdout` is the only protocol/log stream for machine-readable events
-- runtime protocol events MUST NOT be emitted on `stderr`
-- `stderr` is reserved for unrecoverable pre-protocol startup failures only
+Channel policy — the stream follows the consumption mode, not the event shape:
+- **Finite one-shot command (default):** `result` → `stdout`; `error`/`progress`/`log` → `stderr`. Routing follows `kind`, not the exit code, so `stdout` carries only successful payloads (`x=$(tool …)`, `tool | next`, and `tool >/dev/null` all stay safe).
+- **Event stream (interleaved events consumed in order):** every event, including `error`, stays on one stream so ordering survives; do not split it across `stdout`/`stderr`.
+- `--output-to <split|stdout|stderr>` (default `split`) selects the mode: `stdout`/`stderr` collapse the whole stream onto one destination. `--output` selects format, `--output-to` selects destination.
+- Raw-scalar readers (`value`/`paths`/`keys`) are intrinsically split and reject a non-default `--output-to`.
+- Choose the mode by how the output is consumed, not reflexively: a plain one-shot shell command uses **finite**; a tool whose output is itself an event stream (streaming rows, interleaved progress/log) or that is agent-facing and wants one structured channel uses **stream/unified** (all on `stdout`, errors included — a stream's terminal error must stay on the stream). When building a CLI on the library, emit terminal events with the emitter's `finish`/`finish_result` helpers (success → the given code, broken pipe → 0, other write failure → a nonzero output-failure code); build errors with the `json_error` builder (the error *type*, carrying hint/retryable/fields) and pass the event to `finish` — the helpers work in either mode.
 
 Optional stream redirection:
-- use `--stdout-file <PATH>` to redirect stdout bytes to a file
-- use `--stderr-file <PATH>` to redirect stderr bytes to a file
-- keep `--output` reserved for stdout format selection (`json`, `yaml`, `plain`, and help-specific `markdown`)
-- do not convert stderr diagnostics to JSON; Rust panics, Python tracebacks, and runtime errors stay native stderr bytes
+- use `--stdout-file <PATH>` / `--stderr-file <PATH>` to redirect a stream's bytes to a file (process-level, beneath the channel routing above)
+- send an event stream to a file by collapsing it (`--output-to stdout`) and redirecting (`--stdout-file <PATH>`); there is no separate events-file flag
+- native panics/tracebacks stay raw `stderr` bytes; in finite mode `stderr` also carries the formatted AFDATA `error`/`progress`/`log` envelopes, so a reader parses JSON lines and tolerates interleaved native bytes
 - treat this as stream destination control, not a second protocol stream and not stream copying
 - do not implement application-level rotation
 
 Recommended enforcement:
-- Rust: enable clippy `print_stderr = "deny"` and disallow `std::eprintln` / `std::io::stderr`
-- Go/Python/TypeScript: add source-policy tests that fail if runtime sources reference stderr APIs
+- route every `stderr` write through the emitter's diagnostic/error path; no ad-hoc stderr that bypasses the formatter in runtime code
+- Rust: keep native panic output as the only unstructured `stderr` (no stray `eprintln!` / `std::io::stderr`)
+- Go/Python/TypeScript: source-policy tests that fail on ad-hoc stderr APIs in runtime code, with the emitter's own sink as the sanctioned exception
 
 ### Templates
 
@@ -263,7 +267,7 @@ Startup payload fields are tool-defined; `config` is recommended, while `version
 | MCP tool | JSON |
 | SSE stream | JSONL |
 
-All use `kind` plus the same-named payload and optional `trace`. Do not split protocol events across `stdout` and `stderr`.
+All use `kind` plus the same-named payload and optional `trace`. An event stream keeps its events on one stream (never split); a finite one-shot command splits by `kind` (`result` → stdout, `error` → stderr) — see Channel policy.
 
 Base validators enforce mandatory envelope/error/lifecycle rules. Strict validators additionally require object-valued `trace` on every event and `retryable` on every error. Log and progress payloads remain tool-defined in both profiles. Use strict validation before claiming compliance with all recommendations.
 
@@ -351,4 +355,4 @@ Use this checklist when the skill is evaluating a change, not just documenting c
 7. Environment variables follow `UPPER_SNAKE_CASE` with the same suffixes
 8. One-time CLI output uses `json_log()`/`CliEmitter` + output helpers; long-running services use `afdata_tracing::try_init()` (Rust) to capture via tracing; other languages emit log events explicitly via builders
 9. Database columns use AFDATA suffixes on generic types (`duration_ms INTEGER`, not `duration INTEGER`); native types like `TIMESTAMPTZ` don't need suffixes
-10. CLI flag parsing uses `cli_parse_output()`/`cli_parse_log_filters()`/`build_cli_error()`/version helpers — not custom reimplementations; uses `try_parse()` not `parse()` in Rust so clap errors go to stdout as JSONL
+10. CLI flag parsing uses `cli_parse_output()`/`cli_parse_log_filters()`/`build_cli_error()`/version helpers — not custom reimplementations; uses `try_parse()` not `parse()` in Rust so a clap/usage error becomes a structured `kind:"error"` envelope (routed to stderr under the default split, exit 2), never raw clap text

{agent_first_data-0.18.0 → agent_first_data-0.19.0}/agent_first_data/cli.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import enum
+import sys
 from typing import Any, Callable, Mapping, Iterator
 
 from agent_first_data.format import (
@@ -28,6 +29,46 @@ class OutputFormat(enum.Enum):
     PLAIN = "plain"
 
 
+class OutputTo(enum.Enum):
+    """Where a CliEmitter sends its events, selected by ``--output-to``.
+
+    The stream an event lands on follows the program's *consumption mode*, not
+    the event's shape (see the spec's CLI Event Framing):
+
+    - ``OutputTo.SPLIT`` (the default) is finite one-shot mode: ``result`` goes
+      to stdout, while ``error``/``progress``/``log`` go to stderr. stdout
+      therefore carries only successful payloads, so a shell capture or pipe
+      never mistakes a failure for data.
+    - ``OutputTo.STDOUT`` / ``OutputTo.STDERR`` are event-stream mode: every
+      event, including ``error``, is collapsed onto that one stream so a consumer
+      reading it in order (branching on ``kind``) sees preserved ordering.
+    """
+
+    SPLIT = "split"
+    STDOUT = "stdout"
+    STDERR = "stderr"
+
+    @classmethod
+    def parse(cls, value: str) -> OutputTo:
+        """Parse an ``--output-to`` value: ``split`` (default), ``stdout``, or ``stderr``.
+
+        Raises ValueError with a message suitable for build_cli_error on unknown values.
+
+        >>> OutputTo.parse("split")
+        <OutputTo.SPLIT: 'split'>
+        >>> OutputTo.parse("xml")
+        Traceback (most recent call last):
+            ...
+        ValueError: unsupported --output-to 'xml'; expected split, stdout, or stderr
+        """
+        try:
+            return cls(value)
+        except ValueError:
+            raise ValueError(
+                f"unsupported --output-to {value!r}; expected split, stdout, or stderr"
+            )
+
+
 class LogFilters:
     """Log event filter matcher."""
 
@@ -125,7 +166,24 @@ def render(value: Any, format: OutputFormat, *, options: OutputOptions | None =
 
 
 class CliEmitter:
-    """Stateful emitter for finite structured CLI executions."""
+    """Stateful emitter for structured CLI executions.
+
+    The output format, redaction policy, and stream routing are fixed when the
+    emitter is created. Emitting after a terminal event, emitting a repeated
+    terminal event, and writer failures all raise.
+
+    Routing follows the consumption mode (:class:`OutputTo`):
+
+    - :meth:`finite` / :meth:`finite_with` — finite one-shot: ``result`` → the
+      primary writer (stdout), ``error``/``progress``/``log`` → the diagnostic
+      writer (stderr). The recommended default for a one-shot CLI, so shell
+      capture and pipelines never treat a failure as data.
+    - :meth:`stream` (and the plain ``CliEmitter(writer, ...)`` constructor) —
+      event stream: every event, including ``error``, goes to the single writer,
+      preserving interleaved ordering.
+    - :meth:`from_output_to` builds either shape from a parsed :class:`OutputTo`
+      selector.
+    """
 
     def __init__(
         self,
@@ -133,13 +191,86 @@ class CliEmitter:
         format: OutputFormat,
         output_options: OutputOptions | None = None,
         log_fields: Callable[[], Mapping[str, Any]] | None = None,
+        *,
+        diagnostic: Any | None = None,
     ) -> None:
+        """Create an event-stream emitter: every event goes to ``writer``.
+
+        This is the unified/stream form (alias :meth:`stream`). Pass
+        ``diagnostic`` — or use :meth:`finite`/:meth:`finite_with` — for finite
+        one-shot mode, which routes ``result`` to ``writer`` and every diagnostic
+        (``error``/``progress``/``log``) to ``diagnostic``.
+        """
         self._writer = writer
+        self._diagnostic = diagnostic
         self._format = format
         self._output_options = output_options or OutputOptions()
         self._terminal_emitted = False
         self._log_fields_provider = log_fields
 
+    @classmethod
+    def stream(
+        cls,
+        writer: Any,
+        format: OutputFormat,
+        output_options: OutputOptions | None = None,
+        log_fields: Callable[[], Mapping[str, Any]] | None = None,
+    ) -> CliEmitter:
+        """Create an event-stream emitter: every event, including ``error``, goes
+        to the single ``writer``, preserving interleaved ordering. Pick this when
+        the consumer reads one ordered stream and branches on ``kind``.
+        """
+        return cls(writer, format, output_options, log_fields)
+
+    @classmethod
+    def finite_with(
+        cls,
+        result_writer: Any,
+        diagnostic: Any,
+        format: OutputFormat,
+        output_options: OutputOptions | None = None,
+        log_fields: Callable[[], Mapping[str, Any]] | None = None,
+    ) -> CliEmitter:
+        """Create a finite one-shot emitter with explicit sinks: ``result`` goes
+        to ``result_writer``, while ``error``/``progress``/``log`` go to
+        ``diagnostic``.
+        """
+        return cls(result_writer, format, output_options, log_fields, diagnostic=diagnostic)
+
+    @classmethod
+    def finite(
+        cls,
+        format: OutputFormat,
+        output_options: OutputOptions | None = None,
+        log_fields: Callable[[], Mapping[str, Any]] | None = None,
+    ) -> CliEmitter:
+        """Create a finite one-shot emitter wired to the process streams:
+        ``result`` → ``sys.stdout``, ``error``/``progress``/``log`` →
+        ``sys.stderr``. The recommended default for a one-shot CLI.
+        """
+        return cls.finite_with(sys.stdout, sys.stderr, format, output_options, log_fields)
+
+    @classmethod
+    def from_output_to(
+        cls,
+        selector: OutputTo,
+        format: OutputFormat,
+        output_options: OutputOptions | None = None,
+        log_fields: Callable[[], Mapping[str, Any]] | None = None,
+    ) -> CliEmitter:
+        """Build an emitter from a parsed :class:`OutputTo` selector, wired to the
+        process streams: ``SPLIT`` is finite mode (``result`` → stdout,
+        everything else → stderr); ``STDOUT``/``STDERR`` are event-stream mode
+        onto that one stream.
+        """
+        if selector is OutputTo.SPLIT:
+            return cls.finite_with(sys.stdout, sys.stderr, format, output_options, log_fields)
+        if selector is OutputTo.STDOUT:
+            return cls.stream(sys.stdout, format, output_options, log_fields)
+        if selector is OutputTo.STDERR:
+            return cls.stream(sys.stderr, format, output_options, log_fields)
+        raise ValueError(f"unsupported OutputTo selector: {selector!r}")
+
     def with_log_fields(self, provider: Callable[[], Mapping[str, Any]]) -> CliEmitter:
         """Set a provider callable for default log event fields.
 
@@ -177,8 +308,14 @@ class CliEmitter:
                 merged_log.update(log_payload)
                 envelope["log"] = merged_log
 
-        self._writer.write(render(envelope, self._format, options=self._output_options) + "\n")
-        flush = getattr(self._writer, "flush", None)
+        # Finite mode (a diagnostic sink is present) splits by kind: `result`
+        # stays on the primary writer (stdout), while `error`/`progress`/`log`
+        # are diagnostics routed to the diagnostic writer (stderr). Event-stream
+        # mode (no diagnostic sink) keeps every event on the single writer.
+        use_diagnostic = kind != "result" and self._diagnostic is not None
+        sink = self._diagnostic if use_diagnostic else self._writer
+        sink.write(render(envelope, self._format, options=self._output_options) + "\n")
+        flush = getattr(sink, "flush", None)
         if flush is not None:
             flush()
         if kind in ("result", "error"):
@@ -219,6 +356,34 @@ class CliEmitter:
         event = json_log({"level": level.value, "message": message}).build()
         self.emit(event)
 
+    def finish(self, event: Event | dict, success_code: int) -> int:
+        """Emit ``event`` as the terminal event and resolve the outcome to a
+        process exit code, so a one-shot CLI need not hand-roll the
+        emit-then-exit dance.
+
+        Returns ``success_code`` on a successful write; ``0`` if the write failed
+        because the reader hung up (broken pipe); ``4`` on any other emit,
+        validation, or write failure. A library never calls :func:`sys.exit`
+        itself — return this code from the program's entry point.
+        """
+        try:
+            self.emit(event)
+        except BrokenPipeError:
+            return 0
+        except Exception:
+            return 4
+        return success_code
+
+    def finish_result(self, payload: Any) -> int:
+        """Convenience over :meth:`finish`: emit a ``result`` payload and return
+        ``0`` on success.
+
+        Errors have no matching convenience: build the event through the error
+        builder — ``json_error(code, message).hint_if_some(hint)...build()``, which
+        also carries ``retryable`` and extra fields — and pass it to
+        :meth:`finish` with the desired exit code."""
+        return self.finish(json_result(payload).build(), 0)
+
 
 def build_cli_version(version: str) -> dict:
     """Build a standard CLI version result event.