@pikku/kysely 0.13.16 → 0.13.19

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

@@ -1,15 +1,15 @@
 import type {
-  AgentStorageService,
-  AgentRunStateService,
-  CreateRunInput,
-  SaveScoreInput,
-} from '@pikku/core/services'
-import type {
-  AgentThread,
   AgentMessage,
   AgentRunState,
+  AgentThread,
 } from '@pikku/core/agent'
 import type { AgentRunScore } from '@pikku/core/agent-scorer'
+import type {
+  AgentRunStateService,
+  AgentStorageService,
+  CreateRunInput,
+  SaveScoreInput,
+} from '@pikku/core/services'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'

package/src/kysely-audit-service.test.ts

@@ -2,7 +2,7 @@ import { describe, test, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 import Database from 'better-sqlite3'
 import { CamelCasePlugin, Kysely, SqliteDialect, sql } from 'kysely'
-import type { AuditEvent } from '../../../core/src/index.js'
+import type { AuditEvent } from '@pikku/core/services'
 
 import { KyselyAuditService } from './kysely-audit-service.js'
 

package/src/kysely-audit-service.ts

@@ -1,13 +1,10 @@
-import type { AuditService } from '@pikku/core'
-import type {
-  AuditEvent,
-  AuditEventBatch,
-} from '@pikku/core/ecosystem/services'
+import type { AuditService } from '@pikku/core/services'
+import type { AuditEvent, AuditEventBatch } from '@pikku/core/services'
 import type {
   AuditFacets,
   AuditQuery,
   AuditQueryResult,
-} from '@pikku/core/ecosystem/types'
+} from '@pikku/core/services'
 import type { Kysely } from 'kysely'
 import { ensurePikkuSchema } from './schema/index.js'
 import { auditSchema } from './schema/audit.schema.js'
