Crate somatize_core 

The soma core: the graph structure, the contracts for what gets executed, the shape of an execution, and the engine that walks it.

No #[pyclass] here. The moment a core type carries one, it can no longer be used without a Python interpreter loaded, and that does not come undone.

The pieces and their roles, which are easy to confuse:

piece	role
Graph	the structure: which nodes exist and how they connect. Pure data
Catalog	the store: which implementation belongs to each node
Placement	where each node runs. Pure data, and separate from the plan
Memory	what is remembered of each node: what it is, whether it is frozen, whether its output is kept
Device	the place inside a machine: cpu, cuda:0, meta
Host	the place that is another machine or process, by name
Node	the contract for what a node executes
Transport	who carries a slice of plan to another host
Keeper	who hashes a recipe and keeps what it names
Watcher	who is told what happened, as it happens
Fact	one thing that happened, in the engine’s vocabulary
Plan	the decided shape of an execution
Step, Destination	the two ways of walking one: what it does, and where
compile	from the structure to the shape
distribute	and from the placement, which slices travel together
Executor	the engine
Wire	declaring a graph as an expression: a >> (b | c) >> d

One file per type, with its inherent impls and the errors its operations produce. See CLAUDE.md.

Structs

Cargo

What a plan needs beyond itself in order to run elsewhere.

Catalog

A graph’s implementations, by node id.

CodecError

Why something could not be written down, or read back.

Ctx

What a node knows beyond its input, which travels separately. A type rather than an argument because it is the channel: adding to it is additive, and every node ever written has this signature.

Edge

A directed connection between two nodes.

Executor

Executes plans. A type and not a bare function because executing needs context: the store, the placement and the transports.

Graph

A directed acyclic graph of named nodes.

Host

The name of the process where a node runs.

KeeperError

Why something could not be kept, or found.

Kept

Something that was kept, on the way back: the value, and what was said beside it. The metadata comes back because the fingerprint of the code is not in the key — it is written next to the value and compared on a hit.

Key

What a node’s output is called, wherever it is kept. Text and not bytes because it is a name: it ends up in an index, a log line and an error.

Memory

What is remembered about each node. The ones not listed have nothing said about them, which is the same as nothing being kept.

NodeError

What a node can answer when it cannot advance.

NodeId

A node’s name inside a graph. Its own type so no other kind of id gets through.

Outcome

What came back from executing a plan elsewhere.

Packing

Whatever a Codec can write down, kept — by a Keeper that never finds out any of it was ever anything but bytes.

Placement

Where each node runs. The ones not listed run wherever they land.

Step

One step of a plan: a node, and where its input comes from.

TransportError

What a transport can answer when it cannot carry something.

Wire

A half-declared graph.

Enums

CompileError

Why it was not possible to decide how to walk the graph.

Destination

What decides where one part of a plan runs.

Device

The place where a node executes. It travels as text, through Display and FromStr: a variant number would break silently the day the enum grows in the middle.

DeviceError

Why that does not name a place to execute.

Fact

One thing the engine saw.

GraphError

An attempt to build a graph that cannot exist.

Keys

What a node’s output is called: one name, or one per item.

MemoryError

Why what this graph says to keep could not honestly be kept.

Plan

How a graph is walked.

RunError

Why the execution could not be finished. The structural things were ruled out in compile; these are the implementations’ failures.

Value

A datum crossing from one node to the next.

Constants

FINGERPRINT

Which version of the code produced it, written beside the value rather than mixed into the name.

INPUT

What the graph was fed, by the name its content has. Only a Keeper can hash a Value, and a key does not run backwards, so it is written now or never. Set on run and never on resume: a slice is not handed the graph’s input.

NODE

What the engine writes beside a value it keeps. Public because a store outlives the process that wrote to it and readers need these strings.

OURS

The words the engine writes itself, so a layer that refuses a stamp can ask which ones are taken.

Traits

Codec

Writes down what cannot leave a process, and reads it back.

Keeper

Hashes recipes and keeps what they name.

Node

Something a node knows how to do. Send + Sync because a Python Graph is a pyclass — which PyO3 requires to be Send — and it carries the catalog.

Transport

Knows how to execute a plan elsewhere.

Watcher

Told what happened, as it happens.

Functions

anything_written

Whether there is anything written down in there at all, at any depth. Asked before the walk, so the ordinary value costs one look.

as_written

What was written down in there, if that is what it is.

cacheable

Whether what this graph says to keep can honestly be kept. A free function for the same reason compile is one: it needs the graph and the table.

compile

Decides how this graph is walked. The catalog is only consulted to check that every node has an implementation: the shape does not depend on what each one is.

distribute

Wraps the slices that run on another host in Plan::Remote, grouping as much as it can and descending only where a slice is spread across places. Idempotent; a plan with no hosts comes out unchanged.

node

A lone node, named after its type: this is the last place that knows it, and what a node is called is half of the key its output is kept under.

packed_all

Every one of these packed, or the first that cannot be.

unpacked_all

And every one of these unpacked.

written_down

Something written down: what kind it was, and the bytes it became. The kind is named after the type or the format and never after the run — torch.Tensor, arrow.RecordBatch — since it is also how the far end knows who to ask to read it back.