argsbarg 6.1.7 → 6.1.9

package/src/config/validate.ts

@@ -1,9 +1,10 @@
 /*
-Draft-07 JSON Schema subset validator for program.appConfig files.
-Aligned with common ts-json-schema-generator output (local $ref, objects, scalars).
+JSON Schema validation for program.appConfig and leaf inputSchema (@cfworker/json-schema).
+CLI value coercion for configure set remains here (comma-separated arrays, booleans, etc.).
 */
 
-import { parseCommaList, parseDate, parseDateTime } from "../core/formats.ts";
+import { format as jsonSchemaFormats, type Schema, type SchemaDraft, Validator } from "@cfworker/json-schema";
+import { parseCommaList, parseDate, parseDateTime, validateCommaList } from "../core/formats.ts";
 import { isFrameworkConfigKey } from "./bindings.ts";
 
 type JsonSchema = Record<string, unknown>;
@@ -19,248 +20,183 @@ export interface ValidateResult {
   errors: string[];
 }
 
-/** Validate `data` against a JSON Schema root. Returns human-readable error messages. */
-export function validateConfigDocument(data: unknown, rootSchema: JsonSchema): ValidateResult {
-  const errors: string[] = [];
-  validateValue(data, rootSchema, rootSchema, "$", errors, false);
-  return { valid: errors.length === 0, errors };
-}
-
-/** Validate present keys only — skips root `required` checks (partial writes / bootstrap). */
-export function validateConfigDocumentPartial(data: unknown, rootSchema: JsonSchema): ValidateResult {
-  const errors: string[] = [];
-  validateValue(data, rootSchema, rootSchema, "$", errors, true);
-  return { valid: errors.length === 0, errors };
-}
-
-function validateValue(
-  value: unknown,
-  schema: JsonSchema,
-  root: JsonSchema,
-  path: string,
-  errors: string[],
-  partial: boolean,
-): void {
-  const resolved = resolveSchema(schema, root);
-  if (!resolved) {
-    return;
-  }
-
-  if ("const" in resolved) {
-    if (value !== resolved.const) {
-      errors.push(`${path}: must be ${JSON.stringify(resolved.const)}`);
+if (!jsonSchemaFormats["comma-list"]) {
+  jsonSchemaFormats["comma-list"] = (value: string) => {
+    try {
+      validateCommaList(value);
+      return true;
+    } catch {
+      return false;
     }
-    return;
-  }
+  };
+}
 
-  if (Array.isArray(resolved.enum)) {
-    if (!resolved.enum.some((item) => item === value)) {
-      errors.push(`${path}: must be one of ${JSON.stringify(resolved.enum)}`);
-    }
-    return;
+function dataForSchemaValidation(data: unknown): unknown {
+  if (typeof data !== "object" || data === null || Array.isArray(data)) {
+    return data;
   }
-
-  const anyOf = resolved.anyOf ?? resolved.oneOf;
-  if (Array.isArray(anyOf)) {
-    const branchErrors: string[][] = [];
-    for (const branch of anyOf) {
-      if (typeof branch !== "object" || branch === null || Array.isArray(branch)) {
-        continue;
-      }
-      const branchErrs: string[] = [];
-      validateValue(value, branch as JsonSchema, root, path, branchErrs, partial);
-      if (branchErrs.length === 0) {
-        return;
-      }
-      branchErrors.push(branchErrs);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (isFrameworkConfigKey(key)) {
+      continue;
     }
-    errors.push(`${path}: must match one of the allowed types`);
-    if (branchErrors.length === 1 && branchErrors[0]?.[0]) {
-      errors.push(branchErrors[0][0]);
-    }
-    return;
-  }
-
-  const types = normalizeTypes(resolved.type);
-  if (types.length > 0 && !matchesAnyType(value, types)) {
-    errors.push(`${path}: must be ${types.join(" or ")}`);
-    return;
+    out[key] = value;
   }
+  return out;
+}
 
-  if (types.includes("string") || (types.length === 0 && typeof value === "string")) {
-    validateString(value, resolved, path, errors);
+function schemaWithoutRequired(schema: unknown): JsonSchema {
+  if (typeof schema !== "object" || schema === null) {
+    return schema as JsonSchema;
   }
-  if (types.includes("number") || types.includes("integer")) {
-    validateNumber(value, resolved, path, errors, types.includes("integer"));
+  if (Array.isArray(schema)) {
+    return schema.map(schemaWithoutRequired) as unknown as JsonSchema;
   }
-  if (types.includes("boolean")) {
-    if (typeof value !== "boolean") {
-      errors.push(`${path}: must be boolean`);
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(schema)) {
+    if (key === "required") {
+      continue;
     }
+    out[key] = schemaWithoutRequired(value);
   }
-  if (types.includes("null") && value !== null) {
-    errors.push(`${path}: must be null`);
-  }
-  if (types.includes("object") || (types.length === 0 && isPlainObject(value))) {
-    validateObject(value, resolved, root, path, errors, partial);
-  }
-  if (types.includes("array") || (types.length === 0 && Array.isArray(value))) {
-    validateArray(value, resolved, root, path, errors, partial);
-  }
+  return out as JsonSchema;
 }
 
-function resolveSchema(schema: JsonSchema, root: JsonSchema): JsonSchema | undefined {
-  const ref = schema.$ref;
-  if (typeof ref === "string" && ref.startsWith("#/definitions/")) {
-    const name = decodeURIComponent(ref.slice("#/definitions/".length));
-    const definitions = root.definitions;
-    if (typeof definitions !== "object" || definitions === null || Array.isArray(definitions)) {
-      return schema;
-    }
-    const target = (definitions as Record<string, unknown>)[name];
-    if (typeof target === "object" && target !== null && !Array.isArray(target)) {
-      return target as JsonSchema;
-    }
+function formatInstancePath(instanceLocation: string): string {
+  if (instanceLocation.length === 0 || instanceLocation === "#") {
+    return "$";
   }
-  return schema;
-}
-
-function normalizeTypes(type: unknown): string[] {
-  if (typeof type === "string") {
-    return [type];
+  if (instanceLocation.startsWith("#/")) {
+    return instanceLocation.slice(2).replace(/\//g, ".");
   }
-  if (Array.isArray(type)) {
-    return type.filter((t): t is string => typeof t === "string");
-  }
-  return [];
+  return instanceLocation;
 }
 
-function matchesAnyType(value: unknown, types: string[]): boolean {
-  for (const t of types) {
-    if (t === "null" && value === null) return true;
-    if (t === "array" && Array.isArray(value)) return true;
-    if (t === "object" && isPlainObject(value)) return true;
-    if (t === "integer" && typeof value === "number" && Number.isInteger(value)) return true;
-    if (t === "number" && typeof value === "number") return true;
-    if (t === "boolean" && typeof value === "boolean") return true;
-    if (t === "string" && typeof value === "string") return true;
-  }
-  return types.length === 0;
+function formatValidationErrors(errors: { instanceLocation: string; error: string }[]): string[] {
+  return errors.map(({ instanceLocation, error }) => {
+    const path = formatInstancePath(instanceLocation);
+    return `${path}: ${error}`;
+  });
 }
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
+function decodeJsonPointerSegment(segment: string): string {
+  return segment.replace(/~1/g, "/").replace(/~0/g, "~");
 }
 
-function validateString(value: unknown, schema: JsonSchema, path: string, errors: string[]): void {
-  if (typeof value !== "string") {
-    errors.push(`${path}: must be string`);
-    return;
+/** Map a schema `$schema` URI to the @cfworker/json-schema draft (defaults to Draft-07). */
+export function resolveSchemaDraft(schema: JsonSchema): SchemaDraft {
+  const $schema = schema.$schema;
+  if (typeof $schema !== "string") {
+    return "7";
   }
-  if (typeof schema.minLength === "number" && value.length < schema.minLength) {
-    errors.push(`${path}: string shorter than minLength ${schema.minLength}`);
+  const normalized = $schema.toLowerCase();
+  if (normalized.includes("2020-12")) {
+    return "2020-12";
   }
-  if (typeof schema.maxLength === "number" && value.length > schema.maxLength) {
-    errors.push(`${path}: string longer than maxLength ${schema.maxLength}`);
+  if (normalized.includes("2019-09")) {
+    return "2019-09";
   }
-  if (typeof schema.pattern === "string") {
-    try {
-      if (!new RegExp(schema.pattern).test(value)) {
-        errors.push(`${path}: does not match pattern`);
-      }
-    } catch {
-      /* invalid pattern in schema — skip */
+  if (normalized.includes("draft-04") || normalized.includes("draft/4")) {
+    return "4";
+  }
+  if (normalized.includes("draft-07") || normalized.includes("draft/7")) {
+    return "7";
+  }
+  return "7";
+}
+
+function resolveJsonPointer(root: JsonSchema, ref: string): unknown {
+  if (!ref.startsWith("#/")) {
+    return undefined;
+  }
+  const segments = ref
+    .slice(2)
+    .split("/")
+    .filter((segment) => segment.length > 0)
+    .map(decodeJsonPointerSegment);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (typeof current !== "object" || current === null || Array.isArray(current)) {
+      return undefined;
     }
+    current = (current as Record<string, unknown>)[segment];
   }
+  return current;
 }
 
-function validateNumber(value: unknown, schema: JsonSchema, path: string, errors: string[], integer: boolean): void {
-  if (typeof value !== "number" || Number.isNaN(value)) {
-    errors.push(`${path}: must be number`);
+function attachRootCompanionSchemas(validator: Validator, root: JsonSchema, active: JsonSchema): void {
+  if (active === root) {
     return;
   }
-  if (integer && !Number.isInteger(value)) {
-    errors.push(`${path}: must be integer`);
+  const companion: Schema = {};
+  if (typeof root.definitions === "object" && root.definitions !== null && !Array.isArray(root.definitions)) {
+    companion.definitions = root.definitions;
   }
-  if (typeof schema.minimum === "number" && value < schema.minimum) {
-    errors.push(`${path}: below minimum ${schema.minimum}`);
+  if (typeof root.$defs === "object" && root.$defs !== null && !Array.isArray(root.$defs)) {
+    companion.$defs = root.$defs;
   }
-  if (typeof schema.maximum === "number" && value > schema.maximum) {
-    errors.push(`${path}: above maximum ${schema.maximum}`);
+  if (Object.keys(companion).length > 0) {
+    validator.addSchema(companion);
   }
 }
 
-function validateObject(
-  value: unknown,
+function validatorForSchema(schema: JsonSchema, root: JsonSchema, partial: boolean): Validator {
+  const active = partial ? schemaWithoutRequired(schema) : schema;
+  const validator = new Validator(active as Schema, resolveSchemaDraft(root), false);
+  attachRootCompanionSchemas(validator, root, active);
+  return validator;
+}
+
+function validateInstance(
+  data: unknown,
   schema: JsonSchema,
   root: JsonSchema,
-  path: string,
-  errors: string[],
   partial: boolean,
-): void {
-  if (!isPlainObject(value)) {
-    errors.push(`${path}: must be object`);
-    return;
-  }
-  const properties = schema.properties;
-  const propMap =
-    typeof properties === "object" && properties !== null && !Array.isArray(properties)
-      ? (properties as Record<string, JsonSchema>)
-      : undefined;
+  stripFrameworkKeys: boolean,
+): ValidateResult {
+  const validator = validatorForSchema(schema, root, partial);
+  const payload = stripFrameworkKeys ? dataForSchemaValidation(data) : data;
+  const result = validator.validate(payload);
+  if (result.valid) {
+    return { valid: true, errors: [] };
+  }
+  return { valid: false, errors: formatValidationErrors(result.errors) };
+}
 
-  if (propMap) {
-    for (const [key, propSchema] of Object.entries(propMap)) {
-      if (key in value) {
-        validateValue(value[key], propSchema, root, `${path}.${key}`, errors, partial);
-      }
-    }
-  }
+function validateAgainstSchema(data: unknown, rootSchema: JsonSchema, partial: boolean): ValidateResult {
+  return validateInstance(data, rootSchema, rootSchema, partial, true);
+}
 
-  if (!partial) {
-    const required = schema.required;
-    if (Array.isArray(required)) {
-      for (const key of required) {
-        if (typeof key === "string" && !(key in value)) {
-          errors.push(`${path}: missing required property '${key}'`);
-        }
-      }
-    }
-  }
+/** Validate `data` against a JSON Schema root. Returns human-readable error messages. */
+export function validateConfigDocument(data: unknown, rootSchema: JsonSchema): ValidateResult {
+  return validateAgainstSchema(data, rootSchema, false);
+}
 
-  if (schema.additionalProperties === false && propMap) {
-    for (const key of Object.keys(value)) {
-      if (isFrameworkConfigKey(key)) continue;
-      if (!(key in propMap)) {
-        errors.push(`${path}: unknown property '${key}'`);
-      }
-    }
-  }
+/** Validate present keys only — skips `required` checks (partial writes / bootstrap). */
+export function validateConfigDocumentPartial(data: unknown, rootSchema: JsonSchema): ValidateResult {
+  return validateAgainstSchema(data, rootSchema, true);
 }
 
-function validateArray(
-  value: unknown,
-  schema: JsonSchema,
-  root: JsonSchema,
-  path: string,
-  errors: string[],
-  partial: boolean,
-): void {
-  if (!Array.isArray(value)) {
-    errors.push(`${path}: must be array`);
-    return;
+function resolveSchema(schema: JsonSchema, root: JsonSchema): JsonSchema | undefined {
+  const ref = schema.$ref;
+  if (typeof ref !== "string" || !ref.startsWith("#/")) {
+    return schema;
   }
-  if (typeof schema.minItems === "number" && value.length < schema.minItems) {
-    errors.push(`${path}: fewer than minItems ${schema.minItems}`);
+  const target = resolveJsonPointer(root, ref);
+  if (typeof target === "object" && target !== null && !Array.isArray(target)) {
+    return target as JsonSchema;
   }
-  if (typeof schema.maxItems === "number" && value.length > schema.maxItems) {
-    errors.push(`${path}: more than maxItems ${schema.maxItems}`);
+  return schema;
+}
+
+function normalizeTypes(type: unknown): string[] {
+  if (typeof type === "string") {
+    return [type];
   }
-  const items = schema.items;
-  if (typeof items === "object" && items !== null && !Array.isArray(items)) {
-    for (let i = 0; i < value.length; i++) {
-      validateValue(value[i], items as JsonSchema, root, `${path}[${i}]`, errors, partial);
-    }
+  if (Array.isArray(type)) {
+    return type.filter((t): t is string => typeof t === "string");
   }
+  return [];
 }
 
 export function validateParsedConfigValue(
@@ -271,10 +207,9 @@ export function validateParsedConfigValue(
   if (!propertySchema) {
     return parsed;
   }
-  const errors: string[] = [];
-  validateValue(parsed, propertySchema, rootSchema, "$", errors, false);
-  if (errors.length > 0) {
-    throw new Error(errors[0] ?? "Invalid config value");
+  const result = validateInstance(parsed, propertySchema, rootSchema, false, false);
+  if (!result.valid) {
+    throw new Error(result.errors[0] ?? "Invalid config value");
   }
   return parsed;
 }

package/src/core/types.ts

@@ -219,6 +219,10 @@ export interface CliHttpWireContext {
   clientIp: string;
   path: string;
   method: string;
+  /** W3C trace id when `traceparent` is present on the request. */
+  traceId?: string;
+  /** Span id for this server hop when `traceparent` is present. */
+  spanId?: string;
 }
 
 /** Wire-level MCP hooks on JSON-RPC messages (observe-only). */
@@ -596,7 +600,7 @@ export interface InvokeHookContext {
   locals: CliLocals;
   runtime?: ServerRuntime;
   appConfig: AnyAppConfigSnapshot;
-  http?: { request: Request; clientIp: string; requestId: string };
+  http?: { request: Request; clientIp: string; requestId: string; traceId?: string; spanId?: string };
   mcp?: { rpcMethod: string; toolName?: string; requestId: string };
 }
 
@@ -641,9 +645,9 @@ export interface ReadinessContext {
   runtime: ServerRuntime;
 }
 
-/** Framework logging defaults (ECS json or human text on stderr). */
+/** Framework logging defaults (ECS Logging json or human text on stderr). */
 export interface CliLogConfig {
-  /** `json` = ECS lines; `text` = human stderr lines. Default: `json`. */
+  /** `json` = ECS Logging lines; `text` = human stderr lines. Default: `json`. */
   format?: "json" | "text";
   /** Tee stderr + append; relative paths resolve under the app config dir. */
   file?: string;
@@ -651,6 +655,16 @@ export interface CliLogConfig {
   access?: boolean;
   /** Emit error events after the hook pipeline. Default: true. */
   errors?: boolean;
+  /**
+   * Add non-standard fields to each JSON log line after the ECS baseline.
+   * Cannot override `@timestamp`, `log.level`, `message`, `ecs.version`, or service fields.
+   */
+  enrich?: (ctx: import("../log/ecs.ts").LogEnrichContext) => Record<string, unknown>;
+  /**
+   * Full control over JSON log line serialization. When set, bypasses the built-in ECS formatter.
+   * The consumer owns the entire line (including newline omission).
+   */
+  serialize?: (ctx: import("../log/ecs.ts").LogEnrichContext) => string;
 }
 
 /**

package/src/docs/http-guide.ts

@@ -80,6 +80,16 @@ export function generateHttpGuide(root: CliProgram): string {
     "",
     'Errors use `{ "error": "..." }` with `400`, `404`, `503`, or `500`.',
     "",
+    "## Logging",
+    "",
+    "Server logs go to **stderr** (one JSON object per line by default).",
+    "",
+    "- Configure with `program.log` on the program root",
+    "- **`enrich`** — add custom JSON fields on top of the default line",
+    "- **`serialize`** — replace the formatter and emit your own line shape",
+    "",
+    "See the argsbarg [logging guide](https://github.com/bdombro/bun-argsbarg/blob/main/docs/logging.md) for examples and the full `LogEnrichContext` shape.",
+    "",
   ];
 
   if (root.appConfig?.entries && Object.keys(root.appConfig.entries).length > 0) {

package/src/headless/tool-call.ts

@@ -139,7 +139,7 @@ export async function executeHttpRouteCall(
   pathParams: Record<string, string>,
   query: Record<string, string>,
   body: Record<string, unknown>,
-  http?: { request: Request; clientIp: string; requestId: string },
+  http?: { request: Request; clientIp: string; requestId: string; traceId?: string; spanId?: string },
 ): Promise<HeadlessToolCallResult> {
   const argvResult = httpRequestToArgv(cli.program, route, pathParams, query, body);
   if ("error" in argvResult) {

package/src/hooks/run.ts

@@ -134,8 +134,13 @@ export async function runErrorPipeline(
     failureKind === "unexpected" && obscureUnexpected ? obscureUnexpectedClientMessage() : clientError.message;
 
   emitter?.emitInvokeError(failureKind, err, displayMessage, {
-    invocation: hookCtx.invocation,
-    path: hookCtx.path.join(" "),
+    labels: {
+      invocation: hookCtx.invocation,
+      path: hookCtx.path.join(" "),
+    },
+    requestId: hookCtx.locals.requestId,
+    traceId: hookCtx.http?.traceId,
+    spanId: hookCtx.http?.spanId,
   });
 
   return { failureKind, clientError, errorMsg: displayMessage };

package/src/http/server.ts

@@ -9,6 +9,7 @@ import {
   headlessFailureToHttpResponse,
   headlessSuccessToHttpResponse,
 } from "../headless/tool-call.ts";
+import { extractTraceContext, formatTraceparent } from "../log/trace.ts";
 import type { Cli } from "../runtime/cli.ts";
 import { leafHttpResponseDefaults } from "../runtime/exposure.ts";
 import type { ResolvedHttpServeConfig } from "../server/overrides.ts";
@@ -70,12 +71,14 @@ export async function handleApiRequest(
   const requestId = randomUUID();
   const url = new URL(request.url);
   const clientIp = resolveClientIp(request, trustProxy);
+  const trace = extractTraceContext(request);
   const wireCtx: CliHttpWireContext = {
     request,
     requestId,
     clientIp,
     path: url.pathname,
     method: request.method,
+    ...(trace ? { traceId: trace.traceId, spanId: trace.spanId } : {}),
   };
   const hooks = cli.server?.httpHooks ?? cli.program.httpServer?.hooks;
   const emitter = cli.server?.emitter;
@@ -99,8 +102,22 @@ export async function handleApiRequest(
       durationMs,
       requestId,
       clientIp,
+      traceId: trace?.traceId,
+      spanId: trace?.spanId,
+    });
+    if (!trace) {
+      return response;
+    }
+    const headers = new Headers(response.headers);
+    headers.set(
+      "traceparent",
+      formatTraceparent({ traceId: trace.traceId, spanId: trace.spanId, sampled: trace.sampled }),
+    );
+    return new Response(response.body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers,
     });
-    return response;
   };
 
   await hooks?.onRequest?.(wireCtx);
@@ -168,6 +185,7 @@ export async function handleApiRequest(
       request,
       clientIp,
       requestId,
+      ...(trace ? { traceId: trace.traceId, spanId: trace.spanId } : {}),
     });
     if (result.ok) {
       const leafHttp = leafHttpResponseDefaults(match.route.leaf);

package/src/index.ts

@@ -79,6 +79,8 @@ export {
   wantsExplicitJson,
 } from "./headless/routing.ts";
 export { generateOpenApi, openApiJson } from "./http/openapi.ts";
+export type { EcsLogEvent, LogEnrichContext } from "./log/ecs.ts";
+export { ECS_VERSION, formatEcsLine } from "./log/ecs.ts";
 export type { McpBundlePaths, PackMcpBundleOpts } from "./mcp/bundle.ts";
 export { defaultMcpBundlePaths, generateMcpManifest, packMcpBundle } from "./mcp/bundle.ts";
 export { Cli, type CliInvokeKind, type CliInvokeResult } from "./runtime/cli.ts";

package/src/log/ecs.test.ts

@@ -3,10 +3,10 @@ Unit tests for ECS log line formatting.
 */
 
 import { describe, expect, test } from "bun:test";
-import { formatEcsLine } from "./ecs.ts";
+import { ECS_VERSION, formatEcsLine, mergeEnrichFields, PROTECTED_ECS_KEYS } from "./ecs.ts";
 
 describe("formatEcsLine", () => {
-  test("includes service fields and event action", () => {
+  test("includes ECS Logging baseline fields", () => {
     const line = formatEcsLine(
       { name: "myapp", version: "7.0.0" },
       {
@@ -21,9 +21,49 @@ describe("formatEcsLine", () => {
     expect(parsed["event.action"]).toBe("http.server.start");
     expect(parsed.message).toBe("HTTP API listening");
     expect(parsed["log.level"]).toBe("info");
+    expect(parsed["ecs.version"]).toBe(ECS_VERSION);
     expect(typeof parsed["@timestamp"]).toBe("string");
   });
 
+  test("nests labels object instead of flattening", () => {
+    const line = formatEcsLine(
+      { name: "app", version: "1.0.0" },
+      {
+        level: "info",
+        message: "ok",
+        labels: { request_id: "abc", team: "demo" },
+      },
+    );
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    expect(parsed.labels).toEqual({ request_id: "abc", team: "demo" });
+    expect(parsed["labels.request_id"]).toBeUndefined();
+  });
+
+  test("includes trace and canonical http fields", () => {
+    const line = formatEcsLine(
+      { name: "app", version: "1.0.0" },
+      {
+        level: "info",
+        message: "GET /workspaces",
+        action: "http.access",
+        traceId: "0af7651916cd43dd8448eb211c80319c",
+        spanId: "b7ad6b7169203331",
+        fields: {
+          "http.request.method": "GET",
+          "url.path": "/workspaces",
+          "http.response.status_code": 200,
+          "event.duration": 45_000_000,
+        },
+      },
+    );
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    expect(parsed["trace.id"]).toBe("0af7651916cd43dd8448eb211c80319c");
+    expect(parsed["span.id"]).toBe("b7ad6b7169203331");
+    expect(parsed["http.request.method"]).toBe("GET");
+    expect(parsed["url.path"]).toBe("/workspaces");
+    expect(parsed["event.duration"]).toBe(45_000_000);
+  });
+
   test("includes error stack fields", () => {
     const err = new Error("boom");
     const line = formatEcsLine(
@@ -40,4 +80,30 @@ describe("formatEcsLine", () => {
     expect(parsed["error.type"]).toBe("Error");
     expect(String(parsed["error.stack_trace"])).toContain("boom");
   });
+
+  test("enrich merges additive fields but not protected keys", () => {
+    const line = formatEcsLine({
+      service: { name: "app", version: "1.0.0" },
+      event: { level: "info", message: "hello" },
+      enrich: () => ({
+        "custom.field": "yes",
+        message: "overridden",
+      }),
+    });
+    const parsed = JSON.parse(line) as Record<string, unknown>;
+    expect(parsed.message).toBe("hello");
+    expect(parsed["custom.field"]).toBe("yes");
+  });
+});
+
+describe("mergeEnrichFields", () => {
+  test("skips protected and existing keys", () => {
+    const line: Record<string, unknown> = { message: "keep", "trace.id": "set" };
+    mergeEnrichFields(line, { message: "nope", "ecs.version": "0.0.0", "trace.id": "bad", extra: 1 });
+    expect(line.message).toBe("keep");
+    expect(line["ecs.version"]).toBeUndefined();
+    expect(line["trace.id"]).toBe("set");
+    expect(line.extra).toBe(1);
+    expect(PROTECTED_ECS_KEYS.has("message")).toBe(true);
+  });
 });