@lostgradient/weft 0.2.0

package/dist/connection.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared Weft server connection resolution for the HTTP client and CLI commands.
+ *
+ * A single resolver backs every entry point so `WEFT_ADDR`, `WEFT_TOKEN`,
+ * `~/.weft/config` profiles, the local run lockfile, and the development default
+ * are interpreted identically whether you construct an {@link HttpClient} or run
+ * `weft api`/`weft codegen`.
+ *
+ * Resolution order for the server address is explicit option, then `WEFT_ADDR`,
+ * then the selected profile's `server`, then the run lockfile written by
+ * `weft serve` (CLI only — see `includeRunLockfile`), then
+ * `http://localhost:7233`. Token resolution prefers the explicit option, then
+ * `WEFT_TOKEN`, then the profile token (with `env:` and `tokenEnv` indirection).
+ * A profile token is only applied when neither an explicit `server` option nor
+ * `WEFT_ADDR` redirected the request to a different destination.
+ *
+ * @module connection
+ */
+/**
+ * Inputs accepted by {@link resolveConnection}.
+ *
+ * @example
+ * ```ts
+ * import { resolveConnection, type ConnectionOptions } from '@lostgradient/weft';
+ *
+ * const options: ConnectionOptions = {
+ *   server: 'https://weft.example.com',
+ *   token: 'secret-token',
+ * };
+ *
+ * const connection = resolveConnection(options);
+ * console.log(connection.server.toString());
+ * ```
+ */
+export type ConnectionOptions = {
+    readonly server?: string;
+    readonly token?: string;
+    readonly profile?: string;
+    /**
+     * Consult the local run lockfile written by `weft serve` as a fallback server
+     * address. Defaults to `true` for CLI developer convenience; library clients
+     * pass `false` so resolution stays explicit-options/env/profile/default.
+     */
+    readonly includeRunLockfile?: boolean;
+};
+/**
+ * Resolved Weft server connection settings.
+ *
+ * @example
+ * ```ts
+ * import { resolveConnection, type ResolvedConnection } from '@lostgradient/weft';
+ *
+ * const connection: ResolvedConnection = resolveConnection({
+ *   server: 'https://weft.example.com',
+ *   token: 'secret-token',
+ * });
+ *
+ * console.log(connection.token);
+ * ```
+ */
+export type ResolvedConnection = {
+    readonly server: URL;
+    readonly token?: string;
+};
+/**
+ * Default local Weft server address used when nothing else resolves.
+ *
+ * @example
+ * ```ts
+ * import { DEFAULT_WEFT_ADDRESS } from '@lostgradient/weft';
+ *
+ * console.log(DEFAULT_WEFT_ADDRESS); // "http://localhost:7233"
+ * ```
+ */
+export declare const DEFAULT_WEFT_ADDRESS = "http://localhost:7233";
+/**
+ * Raised when connection resolution fails. Two cases surface as this error:
+ * a present `~/.weft/config` file that cannot be parsed (a missing file is not
+ * an error), and a resolved server value that is not a valid URL — regardless
+ * of where it came from (`--server`/explicit option, `WEFT_ADDR`, the profile
+ * `server` field, or the run lockfile). Both are surfaced rather than silently
+ * connecting to the wrong server; the message carries the offending value (the
+ * invalid URL string, or the config path for a parse failure).
+ *
+ * @example
+ * ```ts
+ * import { ConnectionConfigurationError, resolveConnection } from '@lostgradient/weft';
+ *
+ * try {
+ *   resolveConnection();
+ * } catch (error) {
+ *   if (error instanceof ConnectionConfigurationError) {
+ *     console.error(error.message);
+ *   }
+ * }
+ * ```
+ */
+export declare class ConnectionConfigurationError extends Error {
+    constructor(message: string);
+}
+/**
+ * Resolve Weft server connection settings from explicit options, environment
+ * variables, `~/.weft/config`, the local run lockfile (when
+ * `includeRunLockfile` is not `false`), and the development default.
+ *
+ * Resolution is synchronous so it can run inside the {@link HttpClient}
+ * constructor and CLI command handlers alike.
+ *
+ * @example
+ * ```ts
+ * import { resolveConnection } from '@lostgradient/weft';
+ *
+ * const connection = resolveConnection({ server: 'https://weft.example.com' });
+ * console.log(connection.server.toString()); // "https://weft.example.com/"
+ * ```
+ */
+export declare function resolveConnection(options?: ConnectionOptions): ResolvedConnection;
+/** Record the address of a running server so later CLI commands can find it. */
+export declare function writeRunLockfile(server: string): Promise<void>;
+/** Remove the run lockfile when the recorded server shuts down. */
+export declare function removeRunLockfile(server: string): Promise<void>;

