/**
 * The data-program execution orchestrator.
 *
 * Loads a stored program (or dry-runs inline code), checks viewer-scoped
 * access, resolves the run-result cache, and — on a cache miss — executes
 * the program through the EXISTING `executeSandboxCode` (run-code) sandbox.
 * No new sandboxing, credential, SSRF, or quota code lives here: all
 * provider access flows through the sandbox's existing bridge globals
 * (`providerFetch`, `providerFetchAll`, `providerSearchAll`, `appAction`,
 * `workspace*`), which resolve auth through `provider-api-request` /
 * `resolveAuth` using the CALLER's own request context — never the
 * program's original author.
 */
import type { ActionEntry } from "../agent/production-agent.js";
import { type DataProgramColumn } from "./contract.js";
export type DataProgramErrorCode = "program_not_found" | "access_denied" | "archived" | "timeout" | "emit_missing" | "emit_shape_invalid" | "sandbox_error" | "run_code_unavailable" | "background_pending" | "result_too_large";
export interface DataProgramSuccess {
    ok: true;
    rows: Record<string, unknown>[];
    schema: DataProgramColumn[];
    truncated: boolean;
    stale: boolean;
    cacheHit: boolean;
    asOfMs: number;
    runId: string;
}
export interface DataProgramFailure {
    ok: false;
    error: {
        code: DataProgramErrorCode;
        message: string;
    };
    lastGoodRun?: {
        rows: Record<string, unknown>[];
        schema: DataProgramColumn[];
        truncated: boolean;
        asOfMs: number;
    };
}
export type DataProgramResult = DataProgramSuccess | DataProgramFailure;
export type DataProgramTriggeredBy = "agent" | "panel_view" | "schedule" | "manual_refresh" | "preview";
export interface RunDataProgramArgs {
    /** Stored program id. Mutually exclusive with `code` (code = inline dry-run/preview path). */
    programId?: string;
    /**
     * The calling app's id. When provided alongside `programId`, the lookup is
     * scoped to programs owned by this app — a program created in one app is
     * not runnable from another app's agent chat in a shared-database
     * deployment, even for a user who otherwise has row-level access.
     */
    appId?: string;
    /** Inline code for a dry-run/preview — no persisted program, no cache. */
    code?: string;
    params?: Record<string, unknown>;
    ctx: {
        userEmail?: string;
        orgId?: string | null;
    };
    triggeredBy: DataProgramTriggeredBy;
    forceRefresh?: boolean;
    timeoutMs?: number;
}
export declare function initDataPrograms(opts: {
    appId: string;
    getActions: () => Record<string, ActionEntry>;
}): void;
/** The appId passed to the most recent `initDataPrograms()` call, if any. */
export declare function getInitializedDataProgramsAppId(): string | undefined;
/** Test-only: clear module-level supplier state. */
export declare function _resetDataProgramsRuntimeForTests(): void;
/** Canonical (key-sorted) JSON so equivalent params always hash the same. */
export declare function canonicalDataProgramParamsJson(value: unknown): string;
/**
 * Hash params (and, critically, the viewer/org scope) into the cache key used for
 * `data_program_runs` lookups.
 *
 * `providerFetch` inside a program resolves auth using the CALLING viewer's
 * own request context (never the program author's), so two different viewers
 * running the same program with the same params can legitimately get two
 * different results — e.g. one has a configured HubSpot key and the other
 * doesn't, or row-level provider permissions differ per user. Folding
 * `viewerKey` and `orgKey` into the hash means the run cache (and the active-run /
 * last-successful-run lookups keyed on it) is scoped per viewer, so a
 * teammate missing a credential sees their own auth error, not a cached
 * result produced under someone else's token or org grants. Pass stable
 * identities for `viewerKey` (the calling user's email) and `orgKey`
 * (the active org id); omitting them is only safe for inline preview/dry-run
 * calls that never persist or read the shared cache.
 */
export declare function hashDataProgramParams(params: Record<string, unknown> | undefined, viewerKey?: string, orgKey?: string | null): string;
/**
 * Run a stored data program (or inline code for preview/dry-run). Never
 * throws — always resolves to a discriminated success/failure result.
 */
export declare function runDataProgram(args: RunDataProgramArgs): Promise<DataProgramResult>;
//# sourceMappingURL=execute.d.ts.map