AXIS–MIRA V7: SkinTokens++ Mechanics-first coupled rig/skin research

.github/workflows/axis_mira_v7_research.yml

@@ -0,0 +1,55 @@
+name: axis-mira-v7-research
+
+on:
+  pull_request:
+    paths:
+      - 'models/axis/rig_program_model_v7.py'
+      - 'models/mira/skin_fsq_codec_v7.py'
+      - 'models/mira/skin_attention_codec_v7.py'
+      - 'compiler/realsas_compiler_core/mechanics_interaction_v1.py'
+      - 'tests/models/test_axis_mira_v7_research.py'
+      - 'canonical/AXIS_MIRA_V7_CORPUS370_PREREG_V1.json'
+      - 'docs/research/AXIS_MIRA_V7_SKINTOKENS_PLUSPLUS_20261106.md'
+      - '.github/workflows/axis_mira_v7_research.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  v7-contract-courts:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - name: Install CPU research requirements
+        run: |
+          set -euo pipefail
+          python -m pip install --no-input --progress-bar off -r requirements/mainline-ci.txt
+          python -m pip install --no-input --progress-bar off -r requirements/torch-cpu.txt
+      - name: Syntax
+        run: |
+          python -m py_compile models/axis/rig_program_model_v7.py models/mira/skin_fsq_codec_v7.py models/mira/skin_attention_codec_v7.py compiler/realsas_compiler_core/mechanics_interaction_v1.py
+      - name: Source and Mechanic court
+        run: |
+          pytest -q tests/models/test_axis_mira_v7_research.py
+      - name: Verify no V7 training authority was minted
+        run: |
+          python - <<'PY'
+          import json
+          from pathlib import Path
+          d = json.loads(Path('canonical/AXIS_MIRA_V7_CORPUS370_PREREG_V1.json').read_text())
+          assert d['training']['allowed_now'] is False
+          assert d['training']['checkpoint_product_authority'] is False
+          assert d['owner_contract']['graphics'] == 'SEPARATE_IRIS_LINKED_GRAPHICS_COMPILER'
+          assert d['skin']['vocab_size'] == 64000
+          assert d['skin']['source_vae_attention_parity_claimed'] is False
+          print('AXIS_MIRA_V7_RESEARCH_AUTHORITY_SEALED')
+          PY

canonical/AXIS_MIRA_V7_CORPUS370_PREREG_V1.json

@@ -0,0 +1,60 @@
+{
+  "schema": "RealSaS.AxisMiraV7Corpus370Prereg.v1",
+  "date_utc": "2026-11-06",
+  "status": "RESEARCH_SOURCE_ONLY__NO_TRAINING_AUTHORITY",
+  "branch": "research/axis-mira-v7-skintokens-control-370",
+  "source_cohort": {
+    "candidate_count": 370,
+    "admitted_for_training": null,
+    "observation_pass_not_equivalent_to_truth_admission": true,
+    "upstream_work": "PR #327"
+  },
+  "owner_contract": {
+    "axis": "LEARNED_MECHANICS_RIG_CONTROL_AND_SKIN_CODE",
+    "mira": "LEARNED_MECHANICAL_SKIN_FIELD_CODEC",
+    "mechanics": "EXECUTABLE_CONSTRAINTS_IK_DEFORMATION_INTERACTION",
+    "graphics": "SEPARATE_IRIS_LINKED_GRAPHICS_COMPILER",
+    "motion": "CONTROL_SPACE_MOTION"
+  },
+  "rig": {
+    "architecture_id": "RealSaS.AXIS.UnifiedRigControlSkin.CausalCrossAttention.v7_0",
+    "scene_dim": 47,
+    "hidden_dim": 768,
+    "layers": 16,
+    "heads": 12,
+    "max_sequence_length": 4096,
+    "skin_vocab_size": 64000
+  },
+  "skin": {
+    "architecture_id": "RealSaS.MIRA.CarrierNativeFSQ.STGradient.ActiveField.v7_0",
+    "tokens_per_joint": 4,
+    "fsq_levels": [
+      8,
+      8,
+      8,
+      5,
+      5,
+      5
+    ],
+    "vocab_size": 64000,
+    "source_vae_attention_parity_claimed": false
+  },
+  "required_receipts": [
+    "CORPUS370_SOURCE_FAMILY_QUALIFICATION",
+    "CORPUS370_MECHANICS_INTERVENTION_TRUTH",
+    "CORPUS370_CANONICAL_MESH_SHARED_SCENE_BINDINGS",
+    "CORPUS370_DENSE_SKIN_TARGET_AUTHORITY",
+    "CORPUS370_LEAKAGE_CONNECTED_TRAIN_UNSEEN_SPLIT",
+    "MIRA_V7_CODEC_FROZEN_TRAIN_ONLY",
+    "AXIS_V7_CAUSAL_EVENT_TEACHER_SEAL",
+    "MECHANICS_INTERACTABILITY_BEHAVIOR_COURT"
+  ],
+  "training": {
+    "allowed_now": false,
+    "checkpoint_product_authority": false,
+    "unseen_tuning_allowed": false,
+    "source_name_student_truth_allowed": false,
+    "compiler_control_synthesis_allowed": false,
+    "graphics_train_target_in_axis_mira": false
+  }
+}

