Namespaces

A Fallen-8 is a collection of namespaces, and a namespace is one isolated graph backed by its own Fallen-8 engine. Each namespace owns a private set of vertices, edges, indices, subgraphs, stored queries, registered plugins, and a change feed; nothing crosses between them. One reserved namespace, default, always exists and answers the bare (un-prefixed) URLs. This page covers the model, the /ns/{name}/… routing scheme, the management API, naming rules, the catalog that keeps the inventory durable, and how namespaces interact with save games.

The model

Property	Value
Namespaces per Fallen-8	Up to `Fallen8:Namespaces:MaxNamespaces` (default 10000), counting `default`. A cap, not a target, each namespace runs a full engine with its own writer thread and (in durable mode) write-ahead log, so realistic fleets are dozens to hundreds.
Isolation	Every namespace has its own engine. Data, indices, subgraphs, stored queries, and registered plugins written to one are invisible to the others. Isolation covers data and metadata, not process resources: the GC heap, the sensitive-endpoint rate-limit window, the single analytics run slot (`429` while it is held), and the global ingestion queue (`503` when full) are Fallen-8-wide.
Reserved namespace	`default` is always present, aliases the bare URLs, and cannot be renamed or dropped.
Identity	Internally each namespace has an immutable, collection-assigned id (e.g. `ns-20260723-101502-3f2a`). On-disk storage and metrics are keyed by the id, never the name, which is why names are permissive and rename is a pure metadata move. The management API never reports the id; the one place it surfaces is a save game’s `namespaces[]` manifest, which the boot chain matches on (see save games).

Routing: bare and `/ns/{name}/…`

Every namespace-scoped route has a twin under /ns/{name}/…. A bare URL addresses the reserved default namespace, so /vertex/count and /ns/default/vertex/count hit the same engine. Fallen-8-level routes exist once and have no twin: namespace management itself, PUT /save/all, HEAD /tabularasa/all, the save-game registry (/savegames/…), GET /config, POST /chat, POST /delegates/validate, and the benchmark helpers (GET /generate, GET /benchmark).

The same read, against default (bare) and against a flights namespace:

Bash
PowerShell

curl http://localhost:8080/vertex/count
curl http://localhost:8080/ns/flights/vertex/count

Invoke-RestMethod http://localhost:8080/vertex/count
Invoke-RestMethod http://localhost:8080/ns/flights/vertex/count

A /ns/{name}/… request for a namespace that does not exist returns 404 problem+json with the offending name in the namespace extension member, for both reads and writes, before any mutation runs.

Managing namespaces (REST)

These routes are Fallen-8-level: they exist once and are never themselves prefixed with /ns/{ns}.

Route	Effect	Responses
`GET /ns`	List all namespaces (name-ordered, always includes `default`) with the `maxNamespaces` ceiling	`200`
`GET /ns/{name}`	Get one namespace	`200` · `404`
`PUT /ns/{name}`	Create a new, empty namespace	`201` · `400` invalid name · `401` · `409` name in use · `422` quota reached (body carries `maxNamespaces`) · `429`
`PATCH /ns/{name}`	Rename (body field `name`) and/or set the plugin-registration override (body field `pluginRegistration`: `"enabled"`, `"disabled"`, or `"inherit"`). Both fields are optional; supply at least one	`200` · `400` neither field supplied, invalid new name, or unrecognized `pluginRegistration` · `401` · `404` · `409` new name in use, or a rename of `default` (setting `default`’s override is allowed) · `429`
`DELETE /ns/{name}`	Drop irreversibly	`204` · `401` · `404` · `409` target is `default` · `429`

Create, rename, and drop require an authenticated caller and are rate-limited (401/429); see security. A list/get entry reports:

Field	Meaning
`name`	The URL-addressable name
`state`	`ready` or `creating` (always `ready` today)
`vertexCount` / `edgeCount`	Element counts for this namespace
`createdAt`	Creation time (UTC, ISO 8601)
`pluginRegistrationEnabled`	This namespace’s plugin-registration override: `true`/`false` when set explicitly, `null` when it inherits the instance default (see plugin registration)

