vta-keyspaces 0.3.0

//! Central registry of the VTA's keyspace names.
//!
//! Every `store.keyspace(..)` call in the VTA (`vta-service` server, offline
//! CLIs, backup, tests) names its keyspace through a `const` here rather than a
//! bare string literal. This is the single source of truth that killed the
//! `"imported"` / `"imported_secrets"` test-vs-production divergence (a test
//! opened a *different*, empty keyspace than the one production writes). The
//! `no_bare_keyspace_literals` guard in `vta-service` keeps it that way by
//! scanning that crate's source for bare `.keyspace("…")` literals.
//!
//! Keyspace *names* live here; per-keyspace *key formats* (the `key:`, `seed:`,
//! `path_counter:` … record families inside a keyspace) are a separate concern
//! and are not yet centralised.
//!
//! A near-leaf crate: it holds the shared keyspace vocabulary (the name
//! constants) plus the [`Keyspaces`] handle bundle, so that every VTA subsystem
//! crate can name and pass keyspaces without depending on `vta-service`. Its
//! only dependency is `vti-common` (for `KeyspaceHandle`).

use vti_common::store::KeyspaceHandle;

/// Shared bundle of borrowed keyspace handles passed to operations that need
/// several keyspaces at once.
///
/// The struct is a pure field bundle — the constructors that borrow it from a
/// concrete `AppState` / `VtaState` live in `vta-service` (they know those
/// types), so this stays free of any `vta-service` dependency.
pub struct Keyspaces<'a> {
    pub keys: &'a KeyspaceHandle,
    pub acl: &'a KeyspaceHandle,
    pub contexts: &'a KeyspaceHandle,
    pub did_templates: &'a KeyspaceHandle,
    pub audit: &'a KeyspaceHandle,
    pub imported: &'a KeyspaceHandle,
    #[cfg(feature = "webvh")]
    pub webvh: &'a KeyspaceHandle,
}

/// Master seed + key records (`key:`, `seed:`, `path_counter:`,
/// `active_seed_id`, `imported_kek_salt`, …) and the backup import sentinel.
pub const KEYS: &str = "keys";
/// Auth sessions + challenges.
pub const SESSIONS: &str = "sessions";
/// ACL entries + the seal record + the integrity-anchor root.
pub const ACL: &str = "acl";
/// Trust contexts (the BIP-32 key hierarchy roots).
pub const CONTEXTS: &str = "contexts";
/// Stored DID templates (global + context-scoped).
pub const DID_TEMPLATES: &str = "did_templates";
/// Audit log.
pub const AUDIT: &str = "audit";
/// The keyed-hash keys the audit log commits actor and target identifiers
/// under, and their history.
///
/// Separate from [`AUDIT`] because the two have opposite lifetimes: entries
/// are erased when their retention expires, and a key must outlive every entry
/// that references it or those entries stop being checkable against a
/// candidate identifier.
pub const AUDIT_KEY: &str = "audit_key";
/// Imported secret material (KEK-wrapped). Named `imported_secrets`, **not**
/// `imported` — the latter was a long-standing test-only typo that operated on
/// an empty keyspace disjoint from production. Always reference this const.
pub const IMPORTED_SECRETS: &str = "imported_secrets";
/// Non-extractable internal signing keys.
///
/// Deliberately **not** [`IMPORTED_SECRETS`]: that keyspace wraps its contents
/// under a KEK derived from the BIP-39 master seed, so anything stored there is
/// reconstructible by whoever holds the mnemonic. Internal keys exist precisely
/// to have no such path — their material is generated from the system CSPRNG,
/// never derived, and lives here instead.
///
/// In [`EXCLUDED_FROM_BACKUP`] by design, not by omission. A backup containing
/// this keyspace would be an export of keys the VTA promises never to export.
pub const INTERNAL_KEYS: &str = "internal_keys";
/// Ephemeral cache (resolver/auth caches).
pub const CACHE: &str = "cache";
/// Holder credential vault (third-party secrets stored on this VTA).
pub const VAULT: &str = "vault";
/// Persistent runtime service-enable state (`operations::protocol::runtime_state`).
pub const SERVICE_STATE: &str = "service_state";
/// Sealed-bootstrap anti-replay nonce log.
pub const SEALED_NONCES: &str = "sealed_nonces";
/// In-flight backup-bundle control-plane records.
pub const BACKUP_BUNDLES: &str = "backup_bundles";
/// WebVH DID records + `did.jsonl` state.
pub const WEBVH: &str = "webvh";
/// In-flight passkey-as-verificationMethod enrolment state.
pub const PASSKEY_VMS: &str = "passkey_vms";
/// Persisted protocol-management drain set.
pub const DRAINS: &str = "drains";
/// Per-kind previous-config snapshots for fail-forward rollback.
/// (Historically `operations::protocol::snapshot::KEYSPACE_NAME`.)
pub const SNAPSHOT: &str = "service_prev_config";
/// KMS-protected, unencrypted boot keyspace (TEE integrity manifest, etc.).
pub const BOOTSTRAP: &str = "bootstrap";
/// Inbound-messaging consent: durable grants + TTL'd pending requests
/// (`vti_common::consent`). The VTA is the first gate for bridged conversations.
pub const CONSENT: &str = "consent";
/// Per-(platform, context) approver bindings — who decides consent and how the
/// prompt routes (`vti_common::consent::ApproverBinding`).
pub const CONSENT_APPROVERS: &str = "consent_approvers";
/// VTA-issued credentials (minted by `vta/credentials/issue/0.1`, revoked by
/// `vta/credentials/revoke/0.1`). One record per credential keyed `cred:<id>`;
/// revocation is a tombstone (`revokedAt` set in place), not a delete. Distinct
/// from [`VAULT`] (which stores credentials the holder *holds*).
pub const ISSUED_CREDENTIALS: &str = "issued_credentials";

