agent-workflow-inspector 0.0.0-stage → 2.0.0

package/docs/releasing.md

@@ -0,0 +1,23 @@
+# Release procedure
+
+## v1.0.0 status (verified October 20, 2026)
+
+- [GitHub release](https://github.com/jigar48/awi/releases/tag/v1.0.0): published October 19, 2026, neither draft nor prerelease. Assets include the package tarball and `release-candidate.json` (an artifact filename, not the current release status).
+- Annotated tag `v1.0.0` resolves to commit `1baca3ebdcc4da792f11487483abf3f60c22d1fb`. The default branch is `main`.
+- [npm registry version](https://registry.npmjs.org/agent-workflow-inspector/1.0.0): HTTP 200, name `agent-workflow-inspector`, version `1.0.0`, published October 19, 2026.
+- Registry tarball integrity: `sha512-lLYHfyeswXS2mF13a0a0YLKkdC6PSSYBnZM74XuYsqfHIiNTkBFQDk6gmhb3fcaAH3Ebf+W+lDo/LxUKv9CAXw==`.
+
+These are read-only metadata checks, not a fresh registry installation or byte comparison against GitHub assets. The registry README still contains historical candidate wording; local documentation changes do not modify existing npm metadata or release assets.
+
+## Future releases
+
+Publication is a separate maintainer action requiring explicit authorization. Never republish 1.0.0, move its tag, or replace its assets to include these later changes.
+
+1. Choose an unused version and review source, package metadata, changelog and release notes. Confirm current registry ownership and existing tags/releases without exposing credentials.
+2. Run `pnpm install --frozen-lockfile`, `pnpm check`, `pnpm verify:quickstart`, `pnpm format:check`, `pnpm schemas`, `git diff --exit-code -- docs/schemas`, `pnpm audit --prod`, `pnpm audit`, and `pnpm smoke:package`.
+3. Require a successful nine-job hosted matrix for the exact approved source commit. Earlier runs do not validate a later commit.
+4. Pack and inspect the artifact. Record the source SHA and tarball SHA-512 outside the package; validate the isolated installed package, executable, examples and ESM/TypeScript imports.
+5. Only after approval, use the maintainer's authenticated release process with interactive 2FA or a separately reviewed trusted publisher. Never store credentials in this repository. No publishing workflow is provided here.
+6. Verify the published tag/source SHA, GitHub assets and registry integrity against the approved artifact. Test a clean registry consumer, then record the date, URLs, CI run and verification limits.
+
+See [verification](verification.md) for historical results and the [release notes](releases/v1.0.0.md) for v1.0.0 behavior.

package/docs/report-schema.md

@@ -0,0 +1,29 @@
+# JSON report v2
+
+The [machine schema](schemas/report.schema.json) and the exported `Report` type use `version: 2`. The `fingerprintVersion` remains `awi-sha256-v1`. The envelope also includes `complete`, `summaries`, `findings`, and `warnings`. Optional `content` requires explicit opt-in. Reports contain no generation timestamp or absolute input path.
+
+Summaries include `traceId`, `operations`, `toolCalls`, `maxDepth`, and, when available, `durationMs` and recorded leaf `usage`. Findings include `ruleId`, `severity`, `confidence`, `title`, `description`, `explanation`, `remediation`, `traceId`, `operationIds`, and structured `evidence`. `evidence.references` repeats the operation aliases and includes the adapter's source format and index when available. A source index describes recorded order in its input, which can repeat across merged files. AWI005 is trace-wide and has empty operation and reference lists.
+
+`traceId` uses `trace-N`. `operationIds` and `evidence.references[].operationId` use `op-N`. Join on `traceId` within a report and on the pair `(traceId, operationId)` for operation references. Ordinals start at 1 and follow the lexical order of recorded trace IDs and the recorded operation IDs within each merged trace. They can shift when inputs are added, removed, or renamed. Findings retain descending severity and the existing lexical order of underlying trace IDs, rule IDs, and operation ID lists. Source indices still depend on the order in the original export. Warnings deduplicate and sort.
+
+```json
+{
+  "version": 2,
+  "fingerprintVersion": "awi-sha256-v1",
+  "complete": true,
+  "summaries": [
+    { "traceId": "trace-1", "operations": 0, "toolCalls": 0, "maxDepth": 0 }
+  ],
+  "findings": [],
+  "warnings": []
+}
+```
+
+`complete: false` indicates truncation and produces a CLI operational failure. Eligibility warnings identify unavailable timing or argument evidence. Consumers should use structured fields for integrations and allow additive evidence fields.
+
+## Migrating from v1
+
+- Update consumers to recognize `version: 2`. The v2 validator rejects v1, and v1 validators reject v2. Trace input and configuration versions are independent of the report version.
+- Replace joins to raw input IDs with report-local joins. For private debugging, `--show-content` and `analyze(traces, config, true)` add `content[].recordedTraceId` alongside the report alias `content[].traceId`. The normalized operation at zero-based index `N - 1` in `content[].operations` corresponds to `op-N` and contains the recorded ID, subject to output sanitization. Findings and summaries keep the same aliases. See [privacy limits](security.md).
+- AWI006 `evidence.recordedCosts` groups amounts by `currency-N` in lexical order of recorded currency labels within the finding. These aliases have finding-local scope.
+- AWI007 remains disabled by default. Once enabled, it reports `failedCalls`, `distinctArgumentFingerprints` and `references`, with operation IDs in run order. V2 omits `toolName` and `errorCode` from evidence even when recorded content is enabled.

package/docs/schemas/config.schema.json

@@ -0,0 +1,183 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "version": { "default": 1, "type": "number", "const": 1 },
+    "rules": {
+      "default": {
+        "AWI001": { "enabled": true, "threshold": 4 },
+        "AWI002": { "enabled": true, "threshold": 3 },
+        "AWI003": { "enabled": true, "minRepetitions": 3, "maxCycleLength": 6 },
+        "AWI004": { "enabled": true, "threshold": 5, "windowSeconds": 30 },
+        "AWI005": { "enabled": true, "maxOperations": 100, "maxDepth": 20 },
+        "AWI006": { "enabled": true },
+        "AWI007": {
+          "enabled": false,
+          "threshold": 4,
+          "minDistinctArguments": 3
+        }
+      },
+      "type": "object",
+      "properties": {
+        "AWI001": {
+          "default": { "enabled": true, "threshold": 4 },
+          "type": "object",
+          "properties": {
+            "enabled": { "default": true, "type": "boolean" },
+            "threshold": {
+              "default": 4,
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 100
+            }
+          },
+          "required": ["enabled", "threshold"],
+          "additionalProperties": false
+        },
+        "AWI002": {
+          "default": { "enabled": true, "threshold": 3 },
+          "type": "object",
+          "properties": {
+            "enabled": { "default": true, "type": "boolean" },
+            "threshold": {
+              "default": 3,
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 100
+            }
+          },
+          "required": ["enabled", "threshold"],
+          "additionalProperties": false
+        },
+        "AWI003": {
+          "default": {
+            "enabled": true,
+            "minRepetitions": 3,
+            "maxCycleLength": 6
+          },
+          "type": "object",
+          "properties": {
+            "enabled": { "default": true, "type": "boolean" },
+            "minRepetitions": {
+              "default": 3,
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 100
+            },
+            "maxCycleLength": {
+              "default": 6,
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 16
+            }
+          },
+          "required": ["enabled", "minRepetitions", "maxCycleLength"],
+          "additionalProperties": false
+        },
+        "AWI004": {
+          "default": { "enabled": true, "threshold": 5, "windowSeconds": 30 },
+          "type": "object",
+          "properties": {
+            "enabled": { "default": true, "type": "boolean" },
+            "threshold": {
+              "default": 5,
+              "type": "integer",
+              "minimum": 2,
+              "maximum": 100
+            },
+            "windowSeconds": {
+              "default": 30,
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 3600
+            }
+          },
+          "required": ["enabled", "threshold", "windowSeconds"],
+          "additionalProperties": false
+        },
+        "AWI005": {
+          "default": { "enabled": true, "maxOperations": 100, "maxDepth": 20 },
+          "type": "object",
+          "properties": {
+            "enabled": { "default": true, "type": "boolean" },
+            "maxOperations": {
+              "default": 100,
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 50000
+            },
+            "maxDepth": {
+              "default": 20,
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 1000
+            }
+          },
+          "required": ["enabled", "maxOperations", "maxDepth"],
+          "additionalProperties": false
+        },
+        "AWI006": {
+          "default": { "enabled": true },
+          "type": "object",
+          "properties": { "enabled": { "default": true, "type": "boolean" } },
+          "required": ["enabled"],
+          "additionalProperties": false
+        },
+        "AWI007": {
+          "default": {
+            "enabled": false,
+            "threshold": 4,
+            "minDistinctArguments": 3
+          },
+          "type": "object",
+          "properties": {
+            "enabled": { "default": false, "type": "boolean" },
+            "threshold": {
+              "default": 4,
+              "type": "integer",
+              "minimum": 4,
+              "maximum": 100
+            },
+            "minDistinctArguments": {
+              "default": 3,
+              "type": "integer",
+              "minimum": 3,
+              "maximum": 100
+            }
+          },
+          "required": ["enabled", "threshold", "minDistinctArguments"],
+          "additionalProperties": false
+        }
+      },
+      "required": [
+        "AWI001",
+        "AWI002",
+        "AWI003",
+        "AWI004",
+        "AWI005",
+        "AWI006",
+        "AWI007"
+      ],
+      "additionalProperties": false
+    },
+    "fingerprint": {
+      "default": { "ignorePaths": [] },
+      "type": "object",
+      "properties": {
+        "ignorePaths": {
+          "default": [],
+          "maxItems": 100,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z_][A-Za-z0-9_]*(\\.[A-Za-z_][A-Za-z0-9_]*)*$"
+          }
+        }
+      },
+      "required": ["ignorePaths"],
+      "additionalProperties": false
+    }
+  },
+  "required": ["version", "rules", "fingerprint"],
+  "additionalProperties": false
+}

