Brainy Brainy
Docs Brainy

Recovering what was removed

In this section

A delete in brainy is not a loss. When a row is removed, its last version - the row exactly as it stood just before the removal - stays readable for the life of the store. When the row is a stored file, the file's content stays too. Trimming a brain's history (compactHistory(), which a closing brain runs by default) may fold old versions together and may free the space of every version that was replaced, but it never frees the last copy of something that was removed.

Two doors give you the rows back, and a third gives you a removed file's bytes.

listRemoved - what was removed

let cursor: string | undefined
do {
  const page = await brain.listRemoved({ since: new Date(Date.now() - 7 * 86_400_000), cursor })
  for (const row of page.removed) {
    console.log(row.id, row.kind, row.type, row.door, new Date(row.timestamp))
  }
  cursor = page.nextCursor ?? undefined
} while (cursor)TS

Every removal the store still has a record of, oldest first. One entry per removal event: a row removed, written again under the same id and removed again is two entries.

field

what it says

id

the removed row's id

kind

entity, or relationship

type, subtype

the entity or relationship type the last version names (null when it names none)

generation, timestamp

the commit that removed it, and when

door

the door that committed the removal: remove, removeMany, unrelate, transact, vfs.unlink, vfs.rmdir. Absent on a commit made before the stamp existed

origin, meta

the engine origin and the transact() meta the commit carried, when it carried any

lastVersion

readable, or unavailable (see below)

source

where the answer is served from now - the removed-rows list, a generation's own before-image, or the fact log

Parameters: since and until (a generation, or a Date), type, kind, limit (1 to 1,000, default 100) and cursor.

Two honest properties of a page. A page can hold fewer rows than limit and still not be the last - the call stops after a bounded amount of scanning, so keep calling with nextCursor until it is null. And observableFrom names the lowest generation any record on the store could have named a removal in: a removal that happened before the store kept the record the listing reads cannot be listed, and the answer says where that line is rather than guessing.

