autotel-pact 0.2.0

package/dist/types-BHGiwqcp.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Kind of contract interaction observed.
+ */
+type PactKind = 'message' | 'http';
+type PactOutcome = 'passed' | 'failed';
+type LedgerSource = 'test' | 'production';
+type LedgerRole = 'consumer' | 'provider';
+declare const LEDGER_ENTRY_SPEC = "autotel-pact-ledger-entry/v0.2.0";
+declare const AUDIT_MATRIX_SPEC = "autotel-pact-audit-matrix/v0.2.0";
+/**
+ * Metadata about a single Pact interaction, derived from the reified message
+ * plus the consumer/provider config. Stamped onto the span and the ledger entry.
+ */
+interface PactInteractionMeta {
+    consumer: string;
+    provider: string;
+    description: string;
+    states: string[];
+    kind: PactKind;
+    interactionId?: string;
+}
+/**
+ * Per-interaction ledger evidence (consumer exercise, provider verify, or production tag).
+ */
+interface InteractionLedgerEntry {
+    type?: 'interaction';
+    spec: typeof LEDGER_ENTRY_SPEC;
+    consumer: string;
+    provider: string;
+    interaction: string;
+    interaction_id?: string;
+    states: string[];
+    kind: PactKind;
+    outcome: PactOutcome;
+    source: LedgerSource;
+    role: LedgerRole;
+    duration_ms: number;
+    observed_at: string;
+    trace_id?: string;
+    span_id?: string;
+    run_id?: string;
+    git_sha?: string;
+    error?: string;
+}
+/**
+ * Run-level provider verification failure — does not imply per-interaction outcomes.
+ */
+interface ProviderVerificationRunEntry {
+    type: 'provider_verification_run';
+    spec: typeof LEDGER_ENTRY_SPEC;
+    consumer: string;
+    provider: string;
+    outcome: 'failed';
+    source: LedgerSource;
+    role: 'provider';
+    observed_at: string;
+    error: string;
+    run_id?: string;
+    git_sha?: string;
+    trace_id?: string;
+    span_id?: string;
+}
+type LedgerRecord = InteractionLedgerEntry | ProviderVerificationRunEntry;
+declare function isInteractionLedgerEntry(entry: LedgerRecord): entry is InteractionLedgerEntry;
+declare function isProviderVerificationRun(entry: LedgerRecord): entry is ProviderVerificationRunEntry;
+/**
+ * Shape of a Pact contract file on disk (subset we read).
+ */
+interface PactFile {
+    consumer: {
+        name: string;
+    };
+    provider: {
+        name: string;
+    };
+    messages?: Array<{
+        description: string;
+        providerStates?: Array<{
+            name: string;
+        }>;
+        metadata?: Record<string, unknown>;
+    }>;
+    interactions?: Array<{
+        description: string;
+        providerStates?: Array<{
+            name: string;
+        }>;
+        metadata?: Record<string, unknown>;
+    }>;
+}
+interface BrokerVerification {
+    consumer: string;
+    provider: string;
+    success: boolean;
+    verifiedAt?: string;
+    /**
+     * Populated when the broker could not be reached or returned a non-2xx
+     * response. Distinguishes "broker said the pact is not verified" (no error)
+     * from "we could not determine verification status" (error set).
+     */
+    error?: string;
+}
+/**
+ * One row in the audit matrix.
+ */
+interface AuditRow {
+    consumer: string;
+    provider: string;
+    interaction: string;
+    interaction_id?: string;
+    kind: PactKind;
+    contracted: boolean;
+    /** Any interaction-level ledger hit in the window (test or production). */
+    observed: boolean;
+    test_seen: boolean;
+    prod_seen: boolean;
+    provider_verified: boolean;
+    broker_verified: boolean;
+    broker_verified_at?: string;
+    /** Set when the broker check failed (network error, non-2xx, parse error). */
+    broker_error?: string;
+    last_observed_at?: string;
+    last_outcome?: PactOutcome;
+}
+interface AuditMatrix {
+    spec: typeof AUDIT_MATRIX_SPEC;
+    rows: AuditRow[];
+    counts: {
+        total: number;
+        /** Any contracted row. */
+        contracted: number;
+        /** Any row with test_seen OR prod_seen. */
+        observed: number;
+        /** Contracted AND seen in a consumer test. */
+        contracted_and_test_seen: number;
+        /** Contracted but not seen in a consumer test (stale confidence). */
+        contracted_not_test_seen: number;
+        /** Seen (test or production) without a matching contract (ungoverned flow). */
+        test_or_prod_seen_not_contracted: number;
+        test_seen: number;
+        prod_seen: number;
+        provider_verified: number;
+        broker_verified: number;
+    };
+    window_days: number;
+    generated_at: string;
+    verification_failures?: ProviderVerificationRunEntry[];
+}
+interface PactInteractionKey {
+    consumer: string;
+    provider: string;
+    interaction: string;
+    kind: PactKind;
+    interactionId?: string;
+}
+
+export { AUDIT_MATRIX_SPEC as A, type BrokerVerification as B, type InteractionLedgerEntry as I, LEDGER_ENTRY_SPEC as L, type PactInteractionMeta as P, type PactOutcome as a, type PactFile as b, type PactInteractionKey as c, type AuditMatrix as d, type AuditRow as e, type LedgerRecord as f, type LedgerRole as g, type LedgerSource as h, type PactKind as i, type ProviderVerificationRunEntry as j, isInteractionLedgerEntry as k, isProviderVerificationRun as l };