package/dist/connection.js

@@ -0,0 +1,161 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, rm } from "node:fs/promises";
+export const DEFAULT_WEFT_ADDRESS = "http://localhost:7233";
+
+export class ConnectionConfigurationError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ConnectionConfigurationError";
+  }
+}
+export function resolveConnection(options = {}) {
+  const context = resolveConnectionContext(options), server = resolveServerString(context), fallbackProfile = profileForToken(context, server), token = resolveToken(options.token ?? Bun.env.WEFT_TOKEN, fallbackProfile);
+  return {
+    server: parseServerUrl(server),
+    ...token === void 0 ? {} : { token }
+  };
+}
+function parseServerUrl(server) {
+  try {
+    return new URL(server);
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : String(error);
+    throw new ConnectionConfigurationError(`Invalid server URL '${server}': ${reason}`);
+  }
+}
+function profileForToken(context, resolvedServer) {
+  if (context.profile === void 0)
+    return;
+  if (!(context.options.server !== void 0 || Bun.env.WEFT_ADDR !== void 0))
+    return context.profile;
+  const profileServer = context.profile.server;
+  if (profileServer === void 0)
+    return;
+  return sameDestination(resolvedServer, profileServer) ? context.profile : void 0;
+}
+function sameDestination(a, b) {
+  let left, right;
+  try {
+    left = new URL(a);
+    right = new URL(b);
+  } catch {
+    return a === b;
+  }
+  return left.origin === right.origin && left.pathname.replace(/\/+$/, "") === right.pathname.replace(/\/+$/, "");
+}
+function resolveConnectionContext(options) {
+  const configuration = readWeftConfiguration(), profileName = options.profile ?? Bun.env.WEFT_PROFILE ?? configuration.defaultProfile, profile = profileName === void 0 ? void 0 : configuration.profiles?.[profileName], runLockfile = options.includeRunLockfile === !1 ? void 0 : readRunLockfile();
+  return {
+    options,
+    ...profile === void 0 ? {} : { profile },
+    ...runLockfile === void 0 ? {} : { runLockfile }
+  };
+}
+function resolveServerString(context) {
+  return context.options.server ?? Bun.env.WEFT_ADDR ?? context.profile?.server ?? context.runLockfile?.server ?? context.runLockfile?.url ?? DEFAULT_WEFT_ADDRESS;
+}
+export async function writeRunLockfile(server) {
+  await mkdir(weftHome(), { recursive: !0 });
+  await Bun.write(runLockfilePath(), `${JSON.stringify({ server }, null, 2)}
+`);
+}
+export async function removeRunLockfile(server) {
+  const lockfile = readRunLockfile();
+  if (lockfile === void 0)
+    return;
+  if ((lockfile.server ?? lockfile.url) !== server)
+    return;
+  await rm(runLockfilePath(), { force: !0 });
+}
+function readWeftConfiguration() {
+  const path = configurationPath();
+  if (!existsSync(path))
+    return {};
+  let parsed;
+  try {
+    parsed = Bun.TOML.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ConnectionConfigurationError(`Failed to read connection configuration at ${path}: ${message}`);
+  }
+  return normalizeConfiguration(parsed);
+}
+function readRunLockfile() {
+  const path = runLockfilePath();
+  if (!existsSync(path))
+    return;
+  const text = readFileSync(path, "utf8").trim();
+  if (text === "")
+    return;
+  try {
+    return normalizeRunLockfile(JSON.parse(text));
+  } catch {
+    return;
+  }
+}
+function normalizeConfiguration(value) {
+  if (!isRecord(value))
+    return {};
+  const profiles = normalizeProfiles(value.profiles), defaultProfile = stringValue(value.defaultProfile ?? value.default_profile);
+  return {
+    ...defaultProfile === void 0 ? {} : { defaultProfile },
+    profiles
+  };
+}
+function normalizeProfiles(value) {
+  const profiles = {};
+  if (!isRecord(value))
+    return profiles;
+  for (const [name, profile] of Object.entries(value)) {
+    const normalized = normalizeProfile(profile);
+    if (normalized !== void 0)
+      profiles[name] = normalized;
+  }
+  return profiles;
+}
+function normalizeProfile(value) {
+  if (!isRecord(value))
+    return;
+  const server = stringValue(value.server), token = stringValue(value.token), tokenEnv = stringValue(value.tokenEnv ?? value.token_env);
+  return {
+    ...server === void 0 ? {} : { server },
+    ...token === void 0 ? {} : { token },
+    ...tokenEnv === void 0 ? {} : { tokenEnv }
+  };
+}
+function normalizeRunLockfile(value) {
+  if (!isRecord(value))
+    return;
+  const server = stringValue(value.server), url = stringValue(value.url);
+  if (server === void 0 && url === void 0)
+    return;
+  return {
+    ...server === void 0 ? {} : { server },
+    ...url === void 0 ? {} : { url }
+  };
+}
+function resolveToken(token, profile) {
+  const directToken = token ?? profile?.token;
+  if (directToken?.startsWith("env:"))
+    return Bun.env[directToken.slice(4)];
+  if (directToken !== void 0)
+    return directToken;
+  if (profile?.tokenEnv !== void 0)
+    return Bun.env[profile.tokenEnv];
+  return;
+}
+function configurationPath() {
+  return `${weftHome()}/config`;
+}
+function runLockfilePath() {
+  return `${weftHome()}/run`;
+}
+function weftHome() {
+  return Bun.env.WEFT_HOME ?? `${Bun.env.HOME ?? "."}/.weft`;
+}
+function stringValue(value) {
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/dist/core/activity-registry.d.ts

@@ -0,0 +1,135 @@
+/**
+ * WeakMap-backed activity registry.
+ *
+ * Metadata is keyed to function references in a WeakMap so that lookup by
+ * function reference is O(1). A separate name index (plain Map) holds strong
+ * references to registered functions, keeping them alive until explicitly
+ * unregistered. When a function is unregistered, removing it from the name
+ * index releases the strong reference and allows the WeakMap entry to be
+ * collected.
+ *
+ * @module core/activity-registry
+ */
+import { type DefinitionSchema, type Duration, type RetryPolicy } from './types.ts';
+/**
+ * Metadata stored per-activity, keyed to the function reference in a WeakMap.
+ *
+ * @example
+ * ```ts
+ * import { ActivityRegistry, type ActivityMetadata } from '@lostgradient/weft';
+ *
+ * const registry = new ActivityRegistry();
+ * const fn = async (input: unknown) => ({ result: input });
+ * registry.register('processOrder', fn, { queue: 'orders', timeout: '30s' });
+ *
+ * const meta: ActivityMetadata | undefined = registry.getMetadata(fn);
+ * console.log(meta?.name);   // 'processOrder'
+ * console.log(meta?.queue);  // 'orders'
+ * ```
+ */
+export interface ActivityMetadata {
+    /** Registered activity name. */
+    name: string;
+    /** Queue used for activity dispatch. */
+    queue: string;
+    /** User-facing description for catalog, code generation, and tool surfaces. */
+    description?: string;
+    /** User-facing grouping tags for catalog and documentation surfaces. */
+    tags?: ReadonlyArray<string>;
+    /** Optional input schema metadata for introspection; core execution does not validate input against it. */
+    inputSchema?: DefinitionSchema;
+    /** Optional output schema metadata for introspection; core execution does not validate output against it. */
+    outputSchema?: DefinitionSchema;
+    /** Retry policy used when the activity fails. */
+    retry?: RetryPolicy;
+    /** Activity execution timeout. */
+    timeout?: Duration;
+    /** Whether the activity can be safely repeated. */
+    idempotent?: boolean;
+}
+/**
+ * Optional overrides when registering an activity.
+ *
+ * @example
+ * ```ts
+ * import { ActivityRegistry, type ActivityRegistrationOptions } from '@lostgradient/weft';
+ *
+ * const options: ActivityRegistrationOptions = {
+ *   queue: 'high-priority',
+ *   timeout: '60s',
+ *   idempotent: true,
+ * };
+ *
+ * const registry = new ActivityRegistry();
+ * const fn = async (input: unknown) => input;
+ * registry.register('sendNotification', fn, options);
+ * ```
+ */
+export interface ActivityRegistrationOptions {
+    /** Queue used for activity dispatch. */
+    queue?: string;
+    /** User-facing description for catalog, code generation, and tool surfaces. */
+    description?: string;
+    /** User-facing grouping tags for catalog and documentation surfaces. */
+    tags?: ReadonlyArray<string>;
+    /** Optional input schema metadata for introspection; registration validates metadata shape only. */
+    inputSchema?: DefinitionSchema;
+    /** Optional output schema metadata for introspection; registration validates metadata shape only. */
+    outputSchema?: DefinitionSchema;
+    /** Retry policy used when the activity fails. */
+    retry?: RetryPolicy;
+    /** Activity execution timeout. */
+    timeout?: Duration;
+    /** Whether the activity can be safely repeated. */
+    idempotent?: boolean;
+}
+export type RegisteredActivityFunction = (input?: unknown, context?: unknown) => unknown;
+export declare function copyActivityMetadata(metadata: ActivityMetadata): ActivityMetadata;
+/**
+ * WeakMap-backed registry mapping activity names to their execute functions
+ * and metadata. Used internally by the {@link Engine} to dispatch activities
+ * by name. Call `engine.register(activityDefinition)` rather than
+ * constructing an `ActivityRegistry` directly — the engine manages the
+ * registry lifecycle.
+ *
+ * @example
+ * ```ts
+ * import { ActivityRegistry } from '@lostgradient/weft';
+ *
+ * const registry = new ActivityRegistry();
+ * const fn = async (input: unknown) => ({ result: input });
+ * registry.register('processOrder', fn, { queue: 'orders', timeout: '30s' });
+ *
+ * const meta = registry.getMetadata(fn);
+ * console.log(meta?.name);   // 'processOrder'
+ * console.log(meta?.queue);  // 'orders'
+ * ```
+ */
+export declare class ActivityRegistry {
+    #private;
+    constructor();
+    /**
+     * Register an activity function with associated metadata.
+     *
+     * If `fn` was created via the `activity()` helper, metadata is
+     * auto-extracted from its colocated properties. Explicit `options`
+     * take precedence over auto-extracted values.
+     */
+    register(name: string, fn: Function, options?: ActivityRegistrationOptions): void;
+    /** Check whether an activity is registered under the given name. */
+    has(name: string): boolean;
+    /** Resolve a function by its registered name. Returns `undefined` if not found. */
+    resolve(name: string): RegisteredActivityFunction | undefined;
+    /** Get metadata for a function reference. Returns `undefined` if the function was never registered. */
+    getMetadata(fn: Function): ActivityMetadata | undefined;
+    /** Get metadata by registered activity name. */
+    getMetadataByName(name: string): ActivityMetadata | undefined;
+    /** Get catalog metadata for a registered activity name. */
+    getDefinition(name: string): ActivityMetadata | undefined;
+    /** List catalog metadata for all registered activity names. */
+    listDefinitions(): ActivityMetadata[];
+    /** Remove an activity registration by name. */
+    unregister(name: string): void;
+    /** Iterate over all registered activity names. */
+    names(): IterableIterator<string>;
+}

package/dist/core/activity-registry.js

@@ -0,0 +1,174 @@
+import {
+  validateDefinitionSchemaMetadata
+} from "./types.js";
+import { validateWorkflowOrActivityName } from "./types/name-grammar.js";
+function extractDefinitionMetadata(name, fn) {
+  const record = fn;
+  return {
+    ...extractCatalogMetadata(record),
+    ...extractSchemaMetadata(name, record),
+    ...extractDispatchMetadata(record)
+  };
+}
+function extractCatalogMetadata(record) {
+  return {
+    ...typeof record.description === "string" ? { description: record.description } : {},
+    ...Array.isArray(record.tags) && record.tags.every((tag) => typeof tag === "string") ? { tags: [...record.tags] } : {}
+  };
+}
+function extractSchemaMetadata(name, record) {
+  return {
+    ..."inputSchema" in record ? {
+      inputSchema: validateDefinitionSchemaMetadata(record.inputSchema, `activity definition "${name}".inputSchema`)
+    } : {},
+    ..."outputSchema" in record ? {
+      outputSchema: validateDefinitionSchemaMetadata(record.outputSchema, `activity definition "${name}".outputSchema`)
+    } : {}
+  };
+}
+function extractDispatchMetadata(record) {
+  return {
+    ...typeof record.queue === "string" ? { queue: record.queue } : {},
+    ...isRetryPolicyCandidate(record.retry) ? { retry: record.retry } : {},
+    ...typeof record.timeout === "string" || typeof record.timeout === "number" ? { timeout: record.timeout } : {},
+    ...typeof record.idempotent === "boolean" ? { idempotent: record.idempotent } : {}
+  };
+}
+function isRetryPolicyCandidate(value) {
+  return typeof value === "object" && value !== null;
+}
+export function copyActivityMetadata(metadata) {
+  return {
+    name: metadata.name,
+    queue: metadata.queue,
+    ...metadata.description === void 0 ? {} : { description: metadata.description },
+    ...metadata.tags === void 0 ? {} : { tags: [...metadata.tags] },
+    ...metadata.inputSchema === void 0 ? {} : { inputSchema: metadata.inputSchema },
+    ...metadata.outputSchema === void 0 ? {} : { outputSchema: metadata.outputSchema },
+    ...metadata.retry === void 0 ? {} : { retry: copyRetryPolicy(metadata.retry) },
+    ...metadata.timeout === void 0 ? {} : { timeout: metadata.timeout },
+    ...metadata.idempotent === void 0 ? {} : { idempotent: metadata.idempotent }
+  };
+}
+function copyRetryPolicy(retry) {
+  return {
+    ...retry,
+    ...retry.nonRetryableErrors === void 0 ? {} : { nonRetryableErrors: [...retry.nonRetryableErrors] }
+  };
+}
+function resolveSchemaMetadata(name, extracted, options) {
+  const inputSchema = options?.inputSchema === void 0 ? extracted.inputSchema : validateDefinitionSchemaMetadata(options.inputSchema, `activity registration "${name}".inputSchema`), outputSchema = options?.outputSchema === void 0 ? extracted.outputSchema : validateDefinitionSchemaMetadata(options.outputSchema, `activity registration "${name}".outputSchema`);
+  return {
+    ...inputSchema === void 0 ? {} : { inputSchema },
+    ...outputSchema === void 0 ? {} : { outputSchema }
+  };
+}
+function preferOptionValue(optionValue, extractedValue) {
+  return optionValue ?? extractedValue;
+}
+function applyOptionalActivityMetadata(metadata, values) {
+  if (values.description !== void 0)
+    metadata.description = values.description;
+  if (values.tags !== void 0)
+    metadata.tags = [...values.tags];
+  if (values.inputSchema !== void 0)
+    metadata.inputSchema = values.inputSchema;
+  if (values.outputSchema !== void 0)
+    metadata.outputSchema = values.outputSchema;
+  if (values.retry !== void 0)
+    metadata.retry = copyRetryPolicy(values.retry);
+  if (values.timeout !== void 0)
+    metadata.timeout = values.timeout;
+  if (values.idempotent !== void 0)
+    metadata.idempotent = values.idempotent;
+}
+function assignOptionalActivityMetadataValue(metadata, key, value) {
+  if (value !== void 0)
+    metadata[key] = value;
+}
+function buildOptionalActivityMetadata(name, extracted, options) {
+  const optionalMetadata = {
+    ...resolveSchemaMetadata(name, extracted, options)
+  };
+  assignOptionalActivityMetadataValue(optionalMetadata, "description", preferOptionValue(options?.description, extracted.description));
+  assignOptionalActivityMetadataValue(optionalMetadata, "tags", preferOptionValue(options?.tags, extracted.tags));
+  assignOptionalActivityMetadataValue(optionalMetadata, "retry", preferOptionValue(options?.retry, extracted.retry));
+  assignOptionalActivityMetadataValue(optionalMetadata, "timeout", preferOptionValue(options?.timeout, extracted.timeout));
+  assignOptionalActivityMetadataValue(optionalMetadata, "idempotent", preferOptionValue(options?.idempotent, extracted.idempotent));
+  return optionalMetadata;
+}
+function buildActivityMetadata(name, extracted, options) {
+  const metadata = {
+    name,
+    queue: preferOptionValue(options?.queue, extracted.queue) ?? "default"
+  };
+  applyOptionalActivityMetadata(metadata, buildOptionalActivityMetadata(name, extracted, options));
+  return metadata;
+}
+
+export class ActivityRegistry {
+  #metadata;
+  #definitions;
+  #nameIndex;
+  constructor() {
+    this.#metadata = new WeakMap;
+    this.#definitions = new Map;
+    this.#nameIndex = new Map;
+  }
+  #retargetFunctionMetadata(fn, excludingName) {
+    let replacementMetadata;
+    for (const [registeredName, registeredFn] of this.#nameIndex)
+      if (registeredName !== excludingName && registeredFn === fn)
+        replacementMetadata = this.#definitions.get(registeredName);
+    if (replacementMetadata === void 0)
+      this.#metadata.delete(fn);
+    else
+      this.#metadata.set(fn, replacementMetadata);
+  }
+  register(name, fn, options) {
+    validateWorkflowOrActivityName(name, "activity");
+    const existingFn = this.#nameIndex.get(name);
+    if (existingFn && existingFn !== fn)
+      this.#retargetFunctionMetadata(existingFn, name);
+    const extracted = extractDefinitionMetadata(name, fn), metadata = buildActivityMetadata(name, extracted, options);
+    this.#metadata.set(fn, metadata);
+    this.#definitions.set(name, metadata);
+    this.#nameIndex.set(name, fn);
+  }
+  has(name) {
+    return this.#nameIndex.has(name);
+  }
+  resolve(name) {
+    const fn = this.#nameIndex.get(name);
+    if (!fn)
+      return;
+    return fn;
+  }
+  getMetadata(fn) {
+    const metadata = this.#metadata.get(fn);
+    return metadata === void 0 ? void 0 : copyActivityMetadata(metadata);
+  }
+  getMetadataByName(name) {
+    return this.getDefinition(name);
+  }
+  getDefinition(name) {
+    const metadata = this.#definitions.get(name);
+    return metadata === void 0 ? void 0 : copyActivityMetadata(metadata);
+  }
+  listDefinitions() {
+    return [...this.#nameIndex.keys()].flatMap((name) => {
+      const metadata = this.getDefinition(name);
+      return metadata === void 0 ? [] : [metadata];
+    });
+  }
+  unregister(name) {
+    const fn = this.#nameIndex.get(name);
+    this.#nameIndex.delete(name);
+    this.#definitions.delete(name);
+    if (fn)
+      this.#retargetFunctionMetadata(fn);
+  }
+  *names() {
+    yield* this.#nameIndex.keys();
+  }
+}

