@smithers-orchestrator/db 0.16.0

package/src/loadInputEffect.js

@@ -0,0 +1,28 @@
+import { eq } from "drizzle-orm";
+import { getTableColumns } from "drizzle-orm/utils";
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} BunSQLiteDatabase */
+/** @typedef {import("drizzle-orm").Table} Table */
+
+/**
+ * @param {BunSQLiteDatabase<Record<string, never>>} db
+ * @param {Table} inputTable
+ * @param {string} runId
+ * @returns {Effect.Effect<Record<string, unknown> | undefined, SmithersError>}
+ */
+export function loadInput(db, inputTable, runId) {
+    const cols = getTableColumns(inputTable);
+    const runIdCol = cols.runId;
+    if (!runIdCol) {
+        throw new SmithersError("DB_MISSING_COLUMNS", "schema.input must include runId column");
+    }
+    return Effect.tryPromise({
+        try: () => db.select().from(inputTable).where(eq(runIdCol, runId)).limit(1),
+        catch: (cause) => toSmithersError(cause, "load input", {
+            code: "DB_QUERY_FAILED",
+            details: { runId },
+        }),
+    }).pipe(Effect.map((rows) => rows[0]), Effect.annotateLogs({ runId }), Effect.withLogSpan("db:load-input"));
+}

package/src/loadOutputsEffect.js

@@ -0,0 +1,87 @@
+import { eq, getTableName } from "drizzle-orm";
+import { getTableColumns } from "drizzle-orm/utils";
+import { Effect, Option } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/** @typedef {import("@smithers-orchestrator/driver/OutputSnapshot").OutputSnapshot} OutputSnapshot */
+/** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} BunSQLiteDatabase */
+/** @typedef {import("drizzle-orm").Table} Table */
+
+/**
+ * @param {Table} table
+ * @returns {string[]}
+ */
+function getBooleanColumnKeys(table) {
+    try {
+        const cols = getTableColumns(table);
+        const keys = [];
+        for (const [key, col] of Object.entries(cols)) {
+            const c = /** @type {Record<string, unknown> & { config?: { mode?: string }; mapFromDriverValue?: unknown }} */ (/** @type {unknown} */ (col));
+            const mapFn = /** @type {{ toString?: () => string } | undefined} */ (c?.mapFromDriverValue);
+            if (c?.columnType === "SQLiteBoolean" || c?.config?.mode === "boolean" || c?.mode === "boolean" || mapFn?.toString?.().includes("Boolean") || (c?.dataType === "boolean")) {
+                keys.push(key);
+            }
+        }
+        return keys;
+    } catch {
+        return [];
+    }
+}
+/**
+ * @param {ReadonlyArray<Record<string, unknown>>} rows
+ * @param {readonly string[]} boolKeys
+ * @returns {Array<Record<string, unknown>>}
+ */
+function coerceBooleanColumns(rows, boolKeys) {
+    if (boolKeys.length === 0) return rows.slice();
+    return rows.map((row) => {
+        if (!row) return row;
+        /** @type {Record<string, unknown>} */
+        const patched = { ...row };
+        for (const key of boolKeys) {
+            if (key in patched && typeof patched[key] !== "boolean") {
+                patched[key] = Boolean(patched[key]);
+            }
+        }
+        return patched;
+    });
+}
+/**
+ * @param {BunSQLiteDatabase<Record<string, unknown>>} db
+ * @param {Record<string, Table | unknown>} schema
+ * @param {string} runId
+ * @returns {Effect.Effect<OutputSnapshot, SmithersError>}
+ */
+export function loadOutputs(db, schema, runId) {
+    return Effect.gen(function* () {
+        /** @type {Record<string, ReadonlyArray<Record<string, unknown>>>} */
+        const out = {};
+        for (const [key, table] of Object.entries(schema)) {
+            if (!table || typeof table !== "object") continue;
+            if (key === "input") continue;
+            const colsOpt = yield* Effect.try({
+                try: () => getTableColumns(/** @type {Table} */ (table)),
+                catch: (cause) => toSmithersError(cause, "get table columns", { code: "DB_QUERY_FAILED", details: { runId, schemaKey: key } }),
+            }).pipe(Effect.option);
+            if (Option.isNone(colsOpt)) continue;
+            const cols = colsOpt.value;
+            const runIdCol = cols.runId;
+            if (!runIdCol) continue;
+            const tableNameOpt = yield* Effect.try({
+                try: () => getTableName(/** @type {Table} */ (table)),
+                catch: (cause) => toSmithersError(cause, "get table name", { code: "DB_QUERY_FAILED", details: { runId, schemaKey: key } }),
+            }).pipe(Effect.option);
+            if (Option.isNone(tableNameOpt)) continue;
+            const tableName = tableNameOpt.value;
+            const rawRows = yield* Effect.tryPromise({
+                try: () => db.select().from(/** @type {Table} */ (table)).where(eq(runIdCol, runId)),
+                catch: (cause) => toSmithersError(cause, `load outputs ${tableName}`, { code: "DB_QUERY_FAILED", details: { runId, tableName } }),
+            });
+            const boolKeys = getBooleanColumnKeys(/** @type {Table} */ (table));
+            const rows = coerceBooleanColumns(rawRows, boolKeys);
+            out[tableName] = rows;
+            out[key] = rows;
+        }
+        return /** @type {OutputSnapshot} */ (/** @type {unknown} */ (out));
+    }).pipe(Effect.annotateLogs({ runId }), Effect.withLogSpan("db:load-outputs"));
+}

