@pikku/queue-pg-boss 0.12.9 → 0.12.11

package/CHANGELOG.md

@@ -1,3 +1,131 @@
+## 0.12.11
+
+### Patch Changes
+
+- 4c7a1b5: Run the monorepo's own scripts through bun instead of yarn. What moves is the
+  package manager each package's `prepublishOnly` and build scripts invoke, plus
+  the two manifest fixes bun needs to resolve the tree: `uWebSockets.js` is
+  declared with an explicit `github:` specifier, and `@pikku/uws-handler` marks
+  its `uWebSockets.js` peer optional so a bun install of a consumer that brings
+  its own uWS app does not try to fetch it from the registry.
+
+  Three published behaviours change, all of them cases where an isolated
+  `node_modules` or bun as the runtime had been papered over by yarn's hoisting:
+
+  - `@pikku/migrator-sql` turns foreign keys on when it opens a sqlite database
+    through bun. `node:sqlite` enforces them by default and `bun:sqlite` does not,
+    which silently turned every `ON DELETE CASCADE` into a no-op under
+    `bunx --bun pikku`.
+  - `@pikku/cli` resolves a deploy provider against the project being deployed
+    rather than against wherever the CLI itself is installed, which is what its
+    own "is not installed" error asks the user to arrange.
+  - `@pikku/cli` treats a specifier a runtime hands straight back — bun does this
+    for the modules it implements itself — as not resolved from the project, so
+    it falls back rather than loading the runtime's own copy.
+
+- Updated dependencies [4c7a1b5]
+  - @pikku/core@0.12.108
+
+## 0.12.10
+
+### Patch Changes
+
+- 266e3bc: One door per name: `@pikku/core/ecosystem/*` and the package root are gone
+
+  `@pikku/core` published every module twice. `ecosystem/http` re-exported
+  `./http`, `ecosystem/services` re-exported `./services`, and a name was
+  reachable through either — so every addition had to be made in two places, and a
+  consumer's import said nothing about what it actually used. The package root was
+  the same problem at a larger scale: a single barrel of 206 names that no bundler
+  could take apart, and the one specifier that revealed nothing at all.
+
+  Both are deleted. Every name now lives on the subpath that owns it, and every
+  import carries that subpath — `@pikku/core/http`, `@pikku/core/services`,
+  `@pikku/core/errors`, `@pikku/core/types`.
+
+  Deleting the facades meant the raw subpaths had to become a superset of them,
+  which they were not: the facade tree had accumulated 25 names with no raw home
+  and about 26 more filed under a different area than the module they came from.
+  Those names moved to the area that owns them, and three areas were published as
+  new entry points rather than left on a root that is going away — `./types` (the
+  shared type surface, the largest single destination), `./state` and
+  `./classification`.
+
+  `./classification` is one door onto one subject: what a value is and how it must
+  be handled. Its three halves would each have been an entry point — the brands
+  and manifest types, the stored-form helpers (`hashToken`, `unsafeAsSealed` and
+  friends), and `SecretValue` — split by whether a name happens to be a type or a
+  value, which is the same defect as the facades. The duration and versioned-id
+  helpers went to `./utils`, which already published, and `PikkuRequest` went to
+  `./function`: it is the transport-agnostic request base, not an HTTP one — HTTP
+  has `PikkuHTTPAbstractRequest`, and the only thing outside core that extends
+  `PikkuRequest` is Azure's timer request.
+
+  `./types` inherited the root barrel's habit before it inherited its contents, so
+  the names with an owner elsewhere were moved off it. The middleware types and the
+  five middleware factories — `pikkuMiddleware`, `pikkuMiddlewareFactory`,
+  `pikkuChannelMiddleware`, `pikkuChannelMiddlewareFactory` and
+  `pikkuAgentMiddleware`, runtime values on a types entry point — are now
+  `@pikku/core/middleware`; the function meta types are `@pikku/core/function`;
+  `SerializedError` is `@pikku/core/errors`; and the generic TypeScript helpers
+  (`MakeRequired`, `PickRequired`, `PickOptional`, `RequireAtLeastOne`,
+  `JSONPrimitive`, `JSONValue`) are `@pikku/core/utils`. What is left on `./types`
+  is the vocabulary the wirings share, which no single module owns.
+
+  `pikku` was itself a root barrel — `export * from '@pikku/core'` — and
+  now exports only the services it bundles.
+
+  One module survives at the old specifier, and only for the bootstrap:
+  `packages/cli` is generated by the _published_ CLI pinned in its `build.sh`, and
+  that CLI still writes a bare `@pikku/core` into the files it generates for the
+  CLI itself. `bootstrap-compat/root.ts` carries the eight types it names, a test
+  in core fails if that list grows, and it goes when the pin moves to a CLI
+  released from this branch. The adapter names the pinned CLI reaches for —
+  `pikkuState` and `CreateWireServices` — are rewritten to `@pikku/core/state` and
+  `@pikku/core/types` by the same `build.sh` patch pass, so no second shim is
+  needed for them.
+
+  A guard test keeps the root shut: it parses imports and rejects a bare
+  `@pikku/core` rather than grepping for it, because several tests hold a user's
+  file as a template literal, where `import … from '@pikku/core'` is fixture text
+  rather than an import this repo makes.
+
+  An agent scaffold a project generated under an older CLI is refreshed rather
+  than left to fail: `pikku all` already deleted one importing an entry point
+  `@pikku/core` no longer publishes, and the `#pikku` hub joins that list.
+  Without it a project that scaffolds the agent endpoint but
+  declares no agents keeps the old file forever — the generator that would rewrite
+  it only runs when agents exist, and the file being present is what stops it
+  being regenerated as missing.
+
+  `pikku new addon` also wrote a tsconfig `paths` map naming only the deleted hub.
+  An addon's `imports` map points into `dist`, so `paths` is what resolves
+  `#pikku/<leaf>` for the addon's own source build — it now names the two leaf
+  patterns, in both the addon and its test harness.
+
+- 6eef0a0: Bump every dependency to its latest compatible minor/patch across the monorepo.
+- Updated dependencies [7722ceb]
+- Updated dependencies [375c1ff]
+- Updated dependencies [02a70cd]
+- Updated dependencies [aeef159]
+- Updated dependencies [a281de6]
+- Updated dependencies [266e3bc]
+- Updated dependencies [02a70cd]
+- Updated dependencies [786dae5]
+- Updated dependencies [6eef0a0]
+- Updated dependencies [3561d67]
+- Updated dependencies [a91c433]
+- Updated dependencies [02a70cd]
+- Updated dependencies [9537f74]
+- Updated dependencies [2b57ca8]
+- Updated dependencies [266e3bc]
+- Updated dependencies [9fce0f1]
+- Updated dependencies [83683a0]
+- Updated dependencies [456c88b]
+- Updated dependencies [456c88b]
+- Updated dependencies [c127273]
+  - @pikku/core@0.12.85
+
 ## 0.12.9
 
 ### Patch Changes

