osborn 0.9.249 → 0.9.251

package/dist/content/lens-period-render.js

@@ -0,0 +1,70 @@
+/**
+ * lens-period-render.ts — Markdown review output for a period-map run. Pure.
+ * high_leverage is rendered FIRST (strongest content candidates). The caller
+ * redacts the final string again (secrets + client) before writing it.
+ */
+const q = (x) => `  - > "${x.text.replace(/\n+/g, ' ')}" — ${x.speaker}, row #${x.row}, ${x.timestamp}${x.tsCorrected ? ' (ts corrected)' : ''}`;
+const quotes = (xs) => xs.map(q);
+export function renderPeriodMd(r) {
+    const L = [];
+    const b = r.block;
+    L.push(`# Period map — session ${r.sessionId}`, '');
+    L.push(`Model: ${r.model} (context ${r.contextLength.toLocaleString()} tok; block cap 25% = ${r.capTokens.toLocaleString()} tok). Review output only — profile and HWM untouched.`, '');
+    L.push('## Block');
+    if (b) {
+        L.push(`- Basis: ${b.basis}`, `- Rows in block: #${b.firstRowId}–#${b.lastRowId} (${b.periodRows - (b.leftOut?.rows ?? 0)} conversation rows of ${b.periodRows} in the period)`, `- Time: ${b.from} → ${b.to}`, `- Size: ${b.chars.toLocaleString()} chars ≈ ${b.estTokens.toLocaleString()} tokens (est. 4 chars/token)`, b.leftOut
+            ? `- LEFT OUT (over the cap, oldest end): ${b.leftOut.rows} rows #${b.leftOut.firstRowId}–#${b.leftOut.lastRowId} (${b.leftOut.from} → ${b.leftOut.to}, ≈${b.leftOut.estTokens.toLocaleString()} tok)`
+            : '- Left out: nothing (whole period fits the cap)');
+    }
+    else
+        L.push('- (no block)');
+    L.push(`- Raw rows in the block's range (user+assistant, main thread): ${r.rowsRead}; kept after strip/sanitize: ${r.rowsKeptInSession}`);
+    L.push(`- Audio: ${r.audio}`, '');
+    L.push("### Stripped before the block (rows affected, within the block's row range)");
+    const kinds = Object.entries(r.stripped).sort((a, b2) => b2[1] - a[1]);
+    L.push(...(kinds.length ? kinds.map(([k, n]) => `- ${k}: ${n}`) : ['- none']), '');
+    L.push('## Cost', `- Calls: ${r.calls}; tokens ${r.promptTokens.toLocaleString()} in + ${r.completionTokens.toLocaleString()} out; $${r.costUsd.toFixed(4)} (cap $${r.capUsd.toFixed(2)}); finish=${r.finish || '-'}; provider=${r.provider || '-'}`, '');
+    if (r.errors.length)
+        L.push('## Errors', ...r.errors.map(e => `- ${e}`), '');
+    const m = r.map;
+    if (!m)
+        return L.join('\n') + '\n';
+    L.push('## High-leverage work (ranked)');
+    if (!m.highLeverage.length)
+        L.push('- (none verified)');
+    m.highLeverage.forEach((h, i) => L.push(`${i + 1}. **${h.title}** [${h.evidence}] — ${h.why}`, ...quotes(h.quotes)));
+    L.push('', '## Period goal');
+    if (m.periodGoal)
+        L.push(m.periodGoal.text, ...quotes(m.periodGoal.quotes));
+    else
+        L.push('- (none verified)');
+    L.push('', '## Arc');
+    m.arc.forEach((s, i) => L.push(`${i + 1}. [${s.step}] ${s.what}${s.why ? ` — ${s.why}` : ''}`, ...quotes(s.quotes)));
+    L.push('', '## What worked', '### Held up');
+    for (const w of m.whatWorked.heldUp)
+        L.push(`- **${w.name}** (${w.kind || '-'}) — ${w.why}`, ...quotes(w.quotes));
+    L.push('### Did not');
+    for (const w of m.whatWorked.didnt)
+        L.push(`- **${w.name}** (${w.kind || '-'}) — ${w.why}`, ...quotes(w.quotes));
+    L.push('', '## Stories');
+    for (const s of m.stories) {
+        L.push(`### ${s.title}`, `Why it matters: ${s.whyItMatters}`, `Rows: #${s.from}–#${s.to}`);
+        for (const tp of s.turningPoints)
+            L.push(`- Turning point: ${tp.moment}`, ...tp.userLines.map(x => '  ' + q(x)));
+        L.push('');
+    }
+    L.push('## Angles');
+    for (const a of m.angles)
+        L.push(`- **${a.title}** — demand question: ${a.demandQuestion}${a.story ? ` (story: ${a.story})` : ''}`, ...quotes(a.quotes));
+    L.push('', '## Anchors (row ranges per story)');
+    for (const a of m.anchors) {
+        const audio = a.audio ? `; audio ${a.audio.start ?? '?'}–${a.audio.end ?? '?'}${a.audio.approximate ? ' (approx.)' : ''}` : '';
+        L.push(`- ${a.story}: rows #${a.from}–#${a.to} (${a.rows} conversation rows, ${a.fromTs} → ${a.toTs}${audio})`);
+    }
+    L.push('', `## Quote verification`, `- Verified quotes kept: ${m.quotesKept}; quotes dropped: ${m.drops.length}; items dropped: ${m.itemsDropped.length}`);
+    for (const d of m.drops)
+        L.push(`- DROP [${d.section}] ${d.item} — row ${d.row || '?'}: "${d.text}" → ${d.reason}`);
+    for (const it of m.itemsDropped)
+        L.push(`- ITEM DROPPED ${it}`);
+    return L.join('\n') + '\n';
+}