package/src/output/OutputKey.ts

@@ -0,0 +1 @@
+export type OutputKey = { runId: string; nodeId: string; iteration?: number };

package/src/output/buildKeyWhere.js

@@ -0,0 +1,17 @@
+import { and, eq } from "drizzle-orm";
+import { getKeyColumns } from "./getKeyColumns.js";
+/** @typedef {import("./OutputKey.ts").OutputKey} OutputKey */
+/** @typedef {import("drizzle-orm").Table} Table */
+
+/**
+ * @param {Table} table
+ * @param {OutputKey} key
+ */
+export function buildKeyWhere(table, key) {
+    const cols = getKeyColumns(table);
+    const clauses = [eq(cols.runId, key.runId), eq(cols.nodeId, key.nodeId)];
+    if (cols.iteration) {
+        clauses.push(eq(cols.iteration, key.iteration ?? 0));
+    }
+    return and(...clauses);
+}

package/src/output/buildOutputRow.js

@@ -0,0 +1,34 @@
+import { getTableColumns } from "drizzle-orm/utils";
+/** @typedef {import("drizzle-orm").Table} Table */
+
+/**
+ * @param {Table} table
+ * @param {string} runId
+ * @param {string} nodeId
+ * @param {number} iteration
+ * @param {unknown} payload
+ */
+export function buildOutputRow(table, runId, nodeId, iteration, payload) {
+    const cols = getTableColumns(table);
+    const keys = Object.keys(cols);
+    const hasPayload = keys.includes("payload");
+    const payloadOnly = hasPayload &&
+        keys.every((key) => key === "runId" ||
+            key === "nodeId" ||
+            key === "iteration" ||
+            key === "payload");
+    if (payloadOnly) {
+        return {
+            runId,
+            nodeId,
+            iteration,
+            payload: (payload ?? null),
+        };
+    }
+    return {
+        ...(payload ?? {}),
+        runId,
+        nodeId,
+        iteration,
+    };
+}

