@etiquekit/etq 1.0.12 → 1.0.13

package/packages/control/src/projection/timeline.ts

@@ -0,0 +1,708 @@
+import type { LocalLedgerView, LocalLedgerViewOptions, LocalLedgerViewRow } from './local-ledger-view';
+import { buildLocalLedgerView } from './local-ledger-view';
+import { existsSync } from 'node:fs';
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+export type TimelineScope = 'project' | 'seat' | 'lane' | 'principal';
+export type TimelineFormat = 'text' | 'json' | 'markdown';
+export type TimelineItemType = 'task_card' | 'return' | 'receipt' | 'decision' | 'chatter';
+
+type JsonRecord = Record<string, unknown>;
+
+export interface TimelineCardSection {
+  label: 'Routing' | 'Evidence' | 'Failure modes' | 'Confidence calibration';
+  body: string;
+}
+
+export interface TimelineViewOptions extends LocalLedgerViewOptions {
+  scope?: TimelineScope;
+}
+
+export interface TimelineFeedItem {
+  item_id: string;
+  item_type: TimelineItemType;
+  scope: TimelineScope;
+  lane: string | null;
+  seat_id: string | null;
+  operator_principal: string | null;
+  actor_seat_id: string | null;
+  created_at: string | null;
+  next_owner: string | null;
+  role: string | null;
+  verdict: string | null;
+  status_effect: string | null;
+  topic_hints: string[];
+  requires_ack: boolean | null;
+  display: {
+    role_chip: string | null;
+    lane_chip: string | null;
+    seat_badge: string | null;
+    verdict_pill: string | null;
+    status_subtitle: string | null;
+    topic_chips: string[];
+    sections: TimelineCardSection[];
+  };
+  thread: {
+    thread_id: string;
+    parent_ref: string | null;
+    depth: number;
+    is_thread_root: boolean;
+    thread_item_count: number;
+  };
+  title: string;
+  body: string;
+  source: {
+    kind: 'event' | 'packet';
+    seq: number | null;
+    event_ref: string | null;
+    packet_ref: string | null;
+    commit_sha: string;
+    event_log_hash: string;
+  };
+  authority_boundary: {
+    projection_item_only: true;
+    can_execute: false;
+    can_trigger_mention: false;
+    can_write_back: false;
+    can_grant: false;
+    can_close: false;
+    can_merge: false;
+    can_sign: false;
+  };
+}
+
+export interface TimelineThread {
+  thread_id: string;
+  lane: string | null;
+  title: string;
+  item_ids: string[];
+  latest_seq: number | null;
+  item_count: number;
+}
+
+export interface TimelineCuratorPortal {
+  schema: 'timeline-curator-portal.v0';
+  health_board: {
+    registry_ref: '.etiquette/roster/enrollments/*.json';
+    seats: {
+      seat_id: string;
+      lifecycle_state: string;
+      ready: boolean;
+      operator_principal: string | null;
+      execution_seat: string | null;
+      source: 'roster' | 'ledger-observed';
+      sentinel_state_ref: string;
+      cursor_ref: string;
+    }[];
+  };
+  digest_view: {
+    window: 'current_projection';
+    items_by_type: Record<TimelineItemType, number>;
+    threads: number;
+    requires_ack: number;
+  };
+  promotion_queue: {
+    display_only: true;
+    items: {
+      item_id: string;
+      source_ref: string;
+      lane: string | null;
+      next_owner: string | null;
+      reason: string;
+    }[];
+  };
+  authority_boundary: {
+    display_only: true;
+    can_execute: false;
+    can_write_back: false;
+    can_promote: false;
+    can_grant: false;
+    can_close: false;
+    can_merge: false;
+  };
+}
+
+export interface TimelineView {
+  schema: 'timeline-projection.v0';
+  project: string;
+  scope: TimelineScope;
+  watermark: LocalLedgerView['watermark'];
+  source: {
+    mode: 'projection-only';
+    projection_schema: 'local-ledger-view.v0';
+    event_log_ref: '.etiquette/events/local.ndjson';
+    packet_glob_ref: 'docs/work/packets/*.json';
+    roster_ref: '.etiquette/roster/enrollments/*.json';
+  };
+  identity_resolution: {
+    source: 'one-roster';
+    seat_filter: string | null;
+    lane_filter: string | null;
+    chat_nicknames_are_identity: false;
+    parallel_identity_store: false;
+  };
+  feed: {
+    items: TimelineFeedItem[];
+    items_matched: number;
+    display_modes: ['stream', 'thread'];
+    deep_link: {
+      query_param: 'seq';
+      item_id: string | null;
+      event_ref: string | null;
+    };
+    threads: TimelineThread[];
+  };
+  curator_portal: TimelineCuratorPortal;
+  boundary: string;
+  authority_boundary: {
+    read_only_projection: true;
+    rebuildable_projection: true;
+    can_execute: false;
+    can_trigger_mention: false;
+    can_write_back: false;
+    can_create_canonical_chatter: false;
+    can_grant: false;
+    can_mint_or_widen_lease: false;
+    can_close: false;
+    can_merge: false;
+    can_sign: false;
+    can_use_hosted_backend: false;
+  };
+  next_step: string;
+}
+
+const DECISION_WORDS = [
+  'decision',
+  'grant',
+  'approval',
+  'approve',
+  'escalate',
+  'policy',
+  'closeout',
+];
+
+const TIMELINE_ITEM_TYPES: TimelineItemType[] = ['task_card', 'return', 'receipt', 'decision', 'chatter'];
+
+function stringField(record: JsonRecord, field: string): string | null {
+  const value = record[field];
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null;
+}
+
+function boolField(record: JsonRecord, field: string): boolean {
+  return record[field] === true;
+}
+
+function safeName(value: string): string {
+  return value.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'seat';
+}
+
+async function readJsonIfExists(path: string): Promise<JsonRecord | null> {
+  try {
+    return JSON.parse(await readFile(path, 'utf-8')) as JsonRecord;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+async function listRosterEnrollments(root: string): Promise<JsonRecord[]> {
+  const dir = join(root, '.etiquette', 'roster', 'enrollments');
+  if (!existsSync(dir)) return [];
+  const entries = await readdir(dir, { withFileTypes: true });
+  const rows: JsonRecord[] = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.json')) continue;
+    const row = await readJsonIfExists(join(dir, entry.name));
+    if (row) rows.push(row);
+  }
+  return rows.sort((left, right) => String(left.seat_id ?? '').localeCompare(String(right.seat_id ?? '')));
+}
+
+function classifyTimelineItem(row: LocalLedgerViewRow): TimelineItemType {
+  const role = row.role?.toLowerCase() ?? '';
+  const type = row.type?.toLowerCase() ?? '';
+  const text = row.text.toLowerCase();
+  if (role.includes('task') || type.includes('task')) return 'task_card';
+  if (role.includes('return') || type.includes('return')) return 'return';
+  if (role.includes('receipt') || type.includes('receipt')) return 'receipt';
+  if (DECISION_WORDS.some((word) => role.includes(word) || type.includes(word) || text.includes(word))) {
+    return 'decision';
+  }
+  return 'chatter';
+}
+
+function isPrincipalRow(row: LocalLedgerViewRow): boolean {
+  const haystack = [
+    row.role,
+    row.type,
+    row.from,
+    row.to,
+    row.next_owner,
+    row.text,
+  ].filter((value): value is string => Boolean(value)).join(' ').toLowerCase();
+  return row.requires_ack === true
+    || Boolean(row.next_owner)
+    || DECISION_WORDS.some((word) => haystack.includes(word));
+}
+
+function rowInTimelineScope(row: LocalLedgerViewRow, scope: TimelineScope, options: TimelineViewOptions): boolean {
+  if (scope === 'project') return true;
+  if (scope === 'principal') return isPrincipalRow(row);
+  if (scope === 'lane') return Boolean(options.lane) && row.lane === options.lane;
+  if (scope === 'seat') {
+    const seat = options.seat;
+    return Boolean(seat) && (
+      row.from === seat
+      || row.to === seat
+      || row.next_owner === seat
+      || row.text.includes(String(seat))
+    );
+  }
+  return false;
+}
+
+function itemTitle(row: LocalLedgerViewRow, itemType: TimelineItemType): string {
+  const label = itemType.replace('_', ' ');
+  const lane = row.lane ? ` for ${row.lane}` : '';
+  const role = row.role ? ` (${row.role})` : '';
+  return `${label}${lane}${role}`;
+}
+
+function itemBody(row: LocalLedgerViewRow): string {
+  const parts = [
+    row.from && row.to ? `${row.from} -> ${row.to}` : row.from ?? row.to ?? null,
+    row.next_owner ? `next_owner=${row.next_owner}` : null,
+    row.requires_ack === true ? 'requires_ack=true' : null,
+    row.verdict ? `verdict=${row.verdict}` : null,
+    row.status_effect && row.status_effect !== 'none' ? `status_effect=${row.status_effect}` : null,
+    row.packet_ref ? `packet=${row.packet_ref}` : null,
+    row.event_ref ? `event=${row.event_ref}` : null,
+  ].filter((value): value is string => Boolean(value));
+  return parts.join(' | ') || row.text;
+}
+
+function sourceIdForRow(row: LocalLedgerViewRow): string {
+  return row.event_ref ?? row.packet_ref ?? `${row.kind}:${row.seq ?? 'unsequenced'}`;
+}
+
+function sourceRefForRow(row: LocalLedgerViewRow): string {
+  return row.event_ref ?? row.packet_ref ?? 'unsequenced';
+}
+
+function threadIdForRow(row: LocalLedgerViewRow): string {
+  if (row.lane) return `lane:${row.lane}`;
+  if (row.in_reply_to) return `reply:${row.in_reply_to}`;
+  if (row.parent_event_ref) return `reply:${row.parent_event_ref}`;
+  if (row.parent_event_seq !== null) return `reply:local://event/${row.parent_event_seq}`;
+  return `item:${sourceIdForRow(row)}`;
+}
+
+function parentRefForRow(row: LocalLedgerViewRow): string | null {
+  if (row.in_reply_to) return row.in_reply_to;
+  if (row.parent_event_ref) return row.parent_event_ref;
+  if (row.parent_event_seq !== null) return `local://event/${row.parent_event_seq}`;
+  return null;
+}
+
+function verdictPill(row: LocalLedgerViewRow): string | null {
+  if (row.verdict) return row.verdict;
+  const match = row.text.match(/\b(CONFIRM_WITH_AMENDMENTS|CONFIRM|COUNTER|PASS|FAIL|HOLD|GO|NO_GO)\b/i);
+  return match ? match[1].toUpperCase() : null;
+}
+
+function cardSections(row: LocalLedgerViewRow): TimelineCardSection[] {
+  const route = [
+    row.from ? `from=${row.from}` : null,
+    row.to ? `to=${row.to}` : null,
+    row.next_owner ? `next_owner=${row.next_owner}` : null,
+    row.mode ? `mode=${row.mode}` : null,
+  ].filter((part): part is string => Boolean(part)).join(' | ') || 'routing unresolved in projection';
+  const evidence = [
+    row.event_ref ? `event=${row.event_ref}` : null,
+    row.packet_ref ? `packet=${row.packet_ref}` : null,
+    row.packet_tier ? `packet_tier=${row.packet_tier}` : null,
+  ].filter((part): part is string => Boolean(part)).join(' | ') || sourceRefForRow(row);
+  const confidence = row.seq !== null
+    ? `sequenced local event seq=${row.seq}; rebuild from local event log and packet refs`
+    : 'legacy packet fallback; unsequenced packet row remains projection-only';
+  return [
+    { label: 'Routing', body: route },
+    { label: 'Evidence', body: evidence },
+    { label: 'Failure modes', body: 'display-only projection; no comments, writes, mentions, grants, closes, merges, or execution' },
+    { label: 'Confidence calibration', body: confidence },
+  ];
+}
+
+function buildThreads(items: TimelineFeedItem[]): TimelineThread[] {
+  const byThread = new Map<string, TimelineFeedItem[]>();
+  for (const item of items) {
+    const existing = byThread.get(item.thread.thread_id) ?? [];
+    existing.push(item);
+    byThread.set(item.thread.thread_id, existing);
+  }
+  return Array.from(byThread.entries()).map(([threadId, threadItems]) => {
+    const sorted = [...threadItems].sort((left, right) => (left.source.seq ?? 0) - (right.source.seq ?? 0));
+    const latestSeq = sorted.reduce<number | null>((latest, item) => (
+      item.source.seq === null ? latest : Math.max(latest ?? 0, item.source.seq)
+    ), null);
+    const lane = sorted.find((item) => item.lane)?.lane ?? null;
+    return {
+      thread_id: threadId,
+      lane,
+      title: lane ? `Thread ${lane}` : `Thread ${threadId}`,
+      item_ids: sorted.map((item) => item.item_id),
+      latest_seq: latestSeq,
+      item_count: sorted.length,
+    };
+  }).sort((left, right) => (right.latest_seq ?? 0) - (left.latest_seq ?? 0));
+}
+
+function attachThreadCounts(items: TimelineFeedItem[], threads: TimelineThread[]): TimelineFeedItem[] {
+  const countByThread = new Map(threads.map((thread) => [thread.thread_id, thread.item_count] as const));
+  return items.map((item) => ({
+    ...item,
+    thread: {
+      ...item.thread,
+      thread_item_count: countByThread.get(item.thread.thread_id) ?? 1,
+    },
+  }));
+}
+
+function titleCase(value: string): string {
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+function itemBadge(itemType: TimelineItemType): string {
+  switch (itemType) {
+    case 'task_card':
+      return 'TASK';
+    case 'return':
+      return 'RETURN';
+    case 'receipt':
+      return 'RECEIPT';
+    case 'decision':
+      return 'DECISION';
+    case 'chatter':
+      return 'CHATTER';
+  }
+}
+
+function itemSourceRef(item: TimelineFeedItem): string {
+  return item.source.event_ref ?? item.source.packet_ref ?? 'unsequenced';
+}
+
+function itemAudienceLine(item: TimelineFeedItem): string {
+  const participants = [
+    item.actor_seat_id ? `from=${item.actor_seat_id}` : null,
+    item.seat_id ? `seat=${item.seat_id}` : null,
+    item.operator_principal ? `operator=${item.operator_principal}` : null,
+  ].filter((value): value is string => Boolean(value));
+  return participants.length > 0 ? participants.join(' ') : 'seat=unresolved';
+}
+
+function timelineItemFromRow(
+  row: LocalLedgerViewRow,
+  scope: TimelineScope,
+  watermark: LocalLedgerView['watermark'],
+): TimelineFeedItem {
+  const itemType = classifyTimelineItem(row);
+  const sourceId = sourceIdForRow(row);
+  const threadId = threadIdForRow(row);
+  const parentRef = parentRefForRow(row);
+  const itemVerdict = verdictPill(row);
+  return {
+    item_id: `timeline:${sourceId}`,
+    item_type: itemType,
+    scope,
+    lane: row.lane,
+    seat_id: row.to ?? row.next_owner ?? row.from,
+    operator_principal: null,
+    actor_seat_id: row.from,
+    created_at: row.created_at,
+    next_owner: row.next_owner,
+    role: row.role,
+    verdict: itemVerdict,
+    status_effect: row.status_effect,
+    topic_hints: row.topic_hints,
+    requires_ack: row.requires_ack,
+    display: {
+      role_chip: row.role,
+      lane_chip: row.lane,
+      seat_badge: row.to ?? row.next_owner ?? row.from,
+      verdict_pill: itemVerdict,
+      status_subtitle: row.status_effect && row.status_effect !== 'none' ? row.status_effect : null,
+      topic_chips: row.topic_hints,
+      sections: cardSections(row),
+    },
+    thread: {
+      thread_id: threadId,
+      parent_ref: parentRef,
+      depth: parentRef ? 1 : 0,
+      is_thread_root: parentRef === null,
+      thread_item_count: 1,
+    },
+    title: itemTitle(row, itemType),
+    body: itemBody(row),
+    source: {
+      kind: row.kind,
+      seq: row.seq,
+      event_ref: row.event_ref,
+      packet_ref: row.packet_ref,
+      commit_sha: watermark.commit_sha,
+      event_log_hash: watermark.event_log_hash,
+    },
+    authority_boundary: {
+      projection_item_only: true,
+      can_execute: false,
+      can_trigger_mention: false,
+      can_write_back: false,
+      can_grant: false,
+      can_close: false,
+      can_merge: false,
+      can_sign: false,
+    },
+  };
+}
+
+function collectObservedSeats(rows: LocalLedgerViewRow[]): Set<string> {
+  const seats = new Set<string>();
+  for (const row of rows) {
+    for (const seat of [row.from, row.to, row.next_owner]) {
+      if (seat) seats.add(seat);
+    }
+  }
+  return seats;
+}
+
+async function buildCuratorPortal(root: string, rows: LocalLedgerViewRow[], items: TimelineFeedItem[], threads: TimelineThread[]): Promise<TimelineCuratorPortal> {
+  const enrollments = await listRosterEnrollments(root);
+  const enrollmentBySeat = new Map<string, JsonRecord>();
+  for (const enrollment of enrollments) {
+    const seat = stringField(enrollment, 'seat_id');
+    if (seat) enrollmentBySeat.set(seat, enrollment);
+  }
+  const seats = new Set([...collectObservedSeats(rows), ...enrollmentBySeat.keys()]);
+  const itemsByType = TIMELINE_ITEM_TYPES.reduce<Record<TimelineItemType, number>>((acc, type) => {
+    acc[type] = 0;
+    return acc;
+  }, {
+    task_card: 0,
+    return: 0,
+    receipt: 0,
+    decision: 0,
+    chatter: 0,
+  });
+  for (const item of items) itemsByType[item.item_type] += 1;
+  const queueItems = items
+    .filter((item) => item.requires_ack === true || item.item_type === 'decision' || Boolean(item.status_effect && item.status_effect !== 'none'))
+    .map((item) => ({
+      item_id: item.item_id,
+      source_ref: itemSourceRef(item),
+      lane: item.lane,
+      next_owner: item.next_owner,
+      reason: item.requires_ack === true ? 'requires_ack' : item.status_effect && item.status_effect !== 'none' ? `status_effect:${item.status_effect}` : 'decision',
+    }));
+  return {
+    schema: 'timeline-curator-portal.v0',
+    health_board: {
+      registry_ref: '.etiquette/roster/enrollments/*.json',
+      seats: Array.from(seats).sort().map((seat) => {
+        const enrollment = enrollmentBySeat.get(seat);
+        const key = safeName(seat);
+        return {
+          seat_id: seat,
+          lifecycle_state: stringField(enrollment ?? {}, 'lifecycle_state') ?? (enrollment ? 'enrolled' : 'observed'),
+          ready: enrollment ? boolField(enrollment, 'ready') : false,
+          operator_principal: enrollment ? stringField(enrollment, 'operator_principal') : null,
+          execution_seat: enrollment ? stringField(enrollment, 'execution_seat') : null,
+          source: enrollment ? 'roster' : 'ledger-observed',
+          sentinel_state_ref: `.etiquette/state/sentinel/${key}.json`,
+          cursor_ref: `.etiquette/state/sentinel/${key}.cursor.json`,
+        };
+      }),
+    },
+    digest_view: {
+      window: 'current_projection',
+      items_by_type: itemsByType,
+      threads: threads.length,
+      requires_ack: items.filter((item) => item.requires_ack === true).length,
+    },
+    promotion_queue: {
+      display_only: true,
+      items: queueItems,
+    },
+    authority_boundary: {
+      display_only: true,
+      can_execute: false,
+      can_write_back: false,
+      can_promote: false,
+      can_grant: false,
+      can_close: false,
+      can_merge: false,
+    },
+  };
+}
+
+export async function buildTimelineView(root: string, options: TimelineViewOptions = {}): Promise<TimelineView> {
+  const scope = options.scope ?? 'project';
+  if (scope === 'seat' && !options.seat) throw new Error('--seat is required when --scope seat');
+  if (scope === 'lane' && !options.lane) throw new Error('--lane is required when --scope lane');
+  const ledger = await buildLocalLedgerView(root, {
+    ...options,
+    kind: 'all',
+  });
+  const rows = [...ledger.events, ...ledger.packets]
+    .filter((row) => rowInTimelineScope(row, scope, options))
+    .sort((a, b) => (a.seq ?? Number.MAX_SAFE_INTEGER) - (b.seq ?? Number.MAX_SAFE_INTEGER));
+  const rawItems = rows.map((row) => timelineItemFromRow(row, scope, ledger.watermark));
+  const threads = buildThreads(rawItems);
+  const items = attachThreadCounts(rawItems, threads);
+  return {
+    schema: 'timeline-projection.v0',
+    project: root,
+    scope,
+    watermark: ledger.watermark,
+    source: {
+      mode: 'projection-only',
+      projection_schema: 'local-ledger-view.v0',
+      event_log_ref: '.etiquette/events/local.ndjson',
+      packet_glob_ref: 'docs/work/packets/*.json',
+      roster_ref: '.etiquette/roster/enrollments/*.json',
+    },
+    identity_resolution: {
+      source: 'one-roster',
+      seat_filter: options.seat ?? null,
+      lane_filter: options.lane ?? null,
+      chat_nicknames_are_identity: false,
+      parallel_identity_store: false,
+    },
+    feed: {
+      items,
+      items_matched: rows.length,
+      display_modes: ['stream', 'thread'],
+      deep_link: {
+        query_param: 'seq',
+        item_id: null,
+        event_ref: null,
+      },
+      threads,
+    },
+    curator_portal: await buildCuratorPortal(root, rows, items, threads),
+    boundary: 'read-only rebuildable timeline projection; chatter is projection, not canonical; mentions cannot execute in v0',
+    authority_boundary: {
+      read_only_projection: true,
+      rebuildable_projection: true,
+      can_execute: false,
+      can_trigger_mention: false,
+      can_write_back: false,
+      can_create_canonical_chatter: false,
+      can_grant: false,
+      can_mint_or_widen_lease: false,
+      can_close: false,
+      can_merge: false,
+      can_sign: false,
+      can_use_hosted_backend: false,
+    },
+    next_step: 'use normal ledger workflow for any canonical post, grant, closeout, execution, or mention-trigger experiment',
+  };
+}
+
+export function applyTimelineDeepLink(view: TimelineView, seq: number | null): TimelineView {
+  if (seq === null || !Number.isFinite(seq)) return view;
+  const item = view.feed.items.find((candidate) => candidate.source.seq === seq) ?? null;
+  return {
+    ...view,
+    feed: {
+      ...view.feed,
+      deep_link: {
+        query_param: 'seq',
+        item_id: item?.item_id ?? null,
+        event_ref: item?.source.event_ref ?? null,
+      },
+    },
+  };
+}
+
+export function renderTimelineViewText(view: TimelineView): string {
+  return [
+    `timeline_feed: ${titleCase(view.scope)}`,
+    `schema: ${view.schema}`,
+    `scope: ${view.scope}`,
+    `source: ${view.source.projection_schema}`,
+    `watermark: ${view.watermark.latest_event_ref} commit_sha=${view.watermark.commit_sha}`,
+    `event_log_hash: ${view.watermark.event_log_hash}`,
+    `identity: ${view.identity_resolution.source} (chat nicknames are not identity)`,
+    `boundary: read-only projection; no execution, no write-back, no grants`,
+    `items_matched: ${view.feed.items_matched}`,
+    `display_modes: ${view.feed.display_modes.join(',')}`,
+    `threads: ${view.feed.threads.length}`,
+    `health_board_seats: ${view.curator_portal.health_board.seats.map((seat) => seat.seat_id).join(',') || 'none'}`,
+    `promotion_queue: ${view.curator_portal.promotion_queue.items.length} display_only=true`,
+    ...view.feed.items.map((item) => [
+      `[${itemBadge(item.item_type)}] ${item.title}`,
+      `  ${itemAudienceLine(item)}`,
+      `  source: ${itemSourceRef(item)} seq=${String(item.source.seq ?? 'none')}`,
+      `  thread: ${item.thread.thread_id} items=${item.thread.thread_item_count}`,
+      item.lane ? `  lane: ${item.lane}` : null,
+      item.role ? `  role: ${item.role}` : null,
+      item.verdict ? `  verdict: ${item.verdict}` : null,
+      item.status_effect && item.status_effect !== 'none' ? `  status_effect: ${item.status_effect}` : null,
+      item.topic_hints.length > 0 ? `  topics: ${item.topic_hints.join(',')}` : null,
+      `  body: ${item.body}`,
+      '  authority: projection-only; cannot execute, write back, grant, close, merge, or sign',
+    ].filter((line): line is string => line !== null).join('\n')),
+    'can_execute: false',
+    'can_write_back: false',
+    'can_grant: false',
+  ].join('\n');
+}
+
+export function renderTimelineViewMarkdown(view: TimelineView): string {
+  return [
+    `# Timeline Feed: ${titleCase(view.scope)}`,
+    '',
+    '| Field | Value |',
+    '| --- | --- |',
+    `| Schema | \`${view.schema}\` |`,
+    `| Source | \`${view.source.projection_schema}\` |`,
+    `| Watermark | \`${view.watermark.latest_event_ref}\` |`,
+    `| Commit | \`${view.watermark.commit_sha}\` |`,
+    `| Event log hash | \`${view.watermark.event_log_hash}\` |`,
+    `| Identity | ${view.identity_resolution.source}; chat nicknames are not identity |`,
+    '| Boundary | read-only projection; no execution, no write-back, no grants |',
+    `| Display modes | ${view.feed.display_modes.map((mode) => `\`${mode}\``).join(', ')} |`,
+    `| Threads | ${view.feed.threads.length} |`,
+    `| Health board seats | ${view.curator_portal.health_board.seats.map((seat) => `\`${seat.seat_id}\``).join(', ') || '_none_'} |`,
+    '',
+    '## Feed',
+    '',
+    ...(view.feed.items.length === 0
+      ? ['_No timeline items._']
+      : view.feed.items.map((item) => [
+        `### [${itemBadge(item.item_type)}] ${item.title}`,
+        '',
+        '| Field | Value |',
+        '| --- | --- |',
+        `| Type | \`${item.item_type}\` |`,
+        `| Source | \`${itemSourceRef(item)}\` |`,
+        `| Commit | \`${item.source.commit_sha}\` |`,
+        `| Thread | \`${item.thread.thread_id}\` (${item.thread.thread_item_count} item${item.thread.thread_item_count === 1 ? '' : 's'}) |`,
+        item.lane ? `| Lane | \`${item.lane}\` |` : null,
+        item.role ? `| Role | \`${item.role}\` |` : null,
+        item.verdict ? `| Verdict | \`${item.verdict}\` |` : null,
+        item.topic_hints.length > 0 ? `| Topics | ${item.topic_hints.map((topic) => `\`${topic}\``).join(', ')} |` : null,
+        `| Audience | ${itemAudienceLine(item)} |`,
+        `| Body | ${item.body} |`,
+        '| Authority | projection-only; cannot execute, write back, grant, close, merge, or sign |',
+      ].filter((line): line is string => line !== null).join('\n'))),
+    '',
+    '## Curator Portal',
+    '',
+    `- Health board seats: ${view.curator_portal.health_board.seats.map((seat) => `\`${seat.seat_id}\``).join(', ') || '_none_'}`,
+    `- Digest threads: ${view.curator_portal.digest_view.threads}`,
+    `- Promotion queue: ${view.curator_portal.promotion_queue.items.length} display-only item${view.curator_portal.promotion_queue.items.length === 1 ? '' : 's'}`,
+    '- Authority: display-only; cannot execute, write back, promote, grant, close, or merge.',
+    '',
+  ].join('\n');
+}