Phase 3 — structured L3 review panels

ARCHITECTURE.md

@@ -1,4 +1,4 @@
-# SAPIENS Phase-0 Architecture
+# SAPIENS Architecture (Phases 0–3)
 
 ## Design goals
 
@@ -13,7 +13,18 @@
 ```text
 src/sapiens/
   models.py       immutable candidate/evidence/manifest models
-  adapter.py      DomainAdapter protocol and Phase-0 adapter validation
+  adapter.py      DomainAdapter protocol; validation routes to the registry
+  registry.py     trust-tiered adapter registry (Phase 1)
+  permissions.py  owner-permission/licence manifest for third-party code (Phase 1)
+  isolation.py    subprocess + rlimit execution for UNTRUSTED adapters (Phase 1)
+  checkpoints.py  signed ledger checkpoints + external anchor export (Phase 1)
+  validation.py   L1/L2 automated gates + holdout protocols + leakage controls (Phase 2)
+  fixtures.py     seeded-bias fixture suite with labelled outcomes (Phase 2)
+  calibration.py  gate-performance calibration reports (Phase 2)
+  confidence.py   calibration-gated confidence aggregation (Phase 2)
+  review.py       L3 panel protocol: roles, objections, rounds, gates (Phase 3)
+  reviewers.py    deterministic reference reviewers, four roles (Phase 3)
+  catchrate.py    panel catch-rate scoring over seeded fixtures (Phase 3)
   ledger.py       JSONL hash-chain ledger and L0→L4 transition guard
   kernel.py       domain-neutral candidate registration and next-gate validation
   bridge.py       cross-domain structure transfer with mandatory L0 reset
@@ -32,7 +43,9 @@ Adapters may propose candidates and produce evidence, but they cannot set eviden
 
 Required methods:
 
-- `manifest`: domain name/version/vocabulary and `synthetic_only=True` for Phase 0.
+- `manifest`: domain name/version/vocabulary plus provenance facts
+  (`synthetic_only`, `code_origin`, `data_sources`, `third_party_source`).
+  The Phase-1 registry derives a trust tier from these facts.
 - `propose(seed, limit)`: deterministic candidates.
 - `validate(candidate, stage, seed, context)`: bounded evidence for `internal`, `replication`, or `review`.
 - `import_structure(structure, candidate_id)`: target-domain candidate from cross-domain structure.
@@ -41,7 +54,15 @@ Required methods:
 
 The ledger is newline-delimited canonical JSON. Each event stores the previous event hash and its own hash. Replay validates sequence, hashes, candidate creation, evidence scope, one-step promotion, required evidence kinds, demotion reasons, and the L4 human gate.
 
-Hash chaining detects tampering but does **not** prove authorship, signatures, scientific truth, or external timestamping.
+Hash chaining detects tampering but does **not** prove authorship, scientific truth, or external timestamping. Phase-1 `checkpoint` events summarise the chain (event count + head hash) and may carry an HMAC-SHA256 signature (environment-held key, never stored); `sapiens.checkpoints` also exports/verifies external anchor files. HMAC is symmetric: it proves key possession, not third-party authorship.
+
+## Validation gates (Phase 2)
+
+`DiscoveryKernel(validation=ValidationGates(...))` opts into automated L1/L2 gates. L1 runs statistical sanity checks over a candidate's internal evidence (determinism across identical reruns, degenerate constant scores, score presence). L2 requires a declared `HoldoutProtocol` for the domain and enforces holdout discipline: replication evidence must come from declared holdout datasets, dataset collisions and (dataset, seed) reuse across the boundary are leakage and reject the gate, and a minimum pass fraction applies. Gate verdicts are appended to `kernel.gate_log` (inspectable, recomputable) — the kernel never fabricates gate outcomes as ledger evidence. Gates are pure functions in `sapiens.validation`; `sapiens.fixtures` ships a labelled seeded-bias suite; `sapiens.calibration` scores gates against it; `sapiens.confidence` refuses to aggregate confidence without the resulting report.
+
+## L3 review panels (Phase 3)
+
+`DiscoveryKernel(panel=ReviewPanel(...))` gates L3 promotion on a structured panel. Reviewers are pure deterministic functions in four roles (statistician, domain theorist, methodologist, devil's advocate). The panel convenes bounded rounds; objections carry severity (MINOR/MAJOR/BLOCKING) and a tracked lifecycle (raised/sustained/withdrawn); reference reviewers escalate re-affirmed MAJOR findings to BLOCKING. Approval requires no sustained MAJOR/BLOCKING objection; MINOR caveats are recorded but non-fatal. The panel's verdict is recorded in the ledger as review evidence (`panel-transcript` dataset) — approval adds it to the promotion refs, rejection leaves the candidate at L2 with the rejection on record. `sapiens.catchrate` scores panels against the seeded fixture suite.
 
 ## Cross-domain bridge
 
@@ -51,4 +72,4 @@ Hash chaining detects tampering but does **not** prove authorship, signatures, s
 
 `WorkQueue` gives bounded jobs, serialized payload-size limits, idempotency keys, leases, stale-lease rejection, and retry/dead states. `DiscoveryDaemon.run_bounded` executes only explicitly registered handlers under time/step budgets; it does not dynamically import or shell out from queue payloads.
 
-Phase 0 uses cooperative in-process preemption. Subprocess/cgroup isolation is a roadmap item before untrusted adapters.
+Synthetic and CORE (first-party, real-data) adapters run in-process with cooperative preemption. UNTRUSTED (third-party) adapters run only via `sapiens.isolation`: a child process applies POSIX rlimits (CPU, address space, open files) to itself, the parent enforces a wall-clock timeout, and every failure mode is contained fail-closed (no evidence on failure). Third-party adapters additionally require a recorded owner permission (`permissions.json`, empty by default) before the registry will validate them at all. rlimits bound resources; they are not a full security sandbox.

PROVENANCE.md

@@ -33,3 +33,16 @@ No third-party source code is included. Therefore no third-party notices are emb
 ## Known licence gate
 
 ASTRA-dev/ASTRA/GEODISC/BIODISC lack explicit licences at inspected refs. Any future kernel extraction from those repositories requires a signed/committed compatible licence or separate written permission. Until then: architecture-only references or clean-room reimplementation only.
+
+## Phase 1 — permission manifest mechanism
+
+Phase 1 operationalises the gate: [`permissions.json`](permissions.json) is the
+machine-readable owner-permission manifest consumed by `sapiens.permissions`
+and enforced by `sapiens.registry`. Any adapter declaring
+`code_origin="third-party"` is UNTRUSTED-tier: it cannot validate without a
+matching active permission entry (`adapter:<name>` scope for its declared
+`third_party_source`), and it executes only inside the resource-limited
+subprocess (`sapiens.isolation`). **The shipped manifest is empty** — zero
+ASTRA-family permissions — so the clean-room boundary above is enforced by
+code, not by convention. Entries may be added only with explicit owner
+sign-off (recorded grantor, licence, evidence reference, validity window).

README.md

@@ -8,8 +8,8 @@
 
 SAPIENS is an **experimental platform for traceable cross-domain
 scientific-discovery workflows** — a `DomainAdapter` boundary, a hash-chained
-L0→L4 evidence ledger, and kernel-gated promotions. **Phase 0: synthetic
-adapters only, no discoveries claimed.**
+L0→L4 evidence ledger, and kernel-gated promotions. **Phases 0–1 shipped:
+synthetic adapters only in practice, no discoveries claimed.**
 
 It provides the plumbing a discovery system needs before it can be trusted:
 a domain-neutral adapter boundary, an append-only hash-chained evidence
@@ -20,11 +20,13 @@ budgets.
 
 > **Read this first — despite the acronym:** SAPIENS is **not** AGI, ASI, or
 > superintelligence, and does not claim to be. It is an experimental research
-> platform. **No scientific discoveries are claimed.** Phase 0 ships with
-> deterministic **synthetic adapters only**; the included examples discover
+> platform. **No scientific discoveries are claimed.** The shipped adapters
+> remain deterministic and **synthetic only**; the included examples discover
 > nothing about nature. The CLI reports `"scientific_discoveries_claimed": 0`
 > by construction, and the test suite enforces the honesty and boundary
-> invariants described below.
+> invariants described below. Phase 1 added the *machinery* for real-domain
+> work (trust tiers, isolation, permissions) — but no real-data adapter
+> ships yet.
 
 ## Why
 
@@ -39,7 +41,18 @@ inherits traceability and bounded confidence instead of retrofitting them.
 ```text
 src/sapiens/
   models.py       immutable candidate / evidence / manifest models
