@makaio/framework 1.0.0-dev-1789609124644 → 1.0.0-dev-1790066089222

package/dist/index-CyEE1RI5.d.mts

@@ -0,0 +1,869 @@
+import { i as CliContribution } from "./types-Cuhnt15L.mjs";
+import { a as InstalledExtensionRecord, d as TransitionOutcome, l as SetEnabledReason, v as ExtensionInfo } from "./index-uk8icWON2.mjs";
+import { r as WindowRegistry } from "./window-registry-C3W2wtlX.mjs";
+import { z } from "zod";
+import { MakaioError } from "@makaio/framework/core";
+import { ExtensionContributionProcessor, ExtensionOperatorConfigEntry, ExtensionOperatorConfigSource, ExtensionService, ExtensionToken, MakaioExtension, NodeExtensionContext, StorageDialect, TrayManifest, VersionLiteral } from "@makaio/framework/contracts";
+import { IMakaioBus } from "@makaio/framework/bus";
+
+//#region packages/kernel/src/extension/types.d.ts
+/**
+ * Host-supplied reader for the extension packages installed on the machine
+ * running this coordinator.
+ *
+ * The coordinator only knows the packages it loaded, which is a strictly
+ * smaller set than what is installed: surface affinity, unmet requirements, or
+ * boot-time suppression all leave an installed package unloaded, and its
+ * enablement preference is still addressable. Discovering the rest means
+ * scanning the host's install tiers and importing extension code, neither of
+ * which belongs in the kernel — so the composition root supplies it here, the
+ * same way it supplies the durable enablement store's read/write callbacks.
+ *
+ * Called on demand (`kernel:extension.catalog`, and the validation
+ * `kernel:extension.setEnabled` performs for a name this coordinator never
+ * loaded), never during boot, and never on a hot path. Implementations are
+ * expected to be slow — they spawn imports — and must resolve rather than
+ * reject for an individual unreadable package, reporting it as
+ * `criticalityUnknown` instead.
+ * @returns Every installed executable extension package, one record per
+ *   executable package name, in discovery-tier priority order.
+ */
+type InstalledExtensionCatalogSource = () => Promise<readonly InstalledExtensionRecord[]>;
+/** Concrete Node runtime context supplied by the kernel coordinator. */
+type KernelExtensionContext = NodeExtensionContext<IMakaioBus>;
+/** Concrete executable extension shape loaded by the kernel coordinator. */
+type KernelMakaioExtension = MakaioExtension<KernelExtensionContext>;
+/** Awaited contribution processor registered with the {@link ExtensionCoordinator}. */
+type ContributionProcessor = ExtensionContributionProcessor<KernelExtensionContext>;
+/**
+ * Hosted runtime surface category used for extension/package gating.
+ *
+ * Represents the concrete surface a runtime IS -- `'any'` is intentionally
+ * absent because a runtime cannot BE `'any'`; it is always interactive or
+ * headless. Package manifests may declare `'any'` as their surface affinity,
+ * which the coordinator interprets as "load on all surfaces".
+ */
+type ExtensionRuntimeSurface = 'interactive' | 'headless';
+/**
+ * Host-advertised runtime capability fact.
+ */
+interface RuntimeCapability {
+  /** Stable capability token. */
+  readonly id: string;
+  /** Concrete capability contract version when the host exposes one. */
+  readonly version?: VersionLiteral;
+}
+/**
+ * Snapshot of the runtime environment provided by the host.
+ *
+ * The coordinator uses this to evaluate {@link RuntimeRequirement} gates on
+ * each extension before deciding whether to load it.
+ */
+interface RuntimeEnvironment {
+  /**
+   * Identifiers of the active host runtimes (e.g. `'node'`, `'electron'`).
+   *
+   * Extensions that declare `{ type: 'host', id: '...' }` requirements check
+   * against this set.
+   */
+  readonly hosts: ReadonlySet<string>;
+  /**
+   * Capability tokens advertised by the host (e.g. `'storage.drizzle'`).
+   *
+   * Extensions that declare `{ type: 'capability', id: '...' }` requirements
+   * check against this set. Versioned requirements additionally consult
+   * {@link RuntimeEnvironment.capabilityVersions}.
+   */
+  readonly capabilities: ReadonlySet<string>;
+  /**
+   * Concrete versions for host capabilities that expose a versioned contract.
+   *
+   * A capability requirement with a `version` range is satisfied only when the
+   * capability ID is present and this map contains a satisfying concrete version.
+   */
+  readonly capabilityVersions?: ReadonlyMap<string, VersionLiteral>;
+}
+/**
+ * Options for constructing an {@link ExtensionCoordinator}.
+ */
+interface ExtensionCoordinatorOptions {
+  /** Hosted surface category used to apply package gating. Defaults to `'headless'`. */
+  surface?: ExtensionRuntimeSurface;
+  /**
+   * Host launcher command embedded into client wiring installed from warning actions.
+   *
+   * Defaults to `'makaio'` for framework-only hosts. Hosts pass their
+   * own launcher policy through this seam so the runtime does not infer it
+   * from process entrypoints.
+   */
+  launcherCommand?: string;
+  /** Optional database instance for storage handler registration (opaque — cast to MakaioDatabase at call site). */
+  db?: unknown;
+  /**
+   * Node host fields for the context supplied to extension factories.
+   *
+   * Required when any loaded extension declares a `create` factory. When absent,
+   * extensions with `create` will fail to start.
+   *
+   * Omit `config`, `signal`, and `hasExtension` — those are coordinator-owned
+   * and assembled per extension at context-build time.
+   */
+  extensionContextBase?: Omit<KernelExtensionContext, 'bus' | 'identity' | 'getService' | 'dataDir' | 'config' | 'signal' | 'hasExtension'>;
+  /**
+   * Host-provided runtime environment snapshot used to evaluate extension
+   * {@link RuntimeRequirement} gates during {@link ExtensionCoordinator.load}.
+   *
+   * Extensions whose {@link MakaioExtension.requires} entries are not all
+   * satisfied by the supplied environment are excluded. Omit only in tests that
+   * intentionally bypass environment gating.
+   */
+  runtimeEnvironment?: RuntimeEnvironment;
+  /**
+   * Names of packages whose enablement is operator-managed.
+   *
+   * Scopes the coordinator's enablement machinery to the packages a
+   * descriptor actually declares: {@link ExtensionCoordinatorOptions.loadEnabled}
+   * is only consulted for a name in this set, `handleSetEnabled`
+   * (`kernel:extension.setEnabled`) refuses outright for any other name, and
+   * `ExtensionInfo.persistedEnabled` is `undefined` for it. Every name absent
+   * from this set boots unconditionally enabled — a framework package is not
+   * subject to operator enablement at all, so the enablement store's
+   * category defaults (and a hand-edited disable) can never skip it, and
+   * dependents cannot be excluded by a framework name looking "disabled".
+   *
+   * Omitted entirely: every loaded package is treated as managed, which
+   * preserves prior behavior for coordinators built without this option
+   * (including every existing test that constructs one without it).
+   */
+  extensionManagedNames?: ReadonlySet<string>;
+  /**
+   * Names of packages this host loads unconditionally as framework packages.
+   *
+   * These are the only names an extension package may legitimately register a
+   * second time: the host always loads the framework package, and a single
+   * extension registration under one of those names is the supported core
+   * override, which {@link ExtensionCoordinator.load} lets win the name. A
+   * collision under any other name is an extension identity collision with no
+   * legitimate winner and aborts `load()` — see `coalesceExtensionOverrides`.
+   *
+   * Omitted entirely: every name in the loaded set is treated as an extension
+   * identity, so any name collision aborts. A composition root that mixes
+   * framework packages into the same `load()` call must supply this set, or a
+   * legitimate core override is reported as a collision.
+   */
+  frameworkPackageNames?: ReadonlySet<string>;
+  /**
+   * Optional reader for the extension packages installed on this host.
+   *
+   * Backs `kernel:extension.catalog` and lets `kernel:extension.setEnabled`
+   * validate — and then persist — a preference for a name this coordinator
+   * never loaded. Without it, `catalog` reports `entries: null` and
+   * `setEnabled` refuses such a name outright (reason `'no-catalog'`) rather
+   * than writing a preference on the caller's word.
+   *
+   * See {@link InstalledExtensionCatalogSource} for the contract.
+   */
+  installedCatalog?: InstalledExtensionCatalogSource;
+  /**
+   * Optional callback to durably persist an enablement preference.
+   *
+   * Called by `handleSetEnabled` (the `kernel:extension.setEnabled` RPC
+   * handler) on every request it does not refuse outright — unconditionally,
+   * regardless of whether the preference appears unchanged, and regardless of
+   * this same coordinator's own {@link ExtensionCoordinatorOptions.loadEnabled}
+   * value. The composition root supplies this to bridge into a durable store
+   * (for example `ExtensionEnablementStore` from `@makaio/runtime-node`),
+   * which re-reads its backing file before writing so a concurrent hand-edit
+   * is never silently overwritten by a stale in-memory guess.
+   */
+  persistEnabled?: (name: string, enabled: boolean) => Promise<void>;
+  /**
+   * Optional callback to retrieve the persisted enablement preference.
+   *
+   * Called once per package during {@link ExtensionCoordinator.load}, to seed
+   * `entry.enabled` for this boot: returns `false` to skip the package at
+   * boot, `true` or `undefined` to start it normally. That boot-time read is
+   * a snapshot — nothing later re-derives `entry.enabled` from it, and
+   * `handleSetEnabled` must never use it (or `entry.enabled`) to decide
+   * whether a write is necessary — see {@link persistEnabled}. A hand-edit to
+   * the backing store between boots is exactly what this snapshot is meant to
+   * pick up on the *next* restart, not something a live `setEnabled` call
+   * reconciles against.
+   *
+   * `list()` and the singular `get` lookup (`kernel:extension.list` /
+   * `kernel:extension.get`) also call this — once per extension, per call —
+   * to populate `ExtensionInfo.persistedEnabled`. Unlike the boot-time read
+   * above, that call is live: a caller backed by `ExtensionEnablementStore`
+   * (`@makaio/runtime-node`) reflects every `persistEnabled` write this
+   * process has committed in-process since boot, because that store updates
+   * its in-memory set only after its own write lands (see that module). It
+   * does not reflect a concurrent hand-edit made by another process; the
+   * next boot's `load()` call is what picks that up.
+   */
+  loadEnabled?: (name: string) => boolean | undefined;
+  /**
+   * Optional callback to retrieve stored configuration for a package during
+   * startAll and enablePackage. Returns `undefined` when no stored config exists.
+   */
+  loadConfig?: (name: string) => Record<string, unknown> | undefined;
+  /**
+   * Optional operator-owned configuration layer, consulted at every config
+   * resolution point.
+   *
+   * Sits above both descriptor/host defaults and {@link ExtensionCoordinatorOptions.loadConfig},
+   * so an explicit operator decision is never silently overwritten by a write
+   * from the storage tier. An entry the source reports as unusable fails the
+   * affected extension when it activates, under the coordinator's existing
+   * criticality rules; extensions the source says nothing about are unaffected.
+   *
+   * When absent, config resolution behaves exactly as it does without an
+   * operator layer.
+   */
+  operatorConfig?: ExtensionOperatorConfigSource;
+  /**
+   * Optional callback invoked by {@link ExtensionCoordinator.startAll} to run
+   * database migrations declared by loaded packages before any services start.
+   *
+   * The coordinator collects all packages whose `StorageManifest.migrations`
+   * field is set and passes them as an array of
+   * `{ name, migrationsPath, migrationSourceId, migrationsPathByDialect? }`
+   * objects to this callback in topological (dependency) order. The callback is
+   * responsible for applying pending migrations — typically via Drizzle
+   * `migrate()` or the bundled `applyMigrations()` helper — using a tracking
+   * table keyed to the migration bundle identity so packages that share one
+   * folder share one ledger.
+   *
+   * When absent, declared migrations are silently skipped and storage tables
+   * that depend on them will not be created at runtime.
+   *
+   * The `migrationsPath` values are absolute discovery paths resolved by the
+   * coordinator from each package's `StorageManifest.migrations` field
+   * plus executable `storage.packageRoot` metadata when needed.
+   * `migrationSourceId` is the stable runtime identity used for bundled hosts;
+   * when a package does not declare one, it falls back to `migrationsPath`.
+   *
+   * When a package declares the object form of `StorageManifest.migrations`,
+   * the coordinator additionally passes `migrationsPathByDialect` — an
+   * absolute, containment-checked map of every declared per-dialect chain. The
+   * coordinator stays dialect-agnostic; the host runtime selects the active
+   * dialect's chain from this map and falls back to `migrationsPath` when the
+   * map has no entry for that dialect.
+   * @param sources - Migration sources in dependency order, each carrying the
+   *   package name, absolute migration folder path, stable source id, and an
+   *   optional per-dialect chain map.
+   * @returns A promise that resolves when all migrations have been applied.
+   */
+  runMigrations?: (sources: ReadonlyArray<{
+    name: string;
+    migrationsPath: string;
+    migrationSourceId: string;
+    migrationsPathByDialect?: Partial<Record<StorageDialect, string>>;
+  }>) => Promise<void>;
+}
+//#endregion
+//#region packages/kernel/src/extension/resolve-config.d.ts
+/** Constructor fields for an {@link ExtensionOperatorConfigError}. */
+interface ExtensionOperatorConfigErrorInput {
+  /** Extension whose configuration could not be resolved. */
+  readonly extensionName: string;
+  /** Opaque origin label copied from the operator entry. */
+  readonly source: string;
+  /**
+   * Human-readable description of what is wrong, already bounded and flattened,
+   * phrased to follow the extension and source prefix.
+   */
+  readonly summary: string;
+  /**
+   * Underlying error, preserved unbounded for callers that inspect it rather
+   * than print it.
+   */
+  readonly cause?: unknown;
+}
+/**
+ * Raised when an extension's operator-supplied configuration cannot be
+ * honoured, either because the operator entry itself is unusable or because the
+ * configuration it takes part in is rejected by the extension's config schema.
+ *
+ * Carries the extension name and the entry's `source` label so the operator
+ * can find the offending input. In `'activate'` mode it is thrown, and the
+ * coordinator routes it through the same criticality rules as any other
+ * activation failure: a non-critical extension fails alone, a `critical: true`
+ * extension aborts startup. In `'observe'` mode it is constructed but never
+ * thrown — only its message is used, as the text of a warning — because a
+ * caller that is not driving the lifecycle has no criticality rule to apply.
+ */
+declare class ExtensionOperatorConfigError extends MakaioError {
+  /** Name of the extension whose configuration could not be resolved. */
+  readonly extensionName: string;
+  /** Opaque origin label copied from the operator entry. */
+  readonly source: string;
+  /**
+   * @param input - Extension identity, origin label, summary, and optional cause.
+   */
+  constructor(input: ExtensionOperatorConfigErrorInput);
+}
+/**
+ * The result of a configuration resolution, together with how it was reached.
+ *
+ * The distinction matters to callers that report configuration back to a
+ * human: after a rejected merge, the returned object is the schema's own
+ * `.default()` values with every configuration layer discarded — including the
+ * operator's. Presenting those as the values an extension is running with
+ * would attribute schema defaults to the operator, and to a configuration the
+ * extension was never able to accept.
+ */
+interface ExtensionConfigResolution {
+  /**
+   * Parsed config object, or `undefined` when the extension declares no config
+   * schema or no parse produced a usable object.
+   */
+  readonly config: unknown;
+  /**
+   * `true` when the merged configuration was rejected by the schema and
+   * `config` holds the schema's defaults instead, so no configuration layer is
+   * reflected in it. `false` whenever `config` reflects the merged layers, and
+   * whenever there is nothing to reflect (no schema, or no usable fallback).
+   */
+  readonly usedSchemaDefaults: boolean;
+}
+//#endregion
+//#region packages/kernel/src/extension/extension-toggle.d.ts
+/**
+ * Result of {@link handleSetEnabled}.
+ *
+ * Carries both the collapsed `success` boolean (for callers that only need
+ * to know whether the request needs attention) and the full `outcome` (for
+ * callers — the `kernel:extension.setEnabled` RPC response and the CLI/UI
+ * surfaces that read it — that must tell a durable-but-deferred preference
+ * apart from an outright rejection instead of guessing from `success` alone).
+ */
+interface SetEnabledResult {
+  /** `true` when the preference already matches the runtime state; `false` otherwise. */
+  readonly success: boolean;
+  /** The transition outcome computed for this request. */
+  readonly outcome: TransitionOutcome;
+  /**
+   * Machine-readable detail for this outcome, when there is one to report —
+   * which refusal it was, or why a persisted preference is not in effect. See
+   * {@link SetEnabledReason}. Absent only for the plain `'applied'` case,
+   * where the loaded extension already matches the request and there is
+   * nothing further to explain.
+   */
+  readonly reason?: SetEnabledReason;
+}
+//#endregion
+//#region packages/kernel/src/extension/extension-coordinator.d.ts
+/**
+ * Manages optional extensions through a unified lifecycle with per-extension state
+ * machine, bus observability, and window/tray/CLI surface collection.
+ *
+ * Lifecycle flow for each extension:
+ * ```
+ * discovered -> initializing -> [create + init + contributions] -> active
+ *                            ↘ failed  (any step fails, contributions rolled back)
+ *                            ↘ skipped  (ServiceSkipError from create or init,
+ *                                        or loadEnabled returned false at boot)
+ * ```
+ *
+ * Every state transition emits `kernel:extension.stateChanged` on the bus.
+ * Non-critical failures are isolated so remaining extensions continue to start.
+ * Critical extension failures abort boot because the host declared them mandatory.
+ *
+ * Lifecycle transitions are serialized. Extension lifecycle callbacks must not
+ * await another coordinator lifecycle call, because it waits in the same lane.
+ *
+ * During {@link load}, window manifests are registered into
+ * {@link windowRegistry}, tray entries are collected into {@link trayEntries},
+ * CLI contributions are collected into {@link cliContributions}, and package
+ * namespaces are registered on the bus — but only for entries whose
+ * preference-enabled state survives the dependency closure computed by
+ * `closeEnabledExtensionEntries` (`extension-entry-closure.ts`), so an entry
+ * that can never reach `active` this process never registers surfaces a
+ * `cli.execute` or window-open call could otherwise dispatch into, and its
+ * namespace can never win a collision against an active entry's or a
+ * framework namespace of the same name. Static tray entries are bridged to
+ * the tray menu bus service after each extension starts so the tray service
+ * can be supplied by the same extension graph.
+ *
+ * During {@link startAll}, each extension's {@link MakaioExtension.create} factory
+ * is called with a `NodeExtensionContext`, followed by `service.init()`.
+ * Storage handlers (if any) are registered via
+ * `MakaioExtension.storage.registerHandlers` when a `db` instance is
+ * provided to the constructor.
+ */
+declare class ExtensionCoordinator {
+  private readonly bus;
+  private readonly surface;
+  private readonly db;
+  private readonly extensionContextBase;
+  private readonly runtimeEnvironment;
+  /**
+   * AbortController signalling graceful shutdown to all active packages.
+   *
+   * Aborted at the start of {@link shutdown} so packages receive the signal
+   * before their services are destroyed.
+   */
+  private readonly shutdownController;
+  /** Insertion-ordered map so iteration matches dependency sort order. */
+  private readonly entries;
+  private loadOrder;
+  private loaded;
+  private started;
+  private shutdownRequested;
+  private shutdownPromise;
+  /** FIFO lane for lifecycle transitions that mutate extension entries. */
+  private lifecycleTail;
+  private rpcCleanups;
+  private readonly contributionProcessors;
+  /**
+   * Transient map from composite key (`toastId:actionId`) to the corresponding
+   * {@link ExtensionWarningAction}. Populated during {@link emitWarningsForEntry}
+   * and cleared per package before that package's current warning set is
+   * recorded, then cleared globally on {@link shutdown}.
+   *
+   * This map is intentionally coordinator-owned because toast interactions
+   * arrive after warning emission and need a short-lived runtime lookup without
+   * exposing executable warning actions in the toast payload.
+   */
+  private readonly warningActionMap;
+  /** Window registry populated during {@link load}. */
+  readonly windowRegistry: WindowRegistry;
+  private readonly _trayEntries;
+  private readonly _cliContributions;
+  private readonly persistEnabled;
+  private readonly loadEnabled;
+  private readonly loadConfig;
+  private readonly operatorConfig;
+  private readonly runMigrations;
+  private readonly extensionManagedNames;
+  private readonly frameworkPackageNames;
+  private readonly installedCatalog;
+  /**
+   * @param bus - Bus instance for emitting lifecycle events and serving the list RPC.
+   * @param options - Coordinator configuration.
+   */
+  constructor(bus: IMakaioBus, options?: ExtensionCoordinatorOptions);
+  /**
+   * Tray manifest entries collected from packages during {@link load}.
+   * @returns Immutable snapshot of all collected tray entries.
+   */
+  get trayEntries(): ReadonlyArray<TrayManifest & {
+    readonly packageName: string;
+  }>;
+  /**
+   * CLI contributions collected from packages during {@link load}.
+   * @returns Immutable snapshot of all collected CLI contributions.
+   */
+  get cliContributions(): ReadonlyArray<CliContribution>;
+  /**
+   * Returns extensions that declare HTTP routes.
+   * Primarily retained for diagnostics and compatibility with callers that
+   * need a snapshot of loaded HTTP surfaces. Runtime route mounting is handled
+   * by contribution processors as extensions activate or stop.
+   * @returns Loaded extensions that have an `http` field defined.
+   */
+  extensionsWithHttp(): ReadonlyArray<{
+    http: {
+      prefix: string;
+      mount: (app: unknown) => void;
+    };
+  }>;
+  /**
+   * Load extension manifests and build the dependency graph.
+   *
+   * Sets all entries to the `discovered` state and registers the
+   * `kernel:extension.list`, `kernel:extension.get`, `kernel:extension.setEnabled`,
+   * `cli.listContributions`, and `cli.execute` RPC handlers.
+   *
+   * Extensions that do not match the coordinator's runtime surface or declared
+   * environment requirements are
+   * silently excluded. Dependents of excluded extensions are transitively pruned.
+   *
+   * Window manifests are registered into {@link windowRegistry}, tray entries
+   * are collected into {@link trayEntries}, CLI contributions are collected
+   * into {@link cliContributions}, and package bus namespaces are registered
+   * -- all before any services are started, and all gated by the same
+   * dependency closure (see the class-level doc comment above).
+   *
+   * Single-use: calling this method twice on the same instance throws.
+   *
+   * The retained names are returned because filtering happens here and nowhere
+   * else: a composition root that wants to diagnose what it handed in — an
+   * operator config file for an extension this surface excludes, for example —
+   * would otherwise have to restate the surface and environment rules and drift
+   * from them. They are a result of this call rather than an accessor, so there
+   * is no state in which they can be read as "nothing was retained" when in fact
+   * nothing has been loaded yet.
+   * @param packages - Extension manifests to register.
+   * @param configDefaults - Optional map of extension name to default config values
+   *   sourced from descriptor.json.
+   * @returns The packages actually registered, in load order: the input minus
+   *   the ones excluded by surface or environment filtering and their pruned
+   *   dependents, with one entry per name — for an accepted core override
+   *   (see {@link ExtensionCoordinatorOptions.frameworkPackageNames}), the
+   *   overriding registration rather than the framework package it replaced.
+   *   The manifests themselves rather than their names, because a caller
+   *   matching names back against its own input would re-admit exactly the
+   *   overridden registration this dropped.
+   * @throws Error if called more than once, if two registrations collide on a
+   *   name that is not an overridable framework package name, if a dependency
+   *   cycle is detected, or if dependency sorting fails.
+   */
+  load(packages: ReadonlyArray<KernelMakaioExtension>, configDefaults?: ReadonlyMap<string, Readonly<Record<string, unknown>>>): readonly KernelMakaioExtension[];
+  /**
+   * Register the `kernel:extension.*` and `cli.*` RPC handlers on the bus.
+   *
+   * Extracted out of {@link load} purely to stay within that method's line
+   * budget; it has no meaning independent of the single call site there.
+   */
+  private registerRpcHandlers;
+  /**
+   * Start all loaded packages in dependency order.
+   *
+   * For each package the state machine advances:
+   * `discovered -> initializing -> active | failed | skipped`
+   *
+   * Failures are isolated: a package that throws during `create` or `init` is
+   * set to `failed` and the error is captured, but remaining packages continue
+   * to start unless the package declares `critical: true`.
+   *
+   * Single-use: calling this method twice on the same instance throws.
+   * @throws Error if called more than once, before {@link load}, or when a
+   *   critical package fails.
+   */
+  startAll(): Promise<void>;
+  /** Run the admitted startup transition in the coordinator lifecycle lane. */
+  private startAllInLifecycleLane;
+  /**
+   * Shut down all active packages in reverse dependency order.
+   *
+   * Calls each package's service `destroy()` method (if any). A teardown
+   * failure does not stop remaining packages from shutting down, but it is
+   * reported: once every package has been stopped, all failures are thrown
+   * together so the caller can treat termination as unclean.
+   *
+   * Safe to call even if {@link startAll} was never called.
+   * @returns A promise that settles after every admitted transition and teardown complete.
+   * @throws An AggregateError when any package failed to shut down cleanly.
+   */
+  shutdown(): Promise<void>;
+  /** Run shutdown after every lifecycle transition admitted before shutdown. */
+  private shutdownInLifecycleLane;
+  /**
+   * Return the current state snapshot for all registered packages.
+   * @returns Array of {@link ExtensionInfo} objects reflecting current observable states.
+   */
+  list(): ExtensionInfo[];
+  /**
+   * Return the current state snapshot for a single named package.
+   *
+   * Backs the `kernel:extension.get` RPC (see `coordinator-rpc-handlers.ts`)
+   * so that handler does not need its own access to {@link loadEnabled} to
+   * populate `ExtensionInfo.persistedEnabled`.
+   * @param name - Extension name to look up.
+   * @returns The {@link ExtensionInfo} snapshot, or `null` when unknown.
+   */
+  getInfo(name: string): ExtensionInfo | null;
+  /**
+   * Retrieve the live service instance for a named extension.
+   * @param tokenOrName - Extension token or extension name string.
+   * @returns The active service instance, or `undefined`.
+   */
+  getExtensionService<TService = ExtensionService>(tokenOrName: string | ExtensionToken<TService>): TService | undefined;
+  /**
+   * Look up a loaded extension by name.
+   * @param name - Extension name.
+   * @returns The extension, or `undefined` if not loaded.
+   */
+  getExtension(name: string): KernelMakaioExtension | undefined;
+  /**
+   * Return the schema-parsed effective config for a loaded extension.
+   *
+   * Runs the same resolution path the kernel uses at activation, in `'observe'`
+   * mode, so every schema transform (e.g. `.trim()`) is reflected in the
+   * returned values. This is the correct source for building provenance
+   * snapshots — never the raw operator layer, which may not match what the
+   * extension actually received.
+   *
+   * Deliberately state-neutral. Resolution composes the configuration layers
+   * and nothing else: it needs no live service, no context, and no running
+   * lifecycle, so a disabled, stopped, failed, or not-yet-started extension
+   * resolves exactly like a running one. A settings surface is precisely where
+   * an extension gets toggled off, and it must not start reporting different
+   * values the moment it does.
+   * Reports how the configuration was reached, because the two outcomes are
+   * not interchangeable for a settings surface: when the merged configuration
+   * is rejected, resolution falls back to the schema's own defaults with every
+   * layer discarded, and reporting those as effective values would attribute
+   * schema defaults to whichever layer supplied them.
+   * @param name - Extension name.
+   * @returns The resolution, or `undefined` when no extension is loaded under
+   *   `name`. Its `config` is `undefined` when the extension declares no
+   *   `configSchema`, or when the merged configuration is rejected by the
+   *   schema and the schema-default fallback parse fails as well.
+   */
+  getResolvedConfig(name: string): ExtensionConfigResolution | undefined;
+  /**
+   * Collect provider definition IDs from extensions that can still provide them.
+   *
+   * Active entries are already visible through the contribution catalog.
+   * Enabled `discovered` and `initializing` entries are still eligible to
+   * activate later in the same boot or enablement pass, so adapters should
+   * defer for their providers. Disabled and terminal inactive entries are
+   * excluded so optional-provider adapters do not wait on providers that
+   * cannot become catalog-visible.
+   * @returns Set of provider definition IDs from active or activation-eligible extensions.
+   */
+  getLoadedProviderDefinitionIds(): ReadonlySet<string>;
+  /**
+   * Iterate all active extensions in dependency order with their contexts.
+   *
+   * Intended for host-owned integration code that needs a snapshot of active
+   * packages after the coordinator has completed startup.
+   *
+   * Configuration is resolved in observe mode, so a configuration that has since
+   * become invalid degrades that extension's `ctx.config` to schema defaults
+   * rather than throwing and abandoning the rest of the iteration.
+   * @param callback - Called once per active extension with its name, manifest,
+   *   and a per-extension `NodeExtensionContext`.
+   */
+  forEachActiveExtension(callback: (name: string, pkg: KernelMakaioExtension, ctx: KernelExtensionContext) => void): void;
+  /**
+   * Invoke a callback for a single active extension with its resolved context.
+   *
+   * Singular complement to {@link forEachActiveExtension} for targeted operations
+   * after an extension is re-enabled, and resolves configuration in the same
+   * non-throwing observe mode.
+   * No-ops when the extension is not found or not in `active` state.
+   * @param name - Name of the extension to target.
+   * @param callback - Called with the extension name, manifest, and a
+   *   per-extension `NodeExtensionContext` when the extension is active.
+   */
+  forExtension(name: string, callback: (name: string, pkg: KernelMakaioExtension, ctx: KernelExtensionContext) => void): void;
+  /**
+   * Register an awaited contribution processor.
+   *
+   * The processor's `processActivated` method is called
+   * (and awaited) each time an extension transitions to `active` — both during
+   * {@link startAll} and on a coordinator-internal restart via
+   * {@link applyExtensionTransition} (`true`).
+   *
+   * `processStopped` (when present) is called before
+   * the extension's service is destroyed during {@link shutdown} or a
+   * coordinator-internal restart via {@link applyExtensionTransition}
+   * (`false`).
+   *
+   * Processors run in registration order during activation and reverse
+   * registration order during deactivation. During activation, processor errors
+   * cause the extension to transition to `failed` with rollback of
+   * already-activated contributions. During deactivation, errors are caught and
+   * logged (best-effort).
+   * @param processor - Processor to register.
+   * @returns Cleanup function that removes the processor from the registry.
+   */
+  registerContributionProcessor(processor: ContributionProcessor): () => void;
+  /**
+   * Handle the `kernel:extension.setEnabled` RPC by durably recording the
+   * operator's enablement preference for an extension.
+   *
+   * This is the operator-preference seam, and it is **persist-only**: it
+   * never runs a live state-machine transition. It persists the requested
+   * preference (refusing to disable a `critical` extension, or one whose
+   * criticality could not be resolved, and throwing when this coordinator was
+   * constructed without a `persistEnabled` writer) and reports whether the
+   * process's current runtime state already matches it. See
+   * {@link handleSetEnabledImpl} for the full rationale — several package
+   * contributions are composed exactly once at boot and cannot be replayed
+   * for one package in isolation while the process keeps running.
+   * Coordinator-internal or product-internal callers that need to actually
+   * restart an already-started extension as part of their own mechanics
+   * should call {@link applyExtensionTransition} instead.
+   *
+   * Every request is validated against the host's installed-extension catalog
+   * — a name this coordinator never loaded as an operator-managed extension
+   * for its existence, and every name for whether more than one installed copy
+   * claims it. A second copy installed while this process runs never reaches
+   * `entries`, which still describes the single copy loaded at boot, so only
+   * the catalog can see that the next start will refuse the name. That read
+   * scans install tiers and imports extension code, so it happens here, before
+   * the request enters the lifecycle queue — holding the lifecycle lock across
+   * it would stall shutdown and every other transition behind an interactive
+   * request. Because it is awaited outside the queue, admission is decided
+   * after it rather than before (see {@link admitLifecycle}).
+   * @param name - Name of the extension to toggle.
+   * @param enabled - `true` to enable, `false` to disable.
+   * @returns A {@link SetEnabledResult}: `success` is `true` when the
+   *   preference already matches the runtime state and `false` when the
+   *   request was rejected or can only take effect on the next process
+   *   restart; `outcome` always carries the underlying {@link TransitionOutcome}
+   *   (`'applied'`, `'rejected'`, or `'restart-required'`) so callers can tell
+   *   those two `false` cases apart, and `reason` the detail behind it.
+   * @throws Error when this coordinator has no durable `persistEnabled`
+   *   writer, or when a framework package holds the requested name and this
+   *   coordinator has no installed-extension catalog.
+   */
+  handleSetEnabled(name: string, enabled: boolean): Promise<SetEnabledResult>;
+  /**
+   * Build the {@link CatalogHost} surface the installed-extension catalog
+   * assembly reads.
+   * @returns Host surface for the catalog helpers.
+   */
+  private createCatalogHost;
+  /**
+   * Enable or disable an already-boot-started extension without touching
+   * operator preference.
+   *
+   * This is the coordinator-internal lifecycle primitive: it does not persist
+   * anything and does not refuse a `critical` extension, but it does run the
+   * real state-machine transition (unlike {@link handleSetEnabled}, which is
+   * persist-only). Use it when a restart is part of the coordinator's own
+   * mechanics rather than an operator-originated request — for example a
+   * dependency registry that restarts a `critical` extension built to survive
+   * that gap (see the `automation-trigger` binding runtime package for the
+   * canonical example). It refuses to activate an extension boot skipped
+   * entirely (never started `create`/`init` this process) — see the
+   * boot-skip guard in `enableExtension` — because that entry's boot-only
+   * contribution surfaces were never composed in the first place.
+   * @param name - Name of the extension to toggle.
+   * @param enabled - `true` to enable, `false` to disable.
+   * @returns The transition outcome: `'applied'` or `'rejected'`.
+   */
+  applyExtensionTransition(name: string, enabled: boolean): Promise<Exclude<TransitionOutcome, 'restart-required'>>;
+  /**
+   * Build the {@link ToggleHost} surface shared by {@link handleSetEnabled} and
+   * {@link applyExtensionTransition}.
+   *
+   * Centralizing this avoids the two toggle entry points drifting out of sync
+   * on which coordinator state the toggle helpers can see.
+   * @returns Host surface for the toggle lifecycle helpers.
+   */
+  private createToggleHost;
+  /**
+   * Admit an operator-originated lifecycle transition, unless this coordinator
+   * is already terminal.
+   *
+   * The shutdown check and the enqueue happen in the same synchronous turn,
+   * and that is the entire contract: `shutdown()` marks the coordinator
+   * terminal and reserves the teardown slot in one turn too, so anything
+   * admitted here is admitted strictly before teardown. A caller that awaited
+   * between its own check and the enqueue — `handleSetEnabled` awaits the
+   * installed-extension catalog scan — would otherwise queue work behind
+   * teardown and still persist a preference after the runtime stopped.
+   * @param operation - Lifecycle transition to run exclusively.
+   * @param onShutdown - Result reported instead of running `operation` when the
+   *   coordinator is already terminal.
+   * @returns The operation's result, or `onShutdown`.
+   */
+  private admitLifecycle;
+  /**
+   * Schedule a lifecycle transition after every previously admitted transition.
+   *
+   * The tail recovers from failures so one rejected operation cannot strand
+   * later shutdown or toggle work behind a rejected promise.
+   * @param operation - Lifecycle transition to run exclusively.
+   * @returns The operation's result.
+   */
+  private enqueueLifecycle;
+  /**
+   * Create the shared extension-context helper host without exposing coordinator internals.
+   * @returns Helper host for config resolution and ExtensionContext construction.
+   */
+  private createExtensionContextHost;
+  /**
+   * Create the helper host for extension health checks.
+   * @returns Coordinator state required by the health runner.
+   */
+  private createExtensionHealthHost;
+  /**
+   * Check whether an extension has reached active state.
+   * @param name - Extension name to check.
+   * @returns `true` when the extension is active.
+   */
+  private hasActiveExtension;
+}
+//#endregion
+//#region packages/kernel/src/extension/extension-selection.d.ts
+/**
+ * Resolve name collisions across a registration list, allowing exactly one
+ * kind of collision: an extension package deliberately overriding a framework
+ * package that the host loads unconditionally.
+ *
+ * Extension package names are identities, not suggestions. Two extension
+ * packages registering under the same name have no legitimate winner — one
+ * would silently displace the other, including the case where the displacing
+ * registration is operator-disabled and therefore never starts at all. Upstream
+ * stages already guarantee unique extension identities: filesystem discovery
+ * rejects a same-tier descriptor-name collision outright and resolves a
+ * cross-tier one by tier precedence. Reaching this function with two extension
+ * registrations under one name therefore means a stage upstream of it stopped
+ * holding that guarantee, so it fails loudly rather than picking one.
+ *
+ * A framework package name is different: the host loads those packages
+ * unconditionally, and an extension registering under one of them is the
+ * supported core-override flow. `frameworkPackageNames` names exactly those,
+ * so the override wins the name (taking the overridden package's place at the
+ * end of the load order) while any further registration under the same name is
+ * again a collision with no legitimate winner.
+ * @param extensions - Eligible extensions in load priority order.
+ * @param frameworkPackageNames - Names the host loads unconditionally as
+ *   framework packages. A single extension registration under one of these is
+ *   a deliberate core override and wins the name. Omitted (or empty) means
+ *   every name in `extensions` is an extension identity, so any collision
+ *   throws.
+ * @returns Unique extensions, with an accepted core override in place of the
+ *   framework package it replaced.
+ * @throws Error when two registrations collide on a name that is not an
+ *   overridable framework package name, or when a framework package name is
+ *   claimed more than once by an override.
+ */
+declare function coalesceExtensionOverrides(extensions: ReadonlyArray<KernelMakaioExtension>, frameworkPackageNames?: ReadonlySet<string>): KernelMakaioExtension[];
+/**
+ * Filter extensions by runtime surface / environment requirements and prune dependents.
+ * @param extensions - Full extension set to filter.
+ * @param surface - Runtime surface to match.
+ * @param env - Host-provided runtime environment, or `undefined` to allow all.
+ * @returns Extensions eligible for loading in the current host environment.
+ */
+declare function filterEligibleExtensions(extensions: ReadonlyArray<KernelMakaioExtension>, surface: ExtensionRuntimeSurface, env: RuntimeEnvironment | undefined): KernelMakaioExtension[];
+//#endregion
+//#region packages/kernel/src/extension/installed-extension-catalog.d.ts
+/**
+ * Resolve the one installed record a name's enablement decision must answer
+ * against on a given runtime surface.
+ *
+ * A name can appear on more than one row, and picking the first match is only
+ * correct by accident. The catalog describes the *host* — every installed copy,
+ * on every surface — while an enablement decision is made for one concrete
+ * runtime. Three rules bridge that gap:
+ *
+ * 1. **A shadowed row is never the answer while a live one exists.** Discovery
+ *    drops a shadowed descriptor whole, so its row describes an install no
+ *    boot loads. When *every* row for the name is shadowed the name is still
+ *    installed and still addressable, so the shadowed rows are what is left to
+ *    answer from.
+ * 2. **Surface decides between the rest.** The coordinator filters packages by
+ *    surface *before* it resolves names, which is exactly why two copies
+ *    restricted to different surfaces are not reported as a collision (see
+ *    {@link InstalledExtensionRecord.collidesWith}). The same asymmetry has to
+ *    hold here: on a headless runtime the headless copy is the one whose
+ *    `critical` flag the next boot honours, and answering from the interactive
+ *    copy would accept or refuse a disable on the strength of a package this
+ *    surface never loads. A row restricted to *another* surface is kept only
+ *    when nothing else claims the name — installed-but-not-loadable-here is
+ *    still a real install with a real preference.
+ * 3. **The contest is re-judged for this surface whenever it can be.** The
+ *    catalog's own `collidesWith` answers "is this name contested
+ *    *somewhere*", which is a different question — see
+ *    {@link resolveContestOnThisSurface}. Carrying it through unchanged would
+ *    refuse a name this runtime resolves cleanly; trusting its absence would
+ *    accept one it cannot resolve at all; and discarding it where no second
+ *    claimant is visible would drop the only evidence there is.
+ * @param records - Installed records as reported by the catalog source.
+ * @param name - Executable package name being resolved.
+ * @param surface - Runtime surface the decision is being made for.
+ * @returns The record to validate against, with its enablement facts stated
+ *   for `surface`, or `undefined` when nothing installed claims the name.
+ */
+declare function resolveInstalledExtensionRecord(records: readonly InstalledExtensionRecord[], name: string, surface: ExtensionRuntimeSurface): InstalledExtensionRecord | undefined;
+//#endregion
+export { SetEnabledResult as a, ContributionProcessor as c, InstalledExtensionCatalogSource as d, KernelExtensionContext as f, RuntimeEnvironment as h, ExtensionCoordinator as i, ExtensionCoordinatorOptions as l, RuntimeCapability as m, coalesceExtensionOverrides as n, ExtensionConfigResolution as o, KernelMakaioExtension as p, filterEligibleExtensions as r, ExtensionOperatorConfigError as s, resolveInstalledExtensionRecord as t, ExtensionRuntimeSurface as u };