@@ -118,8 +115,7 @@ export class KyselyAuditService implements AuditService {
     if (!batch.length) return
     const rows = batch.map((e) => {
       const metadata = e.metadata as
-        | { tables?: unknown; changedColumns?: unknown }
-        | undefined
+        { tables?: unknown; changedColumns?: unknown } | undefined
       return {
         audit_id: e.eventId ?? e.queryId ?? fallbackId(),
         occurred_at: e.occurredAt ?? new Date().toISOString(),

package/src/kysely-channel-store.ts

@@ -1,5 +1,5 @@
-import type { Channel } from '@pikku/core/channel'
 import { ChannelStore } from '@pikku/core/channel'
+import type { Channel } from '@pikku/core/channel'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'

package/src/kysely-credential-service.ts

@@ -1,13 +1,13 @@
-import type { CredentialService } from '@pikku/core/services'
-import type { Kysely } from 'kysely'
-import type { KyselyPikkuDB } from './kysely-tables.js'
 import {
   deriveKEK,
-  generateKEKSalt,
-  envelopeEncrypt,
   envelopeDecrypt,
+  envelopeEncrypt,
   envelopeRewrap,
+  generateKEKSalt,
 } from '@pikku/core/crypto-utils'
+import type { CredentialService } from '@pikku/core/services'
+import type { Kysely } from 'kysely'
+import type { KyselyPikkuDB } from './kysely-tables.js'
 import { ensurePikkuSchema } from './schema/index.js'
 import { credentialSchema } from './schema/credential.schema.js'
 

package/src/kysely-deployment-service.ts

@@ -1,11 +1,12 @@
-import { buildRemoteHeaders } from '@pikku/core/ecosystem/remote'
+import { buildRemoteHeaders } from '@pikku/core/remote'
 import type {
   DeploymentService,
   DeploymentServiceConfig,
   DeploymentConfig,
-} from '@pikku/core/ecosystem/services'
-import type { JWTService, SecretService } from '@pikku/core/services'
-import { getAllFunctionNames } from '@pikku/core/ecosystem/function'
+} from '@pikku/core/services'
+import type { JWTService } from '@pikku/core/services'
+import type { SecretService } from '@pikku/core/services'
+import { getAllFunctionNames } from '@pikku/core/function'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { ensurePikkuSchema } from './schema/index.js'

package/src/kysely-eventhub-store.ts

@@ -1,4 +1,4 @@
-import { EventHubStore } from '@pikku/core/ecosystem/channel'
+import { EventHubStore } from '@pikku/core/channel'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 

package/src/kysely-scope-service.ts

@@ -1,7 +1,7 @@
 import type { ScopeService } from '@pikku/core/services'
-import type { Role } from '@pikku/core/ecosystem/services'
-import type { FlatScope } from '@pikku/core/ecosystem/scope'
-import type { SystemRole } from '@pikku/core/ecosystem/role'
+import type { Role } from '@pikku/core/services'
+import type { FlatScope } from '@pikku/core/scope'
+import type { SystemRole } from '@pikku/core/role'
 import {
   SystemRoleImmutableError,
   SystemRoleShadowedError,

package/src/kysely-secret-service.ts

@@ -1,14 +1,15 @@
-import { createSecretValue, isSecretValue, type SecretValue } from '@pikku/core'
-import type { SecretService, SecretValues } from '@pikku/core/services'
-import type { Kysely } from 'kysely'
-import type { KyselyPikkuDB } from './kysely-tables.js'
 import {
   deriveKEK,
-  generateKEKSalt,
-  envelopeEncrypt,
   envelopeDecrypt,
+  envelopeEncrypt,
   envelopeRewrap,
+  generateKEKSalt,
 } from '@pikku/core/crypto-utils'
+import { createSecretValue, isSecretValue } from '@pikku/core/classification'
+import type { SecretService, SecretValues } from '@pikku/core/services'
+import type { SecretValue } from '@pikku/core/classification'
+import type { Kysely } from 'kysely'
+import type { KyselyPikkuDB } from './kysely-tables.js'
 import { ensurePikkuSchema } from './schema/index.js'
 import { secretSchema } from './schema/secret.schema.js'
 

package/src/kysely-services.test.ts

@@ -5,7 +5,7 @@ import { SerializePlugin } from './serialize-plugin.js'
 import Database from 'better-sqlite3'
 import { PostgresJSDialect } from 'kysely-postgres-js'
 import postgres from 'postgres'
-import { defineServiceTests } from '@pikku/core/ecosystem/testing'
+import { defineServiceTests } from '@pikku/core/testing'
 
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { KyselyChannelStore } from './kysely-channel-store.js'

package/src/kysely-session-store.ts

@@ -1,5 +1,5 @@
-import type { CoreUserSession } from '@pikku/core'
 import type { SessionStore } from '@pikku/core/services'
+import type { CoreUserSession } from '@pikku/core/types'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'

package/src/kysely-tables.ts

@@ -3,7 +3,7 @@ import type {
   WorkflowStatus,
   StepStatus,
   WorkflowVersionStatus,
-} from '@pikku/core/ecosystem/workflow'
+} from '@pikku/core/workflow'
 
 export interface ChannelsTable {
   channelId: string

package/src/kysely-virtual-user-run-store.ts

@@ -6,7 +6,7 @@ import type {
   VirtualUserRunRecord,
   VirtualUserRunStart,
   VirtualUserRunStore,
-} from '@pikku/core/ecosystem/virtual-user'
+} from '@pikku/core/virtual-user'
 import type { KyselyPikkuDB, VirtualUserRunTable } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'
 import { ensurePikkuSchema } from './schema/index.js'

package/src/kysely-webhook-service.test.ts

@@ -2,7 +2,7 @@ import { describe, test, beforeEach } from 'node:test'
 import assert from 'node:assert/strict'
 import { CamelCasePlugin, Kysely, SqliteDialect } from 'kysely'
 import Database from 'better-sqlite3'
-import { setSingletonServices } from '@pikku/core/ecosystem'
+import { setSingletonServices } from '@pikku/core/state'
 
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { SerializePlugin } from './serialize-plugin.js'

package/src/kysely-webhook-service.ts

@@ -1,4 +1,5 @@
 import { QueueWebhookService } from '@pikku/core/services'
+import type { QueueService } from '@pikku/core/queue'
 import {
   PIKKU_OUTGOING_WEBHOOK_QUEUE_NAME,
   type SendWebhookInput,
@@ -6,8 +7,7 @@ import {
   type WebhookAttemptResult,
   type WebhookDeliveryRecord,
   type WebhookDeliveryWithAttempts,
-} from '@pikku/core/ecosystem/services'
-import type { QueueService } from '@pikku/core/queue'
+} from '@pikku/core/services'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { ensurePikkuSchema } from './schema/index.js'

package/src/kysely-workflow-mirror.ts

@@ -1,4 +1,4 @@
-import type { SerializedError } from '@pikku/core/ecosystem/types'
+import type { SerializedError } from '@pikku/core/errors'
 import type {
   StepState,
   WorkflowRunMirror,
@@ -6,7 +6,7 @@ import type {
   WorkflowStatus,
   WorkflowPlannedStep,
   WorkflowVersionStatus,
-} from '@pikku/core/ecosystem/workflow'
+} from '@pikku/core/workflow'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { ensurePikkuSchema } from './schema/index.js'

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

@@ -3,7 +3,7 @@ import type {
   StepState,
   WorkflowStatus,
   WorkflowRunService,
-} from '@pikku/core/ecosystem/workflow'
+} from '@pikku/core/workflow'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { parseJson } from './kysely-json.js'

package/src/kysely-workflow-service.test.ts

@@ -3,6 +3,7 @@ import assert from 'node:assert/strict'
 import { CamelCasePlugin, Kysely, SqliteDialect, sql } from 'kysely'
 import Database from 'better-sqlite3'
 
+import type { StepState } from '@pikku/core/ecosystem/workflow'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { SerializePlugin } from './serialize-plugin.js'
 import { KyselyWorkflowService } from './kysely-workflow-service.js'
@@ -429,3 +430,113 @@ describe('KyselyWorkflowService — a transition that addresses no history row',
   })
 })
 
