@db3.ai/app 0.1.0-beta.1

package/dist/flows/contracts/index.js

@@ -0,0 +1,7 @@
+export * from './FlowBlock.js';
+export * from './FlowCompiler.js';
+export * from './FlowDefinition.js';
+export * from './FlowDefinitionStore.js';
+export * from './FlowRun.js';
+export * from './FlowValue.js';
+export * from './FlowsService.js';

package/dist/flows/defineBlock.d.ts

@@ -0,0 +1,18 @@
+import type { FlowBlockDefinition, FlowValues } from './contracts/index.js';
+/**
+ * Preserves generic block input, output, and configuration types while exposing
+ * the plain one-file block contract used by the runtime.
+ *
+ * @param definition - Executable block definition.
+ * @returns The same definition with its inferred generic types intact.
+ *
+ * @example
+ * export default defineBlock({
+ * 	type: 'text.uppercase',
+ * 	name: 'Uppercase',
+ * 	inputs: { text: { type: 'string', required: true } },
+ * 	outputs: { text: { type: 'string', required: true } },
+ * 	run: input => ({ text: input.text.toUpperCase() }),
+ * });
+ */
+export declare function defineBlock<TInput extends FlowValues, TOutput extends FlowValues, TConfig extends FlowValues = FlowValues>(definition: FlowBlockDefinition<TInput, TOutput, TConfig>): FlowBlockDefinition<TInput, TOutput, TConfig>;

package/dist/flows/defineBlock.js

@@ -0,0 +1,19 @@
+/**
+ * Preserves generic block input, output, and configuration types while exposing
+ * the plain one-file block contract used by the runtime.
+ *
+ * @param definition - Executable block definition.
+ * @returns The same definition with its inferred generic types intact.
+ *
+ * @example
+ * export default defineBlock({
+ * 	type: 'text.uppercase',
+ * 	name: 'Uppercase',
+ * 	inputs: { text: { type: 'string', required: true } },
+ * 	outputs: { text: { type: 'string', required: true } },
+ * 	run: input => ({ text: input.text.toUpperCase() }),
+ * });
+ */
+export function defineBlock(definition) {
+    return definition;
+}

package/dist/flows/drivers/FileFlowDefinitionStore.d.ts

@@ -0,0 +1,53 @@
+import type { FlowDefinition, FlowDefinitionStore, FlowDefinitionSummary, FlowDefinitionWriteOptions, StoredFlowDefinition } from '../contracts/index.js';
+/**
+ * Options for a Git-friendly file definition provider.
+ */
+export interface FileFlowDefinitionStoreOptions {
+    /** Directory containing `flow.json` or `*.flow.json` definitions. */
+    root: string;
+}
+/**
+ * Error thrown when a save would overwrite a newer definition revision.
+ */
+export declare class FlowDefinitionConflictError extends Error {
+    readonly id: string;
+    /**
+     * Creates a revision conflict error.
+     *
+     * @param id - Flow definition ULID.
+     */
+    constructor(id: string);
+}
+/**
+ * Stores source-of-truth flow definitions as deterministic project JSON files.
+ */
+export declare class FileFlowDefinitionStore implements FlowDefinitionStore {
+    #private;
+    /**
+     * Creates a file definition provider rooted inside one project.
+     *
+     * @param options - File provider options.
+     */
+    constructor(options: FileFlowDefinitionStoreOptions);
+    /**
+     * Lists every readable definition beneath the configured root.
+     *
+     * @returns Flow summaries ordered by name.
+     */
+    list(): Promise<FlowDefinitionSummary[]>;
+    /**
+     * Loads one definition by its stable flow ULID.
+     *
+     * @param id - Flow ULID.
+     * @returns Stored definition or null.
+     */
+    read(id: string): Promise<StoredFlowDefinition | null>;
+    /**
+     * Creates or atomically replaces one deterministic JSON definition file.
+     *
+     * @param definition - Definition to persist.
+     * @param options - Optional expected revision and creation path.
+     * @returns Stored definition metadata after writing.
+     */
+    write(definition: FlowDefinition, options?: FlowDefinitionWriteOptions): Promise<StoredFlowDefinition>;
+}

