DNA, the building block

DNA is what the organism is assembled from: the library in vendor/dna, the dna::Dna locus your organization constructs from it, and the hale dna commands…

DNA is what the organism is assembled from: the library in vendor/dna, the dna::Dna locus your organization constructs from it, and the hale dna commands. Its one job is to be the same parts in every organism, so that what differs between two organisms is only what their projects wrote. The toolchain owns it: you never edit vendor/dna, and hale dna upgrade writes it again. It fails loudly when it and the binary disagree: hale dna status names the digest vendor/dna came from and tells you to upgrade. It never holds anything of yours: your source lives in dna/, your secrets in the vault, your history in the record.

The rest of this section describes the organism by its parts. This page is the view from underneath: where the library comes from, the locus it gives you, how the parts are carved out of that locus, and every file hale dna new and hale dna init write.

The hale binary carries the DNA source inside it. new, init and upgrade write the part a project imports into vendor/dna:

The version alone does not name the source, because two builds of one version can embed different source. The digest does:

hale dna --embedded-digest                      # the digest this binary embeds, and nothing else
hale dna --embedded-digest --from-tree <dir>    # what the checkout at <dir> would embed

hale --version prints its first sixteen digits (embedded dna: ca4012a0cda7226d). Every materialization writes the full digest into vendor/dna/README.md and .hale/dna/embedded.digest, and pins the toolchain version in hale.lock:

# vendor/dna — toolchain-owned

The DNA core (`dna/core` of the hale repository) as shipped by hale 0.21.0.
Embedded source digest: ca4012a0cda7226dd7b82f28f2b9c6104df253e56658d6e3aaabd4cf0a8fb25a
(`hale dna --embedded-digest`; two builds of one version can embed different
source, so the digest is the provenance and the version is not.)
Regenerated by `hale dna init` / `hale dna upgrade`; pinned in `hale.lock` as
`[dna] toolchain`. Do not edit: project-owned source lives in `dna/`.

.hale/dna/embedded.digest has the same two lines as hale --version, with all 64 digits.

hale dna status opens with the binary’s digest:

embedded dna: ca4012a0cda7226d (hale 0.21.0)

When vendor/dna was materialized from another source set, the same line adds ; vendor/dna was materialized from <digest> — run `hale dna upgrade`. A clone carries no vendor/dna (it is in .gitignore); a body started in a fresh clone materializes it first. What upgrade rewrites, and what it leaves alone, is in Shaping and governing it.

The binary embeds more than vendor/dna: the host that hale dna dev, run and most verbs execute, the operations the head serves, and the face. Those are built from the binary into its cache and never copied into your project. The digest covers all of it.

The host is two programs over one seed. Its body (dna/host) is what hale dna dev, hale dna run and hale node run until they are stopped; every other verb — status, review, apply, fill and the rest — is its verb program’s (dna/host/verb), which answers one verb and exits. hale dna builds both into the cache the first time any host verb needs one, and runs the one the verb belongs to in its own process, so stopping hale dna dev stops the body itself.

Your organization is a Hale program, dna/org/main.hl, and its main locus has three params: core, the substrate; leader, the position that decides inside the grant; and nerves, its connection to the broker. core is one dna::Dna, and every setting is a constructor argument:

import "vendor/dna" as dna;
import "vendor/dna/pond/realtime/nats" as nats;

