Backend ABC, the BackendRuntime ABC one launch subcommand implements with
its liveness declarations, the CallbackSchema, the scheduling protocol’s names and models, and
the three seams a backend plugs its engine into: the TaskDoor (its queue), the ScheduleStore
(its schedule storage, read back as StoredSchedule; its ScheduleWriter part is the one
schedule writer) and the WorkerInspection (its worker views).
CONSUMING_RUNTIME
tai42_contract.backend.runtime.CONSUMING_RUNTIME
CRONTAB_FIELDS
tai42_contract.backend.scheduling.CRONTAB_FIELDS
PROCESS_PRELUDE_ENV
tai42_contract.backend.runtime.PROCESS_PRELUDE_ENV
BackendRuntime.process_prelude); the launch compares it with the prelude the selected
runtime declares.
SCHEDULE_BRANCH_SUFFIX
tai42_contract.backend.scheduling.SCHEDULE_BRANCH_SUFFIX
SCHEDULE_CADENCE_ADAPTER
tai42_contract.backend.scheduling.SCHEDULE_CADENCE_ADAPTER
SCHEDULE_CADENCE_KEY
tai42_contract.backend.scheduling.SCHEDULE_CADENCE_KEY
SCHEDULE_DELETE_TOOL
tai42_contract.backend.scheduling.SCHEDULE_DELETE_TOOL
SCHEDULE_EXPORT_TOOL
tai42_contract.backend.scheduling.SCHEDULE_EXPORT_TOOL
SCHEDULE_EXTENSION
tai42_contract.backend.scheduling.SCHEDULE_EXTENSION
SCHEDULE_IMPORT_TOOL
tai42_contract.backend.scheduling.SCHEDULE_IMPORT_TOOL
SCHEDULE_LIST_TOOL
tai42_contract.backend.scheduling.SCHEDULE_LIST_TOOL
SCHEDULE_MARKER_TOOLS
tai42_contract.backend.scheduling.SCHEDULE_MARKER_TOOLS
SCHEDULE_NAME_KEY
tai42_contract.backend.scheduling.SCHEDULE_NAME_KEY
Backend
tai42_contract.backend.base.Backend
launch) and executes the work its
workers pull from the broker. The app core depends only on this interface
and stays backend-agnostic; concrete backends (celery/rq/arq) implement it
and register via @tai42_app.backends.register_backend.
Fleet propagation of config changes is not a backend concern: it is the
app’s own worker bus, internal to the app. A backend-runtime process
receives fleet ops through the app’s bus subscription exactly like a serving
HTTP worker — the backend carries no control-plane surface of its own.
Each backend declares its own drain bound (drain_timeout); the app
announces it, together with its own shutdown bounds, when the process leaves,
so a fleet restart waits for the worker to finish its in-flight work rather
than reporting it timed out.
Members
drain_timeout
tai42_contract.backend.base.Backend.drain_timeout
launch
tai42_contract.backend.base.Backend.launch
@tai42_app.backends.register_backend.
Parameters
BackendRuntime
tai42_contract.backend.runtime.BackendRuntime
liveness), and a progress runtime reports from its own loop.
A runtime runs only on the objects its build produced. The host re-imports the
package a runtime comes from on every config reload, so that the package’s registrations
re-fire into the new configuration, and a reload can land between build and the run
body as well as during it. The runtime is a process-lifetime object and stays whole across
those re-imports: it holds what it built and never resolves its own objects again through
the import system. It hands its engine the objects themselves wherever the engine’s interface
takes an object; it imports nothing of its own package after build; the state its
engine reads lives on the objects it built, never in its package’s module globals; and it
connects receivers to an engine’s process-wide signals from build, never at import.
Where an engine’s interface takes only an import path (a setting that names a class, a stored
job that names its function), the engine resolves that name itself, possibly after a reload,
and so may reach the re-imported copy. An object handed over by name therefore keeps no state
of its own: it reads what it needs from its arguments, from the objects the build produced
that the engine passes it, or from the process environment, so the re-imported copy behaves
as the built one.
Members
name
tai42_contract.backend.runtime.BackendRuntime.name
mode
tai42_contract.backend.runtime.BackendRuntime.mode
consumes_work
tai42_contract.backend.runtime.BackendRuntime.consumes_work
pool_turnover_required
tai42_contract.backend.runtime.BackendRuntime.pool_turnover_required
ClassVar: a
launch option can decide whether this engine’s pool persists, so an instance
may set it. The host therefore reads it off the live runtime.
process_prelude
tai42_contract.backend.runtime.BackendRuntime.process_prelude
module:callable the process must have run before any other import, or None.
Declared by a runtime whose engine reshapes the interpreter’s blocking primitives (its
threads, locks, sockets and sleeps) and so must do it before any other module has bound
them. The host’s entry runs it, with no arguments, first thing in a fresh process, and the
launch refuses a runtime whose prelude this process was not started with
(ProcessPreludeRequired). Not a ClassVar, like pool_turnover_required:
a launch option can decide it, so the host reads it off the live runtime.
liveness
tai42_contract.backend.runtime.BackendRuntime.liveness
ProgressLiveness: what it is alive for is consuming,
and its loop is what consumes. An HTTP server declares HttpLiveness with the path
an orchestrator’s HTTP probe requests.
bind_progress
tai42_contract.backend.runtime.BackendRuntime.bind_progress
build. A second bind raises RuntimeError.
Parameters
report_progress
tai42_contract.backend.runtime.BackendRuntime.report_progress
next_within seconds.
Called from inside the loop on every pass, idle or busy, from any thread. next_within
is the loop’s own sleep or poll bound for the pass that follows; the probe judges this
process against it, so a loop that stops passing stops reporting and is seen as such.
Raises RuntimeError when no reporter is bound (a runtime driven without the host’s
binding, or one that declares HttpLiveness) and ValueError when
next_within is not positive.
Parameters
from_args
tai42_contract.backend.runtime.BackendRuntime.from_args
build
tai42_contract.backend.runtime.BackendRuntime.build
from_args alone must not be forced to declare an empty override.
run_on_loop
tai42_contract.backend.runtime.BackendRuntime.run_on_loop
mode is on_loop.
run_blocking
tai42_contract.backend.runtime.BackendRuntime.run_blocking
mode is worker_thread or inline.
request_drain
tai42_contract.backend.runtime.BackendRuntime.request_drain
worker_thread body runs on
another thread — so it MUST NOT block and MUST NOT touch
main-thread-only APIs (signal.signal above all: the host owns the
process’s signal disposition and a vendor rebind destroys it).
MUST BE IDEMPOTENT: the host calls it on signal AND again on the
cancellation path. Escalation belongs to request_terminate,
never to a second request_drain.
REQUIRED iff consumes_work.
request_terminate
tai42_contract.backend.runtime.BackendRuntime.request_terminate
turn_over_pool
tai42_contract.backend.runtime.BackendRuntime.turn_over_pool
reason, and CONFIRM it.
On return, no pre-mutation worker may take new work; one still finishing the
job it holds exits after it, and is not waited for. Raise loudly if it
cannot be confirmed within budget seconds — the
caller is inside a fleet-op apply, and a raise makes that op report
failed rather than a false applied.
Called from the fleet-op hook, which the host wires BEFORE build
so an op landing during a long boot is not missed. So this may run before
the engine objects exist, and it runs CONCURRENTLY with the run body once
they do. A no-op is the correct answer whenever there is no pool yet, or
the live pool turns out not to hold a snapshot: the workers that do not
exist cannot be stale, and the next ones are built after the mutation.
REQUIRED iff pool_turnover_required.
Parameters
aclose
tai42_contract.backend.runtime.BackendRuntime.aclose
CallbackSchema
tai42_contract.backend.callback.CallbackSchema
condition and a follow-up tool kwargs expr.
Attributes
CrontabCadence
tai42_contract.backend.scheduling.CrontabCadence
Members
expression
tai42_contract.backend.scheduling.CrontabCadence.expression
{"expression": ...} with it gives this cadence back.
ExecutionMode
tai42_contract.backend.runtime.ExecutionMode
Members
on_loop
tai42_contract.backend.runtime.ExecutionMode.on_loop
worker_thread
tai42_contract.backend.runtime.ExecutionMode.worker_thread
inline
tai42_contract.backend.runtime.ExecutionMode.inline
FleetOpApplied
tai42_contract.backend.runtime.FleetOpApplied
effects is what the op changed here (empty for a query or a process exit); a handler
decides on it, never on op, which names the op for logs and a turnover reason.
budget is the seconds left before the publisher’s report cut, measured from this
process’s receipt of the op; a post-apply obligation that cannot finish within it must raise.
Attributes
FleetOpEffect
tai42_contract.backend.runtime.FleetOpEffect
Members
registry
tai42_contract.backend.runtime.FleetOpEffect.registry
templates
tai42_contract.backend.runtime.FleetOpEffect.templates
HttpLiveness
tai42_contract.backend.runtime.HttpLiveness
GET path with a success status on the port it serves.
path is absolute (starts with /) and needs neither a session nor data from a backing
store, so the answer depends on the server alone; a process whose every route sits behind
credentials (basic auth) needs them on the probe too.
Attributes
IntervalCadence
tai42_contract.backend.scheduling.IntervalCadence
every seconds; relative aligns the schedule to the interval’s own clock.
Attributes
Liveness
tai42_contract.backend.runtime.Liveness
ProcessPreludeRequired
tai42_contract.backend.runtime.ProcessPreludeRequired
prelude names it.
Attributes
ProgressLiveness
tai42_contract.backend.runtime.ProgressLiveness
build (BackendRuntime.bind_progress); the
runtime calls BackendRuntime.report_progress from inside its loop on every pass.
ProgressReporter
tai42_contract.backend.runtime.ProgressReporter
next_within is a positive number of seconds. A loop whose own interval is zero (it passes
again without sleeping) promises a fixed positive floor instead: its engine’s own floor for the
wait, where the engine has one, else a bound its next pass returns within.
ScheduleCadence
tai42_contract.backend.scheduling.ScheduleCadence
ScheduleCreate
tai42_contract.backend.scheduling.ScheduleCreate
tool_name on cadence, or once now when no cadence is given.
tool_kwargs are the arguments each fire passes to the tool, the tool’s alone and forwarded
untouched — a tool whose OWN argument is named subject carries it here like any argument.
subject is the OPTIONAL top-level door field naming the schedule-door state context each
fire re-establishes: the create door stamps it onto the job, and the fire keys its state writes and
parks on it (it never reaches the base tool). state_binding is the OPTIONAL door-layer binding
the fire applies around the started tool alone (never the base tool’s). schedule_name names a
recurring schedule; without it the door derives one from the tool, its arguments and the cadence.
A schedule is a parkable-driving door: it carries the four ParkableDoorMixin jqs
(start_expr builds the fired tool’s kwargs; cancel_expr / resume_expr act on the run’s
parked interactions; extras_expr builds the started run’s extras), each evaluated over the
fired tool’s arguments with the run’s parked interactions bound as $parked. Any contract jq
needs an execution_key (the api-key user_id the recurring fire runs as, so a park it
raises can be rebound and resumed under that authority).
Attributes
ScheduleDetail
tai42_contract.backend.scheduling.ScheduleDetail
args and kwargs are the fired tool’s arguments plus the reserved door stamps the
fire needs, as in ScheduleRecord.
Attributes
ScheduleImportError
tai42_contract.backend.scheduling.ScheduleImportError
index in the rows it was handed.
Attributes
ScheduleImportMode
tai42_contract.backend.scheduling.ScheduleImportMode
ScheduleImportReport
tai42_contract.backend.scheduling.ScheduleImportReport
ScheduleListRow
tai42_contract.backend.scheduling.ScheduleListRow
next_run_at_ts is the next run’s POSIX timestamp, None when the schedule has no next
run (0.0 is a timestamp like any other). next_run_at_iso is derived from it, the UTC
ISO-8601 form or None: a row is built without it, and a given value that disagrees with
the timestamp is refused.
Attributes
ScheduleRecord
tai42_contract.backend.scheduling.ScheduleRecord
ScheduleRowError
tai42_contract.backend.scheduling.ScheduleRowError
ScheduleStore
tai42_contract.backend.schedule_store.ScheduleStore
False or None answers only “no such
schedule”.
Members
holds_disabled
tai42_contract.backend.schedule_store.ScheduleStore.holds_disabled
enabled=False) as such.
A store that holds none keeps every schedule it stores enabled: write refuses a
disabled record and set_enabled is never called on it.
exists
tai42_contract.backend.schedule_store.ScheduleStore.exists
name is stored.
Parameters
read
tai42_contract.backend.schedule_store.ScheduleStore.read
name, or None when none is stored.
Parameters
read_all
tai42_contract.backend.schedule_store.ScheduleStore.read_all
delete
tai42_contract.backend.schedule_store.ScheduleStore.delete
name; False when none was stored.
Parameters
set_enabled
tai42_contract.backend.schedule_store.ScheduleStore.set_enabled
name; False when none is stored.
Parameters
run_now
tai42_contract.backend.schedule_store.ScheduleStore.run_now
name run at once, its recurrence kept; False when none is stored.
Parameters
update
tai42_contract.backend.schedule_store.ScheduleStore.update
name in one step; False when none is stored.
cadence, when given, replaces its cadence; next_run_at_ts, when given, moves its
next run to that POSIX timestamp. At least one is given. A new cadence without a
next_run_at_ts takes its next run from the store’s own rule for a new cadence.
Parameters
ScheduleWriter
tai42_contract.backend.schedule_store.ScheduleWriter
relative_intervals before it writes.
Members
relative_intervals
tai42_contract.backend.schedule_store.ScheduleWriter.relative_intervals
relative=True.
write
tai42_contract.backend.schedule_store.ScheduleWriter.write
record names, as record defines it.
The one writer behind the schedule branch, create, update and import. record.tool is
stored inside the job kwargs under the backend’s tool-name argument. The write is durable
when this returns; it raises on a store failure.
Parameters
StoredSchedule
tai42_contract.backend.schedule_store.StoredSchedule
kwargs are the stored job kwargs: the fired tool’s name under the backend’s tool-name
argument, the tool’s arguments and the reserved stamps. next_run_at_ts is the next run’s
POSIX timestamp, None when the store records no next run. error is the store’s last
scheduling failure for the schedule, when it records one.
Attributes
TaskDoor
tai42_contract.backend.dispatch.TaskDoor
HandleT is the vendor’s own handle on a submitted job (a result object, a job record);
only the door reads it.
Members
task_opts
tai42_contract.backend.dispatch.TaskDoor.task_opts
None) of the sync and async branch
tools, and reaches submit in its options when the caller gave a value.
submit
tai42_contract.backend.dispatch.TaskDoor.submit
args and kwargs; return its handle.
kwargs are the prepared job kwargs (the tool name and the reserved stamps inside).
options are the task options the caller gave, None values already dropped and the
callback taken out: the door maps each onto its queue’s API and raises on one it cannot
honour. callback, when given, already carries what its follow-up job needs; the door
chains it to run on the job’s result.
Parameters
task_id
tai42_contract.backend.dispatch.TaskDoor.task_id
wait
tai42_contract.backend.dispatch.TaskDoor.wait
timeout seconds for the job to finish and return its result.
A failed job raises its failure as the vendor retains it. A job still unfinished at
timeout raises TaskWaitTimeoutError; the job itself is left running.
Parameters
TaskWaitTimeoutError
tai42_contract.backend.dispatch.TaskWaitTimeoutError
TaskDoor.wait when the job is still unfinished at its timeout.
Its own class, so a job that itself failed with a TimeoutError is never read as an
unfinished one.
WorkerInspection
tai42_contract.backend.inspection.WorkerInspection
worker_name narrows a view to one worker; None covers every worker. A view is
handed a worker_name only when addresses_workers, and cancel a
terminate=True only when terminates.
Members
addresses_workers
tai42_contract.backend.inspection.WorkerInspection.addresses_workers
terminates
tai42_contract.backend.inspection.WorkerInspection.terminates
cancel serves terminate=True: the backend’s workers stop a task while it runs.
ping
tai42_contract.backend.inspection.WorkerInspection.ping
active_workers
tai42_contract.backend.inspection.WorkerInspection.active_workers
task_status
tai42_contract.backend.inspection.WorkerInspection.task_status
task_id.
Parameters
task_result
tai42_contract.backend.inspection.WorkerInspection.task_result
(ready, status, value): whether it finished, its status word, its result.
With a timeout it waits up to that many seconds for the task to finish; with None
it reads the current state at once. value is the result when ready. A failed task
raises its failure as the vendor retains it.
Parameters
cancel
tai42_contract.backend.inspection.WorkerInspection.cancel
task_id; return what was done.
Without terminate a task that has not started is kept from running and a running one is
left to finish; with terminate a running task is stopped as well. A backend that cannot
cancel a running task without stopping it refuses the call without terminate for a
running task rather than stopping it. The reply says what was done; when a worker answers
that it cannot stop the task it runs, the call is refused rather than leaving the task
running behind a reply that says otherwise, and a stop the workers did not confirm within
the time the backend waits for it is reported as not confirmed, with the status the task
reached.
Parameters
active_tasks
tai42_contract.backend.inspection.WorkerInspection.active_tasks
reserved_tasks
tai42_contract.backend.inspection.WorkerInspection.reserved_tasks
scheduled_tasks
tai42_contract.backend.inspection.WorkerInspection.scheduled_tasks
eta or countdown).
registered_tasks
tai42_contract.backend.inspection.WorkerInspection.registered_tasks
failed_tasks
tai42_contract.backend.inspection.WorkerInspection.failed_tasks
worker_stats
tai42_contract.backend.inspection.WorkerInspection.worker_stats
worker_queues
tai42_contract.backend.inspection.WorkerInspection.worker_queues