package/dist/flows/drivers/FileFlowDefinitionStore.js

@@ -0,0 +1,313 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, writeFile } from 'node:fs/promises';
+import { basename, dirname, relative, resolve, sep } from 'node:path';
+/**
+ * Error thrown when a save would overwrite a newer definition revision.
+ */
+export class FlowDefinitionConflictError extends Error {
+    id;
+    /**
+     * Creates a revision conflict error.
+     *
+     * @param id - Flow definition ULID.
+     */
+    constructor(id) {
+        super(`Flow definition "${id}" changed after it was loaded.`);
+        this.id = id;
+        this.name = 'FlowDefinitionConflictError';
+    }
+}
+/**
+ * Stores source-of-truth flow definitions as deterministic project JSON files.
+ */
+export class FileFlowDefinitionStore {
+    #root;
+    /**
+     * Creates a file definition provider rooted inside one project.
+     *
+     * @param options - File provider options.
+     */
+    constructor(options) {
+        this.#root = resolve(options.root);
+    }
+    /**
+     * Lists every readable definition beneath the configured root.
+     *
+     * @returns Flow summaries ordered by name.
+     */
+    async list() {
+        const definitions = await this.#readAll();
+        return definitions
+            .map(stored => ({
+            id: stored.definition.id,
+            name: stored.definition.name,
+            description: stored.definition.description,
+            inputs: structuredClone(stored.definition.inputs),
+            outputs: structuredClone(stored.definition.outputs),
+            revision: stored.revision,
+            path: stored.path,
+        }))
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    /**
+     * Loads one definition by its stable flow ULID.
+     *
+     * @param id - Flow ULID.
+     * @returns Stored definition or null.
+     */
+    async read(id) {
+        const matches = (await this.#readAll()).filter(stored => stored.definition.id === id);
+        if (matches.length > 1) {
+            throw new Error(`Flow definition id "${id}" is duplicated in the file store.`);
+        }
+        return matches[0] ?? null;
+    }
+    /**
+     * Creates or atomically replaces one deterministic JSON definition file.
+     *
+     * @param definition - Definition to persist.
+     * @param options - Optional expected revision and creation path.
+     * @returns Stored definition metadata after writing.
+     */
+    async write(definition, options = {}) {
+        const storedDefinitions = await this.#readAll();
+        const existing = storedDefinitions.find(stored => stored.definition.id === definition.id) ?? null;
+        if (options.expectedRevision && existing?.revision !== options.expectedRevision) {
+            throw new FlowDefinitionConflictError(definition.id);
+        }
+        if (options.expectedRevision && !existing) {
+            throw new FlowDefinitionConflictError(definition.id);
+        }
+        const path = existing?.path
+            ?? normalizeRelativePath(options.path ?? `${slugify(definition.name)}/flow.json`);
+        const occupied = storedDefinitions.find(stored => stored.path === path && stored.definition.id !== definition.id);
+        if (occupied) {
+            throw new Error(`Flow definition path "${path}" is already used by "${occupied.definition.id}".`);
+        }
+        const absolutePath = this.#resolvePath(path);
+        const content = serializeDefinition(definition);
+        const temporaryPath = resolve(dirname(absolutePath), `.${basename(absolutePath)}.${process.pid}.${Date.now()}.tmp`);
+        await mkdir(dirname(absolutePath), { recursive: true });
+        await writeFile(temporaryPath, content, 'utf8');
+        await rename(temporaryPath, absolutePath);
+        return {
+            definition: structuredClone(definition),
+            revision: revisionFor(content),
+            path,
+        };
+    }
+    /**
+     * Reads and parses every matching definition file beneath the root.
+     *
+     * @returns Stored definitions with provider paths and content revisions.
+     */
+    async #readAll() {
+        const paths = await findDefinitionFiles(this.#root);
+        const definitions = await Promise.all(paths.map(path => this.#readPath(path)));
+        const ids = new Set();
+        for (const stored of definitions) {
+            if (ids.has(stored.definition.id)) {
+                throw new Error(`Flow definition id "${stored.definition.id}" is duplicated in the file store.`);
+            }
+            ids.add(stored.definition.id);
+        }
+        return definitions;
+    }
+    /**
+     * Reads one definition file and attaches revision metadata.
+     *
+     * @param absolutePath - Absolute definition file path.
+     * @returns Parsed definition with provider metadata.
+     */
+    async #readPath(absolutePath) {
+        const content = await readFile(absolutePath, 'utf8');
+        let parsed;
+        try {
+            parsed = JSON.parse(content);
+        }
+        catch (error) {
+            throw new Error(`Invalid flow JSON at "${relative(this.#root, absolutePath)}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+        assertDefinitionEnvelope(parsed, relative(this.#root, absolutePath));
+        return {
+            definition: parsed,
+            revision: revisionFor(content),
+            path: relative(this.#root, absolutePath).split(sep).join('/'),
+        };
+    }
+    /**
+     * Resolves and contains a provider-relative path beneath the configured root.
+     *
+     * @param path - Provider-relative definition path.
+     * @returns Contained absolute filesystem path.
+     */
+    #resolvePath(path) {
+        const absolutePath = resolve(this.#root, normalizeRelativePath(path));
+        if (absolutePath !== this.#root && !absolutePath.startsWith(`${this.#root}${sep}`)) {
+            throw new Error('Flow definition path must remain inside the configured root.');
+        }
+        return absolutePath;
+    }
+}
+/**
+ * Finds definition files recursively while tolerating an absent root directory.
+ *
+ * @param root - Absolute directory to scan.
+ * @returns Sorted matching definition paths.
+ */
+async function findDefinitionFiles(root) {
+    let entries;
+    try {
+        entries = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isMissingPathError(error))
+            return [];
+        throw error;
+    }
+    const paths = [];
+    for (const entry of entries) {
+        const path = resolve(root, entry.name);
+        if (entry.isDirectory()) {
+            paths.push(...await findDefinitionFiles(path));
+            continue;
+        }
+        if (entry.isFile() && (entry.name === 'flow.json' || entry.name.endsWith('.flow.json'))) {
+            paths.push(path);
+        }
+    }
+    return paths.sort();
+}
+/**
+ * Serializes a definition with deterministic object-key ordering and tab indentation.
+ *
+ * @param definition - Source definition to serialize.
+ * @returns Git-friendly JSON content ending in a newline.
+ */
+function serializeDefinition(definition) {
+    return `${JSON.stringify(orderDefinition(definition), null, '\t')}\n`;
+}
+/**
+ * Applies a readable stable property order to a source definition.
+ *
+ * @param definition - Definition to normalize for source control.
+ * @returns Definition-shaped object with stable property order.
+ */
+function orderDefinition(definition) {
+    return {
+        schemaVersion: definition.schemaVersion,
+        id: definition.id,
+        name: definition.name,
+        ...(definition.description ? { description: definition.description } : {}),
+        inputs: sortRecord(definition.inputs),
+        outputs: sortRecord(definition.outputs),
+        blocks: definition.blocks.map(block => ({
+            id: block.id,
+            type: block.type,
+            ...(block.name ? { name: block.name } : {}),
+            ...(block.flowId ? { flowId: block.flowId } : {}),
+            ...(block.config ? { config: sortRecord(block.config) } : {}),
+            position: {
+                x: Math.round(block.position.x),
+                y: Math.round(block.position.y),
+            },
+        })),
+        connections: definition.connections.map(connection => ({
+            id: connection.id,
+            sourceBlockId: connection.sourceBlockId,
+            sourcePort: connection.sourcePort,
+            targetBlockId: connection.targetBlockId,
+            targetPort: connection.targetPort,
+        })),
+    };
+}
+/**
+ * Sorts record keys recursively while preserving array order.
+ *
+ * @param record - Record to normalize.
+ * @returns Record with stable key ordering.
+ */
+function sortRecord(record) {
+    return Object.fromEntries(Object.entries(record)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, value]) => [key, sortValue(value)]));
+}
+/**
+ * Normalizes nested configuration and schema values for deterministic output.
+ *
+ * @param value - Unknown nested value.
+ * @returns Recursively ordered value.
+ */
+function sortValue(value) {
+    if (Array.isArray(value))
+        return value.map(sortValue);
+    if (!value || typeof value !== 'object')
+        return value;
+    return sortRecord(value);
+}
+/**
+ * Calculates the optimistic-concurrency revision for exact file content.
+ *
+ * @param content - Exact serialized definition content.
+ * @returns SHA-256 hexadecimal content revision.
+ */
+function revisionFor(content) {
+    return createHash('sha256').update(content).digest('hex');
+}
+/**
+ * Produces a readable provider path segment from a flow name.
+ *
+ * @param name - Human-readable flow name.
+ * @returns Safe lowercase path segment.
+ */
+function slugify(name) {
+    const slug = name
+        .toLowerCase()
+        .trim()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '');
+    return slug || 'flow';
+}
+/**
+ * Rejects absolute and parent-traversing provider paths.
+ *
+ * @param path - Candidate provider-relative path.
+ * @returns Normalized safe definition path.
+ */
+function normalizeRelativePath(path) {
+    const normalized = path.replaceAll('\\', '/').replace(/^\.\//, '');
+    if (!normalized || normalized.startsWith('/') || normalized.split('/').includes('..')) {
+        throw new Error('Flow definition path must be a safe relative path.');
+    }
+    if (!(normalized.endsWith('/flow.json') || normalized.endsWith('.flow.json'))) {
+        throw new Error('Flow definition files must be named flow.json or end with .flow.json.');
+    }
+    return normalized;
+}
+/**
+ * Checks the basic envelope required before treating parsed JSON as a definition.
+ *
+ * @param value - Parsed JSON value.
+ * @param path - Provider path used in validation errors.
+ */
+function assertDefinitionEnvelope(value, path) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Flow definition at "${path}" must be an object.`);
+    }
+    const definition = value;
+    if (definition.schemaVersion !== 1 || typeof definition.id !== 'string' || typeof definition.name !== 'string') {
+        throw new Error(`Flow definition at "${path}" has an invalid version, id, or name.`);
+    }
+    if (!Array.isArray(definition.blocks) || !Array.isArray(definition.connections)) {
+        throw new Error(`Flow definition at "${path}" requires block and connection arrays.`);
+    }
+}
+/**
+ * Narrows filesystem errors representing an absent directory.
+ *
+ * @param error - Unknown filesystem failure.
+ * @returns True when the error reports a missing path.
+ */
+function isMissingPathError(error) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
+}

package/dist/flows/drivers/index.d.ts

@@ -0,0 +1 @@
+export * from './FileFlowDefinitionStore.js';

package/dist/flows/drivers/index.js

@@ -0,0 +1 @@
+export * from './FileFlowDefinitionStore.js';

package/dist/flows/errors.d.ts

@@ -0,0 +1,8 @@
+import type { FlowErrorSnapshot } from './contracts/index.js';
+/**
+ * Converts an unknown thrown value into a JSON-safe durable error snapshot.
+ *
+ * @param error - Unknown thrown value.
+ * @returns Structured error suitable for run and step models.
+ */
+export declare function flowErrorSnapshot(error: unknown): FlowErrorSnapshot;

package/dist/flows/errors.js

@@ -0,0 +1,19 @@
+/**
+ * Converts an unknown thrown value into a JSON-safe durable error snapshot.
+ *
+ * @param error - Unknown thrown value.
+ * @returns Structured error suitable for run and step models.
+ */
+export function flowErrorSnapshot(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name || 'Error',
+            message: error.message,
+            ...(error.stack ? { stack: error.stack } : {}),
+        };
+    }
+    return {
+        name: 'Error',
+        message: String(error),
+    };
+}

package/dist/flows/index.d.ts

@@ -0,0 +1,13 @@
+export * from './constants.js';
+export * from './blocks/index.js';
+export * from './contracts/index.js';
+export * from './defineBlock.js';
+export * from './drivers/index.js';
+export * from './errors.js';
+export * from './FlowBlockRegistry.js';
+export * from './FlowCompiler.js';
+export * from './FlowDefinitionError.js';
+export * from './Flows.js';
+export * from './FlowStepJob.js';
+export * from './FlowValueValidator.js';
+export * from './models/index.js';

package/dist/flows/index.js

@@ -0,0 +1,13 @@
+export * from './constants.js';
+export * from './blocks/index.js';
+export * from './contracts/index.js';
+export * from './defineBlock.js';
+export * from './drivers/index.js';
+export * from './errors.js';
+export * from './FlowBlockRegistry.js';
+export * from './FlowCompiler.js';
+export * from './FlowDefinitionError.js';
+export * from './Flows.js';
+export * from './FlowStepJob.js';
+export * from './FlowValueValidator.js';
+export * from './models/index.js';

package/dist/flows/models/FlowRun.d.ts

@@ -0,0 +1,55 @@
+import { ActiveRecord, type FieldBuilder } from '../../db/index.js';
+import type { EntityRef } from '../../db/fields/LinkField.js';
+import { type FlowReplayDefinition, type FlowRunStatus } from '../constants.js';
+import type { FlowErrorSnapshot, FlowExecutionDefinition, FlowValues } from '../contracts/index.js';
+/**
+ * Durable invocation of one immutable flow definition snapshot.
+ */
+export declare class FlowRun extends ActiveRecord {
+    static table: string;
+    static primaryKey: string;
+    static labelFields: string[];
+    static comment: string;
+    /**
+     * Defines persisted flow-run identity, snapshot, lifecycle, and result fields.
+     *
+     * @param field - ActiveRecord field builder.
+     * @returns Flow run field definitions.
+     */
+    static fields(field: FieldBuilder): {
+        id: import("../../db/index.js").UlidField;
+        flowId: import("../../db/index.js").StringField;
+        flowName: import("../../db/index.js").StringField;
+        status: import("../../db/index.js").ChoiceStringField;
+        replayDefinition: import("../../db/index.js").ChoiceStringField;
+        definitionRevision: import("../../db/index.js").StringField;
+        definitionSnapshot: import("../../db/index.js").JsonStringField<FlowExecutionDefinition>;
+        input: import("../../db/index.js").JsonStringField<FlowValues>;
+        output: import("../../db/index.js").JsonStringField<FlowValues>;
+        error: import("../../db/index.js").JsonStringField<FlowErrorSnapshot>;
+        replayOf: import("../../db/index.js").LinkField<FlowRun>;
+        parentRun: import("../../db/index.js").LinkField<FlowRun>;
+        parentBlockId: import("../../db/index.js").StringField;
+        startedAt: import("../../db/index.js").TimestampField;
+        completedAt: import("../../db/index.js").TimestampField;
+        createdAt: import("../../db/index.js").TimestampField;
+        updatedAt: import("../../db/index.js").TimestampField;
+    };
+    id: string | null;
+    flowId: string | null;
+    flowName: string | null;
+    status: FlowRunStatus | null;
+    replayDefinition: FlowReplayDefinition | null;
+    definitionRevision: string | null;
+    definitionSnapshot: FlowExecutionDefinition | null;
+    input: FlowValues | null;
+    output: FlowValues | null;
+    error: FlowErrorSnapshot | null;
+    replayOf: EntityRef<FlowRun> | null;
+    parentRun: EntityRef<FlowRun> | null;
+    parentBlockId: string | null;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    createdAt: Date | null;
+    updatedAt: Date | null;
+}

package/dist/flows/models/FlowRun.js

@@ -0,0 +1,126 @@
+import { ActiveRecord } from '../../db/index.js';
+import { FLOW_REPLAY_DEFINITION, FLOW_RUN_STATUS } from '../constants.js';
+/**
+ * Durable invocation of one immutable flow definition snapshot.
+ */
+export class FlowRun extends ActiveRecord {
+    static table = 'flow_runs';
+    static primaryKey = 'id';
+    static labelFields = ['flowName', 'status'];
+    static comment = 'Durable flow invocation and immutable definition snapshot used for observability and replay.';
+    /**
+     * Defines persisted flow-run identity, snapshot, lifecycle, and result fields.
+     *
+     * @param field - ActiveRecord field builder.
+     * @returns Flow run field definitions.
+     */
+    static fields(field) {
+        return {
+            id: field.ulid({
+                comment: 'Stable flow run ULID.',
+            }),
+            flowId: field.string({
+                column: 'flow_id',
+                required: true,
+                length: 26,
+                maxLength: 26,
+                index: true,
+                comment: 'Stable ULID from the source flow definition.',
+            }),
+            flowName: field.string({
+                column: 'flow_name',
+                required: true,
+                length: 255,
+                maxLength: 255,
+                comment: 'Flow name captured when this run was created.',
+            }),
+            status: field.choice({
+                required: true,
+                choices: Object.values(FLOW_RUN_STATUS),
+                default: FLOW_RUN_STATUS.queued,
+                length: 20,
+                maxLength: 20,
+                index: true,
+                comment: 'Current durable lifecycle state for the flow invocation.',
+            }),
+            replayDefinition: field.choice({
+                column: 'replay_definition',
+                required: false,
+                choices: Object.values(FLOW_REPLAY_DEFINITION),
+                length: 20,
+                maxLength: 20,
+                comment: 'Definition source selected when this run replays an earlier invocation.',
+            }),
+            definitionRevision: field.string({
+                column: 'definition_revision',
+                required: true,
+                length: 64,
+                maxLength: 64,
+                index: true,
+                comment: 'SHA-256 revision of the source definition used for this run.',
+            }),
+            definitionSnapshot: field.jsonLongText({
+                column: 'definition_snapshot',
+                required: true,
+                comment: 'Immutable normalized flow definition executed by this run.',
+            }),
+            input: field.jsonLongText({
+                required: true,
+                comment: 'Validated public input supplied to the root block.',
+            }),
+            output: field.jsonLongText({
+                required: false,
+                comment: 'Validated public output produced by the terminal block.',
+            }),
+            error: field.jsonLongText({
+                required: false,
+                comment: 'Structured terminal error when the run fails.',
+            }),
+            replayOf: field.link(() => FlowRun, {
+                column: 'replay_of_run_id',
+                required: false,
+                onDelete: 'SET NULL',
+                index: true,
+                comment: 'Earlier flow run replayed by this invocation, when applicable.',
+            }),
+            parentRun: field.link(() => FlowRun, {
+                column: 'parent_run_id',
+                required: false,
+                onDelete: 'CASCADE',
+                index: true,
+                comment: 'Parent flow run waiting for this nested invocation.',
+            }),
+            parentBlockId: field.string({
+                column: 'parent_block_id',
+                required: false,
+                length: 26,
+                maxLength: 26,
+                index: true,
+                comment: 'Flow-backed block occurrence in the parent run.',
+            }),
+            startedAt: field.timestamp({
+                column: 'started_at',
+                precision: 3,
+                index: true,
+                comment: 'Time the first block began execution.',
+            }),
+            completedAt: field.timestamp({
+                column: 'completed_at',
+                precision: 3,
+                index: true,
+                comment: 'Time the run completed or failed.',
+            }),
+            createdAt: field.timestamp({
+                column: 'created_at',
+                precision: 3,
+                auto: 'create',
+                index: true,
+            }),
+            updatedAt: field.timestamp({
+                column: 'updated_at',
+                precision: 3,
+                auto: 'update',
+            }),
+        };
+    }
+}