/// Per-context key/value store for AI-agent memory (`vta/memory/{put,list,
/// delete}/0.1`). One record per `(contextId, key)` pair, keyed
/// `mem:<contextId>:<key>`; `list` is a `mem:<contextId>:` prefix scan. Durable
/// user data → in [`BACKED_UP`].
pub const MEMORY: &str = "memory";

/// A member's MLS group state for each data room they belong to
/// (`rooms/keys/{welcome,commit,open}`), keyed `room-group:<roomId>`.
///
/// **This holds group secrets.** Whoever reads a row can decrypt every record
/// the group could, up to its epoch — the same class of material as [`KEYS`],
/// and it inherits the same protection: the KMS storage key in a TEE
/// deployment, and a trusted data directory outside one.
///
/// In [`BACKED_UP`], and that is a decision rather than a default. A member who
/// restores a VTA without their room groups has lost the ability to read every
/// sealed room they belong to, with no way to recover it — the group cannot be
/// re-derived, and rejoining means a fresh invitation from every owner. The
/// backup already carries the credential vault and the master seed; group state
/// belongs with them.
pub const ROOM_GROUPS: &str = "room_groups";

/// Invitation credentials this VTA has consumed by joining a room
/// (`rooms/keys/welcome`), keyed `room-vic:<credentialId>`.
///
/// Separate from [`ROOM_GROUPS`] because it outlives them: a member who leaves a
/// room discards the group, and the consumed-invitation record must survive that
/// or the same invitation would let them be re-added without a fresh one. Single
/// use means single use.
pub const ROOM_INVITATIONS: &str = "room_invitations";

