@atomicmemory/core 1.0.0

package/dist/services/tiered-loading.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Tiered Context Loading (L0/L1/L2).
+ *
+ * Three representation tiers for each memory, inspired by OpenViking's
+ * SemanticDagExecutor pattern. Token savings come from injecting the
+ * cheapest tier that preserves enough signal for the model to act on.
+ *
+ *   L0  — Abstract/headline (~10-20 tokens). Stored in `summary`.
+ *   L1  — Condensed overview (~100-200 tokens). Stored in `overview`.
+ *   L2  — Full content (variable). Stored in `content`.
+ *
+ * Tier selection is driven by a token budget: the caller declares how
+ * many tokens are available for context injection, and `assignTiers`
+ * decides the best tier per memory to maximize information within budget.
+ *
+ * Strategy:
+ *   1. Greedy L0-fit: include ranked memories at L0 only while the
+ *      cumulative L0 sum fits the budget; tail that can't fit is excluded.
+ *   2. Within the included set, reserve L2 for the top 1–2 results.
+ *   3. Promote a bounded support slice to L1.
+ *   4. Track which exclusions and demotions were budget-driven (vs
+ *      quota-driven) so callers can surface `meta.budget_constrained`
+ *      truthfully without resorting to heuristics.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+export type ContextTier = 'L0' | 'L1' | 'L2';
+export interface TierAssignment {
+    memoryId: string;
+    tier: ContextTier;
+    estimatedTokens: number;
+}
+export interface TierBudgetResult {
+    assignments: TierAssignment[];
+    totalTokens: number;
+    budgetUsed: number;
+    /** Memories that survived L0-fit and were rendered into the package. */
+    includedMemories: SearchResult[];
+    /** Memories dropped because their L0 representation did not fit the budget. */
+    excludedMemoryIds: string[];
+    /**
+     * Memories kept at a lower tier than they were eligible for, solely
+     * because the budget could not afford the upgrade. Quota-only blocks
+     * (e.g. MAX_L2_MEMORIES, l1Quota cap) are NOT recorded here — those
+     * are packaging policy and would not relax under a larger budget.
+     */
+    budgetLimitedPromotionIds: string[];
+}
+export interface TierAssignmentOptions {
+    forceRichTopHit?: boolean;
+}
+/**
+ * Estimate token count for a string using a simple character-based heuristic.
+ * Accurate enough for budget allocation (±20% vs real tokenizer).
+ */
+export declare function estimateTokens(text: string): number;
+/**
+ * Get the content string for a memory at the requested tier.
+ * Falls through to the next available tier if the requested one is empty.
+ */
+export declare function getContentAtTier(memory: SearchResult, tier: ContextTier): string;
+/**
+ * Determine the best tier for a single memory given a remaining budget.
+ * Tries L2 first, falls back to L1, then L0.
+ */
+export declare function selectTierForBudget(memory: SearchResult, remainingBudget: number): TierAssignment;
+/**
+ * Assign tiers to a ranked list of memories under a token budget.
+ *
+ * Compression-and-exclude policy:
+ *   1. Greedy L0-fit: include each memory at L0 only while the L0 sum
+ *      fits the budget. Tail beyond that is dropped (excludedMemoryIds).
+ *   2. Reserve L2 for the top 1-2 included results.
+ *   3. Promote a bounded support slice to L1.
+ *   4. Track budget-driven (not quota-driven) failures to upgrade.
+ */
+export declare function assignTiers(memories: SearchResult[], tokenBudget: number, options?: TierAssignmentOptions): TierBudgetResult;
+/**
+ * Build the tiered injection payload: one entry per assignment, in
+ * assignment order. Driven off `assignments` (not `memories`) so
+ * memories that were excluded during L0-fit do not silently
+ * re-appear at L0. Throws if an assignment references a memory id
+ * not present in `memories` — that signals a caller bug.
+ */
+export declare function buildTieredPayload(memories: SearchResult[], assignments: TierAssignment[]): Array<{
+    id: string;
+    tier: ContextTier;
+    content: string;
+}>;

