@signal4/s4 2.6.0 → 2.7.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) {
@@ -233,7 +293,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 +314,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 +331,63 @@ 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 parts = [`Showing ${opts.shown}${opts.total != null ? ` of ${opts.total}` : ""}${opts.noun ? ` ${opts.noun}` : ""}`];
+    if (opts.minSimilarity != null)
+        parts.push(`sim ≥${opts.minSimilarity}`);
+    if (more)
+        parts.push(surfaceHint(`more: offset:${opts.offset + opts.consumed}`));
+    return parts.join(" · ");
+}
 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`];
+    const lines = [resultsHeader({
+            shown: quotes.length, total: realTotal(data), offset, consumed: (data.quotes ?? []).length,
+            hasMore: data.has_more, minSimilarity: data.min_similarity,
+        }) + "\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
@@ -350,14 +433,23 @@ function claimSpeakerParts(speakers, n = 4) {
         .map((s) => `${s.name} (speaker:${s.identity_id ?? "n/a"}, ${s.observation_count})`)
         .join(", ");
 }
+/** Notice prepended when the backend reports the speaker_name filter did not
+ * resolve (speaker_resolved === false). Absent field → no notice. */
+export function speakerResolutionNote(data) {
+    if (data.speaker_resolved !== false)
+        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";
+}
 export function formatClaims(data, footer = "", offset = 0) {
     const claims = data.claims ?? [];
+    const note = speakerResolutionNote(data);
     if (!claims.length)
-        return "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 + "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",
+        }) + "\n"];
     for (let i = 0; i < claims.length; i++) {
         const c = claims[i];
         lines.push(claimLine(c, i + 1));
@@ -376,19 +468,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(lines.join("\n"), footer, paging, hint);
+    return withFooters(note + lines.join("\n"), footer, "", hint);
 }
 // ---------------------------------------------------------------------------
 // Claims analysis (/api/v1/analysis/claims/*)
@@ -437,8 +527,9 @@ export function formatClaimsTopicAnalysis(data, topic, footer = "") {
     return withFooters(lines.join("\n"), footer, "", hint);
 }
 export function formatClaimsTrend(data, topic, footer = "") {
+    const note = speakerResolutionNote(data);
     if (data.direction === "no_data") {
-        return `No claim volume data for "${topic}" in the baseline window. Try a broader topic or longer baseline_days.` + footer;
+        return note + `No claim volume data for "${topic}" in the baseline window. Try a broader topic or longer baseline_days.` + footer;
     }
     const lines = [
         `# Claim trend: "${topic}" — ${trendToken(data.direction, data.change_pct)}`,
@@ -449,7 +540,7 @@ export function formatClaimsTrend(data, topic, footer = "") {
         `baseline (${data.baseline.days}d): ${data.baseline.claims} claims, ${data.baseline.observations} obs, ${data.baseline.per_day}/day`,
     ];
     const hint = nextCallHint(`search_claims topic:"${topic}"`, `get_timeline topic:"${topic}"`);
-    return withFooters(lines.join("\n"), footer, "", hint);
+    return withFooters(note + lines.join("\n"), footer, "", hint);
 }
 export function formatClaimsContradictions(data, speaker, topic, footer = "") {
     if (data.verdict === "no_data") {
@@ -807,21 +898,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)}`,
@@ -831,7 +929,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
@@ -1417,20 +1515,84 @@ export function formatClaimDetail(detail, observations, related) {
 // ---------------------------------------------------------------------------
 // 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