Skip to content

Commit eb2279b

Browse files
frawarefraware
committed
Make COMMUNITY_LAYER the public front door and freeze published-runs v1 API
Prominent README start block, v1 API/CLI guarantees, publication README template, claim phrase linter, and polished examples with load_published_runs_api walkthrough.
1 parent 8d10ac8 commit eb2279b

29 files changed

Lines changed: 640 additions & 147 deletions

‎CHANGELOG.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,12 @@
22

33
## Reference system (host-realistic flagship)
44

5+
### 2026-05-28 — Community front door and frozen published-runs v1 API
6+
7+
- README **Start here** block; [COMMUNITY_LAYER.md](docs/COMMUNITY_LAYER.md) as default public map.
8+
- [PUBLISHED_RUNS_API.md](docs/PUBLISHED_RUNS_API.md) v1 stability contract; CLI `summary` / `provenance`.
9+
- Publication-grade bundle README template + `check_public_claim_phrases.py`; examples discipline pass.
10+
511
### 2026-05-28 — v1 lock verification script
612

713
- `scripts/verify_v1_lock.py` + `make verify-v1-lock-quick`; CONTRIBUTING leads with Community layer for consumers.

‎CONTRIBUTING.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,13 @@ Thank you for contributing. This repository separates **public structural CI** f
1313
3. For benchmark/governance changes, run `make verify-reference-system` and `make community-verify` when touching published bundles or `conicshield.published_runs`.
1414
4. Read [`docs/CI_MERGE_GATES.md`](docs/CI_MERGE_GATES.md), [`docs/REVIEWER_MERGE_CHECKLIST.md`](docs/REVIEWER_MERGE_CHECKLIST.md), and [`docs/REFERENCE_EVIDENCE_TIERS.md`](docs/REFERENCE_EVIDENCE_TIERS.md).
1515

