@signal4/s4 2.6.1 → 2.8.0

package/dist/format.js

@@ -6,6 +6,7 @@
  * any port. Canonical tokens, truncation markers, and footers all live
  * here — do not invent per-tool vocabulary in handlers.
  */
+import { hint as surfaceHint, getSurface } from "./surface.js";
 const PUBLIC_URL = "https://api.signal4.ca";
 // ---------------------------------------------------------------------------
 // Political lean — single canonical bucket table (spec §5), shared with the
@@ -99,6 +100,65 @@ export function confToken(confidence) {
         return "conf:unverified";
     return `conf:${Math.round(confidence * 100)}%`;
 }
+// ---------------------------------------------------------------------------
+// Speaker attribution
+// ---------------------------------------------------------------------------
+/**
+ * How a speaker renders, gated on the episode's host/guest roster (core#559).
+ *
+ * There are four states, and a consumer must be able to tell them apart:
+ *
+ *   corroborated  **Glenn Beck**                    — the roster backs the name
+ *   unconfirmed   **Unconfirmed — possibly Glenn Beck**  — roster exists, name absent
+ *   unchecked     **Unconfirmed — possibly Glenn Beck**  — no roster to check against
+ *   no identity   **Unresolved speaker**            — a distinct voice, no name
+ *
+ * The hedge word leads so that a skim reads it. Putting the name first and the
+ * caveat in a token loses the caveat: an LLM consumer summarising the result
+ * writes "Glenn Beck said X" either way.
+ *
+ * The two hedged tiers deliberately share a label and differ in their token.
+ * They are the same instruction to the reader ("do not cite this name") for
+ * two different reasons, and the reason is machine-readable where it belongs.
+ *
+ * Fails closed: a backend that emits `identity_id` without `attribution` (any
+ * build older than core#559) is treated as `unchecked`. A stale deploy must not
+ * be able to turn assertions back on.
+ */
+export function speakerAttribution(spk) {
+    const s = spk ?? {};
+    const id = s.identity_id;
+    const name = s.name ?? s.primary_name;
+    if (id == null) {
+        // No identity — a diarization cluster. Any name string sitting here is a
+        // placeholder ("Unknown", "SPEAKER_01"), never something to print as a
+        // speaker: nothing links it to a person we can name.
+        return {
+            label: "Unresolved speaker",
+            tokens: ["speaker:unresolved (diarization cluster)"],
+            hedged: false,
+        };
+    }
+    const shown = name ?? `Speaker ${id}`;
+    const attribution = s.attribution ?? "unchecked";
+    if (attribution === "corroborated") {
+        const by = s.corroborated_by ? ` (${s.corroborated_by})` : "";
+        return { label: shown, tokens: [`speaker:${id}`, `attribution:corroborated${by}`], hedged: false };
+    }
+    return {
+        label: `Unconfirmed — possibly ${shown}`,
+        tokens: [`speaker:${id}`, `attribution:${attribution}`],
+        hedged: true,
+    };
+}
+/** Footer shown whenever a result set contains a hedged speaker name.
+ *  Without it, "Unconfirmed — possibly X" is a label with no defined meaning. */
+export const ATTRIBUTION_NOTE = "\n\n_Speaker names: `attribution:corroborated` = the identity is on that " +
+    "episode's host/guest list — safe to cite. `unconfirmed` = the episode has a " +
+    "host/guest list and this name is not on it. `unchecked` = no list exists for " +
+    "that episode. Do not cite an Unconfirmed name as the speaker; check it with " +
+    "`get_episode` (returns hosts/guests) or `get_segment_sentences`. `confidence` " +
+    "is not calibrated and is not a substitute for this._";
 /** `trend:surging (+340%)` / `trend:new` / `trend:steady (n/a)` (spec §5). */
 export function trendToken(direction, changePct) {
     if (direction === "new")
@@ -143,7 +203,7 @@ export function truncateWithPointer(text, pointer, maxlen = QUOTE_BUDGET) {
     const cut = clean.slice(0, maxlen);
     const last = cut.lastIndexOf(" ");
     const body = last > maxlen * 0.5 ? cut.slice(0, last) : cut;
-    return `${body}…[truncated — full text: ${pointer}]`;
+    return `${body}…[truncated — full text: ${surfaceHint(pointer)}]`;
 }
 /** Rewrite LLM `{seg_N}` / `{{seg_N}}` citations to the spec token `seg:N`. */
 export function rewriteSegCitations(text) {
@@ -157,10 +217,10 @@ export function rewriteSegCitations(text) {
 /** `showing 20 of 249 — offset:20 for more` (spec §7.2). */
 export function pagingNote(opts) {
     if (opts.countCapped) {
-        return `\nshowing ${opts.shown} of ${opts.total ?? "n/a"} (count_capped — true total unknown) — offset:${(opts.offset ?? 0) + opts.shown} for more`;
+        return surfaceHint(`\nshowing ${opts.shown} of ${opts.total ?? "n/a"} (count_capped — true total unknown) — offset:${(opts.offset ?? 0) + opts.shown} for more`);
     }
     if (opts.total != null && opts.total > opts.shown + (opts.offset ?? 0)) {
-        return `\nshowing ${opts.shown} of ${opts.total} — offset:${(opts.offset ?? 0) + opts.shown} for more`;
+        return surfaceHint(`\nshowing ${opts.shown} of ${opts.total} — offset:${(opts.offset ?? 0) + opts.shown} for more`);
     }
     return "";
 }
@@ -169,7 +229,7 @@ export function nextCallHint(...calls) {
     const real = calls.filter((c) => !!c);
     if (!real.length)
         return "";
-    return `\n→ ${real.join(" · ")}`;
+    return surfaceHint(`\n→ ${real.join(" · ")}`);
 }
 /** Assemble body + footers in spec order. */
 function withFooters(body, footer, paging, hint) {
@@ -225,6 +285,11 @@ function clipLine(contentType, url) {
 // ---------------------------------------------------------------------------
 // Empty state
 // ---------------------------------------------------------------------------
+/** An empty page past the end of a list that had results: not "no matches" (signal4#329). */
+export function pastEndMessage(offset, noun, depthNote = "") {
+    return `No more ${noun} past offset ${offset.toLocaleString("en-US")}: the list ends before it. `
+        + `Earlier pages (offset 0 up) hold the matches${depthNote ? `; ${depthNote}` : ""}.`;
+}
 export function emptyStateSuggestions(params) {
     const suggestions = [];
     if (params.fullHistory) {
@@ -233,7 +298,11 @@ export function emptyStateSuggestions(params) {
             suggestions.push("Verify the speaker name with find_speakers");
     }
     else {
-        if (params.days && params.days < 30)
+        // A caller who named their own dates does not want to hear about `days` —
+        // suggesting it implies we ignored the dates they passed (#554).
+        if (params.explicitRange)
+            suggestions.push("Try an earlier start_date, or full_history=true with a topic + speaker filter for the whole archive");
+        else if (params.days && params.days < 30)
             suggestions.push("Try a wider window: days=30");
         else if (params.days && params.days < 90)
             suggestions.push("Try a wider window: days=90");
@@ -250,8 +319,13 @@ export function emptyStateSuggestions(params) {
     let msg = `No matching content for "${query}"`;
     if (params.channel_name)
         msg += ` on channel "${params.channel_name}"`;
+    // Say the window we actually searched. "in the last 30 days" printed under a
+    // query that passed start_date=2025-01-01 is a lie about the search, and the
+    // one that made a client re-run correct searches (#554).
     if (params.fullHistory)
         msg += ` in the full corpus history`;
+    else if (params.explicitRange && params.startDate)
+        msg += ` between ${params.startDate} and ${params.endDate ?? "today"}`;
     else if (params.days)
         msg += ` in the last ${params.days} days`;
     msg += ".";
@@ -262,49 +336,86 @@ export function emptyStateSuggestions(params) {
 // ---------------------------------------------------------------------------
 // Quotes
 // ---------------------------------------------------------------------------
+/** Quote excerpt budget in the compact search view. */
+export const SEARCH_QUOTE_BUDGET = 300;
+/** Real total if the API gave one; null/undefined means "unknown" and is never printed as a count. */
+export function realTotal(data) {
+    return typeof data.total_results === "number" ? data.total_results : null;
+}
+/** `Showing 10 of 249 · sim ≥0.35 · more: --offset 10` — honest about unknown totals. */
+export function resultsHeader(opts) {
+    const more = opts.hasMore ?? (opts.total != null && opts.total > opts.offset + opts.consumed);
+    const range = opts.offset > 0 ? `${opts.offset + 1}–${opts.offset + opts.consumed}` : `${opts.shown}`;
+    const parts = [`Showing ${range}${opts.total != null ? ` of ${opts.total.toLocaleString("en-US")}` : ""}${opts.noun ? ` ${opts.noun}` : ""}`];
+    if (opts.minSimilarity != null)
+        parts.push(`sim ≥${opts.minSimilarity}`);
+    if (more)
+        parts.push(surfaceHint(`more: offset:${opts.offset + opts.consumed}`));
+    else if (opts.depthReached)
+        parts.push(depthNote(opts.rankedDepth));
+    return parts.join(" · ");
+}
+/** A ranked search served its last page: more matches exist past it, but no deeper page. */
+export function depthNote(rankedDepth) {
+    const at = rankedDepth ? ` at rank ${rankedDepth.toLocaleString("en-US")}` : "";
+    return `ranked results end${at}; mode:keyword or count_mentions group_by:episode list every match`;
+}
+/** One paging line for list tools: "showing 21–40 of 312 · next: offset:40".
+ * `param` names the offset parameter (observations_offset on get_claim). Empty when the
+ * whole list fits on the first page. (signal4#329) */
+export function pageLine(opts) {
+    const param = opts.param ?? "offset";
+    if (!opts.hasMore && opts.offset === 0)
+        return "";
+    const range = opts.shown ? `${opts.offset + 1}–${opts.offset + opts.shown}` : `none past ${opts.offset}`;
+    const of = opts.total != null ? ` of ${opts.total.toLocaleString("en-US")}` : "";
+    const noun = opts.noun ? ` ${opts.noun}` : "";
+    const tail = opts.hasMore ? ` · next: ${param}:${opts.offset + opts.shown}`
+        : opts.depthNote ? ` · ${opts.depthNote}` : " · last page";
+    return surfaceHint(`\nshowing ${range}${of}${noun}${tail}`);
+}
 export function formatQuotes(data, footer = "", offset = 0) {
     const quotes = dedupQuotes(data.quotes ?? []);
     if (!quotes.length)
-        return "No quotes found matching your search criteria." + footer;
-    const total = data.total_results ?? quotes.length;
-    const ms = data.processing_time_ms ?? 0;
-    const lines = [`**${total} results** (showing ${quotes.length}, ${ms.toFixed(0)}ms)\n`];
+        return (offset > 0 ? pastEndMessage(offset, "quotes") : "No quotes found matching your search criteria.") + footer;
+    const lines = [resultsHeader({
+            shown: quotes.length, total: realTotal(data), offset, consumed: (data.quotes ?? []).length,
+            hasMore: data.has_more, minSimilarity: data.min_similarity,
+            depthReached: data.depth_reached, rankedDepth: data.ranked_depth,
+        }) + "\n"];
+    // Set when any quote renders a hedged name, so the footer explaining what
+    // "Unconfirmed — possibly X" means appears only where it is needed.
+    let anyHedged = false;
     for (let i = 0; i < quotes.length; i++) {
         const q = quotes[i];
         const spk = q.speaker ?? {};
-        const resolved = spk.identity_id != null;
-        const spkName = resolved ? (spk.name ?? `Speaker ${spk.identity_id}`) : "Unresolved speaker";
-        const spkToken = resolved ? `speaker:${spk.identity_id}` : "speaker:unresolved (diarization cluster)";
+        const attr = speakerAttribution(spk);
+        if (attr.hedged)
+            anyHedged = true;
         const sim = q.similarity;
         const date = fmtDate(q.episode_date ?? q.publish_date);
         const segId = q.segment_id;
         const tStart = q.timestamp_start ?? q.start_time;
-        const tEnd = q.timestamp_end ?? q.end_time;
-        const tokens = [spkToken, confToken(spk.confidence)];
+        const tokens = [...attr.tokens, confToken(spk.confidence)];
         if (spk.appearance_type)
             tokens.push(`appearance:${spk.appearance_type}`);
         if (sim != null)
             tokens.push(`sim:${sim.toFixed(2)}`);
         tokens.push(`date:${date}`);
         if (tStart != null)
-            tokens.push(fmtTimeRange(tStart, tEnd));
+            tokens.push(`@${fmtTime(tStart)}`);
         const lt = langToken(q.language);
         if (lt)
             tokens.push(lt);
-        if (q.channel_id != null)
-            tokens.push(`channel_id:${q.channel_id}`);
         tokens.push(`channel:${q.channel_name ?? "n/a"}`);
-        lines.push(`${i + 1}. **${spkName}** — ${tokens.join(" ")}`);
+        lines.push(`${i + 1}. **${attr.label}** — ${tokens.join(" ")}`);
         lines.push(`   seg:${segId ?? "n/a"} episode:${q.content_id ?? "n/a"}`);
-        const clip = clipUrl(q.content_id, tStart ?? undefined, tEnd ?? undefined, q.clip_url);
-        lines.push(`   ${clipLine(q.content_type, clip)}`);
         const pointer = segId != null ? `get_segment seg:${segId}` : undefined;
-        lines.push(`   > ${truncateWithPointer(q.text, pointer)}\n`);
+        lines.push(`   > ${truncateWithPointer(q.text, pointer, SEARCH_QUOTE_BUDGET)}\n`);
     }
     const first = quotes[0];
     const hint = nextCallHint(first?.segment_id != null ? `get_segment seg:${first.segment_id}` : undefined, first?.speaker?.identity_id != null ? `get_speaker speaker_id:${first.speaker.identity_id}` : undefined);
-    const paging = pagingNote({ shown: quotes.length, total, offset, countCapped: data.count_capped });
-    return withFooters(lines.join("\n"), footer, paging, hint);
+    return withFooters(lines.join("\n"), footer, "", hint) + (anyHedged ? ATTRIBUTION_NOTE : "");
 }
 // ---------------------------------------------------------------------------
 // Claims
@@ -357,15 +468,42 @@ export function speakerResolutionNote(data) {
         return "";
     return "Note: speaker name did not resolve to a known speaker — 0 results may mean an unrecognized/variant spelling (ASR may render names phonetically), not that the speaker never said this. Try find_speakers to locate the canonical name.\n\n";
 }
+/** "12,345" or "100,000+" for a capped count. */
+function countLabel(n, capped) {
+    return `${n.toLocaleString("en-US")}${capped ? "+" : ""}`;
+}
+/** What an entity name matched: the label, the other names folded in, how it was found. */
+export function entityMatchLine(m) {
+    const parts = [`entity:${m.entity_id} "${m.name}"`];
+    if (m.how === "similar")
+        parts.push(`closest name to "${m.query}"`);
+    else if (m.how === "alias")
+        parts.push(`matched "${m.query}" as an alias`);
+    if (m.entity_ids.length > 1) {
+        const also = m.other_names.length ? `: ${m.other_names.slice(0, 3).map((n) => `"${n}"`).join(", ")}` : "";
+        parts.push(`${m.entity_ids.length} entity rows${also}`);
+    }
+    parts.push(`linked claims:${countLabel(m.linked_claims, m.linked_claims_capped)}`);
+    return parts.join(" · ");
+}
+/** Notice for an entity filter: what it matched, or that it matched nothing. */
+export function entityResolutionNote(data) {
+    if (data.entity_resolved === false) {
+        return "Note: the entity name matched no known entity — 0 results means an unknown name, not that nothing was claimed. Try find_entities for the canonical name.\n\n";
+    }
+    return data.entity_match ? `entity filter: ${entityMatchLine(data.entity_match)}\n` : "";
+}
 export function formatClaims(data, footer = "", offset = 0) {
     const claims = data.claims ?? [];
-    const note = speakerResolutionNote(data);
+    const note = speakerResolutionNote(data) + entityResolutionNote(data);
     if (!claims.length)
-        return note + "No claims found matching your search criteria." + footer;
-    const total = data.total_results ?? claims.length;
-    const ms = data.processing_time_ms ?? 0;
-    const mode = data.search_mode ?? "n/a";
-    const lines = [`**${total} claims** (showing ${claims.length}, ${mode}, ${ms.toFixed(0)}ms)\n`];
+        return note + (offset > 0 ? pastEndMessage(offset, "claims") : "No claims found matching your search criteria.") + footer;
+    const total = realTotal(data);
+    const lines = [resultsHeader({
+            shown: claims.length, total, offset, consumed: claims.length,
+            hasMore: data.has_more, minSimilarity: data.min_similarity, noun: "claims",
+            depthReached: data.depth_reached, rankedDepth: data.ranked_depth,
+        }) + "\n"];
     for (let i = 0; i < claims.length; i++) {
         const c = claims[i];
         lines.push(claimLine(c, i + 1));
@@ -384,19 +522,17 @@ export function formatClaims(data, footer = "", offset = 0) {
         const obs = c.sample_observations ?? [];
         if (obs.length) {
             const o = obs[0];
-            const clip = clipUrl(o.content_id, o.start_time ?? undefined, o.end_time ?? undefined, o.clip_url);
             const label = [o.speaker_name, o.channel_name, fmtDate(o.publish_date)].filter(Boolean).join(", ");
             const pointer = o.segment_id != null ? `get_segment seg:${o.segment_id}` : undefined;
             lines.push(`   sample: "${truncateWithPointer(o.chunk_text, pointer)}" — ${label}`);
-            lines.push(`   seg:${o.segment_id ?? "n/a"} episode:${o.content_id ?? "n/a"} ${clipLine(o.content_type, clip)}`);
+            lines.push(`   seg:${o.segment_id ?? "n/a"} episode:${o.content_id ?? "n/a"}`);
         }
         lines.push("");
     }
     if (anyNonEnglish(claims))
         lines.push(NON_ENGLISH_NOTE, "");
-    const paging = pagingNote({ shown: claims.length, total, offset });
     const hint = nextCallHint(`get_claim claim:${claims[0].claim_id} include_observations:true`);
-    return withFooters(note + lines.join("\n"), footer, paging, hint);
+    return withFooters(note + lines.join("\n"), footer, "", hint);
 }
 // ---------------------------------------------------------------------------
 // Claims analysis (/api/v1/analysis/claims/*)
@@ -620,40 +756,51 @@ export function formatEntitySearch(data) {
         const tokens = [`entity:${e.id}`];
         if (e.entity_type)
             tokens.push(`type:${e.entity_type}`);
-        tokens.push(`claims:${e.claim_count}`, `channels:${e.channel_count}`);
+        tokens.push(`claims:${countLabel(e.claim_count, e.claim_count_capped)}`);
         if (e.first_seen_date)
             tokens.push(`first_seen:${fmtDate(e.first_seen_date)}`);
         if (e.last_seen_date)
             tokens.push(`last_seen:${fmtDate(e.last_seen_date)}`);
         lines.push(`- **${e.name}** — ${tokens.join(" ")}`);
+        if (e.matched_ids && e.matched_ids.length > 1) {
+            const also = e.also_named?.length ? ` (also named ${e.also_named.slice(0, 3).map((n) => `"${n}"`).join(", ")})` : "";
+            lines.push(`   "${data.query}" covers ${e.matched_ids.length} entity rows${also}; entity_claims uses them all`);
+        }
         if (e.aliases?.length)
             lines.push(`   aliases:${e.aliases.slice(0, 5).join(",")}`);
     }
-    const hint = nextCallHint(`entity_claims entity:"${data.entities[0].name}"`);
-    return lines.join("\n") + hint;
+    lines.push("", "_claims = claims linked to the entity, single mentions included._");
+    const paging = pageLine({ offset: data.offset ?? 0, shown: data.entities.length, hasMore: !!data.has_more });
+    const hint = nextCallHint(`entity_claims entity:"${data.query}"`);
+    return lines.join("\n") + paging + hint;
 }
 export function formatEntityClaims(data, footer = "", offset = 0) {
     if (!data.entity_id) {
-        return `No entity found matching "${data.entity}". Try a different spelling, or use search_claims?entity= for fuzzy matching.` + footer;
+        if (data.timed_out) {
+            return `Timed out looking up "${data.entity}" — this is not "no claims". Retry (a repeat call is usually fast), or use search_claims with a topic and entity:"${data.entity}".` + footer;
+        }
+        return `No entity found matching "${data.entity}". Try find_entities for the canonical name, or search_claims with a topic.` + footer;
     }
     const lines = [`# Claims about ${data.entity}`];
     const tokens = [`entity:${data.entity_id}`];
     if (data.entity_type)
         tokens.push(`type:${data.entity_type}`);
-    if (data.claim_count_rollup != null)
-        tokens.push(`claims:${data.claim_count_rollup}`);
-    if (data.channel_count != null)
-        tokens.push(`channels:${data.channel_count}`);
     lines.push(tokens.join(" "));
+    if (data.match)
+        lines.push(`matched: ${entityMatchLine(data.match)}`);
     if (data.aliases?.length)
         lines.push(`aliases:${data.aliases.slice(0, 6).join(",")}`);
+    if (data.timed_out) {
+        lines.push("", `Timed out before the claims were ranked: ${data.entity} has too many linked claims to rank in the time limit with these filters. This is not "no claims". Retry, or narrow with collection or stance, or use search_claims with a topic and entity:"${data.entity}".`);
+        return lines.join("\n") + footer;
+    }
     if (data.stance_distribution?.length) {
         const total = data.stance_distribution.reduce((s, x) => s + x.count, 0) || 1;
         const parts = data.stance_distribution
             .map((s) => `${s.stance}:${s.count} (${Math.round((s.count / total) * 100)}%)`);
         lines.push(`\nstance: ${parts.join(" ")}`);
     }
-    lines.push(`\n## Top claims (${data.claims.length} of ${data.total_claims})`);
+    lines.push(`\n## Top claims (${data.claims.length} of ${data.total_claims.toLocaleString("en-US")} observed at least twice)`);
     data.claims.forEach((c, i) => lines.push(claimLine(c, i + 1)));
     if (anyNonEnglish(data.claims))
         lines.push("", NON_ENGLISH_NOTE);
@@ -686,23 +833,27 @@ export function formatClaimGraph(data) {
     const hint = nextCallHint(`get_claim claim:${data.claim.claim_id} include_observations:true`, next ? `claim_graph claim_id:${next.claim_id}` : undefined);
     return lines.join("\n") + hint;
 }
-export function formatTopClaims(data, footer = "") {
+export function formatTopClaims(data, footer = "", offset = 0) {
+    const start = data.offset ?? offset;
     if (!data.claims?.length) {
+        if (start > 0)
+            return `No ${data.metric} claims past rank ${start} (the leaderboard is ${data.ranked_depth ?? 100} deep).` + footer;
         return `No ${data.metric} claims found in the window. Try a wider days range or lower min_observations.` + footer;
     }
     const contested = data.metric === "contested";
     const label = contested ? "Most contested claims" : "Most widely-spread claims";
     const lines = [`# ${label}`, ""];
     data.claims.forEach((c, i) => {
-        lines.push(claimLine(c, i + 1, { assertDeny: contested }));
+        lines.push(claimLine(c, start + i + 1, { assertDeny: contested }));
         const speakers = (c.top_speakers ?? []).slice(0, 3);
         if (speakers.length)
             lines.push(`   speakers: ${claimSpeakerParts(speakers, 3)}`);
     });
     if (anyNonEnglish(data.claims))
         lines.push("", NON_ENGLISH_NOTE);
+    const paging = pageLine({ offset: start, shown: data.claims.length, hasMore: !!data.has_more });
     const hint = nextCallHint(`get_claim claim:${data.claims[0].claim_id} include_observations:true`);
-    return withFooters(lines.join("\n"), footer, "", hint);
+    return withFooters(lines.join("\n"), footer, paging, hint);
 }
 // ---------------------------------------------------------------------------
 // Speaker
@@ -816,21 +967,28 @@ export function formatChannel(data) {
 export function formatSegment(data) {
     const segId = data.segment_id;
     const spk = data.speaker ?? {};
-    const spkName = data.speaker_name ?? spk.name;
-    const resolved = spk.identity_id != null;
+    // get_segment returns the primary speaker flat (speaker_name /
+    // canonical_speaker_id / attribution) and the per-speaker list separately;
+    // other producers of SegmentDetail nest it. Accept both, preferring the flat
+    // fields, which is the precedence formatSegment already had for the name.
+    const primary = {
+        ...spk,
+        name: data.speaker_name ?? spk.name,
+        identity_id: spk.identity_id ?? data.canonical_speaker_id,
+        attribution: spk.attribution ?? data.attribution,
+        corroborated_by: spk.corroborated_by ?? data.corroborated_by,
+    };
+    const attr = speakerAttribution(primary);
+    const resolved = primary.identity_id != null;
     const clip = clipUrl(data.content_id, data.start_time ?? undefined, data.end_time ?? undefined, data.clip_url);
-    const speakerTokens = [];
-    if (resolved)
-        speakerTokens.push(`speaker:${spk.identity_id}`);
-    else if (!spkName)
-        speakerTokens.push("speaker:unresolved (diarization cluster)");
+    const speakerTokens = [...attr.tokens];
     if (spk.confidence !== undefined || resolved)
         speakerTokens.push(confToken(spk.confidence));
     if (spk.appearance_type)
         speakerTokens.push(`appearance:${spk.appearance_type}`);
     const lines = [
         `**Segment ${segId ?? "n/a"}**`,
-        `- **Speaker:** ${spkName ?? "unresolved (diarization cluster)"}${speakerTokens.length ? ` — ${speakerTokens.join(" ")}` : ""}`,
+        `- **Speaker:** ${attr.label}${speakerTokens.length ? ` — ${speakerTokens.join(" ")}` : ""}`,
         `- **Channel:** ${data.channel_name ?? "n/a"}${data.channel_id != null ? ` — channel_id:${data.channel_id}` : ""}`,
         `- **Episode:** ${data.episode_title ?? "n/a"} — episode:${data.content_id ?? "n/a"}`,
         `- **Date:** date:${fmtDate(data.episode_date)}`,
@@ -840,7 +998,7 @@ export function formatSegment(data) {
     lines.push(`- ${clipLine(data.content_type, clip)}`);
     lines.push(`\n> ${data.text ?? ""}`);
     const hint = nextCallHint(segId != null ? `get_thread segment_id:${segId}` : undefined, data.content_id ? `get_episode content_id:${data.content_id}` : undefined);
-    return lines.join("\n") + hint;
+    return lines.join("\n") + hint + (attr.hedged ? ATTRIBUTION_NOTE : "");
 }
 // ---------------------------------------------------------------------------
 // Analysis
@@ -1363,7 +1521,7 @@ function observationLine(o) {
         `  seg:${o.segment_id ?? "n/a"} episode:${o.content_id ?? "n/a"} ${clipLine(o.content_type, clip)}`,
     ];
 }
-export function formatClaimDetail(detail, observations, related) {
+export function formatClaimDetail(detail, observations, related, obsOffset = 0) {
     const c = detail.claim;
     const lines = [];
     lines.push(`# Claim claim:${c.claim_id}`);
@@ -1401,18 +1559,28 @@ export function formatClaimDetail(detail, observations, related) {
     const obs = observations?.observations ?? c.sample_observations ?? [];
     let firstObsSeg;
     if (obs.length) {
-        const label = observations ? `**Observations** (${observations.total} total)` : "**Sample Observations**";
+        const label = observations ? `**Observations** (${observations.total.toLocaleString("en-US")} total)` : "**Sample Observations**";
         lines.push(label);
-        for (const o of obs.slice(0, 20)) {
+        for (const o of observations ? obs : obs.slice(0, 20)) {
             if (firstObsSeg == null && o.segment_id != null)
                 firstObsSeg = o.segment_id;
             lines.push(...observationLine(o));
         }
-        if (observations && observations.total > Math.min(obs.length, 20)) {
-            lines.push(`showing ${Math.min(obs.length, 20)} of ${observations.total} — page:${(observations.page ?? 1) + 1} for more`);
+        // The hint used to say "page:N", a parameter get_claim never had (signal4#329).
+        if (observations) {
+            const page = pageLine({
+                offset: obsOffset, shown: obs.length, total: observations.total,
+                hasMore: obsOffset + obs.length < observations.total,
+                param: "observations_offset", noun: "observations",
+            }).trim();
+            if (page)
+                lines.push(page);
         }
         lines.push("");
     }
+    else if (observations && obsOffset > 0) {
+        lines.push(`**Observations**: none past ${obsOffset.toLocaleString("en-US")} (${observations.total.toLocaleString("en-US")} total)`, "");
+    }
     if (related?.claims?.length) {
         lines.push("**Related Claims:**");
         for (const r of related.claims) {
@@ -1420,26 +1588,93 @@ export function formatClaimDetail(detail, observations, related) {
         }
         lines.push("");
     }
+    else if (related?.method === "timed_out" || related?.method === "unavailable") {
+        lines.push("_Related claims: lookup timed out; the claim above is unaffected. Retry, or use search_claims with its summary as the topic._", "");
+    }
     const hint = nextCallHint(firstObsSeg != null ? `get_segment seg:${firstObsSeg}` : undefined, `claim_graph claim_id:${c.claim_id}`);
     return lines.join("\n") + hint;
 }
 // ---------------------------------------------------------------------------
 // Timeline
 // ---------------------------------------------------------------------------
-/** MCP timeline: `date<TAB>count` rows (spec §5 — bar glyphs retired). */
+export const TIMELINE_MAX_ROWS = 60;
+function isoWeekStart(d) {
+    const t = new Date(d.slice(0, 10) + "T00:00:00Z");
+    const dow = (t.getUTCDay() + 6) % 7; // Monday = 0
+    t.setUTCDate(t.getUTCDate() - dow);
+    return t.toISOString().slice(0, 10);
+}
+/** Aggregate day buckets to week, then month, until at most `max` rows remain. */
+export function aggregateBuckets(buckets, granularity, max = TIMELINE_MAX_ROWS) {
+    let rows = buckets.map((b) => ({ start: b.start.slice(0, 10), count: b.count }));
+    let g = granularity;
+    const fold = (key) => {
+        const m = new Map();
+        for (const r of rows) {
+            const k = key(r.start);
+            m.set(k, (m.get(k) ?? 0) + r.count);
+        }
+        rows = [...m.entries()].map(([start, count]) => ({ start, count })).sort((a, b) => a.start.localeCompare(b.start));
+    };
+    if (rows.length > max && g === "day") {
+        fold(isoWeekStart);
+        g = "week";
+    }
+    // Only fine buckets fold. month/quarter/year come bucketed by the server on calendar
+    // boundaries; re-keying them here would relabel a quarter as a month.
+    if (rows.length > max && g === "week") {
+        fold((d) => d.slice(0, 7));
+        g = "month";
+    }
+    return { rows, granularity: g };
+}
+/** MCP timeline: one summary line, then `date<TAB>count` rows (zero runs collapsed, ≤60 rows). */
 export function formatTimeline(data, footer = "") {
-    const buckets = data.buckets ?? [];
-    if (!buckets.length)
+    const raw = data.buckets ?? [];
+    if (!raw.length)
         return "No data found for this topic in the given time range." + footer;
+    const { rows: buckets, granularity } = aggregateBuckets(raw, data.granularity);
+    const total = buckets.reduce((n, b) => n + b.count, 0);
+    const peak = buckets.reduce((best, b) => (b.count > best.count ? b : best), buckets[0]);
+    const mean = total / buckets.length;
     const lines = [
-        `**"${data.topic}"** — ${data.total} segments (${data.granularity}, ${data.search_mode})\n`,
+        `**"${data.topic}"** — ${data.total ?? total} segments${data.episodes != null ? ` · ${data.episodes} episodes · ${data.channels ?? 0} channels` : ""} · peak ${peak.start} (${peak.count}) · mean ${mean.toFixed(1)}/${granularity} · by ${granularity}${granularity !== data.granularity ? ` (aggregated from ${data.granularity})` : ""} · semantic estimate at ≥${data.min_similarity ?? 0.35}\n`,
         "date\tcount",
     ];
+    let zeroRun = [];
+    const flush = () => {
+        if (zeroRun.length > 3)
+            lines.push(`${zeroRun[0].start}..${zeroRun[zeroRun.length - 1].start}\t0 (${zeroRun.length} empty)`);
+        else
+            for (const z of zeroRun)
+                lines.push(`${z.start}\t0`);
+        zeroRun = [];
+    };
     for (const b of buckets) {
+        if (b.count === 0) {
+            zeroRun.push(b);
+            continue;
+        }
+        flush();
         lines.push(`${b.start}\t${b.count}`);
     }
-    const peak = buckets.reduce((best, b) => (b.count > best.count ? b : best), buckets[0]);
+    flush();
+    for (const note of data.notes ?? [])
+        lines.push(`_Note: ${note}._`);
     const hint = nextCallHint(`search_quotes topic:"${data.topic}" start_date:${peak.start.slice(0, 10)}`);
     return withFooters(lines.join("\n"), footer, "", hint);
 }
+/** Token-light collection listing: header, `key | channels | description`, aliases. */
+export function formatCollections(data) {
+    const cols = (data.collections ?? []).filter((c) => c.enabled !== false);
+    const surface = getSurface();
+    const flag = surface === "cli" ? "--collection" : "collection";
+    const lines = [`${cols.length} collections · omit ${flag} to search ${data.default ?? "everything"}`];
+    for (const c of cols)
+        lines.push(`${c.key} | ${c.channels ?? "?"} channels | ${truncate(c.description ?? c.label ?? "", 90)}`);
+    const al = Object.entries(data.aliases ?? {});
+    if (al.length)
+        lines.push(`aliases: ${al.map(([a, k]) => `${a}=${k}`).join(", ")}`);
+    return lines.join("\n");
+}
 //# sourceMappingURL=format.js.map