The organism, part by part

The product is the organism: your Hale application, plus the parts that let it be governed, changed, run and watched. Someone asks for an outcome; the…

The product is the organism: your Hale application, plus the parts that let it be governed, changed, run and watched. Someone asks for an outcome; the organism turns it into work, proposes a change in a sandbox, proves it with the toolchain, asks whoever holds the authority, applies exactly what was approved, runs it, and watches that it works. Every decision is a row in a record that lives in your git repository.

This page is the map. Each part has one job, one place in the tree, and one chapter that covers it.

• Start with Getting started: make an organism, fill its vault, start it, answer the first Review.
• Then One task, end to end: one request from the terminal to a change kept or rolled back, with the record’s rows beside each step.
• The part chapters follow, one per group of parts. Read the one you need when you need it.
• Shaping and governing it is how you change what the organism is: its purpose, practices, grant and law.
• DNA, the building block comes last on purpose. DNA (vendor/dna, the dna::Dna locus, the hale dna commands) is what every part is assembled from. It is the inside view, and you do not need it to run an organism.
• Troubleshooting and the Reference are for looking things up.

Schedules, which say when a workflow runs and who convenes it, have their own chapter: Schedules.

Every part keeps two rules. They are why nothing is half-written and why a restart loses nothing.

One store per step. A workflow step writes to exactly one store, by that store’s one writer, and the next step reads what the previous one made durable. A workflow definition names the store of each step in one word (record, forge, genome, heart, graph, nerves, memory, vault or host), and a step that names none, or two, is refused before anything runs. A write whose subject moved since it was read is refused and decided again. There is no transaction spanning two stores, and none is needed. The spine has the engine.

Row first. Every live signal is a row before it is sent. When you ask for something, the command writes a row and stops; a node relays that row onto the nerves until the record holds the answer. Events name a row by id, arrive at least once, and are consumed once by that id. An event from outside, such as the application’s own, is a signal, not a fact: it lands as a reading.recorded row before anything acts on it. The nerves has the relay.

Each part sits in one tier. A tier is defined by what it is handed and what it is never handed.

The local vault is one directory per user. Any program that user runs could read any entry by name, so what keeps a part to its own credential is what it is handed, not what it could read. The skin covers the vault and the accounts.

Plainly, so you can decide whether it fits.

• Take a request in a sentence, from the terminal (hale dna task create) or from the face, and turn it into one execution of a workflow the record keeps.
• Make a proposed change in a sandbox worktree of your repository. The editor holds four tools there: read, edit, format and check.
• Prove the candidate: its base artifact, format, check, verify, tests, the fleet it would deploy, a rehearsed rollback, and the structural diff. Each result is a receipt in the record.
• Show the source diff, the semantic diff and the evidence together, pinned to one commit: in the terminal, in iris, on the read-only page hale dna ui serves, and as a pull request when GitHub is configured.
• Let the Leader, a model, decide inside a grant the Board gave, with its reasoning on the record, and ask the Board for everything else.
• Apply exactly the approved commit, express it (a restart under hale dna dev, a deploy row every node of a fleet answers, or your own deployment command), watch it for a window, and keep it or roll it back.
• Grow its own org chart through the same door: a change to the organization is the Board’s to review, and applying it restarts the organization.
• Hand a person’s job to that person as a Task, and wait for them.
• Run work as workflow definitions written in code, and resume every execution after a restart under the same ids.
• Record all of it in order: in git under refs/dna/*, and, once you adopt the ledger, the day’s work in memory.

• Apply anything without a verdict. The Leader’s verdict is a model’s, inside a grant only the Board writes; the Board’s is a person’s.
• Let the editor commit, open worktrees, apply, or read memory’s knowledge. The law in dna/org/law.hl forbids each, and a wiring that breaks it fails to build, with a witness path.
• See behaviour in the structural view. The semantic diff sees structure and rules and is blind to what a handler computes. That is why the source diff is always beside it.
• Grow without the Board. Persistent pressure becomes a proposal; nothing joins the org chart until the Board approves the commit.
• Migrate live state. A restart is a restart. State the application keeps only in memory is gone across a change, as it would be across any deploy.
• Diff the fleet as a whole. A Review’s semantic diff is the edited seed’s. The deploy row names the instances it reaches.
• Raise pressure from your metrics on its own. hale dna pressure raise writes a pressure signal; nothing raises one from a service’s metrics.
• React beyond one reflex. The reflexes have one rule: an instance its node reads as down is restarted. They do not roll back or back off.
• Take commands on hale dna ui. That page reads the record and refuses every form. Commands go through the head, which serves the face.
• Run a definition whose step writes the heart, the vault or a host. Such a definition is refused at admission, and hale dna definitions says why. A leg’s deploy and heart hands refuse too.
• Read a model key from the environment. A model key is a vault slot, model-<NAME>, filled with hale dna secret set.
• Run without git. The record is refs in your repository, changes are commits, rollbacks are resets. Teammates and nodes share it through a remote.
• Promise an external effect happened once. A transition happens once in the record. Whether a performer’s effect ran once across a restart is its adapter’s to say; one that cannot say leaves the attempt for a person (hale dna effect resolve).
• Close a person’s job for them. A case waits for its person’s hale dna task done, through any restart.
• Cancel an execution from the terminal. The engine can cancel; no hale dna verb asks it to.

Before the apply path was built, reviewers decided planted changes from the structural diff alone, the source diff alone, and both. The source diff and the combined view decided every case; the structural view alone decided the rule-backed cases and correctly held on the rest. So the combined view is what you get, and what the Leader gets. The write-up is dna/kill-test/WALKTHROUGH.md in the hale repository.

The contract behind every statement on these pages is spec/dna.md.