{"record":{"id":"bc70177641f3237d","repo":"astrid-runtime/astrid","slug":"native-capsule-runtime-requires-the-authoritative","errorCode":null,"errorMessage":"native capsule runtime requires the authoritative principal store","messagePattern":"native capsule runtime requires the authoritative principal store","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-kernel/src/lib.rs","lineNumber":1940,"sourceCode":"\n        let capsule_listener = (!self.native_uplink_owns_listener.load(Ordering::Acquire))\n            .then(|| self.cli_socket_listener.clone())\n            .flatten();\n        let mut ctx = astrid_capsule::context::CapsuleContext::new(\n            load_principal,\n            self.workspace_root.clone(),\n            // Durable home VFS authority is threaded separately through the\n            // UID-bound principal store. Do not pass a native PrincipalHome\n            // path into the steady-state capsule context.\n            None,\n            kv,\n            Arc::clone(&self.event_bus),\n            capsule_listener,\n        )\n        .with_astrid_workspace()\n        .with_principal_storage(\n            self.principal_store.clone().ok_or_else(|| {\n                anyhow::anyhow!(\n                    \"native capsule runtime requires the authoritative principal store\"\n                )\n            })?,\n            self.principal_directory.clone(),\n        )\n        .with_workspace_branches(self.workspace_branches.clone().ok_or_else(|| {\n            anyhow::anyhow!(\n                \"canonical Astrid workspace requires the kernel workspace branch service\"\n            )\n        })?)\n        .with_process_storage_mount_broker(\n            self.process_storage_mount_broker\n                .get()\n                .cloned()\n                .ok_or_else(|| anyhow::anyhow!(\"native process storage mount broker unavailable\"))?,\n        )\n        .with_registry(Arc::clone(&self.capsules))\n        .with_session_token(Arc::clone(&self.session_token))","sourceCodeStart":1922,"sourceCodeEnd":1958,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-kernel/src/lib.rs#L1922-L1958","documentation":"This error is thrown by the kernel's native capsule runtime builder when the AstridKernel was constructed without an authoritative principal store. The principal store is the source of truth for capsule ownership per principal, so the runtime refuses to start without it rather than run with no authority over principals. It is a fail-fast guard in `with_principal_storage(...)` during runtime assembly.","triggerScenarios":"Calling the kernel method that starts the native capsule runtime (lib.rs:1940, the builder chain ending in `with_astrid_workspace()`) while `self.principal_store` is `None` — i.e. the kernel was built via a path that never called the principal-store setter, or the field was explicitly left unset.","commonSituations":"Constructing AstridKernel with a minimal/partial builder configuration in tests or embedded setups; refactoring that renamed or dropped the principal-store builder call; instantiating the kernel for a use case (e.g. headless tooling) that skipped principal storage but then attempted to launch capsules.","solutions":["Set the principal store on the kernel before starting the native capsule runtime, via the builder method that populates `principal_store`","Check the kernel construction code path and ensure `with_principal_storage`-equivalent configuration is always applied","If the runtime is intentionally principal-less, use a runtime mode that does not require the authoritative store instead of the native capsule runtime"],"exampleFix":"// before\nlet kernel = AstridKernel::builder().build();\nkernel.start_native_capsule_runtime().await?; // panics into anyhow: no principal store\n// after\nlet kernel = AstridKernel::builder()\n    .with_principal_store(principal_store)\n    .build();\nkernel.start_native_capsule_runtime().await?;","handlingStrategy":"validation","validationCode":"// Rust, before starting the runtime\nif kernel.principal_store().is_none() {\n    return Err(anyhow!(\"principal store must be configured before native capsule runtime\"));\n}","typeGuard":"fn has_principal_store(kernel: &AstridKernel) -> bool {\n    kernel.principal_store().is_some()\n}","tryCatchPattern":null,"preventionTips":["Always construct the kernel through the standard bootstrap builder that wires the principal store","Add a startup assertion/test that the kernel can start its native runtime with your configuration","When adding new kernel fields, update all construction sites in the same change"],"tags":["rust","configuration","kernel-startup","capsule-runtime"],"backgroundTag":"missing-required-config","analyzedSha":"affd8760f44190dbdfbec23403f4c4b642c33112","analyzedAt":"2026-09-09T21:28:12.402Z","contentChangedAt":"2026-09-09T21:28:12.402Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}