@uptimizr/db 0.1.0

package/dist/cli/seed.js

@@ -0,0 +1,175 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createApiKey, createProject } from "../duckdb/projects.js";
+import { createDuckdbClient } from "../duckdb/client.js";
+import { migrateDuckdb } from "../duckdb/migrations.js";
+import { readDbSettings } from "../env.js";
+/**
+ * Walk up from a starting directory until a directory containing
+ * `pnpm-workspace.yaml` is found, i.e. the monorepo root. Returns `undefined`
+ * if no such directory 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;
+    }
+}
+/**
+ * Set (or append) a `KEY=value` line in a `.env` file body, preserving the rest
+ * of the file. Only the first occurrence of the key is updated.
+ */
+function setEnvVar(body, key, value) {
+    const line = `${key}=${value}`;
+    const pattern = new RegExp(`^${key}=.*$`, "m");
+    if (pattern.test(body)) {
+        return body.replace(pattern, line);
+    }
+    return body.endsWith("\n") || body === "" ? `${body}${line}\n` : `${body}\n${line}\n`;
+}
+/**
+ * Write a set of `KEY=value` pairs into the root `.env` so the Babylon playground
+ * and dashboard pick them up automatically. No-op (with a hint) when no `.env`
+ * exists yet.
+ */
+function writeEnv(root, vars) {
+    const envPath = join(root, ".env");
+    if (!existsSync(envPath)) {
+        console.log(`  (no .env at ${envPath} — copy .env.example to .env to auto-fill these)`);
+        return;
+    }
+    let body = readFileSync(envPath, "utf8");
+    for (const [key, value] of Object.entries(vars)) {
+        body = setEnvVar(body, key, value);
+    }
+    writeFileSync(envPath, body);
+    console.log(`✓ wrote ${Object.keys(vars).join(", ")} to ${envPath}`);
+}
+/** The four built-in demo scenes (kept in sync with `examples/playground/scenes.json`). */
+const LOBBY_SCENE = {
+    id: "lobby",
+    label: "Lobby (viewer)",
+    description: "An orbit / arc-rotate camera framing a model — how people inspect an object.",
+    cameraMode: "viewer",
+    engines: ["babylon", "babylon-lite", "three", "playcanvas", "r3f", "aframe"],
+    defaultEngine: "babylon",
+    builtin: true,
+};
+const ATRIUM_SCENE = {
+    id: "atrium",
+    label: "Atrium (first-person)",
+    description: "A walkable scene traversed with WASD + look — where people walk and what they approach.",
+    cameraMode: "first-person",
+    engines: ["babylon", "three", "playcanvas"],
+    defaultEngine: "babylon",
+    builtin: true,
+};
+const SHOWCASE_SCENE = {
+    id: "showcase",
+    label: "Showcase (real glTF viewer)",
+    description: "An orbit camera framing a real glTF model (Khronos ToyCar) — inspecting a detailed PBR asset.",
+    cameraMode: "viewer",
+    engines: ["babylon", "three", "playcanvas"],
+    defaultEngine: "babylon",
+    builtin: false,
+};
+const GALLERY_SCENE = {
+    id: "gallery",
+    label: "Gallery (walkable real models)",
+    description: "A first-person walkable room with real glTF models (Khronos ToyCar, Fox, GlamVelvetSofa) on pedestals — walk up and inspect or pick the exhibits.",
+    cameraMode: "first-person",
+    engines: ["babylon", "three", "playcanvas"],
+    defaultEngine: "babylon",
+    builtin: false,
+};
+/**
+ * Upsert project entries into the local, gitignored registry the dashboard reads
+ * (`.uptimizr/projects.json`) so its project picker lists the seeded projects on
+ * first run without ever calling the collector.
+ */
+function writeRegistry(root, entries) {
+    const registryPath = join(root, ".uptimizr", "projects.json");
+    mkdirSync(dirname(registryPath), { recursive: true });
+    let list = [];
+    if (existsSync(registryPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(registryPath, "utf8"));
+            if (Array.isArray(parsed))
+                list = parsed;
+        }
+        catch {
+            list = [];
+        }
+    }
+    const ids = new Set(entries.map((e) => e.id));
+    // Also drop any prior entry bound to the same scene id, so re-seeding replaces a
+    // scene's project binding instead of stacking a duplicate card in the dashboard.
+    const sceneIds = new Set(entries.map((e) => e.scene?.id).filter((s) => typeof s === "string"));
+    const next = [
+        ...list.filter((p) => p && !ids.has(p.id) && !(p.scene?.id != null && sceneIds.has(p.scene.id))),
+        ...entries,
+    ];
+    writeFileSync(registryPath, `${JSON.stringify(next, null, 2)}\n`);
+    console.log(`✓ recorded ${entries.length} project(s) in ${registryPath}`);
+}
+/**
+ * Seed the demo projects — a **viewer** (arc-rotate) and a **walkable**
+ * (first-person) project for the built-in lobby/atrium scenes, plus a
+ * **showcase** and **gallery** project for the real-glTF demo scenes — and issue
+ * an API key for each. One project per scene mirrors how a real deployment keeps
+ * distinct experiences separate, and lets the playground route each scene's
+ * sessions to its own project (ADR 0026). Keys are printed once (stored only as
+ * hashes). Run via `pnpm --filter @uptimizr/db seed -- "My Project"`.
+ */
+async function main() {
+    const args = process.argv.slice(2).filter((arg) => arg !== "--");
+    const baseName = args[0] ?? "Demo Project";
+    const db = await createDuckdbClient(readDbSettings().duckdb.path);
+    await migrateDuckdb(db);
+    const viewer = await createProject(db, `${baseName} (Viewer)`);
+    const viewerKey = (await createApiKey(db, viewer.id)).key;
+    const walkable = await createProject(db, `${baseName} (Walkable)`);
+    const walkableKey = (await createApiKey(db, walkable.id)).key;
+    const showcase = await createProject(db, `${baseName} (Showcase)`);
+    const showcaseKey = (await createApiKey(db, showcase.id)).key;
+    const gallery = await createProject(db, `${baseName} (Gallery)`);
+    const galleryKey = (await createApiKey(db, gallery.id)).key;
+    await db.close();
+    console.log(`✓ project created: ${viewer.id} (${viewer.name})`);
+    console.log(`  API key (store securely, shown once): ${viewerKey}`);
+    console.log(`✓ project created: ${walkable.id} (${walkable.name})`);
+    console.log(`  API key (store securely, shown once): ${walkableKey}`);
+    console.log(`✓ project created: ${showcase.id} (${showcase.name})`);
+    console.log(`  API key (store securely, shown once): ${showcaseKey}`);
+    console.log(`✓ project created: ${gallery.id} (${gallery.name})`);
+    console.log(`  API key (store securely, shown once): ${galleryKey}`);
+    const root = findRepoRoot(process.cwd());
+    if (!root)
+        return;
+    const createdAt = new Date().toISOString();
+    writeEnv(root, {
+        VITE_PROJECT_ID: viewer.id,
+        VITE_API_KEY: viewerKey,
+        NEXT_PUBLIC_API_KEY: viewerKey,
+        VITE_PROJECT_ID_WALKABLE: walkable.id,
+        VITE_API_KEY_WALKABLE: walkableKey,
+    });
+    writeRegistry(root, [
+        { id: viewer.id, name: viewer.name, apiKey: viewerKey, createdAt, scene: LOBBY_SCENE },
+        { id: walkable.id, name: walkable.name, apiKey: walkableKey, createdAt, scene: ATRIUM_SCENE },
+        { id: showcase.id, name: showcase.name, apiKey: showcaseKey, createdAt, scene: SHOWCASE_SCENE },
+        { id: gallery.id, name: gallery.name, apiKey: galleryKey, createdAt, scene: GALLERY_SCENE },
+    ]);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=seed.js.map

package/dist/cli/seed.js.map

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

package/dist/duckdb/client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * DuckDB client — the OSS single-file store (ADR 0020).
+ *
+ * DuckDB is in-process and ACID, but a single connection is *not* safe for
+ * concurrent statements. We therefore expose one shared connection and serialize
+ * every operation through a promise chain ("single-writer discipline"). Reads and
+ * writes alike run one-at-a-time; for a self-hosted collector this is more than
+ * fast enough and removes an entire class of races.
+ *
+ * Values returned by the Neo client are post-processed by {@link convertValue}
+ * into plain JS so the rest of the codebase never sees DuckDB value wrappers.
+ */
+import { type DuckDBConnection } from "@duckdb/node-api";
+/** A row of already-converted, plain-JS values. */
+export type DuckdbRow = Record<string, unknown>;
+export interface DuckdbClient {
+    /** Run a statement, ignoring any result set. */
+    run(sql: string, params?: Record<string, unknown>): Promise<void>;
+    /** Run a query and return all rows as plain JS objects. */
+    all<T = DuckdbRow>(sql: string, params?: Record<string, unknown>): Promise<T[]>;
+    /**
+     * Acquire exclusive access to the underlying connection for a unit of work
+     * (e.g. a bulk append). No other client operation runs until `fn` settles.
+     */
+    exclusive<T>(fn: (con: DuckDBConnection) => Promise<T>): Promise<T>;
+    /** Close the connection and release the instance. */
+    close(): Promise<void>;
+}
+/**
+ * Convert a single DuckDB Neo value into a plain JS value:
+ * - `bigint` (from BIGINT/COUNT) → `number`
+ * - list values (`{ items: [...] }`) → arrays (recursively converted)
+ * - timestamp/date values → naive-UTC string via `toString()`
+ * - everything else (string/number/boolean/null) passes through unchanged.
+ */
+export declare function convertValue(value: unknown): unknown;
+/**
+ * Open (or create) a DuckDB store at `path`. Use `":memory:"` for tests.
+ * The returned client owns a single serialized connection.
+ */
+export declare function createDuckdbClient(path: string): Promise<DuckdbClient>;
+//# sourceMappingURL=client.d.ts.map

package/dist/duckdb/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/duckdb/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAKH,OAAO,EAAkB,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzE,mDAAmD;AACnD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD,MAAM,WAAW,YAAY;IAC3B,gDAAgD;IAChD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAClE,2DAA2D;IAC3D,GAAG,CAAC,CAAC,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,CAAC;IAChF;;;OAGG;IACH,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,qDAAqD;IACrD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAUpD;AAQD;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CA8C5E"}

package/dist/duckdb/client.js

@@ -0,0 +1,93 @@
+/**
+ * DuckDB client — the OSS single-file store (ADR 0020).
+ *
+ * DuckDB is in-process and ACID, but a single connection is *not* safe for
+ * concurrent statements. We therefore expose one shared connection and serialize
+ * every operation through a promise chain ("single-writer discipline"). Reads and
+ * writes alike run one-at-a-time; for a self-hosted collector this is more than
+ * fast enough and removes an entire class of races.
+ *
+ * Values returned by the Neo client are post-processed by {@link convertValue}
+ * into plain JS so the rest of the codebase never sees DuckDB value wrappers.
+ */
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { DuckDBInstance } from "@duckdb/node-api";
+/**
+ * Convert a single DuckDB Neo value into a plain JS value:
+ * - `bigint` (from BIGINT/COUNT) → `number`
+ * - list values (`{ items: [...] }`) → arrays (recursively converted)
+ * - timestamp/date values → naive-UTC string via `toString()`
+ * - everything else (string/number/boolean/null) passes through unchanged.
+ */
+export function convertValue(value) {
+    if (typeof value === "bigint")
+        return Number(value);
+    if (value == null || typeof value !== "object")
+        return value;
+    // DuckDBListValue exposes `.items`; arrays already plain.
+    if (Array.isArray(value))
+        return value.map(convertValue);
+    const obj = value;
+    if (Array.isArray(obj.items))
+        return obj.items.map(convertValue);
+    // DuckDBTimestampValue (`micros`) / DuckDBDateValue (`days`) → naive-UTC text.
+    if ("micros" in obj || "days" in obj)
+        return String(value);
+    return value;
+}
+function convertRow(row) {
+    const out = {};
+    for (const key of Object.keys(row))
+        out[key] = convertValue(row[key]);
+    return out;
+}
+/**
+ * Open (or create) a DuckDB store at `path`. Use `":memory:"` for tests.
+ * The returned client owns a single serialized connection.
+ */
+export async function createDuckdbClient(path) {
+    // DuckDB opens/creates the file but not its parent directory; ensure it
+    // exists first so a fresh checkout (e.g. ./data/uptimizr.duckdb) doesn't fail
+    // with ENOENT. Skip for the in-memory store, which has no filesystem path.
+    if (path !== ":memory:") {
+        await mkdir(dirname(path), { recursive: true });
+    }
+    const instance = await DuckDBInstance.create(path);
+    const connection = await instance.connect();
+    // Serialize every operation onto a single promise chain.
+    let tail = Promise.resolve();
+    function enqueue(fn) {
+        const result = tail.then(fn, fn);
+        // Keep the chain alive even if an op rejects.
+        tail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    return {
+        run(sql, params) {
+            return enqueue(async () => {
+                if (params)
+                    await connection.run(sql, params);
+                else
+                    await connection.run(sql);
+            });
+        },
+        all(sql, params) {
+            return enqueue(async () => {
+                const reader = params
+                    ? await connection.runAndReadAll(sql, params)
+                    : await connection.runAndReadAll(sql);
+                return reader.getRowObjects().map(convertRow);
+            });
+        },
+        exclusive(fn) {
+            return enqueue(() => fn(connection));
+        },
+        close() {
+            return enqueue(async () => {
+                connection.closeSync();
+            });
+        },
+    };
+}
+//# sourceMappingURL=client.js.map

package/dist/duckdb/client.js.map

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

package/dist/duckdb/events.d.ts

@@ -0,0 +1,44 @@
+import { type AnyEvent } from "@uptimizr/schema";
+import type { DuckdbClient } from "./client.js";
+import type { SessionMeta } from "../events.js";
+export type { SessionMeta };
+/**
+ * Batched insert of validated events via the DuckDB Appender — the bulk path
+ * that handles `DOUBLE[]` columns (including empty arrays) natively. Reuses the
+ * shared {@link toEventRow} mapper so the promoted columns match the ClickHouse
+ * store exactly; only `ts`/`inserted_at` are bound as native TIMESTAMP values.
+ *
+ * `node_transform` events (ADR 0027) are split out into the dedicated
+ * `node_samples` table rather than the wide `events` table; both writes happen
+ * under the same single-writer lock so a batch is never partially applied.
+ *
+ * Runs under the client's single-writer lock so the append is never interleaved
+ * with another statement.
+ */
+export declare function insertEvents(client: DuckdbClient, events: readonly AnyEvent[]): Promise<void>;
+/**
+ * Ordered read of a single session's events for replay/timeline. Returns
+ * fully-parsed, schema-validated events in `ts` order. Gated upstream by
+ * `ENABLE_RAW_SESSION_RETENTION` (ADR 0003) — this function does not enforce it.
+ *
+ * Merges the wide `events` table with the dedicated `node_samples` table
+ * (ADR 0027 §9) so scene-actor motion replays alongside the visitor's inputs.
+ */
+export declare function getSessionEvents(client: DuckdbClient, projectId: string, sessionId: string): Promise<AnyEvent[]>;
+/**
+ * Streaming counterpart to {@link getSessionEvents}: yields one validated event
+ * at a time in `ts` order. For the self-hosted single-file store a session is
+ * read in order and yielded incrementally; malformed/invalid rows are skipped.
+ * This is the path behind the collector's NDJSON replay response (ADR 0015).
+ *
+ * Includes reconstructed `node_samples` (ADR 0027), merged into the wide-event
+ * stream by `ts` so the replay timeline stays complete and ordered.
+ */
+export declare function streamSessionEvents(client: DuckdbClient, projectId: string, sessionId: string): AsyncGenerator<AnyEvent>;
+/**
+ * Read a session's stored metadata (`device`/`scene`/`user`) from its
+ * `session_start` event. Returns `null` when the session has no start event.
+ * Coarse descriptor — not gated by raw-session retention.
+ */
+export declare function getSessionMeta(client: DuckdbClient, projectId: string, sessionId: string): Promise<SessionMeta | null>;
+//# sourceMappingURL=events.d.ts.map

package/dist/duckdb/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/duckdb/events.ts"],"names":[],"mappings":"AACA,OAAO,EAAkB,KAAK,QAAQ,EAA2B,MAAM,kBAAkB,CAAC;AAE1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,YAAY,EAAE,WAAW,EAAE,CAAC;AAO5B;;;;;;;;;;;;GAYG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,YAAY,EACpB,MAAM,EAAE,SAAS,QAAQ,EAAE,GAC1B,OAAO,CAAC,IAAI,CAAC,CAuFf;AAuED;;;;;;;GAOG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,EAAE,CAAC,CAcrB;AAED;;;;;;;;GAQG;AACH,wBAAuB,mBAAmB,CACxC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,cAAc,CAAC,QAAQ,CAAC,CAe1B;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAqB7B"}

package/dist/duckdb/events.js

@@ -0,0 +1,225 @@
+import { DOUBLE, LIST, timestampValue } from "@duckdb/node-api";
+import { anyEventSchema } from "@uptimizr/schema";
+import { toEventRow, toNodeSampleRow, nodeSampleRowToEvent } from "../events.js";
+/** Coerce an event's epoch-ms timestamp into a DuckDB TIMESTAMP value (UTC micros). */
+function tsValue(epochMs) {
+    return timestampValue(BigInt(Math.trunc(epochMs)) * 1000n);
+}
+/**
+ * Batched insert of validated events via the DuckDB Appender — the bulk path
+ * that handles `DOUBLE[]` columns (including empty arrays) natively. Reuses the
+ * shared {@link toEventRow} mapper so the promoted columns match the ClickHouse
+ * store exactly; only `ts`/`inserted_at` are bound as native TIMESTAMP values.
+ *
+ * `node_transform` events (ADR 0027) are split out into the dedicated
+ * `node_samples` table rather than the wide `events` table; both writes happen
+ * under the same single-writer lock so a batch is never partially applied.
+ *
+ * Runs under the client's single-writer lock so the append is never interleaved
+ * with another statement.
+ */
+export async function insertEvents(client, events) {
+    if (events.length === 0)
+        return;
+    const wideEvents = events.filter((e) => e.type !== "node_transform");
+    const nodeSamples = events.filter((e) => e.type === "node_transform");
+    await client.exclusive(async (con) => {
+        const now = tsValue(Date.now());
+        if (wideEvents.length > 0) {
+            const appender = await con.createAppender("events");
+            for (const event of wideEvents) {
+                const row = toEventRow(event);
+                appender.appendVarchar(row.project_id);
+                appender.appendVarchar(row.session_id);
+                appender.appendVarchar(row.visitor_id);
+                appender.appendVarchar(row.event_type);
+                appender.appendTimestamp(tsValue(event.ts));
+                appender.appendVarchar(row.sdk_version);
+                appender.appendVarchar(row.url);
+                appender.appendVarchar(row.scene_id);
+                appender.appendVarchar(row.source);
+                appender.appendVarchar(row.handedness);
+                appender.appendVarchar(row.source_id);
+                appender.appendList(row.ray_origin, LIST(DOUBLE));
+                appender.appendList(row.ray_direction, LIST(DOUBLE));
+                appender.appendList(row.position, LIST(DOUBLE));
+                appender.appendList(row.direction, LIST(DOUBLE));
+                appender.appendList(row.hit_point, LIST(DOUBLE));
+                appender.appendList(row.screen, LIST(DOUBLE));
+                appender.appendVarchar(row.mesh);
+                appender.appendDouble(row.fps);
+                appender.appendVarchar(row.name);
+                appender.appendVarchar(row.payload);
+                appender.appendTimestamp(now);
+                // Columns added by later ALTER TABLE migrations are physically appended
+                // after `inserted_at`, so the mesh_visibility metrics (#37, migrations
+                // 0008–0010) are appended here, last, to match the table's column order.
+                appender.appendDouble(row.visible_ms);
+                appender.appendDouble(row.centered_ms);
+                appender.appendDouble(row.screen_fraction);
+                // resource_sample footprint columns (#44, migrations 0011–0015) follow,
+                // in table column order.
+                appender.appendDouble(row.texture_bytes);
+                appender.appendDouble(row.geometry_bytes);
+                appender.appendDouble(row.triangles);
+                appender.appendDouble(row.vertices);
+                appender.appendDouble(row.js_heap_bytes);
+                // capability_change tokens (#49, migrations 0016–0017) follow, in table
+                // column order. `kind` is carried by `name` above.
+                appender.appendVarchar(row.cap_from);
+                appender.appendVarchar(row.cap_to);
+                // frame_perf detail columns (#80, migrations 0020–0024) follow, in table
+                // column order. 0 on non-frame_perf rows (filtered out on read).
+                appender.appendDouble(row.frame_time_ms);
+                appender.appendDouble(row.frame_time_p95_ms);
+                appender.appendDouble(row.long_frames);
+                appender.appendDouble(row.dpr);
+                appender.appendDouble(row.render_scale);
+                appender.endRow();
+            }
+            appender.flushSync();
+            appender.closeSync();
+        }
+        if (nodeSamples.length > 0) {
+            // node_samples (ADR 0027 §9): transform-shaped table, column order matches
+            // migration 0018 — project, session, ts, sdk_version, scene_id, node_id,
+            // bone_id, position, rotation, scale, inserted_at. `child_path` (ADR 0033,
+            // migration 0025) is physically last, so it is appended after inserted_at.
+            const appender = await con.createAppender("node_samples");
+            for (const event of nodeSamples) {
+                const row = toNodeSampleRow(event);
+                appender.appendVarchar(row.project_id);
+                appender.appendVarchar(row.session_id);
+                appender.appendTimestamp(tsValue(event.ts));
+                appender.appendVarchar(row.sdk_version);
+                appender.appendVarchar(row.scene_id);
+                appender.appendVarchar(row.node_id);
+                appender.appendVarchar(row.bone_id);
+                appender.appendList(row.position, LIST(DOUBLE));
+                appender.appendList(row.rotation, LIST(DOUBLE));
+                appender.appendList(row.scale, LIST(DOUBLE));
+                appender.appendTimestamp(now);
+                appender.appendVarchar(row.child_path);
+                appender.endRow();
+            }
+            appender.flushSync();
+            appender.closeSync();
+        }
+    });
+}
+/**
+ * Read a session's stored `node_transform` samples (ADR 0027), reconstructed
+ * into replay-complete events in `ts` order. Split from {@link getSessionEvents}
+ * because they live in a dedicated table; the two ordered streams are merged by
+ * the callers below.
+ */
+async function readSessionNodeSamples(client, projectId, sessionId) {
+    const rows = await client.all(`SELECT epoch_ms(ts) AS ts_ms, sdk_version, scene_id, node_id, bone_id,
+            child_path, position, rotation, scale
+     FROM node_samples
+     WHERE project_id = $projectId AND session_id = $sessionId
+     ORDER BY ts ASC`, { projectId, sessionId });
+    return rows.map((row) => nodeSampleRowToEvent({
+        project_id: projectId,
+        session_id: sessionId,
+        sdk_version: row.sdk_version,
+        scene_id: row.scene_id,
+        node_id: row.node_id,
+        bone_id: row.bone_id,
+        child_path: row.child_path,
+        position: row.position ?? [],
+        rotation: row.rotation ?? [],
+        scale: row.scale ?? [],
+    }, row.ts_ms));
+}
+/**
+ * Merge two `ts`-ordered event streams into one ascending stream. Stable on
+ * ties (wide events before node samples at the same `ts`), so replay sees a
+ * single ordered timeline (ADR 0027 §8).
+ */
+function mergeByTs(wide, nodes) {
+    const merged = [];
+    let i = 0;
+    let j = 0;
+    while (i < wide.length && j < nodes.length) {
+        if (nodes[j].ts < wide[i].ts)
+            merged.push(nodes[j++]);
+        else
+            merged.push(wide[i++]);
+    }
+    while (i < wide.length)
+        merged.push(wide[i++]);
+    while (j < nodes.length)
+        merged.push(nodes[j++]);
+    return merged;
+}
+/**
+ * Ordered read of a single session's events for replay/timeline. Returns
+ * fully-parsed, schema-validated events in `ts` order. Gated upstream by
+ * `ENABLE_RAW_SESSION_RETENTION` (ADR 0003) — this function does not enforce it.
+ *
+ * Merges the wide `events` table with the dedicated `node_samples` table
+ * (ADR 0027 §9) so scene-actor motion replays alongside the visitor's inputs.
+ */
+export async function getSessionEvents(client, projectId, sessionId) {
+    const rows = await client.all(`SELECT payload FROM events
+     WHERE project_id = $projectId AND session_id = $sessionId
+     ORDER BY ts ASC`, { projectId, sessionId });
+    const events = [];
+    for (const row of rows) {
+        const parsed = anyEventSchema.safeParse(JSON.parse(row.payload));
+        if (parsed.success)
+            events.push(parsed.data);
+    }
+    const nodes = await readSessionNodeSamples(client, projectId, sessionId);
+    return nodes.length > 0 ? mergeByTs(events, nodes) : events;
+}
+/**
+ * Streaming counterpart to {@link getSessionEvents}: yields one validated event
+ * at a time in `ts` order. For the self-hosted single-file store a session is
+ * read in order and yielded incrementally; malformed/invalid rows are skipped.
+ * This is the path behind the collector's NDJSON replay response (ADR 0015).
+ *
+ * Includes reconstructed `node_samples` (ADR 0027), merged into the wide-event
+ * stream by `ts` so the replay timeline stays complete and ordered.
+ */
+export async function* streamSessionEvents(client, projectId, sessionId) {
+    const rows = await client.all(`SELECT payload FROM events
+     WHERE project_id = $projectId AND session_id = $sessionId
+     ORDER BY ts ASC`, { projectId, sessionId });
+    const wide = [];
+    for (const row of rows) {
+        const parsed = anyEventSchema.safeParse(JSON.parse(row.payload));
+        if (parsed.success)
+            wide.push(parsed.data);
+    }
+    const nodes = await readSessionNodeSamples(client, projectId, sessionId);
+    const ordered = nodes.length > 0 ? mergeByTs(wide, nodes) : wide;
+    for (const event of ordered)
+        yield event;
+}
+/**
+ * Read a session's stored metadata (`device`/`scene`/`user`) from its
+ * `session_start` event. Returns `null` when the session has no start event.
+ * Coarse descriptor — not gated by raw-session retention.
+ */
+export async function getSessionMeta(client, projectId, sessionId) {
+    const rows = await client.all(`SELECT payload, CAST(ts AS VARCHAR) AS ts FROM events
+     WHERE project_id = $projectId AND session_id = $sessionId
+       AND event_type = 'session_start'
+     ORDER BY ts ASC
+     LIMIT 1`, { projectId, sessionId });
+    const row = rows[0];
+    if (!row)
+        return null;
+    const parsed = anyEventSchema.safeParse(JSON.parse(row.payload));
+    const event = parsed.success && parsed.data.type === "session_start" ? parsed.data : undefined;
+    return {
+        sessionId,
+        startedAt: row.ts,
+        device: event?.device,
+        scene: event?.scene,
+        user: event?.user,
+    };
+}
+//# sourceMappingURL=events.js.map

package/dist/duckdb/events.js.map

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

package/dist/duckdb/migrations.d.ts

@@ -0,0 +1,20 @@
+import type { DuckdbClient } from "./client.js";
+/**
+ * Ordered, forward-only DuckDB migrations for the OSS single-file store
+ * (ADR 0020 / ADR 0007). Append new statements; never edit a shipped one. All
+ * statements are idempotent (`IF NOT EXISTS` / `CREATE OR REPLACE VIEW`), so
+ * {@link migrateDuckdb} is safe to run on every boot.
+ *
+ * This store is **single-tenant**: there is no `org_id` and no tenant isolation
+ * (those live only in the proprietary scale layer). Events and metadata share
+ * one file so a self-hosted collector needs no external services.
+ */
+export declare const DUCKDB_MIGRATIONS: ReadonlyArray<{
+    id: string;
+    sql: string;
+}>;
+/**
+ * Apply all DuckDB migrations in order. Idempotent — safe to run on every boot.
+ */
+export declare function migrateDuckdb(client: DuckdbClient): Promise<void>;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/duckdb/migrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrations.d.ts","sourceRoot":"","sources":["../../src/duckdb/migrations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAAa,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,CA2SxE,CAAC;AAEF;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAQvE"}