Skip to content

README.md

Latest commit

 

History

History
170 lines (110 loc) · 5.96 KB

README.md

File metadata and controls

170 lines (110 loc) · 5.96 KB

Examples And Operational Structure

This directory is not just a bag of demos.

It exists to teach the structural model Observer wants teams to adopt.

The important idea is simple:

  • examples show the pattern in small, copyable form
  • a real product owns the same pattern in its maintained repo tree

That distinction is what gives the product layer its operational value.

The Aha

At first glance an Observer product can look almost boring:

  • one product.json
  • a few stage directories
  • some suite files
  • some helper scripts
  • some checked-in expected artifacts

But that boring shape is the point.

The structure is doing real work:

  • the product declares what must pass together
  • each stage owns one verification concern
  • each stage keeps its own local suite inputs and runtime state
  • generated state stays local under .observer/
  • the final product verdict is derived instead of hand-waved

That is how questions that used to live in scattered shell glue become product questions:

  • is the distribution artifact healthy
  • do all maintained libraries still compile
  • do required docs still exist
  • does the public starter path still work
  • do the core conformance promises still hold

Without this structure, teams usually write scripts forever, forget to run them, and slowly lose track of which checks actually define product health.

With this structure, those checks become declared stages in one maintained contract.

The Two Levels

Observer now has both levels in this repository.

Level 1: teaching example

See product-certify.

That example is intentionally small.

It teaches the product layer without forcing you to read the whole repository.

Use it when you want to understand:

  • what a product definition looks like
  • how stage-local suite directories are laid out
  • where product outputs land
  • how stage child reports relate to the final product report

Level 1.5: topology study

See portfolio-topology.

That example is intentionally larger and more opinionated.

Use it when you want to study:

  • how several internal proof products compose into public deliverables
  • how observer_product reuse changes the authored product set
  • how TOML subproduct stanzas scale into a portfolio contract
  • where the current operational tradeoffs still are for very large repos

Level 2: maintained product-owned certification

See the repo-owned contract at ../product.json and the maintained stage tree at ../tests.

That is not an example.

That is Observer using the same structure on itself.

Use that layout as the model once you move from learning to real adoption.

Recommended Layout

For a real product, the recommended shape is:

my-product/
  product.json
  tests/
    stage-a/
      README.md
      observer/
        tests.obs
        tests.inv          # when the stage is inventory-driven
        observer.toml      # when the stage resolves a provider host
        corpus/            # when the stage is workflow-shaped
        bin/               # stage-local helper tools
        expected.*         # checked-in goldens and hashes
    stage-b/
      ...

Operational rules:

  • keep one stage per product concern
  • keep stage-local helper tools with the stage that owns them
  • keep checked-in expected artifacts with the stage that verifies them
  • keep generated runtime state in stage-local .observer/
  • keep the root product output in repo-root .observer/
  • prefer explicit contracts over hidden runner behavior

How To Think About Boundaries

A useful rule is:

  • if it teaches the pattern, it belongs in examples/
  • if it certifies the maintained product, it belongs in the product-owned tests/ tree

Examples are for comprehension.

The maintained product tree is for operational truth.

Do not let those collapse into each other.

If everything stays in examples, the repo never quite admits what it really depends on.

If everything becomes product-owned immediately, the learning path gets too heavy.

The right model is to keep both, with a clear handoff from one to the other.

Additional Pattern Example

See python-proxy-pattern.

That example exists to teach one of the most important adoption patterns:

  • the host language is often the authoring surface, not the semantic subject under test
  • one coarse wrapper script is usually the wrong verification unit
  • granular proxy-language targets are usually the better shape

That pattern is now also productized in the CLI through:

  • observer new shell-proxy <path> --proxy <python|javascript> --subject-family <rust|c|python|generic>

It is organized as three copy-pasteable levels:

  • single-test-strategy/: one target when there is truly one externally meaningful proof unit
  • multi-test-strategy/: several granular targets for one product surface
  • staged-product/: a GLC-shaped decomposition into unit, golden, and coverage/product stages

Reading Order

If you are new to this structure, read in this order:

  1. product-certify/README.md for the minimal product-layer shape.
  2. portfolio-topology/README.md for the large authored topology and proof-product layering.
  3. python-proxy-pattern/README.md for the proxy-language verification teaching path.
  4. ../tests/README.md for the maintained repo-owned certification tree.
  5. ../product.json to see the real product contract.
  6. One real stage such as ../tests/cli-conformance/observer/README.md or ../tests/rust-starter/observer/README.md.

That sequence usually gives the intended Aha moment: the example teaches the grammar, and the maintained product tree shows the operational payoff.

If you want the quick path, use the example tree to understand the pattern, then use observer new shell-proxy ... to generate the starting structure directly.