/// The holder's identity attributes, profiles, bindings and contacts
/// (`persona/*`) — the fourth store, beside [`VAULT`] (secrets and
/// credentials), [`MEMORY`] (agent memory) and [`APP_STATE`] (uninterpreted
/// application JSON).
///
/// It is a distinct store because disclosure control is its point, and a
/// maintainer that cannot read a record cannot decide which of its members may
/// leave, cannot audit which ones did, and cannot answer "what have I shared
/// with whom". [`APP_STATE`] promises never to interpret its records, so it
/// cannot host this; and a namespace there is collision avoidance rather than a
/// trust boundary, so a compromised application sharing a context could remove
/// the holder's identity data.
///
/// **Two scopes share the keyspace, and the split is a security control rather
/// than a filing decision.** The pool and profiles are *agent-scoped* — above
/// every context — so that the correlation index can see the risk it most needs
/// to report: the same value presented by two personas in two different
/// contexts, which a per-context index cannot see by construction. Bindings,
/// contacts and disclosure records are context-scoped, because a persona lives
/// in a context and so do its counterparties.
///
/// Nothing inside a context may read the agent-scoped prefixes. The holder
/// pushes a materialised projection down; a context never pulls. That is
/// enforced at dispatch, not here, but the prefix split is what makes the
/// enforcement expressible.
///
/// Agent-scoped:
///
/// - `pa:<attributeId>` — one attribute of the pool.
/// - `pp:<profileId>` — one profile.
/// - `pxi:<hmac>` — correlation index, keyed by a keyed hash of the value so
///   exact-match lookup works with no plaintext index over personal data.
/// - `pxr:<attributeId>:<profileId>` — attribute → profile reverse index, so a
///   delete can name its referring profiles without scanning every profile.
///
/// Context-scoped:
///
/// - `pb:<contextId>:<personaDid>` — binding of a profile to a persona DID.
/// - `pc:<contextId>:<contactId>` — a contact's current revision.
/// - `pcr:<contextId>:<contactId>:<rev>` — superseded contact revisions,
///   reference-counted rather than reaped on a flat TTL: a revision behind a
///   disclosure record is evidence the holder can still be asked to account for.
/// - `pd:<contextId>:<seq:020>` — append-only disclosure record.
/// - `plp:<contextId>:<profileId>` — context-local profile (inline entries
///   only). A *separate prefix*, not a flag on `pp:`, so a context-scoped list
///   scans a space that structurally cannot contain a pool profile — a filter
///   bug there would be the same one-line leak the authorization rule exists to
///   remove.
/// - `plb:<contextId>:<personaDid>` — binding of a local profile.
///
/// The holder's identity is the account → in [`BACKED_UP`]. A restored agent
/// that came back without it would be an agent that no longer knows who its
/// holder is.
pub const PERSONA: &str = "persona";

/// Versioned, namespaced application state (`vta/app-state/{get,put,list,
/// delete,get-many,put-many}/1.0`) — the third store, beside [`VAULT`] (secrets
/// and credentials) and [`MEMORY`] (agent memory), for JSON an application owns
/// and the VTA does not interpret.
///
/// Four record shapes share the keyspace, distinguished by prefix:
///
/// - `app:<contextId>:<namespace>:<key>` — the record itself. `list` in
///   snapshot mode is an `app:<contextId>:<namespace>:` prefix scan.
/// - `appv:<contextId>:<namespace>:<version:020}>` — version index, mapping a
///   zero-padded counter value to its record key. Change-feed `list` scans this
///   so it can return changes in version order and paginate over a stable
///   storage key; a scan-and-sort over the records could do neither.
/// - `appc:<contextId>:<namespace>` — the namespace's monotonic write counter.
/// - `appt:<contextId>:<namespace>` — the oldest version still covered by a
///   retained tombstone, which is what `sinceVersion` is checked against.
///
/// Deliberately **not** [`MEMORY`]: clearing an agent's memory has to stay a
/// safe thing for a user to ask, which it cannot be if account state lives
/// there. Durable user data — an account's recoverability depends on it — so it
/// is in [`BACKED_UP`], and a restore that came back without it would defeat
/// the point of the feature.
pub const APP_STATE: &str = "app_state";

/// Rego policy modules for the Policy Decision Point (`policy/{upsert,list,
/// delete,evaluate}`). One `policy::PolicyModule` per id, keyed `policy:<id>`;
/// the active set is every enabled row, priority-ordered. Durable operator
/// security config → in [`BACKED_UP`] (a lost policy set would silently drop
/// enforcement on restore).
pub const POLICY: &str = "policy";

