/**
 * Core operations module.
 *
 * Provides a stable, typed API surface for calling Neotoma's core actions
 * (store, retrieve, create_relationship, etc.) without going through the
 * MCP JSON-RPC protocol. This is the foundation used by:
 *   - `@neotoma/client` (local transport)
 *   - hook plugins for Claude Code, Cursor, OpenCode, Codex
 *   - Claude Agent SDK adapter
 *
 * Design:
 *   - Wraps the existing `NeotomaServer.executeToolForCli` dispatcher so we
 *     reuse every business rule, idempotency check, schema validation, and
 *     provenance construction already implemented there.
 *   - Parses the MCP-standard `{ content: [{ type, text }] }` response into
 *     typed return values.
 *   - Exposes a `createOperations({ userId })` factory so each caller gets
 *     a bound instance with its authenticated user.
 *
 * See `docs/developer/mcp/instructions.md` for the semantic contract that
 * agents follow when storing and retrieving through these operations.
 */
import { NeotomaServer } from "../server.js";
export interface CreateOperationsOptions {
    userId: string;
    /** Optional pre-constructed server instance. If omitted, a new one is created lazily. */
    server?: NeotomaServer;
}
export interface StoreEntityInput {
    entity_type: string;
    [key: string]: unknown;
}
export interface StoreRelationshipInput {
    relationship_type: string;
    source_index?: number;
    target_index?: number;
    source_entity_id?: string;
    target_entity_id?: string;
    metadata?: Record<string, unknown>;
}
export interface StoreInput {
    entities?: StoreEntityInput[];
    relationships?: StoreRelationshipInput[];
    idempotency_key?: string;
    file_path?: string;
    file_content?: string;
    mime_type?: string;
    file_idempotency_key?: string;
    original_filename?: string;
}
export interface StoredEntityRef {
    entity_id: string;
    entity_type: string;
    action?: "created" | "updated" | string;
    [key: string]: unknown;
}
export interface StoreResult {
    structured?: {
        entities: StoredEntityRef[];
        relationships?: unknown[];
    };
    unstructured?: {
        asset_entity_id?: string;
        [key: string]: unknown;
    };
    [key: string]: unknown;
}
export interface RetrieveEntitiesInput {
    entity_type?: string;
    limit?: number;
    offset?: number;
    since?: string;
    until?: string;
    [key: string]: unknown;
}
export interface RetrieveEntityByIdentifierInput {
    identifier: string;
    entity_type?: string;
}
export interface CreateRelationshipInput {
    relationship_type: string;
    source_entity_id: string;
    target_entity_id: string;
    source_id?: string;
    metadata?: Record<string, unknown>;
}
export interface CreateRelationshipsInput {
    relationships: CreateRelationshipInput[];
    source_id?: string;
}
export interface Operations {
    /** Store structured and/or unstructured data. See docs/developer/mcp/instructions.md. */
    store(input: StoreInput): Promise<StoreResult>;
    /** @deprecated Use {@link Operations.store}. */
    storeStructured(input: StoreInput): Promise<StoreResult>;
    /** @deprecated Use {@link Operations.store}. */
    storeUnstructured(input: StoreInput): Promise<StoreResult>;
    /** List entities by type or time window. */
    retrieveEntities(input: RetrieveEntitiesInput): Promise<unknown>;
    /** Look up a single entity by identifier (name, email, canonical_name, etc.). */
    retrieveEntityByIdentifier(input: RetrieveEntityByIdentifierInput): Promise<unknown>;
    /** Snapshot of a single entity. Pass format: "json" for machine-readable payloads (e.g. issue tooling). */
    retrieveEntitySnapshot(input: {
        entity_id: string;
        format?: string;
        at?: string;
    }): Promise<unknown>;
    /** List observations for provenance / history. */
    listObservations(input: {
        entity_id: string;
        limit?: number;
    }): Promise<unknown>;
    /** List timeline events for a time window. */
    listTimelineEvents(input: {
        since?: string;
        until?: string;
        limit?: number;
    }): Promise<unknown>;
    /** Retrieve related entities (graph expansion). */
    retrieveRelatedEntities(input: {
        entity_id: string;
        relationship_types?: string[];
        direction?: "inbound" | "outbound" | "both";
        max_hops?: number;
        include_entities?: boolean;
    }): Promise<unknown>;
    /** Create a relationship between two existing entities. */
    createRelationship(input: CreateRelationshipInput): Promise<unknown>;
    /** Create multiple relationships between existing entities. */
    createRelationships(input: CreateRelationshipsInput): Promise<unknown>;
    /** Correct an observation (creates a new observation that supersedes the prior). */
    correct(input: {
        entity_id: string;
        corrections: Record<string, unknown>;
    }): Promise<unknown>;
    /** List registered entity types (schema-level discovery). */
    listEntityTypes(input?: {
        search?: string;
    }): Promise<unknown>;
    /** Per-type entity counts. */
    getEntityTypeCounts(input?: Record<string, unknown>): Promise<unknown>;
    /** Raw escape hatch — invoke any MCP tool by name. */
    executeTool(name: string, args: unknown): Promise<unknown>;
    /** Dispose the internal server instance if this factory created one. */
    dispose(): Promise<void>;
}
/**
 * Create a bound operations client for a given user.
 *
 * The caller is responsible for providing `userId` — this mirrors the
 * existing `executeToolForCli` contract and lets the same process serve
 * multiple users (e.g. API server mode). For single-user local mode use
 * the local dev user id from `services/local_auth.ts`.
 */
export declare function createOperations(options: CreateOperationsOptions): Operations;
export type { NeotomaServer };
//# sourceMappingURL=operations.d.ts.map