@sixb/core 0.0.1

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

@@ -0,0 +1,181 @@
+import { cloneJsonValue, type JsonValue } from "../../json"
+import {
+  compareStartedAt,
+  hasEmptyStatuses,
+  latestStartedAtByOwnerId,
+  matchesRunListDateFilters,
+  paginate,
+  toStatusSet,
+} from "../run-listing"
+import { SyncRunError } from "./errors"
+import type {
+  FinishSyncRunInput,
+  ListLatestSyncRunsInput,
+  ListLatestSyncRunsResult,
+  ListSyncRunsInput,
+  ListSyncRunsResult,
+  StartSyncRunInput,
+  SyncRunFailure,
+  SyncRunRecord,
+  SyncRunStorage,
+} from "./types"
+
+function syncRunKey(projectId: string, id: string): string {
+  return `${projectId}:${id}`
+}
+
+function cloneSyncRunRecord(record: SyncRunRecord): SyncRunRecord {
+  return structuredClone(record)
+}
+
+function normalizeCheckpoint(checkpoint: JsonValue | undefined): JsonValue | undefined {
+  return checkpoint !== undefined ? cloneJsonValue(checkpoint) : undefined
+}
+
+function normalizeError(error: SyncRunFailure | undefined): SyncRunFailure | undefined {
+  return error ? structuredClone(error) : undefined
+}
+
+export class InMemorySyncRunStorage implements SyncRunStorage {
+  private readonly rows = new Map<string, SyncRunRecord>()
+
+  snapshot(): InMemorySyncRunStorageSnapshot {
+    return structuredClone(this.rows)
+  }
+
+  restore(snapshot: InMemorySyncRunStorageSnapshot): void {
+    this.rows.clear()
+    for (const [key, record] of structuredClone(snapshot)) {
+      this.rows.set(key, record)
+    }
+  }
+
+  async start(input: StartSyncRunInput): Promise<SyncRunRecord> {
+    const key = syncRunKey(input.projectId, input.id)
+    if (this.rows.has(key)) {
+      throw new SyncRunError(
+        `[Sixb] Sync run '${input.id}' already exists for project '${input.projectId}'.`
+      )
+    }
+
+    const record: SyncRunRecord = {
+      id: input.id,
+      projectId: input.projectId,
+      syncId: input.syncId,
+      datasetId: input.datasetId,
+      mode: input.mode,
+      status: "running",
+      startedAt: new Date(input.startedAt ?? new Date()),
+      expectedLatestVersionId: input.expectedLatestVersionId,
+      commitMessage: input.commitMessage,
+    }
+
+    this.rows.set(key, structuredClone(record))
+    return cloneSyncRunRecord(record)
+  }
+
+  async finish(input: FinishSyncRunInput): Promise<SyncRunRecord> {
+    const key = syncRunKey(input.projectId, input.id)
+    const existing = this.rows.get(key)
+
+    if (!existing) {
+      throw new SyncRunError(
+        `[Sixb] Sync run '${input.id}' not found for project '${input.projectId}'.`
+      )
+    }
+
+    if (input.status === "succeeded") {
+      if (input.output && input.output.datasetId !== existing.datasetId) {
+        throw new SyncRunError(
+          `[Sixb] Sync run '${input.id}' output dataset '${input.output.datasetId}' does not match '${existing.datasetId}'.`
+        )
+      }
+      if (!input.output && (existing.mode !== "append" || input.rowsRead !== 0)) {
+        throw new SyncRunError(
+          `[Sixb] Sync run '${input.id}' may omit its output only for an empty append.`
+        )
+      }
+    }
+
+    const base: SyncRunRecord = {
+      ...existing,
+      status: input.status,
+      finishedAt: new Date(input.finishedAt ?? new Date()),
+    }
+
+    const next: SyncRunRecord =
+      input.status === "succeeded"
+        ? {
+            ...base,
+            rowsRead: input.rowsRead,
+            output: input.output ? structuredClone(input.output) : undefined,
+            error: undefined,
+            checkpoint: normalizeCheckpoint(input.checkpoint),
+          }
+        : {
+            ...base,
+            rowsRead: input.rowsRead ?? existing.rowsRead,
+            output: undefined,
+            error: normalizeError(input.error),
+            checkpoint: undefined,
+          }
+
+    this.rows.set(key, structuredClone(next))
+    return cloneSyncRunRecord(next)
+  }
+
+  async getById(params: { projectId: string; id: string }): Promise<SyncRunRecord | null> {
+    const record = this.rows.get(syncRunKey(params.projectId, params.id))
+    return record ? cloneSyncRunRecord(record) : null
+  }
+
+  async list(input: ListSyncRunsInput): Promise<ListSyncRunsResult> {
+    if (hasEmptyStatuses(input) || input.syncIds?.length === 0) {
+      return {
+        runs: [],
+        hasMore: false,
+        total: 0,
+      }
+    }
+
+    const order = input.order ?? "desc"
+    const statuses = toStatusSet(input.statuses)
+    const syncIds = input.syncIds ? new Set(input.syncIds) : null
+
+    const filtered = [...this.rows.values()]
+      .filter((record) => record.projectId === input.projectId)
+      .filter((record) => (input.syncId ? record.syncId === input.syncId : true))
+      .filter((record) => (syncIds ? syncIds.has(record.syncId) : true))
+      .filter((record) => (input.datasetId ? record.datasetId === input.datasetId : true))
+      .filter((record) =>
+        matchesRunListDateFilters(record, {
+          statuses,
+          startedAfter: input.startedAfter,
+          startedBefore: input.startedBefore,
+        })
+      )
+      .sort((left, right) => compareStartedAt(left, right, order))
+
+    const { page, total, hasMore } = paginate(filtered, input)
+
+    return {
+      runs: page.map(cloneSyncRunRecord),
+      hasMore,
+      total,
+    }
+  }
+
+  async listLatestBySyncIds(input: ListLatestSyncRunsInput): Promise<ListLatestSyncRunsResult> {
+    const runs = latestStartedAtByOwnerId(
+      [...this.rows.values()].filter((record) => record.projectId === input.projectId),
+      input.syncIds,
+      (record) => record.syncId
+    )
+
+    return {
+      runs: runs.map(cloneSyncRunRecord),
+    }
+  }
+}
+
+export type InMemorySyncRunStorageSnapshot = Map<string, SyncRunRecord>

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

