@sixb/core 0.1.17 → 0.1.19

package/src/runtime/types.ts

@@ -5,13 +5,9 @@
  * Each level narrows generic parameters so downstream code stays type-safe.
  */
 
-import type {
-  ActionDefinitionCatalog,
-  ActionParamsConfig,
-  InferActionParams,
-  RequestActionResult,
-} from "../actions"
+import type { ActionDefinitionCatalog, ActionParamsConfig, InferActionParams } from "../actions"
 import type { AuthorizationContext } from "../authorization"
+import type { OpenedFileRef } from "../blob-storage"
 import type { Broker } from "../broker"
 import type { DomainEventLog } from "../events"
 import type { RuntimeAuthorization } from "../execution"
@@ -43,11 +39,12 @@ import type { OntologyDocumentInput, OntologyRegistry, OntologySource } from "..
 import type {
   LinkToken,
   ObjectTypeProperties,
+  ObjectTypeReadProperties,
   ObjectTypeWithPropertyTokens,
   PropertyToken,
 } from "../ontology/tokens"
 import type { Queues } from "../queues"
-import type { ActionRunRecord, ObjectLinkRow, Storage } from "../storage"
+import type { ActionRunRecord, ObjectLinkRow, Redactions, Storage } from "../storage"
 // ── Shared runtime context ──────────────────────────────────
 
 /**
@@ -100,7 +97,7 @@ export type { OntologyDocumentInput, OntologySource }
 // ── Rows ────────────────────────────────────────────────────
 //
 // Rows read `properties` from the type inferred where the object type is defined
-// (`ObjectTypeProperties`), never from the schema, so relating two rows — or anything returning
+// (`ObjectTypeReadProperties`), never from the schema, so relating two rows — or anything returning
 // them — costs no schema inference. Rows and query builders also declare their variance, so
 // TypeScript never measures it: a measurement that overflows (TS2589) caches the variance it gave
 // up on, under which a plain query once passed for an expanded one.
@@ -109,7 +106,10 @@ export type { OntologyDocumentInput, OntologySource }
 export type TwinObject<out TObjectType extends ObjectTypeWithPropertyTokens> = {
   primaryId: string
   objectTypeId: TObjectType["id"]
-  properties: ObjectTypeProperties<TObjectType>
+  /** A marked property is absent when the reader lacks its clearance; see `redactions`. */
+  properties: ObjectTypeReadProperties<TObjectType>
+  /** Properties omitted because the reader lacks a clearance, keyed by property id. */
+  redactions?: Redactions
   createdAt: Date
   updatedAt: Date
 }
@@ -313,6 +313,32 @@ export type ObjectWhereBuilder<TObjectType extends ObjectTypeWithPropertyTokens>
 export type TelemetryPropertyToken<TObjectType extends ObjectTypeWithPropertyTokens> =
   TObjectType["p"][InferTelemetryPropertyIds<TObjectType>]
 
+type FilePropertyId<TObjectType extends ObjectTypeWithPropertyTokens, TSchema> = Extract<
+  TObjectType["properties"][number],
+  { readonly schema: TSchema }
+>["id"]
+
+/** A property token holding one file: its schema is `"fileRef"`. */
+export type FilePropertyToken<TObjectType extends ObjectTypeWithPropertyTokens> =
+  TObjectType["p"][FilePropertyId<TObjectType, "fileRef">]
+
+/** A property token holding a list of files: an array of `"fileRef"`. */
+export type FileListPropertyToken<TObjectType extends ObjectTypeWithPropertyTokens> =
+  TObjectType["p"][FilePropertyId<
+    TObjectType,
+    { readonly type: "array"; readonly items: "fileRef" }
+  >]
+
+/** One file property value of one object, read through that object. */
+export interface ObjectFileHandle {
+  /**
+   * Re-read the object with the caller's permissions and open the file it references. Returns
+   * null when the object, the value or its stored blob is absent; throws `AuthorizationError`
+   * when the caller cannot view the object type or is not cleared for the property's markings.
+   */
+  open(): Promise<OpenedFileRef | null>
+}
+
 type AnyPropertyToken = PropertyToken<string, string, Property>
 
 type ObjectSetPropertyId<TObjectType extends ObjectTypeWithPropertyTokens> =
