Hive

A hive is an encrypted, mountable filesystem image that OctoMY™ uses for any piece of state that must survive a restart, follow an identity around, or be cryptographically scoped to one owner. Hives are the storage substrate that sits underneath every other concept in the app — sentient identity, node identity, contacts, key material, configuration, OPAL audit history.

TL;DR

A hive is a single file on disk that, when mounted with the right key, becomes a writable directory tree. Three classes exist today (sentient hive, node hive, general hive); only the first two are user-visible.

For the user-facing controls, see Active Mounts. For the encryption model see the Security Model.

Why an encrypted filesystem and not a database?

A hive is a Shufflecake volume — a deniable encrypted block device wrapped around a sparse store file, presented as an ExFat filesystem once unlocked. That gives the app three properties that an ordinary on-disk database can't provide:

1. One key, one mount point. Authentication is a single Argon2id derivation against the hive's header. Everything inside is then plaintext-accessible to the running process; nothing else on the system can read it without the same key.
2. Plausible deniability. Shufflecake allows multiple logical volumes to coexist in the same underlying store file with different keys; an attacker who compels a passphrase sees only the volume that key unlocks.
3. Mount/unmount semantics map cleanly onto identity lifecycle. Switching sentient = unmount old hive, mount new hive. There's no "drop my contacts from a shared SQLite" surface area; the contacts are simply no longer addressable.

The encrypted-store-as-identity-boundary is what lets the app move a user between sentients without restarting the process and without leaving residue from the previous identity in shared in-memory caches.

Three classes of hive (§HT-1)

Every hive carries its type in its on-disk identifier. There is no separate manifest field; the prefix is the type.

Why types live in the identifier

Earlier versions of the app used a privileged "System" hive owned by the device's primary sentient. The string was special-cased throughout the codebase: in passphrase prompts, in the lanyard, in factory code paths. Renaming a sentient required hunting through string literals; auto-creating a hive for an imported sentient required carving an exception for the magic name.

Replacing that with a typed prefix moves the type into a single field and lets the display layer look it up freshly every time. Renaming a sentient now updates every UI surface without changing anything on disk; importing an additional sentient produces another SID-<hex> hive that's visually peer-equal to the original.

How sentient and node hives layer

Within an active session, a node hive is always mounted on top of its owning sentient hive — the node hive's mount path lives inside the sentient hive's mount tree. Two practical consequences:

• Unmount order matters. The node hive must come down first. The §SP-8a Teardown phase in IdentitySwitchService::runTeardown does this in the documented order; the user-facing path stays out of trouble.
• The node hive needs the sentient hive's vault to mount. The node hive's master key is stored as raw bytes inside the sentient's SentientVault. Mounting the node hive amounts to looking that key up and using it directly — there's no separate passphrase. This is what makes the layering safe: anything that knows the sentient's vault key can re-derive any of its node hives.

The layering is one-sentient-active-at-a-time and at-most-one-node-on-top: §OQ-7's "concurrent mounts" resolution. The architecture supports the dual mount; it does not pursue N>1 sentients mounted side-by-side, because there is no user-facing model for it.

The hive lifecycle

                                         ┌───────────────┐
                                         │ HiveFactory   │
                                         └──────┬────────┘
                                                │  createSentientHive (auto / wizard)
                                                │  createNodeHive    (§9b funnel)
                                                ▼
                                         ┌───────────────┐
            mount  ───────────────────►  │   on disk     │
            (Argon2id + ExFat)           │ SID-<hex>     │
                                         │ NID-<hex>     │
                                         └──────┬────────┘
                                                │ HiveSession::mountHiveAsync
                                                │ HiveSession::mountNodeHive
                                                ▼
                                         ┌───────────────┐
                                         │  mounted      │ ─── Lanyard / Active Mounts
                                         │  (writable    │
                                         │   ExFat tree) │
                                         └──────┬────────┘
                                                │ §SP-8a Save → Teardown
                                                ▼
                                         ┌───────────────┐
                                         │  unmounted    │
                                         │  (still on    │
                                         │   disk)       │
                                         └───────────────┘

• Creation runs through HiveFactory. The sentient hive is created once per sentient (§SP-1 auto-create on first boot, or via the create-sentient wizard). The node hive is created lazily when a node is added; the call funnels through Node::nodeIdentityChanged so that wizard and OPAL paths get the same treatment.
• Mount is async because Argon2id derivation is CPU-bound (a few hundred ms on first touch). HiveSession::mountHiveAsync runs it on a worker thread.
• Save & Teardown belong to the Identity Switching cascade. Anything dirty in the in-memory mirrors of subsystems backed by the hive (SentientVault, AddressBook, KeyStore, registries) flushes here.
• Unmount releases the file handle. The store file remains on disk; the next mount of the same hive re-runs Argon2id against the same header.

Where the user sees hives

Outside the diagnostic Active Mounts screen, the user never sees the raw SID-<hex> / NID-<hex> strings. Every UI surface — the lanyard chips, the sentient and node lobbies, the selection activities, the status widgets, log lines that surface in the UI — looks up the owning entity and renders its friendly display name + identicon.

The taxonomy is engineering visible (in spec text, in log entries, in HiveRegistry::sentientHives() / nodeHives() / generalHives() filters) but user invisible. That separation is on purpose: the type prefix is a stable contract for code, while the display name is a mutable choice the user makes.

Common questions

Can I rename a sentient? Yes, freely. The on-disk hive id is SID-<hex> and never changes; the display name is read fresh from the sentient's vault every time the lanyard updates.

What happens if my sentient hive is corrupted? Mount fails with a wrong-passphrase or volume-error reason. The session is not affected (you're still on the previous active sentient if there was one). Recovery is the BIP39 phrase you wrote down at first boot.

Can two devices share a hive file? No. The hive is per-device — moving a sentient identity to a new device is the migration protocol, which produces a fresh SID-<hex> hive on the new device with the original SID derived from the recovery phrase. Per §SP-10, imports always land in a new hive, never overwrite an existing one.

Is a "general hive" useful today? Not yet. The class is reserved in the taxonomy so future surfaces (user-named encrypted volumes, mount-time union-fs composition) don't have to renegotiate the type system. No factory or UI exists for them.

Related