@sixb/core 0.0.1

package/src/storage/objects/index.ts

@@ -0,0 +1,24 @@
+export type {
+  CountObjectsInput,
+  CountObjectsResult,
+  ExistsObjectsInput,
+  ExistsObjectsResult,
+  ExpandedLinkValue,
+  ExpandedObjectRow,
+  FacetObjectsInput,
+  FacetObjectsResult,
+  LinkDirection,
+  ObjectFacetBucket,
+  ObjectFacetRequest,
+  ObjectFacetResult,
+  ObjectLinkRow,
+  ObjectQueryCapabilities,
+  ObjectQueryCapabilityMap,
+  ObjectQueryScalarOperation,
+  ObjectQueryScalarOperations,
+  ObjectRow,
+  ObjectRowLinks,
+  ObjectStorage,
+  QueryObjectsInput,
+  QueryObjectsResult,
+} from "./types"

package/src/storage/objects/types.ts

@@ -0,0 +1,244 @@
+import type {
+  ObjectQuery,
+  ObjectQueryDirection,
+  ObjectQueryPredicate,
+  ObjectQuerySetOperation,
+  ObjectQuerySortField,
+  QueryScalarKind,
+} from "../../objects/query"
+
+/**
+ * Latest-state projection storage for objects and links.
+ */
+
+export interface ObjectRow {
+  projectId: string
+  objectTypeId: string
+  primaryId: string
+  properties: Record<string, unknown>
+  createdAt: Date
+  updatedAt: Date
+  version: number
+  /** Commit that produced the current effective row. */
+  lastCommitId: string
+  /**
+   * Linked objects attached by an `expand` query node, keyed by link id.
+   *
+   * Populated by the core executor during graph-aware reads; storage providers
+   * never read or write it. The wire response schema and the client `TwinObject`
+   * `.links` typing are layered on top of this runtime shape.
+   */
+  links?: ObjectRowLinks
+}
+
+/** Per-link expansion result keyed by link id (see {@link ObjectQueryExpand}). */
+export type ObjectRowLinks = Record<string, ExpandedLinkValue>
+
+/**
+ * The value attached under one expanded link.
+ *
+ * Cardinality drives the shape: a `"one"` link yields a single object (or
+ * `null` when the link is absent), a `"many"` link yields an array.
+ */
+export type ExpandedLinkValue = ExpandedObjectRow | readonly ExpandedObjectRow[] | null
+
+/** A hydrated linked object, plus any properties carried on the link edge itself. */
+export interface ExpandedObjectRow extends ObjectRow {
+  /** Relationship metadata stored on the link instance, when present. */
+  linkProperties?: Record<string, unknown>
+}
+
+export interface ObjectLinkRow {
+  projectId: string
+  sourceTypeId: string
+  sourceId: string
+  linkId: string
+  targetTypeId: string
+  targetId: string
+  properties?: Record<string, unknown>
+  createdAt: Date
+  updatedAt: Date
+  /** Commit that produced the current effective row. */
+  lastCommitId: string
+}
+
+export type LinkDirection = "outgoing" | "incoming" | "both"
+
+export type ObjectQueryCapabilityMap<T extends string> = Readonly<Partial<Record<T, boolean>>>
+
+export type ObjectQueryScalarOperation = "equality" | "ordering"
+
+export type ObjectQueryScalarOperations = Readonly<
+  Partial<Record<QueryScalarKind, ObjectQueryCapabilityMap<ObjectQueryScalarOperation>>>
+>
+
+/**
+ * Provider-declared object query support.
+ *
+ * Missing nested flags are treated as unsupported. The planner can use this
+ * as a pushdown boundary and decide separately whether bounded fallback is
+ * allowed for unsupported nodes.
+ */
+export interface ObjectQueryCapabilities {
+  /** True only when `queryObjects` is implemented and should be called. */
+  queryObjects: boolean
+  /** True only when `countObjects` is implemented and should be called. */
+  countObjects?: boolean
+  /** True only when `existsObjects` is implemented and should be called. */
+  existsObjects?: boolean
+  /** True only when `facetObjects` is implemented and should be called. */
+  facetObjects?: boolean
+  nodes?: ObjectQueryCapabilityMap<ObjectQuery["kind"]>
+  predicateOps?: ObjectQueryCapabilityMap<ObjectQueryPredicate["op"]>
+  sortKinds?: ObjectQueryCapabilityMap<ObjectQuerySortField["kind"]>
+  traversalDirections?: ObjectQueryCapabilityMap<ObjectQueryDirection>
+  setOps?: ObjectQueryCapabilityMap<ObjectQuerySetOperation>
+  /** Scalar operations whose semantics the provider can preserve exactly. */
+  scalarOperations?: ObjectQueryScalarOperations
+  features?: {
+    /**
+     * True only when the provider can expand `start.includeSubtypes` itself.
+     * Storage-only providers usually cannot, because subtype expansion requires
+     * the ontology registry and should fall back to the core executor.
+     */
+    includeSubtypes?: boolean
+  }
+  limits?: {
+    maxLimit?: number
+    maxPageSize?: number
+    totalCount?: boolean
+    stablePageTokens?: boolean
+  }
+  notes?: readonly string[]
+}
+
+export interface QueryObjectsInput {
+  projectId: string
+  query: ObjectQuery
+  includeTotal?: boolean
+}
+
+export interface QueryObjectsResult {
+  objects: readonly ObjectRow[]
+  hasMore: boolean
+  total?: number
+  nextPageToken?: string
+}
+
+export interface CountObjectsInput {
+  projectId: string
+  query: ObjectQuery
+}
+
+export interface CountObjectsResult {
+  count: number
+}
+
+export interface ExistsObjectsInput {
+  projectId: string
+  query: ObjectQuery
+}
+
+export interface ExistsObjectsResult {
+  exists: boolean
+}
+
+export interface ObjectFacetRequest {
+  propertyId: string
+  limit: number
+}
+
+export interface ObjectFacetBucket {
+  value: unknown
+  count: number
+}
+
+export interface ObjectFacetResult {
+  propertyId: string
+  buckets: readonly ObjectFacetBucket[]
+}
+
+export interface FacetObjectsInput {
+  projectId: string
+  query: ObjectQuery
+  facets: readonly ObjectFacetRequest[]
+}
+
+export interface FacetObjectsResult {
+  facets: readonly ObjectFacetResult[]
+}
+
+export interface ObjectStorage {
+  queryCapabilities(): ObjectQueryCapabilities
+
+  queryObjects?(params: QueryObjectsInput): Promise<QueryObjectsResult>
+  countObjects?(params: CountObjectsInput): Promise<CountObjectsResult>
+  existsObjects?(params: ExistsObjectsInput): Promise<ExistsObjectsResult>
+  facetObjects?(params: FacetObjectsInput): Promise<FacetObjectsResult>
+
+  getByPrimaryId(params: {
+    projectId: string
+    objectTypeId: string
+    primaryId: string
+  }): Promise<ObjectRow | null>
+
+  listLinks(params: {
+    projectId: string
+    objectTypeId: string
+    objectId: string
+    linkId?: string
+    direction?: LinkDirection
+  }): Promise<readonly ObjectLinkRow[]>
+
+  /**
+   * Batch fetch objects by (objectTypeId, primaryId) pairs.
+   * Returns a Map keyed by "objectTypeId:primaryId". Missing items are absent.
+   */
+  getByPrimaryIdBatch(params: {
+    projectId: string
+    items: readonly { objectTypeId: string; primaryId: string }[]
+  }): Promise<Map<string, ObjectRow>>
+
+  /**
+   * Batch fetch outgoing links by (objectTypeId, objectId, linkId) tuples.
+   * Returns a Map keyed by "objectTypeId:objectId:linkId". Missing entries are absent.
+   */
+  listLinksBatch(params: {
+    projectId: string
+    items: readonly { objectTypeId: string; objectId: string; linkId: string }[]
+  }): Promise<Map<string, ObjectLinkRow[]>>
+
+  /**
+   * Batch fetch every link incident to any of the given objects, in BOTH directions (the object as
+   * link source or target). Returns a flat, de-duplicated list: a physical link incident to two
+   * listed objects appears once. Used to load cascade-delete state for `object.delete` operations,
+   * which {@link listLinksBatch} cannot express because it keys on a specific linkId.
+   */
+  listIncidentLinksBatch(params: {
+    projectId: string
+    items: readonly { objectTypeId: string; objectId: string }[]
+  }): Promise<readonly ObjectLinkRow[]>
+
+  /** Stable keyset page used by background reconciliation without a total-count scan. */
+  listByPrimaryIdPage(params: {
+    projectId: string
+    objectTypeId: string
+    afterPrimaryId?: string
+    limit: number
+  }): Promise<{ objects: readonly ObjectRow[]; nextPrimaryId?: string }>
+
+  list(params: {
+    projectId: string
+    objectTypeId?: string | readonly string[]
+    primaryIdPrefix?: string
+    primaryIdSuffix?: string
+    updatedAfter?: Date
+    updatedBefore?: Date
+    createdAfter?: Date
+    createdBefore?: Date
+    limit?: number
+    offset?: number
+    orderBy?: "createdAt" | "updatedAt" | "primaryId"
+    order?: "asc" | "desc"
+  }): Promise<{ objects: readonly ObjectRow[]; hasMore: boolean; total: number }>
+}