@@ -773,6 +799,11 @@ export interface ObjectReadByIdHandle<out TObjectType extends ObjectTypeWithProp
 
   /** List links from this object, optionally filtered by link token. */
   listLinks(link?: LinkTokenForObjectType<TObjectType>): Promise<readonly ObjectLinkRow[]>
+
+  /** Read a `fileRef` property of this object. */
+  file(property: FilePropertyToken<TObjectType>): ObjectFileHandle
+  /** Read one file of a property holding a list of files. */
+  file(property: FileListPropertyToken<TObjectType>, index: number): ObjectFileHandle
 }
 
 /**
@@ -824,36 +855,25 @@ export interface ObjectByIdHandle<TObjectType extends ObjectTypeWithPropertyToke
     target: ObjectRef<ResolveTargetTypeId<TLinkToken["targetObjectTypeId"]>>
   ): Promise<void>
 
-  /** Request an action on this object by id (dynamic / server contexts). */
+  /**
+   * Run an action on this object by id (dynamic / server contexts) and return its terminal run.
+   * A failed run resolves with status `failed`.
+   */
   requestAction(input: {
     actionId: string
     params?: Record<string, unknown>
     runId?: string
-  }): Promise<RequestActionResult>
+    signal?: AbortSignal
+  }): Promise<ActionRunRecord>
 
   /**
-   * Request an action on this object using a typed action reference.
+   * Run an action on this object using a typed action reference, and return its terminal run.
    * Params are inferred from the action's declared shape.
    */
   requestAction<const TAction extends TypedActionReference>(input: {
     action: TAction
     params: NoInfer<TypedActionParams<TAction>>
     runId?: string
-  }): Promise<RequestActionResult>
-
-  /** Request an action and wait for the terminal lifecycle event. */
-  requestActionAndWait(input: {
-    actionId: string
-    params?: Record<string, unknown>
-    timeoutMs?: number
-    signal?: AbortSignal
-  }): Promise<ActionRunRecord>
-
-  /** Request a typed action and wait for the terminal lifecycle event. */
-  requestActionAndWait<const TAction extends TypedActionReference>(input: {
-    action: TAction
-    params: NoInfer<TypedActionParams<TAction>>
-    timeoutMs?: number
     signal?: AbortSignal
   }): Promise<ActionRunRecord>
 
@@ -895,40 +915,27 @@ export interface ObjectSet<TObjectType extends ObjectTypeWithPropertyTokens>
     }[]
   ): Promise<void>
 
-  /** Request an action on an object of this type by id (dynamic / server contexts). */
+  /**
+   * Run an action on an object of this type by id (dynamic / server contexts) and return its
+   * terminal run. A failed run resolves with status `failed`.
+   */
   requestAction(input: {
     id: string
     actionId: string
     params?: Record<string, unknown>
     runId?: string
-  }): Promise<RequestActionResult>
+    signal?: AbortSignal
+  }): Promise<ActionRunRecord>
 
   /**
-   * Request an action on an object of this type using a typed action reference.
-   * Params are inferred from the action's declared shape.
+   * Run an action on an object of this type using a typed action reference, and return its
+   * terminal run. Params are inferred from the action's declared shape.
    */
   requestAction<const TAction extends TypedActionReference>(input: {
     id: string
     action: TAction
     params: NoInfer<TypedActionParams<TAction>>
     runId?: string
-  }): Promise<RequestActionResult>
-
-  /** Request an action on an object and wait for the terminal lifecycle event. */
-  requestActionAndWait(input: {
-    id: string
-    actionId: string
-    params?: Record<string, unknown>
-    timeoutMs?: number
-    signal?: AbortSignal
-  }): Promise<ActionRunRecord>
-
-  /** Request a typed action and wait for the terminal lifecycle event. */
-  requestActionAndWait<const TAction extends TypedActionReference>(input: {
-    id: string
-    action: TAction
-    params: NoInfer<TypedActionParams<TAction>>
-    timeoutMs?: number
     signal?: AbortSignal
   }): Promise<ActionRunRecord>
 

package/src/scheduler/runtime.ts

