@sixb/core 0.1.1 → 0.1.2

package/src/security/types.ts

@@ -1,5 +1,4 @@
 import type { AuthSessionAudience } from "../auth/audience"
-import type { ResolvedRole } from "../authorization/types"
 
 export interface GroupDefinition<TId extends string = string> {
   readonly kind: "group"
@@ -105,6 +104,13 @@ export interface ObserveGrant {
   readonly selection: Selection
 }
 
+/** Manage the OAuth connection lifecycle for selected connector definitions. */
+export interface ManageGrant {
+  readonly kind: "grant"
+  readonly capability: "manage"
+  readonly selection: Selection
+}
+
 export type GrantDefinition =
   | AccessGrant
   | ViewGrant
@@ -113,6 +119,7 @@ export type GrantDefinition =
   | ApplyGrant
   | RunGrant
   | ObserveGrant
+  | ManageGrant
 
 export type GrantCapability = GrantDefinition["capability"]
 
@@ -143,14 +150,3 @@ export interface RegisteredSecurityDefinitions {
   readonly membershipPolicies: readonly MembershipPolicyDefinition[]
   readonly membershipPoliciesById: ReadonlyMap<string, MembershipPolicyDefinition>
 }
-
-export interface SecurityRegistry {
-  listGroups(): readonly GroupDefinition[]
-  getGroupById(groupId: string): GroupDefinition | null
-  listRoles(): readonly RoleDefinition[]
-  getRoleById(roleId: string): RoleDefinition | null
-  /** Roles with their grants pre-expanded to concrete id sets for resolution. */
-  listResolvedRoles(): readonly ResolvedRole[]
-  listMembershipPolicies(): readonly MembershipPolicyDefinition[]
-  getMembershipPolicyById(policyId: string): MembershipPolicyDefinition | null
-}

package/src/security/validation.ts

@@ -29,6 +29,7 @@ const GRANT_CAPABILITIES = Object.keys({
   apply: true,
   run: true,
   observe: true,
+  manage: true,
 } satisfies Record<GrantCapability, true>) as readonly GrantCapability[]
 
 /** "'a', 'b', or 'c'" — the shape the security errors already use. */
@@ -223,6 +224,10 @@ export function assertGrantDefinition(
     throw createError(`[Sixb] ${field} observe grant target must be 'logs'.`)
   }
 
+  if (value.capability === "manage" && value.target !== undefined) {
+    throw createError(`[Sixb] ${field} manage grant must not declare a target.`)
+  }
+
   assertSelection(value.selection, field, createError)
 }
 
