@sixb/core 0.1.11 → 0.1.13

package/src/testing/workflow-intervention-storage-contract.ts

@@ -0,0 +1,203 @@
+import { describe, expect, test } from "bun:test"
+import type { Principal } from "../auth"
+import {
+  type CreateWorkflowInterventionInput,
+  WorkflowInterventionError,
+  type WorkflowInterventionStorage,
+} from "../storage/workflow-interventions"
+
+export interface WorkflowInterventionStorageContractSuiteOptions<
+  TStorage extends WorkflowInterventionStorage = WorkflowInterventionStorage,
+> {
+  readonly createStorage: () => TStorage | Promise<TStorage>
+  readonly cleanup?: (storage: TStorage) => void | Promise<void>
+}
+
+const projectId = "workflow-intervention-contract"
+
+/** Provider-neutral lifecycle, paging, and principal-attribution contract for interventions. */
+export function runWorkflowInterventionStorageContractSuite<
+  TStorage extends WorkflowInterventionStorage,
+>(label: string, options: WorkflowInterventionStorageContractSuiteOptions<TStorage>): void {
+  const withStorage = async (run: (storage: TStorage) => Promise<void>): Promise<void> => {
+    const storage = await options.createStorage()
+    try {
+      await run(storage)
+    } finally {
+      await options.cleanup?.(storage)
+    }
+  }
+
+  describe(label, () => {
+    test("creates pending interventions and supports filtered paging", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(interventionInput({ id: "intervention-1", requestedAt: at("10:00") }))
+        await storage.create(
+          interventionInput({
+            id: "intervention-2",
+            workflowRunId: "run-2",
+            requestedAt: at("11:00"),
+          })
+        )
+        await storage.submit({ projectId, id: "intervention-2", response: { decision: "approve" } })
+        await storage.create(
+          interventionInput({
+            projectId: "other-project",
+            id: "other-project",
+            requestedAt: at("12:00"),
+          })
+        )
+
+        const stored = await storage.getById({ projectId, id: "intervention-1" })
+        const page = await storage.list({
+          projectId,
+          statuses: ["pending"],
+          workflowId: "review-workflow",
+          interventionId: "review-draft-document",
+          requestedAfter: at("09:00"),
+          order: "asc",
+          limit: 1,
+        })
+
+        expect(stored).toMatchObject({
+          id: "intervention-1",
+          status: "pending",
+          input: { draftId: "draft-1" },
+          defaultResponse: { decision: "approve" },
+        })
+        expect(stored?.requestedAt.toISOString()).toBe(at("10:00").toISOString())
+        expect(page.total).toBe(1)
+        expect(page.hasMore).toBe(false)
+        expect(page.interventions.map((intervention) => intervention.id)).toEqual([
+          "intervention-1",
+        ])
+        await expect(storage.list({ projectId, statuses: [] })).resolves.toEqual({
+          interventions: [],
+          hasMore: false,
+          total: 0,
+        })
+      })
+    })
+
+    test("submits, cancels, expires, and rejects invalid transitions", async () => {
+      await withStorage(async (storage) => {
+        await storage.create(interventionInput({ id: "submit-me" }))
+        const submitted = await storage.submit({
+          projectId,
+          id: "submit-me",
+          submittedAt: at("12:00"),
+          submittedBy: { type: "user", id: "usr_1" },
+          response: { decision: "approve", reviewerNote: "Looks good." },
+        })
+
+        await storage.create(interventionInput({ id: "cancel-me" }))
+        const cancelled = await storage.cancel({
+          projectId,
+          id: "cancel-me",
+          cancelledAt: at("12:30"),
+          cancelledBy: { type: "system", id: "workflow-timeout" },
+        })
+
+        await storage.create(interventionInput({ id: "expire-me" }))
+        const expired = await storage.expire({ projectId, id: "expire-me", expiredAt: at("13:00") })
+
+        expect(submitted).toMatchObject({
+          status: "submitted",
+          response: { decision: "approve", reviewerNote: "Looks good." },
+          submittedBy: { type: "user", id: "usr_1" },
+        })
+        expect(submitted.submittedAt?.toISOString()).toBe(at("12:00").toISOString())
+        expect(cancelled).toMatchObject({
+          status: "cancelled",
+          cancelledBy: { type: "system", id: "workflow-timeout" },
+        })
+        expect(cancelled.cancelledAt?.toISOString()).toBe(at("12:30").toISOString())
+        expect(expired.status).toBe("expired")
+        expect(expired.expiredAt?.toISOString()).toBe(at("13:00").toISOString())
+
+        await expect(storage.cancel({ projectId, id: "submit-me" })).rejects.toBeInstanceOf(
+          WorkflowInterventionError
+        )
+        await expect(
+          storage.submit({ projectId, id: "missing", response: {} })
+        ).rejects.toBeInstanceOf(WorkflowInterventionError)
+        await expect(storage.create(interventionInput({ id: "submit-me" }))).rejects.toBeInstanceOf(
+          WorkflowInterventionError
+        )
+        await expect(
+          storage.create(interventionInput({ id: "bad-index", nodeIndex: -1 }))
+        ).rejects.toBeInstanceOf(WorkflowInterventionError)
+      })
+    })
+
+    test("persists submitting and cancelling principals as { type, id }", async () => {
+      await withStorage(async (storage) => {
+        const principals: readonly Principal[] = [
+          { type: "user", id: "usr_1" },
+          { type: "serviceAccount", id: "sa_1" },
+          { type: "system", id: "system" },
+        ]
+        for (const [index, principal] of principals.entries()) {
+          await storage.create(
+            interventionInput({ id: `submit-${principal.type}`, requestedAt: at(`10:0${index}`) })
+          )
+          await storage.submit({
+            projectId,
+            id: `submit-${principal.type}`,
+            response: {},
+            submittedBy: principal,
+          })
+          await storage.create(interventionInput({ id: `cancel-${principal.type}` }))
+          await storage.cancel({
+            projectId,
+            id: `cancel-${principal.type}`,
+            cancelledBy: principal,
+          })
+        }
+        await storage.create(interventionInput({ id: "anonymous" }))
+        await storage.submit({ projectId, id: "anonymous", response: {} })
+
+        for (const principal of principals) {
+          const submitted = await storage.getById({ projectId, id: `submit-${principal.type}` })
+          const cancelled = await storage.getById({ projectId, id: `cancel-${principal.type}` })
+          expect(submitted?.submittedBy).toStrictEqual(principal)
+          expect(cancelled?.cancelledBy).toStrictEqual(principal)
+        }
+        const anonymous = await storage.getById({ projectId, id: "anonymous" })
+        expect(anonymous?.submittedBy).toBeUndefined()
+        expect(anonymous?.cancelledBy).toBeUndefined()
+
+        const listed = await storage.list({ projectId, statuses: ["submitted"], order: "asc" })
+        expect(
+          listed.interventions.flatMap((intervention) =>
+            intervention.submittedBy ? [intervention.submittedBy] : []
+          )
+        ).toStrictEqual([...principals])
+      })
+    })
+  })
+}
+
+function interventionInput(
+  overrides: Partial<CreateWorkflowInterventionInput> = {}
+): CreateWorkflowInterventionInput {
+  return {
+    id: "intervention-1",
+    projectId,
+    workflowId: "review-workflow",
+    workflowRunId: "run-1",
+    nodeRunId: "node-1",
+    nodeIndex: 0,
+    nodeId: "review-draft-document",
+    nodeKey: "reviewDraftDocument",
+    interventionId: "review-draft-document",
+    input: { draftId: "draft-1" },
+    defaultResponse: { decision: "approve" },
+    requestedAt: at("10:00"),
+    ...overrides,
+  }
+}
+
+function at(time: string): Date {
+  return new Date(`2026-05-08T${time}:00.000Z`)
+}

