{"record":{"id":"cc7c1f53400bd9a9","repo":"astrid-runtime/astrid","slug":"system-resident-capsule-id-must-be-created-by","errorCode":null,"errorMessage":"system-resident capsule '{id}' must be created by the operator/default view before dependents attach","messagePattern":"system-resident capsule '(.+?)' must be created by the operator/default view before dependents attach","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"crates/astrid-kernel/src/lib.rs","lineNumber":1761,"sourceCode":"        // fresh runtime for its immutable UID; only an explicitly classified\n        // SystemResident service may attach another view to one runtime.\n        {\n            let mut registry = self.capsules.write().await;\n            if registry.get_for(principal, &id).is_some() {\n                return Ok(());\n            }\n            if system_runtime && registry.contains_system_runtime(&id, &wasm_hash) {\n                registry\n                    .register_existing(&id, &wasm_hash, principal)\n                    .map_err(|e| anyhow::anyhow!(\"Failed to add capsule view: {e}\"))?;\n                if let Some(capsule) = registry.get_for(principal, &id) {\n                    capsule.resume_for(principal);\n                }\n                return Ok(());\n            }\n        }\n        if system_runtime && principal != &PrincipalId::default() {\n            anyhow::bail!(\n                \"system-resident capsule '{id}' must be created by the operator/default view before dependents attach\"\n            );\n        }\n        // System residency is an operator/admin classification, not a host\n        // path ancestry claim. The source directory is a disposable\n        // materialization of the durable package registry; `system_capsules`\n        // is the authenticated admission set and the installed authority\n        // receipt was verified above.\n\n        let principal_uid = self.runtime_principal_uid(system_runtime, principal, &id)?;\n        let scope = principal_uid.map_or(\n            astrid_capsule::registry::RuntimeScope::SystemResident,\n            astrid_capsule::registry::RuntimeScope::Principal,\n        );\n        let runtime_id =\n            self.capsules\n                .write()\n                .await","sourceCodeStart":1743,"sourceCodeEnd":1779,"githubUrl":"https://github.com/astrid-runtime/astrid/blob/affd8760f44190dbdfbec23403f4c4b642c33112/crates/astrid-kernel/src/lib.rs#L1743-L1779","documentation":"A system-resident capsule's runtime is shared and must be created once by the operator/default view before any other principal can attach to it. If a non-default principal attempts to load the capsule and no existing system runtime is registered, the kernel rejects the load so the operator bootstraps it first.","triggerScenarios":"Loading a system-resident capsule with `principal != PrincipalId::default()` when the registry has no matching system runtime for that capsule id and WASM hash (i.e., the default view has never loaded it in this daemon).","commonSituations":"A principal's startup script loads a system capsule before the daemon has booted it; the daemon restarted and only non-default principals reattached; a new capsule version was installed but only principals reloaded it.","solutions":["Load the capsule once with the default principal (operator view) to create the system runtime.","Order startup so the operator/default view loads system capsules before principal views attach.","Remove the capsule from `system_capsules` if it is actually meant to be principal-scoped."],"exampleFix":"// before\nkernel.load_capsule(&dir, &user_principal).await?;\n// after\nkernel.load_capsule(&dir, &PrincipalId::default()).await?; // bootstrap system runtime\nkernel.load_capsule(&dir, &user_principal).await?;","handlingStrategy":"validation","validationCode":"if is_system_capsule(id) && principal != PrincipalId::default() && !daemon_has_system_runtime(id) {\n    return Err(anyhow!(\"bootstrap {id} via the default view first\"));\n}","typeGuard":null,"tryCatchPattern":"match kernel.load_capsule(&dir, &principal).await {\n    Err(e) if e.to_string().contains(\"must be created by the operator/default view\") => {\n        kernel.load_capsule(&dir, &PrincipalId::default()).await?;\n        kernel.load_capsule(&dir, &principal).await\n    }\n    other => other,\n}","preventionTips":["Load all system capsules with the default principal during daemon startup.","Gate principal view loading on system-runtime readiness events.","Document bootstrap order for system-resident services."],"tags":["capsule-lifecycle","system-resident","startup-ordering"],"backgroundTag":"invalid-state-transition","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"}