@sonicjs-cms/core 2.19.0 → 3.0.0-beta.3

package/dist/define-plugin-BzNHc1ZI.d.ts

@@ -0,0 +1,1321 @@
+import { i as HookSystemLike, m as TypedHooks, E as EmailProvider, s as EmailLogRow, t as EmailMessage, q as SendResult, f as HookEventName, l as TypedHookHandler } from './types-Dea1eNxU.js';
+import { Hono } from 'hono';
+import { d as HookSystem, b as HookHandler, k as PluginHook, v as PluginValidator$1, P as Plugin, u as PluginValidationResult, q as PluginRegistry, i as PluginConfig, t as PluginStatus, m as PluginManager$1, j as PluginContext } from './plugin-DDYetMF-.js';
+
+/**
+ * Plugin cron surface
+ *
+ * A plugin declares scheduled work as data:
+ *
+ *   crons: [{ schedule: '*\/15 * * * *', hookFamily: 'email-reconciliation' }]
+ *   async onCronTick(event, ctx) {
+ *     if (event.hookFamily !== 'email-reconciliation') return
+ *     ...
+ *   }
+ *
+ * Declaring a schedule does NOT by itself run anything (same as Payload's jobs
+ * queue): on Cloudflare Workers the execution mechanism is a Cron Trigger, which
+ * the runtime delivers to the Worker's `scheduled()` handler. `createScheduledHandler`
+ * builds that handler; it fans a fired trigger out to the plugins whose declared
+ * schedule matches, tagging each call with the matching `hookFamily` so a plugin
+ * with several crons can branch on it.
+ *
+ * The consumer must still register the cron expressions in `wrangler.toml`
+ * (`[triggers] crons = [...]`); the schedules declared here are the source of
+ * truth for which plugin handles which expression.
+ *
+ * Cron runs OUTSIDE the HTTP request context (no per-request `c.env`), which is
+ * exactly why services are reached through env-independent singletons.
+ */
+
+/** A scheduled-work declaration on a plugin. */
+interface CronDeclaration {
+    /** Cron expression, e.g. `'*\/15 * * * *'`. Must also be in wrangler.toml triggers. */
+    schedule: string;
+    /** Logical family the handler branches on (e.g. `'email-reconciliation'`). */
+    hookFamily: string;
+}
+/** The event passed to a plugin's `onCronTick`. */
+interface CronTickEvent {
+    /** The cron expression that fired. */
+    cron: string;
+    /** Epoch ms the trigger was scheduled for. */
+    scheduledTime: number;
+    /** The matching declaration's family, so a multi-cron plugin can branch. */
+    hookFamily: string;
+}
+/** Context handed to `onCronTick`. Mirrors the boot context; carries no request env. */
+interface CronContext {
+    /** The live hook system (so cron work can dispatch/observe hooks). */
+    hooks: HookSystemLike;
+    /** Runtime bindings supplied by the Worker's scheduled() invocation. */
+    env?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/**
+ * Structural contract this module needs from a plugin. Deliberately minimal (not
+ * the full `Plugin`) so the `src`/`dist` duplicate identities and user plugins all
+ * satisfy it without casts.
+ */
+interface CronablePlugin {
+    name?: string;
+    crons?: CronDeclaration[];
+    onCronTick?: (event: CronTickEvent, context: CronContext) => void | Promise<void>;
+}
+/** A flattened view of every declared cron across a set of plugins. */
+interface CollectedCron {
+    plugin: string;
+    schedule: string;
+    hookFamily: string;
+}
+/** Flatten every plugin's `crons[]` into one list (for diagnostics / wrangler sync). */
+declare function collectCrons(plugins: Array<CronablePlugin | undefined | null>): CollectedCron[];
+/** The set of distinct cron expressions declared across plugins. */
+declare function collectCronSchedules(plugins: Array<CronablePlugin | undefined | null>): string[];
+/** Outcome of a cron dispatch. */
+interface CronDispatchResult {
+    /** Plugins whose `onCronTick` ran successfully (one entry per matching declaration). */
+    invoked: Array<{
+        plugin: string;
+        hookFamily: string;
+    }>;
+    /** Per-plugin errors (dispatch never throws). */
+    errors: Array<{
+        plugin: string;
+        hookFamily: string;
+        error: unknown;
+    }>;
+    /** True if the fired cron matched no declared schedule. */
+    unmatched: boolean;
+}
+/**
+ * Dispatch one fired cron expression to the plugins that declared it.
+ *
+ * For each plugin whose `crons[]` contains a declaration with `schedule === cron`,
+ * its `onCronTick` is invoked once per matching declaration, with the event's
+ * `hookFamily` set to that declaration's family. Errors are isolated per plugin.
+ */
+declare function dispatchCronTick(plugins: Array<CronablePlugin | undefined | null>, cron: string, scheduledTime: number, context: CronContext): Promise<CronDispatchResult>;
+/** Minimal shape of a Cloudflare `ScheduledController`. */
+interface ScheduledControllerLike {
+    cron: string;
+    scheduledTime: number;
+}
+/** Minimal shape of a Cloudflare `ExecutionContext`. */
+interface ExecutionContextLike {
+    waitUntil?(promise: Promise<unknown>): void;
+}
+interface CreateScheduledHandlerOptions {
+    /** Plugins to consider (evaluated lazily at fire time). */
+    plugins: Array<CronablePlugin | undefined | null> | (() => Array<CronablePlugin | undefined | null>);
+    /** Provides the hook system (e.g. the singleton getter). */
+    getHooks: () => HookSystemLike;
+    /** Optional: when true, skip dispatch entirely (mirrors plugins.disableAll). */
+    disabled?: boolean;
+    /**
+     * Boot function from {@link SonicJSApp.boot}. Called before the first cron
+     * dispatch so a cron-first cold isolate (one that never handled an HTTP
+     * request) still has a wired hook bus and reachable email service.
+     * Without this, `getHookSystem()` may throw in cron handlers.
+     */
+    boot?: (env: Record<string, unknown>) => Promise<void>;
+}
+/**
+ * Build a Cloudflare `scheduled(controller, env, ctx)` handler that fans cron
+ * triggers out to plugins.
+ *
+ * Usage in a Worker entry:
+ *   export default {
+ *     fetch: app.fetch,
+ *     scheduled: createScheduledHandler({ plugins, getHooks: getHookSystem }),
+ *   }
+ */
+declare function createScheduledHandler(options: CreateScheduledHandlerOptions): (controller: ScheduledControllerLike, env: Record<string, unknown>, ctx?: ExecutionContextLike) => Promise<CronDispatchResult>;
+
+/**
+ * Hook-system singleton
+ *
+ * Gives env-independent access to the app's hook system. Code that runs outside
+ * the HTTP request context — most importantly scheduled (cron) handlers, which
+ * have no per-request `c.env` — needs a way to reach the hook system without
+ * threading it through every call. The app sets the singleton eagerly at
+ * construction; everything else reads it.
+ *
+ * Contract: `getHookSystem()` throws if read before the app has set one
+ * (throw-before-get), which surfaces wiring-order bugs loudly instead of
+ * silently no-oping. `setHookSystem()` is idempotent (last write wins) so that
+ * constructing multiple apps in one process — e.g. across tests — does not
+ * throw; call `resetHookSystem()` in test teardown for isolation.
+ */
+
+/** Set the process-wide hook system. Last write wins. */
+declare function setHookSystem(hookSystem: HookSystemLike): void;
+/**
+ * Get the process-wide hook system.
+ * @throws if no hook system has been set yet.
+ */
+declare function getHookSystem(): HookSystemLike;
+/** True if a hook system has been set. */
+declare function hasHookSystem(): boolean;
+/** Clear the singleton. Intended for test isolation. */
+declare function resetHookSystem(): void;
+/** Convenience: a typed facade over the current singleton hook system. */
+declare function getTypedHooks(): TypedHooks;
+
+/**
+ * Plugin route mounting primitive
+ *
+ * This is the shared, position-aware primitive that mounts plugin routes into
+ * the Hono app. It replaces the hand-wired, copy-pasted
+ * `if (plugin.routes) { for (...) app.route(...) }` blocks that previously lived
+ * in `app.ts`.
+ *
+ * ## Why synchronous
+ *
+ * Hono's `SmartRouter` builds (and then locks) its match tree on the first
+ * request. Calling `app.route()` after that throws:
+ *
+ *   `Error: Can not add a route since the matcher is already built`
+ *
+ * Therefore route mounting MUST happen synchronously at app-construction time,
+ * before any request is served. A plugin's imperative `register(app)` hook is
+ * held to the same contract: returning a Promise is a hard error
+ * (`PluginRegisterMustBeSyncError`) rather than a silent hang. Asynchronous,
+ * env-dependent work (hook subscriptions, services, crons) belongs in a later
+ * lazy "wire" phase — not here.
+ *
+ * ## Position-awareness
+ *
+ * Plugin routes must be mounted BEFORE the bare `/admin` catch-all so that a
+ * plugin's own `/admin/<x>` pages are not shadowed. Callers are responsible for
+ * invoking `registerPluginRoutes()` at the correct position in `app.ts`; this
+ * module just performs the mounting deterministically.
+ */
+
+/**
+ * Minimal structural contract this module needs to mount a plugin.
+ *
+ * Deliberately NOT the full `Plugin` interface: the core plugins are typed
+ * against the built `@sonicjs-cms/core` `dist` declarations, while this file
+ * lives in `src`, and TypeScript treats those two `Plugin` types as distinct
+ * nominal identities. Accepting a structural subset lets both the `src` and
+ * `dist` `Plugin` shapes (and user-supplied plugins) be mounted without casts,
+ * and keeps `mount.ts` honest about what it actually reads.
+ */
+interface MountableRoute {
+    path: string;
+    handler: unknown;
+    priority?: number;
+}
+interface MountablePlugin {
+    /** Stable unique id (used by topo-sort). Falls back to `name`. */
+    id?: string;
+    name?: string;
+    /** IDs of plugins that must be mounted before this one. */
+    dependencies?: string[];
+    routes?: MountableRoute[];
+    /** Synchronous imperative route registration. A Promise return is rejected. */
+    register?: (app: any) => unknown;
+}
+/**
+ * Thrown when a plugin's `register(app)` hook returns a Promise.
+ *
+ * `register()` runs synchronously at construction time (see module docs). Move
+ * any async work to a lifecycle hook (`install`/`activate`) or the async wiring
+ * phase instead.
+ */
+declare class PluginRegisterMustBeSyncError extends Error {
+    constructor(pluginName: string);
+}
+/** A single mounted route, for diagnostics/introspection. */
+interface MountedRoute {
+    plugin: string;
+    path: string;
+}
+/** Outcome of a mount pass. */
+interface MountResult {
+    /** Routes successfully mounted, in mount order. */
+    mounted: MountedRoute[];
+    /** Plugins (or routes) skipped, with a human-readable reason. */
+    skipped: Array<{
+        plugin: string;
+        reason: string;
+    }>;
+}
+type AnyHono = Hono<any, any, any>;
+/**
+ * Mount a single plugin's routes into `app`.
+ *
+ * Applies, in order:
+ *  1. The plugin's declarative `routes[]` (sorted by priority), and
+ *  2. The plugin's imperative `register(app)` hook, if present (sync-guarded).
+ *
+ * @param app    Host Hono app (mount BEFORE the `/admin` catch-all).
+ * @param plugin Plugin to mount.
+ * @param result Optional accumulator for diagnostics.
+ */
+declare function mountPlugin(app: AnyHono, plugin: MountablePlugin, result?: MountResult): void;
+/** Options for {@link registerPluginRoutes}. */
+interface RegisterPluginRoutesOptions {
+    /**
+     * Label used in dev warnings (e.g. `'core'` or `'user'`). Purely cosmetic.
+     */
+    source?: string;
+    /**
+     * When true, log a warning if two plugins mount the exact same route path
+     * (later registration is shadowed by Hono's first-match semantics). Defaults
+     * to true in non-production.
+     */
+    warnOnDuplicatePath?: boolean;
+    /**
+     * When true, sort plugins by their `dependencies` field before mounting
+     * (dependency-first order). Defaults to true.
+     */
+    sortByDependencies?: boolean;
+    /**
+     * Forwarded to `topoSort` — unknown dependency id throws when true, warns
+     * when false (default).
+     */
+    strict?: boolean;
+}
+/**
+ * Mount a list of plugins into `app`, in array order.
+ *
+ * This is the generic replacement for the hand-wired plugin blocks. Plugins are
+ * mounted in the order given (the caller decides ordering — typically core
+ * plugins first, then user `plugins.register` plugins), each before the bare
+ * `/admin` catch-all.
+ *
+ * Invalid entries are skipped (recorded in the result) rather than throwing, so
+ * one malformed plugin can't take down the whole app. The one hard error is a
+ * plugin whose `register()` is asynchronous — that is a contract violation that
+ * must surface loudly.
+ *
+ * @returns A {@link MountResult} describing what was mounted/skipped.
+ */
+declare function registerPluginRoutes(app: AnyHono, plugins: Array<MountablePlugin | undefined | null>, options?: RegisterPluginRoutesOptions): MountResult;
+
+/**
+ * Plugin wiring phase (the async half of two-phase boot)
+ *
+ * Route mounting is synchronous and happens at construction (see `mount.ts`).
+ * Everything that needs the runtime environment — hook subscriptions and the
+ * `onBoot` lifecycle — happens here, lazily, on the first request, after every
+ * plugin has registered. Splitting the two avoids Hono's "matcher already built"
+ * lock (routes must mount before the first request; env-dependent wiring can
+ * only run once a request supplies `c.env`).
+ *
+ * This module is the wiring mechanism. Where/when it is invoked (a once-guarded
+ * first-request step) is the caller's concern; `createPluginWirer()` provides
+ * the once-guard.
+ */
+
+/** A hook subscription declared by a plugin (the legacy `hooks[]` shape). */
+interface WirableHook {
+    name: string;
+    handler: (data: any, context: any) => any;
+    priority?: number;
+}
+/**
+ * Structural contract this module needs from a plugin. Deliberately minimal (and
+ * not the full `Plugin` interface) so the `src`/`dist` duplicate `Plugin`
+ * identities and user-supplied plugins all satisfy it without casts.
+ */
+interface WirablePlugin {
+    /** Stable unique id (used by topo-sort). Falls back to `name`. */
+    id?: string;
+    name?: string;
+    /** IDs of plugins that must be wired before this one. */
+    dependencies?: string[];
+    /**
+     * When true, the plugin is inserted as 'active' on first install.
+     * Subsequent boots leave the admin-managed status untouched (the ON CONFLICT
+     * clause does not update `status`), so admins can still deactivate it.
+     */
+    defaultActive?: boolean;
+    /**
+     * Capabilities declared by the plugin. When present (even as an empty array),
+     * the wire phase enforces that each declarative hook subscription is covered by
+     * a matching capability in {@link HOOK_CAPABILITY_MAP}. Absent on old-style
+     * `PluginBuilder` plugins — the gate is skipped for backwards compatibility.
+     */
+    capabilities?: readonly string[];
+    hooks?: WirableHook[];
+    /**
+     * Async lifecycle hook run once, after all plugins have registered and their
+     * hooks are subscribed. The place for env-dependent setup (services, seeding,
+     * cron registration). Errors are isolated per-plugin.
+     */
+    onBoot?: (context: PluginBootContext) => void | Promise<void>;
+}
+/** Options forwarded to {@link wireRegisteredPlugins}. */
+interface WireOptions {
+    /**
+     * Strict mode: capability violations are captured as errors in `WireResult`
+     * (and the hook is skipped) instead of only logging a warning.
+     * Also makes unknown dependency ids hard errors instead of warnings.
+     * Enable in CI or development; leave off in production for resilience.
+     */
+    strict?: boolean;
+    /**
+     * When false, skip dependency-aware ordering. Defaults to true (plugins with
+     * `dependencies` are wired after their declared dependencies).
+     */
+    sortByDependencies?: boolean;
+}
+/** Context handed to `onBoot`. Kept loose; concrete bindings are filled by the host. */
+interface PluginBootContext {
+    /** The live hook system (already carrying every plugin's subscriptions). */
+    hooks: HookSystemLike;
+    /** Runtime bindings, when available. */
+    env?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** Outcome of a wiring pass. */
+interface WireResult {
+    /** Total hook subscriptions registered. */
+    subscribed: number;
+    /** Names of plugins whose `onBoot` completed successfully. */
+    booted: string[];
+    /** Per-plugin errors (wiring never throws; one bad plugin can't break boot). */
+    errors: Array<{
+        plugin: string;
+        phase: 'subscribe' | 'onBoot';
+        error: unknown;
+    }>;
+}
+/**
+ * Subscribe every plugin's declarative `hooks[]` to the live hook system, then
+ * run each plugin's `onBoot`, in array order.
+ *
+ * Subscriptions happen for ALL plugins first, so that one plugin's `onBoot` can
+ * rely on another plugin's hooks already being registered. Per-plugin errors are
+ * captured in the result rather than thrown.
+ */
+declare function wireRegisteredPlugins(plugins: Array<WirablePlugin | undefined | null>, context: PluginBootContext, options?: WireOptions): Promise<WireResult>;
+/**
+ * Wrap {@link wireRegisteredPlugins} in a once-guard.
+ *
+ * The returned function runs the wiring at most once per process: the first call
+ * starts it and caches the promise; every later call returns that same promise.
+ * This is the first-request trigger — many concurrent first requests all await
+ * one wiring pass.
+ *
+ * @param plugins     Plugins to wire (evaluated lazily at first call).
+ * @param ctxFactory  Builds the boot context at first-call time (so it can read
+ *                    per-request env).
+ */
+declare function createPluginWirer(plugins: Array<WirablePlugin | undefined | null> | (() => Array<WirablePlugin | undefined | null>), ctxFactory: () => PluginBootContext): () => Promise<WireResult>;
+
+/**
+ * Plugin admin-sidebar menu registry.
+ *
+ * Plugins declare `menu: PluginMenuEntry[]` on definePlugin. registerPlugins
+ * collects every entry into this module singleton; the admin layout reads via
+ * `resolvePluginMenuItems(user)` to render the sidebar.
+ *
+ * Phase 1 — strings + paths only. No custom React/HTMX components in menu
+ * entries (icons are name strings looked up by the sidebar's icon map).
+ */
+interface PluginMenuEntry {
+    /** Display label. */
+    label: string;
+    /** Admin URL the entry navigates to (e.g. `/admin/email`). */
+    path: string;
+    /** Icon name from the admin icon map. Default: `puzzle-piece`. */
+    icon?: string;
+    /** Sort key (ASC). Default 100. */
+    order?: number;
+    /** Required permission slugs; if any matches the user's permissions, the entry is shown. */
+    permissions?: readonly string[];
+}
+/**
+ * Resolved entry — guaranteed `icon` + `order`, ready to render. Same shape
+ * the catalyst sidebar consumes via `dynamicMenuItems`. `icon` is the rendered
+ * SVG HTML string (resolved via {@link MENU_ICON_MAP} when the entry supplied
+ * a name; passed through verbatim when the entry supplied raw SVG/HTML).
+ */
+interface ResolvedPluginMenuEntry {
+    label: string;
+    path: string;
+    icon: string;
+    order: number;
+}
+declare function setPluginMenu(items: readonly PluginMenuEntry[]): void;
+declare function getPluginMenu(): readonly PluginMenuEntry[];
+declare function resetPluginMenu(): void;
+/**
+ * Filter entries by user permissions, sort by `order` ASC, project to render-ready
+ * shape with default icon. Pure function — same inputs, same output.
+ *
+ * Permission semantics: an entry with no `permissions` is always visible. An entry
+ * with `permissions: ['x','y']` is visible if the user has ANY of `x` or `y`.
+ * Users with `role: 'admin'` bypass all permission checks (admins see everything).
+ */
+declare function resolvePluginMenuItems(user?: {
+    permissions?: readonly string[];
+    role?: string;
+}): ResolvedPluginMenuEntry[];
+
+/**
+ * Schema-driven plugin settings.
+ *
+ * Plugins declare `configSchema: { key: ConfigSchemaField }` on definePlugin.
+ * The host renders the admin settings UI from the schema, parses FormData back
+ * into typed values, and exposes the resulting record via `ctx.settings.load()`.
+ *
+ * Field kinds: 'string' | 'number' | 'boolean' | 'select'. New kinds get added
+ * here once and every consumer picks them up.
+ *
+ * Phase 1 — settings UI only. The renderer emits plain HTML strings designed to
+ * compose into the existing admin layout (no client-side JS). FormData parsing
+ * coalesces unchecked-checkbox omission into `false` (the only browser quirk
+ * the renderer must account for).
+ */
+interface BaseField {
+    label: string;
+    description?: string;
+    required?: boolean;
+}
+interface StringField extends BaseField {
+    type: 'string';
+    default?: string;
+    format?: 'email' | 'url' | 'password';
+    /** Render as `<input type="password">`. Implied when `format === 'password'`. */
+    sensitive?: boolean;
+    placeholder?: string;
+    minLength?: number;
+    maxLength?: number;
+}
+interface NumberField extends BaseField {
+    type: 'number';
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+}
+interface BooleanField extends BaseField {
+    type: 'boolean';
+    default?: boolean;
+}
+interface SelectField extends BaseField {
+    type: 'select';
+    default?: string;
+    /** Either `['us','eu']` shorthand or `[{ value, label }]` for distinct display strings. */
+    options: readonly string[] | readonly {
+        value: string;
+        label: string;
+    }[];
+}
+type ConfigSchemaField = StringField | NumberField | BooleanField | SelectField;
+type ConfigSchema = Record<string, ConfigSchemaField>;
+/** Parsed shape — typed record inferred from the schema. */
+type SettingsFor<S extends ConfigSchema> = {
+    [K in keyof S]: S[K] extends StringField ? string : S[K] extends NumberField ? number : S[K] extends BooleanField ? boolean : S[K] extends SelectField ? string : never;
+};
+interface ParsedField {
+    key: string;
+    field: ConfigSchemaField;
+}
+/** Stable, ordered field list (preserves declaration order). */
+declare function parseConfigSchema(schema: ConfigSchema): ParsedField[];
+/**
+ * Render all fields as HTML controls. Output is a sequence of `<div class="field">…</div>`
+ * blocks designed to drop into the admin form template (no surrounding `<form>` or
+ * submit button — those belong to the page that calls this).
+ */
+declare function renderSchemaFields(schema: ConfigSchema, currentValues?: Record<string, unknown>): string;
+/**
+ * Coerce FormData entries into typed settings per the schema. Notably:
+ * - Unchecked checkboxes are omitted by the browser; we coalesce to `false`.
+ * - Numbers parse via `Number()` and fall back to the field's default if invalid.
+ * - Strings preserve empty string (NOT default) so an admin can intentionally clear.
+ */
+declare function parseFormDataToSettings(schema: ConfigSchema, form: FormData): Record<string, unknown>;
+/** Fill missing keys with field defaults. Existing keys (incl. `false`/`0`/'') win. */
+declare function applySchemaDefaults<S extends ConfigSchema>(schema: S, stored: Record<string, unknown>): Record<string, unknown>;
+
+/**
+ * registerPlugins — single chokepoint for plugin registration.
+ *
+ * Replaces the historical pattern of calling `registerPluginRoutes` + scheduling
+ * `wireRegisteredPlugins` + manually wiring `addMenuItem` calls + per-plugin
+ * settings-route handlers.
+ *
+ * Authors write:
+ *   const myPlugin = definePlugin({ id, version, capabilities, register, hooks, menu, configSchema, ... })
+ *
+ * Hosts call:
+ *   const reg = registerPlugins(app, [pluginA, pluginB], { hookSystem, env, ... })
+ *   // ...
+ *   await reg.boot(env)   // first-request lazy wire
+ *
+ * What this fn does, in order:
+ *   1. Validate each plugin (id, semver, dep references) — throws on hard errors
+ *   2. Topologically order by `dependencies`
+ *   3. MOUNT pass — invoke `registerPluginRoutes()` (sync, routes only)
+ *   4. Collect declarative `menu[]` entries → setPluginMenu (overwrites prior)
+ *   5. Collect declarative `crons[]` for the host scheduled() handler
+ *   6. Return a registry + a one-shot `boot(env)` that lazily runs the WIRE pass
+ *      (subscribe hooks + run onBoot + DB-reflect) on first request
+ *
+ * The mount/wire split is preserved (Hono's router locks after first request, so
+ * routes MUST mount synchronously at construction; env-dependent setup is lazy).
+ * That split is now an implementation detail — authors see ONE function.
+ */
+
+type RegisterPluginsErrorReason = 'invalid_id' | 'invalid_semver' | 'duplicate_id' | 'register_returned_promise';
+declare class RegisterPluginsError extends Error {
+    readonly reason: RegisterPluginsErrorReason;
+    readonly details: Readonly<Record<string, unknown>>;
+    constructor(reason: RegisterPluginsErrorReason, details: Readonly<Record<string, unknown>>);
+}
+/**
+ * Structural contract: the union of MountablePlugin + WirablePlugin + the
+ * declarative admin surface. Plugins built via `definePlugin()` satisfy this
+ * automatically; hand-rolled objects need at minimum `id`, `version`.
+ */
+interface RegisterablePlugin extends MountablePlugin, WirablePlugin {
+    id: string;
+    version: string;
+    displayName?: string;
+    sonicjsVersionRange?: string;
+    menu?: PluginMenuEntry[];
+    crons?: CronDeclaration[];
+    /** Schema-driven settings — the admin route reads this via getPluginDefinition(id). */
+    configSchema?: ConfigSchema;
+}
+interface RegisterPluginsHostContext {
+    /** Hook system the wire phase subscribes to. */
+    hookSystem: PluginBootContext['hooks'];
+    /** Runtime bindings (env.DB, env.KV, env.R2, etc.). Used by the wire phase. */
+    env?: Record<string, unknown>;
+    /** Forwarded to the mount pass as the `source` label in dev warnings. */
+    source?: string;
+    /** Strict-mode: cycle / unknown-dep / capability errors throw instead of warn. */
+    strict?: boolean;
+    /** Forwarded to registerPluginRoutes. */
+    mountOptions?: Omit<RegisterPluginRoutesOptions, 'source' | 'strict'>;
+}
+interface RegistryEntry {
+    id: string;
+    displayName: string;
+    version: string;
+    capabilities: readonly string[];
+}
+interface PluginsRegistry {
+    /** Plugins indexed by id, in topo-sorted order. */
+    readonly byId: ReadonlyMap<string, RegistryEntry>;
+    /** Plugin ids in registration order (post topo-sort). */
+    readonly order: readonly string[];
+    /** Aggregated menu entries (also pushed to the menu singleton). */
+    readonly menu: readonly PluginMenuEntry[];
+    /** Aggregated cron declarations. */
+    readonly crons: readonly CronDeclaration[];
+    /** Aggregated cron schedule expressions (deduped) — useful for wrangler.toml codegen. */
+    readonly cronSchedules: readonly string[];
+    /** Mount-pass diagnostics. */
+    readonly mountResult: MountResult;
+    /**
+     * Lazy wire pass — call from the first-request middleware. Idempotent
+     * (subsequent calls return the cached result of the first run).
+     */
+    boot(env?: Record<string, unknown>): Promise<WireResult>;
+}
+declare function registerPlugins(app: Hono<any, any, any>, plugins: ReadonlyArray<RegisterablePlugin | undefined | null>, host: RegisterPluginsHostContext): PluginsRegistry;
+
+/**
+ * Hook System Implementation
+ *
+ * Provides event-driven extensibility for plugins
+ */
+
+declare class HookSystemImpl implements HookSystem {
+    private hooks;
+    private executing;
+    /**
+     * Register a hook handler
+     */
+    register(hookName: string, handler: HookHandler, priority?: number): void;
+    /**
+     * Execute all handlers for a hook
+     */
+    execute(hookName: string, data: any, context?: any): Promise<any>;
+    /**
+     * Remove a hook handler
+     */
+    unregister(hookName: string, handler: HookHandler): void;
+    /**
+     * Get all registered hooks for a name
+     */
+    getHooks(hookName: string): PluginHook[];
+    /**
+     * Get all registered hook names
+     */
+    getHookNames(): string[];
+    /**
+     * Get hook statistics
+     */
+    getStats(): {
+        hookName: string;
+        handlerCount: number;
+    }[];
+    /**
+     * Clear all hooks (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Create a scoped hook system for a plugin
+     */
+    createScope(_pluginName: string): ScopedHookSystem;
+}
+/**
+ * Scoped hook system for individual plugins
+ */
+declare class ScopedHookSystem {
+    private parent;
+    private registeredHooks;
+    constructor(parent: HookSystemImpl);
+    /**
+     * Register a hook (scoped to this plugin)
+     */
+    register(hookName: string, handler: HookHandler, priority?: number): void;
+    /**
+     * Execute a hook
+     */
+    execute(hookName: string, data: any, context?: any): Promise<any>;
+    /**
+     * Unregister a specific hook
+     */
+    unregister(hookName: string, handler: HookHandler): void;
+    /**
+     * Unregister all hooks for this plugin
+     */
+    unregisterAll(): void;
+    /**
+     * Get hooks registered by this plugin
+     */
+    getRegisteredHooks(): {
+        hookName: string;
+        handler: HookHandler;
+    }[];
+}
+/**
+ * Hook utilities
+ */
+declare class HookUtils {
+    /**
+     * Create a hook name with namespace
+     */
+    static createHookName(namespace: string, event: string): string;
+    /**
+     * Parse a hook name to extract namespace and event
+     */
+    static parseHookName(hookName: string): {
+        namespace: string;
+        event: string;
+    };
+    /**
+     * Create a middleware that executes hooks
+     */
+    static createHookMiddleware(hookSystem: HookSystem, beforeHook?: string, afterHook?: string): (c: any, next: any) => Promise<void>;
+    /**
+     * Create a debounced hook handler
+     */
+    static debounce(handler: HookHandler, delay: number): HookHandler;
+    /**
+     * Create a throttled hook handler
+     */
+    static throttle(handler: HookHandler, limit: number): HookHandler;
+}
+
+/**
+ * Plugin Validator
+ *
+ * Validates plugin definitions, dependencies, and compatibility
+ */
+
+declare class PluginValidator implements PluginValidator$1 {
+    private static readonly RESERVED_NAMES;
+    private static readonly RESERVED_PATHS;
+    /**
+     * Validate plugin definition
+     */
+    validate(plugin: Plugin): PluginValidationResult;
+    /**
+     * Validate plugin dependencies
+     */
+    validateDependencies(plugin: Plugin, registry: PluginRegistry): PluginValidationResult;
+    /**
+     * Validate plugin compatibility with SonicJS version
+     */
+    validateCompatibility(plugin: Plugin, sonicVersion: string): PluginValidationResult;
+    /**
+     * Check if two version ranges are compatible
+     */
+    private isCompatible;
+    /**
+     * Validate plugin security constraints
+     */
+    validateSecurity(plugin: Plugin): PluginValidationResult;
+}
+
+/**
+ * Plugin Registry Implementation
+ *
+ * Manages plugin registration, activation, and lifecycle
+ */
+
+declare class PluginRegistryImpl implements PluginRegistry {
+    private plugins;
+    private configs;
+    private statuses;
+    private validator;
+    constructor(validator?: PluginValidator);
+    /**
+     * Get plugin by name
+     */
+    get(name: string): Plugin | undefined;
+    /**
+     * Get all registered plugins
+     */
+    getAll(): Plugin[];
+    /**
+     * Get active plugins
+     */
+    getActive(): Plugin[];
+    /**
+     * Register a plugin
+     */
+    register(plugin: Plugin): Promise<void>;
+    /**
+     * Unregister a plugin
+     */
+    unregister(name: string): Promise<void>;
+    /**
+     * Check if plugin is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Activate a plugin
+     */
+    activate(name: string): Promise<void>;
+    /**
+     * Deactivate a plugin
+     */
+    deactivate(name: string): Promise<void>;
+    /**
+     * Get plugin configuration
+     */
+    getConfig(name: string): PluginConfig | undefined;
+    /**
+     * Set plugin configuration
+     */
+    setConfig(name: string, config: PluginConfig): void;
+    /**
+     * Get plugin status
+     */
+    getStatus(name: string): PluginStatus | undefined;
+    /**
+     * Get all plugin statuses
+     */
+    getAllStatuses(): Map<string, PluginStatus>;
+    /**
+     * Update plugin status
+     */
+    private updateStatus;
+    /**
+     * Get plugins that depend on the specified plugin
+     */
+    private getDependents;
+    /**
+     * Get dependency graph
+     */
+    getDependencyGraph(): Map<string, string[]>;
+    /**
+     * Resolve plugin load order based on dependencies
+     */
+    resolveLoadOrder(): string[];
+    /**
+     * Export plugin configuration
+     */
+    exportConfig(): {
+        plugins: PluginConfig[];
+    };
+    /**
+     * Import plugin configuration
+     */
+    importConfig(config: {
+        plugins: PluginConfig[];
+    }): void;
+    /**
+     * Clear all plugins (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Get registry statistics
+     */
+    getStats(): {
+        total: number;
+        active: number;
+        inactive: number;
+        withErrors: number;
+    };
+}
+
+/**
+ * Plugin Manager
+ *
+ * Central orchestrator for the plugin system
+ */
+
+declare class PluginManager implements PluginManager$1 {
+    readonly registry: PluginRegistry;
+    readonly hooks: HookSystem;
+    private validator;
+    private context?;
+    private scopedHooks;
+    private pluginRoutes;
+    constructor();
+    /**
+     * Initialize plugin system
+     */
+    initialize(context: PluginContext): Promise<void>;
+    /**
+     * Load plugins from configuration
+     */
+    loadPlugins(configs: PluginConfig[]): Promise<void>;
+    /**
+     * Install a plugin
+     */
+    install(plugin: Plugin, config?: PluginConfig): Promise<void>;
+    /**
+     * Uninstall a plugin
+     */
+    uninstall(name: string): Promise<void>;
+    /**
+     * Get plugin status
+     */
+    getStatus(name: string): PluginStatus;
+    /**
+     * Get all plugin statuses
+     */
+    getAllStatuses(): PluginStatus[];
+    /**
+     * Register plugin extensions (routes, middleware, etc.)
+     */
+    private registerPluginExtensions;
+    /**
+     * Unregister plugin extensions
+     */
+    private unregisterPluginExtensions;
+    /**
+     * Update plugin status
+     */
+    private updatePluginStatus;
+    /**
+     * Create a logger for a plugin
+     */
+    private createLogger;
+    /**
+     * Get plugin routes for mounting in main app
+     */
+    getPluginRoutes(): Map<string, Hono>;
+    /**
+     * Get plugin middleware for main app
+     */
+    getPluginMiddleware(): Array<{
+        name: string;
+        handler: any;
+        priority: number;
+        global: boolean;
+    }>;
+    /**
+     * Execute shutdown procedures
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Get plugin system statistics
+     */
+    getStats(): {
+        registry: ReturnType<PluginRegistryImpl['getStats']>;
+        hooks: Array<{
+            hookName: string;
+            handlerCount: number;
+        }>;
+        routes: number;
+        middleware: number;
+    };
+}
+
+/**
+ * Minimal structural D1 surface needed for logging. Avoids importing the full
+ * `D1Database` type and keeps the service trivially fakeable in tests.
+ */
+interface EmailLogDb {
+    prepare(query: string): {
+        bind(...values: unknown[]): {
+            run(): Promise<unknown>;
+        };
+    };
+}
+interface EmailServiceOptions {
+    /** The transport. */
+    provider: EmailProvider;
+    /** Default from-address used when a message omits `from`. */
+    defaultFrom: string;
+    /** Default reply-to applied when a message omits `replyTo`. */
+    defaultReplyTo?: string;
+    /** When provided, every send writes an email_log document to the documents table. */
+    db?: EmailLogDb;
+    /** Injectable clock (tests). Defaults to `Date.now`. */
+    now?: () => number;
+    /** Injectable id factory (tests). Defaults to `crypto.randomUUID`. */
+    idFactory?: () => string;
+}
+declare class EmailService {
+    private readonly provider;
+    private readonly defaultFrom;
+    private readonly defaultReplyTo?;
+    private readonly db?;
+    private readonly now;
+    private readonly idFactory;
+    constructor(options: EmailServiceOptions);
+    /** Name of the active transport (e.g. `'resend'`). */
+    getProviderName(): string;
+    /** True if the active transport is ready to send. */
+    isConfigured(): boolean;
+    /**
+     * Ask the active provider to reconcile delivery state for a batch of
+     * recently-sent email_log document rows. Returns empty array when the provider
+     * does not implement `reconcile()` (Resend, SendGrid, Console).
+     *
+     * Called by the `email-reconciliation` cron plugin.
+     */
+    reconcileDelivery(rows: EmailLogRow[]): Promise<Array<{
+        id: string;
+        delivery_state: string;
+    }>>;
+    /** Normalize, send, and log. Never throws for ordinary delivery failures. */
+    send(message: EmailMessage): Promise<SendResult>;
+    /**
+     * Best-effort write of an email_log document into the `documents` table.
+     * Documents use SECONDS for timestamps (not ms). Email log entries are
+     * draft-only (is_current_draft=1, is_published=0, maxVersionsPerRoot=1).
+     * Returns the new document's root_id, or undefined if logging is disabled / fails.
+     */
+    private writeLog;
+}
+
+/**
+ * Plugin capabilities
+ *
+ * A plugin declares the capabilities it needs (`capabilities: ['email:send']`).
+ * The host then hands it a context whose powerful accessors are *gated* by those
+ * declarations: reaching `ctx.email` without having declared `email:send` throws
+ * `SonicCapabilityError` immediately, instead of failing deep inside a send.
+ *
+ * This is the isolation boundary that Strapi (namespacing only) and Payload (full
+ * config access) don't have: capabilities make a plugin's blast radius explicit
+ * and enforceable, and double as documentation of what a plugin can touch.
+ *
+ * Phase 1 vocabulary. Payment/queue/scheduled-fetch capabilities are intentionally
+ * deferred to Phase 2 (see the overhaul plan §8.4 / open question 2).
+ */
+
+/**
+ * Fixed capability names. `db:<table>` is parameterized (a plugin owns specific
+ * tables), so it is matched by pattern rather than listed here.
+ */
+declare const FIXED_CAPABILITIES: readonly ["email:send", "cache:read", "cache:write", "media:read", "media:write", "http:fetch", "cron:register", "admin:menu", "hooks.auth:subscribe", "hooks.content:subscribe", "hooks.email:subscribe"];
+type FixedCapability = (typeof FIXED_CAPABILITIES)[number];
+/** A scoped database capability, e.g. `db:email_log`. */
+type DbCapability = `db:${string}`;
+/** Any declarable capability. */
+type Capability = FixedCapability | DbCapability;
+/** True if `name` is a recognized capability (fixed name or a valid `db:<table>`). */
+declare function isKnownCapability(name: string): name is Capability;
+/**
+ * Thrown when a plugin uses a capability it did not declare.
+ */
+declare class SonicCapabilityError extends Error {
+    readonly capability: string;
+    readonly plugin?: string;
+    /** The API surface the plugin tried to access (e.g. 'ctx.cap.email'). Optional. */
+    readonly accessedApi?: string;
+    constructor(capability: string, plugin?: string, accessedApi?: string);
+}
+/** True if `capability` is in the granted set. */
+declare function hasCapability(granted: readonly string[], capability: string): boolean;
+/**
+ * Assert a capability is granted, throwing {@link SonicCapabilityError} otherwise.
+ */
+declare function assertCapability(granted: readonly string[], capability: string, plugin?: string): void;
+/**
+ * Validate a plugin's declared capability list. Returns the unknown entries (empty
+ * array = all valid). Callers decide whether to warn or hard-fail.
+ *
+ * Apply {@link normalizeCapabilities} first if the input may contain deprecated
+ * spellings (e.g. from an older SDK or a sibling fork's manifest).
+ */
+declare function validateCapabilities(declared: readonly string[]): string[];
+declare const CAPABILITY_RENAMES: {
+    readonly 'storage:read': "media:read";
+    readonly 'storage:write': "media:write";
+    readonly 'hooks.cron:register': "cron:register";
+    readonly 'hooks.auth:register': "hooks.auth:subscribe";
+    readonly 'hooks.content-read:register': "hooks.content:subscribe";
+    readonly 'hooks.content-write:register': "hooks.content:subscribe";
+    readonly 'hooks.email-events:register': "hooks.email:subscribe";
+};
+/**
+ * Resolve a (possibly deprecated) capability string to its canonical form, or
+ * `null` if it is unknown after rename resolution. Renames apply first, then the
+ * result is checked against the known vocabulary.
+ */
+declare function normalizeCapability(input: string): Capability | null;
+/**
+ * Normalize a list of capability strings. Returns the canonical capabilities plus
+ * the inputs that remained unknown after rename resolution, so the caller can warn
+ * (production) or reject (strict).
+ */
+declare function normalizeCapabilities(declared: readonly string[]): {
+    capabilities: Capability[];
+    unknown: string[];
+};
+/** Provider factories for capability-backed accessors. Each is called lazily. */
+interface CapabilityProviders {
+    email?: () => EmailService;
+    cache?: () => unknown;
+    http?: () => typeof fetch;
+}
+declare const CAP_NOT_DECLARED: unique symbol;
+/**
+ * The type of a capability accessor the plugin did NOT declare. Deliberately a
+ * branded type (not `never`, which is assignable to everything): using it where a
+ * service is expected is a compile error, so `ctx.cap.email` without `email:send`
+ * fails to type-check instead of silently passing.
+ */
+type CapabilityNotDeclared<C extends string = string> = {
+    readonly [CAP_NOT_DECLARED]: C;
+};
+type WhenGranted<Caps extends readonly Capability[], C extends string, T> = C extends Caps[number] ? T : CapabilityNotDeclared<C>;
+type WhenGrantedAny<Caps extends readonly Capability[], C extends string, T> = Extract<Caps[number], C> extends never ? CapabilityNotDeclared<C> : T;
+/**
+ * The gated context handed to a plugin. Accessors throw at runtime unless the
+ * backing capability was declared; with a const-narrowed `Caps` tuple they are
+ * also *typed* to the service (or `never`) at compile time, so `ctx.cap.email`
+ * is `EmailService` only when `'email:send'` was declared.
+ */
+interface CapabilityContext<Caps extends readonly Capability[] = readonly Capability[]> {
+    /** The capabilities granted to this plugin. */
+    readonly capabilities: readonly string[];
+    /** True if the plugin declared `capability`. */
+    has(capability: string): boolean;
+    /** Throw {@link SonicCapabilityError} unless `capability` was declared. */
+    require(capability: string): void;
+    /** Email service. `EmailService` when `email:send` is declared, else `never`. */
+    readonly email: WhenGranted<Caps, 'email:send', EmailService>;
+    /** Cache service. Present when `cache:read` or `cache:write` is declared. */
+    readonly cache: WhenGrantedAny<Caps, 'cache:read' | 'cache:write', unknown>;
+    /** Outbound fetch. Present when `http:fetch` is declared. */
+    readonly http: WhenGranted<Caps, 'http:fetch', typeof fetch>;
+}
+/** The un-narrowed gated context (every accessor typed as its service). */
+type PluginCapabilityContext = CapabilityContext</** all */ readonly Capability[]>;
+/**
+ * Build a capability-gated context.
+ *
+ * Accessors are lazy getters: they check the grant (and that a provider was
+ * supplied) at access time, so merely constructing the context is cheap and
+ * holding a reference to a capability you never use costs nothing.
+ *
+ * @param granted   Capabilities the plugin declared.
+ * @param providers Backing service factories (only the granted ones get called).
+ * @param plugin    Plugin name, for clearer errors.
+ */
+declare function createCapabilityContext<const Caps extends readonly Capability[]>(granted: Caps, providers?: CapabilityProviders, plugin?: string): CapabilityContext<Caps>;
+
+/**
+ * definePlugin() — the v3 plugin authoring entry point
+ *
+ * A plugin is authored as a single typed declaration and consumed, unchanged, by
+ * every part of the runtime:
+ *
+ *   export const emailPlugin = definePlugin({
+ *     id: 'email',
+ *     version: '3.0.0',
+ *     capabilities: ['email:send', 'hooks.auth:subscribe', 'cron:register'],
+ *     register(app) { app.route('/admin/plugins/email', emailRoutes) },   // SYNC
+ *     async onBoot(ctx) {                                                  // ASYNC
+ *       ctx.hooks.on('auth:registration:completed', (p) => { ... })       // typed
+ *       ctx.cap.email                                                     // gated
+ *     },
+ *     crons: [{ schedule: '*\/15 * * * *', hookFamily: 'email-reconciliation' }],
+ *     async onCronTick(event, ctx) { ... },
+ *   })
+ *
+ * The object it returns satisfies the structural contracts the runtime already
+ * uses — `MountablePlugin` (mount.ts), `WirablePlugin` (wire.ts), `CronablePlugin`
+ * (cron.ts) — plus the legacy `Plugin` metadata fields the admin/registry read.
+ * No adapters: a defined plugin drops straight into `plugins.register` or the core
+ * plugin list.
+ *
+ * The value definePlugin adds over a hand-written object is the enriched context:
+ * inside `onBoot`/`onCronTick` the author gets a *typed* hook facade (`ctx.hooks`)
+ * and the *capability-gated* service context (`ctx.cap`), instead of the raw
+ * string-keyed hook system. See the two-phase boot contract: `register` is
+ * synchronous (routes only); everything env-dependent lives in `onBoot`.
+ */
+
+/**
+ * Declarative typed hook subscriptions: a map of canonical event name → handler,
+ * each narrowed to that event's payload. Flattened into the plugin's `hooks[]`
+ * and subscribed during the wire phase. Use `onBoot`'s `ctx.hooks.on()` instead
+ * for dynamic/conditional subscriptions.
+ */
+type DeclarativeHooks = {
+    [E in HookEventName]?: TypedHookHandler<E>;
+};
+/**
+ * Context handed to a defined plugin's `onBoot` / `onCronTick`.
+ *
+ * Enriches the raw boot/cron context with a typed hook facade and the gated
+ * capability context, while keeping `raw` and `env` available as an escape hatch.
+ */
+interface DefinedPluginContext<Caps extends readonly Capability[] = readonly Capability[]> {
+    /** Typed hook facade — `ctx.hooks.on('auth:registration:completed', …)`. */
+    hooks: TypedHooks;
+    /**
+     * Capability-gated services. With a const-narrowed `Caps`, `ctx.cap.email` is
+     * typed `EmailService` only when `'email:send'` was declared (else `never`),
+     * and throws `SonicCapabilityError` at runtime if accessed undeclared.
+     */
+    cap: CapabilityContext<Caps>;
+    /** Runtime bindings, when available (absent during construction). */
+    env?: Record<string, unknown>;
+    /** The unwrapped context the runtime passed. */
+    raw: PluginBootContext | CronContext;
+}
+/** Input to {@link definePlugin}. */
+interface DefinePluginInput<Caps extends readonly Capability[] = readonly []> {
+    /** Unique, stable plugin id (kebab-case). Becomes the plugin `name`. */
+    id: string;
+    /** Human-readable display name. Defaults to `id`. */
+    name?: string;
+    /**
+     * Semantic version of this plugin (e.g. `'1.2.3'`). Must be a valid semver
+     * string — invalid values emit a console.warn at definition time.
+     */
+    version: string;
+    /**
+     * A semver range expressing which SonicJS core versions this plugin supports
+     * (e.g. `'^3.0.0'` or `'>=3.1.0 <4.0.0'`). Checked against the running
+     * core version at registration; a mismatch logs a compatibility warning but
+     * does not block activation (plugins remain resilient by default).
+     */
+    sonicjsVersionRange?: string;
+    description?: string;
+    author?: {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    /** Other plugin ids this one needs (load-order / activation). */
+    dependencies?: string[];
+    /**
+     * Capabilities this plugin declares. The gated `ctx.cap` accessors throw for
+     * anything not listed here. Pass as a literal (`['email:send'] as const` is not
+     * needed — the `const` type param infers the tuple) to get `ctx.cap` narrowed.
+     * Unknown/deprecated names are normalized then warned about at definition.
+     */
+    capabilities?: Caps;
+    /** Declarative routes (mounted before the /admin catch-all). */
+    routes?: MountableRoute[];
+    /**
+     * Imperative route registration. MUST be synchronous (Hono's router locks after
+     * the first request). Async work belongs in `onBoot`.
+     */
+    register?: (app: Hono) => void;
+    /**
+     * Declarative typed hook subscriptions (`{ 'content:after:create': (p) => … }`).
+     * Subscribed during the wire phase; each handler is narrowed to its event payload.
+     */
+    hooks?: DeclarativeHooks;
+    /**
+     * Run once on first request, after every plugin has registered. The place for
+     * dynamic hook subscriptions (`ctx.hooks.on(...)`) and env-dependent setup.
+     */
+    onBoot?: (context: DefinedPluginContext<Caps>) => void | Promise<void>;
+    /** Scheduled-work declarations (also list the expressions in wrangler.toml). */
+    crons?: CronDeclaration[];
+    /** Handler for a fired cron; branch on `event.hookFamily`. */
+    onCronTick?: (event: CronTickEvent, context: DefinedPluginContext<Caps>) => void | Promise<void>;
+    install?: (context: unknown) => void | Promise<void>;
+    uninstall?: (context: unknown) => void | Promise<void>;
+    activate?: (context: unknown) => void | Promise<void>;
+    deactivate?: (context: unknown) => void | Promise<void>;
+    /**
+     * Declarative admin-sidebar entries collected by registerPlugins. The catalyst
+     * sidebar renders them automatically; no per-plugin `addMenuItem(...)` call
+     * required.
+     */
+    menu?: PluginMenuEntry[];
+    /**
+     * Schema-driven settings. Declaring this auto-renders the admin form at
+     * `/admin/settings/plugins/:id`, parses FormData back into typed values, and
+     * persists them via the plugin-service. Authors no longer hand-roll settings
+     * routes/templates.
+     */
+    configSchema?: ConfigSchema;
+}
+/**
+ * The runtime shape produced by {@link definePlugin}. Carries the legacy metadata
+ * fields plus the v3 surfaces; structurally satisfies `MountablePlugin`,
+ * `WirablePlugin`, and `CronablePlugin`.
+ */
+interface DefinedPlugin {
+    id: string;
+    name: string;
+    version: string;
+    /** The semver range for SonicJS core compatibility declared by the author. */
+    sonicjsVersionRange?: string;
+    description?: string;
+    author?: {
+        name: string;
+        email?: string;
+        url?: string;
+    };
+    dependencies?: string[];
+    capabilities: Capability[];
+    routes?: MountableRoute[];
+    register?: (app: Hono) => void;
+    /** Declarative hook subscriptions, flattened for the wire phase. */
+    hooks?: WirableHook[];
+    /** Wrapped onBoot accepting the runtime's raw boot context. */
+    onBoot?: (context: PluginBootContext) => void | Promise<void>;
+    crons?: CronDeclaration[];
+    /** Wrapped onCronTick accepting the runtime's raw cron context. */
+    onCronTick?: (event: CronTickEvent, context: CronContext) => void | Promise<void>;
+    install?: (context: unknown) => void | Promise<void>;
+    uninstall?: (context: unknown) => void | Promise<void>;
+    activate?: (context: unknown) => void | Promise<void>;
+    deactivate?: (context: unknown) => void | Promise<void>;
+    /** Declarative admin sidebar entries. registerPlugins collects + sets the menu singleton. */
+    menu?: PluginMenuEntry[];
+    /** Schema-driven settings. Renders the admin settings form for this plugin. */
+    configSchema?: ConfigSchema;
+    /** Marker so tooling/tests can detect a v3-defined plugin. */
+    readonly __sonicV3: true;
+}
+/**
+ * Define a v3 plugin. Validates declared capabilities (warns on unknown), then
+ * returns a runtime-ready plugin whose `onBoot`/`onCronTick` receive the enriched,
+ * typed, capability-gated context. The `const Caps` type parameter captures the
+ * declared capability tuple so `ctx.cap` is narrowed at the author's call site.
+ */
+declare function definePlugin<const Caps extends readonly Capability[] = readonly []>(input: DefinePluginInput<Caps>): DefinedPlugin;
+/** True if `plugin` was produced by {@link definePlugin}. */
+declare function isDefinedPlugin(plugin: unknown): plugin is DefinedPlugin;
+
+export { collectCrons as $, RegisterPluginsError as A, type BooleanField as B, CAPABILITY_RENAMES as C, type DbCapability as D, type ExecutionContextLike as E, FIXED_CAPABILITIES as F, type RegisterPluginsErrorReason as G, HookSystemImpl as H, type RegisterPluginsHostContext as I, type RegisterablePlugin as J, type RegistryEntry as K, ScopedHookSystem as L, type MountResult as M, type NumberField as N, type SelectField as O, type ParsedField as P, type SettingsFor as Q, type RegisterPluginRoutesOptions as R, type ScheduledControllerLike as S, SonicCapabilityError as T, type StringField as U, type WirablePlugin as V, type WirableHook as W, type WireResult as X, applySchemaDefaults as Y, assertCapability as Z, collectCronSchedules as _, type Capability as a, createCapabilityContext as a0, createPluginWirer as a1, createScheduledHandler as a2, definePlugin as a3, dispatchCronTick as a4, getHookSystem as a5, getTypedHooks as a6, hasCapability as a7, hasHookSystem as a8, isDefinedPlugin as a9, isKnownCapability as aa, mountPlugin as ab, normalizeCapabilities as ac, normalizeCapability as ad, parseConfigSchema as ae, parseFormDataToSettings as af, registerPluginRoutes as ag, registerPlugins as ah, renderSchemaFields as ai, resetHookSystem as aj, setHookSystem as ak, validateCapabilities as al, wireRegisteredPlugins as am, type PluginMenuEntry as an, type ResolvedPluginMenuEntry as ao, getPluginMenu as ap, resetPluginMenu as aq, resolvePluginMenuItems as ar, setPluginMenu as as, type CapabilityContext as b, type CapabilityProviders as c, type CollectedCron as d, type ConfigSchema as e, type ConfigSchemaField as f, type CreateScheduledHandlerOptions as g, type CronContext as h, type CronDeclaration as i, type CronDispatchResult as j, type CronTickEvent as k, type CronablePlugin as l, type DeclarativeHooks as m, type DefinePluginInput as n, type DefinedPlugin as o, type DefinedPluginContext as p, type FixedCapability as q, HookUtils as r, type MountedRoute as s, type PluginBootContext as t, type PluginCapabilityContext as u, PluginManager as v, PluginRegisterMustBeSyncError as w, PluginRegistryImpl as x, PluginValidator as y, type PluginsRegistry as z };