peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/context/memory-preflight-config.js

@@ -0,0 +1,25 @@
+const DEFAULTS = Object.freeze({
+    enabled: true,
+    maxTokens: 1200,
+    listCap: 12,
+    contentCacheBytes: 6000,
+});
+const LIST_CAP_MIN = 1;
+const LIST_CAP_MAX = 50;
+function asFiniteInt(value, fallback) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0
+        ? Math.trunc(value)
+        : fallback;
+}
+export function resolveMemoryPreflightConfig(prefs) {
+    const m = prefs.memoryPreflight ?? {};
+    const listCapRaw = asFiniteInt(m.listCap, DEFAULTS.listCap);
+    return {
+        enabled: m.enabled === false ? false : DEFAULTS.enabled,
+        maxTokens: m.maxTokens && m.maxTokens > 0 ? m.maxTokens : DEFAULTS.maxTokens,
+        listCap: Math.min(LIST_CAP_MAX, Math.max(LIST_CAP_MIN, listCapRaw)),
+        contentCacheBytes: m.contentCacheBytes && m.contentCacheBytes > 0
+            ? m.contentCacheBytes
+            : DEFAULTS.contentCacheBytes,
+    };
+}

package/dist/services/context/memory-preflight-service.d.ts

@@ -0,0 +1,19 @@
+import { type MemoryPreflightPrefsInput } from './memory-preflight-config.js';
+export interface MemoryPreflightResult {
+    available: boolean;
+    block?: string;
+    feedbackListItems?: number;
+    cachedItemCount?: number;
+    reason?: string;
+    truncated?: boolean | undefined;
+    droppedCount?: number | undefined;
+}
+export declare class MemoryPreflightService {
+    private readonly reader;
+    private readonly config;
+    /** path -> body; sub-agent-requested memo contents (Task 4 deviation, see module header). */
+    private readonly cachedMemoContents;
+    constructor(projectRoot: string, prefs: MemoryPreflightPrefsInput);
+    cacheMemoContent(path: string, content: string): void;
+    fetchBlock(_taskTitle: string): Promise<MemoryPreflightResult>;
+}

package/dist/services/context/memory-preflight-service.js

