Coding is workflows too.

The substrate didn't have to learn anything new.

For most of its life Safebox operated on what you'd call ordinary data. Emails arriving at a community inbox. Jobs queued for processing. Posts and articles materialized from external feeds. Calendar events, customer records, conversational messages. The verbs were ordinary too: route, summarize, schedule, file, answer.

Then we pointed it at code. Specifically, we pointed it at a Qbix codebase that Grokers had already indexed — every function, method, and class extracted into a Grokers/symbol stream, every call site into a Grokers/calls relation, every cross-language event hook into a Grokers/extern bridge node. The codebase, in other words, became a graph in the substrate's existing stream model. The act of writing code didn't change. The representation of code did.

What we discovered was that Safebox's machinery — workflows, tools, capabilities, action proposals, governance gates, judgment dispatch, audit chains — operated on this graph identically to how it operated on email or jobs. The verbs changed (modify, rename, split, document, test) but the verb framework didn't. A workflow that modified a function looked structurally indistinguishable from a workflow that filed a customer support ticket. Both forked a workspace. Both proposed actions. Both passed through the same governance. Both produced the same audit chain.

This is the realization that organized everything that follows. Workflows aren't a user-data abstraction. They're a coordinated state abstraction, and code is just another kind of state that needs coordinating. Once Grokers turned code into structured graph nodes, the rest was already built.

Modify a function. The same way you'd file a ticket.

Start with a concrete example: change the signature of a function whose callers are spread across several files. The classic refactor. In a swarm-of-agents architecture this is improvised — one agent reads the target, another reads the callers, they share notes through chat, they hope nothing was missed. In Safebox the same task decomposes into a workflow with explicit steps and tools.

Every step composes existing primitives. Forking workspaces, proposing actions, walking relations, dispatching judgments, taking snapshots, posting messages — all of it was already in the substrate before we pointed it at code. The verbs are new. The machinery isn't.

Sequential agent loops dress up improvisation as autonomy. Workflows make the same work auditable, governed, and parallel-safe — without taking the human out of the loop.

Verification, ripple, and the absence of magic.

The hardest part of any refactor isn't writing new code. It's making sure the new code keeps the promises the old code was making — and finding everything else that breaks if it doesn't.

