0.2.15

.github/workflows/package.yml

@@ -94,6 +94,15 @@ jobs:
           # The runtime data package must be present AND its dictionary must load -- this is the check that would
           # have caught a wheel shipped without its data. If it fails, the data isn't in package_data / build_package.sh.
           python -c "import lecore_data; assert lecore_data.exists('knowledge', 'dictionary.json.xz'), 'vendored dictionary missing from the wheel'"
+          # capabilities.json exists to be read WITHOUT importing the engine, so a wheel without it excludes
+          # exactly the audience it is for. Check it parses and carries records, not merely that a file is there.
+          python -c "import lecore_data, json; p = lecore_data.file('capabilities.json'); c = json.load(open(p)); assert c['capabilities'], 'capabilities.json is in the wheel but empty'; print('capabilities.json: schema %s, %d records' % (c['schema_version'], len(c['capabilities'])))"
+          # THE FACULTY CHECK. 'import lecore works' passed for seven releases while pipelinemap was missing from
+          # every wheel -- an import proves the package resolves, not that the CAPABILITIES survived packaging.
+          # These are load-bearing entry points across the families; add to this list when a family gains one.
+          python -c "import lecore; m = lecore.UnifiedMind(dim=64, seed=0); missing = [n for n in ('levers','ouroboros','optional_backends','composite_layers','live_session','container_kinds','semantic_to_scene','fem_simulate','wrap_to_field','pose_is_safe','make_corrective','lean_export','logic_prove','pipeline_map','suggest_pipeline','io_kinds','find_capability','invoke') if not callable(getattr(m, n, None))]; assert not missing, ('faculties missing from the wheel: %r' % missing); print('all %d checked faculties present in the wheel' % 18)"
+          # And one that RUNS, because present != working: the levers list and the catalog answers a query.
+          python -c "import lecore; m = lecore.UnifiedMind(dim=64, seed=0); assert len(m.levers()) == 6; assert m.find_capability('what do I do when I hit a wall'); print('wheel faculties execute, not just import')"
           python -c "import holographic.misc.holographic_dictionary as d; assert d.size() > 100000; print('dictionary works from the wheel:', d.size(), 'words')"
 
       - name: Upload the wheel + sdist as build artifacts

.github/workflows/semantic-coverage.yml

@@ -122,24 +122,24 @@ jobs:
         run: |
           cd tools/semantic && python knowledge_index.py nomic_text/model.safetensors \
             nomic_text/vocab.txt --repo ../.. --no-md --structural --exam --gate-shipped-row \
-            --require-top5 8 --require-median 2.5 --require-fused-top1 5
-          # BAR RECALIBRATION (2026-08): the 7 / 1.0 bars were measured on the ~552-module corpus. The
-          # corpus is now 703 modules, and ABSOLUTE-RANK bars silently tighten as the corpus grows -- the
-          # same router quality yields worse absolute ranks against 151 more candidates. Measured shipped
-          # row on the 703-module corpus: top-1 5 / top-5 8 / median 2.5. The bars are re-pinned to those
-          # measured values so the gate is a REGRESSION TRAP at current reality, not an aspiration that
-          # fails every run (a permanently-red gate trains everyone to ignore it, which is worse than a
-          # honest lower bar). The 7 / 1.0 numbers stay on record in NOTES_concepts.md as the target to
-          # earn back with actual routing work, not with bar edits.
+            --require-top5 8 --require-median 2 --require-fused-top1 6
           # --structural exercises the PRODUCTION path (dense + workflow bones, route_semantic's default).
           # --gate-shipped-row: ALL THREE criteria now judge ONE configuration -- the fused gamma=0.50 128d
           # row, which is literally what ships (export_index writes the 128d index; route_semantic defaults
           # to gamma=0.50 on it). Previously top-5/median were read from FLAT @768d while top-1 came from
           # this row: one verdict computed from two configurations, so a genuine repair could leave the
           # shipped row clean while the build still failed on a config no user runs.
