@gonvex/module-sdk 0.3.0

package/dist/index.d.ts

@@ -0,0 +1,641 @@
+/** JSON values accepted by the module ABI. */
+export type JsonValue = null | boolean | number | string | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+export type JsonObject = {
+    [key: string]: JsonValue;
+};
+export type ModuleLanguage = "typescript";
+export type ModuleEngine = "v8";
+export type PortableSchema = StringSchema | NumberSchema | BooleanSchema | NullSchema | AnySchema | IdSchema | LiteralSchema | ArraySchema | ObjectSchema | RecordSchema | OptionalSchema;
+export type StringSchema = {
+    readonly kind: "string";
+    readonly format?: "email" | "uri" | "uuid" | "datetime";
+    readonly minLength?: number;
+    readonly maxLength?: number;
+};
+export type NumberSchema = {
+    readonly kind: "number";
+    readonly integer?: boolean;
+    readonly minimum?: number;
+    readonly maximum?: number;
+};
+export type BooleanSchema = {
+    readonly kind: "boolean";
+};
+export type NullSchema = {
+    readonly kind: "null";
+};
+export type AnySchema = {
+    readonly kind: "any";
+};
+export type IdSchema = {
+    readonly kind: "id";
+    readonly entity: string;
+};
+export type LiteralSchema = {
+    readonly kind: "literal";
+    readonly value: JsonValue;
+};
+export type ArraySchema = {
+    readonly kind: "array";
+    readonly items: PortableSchema;
+};
+export type ObjectSchema = {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, PortableSchema>>;
+    readonly allowUnknown?: boolean;
+};
+export type RecordSchema = {
+    readonly kind: "record";
+    readonly values: PortableSchema;
+};
+export type OptionalSchema = {
+    readonly kind: "optional";
+    readonly value: PortableSchema;
+};
+export type InferSchema<S extends PortableSchema> = S extends StringSchema ? string : S extends NumberSchema ? number : S extends BooleanSchema ? boolean : S extends NullSchema ? null : S extends AnySchema ? JsonValue : S extends IdSchema ? string : S extends LiteralSchema ? S["value"] : S extends ArraySchema ? InferSchema<S["items"]>[] : S extends ObjectSchema ? {
+    [K in keyof S["fields"]]: S["fields"][K] extends OptionalSchema ? InferSchema<S["fields"][K]["value"]> | undefined : S["fields"][K] extends PortableSchema ? InferSchema<S["fields"][K]> : never;
+} : S extends RecordSchema ? Record<string, InferSchema<S["values"]>> : S extends OptionalSchema ? InferSchema<S["value"]> | undefined : never;
+/** Constructors for the language-neutral schema subset. */
+export declare const schema: {
+    string(options?: Omit<StringSchema, "kind">): StringSchema;
+    email(): StringSchema;
+    uri(): StringSchema;
+    uuid(): StringSchema;
+    datetime(): StringSchema;
+    number(options?: Omit<NumberSchema, "kind">): NumberSchema;
+    integer(options?: Omit<NumberSchema, "kind" | "integer">): NumberSchema;
+    boolean(): BooleanSchema;
+    null(): NullSchema;
+    any(): AnySchema;
+    id(entity: string): IdSchema;
+    literal(value: JsonValue): LiteralSchema;
+    array(items: PortableSchema): ArraySchema;
+    object(fields: Record<string, PortableSchema>, options?: Omit<ObjectSchema, "kind" | "fields">): ObjectSchema;
+    record(values: PortableSchema): RecordSchema;
+    optional(value: PortableSchema): OptionalSchema;
+};
+export type Account = {
+    readonly id: string;
+    readonly email?: string;
+    readonly name?: string;
+    readonly avatarUrl?: string;
+};
+export type Tenant = {
+    readonly id: string;
+    readonly name?: string;
+};
+export type Member = {
+    readonly id: string;
+    readonly accountId: string;
+    readonly status?: "active" | "revoked" | "disabled" | (string & {});
+    readonly role?: string;
+    readonly displayName?: string;
+    readonly permissions: Readonly<Record<string, JsonValue>> | null;
+};
+/** Authentication identity exposed to a module. */
+export type AuthContext = {
+    readonly auth: {
+        readonly account: Account | null;
+    };
+};
+/** Tenant and tenant-local member identity, both nullable at the ABI boundary. */
+export type TenantContext = {
+    readonly tenant: Tenant | null;
+    readonly member: Member | null;
+};
+export type ReadDB = {
+    readonly query: <T = JsonValue>(statement: string, parameters?: readonly JsonValue[]) => Promise<readonly T[]>;
+};
+export type WriteDB = ReadDB & {
+    readonly insert: <T = JsonValue>(table: string, row: JsonObject) => Promise<T>;
+    readonly update: <T = JsonValue>(table: string, id: string, patch: JsonObject) => Promise<T>;
+    readonly delete: (table: string, id: string) => Promise<void>;
+};
+/** Durable external work recorded in the Reducer's current transaction. */
+export type ReducerActions = {
+    readonly enqueue: (path: string, args: JsonValue) => Promise<string>;
+};
+/** One-shot work owned by the Gonvex scheduler. Timestamps are Unix milliseconds. */
+export type Scheduler = {
+    readonly runAfter: (delayMs: number, functionPath: string, args?: JsonValue) => Promise<string>;
+    readonly runAt: (unixMs: number, functionPath: string, args?: JsonValue) => Promise<string>;
+};
+export type QueryContext = AuthContext & TenantContext & {
+    readonly db: ReadDB;
+    readonly now: number;
+};
+export type ReducerContext = AuthContext & TenantContext & {
+    readonly db: WriteDB;
+    readonly actions: ReducerActions;
+    readonly scheduler: Scheduler;
+    readonly now: number;
+};
+export type ActionStorage = {
+    readonly generateUploadUrl: (options?: JsonObject) => Promise<JsonValue>;
+    readonly getUrl: (fileId: string) => Promise<JsonValue>;
+    readonly generateDownloadUrl: (fileId: string, ttlMs?: number) => Promise<JsonValue>;
+    readonly getMetadata: (fileId: string) => Promise<JsonValue>;
+    readonly delete: (fileId: string) => Promise<JsonValue>;
+    readonly store: (contentBase64: string, options?: JsonObject) => Promise<JsonValue>;
+    readonly call: (operation: string, payload?: JsonValue) => Promise<JsonValue>;
+};
+export type ActionToolBinding = {
+    readonly kind: "query" | "reducer";
+    readonly function: string;
+};
+export type ActionToolBindings = Readonly<Record<string, ActionToolBinding>>;
+export type SandboxStatus = "queued" | "running" | "succeeded" | "failed" | "cancelled" | "timedOut";
+export type SandboxHandle = {
+    readonly sandboxId: string;
+    readonly expiresAt: number;
+    readonly duckdb: boolean;
+};
+export type SandboxExecution = {
+    readonly sandboxId: string;
+    readonly executionId: string;
+    readonly status: SandboxStatus;
+};
+export type SandboxExecutionStatus = SandboxExecution & {
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    readonly result?: JsonValue;
+    readonly error?: string;
+    readonly logs: readonly {
+        readonly level: "log" | "warn" | "error";
+        readonly message: string;
+    }[];
+};
+export type ActionSandbox = {
+    /** Create one caller-owned, tenant-scoped ephemeral TypeScript workspace. */
+    readonly create: (options?: {
+        readonly ttlMs?: number;
+    }) => Promise<SandboxHandle>;
+    /** Start TypeScript code asynchronously. The code returns its JSON result with a top-level return statement. */
+    readonly run: (sandboxId: string, options: {
+        readonly code: string;
+        readonly timeoutMs?: number;
+    }) => Promise<SandboxExecution>;
+    readonly cancel: (sandboxId: string, executionId: string) => Promise<SandboxExecutionStatus>;
+    readonly status: (sandboxId: string, executionId: string) => Promise<SandboxExecutionStatus>;
+    readonly readFile: (sandboxId: string, path: string) => Promise<{
+        readonly contentBase64: string;
+        readonly size: number;
+    }>;
+    readonly writeFile: (sandboxId: string, path: string, contentBase64: string) => Promise<{
+        readonly path: string;
+        readonly size: number;
+    }>;
+    readonly readText: (sandboxId: string, path: string) => Promise<string>;
+    readonly writeText: (sandboxId: string, path: string, content: string) => Promise<{
+        readonly path: string;
+        readonly size: number;
+    }>;
+    /** Ingest an authorized Gonvex storage file into DuckDB without placing its bytes in model context. */
+    readonly importFile: (sandboxId: string, options: {
+        readonly fileId: string;
+        readonly filename: string;
+    }) => Promise<{
+        readonly alias: string;
+        readonly tables: readonly {
+            readonly tableName: string;
+            readonly rowCount: number;
+            readonly columns: readonly string[];
+        }[];
+    }>;
+};
+export type SandboxCapability = {
+    /** Bind a private DuckDB database into the TypeScript worker. */
+    readonly duckdb?: true;
+};
+export type ActionCapabilities<Tools extends ActionToolBindings = ActionToolBindings> = {
+    /** Exact URL origins this Action may call. No network access is granted when omitted. */
+    readonly networkOrigins?: readonly string[];
+    /** Exact project secret names copied into this invocation. No other environment values are exposed. */
+    readonly secrets?: readonly string[];
+    /** Named, statically bound Query and Reducer tools. Arbitrary function paths are never accepted. */
+    readonly tools?: Tools;
+    readonly scheduler?: true;
+    readonly storage?: true;
+    /** Run untrusted TypeScript in an out-of-process, tenant-scoped sandbox. Agent Actions only. */
+    readonly sandbox?: SandboxCapability;
+};
+type ActionToolFunctions<Tools extends ActionToolBindings> = {
+    readonly [Name in keyof Tools]: <Result = JsonValue>(args?: JsonValue) => Promise<Result>;
+};
+export type ActionContext<Capabilities extends ActionCapabilities = ActionCapabilities> = AuthContext & TenantContext & {
+    readonly now: number;
+} & (Capabilities extends {
+    readonly networkOrigins: readonly string[];
+} ? {
+    readonly fetch: (input: string | URL, init?: RequestInit) => Promise<Response>;
+} : {}) & (Capabilities extends {
+    readonly secrets: readonly string[];
+} ? {
+    readonly secrets: Readonly<Record<Capabilities["secrets"][number], string>>;
+} : {}) & (Capabilities extends {
+    readonly tools: infer Tools extends ActionToolBindings;
+} ? {
+    readonly tools: ActionToolFunctions<Tools>;
+} : {}) & (Capabilities extends {
+    readonly scheduler: true;
+} ? {
+    readonly scheduler: Scheduler;
+} : {}) & (Capabilities extends {
+    readonly storage: true;
+} ? {
+    readonly storage: ActionStorage;
+} : {}) & (Capabilities extends {
+    readonly sandbox: SandboxCapability;
+} ? {
+    readonly sandbox: ActionSandbox;
+} : {});
+export type Handler<Context, Args, Result> = (context: Context, args: Args) => Result | Promise<Result>;
+export type OfflinePolicy = {
+    readonly mode: "forbidden";
+} | {
+    readonly mode: "allowed";
+    readonly conflict?: "reject" | "expectedVersion" | "merge";
+} | {
+    readonly mode: "onlineOnly";
+    readonly reason: string;
+};
+export type OptimisticID = string | readonly string[];
+/** Resolve this value from Reducer arguments in the client Local Replica. */
+export type OptimisticArgument = {
+    readonly $arg: string | readonly string[];
+};
+export type OptimisticValue = JsonValue | OptimisticArgument | readonly OptimisticValue[] | {
+    readonly [key: string]: OptimisticValue;
+};
+export type OptimisticObject = {
+    readonly [key: string]: OptimisticValue;
+};
+export type OptimisticEffect = {
+    readonly operation: "patch";
+    readonly entity: string;
+    readonly id: OptimisticID;
+    readonly fields: OptimisticObject;
+} | {
+    readonly operation: "upsert";
+    readonly entity: string;
+    readonly id: OptimisticID;
+    readonly value: OptimisticObject;
+} | {
+    readonly operation: "delete";
+    readonly entity: string;
+    readonly id: OptimisticID;
+};
+export type OptimisticTransaction = {
+    readonly effects: readonly OptimisticEffect[];
+    readonly expectedRevision?: number;
+};
+export type QueryOptions<Args, Result> = {
+    readonly args?: PortableSchema;
+    readonly result?: PortableSchema;
+    readonly delivery?: "oneShot" | "live" | "replica";
+    readonly liveQueryPlan?: LiveQueryPlan;
+    readonly replica?: ReplicaCollectionDefinition;
+    /** Internal Queries are callable only through a declared Action tool. */
+    readonly internal?: boolean;
+    readonly run?: Handler<QueryContext, Args, Result>;
+};
+/** Declarative contract for a bounded, locally materialized query collection. */
+export type ReplicaCollectionDefinition = {
+    readonly table: string;
+    readonly key: string;
+    readonly columns: readonly string[];
+    readonly equalFilters?: Readonly<Record<string, string>>;
+    readonly excludeWhenSet?: readonly string[];
+    readonly visibilityTables?: readonly string[];
+    /** Assigned by the runtime; module authors do not set this. */
+    readonly visibilityPlanHash?: string;
+    readonly orderBy?: string;
+    readonly orderDirection?: "asc" | "desc";
+    /** `eager` is complete at initial delivery; `progressive` may fill incrementally. */
+    readonly mode?: "eager" | "progressive";
+    readonly maxRows?: number;
+    readonly maxBytes?: number;
+    readonly retentionMs?: number;
+};
+export type ReplicaCollectionOptions<Args, Result> = Omit<QueryOptions<Args, Result>, "delivery" | "replica"> & {
+    readonly replica: ReplicaCollectionDefinition;
+};
+export type ReducerOptions<Args, Result> = {
+    readonly args?: PortableSchema;
+    readonly result?: PortableSchema;
+    readonly offline: OfflinePolicy;
+    /** Set false for reducers that are not invoked directly by an interactive client. */
+    readonly interactive?: boolean;
+    readonly optimistic?: OptimisticTransaction;
+    /** Required exception for a public interactive reducer that cannot predict a safe local transaction. */
+    readonly nonOptimisticReason?: string;
+    readonly internal?: boolean;
+    readonly run?: Handler<ReducerContext, Args, Result>;
+};
+export type InternalReducerOptions<Args, Result> = Omit<ReducerOptions<Args, Result>, "offline" | "interactive" | "internal"> & {
+    readonly offline?: OfflinePolicy;
+};
+export type ActionOptions<Args, Result, Capabilities extends ActionCapabilities = ActionCapabilities> = {
+    /** Optional explicit public path used by static module artifact extraction. */
+    readonly name?: string;
+    readonly args?: PortableSchema;
+    readonly result?: PortableSchema;
+    /** Agent Actions are disabled unless the runtime operator explicitly enables them. */
+    readonly profile?: "standard" | "agent";
+    readonly capabilities?: Capabilities;
+    readonly run?: Handler<ActionContext<Capabilities>, Args, Result>;
+};
+export type LiveQueryValue = {
+    readonly argument?: string;
+    readonly literal?: JsonValue;
+};
+export type FilterOperator = "contains" | "notContains" | "equals" | "notEquals" | "startsWith" | "endsWith" | "empty" | "notEmpty" | "oneOf" | "lessThan" | "lessThanOrEqual" | "greaterThan" | "greaterThanOrEqual" | "inRange";
+export type LiveQueryExpression = {
+    readonly operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "range" | "in" | "contains" | "containsInsensitive" | "and" | "or" | "not" | "server";
+    readonly column?: string;
+    readonly value?: LiveQueryValue;
+    readonly valueTo?: LiveQueryValue;
+    readonly children?: readonly LiveQueryExpression[];
+};
+export type LiveQueryPlan = {
+    readonly table: string;
+    readonly key: string;
+    readonly columns?: readonly string[];
+    readonly resultPath?: readonly string[];
+    readonly where?: LiveQueryExpression;
+    readonly search?: {
+        readonly argument: string;
+        readonly columns: readonly string[];
+    };
+    readonly filters?: {
+        readonly argument: string;
+        readonly allowedColumns: readonly string[];
+        readonly allowedOperators: readonly FilterOperator[];
+    };
+    readonly sort?: {
+        readonly columnArgument?: string;
+        readonly directionArgument?: string;
+        readonly defaultColumn: string;
+        readonly defaultDirection: "asc" | "desc";
+        readonly allowedColumns: readonly string[];
+    };
+    readonly window?: {
+        readonly offsetArgument: string;
+        readonly limitArgument: string;
+        readonly defaultLimit: number;
+        readonly maxLimit: number;
+        /** Request exact total-count metadata alongside a shaped result window. */
+        readonly count?: "exact";
+    };
+    readonly serverOnly?: boolean;
+};
+export type VisibilityOperator = "public" | "permission" | "role" | "eqContext" | "inSet" | "and" | "or" | "not";
+export type VisibilityContextKey = "account.id" | "member.id" | "tenant.id";
+export type VisibilityPlan = {
+    readonly table: string;
+    readonly key: string;
+    readonly sets: Readonly<Record<string, VisibilitySet>>;
+    readonly where: VisibilityExpression;
+};
+export type VisibilitySet = {
+    readonly table: string;
+    readonly select: string;
+    readonly joins: readonly VisibilityJoin[];
+    readonly where: readonly VisibilityConstraint[];
+};
+export type VisibilityJoin = {
+    readonly table: string;
+    readonly leftColumn: string;
+    readonly rightColumn: string;
+};
+export type VisibilityConstraint = {
+    readonly table: string;
+    readonly column: string;
+    readonly context: VisibilityContextKey;
+};
+export type VisibilityExpression = {
+    readonly operator: VisibilityOperator;
+    readonly column?: string;
+    readonly context?: VisibilityContextKey;
+    readonly set?: string;
+    readonly value?: string;
+    readonly children?: readonly VisibilityExpression[];
+};
+export type ModuleFunctionKind = "query" | "reducer" | "action";
+export type CronScope = "project" | "tenant";
+export type CronSchedule = {
+    readonly intervalMs: number;
+    readonly expression?: never;
+} | {
+    readonly expression: string;
+    readonly intervalMs?: never;
+};
+export type CronSpec = Readonly<{
+    name: string;
+    function: string;
+    args?: JsonValue;
+    scope: CronScope;
+} & CronSchedule>;
+export type CronOptions = Omit<CronSpec, "scope">;
+export type ModuleFunctionManifest = {
+    readonly path: string;
+    readonly kind: ModuleFunctionKind;
+    readonly args?: PortableSchema;
+    readonly result?: PortableSchema;
+    readonly internal?: boolean;
+    readonly delivery?: "oneShot" | "live" | "replica";
+    readonly liveQueryPlan?: LiveQueryPlan;
+    readonly replica?: ReplicaCollectionDefinition;
+    readonly offline?: OfflinePolicy;
+    readonly interactive?: boolean;
+    readonly optimistic?: OptimisticTransaction;
+    readonly nonOptimisticReason?: string;
+    readonly actionProfile?: "standard" | "agent";
+    readonly actionCapabilities?: ActionCapabilities;
+};
+export type ModuleManifest = {
+    readonly format: "gonvex.module.v1";
+    readonly name: string;
+    readonly version: string;
+    readonly language: ModuleLanguage;
+    readonly engine: ModuleEngine;
+    readonly functions: Readonly<Record<string, ModuleFunctionManifest>>;
+    readonly crons?: readonly CronSpec[];
+    readonly schema?: PortableSchema;
+    readonly artifact?: {
+        readonly hash: string;
+        readonly mediaType: string;
+        readonly entrypoint: string;
+    };
+    readonly visibility?: Readonly<Record<string, VisibilityPlan>>;
+    readonly invitationAcceptanceReducer?: string;
+};
+/** Declare the host-invoked internal Reducer that applies invitation payloads. */
+export declare function invitationAcceptance(reducerPath: string): Readonly<{
+    reducer: string;
+}>;
+export type ModuleArtifact = {
+    readonly manifest: ModuleManifest;
+    readonly bytes: Uint8Array;
+};
+export type ModuleFunctionHandler = Handler<QueryContext, unknown, unknown> | Handler<ReducerContext, unknown, unknown> | Handler<ActionContext, unknown, unknown>;
+/** A manifest entry together with the executable function retained by the host. */
+export type RuntimeFunctionRegistration = {
+    readonly path: string;
+    readonly kind: ModuleFunctionKind;
+    readonly definition: ModuleFunctionManifest;
+    readonly handler?: ModuleFunctionHandler;
+};
+export type ModuleRuntimeRegistration = {
+    readonly path: string;
+    readonly kind: ModuleFunctionKind;
+    readonly definition: ModuleFunctionManifest;
+};
+/** Deterministic, handler-free payload consumed by a module host during loading. */
+export type ModuleRuntimeRegistrationPayload = {
+    readonly format: "gonvex.module.runtime.v1";
+    readonly manifest: ModuleManifest;
+    readonly registrations: readonly ModuleRuntimeRegistration[];
+};
+export type QueryInvocation<Args = unknown> = {
+    readonly path: string;
+    readonly kind: "query";
+    readonly context: QueryContext;
+    readonly args: Args;
+};
+export type ReducerInvocation<Args = unknown> = {
+    readonly path: string;
+    readonly kind: "reducer";
+    readonly context: ReducerContext;
+    readonly args: Args;
+};
+export type ActionInvocation<Args = unknown> = {
+    readonly path: string;
+    readonly kind: "action";
+    readonly context: ActionContext;
+    readonly args: Args;
+};
+export type ModuleInvocation<Args = unknown> = QueryInvocation<Args> | ReducerInvocation<Args> | ActionInvocation<Args>;
+type AnyFunctionOptions = QueryOptions<unknown, unknown> | ReducerOptions<unknown, unknown> | ActionOptions<unknown, unknown>;
+/** Declare and validate one source table's language-neutral visibility plan. */
+export declare function visibility(options: VisibilityPlan): VisibilityPlan;
+/** JSON serialization with recursively sorted object keys for reproducible artifacts. */
+export declare const stableJsonStringify: (value: unknown, space?: number) => string;
+/** Declare a project-wide recurring Reducer or Action. */
+export declare function cron(options: CronOptions): CronSpec;
+/** Declare a recurring Reducer or Action once for every tenant. */
+export declare function tenantCron(options: CronOptions): CronSpec;
+export declare class ModuleManifestCollector {
+    private readonly entries;
+    private readonly visibilityEntries;
+    private readonly cronEntries;
+    private readonly metadata;
+    constructor(metadata: Omit<ModuleManifest, "functions">);
+    register(path: string, entry: Omit<ModuleFunctionManifest, "path">): ModuleFunctionManifest;
+    registerVisibility(options: VisibilityPlan): VisibilityPlan;
+    registerCron(options: CronSpec): CronSpec;
+    manifest(): ModuleManifest;
+    serialize(space?: number): string;
+}
+export type RegisteredFunction<Args, Result> = {
+    readonly path: string;
+    readonly kind: ModuleFunctionKind;
+    readonly definition: ModuleFunctionManifest;
+    readonly handler?: Handler<QueryContext, Args, Result> | Handler<ReducerContext, Args, Result> | Handler<ActionContext, Args, Result>;
+};
+/**
+ * Executable definition returned by the top-level declaration helpers.
+ *
+ * The module loader uses the exported binding itself as the declaration and
+ * invokes `handler` when a V8 request arrives. `options` retains the
+ * declarative input so hosts can project it into a manifest without needing
+ * to evaluate TypeScript source again.
+ */
+export type ModuleDefinition<Kind extends ModuleFunctionKind, Options> = {
+    readonly kind: Kind;
+    readonly internal?: boolean;
+    readonly delivery?: "oneShot" | "live" | "replica";
+    readonly liveQueryPlan?: LiveQueryPlan;
+    readonly replica?: ReplicaCollectionDefinition;
+    readonly options: Readonly<Options>;
+    readonly handler?: Options extends {
+        readonly run?: infer HandlerType;
+    } ? HandlerType : never;
+};
+export type QueryDefinition<Args, Result> = ModuleDefinition<"query", QueryOptions<Args, Result>>;
+export type ReducerDefinition<Args, Result> = ModuleDefinition<"reducer", ReducerOptions<Args, Result>>;
+export type ActionDefinition<Args, Result, Capabilities extends ActionCapabilities = ActionCapabilities> = ModuleDefinition<"action", ActionOptions<Args, Result, Capabilities>>;
+/** Declare an executable one-shot, live, or replica query export. */
+export declare function query<Args = JsonValue, Result = JsonValue>(options?: QueryOptions<Args, Result>): QueryDefinition<Args, Result>;
+/** Declare a one-shot Query that is unreachable from clients and may be bound to an Action tool. */
+export declare function internalQuery<Args = JsonValue, Result = JsonValue>(options?: Omit<QueryOptions<Args, Result>, "internal" | "delivery" | "replica">): QueryDefinition<Args, Result>;
+/** Declare an executable live query export with a structured live plan. */
+export declare function liveQuery<Args = JsonValue, Result = JsonValue>(options?: Omit<QueryOptions<Args, Result>, "delivery">): QueryDefinition<Args, Result>;
+/** Declare an executable bounded replica collection export. */
+export declare function replicaCollection<Args = JsonValue, Result = JsonValue>(options: ReplicaCollectionOptions<Args, Result>): QueryDefinition<Args, Result>;
+/** Declare an executable public reducer export. */
+export declare function reducer<Args = JsonValue, Result = JsonValue>(options: ReducerOptions<Args, Result>): ReducerDefinition<Args, Result>;
+/** Declare an executable non-interactive internal reducer export. */
+export declare function internalReducer<Args = JsonValue, Result = JsonValue>(options: InternalReducerOptions<Args, Result>): ReducerDefinition<Args, Result>;
+/** Declare an executable action export. */
+export declare function action<Args = JsonValue, Result = JsonValue, const Capabilities extends ActionCapabilities = ActionCapabilities>(options?: ActionOptions<Args, Result, Capabilities>): ActionDefinition<Args, Result, Capabilities>;
+export declare class ModuleBuilder {
+    readonly manifestCollector: ModuleManifestCollector;
+    private readonly runtimeEntries;
+    constructor(metadata: {
+        name: string;
+        version: string;
+        language?: ModuleLanguage;
+        engine?: ModuleEngine;
+        schema?: PortableSchema;
+        artifact?: ModuleManifest["artifact"];
+        visibility?: Readonly<Record<string, VisibilityPlan>>;
+        crons?: readonly CronSpec[];
+    });
+    visibility(options: VisibilityPlan): VisibilityPlan;
+    cron(options: CronOptions): CronSpec;
+    tenantCron(options: CronOptions): CronSpec;
+    query<Args = JsonValue, Result = JsonValue>(path: string, options?: QueryOptions<Args, Result>): RegisteredFunction<Args, Result>;
+    /** Register a Query delivered as a live, structured query stream. */
+    liveQuery<Args = JsonValue, Result = JsonValue>(path: string, options?: Omit<QueryOptions<Args, Result>, "delivery">): RegisteredFunction<Args, Result>;
+    /** Register a Query delivered as a bounded local replica collection. */
+    replicaCollection<Args = JsonValue, Result = JsonValue>(path: string, options: ReplicaCollectionOptions<Args, Result>): RegisteredFunction<Args, Result>;
+    reducer<Args = JsonValue, Result = JsonValue>(path: string, options: ReducerOptions<Args, Result>): RegisteredFunction<Args, Result>;
+    /** Register a non-public Reducer while retaining kind `reducer` in the manifest. */
+    internalReducer<Args = JsonValue, Result = JsonValue>(path: string, options: InternalReducerOptions<Args, Result>): RegisteredFunction<Args, Result>;
+    action<Args = JsonValue, Result = JsonValue, const Capabilities extends ActionCapabilities = ActionCapabilities>(path: string, options?: ActionOptions<Args, Result, Capabilities>): RegisteredFunction<Args, Result>;
+    manifest(): ModuleManifest;
+    serialize(space?: number): string;
+    /** Executable registrations sorted by path for deterministic host loading. */
+    runtimeRegistrations(): readonly RuntimeFunctionRegistration[];
+    runtimePayload(): ModuleRuntimeRegistrationPayload;
+    serializeRuntimePayload(space?: number): string;
+    createRuntimeRegistry(): ModuleRuntimeRegistry;
+}
+/**
+ * Host-side executable registry. It is deliberately unaware of V8,
+ * Postgres, or network transport; an engine supplies the capability-bearing
+ * context and this registry only selects and invokes the registered handler.
+ */
+export declare class ModuleRuntimeRegistry {
+    private readonly entries;
+    private readonly baseManifest;
+    constructor(source: ModuleBuilder);
+    register(registration: RuntimeFunctionRegistration): void;
+    has(path: string, kind?: ModuleFunctionKind): boolean;
+    registration(path: string): RuntimeFunctionRegistration | undefined;
+    registrations(): readonly RuntimeFunctionRegistration[];
+    manifest(): ModuleManifest;
+    registrationPayload(): ModuleRuntimeRegistrationPayload;
+    serializeRegistrationPayload(space?: number): string;
+    query<Args, Result>(path: string, context: QueryContext, args: Args): Promise<Result>;
+    reducer<Args, Result>(path: string, context: ReducerContext, args: Args): Promise<Result>;
+    action<Args, Result>(path: string, context: ActionContext, args: Args): Promise<Result>;
+    dispatch<Args = unknown>(invocation: ModuleInvocation<Args>): Promise<unknown>;
+}
+export declare function createModule(metadata: ConstructorParameters<typeof ModuleBuilder>[0]): ModuleBuilder;
+/** Type-only helper for APIs that accept any builder options. */
+export type ModuleFunctionOptions = AnyFunctionOptions;
+export {};