@arcforgelabs/flow 2026.10.21 → 2026.10.22

package/server/core/links.js

@@ -0,0 +1,153 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { externalLinks, LINK_ENTITIES, LINK_MATCHES } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { openReview, resolveReviewFor } from './review.js';
+
+// The identity map (issue 57). It records that a Flow record and a record in
+// another system are the same thing, how Flow knows, and who confirmed it.
+// Pushes, imports and the ledger read the link first; matching by name only
+// ever proposes one.
+//
+// A link is exact when Flow made the external record, or both sides carry the
+// same id. A name match is a guess: it stays `proposed` and opens a review item
+// until a person confirms it. A link is never deleted; a replaced one is
+// `superseded`.
+
+const EXACT = new Set(['created_by_flow', 'exact_id', 'imported', 'person']);
+
+function check({ entity, flowId, system, externalId, matchedBy }) {
+  if (!LINK_ENTITIES.includes(entity)) throw new FlowError('invalid', `unknown link entity: ${entity}`);
+  if (!LINK_MATCHES.includes(matchedBy)) throw new FlowError('invalid', `unknown match: ${matchedBy}`);
+  if (!flowId || !system || !externalId) throw new FlowError('invalid', 'flowId, system and externalId are required');
+}
+
+// Two callers that link the same external record, or the same Flow record, at
+// the same time take turns: the decision below reads, then writes.
+async function lockPair(tx, organisationId, { system, entity, externalId, flowId }) {
+  const keys = [
+    `link:${organisationId}:${system}:${entity}:ext:${externalId}`,
+    `link:${organisationId}:${system}:${entity}:flow:${flowId}`,
+  ].sort();
+  for (const key of keys) await tx.execute(sql`select pg_advisory_xact_lock(hashtextextended(${key}, 0))`);
+}
+
+async function activeBy(tx, organisationId, { system, entity }, column, value) {
+  const [row] = await tx.select().from(externalLinks).where(and(
+    eq(externalLinks.organisationId, organisationId),
+    eq(externalLinks.system, system),
+    eq(externalLinks.entity, entity),
+    eq(column, value),
+    eq(externalLinks.state, 'active'),
+  ));
+  return row ?? null;
+}
+
+// Records a link. Answers `{ outcome, link }`:
+// - `linked`: a new active link;
+// - `existing`: the same active link was already there;
+// - `proposed`: a guess, waiting for a person (a review item is open);
+// - `conflict`: one side already links elsewhere. Nothing changes; a review
+//   item holds both sides.
+export async function linkRecord(db, organisationId, link) {
+  check(link);
+  const { entity, flowId, system, externalId, matchedBy } = link;
+  return db.transaction(async (tx) => {
+    await lockPair(tx, organisationId, link);
+    const byExternal = await activeBy(tx, organisationId, link, externalLinks.externalId, externalId);
+    if (byExternal?.flowId === flowId) return { outcome: 'existing', link: byExternal };
+    const byFlow = await activeBy(tx, organisationId, link, externalLinks.flowId, flowId);
+    if (byExternal || byFlow) {
+      await openReview(tx, organisationId, {
+        kind: 'link.conflict',
+        entity,
+        flowId,
+        systems: [system],
+        evidence: {
+          proposed: { system, externalId, matchedBy },
+          linkedExternal: byExternal && { flowId: byExternal.flowId, externalId: byExternal.externalId },
+          linkedFlow: byFlow && { flowId: byFlow.flowId, externalId: byFlow.externalId },
+        },
+      });
+      return { outcome: 'conflict', link: byExternal ?? byFlow };
+    }
+    const state = EXACT.has(matchedBy) ? 'active' : 'proposed';
+    const [waiting] = await tx.select().from(externalLinks).where(and(
+      eq(externalLinks.organisationId, organisationId),
+      eq(externalLinks.system, system),
+      eq(externalLinks.entity, entity),
+      eq(externalLinks.externalId, externalId),
+      eq(externalLinks.flowId, flowId),
+      eq(externalLinks.state, 'proposed'),
+    ));
+    if (waiting && state === 'proposed') return { outcome: 'proposed', link: waiting };
+    if (waiting) {
+      // Exact evidence for a pair a person was asked about settles the question.
+      await tx.update(externalLinks).set({ state: 'superseded', updatedAt: sql`now()` })
+        .where(eq(externalLinks.id, waiting.id));
+      await resolveReviewFor(tx, organisationId, {
+        kind: 'link.proposed', entity, flowId, resolution: `exact:${matchedBy}`, actor: 'system:links',
+      });
+    }
+    const [row] = await tx.insert(externalLinks)
+      .values({ organisationId, entity, flowId, system, externalId, matchedBy, state })
+      .returning();
+    if (state === 'proposed') {
+      await openReview(tx, organisationId, {
+        kind: 'link.proposed',
+        entity,
+        flowId,
+        systems: [system],
+        evidence: { linkId: row.id, system, externalId, matchedBy },
+      });
+    }
+    return { outcome: state === 'active' ? 'linked' : 'proposed', link: row };
+  });
+}
+
+// A person confirms a proposed link. It becomes active, unless either side
+// gained an active link meanwhile.
+export async function confirmLink(db, organisationId, linkId, { personId = null, actor }) {
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+  return db.transaction(async (tx) => {
+    const [proposed] = await tx.select().from(externalLinks)
+      .where(and(eq(externalLinks.organisationId, organisationId), eq(externalLinks.id, linkId)));
+    if (!proposed) throw notFound('link');
+    await lockPair(tx, organisationId, proposed);
+    const [current] = await tx.select().from(externalLinks)
+      .where(eq(externalLinks.id, linkId)).for('update');
+    if (current.state !== 'proposed') throw new FlowError('conflict', 'link is not waiting for a person', { state: current.state });
+    const taken = await activeBy(tx, organisationId, current, externalLinks.externalId, current.externalId)
+      ?? await activeBy(tx, organisationId, current, externalLinks.flowId, current.flowId);
+    if (taken) throw new FlowError('conflict', 'one side already has an active link', { linkId: taken.id });
+    const [row] = await tx.update(externalLinks)
+      .set({ state: 'active', confirmedBy: personId, confirmedAt: sql`now()`, updatedAt: sql`now()` })
+      .where(eq(externalLinks.id, linkId))
+      .returning();
+    await resolveReviewFor(tx, organisationId, {
+      kind: 'link.proposed', entity: row.entity, flowId: row.flowId, resolution: 'confirmed', actor,
+    });
+    return row;
+  });
+}
+
+// Ends a link (for example when the external record was merged or deleted).
+export async function supersedeLink(db, organisationId, linkId) {
+  const [row] = await db.update(externalLinks)
+    .set({ state: 'superseded', updatedAt: sql`now()` })
+    .where(and(eq(externalLinks.organisationId, organisationId), eq(externalLinks.id, linkId)))
+    .returning();
+  if (!row) throw notFound('link');
+  return row;
+}
+
+// The Flow record an external record is, through an active link, or null.
+export async function flowIdFor(db, organisationId, { system, entity, externalId }) {
+  const row = await activeBy(db, organisationId, { system, entity }, externalLinks.externalId, externalId);
+  return row?.flowId ?? null;
+}
+
+// The external id of a Flow record in one system, through an active link, or null.
+export async function externalIdFor(db, organisationId, { system, entity, flowId }) {
+  const row = await activeBy(db, organisationId, { system, entity }, externalLinks.flowId, flowId);
+  return row?.externalId ?? null;
+}

