@sixb/core 0.1.21 → 0.1.22

package/src/events/selectors/builder.ts

@@ -13,6 +13,8 @@ import type {
   RunEventSelectorOperation,
   SyncEventSelectorContext,
   SyncEventToken,
+  UserEventSelectorContext,
+  UserEventSelectorOperation,
 } from "./types"
 
 type EventPropertySelectorMap<TTokens, TContext> = {
@@ -94,6 +96,17 @@ export interface PipelineEventSelectorBuilder<TPipeline extends PipelineEventTok
   cancelled(): EventSelectorSpec<PipelineEventSelectorContext<TPipeline, "cancelled">>
 }
 
+/** Member events, project-wide: there is one member directory per project. */
+export interface UserEventSelectorBuilder extends EventSelectorSpec<UserEventSelectorContext> {
+  /** A person signed in for the first time, which created their account. */
+  joined(): EventSelectorSpec<UserEventSelectorContext<"joined">>
+  suspended(): EventSelectorSpec<UserEventSelectorContext<"suspended">>
+  reactivated(): EventSelectorSpec<UserEventSelectorContext<"reactivated">>
+  invited(): EventSelectorSpec<UserEventSelectorContext<"invited">>
+  /** A member's name or picture changed, by their own edit or their identity provider. */
+  profileUpdated(): EventSelectorSpec<UserEventSelectorContext<"profileUpdated">>
+}
+
 abstract class EventSelectorSpecView<TContext> implements EventSelectorSpec<TContext> {
   constructor(protected readonly spec: EventSelectorSpec<TContext>) {}
 
@@ -392,6 +405,39 @@ class PipelineEventSelectorBuilderImpl<TPipeline extends PipelineEventToken>
   }
 }
 
+class UserEventSelectorBuilderImpl
+  extends EventSelectorSpecView<UserEventSelectorContext>
+  implements UserEventSelectorBuilder
+{
+  joined(): EventSelectorSpec<UserEventSelectorContext<"joined">> {
+    return this.withType("user.joined")
+  }
+
+  suspended(): EventSelectorSpec<UserEventSelectorContext<"suspended">> {
+    return this.withType("user.suspended")
+  }
+
+  reactivated(): EventSelectorSpec<UserEventSelectorContext<"reactivated">> {
+    return this.withType("user.reactivated")
+  }
+
+  invited(): EventSelectorSpec<UserEventSelectorContext<"invited">> {
+    return this.withType("user.invited")
+  }
+
+  profileUpdated(): EventSelectorSpec<UserEventSelectorContext<"profileUpdated">> {
+    return this.withType("user.profile.updated")
+  }
+
+  private withType<TOperation extends UserEventSelectorOperation>(
+    type: Extract<DomainEvent["type"], `user.${string}`>
+  ): EventSelectorSpec<UserEventSelectorContext<TOperation>> {
+    return { ...this.spec, types: [type] } as EventSelectorSpec<
+      UserEventSelectorContext<TOperation>
+    >
+  }
+}
+
 export interface EventSelectors {
   object<TObjectType extends ObjectTypeWithTokens>(
     objectType: TObjectType
@@ -404,6 +450,7 @@ export interface EventSelectors {
   pipeline<TPipeline extends PipelineEventToken>(
     pipeline: TPipeline
   ): PipelineEventSelectorBuilder<TPipeline>
+  users(): UserEventSelectorBuilder
 }
 
 export const events: EventSelectors = {
@@ -440,6 +487,9 @@ export const events: EventSelectors = {
       pipelineId: pipeline.id,
     } as EventSelectorSpec<PipelineEventSelectorContext<TPipeline>>)
   },
+  users(): UserEventSelectorBuilder {
+    return new UserEventSelectorBuilderImpl({ topic: "users" })
+  },
 }
 
 function createPropertySelectorMap(

package/src/events/selectors/index.ts

@@ -7,6 +7,7 @@ export type {
   PipelineEventSelectorBuilder,
   RuleEventSelectorBuilder,
   SyncEventSelectorBuilder,
+  UserEventSelectorBuilder,
 } from "./builder"
 export { events } from "./builder"
 export { buildEventSelectorPredicate, eventSelectorSpec } from "./predicate"
@@ -33,4 +34,7 @@ export type {
   SyncEventSelectorContext,
   SyncEventSelectorEvent,
   SyncEventToken,
+  UserEventSelectorContext,
+  UserEventSelectorEvent,
+  UserEventSelectorOperation,
 } from "./types"

package/src/events/selectors/types.ts

@@ -7,6 +7,7 @@ import type {
   DomainEvent,
   PipelineRunFinishedEvent,
   SyncRunFinishedEvent,
+  UserEvent,
 } from "../types"
 
 declare const eventSelectorContextType: unique symbol
@@ -78,6 +79,20 @@ export type PipelineEventSelectorContext<
   readonly operation: TOperation
 }
 