@@ -302,6 +307,8 @@ export function validateSecurityDefinitionsAtStartup(input: {
   readonly agentIds?: ReadonlySet<string>
   /** Registered observability surfaces. */
   readonly observableIds?: ReadonlySet<string>
+  /** Registered connector ids — when provided, manage grants must reference them. */
+  readonly connectorIds?: ReadonlySet<string>
 }): RegisteredSecurityDefinitions {
   const groupsById = new Map<string, GroupDefinition>()
   const rolesById = new Map<string, RoleDefinition>()

package/src/storage/action-runs/failure.ts

@@ -0,0 +1,64 @@
+import { parseSixbFailure } from "../../errors/internal"
+import { isPlainRecord } from "../../json"
+import {
+  ACTION_RUN_FAILURE_CODES,
+  ACTION_RUN_PHASES,
+  type ActionRunFailure,
+  type ActionRunFailureDetails,
+  type ActionRunPhase,
+} from "./types"
+
+/** Serializes the canonical failure plus Action's typed lifecycle extension. */
+export function serializeActionRunFailure<TPhase extends ActionRunPhase>(
+  failure: ActionRunFailure<TPhase>,
+  expectedPhase?: TPhase
+): string {
+  const parsed =
+    expectedPhase === undefined
+      ? parseActionRunFailure(failure)
+      : parseActionRunFailure(failure, expectedPhase)
+  return JSON.stringify(parsed)
+}
+
+/** Validates and detaches an Action failure read from a storage boundary. */
+export function parseActionRunFailure<TPhase extends ActionRunPhase>(
+  value: unknown,
+  expectedPhase: TPhase
+): ActionRunFailure<TPhase>
+export function parseActionRunFailure(value: unknown): ActionRunFailure
+export function parseActionRunFailure(
+  value: unknown,
+  expectedPhase?: ActionRunPhase
+): ActionRunFailure {
+  const candidate = parseStoredActionRunFailureValue(value)
+  const failure = parseSixbFailure(candidate, ACTION_RUN_FAILURE_CODES)
+  const details = failure.details
+  if (
+    !isPlainRecord(details) ||
+    typeof details.actionId !== "string" ||
+    typeof details.runId !== "string" ||
+    typeof details.phase !== "string" ||
+    !(ACTION_RUN_PHASES as readonly string[]).includes(details.phase)
+  ) {
+    throw new Error(
+      "[Sixb] Stored failure is invalid: Action details must contain actionId, runId, and a known phase."
+    )
+  }
+  if (expectedPhase !== undefined && details.phase !== expectedPhase) {
+    throw new Error(`[Sixb] Stored Action ${expectedPhase} failure has phase '${details.phase}'.`)
+  }
+
+  return {
+    ...failure,
+    details: details as unknown as ActionRunFailureDetails,
+  }
+}
+
+function parseStoredActionRunFailureValue(value: unknown): unknown {
+  if (typeof value !== "string") return value
+  try {
+    return JSON.parse(value) as unknown
+  } catch {
+    throw new Error("[Sixb] Stored failure is invalid: value is not valid JSON.")
+  }
+}

package/src/storage/action-runs/idempotency.ts

@@ -37,7 +37,7 @@ export function finishActionRunPhase(
     return input.phase ?? current ?? "validation"
   }
 
-  return input.phase ?? input.error?.phase ?? current ?? "validation"
+  return input.error.details.phase
 }
 
 export function canRequeueActionRunAfterEnqueueFailure(
@@ -47,6 +47,8 @@ export function canRequeueActionRunAfterEnqueueFailure(
   return (
     existing.status === "failed" &&
     existing.phase === "enqueue" &&
+    existing.executionId === input.executionId &&
+    existing.error?.retryable === true &&
     existing.actionId === input.actionId &&
     existing.idempotencyKey === input.idempotencyKey &&
     actionSubjectsEqual(existing.subject, input.subject) &&

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

@@ -1,14 +1,18 @@
+import type { ExecutionStorage } from "../executions"
 import { ActionRunError } from "./errors"
+import { parseActionRunFailure } from "./failure"
 import {
   actionRunPhaseRecordsEqual,
   actionSubjectsEqual,
   canRequeueActionRunAfterEnqueueFailure,
   isTerminalActionRun,
 } from "./idempotency"
+import { assertActionRunExecution } from "./provider"
 import type {
   ActionRunEffectsRecord,
   ActionRunFailure,
   ActionRunParams,
+  ActionRunPhase,
   ActionRunRecord,
   ActionRunStorage,
   ActionRunWritebackRecord,
@@ -49,8 +53,13 @@ function normalizeSubject(subject: QueueActionRunInput["subject"]): QueueActionR
   return structuredClone(subject)
 }
 
-function normalizeError(error: ActionRunFailure | undefined): ActionRunFailure | undefined {
-  return error ? structuredClone(error) : undefined
+function normalizeError<TPhase extends ActionRunPhase>(
+  error: ActionRunFailure<TPhase>,
+  expectedPhase?: TPhase
+): ActionRunFailure<TPhase> {
+  return expectedPhase === undefined
+    ? (parseActionRunFailure(error) as ActionRunFailure<TPhase>)
+    : parseActionRunFailure(error, expectedPhase)
 }
 
 function normalizeWriteback(
@@ -68,7 +77,7 @@ function normalizeWriteback(
   return {
     status: "failed",
     completedAt,
-    error: normalizeError(input.error),
+    error: normalizeError(input.error, "writeback"),
   }
 }
 
@@ -86,7 +95,7 @@ function normalizeEffects(
   return {
     status: "failed",
     completedAt,
-    error: normalizeError(input.error),
+    error: normalizeError(input.error, "effects"),
   }
 }
 
@@ -109,7 +118,10 @@ export class InMemoryActionRunStorage implements ActionRunStorage {
   private readonly rows = new Map<string, ActionRunRecord>()
   private readonly runRootOperation: RunRootOperation
 
-  constructor(input: { readonly runRootOperation?: RunRootOperation } = {}) {
+  constructor(
+    private readonly executions: ExecutionStorage,
+    input: { readonly runRootOperation?: RunRootOperation } = {}
+  ) {
     this.runRootOperation = input.runRootOperation ?? runDirectly
   }
 
@@ -129,7 +141,7 @@ export class InMemoryActionRunStorage implements ActionRunStorage {
   }
 
   async queue(input: QueueActionRunInput): Promise<ActionRunRecord> {
-    return this.runRootOperation(() => {
+    return this.runRootOperation(async () => {
       const key = actionRunKey(input.projectId, input.id)
       const existing = this.rows.get(key)
       if (existing && !canRequeueActionRunAfterEnqueueFailure(existing, input)) {
@@ -137,10 +149,30 @@ export class InMemoryActionRunStorage implements ActionRunStorage {
           `[Sixb] Action run '${input.id}' already exists for project '${input.projectId}'.`
         )
       }
+      if (
+        [...this.rows.values()].some(
+          (run) =>
+            run.projectId === input.projectId &&
+            run.id !== input.id &&
+            run.executionId === input.executionId
+        )
+      ) {
+        throw new ActionRunError(
+          `[Sixb] Execution '${input.executionId}' already belongs to another Action run.`
+        )
+      }
+      await assertActionRunExecution({
+        executions: this.executions,
+        projectId: input.projectId,
+        executionId: input.executionId,
+        runId: input.id,
+        actionId: input.actionId,
+      })
 
       const record: ActionRunRecord = {
         id: input.id,
         projectId: input.projectId,
+        executionId: input.executionId,
         actionId: input.actionId,
         subject: normalizeSubject(input.subject),
         status: "queued",
@@ -287,9 +319,7 @@ export class InMemoryActionRunStorage implements ActionRunStorage {
       }
 
       const phase =
-        input.status === "succeeded"
-          ? (input.phase ?? existing.phase)
-          : (input.phase ?? input.error?.phase ?? existing.phase)
+        input.status === "succeeded" ? (input.phase ?? existing.phase) : input.error.details.phase
 
       const base: ActionRunRecord = {
         ...existing,

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

@@ -12,6 +12,8 @@ export { InMemoryActionRunStorage } from "./in-memory"
 export type {
   ActionRunEffectsRecord,
   ActionRunFailure,
+  ActionRunFailureCode,
+  ActionRunFailureDetails,
   ActionRunParams,
   ActionRunPhase,
   ActionRunPhaseStatus,
@@ -29,3 +31,4 @@ export type {
   RecordActionWritebackInput,
   StartActionRunInput,
 } from "./types"
+export { ACTION_RUN_FAILURE_CODES, ACTION_RUN_PHASES } from "./types"

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

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

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

@@ -1,44 +1,78 @@
 import type { ActionSubject } from "../../actions"
+import type { SixbErrorCode, SixbFailure } from "../../errors/types"
 import type { JsonValue } from "../../json"
 
 export type ActionRunStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled"
 
-export type ActionRunPhase =
-  | "request"
-  | "enqueue"
-  | "validation"
-  | "writeback"
-  | "edits"
-  | "commit"
-  | "effects"
-  | "cancelled"
+export const ACTION_RUN_PHASES = [
+  "request",
+  "enqueue",
+  "validation",
+  "writeback",
+  "edits",
+  "commit",
+  "effects",
+  "cancelled",
+] as const
+
+export type ActionRunPhase = (typeof ACTION_RUN_PHASES)[number]
 
 export type ActionRunParams = Readonly<Record<string, JsonValue>>
 
 export type ActionRunPhaseStatus = "succeeded" | "failed"
 
-export interface ActionRunFailure {
-  readonly name?: string
-  readonly message: string
-  readonly phase?: ActionRunPhase
-}
+/** Error codes an action run or phase record can persist and expose. */
+export const ACTION_RUN_FAILURE_CODES = [
+  "internal.unexpected",
+  "runtime.cancelled",
+  "queue.enqueue_failed",
+  "action.phase_failed",
+] as const satisfies readonly [SixbErrorCode, ...SixbErrorCode[]]
 
-export interface ActionRunWritebackRecord {
-  readonly status: ActionRunPhaseStatus
-  readonly completedAt: Date
-  readonly result?: JsonValue
-  readonly error?: ActionRunFailure
+export type ActionRunFailureCode = (typeof ACTION_RUN_FAILURE_CODES)[number]
+
+export interface ActionRunFailureDetails<TPhase extends ActionRunPhase = ActionRunPhase> {
+  readonly actionId: string
+  readonly runId: string
+  readonly phase: TPhase
 }
 
-export interface ActionRunEffectsRecord {
-  readonly status: ActionRunPhaseStatus
-  readonly completedAt: Date
-  readonly error?: ActionRunFailure
+/** Portable failure record with Action's required correlation details. */
+export interface ActionRunFailure<TPhase extends ActionRunPhase = ActionRunPhase>
+  extends Omit<SixbFailure<ActionRunFailureCode>, "details"> {
+  readonly details: ActionRunFailureDetails<TPhase>
 }
 
+export type ActionRunWritebackRecord =
+  | {
+      readonly status: "succeeded"
+      readonly completedAt: Date
+      readonly result: JsonValue
+      readonly error?: never
+    }
+  | {
+      readonly status: "failed"
+      readonly completedAt: Date
+      readonly result?: never
+      readonly error: ActionRunFailure<"writeback">
+    }
+
+export type ActionRunEffectsRecord =
+  | {
+      readonly status: "succeeded"
+      readonly completedAt: Date
+      readonly error?: never
+    }
+  | {
+      readonly status: "failed"
+      readonly completedAt: Date
+      readonly error: ActionRunFailure<"effects">
+    }
+
 export interface ActionRunRecord {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly actionId: string
   readonly subject: ActionSubject
   readonly status: ActionRunStatus
@@ -56,6 +90,7 @@ export interface ActionRunRecord {
 export interface QueueActionRunInput {
   readonly id: string
   readonly projectId: string
+  readonly executionId: string
   readonly actionId: string
   readonly subject: ActionSubject
   readonly params: ActionRunParams
@@ -92,7 +127,7 @@ export type RecordActionWritebackInput =
       readonly projectId: string
       readonly status: "failed"
       readonly completedAt?: Date
-      readonly error: ActionRunFailure
+      readonly error: ActionRunFailure<"writeback">
     }
 
 export type RecordActionEffectsInput =
@@ -107,7 +142,7 @@ export type RecordActionEffectsInput =
       readonly projectId: string
       readonly status: "failed"
       readonly completedAt?: Date
-      readonly error: ActionRunFailure
+      readonly error: ActionRunFailure<"effects">
     }
 
 export type FinishActionRunInput =
@@ -123,8 +158,7 @@ export type FinishActionRunInput =
       readonly projectId: string
       readonly status: "failed" | "cancelled"
       readonly finishedAt?: Date
-      readonly error?: ActionRunFailure
-      readonly phase?: ActionRunPhase
+      readonly error: ActionRunFailure
     }
 
 export interface ListActionRunsInput {

package/src/storage/agents/errors.ts

@@ -2,6 +2,7 @@ export type AgentStorageErrorCode =
   | "thread_not_found"
   | "active_run_exists"
   | "run_not_found"
+  | "invalid_input"
   | "invalid_state"
   | "execution_lost"
   | "duplicate_id"

package/src/storage/agents/in-memory.ts

@@ -1,9 +1,15 @@
 import { AGENT_MESSAGE_CONTENT_VERSION } from "../../agents/message"
 import { principalsEqual } from "../../auth"
+import { normalizeRequesterGroupIds } from "../../auth/attribution"
+import { parseSixbFailure } from "../../errors/internal"
+import type { SixbFailure } from "../../errors/types"
+import type { ExecutionStorage } from "../executions"
 import { AgentStorageError } from "./errors"
+import { assertAgentRunExecution } from "./provider"
 import type {
   AgentMessageRecord,
   AgentMessageStore,
+  AgentRunFailureCode,
   AgentRunRecord,
   AgentRunStore,
   AgentStorage,
@@ -24,6 +30,13 @@ import type {
   ReclaimAgentRunInput,
   StartAgentRunInput,
 } from "./types"
+import { AGENT_RUN_FAILURE_CODES } from "./types"
+
+function normalizeFailure(
+  failure: SixbFailure<AgentRunFailureCode> | undefined
+): SixbFailure<AgentRunFailureCode> | undefined {
+  return failure ? parseSixbFailure(failure, AGENT_RUN_FAILURE_CODES) : undefined
+}
 
 function key(projectId: string, id: string): string {
   return `${projectId}:${id}`
@@ -149,9 +162,19 @@ class InMemoryAgentThreadStore implements AgentThreadStore {
 // ── runs ──────────────────────────────────────────────────────────────────────────────────────
 
 class InMemoryAgentRunStore implements AgentRunStore {
-  constructor(private readonly state: AgentStoreState) {}
+  constructor(
+    private readonly state: AgentStoreState,
+    private readonly executions: ExecutionStorage
+  ) {}
 
   async create(input: CreateAgentRunInput): Promise<AgentRunRecord> {
+    await assertAgentRunExecution({
+      executions: this.executions,
+      projectId: input.projectId,
+      executionId: input.executionId,
+      runId: input.id,
+      agentId: input.agentId,
+    })
     // No `await` between read and write: the in-memory critical section is atomic, so two concurrent
     // queued runs on the same thread cannot both win — the second observes `activeRunId` set.
     const threadKey = key(input.projectId, input.threadId)
@@ -176,15 +199,26 @@ class InMemoryAgentRunStore implements AgentRunStore {
         `[Sixb] Agent run '${input.id}' already exists for project '${input.projectId}'.`
       )
     }
+    if (
+      [...this.state.runs.values()].some(
+        (run) => run.projectId === input.projectId && run.executionId === input.executionId
+      )
+    ) {
+      throw new AgentStorageError(
+        "duplicate_id",
+        `[Sixb] Execution '${input.executionId}' already belongs to another Agent run.`
+      )
+    }
 
     const createdAt = new Date(input.createdAt ?? new Date())
     const run: AgentRunRecord = {
       id: input.id,
       projectId: input.projectId,
+      executionId: input.executionId,
       threadId: input.threadId,
       agentId: input.agentId,
       triggerMessageId: input.triggerMessageId,
-      requestedByPrincipal: clone(input.requestedByPrincipal),
+      requesterGroupIds: normalizeRequesterGroupIds(input.requesterGroupIds),
       status: "queued",
       attempt: 0,
       createdAt,
@@ -207,9 +241,6 @@ class InMemoryAgentRunStore implements AgentRunStore {
     const next: AgentRunRecord = {
       ...run,
       status: "running",
-      ...(input.executionPrincipal === undefined
-        ? {}
-        : { executionPrincipal: clone(input.executionPrincipal) }),
       ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
       attempt: 1,
       execution: clone(input.execution),
@@ -225,7 +256,7 @@ class InMemoryAgentRunStore implements AgentRunStore {
     const next: AgentRunRecord = {
       ...run,
       status: input.status,
-      ...(input.error === undefined ? {} : { error: input.error }),
+      ...(input.error === undefined ? {} : { error: normalizeFailure(input.error) }),
       completedAt,
     }
     this.state.runs.set(key(input.projectId, input.id), clone(next))
@@ -283,9 +314,10 @@ class InMemoryAgentRunStore implements AgentRunStore {
       status: input.status,
       ...(input.modelId === undefined ? {} : { modelId: input.modelId }),
       ...(input.finishReason === undefined ? {} : { finishReason: input.finishReason }),
-      ...(input.usage === undefined ? {} : { usage: clone(input.usage) }),
       ...(input.diagnostics === undefined ? {} : { diagnostics: clone(input.diagnostics) }),
-      ...(input.status === "succeeded" || input.error === undefined ? {} : { error: input.error }),
+      ...(input.status === "succeeded" || input.error === undefined
+        ? {}
+        : { error: normalizeFailure(input.error) }),
       execution: undefined,
       completedAt,
     }
@@ -471,9 +503,15 @@ export class InMemoryAgentStorage implements AgentStorage {
     messages: new Map(),
   }
 
-  readonly threads = new InMemoryAgentThreadStore(this.state)
-  readonly runs = new InMemoryAgentRunStore(this.state)
-  readonly messages = new InMemoryAgentMessageStore(this.state)
+  readonly threads: InMemoryAgentThreadStore
+  readonly runs: InMemoryAgentRunStore
+  readonly messages: InMemoryAgentMessageStore
+
+  constructor(executions: ExecutionStorage) {
+    this.threads = new InMemoryAgentThreadStore(this.state)
+    this.runs = new InMemoryAgentRunStore(this.state, executions)
+    this.messages = new InMemoryAgentMessageStore(this.state)
+  }
 
   snapshot(): InMemoryAgentStorageSnapshot {
     return {

package/src/storage/agents/index.ts

@@ -11,11 +11,11 @@ export type {
   AgentRunDiagnosticCode,
   AgentRunDiagnosticSeverity,
   AgentRunExecution,
+  AgentRunFailureCode,
   AgentRunFinishReason,
   AgentRunRecord,
   AgentRunStatus,
   AgentRunStore,
-  AgentRunUsage,
   AgentStorage,
   AgentThreadRecord,
   AgentThreadStatus,
@@ -37,6 +37,7 @@ export type {
 } from "./types"
 export {
   AGENT_RUN_DIAGNOSTIC_CODES,
+  AGENT_RUN_FAILURE_CODES,
   AGENT_RUN_FINISH_REASONS,
   coerceAgentRunFinishReason,
 } from "./types"

package/src/storage/agents/provider.ts

@@ -0,0 +1,27 @@
+import { agentServiceAccountId } from "../../agents/authority"
+import type { ExecutionStorage } from "../executions"
+import { findAgentRunExecution } from "../executions/run-link"
+import { AgentStorageError } from "./errors"
+
+/** Validate the semantic link between a conversational Agent run and its immutable execution. */
+export async function assertAgentRunExecution(input: {
+  readonly executions: ExecutionStorage
+  readonly projectId: string
+  readonly executionId: string
+  readonly runId: string
+  readonly agentId: string
+}): Promise<void> {
+  const execution = await findAgentRunExecution({
+    executions: input.executions,
+    projectId: input.projectId,
+    executionId: input.executionId,
+    runId: input.runId,
+    serviceAccountId: agentServiceAccountId(input.agentId),
+  })
+  if (!execution) {
+    throw new AgentStorageError(
+      "invalid_input",
+      `[Sixb] Execution '${input.executionId}' does not authorize Agent run '${input.runId}'.`
+    )
+  }
+}