package/server/core/outbox.js

@@ -0,0 +1,129 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { outbox } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+import { linkRecord } from './links.js';
+import { openReview } from './review.js';
+
+// The outbox. Every write Flow makes to another system is a row here first,
+// written in the same transaction as the Flow change it reports, with its
+// idempotency key. An adapter sends it through its governor and records what
+// came back. So a write is never lost, never made twice, and never made
+// without a record of why.
+//
+//   pending -> sending -> sent
+//                      -> ambiguous (outcome unknown: settle by a lookup first)
+//                      -> pending again (a retry) or failed (opens a review item)
+//   pending or ambiguous -> cancelled (a person)
+
+// How long a send may take before Flow treats its outcome as unknown.
+export const SEND_LEASE_MS = 10 * 60 * 1000;
+
+// Queues a write. Pass the transaction that makes the Flow change. A repeat with
+// the same key returns the first row; the same key for another record refuses.
+export async function queueWrite(tx, organisationId, {
+  system, action, entity, flowId, idempotencyKey, request, actor,
+}) {
+  if (!system || !action || !entity || !flowId) throw new FlowError('invalid', 'system, action, entity and flowId are required');
+  if (!idempotencyKey) throw new FlowError('invalid', 'idempotencyKey is required');
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+  const [row] = await tx.insert(outbox)
+    .values({ organisationId, system, action, entity, flowId, idempotencyKey, request, createdBy: actor })
+    .onConflictDoNothing({ target: outbox.idempotencyKey })
+    .returning();
+  if (row) return { write: row, queued: true };
+  const [first] = await tx.select().from(outbox).where(eq(outbox.idempotencyKey, idempotencyKey));
+  if (first.organisationId !== organisationId || first.flowId !== flowId || first.action !== action) {
+    throw new FlowError('conflict', 'idempotency key already used for another write');
+  }
+  return { write: first, queued: false };
+}
+
+// Claims pending writes for one system. A write left `sending` past the lease
+// (the process died mid-call) becomes `ambiguous`: the call may have left.
+export async function claimWrites(db, { system, limit = 10, leaseMs = SEND_LEASE_MS }) {
+  return db.transaction(async (tx) => {
+    await tx.update(outbox)
+      .set({ state: 'ambiguous', lastError: 'send did not finish', updatedAt: sql`now()` })
+      .where(and(
+        eq(outbox.system, system),
+        eq(outbox.state, 'sending'),
+        sql`${outbox.updatedAt} < now() - make_interval(secs => ${leaseMs / 1000})`,
+      ));
+    const { rows } = await tx.execute(sql`
+      select id from outbox where system = ${system} and state = 'pending'
+      order by created_at for update skip locked limit ${limit}`);
+    const claimed = [];
+    for (const { id } of rows) {
+      const [write] = await tx.update(outbox)
+        .set({ state: 'sending', attempts: sql`${outbox.attempts} + 1`, updatedAt: sql`now()` })
+        .where(eq(outbox.id, id))
+        .returning();
+      claimed.push(write);
+    }
+    return claimed;
+  });
+}
+
+// Moves one write from the states in `from` to new fields. Refuses a move from
+// any other state, so two workers can never both settle one write.
+async function move(tx, organisationId, writeId, from, fields) {
+  const [row] = await tx.update(outbox)
+    .set({ ...fields, updatedAt: sql`now()` })
+    .where(and(
+      eq(outbox.organisationId, organisationId),
+      eq(outbox.id, writeId),
+      sql`${outbox.state} in (${sql.join(from.map((s) => sql`${s}`), sql`, `)})`,
+    ))
+    .returning();
+  if (row) return row;
+  const [existing] = await tx.select().from(outbox)
+    .where(and(eq(outbox.organisationId, organisationId), eq(outbox.id, writeId)));
+  if (!existing) throw notFound('write');
+  throw new FlowError('conflict', `write is ${existing.state}`, { state: existing.state });
+}
+
+// The system made the record. Flow links its own record to it in the same
+// transaction, so the identity map always knows what Flow created.
+export async function markSent(db, organisationId, writeId, { externalId }) {
+  if (!externalId) throw new FlowError('invalid', 'externalId is required');
+  return db.transaction(async (tx) => {
+    const row = await move(tx, organisationId, writeId, ['sending', 'ambiguous'], {
+      state: 'sent', externalId, sentAt: sql`now()`, lastError: null,
+    });
+    const link = await linkRecord(tx, organisationId, {
+      entity: row.entity, flowId: row.flowId, system: row.system, externalId, matchedBy: 'created_by_flow',
+    });
+    return { write: row, link };
+  });
+}
+
+// The outcome is unknown (a timeout, a 5xx after the request left). The adapter
+// must look in the system before it sends again.
+export async function markAmbiguous(db, organisationId, writeId, { error }) {
+  return move(db, organisationId, writeId, ['sending'], { state: 'ambiguous', lastError: String(error).slice(0, 2000) });
+}
+
+// The system refused the write, or a lookup found it was never made. With
+// `retry` it goes back to pending; without, it fails and opens a review item.
+export async function markFailed(db, organisationId, writeId, { error, retry = false }) {
+  const message = String(error).slice(0, 2000);
+  if (retry) return move(db, organisationId, writeId, ['sending', 'ambiguous'], { state: 'pending', lastError: message });
+  return db.transaction(async (tx) => {
+    const row = await move(tx, organisationId, writeId, ['sending', 'ambiguous'], { state: 'failed', lastError: message });
+    await openReview(tx, organisationId, {
+      kind: 'write.failed',
+      entity: row.entity,
+      flowId: row.flowId,
+      systems: [row.system],
+      evidence: { writeId: row.id, action: row.action, attempts: row.attempts, error: message },
+    });
+    return row;
+  });
+}
+
+export async function cancelWrite(db, organisationId, writeId, { actor }) {
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+  return move(db, organisationId, writeId, ['pending', 'ambiguous', 'failed'], {
+    state: 'cancelled', lastError: `cancelled by ${actor}`,
+  });
+}

