@fidelios/server 0.0.1

package/dist/services/plugin-job-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-job-store.d.ts","sourceRoot":"","sources":["../../src/services/plugin-job-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAGH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAW,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAClE,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,eAAe,EAChB,MAAM,kBAAkB,CAAC;AAG1B;;;;GAIG;AACH,KAAK,mBAAmB,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;AAMrD;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,iCAAiC;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,6BAA6B;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,+BAA+B;IAC/B,OAAO,EAAE,mBAAmB,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wBAAwB;IACxB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,oCAAoC;IACpC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AAMD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,EAAE;IAwBjC;;;;;;;;;;;;;;;;OAgBG;kCAES,MAAM,gBACF,oBAAoB,EAAE,GACnC,OAAO,CAAC,IAAI,CAAC;IA4DhB;;;;;OAKG;uBAES,MAAM,WACP,mBAAmB,GAC3B,OAAO,CAAC,CAAC,OAAO,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;IAW9C;;;;;;OAMG;0BAES,MAAM,UACR,MAAM,GACb,OAAO,CAAC,CAAC,OAAO,UAAU,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;IAanD;;;;;OAKG;sBAEM,MAAM,GACZ,OAAO,CAAC,CAAC,OAAO,UAAU,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;IAQnD;;;;;OAKG;kCAES,MAAM,SACT,MAAM,GACZ,OAAO,CAAC,CAAC,OAAO,UAAU,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;IAQnD;;;;;OAKG;2BAEM,MAAM,UACL,mBAAmB,GAC1B,OAAO,CAAC,IAAI,CAAC;IAOhB;;;;;;;;;OASG;+BAEM,MAAM,aACF,IAAI,aACJ,IAAI,GAAG,IAAI,GACrB,OAAO,CAAC,IAAI,CAAC;IAWhB;;;;;;OAMG;4BAC2B,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUpD;;;;;;;;;OASG;qBAEM,iBAAiB,GACvB,OAAO,CAAC,OAAO,aAAa,CAAC,YAAY,CAAC;IAc7C;;;;OAIG;uBACsB,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C;;;;;;OAMG;uBAEM,MAAM,SACN,mBAAmB,GACzB,OAAO,CAAC,IAAI,CAAC;IAYhB;;;;;OAKG;sBAEM,MAAM,GACZ,OAAO,CAAC,CAAC,OAAO,aAAa,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC;IAQtD;;;;;OAKG;yBAEM,MAAM,mBAEZ,OAAO,CAAC,CAAC,OAAO,aAAa,CAAC,YAAY,CAAC,EAAE,CAAC;IASjD;;;;;;OAMG;+BAES,MAAM,WACP,kBAAkB,mBAE1B,OAAO,CAAC,CAAC,OAAO,aAAa,CAAC,YAAY,CAAC,EAAE,CAAC;EAapD;AAED,6DAA6D;AAC7D,MAAM,MAAM,cAAc,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC"}

package/dist/services/plugin-job-store.js

