@atomicmemory/core 1.0.0

package/dist/services/raw-storage-reconciler-scheduler.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Scheduler wrapper around `runOnce`. Owns the `setInterval` handle,
+ * prevents overlapping runs, and exposes an
+ * explicit `stop()` that awaits any in-flight tick before resolving.
+ *
+ * NOT auto-started from `createCoreRuntime` — tests never want a
+ * background timer firing in the middle of seeded-row assertions.
+ * Production composition (a separate boot path) explicitly calls
+ * `startReconciler(deps)` when the runtime container hands back a
+ * non-null `reconcilerDeps` bundle and adds `scheduler.stop` to the
+ * graceful-shutdown hook.
+ */
+import { type ReconcilerDeps } from './raw-storage-reconciler.js';
+export interface ReconcilerScheduler {
+    /** Clears the interval and awaits the in-flight `runOnce()`. */
+    stop(): Promise<void>;
+    /** True while a `runOnce()` invocation is in flight. */
+    readonly isRunning: boolean;
+}
+export interface SchedulerOptions extends ReconcilerDeps {
+    /** Polling interval — `setInterval(tick, intervalMs)`. */
+    intervalMs: number;
+    /**
+     * Called with the error if `runOnce()` rejects. Sanitization is
+     * the caller's responsibility.
+     */
+    onError?: (err: unknown) => void;
+}
+export declare function startReconciler(options: SchedulerOptions): ReconcilerScheduler;

package/dist/services/raw-storage-reconciler-scheduler.js

@@ -0,0 +1,43 @@
+/**
+ * Scheduler wrapper around `runOnce`. Owns the `setInterval` handle,
+ * prevents overlapping runs, and exposes an
+ * explicit `stop()` that awaits any in-flight tick before resolving.
+ *
+ * NOT auto-started from `createCoreRuntime` — tests never want a
+ * background timer firing in the middle of seeded-row assertions.
+ * Production composition (a separate boot path) explicitly calls
+ * `startReconciler(deps)` when the runtime container hands back a
+ * non-null `reconcilerDeps` bundle and adds `scheduler.stop` to the
+ * graceful-shutdown hook.
+ */
+import { runOnce } from './raw-storage-reconciler.js';
+export function startReconciler(options) {
+    let isRunning = false;
+    let stopped = false;
+    let inFlight = Promise.resolve();
+    const tick = () => {
+        if (stopped || isRunning)
+            return;
+        isRunning = true;
+        inFlight = runOnce(options)
+            .then(() => undefined)
+            .catch((err) => {
+            if (options.onError)
+                options.onError(err);
+        })
+            .finally(() => {
+            isRunning = false;
+        });
+    };
+    const handle = setInterval(tick, options.intervalMs);
+    return {
+        get isRunning() {
+            return isRunning;
+        },
+        async stop() {
+            stopped = true;
+            clearInterval(handle);
+            await inFlight;
+        },
+    };
+}