package/dist/index.d.ts

@@ -8,5 +8,5 @@ export { PgBossServiceFactory } from './pg-boss-service-factory.js';
 export { PgBossQueueService } from './pg-boss-queue-service.js';
 export { PgBossQueueWorkers } from './pg-boss-queue-worker.js';
 export { PgBossSchedulerService } from './pg-boss-scheduler-service.js';
-export type { QueueService, QueueJob } from '@pikku/core/queue';
-export type { PikkuWorkerConfig, PikkuJobConfig, JobOptions, } from '@pikku/core/ecosystem/queue';
+export type { QueueJob, QueueService } from '@pikku/core/queue';
+export type { PikkuWorkerConfig, PikkuJobConfig, JobOptions, } from '@pikku/core/queue';

package/dist/pg-boss-queue-service.d.ts

@@ -1,7 +1,7 @@
 import type { PgBoss, Request as PgBossRequest } from 'pg-boss';
-import type { QueueService, QueueJob } from '@pikku/core/queue';
-import type { JobOptions } from '@pikku/core/ecosystem/queue';
-export declare const mapPikkuJobToPgBoss: (options?: JobOptions) => PgBossRequest["options"];
+import type { QueueJob, QueueService } from '@pikku/core/queue';
+import type { JobOptions } from '@pikku/core/queue';
+export declare const mapPikkuJobToPgBoss: (options?: JobOptions) => PgBossRequest['options'];
 /**
  * pg-boss/PostgreSQL queue service implementation
  * Supports job results, retries, and PostgreSQL-based queuing

package/dist/pg-boss-queue-worker.d.ts

@@ -1,5 +1,5 @@
 import type { PgBoss, WorkOptions } from 'pg-boss';
-import type { QueueWorkers, PikkuWorkerConfig, QueueConfigMapping, ConfigValidationResult } from '@pikku/core/ecosystem/queue';
+import type { QueueWorkers, PikkuWorkerConfig, QueueConfigMapping, ConfigValidationResult } from '@pikku/core/queue';
 import type { Logger } from '@pikku/core/services';
 export declare const mapPikkuWorkerToPgBoss: (workerConfig?: PikkuWorkerConfig) => WorkOptions;
 /**

package/dist/pg-boss-queue-worker.js

@@ -1,6 +1,6 @@
 import { runQueueJob } from '@pikku/core/queue';
-import { registerQueueWorkers, QueueJobFailedError, QueueJobDiscardedError, } from '@pikku/core/ecosystem/queue';
-import { pikkuState } from '@pikku/core/ecosystem';
+import { registerQueueWorkers, QueueJobFailedError, QueueJobDiscardedError, } from '@pikku/core/queue';
+import { pikkuState } from '@pikku/core/state';
 import { mapPgBossJobToQueueJob } from './utils.js';
 export const mapPikkuWorkerToPgBoss = (workerConfig) => {
     // Map the requested parallelism to pg-boss `localConcurrency` (independent

package/dist/pg-boss-scheduler-service.d.ts

@@ -1,7 +1,7 @@
 import type { PgBoss } from 'pg-boss';
-import type { CoreUserSession } from '@pikku/core';
-import type { ScheduledTaskInfo, ScheduledTaskSummary } from '@pikku/core/ecosystem/services';
-import { SchedulerService } from '@pikku/core';
+import { SchedulerService } from '@pikku/core/services';
+import type { CoreUserSession } from '@pikku/core/types';
+import type { ScheduledTaskInfo, ScheduledTaskSummary } from '@pikku/core/services';
 /**
  * pg-boss scheduler service implementation
  * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL.

package/dist/pg-boss-scheduler-service.js

@@ -1,8 +1,8 @@
-import { SchedulerService } from '@pikku/core';
-import { parseDurationString } from '@pikku/core/ecosystem/types';
-import { pikkuState } from '@pikku/core/ecosystem';
 import { runScheduledTask } from '@pikku/core/scheduler';
-import { getScheduledTasks } from '@pikku/core/ecosystem/scheduler';
+import { SchedulerService } from '@pikku/core/services';
+import { parseDurationString } from '@pikku/core/utils';
+import { pikkuState } from '@pikku/core/state';
+import { getScheduledTasks } from '@pikku/core/scheduler';
 /** Prefix for pg-boss queues/schedules backing recurring scheduled tasks. */
 const RECURRING_TASK_PREFIX = 'pikku-recurring-scheduled-task_';
 /**

package/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@pikku/queue-pg-boss",
-  "version": "0.12.9",
+  "version": "0.12.11",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pikkujs/pikku.git",
+    "directory": "packages/services/queue-pg-boss"
+  },
   "description": "pg-boss queue, worker and scheduler services for Pikku, backed by Postgres",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -13,16 +18,13 @@
     "ncu": "npx npm-check-updates",
     "build": "tsc -b",
     "release": "npm run build && npm test",
-    "prepublishOnly": "yarn build"
+    "prepublishOnly": "bun run build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.84"
+    "@pikku/core": "^0.12.108"
   },
   "dependencies": {
-    "pg-boss": "^12.14.0"
-  },
-  "devDependencies": {
-    "typescript": "^6.0.3"
+    "pg-boss": "^12.27.0"
   },
   "exports": {
     ".": "./dist/index.js"

package/run-tests.sh

@@ -1,8 +1,5 @@
 #!/bin/bash
 
-script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$script_dir"
-
 # Enable nullglob to handle cases where no files match the pattern
 shopt -s nullglob
 
@@ -37,20 +34,35 @@ files=($(find src -type f -name "*.test.ts"))
 # Check if any files matched the pattern
 if [ ${#files[@]} -eq 0 ]; then
   echo "No test files found matching pattern: $pattern"
+  if [ "${STRICT_TEST_DISCOVERY}" = "1" ]; then
+    exit 1
+  fi
   exit 0
 fi
 
-# Construct the node command
-node_cmd=(node --import tsx --test)
+# Construct the bun command
+#
+# --parallel gives every test file its own worker process, which is what node's
+# `--test` did. Several suites keep module-level caches (a TypeScript program, a
+# temp fixture directory) that a shared process would leak between files.
+#
+# --timeout because bun caps a test at 5s by default where node had no cap, and
+# the suites that build real TypeScript programs run well past that.
+bun_cmd=(bun test --parallel --timeout 120000)
 
 # Append options based on flags
 if [ "$watch_mode" = true ]; then
-  node_cmd+=(--watch)
+  # --watch reruns in one process; parallel workers have nothing to watch.
+  bun_cmd=(bun test --watch --timeout 120000)
 fi
 
 if [ "$coverage_mode" = true ]; then
-  node_cmd+=(--test-coverage-include="src/**/*.{ts,js}" --test-coverage-exclude="**/dist/**" --experimental-test-coverage --test-reporter=lcov --test-reporter-destination=lcov.info)
+  # --coverage-dir=. keeps lcov.info at the package root: CI merges every
+  # package's report by prefixing its SF paths with the file's own directory,
+  # so a nested coverage/ directory would re-root them one level too deep.
+  bun_cmd+=(--coverage --coverage-reporter=lcov --coverage-reporter=text --coverage-dir=.)
+  export PIKKU_TEST_COVERAGE=1
 fi
 
-# Execute the node command with the expanded list of files
-"${node_cmd[@]}" "${files[@]}"
+# Execute the bun command with the expanded list of files
+"${bun_cmd[@]}" "${files[@]}"

package/src/index.ts

@@ -1,19 +0,0 @@
-/**
- * @module @pikku/queue-pg-boss
- *
- * PostgreSQL queue service for Pikku using pg-boss
- * Provides job results, retries, priorities, and PostgreSQL-based queuing
- */
-
-export { PgBossServiceFactory } from './pg-boss-service-factory.js'
-export { PgBossQueueService } from './pg-boss-queue-service.js'
-export { PgBossQueueWorkers } from './pg-boss-queue-worker.js'
-export { PgBossSchedulerService } from './pg-boss-scheduler-service.js'
-
-// Re-export core queue types for convenience
-export type { QueueService, QueueJob } from '@pikku/core/queue'
-export type {
-  PikkuWorkerConfig,
-  PikkuJobConfig,
-  JobOptions,
-} from '@pikku/core/ecosystem/queue'

