thatcher 1.0.87 → 1.0.89

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thatcher",
-  "version": "1.0.87",
+  "version": "1.0.89",
   "description": "A config-driven application framework for building data-intensive web apps without code.",
   "main": "src/index.js",
   "type": "module",

package/src/lib/insights-engine.js

@@ -0,0 +1,133 @@
+// A synthesis layer over data already computed this session -- reads the
+// outputs of inventory-forecast.js/demand-forecast.js/resource-capacity.js/
+// contract-expiry.js, never reimplements their math. Deliberately rule-based
+// rather than an external LLM call: no API key, no network dependency, no
+// cost, and every rule is deterministic and directly witnessable via
+// exec_js the same way every other feature this session has been.
+import { daysUntilStockout, isReorderDue } from './inventory-forecast.js';
+import { daysUntilExpiry } from './contract-expiry.js';
+import { userCommittedHours, DEFAULT_WEEKLY_CAPACITY_HOURS } from './resource-capacity.js';
+
+const SEVERITY_ORDER = { critical: 0, warning: 1, info: 2 };
+
+function insight(severity, category, message, entity, entityId) {
+  return { severity, category, message, entity, entity_id: entityId };
+}
+
+// Product X will stock out in N days with no reorder currently scheduled --
+// "no reorder scheduled" here means the reorder isn't yet due (isReorderDue
+// false) but stockout is imminent, distinct from the existing product
+// detail-view warning which only flags the reorder-due boundary itself.
+export function stockoutRiskInsights(products, movementsByProductId) {
+  const results = [];
+  for (const product of products) {
+    const movements = movementsByProductId[product.id] || [];
+    const currentStock = movements.reduce((sum, m) => sum + (Number(m.quantity) || 0), 0);
+    const avgDailyConsumption = movements
+      .filter(m => Number(m.quantity) < 0)
+      .reduce((sum, m) => sum + Math.abs(Number(m.quantity) || 0), 0) / 90;
+    const days = daysUntilStockout(currentStock, avgDailyConsumption);
+    if (days == null) continue;
+    if (days <= 14) {
+      const severity = days <= 3 ? 'critical' : 'warning';
+      results.push(insight(severity, 'inventory', `${product.name || product.id} will stock out in ${Math.round(days)} days`, 'product', product.id));
+    }
+  }
+  return results;
+}
+
+// Contract Y expires in N days with no renewal opportunity linked --
+// cross-references contract.opportunity_id, since a contract already headed
+// toward renewal via a tracked deal is a materially different situation
+// from one with nothing lined up.
+export function contractExpiryInsights(contracts) {
+  const results = [];
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  for (const contract of contracts) {
+    if (contract.status !== 'active' || contract.end_date == null) continue;
+    const days = daysUntilExpiry(contract.end_date, nowSeconds);
+    if (days > (contract.notice_period_days ?? 30)) continue;
+    if (contract.opportunity_id) continue;
+    const severity = days <= 0 ? 'critical' : 'warning';
+    results.push(insight(severity, 'contract', `${contract.name || contract.id} expires in ${days} days with no renewal opportunity linked`, 'contract', contract.id));
+  }
+  return results;
+}
+
+// User Z is at N% capacity across active allocations -- a straightforward
+// utilization-threshold rule reusing the exact load calculation
+// resource-optimizer.js's suggestion ranking already relies on.
+export async function capacityInsights(users, windowStart, windowEnd) {
+  const results = [];
+  for (const user of users) {
+    const committed = await userCommittedHours(user.id, windowStart, windowEnd);
+    const pct = Math.round((committed / DEFAULT_WEEKLY_CAPACITY_HOURS) * 100);
+    if (pct >= 90) {
+      const severity = pct >= 100 ? 'critical' : 'warning';
+      results.push(insight(severity, 'resource', `${user.name || user.id} is at ${pct}% capacity`, 'user', user.id));
+    }
+  }
+  return results;
+}
+
+// Opportunity pipeline for month N shows a >30% drop from month N-1 --
+// compares adjacent buckets from demand-forecast.js's own projectDemandByMonth
+// output, never recomputing the bucket sums itself.
+export function pipelineDropInsights(monthlyBuckets) {
+  const results = [];
+  for (let i = 1; i < monthlyBuckets.length; i++) {
+    const [prevKey, prevValue] = monthlyBuckets[i - 1];
+    const [curKey, curValue] = monthlyBuckets[i];
+    if (prevValue <= 0) continue;
+    const dropPct = ((prevValue - curValue) / prevValue) * 100;
+    if (dropPct > 30) {
+      results.push(insight('warning', 'pipeline', `Projected pipeline for ${curKey} is ${Math.round(dropPct)}% lower than ${prevKey}`, 'opportunity', curKey));
+    }
+  }
+  return results;
+}
+
+export function sortBySeverity(insights) {
+  return [...insights].sort((a, b) => (SEVERITY_ORDER[a.severity] ?? 3) - (SEVERITY_ORDER[b.severity] ?? 3));
+}
+
+// Orchestrator: every list() call here passes {user}, the SAME row/org-access
+// scoping every entity route in the codebase already applies -- an insight
+// can never surface a record the requesting user couldn't otherwise see,
+// because it is generated from the identical scoped query that record's own
+// list view would use. entityType optionally narrows which rule categories
+// run (e.g. 'product' -> only stockout insights), skipping the rest rather
+// than fetching data for rules that won't run.
+export async function generateInsights(user, entityType = null) {
+  const { list } = await import('./busybase/store.js');
+  const results = [];
+
+  if (!entityType || entityType === 'product') {
+    const products = await list('product', {}, { user });
+    const movementsByProductId = {};
+    for (const product of products) {
+      movementsByProductId[product.id] = await list('stock_movement', { product_id: product.id });
+    }
+    results.push(...stockoutRiskInsights(products, movementsByProductId));
+  }
+
+  if (!entityType || entityType === 'contract') {
+    const contracts = await list('contract', {}, { user });
+    results.push(...contractExpiryInsights(contracts));
+  }
+
+  if (!entityType || entityType === 'user' || entityType === 'resource_allocation') {
+    const users = await list('user', {}, { user });
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    results.push(...(await capacityInsights(users, nowSeconds, nowSeconds + 30 * 86400)));
+  }
+
+  if (!entityType || entityType === 'opportunity') {
+    const { projectDemandByMonth } = await import('./demand-forecast.js');
+    const opportunities = await list('opportunity', {}, { user });
+    const buckets = projectDemandByMonth(opportunities);
+    results.push(...pipelineDropInsights(buckets));
+  }
+
+  return sortBySeverity(results);
+}