package/src/webhooks/types.ts

@@ -1,6 +1,6 @@
 import type { ConnectorConnectionMetadata, ConnectorDefinition } from "../connectors/types"
 import type { Logger } from "../logging"
-import type { OntologySource, Sixb } from "../runtime"
+import type { Sixb } from "../runtime"
 
 export type WebhookBodyFormat = "json" | "text" | "raw"
 
@@ -57,7 +57,7 @@ export interface WebhookVerifyContext {
 
 /** Handler input bound to the durable Webhook run admitted for this delivery. */
 export interface WebhookHandlerContext<TBody, TClient> extends WebhookVerifyContext {
-  readonly sixb: Sixb<readonly OntologySource[]>
+  readonly sixb: Sixb
   readonly logger: Logger
   readonly body: TBody
   /** Resolve selected managed connections for an external account in this connector. */

package/src/workflows/failure.ts

@@ -1,5 +1,5 @@
+import { withFailureMessage } from "../errors/failure-message"
 import { createSixbError, isSixbError, summarizeErrorMessage } from "../errors/internal"
-import type { ReadonlyJsonObject } from "../json"
 import {
   ModelProviderError,
   StructuredOutputError,
@@ -29,21 +29,27 @@ export interface WorkflowNodeFailureIdentity extends WorkflowNodeFailureIdentity
 
 /** Translate a node-local failure into the workflow primitive's durable vocabulary. */
 export function createWorkflowNodeFailure(error: unknown, identity: WorkflowNodeFailureIdentity) {
-  return createSixbError(
+  const modelDetails = safeModelFailureDetails(error)
+  const failure = createSixbError(
     "workflow.node_failed",
     summarizeErrorMessage(error, "Workflow node execution failed."),
     {
       cause: error,
       details: {
         ...workflowNodeFailureDetails(identity),
-        ...safeModelFailureDetails(error),
+        ...modelDetails,
       },
     }
   )
+  return modelDetails.modelFailure
+    ? withFailureMessage(failure, modelDetails.modelFailure.message)
+    : failure
 }
 
 /** Only controlled diagnostics cross the durable boundary; provider messages/output stay private. */
-function safeModelFailureDetails(error: unknown): ReadonlyJsonObject {
+function safeModelFailureDetails(error: unknown): {
+  modelFailure?: { source: string; reason: string; message: string; status?: number }
+} {
   if (error instanceof UnsupportedModelFeatureError) {
     const reason = error.reason ?? "unsupported-feature"
     const messages = {

package/src/workflows/run-dispatch.ts

@@ -6,9 +6,10 @@ import { captureSixbFailure } from "../errors/internal"
 import type { DomainEventLog } from "../events"
 import type { RunDispatcher } from "../execution/dispatch"
 import { createPrimitiveExecutionRecord } from "../execution/durable"
-import type { ValueType } from "../ontology"
+import type { SchemaOrRef, ValueType } from "../ontology"
 import type { Queues } from "../queues"
 import type { SixbDefinitions } from "../runtime/definitions"
+import { assertParamUsersActive } from "../shared/params/user-refs"
 import type { CreateExecutionInput, Storage, WorkflowRunRecord } from "../storage"
 import { WORKFLOW_RUN_FAILURE_CODES, WorkflowRunError } from "../storage"
 import { WorkflowValidationError } from "./errors"
@@ -172,6 +173,16 @@ async function persistWorkflowRun(
     return { run: existing, created: false }
   }
 
+  // A replayed run keeps the input it was accepted with; only a new run checks its users.
+  await assertParamUsersActive({
+    auth: input.storage.auth,
+    projectId: input.projectId,
+    schemas: input.workflow.input as Readonly<Record<string, SchemaOrRef>>,
+    values: request.snapshot,
+    valueTypesById: input.valueTypesById,
+    describe: (fieldId) => `Workflow "${input.workflow.id}" input '${fieldId}'`,
+    invalid: (message) => new WorkflowValidationError(message),
+  })
   const execution = await input.createExecution(`exec_${randomUUID()}`, request.runId)
   const queuedAt = new Date()
   try {

package/src/workflows/snapshot.ts

@@ -234,14 +234,23 @@ function snapshotSchemaValue(params: {
   const { schema, value, path, valueTypesById } = params
 
   if (typeof schema === "string") {
-    if (schema === "date" || schema === "timestamp") {
-      if (value instanceof Date) {
-        return snapshotDate(value, path)
-      }
-      return snapshotJsonValue(value, path)
+    switch (schema) {
+      case "date":
+      case "timestamp":
+        return value instanceof Date ? snapshotDate(value, path) : snapshotJsonValue(value, path)
+      case "string":
+      case "uuid":
+      case "integer":
+      case "double":
+      case "decimal":
+      case "boolean":
+      case "fileRef":
+      case "userRef":
+        return snapshotJsonValue(value, path)
+      default:
+        schema satisfies never
+        return snapshotJsonValue(value, path)
     }
-
-    return snapshotJsonValue(value, path)
   }
 
   if (schema.type === "enum") {

package/src/workflows/types.ts

@@ -18,7 +18,7 @@ import type { LogsRuntime } from "../logging/execution"
 import type { ModelsRuntime } from "../models/generation-types"
 import type { LanguageModel } from "../models/language-model"
 import type { ObjectsRuntime } from "../objects/execution"
-import type { InferSchemaOrRef, ObjectRef, OntologySource, SchemaOrRef } from "../ontology"
+import type { InferSchemaOrRef, ObjectRef, SchemaOrRef } from "../ontology"
 import type { PipelinesRuntime } from "../pipelines/execution"
 import type { ProjectionsRuntime } from "../projections/execution"
 import type { RulesRuntime } from "../rules/execution"
@@ -62,7 +62,7 @@ export interface StepRunContext<TInput extends Record<string, unknown>> {
  */
 export interface WorkflowRuntimeFacade {
   readonly models: ModelsRuntime
-  readonly objects: ObjectsRuntime<readonly OntologySource[]>
+  readonly objects: ObjectsRuntime
   readonly actions: ActionsRuntime
   readonly agent: AgentRuntime
   readonly datasets: DatasetsRuntime

package/src/workflows/validation.ts

@@ -172,14 +172,14 @@ function validateWorkflowAgentStepRuntimeReferences(
   step: AgentStepDefinition,
   options: { readonly models?: ModelCatalog; readonly tools: AgentToolCatalog }
 ): void {
-  if (step.model === undefined && options.models === undefined) {
+  if (step.model === undefined && options.models?.language === undefined) {
     throw new WorkflowDefinitionError(
       `Workflow "${workflowId}" agent step "${step.id}" needs a model. Configure 'models.language' or pass 'model' to defineAgentStep().`
     )
   }
   if (step.model !== undefined && options.models !== undefined) {
     const ref = { provider: step.model.providerId, modelId: step.model.modelId }
-    if (options.models.language.getByRef(ref) === null) {
+    if (options.models.language?.getByRef(ref) == null) {
       throw new WorkflowDefinitionError(
         `Workflow "${workflowId}" agent step "${step.id}" uses unknown language model "${ref.provider}/${ref.modelId}". Add it to 'models.language' in createSixb().`
       )