package/src/pg-boss-queue-service.test.ts

@@ -1,78 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import { mapPikkuJobToPgBoss } from './pg-boss-queue-service.js'
-
-// These guard the contract the workflow engine relies on: a step's resolved
-// retry policy (attempts + backoff) must survive translation into pg-boss
-// terms, so "workflow owns retries" actually reaches the queue.
-describe('mapPikkuJobToPgBoss — retry mapping', () => {
-  test('attempts → retryLimit (attempts - 1)', () => {
-    // Default policy: 5 retries → 6 attempts → retryLimit 5.
-    assert.equal(mapPikkuJobToPgBoss({ attempts: 6 }).retryLimit, 5)
-  })
-
-  test('attempts: 1 (retries: 0) → retryLimit 0 (pg-boss never re-runs it)', () => {
-    assert.equal(mapPikkuJobToPgBoss({ attempts: 1 }).retryLimit, 0)
-  })
-
-  test("backoff 'exponential' → retryBackoff true + 1s base delay", () => {
-    const opts = mapPikkuJobToPgBoss({ attempts: 6, backoff: 'exponential' })
-    assert.equal(opts.retryBackoff, true)
-    // pg-boss multiplies retry_delay by 2^n and the queue default is 0 —
-    // without a base, "exponential" retries all fire immediately.
-    assert.equal(opts.retryDelay, 1)
-  })
-
-  test('sub-second fixed delay rounds up to 1s, not down to immediate', () => {
-    const opts = mapPikkuJobToPgBoss({
-      attempts: 4,
-      backoff: { type: 'fixed', delay: 300 },
-    })
-    assert.equal(opts.retryDelay, 1)
-  })
-
-  test('fixed backoff → retryBackoff false + retryDelay in seconds', () => {
-    const opts = mapPikkuJobToPgBoss({
-      attempts: 4,
-      backoff: { type: 'fixed', delay: 5000 },
-    })
-    assert.equal(opts.retryBackoff, false)
-    // pg-boss takes seconds; our delay is milliseconds.
-    assert.equal(opts.retryDelay, 5)
-  })
-
-  test('exponential object backoff → retryBackoff true + retryDelay in seconds', () => {
-    const opts = mapPikkuJobToPgBoss({
-      attempts: 4,
-      backoff: { type: 'exponential', delay: 2000 },
-    })
-    assert.equal(opts.retryBackoff, true)
-    assert.equal(opts.retryDelay, 2)
-  })
-
-  test('no options → no retry fields set', () => {
-    const opts = mapPikkuJobToPgBoss(undefined)
-    assert.equal(opts.retryLimit, undefined)
-    assert.equal(opts.retryBackoff, undefined)
-  })
-})
-
-describe('mapPikkuJobToPgBoss — group mapping', () => {
-  test('group id is forwarded so the worker can enforce a per-group limit', () => {
-    assert.deepEqual(mapPikkuJobToPgBoss({ group: { id: 'deployWorkflow' } })
-      .group, { id: 'deployWorkflow' })
-  })
-
-  test('tier is only set when provided', () => {
-    const opts = mapPikkuJobToPgBoss({
-      group: { id: 'deployWorkflow', tier: 'slow' },
-    })
-    assert.deepEqual(opts.group, { id: 'deployWorkflow', tier: 'slow' })
-    assert.equal('tier' in mapPikkuJobToPgBoss({ group: { id: 'a' } }).group!, false)
-  })
-
-  test('no group → no group field', () => {
-    assert.equal(mapPikkuJobToPgBoss({ attempts: 2 }).group, undefined)
-  })
-})

