@sixb/core 0.1.5 → 0.1.7

package/src/testing/materializer-storage-contract.ts

@@ -15,6 +15,7 @@ import { restoreTrustedPrimitiveExecutionScope } from "../execution/durable"
 import { createTestingScope } from "../execution/scopes"
 import type { OntologyMaterializer } from "../materializer"
 import {
+  createLinkScopeFingerprint,
   createOntologyMaterializer,
   type OntologyEditOperation,
   ProjectionRegistry,
@@ -42,7 +43,7 @@ const Device = defineObjectType({
     prop("name", "string", { required: true }),
     prop("temperature", "double", { mode: "telemetry" }),
   ],
-  links: [link.self("parent", { cardinality: "one" })],
+  links: [link.self("parent", { cardinality: "one" }), link.self("peers", { cardinality: "many" })],
 })
 
 const devices = defineDataset("storage_contract_devices", {
@@ -55,6 +56,9 @@ const devices = defineDataset("storage_contract_devices", {
 const readings = defineDataset("storage_contract_readings", {
   schema: [col("device_id", "string"), col("at", "timestamp"), col("value", "float64")],
 })
+const devicePeers = defineDataset("storage_contract_device_peers", {
+  schema: [col("source_id", "string"), col("target_id", "string")],
+})
 const ConflictDevice = defineObjectType({
   id: "StorageContractConflictDevice",
   name: "Conflict device",
@@ -88,6 +92,10 @@ const temperatureProjection = defineProjection(
 )
   .fromDataset(readings)
   .points({ objectId: "device_id", at: "at", value: "value" })
+const devicePeersProjection = defineProjection("storage_contract_device_peers", Device.l.peers)
+  .fromDataset(devicePeers)
+  .sourceField("source_id")
+  .targetField("target_id")
 const conflictDeviceProjection = defineProjection(
   "storage_contract_conflict_devices",
   ConflictDevice
@@ -98,11 +106,17 @@ const conflictDeviceProjection = defineProjection(
 
 const ontology = new OntologyRegistry({ sources: [Device, ConflictDevice] })
 const projections = new ProjectionRegistry({
-  projections: [deviceProjection, temperatureProjection, conflictDeviceProjection],
+  projections: [
+    deviceProjection,
+    temperatureProjection,
+    devicePeersProjection,
+    conflictDeviceProjection,
+  ],
   ontology,
   datasetsById: new Map<string, DatasetDefinition>([
     [devices.id, devices],
     [readings.id, readings],
+    [devicePeers.id, devicePeers],
     [conflictDevices.id, conflictDevices],
   ]),
 })
@@ -561,6 +575,160 @@ export function runMaterializerStorageContractSuite<TStorage extends Storage>(
       await provider.cleanup?.(createdStorage)
     }
   })
+
+  test(`${name} fences projected cardinality-many link scopes by fingerprint`, async () => {
+    const createdStorage = await provider.createStorage()
+    const storage = requireContractStorage(createdStorage)
+    let materializationOrdinal = 0
+    const materializer = createOntologyMaterializer({
+      projectId: "materializer-storage-contract",
+      ontology,
+      projections,
+      storage,
+      dependencies: {
+        batching: { sourceStageRows: 1, statePageRows: 1, planChunkRows: 1 },
+        clock: () => new Date("2026-02-01T12:00:00.000Z"),
+        materializationId: () => `many-scope-contract-candidate-${++materializationOrdinal}`,
+      },
+    })
+    const runtimeMaterializer = materializer.withScope(runtimeScope())
+    const source = { objectTypeId: Device.id, primaryId: "source" }
+    const peer = (primaryId: string) => ({ objectTypeId: Device.id, primaryId })
+    const linkRef = (targetId: string) => ({
+      source,
+      linkId: "peers",
+      target: peer(targetId),
+    })
+
+    try {
+      await runtimeMaterializer.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: "many-scope-endpoints" },
+        operations: ["source", "peer-a", "peer-b", "peer-c"].map((primaryId) => ({
+          id: `create-${primaryId}`,
+          kind: "object.create" as const,
+          ref: peer(primaryId),
+          properties: { name: primaryId },
+        })),
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+
+      const datasetVersion = {
+        datasetId: devicePeers.id,
+        versionId: "many-links-v1",
+        createdAt: "2026-02-01T00:00:00.000Z",
+      }
+      const execution = await claim(storage, {
+        runId: "many-links-v1",
+        projectionId: devicePeersProjection.id,
+        protocol: "replacement",
+        datasetVersion,
+      })
+      const projectedLinks = [linkRef("peer-a"), linkRef("peer-b")]
+      await (
+        await projectionMaterializer(
+          materializer,
+          storage,
+          devicePeersProjection.id,
+          "many-links-v1"
+        )
+      ).projections.replace({
+        source: { projectionId: devicePeersProjection.id },
+        datasetVersion,
+        execution,
+        entries: entries(
+          projectedLinks.map((ref) => ({
+            root: { kind: "link", ref },
+            assertions: [{ kind: "link", ref }],
+          }))
+        ),
+      })
+
+      const observedLinks = await storage.objects.listLinks({
+        projectId: "materializer-storage-contract",
+        objectTypeId: Device.id,
+        objectId: source.primaryId,
+        linkId: "peers",
+      })
+      const fingerprint = createLinkScopeFingerprint(
+        observedLinks.map((row) => {
+          if (row.lastCommitId === undefined) {
+            throw new Error("Projected contract link is missing materializer provenance.")
+          }
+          return {
+            ref: linkRef(row.targetId),
+            createdAt: row.createdAt.toISOString(),
+            updatedAt: row.updatedAt.toISOString(),
+            lastCommitId: row.lastCommitId,
+          }
+        })
+      )
+      const commitObservation = async (runId: string, name: string) => {
+        await queueTestActionRun(storage, {
+          id: runId,
+          projectId: "materializer-storage-contract",
+          actionId: "observePeers",
+          subject: { kind: "object", objectTypeId: Device.id, primaryId: source.primaryId },
+          params: {},
+          idempotencyKey: runId,
+        })
+        await storage.actionRuns.start({ id: runId, projectId: "materializer-storage-contract" })
+        const actionMaterializer = await primitiveMaterializer(materializer, storage, {
+          kind: "action",
+          id: "observePeers",
+          runId,
+        })
+        return actionMaterializer.edits.commit({
+          mode: "atomic",
+          source: { kind: "action", actionId: "observePeers", runId },
+          operations: [
+            {
+              id: `record-${runId}`,
+              kind: "object.patch",
+              ref: source,
+              set: { name },
+              unset: [],
+              reset: [],
+            },
+          ],
+          expectedObjects: [],
+          expectedLinks: [],
+          expectedLinkScopes: [{ source, linkId: "peers", fingerprint }],
+        })
+      }
+
+      // Regression guard for G-021: make begin() hydrate the expected scope through the
+      // cardinality-one slot reader again and this otherwise unrelated Action commit fails before
+      // its already-stable fingerprint can be compared.
+      await expect(commitObservation("many-scope-action", "observed peers")).resolves.toMatchObject(
+        { kind: "edit", created: true }
+      )
+
+      await runtimeMaterializer.edits.commit({
+        mode: "atomic",
+        source: { kind: "runtime", requestId: "many-scope-change" },
+        operations: [{ id: "add-peer", kind: "link.upsert", ref: linkRef("peer-c") }],
+        expectedObjects: [],
+        expectedLinks: [],
+        expectedLinkScopes: [],
+      })
+
+      await expect(commitObservation("stale-many-scope-action", "must not commit")).rejects.toThrow(
+        "Expected link scope changed"
+      )
+      expect(
+        await storage.objects.getByPrimaryId({
+          projectId: "materializer-storage-contract",
+          objectTypeId: Device.id,
+          primaryId: source.primaryId,
+        })
+      ).toMatchObject({ properties: { name: "observed peers" } })
+    } finally {
+      await provider.cleanup?.(createdStorage)
+    }
+  })
 }
 
 function runtimeScope() {

package/src/testing/queues-contract.ts

@@ -270,7 +270,7 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
         })
       })
 
-      test("keeps syncRuns, pipelines, projections, workflows, and actions lanes independent", async () => {
+      test("keeps every worker lane independent", async () => {
         await withQueues(async (queues) => {
           await queues.syncRuns.enqueue({
             projectId: "project-a",
@@ -309,6 +309,24 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
               },
             ],
           })
+          await queues.agents.enqueue({
+            projectId: "project-a",
+            jobs: [
+              {
+                type: "agent.run.requested",
+                payload: { runId: "agent-run-1" },
+              },
+            ],
+          })
+          await queues.agentChildren.enqueue({
+            projectId: "project-a",
+            jobs: [
+              {
+                type: "agent.subagent-run.requested",
+                payload: { runId: "child-run-1" },
+              },
+            ],
+          })
 
           const crossLane = await queues.pipelines.claim({
             projectId: "project-a",
@@ -330,6 +348,16 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
             workerId: "action-worker-1",
             limit: 10,
           })
+          const agentLane = await queues.agents.claim({
+            projectId: "project-a",
+            workerId: "agent-worker-1",
+            limit: 10,
+          })
+          const childLane = await queues.agentChildren.claim({
+            projectId: "project-a",
+            workerId: "child-agent-worker-1",
+            limit: 10,
+          })
           const sameLane = await queues.syncRuns.claim({
             projectId: "project-a",
             workerId: "sync-worker-1",
@@ -344,6 +372,13 @@ export function runQueueContractSuite(label: string, options: QueueContractSuite
           expect(workflowLane[0]?.job.payload.runId).toBe("workflow-run-1")
           expect(actionLane).toHaveLength(1)
           expect(actionLane[0]?.job.payload.runId).toBe("act_1")
+          expect(agentLane).toHaveLength(1)
+          expect(agentLane[0]?.job).toMatchObject({
+            type: "agent.run.requested",
+            payload: { runId: "agent-run-1" },
+          })
+          expect(childLane).toHaveLength(1)
+          expect(childLane[0]?.job.payload.runId).toBe("child-run-1")
           expect(sameLane).toHaveLength(1)
         })
       })

package/src/workflows/agent-step-identity.ts

@@ -0,0 +1,4 @@
+/** Stable internal actor id for one workflow Agent step. */
+export function workflowAgentStepActorId(workflowId: string, stepId: string): string {
+  return `workflow:${encodeURIComponent(workflowId)}:step:${encodeURIComponent(stepId)}`
+}

package/src/workflows/builders.ts

@@ -1,14 +1,16 @@
 import type { ActionDefinition } from "../actions"
 import { isActionDefinition } from "../actions"
-import type { AgentDefinition } from "../agents"
-import { isAgentDefinition } from "../agents"
+import { AGENT_REASONING_LEVELS, isAgentToolDefinition } from "../agents"
+import { isModelReasoning } from "../models/language-model"
 import type { SchemaOrRef } from "../ontology"
 import type { ScheduleDefinition, ScheduleDefinitionForEvent } from "../schedules"
 import { isScheduleDefinition } from "../schedules"
+import { isGroupDefinition } from "../security"
 import { WorkflowDefinitionError } from "./errors"
 import type {
   AgentStepBuilder,
   AgentStepDefinition,
+  DefineAgentStepConfig,
   InterventionBuilder,
   InterventionDefaultsRuntimeHandler,
   InterventionDefinition,
@@ -115,14 +117,25 @@ export function defineWorkflowStep<const TId extends string>(id: TId): StepBuild
   } as unknown as StepBuilder<TId>
 }
 
-export function defineAgentStep<const TId extends string, const TAgent extends AgentDefinition>(
+export function defineAgentStep<const TId extends string>(
   id: TId,
-  agent: TAgent
-): AgentStepBuilder<TId, TAgent> {
+  config: DefineAgentStepConfig
+): AgentStepBuilder<TId> {
   assertNonEmpty(id, "Agent step", "id")
-  if (!isAgentDefinition(agent)) {
-    throw new WorkflowDefinitionError(`Agent step "${id}" references an invalid agent.`)
+  if (!isRecord(config)) {
+    throw new WorkflowDefinitionError(`Agent step "${id}" config must be an object.`)
   }
+  if (typeof config.instructions !== "string" || !config.instructions.trim()) {
+    throw new WorkflowDefinitionError(`Agent step "${id}" instructions must not be empty.`)
+  }
+  if (config.reasoning !== undefined && !isModelReasoning(config.reasoning)) {
+    throw new WorkflowDefinitionError(
+      `Agent step "${id}" reasoning must be one of: ${AGENT_REASONING_LEVELS.join(", ")}, or a nonnegative budgetTokens object.`
+    )
+  }
+  const { model, reasoning, instructions } = config
+  const groupIds = groupIdsFromAgentStepConfig(id, config)
+  const toolNames = toolNamesFromAgentStepConfig(id, config)
 
   return {
     input(input: RuntimeWorkflowInput): unknown {
@@ -133,13 +146,82 @@ export function defineAgentStep<const TId extends string, const TAgent extends A
               if (typeof prompt !== "function") {
                 throw new WorkflowDefinitionError(`Agent step "${id}" prompt must be a function.`)
               }
-              return { kind: "agentStep", id, agent, input, output, prompt }
+              return {
+                kind: "agentStep",
+                id,
+                ...(model === undefined ? {} : { model }),
+                ...(reasoning === undefined ? {} : { reasoning }),
+                instructions,
+                groupIds,
+                toolNames,
+                input,
+                output,
+                prompt,
+              }
             },
           }
         },
       }
     },
-  } as unknown as AgentStepBuilder<TId, TAgent>
+  } as unknown as AgentStepBuilder<TId>
+}
+
+function groupIdsFromAgentStepConfig(
+  stepId: string,
+  config: DefineAgentStepConfig
+): readonly string[] {
+  if (config.groups !== undefined && !Array.isArray(config.groups)) {
+    throw new WorkflowDefinitionError(
+      `Agent step "${stepId}" groups must be an array of group definitions.`
+    )
+  }
+  const groupIds = Array.from(config.groups ?? [], (group) => {
+    if (!isGroupDefinition(group)) {
+      throw new WorkflowDefinitionError(
+        `Agent step "${stepId}" groups must contain only group definitions.`
+      )
+    }
+    return group.id
+  })
+  assertUniqueAgentStepValues(stepId, "group", groupIds)
+  return Object.freeze(groupIds)
+}
+
+function toolNamesFromAgentStepConfig(
+  stepId: string,
+  config: DefineAgentStepConfig
+): readonly string[] {
+  if (config.tools !== undefined && !Array.isArray(config.tools)) {
+    throw new WorkflowDefinitionError(
+      `Agent step "${stepId}" tools must be an array of agent tool definitions.`
+    )
+  }
+  const toolNames = Array.from(config.tools ?? [], (tool) => {
+    if (!isAgentToolDefinition(tool)) {
+      throw new WorkflowDefinitionError(
+        `Agent step "${stepId}" tools must contain only agent tool definitions.`
+      )
+    }
+    return tool.name
+  })
+  assertUniqueAgentStepValues(stepId, "tool", toolNames)
+  return Object.freeze(toolNames)
+}
+
+function assertUniqueAgentStepValues(
+  stepId: string,
+  kind: "group" | "tool",
+  values: readonly string[]
+): void {
+  const seen = new Set<string>()
+  for (const value of values) {
+    if (seen.has(value)) {
+      throw new WorkflowDefinitionError(
+        `Agent step "${stepId}" ${kind}s contains duplicate ${kind} '${value}'.`
+      )
+    }
+    seen.add(value)
+  }
 }
 
 export function defineIntervention<const TId extends string>(
@@ -469,3 +551,7 @@ function isRuntimeWorkflowMapper(value: unknown): value is RuntimeWorkflowMapper
 function isRuntimeWorkflowScheduleMapper(value: unknown): value is RuntimeWorkflowScheduleMapper {
   return typeof value === "function"
 }
+
+function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}

