README.md

Python Proxy-Language Pattern

This example tree teaches the pattern where Python is used as the authoring surface for verification, not as the thing being verified.

This tree is the semantic basis for the CLI scaffold shape observer new shell-proxy ... --proxy python ....

The newer command surface makes two layers explicit:

1. the shell proxy language
2. the subject family under test

This example is about the first of those proxy backends: Python.

That is usually the right way to use Observer with Python.

The anti-pattern is:

• write one large Python wrapper script
• expose that wrapper as one Observer target
• treat wrapper exit status as the whole proof

The preferred pattern is:

• write Python tests that each express one real product contract
• expose those tests through the Observer Python integration
• let inventory, suites, reports, compare artifacts, and product stages operate on those granular units

In other words:

• Python is the shell proxy
• the subject under test may be Rust, C, Python, or a broader product surface
• Observer should see real proof units, not one Python orchestration blob

This tree is organized as three levels.

1. Single-Test Strategy

See single-test-strategy.

Use this when there is truly one externally meaningful proof unit.

This is not a wrapper blob. It is a single, explicit contract, such as:

• compiler/emits-canonical-json

That target still names the real thing being verified.

2. Multi-Test Strategy

See multi-test-strategy.

Use this when one product surface can and should be decomposed into several independent proofs.

This is the usual sweet spot:

• one target for canonical emission
• one target for invalid input rejection
• one target for package metadata
• one target for another externally visible behavior

3. Staged Product Strategy

See staged-product.

This is the GLC-shaped decomposition in teaching form.

It splits the verification problem into explicit stages:

• unit: provider-backed semantic checks
• golden: corpus-driven artifact emission and validation
• dict: cross-case coverage/consistency checks over generated outputs

Then it composes those stages with one product.json contract.

Recommended Reading Order

1. single-test-strategy/README.md
2. multi-test-strategy/README.md
3. staged-product/README.md

That order mirrors the intended mental model:

• one real proof unit
• several real proof units
• one maintained product contract built from several proof areas

If you already understand that model and just want a generated starting tree, use:

observer new shell-proxy demo --proxy python --subject-family rust
observer new shell-proxy demo --proxy python --subject-family c
observer new shell-proxy demo --proxy python --subject-family rust --strategy staged-product