package/dist/services/raw-storage-reconciler.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Raw-storage reconciler — promotes `blob_pending` Filecoin
+ * rows to `blob_available` once gateway retrievability is confirmed,
+ * or marks them `blob_archival_failed` after retry exhaustion.
+ *
+ * `runOnce(deps)` is the deterministic, side-effect-bounded entry
+ * point tests call directly. The scheduler (a separate module) wraps
+ * it in a timer-driven loop for production use. NEVER calls
+ * setTimeout/setInterval internally — backoff scheduling lives on
+ * the row's `raw_storage_next_check_at` column, not in process memory.
+ */
+import pg from 'pg';
+import type { RawContentStore } from '../storage/raw-content-store.js';
+import type { RawContentCodec } from '../storage/raw-content-codec.js';
+export { computeBackoffMs } from './raw-storage-reconciler-backoff.js';
+export interface ReconcilerDeps {
+    pool: pg.Pool;
+    /**
+     * Active Filecoin adapter (or any adapter whose capabilities map
+     * cleanly onto `head()`-returns-retrievability). The reconciler
+     * calls `store.head(storage_uri)` for each claimed row outside
+     * any DB tx; in `hash_verify` mode it additionally calls `get()`.
+     */
+    store: RawContentStore;
+    /**
+     * Content codec the upload service wrapped around the adapter's
+     * `put()`. The reconciler's `hash_verify` mode uses
+     * `codec.decode()` to reverse the encoding before sha256-comparing
+     * the bytes to the row's `content_hash`. Ignored in `head_only`
+     * mode; supplied unconditionally by `createCoreRuntime` so the
+     * dep bundle stays the same shape across modes.
+     */
+    codec: RawContentCodec;
+    /**
+     * Verification depth before promoting `blob_pending` →
+     * `blob_available`:
+     *
+     *   - `'head_only'`: trust the adapter's `head()` exists-check.
+     *     Confirms retrievability but does NOT decode the bytes.
+     *   - `'hash_verify'`: after `head()` confirms retrievability,
+     *     `get()` the bytes, decode with the active codec, sha256 the
+     *     plaintext, and compare to the row's `content_hash`. A
+     *     mismatch routes the row to `blob_archival_failed` with
+     *     code `content_hash_mismatch`.
+     *
+     * Runtime config may surface this knob later; the reconciler takes
+     * the resolved value directly.
+     */
+    verifyMode: 'head_only' | 'hash_verify';
+    batchSize: number;
+    staleAfterMs: number;
+    baseIntervalMs: number;
+    backoffMaxMs: number;
+    maxAttempts: number;
+    /**
+     * Injectable clock for `pendingAgeSeconds` math. Defaults to `new Date()` in
+     * production; tests pass a fixed `Date` so the integration
+     * assertions can lock the exact age the event carries instead
+     * of a wall-clock range. Pure deterministic substitution; no
+     * timing-dependent test logic.
+     */
+    now?: () => Date;
+}
+export interface ReconcilerRunSummary {
+    claimed: number;
+    promoted: number;
+    stillPending: number;
+    archivalFailed: number;
+    lostClaim: number;
+}
+export declare function runOnce(deps: ReconcilerDeps): Promise<ReconcilerRunSummary>;

package/dist/services/raw-storage-reconciler.js

