yaml-flow 8.8.7 → 8.9.0

package/lib/board-live-cards-public.d.cts

@@ -1,4 +1,326 @@
-import './storage-interface-D-iEiTJA.cjs';
-export { p as BOARD_GRAPH_KEY, B as BoardChangeNotification, l as BoardLiveCardsNonCorePublic, c as BoardLiveCardsPublic, z as BoardLiveCardsPublicOptions, d as BoardNonCorePlatformAdapter, e as BoardPlatformAdapter, C as CommandInput, a as CommandResult, E as EMPTY_CONFIG, q as SNAPSHOT_SCHEMA_VERSION_V1, r as createBoardLiveCardsNonCorePublic, s as createBoardLiveCardsPublic } from './board-live-cards-public-BT5HrgqZ.cjs';
-import './execution-refs.cjs';
+import { K as KVStorage, B as BlobStorage, S as ScratchStorage, A as ArchiveFactory, Q as QueueStorage, g as AtomicRelayLock, a as KindValueRef } from './storage-interface-DogVPooM.cjs';
+import { C as ChatStorage, B as BoardCallbackTransport } from './board-callback-transport-kP0K6UMq.cjs';
+import { ExecutionRef } from './execution-refs.cjs';
+import { k as BoardStatusObject, L as LiveCard, h as NotificationEmitter, J as JournalStorageAdapter, B as BoardChangeNotification } from './board-live-cards-lib-DVh3t9NT.cjs';
+export { l as BOARD_GRAPH_KEY, E as EMPTY_CONFIG, S as SNAPSHOT_SCHEMA_VERSION_V1 } from './board-live-cards-lib-DVh3t9NT.cjs';
 import './types-BBhqYGhE.cjs';
