Turn worker ABI
The turn worker ABI is the language-neutral contract between akterd and the code that runs an app’s actor handlers. An SDK in any language implements it to run actors on akterd. @akterjs/effect implements it as TurnWorker.
Sources of truth
| Source | Contents |
|---|---|
packages/effect/abi/akter.capnp | The Cap’n Proto schema of every frame and of the published contracts. |
packages/effect/abi/README.md | The specification: encoding, socket framing, handshake, turns, determinism, and versioning. |
packages/effect/abi/vectors | Golden vectors. Each .bin file holds canonical Cap’n Proto bytes, and the .json file beside it holds the same value in Cap’n Proto’s JSON format. |
Every frame uses the canonical Cap’n Proto encoding, so one value always has one byte string. A conforming codec decodes each .bin vector to its .json value and encodes that value back to identical bytes. sale.contracts.bin holds the published contracts of the sample Sale actor, and sale-tables.contracts.bin adds its tables.
The worker connects to the Unix stream socket that AKTER_WORKER_SOCKET names. Each frame on the socket uses Cap’n Proto stream framing with exactly one segment.
AKTER_STATEMENT_DETAIL sets what a caller sees when a handler’s SQL statement fails. With shown, the default, the caller gets the statement’s own message. With logged, the host logs that message under the command’s id and the caller gets a generic message. Any other value stops the worker before it connects.
Frames
A Frame carries exactly one message.
| Message | Sender | Purpose |
|---|---|---|
workerHello | Worker | Lists the ABI versions the worker speaks, names its SDK, and carries the app’s published contracts. |
hostWelcome | Host | Picks one ABI version and states the largest frame the host accepts. |
hostRefusal | Host | Refuses the worker with noCommonVersion or manifestRejected. |
turnInvocation | Host | Starts one turn of one actor. |
hostCall | Worker | Asks the host to run SQL, a search, or a file, channel, or transaction call, inside the turn’s transaction. |
hostReply | Host | Answers one host call, or answers unsupported. |
turnOutcome | Worker | Ends the turn with a success, a typed failure, or a defect. |
turnCancel | Host | Abandons a turn, a turn batch, or a job run with the reason deadline, shutdown, or aborted. The worker sends nothing more for it. |
turnBatch | Host | Starts the queued turns of one actor. The worker runs them one at a time, in order. |
outcomeBatch | Worker | Ends one or more turns of a batch, in the order of the batch. |
jobRun | Host | Runs or resumes a job body with its input, its journal so far, a clock, and a seed. |
jobCall | Worker | Journals an Activity result, runs a <Actor>.turn step, or sets a durable clock. |
jobReply | Host | Answers one job call. |
jobExit | Worker | Ends a job run with a success, a typed failure, or a defect, or suspends it until the journal grows. |
The conversation for one turn
- The worker sends
workerHello. The host answershostWelcomeorhostRefusal. - The host sends a
turnInvocation. It names the turn number, the actor address, the parent, and the stored state, orabsentbefore creation. - The invocation names the member to run:
initial, acommand, aquery, ajobResult, ajobStep, achildFault, orupgrade. - The invocation also carries the encoded input, the caller’s principal, the command ID, a hybrid logical clock, a 32-byte random seed, and any transaction it joins.
- The worker runs the handler. Each SQL statement becomes a
hostCallwith the turn number and a call number that starts at 0. - The host runs the statement inside the turn’s transaction and sends a
hostReplywith rows or a SQL failure. It answersfsandtransactioncalls withunsupported. It answerschannelcalls as Channels describes, andsearchcalls as Search describes. - The worker sends one
turnOutcomewith the same turn number.
Several turns run at once on one connection, with at most one turn per actor. A handler reads time only from the invocation’s clock and randomness only from its seed. The same invocation and the same replies give the same outcome bytes.
A successful outcome carries the next state, or unchanged, and the encoded output. It also lists the outbox messages, the timers to schedule or cancel, the jobs to start, and the job signals. The host commits the turn’s SQL writes and these effects together, or commits none of them.
A failed outcome carries a declared error as a TypedError with its tag and encoded value. A defect carries a message. After either one, the host rolls back the turn.
Turn batches
ABI 1.3 adds turn batches. The host sends them only when the negotiated minor version is 3 or higher.
- A
turnBatchholds the queued turns of one actor. The first turn carries the stored state, orabsent. Every later turn carries the statechained. - The worker runs a chained turn on the state that the previous turn ended with. After
unchanged, a failure, or a defect, that state is the previous turn’s starting state. - The worker returns every outcome of the batch in
outcomeBatchframes, in order. Before a turn’s firsthostCall, it sends the earlier outcomes that it has not sent. - The host runs each turn in its own savepoint and commits the batch once. It releases replies and other effects only after that commit.
The ABI specification lists every rule, and ADR 0032 records why.
Search calls
ABI 1.4 adds the search host call. The worker sends it only when the negotiated minor version is 4 or higher.
- A
searchcall names a table and one of its search indexes. It carries the query text, the query vector, the filters, and a limit. - The host ranks the rows inside the turn’s transaction, so a search sees the turn’s own writes. It answers with at most
limithits, best first. - Each hit holds the row, the fused score, and the row’s rank in the text ranking and in the vector ranking.
- The host answers a call that it cannot run with a failure reason. The worker then stops the turn with a
SearchRefusedErrordefect. PublishedContractslists each table’s search indexes, and each vector column’s dimensions and quantization.
The ABI specification lists every ranking rule, and ADR 0033 records why.
Child faults
A childFault invocation runs the parent’s onChildFault command after the host quarantines a child’s envelope. ABI 1.5 adds the member, attempts, and envelope fields to ChildFault. A host fills them only when the negotiated minor version is 5 or higher.
membernames the child’s command that faulted.attemptscounts the failed attempts before the host quarantined the envelope.envelopeidentifies the quarantined envelope, such astimer:<id>.
ADR 0034 records why.
State upgrades
ABI 1.6 adds the upgrade turn member. The host sends it only when the negotiated minor version is 6 or higher.
- An
upgradeturn carries the stored state as an earlier release wrote it. Its input isnull, its caller is the system principal, and its command ID isupgrade:<schemaVersion>. - The worker runs the actor’s
Akter.migrateState. It answersunchangedwhen the current states already decode the stored state. - It answers the upgraded state when
Akter.migrateStateupgrades it. The outcome carries no output and no other effects. - It answers a defect with the
StateUnreadableErrormessage when the state cannot upgrade. It also answers a defect when the state isabsent.
The ABI specification lists every rule, and ADR 0036 records why.
Values on the wire
- Encoded data. States, inputs, outputs, principals, and errors travel as
Datathat holds the JSON encoding of the contract schema. - SQL values. A
SqlValueisnull,integer,real,text, orblob, matching the SQLite storage classes. - Published contracts.
PublishedContractslists each actor with its key, parent, callers, states, initial state, commands, queries, jobs, final states, secrets, tables, dropped tables, timeouts, schedules, and HTTP bindings. The host checks the contracts inworkerHellobefore it sends a turn.
Jobs and tables
A job body runs on the worker, and akterd keeps its journal in the actor’s database. Each <Actor>.turn in a job body is a jobStep turn. The step’s state change, its SQL writes, and its journal record commit in one transaction. A resumed run replays the journal, so no journaled step or activity runs twice.
akterd creates and migrates each actor’s tables from the STRICT DDL in the published contracts. It refuses a manifest that drops a table or a column without declaring the drop. It also refuses a manifest that changes a column’s type, a column’s nullability, or a primary key, or that adds a notNull column to an existing table. The ABI specification lists every rule, and ADR 0029 records why.