package/src/ui/insights-renderer.js

@@ -0,0 +1,47 @@
+import { page } from '@/ui/layout.js';
+import { esc, emptyRow } from '@/ui/render-helpers.js';
+
+const SEVERITY_PILL = { critical: 'pill-danger', warning: 'pill-warning', info: 'pill-neutral' };
+const ENTITY_ROUTE = { product: 'product', contract: 'contract', user: 'user', resource_allocation: 'resource_allocation' };
+
+function insightRow(insight) {
+  const pillCls = SEVERITY_PILL[insight.severity] || 'pill-neutral';
+  const entityPath = ENTITY_ROUTE[insight.entity];
+  // opportunity-pipeline insights carry a month-string entity_id (e.g.
+  // '2026-09'), not a real record id -- there is no single record to link
+  // to for a whole-pipeline observation, so only entities with a real
+  // per-record id get a link.
+  const link = entityPath && insight.entity !== 'opportunity'
+    ? `<a href="/${esc(entityPath)}/${esc(insight.entity_id)}" class="text-primary hover:underline">View</a>`
+    : '';
+  return `<tr>
+    <td><span class="pill ${pillCls}">${esc(insight.severity)}</span></td>
+    <td>${esc(insight.category)}</td>
+    <td>${esc(insight.message)}</td>
+    <td>${link}</td>
+  </tr>`;
+}
+
+export function renderInsightsPage(user, insights = []) {
+  const rows = insights.map(insightRow).join('') || emptyRow(4, 'No insights right now');
+  const counts = insights.reduce((acc, i) => { acc[i.severity] = (acc[i.severity] || 0) + 1; return acc; }, {});
+
+  const content = `
+    <div class="page-header">
+      <h1 class="page-title">Insights</h1>
+      <p class="page-subtitle">${esc(String(counts.critical || 0))} critical, ${esc(String(counts.warning || 0))} warning, ${esc(String(counts.info || 0))} info</p>
+    </div>
+    <div class="card-clean">
+      <div class="card-clean-body">
+        <div class="table-wrap">
+          <table class="data-table">
+            <thead><tr><th>Severity</th><th>Category</th><th>Insight</th><th>Link</th></tr></thead>
+            <tbody>${rows}</tbody>
+          </table>
+        </div>
+      </div>
+    </div>
+  `;
+
+  return page(user, 'Insights | Thatcher', null, content, []);
+}

package/src/ui/page-handler.js

@@ -9,7 +9,7 @@ import { renderEngagementGrid } from '@/ui/engagement-grid-renderer.js';
 import { renderBoardView } from '@/ui/board-view-renderer.js';
 import { renderGridView } from '@/ui/grid-view-renderer.js';
 import { renderCalendarView, renderTimelineView } from '@/ui/calendar-view-renderer.js';
-import { renderCountByFieldReport, renderCountOverTimeReport, renderSumByFieldReport, renderRollupReport, renderInventoryForecastReport, renderDemandForecastReport } from '@/ui/report-renderer.js';
+import { renderCountByFieldReport, renderCountOverTimeReport, renderSumByFieldReport, renderRollupReport, renderInventoryForecastReport, renderDemandForecastReport, renderPivotReport } from '@/ui/report-renderer.js';
 import { renderClientProgress } from '@/ui/client-progress-renderer.js';
 import { renderLetterWorkflow } from '@/ui/letter-workflow-renderer.js';
 import { renderAdvancedSearch } from '@/ui/advanced-search-renderer.js';