A store an earlier engine wrote: the band and the gap. A store written by 13.2.x has a removal list that does not yet cover its whole history. The background job removed-rows-seed brings it level from the fact log in installments of 2,000 generations (about 5 MB of log each on a measured copy of a real store: 2.4 KB a generation), behind the doors, and says once when it is level: removed-rows ledger brought level with the horizon H from the fact log: N removal(s) kept over K installments. The job resumes from the list's own coverage after a restart; a store with no job runtime keeps the trimming pass's seed at close. Until it lands, a door call never reads the whole log: it reads the band - the 2,000 generations below the horizon - and the page says what it did not read. Every page carries bandFrom (the lowest generation read from the fact log) and gapGenerations (how many generations between the list's coverage and bandFrom the page does not read). gapGenerations: 0 means the answer is complete; above 0 it may omit removals in those generations, so call again after the seed has landed. The first answer given with a gap is narrated: recovery read: the removed-rows ledger covers through G; this answer reads generations H..horizon and omits G+1..H-1 until the background seed lands. Within the band, a row whose last version lies below it is not guessed at; it appears after the seed lands. retainedWalkedFrom names the lowest retained generation (above the horizon) an answer looked at: a listing walks the whole retained range page by page, but readRemoved of an id walks only the newest 2,000 generations of a longer retained range, counts the ones it did not walk in gapGenerations, and so a null it answers says exactly what was not looked at.

readRemoved - one removal, in full

const gone = await brain.readRemoved(invoiceId)
if (gone) console.log(gone.value.metadata, 'removed at', new Date(gone.timestamp), 'by', gone.door)TS

Returns the row's last version exactly as asOf(generation - 1) returned it before the removal - an entity, or a relationship with its two ends - with the removal's own details and hasVector. Pass generation to read a particular removal of an id removed more than once (the default is the most recent), and includeVectors: true for the vector components (off by default, as get).

  • null means no removal of that id is on record - in what the answer covers. While gapGenerations is above 0 (see the band and the gap above), an id removed inside the gap also answers null, exactly as a live row does, because as far as the covered record knows the row is live. A caller reads gapGenerations from brain.removedRowsCoverage() (or the coverage field on the wire answer) to tell the two apart.

  • A removal that is on record but whose last version cannot be established

    • a crash left the removing generation without a before-image, and the fact log holds no earlier version - is listed unavailable, and readRemoved refuses RemovedRowUnavailableError (HTTP 410). It never answers null, which would say "never removed".

asOf below the compaction horizon keeps refusing, because the rest of the store at that generation is gone. These doors are the guaranteed way to a removed row.

A removed file

A stored file is an entity whose metadata.storage names its content (a hash and a size). Trimming keeps that content for as long as the removal is listed, so the file's bytes are never the part that got away. readRemoved returns the row that names them; readRemovedContent(id, { generation? }) returns the bytes themselves, exactly as the file held them. The row's hash is the lookup, and the bytes are checked against it by the content store's own integrity check.

const file = await brain.readRemovedContent(fileId)   // { id, generation, timestamp, hash, size, path?, content: Buffer } | nullTS
  • null when no removal of the id is on record - the same answer as readRemoved.

  • A row whose content is not in the store refuses RemovedContentNotStoredError, carrying the hash (HTTP 410). It is never an empty answer: an empty stream would say the file was empty. readRemoved(id) still returns the row, with the same hash. If a copy of the brain still holds the bytes, repairBlobReferences({ readmit }) puts them back under that hash (docs/blob-references.md), and the read answers again.

  • A relationship, and an entity that was not a file, name no content: ValidationRefusedError.

  • A removal whose last version cannot be established refuses RemovedRowUnavailableError, as readRemoved does.

  • When the id was removed more than once, the most recent removal is read; generation selects an earlier one.

Over brainy host the bytes are streamed: POST /v1/brains/{brain}/removed/{id}/content answers application/octet-stream - the file itself, not a JSON document - written in slices as the socket drains, with content-length set so a transfer cut short reads as cut short. (The host reads the content out of the store whole first - the store has no partial read yet - so the file's size is held in the host's memory for the length of the transfer; the largest file the store holds is 2 GB.) The headers name what the bytes are: x-brainy-content-sha256 (their SHA-256, which is their name in the store), x-brainy-removed-id, x-brainy-removed-generation, x-brainy-removed-at, x-brainy-removed-path (percent-encoded) and a content-disposition with the file's name. An id with no removal on record answers the JSON document { "removedContent": null }. The transports that can only carry a document (the MCP tool brainy_read_removed_content, the WebSocket) answer the file base64-encoded up to 8 MiB and refuse above it by name, saying where the bytes can be read.

curl -sS -X POST "$HOST/v1/brains/venue/removed/$FILE_ID/content" \
  -H "Authorization: Bearer $SERVICE_KEY" -H 'content-type: application/json' -d '{}' \
  -o recovered.bin -D headers.txt
sha256sum recovered.bin   # equals the x-brainy-content-sha256 headerSH

Over the wire

All three doors are reached with the service key: they read every caller's removals, not one caller's own.

door

brainy host

listRemoved

POST /v1/brains/{brain}/removed with { since, until, type, kind, limit, cursor }

readRemoved

POST /v1/brains/{brain}/removed/{id} with { generation, includeVectors }

readRemovedContent

POST /v1/brains/{brain}/removed/{id}/content with { generation } - answers the file's bytes

curl -sS -X POST "$HOST/v1/brains/venue/removed" \
  -H "Authorization: Bearer $SERVICE_KEY" -H 'content-type: application/json' \
  -d '{ "limit": 20, "kind": "entity" }'SH

MCP names them brainy_list_removed, brainy_read_removed and brainy_read_removed_content; BrainyClient has listRemoved(), readRemoved() and readRemovedContent() (which returns the file as a Buffer, checked against the host's hash, so a transfer that arrives short or altered throws). listRemoved answers the page plus the head generation; readRemoved answers { removedRow, coverage }, removedRow null when nothing was removed under that id, and coverage the five numbers observableFrom, ledgerCoveredThrough, horizon, bandFrom and gapGenerations.

What stores answer

store

in process and brainy host

brainy serve

a tree store (history in files)

answers

NotYetNativeError - the native handler is not written yet

a mirror store (the segment log serves, the tree is still written)

answers

NotYetNativeError

a log-canonical store (the one-way mark)

answers, across the mark: the removals before it (the removed-rows list, the retired fact log's files, the record-sets) and the ones the segment log committed after it (a tombstone; its last version is the record just below; its time, and the door and transact() meta the writer recorded, are the commit's boundary row)

NotYetNativeError

A refusal names the door and why. None of them is an empty answer.

The doors that remove everything

  • clear() is a logged mass removal. Every entity and relationship goes through the commit path under the door clear (in bounded commits), so every row that was live is a removal now: listed, readable, and asOf before the clear still answers. The content of a removed file stays in the blob store. Only what is derived (the indexes, the id tables, the counts) is reset. A product's data refresh - a clear and a re-import - therefore leaves the previous data recoverable. On a log-canonical store the in-process clear() refuses (LogCanonicalClearError); brainy serve clears it as one logged generation. A clear is many commits, so a process that dies between two leaves a brain part way cleared - and that is never silent: a marker (_system/clear-in-progress.json) is made durable before the first commit and removed only after the last commit and the reset of what is derived. While it stands, the next open says so in its log line, health() carries an unfinished-clear row (a warning: nothing was lost, every removal made so far is listed), and the next clear() finishes the job and removes the marker.

  • restore() replaces the store with a snapshot and keeps the one it replaced: every displaced top-level entry is set aside under _displaced/<stamp>/ in the store root (a rename, so it cannot run out of space), after the buffered tier of recent history was made durable. Copy the folder's contents into an empty directory and it opens as the store as it stood. Nothing deletes it; an operator does, when a decision says so. The restore tells the operator where it sits the moment it is set aside, and what it occupies once a background walk of it finishes - the blocks on disk (the allocated size, not the declared size a sparse store inflates), beside the declared size and the file count.

  • The orphan prune (repairIndex) sets a container that has lost its metadata leg aside under _quarantine/<stamp>-orphaned-container/ instead of deleting it.

  • The repack (repackHistory()) folds old record-sets into sealed segments; a generation whose before-image file exists and will not read is left unfolded with its directory exactly as it is, and the repack says so, instead of packing the generation without the row and deleting the bytes.

  • The blob recount counts the history the repacker folded into sealed segments, so a removed file's content is not released while a packed before-image still names it.

What keeps it true

  • compactHistory() copies every removal's last version - and takes a hold on the file content it names - into the removed-rows list (_generations/removed/) before it frees anything, one entry per removal event, and stops with RemovedRowsNotRetainedError if it cannot write the list. A crash between the copy and the free leaves the list ahead of the history, never behind it.

  • A damaged list is never read as empty: it refuses both doors and refuses trimming, by name (RemovedRowsLedgerDamagedError, HTTP 503). The brain itself opens and serves.

  • A store trimmed by an engine that kept no list is brought level from the fact log on the next explicit trim; what that older engine already freed (a file's content) stays freed, and the listing says which entries are unavailable. Until then the doors read that stretch of the fact log themselves - one sequential pass, shared by calls that arrive together, kept in memory for as long as the store stands - and write nothing: a read never changes the store.

  • Files written as working state (retention: 'latest-only') keep their own rule: superseded versions are dropped on purpose; the last version is kept on removal, with its content.

  • On a mirror or log-canonical store a request to reclaim history is refused by name (RetentionForeverError) and the segment log keeps every version, so there is nothing to retain.

Errors

error

when

HTTP

RemovedRowUnavailableError

readRemoved met a removal on record whose last version cannot be established

410

RemovedContentNotStoredError

readRemovedContent met a removed file whose row names content (a hash) the store does not hold; carries the hash

410

RemovedRowsLedgerDamagedError

the removed-rows list cannot be read; also refuses trimming

503

RemovedRowsNotRetainedError

compactHistory() could not write the list, so it freed nothing

-

ValidationRefusedError

a limit, kind, window or cursor that is not valid

400

The contract rows are in the API contract; the routes are in brainy host.