/// Task-execution consent for the PDP's `requireConsent` disposition: pending
/// approvals keyed by payload digest, and granted consents a re-submitted task
/// consumes. Distinct from [`CONSENT`] (messaging-bridge conversation consent).
/// One `policy::consent::PendingTaskConsent` per `pending:<digest>` and
/// `policy::consent::TaskConsentGrant` per `grant:<digest>:<requester>`.
/// Durable operator-facing security state → [`BACKED_UP`].
pub const TASK_CONSENT: &str = "task_consent";

/// Durable reliable-messaging outbox backing `vti_common::outbox_store::`
/// `VtiOutboxStore` for the delivery-layer `MessagingService` (D2 P2a
/// cut-over). Holds `Guaranteed`-delivery outbox entries; dormant in P2a (all
/// current sends are `BestEffort`) but wired so the drain/confirmation loops
/// persist across restarts once P2b adds guaranteed VTA pushes. Runtime state,
/// not backed up.
pub const OUTBOX: &str = "outbox";

/// Idempotency records for keyed Trust Tasks — one row per
/// `(actor, idempotency-key)`, holding the request digest and, for tasks whose
/// response may be replayed, the original response. Lets a client's retry of a
/// lost reply converge on the first execution instead of producing a second
/// durable effect.
///
/// Persistent rather than in-memory (unlike the `(actor, envelope-id)` replay
/// cache it sits beside) because the window that matters is exactly the one a
/// restart falls inside: the VTA processed the request, the reply was lost, and
/// the client is still retrying. Swept on TTL by
/// `vta_sweepers::idempotency_sweeper`. Runtime state, not backed up.
pub const IDEMPOTENCY: &str = "idempotency";

/// Durable TSP relationship state, backing the SDK's `RelationshipStore` for the
/// TSP transport. One record per facet per `(our_vid, their_vid)` pair — the
/// relationship FSM state, thread digests, reply path and learned capability.
///
/// Persistent because Rev 3 §7.2.2 has an endpoint silently drop application
/// traffic from a VID it holds no relationship with: an in-memory store wiped on
/// restart makes every established peer's messages vanish until each
/// re-handshakes. Persisting the state turns a restart transparent (design note
/// `docs/05-design-notes/tsp-relationship-recovery.md`, D1). Runtime state, not
/// backed up — a relationship is re-establishable (D2/D3), and like [`SESSIONS`]
/// it is scoped to this VTA's DIDs, so a restore re-drives it rather than
/// carrying it.
pub const RELATIONSHIPS: &str = "relationships";

/// Every production keyspace. Partitioned by [`BACKED_UP`] +
/// [`EXCLUDED_FROM_BACKUP`]; the [`tests::backup_partition_is_total`] guard
/// asserts the partition stays exhaustive so a newly-added keyspace can't be
/// silently omitted from the backup decision.
pub const ALL: &[&str] = &[
    INTERNAL_KEYS,
    KEYS,
    SESSIONS,
    ACL,
    CONTEXTS,
    DID_TEMPLATES,
    AUDIT,
    AUDIT_KEY,
    IMPORTED_SECRETS,
    CACHE,
    VAULT,
    SERVICE_STATE,
    SEALED_NONCES,
    BACKUP_BUNDLES,
    WEBVH,
    PASSKEY_VMS,
    DRAINS,
    SNAPSHOT,
    BOOTSTRAP,
    CONSENT,
    CONSENT_APPROVERS,
    ISSUED_CREDENTIALS,
    MEMORY,
    ROOM_GROUPS,
    ROOM_INVITATIONS,
    APP_STATE,
    PERSONA,
    POLICY,
    TASK_CONSENT,
    OUTBOX,
    IDEMPOTENCY,
    RELATIONSHIPS,
];