+
+/**
+ * board-live-cards-public.ts
+ *
+ * Platform-free public API layer for the board-live-cards system.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * LAYER DIAGRAM
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   board-live-cards-cli.ts       (THIN — arg parse → call public → print JSON)
+ *           ↓ calls
+ *   board-live-cards-public.ts    (THIS FILE — facade, all logic, no platform code)
+ *           ↓ depends on injected
+ *   board-live-cards-lib.ts       (pure domain — stores, graph, codecs)
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PLATFORM ADAPTERS  (injected into BoardPlatformAdapter)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   Node/FS         createFsBoardPlatformAdapter(baseRef, cliDir)
+ *   Azure Functions createAzureBoardPlatformAdapter(baseRef, containerClient, …)
+ *   Firebase Fn     createFirebaseBoardPlatformAdapter(baseRef, firestoreDb, …)
+ *   In-memory/test  createInMemoryBoardPlatformAdapter(baseRef)
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * USAGE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const board = createBoardLiveCardsPublic(baseRef, adapter);
+ *   const status = board.status();
+ */
+
+type CommandInput = {
+    params?: Record<string, string | number | boolean>;
+    body?: unknown;
+};
+type CommandResult<T = undefined> = (T extends undefined ? {
+    status: 'success';
+} : {
+    status: 'success';
+    data: T;
+}) | {
+    status: 'fail';
+    error: string;
+} | {
+    status: 'error';
+    error: string;
+};
+interface BoardPlatformAdapter {
+    /**
+     * KV storage factory — scoped by namespace.
+     * Namespaces used by the public layer:
+     *   'state-snapshot'     — board graph snapshot (StateSnapshotStorageAdapter, built internally)
+     *   'config'             — board configuration (.task-executor, .chat-handler, .chat-handler-flow, .card-store-ref)
+     *   'card-upsert'        — card upsert dedup index
+     *   'execution-requests' — queued execution requests (keyed by journalId)
+     *   'card-runtime'       — card runtime state snapshots
+     *   'output'             — published board status + card computed outputs
+     */
+    kvStorage(namespace: string): KVStorage;
+    /**
+     * Build a KVStorage rooted at the given ref.
+     * Used by the public layer for both card store and outputs store routing.
+     *   FS:          createFsKvStorage(parseRef(ref).value)
+     *   localStorage: createLocalStorageKvStorage(parseRef(ref).value)
+     */
+    kvStorageForRef(ref: string): KVStorage;
+    /**
+     * Blob storage factory — scoped by namespace.
+     * Namespaces used by the public layer:
+     *   ''        — root-scoped blob access (for resolving arbitrary KindValueRef blobs)
+     */
+    blobStorage(namespace: string): BlobStorage;
+    blobStorageForRef(ref: string): BlobStorage;
+    chatStorageForRef(ref: string): ChatStorage;
+    /**
+     * Ephemeral scratch store for transient I/O staging (probe in/out/err,
+     * dispatchExecution argv/out/err). Default scope is board-local; if the
+     * config has a 'scratch-store-ref' set, scratchStorageForRef(ref) is used
+     * instead.
+     */
+    scratchStorage(): ScratchStorage;
+    scratchStorageForRef(ref: string): ScratchStorage;
+    /**
+     * Archive factory — long-lived tracking / audit store. Default scope is
+     * board-local; if the config has an 'archive-store-ref' set,
+     * archiveFactoryForRef(ref) is used instead so archives can live on a
+     * different backend / path than the main board runtime.
+     */
+    archiveFactory(): ArchiveFactory;
+    archiveFactoryForRef(ref: string): ArchiveFactory;
+    /**
+     * Journal storage adapter (append-only log).
+     * Uses the lib's JournalStorageAdapter interface.
+     * One journal per board — no namespace parameter needed.
+     */
+    journalAdapter(): JournalStorageAdapter;
+    journalAdapterForRef(ref: string): JournalStorageAdapter;
+    /**
+     * Queue storage lane resolved from an explicit queue store ref.
+     * The adapter chooses the backend from the ref; lane chooses the internal queue.
+     */
+    queueStorageForRef(ref: string, lane: string): QueueStorage;
+    /**
+     * AtomicRelayLock — non-blocking try-acquire with relay-on-busy semantics.
+     * Guards processAccumulatedEvents drain cycle.
+     *   FS:        proper-lockfile (createFsAtomicRelayLock)
+     *   Azure:     blob lease
+     *   Firestore: Firestore transaction + sentinel document
+     */
+    lock: AtomicRelayLock;
+    /**
+     * Adapter-owned callback transport used to build worker callback payloads.
+     * The board core treats callback delivery as a platform concern.
+     */
+    callbackTransport?: BoardCallbackTransport;
+    /**
+     * Generic execution dispatch — platform adapts ExecutionRef → actual transport.
+     * Public layer constructs fully-formed semantic args (source def, base_ref,
+     * callback token with selfRef baked in). Platform handles transport:
+      *   Node host adapter: may write args to temp file and may spawn a detached process
+     *   Azure: HTTP POST args as JSON body
+     *   Firebase: publishes args as pubsub message
+     */
+    dispatchExecution(ref: ExecutionRef, args: Record<string, unknown>): Promise<{
+        dispatched: boolean;
+        error?: string;
+    }>;
+    /**
+     * Whether dispatchExecution can accept a board-owned staged source output ref
+     * for this executor. When false/absent, the adapter keeps its legacy staging
+     * protocol such as scratch in/out refs for local process launch.
+     */
+    supportsDirectSourceOutput?(ref: ExecutionRef): boolean;
+    /**
+     * Resolve a blob ref to its string contents.
+     * The adapter handles the platform-specific lookup (e.g. absolute FS path vs board-relative key).
+     * Throws if the blob does not exist.
+     */
+    resolveBlob(ref: KindValueRef): string;
+    /**
+     * Compute a stable, deterministic content hash for any JSON-serializable value.
+     * Used for dedup indexes and snapshot versioning.
+     *   Node/FS: computeStableJsonHash (storage-fs-adapters)
+     *   Browser: Web Crypto subtle.digest or equivalent
+     */
+    hashFn(value: unknown): string;
+    /**
+     * Generate a random short ID (32 hex chars).
+     * Used for commit IDs and delivery tokens.
+     *   Node/FS: getHash(`${Date.now()}-${Math.random()}`).slice(0, 32)
+     *   Browser: crypto.randomUUID().replace(/-/g, '')
+     */
+    genId(): string;
+    /**
+     * Request an additional drain pass asynchronously (e.g. spawn a background process).
+     * Called as the relay continuation after each drain cycle so that events written
+     * during the cycle (e.g. task-completed appended by the card handler) are eventually
+     * processed even when the current process exits immediately after returning.
+     * Optional — if absent, no continuation is scheduled.
+     */
+    requestProcessAccumulated?(): void;
+    /**
+     * Optional cross-process board change notification publisher (named pipe, webhook, pubsub, etc.).
+     * Called once per drain cycle with the complete batch of notifications produced in that cycle.
+     */
+    publishBoardChangeNotifications?(notifications: BoardChangeNotification[]): void | Promise<void>;
+    /** Optional warn sink — defaults to no-op. */
+    onWarn?(msg: string): void;
+}
+interface BoardLiveCardsPublic {
+    init(input: CommandInput): CommandResult;
+    status(input: CommandInput): CommandResult<BoardStatusObject>;
+    getBoardRuntimeStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getCardStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string;
+    }>;
+    getOutputsStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string;
+    }>;
+    getScratchStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getChatStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getArtifactsStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getFetchedSourcesStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getConfig(input: CommandInput): CommandResult<{
+        value: unknown;
+    }>;
+    getOutputsDataObject(input: CommandInput): CommandResult;
+    getAllOutputsDataObjects(input: CommandInput): CommandResult<Record<string, unknown>>;
+    getOutputsComputedValues(input: CommandInput): CommandResult;
+    getAllOutputsComputedValues(input: CommandInput): CommandResult<Record<string, unknown>>;
+    getOutputsFetchedSources(input: CommandInput): CommandResult<Record<string, string>>;
+    getAllOutputsFetchedSources(input: CommandInput): CommandResult<Record<string, Record<string, string>>>;
+    buildSseOneShotPayload(input: CommandInput): CommandResult<BoardSseOneShotPayload>;
+    removeCard(input: CommandInput): CommandResult;
+    addCardFiles(input: CommandInput): CommandResult<{
+        cardId: string;
+        files_added: Array<{
+            idx: number;
+            entry: unknown;
+        }>;
+        notified: true;
+    }>;
+    retrigger(input: CommandInput): CommandResult;
+    processAccumulatedEvents(input: CommandInput): Promise<CommandResult>;
+    upsertCard(input: CommandInput): CommandResult;
+    taskFailed(input: CommandInput): CommandResult;
+    taskProgress(input: CommandInput): CommandResult;
+    sourceDataFetched(input: CommandInput): CommandResult;
+    sourceDataFetchFailure(input: CommandInput): CommandResult;
+}
+interface BoardSseOneShotPayload {
+    cardDefinitions: Array<Record<string, unknown>>;
+    statusSnapshot: BoardStatusObject;
+    dataObjectsByToken: Record<string, unknown>;
+    cardRuntimeById: Record<string, unknown>;
+}
+interface BoardLiveCardsPublicOptions {
+    boardRuntimeStoreRef?: string;
+    scratchStoreRef?: string;
+    taskExecutorRef?: ExecutionRef;
+    chatHandlerFlow?: unknown;
+    emitNotification?: NotificationEmitter;
+}
+declare function createBoardLiveCardsPublic(baseRef: KindValueRef, adapter: BoardPlatformAdapter, options?: BoardLiveCardsPublicOptions): BoardLiveCardsPublic;
+interface BoardNonCorePlatformAdapter extends BoardPlatformAdapter {
+    /**
+     * Invoke a task executor subcommand and return stdout.
+     * Throws on transport failure, non-zero exit, or timeout.
+     */
+    invokeExecutor(ref: ExecutionRef, subcommand: string, opts?: {
+        timeout?: number;
+        input?: string;
+    }): Promise<string>;
+    /** Schema-only card validator (no executor invocation). */
+    validateSchema(card: Record<string, unknown>): {
+        ok: boolean;
+        errors: string[];
+    };
+    /** Absolute-path blob I/O for resolving arbitrary KindValueRef blobs. */
+    absoluteBlob: BlobStorage;
+    /**
+    * Default timeouts (ms) for executor request/response calls.
+     * Each field can also be overridden per-source via source_def.timeout.
+     *
+     *   validationMs — validate-source-def, validate-card-preflight (structural, fast). Default: 10_000.
+      *   preflightMs  — source preflight executor hooks (probe-source-preflight). Default: 60_000.
+     *   probeMs      — run-source-fetch in probe/simulation paths. Default: 60_000.
+     *   describeMs   — describe-capabilities introspection. Default: 10_000.
+     */
+    executorTimeouts?: {
+        validationMs?: number;
+        preflightMs?: number;
+        probeMs?: number;
+        describeMs?: number;
+    };
+}
+interface BoardLiveCardsNonCorePublic {
+    /** body: { "card-content": <card> } — card JSON arrives via stdin; validates schema + JSONata + provides refs + source_defs (executor, if configured) */
+    validateCardPreflight(input: CommandInput): Promise<CommandResult<{
+        cardId: string;
+        isValid: boolean;
+        issues: string[];
+    }>>;
+    /** body: { "card-content": <card>, "mock-projections"?: {} }; params: sourceIdx, outRef? — card JSON arrives via stdin; no board state needed */
+    probeSourcePreflight(input: CommandInput): Promise<CommandResult>;
+    /** body: { "card-content": <card>, "mock-projections"?: {} }; params: sourceIdx, outRef? — runs the real source fetch flow as a preflight */
+    runSourcePreflight(input: CommandInput): Promise<CommandResult<{
+        bindTo: string;
+        ok: boolean;
+        result: unknown;
+        issues: string[];
+    }>>;
+    /** body: { "card-content": <card>, "mock-fetched-sources"?: {}, "mock-requires"?: {} } — evaluates compute expressions with supplied data; no board state needed */
+    evalCardCompute(input: CommandInput): CommandResult<{
+        cardId: string;
+        ok: boolean;
+        computed_values: Record<string, unknown>;
+        errors: Array<{
+            bindTo: string;
+            error: string;
+        }>;
+    }>;
+    /** body: { "card-content": <card>, "mock-fetched-sources"?: {}, "mock-requires"?: {} } — full cycle: validate → resolve projections → probe sources → compute */
+    simulateCardCycle(input: CommandInput): Promise<CommandResult>;
+    /** no params needed */
+    describeTaskExecutorCapabilities(input: CommandInput): Promise<CommandResult>;
+    /**
+     * Write/update cards in the configured card store.
+     * body: { ops: Array<{ op: 'update', id: string, 'card-content': LiveCard }> }
+     */
+    updatesInCardStore(input: CommandInput): CommandResult;
+    /**
+     * Read cards from the configured card store by id.
+     * body: { ids: string[] }
+     */
+    readFromCardStore(input: CommandInput): CommandResult<{
+        cards: Array<{
+            id: string;
+            'card-content': LiveCard | null;
+        }>;
+    }>;
+}
+declare function createBoardLiveCardsNonCorePublic(baseRef: KindValueRef, adapter: BoardNonCorePlatformAdapter, opts?: {
+    boardRuntimeStoreRef?: string;
+    taskExecutorRef?: ExecutionRef;
+}): BoardLiveCardsNonCorePublic;
+
+export { BoardChangeNotification, type BoardLiveCardsNonCorePublic, type BoardLiveCardsPublic, type BoardLiveCardsPublicOptions, type BoardNonCorePlatformAdapter, type BoardPlatformAdapter, type BoardSseOneShotPayload, type CommandInput, type CommandResult, createBoardLiveCardsNonCorePublic, createBoardLiveCardsPublic };