package/dist/content/lens-period.d.ts

@@ -0,0 +1,106 @@
+/**
+ * lens-period.ts — the PERIOD MAP: one model call over one raw block
+ * (lens-period-block.ts) → what this stretch of work was, as a map.
+ *
+ * Sections: high_leverage (ranked first), period_goal, arc, what_worked,
+ * stories (with the user's own verbatim lines at the turning points), angles
+ * (each with the demand question it answers) and anchors (row ranges per story,
+ * for a later clip/library step).
+ *
+ * Every quote is verified DETERMINISTICALLY with lens-quotes against the block's
+ * rows; the speaker/row/timestamp written out are the matched row's. A failing
+ * quote is dropped (and logged with the reason); an item left with no verified
+ * quote is dropped. Story lines must be the user's own words (not pasted text).
+ */
+import { type DbRecord } from './lens-db.js';
+import { type Quote } from './lens-quotes.js';
+import { type RecordingAlignment } from './lens-audio.js';
+export type LeverageEvidence = 'shipped' | 'root-caused' | 'decided';
+export interface HighLeverage {
+    title: string;
+    why: string;
+    evidence: LeverageEvidence;
+    quotes: Quote[];
+}
+export interface ArcStep {
+    step: string;
+    what: string;
+    why: string;
+    quotes: Quote[];
+}
+export interface WorkedItem {
+    name: string;
+    kind: string;
+    why: string;
+    quotes: Quote[];
+}
+export interface TurningPoint {
+    moment: string;
+    userLines: Quote[];
+}
+export interface Story {
+    title: string;
+    whyItMatters: string;
+    turningPoints: TurningPoint[];
+    from: number;
+    to: number;
+}
+export interface Angle {
+    title: string;
+    demandQuestion: string;
+    story: string;
+    quotes: Quote[];
+}
+export interface Anchor {
+    story: string;
+    from: number;
+    to: number;
+    rows: number;
+    fromTs: string;
+    toTs: string;
+    /** Only when an AudioAdapter (lens-audio.ts) found a recording; transcript-only runs keep row ranges. */
+    audio?: {
+        path: string;
+        start: string | null;
+        end: string | null;
+        approximate: boolean;
+    };
+}
+export interface QuoteDrop {
+    section: string;
+    item: string;
+    text: string;
+    row: string;
+    reason: string;
+}
+export interface PeriodMap {
+    highLeverage: HighLeverage[];
+    periodGoal: {
+        text: string;
+        quotes: Quote[];
+    } | null;
+    arc: ArcStep[];
+    whatWorked: {
+        heldUp: WorkedItem[];
+        didnt: WorkedItem[];
+    };
+    stories: Story[];
+    angles: Angle[];
+    anchors: Anchor[];
+    drops: QuoteDrop[];
+    quotesKept: number;
+    itemsDropped: string[];
+}
+/** Transcript FIRST, instructions AFTER (measured on minimax-m3: the task gets lost otherwise). */
+export declare function periodPrompt(blockText: string, meta: {
+    from: string;
+    to: string;
+    rows: number;
+}): string;
+export declare function normalizeLeverage(v: unknown): LeverageEvidence | '';
+/** Parse + verify the model's map against the block rows. Null when the JSON is unusable. */
+export declare function readPeriodMap(raw: string, records: DbRecord[]): PeriodMap | null;
+/** Optional audio step: attach clip offsets to anchors when a recording alignment exists; no-op otherwise. */
+export declare function attachAudio(map: PeriodMap, align: RecordingAlignment | null): PeriodMap;
+/** Plain-text view of the block for debugging/tests. */
+export declare const blockView: (records: DbRecord[]) => string;