16+
## Public claim surface (review rule)
17+
18+
Any PR that changes **README**, **docs/**, **examples/**, or **published bundle READMEs** in ways that affect what outsiders may believe must:
19+
20+
1. Cite alignment with at least one authority doc: [`docs/PUBLIC_CLAIMS.md`](docs/PUBLIC_CLAIMS.md), [`docs/ROADMAP.md`](docs/ROADMAP.md), [`docs/DIFFERENTIATION_PUBLIC_STANCE.md`](docs/DIFFERENTIATION_PUBLIC_STANCE.md), or [`docs/SOLVER_PATHS_AND_BATCHING.md`](docs/SOLVER_PATHS_AND_BATCHING.md) (in PR description or diff comments).
21+
2. Pass `python scripts/check_public_claim_phrases.py` (also run via `make verify-v1-lock-quick`).
22+
1623
## Required CI (public lane)
1724

1825
These checks run on every PR to `main` and should be green:

‎README.md‎

Lines changed: 21 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,26 @@
2020

2121
A policy proposes an action. ConicShield solves a constrained optimization problem to find the **nearest admissible** action under explicit safety constraints. The world sees the **corrected** action, not the raw proposal. Every intervention yields structured records you can hash, audit, and benchmark under family policy.
2222

23+
---
24+
25+
## Start here
26+
27+
| You want to… | Go here |
28+
|--------------|---------|
29+
| **Use or cite published benchmarks** (recommended for outsiders) | **[Community layer](docs/COMMUNITY_LAYER.md)** — quickstarts, `conicshield.published_runs` API, runnable [examples](examples/README.md) |
30+
| **Operate the reference system** (maintainers, auditors) | [Documentation index](docs/README.md) — cadence, governance, refresh procedures |
31+
32+
The **community entrypoint** is for researchers, integrators, and anyone consuming `host-realistic-20260525` without reading internal policy graphs. **Maintainer / reference-system docs** live under [`docs/README.md`](docs/README.md) and [`docs/REFERENCE_SYSTEM.md`](docs/REFERENCE_SYSTEM.md).
33+
34+
```bash
35+
pip install -e ".[dev]"
36+
python examples/verify_published_run_index.py # researcher: index + flagship verify
37+
python -m conicshield.published_runs.cli current # family current_run_id
38+
make verify-v1-lock-quick # auditor: is v1 still coherent?
39+
```
40+
41+
---
42+
2343
```mermaid
2444
flowchart LR
2545
Q[Scores / Q-values] --> S[ConicShield]
@@ -59,9 +79,7 @@ Refresh: `make host-realistic-refresh-cycle-licensed` — [`docs/HOST_REALISTIC_
5979

6080
**Batch:** governed; viability-tested — not universal speedup ([`docs/SOLVER_PATHS_AND_BATCHING.md`](docs/SOLVER_PATHS_AND_BATCHING.md)). **Differentiation:** validation-only ([`docs/DIFFERENTIATION_PUBLIC_STANCE.md`](docs/DIFFERENTIATION_PUBLIC_STANCE.md)).
6181

62-
**Start here:** [Community layer](docs/COMMUNITY_LAYER.md) · [Researcher](docs/QUICKSTART_RESEARCHER.md) · [Integrator](docs/QUICKSTART_INTEGRATOR.md) · [Maintainer](docs/QUICKSTART_MAINTAINER.md) · [Examples](examples/README.md)
63-
64-
Docs index: [`docs/README.md`](docs/README.md). Local: `make verify-v1-lock`, `make community-verify`, `python -m conicshield.published_runs.cli list`. Maintainer lock: [`docs/V1_LOCK_CHECKLIST.md`](docs/V1_LOCK_CHECKLIST.md).
82+
Published-run API: [`docs/PUBLISHED_RUNS_API.md`](docs/PUBLISHED_RUNS_API.md) · Claims: [`docs/PUBLIC_CLAIMS.md`](docs/PUBLIC_CLAIMS.md)
6583

6684
## Installation
6785

‎benchmarks/PUBLISHED_RUN_INDEX.json‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"schema_version": 2,
3-
"generated_at_utc": "2026-05-28T18:06:51Z",
3+
"generated_at_utc": "2026-05-28T18:32:05Z",
44
"published_root": "benchmarks/published_runs",
55
"governed_run_ids": [
66
"host-realistic-20260525",
@@ -49,7 +49,7 @@
4949
"sha256": "1db4e6dda92c509858f66dc377689bff9501829fab500f7b883207ed29d21afc"
5050
},
5151
"README.md": {
52-
"sha256": "964a574d4db5ba67b89f7bb30a35026d49f6ff4d157ca026cd7633b4f01ec86b"
52+
"sha256": "34772f5e47404fe66bee70d6ba0531ce079630db052fcf82c4deb0dd36b0f7a9"
5353
},
5454
"COMMUNITY_METADATA.json": {
5555
"sha256": "7f90be26414fc37cbf4264a2eb249e96fbd812cb5816440e6a96f9d9e9f55797"
@@ -105,7 +105,7 @@
105105
"sha256": "8ff93f876bc47fb202e445daafd9bbaec4f958ca739afad95b48057b22b03d4c"
106106
},
107107
"README.md": {
108-
"sha256": "77e1a39e23c4372f9c35bbb1fc08a4ce6fd2d371cd1e3016fa73419a94a49d8c"
108+
"sha256": "8f10802c53bc74f0c9ef8d25ff3f629302fe653f67ebab54f697af2fd19adbd2"
109109
},
110110
"COMMUNITY_METADATA.json": {
111111
"sha256": "9ec9905740af298888ad444cd0bb6b95c665752a92ff3992f856543feca3371d"
@@ -164,7 +164,7 @@
164164
"sha256": "1db4e6dda92c509858f66dc377689bff9501829fab500f7b883207ed29d21afc"
165165
},
166166
"README.md": {
167-
"sha256": "ebb3b72b0c01d0bb069ad028adb68ca0c92c04a5128c2dede5113a1dc9c8e276"
167+
"sha256": "8cad5e7f35fddd1a17361654a56b493ab7abdba1c1ea970bc835e0f6f6e50d68"
168168
},
169169
"COMMUNITY_METADATA.json": {
170170
"sha256": "dc3b5406635ab19eeea7480e5f51090eca9a21e634a5343c94e991286f8b8b55"

‎benchmarks/published_runs/host-realistic-20260525/README.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Flagship **host-realistic** governed bundle: closed export→bank→publish loop at `vendor_native` with native Moreau arm and family `current_run_id`.
44

5+
Publication-grade governed benchmark bundle. Read [`COMMUNITY_METADATA.json`](COMMUNITY_METADATA.json) first.
6+
57
| Field | Value |
68
|-------|--------|
79
| `evidence_tier` | `vendor_native` |
@@ -13,7 +15,8 @@ Flagship **host-realistic** governed bundle: closed export→bank→publish loop
1315
| Export `export_kind` | `live_upstream_dump` |
1416
| Export source | `benchmarks/external_evidence/offline_graph_export_upstream.json` |
1517
| Parity status | `present` |
16-
| Scope contract | [`COMMUNITY_METADATA.json`](COMMUNITY_METADATA.json) |
18+
| Governance state | `published` |
19+
| Index integrity | Run `python -m conicshield.published_runs.cli verify` after clone |
1720

1821
## What this run proves
1922

@@ -24,25 +27,30 @@ Flagship **host-realistic** governed bundle: closed export→bank→publish loop
2427
## What this run does not prove
2528

2629
- Production differentiable shield / autograd product ([`docs/DIFFERENTIATION_PUBLIC_STANCE.md`](../../docs/DIFFERENTIATION_PUBLIC_STANCE.md))
27-
- Universal batch speedup ([`docs/SOLVER_PATHS_AND_BATCHING.md`](../../docs/SOLVER_PATHS_AND_BATCHING.md))
28-
- Full Maps/session navigation graph (fork topology unless provenance says otherwise)
30+
- Claim of universal batch throughput win ([`docs/SOLVER_PATHS_AND_BATCHING.md`](../../docs/SOLVER_PATHS_AND_BATCHING.md))
31+
- Full upstream Maps/session navigation graph (fork topology only unless provenance documents more)
2932

3033
## Validate and inspect
3134

3235
```bash
3336
python -m conicshield.published_runs.cli verify host-realistic-20260525
37+
python -m conicshield.published_runs.cli show host-realistic-20260525
3438
python -m conicshield.artifacts.validator_cli --run-dir benchmarks/published_runs/host-realistic-20260525
3539
python scripts/validate_published_bundle_profile.py --run-id host-realistic-20260525
3640
```
3741

38-
Python API:
42+
Python API (v1 stable — see [`docs/PUBLISHED_RUNS_API.md`](../../docs/PUBLISHED_RUNS_API.md)):
3943

4044
```python
41-
from conicshield.published_runs import load_run, load_summary, verify_run
45+
from conicshield.published_runs import load_run, load_summary, load_provenance, verify_run
4246
verify_run('host-realistic-20260525')
4347
bundle = load_run('host-realistic-20260525')
4448
```
4549

50+
## Cite this artifact
51+
52+
Cite the **`run_id`**, repository **commit SHA**, and [`COMMUNITY_METADATA.json`](COMMUNITY_METADATA.json) scope. Distinguish **artifact identity** from scientific conclusions — see [`docs/CITING_CONICSHIELD_ARTIFACTS.md`](../../docs/CITING_CONICSHIELD_ARTIFACTS.md) and [`docs/PUBLIC_CLAIMS.md`](../../docs/PUBLIC_CLAIMS.md).
53+
4654
## Solver stack
4755

4856
- `cvxpy`: `1.8.2`

‎benchmarks/published_runs/wsl-native-20260409-091141/README.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Governed benchmark bundle `wsl-native-20260409-091141` at evidence tier `vendor_native`.
44

5+
Publication-grade governed benchmark bundle. Read [`COMMUNITY_METADATA.json`](COMMUNITY_METADATA.json) first.
6+
57
| Field | Value |
68
|-------|--------|
79
| `evidence_tier` | `vendor_native` |
@@ -13,7 +15,8 @@ Governed benchmark bundle `wsl-native-20260409-091141` at evidence tier `vendor_
1315
| Export `export_kind` | `live_upstream_dump` |
1416
| Export source | n/a |
1517
| Parity status | `n/a` |
16-
| Scope contract | [`COMMUNITY_METADATA.json`](COMMUNITY_METADATA.json) |
18+
| Governance state | `published` |
19+
| Index integrity | Run `python -m conicshield.published_runs.cli verify` after clone |
1720

1821
## What this run proves
1922

@@ -23,25 +26,30 @@ Governed benchmark bundle `wsl-native-20260409-091141` at evidence tier `vendor_
2326
## What this run does not prove
2427

2528
- Production differentiable shield / autograd product ([`docs/DIFFERENTIATION_PUBLIC_STANCE.md`](../../docs/DIFFERENTIATION_PUBLIC_STANCE.md))
26-
- Universal batch speedup ([`docs/SOLVER_PATHS_AND_BATCHING.md`](../../docs/SOLVER_PATHS_AND_BATCHING.md))
27-
- Full Maps/session navigation graph (fork topology unless provenance says otherwise)
29+
- Claim of universal batch throughput win ([`docs/SOLVER_PATHS_AND_BATCHING.md`](../../docs/SOLVER_PATHS_AND_BATCHING.md))
30+
- Full upstream Maps/session navigation graph (fork topology only unless provenance documents more)
2831

2932
## Validate and inspect
3033

3134
```bash
3235
python -m conicshield.published_runs.cli verify wsl-native-20260409-091141
36+
python -m conicshield.published_runs.cli show wsl-native-20260409-091141
3337
python -m conicshield.artifacts.validator_cli --run-dir benchmarks/published_runs/wsl-native-20260409-091141
3438
python scripts/validate_published_bundle_profile.py --run-id wsl-native-20260409-091141
3539
```
3640

37-
Python API:
41+
Python API (v1 stable — see [`docs/PUBLISHED_RUNS_API.md`](../../docs/PUBLISHED_RUNS_API.md)):
3842

3943
```python
40-
from conicshield.published_runs import load_run, load_summary, verify_run
44+
from conicshield.published_runs import load_run, load_summary, load_provenance, verify_run
4145
verify_run('wsl-native-20260409-091141')
4246
bundle = load_run('wsl-native-20260409-091141')
4347
```
4448

49+
## Cite this artifact
50+
51+
Cite the **`run_id`**, repository **commit SHA**, and [`COMMUNITY_METADATA.json`](COMMUNITY_METADATA.json) scope. Distinguish **artifact identity** from scientific conclusions — see [`docs/CITING_CONICSHIELD_ARTIFACTS.md`](../../docs/CITING_CONICSHIELD_ARTIFACTS.md) and [`docs/PUBLIC_CLAIMS.md`](../../docs/PUBLIC_CLAIMS.md).
52+
4553
## Further reading
4654

4755
- Consumer guide: [`docs/PUBLISHED_RUN_INDEX_FOR_CONSUMERS.md`](../../docs/PUBLISHED_RUN_INDEX_FOR_CONSUMERS.md)

‎benchmarks/published_runs/wsl-real-20260409-132450/README.md‎

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@
22

33
Governed benchmark bundle `wsl-real-20260409-132450` at evidence tier `vendor_reference`.
44

5+
Publication-grade governed benchmark bundle. Read [`COMMUNITY_METADATA.json`](COMMUNITY_METADATA.json) first.
6+
57
| Field | Value |
68
|-------|--------|
79
| `evidence_tier` | `vendor_reference` |
@@ -13,7 +15,8 @@ Governed benchmark bundle `wsl-real-20260409-132450` at evidence tier `vendor_re
1315
| Export `export_kind` | `live_upstream_dump` |
1416
| Export source | n/a |
1517
| Parity status | `n/a` |
16-
| Scope contract | [`COMMUNITY_METADATA.json`](COMMUNITY_METADATA.json) |
18+
| Governance state | `review-locked` |
19+
| Index integrity | Run `python -m conicshield.published_runs.cli verify` after clone |
1720

1821
## What this run proves
1922

@@ -23,25 +26,30 @@ Governed benchmark bundle `wsl-real-20260409-132450` at evidence tier `vendor_re
2326
## What this run does not prove
2427

2528
- Production differentiable shield / autograd product ([`docs/DIFFERENTIATION_PUBLIC_STANCE.md`](../../docs/DIFFERENTIATION_PUBLIC_STANCE.md))
26-
- Universal batch speedup ([`docs/SOLVER_PATHS_AND_BATCHING.md`](../../docs/SOLVER_PATHS_AND_BATCHING.md))
27-
- Full Maps/session navigation graph (fork topology unless provenance says otherwise)
29+
- Claim of universal batch throughput win ([`docs/SOLVER_PATHS_AND_BATCHING.md`](../../docs/SOLVER_PATHS_AND_BATCHING.md))
30+
- Full upstream Maps/session navigation graph (fork topology only unless provenance documents more)
2831

2932
## Validate and inspect
3033

3134
```bash
3235
python -m conicshield.published_runs.cli verify wsl-real-20260409-132450
36+
python -m conicshield.published_runs.cli show wsl-real-20260409-132450
3337
python -m conicshield.artifacts.validator_cli --run-dir benchmarks/published_runs/wsl-real-20260409-132450
3438
python scripts/validate_published_bundle_profile.py --run-id wsl-real-20260409-132450
3539
```
3640

37-
Python API:
41+
Python API (v1 stable — see [`docs/PUBLISHED_RUNS_API.md`](../../docs/PUBLISHED_RUNS_API.md)):
3842

3943
```python
40-
from conicshield.published_runs import load_run, load_summary, verify_run
44+
from conicshield.published_runs import load_run, load_summary, load_provenance, verify_run
4145
verify_run('wsl-real-20260409-132450')
4246
bundle = load_run('wsl-real-20260409-132450')
4347
```
4448

49+
## Cite this artifact
50+
51+
Cite the **`run_id`**, repository **commit SHA**, and [`COMMUNITY_METADATA.json`](COMMUNITY_METADATA.json) scope. Distinguish **artifact identity** from scientific conclusions — see [`docs/CITING_CONICSHIELD_ARTIFACTS.md`](../../docs/CITING_CONICSHIELD_ARTIFACTS.md) and [`docs/PUBLIC_CLAIMS.md`](../../docs/PUBLIC_CLAIMS.md).
52+
4553
## Solver stack
4654

4755
- `cvxpy`: `1.8.2`

‎benchmarks/reports/reference_system_status.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
{
22
"schema_version": "conicshield_reference_system_status/v1",
3-
"generated_at_utc": "2026-05-28T18:14:08Z",
3+
"generated_at_utc": "2026-05-28T18:32:31Z",
44
"flagship_run_id": "host-realistic-20260525",
55
"family_id": "conicshield-transition-bank-v1",
66
"reference_authority_aligned": true,
@@ -10,7 +10,7 @@
1010
"refresh_count": 4,
1111
"full_cycle_refresh_count": 1,
1212
"last_full_refresh_at_utc": "2026-05-28T17:00:56Z",
13-
"cadence_age_days": 0.05083969313657408,
13+
"cadence_age_days": 0.06360137756944444,
1414
"cadence_policy_ok": true,
1515
"full_refresh_cadence_ok": true,
1616
"batch_story": "throughput_win",

‎conicshield/published_runs/__init__.py‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,16 @@
1-
"""Public dataset interface for governed published benchmark bundles."""
1+
"""Public dataset interface for governed published benchmark bundles.
2+
3+
Stable v1 surface (do not rename without a major version bump):
4+
5+
- ``list_runs``, ``get_current_run``, ``load_run``, ``verify_run``
6+
- ``load_summary``, ``load_provenance``, ``load_episodes``
7+
- ``index_path``, ``ensure_community_metadata``
8+
9+
See ``docs/PUBLISHED_RUNS_API.md`` for stability guarantees.
10+
"""
211

312
from conicshield.published_runs.api import (
13+
PUBLISHED_RUNS_API_VERSION,
414
current_family_run,
515
ensure_community_metadata,
616
get_current_run,
@@ -22,6 +32,7 @@
2232
)
2333

2434
__all__ = [
35+
"PUBLISHED_RUNS_API_VERSION",
2536
"CommunityMetadata",
2637
"IntegrityEntry",
2738
"PublishedRunBundle",

0 commit comments

Comments
 (0)