package/dist/services/tiered-loading.js

@@ -0,0 +1,263 @@
+/**
+ * Tiered Context Loading (L0/L1/L2).
+ *
+ * Three representation tiers for each memory, inspired by OpenViking's
+ * SemanticDagExecutor pattern. Token savings come from injecting the
+ * cheapest tier that preserves enough signal for the model to act on.
+ *
+ *   L0  — Abstract/headline (~10-20 tokens). Stored in `summary`.
+ *   L1  — Condensed overview (~100-200 tokens). Stored in `overview`.
+ *   L2  — Full content (variable). Stored in `content`.
+ *
+ * Tier selection is driven by a token budget: the caller declares how
+ * many tokens are available for context injection, and `assignTiers`
+ * decides the best tier per memory to maximize information within budget.
+ *
+ * Strategy:
+ *   1. Greedy L0-fit: include ranked memories at L0 only while the
+ *      cumulative L0 sum fits the budget; tail that can't fit is excluded.
+ *   2. Within the included set, reserve L2 for the top 1–2 results.
+ *   3. Promote a bounded support slice to L1.
+ *   4. Track which exclusions and demotions were budget-driven (vs
+ *      quota-driven) so callers can surface `meta.budget_constrained`
+ *      truthfully without resorting to heuristics.
+ */
+const TOKENS_PER_CHAR = 0.25;
+const MAX_L2_MEMORIES = 2;
+const L2_BUDGET_SHARE = 0.6;
+const TARGET_L2_SHARE = 0.2;
+const TARGET_L1_SHARE = 0.3;
+/**
+ * Estimate token count for a string using a simple character-based heuristic.
+ * Accurate enough for budget allocation (±20% vs real tokenizer).
+ */
+export function estimateTokens(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length * TOKENS_PER_CHAR);
+}
+/**
+ * Get the content string for a memory at the requested tier.
+ * Falls through to the next available tier if the requested one is empty.
+ */
+export function getContentAtTier(memory, tier) {
+    if (tier === 'L0') {
+        return memory.summary || truncateToHeadline(memory.content);
+    }
+    if (tier === 'L1') {
+        if (memory.overview)
+            return memory.overview;
+        return memory.content;
+    }
+    return memory.content;
+}
+/**
+ * Determine the best tier for a single memory given a remaining budget.
+ * Tries L2 first, falls back to L1, then L0.
+ */
+export function selectTierForBudget(memory, remainingBudget) {
+    const l2Tokens = estimateTokens(memory.content);
+    if (l2Tokens <= remainingBudget) {
+        return { memoryId: memory.id, tier: 'L2', estimatedTokens: l2Tokens };
+    }
+    const l1Content = memory.overview || memory.content;
+    const l1Tokens = estimateTokens(l1Content);
+    if (l1Tokens <= remainingBudget && memory.overview) {
+        return { memoryId: memory.id, tier: 'L1', estimatedTokens: l1Tokens };
+    }
+    const l0Content = memory.summary || truncateToHeadline(memory.content);
+    const l0Tokens = estimateTokens(l0Content);
+    return { memoryId: memory.id, tier: 'L0', estimatedTokens: l0Tokens };
+}
+/**
+ * Assign tiers to a ranked list of memories under a token budget.
+ *
+ * Compression-and-exclude policy:
+ *   1. Greedy L0-fit: include each memory at L0 only while the L0 sum
+ *      fits the budget. Tail beyond that is dropped (excludedMemoryIds).
+ *   2. Reserve L2 for the top 1-2 included results.
+ *   3. Promote a bounded support slice to L1.
+ *   4. Track budget-driven (not quota-driven) failures to upgrade.
+ */
+export function assignTiers(memories, tokenBudget, options = {}) {
+    if (memories.length === 0) {
+        return { assignments: [], totalTokens: 0, budgetUsed: 0, includedMemories: [], excludedMemoryIds: [], budgetLimitedPromotionIds: [] };
+    }
+    const allTierOptions = memories.map(buildTierOptions);
+    const { included, includedTierOptions, excludedMemoryIds } = selectL0Fit(memories, allTierOptions, tokenBudget);
+    if (included.length === 0) {
+        return { assignments: [], totalTokens: 0, budgetUsed: 0, includedMemories: [], excludedMemoryIds, budgetLimitedPromotionIds: [] };
+    }
+    const assignments = includedTierOptions.map(({ L0 }) => ({ ...L0 }));
+    const topSliceCount = getTopSliceCount(included.length);
+    const l1Quota = getL1Quota(included.length, topSliceCount);
+    const budgetLimitedPromotionIds = [];
+    let remaining = tokenBudget - sumTokens(assignments);
+    if (options.forceRichTopHit) {
+        remaining = promoteFirstMemoryToRichContext(assignments, includedTierOptions, remaining, budgetLimitedPromotionIds);
+    }
+    const remainingL2Budget = Math.floor(tokenBudget * L2_BUDGET_SHARE);
+    promoteTopSliceToL2(assignments, includedTierOptions, remaining, remainingL2Budget, topSliceCount, budgetLimitedPromotionIds);
+    remaining = tokenBudget - sumTokens(assignments);
+    promoteSupportingSliceToL1(assignments, includedTierOptions, remaining, topSliceCount, l1Quota, budgetLimitedPromotionIds);
+    const totalTokens = sumTokens(assignments);
+    return {
+        assignments,
+        totalTokens,
+        budgetUsed: totalTokens,
+        includedMemories: included,
+        excludedMemoryIds,
+        budgetLimitedPromotionIds,
+    };
+}
+/**
+ * Tail-exclude L0 selector. Walks input in rank order and includes
+ * each memory while its L0 token cost fits the remaining budget. On
+ * the first overflow it stops and excludes the entire remaining
+ * suffix — preserving semantic priority (drop the least-relevant
+ * tail, never a higher-ranked memory in favor of a smaller
+ * lower-ranked one).
+ */
+function selectL0Fit(memories, allTierOptions, tokenBudget) {
+    const included = [];
+    const includedTierOptions = [];
+    const excludedMemoryIds = [];
+    let used = 0;
+    let overflowed = false;
+    for (let i = 0; i < memories.length; i++) {
+        if (!overflowed) {
+            const l0Cost = allTierOptions[i].L0.estimatedTokens;
+            if (used + l0Cost <= tokenBudget) {
+                included.push(memories[i]);
+                includedTierOptions.push(allTierOptions[i]);
+                used += l0Cost;
+                continue;
+            }
+            overflowed = true;
+        }
+        excludedMemoryIds.push(memories[i].id);
+    }
+    return { included, includedTierOptions, excludedMemoryIds };
+}
+/**
+ * Build the tiered injection payload: one entry per assignment, in
+ * assignment order. Driven off `assignments` (not `memories`) so
+ * memories that were excluded during L0-fit do not silently
+ * re-appear at L0. Throws if an assignment references a memory id
+ * not present in `memories` — that signals a caller bug.
+ */
+export function buildTieredPayload(memories, assignments) {
+    const memoryById = new Map(memories.map((m) => [m.id, m]));
+    return assignments.map((a) => {
+        const memory = memoryById.get(a.memoryId);
+        if (!memory) {
+            throw new Error(`buildTieredPayload: assignment references missing memory id "${a.memoryId}"`);
+        }
+        return {
+            id: a.memoryId,
+            tier: a.tier,
+            content: getContentAtTier(memory, a.tier),
+        };
+    });
+}
+const HEADLINE_MAX_WORDS = 10;
+function truncateToHeadline(content) {
+    const words = content.split(/\s+/);
+    if (words.length <= HEADLINE_MAX_WORDS)
+        return content;
+    return words.slice(0, HEADLINE_MAX_WORDS).join(' ') + '...';
+}
+function buildTierOptions(memory) {
+    return {
+        L0: buildAssignment(memory, 'L0'),
+        L1: buildAssignment(memory, 'L1'),
+        L2: buildAssignment(memory, 'L2'),
+    };
+}
+function buildAssignment(memory, tier) {
+    const content = getContentAtTier(memory, tier);
+    return {
+        memoryId: memory.id,
+        tier,
+        estimatedTokens: estimateTokens(content),
+    };
+}
+/** True iff a larger budget would have allowed `chooseRichTopHit` to upgrade. */
+function richTopHitHasBudgetUpgrade(options, baseline) {
+    return options.L2.estimatedTokens > baseline || options.L1.estimatedTokens > baseline;
+}
+function promoteFirstMemoryToRichContext(assignments, tierOptions, remainingBudget, budgetBlocked) {
+    if (assignments.length === 0)
+        return remainingBudget;
+    const baseline = assignments[0].estimatedTokens;
+    const preferredUpgrade = chooseRichTopHit(tierOptions[0], remainingBudget, baseline);
+    if (!preferredUpgrade) {
+        if (richTopHitHasBudgetUpgrade(tierOptions[0], baseline)) {
+            budgetBlocked.push(assignments[0].memoryId);
+        }
+        return remainingBudget;
+    }
+    assignments[0] = preferredUpgrade;
+    return remainingBudget - (preferredUpgrade.estimatedTokens - tierOptions[0].L0.estimatedTokens);
+}
+function chooseRichTopHit(options, remainingBudget, baselineTokens) {
+    const l2Extra = options.L2.estimatedTokens - baselineTokens;
+    if (l2Extra <= remainingBudget)
+        return options.L2;
+    const l1Extra = options.L1.estimatedTokens - baselineTokens;
+    if (options.L1.estimatedTokens > baselineTokens && l1Extra <= remainingBudget) {
+        return options.L1;
+    }
+    return null;
+}
+function promoteTopSliceToL2(assignments, tierOptions, remainingBudget, remainingL2Budget, topSliceCount, budgetBlocked) {
+    let remaining = remainingBudget;
+    let remainingL2 = remainingL2Budget;
+    for (let index = 0; index < topSliceCount; index++) {
+        const next = tierOptions[index].L2;
+        const extraTokens = next.estimatedTokens - assignments[index].estimatedTokens;
+        if (extraTokens > remaining || extraTokens > remainingL2) {
+            // Both bounds scale with tokenBudget (remainingL2 = floor(budget * L2_BUDGET_SHARE)),
+            // so a larger budget would have permitted the upgrade. Record budget block,
+            // but only if there was an actual upgrade available (extraTokens > 0).
+            if (extraTokens > 0)
+                budgetBlocked.push(assignments[index].memoryId);
+            continue;
+        }
+        assignments[index] = next;
+        remaining -= extraTokens;
+        remainingL2 -= extraTokens;
+    }
+}
+function promoteSupportingSliceToL1(assignments, tierOptions, remainingBudget, topSliceCount, l1Quota, budgetBlocked) {
+    let remaining = remainingBudget;
+    const stopIndex = Math.min(assignments.length, topSliceCount + l1Quota);
+    for (let index = topSliceCount; index < stopIndex; index++) {
+        const next = tierOptions[index].L1;
+        const extraTokens = next.estimatedTokens - assignments[index].estimatedTokens;
+        // No real upgrade (no `overview`, L1 collapses to L0). Not a budget question.
+        if (next.estimatedTokens === assignments[index].estimatedTokens)
+            continue;
+        if (extraTokens > remaining) {
+            budgetBlocked.push(assignments[index].memoryId);
+            continue;
+        }
+        assignments[index] = next;
+        remaining -= extraTokens;
+    }
+}
+function getTopSliceCount(totalMemories) {
+    if (totalMemories === 0)
+        return 0;
+    return Math.min(MAX_L2_MEMORIES, Math.max(1, Math.round(totalMemories * TARGET_L2_SHARE)));
+}
+function getL1Quota(totalMemories, topSliceCount) {
+    const remainingAfterTopSlice = totalMemories - topSliceCount;
+    if (remainingAfterTopSlice <= 1)
+        return Math.max(0, remainingAfterTopSlice);
+    const targetL1Count = Math.max(1, Math.floor(totalMemories * TARGET_L1_SHARE));
+    return Math.min(remainingAfterTopSlice - 1, targetL1Count);
+}
+function sumTokens(assignments) {
+    return assignments.reduce((sum, assignment) => sum + assignment.estimatedTokens, 0);
+}