package/src/output/describeSchemaShape.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+import { getAgentOutputSchema } from "./getAgentOutputSchema.js";
+/** @typedef {import("drizzle-orm").Table} Table */
+
+/**
+ * @param {Table | z.ZodObject} tableOrSchema
+ * @param {z.ZodObject} [zodSchema]
+ * @returns {string}
+ */
+export function describeSchemaShape(tableOrSchema, zodSchema) {
+    const schema = zodSchema ?? (isZodSchema(tableOrSchema) ? tableOrSchema : null);
+    if (schema && typeof schema.toJSONSchema === "function") {
+        const jsonSchema = schema.toJSONSchema();
+        return JSON.stringify(jsonSchema, null, 2);
+    }
+    if (!isZodSchema(tableOrSchema)) {
+        const agentSchema = getAgentOutputSchema(tableOrSchema);
+        if (typeof agentSchema.toJSONSchema === "function") {
+            const jsonSchema = agentSchema.toJSONSchema();
+            return JSON.stringify(jsonSchema, null, 2);
+        }
+    }
+    const target = schema ?? (isZodSchema(tableOrSchema) ? tableOrSchema : getAgentOutputSchema(tableOrSchema));
+    const shape = target.shape;
+    /** @type {Record<string, string>} */
+    const fields = {};
+    for (const [key, zodType] of Object.entries(shape)) {
+        fields[key] = describeZodType(/** @type {z.ZodType} */ (zodType));
+    }
+    return JSON.stringify(fields, null, 2);
+}
+/**
+ * @param {unknown} val
+ * @returns {val is z.ZodObject}
+ */
+function isZodSchema(val) {
+    return (!!val && typeof val === "object" && "shape" in val && typeof (/** @type {{ shape: unknown }} */ (val)).shape === "object");
+}
+/**
+ * @param {z.ZodType} schema
+ * @returns {string}
+ */
+function describeZodType(schema) {
+    const internal = /** @type {{ _zod?: { def?: Record<string, unknown> } }} */ (/** @type {unknown} */ (schema));
+    if (internal._zod?.def) {
+        const def = internal._zod.def;
+        const typeName = /** @type {string} */ (def.type);
+        if (typeName === "optional" || typeName === "default" || typeName === "nullable") {
+            const inner = def.innerType ? describeZodType(/** @type {z.ZodType} */ (def.innerType)) : "unknown";
+            if (typeName === "optional") return `${inner} (optional)`;
+            if (typeName === "nullable") return `${inner} | null`;
+            return inner;
+        }
+        if (typeName === "string") return "string";
+        if (typeName === "number" || typeName === "int" || typeName === "float") return "number";
+        if (typeName === "boolean") return "boolean";
+        if (typeName === "array") {
+            const itemType = def.element ? describeZodType(/** @type {z.ZodType} */ (def.element)) : "unknown";
+            return `${itemType}[]`;
+        }
+        if (typeName === "object") return "object";
+        if (typeName === "enum") return `enum(${(/** @type {unknown[]} */ (def.values ?? [])).join(" | ")})`;
+        if (typeName === "literal") return `literal(${JSON.stringify(def.value)})`;
+        if (typeName === "union") {
+            const options = (/** @type {z.ZodType[]} */ (def.options ?? [])).map((o) => describeZodType(o));
+            return options.join(" | ");
+        }
+    }
+    return "unknown";
+}

package/src/output/getAgentOutputSchema.js

@@ -0,0 +1,13 @@
+import { createInsertSchema } from "drizzle-zod";
+import { z } from "zod";
+/**
+ * Creates a Zod schema for agent output by removing runId, nodeId, iteration
+ * (which are auto-populated by smithers)
+ */
+export function getAgentOutputSchema(table) {
+    const baseSchema = createInsertSchema(table);
+    // Remove the key columns that smithers populates automatically
+    const shape = baseSchema.shape;
+    const { runId, nodeId, iteration, ...rest } = shape;
+    return z.object(rest);
+}

package/src/output/getKeyColumns.js

@@ -0,0 +1,19 @@
+import { getTableColumns } from "drizzle-orm/utils";
+import { SmithersError } from "@smithers-orchestrator/errors/SmithersError";
+/** @typedef {import("drizzle-orm").AnyColumn} AnyColumn */
+/** @typedef {import("drizzle-orm").Table} Table */
+
+/**
+ * @param {Table} table
+ * @returns {{ runId: AnyColumn; nodeId: AnyColumn; iteration?: AnyColumn; }}
+ */
+export function getKeyColumns(table) {
+    const cols = getTableColumns(table);
+    const runId = cols.runId;
+    const nodeId = cols.nodeId;
+    const iteration = cols.iteration;
+    if (!runId || !nodeId) {
+        throw new SmithersError("DB_MISSING_COLUMNS", `Output table ${table["_"]?.name ?? ""} must include runId and nodeId columns.`);
+    }
+    return { runId, nodeId, iteration };
+}

package/src/output/index.js

