@atomicmemory/core 1.0.0

package/dist/services/tll-retrieval.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Phase 4b — TLL retrieval signal.
+ *
+ * For event-ordering / temporal-reasoning / multi-session-reasoning queries,
+ * expand the candidate set by traversing entity TLL chains. This is the
+ * unique architectural primitive: nobody else ships per-entity event-chain
+ * traversal at retrieval time.
+ *
+ * The mechanism:
+ *   1. From the initial retrieval candidates, find which entities they link.
+ *   2. For each entity, fetch its full TLL chain (event sequence).
+ *   3. Merge chain memory_ids into the candidate pool.
+ *   4. Boost score for memories that appear in TLL chains for the query's
+ *      entities — they're explicitly part of the chronological story.
+ *
+ * Skipped for non-ordering queries (factual lookups don't need chains).
+ */
+import type pg from 'pg';
+import type { TllRepository } from '../db/repository-tll.js';
+/**
+ * Cap on the number of top similarity-ranked candidates that seed TLL
+ * entity-lookup. Bounds the per-query fan-out for the
+ * `memory_entities` join — a higher value increases recall on
+ * sprawling queries but inflates the worst-case row scan when an
+ * entity dictionary is dense. 10 matches the production search seed
+ * count in `memory-search.ts` so both call sites move together.
+ */
+export declare const TLL_ENTITY_LOOKUP_SEED_LIMIT = 10;
+/**
+ * Returns true if the query has the shape of an event-ordering / temporal
+ * question and should trigger TLL chain expansion. The gate is
+ * intentionally conservative: TLL augmentation is augmentation, not the
+ * primary retrieval path, so over-firing was producing irrelevant chain
+ * memories on plain-fact queries that happened to contain "first",
+ * "before", "track", etc.
+ *
+ * Two ordering terms co-occurring (e.g. "what did I discuss BEFORE and
+ * AFTER X") is a strong-enough signal on its own; one structural
+ * sequence phrase (e.g. "in what order", "evolution of", "since when")
+ * is also strong enough. Single ordering term + nothing else is not.
+ */
+export declare function shouldUseTLL(query: string): boolean;
+/**
+ * Get the entity_ids linked to a set of memory_ids via memory_entities.
+ * Used to find which entities to chain-traverse from initial retrieval.
+ * Exported for direct unit testing of SQL shape; the production caller
+ * is `expandViaTLL` below.
+ */
+export declare function entitiesForMemories(pool: pg.Pool, memoryIds: string[]): Promise<string[]>;
+/**
+ * Expand candidate set via TLL chain traversal for the entities most
+ * relevant to the query (derived from initial retrieval).
+ * Returns: array of memory_ids in chronological chain order, deduplicated.
+ */
+export declare function expandViaTLL(userId: string, initialMemoryIds: string[], tllRepository: TllRepository, pool: pg.Pool): Promise<string[]>;

package/dist/services/tll-retrieval.js

@@ -0,0 +1,101 @@
+/**
+ * Phase 4b — TLL retrieval signal.
+ *
+ * For event-ordering / temporal-reasoning / multi-session-reasoning queries,
+ * expand the candidate set by traversing entity TLL chains. This is the
+ * unique architectural primitive: nobody else ships per-entity event-chain
+ * traversal at retrieval time.
+ *
+ * The mechanism:
+ *   1. From the initial retrieval candidates, find which entities they link.
+ *   2. For each entity, fetch its full TLL chain (event sequence).
+ *   3. Merge chain memory_ids into the candidate pool.
+ *   4. Boost score for memories that appear in TLL chains for the query's
+ *      entities — they're explicitly part of the chronological story.
+ *
+ * Skipped for non-ordering queries (factual lookups don't need chains).
+ */
+/**
+ * Cap on the number of top similarity-ranked candidates that seed TLL
+ * entity-lookup. Bounds the per-query fan-out for the
+ * `memory_entities` join — a higher value increases recall on
+ * sprawling queries but inflates the worst-case row scan when an
+ * entity dictionary is dense. 10 matches the production search seed
+ * count in `memory-search.ts` so both call sites move together.
+ */
+export const TLL_ENTITY_LOOKUP_SEED_LIMIT = 10;
+/**
+ * Single-token ordering signals. Matched in isolation these are too
+ * weak to gate TLL — "what is my FIRST name", "the model used BEFORE
+ * GPT-4", "we then moved on" all contain one of these but are not
+ * EO/MSR/TR queries. We require either two of them to co-occur, or
+ * one of the structural sequence patterns below, before firing.
+ */
+const ORDERING_TERMS_RE = /\b(first|last|before|after|then|later|earlier|previous|next|prior)\b/gi;
+/**
+ * Structural sequence patterns. Each one is a phrase whose presence
+ * unambiguously indicates an ordering / temporal-reasoning question.
+ * Single-pattern hit is enough to gate TLL.
+ *
+ * Curated to keep precision high: "track my spending" and "what is my
+ * first name" must not match any pattern here. Add new patterns
+ * conservatively — a leak here will silently re-introduce the
+ * false-positive class this fix addresses.
+ */
+const SEQUENCE_PATTERNS = [
+    /\bin (what |the )?(chronological |reverse )?order\b/i,
+    /\b(when|after) did\b/i,
+    /\bsince when\b/i,
+    /\bover time\b/i,
+    /\bevolution of\b/i,
+    /\b(history|timeline) of\b/i,
+    /\bbrought up\b/i,
+    /\b(originally|initially)\b/i,
+    /\bprogression of\b/i,
+    /\bhow .{1,80}(evolved?|shifted?|changed)\b/i,
+    /\bwhat .{1,80}(originally|initially)\b/i,
+];
+/**
+ * Returns true if the query has the shape of an event-ordering / temporal
+ * question and should trigger TLL chain expansion. The gate is
+ * intentionally conservative: TLL augmentation is augmentation, not the
+ * primary retrieval path, so over-firing was producing irrelevant chain
+ * memories on plain-fact queries that happened to contain "first",
+ * "before", "track", etc.
+ *
+ * Two ordering terms co-occurring (e.g. "what did I discuss BEFORE and
+ * AFTER X") is a strong-enough signal on its own; one structural
+ * sequence phrase (e.g. "in what order", "evolution of", "since when")
+ * is also strong enough. Single ordering term + nothing else is not.
+ */
+export function shouldUseTLL(query) {
+    const orderingMatches = (query.match(ORDERING_TERMS_RE) ?? []).length;
+    if (orderingMatches >= 2)
+        return true;
+    return SEQUENCE_PATTERNS.some((re) => re.test(query));
+}
+/**
+ * Get the entity_ids linked to a set of memory_ids via memory_entities.
+ * Used to find which entities to chain-traverse from initial retrieval.
+ * Exported for direct unit testing of SQL shape; the production caller
+ * is `expandViaTLL` below.
+ */
+export async function entitiesForMemories(pool, memoryIds) {
+    if (memoryIds.length === 0)
+        return [];
+    const result = await pool.query(`SELECT DISTINCT entity_id FROM memory_entities WHERE memory_id = ANY($1::uuid[])`, [memoryIds]);
+    return result.rows.map((r) => r.entity_id);
+}
+/**
+ * Expand candidate set via TLL chain traversal for the entities most
+ * relevant to the query (derived from initial retrieval).
+ * Returns: array of memory_ids in chronological chain order, deduplicated.
+ */
+export async function expandViaTLL(userId, initialMemoryIds, tllRepository, pool) {
+    if (initialMemoryIds.length === 0)
+        return [];
+    const entityIds = await entitiesForMemories(pool, initialMemoryIds.slice(0, TLL_ENTITY_LOOKUP_SEED_LIMIT));
+    if (entityIds.length === 0)
+        return [];
+    return tllRepository.chainsFor(userId, entityIds);
+}

package/dist/services/topic-abstraction.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Topic abstraction layer for the EO (event ordering) experiment.
+ *
+ * For each chunk processed during ingest, run a separate LLM pass to extract
+ * the *conceptual topic* discussed in the fragment at a higher abstraction
+ * level than the raw fact (e.g. "API authentication design" rather than
+ * "Flask, Bootstrap"). The topic is stored alongside the raw fact so that
+ * EO-style queries — which expect conceptual phases, not implementation
+ * specifics — can retrieve material at the rubric's abstraction level.
+ *
+ * Principled, no regex: an LLM-learned summarization, an embedding similarity
+ * fusion at retrieval. No query-text pattern matching. The mechanism activates
+ * uniformly for all chunks; the answer LLM uses topic context for any query
+ * that benefits from it.
+ *
+ * Cost budget: one extra short LLM call per chunk during ingest. Adds
+ * ~10-25 % to ingest token usage. Zero added latency at retrieval.
+ *
+ * See benchmarks-sprint3/2026-05-10-am-baseline-and-rerank-design.md.
+ */
+import type { LLMProvider } from './llm.js';
+export interface TopicAbstraction {
+    topic: string;
+}
+export declare class TopicAbstractionError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Extract a conceptual topic from a chunk + fact pair.
+ *
+ * Fail-closed: throws TopicAbstractionError on any LLM transport failure
+ * or invalid output. Caller (memory-ingest.ts) decides whether to record
+ * the chunk without a topic, or fail the ingest entirely.
+ */
+export declare function extractTopicAbstraction(chunkText: string, factText: string, llmClient?: LLMProvider): Promise<TopicAbstraction>;

package/dist/services/topic-abstraction.js

@@ -0,0 +1,105 @@
+/**
+ * Topic abstraction layer for the EO (event ordering) experiment.
+ *
+ * For each chunk processed during ingest, run a separate LLM pass to extract
+ * the *conceptual topic* discussed in the fragment at a higher abstraction
+ * level than the raw fact (e.g. "API authentication design" rather than
+ * "Flask, Bootstrap"). The topic is stored alongside the raw fact so that
+ * EO-style queries — which expect conceptual phases, not implementation
+ * specifics — can retrieve material at the rubric's abstraction level.
+ *
+ * Principled, no regex: an LLM-learned summarization, an embedding similarity
+ * fusion at retrieval. No query-text pattern matching. The mechanism activates
+ * uniformly for all chunks; the answer LLM uses topic context for any query
+ * that benefits from it.
+ *
+ * Cost budget: one extra short LLM call per chunk during ingest. Adds
+ * ~10-25 % to ingest token usage. Zero added latency at retrieval.
+ *
+ * See benchmarks-sprint3/2026-05-10-am-baseline-and-rerank-design.md.
+ */
+import { llm as defaultLlm } from './llm.js';
+import { extractFirstJsonObject } from './extraction.js';
+const TOPIC_MAX_TOKENS = 128;
+const TOPIC_MAX_WORDS = 7;
+const TOPIC_MIN_WORDS = 3;
+const TOPIC_SYSTEM_PROMPT = [
+    'You extract the conceptual TOPIC discussed in a short conversation fragment.',
+    '',
+    'Rules:',
+    '- Output a JSON object: {"topic": "<3 to 7 words>"}',
+    '- The topic must name a conceptual phase, theme, or domain — NOT implementation specifics.',
+    '- Good topics: "API authentication design", "deployment pipeline setup",',
+    '  "frontend layout iteration", "user onboarding flow", "database migration planning".',
+    '- Bad topics (too specific): "Flask login route", "Bootstrap navbar CSS",',
+    '  "PostgreSQL ALTER TABLE statement", "axios POST to /api/users".',
+    '- Bad topics (too generic): "code", "the user", "discussion", "project work".',
+    '- Strictly 3 to 7 words. No punctuation other than spaces.',
+    '- No markdown fences. No prose around the JSON.',
+].join('\n');
+export class TopicAbstractionError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'TopicAbstractionError';
+    }
+}
+/**
+ * Extract a conceptual topic from a chunk + fact pair.
+ *
+ * Fail-closed: throws TopicAbstractionError on any LLM transport failure
+ * or invalid output. Caller (memory-ingest.ts) decides whether to record
+ * the chunk without a topic, or fail the ingest entirely.
+ */
+export async function extractTopicAbstraction(chunkText, factText, llmClient = defaultLlm) {
+    const messages = [
+        { role: 'system', content: TOPIC_SYSTEM_PROMPT },
+        { role: 'user', content: buildTopicUserMessage(chunkText, factText) },
+    ];
+    let raw;
+    try {
+        raw = await llmClient.chat(messages, {
+            temperature: 0,
+            jsonMode: true,
+            maxTokens: TOPIC_MAX_TOKENS,
+        });
+    }
+    catch (err) {
+        throw new TopicAbstractionError(`topic extraction LLM call failed: ${err.message}`, err);
+    }
+    if (!raw) {
+        throw new TopicAbstractionError('topic extraction returned empty content');
+    }
+    const cleaned = extractFirstJsonObject(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (err) {
+        throw new TopicAbstractionError(`topic extraction returned non-JSON: ${cleaned.slice(0, 200)}`, err);
+    }
+    return validateTopic(parsed);
+}
+function buildTopicUserMessage(chunkText, factText) {
+    return [
+        'CHAT FRAGMENT:',
+        chunkText.trim().slice(0, 4000),
+        '',
+        'FACT EXTRACTED FROM FRAGMENT:',
+        factText.trim().slice(0, 1000),
+        '',
+        'Return the conceptual topic as JSON: {"topic": "<3 to 7 words>"}',
+    ].join('\n');
+}
+function validateTopic(parsed) {
+    const topicRaw = typeof parsed.topic === 'string' ? parsed.topic.trim() : null;
+    if (!topicRaw) {
+        throw new TopicAbstractionError(`topic extraction returned no topic field: ${JSON.stringify(parsed).slice(0, 200)}`);
+    }
+    const words = topicRaw.split(/\s+/).filter(Boolean);
+    if (words.length < TOPIC_MIN_WORDS || words.length > TOPIC_MAX_WORDS) {
+        throw new TopicAbstractionError(`topic must be ${TOPIC_MIN_WORDS}-${TOPIC_MAX_WORDS} words, got ${words.length}: "${topicRaw}"`);
+    }
+    return { topic: words.join(' ') };
+}

package/dist/services/trust-scoring.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Trust scoring for memories at write time.
+ *
+ * Computes a trust score (0.0–1.0) based on source domain reputation,
+ * content characteristics, and injection pattern detection. The score
+ * is stored alongside each memory and used at retrieval time to filter
+ * or down-rank low-trust content.
+ *
+ * Phase 3 security baseline — threat-model.md P0 item.
+ * Based on A-MemGuard (simplified) and reference-implementations.md §8.
+ */
+import { type SanitizationResult } from './input-sanitizer.js';
+/** Trust score with breakdown of contributing signals. */
+export interface TrustScore {
+    score: number;
+    domainTrust: number;
+    contentPenalty: number;
+    injectionPenalty: number;
+    sanitization: SanitizationResult;
+}
+/**
+ * Compute a trust score for a memory based on its content and source.
+ *
+ * Score starts at 1.0 and is reduced by:
+ * - Unknown source domain: -0.2
+ * - Each injection pattern match: -0.3 (capped at -0.9)
+ * - Content anomalies (length, unicode, repetition): -0.1 each
+ *
+ * Final score is clamped to [0.0, 1.0].
+ */
+export declare function computeTrustScore(content: string, sourceSite: string): TrustScore;
+/** Check if a domain is in the trusted set. */
+export declare function isDomainTrusted(sourceSite: string): boolean;
+/**
+ * Determine if a memory should be stored based on its trust score.
+ * Returns true if the score meets the minimum threshold.
+ */
+export declare function meetsMinimumTrust(trustScore: TrustScore, threshold: number): boolean;
+/**
+ * Apply a trust-based penalty to a retrieval score.
+ * Low-trust memories are down-ranked proportionally.
+ */
+export declare function applyTrustPenalty(retrievalScore: number, trustScore: number): number;

package/dist/services/trust-scoring.js

@@ -0,0 +1,89 @@
+/**
+ * Trust scoring for memories at write time.
+ *
+ * Computes a trust score (0.0–1.0) based on source domain reputation,
+ * content characteristics, and injection pattern detection. The score
+ * is stored alongside each memory and used at retrieval time to filter
+ * or down-rank low-trust content.
+ *
+ * Phase 3 security baseline — threat-model.md P0 item.
+ * Based on A-MemGuard (simplified) and reference-implementations.md §8.
+ */
+import { sanitize } from './input-sanitizer.js';
+/**
+ * Known trusted domains where content is likely user-authored and legitimate.
+ * Memories from trusted domains start at 1.0; unknown domains start at 0.8.
+ */
+const TRUSTED_DOMAINS = new Set([
+    'claude.ai',
+    'chatgpt.com',
+    'chat.openai.com',
+    'gemini.google.com',
+    'github.com',
+    'stackoverflow.com',
+    'docs.google.com',
+    'notion.so',
+]);
+const UNKNOWN_DOMAIN_PENALTY = 0.2;
+const INJECTION_PENALTY_PER_MATCH = 0.3;
+const CONTENT_WARN_PENALTY = 0.1;
+const MAX_INJECTION_PENALTY = 0.9;
+/**
+ * Compute a trust score for a memory based on its content and source.
+ *
+ * Score starts at 1.0 and is reduced by:
+ * - Unknown source domain: -0.2
+ * - Each injection pattern match: -0.3 (capped at -0.9)
+ * - Content anomalies (length, unicode, repetition): -0.1 each
+ *
+ * Final score is clamped to [0.0, 1.0].
+ */
+export function computeTrustScore(content, sourceSite) {
+    const sanitization = sanitize(content);
+    const domainTrust = isDomainTrusted(sourceSite) ? 0 : UNKNOWN_DOMAIN_PENALTY;
+    const injectionCount = sanitization.findings.filter((f) => f.rule.startsWith('injection:')).length;
+    const injectionPenalty = Math.min(injectionCount * INJECTION_PENALTY_PER_MATCH, MAX_INJECTION_PENALTY);
+    const warnCount = sanitization.findings.filter((f) => f.severity === 'warn').length;
+    const contentPenalty = warnCount * CONTENT_WARN_PENALTY;
+    const score = Math.max(0, Math.min(1, 1.0 - domainTrust - injectionPenalty - contentPenalty));
+    return {
+        score,
+        domainTrust: 1.0 - domainTrust,
+        contentPenalty,
+        injectionPenalty,
+        sanitization,
+    };
+}
+/** Check if a domain is in the trusted set. */
+export function isDomainTrusted(sourceSite) {
+    const normalized = normalizeSourceSite(sourceSite);
+    if (!normalized)
+        return false;
+    return Array.from(TRUSTED_DOMAINS).some((trustedDomain) => normalized === trustedDomain || normalized.endsWith(`.${trustedDomain}`));
+}
+/**
+ * Determine if a memory should be stored based on its trust score.
+ * Returns true if the score meets the minimum threshold.
+ */
+export function meetsMinimumTrust(trustScore, threshold) {
+    return trustScore.score >= threshold;
+}
+/**
+ * Apply a trust-based penalty to a retrieval score.
+ * Low-trust memories are down-ranked proportionally.
+ */
+export function applyTrustPenalty(retrievalScore, trustScore) {
+    return retrievalScore * trustScore;
+}
+function normalizeSourceSite(sourceSite) {
+    const trimmed = sourceSite.trim().toLowerCase().replace(/\.+$/, '');
+    if (!trimmed)
+        return '';
+    try {
+        const parsed = new URL(trimmed.includes('://') ? trimmed : `https://${trimmed}`);
+        return parsed.hostname.toLowerCase().replace(/\.+$/, '');
+    }
+    catch {
+        return trimmed;
+    }
+}

package/dist/services/typed-belief-calculus.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Typed Belief Calculus (TBC) — Phase 2 LLM resolver.
+ *
+ * The TBC is a strict superset of AUDN's `Add | Update | Delete | No-op`
+ * decision space. It introduces eight typed operators that each carry
+ * explicit storage semantics: Affirm, Update, Retract, Supersede, Promote,
+ * Demote, EvidenceFor, Counter.
+ *
+ * Phase 2 (this revision) wires `decideBeliefOperator` to a real LLM call
+ * and lets `memory-audn.ts` route through it when `RuntimeConfig.tbcEnabled`
+ * is true. Schema is unchanged — TBC mutations write to existing JSONB
+ * metadata only. See `tbc-execution.ts` for the executor and
+ * `docs/typed-belief-calculus.md` for design rationale.
+ */
+import type { LLMProvider } from './llm.js';
+import type { CandidateMemory } from './conflict-policy.js';
+import type { MemoryMetadata } from '../db/repository-types.js';
+import type { FactInput } from './memory-service-types.js';
+/**
+ * The eight typed belief operators that extend AUDN.
+ *
+ * Each operator describes a distinct effect on the belief graph; they are
+ * not mutually exclusive intents over the same evidence — `decideBeliefOperator`
+ * always picks exactly one per ingest, mirroring how AUDN picks exactly one
+ * AUDNAction today.
+ */
+export declare enum BeliefOperator {
+    /** New evidence supports an existing claim — strengthen confidence, no new claim. */
+    Affirm = "AFFIRM",
+    /** Same attribute, different value — versioned supersession with both states retained. */
+    Update = "UPDATE",
+    /** Claim now believed false (no replacement) — mark RETRACTED, preserve as evidence. */
+    Retract = "RETRACT",
+    /** Replaced by a more specific or general claim — link old to new; both queryable. */
+    Supersede = "SUPERSEDE",
+    /** Strong, repeated belief becomes a directive (constraint tier) influencing answer prompt. */
+    Promote = "PROMOTE",
+    /** Challenged but not retracted — lower confidence; flag for re-evaluation. */
+    Demote = "DEMOTE",
+    /** Adds an evidence-for edge to a supported claim — does not introduce a new claim. */
+    EvidenceFor = "EVIDENCE_FOR",
+    /** Adds a counter edge to a challenged claim — does not introduce a new claim. */
+    Counter = "COUNTER"
+}
+/**
+ * Decision produced by the TBC resolver for a single inbound claim.
+ *
+ * - `operator` is the chosen typed operator from the eight in `BeliefOperator`.
+ * - `target_claim_id` identifies the existing belief targeted by the operator.
+ *   Required for every operator except `Affirm` when no target was found.
+ * - `confidence_delta` is the proposed change to the target claim's confidence
+ *   in `[-1, 1]`. Operators that introduce a brand-new claim should report `0`.
+ * - `rationale` is a free-form natural-language justification for the operator
+ *   choice; surfaced in trace events and used by audit/debug consumers.
+ */
+export interface BeliefOperationDecision {
+    operator: BeliefOperator;
+    target_claim_id?: string;
+    confidence_delta: number;
+    rationale: string;
+}
+/**
+ * A single prior belief state, captured when a TBC operator mutates a claim.
+ *
+ * Phase 2 stores these only in memory metadata (additive). Phase 3 will
+ * normalize them into a `belief_revision_history` table.
+ */
+export interface BeliefRevisionEntry {
+    /** Operator that produced this entry. */
+    operator: BeliefOperator;
+    /** Confidence at the time this entry was recorded, in `[0, 1]`. */
+    confidence: number;
+    /** Optional content snapshot — `null` for graph-only operators (EvidenceFor / Counter). */
+    content: string | null;
+    /** ISO-8601 timestamp of the revision. */
+    recordedAt: string;
+    /** Free-form rationale carried forward from the originating decision. */
+    rationale: string;
+    /**
+     * Edge weight in `[-1, 1]` for graph-only operators. Positive for
+     * EvidenceFor, negative for Counter, undefined for content mutations.
+     */
+    weight?: number;
+}
+/**
+ * Belief-aware metadata extension to the existing `MemoryMetadata` shape.
+ *
+ * The keys are additive — Phase 2 does not move any AUDN-era fields. When
+ * `TBC_ENABLED=false` (default), nothing in this interface is read or written
+ * and the AUDN behavior is unchanged.
+ */
+export interface BeliefMetadata extends MemoryMetadata {
+    /** Current confidence of the belief in `[0, 1]`. */
+    confidence?: number;
+    /** The TBC operator that most recently mutated this memory. */
+    mutation_type?: BeliefOperator;
+    /** True when this memory has been promoted to the directive tier. */
+    directive?: boolean;
+    /** Append-only list of prior states recorded by previous TBC mutations. */
+    revision_history?: BeliefRevisionEntry[];
+    /** Append-only edge log written by EvidenceFor/Counter operators. */
+    belief_edges?: BeliefRevisionEntry[];
+}
+/** Raised when the LLM resolver cannot produce a usable TBC decision. */
+export declare class BeliefResolverError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Resolve a typed belief operator for a candidate set via an LLM call.
+ *
+ * Fail-closed: any LLM transport failure or parser failure raises
+ * `BeliefResolverError` rather than silently returning an `Affirm`/`ADD`
+ * stub. AUDN's existing executor will surface the error to the caller.
+ *
+ * The signature mirrors `resolveAUDN(factText, candidates)` so the
+ * `memory-audn.ts` call site can swap it in cleanly.
+ *
+ * @param newClaim - The inbound atomic claim about to be ingested.
+ * @param candidates - Conflict candidates already discovered via the standard
+ *   AUDN candidate search; same input AUDN sees today.
+ * @param llmClient - Optional LLM provider override for tests; defaults to
+ *   the shared singleton in `services/llm.ts`.
+ * @returns A `BeliefOperationDecision` selecting one of the eight operators.
+ */
+export declare function decideBeliefOperator(newClaim: FactInput, candidates: readonly CandidateMemory[], llmClient?: LLMProvider): Promise<BeliefOperationDecision>;