/// Keyspaces a backup carries, **every row of each**, as a raw dump.
///
/// A backup exists to bring an agent back, so the rule is inclusion: a
/// keyspace is here unless there is a reason on [`EXCLUDED_FROM_BACKUP`] for
/// leaving it out. Within a carried keyspace the only rows left behind are the
/// few that belong to one *deployment* rather than to the agent — see
/// [`is_environment_bound`] — and the restore re-creates those for the target.
///
/// Every name here is exported by `vta_backup::ops::export_backup` without a
/// per-keyspace code path: it walks this list. `every_backed_up_keyspace_
/// survives_a_round_trip` in `vta-backup` writes a row into each and asserts
/// it comes back, so a keyspace cannot be listed here and silently skipped —
/// which is exactly what happened to ten of them while export was a set of
/// hand-written collectors.
pub const BACKED_UP: &[&str] = &[
    KEYS,
    ACL,
    CONTEXTS,
    DID_TEMPLATES,
    AUDIT,
    // Without the keys, a restored audit log still verifies as a chain and
    // still says what happened, but no entry can be checked against a
    // candidate identifier again — the commitments become opaque. The key is
    // generated rather than derived, so nothing else reproduces it.
    AUDIT_KEY,
    IMPORTED_SECRETS,
    // The holder's secrets and credentials. The reason a person keeps a VTA.
    VAULT,
    WEBVH,
    // Which transports this VTA serves. The DID log restored beside it
    // advertises them, and a document naming a transport the node does not
    // serve fails at the peer as a parse error, not as "not served".
    SERVICE_STATE,
    SNAPSHOT,
    DRAINS,
    // Anti-replay for sealed bootstrap requests. Restoring it only ever makes
    // the restored agent stricter; leaving it behind reopens every request
    // still inside its validity window.
    SEALED_NONCES,
    CONSENT,
    CONSENT_APPROVERS,
    // Credentials this VTA issued. Losing the records loses the ability to
    // revoke them, while every copy in the wild stays valid.
    ISSUED_CREDENTIALS,
    // Durable agent memory is user data and must survive a restore.
    MEMORY,
    ROOM_GROUPS,
    ROOM_INVITATIONS,
    // Application state IS the user's account for a consumer built on it —
    // labels, relationships, contacts, join history. A restore that came back
    // without it would return a VTA whose applications no longer recognise
    // their own data, which is the failure the store exists to prevent.
    APP_STATE,
    // The holder's own identity — attributes, profiles, bindings, contacts.
    // A restore that came back without it would return an agent that no longer
    // knows who its holder is, which is most of what the restore was for.
    PERSONA,
    // Operator security policy — must survive a restore, else enforcement
    // silently reverts to whatever defaults boot-install provides.
    POLICY,
    // Task-consent grants are durable authorizations a re-submitted task
    // consumes; losing them on restore would strand in-flight approvals.
    TASK_CONSENT,
];

/// Keyspaces deliberately **not** in a backup, each for a stated reason.
pub const EXCLUDED_FROM_BACKUP: &[&str] = &[
    // Non-extractable internal signing keys. Excluding them is the feature:
    // a backup that carried them would export keys the VTA guarantees never
    // to export, and restoring one elsewhere would silently clone a signer.
    // Their *records* live in KEYS and are carried; the restore reports every
    // one whose material stayed behind.
    INTERNAL_KEYS,
    // Live sessions are bound to the JWT key and the node that issued them.
    SESSIONS,
    // Re-derivable resolution and auth caches.
    CACHE,
    // The control plane of the transfer carrying this very backup.
    BACKUP_BUNDLES,
    // TTL'd, in-flight passkey enrolment ceremonies.
    PASSKEY_VMS,
    // The deployment's own boot material: KMS ciphertexts, the integrity
    // manifest, the staged restore itself. A restore writes the target's.
    BOOTSTRAP,
    // Reliable-messaging outbox: runtime delivery state, re-driven from live
    // sends, not part of a state backup.
    OUTBOX,
    // Trust-Task idempotency records. Short-lived by construction (a retry
    // window, not durable state) and scoped to the VTA that served the original
    // request — restoring one elsewhere would claim to have already performed
    // operations that instance never did.
    IDEMPOTENCY,
    // TSP relationship state: durable across a restart, but re-establishable by
    // a re-handshake (design note D2/D3) and scoped to this VTA's DIDs — so a
    // restore re-drives it, like [`SESSIONS`], rather than carrying it.
    RELATIONSHIPS,
];