package/src/storage/ontology/commits.ts

@@ -0,0 +1,132 @@
+import type { EventActor } from "../../events/envelope"
+import type {
+  EditCommitResult,
+  OntologyMaterializationOrigin,
+  PinnedDatasetVersion,
+  ProjectionCommitResult,
+  ProjectionSourceRef,
+  TelemetryCommitResult,
+} from "../../materialization/model"
+
+export interface GetOntologyCommitByIdempotencyKeyInput {
+  readonly projectId: string
+  readonly idempotencyKey: string
+}
+
+export interface GetOntologyCommitByIdInput {
+  readonly projectId: string
+  readonly id: string
+}
+
+export type OntologyCommitOriginSelector =
+  | { readonly kind: "action"; readonly actionRunId: string }
+  | { readonly kind: "projection"; readonly projectionRunId: string }
+  | {
+      readonly kind: "telemetry"
+      readonly projectionRunId: string
+      readonly batchOrdinal: number
+    }
+
+export interface GetOntologyCommitByOriginInput {
+  readonly projectId: string
+  readonly origin: OntologyCommitOriginSelector
+}
+
+export type OntologyCommitRunSelector =
+  | { readonly kind: "action"; readonly id: string }
+  | { readonly kind: "projection"; readonly id: string }
+
+export interface ListOntologyCommitsInput {
+  readonly projectId: string
+  readonly run?: OntologyCommitRunSelector
+  readonly limit?: number
+  readonly offset?: number
+  readonly order?: "asc" | "desc"
+}
+
+export interface ListOntologyCommitsResult {
+  readonly commits: readonly OntologyCommitRecord[]
+  readonly total: number
+  readonly hasMore: boolean
+}
+
+interface OntologyCommitFields {
+  readonly projectId: string
+  readonly id: string
+  readonly idempotencyKey: string
+  readonly requestHash: string
+  readonly origin: OntologyMaterializationOrigin
+  readonly actor?: EventActor
+  readonly ontologyRevision: string
+  readonly projectionRevision?: string
+  readonly ownershipHash?: string
+  readonly committedAt: string
+}
+
+export interface EditOntologyCommitIntent {
+  readonly kind: "edit"
+  readonly mode: "atomic" | "continue"
+  readonly operationCount: number
+}
+
+export interface ProjectionOntologyCommitIntent {
+  readonly kind: "projection"
+  readonly source: ProjectionSourceRef
+  readonly datasetVersion: PinnedDatasetVersion
+}
+
+interface TelemetryOntologyCommitIntentBase {
+  readonly kind: "telemetry"
+  /** Canonical unique points that enter semantic materialization. */
+  readonly pointCount: number
+  /** Caller-supplied points before equal-duplicate normalization. */
+  readonly inputPointCount: number
+}
+
+export type TelemetryOntologyCommitIntent =
+  | (TelemetryOntologyCommitIntentBase & {
+      readonly source: { readonly kind: "runtime" }
+    })
+  | (TelemetryOntologyCommitIntentBase & {
+      readonly source: {
+        readonly kind: "projection"
+        readonly projection: ProjectionSourceRef
+        readonly datasetVersion: PinnedDatasetVersion
+        readonly batchOrdinal: number
+        readonly sourceRowCount: number
+        readonly sourceRowsSkipped: number
+        readonly inputExhausted: boolean
+      }
+    })
+
+/** Commit metadata and intent supplied before the transaction is finalized. */
+export type OntologyCommitWrite =
+  | (OntologyCommitFields & { readonly intent: EditOntologyCommitIntent })
+  | (OntologyCommitFields & { readonly intent: ProjectionOntologyCommitIntent })
+  | (OntologyCommitFields & { readonly intent: TelemetryOntologyCommitIntent })
+
+/** Read-only finalized commit with an intent-correlated authoritative result. */
+export type OntologyCommitRecord =
+  | (OntologyCommitFields & {
+      readonly intent: EditOntologyCommitIntent
+      readonly result: EditCommitResult
+    })
+  | (OntologyCommitFields & {
+      readonly intent: ProjectionOntologyCommitIntent
+      readonly result: ProjectionCommitResult
+    })
+  | (OntologyCommitFields & {
+      readonly intent: TelemetryOntologyCommitIntent
+      readonly result: TelemetryCommitResult
+    })
+
+export interface OntologyCommitStorage {
+  getByIdempotencyKey(
+    input: GetOntologyCommitByIdempotencyKeyInput
+  ): Promise<OntologyCommitRecord | null>
+  getById(input: GetOntologyCommitByIdInput): Promise<OntologyCommitRecord | null>
+  /** Exact authoritative lookup used by Action/projection lifecycle coordination. */
+  getByOrigin(input: GetOntologyCommitByOriginInput): Promise<OntologyCommitRecord | null>
+  /** Reads authoritative commit history, optionally correlated to an Action or projection run. */
+  list(input: ListOntologyCommitsInput): Promise<ListOntologyCommitsResult>
+}

