@makaio/framework 1.0.0-dev-1789642522820 → 1.0.0-dev-1790087128488

package/dist/{index-zEkS2L862.d.mts → index-D9ExWo6a2.d.mts}

@@ -18,10 +18,10 @@ import { ExtensionWarningEntry, ExtensionWarningEntrySchema } from "@makaio/fram
  * detail, not an externally observable state.
  */
 declare const ComponentStateSchema: z.ZodEnum<{
-  discovered: "discovered";
   failed: "failed";
-  active: "active";
+  discovered: "discovered";
   skipped: "skipped";
+  active: "active";
   stopped: "stopped";
   initializing: "initializing";
 }>;
@@ -47,10 +47,10 @@ declare const ComponentInfoSchema: z.ZodObject<{
   name: z.ZodString;
   displayName: z.ZodString;
   state: z.ZodEnum<{
-    discovered: "discovered";
     failed: "failed";
-    active: "active";
+    discovered: "discovered";
     skipped: "skipped";
+    active: "active";
     stopped: "stopped";
     initializing: "initializing";
   }>;
@@ -68,10 +68,10 @@ declare const ServiceInfoSchema: z.ZodObject<{
   name: z.ZodString;
   displayName: z.ZodString;
   state: z.ZodEnum<{
-    discovered: "discovered";
     failed: "failed";
-    active: "active";
+    discovered: "discovered";
     skipped: "skipped";
+    active: "active";
     stopped: "stopped";
     initializing: "initializing";
   }>;
@@ -90,10 +90,10 @@ declare const ExtensionInfoSchema: z.ZodObject<{
   name: z.ZodString;
   displayName: z.ZodString;
   state: z.ZodEnum<{
-    discovered: "discovered";
     failed: "failed";
-    active: "active";
+    discovered: "discovered";
     skipped: "skipped";
+    active: "active";
     stopped: "stopped";
     initializing: "initializing";
   }>;
@@ -104,6 +104,9 @@ declare const ExtensionInfoSchema: z.ZodObject<{
     headless: "headless";
   }>>;
   enabled: z.ZodBoolean;
+  extensionManaged: z.ZodBoolean;
+  persistedEnabled: z.ZodOptional<z.ZodBoolean>;
+  critical: z.ZodBoolean;
   browser: z.ZodOptional<z.ZodObject<{
     entrypoint: z.ZodString;
   }, z.core.$strip>>;
@@ -112,6 +115,92 @@ declare const ExtensionInfoSchema: z.ZodObject<{
 type ExtensionInfo = z.infer<typeof ExtensionInfoSchema>;
 //#endregion
 //#region packages/kernel/src/observability/extension-namespace.d.ts
+/**
+ * Outcome of one `kernel:extension.setEnabled` request.
+ *
+ * Mirrors the `TransitionOutcome` union the coordinator's toggle helpers
+ * compute internally (see `extension/extension-toggle.ts`) so the bus
+ * response can carry the same fidelity instead of collapsing it to a single
+ * `success` boolean. `kernel:extension.setEnabled` is persist-only — it never
+ * runs a live state-machine transition — so for that RPC this is a
+ * comparison between the durably persisted preference and the process's
+ * actual runtime state, not the result of an attempted transition:
+ * - `'applied'` — the persisted preference already matches the process's
+ *   current runtime state; no restart is needed for it to take effect.
+ * - `'rejected'` — the request was refused outright without persisting
+ *   anything: an unknown extension name, a disable of a `critical` package or
+ *   of one whose criticality could not be resolved, or a coordinator already
+ *   shutting down. Every such refusal is a *response*, carrying a
+ *   {@link SetEnabledReasonSchema} code for which one it was, rather than a
+ *   fault — a caller that cannot inspect the host itself must be able to tell
+ *   "refused, and here is why" apart from "the call failed".
+ *   `TransitionOutcome` is shared with the coordinator-internal
+ *   `applyExtensionTransition` primitive, where `'rejected'` additionally
+ *   covers a state-machine refusal such as retrying a transition on an entry
+ *   the boot phase skipped entirely.
+ * - `'restart-required'` — the preference was persisted, but it diverges
+ *   from the process's current runtime state; only the next process restart
+ *   applies it.
+ */
+declare const TransitionOutcomeSchema: z.ZodEnum<{
+  rejected: "rejected";
+  applied: "applied";
+  "restart-required": "restart-required";
+}>;
+/** Inferred union type for {@link TransitionOutcomeSchema}. */
+type TransitionOutcome = z.infer<typeof TransitionOutcomeSchema>;
+/**
+ * Machine-readable detail accompanying one `kernel:extension.setEnabled`
+ * outcome.
+ *
+ * The {@link TransitionOutcomeSchema} alone cannot tell a caller *why* a
+ * request was refused, or why a persisted preference cannot take effect yet —
+ * both of which decide what an operator is told and whether they can act on
+ * it. Codes rather than prose so the wording stays with the surface that
+ * renders it:
+ *
+ * Refusals (`'rejected'`, nothing was written):
+ * - `'critical'` — a disable targeting a `critical` package. The runtime
+ *   force-starts it on every boot regardless of the store, so persisting the
+ *   disable would only produce a permanent, ignored entry.
+ * - `'criticality-unknown'` — a disable targeting a package whose criticality
+ *   could not be resolved, because its server entrypoint could not be read.
+ *   Fail-closed: a later boot that *can* read the export might force-start it.
+ * - `'not-installed'` — no loaded extension and no installed package carries
+ *   this name on this host.
+ * - `'no-catalog'` — the name is not loaded here and this runtime exposes no
+ *   installed-extension catalog, so it cannot tell a real installed package
+ *   apart from a typo and refuses rather than persisting on the caller's word.
+ * - `'name-collision'` — more than one installed package claims this name and
+ *   the runtime cannot resolve it to a single extension, so the next boot
+ *   refuses before any preference is read. A preference written now could
+ *   never be acted on, and would silently apply to whichever copy an operator
+ *   happens to leave behind.
+ * - `'shutting-down'` — the coordinator is tearing down.
+ *
+ * Persisted, but not in effect (`'restart-required'`, or `'applied'` when the
+ * runtime already matches the request):
+ * - `'runtime-state-diverges'` — the loaded extension's runtime state differs
+ *   from the persisted preference; only a restart reconciles them.
+ * - `'not-loaded'` — the package is installed but this process never loaded it
+ *   (surface affinity, unmet requirements, or boot-time suppression).
+ * - `'framework-package-shadowed'` — a framework package currently holds this
+ *   name, so the installed package under it stays shadowed until it no longer
+ *   does.
+ */
+declare const SetEnabledReasonSchema: z.ZodEnum<{
+  critical: "critical";
+  "not-installed": "not-installed";
+  "criticality-unknown": "criticality-unknown";
+  "no-catalog": "no-catalog";
+  "name-collision": "name-collision";
+  "shutting-down": "shutting-down";
+  "runtime-state-diverges": "runtime-state-diverges";
+  "not-loaded": "not-loaded";
+  "framework-package-shadowed": "framework-package-shadowed";
+}>;
+/** Inferred union type for {@link SetEnabledReasonSchema}. */
+type SetEnabledReason = z.infer<typeof SetEnabledReasonSchema>;
 /**
  * Extension namespace for bus operations.
  */
@@ -138,18 +227,18 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
     name: z.ZodString;
     displayName: z.ZodString;
     from: z.ZodEnum<{
-      discovered: "discovered";
       failed: "failed";
-      active: "active";
+      discovered: "discovered";
       skipped: "skipped";
+      active: "active";
       stopped: "stopped";
       initializing: "initializing";
     }>;
     to: z.ZodEnum<{
-      discovered: "discovered";
       failed: "failed";
-      active: "active";
+      discovered: "discovered";
       skipped: "skipped";
+      active: "active";
       stopped: "stopped";
       initializing: "initializing";
     }>;
@@ -181,10 +270,10 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
         name: z.ZodString;
         displayName: z.ZodString;
         state: z.ZodEnum<{
-          discovered: "discovered";
           failed: "failed";
-          active: "active";
+          discovered: "discovered";
           skipped: "skipped";
+          active: "active";
           stopped: "stopped";
           initializing: "initializing";
         }>;
@@ -195,6 +284,9 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
           headless: "headless";
         }>>;
         enabled: z.ZodBoolean;
+        extensionManaged: z.ZodBoolean;
+        persistedEnabled: z.ZodOptional<z.ZodBoolean>;
+        critical: z.ZodBoolean;
         browser: z.ZodOptional<z.ZodObject<{
           entrypoint: z.ZodString;
         }, z.core.$strip>>;
@@ -219,10 +311,10 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
         name: z.ZodString;
         displayName: z.ZodString;
         state: z.ZodEnum<{
-          discovered: "discovered";
           failed: "failed";
-          active: "active";
+          discovered: "discovered";
           skipped: "skipped";
+          active: "active";
           stopped: "stopped";
           initializing: "initializing";
         }>;
@@ -233,6 +325,9 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
           headless: "headless";
         }>>;
         enabled: z.ZodBoolean;
+        extensionManaged: z.ZodBoolean;
+        persistedEnabled: z.ZodOptional<z.ZodBoolean>;
+        critical: z.ZodBoolean;
         browser: z.ZodOptional<z.ZodObject<{
           entrypoint: z.ZodString;
         }, z.core.$strip>>;
@@ -240,13 +335,30 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
     }, z.core.$strip>;
   };
   /**
-   * Enable or disable an extension at runtime.
+   * Durably record the operator's enablement preference for an extension.
    *
    * Subject: `kernel:extension.setEnabled`
    * Type: RPC (request/response)
-   * Purpose: Allows the user or platform config to toggle an extension without
-   * a full restart. The coordinator re-enters the load path on enable, or runs
-   * cleanup and transitions to `stopped` on disable.
+   * Purpose: Allows the user or platform config to persist an enable/disable
+   * preference for an extension. This is persist-only: the coordinator never
+   * applies the change to the running process, because several package
+   * contributions are composed exactly once at boot and cannot be replayed
+   * for one package in isolation. The response's `outcome` reports whether
+   * the process's current runtime state already matches the request
+   * (`'applied'`) or a restart is needed for it to take effect
+   * (`'restart-required'`).
+   *
+   * Names this coordinator never loaded are addressable too, provided it
+   * exposes an installed-extension catalog (`kernel:extension.catalog`): the
+   * request is validated against that catalog — the name must be installed
+   * here, and a disable of a `critical` package, or of one whose criticality
+   * could not be resolved, is refused — before anything is written. This is
+   * what lets a caller that cannot see this host's filesystem persist a
+   * preference without having to vouch for the name itself. A name several
+   * installed copies claim is resolved against this coordinator's own runtime
+   * surface first, since two copies restricted to different surfaces both load
+   * — each on its own — and only one of them is the copy this runtime would
+   * start; a name that stays unresolvable is refused outright.
    * @param name - Unique extension identifier to toggle.
    * @param enabled - Target enabled state.
    */
