Improvements

For each module: the evolution path (what the module is today and what to do next), the quality lenses (what limits it, what already helps and what needs design work), the open questions to settle, and the findings of its review that are still open. Individual weaknesses are on the Risks page and confirmed defects on the Bugs page.

​

Boot

​

Evolution path

Boot’s path is mostly about making the safe choice the default and proving the shipped artifact works.

1. Today. One process, loopback by default with a start-up guard, dev default on the JVM, prod forced on native, all plugins except script-js by default, in-memory state unless a persistence or workers build is chosen.
2. Safer defaults. Done: refuse to bind publicly without a key, guard /actuator. Next: fix the guard for the MCP-key-only case, guard or switch off Swagger, prod as the default profile, trim dev exposure. Risks: guardMcpKeyOnly, profileDefault, devExposure, openOps.
3. Verify the shipped artifact. Smoke-test the native binary and its profile; measure the build heap; make tests independent of plugin choice. Risks: nativeGap, xmx8g, testsNeedPlugin, profileForce, nativeMetaStale.
4. Persistent profile. A documented profile with file stores or a database, and clean-up of dead keys. Risks: singleProc, deadKeys.
5. Flexible packaging. Prebuilt plugin variants or a plugin directory for JVM builds. Risks: buildFixed, scanBroad.

​

Quality lenses

​

Questions to settle

• Security. The server is exposed on 0.0.0.0 with an API key and no profile. List what a stranger can read (hint: the docs), and what changes if only yukta.mcp.api-key is set. (risk openOps)
• Security. Which of our default settings would you change first to be safe in production, and what breaks for developers? (risk profileDefault)
• Scale. You must run three copies behind a load balancer. What does each copy hold that the others cannot see? (risk singleProc)
• Packaging. A customer wants a build without shell execution and without JavaScript. What do they type and what can they not change later? (risk buildFixed)
• Reliability. A native-only crash appears after a release. How would we have caught it? (risk nativeGap)
• Operability. An operator asks which plugins are in the binary. Where do they look? (risk scanBroad)
• Web. A client calls /apis/workflows by mistake. What does it get and is that fine? (risk apiPath200)
• Caching. We replace favicon.ico. When do users see it? (risk staticStale)
• Config. How would you prove every key in application.yaml is read by something? (risk deadKeys)
• Testing. Someone builds with -Pyukta.plugins=none. What tells them tests can’t pass? (risk testsNeedPlugin)

​

Build logic

​

Evolution path

Order is by cheap trust gains first: make what the build says true, then close bypasses, then make it reproducible, then speed it up.

1. Today. Six plugins, one catalog, 27 modules. Gates fail the build; OpenGrep needs the program installed; one coverage exception; no lock files; Netty now comes from the catalog; CI builds in four shards.
2. Make the docs and versions honest. Correct the docs from the code, delete the stale Netty line, fix the nashorn reason text, and decide whether pull requests should block on vulnerabilities. Risks: nettyTwoSources, docDrift, legalSignoff, trivyPrGate, cvePins.
3. Close the escape hatches. Guard every quality task against being disabled, fail on missing coverage data, burn down the three temporary disables, check build-logic itself. Risks: disabledTasks, coverageNoData, selfUnchecked.
4. Reproducible and visible. Commit lock files and turn on the CI check; warn when OpenGrep is skipped; add a toolchain resolver; align Node and pnpm in CI. Risks: noLockfiles, opengrepSilentSkip, noToolchainResolver, nodeDrift.
5. Faster and sharper. Run OpenGrep once with declared outputs, tune Error Prone and SpotBugs, generate the CI module map, and decide whether 100% per class stays. Risks: opengrepEveryModule, advisoryTools, ciManualMap, strict100, fullBuildOnRoot.

​

Quality lenses

​

Questions to settle

• Security. If the Netty override and the catalog disagree, how would you notice in a pull request, and what would you add to make it impossible? (risk nettyTwoSources)
• Security. Lock files are declared but absent. What would a locked build protect you from that BOM pinning does not? (risk noLockfiles)
• Operability. A new contributor never installs OpenGrep. What do you want to happen locally: nothing, a warning, an error, or an auto-download? (risk opengrepSilentSkip)
• Governance. Three modules disable some analysers with a ‘temporarily disabled’ comment. Who should own burning those down, and what would make the temporary disable expire? (risk disabledTasks)
• Correctness. 100% line and branch per class: what tests have you seen written only to reach a branch, and would you accept them? (risk strict100)
• Governance. Would you accept the nashorn-core exception for a native image without a written legal opinion? What is the smallest evidence you would want? (risk legalSignoff)
• Performance. Check time on a full repo is mostly waiting. Which gate would you measure first, and what would you change if OpenGrep were the slowest? (risk opengrepEveryModule)
• Evolvability. A new Checkstyle rule would fail 40 files in 10 modules. How should it be introduced without blocking everyone? (risk advisoryTools)
• Availability. GitHub or Maven Central is down for an hour. Which parts of the pipeline break, and which would you mirror first? (risk fullBuildOnRoot)
• Operability. If the CI module map were generated from settings.gradle.kts, what could still go wrong when someone adds a module? (risk ciManualMap)

​

Build logic review