@@ -0,0 +1,14 @@
+export { SyncRunError } from "./errors"
+export { InMemorySyncRunStorage } from "./in-memory"
+export type {
+  FinishSyncRunInput,
+  ListLatestSyncRunsInput,
+  ListLatestSyncRunsResult,
+  ListSyncRunsInput,
+  ListSyncRunsResult,
+  StartSyncRunInput,
+  SyncRunFailure,
+  SyncRunRecord,
+  SyncRunStatus,
+  SyncRunStorage,
+} from "./types"

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

@@ -0,0 +1,93 @@
+import type { JsonValue } from "../../json"
+import type { DatasetVersionRef, DatasetWriteMode } from "../../lake-storage"
+
+export type SyncRunStatus = "running" | "succeeded" | "failed" | "cancelled"
+
+export interface SyncRunFailure {
+  readonly name?: string // Example: "AbortError"
+  readonly message: string // Example: "Sync cancelled by request"
+}
+
+export interface SyncRunRecord {
+  readonly id: string
+  readonly projectId: string
+  readonly syncId: string
+  readonly datasetId: string
+  readonly mode: DatasetWriteMode
+  readonly status: SyncRunStatus
+  readonly startedAt: Date
+  readonly finishedAt?: Date
+  readonly rowsRead?: number // Rows produced by this run, not the dataset's full visible row count.
+  readonly output?: DatasetVersionRef
+  readonly expectedLatestVersionId?: string
+  readonly commitMessage?: string
+  readonly error?: SyncRunFailure
+  readonly checkpoint?: JsonValue
+}
+
+export interface StartSyncRunInput {
+  readonly id: string
+  readonly projectId: string
+  readonly syncId: string
+  readonly datasetId: string
+  readonly mode: DatasetWriteMode
+  readonly startedAt?: Date
+  readonly expectedLatestVersionId?: string
+  readonly commitMessage?: string
+}
+
+export type FinishSyncRunInput =
+  | {
+      readonly id: string
+      readonly projectId: string
+      readonly status: "succeeded"
+      readonly finishedAt?: Date
+      readonly rowsRead: number
+      /** Absent only when the first append run succeeds without producing any rows. */
+      readonly output?: DatasetVersionRef
+      readonly checkpoint?: JsonValue
+    }
+  | {
+      readonly id: string
+      readonly projectId: string
+      readonly status: "failed" | "cancelled"
+      readonly finishedAt?: Date
+      readonly rowsRead?: number
+      readonly error?: SyncRunFailure
+    }
+
+export interface ListSyncRunsInput {
+  readonly projectId: string
+  readonly syncId?: string
+  readonly syncIds?: readonly string[]
+  readonly datasetId?: string
+  readonly statuses?: readonly SyncRunStatus[]
+  readonly startedAfter?: Date
+  readonly startedBefore?: Date
+  readonly limit?: number
+  readonly offset?: number
+  readonly order?: "asc" | "desc"
+}
+
+export interface ListSyncRunsResult {
+  readonly runs: readonly SyncRunRecord[]
+  readonly hasMore: boolean
+  readonly total: number
+}
+
+export interface ListLatestSyncRunsInput {
+  readonly projectId: string
+  readonly syncIds: readonly string[]
+}
+
+export interface ListLatestSyncRunsResult {
+  readonly runs: readonly SyncRunRecord[]
+}
+
+export interface SyncRunStorage {
+  start(input: StartSyncRunInput): Promise<SyncRunRecord>
+  finish(input: FinishSyncRunInput): Promise<SyncRunRecord>
+  getById(params: { projectId: string; id: string }): Promise<SyncRunRecord | null>
+  list(input: ListSyncRunsInput): Promise<ListSyncRunsResult>
+  listLatestBySyncIds(input: ListLatestSyncRunsInput): Promise<ListLatestSyncRunsResult>
+}

