@sixb/core 0.1.0 → 0.1.2

package/src/blob-storage/execution.ts

@@ -0,0 +1,78 @@
+import { assertProviderAccess } from "../authorization"
+import type { ExecutionContext } from "../execution"
+import type { SixbRuntimeContext } from "../runtime/types"
+import type {
+  AbortBlobUploadInput,
+  BlobByteRange,
+  BlobInfo,
+  BlobStorage,
+  BlobUploadSession,
+  CompleteBlobUploadInput,
+  CreateBlobUploadInput,
+  FileRef,
+  PutBlobInput,
+  SignBlobUploadPartInput,
+  SignedBlobUploadPart,
+} from "./types"
+import { supportsDirectUpload, supportsRangeRead } from "./validation"
+
+/** Blob operations bound to one execution. Provider lifecycle is deliberately host-only. */
+export interface BlobsRuntime {
+  put(input: PutBlobInput): Promise<FileRef>
+  open(blobId: string): Promise<ReadableStream<Uint8Array>>
+  stat(blobId: string): Promise<BlobInfo | null>
+  openRange?(blobId: string, range: BlobByteRange): Promise<ReadableStream<Uint8Array>>
+  createUpload?(input: CreateBlobUploadInput): Promise<BlobUploadSession>
+  signUploadPart?(input: SignBlobUploadPartInput): Promise<SignedBlobUploadPart>
+  completeUpload?(input: CompleteBlobUploadInput): Promise<FileRef>
+  abortUpload?(input: AbortBlobUploadInput): Promise<void>
+}
+
+export function createBlobsRuntime(
+  runtime: SixbRuntimeContext,
+  execution: ExecutionContext,
+  blobStorage: BlobStorage
+): BlobsRuntime {
+  const assertAccess = () => assertProviderAccess(runtime, execution, "blobs.access")
+  const executionBlobs: BlobsRuntime = {
+    put: (input) => {
+      assertAccess()
+      return blobStorage.put(input)
+    },
+    open: (blobId) => {
+      assertAccess()
+      return blobStorage.open(blobId)
+    },
+    stat: (blobId) => {
+      assertAccess()
+      return blobStorage.stat(blobId)
+    },
+  }
+
+  if (supportsRangeRead(blobStorage)) {
+    executionBlobs.openRange = (blobId, range) => {
+      assertAccess()
+      return blobStorage.openRange(blobId, range)
+    }
+  }
+  if (supportsDirectUpload(blobStorage)) {
+    executionBlobs.createUpload = (input) => {
+      assertAccess()
+      return blobStorage.createUpload(input)
+    }
+    executionBlobs.signUploadPart = (input) => {
+      assertAccess()
+      return blobStorage.signUploadPart(input)
+    }
+    executionBlobs.completeUpload = (input) => {
+      assertAccess()
+      return blobStorage.completeUpload(input)
+    }
+    executionBlobs.abortUpload = (input) => {
+      assertAccess()
+      return blobStorage.abortUpload(input)
+    }
+  }
+
+  return Object.freeze(executionBlobs)
+}

package/src/blob-storage/validation.ts