+export type UserEventSelectorOperation =
+  | "joined"
+  | "suspended"
+  | "reactivated"
+  | "invited"
+  | "profileUpdated"
+
+export type UserEventSelectorContext<
+  TOperation extends UserEventSelectorOperation = UserEventSelectorOperation,
+> = {
+  readonly kind: "user"
+  readonly operation: TOperation
+}
+
 export type EventSelectorContext =
   | ObjectEventSelectorContext
   | LinkEventSelectorContext
@@ -85,6 +100,7 @@ export type EventSelectorContext =
   | DatasetEventSelectorContext
   | SyncEventSelectorContext
   | PipelineEventSelectorContext
+  | UserEventSelectorContext
 
 export type InferEventSelectorContext<TSelector> = TSelector extends {
   readonly [eventSelectorContextType]?: infer TContext
@@ -109,7 +125,9 @@ export type EventSelectorEvent<TContext> =
             ? SyncEventSelectorEvent<TSync, TOperation>
             : TContext extends PipelineEventSelectorContext<infer TPipeline, infer TOperation>
               ? PipelineEventSelectorEvent<TPipeline, TOperation>
-              : never
+              : TContext extends UserEventSelectorContext<infer TOperation>
+                ? UserEventSelectorEvent<TOperation>
+                : never
 
 export interface ObjectEventSelectorEvent<TObjectType extends ObjectTypeWithTokens> {
   readonly object: {
@@ -160,6 +178,19 @@ export type PipelineEventSelectorEvent<
   readonly status: TOperation
 }
 
+type UserEventTypeOf = {
+  readonly joined: "user.joined"
+  readonly suspended: "user.suspended"
+  readonly reactivated: "user.reactivated"
+  readonly invited: "user.invited"
+  readonly profileUpdated: "user.profile.updated"
+}
+
+/** The payload of the member event an operation selects. */
+export type UserEventSelectorEvent<
+  TOperation extends UserEventSelectorOperation = UserEventSelectorOperation,
+> = Extract<UserEvent, { type: UserEventTypeOf[TOperation] }>["payload"]
+
 export interface EventSelectorSpec<TContext = EventSelectorContext> {
   readonly [eventSelectorContextType]?: TContext
   readonly topic?: DomainEvent["topic"]

package/src/events/service.ts

@@ -3,6 +3,7 @@ import type { Broker, BrokerCursor, BrokerRecord, BrokerStreamDefinition } from
 import { type ErrorReporter, SixbErrorReporter } from "../error-reporting/reporter"
 import { reportEventDeliveryFailure } from "../error-reporting/reports"
 import { getInvalidJsonValueReason, type JsonValue } from "../json"
+import { objectPartitionKey } from "../materialization/event-envelopes"
 import type { OntologyMaterializationEvent } from "../materialization/events"
 import {
   EVENT_DEFINITIONS,
@@ -12,7 +13,14 @@ import {
   resolveEventStorage,
 } from "./definitions"
 import { EventsError } from "./errors"
-import type { DomainEvent, EventDraft, StoredAuthorableEvent, StoredDomainEvent } from "./types"
+import type {
+  DomainEvent,
+  EventDraft,
+  StoredAuthorableEvent,
+  StoredDomainEvent,
+  StoredObjectDeletedEvent,
+  StoredObjectMutationEvent,
+} from "./types"
 
 // Keep domain events as a short recent log. This is 2 days in milliseconds.
 export const DEFAULT_EVENTS_RETENTION_MS = 2 * 24 * 60 * 60 * 1000
@@ -55,6 +63,15 @@ export interface EventsSubscribeInput {
   readonly types?: readonly DomainEvent["type"][]
 }
 
+export interface ObjectEventBeforeInput {
+  /** The event of the log to look before. */
+  readonly cursor: string
+  readonly objectTypeId: string
+  readonly primaryId: string
+}
+
+const OBJECT_EVENT_TYPES = EVENT_TYPES.filter((type) => EVENT_DEFINITIONS[type].topic === "objects")
+
 /** Exact, already-identified materialization event persisted before broker publication. @internal */
 export type StableEventEnvelope = OntologyMaterializationEvent
 
@@ -76,13 +93,26 @@ export interface DomainEventLog {
   ): Promise<() => void>
 }
 
+/** Internal port that reads the log for what an object held when another event happened. */
+export interface ObjectEventHistory {
+  /**
+   * The last event of an object before an event of the log, which carries the state the object
+   * held when that event happened. Undefined when the log keeps none.
+   */
+  lastObjectEventBefore(
+    input: ObjectEventBeforeInput
+  ): Promise<StoredObjectMutationEvent | StoredObjectDeletedEvent | undefined>
+}
+
 /** Narrow internal port used to publish envelopes already persisted in the ontology outbox. */
 export interface StableEventPublisher {
   publishEnvelopes(envelopes: readonly StableEventEnvelope[]): Promise<readonly StoredDomainEvent[]>
 }
 
 /** Project-scoped domain event service backed by the shared broker provider. */
-export class DomainEventService implements DomainEventLog, StableEventPublisher {
+export class DomainEventService
+  implements DomainEventLog, ObjectEventHistory, StableEventPublisher
+{
   private readonly projectId: string
   private readonly broker: Broker
   private readonly stream: BrokerStreamDefinition
@@ -233,6 +263,29 @@ export class DomainEventService implements DomainEventLog, StableEventPublisher
     return page.records.map(hydrateEventRecord)
   }
 
+  async lastObjectEventBefore(
+    input: ObjectEventBeforeInput
+  ): Promise<StoredObjectMutationEvent | StoredObjectDeletedEvent | undefined> {
+    await this.ensureStream()
+    const page = await this.broker.tail({
+      projectId: this.projectId,
+      streamId: this.stream.id,
+      beforeCursor: input.cursor,
+      limit: 1,
+      names: OBJECT_EVENT_TYPES,
+      keys: [objectPartitionKey(input)],
+    })
+
+    const [event] = page.records.map(hydrateEventRecord)
+    if (event?.topic !== "objects") return undefined
+
+    // A key joins two ids with a colon, so another object could share it: that one says nothing.
+    const { objectTypeId, primaryId } = event.payload
+    if (objectTypeId !== input.objectTypeId || primaryId !== input.primaryId) return undefined
+
+    return event
+  }
+
   async latestCursor(): Promise<string | undefined> {
     await this.ensureStream()
     return this.broker.latestCursor({

package/src/events/types/index.ts

@@ -9,6 +9,7 @@ import type { RuleEvent } from "./rules"
 import type { ScheduleEvent } from "./schedules"
 import type { SyncEvent } from "./syncs"
 import type { TelemetryEvent } from "./telemetry"
+import type { UserEvent } from "./users"
 import type { WorkflowEvent } from "./workflows"
 
 export type { EventExecutor } from "../../materialization/events"
@@ -56,6 +57,14 @@ export type {
 export type { ScheduleEvent, ScheduleTriggeredEvent } from "./schedules"
 export type { SyncEvent, SyncRunFinishedEvent, SyncRunStartedEvent } from "./syncs"
 export type { TelemetryAppendedEvent, TelemetryEvent } from "./telemetry"
+export type {
+  UserEvent,
+  UserInvitedEvent,
+  UserJoinedEvent,
+  UserProfileUpdatedEvent,
+  UserReactivatedEvent,
+  UserSuspendedEvent,
+} from "./users"
 export type {
   WorkflowEvent,
   WorkflowInterventionCancelledEvent,
@@ -81,6 +90,7 @@ export type DomainEvent =
   | PipelineEvent
   | WorkflowEvent
   | DatasetEvent
+  | UserEvent
 
 export type OntologyDomainEvent = ObjectEvent | LinkEvent | TelemetryEvent
 export type AuthorableDomainEvent = Exclude<DomainEvent, OntologyDomainEvent>

package/src/events/types/users.ts

@@ -0,0 +1,73 @@
+import type { AuthorizablePrincipal } from "../../execution/types"
+import type { UserProfile } from "../../users"
+import type { EventEnvelope } from "../envelope"
+import type { PropertyChange } from "../property-changes"
+
+/** A person signed in for the first time, which created their account. */
+export interface UserJoinedEvent extends EventEnvelope {
+  type: "user.joined"
+  topic: "users"
+  partitionKey: string
+  payload: {
+    user: UserProfile
+    /** The invitation they accepted. Absent when they joined without one. */
+    invitationId?: string
+  }
+}
+
+export interface UserSuspendedEvent extends EventEnvelope {
+  type: "user.suspended"
+  topic: "users"
+  partitionKey: string
+  payload: {
+    user: UserProfile
+    requestedBy: AuthorizablePrincipal
+  }
+}
+
+export interface UserReactivatedEvent extends EventEnvelope {
+  type: "user.reactivated"
+  topic: "users"
+  partitionKey: string
+  payload: {
+    user: UserProfile
+    requestedBy: AuthorizablePrincipal
+  }
+}
+
+/** Someone was invited. They become a member, with `user.joined`, at their first sign-in. */
+export interface UserInvitedEvent extends EventEnvelope {
+  type: "user.invited"
+  topic: "users"
+  partitionKey: string
+  payload: {
+    invitationId: string
+    email: string
+    expiresAt: string
+    requestedBy: AuthorizablePrincipal
+  }
+}
+
+/** A member's name or picture changed. */
+export interface UserProfileUpdatedEvent extends EventEnvelope {
+  type: "user.profile.updated"
+  topic: "users"
+  partitionKey: string
+  payload: {
+    user: UserProfile
+    /** Only the fields that changed. */
+    changes: {
+      displayName?: PropertyChange<string>
+      avatarUrl?: PropertyChange<string>
+    }
+    /** The member who edited their profile. Absent when their identity provider changed it. */
+    requestedBy?: AuthorizablePrincipal
+  }
+}
+
+export type UserEvent =
+  | UserJoinedEvent
+  | UserSuspendedEvent
+  | UserReactivatedEvent
+  | UserInvitedEvent
+  | UserProfileUpdatedEvent

package/src/events/view-conditions.ts

@@ -0,0 +1,241 @@
+import type {
+  AuthorizedObjectReader,
+  ReaderViewCondition,
+} from "../execution/authorized-object-reader"
+import type { Clearance } from "../execution/object-reader-clearance"
+import { type ObjectKey, visibleObjects } from "../execution/visible-objects"
+import { matchesPredicate } from "../objects/query/matches-predicate"
+import { type ObjectBatchKey, objectBatchKey } from "../storage"
+import type { PropertyChangeMap } from "./property-changes"
+import type {
+  StoredDomainEvent,
+  StoredObjectDeletedEvent,
+  StoredObjectMutationEvent,
+} from "./types"
+
+/** Decided from the state the event carries, or by whether the reader sees the objects it names. */
+type Decision = boolean | { readonly named: readonly ObjectKey[] }
+
+/** Where the state of an object that no longer exists is found. */
+export interface ObjectHistory {
+  /** The objects among these that exist, whoever may see them. */
+  existing(objects: readonly ObjectKey[]): Promise<ReadonlySet<ObjectBatchKey>>
+
+  /** The last event of an object before this event, or undefined when the log keeps none. */
+  lastEventBefore(
+    event: StoredDomainEvent,
+    object: ObjectKey
+  ): Promise<StoredObjectMutationEvent | StoredObjectDeletedEvent | undefined>
+}
+
+/**
+ * The events, in order, whose objects a reader sees under the conditions it views their types
+ * through. An event that names no conditioned type passes: its grants decided it.
+ *
+ * - An object's creation or update is decided on the state it carries, its deletion on the last
+ *   state the object held.
+ * - Link events, telemetry and rule transitions carry no state to decide on. The objects they name
+ *   of a conditioned type are read through the reader as they are now, in one call for the batch.
+ * - One that no longer exists is decided on the state it held when the event happened, from its
+ *   last event before it. A reader who saw an object is told what its deletion removed, and
+ *   one who never saw it is told nothing, as for a hidden object.
+ */
+export async function visibleUnderConditions(
+  reader: AuthorizedObjectReader,
+  events: readonly StoredDomainEvent[],
+  conditions: ReadonlyMap<string, ReaderViewCondition>,
+  clearanceFor: (event: StoredDomainEvent) => Clearance,
+  history: ObjectHistory
+): Promise<readonly StoredDomainEvent[]> {
+  if (conditions.size === 0) return events
+
+  const decisions = events.map((event) => decide(event, conditions, clearanceFor(event)))
+
+  const named = decisions.flatMap((decision) =>
+    typeof decision === "boolean" ? [] : decision.named
+  )
+  const seenNow = await visibleObjects(reader, named)
+  const seenThen = await seenBeforeDeletion(events, decisions, seenNow, conditions, history)
+
+  return events.filter((_, index) => {
+    const decision = decisions[index]!
+    if (typeof decision === "boolean") return decision
+
+    return decision.named.every((object) => {
+      const key = objectBatchKey(object.objectTypeId, object.primaryId)
+      return seenNow.has(key) || seenThen.has(eventObjectKey(index, key))
+    })
+  })
+}
+
+/**
+ * Among the objects the reader does not see now, those that no longer exist and that it saw when
+ * the event naming them happened, keyed by {@link eventObjectKey}.
+ *
+ * One that still exists is hidden, and its events with it. Only the others are looked up in the
+ * log, so a reader pays for it only when an event names an object since deleted.
+ */
+async function seenBeforeDeletion(
+  events: readonly StoredDomainEvent[],
+  decisions: readonly Decision[],
+  seenNow: ReadonlySet<ObjectBatchKey>,
+  conditions: ReadonlyMap<string, ReaderViewCondition>,
+  history: ObjectHistory
+): Promise<ReadonlySet<string>> {
+  const unseen = decisions.flatMap((decision, index) =>
+    typeof decision === "boolean"
+      ? []
+      : decision.named
+          .map((object) => ({
+            index,
+            object,
+            key: objectBatchKey(object.objectTypeId, object.primaryId),
+          }))
+          .filter(({ key }) => !seenNow.has(key))
+  )
+  if (unseen.length === 0) return new Set()
+
+  const unique = new Map(unseen.map(({ object, key }) => [key, object]))
+  const existing = await history.existing([...unique.values()])
+  const deleted = unseen.filter(({ key }) => !existing.has(key))
+
+  const seenThen = await Promise.all(
+    deleted.map(async ({ index, object }) => {
+      const last = await history.lastEventBefore(events[index]!, object)
+      if (!last) return false
+
+      const properties =
+        last.type === "object.deleted"
+          ? lastState(last.payload.propertyChanges)
+          : last.payload.properties
+
+      return matchesPredicate({ properties }, conditions.get(object.objectTypeId)!.predicate)
+    })
+  )
+
+  return new Set(
+    deleted.flatMap(({ index, key }, at) => (seenThen[at] ? [eventObjectKey(index, key)] : []))
+  )
+}
+
+/** An object as one event of the batch names it. */
+function eventObjectKey(index: number, key: ObjectBatchKey): string {
+  return `${index}\u0000${key}`
+}
+
+function decide(
+  event: StoredDomainEvent,
+  conditions: ReadonlyMap<string, ReaderViewCondition>,
+  clearance: Clearance
+): Decision {
+  switch (event.topic) {
+    case "objects": {
+      const condition = conditions.get(event.payload.objectTypeId)
+      if (!condition) return true
+      if (condition.hiddenBy(clearance)) return false
+
+      const properties =
+        event.type === "object.deleted"
+          ? lastState(event.payload.propertyChanges)
+          : event.payload.properties
+
+      // The object is visible in the state the event carries. An update after which it no longer
+      // is delivers nothing: the reader's copy stays stale until it reads the object again.
+      return matchesPredicate({ properties }, condition.predicate)
+    }
+
+    case "links": {
+      const { sourceTypeId, sourceId, targetTypeId, targetId } = event.payload
+      return namedObjects(conditions, clearance, [
+        { objectTypeId: sourceTypeId, primaryId: sourceId },
+        { objectTypeId: targetTypeId, primaryId: targetId },
+      ])
+    }
+
+    case "telemetry": {
+      const { objectTypeId, objectId } = event.payload
+      return namedObjects(conditions, clearance, [{ objectTypeId, primaryId: objectId }])
+    }
+
+    case "rules": {
+      const { objectTypeId, primaryId } = event.payload.subject
+      return namedObjects(conditions, clearance, [{ objectTypeId, primaryId }])
+    }
+
+    default:
+      return true
+  }
+}
+
+/**
+ * An update shown to a reader who could not see the object before it: what the object held then
+ * is not this reader's to know. Decided on the event as stored, applied to the event as shown.
+ *
+ * Each change then reads as the object appearing with its new value. A property the update cleared
+ * did not exist for this reader, so its change is left out.
+ */
+export function withoutHiddenPriorState(
+  stored: StoredDomainEvent,
+  shown: StoredDomainEvent,
+  conditions: ReadonlyMap<string, ReaderViewCondition>
+): StoredDomainEvent {
+  if (stored.type !== "object.updated" || shown.type !== "object.updated") return shown
+
+  const condition = conditions.get(stored.payload.objectTypeId)
+  if (!condition) return shown
+
+  const prior = priorState(stored.payload.properties, stored.payload.propertyChanges)
+  if (matchesPredicate({ properties: prior }, condition.predicate)) return shown
+
+  const propertyChanges = Object.fromEntries(
+    Object.entries(shown.payload.propertyChanges).flatMap(([propertyId, change]) =>
+      change.operation === "cleared"
+        ? []
+        : [[propertyId, { operation: "created" as const, after: change.after }]]
+    )
+  )
+
+  return { ...shown, payload: { ...shown.payload, propertyChanges } }
+}
+
+/** The properties an object held before an update, from its new state and what changed. */
+function priorState(
+  properties: Readonly<Record<string, unknown>>,
+  changes: PropertyChangeMap
+): Record<string, unknown> {
+  const prior: Record<string, unknown> = { ...properties }
+
+  for (const [propertyId, change] of Object.entries(changes)) {
+    if (change.operation === "created") delete prior[propertyId]
+    else prior[propertyId] = change.before
+  }
+
+  return prior
+}
+
+/** The objects of a conditioned type among these, which the reader must see. */
+function namedObjects(
+  conditions: ReadonlyMap<string, ReaderViewCondition>,
+  clearance: Clearance,
+  objects: readonly ObjectKey[]
+): Decision {
+  const conditioned = objects.filter((object) => conditions.has(object.objectTypeId))
+  if (conditioned.length === 0) return true
+
+  if (conditioned.some((object) => conditions.get(object.objectTypeId)!.hiddenBy(clearance))) {
+    return false
+  }
+
+  return { named: conditioned }
+}
+
+/** A deletion records every property the object held as cleared, with the value it had. */
+function lastState(changes: PropertyChangeMap): Record<string, unknown> {
+  const properties: Record<string, unknown> = {}
+
+  for (const [propertyId, change] of Object.entries(changes)) {
+    if (change.operation !== "created") properties[propertyId] = change.before
+  }
+
+  return properties
+}

package/src/execution/agent.ts

@@ -109,6 +109,31 @@ export function bindDurableAgentExecution(
   return sixb
 }
 
+/**
+ * Bind one agent API gateway request to the run's own execution, the way the run's in-process
+ * tools are bound: what the request starts is a child of the run, with the run's requester and
+ * correlation. Model calls behind it count toward the attempt the request was admitted under, with
+ * a recorder of their own: the worker's in-memory failure state and cancellation do not reach them.
+ */
+export function bindAgentGatewayRequestExecution(
+  host: AgentExecutionHost,
+  input: {
+    /** Aborting it cancels the request's model calls. */
+    readonly signal: AbortSignal
+    readonly execution: ExecutionRecord
+    readonly actorId?: string
+    readonly runId: string
+    readonly attempt: number
+    readonly authorization: AgentExecutionAuthorization
+  }
+): Sixb {
+  const { signal, attempt, ...execution } = input
+  const sixb = bindDurableAgentExecution(host, execution)
+
+  bindModelExecutionAttempt(sixb.models, { attempt, signal })
+  return sixb
+}
+
 /**
  * Account model calls made through a run's bound SDK — by its tools, or embeddings behind their
  * searches — like the run's own: same execution attempt, limits, failure state and cancellation.