/**
 * BrainPort — knowledge archival + retrieval contract (4 memory tiers).
 *
 * Tier 1 — working: get/set with scope='run' + ttlMs auto-expire (A6, sprint-562).
 * Tier 2 — episodic: since/record per agentId (A6, sprint-562).
 * Tier 3 — semantic: query/archive shared across agents (C4, sprint-564).
 * Tier 4 — procedural: resolveSkills for learned/private/shared skills (C4, sprint-564).
 */
export interface BrainEntryInput {
    content: string;
    content_type?: string;
    author?: string;
    category?: string;
    tags?: string[];
    confidence?: number;
    metadata?: Record<string, unknown>;
    brain_id?: string;
}
export interface BrainEntry {
    id: string;
    content: string;
    category?: string;
    tags?: string[];
    metadata?: Record<string, unknown>;
    created_at?: string;
}
export interface BrainQueryFilters {
    category?: string;
    tags?: string[];
    limit?: number;
    [key: string]: unknown;
}
export interface WorkingMemoryPort {
    set(runId: string, key: string, value: unknown, opts?: {
        ttlMs?: number;
    }): Promise<void>;
    get(runId: string, key: string): Promise<unknown>;
    delete(runId: string, key: string): Promise<void>;
}
export declare class InMemoryWorkingMemory implements WorkingMemoryPort {
    private store;
    set(runId: string, key: string, value: unknown, opts?: {
        ttlMs?: number;
    }): Promise<void>;
    get(runId: string, key: string): Promise<unknown>;
    delete(runId: string, key: string): Promise<void>;
}
export interface EpisodicMemoryEntry {
    agentId: string;
    runId: string;
    event: string;
    metadata?: Record<string, unknown>;
    timestamp: number;
    /**
     * OTel trace ID associated with the run that produced this entry.
     * Optional for backward compatibility — existing entries without traceId
     * are never returned by queryByTrace.
     *
     * DB impact: migration 037_episodic_indexed_by_trace.sql adds
     * `trace_id TEXT` column + `idx_episodic_trace_id` B-tree index
     * on `episodic_memory(trace_id)`.
     */
    traceId?: string;
}
export interface EpisodicMemoryPort {
    /**
     * Record an episodic event.
     *
     * @param agentId - Owning agent.
     * @param runId   - Run (execution) identifier.
     * @param event   - Event name / label.
     * @param metadata - Arbitrary structured payload.
     * @param opts.traceId - OTel trace ID to associate with this entry (optional,
     *   non-breaking — callers that do not pass it produce entries invisible to queryByTrace).
     */
    record(agentId: string, runId: string, event: string, metadata?: Record<string, unknown>, opts?: {
        traceId?: string;
    }): Promise<void>;
    since(agentId: string, sinceMs: number, opts?: {
        limit?: number;
    }): Promise<EpisodicMemoryEntry[]>;
    /**
     * Retrieve all episodic entries associated with a given OTel trace ID,
     * ordered by insertion (ascending timestamp).
     *
     * @param traceId - OTel W3C trace ID (32 hex chars) or any opaque run-correlation key.
     * @param opts.limit - Maximum number of entries to return (default: unbounded).
     * @returns Entries matching traceId, oldest first.
     */
    queryByTrace(traceId: string, opts?: {
        limit?: number;
    }): Promise<EpisodicMemoryEntry[]>;
}
export declare class InMemoryEpisodicMemory implements EpisodicMemoryPort {
    private events;
    record(agentId: string, runId: string, event: string, metadata?: Record<string, unknown>, opts?: {
        traceId?: string;
    }): Promise<void>;
    since(agentId: string, sinceMs: number, opts?: {
        limit?: number;
    }): Promise<EpisodicMemoryEntry[]>;
    queryByTrace(traceId: string, opts?: {
        limit?: number;
    }): Promise<EpisodicMemoryEntry[]>;
}
export interface SemanticMemoryPort {
    /** Query shared knowledge across agents. */
    query(q: string, filters?: BrainQueryFilters): Promise<BrainEntry[]>;
    /** Archive shared knowledge. */
    archive(entry: BrainEntryInput): Promise<BrainEntry | null>;
}
export declare class InMemorySemanticMemory implements SemanticMemoryPort {
    private entries;
    query(q: string, filters?: BrainQueryFilters): Promise<BrainEntry[]>;
    archive(entry: BrainEntryInput): Promise<BrainEntry | null>;
}
export interface ProceduralSkill {
    name: string;
    description: string;
    source: "learning-loop" | "manual" | "shared";
    confidence: number;
    chainOfThought?: string;
}
export interface ProceduralMemoryPort {
    /** Resolve all skills available to an agent (learned + shared + private). */
    resolveSkills(agentId: string): Promise<ProceduralSkill[]>;
    /** Register a learned skill for an agent. */
    registerSkill(agentId: string, skill: ProceduralSkill): Promise<void>;
    /** Share a skill with other agents. */
    shareSkill(skillName: string, fromAgentId: string, toAgentIds: string[]): Promise<void>;
}
export declare class InMemoryProceduralMemory implements ProceduralMemoryPort {
    private skills;
    private shared;
    resolveSkills(agentId: string): Promise<ProceduralSkill[]>;
    registerSkill(agentId: string, skill: ProceduralSkill): Promise<void>;
    shareSkill(skillName: string, fromAgentId: string, toAgentIds: string[]): Promise<void>;
}
/**
 * Thrown when the Brain API is unreachable (connection refused, DNS failure,
 * timeout on connect). Callers can retry with backoff or fall back to a local cache.
 */
