Schemas

Capability

Field	Type	Req	Description
name	string	yes	Capability name.
summary	string	yes	What it enables for downstream apps.
surfaces	string[]	yes	Endpoints / frames that expose it.

ChunkFlow

Field	Type	Req	Description
name	string	yes	Flow name, e.g. 'upload' or 'read'.
summary	string	yes	What the flow does.
sequence	string[]	yes	Ordered wire steps for the flow.

ConfigField

One config field reflected from an Interface.Config class.

Field	Type	Req	Description
name	string	yes	Config field name.
type	string	yes	Python type annotation as string.
default	any	yes	Default value, or null if required.
required	boolean	yes	True when the field has no default.

ConfigFilter

One operator clause over a config json path (range/equality/membership).

Field	Type	Req	Description
path	string	yes	Dotted path into the config layer, e.g. 'a.b'.
op	ConfigOp	no
value	any	no

ConfigLayer

Enum: default, version, update, resolved

ConfigMatch

Field	Type	Req	Description
layer	ConfigLayer	no
filters	ConfigFilter[]	no

ConfigOp

Enum: eq, ne, lt, lte, gt, gte, in, contains

CreateInterfaceRequest

Create (materialize) an Interface, optionally with a client-supplied id.

Field	Type	Req	Description
target	string	yes	Module path to instantiate.
version	array	no	Passed to Interface.make().
uuid	any	no	Client-supplied id (e.g. content hash). Idempotent: creating again with the same id returns the existing instance unchanged.
label	any	no	Optional mutable label to set on creation.
meta	object	no

DataStatusResponse

Whether a run's stored data is readable now (local / remote / evicted).

Field	Type	Req	Description
uuid	string	yes
available	boolean	yes	True when the working directory is mounted.
mounted	boolean	yes
storage_uri	any	no
local_uri	any	no
bytes_missing	boolean	no

DispatchInterface

One interface to add to an Execution.

Carries the ordered with-context it runs under.

Field	Type	Req	Description
target	string	yes	Interface module path.
version	array	no
context	InterfaceRef[]	no	Ordered with-contexts the interface is created under; any interface (Scope is one kind). Entered in order, exited in reverse (LIFO), exactly like the CLI's element chain. Order is significant.

DispatchRequest

Create/reuse an Execution and dispatch interfaces into it.

Mirrors with Project(request): Execution.add([with ctx: ...]).dispatch() Here, Project is the request's ambient project (?project=); the Execution is the container; each interface carries its own ordered context chain.

Field	Type	Req	Description
execution	any	no	The Execution container interface; omit for a default Execution().
execution_ref	any	no	Reuse/resume a specific Execution instance (its uuid) instead of creating one.
interfaces	DispatchInterface[]	no	Interfaces to add to the Execution, each with its with-context stack.

ExecutionInfo

An Execution run-record, the only kind that carries lifecycle status.

Field	Type	Req	Description
uuid	string	yes	Unique execution identifier.
module	any	no	Project-relative module path.
config	object	yes	Resolved execution configuration.
version	array	no	Compact version list.
cli	string	no	Reproduction command (module + version).
seed	integer	yes	Random seed for this execution.
nickname	string	yes	Human-readable execution nickname.
resources	any	no	Requested compute resources.
parent_uuid	string	yes	Uuid of the parent Interface for this run.
is_started	boolean	yes	True when started_at has been written.
is_active	boolean	yes	True when heartbeat is recent and not finished.
is_finished	boolean	yes	True when finished_at has been written.
is_incomplete	boolean	yes	True when started but not live.
is_live	boolean	no	True when the heartbeat is recent.
is_resumed	boolean	no	True when the run was resumed at least once.
started_at	any	no	ISO-8601 start timestamp.
resumed_at	any	no	ISO-8601 last resume timestamp.
finished_at	any	no	ISO-8601 finish timestamp.
heartbeat_at	any	no	ISO-8601 last heartbeat timestamp.
created_at	string	yes	ISO-8601 creation timestamp.
created_by	any	no	User attributed as creator when first materialized.
label	any	no	Optional mutable, human-facing label.

FindRequest

Field	Type	Req	Description
module	any	no
kind	any	no
created_by	any	no
label	any	no
parent_id	any	no
identity_key	any	no
predicate_key	any	no
predicate	any	no
config	any	no
sort	SortSpec[]	no
include_hidden	boolean	no
include_bytes_missing	boolean	no
record_id_suffix	any	no
limit	integer	no
offset	integer	no

FrameField

Field	Type	Req	Description
name	string	yes	Field name on the JSON frame.
type	string	yes	JSON type, e.g. string, object, bool.
required	boolean	no	Whether the field is required.
description	string	yes	What the field means.

GraphEdge

A typed, directed edge referencing nodes by uuid.

Field	Type	Req	Description
source	string	yes
target	string	yes
rel	string	yes	derivation | context | uses | runs | manifest | …