@@ -0,0 +1,350 @@
+/**
+ * Plugin Job Store — persistence layer for scheduled plugin jobs and their
+ * execution history.
+ *
+ * This service manages the `plugin_jobs` and `plugin_job_runs` tables. It is
+ * the server-side backing store for the `ctx.jobs` SDK surface exposed to
+ * plugin workers.
+ *
+ * ## Responsibilities
+ *
+ * 1. **Sync job declarations** — When a plugin is installed or started, the
+ *    host calls `syncJobDeclarations()` to upsert the manifest's declared jobs
+ *    into the `plugin_jobs` table. Jobs removed from the manifest are marked
+ *    `paused` (not deleted) to preserve history.
+ *
+ * 2. **Job CRUD** — List, get, pause, and resume jobs for a given plugin.
+ *
+ * 3. **Run lifecycle** — Create job run records, update their status, and
+ *    record results (duration, errors, logs).
+ *
+ * 4. **Next-run calculation** — After a run completes the host should call
+ *    `updateNextRunAt()` with the next cron tick so the scheduler knows when
+ *    to fire next.
+ *
+ * The capability check (`jobs.schedule`) is enforced upstream by the host
+ * client factory and manifest validator — this store trusts that the caller
+ * has already been authorised.
+ *
+ * @see PLUGIN_SPEC.md §17 — Scheduled Jobs
+ * @see PLUGIN_SPEC.md §21.3 — `plugin_jobs` / `plugin_job_runs` tables
+ */
+import { and, desc, eq } from "drizzle-orm";
+import { plugins, pluginJobs, pluginJobRuns } from "@fidelios/db";
+import { notFound } from "../errors.js";
+// ---------------------------------------------------------------------------
+// Service
+// ---------------------------------------------------------------------------
+/**
+ * Create a PluginJobStore backed by the given Drizzle database instance.
+ *
+ * @example
+ * ```ts
+ * const jobStore = pluginJobStore(db);
+ *
+ * // On plugin install/start — sync declared jobs into the DB
+ * await jobStore.syncJobDeclarations(pluginId, manifest.jobs ?? []);
+ *
+ * // Before dispatching a runJob RPC — create a run record
+ * const run = await jobStore.createRun({ jobId, pluginId, trigger: "schedule" });
+ *
+ * // After the RPC completes — record the result
+ * await jobStore.completeRun(run.id, {
+ *   status: "succeeded",
+ *   durationMs: Date.now() - startedAt,
+ * });
+ * ```
+ */
+export function pluginJobStore(db) {
+    // -----------------------------------------------------------------------
+    // Internal helpers
+    // -----------------------------------------------------------------------
+    async function assertPluginExists(pluginId) {
+        const rows = await db
+            .select({ id: plugins.id })
+            .from(plugins)
+            .where(eq(plugins.id, pluginId));
+        if (rows.length === 0) {
+            throw notFound(`Plugin not found: ${pluginId}`);
+        }
+    }
+    // -----------------------------------------------------------------------
+    // Public API
+    // -----------------------------------------------------------------------
+    return {
+        // =====================================================================
+        // Job declarations (plugin_jobs)
+        // =====================================================================
+        /**
+         * Sync declared jobs from a plugin manifest into the `plugin_jobs` table.
+         *
+         * This is called at plugin install and on each worker startup so the DB
+         * always reflects the manifest's declared jobs:
+         *
+         * - **New jobs** are inserted with status `active`.
+         * - **Existing jobs** have their `schedule` updated if it changed.
+         * - **Removed jobs** (present in DB but absent from the manifest) are
+         *   set to `paused` so their history is preserved.
+         *
+         * The unique constraint `(pluginId, jobKey)` is used for conflict
+         * resolution.
+         *
+         * @param pluginId - UUID of the owning plugin
+         * @param declarations - Job declarations from the plugin manifest
+         */
+        async syncJobDeclarations(pluginId, declarations) {
+            await assertPluginExists(pluginId);
+            // Fetch existing jobs for this plugin
+            const existingJobs = await db
+                .select()
+                .from(pluginJobs)
+                .where(eq(pluginJobs.pluginId, pluginId));
+            const existingByKey = new Map(existingJobs.map((j) => [j.jobKey, j]));
+            const declaredKeys = new Set();
+            // Upsert each declared job
+            for (const decl of declarations) {
+                declaredKeys.add(decl.jobKey);
+                const existing = existingByKey.get(decl.jobKey);
+                const schedule = decl.schedule ?? "";
+                if (existing) {
+                    // Update schedule if it changed; re-activate if it was paused
+                    const updates = {
+                        updatedAt: new Date(),
+                    };
+                    if (existing.schedule !== schedule) {
+                        updates.schedule = schedule;
+                    }
+                    if (existing.status === "paused") {
+                        updates.status = "active";
+                    }
+                    await db
+                        .update(pluginJobs)
+                        .set(updates)
+                        .where(eq(pluginJobs.id, existing.id));
+                }
+                else {
+                    // Insert new job
+                    await db.insert(pluginJobs).values({
+                        pluginId,
+                        jobKey: decl.jobKey,
+                        schedule,
+                        status: "active",
+                    });
+                }
+            }
+            // Pause jobs that are no longer declared in the manifest
+            for (const existing of existingJobs) {
+                if (!declaredKeys.has(existing.jobKey) && existing.status !== "paused") {
+                    await db
+                        .update(pluginJobs)
+                        .set({ status: "paused", updatedAt: new Date() })
+                        .where(eq(pluginJobs.id, existing.id));
+                }
+            }
+        },
+        /**
+         * List all jobs for a plugin, optionally filtered by status.
+         *
+         * @param pluginId - UUID of the owning plugin
+         * @param status - Optional status filter
+         */
+        async listJobs(pluginId, status) {
+            const conditions = [eq(pluginJobs.pluginId, pluginId)];
+            if (status) {
+                conditions.push(eq(pluginJobs.status, status));
+            }
+            return db
+                .select()
+                .from(pluginJobs)
+                .where(and(...conditions));
+        },
+        /**
+         * Get a single job by its composite key `(pluginId, jobKey)`.
+         *
+         * @param pluginId - UUID of the owning plugin
+         * @param jobKey - Stable job identifier from the manifest
+         * @returns The job row, or `null` if not found
+         */
+        async getJobByKey(pluginId, jobKey) {
+            const rows = await db
+                .select()
+                .from(pluginJobs)
+                .where(and(eq(pluginJobs.pluginId, pluginId), eq(pluginJobs.jobKey, jobKey)));
+            return rows[0] ?? null;
+        },
+        /**
+         * Get a single job by its primary key (UUID).
+         *
+         * @param jobId - UUID of the job row
+         * @returns The job row, or `null` if not found
+         */
+        async getJobById(jobId) {
+            const rows = await db
+                .select()
+                .from(pluginJobs)
+                .where(eq(pluginJobs.id, jobId));
+            return rows[0] ?? null;
+        },
+        /**
+         * Fetch a single job by ID, scoped to a specific plugin.
+         *
+         * Returns `null` if the job does not exist or does not belong to the
+         * given plugin — callers should treat both cases as "not found".
+         */
+        async getJobByIdForPlugin(pluginId, jobId) {
+            const rows = await db
+                .select()
+                .from(pluginJobs)
+                .where(and(eq(pluginJobs.id, jobId), eq(pluginJobs.pluginId, pluginId)));
+            return rows[0] ?? null;
+        },
+        /**
+         * Update a job's status.
+         *
+         * @param jobId - UUID of the job row
+         * @param status - New status
+         */
+        async updateJobStatus(jobId, status) {
+            await db
+                .update(pluginJobs)
+                .set({ status, updatedAt: new Date() })
+                .where(eq(pluginJobs.id, jobId));
+        },
+        /**
+         * Update the `lastRunAt` and `nextRunAt` timestamps on a job.
+         *
+         * Called by the scheduler after a run completes to advance the
+         * scheduling pointer.
+         *
+         * @param jobId - UUID of the job row
+         * @param lastRunAt - When the last run started
+         * @param nextRunAt - When the next run should fire
+         */
+        async updateRunTimestamps(jobId, lastRunAt, nextRunAt) {
+            await db
+                .update(pluginJobs)
+                .set({
+                lastRunAt,
+                nextRunAt,
+                updatedAt: new Date(),
+            })
+                .where(eq(pluginJobs.id, jobId));
+        },
+        /**
+         * Delete all jobs (and cascaded runs) owned by a plugin.
+         *
+         * Called during plugin uninstall when `removeData = true`.
+         *
+         * @param pluginId - UUID of the owning plugin
+         */
+        async deleteAllJobs(pluginId) {
+            await db
+                .delete(pluginJobs)
+                .where(eq(pluginJobs.pluginId, pluginId));
+        },
+        // =====================================================================
+        // Job runs (plugin_job_runs)
+        // =====================================================================
+        /**
+         * Create a new job run record with status `queued`.
+         *
+         * The caller should create the run record *before* dispatching the
+         * `runJob` RPC to the worker, then update it to `running` once the
+         * worker begins execution.
+         *
+         * @param input - Job run input (jobId, pluginId, trigger)
+         * @returns The newly created run row
+         */
+        async createRun(input) {
+            const rows = await db
+                .insert(pluginJobRuns)
+                .values({
+                jobId: input.jobId,
+                pluginId: input.pluginId,
+                trigger: input.trigger,
+                status: "queued",
+            })
+                .returning();
+            return rows[0];
+        },
+        /**
+         * Mark a run as `running` and set its `startedAt` timestamp.
+         *
+         * @param runId - UUID of the run row
+         */
+        async markRunning(runId) {
+            await db
+                .update(pluginJobRuns)
+                .set({
+                status: "running",
+                startedAt: new Date(),
+            })
+                .where(eq(pluginJobRuns.id, runId));
+        },
+        /**
+         * Complete a run — set its final status, error, duration, and
+         * `finishedAt` timestamp.
+         *
+         * @param runId - UUID of the run row
+         * @param input - Completion details
+         */
+        async completeRun(runId, input) {
+            await db
+                .update(pluginJobRuns)
+                .set({
+                status: input.status,
+                error: input.error ?? null,
+                durationMs: input.durationMs ?? null,
+                finishedAt: new Date(),
+            })
+                .where(eq(pluginJobRuns.id, runId));
+        },
+        /**
+         * Get a run by its primary key.
+         *
+         * @param runId - UUID of the run row
+         * @returns The run row, or `null` if not found
+         */
+        async getRunById(runId) {
+            const rows = await db
+                .select()
+                .from(pluginJobRuns)
+                .where(eq(pluginJobRuns.id, runId));
+            return rows[0] ?? null;
+        },
+        /**
+         * List runs for a specific job, ordered by creation time descending.
+         *
+         * @param jobId - UUID of the job
+         * @param limit - Maximum number of rows to return (default: 50)
+         */
+        async listRunsByJob(jobId, limit = 50) {
+            return db
+                .select()
+                .from(pluginJobRuns)
+                .where(eq(pluginJobRuns.jobId, jobId))
+                .orderBy(desc(pluginJobRuns.createdAt))
+                .limit(limit);
+        },
+        /**
+         * List runs for a plugin, optionally filtered by status.
+         *
+         * @param pluginId - UUID of the owning plugin
+         * @param status - Optional status filter
+         * @param limit - Maximum number of rows to return (default: 50)
+         */
+        async listRunsByPlugin(pluginId, status, limit = 50) {
+            const conditions = [eq(pluginJobRuns.pluginId, pluginId)];
+            if (status) {
+                conditions.push(eq(pluginJobRuns.status, status));
+            }
+            return db
+                .select()
+                .from(pluginJobRuns)
+                .where(and(...conditions))
+                .orderBy(desc(pluginJobRuns.createdAt))
+                .limit(limit);
+        },
+    };
+}
+//# sourceMappingURL=plugin-job-store.js.map

