Skip to content

Add portable run receipts and deferred export - #73

Merged
bigboateng merged 4 commits into
mainfrom
feat/portable-run-receipts
Aug 20, 2026
Merged

Add portable run receipts and deferred export#73
bigboateng merged 4 commits into
mainfrom
feat/portable-run-receipts

Conversation

@bigboateng

@bigboateng bigboateng commented Aug 20, 2026

Copy link
Copy Markdown
Contributor

Why

Yield's append-only run journal contains the facts required for replay, but it
is not a portable or privacy-safe format for run health analysis, experiments,
or external reporting.

This change adds a deterministic observation layer without adding network work
to foreground skill execution.

What changes

  • Add the public yield.observation.v1 RunReceipt schema.
  • Deterministically project receipts from exact journal prefixes.
  • Store immutable, content-addressed receipts locally before a successful
    foreground return.
  • Record typed lifecycle, requirement, rejection, divergence, source, runtime,
    and experiment facts.
  • Add explicit commands to inspect and materialize receipts.
  • Add a deferred outbox with enqueue, delivery, status, and retry operations.
  • Add deterministic local health and experiment reports.
  • Extend cross-SDK conformance coverage for Go, TypeScript, Python, and Rust.

Receipt digests use canonical JSON. Reprojecting the same journal prefix
produces the same bytes and digest.

Safety and compatibility

The append-only run journal remains authoritative. Receipts and outbox state
are derived data and are never used during replay.

This change does not alter the yield.v1 SDK protocol or SDK APIs. Existing
journals are not rewritten, and legacy receipts omit facts that were not
recorded originally.

Foreground execution never performs export or network work. A sink failure
cannot change a skill result. Delivery is explicit, idempotent by receipt
digest, resumable after failure, and independent of delivery order.

Receipt objects are written with temporary files, synchronization, and atomic
installation. Per-digest locks prevent concurrent delivery of the same
receipt.

Privacy boundary

Receipts do not contain prompts, instructions, model responses, user answers,
command arguments, stdout, stderr, source contents, credentials, tokens,
environment values, or free-form failure details.

Raw values are represented by structured classifications or SHA-256 digests
where correlation is useful. Digests provide integrity and correlation, not
anonymization, and may still reveal low-entropy values through guessing.

Receipts contain only facts observed by the Yield supervisor. They do not
claim visibility into activity outside the Yield protocol.

CLI

The new surface includes:

  • yskill receipt
  • yskill receipt materialize
  • yskill outbox enqueue
  • yskill outbox deliver
  • yskill outbox status
  • yskill outbox retry
  • yskill report

Outbox delivery uses an external executable. Yield sends one receipt on
standard input and does not include a built-in service or network adapter.

Scope

Yield provides evidence and experiment primitives. It does not select
experiment winners or grant authority to rewrite, install, merge, release, or
activate a proposal.

Garbage collection, automatic background scheduling, first-party network
sinks, receipt signatures, and causal experiment evaluation remain out of
scope.

Verification

  • Repository-wide Go tests
  • Race tests for engine, receipt storage, run logs, and outbox concurrency
  • Go vet and repository formatting
  • Release and packaging controls
  • Four-language SDK conformance
  • Full example workflow suite
  • Ubuntu, macOS, and Windows CI

@bigboateng
bigboateng enabled auto-merge (squash) August 20, 2026 08:32
@bigboateng
bigboateng merged commit 7db2e53 into main Aug 20, 2026
12 checks passed
@bigboateng
bigboateng deleted the feat/portable-run-receipts branch August 20, 2026 08:43
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