/**
 * Data residency: each tenant's requests and data kept in the regions it requires. A policy says
 * which regions each tenant may reach and what runs where; the client's lifecycle routes every
 * provider call by it, and the regional stores write each tenant's traces and assets in its region.
 */
import type { AssetStore } from '../images/asset-support.js';
import type { RegionDefinition, ResidencyPolicy } from '../types/residency.js';
import type { Run, TraceStore } from '../types/tracing.js';
export { ResidencyError } from './errors.js';
export type { CallResidency, RegionDefinition, ResidencyDecision, ResidencyPlacement, ResidencyPolicy, ResidencyTarget, } from '../types/residency.js';
/** Regions as a rule names them: every region, none, one, or a list, the first the home. */
export type RegionRule = 'any' | 'refuse' | string | readonly string[];
/** Options for `residency()`. */
export interface ResidencyOptions {
    /** Every region, by name, with the providers that run in it and their twins. */
    regions: Readonly<Record<string, RegionDefinition>>;
    /**
     * Each tenant's regions, the first its home: a map, or a function, such as one that reads the
     * tenant's record. A tenant it says nothing of follows `unassigned`.
     */
    tenants?: Readonly<Record<string, RegionRule>> | ((tenantId: string) => RegionRule | undefined | Promise<RegionRule | undefined>);
    /** The regions of a tenant no rule names. Defaults to `any`; `refuse` refuses every one of its calls. */
    unassigned?: RegionRule;
    /** The regions of an operation with no tenant. Defaults to `any`. */
    untenanted?: RegionRule;
}
/** A policy from `residency()`, which also lists its regions. */
export interface Residency extends ResidencyPolicy {
    /** Every region, in the order the options name them. */
    regions(): string[];
}
/**
 * A residency policy: which regions each tenant may reach, the providers in each region, and the
 * twin of a provider inside a region, such as an EU endpoint of the same service. Give it to the
 * client as `lifecycle.residency`, and a tenant's calls never reach a provider outside its regions:
 * each is sent to the provider routing chose when it is inside, to its twin inside when there is
 * one, and refused with a `ResidencyError` naming the rule when neither.
 *
 * ```ts
 * const policy = residency({
 *   regions: {
 *     'eu-west': { providers: ['openai-eu', 'mistral'], twins: { openai: 'openai-eu' } },
 *     'us-east': { providers: ['openai', 'anthropic'] },
 *   },
 *   tenants: { acme: ['eu-west'], globex: 'any' },
 * });
 * ```
 */
export declare function residency(options: ResidencyOptions): Residency;
/** Options for `regionalTraceStore()`. */
export interface RegionalTraceStoreOptions {
    /** A trace store per region, by region. */
    stores: Readonly<Record<string, TraceStore>>;
    /** The residency policy. */
    residency: ResidencyPolicy;
    /**
     * The tenant a run belongs to. Defaults to its `metadata.tenantId`, or the `metadata.nexus.tenant`
     * an agent server records. A run without one goes where its trace went.
     */
    tenantOf?: (run: Run) => string | undefined;
    /** Where a trace with no tenant goes, when its operation may reach any region. Defaults to the first store. */
    defaultRegion?: string;
    /** Traces whose region is remembered, so their runs stay together. Defaults to 10,000. */
    maxTraces?: number;
}
/** A trace store across regions, with a view of one tenant's. */
export interface RegionalTraceStore extends TraceStore {
    /** Reads and writes one tenant's traces, in the regions it may reach only. */
    forTenant(tenantId: string): TraceStore;
    /** The region a trace was written in, when this store wrote it. */
    regionOfTrace(traceId: string): string | undefined;
}
/**
 * A trace store per region: each run is written in its tenant's home region, the first region it may
 * reach that has a store, and every run of a trace goes where the trace went. A run whose tenant may
 * reach no region with a store is refused with a `ResidencyError`, which a tracer reports through its
 * `onError`, and written nowhere. Queries read every region, newest first across them.
 */
export declare function regionalTraceStore(options: RegionalTraceStoreOptions): RegionalTraceStore;
/** Options for `regionalAssetStore()`. */
export interface RegionalAssetStoreOptions {
    /** An asset store per region, by region. */
    stores: Readonly<Record<string, AssetStore>>;
    /** The residency policy. */
    residency: ResidencyPolicy;
}
/**
 * An asset store per region: each asset is stored in its tenant's home region, the first region it
 * may reach that has a store, and read only from the regions the tenant may reach, so an asset is
 * never stored or served outside them. A tenant that may reach no region with a store is refused
 * with a `ResidencyError`, and nothing is stored.
 */
export declare function regionalAssetStore(options: RegionalAssetStoreOptions): AssetStore;