@@ -0,0 +1,120 @@
+/**
+ * MemoryPreflightService — orchestrator-facing API for the
+ * "Orchestrator Memory Preflight" slice (see
+ * docs/superpowers/specs/2026-07-22-orchestrator-memory-preflight-design.md).
+ *
+ * Consumes:
+ *   - resolveMemoryPreflightConfig (Task 1) — merged defaults + per-project overlay
+ *   - MemoryIndexReader (Task 3)            — reads .peaks/memory/index.json + layer=A filter
+ *   - MemoryLruCache (Task 2)               — constructed for capacity parity, but NOT used
+ *                                            for memo content (see deviation note below)
+ *   - compressPrompt (existing)             — headroom-ai wrapper for hard-cap compression
+ *
+ * Deviation from brief — controller-accepted (pre-task 4):
+ *   The brief mandated use of `MemoryLruCache` for memo content caching. The
+ *   orchestrator dispatch flow only ever has at most a handful of explicit
+ *   `cacheMemoContent` calls per task (typically 0-3), and ordering / explicit
+ *   invalidation is preferred over LRU eviction by recency. To keep the
+ *   semantic obvious and the byte budget check trivial, this implementation
+ *   uses a plain `Map<path, body>` for memo path -> body content. The
+ *   `MemoryLruCache` class remains as a separate, reusable LRU primitive
+ *   (Task 2) and is not consumed by this service.
+ */
+import { compressPrompt } from './headroom-client.js';
+import { MemoryIndexReader } from './memory-index-reader.js';
+import { resolveMemoryPreflightConfig, } from './memory-preflight-config.js';
+async function compressToCap(text, capBytes, mode) {
+    try {
+        const result = await compressPrompt(text, mode);
+        if (result.warning !== null || result.compressedPrompt === null) {
+            return { text, truncated: false };
+        }
+        const compressed = result.compressedPrompt;
+        if (Buffer.byteLength(compressed, 'utf8') > capBytes) {
+            const sliced = compressed.slice(0, Math.max(0, capBytes - 64)) + '\n…[truncated]';
+            return { text: sliced, truncated: true };
+        }
+        return { text: compressed, truncated: false };
+    }
+    catch {
+        return { text, truncated: false };
+    }
+}
+export class MemoryPreflightService {
+    reader;
+    config;
+    /** path -> body; sub-agent-requested memo contents (Task 4 deviation, see module header). */
+    cachedMemoContents = new Map();
+    constructor(projectRoot, prefs) {
+        this.config = resolveMemoryPreflightConfig(prefs);
+        this.reader = new MemoryIndexReader(projectRoot);
+    }
+    cacheMemoContent(path, content) {
+        if (!this.config.enabled)
+            return;
+        const bytes = Buffer.byteLength(content, 'utf8');
+        if (bytes > this.config.contentCacheBytes) {
+            // too big to ever fit; do not cache.
+            return;
+        }
+        this.cachedMemoContents.set(path, content);
+    }
+    async fetchBlock(_taskTitle) {
+        if (!this.config.enabled)
+            return { available: false, reason: 'DISABLED' };
+        const selected = this.reader.selectFeedbackLayerA(this.config.listCap);
+        if (selected.length === 0) {
+            const any = this.reader.loadIfStale();
+            if (any.length === 0)
+                return { available: false, reason: 'MEMORY_INDEX_MISSING' };
+            return { available: false, reason: 'NO_FEEDBACK_LAYER_A' };
+        }
+        const listLines = selected
+            .map((e) => `- * ${e.name}\n    Path: ${e.sourcePath}\n    One-line: ${summarize(e.description)}`)
+            .join('\n');
+        let tail = '\n';
+        let cachedCount = 0;
+        if (this.cachedMemoContents.size > 0) {
+            const sections = [];
+            for (const [path, body] of this.cachedMemoContents) {
+                sections.push(`### ${path}\n\n${body}`);
+                cachedCount += 1;
+            }
+            tail = `\n\n## Requested memory details:\n${sections.join('\n\n')}\n`;
+        }
+        const header = '## Project memory relevant to this task\n';
+        const composed = `${header}${listLines}${tail}`;
+        const capBytes = Math.max(64, this.config.maxTokens * 4);
+        const { text, truncated } = await compressToCap(composed, capBytes, 'balanced');
+        const droppedCount = truncated ? selected.length - countItemsInBlock(text) : 0;
+        return {
+            available: true,
+            block: text,
+            feedbackListItems: selected.length,
+            cachedItemCount: cachedCount,
+            truncated,
+            droppedCount: droppedCount > 0 ? droppedCount : undefined,
+        };
+    }
+}
+function summarize(description) {
+    // Drop the <!-- peaks-feedback-promoted: layer=A --> marker, take the next 1 line.
+    const cleaned = description.replace(/<!--[^>]*-->/g, '').trim();
+    return cleaned.split('\n')[0] ?? cleaned;
+}
+function countItemsInBlock(text) {
+    // Count `- * ` markers ONLY in the list portion (between the
+    // `## Project memory relevant to this task` header and the
+    // `## Requested memory details:` sub-section, if present). Memo
+    // bodies appended under `## Requested memory details:` may
+    // legitimately contain their own `- * ` markdown bullets, which
+    // would otherwise inflate the count and produce a wrong
+    // `droppedCount` in the truncated case.
+    const headerEnd = text.indexOf('\n## ');
+    if (headerEnd === -1) {
+        return (text.match(/- \* /g) ?? []).length;
+    }
+    const tailStart = text.indexOf('\n## Requested memory details:', headerEnd + 1);
+    const listEnd = tailStart === -1 ? text.length : tailStart;
+    return (text.slice(0, listEnd).match(/- \* /g) ?? []).length;
+}

package/dist/services/context/renderer.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per spec §4.1 Step 4 — Renderer.
+ *
+ * Audience-scoped view: peaks-rd sees goal + docs + memory;
+ * peaks-qa sees test files + coverage + (later) mut-report;
+ * peaks-mut sees test files + source under test only.
+ *
+ * Hard constraint: budget truncation must be explicit, never silent.
+ */
+import type { Audience, CollectorOutput, DocRetrieverOutput, RendererOutput, TokenizerOutput } from './types.js';
+export interface RenderInput {
+    readonly goal: string;
+    readonly audience: Audience;
+    readonly docBudgetTokens: number;
+    readonly collector: CollectorOutput;
+    readonly docRetriever: DocRetrieverOutput;
+    readonly tokenizer: TokenizerOutput;
+    readonly now?: () => Date;
+}
+export declare function render(input: RenderInput): RendererOutput;