@@ -241,6 +241,16 @@ export async function handlePage(pathname, req, res) {
   if (!user) { res.writeHead(302, { Location: '/login' }); res.end(); return REDIRECT; }
   if (normalized === '/unauthorized') return renderAccessDenied(user, 'system', 'access');
   if (normalized === '/notifications') { let notifs=[]; try{notifs=await list('notification',{user_id:user.id},{sort:{field:'created_at',dir:'DESC'},limit:100,user})}catch{} const{renderNotificationsPage}=await lazyRenderer('notifications-renderer.js'); return renderNotificationsPage(user,notifs); }
+  if (normalized === '/insights') {
+    // generateInsights internally scopes every underlying list() call to
+    // {user} -- no separate access check needed here, the insights
+    // themselves can never surface a record this user couldn't already see.
+    const { generateInsights } = await import('@/lib/insights-engine.js');
+    let insights = [];
+    try { insights = await generateInsights(user); } catch {}
+    const { renderInsightsPage } = await lazyRenderer('insights-renderer.js');
+    return renderInsightsPage(user, insights);
+  }
   if (normalized === '/' || normalized === '/dashboard') return renderDashboard(user, await getDashboardStats(user));
   if (normalized.startsWith('/admin/') || normalized === '/admin/jobs') return handleAdminPage(normalized, segments, user, req);
   if (segments[0] === 'client' && segments.length === 3 && ['dashboard', 'users', 'progress'].includes(segments[2])) return handleClientSubRoute(user, segments[1], segments[2]);
@@ -360,6 +370,13 @@ export async function handlePage(pathname, req, res) {
       const groupBy = params.get('group_by') || '';
       return renderSumByFieldReport(user, entityName, spec, items, field, groupBy);
     }
+    if (report === 'pivot') {
+      const rowField = params.get('row_field') || '';
+      const colField = params.get('col_field') || '';
+      const valueField = params.get('value_field') || '';
+      const agg = params.get('agg') || 'count';
+      return renderPivotReport(user, entityName, spec, items, rowField, colField, valueField, agg);
+    }
     if (report === 'rollup') {
       const refField = params.get('ref_field') || '';
       const rollupField = params.get('rollup_field') || '';

package/src/ui/report-renderer.js

@@ -1,259 +1,345 @@
-import { page } from '@/ui/layout.js';
-import { esc } from '@/ui/render-helpers.js';
-import { emptyState } from '@/ui/format-helpers.js';
-import { getEntityLabel } from '@/config/spec-helpers.js';
-
-const MAX_BUCKETS = 15;
-
-function bucketLabel(spec, field, rawValue) {
-  if (rawValue === null || rawValue === undefined || rawValue === '') return '(empty)';
-  const fieldDef = spec.fields?.[field];
-  if (fieldDef?.type === 'enum' && Array.isArray(fieldDef.options)) {
-    const opt = fieldDef.options.find(o => String(o.value ?? o) === String(rawValue));
-    return opt ? String(opt.label || opt.value || opt) : String(rawValue);
-  }
-  return String(rawValue);
-}
-
-export function countByField(records, spec, field) {
-  const counts = new Map();
-  for (const r of records) {
-    const label = bucketLabel(spec, field, r[field]);
-    counts.set(label, (counts.get(label) || 0) + 1);
-  }
-  const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
-  if (sorted.length <= MAX_BUCKETS) return sorted;
-  const top = sorted.slice(0, MAX_BUCKETS - 1);
-  const otherCount = sorted.slice(MAX_BUCKETS - 1).reduce((sum, [, c]) => sum + c, 0);
-  return [...top, ['(other)', otherCount]];
-}
-
-function barChart(buckets) {
-  if (!buckets.length) return emptyState('No data to report on', 'bar-chart');
-  const max = Math.max(...buckets.map(([, c]) => c), 1);
-  const rows = buckets.map(([label, count]) => {
-    const pct = Math.round((count / max) * 100);
-    return `<div class="report-bar-row" style="display:flex;align-items:center;gap:12px;margin-bottom:8px">
-      <div style="min-width:140px;max-width:220px;font-size:13px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="${esc(label)}">${esc(label)}</div>
-      <div style="flex:1;height:20px;background:var(--color-border,#eee);border-radius:4px;overflow:hidden">
-        <div style="height:100%;width:${pct}%;background:var(--color-primary,#3b82f6);border-radius:4px"></div>
-      </div>
-      <div style="min-width:40px;text-align:right;font-size:13px;font-weight:600">${count}</div>
-    </div>`;
-  }).join('');
-  return `<div class="report-bar-chart">${rows}</div>`;
-}
-
-function bucketDateKey(dateValue, granularity) {
-  if (dateValue === null || dateValue === undefined || dateValue === '') return null;
-  const num = Number(dateValue);
-  const d = !isNaN(num) && num > 0 ? new Date(num * 1000) : new Date(dateValue);
-  if (isNaN(d.getTime())) return null;
-  const y = d.getFullYear();
-  const m = String(d.getMonth() + 1).padStart(2, '0');
-  const day = String(d.getDate()).padStart(2, '0');
-  if (granularity === 'day') return `${y}-${m}-${day}`;
-  if (granularity === 'week') {
-    const onejan = new Date(y, 0, 1);
-    const week = Math.ceil((((d - onejan) / 86400000) + onejan.getDay() + 1) / 7);
-    return `${y}-W${String(week).padStart(2, '0')}`;
-  }
-  return `${y}-${m}`;
-}
-
-export function countOverTime(records, dateField, granularity = 'month') {
-  const counts = new Map();
-  let unresolved = 0;
-  for (const r of records) {
-    const key = bucketDateKey(r[dateField], granularity);
-    if (key === null) { unresolved++; continue; }
-    counts.set(key, (counts.get(key) || 0) + 1);
-  }
-  const sorted = [...counts.entries()].sort((a, b) => a[0].localeCompare(b[0]));
-  return { buckets: sorted.length > MAX_BUCKETS ? sorted.slice(-MAX_BUCKETS) : sorted, unresolved, truncated: sorted.length > MAX_BUCKETS };
-}
-
-export function renderCountByFieldReport(user, entityName, spec, records, field) {
-  const label = getEntityLabel(spec, true) || entityName;
-  const fieldDef = spec.fields?.[field];
-  if (!fieldDef) {
-    return page(user, `${label} | Report`, null,
-      `<div class="page-header"><h1 class="page-title">${esc(label)}</h1></div>
-      <div class="report-empty-state">Unknown field "${esc(field)}" for this entity.</div>`);
-  }
-  const buckets = countByField(records, spec, field);
-  const content = `<div class="page-header">
-      <div><h1 class="page-title">${esc(label)} by ${esc(fieldDef.label || field)}</h1><p class="page-subtitle">${records.length} total records</p></div>
-    </div>
-    ${barChart(buckets)}`;
-  return page(user, `${label} Report | Thatcher`, null, content);
-}
-
-export function sumByField(records, spec, field, groupBy) {
-  const sums = new Map();
-  for (const r of records) {
-    const raw = r[field];
-    const num = typeof raw === 'string' ? Number(raw) : raw;
-    if (typeof num !== 'number' || isNaN(num)) continue;
-    const label = bucketLabel(spec, groupBy, r[groupBy]);
-    sums.set(label, (sums.get(label) || 0) + num);
-  }
-  const sorted = [...sums.entries()].sort((a, b) => b[1] - a[1]);
-  if (sorted.length <= MAX_BUCKETS) return sorted;
-  const top = sorted.slice(0, MAX_BUCKETS - 1);
-  const otherSum = sorted.slice(MAX_BUCKETS - 1).reduce((sum, [, v]) => sum + v, 0);
-  return [...top, ['(other)', otherSum]];
-}
-
-function formatSumValue(value, fieldDef) {
-  if (fieldDef?.type === 'currency') return (fieldDef.currency_symbol || '$') + (value / 100).toFixed(2);
-  return String(Math.round(value * 100) / 100);
-}
-
-function sumBarChart(buckets, fieldDef) {
-  if (!buckets.length) return emptyState('No data to report on', 'bar-chart');
-  const max = Math.max(...buckets.map(([, v]) => Math.abs(v)), 1);
-  const rows = buckets.map(([label, value]) => {
-    const pct = Math.round((Math.abs(value) / max) * 100);
-    return `<div class="report-bar-row" style="display:flex;align-items:center;gap:12px;margin-bottom:8px">
-      <div style="min-width:140px;max-width:220px;font-size:13px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="${esc(label)}">${esc(label)}</div>
-      <div style="flex:1;height:20px;background:var(--color-border,#eee);border-radius:4px;overflow:hidden">
-        <div style="height:100%;width:${pct}%;background:var(--color-primary,#3b82f6);border-radius:4px"></div>
-      </div>
-      <div style="min-width:80px;text-align:right;font-size:13px;font-weight:600">${esc(formatSumValue(value, fieldDef))}</div>
-    </div>`;
-  }).join('');
-  return `<div class="report-bar-chart">${rows}</div>`;
-}
-
-export function renderSumByFieldReport(user, entityName, spec, records, field, groupBy) {
-  const label = getEntityLabel(spec, true) || entityName;
-  const fieldDef = spec.fields?.[field];
-  const groupByDef = spec.fields?.[groupBy];
-  if (!fieldDef || !groupByDef) {
-    return page(user, `${label} | Report`, null,
-      `<div class="page-header"><h1 class="page-title">${esc(label)}</h1></div>
-      <div class="report-empty-state">Unknown field "${esc(!fieldDef ? field : groupBy)}" for this entity.</div>`);
-  }
-  const buckets = sumByField(records, spec, field, groupBy);
-  const content = `<div class="page-header">
-      <div><h1 class="page-title">${esc(label)}: ${esc(fieldDef.label || field)} by ${esc(groupByDef.label || groupBy)}</h1><p class="page-subtitle">${records.length} total records</p></div>
-    </div>
-    ${sumBarChart(buckets, fieldDef)}`;
-  return page(user, `${label} Report | Thatcher`, null, content);
-}
-
-// Cross-entity rollup: entity A's records are grouped by a field on related
-// entity B, joined through A's ref field. relatedRecords must already be the
-// CALLER's row/org-scoped list() result for B -- this function only joins
-// and counts, it enforces no access itself (the access decision -- can this
-// user list B at all -- is made by the caller before relatedRecords exists).
-export function rollupByRelatedField(records, refField, relatedRecords, relatedSpec, rollupField) {
-  const relatedById = new Map(relatedRecords.map(r => [String(r.id), r]));
-  const counts = new Map();
-  let unmatched = 0;
-  for (const r of records) {
-    const refId = r[refField];
-    const related = refId != null ? relatedById.get(String(refId)) : null;
-    if (!related) { unmatched++; continue; }
-    const label = bucketLabel(relatedSpec, rollupField, related[rollupField]);
-    counts.set(label, (counts.get(label) || 0) + 1);
-  }
-  const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
-  return { buckets: sorted.length > MAX_BUCKETS ? sorted.slice(0, MAX_BUCKETS) : sorted, unmatched };
-}
-
-export function renderRollupReport(user, entityName, spec, records, refField, relatedEntity, relatedSpec, relatedRecords, rollupField) {
-  const label = getEntityLabel(spec, true) || entityName;
-  const relatedLabel = getEntityLabel(relatedSpec, true) || relatedEntity;
-  const rollupFieldDef = relatedSpec?.fields?.[rollupField];
-  if (!spec.fields?.[refField] || !rollupFieldDef) {
-    return page(user, `${label} | Report`, null,
-      `<div class="page-header"><h1 class="page-title">${esc(label)}</h1></div>
-      <div class="report-empty-state">Unknown field for this rollup.</div>`);
-  }
-  const { buckets, unmatched } = rollupByRelatedField(records, refField, relatedRecords, relatedSpec, rollupField);
-  const notice = unmatched
-    ? `<div class="report-notice">${unmatched} record${unmatched === 1 ? '' : 's'} without a resolvable ${esc(relatedLabel)} excluded</div>`
-    : '';
-  const content = `<div class="page-header">
-      <div><h1 class="page-title">${esc(label)} by ${esc(relatedLabel)}.${esc(rollupFieldDef.label || rollupField)}</h1><p class="page-subtitle">${records.length} total records</p></div>
-    </div>
-    ${notice}
-    ${barChart(buckets)}`;
-  return page(user, `${label} Report | Thatcher`, null, content);
-}
-
-export function renderCountOverTimeReport(user, entityName, spec, records, dateField, granularity) {
-  const label = getEntityLabel(spec, true) || entityName;
-  const fieldDef = spec.fields?.[dateField];
-  if (!fieldDef) {
-    return page(user, `${label} | Report`, null,
-      `<div class="page-header"><h1 class="page-title">${esc(label)}</h1></div>
-      <div class="report-empty-state">Unknown date field "${esc(dateField)}" for this entity.</div>`);
-  }
-  const { buckets, unresolved, truncated } = countOverTime(records, dateField, granularity);
-  const notice = unresolved
-    ? `<div class="report-notice">${unresolved} record${unresolved === 1 ? '' : 's'} without a resolvable date excluded</div>`
-    : '';
-  const truncatedNotice = truncated
-    ? `<div class="report-notice">Showing the most recent ${buckets.length} periods only</div>`
-    : '';
-  const content = `<div class="page-header">
-      <div><h1 class="page-title">${esc(label)} over time</h1><p class="page-subtitle">${records.length} total records, grouped by ${esc(granularity)}</p></div>
-    </div>
-    ${notice}${truncatedNotice}
-    ${barChart(buckets)}`;
-  return page(user, `${label} Report | Thatcher`, null, content);
-}
-
-// One table per-product rather than a bar chart: unlike count-by-field/
-// sum-by-field's single grouped metric, a forecast is inherently multiple
-// values per row (stock, consumption rate, days-out, reorder date) -- a bar
-// chart of any single one of those would discard the others, so a table is
-// the correct shape here, reusing the same page()/esc() rendering discipline
-// as every other report rather than inventing a new chart type.
-export function renderInventoryForecastReport(user, spec, forecastRows) {
-  const label = getEntityLabel(spec, true) || 'Products';
-  const rows = forecastRows.map(p => {
-    const daysLabel = p.days_until_stockout == null ? 'Unknown' : String(Math.round(p.days_until_stockout))
-    const reorderLabel = p.reorder_date == null ? '-' : new Date(p.reorder_date * 1000).toISOString().slice(0, 10)
-    const rowCls = p.reorder_due ? 'style="background:var(--color-danger-bg,#fee2e2)"' : ''
-    return `<tr ${rowCls}>
-      <td>${esc(p.name || p.id)}</td>
-      <td>${esc(String(p.current_stock))}</td>
-      <td>${esc((p.avg_daily_consumption || 0).toFixed(2))}</td>
-      <td>${esc(daysLabel)}</td>
-      <td>${esc(reorderLabel)}${p.reorder_due ? ' <span class="pill pill-danger">Reorder Now</span>' : ''}</td>
-    </tr>`;
-  }).join('') || emptyState('No products to forecast', 'bar-chart');
-
-  const content = `<div class="page-header">
-      <div><h1 class="page-title">${esc(label)}: Inventory Forecast</h1><p class="page-subtitle">${forecastRows.length} products</p></div>
-    </div>
-    <div class="table-wrap"><table class="data-table">
-      <thead><tr><th>Product</th><th>Current Stock</th><th>Avg Daily Use</th><th>Days Until Stockout</th><th>Suggested Reorder</th></tr></thead>
-      <tbody>${rows}</tbody>
-    </table></div>`;
-  return page(user, `Inventory Forecast | Thatcher`, null, content);
-}
-
-// Reuses sumBarChart (already built for sum-by-field's currency-aware bar
-// rendering) rather than inventing a third chart type -- a demand-by-month
-// bucket is the exact same [label, numericValue] shape sum-by-field already
-// renders, just currency-formatted since weighted_value derives from a
-// currency field.
-export function renderDemandForecastReport(user, spec, buckets, totalOpportunities) {
-  const label = getEntityLabel(spec, true) || 'Opportunities';
-  const valueFieldDef = spec.fields?.value || { type: 'currency' };
-  const totalProjected = buckets.reduce((sum, [, v]) => sum + v, 0);
-  const notice = !buckets.length
-    ? `<div class="report-notice">No open opportunities with a future expected close date</div>`
-    : '';
-  const content = `<div class="page-header">
-      <div><h1 class="page-title">${esc(label)}: Demand Forecast</h1><p class="page-subtitle">${totalOpportunities} total opportunities, ${esc(formatSumValue(totalProjected, valueFieldDef))} projected across ${buckets.length} future month${buckets.length === 1 ? '' : 's'}</p></div>
-    </div>
-    ${notice}
-    ${sumBarChart(buckets, valueFieldDef)}`;
-  return page(user, `Demand Forecast | Thatcher`, null, content);
-}
+import { page } from '@/ui/layout.js';
+import { esc } from '@/ui/render-helpers.js';
+import { emptyState } from '@/ui/format-helpers.js';
+import { getEntityLabel } from '@/config/spec-helpers.js';
+
+const MAX_BUCKETS = 15;
+
+function bucketLabel(spec, field, rawValue) {
+  if (rawValue === null || rawValue === undefined || rawValue === '') return '(empty)';
+  const fieldDef = spec.fields?.[field];
+  if (fieldDef?.type === 'enum' && Array.isArray(fieldDef.options)) {
+    const opt = fieldDef.options.find(o => String(o.value ?? o) === String(rawValue));
+    return opt ? String(opt.label || opt.value || opt) : String(rawValue);
+  }
+  return String(rawValue);
+}
+
+export function countByField(records, spec, field) {
+  const counts = new Map();
+  for (const r of records) {
+    const label = bucketLabel(spec, field, r[field]);
+    counts.set(label, (counts.get(label) || 0) + 1);
+  }
+  const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+  if (sorted.length <= MAX_BUCKETS) return sorted;
+  const top = sorted.slice(0, MAX_BUCKETS - 1);
+  const otherCount = sorted.slice(MAX_BUCKETS - 1).reduce((sum, [, c]) => sum + c, 0);
+  return [...top, ['(other)', otherCount]];
+}
+
+function barChart(buckets) {
+  if (!buckets.length) return emptyState('No data to report on', 'bar-chart');
+  const max = Math.max(...buckets.map(([, c]) => c), 1);
+  const rows = buckets.map(([label, count]) => {
+    const pct = Math.round((count / max) * 100);
+    return `<div class="report-bar-row" style="display:flex;align-items:center;gap:12px;margin-bottom:8px">
+      <div style="min-width:140px;max-width:220px;font-size:13px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="${esc(label)}">${esc(label)}</div>
+      <div style="flex:1;height:20px;background:var(--color-border,#eee);border-radius:4px;overflow:hidden">
+        <div style="height:100%;width:${pct}%;background:var(--color-primary,#3b82f6);border-radius:4px"></div>
+      </div>
+      <div style="min-width:40px;text-align:right;font-size:13px;font-weight:600">${count}</div>
+    </div>`;
+  }).join('');
+  return `<div class="report-bar-chart">${rows}</div>`;
+}
+
+function bucketDateKey(dateValue, granularity) {
+  if (dateValue === null || dateValue === undefined || dateValue === '') return null;
+  const num = Number(dateValue);
+  const d = !isNaN(num) && num > 0 ? new Date(num * 1000) : new Date(dateValue);
+  if (isNaN(d.getTime())) return null;
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  if (granularity === 'day') return `${y}-${m}-${day}`;
+  if (granularity === 'week') {
+    const onejan = new Date(y, 0, 1);
+    const week = Math.ceil((((d - onejan) / 86400000) + onejan.getDay() + 1) / 7);
+    return `${y}-W${String(week).padStart(2, '0')}`;
+  }
+  return `${y}-${m}`;
+}
+
+export function countOverTime(records, dateField, granularity = 'month') {
+  const counts = new Map();
+  let unresolved = 0;
+  for (const r of records) {
+    const key = bucketDateKey(r[dateField], granularity);
+    if (key === null) { unresolved++; continue; }
+    counts.set(key, (counts.get(key) || 0) + 1);
+  }
+  const sorted = [...counts.entries()].sort((a, b) => a[0].localeCompare(b[0]));
+  return { buckets: sorted.length > MAX_BUCKETS ? sorted.slice(-MAX_BUCKETS) : sorted, unresolved, truncated: sorted.length > MAX_BUCKETS };
+}
+
+export function renderCountByFieldReport(user, entityName, spec, records, field) {
+  const label = getEntityLabel(spec, true) || entityName;
+  const fieldDef = spec.fields?.[field];
+  if (!fieldDef) {
+    return page(user, `${label} | Report`, null,
+      `<div class="page-header"><h1 class="page-title">${esc(label)}</h1></div>
+      <div class="report-empty-state">Unknown field "${esc(field)}" for this entity.</div>`);
+  }
+  const buckets = countByField(records, spec, field);
+  const content = `<div class="page-header">
+      <div><h1 class="page-title">${esc(label)} by ${esc(fieldDef.label || field)}</h1><p class="page-subtitle">${records.length} total records</p></div>
+    </div>
+    ${barChart(buckets)}`;
+  return page(user, `${label} Report | Thatcher`, null, content);
+}
+
+export function sumByField(records, spec, field, groupBy) {
+  const sums = new Map();
+  for (const r of records) {
+    const raw = r[field];
+    const num = typeof raw === 'string' ? Number(raw) : raw;
+    if (typeof num !== 'number' || isNaN(num)) continue;
+    const label = bucketLabel(spec, groupBy, r[groupBy]);
+    sums.set(label, (sums.get(label) || 0) + num);
+  }
+  const sorted = [...sums.entries()].sort((a, b) => b[1] - a[1]);
+  if (sorted.length <= MAX_BUCKETS) return sorted;
+  const top = sorted.slice(0, MAX_BUCKETS - 1);
+  const otherSum = sorted.slice(MAX_BUCKETS - 1).reduce((sum, [, v]) => sum + v, 0);
+  return [...top, ['(other)', otherSum]];
+}
+
+function formatSumValue(value, fieldDef) {
+  if (fieldDef?.type === 'currency') return (fieldDef.currency_symbol || '$') + (value / 100).toFixed(2);
+  return String(Math.round(value * 100) / 100);
+}
+
+function sumBarChart(buckets, fieldDef) {
+  if (!buckets.length) return emptyState('No data to report on', 'bar-chart');
+  const max = Math.max(...buckets.map(([, v]) => Math.abs(v)), 1);
+  const rows = buckets.map(([label, value]) => {
+    const pct = Math.round((Math.abs(value) / max) * 100);
+    return `<div class="report-bar-row" style="display:flex;align-items:center;gap:12px;margin-bottom:8px">
+      <div style="min-width:140px;max-width:220px;font-size:13px;overflow:hidden;text-overflow:ellipsis;white-space:nowrap" title="${esc(label)}">${esc(label)}</div>
+      <div style="flex:1;height:20px;background:var(--color-border,#eee);border-radius:4px;overflow:hidden">
+        <div style="height:100%;width:${pct}%;background:var(--color-primary,#3b82f6);border-radius:4px"></div>
+      </div>
+      <div style="min-width:80px;text-align:right;font-size:13px;font-weight:600">${esc(formatSumValue(value, fieldDef))}</div>
+    </div>`;
+  }).join('');
+  return `<div class="report-bar-chart">${rows}</div>`;
+}
+
+export function renderSumByFieldReport(user, entityName, spec, records, field, groupBy) {
+  const label = getEntityLabel(spec, true) || entityName;
+  const fieldDef = spec.fields?.[field];
+  const groupByDef = spec.fields?.[groupBy];
+  if (!fieldDef || !groupByDef) {
+    return page(user, `${label} | Report`, null,
+      `<div class="page-header"><h1 class="page-title">${esc(label)}</h1></div>
+      <div class="report-empty-state">Unknown field "${esc(!fieldDef ? field : groupBy)}" for this entity.</div>`);
+  }
+  const buckets = sumByField(records, spec, field, groupBy);
+  const content = `<div class="page-header">
+      <div><h1 class="page-title">${esc(label)}: ${esc(fieldDef.label || field)} by ${esc(groupByDef.label || groupBy)}</h1><p class="page-subtitle">${records.length} total records</p></div>
+    </div>
+    ${sumBarChart(buckets, fieldDef)}`;
+  return page(user, `${label} Report | Thatcher`, null, content);
+}
+
+// Cross-entity rollup: entity A's records are grouped by a field on related
+// entity B, joined through A's ref field. relatedRecords must already be the
+// CALLER's row/org-scoped list() result for B -- this function only joins
+// and counts, it enforces no access itself (the access decision -- can this
+// user list B at all -- is made by the caller before relatedRecords exists).
+export function rollupByRelatedField(records, refField, relatedRecords, relatedSpec, rollupField) {
+  const relatedById = new Map(relatedRecords.map(r => [String(r.id), r]));
+  const counts = new Map();
+  let unmatched = 0;
+  for (const r of records) {
+    const refId = r[refField];
+    const related = refId != null ? relatedById.get(String(refId)) : null;
+    if (!related) { unmatched++; continue; }
+    const label = bucketLabel(relatedSpec, rollupField, related[rollupField]);
+    counts.set(label, (counts.get(label) || 0) + 1);
+  }
+  const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]);
+  return { buckets: sorted.length > MAX_BUCKETS ? sorted.slice(0, MAX_BUCKETS) : sorted, unmatched };
+}
+
+export function renderRollupReport(user, entityName, spec, records, refField, relatedEntity, relatedSpec, relatedRecords, rollupField) {
+  const label = getEntityLabel(spec, true) || entityName;
+  const relatedLabel = getEntityLabel(relatedSpec, true) || relatedEntity;
+  const rollupFieldDef = relatedSpec?.fields?.[rollupField];
+  if (!spec.fields?.[refField] || !rollupFieldDef) {
+    return page(user, `${label} | Report`, null,
+      `<div class="page-header"><h1 class="page-title">${esc(label)}</h1></div>
+      <div class="report-empty-state">Unknown field for this rollup.</div>`);
+  }
+  const { buckets, unmatched } = rollupByRelatedField(records, refField, relatedRecords, relatedSpec, rollupField);
+  const notice = unmatched
+    ? `<div class="report-notice">${unmatched} record${unmatched === 1 ? '' : 's'} without a resolvable ${esc(relatedLabel)} excluded</div>`
+    : '';
+  const content = `<div class="page-header">
+      <div><h1 class="page-title">${esc(label)} by ${esc(relatedLabel)}.${esc(rollupFieldDef.label || rollupField)}</h1><p class="page-subtitle">${records.length} total records</p></div>
+    </div>
+    ${notice}
+    ${barChart(buckets)}`;
+  return page(user, `${label} Report | Thatcher`, null, content);
+}
+
+export function renderCountOverTimeReport(user, entityName, spec, records, dateField, granularity) {
+  const label = getEntityLabel(spec, true) || entityName;
+  const fieldDef = spec.fields?.[dateField];
+  if (!fieldDef) {
+    return page(user, `${label} | Report`, null,
+      `<div class="page-header"><h1 class="page-title">${esc(label)}</h1></div>
+      <div class="report-empty-state">Unknown date field "${esc(dateField)}" for this entity.</div>`);
+  }
+  const { buckets, unresolved, truncated } = countOverTime(records, dateField, granularity);
+  const notice = unresolved
+    ? `<div class="report-notice">${unresolved} record${unresolved === 1 ? '' : 's'} without a resolvable date excluded</div>`
+    : '';
+  const truncatedNotice = truncated
+    ? `<div class="report-notice">Showing the most recent ${buckets.length} periods only</div>`
+    : '';
+  const content = `<div class="page-header">
+      <div><h1 class="page-title">${esc(label)} over time</h1><p class="page-subtitle">${records.length} total records, grouped by ${esc(granularity)}</p></div>
+    </div>
+    ${notice}${truncatedNotice}
+    ${barChart(buckets)}`;
+  return page(user, `${label} Report | Thatcher`, null, content);
+}
+
+// One table per-product rather than a bar chart: unlike count-by-field/
+// sum-by-field's single grouped metric, a forecast is inherently multiple
+// values per row (stock, consumption rate, days-out, reorder date) -- a bar
+// chart of any single one of those would discard the others, so a table is
+// the correct shape here, reusing the same page()/esc() rendering discipline
+// as every other report rather than inventing a new chart type.
+export function renderInventoryForecastReport(user, spec, forecastRows) {
+  const label = getEntityLabel(spec, true) || 'Products';
+  const rows = forecastRows.map(p => {
+    const daysLabel = p.days_until_stockout == null ? 'Unknown' : String(Math.round(p.days_until_stockout))
+    const reorderLabel = p.reorder_date == null ? '-' : new Date(p.reorder_date * 1000).toISOString().slice(0, 10)
+    const rowCls = p.reorder_due ? 'style="background:var(--color-danger-bg,#fee2e2)"' : ''
+    return `<tr ${rowCls}>
+      <td>${esc(p.name || p.id)}</td>
+      <td>${esc(String(p.current_stock))}</td>
+      <td>${esc((p.avg_daily_consumption || 0).toFixed(2))}</td>
+      <td>${esc(daysLabel)}</td>
+      <td>${esc(reorderLabel)}${p.reorder_due ? ' <span class="pill pill-danger">Reorder Now</span>' : ''}</td>
+    </tr>`;
+  }).join('') || emptyState('No products to forecast', 'bar-chart');
+
+  const content = `<div class="page-header">
+      <div><h1 class="page-title">${esc(label)}: Inventory Forecast</h1><p class="page-subtitle">${forecastRows.length} products</p></div>
+    </div>
+    <div class="table-wrap"><table class="data-table">
+      <thead><tr><th>Product</th><th>Current Stock</th><th>Avg Daily Use</th><th>Days Until Stockout</th><th>Suggested Reorder</th></tr></thead>
+      <tbody>${rows}</tbody>
+    </table></div>`;
+  return page(user, `Inventory Forecast | Thatcher`, null, content);
+}
+
+// Reuses sumBarChart (already built for sum-by-field's currency-aware bar
+// rendering) rather than inventing a third chart type -- a demand-by-month
+// bucket is the exact same [label, numericValue] shape sum-by-field already
+// renders, just currency-formatted since weighted_value derives from a
+// currency field.
+// Two-dimensional cross-tab: row_field x col_field, cell = aggregated
+// value_field. Distinct from countByField/sumByField (single-dimension
+// group-bys) -- this is the only report shape that can answer "how does X
+// break down by Y AND Z simultaneously". Both axes independently collapse
+// past MAX_BUCKETS into an '(other)' bucket the same way countByField does,
+// so a high-cardinality field on either axis can't blow up the table.
+const PIVOT_AGGREGATORS = {
+  sum: (values) => values.reduce((a, b) => a + b, 0),
+  count: (values) => values.length,
+  avg: (values) => values.length ? values.reduce((a, b) => a + b, 0) / values.length : 0,
+};
+
+function topBucketLabels(records, spec, field) {
+  const counts = new Map();
+  for (const r of records) {
+    const label = bucketLabel(spec, field, r[field]);
+    counts.set(label, (counts.get(label) || 0) + 1);
+  }
+  const sorted = [...counts.entries()].sort((a, b) => b[1] - a[1]).map(([label]) => label);
+  if (sorted.length <= MAX_BUCKETS) return new Set(sorted);
+  return new Set(sorted.slice(0, MAX_BUCKETS - 1));
+}
+
+export function pivotByFields(records, spec, rowField, colField, valueField, agg = 'count') {
+  const aggregator = PIVOT_AGGREGATORS[agg] || PIVOT_AGGREGATORS.count;
+  const rowKeep = topBucketLabels(records, spec, rowField);
+  const colKeep = topBucketLabels(records, spec, colField);
+  const cellValues = new Map();
+  const rowLabels = new Set();
+  const colLabels = new Set();
+
+  for (const r of records) {
+    const rawRow = bucketLabel(spec, rowField, r[rowField]);
+    const rawCol = bucketLabel(spec, colField, r[colField]);
+    const rowLabel = rowKeep.has(rawRow) ? rawRow : '(other)';
+    const colLabel = colKeep.has(rawCol) ? rawCol : '(other)';
+    rowLabels.add(rowLabel);
+    colLabels.add(colLabel);
+    const key = rowLabel + '' + colLabel;
+    const raw = agg === 'count' ? 1 : (typeof r[valueField] === 'string' ? Number(r[valueField]) : r[valueField]);
+    if (agg !== 'count' && (typeof raw !== 'number' || isNaN(raw))) continue;
+    if (!cellValues.has(key)) cellValues.set(key, []);
+    cellValues.get(key).push(agg === 'count' ? 1 : raw);
+  }
+
+  const rows = [...rowLabels].sort((a, b) => a === '(other)' ? 1 : b === '(other)' ? -1 : a.localeCompare(b));
+  const cols = [...colLabels].sort((a, b) => a === '(other)' ? 1 : b === '(other)' ? -1 : a.localeCompare(b));
+  const cells = rows.map(rowLabel =>
+    cols.map(colLabel => {
+      const values = cellValues.get(rowLabel + '' + colLabel);
+      return values ? aggregator(values) : 0;
+    })
+  );
+
+  return { rows, cols, cells };
+}
+
+export function renderPivotReport(user, entityName, spec, records, rowField, colField, valueField, agg) {
+  const label = getEntityLabel(spec, true) || entityName;
+  const rowFieldDef = spec.fields?.[rowField];
+  const colFieldDef = spec.fields?.[colField];
+  const validAgg = PIVOT_AGGREGATORS[agg] ? agg : 'count';
+  const valueFieldDef = validAgg === 'count' ? null : spec.fields?.[valueField];
+  if (!rowFieldDef || !colFieldDef || (validAgg !== 'count' && !valueFieldDef)) {
+    const badField = !rowFieldDef ? rowField : !colFieldDef ? colField : valueField;
+    return page(user, `${label} | Report`, null,
+      `<div class="page-header"><h1 class="page-title">${esc(label)}</h1></div>
+      <div class="report-empty-state">Unknown field "${esc(badField)}" for this entity.</div>`);
+  }
+  const { rows, cols, cells } = pivotByFields(records, spec, rowField, colField, valueField, validAgg);
+  const formatCell = (v) => validAgg === 'avg' ? String(Math.round(v * 100) / 100) : (valueFieldDef ? formatSumValue(v, valueFieldDef) : String(v));
+  const headerCells = cols.map(c => `<th>${esc(c)}</th>`).join('');
+  const bodyRows = rows.map((r, i) => {
+    const dataCells = cells[i].map(v => `<td style="text-align:right">${esc(formatCell(v))}</td>`).join('');
+    return `<tr><td>${esc(r)}</td>${dataCells}</tr>`;
+  }).join('') || emptyState('No data to report on', 'bar-chart');
+  const content = `<div class="page-header">
+      <div><h1 class="page-title">${esc(label)}: ${esc(rowFieldDef.label || rowField)} &times; ${esc(colFieldDef.label || colField)} (${esc(validAgg)}${valueFieldDef ? ' of ' + esc(valueFieldDef.label || valueField) : ''})</h1><p class="page-subtitle">${records.length} total records</p></div>
+    </div>
+    <div class="table-wrap"><table class="data-table">
+      <thead><tr><th></th>${headerCells}</tr></thead>
+      <tbody>${bodyRows}</tbody>
+    </table></div>`;
+  return page(user, `${label} Report | Thatcher`, null, content);
+}
+
+export function renderDemandForecastReport(user, spec, buckets, totalOpportunities) {
+  const label = getEntityLabel(spec, true) || 'Opportunities';
+  const valueFieldDef = spec.fields?.value || { type: 'currency' };
+  const totalProjected = buckets.reduce((sum, [, v]) => sum + v, 0);
+  const notice = !buckets.length
+    ? `<div class="report-notice">No open opportunities with a future expected close date</div>`
+    : '';
+  const content = `<div class="page-header">
+      <div><h1 class="page-title">${esc(label)}: Demand Forecast</h1><p class="page-subtitle">${totalOpportunities} total opportunities, ${esc(formatSumValue(totalProjected, valueFieldDef))} projected across ${buckets.length} future month${buckets.length === 1 ? '' : 's'}</p></div>
+    </div>
+    ${notice}
+    ${sumBarChart(buckets, valueFieldDef)}`;
+  return page(user, `Demand Forecast | Thatcher`, null, content);
+}