/// Rows inside a [`BACKED_UP`] keyspace that belong to the **deployment**, not
/// to the agent, as `(keyspace, key prefix)`.
///
/// A backup moves between a plain VTA, a hardened one and a Nitro enclave in
/// any direction. These rows only mean something in the environment that wrote
/// them, or are derived from that environment's storage key, so copying one
/// would be wrong on the target: the restore leaves them out and re-creates
/// what the target needs.
pub const ENVIRONMENT_BOUND_ROWS: &[(&str, &str)] = &[
    // TEE identity mirror, did.jsonl copy, Mode-B carve-out sentinel and the
    // legacy admin credential. The restore writes the target's own.
    (KEYS, "tee:"),
    // The hardened deployment's JWT key row. The key itself travels as the
    // payload's `jwt_signing_key` and lands wherever the target keeps it.
    (KEYS, "hardened:"),
    // Restore / import bookkeeping of the source.
    (KEYS, "backup:"),
    (KEYS, "restore:"),
    // Blinded persona indexes are keyed by an HMAC whose key is derived from
    // the storage key, so they are meaningless under any other one. The
    // restore rebuilds them from the rows they index.
    (PERSONA, "pxi:"),
    (PERSONA, "pxf:"),
    (PERSONA, "pxfv"),
    // Cached bearer tokens for DID-hosting daemons. Service-local secrets; a
    // restored VTA re-authenticates on first use.
    (WEBVH, "server-auth:"),
];

/// Whether `key` in `keyspace` is an [`ENVIRONMENT_BOUND_ROWS`] row.
#[must_use]
pub fn is_environment_bound(keyspace: &str, key: &[u8]) -> bool {
    ENVIRONMENT_BOUND_ROWS
        .iter()
        .any(|(ks, prefix)| *ks == keyspace && key.starts_with(prefix.as_bytes()))
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::collections::BTreeSet;

    /// The backup partition must be total and disjoint: every production
    /// keyspace is either backed up or explicitly excluded. Adding a keyspace
    /// to [`ALL`] without classifying it fails here — that's the point.
    #[test]
    fn backup_partition_is_total() {
        let all: BTreeSet<&str> = ALL.iter().copied().collect();
        let backed: BTreeSet<&str> = BACKED_UP.iter().copied().collect();
        let excluded: BTreeSet<&str> = EXCLUDED_FROM_BACKUP.iter().copied().collect();

        assert_eq!(all.len(), ALL.len(), "ALL has a duplicate");
        assert!(
            backed.is_disjoint(&excluded),
            "a keyspace is both backed up and excluded: {:?}",
            backed.intersection(&excluded).collect::<Vec<_>>()
        );
        let union: BTreeSet<&str> = backed.union(&excluded).copied().collect();
        assert_eq!(
            union, all,
            "backup partition is not exhaustive — every keyspace in ALL must be in \
             exactly one of BACKED_UP / EXCLUDED_FROM_BACKUP"
        );
    }

    /// An environment-bound rule for a keyspace a backup never carries would be
    /// dead, and one naming an unknown keyspace would be a typo that silently
    /// lets a deployment row travel.
    #[test]
    fn environment_bound_rows_name_backed_up_keyspaces() {
        for (ks, prefix) in ENVIRONMENT_BOUND_ROWS {
            assert!(
                BACKED_UP.contains(ks),
                "environment-bound rule ({ks}, {prefix}) names a keyspace that is not backed up"
            );
            assert!(
                !prefix.is_empty(),
                "an empty prefix would drop the whole keyspace"
            );
        }
    }

    #[test]
    fn environment_bound_rows_are_matched_by_prefix_within_their_keyspace() {
        assert!(is_environment_bound(KEYS, b"tee:vta_did"));
        assert!(is_environment_bound(KEYS, b"hardened:jwt_key"));
        assert!(is_environment_bound(PERSONA, b"pxi:abcd"));
        assert!(is_environment_bound(WEBVH, b"server-auth:srv1"));
        // Same prefix, different keyspace: carried.
        assert!(!is_environment_bound(ACL, b"tee:mode-b"));
        // The agent's own rows are carried.
        assert!(!is_environment_bound(KEYS, b"key:abc"));
        assert!(!is_environment_bound(PERSONA, b"pa:01H"));
        assert!(!is_environment_bound(WEBVH, b"server:srv1"));
    }
}