@@ -18,6 +18,8 @@ const MAX_TIMER_DELAY_MS = 2_147_483_647
 export interface SchedulerRuntimeOptions {
   schedules: readonly ScheduleDefinition[]
   events: DomainEventLog
+  /** Evaluates cron schedules that set no time zone of their own. Defaults to UTC. */
+  timeZone?: string
   now?: () => Date
 }
 
@@ -30,6 +32,7 @@ export interface SchedulerController {
 export class SchedulerRuntime implements SchedulerController {
   private readonly schedules: readonly CronScheduleDefinition[]
   private readonly events: DomainEventLog
+  private readonly timeZone: string | undefined
   private readonly now: () => Date
   private started = false
   private timer: ReturnType<typeof setTimeout> | null = null
@@ -39,6 +42,8 @@ export class SchedulerRuntime implements SchedulerController {
   constructor(options: SchedulerRuntimeOptions) {
     this.schedules = options.schedules.filter(isCronSchedule)
     this.events = options.events
+    // `undefined` keeps the arithmetic UTC path; an explicit "UTC" would go through Intl.
+    this.timeZone = options.timeZone === "UTC" ? undefined : options.timeZone
     this.now = options.now ?? (() => new Date())
   }
 
@@ -60,7 +65,11 @@ export class SchedulerRuntime implements SchedulerController {
       // agree, or one unschedulable expression stops every other schedule in the project and
       // crash-loops the scheduler role.
       try {
-        const next = nextCronOccurrence(schedule.trigger.expression, now, schedule.trigger.timezone)
+        const next = nextCronOccurrence(
+          schedule.trigger.expression,
+          now,
+          schedule.trigger.timezone ?? this.timeZone
+        )
         this.nextOccurrences.set(schedule.id, next)
       } catch (error) {
         console.error(
@@ -178,7 +187,7 @@ export class SchedulerRuntime implements SchedulerController {
         const next = nextCronOccurrence(
           schedule.trigger.expression,
           occurrenceAt,
-          schedule.trigger.timezone
+          schedule.trigger.timezone ?? this.timeZone
         )
         this.nextOccurrences.set(schedule.id, next)
       } catch (error) {

package/src/schedules/builders.ts

@@ -169,9 +169,6 @@ function assertEventSource(source: EventSelectorSpec): void {
     case "rules":
       assertNonEmpty(source.ruleId ?? "", "event source ruleId")
       return
-    case "actions":
-      assertNonEmpty(source.actionId ?? "", "event source actionId")
-      return
     case "datasets":
       assertNonEmpty(source.datasetId ?? "", "event source datasetId")
       return
@@ -183,7 +180,7 @@ function assertEventSource(source: EventSelectorSpec): void {
       return
     default:
       throw new ScheduleValidationError(
-        "Schedule event source must select object, link, rule, action, dataset, sync, or pipeline events."
+        "Schedule event source must select object, link, rule, dataset, sync, or pipeline events."
       )
   }
 }

package/src/schedules/runtime.ts

@@ -100,26 +100,6 @@ export function buildEventScheduleContext(event: DomainEvent): RuntimeEventSched
           primaryId: event.payload.subject.primaryId,
         },
       }
-    case "action.requested":
-      return {
-        actionId: event.payload.actionId,
-        runId: event.payload.runId,
-        ...actionSubjectContext(event.payload.subject),
-        params: { ...event.payload.params },
-      }
-    case "action.completed":
-      return {
-        actionId: event.payload.actionId,
-        runId: event.payload.runId,
-        ...actionSubjectContext(event.payload.subject),
-      }
-    case "action.failed":
-      return {
-        actionId: event.payload.actionId,
-        runId: event.payload.runId,
-        ...actionSubjectContext(event.payload.subject),
-        error: event.payload.error,
-      }
     case "dataset.version.committed":
       return { ...event.payload }
     case "sync.run.finished":
@@ -131,27 +111,6 @@ export function buildEventScheduleContext(event: DomainEvent): RuntimeEventSched
   }
 }
 
-function actionSubjectContext(subject: {
-  readonly kind: "none" | "object"
-  readonly objectTypeId?: string
-  readonly primaryId?: string
-}): { readonly subject?: { readonly objectTypeId: string; readonly primaryId: string } } {
-  if (
-    subject.kind !== "object" ||
-    subject.objectTypeId === undefined ||
-    subject.primaryId === undefined
-  ) {
-    return {}
-  }
-
-  return {
-    subject: {
-      objectTypeId: subject.objectTypeId,
-      primaryId: subject.primaryId,
-    },
-  }
-}
-
 function fieldsForEvent(event: DomainEvent): Readonly<Record<string, unknown>> {
   if (event.topic !== "links") {
     return {}

package/src/schedules/validation.ts

@@ -8,7 +8,6 @@ import type { EventScheduleCondition, EventScheduleDefinition, ScheduleDefinitio
 const objectEventTypes = new Set(["object.created", "object.updated", "object.deleted"])
 const linkEventTypes = new Set(["link.created", "link.updated", "link.deleted"])
 const ruleEventTypes = new Set(["rule.triggered", "rule.resolved"])
-const actionEventTypes = new Set(["action.requested", "action.completed", "action.failed"])
 const datasetEventTypes = new Set(["dataset.version.committed"])
 const syncEventTypes = new Set(["sync.run.finished"])
 const pipelineEventTypes = new Set(["pipeline.run.finished"])
@@ -17,7 +16,6 @@ const linkIdentityFields = new Set(["target.objectTypeId", "target.primaryId"])
 
 export interface ValidateSchedulesAtStartupOptions {
   readonly registeredRuleIds?: ReadonlySet<string>
-  readonly registeredActionIds?: ReadonlySet<string>
   readonly registeredDatasetIds?: ReadonlySet<string>
   readonly registeredSyncIds?: ReadonlySet<string>
   readonly registeredPipelineIds?: ReadonlySet<string>
@@ -138,9 +136,6 @@ function assertEventSourceShape(
     case "rules":
       assertNonEmptyString(value.ruleId, `${path} ruleId`, createError)
       return
-    case "actions":
-      assertNonEmptyString(value.actionId, `${path} actionId`, createError)
-      return
     case "datasets":
       assertNonEmptyString(value.datasetId, `${path} datasetId`, createError)
       return
@@ -154,7 +149,7 @@ function assertEventSourceShape(
       return
     default:
       throw createError(
-        `${path} must select object, link, rule, action, dataset, sync, or pipeline events.`
+        `${path} must select object, link, rule, dataset, sync, or pipeline events.`
       )
   }
 }
@@ -212,15 +207,6 @@ function validateEventSchedule(
         "rule"
       )
       return
-    case "actions":
-      validateRegisteredSource(
-        schedule,
-        source.actionId,
-        options.registeredActionIds,
-        actionEventTypes,
-        "action"
-      )
-      return
     case "datasets":
       validateRegisteredSource(
         schedule,
@@ -294,7 +280,7 @@ function validateRegisteredSource(
   sourceId: string | undefined,
   registeredIds: ReadonlySet<string> | undefined,
   supportedTypes: ReadonlySet<string>,
-  sourceKind: "rule" | "action" | "dataset" | "sync" | "pipeline"
+  sourceKind: "rule" | "dataset" | "sync" | "pipeline"
 ): void {
   validateEventTypes(schedule, supportedTypes, sourceKind)
   if (!registeredIds?.has(sourceId ?? "")) {

package/src/security/builders.ts

@@ -2,6 +2,7 @@ import { SecurityValidationError } from "./errors"
 import type {
   GrantDefinition,
   GroupDefinition,
+  MarkingDefinition,
   MembershipOperation,
   MembershipPolicyDefinition,
   RoleDefinition,
@@ -18,11 +19,18 @@ export interface DefineGroupOptions {
   readonly description?: string
 }
 
+export interface DefineMarkingOptions {
+  readonly label?: string
+  readonly description?: string
+}
+
 export interface DefineRoleOptions {
   readonly label?: string
   readonly description?: string
   readonly grantedTo: readonly GroupDefinition[]
-  readonly grants: readonly GrantDefinition[]
+  readonly grants?: readonly GrantDefinition[]
+  /** Markings this role's members may read. */
+  readonly clearances?: readonly MarkingDefinition[]
 }
 
 export interface DefineMembershipPolicyOptions {
@@ -81,6 +89,37 @@ export function defineGroup<const TId extends string>(
   }
 }
 
+/** Read the ids of marking definitions, rejecting anything else such as a bare id. */
+export function markingIdsFrom(
+  markings: readonly MarkingDefinition[],
+  field: string
+): readonly string[] {
+  return markings.map((marking) => {
+    if (!isRecord(marking) || marking.kind !== "marking") {
+      throw new SecurityValidationError(`[Sixb] ${field} must contain only marking definitions.`)
+    }
+
+    assertNonEmptyString(marking.id, `${field} marking id`)
+    return marking.id
+  })
+}
+
+export function defineMarking<const TId extends string>(
+  id: TId,
+  options: DefineMarkingOptions = {}
+): MarkingDefinition<TId> {
+  assertNonEmptyString(id, "Marking id")
+  assertOptionalString(options.label, `Marking '${id}' label`)
+  assertOptionalString(options.description, `Marking '${id}' description`)
+
+  return {
+    kind: "marking",
+    id,
+    ...(options.label !== undefined ? { label: options.label } : {}),
+    ...(options.description !== undefined ? { description: options.description } : {}),
+  }
+}
+
 export function defineRole<const TId extends string>(
   id: TId,
   options: DefineRoleOptions
@@ -91,13 +130,17 @@ export function defineRole<const TId extends string>(
   assertNonEmptyArray(options.grantedTo, `Role '${id}' grantedTo`)
 
   const grantedToGroupIds = groupIdsFrom(options.grantedTo, `Role '${id}' grantedTo`)
+  const grants = options.grants ?? []
+  const clearances = markingIdsFrom(options.clearances ?? [], `Role '${id}' clearances`)
 
-  for (const grant of options.grants) {
+  for (const grant of grants) {
     assertGrantDefinition(grant, `Role '${id}' grants`)
   }
 
-  if (options.grants.length === 0) {
-    throw new SecurityValidationError(`[Sixb] Role '${id}' grants must not be empty.`)
+  if (grants.length === 0 && clearances.length === 0) {
+    throw new SecurityValidationError(
+      `[Sixb] Role '${id}' must declare at least one grant or clearance.`
+    )
   }
 
   return {
@@ -106,7 +149,8 @@ export function defineRole<const TId extends string>(
     ...(options.label !== undefined ? { label: options.label } : {}),
     ...(options.description !== undefined ? { description: options.description } : {}),
     grantedToGroupIds,
-    grants: options.grants,
+    grants,
+    ...(clearances.length > 0 ? { clearances } : {}),
   }
 }
 

package/src/security/every.ts

@@ -8,7 +8,7 @@
  *
  * They live under one `every` namespace on purpose. Spending seven of the best identifiers in
  * `@sixb/core` — `actions`, `workflows`, `syncs`, … — on an auxiliary subsystem collided with the
- * primitives themselves and with `events.actions()` / `logs.actions()` on the client.
+ * primitives themselves and with client builders such as `logs.actions()`.
  */
 
 import type { ActionDefinition } from "../actions/types"

package/src/security/index.ts

@@ -1,10 +1,11 @@
 export { applications } from "./applications"
 export type {
   DefineGroupOptions,
+  DefineMarkingOptions,
   DefineMembershipPolicyOptions,
   DefineRoleOptions,
 } from "./builders"
-export { defineGroup, defineMembershipPolicy, defineRole } from "./builders"
+export { defineGroup, defineMarking, defineMembershipPolicy, defineRole } from "./builders"
 export { SecurityValidationError } from "./errors"
 export type { BreadthSelector, BreadthTarget } from "./every"
 export { every } from "./every"
@@ -31,10 +32,13 @@ export type {
   GroupReference,
   ManageGrant,
   ManageGrantTarget,
+  MarkingDefinition,
   MembershipOperation,
   MembershipPolicyDefinition,
   ObserveGrant,
   ObserveGrantTarget,
+  RedactionReason,
+  Redactions,
   RegisteredSecurityDefinitions,
   RoleDefinition,
   RunGrant,
@@ -50,6 +54,7 @@ export {
   assertMembershipPolicyDefinition,
   assertRoleDefinition,
   isGroupDefinition,
+  isMarkingDefinition,
   isMembershipPolicyDefinition,
   isRoleDefinition,
   validateSecurityDefinitionsAtStartup,