@db3.ai/app 0.1.0-beta.1

package/dist/devtools/HttpEventDispatcher.js

@@ -0,0 +1,180 @@
+const defaultBatchSize = 25;
+const defaultFlushIntervalMs = 100;
+const defaultRetryAfterMs = 1000;
+const defaultRequestTimeoutMs = 1000;
+const defaultMaxPendingEvents = 1000;
+/**
+ * Builds the configured development event ingestion endpoint.
+ *
+ * @param env - Environment values controlling the devtools service address.
+ * @returns Absolute HTTP endpoint for event batches.
+ */
+export function devtoolsEventsUrl(env = process.env) {
+    if (env.PLATFORM_DEVTOOLS_EVENTS_URL) {
+        return env.PLATFORM_DEVTOOLS_EVENTS_URL;
+    }
+    const host = env.PLATFORM_DEVTOOLS_HOST || '127.0.0.1';
+    const port = env.PLATFORM_DEVTOOLS_API_PORT || '9998';
+    return `http://${host}:${port}/api/events`;
+}
+/**
+ * Creates a bounded, fire-and-forget HTTP dispatcher for framework events.
+ *
+ * Events are batched off the caller's stack. Failed batches are discarded and
+ * subsequent delivery pauses briefly, keeping development instrumentation from
+ * affecting application behavior when the event service is unavailable.
+ *
+ * @param options - Batching, endpoint, timeout, and test-fetch configuration.
+ * @returns Callable dispatcher with flush and close lifecycle methods.
+ */
+export function createHttpEventDispatcher(options = {}) {
+    const url = options.url ?? devtoolsEventsUrl();
+    const batchSize = positiveInteger(options.batchSize, defaultBatchSize);
+    const flushIntervalMs = positiveInteger(options.flushIntervalMs, defaultFlushIntervalMs);
+    const retryAfterMs = positiveInteger(options.retryAfterMs, defaultRetryAfterMs);
+    const requestTimeoutMs = positiveInteger(options.requestTimeoutMs, defaultRequestTimeoutMs);
+    const maxPendingEvents = positiveInteger(options.maxPendingEvents, defaultMaxPendingEvents);
+    const fetchImpl = options.fetch ?? fetch;
+    const queue = [];
+    let timer = null;
+    let inFlight = null;
+    let disabledUntil = 0;
+    let closed = false;
+    /**
+     * Clears the scheduled batch timer.
+     */
+    function clearScheduledFlush() {
+        if (!timer)
+            return;
+        clearTimeout(timer);
+        timer = null;
+    }
+    /**
+     * Schedules delivery without keeping an otherwise idle process alive.
+     *
+     * @param delayMs - Delay before the next delivery attempt.
+     */
+    function schedule(delayMs = flushIntervalMs) {
+        if (closed || timer || queue.length === 0)
+            return;
+        timer = setTimeout(() => {
+            timer = null;
+            void flushNext();
+        }, delayMs);
+        timer.unref?.();
+    }
+    /**
+     * Posts one batch and reports whether it was accepted.
+     *
+     * @param ignoreBackoff - Whether shutdown should bypass the retry pause.
+     * @returns True on accepted delivery and false when delivery was skipped or failed.
+     */
+    async function sendNextBatch(ignoreBackoff) {
+        if (queue.length === 0)
+            return true;
+        const now = Date.now();
+        if (!ignoreBackoff && now < disabledUntil) {
+            schedule(Math.max(flushIntervalMs, disabledUntil - now));
+            return false;
+        }
+        const batch = queue.splice(0, batchSize);
+        const controller = new AbortController();
+        const requestTimeout = setTimeout(() => {
+            controller.abort();
+        }, requestTimeoutMs);
+        requestTimeout.unref?.();
+        try {
+            const response = await fetchImpl(url, {
+                method: 'POST',
+                headers: {
+                    'content-type': 'application/json',
+                    ...options.headers,
+                },
+                body: JSON.stringify({
+                    events: batch,
+                }),
+                signal: controller.signal,
+            });
+            if (!response.ok) {
+                throw new Error(`Devtools event sink returned ${response.status}.`);
+            }
+            return true;
+        }
+        catch (_error) {
+            disabledUntil = Date.now() + retryAfterMs;
+            return false;
+        }
+        finally {
+            clearTimeout(requestTimeout);
+        }
+    }
+    /**
+     * Serializes delivery attempts so batches cannot overtake one another.
+     *
+     * @param ignoreBackoff - Whether to bypass a previous failure pause.
+     * @returns True when the attempted batch was accepted.
+     */
+    async function flushNext(ignoreBackoff = false) {
+        clearScheduledFlush();
+        while (inFlight) {
+            await inFlight;
+        }
+        if (queue.length === 0)
+            return true;
+        inFlight = sendNextBatch(ignoreBackoff);
+        try {
+            return await inFlight;
+        }
+        finally {
+            inFlight = null;
+            if (!closed && queue.length > 0) {
+                schedule();
+            }
+        }
+    }
+    const dispatch = ((event) => {
+        if (closed)
+            return;
+        queue.push(event);
+        while (queue.length > maxPendingEvents) {
+            queue.shift();
+        }
+        if (queue.length >= batchSize) {
+            void flushNext();
+            return;
+        }
+        schedule();
+    });
+    dispatch.flush = async () => {
+        await flushNext();
+    };
+    dispatch.close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        clearScheduledFlush();
+        if (inFlight) {
+            await inFlight;
+        }
+        while (queue.length > 0) {
+            const sent = await flushNext(true);
+            if (!sent) {
+                queue.length = 0;
+                break;
+            }
+        }
+    };
+    return dispatch;
+}
+/**
+ * Returns a positive integer or a safe fallback.
+ *
+ * @param input - Caller-provided numeric option.
+ * @param fallback - Value used for invalid input.
+ * @returns Normalized positive integer.
+ */
+function positiveInteger(input, fallback) {
+    if (!Number.isFinite(input) || Number(input) <= 0)
+        return fallback;
+    return Math.floor(Number(input));
+}

