@sixb/core 0.1.0 → 0.1.2

package/src/storage/webhook-runs/in-memory.ts

@@ -1,3 +1,5 @@
+import { parseSixbFailure } from "../../errors/internal"
+import type { ExecutionStorage } from "../executions"
 import {
   cloneRecord,
   compareStartedAt,
@@ -8,18 +10,23 @@ import {
   toStatusSet,
 } from "../run-listing"
 import { WebhookRunError } from "./errors"
+import { assertWebhookRunExecution } from "./provider"
 import type {
   FinishWebhookRunInput,
   ListWebhookRunsInput,
   ListWebhookRunsResult,
+  RestartWebhookRunInput,
   StartWebhookRunInput,
   WebhookRunRecord,
   WebhookRunStorage,
 } from "./types"
+import { canRetryWebhookRun, WEBHOOK_RUN_FAILURE_CODES } from "./types"
 
 export class InMemoryWebhookRunStorage implements WebhookRunStorage {
   private readonly runs = new Map<string, WebhookRunRecord>()
 
+  constructor(private readonly executions: ExecutionStorage) {}
+
   snapshot(): InMemoryWebhookRunStorageSnapshot {
     return structuredClone(this.runs)
   }
@@ -32,39 +39,71 @@ export class InMemoryWebhookRunStorage implements WebhookRunStorage {
   }
 
   async start(input: StartWebhookRunInput): Promise<WebhookRunRecord> {
+    await assertWebhookRunExecution({
+      executions: this.executions,
+      projectId: input.projectId,
+      executionId: input.executionId,
+      runId: input.id,
+      route: input.route,
+    })
     const key = storageKey(input.projectId, input.id)
-    if (this.runs.has(key)) {
+    if (this.runs.has(key) || this.findByDelivery(input)) {
       throw new WebhookRunError(
-        `[Sixb] Webhook run '${input.id}' already exists for project '${input.projectId}'.`
+        `[Sixb] Webhook run '${input.id}' or delivery key already exists for project '${input.projectId}'.`,
+        "duplicate_run"
       )
     }
 
     const record: WebhookRunRecord = {
       id: input.id,
       projectId: input.projectId,
+      executionId: input.executionId,
       connectorId: input.connectorId,
       webhookId: input.webhookId,
       status: "running",
       method: input.method,
       route: input.route,
       startedAt: new Date(input.startedAt ?? new Date()),
+      requestBodyBytes: input.requestBodyBytes,
+      requestBodySha256: input.requestBodySha256,
+      idempotencyKey: input.idempotencyKey,
     }
 
     this.runs.set(key, cloneRecord(record))
     return cloneRecord(record)
   }
 
+  async restart(input: RestartWebhookRunInput): Promise<WebhookRunRecord> {
+    const existing = this.requireWebhookRun(input.projectId, input.id)
+    if (!canRetryWebhookRun(existing)) {
+      throw new WebhookRunError(
+        `[Sixb] Webhook run '${input.id}' cannot restart from status '${existing.status}'.`,
+        "invalid_transition"
+      )
+    }
+    const next: WebhookRunRecord = {
+      ...existing,
+      status: "running",
+      startedAt: new Date(input.startedAt ?? new Date()),
+      finishedAt: undefined,
+      responseStatus: undefined,
+      error: undefined,
+    }
+    this.runs.set(storageKey(input.projectId, input.id), cloneRecord(next))
+    return cloneRecord(next)
+  }
+
   async finish(input: FinishWebhookRunInput): Promise<WebhookRunRecord> {
     const existing = this.requireRunningWebhookRun(input.projectId, input.id)
     const next: WebhookRunRecord = {
       ...existing,
       status: input.status,
       finishedAt: new Date(input.finishedAt ?? new Date()),
-      requestBodyBytes: input.requestBodyBytes,
       responseStatus: input.responseStatus,
-      idempotencyKey: input.idempotencyKey,
-      deliveryClaimResult: input.deliveryClaimResult,
-      error: input.status === "succeeded" ? undefined : input.error,
+      error:
+        input.status === "failed"
+          ? parseSixbFailure(input.error, WEBHOOK_RUN_FAILURE_CODES)
+          : undefined,
     }
 
     this.runs.set(storageKey(input.projectId, input.id), cloneRecord(next))
@@ -76,6 +115,16 @@ export class InMemoryWebhookRunStorage implements WebhookRunStorage {
     return record ? cloneRecord(record) : null
   }
 
+  async getByDelivery(input: {
+    projectId: string
+    connectorId: string
+    webhookId: string
+    idempotencyKey: string
+  }): Promise<WebhookRunRecord | null> {
+    const record = this.findByDelivery(input)
+    return record ? cloneRecord(record) : null
+  }
+
   async list(input: ListWebhookRunsInput): Promise<ListWebhookRunsResult> {
     if (hasEmptyStatuses(input)) {
       return {
@@ -112,20 +161,46 @@ export class InMemoryWebhookRunStorage implements WebhookRunStorage {
     }
   }
 
-  private requireRunningWebhookRun(projectId: string, id: string): WebhookRunRecord {
+  private requireWebhookRun(projectId: string, id: string): WebhookRunRecord {
     const record = this.runs.get(storageKey(projectId, id))
     if (!record) {
-      throw new WebhookRunError(`[Sixb] Webhook run '${id}' not found for project '${projectId}'.`)
+      throw new WebhookRunError(
+        `[Sixb] Webhook run '${id}' not found for project '${projectId}'.`,
+        "not_found"
+      )
     }
 
+    return record
+  }
+
+  private requireRunningWebhookRun(projectId: string, id: string): WebhookRunRecord {
+    const record = this.requireWebhookRun(projectId, id)
+
     if (record.status !== "running") {
       throw new WebhookRunError(
-        `[Sixb] Webhook run '${id}' for project '${projectId}' is already terminal.`
+        `[Sixb] Webhook run '${id}' for project '${projectId}' is already terminal.`,
+        "invalid_transition"
       )
     }
 
     return record
   }
+
+  private findByDelivery(input: {
+    readonly projectId: string
+    readonly connectorId: string
+    readonly webhookId: string
+    readonly idempotencyKey?: string
+  }): WebhookRunRecord | undefined {
+    if (input.idempotencyKey === undefined) return undefined
+    return [...this.runs.values()].find(
+      (run) =>
+        run.projectId === input.projectId &&
+        run.connectorId === input.connectorId &&
+        run.webhookId === input.webhookId &&
+        run.idempotencyKey === input.idempotencyKey
+    )
+  }
 }
 
 export type InMemoryWebhookRunStorageSnapshot = Map<string, WebhookRunRecord>

package/src/storage/webhook-runs/index.ts

@@ -1,12 +1,16 @@
-export { WebhookRunError } from "./errors"
+export { WebhookRunError, type WebhookRunErrorCode } from "./errors"
 export { InMemoryWebhookRunStorage } from "./in-memory"
 export type {
   FinishWebhookRunInput,
   FinishWebhookRunStatus,
+  GetWebhookRunByDeliveryInput,
   ListWebhookRunsInput,
   ListWebhookRunsResult,
+  RestartWebhookRunInput,
   StartWebhookRunInput,
+  WebhookRunFailureCode,
   WebhookRunRecord,
   WebhookRunStatus,
   WebhookRunStorage,
 } from "./types"
+export { canRetryWebhookRun, WEBHOOK_RUN_FAILURE_CODES } from "./types"

package/src/storage/webhook-runs/provider.ts

@@ -0,0 +1,30 @@
+import type { ExecutionStorage } from "../executions"
+import { findPrimitiveRunExecution } from "../executions/run-link"
+import { WebhookRunError } from "./errors"
+
+/** Validate the semantic link between a durable Webhook delivery and its immutable execution. */
+export async function assertWebhookRunExecution(input: {
+  readonly executions: ExecutionStorage
+  readonly projectId: string
+  readonly executionId: string
+  readonly runId: string
+  readonly route: string
+}): Promise<void> {
+  const execution = await findPrimitiveRunExecution({
+    executions: input.executions,
+    projectId: input.projectId,
+    executionId: input.executionId,
+    primitive: { kind: "webhook", id: input.route, runId: input.runId },
+    sourceTypes: ["webhook"],
+  })
+  if (
+    !execution ||
+    execution.source.type !== "webhook" ||
+    execution.source.deliveryId !== input.runId
+  ) {
+    throw new WebhookRunError(
+      `[Sixb] Execution '${input.executionId}' does not authorize Webhook run '${input.runId}'.`,
+      "invalid_execution"
+    )
+  }
+}

package/src/storage/webhook-runs/types.ts

@@ -1,11 +1,21 @@
-import type { WebhookDeliveryClaimResult } from "../webhook-deliveries"
+import type { SixbErrorCode, SixbFailure } from "../../errors/types"
 
-export type WebhookRunStatus = "running" | "succeeded" | "failed" | "skipped"
+export type WebhookRunStatus = "running" | "succeeded" | "failed"
 export type FinishWebhookRunStatus = Exclude<WebhookRunStatus, "running">
 
+/** Error codes a webhook run can persist and expose through its public contract. */
+export const WEBHOOK_RUN_FAILURE_CODES = [
+  "internal.unexpected",
+  "webhook.delivery_failed",
+  "webhook.delivery_rejected",
+] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]
+
+export type WebhookRunFailureCode = (typeof WEBHOOK_RUN_FAILURE_CODES)[number]
+
 export interface WebhookRunRecord {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly connectorId: string
   readonly webhookId: string
   readonly status: WebhookRunStatus
@@ -13,33 +23,57 @@ export interface WebhookRunRecord {
   readonly route: string
   readonly startedAt: Date
   readonly finishedAt?: Date
-  readonly requestBodyBytes?: number
+  readonly requestBodyBytes: number
+  readonly requestBodySha256: string
   readonly responseStatus?: number
   readonly idempotencyKey?: string
-  readonly deliveryClaimResult?: WebhookDeliveryClaimResult
-  readonly error?: string
+  readonly error?: SixbFailure<WebhookRunFailureCode>
 }
 
 export interface StartWebhookRunInput {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly connectorId: string
   readonly webhookId: string
   readonly method: string
   readonly route: string
+  readonly requestBodyBytes: number
+  readonly requestBodySha256: string
+  readonly idempotencyKey?: string
   readonly startedAt?: Date
 }
 
-export interface FinishWebhookRunInput {
+export interface RestartWebhookRunInput {
+  readonly id: string
+  readonly projectId: string
+  readonly startedAt?: Date
+}
+
+interface FinishWebhookRunBaseInput {
   readonly id: string
   readonly projectId: string
-  readonly status: FinishWebhookRunStatus
   readonly finishedAt?: Date
-  readonly requestBodyBytes?: number
   readonly responseStatus?: number
-  readonly idempotencyKey?: string
-  readonly deliveryClaimResult?: WebhookDeliveryClaimResult
-  readonly error?: string
+}
+
+export type FinishWebhookRunInput = FinishWebhookRunBaseInput &
+  (
+    | {
+        readonly status: "succeeded"
+        readonly error?: never
+      }
+    | {
+        readonly status: "failed"
+        readonly error: SixbFailure<WebhookRunFailureCode>
+      }
+  )
+
+export interface GetWebhookRunByDeliveryInput {
+  readonly projectId: string
+  readonly connectorId: string
+  readonly webhookId: string
+  readonly idempotencyKey: string
 }
 
 export interface ListWebhookRunsInput {
@@ -63,7 +97,14 @@ export interface ListWebhookRunsResult {
 
 export interface WebhookRunStorage {
   start(input: StartWebhookRunInput): Promise<WebhookRunRecord>
+  restart(input: RestartWebhookRunInput): Promise<WebhookRunRecord>
   finish(input: FinishWebhookRunInput): Promise<WebhookRunRecord>
   getById(params: { projectId: string; id: string }): Promise<WebhookRunRecord | null>
+  getByDelivery(input: GetWebhookRunByDeliveryInput): Promise<WebhookRunRecord | null>
   list(input: ListWebhookRunsInput): Promise<ListWebhookRunsResult>
 }
+
+/** Provider retries may reopen only failures classified as retryable by the shared error policy. */
+export function canRetryWebhookRun(run: WebhookRunRecord): boolean {
+  return run.status === "failed" && run.error?.retryable === true
+}

package/src/storage/workflow-runs/in-memory.ts

@@ -1,4 +1,9 @@
-import { SYSTEM_PRINCIPAL } from "../../auth"
+import { normalizeRequesterGroupIds } from "../../auth/attribution"
+import { parseSixbFailure } from "../../errors/internal"
+import type { SixbFailure } from "../../errors/types"
+import type { AgentRunFailureCode } from "../agents"
+import { AGENT_RUN_FAILURE_CODES } from "../agents"
+import type { ExecutionStorage } from "../executions"
 import {
   cloneRecord,
   compareStartedAt,
@@ -10,6 +15,7 @@ import {
   toStatusSet,
 } from "../run-listing"
 import { WorkflowRunError } from "./errors"
+import { assertWorkflowAgentNodeRunExecution, assertWorkflowRunExecution } from "./provider"
 import type {
   CancelWorkflowAgentNodeRunInput,
   ConfirmWorkflowAgentNodeRunExecutionOwnershipInput,
@@ -39,9 +45,23 @@ import type {
   WorkflowAgentNodeRunStorage,
   WorkflowNodeRunRecord,
   WorkflowNodeRunStorage,
+  WorkflowRunFailureCode,
   WorkflowRunRecord,
   WorkflowRunStorage,
 } from "./types"
+import { WORKFLOW_RUN_FAILURE_CODES } from "./types"
+
+function normalizeFailure(
+  failure: SixbFailure<WorkflowRunFailureCode> | undefined
+): SixbFailure<WorkflowRunFailureCode> | undefined {
+  return failure ? parseSixbFailure(failure, WORKFLOW_RUN_FAILURE_CODES) : undefined
+}
+
+function normalizeAgentFailure(
+  failure: SixbFailure<AgentRunFailureCode> | undefined
+): SixbFailure<AgentRunFailureCode> | undefined {
+  return failure ? parseSixbFailure(failure, AGENT_RUN_FAILURE_CODES) : undefined
+}
 
 function assertNonNegativeInteger(value: number, fieldName: string): void {
   if (!Number.isInteger(value) || value < 0) {
@@ -55,16 +75,20 @@ export class InMemoryWorkflowRunStorage implements WorkflowRunStorage {
 
   private readonly runs = new Map<string, WorkflowRunRecord>()
 
-  constructor() {
+  constructor(private readonly executions: ExecutionStorage) {
     this.nodes = new InMemoryWorkflowNodeRunStorage({
       requireRunningWorkflowRun: (projectId, id) => this.requireRunningWorkflowRun(projectId, id),
       requireActiveWorkflowRun: (projectId, id) => this.requireActiveWorkflowRun(projectId, id),
       assertExecutionOwnership: (projectId, id, token) =>
         this.assertExecutionOwnership(projectId, id, token),
     })
-    this.agentNodes = new InMemoryWorkflowAgentNodeRunStorage({
-      requireAgentNodeRun: (projectId, id) => this.nodes.requireAgentNodeRun(projectId, id),
-    })
+    this.agentNodes = new InMemoryWorkflowAgentNodeRunStorage(
+      {
+        requireAgentNodeRun: (projectId, id) => this.nodes.requireAgentNodeRun(projectId, id),
+        requireWorkflowRun: (projectId, id) => this.requireExistingWorkflowRun(projectId, id),
+      },
+      this.executions
+    )
   }
 
   snapshot(): InMemoryWorkflowRunStorageSnapshot {
@@ -91,19 +115,35 @@ export class InMemoryWorkflowRunStorage implements WorkflowRunStorage {
         `[Sixb] Workflow run '${input.id}' already exists for project '${input.projectId}'.`
       )
     }
+    if (
+      [...this.runs.values()].some(
+        (run) => run.projectId === input.projectId && run.executionId === input.executionId
+      )
+    ) {
+      throw new WorkflowRunError(
+        `[Sixb] Execution '${input.executionId}' already belongs to another workflow run.`
+      )
+    }
+    await assertWorkflowRunExecution({
+      executions: this.executions,
+      projectId: input.projectId,
+      executionId: input.executionId,
+      runId: input.id,
+      workflowId: input.workflowId,
+    })
 
     const queuedAt = new Date(input.queuedAt ?? new Date())
     const record: WorkflowRunRecord = {
       id: input.id,
       projectId: input.projectId,
+      executionId: input.executionId,
       workflowId: input.workflowId,
       status: "queued",
       input: cloneRecord(input.input),
       queuedAt,
       startedAt: queuedAt,
       attempt: 0,
-      requestedByPrincipal: cloneRecord(input.requestedByPrincipal ?? SYSTEM_PRINCIPAL),
-      ...(input.source ? { source: cloneRecord(input.source) } : {}),
+      requesterGroupIds: normalizeRequesterGroupIds(input.requesterGroupIds),
     }
 
     this.runs.set(key, cloneRecord(record))
@@ -113,51 +153,26 @@ export class InMemoryWorkflowRunStorage implements WorkflowRunStorage {
   async start(input: StartWorkflowRunInput): Promise<WorkflowRunRecord> {
     const key = storageKey(input.projectId, input.id)
     const existing = this.runs.get(key)
-    if (existing) {
-      if (existing.status !== "queued") {
-        throw new WorkflowRunError(
-          `[Sixb] Workflow run '${input.id}' already exists for project '${input.projectId}'.`
-        )
-      }
-
-      if (existing.workflowId !== input.workflowId) {
-        throw new WorkflowRunError(
-          `[Sixb] Workflow run '${input.id}' workflow '${input.workflowId}' does not match existing workflow '${existing.workflowId}'.`
-        )
-      }
-
-      const next: WorkflowRunRecord = {
-        ...existing,
-        status: "running",
-        input: cloneRecord(input.input),
-        startedAt: new Date(input.startedAt ?? new Date()),
-        finishedAt: undefined,
-        error: undefined,
-        source:
-          existing.source ?? (input.source === undefined ? undefined : cloneRecord(input.source)),
-        attempt: existing.attempt + 1,
-        execution: input.execution ? cloneRecord(input.execution) : undefined,
-      }
-
-      this.runs.set(key, cloneRecord(next))
-      return cloneRecord(next)
+    if (!existing || existing.status !== "queued") {
+      throw new WorkflowRunError(
+        existing
+          ? `[Sixb] Workflow run '${input.id}' cannot start from status '${existing.status}'.`
+          : `[Sixb] Workflow run '${input.id}' not found for project '${input.projectId}'.`
+      )
     }
 
-    const record: WorkflowRunRecord = {
-      id: input.id,
-      projectId: input.projectId,
-      workflowId: input.workflowId,
+    const next: WorkflowRunRecord = {
+      ...existing,
       status: "running",
-      input: cloneRecord(input.input),
       startedAt: new Date(input.startedAt ?? new Date()),
-      attempt: 1,
-      requestedByPrincipal: cloneRecord(input.requestedByPrincipal ?? SYSTEM_PRINCIPAL),
-      ...(input.execution ? { execution: cloneRecord(input.execution) } : {}),
-      ...(input.source ? { source: cloneRecord(input.source) } : {}),
+      finishedAt: undefined,
+      error: undefined,
+      attempt: existing.attempt + 1,
+      execution: input.execution ? cloneRecord(input.execution) : undefined,
     }
 
-    this.runs.set(key, cloneRecord(record))
-    return cloneRecord(record)
+    this.runs.set(key, cloneRecord(next))
+    return cloneRecord(next)
   }
 
   async finish(input: FinishWorkflowRunInput): Promise<WorkflowRunRecord> {
@@ -174,11 +189,13 @@ export class InMemoryWorkflowRunStorage implements WorkflowRunStorage {
       input.status === "succeeded"
         ? {
             ...base,
+            output: cloneRecord(input.output),
             error: undefined,
           }
         : {
             ...base,
-            error: input.error,
+            output: undefined,
+            error: normalizeFailure(input.error),
           }
 
     this.runs.set(storageKey(input.projectId, input.id), cloneRecord(next))
@@ -464,7 +481,7 @@ export class InMemoryWorkflowNodeRunStorage implements WorkflowNodeRunStorage {
         : {
             ...base,
             output: undefined,
-            error: input.error,
+            error: normalizeFailure(input.error),
           }
 
     this.nodes.set(storageKey(input.projectId, input.id), cloneRecord(next))
@@ -589,7 +606,9 @@ export class InMemoryWorkflowAgentNodeRunStorage implements WorkflowAgentNodeRun
   constructor(
     private readonly nodes: {
       requireAgentNodeRun(projectId: string, id: string): WorkflowNodeRunRecord
-    }
+      requireWorkflowRun(projectId: string, id: string): WorkflowRunRecord
+    },
+    private readonly executions: ExecutionStorage
   ) {}
 
   snapshot(): InMemoryWorkflowAgentNodeRunStorageSnapshot {
@@ -603,6 +622,15 @@ export class InMemoryWorkflowAgentNodeRunStorage implements WorkflowAgentNodeRun
 
   async create(input: CreateWorkflowAgentNodeRunInput): Promise<WorkflowAgentNodeRunRecord> {
     const node = this.nodes.requireAgentNodeRun(input.projectId, input.nodeRunId)
+    const workflowRun = this.nodes.requireWorkflowRun(input.projectId, node.workflowRunId)
+    await assertWorkflowAgentNodeRunExecution({
+      executions: this.executions,
+      projectId: input.projectId,
+      executionId: input.executionId,
+      nodeRunId: input.nodeRunId,
+      agentId: input.agentId,
+      workflowExecutionId: workflowRun.executionId,
+    })
     if (node.status !== "running") {
       throw new WorkflowRunError(
         `[Sixb] Agent workflow node run '${input.nodeRunId}' must be running when queued.`
@@ -614,9 +642,19 @@ export class InMemoryWorkflowAgentNodeRunStorage implements WorkflowAgentNodeRun
         `[Sixb] Agent execution already exists for workflow node run '${input.nodeRunId}'.`
       )
     }
+    if (
+      [...this.runs.values()].some(
+        (run) => run.projectId === input.projectId && run.executionId === input.executionId
+      )
+    ) {
+      throw new WorkflowRunError(
+        `[Sixb] Execution '${input.executionId}' already belongs to another Workflow Agent-node run.`
+      )
+    }
     const record: WorkflowAgentNodeRunRecord = {
       projectId: input.projectId,
       nodeRunId: input.nodeRunId,
+      executionId: input.executionId,
       agentId: input.agentId,
       status: "queued",
       prompt: input.prompt,
@@ -632,9 +670,6 @@ export class InMemoryWorkflowAgentNodeRunStorage implements WorkflowAgentNodeRun
     const next: WorkflowAgentNodeRunRecord = {
       ...run,
       status: "running",
-      ...(input.executionPrincipal
-        ? { executionPrincipal: cloneRecord(input.executionPrincipal) }
-        : {}),
       ...(input.modelId ? { modelId: input.modelId } : {}),
       attempt: 1,
       execution: cloneRecord(input.execution),
@@ -673,10 +708,11 @@ export class InMemoryWorkflowAgentNodeRunStorage implements WorkflowAgentNodeRun
       status: input.status,
       ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
       ...(input.finishReason === undefined ? {} : { finishReason: input.finishReason }),
-      ...(input.usage === undefined ? {} : { usage: cloneRecord(input.usage) }),
       ...(input.trace === undefined ? {} : { trace: cloneRecord(input.trace) }),
       ...(input.diagnostics === undefined ? {} : { diagnostics: cloneRecord(input.diagnostics) }),
-      ...(input.status === "succeeded" || input.error === undefined ? {} : { error: input.error }),
+      ...(input.status === "succeeded" || input.error === undefined
+        ? {}
+        : { error: normalizeAgentFailure(input.error) }),
       execution: undefined,
       completedAt: new Date(input.completedAt ?? new Date()),
     })
@@ -693,7 +729,7 @@ export class InMemoryWorkflowAgentNodeRunStorage implements WorkflowAgentNodeRun
       ...run,
       status: "cancelled",
       execution: undefined,
-      error: input.error,
+      error: normalizeAgentFailure(input.error),
       completedAt: new Date(input.completedAt ?? new Date()),
     })
   }

package/src/storage/workflow-runs/index.ts

@@ -39,7 +39,9 @@ export type {
   WorkflowNodeRunStorage,
   WorkflowNodeRunType,
   WorkflowRunExecution,
+  WorkflowRunFailureCode,
   WorkflowRunRecord,
   WorkflowRunStatus,
   WorkflowRunStorage,
 } from "./types"
+export { WORKFLOW_RUN_FAILURE_CODES } from "./types"

package/src/storage/workflow-runs/provider.ts

@@ -0,0 +1,70 @@
+import { agentServiceAccountId } from "../../agents/authority"
+import type { ExecutionStorage } from "../executions"
+import { findAgentRunExecution, findPrimitiveRunExecution } from "../executions/run-link"
+import { WorkflowRunError } from "./errors"
+
+/** Validate the semantic link between a durable workflow run and its immutable execution. */
+export async function assertWorkflowRunExecution(input: {
+  readonly executions: ExecutionStorage
+  readonly projectId: string
+  readonly executionId: string
+  readonly runId: string
+  readonly workflowId: string
+}): Promise<void> {
+  const execution = await findPrimitiveRunExecution({
+    executions: input.executions,
+    projectId: input.projectId,
+    executionId: input.executionId,
+    primitive: { kind: "workflow", id: input.workflowId, runId: input.runId },
+    sourceTypes: ["execution", "schedule", "event"],
+  })
+  if (!execution) {
+    invalidExecution(input.executionId, input.runId)
+  }
+
+  if (execution.source.type === "schedule" || execution.source.type === "event") {
+    if (execution.requestedBy !== undefined) {
+      invalidExecution(input.executionId, input.runId)
+    }
+    return
+  }
+
+  // ExecutionStorage already validates the immutable parent reference, correlation id, and
+  // requested-by propagation. This boundary only owns the workflow-specific source restriction.
+  if (execution.source.type !== "execution") {
+    invalidExecution(input.executionId, input.runId)
+  }
+}
+
+/** Validate the semantic link between a Workflow Agent-node run and its child execution. */
+export async function assertWorkflowAgentNodeRunExecution(input: {
+  readonly executions: ExecutionStorage
+  readonly projectId: string
+  readonly executionId: string
+  readonly nodeRunId: string
+  readonly agentId: string
+  readonly workflowExecutionId: string
+}): Promise<void> {
+  const execution = await findAgentRunExecution({
+    executions: input.executions,
+    projectId: input.projectId,
+    executionId: input.executionId,
+    runId: input.nodeRunId,
+    serviceAccountId: agentServiceAccountId(input.agentId),
+  })
+  if (
+    !execution ||
+    execution.source.type !== "execution" ||
+    execution.source.executionId !== input.workflowExecutionId
+  ) {
+    throw new WorkflowRunError(
+      `[Sixb] Execution '${input.executionId}' does not authorize Workflow Agent-node run '${input.nodeRunId}'.`
+    )
+  }
+}
+
+function invalidExecution(executionId: string, runId: string): never {
+  throw new WorkflowRunError(
+    `[Sixb] Execution '${executionId}' does not authorize workflow run '${runId}'.`
+  )
+}