Core module reference

​

Overview

​

Who this is for and how to read it

​

Scope: what is and is not in core

• Workflow definitions, versions, validation and compilation
• The stream engine and per-node failure and time policy
• Admission control, idempotent starts, the command pipeline
• Tracker, progress, results, metrics and tracing
• Execution log, checkpoints, recovery and resume
• Supervisor and reviewer hosts, worker registry, leader election
• API key and role model, variable allow-list

• REST controllers, SSE endpoints, Host/Origin filter: web
• MCP tools: mcp. CLI: cli. UI: ui
• Node implementations (LLM_CALL, HTTP_REQUEST, …): plugins/*; contracts: plugin-api
• PostgreSQL stores and Flyway migrations: persistence-postgres
• RSocket worker transport and agent: workers
• Application wiring and native image: boot

​

Status legend

​

Core concepts

​

A workflow, concretely

{
  "workflowId": "triage",
  "description": "Classify a ticket, wait for approval, update the tracker",
  "nodes": [
    { "nodeId": "ticket",   "type": "API_TRIGGER",     "config": {} },
    { "nodeId": "classify", "type": "LLM_CALL",
      "config": { "engine": {
        "retry":   { "maxAttempts": 3, "backoffMs": 200, "maxBackoffMs": 5000 },
        "onError": "ROUTE" } } },
    { "nodeId": "approve",  "type": "WAIT_FOR_SIGNAL", "config": { "signal": "approve" } },
    { "nodeId": "update",   "type": "HTTP_REQUEST",    "config": {} },
    { "nodeId": "done",     "type": "CONSOLE_TERMINAL","config": {} },
    { "nodeId": "dead",     "type": "CONSOLE_TERMINAL","config": {} }
  ],
  "edges": [
    { "source": "ticket",   "target": "classify" },
    { "source": "classify", "target": "approve" },
    { "source": "approve",  "target": "update" },
    { "source": "update",   "target": "done" },
    { "source": "classify", "target": "dead", "sourcePort": "error" }
  ]
}

​

Architecture

​

Position in the system

​

Component map

​

Design principles

• Plugins hold business logic only. Back-pressure, retries, timeouts, pause/step and failure routing live in the engine once, wrapped around every node.
• One path to change a run. Humans, supervisors, REST and MCP all send the same commands through the same ordered, reviewable, audited pipeline.
• Safe defaults, explicit opt-in. Process execution is off, environment access is allow-listed, limits are off (not unbounded by accident: documented in the reference).
• Storage behind interfaces. Memory, files and PostgreSQL implement the same stores, so durability is a deployment choice, not a code path.
• Honest guarantees. At-least-once, forward-only status, FIFO per run: see Guarantees.

​

Run lifecycle

​

The node wrapper

​

Package map

​

Feature catalog

​

Workflow definitions

​

DEF-01: Definition store and versions

• Saving an identical definition adds no version. Each run records a content hash of the graph it used (definitionVersion), carried by progress, history and the log.
• A start payload with yukta.version runs that saved version and bypasses the prepared-workflow cache.
• WorkflowDiff reports a changed description, nodes added, removed or changed, and edges added or removed. A version may carry a note.
• File layout: <baseDir>/workflows/<session>/<workflow>/current.json and history/<version>.json; ids are URL-encoded; writes are atomic and fsynced.

​

DEF-02: Validation

• Rejects cycles, duplicate node ids, duplicate edges, an edge sourcePort the source plugin does not declare (error is allowed on nodes with onError: ROUTE), and graphs over 500 nodes or 2000 edges.
• Rejects malformed failure policies: unknown keys, maxBackoffMs not below the node timeout, retryOn and noRetryOn sharing a class, deadlineMs not above elementTimeoutMs.
• Identifiers (session, workflow, node, plugin name, file path, config key) are shape-checked by Bean Validation annotations at the orchestrator boundary, e.g. no path separators in a session id.

​

DEF-03: Preparation and compile cache

• One assembler per node kind (trigger, processor, terminal) builds each node’s wrapper (ENG-02).
• Concurrent starts of a workflow that is not yet prepared share one preparation, keyed by definition content.
• A prepared workflow is cached only if the stored definition has not changed meanwhile, so an old compile never overwrites a newer edit. Applying a session configuration drops a stale cached entry.
• A processor with engine.placement has its plugin swapped for a RemoteProcessor here (SCL-01).

​

Execution engine

​

ENG-01: Streaming DAG and back-pressure

• Every child subscribes before its source starts, so no early message is lost. A fan-out moves at the speed of its slowest child.
• Opt-out per node: engine.edgeBuffer {size, overflow} puts a bounded buffer in front of a node. When the node is slower than its parents it drops messages (DROP_OLDEST default, or DROP_NEWEST) instead of pacing the fan-out. Drops are counted in yukta.edge.dropped. The default stays lossless.
• Blocking plugins run on virtual threads so they do not hold the event loop.

​

ENG-02: Node wrapper pipeline

• Order: merge parents → edge buffer → valve → plugin call (attempt, timeout, retry, onError) → clocks and status → broadcast to children. See the steps in Architecture.
• The plugin gets a Reactor context holding the execution id, node id, a heartbeat Runnable (WorkflowContext.HEARTBEAT_KEY), a PluginLogSink and, for sub-workflows, a result collector.
• With retry, onError or elementTimeoutMs the plugin is called once per message and the message carries an attempt header (1, 2, …).

​

ENG-03: Join rules

​

ENG-04: Failure policy (engine config)

"engine": {
  "retry":   { "maxAttempts": 3, "backoffMs": 200, "maxBackoffMs": 5000 },
  "onError": "ROUTE",
  "trigger": "ALL_DONE",
  "elementTimeoutMs": 20000,
  "deadlineMs": 600000,
  "failureBudget": { "maxFailures": 10, "windowMs": 60000 },
  "edgeBuffer": { "size": 100, "overflow": "DROP_OLDEST" },
  "placement": { "pool": "default" }
}

• All-or-nothing output. With retry or onError CONTINUE/ROUTE, what an attempt emitted before it failed is held back and dropped, so a retry or dead letter never lands on top of a partial result. One message’s output is therefore buffered until its attempt ends.
• Malformed policies are rejected by validation (DEF-02) with node id and option.

​

ENG-05: Clocks and timeouts

• Idle timeout is the node’s timeoutSeconds, else the plugin’s getDefaultTimeout(config). Built-ins: PROCESS_EXECUTOR its timeout (300 s) + 10 % (min 5 s); LLM_CALL every attempt plus backoff; HTTP_REQUEST its timeout + 5 s; others 30 s. WAIT_FOR_SIGNAL adds its wait + 30 s.
• A timeout given as an expression is unknown at compile time: the node starts with the default and is re-timed when its first message arrives (NodeTimeouts). Write numeric options as typed expressions, e.g. ${payload.secs:int}.
• Pausing freezes all clocks. A terminal’s idle timeout and deadlineMs also cover what it does after its last input.
• Long silent work keeps its node alive by calling the heartbeat Runnable found under WorkflowContext.HEARTBEAT_KEY in the Reactor context.

​

ENG-06: Status model

• Order: PENDING < QUEUED < RUNNING < any terminal status. A status that would step back is ignored, but its metadata is still merged.
• A node becomes RUNNING (and gets its startTime) at its first activity (NodeActivity.onFirstTouch: first input, or subscribe for a trigger), not when the graph is wired.
• Nodes behind a failed node end UPSTREAM_FAILED, so only the node that failed shows FAILURE.
• The first terminal that fails ends the run at once and cancels the other branches (CANCELLED). A caller that cancels ends the run CANCELLED. A second end of a run is ignored.
• A processor skipped from the start can be unskipped later.

​

ENG-07: Sub-workflows

• The child is a normal run with its own execution id, tracked and audited like any other. Its terminal nodes feed a ResultCollector; the node emits {executionId, results[]}. A failing child fails the node, so the parent’s failure policy applies.
• The child’s start payload carries yukta.depth and yukta.parentExecutionId. Nesting is limited to 5.
• With yukta.execution.max-concurrent set, a child runs on the slot its parent holds (ExecutionScheduler.borrowed()): children are not counted in limits or the running gauge, which prevents a parent waiting on children from starving them.
• The child is subscribed inside the parent node, so cancelling the node cancels the child (CANCELLED).

​

Admission and governance

​

ADM-01: Scheduler, limits and queue

• Caps: total concurrent runs, per workflow, per session. All are off by default. A start that does not fit waits (QUEUED) or is refused with HTTP 429, per on-limit.
• Queue order: payload key yukta.priority (number, higher first, default 0), then the session with the fewest running runs (oldest first on a tie), then arrival. One busy session cannot starve others.
• The slot is taken after preparation and before the id is handed out. Restarting a finished run, restart-from-node and resume take their slot the same way. Restarting a run that is still going keeps the old behaviour: the old run holds its slot until it ends.
• Shutdown: nothing new is admitted, queued starts are refused, running ones get shutdown-timeout to finish.
• Refusals are counted by reason in yukta.executions.rejected{reason=shutdown|limit|queue_full|workflow_queue_full|queue_timeout|not_leader}.

​

ADM-02: Idempotent start

• POST /workflow/start accepts an Idempotency-Key header. A repeat with the same key, session and workflow within the TTL returns the first execution id. A failed start is not remembered.
• With the file log the keys are written as IDEMPOTENCY_KEY entries and reloaded on startup (the window restarts at the reload).

​

ADM-03: Live limit and priority changes

• changeLimits(max, perWorkflow) is recorded in the log under run id scheduler; the newest retained-runs of them are kept. On startup the newest applied SetLimits(max, perWorkflow) entry is re-applied, so the log wins over configuration from then on.
• changePriority(execution, priority) moves a QUEUED start and is recorded as SetPriority(n); rejected if the run is not waiting.
• Both pass the reviewers and are audited with the actor. Over REST, limits need role ADMIN and priority OPERATOR.

​

Control plane

​

CTL-01: Command pipeline

• Commands are a sealed set (ExecutionControlCommand): pause/resume workflow and node, step mode, step, stop node, stop workflow, skip, breakpoint, signal, restart, restart-from-node, set limits, set priority. One processor class per command.
• The caller’s answer arrives only once the command has been applied (CommandSequencer: FIFO per run; runs are independent).
• Audit: every command for a known run is logged as CONTROL_APPLIED (status = command name) or CONTROL_REJECTED (status = command: reason). Commands for unknown runs are not recorded. A restart that fails is audited as rejected.
• The actor is carried in the Reactor context (ControlActor.CONTEXT_KEY); REST uses the API key name, supervisors their id.

​

CTL-02: Pause, step, breakpoint and skip

• Pause stops taking new messages; the one being processed finishes. All clocks freeze, so a pause never causes a timeout.
• Step lets exactly n messages through, then pauses.
• Breakpoint holds a node before the first element whose payload, payload.some.path or metadata.key equals a given text. Ordered and audited like any command (SetBreakpointCommand).
• Skip (processors only) passes elements through without calling the plugin from the next element on; one already in the plugin finishes. Unskip resumes. Other node kinds are rejected.

​

CTL-03: Stop modes

​

CTL-04: Restart, restart-from-node and retry node

• Restart from node re-runs the node and its descendants and replays the recorded output of the nodes feeding them (RestartPlan); independent branches are left alone. On a run still going, only parents that have finished (durable end marker) are replayed; a replayed output is marked finished under the new run.
• Retry node does the same for a node that ended FAILURE or TIMED_OUT, using the output its parents recorded.
• The archive keeps recent finished runs restartable: graph, start payload and recorded outputs (ExecutionArchive). A node that exceeds its caps makes a restart that needs it be refused rather than replayed partially, unless a spill directory is set (DUR-02).
• Restart-from-node after a server restart is not supported (the archive is in memory); use resume for aborted runs.

​

CTL-05: Signals and approval steps

• The plugin must answer ACCEPTED or QUEUED. A node of a live run that is not waiting yet keeps the signal for ten minutes (at most 100, QUEUED); a signal for a node that is not registered gives HTTP 409.
• Waits of all plugins share SignalWaits.shared(), so one list of open approvals (oldest first) serves REST, MCP and the workflow page.
• WAIT_FOR_SIGNAL holds each message until its signal arrives (signal, timeoutSeconds default 3600, onTimeout, onReject) and tags it with signal.name/decision/data.
• An answer is recorded in the checkpoint store as a message of pseudo node signal:<node> (a timeout is not), so a resumed run reuses it for the same message id instead of waiting again.

​

CTL-06: Reviewers

• A ControlReviewer bean implements review(ControlRequest). The first refusal in order() wins; a reviewer that errors refuses.
• The caller gets ControlRejectedException (HTTP 403) and the log gets CONTROL_REJECTED.
• Limit and priority changes pass reviewers too. The raw plugin-level node command refuses signal bodies (use the signal command).

​

CTL-07: Supervisors

• A bean implements ExecutionSupervisor: supervise(Flux<ExecutionEvent>) receives the global event feed and returns ExecutionControlCommands. SupervisorHost subscribes each supervisor once and applies commands with the supervisor id as actor (logged as PauseWorkflowCommand [by <id>]).
• Isolation: failures resubscribe with backoff; commands are limited to yukta.supervisor.max-commands-per-second (20); yukta.supervisor.dry-run=true records without applying; a supervisor never sees the outcome of its own commands; events arrive through a bounded buffer (256) on boundedElastic, and a slow supervisor drops events (yukta.tracker.dropped{kind=supervisor}) instead of holding the tracker.
• No JVM code needed: the feed is also an SSE stream, GET /api/events/stream (filters executionId, type); external agents steer through REST or MCP.
• GET /api/supervisors reports kind (CONTROL_PLANE | SUPERVISOR), order, dry-run flag and command counts.
• Reference implementation: plugins/supervisors/rule-supervisor (JSON rules + SpEL).

​

CTL-08: Plugin-level control bus

• Keyed by workflow and node (not by run), it bypasses the reviewers and is not audited like run commands. Handlers: ControlHeartbeatHandler, ControlStatisticsHandler, ControlSignalHandler.

​

Observability

​

OBS-01: Tracker and live progress

• State and workflow events are never dropped: they go to an unbounded queue (gauge yukta.tracker.queue.depth). Log lines are best effort (OBS-02).
• One consumer applies events in batches (TrackerEventApplier) to per-run WorkflowState; it resubscribes with capped backoff if its stream fails, until shutdown().
• Every progress snapshot carries definitionVersion (content hash of the graph).
• History: the newest status-history-max-per-run (200) snapshots per run for status-history-max-executions (1000) runs, always the newest; a late SSE client catches up from this cache (TTL 5 minutes).
• yukta.tracker.max-sessions evicts the oldest session without a running run when more are held (off by default). Finished runs are cleaned up after yukta.tracker.cleanup-ttl (10m).
• Use SinkEmit.offer, not Sinks.Many#emitNext, for any bounded sink: emitNext terminates the sink on overflow.

​

OBS-02: Live logs

• A plugin writes through the PluginLogSink in the Reactor context. A node that did so (NodeActivity.hasLoggedLive) is not echoed again from its output message; other nodes log that message cut to 2,048 characters.
• More than 10,000 waiting lines are dropped and counted in yukta.tracker.dropped{type=log} (type=state counts events lost because the tracker had ended).
• A failed log write is logged and counted in yukta.tracker.log.append.failed{type=node|run}; it never blocks a status update or the end of a run.
• Engine log lines carry executionId / nodeId as structured key-values; there is no MDC.

​

OBS-03: Execution results

• Terminals publish each input message and a NODE_END; the orchestrator publishes EXECUTION_END and completes the stream.
• The live stream is complete; only the replay buffer is bounded, and end events carry truncated when it dropped anything.

​

OBS-04: Metrics

• The tracker records node executions, durations and retries when a node reaches a terminal status, and run duration and queue wait per run.
• Scheduler gauges, rejection counts by reason, checkpoint bytes and errors, dropped events and edge drops complete the picture.

​

OBS-05: Tracing

• Observations become spans only when a Micrometer tracer is on the classpath.
• Node spans are opened only for a status the run state accepted, so a late RUNNING for an ended node leaves no open span.

​

Durability and persistence

​

DUR-01: Execution log

• Event types: RUN_STARTED, RUN_FINISHED, RUN_ABORTED, CONTROL_APPLIED, CONTROL_REJECTED, NODE_FINISHED (history only), RUN_RESUMED, IDEMPOTENCY_KEY.
• Memory by default, trimmed like the file log (LogRetention: newest retained-runs, never a run without an end, every compact-after events). With yukta.execution-log.dir it is executions.jsonl on disk.
• File access runs on one background writer thread. Events are not fsynced unless yukta.execution-log.fsync=true; a rewritten file (compaction, session config) is forced to disk before it replaces the old one.
• Boot recovery (ExecutionRecovery): runs that never finished are marked ABORTED, the newest retained-runs are restored into history, and the log is rewritten without older ones.

​

DUR-02: Checkpoints and durable end markers

• Memory store: capped by messages per node, bytes per node (strings and byte arrays by size, other payloads count 1 KiB) and retained executions. A node over a cap makes a restart that needs it refuse, unless a spill directory is set: the whole node output then moves to files (replayed as plain JSON), is deleted with the execution, and leftovers of an earlier process are removed at startup. Do not point it at a shared folder.
• File store (yukta.restart.dir): one JSON line per message through one open channel per node until markComplete; no caps. markComplete forces the output, writes and forces <node>.done and the directory.
• PostgreSQL store: DUR-04.
• yukta.checkpoint.errors counts failed markers; that node then runs again on resume.

​

DUR-03: Resume and recovery

• Needs yukta.execution-log.dir (holds the start payload) and a file or PostgreSQL checkpoint store. A run resumes once (RUN_RESUMED) and only if its definition is unchanged. The claim is kept in memory and dropped on failure or if the caller cancels.
• Refused (HTTP 409 ConflictException) if the run was not aborted, was already resumed or its workflow changed.
• yukta.restart.auto-resume=true resumes each interrupted run after any recovery, one after another.
• Resume reads the log and checkpoint files on boundedElastic.

​

DUR-04: PostgreSQL stores

• R2DBC at run time (spring.r2dbc.url); Flyway migrations applied over JDBC (spring.flyway.url) from persistence-postgres/src/main/resources/db/migration. Profile postgres; build with -Pyukta.persistence=postgres.
• Stores: R2dbcSessionConfigStore, R2dbcWorkflowDefinitionStore (newest 20 versions, notes), R2dbcExecutionLogStore (one writer thread; trims to retained-runs; never drops a run without an end), R2dbcNodeCheckpointStore (one JSONB row per message plus a state row per node with the end marker; migration V3), R2dbcKeyValueStore (KV_STORE; V5), R2dbcSessionHistoryStore (SESSION_MEMORY; V6). Leader lease is V4.
• The in-memory and file defaults step aside when the type is postgres.

​

DUR-05: Session configuration

• Applying a session configuration stores the session and its workflows, and drops a cached prepared workflow if the stored definition has moved on.
• Default execution timeout (the run deadline of ENG-05) is 3600 s and can be set per session.

​

Scale-out and high availability

​

SCL-01: Remote workers

• Registry: a registration or heartbeat renews a lease (yukta.workers.lease, 15s); a worker that misses it is dropped. Workers connect out to the control plane over RSocket (route worker.session), reconnecting with a growing pause.
• Placement: WorkflowPreparator swaps the plugin for a RemoteProcessor; the local plugin still provides type, schema, timeouts and validation. The control plane picks the connected worker of the pool that allows the plugin type and has the most free slots; none means the attempt fails at once, retryably.
• Protocol: one requestChannel per attempt (node.run): START, the input messages, COMPLETE; back come the output, HEARTBEATs that restart the node’s idle clock, and COMPLETE or ERROR. Back-pressure and cancellation work end to end. Messages cross as plain JSON values.
• Failure: a worker lost mid-attempt fails it with a WorkflowExecutionException naming it; the engine’s retry can land on another worker. A stopping worker drains first (draining on the lease frame), waiting up to yukta.workers.drain-timeout (30s).
• Security: shared token; optional mutual TLS (control plane: spring.rsocket.server.ssl.bundle and client-auth=need; worker: yukta.workers.ssl-bundle, host name verified).
• yukta.workers.control-plane may list several comma-separated addresses; a standby refuses registration, so workers find the leader after a failover.

​

SCL-02: Active/standby high availability

• A single server is always leader (SingleServerLeader). With yukta.ha.mode=postgres the lease row (V4__leader_lease) has a fencing number that grows with every change of holder. It is renewed three times per lease; a graceful stop releases it.
• A server counts itself leader only while its last renewal is younger than the lease, so one that cannot reach the database stops before another takes over.
• A standby refuses every start, restart and resume with NotLeaderException (HTTP 503; yukta.executions.rejected{reason=not_leader}).
• Takeover: startup recovery is skipped in this mode; TakeoverRecovery runs ExecutionRecovery.recover() (old leader’s unfinished runs become ABORTED). With yukta.restart.auto-resume=true they are resumed from the checkpoints (use the PostgreSQL store or a shared directory).

​

Security

​

SEC-01: API keys, roles and actors

• Keys come from yukta.api-key (one key that may do everything) and yukta.api-keys[] (name, key, role, sessions). A key is plain text or sha256:<hex>; several keys at once allow rotation without downtime. A request presents Authorization: Bearer <key> or X-API-Key.
• Roles: VIEWER reads. OPERATOR also starts, controls and recovers runs (paths under /api/executions/ and /api/workflow/, no ..). ADMIN everything, including defining sessions and workflows (which can run processes, scripts and SQL) and changing scheduler limits.
• The audit records the actor as key:<name>; GET /api/control/audit lists who sent which command.
• With no key set, the web layer enforces a Host and Origin check (HostOriginFilter): unknown Host or foreign Origin on a non-GET gets 403, protecting a local server from CSRF and DNS rebinding.

​

SEC-02: Expressions, variables and secrets

• Sources: ${payload.x}, ${metadata.key}, typed values such as ${payload.secs:int} (untyped stays text), ${context.x} (plain values from the run’s Reactor context, outside yukta.*).
• ${env.X} and ${sys.x} read only: YUKTA_VAR_* variables, yukta.var.* properties, a short list of harmless names (HOME, USER, PATH, user.name, os.name, …), and names in yukta.variables.allowed / YUKTA_VARIABLES_ALLOWED. Names that look like secrets stay blocked even if listed.
• Secrets are written decrypted:name; the default provider reads YUKTA_SECRET_NAME, so values never appear in a stored definition.
• Expressions (SpEL) may call only a short list of methods (SafeMethodResolver). The evaluators live in plugin-api and the script plugin, not in core.

​

SEC-03: Execution safety limits

​

Extensibility

​

EXT-01: Plugin contract and registry

• PluginRegistry maps getType() to the plugin and fails at startup on a duplicate type. A plugin may declare config fields, output ports, a default timeout (getDefaultTimeout(config)) and a failure mode.
• The plugin runs inside the same JVM as the engine. Throwing IllegalArgumentException means “bad input” and is never retried.
• Plugins can be implemented by plugin-api contracts without depending on core internals; the engine hides its engine options from them.

​

EXT-02: Plugin logging API

• PluginLoggerFactory is a @FunctionalInterface with one method, create(LoggerContext). LoggerContext is a record of execution id, session id, plugin id and plugin name; default methods for 3- and 4-argument creation keep older callers working.
• DefaultPluginLoggerFactory extracts the values and builds a DefaultPluginLogger. Lines flow to live logs.

​

EXT-03: LLM and MCP budgets

• LLM_CALL takes budget: {maxTokens, maxCost, maxCalls, hardStop, agent}; MCP_TOOL_CALL takes {maxCalls, agent, hardStop}. Use is counted per run across nodes (RunBudgets.shared(); newest 10000 runs); a budget with an agent is counted apart.
• At the limit the next call fails like a failed call (so failureMode and routeByStatus apply). With hardStop: true it throws RunAbortedException, which NodePolicies never retries, drops or routes: the whole run ends.
• yukta.llm.rate-limit.<provider> (requests per minute) spaces calls to a provider across all nodes and runs.

​

Reference

​

Configuration properties

​

Metrics

​

Enumerations

• SUCCESS · FAILURE · ERROR
• STOPPED · CANCELLED · TIMED_OUT
• SKIPPED · UPSTREAM_FAILED · ABORTED

• onError: FAIL · CONTINUE · ROUTE
• trigger (join): ALL_SUCCESS · ALL_DONE · ONE_SUCCESS
• edgeBuffer.overflow: DROP_OLDEST · DROP_NEWEST
• stop mode: DRAIN · CANCEL · KILL
• on-limit: QUEUE · REJECT
• API role: VIEWER · OPERATOR · ADMIN
• Log event: RUN_STARTED · RUN_FINISHED · RUN_ABORTED · CONTROL_APPLIED · CONTROL_REJECTED · NODE_FINISHED · RUN_RESUMED · IDEMPOTENCY_KEY

​

HTTP outcomes produced by core

​

Client surface by capability

​

Guarantees and limits

​

Durability matrix

​

Capacity ceilings

• One brain: admission, command ordering and run state are in one JVM (active/standby gives failover, not scale-out of admission).
• Graph size: 500 nodes, 2000 edges, sub-workflow depth 5.
• Memory growth: the state queue is unbounded; sessions are evicted only when yukta.tracker.max-sessions is set; the in-memory log and idempotency cache are bounded by their retention settings.
• Large payloads are carried through memory by every node that touches them; there is no claim-check yet.

​

Maintaining this document

​

How the page is organised

​

What to edit when you change core

### XXX-00: Feature name

**Status:** stable

One or two sentences: what it does for the user.

**Behaviour**

- Observable rules, defaults and edge cases.

**Configure:** `yukta.example.setting` (default)

**Surface:** REST, MCP, CLI or UI entry points

**Source:** `ClassName`

**Limits:** Known gaps and ceilings.

​

Conventions

• IDs are permanent. GROUP-NN, assigned in order and never renumbered. Other pages, plans and reviews link to them.
• Card format. A card is a ### heading GROUP-NN: name followed by a **Status:** line. The status is one of stable, optional, partial, planned.
• Classes named in backticks in CamelCase (for example ExecutionScheduler) are checked against the source tree. Use the simple class name. Names that are not in the repository (JDK or library types) are listed in the script’s allow-list. Plain backticks are also used for settings, values, endpoints and anything not a class.
• Settings are written in full the first time (yukta.execution.queue-timeout) and may be abbreviated with … inside the same card.
• Defaults go in parentheses after the setting, or in the reference table; state “off” for disabled-by-default.
• One fact, one place. Describe behaviour in the card and link to it elsewhere with an in-page anchor link (the heading slug, for example #eng-04--failure-policy-engine-config); do not restate it.
• MDX safety. Put curly braces and < in backticks, escape \| inside table cells, and use {/* */} for comments.
• No SPDX header in .mdx files; they are covered by the docs/**/*.mdx annotation in REUSE.toml.

​

Checking for drift

# report drift between this page and the code
core/scripts/check-core-reference.sh

# after you have updated the page: record the commit and date it was verified against
core/scripts/check-core-reference.sh --stamp

• a backticked class name cites a class that no longer exists in core, plugin-api, workers, persistence-postgres, plugins, messaging, web or mcp;
• a yukta.* setting or meter string appears in core/src/main but nowhere on this page;
• a feature has a missing or duplicate ID, an unknown status, or a retired ID is reused;
• an in-page link (](#…)) points at a heading that does not exist.

​

Pull-request checklist for core changes

• Behaviour, default or limit changed: card and reference row updated
• New setting or meter: row added to the reference tables
• New class cited: the backticked name is the real class name
• Feature finished or removed: status or card updated, retired ID recorded
• core/scripts/check-core-reference.sh passes and --stamp was run
• core/CLAUDE.md updated if a build command or key location changed

​

Retired feature IDs

​

Glossary