agent-first-data 0.35.1 → 0.36.0

package/README.md

@@ -17,10 +17,12 @@ console.log(render(event.toJSON(), "json"));
 console.log(render(event.toJSON(), "plain"));
 ```
 
-Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `redactUrlsInText`, `redactArgv`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `buildCliError`, and `buildCliVersion`.
+Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `redactUrlsInText`, `redactArgv`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `isValidRfc3339`, `isValidBcp47`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `buildCliError`, `buildCliVersion`, and `CliEmitter`.
 
 ## Behavior Notes
 
+- `OutputOptions.redaction.revealNames` 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.redaction.urlNames` applies URL treatment to exact legacy field names
@@ -29,7 +31,7 @@ Useful names use TypeScript casing: `render`, `outputOptionsForPolicy`, `redacte
 - 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.
 - `buildCliError(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 TypeScript `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
 

package/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"

package/dist/cli.d.ts

@@ -108,6 +108,9 @@ export declare class CliEmitter {
     private terminalEmitted;
     private diagnostic?;
     private strictProtocol;
+    private writeFailed;
+    /** Where an event-stream emitter reports a failed write; tests replace it. */
+    private processStderr;
     /**
      * Create an event-stream emitter: every event, including `error`, goes to the
      * single `writer`. Use CliEmitter.finite for a one-shot command that should
@@ -154,10 +157,17 @@ export declare class CliEmitter {
      * exit code, so a one-shot CLI need not hand-roll the emit-then-exit dance.
      *
      * A successful write returns `successCode`; a broken pipe (the reader hung up)
-     * returns `0`; any other write or validation failure returns `4`. A library
-     * never calls process.exit itself — return this code and let the caller exit.
+     * returns `0` and says nothing. Any other write failure returns `4` after
+     * reporting `output_write_failed` as an `error` event: on the diagnostic
+     * writer in finite mode, on the process's 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 process.exit itself — return this code and let the
+     * caller exit.
      */
     finish(event: Event, successCode: number): number;
+    private reportOutputWriteFailed;
     /**
      * Convenience over finish: emit a `result` payload and return `0` on success.
      *

package/dist/cli.js

@@ -156,6 +156,9 @@ export class CliEmitter {
     terminalEmitted = false;
     diagnostic;
     strictProtocol = false;
+    writeFailed = false;
+    /** Where an event-stream emitter reports a failed write; tests replace it. */
+    processStderr = processStderrWriter;
     /**
      * Create an event-stream emitter: every event, including `error`, goes to the
      * single `writer`. Use CliEmitter.finite for a one-shot command that should
@@ -217,6 +220,7 @@ export class CliEmitter {
         return this;
     }
     emit(event) {
+        this.writeFailed = false;
         const jsonValue = event.toJSON();
         validateProtocolEvent(jsonValue, this.strictProtocol);
         const kind = jsonValue.kind;
@@ -233,7 +237,15 @@ export class CliEmitter {
         else {
             throw new Error(`unsupported event kind ${JSON.stringify(kind)}`);
         }
-        this.sinkFor(kind)(`${render(jsonValue, this.format, this.outputOptions)}\n`);
+        const line = `${render(jsonValue, this.format, this.outputOptions)}\n`;
+        try {
+            this.sinkFor(kind)(line);
+        }
+        catch (err) {
+            // Marks the failure as output's, not the event's, for finish().
+            this.writeFailed = true;
+            throw err;
+        }
         if (kind === "result" || kind === "error")
             this.terminalEmitted = true;
     }
@@ -265,8 +277,14 @@ export class CliEmitter {
      * exit code, so a one-shot CLI need not hand-roll the emit-then-exit dance.
      *
      * A successful write returns `successCode`; a broken pipe (the reader hung up)
-     * returns `0`; any other write or validation failure returns `4`. A library
-     * never calls process.exit itself — return this code and let the caller exit.
+     * returns `0` and says nothing. Any other write failure returns `4` after
+     * reporting `output_write_failed` as an `error` event: on the diagnostic
+     * writer in finite mode, on the process's 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 process.exit itself — return this code and let the
+     * caller exit.
      */
     finish(event, successCode) {
         try {
@@ -274,7 +292,28 @@ export class CliEmitter {
             return successCode;
         }
         catch (err) {
-            return CliEmitter.isBrokenPipe(err) ? 0 : 4;
+            if (CliEmitter.isBrokenPipe(err))
+                return 0;
+            if (!this.writeFailed)
+                return 1;
+            this.reportOutputWriteFailed();
+            return 4;
+        }
+    }
+    reportOutputWriteFailed() {
+        try {
+            const event = jsonError("output_write_failed", "could not write command output").build();
+            if (this.diagnostic) {
+                this.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(this.processStderr, this.format).withStrictProtocol().emit(event);
+            }
+        }
+        catch {
+            // Best effort: an unwritable stderr leaves only the exit code.
         }
     }
     /**

package/dist/format.d.ts

@@ -10,9 +10,10 @@
  * Number literal fidelity: decodeProtocolEvent parses with `lossless-json`
  * instead of JSON.parse, so a number's exact source literal (arbitrary
  * precision integers, high-precision floats, exponent forms, "-0") survives
- * decode. Parsed numbers become LosslessNumber internally; every JSON/YAML
- * rendering path here treats it as an opaque scalar leaf (never destructured
- * as a plain object) and re-emits its exact literal text. Native bigint values
+ * decode. Parsed numbers become LosslessNumber internally; every rendering
+ * path here treats it as an opaque scalar leaf (never destructured as a plain
+ * object). JSON re-emits its exact literal text; YAML/plain render it in the
+ * spec's canonical number form without losing a digit. Native bigint values
  * are also supported so callers can render integers beyond Number's safe
  * range without first corrupting them.
  */
@@ -22,7 +23,8 @@ export type JsonValue = string | number | bigint | boolean | null | JsonValue[]
 export type LogLevel = "debug" | "info" | "warn" | "error";
 /**
  * Event is an opaque type wrapping a protocol event envelope.
- * Guaranteed to be strict-valid by construction.
+ * Non-error builders retain caller-provided traces verbatim; validate the
+ * envelope before accepting externally supplied traces as protocol-valid.
  */
 export declare class Event {
     private readonly value;
@@ -100,7 +102,7 @@ export type DecodedError = {
     kind: "error";
     code: string;
     message: string;
-    retryable: boolean;
+    retryable: boolean | null;
     hint?: string;
     fields: Record<string, JsonValue>;
     trace?: Record<string, JsonValue>;
@@ -117,12 +119,12 @@ export type DecodedLog = {
 };
 /** Discriminated union of decoded protocol events, narrow on `kind`. */
 export type DecodedEvent = DecodedResult | DecodedError | DecodedProgress | DecodedLog;
-/** Thrown by decodeProtocolEvent for malformed JSON or a strict-invalid event. */
+/** Thrown by decodeProtocolEvent for malformed JSON or a base-invalid event. */
 export declare class EventDecodeError extends Error {
     constructor(message: string);
 }
 /**
- * Parse one protocol line (a single JSON text value), strict-validate it, and
+ * Parse one protocol line (a single JSON text value), base-validate it, and
  * return a typed decoded event.
  */
 export declare function decodeProtocolEvent(text: string): DecodedEvent;
@@ -158,6 +160,8 @@ export type OutputOptions = {
          * redaction in addition to _url/_URL fields.
          */
         urlNames?: readonly string[];
+        /** Exact structured field names to reveal; URL parameters and argv stay redacted. */
+        revealNames?: readonly string[];
     };
     /** Rendering style for plain (logfmt) output only. Omitted means readable.
      * JSON and YAML are structure-preserving and ignore this setting. */
@@ -191,6 +195,8 @@ export declare function redactedValue(value: unknown, options?: {
     policy?: RedactionPolicy;
     secretNames?: readonly string[];
     urlNames?: readonly string[];
+    /** Exact structured field names to reveal; URL parameters and argv stay redacted. */
+    revealNames?: readonly string[];
 }): JsonValue;
 /**
  * Redact secret components of a single URL string.

package/dist/format.js

@@ -10,9 +10,10 @@
  * Number literal fidelity: decodeProtocolEvent parses with `lossless-json`
  * instead of JSON.parse, so a number's exact source literal (arbitrary
  * precision integers, high-precision floats, exponent forms, "-0") survives
- * decode. Parsed numbers become LosslessNumber internally; every JSON/YAML
- * rendering path here treats it as an opaque scalar leaf (never destructured
- * as a plain object) and re-emits its exact literal text. Native bigint values
+ * decode. Parsed numbers become LosslessNumber internally; every rendering
+ * path here treats it as an opaque scalar leaf (never destructured as a plain
+ * object). JSON re-emits its exact literal text; YAML/plain render it in the
+ * spec's canonical number form without losing a digit. Native bigint values
  * are also supported so callers can render integers beyond Number's safe
  * range without first corrupting them.
  */
@@ -22,7 +23,8 @@ import { parse as losslessParse, stringify as losslessStringify, isLosslessNumbe
 // ═══════════════════════════════════════════
 /**
  * Event is an opaque type wrapping a protocol event envelope.
- * Guaranteed to be strict-valid by construction.
+ * Non-error builders retain caller-provided traces verbatim; validate the
+ * envelope before accepting externally supplied traces as protocol-valid.
  */
 export class Event {
     value;
@@ -113,7 +115,7 @@ export class JsonErrorBuilder {
             this.issues.push(`cannot write reserved error field ${JSON.stringify(name)}`);
         }
         else {
-            this.extensionFields[name] = value;
+            setJsonField(this.extensionFields, name, value);
         }
         return this;
     }
@@ -127,7 +129,7 @@ export class JsonErrorBuilder {
                 this.issues.push(`cannot write reserved error field ${JSON.stringify(key)}`);
             }
             else {
-                this.extensionFields[key] = val;
+                setJsonField(this.extensionFields, key, val);
             }
         }
         return this;
@@ -142,7 +144,7 @@ export class JsonErrorBuilder {
                 this.issues.push(`cannot write reserved error field ${JSON.stringify(key)}`);
             }
             else {
-                this.extensionFields[key] = val;
+                setJsonField(this.extensionFields, key, val);
             }
         }
         return this;
@@ -277,6 +279,9 @@ function validateErrorPayload(error) {
     if ("hint" in error && typeof error.hint !== "string") {
         throw new Error("event.error.hint must be a string when present");
     }
+    if ("retryable" in error && typeof error.retryable !== "boolean") {
+        throw new Error("event.error.retryable must be a boolean when present");
+    }
 }
 /** Validate finite CLI lifecycle: (log | progress)* -> exactly one terminal. `strict` also enforces the recommended strict protocol profile (default true). */
 export function validateProtocolStream(events, strict = true) {
@@ -319,7 +324,7 @@ function validateStrictError(error) {
         throw new Error("event.error.hint must be a string when present in strict mode");
     }
 }
-/** Thrown by decodeProtocolEvent for malformed JSON or a strict-invalid event. */
+/** Thrown by decodeProtocolEvent for malformed JSON or a base-invalid event. */
 export class EventDecodeError extends Error {
     constructor(message) {
         super(message);
@@ -327,8 +332,70 @@ export class EventDecodeError extends Error {
     }
 }
 const ERROR_RESERVED_FIELDS = new Set(["code", "message", "hint", "retryable"]);
+/** How many arrays and objects a protocol line may nest, counting the envelope object. Every SDK enforces the same bound. */
+const MAX_PROTOCOL_NESTING = 127;
+function hexEscape(text, at) {
+    if (text.charCodeAt(at) !== 0x5c || text.charCodeAt(at + 1) !== 0x75)
+        return null;
+    const digits = text.slice(at + 2, at + 6);
+    return /^[0-9a-fA-F]{4}$/.test(digits) ? parseInt(digits, 16) : null;
+}
+/**
+ * The decode rules lossless-json does not enforce: a nesting bound, and no
+ * lone UTF-16 surrogate, escaped or raw (lossless-json keeps one in the
+ * string). Only strings and escapes are tracked; the rest of the grammar is
+ * left to the parser.
+ */
+function checkProtocolLine(text) {
+    let depth = 0;
+    let inString = false;
+    for (let i = 0; i < text.length; i++) {
+        const c = text.charCodeAt(i);
+        if (inString) {
+            if (c === 0x22) {
+                inString = false;
+            }
+            else if (c === 0x5c) {
+                const unit = hexEscape(text, i);
+                if (unit !== null && unit >= 0xd800 && unit <= 0xdbff) {
+                    const low = hexEscape(text, i + 6);
+                    if (low === null || low < 0xdc00 || low > 0xdfff) {
+                        throw new SyntaxError(`lone surrogate escape at position ${i}`);
+                    }
+                    i += 11;
+                }
+                else if (unit !== null && unit >= 0xdc00 && unit <= 0xdfff) {
+                    throw new SyntaxError(`lone surrogate escape at position ${i}`);
+                }
+                else {
+                    i++;
+                }
+            }
+            else if (c >= 0xd800 && c <= 0xdbff) {
+                const next = text.charCodeAt(i + 1);
+                if (!(next >= 0xdc00 && next <= 0xdfff))
+                    throw new SyntaxError(`lone surrogate at position ${i}`);
+                i++;
+            }
+            else if (c >= 0xdc00 && c <= 0xdfff) {
+                throw new SyntaxError(`lone surrogate at position ${i}`);
+            }
+        }
+        else if (c === 0x22) {
+            inString = true;
+        }
+        else if (c === 0x5b || c === 0x7b) {
+            depth++;
+            if (depth > MAX_PROTOCOL_NESTING)
+                throw new SyntaxError(`nesting deeper than ${MAX_PROTOCOL_NESTING}`);
+        }
+        else if (c === 0x5d || c === 0x7d) {
+            depth--;
+        }
+    }
+}
 /**
- * Parse one protocol line (a single JSON text value), strict-validate it, and
+ * Parse one protocol line (a single JSON text value), base-validate it, and
  * return a typed decoded event.
  */
 export function decodeProtocolEvent(text) {
@@ -338,13 +405,16 @@ export function decodeProtocolEvent(text) {
         // source literal (see module-level fidelity note) instead of collapsing
         // it through float64. isSyntaxError-compatible: throws the same
         // SyntaxError shape JSON.parse would.
-        parsed = losslessParse(text);
+        checkProtocolLine(text);
+        // A repeated key keeps its last value, as JSON.parse and every other
+        // SDK's decoder do; lossless-json would otherwise throw.
+        parsed = losslessParse(text, null, { onDuplicateKey: ({ newValue }) => newValue });
     }
     catch (e) {
         throw new EventDecodeError(`invalid JSON: ${e.message}`);
     }
     try {
-        validateProtocolEvent(parsed, true);
+        validateProtocolEvent(parsed, false);
     }
     catch (e) {
         throw new EventDecodeError(e.message);
@@ -359,13 +429,13 @@ export function decodeProtocolEvent(text) {
             const fields = {};
             for (const [k, v] of Object.entries(error)) {
                 if (!ERROR_RESERVED_FIELDS.has(k))
-                    fields[k] = v;
+                    setJsonField(fields, k, v);
             }
             const decoded = {
                 kind: "error",
                 code: error.code,
                 message: error.message,
-                retryable: error.retryable,
+                retryable: typeof error.retryable === "boolean" ? error.retryable : null,
                 fields,
                 trace,
             };
@@ -443,8 +513,12 @@ export function formatJsonValue(value, options = {}) {
  * and formatting for everything else.
  */
 function canonicalJsonString(value) {
-    return losslessStringify(value) ?? "null";
+    return losslessStringify(value, null, undefined, NUMBER_STRINGIFIERS) ?? "null";
 }
+// JSON.stringify spells negative zero "0"; the other SDKs keep its sign.
+const NUMBER_STRINGIFIERS = [
+    { test: (value) => Object.is(value, -0), stringify: () => "-0" },
+];
 /**
  * Format as multi-line YAML. Structure-preserving: like JSON, original keys,
  * scalar types, and numeric semantics are kept after redaction; secrets are
@@ -761,6 +835,7 @@ function isRedacted(value) {
 const DEFAULT_CONTEXT = {
     secretNames: new Set(),
     urlNames: new Set(),
+    revealNames: new Set(),
 };
 function secretNameSet(redactionOptions) {
     return new Set(redactionOptions.secretNames ?? []);
@@ -769,6 +844,7 @@ function contextFromOptions(redactionOptions) {
     return {
         secretNames: secretNameSet(redactionOptions),
         urlNames: new Set(redactionOptions.urlNames ?? []),
+        revealNames: new Set(redactionOptions.revealNames ?? []),
     };
 }
 function keyHasSecretSuffix(key) {
@@ -791,7 +867,7 @@ function redactSecrets(value, context = DEFAULT_CONTEXT, depth = 0) {
     if (isObject(value)) {
         for (const k of Object.keys(value)) {
             const v = value[k];
-            if (isSecretKey(k, context.secretNames)) {
+            if (isSecretKey(k, context.secretNames) && !context.revealNames.has(k)) {
                 // A null secret is an absent secret. Masking it would manufacture the
                 // appearance of a configured credential — readers cannot tell
                 // "***"-because-set from "***"-because-null. Redaction hides a value
@@ -832,7 +908,7 @@ function redactUrlValue(value, context, depth) {
     if (isObject(value)) {
         for (const key of Object.keys(value)) {
             const item = value[key];
-            if (isSecretKey(key, context.secretNames)) {
+            if (isSecretKey(key, context.secretNames) && !context.revealNames.has(key)) {
                 if (item !== null)
                     value[key] = REDACTED_MARKER;
             }
@@ -1216,21 +1292,34 @@ function tryStripGenericMicro(key) {
         return null;
     return [stripped, code];
 }
-function isInt(value) {
-    return typeof value === "number" && Number.isInteger(value);
-}
+/**
+ * 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.
+ */
 function decimalIntText(value) {
-    if (typeof value === "string" && /^-?\d+$/.test(value))
-        return value;
+    if (typeof value === "string")
+        return /^-?\d+$/.test(value) ? value : null;
     if (typeof value === "bigint")
         return value.toString();
-    if (isInt(value) && Number.isSafeInteger(value))
-        return String(value);
-    if (isLosslessNumber(value)) {
-        const text = value.toString();
-        return /^-?\d+$/.test(text) ? text : null;
+    let literal;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            return null;
+        literal = value.toString();
     }
-    return null;
+    else if (isLosslessNumber(value)) {
+        literal = value.toString();
+    }
+    else {
+        return null;
+    }
+    const integer = /[.eE]/.test(literal) ? integralFloatText(literal) : literal;
+    if (integer === null)
+        return null;
+    return integer === "-0" ? "0" : integer;
 }
 const MIN_I64 = -9223372036854775808n;
 const MAX_I64 = 9223372036854775807n;
@@ -1240,14 +1329,23 @@ const MAX_U64 = 18446744073709551615n;
 function integerValue(value) {
     if (typeof value === "bigint")
         return value;
-    if (typeof value === "number")
-        return Number.isInteger(value) ? BigInt(value) : null;
+    if (typeof value === "number") {
+        // Read through the shortest spelling, the text the canonical number form
+        // prints, so 2**60 counts as 1152921504606847000 exactly as a decoded
+        // literal of that spelling does in every SDK; BigInt(value) would give
+        // ...846976 and disagree with Rust.
+        if (!Number.isFinite(value))
+            return null;
+        const literal = value.toString();
+        const integer = /[.eE]/.test(literal) ? integralFloatText(literal) : literal;
+        return integer !== null ? BigInt(integer) : null;
+    }
     if (isLosslessNumber(value)) {
         const literal = value.toString();
         if (/^-?\d+$/.test(literal))
             return BigInt(literal);
-        const parsed = Number(literal);
-        return Number.isInteger(parsed) ? BigInt(parsed) : null;
+        const integer = integralFloatText(literal);
+        return integer !== null ? BigInt(integer) : null;
     }
     return null;
 }
@@ -1288,24 +1386,14 @@ function isNum(value) {
 }
 function tryProcessField(key, value) {
     let stripped;
-    // Plain-format suffix processing below does real arithmetic (division,
-    // modulo, Math.floor/abs) that only works on a native JS number. A decoded
-    // LosslessNumber is normalized to one here via Number() \u2014 which never
-    // throws, unlike LosslessNumber's own valueOf() (documented to throw for
-    // values it can't safely represent as number/bigint) \u2014 so an ordinary
-    // decoded value (e.g. duration_ms: 42) keeps formatting exactly as before,
-    // and an exotic decoded value degrades gracefully (loses precision here,
-    // same as it always would for a >2^53 native number) rather than crashing.
-    // This is Plain's documented lossy/human path; JSON/YAML stay exact via
-    // yamlScalar/plainScalar/canonicalJsonString, and decimalIntText below
-    // (msats/sats/epoch_ns) keeps exactness by reading `value` directly instead
-    // of `numeric`.
-    const numeric = isLosslessNumber(value) ? Number(value.toString()) : value;
+    // Appending a unit does no arithmetic and must retain decoded digits.
+    const isNumber = isNum(value) || isLosslessNumber(value);
     // Group 1: compound timestamp suffixes
     stripped = stripSuffixCI(key, "_epoch_ms");
     if (stripped !== null) {
-        if (isInt(numeric)) {
-            const formatted = formatRfc3339Ms(numeric);
+        const integer = signedI64(value);
+        if (integer !== null) {
+            const formatted = formatRfc3339Ms(Number(integer));
             if (formatted !== null)
                 return [stripped, formatted];
         }
@@ -1313,8 +1401,9 @@ function tryProcessField(key, value) {
     }
     stripped = stripSuffixCI(key, "_epoch_s");
     if (stripped !== null) {
-        if (isInt(numeric)) {
-            const formatted = formatRfc3339Ms(numeric * 1000);
+        const integer = signedI64(value);
+        if (integer !== null) {
+            const formatted = formatRfc3339Ms(Number(integer) * 1000);
             if (formatted !== null)
                 return [stripped, formatted];
         }
@@ -1376,20 +1465,20 @@ function tryProcessField(key, value) {
     }
     stripped = stripSuffixCI(key, "_minutes");
     if (stripped !== null) {
-        if (isNum(numeric))
-            return [stripped, `${plainScalar(numeric)} minutes`];
+        if (isNumber)
+            return [stripped, `${plainScalar(value)} minutes`];
         return null;
     }
     stripped = stripSuffixCI(key, "_hours");
     if (stripped !== null) {
-        if (isNum(numeric))
-            return [stripped, `${plainScalar(numeric)} hours`];
+        if (isNumber)
+            return [stripped, `${plainScalar(value)} hours`];
         return null;
     }
     stripped = stripSuffixCI(key, "_days");
     if (stripped !== null) {
-        if (isNum(numeric))
-            return [stripped, `${plainScalar(numeric)} days`];
+        if (isNumber)
+            return [stripped, `${plainScalar(value)} days`];
         return null;
     }
     // Group 4: single-unit suffixes
@@ -1416,8 +1505,8 @@ function tryProcessField(key, value) {
     }
     stripped = stripSuffixCI(key, "_percent");
     if (stripped !== null) {
-        if (isNum(numeric))
-            return [stripped, `${plainScalar(numeric)}%`];
+        if (isNumber)
+            return [stripped, `${plainScalar(value)}%`];
         return null;
     }
     // Group 5: short suffixes (last to avoid false positives)
@@ -1433,27 +1522,27 @@ function tryProcessField(key, value) {
     }
     stripped = stripSuffixCI(key, "_ns");
     if (stripped !== null) {
-        if (isNum(numeric))
-            return [stripped, `${plainScalar(numeric)}ns`];
+        if (isNumber)
+            return [stripped, `${plainScalar(value)}ns`];
         return null;
     }
     stripped = stripSuffixCI(key, "_us");
     if (stripped !== null) {
-        if (isNum(numeric))
-            return [stripped, `${plainScalar(numeric)}\u03bcs`];
+        if (isNumber)
+            return [stripped, `${plainScalar(value)}\u03bcs`];
         return null;
     }
     stripped = stripSuffixCI(key, "_ms");
     if (stripped !== null) {
-        const fv = formatMsValue(numeric);
+        const fv = formatMsValue(value);
         if (fv !== null)
             return [stripped, fv];
         return null;
     }
     stripped = stripSuffixCI(key, "_s");
     if (stripped !== null) {
-        if (isNum(numeric))
-            return [stripped, `${plainScalar(numeric)}s`];
+        if (isNumber)
+            return [stripped, `${plainScalar(value)}s`];
         return null;
     }
     return null;
@@ -1500,17 +1589,18 @@ function processObjectFields(obj) {
 // Formatting Helpers
 // ═══════════════════════════════════════════
 function formatMsAsSeconds(ms) {
-    const formatted = (ms / 1000).toFixed(3);
+    const formatted = toFixedHalfEven(ms / 1000, 3);
     const trimmed = formatted.replace(/0+$/, "");
     if (trimmed.endsWith("."))
         return trimmed + "0s";
     return trimmed + "s";
 }
 function formatMsValue(value) {
-    if (!isNum(value))
+    const numeric = isLosslessNumber(value) ? Number(value.toString()) : value;
+    if (!isNum(numeric) || !Number.isFinite(numeric))
         return null;
-    if (Math.abs(value) >= 1000)
-        return formatMsAsSeconds(value);
+    if (Math.abs(numeric) >= 1000)
+        return formatMsAsSeconds(numeric);
     return `${plainScalar(value)}ms`;
 }
 const MIN_RFC3339_MS = -62135596800000;
@@ -1524,25 +1614,30 @@ function formatRfc3339Ms(ms) {
     return d.toISOString().replace(/(\.\d{3})\d*Z$/, "$1Z");
 }
 /**
- * Round to `digits` decimals using round-half-to-even (banker's rounding) and
- * format with a fixed decimal count. `Number.toFixed` rounds half away from
- * zero, which diverges from the printf `%.1f` used by Rust/Go/Python on exact
- * ties (e.g. 1280 bytes = 1.25 KiB → "1.2KiB", not "1.3KiB").
+ * Format `x` with `digits` decimals the way printf `%.Nf` does in Rust, Go and
+ * Python: round the double's exact binary value, half to even.
+ *
+ * `Number.toFixed` already rounds the exact value, but breaks a true tie
+ * (1.0625 at 3 places) away from zero and switches to exponent form from
+ * 1e21. So take the exact expansion — 100 places covers every double this
+ * can tie on — and round the decimal string here. An epsilon test on
+ * `x * 10 ** digits` is not a substitute: it calls near-ties ties.
  */
 function toFixedHalfEven(x, digits) {
-    const factor = 10 ** digits;
-    const scaled = x * factor;
-    const floor = Math.floor(scaled);
-    const diff = scaled - floor;
-    const eps = 1e-9;
-    let rounded;
-    if (diff > 0.5 + eps)
-        rounded = floor + 1;
-    else if (diff < 0.5 - eps)
-        rounded = floor;
-    else
-        rounded = floor % 2 === 0 ? floor : floor + 1;
-    return (rounded / factor).toFixed(digits);
+    const negative = x < 0;
+    const a = Math.abs(x);
+    // Every double from 1e21 up is an integer, which BigInt spells exactly.
+    const exact = a >= 1e21 ? `${BigInt(a)}.${"0".repeat(100)}` : a.toFixed(100);
+    const [whole, fraction] = exact.split(".");
+    const next = fraction.charCodeAt(digits) - 48;
+    let units = BigInt(whole + fraction.slice(0, digits));
+    const tieBroken = /[1-9]/.test(fraction.slice(digits + 1)) || units % 2n === 1n;
+    if (next > 5 || (next === 5 && tieBroken))
+        units += 1n;
+    const text = units.toString().padStart(digits + 1, "0");
+    const point = text.length - digits;
+    const body = digits === 0 ? text : `${text.slice(0, point)}.${text.slice(point)}`;
+    return negative ? `-${body}` : body;
 }
 function formatBytesHuman(bytes) {
     const KiB = 1024;
@@ -1696,6 +1791,100 @@ function isAmbiguousYamlKey(key) {
     return ["inf", "infinity", "nan"].includes(key.replace(/^[+-]/, "").toLowerCase())
         || /^[-+]?(?:[0-9]+\.?[0-9]*|\.[0-9]+)(?:[eE][-+]?[0-9]+)?$/.test(key);
 }
+/**
+ * Render a number's literal canonically for YAML/plain: 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
+ * placeDecimalPoint. Native numbers and decoded literals share it, and it
+ * works on the text so a digit is never lost to a float64 round trip.
+ */
+function formatNumberLiteral(literal) {
+    return integralFloatText(literal) ?? placeDecimalPoint(literal) ?? normalizeExponent(literal);
+}
+const I64_MIN = -(2n ** 63n);
+const I64_MAX = 2n ** 63n - 1n;
+/**
+ * Spell a non-integral float literal with the notation `Number#toString`
+ * picks: positional when the value lies in [1e-6, 1e21), exponent form
+ * otherwise. A decoded literal carries its own spelling and the other SDKs'
+ * native formatters switch elsewhere, so the choice is made here, on the
+ * digits as written. Null for integer literals and exponents beyond i64,
+ * which keep their spelling.
+ */
+function placeDecimalPoint(literal) {
+    if (!/[.eE]/.test(literal))
+        return null;
+    const sign = literal.startsWith("-") ? "-" : "";
+    const unsigned = sign ? literal.slice(1) : literal;
+    const e = unsigned.search(/[eE]/);
+    const mantissa = e >= 0 ? unsigned.slice(0, e) : unsigned;
+    const [whole, fraction = ""] = mantissa.split(".");
+    const digits = whole + fraction;
+    const significant = digits.replace(/^0+/, "");
+    if (!significant)
+        return null;
+    const shape = /^([-+]?)0*(\d{0,19})$/.exec(e >= 0 ? unsigned.slice(e + 1) : "0");
+    if (!shape || (e >= 0 && unsigned.length === e + 1 + shape[1].length))
+        return null;
+    const exponent = BigInt(shape[1] + (shape[2] || "0"));
+    // point: how many significant digits precede the decimal point.
+    const point = BigInt(whole.length - (digits.length - significant.length)) + exponent;
+    if (exponent < I64_MIN || exponent > I64_MAX || point - 1n < I64_MIN || point > I64_MAX) {
+        return null;
+    }
+    let text;
+    if (point >= 1n && point <= 21n) {
+        const integer = significant.slice(0, Number(point));
+        const rest = significant.slice(Number(point));
+        if (!rest)
+            return null;
+        text = `${integer}.${rest}`;
+    }
+    else if (point >= -5n && point <= 0n) {
+        text = `0.${"0".repeat(Number(-point))}${significant}`;
+    }
+    else {
+        const scale = point - 1n;
+        const rest = significant.length > 1 ? `.${significant.slice(1)}` : "";
+        text = `${significant[0]}${rest}e${scale < 0n ? "-" : "+"}${scale < 0n ? -scale : scale}`;
+    }
+    return sign + text;
+}
+function integralFloatText(literal) {
+    if (!/[.eE]/.test(literal))
+        return null;
+    const negative = literal.startsWith("-");
+    const unsigned = negative ? literal.slice(1) : literal;
+    const e = unsigned.search(/[eE]/);
+    const mantissa = e >= 0 ? unsigned.slice(0, e) : unsigned;
+    const [whole, fraction = ""] = mantissa.split(".");
+    const digits = whole + fraction;
+    if (!/[^0]/.test(digits))
+        return negative ? "-0" : "0";
+    const exponent = e >= 0 ? Number(unsigned.slice(e + 1)) : 0;
+    if (!Number.isSafeInteger(exponent))
+        return null;
+    const point = whole.length + exponent;
+    const split = Math.min(Math.max(point, 0), digits.length);
+    if (/[^0]/.test(digits.slice(split)))
+        return null;
+    const padding = Math.min(Math.max(point - digits.length, 0), 22);
+    const integer = (digits.slice(0, split) + "0".repeat(padding)).replace(/^0+/, "");
+    if (integer.length > 21)
+        return null;
+    return (negative ? "-" : "") + (integer || "0");
+}
+function normalizeExponent(literal) {
+    const match = /^(.*?)[eE]([-+]?)0*(\d*)$/.exec(literal);
+    if (!match)
+        return literal;
+    // An unsigned exponent is positive; spell it like toString() does (e+23).
+    return `${match[1]}e${match[2] || "+"}${match[3] || "0"}`;
+}
+function numberText(value) {
+    // `toString` spells negative zero "0"; the canonical form keeps the sign.
+    return Object.is(value, -0) ? "-0" : formatNumberLiteral(value.toString());
+}
 function yamlScalar(value) {
     if (typeof value === "string")
         return `"${escapeYamlStr(value)}"`;
@@ -1704,14 +1893,14 @@ function yamlScalar(value) {
     if (typeof value === "boolean")
         return value.toString();
     if (typeof value === "number")
-        return value.toString();
+        return numberText(value);
     if (typeof value === "bigint")
         return value.toString();
-    // Decoded number: emit the exact source literal unquoted, matching JSON's
-    // structure-preserving fidelity contract for YAML too.
+    // Decoded number: its exact digits, in the same canonical form a native
+    // number gets.
     if (isLosslessNumber(value))
-        return value.toString();
-    return `"${escapeYamlStr(canonicalJsonString(sortJsonValue(value)))}"`;
+        return formatNumberLiteral(value.toString());
+    return `"${escapeYamlStr(embeddedJson(value))}"`;
 }
 // ═══════════════════════════════════════════
 // Plain Rendering (logfmt)
@@ -1772,19 +1961,19 @@ function plainScalar(value) {
     if (typeof value === "boolean")
         return value.toString();
     if (typeof value === "number")
-        return value.toString();
+        return numberText(value);
     if (typeof value === "bigint")
         return value.toString();
-    // 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 mangled float64 round-trip).
+    // Decoded number: its exact digits (Plain is documented lossy only for
+    // arithmetic-derived formatting), in the same canonical form a native
+    // number gets.
     if (isLosslessNumber(value))
-        return value.toString();
-    return canonicalJsonString(sortJsonValue(value));
+        return formatNumberLiteral(value.toString());
+    return embeddedJson(value);
 }
 function plainScalarRaw(value) {
     if (isObject(value) || Array.isArray(value)) {
-        return canonicalJsonString(sortJsonValue(value));
+        return embeddedJson(value);
     }
     return plainScalar(value);
 }
@@ -1809,6 +1998,11 @@ function quoteLogfmtKey(key) {
 // ═══════════════════════════════════════════
 // Utilities
 // ═══════════════════════════════════════════
+// Arbitrary JSON names, including __proto__, are own data properties. A normal
+// bracket assignment would invoke Object.prototype's legacy prototype setter.
+function setJsonField(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}
 function sanitizeForJson(value, stack = new WeakSet(), depth = 0) {
     if (depth >= MAX_DEPTH)
         return MAX_DEPTH_MARKER;
@@ -1823,8 +2017,9 @@ function sanitizeForJson(value, stack = new WeakSet(), depth = 0) {
         const n = value;
         if (!Number.isFinite(n))
             return "<unsupported:number>";
-        if (Number.isInteger(n) && !Number.isSafeInteger(n))
-            return "<unsupported:unsafe-integer>";
+        // An integral number past 2^53 is still a float64, like every SDK's native
+        // float, and renders by the same canonical rule. A caller that needs such
+        // an integer exactly passes a bigint.
         return n;
     }
     if (t === "bigint")
@@ -1859,7 +2054,7 @@ function sanitizeForJson(value, stack = new WeakSet(), depth = 0) {
         stack.add(obj);
         const out = {};
         for (const [k, v] of Object.entries(obj)) {
-            out[k] = sanitizeForJson(v, stack, depth + 1);
+            setJsonField(out, k, sanitizeForJson(v, stack, depth + 1));
         }
         stack.delete(obj);
         return out;
@@ -1878,17 +2073,23 @@ function isObject(value) {
 function sortedObjectKeys(obj) {
     return Object.keys(obj).sort(jcsCompare);
 }
-function sortJsonValue(value) {
+/**
+ * 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.
+ */
+function embeddedJson(value) {
     if (Array.isArray(value))
-        return value.map(sortJsonValue);
+        return `[${value.map(embeddedJson).join(",")}]`;
     if (isObject(value)) {
-        const out = {};
-        for (const key of sortedObjectKeys(value)) {
-            out[key] = sortJsonValue(value[key]);
-        }
-        return out;
+        const members = sortedObjectKeys(value).map((key) => `${JSON.stringify(key)}:${embeddedJson(value[key])}`);
+        return `{${members.join(",")}}`;
     }
-    return value;
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    return plainScalar(value);
 }
 function jcsCompare(a, b) {
     const ua = Array.from(a).flatMap((c) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "agent-first-data",
-  "version": "0.35.1",
-  "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",
   "repository": {
     "type": "git",
@@ -24,10 +24,10 @@
   "scripts": {
     "build": "tsc",
     "prepack": "npm run build",
-    "test": "tsx --test src/*.test.ts"
+    "test": "node --import tsx --test src/*.test.ts"
   },
   "devDependencies": {
-    "@types/node": "^26.6.5",
+    "@types/node": "^26.6.6",
     "tsx": "^4.23.15",
     "typescript": "^7.0.2"
   },