@@ -0,0 +1,14 @@
+// @smithers-type-exports-begin
+/** @typedef {import("./OutputKey.ts").OutputKey} OutputKey */
+// @smithers-type-exports-end
+
+export { buildOutputRow } from "./buildOutputRow.js";
+export { stripAutoColumns } from "./stripAutoColumns.js";
+export { getKeyColumns } from "./getKeyColumns.js";
+export { buildKeyWhere } from "./buildKeyWhere.js";
+export { selectOutputRow } from "./selectOutputRowEffect.js";
+export { upsertOutputRow } from "./upsertOutputRowEffect.js";
+export { validateOutput } from "./validateOutput.js";
+export { validateExistingOutput } from "./validateExistingOutput.js";
+export { getAgentOutputSchema } from "./getAgentOutputSchema.js";
+export { describeSchemaShape } from "./describeSchemaShape.js";

package/src/output/selectOutputRowEffect.js

@@ -0,0 +1,30 @@
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { buildKeyWhere } from "./buildKeyWhere.js";
+/** @typedef {import("./OutputKey.ts").OutputKey} OutputKey */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+/** @typedef {import("drizzle-orm").Table} Table */
+/** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} BunSQLiteDatabase */
+
+/**
+ * @template T
+ * @param {BunSQLiteDatabase<Record<string, unknown>>} db
+ * @param {Table} table
+ * @param {OutputKey} key
+ * @returns {Effect.Effect<T | undefined, SmithersError>}
+ */
+export function selectOutputRow(db, table, key) {
+    const where = buildKeyWhere(table, key);
+    return Effect.tryPromise({
+        try: () => db.select().from(table).where(where).limit(1),
+        catch: (cause) => toSmithersError(cause, `select output ${table["_"]?.name ?? "output"}`, {
+            code: "DB_QUERY_FAILED",
+            details: { outputTable: table["_"]?.name ?? "output" },
+        }),
+    }).pipe(Effect.map((rows) => rows[0]), Effect.annotateLogs({
+        outputTable: table["_"]?.name ?? "output",
+        runId: key.runId,
+        nodeId: key.nodeId,
+        iteration: key.iteration ?? 0,
+    }), Effect.withLogSpan("db:select-output-row"));
+}

package/src/output/stripAutoColumns.js

@@ -0,0 +1,10 @@
+/**
+ * @param {unknown} payload
+ */
+export function stripAutoColumns(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return payload;
+    }
+    const { runId: _runId, nodeId: _nodeId, iteration: _iteration, ...rest } = payload;
+    return rest;
+}

package/src/output/upsertOutputRowEffect.js

@@ -0,0 +1,38 @@
+import { Effect } from "effect";
+import { toSmithersError } from "@smithers-orchestrator/errors/toSmithersError";
+import { withSqliteWriteRetryEffect } from "../write-retry.js";
+import { getKeyColumns } from "./getKeyColumns.js";
+/** @typedef {import("./OutputKey.ts").OutputKey} OutputKey */
+/** @typedef {import("@smithers-orchestrator/errors/SmithersError").SmithersError} SmithersError */
+/** @typedef {import("drizzle-orm").Table} Table */
+/** @typedef {import("drizzle-orm/bun-sqlite").BunSQLiteDatabase} BunSQLiteDatabase */
+
+/**
+ * @param {BunSQLiteDatabase<Record<string, unknown>>} db
+ * @param {Table} table
+ * @param {OutputKey} key
+ * @param {Record<string, unknown>} payload
+ * @returns {Effect.Effect<void, SmithersError>}
+ */
+export function upsertOutputRow(db, table, key, payload) {
+    const cols = getKeyColumns(table);
+    const values = { ...payload };
+    values.runId = key.runId;
+    values.nodeId = key.nodeId;
+    if (cols.iteration) {
+        values.iteration = key.iteration ?? 0;
+    }
+    const target = cols.iteration ? [cols.runId, cols.nodeId, cols.iteration] : [cols.runId, cols.nodeId];
+    return withSqliteWriteRetryEffect(() => Effect.tryPromise({
+        try: () => db.insert(table).values(values).onConflictDoUpdate({ target, set: values }),
+        catch: (cause) => toSmithersError(cause, `upsert output ${table["_"]?.name ?? "output"}`, {
+            code: "DB_WRITE_FAILED",
+            details: { outputTable: table["_"]?.name ?? "output" },
+        }),
+    }), { label: `upsert output ${table["_"]?.name ?? "output"}` }).pipe(Effect.asVoid, Effect.annotateLogs({
+        outputTable: table["_"]?.name ?? "output",
+        runId: key.runId,
+        nodeId: key.nodeId,
+        iteration: key.iteration ?? 0,
+    }), Effect.withLogSpan("db:upsert-output-row"));
+}