package/src/pg-boss-queue-service.ts

@@ -1,113 +0,0 @@
-import type { PgBoss, Request as PgBossRequest } from 'pg-boss'
-import type { QueueService, QueueJob } from '@pikku/core/queue'
-import type { JobOptions } from '@pikku/core/ecosystem/queue'
-import { mapPgBossJobToQueueJob } from './utils.js'
-
-export const mapPikkuJobToPgBoss = (
-  options?: JobOptions
-): PgBossRequest['options'] => {
-  const pgBossOptions: any = {}
-
-  if (options?.priority !== undefined) {
-    pgBossOptions.priority = options.priority
-  }
-
-  if (options?.delay !== undefined) {
-    pgBossOptions.startAfter = new Date(Date.now() + options.delay)
-  }
-
-  if (options?.jobId !== undefined) {
-    pgBossOptions.singletonKey = options.jobId
-  }
-
-  if (options?.group !== undefined) {
-    pgBossOptions.group = {
-      id: options.group.id,
-      ...(options.group.tier !== undefined ? { tier: options.group.tier } : {}),
-    }
-  }
-
-  // Map retry options
-  if (options?.attempts !== undefined) {
-    pgBossOptions.retryLimit = options.attempts - 1
-  }
-
-  if (options?.backoff !== undefined) {
-    const type =
-      typeof options.backoff === 'string'
-        ? options.backoff
-        : options.backoff.type
-    const delay =
-      typeof options.backoff === 'object' ? options.backoff.delay : undefined
-    pgBossOptions.retryBackoff = type === 'exponential'
-    if (delay !== undefined) {
-      // pg-boss uses seconds, we use milliseconds — never round a sub-second
-      // delay down to 0, which pg-boss treats as retry-immediately
-      pgBossOptions.retryDelay = Math.max(1, Math.round(delay / 1000))
-    } else if (type === 'exponential') {
-      // pg-boss computes exponential backoff as retry_delay * 2^n, and the
-      // queue-level retry_delay defaults to 0 — without an explicit base every
-      // "exponential" retry fires immediately. 1s base → ~1s, 2s, 4s, 8s…
-      pgBossOptions.retryDelay = 1
-    }
-  }
-
-  if (options?.removeOnComplete !== undefined) {
-    pgBossOptions.onComplete = options.removeOnComplete === 0
-  }
-
-  if (options?.removeOnFail !== undefined) {
-    // pg-boss doesn't have a direct equivalent, but we can track this for consistency
-    // Note: pg-boss keeps failed jobs by default
-  }
-
-  return pgBossOptions as PgBossRequest['options']
-}
-
-/**
- * pg-boss/PostgreSQL queue service implementation
- * Supports job results, retries, and PostgreSQL-based queuing
- */
-export class PgBossQueueService implements QueueService {
-  readonly name = 'pg-boss'
-  readonly supportsResults = true
-  protected pgBoss: PgBoss
-
-  constructor(pgBoss: PgBoss) {
-    this.pgBoss = pgBoss
-  }
-
-  /**
-   * Add a job to the queue
-   */
-  public async add<In>(
-    queueName: string,
-    data: In,
-    options?: JobOptions
-  ): Promise<string> {
-    await this.pgBoss.createQueue(queueName)
-    const jobId = await this.pgBoss.send(
-      queueName,
-      data as any,
-      mapPikkuJobToPgBoss(options)
-    )
-    if (!jobId) {
-      throw new Error('Failed to create job')
-    }
-    return jobId
-  }
-
-  /**
-   * Get job by ID
-   */
-  async getJob<T, R>(
-    queueName: string,
-    jobId: string
-  ): Promise<QueueJob<T, R> | null> {
-    const job = await this.pgBoss.getJobById<T>(queueName, jobId)
-    if (!job) {
-      return null
-    }
-    return mapPgBossJobToQueueJob<T, R>(job, this.pgBoss)
-  }
-}

package/src/pg-boss-queue-worker.test.ts