package/src/storage/ontology/in-memory/commits.ts

@@ -0,0 +1,122 @@
+import type {
+  GetOntologyCommitByIdempotencyKeyInput,
+  GetOntologyCommitByIdInput,
+  GetOntologyCommitByOriginInput,
+  ListOntologyCommitsInput,
+  ListOntologyCommitsResult,
+  OntologyCommitRecord,
+  OntologyCommitRunSelector,
+  OntologyCommitStorage,
+} from "../commits"
+import {
+  commitKey,
+  commitOriginKey,
+  type InMemoryOntologyState,
+  idempotencyKey,
+} from "./shared-state"
+
+export class InMemoryOntologyCommitStorage implements OntologyCommitStorage {
+  constructor(
+    private readonly state: InMemoryOntologyState,
+    private readonly runRootOperation: <T>(run: () => Promise<T> | T) => Promise<T>
+  ) {}
+
+  async getByIdempotencyKey(
+    input: GetOntologyCommitByIdempotencyKeyInput
+  ): Promise<OntologyCommitRecord | null> {
+    return this.runRootOperation(() => {
+      const id = this.state.commitIdByIdempotency.get(
+        idempotencyKey(input.projectId, input.idempotencyKey)
+      )
+      if (!id) return null
+      return structuredClone(this.state.commitsById.get(commitKey(input.projectId, id)) ?? null)
+    })
+  }
+
+  async getById(input: GetOntologyCommitByIdInput): Promise<OntologyCommitRecord | null> {
+    return this.runRootOperation(() =>
+      structuredClone(this.state.commitsById.get(commitKey(input.projectId, input.id)) ?? null)
+    )
+  }
+
+  async getByOrigin(input: GetOntologyCommitByOriginInput): Promise<OntologyCommitRecord | null> {
+    return this.runRootOperation(() => {
+      assertOriginLookup(input)
+      const id = this.state.commitIdByOrigin.get(commitOriginKey(input.projectId, input.origin))
+      if (!id) return null
+      return structuredClone(this.state.commitsById.get(commitKey(input.projectId, id)) ?? null)
+    })
+  }
+
+  async list(input: ListOntologyCommitsInput): Promise<ListOntologyCommitsResult> {
+    return this.runRootOperation(() => {
+      if (input.projectId.trim().length === 0 || input.run?.id.trim().length === 0) {
+        throw new Error("[Sixb] Ontology commit project and run ids must be nonblank.")
+      }
+      const offset = input.offset ?? 0
+      const limit = input.limit ?? this.state.commitsById.size
+      if (
+        !Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        !Number.isSafeInteger(limit) ||
+        limit < 0
+      ) {
+        throw new Error(
+          "[Sixb] Ontology commit list limit and offset must be nonnegative integers."
+        )
+      }
+      const direction = input.order === "desc" ? -1 : 1
+      const commits = [...this.state.commitsById.values()]
+        .filter((commit) => commit.projectId === input.projectId)
+        .filter((commit) => (input.run ? commitMatchesRun(commit, input.run) : true))
+        .sort((left, right) => {
+          if (input.run?.kind === "projection") {
+            const byOrdinal = projectionRunOrdinal(left) - projectionRunOrdinal(right)
+            if (byOrdinal !== 0) return byOrdinal * direction
+          }
+          const byTime = left.committedAt.localeCompare(right.committedAt)
+          if (byTime !== 0) return byTime * direction
+          return left.id.localeCompare(right.id) * direction
+        })
+      const total = commits.length
+      const page = commits.slice(offset, offset + limit).map((commit) => structuredClone(commit))
+      return { commits: page, total, hasMore: offset + page.length < total }
+    })
+  }
+}
+
+function assertOriginLookup(input: GetOntologyCommitByOriginInput): void {
+  if (input.projectId.trim().length === 0) {
+    throw new Error("[Sixb] Ontology commit project id must be nonblank.")
+  }
+  const runId =
+    input.origin.kind === "action" ? input.origin.actionRunId : input.origin.projectionRunId
+  if (runId.trim().length === 0) {
+    throw new Error("[Sixb] Ontology commit origin run id must be nonblank.")
+  }
+  if (
+    input.origin.kind === "telemetry" &&
+    (!Number.isSafeInteger(input.origin.batchOrdinal) || input.origin.batchOrdinal < 0)
+  ) {
+    throw new Error("[Sixb] Ontology telemetry commit batch ordinal must be nonnegative.")
+  }
+}
+
+function commitMatchesRun(commit: OntologyCommitRecord, run: OntologyCommitRunSelector): boolean {
+  if (run.kind === "action") {
+    return commit.origin.kind === "action" && commit.origin.runId === run.id
+  }
+  if (commit.origin.kind === "projection") return commit.origin.projectionRunId === run.id
+  return (
+    commit.origin.kind === "telemetry" &&
+    commit.origin.source.kind === "projection" &&
+    commit.origin.source.projectionRunId === run.id
+  )
+}
+
+function projectionRunOrdinal(commit: OntologyCommitRecord): number {
+  if (commit.origin.kind === "telemetry" && commit.origin.source.kind === "projection") {
+    return commit.origin.source.batchOrdinal
+  }
+  return 0
+}

