Skip to content

Publish first-class observation APIs across all SDKs - #74

Merged
bigboateng merged 3 commits into
mainfrom
public-observation-api
Aug 20, 2026
Merged

Publish first-class observation APIs across all SDKs#74
bigboateng merged 3 commits into
mainfrom
public-observation-api

Conversation

@bigboateng

@bigboateng bigboateng commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

Why

Yield already projects privacy-safe run receipts, stores them durably, and
builds local reports. Those capabilities were internal to the CLI, and the
language-neutral receipt schema did not yet have programmatic readers in every
supported SDK.

What changed

  • publish github.com/operatorstack/yield/observation with the existing
    yield.observation.v1 receipt types
  • add pure Go Project, strict Parse, CanonicalBytes, and
    VerifyCanonical APIs
  • publish the concrete Go receipt Store and deterministic BuildReport
    aggregation
  • refactor the supervisor, CLI, prune protection, and existing outbox consumer
    onto the public Go package
  • add strict, schema-bound receipt readers and digest verification to the
    TypeScript, Python, and Rust SDKs
  • verify every reader against one Go-generated canonical fixture
  • document the public APIs and add a minor Changeset

The Go supervisor remains the only component that projects receipts from the
authoritative append-only run journal. TypeScript, Python, and Rust consume the
same portable IR: they validate its closed schema, reproduce Yield's
integer-only RFC 8785 canonicalization profile, and verify the embedded SHA-256
digest. They do not read or mutate journals, write receipt storage, or
participate in replay.

Compatibility and boundaries

This does not change yield.v1, yield.observation.v1, canonical receipt
bytes, receipt digests, storage paths, CLI behavior, replay behavior, or outbox
delivery. Existing v0.6 journals remain inputs and are never rewritten.

The append-only journal remains authoritative. Projection is read-only; local
receipt persistence remains isolated in observation.Store; journal mutation
remains in the supervisor; and replay still has no receipt or sink dependency.
Generic sink delivery and pure SDK evaluators remain separate follow-up
changes.

Verification

  • npm run format:check
  • go vet ./...
  • go test -count=1 ./...
  • go build ./...
  • go test -race ./observation ./internal/runlog ./internal/engine ./internal/outbox
  • TypeScript tests, build, and packed-package import smoke test
  • Python SDK tests
  • Rust SDK and documentation tests
  • npm run test:release
  • node scripts/check-release-control.mjs

Tests cover deterministic projection, schema alignment, legacy journals,
privacy exclusions, malformed and partial prefixes, strict canonical parsing,
digest mismatch, durable store convergence, engine materialization, outbox
compatibility, external Go package use, and exact cross-language parsing of the
shared canonical fixture.

@bigboateng bigboateng changed the title Publish first-class Go observation APIs Publish first-class observation APIs across all SDKs Aug 20, 2026
@bigboateng
bigboateng merged commit df863d7 into main Aug 20, 2026
12 checks passed
@bigboateng
bigboateng deleted the public-observation-api branch August 20, 2026 13:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant