autotel-eventcatalog 2.0.0 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,74 @@
 # Changelog
 
+## 4.0.0
+
+### Minor Changes
+
+- fb6cba7: ### autotel-pact
+
+  First public release. Runtime evidence for Pact contracts: a green Pact suite proves compatibility; this package proves relevance by recording which contracted interactions were actually exercised, by whom, and how recently. Four independent evidence sources feed a single audit matrix.
+
+  **Consumer side**
+  - `withPactInteraction(pact, handler, opts)` wraps `MessageConsumerPact.verify()`. It opens an autotel span with `pact.*` attributes, runs the underlying verification, and appends a `source: test, role: consumer` ledger entry.
+  - `withHttpPactInteraction(pact, interaction, testFn)` mirrors the same shape on `PactV3.executeTest()`.
+  - `autotel-pact/auto-wrap` is a vitest/jest setup entry that monkey-patches `MessageConsumerPact.prototype.verify` and `PactV3.prototype.executeTest`. Adopting is a single config-file line. The patch is idempotent and a no-op when Pact-JS is not installed.
+  - Pass `interactionId: 'order.created.v1'` to keep audit rows stable across `expectsToReceive` renames. The audit matches on `interactionId` first and description as fallback.
+
+  **Provider side**
+  - `withProviderVerification(verifierOpts, wrapOpts)` runs the Pact Verifier inside an autotel span. On success it fans out one ledger row per interaction in the pact file with `role: 'provider'`. On failure it emits a single `provider_verification_run` record, because the failure cannot be attributed to one interaction.
+  - `skipVerifier: true` skips loading and calling the Verifier and emits the success-path rows from the pact file alone. For demos, smoke tests, and audit-pipeline exercises; not for production CI.
+
+  **Production observation**
+  - `PactLedgerSpanProcessor` plus `tagPactInteraction({...})` lets you record `source: production` evidence from any span whose handler is part of a contracted interaction. Outcome is derived from `span.status.code` (OTel `ERROR` becomes `failed`).
+  - Bounded queue with drop-oldest-on-full eviction so newest evidence survives sustained pressure. Throttled warning on each drop wave. Fail-open writes: a ledger I/O error reports via `onWriteError` and never breaks the app.
+  - `appendLedgerEntryAsync` applies producer-side backpressure. Callers await drainage past 4096 pending writes so memory cannot grow unbounded.
+
+  **Pact Broker enrichment**
+  - The audit CLI reads the latest Pact Broker verification per consumer/provider pair when `--broker-url` (or `PACT_BROKER_BASE_URL`) is set. Supports bearer token and basic auth.
+  - The audit row distinguishes "broker said no" from "broker unreachable or errored" via the `broker_error` field. `--gate=broker` exits non-zero on either condition, so a transient broker outage cannot silently pass CI.
+  - Broker verification is at pact-pair granularity, not per-interaction. The package documents this limitation in every surface that shows the column.
+
+  **Audit CLI**
+  - `autotel-pact audit` prints a nine-column table: STATUS, CONTRACTED, TEST_SEEN, PROD_SEEN, PROVIDER_VERIFIED, BROKER_VERIFIED, CONSUMER → PROVIDER, KIND, INTERACTION. Status is OK (contracted and seen in test), STALE (contracted, not seen in test), or SHADOW (seen anywhere with no contract).
+  - Gates: `--gate` (default) fails on STALE rows; `--gate=strict` also fails on SHADOW rows; `--gate=broker` fails when any contracted row lacks broker proof or the broker was unreachable.
+  - `--json` emits the v0.2.0 audit matrix; counts use names that match the v0.2 semantics: `contracted_and_test_seen`, `contracted_not_test_seen`, `test_or_prod_seen_not_contracted`.
+
+  **Schemas**
+  - `autotel-pact-ledger-entry/v0.2.0` and `autotel-pact-audit-matrix/v0.2.0`, published as JSON Schema under `schemas/`. Every persisted artifact carries a `spec` envelope so downstream tooling can refuse unknown majors.
+
+  **Coverage**
+  - 91 unit tests across 13 files. End-to-end demo in `apps/example-contract-testing` exercises every evidence path (TEST_SEEN, STALE, SHADOW, PROVIDER_VERIFIED, PROD_SEEN) and asserts the resulting matrix programmatically.
+
+  ### autotel-eventcatalog
+
+  `stamp` and `generate` commands now accept `--format json` for machine-readable stdout output, matching what `drift` already does. Default remains `text`.
+
+  Other improvements:
+  - `loadSnapshot` produces actionable error messages (`Snapshot not found`, `Snapshot is empty`, `Snapshot is not valid JSON`, …) instead of raw `ENOENT` / `SyntaxError`.
+  - The undocumented `--version` flag for `generate` is now shown in `--help`.
+  - The `schemas/README.md` documents why `v0.1.0` schemas are preserved alongside `v0.2.0`.
+  - Removed an unsafe inline type cast in `diff.ts` (`fieldStats` is already correctly typed on `EventObservation`).
+
+  ### autotel-subscribers
+
+  `ArchitectureSnapshotSubscriber.toSnapshot()` and `.writeToFile()` now accept an optional `freezeTimestamps: string` option. When supplied, every timestamp in the output (`generatedAt`, plus each event's `firstSeen` / `lastSeen`) is replaced with that value — useful when writing a snapshot intended to be committed to a repository as a stable artifact.
+
+  Production code that captures real observation timestamps should not pass this option; it exists for snapshot-as-documentation workflows where byte-stability matters more than wall-clock accuracy.
+
+  The legacy `toSnapshot(now)` form (passing a bare clock function) continues to work for backward compatibility.
+
+### Patch Changes
+
+- Updated dependencies [fb6cba7]
+  - autotel-subscribers@34.1.0
+
+## 3.0.0
+
+### Patch Changes
+
+- Updated dependencies [30a485b]
+  - autotel-subscribers@34.0.0
+
 ## 2.0.0
 
 ### Minor Changes

package/CONTRIBUTING.md

@@ -1,7 +1,7 @@
 # Contributing to autotel-eventcatalog
 
-A short, opinionated guide. The package is small enough that you can read all
-of it in an afternoon; this doc is here so you don't have to.
+A short, opinionated guide. The package is small enough to read in an
+afternoon; this doc covers it so you don't have to.
 
 ## Where things live
 
@@ -27,9 +27,10 @@ packages/autotel-eventcatalog/
 │   └── cli.e2e.test.ts      e2e tests (spawn the built CLI)
 │   └── contract.test.ts     versioned-JSON contract tests
 ├── schemas/
-│   ├── drift-report-v0.1.0.json
-│   ├── drift-summary-v0.1.0.json
-│   └── stamp-summary-v0.1.0.json
+│   ├── drift-report-v0.2.0.json
+│   ├── drift-summary-v0.2.0.json
+│   ├── stamp-summary-v0.1.0.json
+│   └── generate-summary-v0.1.0.json
 ├── action.yml               composite GitHub Action (used by external repos)
 ├── docs/                    this folder
 └── README.md
@@ -59,13 +60,12 @@ cli.ts ─► everything (the only place all branches meet)
 3. `cli.ts` is the dispatcher; nothing else imports from `cli.ts`.
 4. `stamp.ts` is independent of `diff.ts`. They share inputs but no logic.
 
-If a future change wants to break one of these rules, that's the signal to
-stop and ask whether the new feature belongs in this package.
+If a future change would break one of these rules, stop and ask whether the
+new feature belongs in this package.
 
 ## Load-bearing invariants
 
-These are the rules I'd commit to keeping. Future-me, future-contributors:
-when in doubt, push back.
+These are the rules I'd commit to keeping. When in doubt, push back.
 
 ### 1. No new top-level commands without a user
 
@@ -94,10 +94,9 @@ dashboard, a file watcher, an LSP server, an MCP server, a webhook
 listener) lives in [`autotel-subscribers`](../autotel-subscribers/) or in
 example apps.
 