compiler/realsas_compiler_core/mechanics_interaction_v1.py

@@ -0,0 +1,127 @@
+from __future__ import annotations
+
+"""Mechanics-only implicit control selection for a picked carrier triangle.
+
+This is a read-only runtime selection of ALREADY DECLARED controls; it never
+synthesizes controls, animates graphics, or mints CanonicalRig authority.
+The caller supplies the hit triangle and barycentrics from a presentation hit
+test. Returned control IDs are opaque; only Mechanics interprets their action.
+"""
+
+from dataclasses import dataclass
+import math
+
+from .canonical_rig_ir_v2 import CanonicalRigIRV2
+from .canonical_skin_ir_v2 import CanonicalSkinIRV2
+from .types import QualificationError
+
+
+@dataclass(frozen=True)
+class MechanicsPickCandidateV1:
+    canonical_control_id: str
+    control_kind: str
+    influence_score: float
+    supporting_joint_ids: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class MechanicsSurfacePickV1:
+    triangle_vertex_ids: tuple[str, str, str]
+    barycentric: tuple[float, float, float]
+    candidates: tuple[MechanicsPickCandidateV1, ...]
+    rig_lineage_hash: str
+    skin_lineage_hash: str
+    status: str  # CANDIDATES | ABSTAIN_NO_DECLARED_CONTROL
+
+
+def select_mechanics_controls_from_surface_v1(
+    rig: CanonicalRigIRV2,
+    skin: CanonicalSkinIRV2,
+    *,
+    triangle_vertex_ids: tuple[str, str, str],
+    barycentric: tuple[float, float, float],
+    maximum_candidates: int = 8,
+    minimum_support: float = 1e-6,
+) -> MechanicsSurfacePickV1:
+    if rig.mesh_lineage_hash != skin.mesh_lineage_hash:
+        raise QualificationError("MECHANICS_PICK_MESH_LINEAGE_DRIFT")
+    if rig.deform_structure_hash != skin.deform_structure_hash:
+        raise QualificationError("MECHANICS_PICK_DEFORM_LINEAGE_DRIFT")
+    if maximum_candidates < 1 or not (0.0 <= minimum_support <= 1.0):
+        raise QualificationError("MECHANICS_PICK_POLICY_INVALID")
+    if len(triangle_vertex_ids) != 3 or len(set(triangle_vertex_ids)) != 3:
+        raise QualificationError("MECHANICS_PICK_TRIANGLE_INVALID")
+    if len(barycentric) != 3 or not all(math.isfinite(float(x)) and float(x) >= 0.0 for x in barycentric):
+        raise QualificationError("MECHANICS_PICK_BARYCENTRIC_INVALID")
+    mass = sum(barycentric)
+    if abs(mass - 1.0) > 1e-5:
+        raise QualificationError("MECHANICS_PICK_BARYCENTRIC_NOT_SIMPLEX")
+
+    by_vertex = {row.canonical_mesh_vertex_id: row for row in skin.rows}
+    if len(by_vertex) != len(skin.rows):
+        raise QualificationError("MECHANICS_PICK_DUPLICATE_SKIN_VERTEX")
+    if any(vid not in by_vertex for vid in triangle_vertex_ids):
+        raise QualificationError("MECHANICS_PICK_SKIN_VERTEX_UNKNOWN")
+
+    influence: dict[str, float] = {}
+    for vid, bary in zip(triangle_vertex_ids, barycentric):
+        for joint_id, weight in by_vertex[vid].influences:
+            value = float(weight)
+            if not math.isfinite(value) or value < 0.0:
+                raise QualificationError("MECHANICS_PICK_SKIN_WEIGHT_INVALID")
+            influence[joint_id] = influence.get(joint_id, 0.0) + float(bary) * value
+
+    joint_ids = {j.canonical_joint_id for j in rig.joints}
+    if not set(influence).issubset(joint_ids):
+        raise QualificationError("MECHANICS_PICK_JOINT_UNKNOWN")
+    chains = {row.canonical_chain_id: row for row in rig.chains}
+    # IK effectors are recognized only through their DECLARED constraint inputs.
+    ik_targets: dict[str, set[str]] = {}
+    for constraint in rig.constraints:
+        if constraint.operator_id != "IK" or constraint.canonical_chain_id is None:
+            continue
+        chain = chains.get(constraint.canonical_chain_id)
+        if chain is None or not chain.canonical_joint_ids:
+            raise QualificationError("MECHANICS_PICK_CHAIN_UNKNOWN")
+        tip = chain.canonical_joint_ids[-1]
+        for control_id in constraint.input_canonical_control_ids[:1]:
+            ik_targets.setdefault(control_id, set()).add(tip)
+
+    candidates: list[MechanicsPickCandidateV1] = []
+    seen: set[str] = set()
+    for control in rig.controls:
+        cid = control.canonical_control_id
+        if cid in seen:
+            raise QualificationError("MECHANICS_PICK_DUPLICATE_CONTROL")
+        seen.add(cid)
+        if control.control_kind not in {"IK_EFFECTOR", "FK", "ROOT", "SPLINE", "AIM_TARGET", "SOCKET_CONTROL"}:
+            continue
+        targets = set(control.target_canonical_joint_ids)
+        if control.control_kind == "IK_EFFECTOR":
+            targets.update(ik_targets.get(cid, set()))
+        if not targets or not targets.issubset(joint_ids):
+            continue
+        support = sum(influence.get(jid, 0.0) for jid in targets)
+        if support < minimum_support:
+            continue
+        candidates.append(MechanicsPickCandidateV1(
+            canonical_control_id=cid,
+            control_kind=control.control_kind,
+            influence_score=float(support),
+            supporting_joint_ids=tuple(sorted(targets)),
+        ))
+    candidates.sort(key=lambda x: (-x.influence_score, x.canonical_control_id))
+    return MechanicsSurfacePickV1(
+        triangle_vertex_ids=triangle_vertex_ids,
+        barycentric=tuple(map(float, barycentric)),
+        candidates=tuple(candidates[:maximum_candidates]),
+        rig_lineage_hash=rig.rig_lineage_hash,
+        skin_lineage_hash=skin.skin_lineage_hash,
+        status="CANDIDATES" if candidates else "ABSTAIN_NO_DECLARED_CONTROL",
+    )
+
+
+__all__ = [
+    "MechanicsPickCandidateV1", "MechanicsSurfacePickV1",
+    "select_mechanics_controls_from_surface_v1",
+]