Every function that Grokers analyzes carries a structured contract: Grokers/preconditions (what must be true to call it), Grokers/postconditions (what's true after it returns), Grokers/sideEffects (what it changes outside its own scope), Grokers/invariants (what holds throughout). These are prose, written by the analyzer during the comprehension pass. They're not formal logic — they're claims a careful reader could verify against the source. Their value isn't in being theorem-checkable; it's in being explicit, so downstream workflows can reason about whether they still hold.

When a workflow proposes a refactor, the verification step doesn't just run tests. It re-derives the contract from the new source and compares against the old contract. Three classifications fall out, and each routes to a different downstream behavior.

The third case is where the architecture earns its complexity. Without explicit contract checking, a refactor that subtly weakens a postcondition propagates the weakness into every caller silently. With it, the workflow surfaces the change, walks the callers, and either fixes them or escalates. The recursion is bounded because the call graph is a directed acyclic graph (Grokers handles cycles separately as concepts to investigate). Most ripples terminate within two or three levels.

Documentation is part of the contract.

When the contract changes, the docstring is wrong by the same change. The code/proposeRewrite tool produces the new source and the new docstring as a coupled output — they're not separable artifacts. Verification then checks both. And critically, when the docstring needs updating in callers (because the caller's docstring references the called function's behavior), that update is targeted: edit the two sentences that became wrong, leave the rest of the prose alone. Reviewers see meaningful diffs, not stylistic churn.

Tests come along for the ride.

A function with associated tests has Grokers/covers relations from Grokers/test streams pointing at it. When the workflow finishes the rewrite, the verification step runs those tests against the new source inside the workspace clone. If they pass, the contract was probably preserved correctly. If they fail, the workflow either retries the rewrite with the failure as additional context (bounded retries), or marks the existing tests as themselves needing update — which kicks off a code/test sub-workflow whose contract is "produce a test that exercises the new behavior, verify it actually exercises the symbol via mutation testing, register it."

Conventions and Grokers hints feed in at every step.

Two layers of grounding make the LLM's proposals match the codebase rather than match the LLM's training corpus.

Conventions are governed substrate streams of type Safebox/convention, with an appliesTo attribute marking the contexts where they apply — code-style/php, code-style/js, tool-generation, prompt-assembly, and so on. Some are mechanical: tabs versus spaces, brace placement, identifier casing, line-length norms. Others are idiomatic: this codebase prefers callbacks over Promises in async paths, errors are returned as tuples rather than thrown, validation lives in handlers not models. Grokers extracts the mechanical ones during indexing automatically. The idiomatic ones are LLM-inferred during the comprehension pass and proposed for human approval before being injected into rewrite prompts. Conventions can be added, edited, voted on, and superseded the same way any other governed stream can.

Hints are framework-specific patterns Grokers recognizes during analysis. The Qbix indexer ships hints files that pre-confirm patterns like "Q::event(name, params) is a hook fire — bind the params to the named hook," "Q.batcher wraps a function in batching — its callers receive arrays not individuals," "Q.Method is a lazy-load stub — the real implementation is in a sibling file." These hints feed into the prompts the rewrite tool assembles, so when the LLM is asked to refactor a function that interacts with a framework convention, it starts informed rather than inferring from scratch.

Together, conventions plus hints mean the LLM is reasoning in a context where most ambiguity has already been resolved. The codebase's style is a fact; the framework's idioms are facts; the analyzed contract is a fact. The LLM's job is to write code that respects the facts. The verification step catches the cases where it didn't.

Two layers of state, with clear ownership.

The substrate's stream layer captures the symbol-level changes — what a function used to be, what it now is, who proposed the change, which tests verified it, which judgment voted to allow it. Below that, two more layers of state need to exist for code to actually compile, link, and ship.

ZFS as the workspace's filesystem reality

A workspace fork in the substrate is a logical claim — "this branch of state diverges from base here." That claim has to land somewhere on disk if the workflow is going to run tests, invoke compilers, or produce binaries. ZFS clones provide this naturally. When the substrate creates a workspace stream, a Safebox hook takes a ZFS snapshot of the relevant dataset and clones it to a writable mountpoint. The workspace's filesystem operations happen in that clone. The base dataset is untouched.

ZFS is the right choice for three reasons. Snapshots are atomic and cheap, so taking one at workflow start adds no measurable latency. Clones are copy-on-write, so two workspaces forked from the same base share storage until one of them writes, which means parallel workflows don't multiply disk usage. And destruction is instantaneous: when a workflow fails verification and the workspace is closed, the clone is gone and the base is exactly as it was. Failed workflows leave no filesystem residue.

What ZFS handles that the substrate alone cannot: large binary blobs that don't belong in stream rows (compiled artifacts, model weights, image assets), database state that needs to be snapshotted alongside the code (test fixtures, migration baselines), and test suite outputs that benefit from being captured as part of the same atomic snapshot as the code that produced them.

An obvious-looking shortcut — symlinks plus moves to fake snapshots on hosts that don't run ZFS — is worth ruling out explicitly. It doesn't work. Atomicity is fake (mv plus symlink is many operations, not one), tools that resolve paths produce surprises (some test runners write outputs to the symlink target's directory, contaminating the supposed isolation), and inode-level operations behave wrong (file watchers see two different files where there's logically one). The architectural alternatives where ZFS isn't available are btrfs subvolumes (closest equivalent, same copy-on-write semantics) or plain copy-on-fork (full duplication per workspace, expensive on disk but semantically clean). Symlink hacks are the worst option of the three.

Symbol-canonical, not file-canonical.

One detail of how the substrate represents code matters enough to call out. The canonical state of a function lives in its Grokers/symbol stream — the source text is the stream's content; the contract is its attributes. The file on disk is a derived artifact, assembled from symbols in their declared file-order plus the non-symbol regions between them (imports, top-level declarations, comments outside any symbol). Line numbers are not stored on symbol streams. They're computed when needed, from the file's current content inside the workspace clone.

This matters because it means modifying one symbol doesn't require updating every other symbol in the same file. The substrate doesn't have to ripple line-number changes through all the unaffected symbols every time a refactor shifts source positions. The shift exists in the file as a consequence of the splice, but it isn't substrate state. When a workflow finishes, the workspace's modified files get re-grokked (call site line numbers stored as Grokers/calls relation weights are updated), but the substrate doesn't carry stale line numbers between operations. The symbol is canonical; the file is the projection of the symbols at any given moment; line numbers are properties of the projection.

Git as one-way push projection

Humans expect to review code changes in git. Pull requests, branch comparisons, blame, history. Safebox accommodates this by treating git as a projection layer — a one-way export of completed work to a system humans operate. Each successful workflow that touches a git-tracked codebase produces a branch on the upstream remote. The branch's commit message references the workflow's audit chain so a reviewer can trace any line of code back to the workload that proposed it, the judgments that voted on it, and the tests that verified it.

The relationship runs one direction. Safebox pushes to git; it does not pull. This is a deliberate architectural commitment, and it's worth being explicit about why. If Safebox pulled from upstream, the substrate would have to reconcile its view of the codebase with whatever changes humans (or other Safebox instances) made independently. Reconciliation is a hard problem in distributed systems generally and a wickedly hard problem when one side of the merge is a structured graph and the other is text diffs. Forward-only avoids it.

The cost: the substrate's view of the codebase can drift relative to upstream. The benefit: the substrate's view is always internally consistent, and any branch it produces is grounded in a known-good baseline. When drift becomes a problem operationally — upstream has moved on, the substrate's grokked view is stale — the operator clones upstream again at a new commit. A new Grokers/repo stream comes into existence; Grokers indexes it; new workflows fork from the new baseline. Old workspaces remain queryable as historical record. Three operations — initial deployment, periodic refresh, historical analysis — all collapse into the same pattern.

Modify is the first. The rest follow the same shape.

Once the basic shape is right — fork a workspace, read context with conventions and hints, propose with the LLM, verify against the contract, apply through governance, publish via the projection layer — the same shape carries a whole family of code operations. None of them require new substrate primitives.

Each entry in this table is a separate workflow with its own definition, but the shape is uniform. They share infrastructure — snapshot machinery, convention lookup, contract verification, audit chain, governance gating — and differ only in their middle steps. The family isn't held together by inheritance or by a common framework class; it's held together by composing the same substrate primitives in different orders.

Notifications matter more than they look.

One workflow in that table — code/notify — is worth dwelling on, because it's where the substrate's existing user-data heritage shows through clearly. When a Qbix function's contract changes, the people affected are: developers maintaining callers, operators of services that depend on the function via an HTTP endpoint or an event bridge, plugin authors whose ontology references the changed plugin's ontology, and humans who explicitly subscribed to the symbol's stream because they wanted to be told.

The substrate already has machinery for this. Streams.subscribe. Subscription rules. Notification dispatch via email, mobile, or in-app. Filter rules to suppress notifications under certain conditions. All of it built for ordinary user-data flows and now applicable, without modification, to code-state changes. A developer who wants to know when a function they depend on changes its contract subscribes to that function's symbol stream the same way they'd subscribe to a chat channel. They get a notification. They review the change. They update their code if needed.

Cross-language notifications work the same way. A PHP function fires a Q::event hook; a JS handler listens. Grokers represents this as both sides pointing at the same Grokers/extern/hook/... bridge node. When the PHP function's contract changes, the workflow's code/notify step traverses the bridge node to find every listener — across languages, across plugins — and posts notifications to their authors. The substrate doesn't care that one side is PHP and the other JS. The relation graph is uniform.

The same machinery that notifies users about new mail notifies developers about contract changes. The substrate doesn't distinguish kinds of state — it distinguishes kinds of subscription.

Composition without orchestrators.

The interesting property of this family is that the workflows compose without anybody orchestrating them. A code/modify that produces an incompatible contract change spawns a code/notify as a downstream effect, which posts messages, which triggers human review, which may produce its own code/modify on a downstream caller, which may spawn another code/notify. The graph of activity unfolds as workflows trigger each other through stream events and substrate messages, not through a central planner deciding what runs next.

This is why the substrate doesn't need to know what an "agent" is. The activity that an agent-driven architecture would describe as "the agent decided to update the documentation after the refactor" is, here, "the code/modify workflow's audit message triggered the Streams/messageType handler that spawned a code/document workflow against the same symbol." The decision-making is structural: declared in the substrate, governed at every step, queryable by anyone with read access to the audit chain.

Multiple teams. The same upstream. Different sprints.

Once code modification is a workflow primitive, multiple teams can run modifications in parallel against the same upstream codebase. Each team operates its own Safebox instance, with its own community, its own governance policies, its own credential vault, its own ZFS pool. Each instance clones the same upstream repo independently. Each instance forks workspaces independently. Each instance pushes branches to git independently.

Because forks are forward-only and the substrate has no merge primitive, two teams working in parallel produce two parallel branches in upstream git, both grounded in the same baseline commit. The substrate makes no attempt to reconcile them. Reconciliation, if needed, happens upstream — by humans reviewing both PRs, by an integration team merging them sequentially, by whatever process the upstream project already has for handling concurrent contributions. Safebox stays out of that decision. It produces well-formed proposals; it doesn't insist on how they get integrated.

This composes with the existing Safebox governance model in a useful way. A team's Safebox enforces M-of-N approval before any branch leaves the substrate. A reviewer signs off as a judgment vote, captured as a substrate stream, before the git push happens. The PR that lands on GitHub or GitLab carries provenance: which workflow, which workload, which approvers, which test results. A reviewer on the upstream side can verify the chain back to its source — the same way a regulator can verify any other Safebox-produced action.

The verification step is the CI step.

Continuous integration today is a separate stack. GitHub Actions, GitLab CI, CircleCI, Jenkins. Each one runs on its own runners, with its own credential management, its own caching layer, its own audit story. When a CI run fails, you read its log. When it succeeds, you trust that it ran. The integration with the codebase is a YAML file in the repo and a webhook on the git provider.

Most of what CI does — run tests, run linters, build artifacts, publish results, notify reviewers — is already what a Safebox workflow's verification step does. The difference is that a Safebox workflow's verification step happens before the commit, not after. The workspace's tests run inside the workspace's ZFS clone, with the workspace's proposed changes already applied, while the workflow can still abort. A failing test in CI prompts a developer to push a fix. A failing test in Safebox prompts the workflow to retry, escalate, or roll back without anything leaving the substrate.

For codebases that already use CI, Safebox doesn't replace it overnight — the workflow can push a branch, and existing CI runs against the branch as it always has. The audit chain captures both: the substrate-side verification that the workflow performed before pushing, and the CI-side verification that ran afterward. Over time, as Safebox workflows accrete coverage, the CI step becomes redundant. It can be retired one project at a time.

For new codebases, the picture is simpler. There's no separate CI to integrate with. Tests, linters, builds, deploys are all workflows. The substrate is the integration point. If a project uses GitHub for code review and wants pull requests, it gets pull requests via the projection layer. If it doesn't, it doesn't need them — the substrate's audit chain replaces what humans were using PR review to enforce.

Where Safebots actually earns its keep.

Everything described so far is mechanical. Once a human says "modify this function to handle the new error case," the workflow runs without further human input until completion or escalation. But humans rarely arrive at "modify this function to handle the new error case" already knowing exactly what they want. The act of figuring out what to do is conversational.

That conversational layer is what Safebots is for. A developer talks to a bot about a bug they're seeing, the bot queries the Grokers graph, the bot proposes hypotheses, the developer pushes back, the bot revises, eventually they arrive at a concrete change that needs to happen. The bot then proposes a workflow invocation as its action — "I'd like to run code/modify on these three functions with this change description" — and the workflow takes over. Conversation produces the intent; workflows produce the change.

This is the layering that distinguishes Safebox's architecture from the swarm-of-agents pattern in current AI tooling. In a swarm, the conversational layer and the doing layer are entangled — the agent talks AND acts, picking its own tool calls in free-form sequence, with no clean separation between "we're still figuring out what to do" and "we're now doing it." Safe behavior in a swarm depends on the agent making good choices about which actions to take when. The substrate doesn't help, because the substrate isn't involved.

The decoupling is the safety property. Safebots talks all it wants — the conversation is itself substrate-tracked, captured as messages in chat streams, queryable in the audit history, but it commits no changes. Acting requires invoking a workflow, and workflows go through the substrate's existing machinery: declared action types, governance gates, judgment dispatch, contract verification, ZFS-backed isolation, audit chain. The conversational layer's job is to figure out the right workflow to run, with the right inputs, at the right time. The doing layer's job is to run that workflow safely, regardless of how exotic the conversation that produced it.

This is what we mean by "decoupled agents."

Industry vocabulary names a thing called an "agent" — an LLM-driven loop that talks, decides, and acts in one process. Safebox doesn't have one. What it has instead is two cleanly-separated processes: a conversational system (Safebots) that generates intent, and a workflow system (Safebox) that realizes intent under governance. Each is auditable independently. The conversational side can be wrong about what to do, and the worst that happens is a workflow proposal that governance rejects. The workflow side can fail mid-execution, and the worst that happens is a workspace fork that gets rolled back. Neither failure mode produces an unbounded blast radius.

The trick is that the conversational layer doesn't lose any of the capabilities the agent framing was promising. A developer can have a long-running, exploratory, multi-turn conversation with Safebots about a refactor. The bot can read code through Grokers tools, run hypothetical analyses, draft changes, ask clarifying questions, revise its understanding. All of that is just substrate operations at a conversational pace. When the conversation converges on a change to make, the bot proposes the workflow, and the developer (or governance, or both) approves. The conversation continues — perhaps about the next change, perhaps about the workflow's results. The substrate is fully in the loop the whole time, not present at decision moments only.

We have decoupled agents. Conversation is one substrate operation; workflows are another. Neither pretends to be the other. Safety lives at the seam.

The same property at every layer.

Notice that this same decoupling shows up at each layer of the stack. Grokers indexes; Safebox runs workflows on the index; Safebots converses about what workflows to run. Each layer is a distinct substrate operation. None of them does the other's job. None of them depends on a unified "agent" abstraction that conflates them.

A team using all three layers gets: Grokers' pre-computed graph (so the conversation has accurate context), Safebox's workflow machinery (so the conversation's outputs get realized safely), and Safebots' conversational layer (so the team can think out loud about complex changes without hand-authoring every workflow invocation). A team using just Grokers and Safebox skips the conversational layer and authors workflow invocations directly — fine for batch operations, scheduled maintenance, and CI. A team using just Grokers integrates pre-computed code understanding into whatever tooling they already have without committing to the rest of the stack. The layers are independent. Adoption can be staged.

An honest map of the territory.

The architecture sketched here is an extension of the substrate, not a replacement for the tools developers already use. Three things worth being explicit about.

It is not a swarm of autonomous agents writing your code unsupervised.

Every workflow's writes pass through governance. M-of-N approval, judgment dispatch, declared action types, audit chain. A workflow that proposes a change to a function cannot bypass review by being in a hurry. The substrate's safety properties are structural — the workflow can't write outside its declared bounds even if the LLM driving it tries to. This is the same property described in architecture.html, applied to code instead of email.

It is not a Cursor or Claude Code replacement for one-off edits.

For a single-file fix, the overhead of forking a workspace is unwarranted. Existing IDE-integrated coding tools remain the right tool for in-the-flow editing. Safebox's workflow model earns its complexity at a different scale: refactors that touch tens or hundreds of symbols, parallel changes across teams, audit-required modifications, scheduled maintenance work, governance-gated production deploys. The relevant comparison isn't to Cursor; it's to a small team's combined CI+PR+refactoring tooling, which is the surface this replaces.

It is not a way to avoid git.

For codebases that already live in git, git stays. The projection layer pushes Safebox-produced branches there. Humans review PRs the way they always have. Git history continues to grow normally. What changes is what produces the commits and what verifies them before they land. For codebases that don't live in git, the substrate is the source of truth; git can be added later as a projection if humans need to look at the code that way.

Workflows all the way down.

The phrase comes from inside the team. We had spent months thinking about workflows as the right abstraction for ordinary work — answering email, scheduling meetings, processing claims. When code modification turned out to fit the same shape, the obvious question was: what else does. The answer seems to be most things. Infrastructure configuration. Scientific data curation. Regulatory filing. Training data preparation. Anything that involves coordinated state that multiple parties want to operate on, that needs an audit trail, that benefits from forward-only history with explicit divergence rather than retroactive reconciliation.

The substrate doesn't care what domain it's operating in. It composes the same twelve primitives — streams, relations, forks, workspaces, messages, actions, policies, judgments, conventions, capabilities, tools, workflows — onto whatever shape of state needs coordinating. Code happens to be one shape. There will be others. The shape we'll be most surprised by is probably not the one we're building for next; it's the one that, like code, was sitting in plain sight the whole time waiting for the right representation.

The substrate's bet is that most coordination problems have the same structure underneath, and a system that solves the structural problem solves most of the surface problems automatically. Code as the second domain confirms the first.

• Code modification as a workflow class composes with the existing substrate without new primitives.
• Contract verification — re-derive pre, post, side, and invariant claims from the new source — is the workflow step that distinguishes a safe refactor from a silent regression.
• Ripple is bounded recursion through the call graph: each level either passes the contract check or recurses into its own code/modify.
• Conventions and Grokers hints feed into every rewrite as substrate-resident inputs. The codebase's style and the framework's idioms are facts the workflow can consult.
• The same shape carries documentation, tests, audits, migrations, and notifications. One family, one set of substrate primitives, many verbs.
• ZFS provides filesystem-level forking with atomic rollback. Symlink hacks are not a substitute. Btrfs subvolumes or plain copy-on-fork are the alternatives where ZFS isn't available.
• Symbol streams are canonical. Files on disk are derived projections. Line numbers are computed, not stored.
• Git is a one-way projection for human review. Forward-only means no merge primitive, no reconciliation. New baselines come from re-cloning at a new commit.
• Multiple teams can run independent Safeboxes against the same upstream, producing parallel governed branches.
• The verification step inside a workflow replaces what teams currently buy as CI.
• Conversation lives one layer above, in Safebots. Decoupled from action. The substrate is the only path from intent to change.