-The reason: long-running processes have a different lifecycle from
-command-line tools. Process management, signal handling, restart
-semantics, observability. Mixing the two doubles the operational surface
-for no clarity gain.
+Long-running processes have a different lifecycle from command-line
+tools: process management, signal handling, restart semantics, observability.
+Mixing the two doubles the operational surface for no clarity gain.
 
 ### 3. No domain-specific extensions to the core
 
@@ -106,11 +105,10 @@ events, services, channels, field paths. Adding a SARIF renderer should
 never require a `severity` field on `DriftCounts`. Adding a Slack
 renderer should never require a `messageColor` field on `DriftReport`.
 
-If a new renderer wants information that doesn't fit the existing types,
+If a new renderer needs information that doesn't fit the existing types,
 the renderer should derive it locally, not push back into the core. If
-multiple renderers want the same derived information, _then_ it earns a
-place in `diff.ts`. Pause and confirm it's about drift, not about
-presentation.
+multiple renderers need the same derived information, _then_ it earns a
+place in `diff.ts`. Confirm it's about drift, not about presentation.
 
 ## How to do common things
 
@@ -166,8 +164,8 @@ produced, also update the golden fixture for that scenario.
 8. Update golden fixtures
 9. Tests for each of the above
 
-New categories cost a lot. The reason this list is long is to make you
-pause before adding one.
+New categories cost a lot. This list is long to make you pause before
+adding one.
 
 ## Commit conventions
 

