Phase 1 — trust-tiered adapter registry, isolation, permissions, checkpoints

ARCHITECTURE.md

@@ -1,4 +1,4 @@
-# SAPIENS Phase-0 Architecture
+# SAPIENS Architecture (Phases 0–1)
 
 ## Design goals
 
@@ -13,7 +13,11 @@
 ```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)
   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 +36,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 +47,7 @@ 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.
 
 ## Cross-domain bridge
 
@@ -51,4 +57,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,11 @@ 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
   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 +74,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 +162,43 @@ 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** (current 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.
 
 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).
+1. ~~**Phase 1** — legal/licence gate and adapter hardening~~ **shipped**.
 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.
+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,12 +7,28 @@
 - Synthetic integrated orchestration.
 - Tests and Python matrix CI.
 
-## Phase 1 — legal/licence gate and adapter hardening
-
-- 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.
+## Phase 1 — shipped (package version 0.2.0)
+
+Legal/licence gate and adapter hardening:
+
+- ~~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.
+
+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 2 — validation framework v1
 
@@ -28,6 +44,8 @@
 
 ## 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.

permissions.json

@@ -0,0 +1,5 @@
+{
+  "version": 1,
+  "comment": "Owner permissions for third-party code reuse (Phase 1). EMPTY BY DEFAULT: no ASTRA-family (or any other third-party) permissions are recorded, so every third-party adapter is refused. Add entries only with explicit owner sign-off; see PROVENANCE.md.",
+  "entries": []
+}

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "sapiens-discovery"
-version = "0.1.0"
+version = "0.2.0"
 description = "Experimental foundation for traceable cross-domain scientific-discovery workflows"
 readme = "README.md"
 requires-python = ">=3.10"

src/sapiens/__init__.py

@@ -5,16 +5,22 @@
 from .kernel import DiscoveryKernel
 from .ledger import EvidenceLedger
 from .models import AdapterManifest, Candidate, Evidence, EvidenceLevel
+from .permissions import PermissionEntry, PermissionManifest
+from .registry import AdapterRegistry, TrustTier
 
 __all__ = [
     "AdapterManifest",
+    "AdapterRegistry",
     "Candidate",
     "DiscoveryKernel",
     "DomainAdapter",
     "Evidence",
     "EvidenceLedger",
     "EvidenceLevel",
+    "PermissionEntry",
+    "PermissionManifest",
     "TransferEnvelope",
+    "TrustTier",
     "transfer",
 ]
-__version__ = "0.1.0"
+__version__ = "0.2.0"

src/sapiens/adapter.py

@@ -25,8 +25,15 @@ def import_structure(self, structure: dict[str, object], *, candidate_id: str) -
 
 
 def validate_adapter(adapter: DomainAdapter) -> None:
-    if not isinstance(adapter, DomainAdapter):
-        raise TypeError("adapter does not implement DomainAdapter")
-    manifest = adapter.manifest
-    if not manifest.synthetic_only:
-        raise ValueError("Phase 0 refuses non-synthetic adapters")
+    """Phase-1 gate: auto-tiered registry validation.
+
+    Kept for backward compatibility with Phase-0 callers. Synthetic adapters
+    pass exactly as before; first-party clean-room real-data adapters pass at
+    CORE tier; third-party adapters require a recorded permission and raise
+    ``MissingPermissionError`` without one. Callers that need the tier (e.g.
+    the kernel, to decide on isolation) should use ``AdapterRegistry``
+    directly.
+    """
+    from .registry import AdapterRegistry
+
+    AdapterRegistry().validate_adapter(adapter)