package/src/storage/timeseries/index.ts

@@ -0,0 +1,7 @@
+export type {
+  TimeseriesHistoryBatchInput,
+  TimeseriesHistoryBatchResult,
+  TimeseriesHistorySeriesInput,
+  TimeseriesPoint,
+  TimeseriesStorage,
+} from "./types"

package/src/storage/timeseries/store.ts

@@ -0,0 +1,214 @@
+import type { TelemetrySeriesRef } from "../../materialization/model"
+import type { StoredTelemetryPoint } from "../ontology/materializations"
+import type { TimeseriesHistoryBatchInput, TimeseriesPoint, TimeseriesStorage } from "./types"
+
+function pointKey(
+  projectId: string,
+  objectTypeId: string,
+  objectId: string,
+  propertyId: string
+): string {
+  return JSON.stringify([projectId, objectTypeId, objectId, propertyId])
+}
+
+export class InMemoryTimeseriesStorage implements TimeseriesStorage {
+  // A telemetry point is uniquely identified by (series, at): one value per
+  // instant per series. Re-applying the same instant is a last-write-wins
+  // upsert, which makes telemetry writes idempotent under replay for free.
+  private readonly pointsByKey = new Map<string, Map<number, TimeseriesPoint>>()
+
+  constructor() {
+    materializerAdapters.set(this, {
+      getExactPoint: (projectId, series, at) => this.getExactPoint(projectId, series, at),
+      listLatestForObject: (projectId, objectTypeId, objectId) =>
+        this.listLatestForObject(projectId, objectTypeId, objectId),
+      applyExactPoint: (projectId, point) => this.applyExactPoint(projectId, point),
+    })
+  }
+
+  snapshot(): InMemoryTimeseriesStorageSnapshot {
+    return {
+      pointsByKey: structuredClone(this.pointsByKey),
+    }
+  }
+
+  restore(snapshot: InMemoryTimeseriesStorageSnapshot): void {
+    this.pointsByKey.clear()
+    for (const [key, points] of structuredClone(snapshot.pointsByKey)) {
+      this.pointsByKey.set(key, points)
+    }
+  }
+
+  private getExactPoint(
+    projectId: string,
+    series: TelemetrySeriesRef,
+    at: string
+  ): TimeseriesPoint | null {
+    const point =
+      this.pointsByKey
+        .get(
+          pointKey(
+            projectId,
+            series.object.objectTypeId,
+            series.object.primaryId,
+            series.propertyId
+          )
+        )
+        ?.get(new Date(at).getTime()) ?? null
+    return point ? clonePoint(point) : null
+  }
+
+  private listLatestForObject(
+    projectId: string,
+    objectTypeId: string,
+    objectId: string
+  ): TimeseriesPoint[] {
+    const latest: TimeseriesPoint[] = []
+    for (const series of this.pointsByKey.values()) {
+      let point: TimeseriesPoint | null = null
+      for (const candidate of series.values()) {
+        if (
+          candidate.projectId !== projectId ||
+          candidate.objectTypeId !== objectTypeId ||
+          candidate.objectId !== objectId
+        ) {
+          continue
+        }
+        if (!point || candidate.at > point.at) point = candidate
+      }
+      if (point) latest.push(clonePoint(point))
+    }
+    return latest
+  }
+
+  private applyExactPoint(projectId: string, point: StoredTelemetryPoint): void {
+    const key = pointKey(
+      projectId,
+      point.series.object.objectTypeId,
+      point.series.object.primaryId,
+      point.series.propertyId
+    )
+    const series = this.pointsByKey.get(key) ?? new Map<number, TimeseriesPoint>()
+    series.set(new Date(point.at).getTime(), {
+      projectId,
+      objectTypeId: point.series.object.objectTypeId,
+      objectId: point.series.object.primaryId,
+      propertyId: point.series.propertyId,
+      value: structuredClone(point.value),
+      ...(point.unit !== undefined ? { unit: point.unit } : {}),
+      at: new Date(point.at),
+      lastCommitId: point.lastCommitId,
+    })
+    this.pointsByKey.set(key, series)
+  }
+
+  async getHistory(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    propertyId: string
+    from?: Date
+    to?: Date
+    limit?: number
+    order?: "asc" | "desc"
+  }): Promise<readonly TimeseriesPoint[]> {
+    const key = pointKey(params.projectId, params.objectTypeId, params.objectId, params.propertyId)
+    const { from, to } = params
+    let points = [...(this.pointsByKey.get(key)?.values() ?? [])]
+    if (from || to) {
+      points = points.filter((point) => (!from || point.at >= from) && (!to || point.at <= to))
+    }
+
+    points.sort((a, b) => a.at.getTime() - b.at.getTime())
+    if (params.order === "desc") {
+      points.reverse()
+    }
+
+    if (params.limit !== undefined) {
+      points = points.slice(0, Math.max(0, params.limit))
+    }
+
+    return points.map(clonePoint)
+  }
+
+  async getHistoryBatch(input: TimeseriesHistoryBatchInput): Promise<
+    readonly {
+      objectTypeId: string
+      objectId: string
+      propertyId: string
+      points: readonly TimeseriesPoint[]
+    }[]
+  > {
+    const results = []
+    for (const series of input.series) {
+      results.push({
+        ...series,
+        points: await this.getHistory({
+          projectId: input.projectId,
+          objectTypeId: series.objectTypeId,
+          objectId: series.objectId,
+          propertyId: series.propertyId,
+          from: input.from,
+          to: input.to,
+          limit: input.limitPerSeries,
+          order: input.order,
+        }),
+      })
+    }
+    return results
+  }
+
+  async getLatest(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    propertyId: string
+  }): Promise<TimeseriesPoint | null> {
+    const series = this.pointsByKey.get(
+      pointKey(params.projectId, params.objectTypeId, params.objectId, params.propertyId)
+    )
+    if (!series || series.size === 0) {
+      return null
+    }
+
+    let latest: TimeseriesPoint | null = null
+    for (const point of series.values()) {
+      if (!latest || point.at.getTime() > latest.at.getTime()) {
+        latest = point
+      }
+    }
+    return latest ? clonePoint(latest) : null
+  }
+}
+
+interface InMemoryTimeseriesMaterializerAdapter {
+  getExactPoint(projectId: string, series: TelemetrySeriesRef, at: string): TimeseriesPoint | null
+  listLatestForObject(projectId: string, objectTypeId: string, objectId: string): TimeseriesPoint[]
+  applyExactPoint(projectId: string, point: StoredTelemetryPoint): void
+}
+
+const materializerAdapters = new WeakMap<
+  InMemoryTimeseriesStorage,
+  InMemoryTimeseriesMaterializerAdapter
+>()
+
+/** @internal Exact access for the in-memory ontology provider; not exported from package barrels. */
+export function getInMemoryTimeseriesMaterializerAdapter(
+  storage: InMemoryTimeseriesStorage
+): InMemoryTimeseriesMaterializerAdapter {
+  const adapter = materializerAdapters.get(storage)
+  if (!adapter) throw new Error("[Sixb] In-memory timeseries materializer adapter is unavailable.")
+  return adapter
+}
+
+function clonePoint(point: TimeseriesPoint): TimeseriesPoint {
+  return {
+    ...structuredClone(point),
+    value: structuredClone(point.value),
+    at: new Date(point.at),
+  }
+}
+
+export interface InMemoryTimeseriesStorageSnapshot {
+  readonly pointsByKey: Map<string, Map<number, TimeseriesPoint>>
+}