package/src/workflows/execution.ts

@@ -61,7 +61,8 @@ export type ListWorkflowRunNodesInput = Omit<
 >
 
 /** Execution-facing Agent node view derived from its run row and model-call ledger. */
-export interface WorkflowAgentNodeRunView extends Omit<WorkflowAgentNodeRunRecord, "execution"> {
+export interface WorkflowAgentNodeRunView
+  extends Omit<WorkflowAgentNodeRunRecord, "execution" | "actorId"> {
   readonly usage?: AiModelCallUsage
   /** Preferred valuation; omitted when there are no calls or cost storage is unavailable. */
   readonly cost?: AiCostSummary
@@ -274,7 +275,6 @@ function toWorkflowAgentNodeRunView(
     projectId: execution.projectId,
     nodeRunId: execution.nodeRunId,
     executionId: execution.executionId,
-    agentId: execution.agentId,
     status: execution.status,
     prompt: execution.prompt,
     modelId: execution.modelId,

package/src/workflows/failure.ts

@@ -15,7 +15,7 @@ export interface WorkflowNodeFailureIdentity extends WorkflowNodeFailureIdentity
         readonly actionId: string
         readonly actionRunId?: string
       }
-    | { readonly type: "agent"; readonly agentId: string }
+    | { readonly type: "agent"; readonly agentStepId: string }
     | { readonly type: "intervention"; readonly interventionId: string }
 }
 
@@ -56,7 +56,7 @@ function workflowNodeFailureDetails(identity: WorkflowNodeFailureIdentity) {
         ...(identity.child.actionRunId ? { actionRunId: identity.child.actionRunId } : {}),
       }
     case "agent":
-      return { ...base, agentId: identity.child.agentId }
+      return { ...base, agentStepId: identity.child.agentStepId }
     case "intervention":
       return { ...base, interventionId: identity.child.interventionId }
   }