package/docs/schemas/report.schema.json

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "version": { "type": "number", "const": 2 },
+    "fingerprintVersion": { "type": "string", "const": "awi-sha256-v1" },
+    "complete": { "type": "boolean" },
+    "summaries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "traceId": { "type": "string", "pattern": "^trace-[1-9][0-9]*$" },
+          "operations": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "toolCalls": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "maxDepth": {
+            "type": "integer",
+            "minimum": 0,
+            "maximum": 9007199254740991
+          },
+          "durationMs": { "type": "number", "minimum": 0 },
+          "usage": {
+            "type": "object",
+            "properties": {
+              "inputTokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "outputTokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "totalTokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "additionalProperties": false
+          }
+        },
+        "required": ["traceId", "operations", "toolCalls", "maxDepth"],
+        "additionalProperties": false
+      }
+    },
+    "findings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "ruleId": {
+            "type": "string",
+            "enum": [
+              "AWI001",
+              "AWI002",
+              "AWI003",
+              "AWI004",
+              "AWI005",
+              "AWI006",
+              "AWI007"
+            ]
+          },
+          "severity": { "type": "string", "enum": ["low", "medium", "high"] },
+          "confidence": { "type": "string", "enum": ["high", "moderate"] },
+          "title": { "type": "string" },
+          "description": { "type": "string" },
+          "explanation": { "type": "string" },
+          "remediation": { "type": "string" },
+          "traceId": { "type": "string", "pattern": "^trace-[1-9][0-9]*$" },
+          "operationIds": {
+            "type": "array",
+            "items": { "type": "string", "pattern": "^op-[1-9][0-9]*$" }
+          },
+          "evidence": {
+            "type": "object",
+            "properties": {
+              "references": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "operationId": {
+                      "type": "string",
+                      "pattern": "^op-[1-9][0-9]*$"
+                    },
+                    "source": {
+                      "type": "object",
+                      "properties": {
+                        "format": { "type": "string", "enum": ["awi", "otel"] },
+                        "index": {
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 9007199254740991
+                        }
+                      },
+                      "required": ["format", "index"],
+                      "additionalProperties": false
+                    }
+                  },
+                  "required": ["operationId"],
+                  "additionalProperties": false
+                }
+              }
+            },
+            "required": ["references"],
+            "additionalProperties": {}
+          }
+        },
+        "required": [
+          "ruleId",
+          "severity",
+          "confidence",
+          "title",
+          "description",
+          "explanation",
+          "remediation",
+          "traceId",
+          "operationIds",
+          "evidence"
+        ],
+        "additionalProperties": false
+      }
+    },
+    "warnings": { "type": "array", "items": { "type": "string" } },
+    "content": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "traceId": { "type": "string", "pattern": "^trace-[1-9][0-9]*$" },
+          "recordedTraceId": { "type": "string" },
+          "operations": { "type": "array", "items": {} }
+        },
+        "required": ["traceId", "recordedTraceId", "operations"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": [
+    "version",
+    "fingerprintVersion",
+    "complete",
+    "summaries",
+    "findings",
+    "warnings"
+  ],
+  "additionalProperties": false
+}