package/src/storage/ontology/in-memory/index.ts

@@ -0,0 +1,94 @@
+import type { InMemoryObjectStorage } from "../../objects/in-memory"
+import type { InMemoryTimeseriesStorage } from "../../timeseries/store"
+import type { OntologyStorage } from ".."
+import type { ProviderMaterializationTransactionLifecycle } from "../provider"
+import type { AssertSourceMaterializationExecution } from "../sources"
+import { InMemoryOntologyCommitStorage } from "./commits"
+import { InMemoryOntologyMaterializationStorage } from "./materializations"
+import { InMemoryOntologyOutboxStorage } from "./outbox"
+import {
+  cloneOntologyState,
+  createInMemoryOntologyState,
+  type InMemoryOntologyState,
+  type InMemoryOntologyStorageTestHooks,
+  restoreOntologyState,
+} from "./shared-state"
+import { InMemoryOntologySourceStorage } from "./sources"
+import {
+  type InMemoryOntologyStorageTestingAdapter,
+  registerInMemoryOntologyStorageTestingAdapter,
+} from "./testing"
+
+export type InMemoryOntologyStorageSnapshot = InMemoryOntologyState
+
+interface InMemoryOntologyStorageOptions {
+  readonly runRootOperation: <T>(run: () => Promise<T> | T) => Promise<T>
+  readonly getTransactionToken: () => object | null
+  readonly getMaterializationLifecycle: () => ProviderMaterializationTransactionLifecycle | null
+  readonly assertSourceMaterializationExecution: AssertSourceMaterializationExecution
+}
+
+export class InMemoryOntologyStorage implements OntologyStorage {
+  private readonly state = createInMemoryOntologyState()
+  readonly commits: InMemoryOntologyCommitStorage
+  readonly sources: InMemoryOntologySourceStorage
+  readonly materializations: InMemoryOntologyMaterializationStorage
+  readonly outbox: InMemoryOntologyOutboxStorage
+  private testHooks: InMemoryOntologyStorageTestHooks = {}
+  private readonly testingAdapter: InMemoryOntologyStorageTestingAdapter = {
+    setTestHooks: (hooks) => this.setTestHooks(hooks),
+    snapshot: () => this.snapshot(),
+  }
+
+  constructor(
+    objects: InMemoryObjectStorage,
+    timeseries: InMemoryTimeseriesStorage,
+    options: InMemoryOntologyStorageOptions
+  ) {
+    this.commits = new InMemoryOntologyCommitStorage(this.state, options.runRootOperation)
+    this.sources = new InMemoryOntologySourceStorage(
+      this.state,
+      options.runRootOperation,
+      options.assertSourceMaterializationExecution
+    )
+    this.outbox = new InMemoryOntologyOutboxStorage(this.state, options.runRootOperation)
+    this.materializations = new InMemoryOntologyMaterializationStorage(
+      this.state,
+      objects,
+      timeseries,
+      options.getTransactionToken,
+      options.getMaterializationLifecycle,
+      {
+        beforeRead: (boundary) => this.testHooks.beforeRead?.(boundary),
+        beforeWrite: (boundary, ordinal) => this.testHooks.beforeWrite?.(boundary, ordinal),
+        observeBuffer: (boundary, rows) => this.testHooks.observeBuffer?.(boundary, rows),
+        observeWork: (records) => this.testHooks.observeWork?.(records),
+      }
+    )
+    registerInMemoryOntologyStorageTestingAdapter(this, this.testingAdapter)
+  }
+
+  /** @internal Test-only failure injection; not part of OntologyStorage. */
+  setTestHooks(hooks: InMemoryOntologyStorageTestHooks): void {
+    this.testHooks = hooks
+  }
+
+  /** @internal Register a decorated facade as an alias for the same test adapter. */
+  registerTestingAlias(storage: OntologyStorage): void {
+    registerInMemoryOntologyStorageTestingAdapter(storage, this.testingAdapter)
+  }
+
+  snapshot(): InMemoryOntologyStorageSnapshot {
+    return cloneOntologyState(this.state)
+  }
+
+  restore(snapshot: InMemoryOntologyStorageSnapshot): void {
+    restoreOntologyState(this.state, snapshot)
+  }
+
+  completeTransaction(transactionToken: object): void {
+    this.materializations.deactivateTransaction(transactionToken)
+  }
+}
+
+export type { InMemoryOntologyStorageTestHooks } from "./shared-state"