@@ -1,3 +1,4 @@
+import { isPlainRecord } from "../json"
 import { blobIdFromDigest } from "./derive"
 import type {
   BlobDigest,
@@ -7,22 +8,13 @@ import type {
   RangeReadableBlobStorage,
 } from "./types"
 
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return false
-  }
-
-  const prototype = Object.getPrototypeOf(value)
-  return prototype === Object.prototype || prototype === null
-}
-
 export function isBlobDigest(value: unknown): value is BlobDigest {
   return typeof value === "string" && value.startsWith("sha256:") && value.length > "sha256:".length
 }
 
 export function isFileRef(value: unknown): value is FileRef {
   return (
-    isPlainObject(value) &&
+    isPlainRecord(value) &&
     typeof value.blobId === "string" &&
     value.blobId.trim().length > 0 &&
     isBlobDigest(value.digest) &&

package/src/bootstrap/discovery.ts

@@ -10,30 +10,19 @@ import { readdir } from "node:fs/promises"
 import { join, relative } from "node:path"
 import { pathToFileURL } from "node:url"
 import { isActionDefinition } from "../actions"
-import type { ActionDefinition } from "../actions/types"
-import type { AgentDefinition } from "../agents"
 import { isAgentDefinition } from "../agents"
 import { isConnectorDefinition } from "../connectors"
-import type { ConnectorDefinition } from "../connectors/types"
 import { isDatasetDefinition } from "../datasets"
-import type { DatasetDefinition } from "../datasets/types"
 import type { OntologyDocumentInput, OntologySource } from "../ontology/registry"
 import type { ObjectTypeWithPropertyTokens } from "../ontology/tokens"
 import type { ValueType } from "../ontology/types"
 import { isPipelineDefinition } from "../pipelines"
-import type { PipelineDefinition } from "../pipelines/types"
 import { isProjectionDefinition } from "../projections/builders"
-import type { ProjectionDefinition } from "../projections/types"
 import { isRuleDefinition } from "../rules"
-import type { RuleDefinition } from "../rules/types"
 import { RuntimeError } from "../runtime/errors"
-import type { ScheduleDefinition } from "../schedules"
 import { isScheduleDefinition } from "../schedules"
-import type { GroupDefinition, MembershipPolicyDefinition, RoleDefinition } from "../security"
 import { isGroupDefinition, isMembershipPolicyDefinition, isRoleDefinition } from "../security"
-import type { SyncDefinition } from "../syncs"
 import { isSyncDefinition } from "../syncs"
-import type { WorkflowDefinition } from "../workflows"
 import { isWorkflowDefinition } from "../workflows"
 
 const moduleExtensions = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"])
@@ -82,265 +71,112 @@ export async function discoverOntologySources(
   return discoveredSources
 }
 
-export async function discoverActions(projectRoot: string): Promise<readonly ActionDefinition[]> {
-  const actionsDir = join(projectRoot, "actions")
-  const modulePaths = await listModuleFiles(actionsDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
-    kind: "action",
-  })
-
-  const actions: ActionDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isActionDefinition(candidate)) {
-      actions.push(candidate)
-    }
-  }
-
-  return actions
+type DiscoveryModuleKind =
+  | "action"
+  | "agent"
+  | "connector"
+  | "dataset"
+  | "group"
+  | "membershipPolicy"
+  | "ontology"
+  | "pipeline"
+  | "projection"
+  | "role"
+  | "rule"
+  | "schedule"
+  | "sync"
+  | "workflow"
+
+interface DefinitionDiscoveryFamily<TDefinition> {
+  readonly directory: readonly string[]
+  readonly kind: Exclude<DiscoveryModuleKind, "ontology">
+  readonly isDefinition: (value: unknown) => value is TDefinition
 }
 