// ---------------------------------------------------------------------------
// What a DID deletion means for each keyspace
// ---------------------------------------------------------------------------

/// What happens to a keyspace's DID-keyed contents when that DID is deleted.
///
/// Deleting a DID is not one cleanup. It is four different relationships, and
/// treating them alike gets one of them wrong in a way nobody notices until it
/// matters:
///
/// * things the DID **owns** go with it;
/// * things that **name it as a subject of authorization** must go with it, or
///   they become authority for an identity that no longer resolves;
/// * things that **depend on it to function** must *stop* the deletion, because
///   cascading would silently break them;
/// * credentials the VTA **issued** cannot be deleted at all — copies exist
///   elsewhere — so the only honest action is revocation.
///
/// # Why this is an enum and not a list in a function
///
/// The failure mode is not getting today's answers wrong. It is a keyspace
/// added next quarter that nobody classifies, whose rows then quietly outlive
/// the DID they belong to. [`ALL`] is already pinned by a census test for the
/// backup partition, for exactly the same reason; this rides the same rail, so
/// "we forgot" is a red test rather than an orphan found months later in a log.
///
/// The classifications below are judgements and several are arguable. That is
/// fine — the point of the census is to force the question to be asked, not to
/// claim these answers are the last word.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DidDeleteEffect {
    /// Rows belonging to the DID are removed with it.
    Cascade,
    /// A row referencing the DID **blocks** the deletion: something still in
    /// use would break. Refused, never forced — the operator is told what to
    /// unpick first.
    Blocks,
    /// Rows cannot be removed, because the VTA is not the only holder. They
    /// are revoked instead.
    Revoke,
    /// Nothing here is keyed to a DID.
    Unrelated,
}

/// The effect a DID deletion has on `keyspace`, or `None` if the name is not a
/// keyspace this build knows.
///
/// Every entry in [`ALL`] is classified — see `did_delete_census` in this
/// module's tests.
#[must_use]
pub const fn did_delete_effect(keyspace: &str) -> Option<DidDeleteEffect> {
    use DidDeleteEffect::*;
    // `const fn` cannot match on `&str`, so this is a byte-slice match.
    Some(match keyspace.as_bytes() {
        // ---- Owned by the DID -------------------------------------------
        // Key material derived under it, its own log, its advertised name.
        b"keys" | b"internal_keys" | b"imported_secrets" | b"webvh" => Cascade,
        // Resolution + protocol caches keyed by DID: stale the moment it goes.
        b"cache" | b"outbox" => Cascade,
        // TSP relationships name this VTA's DID as one half of each `(our_vid,
        // their_vid)` pair; with that VID gone the relationship can neither send
        // nor be sent to, so its rows go with it — the same reasoning as the
        // protocol caches above. (The cascade removes rows keyed on the deleted
        // VID as `our_vid`; a peer VID appearing as `their_vid` of a *surviving*
        // local VID is a different pair and stays.)
        b"relationships" => Cascade,

        // ---- Names the DID as a subject of authorization -----------------
        // An ACL entry outliving its DID is the worst of the orphans: live
        // authority for an identity that can no longer be resolved or rotated.
        // The VTC learned this the expensive way (#1194, #1196).
        b"acl" | b"sessions" | b"passkey_vms" => Cascade,
        // Consent state and the vault are held *for* a holder; with the holder
        // gone they are unreachable by anyone.
        b"consent" | b"task_consent" | b"vault" => Cascade,
        // Per-DID application state the VTA stores on a holder's behalf.
        b"app_state" | b"memory" => Cascade,
        // A member's room groups, and the invitations they were joined under.
        // Held for the holder in the same sense the vault is: the group state
        // decrypts a room *that member* belongs to, and with the member gone
        // nobody can use it or ever will again. Keeping it would leave group
        // secrets on disk outliving the only party they were for.
        //
        // The consumed-invitation records go with them and not before: while
        // the member exists, a consumed invitation MUST outlive the group it
        // let them join, or leaving a room would make the same invitation work
        // twice. Single use means single use, and the record is the only thing
        // that remembers.
        b"room_groups" | b"room_invitations" => Cascade,

        // Persona is two scopes in one keyspace and only one half is DID-keyed,
        // which the per-keyspace enum cannot say — so it is said here. The
        // context-scoped rows DO belong to a DID: a binding is keyed by the
        // persona DID, and a contact records the persona that knows it. Those
        // cascade, because a binding for a DID that can no longer be resolved is
        // the ACL orphan again in a different keyspace. The agent-scoped rows —
        // the attribute pool, the profiles, and their indexes — are keyed to no
        // DID and survive, which is correct: a profile may be bound to several
        // personas, and deleting one persona must not destroy facts the holder
        // still presents through another.
        b"persona" => Cascade,

        // ---- Depends on the DID to function ------------------------------
        // A context whose `did` is this one, a DID named in an advertised
        // service entry (or its rollback snapshot), a policy or approver set
        // that names it. Cascading any of these breaks something that is still
        // in use; refusing tells the operator what to unpick.
        b"contexts" | b"service_state" | b"service_prev_config" => Blocks,
        b"policy" | b"consent_approvers" => Blocks,

        // ---- Cannot be deleted, only revoked -----------------------------
        // Third parties hold copies. Deleting our record achieves nothing but
        // losing our ability to revoke it.
        b"issued_credentials" => Revoke,

        // ---- Not keyed to a DID ------------------------------------------
        // The audit log is deliberately here: it is append-only, and the record
        // that a DID was deleted is the one thing that must survive deleting it.
        b"audit" | b"audit_key" => Unrelated,
        b"did_templates" | b"sealed_nonces" | b"backup_bundles" => Unrelated,
        b"drains" | b"bootstrap" | b"idempotency" => Unrelated,

        _ => return None,
    })
}

