agent-workflow-inspector 0.0.0-stage → 1.0.0

package/docs/releasing.md

@@ -0,0 +1,112 @@
+# V1.0.0 release procedure
+
+This is an approval-gated plan, not an automated publisher. All public actions below are pending explicit maintainer approval. No publish workflow or write credential has been added. Run commands from the repository root in PowerShell, check each exit code, and stop on any failure or unexpected remote state. GitHub CLI (`gh`) and a supported npm CLI must be installed/authenticated before publication; neither is currently available/authenticated in the Windows release shell. Never print credentials or copy them into the repository.
+
+## Candidate and repository state
+
+- Package: `agent-workflow-inspector@1.0.0`, MIT. Source bin `dist/cli/index.js`, ESM export and declarations `dist/index.js` / `dist/index.d.ts`; Node 22.18+ (22.x), 24.11+ (24.x), 26.x.
+- Local `main` preserves audited history through d2514af. The feature branch is retained. No force push, history rewrite, branch deletion or tag creation is required during preparation.
+- At inspection, public origin was `https://github.com/jigar48/awi.git`, default branch `codex/awi-v1`, sole remote commit d2514af, with no tags/releases. Description/homepage were empty and topics were empty.
+- Public branch metadata reported `protected:false`; repository rulesets returned an empty list. The detailed protection endpoint returned 403 to the connected integration, so a maintainer must confirm settings before changing defaults. Do not bypass any rules; use the required review path if protection changes.
+- The npm registry returned 404 on October 19, 2026. The name is not reserved and no ownership is established by that result. Linux npm 11.17.0 `whoami` returned ENEEDAUTH; Windows npm is absent from PATH. Authenticate the intended maintainer account, with 2FA, and recheck availability immediately before publishing. Never overwrite an existing version; if 1.0.0 appears, stop and compare ownership/source before choosing a new version.
+- Historical [CI run](https://github.com/jigar48/awi/actions/runs/39208844432) passed all nine jobs for d2514af only. It does not validate this later candidate.
+
+## Ordered public actions — approval required
+
+### 1. Push only the final main candidate
+
+```powershell
+git status --porcelain=v1
+git switch main
+$releaseSha = (git rev-parse HEAD).Trim()
+git merge-base --is-ancestor d2514af main
+git ls-remote --symref origin
+git push --set-upstream origin main
+git ls-remote origin refs/heads/main
+```
+
+Require a clean tree, the approved SHA and preserved audited ancestry. If remote main appears or changes, fetch and inspect ancestry before pushing; never force. This push triggers `.github/workflows/ci.yml` on main without changing the default branch.
+
+### 2. Verify fresh main CI
+
+```powershell
+gh run list --repo jigar48/awi --workflow ci.yml --branch main --commit $releaseSha --event push --json databaseId,headSha,status,conclusion,url
+```
+
+Select the matching run ID, then run `gh run watch RUN_ID --repo jigar48/awi --exit-status` and `gh run view RUN_ID --repo jigar48/awi --json headSha,conclusion,jobs`. Require exactly nine successful verify jobs: Windows, macOS and Ubuntu × Node 22.18.0, 24.11.0 and 26. Every install/test/type/lint/build/format/schema/audit/pack/consumer step must pass. Stop publication on a failure or SHA mismatch. Any correction requires a new commit, push, matrix and package validation.
+
+### 3. Set default branch and prepared metadata
+
+Only after successful main CI, inspect branch settings with an admin identity. Apply the prepared description/homepage/topics and default branch:
+
+```powershell
+gh api --method PATCH repos/jigar48/awi --input .github/repository-metadata.json
+gh api --method PUT repos/jigar48/awi/topics --input .github/repository-topics.json
+gh repo edit jigar48/awi --default-branch main
+```
+
+Topics satisfy GitHub's current rules: eight lowercase names using letters/hyphens, each at most 50 characters; maximum allowed is 20. See [GitHub topic requirements](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). Funding appears from `.github/FUNDING.yml`; no external account settings are changed by the local file.
+
+### 4. Freeze artifact and create annotated tag
+
+Recheck HEAD equals the successful CI SHA and clean status. Preserve the exact locally validated tarball and its external SHA-512 integrity manifest. Do not rebuild or substitute it after approval; if regenerated, repeat the clean consumer check and recompute the manifest. Inspect `git ls-remote --tags origin` and ensure no v1.0.0 exists.
+
+```powershell
+git tag -a v1.0.0 $releaseSha -m 'Agent Workflow Inspector v1.0.0'
+git push origin refs/tags/v1.0.0
+git rev-parse 'v1.0.0^{}'
+git ls-remote origin 'refs/tags/v1.0.0*'
+```
+
+Require the peeled remote tag to equal `$releaseSha`. A tag push also triggers CI; do not confuse it with the already required main run. Do not move an existing tag.
+
+### 5. Publish GitHub release
+
+The prepared notes use absolute version-tagged documentation URLs. Remove the candidate status line only in the temporary publication body after approval; preserve the source notes as a preparation record.
+
+```powershell
+$notes = Get-Content docs/releases/v1.0.0.md -Raw
+$notes = $notes.Replace('Release notes prepared for approval. This version has not been published.', 'Initial public release.')
+[IO.File]::WriteAllText((Join-Path $PWD '.awi-audit/release-body.md'), $notes)
+gh release create v1.0.0 agent-workflow-inspector-1.0.0.tgz .awi-audit/release-candidate.json --repo jigar48/awi --verify-tag --title 'Agent Workflow Inspector v1.0.0 — Deterministic AI Agent Trace Diagnostics' --notes-file .awi-audit/release-body.md
+```
+
+The release body labels npm installation as conditional until registry publication succeeds, so an npm authentication failure does not falsely advertise availability. No GitHub release has been created during preparation.
+
+### 6. Publish npm securely
+
+For the first version, prefer interactive npm web login/2FA on the maintainer's trusted machine. The current npm [trust CLI prerequisites](https://docs.npmjs.com/cli/v11/commands/npm-trust/) require the package to exist before a trusted publisher can be configured. Therefore this unpublished name cannot yet use that setup path. Do not create a bootstrap/dummy version, or a long-lived npm automation token.
+
+Install a current supported npm CLI and use the intended maintainer account. Commands below are pending approval and human authentication:
+
+```powershell
+npm login --auth-type=web --registry=https://registry.npmjs.org
+npm whoami --registry=https://registry.npmjs.org
+npm view agent-workflow-inspector versions maintainers --json --registry=https://registry.npmjs.org
+npm publish ./agent-workflow-inspector-1.0.0.tgz --access public --registry=https://registry.npmjs.org --ignore-scripts
+```
+
+Expected pre-publication registry response is E404. Any other response needs review; if version 1.0.0 exists, stop. Human authentication is intentionally outside agent logs. Publish the already validated tarball with lifecycle scripts disabled. Local interactive publication does not create GitHub OIDC provenance; do not claim it does.
+
+GitHub-hosted OIDC trusted publishing is suitable for subsequent versions: public repository/package, pinned actions, protected manual publish workflow, explicit immutable source SHA/tag, passing CI gate, protected environment, `contents: read` and job-scoped `id-token: write`, no write token or release-build cache. npm documents Node >=22.14 and npm >=11.5.1 for OIDC; the trust CLI needs npm >=11.15. A future reviewed `publish.yml` must exist before npm configuration names it. Configure `jigar48/awi`, that exact workflow filename and environment in package settings; stage-only permission with maintainer 2FA approval is preferred. Current npm documentation also requires a new trusted configuration's first successful publish within two days. See [trusted publishing](https://docs.npmjs.com/trusted-publishers/). Do not enable any publisher or add a live workflow during this preparation.
+
+### 7. Verify registry and clean registry consumer
+
+```powershell
+npm view agent-workflow-inspector@1.0.0 name version license engines bin exports types repository homepage bugs dist --json --registry=https://registry.npmjs.org
+npm owner ls agent-workflow-inspector --registry=https://registry.npmjs.org
+```
+
+Require registry `dist.integrity` to equal `.awi-audit/release-candidate.json` tarballIntegrity. Download the registry tarball, verify its SHA-512 and compare bytes with the approved artifact. Never accept matching version strings alone. The tarball manifest records the source SHA; the annotated tag and successful CI must identify that same SHA. Reject any payload difference.
+
+Create a new temporary directory outside the checkout, `npm init -y`, then `npm install --ignore-scripts --save-exact agent-workflow-inspector@1.0.0 --registry=https://registry.npmjs.org`. Execute its installed `node_modules/.bin/awi` (`awi.cmd` on Windows) with --help, --version and all four shipped examples using resolved package paths; expected results match `scripts/package-smoke.mjs`. Check JSON output, exit codes, ESM public imports and strict TypeScript imports, using only declared consumer tooling. Clean up the temporary directory after inspection. This registry-based check cannot run before publication; the local tarball equivalent has already run.
+
+### 8. Verify release links and record outcome
+
+Use `gh release view v1.0.0 --repo jigar48/awi --json url,tagName,targetCommitish,assets,body` and repository metadata to confirm the default main branch, tag, notes and downloadable artifact. Open version-tagged documentation URLs and npm package page. Match the release tarball to the same SHA-512 manifest and record the successful main run URL and release commit. A registry/release mismatch is a release incident, not grounds to force-move a tag or overwrite a version.
+
+After successful publication, a separate documentation-only follow-up may replace the README's candidate notice, add the actual publication date to the changelog, and record registry/release URLs and integrity. Such a follow-up is not part of the v1.0.0 source tag and must not be represented as its published contents.
+
+## Approval gate
+
+Local preparation is complete only after full validation and tarball consumer smoke pass. Publication remains blocked on approval, fresh main CI and authenticated npm ownership/name checks. Approval must explicitly cover main push, remote metadata/default-branch changes, annotated tag push, GitHub release and npm publication. The previous feature-branch push authorization does not authorize these actions.

package/docs/report-schema.md

@@ -0,0 +1,22 @@
+# JSON report v1
+
+[Machine schema](schemas/report.schema.json). Fields: version 1, fingerprintVersion awi-sha256-v1, complete, summaries, findings, warnings. No clock or absolute paths. Optional content requires explicit opt-in.
+
+Summary fields: traceId, operations, toolCalls, maxDepth, optional durationMs and recorded leaf usage. Unknown resources stay absent. Finding fields: ruleId, severity, confidence, title, description, explanation, remediation, traceId, operationIds, structured evidence. References contain operationId and adapter source format/index when available. traceId + operationId is authoritative across merged files; source index preserves adapter recorded order, not causal order. AWI005 is trace-wide with no individual operation list.
+
+Findings sort by descending severity, trace ID, rule ID, then operation ID list using lexical comparison. Warnings deduplicate and sort. CLI filesystem inputs enumerate deterministically. Operations and resource evidence use stable ID ordering after ingestion; timing rules use exact timestamps. Adapter source indices retain recorded order, so ingesting a reordered raw export changes those evidence indices deliberately. Direct-library trace fragments produce the same findings regardless of fragment order.
+
+```json
+{
+  "version": 1,
+  "fingerprintVersion": "awi-sha256-v1",
+  "complete": true,
+  "summaries": [
+    { "traceId": "demo", "operations": 0, "toolCalls": 0, "maxDepth": 0 }
+  ],
+  "findings": [],
+  "warnings": []
+}
+```
+
+complete:false means truncation and is never clean success. Eligibility warnings identify unavailable timing/argument evidence. Complete means all applicable analysis finished, not that absent information was reconstructed. Incompatible contracts require a version change. Evidence fields are rule-specific and additive; consumers should not parse prose.

package/docs/schemas/config.schema.json

@@ -0,0 +1,145 @@
+{
+  "$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 }
+      },
+      "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
+        }
+      },
+      "required": ["AWI001", "AWI002", "AWI003", "AWI004", "AWI005", "AWI006"],
+      "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,117 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "version": { "type": "number", "const": 1 },
+    "fingerprintVersion": { "type": "string", "const": "awi-sha256-v1" },
+    "complete": { "type": "boolean" },
+    "summaries": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "traceId": { "type": "string" },
+          "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"]
+          },
+          "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" },
+          "operationIds": { "type": "array", "items": { "type": "string" } },
+          "evidence": {
+            "type": "object",
+            "propertyNames": { "type": "string" },
+            "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" },
+          "operations": { "type": "array", "items": {} }
+        },
+        "required": ["traceId", "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,11 @@
+# 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.
+
+Ordinary reports include trace/operation IDs, measurements, rule IDs, source indices and explanations. Raw tool names, names, arguments, results, prompts, metadata, error messages and hashes are omitted. IDs can themselves contain secrets; export opaque safe IDs. JSON output escapes terminal formatting and control characters while preserving identifiers on JSON parsing. Human output replaces Unicode controls, formatting controls and line/paragraph separators including ANSI escape and bidirectional controls. Human output colors severity only on supported interactive terminals, honors NO_COLOR and --no-color, and never relies solely on color.
+
+--show-content includes content and can expose private data. Recursive redaction replaces values by keys matching authorization, password, secret, token, API key, cookie, credential, prompt, message, output or result. It cannot recognize every secret, especially arbitrary argument strings and IDs. Review locally before sharing. AWI never transmits content. Default reports also contain sensitive workflow correlations.
+
+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. No general anonymization guarantee exists for identifiers or opt-in content. See SECURITY.md for private disclosure guidance.

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,38 @@
+# 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).
+
+## Hosted CI and release candidate
+
+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. No tag, GitHub release or npm publication has been performed.
+
+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. **Publication remains blocked until approval, a fresh successful matrix on the final main candidate, and npm authentication/name checks.** See [release procedure](releasing.md).