package/dist/devtools/contracts/DevtoolsEventDispatcher.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Environment values shared by framework instrumentation that streams events
+ * to the local development service.
+ */
+export interface DevtoolsEnvironment {
+    NODE_ENV?: string;
+    PLATFORM_DEVTOOLS_API_PORT?: string;
+    PLATFORM_DEVTOOLS_EVENTS_URL?: string;
+    PLATFORM_DEVTOOLS_HOST?: string;
+}
+/**
+ * Configuration for a bounded, best-effort HTTP event dispatcher.
+ */
+export interface HttpEventDispatcherOptions {
+    /** HTTP endpoint that accepts `{ events: [...] }` JSON batches. */
+    url?: string;
+    /** Maximum events sent in one request. */
+    batchSize?: number;
+    /** Maximum time an event waits before its batch is sent. */
+    flushIntervalMs?: number;
+    /** Pause before later batches are attempted after a failed request. */
+    retryAfterMs?: number;
+    /** Maximum time allowed for one ingestion request. */
+    requestTimeoutMs?: number;
+    /** Maximum unsent events retained before the oldest event is discarded. */
+    maxPendingEvents?: number;
+    /** Additional HTTP headers included with every ingestion request. */
+    headers?: Record<string, string>;
+    /** Fetch implementation used by tests or alternate runtimes. */
+    fetch?: typeof fetch;
+}
+/**
+ * Callable event sink with explicit flushing and shutdown lifecycle controls.
+ *
+ * Delivery is intentionally best-effort: a failed batch is discarded so
+ * development instrumentation cannot hold an application process open.
+ */
+export interface DevtoolsEventDispatcher<TEvent extends object> {
+    /**
+     * Queues one event for asynchronous delivery.
+     *
+     * @param event - Structured framework event to send.
+     */
+    (event: TEvent): void;
+    /**
+     * Sends the next pending batch when the dispatcher is available.
+     */
+    flush(): Promise<void>;
+    /**
+     * Stops accepting events and attempts to drain the bounded queue.
+     */
+    close(): Promise<void>;
+}

package/dist/devtools/contracts/DevtoolsEventDispatcher.js

@@ -0,0 +1 @@
+export {};

package/dist/devtools/contracts/index.d.ts

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

package/dist/devtools/contracts/index.js

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

package/dist/devtools/environment.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Returns whether instrumentation should automatically stream to local
+ * development tooling.
+ *
+ * Tests are excluded because they should opt into transports explicitly.
+ *
+ * @param environment - Current runtime environment name.
+ * @returns True for interactive local development environments.
+ */
+export declare function isInteractiveDevelopmentEnvironment(environment: string | undefined): boolean;

package/dist/devtools/environment.js

@@ -0,0 +1,14 @@
+import { isDevelopmentEnvironment } from '@db3.ai/pure';
+/**
+ * Returns whether instrumentation should automatically stream to local
+ * development tooling.
+ *
+ * Tests are excluded because they should opt into transports explicitly.
+ *
+ * @param environment - Current runtime environment name.
+ * @returns True for interactive local development environments.
+ */
+export function isInteractiveDevelopmentEnvironment(environment) {
+    const normalized = (environment || '').toLowerCase().trim();
+    return normalized !== 'test' && isDevelopmentEnvironment(normalized);
+}

