yaml-flow 8.5.3 → 8.6.1

package/cli/types-H3EMBPY2.d.ts

@@ -1,398 +0,0 @@
-import { b as KVStorage, B as BlobStorage, S as ScratchStorage, c as ArchiveFactory, d as AtomicRelayLock, E as ExecutionRef, K as KindValueRef, J as JournalStorage } from './execution-interface-BCIhu1gO.js';
-import { L as LiveCard, B as BoardStatusObject, J as JournalStorageAdapter, O as OutputStoreEvent } from './board-live-cards-lib-COi4bSpk.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 result = await board.processAccumulatedEvents();
- *   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:
-     *   'sources' — fetched source data files (keyed by cardId/outputFile)
-     *   ''        — root-scoped blob access (for resolving arbitrary KindValueRef blobs)
-     */
-    blobStorage(namespace: string): BlobStorage;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Self-identity ExecutionRef — how to invoke THIS board instance.
-     * Embedded in source callback tokens so executors know where to report back.
-    *   Node/FS:  { howToRun: 'local-node', whatToRun: 'b64:<base64url({"kind":"yaml-flow-cli","value":"board-live-cards-cli.js"})>' }
-    *   Azure Fn: { howToRun: 'http:post',  whatToRun: 'b64:<base64url({"kind":"http-url","value":"https://…/api/board"})>' }
-     */
-    selfRef: ExecutionRef;
-    /**
-     * 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: writes args to temp file, spawns 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;
-    }>;
-    /**
-     * 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>;
-    getCardStoreRef(input: CommandInput): CommandResult<{
-        storeRef: string;
-    }>;
-    getOutputsStoreRef(input: CommandInput): CommandResult<{
-        storeRef: string;
-    }>;
-    getScratchStoreRef(input: CommandInput): CommandResult<{
-        storeRef: string | null;
-    }>;
-    getArchiveStoreRef(input: CommandInput): CommandResult<{
-        storeRef: string | null;
-    }>;
-    getChatStoreRef(input: CommandInput): CommandResult<{
-        storeRef: string | null;
-    }>;
-    getArtifactsStoreRef(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>>>;
-    removeCard(input: CommandInput): CommandResult;
-    addCardFiles(input: CommandInput): CommandResult<{
-        cardId: string;
-        files_added: Array<{
-            idx: number;
-            entry: unknown;
-        }>;
-        notified: true;
-    }>;
-    cardRefreshedNotify(input: CommandInput): CommandResult;
-    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;
-}
-type BoardChangeNotification = OutputStoreEvent | {
-    kind: 'card_refreshed';
-    cardId: string;
-    card: LiveCard;
-} | {
-    kind: 'card_removed';
-    cardId: string;
-};
-declare function createBoardLiveCardsPublic(baseRef: KindValueRef, adapter: BoardPlatformAdapter): BoardLiveCardsPublic;
-interface BoardNonCorePlatformAdapter extends BoardPlatformAdapter {
-    /**
-     * Synchronously invoke a task executor subcommand and return stdout.
-     * Throws on non-zero exit or timeout.
-     */
-    invokeExecutorSync(ref: ExecutionRef, subcommand: string, args: string[], opts?: {
-        timeout?: number;
-        input?: string;
-    }): 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 synchronous executor invocations.
-     * 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 {
-    /** params: cardId? or all?; returns array even for single card */
-    validateCard(input: CommandInput): CommandResult<Array<{
-        cardId: string;
-        isValid: boolean;
-        issues: string[];
-    }>>;
-    /** body: { "card-content": <card> } — card JSON arrives via stdin; validates schema + JSONata + provides refs + source_defs (executor, if configured) */
-    validateCardPreflight(input: CommandInput): CommandResult<{
-        cardId: string;
-        isValid: boolean;
-        issues: string[];
-    }>;
-    /** params: cardId, sourceIdx, outRef?; body — mockProjections object */
-    probeSource(input: CommandInput): CommandResult;
-    /** body: { sourceDef, mockProjections }; params: outRef? */
-    probeTmpSource(input: CommandInput): CommandResult;
-    /** body: { "card-content": <card>, "mock-projections"?: {} }; params: sourceIdx, outRef? — card JSON arrives via stdin; no board state needed */
-    probeSourcePreflight(input: CommandInput): CommandResult;
-    /** body: { "card-content": <card>, "mock-projections"?: {} }; params: sourceIdx, outRef? — runs the real source fetch flow as a preflight */
-    runSourcePreflight(input: CommandInput): 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): CommandResult;
-    /** no params needed */
-    describeTaskExecutorCapabilities(input: CommandInput): 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): BoardLiveCardsNonCorePublic;
-
-/**
- * chat-storage-lib.ts
- *
- * ChatStorage interface + factories backed by JournalStorage (history) and
- * KVStorage (processing state and config).
- *
- * Platform-free — no node:fs or node:crypto imports.
- */
-
-interface ChatRecord {
-    /** Journal entry id — also used as SSE cursor. */
-    id: string;
-    role: string;
-    text: string;
-    files: unknown[];
-    turn: string;
-    updated_at: string;
-}
-interface ChatConfig {
-    systemPrompt?: string;
-}
-interface ChatReadAfterResult {
-    records: ChatRecord[];
-    /** Pass as cursor on the next call. Null when the journal is empty. */
-    cursor: string | null;
-}
-interface ChatStorage {
-    /** Append a message; returns the new entry id (usable as a cursor). */
-    append(cardId: string, role: string, text: string, files?: unknown[], turn?: string): string;
-    /** Read all messages in insertion order. */
-    readAll(cardId: string): ChatRecord[];
-    /**
-     * Read messages appended after cursor.
-     * Pass null to read from the beginning.
-     */
-    readAfter(cardId: string, cursor: string | null): ChatReadAfterResult;
-    /** Remove all messages for this card. */
-    clear(cardId: string): void;
-    setProcessing(cardId: string, active: boolean): void;
-    isProcessing(cardId: string): boolean;
-    getConfig(cardId: string): ChatConfig;
-    setConfig(cardId: string, patch: Partial<ChatConfig>): void;
-}
-/**
- * Create a ChatStorage backed by:
- *  - journalFactory(cardId) → JournalStorage  (one per-card journal for history)
- *  - kv                     → KVStorage       (shared processing flags + config)
- */
-declare function createChatStorage(journalFactory: (cardId: string) => JournalStorage, kv: KVStorage): ChatStorage;
-declare function createInMemoryChatStorage(): ChatStorage;
-
-interface InvocationAdapter {
-    /**
-     * Fire-and-forget invocation of an ExecutionRef with args.
-     * Used for chat-handler dispatch, and potentially task-executor / inference-adapter.
-     * Returns a promise that resolves when the invocation is dispatched (not completed).
-     */
-    invoke(ref: ExecutionRef, args: Record<string, unknown>): Promise<{
-        dispatched: boolean;
-        error?: string;
-    }>;
-    /**
-     * Optional synchronous describe call — asks the target to identify itself.
-     * Used for pre-init validation (e.g. confirming a chat-handler reports kind='chat-handler').
-     * Hosts that pre-register capabilities at deploy time may omit this.
-     */
-    describe?(ref: ExecutionRef): Promise<DescribeEnvelope | null>;
-}
-interface NotificationTransport {
-    /**
-     * Start listening for events on a notification endpoint identified by a kind-ref.
-     * The ref kind determines the transport mechanism:
-     *   ::named-pipe::/tmp/board-x.sock
-     *   ::firestore-watch::collections/board-x/notifications
-     *   ::signalr::https://x.service.signalr.net/hub/board-x
-     * onEvent is called with parsed JSON notification objects.
-     * Returns a teardown function.
-     */
-    subscribe(ref: KindValueRef, onEvent: (event: unknown) => void): Promise<() => void>;
-}
-interface DescribeEnvelope {
-    name: string;
-    kind: 'task-executor' | 'chat-handler' | 'inference-adapter';
-    protocolVersion: string;
-    supports?: string[];
-}
-
-export { type BoardPlatformAdapter as B, type ChatStorage as C, type DescribeEnvelope as D, type InvocationAdapter as I, type NotificationTransport as N, type CommandInput as a, type CommandResult as b, type ChatRecord as c, type ChatReadAfterResult as d, type ChatConfig as e, type BoardNonCorePlatformAdapter as f, type BoardLiveCardsNonCorePublic as g, type BoardLiveCardsPublic as h, createBoardLiveCardsNonCorePublic as i, createBoardLiveCardsPublic as j, createChatStorage as k, createInMemoryChatStorage as l };