+/**
+ * Dispatch is at-least-once — the relay re-dispatches a step it believes was
+ * dropped, and a queue can redeliver a job it already handed out — so the claim
+ * is the only thing standing between a duplicate dispatch and a second
+ * execution of a side-effecting step.
+ */
+describe('KyselyWorkflowService — claiming a step for execution', () => {
+  const claim = (runId: string, stepName: string, rpcName = 'rpc.fn') =>
+    (service as any).claimStepForExecution(
+      runId,
+      stepName,
+      rpcName
+    ) as Promise<StepState | null>
+
+  test('two dispatches racing for the same pending step: exactly one wins', async () => {
+    const runId = await seedRun()
+    await service.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+
+    const claims = await Promise.all([claim(runId, 's1'), claim(runId, 's1')])
+    const winners = claims.filter((c) => c !== null)
+
+    assert.equal(
+      winners.length,
+      1,
+      `both dispatches claimed the step, so a side-effecting step would run twice: ${JSON.stringify(claims)}`
+    )
+    assert.equal((await service.getStepState(runId, 's1')).status, 'running')
+  })
+
+  test('two dispatches racing to retry the same failed step: exactly one wins', async () => {
+    const runId = await seedRun()
+    const step = await service.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+    await service.setStepRunning(step.stepId)
+    await service.setStepError(step.stepId, new Error('boom'))
+
+    const claims = await Promise.all([claim(runId, 's1'), claim(runId, 's1')])
+    const winners = claims.filter((c) => c !== null)
+
+    assert.equal(
+      winners.length,
+      1,
+      `both dispatches started a retry, so the failed step would be retried twice concurrently: ${JSON.stringify(claims)}`
+    )
+    assert.equal(
+      (await service.getStepState(runId, 's1')).attemptCount,
+      2,
+      'the retry raced itself and burned more than one attempt'
+    )
+  })
+
+  test('a step already claimed is not claimable again', async () => {
+    const runId = await seedRun()
+    await service.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+
+    assert.notEqual(await claim(runId, 's1'), null)
+    assert.equal(
+      await claim(runId, 's1'),
+      null,
+      'a redelivered job re-claimed a step that is already running'
+    )
+  })
+
+  test('a succeeded step is not claimable', async () => {
+    const runId = await seedRun()
+    const step = await service.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+    await service.setStepRunning(step.stepId)
+    await service.setStepResult(step.stepId, { ok: true })
+
+    assert.equal(await claim(runId, 's1'), null)
+  })
+
+  test('a claim that fails releases the step, so it is retryable', async () => {
+    const runId = await seedRun()
+    const step = await service.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+
+    const first = await claim(runId, 's1')
+    assert.notEqual(first, null)
+    await service.setStepError(step.stepId, new Error('boom'))
+
+    const retry = await claim(runId, 's1')
+    assert.notEqual(
+      retry,
+      null,
+      'the failed step stayed claimed, so it can never be retried'
+    )
+    assert.equal(retry?.status, 'running')
+    assert.equal(retry?.attemptCount, 2)
+  })
+
+  test('a claim for a different function than the step was dispatched with is refused', async () => {
+    const runId = await seedRun()
+    await service.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+
+    await assert.rejects(() => claim(runId, 's1', 'rpc.other'))
+    assert.equal(
+      (await service.getStepState(runId, 's1')).status,
+      'pending',
+      'the mismatched claim moved the step anyway'
+    )
+  })
+
+  test('a scheduled step is claimable, and only once', async () => {
+    const runId = await seedRun()
+    const step = await service.insertStepState(runId, 's1', 'rpc.fn', { x: 1 })
+    await service.setStepScheduled(step.stepId)
+
+    const claims = await Promise.all([claim(runId, 's1'), claim(runId, 's1')])
+    assert.equal(claims.filter((c) => c !== null).length, 1)
+  })
+})