package/server/core/queue.js

@@ -0,0 +1,142 @@
+import { and, eq, sql } from 'drizzle-orm';
+import { backgroundJobs } from '../db/schema.js';
+import { FlowError } from './errors.js';
+import { openReview } from './review.js';
+
+// The background job queue (issue 6). Every sync and write step runs as a job
+// here, so steps never overlap, a crash never loses one, and a person can see
+// what is queued, running or stuck. It is PostgreSQL only: workers claim with
+// FOR UPDATE SKIP LOCKED and hold a lease. A lease that runs out makes the job
+// claimable again, so a dead process never holds a job for good.
+
+export const DEFAULT_LEASE_MS = 5 * 60 * 1000;
+const FIRST_RETRY_MS = 60 * 1000;
+const LAST_RETRY_MS = 6 * 60 * 60 * 1000;
+
+// The wait before attempt `attempts + 1`: 1 minute, doubling, at most 6 hours.
+export function retryDelayMs(attempts) {
+  return Math.min(FIRST_RETRY_MS * 2 ** Math.max(0, attempts - 1), LAST_RETRY_MS);
+}
+
+// Queues a job. While a job with the same kind and dedupe key is queued or
+// running, it is returned instead of a second one.
+export async function enqueueJob(db, organisationId, {
+  kind, dedupeKey = '', payload = {}, runAfter = null, maxAttempts = 8,
+}) {
+  if (!kind) throw new FlowError('invalid', 'kind is required');
+  const [row] = await db.insert(backgroundJobs)
+    .values({ organisationId, kind, dedupeKey, payload, maxAttempts, ...(runAfter ? { runAfter } : {}) })
+    .onConflictDoNothing()
+    .returning();
+  if (row) return { job: row, queued: true };
+  const [open] = await db.select().from(backgroundJobs).where(and(
+    eq(backgroundJobs.organisationId, organisationId),
+    eq(backgroundJobs.kind, kind),
+    eq(backgroundJobs.dedupeKey, dedupeKey),
+    sql`${backgroundJobs.state} in ('queued', 'running')`,
+  ));
+  return { job: open, queued: false };
+}
+
+async function giveUp(tx, job, error) {
+  const [row] = await tx.update(backgroundJobs)
+    .set({ state: 'dead', lockedBy: null, lockedUntil: null, lastError: error, updatedAt: sql`now()` })
+    .where(eq(backgroundJobs.id, job.id))
+    .returning();
+  await openReview(tx, job.organisationId, {
+    kind: 'job.dead',
+    entity: 'background_job',
+    flowId: job.id,
+    evidence: { kind: job.kind, dedupeKey: job.dedupeKey, attempts: job.attempts, error },
+  });
+  return row;
+}
+
+// Claims up to `limit` due jobs for one worker. A running job whose lease ran
+// out is due again; one that has used every attempt is given up instead.
+export async function claimJobs(db, { workerId, kinds = null, limit = 1, leaseMs = DEFAULT_LEASE_MS }) {
+  if (!workerId) throw new FlowError('invalid', 'workerId is required');
+  return db.transaction(async (tx) => {
+    const kindFilter = kinds?.length
+      ? sql`and kind in (${sql.join(kinds.map((k) => sql`${k}`), sql`, `)})`
+      : sql``;
+    const { rows: due } = await tx.execute(sql`
+      select id, attempts, max_attempts from background_jobs
+      where ((state = 'queued' and run_after <= now()) or (state = 'running' and locked_until < now()))
+      ${kindFilter}
+      order by run_after, created_at
+      for update skip locked
+      limit ${limit}`);
+    const claimed = [];
+    for (const candidate of due) {
+      if (candidate.attempts >= candidate.max_attempts) {
+        const [job] = await tx.select().from(backgroundJobs).where(eq(backgroundJobs.id, candidate.id));
+        await giveUp(tx, job, job.lastError ?? 'lease ran out on the last attempt');
+        continue;
+      }
+      const [job] = await tx.update(backgroundJobs)
+        .set({
+          state: 'running',
+          lockedBy: workerId,
+          lockedUntil: sql`now() + make_interval(secs => ${leaseMs / 1000})`,
+          attempts: sql`${backgroundJobs.attempts} + 1`,
+          updatedAt: sql`now()`,
+        })
+        .where(eq(backgroundJobs.id, candidate.id))
+        .returning();
+      claimed.push(job);
+    }
+    return claimed;
+  });
+}
+
+// Only the worker that holds the lease may finish a job. A worker whose lease
+// ran out and was taken over finishes nothing and is told so.
+async function finish(db, job, workerId, fields) {
+  const [row] = await db.update(backgroundJobs)
+    .set({ ...fields, lockedBy: null, lockedUntil: null, updatedAt: sql`now()` })
+    .where(and(
+      eq(backgroundJobs.id, job.id),
+      eq(backgroundJobs.state, 'running'),
+      eq(backgroundJobs.lockedBy, workerId),
+      eq(backgroundJobs.attempts, job.attempts),
+    ))
+    .returning();
+  if (!row) throw new FlowError('conflict', 'job lease was lost', { jobId: job.id });
+  return row;
+}
+
+export async function completeJob(db, job, { workerId, result = null }) {
+  return finish(db, job, workerId, { state: 'succeeded', result, lastError: null });
+}
+
+// A failed attempt waits and runs again, until its attempts run out or the
+// error cannot be fixed by waiting (`retry: false`); then it opens a review item.
+export async function failJob(db, job, { workerId, error, retry = true }) {
+  const message = String(error?.message ?? error ?? 'failed').slice(0, 2000);
+  if (!retry || job.attempts >= job.maxAttempts) {
+    return db.transaction(async (tx) => {
+      const row = await finish(tx, job, workerId, { state: 'running', lastError: message });
+      return giveUp(tx, { ...row, attempts: job.attempts }, message);
+    });
+  }
+  return finish(db, job, workerId, {
+    state: 'queued',
+    lastError: message,
+    runAfter: sql`now() + make_interval(secs => ${retryDelayMs(job.attempts) / 1000})`,
+  });
+}
+
+// Claims one due job and runs its handler. Answers what happened, or null when
+// nothing was due. A handler throws to fail; `error.retry = false` gives up.
+export async function runNextJob(db, { workerId, handlers, leaseMs }) {
+  const [job] = await claimJobs(db, { workerId, kinds: Object.keys(handlers), limit: 1, leaseMs });
+  if (!job) return null;
+  try {
+    const result = await handlers[job.kind](job);
+    return { job: await completeJob(db, job, { workerId, result: result ?? null }), outcome: 'succeeded' };
+  } catch (error) {
+    const row = await failJob(db, job, { workerId, error, retry: error?.retry !== false });
+    return { job: row, outcome: row.state };
+  }
+}

