@pikku/kysely 0.13.16 → 0.13.19

package/dist/src/kysely-workflow-service.d.ts

@@ -1,6 +1,6 @@
-import type { SerializedError } from '@pikku/core/ecosystem/types';
+import type { SerializedError } from '@pikku/core/errors';
 import { PikkuWorkflowService } from '@pikku/core/workflow';
-import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus } from '@pikku/core/ecosystem/workflow';
+import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus } from '@pikku/core/workflow';
 import { type Kysely } from 'kysely';
 import type { KyselyPikkuDB } from './kysely-tables.js';
 export declare class KyselyWorkflowService extends PikkuWorkflowService {
@@ -47,7 +47,36 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
     protected setStepErrorImpl(stepId: string, error: Error): Promise<void>;
     protected createRetryAttemptImpl(stepId: string, status: 'pending' | 'running'): Promise<StepState>;
     withRunLock<T>(_id: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * A pass-through, and deliberately so: the one decision that must exclude —
+     * claiming a step to execute it — is made by `claimStepForExecution` below as
+     * a single conditional write, which needs no lock to be exclusive.
+     *
+     * What is left are the suspend and approval sections in the engine, where the
+     * lock is genuine mutual exclusion rather than a claim. A dialect with a real
+     * primitive overrides this to cover them — `kysely-postgres` with
+     * `pg_advisory_xact_lock`, `kysely-mysql` with `GET_LOCK`.
+     */
     withStepLock<T>(_runId: string, _stepName: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Claim the step with a status-guarded `UPDATE` and read the affected-row
+     * count: the database decides the winner in one statement, so two dispatches
+     * racing for the same step cannot both proceed.
+     *
+     * This replaces the read-then-write the base engine does under `withStepLock`,
+     * which is only as exclusive as that lock — and every dialect but Postgres and
+     * MySQL inherits a pass-through. A conditional update needs no advisory-lock
+     * primitive, so every SQL dialect gets the same guarantee.
+     *
+     * The winner then goes through the ordinary transition methods, so history
+     * rows and the mirror see exactly what they saw before.
+     */
+    protected claimStepForExecution(runId: string, stepName: string, rpcName: string): Promise<StepState | null>;
+    /**
+     * Move a step to `running` only if it is still in one of `from`, reporting
+     * whether this caller is the one that moved it.
+     */
+    private claimStepStatus;
     getCompletedGraphState(runId: string): Promise<{
         completedNodeIds: string[];
         failedNodeIds: string[];
@@ -81,16 +110,18 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
     private jsonPathFor;
     protected updateRunStateImpl(runId: string, name: string, value: unknown): Promise<void>;
     /**
-     * The undispatched-step query, shared by the dialects that can safely relay.
+     * The undispatched-step query, shared by every dialect.
      *
-     * Deliberately NOT an override of `findUndispatchedSteps`: this class's
-     * `withStepLock` is a pass-through, so a subclass inheriting it (kysely-sqlite)
-     * has no atomic claim, and the relay's redundant dispatches would become
-     * double executions. A dialect opts in by overriding `findUndispatchedSteps`
-     * to call this — which `kysely-postgres` and `kysely-mysql` do, having real
-     * locks.
+     * It used to be deliberately NOT an override, because this class's
+     * `withStepLock` is a pass-through: a subclass inheriting it (kysely-sqlite)
+     * had no atomic claim, so the relay's redundant dispatches would have become
+     * double executions, and only `kysely-postgres` and `kysely-mysql` opted in
+     * on the strength of their real locks. `claimStepForExecution` no longer
+     * needs that lock — the claim is a status-guarded `UPDATE`, atomic in every
+     * dialect — so the relay is safe here for all of them and the override lives
+     * in the base.
      */
-    protected queryUndispatchedSteps(before: Date, limit: number): Promise<Array<{
+    protected findUndispatchedSteps(before: Date, limit: number): Promise<Array<{
         runId: string;
         stepId: string;
     }>>;

package/dist/src/kysely-workflow-service.js

@@ -1,4 +1,4 @@
-import { PikkuWorkflowService } from '@pikku/core/workflow';
+import { PikkuWorkflowService, WorkflowStepFunctionMismatchError, } from '@pikku/core/workflow';
 import { sql } from 'kysely';
 import { KyselyWorkflowRunService } from './kysely-workflow-run-service.js';
 import { parseJson } from './kysely-json.js';
@@ -363,9 +363,73 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
     async withRunLock(_id, fn) {
         return fn();
     }
+    /**
+     * A pass-through, and deliberately so: the one decision that must exclude —
+     * claiming a step to execute it — is made by `claimStepForExecution` below as
+     * a single conditional write, which needs no lock to be exclusive.
+     *
+     * What is left are the suspend and approval sections in the engine, where the
+     * lock is genuine mutual exclusion rather than a claim. A dialect with a real
+     * primitive overrides this to cover them — `kysely-postgres` with
+     * `pg_advisory_xact_lock`, `kysely-mysql` with `GET_LOCK`.
+     */
     async withStepLock(_runId, _stepName, fn) {
         return fn();
     }
+    /**
+     * Claim the step with a status-guarded `UPDATE` and read the affected-row
+     * count: the database decides the winner in one statement, so two dispatches
+     * racing for the same step cannot both proceed.
+     *
+     * This replaces the read-then-write the base engine does under `withStepLock`,
+     * which is only as exclusive as that lock — and every dialect but Postgres and
+     * MySQL inherits a pass-through. A conditional update needs no advisory-lock
+     * primitive, so every SQL dialect gets the same guarantee.
+     *
+     * The winner then goes through the ordinary transition methods, so history
+     * rows and the mirror see exactly what they saw before.
+     */
+    async claimStepForExecution(runId, stepName, rpcName) {
+        const stepState = await this.getStepState(runId, stepName);
+        // knowledge: decisions/security/a-step-runs-the-function-the-workflow-dispatched-it-with.md
+        if (stepState.rpcName !== undefined &&
+            stepState.rpcName !== (rpcName ?? null)) {
+            throw new WorkflowStepFunctionMismatchError(runId, stepName);
+        }
+        if (stepState.status === 'succeeded' || stepState.status === 'running') {
+            return null;
+        }
+        if (stepState.status === 'failed') {
+            if (!(await this.claimStepStatus(stepState.stepId, ['failed']))) {
+                return null;
+            }
+            return this.createRetryAttempt(stepState.stepId, 'running');
+        }
+        if (stepState.status === 'pending' || stepState.status === 'scheduled') {
+            if (!(await this.claimStepStatus(stepState.stepId, [
+                'pending',
+                'scheduled',
+            ]))) {
+                return null;
+            }
+            await this.setStepRunning(stepState.stepId);
+            return { ...stepState, status: 'running' };
+        }
+        return stepState;
+    }
+    /**
+     * Move a step to `running` only if it is still in one of `from`, reporting
+     * whether this caller is the one that moved it.
+     */
+    async claimStepStatus(stepId, from) {
+        const claimed = await this.db
+            .updateTable('workflowStep')
+            .set({ status: 'running', updatedAt: new Date() })
+            .where('workflowStepId', '=', stepId)
+            .where('status', 'in', from)
+            .executeTakeFirst();
+        return Number(claimed?.numUpdatedRows ?? 0n) > 0;
+    }
     async getCompletedGraphState(runId) {
         const results = await this.db
             .selectFrom('workflowStep as ws')
@@ -470,16 +534,18 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
             .execute();
     }
     /**
-     * The undispatched-step query, shared by the dialects that can safely relay.
+     * The undispatched-step query, shared by every dialect.
      *
-     * Deliberately NOT an override of `findUndispatchedSteps`: this class's
-     * `withStepLock` is a pass-through, so a subclass inheriting it (kysely-sqlite)
-     * has no atomic claim, and the relay's redundant dispatches would become
-     * double executions. A dialect opts in by overriding `findUndispatchedSteps`
-     * to call this — which `kysely-postgres` and `kysely-mysql` do, having real
-     * locks.
+     * It used to be deliberately NOT an override, because this class's
+     * `withStepLock` is a pass-through: a subclass inheriting it (kysely-sqlite)
+     * had no atomic claim, so the relay's redundant dispatches would have become
+     * double executions, and only `kysely-postgres` and `kysely-mysql` opted in
+     * on the strength of their real locks. `claimStepForExecution` no longer
+     * needs that lock — the claim is a status-guarded `UPDATE`, atomic in every
+     * dialect — so the relay is safe here for all of them and the override lives
+     * in the base.
      */
-    async queryUndispatchedSteps(before, limit) {
+    async findUndispatchedSteps(before, limit) {
         const rows = await this.db
             .selectFrom('workflowStep as s')
             .innerJoin('workflowRuns as r', 'r.workflowRunId', 's.workflowRunId')

package/dist/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-agent-run-scores.ts","../src/kysely-agent-run-service.ts","../src/kysely-agent-run-state-service.ts","../src/kysely-agent-storage-service.ts","../src/kysely-audit-service.ts","../src/kysely-channel-store.ts","../src/kysely-credential-service.ts","../src/kysely-deployment-service.ts","../src/kysely-eventhub-store.ts","../src/kysely-json.ts","../src/kysely-scope-service.ts","../src/kysely-secret-service.ts","../src/kysely-session-store.ts","../src/kysely-tables.ts","../src/kysely-virtual-user-run-store.ts","../src/kysely-webhook-service.ts","../src/kysely-workflow-mirror.ts","../src/kysely-workflow-run-service.ts","../src/kysely-workflow-service.ts","../src/serialize-plugin.ts","../src/schema/agent.schema.ts","../src/schema/audit.schema.ts","../src/schema/channel.schema.ts","../src/schema/credential.schema.ts","../src/schema/deployment.schema.ts","../src/schema/index.ts","../src/schema/pikku-schema.types.ts","../src/schema/scope.schema.ts","../src/schema/secret.schema.ts","../src/schema/session.schema.ts","../src/schema/virtual-user.schema.ts","../src/schema/webhook.schema.ts","../src/schema/workflow.schema.ts","../bin/pikku-kysely-pure.ts"],"version":"6.0.3"}
+{"root":["../src/coercion-plugin.ts","../src/create-audited-kysely.ts","../src/index.ts","../src/kysely-agent-run-scores.ts","../src/kysely-agent-run-service.ts","../src/kysely-agent-run-state-service.ts","../src/kysely-agent-storage-service.ts","../src/kysely-audit-service.ts","../src/kysely-channel-store.ts","../src/kysely-credential-service.ts","../src/kysely-deployment-service.ts","../src/kysely-eventhub-store.ts","../src/kysely-json.ts","../src/kysely-scope-service.ts","../src/kysely-secret-service.ts","../src/kysely-session-store.ts","../src/kysely-tables.ts","../src/kysely-virtual-user-run-store.ts","../src/kysely-webhook-service.ts","../src/kysely-workflow-mirror.ts","../src/kysely-workflow-run-service.ts","../src/kysely-workflow-service.ts","../src/serialize-plugin.ts","../src/schema/agent.schema.ts","../src/schema/audit.schema.ts","../src/schema/channel.schema.ts","../src/schema/credential.schema.ts","../src/schema/deployment.schema.ts","../src/schema/index.ts","../src/schema/pikku-schema.types.ts","../src/schema/scope.schema.ts","../src/schema/secret.schema.ts","../src/schema/session.schema.ts","../src/schema/virtual-user.schema.ts","../src/schema/webhook.schema.ts","../src/schema/workflow.schema.ts","../bin/pikku-kysely-pure.ts"],"version":"6.0.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/kysely",
-  "version": "0.13.16",
+  "version": "0.13.19",
   "description": "Kysely-backed Pikku services — workflow state, secrets, sessions, scopes and audit",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -21,20 +21,20 @@
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.84"
+    "@pikku/core": "^0.12.87"
   },
   "dependencies": {
-    "kysely": "^0.29.0"
+    "kysely": "^0.29.5"
   },
   "devDependencies": {
-    "@types/better-sqlite3": "^7.6.13",
-    "better-sqlite3": "^12.10.0",
+    "@types/better-sqlite3": "^9.6.0",
+    "better-sqlite3": "^13.0.3",
     "kysely-codegen": "^0.20.0",
     "kysely-postgres-js": "^3.0.0",
-    "postgres": "^3.4.8",
+    "postgres": "^3.4.9",
     "typescript": "^6.0.3"
   },
   "exports": {
     ".": "./dist/src/index.js"
   }
-}
+}

package/src/coercion-plugin.test.ts

@@ -0,0 +1,160 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import type { QueryResult, UnknownRow } from 'kysely'
+import { createCoercionPlugin, type CoercionMap } from './coercion-plugin.js'
+
+function selectFrom(...tables: string[]) {
+  return {
+    kind: 'SelectQueryNode',
+    from: {
+      kind: 'FromNode',
+      froms: tables.map((table) => ({
+        kind: 'TableNode',
+        table: {
+          kind: 'SchemableIdentifierNode',
+          identifier: { kind: 'IdentifierNode', name: table },
+        },
+      })),
+    },
+  }
+}
+
+const runTransform = async (
+  map: CoercionMap,
+  rows: UnknownRow[],
+  node?: unknown
+): Promise<UnknownRow[]> => {
+  const plugin = createCoercionPlugin({ map })
+  const queryId = {} as { queryId: string }
+  if (node !== undefined) {
+    plugin.transformQuery({ node, queryId } as any)
+  }
+  const result = { rows } as QueryResult<UnknownRow>
+  const out = await plugin.transformResult({ result, queryId } as any)
+  return out.rows as UnknownRow[]
+}
+
+describe('createCoercionPlugin', () => {
+  test('transformQuery passes the node through untouched', () => {
+    const plugin = createCoercionPlugin({ map: {} })
+    const node = selectFrom('users') as any
+    assert.equal(
+      plugin.transformQuery({ node, queryId: { queryId: 'x' } } as any),
+      node
+    )
+  })
+
+  test('coerces date columns from ISO strings to Date', async () => {
+    const [row] = await runTransform({ users: { created_at: 'date' } }, [
+      { created_at: '2026-06-26T00:00:00.000Z' },
+    ])
+    assert.ok(row!.created_at instanceof Date)
+    assert.equal(
+      (row!.created_at as Date).toISOString(),
+      '2026-06-26T00:00:00.000Z'
+    )
+  })
+
+  test('leaves unparseable date strings untouched', async () => {
+    const [row] = await runTransform({ users: { created_at: 'date' } }, [
+      { created_at: 'not-a-date' },
+    ])
+    assert.equal(row!.created_at, 'not-a-date')
+  })
+
+  test('coerces bool columns from 0/1 numbers and bigints', async () => {
+    const rows = await runTransform(
+      { users: { is_active: 'bool', has_pets: 'bool' } },
+      [{ is_active: 1, has_pets: 0n }]
+    )
+    assert.equal(rows[0]!.is_active, true)
+    assert.equal(rows[0]!.has_pets, false)
+  })
+
+  test('parses json columns and tolerates invalid json', async () => {
+    const rows = await runTransform(
+      { users: { meta: 'json', broken: 'json' } },
+      [{ meta: '{"a":1}', broken: '{bad' }]
+    )
+    assert.deepEqual(rows[0]!.meta, { a: 1 })
+    assert.equal(rows[0]!.broken, '{bad')
+  })
+
+  test('passes through null values and unmapped columns', async () => {
+    const rows = await runTransform({ users: { created_at: 'date' } }, [
+      { created_at: null, name: 'leave me' },
+    ])
+    assert.equal(rows[0]!.created_at, null)
+    assert.equal(rows[0]!.name, 'leave me')
+  })
+
+  test('matches both snake_case and camelCase column names', async () => {
+    const rows = await runTransform({ users: { created_at: 'date' } }, [
+      { createdAt: '2026-06-26T00:00:00.000Z' },
+    ])
+    assert.ok(rows[0]!.createdAt instanceof Date)
+  })
+
+  test('leaves columns ambiguous across tables uncoerced', async () => {
+    const rows = await runTransform(
+      { users: { value: 'json' }, events: { value: 'bool' } },
+      [{ value: '{"a":1}' }]
+    )
+    assert.equal(rows[0]!.value, '{"a":1}')
+  })
+
+  test('still coerces columns that agree across tables', async () => {
+    const rows = await runTransform(
+      { users: { active: 'bool' }, events: { active: 'bool' } },
+      [{ active: 1 }]
+    )
+    assert.equal(rows[0]!.active, true)
+  })
+
+  test('uses table-qualified coercions when names collide', async () => {
+    const map: CoercionMap = {
+      users: { settings: 'json' },
+      posts: { settings: 'bool' },
+    }
+    const fromUsers = await runTransform(
+      map,
+      [{ settings: '{"theme":"dark"}' }],
+      selectFrom('users')
+    )
+    assert.deepEqual(fromUsers[0]!.settings, { theme: 'dark' })
+
+    const fromPosts = await runTransform(
+      map,
+      [{ settings: 1 }],
+      selectFrom('posts')
+    )
+    assert.equal(fromPosts[0]!.settings, true)
+  })
+
+  test('table-qualified lookup matches camelCase result columns too', async () => {
+    const rows = await runTransform(
+      { users: { created_at: 'date' }, jobs: { created_at: 'json' } },
+      [{ createdAt: '2026-06-26T00:00:00.000Z' }],
+      selectFrom('users')
+    )
+    assert.ok(rows[0]!.createdAt instanceof Date)
+  })
+
+  test('a join whose tables disagree leaves the column uncoerced', async () => {
+    const rows = await runTransform(
+      { users: { value: 'json' }, events: { value: 'bool' } },
+      [{ value: '{"a":1}' }],
+      selectFrom('users', 'events')
+    )
+    assert.equal(rows[0]!.value, '{"a":1}')
+  })
+
+  test('falls back to flat keys when the query names no known table', async () => {
+    const rows = await runTransform(
+      { users: { created_at: 'date' } },
+      [{ createdAt: '2026-01-02T03:04:05.000Z' }],
+      selectFrom('unrelated')
+    )
+    assert.ok(rows[0]!.createdAt instanceof Date)
+  })
+})

package/src/coercion-plugin.ts

@@ -0,0 +1,187 @@
+import type { KyselyPlugin, RootOperationNode, UnknownRow } from 'kysely'
+
+/**
+ * The kinds a column can be coerced *to* at runtime. This is the value type of
+ * the generated `CoercionMap`, so it is a public artifact contract — a kind may
+ * only appear here if `fromDb` below actually does something with it.
+ *
+ * `uuid` is deliberately absent: it is an annotation kind (it selects the `Uuid`
+ * TypeScript type in the generated schema) but not a coercion kind, and the
+ * codegen filters it out of `coercion.gen.ts` for exactly that reason — a UUID
+ * is a string in both Postgres and SQLite.
+ */
+export type ColumnKind = 'date' | 'bool' | 'json'
+
+/**
+ * Per-table column kind map. Keys are the table names queries are written
+ * against; inner keys are snake_case column names.
+ * Generated into `outDir/db/coercion.gen.ts` by `pikku db migrate` from the
+ * explicit `kind` entries in `db/annotations.ts`.
+ */
+export type CoercionMap = Record<string, Record<string, ColumnKind>>
+
+export interface CreateCoercionPluginOptions {
+  map: CoercionMap
+}
+
+function fromDb(value: unknown, kind: ColumnKind): unknown {
+  if (value == null) return value
+  switch (kind) {
+    case 'date':
+      if (typeof value === 'string') {
+        const d = new Date(value)
+        return Number.isNaN(d.getTime()) ? value : d
+      }
+      return value
+    case 'bool':
+      if (typeof value === 'number') return value !== 0
+      if (typeof value === 'bigint') return value !== 0n
+      return value
+    case 'json':
+      if (typeof value !== 'string') return value
+      try {
+        return JSON.parse(value)
+      } catch {
+        return value
+      }
+  }
+}
+
+function snakeToCamel(name: string): string {
+  return name.replace(/_([a-z])/g, (_, c) => c.toUpperCase())
+}
+
+interface ResolvedMaps {
+  /** `table.column` → kind, for the exact per-query resolution. */
+  qualified: Record<string, ColumnKind>
+  /** `column` → kind, the fallback for when the query's tables say nothing. */
+  flat: Record<string, ColumnKind>
+}
+
+/**
+ * Flatten the per-table map into a table-qualified lookup plus a bare
+ * column-name fallback. Both are indexed by BOTH snake_case and camelCase so
+ * they work regardless of CamelCasePlugin ordering in the plugin array.
+ *
+ * When two tables disagree on the kind for the same column name, the bare name
+ * is ambiguous (a joined/aliased query could carry either) and is dropped from
+ * the flat map rather than letting whichever table was processed last win. The
+ * qualified map still resolves it whenever the query names its tables.
+ */
+function buildMaps(map: CoercionMap): ResolvedMaps {
+  const qualified: Record<string, ColumnKind> = {}
+  const flat: Record<string, ColumnKind> = {}
+  const ambiguous = new Set<string>()
+  const assignFlat = (key: string, kind: ColumnKind) => {
+    const existing = flat[key]
+    if (existing !== undefined && existing !== kind) {
+      ambiguous.add(key)
+      return
+    }
+    flat[key] = kind
+  }
+  for (const [table, cols] of Object.entries(map)) {
+    for (const [col, kind] of Object.entries(cols)) {
+      const camel = snakeToCamel(col)
+      qualified[`${table}.${col}`] = kind
+      qualified[`${table}.${camel}`] = kind
+      assignFlat(col, kind)
+      assignFlat(camel, kind)
+    }
+  }
+  for (const key of ambiguous) delete flat[key]
+  return { qualified, flat }
+}
+
+/**
+ * Collect every table named anywhere in the query's operation node, so a result
+ * column can be resolved against the tables the query actually touched instead
+ * of against every table in the schema.
+ */
+function collectQueryTables(node: unknown, out: Set<string>): void {
+  if (!node || typeof node !== 'object') return
+
+  const op = node as {
+    kind?: string
+    table?: { identifier?: { name?: string } }
+  }
+  if (op.kind === 'TableNode') {
+    const tableName = op.table?.identifier?.name
+    if (typeof tableName === 'string' && tableName.length > 0)
+      out.add(tableName)
+  }
+
+  for (const value of Object.values(node)) {
+    if (Array.isArray(value)) {
+      for (const item of value) collectQueryTables(item, out)
+    } else {
+      collectQueryTables(value, out)
+    }
+  }
+}
+
+/**
+ * Resolve a result column's kind against the query's tables, falling back to
+ * the bare column name. Tables that disagree with each other are as ambiguous
+ * as two schema tables are, so they fall back too.
+ */
+function lookupKind(
+  maps: ResolvedMaps,
+  tables: readonly string[],
+  col: string
+): ColumnKind | undefined {
+  let matchedKind: ColumnKind | undefined
+  for (const table of tables) {
+    const kind = maps.qualified[`${table}.${col}`]
+    if (!kind) continue
+    if (matchedKind && matchedKind !== kind) return maps.flat[col]
+    matchedKind = kind
+  }
+  return matchedKind ?? maps.flat[col]
+}
+
+/**
+ * Convert values stored in a dialect's on-disk representation back into the
+ * logical types app code expects (Date / boolean / parsed JSON).
+ *
+ * SQLite is what makes this necessary — it stores dates as TEXT, booleans as
+ * INTEGER and JSON as TEXT — but the plugin is dialect-neutral: on Postgres the
+ * driver already returns Date/boolean/object, and every branch of `fromDb`
+ * passes a non-string, non-number value straight through. That is why it lives
+ * in `@pikku/kysely` next to `SerializePlugin` rather than in a SQLite package:
+ * the CLI installs it on its local Postgres database too.
+ *
+ * Write-side coercion (Date → ISO string, boolean → 0/1, object → JSON) is
+ * handled in the SQLite database adapters (always-on), so this plugin is
+ * read-only.
+ *
+ * Place AFTER CamelCasePlugin in the plugin array (or it handles both
+ * orderings via the dual-keyed maps).
+ */
+export function createCoercionPlugin(
+  options: CreateCoercionPluginOptions
+): KyselyPlugin {
+  const maps = buildMaps(options.map)
+  const queryTables = new WeakMap<object, readonly string[]>()
+  return {
+    transformQuery(args) {
+      const tables = new Set<string>()
+      collectQueryTables(args.node as RootOperationNode, tables)
+      queryTables.set(args.queryId, [...tables])
+      return args.node
+    },
+    async transformResult(args) {
+      const tables = queryTables.get(args.queryId) ?? []
+      const out: UnknownRow[] = []
+      for (const row of args.result.rows as UnknownRow[]) {
+        const next: UnknownRow = { ...row }
+        for (const [col, val] of Object.entries(row)) {
+          const kind = lookupKind(maps, tables, col)
+          if (kind) next[col] = fromDb(val, kind)
+        }
+        out.push(next)
+      }
+      return { ...args.result, rows: out }
+    },
+  }
+}

package/src/create-audited-kysely.test.ts

@@ -7,7 +7,7 @@ import {
   NoopAuditService,
   type AuditEvent,
   type AuditService,
-} from '../../../core/src/index.js'
+} from '@pikku/core/services'
 
 import { createAuditedKysely } from './create-audited-kysely.js'
 

package/src/create-audited-kysely.ts

@@ -1,4 +1,4 @@
-import type { AuditLog } from '@pikku/core'
+import type { AuditLog } from '@pikku/core/services'
 import type {
   Kysely,
   KyselyPlugin,

package/src/index.ts

@@ -25,6 +25,12 @@ export {
   type Serializer,
   type Deserializer,
 } from './serialize-plugin.js'
+export {
+  createCoercionPlugin,
+  type ColumnKind,
+  type CoercionMap,
+  type CreateCoercionPluginOptions,
+} from './coercion-plugin.js'
 export {
   auditSchema,
   pikkuSchemas,
@@ -40,12 +46,9 @@ export {
 } from './schema/index.js'
 
 export type { KyselyPikkuDB } from './kysely-tables.js'
-export type { WorkflowRunService } from '@pikku/core/ecosystem/workflow'
-export type {
-  AgentRunService,
-  AgentRunRow,
-} from '@pikku/core/ecosystem/agent'
+export type { WorkflowRunService } from '@pikku/core/workflow'
+export type { AgentRunService, AgentRunRow } from '@pikku/core/agent'
 export type {
   VirtualUserRunStore,
   VirtualUserRunRecord,
-} from '@pikku/core/ecosystem/virtual-user'
+} from '@pikku/core/virtual-user'

package/src/kysely-agent-run-scores.ts

@@ -1,7 +1,7 @@
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
-import type { SaveScoreInput } from '@pikku/core/services'
 import type { AgentRunScore } from '@pikku/core/agent-scorer'
+import type { SaveScoreInput } from '@pikku/core/services'
 import { parseJson } from './kysely-json.js'
 
 /**

package/src/kysely-agent-run-service.ts

@@ -1,8 +1,9 @@
-import type { AgentThread, AgentMessage } from '@pikku/core/agent'
 import type {
+  AgentThread,
+  AgentMessage,
   AgentRunRow,
   AgentRunService,
-} from '@pikku/core/ecosystem/agent'
+} from '@pikku/core/agent'
 import type { Kysely } from 'kysely'
 import { sql } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'

package/src/kysely-agent-run-state-service.ts

@@ -1,14 +1,14 @@
 import { sql } from 'kysely'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
+import type { AgentRunState } from '@pikku/core/agent'
+import type { AgentRunScore } from '@pikku/core/agent-scorer'
 import type {
   AgentRunStateService,
   CreateRunInput,
   SaveScoreInput,
 } from '@pikku/core/services'
-import type { AgentRunState } from '@pikku/core/agent'
-import type { PendingApproval } from '@pikku/core/ecosystem/agent'
-import type { AgentRunScore } from '@pikku/core/agent-scorer'
+import type { PendingApproval } from '@pikku/core/agent'
 import { ensurePikkuSchema } from './schema/index.js'
 import { agentSchema } from './schema/agent.schema.js'
 import { getRunScores, saveRunScore } from './kysely-agent-run-scores.js'