package/README.md

@@ -26,8 +26,6 @@ directory. Both ship a versioned JSON summary you can gate CI on. The
 `drift` command also ships as a one-line GitHub Action with a sticky PR
 comment.
 
-Same model as Pact, for event architectures.
-
 ## What this package does NOT do
 
 To keep the scope tight:
@@ -78,25 +76,29 @@ autotel-eventcatalog generate \
 Re-runnable: existing catalog files are skipped, never overwritten. New
 events / services / channels from the snapshot are added on top.
 Producer (`sends`), consumer (`receives`), and channel routing edges
-are wired automatically. Pass `--dry-run` to preview, `--edges-only`
-to re-sync relationships without touching resource bodies, or
-`--version 2.0.0` to override the default version for newly created
-resources.
+are wired automatically.
+
+| Flag                 | Default | Use it when…                                                                                 |
+| -------------------- | ------- | -------------------------------------------------------------------------------------------- |
+| `--dry-run`          | off     | You want to preview the operations without touching disk.                                    |
+| `--edges-only`       | off     | The catalog already has resources; you just want producer/consumer/channel wiring re-synced. |
+| `--version <semver>` | `1.0.0` | Override the version assigned to newly created resources.                                    |
+| `--format json`      | `text`  | You want a machine-readable plan on stdout (the same shape as `--summary-output`).           |
 
 ### Schema sources
 
 When `generate` writes an event's `schema.json`, it picks the schema
 in this order:
 
