@sixb/core 0.0.1

package/src/storage/ontology/sources.ts

@@ -0,0 +1,195 @@
+import type {
+  PinnedDatasetVersion,
+  ProjectionEntityRef,
+  ProjectionExecution,
+  ProjectionSourceAssertion,
+  ProjectionSourceRef,
+} from "../../materialization/model"
+
+export type OntologySourceMaterializationStatus =
+  | "staging"
+  | "ready"
+  | "active"
+  | "superseded"
+  | "abandoned"
+
+/**
+ * One explicit, durable materialization of a projection source.
+ *
+ * Staging/ready records retain their execution token so every write can be fenced. Active and
+ * terminal records clear it: queue execution ownership is transient and is not source authority.
+ */
+export interface OntologySourceRecord {
+  readonly projectId: string
+  readonly source: ProjectionSourceRef
+  readonly materializationId: string
+  readonly projectionRunId: string
+  readonly projectionKind: "object" | "link"
+  readonly protocol: "replacement"
+  readonly status: OntologySourceMaterializationStatus
+  readonly executionToken: string | null
+  readonly datasetVersion: PinnedDatasetVersion
+  readonly projectionRevision: string
+  readonly ownershipHash: string
+  readonly ontologyRevision: string
+  /** Null until staging is sealed by markReady; zero explicitly represents an empty output. */
+  readonly rootCount: number | null
+  /** Null until staging is sealed by markReady; zero explicitly represents an empty output. */
+  readonly assertionCount: number | null
+  readonly createdAt: string
+  readonly readyAt: string | null
+  readonly activatedAt: string | null
+  readonly terminalAt: string | null
+  readonly lastCommitId: string | null
+  readonly updatedAt: string
+}
+
+export interface StoredSourceObjectAssertion {
+  readonly source: ProjectionSourceRef
+  readonly materializationId: string
+  readonly root: ProjectionEntityRef
+  readonly assertion: Extract<ProjectionSourceAssertion, { readonly kind: "object" }>
+  readonly stagingOrdinal: number
+}
+
+export interface StoredSourceLinkAssertion {
+  readonly source: ProjectionSourceRef
+  readonly materializationId: string
+  readonly root: ProjectionEntityRef
+  readonly assertion: Extract<ProjectionSourceAssertion, { readonly kind: "link" }>
+  readonly stagingOrdinal: number
+}
+
+export type StoredSourceAssertion = StoredSourceObjectAssertion | StoredSourceLinkAssertion
+
+export interface GetActiveOntologySourceInput {
+  readonly projectId: string
+  readonly source: ProjectionSourceRef
+}
+
+export interface BeginSourceMaterializationInput {
+  readonly projectId: string
+  readonly source: ProjectionSourceRef
+  readonly materializationId: string
+  readonly execution: ProjectionExecution
+  readonly projectionKind: "object" | "link"
+  readonly protocol: "replacement"
+  readonly datasetVersion: PinnedDatasetVersion
+  readonly projectionRevision: string
+  readonly ownershipHash: string
+  readonly ontologyRevision: string
+  readonly createdAt: string
+}
+
+/** One normalized assertion staged under an existing source materialization manifest. */
+export interface StageSourceAssertion {
+  readonly root: ProjectionEntityRef
+  readonly assertion: ProjectionSourceAssertion
+  readonly stagingOrdinal: number
+}
+
+export interface StageSourceRowsInput {
+  readonly projectId: string
+  readonly source: ProjectionSourceRef
+  readonly materializationId: string
+  readonly execution: ProjectionExecution
+  readonly rows: readonly StageSourceAssertion[]
+}
+
+export interface StageSourceRowsResult {
+  readonly inserted: number
+  readonly unchanged: number
+}
+
+export interface MarkSourceMaterializationReadyInput {
+  readonly projectId: string
+  readonly source: ProjectionSourceRef
+  readonly materializationId: string
+  readonly execution: ProjectionExecution
+  readonly rootCount: number
+  readonly assertionCount: number
+  readonly readyAt: string
+}
+
+interface BaseAbandonSourceMaterializationInput {
+  readonly projectId: string
+  readonly source: ProjectionSourceRef
+  readonly execution: ProjectionExecution
+  readonly abandonedAt: string
+}
+
+/** Abandon the current execution's exact candidate after ingress or semantic failure. */
+export interface AbandonSourceMaterializationCandidateInput
+  extends BaseAbandonSourceMaterializationInput {
+  readonly kind: "candidate"
+  readonly materializationId: string
+}
+
+/**
+ * Reclaim a logical run after redelivery. The current execution may abandon the prior execution's
+ * staging/ready candidate, but never one already owned by its own token.
+ */
+export interface ReclaimSourceMaterializationInput extends BaseAbandonSourceMaterializationInput {
+  readonly kind: "reclaim"
+}
+
+export type AbandonSourceMaterializationInput =
+  | AbandonSourceMaterializationCandidateInput
+  | ReclaimSourceMaterializationInput
+
+export interface CleanupTerminalSourceMaterializationsInput {
+  readonly projectId: string
+  /** Exclusive cutoff applied only to superseded/abandoned terminalAt. */
+  readonly terminalBefore: string
+  /** Maximum total child-row plus manifest deletions performed by one call. */
+  readonly limit: number
+}
+
+export interface CleanupTerminalSourceMaterializationsResult {
+  readonly rowsDeleted: number
+  readonly materializationsDeleted: number
+}
+
+export interface SummarizeTerminalSourceMaterializationsInput {
+  readonly projectId: string
+}
+
+export interface TerminalSourceMaterializationSummary {
+  readonly count: number
+  readonly oldestTerminalAt: string | null
+}
+
+export interface AssertSourceMaterializationExecutionInput {
+  readonly projectId: string
+  readonly source: ProjectionSourceRef
+  readonly execution: ProjectionExecution
+  /** Full immutable source identity, required when a candidate manifest is first created. */
+  readonly identity?: Pick<
+    BeginSourceMaterializationInput,
+    | "projectionKind"
+    | "protocol"
+    | "datasetVersion"
+    | "projectionRevision"
+    | "ownershipHash"
+    | "ontologyRevision"
+  >
+}
+
+export type AssertSourceMaterializationExecution = (
+  input: AssertSourceMaterializationExecutionInput
+) => Promise<void> | void
+
+export interface OntologySourceStorage {
+  beginMaterialization(input: BeginSourceMaterializationInput): Promise<OntologySourceRecord>
+  stageRows(input: StageSourceRowsInput): Promise<StageSourceRowsResult>
+  markReady(input: MarkSourceMaterializationReadyInput): Promise<OntologySourceRecord>
+  getActive(input: GetActiveOntologySourceInput): Promise<OntologySourceRecord | null>
+  abandon(input: AbandonSourceMaterializationCandidateInput): Promise<OntologySourceRecord>
+  abandon(input: ReclaimSourceMaterializationInput): Promise<OntologySourceRecord | null>
+  cleanupTerminal(
+    input: CleanupTerminalSourceMaterializationsInput
+  ): Promise<CleanupTerminalSourceMaterializationsResult>
+  summarizeTerminal(
+    input: SummarizeTerminalSourceMaterializationsInput
+  ): Promise<TerminalSourceMaterializationSummary>
+}