package/src/workflows/index.ts

@@ -1,3 +1,4 @@
+export { workflowAgentStepActorId } from "./agent-step-identity"
 export {
   defineAgentStep,
   defineIntervention,
@@ -39,6 +40,7 @@ export type {
   AgentStepPrompt,
   AgentStepPromptBuilder,
   AgentStepPromptContext,
+  DefineAgentStepConfig,
   DerivedWorkflowNodeKey,
   InferAgentStepInput,
   InferAgentStepOutput,
@@ -90,6 +92,7 @@ export {
   isInterventionDefinition,
   isStepDefinition,
   isWorkflowDefinition,
+  validateWorkflowAgentStepGroupReferences,
   validateWorkflowAgentStepInput,
   validateWorkflowAgentStepOutput,
   validateWorkflowDefinition,

package/src/workflows/types.ts

@@ -5,8 +5,8 @@ import type {
   ObjectActionDefinition,
 } from "../actions"
 import type { ActionsRuntime } from "../actions/execution"
-import type { AgentsRuntime } from "../agents/execution"
-import type { AgentDefinition } from "../agents/types"
+import type { AgentRuntime } from "../agents/execution"
+import type { AgentReasoningLevel, AgentToolDefinition } from "../agents/types"
 import type { Principal } from "../auth"
 import type { BlobsRuntime } from "../blob-storage/execution"
 import type { ConnectorRuntime } from "../connectors/execution"
@@ -15,6 +15,7 @@ import type { EventsRuntime } from "../events/execution"
 import type { JsonValue } from "../json"
 import type { Logger } from "../logging"
 import type { LogsRuntime } from "../logging/execution"
+import type { LanguageModel } from "../models/language-model"
 import type { ObjectsRuntime } from "../objects/execution"
 import type { InferSchemaOrRef, ObjectRef, OntologySource, SchemaOrRef } from "../ontology"
 import type { PipelinesRuntime } from "../pipelines/execution"
@@ -22,6 +23,7 @@ import type { ProjectionsRuntime } from "../projections/execution"
 import type { RulesRuntime } from "../rules/execution"
 import type { ScheduleDefinition, ScheduleDefinitionForEvent } from "../schedules"
 import type { SchedulesRuntime } from "../schedules/execution"
+import type { GroupDefinition } from "../security"
 import type { SyncsRuntime } from "../syncs/execution"
 import type { WorkflowsRuntime } from "./execution"
 
@@ -60,7 +62,7 @@ export interface StepRunContext<TInput extends Record<string, unknown>> {
 export interface WorkflowRuntimeFacade {
   readonly objects: ObjectsRuntime<readonly OntologySource[]>
   readonly actions: ActionsRuntime
-  readonly agents: AgentsRuntime
+  readonly agent: AgentRuntime
   readonly datasets: DatasetsRuntime
   readonly workflows: WorkflowsRuntime
   readonly syncs: SyncsRuntime
@@ -133,9 +135,18 @@ export type AgentStepPrompt<TInput extends Record<string, unknown>> = (
   ctx: AgentStepPromptContext<TInput>
 ) => string | Promise<string>
 
+/** Runtime configuration owned directly by a workflow Agent step. */
+export interface DefineAgentStepConfig {
+  readonly model?: LanguageModel
+  readonly reasoning?: AgentReasoningLevel
+  readonly instructions: string
+  readonly groups?: readonly GroupDefinition[]
+  /** Project tools this workflow task may call. Defaults to none. */
+  readonly tools?: readonly AgentToolDefinition[]
+}
+
 export interface AgentStepDefinition<
   TId extends string = string,
-  TAgent extends AgentDefinition = AgentDefinition,
   TInput extends Record<string, unknown> = Record<string, unknown>,
   TOutput extends Record<string, unknown> = Record<string, unknown>,
   TInputValue extends Record<string, unknown> = Record<string, unknown>,
@@ -143,7 +154,11 @@ export interface AgentStepDefinition<
 > {
   readonly kind: "agentStep"
   readonly id: TId
-  readonly agent: TAgent
+  readonly model?: LanguageModel
+  readonly reasoning?: AgentReasoningLevel
+  readonly instructions: string
+  readonly groupIds: readonly string[]
+  readonly toolNames: readonly string[]
   readonly input: TInput
   readonly output: TOutput
   readonly prompt: AgentStepPrompt<Record<string, unknown>>
@@ -153,7 +168,6 @@ export interface AgentStepDefinition<
 
 export interface AgentStepPromptBuilder<
   TId extends string,
-  TAgent extends AgentDefinition,
   TInput extends Record<string, unknown>,
   TOutput extends Record<string, unknown>,
 > {
@@ -161,7 +175,6 @@ export interface AgentStepPromptBuilder<
     prompt: AgentStepPrompt<InferSchemaOrRefRecord<TInput>>
   ): AgentStepDefinition<
     TId,
-    TAgent,
     TInput,
     TOutput,
     InferSchemaOrRefRecord<TInput>,
@@ -171,18 +184,17 @@ export interface AgentStepPromptBuilder<
 
 export interface AgentStepOutputBuilder<
   TId extends string,
-  TAgent extends AgentDefinition,
   TInput extends Record<string, unknown>,
 > {
   output<const TOutput extends Record<string, unknown>>(
     output: TOutput & SchemaOrRefInput<TOutput>
-  ): AgentStepPromptBuilder<TId, TAgent, TInput, TOutput>
+  ): AgentStepPromptBuilder<TId, TInput, TOutput>
 }
 
-export interface AgentStepBuilder<TId extends string, TAgent extends AgentDefinition> {
+export interface AgentStepBuilder<TId extends string> {
   input<const TInput extends Record<string, unknown>>(
     input: TInput & SchemaOrRefInput<TInput>
-  ): AgentStepOutputBuilder<TId, TAgent, TInput>
+  ): AgentStepOutputBuilder<TId, TInput>
 }
 
 export type InferAgentStepInput<TStep extends AgentStepDefinition> = TStep extends {