package/dist/services/plugin-job-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-job-store.js","sourceRoot":"","sources":["../../src/services/plugin-job-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAOlE,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAqCxC,8EAA8E;AAC9E,UAAU;AACV,8EAA8E;AAE9E;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,cAAc,CAAC,EAAM;IACnC,0EAA0E;IAC1E,mBAAmB;IACnB,0EAA0E;IAE1E,KAAK,UAAU,kBAAkB,CAAC,QAAgB;QAChD,MAAM,IAAI,GAAG,MAAM,EAAE;aAClB,MAAM,CAAC,EAAE,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC;aAC1B,IAAI,CAAC,OAAO,CAAC;aACb,KAAK,CAAC,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC;QACnC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACtB,MAAM,QAAQ,CAAC,qBAAqB,QAAQ,EAAE,CAAC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,0EAA0E;IAC1E,aAAa;IACb,0EAA0E;IAE1E,OAAO;QACL,wEAAwE;QACxE,iCAAiC;QACjC,wEAAwE;QAExE;;;;;;;;;;;;;;;;WAgBG;QACH,KAAK,CAAC,mBAAmB,CACvB,QAAgB,EAChB,YAAoC;YAEpC,MAAM,kBAAkB,CAAC,QAAQ,CAAC,CAAC;YAEnC,sCAAsC;YACtC,MAAM,YAAY,GAAG,MAAM,EAAE;iBAC1B,MAAM,EAAE;iBACR,IAAI,CAAC,UAAU,CAAC;iBAChB,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;YAE5C,MAAM,aAAa,GAAG,IAAI,GAAG,CAC3B,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CACvC,CAAC;YAEF,MAAM,YAAY,GAAG,IAAI,GAAG,EAAU,CAAC;YAEvC,2BAA2B;YAC3B,KAAK,MAAM,IAAI,IAAI,YAAY,EAAE,CAAC;gBAChC,YAAY,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAE9B,MAAM,QAAQ,GAAG,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAChD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,EAAE,CAAC;gBAErC,IAAI,QAAQ,EAAE,CAAC;oBACb,8DAA8D;oBAC9D,MAAM,OAAO,GAA4B;wBACvC,SAAS,EAAE,IAAI,IAAI,EAAE;qBACtB,CAAC;oBACF,IAAI,QAAQ,CAAC,QAAQ,KAAK,QAAQ,EAAE,CAAC;wBACnC,OAAO,CAAC,QAAQ,GAAG,QAAQ,CAAC;oBAC9B,CAAC;oBACD,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;wBACjC,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC;oBAC5B,CAAC;oBAED,MAAM,EAAE;yBACL,MAAM,CAAC,UAAU,CAAC;yBAClB,GAAG,CAAC,OAAO,CAAC;yBACZ,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC3C,CAAC;qBAAM,CAAC;oBACN,iBAAiB;oBACjB,MAAM,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC;wBACjC,QAAQ;wBACR,MAAM,EAAE,IAAI,CAAC,MAAM;wBACnB,QAAQ;wBACR,MAAM,EAAE,QAAQ;qBACjB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YAED,yDAAyD;YACzD,KAAK,MAAM,QAAQ,IAAI,YAAY,EAAE,CAAC;gBACpC,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,QAAQ,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;oBACvE,MAAM,EAAE;yBACL,MAAM,CAAC,UAAU,CAAC;yBAClB,GAAG,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;yBAChD,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC;gBAC3C,CAAC;YACH,CAAC;QACH,CAAC;QAED;;;;;WAKG;QACH,KAAK,CAAC,QAAQ,CACZ,QAAgB,EAChB,MAA4B;YAE5B,MAAM,UAAU,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;YACvD,IAAI,MAAM,EAAE,CAAC;gBACX,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;YACjD,CAAC;YACD,OAAO,EAAE;iBACN,MAAM,EAAE;iBACR,IAAI,CAAC,UAAU,CAAC;iBAChB,KAAK,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC;QAC/B,CAAC;QAED;;;;;;WAMG;QACH,KAAK,CAAC,WAAW,CACf,QAAgB,EAChB,MAAc;YAEd,MAAM,IAAI,GAAG,MAAM,EAAE;iBAClB,MAAM,EAAE;iBACR,IAAI,CAAC,UAAU,CAAC;iBAChB,KAAK,CACJ,GAAG,CACD,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,EACjC,EAAE,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,CAC9B,CACF,CAAC;YACJ,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QACzB,CAAC;QAED;;;;;WAKG;QACH,KAAK,CAAC,UAAU,CACd,KAAa;YAEb,MAAM,IAAI,GAAG,MAAM,EAAE;iBAClB,MAAM,EAAE;iBACR,IAAI,CAAC,UAAU,CAAC;iBAChB,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;YACnC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QACzB,CAAC;QAED;;;;;WAKG;QACH,KAAK,CAAC,mBAAmB,CACvB,QAAgB,EAChB,KAAa;YAEb,MAAM,IAAI,GAAG,MAAM,EAAE;iBAClB,MAAM,EAAE;iBACR,IAAI,CAAC,UAAU,CAAC;iBAChB,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;YAC3E,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QACzB,CAAC;QAED;;;;;WAKG;QACH,KAAK,CAAC,eAAe,CACnB,KAAa,EACb,MAA2B;YAE3B,MAAM,EAAE;iBACL,MAAM,CAAC,UAAU,CAAC;iBAClB,GAAG,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;iBACtC,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;QACrC,CAAC;QAED;;;;;;;;;WASG;QACH,KAAK,CAAC,mBAAmB,CACvB,KAAa,EACb,SAAe,EACf,SAAsB;YAEtB,MAAM,EAAE;iBACL,MAAM,CAAC,UAAU,CAAC;iBAClB,GAAG,CAAC;gBACH,SAAS;gBACT,SAAS;gBACT,SAAS,EAAE,IAAI,IAAI,EAAE;aACtB,CAAC;iBACD,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;QACrC,CAAC;QAED;;;;;;WAMG;QACH,KAAK,CAAC,aAAa,CAAC,QAAgB;YAClC,MAAM,EAAE;iBACL,MAAM,CAAC,UAAU,CAAC;iBAClB,KAAK,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC9C,CAAC;QAED,wEAAwE;QACxE,6BAA6B;QAC7B,wEAAwE;QAExE;;;;;;;;;WASG;QACH,KAAK,CAAC,SAAS,CACb,KAAwB;YAExB,MAAM,IAAI,GAAG,MAAM,EAAE;iBAClB,MAAM,CAAC,aAAa,CAAC;iBACrB,MAAM,CAAC;gBACN,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,MAAM,EAAE,QAAQ;aACjB,CAAC;iBACD,SAAS,EAAE,CAAC;YAEf,OAAO,IAAI,CAAC,CAAC,CAAE,CAAC;QAClB,CAAC;QAED;;;;WAIG;QACH,KAAK,CAAC,WAAW,CAAC,KAAa;YAC7B,MAAM,EAAE;iBACL,MAAM,CAAC,aAAa,CAAC;iBACrB,GAAG,CAAC;gBACH,MAAM,EAAE,SAA+B;gBACvC,SAAS,EAAE,IAAI,IAAI,EAAE;aACtB,CAAC;iBACD,KAAK,CAAC,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;QACxC,CAAC;QAED;;;;;;WAMG;QACH,KAAK,CAAC,WAAW,CACf,KAAa,EACb,KAA0B;YAE1B,MAAM,EAAE;iBACL,MAAM,CAAC,aAAa,CAAC;iBACrB,GAAG,CAAC;gBACH,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,KAAK,EAAE,KAAK,CAAC,KAAK,IAAI,IAAI;gBAC1B,UAAU,EAAE,KAAK,CAAC,UAAU,IAAI,IAAI;gBACpC,UAAU,EAAE,IAAI,IAAI,EAAE;aACvB,CAAC;iBACD,KAAK,CAAC,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;QACxC,CAAC;QAED;;;;;WAKG;QACH,KAAK,CAAC,UAAU,CACd,KAAa;YAEb,MAAM,IAAI,GAAG,MAAM,EAAE;iBAClB,MAAM,EAAE;iBACR,IAAI,CAAC,aAAa,CAAC;iBACnB,KAAK,CAAC,EAAE,CAAC,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;YACtC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QACzB,CAAC;QAED;;;;;WAKG;QACH,KAAK,CAAC,aAAa,CACjB,KAAa,EACb,KAAK,GAAG,EAAE;YAEV,OAAO,EAAE;iBACN,MAAM,EAAE;iBACR,IAAI,CAAC,aAAa,CAAC;iBACnB,KAAK,CAAC,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;iBACrC,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;iBACtC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;QAED;;;;;;WAMG;QACH,KAAK,CAAC,gBAAgB,CACpB,QAAgB,EAChB,MAA2B,EAC3B,KAAK,GAAG,EAAE;YAEV,MAAM,UAAU,GAAG,CAAC,EAAE,CAAC,aAAa,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC,CAAC;YAC1D,IAAI,MAAM,EAAE,CAAC;gBACX,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,aAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;YACpD,CAAC;YACD,OAAO,EAAE;iBACN,MAAM,EAAE;iBACR,IAAI,CAAC,aAAa,CAAC;iBACnB,KAAK,CAAC,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;iBACzB,OAAO,CAAC,IAAI,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC;iBACtC,KAAK,CAAC,KAAK,CAAC,CAAC;QAClB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/services/plugin-lifecycle.d.ts