package/src/kysely-workflow-service.ts

@@ -1,6 +1,18 @@
-import type { SerializedError } from '@pikku/core/ecosystem/types'
-import { PikkuWorkflowService } from '@pikku/core/workflow'
-import type { WorkflowPlannedStep, WorkflowQueueOptions, WorkflowRun, WorkflowRunWire, StepState, StepStatus, WorkflowStatus, WorkflowVersionStatus } from '@pikku/core/ecosystem/workflow'
+import type { SerializedError } from '@pikku/core/errors'
+import {
+  PikkuWorkflowService,
+  WorkflowStepFunctionMismatchError,
+} from '@pikku/core/workflow'
+import type {
+  WorkflowPlannedStep,
+  WorkflowQueueOptions,
+  WorkflowRun,
+  WorkflowRunWire,
+  StepState,
+  StepStatus,
+  WorkflowStatus,
+  WorkflowVersionStatus,
+} from '@pikku/core/workflow'
 import { sql, type Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import { KyselyWorkflowRunService } from './kysely-workflow-run-service.js'
@@ -451,6 +463,16 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
     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<T>(
     _runId: string,
     _stepName: string,
@@ -459,6 +481,79 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
     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.
+   */
+  protected override async claimStepForExecution(
+    runId: string,
+    stepName: string,
+    rpcName: string
+  ): Promise<StepState | null> {
+    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.
+   */
+  private async claimStepStatus(
+    stepId: string,
+    from: StepStatus[]
+  ): Promise<boolean> {
+    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: string): Promise<{
     completedNodeIds: string[]
     failedNodeIds: string[]
@@ -597,16 +692,18 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
   }
 
   /**
-   * 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 async queryUndispatchedSteps(
+  protected override async findUndispatchedSteps(
     before: Date,
     limit: number
   ): Promise<Array<{ runId: string; stepId: string }>> {

package/dist/src/kysely-ai-agent-run-service.d.ts

@@ -1,22 +0,0 @@
-import type { AIThread, AIMessage } from '@pikku/core/ai-agent';
-import type { AgentRunRow, AgentRunService } from '@pikku/core/ecosystem/ai-agent';
-import type { Kysely } from 'kysely';
-import type { KyselyPikkuDB } from './kysely-tables.js';
-export declare class KyselyAgentRunService implements AgentRunService {
-    private db;
-    constructor(db: Kysely<KyselyPikkuDB>);
-    listThreads(options?: {
-        agentName?: string;
-        resourceId?: string;
-        owners?: string[];
-        limit?: number;
-        offset?: number;
-    }): Promise<AIThread[]>;
-    getThread(threadId: string): Promise<AIThread | null>;
-    getThreadMessages(threadId: string): Promise<AIMessage[]>;
-    getThreadRuns(threadId: string): Promise<AgentRunRow[]>;
-    deleteThread(threadId: string): Promise<boolean>;
-    getDistinctAgentNames(): Promise<string[]>;
-    private mapThreadRow;
-    private mapRunRow;
-}