docs/research/AXIS_MIRA_V7_SKINTOKENS_PLUSPLUS_20261106.md

@@ -0,0 +1,89 @@
+# AXIS–MIRA V7 / SkinTokens++ — Mechanics-first research contract
+
+**Date:** 2026-11-06  
+**Status:** `RESEARCH_CODE_ONLY__NO_TRAINING_AUTHORITY__NO_PRODUCT_MODELRELEASE`  
+**Parent:** V6 product branch `axis-v6-rig-program-product`; isolated PR stack.  
+**Goal:** compiled puppet is natively controllable ("You can play with your puppet").
+
+## Ownership is non-negotiable
+
+| Domain | Authority | What it owns |
+|---|---|---|
+| Shape / geometry | IRIS + TESSA / qualified Mesh | shared 3D evidence and mechanical carrier geometry |
+| **Rig/Skin learning** | **AXIS–MIRA V7** | skeleton and rest geometry; frame/DOF; controls and relations; compact skin influence fields |
+| **Mechanical execution** | **Mechanics Compiler/runtime** | constraint solving, IK/FK, skin deformation, contact/limits, attachment transforms, typed residuals |
+| **Graphics** | **IRIS-linked Graphics domain + Graphics Compiler** | CAA/appearance, layer decomposition, occlusion, draw order, visibility, 2D presentation |
+| Motion | Control-space motion | editable control trajectories executed by Mechanics |
+
+The Mechanics result may be consumed by Graphics, but neither AXIS–MIRA nor Mechanics owns graphics decisions. No AXIS model target for alpha/layer/RGB/draw order is permitted.
+
+## SkinTokens++ — upstream baseline and what *plus* must mean
+
+Researched the **official source**, not just the paper. Reference repository: https://github.com/VAST-AI-Research/SkinTokens.
+Source files reviewed on 2026-11-06:
+
+- `src/model/tokenrig.py` — GitHub blob `ab35e3fb8dd850737cba7d1782f03c75846971be`: Qwen3 0.6B-style autoregressive model; learned Michelangelo mesh conditioning; vocabulary switch grammar; frozen skin VAE in TokenRig.
+- `src/model/skin_vae/autoencoders/skin_fsq_cvae_model.py` — blob `6b66d9e9486d261f0a5d67f795bbe60499fb26e3`: separate skin and conditional attention encoders, query sampling, latent quantization, learned decoder with sampled conditioning.
+- `src/model/skin_vae/autoencoders/FSQ.py` — blob `9f7bcf0e670071a04a19495ea8efa7d3ead0a1fe`: differentiable round-STE finite scalar quantization, integer-code conversions.
+- `src/model/skin_vae_model.py` — blob `a2b4e88b6997883ce5861333bb498dc9593ff80d`: token compression / decompression, per-bone examples, sampling and training wrapper.
+- `src/tokenizer/spec.py` — blob `d4cc653519937bb98d6059d765686e2ea53b89dc`: structural skeleton sequence and parent-link tokenization.
+
+Their published checkpoint naming includes `skin_vae_2_10_32768`. **Our 64,000 vocabulary is a new local configuration, not evidence of checkpoint or tokenizer compatibility**. Never suggest that official weights load directly. Respect repository/model licenses and provenance independently.
+
+### Mechanistic comparison
+
+| Capability | Upstream TokenRig / SkinTokens | RealSaS V7 initial implementation | Next step |
+|---|---|---|---|
+| Unified skeleton + skin sequence | Yes | Yes, via typed V6 wire reused by V7 | new event grammar for interaction-affordance targets only after teacher seal |
+| FSQ + straight-through reconstruction | Yes | V7 MIRA uses true gradient-carrying code path | verify with reconstruction-only backward court |
+| Spatial attention-based VAE | Yes | Two V7 options: baseline uses weighted pooling; new **learned-query local attention candidate** encodes active sampled support. Not exact upstream CVAE parity | compare baseline and new attention candidate under equal train/validation budgets; add geometry-conditioned decoder attention only if measured improvements justify it |
+| Rig conditioning | Learned mesh encoder | Current IRIS/TESSA-adaptable 47-D surface evidence seam | first-class versioned shared-scene adapter, no hidden oracle truth |
+| Skeleton generation | Yes | V6 RigProgram language extended by large V7 decoder | require true free-running unseen tests |
+| Control rig / interaction affordances | Not the core TokenRig target | V6 control/constraint program + runtime implicit pick from declared controls | learned/evidence-grounded affordances; local DOF/limit solver |
+| Real-time deformation | Downstream use after rigging | V6 Mechanics solver; new pick selection bridge | batched/C++ runtime; contact and joint-limit courts |
+| 2D drawing/occlusion | Not a TokenRig output | **Not owned here** | downstream Graphics consumers only |
+
+## Implementation in this V7 research branch
+
+- `models/mira/skin_fsq_codec_v7.py`: 64k code vocabulary from (8,8,8,5,5,5), 4 tokens/joint, large carrier ceiling, sparse-aware reconstruction, teacher-relative edge gradient loss, reconstruction-only STE gradient. **Initial codec baseline, not full official architecture.**
+- `models/mira/skin_attention_codec_v7.py`: source-inspired but independently implemented learned-query per-joint attention with bounded active-support top-k sampling, inherited straight-through FSQ decode. Not weight compatible with upstream.\n- `models/axis/rig_program_model_v7.py`: 16 x 768, 12-head conditional causal model; typed RigProgram + SkinCodes, tied embedding/output projection, sparse skin logits at SKIN_CODE positions, V6 wire contract and variable morpologies.
+- `compiler/realsas_compiler_core/mechanics_interaction_v1.py`: generic barycentric hit-to-declared-control scoring over qualified skin/rig. This is runtime interpretation of already generated structure; it **does not** synthesize control rig, choose new rig parents, or make Graphics decisions.
+- `tests/models/test_axis_mira_v7_research.py`: reconstruction-only gradient, hard-code parity, sparse CE/backprop, read-only pick, fail-closed lineage.
+
+## Corpus370 policy
+
+**370 is a candidate acquisition universe, NOT 370 qualified training examples.** Existing PR #327 retains 352 observation PASS / 18 original mask FAIL while further family courts, source-locus ownership evidence, mechanical target qualification and lineage-safe splits remain open. Do not train V7 simply because source observations pass.
+
+V7 requires separated versioned receipts:
+
+1. (Mesh, scene, Rig, Skin) source-to-canonical mapping with evidence and no privileged source-name leakage.
+2. Mechanically intervention-tested joint/frame/DOF labels; absence/ambiguous labels typed as masked/abstain, not guessed.
+3. Exact MIRA V7 codec TRAIN split targets; no cross-family leakage or unseen access.
+4. Frozen MIRA codec **before** AXIS SkinCode teacher targets.
+5. AXIS V7 frozen TRAIN/internal validation then sealed one-time UNSEEN scope.
+6. Free-running **behavioral** tests: reachable handle IK, hand/weapon attachment, contact consistency, joint-limit compliance, deformation distortion, sparse influence, presentation-agnostic under motion.
+7. Knight M+C AA regression independent of unseen selection. No product certification based on a single sample.
+
+No V7 training or ProductRevision promotion is authorized by this research branch.
+
+## Milestones (large increments, no model-size theater)
+
+**A — engineering research candidate (this PR):** higher-capacity coupled Rig/Skin model, improved V7 baseline codec, typed Mechanics hit interaction, CI, exact upstream code references, versioned corpus gate.
+
+**B — architecture science:** benchmark new local-attention MIRA vs initial pooling baseline, then evaluate deeper conditional decoder/encoder parity against upstream; quantify active-support sampling on nonhumanoid corpus, gradient preservation, smoothness and reconstruction at 32k vs 64k, fixed budget.
+
+**C — mechanics semantics:** local DOF/limits, targets/attachments orientation, multi-constraint solves, influence-to-control ambiguity and abstention, spatial interaction tracking; no graphics authority creep.
+
+**D — data/model training:** qualified Corpus370 train/unseen split, frozen codec, coupled AXIS, checkpoint selection only on TRAIN-internal validation, independent unseen behavior court.
+
+**E — real-time product:** C++ cached solver/deform path, mouse interaction latency/p95 metrics, Graphics consuming Mechanics state, independent source fidelity and dynamic visual proofs.
+
+## Research falsification rules
+
+- Strong SkinCode MAE but bad contact, fold or vertex distortion is **FAIL** for playable puppet.
+- A legal skeleton with no usable declared handle is **FAIL** for interactive suitability.
+- One Knight oracle control-space parity is regression only, never proof of learned rigging.
+- A Graphics fidelity problem belongs to Graphics and its evidence binding, not to an AXIS graphics head.
+- Any missing ModelRelease, absent exact codec hash or unsealed subject family is fail-closed.
+- Bigger architecture is not itself a gain; model capacity must be backed by training data, sampling, pretraining or demonstrable learning curves.
+