package/dist/services/timeline-pack.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Timeline-pack formatting — derived retrieval projection.
+ *
+ * Groups memories within a namespace that span multiple distinct dates into
+ * a chronologically-ordered timeline with the latest entry explicitly tagged
+ * [CURRENT]. This gives the answering LLM an unambiguous signal for which
+ * value is most recent, targeting knowledge-update failures where older
+ * values outrank newer ones in flat chronological injection.
+ *
+ * This is a formatting-only transform — same memories in, differently
+ * formatted text out. No changes to ingestion, retrieval, or storage.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+export interface TimelineEntry {
+    memoryId: string;
+    date: string;
+    content: string;
+    isCurrent: boolean;
+}
+export interface TimelinePack {
+    topic: string;
+    entries: TimelineEntry[];
+    latestEntryId: string;
+}
+/** True when memories span at least 2 distinct calendar dates. */
+export declare function spansMultipleDates(memories: SearchResult[]): boolean;
+/**
+ * Build a single timeline pack from memories sharing a namespace.
+ * Memories are sorted chronologically; the most recent gets isCurrent=true.
+ */
+export declare function buildTimelinePack(topic: string, memories: SearchResult[]): TimelinePack;
+/**
+ * Format a timeline pack as injection text.
+ * Each entry is a dash-delimited line; the latest carries a [CURRENT] tag.
+ */
+export declare function formatTimelinePack(pack: TimelinePack): string;

