@agenr/skeln-plugin 3.3.0

package/dist/claim-slot-policy-CQ-h0GaV.d.ts

@@ -0,0 +1,880 @@
+/**
+ * Core domain types for agenr.
+ * These types have zero infrastructure dependencies.
+ */
+/** Ordered list of supported durable knowledge entry categories. */
+declare const ENTRY_TYPES: readonly ["fact", "decision", "preference", "lesson", "relationship", "milestone"];
+/**
+ * Union of all supported knowledge entry categories.
+ */
+type EntryType = (typeof ENTRY_TYPES)[number];
+/** Ordered list of supported recall durability levels. */
+declare const EXPIRY_LEVELS: readonly ["core", "permanent", "temporary"];
+/** Ordered list of supported claim-key lifecycle statuses. */
+declare const CLAIM_KEY_STATUSES: readonly ["trusted", "tentative", "unresolved"];
+/** Ordered list of supported claim-key provenance sources. */
+declare const CLAIM_KEY_SOURCES: readonly ["manual", "model", "json_retry", "deterministic_repair", "surgeon_metadata_rewrite", "surgeon_family_reuse", "surgeon_compaction"];
+/** Ordered list of supported claim-support provenance modes. */
+declare const CLAIM_SUPPORT_MODES: readonly ["explicit", "normalized", "inferred"];
+
+/**
+ * Union of all supported recall durability levels.
+ */
+type Expiry = (typeof EXPIRY_LEVELS)[number];
+/**
+ * Union of all supported claim-key lifecycle statuses.
+ */
+type ClaimKeyStatus = (typeof CLAIM_KEY_STATUSES)[number];
+/**
+ * Union of all supported claim-key provenance sources.
+ */
+type ClaimKeySource = (typeof CLAIM_KEY_SOURCES)[number];
+/**
+ * Union of all supported claim-support provenance modes.
+ */
+type ClaimSupportMode = (typeof CLAIM_SUPPORT_MODES)[number];
+/** Ordered list of supported episode sources. */
+declare const EPISODE_SOURCES: readonly ["openclaw", "skeln", "codex", "cli", "synthesis"];
+/** Ordered list of supported episode activity levels. */
+declare const EPISODE_ACTIVITY_LEVELS: readonly ["substantial", "minimal", "none"];
+/** Ordered list of supported procedure step kinds. */
+declare const PROCEDURE_STEP_KINDS: readonly ["run_command", "read_reference", "inspect_state", "edit_file", "ask_user", "invoke_tool", "verify"];
+/** Ordered list of supported procedure provenance source kinds. */
+declare const PROCEDURE_SOURCE_KINDS: readonly ["skill", "doc", "entry", "episode", "repo_file", "manual"];
+
+/**
+ * Union of all supported episode sources.
+ */
+type EpisodeSource = (typeof EPISODE_SOURCES)[number];
+/**
+ * Union of all supported episode activity levels.
+ */
+type EpisodeActivityLevel = (typeof EPISODE_ACTIVITY_LEVELS)[number];
+/**
+ * Union of all supported procedure step kinds.
+ */
+type ProcedureStepKind = (typeof PROCEDURE_STEP_KINDS)[number];
+/**
+ * Union of all supported procedure provenance source kinds.
+ */
+type ProcedureSourceKind = (typeof PROCEDURE_SOURCE_KINDS)[number];
+/**
+ * Explicit lifecycle and provenance metadata attached to a stored claim key.
+ */
+interface ClaimKeyLifecycleMetadata {
+    claim_key_raw?: string;
+    claim_key_status?: ClaimKeyStatus;
+    claim_key_source?: ClaimKeySource;
+    claim_key_confidence?: number;
+    claim_key_rationale?: string;
+    claim_support_source_kind?: string;
+    claim_support_locator?: string;
+    claim_support_observed_at?: string;
+    claim_support_mode?: ClaimSupportMode;
+}
+/**
+ * Canonical stored knowledge record.
+ */
+interface Entry extends ClaimKeyLifecycleMetadata {
+    id: string;
+    type: EntryType;
+    subject: string;
+    content: string;
+    importance: number;
+    expiry: Expiry;
+    tags: string[];
+    source_file?: string;
+    source_context?: string;
+    embedding?: number[];
+    content_hash?: string;
+    norm_content_hash?: string;
+    quality_score: number;
+    recall_count: number;
+    last_recalled_at?: string;
+    superseded_by?: string;
+    valid_from?: string;
+    valid_to?: string;
+    claim_key?: string;
+    supersession_kind?: string;
+    supersession_reason?: string;
+    cluster_id?: string;
+    user_id?: string;
+    project?: string;
+    retired: boolean;
+    retired_at?: string;
+    retired_reason?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Mutable entry fields supported by direct update paths.
+ *
+ * Claim-key lifecycle updates are replacement-style, not merge-style. When any
+ * lifecycle field is mutated, callers must provide one complete validated
+ * lifecycle payload for the target claim key. Partial lifecycle patches are
+ * rejected at the persistence boundary.
+ */
+interface EntryUpdateInput {
+    importance?: Entry["importance"];
+    expiry?: Entry["expiry"];
+    claim_key?: Entry["claim_key"];
+    claim_key_raw?: Entry["claim_key_raw"];
+    claim_key_status?: Entry["claim_key_status"];
+    claim_key_source?: Entry["claim_key_source"];
+    claim_key_confidence?: Entry["claim_key_confidence"];
+    claim_key_rationale?: Entry["claim_key_rationale"];
+    claim_support_source_kind?: Entry["claim_support_source_kind"];
+    claim_support_locator?: Entry["claim_support_locator"];
+    claim_support_observed_at?: Entry["claim_support_observed_at"];
+    claim_support_mode?: Entry["claim_support_mode"];
+    valid_from?: Entry["valid_from"];
+    valid_to?: Entry["valid_to"];
+}
+/**
+ * Canonical stored episodic-memory record.
+ */
+interface Episode {
+    id: string;
+    source: EpisodeSource;
+    sourceId?: string;
+    sourceRef?: string;
+    transcriptHash?: string;
+    summaryHash?: string;
+    agentId?: string;
+    surface?: string;
+    startedAt: string;
+    endedAt?: string;
+    summary: string;
+    tags: string[];
+    activityLevel?: EpisodeActivityLevel;
+    userId?: string;
+    project?: string;
+    genModel?: string;
+    genVersion?: string;
+    messageCount?: number;
+    embedding?: number[];
+    retired: boolean;
+    retiredAt?: string;
+    retiredReason?: string;
+    supersededBy?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Explicit authored provenance attached to a procedure or reference step.
+ */
+interface ProcedureSource {
+    kind: ProcedureSourceKind;
+    path?: string;
+    locator?: string;
+    label?: string;
+}
+/**
+ * Closed JSON-like value space accepted by `invoke_tool.arguments`.
+ */
+type ProcedureToolArgumentValue = string | number | boolean | null | {
+    [key: string]: ProcedureToolArgumentValue;
+} | ProcedureToolArgumentValue[];
+/**
+ * Condition that scopes a step to one supported harness value.
+ */
+interface ProcedureHarnessCondition {
+    kind: "harness_is";
+    value: string;
+}
+/**
+ * Condition that scopes a step to one available tool name.
+ */
+interface ProcedureToolAvailableCondition {
+    kind: "tool_available";
+    value: string;
+}
+/**
+ * Condition that requires one exact file path to exist.
+ */
+interface ProcedureFileExistsCondition {
+    kind: "file_exists";
+    path: string;
+}
+/**
+ * Condition that requires one path to exist.
+ */
+interface ProcedurePathExistsCondition {
+    kind: "path_exists";
+    path: string;
+}
+/**
+ * Condition that checks one environment flag by name and optional value.
+ */
+interface ProcedureEnvFlagCondition {
+    kind: "env_flag";
+    name: string;
+    value?: string;
+}
+/**
+ * Condition that checks one bounded repository-state marker.
+ */
+interface ProcedureRepoStateCondition {
+    kind: "repo_state";
+    value: string;
+}
+/**
+ * Condition that requires one explicit user confirmation token.
+ */
+interface ProcedureUserConfirmedCondition {
+    kind: "user_confirmed";
+    value: string;
+}
+/**
+ * Supported bounded declarative condition union for procedure steps.
+ */
+type ProcedureCondition = ProcedureHarnessCondition | ProcedureToolAvailableCondition | ProcedureFileExistsCondition | ProcedurePathExistsCondition | ProcedureEnvFlagCondition | ProcedureRepoStateCondition | ProcedureUserConfirmedCondition;
+/**
+ * Shared authored fields carried by every normalized procedure step.
+ */
+interface ProcedureStepBase {
+    id: string;
+    kind: ProcedureStepKind;
+    instruction: string;
+    conditions?: ProcedureCondition[];
+    stop_if?: ProcedureCondition[];
+}
+/**
+ * Step that records one shell command to run.
+ */
+interface ProcedureRunCommandStep extends ProcedureStepBase {
+    kind: "run_command";
+    command: string;
+}
+/**
+ * Step that points readers at an external reference.
+ */
+interface ProcedureReadReferenceStep extends ProcedureStepBase {
+    kind: "read_reference";
+    ref: ProcedureSource;
+}
+/**
+ * Step that asks the agent to inspect current state before continuing.
+ */
+interface ProcedureInspectStateStep extends ProcedureStepBase {
+    kind: "inspect_state";
+    target?: string;
+    query?: string;
+}
+/**
+ * Step that describes one file edit in human-readable terms.
+ */
+interface ProcedureEditFileStep extends ProcedureStepBase {
+    kind: "edit_file";
+    path: string;
+    edit: string;
+}
+/**
+ * Step that asks the agent to collect input from the user.
+ */
+interface ProcedureAskUserStep extends ProcedureStepBase {
+    kind: "ask_user";
+    prompt: string;
+}
+/**
+ * Step that invokes a structured tool with optional arguments.
+ */
+interface ProcedureInvokeToolStep extends ProcedureStepBase {
+    kind: "invoke_tool";
+    tool: string;
+    arguments?: {
+        [key: string]: ProcedureToolArgumentValue;
+    };
+}
+/**
+ * Step that checks whether the procedure completed successfully.
+ */
+interface ProcedureVerifyStep extends ProcedureStepBase {
+    kind: "verify";
+    checks: string[];
+}
+/**
+ * Supported authored procedure-step union.
+ */
+type ProcedureStep = ProcedureRunCommandStep | ProcedureReadReferenceStep | ProcedureInspectStateStep | ProcedureEditFileStep | ProcedureAskUserStep | ProcedureInvokeToolStep | ProcedureVerifyStep;
+/**
+ * Canonical normalized procedure body stored in `body_json`.
+ */
+interface ProcedureDefinition {
+    procedure_key: string;
+    title: string;
+    goal: string;
+    when_to_use: string[];
+    when_not_to_use: string[];
+    prerequisites: string[];
+    steps: ProcedureStep[];
+    verification: string[];
+    failure_modes: string[];
+    sources: ProcedureSource[];
+}
+/**
+ * Lifecycle and revision metadata stored alongside a procedure revision.
+ */
+interface ProcedureLifecycleMetadata {
+    recall_text: string;
+    revision_hash: string;
+    source_hash: string;
+    retired: boolean;
+    retired_at?: string;
+    retired_reason?: string;
+    superseded_by?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Canonical stored procedural-memory record.
+ */
+interface Procedure extends ProcedureDefinition, ProcedureLifecycleMetadata {
+    id: string;
+    source_file?: string;
+    embedding?: number[];
+}
+
+/**
+ * Aggregate active corpus counts for one entity prefix.
+ */
+interface ClaimKeyEntityPrefixStats {
+    entityPrefix: string;
+    activeEntryCount: number;
+    trustedEntryCount: number;
+    tentativeEntryCount: number;
+    unresolvedEntryCount: number;
+    legacyEntryCount: number;
+    deterministicRepairEntryCount: number;
+    manualEntryCount: number;
+    modelEntryCount: number;
+    jsonRetryEntryCount: number;
+    surgeonFamilyReuseEntryCount: number;
+}
+
+/**
+ * Write-time episode payload before adapter-managed identity and lifecycle fields are applied.
+ */
+interface EpisodeInput {
+    source: EpisodeSource;
+    sourceId?: string;
+    sourceRef?: string;
+    transcriptHash?: string;
+    summaryHash?: string;
+    agentId?: string;
+    surface?: string;
+    startedAt: string;
+    endedAt?: string;
+    summary: string;
+    tags?: string[];
+    activityLevel?: EpisodeActivityLevel;
+    userId?: string;
+    project?: string;
+    genModel?: string;
+    genVersion?: string;
+    messageCount?: number;
+    embedding?: number[];
+}
+/**
+ * Calendar-aware temporal constraint used by future episode retrieval.
+ */
+interface TemporalWindow {
+    kind: "interval" | "anchor" | "open_start" | "open_end";
+    start?: Date;
+    end?: Date;
+    anchor?: Date;
+    radiusDays?: number;
+    source: "explicit" | "inferred";
+}
+/**
+ * Upsert outcome returned by episode persistence adapters.
+ */
+interface EpisodeUpsertResult {
+    episode: Episode;
+    action: "inserted" | "updated" | "unchanged";
+}
+
+/**
+ * Internal ranking profiles that adjust recall scoring for specific query intents.
+ */
+type RecallRankingProfile = "historical_state" | "entity_attribute";
+/**
+ * Supported attribute buckets for precision-first entity recall.
+ */
+type EntityAttributeKind = "identity" | "location" | "email" | "phone" | "address";
+/**
+ * Narrow structured query shape for precision-first entity-attribute recall.
+ */
+interface EntityAttributeQueryShape {
+    kind: "entity_attribute";
+    entityText: string;
+    normalizedEntity: string;
+    entityTokens: string[];
+    attributeKind: EntityAttributeKind;
+    attributeTokens: string[];
+}
+/**
+ * Input to the v1 recall pipeline.
+ */
+interface RecallInput {
+    text: string;
+    limit?: number;
+    threshold?: number;
+    budget?: number;
+    types?: EntryType[];
+    tags?: string[];
+    since?: string;
+    until?: string;
+    around?: string;
+    aroundRadius?: number;
+    asOf?: string;
+    sessionKey?: string;
+    rankingProfile?: RecallRankingProfile;
+    queryShape?: EntityAttributeQueryShape;
+}
+/**
+ * A single scored recall result with signal breakdown metadata.
+ *
+ * The composite `score` is built from `relevance`, `recency`, and `importance`.
+ * `relevance` is the normalized reciprocal rank fusion (RRF) score computed in
+ * `src/core/recall/fusion.ts`. `vector` and `lexical` are retained as
+ * evidence-only diagnostics: they explain which retrieval channels admitted
+ * the candidate and let traces inspect raw similarity, but neither participates
+ * in the composite score directly now that RRF owns the fused signal.
+ */
+interface RecallOutput {
+    entry: Entry;
+    score: number;
+    scores: {
+        /** Fused reciprocal rank fusion score used as the composite relevance signal. */
+        relevance: number;
+        /** Alias of `relevance` that makes the RRF origin explicit in traces. */
+        rrf: number;
+        /** Evidence-only raw vector similarity score. Not part of the composite. */
+        vector: number;
+        /** Evidence-only raw lexical overlap score. Not part of the composite. */
+        lexical: number;
+        recency: number;
+        importance: number;
+        historicalLineage: number;
+        /** Seeded neighborhood rerank boost applied after RRF and historical lineage. */
+        neighborhoodBoost: number;
+        claimKeyTrustPenalty: number;
+        claimKeyRedundancyPenalty: number;
+        /**
+         * Raw cross-encoder score in the 0-1 range when the rerank stage
+         * produced one for this candidate. Absent when the candidate fell
+         * outside the shortlist, when the stage was disabled, or when the
+         * provider failed.
+         */
+        crossEncoder?: number;
+    };
+}
+/**
+ * Minimal entry fields needed during recall scoring before final hydration.
+ */
+type RecallCandidateEntry = Pick<Entry, "id" | "subject" | "content" | "importance" | "expiry" | "created_at" | "embedding" | "superseded_by" | "claim_key" | "claim_key_status" | "claim_support_observed_at" | "valid_from" | "valid_to" | "retired">;
+/**
+ * A candidate returned from vector search with ranking-time entry data.
+ */
+interface VectorCandidate {
+    entry: RecallCandidateEntry;
+    vectorSim: number;
+}
+/**
+ * A candidate returned from lexical FTS search with ranking-time entry data.
+ *
+ * BM25 rank controls admission order inside the lexical channel. That order
+ * is then folded into the reciprocal rank fusion pass in
+ * `src/core/recall/fusion.ts`, so the rank value itself is not part of the
+ * final composite score.
+ */
+interface FtsCandidate {
+    entry: RecallCandidateEntry;
+    rank: number;
+    tier: "exact" | "all_tokens" | "any_tokens";
+}
+/**
+ * Filters that the core recall pipeline can push down into adapter queries.
+ */
+interface EntryFilters {
+    types?: EntryType[];
+    tags?: string[];
+    since?: Date;
+    until?: Date;
+}
+
+/**
+ * Neighborhood expansion and seeded rerank helpers.
+ *
+ * Bounded graph-style expansion and a distance-style reranker both sit after
+ * RRF fusion. agenr does not have a graph DB, so "neighborhood" means a
+ * bounded sweep over sibling claim keys, supersession chains, procedure
+ * revisions, episode session families, and topical peers as computed from
+ * the existing relational model.
+ *
+ * The helpers in this file are deliberately pure:
+ * - `selectStrongSeeds()` picks retrieval leaders whose gap to the rest of
+ *   the pack clearly earns them seed status.
+ * - `seededRerank()` applies a small positive delta to ranked candidates
+ *   that share lineage with at least one strong seed, without ever lifting
+ *   a candidate that has no lineage signal.
+ * - The domain-specific predicates (`sharesEntryLineage`,
+ *   `sharesEpisodeLineage`, `sharesProcedureLineage`) encode what "shares
+ *   lineage" means for entries, episodes, and procedures respectively.
+ */
+/**
+ * Discriminated neighborhood family kinds used to describe one expansion
+ * direction across the recall pipeline.
+ *
+ * - `supersession_chain` reaches along `superseded_by` pointers.
+ * - `claim_key_sibling` reaches across rows sharing one claim-key slot.
+ * - `procedure_revision` reaches across revisions of one procedure key.
+ * - `session_family` reaches across episodes originating in the same
+ *   session identity (same `source` plus `sourceId`).
+ * - `topic_family` reaches across rows sharing a strong subject prefix and
+ *   is the weakest, retired-only fallback for entries.
+ */
+type NeighborhoodFamily = "supersession_chain" | "claim_key_sibling" | "procedure_revision" | "session_family" | "topic_family";
+/**
+ * Adapter-facing request for the bounded entry neighborhood expansion port.
+ *
+ * This is the generalized successor of the phase 1 `fetchPredecessors`
+ * lookup. The adapter should honor the requested `families` exactly and
+ * respect `includeRetired` as a hard gate so the default entry profile
+ * never pulls retired rows into the candidate pool.
+ */
+interface EntryNeighborhoodRequest {
+    /** Seed entry IDs to expand around. */
+    seedIds: string[];
+    /** Maximum total rows the adapter may return. */
+    budget: number;
+    /** Families the adapter should traverse. */
+    families: readonly NeighborhoodFamily[];
+    /** When true, retired rows are eligible; when false, only active rows. */
+    includeRetired?: boolean;
+}
+/** Default total-rows budget for one neighborhood expansion call. */
+declare const DEFAULT_NEIGHBORHOOD_BUDGET = 24;
+/** Default top-N size used when choosing strong rerank seeds. */
+declare const DEFAULT_STRONG_SEED_TOP_N = 3;
+/**
+ * Minimum score gap that separates strong seeds from the pack.
+ *
+ * Keeping the floor small but non-zero prevents flat score landscapes
+ * (common when RRF produces ties) from promoting every candidate into a
+ * seed, which would collapse seededRerank into "boost everything".
+ */
+declare const DEFAULT_STRONG_SEED_SCORE_GAP = 0.05;
+/**
+ * Default positive delta applied to candidates that share lineage with a
+ * strong seed. Intentionally smaller than the existing historical lineage
+ * boosts so the stage cannot override claim-key shaping or historical
+ * trust suppression.
+ */
+declare const DEFAULT_SEEDED_RERANK_WEIGHT = 0.03;
+
+/** Shared shape used by all seededRerank callers. */
+interface SeededRerankCandidate {
+    /** Stable identifier used to detect the seed itself and skip rerank. */
+    id: string;
+    /** Current ranked score in the 0-1 range. */
+    score: number;
+}
+/** Tuning knobs for strong-seed selection and seededRerank. */
+interface SeededRerankOptions {
+    /** Positive delta applied to lineage-matched candidates. */
+    weight?: number;
+    /** Top candidate count to consider as potential seeds. */
+    topN?: number;
+    /** Minimum score gap between the leader and the top-N follower. */
+    scoreGapFloor?: number;
+}
+/**
+ * Pick the top-ranked candidates that clearly stand apart from the pack.
+ *
+ * The score gap between the leader and the first candidate past the
+ * `topN` cutoff must exceed `scoreGapFloor` for any seeds to qualify.
+ * A flat ranking (common when every candidate earned the same RRF score)
+ * therefore produces zero seeds and leaves the rest of the pipeline alone.
+ *
+ * @param candidates - Candidates after scoring but before final shaping.
+ * @param options - Optional top-N and score-gap tuning.
+ * @returns The strong-seed subset ordered from strongest to weakest.
+ */
+declare function selectStrongSeeds<TCandidate extends SeededRerankCandidate>(candidates: readonly TCandidate[], options?: SeededRerankOptions): TCandidate[];
+/**
+ * Boost ranked candidates that share lineage with at least one strong seed.
+ *
+ * - Seeds themselves are left unchanged.
+ * - Candidates without lineage evidence are left unchanged.
+ * - Matched candidates receive `weight` added to their score, clamped to
+ *   the 0-1 range.
+ * - The rerank never lifts a candidate that has no lineage relationship
+ *   to any seed, which is the core safety property called out in the plan.
+ *
+ * @param candidates - Ranked candidate list prior to rerank.
+ * @param seeds - Strong seeds chosen via `selectStrongSeeds`.
+ * @param sharesLineage - Domain-specific predicate returning true when the
+ *   candidate shares structural or topical lineage with the supplied seed.
+ * @param options - Tuning knobs (weight only has an effect here).
+ * @returns Candidates with any lineage-boosted scores applied.
+ */
+declare function seededRerank<TCandidate extends SeededRerankCandidate>(candidates: readonly TCandidate[], seeds: readonly TCandidate[], sharesLineage: (candidate: TCandidate, seed: TCandidate) => boolean, options?: SeededRerankOptions): {
+    candidates: TCandidate[];
+    boostedIds: string[];
+};
+/**
+ * Decide whether two entry candidates share lineage for rerank purposes.
+ *
+ * Three relationships qualify as lineage:
+ * - Same `claim_key` (same slot in the claim-key model).
+ * - Direct `superseded_by` link in either direction.
+ * - Shared subject prefix wide enough to count as the same topic.
+ *
+ * @param candidate - Candidate entry under evaluation.
+ * @param seed - Strong-seed entry the candidate is being compared to.
+ * @returns True when the two entries share lineage, false otherwise.
+ */
+declare function sharesEntryLineage(candidate: RecallCandidateEntry, seed: RecallCandidateEntry): boolean;
+/**
+ * Decide whether two episodes belong to the same session family.
+ *
+ * - Same `source` plus `sourceId` is the strongest signal; it identifies
+ *   the same originating session across storage and rehydration paths.
+ * - A shared `transcriptHash` is the fallback when one side lacks a
+ *   persisted `sourceId`, since episodes that land on the same transcript
+ *   are structurally the same session even after re-ingest.
+ *
+ * @param candidate - Candidate episode under evaluation.
+ * @param seed - Strong-seed episode the candidate is being compared to.
+ * @returns True when the episodes share session lineage.
+ */
+declare function sharesEpisodeLineage(candidate: Episode, seed: Episode): boolean;
+/**
+ * Decide whether two procedures share the same procedure-key revision chain.
+ *
+ * @param candidate - Candidate procedure under evaluation.
+ * @param seed - Strong-seed procedure the candidate is being compared to.
+ * @returns True when both rows share one stable procedure key.
+ */
+declare function sharesProcedureLineage(candidate: Procedure, seed: Procedure): boolean;
+
+/**
+ * Storage contract for persisting, updating, and querying knowledge entries.
+ */
+interface DatabasePort {
+    /** Insert a new entry with its embedding. */
+    insertEntry(entry: Entry, embedding: number[], contentHash: string): Promise<string>;
+    /** Drop expensive indexes and triggers before a bulk write phase begins. */
+    prepareForBulkWrites(): Promise<void>;
+    /** Rebuild expensive indexes and triggers after a bulk write phase ends. */
+    finalizeBulkWrites(): Promise<void>;
+    /** Get entries by IDs. */
+    getEntries(ids: string[]): Promise<Entry[]>;
+    /** Get a single entry by ID. */
+    getEntry(id: string): Promise<Entry | null>;
+    /** Check if content hashes already exist. Returns the set of existing hashes. */
+    findExistingHashes(hashes: string[]): Promise<Set<string>>;
+    /** Check if normalized content hashes already exist. Returns the set of existing hashes. */
+    findExistingNormHashes(hashes: string[]): Promise<Set<string>>;
+    /** Mark an entry as retired. */
+    retireEntry(id: string, reason?: string): Promise<boolean>;
+    /** Supersede an active entry, linking it to the new entry that replaces it. */
+    supersedeEntry(oldId: string, newId: string, kind?: string, reason?: string): Promise<boolean>;
+    /** Find active entries with the given claim key. */
+    findActiveEntriesByClaimKey(claimKey: string): Promise<Entry[]>;
+    /** Get distinct entity prefixes from existing claim keys. */
+    getDistinctClaimKeyPrefixes(): Promise<string[]>;
+    /** Get bounded full claim-key examples ordered for extraction hinting. */
+    getClaimKeyExamples?(limit?: number): Promise<string[]>;
+    /** Get active per-prefix claim-key counts for conservative alias-family handling. */
+    getClaimKeyEntityPrefixStats?(): Promise<ClaimKeyEntityPrefixStats[]>;
+    /** Update entry fields (importance, expiry, and temporal metadata). */
+    updateEntry(id: string, fields: EntryUpdateInput): Promise<boolean>;
+    /** Check if a file has been ingested (by path + hash). */
+    getIngestLogEntry(filePath: string): Promise<{
+        fileHash: string;
+        ingestedAt: string;
+    } | null>;
+    /** Record that a file was ingested. */
+    insertIngestLogEntry(filePath: string, fileHash: string, entryCount: number): Promise<void>;
+    /** Initialize the database schema. */
+    init(): Promise<void>;
+    /** Close the database connection. */
+    close(): Promise<void>;
+}
+/**
+ * Storage contract for persisting and querying episodic memory records.
+ */
+interface EpisodeDatabasePort {
+    /** Get one episode by its stable `(source, sourceId)` identity. */
+    getEpisodeBySourceId(source: EpisodeSource, sourceId: string): Promise<Episode | null>;
+    /** Get one episode by fallback `(source, transcriptHash)` identity. */
+    getEpisodeByTranscriptHash(source: EpisodeSource, transcriptHash: string): Promise<Episode | null>;
+    /** Insert or update an episode using `summaryHash` change detection. */
+    upsertEpisode(input: EpisodeInput): Promise<EpisodeUpsertResult>;
+    /** List non-retired episodes whose time range overlaps the requested window. */
+    listEpisodesByTimeWindow(window: TemporalWindow, limit?: number): Promise<Episode[]>;
+    /** Find episodes by vector similarity to a query embedding. */
+    episodeVectorSearch(params: {
+        embedding: number[];
+        limit: number;
+    }): Promise<Array<{
+        episode: Episode;
+        vectorSim: number;
+    }>>;
+    /** List non-retired episodes that still need embeddings. */
+    listEpisodesWithoutEmbeddings(limit?: number): Promise<Episode[]>;
+    /** Update only the embedding payload for an existing episode row. */
+    updateEpisodeEmbedding(id: string, embedding: number[]): Promise<void>;
+}
+/**
+ * Storage contract for persisting and querying procedural-memory revisions.
+ */
+interface ProcedureDatabasePort {
+    /** Insert or update one procedure revision row. */
+    upsertProcedure(procedure: Procedure): Promise<Procedure>;
+    /** Get one active procedure by primary key. */
+    getProcedure(id: string): Promise<Procedure | null>;
+    /** Hydrate active procedures by ID while preserving caller order. */
+    hydrateProcedures(ids: string[]): Promise<Procedure[]>;
+    /** Get the currently active procedure revision for one stable key. */
+    findActiveProcedureByKey(procedureKey: string): Promise<Procedure | null>;
+    /** Find procedures by vector similarity to a query embedding. */
+    procedureVectorSearch(params: {
+        embedding: number[];
+        limit: number;
+    }): Promise<Array<{
+        procedure: Procedure;
+        vectorSim: number;
+    }>>;
+    /** Find procedures by lexical search over the procedure FTS index. */
+    procedureFtsSearch(params: {
+        text: string;
+        limit: number;
+    }): Promise<Array<{
+        procedure: Procedure;
+        rank: number;
+    }>>;
+    /** List active procedures that still need embeddings. */
+    listProceduresWithoutEmbeddings(limit?: number): Promise<Procedure[]>;
+    /** Update only the embedding payload for an existing procedure row. */
+    updateProcedureEmbedding(id: string, embedding: number[]): Promise<void>;
+    /** Mark one active procedure revision as retired. */
+    retireProcedure(id: string, reason?: string): Promise<boolean>;
+    /** Supersede one active procedure revision with a new revision. */
+    supersedeProcedure(oldId: string, newId: string, reason?: string): Promise<boolean>;
+}
+/**
+ * Embedding provider contract used by core ranking and storage flows.
+ */
+interface EmbeddingPort {
+    /** Compute embeddings for one or more texts. */
+    embed(texts: string[]): Promise<number[][]>;
+}
+/**
+ * Query-time retrieval contract used by the v1 recall pipeline.
+ */
+interface RecallPorts {
+    /** Compute a single embedding for a recall query string. */
+    embed(text: string): Promise<number[]>;
+    /** Search vector candidates with adapter-level filtering applied. */
+    vectorSearch(params: {
+        embedding: number[];
+        limit: number;
+        filters?: EntryFilters;
+    }): Promise<VectorCandidate[]>;
+    /** Search FTS candidates with adapter-level filtering applied. */
+    ftsSearch(params: {
+        text: string;
+        limit: number;
+        filters?: EntryFilters;
+    }): Promise<FtsCandidate[]>;
+    /**
+     * Expand a typed neighborhood of entries around the provided seed IDs.
+     *
+     * The adapter honors `families` exactly and treats `includeRetired` as a
+     * hard gate. This is the generalized successor of the phase 1
+     * `fetchPredecessors` lookup and is used by every entry ranking profile.
+     * The default profile passes `includeRetired: false`; historical-state
+     * passes `includeRetired: true` with a wider family set.
+     */
+    expandNeighborhood?(request: EntryNeighborhoodRequest): Promise<RecallCandidateEntry[]>;
+    /** Hydrate fully populated entries for the final ranked result set. */
+    hydrateEntries(ids: string[]): Promise<Entry[]>;
+    /** Persist recall events for the returned entry set. */
+    recordRecallEvents(params: {
+        entryIds: string[];
+        query: string;
+        sessionKey?: string;
+    }): Promise<void>;
+    /**
+     * Optional cross-encoder rerank port. When present, recall calls the
+     * port for the top-K shortlist after MMR diversification and before
+     * thresholding. The recall pipeline fails closed on adapter errors so
+     * the cross-encoder can never drop recall below its pre-rerank
+     * baseline.
+     */
+    crossEncoder?: CrossEncoderPort;
+}
+/**
+ * LLM provider contract for free-form and structured completions.
+ */
+interface LlmPort {
+    /** Generate a completion from a system prompt and user message. */
+    complete(systemPrompt: string, userMessage: string): Promise<string>;
+    /** Generate a structured completion (JSON output). */
+    completeJson<T>(systemPrompt: string, userMessage: string): Promise<T>;
+}
+/**
+ * One passage handed to the cross-encoder for relevance scoring.
+ */
+interface CrossEncoderPassage {
+    /** Stable identifier used to correlate scores back to the caller. */
+    id: string;
+    /** Free-form text representation of the passage. */
+    text: string;
+}
+/**
+ * One scored passage returned by a cross-encoder ranker.
+ */
+interface CrossEncoderScore {
+    /** Stable identifier matching the input passage. */
+    id: string;
+    /** Relevance score in the inclusive 0-1 range. */
+    score: number;
+}
+/**
+ * Cross-encoder contract used by the recall pipeline to rerank a small
+ * top-K shortlist. Implementations must be safe to call concurrently and
+ * should bound provider concurrency internally so recall latency does
+ * not spiral under load.
+ *
+ * Identifiers are passed through explicitly so core recall never has to
+ * correlate by list position.
+ */
+interface CrossEncoderPort {
+    /**
+     * Score each passage against the query.
+     *
+     * @param query - Natural-language recall query.
+     * @param passages - Passages ordered in their caller-preferred order.
+     * @returns Each passage's relevance score keyed by passage ID.
+     */
+    rank(query: string, passages: readonly CrossEncoderPassage[]): Promise<CrossEncoderScore[]>;
+}
+
+/**
+ * Runtime slot-policy classes used by claim-centric read surfaces.
+ */
+type ClaimSlotPolicy = "exclusive" | "multivalued";
+/**
+ * Data-driven slot-policy overrides keyed by canonical claim-key attribute head.
+ */
+interface ClaimSlotPolicyConfig {
+    /** Optional attribute-head policy overrides such as `integration -> exclusive`. */
+    attributeHeads?: Readonly<Record<string, ClaimSlotPolicy>>;
+}
+
+export { type ClaimSlotPolicyConfig as C, DEFAULT_NEIGHBORHOOD_BUDGET as D, type EntryType as E, type FtsCandidate as F, type LlmPort as L, type NeighborhoodFamily as N, type ProcedureDatabasePort as P, type RecallInput as R, type SeededRerankCandidate as S, type VectorCandidate as V, type CrossEncoderPort as a, type Expiry as b, type RecallPorts as c, type RecallOutput as d, DEFAULT_SEEDED_RERANK_WEIGHT as e, DEFAULT_STRONG_SEED_SCORE_GAP as f, DEFAULT_STRONG_SEED_TOP_N as g, type EntityAttributeKind as h, type EntityAttributeQueryShape as i, type EntryFilters as j, type EntryNeighborhoodRequest as k, type RecallCandidateEntry as l, type RecallRankingProfile as m, type SeededRerankOptions as n, selectStrongSeeds as o, sharesEntryLineage as p, sharesEpisodeLineage as q, sharesProcedureLineage as r, seededRerank as s, type Entry as t, type ClaimSlotPolicy as u, type DatabasePort as v, type EpisodeDatabasePort as w, type EmbeddingPort as x };