Blackbox AIDocs

Data and backup#

Where Blackbox AI keeps state, what the archive guarantees, and how to copy it without corrupting it.

Where state lives#

Data Location
World state The application data/ directory, including store.json
Canonical evaluation report A dedicated slot under data/
Provider settings and the stored device token BLACKBOX_CONFIG_DIR, when set; otherwise an interactive user profile
Durable research archive Append-only JSONL under the data directory

A service installation must set BLACKBOX_CONFIG_DIR explicitly rather than relying on a profile that a service account may not have.

One server, one world#

The service embodies a single persisted world identity. On an existing store, BLACKBOX_WORLD_ID asserts the identity you expect, and a mismatch is refused rather than adopted.

Warning

A refused store is the protection working. Do not change the asserted identity to make the error stop — confirm which store you intended to open first.

What the archive guarantees#

The durable archive is single-process and operationally at-least-once:

Property Detail
Duplicate tolerance Record identifiers and start-up recovery deduplicate exact retries
Torn writes Readers tolerate a torn final JSONL line
Concurrent writers Not supported
External deletion Not supported

Two consequences follow. Never run a second process against the same data directory. Never delete archive files from outside the application.

Back up#

  1. Stop the service. A copy taken while the service is writing is a copy of an indeterminate moment.
  2. Copy the whole data directory, not selected files. store.json and the archive are consistent with each other only as a set.
  3. Copy the configuration directory separately if it holds provider settings and a device token.
  4. Start the service and confirm the world resumes.
npm run start
Warning

The configuration directory can contain a stored device token. Treat a backup of it as credential material — encrypt it, and do not keep it beside the world data on shared storage.

Restore#

Restore the whole directory to the same path, then start the service. The server auto-resumes a persisted advancing world. Fiction time does not catch up for the period the service was down.

Archive, purge and the research archive#

Three different things share the word:

Term Meaning
World Archive A durable, audited, read-only terminal lifecycle transition
Purge Distinct from Archive; removal rather than a read-only transition
Research archive The append-only JSONL record of what happened

Archiving a world is terminal and audited. Use Hold when you want to stop activity reversibly.

Verify#

  • After a restore, the Now surface shows the expected world with its chronicle intact.
  • The asserted world identity matches the store, with no start-up refusal.

If it does not work#

Symptom Check Recovery
Start-up refuses the store Asserted world identity against the store Point at the intended store
The archive has a truncated last line Whether the service was killed mid-write Readers tolerate this; no action needed
Duplicate records after a crash Whether an exact retry occurred Record ids and start-up recovery deduplicate exact retries
State is missing after a copy Whether the copy was taken while running Restore from a copy taken with the service stopped