Releases
A release is a frozen copy. You name part of a Brain’s records, the Brain copies the values those records hold right now, numbers the copy 1, 2, 3, and keeps it. Nothing about the copy changes afterwards, whatever happens to the records.
It is not sync. Cutting a release applies nothing to any Brain, no Brain reads through it, and no link crosses from one Brain to another. A release reaches another Brain only when someone applies it: a copy, staged under that Brain’s own admission, after which nothing is inherited.
Cut a release
Section titled “Cut a release”$API is as in the quickstart. Cutting needs
admin, and read as well, because a release holds content: a key granted
admin alone is refused. For a management key or a session, the person’s role
decides: owners, admins and editors may cut, viewers may not.
curl -X POST "$API/v1/brains/tenant:acme/releases" \ -H "authorization: Bearer $NICIA_KEY" \ -H "idempotency-key: method-v1" \ -H "content-type: application/json" \ -d '{ "name": "Method v1", "scope": { "kinds": ["playbook"], "where": { "stage": "live" } } }'{ "name": "Method v1", "scope": { "kinds": ["playbook"], "where": { "stage": "live" } }}The answer is 201 with the release’s summary:
{ "data": { "release": { "number": 1, "name": "Method v1", "scope": { "kinds": ["playbook"], "where": { "stage": "live" } }, "position": "57", "itemCount": 12, "manifestHash": "4c1a9e72f0b83d65a1c7e0f2b9d4836a5e1f70c2b8a3d9e6f4017a5c2b8d3e91", "createdByKeyId": "key_7f3a1c", "createdAt": "2026-11-19T09:00:00.000Z" } }}numbercounts up per Brain from 1, in the order cuts commit, with no gaps.positionis the journal position the records were read at: the items are the records as of it. Events that change no record (another cut, ananswer.changed) may sit between it and this release’srelease.cutevent.manifestHashis a digest of the ordered items. It never changes for a release, so equal digests mean equal copies. To verify it, take the items asGET /releases/{number}?items=trueserves them (kind, then id, order), build the array["release-manifest-v1", [kind, id, fields, recordedAt], ...], serialize it as JSON with object keys sorted and no whitespace, and take the SHA-256 hex of its UTF-8 bytes.nameis optional and is only a label.
What a scope freezes
Section titled “What a scope freezes”scope.kinds names one to twenty kinds. The release holds every current,
accepted record of each, narrowed by scope.where, which is the same predicate
object POST /query takes and applies to each
named kind: every kind must declare the fields it names.
- A record that is retired or deleted is not in it, and neither is one still staged for review: a release holds what the Brain accepts.
- Each item carries the record’s declared values, including its prose body, and the instant its accepted version was recorded.
- Edges between records are not carried: a declared relationship is not an item.
- Documents are not carried. A release is of records.
A scope that resolves to nothing is refused, so a release never has zero items. One that resolves to more than 20,000 records, or more bytes of values than a table snapshot holds, is refused too: narrow it.
| Refusal | Status | error.details |
|---|---|---|
release_empty |
400 |
reason |
release_too_large |
409 |
reason, limit (records), limitBytes |
release_scope_moving |
409 |
reason: the Brain kept changing; retry the cut |
idempotency_key_reused |
409 |
reason: that key cut a different release |
Read a release
Section titled “Read a release”curl "$API/v1/brains/tenant:acme/releases" -H "authorization: Bearer $NICIA_KEY"curl "$API/v1/brains/tenant:acme/releases/1?items=true&limit=100" \ -H "authorization: Bearer $NICIA_KEY"GET /releases lists summaries, newest first, with a nextCursor. GET /releases/{number} answers the summary, and with items=true the frozen items
in a fixed order (kind, then id), a page at a time:
{ "data": { "release": { "number": 1, "name": "Method v1", "scope": { "kinds": ["playbook"], "where": { "stage": "live" } }, "position": "57", "itemCount": 12, "manifestHash": "4c1a9e72f0b83d65a1c7e0f2b9d4836a5e1f70c2b8a3d9e6f4017a5c2b8d3e91", "createdByKeyId": "key_7f3a1c", "createdAt": "2026-11-19T09:00:00.000Z" }, "items": [ { "kind": "playbook", "id": "first-call", "fields": { "name": "First call", "stage": "live", "owner": "ops" }, "recordedAt": "2026-11-18T16:20:00.000Z" } ], "nextCursor": "0" }}Reading needs read. Edit a record, retire it, or add another afterwards and
the release’s items and manifestHash stay exactly as they were; cut again to
freeze the new state as the next number. There is no operation to roll a release
back or delete one.
Retry safely
Section titled “Retry safely”Send an Idempotency-Key. A retry of a cut that already committed answers 200
with that release instead of cutting a second; the same key for a different name
or scope is a 409. Without a key, two cuts are two releases.
Apply a release to another Brain
Section titled “Apply a release to another Brain”POST /v1/brains/{handle}/releases/apply is called on the receiving Brain and
names the publisher and a release number. Both Brains must be in the same
organization.
curl -X POST "$API/v1/brains/client-a/releases/apply" \ -H "x-api-key: $NICIA_MANAGEMENT_KEY" \ -H "content-type: application/json" \ -d '{ "from": "tenant:acme", "release": 2 }'{ "from": "tenant:acme", "release": 2 }There is no separate write path. The whole release is one snapshot: one
complete snapshot of a source in the receiving
Brain, with one table per kind, stating the release number as its revision.
The source is named for the publisher (a digest of its Brain id; no kind is in
the name), so release 1, 2 and 3 of one publisher are three snapshots of one
source. A snapshot is complete for the source, not per kind: that is why a
release withdraws a kind it no longer holds, and why nothing else should be
written to a release-… source. It is sealed and applies in the background, exactly as a CSV import
does, so the receiving Brain’s own admission decides what lands. One snapshot is
one plan, one set of decisions and one apply, so a release is never
half-applied and the revision advances once, only when everything applied.
- A record it does not hold is created, and one it holds is updated when that source alone supports the value. A list that shrank between releases loses the element the release dropped.
- A value a person set in the receiving Brain is not overwritten. Where the field
declares
multiplicity: "single"(and for a record’s prose body, which is always single-valued) the release’s value is contested and the record waits in Review as one Proposal, and the person’s value is still what is served. Where the field declares no multiplicity (every field of the built-inrule,decision,betandbeliefkinds), the person’s value is kept and the release’s value is an advisorydisagreesin the plan, with nothing staged. - A record the new release no longer holds is a withdrawal, and so is every record of a kind the new release no longer holds: the source’s support goes, and the record is deleted when nothing else supports it.
- Who needs to say yes depends on the receiving Brain’s mode. On an
openBrain a management credential’s apply lands its updates and withdrawals without a review. On areviewedBrain nothing lands: the snapshot stops atplannedwithprocessing.heldBecauseset, the receiving Brain’s records read exactly as before (a release serves nothing ahead of its apply, so the new records are not yet visible), and?plan=trueshows what the release would do. A person decides, and their apply lands every entry. On anunrestrictedBrain there is no contest: the release’s values overwrite what is there, a hand edit included. - Applying a release counts as confirming the rules it writes. The person who
applied it meant to ship the whole thing, so every decision, rule or belief
the apply created or updated, and that actually landed, is recorded as
affirmed (“Still holds”) by that person, with the note
Applied release N.: the same statementPOST /records/{id}/affirmwrites, one per record, in one batched write right after the apply. Nothing is affirmed that did not land: a contested change waiting in Review is not (approving it is what confirms it, by the approver), a record the release did not touch is not, and a withdrawal is not. So a release that rewrites rules does not leave each one on every client’s list ofunconfirmedrecords. This governs release apply only: a CSV import or a document sync, whose owner did not choose each row, still leaves a rewritten rule unconfirmed. - Release 1 then release 3 is fine. An older release than one already applied is
refused with
source_revision_stale, before anything is staged, and the refusal is kept as the source’s last refusal.
The answer is 202 once every kind is staged and sealed. It names the one
source and the one snapshot, and that snapshot’s status endpoint is the
outcome of the whole release:
GET /v1/brains/{handle}/sources/{source}/snapshots/{snapshot.id}.
{ "data": { "from": "tenant:acme", "release": 2, "source": "release-2281193b167a", "kinds": ["decision", "rule"], "snapshot": { "id": "01a1f294-5ea7-749b-a762-e95c2fb64aec", "source": "release-2281193b167a", "status": "sealed", "completeness": "complete", "documents": 5, "bytes": 537, "revision": 2, "openedAt": "2026-11-19T09:10:00.000Z", "sealedAt": "2026-11-19T09:10:00.200Z", "expiresAt": "2026-11-19T09:40:00.000Z", "processing": { "state": "queued", "step": "seal" } } }}Poll the status endpoint. status: "applied" means everything landed;
awaiting_review means something waits for a person (the rest has landed);
processing.state: "failed", with its error, means a background step stopped
and none of it landed: the source’s applied revision has not moved, and repeating
the seal retries it. ?plan=true lists every entry and its class.
Who may apply
Section titled “Who may apply”A management credential only: a session or an organization key whose person,
by their role now, administers the receiving Brain and can read the publisher. A
Brain key is refused with 401, whatever it is granted, so a client Brain’s key
can never be used to read the upstream Brain. A publisher in another organization
is a 404.
Overlays: local knowledge on top of a release
Section titled “Overlays: local knowledge on top of a release”What a receiving Brain adds is its own and stays its own. A person’s hand edit of
a released value is protected as above. A local record that rests on a released
rule (a rule with exception_to pointing at it) is
grounded on it, so when a later release changes what it
rests on, the exception reopens and is served as needing review. Nothing
local is visible to the publisher or to any other receiving Brain.
What is carried, and what is not
Section titled “What is carried, and what is not”A release is applied whole or not at all. A value that would not read back as
itself through the table pipeline refuses the whole apply with 409 and reason
release_values_not_carried, whose error.details.problems names each kind and
field, why, how many items, and examples. Nothing is staged.
- Carried exactly: strings, numbers, booleans, enum members, dates and
datetimes, a list of strings (one column per element), and a record’s prose
body. The body is read as one single-valued field named
bodyon every kind (unless the kind declares a field of that name), written as the record’s body, and protected like a field. Prose is markdown, so it is compared as written, not like a short field: only leading and trailing whitespace and the difference between CRLF and LF line endings are ignored. A body that differs in case, line breaks, paragraph breaks or indentation is an update; a byte-identical one is a no-op; and a body a person edited in the receiving Brain is contested, not overwritten. - Refused, naming it: a field the receiving kind does not declare, or a value
its field’s type cannot hold (
field_not_declared,value_not_readable_as_field_type). - Not values: a string’s surrounding whitespace is trimmed, and an empty string
or a
nullis no value. - Never in a release, so never applied: links (edges between records) and documents. A local record that should rest on a released one is written in the receiving Brain.
- No grounds: a
rule,decision,betorbeliefcreated this way states no grounds, so it has nothing to reopen. The Brain serves it as it serves any such record that rests on nothing:current, with an empty closure. - A kind the receiving Brain does not declare is
409release_kind_not_declared(details.kinds); roll the schema out first. A kind table rows cannot be read into (a platform kind, a page, a quote-bodied kind) isrelease_kind_not_appliable.
What a Brain holds
Section titled “What a Brain holds”GET /v1/brains/{handle}/releases/applied lists the sources a release apply
created in this Brain, one per publisher, with the publisher’s handle (as it was
when the latest release was applied), the highest release number applied
(source.revision.applied) and the last refusal. It reads nothing from the
publisher, and it is for a management credential only, because it names the
upstream Brain: a Brain key is refused with 401. A receiving Brain’s own keys can
still see in GET /sources that a source named release-<hash> exists and the
revision it has applied (the release number), but never the publisher’s handle or
id.
Applying the same release again is a refresh: it stages the same values, which change nothing, and affirms nothing new.
A plan a person has to apply (a reviewed Brain, an apply that asked for a
person) is listed by GET /attention as an
import_exception item with heldBecause and no staged change, until it is
applied. Rejecting the change a contested record staged settles the snapshot’s
Proposal, as publishing it does; the rejected value is remembered, so a later
release that restates it raises nothing again.
Where a served record came from
Section titled “Where a served record came from”A record a release stated carries release: { number, from? } wherever the Brain serves it: GET /records/{id}, each record of POST /query, a record item of POST /context with format: "items", and each native item of a receipt. number is the highest release applied to this Brain whose snapshot held the record. A record written here has no release.
- A management credential also sees
from, the publisher’s handle as it was when that release was applied. - A Brain key never sees
from. A client Brain’s agent is told that a rule came from a release, and which one, never whose. The release source’s own name (release-and a digest) is visible to a Brain key, and does not name the publisher. A released rule is served once, as its record: the release’s row document is kept as evidence but is not served beside the record when the record says everything the row does. - On a receipt, it is the release the Brain held when the receipt committed, so a later release never rewrites what an earlier read was shown.
releasesays where the record came from, not that every value is unchanged: a body a person edited here is still served under the release that stated the record.
Nothing is stored for it: it is derived from the snapshots a release apply already keeps, in one batched lookup per served page.
Who holds this Brain’s releases
Section titled “Who holds this Brain’s releases”GET /v1/brains/{handle}/releases/subscribers is the publisher’s fleet view: the Brains of the organization that have applied any release of this Brain, a page at a time (limit, up to 100, and nextCursor). Each carries:
handle, the receiving Brain’s handle now;applied, the highest release it has applied, andbehind, how many releases were cut after it (latestReleaseminusapplied;0is current);latestApply, its newest apply whatever became of it, withprocessing:failed(witherror),needs_review(contested values in Review, or a plan areviewedBrain holds for a person, withheldBecause), orapplied;lastRefusal, the last release it refused as stale.
Read latestApply.processing.state beside applied: the applied release advances when the plan applies, before a contested value is decided, so a Brain can read applied: 3 while its release 3 still waits in Review.
It is a management credential’s read, because it names other Brains: a Brain key, the publisher’s own included, is refused with 401. The person’s role now must be able to read this Brain, and a role reads every Brain of the organization. It never opens another Brain’s records: one bounded query over what each apply recorded.
{ "data": { "latestRelease": 4, "subscribers": [ { "handle": "client-a", "applied": 3, "behind": 1, "latestApply": { "snapshot": "01a1f294-5ea7-749b-a762-e95c2fb64aec", "release": 3, "status": "awaiting_review", "processing": { "state": "needs_review" }, "startedAt": "2026-11-19T09:10:00.000Z" } }, { "handle": "client-c", "applied": 4, "behind": 0, "latestApply": { "snapshot": "01a1f294-6bb1-7c10-9a58-0e3a1f5d7c21", "release": 4, "status": "applied", "processing": { "state": "applied" }, "startedAt": "2026-11-19T09:12:00.000Z" }, "lastRefusal": { "reason": "source_revision_stale", "statedRevision": 1, "appliedRevision": 2, "refusedAt": "2026-11-19T09:11:00.000Z", "keyId": "key_7f3a1c" } } ] }}The event
Section titled “The event”Every cut journals one release.cut event
carrying the number, name, item count and manifest hash, never a value, so a
runner following the event stream learns that a new
release exists.