package/package.json

@@ -0,0 +1,108 @@
+{
+  "name": "autotel-pact",
+  "version": "0.2.0",
+  "description": "Runtime evidence for Pact contracts — autotel bridge that records which contract interactions were actually exercised, and audits 'contracted but never observed'.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": [
+    "./dist/auto-wrap.js",
+    "./dist/auto-wrap.cjs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./audit": {
+      "types": "./dist/audit.d.ts",
+      "import": "./dist/audit.js",
+      "require": "./dist/audit.cjs"
+    },
+    "./auto-wrap": {
+      "types": "./dist/auto-wrap.d.ts",
+      "import": "./dist/auto-wrap.js",
+      "require": "./dist/auto-wrap.cjs"
+    },
+    "./provider": {
+      "types": "./dist/provider.d.ts",
+      "import": "./dist/provider.js",
+      "require": "./dist/provider.cjs"
+    },
+    "./broker": {
+      "types": "./dist/broker.d.ts",
+      "import": "./dist/broker.js",
+      "require": "./dist/broker.cjs"
+    },
+    "./processor": {
+      "types": "./dist/processor.d.ts",
+      "import": "./dist/processor.js",
+      "require": "./dist/processor.cjs"
+    },
+    "./tag": {
+      "types": "./dist/tag.d.ts",
+      "import": "./dist/tag.js",
+      "require": "./dist/tag.cjs"
+    },
+    "./schemas/*.json": "./schemas/*.json"
+  },
+  "bin": {
+    "autotel-pact": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "schemas",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rimraf dist"
+  },
+  "keywords": [
+    "autotel",
+    "pact",
+    "contract-testing",
+    "opentelemetry",
+    "observability",
+    "runtime-evidence",
+    "pact-message",
+    "async"
+  ],
+  "author": "Jag Reehal <jag@jagreehal.com> (https://jagreehal.com)",
+  "license": "MIT",
+  "peerDependencies": {
+    "@pact-foundation/pact": ">=16",
+    "autotel": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@pact-foundation/pact": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@pact-foundation/pact": "^16.5.0",
+    "@types/node": "^25.9.1",
+    "autotel": "workspace:*",
+    "rimraf": "^6.1.3",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.7"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jagreehal/autotel",
+    "directory": "packages/autotel-pact"
+  },
+  "bugs": {
+    "url": "https://github.com/jagreehal/autotel/issues"
+  },
+  "homepage": "https://github.com/jagreehal/autotel/tree/main/packages/autotel-pact#readme"
+}

package/schemas/README.md

@@ -0,0 +1,24 @@
+# autotel-pact JSON Schemas
+
+The **public contract** for `autotel-pact`'s persisted artifacts.
+
+| File | Emitted by | `spec:` value |
+|------|------------|---------------|
+| [`ledger-entry-v0.2.0.json`](./ledger-entry-v0.2.0.json) | Wrappers, processor, provider verify | `autotel-pact-ledger-entry/v0.2.0` |
+| [`audit-matrix-v0.2.0.json`](./audit-matrix-v0.2.0.json) | `autotel-pact audit --json` | `autotel-pact-audit-matrix/v0.2.0` |
+
+v0.2 covers:
+
+- `source` (`test` | `production`) and `role` (`consumer` | `provider`) on every interaction row.
+- A discriminated `type: 'provider_verification_run'` record for run-level provider failures that cannot be attributed to a single interaction.
+- Renamed audit-matrix count fields: `contracted_and_test_seen`, `contracted_not_test_seen`, `test_or_prod_seen_not_contracted`.
+
+## Version policy
+
+Minor bumps add optional fields; major bumps break shape. The `spec` field is the gate against unknown majors.
+
+```ts
+import { LEDGER_ENTRY_SPEC, AUDIT_MATRIX_SPEC } from 'autotel-pact';
+```
+
+Readers reject unknown `spec` values. There is no legacy migration path; v0.1 was never released.

