@atomicmemory/core 1.0.0

package/dist/services/fact-normalization.js

@@ -0,0 +1,248 @@
+/**
+ * Deterministic post-processing for LLM-extracted facts.
+ * Preserves atomic memory coverage by splitting common multi-clause patterns
+ * that the extraction prompt still tends to bundle together.
+ */
+const RECOMMENDATION_MARKERS = [
+    ', as recommended by ',
+    ', recommended by ',
+    ', as suggested by ',
+    ', suggested by ',
+];
+export function normalizeExtractedFacts(facts) {
+    const expanded = facts.flatMap((fact) => splitCompoundFact(fact)
+        .flatMap(expandBecauseClause)
+        .flatMap(normalizeLiteralAliasFacts));
+    return dedupeFacts(expanded);
+}
+function splitCompoundFact(fact) {
+    const recommendationSplit = splitRecommendationAttribution(fact);
+    if (recommendationSplit)
+        return recommendationSplit;
+    const transitionSplit = splitStateTransitionFact(fact);
+    if (transitionSplit)
+        return transitionSplit;
+    return [fact];
+}
+function splitRecommendationAttribution(fact) {
+    const marker = RECOMMENDATION_MARKERS.find((candidate) => fact.fact.includes(candidate));
+    if (!marker)
+        return null;
+    const parts = fact.fact.split(marker);
+    if (parts.length !== 2)
+        return null;
+    const mainFact = ensurePeriod(parts[0]);
+    const recommender = normalizePerson(parts[1]);
+    const recommendedObject = extractRecommendedObject(mainFact);
+    if (!recommender || !recommendedObject)
+        return null;
+    const recommendationFact = `${extractTemporalPrefix(mainFact)}${recommender} recommended ${recommendedObject}.`;
+    return [
+        { ...fact, fact: mainFact },
+        {
+            ...fact,
+            fact: recommendationFact,
+            type: 'person',
+            importance: clampImportance(Math.min(fact.importance, 0.5)),
+            keywords: mergeKeywords(fact.keywords, [recommender]),
+        },
+    ];
+}
+function extractRecommendedObject(text) {
+    const withoutPrefix = stripTemporalPrefix(text);
+    const patterns = [
+        /^user is using (.+)$/i,
+        /^user uses (.+)$/i,
+        /^user plans to use (.+)$/i,
+        /^user will use (.+)$/i,
+        /^user is considering (.+)$/i,
+        /^user chose (.+)$/i,
+        /^user selected (.+)$/i,
+    ];
+    for (const pattern of patterns) {
+        const match = withoutPrefix.match(pattern);
+        if (!match)
+            continue;
+        return match[1].trim().replace(/[. ]+$/, '');
+    }
+    return null;
+}
+function normalizePerson(raw) {
+    const cleaned = raw
+        .trim()
+        .replace(/[. ]+$/, '')
+        .replace(/^(their|the)\s+/i, '')
+        .replace(/^(colleague|friend|advisor|professor|team lead)\s+/i, '')
+        .trim();
+    return cleaned || null;
+}
+function splitStateTransitionFact(fact) {
+    return splitSwitchAwayFact(fact) ?? splitFromToStateChange(fact);
+}
+function splitSwitchAwayFact(fact) {
+    const match = fact.fact.match(/^(As of [^,]+,\s+)?(user|we)\s+switched away from (.+?) and (.+?)[. ]*$/i);
+    if (!match)
+        return null;
+    const prefix = match[1] ?? '';
+    const subject = match[2].toLowerCase();
+    const previousState = stripTrailingPunctuation(match[3]);
+    const currentTarget = normalizeStateTarget(match[4]);
+    if (!currentTarget)
+        return null;
+    return [
+        ...buildCurrentStateFacts(fact, prefix, subject, currentTarget),
+        buildStateFact(fact, buildHistoricalStateText(prefix, subject, `switched away from ${previousState}`), 0.45),
+    ];
+}
+function splitFromToStateChange(fact) {
+    const match = fact.fact.match(/^(As of [^,]+,\s+)?(user|we|project)\s+(?:switched|migrated|moved|changed)\s+from (.+?) to (.+?)[. ]*$/i);
+    if (!match)
+        return null;
+    const prefix = match[1] ?? '';
+    const subject = match[2].toLowerCase();
+    const previousState = stripTrailingPunctuation(match[3]);
+    const currentTarget = normalizeStateTarget(match[4]);
+    if (!currentTarget)
+        return null;
+    return [
+        ...buildCurrentStateFacts(fact, prefix, subject, currentTarget),
+        buildStateFact(fact, buildHistoricalStateText(prefix, subject, `previously used ${previousState}`), 0.45),
+    ];
+}
+function buildStateFact(fact, text, importance) {
+    return {
+        ...fact,
+        fact: text,
+        importance: clampImportance(importance ?? fact.importance),
+        keywords: filterKeywordsForFact(fact.keywords, text),
+    };
+}
+function buildCurrentStateFacts(fact, prefix, subject, target) {
+    return [
+        buildStateFact(fact, buildCurrentStateText(prefix, subject, target)),
+        ...buildBackendAliasFacts(fact, prefix, subject, target),
+    ];
+}
+function buildCurrentStateText(prefix, subject, target) {
+    const verb = subject === 'we' ? 'use' : 'uses';
+    return formatStateSentence(prefix, `${subject} ${verb} ${target}`);
+}
+function buildHistoricalStateText(prefix, subject, clause) {
+    return formatStateSentence(prefix, `${subject} ${clause}`);
+}
+function formatStateSentence(prefix, statement) {
+    const sentence = `${prefix}${statement}`.trim();
+    return ensurePeriod(prefix ? sentence : capitalize(sentence));
+}
+function normalizeStateTarget(raw) {
+    const clause = stripTrailingPunctuation(raw);
+    const patterns = [
+        /^(?:uses?|using|used|built|build|created|create|adopted|adopt|started using|start using|moved to|move to)\s+(.+)$/i,
+    ];
+    for (const pattern of patterns) {
+        const match = clause.match(pattern);
+        if (match)
+            return stripTrailingPunctuation(match[1]);
+    }
+    return clause || null;
+}
+function filterKeywordsForFact(keywords, factText) {
+    const lowerFact = factText.toLowerCase();
+    return keywords.filter((keyword) => lowerFact.includes(keyword.trim().toLowerCase()));
+}
+function buildBackendAliasFacts(fact, prefix, subject, target) {
+    if (!isMemoryBackendTarget(target))
+        return [];
+    const statement = formatStateSentence(prefix, `${subject}'s current memory backend is ${target}`);
+    return [{
+            ...buildStateFact(fact, statement, Math.min(fact.importance, 0.7)),
+            keywords: mergeKeywords(filterKeywordsForFact(fact.keywords, statement), ['memory backend', 'backend']),
+        }];
+}
+function isMemoryBackendTarget(target) {
+    const lower = target.toLowerCase();
+    return lower.includes('memory engine') || lower.includes('memory backend');
+}
+function expandBecauseClause(fact) {
+    const parts = splitBecauseClause(fact.fact);
+    if (!parts)
+        return [fact];
+    return [buildPrimaryFact(fact, parts.primary), buildReasonFact(fact, parts.reason)];
+}
+function splitBecauseClause(text) {
+    const markerIndex = text.toLowerCase().indexOf(' because ');
+    if (markerIndex === -1)
+        return null;
+    const primary = text.slice(0, markerIndex).trim().replace(/[. ]+$/, '');
+    const reason = text.slice(markerIndex + ' because '.length).trim().replace(/[. ]+$/, '');
+    if (!primary || !reason)
+        return null;
+    return { primary: `${primary}.`, reason };
+}
+function normalizeLiteralAliasFacts(fact) {
+    const namedPetFact = normalizeNamedPetFact(fact);
+    return namedPetFact ? [namedPetFact] : [fact];
+}
+function normalizeNamedPetFact(fact) {
+    const match = fact.fact.match(/^(As of [^,]+,\s+)?([A-Z][A-Za-z'’.-]+),\s+(?:my|user's)\s+(guinea pig|dog|cat)\.?$/i);
+    if (!match)
+        return null;
+    const temporalPrefix = match[1] ?? '';
+    const petName = match[2];
+    const petType = match[3].toLowerCase();
+    return {
+        ...fact,
+        fact: `${temporalPrefix}user has a ${petType} named ${petName}.`,
+        keywords: mergeKeywords(fact.keywords, [petName, petType]),
+        type: 'person',
+    };
+}
+function buildPrimaryFact(fact, primary) {
+    return { ...fact, fact: primary };
+}
+function buildReasonFact(fact, reason) {
+    return {
+        ...fact,
+        fact: `User reports that ${capitalize(reason)}.`,
+        importance: clampImportance(Math.max(0.2, Math.min(0.4, fact.importance - 0.4))),
+        type: 'knowledge',
+    };
+}
+function dedupeFacts(facts) {
+    const unique = new Map();
+    for (const fact of facts) {
+        unique.set(`${fact.type}:${fact.fact}`, fact);
+    }
+    return [...unique.values()];
+}
+function extractTemporalPrefix(text) {
+    if (!text.startsWith('As of '))
+        return '';
+    const userIndex = text.toLowerCase().indexOf('user ');
+    if (userIndex === -1)
+        return '';
+    return text.slice(0, userIndex);
+}
+function ensurePeriod(text) {
+    return text.trim().replace(/[. ]+$/, '') + '.';
+}
+function mergeKeywords(existing, additions) {
+    return [...new Set([...existing, ...additions].map((keyword) => keyword.trim()).filter(Boolean))];
+}
+function clampImportance(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function stripTemporalPrefix(text) {
+    if (!text.startsWith('As of '))
+        return text;
+    const userIndex = text.toLowerCase().indexOf('user ');
+    if (userIndex === -1)
+        return text;
+    return text.slice(userIndex);
+}
+function stripTrailingPunctuation(text) {
+    return text.trim().replace(/[. ]+$/, '');
+}
+function capitalize(text) {
+    return text.charAt(0).toUpperCase() + text.slice(1);
+}

package/dist/services/filecoin-observability.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Structured observability for the Filecoin raw-storage lifecycle.
+ *
+ * Mirrors the `audit-events.ts` shape: typed event payloads emitted
+ * as single-line JSON to stdout, prefixed with `[FILECOIN]` for grep
+ * / log-aggregator filtering. No metrics framework is invented — the
+ * implementation uses log-based aggregation because core does not
+ * have a metrics seam today. Operators can derive counters, gauges,
+ * and histograms from the event stream.
+ *
+ * Sanitization is the load-bearing invariant: events MUST NOT carry
+ * UCAN proofs, principal keys, codec keys, AES-GCM nonces / tags, or
+ * any other credential surface. The module enforces this two ways:
+ *
+ *   1. The typed `FilecoinEventPayload` is a CLOSED record over a
+ *      small set of allow-listed fields. Callers cannot accidentally
+ *      pass a wire-shape `raw_storage_metadata` blob.
+ *   2. `sanitizeErrorMessage` strips UCAN/`did:key:`/base64-key
+ *      lookalikes before they enter the event stream. The function
+ *      is exported so the scheduler's `logReconcilerError` and any
+ *      future call-site share the same redaction rule.
+ *
+ * `computePendingAgeSeconds(pendingSince)` is the pure helper for
+ * pending-age gauges; it carries a single contract (NULL → null;
+ * otherwise integer seconds from the timestamp to `now`) so the
+ * metric definition stays in one place.
+ */
+export type FilecoinEventName = 'filecoin.upload.started' | 'filecoin.upload.accepted' | 'filecoin.upload.failed' | 'filecoin.reconcile.claimed' | 'filecoin.reconcile.promoted' | 'filecoin.reconcile.archival_failed' | 'filecoin.reconcile.stale_claim_recovered' | 'filecoin.reconcile.failure' | 'filecoin.retrieval.verification_failed' | 'filecoin.delete.tombstoned' | 'filecoin.delete.unpinned' | 'filecoin.hint.malformed';
+/**
+ * Closed allowlist of fields that may travel on an event payload.
+ * Adding a field here is the EXPLICIT permission to surface it on
+ * the wire — credentials/proofs/codec keys do not appear and must
+ * never be added without a redaction review.
+ */
+export interface FilecoinEventPayload {
+    documentId?: string;
+    userId?: string;
+    /** Storage provider key as it appears on the row (`'filecoin'`). */
+    provider?: string;
+    statusBefore?: string;
+    statusAfter?: string;
+    /** Reconciler claim UUID; never embeds vendor data. */
+    claimId?: string;
+    /** Categorical, vendor-free (see `FilecoinOnrampErrorCode`). */
+    errorCode?: string;
+    /** Already-sanitized short message — pass through `sanitizeErrorMessage`. */
+    errorMessage?: string;
+    /** Operation duration for upload latency aggregation. */
+    durationMs?: number;
+    /** Reconciler batch size — drives `reconcile_batches_total` aggregation. */
+    batchSize?: number;
+    /** Reconciler attempt count for the row at the time of the event. */
+    reconcileAttempts?: number;
+    /** Pending-age gauge sample, computed via `computePendingAgeSeconds`. */
+    pendingAgeSeconds?: number;
+    /**
+     * On-chain `0x…` transaction hash returned by the Synapse SDK's
+     * `deletePiece` call (the scheduled-removal tx). Surfaced by the
+     * `filecoin.delete.tombstoned` event so operators can correlate
+     * a cleanup pass to chain-side gas cost. Internal-only — the
+     * field NEVER appears on a route response; the route layer
+     * never reads `FilecoinEventPayload`. Phase 7
+     * billing/cost-impact-metadata channel for uncertain delete
+     * outcomes.
+     */
+    deleteTxHash?: string;
+}
+export interface FilecoinEvent {
+    event: FilecoinEventName;
+    timestamp: string;
+    detail: FilecoinEventPayload;
+}
+export interface FilecoinObservabilityConfig {
+    enabled: boolean;
+    logToStdout: boolean;
+}
+/** Override the module's emission config — used by tests to suppress stdout. */
+export declare function configureFilecoinObservability(config: Partial<FilecoinObservabilityConfig>): void;
+export declare function resetFilecoinObservabilityConfig(): void;
+export declare function isFilecoinObservabilityEnabled(): boolean;
+/**
+ * Pure builder — returns the event object without emitting.
+ *
+ * `detail` is run through `projectPayload` so an object variable carrying extra
+ * credential-shaped fields (`raw_storage_metadata`, `proof`,
+ * `codec`, …) loses them before the event materialises. Any
+ * `errorMessage` is sanitized at the same boundary so call sites
+ * are free to pass raw probe/transport messages.
+ */
+export declare function buildFilecoinEvent(event: FilecoinEventName, detail: FilecoinEventPayload): FilecoinEvent;
+export declare function serializeFilecoinEvent(event: FilecoinEvent): string;
+/**
+ * Emit a structured event. No-op when observability is disabled.
+ * Tests typically call `configureFilecoinObservability({ logToStdout:
+ * false })` and spy on `console.log` directly — keeps assertions
+ * decoupled from the prefix string.
+ */
+export declare function emitFilecoinEvent(event: FilecoinEventName, detail: FilecoinEventPayload): void;
+/**
+ * Bounded-length sanitizer for an error message destined for the
+ * event stream. Strips:
+ *
+ *   - `did:key:…` principal-key lookalikes
+ *   - long base64/base64url runs (UCAN proofs are ~200+ chars)
+ *   - codec key/nonce/tag JSON fragments
+ *
+ * Final length-cap protects log volume + acts as a defence in depth
+ * if a future error type slips through with a structured payload in
+ * its message.
+ */
+export declare function sanitizeErrorMessage(input: unknown): string;
+/**
+ * Scheduler error-logger shared by the reconciler's `onError` hook
+ * (rev-8 §8). Centralized so a future telemetry sink swap touches
+ * one call site.
+ */
+export declare function logReconcilerError(err: unknown): void;
+/**
+ * Convert a `raw_storage_pending_since` column value to integer
+ * seconds since the row entered `blob_pending`. Rows that never
+ * entered `blob_pending` (or were promoted / failed terminally)
+ * return `null`.
+ *
+ * `now` defaults to the wall clock — pass it explicitly in tests for
+ * deterministic assertions (no Date.now mocking required).
+ */
+export declare function computePendingAgeSeconds(pendingSince: Date | string | null | undefined, now?: Date): number | null;

package/dist/services/filecoin-observability.js

@@ -0,0 +1,200 @@
+/**
+ * Structured observability for the Filecoin raw-storage lifecycle.
+ *
+ * Mirrors the `audit-events.ts` shape: typed event payloads emitted
+ * as single-line JSON to stdout, prefixed with `[FILECOIN]` for grep
+ * / log-aggregator filtering. No metrics framework is invented — the
+ * implementation uses log-based aggregation because core does not
+ * have a metrics seam today. Operators can derive counters, gauges,
+ * and histograms from the event stream.
+ *
+ * Sanitization is the load-bearing invariant: events MUST NOT carry
+ * UCAN proofs, principal keys, codec keys, AES-GCM nonces / tags, or
+ * any other credential surface. The module enforces this two ways:
+ *
+ *   1. The typed `FilecoinEventPayload` is a CLOSED record over a
+ *      small set of allow-listed fields. Callers cannot accidentally
+ *      pass a wire-shape `raw_storage_metadata` blob.
+ *   2. `sanitizeErrorMessage` strips UCAN/`did:key:`/base64-key
+ *      lookalikes before they enter the event stream. The function
+ *      is exported so the scheduler's `logReconcilerError` and any
+ *      future call-site share the same redaction rule.
+ *
+ * `computePendingAgeSeconds(pendingSince)` is the pure helper for
+ * pending-age gauges; it carries a single contract (NULL → null;
+ * otherwise integer seconds from the timestamp to `now`) so the
+ * metric definition stays in one place.
+ */
+/**
+ * TypeScript's `FilecoinEventPayload` shape only narrows callers
+ * that pass an object LITERAL. A `detail` variable that satisfies
+ * the type but also carries extra credential-shaped fields would
+ * otherwise serialize verbatim because TS erases the excess at
+ * compile time, not run time. `projectPayload` walks the closed
+ * field list and copies ONLY those keys; everything else (planted
+ * `raw_storage_metadata`, `proof`, `codec`, etc.) is dropped before
+ * the payload ever reaches the event stream. `errorMessage` is
+ * additionally run through `sanitizeErrorMessage` here so call sites
+ * can pass raw probe/transport messages without re-sanitizing at
+ * every emit site.
+ */
+const ALLOWED_PAYLOAD_KEYS = [
+    'documentId',
+    'userId',
+    'provider',
+    'statusBefore',
+    'statusAfter',
+    'claimId',
+    'errorCode',
+    'errorMessage',
+    'durationMs',
+    'batchSize',
+    'reconcileAttempts',
+    'pendingAgeSeconds',
+    // Phase 7 billing/cost-impact metadata. Adding this here is
+    // the EXPLICIT runtime permission to carry the on-chain
+    // `0x…` tx hash on the `filecoin.delete.tombstoned` event —
+    // the type-level addition to `FilecoinEventPayload` alone is
+    // not enough because `projectPayload` walks the closed
+    // runtime list and drops anything not on it. Any other
+    // planted field (raw sidecar hints, credentials, vendor
+    // responses) still gets stripped.
+    'deleteTxHash',
+];
+function projectPayload(detail) {
+    const out = {};
+    for (const key of ALLOWED_PAYLOAD_KEYS) {
+        if (!(key in detail))
+            continue;
+        const value = detail[key];
+        if (value === undefined)
+            continue;
+        out[key] =
+            key === 'errorMessage'
+                ? sanitizeErrorMessage(value)
+                : value;
+    }
+    return out;
+}
+const DEFAULT_CONFIG = {
+    enabled: true,
+    logToStdout: true,
+};
+let currentConfig = { ...DEFAULT_CONFIG };
+/** Override the module's emission config — used by tests to suppress stdout. */
+export function configureFilecoinObservability(config) {
+    currentConfig = { ...currentConfig, ...config };
+}
+export function resetFilecoinObservabilityConfig() {
+    currentConfig = { ...DEFAULT_CONFIG };
+}
+export function isFilecoinObservabilityEnabled() {
+    return currentConfig.enabled;
+}
+/**
+ * Pure builder — returns the event object without emitting.
+ *
+ * `detail` is run through `projectPayload` so an object variable carrying extra
+ * credential-shaped fields (`raw_storage_metadata`, `proof`,
+ * `codec`, …) loses them before the event materialises. Any
+ * `errorMessage` is sanitized at the same boundary so call sites
+ * are free to pass raw probe/transport messages.
+ */
+export function buildFilecoinEvent(event, detail) {
+    return {
+        event,
+        timestamp: new Date().toISOString(),
+        detail: projectPayload(detail),
+    };
+}
+export function serializeFilecoinEvent(event) {
+    return `[FILECOIN] ${JSON.stringify(event)}`;
+}
+/**
+ * Emit a structured event. No-op when observability is disabled.
+ * Tests typically call `configureFilecoinObservability({ logToStdout:
+ * false })` and spy on `console.log` directly — keeps assertions
+ * decoupled from the prefix string.
+ */
+export function emitFilecoinEvent(event, detail) {
+    if (!currentConfig.enabled)
+        return;
+    const built = buildFilecoinEvent(event, detail);
+    if (currentConfig.logToStdout) {
+        // eslint-disable-next-line no-console
+        console.log(serializeFilecoinEvent(built));
+    }
+}
+/**
+ * Bounded-length sanitizer for an error message destined for the
+ * event stream. Strips:
+ *
+ *   - `did:key:…` principal-key lookalikes
+ *   - long base64/base64url runs (UCAN proofs are ~200+ chars)
+ *   - codec key/nonce/tag JSON fragments
+ *
+ * Final length-cap protects log volume + acts as a defence in depth
+ * if a future error type slips through with a structured payload in
+ * its message.
+ */
+export function sanitizeErrorMessage(input) {
+    const raw = input instanceof Error
+        ? input.message
+        : typeof input === 'string'
+            ? input
+            : '';
+    return applyRedactionRules(raw).slice(0, MAX_ERROR_MESSAGE_LEN);
+}
+const MAX_ERROR_MESSAGE_LEN = 200;
+function applyRedactionRules(s) {
+    return s
+        // `did:key:z…` principal-key identifiers
+        .replace(/did:key:[A-Za-z0-9_-]+/g, '[REDACTED_PRINCIPAL]')
+        // long base64/base64url runs that look like UCAN proofs
+        .replace(/[A-Za-z0-9_+/=-]{40,}/g, '[REDACTED_BASE64]')
+        // codec/AES-GCM internal field labels (`key_id`, `nonce`, `tag`)
+        // when they appear with a value separator
+        .replace(/(key_id|nonce|tag)\s*[:=]\s*\S+/gi, '$1=[REDACTED]')
+        // raw-storage env vars that look credential-bearing
+        .replace(/RAW_STORAGE_[A-Z0-9_]*(?:PRIVATE_KEY|TOKEN|SECRET|AUTH)[A-Z0-9_]*/g, '[REDACTED_ENV]');
+}
+/**
+ * Scheduler error-logger shared by the reconciler's `onError` hook
+ * (rev-8 §8). Centralized so a future telemetry sink swap touches
+ * one call site.
+ */
+export function logReconcilerError(err) {
+    const code = extractErrorCode(err);
+    emitFilecoinEvent('filecoin.reconcile.failure', {
+        errorCode: code,
+        errorMessage: sanitizeErrorMessage(err),
+    });
+}
+function extractErrorCode(err) {
+    if (err instanceof Error) {
+        const candidate = err.code;
+        if (typeof candidate === 'string')
+            return candidate;
+    }
+    return 'unknown';
+}
+/**
+ * Convert a `raw_storage_pending_since` column value to integer
+ * seconds since the row entered `blob_pending`. Rows that never
+ * entered `blob_pending` (or were promoted / failed terminally)
+ * return `null`.
+ *
+ * `now` defaults to the wall clock — pass it explicitly in tests for
+ * deterministic assertions (no Date.now mocking required).
+ */
+export function computePendingAgeSeconds(pendingSince, now = new Date()) {
+    if (pendingSince === null || pendingSince === undefined)
+        return null;
+    const start = pendingSince instanceof Date ? pendingSince : new Date(pendingSince);
+    if (Number.isNaN(start.getTime()))
+        return null;
+    const ageMs = now.getTime() - start.getTime();
+    if (ageMs < 0)
+        return 0;
+    return Math.floor(ageMs / 1000);
+}

package/dist/services/first-mention-service.d.ts

@@ -0,0 +1,76 @@
+/**
+ * First-mention extraction service — produces a chronological list of
+ * topic-introduction events from a conversation transcript.
+ *
+ * One LLM call scans the full transcript and outputs a JSON array of
+ * `{topic, turn_id, session_id, anchor_date}` records. The service
+ * maps those onto core's stricter `FirstMentionEvent` shape (joining
+ * turn_id to memory_id via a caller-supplied map) and persists via
+ * `FirstMentionRepository.store`.
+ *
+ * Best-effort: extraction failures are logged to stderr and produce an
+ * empty array. Storage errors are propagated (no silent swallow).
+ *
+ * Prompts and salvage parser were ported verbatim from the BEAM harness
+ * (`atomicmemory-benchmarks/data/exp-stage7-beam-dryrun/lib.ts`) so the
+ * core implementation matches the validated extraction behaviour.
+ */
+import { FirstMentionRepository, type FirstMentionEvent } from '../db/repository-first-mentions.js';
+/**
+ * Minimal chat-call shape for first-mention extraction.
+ *
+ * Token usage is intentionally not threaded here: cost telemetry for the
+ * underlying LLM call is already emitted from `LLMProvider.chat` (see
+ * `src/services/llm.ts` -> `writeCostEvent`). Reading per-call usage at
+ * this layer would require widening the LLMProvider.chat return type to
+ * include usage and plumbing it through every adapter; until something in
+ * the FirstMentionService path actually consumes it, the extra surface
+ * area would only invite hardcoded zeros that mislead downstream readers.
+ */
+interface ChatResult {
+    text: string;
+}
+type ChatFn = (system: string, user: string, maxTokens: number) => Promise<ChatResult>;
+export declare class FirstMentionService {
+    private repo;
+    private chatFn;
+    constructor(repo: FirstMentionRepository, chatFn: ChatFn);
+    /**
+     * Extract first-mention events from a conversation transcript and
+     * persist them. Returns the parsed events (post-mapping). Best-effort:
+     * if the LLM call fails or returns unparseable output the method
+     * logs to stderr and returns `[]` without throwing.
+     *
+     * `memoryIdsByTurnId` provides the mapping the LLM cannot produce —
+     * any event whose `turn_id` is not present in the map is dropped.
+     */
+    extractAndStore(userId: string, conversationText: string, sourceSite: string, memoryIdsByTurnId: Map<number, string>): Promise<FirstMentionEvent[]>;
+    /**
+     * Run the extraction LLM call; return parsed array or null on failure.
+     *
+     * Fail-open by design: a flaky upstream LLM call should not crash the
+     * caller's `extractAndStore` invocation; the EO read path treats a
+     * missing first-mention list as "no signal" rather than a hard
+     * failure. The deliberate fallback is a structured
+     * `[first-mention-llm-failed]` log line plus null return so the
+     * failure is observable.
+     */
+    private invokeLlm;
+    /**
+     * Map LLM output records onto core's `FirstMentionEvent` shape.
+     *
+     * `positionInConversation` is the 0-based index in the FINAL turn-id-
+     * sorted output, NOT `turn_id` itself. This makes the mapping stable
+     * across re-runs even when the LLM emits a slightly different
+     * `turn_id` for the same logical topic on a second pass — the
+     * `(user_id, memory_id)` UNIQUE constraint in `first_mention_events`
+     * skips the duplicate insert, but if `position_in_conversation`
+     * tracked `turn_id` directly, an unrelated drift in the second run's
+     * turn assignment would mean callers reading the row see whichever
+     * turn_id was first written. Encoding position by post-sort index
+     * eliminates that variability — read-side ordering is now a stable
+     * sequence (0, 1, 2, ...) regardless of which LLM run produced it.
+     */
+    private mapToEvents;
+}
+export {};