package/docs/schemas/trace.schema.json

@@ -0,0 +1,98 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "version": { "type": "number", "const": 1 },
+    "traceId": { "type": "string", "minLength": 1 },
+    "metadata": {
+      "type": "object",
+      "propertyNames": { "type": "string" },
+      "additionalProperties": {}
+    },
+    "operations": {
+      "maxItems": 50000,
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "parentId": { "type": "string", "minLength": 1 },
+          "type": {
+            "type": "string",
+            "enum": ["tool", "agent", "model", "workflow", "generic"]
+          },
+          "name": { "type": "string", "minLength": 1 },
+          "toolName": { "type": "string" },
+          "startTime": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+          },
+          "endTime": {
+            "type": "string",
+            "format": "date-time",
+            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
+          },
+          "status": {
+            "default": "unknown",
+            "type": "string",
+            "enum": ["ok", "error", "unknown"]
+          },
+          "error": {
+            "type": "object",
+            "properties": {
+              "code": { "type": "string" },
+              "message": { "type": "string" }
+            },
+            "additionalProperties": false
+          },
+          "arguments": {},
+          "resultMetadata": {
+            "type": "object",
+            "propertyNames": { "type": "string" },
+            "additionalProperties": {}
+          },
+          "usage": {
+            "type": "object",
+            "properties": {
+              "inputTokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "outputTokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              },
+              "totalTokens": {
+                "type": "integer",
+                "minimum": 0,
+                "maximum": 9007199254740991
+              }
+            },
+            "additionalProperties": false
+          },
+          "cost": {
+            "type": "object",
+            "properties": {
+              "amount": { "type": "number", "minimum": 0 },
+              "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }
+            },
+            "required": ["amount", "currency"],
+            "additionalProperties": false
+          },
+          "metadata": {
+            "type": "object",
+            "propertyNames": { "type": "string" },
+            "additionalProperties": {}
+          }
+        },
+        "required": ["id", "type", "name", "status"],
+        "additionalProperties": false
+      }
+    }
+  },
+  "required": ["version", "traceId", "operations"],
+  "additionalProperties": false
+}