@@ -1,93 +0,0 @@
-import { describe, test } from 'node:test'
-import assert from 'node:assert/strict'
-
-import {
-  PgBossQueueWorkers,
-  mapPikkuWorkerToPgBoss,
-} from './pg-boss-queue-worker.js'
-
-describe('PgBossQueueWorkers', () => {
-  test('requires a logger (explicit or from singleton services)', async () => {
-    const workers = new PgBossQueueWorkers({} as any)
-
-    await assert.rejects(() => workers.registerQueues(), {
-      message:
-        'Logger is required for registerQueues — pass it explicitly or ensure singleton services are initialized first',
-    })
-  })
-})
-
-describe('mapPikkuWorkerToPgBoss', () => {
-  test('parallelism maps to independent workers (localConcurrency), never batch fetching', () => {
-    // batchSize: 1 keeps each worker single-job so a slow job can never hold its
-    // batch siblings — head-of-line blocking is impossible.
-    assert.deepEqual(mapPikkuWorkerToPgBoss(), {
-      localConcurrency: 10,
-      batchSize: 1,
-    })
-
-    assert.deepEqual(mapPikkuWorkerToPgBoss({ batchSize: 25 }), {
-      localConcurrency: 25,
-      batchSize: 1,
-    })
-  })
-
-  test('pollInterval is converted from ms to seconds', () => {
-    assert.deepEqual(mapPikkuWorkerToPgBoss({ pollInterval: 3000 }), {
-      localConcurrency: 10,
-      batchSize: 1,
-      pollingIntervalSeconds: 3,
-    })
-  })
-
-  test('groupConcurrency caps how much of the worker one group can take', () => {
-    assert.deepEqual(mapPikkuWorkerToPgBoss({ groupConcurrency: 2 }), {
-      localConcurrency: 10,
-      batchSize: 1,
-      localGroupConcurrency: 2,
-    })
-  })
-
-  test('tiered groupConcurrency passes tiers through', () => {
-    assert.deepEqual(
-      mapPikkuWorkerToPgBoss({
-        batchSize: 20,
-        groupConcurrency: { default: 2, tiers: { slowWorkflow: 1 } },
-      }),
-      {
-        localConcurrency: 20,
-        batchSize: 1,
-        localGroupConcurrency: { default: 2, tiers: { slowWorkflow: 1 } },
-      }
-    )
-  })
-
-  test('group limits are clamped to the worker concurrency', () => {
-    // pg-boss asserts every group limit is <= localConcurrency and throws at
-    // worker start otherwise — clamp so an over-eager config degrades to "this
-    // group may use the whole worker" instead of failing to start.
-    assert.deepEqual(
-      mapPikkuWorkerToPgBoss({
-        batchSize: 4,
-        groupConcurrency: { default: 10, tiers: { greedy: 99 } },
-      }),
-      {
-        localConcurrency: 4,
-        batchSize: 1,
-        localGroupConcurrency: { default: 4, tiers: { greedy: 4 } },
-      }
-    )
-
-    assert.deepEqual(
-      mapPikkuWorkerToPgBoss({ batchSize: 3, groupConcurrency: 8 }),
-      { localConcurrency: 3, batchSize: 1, localGroupConcurrency: 3 }
-    )
-  })
-
-  test('no group config means no group limits', () => {
-    assert.equal(
-      'localGroupConcurrency' in mapPikkuWorkerToPgBoss({ batchSize: 5 }),
-      false
-    )
-  })
-})

package/src/pg-boss-queue-worker.ts