package/dist/devtools/index.d.ts

@@ -0,0 +1,3 @@
+export * from './contracts/index.js';
+export * from './environment.js';
+export * from './HttpEventDispatcher.js';

package/dist/devtools/index.js

@@ -0,0 +1,3 @@
+export * from './contracts/index.js';
+export * from './environment.js';
+export * from './HttpEventDispatcher.js';

package/dist/events/Events.d.ts

@@ -0,0 +1,70 @@
+import type * as events from './contracts/index.js';
+/**
+ * Typed in-process dispatcher for application and framework events.
+ *
+ * Event classes are runtime keys, so listeners infer the correct event shape
+ * without requiring a global string-to-payload registry. Dispatch is
+ * intentionally synchronous from the caller's perspective: listeners run in
+ * registration order and asynchronous listeners are awaited.
+ *
+ * @example
+ * const unsubscribe = app().events.listen(WebsiteCrawled, async event => {
+ * 	await indexWebsite(event.websiteId);
+ * });
+ *
+ * await app().events.dispatch(new WebsiteCrawled(websiteId));
+ * unsubscribe();
+ */
+export declare class Events {
+    #private;
+    /**
+     * Registers a listener for exactly one event class.
+     *
+     * Subclasses are independent event types and do not automatically invoke
+     * listeners registered for a parent class.
+     *
+     * @param eventType - Event class used as the listener key.
+     * @param listener - Consumer invoked for subsequent event instances.
+     * @returns Idempotent function that removes this registration.
+     */
+    listen<TEvent extends object>(eventType: events.EventConstructor<TEvent>, listener: events.EventListener<TEvent>): events.EventUnsubscribe;
+    /**
+     * Registers a listener that removes itself before its first invocation.
+     *
+     * Removing the registration before calling the listener guarantees that
+     * overlapping dispatches cannot invoke the one-shot listener twice.
+     *
+     * @param eventType - Event class used as the listener key.
+     * @param listener - Consumer invoked at most once.
+     * @returns Idempotent function that removes the pending registration.
+     */
+    once<TEvent extends object>(eventType: events.EventConstructor<TEvent>, listener: events.EventListener<TEvent>): events.EventUnsubscribe;
+    /**
+     * Dispatches one class instance to its current listeners.
+     *
+     * Listeners run sequentially in registration order. If a listener throws or
+     * rejects, dispatch rejects immediately and later listeners are not invoked.
+     * Callers therefore control whether listener completion is part of their
+     * operation or should be delegated to a durable queued job.
+     *
+     * @param event - Class instance containing event data.
+     */
+    dispatch<TEvent extends object>(event: TEvent): Promise<void>;
+    /**
+     * Returns whether an event class currently has one or more listeners.
+     *
+     * @param eventType - Exact event class to inspect.
+     * @returns True when at least one listener is registered.
+     */
+    hasListeners<TEvent extends object>(eventType: events.EventConstructor<TEvent>): boolean;
+    /**
+     * Removes every listener registered for one event class.
+     *
+     * @param eventType - Exact event class whose registrations should be removed.
+     */
+    forget<TEvent extends object>(eventType: events.EventConstructor<TEvent>): void;
+    /**
+     * Removes all listener registrations owned by this dispatcher.
+     */
+    clear(): void;
+}

package/dist/events/Events.js

