@feltdb/core 0.9.1 → 0.10.0

package/dist/create/server-source/crates/feltdb-server/src/canonical_principals.rs

@@ -0,0 +1,1093 @@
+//! Canonical principal authority and one-way legacy import.
+//!
+//! This module is deliberately narrower than the public principal API. It is
+//! the first 0.10A migration primitive: legacy JSON is accepted only as input,
+//! while every accepted record is committed to FeltDB transaction history.
+
+use crate::{
+    authorization::{authorize, AuthorizationRequest, Subject},
+    principals::{PrincipalAuditEvent, PrincipalKind, PrincipalRecord, PrincipalStatus},
+    tenancy::TenancyStore,
+};
+use feltdb::{application::ApplicationStore, AtomicMutation, AtomicPrecondition, FeltDb};
+use rand::{distributions::Alphanumeric, Rng};
+use serde::{Deserialize, Serialize};
+use serde_json::{json, Value};
+use sha2::{Digest, Sha256};
+use std::{fs, path::Path};
+
+pub const PRINCIPAL_COLLECTION: &str = "system_principals";
+pub const PRINCIPAL_AUDIT_COLLECTION: &str = "system_principal_authorization_decisions";
+pub const APPLICATION_OWNERSHIP_COLLECTION: &str = "system_application_ownership";
+pub const APPLICATION_OWNERSHIP_MIGRATION_VERSION: &str =
+    "application-ownership-backfill/v1";
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
+pub struct CanonicalApplicationOwnership {
+    pub application_id: String,
+    pub tenant_id: String,
+    pub source_authority: String,
+    pub source_record_id: String,
+    pub source_digest: String,
+    pub authorization_reference: String,
+    pub authorized_by: String,
+    pub authorized_at: String,
+    pub migration_version: String,
+    pub reason: String,
+}
+
+impl CanonicalApplicationOwnership {
+    fn is_valid_for(&self, application_id: &str) -> bool {
+        self.application_id == application_id
+            && !self.tenant_id.trim().is_empty()
+            && !self.source_authority.trim().is_empty()
+            && !self.source_record_id.trim().is_empty()
+            && self.source_digest.len() == 71
+            && self.source_digest.starts_with("sha256:")
+            && self.source_digest[7..]
+                .bytes()
+                .all(|byte| byte.is_ascii_hexdigit() && !byte.is_ascii_uppercase())
+            && !self.authorization_reference.trim().is_empty()
+            && !self.authorized_by.trim().is_empty()
+            && !self.authorized_at.trim().is_empty()
+            && self.migration_version == APPLICATION_OWNERSHIP_MIGRATION_VERSION
+            && !self.reason.trim().is_empty()
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CanonicalPrincipal {
+    pub tenant_id: String,
+    pub application_id: String,
+    pub principal: PrincipalRecord,
+    pub source_digest: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct CanonicalPrincipalAudit {
+    tenant_id: String,
+    application_id: String,
+    event: PrincipalAuditEvent,
+    source_digest: String,
+}
+
+#[derive(Debug, Default, Serialize, Deserialize)]
+struct LegacyPrincipalRecords {
+    #[serde(default)]
+    principals: Vec<PrincipalRecord>,
+    #[serde(default)]
+    audit: Vec<PrincipalAuditEvent>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct PrincipalMigrationEvidence {
+    pub principals: usize,
+    pub audit_events: usize,
+    pub verified_existing: usize,
+    pub committed: usize,
+}
+
+/// Resolve principal scope only from canonical application ownership facts.
+/// Tenancy registration and committed application-definition records are
+/// independent observations of the same relationship and must agree.
+pub fn resolve_principal_tenant(
+    application_id: &str,
+    tenancy: &TenancyStore,
+    applications: &ApplicationStore,
+    db: &FeltDb,
+) -> Result<String, String> {
+    let mut ownership_candidates = applications.tenant_ownership_candidates(application_id);
+    if let Some(value) = db
+        .get_value(&application_ownership_key(application_id))
+        .map_err(|error| error.to_string())?
+    {
+        let ownership: CanonicalApplicationOwnership = serde_json::from_value(value).map_err(|_| {
+            format!(
+                "PRINCIPAL_TENANT_MIGRATION_CONFLICT:INVALID_OWNERSHIP:{application_id}"
+            )
+        })?;
+        if !ownership.is_valid_for(application_id) {
+            return Err(format!(
+                "PRINCIPAL_TENANT_MIGRATION_CONFLICT:INVALID_OWNERSHIP:{application_id}"
+            ));
+        }
+        ownership_candidates.push(ownership.tenant_id);
+    }
+    let tenant = resolve_principal_tenant_candidates(
+        application_id,
+        tenancy.application_tenant_candidates(application_id),
+        ownership_candidates,
+    )?;
+    if !tenancy.tenant_exists(&tenant) {
+        return Err(format!(
+            "PRINCIPAL_TENANT_MIGRATION_CONFLICT:MISSING_TENANT:{application_id}:{tenant}"
+        ));
+    }
+    Ok(tenant)
+}
+
+pub fn application_ownership_key(application_id: &str) -> String {
+    format!("{APPLICATION_OWNERSHIP_COLLECTION}:{application_id}")
+}
+
+fn resolve_principal_tenant_candidates(
+    application_id: &str,
+    tenancy_candidates: Vec<String>,
+    application_candidates: Vec<String>,
+) -> Result<String, String> {
+    let candidates = tenancy_candidates
+        .into_iter()
+        .chain(application_candidates)
+        .filter(|tenant| !tenant.trim().is_empty())
+        .collect::<std::collections::BTreeSet<_>>();
+    match candidates.len() {
+        0 => Err(format!(
+            "PRINCIPAL_TENANT_MIGRATION_CONFLICT:MISSING_OWNERSHIP:{application_id}"
+        )),
+        1 => Ok(candidates.into_iter().next().expect("one candidate")),
+        _ => Err(format!(
+            "PRINCIPAL_TENANT_MIGRATION_CONFLICT:AMBIGUOUS_OWNERSHIP:{application_id}"
+        )),
+    }
+}
+
+#[derive(Clone)]
+pub struct CanonicalPrincipalAuthority {
+    db: FeltDb,
+}
+
+impl CanonicalPrincipalAuthority {
+    pub fn new(db: FeltDb) -> Self {
+        Self { db }
+    }
+
+    pub fn get(
+        &self,
+        tenant_id: &str,
+        application_id: &str,
+        principal_id: &str,
+    ) -> Result<Option<CanonicalPrincipal>, String> {
+        self.db
+            .get_collection_record(
+                PRINCIPAL_COLLECTION,
+                &principal_key(tenant_id, application_id, principal_id),
+            )
+            .map_err(|error| error.to_string())?
+            .map(|row| serde_json::from_value(row.value).map_err(|error| error.to_string()))
+            .transpose()
+    }
+
+    pub fn list_canonical(
+        &self,
+        tenant_id: &str,
+        application_id: &str,
+    ) -> Result<Vec<CanonicalPrincipal>, String> {
+        let mut records = self
+            .db
+            .query_collection(PRINCIPAL_COLLECTION, None, |row| {
+                row.value.get("tenant_id").and_then(Value::as_str) == Some(tenant_id)
+                    && row.value.get("application_id").and_then(Value::as_str)
+                        == Some(application_id)
+            })
+            .map_err(|error| error.to_string())?
+            .into_iter()
+            .map(|row| serde_json::from_value(row.value).map_err(|error| error.to_string()))
+            .collect::<Result<Vec<_>, _>>()?;
+        records
+            .sort_by(|left: &CanonicalPrincipal, right| left.principal.id.cmp(&right.principal.id));
+        Ok(records)
+    }
+
+    pub fn list(
+        &self,
+        actor: &str,
+        tenancy: &TenancyStore,
+        application_id: &str,
+    ) -> Result<Vec<PrincipalRecord>, String> {
+        let tenant_id = application_context(tenancy, application_id)?;
+        if !tenancy.authorize_application(actor, &tenant_id, application_id, "applications:read") {
+            return Err("forbidden".into());
+        }
+        Ok(self
+            .list_canonical(&tenant_id, application_id)?
+            .into_iter()
+            .map(|value| value.principal)
+            .collect())
+    }
+
+    pub fn create(
+        &self,
+        actor: &str,
+        tenancy: &TenancyStore,
+        application_id: &str,
+        kind: PrincipalKind,
+        name: &str,
+    ) -> Result<PrincipalRecord, String> {
+        let tenant_id = application_context(tenancy, application_id)?;
+        let required = match kind {
+            PrincipalKind::Agent => "agents:write",
+            PrincipalKind::Connection => "connections:write",
+            _ => "applications:write",
+        };
+        if !tenancy.authorize_application(actor, &tenant_id, application_id, required) {
+            return Err("forbidden".into());
+        }
+        let prefix = match kind {
+            PrincipalKind::Agent => "agent",
+            PrincipalKind::Workload => "workload",
+            PrincipalKind::Service => "service",
+            PrincipalKind::Worker => "worker",
+            PrincipalKind::Connection => "connection",
+        };
+        let principal = PrincipalRecord {
+            id: runtime_id(prefix),
+            application_id: application_id.into(),
+            kind,
+            name: name.into(),
+            version: 1,
+            status: PrincipalStatus::Active,
+            created_by: actor.into(),
+            created_at: now(),
+            capabilities: vec![],
+            parent_id: None,
+            worker_id: None,
+            started_at: None,
+            completed_at: None,
+        };
+        self.commit_principal(
+            &tenant_id,
+            &principal,
+            None,
+            PrincipalAuditEvent {
+                event: "principal.created".into(),
+                actor: actor.into(),
+                principal_id: principal.id.clone(),
+                application_id: application_id.into(),
+                capability: None,
+                decision: None,
+                at: now(),
+            },
+        )?;
+        Ok(principal)
+    }
+
+    pub fn grant(
+        &self,
+        actor: &str,
+        tenancy: &TenancyStore,
+        principal_id: &str,
+        capability: &str,
+    ) -> Result<PrincipalRecord, String> {
+        if capability == "secrets:plaintext" {
+            return Err("plaintext secret access cannot be granted".into());
+        }
+        let (tenant_id, mut principal, sequence) = self.find(principal_id)?;
+        if actor == principal_id
+            || !tenancy.authorize_application(
+                actor,
+                &tenant_id,
+                &principal.application_id,
+                "applications:write",
+            )
+        {
+            return Err("forbidden".into());
+        }
+        if !principal.capabilities.iter().any(|held| held == capability) {
+            principal.capabilities.push(capability.into());
+            principal.version += 1;
+        }
+        self.commit_principal(
+            &tenant_id,
+            &principal,
+            Some(sequence),
+            PrincipalAuditEvent {
+                event: "principal.capability_granted".into(),
+                actor: actor.into(),
+                principal_id: principal.id.clone(),
+                application_id: principal.application_id.clone(),
+                capability: Some(capability.into()),
+                decision: None,
+                at: now(),
+            },
+        )?;
+        Ok(principal)
+    }
+
+    pub fn authorize(&self, principal_id: &str, application_id: &str, capability: &str) -> bool {
+        let Ok((tenant_id, principal, _)) = self.find(principal_id) else {
+            return false;
+        };
+        let active = matches!(
+            principal.status,
+            PrincipalStatus::Active | PrincipalStatus::Running
+        ) && principal.application_id == application_id;
+        let allowed = active
+            && capability != "secrets:plaintext"
+            && authorize(&AuthorizationRequest {
+                subject: &kind_subject(&principal),
+                tenant_id: &tenant_id,
+                application_id: Some(application_id),
+                capability,
+                direct_grants: &principal.capabilities,
+                memberships: &[],
+                roles: &[],
+            })
+            .allowed;
+        if self
+            .commit_audit(
+                &tenant_id,
+                PrincipalAuditEvent {
+                    event: "principal.authorized".into(),
+                    actor: principal_id.into(),
+                    principal_id: principal_id.into(),
+                    application_id: application_id.into(),
+                    capability: Some(capability.into()),
+                    decision: Some(allowed),
+                    at: now(),
+                },
+            )
+            .is_err()
+        {
+            return false;
+        }
+        allowed
+    }
+
+    pub fn create_workload(
+        &self,
+        actor: &str,
+        tenancy: &TenancyStore,
+        agent_id: &str,
+    ) -> Result<PrincipalRecord, String> {
+        let (tenant_id, agent, _) = self.find(agent_id)?;
+        if agent.kind != PrincipalKind::Agent {
+            return Err("agent not found".into());
+        }
+        if !tenancy.authorize_application(
+            actor,
+            &tenant_id,
+            &agent.application_id,
+            "workloads:execute",
+        ) && !tenancy.authorize_application(
+            actor,
+            &tenant_id,
+            &agent.application_id,
+            "applications:write",
+        ) {
+            return Err("forbidden".into());
+        }
+        let principal = PrincipalRecord {
+            id: runtime_id("workload"),
+            application_id: agent.application_id.clone(),
+            kind: PrincipalKind::Workload,
+            name: format!("{} execution", agent.name),
+            version: agent.version,
+            status: PrincipalStatus::Running,
+            created_by: actor.into(),
+            created_at: now(),
+            capabilities: agent.capabilities,
+            parent_id: Some(agent.id),
+            worker_id: None,
+            started_at: Some(now()),
+            completed_at: None,
+        };
+        self.commit_principal(
+            &tenant_id,
+            &principal,
+            None,
+            PrincipalAuditEvent {
+                event: "workload.created".into(),
+                actor: actor.into(),
+                principal_id: principal.id.clone(),
+                application_id: principal.application_id.clone(),
+                capability: None,
+                decision: None,
+                at: now(),
+            },
+        )?;
+        Ok(principal)
+    }
+
+    pub fn assign_worker(
+        &self,
+        actor: &str,
+        tenancy: &TenancyStore,
+        workload_id: &str,
+        worker_id: &str,
+    ) -> Result<(), String> {
+        let (tenant_id, mut workload, sequence) = self.find(workload_id)?;
+        let (worker_tenant, worker, _) = self.find(worker_id)?;
+        if workload.kind != PrincipalKind::Workload {
+            return Err("workload not found".into());
+        }
+        if worker.kind != PrincipalKind::Worker {
+            return Err("worker not found".into());
+        }
+        if worker_tenant != tenant_id || worker.application_id != workload.application_id {
+            return Err("cross-application worker assignment denied".into());
+        }
+        if !tenancy.authorize_application(
+            actor,
+            &tenant_id,
+            &workload.application_id,
+            "applications:write",
+        ) {
+            return Err("forbidden".into());
+        }
+        workload.worker_id = Some(worker_id.into());
+        workload.version += 1;
+        self.commit_principal(
+            &tenant_id,
+            &workload,
+            Some(sequence),
+            PrincipalAuditEvent {
+                event: "workload.worker_assigned".into(),
+                actor: actor.into(),
+                principal_id: workload.id.clone(),
+                application_id: workload.application_id.clone(),
+                capability: None,
+                decision: None,
+                at: now(),
+            },
+        )
+    }
+
+    pub fn worker_can_execute(&self, worker_id: &str, workload_id: &str) -> bool {
+        self.find(workload_id).is_ok_and(|(_, workload, _)| {
+            workload.kind == PrincipalKind::Workload
+                && workload.worker_id.as_deref() == Some(worker_id)
+                && workload.status == PrincipalStatus::Running
+        })
+    }
+
+    pub fn execution_snapshot(
+        &self,
+        worker_id: &str,
+        workload_id: &str,
+    ) -> Option<(String, String, Vec<String>)> {
+        let (_, workload, _) = self.find(workload_id).ok()?;
+        (workload.kind == PrincipalKind::Workload
+            && workload.worker_id.as_deref() == Some(worker_id)
+            && workload.status == PrincipalStatus::Running)
+            .then(|| (workload.application_id, workload.id, workload.capabilities))
+    }
+
+    pub fn audit_for(
+        &self,
+        actor: &str,
+        tenancy: &TenancyStore,
+        application_id: &str,
+        principal_id: Option<&str>,
+        limit: usize,
+    ) -> Result<Vec<PrincipalAuditEvent>, String> {
+        let tenant_id = application_context(tenancy, application_id)?;
+        if !tenancy.authorize_application(actor, &tenant_id, application_id, "applications:read") {
+            return Err("forbidden".into());
+        }
+        let mut events = self
+            .db
+            .query_collection(PRINCIPAL_AUDIT_COLLECTION, None, |row| {
+                row.value.get("tenant_id").and_then(Value::as_str) == Some(&tenant_id)
+                    && row.value.get("application_id").and_then(Value::as_str)
+                        == Some(application_id)
+                    && principal_id.is_none_or(|id| {
+                        row.value
+                            .get("event")
+                            .and_then(|event| event.get("principal_id"))
+                            .and_then(Value::as_str)
+                            == Some(id)
+                    })
+            })
+            .map_err(|error| error.to_string())?
+            .into_iter()
+            .map(|row| {
+                serde_json::from_value::<CanonicalPrincipalAudit>(row.value)
+                    .map(|value| value.event)
+                    .map_err(|error| error.to_string())
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+        events.sort_by_key(|event| std::cmp::Reverse(event.at));
+        events.truncate(limit);
+        Ok(events)
+    }
+
+    /// Import a legacy file in one direction only.
+    ///
+    /// The caller resolves application-to-tenant ownership from the canonical
+    /// tenancy authority. Existing identical records are verified. An identity
+    /// whose canonical digest differs is a hard conflict and is never replaced.
+    pub fn migrate_legacy_file(
+        &self,
+        path: &Path,
+        tenant_for_application: impl Fn(&str) -> Result<String, String>,
+    ) -> Result<PrincipalMigrationEvidence, String> {
+        let bytes = fs::read(path).map_err(|error| error.to_string())?;
+        let legacy: LegacyPrincipalRecords =
+            serde_json::from_slice(&bytes).map_err(|error| error.to_string())?;
+        let mut evidence = PrincipalMigrationEvidence {
+            principals: legacy.principals.len(),
+            audit_events: legacy.audit.len(),
+            verified_existing: 0,
+            committed: 0,
+        };
+
+        for principal in legacy.principals {
+            let tenant_id = tenant_for_application(&principal.application_id)?;
+            let source_digest = digest(&principal)?;
+            let canonical = CanonicalPrincipal {
+                tenant_id: tenant_id.clone(),
+                application_id: principal.application_id.clone(),
+                principal: principal.clone(),
+                source_digest: source_digest.clone(),
+            };
+            let key = principal_key(&tenant_id, &principal.application_id, &principal.id);
+            if let Some(existing) =
+                self.get(&tenant_id, &principal.application_id, &principal.id)?
+            {
+                if existing.source_digest != source_digest
+                    || digest(&existing.principal)? != source_digest
+                {
+                    return Err(format!("PRINCIPAL_MIGRATION_CONFLICT:{}", principal.id));
+                }
+                evidence.verified_existing += 1;
+                continue;
+            }
+            let transaction_id = migration_transaction_id(
+                "principal",
+                &tenant_id,
+                &principal.application_id,
+                &source_digest,
+            );
+            self.commit_insert(
+                &transaction_id,
+                PRINCIPAL_COLLECTION,
+                &key,
+                serde_json::to_value(&canonical).map_err(|error| error.to_string())?,
+                json!({
+                    "kind": "principal_migration",
+                    "subject": principal.created_by,
+                    "tenant": tenant_id,
+                    "application": principal.application_id,
+                    "principal_id": principal.id,
+                    "agent_id": (principal.kind == PrincipalKind::Agent).then(|| principal.id.as_str()),
+                    "delegator_id": principal.parent_id.as_deref().unwrap_or(&principal.created_by),
+                    "operation_id": transaction_id,
+                    "source_digest": source_digest,
+                }),
+            )?;
+            evidence.committed += 1;
+        }
+
+        for (position, event) in legacy.audit.into_iter().enumerate() {
+            let tenant_id = tenant_for_application(&event.application_id)?;
+            let source_digest = digest(&event)?;
+            let key = audit_key(
+                &tenant_id,
+                &event.application_id,
+                &event.principal_id,
+                &source_digest,
+            );
+            let value = CanonicalPrincipalAudit {
+                tenant_id: tenant_id.clone(),
+                application_id: event.application_id.clone(),
+                event: event.clone(),
+                source_digest: source_digest.clone(),
+            };
+            if let Some(existing) = self
+                .db
+                .get_collection_record(PRINCIPAL_AUDIT_COLLECTION, &key)
+                .map_err(|error| error.to_string())?
+            {
+                let existing: CanonicalPrincipalAudit =
+                    serde_json::from_value(existing.value).map_err(|error| error.to_string())?;
+                if existing.source_digest != source_digest {
+                    return Err(format!(
+                        "PRINCIPAL_AUDIT_MIGRATION_CONFLICT:{}:{}",
+                        event.principal_id, position
+                    ));
+                }
+                evidence.verified_existing += 1;
+                continue;
+            }
+            self.commit_insert(
+                &migration_transaction_id(
+                    "principal_audit",
+                    &tenant_id,
+                    &event.application_id,
+                    &source_digest,
+                ),
+                PRINCIPAL_AUDIT_COLLECTION,
+                &key,
+                serde_json::to_value(value).map_err(|error| error.to_string())?,
+                json!({
+                    "kind": "principal_audit_migration",
+                    "subject": event.actor,
+                    "tenant": tenant_id,
+                    "application": event.application_id,
+                    "principal_id": event.principal_id,
+                    "source_digest": source_digest,
+                }),
+            )?;
+            evidence.committed += 1;
+        }
+        Ok(evidence)
+    }
+
+    fn find(&self, principal_id: &str) -> Result<(String, PrincipalRecord, u64), String> {
+        let mut rows = self
+            .db
+            .query_collection(PRINCIPAL_COLLECTION, Some(2), |row| {
+                row.value
+                    .get("principal")
+                    .and_then(|principal| principal.get("id"))
+                    .and_then(Value::as_str)
+                    == Some(principal_id)
+            })
+            .map_err(|error| error.to_string())?;
+        if rows.len() > 1 {
+            return Err(format!("ambiguous principal identity: {principal_id}"));
+        }
+        let row = rows
+            .pop()
+            .ok_or_else(|| "principal not found".to_string())?;
+        let sequence = row
+            .operation
+            .as_ref()
+            .map(|operation| operation.sequence)
+            .ok_or_else(|| "canonical principal has no operation identity".to_string())?;
+        let value: CanonicalPrincipal =
+            serde_json::from_value(row.value).map_err(|error| error.to_string())?;
+        Ok((value.tenant_id, value.principal, sequence))
+    }
+
+    fn commit_principal(
+        &self,
+        tenant_id: &str,
+        principal: &PrincipalRecord,
+        expected_version: Option<u64>,
+        event: PrincipalAuditEvent,
+    ) -> Result<(), String> {
+        let transaction_id = runtime_id("principal_tx");
+        let principal_key = principal_key(tenant_id, &principal.application_id, &principal.id);
+        let audit_key = format!(
+            "{}/{}/{}/{}",
+            tenant_id, principal.application_id, principal.id, transaction_id
+        );
+        let canonical = CanonicalPrincipal {
+            tenant_id: tenant_id.into(),
+            application_id: principal.application_id.clone(),
+            principal: principal.clone(),
+            source_digest: digest(principal)?,
+        };
+        let audit = CanonicalPrincipalAudit {
+            tenant_id: tenant_id.into(),
+            application_id: principal.application_id.clone(),
+            event: event.clone(),
+            source_digest: digest(&event)?,
+        };
+        self.db
+            .apply_atomic_transaction(
+                &transaction_id,
+                None,
+                &[
+                    AtomicPrecondition {
+                        capability: PRINCIPAL_COLLECTION.into(),
+                        key: principal_key.clone(),
+                        expected_version,
+                    },
+                    AtomicPrecondition {
+                        capability: PRINCIPAL_AUDIT_COLLECTION.into(),
+                        key: audit_key.clone(),
+                        expected_version: None,
+                    },
+                ],
+                &[
+                    AtomicMutation {
+                        capability: PRINCIPAL_COLLECTION.into(),
+                        key: principal_key,
+                        value: Some(
+                            serde_json::to_value(canonical).map_err(|error| error.to_string())?,
+                        ),
+                    },
+                    AtomicMutation {
+                        capability: PRINCIPAL_AUDIT_COLLECTION.into(),
+                        key: audit_key,
+                        value: Some(
+                            serde_json::to_value(audit).map_err(|error| error.to_string())?,
+                        ),
+                    },
+                ],
+                Some(json!({
+                    "kind": event.event,
+                    "subject": event.actor,
+                    "tenant": tenant_id,
+                    "application": principal.application_id,
+                    "principal_id": principal.id,
+                })),
+            )
+            .map(|_| ())
+            .map_err(|error| error.to_string())
+    }
+
+    fn commit_audit(&self, tenant_id: &str, event: PrincipalAuditEvent) -> Result<(), String> {
+        let transaction_id = runtime_id("principal_decision_tx");
+        let key = format!(
+            "{}/{}/{}/{}",
+            tenant_id, event.application_id, event.principal_id, transaction_id
+        );
+        let audit = CanonicalPrincipalAudit {
+            tenant_id: tenant_id.into(),
+            application_id: event.application_id.clone(),
+            source_digest: digest(&event)?,
+            event: event.clone(),
+        };
+        self.commit_insert(
+            &transaction_id,
+            PRINCIPAL_AUDIT_COLLECTION,
+            &key,
+            serde_json::to_value(audit).map_err(|error| error.to_string())?,
+            json!({
+                "kind": event.event,
+                "subject": event.actor,
+                "tenant": tenant_id,
+                "application": event.application_id,
+                "principal_id": event.principal_id,
+                "delegator_id": event.actor,
+                "operation_id": transaction_id,
+            }),
+        )
+    }
+
+    fn commit_insert(
+        &self,
+        transaction_id: &str,
+        collection: &str,
+        key: &str,
+        value: Value,
+        audit: Value,
+    ) -> Result<(), String> {
+        self.db
+            .apply_atomic_transaction(
+                transaction_id,
+                None,
+                &[AtomicPrecondition {
+                    capability: collection.into(),
+                    key: key.into(),
+                    expected_version: None,
+                }],
+                &[AtomicMutation {
+                    capability: collection.into(),
+                    key: key.into(),
+                    value: Some(value),
+                }],
+                Some(audit),
+            )
+            .map(|_| ())
+            .map_err(|error| error.to_string())
+    }
+}
+
+fn principal_key(tenant: &str, application: &str, principal: &str) -> String {
+    format!("{tenant}/{application}/{principal}")
+}
+
+fn application_context(tenancy: &TenancyStore, application_id: &str) -> Result<String, String> {
+    tenancy
+        .application_tenant(application_id)
+        .ok_or_else(|| "application not found".into())
+}
+
+fn kind_subject(record: &PrincipalRecord) -> Subject {
+    match record.kind {
+        PrincipalKind::Agent => Subject::Agent(record.id.clone()),
+        PrincipalKind::Workload => Subject::Workload(record.id.clone()),
+        PrincipalKind::Service => Subject::Service(record.id.clone()),
+        PrincipalKind::Worker => Subject::Worker(record.id.clone()),
+        PrincipalKind::Connection => Subject::Connection(record.id.clone()),
+    }
+}
+
+fn runtime_id(prefix: &str) -> String {
+    let value: String = rand::thread_rng()
+        .sample_iter(&Alphanumeric)
+        .take(24)
+        .map(char::from)
+        .collect();
+    format!("{prefix}_{value}")
+}
+
+fn now() -> u64 {
+    std::time::SystemTime::now()
+        .duration_since(std::time::UNIX_EPOCH)
+        .unwrap_or_default()
+        .as_secs()
+}
+
+fn audit_key(tenant: &str, application: &str, principal: &str, digest: &str) -> String {
+    format!("{tenant}/{application}/{principal}/{}", &digest[7..])
+}
+
+fn digest(value: &impl Serialize) -> Result<String, String> {
+    let bytes = serde_json::to_vec(value).map_err(|error| error.to_string())?;
+    Ok(format!("sha256:{:x}", Sha256::digest(bytes)))
+}
+
+fn migration_transaction_id(kind: &str, tenant: &str, application: &str, digest: &str) -> String {
+    let scoped = Sha256::digest(format!("{kind}\0{tenant}\0{application}\0{digest}").as_bytes());
+    format!("migrate_{kind}_{scoped:x}")
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::principals::{PrincipalKind, PrincipalStatus};
+    use std::time::{SystemTime, UNIX_EPOCH};
+
+    fn path(label: &str) -> std::path::PathBuf {
+        std::env::temp_dir().join(format!(
+            "feltdb-canonical-principal-{label}-{}-{}",
+            std::process::id(),
+            SystemTime::now()
+                .duration_since(UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        ))
+    }
+
+    fn principal() -> PrincipalRecord {
+        PrincipalRecord {
+            id: "agent_stable".into(),
+            application_id: "app_a".into(),
+            kind: PrincipalKind::Agent,
+            name: "Stable Agent".into(),
+            version: 3,
+            status: PrincipalStatus::Active,
+            created_by: "principal_delegator".into(),
+            created_at: 100,
+            capabilities: vec!["state:read".into()],
+            parent_id: None,
+            worker_id: None,
+            started_at: None,
+            completed_at: None,
+        }
+    }
+
+    #[test]
+    fn migration_is_idempotent_and_survives_deleting_the_source() {
+        let db_path = path("db");
+        let legacy_path = path("principals.json");
+        let records = LegacyPrincipalRecords {
+            principals: vec![principal()],
+            audit: vec![],
+        };
+        fs::write(&legacy_path, serde_json::to_vec(&records).unwrap()).unwrap();
+
+        let authority = CanonicalPrincipalAuthority::new(FeltDb::open(&db_path).unwrap());
+        let first = authority
+            .migrate_legacy_file(&legacy_path, |_| Ok("tenant_a".into()))
+            .unwrap();
+        assert_eq!(first.committed, 1);
+        let second = authority
+            .migrate_legacy_file(&legacy_path, |_| Ok("tenant_a".into()))
+            .unwrap();
+        assert_eq!(second.verified_existing, 1);
+        fs::remove_file(&legacy_path).unwrap();
+        drop(authority);
+
+        let reopened = CanonicalPrincipalAuthority::new(FeltDb::open(&db_path).unwrap());
+        let recovered = reopened
+            .get("tenant_a", "app_a", "agent_stable")
+            .unwrap()
+            .unwrap();
+        assert_eq!(recovered.principal.created_by, "principal_delegator");
+        assert_eq!(recovered.principal.version, 3);
+    }
+
+    #[test]
+    fn migration_detects_identity_conflicts() {
+        let db_path = path("conflict-db");
+        let legacy_path = path("conflict-principals.json");
+        let records = LegacyPrincipalRecords {
+            principals: vec![principal()],
+            audit: vec![],
+        };
+        fs::write(&legacy_path, serde_json::to_vec(&records).unwrap()).unwrap();
+        let authority = CanonicalPrincipalAuthority::new(FeltDb::open(&db_path).unwrap());
+        authority
+            .migrate_legacy_file(&legacy_path, |_| Ok("tenant_a".into()))
+            .unwrap();
+        let mut changed = principal();
+        changed.name = "Different".into();
+        fs::write(
+            &legacy_path,
+            serde_json::to_vec(&LegacyPrincipalRecords {
+                principals: vec![changed],
+                audit: vec![],
+            })
+            .unwrap(),
+        )
+        .unwrap();
+        let error = authority
+            .migrate_legacy_file(&legacy_path, |_| Ok("tenant_a".into()))
+            .unwrap_err();
+        assert_eq!(error, "PRINCIPAL_MIGRATION_CONFLICT:agent_stable");
+    }
+
+    #[test]
+    fn principal_tenant_resolution_accepts_one_canonical_owner() {
+        assert_eq!(
+            resolve_principal_tenant_candidates(
+                "app_pKEN4gJ0lvQV4D2ZWa",
+                vec![],
+                vec!["tenant_a".into(), "tenant_a".into()],
+            )
+            .unwrap(),
+            "tenant_a"
+        );
+        assert_eq!(
+            resolve_principal_tenant_candidates(
+                "app_a",
+                vec!["tenant_a".into()],
+                vec!["tenant_a".into()],
+            )
+            .unwrap(),
+            "tenant_a"
+        );
+    }
+
+    #[test]
+    fn principal_missing_tenant_and_application_fail_closed() {
+        let error = resolve_principal_tenant_candidates("app_missing", vec![], vec![])
+            .unwrap_err();
+        assert_eq!(
+            error,
+            "PRINCIPAL_TENANT_MIGRATION_CONFLICT:MISSING_OWNERSHIP:app_missing"
+        );
+    }
+
+    #[test]
+    fn principal_ambiguous_tenant_and_cross_tenant_reference_fail_closed() {
+        for (tenancy, applications) in [
+            (vec!["tenant_a".into(), "tenant_b".into()], vec![]),
+            (vec!["tenant_a".into()], vec!["tenant_b".into()]),
+        ] {
+            let error = resolve_principal_tenant_candidates("app_a", tenancy, applications)
+                .unwrap_err();
+            assert_eq!(
+                error,
+                "PRINCIPAL_TENANT_MIGRATION_CONFLICT:AMBIGUOUS_OWNERSHIP:app_a"
+            );
+        }
+    }
+
+    #[test]
+    fn production_shaped_application_definition_resolves_principal_scope() {
+        let db_path = path("production-shaped-db");
+        let legacy_path = path("production-shaped-principals.json");
+        let tenancy_path = path("production-shaped-tenancy.json");
+        let applications_path = path("production-shaped-applications.json");
+        let tenancy = TenancyStore::load(&tenancy_path).unwrap();
+        let tenant = tenancy
+            .create_tenant("principal_owner", "Production tenant")
+            .unwrap();
+        let applications = ApplicationStore::load(&applications_path).unwrap();
+        let draft = applications
+            .create_draft(
+                &tenant.id,
+                "app_pKEN4gJ0lvQV4D2ZWa",
+                "Sanitized production-shaped application",
+                "principal_owner",
+                None,
+            )
+            .unwrap();
+        applications
+            .commit(
+                &tenant.id,
+                "app_pKEN4gJ0lvQV4D2ZWa",
+                &draft.draft_id,
+                "principal_owner",
+            )
+            .unwrap();
+        let mut record = principal();
+        record.application_id = "app_pKEN4gJ0lvQV4D2ZWa".into();
+        fs::write(
+            &legacy_path,
+            serde_json::to_vec(&LegacyPrincipalRecords {
+                principals: vec![record],
+                audit: vec![],
+            })
+            .unwrap(),
+        )
+        .unwrap();
+        let authority = CanonicalPrincipalAuthority::new(FeltDb::open(&db_path).unwrap());
+        authority
+            .migrate_legacy_file(&legacy_path, |application_id| {
+                resolve_principal_tenant(application_id, &tenancy, &applications, &authority.db)
+            })
+            .unwrap();
+        fs::remove_file(&legacy_path).unwrap();
+        drop(authority);
+        let reopened = CanonicalPrincipalAuthority::new(FeltDb::open(&db_path).unwrap());
+        assert!(reopened
+            .get(
+                &tenant.id,
+                "app_pKEN4gJ0lvQV4D2ZWa",
+                "agent_stable"
+            )
+            .unwrap()
+            .is_some());
+    }
+
+    #[test]
+    fn production_mutations_and_worker_validation_survive_cold_restart() {
+        let db_path = path("production-db");
+        let tenancy_path = path("production-tenancy.json");
+        let tenancy = TenancyStore::load(&tenancy_path).unwrap();
+        let tenant = tenancy.create_tenant("owner", "Canonical").unwrap();
+        let application = tenancy
+            .create_application("owner", &tenant.id, "Application")
+            .unwrap();
+        let authority = CanonicalPrincipalAuthority::new(FeltDb::open(&db_path).unwrap());
+        let agent = authority
+            .create(
+                "owner",
+                &tenancy,
+                &application.id,
+                PrincipalKind::Agent,
+                "Agent",
+            )
+            .unwrap();
+        authority
+            .grant("owner", &tenancy, &agent.id, "state:read")
+            .unwrap();
+        let work = authority
+            .create_workload("owner", &tenancy, &agent.id)
+            .unwrap();
+        let worker = authority
+            .create(
+                "owner",
+                &tenancy,
+                &application.id,
+                PrincipalKind::Worker,
+                "Worker",
+            )
+            .unwrap();
+        authority
+            .assign_worker("owner", &tenancy, &work.id, &worker.id)
+            .unwrap();
+        assert!(authority.authorize(&agent.id, &application.id, "state:read"));
+        drop(authority);
+
+        let reopened = CanonicalPrincipalAuthority::new(FeltDb::open(&db_path).unwrap());
+        assert!(reopened.authorize(&agent.id, &application.id, "state:read"));
+        assert!(reopened.worker_can_execute(&worker.id, &work.id));
+        assert_eq!(
+            reopened.execution_snapshot(&worker.id, &work.id).unwrap().0,
+            application.id
+        );
+        assert!(!reopened
+            .audit_for("owner", &tenancy, &application.id, Some(&agent.id), 20)
+            .unwrap()
+            .is_empty());
+    }
+}