@adminiumjs/adminium 0.1.0-rc.1

package/dist/jobs/worker.js

@@ -0,0 +1,282 @@
+/**
+ * In-process polling worker over `adminium_jobs` (01-architecture.md §5
+ * background path, 07-meta-store.md §3.12, M2-T07).
+ *
+ * Loop: claim via the portable UPDATE guard (`jobsRepo.claim`) → parse the
+ * payload against the registered handler's schema → run the handler with a
+ * progress/log/cancel context → `complete` or `fail` with exponential backoff
+ * (base 30 s, doubling, capped at 1 h) until `maxAttempts`, after which the
+ * row lands in terminal `failed` (the dead-letter state). One failing job
+ * never kills the process (08-server-api.md §6.10); `stop()` drains in-flight
+ * jobs before resolving (graceful shutdown).
+ *
+ * Progress is kept in-memory (`getProgress`) and published on `jobs:<jobId>`
+ * — the meta schema has no progress column in wave 0001, and the worker runs
+ * in-process with the API (01 §5), so route reads stay consistent.
+ */
+import { hostname } from 'node:os';
+import { jobsRepo, JOB_BACKOFF_BASE_MS } from '@adminium/meta';
+/** Backoff ceiling: no retry waits longer than an hour. */
+export const JOB_BACKOFF_MAX_MS = 3_600_000;
+/** Default number of jobs executing concurrently in one worker. */
+export const JOB_WORKER_CONCURRENCY = 2;
+/** Default idle delay between claim polls. */
+export const JOB_POLL_INTERVAL_MS = 1_000;
+/** How many finished-job progress snapshots to retain for route reads. */
+const PROGRESS_RETENTION = 500;
+const noopLogger = { info() { }, warn() { }, error() { } };
+/** Channel name for a job's realtime events. */
+export function jobChannel(jobId) {
+    return `jobs:${jobId}`;
+}
+export class JobWorker {
+    meta;
+    jobs;
+    registry;
+    hub;
+    concurrency;
+    pollIntervalMs;
+    backoffBaseMs;
+    backoffMaxMs;
+    now;
+    logger;
+    workerId;
+    running = new Map();
+    progressByJob = new Map();
+    stopped = true;
+    pollTimer = null;
+    constructor(opts) {
+        this.meta = opts.meta;
+        this.jobs = jobsRepo(opts.meta);
+        this.registry = opts.registry;
+        this.hub = opts.hub;
+        this.concurrency = opts.concurrency ?? JOB_WORKER_CONCURRENCY;
+        this.pollIntervalMs = opts.pollIntervalMs ?? JOB_POLL_INTERVAL_MS;
+        this.backoffBaseMs = opts.backoffBaseMs ?? JOB_BACKOFF_BASE_MS;
+        this.backoffMaxMs = opts.backoffMaxMs ?? JOB_BACKOFF_MAX_MS;
+        this.now = opts.now ?? Date.now;
+        this.logger = opts.logger ?? noopLogger;
+        this.workerId = opts.workerId ?? `${hostname()}:${process.pid}`;
+    }
+    /** Jobs currently executing in this worker. */
+    get activeCount() {
+        return this.running.size;
+    }
+    /** Last reported progress for a job known to this process, else `null`. */
+    getProgress(jobId) {
+        return this.progressByJob.get(jobId) ?? null;
+    }
+    /**
+     * Cooperative cancel (08 §2.17): aborts the run's signal if this worker is
+     * executing the job. Returns whether a running job was signalled.
+     */
+    requestCancel(jobId) {
+        const entry = this.running.get(jobId);
+        if (entry === undefined)
+            return false;
+        entry.controller.abort();
+        return true;
+    }
+    /** Start the poll loop; idempotent. */
+    start() {
+        if (!this.stopped)
+            return;
+        this.stopped = false;
+        this.schedulePoll(0);
+    }
+    /**
+     * Graceful drain: stop claiming, wait up to `drainTimeoutMs` for in-flight
+     * jobs, then abort stragglers and wait for them to settle.
+     */
+    async stop(opts = {}) {
+        this.stopped = true;
+        if (this.pollTimer !== null) {
+            clearTimeout(this.pollTimer);
+            this.pollTimer = null;
+        }
+        const drainTimeoutMs = opts.drainTimeoutMs ?? 10_000;
+        const inFlight = () => [...this.running.values()].map((r) => r.promise);
+        if (this.running.size === 0)
+            return;
+        const drained = await withTimeout(Promise.all(inFlight()), drainTimeoutMs);
+        if (!drained) {
+            this.logger.warn({ workerId: this.workerId, jobs: [...this.running.keys()] }, 'drain timeout — aborting in-flight jobs');
+            for (const entry of this.running.values())
+                entry.controller.abort();
+            await Promise.all(inFlight());
+        }
+    }
+    /**
+     * Deterministic single pass (tests/manual ticks): claims due jobs up to the
+     * concurrency limit and resolves when all of them finished. Returns how
+     * many jobs this call executed.
+     */
+    async runOnce() {
+        const batch = [];
+        while (this.running.size < this.concurrency) {
+            const job = await this.jobs.claim(this.workerId, this.now());
+            if (job === null)
+                break;
+            batch.push(this.launch(job));
+        }
+        await Promise.all(batch);
+        return batch.length;
+    }
+    // --- internals -----------------------------------------------------------------
+    schedulePoll(delayMs) {
+        if (this.stopped)
+            return;
+        this.pollTimer = setTimeout(() => {
+            void this.poll();
+        }, delayMs);
+        this.pollTimer.unref?.();
+    }
+    async poll() {
+        if (this.stopped)
+            return;
+        try {
+            while (!this.stopped && this.running.size < this.concurrency) {
+                const job = await this.jobs.claim(this.workerId, this.now());
+                if (job === null)
+                    break;
+                void this.launch(job);
+            }
+        }
+        catch (err) {
+            // e.g. meta DB briefly unreachable — log and keep polling (§6.10).
+            this.logger.error({ workerId: this.workerId, err }, 'job poll failed');
+        }
+        this.schedulePoll(this.pollIntervalMs);
+    }
+    /** Registers the job as running and executes it; never rejects. */
+    launch(job) {
+        const controller = new AbortController();
+        const promise = this.execute(job, controller)
+            .catch((err) => {
+            // `execute` handles handler errors itself; this only catches bugs in
+            // the completion/failure bookkeeping.
+            this.logger.error({ jobId: job.id, kind: job.kind, err }, 'job bookkeeping failed');
+        })
+            .finally(() => {
+            this.running.delete(job.id);
+        });
+        this.running.set(job.id, { controller, promise });
+        return promise;
+    }
+    async execute(job, controller) {
+        const channel = jobChannel(job.id);
+        try {
+            const entry = this.registry.get(job.kind);
+            if (entry === undefined) {
+                throw new Error(`no handler registered for job kind "${job.kind}"`);
+            }
+            const payload = entry.schema.parse(job.payload);
+            const ctx = {
+                jobId: job.id,
+                kind: job.kind,
+                attempt: job.attempts,
+                maxAttempts: job.maxAttempts,
+                signal: controller.signal,
+                progress: (pct, info) => {
+                    this.reportProgress(job, pct, info);
+                },
+                log: (message, data = {}) => {
+                    this.logger.info({ jobId: job.id, kind: job.kind, ...data }, message);
+                },
+            };
+            await entry.run(payload, ctx);
+            if (controller.signal.aborted) {
+                await this.markCancelled(job);
+                return;
+            }
+            await this.jobs.complete(job.id, this.now());
+            this.setProgress(job.id, { pct: 100 });
+            this.hub.publish(channel, 'completed', { jobId: job.id, kind: job.kind }, this.now());
+            this.logger.info({ jobId: job.id, kind: job.kind, attempt: job.attempts }, 'job succeeded');
+        }
+        catch (err) {
+            if (controller.signal.aborted) {
+                await this.markCancelled(job);
+                return;
+            }
+            await this.handleFailure(job, err);
+        }
+    }
+    /** Retry with capped exponential backoff, or dead-letter at maxAttempts. */
+    async handleFailure(job, err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const at = this.now();
+        // Delay for retry n (attempts = n after claim): base * 2^(n-1), capped.
+        // `jobsRepo.fail` recomputes `base' * 2^(n-1)`, so pass base' = delay / 2^(n-1).
+        const exponent = 2 ** Math.max(0, job.attempts - 1);
+        const delay = Math.min(this.backoffBaseMs * exponent, this.backoffMaxMs);
+        const updated = await this.jobs.fail(job.id, message, at, delay / exponent);
+        const dead = updated?.status === 'failed';
+        this.hub.publish(jobChannel(job.id), 'failed', {
+            jobId: job.id,
+            kind: job.kind,
+            error: message,
+            attempt: job.attempts,
+            maxAttempts: job.maxAttempts,
+            final: dead,
+            nextRunAt: dead ? null : (updated?.runAt ?? null),
+        }, at);
+        const logData = { jobId: job.id, kind: job.kind, attempt: job.attempts, err: message };
+        if (dead)
+            this.logger.error(logData, 'job dead-lettered');
+        else
+            this.logger.warn(logData, 'job failed — will retry');
+    }
+    /**
+     * Terminal `cancelled` for a job this worker was running (repo `cancel`
+     * only covers pending rows). Guarded on our own lock so a reclaimed stale
+     * job is never clobbered.
+     */
+    async markCancelled(job) {
+        const at = this.now();
+        await this.meta.db
+            .updateTable('adminium_jobs')
+            .set({ status: 'cancelled', finishedAt: at, dedupeKey: null, lockedBy: null, lockedAt: null })
+            .where('id', '=', job.id)
+            .where('status', '=', 'running')
+            .where('lockedBy', '=', this.workerId)
+            .execute();
+        this.hub.publish(jobChannel(job.id), 'cancelled', { jobId: job.id, kind: job.kind }, at);
+        this.logger.info({ jobId: job.id, kind: job.kind }, 'job cancelled');
+    }
+    reportProgress(job, pct, info) {
+        const clamped = Math.max(0, Math.min(100, Math.round(pct)));
+        const progress = { pct: clamped, step: info?.step, message: info?.message };
+        this.setProgress(job.id, progress);
+        this.hub.publish(jobChannel(job.id), 'progress', { pct: clamped, step: info?.step ?? null, message: info?.message ?? null }, this.now());
+    }
+    /** Insertion-ordered map as a tiny LRU: oldest snapshots fall off first. */
+    setProgress(jobId, progress) {
+        this.progressByJob.delete(jobId);
+        this.progressByJob.set(jobId, progress);
+        while (this.progressByJob.size > PROGRESS_RETENTION) {
+            const oldest = this.progressByJob.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.progressByJob.delete(oldest);
+        }
+    }
+}
+/** Resolves `true` when `promise` settles before `ms`, else `false`. */
+async function withTimeout(promise, ms) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise.then(() => true),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(false), ms);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=worker.js.map

