@arcforgelabs/flow 2026.10.30 → 2026.10.32-beta.1

package/server/core/line-mapping.js

@@ -1,5 +1,5 @@
 import { and, asc, eq, isNull, sql } from 'drizzle-orm';
-import { LINE_MAPPING_KINDS, lineMappings, pipelineCursors, priceItems } from '../db/schema.js';
+import { LINE_MAPPING_KINDS, lineMappings, pipelineCursors, priceItemLinks, priceItems } from '../db/schema.js';
 import { FlowError, notFound } from './errors.js';
 
 // Line mapping (docs/LINE_MAPPING.md): how each line a work system reports
@@ -8,6 +8,10 @@ import { FlowError, notFound } from './errors.js';
 // step reads either the lab's price list or the lab's own mapping rows, so no
 // lab's labels or codes are fixed in Flow's code.
 //
+// Before the steps, a line whose code is a linked product of its work system
+// (the price list's links, server/core/price-list.js) takes that price item.
+// A link is a person's or an exact code's choice, so it always goes first.
+//
 //   same_code           the line's own code is a price item code
 //   account             an account row: a line with no price item (a surcharge)
 //   saved               a row a person saved for this label at this price
@@ -20,7 +24,8 @@ import { FlowError, notFound } from './errors.js';
 //
 // A mapped line keeps the work system's amount and tax flag; the price item
 // gives its code, its text and, when the work system gave none, its price and