package/docs/security.md

@@ -0,0 +1,34 @@
+# Security and privacy
+
+All trace content is inert untrusted JSON. AWI never obeys embedded instructions. Analysis uses no eval, shell execution, URL fetching, telemetry, network, database or intermediate content files. Fixed limits apply to parsing, files, spans, nesting, strings, traversal, cycles, findings and default report amplification. Shared native values count once per occurrence against the processed-content budget.
+
+Default JSON and human reports generated by AWI use report-local ordinal references such as `trace-1` and `op-1`. The references encode rank in a deterministic order. They contain no raw identifier bytes or hashes and are scoped to one report (`op-N` is scoped to one trace within that report). AWI007 still compares exact tool names and error codes internally. Its report gives the number of failures, number of distinct argument fingerprints, and operation references. Default reports omit raw names, codes, arguments, results, prompts, metadata, error messages and fingerprint values. AWI006 uses `currency-N` keys in place of recorded currency labels and preserves each currency group's amount.
+
+Reports still expose counts, timing, usage, cost amounts, source indices, relative identifier order, and relationships within the workflow. Those details can be sensitive or allow inference when combined with other data. Review them before sharing. These guarantees apply to reports produced by AWI analysis. The public renderers format the report supplied by the caller and can display strings the caller inserts.
+
+`--show-content` and the third argument to `analyze(traces, config, true)` add a separate `content` section with the recorded trace ID and normalized operations, including recorded operation and parent IDs, names, tool names, error codes, and arguments. Recursive redaction of operations replaces values under keys matching authorization, password, secret, token, API key, cookie, credential, prompt, message, output or result. Arbitrary strings and keys can still reveal private data. Keep these reports private. AWI never transmits trace content.
+
+JSON serialization escapes control and formatting characters where needed. Human output replaces terminal controls, bidirectional formatting and line/paragraph separators. Severity color is limited to supported interactive terminals and honors `NO_COLOR` and `--no-color`.
+
+Parsing rejects `__proto__`, `constructor` and `prototype` object keys. No prototype merging occurs. Files are size-checked before parsing, decoded as strict UTF-8 (optional BOM accepted), and read in bounded chunks even if they grow. Aggregate limits count bytes actually read. CLI rejects symlink entries and symlink components of trace/configuration/output paths. Resolve legitimate OS aliases (including macOS /var temporary paths) to real paths first. POSIX opens also use O_NOFOLLOW, and all platforms compare the opened file identity with the checked file. This is not a filesystem sandbox against concurrent replacement of directory components: use trusted directories and OS permissions. Reports use an adjacent temporary file with mode 0600 on POSIX (Windows uses inherited filesystem ACLs), fsync and atomic exclusive hard-link publication. Existing targets are never overwritten. Cleanup is attempted on ordinary failures; OS errors can prevent removal. Filesystems without hard links fail closed. Crashes or cleanup failures may leave .tmp files to inspect/remove locally under the same filesystem permissions.
+
+Broken stdout pipes produce a controlled operational failure, without an uncaught stack trace. Errors omit raw parser content, OS filenames and stacks. Schema errors show field paths/codes. See [the security policy](../SECURITY.md) for private disclosure guidance.
+
+## Synthetic before and after
+
+Run the same fixture with the AWI007 opt-in configuration on the previous source revision and on the v2 source:
+
+```sh
+node dist/cli/index.js inspect examples/suspicious/argument-drift.json --config examples/argument-drift.config.json --format json
+```
+
+Selected fields from the AWI007 finding:
+
+| Field                                   | Previous report v1                         | Report v2                      |
+| --------------------------------------- | ------------------------------------------ | ------------------------------ |
+| `traceId`                               | `argument-drift`                           | `trace-1`                      |
+| `operationIds`                          | `drift-0`, `drift-1`, `drift-2`, `drift-3` | `op-1`, `op-2`, `op-3`, `op-4` |
+| `evidence.toolName`                     | `search`                                   | Omitted                        |
+| `evidence.errorCode`                    | `INVALID_QUERY`                            | Omitted                        |
+| `evidence.failedCalls`                  | `4`                                        | `4`                            |
+| `evidence.distinctArgumentFingerprints` | `4`                                        | `4`                            |