The convention plugins are well layered (java, then spring, then library, with quality and jacoco mixed in), the version catalog is shared with the main build, and the quality toolchain is unusually complete: Spotless, Checkstyle, PMD, SpotBugs, Error Prone, a licence allow-list, OpenGrep and JaCoCo with a per-class exception DSL. The review of 2026-10-09 found weak points in policy and enforcement (gates that could not fail, coverage exception sprawl, a broad licence allow-list). All of them are fixed, and the gates now fail the build. What remains open is the supply-chain and housekeeping list below, checked against main after PRs #373, #374 and #391 on 2026-10-15. The ids below that start with BL- were assigned on this page; the source lists those items without ids. Open findings Pending roadmap steps All three roadmap phases are marked done. What is still pending is the tail of phase 2 and the open table above:

1. Get the legal sign-off for nashorn-core in the native image (L5).
2. Add lock files and a toolchain resolver (BL-1, BL-2).
3. Make Trivy block pull requests, or document why it does not (BL-3).
4. Clean the stale Netty line and the drifted documents (BL-4, BL-5).
5. Add a reminder to drop the CVE pins and make OpenGrep fail when its program is missing (BL-7, BL-6).

13 findings already fixed (L1 to L14, with L5 fixed in code and its legal sign-off listed above). Module guide: build-logic. Defect view: bugs.

​

CLI

​

Evolution path

A practical order: fix what misleads users first, then close the gaps to the server, then make the link to the server self-checking.

1. Today. Five command groups (about forty commands, including watch, result, node retry, breakpoint and signal), 100% function coverage, pinned tools, releases with checksums. The first page of every list, no retries, no resume.
2. Make it honest. Done: session apply is registered. Next: refresh the README, fix the root description, silence the duplicate error output, add yukta version, and test that every written command is registered. Risks: docsStale, errorNoise, noVersion.
3. Close the main gaps. Paging flags, stop mode, idempotency key, empty reason fix, and the commands still missing (validate, versions, approvals, scheduler limits and priority, recover, supervisors). Done: events (controlbus watch), node retry, breakpoint, signal, result. Risks: noPaging, stopMode, idemKey, emptyReason, missingCmds.
4. Robust in pipelines. Opt-in retries, stream reconnect with Last-Event-ID, distinct exit codes, consistent -o, token safety warnings. Risks: noRetry, streamLoose, outputUneven, tokenPlain.
5. Self-checking against the server. A contract test (real server or OpenAPI) in CI, a registration test over the command tree, and a move off deprecated paths. Risks: dtoDrift, legacyPaths, testsTwice, winBuild, fileOrJson, localTimestamps, keywordProblems.

​

Quality lenses

​

Questions to settle

• Scope. Is the CLI a full admin tool or a small CI helper? The answer decides whether the 12 missing endpoints matter. (risk missingCmds)
• Correctness. With more than 500 sessions, what should session list do? Truncate silently, warn, page, or fail? (risk noPaging)
• Security. Would you let a token go over plain http to a non-loopback address? What is the right default? (risk tokenPlain)
• Reliability. A pipeline starts a run and the call times out. What should it do next, and what does the CLI offer? (risk idemKey)
• Availability. The stream ends with no error and no final status. Is that success, failure or unknown? (risk streamLoose)
• Evolvability. How would you notice, today, that the server renamed a response field? Who finds out first? (risk dtoDrift)
• Quality. session apply was written, tested and promised by the README but not registered, and is registered now. What test would have caught it, and does one exist for the other commands? (risk docsStale)
• Operability. What exit codes would your automation want, and who should own that contract? (risk errorNoise)
• Governance. Where should the CLI documentation come from so it cannot go stale: Cobra itself, or the Makefile? (risk docsStale)
• Migration. The server plans to drop the session-qualified paths. What do you lose, and how would you keep the cross-session safety check? (risk legacyPaths)

​

CLI review

The CLI was a clean, thin REST client with robustness and build-hygiene problems, and all 13 findings of the review of 2026-10-09 are fixed: paths are escaped, non-streaming requests time out (--timeout, default 30 s), the client can send a bearer token and a start payload, tools are pinned and the build is reproducible, and the test-only interfaces and the 612-line mock are gone (main code went from about 3.7k to 2.9k lines, tests from about 11.5k to 8.0k, and build.gradle.kts from 578 to 48 lines). Since then the CLI gained controlbus watch, result, workflow node retry, breakpoint and signal, and session apply is now registered. What is open is feature parity with the server (paging, stop mode, idempotency, reconnect, and commands for newer endpoints) and a few rough edges. The scorecard after the fixes is command design 4.5/5, correctness 4.5/5, server parity 4/5, build 4.5/5 and tests 4.5/5. The ids below are assigned on this page; the source lists the open items without ids. Open findings Pending roadmap steps All four roadmap phases (safe requests, parity, reproducible build, trim) are marked done. The remaining work is the parity list above:

1. Add paging flags, a stop mode and an idempotency key (CLI-1, CLI-2, CLI-3).
2. Add retries and stream reconnect with Last-Event-ID, including for controlbus watch (CLI-4, CLI-5).
3. Add commands for the endpoints that have none (CLI-9) and a yukta version command (CLI-6).
4. Fix the README, the deprecated paths, the timestamp parsing and the keyword classifier (CLI-7, CLI-8, CLI-10, CLI-11).

13 findings already fixed. Module guide: cli.

​

Core

​

Evolution path