-// tax. A line no step answers keeps no code, so the ledger holds the job.
+// tax. With `linePrice: 'list'` the price item's price wins instead. A line
+// no step answers keeps no code, so the ledger holds the job.
 
 export const STEPS = Object.freeze([
   'same_code', 'account', 'saved', 'catalog_name', 'price_alias', 'catalog_name_price', 'catalog_score', 'alias',
@@ -36,7 +41,10 @@ export const STEP_LABELS = Object.freeze({
   alias: 'Label',
 });
 export const ZERO_LINES = Object.freeze(['keep', 'drop']);
-export const MAPPING_DEFAULTS = Object.freeze({ steps: [...STEPS], zeroLines: 'keep' });
+// Where a mapped line's price comes from: the work system's amount (as the
+// earlier app did), or the lab's own price list.
+export const LINE_PRICES = Object.freeze(['work', 'list']);
+export const MAPPING_DEFAULTS = Object.freeze({ steps: [...STEPS], zeroLines: 'keep', linePrice: 'work' });
 
 const SCORE_MIN = 16;
 const SCORE_GAP = 8;
@@ -96,8 +104,16 @@ export function nameScore(item, { exact, lookup, original }) {
 }
 
 // The lab's price list and mapping rows, indexed once for a run.
-export function mappingContext({ items = [], mappings = [], config = MAPPING_DEFAULTS } = {}) {
+export function mappingContext({ items = [], mappings = [], links = [], config = MAPPING_DEFAULTS } = {}) {
   const live = items.filter((i) => !i.archivedAt);
+  // A linked work system code: its price item, by the code in lookup form.
+  const byId = new Map(live.map((i) => [i.id, i]));
+  const byLinkedCode = new Map();
+  for (const link of links) {
+    const item = byId.get(link.priceItemId);
+    const code = lineText(link.externalCode);
+    if (item && code && !byLinkedCode.has(code)) byLinkedCode.set(code, item);
+  }
   const byCode = new Map(live.map((i) => [i.code, i]));
   const byCodeText = new Map(live.map((i) => [lineText(i.code), i]));
   const byText = new Map();
@@ -113,7 +129,7 @@ export function mappingContext({ items = [], mappings = [], config = MAPPING_DEF
   }
   const rows = mappings.filter((m) => m.enabled !== false);
   const rowsOf = (kind) => rows.filter((m) => m.kind === kind);
-  return { byCode, byCodeText, byText, byPrice, rowsOf, config: { ...MAPPING_DEFAULTS, ...config } };
+  return { byCode, byCodeText, byText, byPrice, byLinkedCode, rowsOf, config: { ...MAPPING_DEFAULTS, ...config } };
 }
 
 const rowMatches = (row, lookup) => (row.match === 'starts_with' ? lookup === row.label || lookup.startsWith(`${row.label} `) : lookup === row.label);
@@ -139,7 +155,7 @@ export function mapLine(line, context) {
     accountCode: null,
     description: (item.description || item.name || original).trim(),
     quantity,
-    unitAmountCents: price ?? item.unitAmountCents,
+    unitAmountCents: config.linePrice === 'list' ? item.unitAmountCents : (price ?? item.unitAmountCents),
     taxCode: taxCode ?? line.taxCode ?? item.taxCode,
     mappedBy: step,
   });
@@ -149,6 +165,9 @@ export function mapLine(line, context) {
   };
   const unmapped = (reason) => ({ ...base, itemCode: null, accountCode: null, mappedBy: null, unmapped: reason });
 
+  const linked = line.itemCode ? context.byLinkedCode?.get(lineText(line.itemCode)) : null;
+  if (linked) return toItem(linked, 'linked');
+
   for (const step of config.steps) {
     switch (step) {
       case 'same_code': {
@@ -229,6 +248,10 @@ function readConfig(raw = {}) {
     if (!ZERO_LINES.includes(raw.zeroLines)) throw invalid(`zeroLines must be one of ${ZERO_LINES.join(', ')}`);
     out.zeroLines = raw.zeroLines;
   }
+  if ('linePrice' in raw) {
+    if (!LINE_PRICES.includes(raw.linePrice)) throw invalid(`linePrice must be one of ${LINE_PRICES.join(', ')}`);
+    out.linePrice = raw.linePrice;
+  }
   return out;
 }
 export { readConfig as readMappingConfig };
@@ -327,11 +350,14 @@ export async function deleteMapping(db, organisationId, id) {
   await remapJobs(db, organisationId);
 }
 
-// The price list and mapping rows for a pipeline run.
-export async function loadMappingContext(db, organisationId, config) {
-  const [items, mappings] = await Promise.all([
+// The price list, mapping rows and `system`'s product links for a pipeline run.
+export async function loadMappingContext(db, organisationId, config, { system = null } = {}) {
+  const [items, mappings, links] = await Promise.all([
     db.select().from(priceItems).where(and(eq(priceItems.organisationId, organisationId), isNull(priceItems.archivedAt))),
     db.select().from(lineMappings).where(eq(lineMappings.organisationId, organisationId)),
+    system
+      ? db.select().from(priceItemLinks).where(and(eq(priceItemLinks.organisationId, organisationId), eq(priceItemLinks.system, system)))
+      : [],
   ]);
-  return mappingContext({ items, mappings, config });
+  return mappingContext({ items, mappings, links, config });
 }

package/server/core/pipeline.js

@@ -8,7 +8,9 @@ import { listAutomations, runAutomations } from './automations.js';
 import { readInvoicingSettings } from './invoicing-rules.js';
 import { observeJob, recordAccountingEvidence, setHold } from './ledger.js';
 import { loadMappingContext, mapLines } from './line-mapping.js';
+import { checkPrices, readCatalogues } from './price-list.js';
 import { linkRecord, priorLinkFor } from './links.js';
+import { HISTORY_ACTOR, HISTORY_HOLD_REASON, isHistoryHeld } from './history.js';
 import { deadHoldSince, deadSince, enqueueJob, runNextJob } from './queue.js';
 
 // The pipeline (docs/DATA_SPINE.md, issue 58). It joins what the integrations
@@ -138,7 +140,7 @@ export async function ingestWork(db, organisationId, { adapter, restart = false,
   const result = { observed: 0, withoutCustomer: 0, skipped: 0, sentToReview: 0, unmappedLines: 0, more: false };
   // Line mapping (line-mapping.js): each line finds its price item first.
   const mapping = (await listAutomations(db, organisationId)).find((a) => a.key === 'map_lines');
-  const context = mapping?.enabled ? await loadMappingContext(db, organisationId, mapping.config) : null;
+  const context = mapping?.enabled ? await loadMappingContext(db, organisationId, mapping.config, { system: adapter.id }) : null;
   for (let page = 0; page < pages; page += 1) {
     const { items, withdrawn, cursor: next, more } = await adapter.capabilities.pullWorkItems(cursor, { limit: 200 });
     for (const item of items) {
@@ -175,6 +177,66 @@ export async function ingestWork(db, organisationId, { adapter, restart = false,
   return result;
 }
 
+// Reads the work system's past jobs (a history import, docs/SEAZONA.md) into
+// the ledger. A job new to the ledger is held with reason `history_import`:
+// it is history, most likely invoiced long ago, so it never drafts until a
+// person releases it, and the matcher still links it to its invoice. A job
+// the ledger already has from the live feed is left as it is: its hold, ready
+// mark and invoice never change here. A held history job that only history
+// has reported takes a later import's changes.
+export async function ingestHistory(db, organisationId, { adapter, pages = WORK_PAGES }) {
+  const name = `${adapter.id}.history`;
+  let cursor = await readCursor(db, organisationId, name);
+  const links = await activeLinks(db, organisationId, { system: adapter.id, entity: 'contact' });
+  const contactOf = new Map(links.map((l) => [l.externalId, l.flowId]));
+  const result = { held: 0, updated: 0, alreadyLive: 0, skipped: 0, more: false };
+  const mapping = (await listAutomations(db, organisationId)).find((a) => a.key === 'map_lines');
+  const context = mapping?.enabled ? await loadMappingContext(db, organisationId, mapping.config) : null;
+  for (let page = 0; page < pages; page += 1) {
+    const { items, cursor: next, more } = await adapter.capabilities.pullHistoryJobs(cursor, { limit: 200 });
+    for (const item of items) {
+      const contactId = contactOf.get(String(item.clientId ?? '')) ?? null;
+      const base = { ...item.ledgerJob, actor: HISTORY_ACTOR };
+      const job = context ? { ...base, lines: mapLines(base.lines ?? [], context) } : base;
+      const [existing] = await db.select().from(billingObligations).where(and(
+        eq(billingObligations.organisationId, organisationId),
+        eq(billingObligations.sourceSystem, job.sourceSystem),
+        eq(billingObligations.sourceJobRef, job.sourceJobRef),
+      ));
+      if (existing) {
+        const [live] = existing && isHistoryHeld(existing)
+          ? await db.select({ id: obligationEvents.id }).from(obligationEvents).where(and(
+            eq(obligationEvents.organisationId, organisationId),
+            eq(obligationEvents.obligationId, existing.id),
+            inArray(obligationEvents.kind, ['observed', 'source_changed']),
+            sql`${obligationEvents.actor} <> ${HISTORY_ACTOR}`,
+          )).limit(1)
+          : [{ id: 'live' }];
+        if (live) {
+          result.alreadyLive += 1;
+          continue;
+        }
+        await observeJob(db, organisationId, { ...job, contactId: contactId ?? existing.contactId });
+        result.updated += 1;
+        continue;
+      }
+      try {
+        const row = await observeJob(db, organisationId, { ...job, contactId });
+        await setHold(db, organisationId, row.id, { holdState: 'held', reason: HISTORY_HOLD_REASON, actor: HISTORY_ACTOR });
+        result.held += 1;
+      } catch (error) {
+        if (!(error instanceof FlowError) || error.code !== 'invalid') throw error;
+        result.skipped += 1;
+      }
+    }
+    cursor = next;
+    await writeCursor(db, organisationId, name, cursor);
+    if (!more) return result;
+  }
+  result.more = true;
+  return result;
+}
+
 const day = (iso) => Date.parse(`${iso}T00:00:00Z`);
 const addDays = (iso, days) => new Date(day(iso) + days * 86_400_000).toISOString().slice(0, 10);
 const daysApart = (a, b) => Math.abs(day(a) - day(b)) / 86_400_000;
@@ -421,14 +483,24 @@ export async function runPipelineOnce(db, integrations, { now = new Date() } = {
   const summary = { organisationId };
   const [work] = integrations.with('pullWorkItems');
   const [accounting] = integrations.with('findInvoices');
+  // The price check (price-list.js) links price lists by code first, so a
+  // new product link maps the jobs read before it.
+  const priceSystems = integrations.with('listPriceItems');
+  if (priceSystems.length) {
+    summary.prices = await checkPrices(db, organisationId, { catalogues: await readCatalogues(organisationId, priceSystems) });
+  }
   if (work) {
-    let restart = false;
+    let restart = (summary.prices?.linked ?? 0) > 0;
     if (typeof work.capabilities.listCustomers === 'function') {
       summary.workCustomers = await linkCustomers(db, organisationId, { system: work.id, customers: await work.capabilities.listCustomers({ organisationId }) });
       // New customer links reach jobs read before them.
-      restart = summary.workCustomers.linked > 0;
+      restart ||= summary.workCustomers.linked > 0;
     }
     summary.work = await ingestWork(db, organisationId, { adapter: work, restart });
+    // After the live feed, so a job both report is the live one.
+    if (typeof work.capabilities.pullHistoryJobs === 'function') {
+      summary.history = await ingestHistory(db, organisationId, { adapter: work });
+    }
   }
   if (accounting) {
     if (typeof accounting.capabilities.listCustomers === 'function') {

package/server/core/price-list.js

@@ -0,0 +1,348 @@
+import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
+import { priceItemLinks, priceItems, reviewItems, TAX_CODES } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { remapJobs } from './line-mapping.js';
+import { openReview, resolveReview } from './review.js';
+
+// The price list (docs/PRICE_LIST.md). Flow's own price items are the source
+// of truth: a lab adds, changes and archives them here with no integration
+// connected. Each connected system that keeps its own price list (Xero items,
+// Seazona products) offers it through the port's `listPriceItems`, read from
+// Flow's copy, so nothing here calls another system.
+//
+// A link joins one record of a system's list to one price item:
+//   - Flow links by itself when both sides have the same code;
+//   - a person links the rest;
+//   - an accounting system (Xero) has one record per price item at most; a
+//     work system (Seazona) can link many products to one price item.
+// The price check compares each price item with its linked records. A
+// difference is an alert only (review item `price_check`): Flow never changes
+// a price on either side. "Mark resolved" accepts what the check found; the
+// same finding never opens again, a new one does.
+
+const invalid = (message) => new FlowError('invalid', message);
+const REVIEW_KIND = 'price_check';
+const MAX_ITEMS = 5000;
+const FINDING_KINDS = Object.freeze(['price', 'tax', 'missing', 'not_linked']);
+export { FINDING_KINDS };
+
+const codeKey = (value) => String(value ?? '').trim().toLowerCase();
+
+const shortText = (value, name, max, { required = false } = {}) => {
+  if (value === null || value === undefined || (typeof value === 'string' && !value.trim())) {
+    if (required) throw invalid(`${name} is required`);
+    return null;
+  }
+  if (typeof value !== 'string' || value.trim().length > max) throw invalid(`${name} must be text of ${max} characters at most`);
+  return value.trim();
+};
+
+// A price item as the API takes it. `partial` reads a change: only the fields
+// it names.
+export function readPriceItem(raw, { partial = false } = {}) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw invalid('the price item must be an object');
+  const known = ['code', 'name', 'description', 'unitAmountCents', 'taxCode', 'accountCode'];
+  const unknown = Object.keys(raw).filter((k) => !known.includes(k));
+  if (unknown.length) throw invalid(`unknown field: ${unknown[0]}`);
+  const out = {};
+  const has = (key) => !partial || key in raw;
+  if (has('code')) out.code = shortText(raw.code, 'code', 30, { required: true });
+  if (has('name')) out.name = shortText(raw.name, 'name', 200, { required: true });
+  if (has('description')) out.description = shortText(raw.description, 'description', 1000);
+  if (has('unitAmountCents')) {
+    const cents = raw.unitAmountCents;
+    if (!Number.isInteger(cents) || cents < 0 || cents > 100_000_000) throw invalid('unitAmountCents must be whole cents, 0 or more');
+    out.unitAmountCents = cents;
+  }
+  if (has('taxCode')) {
+    const taxCode = raw.taxCode ?? 'GST';
+    if (!TAX_CODES.includes(taxCode)) throw invalid(`taxCode must be one of ${TAX_CODES.join(', ')}`);
+    out.taxCode = taxCode;
+  }
+  if (has('accountCode')) out.accountCode = shortText(raw.accountCode, 'accountCode', 20);
+  return out;
+}
+
+const shapeItem = (r) => ({
+  id: r.id, code: r.code, name: r.name, description: r.description, unitAmountCents: r.unitAmountCents,
+  taxCode: r.taxCode, accountCode: r.accountCode, archivedAt: r.archivedAt, updatedAt: r.updatedAt,
+});
+
+const conflictOf = (error) => error?.code === '23505' || error?.cause?.code === '23505';
+
+async function loadItem(db, organisationId, id) {
+  const [row] = await db.select().from(priceItems).where(and(eq(priceItems.organisationId, organisationId), eq(priceItems.id, id)));
+  if (!row) throw notFound('price item');
+  return row;
+}
+
+export async function createPriceItem(db, organisationId, raw, { personId = null } = {}) {
+  const item = readPriceItem(raw);
+  const [{ count }] = await db.select({ count: sql`count(*)::int` }).from(priceItems).where(eq(priceItems.organisationId, organisationId));
+  if (count >= MAX_ITEMS) throw invalid(`an organisation can have ${MAX_ITEMS} price items at most`);
+  try {
+    const [row] = await db.insert(priceItems).values({ organisationId, ...item, updatedBy: personId }).returning();
+    await remapJobs(db, organisationId);
+    return shapeItem(row);
+  } catch (error) {
+    if (conflictOf(error)) throw new FlowError('conflict', `the code ${item.code} is already on the price list`);
+    throw error;
+  }
+}
+
+// A change to a price item. Invoice lines keep the price they were made with;
+// jobs not yet invoiced map again on the next pipeline run.
+export async function updatePriceItem(db, organisationId, id, raw, { personId = null } = {}) {
+  const row = await loadItem(db, organisationId, id);
+  const changes = readPriceItem(raw, { partial: true });
+  if (!Object.keys(changes).length) return shapeItem(row);
+  try {
+    const [saved] = await db.update(priceItems).set({ ...changes, updatedBy: personId, updatedAt: sql`now()` })
+      .where(eq(priceItems.id, row.id)).returning();
+    await remapJobs(db, organisationId);
+    return shapeItem(saved);
+  } catch (error) {
+    if (conflictOf(error)) throw new FlowError('conflict', `the code ${changes.code} is already on the price list`);
+    throw error;
+  }
+}
+
+// Archives (or brings back) a price item. An archived item keeps its invoice
+// lines and its links; new lines no longer map to it.
+export async function archivePriceItem(db, organisationId, id, { archived = true, personId = null } = {}) {
+  const row = await loadItem(db, organisationId, id);
+  const [saved] = await db.update(priceItems)
+    .set({ archivedAt: archived ? (row.archivedAt ?? sql`now()`) : null, updatedBy: personId, updatedAt: sql`now()` })
+    .where(eq(priceItems.id, row.id)).returning();
+  await remapJobs(db, organisationId);
+  return shapeItem(saved);
+}
+
+// Each connected system's list, by system id: { id, name, kind, syncedAt,
+// items, byId }. A system that cannot answer is left out (it is off, or its
+// copy is not there yet).
+export async function readCatalogues(organisationId, systems = [], { log = console } = {}) {
+  const out = new Map();
+  for (const adapter of systems) {
+    try {
+      const answer = await adapter.capabilities.listPriceItems({ organisationId });
+      if (!answer || !Array.isArray(answer.items)) continue;
+      const items = answer.items.filter((i) => i && i.id);
+      out.set(adapter.id, {
+        id: adapter.id,
+        name: adapter.name,
+        kind: answer.kind === 'accounting' ? 'accounting' : 'work',
+        syncedAt: answer.syncedAt ?? null,
+        items,
+        byId: new Map(items.map((i) => [String(i.id), i])),
+      });
+    } catch (error) {
+      log.warn?.(`[price-list] ${adapter.id} price list could not be read: ${error.message}`);
+    }
+  }
+  return out;
+}
+
+async function readLinks(db, organisationId) {
+  return db.select().from(priceItemLinks).where(eq(priceItemLinks.organisationId, organisationId))
+    .orderBy(asc(priceItemLinks.system), asc(priceItemLinks.externalCode));
+}
+
+// Links each record of a system's list whose code is a price item's code, when
+// neither side is linked yet in a way that stops it. Answers how many it made.
+export async function linkByCode(db, organisationId, catalogue, { items = null, links = null } = {}) {
+  const all = items ?? await db.select().from(priceItems).where(eq(priceItems.organisationId, organisationId));
+  const existing = links ?? await readLinks(db, organisationId);
+  const mine = existing.filter((l) => l.system === catalogue.id);
+  const linkedExternal = new Set(mine.map((l) => String(l.externalId)));
+  const linkedItem = new Set(mine.map((l) => l.priceItemId));
+  const byCode = new Map(all.filter((i) => !i.archivedAt).map((i) => [codeKey(i.code), i]));
+  const rows = [];
+  for (const record of catalogue.items) {
+    const item = byCode.get(codeKey(record.code));
+    if (!item || !codeKey(record.code) || linkedExternal.has(String(record.id))) continue;
+    if (catalogue.kind === 'accounting' && linkedItem.has(item.id)) continue;
+    rows.push({ organisationId, priceItemId: item.id, system: catalogue.id, externalId: String(record.id), externalCode: record.code ?? null, matchedBy: 'code' });
+    linkedExternal.add(String(record.id));
+    linkedItem.add(item.id);
+  }
+  if (!rows.length) return 0;
+  const made = await db.insert(priceItemLinks).values(rows).onConflictDoNothing().returning({ id: priceItemLinks.id });
+  return made.length;
+}
+
+// A person's link: `externalId` in `system`'s list goes to this price item.
+// For an accounting system it replaces the item's earlier link; a record
+// linked elsewhere moves here.
+export async function linkPriceItem(db, organisationId, priceItemId, { system, externalId }, { catalogues, personId = null }) {
+  const item = await loadItem(db, organisationId, priceItemId);
+  const catalogue = catalogues.get(system);
+  if (!catalogue) throw new FlowError('conflict', `${system} is not connected, or its price list has not been read yet`);
+  const record = catalogue.byId.get(String(externalId ?? ''));
+  if (!record) throw notFound(`${catalogue.name} record`);
+  const link = await db.transaction(async (tx) => {
+    await tx.delete(priceItemLinks).where(and(
+      eq(priceItemLinks.organisationId, organisationId), eq(priceItemLinks.system, system), eq(priceItemLinks.externalId, String(record.id)),
+    ));
+    if (catalogue.kind === 'accounting') {
+      await tx.delete(priceItemLinks).where(and(
+        eq(priceItemLinks.organisationId, organisationId), eq(priceItemLinks.system, system), eq(priceItemLinks.priceItemId, item.id),
+      ));
+    }
+    const [row] = await tx.insert(priceItemLinks).values({
+      organisationId, priceItemId: item.id, system, externalId: String(record.id), externalCode: record.code ?? null, matchedBy: 'person', createdBy: personId,
+    }).returning();
+    return row;
+  });
+  await remapJobs(db, organisationId);
+  return link;
+}
+
+export async function unlinkPriceItem(db, organisationId, linkId) {
+  const rows = await db.delete(priceItemLinks)
+    .where(and(eq(priceItemLinks.organisationId, organisationId), eq(priceItemLinks.id, linkId))).returning();
+  if (!rows.length) throw notFound('link');
+  await remapJobs(db, organisationId);
+}
+
+// What differs between one price item and its linked records. Pure: the
+// caller passes the item, its links and the catalogues.
+export function findingsFor(item, links, catalogues) {
+  const findings = [];
+  for (const catalogue of catalogues.values()) {
+    const mine = links.filter((l) => l.system === catalogue.id);
+    if (!mine.length && catalogue.kind === 'accounting') {
+      findings.push({ system: catalogue.id, kind: 'not_linked', code: item.code });
+      continue;
+    }
+    for (const link of mine) {
+      const record = catalogue.byId.get(String(link.externalId));
+      const base = { system: catalogue.id, externalId: String(link.externalId), externalCode: record?.code ?? link.externalCode ?? null };
+      if (!record) {
+        findings.push({ ...base, kind: 'missing' });
+        continue;
+      }
+      if (record.unitAmountCents !== null && record.unitAmountCents !== undefined && record.unitAmountCents !== item.unitAmountCents) {
+        findings.push({ ...base, kind: 'price', flow: item.unitAmountCents, other: record.unitAmountCents });
+      }
+      if (record.taxCode && record.taxCode !== item.taxCode) {
+        findings.push({ ...base, kind: 'tax', flow: item.taxCode, other: record.taxCode });
+      }
+    }
+  }
+  return findings;
+}
+
+// The same findings always give the same signature, so an accepted finding
+// is never raised again, and a changed one is.
+export function findingsSignature(item, findings) {
+  const parts = findings.map((f) => [f.system, f.kind, f.externalId ?? '', f.flow ?? '', f.other ?? ''].join('|')).sort();
+  return `${item.unitAmountCents}|${item.taxCode}|${parts.join(';')}`;
+}
+
+const moneyAtRisk = (findings) => findings.reduce((max, f) => (f.kind === 'price' ? Math.max(max, Math.abs(f.flow - f.other)) : max), 0);
+
+async function lastClosedSignatures(db, organisationId, ids) {
+  if (!ids.length) return new Map();
+  const rows = await db.select({ flowId: reviewItems.flowId, evidence: reviewItems.evidence, state: reviewItems.state, resolution: reviewItems.resolution })
+    .from(reviewItems)
+    .where(and(eq(reviewItems.organisationId, organisationId), eq(reviewItems.kind, REVIEW_KIND), inArray(reviewItems.flowId, ids)))
+    .orderBy(desc(reviewItems.updatedAt));
+  const out = new Map();
+  for (const row of rows) if (!out.has(row.flowId)) out.set(row.flowId, row);
+  return out;
+}
+
+// The price check. Links by code first, then compares every live price item
+// with its linked records and keeps one review item per price item in step:
+// opened or refreshed while something differs, closed when nothing does.
+// `only` checks one price item. Reads Flow's copies only.
+export async function checkPrices(db, organisationId, { catalogues, only = null, actor = 'flow:price-check' }) {
+  const items = await db.select().from(priceItems).where(eq(priceItems.organisationId, organisationId));
+  let linked = 0;
+  for (const catalogue of catalogues.values()) linked += await linkByCode(db, organisationId, catalogue, { items });
+  const links = await readLinks(db, organisationId);
+  const live = items.filter((i) => !i.archivedAt && (!only || i.id === only));
+  const latest = await lastClosedSignatures(db, organisationId, live.map((i) => i.id));
+  const summary = { linked, checked: live.length, differing: 0, opened: 0, closed: 0, accepted: 0 };
+  for (const item of live) {
+    const findings = findingsFor(item, links.filter((l) => l.priceItemId === item.id), catalogues);
+    const signature = findingsSignature(item, findings);
+    const last = latest.get(item.id);
+    if (!findings.length) {
+      if (last?.state === 'open') {
+        await db.update(reviewItems).set({ state: 'resolved', resolution: 'prices_agree', resolvedBy: actor, resolvedAt: sql`now()`, updatedAt: sql`now()` })
+          .where(and(eq(reviewItems.organisationId, organisationId), eq(reviewItems.kind, REVIEW_KIND), eq(reviewItems.flowId, item.id), eq(reviewItems.state, 'open')));
+        summary.closed += 1;
+      }
+      continue;
+    }
+    summary.differing += 1;
+    if (last && last.resolution === 'accepted' && last.evidence?.signature === signature) {
+      summary.accepted += 1;
+      continue;
+    }
+    await openReview(db, organisationId, {
+      kind: REVIEW_KIND,
+      entity: 'price_item',
+      flowId: item.id,
+      systems: [...new Set(findings.map((f) => f.system))],
+      evidence: { code: item.code, name: item.name, signature, findings },
+      moneyAtRiskCents: moneyAtRisk(findings),
+    });
+    if (last?.state !== 'open') summary.opened += 1;
+  }
+  return summary;
+}
+
+// "Mark resolved": checks the one price item again, then accepts what is
+// still different, so the same finding stays closed.
+export async function acceptFindings(db, organisationId, priceItemId, { catalogues, actor }) {
+  await loadItem(db, organisationId, priceItemId);
+  await checkPrices(db, organisationId, { catalogues, only: priceItemId, actor });
+  const [open] = await db.select().from(reviewItems).where(and(
+    eq(reviewItems.organisationId, organisationId), eq(reviewItems.kind, REVIEW_KIND),
+    eq(reviewItems.flowId, priceItemId), eq(reviewItems.state, 'open'),
+  ));
+  if (!open) return { state: 'agree' };
+  await resolveReview(db, organisationId, open.id, { resolution: 'accepted', actor });
+  return { state: 'accepted' };
+}
+
+// Everything the price list screen shows: each price item with its links,
+// the linked records and what differs; each system's records that link to no
+// price item; and the systems themselves. Reads Flow's copies only.
+export async function readPriceList(db, organisationId, { catalogues }) {
+  const [items, links, open] = await Promise.all([
+    db.select().from(priceItems).where(eq(priceItems.organisationId, organisationId)).orderBy(asc(priceItems.code)),
+    readLinks(db, organisationId),
+    db.select({ flowId: reviewItems.flowId }).from(reviewItems)
+      .where(and(eq(reviewItems.organisationId, organisationId), eq(reviewItems.kind, REVIEW_KIND), eq(reviewItems.state, 'open'))),
+  ]);
+  const alerting = new Set(open.map((r) => r.flowId));
+  const linksOf = new Map();
+  for (const link of links) {
+    if (!linksOf.has(link.priceItemId)) linksOf.set(link.priceItemId, []);
+    linksOf.get(link.priceItemId).push(link);
+  }
+  const linked = new Set(links.map((l) => `${l.system}:${l.externalId}`));
+  return {
+    systems: [...catalogues.values()].map((c) => ({ id: c.id, name: c.name, kind: c.kind, syncedAt: c.syncedAt, count: c.items.length })),
+    items: items.map((item) => {
+      const mine = linksOf.get(item.id) ?? [];
+      return {
+        ...shapeItem(item),
+        alert: alerting.has(item.id),
+        findings: item.archivedAt ? [] : findingsFor(item, mine, catalogues),
+        links: mine.map((l) => {
+          const record = catalogues.get(l.system)?.byId.get(String(l.externalId)) ?? null;
+          return { id: l.id, system: l.system, externalId: l.externalId, externalCode: l.externalCode, matchedBy: l.matchedBy, record };
+        }),
+      };
+    }),
+    unlinked: [...catalogues.values()].map((c) => ({
+      system: c.id,
+      records: c.items.filter((r) => r.sold !== false && !linked.has(`${c.id}:${r.id}`)),
+    })),
+  };
+}

package/server/db/commands.js

@@ -0,0 +1,42 @@
+import { adapters } from '../integrations/adapters.js';
+import { diagnoseDatabase, formatReport, liveMigrationCounts, publishVerdict } from './doctor.js';
+import { openDatabase } from './index.js';
+import { migrateEverything } from './migrate-all.js';
+
+// `flow-server migrate` and `flow-server doctor` (server/flow-server.js).
+// Each returns the exit code.
+export async function runCommand(command, args, { log = console } = {}) {
+  const option = (name) => {
+    const at = args.indexOf(name);
+    return at === -1 ? undefined : args[at + 1];
+  };
+  let handle;
+  try {
+    handle = openDatabase({ max: 1 });
+  } catch (error) {
+    log.error(`[doctor] ${error.message}`);
+    return 2;
+  }
+  try {
+    if (command === 'migrate') {
+      await migrateEverything(handle.db, { log: (line) => log.log(`[migrate] ${line}`) });
+      log.log('[migrate] the database is at this build');
+      return 0;
+    }
+    const report = await diagnoseDatabase(handle.pool, { adapters });
+    const origin = option('--live');
+    const live = origin ? await liveMigrationCounts(origin) : undefined;
+    const verdict = origin ? publishVerdict(report, live) : null;
+    if (args.includes('--json')) {
+      log.log(JSON.stringify({ ...report, live: live ?? null, verdict }, null, 2));
+    } else {
+      for (const line of formatReport(report, verdict)) log.log(`[doctor] ${line}`);
+    }
+    return report.ok ? 0 : 1;
+  } catch (error) {
+    log.error(`[doctor] ${error.message}`);
+    return 2;
+  } finally {
+    await handle.close();
+  }
+}