@uptimizr/db 0.1.0

package/dist/env.js

@@ -0,0 +1,55 @@
+/**
+ * Connection settings for the OSS DuckDB store, read from the environment
+ * (ADR 0020).
+ *
+ * Names mirror `.env.example`. Everything has a local-dev default so the package
+ * is usable out of the box (a single persisted `.duckdb` file).
+ */
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+function bool(value, fallback) {
+    if (value == null)
+        return fallback;
+    return value === "1" || value.toLowerCase() === "true";
+}
+/**
+ * Walk up from `start` until a directory containing `pnpm-workspace.yaml` is
+ * found, i.e. the monorepo root. Returns `undefined` if none exists.
+ */
+function findRepoRoot(start) {
+    let dir = start;
+    for (;;) {
+        if (existsSync(join(dir, "pnpm-workspace.yaml")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/**
+ * The default DuckDB file location when `DUCKDB_PATH` is unset.
+ *
+ * Resolved against the **repo root** (not the process cwd) so every tool — the
+ * collector server, the migrate/seed/new-project CLIs — converges on one
+ * canonical store no matter which package directory it runs from. Falls back to
+ * the cwd-relative path only when the repo root can't be located (e.g. when the
+ * package is consumed outside the monorepo).
+ */
+function defaultDuckdbPath() {
+    const root = findRepoRoot(process.cwd());
+    return root ? join(root, "data", "uptimizr.duckdb") : "./data/uptimizr.duckdb";
+}
+/**
+ * Build {@link DbSettings} from an env-like record (defaults to `process.env`).
+ * Passing an explicit record keeps this pure and testable.
+ */
+export function readDbSettings(env = process.env) {
+    return {
+        duckdb: {
+            path: env.DUCKDB_PATH ?? defaultDuckdbPath(),
+        },
+        enableRawSessionRetention: bool(env.ENABLE_RAW_SESSION_RETENTION, false),
+    };
+}
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAgB1C,SAAS,IAAI,CAAC,KAAyB,EAAE,QAAiB;IACxD,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO,QAAQ,CAAC;IACnC,OAAO,KAAK,KAAK,GAAG,IAAI,KAAK,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH,SAAS,YAAY,CAAC,KAAa;IACjC,IAAI,GAAG,GAAG,KAAK,CAAC;IAChB,SAAS,CAAC;QACR,IAAI,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC;YAAE,OAAO,GAAG,CAAC;QAC7D,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,GAAG;YAAE,OAAO,SAAS,CAAC;QACrC,GAAG,GAAG,MAAM,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,iBAAiB;IACxB,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC;AACjF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,MAAW,OAAO,CAAC,GAAG;IACnD,OAAO;QACL,MAAM,EAAE;YACN,IAAI,EAAE,GAAG,CAAC,WAAW,IAAI,iBAAiB,EAAE;SAC7C;QACD,yBAAyB,EAAE,IAAI,CAAC,GAAG,CAAC,4BAA4B,EAAE,KAAK,CAAC;KACzE,CAAC;AACJ,CAAC"}

package/dist/events.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Engine-neutral event-row mapping (ADR 0020).
+ *
+ * `toEventRow` flattens a validated event into the wide column set both storage
+ * engines share — DuckDB (OSS) and the single-tenant ClickHouse adapter (scale
+ * tier). Keeping it here, free of any engine client, lets both stores
+ * reuse one mapping and lets OSS carry zero ClickHouse references.
+ */
+import { type AnyEvent, type Device, type NodeTransformEvent, type SceneMeta, type SessionUser } from "@uptimizr/schema";
+/** Flat row matching the wide `events` table columns (engine-independent). */
+export interface EventRow {
+    project_id: string;
+    session_id: string;
+    visitor_id: string;
+    event_type: string;
+    ts: string;
+    sdk_version: string;
+    url: string;
+    scene_id: string;
+    source: string;
+    handedness: string;
+    source_id: string;
+    ray_origin: number[];
+    ray_direction: number[];
+    position: number[];
+    direction: number[];
+    hit_point: number[];
+    screen: number[];
+    mesh: string;
+    fps: number;
+    visible_ms: number;
+    centered_ms: number;
+    screen_fraction: number;
+    texture_bytes: number;
+    geometry_bytes: number;
+    triangles: number;
+    vertices: number;
+    js_heap_bytes: number;
+    cap_from: string;
+    cap_to: string;
+    frame_time_ms: number;
+    frame_time_p95_ms: number;
+    long_frames: number;
+    dpr: number;
+    render_scale: number;
+    name: string;
+    payload: string;
+}
+/**
+ * Format an epoch-millisecond timestamp as a naive-UTC `YYYY-MM-DD HH:MM:SS.mmm`
+ * literal. This is the timestamp form both engines accept (ClickHouse
+ * `DateTime64(3)` and DuckDB `TIMESTAMP`), avoiding seconds/millis ambiguity.
+ */
+export declare function formatUtcTimestamp(epochMs: number): string;
+/**
+ * Map a validated event into a flat row. Hot, queryable fields are promoted into
+ * dedicated columns for aggregation; the full event is preserved in `payload`
+ * (JSON) so reads remain replay-complete regardless of extraction.
+ */
+export declare function toEventRow(event: AnyEvent): EventRow;
+/** Per-session descriptor extracted from the session's `session_start` event. */
+export interface SessionMeta {
+    sessionId: string;
+    /** Session start time as a naive-UTC `YYYY-MM-DD HH:MM:SS.mmm` string, if known. */
+    startedAt: string | undefined;
+    device: Device | undefined;
+    scene: SceneMeta | undefined;
+    user: SessionUser | undefined;
+}
+/**
+ * Flat row matching the dedicated `node_samples` table (ADR 0027 §9). The
+ * `node_transform` event is split out of the wide `events` table: it is the
+ * highest-cardinality signal in the system, so it gets its own transform-shaped
+ * storage instead of padding `events` with quaternion/bone columns that are null
+ * for every other type. `bone_id` is `''` for the Tier-1 node/root tier; `scale`
+ * is `[]` when the sample omitted it (unchanged from identity / last sample).
+ * `child_path` (ADR 0033) is `''` for the declared root and for bone rows; it is
+ * the descendant's path relative to `node_id` for a Tier-1 subtree child.
+ */
+export interface NodeSampleRow {
+    project_id: string;
+    session_id: string;
+    ts: string;
+    sdk_version: string;
+    scene_id: string;
+    node_id: string;
+    bone_id: string;
+    child_path: string;
+    position: number[];
+    rotation: number[];
+    scale: number[];
+}
+/** Map a validated `node_transform` event into a flat {@link NodeSampleRow}. */
+export declare function toNodeSampleRow(event: NodeTransformEvent): NodeSampleRow;
+/**
+ * Reconstruct a replay-complete `node_transform` event from a stored
+ * {@link NodeSampleRow}. The dedicated table keeps only the transform-shaped
+ * columns, so this rehydrates the schema event for the replay merge (ADR 0027
+ * §8). `tsEpochMs` is the row's `ts` already converted back to epoch ms by the
+ * caller (engine-specific timestamp decoding stays in the store).
+ */
+export declare function nodeSampleRowToEvent(row: Pick<NodeSampleRow, "project_id" | "session_id" | "sdk_version" | "scene_id" | "node_id" | "bone_id" | "child_path"> & {
+    position: number[];
+    rotation: number[];
+    scale: number[];
+}, tsEpochMs: number): NodeTransformEvent;
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/events.js

@@ -0,0 +1,153 @@
+/**
+ * Engine-neutral event-row mapping (ADR 0020).
+ *
+ * `toEventRow` flattens a validated event into the wide column set both storage
+ * engines share — DuckDB (OSS) and the single-tenant ClickHouse adapter (scale
+ * tier). Keeping it here, free of any engine client, lets both stores
+ * reuse one mapping and lets OSS carry zero ClickHouse references.
+ */
+import { DEFAULT_SCENE_ID, } from "@uptimizr/schema";
+/**
+ * Format an epoch-millisecond timestamp as a naive-UTC `YYYY-MM-DD HH:MM:SS.mmm`
+ * literal. This is the timestamp form both engines accept (ClickHouse
+ * `DateTime64(3)` and DuckDB `TIMESTAMP`), avoiding seconds/millis ambiguity.
+ */
+export function formatUtcTimestamp(epochMs) {
+    const d = new Date(epochMs);
+    const p = (n, w = 2) => String(n).padStart(w, "0");
+    return (`${d.getUTCFullYear()}-${p(d.getUTCMonth() + 1)}-${p(d.getUTCDate())} ` +
+        `${p(d.getUTCHours())}:${p(d.getUTCMinutes())}:${p(d.getUTCSeconds())}.${p(d.getUTCMilliseconds(), 3)}`);
+}
+function vec(value) {
+    return Array.isArray(value) && value.every((n) => typeof n === "number")
+        ? value
+        : [];
+}
+/**
+ * Map a validated event into a flat row. Hot, queryable fields are promoted into
+ * dedicated columns for aggregation; the full event is preserved in `payload`
+ * (JSON) so reads remain replay-complete regardless of extraction.
+ */
+export function toEventRow(event) {
+    // The discriminated union widens awkwardly across payload variants; read
+    // optional fields through a permissive view without losing the validated input.
+    const e = event;
+    const hitPoint = vec(e.hitPoint).length ? vec(e.hitPoint) : vec(e.point);
+    const mesh = typeof e.mesh === "string" ? e.mesh : typeof e.hitMesh === "string" ? e.hitMesh : "";
+    // `name` carries the custom-event name / asset name, and is reused as the coarse
+    // `phase` label for compile_stall (#42) and the `kind` label for
+    // capability_change (#49) so those rollups can group without a dedicated column.
+    const name = typeof e.name === "string"
+        ? e.name
+        : typeof e.phase === "string"
+            ? e.phase
+            : typeof e.kind === "string"
+                ? e.kind
+                : "";
+    const ray = (e.ray ?? {});
+    return {
+        project_id: event.projectId,
+        session_id: event.sessionId,
+        visitor_id: event.visitorId ?? "",
+        event_type: event.type,
+        ts: formatUtcTimestamp(event.ts),
+        sdk_version: event.sdkVersion,
+        url: event.url ?? "",
+        scene_id: typeof e.sceneId === "string" && e.sceneId.length > 0 ? e.sceneId : DEFAULT_SCENE_ID,
+        source: typeof e.source === "string" && e.source.length > 0 ? e.source : "mouse",
+        handedness: typeof e.handedness === "string" ? e.handedness : "",
+        source_id: typeof e.sourceId === "string" ? e.sourceId : "",
+        ray_origin: vec(ray.origin),
+        ray_direction: vec(ray.direction),
+        position: vec(e.position),
+        direction: vec(e.direction),
+        hit_point: hitPoint,
+        screen: vec(e.screen),
+        mesh,
+        fps: typeof e.fps === "number" ? e.fps : 0,
+        // mesh_visibility dwell metrics (#37): promoted for the object-attention
+        // aggregation; 0 on every other event type (the full event stays in payload).
+        // hover_dwell (#48) reuses this column for its `dwellMs` duration, and
+        // compile_stall (#42) reuses it for its `durationMs` — all are millisecond
+        // durations, so no extra column/migration is needed.
+        visible_ms: typeof e.visibleMs === "number"
+            ? e.visibleMs
+            : typeof e.dwellMs === "number"
+                ? e.dwellMs
+                : typeof e.durationMs === "number"
+                    ? e.durationMs
+                    : 0,
+        centered_ms: typeof e.centeredMs === "number" ? e.centeredMs : 0,
+        screen_fraction: typeof e.maxScreenFraction === "number" ? e.maxScreenFraction : 0,
+        // resource_sample (#44) GPU / memory footprint metrics; 0 on other event
+        // types (the full event stays in payload). Every field is optional on the
+        // event, so undefined maps to 0 (NULL-equivalent for SUM/AVG/MAX).
+        texture_bytes: typeof e.textureBytes === "number" ? e.textureBytes : 0,
+        geometry_bytes: typeof e.geometryBytes === "number" ? e.geometryBytes : 0,
+        triangles: typeof e.triangles === "number" ? e.triangles : 0,
+        vertices: typeof e.vertices === "number" ? e.vertices : 0,
+        js_heap_bytes: typeof e.jsHeapBytes === "number" ? e.jsHeapBytes : 0,
+        // capability_change (#49) transition tokens; '' on other event types (the
+        // full event, including `reason`, stays in payload). `kind` lives in `name`.
+        cap_from: typeof e.from === "string" ? e.from : "",
+        cap_to: typeof e.to === "string" ? e.to : "",
+        // frame_perf (#80) percentile/jank/resolution detail; 0 on other event types
+        // (the full event stays in payload). All are optional on the event, so an
+        // absent field maps to 0 — perf queries filter `event_type = 'frame_perf'`
+        // and use `nullIf(...)` where 0 is not a meaningful sample (dpr/renderScale).
+        frame_time_ms: typeof e.frameTimeMs === "number" ? e.frameTimeMs : 0,
+        frame_time_p95_ms: typeof e.frameTimeP95Ms === "number" ? e.frameTimeP95Ms : 0,
+        long_frames: typeof e.longFrames === "number" ? e.longFrames : 0,
+        dpr: typeof e.dpr === "number" ? e.dpr : 0,
+        render_scale: typeof e.renderScale === "number" ? e.renderScale : 0,
+        name,
+        payload: JSON.stringify(event),
+    };
+}
+/** Map a validated `node_transform` event into a flat {@link NodeSampleRow}. */
+export function toNodeSampleRow(event) {
+    return {
+        project_id: event.projectId,
+        session_id: event.sessionId,
+        ts: formatUtcTimestamp(event.ts),
+        sdk_version: event.sdkVersion,
+        scene_id: typeof event.sceneId === "string" && event.sceneId.length > 0
+            ? event.sceneId
+            : DEFAULT_SCENE_ID,
+        node_id: event.nodeId,
+        bone_id: event.boneId ?? "",
+        child_path: event.childPath ?? "",
+        position: [...event.position],
+        rotation: [...event.rotation],
+        scale: event.scale ? [...event.scale] : [],
+    };
+}
+/**
+ * Reconstruct a replay-complete `node_transform` event from a stored
+ * {@link NodeSampleRow}. The dedicated table keeps only the transform-shaped
+ * columns, so this rehydrates the schema event for the replay merge (ADR 0027
+ * §8). `tsEpochMs` is the row's `ts` already converted back to epoch ms by the
+ * caller (engine-specific timestamp decoding stays in the store).
+ */
+export function nodeSampleRowToEvent(row, tsEpochMs) {
+    const event = {
+        type: "node_transform",
+        projectId: row.project_id,
+        sessionId: row.session_id,
+        ts: tsEpochMs,
+        sdkVersion: row.sdk_version,
+        nodeId: row.node_id,
+        position: row.position,
+        rotation: row.rotation,
+    };
+    if (row.scene_id && row.scene_id !== DEFAULT_SCENE_ID)
+        event.sceneId = row.scene_id;
+    if (row.bone_id)
+        event.boneId = row.bone_id;
+    if (row.child_path)
+        event.childPath = row.child_path;
+    if (row.scale.length === 3)
+        event.scale = row.scale;
+    return event;
+}
+//# sourceMappingURL=events.js.map

package/dist/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `@uptimizr/db` — the OSS storage contracts and the single-file DuckDB store
+ * (ADR 0020).
+ *
+ * Ships the dialect-agnostic query layer, engine-neutral event-row mapping and
+ * metadata types, and a fully-functional DuckDB store (events + metadata in one
+ * file). It carries no ClickHouse/Postgres dependency — an optional,
+ * separately-licensed scale store composes these contracts.
+ *
+ * Server/Node only — no DOM imports. Aggregations are query-time in v1.
+ */
+export { readDbSettings } from "./env.js";
+export type { DbSettings, DuckdbSettings } from "./env.js";
+export { toEventRow, formatUtcTimestamp } from "./events.js";
+export type { EventRow, SessionMeta } from "./events.js";
+export { toNodeSampleRow, nodeSampleRowToEvent } from "./events.js";
+export type { NodeSampleRow } from "./events.js";
+export { hashApiKey, apiKeyPrefix, generateApiKey } from "./metadata.js";
+export type { Project, ApiKeyRecord, ApiKeyCapability, ResolvedApiKey, SceneRepresentation, SceneRepresentationKind, SceneRepresentationSummary, } from "./metadata.js";
+export type { Dialect, ParamType } from "./query/dialect.js";
+export { duckdbDialect, toDuckdbTimestamp } from "./query/duckdbDialect.js";
+export { buildListSessions, buildPointerHeatmap, buildWorldHeatmap, buildGazeHeatmap, buildCameraDirectionHeatmap, buildCameraPositionHeatmap, buildSessionTrajectory, buildClickGazeRay, buildFlowHeatmap, buildTopMeshes, buildMeshDwell, buildDeadClicks, buildRageClicks, buildHoverDwell, buildCompileStalls, buildResourceSummary, buildCapabilityChanges, buildCameraGestures, buildPerfSummary, buildPerfDistribution, buildFpsHistogram, buildFrameTimePercentiles, buildJankRate, buildPerfByDevice, buildPerfByScene, buildResourcePercentiles, buildStabilityCounts, buildPerfDaily, buildEventsDaily, buildDistinctScenes, buildTimeseries, buildEventTypeCounts, buildSceneCoverage, buildCameraDistance, buildNavigationStats, buildXrRotationRate, buildXrSourceUsage, buildXrAbandonment, buildInteractionsBySource, } from "./query/aggregations.js";
+export type { QuerySpec, RangeOptions, SceneOptions, SourceOptions, SessionOptions, CameraModeOptions, TimeseriesOptions, SessionSummaryRow, HeatmapBinRow, WorldHeatmapBinRow, PositionBinRow, TrajectoryPointRow, DirectionBinRow, ClickGazeRayRow, FlowLinkRow, MeshCountRow, MeshDwellRow, DeadClickRow, RageClickRow, HoverDwellRow, CompileStallRow, ResourceSummaryRow, CapabilityChangeRow, CameraGestureRow, PerfSummaryRow, PerfDistributionRow, FpsHistogramRow, FrameTimePercentileRow, JankRateRow, PerfByDeviceRow, PerfBySceneRow, ResourcePercentileRow, StabilityCountRow, PerfDailyRow, EventsDailyRow, SceneRow, TimeseriesBucketRow, EventTypeCountRow, CoverageVoxelRow, CameraDistanceBucketRow, NavigationStatsRow, XrRotationRateRow, XrSourceUsageRow, XrAbandonmentRow, InteractionSourceRow, } from "./query/types.js";
+export { createDuckdbClient, convertValue } from "./duckdb/client.js";
+export type { DuckdbClient, DuckdbRow } from "./duckdb/client.js";
+export { DUCKDB_MIGRATIONS, migrateDuckdb } from "./duckdb/migrations.js";
+export { runDuckdbQuery } from "./duckdb/queries.js";
+export { insertEvents as duckdbInsertEvents, getSessionEvents as duckdbGetSessionEvents, streamSessionEvents as duckdbStreamSessionEvents, getSessionMeta as duckdbGetSessionMeta, } from "./duckdb/events.js";
+export { createProject as duckdbCreateProject, getProject as duckdbGetProject, createApiKey as duckdbCreateApiKey, resolveApiKey as duckdbResolveApiKey, } from "./duckdb/projects.js";
+export { upsertSceneProxy as duckdbUpsertSceneProxy, getSceneRepresentation as duckdbGetSceneRepresentation, listSceneRepresentations as duckdbListSceneRepresentations, } from "./duckdb/sceneRegistry.js";
+export { PARITY_PROJECT_ID, PARITY_T0, PARITY_RANGE, PARITY_DAY_RANGE, PARITY_DAY, PARITY_EVENTS, } from "./parity/fixtures.js";
+export { PARITY_ABS_TOLERANCE, PARITY_REL_TOLERANCE, diffParity } from "./parity/compare.js";
+export type { ParityRow, ParityCompareOptions } from "./parity/compare.js";
+export { PARITY_CASES } from "./parity/cases.js";
+export type { ParityCase } from "./parity/cases.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * `@uptimizr/db` — the OSS storage contracts and the single-file DuckDB store
+ * (ADR 0020).
+ *
+ * Ships the dialect-agnostic query layer, engine-neutral event-row mapping and
+ * metadata types, and a fully-functional DuckDB store (events + metadata in one
+ * file). It carries no ClickHouse/Postgres dependency — an optional,
+ * separately-licensed scale store composes these contracts.
+ *
+ * Server/Node only — no DOM imports. Aggregations are query-time in v1.
+ */
+export { readDbSettings } from "./env.js";
+// --- Engine-neutral event-row mapping (ADR 0020) ---
+export { toEventRow, formatUtcTimestamp } from "./events.js";
+// --- Scene-actor transform mapping (node_transform → node_samples, ADR 0027) ---
+export { toNodeSampleRow, nodeSampleRowToEvent } from "./events.js";
+// --- Engine-neutral metadata helpers and types (ADR 0020) ---
+export { hashApiKey, apiKeyPrefix, generateApiKey } from "./metadata.js";
+export { duckdbDialect, toDuckdbTimestamp } from "./query/duckdbDialect.js";
+export { buildListSessions, buildPointerHeatmap, buildWorldHeatmap, buildGazeHeatmap, buildCameraDirectionHeatmap, buildCameraPositionHeatmap, buildSessionTrajectory, buildClickGazeRay, buildFlowHeatmap, buildTopMeshes, buildMeshDwell, buildDeadClicks, buildRageClicks, buildHoverDwell, buildCompileStalls, buildResourceSummary, buildCapabilityChanges, buildCameraGestures, buildPerfSummary, buildPerfDistribution, buildFpsHistogram, buildFrameTimePercentiles, buildJankRate, buildPerfByDevice, buildPerfByScene, buildResourcePercentiles, buildStabilityCounts, buildPerfDaily, buildEventsDaily, buildDistinctScenes, buildTimeseries, buildEventTypeCounts, buildSceneCoverage, buildCameraDistance, buildNavigationStats, buildXrRotationRate, buildXrSourceUsage, buildXrAbandonment, buildInteractionsBySource, } from "./query/aggregations.js";
+// --- DuckDB (OSS single-file store, ADR 0020) ---
+export { createDuckdbClient, convertValue } from "./duckdb/client.js";
+export { DUCKDB_MIGRATIONS, migrateDuckdb } from "./duckdb/migrations.js";
+export { runDuckdbQuery } from "./duckdb/queries.js";
+export { insertEvents as duckdbInsertEvents, getSessionEvents as duckdbGetSessionEvents, streamSessionEvents as duckdbStreamSessionEvents, getSessionMeta as duckdbGetSessionMeta, } from "./duckdb/events.js";
+export { createProject as duckdbCreateProject, getProject as duckdbGetProject, createApiKey as duckdbCreateApiKey, resolveApiKey as duckdbResolveApiKey, } from "./duckdb/projects.js";
+export { upsertSceneProxy as duckdbUpsertSceneProxy, getSceneRepresentation as duckdbGetSceneRepresentation, listSceneRepresentations as duckdbListSceneRepresentations, } from "./duckdb/sceneRegistry.js";
+// --- Cross-engine parity harness (ADR 0020) ---
+// Shared fixtures, golden expectations, and a tolerance-aware comparator. OSS
+// runs DuckDB-vs-golden; the scale tier reuses these to run DuckDB-vs-ClickHouse.
+export { PARITY_PROJECT_ID, PARITY_T0, PARITY_RANGE, PARITY_DAY_RANGE, PARITY_DAY, PARITY_EVENTS, } from "./parity/fixtures.js";
+export { PARITY_ABS_TOLERANCE, PARITY_REL_TOLERANCE, diffParity } from "./parity/compare.js";
+export { PARITY_CASES } from "./parity/cases.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C,sDAAsD;AACtD,OAAO,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAG7D,kFAAkF;AAClF,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAGpE,+DAA+D;AAC/D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAgBzE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC5E,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,2BAA2B,EAC3B,0BAA0B,EAC1B,sBAAsB,EACtB,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACd,cAAc,EACd,eAAe,EACf,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,EACtB,mBAAmB,EACnB,gBAAgB,EAChB,qBAAqB,EACrB,iBAAiB,EACjB,yBAAyB,EACzB,aAAa,EACb,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,EACf,oBAAoB,EACpB,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,yBAAyB,CAAC;AAiDjC,mDAAmD;AACnD,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EACL,YAAY,IAAI,kBAAkB,EAClC,gBAAgB,IAAI,sBAAsB,EAC1C,mBAAmB,IAAI,yBAAyB,EAChD,cAAc,IAAI,oBAAoB,GACvC,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,aAAa,IAAI,mBAAmB,EACpC,UAAU,IAAI,gBAAgB,EAC9B,YAAY,IAAI,kBAAkB,EAClC,aAAa,IAAI,mBAAmB,GACrC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,gBAAgB,IAAI,sBAAsB,EAC1C,sBAAsB,IAAI,4BAA4B,EACtD,wBAAwB,IAAI,8BAA8B,GAC3D,MAAM,2BAA2B,CAAC;AAEnC,iDAAiD;AACjD,8EAA8E;AAC9E,kFAAkF;AAClF,OAAO,EACL,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,UAAU,EACV,aAAa,GACd,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAE7F,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/metadata.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Engine-neutral metadata helpers and types (ADR 0020).
+ *
+ * API-key hashing/generation are pure crypto and the project / API-key / scene
+ * representation shapes are storage-independent. Both the OSS DuckDB store and
+ * the scale-tier Postgres metadata clients reuse these, so the type contracts live
+ * once and OSS carries no Postgres dependency.
+ */
+import type { Aabb, SceneProxy } from "@uptimizr/schema";
+/** SHA-256 hash of an API key. Only the hash is ever stored (never plaintext). */
+export declare function hashApiKey(plaintext: string): string;
+/** Display prefix used to identify a key without revealing it. */
+export declare function apiKeyPrefix(plaintext: string): string;
+/** Generate a new opaque API key (`utk_` + 32 random bytes, base64url). */
+export declare function generateApiKey(): string;
+export interface Project {
+    id: string;
+    name: string;
+    /** Owning organization (scale tier). `null` for single-tenant/OSS projects. */
+    orgId: string | null;
+    createdAt: Date;
+}
+/**
+ * What a project API key is allowed to do. `query` keys may read the analytics
+ * API (the default — public ingestion is keyless, so issued keys are for
+ * reads); `ingest` keys are reserved for server-side write paths.
+ */
+export type ApiKeyCapability = "ingest" | "query";
+export interface ApiKeyRecord {
+    id: string;
+    projectId: string;
+    keyPrefix: string;
+    createdAt: Date;
+    revokedAt: Date | null;
+    /** What this key is allowed to do. Defaults to `query`. */
+    capability: ApiKeyCapability;
+}
+/**
+ * The result of resolving a plaintext API key: the project it authenticates and
+ * the capability that scopes what it may do at the request boundary.
+ */
+export interface ResolvedApiKey {
+    projectId: string;
+    capability: ApiKeyCapability;
+}
+/**
+ * One representation per `(projectId, sceneId)`. Gives world-space heatmaps a
+ * backdrop — an engine-agnostic {@link SceneProxy} captured from a live scene, a
+ * URL to an external display asset, or `"none"` (registered, label only).
+ */
+export type SceneRepresentationKind = "none" | "proxy" | "asset";
+export interface SceneRepresentation {
+    projectId: string;
+    sceneId: string;
+    /** Human-friendly label for the scene (developer-supplied). */
+    label: string | null;
+    kind: SceneRepresentationKind;
+    upAxis: "y" | "z";
+    unitScale: number;
+    /** Overall world bounds `[minX,minY,minZ,maxX,maxY,maxZ]`, when known. */
+    bounds: Aabb | null;
+    /** Full proxy geometry when `kind === "proxy"`. */
+    proxy: SceneProxy | null;
+    /** External asset URL when `kind === "asset"`. */
+    assetUrl: string | null;
+    /** Content digest of the proxy/asset for cache validation. */
+    contentHash: string | null;
+    /** Proxy wire-format version, when a proxy is stored. */
+    proxyVersion: number | null;
+    /** When the geometry was captured (epoch-based; `null` for `"none"`). */
+    capturedAt: Date | null;
+    updatedAt: Date;
+}
+/** Lightweight registry listing row (omits the heavy `proxy` blob). */
+export interface SceneRepresentationSummary {
+    sceneId: string;
+    label: string | null;
+    kind: SceneRepresentationKind;
+    bounds: Aabb | null;
+    contentHash: string | null;
+    capturedAt: Date | null;
+    updatedAt: Date;
+}
+//# sourceMappingURL=metadata.d.ts.map

package/dist/metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.d.ts","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAIzD,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,kEAAkE;AAClE,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,2EAA2E;AAC3E,wBAAgB,cAAc,IAAI,MAAM,CAEvC;AAID,MAAM,WAAW,OAAO;IACtB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,OAAO,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,IAAI,CAAC;IAChB,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,2DAA2D;IAC3D,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,gBAAgB,CAAC;CAC9B;AAID;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAEjE,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,uBAAuB,CAAC;IAC9B,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,mDAAmD;IACnD,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IACzB,kDAAkD;IAClD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,yDAAyD;IACzD,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,yEAAyE;IACzE,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,uEAAuE;AACvE,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,uBAAuB,CAAC;IAC9B,MAAM,EAAE,IAAI,GAAG,IAAI,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,IAAI,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,IAAI,CAAC;CACjB"}

package/dist/metadata.js

@@ -0,0 +1,23 @@
+/**
+ * Engine-neutral metadata helpers and types (ADR 0020).
+ *
+ * API-key hashing/generation are pure crypto and the project / API-key / scene
+ * representation shapes are storage-independent. Both the OSS DuckDB store and
+ * the scale-tier Postgres metadata clients reuse these, so the type contracts live
+ * once and OSS carries no Postgres dependency.
+ */
+import { createHash, randomBytes } from "node:crypto";
+// --- API keys (pure crypto) ---
+/** SHA-256 hash of an API key. Only the hash is ever stored (never plaintext). */
+export function hashApiKey(plaintext) {
+    return createHash("sha256").update(plaintext).digest("hex");
+}
+/** Display prefix used to identify a key without revealing it. */
+export function apiKeyPrefix(plaintext) {
+    return plaintext.slice(0, 12);
+}
+/** Generate a new opaque API key (`utk_` + 32 random bytes, base64url). */
+export function generateApiKey() {
+    return `utk_${randomBytes(32).toString("base64url")}`;
+}
+//# sourceMappingURL=metadata.js.map

package/dist/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../src/metadata.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAGtD,iCAAiC;AAEjC,kFAAkF;AAClF,MAAM,UAAU,UAAU,CAAC,SAAiB;IAC1C,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;AAC9D,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,OAAO,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc;IAC5B,OAAO,OAAO,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC;AACxD,CAAC"}

package/dist/parity/cases.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Cross-engine parity cases (Phase C, ADR 0020).
+ *
+ * Each case pairs one dialect-agnostic aggregation builder with the
+ * engine-independent golden output it must produce for {@link PARITY_EVENTS}.
+ * The golden is authored as truth (hand-verified from the fixtures) so that any
+ * engine — DuckDB in OSS, ClickHouse in the scale tier — can be checked against
+ * the same expectations. Two engines that both match the golden are, by
+ * transitivity, in parity with each other.
+ *
+ * Comparison uses the tolerance rules in {@link diffParity}: order-insensitive,
+ * float-tolerant on continuous columns, integer-exact on bin indices, and
+ * temporal projection columns excluded.
+ */
+import type { Dialect } from "../query/dialect.js";
+import type { QuerySpec } from "../query/types.js";
+import type { ParityRow } from "./compare.js";
+export interface ParityCase {
+    /** Stable identifier (also the test name). */
+    readonly name: string;
+    /** Render the aggregation for a given engine dialect. */
+    build(dialect: Dialect): QuerySpec;
+    /** Columns that together order a row for multiset comparison. */
+    readonly sortKeys: readonly string[];
+    /** Engine-specific temporal columns excluded from comparison. */
+    readonly ignoreColumns?: readonly string[];
+    /** Engine-independent expected output. */
+    readonly golden: readonly ParityRow[];
+}
+export declare const PARITY_CASES: readonly ParityCase[];
+//# sourceMappingURL=cases.d.ts.map

package/dist/parity/cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cases.d.ts","sourceRoot":"","sources":["../../src/parity/cases.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AA2CH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAS9C,MAAM,WAAW,UAAU;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,CAAC;IACnC,iEAAiE;IACjE,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,iEAAiE;IACjE,QAAQ,CAAC,aAAa,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C,0CAA0C;IAC1C,QAAQ,CAAC,MAAM,EAAE,SAAS,SAAS,EAAE,CAAC;CACvC;AAID,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EA2f7C,CAAC"}