1. Today. One JVM. Files or PostgreSQL for definitions, sessions and log. Resume with file checkpoints.
2. Finish PostgreSQL (F10). Done: the checkpoint store in PostgreSQL (yukta.restart.store-type=postgres). Also done: KV_STORE in PostgreSQL and a CI step for the PostgreSQL acceptance test. Left: a PostgreSQL backend for session memory, claim-check references, native-image metadata. Risks: payload23.
3. Workers phase 1-2. Done: registry, agent, token auth, leases, remote processor over a stream with cancel and heartbeat, pool and free-slot choice. mTLS available.
4. Placement and failure. Pools, free-slot choice, local-only plugins, lost-worker retry, chaos tests. Risks: remote.
5. Operations. Worker UI, slot accounting, native image for workers.
6. Control plane HA. Done: active/standby with a PostgreSQL lease, a standby refuses starts, takeover recovers and resumes interrupted runs. Left: queued starts and live waits survive. Workers listing several control planes find the new leader by themselves. Risks: spof.

​

Quality lenses

​

Questions to settle

• Failure. One terminal fails while its sibling is slow. What happens to the sibling, and what is the run’s final status? (risk backpressure25)
• Scale. Your largest customer starts 5,000 runs in a minute with no limits set. What happens first, and what is the first graph you look at? (risk spof)
• Durability. You pull the power. Which approvals, queued starts and limit changes are gone, and do users find out? (risk signals14)
• Security. A workflow author is not trusted. Which three plugins must be unavailable to them? (risk remote)
• Evolution. The remote-workers design needs one decision reversed in a year. Which, and what does it cost? (risk remote)
• Performance. A message becomes 50 MiB. Which components copy it, how many times? (risk payload23)
• Control. An AI supervisor pauses a run you are debugging. How do you tell, and how do you stop it? (risk ctlKey)
• Data. A run was resumed after the definition was edited. Why is that refused, and is it the right call? (risk exactlyOnce22)
• Operability. Which three signals would page you at 3 a.m. today? Which are missing? (risk trackerQ26)
• Product. If sub-workflows power agents that plan their own DAGs, which limit breaks first? (risk gaps12)

​

Feature backlog