package/src/storage/timeseries/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Time-series projection storage for telemetry history.
+ */
+export interface TimeseriesPoint {
+  projectId: string
+  objectTypeId: string
+  objectId: string
+  propertyId: string
+  value: unknown
+  unit?: string
+  at: Date
+  /** Commit that produced this effective point. */
+  lastCommitId: string
+}
+
+export interface TimeseriesHistorySeriesInput {
+  readonly objectTypeId: string
+  readonly objectId: string
+  readonly propertyId: string
+}
+
+export interface TimeseriesHistoryBatchInput {
+  readonly projectId: string
+  readonly series: readonly TimeseriesHistorySeriesInput[]
+  readonly from?: Date
+  readonly to?: Date
+  readonly limitPerSeries?: number
+  readonly order?: "asc" | "desc"
+}
+
+export interface TimeseriesHistoryBatchResult extends TimeseriesHistorySeriesInput {
+  readonly points: readonly TimeseriesPoint[]
+}
+
+export interface TimeseriesStorage {
+  getHistory(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    propertyId: string
+    from?: Date
+    to?: Date
+    limit?: number
+    order?: "asc" | "desc"
+  }): Promise<readonly TimeseriesPoint[]>
+
+  getHistoryBatch(
+    input: TimeseriesHistoryBatchInput
+  ): Promise<readonly TimeseriesHistoryBatchResult[]>
+
+  getLatest(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    propertyId: string
+  }): Promise<TimeseriesPoint | null>
+}

