arborist/docs/v7w-frontier-catalog.md
russell@unturf.com ee22a83a0a
#000013 closed: v7-W spatial-temporal substrate paper + namespace
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).
2026-05-09 15:00:05 -04:00

262 lines
7.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# v7-W ε-frontier catalog
**Companion to:** `docs/_source/merkle-agi-v7w-spatial-temporal.rst`
(the v7-W substrate paper, ticket #000013).
**Status:** draft v0, 2026-05-09.
This catalog enumerates the four canonical ε-frontiers in
v7-W — the kernel-boundaries where ε proofs are admissible. Each
is **affine after appropriate canonical projection** (T4-W) and
each has a published quantization-derived ε bound.
A frontier is the boundary between "model forward pass" and
"committed integer kernel." Below the frontier, proofs are at
the float-tensor level (v7's domain). Above the frontier,
canonical bytes admit replay-audit.
---
## Reference table
| Frontier | Domain | Canonical kernel | ε bound | Reuses |
|---|---|---|---|---|
| `pose_integration` | object pose / agent ego-motion | SE(3) integer composition | Δ_rot + Δ_trans · |t_max| | v7 § 5 bigint accumulator |
| `observation_update` | Kalman / Bayesian state update | affine in innovation | Δ_innovation + Δ_covariance | v7 § 5; arithmetic@v1 for residual fold |
| `object_logits` | per-object classification logits | linear projection | manifest-declared per-class | v7 § 11 multimodal composition |
| `relation_logits` | pairwise scene-graph edge prediction | bilinear scoring | predicate-whitelist + feature granularity | v7 § 11; relation_graph carrier |
Each frontier's full design lives in the substrate paper Part 4;
this catalog is the operator-facing quick reference.
---
## §1 `pose_integration`
**Inputs (canonical bytes):**
```
{
"prev_pose_quantized": {
"axis_angle_int32": [<int32 x 3>],
"translation_int32": [<int32 x 3>]
},
"ego_motion_quantized": {
"axis_angle_int32": [<int32 x 3>],
"translation_int32": [<int32 x 3>]
},
"Δ_t_ticks": <int32>
}
```
**Output:**
```
{
"next_pose_quantized": {
"axis_angle_int32": [<int32 x 3>],
"translation_int32": [<int32 x 3>]
}
}
```
**Operator.** SE(3) composition. The axis-angle representation
is integer-encoded with manifest-declared `Δ_rot_milli_radians`;
translation in `Δ_trans_micrometers`. Composition uses bigint
arithmetic to avoid float drift, then re-quantizes to the
manifest grid.
**ε bound.** Per-step: `Δ_rot + Δ_trans · |translation_max|`.
**Affine after canonical projection.** The axis-angle
representation linearizes rotation under small-time-step
assumption (the common SLAM regime); the linearization error
is bounded by the small-angle approximation residual, captured
in the manifest's published `Δ_rot_residual_bound` field.
**When to use.** Every agent-trace tick. Every object whose
pose changes between observations.
---
## §2 `observation_update`
**Inputs (canonical bytes):**
```
{
"prior_state_quantized": [<int32 x state_dim>],
"prior_covariance_quantized": [[<int32>], ...],
"observation_quantized": [<int32 x obs_dim>],
"innovation_covariance_quantized": [[<int32>], ...],
"observation_matrix_quantized": [[<int32>], ...]
}
```
**Output:**
```
{
"posterior_state_quantized": [<int32 x state_dim>],
"posterior_covariance_quantized": [[<int32>], ...]
}
```
**Operator.** Standard Kalman update:
```
innovation = observation - H · prior_state
K_gain = prior_cov · H^T · (H · prior_cov · H^T + innov_cov)^-1
posterior_state = prior_state + K_gain · innovation
posterior_cov = (I - K_gain · H) · prior_cov
```
All arithmetic uses bigint accumulators (v7 § 5) to avoid
analog leakage in the matrix inversion. Final values
re-quantized to the manifest grid.
**ε bound.** Per-step: `Δ_innovation + Δ_covariance`.
**Affine after canonical projection.** Innovation is affine in
observation; gain application is affine in innovation; posterior
update is affine in gain. The matrix inverse is the only
non-affine step — handled by bigint arithmetic + re-quantization
so the canonical bytes remain deterministic.
**When to use.** Every observation that updates a stateful
estimate (object pose, agent location, place geometry).
Stateless classifications (single-frame object detection
without temporal smoothing) skip this frontier.
---
## §3 `object_logits`
**Inputs (canonical bytes):**
```
{
"object_features_quantized": [<int32 x feature_dim>],
"classifier_weights_quantized": [[<int32>], ...],
"classifier_bias_quantized": [<int32 x num_classes>]
}
```
**Output:**
```
{
"logits_quantized": [<int32 x num_classes>]
}
```
**Operator.** Linear projection: `logits = W · features + b`.
All on quantized integers. Pre-softmax — softmax itself is
NOT in the kernel (softmax is monotone and order-preserving
on the logits, so commitments to logits implicitly commit to
the softmax-class predictions).
**ε bound.** Manifest-declared per-class quantization
threshold. Typical values: 1/256 of the full logit range.
**Affine after canonical projection.** Linear-in-features by
construction.
**When to use.** Every object-detection commitment. Multimodal
pipelines that route through v7's vision encoder use this
frontier as the v7→v7-W handoff.
---
## §4 `relation_logits`
**Inputs (canonical bytes):**
```
{
"subject_features_quantized": [<int32 x feature_dim>],
"object_features_quantized": [<int32 x feature_dim>],
"relation_classifier_weights_quantized": [[<int32>], ...]
}
```
**Output:**
```
{
"relation_logits_quantized": [<int32 x predicate_count>]
}
```
**Operator.** Bilinear scoring on the (subject, object) feature
pair. The bilinear tensor B is canonicalized to its tensor-
decomposed form (Tucker decomposition with manifest-declared
ranks; or CP decomposition for low-rank cases). Scoring then
factorizes:
```
score_per_predicate = subject_features · core · object_features^T
```
…with `core` being the canonicalized decomposition.
**ε bound.** `predicate-whitelist size factor + feature
quantization`. The whitelist size factor accounts for the
finite alphabet of declared predicates per substrate.
**Affine after canonical projection.** Bilinear becomes affine
once the subject (or object) features are fixed; the
factorization makes this explicit. Substrate manifest pins the
factorization rank to keep the canonical bytes deterministic.
**When to use.** Every scene-graph edge commitment. Relation
extraction in multimodal pipelines.
---
## Cumulative ε across frontiers
Per the data-processing inequality, ε accumulates additively
across composed kernels:
```
ε_total = Σ_frontier (ε_frontier × invocation_count)
```
A typical 10-tick agent trace with 3 detected objects + 6
relations:
```
10 ticks × (pose_integration + observation_update)
+ 30 object_logits invocations (3 obj × 10 ticks)
+ 60 relation_logits invocations (6 rel × 10 ticks)
```
Each invocation contributes its frontier's per-step ε. Operators
size their grid choices (manifest's Δ values) to keep ε_total
under the downstream consumer's tolerance.
---
## Out of scope (per #000013 §5)
- **Continuous-state kernels** that haven't been re-canonicalized
to integer state. v7-W requires explicit integer-encoding;
proofs at the float layer live in v7 + arborist's existing
integer-kernel discipline (SQD § 5).
- **Sensor-specific kernels** (LIDAR ICP, RGB-D fusion). Each is
a separate adapter ticket; the four frontiers above are the
*abstract* kernel set, not deployment-specific implementations.
- **Cross-substrate frontiers** (v7-W ↔ arborist-text). Captured
by the cross-domain π* composition theorem (#000015) and the
multimodal composition section in the v7-W substrate paper
(Part 5).
---
## Status
Catalog draft v0. Each frontier's full proof-of-affine-property
and ε derivation will be folded back into the substrate paper
(Part 3 theorems) once the catalog stabilizes. This document is
the operator-facing quick reference; the substrate paper is the
formal source.