feat: add token behavior sealed trait, builder, and proto (16-type TDEG matrix)

[ottobot-ai]

Summary

Implements the complete 16-type token behavior system using a 4-boolean TDEG matrix in Scala, achieving cross-language equivalence with the TypeScript SDK (PR #45).

Trello Card

🎲 SDK: 16-type token behavior matrix implementation

Deliverables

1. TokenBehavior — Sealed trait with 16 case objects (TDEG model) in modules/models/
2. TokenBehaviorBuilder.toStateMachineDefinition(behavior) — Factory producing StateMachineDefinition
3. TokenBehavior.isOperationAllowed(behavior, op): Boolean — Operation legality API
4. TokenOperation — Enumeratum enum for 8 operation types
5. token.proto — New domain proto under ottochain/v1/ with TokenBehaviorType + TokenOperationType enums
6. TokenBehaviorSuite — 58 TDD tests, all passing

Key Design Decisions

Decision	Choice	Rationale
Module	modules/models/	Same as StateMachineDefinition; pure data, no IO
Proto	New token.proto	Establishes domain-proto convention (future: identity, market, governance)
Expiry guard	sequenceNumber	Fixes TypeScript $ordinal latent bug (defaults to 0 in JLVM)

4-bit TDEG Encoding

Bit 3 (8): T = Transferable
Bit 2 (4): D = Divisible
Bit 1 (2): E = Expirable
Bit 0 (1): G = Governable

TokenBehavior.value = T×8 + D×4 + E×2 + G×1

16 named presets: SOULBOUND_RECEIPT(0) → GOVERNED_EXPIRABLE_FUNGIBLE(15)

Test Coverage (58 tests, all passing)

• Group 1: Predicates (6 tests) — isTransferable, isDivisible, fromFlags, etc.
• Group 2: Structure for all 16 types (16 tests) — valid StateMachineDefinition with correct states
• Group 3: Transition presence by flag (12 tests) — T/D/E/G flag → correct transitions
• Group 4: Wire format correctness (6 tests) — StateId wrappers, metadata fields, guards
• Group 5: Operation legality (8 tests) — all operations vs all behaviors
• Group 6: Named preset factories (5 tests) — nft, fungibleToken, stablecoin, license, soulboundBadge
• Group 7: Structural equivalence (5 tests) — unique values/names, round-trip, EXPIRED state presence

References

• TypeScript reference: ottobot-ai/ottochain-sdk PR fix: relax L1 sequence validation to >= for batching support #45 (84 tests)
• Spec: docs: Token Behavior Matrix — Scala TDD-ready specification #114 (merged as docs)
• JLVM context variables: dfa-json-logic-patterns.md §11

---

Implemented by @work (OttoBot) | 2026-02-26