package/dist/core/activity.d.ts

@@ -0,0 +1,2 @@
+export { activity } from './types.ts';
+export type { ActivityCallable, ActivityDefinition, ActivityFunction } from './types.ts';

package/dist/core/activity.js

@@ -0,0 +1 @@
+export { activity } from "./types.js";

package/dist/core/aggregate-validation.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Shared schema and normalizer for `engine.aggregate()` options — the
+ * `groupBy` dimension and the optional `limit` on returned groups. Lives
+ * in `core/` so in-process callers and the server operation share one
+ * validation path.
+ *
+ * The list-filter portion of aggregate input is validated by
+ * {@link normalizeListFilter} in `list-filter-validation.ts`; this module
+ * covers only the aggregate-specific options.
+ *
+ * @module core/aggregate-validation
+ */
+import { z } from 'zod';
+import { WeftError } from './weft-error.ts';
+/**
+ * Group-by dimension for `engine.aggregate()`. Either a fixed structural
+ * dimension or an arbitrary search-attribute name.
+ */
+export type AggregateGroupBy = 'status' | 'type' | 'failureCategory' | {
+    attribute: string;
+};
+/**
+ * Validated options for `engine.aggregate()`. `limit` bounds the number
+ * of groups returned; `undefined` means "use the engine default."
+ */
+export type AggregateOptions = {
+    groupBy: AggregateGroupBy;
+    limit?: number;
+};
+/**
+ * Default and maximum bounds on the number of groups returned. Groups
+ * over the requested limit set `truncated: true` on the response.
+ */
+export declare const AGGREGATE_DEFAULT_LIMIT = 1000;
+export declare const AGGREGATE_MAX_LIMIT = 10000;
+/**
+ * Hard cap on the number of distinct group keys the engine will
+ * materialize for a single aggregate query. Exceeding it raises
+ * {@link AggregateDistinctKeyCapExceededError}; transport layers map
+ * the error to `Unprocessable`. The cap protects against an unbounded
+ * group-by on a high-cardinality attribute exhausting memory; it is
+ * never silently truncated because scan-order would bias which groups
+ * "win."
+ */
+export declare const MAX_AGGREGATE_DISTINCT_KEYS = 100000;
+/**
+ * Concrete object schema for {@link AggregateOptions}. Exported so the
+ * server operation can `.extend()` it onto the list-filter schema.
+ */
+export declare const aggregateOptionsObjectSchema: z.ZodObject<{
+    groupBy: z.ZodUnion<readonly [z.ZodLiteral<"status">, z.ZodLiteral<"type">, z.ZodLiteral<"failureCategory">, z.ZodObject<{
+        attribute: z.ZodString;
+    }, z.core.$strict>]>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+/** A flattened Zod issue suitable for cross-transport serialization. */
+export type AggregateOptionsValidationIssue = {
+    readonly path: ReadonlyArray<string | number>;
+    readonly message: string;
+    readonly code: string;
+};
+/**
+ * Thrown by {@link normalizeAggregateOptions} when input fails validation.
+ * Carries flattened Zod issues so transport adapters can map directly to
+ * the existing `InvalidParams` fault shape.
+ */
+export declare class AggregateOptionsValidationError extends WeftError<'AggregateOptionsValidationError'> {
+    readonly issues: ReadonlyArray<AggregateOptionsValidationIssue>;
+    constructor(issues: ReadonlyArray<AggregateOptionsValidationIssue>);
+}
+/**
+ * Thrown when an aggregate query would materialize more distinct group
+ * keys than {@link MAX_AGGREGATE_DISTINCT_KEYS}. Caller is expected to
+ * narrow the filter or pick a lower-cardinality `groupBy`.
+ */
+export declare class AggregateDistinctKeyCapExceededError extends WeftError<'AggregateDistinctKeyCapExceededError'> {
+    readonly cap: number;
+    constructor(cap: number);
+}
+/**
+ * Parse and validate aggregate options. Returns a typed copy on success;
+ * throws {@link AggregateOptionsValidationError} on failure with
+ * structured issues.
+ */
+export declare function normalizeAggregateOptions(input: unknown): AggregateOptions;