-  adapter.py      DomainAdapter protocol + Phase-0 adapter validation
+  adapter.py      DomainAdapter protocol; validation routes to the registry
+  registry.py     trust-tiered adapter registry (SYNTHETIC / CORE / UNTRUSTED)
+  permissions.py  owner-permission/licence manifest for third-party code
+  isolation.py    subprocess + rlimit execution for UNTRUSTED adapters
+  checkpoints.py  HMAC-signed ledger checkpoints + external anchor export
+  validation.py   L1/L2 automated gates: sanity checks, holdout + leakage
+  fixtures.py     seeded-bias fixture suite (labelled ground truth)
+  calibration.py  gate-performance calibration reports
+  confidence.py   calibration-gated confidence aggregation (refuses blindly)
+  review.py       L3 panel protocol: roles, objections, multi-round gate
+  reviewers.py    deterministic reference reviewers (four roles)
+  catchrate.py    panel catch-rate scoring over the seeded fixtures
   ledger.py       JSONL hash-chained evidence ledger, L0→L4 transition guard
   kernel.py       domain-neutral DiscoveryKernel; owns all promotions
   bridge.py       cross-domain structure transfer — ALWAYS resets target to L0
@@ -68,7 +81,7 @@ Key design rules (enforced by tests in [`tests/`](tests/)):
   - **L2 Replication** — passed held-out / reproducibility checks.
   - **L3 Review** — passed bounded structured review / adversarial checks.
   - **L4 External-ready** — requires an explicit **human gate**; autonomous