-export async function discoverDatasets(projectRoot: string): Promise<readonly DatasetDefinition[]> {
-  const datasetsDir = join(projectRoot, "datasets")
-  const modulePaths = await listModuleFiles(datasetsDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
-    kind: "dataset",
-  })
-
-  const datasets: DatasetDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isDatasetDefinition(candidate)) {
-      datasets.push(candidate)
-    }
-  }
-
-  return datasets
-}
-
-export async function discoverSyncs(projectRoot: string): Promise<readonly SyncDefinition[]> {
-  const syncsDir = join(projectRoot, "syncs")
-  const modulePaths = await listModuleFiles(syncsDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
-    kind: "sync",
-  })
-
-  const syncs: SyncDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isSyncDefinition(candidate)) {
-      syncs.push(candidate)
-    }
-  }
-
-  return syncs
-}
-
-export async function discoverProjections(
-  projectRoot: string
-): Promise<readonly ProjectionDefinition[]> {
-  const projectionsDir = join(projectRoot, "projections")
-  const modulePaths = await listModuleFiles(projectionsDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
+const definitionDiscoveryRegistry = {
+  actions: { directory: ["actions"], kind: "action", isDefinition: isActionDefinition },
+  projections: {
+    directory: ["projections"],
     kind: "projection",
-  })
-
-  const projections: ProjectionDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isProjectionDefinition(candidate)) {
-      projections.push(candidate)
-    }
-  }
-
-  return projections
-}
-
-export async function discoverConnectors(
-  projectRoot: string
-): Promise<readonly ConnectorDefinition[]> {
-  const connectorsDir = join(projectRoot, "connectors")
-  const modulePaths = await listModuleFiles(connectorsDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
-    kind: "connector",
-  })
-
-  const connectors: ConnectorDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isConnectorDefinition(candidate)) {
-      connectors.push(candidate)
-    }
-  }
-
-  return connectors
-}
-
-export async function discoverSchedules(
-  projectRoot: string
-): Promise<readonly ScheduleDefinition[]> {
-  const schedulesDir = join(projectRoot, "schedules")
-  const modulePaths = await listModuleFiles(schedulesDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
+    isDefinition: isProjectionDefinition,
+  },
+  schedules: {
+    directory: ["schedules"],
     kind: "schedule",
-  })
-
-  const schedules: ScheduleDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isScheduleDefinition(candidate)) {
-      schedules.push(candidate)
-    }
-  }
-
-  return schedules
-}
-
-export async function discoverPipelines(
-  projectRoot: string
-): Promise<readonly PipelineDefinition[]> {
-  const pipelinesDir = join(projectRoot, "pipelines")
-  const modulePaths = await listModuleFiles(pipelinesDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
+    isDefinition: isScheduleDefinition,
+  },
+  syncs: { directory: ["syncs"], kind: "sync", isDefinition: isSyncDefinition },
+  connectors: {
+    directory: ["connectors"],
+    kind: "connector",
+    isDefinition: isConnectorDefinition,
+  },
+  pipelines: {
+    directory: ["pipelines"],
     kind: "pipeline",
-  })
-
-  const pipelines: PipelineDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isPipelineDefinition(candidate)) {
-      pipelines.push(candidate)
-    }
-  }
-
-  return pipelines
-}
-
-export async function discoverRules(projectRoot: string): Promise<readonly RuleDefinition[]> {
-  // Rules follow the same convention-based discovery model as syncs and workflows:
-  // any exported rule definition, or arrays containing them, is collected.
-  const rulesDir = join(projectRoot, "rules")
-  const modulePaths = await listModuleFiles(rulesDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
-    kind: "rule",
-  })
-
-  const rules: RuleDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isRuleDefinition(candidate)) {
-      rules.push(candidate)
-    }
-  }
-
-  return rules
-}
-
-export async function discoverGroups(projectRoot: string): Promise<readonly GroupDefinition[]> {
-  const groupsDir = join(projectRoot, "security", "groups")
-  const modulePaths = await listModuleFiles(groupsDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
+    isDefinition: isPipelineDefinition,
+  },
+  datasets: { directory: ["datasets"], kind: "dataset", isDefinition: isDatasetDefinition },
+  rules: { directory: ["rules"], kind: "rule", isDefinition: isRuleDefinition },
+  workflows: {
+    directory: ["workflows"],
+    kind: "workflow",
+    isDefinition: isWorkflowDefinition,
+  },
+  groups: {
+    directory: ["security", "groups"],
     kind: "group",
-  })
-
-  const groups: GroupDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isGroupDefinition(candidate)) {
-      groups.push(candidate)
-    }
-  }
-
-  return groups
-}
-
-export async function discoverRoles(projectRoot: string): Promise<readonly RoleDefinition[]> {
-  const rolesDir = join(projectRoot, "security", "roles")
-  const modulePaths = await listModuleFiles(rolesDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
+    isDefinition: isGroupDefinition,
+  },
+  roles: {
+    directory: ["security", "roles"],
     kind: "role",
-  })
-
-  const roles: RoleDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isRoleDefinition(candidate)) {
-      roles.push(candidate)
-    }
-  }
-
-  return roles
-}
-
-export async function discoverMembershipPolicies(
-  projectRoot: string
-): Promise<readonly MembershipPolicyDefinition[]> {
-  const policiesDir = join(projectRoot, "security", "policies")
-  const modulePaths = await listModuleFiles(policiesDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
+    isDefinition: isRoleDefinition,
+  },
+  membershipPolicies: {
+    directory: ["security", "policies"],
     kind: "membershipPolicy",
-  })
-
-  const membershipPolicies: MembershipPolicyDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isMembershipPolicyDefinition(candidate)) {
-      membershipPolicies.push(candidate)
-    }
-  }
-
-  return membershipPolicies
+    isDefinition: isMembershipPolicyDefinition,
+  },
+  agents: { directory: ["agents"], kind: "agent", isDefinition: isAgentDefinition },
+} as const satisfies Record<string, DefinitionDiscoveryFamily<unknown>>
+
+type DefinitionFromFamily<TFamily> =
+  TFamily extends DefinitionDiscoveryFamily<infer TDefinition> ? TDefinition : never
+
+export type DiscoveredProjectDefinitions = {
+  readonly [TKey in keyof typeof definitionDiscoveryRegistry]: readonly DefinitionFromFamily<
+    (typeof definitionDiscoveryRegistry)[TKey]
+  >[]
 }
 
