russell@unturf.com
ee22a83a0a
Three artifacts landing per ticket §4.1 closure criterion:
1. docs/_source/merkle-agi-v7w-spatial-temporal.rst (658 lines)
============================================================
Substrate paper for the third commitment substrate — sister to v7
(logic / math) and arborist v9.8 (language / claim-lattice). v7-W
commits derived spatial-temporal world-state: objects, relations,
events, places, agent traces, observations. Six parts + appendix:
Part 1 — Introduction & motivation. The third-substrate gap;
why v7 § 11 multimodal composition isn't enough.
Part 2 — Substrate definition. Hierarchical-grid spatial
discretization (S2 / H3 / octree); frame as committed
object with explicit transforms; substrate-declared
clock (single-agent) + Lamport (multi-agent);
quantized centi-confidence (range opt-in); five
canonical tuple-classes (object / relation / event /
place / agent_trace) each with its own π*_w.
Part 3 — Theorems. T1-W (state binding), T2-W (causal
completeness), T3-W (frame-transform soundness),
T4-W (ε at affine frontiers).
Part 4 — Verifier kernels. Pose integration, observation
update (Kalman), object logits, relation logits.
Each affine after canonical projection.
Part 5 — Multimodal composition with v7. Where v7 ends, v7-W
begins; cumulative ε across substrates; frame-
transform anchoring.
Part 6 — Adversarial corners. Frame spoofing, time skew,
observation injection, privacy.
Appendix — Worked SLAM example with full ε budget.
Hard constraints honored: stays inside SQD A1-A3 (canonical
encoding, public quantization, collision-resistant hash); no new
axiom; every π*_w defined on quantized integer state, never on
continuous tensors.
2. docs/v7w-frontier-catalog.md (262 lines)
============================================
Operator-facing quick reference for the four ε-frontiers from
substrate-paper Part 4. Each entry:
- canonical input / output bytes
- operator (linear / bilinear / Kalman / SE(3))
- ε bound expression
- "affine after canonical projection" justification
- when to use
Reference table + cumulative-ε section so operators sizing
deployment grid choices can read off their ε_total under typical
agent-trace + scene-graph workloads.
3. arborist/world/__init__.py — namespace reservation
======================================================
Reserved ``arborist.world`` package. No kernels yet. Module
exports V7W_VERSION ('v0-draft') + STATUS ('namespace_reserved')
metadata. Package docstring lays out the future shape per
substrate-paper Part 4:
arborist/world/
├── pi_star/ — π*_w canonical projections (5 tuple classes)
├── frontier/ — ε-frontier kernels (4 frontiers)
├── frame.py — frame definitions + transforms
├── clock.py — wall-clock + Lamport
├── manifest.py — substrate manifest schema
└── adapters/ — sensor adapters land here, separate tickets
Implementation tickets cite the substrate paper and land kernels
one at a time; the stub exists so cross-referencing imports (mesh
peers, sibling repos) can pin the namespace before anything
implements it.
5 tests pin the reservation contract (test_world_namespace.py):
import succeeds, V7W_VERSION reports v0-draft, STATUS reads
namespace_reserved, __all__ exposes only metadata, substrate
paper + frontier catalog files exist alongside the namespace.
Closure criterion (#000013 §7): substrate paper lands and is
ready for review. Done. Status flipped to closed in the ticket
file + TICKETS.md index entry.
Test suite: 1641 passed, 37 skipped (was 1636; +5).
|
||
|---|---|---|
| .. | ||
| _ext | ||
| _static | ||
| api | ||
| bench.rst | ||
| concepts.rst | ||
| conf.py | ||
| cookbook.rst | ||
| diagrams | ||
| index.rst | ||
| license.rst | ||
| Makefile | ||
| merkle-agi-v7w-spatial-temporal.rst | ||
| pi-star.rst | ||
| quickstart.rst | ||
| README.md | ||
| requirements.txt | ||
| v8-fork-score.rst | ||
Arborist API Reference (Sphinx)
This directory contains Sphinx configuration to generate API documentation from docstrings.
Build
cd docs/_source
make html # Generate HTML (output: _build/html/)
make text # Generate text (output: _build/text/)
make clean # Remove build artifacts
Or directly:
sphinx-build -b html . _build/html
View
After building, open _build/html/index.html in a browser.
Structure
conf.py— Sphinx configurationindex.rst— Main table of contentsapi/— Module documentation (one .rst per module category)substrate.rst— Core data structures (merkle, document, wikitext)storage.rst— SQLite schema (store, ingest, evict)retrieval.rst— FTS5 search (search, sources, concepts)qa.rst— Q&A pipeline (runner, query, verify, evidence, etc.)distill.rst— Distillation (surface→core)mesh.rst— Federation (gossip-based sync)cli.rst— Command-line interface
What it replaces
This generated documentation replaces docs/modules.md (1200+ lines of static API reference). The docstrings in code are the source of truth; Sphinx extracts them automatically.
Adding new modules
- Add a docstring to the module (module-level docstring at the top of
module.py) - Add an
.rstfile inapi/that includes the module withautomoduledirective - Reference it in
index.rst - Rebuild with
make html
Theme
Uses furo theme (modern, responsive, search-enabled).
Autodoc directives
The .rst files use Sphinx automodule to extract:
- Module docstrings
- Class docstrings + members
- Function signatures + docstrings
- Source code links (
:viewcode:extension)
See Sphinx autodoc docs.