<!-- Copied from the TypeScript runtime's own documentation at its newest release tag by scripts/build-llms.js; edit the source repository, not this file. -->
# NarrativeTrace

> Code is the log. Auto-generate human-readable execution traces from method names, parameter names, and return values.

NarrativeTrace is a TypeScript library that eliminates manual logging. It wraps objects with ES Proxy to capture every method call and renders the result as Markdown, prose, diagrams, or JSON. It propagates trace identity across fork/join, fire-and-forget and asynchronous-snapshot boundaries — and the work traced across those boundaries comes back into the launching trace — bridges to OpenTelemetry/Winston/Pino, and includes naming clarity analysis that scores code readability and gates builds.

## Install and first trace (copy this)
Node 20+ required. npm only, before `npm add` (else step 2 throws `SyntaxError: Cannot use import statement outside a module`; pnpm/yarn default to it, skip this):
```bash
npm pkg set type=module
npm add @narrativetrace/core-node @narrativetrace/proxy
```
<!-- snippet: examples/sixty-seconds/index.js -->
```js
// index.js
import { NarrativeTraceConfig, SyncNarrativeContext, renderMarkdownBody } from "@narrativetrace/core-node";
import { traceObject } from "@narrativetrace/proxy";

class OrderService {
  placeOrder(customerId, productId, quantity) {
    return `ORD-${customerId}-${productId}-${quantity}`;
  }
}

const context = new SyncNarrativeContext(new NarrativeTraceConfig());
const service = traceObject(new OrderService(), context, {
  placeOrder: ["customerId", "productId", "quantity"],
});

service.placeOrder("C1", "P1", 2);
console.log(renderMarkdownBody(context.captureTrace()));
```
<!-- /snippet -->
Run `node index.js`. Expected output (your duration will differ):
<!-- snippet: examples/sixty-seconds/narrativetrace-output/sixty-seconds/console-output.txt mask=duration -->
```text
- `OrderService.placeOrder(customerId: "C1", productId: "P1", quantity: 2)` → `"ORD-C1-P1-2"` — 0.4ms
```
<!-- /snippet -->

## Before you start
- Parameter names of classes you don't own are lost at compile time — pass them explicitly (`traceObject(target, context, { placeOrder: [...] })`) or every argument renders as `arg0`, `arg1`, ...; unrecognised option keys there now throw, naming the accepted ones, instead of being silently ignored.
- `@narrativetrace/vitest` peers on vitest `1.x`, `2.x`, or `3.x` (tested, not just declared); register `ClaritySuiteReporter`/`GlossarySuiteReporter` from the `@narrativetrace/vitest/reporters` subpath in `vitest.config.ts`, never the package root — the root also loads `vitest` itself, which crashes config loading on every version.
- `DualPathPipeline`'s buffered argument now defaults itself when `null`/omitted, so adding a Winston/Pino/OTel consumer can no longer make `captureTrace()` silently empty; pass an explicit `new BufferedEventConsumer()` when you want to size it yourself.
- Test trace output is on by default since 2026-09-11 (`NARRATIVETRACE_OUTPUT=false` opts out).
- `createNarrativeTest` also writes a value-free `.nt` structural artifact per scenario (last-green baseline, "Since last green" console delta) with no configuration needed; `approval: true` turns on approval traces (`.approved.nt`/`.received.nt`, promote with `pnpm run approve-narratives`). Use `createNarrativeTest(...).each(cases)` — this port's own thin `.each`, not Vitest's native one — for a per-invocation `.nt`/approval identity.
- A Vitest run has a name — one three-word phrase (`runIdentity()`) named in the console footer (`run: bold elk soars`), `manifest.json`'s top-level `run` object, and every Markdown trace's `run:` frontmatter; pass `runIdentity().name` as `runName` to `createPinoEventConsumer`/`createWinstonEventConsumer`/`createEnricherEventConsumer` to carry it into your own logs too. Never reaches the structural `.nt` artifact, an approved/received trace, or the delta computation.

## Field notes from AI agents (self-reported, not a benchmark)
We asked AI agents to build a claims service with NarrativeTrace and write up the experience for another engineer, naming what was awkward. Prompted, one run each, unedited, model named; we wrote the library. The reports so far are from the Java runtime; the same exercise runs for TypeScript next, and the principle they describe — the trace as evidence, redaction by parameter name, output on by default — is the same here. All six reports, the exact prompt and the task: https://narrativetrace.ai/#agents-saying
- "…the release call is present, generated from a real run, not asserted from inside the process being tested." — Claude Sonnet, 2026-09-11
- "The always-on name-based deny-list is a genuinely nice piece of design: naming a parameter `paymentToken` gets you redaction for free, and I could prove it in a test." — Claude Sonnet, 2026-09-11
- "The trace of a failed payment made missing compensation immediately visible, and approval testing caught an extra call that ordinary value assertions accepted." — GPT-6, 2026-09-08

## Docs

- [Complete Reference](https://narrativetrace.ai/typescript/llms-full.txt): Full API reference, 18-package map, configuration, concurrency, integration guides, architecture decisions, and troubleshooting
- [Agent Skills](https://github.com/narrativetrace/narrativetrace-typescript/blob/v0.1.3/documentation/agent-skills.md): `add-narrative-tracing` — install and first trace, ending at the doctor — and `narrativetrace-doctor` — a thin, read-only agent skill over `npx @narrativetrace/cli doctor`, installable today via `.claude/skills/{add-narrative-tracing,narrativetrace-doctor}/`, `.agents/skills/{add-narrative-tracing,narrativetrace-doctor}/` (Codex), or the always-on `AGENTS.md` pointer

## Sections in Complete Reference

- Overview and philosophy
- Quick start (install and trace)
- Package map with dependency graph (18 published packages)
- Core API: NarrativeContext, SyncNarrativeContext, AsyncNarrativeContext, TracingLevel
- Data model: TraceTree, TraceNode, MethodSignature, ParameterCapture, TraceOutcome
- Proxy API: traceObject, ProxyOptions, decorators (@traced, @narrated, @onError, @notTraced)
- Concurrency: ForkJoinGroup (identity propagation, join wait-analysis), FireAndForgetGroup, ContextSnapshot (bidirectional propagation — async work joins the trace that launched it, reported from publication)
- Vitest API: narrativeTest, createNarrativeTest, createNarrativeTest(...).each, writeTraceOutput, writeStructuralOutput, evaluateApprovalTrace, ClaritySuiteReporter, StructuralSuiteReporter, ManifestSuiteReporter, runIdentity (the run has a name)
- Diagrams API: renderMermaidSequence, renderPlantUmlSequence
- Clarity API: analyzeClarity, renderClaritySuiteReport, exportClarityJson, the clarity gate CLI
- Runtime adapters: express, hono, nestjs, angular, react, react-router
- Observability: observability enricher, opentelemetry bridge, winston, pino consumers
- Configuration: NarrativeTraceConfig, TracingLevel, RenderOptions, MarkdownOptions, NARRATIVETRACE_* env
- Architecture decisions: eager serialization, ALS vs stack-based context, frozen immutable data
- Troubleshooting: common issues and fixes