@@ -1,231 +0,0 @@
-import type { PgBoss, WorkOptions } from 'pg-boss'
-import type {
-  QueueWorkers,
-  PikkuWorkerConfig,
-  QueueConfigMapping,
-  ConfigValidationResult,
-} from '@pikku/core/ecosystem/queue'
-import { runQueueJob } from '@pikku/core/queue'
-import {
-  registerQueueWorkers,
-  QueueJobFailedError,
-  QueueJobDiscardedError,
-} from '@pikku/core/ecosystem/queue'
-import { pikkuState } from '@pikku/core/ecosystem'
-import type { Logger } from '@pikku/core/services'
-import { mapPgBossJobToQueueJob } from './utils.js'
-
-export const mapPikkuWorkerToPgBoss = (
-  workerConfig?: PikkuWorkerConfig
-): WorkOptions => {
-  // Map the requested parallelism to pg-boss `localConcurrency` (independent
-  // per-job workers), NOT `batchSize`. A batch worker hands the whole fetched
-  // batch to one handler and only fetches again once that handler resolves — so
-  // a single slow job blocks every sibling in its batch AND stalls the next
-  // fetch. On a shared queue that is head-of-line blocking: one long job can
-  // freeze the entire worker and starve everything queued behind it.
-  // `localConcurrency` spawns N pollers that each fetch+process a single job and
-  // refill the instant they finish, so a slow job never holds up the others.
-  const localConcurrency = workerConfig?.batchSize ?? 10
-  const workerOptions: WorkOptions = {
-    localConcurrency,
-    batchSize: 1,
-  }
-
-  if (workerConfig?.pollInterval !== undefined) {
-    workerOptions.pollingIntervalSeconds = Math.round(
-      workerConfig.pollInterval / 1000
-    )
-  }
-
-  // Per-group fairness. `localGroupConcurrency` is in-memory and free — groups
-  // already at capacity are excluded from the fetch itself, so an at-capacity
-  // group costs nothing rather than being fetched and restored. pg-boss asserts
-  // every limit is <= localConcurrency, so clamp instead of letting a config
-  // that reads as "let this tier use more" throw at worker start.
-  if (workerConfig?.groupConcurrency !== undefined) {
-    const clamp = (limit: number) => Math.min(limit, localConcurrency)
-    workerOptions.localGroupConcurrency =
-      typeof workerConfig.groupConcurrency === 'number'
-        ? clamp(workerConfig.groupConcurrency)
-        : {
-            default: clamp(workerConfig.groupConcurrency.default),
-            ...(workerConfig.groupConcurrency.tiers
-              ? {
-                  tiers: Object.fromEntries(
-                    Object.entries(workerConfig.groupConcurrency.tiers).map(
-                      ([tier, limit]) => [tier, clamp(limit)]
-                    )
-                  ),
-                }
-              : {}),
-          }
-  }
-
-  return workerOptions
-}
-
-/**
- * pg-boss/PostgreSQL queue worker implementation
- * Supports job results, retries, and PostgreSQL-based queuing
- */
-export class PgBossQueueWorkers implements QueueWorkers {
-  readonly name = 'pg-boss'
-  readonly supportsResults = true
-
-  /**
-   * Configuration mapping rules for pg-boss
-   * This defines how Pikku worker configs map to pg-boss configurations
-   */
-  readonly configMappings: QueueConfigMapping = {
-    // Configurations that are directly supported
-    supported: {
-      batchSize: {
-        queueProperty: 'localConcurrency',
-        description: 'Number of jobs to process concurrently',
-      },
-      groupConcurrency: {
-        queueProperty: 'localGroupConcurrency',
-        description:
-          'Maximum concurrent jobs per group, keeping one shared queue fair across groups',
-      },
-      pollInterval: {
-        queueProperty: 'pollingIntervalSeconds',
-        transform: (value: number) => Math.round(value / 1000),
-        description:
-          'How often to poll for new jobs (converted from ms to seconds)',
-      },
-    },
-
-    // Configurations that are not supported but have reasonable explanations
-    unsupported: {
-      name: {
-        reason: 'Worker names are not supported in pg-boss',
-        explanation:
-          'pg-boss identifies workers by their queue name and process, not custom names',
-      },
-      autorun: {
-        reason: 'Autorun is not configurable in pg-boss (always enabled)',
-        explanation:
-          'pg-boss workers automatically start processing when created',
-      },
-      lockDuration: {
-        reason: 'Lock duration is managed differently in pg-boss',
-        explanation:
-          'pg-boss uses job-level expiration instead of worker-level locks',
-      },
-      drainDelay: {
-        reason: 'Drain delay is not configurable in pg-boss',
-        explanation: 'pg-boss handles graceful shutdown internally',
-      },
-      maxStalledCount: {
-        reason: 'Max stalled count is not configurable in pg-boss',
-        explanation:
-          'pg-boss handles stalled jobs through its built-in retry mechanism',
-      },
-      prefetch: {
-        reason: 'Prefetch is managed internally by pg-boss',
-        explanation:
-          'pg-boss optimizes job fetching automatically based on batch size',
-      },
-      visibilityTimeout: {
-        reason: "Visibility timeout concept doesn't apply to pg-boss",
-        explanation:
-          'pg-boss uses PostgreSQL locks and job expiration instead of visibility timeout',
-      },
-    },
-
-    // Configurations that have partial support or workarounds
-    fallbacks: {
-      removeOnComplete: {
-        reason: 'Job retention is managed through pg-boss archival system',
-        explanation:
-          'pg-boss automatically archives completed jobs based on database settings',
-        fallbackValue: 'Managed by pg-boss database archival',
-      },
-      removeOnFail: {
-        reason:
-          'Failed job retention is managed through pg-boss archival system',
-        explanation:
-          'pg-boss automatically archives failed jobs based on database settings',
-        fallbackValue: 'Managed by pg-boss database archival',
-      },
-    },
-  }
-
-  private pgBoss: PgBoss
-  private activeWorkers = new Map<string, string>()
-
-  constructor(pgBoss: PgBoss) {
-    this.pgBoss = pgBoss
-  }
-
-  /**
-   * Scan state and register all compatible processors
-   */
-  async registerQueues(
-    logger?: Logger
-  ): Promise<Record<string, ConfigValidationResult[]>> {
-    if (!logger) {
-      logger = pikkuState(null, 'package', 'singletonServices')?.logger
-    }
-    if (!logger) {
-      throw new Error(
-        'Logger is required for registerQueues — pass it explicitly or ensure singleton services are initialized first'
-      )
-    }
-
-    return await registerQueueWorkers(
-      this.configMappings,
-      logger,
-      async (queueName, processor) => {
-        await this.pgBoss.createQueue(queueName)
-        const workerId = await this.pgBoss.work<any>(
-          processor.name,
-          {
-            ...mapPikkuWorkerToPgBoss(processor.config),
-            includeMetadata: true,
-          },
-          async (jobs) => {
-            if (!jobs || jobs.length === 0) {
-              logger.warn(`No jobs received for queue ${queueName}`)
-              return
-            }
-            // Process all jobs in parallel
-            await Promise.all(
-              jobs.map(async (job) => {
-                try {
-                  await runQueueJob({
-                    job: mapPgBossJobToQueueJob(job, this.pgBoss),
-                  })
-                } catch (error: unknown) {
-                  if (error instanceof QueueJobFailedError) {
-                    // Mark this specific job as failed
-                    await this.pgBoss.fail(queueName, job.id, {
-                      message: error.message,
-                    })
-                  } else if (error instanceof QueueJobDiscardedError) {
-                    // For pg-boss, complete the job successfully to discard it
-                    logger.info(
-                      `PgBoss job ${job.id} discarded: ${error.message}`
-                    )
-                    await this.pgBoss.complete(queueName, job.id)
-                  } else {
-                    // For other errors, fail the job
-                    await this.pgBoss.fail(queueName, job.id, {
-                      message:
-                        error instanceof Error
-                          ? error.message
-                          : 'Unknown error',
-                    })
-                  }
-                }
-              })
-            )
-          }
-        )
-        this.activeWorkers.set(queueName, workerId)
-      }
-    )
-  }
-}

package/src/pg-boss-scheduler-service.ts