@@ -257,6 +369,77 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
     }, z.core.$strip>;
     response: z.ZodObject<{
       success: z.ZodBoolean;
+      outcome: z.ZodEnum<{
+        rejected: "rejected";
+        applied: "applied";
+        "restart-required": "restart-required";
+      }>;
+      reason: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        "not-installed": "not-installed";
+        "criticality-unknown": "criticality-unknown";
+        "no-catalog": "no-catalog";
+        "name-collision": "name-collision";
+        "shutting-down": "shutting-down";
+        "runtime-state-diverges": "runtime-state-diverges";
+        "not-loaded": "not-loaded";
+        "framework-package-shadowed": "framework-package-shadowed";
+      }>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Request every extension package installed on the host running this
+   * coordinator.
+   *
+   * Subject: `kernel:extension.catalog`
+   * Type: RPC (request/response)
+   * Purpose: Exposes the coordinator host's own installed-package view —
+   * across every discovery tier it reads, including the project-local
+   * `node_modules` of the directory it was started from — enriched with the
+   * enablement facts only the host holding the durable store can answer.
+   * Callers that cannot inspect this host's filesystem (a client configured
+   * against a remote bus, or one invoked from a different working directory)
+   * have no other way to enumerate installed-but-not-loaded extensions, and
+   * `kernel:extension.setEnabled` validates against this same catalog.
+   *
+   * Returns `{ entries: null }` — not an empty array — when this runtime has
+   * no installed-extension catalog at all, because "nothing is installed" and
+   * "this host cannot answer" must not read alike to a caller deciding
+   * whether to trust the result.
+   */
+  catalog: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      entries: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        origin: z.ZodEnum<{
+          local: "local";
+          npm: "npm";
+          "project-local": "project-local";
+        }>;
+        critical: z.ZodOptional<z.ZodBoolean>;
+        criticalityUnknown: z.ZodOptional<z.ZodBoolean>;
+        declaresServerEntrypoint: z.ZodOptional<z.ZodBoolean>;
+        npmName: z.ZodOptional<z.ZodString>;
+        surface: z.ZodOptional<z.ZodEnum<{
+          interactive: "interactive";
+          headless: "headless";
+        }>>;
+        shadowedBy: z.ZodOptional<z.ZodEnum<{
+          local: "local";
+          npm: "npm";
+          "project-local": "project-local";
+        }>>;
+        collidesWith: z.ZodOptional<z.ZodEnum<{
+          local: "local";
+          npm: "npm";
+          "project-local": "project-local";
+        }>>;
+        collisionIgnoresSurface: z.ZodOptional<z.ZodBoolean>;
+        extensionManaged: z.ZodBoolean;
+        persistedEnabled: z.ZodOptional<z.ZodBoolean>;
+      }, z.core.$strip>>>;
     }, z.core.$strip>;
   };
   /**
@@ -506,14 +689,24 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
     }, z.core.$strip>;
   };
   /**
-   * Signal that an extension's enabled state has changed.
+   * Confirm an accepted enable/disable call and the extension's effective state.
    *
    * Subject: `kernel:extension.enabledChanged`
    * Type: Event (fire-and-forget)
-   * Purpose: Emitted after a successful `kernel:extension.setEnabled` call so
-   * observers can react to enable/disable changes without polling.
+   * Purpose: Emitted whenever the coordinator-internal
+   * `applyExtensionTransition` restart primitive accepts an enable/disable
+   * request (its outcome is `'applied'`, never `'rejected'`), so observers
+   * can learn the extension's effective runtime state without polling. This
+   * is **not** a promise that a state transition actually occurred: an
+   * idempotent enable-on-`active` or disable-on-`stopped` call is also
+   * `'applied'` and also announced here, with `entry.enabled` unchanged.
+   * `kernel:extension.setEnabled` does **not** emit this event: that RPC is
+   * persist-only and never attempts a live transition (see its own doc
+   * above), so a durable preference change whose `outcome` is `'applied'` or
+   * `'restart-required'` produces no `enabledChanged` event until whatever
+   * coordinator-internal mechanism actually restarts the extension.
    * @param name - Unique extension identifier.
-   * @param enabled - New enabled state.
+   * @param enabled - The extension's effective enabled state after the call.
    */
   enabledChanged: z.ZodObject<{
     name: z.ZodString;
@@ -539,8 +732,8 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
         extensionName: z.ZodString;
         warnings: z.ZodArray<z.ZodObject<{
           severity: z.ZodEnum<{
-            info: "info";
             degraded: "degraded";
+            info: "info";
             recommended: "recommended";
           }>;
           title: z.ZodString;
@@ -579,8 +772,8 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
     extensionName: z.ZodString;
     warnings: z.ZodArray<z.ZodObject<{
       severity: z.ZodEnum<{
-        info: "info";
         degraded: "degraded";
+        info: "info";
         recommended: "recommended";
       }>;
       title: z.ZodString;
@@ -609,8 +802,9 @@ declare const ExtensionNamespace: _$_makaio_core0.BusNamespaceDefinition<"kernel
  * - `stateChanged`        — event: emitted when an extension transitions between lifecycle states
  * - `list`                — RPC: retrieve all registered extensions and their current state
  * - `get`                 — RPC: retrieve a single extension's info by name
- * - `setEnabled`          — RPC: enable or disable an extension at runtime
- * - `enabledChanged`      — event: emitted when an extension's enabled flag changes
+ * - `setEnabled`          — RPC: persist an operator enable/disable preference
+ * - `catalog`             — RPC: list every extension package installed on the coordinator's host
+ * - `enabledChanged`      — event: confirms an accepted enable/disable call and the extension's effective state
  * - `warnings.list`       — RPC: retrieve active health warnings for all (or one) extension
  * - `warnings.changed`    — event: emitted after every health-check run with the latest warning snapshot
  * @example
@@ -644,18 +838,18 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
     name: z.ZodString;
     displayName: z.ZodString;
     from: z.ZodEnum<{
-      discovered: "discovered";
       failed: "failed";
-      active: "active";
+      discovered: "discovered";
       skipped: "skipped";
+      active: "active";
       stopped: "stopped";
       initializing: "initializing";
     }>;
     to: z.ZodEnum<{
-      discovered: "discovered";
       failed: "failed";
-      active: "active";
+      discovered: "discovered";
       skipped: "skipped";
+      active: "active";
       stopped: "stopped";
       initializing: "initializing";
     }>;
@@ -687,10 +881,10 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
         name: z.ZodString;
         displayName: z.ZodString;
         state: z.ZodEnum<{
-          discovered: "discovered";
           failed: "failed";
-          active: "active";
+          discovered: "discovered";
           skipped: "skipped";
+          active: "active";
           stopped: "stopped";
           initializing: "initializing";
         }>;
@@ -701,6 +895,9 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
           headless: "headless";
         }>>;
         enabled: z.ZodBoolean;
+        extensionManaged: z.ZodBoolean;
+        persistedEnabled: z.ZodOptional<z.ZodBoolean>;
+        critical: z.ZodBoolean;
         browser: z.ZodOptional<z.ZodObject<{
           entrypoint: z.ZodString;
         }, z.core.$strip>>;
@@ -725,10 +922,10 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
         name: z.ZodString;
         displayName: z.ZodString;
         state: z.ZodEnum<{
-          discovered: "discovered";
           failed: "failed";
-          active: "active";
+          discovered: "discovered";
           skipped: "skipped";
+          active: "active";
           stopped: "stopped";
           initializing: "initializing";
         }>;
@@ -739,6 +936,9 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
           headless: "headless";
         }>>;
         enabled: z.ZodBoolean;
+        extensionManaged: z.ZodBoolean;
+        persistedEnabled: z.ZodOptional<z.ZodBoolean>;
+        critical: z.ZodBoolean;
         browser: z.ZodOptional<z.ZodObject<{
           entrypoint: z.ZodString;
         }, z.core.$strip>>;
@@ -746,13 +946,30 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
     }, z.core.$strip>;
   };
   /**
-   * Enable or disable an extension at runtime.
+   * Durably record the operator's enablement preference for an extension.
    *
    * Subject: `kernel:extension.setEnabled`
    * Type: RPC (request/response)
-   * Purpose: Allows the user or platform config to toggle an extension without
-   * a full restart. The coordinator re-enters the load path on enable, or runs
-   * cleanup and transitions to `stopped` on disable.
+   * Purpose: Allows the user or platform config to persist an enable/disable
+   * preference for an extension. This is persist-only: the coordinator never
+   * applies the change to the running process, because several package
+   * contributions are composed exactly once at boot and cannot be replayed
+   * for one package in isolation. The response's `outcome` reports whether
+   * the process's current runtime state already matches the request
+   * (`'applied'`) or a restart is needed for it to take effect
+   * (`'restart-required'`).
+   *
+   * Names this coordinator never loaded are addressable too, provided it
+   * exposes an installed-extension catalog (`kernel:extension.catalog`): the
+   * request is validated against that catalog — the name must be installed
+   * here, and a disable of a `critical` package, or of one whose criticality
+   * could not be resolved, is refused — before anything is written. This is
+   * what lets a caller that cannot see this host's filesystem persist a
+   * preference without having to vouch for the name itself. A name several
+   * installed copies claim is resolved against this coordinator's own runtime
+   * surface first, since two copies restricted to different surfaces both load
+   * — each on its own — and only one of them is the copy this runtime would
+   * start; a name that stays unresolvable is refused outright.
    * @param name - Unique extension identifier to toggle.
    * @param enabled - Target enabled state.
    */