These are the features from the core review of 2026-10-12 that were reviewed but not (fully) built, in priority order. Statuses are as recorded in the backlog: open, partly done, done, needs decision. Rows marked done or partly done keep their history so the open remainder (after “Open:”) is clear. Bugs from the same review are on the bugs page. | ID | Status | Feature | Module | Notes | | F2 | partly done | WAIT_FOR_SIGNAL node + SignalNodeCommand (REST/MCP) are done, a signal that comes before the wait is kept (10 min, 100 at most), and the open waits are listed (GET /api/sessions/{s}/approvals, MCP list_pending_approvals, strip on the workflow page). Answers are remembered in the checkpoint store, so a resumed run does not ask again for an answered message. Open: the wait itself is in memory (a message that is produced again waits again; open waits are not listed until the node waits) | core, plugins, web, mcp, ui | See the core guide, section “Signals and approval steps” | | F3 | done | REST roles per key, actor key:<name>, hashed and rotating keys (sha256:<hex>, several at once), session-limited keys (sessions: /api/sessions/{s}/**, /api/workflow/{s}/** and the executions of those sessions), MCP roles per tool (McpToolAccess) and session scoping of MCP calls. The Control page lists who did what (GET /api/control/audit) | web, mcp, core | See the web guide | | F4 | partly done | Per-run token/cost budget on LLM_CALL, budget.hardStop (ends the run), the llm.budget.exceeded counter and yukta.llm.rate-limit.<provider> are done (see the core guide). RunBudgets is shared with MCP_TOOL_CALL (maxCalls) and a budget can name an agent. Open: token and cost meters, budgets for other plugins | llm-call, core | | | F5 | done | allowedTools on MCP_TOOL_CALL; gateway-level yukta.mcp-client.allowed-tools, max-argument-bytes, deny-argument-patterns; LLM_CALL filters yukta.llm.deny-input-patterns, deny-output-patterns (also the arguments of tool calls the model returns) and max-input-chars. MCP_TOOL_CALL requireApproval holds listed tools (or *) until a signal_node answers (approvalSignal, approvalTimeoutSeconds). Filters are patterns, not a classifier | plugins | | | F6 | partly done | SUB_WORKFLOW node and SubWorkflowGateway are done (see the core guide); a child borrows the parent’s slot and is cancelled with its parent node. Open: parent/child links in run history and the UI (today only the start payload carries yukta.parentExecutionId), runtime-generated sub-DAGs (plan from an agent) | core, plugins | Basis for runtime plans | | F7 | partly done | SESSION_MEMORY history is durable with yukta.session-memory.dir (atomic per-session JSON file, fsynced). KV_STORE and SESSION_MEMORY history can be backed by PostgreSQL (yukta.kv.store-type=postgres, yukta.session-memory.store-type=postgres with an optional yukta.session-memory.ttl). Open: session history has no eviction or TTL and loads whole files; no shared/vector memory for agents; a DB backend (see F10) | plugins | | | F8 | partly done | LLM_CALL tools option sends tool definitions and returns native tool calls in actions; messages turns can carry actions (assistant) and {role: tool, toolCallId, toolName, content}, sent as real tool turns; MCP_LIST_TOOLS follows nextCursor. Open: streaming, parallel tool calls policy, a ready-made agent-loop workflow example (not shipped: it needs a live model and MCP server to verify) | llm-call, mcp-tool-call | See the plugins guide | | F9 | partly done | Durable definitions, the newest 20 versions, GET .../versions, GET .../versions/diff, POST .../rollback, MCP list_workflow_versions/diff_workflow_versions/rollback_workflow and a Versions panel on the workflow page are done. Notes on versions (REST, MCP) and pinning a run (yukta.version in the start payload) are done. The Versions panel on the workflow page shows and edits the notes. Open: none | core, web, mcp, ui | See the core guide | | F10 | partly done | Restart spill (yukta.restart.spill-dir) landed; a RESUMABLE status was skipped on purpose (ABORTED is the resume candidate, a new value would spread into web/UI status vocab). persistence-postgres (R2DBC at run time, Flyway over JDBC for the schema; user decision) backs sessions, workflow definitions + versions and the execution log; tested with Testcontainers and a full-app test. The node checkpoint store in PostgreSQL is done (yukta.restart.store-type=postgres; large messages rely on TOAST, so no separate claim-check yet). Open: PostgreSQL backends for KV_STORE/session memory, idempotency keys already ride the log, (a CI step runs the PostgreSQL acceptance test with -Pyukta.persistence=postgres) native-image reachability metadata for R2DBC/Flyway, connection-pool tuning and health checks, row-level retention for session configs, Flyway license check before distribution (Community edition, allowed per artifact in the build conventions) | new module | Prerequisite for HA | | F11 | phases 1, 2, part of 4 and 6 done | Remote workers (decision: control plane schedules nodes, workers run them). Design and phases in the remote workers plan; phases 1 and 2 are built (registry/agent/leases and remote processor execution with engine.placement, workers module, -Pyukta.workers=true); open: operations (UI list, remote slots in max-concurrent), (workers following the leader: done). Waiting on the open decisions at the end of that document (transport, packaging, secrets, first plugins, payload limit); control plane HA is phase 6 | messaging, core | Large | | F12 | open | Saga compensation, node result caching, A2A agent card, eval/scoring node, backfill, run history search (done for one session: GET /api/workflow/{s}/history?workflowId=&status=&text=&since=&until=; GET /api/executions?... across sessions), MDC log correlation, Vault secrets, yukta.restart.auto-resume | various | Pull in on demand | | F13 | needs decision | Trace id in the progress snapshot (REST/SSE/MCP). Needs micrometer-tracing on the core classpath, which core does not depend on; MDC was dropped on purpose (structured key-values carry executionId/nodeId) | RunTelemetry, WorkflowProgress | Add the dependency only if a tracing backend is used in production |

​

MCP

​

Evolution path

A suggested order, driven by risk rather than by size. The first steps are small and close the largest exposures.

1. Today. 23 tools, stateless /mcp, the same named keys and roles as REST (optional), per-tool role check, session-limited keys, ownership check, bounded log reader with a cursor, polling for progress.
2. Close the cheap gaps. Done: refuse non-loopback without a key. Next: make one setting cover REST and MCP, add idempotencyKey, payload and stop mode to the tools, fix both creation guides and test them, show config fields and config-aware ports in plugin details. Risks: apiKeyOpen, noIdempotency, stopParity, sessionGuideWrong, pluginGuideWrong, portsNoConfig, configSchemaHidden.
3. Know who is calling. Done: named keys with roles, sessions and an actor. Next: a rate limit, a log or counter for rejected calls, and a test that the role map covers every tool. Risks: noActor, noRateLimit, bodyReparse, rejectsUnlogged.
4. Safer authoring and reading. Overwrite flag and dry-run for create_session. Mark log lines as data. Paging for history, sessions and logs. Risks: overwriteSession, logInjection, noPaging.
5. Live and cheap status. A one-pass summary in core for the status tool. A way to wait for or subscribe to changes, so agents stop polling. Risks: healthLinear, noPush, signalNotState.
6. Keep it honest. Generate the tool table from annotations in a test, add a parity check with web, re-enable PMD on tests. Risks: docsDrift, pmdTestOff.

​

Quality lenses

​

Questions to settle

• Security. Today the endpoint is open and relies on a loopback bind. Is that an acceptable default for a tool that can install command-running workflows, and what is the smallest change that makes it safe? (risk apiKeyOpen)
• Identity. If an incident happens, how would you tell whether an agent or a person stopped a run? What would you need to add? (risk noActor)
• Trust boundary. Access is decided by a filter that reads the request body before the MCP runtime does. What could make the two readings differ, and what would you test? (risk bodyReparse)
• Failure. An agent’s start_workflow call times out. What should it do next, and what could it break by doing it? (risk noIdempotency)
• Prompt injection. A plugin logs text from an external web page. How could that text change what the agent does next? (risk logInjection)
• Design. Is it right for the tool description to carry the safety rules (confirm first), or must the server enforce them? (risk overwriteSession)
• Scale. You have 500 sessions and 20 agents polling the status tool every 5 seconds. What breaks first? (risk healthLinear)
• Protocol. What would you give up, and what would you gain, by moving to a stateful transport for live progress? (risk noPush)
• Quality. How would you test that the creation guide stays valid when the plugin API changes? (risk pluginGuideWrong)
• Operations. A control call says ‘Pause signal sent.’ When is it safe for the agent to assume the node is paused? (risk signalNotState)

​

Messaging

​

Evolution path

1. Today. One immutable envelope, one pass-through channel, core stamps history and routes by port. Several fields carried but unused.
2. Decide the unused fields. For each unenforced field choose: enforce it (for example an expiry check), or remove it. Make from and withPayload use one copy path. Risks: unenforced, copyDrift, wideContract.
3. Define the channel contract. Write what a channel may do on failure, how it signals slowness, and fix the registration through auto-configuration. Done: a skipped processor now goes through the channel too. Risks: channelErrors, conditionalOrder, edgeDropsUnseen.
4. Payload model. Choose a payload story: a canonical JSON tree, an optional schema, and a claim check for large bodies. Risks: payloadSize, untypedPayload, shallowImmutable.
5. Better lineage. Carry history through split and aggregate, record truncation, and add a per-output id if needed. Risks: historyCap, lineageReset, idNotUnique.
6. A real second channel. Build one durable or remote channel to prove the SPI, and trusted-header rules for it. Risks: remoteSpi, forgeable, wireFormat.

​

Quality lenses

​

Questions to settle

• Evolution. Name one field of the envelope you would delete today, and one you would enforce. What breaks for each? (risk unenforced)
• Scale. If the SPI had to carry messages to another machine, which five questions must its contract answer first? (risk remoteSpi)
• Correctness. A plugin mutates a list inside its payload. Which other branches can see it, and when would anyone notice? (risk shallowImmutable)
• Performance. A message becomes 50 MiB. Which components copy it, and which only pass a reference? (risk payloadSize)
• Security. Which headers can a malicious plugin set that an operator would trust, and which should core re-stamp? (risk forgeable)
• Operability. You debug a message that went through 80 nodes. What can you still see in its history, and what can you rebuild from elsewhere? (risk historyCap)
• Failure. A custom channel throws on one message. What does the user see, and which component should decide? (risk channelErrors)
• Design. After a split, is each child the same message or a new one? What should its history say? (risk lineageReset)
• Evolvability. Is the 40-method interface worth keeping if only one implementation will ever exist? (risk wideContract)
• Operability. How would you know which channel provider is active in production, and how would two providers be diagnosed? (risk conditionalOrder)

​

Persistence PostgreSQL

​

Evolution path

1. Today. Nine tables, seven stores, a lease. Statements are single and safe; recovery rewrites and multi-step operations are not atomic; the fencing number is unused.
2. Make recovery safe. Transactional rewrite of the log, durable start and end events, transactions for the multi-step operations. Risks: logReplaceAll, logDropsEvents, noTransactions.
3. Fence the leader. Pass the fencing token to the writes that matter and refuse older tokens in the statement. Risks: fencingUnused.
4. Index and bound. Index the event type and update time, stream the reads, make the KV cap and the clean-up honest, add a session delete. Risks: compactionCost, readsWholeSets, historyTtlScan, kvCapRace, noDelete, noRetention, sessionConfigGaps.
5. Observe it. Meters and a health check for the stores, a startup summary of which store is used, honest counters. Risks: noStoreMetrics, halfDurable, heldBytesDrift, blockingCalls.
6. Operate it. Separate accounts, an upgrade test on data, a documented backup and restore. Risks: twoConnections, noMigrationPlan.

​

Quality lenses

​

Questions to settle

• Failure. The server dies between the delete and the last insert of replaceAll. What can an operator still do, and what would they have needed? (risk logReplaceAll)
• Reliability. The log queue is full for ten seconds. Which events are lost, and which of them matter most? (risk logDropsEvents)
• Availability. A leader freezes for 40 seconds with a 15 second lease. Walk through what each server does when the leader wakes up. (risk fencingUnused)
• Correctness. An operator applies a session with twelve workflows and the database restarts after the sixth. What does the session look like? (risk noTransactions)
• Performance. A run has 400 nodes and the database answers in 50 ms. What does a resume cost in waiting time? (risk blockingCalls)
• Scale. You keep 500 runs of 5,000 events. What happens on each trim, and what happens to the queue meanwhile? (risk compactionCost)
• Operations. How would you tell, from the running system, which kinds of state are durable? (risk halfDurable)
• Privacy. A customer asks you to delete everything about one session. What do you run? (risk noDelete)
• Evolution. You rename a field of the workflow definition record. What happens to the stored definitions? (risk noMigrationPlan)
• Security. Which database account does the application use, and what can it do that it should not? (risk twoConnections)

​

Plugin API

​

Evolution path

A suggested order. Step 1 comes first because it protects the ability to stop a run.

1. Today. A small, working SPI with 16 commands, a supervisor and control-plane SPI, an expression sandbox with a method allow-list, and shared helpers for run budgets and approval waits. Open work is mostly bounds on control calls and expressions, decoupling plugins from core, and tooling for authors.
2. Bound the control path. Add review and decide timeouts with a defined outcome, protect stop from being delayed, and align the two ordering rules. Risks: reviewNoTimeout, decideStall, orderOpposite.
3. Make plugins independent of core. Move the resolver and map helpers into plugin-api or a support module, expose the registry and tracker through small SPIs, and add an SPI version with a startup check. Risks: coreDependency, noVersion.
4. Tools for plugin authors. Ship test fixtures with a conformance suite, re-enable PMD for tests, and either call shutdown or remove it. Risks: noTestKit, sharedInstance, pmdOff, shutdownNever.
5. Harden expressions and secrets. Evaluation time budget (the method allow-list is done), parse outside the lock, a run budget that is reserved before the call, scoped and audited secret access, and a data-only UiDesign. Risks: spelLimits, secretThin, uiHtml, budgetLedger.
6. Typed and reactive extension seams. Non-blocking store calls (the PostgreSQL stores now make this concrete), declared node signals, and a decision on the directive layer and the unused optimiser hooks. Risks: storeSync, onSignalLoose, directiveOnlyStop, deadHooks, eventsBestEffort, signalWaitsShared.

​

Quality lenses

​

Questions to settle

• Availability. A supervisor’s review calls a slow policy service. What should happen to a human’s stop command while it waits? (risk reviewNoTimeout)
• Evolvability. You must add a 17th control command. List everything in the repository that breaks and decide if that is a feature or a cost. (risk directiveOnlyStop)
• Correctness. Write the smallest test that proves a plugin is safe to share between two nodes with different configs. (risk sharedInstance)
• Security. Name three expressions you would try against the sandbox that are not in the tests. Which layer would stop each? (risk spelLimits)
• Reliability. A rule must pause a workflow after 3 failures but the feed drops under load. How would you guarantee it? (risk eventsBestEffort)
• Evolvability. An external team wants to ship a plugin as a jar. Which parts of today’s contract and dependencies would stop them? (risk coreDependency)
• Performance. A PostgreSQL checkpoint store answers isFinished in 5 ms. What does that cost a resume of a 200-node run? (risk storeSync)
• Functionality. How would an agent discover that a plugin accepts an ‘approve’ signal and what payload it needs? (risk onSignalLoose)
• Security. Two teams share one server. How would you stop team A’s plugin from reading team B’s secrets? (risk secretThin)
• Operability. Which lifecycle hook should release a database pool, given that shutdown is never called? (risk shutdownNever)

​

Plugins

​

Evolution path

A possible order of work, safest edges first.

1. Today. 31 node types and four supervisor kinds on one JVM. Done since the first guide (PRs #373, #374): script sandbox with class allow-list and limits, command allow-list, env allow-list, restricted SpEL methods, LLM and MCP budgets, provider rate limit, tool approvals, PostgreSQL stores for KV_STORE and SESSION_MEMORY. Open: no host allow-list, plaintext secrets in config, no concurrency cap, memory-only defaults.
2. Contain the sharp edges. Done: script sandbox, command allow-list. Next: operator-set host and folder allow-lists, a max-concurrency setting, kill descendant processes on timeout, redact secrets in read APIs, make the agent guards a deployment default. Risks: scriptHostAccess, ssrf, shellModel, orphans, fanout256, plaintextSecrets, fileSandbox, agentGuardsOptIn.
3. Bound memory and cost. Evict caches and sessions, put LLM-backed decisions under the run budget (LLM_CALL and MCP_TOOL_CALL already are), derive timeouts for SQL and file plugins, add a connection pool, take SESSION_MEMORY off the reactive threads, truncate logged output. Risks: unboundedMaps, sessionMemory, sqlTimeout, consoleLogs, sessionStoreBlocks.
4. Make state durable. Done: PostgreSQL stores for KV_STORE and SESSION_MEMORY (opt-in). Left: make them the default or warn when memory-only, durable anomaly windows, a persistent scheduler, rules that reload. Risks: kvVolatile, windowsPerRun, scheduleLost.
5. Clean the layering. Move the resolver and helpers into plugin-api, validate loop targets, re-enable the gates, rename CONTENT-FILTER with an alias, make control planes optional. Risks: coreLayering, gatesOff, loopSkipsValidation, loopEscalate, typeIds, optionalNotOptional.
6. Decide the oversight model. Alert on ‘no opinion’ from the model plane, prefer rules-first, treat model verdicts as advice. Risks: modelFailsOpen, promptInjection.

​

Quality lenses

​

Questions to settle

• Security. If a workflow author is not fully trusted, which plugins would you remove from the build and which would you keep behind allow-lists? (risk scriptHostAccess)
• Security. Where should the host allow-list live: in each plugin’s config, a deployment setting, or the network around the server? (risk ssrf)
• Scalability. What is the right default concurrency for a plugin that starts a program, calls a model, or reads a file, and who should set it? (risk fanout256)
• Evolvability. Is the ‘typed spec, gateway, failure mode’ pattern worth extracting into a base class, or does that hide the differences between a process, a web call and a tool call? (risk coreLayering)
• Reliability. Which of KV_STORE, SESSION_MEMORY, ANOMALY windows and schedules deserve durable storage first, and what would break without it? (risk kvVolatile)
• Governance. Should a model be allowed to spend money without a cap, and what is the unit of a budget: tokens, cost, calls or time? (risk decisionUnbudgeted)
• Security. Which verdicts in your workflows would hurt if an attacker could choose the answer, and should those use a model at all? (risk promptInjection)
• Availability. When the model control plane is down, should the system keep running unattended, or stop? (risk modelFailsOpen)
• Functionality. Should a loop be a plugin that calls other plugins, or a real sub-graph in the engine? (risk loopSkipsValidation)
• Operability. What should be in the logs for a failed external call: nothing, a summary, or everything the process printed? (risk consoleLogs)

​

Plugins review

The nine built-in plugin modules cover a useful set: triggers (API, one-shot, constants), routing (branch, recipient list, splitter, filter), transformation (mapper, content filter), loops, process execution, HTTP, LLM calls and chat memory, and the newer plugins are carefully written, with typed config records, explicit failure modes, port routing, output caps and good usage text. The plugin layer is also where user-supplied workflow config becomes executed code, and the review of 2026-10-09 found the guard-rails missing: two code-execution paths (SpEL and the mapper’s JavaScript), unbounded process concurrency, no way to pass a secret, quality gates switched off in internal-core, and plugins that depend on :core instead of only on plugin-api. The status on 2026-10-15 (checked against main after PRs #373 and #374) is that the two code-execution paths are mostly closed, secrets are partly addressed, and the resource, layering and gate findings are largely still open. The review’s original scorecard rated security 1/5, resource safety 2/5, layering 2/5 and quality gates 2/5. Priority is P0 (fix now) to P3 (clean-up); effort is S (under half a day), M (1 to 2 days) or L (over 2 days). “Not re-checked” means the finding comes from the original review and may have changed. Open findings Pending roadmap steps The status section of the review gives this suggested order for the next steps (impact over effort, cheap and high impact first); the original five-phase roadmap is otherwise unchanged:

1. sessionStoreBlocks: one line plus moving the store call out of the map operation.
2. G7 host allow-list, together with agentGuardsOptIn (warn when an MCP tool name comes from the message and no list is set).
3. G5 redaction in the read APIs, and resolving decrypted: in SQL_QUERY.
4. G8 and G9: a maxConcurrency setting and descendant kill on timeout.
5. decisionUnbudgeted and the plugin-api budgetLedger: count every model call once, in the gateway.
6. G18: move VariableResolver and MapUtils out of core.

1 finding already fixed (G6, the variable resolver now reads only an allow-list of environment variables). G1 and G2 are mostly closed and stay in the table with what remains. Module guide: plugins. Defect view: bugs.

​

UI

​

Evolution path

1. Today. A same-origin SPA served by boot. Streams and REST work with no key. Builder, plugins, history and control pages exist; unit tests run only by hand.
2. Make it usable on a protected server. Choose a browser auth model, make fetch and the streams carry it, and show a clear ‘sign in’ state instead of ‘server not running’. Risks: noAuthHeader.
3. Safer actions. One idempotency key per click, no automatic retry of non-idempotent calls, per-run stop modes, a draft guard and a version check on save. Risks: startRetryKey, stopAllRuns, noDraftGuard, wholeSessionSave.
4. Use the event model fully. Resume streams with Last-Event-ID, switch to /api/executions/… paths and drive the Control page from the global event stream. Risks: replayNoLastId, logDedupe, legacyAliases, pollControl.
5. Tighten the contract. When core publishes a status enum, generate unions, take icons from plugin metadata and run the unit and type-drift checks in CI. Risks: freeStatus, iconGap, noTestGate, deadSanitiser.
6. Close the REST gap. Add delete, run search, paging and resume as operators ask for them (approvals and versions are done). Risks: uiGaps, pagingCaps.

​

Quality lenses

​

Questions to settle

• Security. Your server is exposed to the team and a key is required. Walk through what the first screen shows and how an operator recovers. What would you build? (risk noAuthHeader)
• Reliability. A start request times out in the browser but the server accepted it. What does the user see, how many runs exist after the retry, and how would you prove it? (risk startRetryKey)
• Performance. A run has produced 200,000 log lines and the connection drops every minute. What does each reconnect cost the server and the browser? (risk replayNoLastId)
• Correctness. Core adds a status WAITING_APPROVAL. Which screens change meaning, and how would you find out before a user does? (risk freeStatus)
• Operability. Two operators press Drain on the same workflow while a third is debugging a run of it. Who is surprised, and what should the dialog say? (risk stopAllRuns)
• Data. Two people edit different workflows of one session. Whose change survives, and where would you add the check? (risk wholeSessionSave)
• Scale. Fifty operators leave the Control page open all day. What is the steady load, and would you move to events or slow the poll? (risk pollControl)
• Governance. A UI regression ships that only a unit test would catch. Which gate should have stopped it? (risk noTestGate)
• Product. A plugin author wants a custom icon and a rich node card. What belongs in the plugin’s metadata and what in the UI, and is rendering their HTML ever acceptable? (risk deadSanitiser)
• Evolution. The server drops its legacy /api/workflow/… status paths next release. What breaks first, and how would you notice in CI? (risk legacyAliases)

​

UI review

The UI is a modern, well-tested SPA: feature folders with separate api, hooks and components, TanStack Query for fetching, React Flow with dagre for the DAG canvas, SSE hooks for live progress and logs, shadcn and Base UI primitives with Tailwind 4 tokens and dark mode, Vitest at about 98% coverage, Playwright end-to-end tests with screenshot baselines, and DOMPurify on plugin-provided node HTML. The review of 2026-10-09 found payload weight (a 3.96 MB icon font and one 887 KB script chunk), live views that stopped silently on the first stream error, wrong API error text, and a guessed status vocabulary. After the fixes the icon font is 11 KB, the largest script chunk is 273 KB, streams reconnect with backoff, server messages reach users, and the types are generated from OpenAPI with a drift guard in the build. All twelve findings (U1 to U12) are resolved; the roadmap’s four phases are done and nothing is pending from the review. The one remaining caveat is that statuses stay free-form strings until core adds a status enum. Open work for the module is tracked as risks: see the UI risks. Module guide: ui. 12 findings already fixed.

​

Web

​

Evolution path

A suggested order, from cheap and safe to large. Each step names the risks it addresses.

1. Today. 16 controllers, four filters, one error handler. Loopback bind with a start-up guard, named keys with roles and session limits. Streams with ids and a heartbeat. Cursor paging over full lists. Run search, control audit and version endpoints added. Tests for every controller, mapper and filter.
2. Close the doors. Done: fail closed when the address is open and no key is set (but see the MCP-key case), guard the actuator. Next: guard or drop the docs, let the UI send the key, log and count rejected requests with a request id and the key name. Risks: openByDefault, uiNoKey, silent401.
3. Make the contract honest. Add a 409 for conflicts; stop the three local catches; validate and record limit changes; unify the edge-port default; apply ownership checks on the canonical routes and add a session filter to the events stream. Risks: noConflict, localCatch, limitsEndpoint, mapperDrift, ownershipGap.
4. Scale reads and streams. Page in the store; give log lines durable sequence numbers; tell slow readers they missed events; cap streams, rate and body size. Risks: pagingLinear, logSeam, slowReader, noLimits, searchScan.
5. Identity and operations. Done: named keys, roles, session limits, hashed keys. Next: expiry and revocation without a restart, the key name in the access log, a per-key rate limit, or an identity provider; masked secrets in read APIs. Risks: staticKeys, configUnredacted.
6. Retire aliases and dead code. Move the CLI and UI to canonical routes, remove the 14 aliases, delete the unused records. Risks: legacyAliases, deadDtos.

​

Quality lenses

​

Questions to settle

• Security. Roles now separate reading, running and authoring. Which key should be allowed to submit a workflow that can run a program, and should an OPERATOR key be able to? (risk staticKeys)
• Security. A container is started from the published image with no configuration. What stops a stranger on the same network from running code, and is that enough? (risk openByDefault)
• Security. Session ids look like tenant boundaries but the checks only run on some routes. What should a session mean to security? (risk ownershipGap)
• Reliability. A UI shows ‘running’ while the run actually finished, because the event was dropped for a slow tab. Where should the truth live? (risk slowReader)
• Correctness. Two log lines with identical text arrive within the same millisecond around a connect. Which one should a viewer see, and how would you prove the stream correct? (risk logSeam)
• Performance. A session has 200,000 runs of history. What does the 200th page of 500 cost, and what would you change first? (risk pagingLinear)
• Operability. On-call sees a spike of 500s. How would you tell conflicts from real bugs with today’s mapping? (risk noConflict)
• Governance. Limit changes are now admin-only, audited with the actor and restored on restart. Should there be a floor, so that one call cannot set ‘no limit’? (risk limitsEndpoint)
• Evolvability. The CLI uses the old routes and the UI the new ones. How do you migrate without breaking either, and what do you lose if the old routes carry the only ownership check? (risk legacyAliases)
• Availability. A client opens a thousand log streams and never reads them. What happens to memory, and what should the server do? (risk noLimits)

​

Workers

​

Evolution path

1. Today. Placement by pool, free-slot choice, leases, drain, retry on another worker, optional mutual TLS, failover across several addresses. In-memory registry; plain TCP and one token by default.
2. Make the link trustworthy. Require TLS off loopback, per-worker credentials mapped to ids, and a decision on where secrets are resolved. Risks: plainTokenDefault, sharedTokenIdentity.
3. Failover that works in the bad case. Check leadership on every lease, reset the reconnect pause, close stale connections. Risks: deposedKeepsWorkers, reconnectBackoff, staleConnections.
4. Make a placed node behave like a local one. Map errors back, forward the log sink and trace context, count budgets on the control plane, enforce capacity, mark stateful plugins. Risks: abortLostAcrossWire, liveLogsLost, noTraceContext, budgetPerJvm, capacityRace, statefulPlacement, perAttemptInit.
5. Handle data and upgrades. A payload limit with a reference above it, a protocol version and a compatibility test. Risks: payloadAsJson, wireVersion.
6. Verify the native path. A native registration test in CI and a clear failure when the role switch is missing. Risks: nativeUnverified.

​

Quality lenses

​

Questions to settle

• Security. A device on your network can reach the control plane’s RSocket port. List what it can learn and what it can make a worker do. (risk plainTokenDefault)
• Identity. One worker is compromised. How do you cut it off without restarting the others? (risk sharedTokenIdentity)
• Availability. The leader loses its database lease but keeps running. Where do the workers end up and when do placed nodes work again? (risk deposedKeepsWorkers)
• Availability. A control plane has restarted five times this week. What is the pause before a worker reconnects after the sixth? (risk reconnectBackoff)
• Correctness. A placed LLM_CALL node hits a budget with hardStop. What does the run do, and what does it do for a local node? (risk abortLostAcrossWire)
• Governance. A run uses three workers and has a token budget of 100,000. How much can it spend? (risk budgetPerJvm)
• Operability. Someone asks to watch a placed build step live. What do they see? (risk liveLogsLost)
• Scale. A placed node returns a 200 MiB file. Which components hold it, and how many times? (risk payloadAsJson)
• Evolution. You change a field of the message record. In which order do you upgrade the control plane and the workers, and what breaks in between? (risk wireVersion)
• Design. Which of your plugins keep anything between messages, and is it safe to place them? (risk statefulPlacement)