agent-first-data 0.16.0 → 0.17.0

package/README.md

@@ -17,7 +17,7 @@ console.log(outputJson(event.toJSON()));
 console.log(outputPlain(event.toJSON()));
 ```
 
-Useful names use TypeScript casing: `outputJson`, `outputYaml`, `outputPlain`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `parseSize`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `cliOutput`, `buildCliError`, `buildCliVersion`, and `cliHandleVersionOrContinue`.
+Useful names use TypeScript casing: `outputJson`, `outputYaml`, `outputPlain`, `outputOptionsForPolicy`, `redactedValue`, `redactUrlSecrets`, `normalizeUtcOffset`, `isValidRfc3339Date`, `isValidRfc3339Time`, `decodeProtocolEvent`, `cliParseOutput`, `cliParseLogFilters`, `cliOutput`, `buildCliError`, `buildCliVersion`, and `cliHandleVersionOrContinue`.
 
 Skill admin and stream redirection are not re-exported from the package root; import them from their own subpaths:
 

package/assets/protocol-v1.schema.json

@@ -47,13 +47,7 @@
       "type": "object",
       "properties": {
         "kind": {"const": "progress"},
-        "progress": {
-          "type": "object",
-          "properties": {
-            "message": {"type": "string", "minLength": 1}
-          },
-          "additionalProperties": true
-        },
+        "progress": true,
         "trace": {"$ref": "#/$defs/trace"}
       },
       "required": ["kind", "progress"],
@@ -63,18 +57,7 @@
       "type": "object",
       "properties": {
         "kind": {"const": "log"},
-        "log": {
-          "type": "object",
-          "properties": {
-            "message": {"type": "string", "minLength": 1},
-            "level": {"enum": ["debug", "info", "warn", "error"]},
-            "code": false
-          },
-          "not": {
-            "required": ["code"]
-          },
-          "additionalProperties": true
-        },
+        "log": true,
         "trace": {"$ref": "#/$defs/trace"}
       },
       "required": ["kind", "log"],

package/assets/registry.json

@@ -132,7 +132,7 @@
       "unit": "bcp47_language_tag",
       "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
       "redaction": {"mode": "none"},
-      "constraints": {"string": true}
+      "constraints": {"bcp47": true}
     },
     {
       "suffix": "_utc_offset",
@@ -152,18 +152,9 @@
       "redaction": {"mode": "none"},
       "constraints": {"integer": true, "minimum": 0}
     },
-    {
-      "suffix": "_size",
-      "category": "size",
-      "json_types": ["string"],
-      "unit": "byte_size_input",
-      "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
-      "redaction": {"mode": "none"},
-      "constraints": {"parse_size_units": ["B", "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB"]}
-    },
     {
       "suffix": "_percent",
-      "category": "ratio",
+      "category": "percentage",
       "json_types": ["number"],
       "unit": "percent",
       "formatting": {"strip_key": true, "plain_yaml": "append_percent"},

package/assets/skills/agent-first-data/references/registry.json

@@ -132,7 +132,7 @@
       "unit": "bcp47_language_tag",
       "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
       "redaction": {"mode": "none"},
-      "constraints": {"string": true}
+      "constraints": {"bcp47": true}
     },
     {
       "suffix": "_utc_offset",
@@ -152,18 +152,9 @@
       "redaction": {"mode": "none"},
       "constraints": {"integer": true, "minimum": 0}
     },
-    {
-      "suffix": "_size",
-      "category": "size",
-      "json_types": ["string"],
-      "unit": "byte_size_input",
-      "formatting": {"strip_key": false, "plain_yaml": "pass_through"},
-      "redaction": {"mode": "none"},
-      "constraints": {"parse_size_units": ["B", "kB", "MB", "GB", "TB", "KiB", "MiB", "GiB", "TiB"]}
-    },
     {
       "suffix": "_percent",
-      "category": "ratio",
+      "category": "percentage",
       "json_types": ["number"],
       "unit": "percent",
       "formatting": {"strip_key": true, "plain_yaml": "append_percent"},

package/assets/skills/agent-first-data/references/rules.md

@@ -37,6 +37,10 @@ The field name is the schema. Always encode units and semantics in the field nam
 | `_epoch_ns` | nanoseconds since Unix epoch as a decimal string | `created_epoch_ns: "1707868800000000000"` |
 | `_rfc3339` | RFC 3339 date-time string | `expires_rfc3339: "2026-02-14T10:30:00Z"` |
 
+Integer vs string is not uniform across siblings: `_epoch_s` and `_epoch_ms` are JSON integers, but `_epoch_ns` is a decimal **string** because nanoseconds exceed the 2⁵³−1 safe-integer range. The same rule applies to large `_sats`/`_msats` (integer when safe, decimal string when not). Writing `_epoch_ns` as a bare JSON number silently loses precision — `afdata lint` rejects it (`suffix_type_mismatch`).
+
+`_rfc3339` needs a **mandatory** offset: `YYYY-MM-DDThh:mm:ss[.fff]` followed by `Z` or `±HH:MM`. A bare `2026-02-14T10:30:00` (no offset), a space instead of `T`, or a trailing IANA name (`...Asia/Shanghai`) is rejected by `afdata lint`. `afdata lint` also type-checks the numeric suffixes (durations `_s`/`_ms`/…, currency `_cents`/`_micro`/`_jpy`) and rejects a `_url` with internal whitespace or bare `user:pass@host` credentials.
+
 ### Strict string formats
 
 | Suffix | Format | Example |
@@ -46,7 +50,7 @@ The field name is the schema. Always encode units and semantics in the field nam
 | `_rfc3339_date` | RFC 3339 full-date string | `invoice_due_rfc3339_date: "2026-06-13"` |
 | `_rfc3339_time` | RFC 3339 partial-time string | `market_open_rfc3339_time: "09:30:00"` |
 
-`*_bcp47` identifies a BCP-47 language tag string. AFDATA does not implement the full BCP-47 registry; tools may validate tags when needed.
+`*_bcp47` identifies a BCP-47 language tag string. AFDATA validates structure (hyphen-separated subtags, 2–3 letter primary language), so the POSIX form `zh_CN` and an over-long primary like `chinese` are rejected; use `zh-CN`. It does not check the IANA registry, so a well-formed-but-unregistered tag like `zz-ZZ` still passes. `is_valid_bcp47` and `afdata lint` apply this check.
 
 `*_utc_offset` identifies a fixed UTC offset. Canonical persisted and structured output values are `"UTC"` or `±HH:MM`, with `HH` in `00..23` and `MM` in `00..59`; zero offsets normalize to `"UTC"`. This is not an IANA timezone name, DST rule, or timezone database field.
 
@@ -63,11 +67,8 @@ Avoid magic string sentinels such as `"auto"` inside strict-format fields. If a
 | Suffix | Example |
 |:-------|:--------|
 | `_bytes` | `payload_bytes: 456789` (non-negative integer) |
-| `_size` | `buffer_size: "10MiB"` or `"10MB"` (config files only, human-readable) |
 
-`_size` parsing requires explicit units: `B`, decimal `kB/MB/GB/TB`, or binary `KiB/MiB/GiB/TiB`. Bare numbers and ambiguous `K/M/G/T` are invalid.
-
-`parse_size("10MiB")` → `10485760`; `parse_size("10MB")` → `10000000`. Returns null for invalid or negative input.
+Byte sizes are always integer `_bytes`, in config and output alike. There is no unit-in-value size string: never write `buffer_size: "10MiB"`. Encode the unit in the key (`buffer_bytes: 10485760`), the same way durations use `timeout_s: 30`.
 
 ### Percentage
 
@@ -75,6 +76,8 @@ Avoid magic string sentinels such as `"auto"` inside strict-format fields. If a
 |:-------|:--------|
 | `_percent` | `cpu_percent: 85` |
 
+Value is in units of percent: `1` = 1%, `0.2` = 0.2%, `85` = 85%. Decimals, negatives, and values >100 are all valid; no fixed range. `%` is exactly 0.01, so `_percent` is never a 0–1 fraction — if the underlying ratio is `0.999`, multiply by 100 and write `success_percent: 99.9`. Writing `0.85` for 85% is a producer-side conversion bug, not a convention ambiguity.
+
 ### Currency
 
 Bitcoin:
@@ -150,7 +153,6 @@ ORM struct fields preserve the suffix: `duration_ms: i64`, not `duration: i64`.
 | `latency: 142` | `latency_ms: 142` | seconds? milliseconds? |
 | `api_key: "sk-..."` | `api_key_secret: "sk-..."` | won't be auto-redacted |
 | `cpu: 85` | `cpu_percent: 85` | 85 what? |
-| `buffer: "10MiB"` | `buffer_size: "10MiB"` | only `_size` gets parsed |
 
 ---
 
@@ -174,7 +176,7 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 4. `_msats`, `_sats`, `_bytes`, `_percent`, `_secret`
 5. `_jpy`, `_ns`, `_us`, `_ms`, `_s`
 
-`_size`, `_bcp47`, `_utc_offset`, `_rfc3339_date`, and `_rfc3339_time` are NOT stripped (pass through). If two keys collide after stripping, both revert to original key AND raw value (no formatting). Redaction runs before collision handling, so fallback never restores a secret.
+`_bcp47`, `_utc_offset`, `_rfc3339_date`, and `_rfc3339_time` are NOT stripped (pass through). If two keys collide after stripping, both revert to original key AND raw value (no formatting). Redaction runs before collision handling, so fallback never restores a secret.
 
 ### Value formatting (YAML and Plain)
 
@@ -184,7 +186,6 @@ Remove recognized formatting suffix from key. Longest match first, exact lowerca
 - `_epoch_ms`/`_epoch_s`/decimal-string `_epoch_ns` → RFC 3339 (negative = pre-1970)
 - `_rfc3339` → pass through
 - `_bytes` → human-readable (`456789` → `446.1KiB`); negative and fractional byte values fall through raw
-- `_size` → pass through
 - `_percent` → append `%`
 - `_msats` → `{n}msats`, `_sats` → `{n}sats`
 - `_usd_cents` → `$X.XX`, `_eur_cents` → `€X.XX`, `_jpy` → `¥X,XXX`, `_{code}_cents` → `X.XX CODE`, `_{code}_micro` → `X.XXXXXX CODE` where `code` is 3-4 ASCII letters
@@ -258,7 +259,7 @@ Startup payload fields are tool-defined; `config` is recommended, while `version
 
 All use `kind` plus the same-named payload and optional `trace`. Do not split protocol events across `stdout` and `stderr`.
 