export declare class BrainUnavailableError extends Error {
    readonly cause?: unknown | undefined;
    constructor(message: string, cause?: unknown | undefined);
}
/**
 * Thrown when the Brain API returns 429 (rate limit exceeded).
 * Callers should retry after the delay indicated in the `retryAfterMs` field
 * (extracted from the Retry-After header) or use exponential backoff.
 */
export declare class BrainRateLimitError extends Error {
    readonly cause?: unknown | undefined;
    /** Retry-After delay in milliseconds. Derived from the HTTP Retry-After header. */
    readonly retryAfterMs: number;
    constructor(message: string, retryAfterMs: number, cause?: unknown | undefined);
}
/**
 * Input for archiving a campaign post-mortem.
 * Stored under category `vauban_postmortem` with tags
 * `["postmortem", "campaign:<slug>", "outcome:<outcome>"]`.
 */
export interface PostmortemInput {
    readonly campaign_slug: string;
    readonly outcome: "success" | "partial" | "failure";
    readonly metrics: Readonly<Record<string, number>>;
    readonly what_worked: readonly string[];
    readonly what_failed: readonly string[];
    readonly lessons: readonly string[];
}
/**
 * Input for archiving a reusable lesson learned.
 * Stored under category `vauban_lesson` with tags
 * `["lesson", ...applies_to]`.
 */
export interface LessonInput {
    readonly title: string;
    readonly context: string;
    readonly insight: string;
    readonly applies_to: readonly string[];
    readonly evidence: Readonly<Record<string, unknown>>;
}
export interface BrainPort {
    archiveKnowledge(entry: BrainEntryInput): Promise<BrainEntry | null>;
    queryKnowledge?(query: string, filters?: BrainQueryFilters): Promise<BrainEntry[]>;
    /**
     * Archive a campaign post-mortem. Optional — implementations that do not
     * override this fall back to the default in `HttpBrainAdapter`.
     */
    archivePostmortem?(input: PostmortemInput): Promise<void>;
    /**
     * Archive a reusable lesson learned. Optional — same fallback as above.
     */
    archiveLesson?(input: LessonInput): Promise<void>;
    working?: WorkingMemoryPort;
    episodic?: EpisodicMemoryPort;
    semantic?: SemanticMemoryPort;
    procedural?: ProceduralMemoryPort;
}
/**
 * Wrap any BrainPort implementation with OTel spans.
 * archiveKnowledge and queryKnowledge calls each get a span with the category
 * and content preview. Gracefully degrades to noop spans when no OTel SDK
 * is installed.
 *
 * Usage:
 *   const raw: BrainPort = buildHttpBrain(...);
 *   const traced = createTracedBrainPort(raw);
 *   await traced.archiveKnowledge({ content: "..." }) // emits "brain.archiveKnowledge" span
 */
export declare function createTracedBrainPort(impl: BrainPort): BrainPort;
//# sourceMappingURL=brain.d.ts.map