package/schemas/audit-matrix-v0.2.0.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://autotel.dev/schemas/autotel-pact/audit-matrix-v0.2.0.json",
+  "title": "autotel-pact audit matrix",
+  "description": "Output of `autotel-pact audit --json`.",
+  "type": "object",
+  "required": ["spec", "rows", "counts", "window_days", "generated_at"],
+  "properties": {
+    "spec": { "const": "autotel-pact-audit-matrix/v0.2.0" },
+    "window_days": { "type": "integer", "minimum": 1 },
+    "generated_at": { "type": "string", "format": "date-time" },
+    "verification_failures": {
+      "type": "array",
+      "items": { "$ref": "ledger-entry-v0.2.0.json#/$defs/provider_verification_run" }
+    },
+    "counts": {
+      "type": "object",
+      "required": [
+        "total",
+        "contracted",
+        "observed",
+        "contracted_and_test_seen",
+        "contracted_not_test_seen",
+        "test_or_prod_seen_not_contracted",
+        "test_seen",
+        "prod_seen",
+        "provider_verified",
+        "broker_verified"
+      ],
+      "properties": {
+        "total": { "type": "integer" },
+        "contracted": { "type": "integer" },
+        "observed": { "type": "integer" },
+        "contracted_and_test_seen": { "type": "integer" },
+        "contracted_not_test_seen": { "type": "integer" },
+        "test_or_prod_seen_not_contracted": { "type": "integer" },
+        "test_seen": { "type": "integer" },
+        "prod_seen": { "type": "integer" },
+        "provider_verified": { "type": "integer" },
+        "broker_verified": { "type": "integer" }
+      }
+    },
+    "rows": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "consumer",
+          "provider",
+          "interaction",
+          "kind",
+          "contracted",
+          "observed",
+          "test_seen",
+          "prod_seen",
+          "provider_verified",
+          "broker_verified"
+        ],
+        "properties": {
+          "consumer": { "type": "string" },
+          "provider": { "type": "string" },
+          "interaction": { "type": "string" },
+          "interaction_id": { "type": "string" },
+          "kind": { "enum": ["message", "http"] },
+          "contracted": { "type": "boolean" },
+          "observed": { "type": "boolean" },
+          "test_seen": { "type": "boolean" },
+          "prod_seen": { "type": "boolean" },
+          "provider_verified": { "type": "boolean" },
+          "broker_verified": { "type": "boolean" },
+          "broker_verified_at": { "type": "string" },
+          "last_observed_at": { "type": "string" },
+          "last_outcome": { "enum": ["passed", "failed"] }
+        }
+      }
+    }
+  }
+}

package/schemas/ledger-entry-v0.2.0.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://autotel.dev/schemas/autotel-pact/ledger-entry-v0.2.0.json",
+  "title": "autotel-pact ledger entry",
+  "description": "JSONL ledger row: interaction observation or provider verification run failure.",
+  "oneOf": [
+    { "$ref": "#/$defs/interaction" },
+    { "$ref": "#/$defs/provider_verification_run" }
+  ],
+  "$defs": {
+    "interaction": {
+      "type": "object",
+      "required": [
+        "spec",
+        "consumer",
+        "provider",
+        "interaction",
+        "states",
+        "kind",
+        "source",
+        "role",
+        "outcome",
+        "duration_ms",
+        "observed_at"
+      ],
+      "properties": {
+        "type": { "const": "interaction" },
+        "spec": { "const": "autotel-pact-ledger-entry/v0.2.0" },
+        "consumer": { "type": "string" },
+        "provider": { "type": "string" },
+        "interaction": { "type": "string" },
+        "interaction_id": { "type": "string", "minLength": 1 },
+        "states": { "type": "array", "items": { "type": "string" } },
+        "kind": { "enum": ["message", "http"] },
+        "source": { "enum": ["test", "production"] },
+        "role": { "enum": ["consumer", "provider"] },
+        "outcome": { "enum": ["passed", "failed"] },
+        "duration_ms": { "type": "number", "minimum": 0 },
+        "observed_at": { "type": "string", "format": "date-time" },
+        "trace_id": { "type": "string" },
+        "span_id": { "type": "string" },
+        "run_id": { "type": "string" },
+        "git_sha": { "type": "string" },
+        "error": { "type": "string" }
+      }
+    },
+    "provider_verification_run": {
+      "type": "object",
+      "required": [
+        "type",
+        "spec",
+        "consumer",
+        "provider",
+        "source",
+        "role",
+        "outcome",
+        "observed_at",
+        "error"
+      ],
+      "properties": {
+        "type": { "const": "provider_verification_run" },
+        "spec": { "const": "autotel-pact-ledger-entry/v0.2.0" },
+        "consumer": { "type": "string" },
+        "provider": { "type": "string" },
+        "source": { "enum": ["test", "production"] },
+        "role": { "const": "provider" },
+        "outcome": { "const": "failed" },
+        "observed_at": { "type": "string", "format": "date-time" },
+        "error": { "type": "string" },
+        "run_id": { "type": "string" },
+        "git_sha": { "type": "string" },
+        "trace_id": { "type": "string" },
+        "span_id": { "type": "string" }
+      }
+    }
+  }
+}