-1. **Declared schema** — if the snapshot's event observation carries a
+1. **Declared schema**: if the snapshot's event observation carries a
    `schema.jsonSchema` (recorded by `ArchitectureSnapshotSubscriber`
    when a `track()` call was made through [`defineEvent`](#defineevent-zod-schemas-at-the-call-site)),
    that schema is used verbatim.
-2. **Inferred schema** — otherwise, the schema is inferred from observed
+2. **Inferred schema**: otherwise, the schema is inferred from observed
    `fieldStats` (runtime types per dotted path) as a fallback. This
    gets a new project from zero to a usable catalog on the first run;
    `defineEvent` is the path to a robust, single-source-of-truth
-   contract once you're ready.
+   contract when you adopt it.
 
 The choice is recorded in the operations log and the `generate-summary`
 JSON envelope as `schemaSource: 'declared' | 'inferred'`, so CI can
@@ -129,8 +131,8 @@ orderPlacedEvent.track({ orderId, customerId, totalCents, items });
 The schema is now the single source of truth: TypeScript catches drift
 at compile time, `safeParse` validates payloads at runtime, and
 `ArchitectureSnapshotSubscriber` carries the JSON Schema forward into
-the snapshot — so `generate` writes the _same_ schema your code
-enforces, no inference guesswork.
+the snapshot, so `generate` writes the _same_ schema your code
+enforces. No inference guesswork.
 
 ### From code
 
@@ -176,22 +178,22 @@ and the catalog's schemas align with what the code emits, running
 No drift detected. Catalog and runtime agree.
 ```
 
-Exit code 0, CI passes. That's the steady-state goal: the catalog and
-the running code make the same claims and the drift detector confirms
-it. Every additional finding is genuine signal of code-vs-catalog
-divergence — a new event added without a schema, a removed producer
-still listed, a schema field that no longer ships.
+Exit code 0, CI passes. That is the steady-state goal: the catalog and
+the running code make the same claims, and the drift detector confirms
+it. Each additional finding signals real code-vs-catalog divergence:
+a new event added without a schema, a removed producer still listed,
+a schema field that no longer ships.
 
 Type drift handles the JSON Schema ↔ JavaScript impedance mismatch
 deliberately: a declared `integer` accepts an observed `number` at the
-type level, then sample values are checked against `Number.isInteger`
+type level, then sample values are checked against `Number.isInteger`,
 so a runtime `1.5` against a declared `integer` still flags. No false
-positives, no swept-under-the-rug genuine signal.
+positives, no missed signal.
 
 The example app exercises both the happy path and the payment-failure
 path so the snapshot covers every documented event. Value drift would
 fire if, for instance, a `declineCode` outside the declared enum
-appeared at runtime — try replacing `card_declined` with something else
+appeared at runtime. Try replacing `card_declined` with something else
 in `build-snapshot.ts` and re-running to see it.
 
 ### As a GitHub Action
@@ -260,7 +262,7 @@ What lands on the PR:
 **How type and value drift work in practice.**
 
 1. `ArchitectureSnapshotSubscriber` records `fieldStats` per event during
-   a test run — for each dotted path it captures the runtime types it
+   a test run. For each dotted path it captures the runtime types it
    saw (`string`, `number`, `object`, …) and up to 20 primitive sample
    values. Verified by
    [`snapshot-fieldstats.integration.test.ts`](../../apps/example-eventcatalog/services/test/snapshot-fieldstats.integration.test.ts),
@@ -277,9 +279,9 @@ What lands on the PR:
    a `valueDrift` entry. Both feed `countDriftReport` and the markdown
    renderer.
 
-You can now pass first-class Zod metadata from `track()` call sites (via
-`defineEvent(...)` in `autotel`) so contracts can be declared in code and
-propagated into runtime snapshots.
+You can pass Zod metadata from `track()` call sites (via `defineEvent(...)`
+in `autotel`) so contracts are declared in code and propagated into runtime
+snapshots.
 
 ## Public JSON contract
 
@@ -303,35 +305,51 @@ changes them without bumping the spec version will fail CI.
 
 `drift --format <name>` dispatches through a small renderer registry. The
 built-ins are `markdown`, `terminal`, `json`, `eventcatalog-snapshot-diff`.
-The registry is exported
-from the library so applications and other tooling can add their own:
+You can plug in your own at runtime in two ways.
+
+**Programmatic** (when you import the library):
 
 ```typescript
-import { RENDERERS, type Renderer } from 'autotel-eventcatalog';
+import { registerRenderer, type Renderer } from 'autotel-eventcatalog';
 
 const sarifRenderer: Renderer = {
   name: 'sarif',
   description: 'Static Analysis Results Interchange Format',
   renderReport(report) {
-    /* ... */ return '';
+    /* return SARIF JSON */ return '';
   },
   renderDelta(delta) {
-    /* ... */ return '';
+    /* return SARIF JSON */ return '';
   },
 };
-// Programmatic consumers can plug it in. The CLI is also extensible via
-// a follow-up release that supports loading renderers from a config file.
+
+registerRenderer(sarifRenderer);
+```
+
+**From the CLI**, with `--register-renderer <module>` as a global option:
+
+```bash
+npx autotel-eventcatalog \
+  --register-renderer ./renderers/sarif.mjs \
+  drift --snapshot snap.json --catalog catalog --format sarif
 ```
 
+The loader expects the module to export either a `default` or a named
+`renderer` matching the `Renderer` shape. ESM (`.mjs`) or compiled
+JavaScript both work; TypeScript users compile to ESM first. Pass the
+flag more than once to load multiple renderers in the same invocation.
+The loader refuses to overwrite a built-in name (`markdown`, `terminal`,
+`json`, `eventcatalog-snapshot-diff`): pick a unique `name` for yours.
+
 The core diff and policy modules are renderer-agnostic; adding a new
-output target should never require touching `diff.ts` or `policy.ts`.
+output target never requires touching `diff.ts` or `policy.ts`.
 
 ## What writes to the catalog
 
 `drift` is **read-only**. It diffs the snapshot against the catalog and
 reports findings. It never modifies catalog files.
 
-`stamp` is the **write path**. By design, it injects a runtime evidence
+`stamp` is the **write path**. It injects a runtime evidence
 block into each event mdx between idempotent markers
 (`<!-- autotel:stamp-start -->` / `<!-- autotel:stamp-end -->`). Re-runs
 replace the content between the markers; nothing outside the markers is
@@ -345,10 +363,26 @@ need to gate on "did this PR forget to re-stamp?".
 ## Working example
 
 See [`apps/example-eventcatalog`](../../apps/example-eventcatalog) in the
-monorepo. It has a working e-commerce catalog and a snapshot. Running
-`pnpm catalog:drift` from that app prints a drift report that surfaces
-two findings, including a deliberately-introduced `personalization_seed`
-field that the schema does not declare.
+monorepo. It has a working e-commerce catalog and a committed snapshot.
+Running `pnpm catalog:drift` from that app prints
+
+```text
+No drift detected. Catalog and runtime agree.
+```
+
+That is the steady-state goal. Each additional finding from there signals
+real code-vs-catalog divergence. The same agreement is locked in as a
+vitest integration test, so a service that stops emitting a documented
+event or a catalog file that rots fails CI before the drift script runs.
+
+### Coverage caveat
+
+Drift only sees what `ArchitectureSnapshotSubscriber` recorded in the
+run that produced the snapshot. Events emitted only on paths your test
+suite does not exercise will not appear; documented events your test
+suite does not exercise will be flagged as `documentedButUnseen`. In
+practice this gives you **catalog honesty for what your test suite
+covers**, which is the property a green pipeline should buy you.
 
 ## Documentation
 
@@ -362,14 +396,12 @@ field that the schema does not declare.
 | Contribute to the package                              | [`CONTRIBUTING.md`](CONTRIBUTING.md)                 |
 | Validate the published JSON shapes                     | [`schemas/README.md`](schemas/README.md)             |
 
-## Used by
-
-_If you adopt this in production, open a PR adding your team to this
-section. We'd like to know who depends on the contract before shipping
-breaking changes, and seeing a name here helps future adopters gauge
-the project's maturity._
+## Related packages
 
-- _no public adopters yet; be the first_
+- [`autotel`](../autotel): OpenTelemetry instrumentation for Node.js.
+  The substrate every snapshot is built from.
+- [`autotel-subscribers/architecture-snapshot`](../autotel-subscribers):
+  produces the snapshot this package consumes.
 
 ## License