Skip to content

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⁠

SourceContents
packages/effect/abi/akter.capnpThe Cap’n Proto schema of every frame and of the published contracts.
packages/effect/abi/README.mdThe specification: encoding, socket framing, handshake, turns, determinism, and versioning.
packages/effect/abi/vectorsGolden 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.

MessageSenderPurpose
workerHelloWorkerLists the ABI versions the worker speaks, names its SDK, and carries the app’s published contracts.
hostWelcomeHostPicks one ABI version and states the largest frame the host accepts.
hostRefusalHostRefuses the worker with noCommonVersion or manifestRejected.
turnInvocationHostStarts one turn of one actor.
hostCallWorkerAsks the host to run SQL, a search, or a file, channel, or transaction call, inside the turn’s transaction.
hostReplyHostAnswers one host call, or answers unsupported.
turnOutcomeWorkerEnds the turn with a success, a typed failure, or a defect.
turnCancelHostAbandons a turn, a turn batch, or a job run with the reason deadline, shutdown, or aborted. The worker sends nothing more for it.
turnBatchHostStarts the queued turns of one actor. The worker runs them one at a time, in order.
outcomeBatchWorkerEnds one or more turns of a batch, in the order of the batch.
jobRunHostRuns or resumes a job body with its input, its journal so far, a clock, and a seed.
jobCallWorkerJournals an Activity result, runs a <Actor>.turn step, or sets a durable clock.
jobReplyHostAnswers one job call.
jobExitWorkerEnds a job run with a success, a typed failure, or a defect, or suspends it until the journal grows.

The conversation for one turn⁠

  1. The worker sends workerHello. The host answers hostWelcome or hostRefusal.
  2. The host sends a turnInvocation. It names the turn number, the actor address, the parent, and the stored state, or absent before creation.
  3. The invocation names the member to run: initial, a command, a query, a jobResult, a jobStep, a childFault, or upgrade.
  4. 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.
  5. The worker runs the handler. Each SQL statement becomes a hostCall with the turn number and a call number that starts at 0.
  6. The host runs the statement inside the turn’s transaction and sends a hostReply with rows or a SQL failure. It answers fs and transaction calls with unsupported. It answers channel calls as Channels describes, and search calls as Search describes.
  7. The worker sends one turnOutcome with 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 turnBatch holds the queued turns of one actor. The first turn carries the stored state, or absent. Every later turn carries the state chained.
  • 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 outcomeBatch frames, in order. Before a turn’s first hostCall, 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 search call 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 limit hits, 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 SearchRefusedError defect.
  • PublishedContracts lists 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.

  • member names the child’s command that faulted.
  • attempts counts the failed attempts before the host quarantined the envelope.
  • envelope identifies the quarantined envelope, such as timer:<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 upgrade turn carries the stored state as an earlier release wrote it. Its input is null, its caller is the system principal, and its command ID is upgrade:<schemaVersion>.
  • The worker runs the actor’s Akter.migrateState. It answers unchanged when the current states already decode the stored state.
  • It answers the upgraded state when Akter.migrateState upgrades it. The outcome carries no output and no other effects.
  • It answers a defect with the StateUnreadableError message when the state cannot upgrade. It also answers a defect when the state is absent.

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 Data that holds the JSON encoding of the contract schema.
  • SQL values. A SqlValue is null, integer, real, text, or blob, matching the SQLite storage classes.
  • Published contracts. PublishedContracts lists 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 in workerHello before 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.