GraphNode

One node in a provenance graph.

attributes is the per-kind open facet (== Interface.on_provenance_attributes()): an Execution carries seed/timing, a Manifest its entries, a recipe interface its config layers + context.

Field	Type	Req	Description
uuid	string	yes
kind	string	yes
module	any	no
version	array	no
label	any	no
attributes	object	no

HTTPValidationError

Field	Type	Req	Description
detail	ValidationError[]	no

HealthResponse

Server health summary.

Field	Type	Req	Description
status	string	yes	Health status literal.
version	string	yes	Installed machinable version.
project	any	no	Default (launch) project directory, if any.
projects	string[]	no	Project directories the server currently holds state for.
executions_active	integer	yes	Active Execution records in the default project.
uptime_seconds	number	yes	Seconds since the API server started.

InterfaceCallRequest

One-shot synchronous Interface method call over REST.

Field	Type	Req	Description
target	string	yes	Module path or existing interface uuid.
version	array	no	Passed to Interface.make() when target is a module path.
meta	object	no	Optional metadata stored with a newly created interface.
method	string	yes	Public method name to invoke.
args	array	no	Positional arguments.
kwargs	object	no	Keyword arguments.

InterfaceHook

Field	Type	Req	Description
name	string	yes	Method/attribute the project interface defines.
signature	string	yes	Python signature.
description	string	yes	When machinable invokes it and contract.

InterfaceInfo

A materialized Interface entry (pure data node, no lifecycle status).

Field	Type	Req	Description
uuid	string	yes	Unique interface identifier.
module	any	no	Project-relative module path.
kind	string	yes	Interface kind, e.g. Interface or Project.
config	object	yes	Resolved configuration for this interface.
predicate	object	yes	Predicate dict used for index lookup.
version	array	no	Compact version list (~versions + override dicts).
cli	string	no	Reproduction command: module + compact version as a CLI string.
cached	boolean	yes	True when computation for this interface has finished.
created_at	string	yes	ISO-8601 creation timestamp recorded at materialization.
created_by	any	no	User attributed as creator when first materialized.
label	any	no	Optional mutable, human-facing label (config stays immutable).
meta	object	no	Client metadata supplied on WS connect.
execution_count	integer	yes	Number of Execution children in the index.
latest_execution_uuid	any	no	Uuid of the most recent Execution child, if any.

InterfaceRef

A uniform reference to any interface.

target (module path) + compact version.

Field	Type	Req	Description
target	string	yes	Module path (or uuid).
version	array	no	Compact version (~versions + override dicts).

LifecycleRequest

Content-addressed lifecycle lookup for a compact version (no run/materialize).

Field	Type	Req	Description
target	string	yes	Module path to look up by content.
version	array	no	Compact version (~versions + overrides).
context	InterfaceRef[]	no	Ordered with-contexts the config is created under (Scope or any interface). Entered before lookup so a scoped config resolves to its scoped identity and must match what it was dispatched under.

LifecycleResponse

The compute lifecycle state for a config, derived purely from the index.

Field	Type	Req	Description
target	string	yes	Module path that was looked up.
module	any	no	Resolved module path.
uuid	any	no	Materialized interface id, or null when never created (draft).
status	LifecycleStatus	yes	draft | running | cached | failed.
cached	boolean	no	True when a finished result is available to read.
execution_uuid	any	no	Latest Execution run id, if any.

LifecycleStatus

Where a content-addressed config sits in its compute lifecycle.

Enum: draft, running, cached, failed

ModuleSchema

Config schema for one discoverable Interface module.

Field	Type	Req	Description
module	string	yes	Project-relative dotted module path.
kind	string	yes	Interface kind for the discovered class.
doc	any	no	Class docstring, if present.
config_fields	ConfigField[]	yes	Reflected Config fields for form rendering.
versions	string[]	yes	Named version methods exposed by the class.
version_methods	VersionMethod[]	no	Version methods with signature + docstring (the ~version vocab).
widget	any	no	Widget frontend descriptor when the class ships one.

ProjectIndex

Index of discoverable Interface modules.

Field	Type	Req	Description
project	string	yes	Absolute project directory path.
modules	ProjectModule[]	yes	Discoverable Interface subclasses.

ProjectModule

Discoverable Interface module in the connected project.

Field	Type	Req	Description
module	string	yes	Project-relative dotted module path.
kind	string	yes	Interface kind for the discovered class.
doc	any	no	Class docstring, if present.
widget	boolean	no	True when the class ships a widget frontend.

ProtocolDoc

The non-OpenAPI half of the contract: WebSocket protocol + hooks.