package/docs/trace-formats.md

@@ -0,0 +1,41 @@
+# Trace formats
+
+## AWI JSON v1
+
+A trace is `{version:1, traceId:string, metadata?:object, operations:Operation[]}`. A collection is `{version:1, traces:Trace[]}`. Unknown fields fail validation; use metadata for extensions. See the [single-trace schema](schemas/trace.schema.json); ingest validates the collection wrapper separately.
+
+Required operation fields: id, type, name. Types: tool, agent, model, workflow, generic. Status: ok, error, unknown (default). Optional fields: parentId, toolName, startTime, endTime, error:{code?,message?}, arguments (any JSON), resultMetadata, usage:{inputTokens?,outputTokens?,totalTokens?}, cost:{amount,currency}, metadata.
+
+Times are offset-bearing ISO-8601 strings, optional independently, with at most nine fractional-second digits. Ordering and overlap use exact nanosecond comparisons; summary duration is a floating-point millisecond measurement. Duration is derived only with both endpoints; end-before-start fails. Trace duration is reported only if all operations have both endpoints. Token counts are nonnegative safe integers; cost is a finite nonnegative amount with a three-letter uppercase currency. Missing resources stay absent; recorded zero stays zero. IDs are nonempty and unique per trace. Missing parents warn and yield lower-bound depth; cycles and duplicates fail. Root depth is 1, empty trace depth 0. Generic operations remain in structure/counts.
+
+## OTLP JSON subset
+
+Accepts protobuf JSON-shaped resourceSpans[].scopeSpans[].spans[]. Does not accept JSONL, legacy instrumentationLibrarySpans, binary protobuf, collector envelopes or proprietary framework exports. Trace IDs are nonzero 32-digit hex; span/parent IDs are 16-digit hex, lowercased. Empty/all-zero parent means root. Missing trace/span IDs fail. Missing scopeSpans/spans are empty; malformed arrays fail.
+
+| Input                                                                     | Canonical mapping                                                                                     |
+| ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| traceId, spanId, parentSpanId, name                                       | identity, parent, name                                                                                |
+| startTimeUnixNano / endTimeUnixNano                                       | ISO times retaining nanosecond precision; decimal strings; numbers must be safe integers              |
+| status.code 1 / STATUS_CODE_OK                                            | ok                                                                                                    |
+| status.code 2 / STATUS_CODE_ERROR                                         | error                                                                                                 |
+| absent, 0, unrecognized status                                            | unknown                                                                                               |
+| gen_ai.tool.name or tool.name                                             | toolName and tool classification                                                                      |
+| gen_ai.operation.name = execute_tool                                      | tool                                                                                                  |
+| invoke_agent                                                              | agent                                                                                                 |
+| chat, generate_content, text_completion, embeddings                       | model                                                                                                 |
+| workflow                                                                  | workflow                                                                                              |
+| unrecognized operation                                                    | generic                                                                                               |
+| gen_ai.tool.call.arguments                                                | arguments; JSON strings parsed if valid, otherwise string preserved                                   |
+| gen_ai.usage.input_tokens / output_tokens / total_tokens                  | separately recorded nonnegative safe integer usage                                                    |
+| exception event: exception.type / exception.message; error status.message | error code/message; status message is a fallback; exception alone does not promote unknown to failure |
+| resource attributes, scope, attributes, events                            | preserved metadata                                                                                    |
+
+Tool name takes precedence over operation classification. No span-name guessing. No results, costs, or usage are invented. AnyValue supports stringValue, boolValue, intValue, doubleValue, bytesValue, arrayValue.values, kvlistValue.values. Integer AnyValues must be signed 64-bit decimal strings or safe integer JSON numbers. Large values outside the safe numeric range stay strings and cannot become usage. Malformed known AnyValue encodings fail; empty or unknown encodings are omitted rather than turned into tool arguments. Arrays/objects with unknown members are not used as argument identity evidence. No type coercion fabricates usage.
+
+These are limited GenAI semantic-convention assumptions, not universal compatibility. Instrumentation can use different attributes or omit arguments; inspect warnings or explicitly convert to AWI JSON. No framework integration has been certified. Positive-duration nanosecond spans retain their precision; truly zero-duration groups are excluded conservatively. Attributes/events remain in memory and are absent from default reports.
+
+Auto-detection requires exactly one recognizable AWI/OTLP root. Otherwise specify input-format or fix the export. Malformed required data fails as a unit rather than silently dropping spans.
+
+Resource attributes are decoded once per resourceSpans entry. Raw and normalized structures each have a bounded node budget; exports with extreme shared-metadata amplification fail explicitly. Binary AnyValues remain opaque base64 metadata and are not interpreted as tool/operation names, errors or argument identity. Unknown duplicate attributes clear earlier evidence rather than reviving stale values. Timestamp zero means missing; negative/out-of-uint64 timestamps fail. Unknown attributes remain outside classification; this subset does not certify every semantic-convention revision.
+
+For missing or empty span names, the display label is unnamed and metadata awi.operation_name_recorded is false. An explicit execute_tool span still counts as a tool, but identity rules exclude it unless an actual tool name or recorded operation name is available. The display placeholder never establishes tool identity.