package/server/core/review.js

@@ -0,0 +1,92 @@
+import { and, asc, desc, eq, sql } from 'drizzle-orm';
+import { reviewItems } from '../db/schema.js';
+import { FlowError, notFound } from './errors.js';
+
+// The review queue (issue 59). Everything a person must decide is one row
+// here: a link Flow could not prove, a write that failed for good, a job that
+// gave up, a difference between two systems. Flow never settles a conflict by
+// overwriting one side; it opens an item and waits for a person.
+
+function requireActor(actor) {
+  if (!actor) throw new FlowError('invalid', 'actor is required');
+}
+
+// Opens an item, or updates the one open item for the same kind and record:
+// a repeat finding refreshes the evidence and never makes a second item.
+export async function openReview(db, organisationId, {
+  kind, entity, flowId, systems = [], evidence = {}, moneyAtRiskCents = 0,
+}) {
+  if (!kind || !entity || !flowId) throw new FlowError('invalid', 'kind, entity and flowId are required');
+  if (!Number.isSafeInteger(moneyAtRiskCents) || moneyAtRiskCents < 0) {
+    throw new FlowError('invalid', 'moneyAtRiskCents must be whole, non-negative cents');
+  }
+  const [row] = await db.insert(reviewItems)
+    .values({ organisationId, kind, entity, flowId, systems, evidence, moneyAtRiskCents })
+    .onConflictDoUpdate({
+      target: [reviewItems.organisationId, reviewItems.kind, reviewItems.entity, reviewItems.flowId],
+      targetWhere: sql`state = 'open'`,
+      set: {
+        systems,
+        evidence,
+        moneyAtRiskCents,
+        seenCount: sql`${reviewItems.seenCount} + 1`,
+        updatedAt: sql`now()`,
+      },
+    })
+    .returning();
+  return row;
+}
+
+// Closes an open item with the choice a person made. `dismiss` records that
+// nothing needed doing.
+export async function resolveReview(db, organisationId, reviewId, { resolution, note = null, actor, dismiss = false }) {
+  requireActor(actor);
+  if (!resolution) throw new FlowError('invalid', 'resolution is required');
+  const [row] = await db.update(reviewItems)
+    .set({
+      state: dismiss ? 'dismissed' : 'resolved',
+      resolution,
+      note,
+      resolvedBy: actor,
+      resolvedAt: sql`now()`,
+      updatedAt: sql`now()`,
+    })
+    .where(and(
+      eq(reviewItems.organisationId, organisationId),
+      eq(reviewItems.id, reviewId),
+      eq(reviewItems.state, 'open'),
+    ))
+    .returning();
+  if (row) return row;
+  const [existing] = await db.select().from(reviewItems)
+    .where(and(eq(reviewItems.organisationId, organisationId), eq(reviewItems.id, reviewId)));
+  if (!existing) throw notFound('review item');
+  throw new FlowError('conflict', 'review item is already closed', { state: existing.state });
+}
+
+// Closes the open item for one record and kind, when the cause went away on its
+// own (for example a person confirmed a link from another screen).
+export async function resolveReviewFor(db, organisationId, { kind, entity, flowId, resolution, actor }) {
+  requireActor(actor);
+  const rows = await db.update(reviewItems)
+    .set({ state: 'resolved', resolution, resolvedBy: actor, resolvedAt: sql`now()`, updatedAt: sql`now()` })
+    .where(and(
+      eq(reviewItems.organisationId, organisationId),
+      eq(reviewItems.kind, kind),
+      eq(reviewItems.entity, entity),
+      eq(reviewItems.flowId, flowId),
+      eq(reviewItems.state, 'open'),
+    ))
+    .returning();
+  return rows[0] ?? null;
+}
+
+// The queue a person works through: most money at risk first, then oldest.
+export async function listReview(db, organisationId, { state = 'open', kind, limit = 100 } = {}) {
+  const filters = [eq(reviewItems.organisationId, organisationId), eq(reviewItems.state, state)];
+  if (kind) filters.push(eq(reviewItems.kind, kind));
+  return db.select().from(reviewItems)
+    .where(and(...filters))
+    .orderBy(desc(reviewItems.moneyAtRiskCents), asc(reviewItems.createdAt))
+    .limit(limit);
+}