package/src/attrs.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { buildPactAttributes, outcomeAttribute, PACT_ATTRS } from './attrs.js';
+import type { PactInteractionMeta } from './types.js';
+
+const meta: PactInteractionMeta = {
+  consumer: 'OrderShipper',
+  provider: 'OrderService',
+  description: 'an OrderCreated event',
+  states: ['an order exists'],
+  kind: 'message',
+};
+
+describe('buildPactAttributes', () => {
+  it('emits the canonical pact.* attribute set', () => {
+    const attrs = buildPactAttributes(meta);
+    expect(attrs[PACT_ATTRS.CONSUMER]).toBe('OrderShipper');
+    expect(attrs[PACT_ATTRS.PROVIDER]).toBe('OrderService');
+    expect(attrs[PACT_ATTRS.KIND]).toBe('message');
+    expect(attrs[PACT_ATTRS.INTERACTION_DESCRIPTION]).toBe('an OrderCreated event');
+    expect(attrs[PACT_ATTRS.INTERACTION_STATES]).toEqual(['an order exists']);
+    expect(attrs[PACT_ATTRS.CONTRACT_FILE]).toBeUndefined();
+  });
+
+  it('includes pact.contract.file when supplied', () => {
+    const attrs = buildPactAttributes(meta, { contractFile: 'pacts/OrderShipper-OrderService.json' });
+    expect(attrs[PACT_ATTRS.CONTRACT_FILE]).toBe('pacts/OrderShipper-OrderService.json');
+  });
+});
+
+describe('outcomeAttribute', () => {
+  it('returns a single-key record for the outcome', () => {
+    expect(outcomeAttribute('passed')).toEqual({ [PACT_ATTRS.OUTCOME]: 'passed' });
+    expect(outcomeAttribute('failed')).toEqual({ [PACT_ATTRS.OUTCOME]: 'failed' });
+  });
+});

package/src/attrs.ts

@@ -0,0 +1,53 @@
+import type { PactInteractionMeta, PactOutcome } from './types.js';
+
+/**
+ * Attribute keys for Pact interactions. Centralised so the namespace is
+ * a single source of truth and is forward-compatible with eventual OTel
+ * semantic conventions.
+ */
+export const PACT_ATTRS = {
+  CONSUMER: 'pact.consumer',
+  PROVIDER: 'pact.provider',
+  KIND: 'pact.kind',
+  INTERACTION_DESCRIPTION: 'pact.interaction.description',
+  INTERACTION_ID: 'pact.interaction.id',
+  INTERACTION_STATES: 'pact.interaction.states',
+  CONTRACT_FILE: 'pact.contract.file',
+  OUTCOME: 'pact.outcome',
+} as const;
+
+export type PactAttributeKey = (typeof PACT_ATTRS)[keyof typeof PACT_ATTRS];
+
+/**
+ * Build the set of attributes to stamp on a span when an interaction is
+ * about to be exercised. `outcome` is added later by the wrapper.
+ */
+export function buildPactAttributes(
+  meta: PactInteractionMeta,
+  opts: { contractFile?: string } = {},
+): Record<string, string | string[]> {
+  const attrs: Record<string, string | string[]> = {
+    [PACT_ATTRS.CONSUMER]: meta.consumer,
+    [PACT_ATTRS.PROVIDER]: meta.provider,
+    [PACT_ATTRS.KIND]: meta.kind,
+    [PACT_ATTRS.INTERACTION_DESCRIPTION]: meta.description,
+    [PACT_ATTRS.INTERACTION_STATES]: meta.states,
+  };
+  if (opts.contractFile) {
+    attrs[PACT_ATTRS.CONTRACT_FILE] = opts.contractFile;
+  }
+  if (meta.interactionId) {
+    attrs[PACT_ATTRS.INTERACTION_ID] = meta.interactionId;
+  }
+  return attrs;
+}
+
+/**
+ * Helper that returns just the outcome attribute — stamped after the
+ * handler resolves or rejects.
+ */
+export function outcomeAttribute(
+  outcome: PactOutcome,
+): Record<string, string> {
+  return { [PACT_ATTRS.OUTCOME]: outcome };
+}