@arcforge/err 2.0.153 → 2.0.154

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@arcforge/err",
-    "version": "2.0.153",
+    "version": "2.0.154",
     "description": "Structured Axon errors — the code map every user-facing failure is rendered from.",
     "type": "module",
     "private": false,
@@ -15,7 +15,7 @@
         "deploy": "echo \"This package is published ONLY by apps/tui/scripts/release.ts, which pins workspace:* deps to concrete versions first. Publishing it directly ships an unresolvable dependency.\" && exit 1"
     },
     "dependencies": {
-        "@arcforge/types": "2.0.153"
+        "@arcforge/types": "2.0.154"
     },
     "devDependencies": {
         "@types/bun": "latest",

package/src/index.ts

@@ -9,4 +9,4 @@ export {
     type AxonErrorSeverity,
     type AxonErrorSource,
 } from "./map"
-export { errScope, type AxonErrorSink } from "./sink"
+export { errScope, observeErrors, type AxonErrorSink } from "./sink"

package/src/map.ts

@@ -316,12 +316,23 @@ export const errorMap = {
         source: "manifest",
         severity: "fatal",
     },
-    CONFIG_ENGINE_UNPARSEABLE: {
+    /**
+     * Replaced CONFIG_ENGINE_UNPARSEABLE, which described AST-editing an
+     * `engine: X({ ... })` call — a field that no longer exists. Warning
+     * rather than fatal for the deprecation window: an agent carrying
+     * `engine:` still boots (on the profile pool, which is what it was
+     * silently doing already), and the author gets told once per load what
+     * to write instead. It becomes fatal when the field is removed.
+     */
+    CONFIG_ENGINE_DEPRECATED: {
         code: "AX-PROJECT-033",
-        title: "Could Not Edit The Engine In axon.config.ts",
-        description: "The agent's `engine: X({ ... })` declaration could not be located or rewritten automatically — set the model by hand.",
+        title: "`engine:` Is Deprecated And Ignored",
+        description: "This agent's axon.config.ts declares `engine:`, which the runtime no longer reads — inference is resolving against the profile's providers instead. Use `model: \"codex:gpt-5.6-terra\"` for a cortex pin, and `providers: [...]` for a source the user would not otherwise have.",
         source: "manifest",
-        severity: "fatal",
+        // DEGRADED, not fatal: the agent boots and runs, but not on the
+        // inference its config names. That is exactly what degraded means,
+        // and it is the honest label for the deprecation window.
+        severity: "degraded",
     },
     MODULE_DEPENDENCY_INSTALL_FAILED: {
         code: "AX-PROJECT-004",
@@ -1011,7 +1022,12 @@ export const errorMap = {
         severity: "degraded",
     },
     KNOWLEDGE_ESCAPE: {
-        code: "AX-KERNEL-012",
+        // Was AX-KERNEL-012, which CODEX_NOT_CONNECTED already holds and which
+        // is deliberately retained retired so that code keeps its original
+        // meaning. Two entries sharing a code is exactly what that comment
+        // warns against — a support thread quoting AX-KERNEL-012 could have
+        // meant either a disconnected provider or a path traversal.
+        code: "AX-KERNEL-021",
         title: "Knowledge Path Escapes Store",
         description: "A knowledge name resolved outside the store root. Names are identifiers, not paths — traversal is refused at the boundary rather than trusted not to happen.",
         source: "kernel",

package/src/sink.ts

@@ -31,7 +31,60 @@ export const errScope = {
     },
 }
 
-/** err()'s delivery call — the current scope's sink, or nothing (see module doc). */
+/**
+ * Observers that see EVERY error, regardless of scope.
+ *
+ * Separate from the scoped sink above because they answer a different
+ * question. The scoped sink asks "whose durable record does this belong
+ * to" — attribution, where being wrong is a lie on disk, which is why it is
+ * exclusive and innermost-wins. An observer asks "did this happen at all",
+ * where the failure mode of getting it wrong is a missing report, not a
+ * false one.
+ *
+ * Making crash reporting a second scope would have meant either competing
+ * with the session for the same slot (whichever ran last wins, errors
+ * vanish) or two AsyncLocalStorage contexts to keep in sync at every entry
+ * point. A flat observer list has neither problem: it fires for errors
+ * constructed inside a session scope AND for the ones outside it, which are
+ * exactly the CLI and tooling failures a session log could never see.
+ *
+ * Deliberately NOT given the ability to suppress or alter the error. An
+ * observer is told, not consulted.
+ */
+const observers = new Set<AxonErrorSink>()
+
+/**
+ * Watch every error constructed anywhere in this process.
+ *
+ * Returns an unsubscribe function. Intended for ONE caller per process —
+ * the host's crash reporter — established at startup. A leaf reaching for
+ * this is a design error: leaves throw, hosts observe.
+ */
+export function observeErrors(observer: AxonErrorSink): () => void {
+    observers.add(observer)
+    return () => observers.delete(observer)
+}
+
+/**
+ * err()'s delivery call — the current scope's sink, then every observer.
+ *
+ * An observer that throws must never break error CONSTRUCTION: err() is on
+ * the failure path by definition, and a reporter that turns one failure
+ * into two (the original plus its own) is worse than no reporter. Each is
+ * isolated so one bad observer cannot starve the rest.
+ *
+ * The scoped sink is called first and is deliberately NOT wrapped — it is
+ * the runtime's own durable record, and a failure to write it is a real
+ * problem the runtime should see, not something this function should hide.
+ */
 export function emitError(error: AxonError): void {
     storage.getStore()?.(error)
+
+    for (const observer of observers) {
+        try {
+            observer(error)
+        } catch {
+            // See above — an observer's fault never propagates into err().
+        }
+    }
 }