package/dist/services/timeline-pack.js

@@ -0,0 +1,50 @@
+/**
+ * Timeline-pack formatting — derived retrieval projection.
+ *
+ * Groups memories within a namespace that span multiple distinct dates into
+ * a chronologically-ordered timeline with the latest entry explicitly tagged
+ * [CURRENT]. This gives the answering LLM an unambiguous signal for which
+ * value is most recent, targeting knowledge-update failures where older
+ * values outrank newer ones in flat chronological injection.
+ *
+ * This is a formatting-only transform — same memories in, differently
+ * formatted text out. No changes to ingestion, retrieval, or storage.
+ */
+import { isAnswerBearing } from './session-packaging.js';
+/** True when memories span at least 2 distinct calendar dates. */
+export function spansMultipleDates(memories) {
+    const dates = new Set();
+    for (const m of memories) {
+        dates.add(m.created_at.toISOString().slice(0, 10));
+        if (dates.size >= 2)
+            return true;
+    }
+    return false;
+}
+/**
+ * Build a single timeline pack from memories sharing a namespace.
+ * Memories are sorted chronologically; the most recent gets isCurrent=true.
+ */
+export function buildTimelinePack(topic, memories) {
+    const sorted = [...memories].sort((a, b) => a.created_at.getTime() - b.created_at.getTime());
+    const latestEntry = sorted[sorted.length - 1];
+    const entries = sorted.map((m) => ({
+        memoryId: m.id,
+        date: m.created_at.toISOString().slice(0, 10),
+        content: m.content,
+        isCurrent: m.id === latestEntry.id,
+    }));
+    return { topic, entries, latestEntryId: latestEntry.id };
+}
+/**
+ * Format a timeline pack as injection text.
+ * Each entry is a dash-delimited line; the latest carries a [CURRENT] tag.
+ */
+export function formatTimelinePack(pack) {
+    const lines = pack.entries.map((e) => {
+        const kind = isAnswerBearing(e.content) ? 'answer' : 'context';
+        const currentTag = e.isCurrent ? ' [CURRENT]' : '';
+        return `- [${e.date}] [${kind}]${currentTag} ${e.content}`;
+    });
+    return `### Timeline: ${pack.topic}\n${lines.join('\n')}`;
+}