package/src/storage/transaction.ts

@@ -0,0 +1,56 @@
+import { StorageTransactionError } from "./errors"
+
+type ObjectLike = Record<PropertyKey, unknown>
+
+export function createTransactionStorageProxy<T extends object>(
+  target: T,
+  isActive: () => boolean
+): T {
+  const proxies = new WeakMap<object, object>()
+
+  const wrap = <TValue extends object>(value: TValue): TValue => {
+    const existing = proxies.get(value)
+    if (existing) return existing as TValue
+
+    const proxy = new Proxy(value as ObjectLike, {
+      // The guard runs on property access and on call. Its purpose is to fail fast when a
+      // transaction handle (`tx`) leaks past the transaction's lifetime — using it afterward is a
+      // bug, not a recoverable state. Overhead is bounded: only the storage namespaces reachable
+      // from `tx` are wrapped (a handful), not the row/link data graph, and never per-record.
+      get(current, property, receiver) {
+        assertTransactionActive(isActive)
+        const result = Reflect.get(current, property, receiver)
+        if (typeof result === "function") {
+          return (...args: unknown[]) => {
+            assertTransactionActive(isActive)
+            return result.apply(current, args)
+          }
+        }
+        if (result && typeof result === "object") {
+          return wrap(result)
+        }
+        return result
+      },
+    })
+
+    proxies.set(value, proxy)
+    return proxy as TValue
+  }
+
+  return wrap(target)
+}
+
+export function assertTransactionActive(isActive: () => boolean): void {
+  if (!isActive()) {
+    throw new StorageTransactionError(
+      "[Sixb] Transaction storage cannot be used after transaction completion.",
+      { code: "transaction_inactive" }
+    )
+  }
+}
+
+export function throwNestedStorageTransaction(): never {
+  throw new StorageTransactionError("[Sixb] Nested storage transactions are not supported yet.", {
+    code: "nested_transaction",
+  })
+}