#[cfg(test)]
mod did_delete_tests {
    use super::*;

    /// Every keyspace must have an answer to "what happens to this when a DID
    /// is deleted".
    ///
    /// This is the whole point of the classification. Adding a keyspace is
    /// easy; remembering that its rows might outlive the DID they belong to is
    /// not, and nothing about adding one prompts the question. This test asks
    /// it, once, at the only moment anyone is looking.
    ///
    /// A new keyspace fails here until it is classified. `Unrelated` is a
    /// perfectly good answer — but it has to be a chosen one.
    #[test]
    fn every_keyspace_is_classified_for_did_deletion() {
        let unclassified: Vec<&str> = ALL
            .iter()
            .copied()
            .filter(|ks| did_delete_effect(ks).is_none())
            .collect();
        assert!(
            unclassified.is_empty(),
            "these keyspaces have no DID-deletion effect declared: {unclassified:?}\n\
             Add them to `did_delete_effect`. `Unrelated` is a fine answer if \
             nothing in the keyspace is keyed to a DID — but it must be chosen, \
             not defaulted."
        );
    }

    /// An unknown name is not silently `Unrelated`. The distinction matters:
    /// `None` means "this build does not know that keyspace", and answering
    /// `Unrelated` to it would let a typo read as "nothing to clean up".
    #[test]
    fn an_unknown_keyspace_has_no_effect_rather_than_a_harmless_one() {
        assert_eq!(did_delete_effect("not_a_keyspace"), None);
        assert_eq!(did_delete_effect(""), None);
    }

    /// The credential keyspace must never be classified `Cascade`.
    ///
    /// Pinned explicitly because it is the one that looks most like a cascade
    /// and is not: the VTA is not the only holder of what it issued, so
    /// deleting our record destroys the ability to revoke it while leaving
    /// every copy in the wild valid forever. That is the exact residue an ACL
    /// revoke left behind on the VTC.
    #[test]
    fn issued_credentials_are_revoked_never_deleted() {
        assert_eq!(
            did_delete_effect(ISSUED_CREDENTIALS),
            Some(DidDeleteEffect::Revoke)
        );
    }

    /// The audit log must survive the deletion it records.
    #[test]
    fn the_audit_log_is_never_cascaded() {
        assert_eq!(did_delete_effect(AUDIT), Some(DidDeleteEffect::Unrelated));
    }
}