starter

Rust Starter

This directory is a runnable Rust provider example for Observer.

Read ../HOWTO.md first if you want the full model, especially the determinism gate and the provider host contract.

It is intended to show the whole real process, not just the Rust authoring helpers in isolation:

• write ordinary Rust code under test
• author tests with describe!(...), test!(...), and expect(...)
• compile a provider host with Cargo
• inspect the raw provider list output
• derive canonical inventory with observer derive-inventory
• run a suite against that inventory
• verify canonical hashes and JSONL output

Contents:

• src/lib.rs: tiny Rust code under test
• src/bin/ledger-observer-host.rs: Observer-authored tests plus the host entrypoint
• observer.toml: provider resolution config
• tests.obs: simple-surface Observer suite
• Makefile: end-to-end commands
• tests.inv: derived inventory snapshot
• expected.inventory.sha256: expected canonical inventory hash
• expected.suite.sha256: expected canonical suite hash
• expected.default.jsonl: expected canonical report snapshot

Suggested reading order:

1. read src/lib.rs
2. read src/bin/ledger-observer-host.rs
3. run make list
4. run make inventory
5. inspect tests.inv
6. run make run
7. run make verify
8. compare this directory with ../starter-failure/

Key idea:

• the Rust tests are authored in Rust
• the provider host exposes them through the standard Observer provider protocol
• Observer derives inventory from that host output
• the suite runs against canonical inventory, not against ad hoc Cargo conventions

One detail is intentional and worth noticing:

• the suite uses one prefix: selector plus two exact-name selectors
• that means make run executes four cases even though the provider exports three tests
• the overlap is there on purpose so users can see both selector styles in one tiny example

Useful commands:

make list
make inventory
make host-run TARGET='ledger/rejects-overdraft'
make run
make report
make verify

The starter uses explicit stable ids for every exported test:

• ledger/applies-ordered-postings
• ledger/rejects-overdraft
• format/renders-balance-line

That is deliberate.

It keeps the end-to-end inventory and suite contract mechanically obvious.