package/dist/content/lens-period.js

@@ -0,0 +1,205 @@
+/**
+ * lens-period.ts — the PERIOD MAP: one model call over one raw block
+ * (lens-period-block.ts) → what this stretch of work was, as a map.
+ *
+ * Sections: high_leverage (ranked first), period_goal, arc, what_worked,
+ * stories (with the user's own verbatim lines at the turning points), angles
+ * (each with the demand question it answers) and anchors (row ranges per story,
+ * for a later clip/library step).
+ *
+ * Every quote is verified DETERMINISTICALLY with lens-quotes against the block's
+ * rows; the speaker/row/timestamp written out are the matched row's. A failing
+ * quote is dropped (and logged with the reason); an item left with no verified
+ * quote is dropped. Story lines must be the user's own words (not pasted text).
+ */
+import { recordView } from './lens-db.js';
+import { buildRecordIndex, explainQuote, parseJsonObject, verifyQuote } from './lens-quotes.js';
+import { isPastedSpan } from './lens-clip-arc.js';
+import { clipOffset } from './lens-audio.js';
+const QUOTE_RULES = 'QUOTES: every "quotes"/"user_lines" entry = {"row": the record\'s row number from its [#row | timestamp | speaker] header ' +
+    '(digits only), "text": an exact verbatim substring (12-300 chars) copied character-for-character from THAT ONE record}. ' +
+    'ONE contiguous span: no ellipses, no skipped words, no merged sentences, no typo or grammar fixes — the person speaks by ' +
+    'voice, keep their disfluencies exactly. Never quote secrets, keys, tokens, emails, or personal details; keep masked tags ' +
+    'like [client] exactly as written.';
+const SHAPE = '{"high_leverage": [{"title", "why": one line — why it is high-leverage, "evidence": "shipped"|"root-caused"|"decided", "quotes": [1-3]}],\n' +
+    ' "period_goal": {"text": 1-2 sentences, "quotes": [1-3]},\n' +
+    ' "arc": [{"step": "tried"|"failed"|"pivot"|"worked"|"outcome", "what": one line, "why": one line (why it failed / why it worked / what changed), "quotes": [1-2]}],\n' +
+    ' "what_worked": {"held_up": [{"name", "kind": "tool"|"model"|"approach", "why", "quotes": [1-2]}], "didnt": [same shape]},\n' +
+    ' "stories": [{"title", "why_it_matters": one line, "from_row": first row of the story, "to_row": last row, ' +
+    '"turning_points": [{"moment": one line, "user_lines": [1-2 USER quotes]}]}],\n' +
+    ' "angles": [{"title", "demand_question": the question a real person is asking that this would answer, "story": story title or "", "quotes": [1-2]}]}';
+/** Transcript FIRST, instructions AFTER (measured on minimax-m3: the task gets lost otherwise). */
+export function periodPrompt(blockText, meta) {
+    return [
+        `Below is ONE raw, unedited, chronological stretch (${meta.rows} records, ${meta.from} to ${meta.to}) of a long voice work ` +
+            'session between a person (user) and their AI coding assistant (assistant). Conversation only — tool calls are not shown. ' +
+            'Read all of it, beginning to end; your task follows after the transcript.',
+        '<transcript>',
+        blockText,
+        '</transcript>',
+        'TASK: map this whole period. Do not summarise record by record — understand what the stretch of work was about and how ' +
+            'it unfolded, then fill every section:\n' +
+            '- high_leverage (0-6, strongest first): the high-value work of the period — something that unblocked a lot, saved real ' +
+            'money or time, a fix that took a whole class of problems off the table, a reusable technique others could use, or a ' +
+            'decision that changed direction. "evidence": shipped (built and shown working), root-caused (cause found/proven), ' +
+            'decided (a direction-changing decision the person made).\n' +
+            '- period_goal: what this stretch of work was about overall.\n' +
+            '- arc (4-12 steps, in order): what was tried, what failed and why, the pivots, what finally worked, and the outcome.\n' +
+            '- what_worked: tools, models and approaches that held up, and ones that did not (with why).\n' +
+            '- stories (1-6): self-contained sub-stories inside the period. Each with a title, why it matters, its row range, and the ' +
+            'PERSON\'s own verbatim lines (user records, their spoken words — not pasted logs/reviews) at the turning points.\n' +
+            '- angles (1-6): postable angles, each with the demand question it would answer.\n' +
+            'Keep masked tags like [client]; never reintroduce client names, IDs or amounts. No personal invoicing/money-owed items.',
+        QUOTE_RULES,
+        `Output ONLY one JSON object: ${SHAPE}`,
+    ].join('\n\n');
+}
+const str = (v) => (typeof v === 'string' ? v.trim() : typeof v === 'number' ? String(v) : '');
+const arr = (v) => (Array.isArray(v) ? v : []);
+export function normalizeLeverage(v) {
+    const s = str(v).toLowerCase().replace(/[\s_]+/g, '-');
+    if (s === 'shipped' || s === 'verified' || s === 'done')
+        return 'shipped';
+    if (s === 'root-caused' || s === 'root-cause' || s === 'rootcaused')
+        return 'root-caused';
+    if (s === 'decided' || s === 'decision')
+        return 'decided';
+    return '';
+}
+class Verifier {
+    idx;
+    byId;
+    ids;
+    drops = [];
+    kept = 0;
+    constructor(records) {
+        this.idx = buildRecordIndex(records);
+        this.byId = new Map(records.map(r => [r.id, r]));
+        this.ids = records.map(r => r.id);
+    }
+    /** Timestamp of the cited row (or the nearest row id) so lens-quotes can verify by row + time. */
+    tsFor(row) {
+        const r = this.byId.get(row);
+        if (r)
+            return r.timestamp;
+        let best = this.ids[0];
+        for (const id of this.ids)
+            if (Math.abs(id - row) < Math.abs(best - row))
+                best = id;
+        return this.byId.get(best)?.timestamp ?? '';
+    }
+    quotes(raw, section, item, max, userOnly = false) {
+        const out = [];
+        const seen = new Set();
+        for (const q of arr(raw).slice(0, max)) {
+            const row = Number(str(q?.row).replace(/^#/, ''));
+            const cand = { text: q?.text, row, timestamp: Number.isFinite(row) ? this.tsFor(row) : '' };
+            const v = verifyQuote(cand, this.idx);
+            const drop = (reason) => this.drops.push({ section, item, text: str(q?.text).slice(0, 160), row: str(q?.row), reason });
+            if (!v) {
+                drop(explainQuote(cand, this.idx));
+                continue;
+            }
+            if (userOnly && (v.speaker !== 'user' || isPastedSpan(this.byId.get(v.row)?.text ?? '', v.text))) {
+                drop(v.speaker !== 'user' ? 'not a user line' : 'pasted text, not the user\'s own words');
+                continue;
+            }
+            const key = `${v.row}:${v.text}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(v);
+        }
+        this.kept += out.length;
+        return out;
+    }
+}
+/** Parse + verify the model's map against the block rows. Null when the JSON is unusable. */
+export function readPeriodMap(raw, records) {
+    const o = parseJsonObject(raw);
+    if (!o)
+        return null;
+    const V = new Verifier(records);
+    const itemsDropped = [];
+    const keep = (section, label, it) => {
+        if (it.quotes.length)
+            return it;
+        itemsDropped.push(`${section}: ${label}`);
+        return null;
+    };
+    const hl = arr(o.high_leverage).slice(0, 6).map(h => {
+        const title = str(h?.title);
+        const evidence = normalizeLeverage(h?.evidence);
+        if (!title)
+            return null;
+        if (!evidence) {
+            itemsDropped.push(`high_leverage: ${title} (evidence "${str(h?.evidence)}" not shipped/root-caused/decided)`);
+            return null;
+        }
+        return keep('high_leverage', title, { title, why: str(h?.why), evidence, quotes: V.quotes(h?.quotes, 'high_leverage', title, 3) });
+    });
+    const pg = o.period_goal;
+    const goalText = str(pg?.text) || str(pg);
+    const goal = goalText ? keep('period_goal', 'goal', { text: goalText, quotes: V.quotes(pg?.quotes, 'period_goal', 'goal', 3) }) : null;
+    const arc = arr(o.arc).slice(0, 14).map((s, i) => {
+        const what = str(s?.what);
+        if (!what)
+            return null;
+        return keep('arc', `${i + 1}. ${what}`, { step: str(s?.step) || 'step', what, why: str(s?.why), quotes: V.quotes(s?.quotes, 'arc', what, 2) });
+    });
+    const worked = (v, sec) => arr(v).slice(0, 8).map(w => {
+        const name = str(w?.name);
+        if (!name)
+            return null;
+        return keep(sec, name, { name, kind: str(w?.kind), why: str(w?.why), quotes: V.quotes(w?.quotes, sec, name, 2) });
+    }).filter((x) => !!x);
+    const ww = (o.what_worked ?? {});
+    const blockFirst = records[0]?.id ?? 0;
+    const blockLast = records[records.length - 1]?.id ?? 0;
+    const clamp = (n) => Math.min(blockLast, Math.max(blockFirst, n));
+    const stories = [];
+    for (const s of arr(o.stories).slice(0, 6)) {
+        const title = str(s?.title);
+        if (!title)
+            continue;
+        const tps = arr(s?.turning_points).slice(0, 5).map(tp => ({ moment: str(tp?.moment), userLines: V.quotes(tp?.user_lines, 'stories', title, 2, true) }))
+            .filter(tp => tp.userLines.length);
+        if (!tps.length) {
+            itemsDropped.push(`stories: ${title} (no verified user line)`);
+            continue;
+        }
+        const rows = tps.flatMap(tp => tp.userLines.map(q => q.row));
+        const f = Number(str(s?.from_row).replace(/^#/, ''));
+        const t = Number(str(s?.to_row).replace(/^#/, ''));
+        // Anchor range = the model's range clamped to the block, always covering every verified line.
+        const from = Math.min(Number.isFinite(f) && f > 0 ? clamp(f) : Infinity, ...rows);
+        const to = Math.max(Number.isFinite(t) && t > 0 ? clamp(t) : -Infinity, ...rows);
+        stories.push({ title, whyItMatters: str(s?.why_it_matters), turningPoints: tps, from, to });
+    }
+    const angles = arr(o.angles).slice(0, 6).map(a => {
+        const title = str(a?.title);
+        if (!title)
+            return null;
+        return keep('angles', title, { title, demandQuestion: str(a?.demand_question), story: str(a?.story), quotes: V.quotes(a?.quotes, 'angles', title, 2) });
+    });
+    const anchors = stories.map(s => {
+        const inRange = records.filter(r => r.id >= s.from && r.id <= s.to);
+        return { story: s.title, from: s.from, to: s.to, rows: inRange.length, fromTs: inRange[0]?.timestamp ?? '', toTs: inRange[inRange.length - 1]?.timestamp ?? '' };
+    });
+    const nn = (xs) => xs.filter((x) => !!x);
+    return {
+        highLeverage: nn(hl), periodGoal: goal, arc: nn(arc), whatWorked: { heldUp: worked(ww.held_up, 'what_worked.held_up'), didnt: worked(ww.didnt, 'what_worked.didnt') },
+        stories, angles: nn(angles), anchors, drops: V.drops, quotesKept: V.kept, itemsDropped,
+    };
+}
+/** Optional audio step: attach clip offsets to anchors when a recording alignment exists; no-op otherwise. */
+export function attachAudio(map, align) {
+    if (!align)
+        return map;
+    for (const a of map.anchors) {
+        a.audio = { path: align.path, start: a.fromTs ? clipOffset(a.fromTs, align.startIso) : null, end: a.toTs ? clipOffset(a.toTs, align.startIso) : null, approximate: align.approximate };
+    }
+    return map;
+}
+/** Plain-text view of the block for debugging/tests. */
+export const blockView = (records) => records.map(recordView).join('\n\n');

package/dist/content/lens-profile.d.ts

@@ -0,0 +1,47 @@
+/**
+ * lens-profile.ts — format + APPEND (never rewrite) the per-project
+ * content-profile.md entry, and the worker's small redacted error log.
+ */
+import type { Evidence, Quote } from './lens-quotes.js';
+import type { GapEvidence } from './lens-hn.js';
+import { type RecordingAlignment } from './lens-audio.js';
+export interface FinalAngle {
+    title: string;
+    why: string;
+    quotes: Quote[];
+    gap: GapEvidence;
+}
+export interface FinalCapability {
+    name: string;
+    did: string;
+    evidence: Evidence;
+    proof: string;
+    quotes: Quote[];
+}
+export interface EntryMeta {
+    sessionId: string;
+    source: 'recall-db';
+    mode: 'incremental' | 'backfill';
+    model: string;
+    records: number;
+    rowRange: [number, number];
+    windows: number;
+    windowsTotal: number;
+    modelCalls: number;
+    costUsd: number;
+    dropped: {
+        angles: number;
+        capabilities: number;
+    };
+    notDone: number;
+    billingDropped?: number;
+    /** True when no client denylist was loaded: header carries a review warning. */
+    noDenylist?: boolean;
+    recording: RecordingAlignment | null;
+}
+export declare function formatEntry(angles: FinalAngle[], caps: FinalCapability[], meta: EntryMeta): string;
+export declare function appendProfile(projectDir: string, entry: string): string;
+/** Scratch output (sample runs): overwrite a single file, never the profile. */
+export declare function writeScratch(path: string, entry: string): string;
+/** Small redacted log line in the project dir; truncated when it grows past 256 KB. */
+export declare function logLine(projectDir: string | null, msg: string): void;

package/dist/content/lens-profile.js

@@ -0,0 +1,95 @@
+/**
+ * lens-profile.ts — format + APPEND (never rewrite) the per-project
+ * content-profile.md entry, and the worker's small redacted error log.
+ */
+import { appendFileSync, existsSync, mkdirSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { redactSecrets } from './transcript-sanitizer.js';
+import { clipOffset } from './lens-audio.js';
+import { LOG_FILE, PROFILE_FILE } from './lens-paths.js';
+const PROFILE_HEADER = '# Content Profile\n\nAppend-only. Postable angles + demonstrated capabilities auto-extracted at each compaction ' +
+    '(disable with OSBORN_CONTENT_LENS=0). Every quote below was verified verbatim against the sanitized session ' +
+    'recall store (session.db row #, timestamp); capabilities are tagged shipped | root-caused. Review before posting.\n';
+const oneLine = (s) => s.replace(/\s+/g, ' ').trim();
+function quoteLines(quotes, rec, indent = '  ') {
+    return quotes.map(q => {
+        const clip = rec ? clipOffset(q.timestamp, rec.startIso) : null;
+        const clipTxt = clip ? ` · clip @${clip}${rec.approximate ? ' (approx)' : ''}` : '';
+        return `${indent}- > "${oneLine(q.text)}" — *${q.speaker}*, \`${q.timestamp}\` (row #${q.row})${clipTxt}`;
+    });
+}
+export function formatEntry(angles, caps, meta) {
+    const L = [];
+    L.push(`\n## ${new Date().toISOString()} — session ${meta.sessionId.substring(0, 8)}`);
+    L.push(`_source: ${meta.source} (${meta.mode}) · rows #${meta.rowRange[0]}–#${meta.rowRange[1]} · ${meta.records} conversation rows · ` +
+        `${meta.windows}/${meta.windowsTotal} window(s) · ${meta.model} · ${meta.modelCalls} call(s) · $${meta.costUsd.toFixed(4)} · ` +
+        `dropped by grounding check: ${meta.dropped.angles} angle(s), ${meta.dropped.capabilities} capability(ies) · ` +
+        `dropped as not-done (plan/speculation): ${meta.notDone}` +
+        `${meta.billingDropped !== undefined ? ` · dropped by finance-topic filter: ${meta.billingDropped}` : ''}_`);
+    if (meta.noDenylist) {
+        L.push('_WARNING: no client denylist was loaded — only shape-based redaction (emails, ids, amounts, legal-suffix company names) was applied. Check for client names before posting._');
+    }
+    if (meta.recording) {
+        const r = meta.recording;
+        L.push(`_recording: \`${r.path}\` · clip offsets relative to ${r.startIso} (${r.basis}` +
+            `${r.approximate ? '; alignment APPROXIMATE' : ''})_`);
+    }
+    L.push('');
+    if (angles.length) {
+        L.push('### Angles', '');
+        for (const a of angles) {
+            L.push(`#### ${oneLine(a.title)}`);
+            if (a.why)
+                L.push(`- **Why postable:** ${oneLine(a.why)}`);
+            L.push('- **Verified quotes:**', ...quoteLines(a.quotes, meta.recording));
+            L.push(`- **Gap evidence** (HN: ${a.gap.queries.map(q => `\`${q}\``).join(', ') || 'none'}):`);
+            for (const s of a.gap.stories) {
+                L.push(`  - [${oneLine(s.title)}](${s.url}) — ${s.points} pts, ${s.num_comments} comments`);
+            }
+            L.push(`  - ${a.gap.note}`, '');
+        }
+    }
+    if (caps.length) {
+        L.push('### Capabilities', '');
+        for (const c of caps) {
+            L.push(`- **${oneLine(c.name)}** \`[${c.evidence}]\` — ${oneLine(c.did)}`);
+            if (c.proof)
+                L.push(`    - _proof:_ ${oneLine(c.proof)}`);
+            L.push(...quoteLines(c.quotes, meta.recording, '    '));
+        }
+        L.push('');
+    }
+    // Defense in depth: everything is redacted (incl. high-entropy) before disk.
+    return redactSecrets(L.join('\n'), { assistant: true });
+}
+export function appendProfile(projectDir, entry) {
+    const path = join(projectDir, PROFILE_FILE);
+    mkdirSync(projectDir, { recursive: true });
+    if (!existsSync(path))
+        appendFileSync(path, PROFILE_HEADER, 'utf-8');
+    appendFileSync(path, entry, 'utf-8');
+    return path;
+}
+/** Scratch output (sample runs): overwrite a single file, never the profile. */
+export function writeScratch(path, entry) {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, PROFILE_HEADER.replace('# Content Profile', '# Content Lens — scratch sample') + entry, 'utf-8');
+    return path;
+}
+const LOG_MAX_BYTES = 256 * 1024;
+/** Small redacted log line in the project dir; truncated when it grows past 256 KB. */
+export function logLine(projectDir, msg) {
+    if (!projectDir)
+        return;
+    try {
+        const p = join(projectDir, LOG_FILE);
+        const line = `${new Date().toISOString()} ${redactSecrets(oneLine(msg), { assistant: true }).slice(0, 2000)}\n`;
+        if (existsSync(p) && statSync(p).size > LOG_MAX_BYTES)
+            writeFileSync(p, line, 'utf-8');
+        else
+            appendFileSync(p, line, 'utf-8');
+    }
+    catch {
+        /* never throw from logging */
+    }
+}

