@arcforgelabs/flow 2026.10.30 → 2026.10.32

package/server/core/invoicing-rules.js

@@ -5,6 +5,7 @@ import {
 import { FlowError, notFound } from './errors.js';
 import { listRules, ruleReasons } from './invoice-rules.js';
 import { draftInvoiceForObligation } from './ledger.js';
+import { checkReferenceTemplate, DEFAULT_REFERENCE, jobReference } from './references.js';
 
 // Invoicing rules (docs/INVOICING_RULES.md). They are the checks a job that
 // is ready to invoice passes before Flow drafts its invoice, and how a checked
@@ -30,6 +31,7 @@ export const INVOICING_DEFAULTS = Object.freeze({
   requirePractitioner: false,
   rushItemCode: null,
   rushPercent: 20,
+  referenceTemplate: DEFAULT_REFERENCE,
 });
 
 const CUSTOMER_DEFAULTS = Object.freeze({
@@ -58,6 +60,15 @@ function shortText(value, name) {
   return value.trim() || null;
 }
 
+// An empty rule gives no Reference: the accounting system shows the number.
+function referenceTemplate(value) {
+  if (value === null) return '';
+  if (typeof value !== 'string' || value.length > 200) throw invalid('referenceTemplate must be text of 200 characters at most');
+  const problem = checkReferenceTemplate(value);
+  if (problem) throw invalid(`referenceTemplate: ${problem}`);
+  return value.trim();
+}
+
 function sendMode(value, name) {
   if (!SEND_MODES.includes(value)) throw invalid(`${name} must be one of ${SEND_MODES.join(', ')}`);
   return value;
@@ -79,6 +90,7 @@ function readSettingChanges(changes) {
     else if (key === 'paymentTermsDays') out[key] = wholeNumber(value, key, 0, 365);
     else if (key === 'rushPercent') out[key] = wholeNumber(value, key, 0, 100);
     else if (key === 'rushItemCode') out[key] = shortText(value, key);
+    else if (key === 'referenceTemplate') out[key] = referenceTemplate(value);
     else throw invalid(`unknown setting: ${key}`);
   }
   return out;
@@ -158,6 +170,18 @@ export async function sendModeFor(db, organisationId, contactId) {
   return effectiveSettings(settings, customers.get(contactId)).sendMode;
 }
 
+// How Flow sends invoices to the accounting system: the organisation's mode,
+// and how many customers have a mode of their own that differs from it.
+export async function sendModeSummary(db, organisationId) {
+  const settings = await readInvoicingSettings(db, organisationId);
+  const [row] = await db.select({ n: sql`count(*)::int` }).from(customerBillingSettings).where(and(
+    eq(customerBillingSettings.organisationId, organisationId),
+    sql`${customerBillingSettings.sendMode} is not null`,
+    sql`${customerBillingSettings.sendMode} <> ${settings.sendMode}`,
+  ));
+  return { mode: settings.sendMode, otherCustomers: row?.n ?? 0 };
+}
+
 // What a job still waits on before Flow drafts it, as reasons a person can
 // read: Flow's own ready stage, then the lab's invoice rules (invoice-rules.js)
 // in their order. An empty list means the job may be drafted. `rules` is the
@@ -203,7 +227,7 @@ export function copyCheck(accounting, organisationId) {
 // The draft automation (automations.js) runs it. Answers counts.
 // With `accounting` null no accounting system is connected: Flow's own records
 // are the only check, as for a person's draft (ledger.js, ledgerView).
-export async function autoDraftJobs(db, organisationId, { accounting = null, now = new Date(), limit = DRAFT_BATCH, actor = ACTOR }) {
+export async function autoDraftJobs(db, organisationId, { accounting = null, work = null, now = new Date(), limit = DRAFT_BATCH, actor = ACTOR }) {
   const result = { drafted: 0, waiting: 0, off: 0, refused: 0 };
   const settings = await readInvoicingSettings(db, organisationId);
   const rules = await listRules(db, organisationId);
@@ -243,6 +267,7 @@ export async function autoDraftJobs(db, organisationId, { accounting = null, now
         liveCheck,
         actor,
         now,
+        reference: await jobReference(db, organisationId, obligation, { template: settings.referenceTemplate, work }),
         dueDate: addDays(invoiceDate, effective.paymentTermsDays),
       });
       result.drafted += 1;

package/server/core/job-board.js

@@ -3,6 +3,7 @@ import { contacts, invoices, priceItems } from '../db/schema.js';
 import { listRules } from './invoice-rules.js';
 import { customerBillingByContact, effectiveSettings, readInvoicingSettings, ruleBlockers } from './invoicing-rules.js';
 import { listObligations } from './ledger.js';
+import { isHistoryHeld } from './history.js';
 import { invoiceViews } from './sending.js';
 
 // The Jobs board (/jobs, server/ui/jobs.js). Its columns are the work
@@ -68,7 +69,9 @@ const ledgerLines = (lines) => (lines ?? []).map((l) => ({
 // Answers { jobs, statuses }. `work` is the adapters that offer listWork;
 // `live` says an accounting system checks the ledger (ledgerView).
 export async function boardJobs(db, organisationId, { work = [], accounting = null, live = false, log = console } = {}) {
-  const listed = await listObligations(db, organisationId, { accounting: live });
+  // Held history jobs are past work, so the board leaves them out
+  // (core/history.js); the history import lists them by accounting state.
+  const listed = (await listObligations(db, organisationId, { accounting: live })).filter((entry) => !isHistoryHeld(entry.obligation));
   const obligations = await describeObligations(db, organisationId, listed, { accounting });
   const byJob = new Map(obligations.map((o) => [keyOf(o.sourceSystem, o.sourceJobRef), o]));
 
@@ -93,7 +96,7 @@ export async function boardJobs(db, organisationId, { work = [], accounting = nu
         totalCents: o.totalCents, lines: ledgerLines(o.lines), obligation: o,
       };
     });
-    return { jobs, statuses: [...statuses.values()] };
+    return { jobs: await withIssues(jobs, work, log), statuses: [...statuses.values()] };
   }
 
   const codes = new Set((await db.select({ code: priceItems.code }).from(priceItems)
@@ -126,5 +129,24 @@ export async function boardJobs(db, organisationId, { work = [], accounting = nu
       });
     }
   }
-  return { jobs, statuses };
+  return { jobs: await withIssues(jobs, work, log), statuses };
+}
+
+// Each job's open issues from its integration (the port's jobIssues): a
+// short phrase and the page where a person fixes it. A failed read leaves
+// the board as it is.
+async function withIssues(jobs, adapters, log) {
+  const issues = new Map();
+  for (const adapter of adapters) {
+    if (typeof adapter.capabilities.jobIssues !== 'function') continue;
+    const refs = jobs.filter((j) => j.sourceSystem === adapter.id).map((j) => j.sourceJobRef);
+    if (!refs.length) continue;
+    try {
+      const found = await adapter.capabilities.jobIssues({ refs });
+      for (const [ref, list] of Object.entries(found ?? {})) issues.set(keyOf(adapter.id, ref), list);
+    } catch (error) {
+      log.error?.(`[jobs] ${adapter.id} jobIssues: ${error.message}`);
+    }
+  }
+  return jobs.map((j) => ({ ...j, issues: issues.get(keyOf(j.sourceSystem, j.sourceJobRef)) ?? [] }));
 }

package/server/core/ledger.js

@@ -399,7 +399,7 @@ function draftBlockers(o, { now, sourceMaxAgeMs, accounting = true }) {
 // the write, finds no invoice for the job. Any doubt refuses the draft, and
 // the refusal is recorded.
 export async function draftInvoiceForObligation(db, organisationId, obligationId, {
-  liveCheck, actor, now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS, dueDate = null,
+  liveCheck, actor, now = new Date(), sourceMaxAgeMs = SOURCE_MAX_AGE_MS, dueDate = null, reference = null,
 }) {
   requireActor(actor);
   // A null liveCheck says no accounting system is connected (ledgerView).
@@ -423,7 +423,8 @@ export async function draftInvoiceForObligation(db, organisationId, obligationId
     }
     const invoice = await createDraftInvoice(tx, organisationId, {
       contactId: obligation.contactId,
-      reference: obligation.caseRef ?? obligation.sourceJobRef,
+      // The Reference rule's text (references.js), never a work system id.
+      reference,
       dueDate,
       lines: obligation.lines.map(({ priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }) => (
         { priceItemId, accountCode, description, quantity, unitAmountCents, taxCode }

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') {
@@ -439,7 +511,7 @@ export async function runPipelineOnce(db, integrations, { now = new Date() } = {
     const settings = await readInvoicingSettings(db, organisationId);
     summary.matching = await matchJobs(db, organisationId, { accounting, now, staleDays: settings.staleDays });
   }
-  if (work || accounting) summary.automations = await runAutomations(db, organisationId, { accounting: accounting ?? null, now });
+  if (work || accounting) summary.automations = await runAutomations(db, organisationId, { accounting: accounting ?? null, work: work ?? null, now });
   return summary;
 }