agent-first-data 0.35.0__tar.gz → 0.36.0__tar.gz

{agent_first_data-0.35.0 → agent_first_data-0.36.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.35.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 Markdown structure and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.
+Version: 0.36.0
+Summary: A naming convention that lets AI agents understand your data without being told what it means, plus the afdata CLI and a Rust library for reading Markdown structure and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
 Requires-Python: >=3.9
@@ -28,10 +28,12 @@ print(render(value, OutputFormat.JSON))
 print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_urls_in_text`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `decode_protocol_event`.
+Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_urls_in_text`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_parse_log_filters`, `CliEmitter`, `decode_protocol_event`.
 
 ## Behavior Notes
 
+- `OutputOptions(reveal_names=...)` reveals exact structured field names at the selected output boundary. Children still pass through redaction; URL parameters and argv receive no exemption.
+- The protocol reader accepts base-profile events. An absent `error.retryable` remains nullable; strict validation is a separate opt-in.
 - Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
 - `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed, and internal whitespace or a `://` that is not the start of a clean URL redacts the whole field, where whitespace is the explicit Unicode `White_Space` set the spec enumerates, not the language's native predicate.
 - `OutputOptions.url_names` applies URL treatment to exact legacy field names
@@ -40,7 +42,7 @@ Useful names use Python casing: `render` (the single value x format x options ->
 - YAML keeps original keys and values (structure-preserving, like JSON), sorting keys by UTF-16 code unit order and quoting/escaping unsafe keys and string scalars. Plain strips formatting suffixes, formats values, sorts the same way, and renders nested objects/arrays as canonical JSON; it quotes a value only when it contains ASCII space, tab, newline, carriage return, form feed, vertical tab, NBSP, `=`, `"`, or `\`, and escapes `\`, `"`, newline, carriage return, tab, form feed, and vertical tab inside the quotes.
 - Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Do not add a raw version/help pre-parser. Until the Python `CliSpec` compiler lands, applications should keep lifecycle parsing in their own parser rather than claim AFDATA closed-world help compatibility.
+- Do not add a raw version/help pre-parser. This SDK provides emitters and readers; argv and lifecycle parsing belong to the application. Claim help-v2 or closed-world compatibility only when using a registry compiler.
 
 ## Reference
 

{agent_first_data-0.35.0 → agent_first_data-0.36.0}/README.md

@@ -19,10 +19,12 @@ print(render(value, OutputFormat.JSON))
 print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_urls_in_text`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `decode_protocol_event`.
+Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_urls_in_text`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_parse_log_filters`, `CliEmitter`, `decode_protocol_event`.
 
 ## Behavior Notes
 
+- `OutputOptions(reveal_names=...)` reveals exact structured field names at the selected output boundary. Children still pass through redaction; URL parameters and argv receive no exemption.
+- The protocol reader accepts base-profile events. An absent `error.retryable` remains nullable; strict validation is a separate opt-in.
 - Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
 - `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed, and internal whitespace or a `://` that is not the start of a clean URL redacts the whole field, where whitespace is the explicit Unicode `White_Space` set the spec enumerates, not the language's native predicate.
 - `OutputOptions.url_names` applies URL treatment to exact legacy field names
@@ -31,7 +33,7 @@ Useful names use Python casing: `render` (the single value x format x options ->
 - YAML keeps original keys and values (structure-preserving, like JSON), sorting keys by UTF-16 code unit order and quoting/escaping unsafe keys and string scalars. Plain strips formatting suffixes, formats values, sorts the same way, and renders nested objects/arrays as canonical JSON; it quotes a value only when it contains ASCII space, tab, newline, carriage return, form feed, vertical tab, NBSP, `=`, `"`, or `\`, and escapes `\`, `"`, newline, carriage return, tab, form feed, and vertical tab inside the quotes.
 - Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Do not add a raw version/help pre-parser. Until the Python `CliSpec` compiler lands, applications should keep lifecycle parsing in their own parser rather than claim AFDATA closed-world help compatibility.
+- Do not add a raw version/help pre-parser. This SDK provides emitters and readers; argv and lifecycle parsing belong to the application. Claim help-v2 or closed-world compatibility only when using a registry compiler.
 
 ## Reference
 

{agent_first_data-0.35.0 → agent_first_data-0.36.0}/agent_first_data/assets/cli-spec-v1.schema.json

@@ -44,7 +44,7 @@
     },
     "exit_codes": {
       "type": "array",
-      "description": "Exit codes this CLI returns beyond AFDATA's 0/1/2, rendered into the reference's exit-code table. 0/1/2 are AFDATA's own and may not be redeclared.",
+      "description": "Exit codes this CLI returns beyond AFDATA's 0/1/2/4, rendered into the reference's exit-code table. AFDATA's codes may not be redeclared.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -56,7 +56,10 @@
           "code": {
             "type": "integer",
             "minimum": 3,
-            "maximum": 255
+            "maximum": 255,
+            "not": {
+              "const": 4
+            }
           },
           "meaning": {
             "$ref": "#/$defs/nonEmpty"

{agent_first_data-0.35.0 → agent_first_data-0.36.0}/agent_first_data/cli.py

@@ -210,6 +210,7 @@ class CliEmitter:
         self._output_options = output_options or OutputOptions()
         self._strict_protocol = strict_protocol
         self._terminal_emitted = False
+        self._write_failed = False
 
     def with_strict_protocol(self) -> CliEmitter:
         """Opt this emitter into the AFDATA recommended strict profile."""
@@ -277,6 +278,7 @@ class CliEmitter:
 
     def emit(self, event: Event | dict) -> None:
         """Emit a typed Event or a dict (for compatibility)."""
+        self._write_failed = False
         if isinstance(event, Event):
             envelope = event.to_dict()
         else:
@@ -320,6 +322,10 @@ class CliEmitter:
                     finally:
                         os.close(null_descriptor)
             raise
+        except Exception:
+            # Marks the failure as output's, not the event's, for finish().
+            self._write_failed = True
+            raise
         if kind in ("result", "error"):
             self._terminal_emitted = True
 
@@ -363,19 +369,40 @@ class CliEmitter:
         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.
+        Returns ``success_code`` on a successful write; ``0``, saying nothing,
+        if the write failed because the reader hung up (broken pipe). Any other
+        write failure returns ``4`` after reporting ``output_write_failed`` as
+        an ``error`` event: on the diagnostic writer in finite mode, on
+        ``sys.stderr`` in event-stream mode, whose only writer is the one that
+        just failed. That report is best effort. An event the emitter refuses
+        (a protocol violation or a second terminal event) is the command's own
+        failure, not an output one, and returns ``1``. 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:
+            if not self._write_failed:
+                return 1
+            self._report_output_write_failed()
             return 4
         return success_code
 
+    def _report_output_write_failed(self) -> None:
+        event = json_error("output_write_failed", "could not write command output").build()
+        try:
+            if self._diagnostic is not None:
+                self.emit(event)
+            else:
+                # Event-stream mode has no diagnostic writer, so the report
+                # goes to the process's stderr through an emitter of its own.
+                CliEmitter.stream(sys.stderr, self._format).with_strict_protocol().emit(event)
+        except Exception:
+            pass
+
     def finish_result(self, payload: Any) -> int:
         """Convenience over :meth:`finish`: emit a ``result`` payload and return
         ``0`` on success.

{agent_first_data-0.35.0 → agent_first_data-0.36.0}/agent_first_data/format.py

@@ -51,7 +51,7 @@ class EventBuildError(Exception):
 
 
 class Event:
-    """Opaque typed event envelope wrapping a validated protocol dict."""
+    """SDK event envelope; validate externally supplied trace values explicitly."""
 
     def __init__(self, envelope: dict) -> None:
         """Private: only builders and validators construct Events."""
@@ -302,7 +302,7 @@ def _validate_error_payload(error: Any) -> None:
     if not isinstance(message, str) or message == "":
         raise ValueError("event.error.message must be a non-empty string")
     if "retryable" in error and not isinstance(error["retryable"], bool):
-        raise ValueError("event.error.retryable must be a boolean")
+        raise ValueError("event.error.retryable must be a boolean when present")
     if "hint" in error and not isinstance(error["hint"], str):
         raise ValueError("event.error.hint must be a string when present")
 
@@ -364,11 +364,9 @@ class _RawNumber:
     """Internal: a decoded JSON number whose exact source literal must
     survive re-emission (see decode_protocol_event's number-fidelity note).
 
-    Deliberately not an int/float subclass: Part 2's suffix-driven formatting
-    (`_is_number`, `_as_int`, ...) checks `isinstance(value, (int, float))`,
-    so a `_RawNumber` gracefully falls through to the existing "wrong type"
-    passthrough there rather than risking a lossy or crashing arithmetic
-    conversion. JSON/YAML/plain leaf rendering special-case it directly.
+    Deliberately not an int/float subclass. Serializers treat it as an opaque
+    scalar; integer-required suffixes inspect its exact decimal digits, while
+    unit scaling uses a bounded floating conversion only where needed.
     """
 
     __slots__ = ("literal",)
@@ -383,11 +381,15 @@ class _RawNumber:
 def _parse_int_lossless(text: str) -> Any:
     """json.loads parse_int hook: int() is exact for every JSON integer
     literal except "-0" (int("-0") == 0, dropping the sign), so only that
-    one case needs wrapping; every other integer stays a plain arbitrary-
-    precision Python int, unchanged from the pre-fidelity behavior."""
+    case and literals beyond Python's conversion limit need wrapping. Other
+    integers stay plain arbitrary-precision Python ints."""
     if text == "-0":
         return _RawNumber(text)
-    return int(text)
+    try:
+        return int(text)
+    except ValueError:
+        # Python's configurable conversion limit is not a JSON grammar limit.
+        return _RawNumber(text)
 
 
 def _parse_float_lossless(text: str) -> Any:
@@ -412,7 +414,7 @@ class DecodedError:
 
     code: str
     message: str
-    retryable: bool
+    retryable: bool | None
     hint: str | None = None
     fields: dict[str, Any] = field(default_factory=dict)
     trace: dict | None = None
@@ -434,12 +436,55 @@ class DecodedLog:
     trace: dict | None = None
 
 
+def _reject_non_json_constant(name: str) -> Any:
+    # ``json.loads`` accepts ``NaN`` and ``Infinity`` by default; they are not
+    # JSON, and every other SDK's decoder refuses them.
+    raise ValueError(f"{name} is not a JSON number")
+
+
+# How many arrays and objects a protocol line may nest, counting the envelope
+# object. Every SDK enforces the same bound.
+_MAX_PROTOCOL_NESTING = 127
+_JSON_STRING_OR_BRACKET = re.compile(r'"(?:[^"\\]+|\\.)*"|[\[\]{}]')
+_SURROGATE = re.compile("[\ud800-\udfff]")
+
+
+def _nesting_exceeds_limit(text: str) -> bool:
+    """Whether brackets outside strings nest past the bound. Checked before
+    ``json.loads``, which would otherwise recurse until RecursionError."""
+    if text.count("[") + text.count("{") <= _MAX_PROTOCOL_NESTING:
+        return False
+    depth = 0
+    for match in _JSON_STRING_OR_BRACKET.finditer(text):
+        token = match.group()
+        if token in "[{":
+            depth += 1
+            if depth > _MAX_PROTOCOL_NESTING:
+                return True
+        elif token in "]}":
+            depth -= 1
+    return False
+
+
+def _has_lone_surrogate(value: Any) -> bool:
+    """``json.loads`` joins an escaped surrogate pair into one character and
+    keeps a lone surrogate (escaped or raw) as-is, so any surrogate code point
+    left in a decoded key or string is a lone one."""
+    if isinstance(value, str):
+        return _SURROGATE.search(value) is not None
+    if isinstance(value, dict):
+        return any(_has_lone_surrogate(k) or _has_lone_surrogate(v) for k, v in value.items())
+    if isinstance(value, list):
+        return any(_has_lone_surrogate(item) for item in value)
+    return False
+
+
 def decode_protocol_event(
     text: str,
 ) -> DecodedResult | DecodedError | DecodedProgress | DecodedLog:
-    """Parse and strict-validate a single protocol v1 JSON line into a typed event.
+    """Parse and base-validate a single protocol v1 JSON line into a typed event.
 
-    Raises EventDecodeError if ``text`` is not valid JSON or fails strict
+    Raises EventDecodeError if ``text`` is not valid JSON or fails base
     validation.
 
     Number literal fidelity: ``json.loads``'s default integer parsing is
@@ -448,17 +493,26 @@ def decode_protocol_event(
     default float parsing collapses any literal through float64 (30 significant
     digits become 15-17, "0.1000...055511..." becomes "0.1"). ``parse_int``/
     ``parse_float`` hooks below route both exceptions through ``_RawNumber``,
-    which stores the exact source literal; every JSON/YAML/plain renderer in
-    this module treats it as an opaque scalar and re-emits that literal
-    verbatim. This is internal — ``_RawNumber`` is never part of the public API.
+    which stores the exact source literal; JSON re-emits that literal
+    verbatim, and YAML/plain render it in the spec's canonical number form
+    without losing a digit. This is internal — ``_RawNumber`` is never part of the public API.
     """
+    if _nesting_exceeds_limit(text):
+        raise EventDecodeError(f"invalid JSON: nesting deeper than {_MAX_PROTOCOL_NESTING}")
     try:
-        event = json.loads(text, parse_int=_parse_int_lossless, parse_float=_parse_float_lossless)
+        event = json.loads(
+            text,
+            parse_int=_parse_int_lossless,
+            parse_float=_parse_float_lossless,
+            parse_constant=_reject_non_json_constant,
+        )
     except (ValueError, TypeError) as exc:
         raise EventDecodeError(f"invalid JSON: {exc}") from exc
+    if _has_lone_surrogate(event):
+        raise EventDecodeError("invalid JSON: lone surrogate in a string")
 
     try:
-        validate_protocol_event(event, strict=True)
+        validate_protocol_event(event, strict=False)
     except ValueError as exc:
         raise EventDecodeError(str(exc)) from exc
 
@@ -475,7 +529,7 @@ def decode_protocol_event(
         return DecodedError(
             code=error["code"],
             message=error["message"],
-            retryable=error["retryable"],
+            retryable=error.get("retryable"),
             hint=error.get("hint"),
             fields=fields,
             trace=trace,
@@ -544,6 +598,8 @@ class OutputOptions:
     # None or RedactionPolicy.All = full redaction (default).
     policy: RedactionPolicy | None = None
     style: PlainStyle = PlainStyle.Readable
+    # Exact structured field names to reveal; URL parameters and argv stay redacted.
+    reveal_names: Sequence[str] = ()
 
     @classmethod
     def for_policy(cls, policy: RedactionPolicy) -> OutputOptions:
@@ -561,6 +617,7 @@ def _format_json(value: Any, *, options: OutputOptions | None = None) -> str:
         value,
         secret_names=output_options.secret_names,
         url_names=output_options.url_names,
+        reveal_names=output_options.reveal_names,
         policy=output_options.policy,
     )
     return _encode_json_lossless(redacted)
@@ -601,6 +658,7 @@ def _format_yaml(value: Any, *, options: OutputOptions | None = None) -> str:
         value,
         secret_names=output_options.secret_names,
         url_names=output_options.url_names,
+        reveal_names=output_options.reveal_names,
         policy=output_options.policy,
     )
     lines = ["---"]
@@ -618,6 +676,7 @@ def _format_plain(value: Any, *, options: OutputOptions | None = None) -> str:
         value,
         secret_names=output_options.secret_names,
         url_names=output_options.url_names,
+        reveal_names=output_options.reveal_names,
         policy=output_options.policy,
     )
     if not isinstance(value, dict):
@@ -646,6 +705,7 @@ def redacted_value(
     *,
     secret_names: Sequence[str] = (),
     url_names: Sequence[str] = (),
+    reveal_names: Sequence[str] = (),
     policy: RedactionPolicy | None = None,
 ) -> Any:
     """Return a JSON-safe copy with redaction options applied.
@@ -654,7 +714,7 @@ def redacted_value(
     Redacts _url fields and exact ``url_names`` entries by the same rules.
     """
     v = _sanitize_for_json(value)
-    _apply_redaction(v, secret_names, url_names, policy)
+    _apply_redaction(v, secret_names, url_names, policy, reveal_names)
     return v
 
 
@@ -770,8 +830,9 @@ def _apply_redaction(
     secret_names: Sequence[str],
     url_names: Sequence[str],
     policy: RedactionPolicy | None,
+    reveal_names: Sequence[str] = (),
 ) -> None:
-    context = _RedactionContext.from_names(secret_names, url_names)
+    context = _RedactionContext.from_names(secret_names, url_names, reveal_names)
     _apply_redaction_policy_with_context(value, policy, context)
 
 
@@ -1036,16 +1097,19 @@ class _RedactionContext:
 
     secret_names: frozenset[str] = frozenset()
     url_names: frozenset[str] = frozenset()
+    reveal_names: frozenset[str] = frozenset()
 
     @classmethod
     def from_names(
         cls,
         secret_names: Sequence[str],
         url_names: Sequence[str] = (),
+        reveal_names: Sequence[str] = (),
     ) -> _RedactionContext:
         return cls(
             secret_names=frozenset(secret_names),
             url_names=frozenset(url_names),
+            reveal_names=frozenset(reveal_names),
         )
 
     def is_secret_key(self, key: str) -> bool:
@@ -1069,7 +1133,7 @@ def _redact_secrets(value: Any, context: _RedactionContext = _RedactionContext()
     if isinstance(value, dict):
         for k in list(value.keys()):
             v = value[k]
-            if context.is_secret_key(k):
+            if context.is_secret_key(k) and k not in context.reveal_names:
                 # A null secret is an absent secret. Masking it would
                 # manufacture the appearance of a configured credential —
                 # readers cannot tell "***"-because-set from
@@ -1103,7 +1167,7 @@ def _redact_url_value(value: Any, context: _RedactionContext, depth: int) -> Any
     if isinstance(value, dict):
         for key in list(value.keys()):
             item = value[key]
-            if context.is_secret_key(key):
+            if context.is_secret_key(key) and key not in context.reveal_names:
                 if item is not None:
                     value[key] = REDACTED_MARKER
             else:
@@ -1117,7 +1181,7 @@ def _redact_url_value(value: Any, context: _RedactionContext, depth: int) -> Any
 # ═══════════════════════════════════════════
 
 
-def _redact_url_in_str(s: str, context: _RedactionContext) -> str | None:
+def _redact_url_in_str(s: str, context: _RedactionContext, depth: int = 0) -> str | None:
     """Redact secret components of a single URL string.
 
     Returns the redacted string when ``s`` is a processable URL, or None when it
@@ -1127,6 +1191,9 @@ def _redact_url_in_str(s: str, context: _RedactionContext) -> str | None:
     # Fast path + precondition: a single, whitespace-free, scheme-prefixed URL.
     if "://" not in s or not _is_single_url(s):
         return None
+    # Bound recursive redirect inspection, failing closed before stack growth.
+    if depth >= 16:
+        return REDACTED_MARKER
     scheme_sep = s.find("://")
     scheme = s[:scheme_sep]
     rest = s[scheme_sep + 3 :]
@@ -1137,9 +1204,29 @@ def _redact_url_in_str(s: str, context: _RedactionContext) -> str | None:
         if c in "/?#":
             auth_end = i
             break
+    # An unencoded '?' or '#' inside a password ends that authority early and
+    # leaves the rest of the password in the query or fragment. When a ':'
+    # precedes that early end and an '@' follows it before the first '/', the
+    # userinfo runs to that '@' — how libpq reads such a connection string.
+    first_slash = rest.find("/")
+    if first_slash == -1:
+        first_slash = len(rest)
+    at = rest.rfind("@", 0, first_slash)
+    if ":" in rest[:auth_end] and at > auth_end:
+        auth_end = len(rest)
+        for i in range(at, len(rest)):
+            if rest[i] in "/?#":
+                auth_end = i
+                break
     authority = rest[:auth_end]
     remainder = rest[auth_end:]
 
+    # An unencoded '/' inside a password ends the authority at a "port" that
+    # is not a number, with the '@' somewhere after it. Where the password
+    # ends cannot be known, so the whole value is replaced.
+    if "@" not in authority and _has_non_numeric_port(authority) and "@" in remainder:
+        return REDACTED_MARKER
+
     new_authority = _redact_userinfo_password(authority)
 
     # `remainder` is `path[?query][#fragment]`; '#' ends the query, so split the
@@ -1147,7 +1234,7 @@ def _redact_url_in_str(s: str, context: _RedactionContext) -> str | None:
     before_fragment, hash_sep, fragment = remainder.partition("#")
     path, question_sep, query = before_fragment.partition("?")
     if question_sep:
-        new_before_fragment = f"{path}?{_redact_query(query, context)}"
+        new_before_fragment = f"{path}?{_redact_query(query, context, depth)}"
     else:
         new_before_fragment = before_fragment
     # A fragment gets the same treatment as the query: `k=v&k=v` after the '#'
@@ -1155,7 +1242,19 @@ def _redact_url_in_str(s: str, context: _RedactionContext) -> str | None:
     # secret-named fragment parameter must not survive where the identically
     # named query parameter would not. A fragment that is not in that shape has
     # no '=' in its segments and passes through byte-for-byte.
-    new_fragment = f"#{_redact_query(fragment, context)}" if hash_sep else ""
+    # A hash route (`#/cb?k=v`) carries its parameters after its first '?',
+    # while a form reader keeps that '?' inside a value; redact both readings:
+    # the fragment as parameters first, so a secret value absorbs its '?',
+    # then whatever follows the first '?' that survives.
+    if not hash_sep:
+        new_fragment = ""
+    else:
+        params = _redact_query(fragment, context, depth)
+        route, route_sep, route_query = params.partition("?")
+        if route_sep:
+            new_fragment = f"#{route}?{_redact_query(route_query, context, depth)}"
+        else:
+            new_fragment = f"#{params}"
 
     return f"{scheme}://{new_authority}{new_before_fragment}{new_fragment}"
 
@@ -1306,7 +1405,7 @@ def _redact_userinfo_password(authority: str) -> str:
     return f"{authority[:colon]}:{REDACTED_MARKER}{authority[at:]}"
 
 
-def _redact_query(query: str, context: _RedactionContext) -> str:
+def _redact_query(query: str, context: _RedactionContext, depth: int) -> str:
     """Redact the values of secret-named query parameters.
 
     Preserves the raw bytes of every other segment (keys, benign values,
@@ -1324,11 +1423,33 @@ def _redact_query(query: str, context: _RedactionContext) -> str:
         name = unquote_plus(raw_key)
         if context.is_secret_key(name):
             segments.append(f"{raw_key}={REDACTED_MARKER}")
+            continue
+        # A redirect target carries its own parameters: redact a nested URL in
+        # place, or the whole value when it arrived encoded.
+        raw_value = segment[eq + 1 :]
+        value = unquote_plus(raw_value)
+        redacted = _redact_url_in_str(value, context, depth + 1)
+        if redacted is not None and redacted != value:
+            if value == raw_value:
+                segments.append(f"{raw_key}={redacted}")
+            else:
+                segments.append(f"{raw_key}={REDACTED_MARKER}")
         else:
             segments.append(segment)
     return "&".join(segments)
 
 
+def _has_non_numeric_port(authority: str) -> bool:
+    """True when the authority's text after its last ':' is not a port number.
+
+    A bracketed IPv6 literal without a port ends in ']' and has none.
+    """
+    colon = authority.rfind(":")
+    if colon == -1 or authority.endswith("]"):
+        return False
+    return not all("0" <= c <= "9" for c in authority[colon + 1 :])
+
+
 def _is_single_url(s: str) -> bool:
     """True when ``s`` is a single bare URL, not a URL embedded in prose.
 
@@ -1395,17 +1516,100 @@ def _is_number(value: Any) -> bool:
 
 def _number_str(value: int | float) -> str:
     """Render a number canonically for YAML/plain output."""
-    if isinstance(value, float) and math.isfinite(value) and value.is_integer() and abs(value) < 1e21:
-        return str(int(value))
-    s = repr(value) if isinstance(value, float) else str(value)
-    return _normalize_exponent(s)
+    if isinstance(value, float):
+        return _number_literal_str(repr(value))
+    return str(value)
+
+
+def _number_literal_str(literal: str) -> str:
+    """Render a number's literal canonically for YAML/plain output: a float
+    literal whose value is an integer below 1e21 in magnitude renders as that
+    integer (``3.0`` -> ``3``, ``-0.0`` -> ``-0``); anything else keeps its
+    digits, placed by ``_place_decimal_point``. Native floats (via ``repr``)
+    and decoded literals share this, and it works on the text so a digit is
+    never lost to a float64 round trip."""
+    integral = _integral_float_text(literal)
+    if integral is not None:
+        return integral
+    placed = _place_decimal_point(literal)
+    return placed if placed is not None else _normalize_exponent(literal)
+
+
+_I64_MIN = -(2**63)
+_I64_MAX = 2**63 - 1
+
+
+def _place_decimal_point(literal: str) -> str | None:
+    """Spell a non-integral float literal with the notation ECMAScript's
+    ``Number#toString`` picks: positional when the value lies in [1e-6, 1e21),
+    exponent form otherwise. ``repr`` switches below 1e-4 and the other SDKs'
+    native formatters elsewhere, so the choice is made here, on the digits as
+    written. ``None`` for integer literals and exponents beyond i64, which keep
+    their spelling."""
+    if not any(c in literal for c in ".eE"):
+        return None
+    sign = "-" if literal.startswith("-") else ""
+    unsigned = literal[1:] if sign else literal
+    mantissa, *exponent = re.split("[eE]", unsigned, maxsplit=1)
+    whole, _, fraction = mantissa.partition(".")
+    digits = whole + fraction
+    significant = digits.lstrip("0")
+    if not significant:
+        return None
+    exponent_text = exponent[0] if exponent else "0"
+    shape = re.fullmatch(r"([+-]?)0*([0-9]*)", exponent_text)
+    if shape is None or not exponent_text.lstrip("+-") or len(shape.group(2)) > 19:
+        return None
+    exp = int(shape.group(1) + (shape.group(2) or "0"))
+    # point: how many significant digits precede the decimal point.
+    point = len(whole) - (len(digits) - len(significant)) + exp
+    if not (_I64_MIN <= exp <= _I64_MAX and _I64_MIN <= point - 1 and point <= _I64_MAX):
+        return None
+    if 1 <= point <= 21:
+        integer, rest = significant[:point], significant[point:]
+        if not rest:
+            return None
+        text = f"{integer}.{rest}"
+    elif -5 <= point <= 0:
+        text = "0." + "0" * -point + significant
+    else:
+        scale = point - 1
+        rest = f".{significant[1:]}" if len(significant) > 1 else ""
+        text = f"{significant[0]}{rest}e{'-' if scale < 0 else '+'}{abs(scale)}"
+    return sign + text
+
+
+def _integral_float_text(literal: str) -> str | None:
+    if not any(c in literal for c in ".eE"):
+        return None
+    negative = literal.startswith("-")
+    unsigned = literal[1:] if negative else literal
+    mantissa, *exponent = re.split("[eE]", unsigned, maxsplit=1)
+    whole, _, fraction = mantissa.partition(".")
+    digits = whole + fraction
+    if not digits.strip("0"):
+        return "-0" if negative else "0"
+    try:
+        exp = int(exponent[0]) if exponent else 0
+    except ValueError:
+        return None
+    point = len(whole) + exp
+    split = min(max(point, 0), len(digits))
+    if any(d != "0" for d in digits[split:]):
+        return None
+    padding = min(max(point - len(digits), 0), 22)
+    integer = (digits[:split] + "0" * padding).lstrip("0")
+    if len(integer) > 21:
+        return None
+    return ("-" if negative else "") + (integer or "0")
 
 
 def _normalize_exponent(s: str) -> str:
     if "e" not in s and "E" not in s:
         return s
     mantissa, exp = re.split("[eE]", s, maxsplit=1)
-    sign = ""
+    # An unsigned exponent is positive; spell it like repr() does (e+23).
+    sign = "+"
     if exp.startswith(("+", "-")):
         sign, exp = exp[0], exp[1:]
     exp = exp.lstrip("0") or "0"
@@ -1420,25 +1624,35 @@ def _as_int(value: Any) -> int | None:
     # Accept integral-valued floats (3.0 -> 3): JS/TS cannot distinguish 3 from
     # 3.0 after JSON parsing, so integrality (not lexical form) gates integer
     # suffixes, keeping the four implementations consistent.
-    if isinstance(value, float) and math.isfinite(value) and value.is_integer():
-        return int(value)
+    # A float is read through its shortest spelling (``repr``), the text the
+    # canonical number form prints, so 2.0**60 counts as 1152921504606847000
+    # exactly as a decoded literal of that spelling does in every SDK; int()
+    # of the binary value would give ...846976 and disagree with Rust.
+    if isinstance(value, float) and math.isfinite(value):
+        literal = repr(value)
+        integer = _integral_float_text(literal) if re.search(r"[.eE]", literal) else literal
+        return int(integer) if integer is not None else None
     return None
 
 
-def _as_non_neg_int(value: Any) -> int | None:
-    n = _as_int(value)
-    if n is not None and n >= 0:
+def _raw_as_int(value: Any) -> int | None:
+    if isinstance(value, _RawNumber):
+        if re.fullmatch(r"-?[0-9]+", value.literal):
+            return int(value.literal) if len(value.literal.lstrip("-")) <= 20 else None
+        integer = _integral_float_text(value.literal)
+        return int(integer) if integer is not None else None
+    return _as_int(value)
+
+
+def _as_u64(value: Any) -> int | None:
+    n = _raw_as_int(value)
+    if n is not None and 0 <= n <= 18_446_744_073_709_551_615:
         return n
     return None
 
 
 def _as_i64(value: Any) -> int | None:
-    if isinstance(value, _RawNumber):
-        if not re.fullmatch(r"-?\d+", value.literal):
-            return None
-        n = int(value.literal)
-    else:
-        n = _as_int(value)
+    n = _raw_as_int(value)
     if n is not None and -9_223_372_036_854_775_808 <= n <= 9_223_372_036_854_775_807:
         return n
     return None
@@ -1449,37 +1663,46 @@ def _signed_magnitude(value: int) -> tuple[str, int]:
 
 
 def _as_decimal_int(value: Any) -> int | None:
-    if isinstance(value, str) and re.fullmatch(r"-?\d+", value):
-        return int(value)
-    return _as_int(value)
+    text = _decimal_int_text(value)
+    return int(text) if text is not None else None
 
 
 def _decimal_int_text(value: Any) -> str | None:
-    if isinstance(value, str) and re.fullmatch(r"-?\d+", value):
-        return value
-    n = _as_int(value)
-    if n is None:
+    """The exact digits of an integer-valued number or decimal integer string,
+    of any magnitude. Bitcoin amounts and ``_epoch_ns`` only append a unit or
+    divide, so unlike money suffixes they are not bounded by i64: an integer
+    literal keeps its digits, and a float counts when its value is an integer
+    below 1e21 (the canonical number form's integer range). A numeric ``-0``
+    is zero."""
+    if isinstance(value, str):
+        return value if re.fullmatch(r"-?[0-9]+", value) else None
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            return None
+        literal = repr(value)
+    elif isinstance(value, _RawNumber):
+        literal = value.literal
+    else:
+        return None
+    integer = _integral_float_text(literal) if re.search(r"[.eE]", literal) else literal
+    if integer is None:
         return None
-    return str(n)
+    return "0" if integer == "-0" else integer
 
 
 def _try_process_field(key: str, value: Any) -> tuple[str, str] | None:
     """Try suffix-driven processing. Returns (stripped_key, formatted_value) or None."""
-    # Plain-format suffix arithmetic below only works on a native int/float. A
-    # decoded _RawNumber (see decode_protocol_event's fidelity note) is
-    # normalized to a float here for that arithmetic, so an ordinary decoded
-    # value (e.g. cpu_percent: 85.5) keeps formatting exactly as before; this
-    # is Plain's documented lossy/human path. The _epoch_ns/_msats/_sats
-    # branches below keep exactness by reading `value` directly instead of
-    # `numeric` (their _as_decimal_int/_decimal_int_text helpers already
-    # handle plain arbitrary-precision int values, which is what every
-    # decoded integer literal already is -- only floats get wrapped).
-    numeric: Any = float(value.literal) if isinstance(value, _RawNumber) else value
+    # Adding a unit does no arithmetic, so it must not round decoded digits.
+    is_number = _is_number(value) or isinstance(value, _RawNumber)
 
     # Group 1: compound timestamp suffixes
     stripped = _strip_suffix_ci(key, "_epoch_ms")
     if stripped is not None:
-        n = _as_int(numeric)
+        n = _as_i64(value)
         if n is not None:
             formatted = _format_rfc3339_ms(n)
             if formatted is not None:
@@ -1487,7 +1710,7 @@ def _try_process_field(key: str, value: Any) -> tuple[str, str] | None:
         return None
     stripped = _strip_suffix_ci(key, "_epoch_s")
     if stripped is not None:
-        n = _as_int(numeric)
+        n = _as_i64(value)
         if n is not None:
             formatted = _format_rfc3339_ms(n * 1000)
             if formatted is not None:
@@ -1548,18 +1771,18 @@ def _try_process_field(key: str, value: Any) -> tuple[str, str] | None:
         return None
     stripped = _strip_suffix_ci(key, "_minutes")
     if stripped is not None:
-        if _is_number(numeric):
-            return stripped, f"{_plain_scalar(numeric)} minutes"
+        if is_number:
+            return stripped, f"{_plain_scalar(value)} minutes"
         return None
     stripped = _strip_suffix_ci(key, "_hours")
     if stripped is not None:
-        if _is_number(numeric):
-            return stripped, f"{_plain_scalar(numeric)} hours"
+        if is_number:
+            return stripped, f"{_plain_scalar(value)} hours"
         return None
     stripped = _strip_suffix_ci(key, "_days")
     if stripped is not None:
-        if _is_number(numeric):
-            return stripped, f"{_plain_scalar(numeric)} days"
+        if is_number:
+            return stripped, f"{_plain_scalar(value)} days"
         return None
 
     # Group 4: single-unit suffixes
@@ -1577,14 +1800,14 @@ def _try_process_field(key: str, value: Any) -> tuple[str, str] | None:
         return None
     stripped = _strip_suffix_ci(key, "_bytes")
     if stripped is not None:
-        n = _as_non_neg_int(numeric)
+        n = _as_u64(value)
         if n is not None:
             return stripped, _format_bytes_human(n)
         return None
     stripped = _strip_suffix_ci(key, "_percent")
     if stripped is not None:
-        if _is_number(numeric):
-            return stripped, f"{_plain_scalar(numeric)}%"
+        if is_number:
+            return stripped, f"{_plain_scalar(value)}%"
         return None
     # Group 5: short suffixes (last to avoid false positives)
     stripped = _strip_suffix_ci(key, "_jpy")
@@ -1596,24 +1819,24 @@ def _try_process_field(key: str, value: Any) -> tuple[str, str] | None:
         return None
     stripped = _strip_suffix_ci(key, "_ns")
     if stripped is not None:
-        if _is_number(numeric):
-            return stripped, f"{_plain_scalar(numeric)}ns"
+        if is_number:
+            return stripped, f"{_plain_scalar(value)}ns"
         return None
     stripped = _strip_suffix_ci(key, "_us")
     if stripped is not None:
-        if _is_number(numeric):
-            return stripped, f"{_plain_scalar(numeric)}\u03bcs"
+        if is_number:
+            return stripped, f"{_plain_scalar(value)}\u03bcs"
         return None
     stripped = _strip_suffix_ci(key, "_ms")
     if stripped is not None:
-        fv = _format_ms_value(numeric)
+        fv = _format_ms_value(value)
         if fv is not None:
             return stripped, fv
         return None
     stripped = _strip_suffix_ci(key, "_s")
     if stripped is not None:
-        if _is_number(numeric):
-            return stripped, f"{_plain_scalar(numeric)}s"
+        if is_number:
+            return stripped, f"{_plain_scalar(value)}s"
         return None
 
     return None
@@ -1685,9 +1908,11 @@ def _format_ms_as_seconds(ms: float) -> str:
 
 def _format_ms_value(value: Any) -> str | None:
     """Format _ms value: < 1000 -> {n}ms, >= 1000 -> seconds."""
-    if not _is_number(value):
+    if not _is_number(value) and not isinstance(value, _RawNumber):
+        return None
+    n = float(value.literal) if isinstance(value, _RawNumber) else float(value)
+    if not math.isfinite(n):
         return None
-    n = float(value)
     if abs(n) >= 1000:
         return _format_ms_as_seconds(n)
     return f"{_plain_scalar(value)}ms"
@@ -1698,7 +1923,12 @@ def _format_rfc3339_ms(ms: int) -> str | None:
         return None
     try:
         dt = datetime(1970, 1, 1, tzinfo=timezone.utc) + timedelta(milliseconds=ms)
-        return dt.strftime("%Y-%m-%dT%H:%M:%S.") + f"{ms % 1000:03d}Z"
+        # Not strftime: glibc's `%Y` does not pad a year below 1000, so year 1
+        # printed as `1-01-01` on Linux while macOS printed `0001-01-01`.
+        return (
+            f"{dt.year:04d}-{dt.month:02d}-{dt.day:02d}T"
+            f"{dt.hour:02d}:{dt.minute:02d}:{dt.second:02d}.{ms % 1000:03d}Z"
+        )
     except (OverflowError, ValueError):
         return None
 
@@ -1858,11 +2088,11 @@ def _yaml_scalar(value: Any) -> str:
     if isinstance(value, (int, float)):
         return _number_str(value)
     if isinstance(value, _RawNumber):
-        # Decoded number: emit the exact source literal unquoted, matching
-        # JSON's structure-preserving fidelity contract for YAML too.
-        return value.literal
+        # Decoded number: its exact digits, in the same canonical form a
+        # native number gets.
+        return _number_literal_str(value.literal)
     if isinstance(value, (dict, list)):
-        return f'"{_escape_yaml_str(_canonical_json(value))}"'
+        return f'"{_escape_yaml_str(_embedded_json(value))}"'
     return f'"{_escape_yaml_str(str(value))}"'
 
 
@@ -1928,18 +2158,18 @@ def _plain_scalar(value: Any) -> str:
     if isinstance(value, (int, float)):
         return _number_str(value)
     if isinstance(value, _RawNumber):
-        # Decoded number: emit the exact source literal (Plain is documented
-        # lossy for arithmetic-derived formatting, but a bare pass-through
-        # scalar still gets its exact digits, not a float64 round-trip).
-        return value.literal
+        # Decoded number: its exact digits (Plain is documented lossy only
+        # for arithmetic-derived formatting), in the same canonical form a
+        # native number gets.
+        return _number_literal_str(value.literal)
     if isinstance(value, (dict, list)):
-        return _canonical_json(value)
+        return _embedded_json(value)
     return str(value)
 
 
 def _plain_scalar_raw(value: Any) -> str:
     if isinstance(value, (dict, list)):
-        return _canonical_json(value)
+        return _embedded_json(value)
     return _plain_scalar(value)
 
 
@@ -1975,13 +2205,21 @@ def _utf16_sort_key(s: str) -> bytes:
     return s.encode("utf-16-be", "surrogatepass")
 
 
-def _canonical_json(value: Any) -> str:
-    return _encode_json_lossless(_sort_json_value(value))
-
-
-def _sort_json_value(value: Any) -> Any:
+def _embedded_json(value: Any) -> str:
+    """A container nested inside a Plain array (or in a YAML scalar position)
+    is written as compact JSON with sorted keys. Its number leaves take the
+    canonical number form, the same text the value prints as a scalar, so a
+    nested ``1.0`` reads ``1`` and a decoded ``1e5`` reads ``100000`` in every
+    SDK rather than in each runtime's own JSON spelling."""
     if isinstance(value, dict):
-        return {k: _sort_json_value(value[k]) for k in _sorted_object_keys(value)}
+        return "{" + ",".join(
+            f"{json.dumps(k, ensure_ascii=False)}:{_embedded_json(value[k])}"
+            for k in _sorted_object_keys(value)
+        ) + "}"
     if isinstance(value, list):
-        return [_sort_json_value(item) for item in value]
-    return value
+        return "[" + ",".join(_embedded_json(item) for item in value) + "]"
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False)
+    if value is None or isinstance(value, (bool, int, float, _RawNumber)):
+        return _plain_scalar(value)
+    return json.dumps(str(value), ensure_ascii=False)

{agent_first_data-0.35.0 → agent_first_data-0.36.0}/agent_first_data.egg-info/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: agent-first-data
-Version: 0.35.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 Markdown structure and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.
+Version: 0.36.0
+Summary: A naming convention that lets AI agents understand your data without being told what it means, plus the afdata CLI and a Rust library for reading Markdown structure and safely editing structured JSON, TOML, YAML, dotenv, and INI documents.
 License-Expression: MIT
 Project-URL: Repository, https://github.com/agentfirstkit/agent-first-data
 Requires-Python: >=3.9
@@ -28,10 +28,12 @@ print(render(value, OutputFormat.JSON))
 print(render(value, OutputFormat.PLAIN))
 ```
 
-Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_urls_in_text`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `decode_protocol_event`.
+Useful names use Python casing: `render` (the single value x format x options -> str entry point; takes an `OutputFormat` and an optional keyword-only `options=`), `redacted_value`, `redact_url_secrets`, `redact_urls_in_text`, `redact_argv`, `normalize_utc_offset`, `is_valid_rfc3339_date`, `is_valid_rfc3339_time`, `is_valid_rfc3339`, `is_valid_bcp47`, `cli_parse_output`, `build_cli_error`, `build_cli_version`, `cli_parse_log_filters`, `CliEmitter`, `decode_protocol_event`.
 
 ## Behavior Notes
 
+- `OutputOptions(reveal_names=...)` reveals exact structured field names at the selected output boundary. Children still pass through redaction; URL parameters and argv receive no exemption.
+- The protocol reader accepts base-profile events. An absent `error.retryable` remains nullable; strict validation is a separate opt-in.
 - Default redaction replaces every `_secret` or configured secret-name subtree with `***`, including objects and arrays.
 - `_url` fields scrub userinfo passwords and secret-named query parameters; surrounding whitespace is trimmed, and internal whitespace or a `://` that is not the start of a clean URL redacts the whole field, where whitespace is the explicit Unicode `White_Space` set the spec enumerates, not the language's native predicate.
 - `OutputOptions.url_names` applies URL treatment to exact legacy field names
@@ -40,7 +42,7 @@ Useful names use Python casing: `render` (the single value x format x options ->
 - YAML keeps original keys and values (structure-preserving, like JSON), sorting keys by UTF-16 code unit order and quoting/escaping unsafe keys and string scalars. Plain strips formatting suffixes, formats values, sorts the same way, and renders nested objects/arrays as canonical JSON; it quotes a value only when it contains ASCII space, tab, newline, carriage return, form feed, vertical tab, NBSP, `=`, `"`, or `\`, and escapes `\`, `"`, newline, carriage return, tab, form feed, and vertical tab inside the quotes.
 - Logging records use `kind:"log"` with a nested `log` payload and a separate `level` field, so error-level logs are not terminal protocol errors.
 - `build_cli_error(message, hint?)` returns a strict-ready CLI error with `error.retryable:false` and `trace:{}`.
-- Do not add a raw version/help pre-parser. Until the Python `CliSpec` compiler lands, applications should keep lifecycle parsing in their own parser rather than claim AFDATA closed-world help compatibility.
+- Do not add a raw version/help pre-parser. This SDK provides emitters and readers; argv and lifecycle parsing belong to the application. Claim help-v2 or closed-world compatibility only when using a registry compiler.
 
 ## Reference
 

{agent_first_data-0.35.0 → agent_first_data-0.36.0}/pyproject.toml

@@ -1,7 +1,7 @@
 [project]
 name = "agent-first-data"
-version = "0.35.0"
-description = "A naming convention that lets AI agents understand your data without being told what it means, plus a CLI and library for reading Markdown structure and safely editing structured JSON, TOML, YAML, dotenv, and INI documents."
+version = "0.36.0"
+description = "A naming convention that lets AI agents understand your data without being told what it means, plus the afdata CLI and a Rust library for reading Markdown structure and safely editing structured JSON, TOML, YAML, dotenv, and INI documents."
 license = "MIT"
 readme = "README.md"
 requires-python = ">=3.9"

{agent_first_data-0.35.0 → agent_first_data-0.36.0}/tests/test_cli.py

@@ -448,9 +448,39 @@ def test_finish_returns_0_on_broken_pipe():
     assert emitter.finish(json_result({"rows": 1}).build(), 0) == 0
 
 
-def test_finish_returns_4_on_other_write_failure():
+def _assert_output_write_failed(text: str) -> None:
+    reported = json.loads(text)
+    assert reported["kind"] == "error"
+    assert reported["error"]["code"] == "output_write_failed"
+
+
+def test_finish_returns_4_on_other_write_failure(monkeypatch):
+    # Event-stream mode reports the failure on the process's stderr.
+    err = StringIO()
+    monkeypatch.setattr("sys.stderr", err)
     emitter = CliEmitter.stream(_FailingWriter(), OutputFormat.JSON)
     assert emitter.finish(json_result({"rows": 1}).build(), 0) == 4
+    _assert_output_write_failed(err.getvalue())
+
+
+def test_finish_reports_an_unwritable_result_on_the_diagnostic_sink():
+    diagnostic = StringIO()
+    emitter = CliEmitter.finite_with(_FailingWriter(), diagnostic, OutputFormat.JSON)
+    assert emitter.finish_result({"rows": 2}) == 4
+    _assert_output_write_failed(diagnostic.getvalue())
+
+    # A closed reader stays silent success.
+    diagnostic = StringIO()
+    emitter = CliEmitter.finite_with(_BrokenPipeWriter(), diagnostic, OutputFormat.JSON)
+    assert emitter.finish_result({}) == 0
+    assert diagnostic.getvalue() == ""
+
+
+def test_finish_returns_1_on_a_protocol_violation():
+    buf = StringIO()
+    emitter = CliEmitter.stream(buf, OutputFormat.JSON).with_strict_protocol()
+    assert emitter.finish({"kind": "error", "error": {"code": "failed", "message": "Failed"}}, 2) == 1
+    assert buf.getvalue() == ""
 
 
 def test_finish_result_returns_0_on_broken_pipe():
@@ -458,12 +488,13 @@ def test_finish_result_returns_0_on_broken_pipe():
     assert emitter.finish_result({"ok": True}) == 0
 
 
-def test_finish_returns_4_on_lifecycle_violation():
-    # A non-BrokenPipe failure (here a duplicate terminal) resolves to 4.
+def test_finish_returns_1_on_lifecycle_violation():
+    # An event the emitter refuses (here a second terminal event) is the
+    # command's failure, not output's.
     buf = StringIO()
     emitter = CliEmitter.stream(buf, OutputFormat.JSON)
     assert emitter.finish(json_result({"rows": 1}).build(), 0) == 0
-    assert emitter.finish(json_error("late", "too late").build(), 1) == 4
+    assert emitter.finish(json_error("late", "too late").build(), 2) == 1
 
 
 # ── version helpers ───────────────────────────────────────────────────────────

{agent_first_data-0.35.0 → agent_first_data-0.36.0}/tests/test_format.py

@@ -89,6 +89,7 @@ def _redaction_options(case):
     return OutputOptions(
         policy=policy,
         secret_names=opts.get("secret_names", ()),
+        reveal_names=opts.get("reveal_names", ()),
         url_names=opts.get("url_names", ()),
     )
 
@@ -99,7 +100,8 @@ def _redaction_options(case):
 def test_redact_fixtures():
     for case in _load("redact.json"):
         name = case["name"]
-        got = redacted_value(case["input"])
+        options = _redaction_options(case)
+        got = redacted_value(case["input"], secret_names=options.secret_names, url_names=options.url_names, reveal_names=options.reveal_names, policy=options.policy)
         assert got == case["expected"], f"[redact/{name}] got {got!r}"
 
 
@@ -131,6 +133,13 @@ def test_redact_argv_fixtures():
     for case in _load("redact_argv.json"):
         name = case["name"]
         options = _redaction_options(case)
+        if case.get("requires") == "redactor_reveal_names":
+            # Python's redact_argv has no reveal option, so a reveal list
+            # cannot reach argv at all: assert the parameter is refused.
+            with pytest.raises(TypeError):
+                redact_argv(case["input"], reveal_names=options.reveal_names)  # type: ignore[call-arg]
+            continue
+        assert not options.reveal_names, f"[redact_argv/{name}] reveal_names needs requires"
         got = redact_argv(
             case["input"],
             secret_names=options.secret_names,
@@ -154,6 +163,7 @@ def test_redaction_options_fixtures():
             case["input"],
             secret_names=output_options.secret_names,
             url_names=output_options.url_names,
+            reveal_names=output_options.reveal_names,
             policy=output_options.policy,
         )
         assert got == expected, f"[redaction_options/{name}] value mismatch: {got}"
@@ -178,6 +188,7 @@ def test_security_fixtures():
             case["input"],
             secret_names=output_options.secret_names,
             url_names=output_options.url_names,
+            reveal_names=output_options.reveal_names,
             policy=output_options.policy,
         ) == case["expected"]
         outputs = (
@@ -534,13 +545,24 @@ def test_helper_fixtures():
                 assert got == expected, f"[helpers/{name}({inp!r})] got {got!r}"
 
 
+def test_native_negative_zero_keeps_its_sign_in_yaml_and_plain():
+    # int(-0.0) == 0, so rendering through int dropped the sign; the shared
+    # fixtures only reach decoded literals, which never went through int.
+    value = {"neg_zero": -0.0, "wait_s": -0.0}
+    assert render(value, OutputFormat.YAML) == "---\nneg_zero: -0\nwait_s: -0"
+    assert render(value, OutputFormat.PLAIN) == "neg_zero=-0 wait=-0s"
+
+
 def test_output_format_fixtures():
     for case in _load("output_formats.json"):
         name = case["name"]
         inp = json.loads(json.dumps(case["input"]))
 
-        got_json = json.loads(render(inp, OutputFormat.JSON))
+        json_text = render(inp, OutputFormat.JSON)
+        got_json = json.loads(json_text)
         assert got_json == case["expected_json"], f"[output/{name}] json mismatch: {got_json}"
+        if "expected_json_text" in case:
+            assert json_text == case["expected_json_text"], f"[output/{name}] json text mismatch: {json_text!r}"
 
         got_yaml = render(inp, OutputFormat.YAML)
         assert got_yaml == case["expected_yaml"], f"[output/{name}] yaml mismatch: {got_yaml!r}"
@@ -745,12 +767,10 @@ def test_decode_protocol_event_invalid_envelope_raises():
         decode_protocol_event(json.dumps({"kind": "result"}))
 
 
-def test_decode_protocol_event_fails_strict_validation():
-    import pytest
-
-    # Missing trace fails the strict profile even though the shape is otherwise valid.
-    with pytest.raises(EventDecodeError):
-        decode_protocol_event(json.dumps({"kind": "result", "result": {}}))
+def test_decode_protocol_event_accepts_base_profile():
+    decoded = decode_protocol_event('{"kind":"error","error":{"code":"failed","message":"Failed"}}')
+    assert decoded.retryable is None
+    assert decoded.trace is None
 
 
 # --- Number literal fidelity (shared spec/fixtures/number_fidelity.json) ---
@@ -779,14 +799,33 @@ def test_number_fidelity_fixtures():
             assert got_plain == case["expected_plain"], f"[number_fidelity/{name}] plain mismatch: {got_plain!r}"
 
 
+def test_decoded_numbers_beyond_python_conversion_limits_still_render():
+    # Python 3.11+ limits int(string) conversions by default; that limit must
+    # not turn a valid protocol number into a decode or rendering exception.
+    integer = "9" * 5000
+    exponent = "1e+" + "9" * 5000
+    for literal in (integer, exponent):
+        decoded = decode_protocol_event('{"kind":"result","result":' + literal + ',"trace":{}}')
+        assert render(decoded.result, OutputFormat.JSON) == literal
+        assert render(decoded.result, OutputFormat.YAML) == "---\n" + literal
+        assert render(decoded.result, OutputFormat.PLAIN) == literal
+    decoded = decode_protocol_event('{"kind":"result","result":{"cost_jpy":' + integer + '},"trace":{}}')
+    assert render(decoded.result, OutputFormat.PLAIN) == "cost_jpy=" + integer
+
+
 def test_protocol_decode_fixtures():
     for case in _load("protocol_decode.json"):
+        decoded = None
         try:
-            decode_protocol_event(case["input_line"])
+            decoded = decode_protocol_event(case["input_line"])
             valid = True
         except EventDecodeError:
             valid = False
         assert valid is case["valid"], f"[protocol_decode/{case['name']}]"
+        if "expected_result_json" in case:
+            assert isinstance(decoded, DecodedResult), f"[protocol_decode/{case['name']}]"
+            got = render(decoded.result, OutputFormat.JSON)
+            assert got == case["expected_result_json"], f"[protocol_decode/{case['name']}] got {got!r}"
 
 
 def test_number_fidelity_does_not_regress_ordinary_decoded_numbers_in_plain_output():
@@ -807,3 +846,9 @@ def test_signed_fiat_i64_min_formats_without_overflow():
         OutputFormat.PLAIN,
     )
     assert plain == "adjustment=-$92233720368547758.08"
+
+
+def test_output_options_preserve_existing_positional_arguments():
+    options = OutputOptions((), ("legacy",), None, PlainStyle.Raw)
+    rendered = json.loads(render({"legacy": "https://example.test/?token_secret=hidden"}, OutputFormat.JSON, options=options))
+    assert rendered == {"legacy": "https://example.test/?token_secret=***"}