thatcher 1.0.88 → 1.0.90

package/package.json

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

package/src/lib/config-generator-engine.js

@@ -277,6 +277,37 @@ function withResourceManagementDefaults(masterConfig) {
   return changed ? { ...masterConfig, entities } : masterConfig;
 }
 
+// Generic outbound CRM-sync connector config, not a bespoke Salesforce/HubSpot
+// integration -- provider/base_url/entity_mappings make it configurable to
+// any downstream system's sync endpoint. organization_id is an EXPLICIT
+// manually-defined field despite system_entity:true (same precedent as
+// USER_ORGANIZATION_ENTITY_DEFAULT above) because integration credentials
+// leaking cross-org via the system_entity multi-tenancy exemption would be a
+// real vulnerability, not the usual global-by-design system entity case.
+const INTEGRATION_CONNECTION_ENTITY_DEFAULT = {
+  label: 'Integration Connection',
+  label_plural: 'Integration Connections',
+  system_entity: true,
+  fields: {
+    organization_id: { type: 'ref', ref: 'organization', label: 'Organization' },
+    provider: { type: 'text', required: true, label: 'Provider' },
+    base_url: { type: 'text', required: true, label: 'Base URL' },
+    auth_type: { type: 'enum', required: true, label: 'Auth Type', options: [{ value: 'api_key', label: 'API Key' }, { value: 'oauth_token', label: 'OAuth Token' }] },
+    credential: { type: 'text', required: true, label: 'Credential', encrypted: true },
+    entity_mappings: { type: 'json', label: 'Entity Mappings' },
+    sync_direction: { type: 'enum', required: true, default: 'outbound', label: 'Sync Direction', options: [{ value: 'outbound', label: 'Outbound' }, { value: 'inbound', label: 'Inbound' }, { value: 'bidirectional', label: 'Bidirectional' }] },
+    enabled: { type: 'bool', default: true, label: 'Enabled' },
+    last_synced_at: { type: 'int', readonly: true, label: 'Last Synced At' },
+  },
+};
+
+function withIntegrationDefaults(masterConfig) {
+  const entities = { ...(masterConfig.entities || {}) };
+  let changed = false;
+  if (!entities.integration_connection) { entities.integration_connection = INTEGRATION_CONNECTION_ENTITY_DEFAULT; changed = true; }
+  return changed ? { ...masterConfig, entities } : masterConfig;
+}
+
 const CUSTOM_ENTITY_DEF_ENTITY_DEFAULT = {
   label: 'Custom Entity Definition',
   label_plural: 'Custom Entity Definitions',
@@ -398,7 +429,7 @@ function withContractDefaults(masterConfig) {
 export class ConfigGeneratorEngine {
   constructor(masterConfig) {
     if (!masterConfig) throw new Error('[ConfigGeneratorEngine] masterConfig is required');
-    this.masterConfig = deepFreeze(withCustomEntityDefaults(withResourceManagementDefaults(withContractDefaults(withTimeTrackingDefaults(withInventoryDefaults(withProjectDefaults(withCrmDefaults(withWebhookDefaults(withMultiTenancyDefaults(masterConfig))))))))));
+    this.masterConfig = deepFreeze(withCustomEntityDefaults(withIntegrationDefaults(withResourceManagementDefaults(withContractDefaults(withTimeTrackingDefaults(withInventoryDefaults(withProjectDefaults(withCrmDefaults(withWebhookDefaults(withMultiTenancyDefaults(masterConfig)))))))))));
     this.specCache = new LRUCache(100);
     this.debugMode = false;
     this._plugins = new Map();

package/src/lib/integration-sync-engine.js

@@ -0,0 +1,82 @@
+import { list } from './busybase/store.js';
+import { validateWebhookUrl } from './webhook-engine.js';
+import { createLogger } from './logger.js';
+
+const log = createLogger('[IntegrationSync]');
+const REQUEST_TIMEOUT_MS = 15000;
+
+// Records changed since the connection's last sync, read through the SAME
+// {user}-scoped list() every interactive read path uses -- a sync job cannot
+// reach records outside its owner's org just because it runs unattended.
+export async function getRecordsChangedSince(entityName, sinceTs, user) {
+  const records = await list(entityName, {}, { user });
+  return records.filter(r => (r.updated_at || 0) > (sinceTs || 0));
+}
+
+function authHeader(connection) {
+  if (connection.auth_type === 'oauth_token') return { Authorization: `Bearer ${connection.credential}` };
+  return { 'X-Api-Key': connection.credential };
+}
+
+function mapRecordFields(record, mapping) {
+  if (!mapping || typeof mapping !== 'object') return record;
+  const mapped = {};
+  for (const [localField, remoteField] of Object.entries(mapping)) {
+    mapped[remoteField] = record[localField];
+  }
+  return mapped;
+}
+
+// connection.credential arrives here already decrypted (store.js decrypts on
+// every list()/get()) -- this function only reads it into the auth header,
+// never logs or persists it further.
+export async function syncRecordToIntegration(connection, entityName, record) {
+  const mappings = typeof connection.entity_mappings === 'string'
+    ? JSON.parse(connection.entity_mappings || '{}')
+    : (connection.entity_mappings || {});
+  const entityMapping = mappings[entityName];
+  if (!entityMapping) return { success: false, error: `No entity_mapping for "${entityName}"` };
+
+  const targetUrl = `${connection.base_url.replace(/\/$/, '')}/api/sync/${entityMapping}`;
+  // Same SSRF guard webhook-engine.js's dispatchWebhooks applies before any
+  // outbound fetch -- reused verbatim, not reimplemented, so a connection
+  // pointed at a private/loopback/link-local target is rejected here, before
+  // any network call is made.
+  const validation = await validateWebhookUrl(targetUrl);
+  if (!validation.ok) {
+    log.error(`integration_connection ${connection.id} target rejected: ${validation.error}`);
+    return { success: false, error: validation.error };
+  }
+
+  const payload = mapRecordFields(record, mappings[`${entityName}_fields`] || mappings.fields);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+  try {
+    const res = await fetch(targetUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...authHeader(connection) },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    return { success: res.ok, statusCode: res.status, error: res.ok ? null : `HTTP ${res.status}` };
+  } catch (e) {
+    return { success: false, statusCode: 0, error: e.message };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function syncConnection(connection, user) {
+  const mappings = typeof connection.entity_mappings === 'string'
+    ? JSON.parse(connection.entity_mappings || '{}')
+    : (connection.entity_mappings || {});
+  const entityNames = Object.keys(mappings).filter(k => !k.endsWith('_fields') && k !== 'fields');
+  const results = [];
+  for (const entityName of entityNames) {
+    const changed = await getRecordsChangedSince(entityName, connection.last_synced_at, user);
+    for (const record of changed) {
+      results.push({ entity: entityName, id: record.id, ...(await syncRecordToIntegration(connection, entityName, record)) });
+    }
+  }
+  return results;
+}

package/src/lib/scheduler-engine.js

@@ -47,6 +47,26 @@ async function runOneJob(job, nowTs) {
       targets = targets.filter(c => isWithinNoticeWindow(c, nowTs));
     }
 
+    // integration_sync is a distinct action shape from bulk field-updates --
+    // it fans out to an external system per connection rather than mutating
+    // Thatcher records, so it bypasses runBulkOperation entirely but still
+    // rides the SAME scheduled_job table/timer, not a new cron mechanism.
+    if (job.entity === 'integration_connection' && action?.type === 'integration_sync') {
+      const { syncConnection } = await import('./integration-sync-engine.js');
+      const syncResults = [];
+      for (const connection of targets) {
+        if (!connection.enabled) continue;
+        const results = await syncConnection(connection, owner);
+        syncResults.push(...results);
+        await update('integration_connection', connection.id, { last_synced_at: nowTs });
+      }
+      const nextRunAt = nowTs + job.interval_minutes * 60;
+      await update('scheduled_job', job.id, { last_run_at: nowTs, next_run_at: nextRunAt });
+      const succeeded = syncResults.filter(r => r.success).length;
+      log.info(`Job "${job.name}" ran: ${succeeded}/${syncResults.length} synced`);
+      return { job_id: job.id, ok: true, total: syncResults.length, succeeded, failed: syncResults.length - succeeded, results: syncResults };
+    }
+
     const ids = targets.map(r => r.id);
 
     let result = { ok: true, total: 0, succeeded: 0, failed: 0, results: [] };

package/src/server/server.js

@@ -493,6 +493,14 @@ async function handleGenericCrud(req, res, entity, id, action, thatcher, configE
           return;
         }
         permissionService.enforceEditPermissions(user, spec, body);
+        // The edit form renders encrypted:true fields blank with a "leave
+        // blank to keep unchanged" note -- a blank submission must not
+        // overwrite the stored secret, since update() spreads body directly
+        // into the patch and encryptFields only skips ABSENT keys, not
+        // empty-string values actually present in the object.
+        for (const [fieldKey, fieldDef] of Object.entries(spec.fields || {})) {
+          if (fieldDef.encrypted && body[fieldKey] === '') delete body[fieldKey];
+        }
         {
           // validateUpdate is the authoritative server-side check for both
           // generic field-type constraints AND entity-specific business

package/src/ui/entity-renderer.js

@@ -65,6 +65,11 @@ function roleLabel(r) {
 }
 
 function formatFieldValue(k, v, entityName, f) {
+  // encrypted:true fields decrypt on every list()/get() read (store.js) so
+  // the plaintext DOES reach this renderer -- redact here, the display
+  // boundary, rather than in store.js which legitimately serves the real
+  // value to business logic that needs it.
+  if (f?.encrypted) return v ? '<span class="pill pill-neutral">••••••••</span>' : '-'
   if (entityName === 'user' && k === 'role') return `<span class="pill pill-neutral">${roleLabel(v)}</span>`
   if (entityName === 'user' && k === 'status') {
     const cls = v === 'active' ? 'pill-success' : v === 'deleted' ? 'pill-danger' : 'pill-neutral'
@@ -346,6 +351,10 @@ export function renderEntityForm(entityName, item, spec, user, isNew = false, re
       const existingNote = existing?.filename ? `<div style="font-size:0.8rem;color:var(--color-text-muted)" data-existing-file="${k}">Current: ${esc(existing.filename)}</div>` : ''
       return `<div class="form-field">${lbl(k,f,f.required)}<input type="file" id="field-${k}" data-attachment="${k}" class="form-input" ${existing ? '' : req}/>${existingNote}<input type="hidden" id="field-${k}-value" name="${k}" value="${existing ? esc(JSON.stringify(existing)) : ''}"/></div>`
     }
+    if (f.encrypted) {
+      const encNote = val ? `<div style="font-size:0.8rem;color:var(--color-text-muted)">Currently set. Leave blank to keep unchanged.</div>` : ''
+      return `<div class="form-field">${lbl(k,f,f.required)}<input type="password" id="field-${k}" name="${k}" value="" class="form-input" autocomplete="new-password" placeholder="Enter ${esc((f.label||k).toLowerCase())}"/>${encNote}</div>`
+    }
     return `<div class="form-field">${lbl(k,f,f.required)}<input type="${type}" id="field-${k}" name="${k}" value="${esc(val)}" class="form-input" ${req} ${placeholder}/></div>`
   }).join('\n')
 

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';
@@ -370,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);
+}