-Base validators enforce mandatory envelope/error/lifecycle rules. Strict validators additionally require object-valued `trace` on every event, complete log fields (`message`, `level`; `code` field MUST NOT appear in log payload), `retryable` on every error, and a non-empty progress `message`. Use strict validation before claiming compliance with all recommendations.
+Base validators enforce mandatory envelope/error/lifecycle rules. Strict validators additionally require object-valued `trace` on every event and `retryable` on every error. Log and progress payloads remain tool-defined in both profiles. Use strict validation before claiming compliance with all recommendations.
 
 ---
 
@@ -298,11 +299,11 @@ let span = info_span!("request", request_id = %uuid);
 let _guard = span.enter();
 ```
 
-For Go, Python, and TypeScript: emit span fields explicitly in each log event via `.field()` or equivalent event construction.
+For Go, Python, and TypeScript: emit span fields explicitly in each tool-defined log payload.
 
 ### Output fields
 
-Every log line contains `message`, `level` (debug/info/warn/error), plus span fields and event fields. Log payloads MUST NOT contain a `code` field. Do not use the log level as `code`; `code:"error"` is reserved for terminal protocol errors. Projects that need timestamps add them as extension fields (`timestamp_epoch_ms`) via emitter defaults or per-call `.field()`.
+Log payloads have no required or reserved fields. Traditional logging adapters commonly add `message` and `level` (debug/info/warn/error), plus span and event fields, but those names and meanings are adapter conventions rather than AFDATA protocol requirements. Projects that need timestamps add `timestamp_epoch_ms` explicitly.
 
 Log redaction is **by field name** (the same `_secret`/`_url` rule as all output), applied when the line is emitted. Name the secret field — `info!(api_key_secret = %key)` — rather than logging a whole object by its `Debug`/string rendering, which hides the inner field names from redaction. For structured/nested secret-bearing data, build a value, apply redaction through output formatters or redacted_value(), then emit via the standard formatting helpers — do not pass the struct to a `?`/`%`-rendered log field.
 
@@ -340,7 +341,7 @@ Use this checklist when the skill is evaluating a change, not just documenting c
 3. Require secret-bearing values to be named with `_secret` or configured exact secret names before serialization. Do not rely on arbitrary free-text scanning or `Debug`/string-rendered objects.
 4. Run `afdata lint` for JSON/JSONL samples, JSON Schema, MCP schemas, or serialized outputs when available; run `afdata validate` for finite protocol events/streams. If unavailable, report the skipped check.
 5. Before changing an external project's public API, wire format, database schema, or persisted field names, report the compatibility impact and request approval before editing.
-6. Config size values use `_size` suffix (`buffer_size: "10MiB"`, not `buffer: "10MiB"`)
+6. Byte sizes use integer `_bytes` everywhere, config included (`buffer_bytes: 10485760`, never `buffer_size: "10MiB"`)
 7. Environment variables follow `UPPER_SNAKE_CASE` with the same suffixes
 8. One-time CLI output uses `json_log()`/`CliEmitter` + output helpers; long-running services use `afdata_tracing::try_init()` (Rust) to capture via tracing; other languages emit log events explicitly via builders
 9. Database columns use AFDATA suffixes on generic types (`duration_ms INTEGER`, not `duration INTEGER`); native types like `TIMESTAMPTZ` don't need suffixes

package/dist/format.d.ts

@@ -2,8 +2,8 @@
  * AFDATA output formatting and protocol templates.
  *
  * Public APIs include protocol event builders, redactedValue (covers _secret
- * and _url fields), output formatters, redactUrlSecrets, parseSize,
- * normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time,
+ * and _url fields), output formatters, redactUrlSecrets,
+ * normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47,
  * RedactionPolicy, OutputStyle, and OutputOptions.
  */
 export type JsonValue = string | number | boolean | null | JsonValue[] | {
@@ -54,30 +54,19 @@ export declare class JsonErrorBuilder {
     build(): Event;
 }
 export declare class JsonProgressBuilder {
-    private readonly message;
-    private extensionFields;
+    private readonly payload;
     private traceValue;
     private issues;
-    constructor(message: string);
-    field(name: string, value: JsonValue): this;
-    fields(obj: unknown): this;
-    extend(obj: unknown): this;
+    constructor(payload: JsonValue);
     trace(value: Record<string, JsonValue> | undefined): this;
-    private isReservedProgressField;
     build(): Event;
 }
 export declare class JsonLogBuilder {
-    private readonly level;
-    private readonly message;
-    private extensionFields;
+    private readonly payload;
     private traceValue;
     private issues;
-    constructor(level: LogLevel, message: string);
-    field(name: string, value: JsonValue): this;
-    fields(obj: unknown): this;
-    extend(obj: unknown): this;
+    constructor(payload: JsonValue);
     trace(value: Record<string, JsonValue> | undefined): this;
-    private isReservedLogField;
     build(): Event;
 }
 /** Fluent builder for result events. */
@@ -85,9 +74,9 @@ export declare function jsonResult(payload: JsonValue): JsonResultBuilder;
 /** Fluent builder for error events. */
 export declare function jsonError(code: string, message: string): JsonErrorBuilder;
 /** Fluent builder for progress events. */
-export declare function jsonProgress(message: string): JsonProgressBuilder;
+export declare function jsonProgress(payload: JsonValue): JsonProgressBuilder;
 /** Fluent builder for log events. */
-export declare function jsonLog(level: LogLevel, message: string): JsonLogBuilder;
+export declare function jsonLog(payload: JsonValue): JsonLogBuilder;
 /** Validate one protocol event envelope. `strict` also enforces the recommended strict protocol profile (default true). */
 export declare function validateProtocolEvent(event: unknown, strict?: boolean): void;
 /** Validate finite CLI lifecycle: (log | progress)* -> exactly one terminal. `strict` also enforces the recommended strict protocol profile (default true). */
@@ -108,15 +97,12 @@ export type DecodedError = {
 };
 export type DecodedProgress = {
     kind: "progress";
-    message: string;
-    fields: Record<string, JsonValue>;
+    progress: JsonValue;
     trace?: Record<string, JsonValue>;
 };
 export type DecodedLog = {
     kind: "log";
-    level: LogLevel;
-    message: string;
-    fields: Record<string, JsonValue>;
+    log: JsonValue;
     trace?: Record<string, JsonValue>;
 };
 /** Discriminated union of decoded protocol events, narrow on `kind`. */
@@ -127,8 +113,7 @@ export declare class EventDecodeError extends Error {
 }
 /**
  * Parse one protocol line (a single JSON text value), strict-validate it, and
- * return a typed decoded event. Extension fields are every payload key beyond
- * the required ones, collected into `fields`.
+ * return a typed decoded event.
  */
 export declare function decodeProtocolEvent(text: string): DecodedEvent;
 export declare enum RedactionPolicy {
@@ -179,13 +164,6 @@ export declare function redactedValue(value: unknown, options?: {
 export declare function redactUrlSecrets(url: string, options?: {
     secretNames?: readonly string[];
 }): string;
-/**
- * Parse a human-readable size string into bytes.
- * Accepts numbers followed by explicit units. Decimal units are
- * B/kB/MB/GB/TB; binary units are KiB/MiB/GiB/TiB.
- * Trims whitespace and rejects ambiguous K/M/G/T units.
- */
-export declare function parseSize(s: string): number | null;
 /**
  * Normalize a fixed UTC offset string to "UTC" or ±HH:MM.
  * This helper handles fixed offsets only; IANA timezone names and DST rules
@@ -196,3 +174,22 @@ export declare function normalizeUtcOffset(value: string): string | null;
 export declare function isValidRfc3339Date(value: string): boolean;
 /** Return true when value is an RFC 3339 partial-time (HH:MM:SS[.fraction]). */
 export declare function isValidRfc3339Time(value: string): boolean;
+/**
+ * Return true when value is a complete RFC 3339 date-time, such as
+ * 2026-02-14T10:30:00Z or 2026-02-14T10:30:00.5+08:00. Composed from
+ * isValidRfc3339Date and isValidRfc3339Time: a full-date, a T/t separator, a
+ * partial-time (with optional fractional seconds), and a mandatory time-offset
+ * (Z/z or ±HH:MM with HH in 00..23 and MM in 00..59). The offset is required, so
+ * a bare 2026-02-14T10:30:00 is rejected; a space separator is rejected; and a
+ * leap second (:60) is rejected, matching isValidRfc3339Time. Non-ASCII is rejected.
+ */
+export declare function isValidRfc3339(value: string): boolean;
+/**
+ * Return true when value is a structurally well-formed BCP 47 (RFC 5646) language tag.
+ * A grammar-level check, not a registry lookup: hyphen-separated ASCII-alphanumeric
+ * subtags (each 1-8 chars) whose primary subtag is a 2-3 letter language code or the
+ * x/i privateuse/grandfathered lead. Rejects the POSIX underscore form (zh_CN), empty
+ * or misplaced hyphens, non-ASCII, and out-of-range primaries such as chinese. Does not
+ * verify that subtags are registered with IANA.
+ */
+export declare function isValidBcp47(value: string): boolean;

package/dist/format.js

@@ -2,8 +2,8 @@
  * AFDATA output formatting and protocol templates.
  *
  * Public APIs include protocol event builders, redactedValue (covers _secret
- * and _url fields), output formatters, redactUrlSecrets, parseSize,
- * normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time,
+ * and _url fields), output formatters, redactUrlSecrets,
+ * normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47,
  * RedactionPolicy, OutputStyle, and OutputOptions.
  */
 // ═══════════════════════════════════════════
@@ -176,53 +176,11 @@ export class JsonErrorBuilder {
     }
 }
 export class JsonProgressBuilder {
-    message;
-    extensionFields = {};
+    payload;
     traceValue = {};
     issues = [];
-    constructor(message) {
-        this.message = message;
-        if (!message || message === "")
-            this.issues.push("message must be a non-empty string");
-    }
-    field(name, value) {
-        if (this.isReservedProgressField(name)) {
-            this.issues.push(`cannot write reserved progress field ${JSON.stringify(name)}`);
-        }
-        else {
-            this.extensionFields[name] = value;
-        }
-        return this;
-    }
-    fields(obj) {
-        if (!isObject(obj)) {
-            this.issues.push("fields must be a JSON object");
-            return this;
-        }
-        for (const [key, val] of Object.entries(obj)) {
-            if (this.isReservedProgressField(key)) {
-                this.issues.push(`cannot write reserved progress field ${JSON.stringify(key)}`);
-            }
-            else {
-                this.extensionFields[key] = val;
-            }
-        }
-        return this;
-    }
-    extend(obj) {
-        if (!isObject(obj)) {
-            this.issues.push("extend must be a JSON object");
-            return this;
-        }
-        for (const [key, val] of Object.entries(obj)) {
-            if (this.isReservedProgressField(key)) {
-                this.issues.push(`cannot write reserved progress field ${JSON.stringify(key)}`);
-            }
-            else {
-                this.extensionFields[key] = val;
-            }
-        }
-        return this;
+    constructor(payload) {
+        this.payload = payload;
     }
     trace(value) {
         if (value !== undefined) {
@@ -235,71 +193,20 @@ export class JsonProgressBuilder {
         }
         return this;
     }
-    isReservedProgressField(name) {
-        return name === "message";
-    }
     build() {
         if (this.issues.length > 0) {
             throw new EventBuildError(`Failed to build progress event: ${this.issues.join("; ")}`, this.issues);
         }
-        const progress = { ...this.extensionFields };
-        progress.message = this.message;
-        const m = { kind: "progress", progress, trace: this.traceValue };
+        const m = { kind: "progress", progress: this.payload, trace: this.traceValue };
         return new Event(m);
     }
 }
 export class JsonLogBuilder {
-    level;
-    message;
-    extensionFields = {};
+    payload;
     traceValue = {};
     issues = [];
-    constructor(level, message) {
-        this.level = level;
-        this.message = message;
-        if (!message || message === "")
-            this.issues.push("message must be a non-empty string");
-        if (!isValidLogLevel(level))
-            this.issues.push(`level must be one of debug, info, warn, error`);
-    }
-    field(name, value) {
-        if (this.isReservedLogField(name)) {
-            this.issues.push(`cannot write reserved log field ${JSON.stringify(name)}`);
-        }
-        else {
-            this.extensionFields[name] = value;
-        }
-        return this;
-    }
-    fields(obj) {
-        if (!isObject(obj)) {
-            this.issues.push("fields must be a JSON object");
-            return this;
-        }
-        for (const [key, val] of Object.entries(obj)) {
-            if (this.isReservedLogField(key)) {
-                this.issues.push(`cannot write reserved log field ${JSON.stringify(key)}`);
-            }
-            else {
-                this.extensionFields[key] = val;
-            }
-        }
-        return this;
-    }
-    extend(obj) {
-        if (!isObject(obj)) {
-            this.issues.push("extend must be a JSON object");
-            return this;
-        }
-        for (const [key, val] of Object.entries(obj)) {
-            if (this.isReservedLogField(key)) {
-                this.issues.push(`cannot write reserved log field ${JSON.stringify(key)}`);
-            }
-            else {
-                this.extensionFields[key] = val;
-            }
-        }
-        return this;
+    constructor(payload) {
+        this.payload = payload;
     }
     trace(value) {
         if (value !== undefined) {
@@ -312,17 +219,11 @@ export class JsonLogBuilder {
         }
         return this;
     }
-    isReservedLogField(name) {
-        return name === "message" || name === "level" || name === "code";
-    }
     build() {
         if (this.issues.length > 0) {
             throw new EventBuildError(`Failed to build log event: ${this.issues.join("; ")}`, this.issues);
         }
-        const log = { ...this.extensionFields };
-        log.level = this.level;
-        log.message = this.message;
-        const m = { kind: "log", log, trace: this.traceValue };
+        const m = { kind: "log", log: this.payload, trace: this.traceValue };
         return new Event(m);
     }
 }
@@ -335,15 +236,12 @@ export function jsonError(code, message) {
     return new JsonErrorBuilder(code, message);
 }
 /** Fluent builder for progress events. */
-export function jsonProgress(message) {
-    return new JsonProgressBuilder(message);
+export function jsonProgress(payload) {
+    return new JsonProgressBuilder(payload);
 }
 /** Fluent builder for log events. */
-export function jsonLog(level, message) {
-    return new JsonLogBuilder(level, message);
-}
-function isValidLogLevel(level) {
-    return level === "debug" || level === "info" || level === "warn" || level === "error";
+export function jsonLog(payload) {
+    return new JsonLogBuilder(payload);
 }
 /** Validate one protocol event envelope. `strict` also enforces the recommended strict protocol profile (default true). */
 export function validateProtocolEvent(event, strict = true) {
@@ -372,10 +270,6 @@ export function validateProtocolEvent(event, strict = true) {
         return;
     if (!isObject(event.trace))
         throw new Error("event.trace is required in strict mode");
-    if (kind === "log")
-        validateStrictLog(event.log);
-    if (kind === "progress")
-        validateStrictProgress(event.progress);
     if (kind === "error")
         validateStrictError(event.error);
 }
@@ -418,25 +312,6 @@ export function validateProtocolStream(events, strict = true) {
         throw new Error("event stream must contain exactly one terminal result or error");
     }
 }
-function validateStrictLog(payload) {
-    if (!isObject(payload))
-        throw new Error("event.log must be a JSON object in strict mode");
-    // 0.16: log payload MUST NOT contain code field
-    if ("code" in payload) {
-        throw new Error("event.log.code is not allowed in strict mode");
-    }
-    if (typeof payload.message !== "string" || payload.message === "") {
-        throw new Error("event.log.message must be a non-empty string in strict mode");
-    }
-    if (!['debug', 'info', 'warn', 'error'].includes(payload.level)) {
-        throw new Error("event.log.level must be one of debug, info, warn, error in strict mode");
-    }
-}
-function validateStrictProgress(payload) {
-    if (!isObject(payload) || typeof payload.message !== "string" || payload.message === "") {
-        throw new Error("event.progress.message must be a non-empty string in strict mode");
-    }
-}
 function validateStrictError(error) {
     if (!isObject(error))
         throw new Error("event.error must be a JSON object in strict mode");
@@ -461,12 +336,9 @@ export class EventDecodeError extends Error {
     }
 }
 const ERROR_RESERVED_FIELDS = new Set(["code", "message", "hint", "retryable"]);
-const PROGRESS_RESERVED_FIELDS = new Set(["message"]);
-const LOG_RESERVED_FIELDS = new Set(["level", "message"]);
 /**
  * Parse one protocol line (a single JSON text value), strict-validate it, and
- * return a typed decoded event. Extension fields are every payload key beyond
- * the required ones, collected into `fields`.
+ * return a typed decoded event.
  */
 export function decodeProtocolEvent(text) {
     let parsed;
@@ -506,24 +378,10 @@ export function decodeProtocolEvent(text) {
                 decoded.hint = error.hint;
             return decoded;
         }
-        case "progress": {
-            const progress = event.progress;
-            const fields = {};
-            for (const [k, v] of Object.entries(progress)) {
-                if (!PROGRESS_RESERVED_FIELDS.has(k))
-                    fields[k] = v;
-            }
-            return { kind: "progress", message: progress.message, fields, trace };
-        }
-        case "log": {
-            const log = event.log;
-            const fields = {};
-            for (const [k, v] of Object.entries(log)) {
-                if (!LOG_RESERVED_FIELDS.has(k))
-                    fields[k] = v;
-            }
-            return { kind: "log", level: log.level, message: log.message, fields, trace };
-        }
+        case "progress":
+            return { kind: "progress", progress: event.progress, trace };
+        case "log":
+            return { kind: "log", log: event.log, trace };
         default:
             // Unreachable: validateProtocolEvent already constrains event.kind.
             throw new EventDecodeError(`unsupported event kind ${JSON.stringify(event.kind)}`);
@@ -603,42 +461,6 @@ export function redactUrlSecrets(url, options) {
     const redacted = redactUrlInStr(url, secretNameSet(options ?? {}));
     return redacted ?? url;
 }
-/**
- * Parse a human-readable size string into bytes.
- * Accepts numbers followed by explicit units. Decimal units are
- * B/kB/MB/GB/TB; binary units are KiB/MiB/GiB/TiB.
- * Trims whitespace and rejects ambiguous K/M/G/T units.
- */
-export function parseSize(s) {
-    s = s.trim();
-    if (!s)
-        return null;
-    const multipliers = {
-        KiB: 1024,
-        MiB: 1024 ** 2,
-        GiB: 1024 ** 3,
-        TiB: 1024 ** 4,
-        kB: 1000,
-        MB: 1000 ** 2,
-        GB: 1000 ** 3,
-        TB: 1000 ** 4,
-        B: 1,
-    };
-    const unit = Object.keys(multipliers).find((candidate) => s.endsWith(candidate));
-    if (unit === undefined)
-        return null;
-    const numStr = s.slice(0, -unit.length);
-    const mult = multipliers[unit];
-    if (!numStr || !/^(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/.test(numStr))
-        return null;
-    const n = Number(numStr);
-    if (isNaN(n) || n < 0 || !isFinite(n))
-        return null;
-    const result = Math.trunc(n * mult);
-    if (!Number.isSafeInteger(result))
-        return null;
-    return result;
-}
 /**
  * Normalize a fixed UTC offset string to "UTC" or ±HH:MM.
  * This helper handles fixed offsets only; IANA timezone names and DST rules
@@ -686,6 +508,71 @@ export function isValidRfc3339Time(value) {
         return true;
     return value[8] === "." && value.length > 9 && /^[0-9]+$/.test(value.slice(9));
 }
+/**
+ * Return true when value is a complete RFC 3339 date-time, such as
+ * 2026-02-14T10:30:00Z or 2026-02-14T10:30:00.5+08:00. Composed from
+ * isValidRfc3339Date and isValidRfc3339Time: a full-date, a T/t separator, a
+ * partial-time (with optional fractional seconds), and a mandatory time-offset
+ * (Z/z or ±HH:MM with HH in 00..23 and MM in 00..59). The offset is required, so
+ * a bare 2026-02-14T10:30:00 is rejected; a space separator is rejected; and a
+ * leap second (:60) is rejected, matching isValidRfc3339Time. Non-ASCII is rejected.
+ */
+export function isValidRfc3339(value) {
+    if (value.length < 20 || !/^[\x00-\x7F]*$/.test(value))
+        return false;
+    if (!isValidRfc3339Date(value.slice(0, 10)))
+        return false;
+    if (value[10] !== "T" && value[10] !== "t")
+        return false;
+    const rest = value.slice(11);
+    const last = rest[rest.length - 1];
+    let partial;
+    if (last === "Z" || last === "z") {
+        partial = rest.slice(0, -1);
+    }
+    else {
+        if (rest.length < 6 || !isRfc3339NumOffset(rest.slice(-6)))
+            return false;
+        partial = rest.slice(0, -6);
+    }
+    return isValidRfc3339Time(partial);
+}
+function isRfc3339NumOffset(offset) {
+    if (offset.length !== 6 || (offset[0] !== "+" && offset[0] !== "-") || offset[3] !== ":") {
+        return false;
+    }
+    const hours = parseFixedDigits(offset.slice(1, 3));
+    const minutes = parseFixedDigits(offset.slice(4, 6));
+    if (hours === null || minutes === null)
+        return false;
+    return hours <= 23 && minutes <= 59;
+}
+/**
+ * Return true when value is a structurally well-formed BCP 47 (RFC 5646) language tag.
+ * A grammar-level check, not a registry lookup: hyphen-separated ASCII-alphanumeric
+ * subtags (each 1-8 chars) whose primary subtag is a 2-3 letter language code or the
+ * x/i privateuse/grandfathered lead. Rejects the POSIX underscore form (zh_CN), empty
+ * or misplaced hyphens, non-ASCII, and out-of-range primaries such as chinese. Does not
+ * verify that subtags are registered with IANA.
+ */
+export function isValidBcp47(value) {
+    if (!value)
+        return false;
+    const subtags = value.split("-");
+    for (let index = 0; index < subtags.length; index++) {
+        const subtag = subtags[index];
+        if (subtag.length < 1 || subtag.length > 8 || !/^[A-Za-z0-9]+$/.test(subtag)) {
+            return false;
+        }
+        if (index === 0) {
+            const isLanguage = subtag.length >= 2 && subtag.length <= 3 && /^[A-Za-z]+$/.test(subtag);
+            const isSpecial = subtag === "x" || subtag === "i";
+            if (!isLanguage && !isSpecial)
+                return false;
+        }
+    }
+    return true;
+}
 function parseUtcOffsetBody(body) {
     if (!body)
         return null;

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, type LogLevel, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, type DecodedEvent, type DecodedResult, type DecodedError, type DecodedProgress, type DecodedLog, EventDecodeError, type JsonValue, RedactionPolicy, OutputStyle, type OutputOptions, outputOptionsForPolicy, outputJson, outputYaml, outputPlain, redactedValue, redactUrlSecrets, parseSize, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, } from "./format.js";
+export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, type LogLevel, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, type DecodedEvent, type DecodedResult, type DecodedError, type DecodedProgress, type DecodedLog, EventDecodeError, type JsonValue, RedactionPolicy, OutputStyle, type OutputOptions, outputOptionsForPolicy, outputJson, outputYaml, outputPlain, redactedValue, redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
 export { type OutputFormat, type CliEventWriter, CliEmitter, LogFilters, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 /**
  * Agent-First Data (AFDATA) — suffix-driven output formatting and protocol templates.
  */
-export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, EventDecodeError, RedactionPolicy, OutputStyle, outputOptionsForPolicy, outputJson, outputYaml, outputPlain, redactedValue, redactUrlSecrets, parseSize, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, } from "./format.js";
+export { jsonResult, jsonError, jsonProgress, jsonLog, Event, EventBuildError, JsonResultBuilder, JsonErrorBuilder, JsonProgressBuilder, JsonLogBuilder, validateProtocolEvent, validateProtocolStream, decodeProtocolEvent, EventDecodeError, RedactionPolicy, OutputStyle, outputOptionsForPolicy, outputJson, outputYaml, outputPlain, redactedValue, redactUrlSecrets, normalizeUtcOffset, isValidRfc3339Date, isValidRfc3339Time, isValidRfc3339, isValidBcp47, } from "./format.js";
 export { CliEmitter, LogFilters, cliParseOutput, cliParseLogFilters, cliOutput, buildCliError, buildCliVersion, cliRenderVersion, cliHandleVersionOrContinue, } from "./cli.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-first-data",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "A naming convention that lets AI agents understand your data without being told what it means.",
   "license": "MIT",
   "repository": {
@@ -36,7 +36,7 @@
   },
   "devDependencies": {
     "@types/node": "^26.1.1",
-    "tsx": "^4.23.0",
+    "tsx": "^4.23.1",
     "typescript": "^7.0.2"
   }
 }