agent-first-data 0.16.1 → 0.17.1

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`, `isValidRfc3339`, `isValidBcp47`, `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/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
@@ -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[] | {
@@ -164,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
@@ -181,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.
  */
 // ═══════════════════════════════════════════
@@ -461,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
@@ -544,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.1",
+  "version": "0.17.1",
   "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"
   }
 }