@@ -0,0 +1,278 @@
+/**
+ * Raw-storage reconciler — promotes `blob_pending` Filecoin
+ * rows to `blob_available` once gateway retrievability is confirmed,
+ * or marks them `blob_archival_failed` after retry exhaustion.
+ *
+ * `runOnce(deps)` is the deterministic, side-effect-bounded entry
+ * point tests call directly. The scheduler (a separate module) wraps
+ * it in a timer-driven loop for production use. NEVER calls
+ * setTimeout/setInterval internally — backoff scheduling lives on
+ * the row's `raw_storage_next_check_at` column, not in process memory.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { buildLastError } from '../db/raw-document-status-repository.js';
+import { claimReconcileBatch, markStillPendingWithClient, } from '../db/raw-storage-reconciliation-repository.js';
+import { markArchivalFailedAndSyncArtifact, promoteAndSyncArtifact, } from '../db/raw-doc-artifact-sync.js';
+import { computePendingAgeSeconds, emitFilecoinEvent, } from './filecoin-observability.js';
+import { computeBackoffMs } from './raw-storage-reconciler-backoff.js';
+export { computeBackoffMs } from './raw-storage-reconciler-backoff.js';
+function clockNow(deps) {
+    return deps.now ? deps.now() : new Date();
+}
+export async function runOnce(deps) {
+    const claimId = randomUUID();
+    const rows = await claimReconcileBatch(deps.pool, {
+        claimId,
+        batchSize: deps.batchSize,
+        staleAfterMs: deps.staleAfterMs,
+        provider: deps.store.provider,
+    });
+    if (rows.length > 0) {
+        emitFilecoinEvent('filecoin.reconcile.claimed', {
+            provider: deps.store.provider,
+            claimId,
+            batchSize: rows.length,
+        });
+    }
+    for (const row of rows) {
+        if (row.recoveredStaleClaim) {
+            emitFilecoinEvent('filecoin.reconcile.stale_claim_recovered', {
+                documentId: row.id,
+                userId: row.userId,
+                provider: row.storageProvider,
+                claimId,
+                reconcileAttempts: row.rawStorageReconcileAttempts,
+                pendingAgeSeconds: computePendingAgeSeconds(row.rawStoragePendingSince, clockNow(deps)) ?? undefined,
+            });
+        }
+    }
+    const summary = {
+        claimed: rows.length, promoted: 0, stillPending: 0, archivalFailed: 0, lostClaim: 0,
+    };
+    for (const row of rows) {
+        const outcome = await processOneRow(deps, row, claimId);
+        if (outcome === 'promoted')
+            summary.promoted += 1;
+        else if (outcome === 'still_pending')
+            summary.stillPending += 1;
+        else if (outcome === 'archival_failed')
+            summary.archivalFailed += 1;
+        else
+            summary.lostClaim += 1;
+    }
+    return summary;
+}
+async function processOneRow(deps, row, claimId) {
+    // Hand the row's `raw_storage_metadata` to the adapter so an
+    // eventual-consistency provider (Filecoin) can short-circuit
+    // its lookup using the provider-specific sidecar it wrote at
+    // `put` time (e.g. `data_set_id`). The adapter validates +
+    // ignores malformed entries; non-Filecoin adapters ignore the
+    // argument entirely.
+    const hints = row.rawStorageMetadata;
+    const probe = await probeHead(deps.store, row.storageUri, hints);
+    if (probe.kind === 'retrievable') {
+        return handleRetrievable(deps, row, claimId, probe);
+    }
+    if (probe.kind === 'permanent_failure') {
+        return archivalFailFromProbe(deps, row, claimId, probe.code, probe.message);
+    }
+    // Transient/pending outcomes. A late retrievable from a
+    // high-attempt-count row must still promote — we never fail on
+    // top of a successful probe (rev-7 §7).
+    return persistPendingOutcome(deps, row, claimId, probe);
+}
+/**
+ * `retrievable` branch. In `head_only` mode the promotion is
+ * unconditional; in `hash_verify` mode we first `get()` the bytes,
+ * decode through the codec, sha256 the plaintext, and compare to
+ * the row's `content_hash`. Mismatch → permanent failure; transport/
+ * decode errors stay transient.
+ */
+async function handleRetrievable(deps, row, claimId, probe) {
+    if (deps.verifyMode === 'hash_verify') {
+        const verify = await verifyContentHash(deps, row);
+        if (verify.kind === 'mismatch') {
+            emitFilecoinEvent('filecoin.retrieval.verification_failed', {
+                documentId: row.id,
+                userId: row.userId,
+                provider: row.storageProvider,
+                claimId,
+                errorCode: 'content_hash_mismatch',
+                errorMessage: verify.message,
+            });
+            return archivalFailFromProbe(deps, row, claimId, 'content_hash_mismatch', verify.message);
+        }
+        if (verify.kind === 'error') {
+            emitFilecoinEvent('filecoin.retrieval.verification_failed', {
+                documentId: row.id,
+                userId: row.userId,
+                provider: row.storageProvider,
+                claimId,
+                errorCode: 'verify_transport_error',
+                errorMessage: verify.message,
+            });
+            return persistPendingOutcome(deps, row, claimId, { kind: 'error', message: verify.message });
+        }
+    }
+    const rowCount = await promoteAndSyncArtifact(deps.pool, {
+        rowId: row.id,
+        claimId,
+        provider: row.storageProvider,
+        providerFields: extractProviderHeadMetadata(row.storageProvider, probe.providerMetadata),
+    });
+    if (rowCount === 1) {
+        emitFilecoinEvent('filecoin.reconcile.promoted', {
+            documentId: row.id,
+            userId: row.userId,
+            provider: row.storageProvider,
+            claimId,
+            statusBefore: 'blob_pending',
+            statusAfter: 'blob_available',
+            reconcileAttempts: row.rawStorageReconcileAttempts,
+            pendingAgeSeconds: computePendingAgeSeconds(row.rawStoragePendingSince, clockNow(deps)) ?? undefined,
+        });
+        return 'promoted';
+    }
+    return 'lost_claim';
+}
+/**
+ * Per-row permanent failure — skip
+ * straight to terminal `blob_archival_failed` without burning
+ * retries. Caller categorizes the failure (`content_hash_mismatch`,
+ * `onramp_reported_failed`, `malformed_storage_uri`, …) via `code`.
+ */
+async function archivalFailFromProbe(deps, row, claimId, code, message) {
+    const rowCount = await markArchivalFailedAndSyncArtifact(deps.pool, {
+        rowId: row.id,
+        claimId,
+        lastError: buildLastError('raw_storage', code, message),
+        provider: row.storageProvider,
+    });
+    if (rowCount === 1) {
+        emitFilecoinEvent('filecoin.reconcile.archival_failed', {
+            documentId: row.id,
+            userId: row.userId,
+            provider: row.storageProvider,
+            claimId,
+            statusBefore: 'blob_pending',
+            statusAfter: 'blob_archival_failed',
+            errorCode: code,
+            errorMessage: message,
+            reconcileAttempts: row.rawStorageReconcileAttempts,
+            pendingAgeSeconds: computePendingAgeSeconds(row.rawStoragePendingSince, clockNow(deps)) ?? undefined,
+        });
+        return 'archival_failed';
+    }
+    return 'lost_claim';
+}
+/**
+ * `hash_verify` integrity check: `get()` + `decode()` + sha256 +
+ * compare against `row.contentHash`. Categorizes failures:
+ *
+ *   - `'match'`     → bytes decode to the registered plaintext hash.
+ *   - `'mismatch'`  → bytes decoded fine but hash disagrees. This
+ *     is a per-row terminal failure; the row cannot satisfy the
+ *     integrity contract no matter how many retries.
+ *   - `'error'`     → transport or decode threw. Likely a global
+ *     infra/config problem (gateway 5xx, missing codec key, codec
+ *     metadata sidecar absent on the row). Stays transient so a
+ *     misconfigured deployment doesn't permanently fail every row.
+ *
+ * A row with `content_hash === null` is treated as `'error'`: it
+ * shouldn't happen for a Phase-5 Filecoin `blob_pending` row (Phase
+ * α writes the plaintext hash), and if it does, we want the
+ * operator to debug it, not flip the row to terminal.
+ */
+async function verifyContentHash(deps, row) {
+    if (!row.contentHash) {
+        return { kind: 'error', message: 'row has no content_hash; cannot verify' };
+    }
+    try {
+        const got = await deps.store.get(row.storageUri);
+        const codecMetadata = extractCodecMetadata(row.rawStorageMetadata);
+        const decoded = await deps.codec.decode({ body: got.body, metadata: codecMetadata });
+        const observed = sha256Hex(decoded.body);
+        if (observed === row.contentHash)
+            return { kind: 'match' };
+        return {
+            kind: 'mismatch',
+            message: `expected content_hash ${row.contentHash}, decoded bytes hash to ${observed}`,
+        };
+    }
+    catch (err) {
+        return { kind: 'error', message: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Read the codec sidecar the durable URI-write step wrote into `raw_storage_metadata.codec`.
+ * Falls back to a `{ name: 'none', version: 1 }` shape so a row missing
+ * the sidecar (e.g. legacy / hand-seeded) decodes through the noop
+ * path instead of throwing on shape mismatch.
+ */
+function extractCodecMetadata(metadata) {
+    const codec = metadata['codec'];
+    if (codec && typeof codec === 'object' && 'name' in codec && 'version' in codec) {
+        return codec;
+    }
+    return { name: 'none', version: 1 };
+}
+function sha256Hex(buf) {
+    return createHash('sha256').update(buf).digest('hex');
+}
+async function probeHead(store, storageUri, hints) {
+    try {
+        const result = await store.head(storageUri, hints);
+        if (result.exists) {
+            const providerMetadata = result.metadata?.providerMetadata ?? {};
+            return { kind: 'retrievable', providerMetadata };
+        }
+        if (result.failure) {
+            return {
+                kind: 'permanent_failure',
+                code: result.failure.code,
+                message: result.failure.message,
+            };
+        }
+        return { kind: 'pending' };
+    }
+    catch (err) {
+        // Thrown errors are transient by default — global infra failures
+        // (auth, rate-limit, gateway 5xx) affect every row, and we must
+        // NOT flip every pending row to `blob_archival_failed` on a
+        // misconfigured deployment. Adapters that want to signal a
+        // per-row permanent failure return `{ exists: false, failure }`
+        // explicitly.
+        return {
+            kind: 'error',
+            message: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Pull just the active provider sibling out of the adapter's head
+ * metadata. Eventual providers return `{ [provider]: {...} }`;
+ * unknown or malformed siblings merge as `{}`.
+ */
+function extractProviderHeadMetadata(provider, providerMetadata) {
+    const providerFields = providerMetadata[provider];
+    if (providerFields && typeof providerFields === 'object' && !Array.isArray(providerFields)) {
+        return providerFields;
+    }
+    return {};
+}
+async function persistPendingOutcome(deps, row, claimId, probe) {
+    const nextAttempts = row.rawStorageReconcileAttempts + 1;
+    if (nextAttempts >= deps.maxAttempts) {
+        const code = probe.kind === 'error' ? 'reconcile_probe_error' : 'reconcile_attempts_exhausted';
+        const message = probe.kind === 'error'
+            ? `probe failed after ${nextAttempts} attempts: ${probe.message}`
+            : `pending after ${nextAttempts} reconciliation attempts`;
+        return archivalFailFromProbe(deps, row, claimId, code, message);
+    }
+    const nextCheckAtMs = computeBackoffMs(nextAttempts, deps.baseIntervalMs, deps.backoffMaxMs);
+    const rowCount = await markStillPendingWithClient(deps.pool, {
+        rowId: row.id, claimId, nextCheckAtMs, provider: row.storageProvider,
+    });
+    return rowCount === 1 ? 'still_pending' : 'lost_claim';
+}

package/dist/services/recap-builder.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Recap layer (Sprint 3 v1) — pre-computed cross-session synthesis.
+ *
+ * For each cluster of N+ memories that share a conceptual topic, generate
+ * an LLM-synthesized narrative ("Episode") and store it as a separate
+ * retrievable unit with its own embedding. Cross-session questions ("how
+ * did the auth design evolve across sessions?") retrieve the Recap
+ * directly instead of re-synthesizing N raw facts at query time.
+ *
+ * Cog-sci analogue: hippocampal consolidation. Three of the four next-gen
+ * memory systems converge on this primitive (Hindsight observations,
+ * Honcho dreaming, X-Mem Episodes, EverMemOS multi-pass restructuring).
+ *
+ * Cluster pivot: `topic_abstraction` field. Requires topic-abstraction
+ * layer to be ON during ingest so memories carry topic tags. The clustering
+ * is simple grouping by exact topic string + user; embedding-based nearest-
+ * neighbor clustering is a v1.1 enhancement.
+ *
+ * Trigger: post-write hook checks if any topic for the user crosses
+ * recapMinClusterSize un-consolidated memories. Builder fires async
+ * (no await) so ingest latency is unaffected.
+ *
+ * Feature flag: recapLayerEnabled (default OFF).
+ *
+ * See benchmarks-sprint3/2026-05-10-am-baseline-and-rerank-design.md.
+ */
+import type { LLMProvider } from './llm.js';
+import type { MemoryServiceDeps } from './memory-service-types.js';
+export interface RecapContent {
+    narrative: string;
+}
+export declare class RecapBuilderError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+/**
+ * Synthesize an episode narrative from a cluster of memory contents.
+ * Fail-closed: throws RecapBuilderError. Caller decides whether to fail
+ * the post-write step or just log.
+ */
+export declare function synthesizeRecap(topic: string, memberContents: string[], llmClient?: LLMProvider): Promise<RecapContent>;
+/**
+ * Background trigger for episode building. Checks each user-topic pair for
+ * un-consolidated clusters meeting the size threshold; for each qualifying
+ * cluster, synthesizes + stores a Recap.
+ *
+ * Fire-and-forget from post-write — never throws to caller.
+ */
+export declare function maybeBuildRecapsForUser(deps: MemoryServiceDeps, userId: string): Promise<number>;

package/dist/services/recap-builder.js

@@ -0,0 +1,157 @@
+/**
+ * Recap layer (Sprint 3 v1) — pre-computed cross-session synthesis.
+ *
+ * For each cluster of N+ memories that share a conceptual topic, generate
+ * an LLM-synthesized narrative ("Episode") and store it as a separate
+ * retrievable unit with its own embedding. Cross-session questions ("how
+ * did the auth design evolve across sessions?") retrieve the Recap
+ * directly instead of re-synthesizing N raw facts at query time.
+ *
+ * Cog-sci analogue: hippocampal consolidation. Three of the four next-gen
+ * memory systems converge on this primitive (Hindsight observations,
+ * Honcho dreaming, X-Mem Episodes, EverMemOS multi-pass restructuring).
+ *
+ * Cluster pivot: `topic_abstraction` field. Requires topic-abstraction
+ * layer to be ON during ingest so memories carry topic tags. The clustering
+ * is simple grouping by exact topic string + user; embedding-based nearest-
+ * neighbor clustering is a v1.1 enhancement.
+ *
+ * Trigger: post-write hook checks if any topic for the user crosses
+ * recapMinClusterSize un-consolidated memories. Builder fires async
+ * (no await) so ingest latency is unaffected.
+ *
+ * Feature flag: recapLayerEnabled (default OFF).
+ *
+ * See benchmarks-sprint3/2026-05-10-am-baseline-and-rerank-design.md.
+ */
+import { llm as defaultLlm } from './llm.js';
+import { extractFirstJsonObject } from './extraction.js';
+import { embedText } from './embedding.js';
+const RECAP_MAX_TOKENS = 1024;
+const RECAP_MAX_MEMBER_CONTENT_CHARS = 600;
+const RECAP_TARGET_WORD_COUNT = 200;
+const RECAP_SYSTEM_PROMPT = [
+    'You synthesize a coherent narrative from a cluster of related memories.',
+    '',
+    'Rules:',
+    '- The cluster shares a conceptual topic (given). Combine the memories into',
+    `  a single narrative of ~${RECAP_TARGET_WORD_COUNT} words capturing how the`,
+    '  topic evolved across the cluster.',
+    '- Preserve specific facts (names, dates, numbers, decisions).',
+    '- Use temporal connectives ("first ... then ... after ... by") so the order',
+    '  is explicit.',
+    '- Do NOT speculate or add information not in the source memories.',
+    '- Output a JSON object: {"narrative": "<200-word narrative>"}.',
+    '- No markdown fences. No prose around the JSON.',
+].join('\n');
+export class RecapBuilderError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = 'RecapBuilderError';
+    }
+}
+/**
+ * Synthesize an episode narrative from a cluster of memory contents.
+ * Fail-closed: throws RecapBuilderError. Caller decides whether to fail
+ * the post-write step or just log.
+ */
+export async function synthesizeRecap(topic, memberContents, llmClient = defaultLlm) {
+    if (memberContents.length === 0) {
+        throw new RecapBuilderError('cannot synthesize recap from zero members');
+    }
+    const messages = [
+        { role: 'system', content: RECAP_SYSTEM_PROMPT },
+        { role: 'user', content: buildEpisodeUserMessage(topic, memberContents) },
+    ];
+    let raw;
+    try {
+        raw = await llmClient.chat(messages, {
+            temperature: 0,
+            jsonMode: true,
+            maxTokens: RECAP_MAX_TOKENS,
+        });
+    }
+    catch (err) {
+        throw new RecapBuilderError(`recap synthesis LLM call failed: ${err.message}`, err);
+    }
+    if (!raw)
+        throw new RecapBuilderError('recap synthesis returned empty content');
+    const cleaned = extractFirstJsonObject(raw);
+    let parsed;
+    try {
+        parsed = JSON.parse(cleaned);
+    }
+    catch (err) {
+        throw new RecapBuilderError(`recap synthesis returned non-JSON: ${cleaned.slice(0, 200)}`, err);
+    }
+    return validateEpisode(parsed);
+}
+function buildEpisodeUserMessage(topic, memberContents) {
+    const truncated = memberContents.map((c, i) => `[${i + 1}] ${c.trim().slice(0, RECAP_MAX_MEMBER_CONTENT_CHARS)}`);
+    return [
+        `TOPIC: ${topic}`,
+        '',
+        `MEMORIES (${memberContents.length}):`,
+        truncated.join('\n\n'),
+        '',
+        'Return JSON: {"narrative": "<200-word narrative weaving the memories together>"}',
+    ].join('\n');
+}
+function validateEpisode(parsed) {
+    const narrative = typeof parsed.narrative === 'string' ? parsed.narrative.trim() : null;
+    if (!narrative) {
+        throw new RecapBuilderError(`recap response missing narrative: ${JSON.stringify(parsed).slice(0, 200)}`);
+    }
+    if (narrative.split(/\s+/).filter(Boolean).length < 20) {
+        throw new RecapBuilderError(`episode narrative too short: "${narrative.slice(0, 100)}"`);
+    }
+    return { narrative };
+}
+/**
+ * Background trigger for episode building. Checks each user-topic pair for
+ * un-consolidated clusters meeting the size threshold; for each qualifying
+ * cluster, synthesizes + stores a Recap.
+ *
+ * Fire-and-forget from post-write — never throws to caller.
+ */
+export async function maybeBuildRecapsForUser(deps, userId) {
+    if (!deps.config.recapLayerEnabled)
+        return 0;
+    const recap = deps.stores.recap;
+    if (!recap)
+        return 0;
+    const minSize = deps.config.recapMinClusterSize;
+    const pivot = deps.config.recapClusterPivot ?? 'topic';
+    let created = 0;
+    try {
+        const clusters = await recap.findUnconsolidatedClusters(userId, minSize, pivot);
+        for (const cluster of clusters) {
+            try {
+                const { narrative } = await synthesizeRecap(cluster.topic, cluster.member_contents);
+                const embedding = await embedText(narrative, 'document');
+                await recap.storeRecap({
+                    userId,
+                    recapText: narrative,
+                    recapEmbedding: embedding,
+                    topic: cluster.topic,
+                    memberMemoryIds: cluster.member_ids,
+                    timeRangeStart: cluster.time_range_start,
+                    timeRangeEnd: cluster.time_range_end,
+                });
+                created += 1;
+            }
+            catch (err) {
+                // Per-cluster fail-soft: log and continue with the next cluster.
+                // The cluster will be retried on the next post-write trigger if the
+                // member count still meets threshold.
+                console.warn(`[episode] synthesis failed for topic="${cluster.topic}" (${cluster.member_ids.length} members): ${err.message}`);
+            }
+        }
+    }
+    catch (err) {
+        console.warn(`[episode] background pass failed for user=${userId}: ${err.message}`);
+    }
+    return created;
+}

package/dist/services/reflect-jobs.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Reflect worker. Pulls one pending job at a time from reflection_jobs,
+ * marks it in_progress, invokes the Reflect orchestrator, and records the
+ * outcome on the job row.
+ *
+ * Mutations fail closed: if Reflect throws, the job is marked failed with
+ * the error message — the loop continues with the next job. The worker never
+ * silently swallows errors.
+ *
+ * Designed for single-instance deployment; multi-instance leasing is out of
+ * scope for v1.
+ */
+import type { ReflectionJobsRepository } from '../db/reflection-jobs-repository.js';
+import type { ReflectResult } from './reflect.js';
+export interface JobsWorkerDeps {
+    jobs: Pick<ReflectionJobsRepository, 'fetchPending' | 'markInProgress' | 'markCompleted' | 'markFailed'>;
+    runReflect: (userId: string, conversationId: string) => Promise<ReflectResult>;
+}
+export declare function processOnePendingJob(deps: JobsWorkerDeps): Promise<boolean>;
+export interface WorkerHandle {
+    stop: () => void;
+}
+export declare function startReflectWorker(deps: JobsWorkerDeps, pollMs: number): WorkerHandle;