Getting Started

Trezko Technical Documentation

Trezko consists of two decoupled components: a stateless edge collector/CLI that extracts structural ASTs from JSON payloads, and a contract registry that tracks versioned schemas across environments.

1. Compare two local JSON snapshots

Run the standalone CLI with Node.js 18+ (no account or API key required for local diffing):

Terminal

npx @trezko/cli diff ./fixtures/v1.order.json ./fixtures/v2.order.json --strict

2. Generate JSON Schema & TypeScript definitions

Terminal

npx @trezko/cli infer ./fixtures/v2.order.json \
  --schema-out ./contracts/order.schema.json \
  --ts-out ./src/contracts/order.d.ts

Configuration (`trezko.yaml`)

Commit a `trezko.yaml` file at the root of your service repository to standardize payload budgets and drift policies across local runs and CI pipelines.

trezko.yaml

version: 1
service: checkout-core
environment_baseline: production

policies:
  fail_on:
    - FIELD_REMOVED
    - TYPE_MISMATCH
    - SUSPICIOUS_LEAK_KEY
  warn_on:
    - NULLABILITY_DRIFT
  budgets:
    max_wire_bytes: 16384
    max_bloat_growth_pct: 15
    deny_key_patterns:
      - "^debug_"
      - "_sql$"
      - "_dump$"

redact:
  strip_all_scalars: true
  preserve_enum_allowlist:
    - "currency"
    - "status"

Rule Matrix & CLI Exit Codes

Deterministic exit codes allow shell scripts and CI runners to distinguish breaking contract failures from advisory bloat warnings.

Rule ID	Default Severity	Exit Code	Trigger Condition
`FIELD_REMOVED`	BREAKING	`2`	Key present in baseline contract is absent in candidate payload.
`TYPE_MISMATCH`	BREAKING	`2`	Primitive or structural type changed (e.g., `number` → `string`).
`NULLABILITY_DRIFT`	WARN	`0` (`1` w/ `--strict`)	Previously non-null scalar returned `null`.
`SUSPICIOUS_LEAK_KEY`	WARN	`2` (if configured)	Key matches internal debug, stack dump, or raw SQL naming patterns.
`FIELD_ADDED`	SAFE	`0`	Additive key introduced without mutating existing sibling fields.

GitHub Actions PR Gate

Post automated contract compatibility summaries directly on pull requests whenever route handlers or serializers change.

.github/workflows/trezko.yml

- name: Trezko Contract Check
  run: |
    npx @trezko/cli verify \
      --config ./trezko.yaml \
      --candidate ./tmp/integration-responses.jsonl \
      --comment-pr

Cloud Run & Kubernetes Sidecar Collector

For live traffic telemetry, deploy `ghcr.io/trezko/edge-agent:0.4.2` alongside your API container. Sampling defaults to 1% of 2xx/4xx responses with bounded ring-buffer memory (32 MiB hard cap).

POST https://ingest.nerbo.xyz/v1/structural-ast

{
  "service": "checkout-core",
  "route": "POST /v2/orders",
  "sample_rate": 0.01,
  "wire_bytes": 1420,
  "ast_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "nodes": [
    { "path": "$.order.id", "type": "string", "byte_len": 12 },
    { "path": "$.order.total_cents", "type": "integer", "byte_len": 5 }
  ]
}

Zero-PII Security Model

Traditional API observability tools ship full HTTP bodies to third-party SaaS buckets, creating GDPR/HIPAA liability and secret-leakage risk. Trezko parses JSON tokens via a streaming lexer inside your network boundary and immediately discards scalar values—retaining only key names, JSON types, null counts, and byte lengths.