package/src/output/validateExistingOutput.js

@@ -0,0 +1,17 @@
+import { createSelectSchema } from "drizzle-zod";
+import { z } from "zod";
+/** @typedef {import("drizzle-orm").Table} Table */
+
+/**
+ * @param {Table} table
+ * @param {unknown} payload
+ * @returns {{ ok: boolean; data?: any; error?: z.ZodError; }}
+ */
+export function validateExistingOutput(table, payload) {
+    const schema = createSelectSchema(table);
+    const result = schema.safeParse(payload);
+    if (result.success) {
+        return { ok: true, data: result.data };
+    }
+    return { ok: false, error: result.error };
+}

package/src/output/validateOutput.js

@@ -0,0 +1,17 @@
+import { createInsertSchema } from "drizzle-zod";
+import { z } from "zod";
+/** @typedef {import("drizzle-orm").Table} Table */
+
+/**
+ * @param {Table} table
+ * @param {unknown} payload
+ * @returns {{ ok: boolean; data?: any; error?: z.ZodError; }}
+ */
+export function validateOutput(table, payload) {
+    const schema = createInsertSchema(table);
+    const result = schema.safeParse(payload);
+    if (result.success) {
+        return { ok: true, data: result.data };
+    }
+    return { ok: false, error: result.error };
+}

package/src/output-schema-descriptor.js