package/src/storage/operation-scope.ts

@@ -0,0 +1,248 @@
+import { AsyncLocalStorage } from "node:async_hooks"
+import type { AgentStorage } from "./agents"
+import type { AuthStorage } from "./auth"
+import type { OntologyStorage } from "./ontology"
+import type { WorkflowRunStorage } from "./workflow-runs"
+
+export type StorageOperationRunner = <TResult>(
+  run: () => Promise<TResult> | TResult
+) => Promise<TResult>
+
+/** Provider-owned execution boundary for root storage operations. */
+export interface StorageOperationScope {
+  assertAvailable(): void
+  run<TResult>(operation: () => Promise<TResult> | TResult): Promise<TResult>
+}
+
+export function createStorageOperationScope(
+  run: StorageOperationRunner,
+  assertAvailable: () => void = () => undefined
+): StorageOperationScope {
+  const executions = new AsyncLocalStorage<{ active: boolean }>()
+  return {
+    assertAvailable,
+    async run(operation) {
+      const inherited = executions.getStore()
+      if (inherited?.active) {
+        assertAvailable()
+        return operation()
+      }
+
+      const execution = { active: true }
+      try {
+        return await executions.run(execution, () => run(operation))
+      } finally {
+        execution.active = false
+      }
+    },
+  }
+}
+
+const operationScopeTargets = new WeakMap<object, object>()
+
+/**
+ * Give every async operation exposed by a store one provider-owned execution scope.
+ *
+ * Storage contracts use `async` methods for I/O and reserve synchronous methods for local
+ * capabilities such as `queryCapabilities()`. Discovering the former from their implementation
+ * removes the second, manually synchronized method registry that previously coupled every storage
+ * primitive to the SQLite/InMemory lock.
+ */
+export function createOperationScopedFacade<T extends object>(
+  target: T,
+  scope: StorageOperationScope,
+  propertyOverrides: Partial<T> = {}
+): T {
+  const methodKinds = discoverMethodKinds(target)
+  const overrideKeys = new Set(Reflect.ownKeys(propertyOverrides))
+  const methodCache = new Map<
+    PropertyKey,
+    { implementation: (...args: unknown[]) => unknown; exposed: (...args: unknown[]) => unknown }
+  >()
+
+  const facade = new Proxy(target, {
+    get(current, property) {
+      if (overrideKeys.has(property)) {
+        return Reflect.get(propertyOverrides, property, propertyOverrides)
+      }
+
+      const value = Reflect.get(current, property, current)
+      const kind = methodKinds.get(property)
+      if (!kind || typeof value !== "function") return value
+      const implementation = value as (...args: unknown[]) => unknown
+
+      const cached = methodCache.get(property)
+      if (cached?.implementation === implementation) return cached.exposed
+
+      const exposed = scopeMethod(implementation, kind, current, scope)
+      methodCache.set(property, { implementation, exposed })
+      return exposed
+    },
+    set(current, property, value) {
+      if (overrideKeys.has(property)) return false
+      return Reflect.set(current, property, value, current)
+    },
+    defineProperty(current, property, attributes) {
+      if (overrideKeys.has(property)) return false
+      return Reflect.defineProperty(current, property, attributes)
+    },
+    deleteProperty(current, property) {
+      if (overrideKeys.has(property)) return false
+      return Reflect.deleteProperty(current, property)
+    },
+  })
+  operationScopeTargets.set(facade, target)
+  return facade
+}
+
+type StorageMethod = (...args: never[]) => unknown
+type StorageMethodKey<T> = {
+  [TKey in keyof T]-?: T[TKey] extends StorageMethod ? TKey : never
+}[keyof T]
+
+/** Replace a provider method behind its scoped facade without exposing the raw provider. */
+export function decorateOperationScopedMethodForTesting<
+  T extends object,
+  TKey extends StorageMethodKey<T>,
+>(
+  facade: T,
+  property: TKey,
+  decorate: (implementation: Extract<T[TKey], StorageMethod>) => Extract<T[TKey], StorageMethod>
+): () => void {
+  const target = operationScopeTargets.get(facade)
+  if (!target) throw new Error("[Sixb] Expected an operation-scoped storage facade.")
+
+  const previousDescriptor = Reflect.getOwnPropertyDescriptor(target, property)
+  const implementation = Reflect.get(target, property, target)
+  if (typeof implementation !== "function") {
+    throw new Error(`[Sixb] Storage property '${String(property)}' is not a method.`)
+  }
+
+  const boundImplementation = ((...args: never[]) =>
+    Reflect.apply(implementation, target, args)) as Extract<T[TKey], StorageMethod>
+  const decorated = decorate(boundImplementation)
+  Reflect.defineProperty(target, property, {
+    configurable: true,
+    enumerable: previousDescriptor?.enumerable ?? false,
+    writable: true,
+    value: decorated,
+  })
+
+  return () => {
+    if (previousDescriptor) {
+      Reflect.defineProperty(target, property, previousDescriptor)
+    } else {
+      Reflect.deleteProperty(target, property)
+    }
+  }
+}
+
+type StorageMethodKind = "async" | "async-generator" | "sync"
+
+function discoverMethodKinds(target: object): ReadonlyMap<PropertyKey, StorageMethodKind> {
+  const methodKeys = new Set<PropertyKey>()
+  for (
+    let current: object | null = target;
+    current && current !== Object.prototype;
+    current = Object.getPrototypeOf(current)
+  ) {
+    for (const property of Reflect.ownKeys(current)) {
+      if (property !== "constructor") methodKeys.add(property)
+    }
+  }
+
+  const methodKinds = new Map<PropertyKey, StorageMethodKind>()
+  for (const property of methodKeys) {
+    const implementation = Reflect.get(target, property, target)
+    if (typeof implementation !== "function") continue
+    methodKinds.set(property, methodKind(implementation))
+  }
+  return methodKinds
+}
+
+function methodKind(implementation: (...args: unknown[]) => unknown): StorageMethodKind {
+  if (isAsyncFunction(implementation)) return "async"
+  if (isAsyncGeneratorFunction(implementation)) return "async-generator"
+  return "sync"
+}
+
+function scopeMethod(
+  implementation: (...args: unknown[]) => unknown,
+  kind: StorageMethodKind,
+  target: object,
+  scope: StorageOperationScope
+): (...args: unknown[]) => unknown {
+  if (kind === "async") {
+    return (...args: unknown[]) => scope.run(() => Reflect.apply(implementation, target, args))
+  }
+
+  if (kind === "async-generator") {
+    return (...args: unknown[]) => {
+      scope.assertAvailable()
+      return Reflect.apply(implementation, target, args)
+    }
+  }
+
+  return implementation.bind(target)
+}
+
+export function createAuthOperationScope<T extends AuthStorage>(
+  target: T,
+  scope: StorageOperationScope
+): T {
+  return createOperationScopedFacade<AuthStorage>(target, scope, {
+    users: createOperationScopedFacade(target.users, scope),
+    identities: createOperationScopedFacade(target.identities, scope),
+    serviceAccounts: createOperationScopedFacade(target.serviceAccounts, scope),
+    serviceAccountGroupMemberships: createOperationScopedFacade(
+      target.serviceAccountGroupMemberships,
+      scope
+    ),
+    sessions: createOperationScopedFacade(target.sessions, scope),
+    accessTokens: createOperationScopedFacade(target.accessTokens, scope),
+    invitations: createOperationScopedFacade(target.invitations, scope),
+    groupMemberships: createOperationScopedFacade(target.groupMemberships, scope),
+    magicLinks: createOperationScopedFacade(target.magicLinks, scope),
+    oidcAuthorizationAttempts: createOperationScopedFacade(target.oidcAuthorizationAttempts, scope),
+  }) as T
+}
+
+export function createAgentOperationScope<T extends AgentStorage>(
+  target: T,
+  scope: StorageOperationScope
+): T {
+  return createOperationScopedFacade<AgentStorage>(target, scope, {
+    threads: createOperationScopedFacade(target.threads, scope),
+    runs: createOperationScopedFacade(target.runs, scope),
+    messages: createOperationScopedFacade(target.messages, scope),
+  }) as T
+}
+
+export function createOntologyOperationScope<T extends OntologyStorage>(
+  target: T,
+  scope: StorageOperationScope
+): T {
+  return createOperationScopedFacade<OntologyStorage>(target, scope, {
+    commits: createOperationScopedFacade(target.commits, scope),
+    sources: createOperationScopedFacade(target.sources, scope),
+    materializations: createOperationScopedFacade(target.materializations, scope),
+    outbox: createOperationScopedFacade(target.outbox, scope),
+  }) as T
+}
+
+export function createWorkflowRunOperationScope<T extends WorkflowRunStorage>(
+  target: T,
+  scope: StorageOperationScope
+): T {
+  return createOperationScopedFacade<WorkflowRunStorage>(target, scope, {
+    nodes: createOperationScopedFacade(target.nodes, scope),
+  }) as T
+}
+
+function isAsyncFunction(value: unknown): value is (...args: unknown[]) => Promise<unknown> {
+  return typeof value === "function" && value.constructor.name === "AsyncFunction"
+}
+
+function isAsyncGeneratorFunction(value: unknown): boolean {
+  return typeof value === "function" && value.constructor.name === "AsyncGeneratorFunction"
+}

package/src/storage/pagination.ts

@@ -0,0 +1,23 @@
+export interface ListWindow {
+  readonly limit?: number
+  readonly offset?: number
+}
+
+export interface ListPage<T> {
+  readonly page: readonly T[]
+  readonly total: number
+  readonly hasMore: boolean
+}
+
+export function paginate<T>(values: readonly T[], input: ListWindow): ListPage<T> {
+  const offset = input.offset ?? 0
+  const limit = input.limit ?? values.length
+  const total = values.length
+  const page = values.slice(offset, offset + limit)
+
+  return {
+    page,
+    total,
+    hasMore: offset + page.length < total,
+  }
+}

package/src/storage/pipeline-runs/errors.ts

@@ -0,0 +1,6 @@
+/**
+ * Base error for pipeline-run storage operations.
+ */
+export class PipelineRunError extends Error {
+  readonly name = "PipelineRunError"
+}