feat: Phase 1 metagraph integration — per-fiber stateRoot + metagraphStateRoot via MPT

[ottobot-ai]

Summary

Phase 1 of the Constellation metagraph integration (spec: PR #107). Adds cryptographic state commitment infrastructure enabling Merkle inclusion proofs for individual fiber states.

Trello Card

Analysis: Validate Constellation metagraph integration approach (6996301a)

What Changed

Schema (backward-compatible, all new fields are Option[_] = None)

StateMachineFiberRecord (Records.scala)

• Add stateRoot: Option[Hash] = None
• Computed via MerklePatriciaProducer.stateless from top-level stateData fields
• Key: UTF-8 hex encoding of field name; Value: JSON-encoded field value

CalculatedState (CalculatedState.scala)

• Add metagraphStateRoot: Option[Hash] = None
• Computed per snapshot as MPT root over {fiberId → fiberStateRoot} pairs

FiberCombiner

• computeStateRoot(stateData): builds in-round MPT from MapValue fields
• createStateMachineFiber: computes initial stateRoot from initialData
• handleCommittedOutcome: recomputes stateRoot for all updated fibers

ML0Service

• computeMetagraphStateRoot(state): MPT of all active fiber stateRoots
• combine: calls computeMetagraphStateRoot after combiner.foldLeft
• hashCalculatedState: returns metagraphStateRoot when present, falls back to state.computeDigest

Tests

[info] xyz.kd5ujc.shared_data.MetagraphIntegrationSuite
[info] + StateMachineFiberRecord should have stateRoot field
[info] + StateMachineFiberRecord stateRoot should be optional and default to None
[info] + StateMachineFiberRecord stateRoot should accept Hash values
[info] + CalculatedState should have metagraphStateRoot field
[info] + CalculatedState metagraphStateRoot should be optional and default to None
[info] + CalculatedState metagraphStateRoot should accept Hash values
[info] + StateMachineFiberRecord stateRoot should survive copy operations
[info] + CalculatedState should preserve metagraphStateRoot when adding fibers
[info] + CalculatedState genesis should have no fibers and no metagraphStateRoot
[info] + metagraphStateRoot is None by default — falls back to default hashing
[info] + metagraphStateRoot Some(_) is returned directly as the canonical hash
[info] + Two states with same fibers but different metagraphStateRoot are distinguishable
[info] + StateMachineFiberRecord with stateRoot supports proof generation precondition
[info] + CalculatedState with metagraphStateRoot supports state proof endpoint precondition
[info] + Non-existent fiber returns None from stateMachines lookup
[info] Passed: Total 15, Failed 0, Errors 0, Passed 15
[info] Passed: Total 252, Failed 0, Errors 0, Passed 252

What's NOT in this PR (Phase 1B)

• GET /state-proof/:fiberId HTTP endpoint — tracked as follow-up
• Persistent MPT storage (Phase 2 — MerklePatriciaProducer.levelDb)

Implementation Notes

• Uses MerklePatriciaProducer.stateless[F] (no persistence, rebuilt each round) — appropriate for Phase 1
• computeStateRoot returns None for empty MapValue stateData (nothing to hash)
• computeMetagraphStateRoot returns None when no fibers have stateRoots yet
• All existing 252 tests pass — no regression