@smithers-orchestrator/db 0.16.0

package/src/assertJsonPayloadWithinBounds.js

@@ -0,0 +1,94 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { assertMaxBytes } from "./assertMaxBytes.js";
+import { assertMaxJsonDepth } from "./assertMaxJsonDepth.js";
+/** @typedef {import("./JsonBounds.ts").JsonBounds} JsonBounds */
+
+/**
+ * @param {string} field
+ * @param {unknown} value
+ * @param {JsonBounds} bounds
+ * @param {string} path
+ * @param {Set<unknown>} seen
+ */
+function validateJsonValue(field, value, bounds, path, seen) {
+    if (value === null || typeof value === "boolean") {
+        return;
+    }
+    if (typeof value === "string") {
+        if (typeof bounds.maxStringLength === "number" &&
+            value.length > bounds.maxStringLength) {
+            throw new SmithersError("INVALID_INPUT", `${field} contains a string exceeding ${bounds.maxStringLength} characters.`, {
+                field,
+                path,
+                maxLength: bounds.maxStringLength,
+                actualLength: value.length,
+            });
+        }
+        return;
+    }
+    if (typeof value === "number") {
+        if (!Number.isFinite(value)) {
+            throw new SmithersError("INVALID_INPUT", `${field} must contain only finite numbers.`, { field, path, value });
+        }
+        return;
+    }
+    if (value === undefined ||
+        typeof value === "bigint" ||
+        typeof value === "function" ||
+        typeof value === "symbol") {
+        throw new SmithersError("INVALID_INPUT", `${field} must be JSON-serializable.`, { field, path, valueType: typeof value });
+    }
+    if (typeof value !== "object") {
+        throw new SmithersError("INVALID_INPUT", `${field} contains an unsupported value.`, { field, path, valueType: typeof value });
+    }
+    if (seen.has(value)) {
+        throw new SmithersError("INVALID_INPUT", `${field} must not contain circular references.`, { field, path });
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        if (typeof bounds.maxArrayLength === "number" &&
+            value.length > bounds.maxArrayLength) {
+            throw new SmithersError("INVALID_INPUT", `${field} contains an array exceeding ${bounds.maxArrayLength} items.`, {
+                field,
+                path,
+                maxLength: bounds.maxArrayLength,
+                actualLength: value.length,
+            });
+        }
+        for (let index = 0; index < value.length; index += 1) {
+            validateJsonValue(field, value[index], bounds, `${path}[${index}]`, seen);
+        }
+        seen.delete(value);
+        return;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        validateJsonValue(field, entry, bounds, `${path}.${key}`, seen);
+    }
+    seen.delete(value);
+}
+/**
+ * @param {string} field
+ * @param {unknown} value
+ * @param {JsonBounds} bounds
+ * @returns {string}
+ */
+export function assertJsonPayloadWithinBounds(field, value, bounds) {
+    let payloadJson;
+    try {
+        payloadJson = JSON.stringify(value);
+    }
+    catch (error) {
+        throw new SmithersError("INVALID_INPUT", `${field} must be JSON-serializable.`, { field }, { cause: error });
+    }
+    if (payloadJson === undefined) {
+        throw new SmithersError("INVALID_INPUT", `${field} must be JSON-serializable.`, { field });
+    }
+    if (typeof bounds.maxBytes === "number") {
+        assertMaxBytes(field, payloadJson, bounds.maxBytes);
+    }
+    if (typeof bounds.maxDepth === "number") {
+        assertMaxJsonDepth(field, value, bounds.maxDepth);
+    }
+    validateJsonValue(field, value, bounds, field, new Set());
+    return payloadJson;
+}

package/src/assertMaxBytes.js

@@ -0,0 +1,23 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/**
+ * @param {string} field
+ * @param {string | ArrayBuffer | ArrayBufferView} value
+ * @param {number} maxBytes
+ * @returns {number}
+ */
+export function assertMaxBytes(field, value, maxBytes) {
+    let actualBytes;
+    if (typeof value === "string") {
+        actualBytes = Buffer.byteLength(value, "utf8");
+    }
+    else if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) {
+        actualBytes = value.byteLength;
+    }
+    else {
+        throw new SmithersError("INVALID_INPUT", `${field} must be a string or byte buffer.`, { field, valueType: typeof value });
+    }
+    if (actualBytes > maxBytes) {
+        throw new SmithersError("INVALID_INPUT", `${field} exceeds the maximum size of ${maxBytes} bytes.`, { field, maxBytes, actualBytes });
+    }
+    return actualBytes;
+}

package/src/assertMaxJsonDepth.js