-export async function discoverWorkflows(
+export async function discoverProjectDefinitions(
   projectRoot: string
-): Promise<readonly WorkflowDefinition[]> {
-  const workflowsDir = join(projectRoot, "workflows")
-  const modulePaths = await listModuleFiles(workflowsDir)
-  const exportedCandidates = await loadModuleExports({
-    modulePaths,
-    projectRoot,
-    kind: "workflow",
-  })
-
-  const workflows: WorkflowDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isWorkflowDefinition(candidate)) {
-      workflows.push(candidate)
-    }
-  }
+): Promise<DiscoveredProjectDefinitions> {
+  const entries = await Promise.all(
+    Object.entries(definitionDiscoveryRegistry).map(async ([key, family]) => {
+      const definitions = await discoverDefinitionFamily(projectRoot, family)
+      return [key, definitions] as const
+    })
+  )
 
-  return workflows
+  // Object.fromEntries erases literal keys. Every entry above comes from the exact registry and its
+  // definitions have passed that entry's type guard, so restoring the mapped result type is safe.
+  return Object.fromEntries(entries) as DiscoveredProjectDefinitions
 }
 
-export async function discoverAgents(projectRoot: string): Promise<readonly AgentDefinition[]> {
-  const agentsDir = join(projectRoot, "agents")
-  const modulePaths = await listModuleFiles(agentsDir)
+async function discoverDefinitionFamily(
+  projectRoot: string,
+  family: DefinitionDiscoveryFamily<unknown>
+): Promise<readonly unknown[]> {
+  const modulePaths = await listModuleFiles(join(projectRoot, ...family.directory))
   const exportedCandidates = await loadModuleExports({
     modulePaths,
     projectRoot,
-    kind: "agent",
+    kind: family.kind,
   })
 
-  const agents: AgentDefinition[] = []
-  for (const candidate of exportedCandidates) {
-    if (isAgentDefinition(candidate)) {
-      agents.push(candidate)
-    }
-  }
-
-  return agents
+  return exportedCandidates.filter(family.isDefinition)
 }
 
 // ── Internal helpers ────────────────────────────────────────
@@ -348,23 +184,7 @@ export async function discoverAgents(projectRoot: string): Promise<readonly Agen
 async function loadModuleExports(options: {
   modulePaths: readonly string[]
   projectRoot: string
-  kind:
-    | "action"
-    | "agent"
-    | "ontology"
-    | "dataset"
-    | "function"
-    | "connector"
-    | "sync"
-    | "projection"
-    | "schedule"
-    | "pipeline"
-    | "rule"
-    | "trigger"
-    | "group"
-    | "role"
-    | "membershipPolicy"
-    | "workflow"
+  kind: DiscoveryModuleKind
 }): Promise<unknown[]> {
   const exportedCandidates: unknown[] = []
   const seen = new Set<unknown>()

package/src/bootstrap/index.ts

@@ -1,18 +1,7 @@
+export type { DiscoveredProjectDefinitions } from "./discovery"
 export {
-  discoverActions,
-  discoverAgents,
-  discoverConnectors,
-  discoverDatasets,
-  discoverGroups,
-  discoverMembershipPolicies,
   discoverOntologySources,
-  discoverPipelines,
-  discoverProjections,
-  discoverRoles,
-  discoverRules,
-  discoverSchedules,
-  discoverSyncs,
-  discoverWorkflows,
+  discoverProjectDefinitions,
 } from "./discovery"
 export type {
   GenerateOntologyTypeManifestOptions,

package/src/broker/in-memory.ts

@@ -180,6 +180,14 @@ export class InMemoryBroker implements Broker {
     assertCursor(params.afterCursor)
     const storedStream = this.getEnsuredStream(params.projectId, params.streamId)
 
+    // Retention may have trimmed past the caller's cursor. Reject that here rather than let
+    // `readForward` skip silently to the oldest retained record: a resuming subscriber would be
+    // fast-forwarded over the gap and would believe it had seen everything. `read` and `tail`
+    // already reject it, and so does the Redis provider, so this keeps the three consistent.
+    // Checked before the subscription is registered so a throw cannot leave one behind.
+    this.applyRetention(storedStream)
+    this.assertCursorInRetainedRange(storedStream, params.afterCursor)
+
     const subscription: Subscription = {
       projectId: params.projectId,
       streamId: params.streamId,
@@ -191,7 +199,6 @@ export class InMemoryBroker implements Broker {
 
     const startMode = params.afterCursor !== undefined ? undefined : (params.from ?? "latest")
     if (params.afterCursor !== undefined || startMode === "earliest") {
-      this.applyRetention(storedStream)
       const initial = this.readForward(storedStream.records, {
         afterCursor: params.afterCursor,
         names: params.names,

package/src/broker/types.ts

@@ -97,6 +97,11 @@ export interface Broker {
   /**
    * Subscribes to retained/live records. Defaults to `from: "latest"` unless
    * `afterCursor` is provided.
+   *
+   * Like `read`, providers must reject an `afterCursor` older than the retained
+   * range rather than silently advancing to the first retained record, so a
+   * resuming subscriber learns the gap exists instead of mistaking a truncated
+   * stream for a complete one.
    */
   subscribe(
     params: {

package/src/connectors/builders.ts

@@ -1,5 +1,11 @@
-import { ConnectorError } from "./errors"
-import type { ConnectorAdapter, ConnectorDefinition } from "./types"
+import { ConnectorError, createConnectorCodedError } from "./errors"
+import type {
+  AnyConnectorAdapter,
+  ConnectorAdapter,
+  ConnectorDefinition,
+  OAuthConnectorAdapter,
+} from "./types"
+import { isOAuthConnectorAdapter } from "./types"
 
 function assertNonEmpty(value: string, field: string): void {
   if (!value.trim()) {
@@ -14,9 +20,17 @@ function assertNonEmpty(value: string, field: string): void {
  * `connectors/` module. Use `await sixb.connector(definition)` at runtime to
  * resolve it to a connected client.
  */
+export function defineConnector<TId extends string, TAdapter extends OAuthConnectorAdapter>(
+  id: TId,
+  adapter: TAdapter
+): ConnectorDefinition<TId, TAdapter>
 export function defineConnector<TId extends string, TAdapter extends ConnectorAdapter>(
   id: TId,
   adapter: TAdapter
+): ConnectorDefinition<TId, TAdapter>
+export function defineConnector<TId extends string, TAdapter extends AnyConnectorAdapter>(
+  id: TId,
+  adapter: TAdapter
 ): ConnectorDefinition<TId, TAdapter> {
   assertNonEmpty(id, "id")
   assertNonEmpty(adapter.type, "type")
@@ -25,6 +39,27 @@ export function defineConnector<TId extends string, TAdapter extends ConnectorAd
     throw new ConnectorError("Connector adapter connect must be a function.")
   }
 
+  if (adapter.authentication !== undefined) {
+    if (
+      !isOAuthConnectorAdapter(adapter) ||
+      typeof adapter.authentication.authorizationUrl !== "function" ||
+      typeof adapter.authentication.exchangeCode !== "function" ||
+      typeof adapter.authentication.refresh !== "function" ||
+      typeof adapter.discoverAccounts !== "function"
+    ) {
+      throw createConnectorCodedError(
+        "connector.configuration_invalid",
+        "OAuth connector adapters must define oauth2 authentication and implement authorizationUrl, exchangeCode, refresh, and discoverAccounts."
+      )
+    }
+    if (adapter.webhooks !== undefined) {
+      throw createConnectorCodedError(
+        "connector.configuration_invalid",
+        "OAuth connector adapters cannot register webhooks until connection routing is defined."
+      )
+    }
+  }
+
   return {
     kind: "connector",
     id,