@@ -0,0 +1,163 @@
+/** @typedef {"string" | "number" | "boolean" | "object" | "array" | "null" | "unknown"} OutputSchemaFieldType */
+/** @typedef {{ name: string; type: OutputSchemaFieldType; optional: boolean; nullable: boolean; description?: string; enum?: readonly unknown[]; }} OutputSchemaFieldDescriptor */
+/** @typedef {{ fields: OutputSchemaFieldDescriptor[]; }} OutputSchemaDescriptor */
+/** @typedef {{ code: "SchemaConversionError"; field: string; construct: string; message: string; }} OutputSchemaDescriptorWarning */
+
+/**
+ * @param {{ shape?: Record<string, unknown> } & Record<string, unknown>} schema
+ * @param {{ onWarning?: (warning: OutputSchemaDescriptorWarning) => void }} [options]
+ * @returns {OutputSchemaDescriptor}
+ */
+export function buildOutputSchemaDescriptor(schema, options = {}) {
+    const shape = schema?.shape;
+    if (!shape || typeof shape !== "object" || Array.isArray(shape)) {
+        throw new Error("Output schema descriptor requires a Zod object schema.");
+    }
+    /** @type {OutputSchemaFieldDescriptor[]} */
+    const fields = [];
+    for (const [name, fieldSchema] of Object.entries(shape)) {
+        fields.push(describeField(name, fieldSchema, options));
+    }
+    return { fields };
+}
+/**
+ * @param {string} name
+ * @param {unknown} schema
+ * @param {{ onWarning?: (warning: OutputSchemaDescriptorWarning) => void }} options
+ * @returns {OutputSchemaFieldDescriptor}
+ */
+function describeField(name, schema, options) {
+    const unwrapped = unwrapSchema(schema);
+    const schemaRecord = /** @type {{ description?: unknown } | null | undefined} */ (schema && typeof schema === "object" ? schema : null);
+    const innerRecord = /** @type {{ description?: unknown } | null | undefined} */ (unwrapped.schema && typeof unwrapped.schema === "object" ? unwrapped.schema : null);
+    const description = asOptionalString(schemaRecord?.description) ?? asOptionalString(innerRecord?.description);
+    const base = describeUnwrappedType(name, unwrapped.schema, options);
+    /** @type {OutputSchemaFieldDescriptor} */
+    const field = {
+        name,
+        type: base.type,
+        optional: unwrapped.optional,
+        nullable: unwrapped.nullable,
+    };
+    if (description) field.description = description;
+    if (base.description) field.description = field.description ?? base.description;
+    if (base.enumValues) field.enum = base.enumValues;
+    return field;
+}
+/**
+ * @param {unknown} schema
+ * @returns {{ schema: unknown; optional: boolean; nullable: boolean }}
+ */
+function unwrapSchema(schema) {
+    /** @type {unknown} */
+    let current = schema;
+    let optional = false;
+    let nullable = false;
+    let guard = 0;
+    /**
+     * @param {unknown} value
+     * @returns {Record<string, unknown> | undefined}
+     */
+    const getDef = (value) => {
+        if (!value || typeof value !== "object") return undefined;
+        const inner = /** @type {{ _zod?: { def?: Record<string, unknown> } }} */ (value);
+        return inner._zod?.def;
+    };
+    let def = getDef(current);
+    while (def && guard < 32) {
+        guard += 1;
+        switch (def?.type) {
+            case "optional":
+                optional = true;
+                current = def.innerType;
+                break;
+            case "default":
+                optional = true;
+                current = def.innerType;
+                break;
+            case "nullable":
+                nullable = true;
+                current = def.innerType;
+                break;
+            case "readonly":
+            case "nonoptional":
+            case "catch":
+                current = def.innerType;
+                break;
+            case "pipe":
+                current = def.out ?? def.in ?? current;
+                break;
+            default:
+                return { schema: current, optional, nullable };
+        }
+        def = getDef(current);
+    }
+    return { schema: current, optional, nullable };
+}
+/**
+ * @param {string} field
+ * @param {unknown} schema
+ * @param {{ onWarning?: (warning: OutputSchemaDescriptorWarning) => void }} options
+ * @returns {{ type: OutputSchemaFieldType; enumValues?: readonly unknown[]; description?: string; }}
+ */
+function describeUnwrappedType(field, schema, options) {
+    const def = /** @type {Record<string, unknown> | undefined} */ (schema && typeof schema === "object" ? /** @type {{ _zod?: { def?: Record<string, unknown> } }} */ (schema)._zod?.def : undefined);
+    const typeName = asOptionalString(def?.type) ?? "unknown";
+    switch (typeName) {
+        case "string": return { type: "string" };
+        case "number":
+        case "int":
+        case "float": return { type: "number" };
+        case "boolean": return { type: "boolean" };
+        case "null": return { type: "null" };
+        case "array":
+        case "tuple":
+        case "set": return { type: "array" };
+        case "object": return { type: "object" };
+        case "record": return { type: "object", description: "Record value shape is not expanded in v1." };
+        case "map": return { type: "object", description: "Map entries are not expanded in v1." };
+        case "enum": {
+            const entries = def?.entries;
+            const enumValues = entries && typeof entries === "object" ? Object.values(entries) : [];
+            return { type: "string", ...(enumValues.length > 0 ? { enumValues } : {}) };
+        }
+        case "literal": {
+            const values = Array.isArray(def?.values) ? def.values : [];
+            if (values.length === 1 && values[0] === null) return { type: "null" };
+            if (values.length === 1 && typeof values[0] === "string") return { type: "string", enumValues: values };
+            if (values.length === 1 && typeof values[0] === "number") return { type: "number", enumValues: values };
+            if (values.length === 1 && typeof values[0] === "boolean") return { type: "boolean", enumValues: values };
+            reportUnsupported(field, typeName, options);
+            return { type: "unknown" };
+        }
+        case "unknown":
+        case "any":
+        case "void":
+        case "undefined":
+        case "never": return { type: "unknown" };
+        default:
+            reportUnsupported(field, typeName, options);
+            return { type: "unknown" };
+    }
+}
+/**
+ * @param {string} field
+ * @param {string} construct
+ * @param {{ onWarning?: (warning: OutputSchemaDescriptorWarning) => void }} options
+ * @returns {void}
+ */
+function reportUnsupported(field, construct, options) {
+    options.onWarning?.({
+        code: "SchemaConversionError",
+        field,
+        construct,
+        message: `Unsupported schema construct "${construct}" in output field "${field}".`,
+    });
+}
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function asOptionalString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}