Field	Type	Req	Description
protocol_version	string	yes	Wire protocol version.
transport	object	yes	Transport notes (control plane vs data plane).
headers	FrameField[]	yes	Cross-cutting request headers (project/user/interpreter).
ws_endpoints	object	yes	WebSocket routes and what they connect to.
ws_frames	WSFrame[]	yes	Every WebSocket frame type.
chunk_flows	ChunkFlow[]	yes	Binary upload and read sequences.
interface_hooks	InterfaceHook[]	yes	Hooks a project Interface implements for the data plane.
capabilities	Capability[]	yes	High-level capability map for downstream consumers.

ProvenanceGraph

Normalized node-link DAG: how a result came to be.

Nodes appear once; shared nodes (a Manifest used by many runs) are referenced by many edges, never duplicated. Every edge's source/target is guaranteed present in nodes.

Field	Type	Req	Description
root	string	yes
nodes	GraphNode[]	no
links	GraphEdge[]	no
truncated	boolean	no	True when a node cap bounded the walk.

RelatedItem

Field	Type	Req	Description
uuid	string	yes
module	any	no
kind	string	yes
version	array	no
label	any	no

RelatedResponse

Field	Type	Req	Description
uuid	string	yes
related	RelatedItem[]	yes

RemotesResponse

Shareable interfaces the project resolves by URL (slurm, globus, …).

Field	Type	Req	Description
remotes	object	no	module path → source URL (or [source, *dependencies]).

ResolveRequest

Dry-run a compact version: expand it to resolved config without running.

Field	Type	Req	Description
target	string	yes	Module path to instantiate.
version	array	no	Compact version (~versions + overrides).

ResolveResponse

Field	Type	Req	Description
module	any	no	Module path.
version	array	no	The compact version as given.
config	object	yes	Resolved configuration.
predicate	object	no	Computed predicate.
cli	string	yes	Reproduction command (module + version).

SearchItem

A lightweight search hit over the interface index.

Field	Type	Req	Description
id	string	yes	Interface uuid.
module	any	no	Module path.
kind	string	yes	Interface kind.
config	object	no	Resolved configuration.
created_at_ns	integer	yes	Creation timestamp (ns).
created_by	any	no	Creator.
label	any	no	Mutable label.

SearchResponse

Field	Type	Req	Description
items	SearchItem[]	yes
total	integer	yes	Total matches ignoring limit/offset.

SetLabelRequest

Set/replace an interface's mutable label (FCFS / last-write-wins).

Field	Type	Req	Description
label	any	yes	New label value, or null to clear.

SortSpec

A single ORDER BY term, over an index column or a config json path.

Field	Type	Req	Description
by	string	no	Index column, or a config json path when config_layer is set.
config_layer	any	no	When set, by is a json path into this config layer.
direction	string	no	"asc" or "desc".

SourceFile

One source file under the project tree.

Field	Type	Req	Description
path	string	yes	Project-relative file path (forward slashes).
module	string	yes	Dotted module path the file imports as.
size	integer	yes	File size in bytes.
mtime_ns	integer	yes	Last-modified time (ns since epoch).

SourceFileContent

Field	Type	Req	Description
path	string	yes	Project-relative file path.
module	string	yes	Dotted module path the file imports as.
content	string	yes	Full file content.
etag	string	yes	MD5 of the content (also returned as ETag header).
size	integer	yes	Content size in bytes.

SourceListResponse

Field	Type	Req	Description
base_dir	string	yes	Absolute base directory the API is confined to.
files	SourceFile[]	yes

SourceMoveRequest

Atomic rename/move within the base directory (e.g. rename an interface).

Field	Type	Req	Description
from	string	yes	Existing source path.
to	string	yes	Destination source path (must not exist).

SourceWriteRequest

Field	Type	Req	Description
content	string	yes	Full new file content (overwrite or create).

SourceWriteResponse

Field	Type	Req	Description
path	string	yes	Project-relative file path.
module	string	yes	Dotted module path the file imports as.
etag	string	yes	MD5 of the written content.
created	boolean	yes	True when the file did not previously exist.

ValidationError

Field	Type	Req	Description
loc	array	yes
msg	string	yes
type	string	yes
input	any	no
ctx	object	no

VersionMethod

A version_<name> method, invoked compactly as ~name(args).

Field	Type	Req	Description
name	string	yes	Version name; use as ~name in a version list.
signature	string	yes	Call signature, e.g. '(path)' or '(*, mode, backbone)'.
doc	any	no	Docstring, if present.

WSFrame

Field	Type	Req	Description
type	string	yes	Value of the frame's type field.
direction	string	yes	"client→server", "server→client", or "either".
summary	string	yes	One-line purpose of the frame.
fields	FrameField[]	no	Frame-specific fields beyond type/id.

WidgetInfo

Frontend descriptor for an interface that ships a widget.

Field	Type	Req	Description
meta	object	no	Opaque widget_meta; machinable never parses it.
esm_url	string	yes	URL serving the widget ES module.
css_url	any	no	URL serving the widget CSS, or null.