@@ -763,6 +980,77 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
     }, z.core.$strip>;
     response: z.ZodObject<{
       success: z.ZodBoolean;
+      outcome: z.ZodEnum<{
+        rejected: "rejected";
+        applied: "applied";
+        "restart-required": "restart-required";
+      }>;
+      reason: z.ZodOptional<z.ZodEnum<{
+        critical: "critical";
+        "not-installed": "not-installed";
+        "criticality-unknown": "criticality-unknown";
+        "no-catalog": "no-catalog";
+        "name-collision": "name-collision";
+        "shutting-down": "shutting-down";
+        "runtime-state-diverges": "runtime-state-diverges";
+        "not-loaded": "not-loaded";
+        "framework-package-shadowed": "framework-package-shadowed";
+      }>>;
+    }, z.core.$strip>;
+  };
+  /**
+   * Request every extension package installed on the host running this
+   * coordinator.
+   *
+   * Subject: `kernel:extension.catalog`
+   * Type: RPC (request/response)
+   * Purpose: Exposes the coordinator host's own installed-package view —
+   * across every discovery tier it reads, including the project-local
+   * `node_modules` of the directory it was started from — enriched with the
+   * enablement facts only the host holding the durable store can answer.
+   * Callers that cannot inspect this host's filesystem (a client configured
+   * against a remote bus, or one invoked from a different working directory)
+   * have no other way to enumerate installed-but-not-loaded extensions, and
+   * `kernel:extension.setEnabled` validates against this same catalog.
+   *
+   * Returns `{ entries: null }` — not an empty array — when this runtime has
+   * no installed-extension catalog at all, because "nothing is installed" and
+   * "this host cannot answer" must not read alike to a caller deciding
+   * whether to trust the result.
+   */
+  catalog: {
+    request: z.ZodObject<{}, z.core.$strip>;
+    response: z.ZodObject<{
+      entries: z.ZodNullable<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        origin: z.ZodEnum<{
+          local: "local";
+          npm: "npm";
+          "project-local": "project-local";
+        }>;
+        critical: z.ZodOptional<z.ZodBoolean>;
+        criticalityUnknown: z.ZodOptional<z.ZodBoolean>;
+        declaresServerEntrypoint: z.ZodOptional<z.ZodBoolean>;
+        npmName: z.ZodOptional<z.ZodString>;
+        surface: z.ZodOptional<z.ZodEnum<{
+          interactive: "interactive";
+          headless: "headless";
+        }>>;
+        shadowedBy: z.ZodOptional<z.ZodEnum<{
+          local: "local";
+          npm: "npm";
+          "project-local": "project-local";
+        }>>;
+        collidesWith: z.ZodOptional<z.ZodEnum<{
+          local: "local";
+          npm: "npm";
+          "project-local": "project-local";
+        }>>;
+        collisionIgnoresSurface: z.ZodOptional<z.ZodBoolean>;
+        extensionManaged: z.ZodBoolean;
+        persistedEnabled: z.ZodOptional<z.ZodBoolean>;
+      }, z.core.$strip>>>;
     }, z.core.$strip>;
   };
   /**
@@ -1012,14 +1300,24 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
     }, z.core.$strip>;
   };
   /**
-   * Signal that an extension's enabled state has changed.
+   * Confirm an accepted enable/disable call and the extension's effective state.
    *
    * Subject: `kernel:extension.enabledChanged`
    * Type: Event (fire-and-forget)
-   * Purpose: Emitted after a successful `kernel:extension.setEnabled` call so
-   * observers can react to enable/disable changes without polling.
+   * Purpose: Emitted whenever the coordinator-internal
+   * `applyExtensionTransition` restart primitive accepts an enable/disable
+   * request (its outcome is `'applied'`, never `'rejected'`), so observers
+   * can learn the extension's effective runtime state without polling. This
+   * is **not** a promise that a state transition actually occurred: an
+   * idempotent enable-on-`active` or disable-on-`stopped` call is also
+   * `'applied'` and also announced here, with `entry.enabled` unchanged.
+   * `kernel:extension.setEnabled` does **not** emit this event: that RPC is
+   * persist-only and never attempts a live transition (see its own doc
+   * above), so a durable preference change whose `outcome` is `'applied'` or
+   * `'restart-required'` produces no `enabledChanged` event until whatever
+   * coordinator-internal mechanism actually restarts the extension.
    * @param name - Unique extension identifier.
-   * @param enabled - New enabled state.
+   * @param enabled - The extension's effective enabled state after the call.
    */
   enabledChanged: z.ZodObject<{
     name: z.ZodString;
@@ -1045,8 +1343,8 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
         extensionName: z.ZodString;
         warnings: z.ZodArray<z.ZodObject<{
           severity: z.ZodEnum<{
-            info: "info";
             degraded: "degraded";
+            info: "info";
             recommended: "recommended";
           }>;
           title: z.ZodString;
@@ -1085,8 +1383,8 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
     extensionName: z.ZodString;
     warnings: z.ZodArray<z.ZodObject<{
       severity: z.ZodEnum<{
-        info: "info";
         degraded: "degraded";
+        info: "info";
         recommended: "recommended";
       }>;
       title: z.ZodString;
@@ -1109,4 +1407,100 @@ declare const ExtensionSubjects: _$_makaio_core0.BusSubjects<_$_makaio_core0.Fla
   }, z.core.$strip>;
 }>, "kernel:extension">;
 //#endregion
-export { ComponentInfoSchema as a, ExtensionInfo as c, ExtensionWarningEntrySchema as d, ServiceInfo as f, ComponentInfo as i, ExtensionInfoSchema as l, ExtensionSubjects as n, ComponentState as o, ServiceInfoSchema as p, ComponentIdentitySchema as r, ComponentStateSchema as s, ExtensionNamespace as t, ExtensionWarningEntry as u };
+//#region packages/kernel/src/observability/installed-extension-catalog-schemas.d.ts
+/**
+ * Discovery tier an installed extension package was found in.
+ *
+ * - `'project-local'` — the highest-priority tier: the `node_modules` of the
+ *   project directory the runtime was started from, or the descriptor roots a
+ *   host declared for itself in runtime config, which rank the same.
+ * - `'local'` — a symlinked install under the data home's `extensions/`.
+ * - `'npm'` — a registry install under the data home's `node_modules/`.
+ *
+ * Reported verbatim so a caller can tell an extension shared through the data
+ * home apart from one that only exists in the host's own project tree.
+ */
+declare const InstalledExtensionOriginSchema: z.ZodEnum<{
+  local: "local";
+  npm: "npm";
+  "project-local": "project-local";
+}>;
+/** Inferred union of installed-extension discovery tiers. */
+type InstalledExtensionOrigin = z.infer<typeof InstalledExtensionOriginSchema>;
+/**
+ * One installed executable extension package, as seen without starting any
+ * extension service.
+ *
+ * Keyed by executable package identity — the descriptor name, or one of its
+ * dot-prefixed children — because that is what the enablement store, the
+ * runtime loader, and every enablement RPC address. A single descriptor whose
+ * server entrypoint exports several packages produces one record per package.
+ */
+declare const InstalledExtensionRecordSchema: z.ZodObject<{
+  name: z.ZodString;
+  version: z.ZodString;
+  origin: z.ZodEnum<{
+    local: "local";
+    npm: "npm";
+    "project-local": "project-local";
+  }>;
+  critical: z.ZodOptional<z.ZodBoolean>;
+  criticalityUnknown: z.ZodOptional<z.ZodBoolean>;
+  declaresServerEntrypoint: z.ZodOptional<z.ZodBoolean>;
+  npmName: z.ZodOptional<z.ZodString>;
+  surface: z.ZodOptional<z.ZodEnum<{
+    interactive: "interactive";
+    headless: "headless";
+  }>>;
+  shadowedBy: z.ZodOptional<z.ZodEnum<{
+    local: "local";
+    npm: "npm";
+    "project-local": "project-local";
+  }>>;
+  collidesWith: z.ZodOptional<z.ZodEnum<{
+    local: "local";
+    npm: "npm";
+    "project-local": "project-local";
+  }>>;
+  collisionIgnoresSurface: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Inferred type for one installed executable extension package. */
+type InstalledExtensionRecord = z.infer<typeof InstalledExtensionRecordSchema>;
+/**
+ * One installed package as reported over the bus, enriched with the enablement
+ * facts only the coordinator holding the durable store can answer.
+ */
+declare const InstalledExtensionCatalogEntrySchema: z.ZodObject<{
+  name: z.ZodString;
+  version: z.ZodString;
+  origin: z.ZodEnum<{
+    local: "local";
+    npm: "npm";
+    "project-local": "project-local";
+  }>;
+  critical: z.ZodOptional<z.ZodBoolean>;
+  criticalityUnknown: z.ZodOptional<z.ZodBoolean>;
+  declaresServerEntrypoint: z.ZodOptional<z.ZodBoolean>;
+  npmName: z.ZodOptional<z.ZodString>;
+  surface: z.ZodOptional<z.ZodEnum<{
+    interactive: "interactive";
+    headless: "headless";
+  }>>;
+  shadowedBy: z.ZodOptional<z.ZodEnum<{
+    local: "local";
+    npm: "npm";
+    "project-local": "project-local";
+  }>>;
+  collidesWith: z.ZodOptional<z.ZodEnum<{
+    local: "local";
+    npm: "npm";
+    "project-local": "project-local";
+  }>>;
+  collisionIgnoresSurface: z.ZodOptional<z.ZodBoolean>;
+  extensionManaged: z.ZodBoolean;
+  persistedEnabled: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+/** Inferred type for one catalog entry reported by `kernel:extension.catalog`. */
+type InstalledExtensionCatalogEntry = z.infer<typeof InstalledExtensionCatalogEntrySchema>;
+//#endregion
+export { ServiceInfoSchema as C, ServiceInfo as S, ComponentStateSchema as _, InstalledExtensionRecord as a, ExtensionWarningEntry as b, ExtensionSubjects as c, TransitionOutcome as d, TransitionOutcomeSchema as f, ComponentState as g, ComponentInfoSchema as h, InstalledExtensionOriginSchema as i, SetEnabledReason as l, ComponentInfo as m, InstalledExtensionCatalogEntrySchema as n, InstalledExtensionRecordSchema as o, ComponentIdentitySchema as p, InstalledExtensionOrigin as r, ExtensionNamespace as s, InstalledExtensionCatalogEntry as t, SetEnabledReasonSchema as u, ExtensionInfo as v, ExtensionWarningEntrySchema as x, ExtensionInfoSchema as y };