Creation protocol · SessionGenerated

Brief

A live session answers JSON lines: one object a line in, with an op and an optional id; one line out, {"id", "ok": …} or {"id", "error": {…}}. entelechy serve <scene.esn> serves it on stdin/stdout, --listen <host:port> also over TCP and WebSocket; the Player serves the same with --serve. Concepts in Manual · Agent protocol.

Methods

op	Properties	Brief
compose	`text`?, `edits`?, `expect`?, `path`?, `documents`?	Changes the scene: rewrites its document on disk (`document` and `status` name it), or with `path` or `documents` the scene’s other documents too, once the texts are checked; answered once the scene stands. A refused text writes nothing and is an error: why, at `line` and `column`, the document’s `version`, and for `edits` the `text` they made, which `line` counts in.
document	`version`?, `path`?	The scene document’s text, or another document of the scene’s.
evaluate	`nodes`?, `settle`?, `measure`?, `clock`?, `time`?, `rate`? …	Runs one frame.
graph	—	The running scene’s structure.
help	`name`?	Entelechy’s syntax and API, layer by layer: all of it, or one name in full.
history	`since`?	What changed the world, and what was refused.
kernel	`kernel`?, `generation`?	One Kernel’s manifest and source.
kernels	—	Every published Kernel, with its generation.
param	`name`, `value`	Sets a parameter the scene declares.
pause	`paused`?, `step`?	Holds a window’s scene time still, lets it run, or steps it a frame (F8, F9 and F7 in the window).
pin	`node`	Keeps a node materialized so `read` can see it.
prepare	`source`	Compiles a Kernel and says what is wrong with it; publishes nothing.
publish	`source`, `expect`?	Compiles, validates and prepares a Kernel, then swaps it in whole; answered once it stands. The running world changes, not a file: the document it came from is left as it is.
quit	—	Ends the connection, or on standard input the process.
read	`output`?, `node`?, `port`?, `format`?, `from`?, `count`?	Reads an output or a node’s port.
reset	`node`?, `port`?	Forgets committed state; `<~` readers start from their initial sources.
restore	`snapshot`?, `from`?, `laws`, `structure`?, `time`?, `rate`? …	Puts a snapshot’s world back, after a trial frame that commits nothing: the state is the snapshot’s, which the next frame reads; until then `read` shows the trial frame’s outputs.
retire	`kernel`?	Removes a published Kernel.
snapshot	`to`?	The whole world: its Kernels, its scene and every committed state.
status	—	The session at a glance.
sync	—	Reads every changed document again.
trace	`node`, `at`?, `element`?, `time`?, `rate`?, `queued`? …	Runs one element of a node’s Kernel and shows every step of it; with no context fields, under the last frame’s context.
unpin	`node`	Lets fusion have a pinned node back.
write	`node`, `port`?, `data`, `format`?	Replaces a node’s committed state.

Signals (events)

What the session observed while synchronizing with the files, as {"kind": …} objects in the events of answers such as compose, sync and param.

kind	Fields	Description
`preparing`	`{ path: PathBuf, id: KernelId }`	A changed Kernel compiled and is being prepared; the running version stays until a later sync publishes the replacement.
`published`	`{ path: PathBuf, id: KernelId, generation: Generation }`	A Kernel was compiled and published.
`rejected`	`{ path: PathBuf, error: Diagnostic }`	A changed Kernel was refused; the previous version stays.
`retired`	`{ path: PathBuf, id: KernelId }`	A Kernel disappeared from its document.
`scene_loaded`	—	The scene document was re-read and its graph rebuilt.
`text`	`{ name: String, chars: usize }`	An input’s text was written into the Host as rows of character codes.
`loaded`	`{ name: String, path: PathBuf, detail: String }`	An input’s file was read into the Host.
`scene_rejected`	`(Diagnostic)`	The changed scene document was refused; the previous graph stays.
`absent`	`{ name: String, path: PathBuf }`	An input’s file is absent; the input reads its fallback.
`wrote`	`{ output: String, path: PathBuf, bytes: usize }`	An output was written to its file after a committed evaluation.
`removed`	`{ output: String, path: PathBuf }`	A file was removed by an output’s operations.
`renamed`	`{ output: String, from: PathBuf, to: PathBuf }`	A file was renamed by an output’s operations.
`write_refused`	`{ output: String, path: PathBuf, why: String }`	An output’s write was refused; said once until the reason changes or a write succeeds.
`routed`	`{ node: String, backend: &'static str, why: String }`	A node runs off the session’s main backend, and why. Said once per placement change.
`large`	`{ path: PathBuf, id: KernelId, why: String }`	A Kernel just published is large (`large`): what it carries through its branches, the structs and the functions that carry most. Said for each version published so.
`unrun`	`{ node: String, why: String }`	A node with no `domain` whose Kernel compares its element with its first input’s count, so the elements past that count, which the test is for, are never run ([`check::defaulted_domain`]). Said once when the scene loads, and again when it changes.
`brought_unchanged`	`{ output: String, path: PathBuf, bytes: usize, frames: u32 }`	A large output written to a file was brought to the Host as a new Field on each of `frames` evaluations in a row and found each time to be the file as it stands: the node it reads runs every time and makes the same, and each time costs the Field fetched, encoded and hashed. Said once, until the output is written or left as it was.
`idle`	`{ path: PathBuf, ids: Vec<KernelId> }`	Kernels a document of the scene publishes and no node uses, each compiled and prepared all the same. Said when the scene loads, and again when they change.

Envelope parts

Name	Within	Description
`column`	error	Where on that line, from 1.
`error`	answer	Why the request was refused, and what acts on it as data; the world is as it was.
`expected`	error	The type that field is.
`field`	error	The field at fault.
`fields`	error	The fields the operation takes.
`fix`	error	The change that mends the fault, when one does: an item of `compose`’s `documents` that takes its document’s place, handed back as it is; `path` with `text`, the refused change’s own document with a `use` item added, or with `edits` adding it to the document on disk. A `rejected` event carries it too.
`frame`	error	The frame a run failed at, counted from its first.
`id`	request	Anything; the answer carries it back as it was sent, to pair them.
`id`	answer	The request’s `id`, or null when it sent none or was not JSON.
`line`	error	Where the fault is, from 1: in the text the request carried, or in `path`.
`message`	error	Why, one or more sentences for a person or an agent to read.
`migration`	error	The Kernel that failed to migrate that state.
`node`	error	The node an evaluation failed at.
`ok`	answer	What the operation answered, as its entry in the protocol section says.
`op`	request	The operation: one of the protocol section’s, each with its own fields.
`operations`	error	Every operation, for an unknown one.
`path`	error	The scene document a refused compose would have written, or the document a failed element’s operation is written in.
`port`	error	The state port whose migration failed.
`similar`	error	The names nearest an unknown one.
`text`	error	The document an `edits` compose made, which `line` counts in.
`version`	error	The scene document’s version as it stands, for a compose refused.
`written`	error	Whether a compose wrote its document: false when refused.

Doors

Name	Opened by	Description
`socket`	`entelechy serve <scene.esn> --listen <host:port>`	The same lines over each TCP connection to the address; `quit` ends the connection.
`stdin`	`entelechy serve <scene.esn>`	Request lines on standard input, answer lines on standard output; `quit` ends the process.
`websocket`	`entelechy serve <scene.esn> --listen <host:port>`	The same lines as WebSocket text messages to the same address, one request a message.