package/lib/board-live-cards-public.d.ts

@@ -1,4 +1,326 @@
-import './storage-interface-D-iEiTJA.js';
-export { p as BOARD_GRAPH_KEY, B as BoardChangeNotification, l as BoardLiveCardsNonCorePublic, c as BoardLiveCardsPublic, z as BoardLiveCardsPublicOptions, d as BoardNonCorePlatformAdapter, e as BoardPlatformAdapter, C as CommandInput, a as CommandResult, E as EMPTY_CONFIG, q as SNAPSHOT_SCHEMA_VERSION_V1, r as createBoardLiveCardsNonCorePublic, s as createBoardLiveCardsPublic } from './board-live-cards-public-DSRamFm8.js';
-import './execution-refs.js';
+import { K as KVStorage, B as BlobStorage, S as ScratchStorage, A as ArchiveFactory, Q as QueueStorage, g as AtomicRelayLock, a as KindValueRef } from './storage-interface-DogVPooM.js';
+import { C as ChatStorage, B as BoardCallbackTransport } from './board-callback-transport-Bekq8Gp-.js';
+import { ExecutionRef } from './execution-refs.js';
+import { k as BoardStatusObject, L as LiveCard, h as NotificationEmitter, J as JournalStorageAdapter, B as BoardChangeNotification } from './board-live-cards-lib-iU8xOwNp.js';
+export { l as BOARD_GRAPH_KEY, E as EMPTY_CONFIG, S as SNAPSHOT_SCHEMA_VERSION_V1 } from './board-live-cards-lib-iU8xOwNp.js';
 import './types-BBhqYGhE.js';
