Research-Stack/6-Documentation/docs/specs/TINY_IP_CONTIKI_SURFACE_SPEC.md

Tiny IP Surface Spec

Version: 0.1
Status: Draft
Scope: Contiki-inspired shell concepts for embedded GCL/Omnitoken nodes
Reference implementation: infra/embedded_surface/tinyip/tinyip_emulator.py

---

Thesis

The embedded surface needs a shell layer that is small enough to reason about, test, and eventually port into tiny carriers.

We do not need to clone Contiki, and Omnitoken must not become UDP. We want the concepts that made Contiki useful on constrained systems:

1. Cooperative event loop.
2. Fixed packet buffers.
3. Timers instead of blocking calls.
4. Small datagram-like shell packets.
5. Explicit neighbor and route tables.
6. Application-level acknowledgments where reliability matters.
7. Admission before payload expansion.

The shell surface is not the root of trust. It is only the local appearance that moves an admitted Omnitoken scalar between observer charts.

---

Layer Shape

GCL operation
  -> Omnitoken scalar/LUT entry
  -> local shell packet
  -> lossy link / serial / tunnel / hosted process

Tiny nodes may collapse the lower layers:

Omnitoken scalar -> tiny packet buffer -> shell send

The shell may be named udp, onion, serial, websocket, ipv923u, or any future substrate label. The shell name does not decide meaning.

---

Core Concepts

Cooperative Processes

Each node owns small cooperative processes. A process runs only when the event loop dispatches an event to it. It must return quickly.

Required process classes:

Process	Purpose
net_rx	Admit inbound packet headers
net_tx	Drain outbound packets
timer	Fire retransmit and maintenance events
shell_app	Handle tiny shell messages
lut_bridge	Project admitted scalar to Omnitoken/GCL

No process may block waiting for network I/O.

Packet Buffer

Each node has a fixed number of packet buffers. If all buffers are full, the node refuses or drops work before expansion.

Recommended tiny defaults:

MTU                  96 bytes
RX buffers            4
TX buffers            4
neighbor entries      8
route entries         8

Tiny IP Header

The emulator uses symbolic fields, but the portable shape is:

src       u16
dst       u16
proto     u8
seq       u16
ttl       u8
flags     u8
len       u8/u16
payload   bytes

src and dst are short atlas-local addresses, not public Internet addresses.

OMNIsurface LUT Payload

The internal payload is an ultracompressed LUT selector, not a protocol-specific message:

u8 domain
u8 scalar

The 1D scalar is scale-invariant: different shells may encode it with different padding, framing, or transport metadata, but the admitted (domain, scalar) pair maps to the same LUT entry.

Example:

0x0D 0x01 -> recover / recovery_subset / BOOT_OK

Reliability is not assumed at the shell layer. If a GCL transition needs proof of receipt, the app sends an ACK scalar.

Required app messages:

Domain	Scalar	Meaning
0x0D	0x01	Recovery pulse
0x0A	0x01	Acknowledge a sequence
0x01	0x01	Health pulse
0x0F	0x01	Lawful refusal

---

Admission Rules

Before accepting a packet as state:

1. Header must parse.
2. ttl must be greater than zero.
3. Payload length must be within MTU.
4. Duplicate (src, seq) must be ignored.
5. (domain, scalar) must exist in the finite LUT.
6. GCL admission must accept the expanded operation.

The link may be lossy, duplicated, reordered, or stale. None of those conditions make a packet state by themselves.

---

Carrier Classes

Class	Meaning
tinyip_loopback	In-process emulator
tinyip_serial	Serial or PTY link
tinyip_tunnel	Tailscale/TCP/WebSocket shell
tinyip_kvm	KVM guest surface via I/O or MMIO
tinyip_qemu	QEMU/TCG guest surface
tinyip_ipv923u	Future shell label; internal scalar unchanged

Every class shares the same packet/admission behavior.

---

Success Criteria

A tiny IP surface is healthy if:

1. All nodes can emit a recovery scalar.
2. The controller receives one valid pulse per node.
3. Duplicate pulses are ignored.
4. Lost pulses are retransmitted by timer.
5. Oversized payloads are refused before expansion.
6. Quorum can be reached under lossy links.

---

Extensions

Geometry Emergency Boot Witness

The Tiny IP surface is extended by the Geometry Emergency Boot Witness specification for hardware-rooted emergency recovery.

Extension document: GEOMETRY_EMERGENCY_BOOT_WITNESS_2026-04-08.md

Key extensions:

Extension	Domain	Scalar	Purpose
Emergency boot commands	0x0D	0x01-0x05, 0xFF	Geometric seed-based recovery
geometry_scan process	-	-	Physical capacitor geometry extraction
seed_assembly process	-	-	Multi-dimensional geometry → seed collapse
tsm_reconstruct process	-	-	TSM-VDP state reconstruction from seed
emergency_shell process	-	-	Emergency command interface
power_monitor process	-	-	AEM20940-based power failure detection

The emergency boot system provides a minimal GEM/Contiki-like interface for device recovery when power failure occurs, using graphene supercapacitor geometric arrangement as the root of trust.

See GEOMETRY_EMERGENCY_BOOT_WITNESS_2026-04-08.md for complete specification of:

• Multi-dimensional geometric encoding (spatial, capacitance, topology, dimensions)
• Power failure detection (AEM20940 + TSM Safety Interlock + Galvanic Bridge)
• Seed extraction and TSM-VDP recovery algorithm
• Emergency boot command interface
• Hardware integration (Lattice iCE40UP5K-SG48, Rogers 4350B substrate)