package/dist/jobs/worker.js.map

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

package/dist/llm/apply-service.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Server-side apply EXECUTOR (06-llm-assist.md §8.3, T10b).
+ *
+ * The transactional counterpart to the browser-safe pure planner
+ * (`@adminium/llm` `buildApplyPlan`, T10a): it turns a reviewed run + the
+ * accepted suggestion-id set into ordered write descriptors and executes them in
+ * ONE `@adminium/meta` transaction — upserting `adminium_schema_overrides`
+ * (`origin: 'llm'`, `llm_run_id`) and `adminium_pages` (nav groups, template
+ * pages, dashboard pages) per §8.3.
+ *
+ * Architecture (01 §2.3): provider network + prompt building live elsewhere; the
+ * planner is pure and browser-safe; only THIS layer touches the DB. It builds on
+ * T07's run-service (status machine, review persistence) and the T09 diff.
+ *
+ * The three §8.3 invariants it enforces at the write layer:
+ *  - **Provenance (user > llm).** Overrides are upserted through
+ *    {@link llmOverridesRepo}, which only ever reads/writes `origin: 'llm'` rows —
+ *    a user edit is never touched or superseded. The plan additionally excludes
+ *    `user-locked` suggestions (they are computed from the live user overrides
+ *    and fed into the diff), so a locked target produces no descriptor at all.
+ *  - **Idempotency.** Overrides upsert on `(connection, op, table, column)` and
+ *    pages upsert on a deterministic id derived from the suggestion-id, so
+ *    re-applying the same run writes no duplicates and re-applying a NEWER run
+ *    supersedes the prior one (new `llm_run_id`).
+ *  - **Undo.** Every insert/update captures a before-image inside the apply
+ *    transaction; {@link undoApply} reverts exactly this apply in one transaction.
+ *
+ * After a durable apply the optional {@link ApplyServiceDeps.regenerate} hook
+ * runs the existing generation path so pages pick up the new overrides
+ * (localized labels flow through the schema-override i18n layer, never the static
+ * locale bundles — §8.3 / 10-i18n-theming.md).
+ */
+import { type DatabaseModel } from '@adminium/engine';
+import { type ApplyPlan, type ApplyPlanSummary, type SuggestionDiff } from '@adminium/llm';
+import { type LlmOverride, type LlmRun, type LlmRunReview, type MetaDb } from '@adminium/meta';
+import { type RunService } from './run-service.js';
+/** applyRun targeted a run that is not in the `validated` state (§7.4). */
+export declare class RunNotApplicableError extends Error {
+    readonly runId: string;
+    readonly status: string;
+    name: string;
+    constructor(runId: string, status: string);
+}
+/** applyRun targeted a run whose snapshot is missing — validation always needs it (§7.4). */
+export declare class SnapshotNotFoundError extends Error {
+    readonly snapshotId: string;
+    name: string;
+    constructor(snapshotId: string);
+}
+/** Nav-field before-image for a single page (undo of a nav-group re-placement). */
+export interface PageNavBefore {
+    id: string;
+    navGroup: string | null;
+    navOrder: number;
+    updatedAt: number;
+}
+/**
+ * Everything needed to revert exactly one apply in a single transaction. Returned
+ * from {@link ApplyResult.undo} and consumed by {@link undoApply}; the route layer
+ * (T11) parks it in the app-wide undo store and calls back on the toast action.
+ */
+export interface ApplyUndo {
+    connectionId: string;
+    /** Override rows inserted by this apply — undo deletes them. */
+    insertedOverrideIds: string[];
+    /** Override rows superseded by this apply — undo restores these images. */
+    updatedOverrides: LlmOverride[];
+    /** Page rows inserted by this apply — undo deletes them. */
+    insertedPageIds: string[];
+    /** Page rows whose nav placement this apply changed — undo restores these images. */
+    updatedPages: PageNavBefore[];
+}
+export interface ApplyCounts {
+    /** Override rows written (inserted + superseded). */
+    overrides: number;
+    /** Page rows created (template + dashboard). */
+    pages: number;
+    /** Page rows re-placed into a nav group. */
+    navGroupUpdates: number;
+}
+export interface ApplyResult {
+    run: LlmRun;
+    plan: ApplyPlan;
+    summary: ApplyPlanSummary;
+    /** Accepted/rejected suggestion-id lists persisted on the run (§8.3). */
+    review: LlmRunReview;
+    /** True when some actionable suggestion was rejected → `partially_applied`. */
+    partial: boolean;
+    counts: ApplyCounts;
+    undo: ApplyUndo;
+}
+export interface ApplyRunOptions {
+    /** The user performing the apply — stamped on the run + created rows. */
+    appliedBy?: string | null;
+}
+/** Context handed to the post-apply regeneration hook (§8.3 step 3). */
+export interface RegenerateContext {
+    connectionId: string;
+    snapshotId: string;
+    runId: string;
+    appliedBy: string | null;
+}
+export interface ApplyServiceDeps {
+    meta: MetaDb;
+    /** T07 run-service — read the run + drive the applied/partially_applied transition. */
+    runService: RunService;
+    /**
+     * Post-apply regeneration (§8.3 step 3): rerun the existing generation path so
+     * pages reflect the new overrides. Injected (not hard-wired) so the executor
+     * stays testable without a live source connection; the route layer supplies the
+     * `runGeneration`-backed implementation. Generated pages are regenerated;
+     * `origin: 'llm'` pages this apply created are preserved (never pruned).
+     */
+    regenerate?: (ctx: RegenerateContext) => Promise<void> | void;
+    /** Clock override — tests. */
+    now?: () => number;
+}
+/**
+ * Diff rows that are accept/reject units for review accounting (§8.2).
+ * `heuristic-only` (the LLM offered nothing) and `user-locked` (§8.2 provenance:
+ * a user edit is never superseded) are not offered for acceptance at all.
+ */
+export declare const ACTIONABLE_STATUSES: ReadonlySet<SuggestionDiff['status']>;
+/**
+ * The headless form of the review screen's "Accept all ≥ N" bulk control
+ * (§10.3). Lives here, beside {@link ACTIONABLE_STATUSES}, because "which rows
+ * may be accepted" is a diff-semantics question — the CLI's `--yes-above` and
+ * any future bulk-apply caller must not each decide it for themselves.
+ *
+ * Only actionable rows qualify, so a threshold of 0 still cannot accept a
+ * `user-locked` row.
+ */
+export declare function selectAcceptedByConfidence(diff: readonly SuggestionDiff[], minConfidence: number): string[];
+export declare function createApplyService(deps: ApplyServiceDeps): {
+    applyRun: (runId: string, acceptedIds: Iterable<string>, opts?: ApplyRunOptions) => Promise<ApplyResult>;
+    executeApplyPlan: (plan: ApplyPlan, ctx?: {
+        createdBy?: string | null;
+    }) => Promise<{
+        undo: ApplyUndo;
+        counts: ApplyCounts;
+    }>;
+    buildPlanForRun: (run: LlmRun, acceptedIds: Iterable<string>) => Promise<{
+        plan: ApplyPlan;
+        diff: SuggestionDiff[];
+        model: DatabaseModel;
+    }>;
+    undoApply: (undo: ApplyUndo) => Promise<void>;
+};
+export type ApplyService = ReturnType<typeof createApplyService>;
+//# sourceMappingURL=apply-service.d.ts.map

package/dist/llm/apply-service.d.ts.map

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