/**
 * Studio's client for the FeltDB control plane.
 *
 * Every request Studio makes goes through this file, and every method here is
 * one public FeltDB route. That is the whole architectural rule, expressed as
 * code: Studio is a *caller* of FeltDB, not a second implementation of it.
 *
 * Three things this client will never do, because doing any of them would make
 * Studio's claims untestable from outside Studio:
 *
 * 1. read state files, storage, or any other side channel;
 * 2. reconstruct state the server did not compute — no client-side diffing,
 *    conflict guessing, or "derived" record history;
 * 3. return placeholder data when a request fails or a capability is absent.
 *
 * A capability the server does not declare has no method here that pretends
 * otherwise. Callers ask {@link CapabilitySet} first and render an explicit
 * unavailable state when the answer is no.
 */
export type CapabilityStatus = 'available' | 'partial' | 'unsupported';
export interface ControlPlaneCapability {
    id: string;
    area: string;
    title: string;
    status: CapabilityStatus;
    /** Public routes serving this capability. Empty exactly when unsupported. */
    surface: string[];
    /** Why the status is what it is. Always present unless available. */
    note: string;
}
export interface CapabilityDeclaration {
    contract: string;
    version: number;
    capabilities: ControlPlaneCapability[];
}
/**
 * What the connected instance says it can do.
 *
 * An unknown id reads as unsupported rather than as available. A Studio built
 * against a newer server must not draw controls an older one cannot serve, and
 * defaulting the other way would make every version skew a broken button.
 */