There is no per-namespace memory figure: engines share one GC heap, so a byte count would be fiction.

Rename is metadata only: the engine, its data, its id, and its on-disk locations are untouched; only the URL address changes. Drop removes the in-memory graph, indices, stored queries, and registered plugins and deletes the namespace’s live on-disk state (its write-ahead log); there is no undo. Checkpoint files are not deleted: they belong to save-game entries and remain valid restore points (delete them with DELETE /savegames/{id}?deleteFiles=true).

Two erase routes sit beside the CRUD table. HEAD /tabularasa empties the addressed namespace but leaves it registered (it is twinned, so bare hits default). The Fallen-8-level HEAD /tabularasa/all is a factory reset: it drops every non-default namespace and empties default, leaving one empty default behind.

Create, rename, and drop:

Bash
PowerShell

curl -X PUT http://localhost:8080/ns/flights
curl -X PATCH http://localhost:8080/ns/flights \
  -H "Content-Type: application/json" -d '{"name":"flights-eu"}'
curl -X DELETE http://localhost:8080/ns/flights-eu

Invoke-RestMethod -Method Put http://localhost:8080/ns/flights
Invoke-RestMethod -Method Patch http://localhost:8080/ns/flights `
  -ContentType application/json -Body '{"name":"flights-eu"}'
Invoke-RestMethod -Method Delete http://localhost:8080/ns/flights-eu

Naming rules

Names are permissive because on disk a name is only a display label, a dictionary key, and a URL path segment (the id carries identity). That last role fixes the only hard limits.


Allowed	Any case, digits, spaces, punctuation, and Unicode; 1 to 63 characters. Names are case-sensitive (compared ordinally).
Rejected	Empty or whitespace-only; longer than 63 characters; leading or trailing whitespace; exactly `.` or `..`; or containing `/`, `\`, or a control character.

So Flights EU, code.repo_v2, fraud!(q3)#2, ümlaut-Ω-graphé, and con are all valid; slash/name, .., " leading", and a 64-character name are not. Because a name is a URL path segment, percent-encode reserved characters in the request URL, Flights EU #2 becomes /ns/Flights%20EU%20%232. Kestrel decodes it before routing, and the namespace is stored and listed under the decoded name. An encoded slash (%2F) is rejected by Kestrel and can never round-trip.

The namespace catalog

The inventory itself is durable, independently of save games. Create, rename, drop, and the plugin-registration override are written to a catalog file, namespaces.json, in the metadata directory (Fallen8:Metadata:Directory, default <app base>/metadata, next to savegames.json). The write goes to a temp file and then replaces the catalog, so a crash mid-write leaves the previous one intact. A namespace that was created but never saved therefore returns after a restart, its committed data replayed from its own write-ahead log.

Three operator notes. A catalog that cannot be read, or that is invalid JSON, aborts startup loudly rather than being silently overwritten: fix or remove the file and restart. A single entry that is reserved (default), duplicate, or malformed is skipped with an error log while its on-disk data stays untouched, so repairing the entry restores it. In volatile mode (Fallen8:Durability:Volatile=true) there is no catalog at all, so namespaces created over REST are gone on the next start along with everything else.

Save, load, and restore

Checkpoints follow namespace boundaries. PUT /save checkpoints the addressed namespace (it has a /ns/{name}/… twin); PUT /save/all checkpoints every namespace into one Fallen-8-level entry. Restoring with PUT /savegames/{id}/load replaces exactly the namespaces the entry contains: a dropped namespace is recreated, an existing one has its graph replaced, and namespaces the entry does not contain are left untouched. Add ?namespace={name} to restore just one namespace out of the entry (404 if the entry lacks it). Because a drop keeps checkpoint files, a dropped namespace can be brought back from a save game. The mechanics, checkpoints, the write-ahead log, durability, live in save games.

Studio

F8 Studio shows the current instance and namespace as a pair in the top bar, and its Connect screen creates, renames, switches, and drops the namespaces of an instance. See studio.