package/dist/services/context/renderer.js

@@ -0,0 +1,30 @@
+function pickDocsForAudience(audience, docs) {
+    if (audience === 'peaks-mut') {
+        // peaks-mut does NOT see docs — its job is purely test quality.
+        return [];
+    }
+    return docs;
+}
+export function render(input) {
+    const now = input.now ?? (() => new Date());
+    const docs = pickDocsForAudience(input.audience, input.docRetriever.fetchedDocs);
+    // Estimate size: rough heuristic — bytes = chars.
+    // v1 serializes to a single string to compute sizeBytes.
+    const serialized = JSON.stringify({
+        goal: input.goal,
+        audience: input.audience,
+        docs: docs.map((d) => ({ dep: d.dep, version: d.version, excerpt: d.sections.map((s) => s.excerpt).join(' ') })),
+        skipped: input.docRetriever.skipped,
+    });
+    const sizeBytes = Buffer.byteLength(serialized, 'utf8');
+    const approxTokens = Math.ceil(sizeBytes / 4);
+    const truncated = approxTokens > input.docBudgetTokens;
+    const result = {
+        audience: input.audience,
+        renderedAt: now().toISOString(),
+        sizeBytes,
+        truncated,
+        ...(truncated ? { truncatedReason: 'doc_budget_exceeded' } : {}),
+    };
+    return Object.freeze(result);
+}

package/dist/services/context/spillover-store.d.ts

@@ -0,0 +1,23 @@
+import type { SpillId, SpillOptions, SpillRecord, SpillState } from './spillover-types.js';
+/**
+ * Defense-in-depth: assert the given path is NOT a symbolic link.
+ *
+ * Symlinks pointing outside the spill directory could be used to bypass
+ * the containment check (assertInside). This function uses lstat (which
+ * does NOT follow symlinks) to detect symbolic links and reject them.
+ *
+ * Note: this check is redundant with the entry.isFile() check in
+ * listSpills() (which rejects symlinks on most platforms), but
+ * provides belt-and-suspenders defense for the writeRecord and
+ * hydrate entry points.
+ */
+export declare function assertNotSymlink(path: string): void;
+export declare function spillDir(projectRoot: string, sessionId: string): string;
+export declare function spillPath(projectRoot: string, sessionId: string, spillId: SpillId): string;
+export declare function createSpillId(now?: Date): SpillId;
+export declare function spill(options: SpillOptions, payload: Readonly<Record<string, unknown>>): SpillRecord;
+export declare function hydrate(projectRoot: string, sessionId: string, spillId: SpillId): SpillRecord | null;
+export declare function listSpills(projectRoot: string, sessionId: string, options?: {
+    readonly state?: SpillState;
+}): readonly SpillRecord[];
+export declare function pruneExpiredSpills(projectRoot: string, sessionId: string): readonly string[];

package/dist/services/context/spillover-store.js