@@ -1,192 +0,0 @@
-import type { PgBoss } from 'pg-boss'
-import type { CoreUserSession } from '@pikku/core'
-import type {
-  ScheduledTaskInfo,
-  ScheduledTaskSummary,
-} from '@pikku/core/ecosystem/services'
-import { SchedulerService } from '@pikku/core'
-import { parseDurationString } from '@pikku/core/ecosystem/types'
-import { pikkuState } from '@pikku/core/ecosystem'
-import { runScheduledTask } from '@pikku/core/scheduler'
-import { getScheduledTasks } from '@pikku/core/ecosystem/scheduler'
-
-/**
- * Data stored in scheduled job
- */
-interface ScheduledJobData {
-  rpcName: string
-  data?: any
-  session?: CoreUserSession
-}
-
-/** Prefix for pg-boss queues/schedules backing recurring scheduled tasks. */
-const RECURRING_TASK_PREFIX = 'pikku-recurring-scheduled-task_'
-
-/**
- * pg-boss scheduler service implementation
- * Uses pg-boss's schedule() API to store recurring jobs in PostgreSQL.
- * Handles both one-off delayed RPCs and recurring cron-scheduled tasks.
- */
-export class PgBossSchedulerService extends SchedulerService {
-  private scheduledCronNames: string[] = []
-
-  constructor(private pgBoss: PgBoss) {
-    super()
-  }
-
-  /**
-   * Initialize - no-op as pg-boss is already initialized by factory
-   */
-  async init(): Promise<void> {
-    // No-op - pg-boss is already initialized by factory
-  }
-
-  /**
-   * Schedule a one-off delayed RPC call
-   * Uses pg-boss send() with startAfter for one-time execution
-   */
-  async scheduleRPC(
-    delay: number | string,
-    rpcName: string,
-    data?: any,
-    session?: CoreUserSession
-  ): Promise<string> {
-    // Parse delay if it's a string
-    const delayMs =
-      typeof delay === 'string' ? parseDurationString(delay) : delay
-
-    const jobData: ScheduledJobData = {
-      rpcName,
-      data,
-      session,
-    }
-
-    // Use send() with startAfter for one-off delayed execution
-    const taskId = await this.pgBoss.send(
-      'pikku-remote-internal-rpc',
-      jobData,
-      {
-        startAfter: new Date(Date.now() + delayMs),
-        singletonKey: `${rpcName}-${Date.now()}`, // Ensure uniqueness
-      }
-    )
-
-    if (!taskId) {
-      throw new Error('Failed to schedule RPC')
-    }
-
-    return taskId
-  }
-
-  /**
-   * Unschedule (cancel) a task by ID
-   */
-  async unschedule(taskId: string): Promise<boolean> {
-    await this.pgBoss.cancel('pikku-remote-internal-rpc', taskId)
-    return true
-  }
-
-  /**
-   * Get a scheduled task by ID with full details
-   */
-  async getTask(taskId: string): Promise<ScheduledTaskInfo | null> {
-    const job = await this.pgBoss.getJobById(
-      'pikku-remote-internal-rpc',
-      taskId
-    )
-
-    if (!job) {
-      return null
-    }
-
-    const jobData = job.data as ScheduledJobData
-
-    return {
-      taskId: job.id,
-      rpcName: jobData.rpcName,
-      scheduledFor: job.startAfter || job.createdOn,
-      data: jobData.data,
-      session: jobData.session,
-      status: job.state as any,
-    }
-  }
-
-  /**
-   * Get all scheduled tasks with minimal info
-   */
-  async getAllTasks(): Promise<ScheduledTaskSummary[]> {
-    // pg-boss doesn't have a simple way to list all pending jobs
-    // This would require querying the database directly or maintaining a separate index
-    // For now, return empty array - can be implemented if needed
-    return []
-  }
-
-  /**
-   * Close - no-op as pg-boss lifecycle is managed by factory
-   */
-  async close(): Promise<void> {
-    // No-op - pg-boss lifecycle is managed by factory
-  }
-
-  /**
-   * Start recurring scheduled tasks.
-   * Registers a pg-boss worker to process recurring jobs via runScheduledTask.
-   */
-  async start(): Promise<void> {
-    const logger = pikkuState(null, 'package', 'singletonServices')!.logger
-    const scheduledTasks = getScheduledTasks()
-
-    const expectedCronNames = new Set<string>()
-    for (const [name, task] of scheduledTasks) {
-      const cronName = `${RECURRING_TASK_PREFIX}${name.replace(/[^a-zA-Z0-9_\-.]/g, '_')}`
-      expectedCronNames.add(cronName)
-      await this.pgBoss.createQueue(cronName)
-      await this.pgBoss.schedule(cronName, task.schedule, {
-        rpcName: name,
-      } as ScheduledJobData)
-      this.scheduledCronNames.push(cronName)
-
-      // Register a worker to process the scheduled jobs
-      await this.pgBoss.work<ScheduledJobData>(cronName, async (jobs) => {
-        for (const job of jobs) {
-          const { rpcName } = job.data
-          logger.info(`Running scheduled task: ${rpcName}`)
-          await runScheduledTask({ name: rpcName })
-        }
-      })
-    }
-
-    // Prune orphaned schedules. A task removed from code leaves its pg-boss
-    // schedule behind; with no worker registered it keeps producing jobs that
-    // pile up as 'created' forever (this is how a removed task flooded a queue
-    // with thousands of stuck jobs). Drop any recurring schedule + queue that's
-    // no longer registered so task removals self-heal on the next boot.
-    try {
-      const existing = await this.pgBoss.getSchedules()
-      for (const schedule of existing) {
-        if (
-          schedule.name.startsWith(RECURRING_TASK_PREFIX) &&
-          !expectedCronNames.has(schedule.name)
-        ) {
-          await this.pgBoss.unschedule(schedule.name)
-          await this.pgBoss.deleteQueue(schedule.name)
-          logger.warn(`Pruned orphaned scheduled task queue: ${schedule.name}`)
-        }
-      }
-    } catch (err) {
-      logger.warn(
-        `Failed to prune orphaned scheduled tasks: ${err instanceof Error ? err.message : String(err)}`
-      )
-    }
-  }
-
-  /**
-   * Stop recurring scheduled tasks by unscheduling them from pg-boss.
-   */
-  async stop(): Promise<void> {
-    for (const cronName of this.scheduledCronNames) {
-      await this.pgBoss.unschedule(cronName)
-    }
-    this.scheduledCronNames = []
-  }
-}

package/src/pg-boss-service-factory.ts

