From 98c0c2d8d636d0176340a99a14b7f7fe1b930aac Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 22 Apr 2026 09:56:57 +0000 Subject: [PATCH 1/2] Add CLAUDE.md and rewrite README.md based on fine-grain audit MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md: replace stale GPT-generated draft with accurate architecture reference — exact ring specs (N, seed, weights), EDCM six-family metrics, directive names, file structure, installation notes, merge modes, status. CLAUDE.md: new developer guide for Claude Code — module summaries, key invariants (ring weights ↔ rings keys, no guardian key, canonical directive names, no pytest-asyncio), CI failure patterns, import paths, stub inventory, known issues, and a recipe for adding a new ring. https://claude.ai/code/session_018vyPzNQrgsLKq34wyyNY7W --- CLAUDE.md | 150 ++++++++++++++++ README.md | 523 ++++++++++++++---------------------------------------- 2 files changed, 287 insertions(+), 386 deletions(-) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b19bf77 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,150 @@ +# CLAUDE.md — PCNA Codebase Guide + +## Project Overview + +PCNA (Prime Circular Neural Architecture) is a deterministic, prime-indexed circular graph system for modular compute and real-time diagnostics. It has two distinct layers: + +- **core/** — the inference engine: six rings of prime-indexed tensor nodes running heptagram propagation, coherence scoring, and EDCM diagnostics +- **backend/** — a FastAPI server that hosts seeds, integrates an LLM orchestrator, and exposes REST/WebSocket APIs + +The canonical upstream is `The-Interdependency/a0`. Features are ported from there and adapted. Development happens on `claude/update-from-interdependency-a0-*` branches; PRs go to `main`. + +--- + +## Repository Layout + +``` +core/ Engine modules (no FastAPI, no DB) +backend/ Server, LLM, optimization, SMS, Moltbook, outreach +frontend/src/ React dashboard (5 components) +tests/ pytest — no pytest-asyncio; use asyncio.run() for async tests +schemas/ JSON schemas +main.py Seed runner entry point +conftest.py sys.path insert — keeps pytest imports working +requirements.txt +``` + +--- + +## Core Modules — What Each Does + +### `core/ptca_core.py` — `PTCACore` +Base class for all prime-ring tensors. Tensor shape: `[N, DIMS=4, PHASES=7, HEPT_SITES=7]`. Heptagram propagation via Euler steps (DT=0.01). Coherence = `1 - |ring - hub|_mean`. Used by Φ, Ψ, Ω, and Σ. + +Key: `_adj_distances(n)` uses `math.ceil(n/4)` to get gap=14 for n=53 (spec-correct). Keep `import math` — it's used here. + +### `core/theta.py` — `ThetaTensor` +N=29 microkernel gate. Ragged circle counts per node (1–12), SHA-256 blueprint sharding, gate control via `GATE_THRESHOLD=0.45`. Not a PTCACore subclass — standalone. Neighbors hardcoded to `±1, ±7 mod 29`. Imported as `from .theta import ThetaTensor`. + +### `core/sigma.py` — `SigmaRing` / `get_sigma()` +N=41 filesystem observer wrapping PTCACore. Tracks watched file mtimes, drains change events on `content_interval` cadence. Singleton via `get_sigma()`. All callers in pcna.py and zeta.py use `try/except ImportError` — sigma is optional but present. + +### `core/memory_core.py` — `MemoryCore` +Parameterized long-term (N=19, seed=19) and short-term (N=17, seed=17) memory rings. Round-robin write, content-addressed query, `flush_to()` transfers short→long on positive reward. + +### `core/pcna.py` — `PCNAEngine` +Six-ring inference engine. Key attributes: `self.phi`, `self.psi`, `self.omega`, `self.theta`, `self.memory_l`, `self.memory_s`. `RING_WEIGHTS` dict uses keys matching `state()["rings"]` exactly: `phi, psi, omega, theta, memory_l, memory_s`. Checkpoints go in `.checkpoints/pcna_checkpoint.npz`. + +### `core/edcm.py` +Six-family metrics (cm, da, drift, dvg, int_val, tbf) with `ALERT_HIGH=0.80`, `ALERT_LOW=0.20`. `DIRECTIVES` dict uses canonical names: `CONSTRAINT_REFOCUS`, `DISSONANCE_HALT`, `DRIFT_ANCHOR`, `DIVERGENCE_COMMIT`, `INTENSITY_CALM`, `BALANCE_CONCISE`. `check_directives()` returns a list of fired directive names. + +### `core/zeta.py` — `ZetaEngine` +ZFAE: evaluates every assistant response via EDCM, nudges PCNAEngine.phi. Coherence formula: `cm*0.35 + da*0.25 + int_val*0.25 + (1-drift)*0.15`. Per-directory resolution (1–5) via prefix matching. Module-level singleton `_zeta_engine`. `_sigma_nudge_factors()` silently swallows `ImportError`; logs other exceptions. + +### `core/merge.py` — `InstanceMerge` +Static methods: `absorb`, `fork`, `converge`. All output dicts use `theta_*` keys (not `guardian_*`). Federated averaging via `_fed_avg(a, b, alpha)`. + +### `backend/edcm_engine.py` — `EDCMAnalyzer` +Derives EDCM metrics from `seed_states` dicts (require `health_score`, `mass`, `role` keys). Fires directives, generates insights/recommendations, assigns `monetization_value`. Async `analyze()` — call with `asyncio.run()` in tests. + +--- + +## Key Invariants + +**Ring weights and ring keys must match.** `RING_WEIGHTS` in `pcna.py` and `state()["rings"]` must have identical keys. Currently: `{phi, psi, omega, theta, memory_l, memory_s}`. If you add or rename a ring, update both. + +**No `guardian` key anywhere.** The ring was renamed from `guardian` to `theta`. If you see `guardian` as a dict key or attribute (outside docstring prose), it's a bug. + +**EDCM directive names are canonical.** Always `CONSTRAINT_REFOCUS`, `DISSONANCE_HALT`, `DRIFT_ANCHOR`, `DIVERGENCE_COMMIT`, `INTENSITY_CALM`, `BALANCE_CONCISE`. No internal abbreviations. + +**`ALERT_HIGH` and `ALERT_LOW` before `DIRECTIVES`.** In `core/edcm.py`, constants must be defined before the `DIRECTIVES` dict that references them. + +**No `pytest-asyncio`.** Tests use `asyncio.run()` directly. Do not add `@pytest.mark.asyncio`. + +**No `sys.path.insert` in source files.** `conftest.py` handles the path. Don't add it to individual modules. + +--- + +## Import Paths + +Tests and backend modules import from the package root: +```python +from core.edcm import compute_metrics, check_alerts, check_directives +from backend.edcm_engine import EDCMAnalyzer +from core.pcna import PCNAEngine +``` + +The root `main.py` uses `from core.topology import ...` — correct. +`core/main.py` uses `from src.core.*` — broken, do not use. + +--- + +## CI + +GitHub Actions runs two jobs on every push: + +1. **flake8** — `--select=E9,F63,F7,F82` (syntax errors, undefined names). Must pass clean. +2. **pytest** — all `test_*.py` and `tests_*.py` in `tests/`. Must pass. + +Common CI failures seen: +- Backslash-escaped triple quotes in f-strings → E999 SyntaxError +- Unused `global` declarations → F824 +- Wrong import paths (e.g. `from src.core.*`) → ModuleNotFoundError +- Missing `asyncio.run()` / leftover `@pytest.mark.asyncio` decorator + +--- + +## Known Stubs (not yet implemented) + +| File | What's missing | +|------|---------------| +| `core/routing_loop.py` | Only a print stub — `GlobalRouterZero` not implemented | +| `backend/moltbook_integration.py` | 100% mock data; all methods are TODOs | +| `backend/sms_service.py` | Twilio integration commented out; mock mode only | +| `backend/researcher_outreach.py` | `send_outreach()` is a stub; message generation works | + +--- + +## Known Issues + +- `core/memory_core.py`: `query()` is defined but never called anywhere +- `core/helix_vis.py`: saves to hardcoded `pcna_helix.gif`; no config +- `core/sigma.py`: `structural_interval` is stored but never acted on +- `core/merge.py`: `fork()` time-seeds its RNG — rapid calls may collide +- `backend/server.py`: MongoDB connection failure is not handled gracefully; seed roles are hardcoded in initialization (not topology-driven) +- `requirements.txt`: missing `motor`, `python-dotenv`, `emergentintegrations`, `scipy`, `matplotlib` + +--- + +## Adding a New Ring + +1. Create `core/.py` — implement the ring class with `tensor`, `ring_coherence`, `node_coherence`, `nudge()`, `state()` interface +2. Add it to `PCNAEngine.__init__()` as `self.` +3. Add the weight to `RING_WEIGHTS` in `core/pcna.py` +4. Add it to `state()["rings"]` with the same key as in `RING_WEIGHTS` +5. Add checkpoint save/load in `save_checkpoint()` / `load_checkpoint()` +6. Wire inject/reward as appropriate in `_inject()` and `reward()` + +--- + +## Working with EDCM + +`core/edcm.py` computes metrics from response text (content length, variance, context overlap). `backend/edcm_engine.py` computes metrics from seed state dicts (health scores, masses, roles). These are two separate derivation paths feeding the same six-family schema. + +To add a new directive: add it to `DIRECTIVES` in `core/edcm.py`, add the corresponding firing condition to `EDCMAnalyzer._fire_directives()` in `backend/edcm_engine.py`, and add a test in `tests/test_edcm_engine.py`. + +--- + +## Frontend + +React app in `frontend/`. Components: `TopologyVisualization`, `SystemHealthDashboard`, `EDCMArtifacts`, `LLMInterface`, `SMSConsole`. Not tested in CI. Backend served separately. diff --git a/README.md b/README.md index a16ba80..0cf7a52 100644 --- a/README.md +++ b/README.md @@ -1,448 +1,199 @@ -# PCNA Repo -Initialized Sat Jan 31 19:00:28 PST 2026 -Below is a single-file, copypastable README.md for your PCNA repository, written clean, technical, and grounded — aligned with your preference for structure first, then content and ready for GitHub. +# PCNA — Prime Circular Neural Architecture +Deterministic, prime-indexed circular graph architecture for modular compute and real-time diagnostics. --- -Prime Circular Neural Architecture (PCNA) +## Architecture -Deterministic, prime-indexed, circular graph architecture for modular compute + diagnostics. +PCNA organizes compute and diagnostics into **53 prime-indexed seeds** arranged on a unit-circle address space with heptagram (7-site) routing. -GPT generated; context, prompt Erin Spencer +### Seed Topology +| Layer | Count | Role | +|-------|-------|------| +| Global router | 1 | Coordination root (ID 0) | +| Sentinels | 4 | Diagnostics — observe, do not compute | +| Meta routers | 7 | Cluster aggregation | +| Compute seeds | 49 (7×7) | Primary compute units | +| **Total** | **53** | Prime — avoids harmonic aliasing | ---- - -I. Purpose - -PCNA is an experimental neural / distributed-compute topology that: - -organizes compute nodes on a unit-circle address space - -routes traffic through prime-indexed clusters - -separates computation from diagnostics +Each compute seed connects to heptagram neighbors (`±3 mod 7` within its meta cluster). Routing traverses the meta-router tree; sentinels scan with a 7:2 stride pattern and publish diagnostics only. -embeds observability directly into the architecture +### Six-Ring Inference Engine (`core/pcna.py`) +The `PCNAEngine` runs a six-ring pipeline per inference call: -Design goal: +| Ring | Symbol | N | Seed | Role | +|------|--------|---|------|------| +| Phi | Φ | 53 | 53 | Cognitive substrate | +| Psi | Ψ | 53 | 43 | Self-model | +| Omega | Ω | 53 | 47 | Autonomy | +| Theta | Θ | 29 | — | Microkernel gate | +| Memory-L | — | 19 | 19 | Long-term memory | +| Memory-S | — | 17 | 17 | Short-term memory | +| Sigma | Σ | 41 | 41 | Filesystem observer | -> predictable routing, sparse communication, measurable stability +**Ring weights** (coherence scoring): Φ 0.30 · Θ 0.20 · Ψ 0.15 · Ω 0.15 · Memory-L 0.12 · Memory-S 0.08 +**Inference steps:** +1. **Project** — SHA-512(text) → 53-dim normalized signal +2. **Inject** — push signal into Φ; cross-inject Θ coherence → Φ, Φ coherence → Ψ, Σ coherence → Ψ, Memory-L hub → Ω +3. **Propagate** — heptagram propagation (Φ:10, Ψ:8, Ω:6, Θ:5 steps) +4. **PTCA-seed audit** — per-node hub-ring coherence for Φ/Ψ/Ω +5. **PCTA-circle audit** — gate status and circle counts on Θ +6. **Coherence score** — weighted ring coherence → winner ring + confidence +### EDCM — Six-Family Diagnostics -PCNA avoids opaque dense attention or monolithic networks in favor of: +The EDCM subsystem (`core/edcm.py`, `backend/edcm_engine.py`) measures system health continuously: -explicit structure +| Metric | Key | Alert | +|--------|-----|-------| +| Constraint Mismatch | `cm` | HIGH ≥ 0.80 | +| Dissonance Accumulation | `da` | HIGH ≥ 0.80 | +| Drift | `drift` | HIGH ≥ 0.80 | +| Divergence | `dvg` | HIGH ≥ 0.80 | +| Intensity | `int_val` | LOW ≤ 0.20 | +| Turn-Balance Fairness | `tbf` | LOW ≤ 0.20 | -bounded neighborhoods - -inspectable flows - -failure visibility +**Behavioral directives** fire automatically on threshold crossings: +`CONSTRAINT_REFOCUS` · `DISSONANCE_HALT` · `DRIFT_ANCHOR` · `DIVERGENCE_COMMIT` · `INTENSITY_CALM` · `BALANCE_CONCISE` +### ZetaEngine (`core/zeta.py`) +Non-LLM real-time learning: after every assistant response, ZFAE (Zeta Function Alpha Echo) computes EDCM coherence and drives PCNA Φ-ring reward backprop. Supports per-directory resolution levels (1–5). --- -II. Core Ideas (Plain English) - -Instead of: - -> one giant black-box neural net - - - -PCNA uses: - -many small nodes - -clustered routing - -meta routers - -independent sentinels watching the system - - -So: - -compute happens here -analysis happens there -feedback closes the loop - -This enables: - -modular growth - -easier debugging - -resilience to failure - -compatibility with EDCM diagnostics - - - ---- - -III. Topology - -Node counts - -Layer Count Role - -child routers 49 primary compute -meta routers 7 cluster aggregation -sentinels 4 diagnostics / metadata -global router 1 coordination root -total seeds 53 prime-indexed set - - -53 is chosen because: - -prime → avoids harmonic aliasing - -clean cluster separation - -symmetric layout for circular addressing - - - ---- - -Layout - -(sentinels) - ○ ○ - ○ ○ - - [ 7 clusters × 7 nodes each ] - - → meta routers (7) - ↓ - global zero - - ---- - -IV. Functional Layers - -1. Child Routers (49) - -Primary compute units. - -Responsibilities: - -token transforms - -state updates - -local tensor math - -Markov recursion - -learning steps - - -Properties: - -small - -independent - -replaceable - - - ---- - -2. Meta Routers (7) - -Cluster coordinators. - -Responsibilities: - -aggregate child outputs - -route inter-cluster traffic - -reduce bandwidth - -maintain locality - - - ---- - -3. Global Router (0) - -System spine. - -Responsibilities: - -high-level coordination - -broadcast - -synchronization - -scheduling - - - ---- - -4. Sentinels (4) - -Diagnostics only — not compute. - -Responsibilities: - -anomaly detection - -stability metrics - -constraint strain (EDCM) - -outlier detection - -metadata analysis - - -Key rule: - -> Sentinels observe but do not influence compute directly. - - - -They produce: - -signals - -flags - -feedback - - -Never hidden mutation. - - ---- - -V. Data Flow - -Forward pass - -input - → children - → meta routers - → global router - → output - -Diagnostic loop - -all states - → sentinels - → metrics - → health signals - → optional corrective policies - -Separation of concerns: - -Path Purpose - -compute results -sentinel measurement - - - ---- - -VI. Why This Exists - -Problems with typical deep nets - -opaque - -fragile - -hard to debug - -expensive global attention - -poor observability - - -PCNA aims to provide - -deterministic routing - -sparse communication - -explicit locality - -inspectability - -modular scaling - -native diagnostics - - - ---- - -VII. Relationship to EDCM - -PCNA and EDCM are complementary: - -System Role - -PCNA compute substrate -EDCM dissonance / stability metrics - - -Conceptually: - -PCNA thinks -EDCM measures strain of thinking - -This allows: - -early instability detection - -alignment checks - -human-readable diagnostics - - - ---- - -VIII. Minimal Folder Structure +## Repository Structure +``` pcna/ +├── core/ +│ ├── pcna.py # PCNAEngine — six-ring inference pipeline +│ ├── ptca_core.py # PTCACore — parameterized prime-ring tensor +│ ├── theta.py # ThetaTensor — N=29 microkernel gate +│ ├── sigma.py # SigmaRing — N=41 filesystem observer +│ ├── memory_core.py # MemoryCore — long/short-term memory rings +│ ├── merge.py # InstanceMerge — absorb/fork/converge +│ ├── zeta.py # ZetaEngine — EDCM-driven backprop +│ ├── edcm.py # EDCM metrics, alerts, directives +│ ├── topology.py # PCNATopology — seed layout and routing +│ ├── tensor_engine.py # TensorState, MarkovRecursion +│ ├── routing_loop.py # GlobalRouterZero (stub — not implemented) +│ └── helix_vis.py # Spectral helix visualizer │ -├─ core/ -│ ├─ node.py -│ ├─ router.py -│ ├─ cluster.py -│ ├─ sentinel.py -│ └─ topology.py -│ -├─ metrics/ -│ ├─ edcm_adapter.py -│ └─ health_metrics.py -│ -├─ sims/ -│ ├─ toy_markov.py -│ └─ stress_tests.py +├── backend/ +│ ├── server.py # FastAPI — endpoints, WebSocket, MongoDB +│ ├── edcm_engine.py # EDCMAnalyzer — artifacts and directives +│ ├── llm_abstraction.py # LLMOrchestrator — multi-provider fallback +│ ├── optimization_engine.py # SelfOptimizer — health and anomaly monitor +│ ├── sms_service.py # SMSService (Twilio stub) +│ ├── moltbook_integration.py # MoltbookClient (stub) +│ └── researcher_outreach.py # OutreachManager — researcher campaign │ -├─ viz/ -│ ├─ circular_layout.py -│ └─ cylinder_unwrap.py +├── frontend/src/ +│ ├── TopologyVisualization.js +│ ├── SystemHealthDashboard.js +│ ├── EDCMArtifacts.js +│ ├── LLMInterface.js +│ └── SMSConsole.js │ -├─ docs/ -│ └─ architecture.md +├── tests/ +│ ├── test_edcm_engine.py # EDCM + EDCMAnalyzer unit tests +│ ├── test_tensor_engine.py # MarkovRecursion mass-conservation tests +│ └── tests_topology.py # PCNATopology routing tests │ -└─ README.md - +├── schemas/ # JSON schema definitions +├── main.py # Seed runner entry point (FastAPI) +├── conftest.py # sys.path setup for pytest +└── requirements.txt +``` --- -IX. Minimal Prototype (concept sketch) - -class ChildNode: - def step(self, x): - return transform(x) +## Installation +```bash +pip install -r requirements.txt +``` -class MetaRouter: - def __init__(self, children): - self.children = children - - def route(self, x): - return sum(c.step(x) for c in self.children) - - -class Sentinel: - def inspect(self, states): - return anomaly_score(states) +Additional dependencies required for full production use: +| Package | Required by | +|---------|-------------| +| `motor` | `backend/server.py` — async MongoDB | +| `python-dotenv` | environment variable loading | +| `emergentintegrations` | `backend/llm_abstraction.py` — multi-provider LLM | +| `scipy` | `proof_check.py` — spectral analysis | +| `matplotlib` | `core/helix_vis.py` — visualization | --- -X. Design Principles +## Running -small pieces > giant monoliths +### Seed runner (single node) -explicit > implicit +```bash +SEED_ID=1 ROLE=compute PORT=8001 python main.py +``` -inspectable > mystical +Multi-seed: set `SEED_URL_=http://host:port` for each neighbor. -deterministic > emergent chaos +### Backend server -diagnostics first-class +```bash +uvicorn backend.server:app --reload +``` +### Tests +```bash +pytest +``` --- -XI. Status - -Early research / experimental. - -Not production hardened. - -Iteration expected. +## Multi-Instance Mesh -Refinement will continue. +`core/merge.py` provides three merge modes for running multiple `PCNAEngine` instances: +| Mode | Behaviour | +|------|-----------| +| `absorb(dominant, donor)` | Dominant absorbs donor state (α=0.15); donor retired | +| `fork(parent)` | Parent spawns child with copied state + Gaussian noise; both continue | +| `converge(a, b, alpha)` | Federated averaging in both directions (default α=0.50); both continue | --- -XII. Attribution - -GPT generated; context, prompt Erin Spencer +## Checkpointing +```python +engine = PCNAEngine() +engine.load_checkpoint() # restore from .checkpoints/pcna_checkpoint.npz +# ... inference ... +engine.save_checkpoint() # persist all ring tensors +``` --- -XIII. License - -MIT recommended -(simple, permissive, encourages adoption and collaboration) +## Design Principles +- **Deterministic routing** over opaque attention +- **Sparse communication** — bounded neighborhoods, heptagram adjacency +- **Explicit structure** — every ring self-declares identity in `state()` +- **Diagnostics first-class** — EDCM runs continuously, not as an afterthought +- **Inspectable** — checkpoint/restore, per-node coherence, per-ring state dicts +- **Modular growth** — rings are independently parameterized by `(n, seed, role)` --- -XIV. hmm - -Open constraints / active questions: - -is 4 sentinel coverage optimal vs 5 or 7? - -best routing strategy: deterministic vs adaptive? - -ideal cluster size beyond 7? - -sentinel → compute feedback latency tradeoffs - - -(hmm retained intentionally as unresolved design space) - - ---- - -If you'd like next, I can: - -generate architecture.md - -write topology.py - -build a runnable Python demo - -or produce SVG visualizers for the circle/cylinder unwrap +## Status +Experimental / research. Core inference engine and EDCM diagnostics are fully implemented. Several backend integrations are stubs awaiting external API credentials: -Structure or code next? +- **Twilio SMS** (`backend/sms_service.py`) — mock mode only +- **Moltbook** (`backend/moltbook_integration.py`) — all stubs +- **Researcher email sending** (`backend/researcher_outreach.py`) — generation implemented, sending is a stub +- **routing_loop.py** — not yet implemented From 936e92fd88408dec894f071f4dea9d7d993b82ec Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 23 Apr 2026 17:03:41 +0000 Subject: [PATCH 2/2] Address Copilot review: fix seed count, ring table, repo tree, and CLAUDE.md invariants MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md: - Fix total seed count: 61 (1+4+7+49), not 53; clarify N=53 is ring tensor size - Remove Sigma from six-ring scored table; give it a separate optional-observer section - Fix Theta seed: 29 (not "—") - Remove spurious pcna/ wrapper from repo tree (files are at repo root) CLAUDE.md: - core/sigma.py: describe actual exception handling (pcna.py uses broad except Exception; zeta.py splits ImportError from runtime exceptions) - core/pcna.py: clarify RING_WEIGHTS defines the scored ring set; state()["rings"] may include non-scored rings (sigma); they are not required to be identical - Key Invariants: rewrite ring-weights invariant to distinguish scored vs observer rings - CI: "two jobs" → "single build job with two steps" - Adding a New Ring: add scored vs observer branching in the recipe https://claude.ai/code/session_018vyPzNQrgsLKq34wyyNY7W --- CLAUDE.md | 16 ++++++++-------- README.md | 16 +++++++++++----- 2 files changed, 19 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b19bf77..c36d9bf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -37,13 +37,13 @@ Key: `_adj_distances(n)` uses `math.ceil(n/4)` to get gap=14 for n=53 (spec-corr N=29 microkernel gate. Ragged circle counts per node (1–12), SHA-256 blueprint sharding, gate control via `GATE_THRESHOLD=0.45`. Not a PTCACore subclass — standalone. Neighbors hardcoded to `±1, ±7 mod 29`. Imported as `from .theta import ThetaTensor`. ### `core/sigma.py` — `SigmaRing` / `get_sigma()` -N=41 filesystem observer wrapping PTCACore. Tracks watched file mtimes, drains change events on `content_interval` cadence. Singleton via `get_sigma()`. All callers in pcna.py and zeta.py use `try/except ImportError` — sigma is optional but present. +N=41 filesystem observer wrapping PTCACore. Tracks watched file mtimes, drains change events on `content_interval` cadence. Singleton via `get_sigma()`. In `core/pcna.py`, sigma import and use are wrapped in a broad `except Exception: pass` (silent). In `core/zeta.py`, the import is caught with `except ImportError` (silent return) and runtime errors with `except Exception` (logged). Treat sigma as optional — callers degrade gracefully if it raises. ### `core/memory_core.py` — `MemoryCore` Parameterized long-term (N=19, seed=19) and short-term (N=17, seed=17) memory rings. Round-robin write, content-addressed query, `flush_to()` transfers short→long on positive reward. ### `core/pcna.py` — `PCNAEngine` -Six-ring inference engine. Key attributes: `self.phi`, `self.psi`, `self.omega`, `self.theta`, `self.memory_l`, `self.memory_s`. `RING_WEIGHTS` dict uses keys matching `state()["rings"]` exactly: `phi, psi, omega, theta, memory_l, memory_s`. Checkpoints go in `.checkpoints/pcna_checkpoint.npz`. +Six-ring inference engine. Key attributes: `self.phi`, `self.psi`, `self.omega`, `self.theta`, `self.memory_l`, `self.memory_s`. `RING_WEIGHTS` defines the **scored** ring set: `{phi, psi, omega, theta, memory_l, memory_s}`. `state()["rings"]` also includes `sigma` (optional observer, not scored). These two dicts are not required to be identical — only the scored rings need entries in `RING_WEIGHTS`. Checkpoints go in `.checkpoints/pcna_checkpoint.npz`. ### `core/edcm.py` Six-family metrics (cm, da, drift, dvg, int_val, tbf) with `ALERT_HIGH=0.80`, `ALERT_LOW=0.20`. `DIRECTIVES` dict uses canonical names: `CONSTRAINT_REFOCUS`, `DISSONANCE_HALT`, `DRIFT_ANCHOR`, `DIVERGENCE_COMMIT`, `INTENSITY_CALM`, `BALANCE_CONCISE`. `check_directives()` returns a list of fired directive names. @@ -61,7 +61,7 @@ Derives EDCM metrics from `seed_states` dicts (require `health_score`, `mass`, ` ## Key Invariants -**Ring weights and ring keys must match.** `RING_WEIGHTS` in `pcna.py` and `state()["rings"]` must have identical keys. Currently: `{phi, psi, omega, theta, memory_l, memory_s}`. If you add or rename a ring, update both. +**`RING_WEIGHTS` defines the scored ring set.** `RING_WEIGHTS` in `pcna.py` must match the keys used in `_coherence_score()` — currently `{phi, psi, omega, theta, memory_l, memory_s}`. `state()["rings"]` may include additional non-scored rings (currently `sigma`). If you add a scored ring, update `RING_WEIGHTS` and `_coherence_score`. If you add a non-scored/observer ring, add it only to `state()["rings"]`, not to `RING_WEIGHTS`. **No `guardian` key anywhere.** The ring was renamed from `guardian` to `theta`. If you see `guardian` as a dict key or attribute (outside docstring prose), it's a bug. @@ -91,7 +91,7 @@ The root `main.py` uses `from core.topology import ...` — correct. ## CI -GitHub Actions runs two jobs on every push: +GitHub Actions runs a single `build` job on every push with two steps: 1. **flake8** — `--select=E9,F63,F7,F82` (syntax errors, undefined names). Must pass clean. 2. **pytest** — all `test_*.py` and `tests_*.py` in `tests/`. Must pass. @@ -130,10 +130,10 @@ Common CI failures seen: 1. Create `core/.py` — implement the ring class with `tensor`, `ring_coherence`, `node_coherence`, `nudge()`, `state()` interface 2. Add it to `PCNAEngine.__init__()` as `self.` -3. Add the weight to `RING_WEIGHTS` in `core/pcna.py` -4. Add it to `state()["rings"]` with the same key as in `RING_WEIGHTS` -5. Add checkpoint save/load in `save_checkpoint()` / `load_checkpoint()` -6. Wire inject/reward as appropriate in `_inject()` and `reward()` +3. Add it to `state()["rings"]` under the same key +4. **If scored:** add the weight to `RING_WEIGHTS` and add the key to `_coherence_score()`'s `ring_scores` dict +5. **If observer/optional:** skip `RING_WEIGHTS`; wrap access in `try/except` in `_inject()` and `reward()` +6. Add checkpoint save/load in `save_checkpoint()` / `load_checkpoint()` (scored rings only) --- diff --git a/README.md b/README.md index 0cf7a52..11cfbf3 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Deterministic, prime-indexed circular graph architecture for modular compute and ## Architecture -PCNA organizes compute and diagnostics into **53 prime-indexed seeds** arranged on a unit-circle address space with heptagram (7-site) routing. +PCNA organizes compute and diagnostics into **61 seeds** arranged on a unit-circle address space with heptagram (7-site) routing. The core ring tensors use N=53 (a prime) as their node count, which avoids harmonic aliasing in heptagram propagation. ### Seed Topology @@ -16,7 +16,7 @@ PCNA organizes compute and diagnostics into **53 prime-indexed seeds** arranged | Sentinels | 4 | Diagnostics — observe, do not compute | | Meta routers | 7 | Cluster aggregation | | Compute seeds | 49 (7×7) | Primary compute units | -| **Total** | **53** | Prime — avoids harmonic aliasing | +| **Total** | **61** | | Each compute seed connects to heptagram neighbors (`±3 mod 7` within its meta cluster). Routing traverses the meta-router tree; sentinels scan with a 7:2 stride pattern and publish diagnostics only. @@ -29,13 +29,20 @@ The `PCNAEngine` runs a six-ring pipeline per inference call: | Phi | Φ | 53 | 53 | Cognitive substrate | | Psi | Ψ | 53 | 43 | Self-model | | Omega | Ω | 53 | 47 | Autonomy | -| Theta | Θ | 29 | — | Microkernel gate | +| Theta | Θ | 29 | 29 | Microkernel gate | | Memory-L | — | 19 | 19 | Long-term memory | | Memory-S | — | 17 | 17 | Short-term memory | -| Sigma | Σ | 41 | 41 | Filesystem observer | **Ring weights** (coherence scoring): Φ 0.30 · Θ 0.20 · Ψ 0.15 · Ω 0.15 · Memory-L 0.12 · Memory-S 0.08 +Sigma (Σ) is an optional observer ring outside the scored pipeline: + +| Ring | Symbol | N | Seed | Role | +|------|--------|---|------|------| +| Sigma | Σ | 41 | 41 | Filesystem observer — injects coherence into Ψ | + +Sigma appears in `state()["rings"]` but is not in `RING_WEIGHTS`; it is accessed via `try/except` and degrades gracefully if unavailable. + **Inference steps:** 1. **Project** — SHA-512(text) → 53-dim normalized signal 2. **Inject** — push signal into Φ; cross-inject Θ coherence → Φ, Φ coherence → Ψ, Σ coherence → Ψ, Memory-L hub → Ω @@ -69,7 +76,6 @@ Non-LLM real-time learning: after every assistant response, ZFAE (Zeta Function ## Repository Structure ``` -pcna/ ├── core/ │ ├── pcna.py # PCNAEngine — six-ring inference pipeline │ ├── ptca_core.py # PTCACore — parameterized prime-ring tensor