@@ -0,0 +1,203 @@
+import type { Db } from "@fidelios/db";
+import type { PluginStatus, PluginRecord } from "@fidelios/shared";
+import { type PluginLoader } from "./plugin-loader.js";
+import type { PluginWorkerManager, WorkerStartOptions } from "./plugin-worker-manager.js";
+/**
+ * Events emitted by the PluginLifecycleManager.
+ * Consumers can subscribe to these for routing-table updates, UI refresh
+ * notifications, and observability.
+ */
+export interface PluginLifecycleEvents {
+    /** Emitted after a plugin is loaded (installed → ready). */
+    "plugin.loaded": {
+        pluginId: string;
+        pluginKey: string;
+    };
+    /** Emitted after a plugin transitions to ready (enabled). */
+    "plugin.enabled": {
+        pluginId: string;
+        pluginKey: string;
+    };
+    /** Emitted after a plugin is disabled (ready → disabled). */
+    "plugin.disabled": {
+        pluginId: string;
+        pluginKey: string;
+        reason?: string;
+    };
+    /** Emitted after a plugin is unloaded (any → uninstalled). */
+    "plugin.unloaded": {
+        pluginId: string;
+        pluginKey: string;
+        removeData: boolean;
+    };
+    /** Emitted on any status change. */
+    "plugin.status_changed": {
+        pluginId: string;
+        pluginKey: string;
+        previousStatus: PluginStatus;
+        newStatus: PluginStatus;
+    };
+    /** Emitted when a plugin enters an error state. */
+    "plugin.error": {
+        pluginId: string;
+        pluginKey: string;
+        error: string;
+    };
+    /** Emitted when a plugin enters upgrade_pending. */
+    "plugin.upgrade_pending": {
+        pluginId: string;
+        pluginKey: string;
+    };
+    /** Emitted when a plugin worker process has been started. */
+    "plugin.worker_started": {
+        pluginId: string;
+        pluginKey: string;
+    };
+    /** Emitted when a plugin worker process has been stopped. */
+    "plugin.worker_stopped": {
+        pluginId: string;
+        pluginKey: string;
+    };
+}
+type LifecycleEventName = keyof PluginLifecycleEvents;
+type LifecycleEventPayload<K extends LifecycleEventName> = PluginLifecycleEvents[K];
+export interface PluginLifecycleManager {
+    /**
+     * Load a newly installed plugin – transitions `installed` → `ready`.
+     *
+     * This is called after the registry has persisted the initial install record.
+     * The caller should have already spawned the worker and performed health
+     * checks before calling this.  If the worker fails, call `markError` instead.
+     */
+    load(pluginId: string): Promise<PluginRecord>;
+    /**
+     * Enable a plugin that is in `disabled`, `error`, or `upgrade_pending` state.
+     * Transitions → `ready`.
+     */
+    enable(pluginId: string): Promise<PluginRecord>;
+    /**
+     * Disable a running plugin.
+     * Transitions `ready` → `disabled`.
+     */
+    disable(pluginId: string, reason?: string): Promise<PluginRecord>;
+    /**
+     * Unload (uninstall) a plugin from any active state.
+     * Transitions → `uninstalled`.
+     *
+     * When `removeData` is true, the plugin row and cascaded config are
+     * hard-deleted.  Otherwise a soft-delete sets status to `uninstalled`.
+     */
+    unload(pluginId: string, removeData?: boolean): Promise<PluginRecord | null>;
+    /**
+     * Mark a plugin as errored (e.g. worker crash, health-check failure).
+     * Transitions → `error`.
+     */
+    markError(pluginId: string, error: string): Promise<PluginRecord>;
+    /**
+     * Mark a plugin as requiring upgrade approval.
+     * Transitions `ready` → `upgrade_pending`.
+     */
+    markUpgradePending(pluginId: string): Promise<PluginRecord>;
+    /**
+     * Upgrade a plugin to a newer version.
+     * This is a placeholder that handles the lifecycle state transition.
+     * The actual package installation is handled by plugin-loader.
+     *
+     * If the upgrade adds new capabilities, transitions to `upgrade_pending`.
+     * Otherwise, transitions to `ready` directly.
+     */
+    upgrade(pluginId: string, version?: string): Promise<PluginRecord>;
+    /**
+     * Start the worker process for a plugin that is already in `ready` state.
+     *
+     * This is used by the server startup orchestration to start workers for
+     * plugins that were persisted as `ready`. It requires a `PluginWorkerManager`
+     * to have been provided at construction time.
+     *
+     * @param pluginId - The UUID of the plugin to start
+     * @param options  - Worker start options (entrypoint path, config, etc.)
+     * @throws if no worker manager is configured or the plugin is not ready
+     */
+    startWorker(pluginId: string, options: WorkerStartOptions): Promise<void>;
+    /**
+     * Stop the worker process for a plugin without changing lifecycle state.
+     *
+     * This is used during server shutdown to gracefully stop all workers.
+     * It does not transition the plugin state — plugins remain in their
+     * current status so they can be restarted on next server boot.
+     *
+     * @param pluginId - The UUID of the plugin to stop
+     */
+    stopWorker(pluginId: string): Promise<void>;
+    /**
+     * Restart the worker process for a running plugin.
+     *
+     * Stops and re-starts the worker process. The plugin remains in `ready`
+     * state throughout. This is typically called after a config change.
+     *
+     * @param pluginId - The UUID of the plugin to restart
+     * @throws if no worker manager is configured or the plugin is not ready
+     */
+    restartWorker(pluginId: string): Promise<void>;
+    /**
+     * Get the current lifecycle state for a plugin.
+     */
+    getStatus(pluginId: string): Promise<PluginStatus | null>;
+    /**
+     * Check whether a transition is allowed from the plugin's current state.
+     */
+    canTransition(pluginId: string, to: PluginStatus): Promise<boolean>;
+    /**
+     * Subscribe to lifecycle events.
+     */
+    on<K extends LifecycleEventName>(event: K, listener: (payload: LifecycleEventPayload<K>) => void): void;
+    /**
+     * Unsubscribe from lifecycle events.
+     */
+    off<K extends LifecycleEventName>(event: K, listener: (payload: LifecycleEventPayload<K>) => void): void;
+    /**
+     * Subscribe to a lifecycle event once.
+     */
+    once<K extends LifecycleEventName>(event: K, listener: (payload: LifecycleEventPayload<K>) => void): void;
+}
+/**
+ * Options for constructing a PluginLifecycleManager.
+ */
+export interface PluginLifecycleManagerOptions {
+    /** Plugin loader instance. Falls back to the default if omitted. */
+    loader?: PluginLoader;
+    /**
+     * Worker process manager. When provided, lifecycle transitions that bring
+     * a plugin online (load, enable, upgrade-to-ready) will start the worker
+     * process, and transitions that take a plugin offline (disable, unload,
+     * markError) will stop it.
+     *
+     * When omitted the lifecycle manager operates in state-only mode — the
+     * caller is responsible for managing worker processes externally.
+     */
+    workerManager?: PluginWorkerManager;
+}
+/**
+ * Create a PluginLifecycleManager.
+ *
+ * This service orchestrates plugin state transitions on top of the
+ * `pluginRegistryService` (which handles raw DB persistence).  It enforces
+ * the lifecycle state machine, emits events for downstream consumers
+ * (routing tables, UI, observability), and manages worker processes via
+ * the `PluginWorkerManager` when one is provided.
+ *
+ * Usage:
+ * ```ts
+ * const lifecycle = pluginLifecycleManager(db, {
+ *   workerManager: createPluginWorkerManager(),
+ * });
+ * lifecycle.on("plugin.enabled", ({ pluginId }) => { ... });
+ * await lifecycle.load(pluginId);
+ * ```
+ *
+ * @see PLUGIN_SPEC.md §21.3 — `plugins.status` column
+ * @see PLUGIN_SPEC.md §12 — Process Model
+ */
+export declare function pluginLifecycleManager(db: Db, options?: PluginLoader | PluginLifecycleManagerOptions): PluginLifecycleManager;
+export {};
+//# sourceMappingURL=plugin-lifecycle.d.ts.map

package/dist/services/plugin-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-lifecycle.d.ts","sourceRoot":"","sources":["../../src/services/plugin-lifecycle.ts"],"names":[],"mappings":"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"}