From b8f976c85634b583ea86644d4ae3a37e0b5154d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mat=C3=A9o=20H=2E=20Petel?= <113530345+fraware@users.noreply.github.com> Date: Tue, 25 Aug 2026 06:12:37 -0700 Subject: [PATCH 1/6] Fix Atlas software conformance workflow --- .../atlas-production-conformance.yml | 100 ++++++++---------- 1 file changed, 43 insertions(+), 57 deletions(-) diff --git a/.github/workflows/atlas-production-conformance.yml b/.github/workflows/atlas-production-conformance.yml index a36391a..da4f375 100644 --- a/.github/workflows/atlas-production-conformance.yml +++ b/.github/workflows/atlas-production-conformance.yml @@ -1,13 +1,8 @@ -# Atlas production-conformance (CI lane E skeleton). -# A green run is not production-network qualification, physical evidence, or a -# security audit. When apps/atlas-api exists, unit/contract tests may run; the -# production checks listed in the report remain unimplemented until a durable -# adapter, authz, rate limits, and migration tests ship. +# Atlas software-contract conformance lane. # -# Schema migration discipline: every versioned Atlas/artifact contract requires -# parser + validator + ArtifactMigrationRegistryV1 tests in packages/validation -# before it is used in a release. This workflow must not change empirical v8 -# gate semantics. +# A green run qualifies the checked Atlas client/API contracts on one exact +# software revision. It is not a public-network qualification, security audit, +# physical-object claim, or empirical release gate. name: atlas-production-conformance on: @@ -30,75 +25,66 @@ env: VITE_SOFTWARE_REVISION: ${{ github.event.pull_request.head.sha || github.sha }} jobs: - skeleton: + contracts: runs-on: ubuntu-24.04 - timeout-minutes: 5 + timeout-minutes: 20 steps: - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 - - name: Emit production-conformance skeleton report + - uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0 + with: + node-version: 22 + - name: Enable Corepack + run: corepack enable + - name: Install frozen dependencies + run: pnpm install --frozen-lockfile + - name: Typecheck Atlas client + run: pnpm --filter @everything-rings/atlas-client typecheck + - name: Test Atlas client + run: pnpm --filter @everything-rings/atlas-client test + - name: Typecheck Atlas API + run: pnpm --filter @everything-rings/atlas-api typecheck + - name: Test Atlas API contracts, HTTP surface, persistence, and V2 records + run: pnpm --filter @everything-rings/atlas-api test + - name: Emit scoped conformance report run: | set -euo pipefail mkdir -p qualification - api_present=false - client_present=false - if [ -f apps/atlas-api/package.json ]; then api_present=true; fi - if [ -f packages/atlas-client/package.json ]; then client_present=true; fi cat > qualification/atlas-production-conformance.json < Date: Tue, 25 Aug 2026 06:13:53 -0700 Subject: [PATCH 2/6] Redesign repository README for final handoff --- README.md | 284 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 232 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index 4b40774..6c5f578 100644 --- a/README.md +++ b/README.md @@ -1,68 +1,181 @@ +
+ # EVERYTHING RINGS -**Hit anything. Discover how it rings.** +### Hit anything. Discover how it rings. + +**A local-first acoustic instrument that turns one physical strike into an interpretable resonance model, a playable instrument, and a shareable acoustic artifact.** + +[**Open the live instrument →**](https://fraware.github.io/EVERYTHING-RINGS/) · [Product principles](docs/PRODUCT.md) · [Science & DSP](docs/DSP.md) · [Full architecture](docs/ENGINEERING_TAKEOVER_AND_FULL_VISION_SPEC.md) + +[![CI](https://github.com/fraware/EVERYTHING-RINGS/actions/workflows/ci.yml/badge.svg?branch=post-freeze-development)](https://github.com/fraware/EVERYTHING-RINGS/actions/workflows/ci.yml) +[![Digital twin qualification](https://github.com/fraware/EVERYTHING-RINGS/actions/workflows/digital-twin-qualification.yml/badge.svg?branch=post-freeze-development)](https://github.com/fraware/EVERYTHING-RINGS/actions/workflows/digital-twin-qualification.yml) +[![Full-vision qualification](https://github.com/fraware/EVERYTHING-RINGS/actions/workflows/full-vision-software-qualification.yml/badge.svg?branch=post-freeze-development)](https://github.com/fraware/EVERYTHING-RINGS/actions/workflows/full-vision-software-qualification.yml) +[![Atlas contracts](https://github.com/fraware/EVERYTHING-RINGS/actions/workflows/atlas-production-conformance.yml/badge.svg?branch=post-freeze-development)](https://github.com/fraware/EVERYTHING-RINGS/actions/workflows/atlas-production-conformance.yml) +[![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f.svg)](LICENSE) +[![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6.svg)](tsconfig.base.json) + +
+ +--- + +## One strike. A whole instrument. + +A glass, bowl, bell, mug, plate, tool, or any other safe object has an audible ring shaped by the transient you record. EVERYTHING RINGS captures that strike in the browser, isolates the ringdown, estimates the resonant structure supported by the recording, reconstructs it, and turns the result into something you can **see, hear, play, save, compare, and share**. + +The first-use loop is intentionally simple: + +
+ +### **STRIKE → REVEAL → HEAR → PLAY → SHARE** + +
+ +Underneath that interaction is a much stricter system: deterministic DSP, native-rate acquisition, explicit quality gates, content-addressed provenance, frozen empirical contracts, synthetic qualification, research-only identity/material models, and an emerging Resonance Atlas architecture. + +## Try it in 60 seconds + +1. Open the [live instrument](https://fraware.github.io/EVERYTHING-RINGS/) on a microphone-enabled browser. +2. Tap **START LISTENING** and allow microphone access. +3. Use a safe object and make one clean strike near the microphone. +4. Explore the revealed modes, listen to the reconstructed model, and play the object chromatically. +5. Save the fingerprint locally or share an Acoustic Capsule without uploading microphone PCM. + +> **Privacy by design:** raw microphone PCM stays local under the current product contract. Local history stores fingerprints, and Acoustic Capsules carry bounded fingerprint data in the URL fragment—not recordings. + +## What a strike becomes + +| Surface | What it gives you | +|---|---| +| **Acoustic DNA** | A deterministic visual identity for one measured fingerprint | +| **Resonance Microscope** | Per-mode frequencies, decay, confidence, and isolated audition | +| **Ringdown Lens** | A time-domain view of fitted modal envelopes | +| **CAPTURE ↔ MODEL** | Local comparison between the isolated ringdown and modal reconstruction | +| **Playable instrument** | Chromatic modal synthesis that preserves the measured frequency ratios and decay constants | +| **Saved captures** | Fingerprint-only local history that can be reopened without microphone access | +| **Resonance Diff** | Descriptive comparison of two capture observations without an identity verdict | +| **Acoustic Capsules** | Fingerprint-only interactive share links: hear it, play it, then try your own | +| **Acoustic Story** | A self-contained fingerprint-derived sound-and-motion artifact | + +## From a strike to the long-term vision + +```mermaid +flowchart LR + A[Physical strike] --> B[Local microphone capture] + B --> C[Quality gate + ringdown isolation] + C --> D[er-dsp-2 fingerprint] + D --> E[Reveal] + D --> F[Modal reconstruction] + D --> G[Playable instrument] + D --> H[Local history + Capsules] + + D --> I[Immutable measurement] + I --> J[Versioned derivations] + J --> K[Repeated-observation acoustic object model] + K --> L[Sonic Twin research] + K --> M[Spatial modal field] + I --> N[Resonance Atlas contracts] + L --> N + M --> N +``` + +The architectural rule is simple and important: + +> **A capture is one observation. A fingerprint is one analysis of that observation. Neither is automatically the physical object.** + +That distinction is what allows the repository to grow from a playful instrument into serious measurement, retrieval, and corpus infrastructure without turning a convenient hash into an unsupported scientific claim. + +## Why this repository is unusual + +### Deterministic first + +The evidence-eligible baseline is explicit and inspectable. The canonical `er-dsp-2` path estimates peaks, tracks persistent modes, fits decay, computes confidence, and emits a versioned fingerprint. Research estimators live on separate non-evidence paths until a future algorithm earns promotion. + +### Local-first by default + +Microphone PCM is not required for sharing, saved-capture playback, Resonance Diff, Twin demos, or Atlas contracts. A future network service must justify any remotely stored data instead of making upload the default architecture. + +### Measurement is separate from derivation -EVERYTHING RINGS is a local-first acoustic instrument for estimating the audible resonances of struck physical objects, reconstructing those resonances, and turning them into playable instruments. +The validation layer content-addresses immutable measurements independently from renderers, instruments, similarity systems, visualizations, embeddings, and Atlas artifacts. Multi-source derivation records and source links let downstream research evolve without rewriting measurement history. -## Current phase +### Claims have maturity, not vibes -MVP-0 contains the full software path from microphone capture to reveal and play: deterministic impact analysis, capture-quality gates, ringdown isolation, versioned acoustic fingerprints, one-to-one recurrence comparison, modal reconstruction, realtime playable modal synthesis, Acoustic DNA, and the consumer **STRIKE → REVEAL → HEAR → PLAY** loop. The reveal includes a Resonance Microscope for exact per-mode inspection and isolated audition, local CAPTURE ↔ MODEL listening, a Ringdown Lens that visualizes the fitted modal envelopes through time, a locally generated Acoustic DNA card, and a self-contained Acoustic Story that packages the fingerprint-derived model as an offline vertical sound-and-motion artifact without exporting microphone PCM. +Capabilities move through an explicit ladder: -Successful consumer fingerprints can be retained in bounded local history and reopened later as fingerprint-derived model instruments; reopened views never retain or imply access to the original microphone recording. Two saved capture observations can be inspected in Resonance Diff with side-by-side Acoustic DNA, A/B model listening, deterministic observable summaries, and threshold-free mutual-nearest frequency pairs. Resonance Diff deliberately emits no identity verdict or aggregate similarity score. +`prototype → software-qualified → synthetic-qualified → physical-research → held-out-validated → product-eligible → released` -Post-freeze product development also closes the sharing loop with **Acoustic Capsules**. A capsule is a bounded, versioned, fingerprint-only URL-fragment transport. The creator can share one interactive link; the recipient can immediately see the Acoustic DNA, hear the fingerprint-derived model, play it chromatically, reshare it, or move directly into `TRY YOUR OWN`. Opening and playing a capsule requires no account, backend fingerprint upload, raw microphone audio, or microphone permission. A capsule is user-shareable data, not authenticated provenance, a canonical physical-object identifier, release evidence, or a permanent public record. +A green workflow cannot promote a synthetic result into physical evidence. The [claim registry](docs/CLAIM_REGISTRY.md) records the strongest proposition currently earned for each capability. -The consumer path is gated in CI by a deterministic mobile browser journey that feeds a physical-style ringdown through the microphone interface and requires the real acquisition, analysis, reveal, listening, playable-instrument, share-download, and strike-again flow to complete. A separate local-history journey requires a successful strike to persist as a fingerprint-only record, survive a hard reload, reopen without reacquiring the microphone, reproduce model/mode/chromatic playback from the saved fingerprint, and return to history without mutation. That journey also creates two distinct equal-signature observations and requires Resonance Diff to keep both records separate, A/B-play both stored models with zero microphone reacquisition, return without mutation, and preserve share/removal behavior on a 390×844 viewport. +## Current capability map -A dedicated Acoustic Capsule journey requires the real history UI to create a fragment-only share link, opens the recipient experience at 390×844, verifies exact signature continuity and interpretation boundaries, requires zero microphone calls during recipient model/chromatic playback, audits phone interaction geometry, exercises reshare, and requires `TRY YOUR OWN` to clear the shared fragment and hand directly into exactly one microphone request. Malformed and oversized capsules must recover to the ordinary consumer landing. A denied-permission journey verifies clear microphone recovery, and phone-sized checks cover the campaign author, campaign collector, validation lab, and release console. +| Capability | Current maturity | Scope | +|---|---|---| +| Consumer **STRIKE → REVEAL → HEAR → PLAY** | **software-qualified** | Browser and synthetic qualification | +| Resonance estimation (`er-dsp-2`) | **software-qualified** | Estimated audible resonances supported by a recorded transient | +| Modal reconstruction + playable instrument | **software-qualified** | Deterministic fingerprint-derived audio | +| Sonic Twin retrieval / verification | **synthetic-qualified** | Named digital populations only | +| Spatial modal-field prediction | **software-qualified** | Predicted fingerprints; never measurement evidence | +| Material inference | **prototype / research** | No calibrated physical material claim | +| Measurement + derivation provenance | **software-qualified** | Content-addressed V1 measurements and V2 multi-source derivations | +| Atlas V1/V2 integrity contracts | **software-qualified** | Records, snapshots, public observations, specimen records, membership assertions | +| Atlas client + local file-backed HTTP API | **software-contract qualified** | Local/durable software path; not a public production network | +| Empirical Gate A2 / B / C | **not yet run** | Frozen physical/perceptual sequence remains separate | -Playback is single-source for sample auditions and A/B comparison, recovers suspended browser audio contexts on user interaction, silences sample and realtime voices on reset/background/disposal, and exposes user-facing recovery instead of raw browser errors. Ringdown animation clamps browser-frame timing to the strike boundary, and render failures fall back to an explicit reload surface instead of an empty page. +The authoritative wording and exclusions live in [`docs/CLAIM_REGISTRY.md`](docs/CLAIM_REGISTRY.md). -The empirical release gates remain open until representative physical and perceptual evidence passes their frozen contracts. Gate A2 defines each physical-session experiment as the first five acquisition-quality-passing attempts. Once an attempt qualifies, its analytical outcome is immutable: a failed analysis occupies its slot and cannot be retried away. Evidence schema v5 records those success/failure outcomes explicitly, stamps the exact software commit that produced each bundle, and recomputes recurrence from retained fingerprints with attempt 1 fixed as the reference. +## The research stack -Every physical validation object also receives a stable `specimenId`. That identity, not a display label, defines release distinctness and links repeated sessions of the same physical specimen. Relabeling an object cannot manufacture another release specimen. An analysis-worker crash or other true internal session error terminates the current validation session; subsequent capture uses a new session ID and retains the specimen ID when the same object is tested again. +The post-freeze software line already contains foundations for the larger research program: -The campaign author creates a frozen `empirical-campaign-1` manifest from real physical specimen choices on the exact software revision that will collect them. The dedicated campaign collector then only arms planned specimens under their precommitted setup and authorized revision. The general validation lab hosts later blinded reconstruction and device-playability review, and the Release Console accounts for planned failures, missing specimens, extra sessions, substitutions, and unplanned evidence before evaluating Gate A2/B/C. Raw microphone PCM remains local throughout. Synthetic or cross-field tests never substitute for required physical evidence. +- repeated-observation `AcousticObjectModelV1` estimates with frequency/decay/amplitude dispersion and observation support; +- nuisance characterization across strike, support, room, station, operator, and day; +- specimen-disjoint benchmark construction and hard-negative selection; +- deterministic Sonic Twin verification with `match / nonmatch / abstain`; +- ranked specimen retrieval with Recall@K and MRR; +- group-disjoint isotonic probability calibration with Brier score, calibration error, ROC AUC, and risk/coverage analysis; +- explicit similarity-algorithm promotion policy; +- spatial modal sound fields with strike-location-conditioned excitation; +- research-only high-resolution modal estimation and material inference; +- station qualification contracts; +- content-addressed measurement, derivation, artifact-envelope, Atlas, and assurance contracts; +- Atlas V2 observation/specimen/membership semantics; +- a typed Atlas client and local file-backed HTTP service with conformance, HTTP, persistence, and V2 tests; +- an independent verification CLI for exact-byte hashing and artifact/evidence validation. -## Engineering invariants +The interactive research surfaces are deliberately labeled synthetic: -- Scientific claims stop at estimated audible resonances from the recorded transient. -- DSP is deterministic and independent of React, the DOM, and Web Audio. -- Native capture sample rates are propagated explicitly; no algorithm assumes 48 kHz. -- Physical quantities include units in identifiers. -- Microphone PCM remains local in MVP-0. -- Consumer capture playback is local and never substitutes for blinded reconstruction evidence. -- Consumer sample auditions do not overlap; a new sample playback replaces the previous sample playback. -- Reset, stop, page backgrounding, and resource disposal silence sample playback and realtime voices. -- Reconstruction synthesizes estimated modes; recorded audio is not mixed into the model output. -- Ringdown visualization evaluates the fitted modal decay envelopes and adds no new analytical estimate. -- Realtime notes preserve one global modal frequency ratio and the measured decay constants. -- Acoustic DNA is a deterministic encoding of the measured fingerprint. -- Acoustic DNA cards and Acoustic Stories derive from the fingerprint/model, contain no microphone PCM, and never count as release evidence. -- Local consumer history stores bounded fingerprint records only; it stores no microphone PCM and does not define canonical physical-object identity. -- Equal Acoustic DNA signatures are never treated as proof of object identity or as a deduplication rule. -- Reopened saved captures synthesize model, mode, and chromatic playback from the stored fingerprint; original-capture playback remains explicitly unavailable. -- Saved-capture playback owns an output-only audio lifecycle and never initializes microphone acquisition or analysis resources. -- Resonance Diff compares capture observations only; it never emits a same/different-object verdict or aggregate identity score. -- Mutual-nearest frequency pairs are symmetric, one-to-one, threshold-free navigation aids and never establish a shared physical mode. -- Fingerprints from different algorithm revisions are visibly flagged instead of normalized into a comparison claim. -- Acoustic Capsules are bounded, versioned fingerprint transports encoded in URL fragments; they contain no microphone PCM and recipient playback is output-only. -- Acoustic Capsule parsing fails closed on malformed, oversized, unsupported-version, unsupported-algorithm, numerically invalid, or signature-inconsistent payloads. -- Acoustic Capsules are not canonical object identifiers, authenticated provenance, release evidence, or permanent public records. -- Changing a shared capsule payload disposes any playback resources bound to the prior fingerprint. -- Gate A2 never substitutes or replaces a qualified analytical failure. -- Physical release distinctness is keyed by stable specimen ID, not object label. -- A precommitted empirical campaign keeps planned failures, missing specimens, setup deviations, extra sessions, and unplanned specimens visible without changing release thresholds. -- Campaign authoring refuses placeholders and duplicate specimen IDs and binds the manifest to the exact running revision. -- Campaign-bound collection cannot arm a specimen absent from the manifest or a build whose software revision differs from the campaign authorization. -- Analysis-worker crashes and other fatal validation-session errors cannot continue on the same worker/audio resources. -- Gate B reviews are bound to one exact passing session/attempt target per specimen. -- Gate C inherits the exact Gate B target and requires explicit cross-device evidence from passing specimens. -- Release thresholds are versioned and frozen before the corresponding empirical dataset is collected. -- The dependency graph is committed and CI/deployment use frozen lockfile installs. -- No learned model enters the pipeline until the deterministic baseline is characterized. +- `?twin=1` — Sonic Twin software lab; +- `?atlas=1` — local Resonance Atlas software lab; +- `?lab=1` — validation/review lab. -## Development +They are research and qualification surfaces, not product claims about physical identity. + +## Repository map + +```text +EVERYTHING-RINGS/ +├── apps/ +│ ├── web/ # consumer instrument + empirical/research surfaces +│ └── atlas-api/ # local/durable Atlas HTTP service contracts +├── packages/ +│ ├── acquisition/ # microphone acquisition + capture quality +│ ├── dsp/ # canonical DSP + research estimators +│ ├── fingerprint/ # recurrence, object models, Twin, calibration, material/spatial research +│ ├── synth/ # modal reconstruction +│ ├── instrument/ # playable modal instrument semantics +│ ├── visual/ # fingerprint-derived visual artifacts +│ ├── validation/ # evidence, gates, provenance, Atlas, assurance +│ ├── atlas-client/ # typed Atlas client +│ ├── er-cli/ # independent verification CLI +│ └── fixtures/ # deterministic test fixtures +├── docs/ # product, science, evidence, claims, release and takeover specs +└── scripts/ # browser, lifecycle and end-to-end qualification +``` + +## Run locally + +Requires Node.js 22 and the repository-declared pnpm version. ```bash corepack enable @@ -70,10 +183,77 @@ pnpm install --frozen-lockfile pnpm typecheck pnpm test pnpm build +pnpm --filter @everything-rings/web dev ``` -Release-validation builds must set `VITE_SOFTWARE_REVISION` to the exact 40-hex Git commit. The GitHub Pages and CI workflows do this automatically; an unstamped local build can use consumer surfaces but cannot author or arm conforming release evidence collection. +The root web app is the consumer experience. For local research surfaces, append `?lab=1`, `?twin=1`, or `?atlas=1` to the local URL. + +### Independent verification CLI + +```bash +pnpm --filter @everything-rings/er-cli test +pnpm --filter @everything-rings/er-cli exec node ./bin/er.mjs hash path/to/file.json +pnpm --filter @everything-rings/er-cli exec node ./bin/er.mjs verify evidence path/to/evidence.json +pnpm --filter @everything-rings/er-cli exec node ./bin/er.mjs verify measurement path/to/measurement.json +pnpm --filter @everything-rings/er-cli exec node ./bin/er.mjs verify derivation path/to/derivation.json +``` + +## Evidence, qualification, and branch authority + +The repository intentionally separates two lines of work: + +- **`main`** is the frozen empirical v8 authority for the current physical validation sequence. Its exact revision is intentionally preserved. +- **`post-freeze-development`** carries product, research, provenance, Atlas, tooling, and future-system work. + +Software qualification covers deterministic execution, integrity, synthetic acoustic recovery, browser flows, and named digital-population behavior. It does **not** by itself establish microphone-transducer validity, human perceptual fidelity, physical-object identity, or material identity. + +The empirical sequence remains separately preregistered and version-bound. See [Gate A](docs/GATE_A.md), [Gate B](docs/GATE_B.md), [Gate C](docs/GATE_C.md), [validation evidence](docs/VALIDATION_EVIDENCE.md), and the [release checklist](docs/RELEASE_CHECKLIST.md). + +
+Scientific interpretation boundary + +The current evidence-eligible interpretation is: + +> **Estimated audible resonances supported by each recorded transient.** + +The project does not currently promote a fingerprint into complete structural eigenmodes, a signature into canonical physical-object identity, a research material label into physical material identification, a reconstruction into calibrated loudness, or a digital-twin result into physical validation. + +Research code may explore those directions only behind explicit version, population, provenance, uncertainty, and maturity boundaries. + +
+ +## Documentation + +| Start here | Purpose | +|---|---| +| [`docs/PRODUCT.md`](docs/PRODUCT.md) | Product principles and interaction doctrine | +| [`docs/DSP.md`](docs/DSP.md) | Canonical signal model and DSP contract | +| [`docs/FULL_VISION_SOFTWARE.md`](docs/FULL_VISION_SOFTWARE.md) | Long-term software architecture | +| [`docs/ENGINEERING_TAKEOVER_AND_FULL_VISION_SPEC.md`](docs/ENGINEERING_TAKEOVER_AND_FULL_VISION_SPEC.md) | Full engineering/research execution specification | +| [`docs/CLAIM_REGISTRY.md`](docs/CLAIM_REGISTRY.md) | Capability maturity and exact claim boundaries | +| [`docs/DIGITAL_TWIN_QUALIFICATION.md`](docs/DIGITAL_TWIN_QUALIFICATION.md) | Synthetic qualification semantics | +| [`docs/VALIDATION.md`](docs/VALIDATION.md) | Validation architecture | +| [`docs/RELEASE_CHECKLIST.md`](docs/RELEASE_CHECKLIST.md) | Software release and assurance checklist | +| [`CONTRIBUTING.md`](CONTRIBUTING.md) | Contribution and change-class rules | +| [`SECURITY.md`](SECURITY.md) | Security reporting and sensitive-artifact boundaries | + +## Contributing + +Contributions are welcome when they preserve the separation between consumer behavior, research diagnostics, and evidence-eligible empirical contracts. Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before changing acquisition, DSP, evidence schemas, gate semantics, provenance, or public claim copy. + +## License + +Software in this repository is released under the [MIT License](LICENSE). Dataset, model, and future physical-corpus artifacts may carry separate terms when explicitly stated. + +--- + +
+ +### The idea is simple. + +**The world is full of things that ring.** +**This is an instrument for discovering them.** -The root web experience is the consumer loop. Append `?campaign-author=1` to select and freeze the real physical campaign, `?campaign=1` for precommitted campaign collection, `?lab=1` for the general validation/review lab, and `?release=1` for the local release-evidence console. Acoustic Capsules use the `#ring=...` fragment on the ordinary consumer route and deliberately strip query-route state when shared. +[**Try EVERYTHING RINGS →**](https://fraware.github.io/EVERYTHING-RINGS/) -See `docs/PRODUCT.md`, `docs/SPEC.md`, `docs/DSP.md`, `docs/VALIDATION.md`, `docs/GATE_A.md`, `docs/REALIMPACT.md`, `docs/GATE_B.md`, `docs/GATE_C.md`, `docs/VALIDATION_EVIDENCE.md`, `docs/EMPIRICAL_CAMPAIGN.md`, `docs/ACOUSTIC_DNA.md`, `docs/ACOUSTIC_CARD.md`, `docs/RINGDOWN_LENS.md`, `docs/ACOUSTIC_STORY.md`, `docs/SAVED_CAPTURES.md`, `docs/CAPTURE_COMPARISON.md`, `docs/ACOUSTIC_CAPSULE.md`, and `docs/DEPLOYMENT.md` for the product principles, implementation contracts, release gates, evidence model, campaign-integrity contract, visual/share artifacts, saved-capture and comparison boundaries, and deployment path. +
From fc84f33f66dece22e661849740f9a0b0172d8576 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mat=C3=A9o=20H=2E=20Petel?= <113530345+fraware@users.noreply.github.com> Date: Tue, 25 Aug 2026 06:14:14 -0700 Subject: [PATCH 3/6] Align contribution guide with MIT licensing --- CONTRIBUTING.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e100ae6..6fd8551 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -EVERYTHING RINGS combines a consumer acoustic instrument with empirical measurement and validation infrastructure. Contributions are welcome, but changes must preserve the distinction between product behavior, research diagnostics, and evidence-eligible empirical contracts. +EVERYTHING RINGS combines a consumer acoustic instrument with empirical measurement, research, provenance, and validation infrastructure. Contributions are welcome, but changes must preserve the distinction between product behavior, research diagnostics, and evidence-eligible empirical contracts. ## Development setup @@ -23,7 +23,7 @@ Consumer UI, local history, sharing, visualization, and other non-empirical feat ### Research/diagnostic changes -Alternative DSP configurations, digital twins, external datasets, similarity baselines, and future embeddings must clearly state whether their output is evidence-eligible. Custom analysis configurations must not claim an `er-dsp-*` canonical algorithm version unless a new algorithm contract is explicitly versioned. +Alternative DSP configurations, digital twins, external datasets, similarity baselines, material/spatial models, and future embeddings must clearly state whether their output is evidence-eligible. Custom analysis configurations must not claim an `er-dsp-*` canonical algorithm version unless a new algorithm contract is explicitly versioned. ### Empirical-contract changes @@ -43,8 +43,12 @@ Keep machine contracts, documentation, and advertised claims synchronized. A nea ## Privacy -Do not commit microphone PCM, private Gate B listening companions, device identifiers that should remain local, secrets, or user-private artifacts. Synthetic/digital-twin signals are acceptable when clearly labeled non-physical. +Do not commit microphone PCM, private Gate B listening companions, secrets, user-private artifacts, or device identifiers that should remain local. Synthetic/digital-twin signals are acceptable when clearly labeled non-physical. + +Public Atlas artifacts must satisfy their versioned privacy and consent contracts. A content digest proves byte identity; it does not prove that an asserted physical-object identity or material label is true. ## Licensing -The repository currently has an open issue to choose an explicit project license. Until that decision is made, public repository visibility should not be interpreted as a grant of reuse rights beyond GitHub's platform terms. Contribution licensing language will be finalized with the repository license decision. +The software repository is licensed under the [MIT License](LICENSE). Unless a contribution explicitly states otherwise and is accepted under separate terms, software contributions are made under the same license. + +Datasets, trained models, benchmark corpora, media, and future physical-corpus artifacts may carry separate licenses or usage terms. The repository's MIT software license does not automatically grant rights to separately identified data or third-party content. From 006f815b9653dc3ef9875ee9d1a87af59330dac9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mat=C3=A9o=20H=2E=20Petel?= <113530345+fraware@users.noreply.github.com> Date: Tue, 25 Aug 2026 06:14:28 -0700 Subject: [PATCH 4/6] Declare repository software license metadata --- package.json | 1 + 1 file changed, 1 insertion(+) diff --git a/package.json b/package.json index fdb2e82..c92c130 100644 --- a/package.json +++ b/package.json @@ -2,6 +2,7 @@ "name": "everything-rings", "private": true, "version": "0.0.0", + "license": "MIT", "packageManager": "pnpm@10.0.0", "scripts": { "build": "pnpm -r build", From 54588c820b92418298e90730ce57339ee6a02911 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mat=C3=A9o=20H=2E=20Petel?= <113530345+fraware@users.noreply.github.com> Date: Tue, 25 Aug 2026 06:15:13 -0700 Subject: [PATCH 5/6] Refresh capability registry after full-vision foundations --- docs/CLAIM_REGISTRY.md | 57 +++++++++++++++++++++--------------------- 1 file changed, 29 insertions(+), 28 deletions(-) diff --git a/docs/CLAIM_REGISTRY.md b/docs/CLAIM_REGISTRY.md index 5af6c38..7ef5d57 100644 --- a/docs/CLAIM_REGISTRY.md +++ b/docs/CLAIM_REGISTRY.md @@ -1,8 +1,8 @@ # Capability claim registry -Human-readable index of EVERYTHING RINGS capabilities and the maturity ladder that binds them. Machine-readable claim objects (`CapabilityClaimV1`, `SoftwareQualificationManifestV1`) live in `packages/validation` and are owned by the validation/assurance lane. This document does not change those contracts. +Human-readable index of EVERYTHING RINGS capabilities and the maturity ladder that binds them. Machine-readable capability registry and assurance objects live in `packages/validation` and are owned by the validation/assurance lane. This document does not change those contracts. -Software qualification never implies physical evidence. A green CI run, an SBOM, or a digital-twin report is not Gate A2/B/C, microphone validation, object identity, or material identity. +Software qualification never implies physical evidence. A green CI run, SBOM, digital-twin report, local Atlas service test, or synthetic benchmark is not Gate A2/B/C, microphone validation, physical-object identity, or material identity. ## Maturity ladder @@ -20,20 +20,16 @@ Physical and product-facing scientific claims must not skip rungs: | product-eligible | Independent review (reviewer ≠ implementer) accepted the claim for product copy | as declared | | released | Shipped under that exact proposition, version, population, and exclusions | as declared | -`CapabilityClaimV1` currently enumerates `implemented` | `software-qualified` | `empirically-qualified`. Map as follows until the validation lane extends the enum: +The machine-readable capability registry is the implementation authority for maturity transitions. Older `CapabilityClaimV1` assurance objects remain valid only within their own contract semantics; do not infer a higher rung from a less expressive historical enum. -- `prototype` ↔ `implemented` -- `software-qualified` and `synthetic-qualified` ↔ `software-qualified` (synthetic-qualified additionally requires digital-twin evidence) -- `physical-research` through `released` ↔ `empirically-qualified` only when empirical-domain evidence is attached; do not stamp `empirically-qualified` for software-only work - -## Claim fields (every row) +## Claim fields Each capability binds: - exact proposition; - algorithm / contract version; -- population (or "none — software only"); -- exclusions (what it does **not** establish); +- population (or `none — software only`); +- exclusions—what it does **not** establish; - source artifacts / evidence domain; - metrics if any; - trust boundary; @@ -44,25 +40,30 @@ Each capability binds: Rungs below are the highest currently earned. They are not aspirations. -| Capability | Proposition | Version | Population | Current rung | Exclusions | -|------------|-------------|---------|------------|--------------|------------| -| Resonance estimation | Estimated audible resonances supported by each recorded transient under `er-dsp-2` | `er-dsp-2` | software path; physical campaign not yet closed | software-qualified | Not eigenmodes, not object identity, not a universal signature, not proof nearby peaks are the same physical mode | -| Reconstruction | Modal reconstruction synthesizes estimated modes from a fingerprint; recorded PCM is not mixed into the model | modal renderer on frozen fingerprint | software | software-qualified | Not calibrated loudness; not a physical playback-chain claim | -| Playable identity | Chromatic playable instrument from a fingerprint-derived model | modal instrument | software / consumer path | software-qualified | Not authenticity; not a canonical object ID | -| Station qualification | Station protocol and diagnostic/verified evaluators exist as software contracts | `packages/validation` station-calibration | digital-station tests only | software-qualified | Does not establish that a physical booth reproduces a reference object | -| Twin retrieval | Deterministic retrieval ranks the correct digital specimen in the named software corpus | sonic-twin index / baseline | built-in digital qualification corpus | synthetic-qualified | Not physical-object identity; not a consumer "same object" score | -| Twin verification | match / nonmatch / abstain baseline and calibration contracts exist | `sonic-twin-isotonic-calibration-2` | digital held-out groups in software tests | synthetic-qualified | Calibrated probability is not a universal same-object probability | -| Spatial prediction | `fingerprintAtSpatialPoint` returns a predicted fingerprint | spatial field V1 | software | software-qualified | Predicted fingerprints are `evidenceEligible: false` and are never measurements | -| Material inference | Centroid baseline exists as research | `material-centroid-research-1` | software research tests | prototype | `evidenceEligible: false`; `calibratedProbability: null`; not a consumer material label | -| Atlas integrity | Content-addressed Atlas records, snapshots, collections, and merges detect mutation in software tests | Atlas V1 contracts | software | software-qualified | Not a production network; not physical provenance truth | -| Atlas network conformance | `MemoryResonanceAtlasServiceV1` passes the in-memory conformance harness | `resonance-atlas-service-1` | software | software-qualified | Production adapter, durability, authz, and rate limits are not claimed; see workflow skeleton | -| Measurement provenance | `MeasurementRecordV1` / `DerivationRecordV1` content-address one measurement and single-source derivations | provenance V1 | software | software-qualified | V1 has a single `measurementId`; V2 multi-source graphs are not claimed | -| Artifact integrity | Artifact envelopes detect payload tampering; SHA-256 of source files is exact bytes | envelope V1; `er-cli` hash | software | software-qualified | Hashing is not a freeze; CLI is not the v8 evidence-production path | -| Browser consumer loop | STRIKE → REVEAL → HEAR → PLAY on synthetic/browser-injected audio in CI | consumer web | CI browser smoke | software-qualified | Not a physical microphone path; not Gate A2 | -| Empirical v8 campaign | Gate A2/B/C under frozen contracts | `gate-a-2`, `gate-b-1`, `gate-c-1`, `validation-evidence-5` | intended physical campaign | prototype | Not run; software must not change thresholds. E1 exits on recorded PASS or fail | +| Capability | Proposition | Version / contract | Population | Current rung | Exclusions | +|------------|-------------|--------------------|------------|--------------|------------| +| Resonance estimation | Estimated audible resonances supported by each recorded transient under the canonical baseline | `er-dsp-2` | software path; physical campaign not yet closed | **software-qualified** | Not complete structural eigenmodes, not object identity, not a universal signature, not proof nearby peaks are the same physical mode | +| Reconstruction | Modal reconstruction synthesizes estimated modes from a fingerprint; recorded PCM is not mixed into the model | canonical modal renderer | software | **software-qualified** | Not calibrated loudness; not a physical playback-chain claim | +| Playable instrument | Chromatic instrument is synthesized from the fingerprint-derived modal model | modal instrument | software / consumer path | **software-qualified** | Not authenticity; not a canonical object ID; not Gate C physical playback evidence | +| Browser consumer loop | STRIKE → REVEAL → HEAR → PLAY executes through the browser journey under synthetic/browser-injected audio | consumer web | CI browser qualification | **software-qualified** | Not a physical microphone path; not Gate A2 | +| Station qualification | Versioned station protocols, status records, and evaluators exist and verify their software contracts | station-calibration contracts | digital-station tests only | **software-qualified** | Does not establish that a real station reproduces a reference specimen | +| Twin retrieval | Deterministic retrieval ranks specimens in named digital benchmark populations | Sonic Twin index / deterministic baseline | built-in digital qualification populations | **synthetic-qualified** | Not physical-object identity; not a consumer same-object score | +| Twin verification | Match / nonmatch / abstain comparison and held-out calibration contracts execute on disjoint digital groups | `sonic-twin-isotonic-calibration-2` + baseline | digital held-out groups | **synthetic-qualified** | Calibrated probability is not a universal physical same-object probability | +| Spatial prediction | A spatial modal field predicts a fingerprint at a modeled strike point | spatial field V1 | software | **software-qualified** | Predicted fingerprints are `evidenceEligible: false` and are never measurements | +| Material inference | Modal-summary centroid baseline performs research-only material prediction with abstention | `material-centroid-research-1` | software research tests | **prototype** | `evidenceEligible: false`; `calibratedProbability: null`; not a physical material-identification claim | +| Measurement provenance | Content-addressed measurement records preserve acquisition/fingerprint identity; downstream derivations can be single-source V1 or multi-source V2, with explicit measurement source links | `measurement-record-1`, derivation V1/V2, measurement-source-link | software | **software-qualified** | No physical corpus has yet been migrated under this post-freeze model; content integrity does not prove physical truth | +| Artifact integrity | Artifact envelopes and verification tooling detect payload mutation and compute exact-byte SHA-256 digests | artifact envelope contracts + `er-cli` | software | **software-qualified** | Hashing proves byte identity, not scientific validity; independent tooling is not the frozen v8 evidence-production path | +| Atlas V1 integrity | Content-addressed Atlas records, snapshots, collections, merges, and registry integrity detect software-level mutation | Atlas V1 contracts | software | **software-qualified** | Not a production network; not proof that asserted specimen metadata are physically true | +| Atlas V2 semantics | Public observations, externally grounded specimen records, membership assertions, and assurance levels are versioned and independently verifiable | Atlas V2 contracts | software | **software-qualified** | Does not infer membership from fingerprint equality or similarity; no public corpus claim | +| Atlas client + API contracts | Typed client and local file-backed HTTP service implement publication/read/search/contract behavior covered by conformance, HTTP, persistence, and V2 tests | Atlas client/API + service contracts | local software | **software-qualified** | No production authz, rate limiting, multi-tenant hosting, public-network security qualification, or operational SLA | +| Research corpus governance | Benchmark snapshots, readiness checks, group semantics, and material-truth assertions exist as software contracts | research-corpus contracts | software | **software-qualified** | Does not create a physical benchmark corpus or certify labels that were never collected | +| Similarity promotion governance | Candidate similarity algorithms can be compared against a deterministic baseline under held-out policy without silently accepting regressions | similarity promotion policy | software / digital tests | **software-qualified** | Policy execution is not physical identity validation and cannot promote a model beyond its evidence population | +| Empirical v8 campaign | Gate A2/B/C remain bound to the frozen physical/perceptual contracts | `gate-a-2`, `gate-b-1`, `gate-c-1`, `validation-evidence-5` | intended physical campaign | **prototype** | Not yet run; software qualification cannot advance this row | ## Promotion rule -Independent review is required before a high-stakes scientific claim becomes product-facing (reviewer ≠ implementer). Twin/Atlas UI copy and feature flags must not present a `software-qualified` or `synthetic-qualified` demo as `released` physical identity. +A capability advances only when evidence for the exact proposition, exact version, named population, exclusions, and trust boundary exists. High-stakes product-facing scientific claims require independent review before `product-eligible` or `released` status. + +Twin, material, station, and Atlas UI copy must never present a `software-qualified` or `synthetic-qualified` result as a released physical-world conclusion. Failed, abstained, missing, or unfavorable observations remain part of the evidence record when the governing protocol requires them. -Update this registry when evidence is attached, never because a workflow went green on synthetic inputs. +Update this registry when evidence is attached—not because a workflow went green on a different proposition. From 94559f8faa71d78a16e8c4922c7f30c437427eb9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mat=C3=A9o=20H=2E=20Petel?= <113530345+fraware@users.noreply.github.com> Date: Tue, 25 Aug 2026 06:15:55 -0700 Subject: [PATCH 6/6] Refresh final software release checklist --- docs/RELEASE_CHECKLIST.md | 167 +++++++++++++------------------------- 1 file changed, 55 insertions(+), 112 deletions(-) diff --git a/docs/RELEASE_CHECKLIST.md b/docs/RELEASE_CHECKLIST.md index 63bba1c..9b4285c 100644 --- a/docs/RELEASE_CHECKLIST.md +++ b/docs/RELEASE_CHECKLIST.md @@ -2,11 +2,13 @@ Use this checklist for any named software revision on `post-freeze-development`. It does not authorize empirical claims. Completing it never implies physical-object identity, microphone validity, material identity, or human-perceptual evidence. -Empirical authority remains `main` / `freeze/gate-a2-v8-2026-08-25` at `717a4c15a3b15e73c5883f34b86897c03ff70829`. Do not merge research or product work into `main` during the active v8 sequence. Do not change Gate A2/B/C thresholds or frozen contract semantics to "complete" a release. +Empirical authority remains `main` / `freeze/gate-a2-v8-2026-08-25` at `717a4c15a3b15e73c5883f34b86897c03ff70829`. Do not merge research or product work into `main` during the active v8 sequence. Do not change Gate A2/B/C thresholds or frozen contract semantics to complete a software release. -## License (#82) +## Software license -Issue #82 did not name a license. This tree records **MIT** in the root `LICENSE` file pending any owner amendment. Do not rewrite git history if the owner later selects a different license; add the new `LICENSE` on a subsequent commit. Dataset, model, and physical-corpus terms may require separate licenses later and are not implied by the software MIT grant. +Repository software is licensed under the root **MIT License**. The root package metadata and contribution guide should remain aligned with `LICENSE`. + +Dataset, trained-model, media, benchmark-corpus, and future physical-corpus artifacts may require separate terms. The software license must not be described as automatically licensing separately identified data or third-party content. ## Record these identifiers @@ -18,15 +20,16 @@ Copy exact values. Do not abbreviate commit SHAs. | Exact commit | `git rev-parse HEAD` (40 hex) | | | Tree | `git rev-parse HEAD^{tree}` | | | Tag / freeze name | Only after this revision itself is qualified. | | -| Ordinary CI run | GitHub Actions workflow `ci`, job `validate` | | +| Ordinary CI run | workflow `ci`, job `validate` | | | Digital-twin qualification run | workflow `digital-twin-qualification` | | | Full-vision software qualification run | workflow `full-vision-software-qualification` | | +| Atlas software-conformance run | workflow `atlas-production-conformance` | | | SBOM workflow/job run | CycloneDX JSON artifact from the qualification `sbom` job | | -| Atlas production-conformance run | workflow `atlas-production-conformance` (skeleton until `apps/atlas-api` exists) | | -| Qualification report digest | SHA-256 of the uploaded `full-vision-software.json` bytes | | -| Digital-twin report digest | SHA-256 of the uploaded digital-twin JSON bytes | | -| SBOM digest | SHA-256 of the uploaded CycloneDX JSON bytes | | -| Capability claims | Entries in `docs/CLAIM_REGISTRY.md` plus any machine-readable `CapabilityClaimV1` IDs | | +| Qualification report digest | SHA-256 of uploaded `full-vision-software.json` bytes | | +| Digital-twin report digest | SHA-256 of uploaded digital-twin JSON bytes | | +| Atlas conformance report digest | SHA-256 of uploaded Atlas conformance JSON bytes | | +| SBOM digest | SHA-256 of uploaded CycloneDX JSON bytes | | +| Capability claims | `docs/CLAIM_REGISTRY.md` plus machine-readable registry/claim IDs | | | Known exclusions | Must include: software qualification is not physical evidence | | Reproducibility command on a clean checkout of the named revision: @@ -43,139 +46,79 @@ Installs must use the committed `pnpm-lock.yaml`. Do not update the lockfile as ## Capability claims -List every product-facing proposition this revision is allowed to support, with maturity from `docs/CLAIM_REGISTRY.md`. Software qualification may support deterministic execution, artifact integrity, synthetic recovery, and named digital-population metrics. It does not support physical-object identity, material identity in the world, calibrated loudness, microphone-transducer behavior, or playback-chain fidelity. +List every product-facing proposition this revision is allowed to support, with maturity from `docs/CLAIM_REGISTRY.md`. Software qualification may support deterministic execution, artifact integrity, synthetic recovery, local service behavior, and named digital-population metrics. It does not support physical-object identity, material identity in the world, calibrated loudness, microphone-transducer behavior, or playback-chain fidelity. -Machine-readable claims, when emitted, use `CapabilityClaimV1` in `packages/validation`. The human-readable registry is the index. Do not promote a registry row past the evidence actually attached. +Machine-readable maturity and assurance objects live in `packages/validation`. The human-readable registry is the project index. Do not promote a registry row past the evidence actually attached. -## Known exclusions (required) +## Known exclusions — required State at least: -- No physical campaign object was tested by this software qualification. -- Gate A2/B/C status is independent of this checklist; see E1 below. -- `?twin=1` and `?atlas=1` remain synthetic demonstrations. -- Predicted spatial fingerprints remain `evidenceEligible: false`. -- Material inference remains research-only (`evidenceEligible: false`) until a held-out physical claim is earned. +- No physical campaign object was tested by software qualification. +- Gate A2/B/C status is independent of this checklist. +- `?twin=1` and `?atlas=1` remain synthetic/local research surfaces. +- Predicted spatial fingerprints remain non-measurement outputs and are not evidence-eligible measurements. +- Material inference remains research-only until a held-out physical claim is earned. +- Atlas client/API conformance is a local software-contract qualification, not a public production-network qualification. +- Content digests establish byte identity, not the truth of physical specimen/material assertions. ## Schema migration discipline -`packages/validation` owns versioned artifact schemas. This checklist does not change those packages. Every new or bumped artifact contract (`schemaVersion` / `*ContractVersion`) requires, in the validation package, before the contract is used in a release: +`packages/validation` owns versioned artifact schemas. Every new or bumped artifact contract (`schemaVersion` / `*ContractVersion`) requires, before use in a named release: 1. a parser that fails closed on unsupported versions; -2. a validator / content-address verification test; -3. an explicit migration test through `ArtifactMigrationRegistryV1` when a prior contract version must still be read. +2. validator/content-address verification tests; +3. an explicit migration test through the artifact migration registry when a prior contract version must remain readable; +4. exact test vectors for content-addressed contracts where cross-runtime stability matters. + +This discipline does not alter the frozen v8 evidence contract (`validation-evidence-5` / `schemaVersion: 5`). + +## Atlas software-contract conformance + +The repository now contains both `@everything-rings/atlas-client` and `@everything-rings/atlas-api`. The API has memory and local file-backed storage paths plus HTTP, persistence, service-conformance, and Atlas V2 tests. + +The `atlas-production-conformance` workflow therefore runs those packages directly. A successful report may state only that the named software revision passed the checked local contracts. It must retain: -CI comments in the qualification and Atlas conformance workflows restate this rule. Missing migration tests block adopting a new artifact version, not the frozen v8 evidence contract (`validation-evidence-5` / `schemaVersion: 5`). +- `softwareOnly: true`; +- `physicalObjectTested: false`; +- `releaseGateEquivalent: false`; +- `publicNetworkQualified: false`. -## E1 — empirical v8 support (tooling only) +Public-network production remains downstream of authentication/authorization, rate limits and abuse controls, multi-tenant durability/backup/restore, operational rollback/recovery, deployment security review, and load/concurrency characterization. + +## E1 — empirical v8 support Physical sequence, do not reorder: `#64 intended-device preflight → #65 specimen/manifest freeze → #66 collection / #25 Gate A2 adjudication → #28 Gate B → #29 Gate C` -This repository's software cannot execute that campaign. Independent verification tooling (`pnpm --filter @everything-rings/er-cli`) hashes source bytes and verifies evidence JSON against schema v5. It must never reserialize source evidence when reporting an original digest. It must never become part of the frozen evidence-production path. +This repository's post-freeze software cannot execute or substitute for that campaign. Independent verification tooling may hash source bytes and verify schema-v5 evidence, but it must never reserialize source evidence when reporting an original digest and must never become part of the frozen evidence-production path. **E1 exit:** Gate A2/B/C status is recorded under the frozen contracts, whether PASS or fail. Failure is an experimental result. Engineers must not change thresholds, attempt counts, or contract versions to obtain a pass. -Record gate status here when it exists (PASS / fail / not-yet-run). Do not leave E1 "done" by software work alone. - | Gate | Contract | Status | Evidence artifact digest | Notes | |------|----------|--------|--------------------------|-------| | A2 | `gate-a-2` / `validation-evidence-5` | not-yet-run | | Physical collection not performed in software | | B | `gate-b-1` | not-yet-run | | | | C | `gate-c-1` | not-yet-run | | | -## Branch protection / rulesets (#81) - -Required GitHub rulesets (repository policy only; not scientific evidence): - -### Ruleset A — `authority-pr-required` - -- Target: `refs/heads/main`, `refs/heads/post-freeze-development` -- Enforcement: active -- Rules: - - `deletion` (block branch deletion) - - `non_fast_forward` (block force-push) - - `pull_request` with `required_review_thread_resolution: true`, `required_approving_review_count: 0` until additional reviewers exist, `require_code_owner_review: false` until additional GitHub users exist, `dismiss_stale_reviews_on_push: true` - - `required_status_checks` with `strict_required_status_checks_policy: true` and check context `validate` (workflow `ci`, job `validate`; GitHub Actions app integration id `15368`) -- No bypass actors. A direct unreviewed push must be rejected. - -When additional maintainers exist, raise `required_approving_review_count` to 1 and set `require_code_owner_review: true`. - -### Ruleset B — `immutable-freeze-refs` - -- Target: `refs/heads/freeze/**` -- Enforcement: active -- Rules: `deletion`, `non_fast_forward` only -- New `freeze/*` refs may be created; existing freeze refs must not be rewritten or deleted. - -Example create payloads (REST `POST /repos/fraware/EVERYTHING-RINGS/rulesets`): - -```json -{ - "name": "authority-pr-required", - "target": "branch", - "enforcement": "active", - "conditions": { - "ref_name": { - "include": ["refs/heads/main", "refs/heads/post-freeze-development"], - "exclude": [] - } - }, - "rules": [ - { "type": "deletion" }, - { "type": "non_fast_forward" }, - { - "type": "pull_request", - "parameters": { - "required_approving_review_count": 0, - "dismiss_stale_reviews_on_push": true, - "require_code_owner_review": false, - "require_last_push_approval": false, - "required_review_thread_resolution": true - } - }, - { - "type": "required_status_checks", - "parameters": { - "strict_required_status_checks_policy": true, - "required_status_checks": [ - { "context": "validate", "integration_id": 15368 } - ] - } - } - ] -} -``` - -```json -{ - "name": "immutable-freeze-refs", - "target": "branch", - "enforcement": "active", - "conditions": { - "ref_name": { - "include": ["refs/heads/freeze/**"], - "exclude": [] - } - }, - "rules": [ - { "type": "deletion" }, - { "type": "non_fast_forward" } - ] -} -``` +## Repository rulesets -If the API rejects the create (permissions, enterprise policy, or check-name mismatch), record the HTTP status here and keep this section as the required configuration. +The authority branches and freeze refs are protected by active repository rulesets applied 2026-08-25: -**Applied 2026-08-25** (authenticated `gh api` as repository admin): +- `authority-pr-required` — id `21426242`; +- `immutable-freeze-refs` — id `21426245`. -- `authority-pr-required` id `21426242` — [ruleset](https://github.com/fraware/EVERYTHING-RINGS/rules/21426242) -- `immutable-freeze-refs` id `21426245` — [ruleset](https://github.com/fraware/EVERYTHING-RINGS/rules/21426245) +Required authority behavior: -GitHub stored additional pull-request defaults (`allowed_merge_methods`, `require_extra_approval_for_unattributed_changes`). Bypass actors remain empty (`current_user_can_bypass: never`). Direct pushes to `main` and `post-freeze-development` must go through a pull request; `ci` job `validate` is required; `freeze/**` cannot be force-pushed or deleted. +- `main` and `post-freeze-development` require pull requests; +- the `ci` / `validate` check is required; +- force pushes and deletion are blocked; +- review threads must be resolved; +- `freeze/**` refs cannot be force-pushed or deleted; +- bypass actors remain empty. -Observed before apply: classic branch protection was off for `main` and `post-freeze-development`, and `GET /repos/fraware/EVERYTHING-RINGS/rulesets` returned `[]`. +When additional maintainers exist, require at least one approving review and CODEOWNER review for authority-branch changes. ## GitHub Actions pins @@ -203,4 +146,4 @@ pnpm --filter @everything-rings/er-cli exec node ./bin/er.mjs verify derivation pnpm --filter @everything-rings/er-cli exec node ./bin/er.mjs verify repository path/to/repository.json ``` -`freeze dataset` and `inspect lineage` are stubs until E2. They exit 2 and must not be treated as a freeze or a lineage proof. +Verification tooling reports the contracts it actually checks. A command name or successful hash is never itself a scientific maturity promotion.