main locus Org {
    params {
        core: dna::Dna = dna::Dna {
            // …
            journal: dna::RoutedJournal {
                record: dna::GitJournal { repo: "." }
            },
            // …
            work: dna::WorkSystem {
                agent: dna::LegRelay { name: "legs" },
                agent_reconciler: dna::RelayReplay { }
            },
            // The organization's spend: one policy (models.hl), one owner.
            budget: dna::Budget { policy: org_budget() },
            // …
            boundary: dna::AutonomyBoundary {
                child: "refproj",
                grant: dna::Grant { child: "refproj", classes: "refactor docs", max_magnitude: 4, review: "pre" }
            },
            review_policy: dna::OrgPolicy { },
            board: dna::Board { who: "board" },
            gateway: dna::MutationGateway {
                leases: dna::GitLeases { repo: "." },
                workspaces: dna::IsolatedWorktrees { repo: ".", root: ".hale/dna/worktrees" },
                repo: dna::LocalGit { repo: "." }
            },
            verification: dna::HaleVerification { receipts: dna::GitReceipts { repo: "." }, scratch: ".hale/dna/scratch", repo: ".", seed: "." },
            // …
            editor: dna::SourceEditor { name: "editor", models: editor_models() },
            genome_seed: ".",
            // …
            catalog: workflows(),
            // …
            planned: true
        };

That is refproj’s, from a fresh hale dna new refproj; your project’s name stands where refproj does. Each field names a concrete locus behind one of the core’s interfaces:

A few fields keep their defaults in the generated file, and are worth knowing because you can set them:

The same file wires the Leader and the nerves:

        leader: dna::Leader = dna::Leader {
            name: "leader",
            models: leader_models(),
            receipts: dna::GitReceipts { repo: "." },
            source: dna::SourceReader { repo: "." },
            // …
            charter: charter(),
            purpose: purpose()
        };

and binds the facts that enter the organization to the nerves, one nats::NatsAdapter each:

    claims { adopt Org; }
    placement { nerves: pinned; }
    // …
    bindings {
        dna::ReviewVerdict: nats::NatsAdapter { };
        dna::IntentOffered: nats::NatsAdapter { };
        dna::ExpressionObserved: nats::NatsAdapter { };
        dna::PressureRaised: nats::NatsAdapter { };
        dna::ConcernRaised: nats::NatsAdapter { };
        dna::PracticeRequested: nats::NatsAdapter { };
        dna::HoldRequested: nats::NatsAdapter { };
        dna::PositionOpenRequested: nats::NatsAdapter { };
        dna::KnowledgeNodeRequested: nats::NatsAdapter { };
        dna::KnowledgeBindingRequested: nats::NatsAdapter { };
        dna::KnowledgeEdgeRequested: nats::NatsAdapter { };
        dna::WorkSubmit: nats::NatsAdapter { };
        dna::WorkAllowanceAsk: nats::NatsAdapter { };
    }

The nerves’ connection, its failure handler and why it stops the organization are on The nerves. The loop at the end of run() calls self.core.request_tick(…) on the wall clock in milliseconds, which is when schedules occur (Schedules).

Because all of this is construction, hale check sees the whole organization as wiring: which position holds which handle, and which effects each can reach. That is what the law in dna/org/law.hl is checked against (The law).

The core’s other loci each live in a file of their own: the Leader and the source reader in dna/core/org.hl, the editor in dna/core/editing.hl, the gateway, worktrees and LocalGit in dna/core/workspace.hl, verification in dna/core/verification.hl, GitJournal and GitReceipts in dna/core/record.hl, the grant’s boundary in dna/core/review.hl, the budget in dna/core/budget.hl, the work system and the leg relay in dna/core/work_system.hl, the catalog in dna/core/workflow_definition.hl. The Board, the review policies and the deployments are in dna/core/assembly.hl, beside dna::Dna itself.

What dna::Dna keeps about the record is split into families: one locus per kind of fact, each a child of the assembly. None of them is set in the generated main.hl; the assembly constructs them, and at birth lends each the record it appends to:

        self.evidence.bind(self.journal, self.verification.receipts);
        self.org_source.bind(self.journal);
        self.practices.bind(self.journal);
        self.concerns.bind(self.journal);
        self.spending.bind(self.journal);
        self.positions.bind(self.journal, self.verification.receipts);
        self.cases.bind(self.journal);
        self.attempts.bind(self.journal);
        self.organization_source_review_facts.bind(self.org_source.facts);
        self.scheduler.bind(self.journal);
        self.knowledge_record.bind(self.journal, self.verification.receipts);

A family holds only its own state and writes only its own rows, in the order the assembly asks for them; it reads everything back from the record (dna/core/record_rows.hl). What crosses families — a Review born, the Board told, an execution admitted — stays the assembly’s.

You never construct a family yourself. They matter when you read the core: a question about practices is answered in practices.hl, not by reading four thousand lines of assembly.hl.

hale dna new <name> makes a directory holding a small application and then runs init on it; it refuses a directory that is not empty. hale dna init [app-dir] attaches to an application that exists: it finds the seed’s main locus and refuses a seed that has none. init adds nothing to the application: no import, no param, no binding. Run again, it keeps every file that is there (kept … (already exists)) and does not reseed a record that exists.

Beside the files, init writes these rows into the record, unless it is run with --no-library (new takes the flag too):

Outside the files, init also:

• makes the directory a git repository if it is not one: the record is a branch;
• seeds the record, refs/dna/journal, with receipts under refs/dna/receipts/ (Memory and the record);
• sets dna.unix.member in the clone’s git config, so the head’s socket knows your uid, and dna.trust = local when the record declares no trust;
• draws the organism’s own secrets into the vault and makes an empty slot for each one a person supplies (The skin);
• formats dna/ and the application’s seed with hale fmt.

new --profile remote-body --remote <url> [--body <user@host>] also adds the origin remote and sets dna.body; hale dna profile reports the combination from those pieces afterwards.

init adds two environments, one per entrypoint, each under its own law:

# hale dna init: the two entrypoints and where each deploys (`hale check --matrix`).
# The organization adopts its law (dna/org/law.hl) itself; the application keeps its own.
[claims]
no_base = true

[environments.local]
source_only = true
entrypoints = ["."]

[environments.org]
source_only = true
entrypoints = ["dna/org"]

no_base is stated rather than inferred: the application and the organization share no constitution, and an unstated shared base would be a rule that looks bound and binds nothing. hale check --matrix . checks both.

# the build artifact
/refproj
# toolchain-managed (vendor is re-materialized; .hale holds sockets, worktrees, scratch; the record is refs/dna/*)
/vendor/
/.hale/
/dna/nats.secrets.conf
/dna/postgres.secrets

dep = []

[dna]
toolchain = "0.21.0"

The first five lines of the ignore file are new’s; init adds each of /vendor/, /.hale/ and the two secrets files that is not already there. The secrets writer refuses a file git would track.

init on an application writes these rows into the record before anything runs:

For refproj that is 72 rows: one attachment, three observations (Echo, Refproj, Pings), two responsibilities, two graph rows (its purpose and its seed; it serves no API surface), and thirty-two proposals with their Reviews — the purpose, eleven design (eight practices and three mandates), seven operating practices, seven using practices, and six for the holes (three positions, three mandates). Shaping and governing it has the practices.

Run init on a directory with no Hale source of its own that is no workspace’s seed, and it treats it as a repository rather than one application: a seed per process, the specs they meet at, a compose file that runs them. It makes the organization the same way, with three differences:

• the manifest gains [environments.org] alone, since there is no application entrypoint;
• no topology artifact is cut; instead the record is seeded with what the repository holds, as one graph: its purpose (the README.md’s title and first paragraph), its processes (the compose services), its seeds, its contracts under spec/, its documents, its CI jobs as gates, and its FRICTION.md entries as witnesses;
• it writes structure.hl in dna/org, whose operational_roles() names the roles each deployment also gets (from support accounts billing on-call), "" by default. init reads it once, when it seeds the record, and keeps one that is already there, so to opt in you write it before init.

An application gets this path too. Its init reads the same graph from its own directory after the rows it observes, with two additions: the application is the root seed, and each API surface it serves (or stream over a hub) is a contract it meets as server, named from the toolchain’s own export. A surface that a spec/<stem>.md already describes is that node, not a second one. The surface’s requires roles become the equipment of the positions, never an organization or an authority.

From that graph init proposes the positions a delivery needs, each with its own Board Review: a board, a reviewer for every part that serves or consumes a contract, a dev and a work item wherever a gate guards something, an operator under every deployment. What a directory listing cannot say, you write in markdown, and init reads it as written:

• A marked list item. A list item that opens with a code span names its kind: `axiom` for a decision, `derived`, `practice` or `law` for a rule proposed as a practice. Its first bold span is its name, and the files an axiom links to are what it shaped.

  - `axiom` **Only the api is exposed.** NATS and the nodes are on the
    private network ([`protocol.yaml`](https://github.com/hale-lang/hale/blob/main/docs/src/dna/spec/protocol.yaml)).

• A declaring table. A table with Served by and Consumed by columns says, for each contract it links, which process serves it, who consumes it, and over what (Over); one whose first column is Deployment with a Runs column names a deployment and what it runs. A name in code is a process or a seed, a link is a file, plain words are someone outside the repository.

  | Document | Served by | Consumed by | Over |
  |---|---|---|---|
  | [`openapi.yaml`](https://github.com/hale-lang/hale/blob/main/docs/src/dna/spec/openapi.yaml) | `api` | callers, `ui`, `node` | HTTP |

What the conventions cannot take stops init with the reason before anything reaches the record: an axiom with no bold name, a table row that links no contract, a name in code the repository does not have, a name with a | in it. Fix the document and run init again; it keeps the files it made and seeds the record whole. The graph, the positions it implies and how routing reads them are on Memory and the record and The head and the face.