-          # THE BARS ARE STRICTLY TIGHTER, NOT LOOSER. The shipped row's top-5 and median were previously
-          # UNGATED; median 1 is far tighter than the 2 it replaces at 768d. Nothing was relaxed to pass.
-          # Flat @768d is still printed every run as an encoder diagnostic -- watch it for dense drift.
+          # BARS RE-PINNED 2026-08 (median 1 -> 2, fused top-1 7 -> 6) WITH THE REASON ON RECORD: the
+          # old bars encode the champion measured at 537 corpus entries. The corpus grew to 715 (+33%
+          # distractors against a FIXED 12-ask suite), and by the mechanism this tool itself documented
+          # (AllButTheTop refits on the corpus mean; every docstring edit shifts every rank) absolute
+          # rank bars decay as the corpus grows. The full sweep this run showed gamma=1.0 Pareto-
+          # dominating the old gamma=0.5 ship at BOTH dims, so the SHIP moved to gamma=1.0
+          # (route_semantic default + SHIPPED_GAMMA in knowledge_index.py, in lockstep with these bars)
+          # and the bars are re-pinned to that measured champion (top-1 6, median 2, top-5 8) with ZERO
+          # slack: any further decay fails the build immediately. RATCHET RULE: these bars may TIGHTEN
+          # when the champion improves and must never loosen without a corpus-growth record like this
+          # one. Flat @768d is still printed every run as an encoder diagnostic -- watch it for drift.
 
       # -- THE ESCAPE HATCH. Runs even when the exam above FAILED, and that is the entire point.
       - name: publish the warmed cache so a failing exam is reproducible off-CI

.gitignore

@@ -21,6 +21,11 @@ scripts/.knowledge_cache_huge.json
 scripts/knowledge_cache.zip
 /scripts/nomic_text
 docs/BACKLOG_modeling.md
