The Overlay Surface Ships¶
Curious · February 26, 2026
What Happened¶
We built the observation surface described in The Precision Matrix as Developmental Metric — six composable geometric overlays on \(g = \Sigma^{-1}\) — and shipped it as a typed API. 135 tests. Every overlay function, every compound observable, every response model validated. The stack computes in under 200 milliseconds.
This is the moment where the theory became infrastructure. The overlays described in §9 of the foundations paper are now callable endpoints returning typed data. An agent — human or machine — can read the full developmental geometry of a field without knowing anything about covariance matrices, eigenvalue spectra, or Marchenko-Pastur distributions. The types carry the contract.
The Six Overlays¶
Each overlay is a different reading of the same object: \(g = \Sigma^{-1}\), the precision matrix of the compositional field.
| Overlay | What It Reads | What It Returns |
|---|---|---|
| Marchenko-Pastur | Eigenvalues vs \(\lambda_+\) | Which dimensions carry signal vs noise |
| Pressure | Diagonal of \(g\) | Per-dimension information density |
| Viscosity | \(\|\Delta g\|_F\) over time | Whether the field is stiffening through practice |
| Capacitance | Discharge after stabilization | Readiness — stored sensitivity to perturbation |
| Eventuality | Eigenvalue trajectory shape | STATE / ACTIVITY / ACHIEVEMENT / ACCOMPLISHMENT per dimension |
| Surplus | 17D vs 768D divergence | Where meaning leads structure, where structure leads meaning |
The overlays compose. The diagonal reading — crossing MP signal/noise with eventuality trajectory with pressure density — produces compound observables per dimension. These compounds are the developmental portrait:
- Crystallized: above noise floor, not moving, high density. Practiced knowledge, settled.
- Dense development: above noise floor, drifting, high density. Active learning in a practiced area.
- Active exploration: above noise floor, drifting, low density. Signal dimension, sparse practice, evolving.
- Expertise: above noise floor, accomplished, high density. Drifted and settled — mastery basin.
- Noise activity: below noise floor, moving. Not yet distinguishable from randomness.
- Undifferentiated: below noise floor, not moving. Untouched.
These labels are not assigned by a classifier. They are factual observations — each one a conjunction of independently computed geometric properties.
The Dynamic Noise Floor¶
The Marchenko-Pastur distribution provides the spectral threshold \(\lambda_+\) separating signal from noise. But the eventuality classifier also needs a noise floor — how much eigenvalue drift counts as movement vs measurement noise.
This floor is not a fixed parameter. It is an epigenetic derivative: \(\text{base}/\sqrt{n}\), where \(n\) is the observation count. Early in development, the floor is wide — the field doesn't know what's signal yet. As observations accumulate, the floor tightens. The field becomes more sensitive to smaller movements. This is not tuning. It is the mathematical consequence of more data producing more precise estimates of what "noise" looks like.
The dynamic factor is observable in the API response on every dimension. It is a diagnostic — part of the dataflow trace, not an input to any classification. The field shows you how it's calibrating itself.
What the Tests Prove¶
110 unit tests across five overlay modules validate the mathematical correctness of each overlay in isolation: MP threshold computation, pressure from metric tensor inversion, viscosity decay, capacitive discharge, eventuality classification with regime-aware thresholds, surplus with geometry-derived (not hardcoded) thresholds, and compound surface composition.
10 integration tests (the Edison switch) build a synthetic 50-composition session spanning three domain clusters and run every overlay function, validating every result against typed response models. They verify:
- The field matures from nascent to developing as compositions accumulate
- Signal dimensions grow when new domains enter the field
- Surplus thresholds are derived from the field's own geometry — never 0.5, never hardcoded
- The dynamic noise floor tightens with observation count
- The full stack computes in under 200 milliseconds
- No input is ever mutated — the entire stack is observation, not modification
15 contract tests simulate what happens when an agent consumes the API. They prove the typed response carries enough information to:
- Decide which dashboard sections to display
- Generate natural language articulations from compound labels
- Select appropriate visualizations
- Map every compound label to a distinct visual treatment
- Handle a nascent field (3 compositions) without crashing
- Serialize the full surface to JSON and round-trip it cleanly
The Typed API¶
Eight endpoints. All read-only GET requests. All returning Pydantic-validated response models with full type annotations.
GET /api/overlay/mp/{session_id}
GET /api/overlay/pressure/{session_id}
GET /api/overlay/viscosity/{session_id}
GET /api/overlay/capacitance/{session_id}
GET /api/overlay/eventuality/{session_id}
GET /api/overlay/surplus/{session_id}
GET /api/overlay/surface/{session_id}
GET /api/overlay/diagonal/{session_id}/{dimension}
The surface endpoint returns everything composed. The diagonal endpoint returns a single dimension's compound observable — the focused reading.
The OpenAPI specification is auto-generated from the Pydantic models. Every field has a type. Every enum has named values. Every response model documents what it carries. An agent reading the spec can build a presentation layer without reading source code.
What This Means¶
The observation surface is the product surface.
Every vertical application of Habitat — education dashboards, organizational self-assessment, creative practice tracking, commons governance — reads the same surface. The compound labels are the same. The maturity stages are the same. The regime structure (gradient / compressed / categorical) is the same. What changes is which dimensions you highlight, which articulation vocabulary you use, and which compound labels you foreground.
An education dashboard foregrounds crystallized dimensions (mastery) and active exploration (growth edges). An organizational tool foregrounds pressure ratios (where practice is concentrated vs sparse) and viscosity (institutional learning resistance). A creative practice tool foregrounds eventuality signatures — the temporal shape of the work.
The geometry is the invariant. The surface is the interface. The overlays compose because they read different derivatives and transforms of the same \(g\).
What's Next¶
The surface ships. The contract is tested. The types are clean.
Next: a working vertical. An agent reads the surface, interprets the compounds, and builds a dashboard that a person can use. Not a demo. Not a mockup. The actual geometry of an actual field, rendered through the typed API, articulated in words the user recognizes.
The field has been observing itself. Now it needs someone to look.