export declare class CapabilitySet {
    readonly declaration: CapabilityDeclaration | null;
    private readonly byId;
    constructor(declaration: CapabilityDeclaration | null);
    get loaded(): boolean;
    get(id: string): ControlPlaneCapability | undefined;
    status(id: string): CapabilityStatus;
    /** Usable at all: available outright, or available for some inputs. */
    usable(id: string): boolean;
    note(id: string): string;
    area(area: string): ControlPlaneCapability[];
}
export declare class ControlPlaneError extends Error {
    readonly code: string;
    readonly status: number;
    constructor(code: string, message: string, status: number);
}
export interface ControlPlaneOptions {
    baseUrl?: string;
    token?: string;
    applicationId?: string;
    environment?: string;
    fetch?: typeof globalThis.fetch;
}
/** A semantic path: object keys are strings, array indices are numbers. */
export type StatePath = Array<string | number>;
export interface StateRevisionSummary {
    state_id: string;
    resource: string;
    content_id: string;
    parent_id: string | null;
    sequence: number;
    authority: string;
    timestamp_ms: number;
    metadata: Record<string, unknown>;
}
export interface StateRevisionDetail extends StateRevisionSummary {
    content: unknown;
    integrity_verified: boolean;
    parent: {
        status: 'root';
    } | {
        status: 'retained';
        revision: StateRevisionSummary;
    } | {
        status: 'expired' | 'missing';
        state_id: string;
    };
}
export interface SemanticChange {
    path: StatePath;
    kind: 'added' | 'removed' | 'changed';
    old_value: unknown;
    new_value: unknown;
}
export interface StateDiff {
    contract: string;
    changes: SemanticChange[];
    is_read_only: boolean;
    from: StateRevisionSummary;
    to: StateRevisionSummary;
    relationship: 'parent' | 'same-resource' | 'cross-resource';
}
export type ConflictClass = 'independent' | 'convergent' | 'conflict';
export interface PathConflict {
    path: StatePath;
    classification: ConflictClass;
    base_value: unknown;
    left_value: unknown;
    right_value: unknown;
}
export interface ConflictClassification {
    contract: string;
    overall: ConflictClass;
    path_conflicts: PathConflict[];
    revisions: {
        base: StateRevisionSummary;
        left: StateRevisionSummary;
        right: StateRevisionSummary;
    };
}
export interface ReconciliationPlanRequest {
    base: string;
    left: string;
    right: string;
    parent_choice: 'left' | 'right';
    overrides?: Array<{
        path: StatePath;
        value: unknown;
    }>;
}
export interface ReconciliationPreview {
    plan: ReconciliationPlanRequest;
    classification: ConflictClassification;
    preview: {
        content: unknown;
        content_id: string;
        parent: StateRevisionSummary;
    };
    unresolved: StatePath[];
}
export interface CollectionActions {
    collection: string;
    actions: Array<{
        name: string;
        operation: 'create' | 'update' | 'delete';
        input_fields: string[];
        required_capabilities: string[];
        audit: boolean;
    }>;
}
export interface ActionCatalogue {
    application: {
        application_id: string;
        environment: string;
    };
    revision_id: string;
    route: string;
    collections: CollectionActions[];
}
export interface IndexReport {
    application: {
        application_id: string;
        environment: string;
    };
    state_namespace: string;
    declared: Array<{
        name: string;
        collection: string;
        fields: Array<{
            field: string;
            backed: boolean;
        }>;
        unique: boolean;
        sparse: boolean;
        version: number;
        state: 'backed' | 'declared';
    }>;
    runtime_equality_indexes: Array<{
        capability: string;
        field: string;
    }>;
    access_paths: Array<{
        collection: string;
        fields: Array<{
            field: string;
            access_method: 'index' | 'scan';
        }>;
    }>;
}
export interface TransactionAttribution {
    transaction_id: string;
    /** The actor the caller authenticated as. Null when the commit named none. */
    subject: string | null;
    tenant_id: string | null;
    application_id: string | null;
    application_revision: string | null;
    base_revision: number;
    commit_revision: number;
    state_before: number;
    state_after: number;
    /** `capability:key` per mutation, truncated by the server. */
    keys: string[];
    /** Exact mutation count, whether or not `keys` lists them all. */
    operations: number;
    unix_ms: number;
}
export interface RecordProvenance {
    record: {
        collection: string;
        id: string;
        capability: string;
        key: string;
        resource: string;
    };
    operation: {
        type: 'insert' | 'update' | 'delete';
        instance_id: string;
        sequence: number;
        vector_clock: Record<string, number> | null;
        state_id: string | null;
    } | null;
    content_hash: string | null;
    updated_ms: number;
    transactions: TransactionAttribution[];
    revisions: StateRevisionSummary[];
    attribution: {
        actor: string | null;
        authority: string | null;
        source: 'transaction' | 'authority' | 'unknown';
    };
}
export interface AgentSummary {
    agent_id: string;
    name: string;
    status: string;
    capabilities: string[];
    created_by: string;
    created_at: number;
    version: number;
    application_id: string;
    sessions: {
        total: number;
        running: number;
    };
    activity: {
        recent_transactions: number;
        records_changed: number;
        last_activity_ms: number | null;
    };
}
export interface AgentDetail {
    identity: {
        agent_id: string;
        name: string;
        kind: string;
        status: string;
        application_id: string;
        environment: string;
        application_revision: string;
        created_by: string;
        created_at: number;
        version: number;
    };
    access: {
        capabilities: string[];
        collections: Array<{
            collection: string;
            read: {
                policy: string | null;
                capabilities: string[];
            };
            write: {
                policy: string | null;
                actions: Array<{
                    name: string;
                    operation: 'create' | 'update' | 'delete';
                    required_capabilities: string[];
                    permitted: boolean;
                }>;
            };
        }>;
    };
    did: {
        transactions: TransactionAttribution[];
        records_changed: number;
        last_activity_ms: number | null;
    };
    doing: {
        sessions: Array<{
            session_id: string;
            kind: string;
            name: string;
            status: string;
            capabilities: string[];
            worker_id: string | null;
            started_at: number | null;
            completed_at: number | null;
            created_by: string;
        }>;
        work: Array<Record<string, any>>;
    };
    authorization_decisions: Array<{
        event: string;
        actor: string;
        principal_id: string;
        capability: string | null;
        decision: boolean | null;
        at: number;
    }>;
}
export interface OperationSummary {
    operation_id: number;
    type: 'insert' | 'update' | 'delete';
    capability: string;
    collection: string;
    key: string;
    instance_id: string;
    sequence: number;
    timestamp_ms: number;
    content_hash: string;
    vector_clock: Record<string, number> | null;
    state_id: string | null;
}
export interface AuthorityStateSummary {
    current_sequence: number;
    records: number;
    events: number;
    collections: Array<{
        collection: string;
        records: number;
    }>;
}
export declare class ControlPlaneApi {
    private readonly options;
    private readonly fetcher;
    constructor(options?: ControlPlaneOptions);
    private origin;
    private url;
    private request;
    private get;
    private post;
    capabilities(): Promise<CapabilitySet>;
    overview(): Promise<Record<string, any> & {
        authority_state: AuthorityStateSummary;
    }>;
    diagnostics(): Promise<Record<string, any>>;
    developer(): Promise<Record<string, any>>;
    actions(): Promise<ActionCatalogue>;
    indexes(): Promise<IndexReport>;
    rebuildIndex(collection: string, field: string): Promise<Record<string, any>>;
    /**
     * Runs one declared action.
     *
     * The route is the application runtime's action route — the same one an
     * application or an agent calls. Studio has no privileged write path, which
     * is why a collection with no declared action is simply not writable here.
     */
    runAction(revisionId: string, action: string, input: Record<string, unknown>): Promise<Record<string, any>>;
    operations(query?: {
        collection?: string;
        kind?: string;
        limit?: number;
    }): Promise<{
        operations: OperationSummary[];
        retained: Record<string, any>;
    }>;
    transactions(query?: {
        subject?: string;
        collection?: string;
        limit?: number;
    }): Promise<{
        transactions: TransactionAttribution[];
        window: {
            held: number;
            capacity: number;
            note: string;
        };
    }>;
    transaction(transactionId: string): Promise<{
        transaction_id: string;
        applied: boolean;
        idempotent_replay: string;
        attribution: TransactionAttribution | null;
        attribution_available: boolean;
    }>;
    /**
     * Everything the instance can say about how a record came to be as it is.
     *
     * Application records are scoped; a direct-authority record is not, so the
     * scope is omitted when no application is selected.
     */
    provenance(collection: string, id: string, scoped?: boolean): Promise<RecordProvenance>;
    agents(): Promise<{
        application: {
            application_id: string;
            environment: string;
        };
        agents: AgentSummary[];
    }>;
    agent(agentId: string): Promise<AgentDetail>;
    /** Registers an agent principal against the selected application. */
    registerAgent(name: string): Promise<{
        id: string;
        name: string;
        kind: string;
        capabilities: string[];
    }>;
    /** Grants one capability to a principal. One call, one capability. */
    grantAgentCapability(agentId: string, capability: string): Promise<Record<string, any>>;
    /** Opens a session for an agent: a workload principal under that agent. */
    startAgentSession(agentId: string): Promise<Record<string, any>>;
    workloads(): Promise<{
        workloads: Array<Record<string, any>>;
    }>;
    replication(): Promise<Record<string, any>>;
    applications(): Promise<{
        applications: Array<Record<string, any>>;
    }>;
    stateResources(query?: {
        prefix?: string;
        limit?: number;
    }): Promise<{
        resources: Array<{
            resource: string;
            revisions: number;
            head: StateRevisionSummary | null;
        }>;
    }>;
    stateHistory(resource: string): Promise<{
        resource: string;
        retention: {
            keep_last: number | null;
            horizon: number;
        };
        revisions: StateRevisionSummary[];
    }>;
    stateRevision(stateId: string): Promise<StateRevisionDetail>;
    stateDiff(from: string, to: string): Promise<StateDiff>;
    stateConflicts(base: string, left: string, right: string): Promise<ConflictClassification>;
    reconciliationPlan(request: ReconciliationPlanRequest): Promise<ReconciliationPreview>;
    reconciliationExecute(request: ReconciliationPlanRequest): Promise<{
        plan: ReconciliationPlanRequest;
        revision: StateRevisionDetail;
    }>;
}
/** Renders a semantic path the way the state model means it. */
export declare function formatStatePath(path: StatePath): string;
/** A message for a refused control-plane request, in the operator's terms. */
export declare function controlPlaneErrorMessage(error: unknown, subject?: string): string;
//# sourceMappingURL=control-plane-api.d.ts.map