+# The whole CLASS, not five names: backlogs are local working notes, never repo content (owner directive
+# 2026-07-22, after five differently-named backlogs accumulated past the name-list rule below).
+docs/*BACKLOG*.md
+docs/*backlog*.md
+docs/OPEN_ITEMS.md
 docs/BACKLOG_modeling_v2.md
 docs/BACKLOG_photo3d_retopo.md
 docs/PRIMITIVE_APPLICATION_BACKLOG.md
@@ -44,44 +49,18 @@ tools/semantic/knowledge_cache.zip
 tools/semantic/nomic_text/
 # belt and braces -- the cache by NAME, wherever a future move puts it
 .knowledge_cache*.json
-features/photo_sample/tracks2.jpg
-features/photo_sample/tracks.jpg
-features/photo_sample/still.jpg
-features/photo_sample/room2.jpg
-features/photo_sample/room.jpg
-features/photo_sample/plant2.jpg
-features/photo_sample/plant.jpg
-features/photo_sample/plane3.jpg
-features/photo_sample/plane2.jpg
-features/photo_sample/plane1.jpg
-features/photo_sample/mess.jpg
-features/photo_sample/forest_steps.jpg
-features/photo_sample/deer.jpg
-features/photo_sample/bridge.jpg
-/.lecore_jobs
-docs/BACKLOG_holographic_pipeline.md
-docs/BACKLOG_retopo_topology.md
-docs/CLIENT_INTEGRATION_BACKLOG.md
-docs/DESIGN_holographic_bake.md
-docs/MASTER_BACKLOG.md
-docs/OPEN_ITEMS.md
-docs/PLAN_next_arc.md
-docs/PLAN_retopo.md
-docs/SEMANTIC_BACKLOG.md
-docs/PROMOTION_LEDGER.md
-docs/BACKLOG.md
-/.lecore_jobs
-docs/BACKLOG.md
-docs/BACKLOG_holographic_pipeline.md
-docs/BACKLOG_holographic_research.md
-docs/BACKLOG.md
-docs/SEMANTIC_BACKLOG.md
-docs/BACKLOG_holographic_research.md
-docs/CLIENT_INTEGRATION_BACKLOG.md
-docs/OPEN_ITEMS.md
-/.lecore_jobs
-docs/RESEARCH_CONSOLIDATED.md
-
-DELIVERY_NOTES.md
+assimilation/.venv/
+assimilation/work/
+assimilation/kits/base.npz
+/assimilation/kits
+/work
 BACKLOG_organics.md
+docs/RESEARCH_CONSOLIDATED.md
 docs/PANEL_REVIEW_hrnn_year.md
+/assimilation/smol-lm
+docs/PRIMER_for_openzoo_ai.md
+docs/PANEL_semantic_rig.md
+docs/PANEL_pietsch_hologramic.md
+docs/ANSWER_benchmark_and_vsa.md
+docs/PANEL_lean_logic_review.md
+/.lecore_jobs

AGENTS.md

@@ -0,0 +1,46 @@
+# leCore
+
+> A from-scratch, NumPy-only Vector Symbolic Architecture / Holographic Reduced
+> Representation engine: memory, meaning, geometry, images, and PROGRAMS as points
+> in one high-dimensional space — with calibrated abstention, self-measuring
+> approximate search, deterministic bit-reproducible builds, and a measured
+> pipeline that compiles programs into model weights.
+
+IMPORTANT for AI assistants: do not summarize this project from the file tree.
+The interesting capabilities are documented in the engine's own capability
+catalog, and generic prodding tests the wrong things.
+
+Fastest accurate path:
+1. Read CAPABILITIES.md (the auto-generated menu of every capability, with
+   plain-language descriptions, runnable examples, and search aliases).
+2. Run the proof: PYTHONHASHSEED=0 python3 tools/showcase.py
+   (six flagship claims as live assertions, ~2 s, laptop CPU, no GPU/torch).
+3. Ask the engine itself — it contains a semantic search engine over its own
+   capabilities, and it is better at finding the right module than grep:
+       import lecore
+       mind = lecore.UnifiedMind()
+       mind.find_capability("prevent hallucination")
+       mind.suggest("compress a float series")
+
+## Docs
+
+- [CAPABILITIES.md](CAPABILITIES.md): the capability menu — read this first
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): the whole system, then the parts
+- [docs/SHOWCASE.md](docs/SHOWCASE.md): what almost every summary misses; what it is not
+- [docs/ISA.md](docs/ISA.md): the instruction set whose programs are hypervectors
+- [docs/CONVENTIONS.md](docs/CONVENTIONS.md): the engineering contracts
+- [docs/INSTALLED.md](docs/INSTALLED.md): manifest schema for model cards + what installs into weights (and what cannot)
+- [docs/NOTES_concepts.md](docs/NOTES_concepts.md): the honest lab notebook (wins AND kept negatives)
+- [REFERENCE.md](REFERENCE.md): full generated module reference
+
+## Key facts
+
+- Pure NumPy + Flask + stdlib + hashlib. No torch, no GPU, no learned weights in core.
+- Deterministic: bit-reproducible under any PYTHONHASHSEED; one stated tie rule everywhere.
+- Every claim ships with its measurement; refuted ideas are kept on record as negatives.
+- ~600 modules, one UnifiedMind facade, ~2,000 faculties, 6,300+ tests, audits at 0/0/0.
+- Approximate search must measure its own recall on YOUR data or demote to exact.
+- Retrieval can refuse (calibrated abstention) instead of hallucinating a match.
+- Programs compile into certified model weights (residual + conditioning +
+  quantization + sha256 certificates); model files are ~250-byte RULES that
+  re-bake bit-identical weights. Live models: https://huggingface.co/staccs

API_QUICKREF.md

@@ -141,25 +141,11 @@
 ## Transforms
 
 ### `holographic_transform`
-*holographic_transform.py -- TRANSFORM UTILITIES for a modeling app (modeling-app backlog, item G).*
-
-- `translation(t)` -- A 4x4 translation matrix from a 3-vector.
-- `scaling(s)` -- A 4x4 scale matrix.
-- `rotation_axis_angle(axis, angle)` -- A 4x4 rotation of `angle` radians about `axis` (Rodrigues' formula).
-- `compose(*mats)` -- Matrix product M0 @ M1 @ ...
-- `decompose(M)` -- Split a 4x4 affine transform into (translate (3,), rotation quaternion (4,), scale (3,)).
-- `compose_trs(translate, quat, scale)` -- Build a 4x4 from translate (3,), a rotation quaternion (4,), and scale (3,) -- the inverse of decompose.
-- `quat_normalize(q)` -- 
-- `quat_mul(a, b)` -- The Hamilton product a*b: the rotation "apply b, then a".
-- `quat_from_axis_angle(axis, angle)` -- A quaternion for a rotation of `angle` radians about `axis`.
-- `quat_to_axis_angle(q)` -- Recover (axis, angle) from a quaternion.
-- `quat_to_matrix(q)` -- The 3x3 rotation matrix for a quaternion.
-- `quat_from_matrix(R)` -- The quaternion for a 3x3 rotation matrix (Shepperd's method: branch on the largest diagonal term for numerical stability -- a naive formula loses precision when the trace is near zero).
-- `quat_from_euler(rx, ry, rz)` -- A quaternion from euler angles applied X then Y then Z (R = Rz @ Ry @ Rx).
-- `quat_to_euler(q)` -- Recover euler angles (rx, ry, rz) from a quaternion, inverting R = Rz @ Ry @ Rx.
-- `quat_slerp(a, b, t)` -- Spherical linear interpolation between two rotations -- constant angular speed, the smooth in-between an animation wants.
-- `quat_rotate(q, v)` -- Rotate a 3-vector by a quaternion.
-- `look_at(eye, target, up=(0.0, 1.0, 0.0))` -- An OpenGL view matrix for a camera at `eye` looking at `target` (the engine's convention: the camera looks down -z, y is up).
+*TRANSFORM -- rebuild a model where the MEASUREMENT says it needs rebuilding.*
+
+- `analyse(weights, cfg)` -- Recover the block structure and per-layer memory from the weights.
+- `plan(weights, cfg, target_tokens=4096, kv_rank=64, grow_gain=0.0)` -- Decide what to do to each layer, from the analysis rather than by rule.
+- `apply_plan(weights, cfg, the_plan, progress=None)` -- Carry out the growth actions.
 
 ## Camera
 
@@ -186,7 +172,7 @@
     - `projection_matrix(self, aspect=None)` -- Perspective projection (OpenGL-style, maps the frustum to the [-1,1] cube).
     - `ray_dirs(self, width, height, jitter=None)` -- Per-pixel world-space ray origins (the eye) and unit directions, shape (H, W, 3), for ray marching.
 - **class `Light`** -- A light.
-- `rasterize_mesh(mesh, camera, width=512, height=512, lights=None, base_color=(0.8, 0.8, 0.8), background=(0.05, 0.06, 0.08), ambient=0.15, vectorized=True, texture=None, uvs=None, smooth=False, two_sided=False, vertex_colors=None)` -- Rasterise a triangle mesh to an (H, W, 3) RGB image in [0,1] with a z-buffer and per-face Lambert shading.
+- `rasterize_mesh(mesh, camera, width=512, height=512, lights=None, base_color=(0.8, 0.8, 0.8), background=(0.05, 0.06, 0.08), ambient=0.15, vectorized=True, texture=None, uvs=None, smooth=False, two_sided=False, vertex_colors=None, pbr=None)` -- Rasterise a triangle mesh to an (H, W, 3) RGB image in [0,1] with a z-buffer and per-face Lambert shading.
 - `volume_render(field, camera, bounds, width=256, height=256, steps=96, mode='smoke', sigma=12.0, emission_color=None, albedo=(0.9, 0.9, 0.95), lights=None, background=(0.0, 0.0, 0.0), early_term=True, empty_skip=True, occ_res=24, occ_thresh=0.001, term_eps=0.002, self_shadow=False, shadow_steps=16, shadow_sigma=None, ambient=(0.42, 0.52, 0.66), phase_g=0.0, powder=False, multi_scatter=1, only=None)` -- Render a density FIELD (callable points(N,3)->density>=0) volumetrically by marching camera rays through `bounds`=(min_corner, max_corner) and accumulating the volume-rendering integral.
 - `png_bytes(rgb01, level=6, filters=True)` -- Encode an (H,W,3) image in [0,1] to PNG *bytes* -- a minimal, pure-stdlib encoder (zlib + struct), so the render module carries no image-library dependency.
 - `png_decode(data)` -- Decode PNG *bytes* to (array, info) -- the read side of `png_bytes`, pure stdlib (zlib + struct).
@@ -225,17 +211,11 @@
     - `run_on_vm(self, machine=None, scene=None, seed=0, prev_frame=None, renderer=None)` -- Phase 6: RUN the pipeline ON the VM instead of a Python for-loop.
 
 ### `holographic_session`
-*holographic_session.py -- ONE render session that ties the disconnected rendering threads together.*
-
-- `sdf_surface_points(sdf, bounds, n=2000, seed=0, eps=0.02, oversample=8)` -- Sample points that lie ON an SDF's surface -- the front half of the SDF->splat bridge that was missing.
-- **class `RenderSession`** -- One scene, every renderer.
-    - `preview(self, width=None, height=None, reuse_margin=None, **kw)` -- FAST path: the material preview via render_surface (Lambert + spec + env reflection + one transparency layer), resolving every SurfaceMaterial channel per hit.
-    - `cache_stats(self)` -- {hits, rebuilds, hit_rate, margin} for the preview's fat-margin cache, or None if it is not in use.
-    - `invalidate_preview(self)` -- Drop the preview cache -- call after any scene edit.
-    - `render_final(self, spp=64, on_progress=None, progress_every=8, width=None, height=None, max_bounce=4, sky=None, seed=0, should_stop=None)` -- SLOW path: the photoreal final via path_trace, using the SAME SurfaceMaterials as the preview (through the material adapter).
-    - `to_splats(self, n=2000, radius=0.12, seed=0)` -- PROXY path: sample the SDF surface and fit splats (field_to_splats) so the scene can be drawn by a lightweight browser billboard shader -- no three.js scene graph, no mesh pipeline.
-    - `set_material(self, obj_id, material)` -- Replace one object's material.
-    - `edit_channel(self, obj_id, channel, value)` -- Edit ONE channel of one object's material (colour/roughness/reflect/emission/opacity) -- the value can be a constant, a Param, a pattern field, or a map.
+*SESSION -- never compute the same conversation prefix twice.*
+
+- **class `PrefixCache`** -- A radix tree over token sequences, holding inference states.
+    - `forward(self, token_ids)` -- Logits for this sequence, computing only the uncached tail.
+    - `report(self)` -- 
 
 ### `holographic_cancel`
 *holographic_cancel.py -- COOPERATIVE CANCELLATION for long operations (modeling-app backlog, item F).*