@@ -0,0 +1,40 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/**
+ * @param {string} field
+ * @param {unknown} value
+ * @param {number} depth
+ * @param {number} maxDepth
+ * @param {string} path
+ * @param {Set<unknown>} seen
+ */
+function validateJsonDepth(field, value, depth, maxDepth, path, seen) {
+    if (depth > maxDepth) {
+        throw new SmithersError("INVALID_INPUT", `${field} exceeds the maximum JSON depth of ${maxDepth}.`, { field, maxDepth, path });
+    }
+    if (value === null || typeof value !== "object") {
+        return;
+    }
+    if (seen.has(value)) {
+        throw new SmithersError("INVALID_INPUT", `${field} must not contain circular references.`, { field, path });
+    }
+    seen.add(value);
+    if (Array.isArray(value)) {
+        for (let index = 0; index < value.length; index += 1) {
+            validateJsonDepth(field, value[index], depth + 1, maxDepth, `${path}[${index}]`, seen);
+        }
+        seen.delete(value);
+        return;
+    }
+    for (const [key, entry] of Object.entries(value)) {
+        validateJsonDepth(field, entry, depth + 1, maxDepth, `${path}.${key}`, seen);
+    }
+    seen.delete(value);
+}
+/**
+ * @param {string} field
+ * @param {unknown} value
+ * @param {number} maxDepth
+ */
+export function assertMaxJsonDepth(field, value, maxDepth) {
+    validateJsonDepth(field, value, 1, maxDepth, field, new Set());
+}

package/src/assertMaxStringLength.js

@@ -0,0 +1,16 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/**
+ * @param {string} field
+ * @param {unknown} value
+ * @param {number} maxLength
+ * @returns {string}
+ */
+export function assertMaxStringLength(field, value, maxLength) {
+    if (typeof value !== "string") {
+        throw new SmithersError("INVALID_INPUT", `${field} must be a string.`, { field, valueType: typeof value });
+    }
+    if (value.length > maxLength) {
+        throw new SmithersError("INVALID_INPUT", `${field} exceeds the maximum length of ${maxLength} characters.`, { field, maxLength, actualLength: value.length });
+    }
+    return value;
+}

package/src/assertOptionalArrayMaxLength.js

@@ -0,0 +1,16 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/**
+ * @param {string} field
+ * @param {unknown} value
+ * @param {number} maxLength
+ */
+export function assertOptionalArrayMaxLength(field, value, maxLength) {
+    if (value === undefined || value === null)
+        return;
+    if (!Array.isArray(value)) {
+        throw new SmithersError("INVALID_INPUT", `${field} must be an array.`, { field, valueType: typeof value });
+    }
+    if (value.length > maxLength) {
+        throw new SmithersError("INVALID_INPUT", `${field} exceeds the maximum size of ${maxLength}.`, { field, maxLength, actualLength: value.length });
+    }
+}

package/src/assertOptionalStringMaxLength.js

@@ -0,0 +1,11 @@
+import { assertMaxStringLength } from "./assertMaxStringLength.js";
+/**
+ * @param {string} field
+ * @param {unknown} value
+ * @param {number} maxLength
+ */
+export function assertOptionalStringMaxLength(field, value, maxLength) {
+    if (value === undefined || value === null)
+        return;
+    assertMaxStringLength(field, value, maxLength);
+}

package/src/assertPositiveFiniteInteger.js

@@ -0,0 +1,14 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+import { assertPositiveFiniteNumber } from "./assertPositiveFiniteNumber.js";
+/**
+ * @param {string} field
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function assertPositiveFiniteInteger(field, value) {
+    const numberValue = assertPositiveFiniteNumber(field, value);
+    if (!Number.isInteger(numberValue)) {
+        throw new SmithersError("INVALID_INPUT", `${field} must be an integer greater than 0.`, { field, value });
+    }
+    return numberValue;
+}

package/src/assertPositiveFiniteNumber.js

@@ -0,0 +1,12 @@
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/**
+ * @param {string} field
+ * @param {unknown} value
+ * @returns {number}
+ */
+export function assertPositiveFiniteNumber(field, value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        throw new SmithersError("INVALID_INPUT", `${field} must be a finite number greater than 0.`, { field, value });
+    }
+    return value;
+}

package/src/buildHumanRequestId.js

@@ -0,0 +1,9 @@
+/**
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ * @returns {string}
+ */
+export function buildHumanRequestId(runId, nodeId, iteration) {
+  return `human:${runId}:${nodeId}:${iteration}`;
+}

package/src/cache/nodeDiffCache.js