+
+/**
+ * board-live-cards-public.ts
+ *
+ * Platform-free public API layer for the board-live-cards system.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * LAYER DIAGRAM
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   board-live-cards-cli.ts       (THIN — arg parse → call public → print JSON)
+ *           ↓ calls
+ *   board-live-cards-public.ts    (THIS FILE — facade, all logic, no platform code)
+ *           ↓ depends on injected
+ *   board-live-cards-lib.ts       (pure domain — stores, graph, codecs)
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * PLATFORM ADAPTERS  (injected into BoardPlatformAdapter)
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   Node/FS         createFsBoardPlatformAdapter(baseRef, cliDir)
+ *   Azure Functions createAzureBoardPlatformAdapter(baseRef, containerClient, …)
+ *   Firebase Fn     createFirebaseBoardPlatformAdapter(baseRef, firestoreDb, …)
+ *   In-memory/test  createInMemoryBoardPlatformAdapter(baseRef)
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * USAGE
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ *   const board = createBoardLiveCardsPublic(baseRef, adapter);
+ *   const status = board.status();
+ */
+
+type CommandInput = {
+    params?: Record<string, string | number | boolean>;
+    body?: unknown;
+};
+type CommandResult<T = undefined> = (T extends undefined ? {
+    status: 'success';
+} : {
+    status: 'success';
+    data: T;
+}) | {
+    status: 'fail';
+    error: string;
+} | {
+    status: 'error';
+    error: string;
+};
+interface BoardPlatformAdapter {
+    /**
+     * KV storage factory — scoped by namespace.
+     * Namespaces used by the public layer:
+     *   'state-snapshot'     — board graph snapshot (StateSnapshotStorageAdapter, built internally)
+     *   'config'             — board configuration (.task-executor, .chat-handler, .chat-handler-flow, .card-store-ref)
+     *   'card-upsert'        — card upsert dedup index
+     *   'execution-requests' — queued execution requests (keyed by journalId)
+     *   'card-runtime'       — card runtime state snapshots
+     *   'output'             — published board status + card computed outputs
+     */
+    kvStorage(namespace: string): KVStorage;
+    /**
+     * Build a KVStorage rooted at the given ref.
+     * Used by the public layer for both card store and outputs store routing.
+     *   FS:          createFsKvStorage(parseRef(ref).value)
+     *   localStorage: createLocalStorageKvStorage(parseRef(ref).value)
+     */
+    kvStorageForRef(ref: string): KVStorage;
+    /**
+     * Blob storage factory — scoped by namespace.
+     * Namespaces used by the public layer:
+     *   ''        — root-scoped blob access (for resolving arbitrary KindValueRef blobs)
+     */
+    blobStorage(namespace: string): BlobStorage;
+    blobStorageForRef(ref: string): BlobStorage;
+    chatStorageForRef(ref: string): ChatStorage;
+    /**
+     * Ephemeral scratch store for transient I/O staging (probe in/out/err,
+     * dispatchExecution argv/out/err). Default scope is board-local; if the
+     * config has a 'scratch-store-ref' set, scratchStorageForRef(ref) is used
+     * instead.
+     */
+    scratchStorage(): ScratchStorage;
+    scratchStorageForRef(ref: string): ScratchStorage;
+    /**
+     * Archive factory — long-lived tracking / audit store. Default scope is
+     * board-local; if the config has an 'archive-store-ref' set,
+     * archiveFactoryForRef(ref) is used instead so archives can live on a
+     * different backend / path than the main board runtime.
+     */
+    archiveFactory(): ArchiveFactory;
+    archiveFactoryForRef(ref: string): ArchiveFactory;
+    /**
+     * Journal storage adapter (append-only log).
+     * Uses the lib's JournalStorageAdapter interface.
+     * One journal per board — no namespace parameter needed.
+     */
+    journalAdapter(): JournalStorageAdapter;
+    journalAdapterForRef(ref: string): JournalStorageAdapter;
+    /**
+     * Queue storage lane resolved from an explicit queue store ref.
+     * The adapter chooses the backend from the ref; lane chooses the internal queue.
+     */
+    queueStorageForRef(ref: string, lane: string): QueueStorage;
+    /**
+     * AtomicRelayLock — non-blocking try-acquire with relay-on-busy semantics.
+     * Guards processAccumulatedEvents drain cycle.
+     *   FS:        proper-lockfile (createFsAtomicRelayLock)
+     *   Azure:     blob lease
+     *   Firestore: Firestore transaction + sentinel document
+     */
+    lock: AtomicRelayLock;
+    /**
+     * Adapter-owned callback transport used to build worker callback payloads.
+     * The board core treats callback delivery as a platform concern.
+     */
+    callbackTransport?: BoardCallbackTransport;
+    /**
+     * Generic execution dispatch — platform adapts ExecutionRef → actual transport.
+     * Public layer constructs fully-formed semantic args (source def, base_ref,
+     * callback token with selfRef baked in). Platform handles transport:
+      *   Node host adapter: may write args to temp file and may spawn a detached process
+     *   Azure: HTTP POST args as JSON body
+     *   Firebase: publishes args as pubsub message
+     */
+    dispatchExecution(ref: ExecutionRef, args: Record<string, unknown>): Promise<{
+        dispatched: boolean;
+        error?: string;
+    }>;
+    /**
+     * Whether dispatchExecution can accept a board-owned staged source output ref
+     * for this executor. When false/absent, the adapter keeps its legacy staging
+     * protocol such as scratch in/out refs for local process launch.
+     */
+    supportsDirectSourceOutput?(ref: ExecutionRef): boolean;
+    /**
+     * Resolve a blob ref to its string contents.
+     * The adapter handles the platform-specific lookup (e.g. absolute FS path vs board-relative key).
+     * Throws if the blob does not exist.
+     */
+    resolveBlob(ref: KindValueRef): string;
+    /**
+     * Compute a stable, deterministic content hash for any JSON-serializable value.
+     * Used for dedup indexes and snapshot versioning.
+     *   Node/FS: computeStableJsonHash (storage-fs-adapters)
+     *   Browser: Web Crypto subtle.digest or equivalent
+     */
+    hashFn(value: unknown): string;
+    /**
+     * Generate a random short ID (32 hex chars).
+     * Used for commit IDs and delivery tokens.
+     *   Node/FS: getHash(`${Date.now()}-${Math.random()}`).slice(0, 32)
+     *   Browser: crypto.randomUUID().replace(/-/g, '')
+     */
+    genId(): string;
+    /**
+     * Request an additional drain pass asynchronously (e.g. spawn a background process).
+     * Called as the relay continuation after each drain cycle so that events written
+     * during the cycle (e.g. task-completed appended by the card handler) are eventually
+     * processed even when the current process exits immediately after returning.
+     * Optional — if absent, no continuation is scheduled.
+     */
+    requestProcessAccumulated?(): void;
+    /**
+     * Optional cross-process board change notification publisher (named pipe, webhook, pubsub, etc.).
+     * Called once per drain cycle with the complete batch of notifications produced in that cycle.
+     */
+    publishBoardChangeNotifications?(notifications: BoardChangeNotification[]): void | Promise<void>;
+    /** Optional warn sink — defaults to no-op. */
+    onWarn?(msg: string): void;
+}
+interface BoardLiveCardsPublic {
+    init(input: CommandInput): CommandResult;
+    status(input: CommandInput): CommandResult<BoardStatusObject>;
+    getBoardRuntimeStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getCardStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string;
+    }>;
+    getOutputsStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string;
+    }>;
+    getScratchStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getChatStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getArtifactsStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getFetchedSourcesStoreRef(input: CommandInput): CommandResult<{
+        storeRef: string | null;
+    }>;
+    getConfig(input: CommandInput): CommandResult<{
+        value: unknown;
+    }>;
+    getOutputsDataObject(input: CommandInput): CommandResult;
+    getAllOutputsDataObjects(input: CommandInput): CommandResult<Record<string, unknown>>;
+    getOutputsComputedValues(input: CommandInput): CommandResult;
+    getAllOutputsComputedValues(input: CommandInput): CommandResult<Record<string, unknown>>;
+    getOutputsFetchedSources(input: CommandInput): CommandResult<Record<string, string>>;
+    getAllOutputsFetchedSources(input: CommandInput): CommandResult<Record<string, Record<string, string>>>;
+    buildSseOneShotPayload(input: CommandInput): CommandResult<BoardSseOneShotPayload>;
+    removeCard(input: CommandInput): CommandResult;
+    addCardFiles(input: CommandInput): CommandResult<{
+        cardId: string;
+        files_added: Array<{
+            idx: number;
+            entry: unknown;
+        }>;
+        notified: true;
+    }>;
+    retrigger(input: CommandInput): CommandResult;
+    processAccumulatedEvents(input: CommandInput): Promise<CommandResult>;
+    upsertCard(input: CommandInput): CommandResult;
+    taskFailed(input: CommandInput): CommandResult;
+    taskProgress(input: CommandInput): CommandResult;
+    sourceDataFetched(input: CommandInput): CommandResult;
+    sourceDataFetchFailure(input: CommandInput): CommandResult;
+}
+interface BoardSseOneShotPayload {
+    cardDefinitions: Array<Record<string, unknown>>;
+    statusSnapshot: BoardStatusObject;
+    dataObjectsByToken: Record<string, unknown>;
+    cardRuntimeById: Record<string, unknown>;
+}
+interface BoardLiveCardsPublicOptions {
+    boardRuntimeStoreRef?: string;
+    scratchStoreRef?: string;
+    taskExecutorRef?: ExecutionRef;
+    chatHandlerFlow?: unknown;
+    emitNotification?: NotificationEmitter;
+}
+declare function createBoardLiveCardsPublic(baseRef: KindValueRef, adapter: BoardPlatformAdapter, options?: BoardLiveCardsPublicOptions): BoardLiveCardsPublic;
+interface BoardNonCorePlatformAdapter extends BoardPlatformAdapter {
+    /**
+     * Invoke a task executor subcommand and return stdout.
+     * Throws on transport failure, non-zero exit, or timeout.
+     */
+    invokeExecutor(ref: ExecutionRef, subcommand: string, opts?: {
+        timeout?: number;
+        input?: string;
+    }): Promise<string>;
+    /** Schema-only card validator (no executor invocation). */
+    validateSchema(card: Record<string, unknown>): {
+        ok: boolean;
+        errors: string[];
+    };
+    /** Absolute-path blob I/O for resolving arbitrary KindValueRef blobs. */
+    absoluteBlob: BlobStorage;
+    /**
+    * Default timeouts (ms) for executor request/response calls.
+     * Each field can also be overridden per-source via source_def.timeout.
+     *
+     *   validationMs — validate-source-def, validate-card-preflight (structural, fast). Default: 10_000.
+      *   preflightMs  — source preflight executor hooks (probe-source-preflight). Default: 60_000.
+     *   probeMs      — run-source-fetch in probe/simulation paths. Default: 60_000.
+     *   describeMs   — describe-capabilities introspection. Default: 10_000.
+     */
+    executorTimeouts?: {
+        validationMs?: number;
+        preflightMs?: number;
+        probeMs?: number;
+        describeMs?: number;
+    };
+}
+interface BoardLiveCardsNonCorePublic {
+    /** body: { "card-content": <card> } — card JSON arrives via stdin; validates schema + JSONata + provides refs + source_defs (executor, if configured) */
+    validateCardPreflight(input: CommandInput): Promise<CommandResult<{
+        cardId: string;
+        isValid: boolean;
+        issues: string[];
+    }>>;
+    /** body: { "card-content": <card>, "mock-projections"?: {} }; params: sourceIdx, outRef? — card JSON arrives via stdin; no board state needed */
+    probeSourcePreflight(input: CommandInput): Promise<CommandResult>;
+    /** body: { "card-content": <card>, "mock-projections"?: {} }; params: sourceIdx, outRef? — runs the real source fetch flow as a preflight */
+    runSourcePreflight(input: CommandInput): Promise<CommandResult<{
+        bindTo: string;
+        ok: boolean;
+        result: unknown;
+        issues: string[];
+    }>>;
+    /** body: { "card-content": <card>, "mock-fetched-sources"?: {}, "mock-requires"?: {} } — evaluates compute expressions with supplied data; no board state needed */
+    evalCardCompute(input: CommandInput): CommandResult<{
+        cardId: string;
+        ok: boolean;
+        computed_values: Record<string, unknown>;
+        errors: Array<{
+            bindTo: string;
+            error: string;
+        }>;
+    }>;
+    /** body: { "card-content": <card>, "mock-fetched-sources"?: {}, "mock-requires"?: {} } — full cycle: validate → resolve projections → probe sources → compute */
+    simulateCardCycle(input: CommandInput): Promise<CommandResult>;
+    /** no params needed */
+    describeTaskExecutorCapabilities(input: CommandInput): Promise<CommandResult>;
+    /**
+     * Write/update cards in the configured card store.
+     * body: { ops: Array<{ op: 'update', id: string, 'card-content': LiveCard }> }
+     */
+    updatesInCardStore(input: CommandInput): CommandResult;
+    /**
+     * Read cards from the configured card store by id.
+     * body: { ids: string[] }
+     */
+    readFromCardStore(input: CommandInput): CommandResult<{
+        cards: Array<{
+            id: string;
+            'card-content': LiveCard | null;
+        }>;
+    }>;
+}
+declare function createBoardLiveCardsNonCorePublic(baseRef: KindValueRef, adapter: BoardNonCorePlatformAdapter, opts?: {
+    boardRuntimeStoreRef?: string;
+    taskExecutorRef?: ExecutionRef;
+}): BoardLiveCardsNonCorePublic;
+
+export { BoardChangeNotification, type BoardLiveCardsNonCorePublic, type BoardLiveCardsPublic, type BoardLiveCardsPublicOptions, type BoardNonCorePlatformAdapter, type BoardPlatformAdapter, type BoardSseOneShotPayload, type CommandInput, type CommandResult, createBoardLiveCardsNonCorePublic, createBoardLiveCardsPublic };