@@ -0,0 +1,155 @@
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { isAbsolute, join, relative } from 'node:path';
+import { SPILL_TTL_MS } from './spillover-types.js';
+const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/;
+function assertSafeSegment(value, name) {
+    if (!SAFE_SEGMENT.test(value) || value === '.' || value === '..') {
+        throw new Error(`${name} must be a safe path segment`);
+    }
+}
+function assertInside(base, target) {
+    const rel = relative(base, target);
+    if (rel === '..' || rel.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`) || isAbsolute(rel)) {
+        throw new Error('Spill path must stay inside the session spill directory');
+    }
+}
+/**
+ * Defense-in-depth: assert the given path is NOT a symbolic link.
+ *
+ * Symlinks pointing outside the spill directory could be used to bypass
+ * the containment check (assertInside). This function uses lstat (which
+ * does NOT follow symlinks) to detect symbolic links and reject them.
+ *
+ * Note: this check is redundant with the entry.isFile() check in
+ * listSpills() (which rejects symlinks on most platforms), but
+ * provides belt-and-suspenders defense for the writeRecord and
+ * hydrate entry points.
+ */
+export function assertNotSymlink(path) {
+    if (!existsSync(path))
+        return; // file doesn't exist yet (writeRecord) or already gone (hydrate)
+    const st = lstatSync(path);
+    if (st.isSymbolicLink()) {
+        throw new Error(`Refusing to operate on symbolic link: ${path}`);
+    }
+}
+export function spillDir(projectRoot, sessionId) {
+    assertSafeSegment(sessionId, 'sessionId');
+    return join(projectRoot, '.peaks', '_runtime', sessionId, 'spill');
+}
+export function spillPath(projectRoot, sessionId, spillId) {
+    assertSafeSegment(spillId, 'spillId');
+    const dir = spillDir(projectRoot, sessionId);
+    const path = join(dir, `${spillId}.json`);
+    assertInside(dir, path);
+    return path;
+}
+export function createSpillId(now = new Date()) {
+    const date = now.toISOString().slice(0, 10);
+    const timestamp = now.getTime().toString(36);
+    return `spill-${date}-${timestamp}-${randomUUID().slice(0, 8)}`;
+}
+function writeRecord(path, record) {
+    assertNotSymlink(path);
+    const content = JSON.stringify(record, null, 2);
+    const temporaryPath = `${path}.${randomUUID()}.tmp`;
+    writeFileSync(temporaryPath, content, 'utf8');
+    try {
+        renameSync(temporaryPath, path);
+    }
+    catch {
+        writeFileSync(path, content, 'utf8');
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // Best-effort cleanup after the direct-write fallback.
+        }
+    }
+}
+export function spill(options, payload) {
+    const record = {
+        spillId: createSpillId(),
+        sessionId: options.sessionId,
+        projectRoot: options.projectRoot,
+        createdAt: new Date().toISOString(),
+        state: 'pending',
+        payload,
+        ...(options.batchId === undefined ? {} : { batchId: options.batchId })
+    };
+    mkdirSync(spillDir(options.projectRoot, options.sessionId), { recursive: true });
+    writeRecord(spillPath(options.projectRoot, options.sessionId, record.spillId), record);
+    return record;
+}
+function readRecord(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+export function hydrate(projectRoot, sessionId, spillId) {
+    const path = spillPath(projectRoot, sessionId, spillId);
+    if (!existsSync(path))
+        return null;
+    try {
+        assertNotSymlink(path);
+        const record = readRecord(path);
+        if (record === null)
+            return null;
+        const hydrated = {
+            ...record,
+            state: 'hydrated',
+            hydratedAt: new Date().toISOString()
+        };
+        writeRecord(path, hydrated);
+        return hydrated;
+    }
+    catch {
+        return null;
+    }
+}
+export function listSpills(projectRoot, sessionId, options) {
+    const dir = spillDir(projectRoot, sessionId);
+    if (!existsSync(dir))
+        return [];
+    const now = Date.now();
+    const records = readdirSync(dir, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith('.json'))
+        .map((entry) => readRecord(join(dir, entry.name)))
+        .filter((record) => record !== null)
+        .map((record) => {
+        const age = now - new Date(record.createdAt).getTime();
+        return age > SPILL_TTL_MS && record.state === 'pending'
+            ? { ...record, state: 'expired' }
+            : record;
+    })
+        .filter((record) => options?.state === undefined || record.state === options.state);
+    records.sort((left, right) => left.createdAt.localeCompare(right.createdAt));
+    return records;
+}
+export function pruneExpiredSpills(projectRoot, sessionId) {
+    const dir = spillDir(projectRoot, sessionId);
+    if (!existsSync(dir))
+        return [];
+    const now = Date.now();
+    const removed = [];
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.json'))
+            continue;
+        const path = join(dir, entry.name);
+        const record = readRecord(path);
+        if (record === null || now - new Date(record.createdAt).getTime() <= SPILL_TTL_MS)
+            continue;
+        try {
+            unlinkSync(path);
+            removed.push(path);
+        }
+        catch {
+            // Best-effort pruning leaves failed paths for a later attempt.
+        }
+    }
+    return removed;
+}

package/dist/services/context/spillover-types.d.ts

@@ -0,0 +1,18 @@
+export type SpillId = string;
+export type SpillState = 'pending' | 'hydrated' | 'expired';
+export interface SpillRecord {
+    readonly spillId: SpillId;
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    readonly createdAt: string;
+    readonly state: SpillState;
+    readonly payload: Readonly<Record<string, unknown>>;
+    readonly batchId?: string;
+    readonly hydratedAt?: string;
+}
+export interface SpillOptions {
+    readonly sessionId: string;
+    readonly projectRoot: string;
+    readonly batchId?: string;
+}
+export declare const SPILL_TTL_MS: number;

package/dist/services/context/spillover-types.js

@@ -0,0 +1 @@
+export const SPILL_TTL_MS = 24 * 60 * 60 * 1000;

package/dist/services/context/threshold.d.ts

@@ -0,0 +1,35 @@
+/**
+ * G9.3 — forced compression gate threshold constants + tier evaluation.
+ *
+ * 256K default context capacity is a conservative proxy. The LLM's real
+ * capacity is its private business (R-1 / R-8 / R-10 / R-13 boundary
+ * inherited from slice #009); we use prompt size as the gate signal.
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`
+ * for the full G9 rule (RL-27..RL-32, AC-50..AC-65).
+ */
+export declare const CONTEXT_CAPACITY_DEFAULT_BYTES: number;
+export declare const THRESHOLD_SOFT_WARN_RATIO = 0.5;
+export declare const THRESHOLD_NEAR_LIMIT_RATIO = 0.75;
+export declare const THRESHOLD_HARD_REJECT_RATIO = 0.8;
+export declare const THRESHOLD_EMERGENCY_RATIO = 0.9;
+export type ThresholdTier = 'ok' | 'soft-warn' | 'near-limit' | 'hard-reject' | 'emergency';
+export interface ThresholdEvaluation {
+    readonly tier: ThresholdTier;
+    readonly ratio: number;
+    readonly bytesUsed: number;
+    readonly capacityBytes: number;
+    readonly warnings: readonly string[];
+}
+/**
+ * Compute the threshold tier for a given prompt size. Pure function
+ * (no IO, no side effects). The `capacityBytes` parameter lets callers
+ * override the default 256K proxy (e.g. for testing or for a future
+ * per-IDE capacity override).
+ */
+export declare function evaluateThresholdTier(promptSize: number, capacityBytes?: number): ThresholdEvaluation;
+/**
+ * Convert a threshold tier to a machine-readable code suitable for the
+ * CLI envelope's `code` field. Used by both the CLI and the hook layer.
+ */
+export declare function tierToCode(tier: ThresholdTier): string;

package/dist/services/context/threshold.js

@@ -0,0 +1,76 @@
+/**
+ * G9.3 — forced compression gate threshold constants + tier evaluation.
+ *
+ * 256K default context capacity is a conservative proxy. The LLM's real
+ * capacity is its private business (R-1 / R-8 / R-10 / R-13 boundary
+ * inherited from slice #009); we use prompt size as the gate signal.
+ *
+ * See: `.peaks/memory/sub-agent-headroom-forced-compression-gate.md`
+ * for the full G9 rule (RL-27..RL-32, AC-50..AC-65).
+ */
+export const CONTEXT_CAPACITY_DEFAULT_BYTES = 256 * 1024; // 256K
+export const THRESHOLD_SOFT_WARN_RATIO = 0.5; // 50%
+export const THRESHOLD_NEAR_LIMIT_RATIO = 0.75; // 75% — user red line
+export const THRESHOLD_HARD_REJECT_RATIO = 0.80; // 80%
+export const THRESHOLD_EMERGENCY_RATIO = 0.90; // 90%
+/**
+ * Compute the threshold tier for a given prompt size. Pure function
+ * (no IO, no side effects). The `capacityBytes` parameter lets callers
+ * override the default 256K proxy (e.g. for testing or for a future
+ * per-IDE capacity override).
+ */
+export function evaluateThresholdTier(promptSize, capacityBytes = CONTEXT_CAPACITY_DEFAULT_BYTES) {
+    if (!Number.isFinite(promptSize) || promptSize < 0) {
+        throw new Error(`evaluateThresholdTier: promptSize must be ≥ 0 (got ${promptSize})`);
+    }
+    if (!Number.isFinite(capacityBytes) || capacityBytes <= 0) {
+        throw new Error(`evaluateThresholdTier: capacityBytes must be > 0 (got ${capacityBytes})`);
+    }
+    const ratio = promptSize / capacityBytes;
+    const warnings = [];
+    let tier;
+    if (ratio >= THRESHOLD_EMERGENCY_RATIO) {
+        tier = 'emergency';
+        warnings.push('PROMPT_EMERGENCY');
+    }
+    else if (ratio >= THRESHOLD_HARD_REJECT_RATIO) {
+        tier = 'hard-reject';
+        warnings.push('PROMPT_TOO_LARGE');
+    }
+    else if (ratio >= THRESHOLD_NEAR_LIMIT_RATIO) {
+        tier = 'near-limit';
+        warnings.push('CONTEXT_NEAR_LIMIT');
+    }
+    else if (ratio >= THRESHOLD_SOFT_WARN_RATIO) {
+        tier = 'soft-warn';
+        warnings.push('CONTEXT_SOFT_WARN');
+    }
+    else {
+        tier = 'ok';
+    }
+    return {
+        tier,
+        ratio,
+        bytesUsed: promptSize,
+        capacityBytes,
+        warnings
+    };
+}
+/**
+ * Convert a threshold tier to a machine-readable code suitable for the
+ * CLI envelope's `code` field. Used by both the CLI and the hook layer.
+ */
+export function tierToCode(tier) {
+    switch (tier) {
+        case 'ok':
+            return 'OK';
+        case 'soft-warn':
+            return 'CONTEXT_SOFT_WARN';
+        case 'near-limit':
+            return 'CONTEXT_NEAR_LIMIT';
+        case 'hard-reject':
+            return 'PROMPT_TOO_LARGE';
+        case 'emergency':
+            return 'PROMPT_EMERGENCY';
+    }
+}

package/dist/services/context/tokenizer.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Per spec §4.1 Step 3 — Tokenizer (non-mutating).
+ *
+ * Hard constraint H3: structured metadata > bare strings. Each collector
+ * artifact and each fetched doc gets a tokenized metadata record so
+ * peaks-rd/qa can do relative-anomaly detection later.
+ *
+ * Immutability H (common/coding-style): the output is frozen so callers
+ * cannot mutate it. Use spread to derive new outputs in future slices.
+ */
+import type { CollectorOutput, DocRetrieverOutput, TokenizerOutput } from './types.js';
+export declare function tokenize(collector: CollectorOutput, docRetriever: DocRetrieverOutput, now?: Date): TokenizerOutput;

package/dist/services/context/tokenizer.js

@@ -0,0 +1,43 @@
+function freshDecayScore(fetchedAt, now) {
+    const ageMs = now.getTime() - new Date(fetchedAt).getTime();
+    const ageDays = ageMs / (1000 * 60 * 60 * 24);
+    // Linear decay: 1.0 at day 0, 0.5 at day 30, 0.0 at day 60+
+    if (ageDays >= 60)
+        return 0;
+    return Math.max(0, 1 - ageDays / 60);
+}
+export function tokenize(collector, docRetriever, now = new Date()) {
+    const metadata = [];
+    for (const doc of docRetriever.fetchedDocs) {
+        metadata.push({
+            id: `doc:${doc.dep}@${doc.version}`,
+            kind: 'doc',
+            version: doc.version,
+            blastRadius: doc.sections.map((s) => s.title),
+            conflictScore: 0, // v1: no cross-source conflict detection yet
+            timeDecayScore: freshDecayScore(doc.fetchedAt, now),
+            tags: ['fetched', doc.source, doc.stale ? 'stale' : 'fresh'],
+        });
+    }
+    for (const mem of collector.memoryEntries) {
+        metadata.push({
+            id: `memory:${mem.path}`,
+            kind: 'memory',
+            blastRadius: [mem.title],
+            conflictScore: 0,
+            timeDecayScore: mem.relevanceScore,
+            tags: ['memory'],
+        });
+    }
+    for (const file of collector.files) {
+        metadata.push({
+            id: `code:${file.path}`,
+            kind: 'code',
+            blastRadius: [file.path],
+            conflictScore: 0,
+            timeDecayScore: 1,
+            tags: [file.kind],
+        });
+    }
+    return Object.freeze({ metadata: Object.freeze(metadata) });
+}