@@ -1,85 +0,0 @@
-import { PgBoss, type ConstructorOptions } from 'pg-boss'
-import { PgBossQueueService } from './pg-boss-queue-service.js'
-import { PgBossQueueWorkers } from './pg-boss-queue-worker.js'
-import { PgBossSchedulerService } from './pg-boss-scheduler-service.js'
-
-/**
- * Factory class for pg-boss services
- * Manages a single PgBoss instance shared across queue, worker, and scheduler services
- */
-export class PgBossServiceFactory {
-  private pgBoss: PgBoss
-  private queueService?: PgBossQueueService
-  private queueWorkers?: PgBossQueueWorkers
-  private schedulerService?: PgBossSchedulerService
-  private initialized = false
-
-  constructor(optionsOrInstance: ConstructorOptions | string | PgBoss) {
-    if (optionsOrInstance instanceof PgBoss) {
-      this.pgBoss = optionsOrInstance
-    } else {
-      const options =
-        typeof optionsOrInstance === 'string'
-          ? { connectionString: optionsOrInstance }
-          : optionsOrInstance
-      this.pgBoss = new PgBoss(options)
-    }
-  }
-
-  /**
-   * Initialize the pg-boss instance
-   */
-  async init(): Promise<void> {
-    if (!this.initialized) {
-      await this.pgBoss.start()
-      this.initialized = true
-    }
-  }
-
-  /**
-   * Get the queue service for publishing jobs
-   */
-  getQueueService(): PgBossQueueService {
-    if (!this.queueService) {
-      this.queueService = new PgBossQueueService(this.pgBoss)
-    }
-    return this.queueService
-  }
-
-  /**
-   * Get the queue workers for processing jobs
-   */
-  getQueueWorkers(): PgBossQueueWorkers {
-    if (!this.queueWorkers) {
-      this.queueWorkers = new PgBossQueueWorkers(this.pgBoss)
-    }
-    return this.queueWorkers
-  }
-
-  /**
-   * Get the scheduler service for managing recurring tasks
-   */
-  getSchedulerService(): PgBossSchedulerService {
-    if (!this.schedulerService) {
-      this.schedulerService = new PgBossSchedulerService(this.pgBoss)
-    }
-    return this.schedulerService
-  }
-
-  /**
-   * Close all services and the pg-boss connection
-   */
-  async close(): Promise<void> {
-    if (this.initialized) {
-      await this.pgBoss.stop()
-      this.initialized = false
-    }
-  }
-
-  /**
-   * Alias for close() - used by stopSingletonServices
-   */
-  async stop(): Promise<void> {
-    await this.close()
-  }
-}

package/src/utils.ts

@@ -1,87 +0,0 @@
-import type { QueueJob, QueueJobStatus } from '@pikku/core/queue'
-import type { PgBoss, JobWithMetadata } from 'pg-boss'
-
-/**
- * Map pg-boss job state to our queue job status
- */
-const mapPgBossStateToStatus = (state: string): QueueJobStatus => {
-  switch (state) {
-    case 'created':
-    case 'retry':
-      return 'waiting'
-    case 'active':
-      return 'active'
-    case 'completed':
-      return 'completed'
-    case 'failed':
-      return 'failed'
-    case 'cancelled':
-      return 'failed'
-    default:
-      return 'waiting'
-  }
-}
-
-/**
- * Map pg-boss job to QueueJob interface
- */
-export const mapPgBossJobToQueueJob = <In, Out>(
-  pgBossJob: JobWithMetadata<In>,
-  pgBossInstance: PgBoss
-): QueueJob<In, Out> => {
-  return {
-    queueName: pgBossJob.name,
-    id: pgBossJob.id || '',
-    data: pgBossJob.data,
-    status: async () => {
-      const jobWithState = await pgBossInstance.getJobById(
-        pgBossJob.name,
-        pgBossJob.id
-      )
-      return mapPgBossStateToStatus(jobWithState?.state || 'created')
-    },
-    waitForCompletion: async (ttl?: number): Promise<Out> => {
-      // pg-boss doesn't have a built-in waitForCompletion, so we'll poll
-      const startTime = Date.now()
-      const timeout = ttl || 30000 // 30 seconds default
-
-      while (Date.now() - startTime < timeout) {
-        const job = await pgBossInstance.getJobById(
-          pgBossJob.name,
-          pgBossJob.id
-        )
-        if (job?.state === 'completed') {
-          return job.output as Out
-        }
-        if (job?.state === 'failed' || job?.state === 'cancelled') {
-          throw new Error(`Job failed: ${JSON.stringify(job.output)}`)
-        }
-        // Wait 100ms before polling again
-        await new Promise((resolve) => setTimeout(resolve, 100))
-      }
-
-      throw new Error('Job did not complete within timeout')
-    },
-    metadata: () => {
-      return {
-        progress: 0, // pg-boss doesn't have built-in progress tracking
-        attemptsMade: pgBossJob.retryCount || 0,
-        maxAttempts: pgBossJob.retryLimit || 1,
-        createdAt: pgBossJob.createdOn
-          ? new Date(pgBossJob.createdOn)
-          : new Date(),
-        processedAt: pgBossJob.startedOn
-          ? new Date(pgBossJob.startedOn)
-          : undefined,
-        completedAt: pgBossJob.completedOn
-          ? new Date(pgBossJob.completedOn)
-          : undefined,
-        failedAt:
-          pgBossJob.state === 'failed' && pgBossJob.completedOn
-            ? new Date(pgBossJob.completedOn)
-            : undefined,
-        error: (pgBossJob.data as any).error,
-      }
-    },
-  }
-}

package/tsconfig.json

@@ -1,17 +0,0 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "rootDir": "./src",
-    "module": "Node18",
-    "outDir": "dist",
-    "target": "esnext",
-    "declaration": true
-  },
-  "include": ["src/**/*.ts"],
-  "exclude": ["**/*.test.ts", "node_modules"],
-  "references": [
-    {
-      "path": "../../core/tsconfig.json"
-    }
-  ]
-}

package/tsconfig.tsbuildinfo

@@ -1 +0,0 @@
-{"root":["./src/index.ts","./src/pg-boss-queue-service.ts","./src/pg-boss-queue-worker.ts","./src/pg-boss-scheduler-service.ts","./src/pg-boss-service-factory.ts","./src/utils.ts"],"version":"6.0.3"}