package/dist/content/lens-quotes.d.ts

@@ -0,0 +1,103 @@
+/**
+ * lens-quotes.ts — the DETERMINISTIC anti-hallucination guard (no model).
+ *
+ * Every quote the model returns must be an exact (whitespace-normalized)
+ * substring of a sanitized session.db conversation row carrying the SAME
+ * timestamp (rows the model actually saw). Items (angles or capabilities) with
+ * any unverifiable quote are dropped wholesale. The speaker and row id written
+ * to disk are taken from the matched row, never from the model.
+ */
+export interface Quote {
+    text: string;
+    timestamp: string;
+    speaker: 'user' | 'assistant';
+    /** session.db content.id of the row the quote was verified against. */
+    row: number;
+    /** The model cited a slightly wrong timestamp; `timestamp` is the source row's. */
+    tsCorrected?: boolean;
+}
+/** Anything row-shaped: DbRecord from lens-db.ts (id = content.id). */
+export interface QuotableRecord {
+    id?: number;
+    text: string;
+    timestamp: string;
+    speaker: 'user' | 'assistant';
+}
+export declare const normalizeWs: (s: string) => string;
+export type RecordIndex = Map<string, string[]>;
+type IndexEntry = {
+    text: string;
+    loose: string;
+    speaker: Quote['speaker'];
+    row: number;
+    ts: string;
+    ms: number;
+};
+/**
+ * Formatting-only normalization applied identically to quote AND row: markdown
+ * emphasis/code marks, typographic quotes/ellipsis, whitespace, letter case. Words, digits and
+ * punctuation that carry meaning are untouched, so this is still a substring check.
+ */
+export declare const looseText: (s: string) => string;
+/** A cited timestamp may slip (neighbouring row, one digit); beyond this it's a different moment. */
+export declare const TS_TOLERANCE_MS: number;
+/** timestamp → rows carrying it (normalized + loose text, row id, parsed time). */
+export declare function buildRecordIndex(records: QuotableRecord[]): Map<string, IndexEntry[]>;
+export type QuoteIndex = ReturnType<typeof buildRecordIndex>;
+/**
+ * Verified quote or null. Pure + deterministic. The quote text must be a
+ * substring (whitespace/markdown-normalized) of a SOURCE row. Exact timestamp
+ * match is preferred; otherwise the nearest row containing the text is accepted
+ * only if the cited timestamp is within TS_TOLERANCE_MS, or the cited row id is
+ * that row. The timestamp, speaker and row written out are ALWAYS the source
+ * row's, never the model's (tsCorrected marks a fixed citation).
+ */
+export declare function verifyQuote(q: {
+    text?: unknown;
+    timestamp?: unknown;
+    row?: unknown;
+}, idx: QuoteIndex): Quote | null;
+/** Why a quote failed (debug only; same rules as verifyQuote). */
+export declare function explainQuote(q: {
+    text?: unknown;
+    timestamp?: unknown;
+    row?: unknown;
+}, idx: QuoteIndex): string;
+/**
+ * Keep items whose quotes ALL verify (1..maxQuotes required). Returns the kept
+ * items with verified quotes substituted, plus the drop count.
+ */
+export declare function verifyItems<T extends {
+    quotes: unknown[];
+}>(items: T[], idx: QuoteIndex, maxQuotes?: number): {
+    kept: (Omit<T, 'quotes'> & {
+        quotes: Quote[];
+    })[];
+    dropped: number;
+};
+/** Tolerant JSON-object parse: accepts fences or leading prose. */
+export declare function parseJsonObject(raw: string): Record<string, unknown> | null;
+export interface RawAngle {
+    title: string;
+    why: string;
+    quotes: unknown[];
+    queries: string[];
+}
+export type Evidence = 'shipped' | 'root-caused';
+export interface RawCapability {
+    name: string;
+    did: string;
+    /** Normalized evidence type; '' when the model gave none / something else (= not done). */
+    evidence: Evidence | '';
+    proof: string;
+    quotes: unknown[];
+}
+/** Done-vs-planned gate: only shipped/verified or proven-root-cause items count. */
+export declare function normalizeEvidence(v: unknown): Evidence | '';
+export declare function splitByEvidence(caps: RawCapability[]): {
+    done: RawCapability[];
+    notDone: number;
+};
+export declare function readAngles(v: unknown, max: number): RawAngle[];
+export declare function readCapabilities(v: unknown, max: number): RawCapability[];
+export {};