Yoke Function Call Reference

Registered function ids are the typed control-plane interface. Use their yoke <subcommand> adapters; Git, gh and external tools remain command-shaped. Read the operation's --help for payload, target, authorization and recovery. The dispatcher verifies claims before the canonical domain handler executes. Live startup recipes: yoke packets render --role main_agent; request a topic with --detail full for its complete schema and recipes.

Operation families

Each registered id has one catalog owner:

Work	Catalog
Work/path/coordination claims and decisions	Claims
Items, sections, progress, readiness and lifecycle	Items
Projects, settings, strategy, Packs, environments and shared files	Project configuration
QA cases, evidence and test machines	QA
Sessions, actors, deployment, messaging and live services	Runtime
Generated tasks, dispatch and reviews	Tasks
Pinned definitions, canon updates and routing	Workflows
Lane preparation, landing, merge and close-out	Worktrees

Envelope

Models: yoke_contracts.api.function_call. Client item selectors are complete public refs; the serving engine alone resolves internal item keys. Task targets also carry task_num. Other record ids retain their own domain meaning.

{"function":"<registered id>","version":"v1","request_id":"<uuid>",
 "actor":{"session_id":"<session>"},
 "target":{"kind":"item","public_ref":"PREFIX-N"},
 "payload":{},"preconditions":{},"options":{}}

Responses carry success, function, version, request_id, result, warnings[], one optional error (code, message, jsonpath, recovery_hint) and event_ids[]. Consume typed fields. Primary mutation failure and downstream-degraded warnings are different outcomes; inspect both. Post-write verification marked degraded is partial-state evidence, never green.

Read deadlines

A registered function declaring no side effects shares a 25-second handler budget in local, self-hosted and hosted dispatch. The HTTPS relay waits 30 seconds for a response and never resends a call that timed out: the server keeps running the original, so a copy would only queue behind it. The server reserves five seconds for its response and failure evidence. Browser dispatch and the local UI proxy use the same handler budget; neither declares an extra browser timer.

The budget is checked at native-call boundaries, never by interrupting running Python. Each PostgreSQL transaction arms its server-side statement timeout once, from the budget remaining when the transaction starts; nested HTTP reads inherit the same deadline, and the handler is checked again when it returns. Subprocesses and native database protocols always finish or time out on their own terms. Mutations retain their existing execution and replay contracts.

An expired read returns read_deadline_exceeded (HTTP 408), with a recovery hint, and YokeFunctionCalled records the failed outcome for Performance. Retry a narrower read: name a project or section, or use --limit and --offset. Request --full only when the caller needs detail. Plan pickers, search and intake follow summary pages; Test plans explicitly requests full rows for outcomes, execution targets, attachments and case counts.

Dropped connections

Handlers open a fresh database connection on every invocation. When that connection drops mid-statement (consuming input failed, SSL SYSCALL error, unexpected eof), a side-effect-free function runs once more inside the same read budget. A function that can change state is never resent, because the lost statement may already have committed. A second drop, or any drop in a state-changing function, returns control_plane_connection_lost (HTTP 500, so the HTTPS client does not resend it). Its recovery is to re-read the targeted state and rerun once yoke env list shows the control plane reachable; the deploy driver adds yoke watch deploy -- RUN-ID, because a run resumes where it stopped. The one call the driver re-sends itself is QA stage dispatch, which is idempotent: a lost answer is sent again up to three times, 5s then 15s apart, and a refusal is never re-sent. Any other exception a handler raises answers handler_exception with the function id and exception class, on in-process dispatch as on the HTTPS route, never a raw traceback. The HTTPS server logs function_call_handler_failed with the request id, exception class and the traceback's frame locations (file, line, function), never the message or payload, so an operator can find the failing line.

Locks a handler could not take

Every write that serializes on a deployment run takes the run row through one bounded lock: it waits at most 2 seconds, then refuses run_busy with the holder's pid, its state and how long it has held the lock. Dispatch answers three lock outcomes by name instead of handler_exception, because each means another transaction held what this call needed and this call's open transaction did not commit:

Code	Cause
run_busy	The deployment run row stayed locked past its 2-second bound.
lock_timeout	Another lock wait outlived a lock_timeout.
statement_cancelled	An operator cancelled the statement, or a server timeout ended it.

Callers retry these instead of failing. The deploy driver re-dispatches a QA or approval stage on its 15-second check, and repeats other run calls after 15s, 30s, then 60s. If the run stays busy past the cap it stops with deployment_run_stayed_busy, leaving the run unchanged and unfailed; re-run yoke watch deploy -- RUN-ID. yoke qa plan run and yoke qa case run, and so yoke watch qa-plan and yoke watch qa-case, back off on the same schedule. They stop with run_busy_retries_exhausted after seven attempts.

Claim verification

Catalog value	Dispatcher obligation
none	No work-claim check; handler/project/org authorization still applies.
item	Active target item claim belongs to calling session.
epic	Calling session holds the target task's parent item claim.
qa_subject	Verify the case's item/run/project subject and recording authority.
self_only	Target claim belongs to calling session.
steering	Require a live steering seat covering the target project/document; refusal names steering_seat_required, seat acquisition or yoke say --steering.

These six values come from yoke_core.domain.yoke_function_registry; none means Python None. Claim policy never grants project/org permissions.

Identity, replay and rollout

Use a stable request id for one intended write. Same function/id replays its ledger response; cross-function reuse refuses. After ledger expiry a call is new. Never repeat a mutation merely to request --json; request its receipt initially. Mutations remain committed when a separately reported downstream side effect degrades. Required operational facts belong to durable owners, not event history.

universe.prune.run manages idempotency by reselecting remaining eligible rows; it stores no result receipt. Its foreground command does not resend a lost mutating pass and reports that pass's count as unknown. See universe retention for the output-only exception.

The registry owns ids, request schemas, handler/claim metadata, adapter status and minimum serving versions. New ids declare their serving floor; below-floor calls refuse with a served recovery or operator escalation. Clients tolerate absent optional response fields from older builds without inventing selectors. HTTP dispatch/health remain cross-version infrastructure boundaries; agents use registered adapters. internal adapter status grants no access by itself.

Source maintainers enumerate the catalog with yoke_core.domain.handlers.__init_register__.register_all_handlers and yoke_core.domain.yoke_function_registry.list_entries; request schemas come from schema_for. The source Atlas renderer is python3 -m yoke_core.tools.atlas_render_docs render. See DB reference for domain contracts and the CLI entrypoint.