@@ -0,0 +1,126 @@
+/**
+ * Typed in-process dispatcher for application and framework events.
+ *
+ * Event classes are runtime keys, so listeners infer the correct event shape
+ * without requiring a global string-to-payload registry. Dispatch is
+ * intentionally synchronous from the caller's perspective: listeners run in
+ * registration order and asynchronous listeners are awaited.
+ *
+ * @example
+ * const unsubscribe = app().events.listen(WebsiteCrawled, async event => {
+ * 	await indexWebsite(event.websiteId);
+ * });
+ *
+ * await app().events.dispatch(new WebsiteCrawled(websiteId));
+ * unsubscribe();
+ */
+export class Events {
+    #listeners = new Map();
+    /**
+     * Registers a listener for exactly one event class.
+     *
+     * Subclasses are independent event types and do not automatically invoke
+     * listeners registered for a parent class.
+     *
+     * @param eventType - Event class used as the listener key.
+     * @param listener - Consumer invoked for subsequent event instances.
+     * @returns Idempotent function that removes this registration.
+     */
+    listen(eventType, listener) {
+        const key = eventType;
+        const listeners = this.#listeners.get(key) ?? new Set();
+        const storedListener = event => {
+            return listener(event);
+        };
+        let subscribed = true;
+        listeners.add(storedListener);
+        this.#listeners.set(key, listeners);
+        return () => {
+            if (!subscribed)
+                return;
+            subscribed = false;
+            listeners.delete(storedListener);
+            if (listeners.size === 0) {
+                this.#listeners.delete(key);
+            }
+        };
+    }
+    /**
+     * Registers a listener that removes itself before its first invocation.
+     *
+     * Removing the registration before calling the listener guarantees that
+     * overlapping dispatches cannot invoke the one-shot listener twice.
+     *
+     * @param eventType - Event class used as the listener key.
+     * @param listener - Consumer invoked at most once.
+     * @returns Idempotent function that removes the pending registration.
+     */
+    once(eventType, listener) {
+        let unsubscribe = () => { };
+        const oneShotListener = event => {
+            unsubscribe();
+            return listener(event);
+        };
+        unsubscribe = this.listen(eventType, oneShotListener);
+        return unsubscribe;
+    }
+    /**
+     * Dispatches one class instance to its current listeners.
+     *
+     * Listeners run sequentially in registration order. If a listener throws or
+     * rejects, dispatch rejects immediately and later listeners are not invoked.
+     * Callers therefore control whether listener completion is part of their
+     * operation or should be delegated to a durable queued job.
+     *
+     * @param event - Class instance containing event data.
+     */
+    async dispatch(event) {
+        const eventType = eventConstructor(event);
+        const listeners = this.#listeners.get(eventType);
+        if (!listeners)
+            return;
+        for (const listener of [...listeners]) {
+            await listener(event);
+        }
+    }
+    /**
+     * Returns whether an event class currently has one or more listeners.
+     *
+     * @param eventType - Exact event class to inspect.
+     * @returns True when at least one listener is registered.
+     */
+    hasListeners(eventType) {
+        return (this.#listeners.get(eventType)?.size ?? 0) > 0;
+    }
+    /**
+     * Removes every listener registered for one event class.
+     *
+     * @param eventType - Exact event class whose registrations should be removed.
+     */
+    forget(eventType) {
+        this.#listeners.delete(eventType);
+    }
+    /**
+     * Removes all listener registrations owned by this dispatcher.
+     */
+    clear() {
+        this.#listeners.clear();
+    }
+}
+/**
+ * Resolves and validates the exact runtime class for an event instance.
+ *
+ * Plain objects are rejected because every object literal shares the `Object`
+ * constructor and would therefore collapse unrelated event types together.
+ *
+ * @param event - Candidate event instance.
+ * @returns Concrete class token used to look up listeners.
+ */
+function eventConstructor(event) {
+    const prototype = Object.getPrototypeOf(event);
+    const eventType = prototype?.constructor;
+    if (typeof eventType !== 'function' || eventType === Object) {
+        throw new TypeError('Events must be class instances. Define an event class and dispatch a new instance.');
+    }
+    return eventType;
+}

package/dist/events/contracts/EventConstructor.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Runtime class token used to register a listener for one event type.
+ *
+ * The constructor is used only as an identity key. Applications create and
+ * dispatch their event instances themselves.
+ */
+export interface EventConstructor<TEvent extends object = object> {
+    /** Human-readable class name used in diagnostics and tooling. */
+    readonly name: string;
+    /** Event instance shape represented by this class token. */
+    readonly prototype: TEvent;
+}

package/dist/events/contracts/EventConstructor.js

@@ -0,0 +1 @@
+export {};

package/dist/events/contracts/EventListener.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Synchronous or asynchronous consumer of one application event type.
+ *
+ * @param event - Event instance dispatched by application or framework code.
+ */
+export type EventListener<TEvent extends object> = (event: TEvent) => void | Promise<void>;

package/dist/events/contracts/EventListener.js

@@ -0,0 +1 @@
+export {};

package/dist/events/contracts/EventUnsubscribe.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Idempotent function that removes one event listener registration.
+ */
+export type EventUnsubscribe = () => void;

package/dist/events/contracts/EventUnsubscribe.js

@@ -0,0 +1 @@
+export {};

package/dist/events/contracts/index.d.ts

@@ -0,0 +1,3 @@
+export * from './EventConstructor.js';
+export * from './EventListener.js';
+export * from './EventUnsubscribe.js';

package/dist/events/contracts/index.js

@@ -0,0 +1,3 @@
+export * from './EventConstructor.js';
+export * from './EventListener.js';
+export * from './EventUnsubscribe.js';

package/dist/events/index.d.ts

@@ -0,0 +1,2 @@
+export * from './contracts/index.js';
+export * from './Events.js';

package/dist/events/index.js

@@ -0,0 +1,2 @@
+export * from './contracts/index.js';
+export * from './Events.js';

package/dist/flows/FlowBlockRegistry.d.ts

@@ -0,0 +1,39 @@
+import type { FlowBlockDefinition, FlowBlockMetadata } from './contracts/index.js';
+/**
+ * Runtime registry resolving serialized block type names into executable functions.
+ */
+export declare class FlowBlockRegistry {
+    #private;
+    /**
+     * Creates a registry and optionally registers initial block types.
+     *
+     * @param blocks - Block definitions available to the runtime.
+     */
+    constructor(blocks?: FlowBlockDefinition[]);
+    /**
+     * Registers one executable block type.
+     *
+     * @param block - Block definition to register.
+     */
+    register(block: FlowBlockDefinition): void;
+    /**
+     * Resolves one registered block type.
+     *
+     * @param type - Serialized block type name.
+     * @returns Registered block definition or null.
+     */
+    get(type: string): FlowBlockDefinition | null;
+    /**
+     * Resolves one block type or throws a developer-facing error.
+     *
+     * @param type - Serialized block type name.
+     * @returns Registered block definition.
+     */
+    require(type: string): FlowBlockDefinition;
+    /**
+     * Returns serializable metadata for block palettes and inspectors.
+     *
+     * @returns Registered block metadata ordered by display name.
+     */
+    metadata(): FlowBlockMetadata[];
+}

package/dist/flows/FlowBlockRegistry.js

@@ -0,0 +1,66 @@
+/**
+ * Runtime registry resolving serialized block type names into executable functions.
+ */
+export class FlowBlockRegistry {
+    #blocks = new Map();
+    /**
+     * Creates a registry and optionally registers initial block types.
+     *
+     * @param blocks - Block definitions available to the runtime.
+     */
+    constructor(blocks = []) {
+        for (const block of blocks) {
+            this.register(block);
+        }
+    }
+    /**
+     * Registers one executable block type.
+     *
+     * @param block - Block definition to register.
+     */
+    register(block) {
+        const type = block.type.trim();
+        if (!type) {
+            throw new Error('Flow block type is required.');
+        }
+        if (this.#blocks.has(type)) {
+            throw new Error(`Flow block type "${type}" is already registered.`);
+        }
+        if ((block.kind ?? 'function') === 'function' && typeof block.run !== 'function') {
+            throw new Error(`Function flow block type "${type}" requires a run function.`);
+        }
+        this.#blocks.set(type, block);
+    }
+    /**
+     * Resolves one registered block type.
+     *
+     * @param type - Serialized block type name.
+     * @returns Registered block definition or null.
+     */
+    get(type) {
+        return this.#blocks.get(type) ?? null;
+    }
+    /**
+     * Resolves one block type or throws a developer-facing error.
+     *
+     * @param type - Serialized block type name.
+     * @returns Registered block definition.
+     */
+    require(type) {
+        const block = this.get(type);
+        if (!block) {
+            throw new Error(`Flow block type "${type}" is not registered.`);
+        }
+        return block;
+    }
+    /**
+     * Returns serializable metadata for block palettes and inspectors.
+     *
+     * @returns Registered block metadata ordered by display name.
+     */
+    metadata() {
+        return [...this.#blocks.values()]
+            .map(({ run: _run, ...metadata }) => metadata)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+}

package/dist/flows/FlowCompiler.d.ts

@@ -0,0 +1,26 @@
+import type { CompiledFlowDefinition, FlowDefinition, FlowExecutionDefinition } from './contracts/index.js';
+import { FlowBlockRegistry } from './FlowBlockRegistry.js';
+/**
+ * Validates serialized flow graphs and produces deterministic sequential plans.
+ */
+export declare class FlowCompiler {
+    #private;
+    private readonly blocks;
+    /**
+     * Creates a compiler backed by the executable block registry.
+     *
+     * @param blocks - Registered block types available to definitions.
+     */
+    constructor(blocks: FlowBlockRegistry);
+    /**
+     * Validates and compiles one source definition into execution order.
+     *
+     * The initial compiler deliberately accepts only one connected sequential path.
+     * Multiple port connections may exist between adjacent blocks, but branching,
+     * merging, and cycles are rejected until their runtime semantics are explicit.
+     *
+     * @param definition - Parsed flow definition or durable execution snapshot.
+     * @returns Validated sequential execution plan.
+     */
+    compile(definition: FlowDefinition | FlowExecutionDefinition): CompiledFlowDefinition;
+}