@pleach/observe changelog

This page collects the site-content changelog entries that materially touched the @pleach/observe docs surface or named a @pleach/observe symbol. It is not the runtime changelog — the canonical record of @pleach/observe runtime behavior lives in the upstream package CHANGELOG.md and on npmjs.org/package/@pleach/observe.

See the combined site changelog at /docs/changelog/combined for the chronological unified view across every SKU.

Unreleased

Fixed

• The ObserveRow subset claim named a stale parent-schema version. @pleach/observe said ObserveRow is a strict subset of AuditableCall v13; the canonical row page says 19, verified against the upstream core package on 2026-07-02. Corrected here and on the two recipe pages that mirrored it.

• The page claimed the row does not carry "the fingerprint payload". Adding ObserveRow.fingerprint falsified the sentence directly beneath the shape. Reworded: the row carries its own narrower fp_v1: hash over {family, model, callClass, input}, computed by the SDK rather than lifted from the v13 record, while the full RoutingDecision, cascade walk history, and attestation hashes do stay undefined.

• Subpath count corrected from three to six. The API-surface table said "Three publishable subpaths"; the package exports six, adding @pleach/observe/integrations/{ledger-decorator,cost-emit,cost-event-emit} (withObserveEmit, createCostEmitter, projectGatewayCostEventToObserveRow).

• @pleach/observe surface reconciled with the shipped recorder (devharness FINDING 83–87). getRecorder() returns ObserveRecorder and throws if called before init (it never returns undefined); a second init throws (singleton-per-process, not a warn-and-return no-op); a redactor that throws is now documented as fail-closed — the SDK swallows, warns via [Observe:redactor-threw], and drops the row (the raw pre-redaction row is never written). The OTel destination Callout corrected to the real envelope: span name `<family>.<callClass>` (e.g. anthropic.synthesize) with gen_ai.* attributes plus pleach.observe.{turn_id,provider_id, cost_usd} / pleach.observe.tag.* (was the fictional pleach.audit.call / pleach.turn_id set). BUILT_IN_MATCHERS ships email + phone + SSN only (dropped the "credit card" claim). Checked against observe/src/recorder.ts + destinations/otel.ts

  • redact.ts.

• Schema codeRepository + sameAs for @pleach/observe corrected in the site's Organization + SoftwareApplication JSON-LD @graph (inlined in <head> on every page). Both fields now point at https://github.com/pleachhq/observe (was https://github.com/pleachhq, a leftover from when the SKU schemas were drafted against an upstream monorepo). Load-bearing because sameAs is the field AI search engines use for entity reconciliation across the npm ↔ GitHub ↔ docs boundary. See the combined view for the full cross-SKU pack.

Added

• Reading rows back — the read side was entirely undocumented. query(filter) on the Memory, Postgres, and Supabase destinations, with the two boundary rules a consumer needs before aggregating: the window is half-open [since, until) so adjacent windows tile without double-counting, and both bounds compare against startedAt rather than completedAt, so a long call is attributed to the window it began in. QueryNotSupportedError is thrown rather than returning [], because an empty array is indistinguishable from "no rows matched". Also the opt-in persistFingerprint column and isRecorderInitialized().

• ObserveRow.byokFailureChain and ObserveRow.fingerprint added to the documented row shape. byokFailureChain carries a four-character keyHint and never the key itself, so the row stays safe to ship to a dashboard your key-holders don't control. isCostAttributionKey / extractCostAttributionTags added to Cost attribution.

• @pleach/observe/testing — the destination conformance harness. assertObserveDestinationConformance throws on the first failed check; runObserveDestinationConformance returns a ConformanceReport for a suite that wants every failure in one pass. The ObserveDestination interface constrains shape; the harness constrains behaviour. The API-surface table moves from six subpaths to seven.

• @pleach/observe — new top-level page for the brownfield audit-row SDK. Documents the five-entry facade surface (init, startTurn, flush, recordCall, subagent, getRecorder), the ObserveRow shape as a strict subset of the AuditableCall v7 schema, the four destinations (Postgres, Supabase, OTel, Memory) on the ./destinations subpath, the custom-destination interface (write + optional flush), the hookable-vs-not-hookable split against the runtime, and composition with @pleach/core when both surfaces run in the same process. Phase 0 status callout makes the design-target stance explicit — @pleach/observe@0.1.0-alpha.0 is scoped, not yet on npm; Phase 1 publish is the next cut.

• Per-recipe deep-dive pages — BYOK observability, observableChatbot, instrumentedCodingAgent, and enterpriseAgent all compose @pleach/observe.

• Packages — added the @pleach/observe matrix row in the Reserved tier with the row note 0.0.1 · Reserved · 0.1.0-alpha.0 scoped, and reworked the Reserved bullet to distinguish @pleach/trust-pack (placeholder, no contract published) from @pleach/observe (Phase 0 contract locked, scoped for Phase 1 under FSL-1.1-Apache-2.0).

• Homepage — new "Keep your stack" block makes @pleach/observe a top-level surface on the marketing home. The brownfield path now sits between "Should you stay where you are?" and "Already paying the lab": wrap an existing Vercel AI SDK / LangChain / hand-rolled loop in ~15 lines. Its diagram (components/observe-brownfield-diagram.tsx) shows the init + per-turn recorder + destination-plug hook fanning out to the four destinations — postgres(), supabase(), otel(), memory() — over the BYOK code shape (init, startTurn, recordCall, end). The ObserveRow-is-a-strict-subset-of-AuditableCall runway claim is the figure caption. Cross-links adoption paths and BYOK observability. Block states @pleach/observe is in alpha; the SDK layer stays free.

Changed

• The proxy comparison's "Adoption cost" row now credits the brownfield SDK. /docs/comparison read "model your agent inside the runtime" against a governed proxy's one-URL swap — accurate before @pleach/observe shipped, stale after. The cell now reads ~15 LoC around the loop you already run, and a new paragraph bounds the claim: the SDK closes the distance on the audit row, not on family-lock, replay, or checkpoints, which need the runtime to drive the loop.

• Pricing rewrites — audit rows ship where you point them — Postgres, Supabase, OTel collector into Datadog / Honeycomb / Grafana / your existing OTLP backend, or a custom destination; the enterprise integration is the bridge from @pleach/observe into the review surface your team already runs.

• Pricing — "Hosted Observe at enterprise scope" named as a paid enterprise product alongside Hosted Gateway and compliance attestation services.