@arcforge/err 2.0.98

package/src/map.ts

@@ -0,0 +1,1044 @@
+/**
+ * The single source of truth for every failure Axon can name. One flat map,
+ * one entry per unique failure — codes are never reused and never change
+ * once shipped (a code is a stable identity a user or a support thread can
+ * reference). New failures get an entry here before their call site exists;
+ * `err()` refuses to compile against a code this map doesn't declare.
+ *
+ * `title`/`description` are the rendering contract: title is a short,
+ * user-facing headline ("Agent failed to start"), description is one or two
+ * sentences of plain-language context — not the message, not the stack.
+ * Both are written for someone who has never read this codebase.
+ *
+ * `severity` replaces a bare recoverable boolean — a degrading-but-handled
+ * failure and a fatal one both need to reach the log, just not with the
+ * same weight:
+ *   - "fatal"      — the operation this belongs to did not complete. Always logged, always rendered loud.
+ *   - "recovered"  — failed, but a fallback/retry made it survivable. Logged for visibility, not alarmed.
+ *   - "degraded"   — the system continues in a lesser state (a feature disabled, a cache miss that will retry). Logged, low urgency.
+ */
+
+// AxonErrorSource / AxonErrorSeverity are the wire contract — they live in
+// @arcforge/types and are re-exported here so this map's entries and existing
+// importers resolve them from the same place.
+export type { AxonErrorSource, AxonErrorSeverity } from "@arcforge/types"
+import type { AxonErrorSource, AxonErrorSeverity } from "@arcforge/types"
+
+export type AxonErrorMapEntry = {
+    /** Stable short code, e.g. "AX-BOOT-001". Never reused, never renumbered. */
+    code: string
+    /** Short, user-facing headline. */
+    title: string
+    /** One or two plain-language sentences — what happened and why it matters, not a stack dump. */
+    description: string
+    source: AxonErrorSource
+    severity: AxonErrorSeverity
+}
+
+/**
+ * This map must be updated for every unique failure case.
+ */
+export const errorMap = {
+    UNKNOWN: {
+        code: "AX-UNKNOWN-001",
+        title: "Unclassified Error",
+        description: "An error occurred that hasn't been given a proper code yet. This is itself worth fixing — see the err(cause) call site that produced it.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    PROMPT_NOT_FOUND: {
+        code: "AX-PROMPT-001",
+        title: "Prompt Not Found",
+        description: "The requested prompt was not found in the agent's blueprint. It may not be declared, or the agent needs to be re-prepared.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    PROMPT_FILE_NOT_FOUND: {
+        code: "AX-PROMPT-002",
+        title: "Prompt File Missing",
+        description: "The prompt is declared but its source file no longer exists on disk.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    PROMPT_RENDER_FAILED: {
+        code: "AX-PROMPT-003",
+        title: "Prompt Render Failed",
+        description: "The prompt's source file failed to compile or render — likely a malformed SFC (content outside <template>/<script>/<style>) or an error thrown while rendering. See the cause for the underlying parser/render error.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    SCRIPT_NOT_FOUND: {
+        code: "AX-SCRIPT-001",
+        title: "Script Not Found",
+        description: "The requested script was not found in the agent's blueprint. It may not be declared, or the agent needs to be re-prepared.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    SCRIPT_FILE_NOT_FOUND: {
+        code: "AX-SCRIPT-002",
+        title: "Script File Missing",
+        description: "The script is declared but its source file no longer exists on disk.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    ENGINE_MISSING: {
+        code: "AX-ENGINE-001",
+        title: "No Engine Configured",
+        description: "The agent's blueprint has no engine — it cannot dispatch to a model. Set `engine` in axon.config.ts.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    INJECT_OUTSIDE_RUNTIME: {
+        code: "AX-RUNTIME-001",
+        title: "Runtime Accessed Before Boot",
+        description: "A runtime global (axon, args) was read before the runtime finished booting.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    BOOT_FAILED: {
+        code: "AX-BOOT-001",
+        title: "Agent Failed To Start",
+        description: "The agent's runtime crashed while starting, before it could accept requests.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    BOOT_SCRIPT_FAILED: {
+        code: "AX-BOOT-002",
+        title: "Boot Script Failed",
+        description: "The agent's boot.vue threw while rendering — check the script setup block for the error.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    BOOT_SCRIPT_INVALID: {
+        code: "AX-BOOT-003",
+        title: "Boot Script Malformed",
+        description: "The agent's boot.vue has content outside its recognized <script>/<template> blocks, or otherwise failed to parse as a valid SFC.",
+        source: "runtime",
+        severity: "fatal",
+    },
+
+    // ── Cognet (host.ts / cognet.ts) ────────────────────────────────────────
+    COGNET_ACCESSED_BEFORE_LOAD: {
+        code: "AX-COGNET-001",
+        title: "Cognet Accessed Before Load",
+        description: "A cognet global (kernel, phase, system, blueprint) was read before the brain finished loading, or outside the loop body that owns it.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_LOOP_ALREADY_DECLARED: {
+        code: "AX-COGNET-002",
+        title: "Loop Already Declared",
+        description: "A cognet's main() called loop() more than once — the loop is the program's entire main body and can only be declared once.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_ALREADY_LOADED: {
+        code: "AX-COGNET-003",
+        title: "Cognet Bound To A Different Kernel",
+        description: "This cognet instance already loaded against a different kernel ABI — a reload produced a conflicting bind instead of a clean swap.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_NO_LOOP: {
+        code: "AX-COGNET-004",
+        title: "Cognet Declared No Loop",
+        description: "The cognet's main() ran (or was woken) without ever declaring loop() — there is no program to run.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_MAX_TICKS: {
+        code: "AX-COGNET-005",
+        title: "Cognet Exceeded Max Ticks",
+        description: "The cognet's loop ran more ticks in one wake than its configured limit allows — likely a runaway loop that never calls stop().",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_ABI_MISMATCH: {
+        code: "AX-COGNET-006",
+        title: "Cognet ABI Mismatch",
+        description: "The compiled cognet targets a kernel ABI version the running kernel doesn't provide — rebuild the cognet against the current framework version.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_MISSING: {
+        code: "AX-COGNET-007",
+        title: "No Compiled Cognet",
+        description: "The blueprint points at a compiled cognet bundle that doesn't exist on disk yet — run `axon prepare` before booting.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_HASH_MISMATCH: {
+        code: "AX-COGNET-008",
+        title: "Cognet Bundle Hash Mismatch",
+        description: "The compiled cognet bundle on disk doesn't match the hash the blueprint expects — it's stale or was tampered with. Run `axon prepare` again.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_INVALID: {
+        code: "AX-COGNET-009",
+        title: "Invalid Cognet Bundle",
+        description: "The compiled cognet's default export isn't a real cognet definition — the compile step produced something malformed.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_IDENTITY_MISMATCH: {
+        code: "AX-COGNET-010",
+        title: "Cognet Identity Mismatch",
+        description: "The compiled cognet artifact's own name doesn't match what the blueprint declared — the wrong bundle may be at this path.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_CONFIG_MISSING: {
+        code: "AX-COGNET-011",
+        title: "Cognet Config Missing",
+        description: "No cognet.config.ts was found in the cognet's source directory — every cognet needs one to declare its identity.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_BUILD_FAILED: {
+        code: "AX-COGNET-012",
+        title: "Cognet Failed To Compile",
+        description: "Bundling the cognet's source into a runnable artifact failed — check the build log for the underlying syntax or import error.",
+        source: "cognet",
+        severity: "fatal",
+    },
+    COGNET_NOT_FOUND: {
+        code: "AX-COGNET-013",
+        title: "Cognet Not Found",
+        description: "The cognet this agent selects isn't installed — check the `cognet` specifier in axon.config.ts and run `axon prepare` to install it from the registry.",
+        source: "cognet",
+        severity: "fatal",
+    },
+
+    // ── Project (build/project/dependencies.ts) ─────────────────────────────
+    MODULE_SPECIFIER_INVALID: {
+        code: "AX-PROJECT-005",
+        title: "Invalid Module Specifier",
+        description: "Module names must be scoped as @scope/name. The registry does not accept unscoped packages, so an unscoped specifier can never resolve.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    CONFIG_MODULES_UNPARSEABLE: {
+        code: "AX-PROJECT-006",
+        title: "Could Not Edit axon.config.ts",
+        description: "The install succeeded but the module entry could not be written into the config's modules array automatically — add or remove it by hand.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    MODULE_DEPENDENCY_INSTALL_FAILED: {
+        code: "AX-PROJECT-004",
+        title: "Module Dependencies Failed To Install",
+        description: "The module source was downloaded, but its npm dependencies could not be materialized for the agent. Resolve the package-manager error and run the install again.",
+        source: "manifest",
+        severity: "fatal",
+    },
+
+    // ── Blueprint (build/blueprint/blueprint.ts) ────────────────────────────
+    BLUEPRINT_NOT_LOADED: {
+        code: "AX-PROJECT-002",
+        title: "Blueprint Accessed Before Load",
+        description: "Something read the blueprint's current value before load() had ever run.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    AGENT_INVALID: {
+        code: "AX-PROJECT-003",
+        title: "Invalid Agent Directory",
+        description: "The agent root has no package.json — every agent is a real package, this one isn't.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    CORRUPT_JSON: {
+        code: "AX-PROJECT-004",
+        title: "Corrupt JSON File",
+        description: "A stored JSON file failed to parse — it may have been hand-edited into an invalid state, or a write was interrupted mid-flight.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    PROVIDER_NOT_CONNECTED: {
+        code: "AX-TUI-011",
+        title: "Provider Not Connected",
+        description: "The selected model routes through a provider (OpenRouter, Codex) that isn't connected yet — connect it before picking a model on that route.",
+        source: "tui",
+        severity: "fatal",
+    },
+    PALETTE_INPUT_REQUIRED: {
+        code: "AX-TUI-012",
+        title: "Required Input Missing",
+        description: "A palette command needs a value for this field before it can run.",
+        source: "tui",
+        severity: "fatal",
+    },
+    BENCH_NO_CASES: {
+        code: "AX-TUI-013",
+        title: "Bench Declared No Cases",
+        description: "The bench's test file ran to completion under Bun but never declared a single benchmark case.",
+        source: "tui",
+        severity: "fatal",
+    },
+
+    // ── Project (build/project/*.ts) ────────────────────────────────────────
+    PROJECT_NOT_FOUND: {
+        code: "AX-PROJECT-005",
+        title: "Project Not Found",
+        description: "No axon.config.ts, module.config.ts, or cognet.config.ts was found at this path — it isn't a recognized project directory.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    PROJECT_EXISTS: {
+        code: "AX-PROJECT-006",
+        title: "Project Already Exists",
+        description: "Scaffolding refused to overwrite a directory that already exists — remove it or pick a different name first.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    TYPEGEN_NO_BLUEPRINT: {
+        code: "AX-PROJECT-007",
+        title: "Typegen Needs A Loaded Blueprint",
+        description: "Agent-kind typegen was called without a blueprint — its declared surfaces are the source of the generated types.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    DEPLOY_AGENTS_ONLY: {
+        code: "AX-PROJECT-008",
+        title: "Only Agents Can Deploy",
+        description: "A module was asked to deploy on its own — modules only run installed inside an agent, deploy the agent instead.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    PUBLISH_UNSUPPORTED_KIND: {
+        code: "AX-PROJECT-009",
+        title: "This Project Kind Cannot Publish Yet",
+        description: "Only agents and modules publish to the registry today. Cognets and benches become first-class registry artifacts in the unified artifact work — until then, publishing one would register it under the wrong kind and claim its name in the shared namespace.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    DEPLOY_PROVISION_FAILED: {
+        code: "AX-PROJECT-012",
+        title: "Deployment Provisioning Failed",
+        description: "The agent was published, but the cloud control plane could not provision its runtime. The request ID identifies the server-side failure.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    DEPLOY_RUNTIME_FAILED: {
+        code: "AX-PROJECT-013",
+        title: "Agent Failed To Start",
+        description: "Cloud infrastructure was provisioned, but the agent process failed during boot. The reported runtime diagnostic identifies the immediate cause.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    DEPLOY_ENV_RESERVED: {
+        code: "AX-PROJECT-014",
+        title: "Reserved Deployment Variable",
+        description: "The production .env file attempts to override a variable owned by the Axon runtime or Cloud Run.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    DEPLOY_ENV_INVALID: {
+        code: "AX-PROJECT-015",
+        title: "Invalid Deployment Variable",
+        description: "The production .env file contains a key that is not a valid environment variable name.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    BUNDLE_MODULE_COLLISION: {
+        code: "AX-PROJECT-009",
+        title: "Module Name Collision",
+        description: "A hard-imported source module's name collides with an already-installed registry module of the same name.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    BUNDLE_INVALID: {
+        code: "AX-PROJECT-010",
+        title: "Invalid Bundle Source",
+        description: "The directory being bundled has no package.json, or its package.json has no name — every bundle needs a real package identity.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    BUNDLE_TAR_MISSING: {
+        code: "AX-PROJECT-011",
+        title: "tar Not Found",
+        description: "Bundling shells out to the system's tar binary, which isn't on PATH — install Git for Windows or use WSL on that platform.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    BUNDLE_TAR_FAILED: {
+        code: "AX-PROJECT-012",
+        title: "tar Failed",
+        description: "The tar subprocess exited non-zero while building a bundle archive.",
+        source: "manifest",
+        severity: "fatal",
+    },
+
+    // ── Bench (build/bench/*.ts) ────────────────────────────────────────────
+    BENCH_RUN_NOT_FOUND: {
+        code: "AX-BENCH-001",
+        title: "Bench Run Not Found",
+        description: "No recorded bench run exists with this id.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_NOT_FOUND: {
+        code: "AX-BENCH-002",
+        title: "Bench Not Found",
+        description: "No bench.config.ts was found at this path — it isn't a recognized bench project.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_TESTS_NOT_FOUND: {
+        code: "AX-BENCH-003",
+        title: "Bench Test Files Not Found",
+        description: "The bench config declares test files that don't exist on disk.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_LOCAL_REF_NOT_FOUND: {
+        code: "AX-BENCH-004",
+        title: "Bench Local Reference Not Found",
+        description: "A factor variable references a local file/directory that doesn't exist.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_CONFIG_INVALID: {
+        code: "AX-BENCH-005",
+        title: "Bench Config Invalid",
+        description: "bench.config.ts failed to evaluate or didn't produce a valid bench definition.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_PACKAGE_NOT_FOUND: {
+        code: "AX-BENCH-006",
+        title: "Bench Package Not Found",
+        description: "No package.json exists at the bench root — every bench project needs one for identity.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_PACKAGE_NAME_REQUIRED: {
+        code: "AX-BENCH-007",
+        title: "Bench Package Name Required",
+        description: "The bench's package.json has no name field.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_PACKAGE_VERSION_REQUIRED: {
+        code: "AX-BENCH-008",
+        title: "Bench Package Version Required",
+        description: "The bench's package.json has no version field.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_CONTEXT_MISSING: {
+        code: "AX-BENCH-009",
+        title: "Bench Context Missing",
+        description: "The benchmark preload needs AXON_BENCH_CONTEXT set — it was run outside the bench harness.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_NO_ACTIVE_CASE: {
+        code: "AX-BENCH-010",
+        title: "No Active Bench Case",
+        description: "A bench emission (measurement, artifact) happened outside any running Bun test — these calls must occur inside a test case.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_WORKSPACE_UNAVAILABLE: {
+        code: "AX-BENCH-011",
+        title: "Bench Workspace Unavailable",
+        description: "The bench's workspace directory hasn't been materialized yet for this run.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_AGENT_UNRESOLVED: {
+        code: "AX-BENCH-012",
+        title: "Bench Agent Unresolved",
+        description: "The bench's declared subject agent isn't a prepared local agent — run `axon prepare` on it first.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_MEASUREMENT_UNKNOWN: {
+        code: "AX-BENCH-013",
+        title: "Unknown Bench Measurement",
+        description: "A measurement was emitted under an id the bench config never declared.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_MEASUREMENT_TYPE: {
+        code: "AX-BENCH-014",
+        title: "Bench Measurement Type Mismatch",
+        description: "A measurement's emitted value doesn't match the type its bench config declaration expects.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_MEASUREMENT_DOMAIN: {
+        code: "AX-BENCH-015",
+        title: "Bench Measurement Out Of Domain",
+        description: "A measurement's emitted value falls outside the range or category the bench config declares for it.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_DIMENSION_UNKNOWN: {
+        code: "AX-BENCH-016",
+        title: "Unknown Bench Dimension",
+        description: "A dimension value was set under an id the bench config never declared.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_DIMENSION_DOMAIN: {
+        code: "AX-BENCH-017",
+        title: "Bench Dimension Out Of Domain",
+        description: "A dimension's set value isn't one of the categories its bench config declares.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_FACTOR_UNKNOWN: {
+        code: "AX-BENCH-018",
+        title: "Unknown Bench Factor",
+        description: "Something referenced a factor id the running bench's coordinate never assigned a value to.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_ARTIFACT_UNKNOWN: {
+        code: "AX-BENCH-019",
+        title: "Unknown Bench Artifact",
+        description: "An artifact was emitted under an id the bench config never declared.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_ARTIFACT_MEDIA_TYPE: {
+        code: "AX-BENCH-020",
+        title: "Bench Artifact Media Type Not Allowed",
+        description: "An artifact was emitted with a media type its bench config declaration doesn't allow.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_FACTOR_NOT_FOUND: {
+        code: "AX-BENCH-021",
+        title: "Bench Factor Not Found",
+        description: "The bench config has no factor with this id.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_FACTOR_VALUE_NOT_FOUND: {
+        code: "AX-BENCH-022",
+        title: "Bench Factor Value Not Found",
+        description: "The bench config's factor has no declared value with this id.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_TEMPLATE_ESCAPE: {
+        code: "AX-BENCH-023",
+        title: "Bench Template Path Escapes Root",
+        description: "A workspace template entry resolved to a path outside the template directory — refused rather than materialized.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_TEMPLATE_SYMLINK_UNSUPPORTED: {
+        code: "AX-BENCH-024",
+        title: "Bench Template Symlinks Unsupported",
+        description: "A workspace template contains a symlink — not supported when materializing a bench workspace.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_TEMPLATE_OUTSIDE_ROOT: {
+        code: "AX-BENCH-025",
+        title: "Bench Template Outside Root",
+        description: "A workspace template's declared source path resolves outside the bench project root.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_TEMPLATE_NOT_FOUND: {
+        code: "AX-BENCH-026",
+        title: "Bench Template Not Found",
+        description: "A workspace template's declared source path isn't a real directory.",
+        source: "bench",
+        severity: "fatal",
+    },
+    BENCH_LOG_INVALID: {
+        code: "AX-BENCH-027",
+        title: "Bench Log Invalid",
+        description: "A bench run's event log is missing an entry its projection requires — the log is incomplete or was written out of order.",
+        source: "bench",
+        severity: "fatal",
+    },
+
+    // ── Blueprint scan (scan/tools.ts, scan/config.ts) ──────────────────────
+    TOOL_DECLARE_FAILED: {
+        code: "AX-BLUEPRINT-002",
+        title: "Tool Declaration Failed",
+        description: "Compiling a src/tools/*.ts file's TypeScript declarations failed — the worker subprocess reported a compile error.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    TOOL_BUNDLE_FAILED: {
+        code: "AX-BLUEPRINT-006",
+        title: "Tool Bundle Failed",
+        description: "Bundling a src/tools/*.ts file to self-contained source failed — the bundler subprocess reported an error. Tools are bundled so the sandbox loads them without mounting the project; a bundle failure means the tool cannot enter the box.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    CONFIG_NOT_FOUND: {
+        code: "AX-BLUEPRINT-003",
+        title: "Config Not Found",
+        description: "No axon.config.ts exists at this path.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    CONFIG_LOAD_FAILED: {
+        code: "AX-BLUEPRINT-004",
+        title: "Config Failed To Load",
+        description: "axon.config.ts threw or failed to evaluate — check the file for a syntax or runtime error.",
+        source: "manifest",
+        severity: "fatal",
+    },
+    CONFIG_INVALID: {
+        code: "AX-BLUEPRINT-005",
+        title: "Config Invalid",
+        description: "axon.config.ts evaluated but never called defineAgent() — every agent config must produce one.",
+        source: "manifest",
+        severity: "fatal",
+    },
+
+    // ── Kernel (engine.ts / executor.ts) ─────────────────────────────────────
+    ENGINE_NO_DONE: {
+        code: "AX-KERNEL-001",
+        title: "Engine Stream Ended Without Completing",
+        description: "The model driver's stream ended without ever emitting a completion event — the engine likely disconnected or crashed mid-response.",
+        source: "kernel",
+        severity: "fatal",
+    },
+    ENGINE_STREAM_FAILED: {
+        code: "AX-KERNEL-008",
+        title: "Engine Stream Failed",
+        description: "The model driver's stream failed and exhausted its retries (or the failure wasn't retryable) — see context for the provider's fault code.",
+        source: "kernel",
+        severity: "fatal",
+    },
+    CODEX_NOT_CONNECTED: {
+        code: "AX-KERNEL-012",
+        title: "Codex Subscription Not Connected",
+        description: "This agent uses a Codex model, but your Axon account is not connected to ChatGPT — run :provider codex connect and try again.",
+        source: "kernel",
+        severity: "fatal",
+    },
+    RUN_IN_PROGRESS: {
+        code: "AX-KERNEL-002",
+        title: "A Wake Is Already Running",
+        description: "The kernel only executes one wake at a time — a new run was requested while the previous one was still active.",
+        source: "kernel",
+        severity: "recovered",
+    },
+    RUN_RESERVATION_EXPIRED: {
+        code: "AX-KERNEL-003",
+        title: "Wake Reservation Expired",
+        description: "The reserved execution slot for this wake is no longer active — it was released before the run could start.",
+        source: "kernel",
+        severity: "fatal",
+    },
+    NO_COGNET_LOADED: {
+        code: "AX-KERNEL-004",
+        title: "No Cognet Loaded",
+        description: "The kernel tried to execute a wake, but the blueprint carried no cognet definition to run it against.",
+        source: "kernel",
+        severity: "fatal",
+    },
+    SYSCALL_OUTSIDE_RUN: {
+        code: "AX-KERNEL-005",
+        title: "Syscall Outside An Active Run",
+        description: "A kernel syscall (engine.stream and similar) was made with no active wake to attribute it to.",
+        source: "kernel",
+        severity: "fatal",
+    },
+    CAPSULE_ACCESSED_BEFORE_BOOT: {
+        code: "AX-KERNEL-007",
+        title: "Capsule Accessed Before Boot",
+        description: "Something reached for the live capsule instance before boot() had run — there is no sandbox yet to hand back.",
+        source: "kernel",
+        severity: "fatal",
+    },
+    COGNET_EMIT_FORBIDDEN: {
+        code: "AX-KERNEL-009",
+        title: "Cognet Emit Forbidden",
+        description: "A cognet tried to emit an event outside the cognet:* namespace — the ABI only lets a cognet narrate its own telemetry, never forge kernel machinery events.",
+        source: "kernel",
+        severity: "fatal",
+    },
+    SCHEDULER_MODE_MISMATCH: {
+        code: "AX-KERNEL-010",
+        title: "Scheduler Mode Mismatch",
+        description: "A caller invoked stream() on a continuous-mode cognet — continuous cognets are invoked by the scheduler's own clock, never by an external stimulus-driven call.",
+        source: "kernel",
+        severity: "fatal",
+    },
+    SCHEDULER_CONTINUOUS_NOT_IMPLEMENTED: {
+        code: "AX-KERNEL-011",
+        title: "Continuous Scheduling Not Implemented",
+        description: "The cognet declared continuous mode, but the scheduler's clock-driven trigger is a stubbed shape only — no cognet may select it yet.",
+        source: "kernel",
+        severity: "fatal",
+    },
+
+    // ── Session (session.ts) ─────────────────────────────────────────────────
+    THREAD_UNKNOWN_PARENT: {
+        code: "AX-SESSION-001",
+        title: "Thread Branched From Unknown Parent",
+        description: "A thread's recorded lineage points at a parent thread id that isn't registered in this session — the session index is inconsistent.",
+        source: "thread",
+        severity: "fatal",
+    },
+    THREAD_NOT_FOUND: {
+        code: "AX-SESSION-002",
+        title: "Thread Not Found",
+        description: "The requested thread id isn't registered in this session.",
+        source: "thread",
+        severity: "fatal",
+    },
+    THREAD_BRANCH_UNKNOWN: {
+        code: "AX-SESSION-003",
+        title: "Cannot Branch Unknown Thread",
+        description: "A branch was requested from a parent thread id that isn't registered in this session.",
+        source: "thread",
+        severity: "fatal",
+    },
+
+    // ── Blueprint ─────────────────────────────────────────────────────────────
+    NO_COGNET: {
+        code: "AX-BLUEPRINT-001",
+        title: "No Cognet Declared",
+        description: "The blueprint carries no cognet definition — an agent cannot run without a brain. The CLI or test harness must construct and pass one.",
+        source: "runtime",
+        severity: "fatal",
+    },
+
+    // ── Server ────────────────────────────────────────────────────────────────
+    PLUGIN_BOOT_FAILED: {
+        code: "AX-SERVER-001",
+        title: "Plugin Failed During Boot",
+        description: "A server plugin threw while running at boot — plugins are the one place in server startup where a failure must abort the boot rather than being warned and skipped.",
+        source: "server",
+        severity: "fatal",
+    },
+    HANDLE_SHUTDOWN_FAILED: {
+        code: "AX-RUNTIME-002",
+        title: "Handle Failed To Shut Down",
+        description: "One of the runtime's owned handles (kernel, etc.) threw during shutdown — teardown is error-isolated, so the others still ran, but this one didn't close cleanly.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    TOOL_CALL_FAILED: {
+        code: "AX-RUNTIME-003",
+        title: "Tool Call Failed",
+        description: "An axon.tools.<namespace>.<fn>() call from script-land completed with a non-ok result from the capsule — unwrapped here into a normal throw, since script-land expects the ordinary call/throw contract, not the kernel's own stable-result shape.",
+        source: "runtime",
+        severity: "fatal",
+    },
+
+    // ── Capsule (build/tools.ts) ─────────────────────────────────────────────
+    CAPSULE_TOOL_TIMEOUT: {
+        code: "AX-CAPSULE-001",
+        title: "Tool Load Timed Out",
+        description: "The sandbox never confirmed loading a declared tool within the timeout — it may be stuck on a slow import or the subprocess is unresponsive.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_TOOL_SCOPE_MISMATCH: {
+        code: "AX-CAPSULE-002",
+        title: "Tool Scope Mismatch",
+        description: "A tool's declared exports don't match what it actually exported once loaded in the sandbox — the bundled source and its declaration have drifted apart.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_TOOL_FAILED: {
+        code: "AX-CAPSULE-003",
+        title: "Tool Failed To Load",
+        description: "A declared tool failed to load into the sandbox — its source may be malformed, too large to import, or the subprocess exited before confirming.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_CONFINE_UNAVAILABLE: {
+        code: "AX-CAPSULE-004",
+        title: "OS Confinement Unavailable",
+        description: "The policy requested OS confinement (isolation: auto) but the host is missing a required primitive (bubblewrap, systemd, nft, or the axon-agent user). Run `axon install`, or set isolation: none to opt out explicitly. The capsule refuses to boot rather than silently run unconfined.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_CONFINE_USER_UNRESOLVED: {
+        code: "AX-CAPSULE-005",
+        title: "Confinement User Unresolved",
+        description: "The confinement user exists but its numeric uid/gid could not be read — the box cannot drop privileges without them. The host user database may be inconsistent.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_BOOT_FAILED: {
+        code: "AX-CAPSULE-006",
+        title: "Capsule Failed To Boot",
+        description: "The sandbox subprocess exited or reported failure before completing the boot handshake. The captured stderr in the error context is the real cause — most often a confinement mount that could not be satisfied (a declared fs path that does not exist) or a runtime that could not start.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_BOOT_TIMEOUT: {
+        code: "AX-CAPSULE-007",
+        title: "Capsule Boot Timed Out",
+        description: "The sandbox subprocess did not report ready within the boot timeout. Its captured stderr is in the error context; if empty, the subprocess may be hung rather than crashed.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_SPAWN_FAILED: {
+        code: "AX-CAPSULE-008",
+        title: "Capsule Spawn Failed",
+        description: "The capsule subprocess command could not be spawned at all — the interpreter or confinement wrapper was not found, or PATH is unset. Check that bun (and, under confinement, bwrap/systemd-run) are on PATH.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_WIRE_CLOSED: {
+        code: "AX-CAPSULE-009",
+        title: "Capsule Wire Closed",
+        description: "A command was sent to the sandbox after its stdin pipe was gone — the subprocess has exited or is mid-teardown. The caller is racing the capsule lifecycle.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_DOWN: {
+        code: "AX-CAPSULE-010",
+        title: "No Live Capsule",
+        description: "An operation needed a running sandbox subprocess, but none is live — it is booting, restarting after a crash, or has been declared dead.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_ALREADY_BOOTED: {
+        code: "AX-CAPSULE-011",
+        title: "Capsule Already Booted",
+        description: "boot() was called on a capsule that already has a live subprocess. Boot is once per lifetime; use update()/reload() to replace a running incarnation.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_INSTALL_FAILED: {
+        code: "AX-CAPSULE-013",
+        title: "Confinement Install Failed",
+        description: "Provisioning the host for the hardened confinement tier failed — most often because creating the dedicated system user needs root. Re-run `axon install` with sufficient privilege.",
+        source: "capsule",
+        severity: "fatal",
+    },
+    CAPSULE_HOST_UNAVAILABLE: {
+        code: "AX-CAPSULE-014",
+        title: "Host Bridge Unavailable",
+        description: "Sandboxed code called a host service, but this capsule was built with no host provider. Host calls require a wired host bridge on the manager side.",
+        source: "capsule",
+        severity: "fatal",
+    },
+
+    // ── TUI (useAgents.ts / platform/build/agent / platform/store / platform/services/cloud) ──
+    NOT_BOOTED: {
+        code: "AX-TUI-001",
+        title: "No Agent Running",
+        description: "A message was sent, or an action requiring a live agent was taken, before any agent finished booting.",
+        source: "tui",
+        severity: "fatal",
+    },
+    NOT_AUTHENTICATED: {
+        code: "AX-TUI-002",
+        title: "Not Logged In",
+        description: "The action needs an active profile, but none is logged in yet.",
+        source: "tui",
+        severity: "fatal",
+    },
+    PROFILE_NOT_AUTHENTICATED: {
+        code: "AX-TUI-003",
+        title: "Profile Has No Session",
+        description: "The target profile exists but has no stored session — it has never logged in, or its session was cleared.",
+        source: "tui",
+        severity: "fatal",
+    },
+    PROFILE_UNKNOWN: {
+        code: "AX-TUI-004",
+        title: "Unknown Profile",
+        description: "The requested profile id isn't one of the profiles stored on this machine.",
+        source: "tui",
+        severity: "fatal",
+    },
+    SESSION_ALREADY_RUNNING: {
+        code: "AX-TUI-005",
+        title: "Session Is Already Running",
+        description: "spawn() was asked to resume a session that already has a live instance. Focus the running instance instead of booting a second runtime over the same log.",
+        source: "tui",
+        severity: "fatal",
+    },
+    SESSION_NOT_RUNNING: {
+        code: "AX-TUI-016",
+        title: "Session Is Not Running",
+        description: "focus() was pointed at a sessionId with no live instance behind it. Spawn (or resume) it first — focus is pure selection over running instances.",
+        source: "tui",
+        severity: "fatal",
+    },
+    NO_FOCUSED_INSTANCE: {
+        code: "AX-TUI-017",
+        title: "No Focused Agent Instance",
+        description: "A module install/uninstall was requested with no running agent instance focused — spawn or focus one first.",
+        source: "tui",
+        severity: "fatal",
+    },
+    MODULE_INSTALL_FAILED: {
+        code: "AX-TUI-018",
+        title: "Module Install Failed",
+        description: "The registry installer returned an error for this module specifier — check the specifier and registry connectivity.",
+        source: "tui",
+        severity: "fatal",
+    },
+    NO_MODULES_INSTALLED: {
+        code: "AX-TUI-019",
+        title: "No Modules Installed",
+        description: "The :uninstall command was opened with no modules resolved into the focused instance's blueprint.",
+        source: "tui",
+        severity: "fatal",
+    },
+    BASE_UNMANAGED: {
+        code: "AX-TUI-006",
+        title: "Base Config Not Platform-Managed",
+        description: "The managed base workspace's config exists on disk but carries no platform manifest — it wasn't created by the platform and won't be overwritten automatically.",
+        source: "tui",
+        severity: "fatal",
+    },
+    BASE_CONFIG_MODIFIED: {
+        code: "AX-TUI-007",
+        title: "Base Config Edited By Hand",
+        description: "The managed base workspace's config no longer matches the hash the platform recorded — someone edited it directly, so the platform refuses to overwrite it.",
+        source: "tui",
+        severity: "fatal",
+    },
+    DEPLOYMENT_NOT_CONNECTABLE: {
+        code: "AX-TUI-028",
+        title: "Deployment Not Connectable",
+        description: "The deployment is not in the connectable list — it may have stopped, errored, or never finished provisioning. Refresh the deployment list and try again.",
+        source: "tui",
+        severity: "fatal",
+    },
+    SUBAGENT_REMOTE_PARENT: {
+        code: "AX-TUI-027",
+        title: "Cannot Spawn A Subagent From A Deployment",
+        description: "A subagent is forked from its parent's local project, and an attached deployment has no local project here — the deployed agent runs its own subagents inside its own capsule.",
+        source: "tui",
+        severity: "fatal",
+    },
+    BASE_MODEL_INSTANCE_CONFLICT: {
+        code: "AX-TUI-026",
+        title: "Managed Model Instance Already Running",
+        description: "A managed base instance is already running on a different engine. The base workspace holds one shared config, so spawning a second naked model would rewrite it underneath the live instance — close the running one first.",
+        source: "tui",
+        severity: "fatal",
+    },
+    NOT_WIRED: {
+        code: "AX-TUI-008",
+        title: "Not Wired Yet",
+        description: "This surface is a declared stub — the real implementation hasn't been built yet.",
+        source: "tui",
+        severity: "fatal",
+    },
+    MIC_ALREADY_CAPTURING: {
+        code: "AX-TUI-009",
+        title: "Mic Already Capturing",
+        description: "capture.start() was called while a capture was already in progress — stop the current one first.",
+        source: "tui",
+        severity: "fatal",
+    },
+    MIC_CAPTURE_UNAVAILABLE: {
+        code: "AX-TUI-010",
+        title: "No Audio Capture Tool Found",
+        description: "Voice input needs one of arecord, sox, or ffmpeg installed and on PATH.",
+        source: "tui",
+        severity: "fatal",
+    },
+    MIC_FFT_SIZE_MISMATCH: {
+        code: "AX-TUI-014",
+        title: "FFT Sample Size Mismatch",
+        description: "computeBuckets() was called with a sample buffer that isn't exactly config.fftSize long — an internal invariant, callers must pad/trim first.",
+        source: "tui",
+        severity: "fatal",
+    },
+    MIC_CAPTURE_FAILED: {
+        code: "AX-TUI-015",
+        title: "Mic Capture Failed",
+        description: "The audio capture subprocess produced no output or exited immediately — check that a microphone is available.",
+        source: "tui",
+        severity: "fatal",
+    },
+    WATCH_PATH_REQUIRED: {
+        code: "AX-TUI-021",
+        title: "Watch Path Required",
+        description: "`axon watch`/`axon unwatch` need a directory argument.",
+        source: "tui",
+        severity: "fatal",
+    },
+    WATCH_PATH_NOT_FOUND: {
+        code: "AX-TUI-022",
+        title: "Watch Path Not Found",
+        description: "`axon watch` was given a directory that doesn't exist on disk.",
+        source: "tui",
+        severity: "fatal",
+    },
+    EDITOR_NOT_SET: {
+        code: "AX-TUI-023",
+        title: "No Editor Configured",
+        description: "`axon settings` needs the $EDITOR environment variable set to know which editor to open.",
+        source: "tui",
+        severity: "fatal",
+    },
+    EDITOR_LAUNCH_FAILED: {
+        code: "AX-TUI-024",
+        title: "Editor Failed To Launch",
+        description: "The command in $EDITOR could not be spawned — check that it's installed and on PATH.",
+        source: "tui",
+        severity: "fatal",
+    },
+    WATCH_AND_INIT_ARGS_REQUIRED: {
+        code: "AX-TUI-025",
+        title: "Directory And Name Required",
+        description: "The init palette's \"watch a new directory\" entry needs both a directory path and an agent name, space-separated.",
+        source: "tui",
+        severity: "fatal",
+    },
+
+    // ── Module boot-time execution (core runs defineModule setup) ────────────
+    MODULE_CONFIG_LOAD_FAILED: {
+        code: "AX-MODULE-001",
+        title: "Module Config Failed To Load",
+        description: "The runtime could not import a module's module.config.ts at boot — the file is missing at its resolved path, or importing it threw. A module that cannot load contributes nothing, so boot fails rather than run a partially-wired agent.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    MODULE_OPTIONS_INVALID: {
+        code: "AX-MODULE-002",
+        title: "Invalid Module Options",
+        description: "The options declared for a module under modules.<name> in axon.config.ts do not satisfy the module's options schema — a required option is missing or a value has the wrong type.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    MODULE_SETUP_FAILED: {
+        code: "AX-MODULE-003",
+        title: "Module Setup Failed",
+        description: "A module's setup() threw during agent boot. Setup runs sequentially in blueprint order and a failure is total — no later module is wired, and the agent does not boot half-configured.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    MODULE_SERVER_NOT_WIRED: {
+        code: "AX-MODULE-004",
+        title: "Module Server API Not Wired",
+        description: "A module's setup() called ctx.server.addRoute/addMiddleware or ctx.tools.get, but that surface is not implemented yet. Declare routes as server/api/ files in the module instead.",
+        source: "runtime",
+        severity: "fatal",
+    },
+    MODULE_ENV_REQUIRED: {
+        code: "AX-MODULE-005",
+        title: "Module Env Var Missing",
+        description: "A module's setup() called ctx.env.require() for a variable the agent's resolved environment does not provide. The module declares required env in module.config.ts; the agent must supply it (e.g. in .env).",
+        source: "runtime",
+        severity: "fatal",
+    },
+    MODULE_POLICY_IMMUTABLE: {
+        code: "AX-MODULE-006",
+        title: "Module Policy Is Immutable At Boot",
+        description: "A module's setup() called ctx.policy.update(). The resolved agent policy is authoritative and cannot be mutated at boot — declare policy needs statically in module.config.ts so the CLI reconciles them at install.",
+        source: "runtime",
+        severity: "fatal",
+    },
+} as const satisfies Record<string, AxonErrorMapEntry>
+
+export type AxonErrorMap = typeof errorMap
+export type AxonErrorCode = keyof AxonErrorMap