package/docs/troubleshooting.md

@@ -0,0 +1,12 @@
+# Troubleshooting
+
+- Invalid JSON/schema: use UTF-8 JSON, supported version and fields. JSONL/collector envelopes need conversion.
+- Ambiguous format: remove conflicting roots or explicitly select input-format; schemas still apply.
+- No sequence findings: read warnings. Recorded arguments, positive-duration times, shared parent and non-overlap are required. Patterns may span bounded windows.
+- Duplicate IDs: files sharing traceId merge. Give unrelated executions different identities.
+- Filesystem failure: check permissions, existing output, regular inputs and hard-link support. Use a new report path.
+- Directory rejected: use a dedicated JSON trace directory; empty dirs, symlinks, unrelated files and excessive recursion fail.
+- Exit 2: severity met fail-on (default high). Review evidence or adjust policy.
+- Exit 1/incomplete: fix input or split workloads. Finding overflow is not success.
+- Missing tokens/cost: unknown remains absent; parent totals are not attributed to tools.
+- Install engines failure: use supported Node. Do not bypass engines or delete lockfile to hide incompatibility.

package/docs/verification.md

@@ -0,0 +1,44 @@
+# Verification record
+
+Audit date: October 19, 2026. Package manager: pnpm 11.25.0. Baseline implementation: 9bc61c1. See the historical [audit findings](audit.md) and current [release procedure](releasing.md).
+
+## Quickstart documentation check — October 20, 2026
+
+On Windows, Node 24.19.0 / pnpm 11.25.0: frozen-lockfile installation, `pnpm check` (72 tests: 69 existing plus two README process-exit checks and one documentation encoding check; typecheck, lint and JS/declaration build), `pnpm verify:quickstart`, `pnpm format:check`, schema regeneration with no drift, isolated `pnpm smoke:package`, and `git diff --check` passed. README/getting-started synthetic JSON traces also parsed and analyzed with zero findings.
+
+The quickstart verifier checks complete JSON reports, no warnings, healthy exit 0 with no findings, and retry exit 2 with exactly `AWI002`, `AWI004`, `AWI006`. It uses `process.execPath`, script-relative paths and no shell or network operations. The existing nine-job workflow now runs it; this change has not yet run on hosted CI, macOS, Linux or the other supported Node versions. No runtime source, dependencies or lockfile changed. The README gate exits 0 for the healthy fixture and 1 for the retry fixture; the CLI retains its existing exit codes. Registry/GitHub status was checked read-only; see [release status and limits](releasing.md). No push, tag, release, publish or deployment was performed during this check.
+
+## Historical hosted CI and release preparation
+
+The [nine-job hosted CI run](https://github.com/jigar48/awi/actions/runs/39208844432) completed successfully for `d2514af3e9d4a7b11a53308a77ab2ca40333d8ce`. Windows, macOS and Ubuntu each passed on Node 22.18.0, 24.11.0 and 26, including all 69 tests, typecheck/lint/build, formatting, schema consistency, production dependency audit, packing and isolated package installation/API checks.
+
+The platform table below records the earlier local audit only. The hosted run resolves that audit's platform gate for d2514af. Later local release-preparation changes affect documentation/package metadata, not runtime source or dependencies. They require a fresh nine-job main run before publication; earlier CI does not validate them. At that preparation stage, no tag, GitHub release or npm publication had been performed; publication was subsequently confirmed on October 20, 2026 (see [current release status](releasing.md)).
+
+Release-preparation validation on Windows Node 24.19.0: `pnpm install --frozen-lockfile`, `pnpm check` (69 passing tests, typecheck, lint, JS/declaration build), `pnpm format:check`, `pnpm schemas` (before/after schema hashes unchanged), full `pnpm audit` (no known vulnerabilities), `pnpm smoke:package` (clean external consumer, all shipped examples/options, ESM and strict TypeScript imports), and `git diff --check` passed. Runtime source, tests, dependencies, lockfile and CI workflow remain identical to d2514af. Local documentation links and prepared GitHub topic syntax were checked; version-tagged release links intentionally await tag creation. Maintainer GitHub/portfolio/support links responded successfully; LinkedIn rejects HEAD checks, so that supplied URL is retained without claiming live content verification. Candidate artifact byte counts, SHA-256/SHA-512 and source SHA are recorded outside the package in the local release manifest.
+
+## Actual platform checks
+
+| Environment                   | Node                      | Full tests | Typecheck / lint / full build | Isolated installed-package check |
+| ----------------------------- | ------------------------- | ---------- | ----------------------------- | -------------------------------- |
+| Windows x64                   | 24.19.0                   | 69 passed  | Passed                        | Passed                           |
+| Ubuntu 24.04.3 x64 under WSL2 | 24.19.0                   | 69 passed  | Passed                        | Passed                           |
+| Ubuntu 24.04.3 x64 under WSL2 | 22.18.0                   | 69 passed  | Passed                        | Passed                           |
+| Ubuntu 24.04.3 x64 under WSL2 | 26.0.0                    | 69 passed  | Passed                        | Passed                           |
+| macOS                         | Not available             | Not run    | Not run                       | Not run                          |
+| Hosted GitHub Actions matrix  | 9 configured combinations | Not run    | Not run                       | Not run                          |
+
+WSL uses real Linux Node distributions and independent Linux dependencies. Downloaded runtimes were verified against their official SHA-256 manifests. WSL/NTFS and Linux temporary-filesystem checks do not certify macOS or hosted runners. Windows Node 22/26 and the exact Node 24.11.0 floor remain for CI to verify. Future Node majors are not verified by these runs.
+
+## Checks performed
+
+- Strict TypeScript, ESLint and full JS/declaration builds.
+- 69 tests: original 37 plus 32 targeted audit regressions, with additional assertions in existing tests. All six rules have positive/negative coverage; tests include exact concurrency/time boundaries, failure interactions, graph errors, OTLP encodings, source validation, deterministic fragments and capped findings, hostile content, terminal/JSON escaping, UTF-8/BOM, symlinks, overwrite/hardlink/long-name handling, resource budgets and operational exit codes.
+- The original 50,000-operation performance assertion remains unchanged. Specific hostile metadata, wide-array and shared-string vectors return controlled errors in a 96 MiB child heap; this is not a universal minimum-memory guarantee for all maximum-size inputs.
+- Network, DNS/fetch and subprocess APIs were blocked while analyzing hostile trace values; no external effects occurred.
+- Frozen-lockfile installation, formatting, whitespace checks and deterministic schema regeneration.
+- Full pnpm audit reported no known dependency vulnerabilities at audit time. This result can change; it does not assess all Node/OS vulnerabilities or prove absence of defects.
+- Actual tarball allowlist, executable mode/shebang, bin/ESM/type export mappings, included maintainer documents, installation outside the repository with scripts disabled, all shipped examples/options and strict consumer TypeScript imports.
+
+A cold-filesystem declaration compilation timeout and a multi-process CLI test timeout were diagnosed as test-harness I/O budgets, not waived product assertions. CLI setup compiles runtime JS with a bounded setup timeout; full builds/consumer typechecks still verify declarations. CLI subprocesses and end-to-end I/O cases have explicit budgets; detector performance checks remain unchanged.
+
+During the original local audit, no remote mutations occurred. The later authorized feature-branch push produced the successful hosted run above. At that stage, publication required approval, a fresh successful matrix on the final main candidate, and npm authentication/name checks. The current published status is recorded separately. See [release procedure](releasing.md).