@@ -0,0 +1,124 @@
+/** @typedef {import("@smithers-orchestrator/db/adapter").SmithersDb} _SmithersDb */
+/** @typedef {import("../adapter/NodeDiffCacheRow.ts").NodeDiffCacheRow} _NodeDiffCacheRow */
+/** @typedef {{ bundle: unknown; sizeBytes: number; cacheResult: "hit" | "miss" }} NodeDiffCacheResult */
+
+const NODE_DIFF_MAX_BYTES = 50 * 1024 * 1024;
+/** @type {WeakMap<object, Map<string, Promise<NodeDiffCacheResult>>>} */
+const inflightByDb = new WeakMap();
+/**
+ * @param {object} dbKey
+ * @returns {Map<string, Promise<NodeDiffCacheResult>>}
+ */
+function getInflightMap(dbKey) {
+    const existing = inflightByDb.get(dbKey);
+    if (existing) return existing;
+    /** @type {Map<string, Promise<NodeDiffCacheResult>>} */
+    const created = new Map();
+    inflightByDb.set(dbKey, created);
+    return created;
+}
+export class NodeDiffTooLargeError extends Error {
+    code = "DiffTooLarge";
+    /** @type {number} */
+    sizeBytes;
+    /** @param {number} sizeBytes */
+    constructor(sizeBytes) {
+        super(`Serialized diff exceeds ${NODE_DIFF_MAX_BYTES} bytes`);
+        this.name = "NodeDiffTooLargeError";
+        this.sizeBytes = sizeBytes;
+    }
+}
+export class NodeDiffCache {
+    /** @type {_SmithersDb} */
+    adapter;
+    /** @type {{ warn?: (message: string, details?: Record<string, unknown>) => void }} */
+    logger;
+    /**
+     * @param {_SmithersDb} adapter
+     * @param {{ warn?: (message: string, details?: Record<string, unknown>) => void }} [logger]
+     */
+    constructor(adapter, logger = {}) {
+        this.adapter = adapter;
+        this.logger = logger;
+    }
+    /**
+     * @param {{ runId: string; nodeId: string; iteration: number; baseRef: string; }} key
+     * @returns {string}
+     */
+    static keyString(key) {
+        return `${key.runId}::${key.nodeId}::${key.iteration}::${key.baseRef}`;
+    }
+    /**
+     * @param {{ runId: string; nodeId: string; iteration: number; baseRef: string; }} key
+     * @returns {Promise<{ bundle: unknown; sizeBytes: number; } | null>}
+     */
+    async get(key) {
+        const row = await this.adapter.getNodeDiffCache(key.runId, key.nodeId, key.iteration, key.baseRef);
+        if (!row || typeof row.diffJson !== "string") return null;
+        try {
+            const bundle = JSON.parse(row.diffJson);
+            const sizeBytes = Number(row.sizeBytes ?? Buffer.byteLength(row.diffJson, "utf8"));
+            return {
+                bundle,
+                sizeBytes: Number.isFinite(sizeBytes) ? sizeBytes : Buffer.byteLength(row.diffJson, "utf8"),
+            };
+        } catch {
+            this.logger.warn?.("Failed to parse cached node diff JSON; treating as miss.", {
+                runId: key.runId, nodeId: key.nodeId, iteration: key.iteration,
+            });
+            return null;
+        }
+    }
+    /**
+     * @param {{ runId: string; nodeId: string; iteration: number; baseRef: string; }} key
+     * @param {() => Promise<unknown>} compute
+     * @returns {Promise<NodeDiffCacheResult>}
+     */
+    async getOrCompute(key, compute) {
+        const hit = await this.get(key);
+        if (hit) return { bundle: hit.bundle, sizeBytes: hit.sizeBytes, cacheResult: "hit" };
+        const adapterWithDb = /** @type {_SmithersDb & { db?: object }} */ (this.adapter);
+        const inflight = getInflightMap(adapterWithDb.db ?? this.adapter);
+        const inflightKey = NodeDiffCache.keyString(key);
+        const pending = inflight.get(inflightKey);
+        if (pending) return pending;
+        const computePromise = (async () => {
+            const bundle = await compute();
+            const diffJson = JSON.stringify(bundle);
+            const sizeBytes = Buffer.byteLength(diffJson, "utf8");
+            if (sizeBytes > NODE_DIFF_MAX_BYTES) throw new NodeDiffTooLargeError(sizeBytes);
+            /** @type {_NodeDiffCacheRow} */
+            const row = {
+                runId: key.runId, nodeId: key.nodeId, iteration: key.iteration, baseRef: key.baseRef,
+                diffJson, computedAtMs: Date.now(), sizeBytes,
+            };
+            try {
+                await this.adapter.upsertNodeDiffCache(row);
+            } catch (error) {
+                this.logger.warn?.("Failed writing node diff cache row.", {
+                    runId: key.runId, nodeId: key.nodeId, iteration: key.iteration,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            return { bundle, sizeBytes, cacheResult: /** @type {const} */ ("miss") };
+        })().finally(() => { inflight.delete(inflightKey); });
+        inflight.set(inflightKey, computePromise);
+        return computePromise;
+    }
+    /**
+     * @param {string} runId
+     * @param {number} targetFrameNo
+     * @returns {ReturnType<_SmithersDb["invalidateNodeDiffsAfterFrame"]>}
+     */
+    invalidateAfterFrame(runId, targetFrameNo) {
+        return this.adapter.invalidateNodeDiffsAfterFrame(runId, targetFrameNo);
+    }
+    /**
+     * @param {string} [runId]
+     * @returns {ReturnType<_SmithersDb["countNodeDiffCacheRows"]>}
+     */
+    countRows(runId) {
+        return this.adapter.countNodeDiffCacheRows(runId);
+    }
+}
+export { NODE_DIFF_MAX_BYTES };

package/src/ensure.js

@@ -0,0 +1,18 @@
+import { Effect } from "effect";
+import { ensureSqlMessageStorageEffect } from "./sql-message-storage.js";
+/** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} _BunSQLiteDatabase */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} _SmithersError */
+
+/**
+ * @param {_BunSQLiteDatabase<Record<string, unknown>>} db
+ * @returns {Effect.Effect<void, _SmithersError>}
+ */
+export function ensureSmithersTablesEffect(db) {
+    return ensureSqlMessageStorageEffect(db).pipe(Effect.withLogSpan("db:ensure-smithers-tables"));
+}
+/**
+ * @param {_BunSQLiteDatabase<Record<string, unknown>>} db
+ */
+export function ensureSmithersTables(db) {
+    Effect.runSync(ensureSmithersTablesEffect(db));
+}

package/src/ensureSqlMessageStorage.js

@@ -0,0 +1,11 @@
+import { Database } from "bun:sqlite";
+import { getSqlMessageStorage } from "./getSqlMessageStorage.js";
+/** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} BunSQLiteDatabase */
+
+/**
+ * @param {BunSQLiteDatabase<any> | Database} db
+ * @returns {Promise<void>}
+ */
+export function ensureSqlMessageStorage(db) {
+    return getSqlMessageStorage(db).ensureSchema();
+}

package/src/ensureSqlMessageStorageEffect.js

@@ -0,0 +1,12 @@
+import { Database } from "bun:sqlite";
+import { Effect } from "effect";
+import { getSqlMessageStorage } from "./getSqlMessageStorage.js";
+/** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} BunSQLiteDatabase */
+
+/**
+ * @param {BunSQLiteDatabase<any> | Database} db
+ * @returns {Effect.Effect<void, never>}
+ */
+export function ensureSqlMessageStorageEffect(db) {
+    return getSqlMessageStorage(db).ensureSchemaEffect();
+}

package/src/frame-codec/FRAME_KEYFRAME_INTERVAL.js

@@ -0,0 +1 @@
+export const FRAME_KEYFRAME_INTERVAL = 50;

package/src/frame-codec/FrameDelta.ts

@@ -0,0 +1,6 @@
+import type { FrameDeltaOp } from "./FrameDeltaOp";
+
+export type FrameDelta = {
+  version: 1;
+  ops: FrameDeltaOp[];
+};

package/src/frame-codec/FrameDeltaOp.ts

@@ -0,0 +1,20 @@
+import type { JsonPath } from "./JsonPath";
+
+export type FrameDeltaOp =
+  | {
+      op: "set";
+      path: JsonPath;
+      value: unknown;
+      nodeId?: string;
+    }
+  | {
+      op: "insert";
+      path: JsonPath;
+      value: unknown;
+      nodeId?: string;
+    }
+  | {
+      op: "remove";
+      path: JsonPath;
+      nodeId?: string;
+    };

package/src/frame-codec/FrameEncoding.ts

@@ -0,0 +1 @@
+export type FrameEncoding = "full" | "delta" | "keyframe";

package/src/frame-codec/JsonPath.ts

@@ -0,0 +1,3 @@
+import type { JsonPathSegment } from "./JsonPathSegment";
+
+export type JsonPath = JsonPathSegment[];

package/src/frame-codec/JsonPathSegment.ts

@@ -0,0 +1 @@
+export type JsonPathSegment = string | number;

package/src/frame-codec/applyFrameDelta.js

@@ -0,0 +1,143 @@
+import { canonicalizeXml, parseXmlJson } from "@smithers-orchestrator/graph/utils/xml";
+/** @typedef {import("./FrameDeltaOp.ts").FrameDeltaOp} FrameDeltaOp */
+/** @typedef {import("./JsonPath.ts").JsonPath} JsonPath */
+/** @typedef {import("./JsonPathSegment.ts").JsonPathSegment} JsonPathSegment */
+
+/** @typedef {import("./FrameDelta.ts").FrameDelta} FrameDelta */
+
+/**
+ * @param {string} previousXmlJson
+ * @param {FrameDelta} delta
+ * @returns {string}
+ */
+export function applyFrameDelta(previousXmlJson, delta) {
+    const root = cloneValue(parseXmlJson(previousXmlJson));
+    const next = applyOps(root, delta.ops);
+    return canonicalizeXml(next);
+}
+/**
+ * @param {unknown} root
+ * @param {FrameDeltaOp[]} ops
+ * @returns {unknown}
+ */
+function applyOps(root, ops) {
+    let current = root;
+    for (const op of ops) {
+        if (op.op === "set") {
+            current = setAtPath(current, op.path, op.value);
+            continue;
+        }
+        if (op.op === "insert") {
+            current = insertAtPath(current, op.path, op.value);
+            continue;
+        }
+        current = removeAtPath(current, op.path);
+    }
+    return current;
+}
+/**
+ * @param {unknown} root
+ * @param {JsonPath} path
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function setAtPath(root, path, value) {
+    if (path.length === 0) {
+        return cloneValue(value);
+    }
+    const { parent, key } = getParentAndKey(root, path);
+    if (Array.isArray(parent)) {
+        if (typeof key !== "number") {
+            throw new Error("Invalid array set path");
+        }
+        parent[key] = cloneValue(value);
+        return root;
+    }
+    if (!isRecord(parent) || typeof key !== "string") {
+        throw new Error("Invalid object set path");
+    }
+    parent[key] = cloneValue(value);
+    return root;
+}
+/**
+ * @param {unknown} root
+ * @param {JsonPath} path
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+function insertAtPath(root, path, value) {
+    if (path.length === 0) {
+        return cloneValue(value);
+    }
+    const { parent, key } = getParentAndKey(root, path);
+    if (!Array.isArray(parent) || typeof key !== "number") {
+        throw new Error("Invalid insert path");
+    }
+    parent.splice(key, 0, cloneValue(value));
+    return root;
+}
+/**
+ * @param {unknown} root
+ * @param {JsonPath} path
+ * @returns {unknown}
+ */
+function removeAtPath(root, path) {
+    if (path.length === 0) {
+        return null;
+    }
+    const { parent, key } = getParentAndKey(root, path);
+    if (Array.isArray(parent)) {
+        if (typeof key !== "number") {
+            throw new Error("Invalid array remove path");
+        }
+        parent.splice(key, 1);
+        return root;
+    }
+    if (!isRecord(parent) || typeof key !== "string") {
+        throw new Error("Invalid object remove path");
+    }
+    delete parent[key];
+    return root;
+}
+/**
+ * @param {unknown} root
+ * @param {JsonPath} path
+ * @returns {{ parent: unknown; key: JsonPathSegment }}
+ */
+function getParentAndKey(root, path) {
+    let cursor = root;
+    for (let i = 0; i < path.length - 1; i += 1) {
+        const seg = path[i];
+        if (typeof seg === "number") {
+            if (!Array.isArray(cursor)) {
+                throw new Error("Invalid numeric path segment");
+            }
+            cursor = cursor[seg];
+            continue;
+        }
+        if (!isRecord(cursor)) {
+            throw new Error("Invalid object path segment");
+        }
+        cursor = cursor[seg];
+    }
+    return { parent: cursor, key: path[path.length - 1] };
+}
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * @template T
+ * @param {T} value
+ * @returns {T}
+ */
+function cloneValue(value) {
+    if (value === null)
+        return value;
+    if (typeof value !== "object")
+        return value;
+    return JSON.parse(JSON.stringify(value));
+}

package/src/frame-codec/applyFrameDeltaJson.js

@@ -0,0 +1,10 @@
+import { applyFrameDelta } from "./applyFrameDelta.js";
+import { parseFrameDelta } from "./parseFrameDelta.js";
+/**
+ * @param {string} previousXmlJson
+ * @param {string} deltaJson
+ * @returns {string}
+ */
+export function applyFrameDeltaJson(previousXmlJson, deltaJson) {
+    return applyFrameDelta(previousXmlJson, parseFrameDelta(deltaJson));
+}