Skip to content

OBSERVER.md

Latest commit

 

History

History
140 lines (101 loc) · 7.08 KB

OBSERVER.md

File metadata and controls

140 lines (101 loc) · 7.08 KB

Observer Specification Set

Status

This repository now treats Observer as a specification set, not a single mixed draft.

The current material is a coherent v0 draft intended to turn the original seed idea into a deliverable platform shape.

Platform Definition

Observer is an opinionated verification platform.

It is universal in a constrained, deliberate sense:

  • tests from multiple ecosystems can register through provider libraries
  • discovery lowers into one canonical inventory contract
  • suites select from inventory and declare expectations
  • the runner executes those suites with deterministic ordering and structured reporting

Observer is not trying to be every testing tool at once. It defines one strong verification model and expects integrations to map into that model.

That model is shared at the semantic boundary, not necessarily at the author-facing syntax boundary. Different language integrations may expose different test-authoring surfaces as long as they lower into the same deterministic platform contract.

Core Thesis

Observer has two authoring surfaces:

  1. a simple surface for the common case
  2. a full script surface for high-rigor testing

These are not two separate engines.

Both surfaces lower to one canonical suite core. That is the central design rule that keeps Observer coherent.

System Layers

Observer consists of these layers:

  1. provider libraries used by language ecosystems such as C, Rust, and Node.js
  2. provider hosts that expose deterministic list and run operations to Observer
  3. inventory as the canonical execution contract
  4. suites that express test intent through simple or full-script surfaces
  5. runner and report machinery that execute and record outcomes
  6. product certification that combines ordered suite stages into one product verdict

Design Priorities

The current draft locks these priorities:

  1. deterministic behavior
  2. canonical inventory and case identity
  3. one semantic core for simple and advanced verification
  4. explicit observation and failure handling
  5. structured machine-readable reporting
  6. product certification as a first-class platform layer

Specification Set

The normative direction of the platform is split across these documents:

Examples and intent sketches live in:

What Changed From The Seed

The earlier single-file draft mixed together:

  • seed ideas
  • candidate syntax
  • normative rules
  • examples from different design generations

This spec set separates those concerns.

The main architectural lock-ins are:

  • provider discovery is the source of language-native tests
  • inventory is the canonical intermediate representation
  • simple tests are sugar over the same core model as the full script surface
  • case identity is suite item plus inventory test name
  • product certification is a top-level contract above suites, not shell glue around suites
  • reports distinguish canonical fields from volatile fields
  • analytics is observational and non-canonical by default

Non-Goals For This Draft

This draft does not attempt to finalize:

  • every concrete surface syntax detail
  • plugin ecosystems or arbitrary extension hooks
  • broad compatibility shims for all existing test runners

The goal here is stronger: lock the platform shape first, then refine syntax and integrations on top of that shape.

The intended category is not "just another test runner".

Observer can execute tests, but its defining concern is broader:

  • explicit discovery and execution contracts
  • deterministic and canonical verification artifacts
  • staged product certification
  • derived analytics and comparison artifacts
  • operational truth that can live above language-local test frameworks