package/lib/board-live-cards-public.js

@@ -1,2 +1,2 @@
-export{n as BOARD_GRAPH_KEY,u as EMPTY_CONFIG,m as SNAPSHOT_SCHEMA_VERSION_V1,z as createBoardLiveCardsNonCorePublic,y as createBoardLiveCardsPublic}from'./chunk-ZWVT24YW.js';import'./chunk-ANKA7HEJ.js';import'./chunk-44L64VQ2.js';import'./chunk-VGT3TRQG.js';import'./chunk-WDPOGXTY.js';import'./chunk-JMDHDY6M.js';import'./chunk-3KC6LBOG.js';import'./chunk-MNEOJWPS.js';import'./chunk-KBELAKIY.js';import'./chunk-FW4363Y4.js';//# sourceMappingURL=board-live-cards-public.js.map
+export{n as BOARD_GRAPH_KEY,u as EMPTY_CONFIG,m as SNAPSHOT_SCHEMA_VERSION_V1,z as createBoardLiveCardsNonCorePublic,y as createBoardLiveCardsPublic}from'./chunk-P3R6TXII.js';import'./chunk-ANKA7HEJ.js';import'./chunk-44L64VQ2.js';import'./chunk-VGT3TRQG.js';import'./chunk-WDPOGXTY.js';import'./chunk-JMDHDY6M.js';import'./chunk-3KC6LBOG.js';import'./chunk-MNEOJWPS.js';import'./chunk-7QNEV5S3.js';import'./chunk-UGB7PC4P.js';import'./chunk-FW4363Y4.js';//# sourceMappingURL=board-live-cards-public.js.map
 //# sourceMappingURL=board-live-cards-public.js.map