Freeze the E002 Stage B instrumentation contract#9
Conversation
There was a problem hiding this comment.
Pull request overview
This PR formalizes and “freezes” the E002 Stage B instrumentation specification and contract as a read-only, offline replay experiment over frozen E001 evidence, and records the core architectural decision (offline replay + exact rational telemetry) in ADR form.
Changes:
- Adds the E002 experiment specification, contract JSON, and placeholder directories for future results/observations.
- Records ADR 0002 and updates repository registries/readmes to register E002 as specified (not yet implemented).
- Updates repository readiness to reflect the new Stage B critical path and entrance criteria.
Reviewed changes
Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| REPOSITORY_READINESS.md | Updates critical path steps and adds E002 Stage B entrance criteria checklist. |
| registry/CONCEPT_REGISTRY.md | Registers SW.EXPERIMENT.E002 as “Specified — E1”. |
| experiments/README.md | Adds E002 entry and links to the E002 spec. |
| experiments/E002/results/README.md | Introduces results directory layout and immutability requirements. |
| experiments/E002/observations/README.md | Introduces emergent observations directory rules for E002. |
| experiments/E002/EXPERIMENT__E002__NONCAUSAL_PNEUMATIC_INSTRUMENTATION__v0.1__2026-07-14.md | Adds the full E002 Stage B experiment specification (hypotheses, observables, invariants, outputs). |
| experiments/E002/config/INSTRUMENTATION_CONTRACT__E002__v0.1__2026-07-14.json | Adds the frozen instrumentation contract (targets, numeric rules, prohibited effects, formulas). |
| docs/decisions/README.md | Adds ADR 0002 to the decision index. |
| docs/decisions/ADR__0002__OFFLINE_REPLAY_AND_EXACT_RATIONAL_TELEMETRY_FOR_E002__2026-07-14.md | Records the decision to implement E002 as offline replay with exact rational telemetry. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| `proposal_eligibility` includes only facts already known before the tick: active work, completed local processing, valid identity and schema, provenance, freshness of any pre-existing lease, and non-isolated participants. It means that work may seek a transfer; it is not a validated aperture or permission to commit. Receiver vacancy is represented separately as capacity conductance. |
| "receiver_conductance": "receiver_vacancy / receiver_capacity", | ||
| "receiver_resistance": "receiver_capacity / receiver_vacancy", | ||
| "sampling_phases": [ |
| "canonical_numeric_representation": { | ||
| "floating_point_allowed": false, | ||
| "infinity_allowed": false, | ||
| "rational_fields": [ |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d563d9774c
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ], | ||
| "primary_phase_period": 3, | ||
| "receiver_conductance": "receiver_vacancy / receiver_capacity", | ||
| "receiver_resistance": "receiver_capacity / receiver_vacancy", |
There was a problem hiding this comment.
In the circular-wait and saturated-receiver samples, receiver vacancy can be zero, so freezing the contract with receiver_capacity / receiver_vacancy as the canonical resistance formula makes an implementation either divide by zero or emit infinity/invalid rationals. That conflicts with the E002 spec's blocked-state requirement for zero receiver vacancy and will invalidate any replay that follows the JSON contract for those runs.
Useful? React with 👍 / 👎.
Summary
Constitutional boundary
E002 is read-only instrumentation. It may characterize traces and generate evidence, but it cannot alter simulator transitions, authorize transfers, assign causal control, or automatically authorize a Stage C experiment.
Validation
python3 tools/check_repository.pyjq -e . experiments/E002/config/INSTRUMENTATION_CONTRACT__E002__v0.1__2026-07-14.jsongit diff --checkbadb4844084fc14adf20935868941a95feebe724e366baa3dc4afdaf297b9821ab34a99d031630a00ce28b3785330a764eab8f1a7ff5eca07cb4afc8ffb4feae