package/server/db/migrations/0005_data_spine.sql

@@ -0,0 +1,99 @@
+CREATE TABLE "background_jobs" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"kind" text NOT NULL,
+	"dedupe_key" text DEFAULT '' NOT NULL,
+	"payload" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"state" text DEFAULT 'queued' NOT NULL,
+	"run_after" timestamp with time zone DEFAULT now() NOT NULL,
+	"attempts" integer DEFAULT 0 NOT NULL,
+	"max_attempts" integer DEFAULT 8 NOT NULL,
+	"locked_by" text,
+	"locked_until" timestamp with time zone,
+	"result" jsonb,
+	"last_error" text,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "background_jobs_state_valid" CHECK (state in ('queued', 'running', 'succeeded', 'failed', 'dead')),
+	CONSTRAINT "background_jobs_attempts_valid" CHECK ("background_jobs"."attempts" >= 0 and "background_jobs"."max_attempts" > 0)
+);
+--> statement-breakpoint
+CREATE TABLE "external_links" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"entity" text NOT NULL,
+	"flow_id" uuid NOT NULL,
+	"system" text NOT NULL,
+	"external_id" text NOT NULL,
+	"matched_by" text NOT NULL,
+	"state" text NOT NULL,
+	"confirmed_by" uuid,
+	"confirmed_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "external_links_org_id" UNIQUE("organisation_id","id"),
+	CONSTRAINT "external_links_entity_valid" CHECK (entity in ('contact', 'price_item', 'obligation', 'invoice', 'payment', 'credit_note')),
+	CONSTRAINT "external_links_matched_by_valid" CHECK (matched_by in ('created_by_flow', 'exact_id', 'imported', 'name', 'person')),
+	CONSTRAINT "external_links_state_valid" CHECK (state in ('active', 'proposed', 'superseded')),
+	CONSTRAINT "external_links_name_needs_person" CHECK ("external_links"."matched_by" <> 'name' or "external_links"."state" <> 'active' or "external_links"."confirmed_at" is not null)
+);
+--> statement-breakpoint
+CREATE TABLE "outbox" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"system" text NOT NULL,
+	"action" text NOT NULL,
+	"entity" text NOT NULL,
+	"flow_id" uuid NOT NULL,
+	"idempotency_key" text NOT NULL,
+	"request" jsonb NOT NULL,
+	"state" text DEFAULT 'pending' NOT NULL,
+	"external_id" text,
+	"attempts" integer DEFAULT 0 NOT NULL,
+	"last_error" text,
+	"created_by" text NOT NULL,
+	"sent_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "outbox_org_id" UNIQUE("organisation_id","id"),
+	CONSTRAINT "outbox_idempotency_key" UNIQUE("idempotency_key"),
+	CONSTRAINT "outbox_state_valid" CHECK (state in ('pending', 'sending', 'ambiguous', 'sent', 'failed', 'cancelled')),
+	CONSTRAINT "outbox_sent_has_id" CHECK ("outbox"."state" <> 'sent' or "outbox"."external_id" is not null)
+);
+--> statement-breakpoint
+CREATE TABLE "review_items" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"organisation_id" uuid NOT NULL,
+	"kind" text NOT NULL,
+	"entity" text NOT NULL,
+	"flow_id" uuid NOT NULL,
+	"systems" text[] DEFAULT '{}'::text[] NOT NULL,
+	"evidence" jsonb DEFAULT '{}'::jsonb NOT NULL,
+	"money_at_risk_cents" bigint DEFAULT 0 NOT NULL,
+	"state" text DEFAULT 'open' NOT NULL,
+	"seen_count" integer DEFAULT 1 NOT NULL,
+	"resolution" text,
+	"note" text,
+	"resolved_by" text,
+	"resolved_at" timestamp with time zone,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL,
+	CONSTRAINT "review_items_org_id" UNIQUE("organisation_id","id"),
+	CONSTRAINT "review_items_state_valid" CHECK (state in ('open', 'resolved', 'dismissed')),
+	CONSTRAINT "review_items_money_not_negative" CHECK ("review_items"."money_at_risk_cents" >= 0),
+	CONSTRAINT "review_items_closed_has_resolution" CHECK ("review_items"."state" = 'open' or ("review_items"."resolution" is not null and "review_items"."resolved_by" is not null and "review_items"."resolved_at" is not null))
+);
+--> statement-breakpoint
+ALTER TABLE "background_jobs" ADD CONSTRAINT "background_jobs_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "external_links" ADD CONSTRAINT "external_links_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "external_links" ADD CONSTRAINT "external_links_confirmed_by_people_id_fk" FOREIGN KEY ("confirmed_by") REFERENCES "public"."people"("id") ON DELETE set null ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "outbox" ADD CONSTRAINT "outbox_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+ALTER TABLE "review_items" ADD CONSTRAINT "review_items_organisation_id_organisations_id_fk" FOREIGN KEY ("organisation_id") REFERENCES "public"."organisations"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+CREATE UNIQUE INDEX "background_jobs_one_open" ON "background_jobs" USING btree ("organisation_id","kind","dedupe_key") WHERE state in ('queued', 'running');--> statement-breakpoint
+CREATE INDEX "background_jobs_due" ON "background_jobs" USING btree ("state","run_after");--> statement-breakpoint
+CREATE UNIQUE INDEX "external_links_active_external" ON "external_links" USING btree ("organisation_id","system","entity","external_id") WHERE state = 'active';--> statement-breakpoint
+CREATE UNIQUE INDEX "external_links_active_flow" ON "external_links" USING btree ("organisation_id","system","entity","flow_id") WHERE state = 'active';--> statement-breakpoint
+CREATE INDEX "external_links_flow" ON "external_links" USING btree ("organisation_id","entity","flow_id");--> statement-breakpoint
+CREATE INDEX "outbox_pending" ON "outbox" USING btree ("system","state","created_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "review_items_one_open" ON "review_items" USING btree ("organisation_id","kind","entity","flow_id") WHERE state = 'open';--> statement-breakpoint
+CREATE INDEX "review_items_queue" ON "review_items" USING btree ("organisation_id","state","money_at_risk_cents");