package/dist/services/timing.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Lightweight timing instrumentation for profiling search and ingest paths.
+ * Collects per-operation latencies and reports P50/P95/P99 summaries.
+ */
+export interface TimingEntry {
+    operation: string;
+    durationMs: number;
+    metadata?: Record<string, unknown>;
+}
+/** Time an async operation and record its duration. */
+export declare function timed<T>(operation: string, fn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
+/** Time a sync operation and record its duration. */
+export declare function timedSync<T>(operation: string, fn: () => T, metadata?: Record<string, unknown>): T;

package/dist/services/timing.js

@@ -0,0 +1,72 @@
+/**
+ * Lightweight timing instrumentation for profiling search and ingest paths.
+ * Collects per-operation latencies and reports P50/P95/P99 summaries.
+ */
+const entries = [];
+/** Time an async operation and record its duration. */
+export async function timed(operation, fn, metadata) {
+    const start = performance.now();
+    const result = await fn();
+    const durationMs = performance.now() - start;
+    entries.push({ operation, durationMs, metadata });
+    console.log(`[timing] ${operation}: ${durationMs.toFixed(1)}ms`);
+    return result;
+}
+/** Time a sync operation and record its duration. */
+export function timedSync(operation, fn, metadata) {
+    const start = performance.now();
+    const result = fn();
+    const durationMs = performance.now() - start;
+    entries.push({ operation, durationMs, metadata });
+    console.log(`[timing] ${operation}: ${durationMs.toFixed(1)}ms`);
+    return result;
+}
+/** Get all collected timing entries. */
+function getTimingEntries() {
+    return [...entries];
+}
+/** Clear collected entries. */
+function clearTimingEntries() {
+    entries.length = 0;
+}
+/** Compute percentile from sorted array. */
+function percentile(sorted, p) {
+    if (sorted.length === 0)
+        return 0;
+    const idx = Math.ceil((p / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, idx)];
+}
+/** Generate a summary report of all collected timings, grouped by operation. */
+function getTimingSummary() {
+    const grouped = new Map();
+    for (const entry of entries) {
+        const list = grouped.get(entry.operation) ?? [];
+        list.push(entry.durationMs);
+        grouped.set(entry.operation, list);
+    }
+    const summary = {};
+    for (const [op, durations] of grouped) {
+        const sorted = [...durations].sort((a, b) => a - b);
+        const total = sorted.reduce((a, b) => a + b, 0);
+        summary[op] = {
+            count: sorted.length,
+            p50: percentile(sorted, 50),
+            p95: percentile(sorted, 95),
+            p99: percentile(sorted, 99),
+            mean: total / sorted.length,
+            total,
+        };
+    }
+    return summary;
+}
+/** Print a formatted timing report to console. */
+function printTimingReport() {
+    const summary = getTimingSummary();
+    console.log('\n=== TIMING REPORT ===');
+    console.log('| Operation | Count | P50 | P95 | P99 | Mean | Total |');
+    console.log('|-----------|-------|-----|-----|-----|------|-------|');
+    for (const [op, stats] of Object.entries(summary).sort((a, b) => b[1].total - a[1].total)) {
+        console.log(`| ${op} | ${stats.count} | ${stats.p50.toFixed(1)}ms | ${stats.p95.toFixed(1)}ms | ${stats.p99.toFixed(1)}ms | ${stats.mean.toFixed(1)}ms | ${stats.total.toFixed(0)}ms |`);
+    }
+    console.log();
+}

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

@@ -0,0 +1,20 @@
+/**
+ * TLL chain-membership augmentation for `performSearch`.
+ *
+ * Extracted from `memory-search.ts` to keep that orchestrator focused on
+ * pipeline coordination and to bring the file back under the 400 LOC
+ * project cap. The augmentation runs AFTER `applySearchRelevanceFilter`
+ * (see `appendTllAugmentation`); chain membership is a different
+ * retrieval signal than semantic similarity, so the augmented rows
+ * don't pass through the similarity gate.
+ */
+import type { TraceCollector } from './retrieval-trace.js';
+import type { MemoryServiceDeps } from './memory-service-types.js';
+import type { PostProcessedSearch } from './memory-search-types.js';
+/**
+ * Append TLL chain-membership augmentations after the relevance gate.
+ * The augmented rows ride around the similarity threshold because chain
+ * membership is a structurally different signal — they have no
+ * meaningful similarity score against the query.
+ */
+export declare function appendTllAugmentation(deps: MemoryServiceDeps, userId: string, query: string, postProcessed: PostProcessedSearch, effectiveLimit: number, activeTrace: TraceCollector): Promise<PostProcessedSearch>;

package/dist/services/tll-augmentation.js

@@ -0,0 +1,125 @@
+/**
+ * TLL chain-membership augmentation for `performSearch`.
+ *
+ * Extracted from `memory-search.ts` to keep that orchestrator focused on
+ * pipeline coordination and to bring the file back under the 400 LOC
+ * project cap. The augmentation runs AFTER `applySearchRelevanceFilter`
+ * (see `appendTllAugmentation`); chain membership is a different
+ * retrieval signal than semantic similarity, so the augmented rows
+ * don't pass through the similarity gate.
+ */
+import { normalizeMemoryRow } from '../db/repository-types.js';
+import { shouldUseTLL, expandViaTLL, TLL_ENTITY_LOOKUP_SEED_LIMIT } from './tll-retrieval.js';
+/**
+ * Append TLL chain-membership augmentations after the relevance gate.
+ * The augmented rows ride around the similarity threshold because chain
+ * membership is a structurally different signal — they have no
+ * meaningful similarity score against the query.
+ */
+export async function appendTllAugmentation(deps, userId, query, postProcessed, effectiveLimit, activeTrace) {
+    const result = await maybeExpandViaTLL(deps, userId, query, postProcessed.memories, effectiveLimit);
+    // Surface the fail-open path on the retrieval trace as a distinct
+    // event so the failure is observable in trace artifacts even when no
+    // augmentation rows are produced. Pairs with the structured
+    // `[tll-expansion-failed]` log line emitted by `maybeExpandViaTLL`.
+    if (result.failed) {
+        activeTrace.event('tll_expansion_failed', { errorMessage: result.errorMessage });
+    }
+    if (result.memories.length === 0)
+        return postProcessed;
+    activeTrace.stage('tll-augmentation', [...postProcessed.memories, ...result.memories], {
+        addedCount: result.memories.length,
+        addedIds: result.memories.map((m) => m.id),
+    });
+    return {
+        ...postProcessed,
+        memories: [...postProcessed.memories, ...result.memories],
+    };
+}
+/**
+ * TLL retrieval signal. For ordering/temporal/multi-session queries, expand
+ * the candidate set by traversing entity event chains. Returns hydrated
+ * SearchResult rows tagged with `retrieval_signal: 'tll-chain'` so the
+ * relevance gate can recognize them as non-similarity-scored augmentations.
+ *
+ * Fail-open by design: chain expansion errors never block primary
+ * retrieval. The deliberate fallback is to log the error with a
+ * structured `[tll-expansion-failed]` prefix and surface a
+ * `tll_expansion_failed` event on the retrieval trace so the failure is
+ * observable rather than lost.
+ */
+async function maybeExpandViaTLL(deps, userId, query, memories, effectiveLimit) {
+    if (!deps.tllRepository || memories.length === 0 || !shouldUseTLL(query)) {
+        return { memories: [], failed: false };
+    }
+    try {
+        const initialIds = memories.slice(0, TLL_ENTITY_LOOKUP_SEED_LIMIT).map((m) => m.id);
+        const chainIds = await expandViaTLL(userId, initialIds, deps.tllRepository, deps.stores.pool);
+        const knownIds = new Set(memories.map((m) => m.id));
+        const newIds = chainIds.filter((id) => !knownIds.has(id)).slice(0, effectiveLimit);
+        if (newIds.length === 0)
+            return { memories: [], failed: false };
+        const hydrated = await hydrateChainMemories(deps, userId, newIds);
+        console.log(`[tll-retrieval] expanded ${newIds.length} chain memories for ordering query`);
+        return { memories: hydrated, failed: false };
+    }
+    catch (err) {
+        // Fail-open: TLL is augmentation, never block primary retrieval.
+        // Structured prefix `[tll-expansion-failed]` lets log scrapers
+        // pick this up as a distinct failure class. The retrieval-trace
+        // event is added by the caller (see `appendTllAugmentation`).
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        console.error('[tll-expansion-failed]', errorMessage);
+        return { memories: [], failed: true, errorMessage };
+    }
+}
+/**
+ * Direct SQL hydration into SearchResult shape — bypasses the store
+ * abstraction since this is a deterministic chain-traversal augmentation,
+ * not a similarity search. Selects the full memories row and runs it
+ * through `normalizeMemoryRow` so every required `MemoryRow` field is
+ * present (response formatters call `.toFixed()` on `score`/`similarity`
+ * and read `source_site`/`summary` directly — partial rows crash there).
+ *
+ * Three non-obvious requirements addressed by the SQL + projection shape:
+ *
+ *   1. Order preservation. `expandViaTLL` returns memory IDs in
+ *      chronological observation_date order; a plain `WHERE id = ANY(...)`
+ *      does not preserve input order. Joining against
+ *      `unnest($2::uuid[]) WITH ORDINALITY` and `ORDER BY req.ord`
+ *      keeps the chronology intact through hydration.
+ *
+ *   2. Workspace isolation. `performSearch` is the global retrieval
+ *      path — `postProcessResults` already drops workspace-scoped rows
+ *      before TLL augmentation, but the augmented rows hydrate from a
+ *      separate query and must apply the same filter, otherwise a
+ *      workspace memory chained from a global memory's entity would
+ *      leak into a global response.
+ *
+ *   3. Defensive `relevance: 1.0`. The augmented rows are appended after
+ *      `applySearchRelevanceFilter`, so they don't pass through the
+ *      similarity gate today. But chain-membership rows have no
+ *      meaningful similarity score against the query — `similarity: 0`
+ *      and `score: 0` make them load-bearing on the relevance value if
+ *      any future filter past this point checks `memory.relevance >=
+ *      threshold`. Setting `relevance: 1.0` (the max) locks in the
+ *      bypass invariant against drift; the `retrieval_signal: 'tll-chain'`
+ *      tag remains the canonical way to detect a chain-augmented row.
+ */
+async function hydrateChainMemories(deps, userId, newIds) {
+    const hydratedRes = await deps.stores.pool.query(`SELECT m.*
+     FROM unnest($2::uuid[]) WITH ORDINALITY AS req(id, ord)
+     JOIN memories m ON m.id = req.id
+     WHERE m.user_id = $1
+       AND m.deleted_at IS NULL
+       AND m.status = 'active'
+       AND m.workspace_id IS NULL
+     ORDER BY req.ord`, [userId, newIds]);
+    return hydratedRes.rows.map((row) => ({
+        ...normalizeMemoryRow(row),
+        similarity: 0,
+        score: 0,
+        relevance: 1.0,
+        retrieval_signal: 'tll-chain',
+    }));
+}