diff --git a/core/__init__.py b/core/__init__.py new file mode 100644 index 00000000..a86326e2 --- /dev/null +++ b/core/__init__.py @@ -0,0 +1,22 @@ +""" +core — Versor Engine top-level package. + +Cl(4,1) Conformal Geometric Algebra field system. + +Two primitives: + versor_apply(V, F) = V * F * reverse(V) — the only field transition + cga_inner(X, Y) = -d^2 / 2 — the only distance metric + +Core invariant: ||F * reverse(F) - 1||_F < 1e-6 at all times. + +Layer map: + algebra/ Cl(4,1) multivector math, versor ops, CGA, holonomy + ingest/ Single injection gate — the only normalization site + field/ FieldState dataclass and propagation loop + vocab/ Word-to-versor manifold, edge rotors + vault/ Exact CGA inner product memory store + persona/ Persona as CGA motor (screw motion) + generate/ Token streaming loop + session/ Session binding: field + vault + vocab + persona + physics/ Field physics operators (salience, attention, drive, etc.) +""" diff --git a/docs/decisions/ADR-0011-renderer.md b/docs/decisions/ADR-0011-renderer.md new file mode 100644 index 00000000..54a7c62f --- /dev/null +++ b/docs/decisions/ADR-0011-renderer.md @@ -0,0 +1,100 @@ +# ADR-0011 — Renderer Layer Contract + +**Status:** Accepted +**Date:** 2026-05-13 + +--- + +## Context + +The architecture pipeline terminates at `generate/stream.py`, which produces a sequence of +versor-nearest tokens. Those tokens are internal field entities — they have CGA coordinates, +provenance, and algebraic identity. Before reaching any surface (terminal, API response, UI, +audio), they must be realized into a modality-specific form. + +In `core-ai`, this became `core_logos` — a full subsystem with deterministic readback, surface +realization, public trace metadata, and its own authority boundary. That was over-engineering: +it solved operational concerns (auditability, proof artifacts, API stability) before the +underlying generation was correct. + +In `core`, the renderer is deliberately thin. It is not a subsystem. It is a single contract. + +--- + +## Decision + +The renderer layer is defined by one interface: + +```python +class Renderer(Protocol): + """Convert a generated token sequence into surface output. + + Contract: + - Input: Iterable[VocabEntry] — the ordered token stream from generate/stream.py + - Output: str | bytes — modality-specific surface realization + - Stateless: the renderer holds no field state and modifies nothing + - Deterministic: identical token sequences produce identical surface output + """ + def render(self, tokens: Iterable["VocabEntry"]) -> str | bytes: ... +``` + +The default implementation (`generate/render.py`) is a plain text renderer: +tokens → their `.surface` strings joined by the language-appropriate separator. + +Modality-specific renderers (markdown, Hebrew RTL, Koine Greek polytonic, audio phoneme stream) +are implementations of this same protocol, registered externally. The engine never selects a +renderer — the caller provides one. + +--- + +## Rationale + +**Why thin?** +The field knows what it means. The renderer only knows how to write it down. These are +fundamentally different concerns. Mixing them (as `core_logos` did) creates a subsystem that +must understand both the algebra and the output format — a dual responsibility that violates +Semantic Rigor. + +**Why caller-provided?** +The engine has no concept of "deployment context." Whether it renders to a terminal, an API, +a mobile UI, or an audio stream is not the engine's concern. Injecting a renderer at the call +site keeps the engine's contract pure and keeps the engine testable in isolation. + +**Why stateless?** +Propagation-over-mutation. The renderer receives a completed token stream. It does not +accumulate, buffer, or modify field state. If continuity across renders is needed, that is a +session-level concern, not a renderer concern. + +**Why deterministic?** +Third Door: the renderer is a pure function of the token stream. Non-determinism (formatting +decisions, adaptive punctuation, "natural" variation in surface form) is a property of language +models that apply stochastic transforms at output time. CORE does not do that. The field +determines meaning; the renderer transcribes it exactly. + +--- + +## Hebrew and Koine Greek Rendering + +These are not localizations — they are depth languages with structurally different rendering +requirements: + +- **Hebrew:** RTL script, prefix/suffix morphology carried as field metadata, nikud + (vowel points) rendered only when the VocabEntry carries them explicitly +- **Koine Greek:** polytonic diacritics, breathing marks, iota subscript — all carried in the + VocabEntry's `.surface` field; the renderer writes them as-is + +Neither requires a special renderer *subsystem*. Both require only that the VocabEntry's +`.surface` field is correctly populated upstream (in `vocab/`), and that the text renderer +respects Unicode directionality. That is all. + +--- + +## Consequences + +- `generate/render.py` is added as the default `TextRenderer` implementation +- `generate/stream.py` does not call any renderer — it yields tokens +- No `core_logos` equivalent will be introduced +- Future modality renderers (audio, structured data) implement `Renderer` and are provided + by the caller +- The renderer is the last thing that happens before output leaves the system +- Nothing after the renderer touches the field diff --git a/docs/sessions/SESSION-2026-05-13.md b/docs/sessions/SESSION-2026-05-13.md new file mode 100644 index 00000000..86307624 --- /dev/null +++ b/docs/sessions/SESSION-2026-05-13.md @@ -0,0 +1,45 @@ +# Session Note — 2026-05-13 + +## Key Clarification: `core` is the primary work. `core-ai` is the archive. + +### Context + +`AssetOverflow/core-ai` was the original implementation of the Versor Engine. Over time it +drifted from its architectural intent — the geometry got buried under operational infrastructure: +`CoreChatRuntime`, `RuntimeMemoryAuthority`, `GradeGuard`, `core_logos` as a full articulation +subsystem, `core_ca` as an apprenticeship platform, bounded continuity state, proof scripts, and +a deployed-product authority hierarchy (`core_ha`, `core_vault`, `core_logos`, `core_engine` as +separate governance domains). + +That work was real engineering but it was solving the wrong problem at the wrong time — it was +building a product *on top of* the model before the model itself was defined and correct. + +`AssetOverflow/core` is the reset: back to first principles, two primitives, one injection gate, +the field as native state, Cl(4,1) as the only substrate. Every layer has exactly one job. + +### Decision + +- **`AssetOverflow/core`** is the primary, active, authoritative repository. +- **`AssetOverflow/core-ai`** is a reference archive. It is not a source of patterns, + conventions, or designs to pull forward unless they are explicitly evaluated against the + seven axioms and the three engineering pillars in `core`'s README. +- The following from `core-ai` are worth reviewing for future mining (not direct import): + - `core_ingest` — `CandidateGeometricPressure` design and governance tier + - `core_vault` — frozen storage semantics +- The following from `core-ai` must **not** be re-introduced into `core`: + - Any chat runtime, authority hierarchy, or proof-script infrastructure + - `core_logos` as a subsystem (articulation in `core` is a thin final layer, not a subsystem) + - `core_ca` apprenticeship layer (out of scope for the engine itself) + - `RuntimeMemoryAuthority` or any tiered memory governance (vault + field are sufficient) + +### Structural Issues Fixed This Session + +- `pyproject.toml`: renamed package from `core-ai` to `core-versor` +- `core/__init__.py`: created — the `core/` Python package previously had no top-level init +- ADR-0011 written: Renderer layer contract + +### Open Items + +- `ingest/gate.py` is the correct shape but `core_ingest`'s `CandidateGeometricPressure` envelope + design deserves evaluation as a pre-gate normalization step (see previous session analysis) +- `docs/decisions/README.md` ADR index needs update through ADR-0011 diff --git a/pyproject.toml b/pyproject.toml index 5a03ff7a..80501b6e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,5 +1,5 @@ [project] -name = "core-ai" +name = "core-versor" version = "0.1.0" description = "Versor Engine: cognitive field system on Cl(4,1) Conformal Geometric Algebra" requires-python = ">=3.11"