-    promotion to L4 is disabled in Phase 0.
+    promotion to L4 is disabled.
 - **Kernel-owned promotions** — adapters propose, only the `DiscoveryKernel`
   promotes, and only through the ledger's transition guard.
 - **Cross-domain bridge resets to L0** — transfer moves *structure and
@@ -156,33 +169,60 @@ astrophysical result**.
 
 ## Status & roadmap
 
-**Phase 0 — shipped** (current package version `0.1.0`): clean-room foundation,
+**Phase 0 — shipped** (package version `0.1.0`): clean-room foundation,
 three deterministic synthetic adapters, synthetic-only orchestration,
 hash-chained ledger, kernel gates, bridge, bounded queue/daemon, and CI on
-Python 3.10/3.11/3.12. The test suite currently includes positive and negative
-period-detection fixtures, L0 reset/provenance checks, ledger tamper checks,
-promotion guards, and bounded queue/daemon behavior.
+Python 3.10/3.11/3.12.
+
+**Phase 1 — shipped** (package version `0.2.0`): the synthetic-only
+gate is replaced by a **trust-tiered adapter registry** (SYNTHETIC / CORE /
+UNTRUSTED), an **owner-permission/licence manifest**
+([`permissions.json`](permissions.json) — empty by default: no third-party
+code may power an adapter without a recorded entry), **subprocess isolation
+with OS-level resource limits** for UNTRUSTED adapters (rlimit CPU /
+address-space / open-files plus wall-clock timeout, fail-closed), and
+**HMAC-signed ledger checkpoints** with external anchor export
+(key from the environment only, never stored). No real-data adapter ships in
+Phase 1; tiers are exercised by synthetic adapters and test doubles.
+
+**Phase 2 — shipped** (package version `0.3.0`): automated L0→L2
+**validation gates** — L1 statistical sanity checks (determinism,
+degenerate-score rejection) and L2 declared holdout protocols with explicit
+leakage controls (dataset collision, (dataset, seed) reuse) — plus a
+labelled **seeded-bias fixture suite** (known-good / overfit / leakage /
+degenerate), **calibration reports** (catch rate and false-reject rate with
+sample counts), and **calibration-gated confidence aggregation** that
+refuses to emit a number without sufficient calibration data.
+
+**Phase 3 — shipped** (current package version `0.4.0`): structured **L3
+review panels** — four role-specialized deterministic reviewers
+(statistician, domain theorist, methodologist, devil's advocate), a bounded
+multi-round protocol with objection lifecycle tracking (raised / sustained
+/ withdrawn) and disagreement gates (sustained MAJOR/BLOCKING objections
+reject; MINOR caveats are recorded but non-fatal), panel verdicts recorded
+in the ledger as review evidence, and **catch-rate scoring** over the
+seeded fixture suite (panel catches 3/3 known-bad, 0 false rejects — exact
+for this suite, not an estimate).
 
 Next, in order (see [`ROADMAP.md`](ROADMAP.md)):
 
-1. **Phase 1** — legal/licence gate and adapter hardening (trust-tiered
-   adapter registry, sandboxing, signed ledger checkpoints).
-2. **Phase 2** — validation framework v1 (statistical gates, holdout
-   protocols, leakage controls, seeded-bias fixtures, calibration).
-3. **Phase 3** — structured L3 review panels (role-specialized reviewers,
-   multi-round objection tracking, catch-rate scoring).
-4. **Phase 4** — **real domain adapters** (ASTRA / GEODISC / BIODISC / SLATE)
-   — only after licence and owner review.
+1. ~~**Phase 1** — legal/licence gate and adapter hardening~~ **shipped**.
+2. ~~**Phase 2** — validation framework v1~~ **shipped**.
+3. ~~**Phase 3** — structured L3 review panels~~ **shipped**.
+4. **Phase 4** — **real domain adapters** — first a clean-room Kepler
+   photometry adapter on public NASA/MAST data; ASTRA / GEODISC / BIODISC /
+   SLATE adapters only after licence and owner review.
 5. **Phase 5** — external-review workflows with human L4 gates and
    reproduction bundles.
 
 ## Provenance & legal boundary
 
-SAPIENS Phase 0 is a **clean-room implementation**: no source code from
+SAPIENS is a **clean-room implementation**: no source code from
 ASTRA-dev, ASTRA, GEODISC, BIODISC, or SLATE was copied into this repository
-(those codebases carry unresolved licensing; reuse is explicitly gated to
-Phase 1+ with owner permission). See [`PROVENANCE.md`](PROVENANCE.md) for the
-documented boundary.
+(those codebases carry unresolved licensing; reuse is gated on recorded owner
+permission — the Phase-1 permission manifest ships empty, so every
+third-party adapter is refused today). See [`PROVENANCE.md`](PROVENANCE.md)
+for the documented boundary.
 
 ## Credits
 

ROADMAP.md

@@ -7,27 +7,77 @@
 - Synthetic integrated orchestration.
 - Tests and Python matrix CI.
 
-## Phase 1 — legal/licence gate and adapter hardening
+## Phase 1 — shipped (package version 0.2.0)
 
-- Obtain explicit licences/permissions for any ASTRA-family code reuse before extraction.
-- Replace synthetic-only adapter gate with a trust-tiered adapter registry.
-- Add subprocess isolation and OS-level resource limits for untrusted adapters.
-- Add signed ledger checkpoints or external anchoring.
+Legal/licence gate and adapter hardening:
 
-## Phase 2 — validation framework v1
+- ~~Obtain explicit licences/permissions for any ASTRA-family code reuse
+  before extraction.~~ Mechanism shipped: `permissions.json` +
+  `sapiens.permissions` record owner grants; the manifest is **empty** — no
+  ASTRA-family (or any third-party) permissions exist, so every third-party
+  adapter is refused until an owner records one.
+- ~~Replace synthetic-only adapter gate with a trust-tiered adapter
+  registry.~~ Shipped: `sapiens.registry` (SYNTHETIC / CORE / UNTRUSTED).
+- ~~Add subprocess isolation and OS-level resource limits for untrusted
+  adapters.~~ Shipped: `sapiens.isolation` — rlimit CPU / address-space /
+  open-files plus wall-clock timeout, fail-closed; the kernel runs
+  UNTRUSTED-tier adapters only through it.
+- ~~Add signed ledger checkpoints or external anchoring.~~ Shipped:
+  `sapiens.checkpoints` — HMAC-SHA256 checkpoint events (key from
+  environment only) plus external anchor export/verify.
 
-- Expand L0→L2 automated gates with statistical sanity checks, holdout protocols, and explicit leakage controls.
-- Add seeded-bias fixtures and calibration reports.
-- Add confidence aggregation only after calibration data exists; do not invent precision.
+Honest limits: rlimits bound resource use but are not a security sandbox;
+HMAC proves local key possession, not third-party authorship. No real-data
+adapter ships in Phase 1.
 
-## Phase 3 — structured L3 review panels
+## Phase 2 — shipped (package version 0.3.0)
 
-- Role-specialized reviewer schemas: statistician, domain theorist, methodologist, devil's advocate.
-- Multi-round reports, objection tracking, disagreement gates.
-- Catch-rate scoring on seeded known-bad and known-good candidates.
+Validation framework v1:
+
+- ~~Expand L0→L2 automated gates~~ Shipped: `sapiens.validation` — L1
+  internal-consistency gate (score presence/range, determinism across reruns,
+  degenerate constant-score rejection) and L2 holdout-replication gate
+  (declared `HoldoutProtocol` per domain; explicit leakage controls on
+  dataset collision and (dataset, seed) reuse; pass-fraction threshold).
+  Opt-in kernel wiring via `DiscoveryKernel(validation=...)`; gate verdicts
+  are logged, never fabricated as evidence; a configured domain without a
+  declared protocol fails closed.
+- ~~Add seeded-bias fixtures and calibration reports.~~ Shipped:
+  `sapiens.fixtures` (known-good / overfit / leakage / degenerate, labelled
+  with expected outcomes) and `sapiens.calibration` (`CalibrationReport`:
+  catch rate, false-reject rate, sample counts; report ids are content
+  hashes).
+- ~~Add confidence aggregation only after calibration data exists~~ Shipped:
+  `sapiens.confidence.aggregate_confidence` raises `UncalibratedError`
+  without a sufficiently sampled calibration report; with one, it emits a
+  documented heuristic (raw pass fraction × demonstrated catch rate) with
+  full provenance. No invented precision.
+
+## Phase 3 — shipped (package version 0.4.0)
+
+Structured L3 review panels:
+
+- ~~Role-specialized reviewer schemas~~ Shipped: `sapiens.review` —
+  statistician, domain theorist, methodologist, devil's advocate; typed
+  approve/object/abstain verdicts with severity-graded objections.
+- ~~Multi-round reports, objection tracking, disagreement gates~~ Shipped:
+  bounded deterministic multi-round protocol; objection lifecycle
+  (raised/sustained/withdrawn) tracked in every `PanelReport`; sustained
+  MAJOR/BLOCKING objections reject, MINOR caveats are recorded but
+  non-fatal (documented gate semantics). Deterministic reference reviewers
+  in `sapiens.reviewers` re-run the Phase-2 gates independently and hunt
+  seeded-bias signatures.
+- ~~Catch-rate scoring~~ Shipped: `sapiens.catchrate.score_panel` over the
+  seeded fixture suite — per-role and panel-level catch rates plus
+  false-reject rate, with an explicit small-sample caveat.
+- Kernel integration: with a panel configured, L3 promotion requires panel
+  approval, and the verdict is recorded in the ledger as review evidence
+  (no side channel). Without a panel, Phase-2 behaviour is unchanged.
 
 ## Phase 4 — real domain adapters
 
+- First: one clean-room Kepler photometry adapter on public NASA/MAST data
+  (reuses this repository's own Apache-2.0 demo pipeline path).
 - ASTRA/GEODISC/BIODISC/SLATE adapters only after licence and owner review.
 - Domain-specific validators remain sandboxed behind adapters.
 - Cross-domain method transfer enters target domain at L0 every time.