runtime: enforce target, fallback, and evaluation boundary

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## Unreleased
+
+- Added a public `PTCNAEngine` receipt spanning neural, circle, seed, and core.
+- Added a deterministic hashed-linear fallback behind the same task interface.
+- Added explicit, attributed fallback routing; target failures still raise by
+  default.
+- Added immutable evaluation plans and terminal evidence receipts that freeze
+  workload, training schedule, comparator, post-training metric, thresholds,
+  resource limits, stopping, and failure propagation before execution.
+- Removed the broken deprecated FastAPI seed runner that imported nonexistent
+  `src.core` modules; `PTCNARuntime` is its supported replacement.
+
 ## 0.1.1 — 2026-07-29
 
 - Added the shared `ptcna.circle.CircleTensor` and one structural composition

README.md

@@ -41,6 +41,48 @@ pip install -e ".[dev]"      # neural layer needs numpy; seed/core are stdlib-on
 pytest                       # testpaths = ptcna
 ```
 
+## Experimental runtime and dependable fallback
+
+The intended architecture and the simpler fallback share one task interface but
+retain separate identities. PTCNA is selected by default. A target error raises
+unless the caller explicitly enables fallback routing; every receipt records the
+backend actually used.
+
+```python
+from ptcna import PTCNARuntime
+
+runtime = PTCNARuntime()
+target = runtime.infer("question")
+fallback = runtime.infer("question", backend="fallback")
+continued = runtime.infer("question", fallback_on_error=True)
+runtime.reward(continued, outcome=1.0)
+```
+
+Freeze a representative labeled workload before inspecting outcomes:
+
+```python
+from ptcna import EvaluationCase, EvaluationPlan, evaluate
+
+plan = EvaluationPlan(
+    plan_id="representative-workload-v1",
+    workload=(EvaluationCase("case-1", "input", "phi"),),
+    minimum_target_accuracy=0.80,
+    maximum_target_deficit_vs_fallback=0.00,
+    training_epochs=3,
+    reward_outcome=1.0,
+    repetitions=3,
+    max_training_steps=9,
+    max_case_evaluations=3,
+    max_seconds=30.0,
+    backend_error_status="FALSIFIED",
+)
+print(plan.digest)  # preserve this with the plan before execution
+receipt = evaluate(plan)
+```
+
+The repository does not ship a pretend representative workload. Until one is
+frozen and executed, whether PTCNA works remains `hmmm`.
+
 ## Status
 
 Alpha (`0.1.1`). All four layers import and the repository test suite passes.
@@ -54,6 +96,13 @@ The layer boundary is now executable rather than only descriptive:
   reviewed PTCNA-specific higher-gonol producer profile exists.
 - EDCM remains an external authority. `ZetaEngine` accepts an explicitly
   injected measurement provider; PTCNA contains no shadow EDCM module.
+- `PTCNAEngine` joins the live neural engine to the complete local core and
+  reports all four layers. `PTCNARuntime` keeps that experimental path distinct
+  from `HashedLinearFallback`; failover is explicit and attributed.
+- `EvaluationPlan` freezes workload, training schedule, comparator, metric,
+  thresholds, resource limits, stopping, and failure propagation before
+  `evaluate` emits
+  `FALSIFIED`, `SURVIVED — not proved`, or `UNRESOLVED`.
 
 The core layer still intentionally exposes PTCA-named public objects such as
 `PTCATensor` and `PTCAInstance`; those names live in the correct layer.

docs/architecture.md

@@ -97,6 +97,14 @@ or criterion change. PTCNA-local prime and ring structures may be constructed
 now; only a claim that they are UCNS-produced remains suspended until an exact
 pinned UCNS receipt exists.
 
+The executable boundary lives in `ptcna.runtime`: `PTCNAEngine` reports all
+four live layers, `HashedLinearFallback` remains separately identified, and
+`PTCNARuntime` raises on target failure unless fallback routing is explicitly
+enabled. `ptcna.evaluation` accepts only an immutable, digest-bearing
+`EvaluationPlan`, trains before scoring, and records the terminal verdict before repair. No
+representative workload is bundled; selecting one remains evidence work, not a
+construction prerequisite.
+
 Semantic authority for discovery-before-recovery remains with
 `The-Interdependency/metapat`; this correction consulted
 `metapat@53315e30c54aba881a5b48cbf395890e83ab05c5`,
@@ -105,6 +113,12 @@ METAPAT canon.
 
 ## Status log
 
+- **2026-08-17 — executable construction/evaluation boundary.** Added the
+  four-layer target receipt, independently test-backed hashed-linear fallback,
+  explicit attributed failover, and frozen evaluation/verdict API. Removed the
+  broken deprecated FastAPI seed runner. This establishes runnable separation;
+  it does not establish that PTCNA works on a representative task.
+
 - **2026-07-05 — circle/seed audit extraction (branch `claude/circle-extraction`).**
   Aggregation moved out of the neural engine into the layers that own it:
   `PCNAEngine._pcta_circle_audit` → `ptcna.circle.circle_audit`;

docs/work-graphs/repository-plan-report.json

@@ -49,8 +49,8 @@
     }
   },
   "status": {
-    "state": "active alpha runtime; intended architecture and dependable fallback construction proceed under separate evidence boundaries",
-    "current_claim": "PTCNA 0.1.1 implements one four-layer runtime in which reverse-mode gradients are owned by the neural layer while circle, seed, and core remain non-differentiating structural hosts. Construction of the intended PTCNA architecture may proceed under PTCNA-local provenance alongside a dependable explicit fallback. UCNS higher-gonol attribution remains suspended, EDCM remains external, and the critical 'does it work?' verdict remains unearned until frozen evaluation.",
+    "state": "active alpha runtime; explicit target, fallback, and frozen-verdict interfaces are implemented under separate evidence identities",
+    "current_claim": "PTCNA 0.1.1 implements one four-layer runtime in which reverse-mode gradients are owned by the neural layer while circle, seed, and core remain non-differentiating structural hosts. The unreleased package surface adds an attributed four-layer target receipt, an independently test-backed hashed-linear fallback, explicit failover, and immutable evaluation plans. UCNS higher-gonol attribution remains suspended, EDCM remains external, and the critical 'does it work?' verdict remains unearned until a representative plan is frozen and executed.",
     "latest_main_milestone": {
       "commit": "4509d33419aa25e6a9cfef415055e378b8f37edc",
       "description": "merged the reconciled four-layer v0.1.1 runtime with one CircleTensor, neural-only reverse-mode scalar ownership, fail-closed UCNS integration, and external EDCM measurement injection"
@@ -81,32 +81,32 @@
       "surface": "0.1.1 cross-repository input manifest",
       "status": "sealed historical coordination record",
       "boundary": "its July producer identities are evidence for the 0.1.1 reconciliation only, not current stack identities"
+    },
+    {
+      "surface": "explicit target/fallback runtime boundary",
+      "status": "implemented and contract-tested on the unreleased package surface",
+      "boundary": "the fallback is separately identified and used after target failure only when the caller explicitly enables attributed failover"
+    },
+    {
+      "surface": "frozen evaluation and terminal receipt API",
+      "status": "implemented and contract-tested infrastructure",
+      "boundary": "the API freezes training and scoring criteria and records verdicts but does not supply a representative workload or establish that either backend is useful"
     }
   ],
   "active_frontier": [
     "keep the operational shell aligned with current skill-lib doctrine and supported GitHub Actions runtimes without changing PTCNA architectural evidence standing",
-    "construct the intended PTCNA architecture faithfully under PTCNA-local provenance without waiting for upstream validation or a simpler baseline to grant permission",
-    "build and independently verify a dependable simpler fallback behind an explicit interface so useful operation survives a PTCNA failure without silently replacing or redefining PTCNA",
-    "freeze the critical 'does it work?' evaluation before outcome inspection, including representative workload, comparator, exact metric and aggregation, threshold, resource bounds, stopping rules, failure propagation, and evidence receipt",
+    "freeze a representative 'does it work?' EvaluationPlan before outcome inspection, including workload, training epochs and reward, exact thresholds, repetitions, resource bounds, and failure propagation; the comparator identity, post-training metric, aggregation, stopping rule, and receipt schema are now executable",
+    "execute the preserved plan without repair or criterion change and record FALSIFIED, SURVIVED — not proved, or UNRESOLVED",
+    "qualify whether the hashed-linear fallback preserves useful operation on the representative workload rather than inferring utility from deterministic contract tests",
     "consume exact UCNS producer receipts when available for UCNS attribution while allowing locally attributed PTCNA prime and ring construction to continue",
     "resolve whether the embedded ZetaEngine remains a bounded PTCNA-local measurement-to-learning adapter or should be removed in favor of separate ZFAE authority before further Zeta development",
-    "test sustained-load and long-horizon state behavior after the architecture and fallback are executable and the evaluation contract is frozen"
+    "test sustained-load and long-horizon state behavior through the explicit target/fallback runtime boundary"
   ],
   "next_actions": [
     {
-      "action": "build the intended PTCNA architecture faithfully under PTCNA-local provenance",
-      "owner": "The-Interdependency/ptcna",
-      "dependency": "repository-owned implementation contracts only; upstream evidence and simpler baselines do not grant permission to construct"
-    },
-    {
-      "action": "build and independently verify a dependable simpler fallback behind the same explicit task boundary",
-      "owner": "The-Interdependency/ptcna",
-      "dependency": "the fallback must remain separately identified and must not silently replace, redefine, or be reported as PTCNA"
-    },
-    {
-      "action": "preregister the critical 'does it work?' evaluation after the target and fallback are sufficiently executable and before outcome inspection",
+      "action": "preregister the critical 'does it work?' evaluation with EvaluationPlan before outcome inspection",
       "owner": "The-Interdependency/ptcna",
-      "dependency": "freeze workload, comparator, metric and aggregation, threshold, resource bounds, stopping rules, failure propagation, and evidence-receipt requirements"
+      "dependency": "requires a representative labeled workload plus externally justified training, reward, accuracy, comparator-deficit, repetition, resource, and backend-error thresholds; construction remains permitted regardless"
     },
     {
       "action": "record the terminal result before repair or criterion change",
@@ -163,6 +163,8 @@
     "historical_stack_manifest": "docs/work-graphs/ptcna-0.1.1-inputs.json",
     "system_overview": "README.md",
     "architecture": "docs/architecture.md",
+    "runtime_boundary": "ptcna/runtime.py",
+    "frozen_evaluation": "ptcna/evaluation.py",
     "neural_runtime": "ptcna/neural/pcna.py",
     "ucns_boundary": "ptcna/ucns_integration.py",
     "external_measurement_adapter": "ptcna/neural/zeta.py",
@@ -171,8 +173,8 @@
   "hmmm": [
     "the exact PTCNA-specific UCNS producer profile and receipt for any structure later claimed as UCNS-produced",
     "whether the constructed PTCNA architecture works under the frozen representative evaluation",
-    "the exact workload, comparator, metric, aggregation, threshold, resource bounds, stopping rules, and failure propagation for that evaluation",
-    "the exact dependable fallback implementation and shared task-interface identity",
+    "the exact representative workload and externally justified training epochs, reward, target threshold, comparator-deficit allowance, repetitions, resource bounds, and backend-error status for the implemented evaluation API",
+    "whether the implemented hashed-linear fallback preserves useful operation on that representative workload",
     "whether the current ring sizes, heptagram propagation, prime constants, and fixed ring weights contain irreducible useful structure or historical accident",
     "the authority boundary and migration path between PTCNA's embedded ZetaEngine and The-Interdependency/zfae",
     "sustained-load behavior across the complete four-layer seam",

ptcna/__init__.py

@@ -1,4 +1,4 @@
-# ratios: loc_comments=22:12 imports_exports=2:1 calls_definitions=1:0
+# ratios: loc_comments=31:51 imports_exports=4:1 calls_definitions=1:0
 """PTCNA — Prime Tensor Circled Neural Architecture.
 
 One architecture, four layers. Each layer's tensors divide into the next; every
@@ -26,6 +26,50 @@
     require_ucns_integration,
     ucns_integration_status,
 )
+from .runtime import HashedLinearFallback, PTCNAEngine, PTCNARuntime
+from .evaluation import EvaluationCase, EvaluationPlan, EvaluationReceipt, evaluate
+
+# === MODULE_BUILD ===
+# id: ptcna_package_surface
+#   module_name: package surface
+#   module_kind: adapter
+#   summary: exposes the four layers, explicit runtime boundary, dependable fallback, and frozen evaluation types from the package root
+#   owner: Erin Spencer
+#   public_surface: neural, circle, seed, core, PTCNAEngine, HashedLinearFallback, PTCNARuntime, EvaluationCase, EvaluationPlan, EvaluationReceipt, evaluate, UCNS integration status types
+#   internal_surface: none
+#   auth_boundary: none
+#   storage_boundary: none
+#   network_boundary: none
+#   user_data_boundary: none
+#   admin_only: false
+#   tests: ptcna/tests/test_runtime.py
+#   rollout: imported through ptcna
+#   rollback: remove root re-exports while retaining module-qualified imports
+#   requires: ptcna_runtime_boundary, ptcna_frozen_evaluation, ptcna_ucns_integration
+#   since: unreleased
+#   unresolved: none
+# === END MODULE_BUILD ===
+
+# === CONTRACTS ===
+# id: ptcna_root_exports_runtime_boundary
+#   given: a caller imports ptcna
+#   then: the experimental engine, distinct fallback, attributed runtime, frozen evaluation types, and evaluator are available without importing deprecated service surfaces
+#   class: compatibility
+# === END CONTRACTS ===
+
+# === BOUNDARIES ===
+# id: ptcna_package_import_boundary
+#   summary: imports local package definitions without constructing engines or performing persistence, network, authentication, user-data, or administrative effects
+#   auth_boundary: none
+#   storage_boundary: none
+#   network_boundary: none
+#   user_data_boundary: none
+#   admin_only: false
+#   pii: none
+#   secrets: none
+#   owner: Erin Spencer
+#   since: unreleased
+# === END BOUNDARIES ===
 
 __all__ = [
     "neural",
@@ -37,6 +81,13 @@
     "UCNSIntegrationSuspended",
     "ucns_integration_status",
     "require_ucns_integration",
+    "PTCNAEngine",
+    "HashedLinearFallback",
+    "PTCNARuntime",
+    "EvaluationCase",
+    "EvaluationPlan",
+    "EvaluationReceipt",
+    "evaluate",
     "__version__",
 ]
-# ratios: loc_comments=22:12 imports_exports=2:1 calls_definitions=1:0
+# ratios: loc_comments=31:51 imports_exports=4:1 calls_definitions=1:0