Pricing engine v2

The target data model for Field's price book, quotes and invoices, and the order in which we get there. It replaces the earlier catalogue and quote design notes. The schema comes first; the UI is rebuilt on it, on Field's design system (DESIGN.md).

Status: in progress. Phase 0b (tenancy) and phase 3 step 2 (issued documents, see "Phase 3, step by step") are built, and so are legacy codes as aliases (item_code_aliases, code retirement step 2) and the first part of phase 1 (kit_components, items.type, price() and the price-equality gate; see "Phases"), and quote rows carry the uid next to every code (code retirement step 3, a boot data migration); nothing else here is built yet unless it says so. Pricing configuration names items by uid with the code as fallback (step 4). The price book clean-up (step 5) is a boot data migration behind the price-equality gate, and MCP answers carry no item codes (step 6; HTTP on request, by default once the app stops reading them). Phase 3 step 3 parts one and two are built too: every quote version is also written as quotes, quote_sections and quote_lines rows and checked against what Field shows, and the quote PDF, the quote email's totals, the job's totals and the API and MCP customer pricing are read from those rows, while the files are still written alongside. Phase 3 step 4a is built too (#27): every job's payment schedule, milestone invoices, payments and receipts are also written as rows and checked against what was issued. Step 4b parts one and two are built too (#28): invoices are issued from the issue service, with INV-YYYY-M-N numbers allocated in the issue transaction, and an issued invoice is corrected by a credit note and a new invoice (see "Phase 3, step by step"). Step 4c is built too (#29): milestone defaults and caps come from the organisation's milestone rules, as rows ("Invoices and payments").

The owner's six decisions of 2026-10-12 (from the document audit) are recorded where they change the design: credit notes ("Invoices and payments"), invoice numbers ("Identity"), document bytes and issue versus delivery ("document_events and issued_documents"), claim-line invoices and milestone rules ("Invoices and payments"), and the order of work ("Phase 3, step by step").

Principles #

1. The database is the engine. Prices, kits, quotes and invoices are PostgreSQL rows with keys, constraints and history. No pricing lives in files (quote-catalogs/*.json5, quote.json, rate-card.json) or in code (rule modes, hardcoded recipes, rate cards).
2. Standard trade-estimating model, nothing clever. Price book → kits → quote lines → invoices, the way Fergus, simPRO, Tradify, ServiceM8 and Xero do it. Field drops everything that existed to turn a voice recording into a quote: rules, layers, compiled line items, attestation, transcripts and evidence packs.
3. One way to compute a price. Every number on screen, in a PDF or over the API comes from the same function over the same rows.
4. History is append-only. A price change is a new row, never an edit. What a quote said when it was sent is never recomputed.
5. Freeze by value, link by id. A quote line copies the price it used and keeps the id of the item and price row it came from, so a draft can show what changed and a sent quote never moves.
6. Fail closed. A missing, archived or unpriced item makes the line unpriced. It never becomes zero and never falls back to a default.

Conventions #

These apply to every table in this document.

Names #

• Tables are snake_case plural nouns: items, item_prices, quote_lines. A join or child table is <parent>_<child>: kit_components.
• Columns are snake_case. A foreign key is <table singular>_uid (item_uid, quote_uid). Booleans read as statements: is_sold, is_default. Timestamps end in _at and are timestamptz. Dates with no time end in _on (valid_until_on).
• Enumerations are text with a CHECK constraint, not Postgres enums, so adding a value is a plain migration.
• Money columns say what they are: unit_cost, unit_sell, line_total, subtotal, tax_total, total. Never price on its own.

Tenancy: one database, many organisations #

Field is built to serve more than one business from one PostgreSQL database. Every tenant-owned table carries org_uid (FK organizations, org_…), and isolation is enforced by the database, not by remembering a WHERE:

• Row-level security on every tenant table: USING (org_uid = (select field_org_uid())) and the same WITH CHECK, with FORCE ROW LEVEL SECURITY so the table owner is filtered too. field_org_uid() returns current_setting('field.org_uid') and raises when it is unset, so a query outside an organisation transaction fails instead of quietly seeing nothing; it is also the org_uid default. Each request runs in a transaction that starts with SET LOCAL ROLE field_app (a role without BYPASSRLS or DDL rights) and SET LOCAL field.org_uid from the signed-in user's membership. A query that forgets its filter sees nothing from other organisations, and an insert into the wrong one is refused. Boot refuses a database role on which this would not hold (server/db/README.md "Tenancy and row-level security").
• Uniques are per organisation: (org_uid, lower(code)), (org_uid, number, version). Two businesses can both have MAT-GRAVEL-20MM and quote EQ-2501-01.
• Foreign keys stay inside an organisation. Child tables carry org_uid too, and composite keys ((org_uid, item_uid)) make a cross-tenant link impossible.
• Shared reference data has no org_uid: units, unit_aliases. tax_codes is per organisation, because tax depends on the country.
• organizations (uid, name, slug, clerk_org_id, status, settings) is the directory and has no RLS. users is the person; org_memberships (org_uid, user_uid, role: owner, staff; status: active, pending, disabled) is their place in an organisation, so one person can belong to several. business_settings becomes one row per organisation. Clerk Organizations map one-to-one onto organizations.
• Blobs (photos, PDFs) are scoped the same way: job_files and issued_documents carry org_uid, so a document is only reachable through its owner's rows.
• The default organisation (DEFAULT_ORG_UID, created by migration 0005_tenancy) is the first organisation. Its slug is default on a database created after 0020_neutral_default_org, and stays as it was on an older one. Existing rows were backfilled with its org_uid in phase 0b (migration 0005_tenancy).
• Until jobs are rows (phase 3b), a deployment serves one organisation (FIELD_ORG, else the default organisation): the data directory is not per organisation, so a signed-in person from another organisation is refused. The database layer is already multi-organisation.
• Not schema-per-tenant or database-per-tenant: those multiply every migration, backup and cross-tenant admin task, for isolation that RLS already gives at this scale.

Identity: uid, code, number #

Every row that something else points at has a uid: an opaque, immutable, prefixed ULID (itm_01JB8Z…), generated by the server, never shown as a label, never reused. It is the primary key and the only thing foreign keys reference.

Existing item uids are kept as they are; only new rows get prefixed ULIDs.

Direction change, 2026-10-12: items have a name the operator chooses and a uid the system keeps; there is no second naming scheme. The price book no longer shows or asks for codes. Existing codes are legacy aliases (item_code_aliases, migration 0006): every code an item has had resolves to it, and codes no longer change. They stay until everything that looks items up by code resolves by uid (code retirement, steps 2 to 6 in "Status" above). The TYPE-THING-SPEC format below is superseded and kept only as the record of what was proposed.

A code is the human SKU an estimator types and reads: unique (case-insensitive), editable, and shown everywhere an item is listed. Renaming a code never breaks anything, because nothing links by code.

• Format: upper case letters, digits and single hyphens, ^[A-Z0-9]+(-[A-Z0-9]+)*$, 3–32 characters. Enforced by a CHECK.

• Shape: <TYPE>-<THING>[-<SPEC>], where the type prefix comes from the item's type:

  Type	Prefix	Examples
  material	MAT	MAT-GRAVEL-20MM, MAT-SLEEPER-KENSINGTON-200
  labour	LAB	LAB-GENERAL, LAB-OPERATOR
  equipment	EQP	EQP-EXCAVATOR-5T, EQP-COMPACTOR-500KG
  subcontract	SUB	SUB-PLUMBER, SUB-CONCRETE-PUMP
  fee	FEE	FEE-ADMIN, FEE-DISPOSAL-MIN
  kit	KIT	KIT-WALL-SLEEPER-1000, KIT-GRAVEL-SUPPLY-INSTALL

• The unit is not part of the code (EQP-EXCAVATOR-5T, not EXCAVATOR-5T-HOUR). The item's unit says how it is sold.

• No generated codes (cat_143d45ed…) and no -copy codes. A variant is its own item with its own code and a variant_of_uid link.

A number is a customer-facing document identifier, allocated once, never reused, from a per-type sequence: quotes EQ-YYMM-NN (as today). Revisions of a quote keep its number and add a version (EQ-2501-03 v2).

Decision, 2026-10-12: invoice numbers are INV-YYYY-M-N, from one sequence per organisation, allocated when the invoice is issued (document_number_counters). An invoice connected to a job carries the job number as a required reference. Numbers already issued (EI-…) stay as they are. Decided 2026-10-13: the month is not zero-padded: January 2026 is INV-2026-1-1, October INV-2026-10-2. Numbers are ordered by their period and sequence, never as text (compareDocumentNumbers, server/invoices/numbers.js). Built (#28, step 4b part one): see "How step 4b issues invoices".

Numbers, money and rounding #

Decisions, 2026-10-12:

• GST is worked out once on the subtotal, not per line. Every quote Field has sent did it this way, so the rows reproduce what customers received. With one rate (all GST at 10 % today) that is round(subtotal × 10 %, 2); with several, once per rate group. Per-line GST could differ by a cent or more (three lines of $10.05: $3.02 on the subtotal, $3.03 per line).
• The line total frozen as printed is the official amount. Quote lines carry their rate to four decimals, and a historical version reproduces exactly. A line whose qty × rate does not give the total it printed (a three-decimal catalogue sell the PDF rounded differently, a fixed price no whole-cent rate reaches) keeps that total, marked line_total_source = 'printed' with the reason in line_total_reason. Every other line is computed, and the database checks that it equals round(qty × rate, 2). Rounding catalogue sells with more than two decimals is a separate catalogue decision; catalogue data is not changed.

• One currency (AUD), held on the quote and invoice row, so the model does not have to change if another is ever needed.
• All amounts are stored excluding GST. Tax comes from the line's tax code.
• Display rule for every screen and PDF: money shows 2 decimals; unit cost may show 4 only in the item editor's cost field. The grid shows $1,654.56, never $1,654.5632.
• Markup is (sell − cost) ÷ cost. Margin is (sell − cost) ÷ sell. The grid labels them exactly that way and never mixes them.

Lifecycle and history #

• Rows that something can point at are never hard-deleted once used. They have status (active, archived, and draft where it makes sense) and archived_at. Unused rows can be deleted.
• Every table has created_at and created_by. Mutable tables also have updated_at, updated_by and an integer version for optimistic concurrency (expectedVersion / If-Match).
• audit_log records field-level changes to every catalogue and document table (who, when, old → new, reason). It replaces catalog_history.

Catalogue #

erDiagram
  categories ||--o{ items : groups
  categories ||--o{ categories : "parent of"
  units ||--o{ items : "sold in"
  tax_codes ||--o{ items : "taxed as"
  items ||--o{ item_prices : "priced by"
  items ||--o{ kit_components : "kit has"
  items ||--o{ kit_components : "used in"
  items ||--o{ item_unit_conversions : converts
  items ||--o{ item_suppliers : "bought from"
  suppliers ||--o{ item_suppliers : supplies
  suppliers ||--o{ price_imports : sends
  price_imports ||--o{ price_import_rows : contains
  items |o--o{ items : "variant of"

items #

One row per thing the business prices.

Dropped from today's table: kind (becomes type, 0 of 174 set today), visibility (becomes is_sold), free-text category (becomes category_uid), tags (0 used), price_reference, unit_label (alias text moves to unit_aliases display), cost_mode and sell_mode (become pricing_method), pricing_basis (already an item_unit_conversions row).

categories #

The work sections a quote is grouped by, not what an item is made of. What it is (material, labour, equipment) is items.type, so the two never compete for the same field the way "Materials" and "Walls" do today.

Proposed starting set (for the operator to confirm): Site & admin, Earthworks, Retaining walls, Drainage, Concrete & paving, Landscaping (Lawn, Irrigation, Planting), Demolition & disposal, Haulage.

units, unit_aliases, item_unit_conversions, tax_codes #

Kept as built: typed units with a dimension and base factor, aliases for input, item-specific conversions (1 m³ gravel = 1.6 t), and tax codes (GST 10 %, GST_FREE, INPUT_TAXED).

item_prices (price history) #

Append-only and effective-dated: kept as built, with names tightened.

• The current price of an item is its latest row with effective_from <= now() (ties: latest created_at). A future-dated row is a scheduled price.
• Rows are never updated or deleted by the app. A grant-level rule (REVOKE UPDATE, DELETE) or trigger enforces it.
• The price at any past moment is a query, not a reconstruction: price_at(item_uid, at). A kit's past price is its components' prices at that moment.

Pricing #

One function computes every price: price(item, at) → { unit_cost, unit_sell, markup_pct, margin_pct, price_uid, problems }.

A kit may also be markup (sell = rolled-up cost × markup) or fixed (a set sell price, cost still rolled up). Its cost always rolls up.

Each component counts in its own unit, converted to the component item's unit through units or item_unit_conversions. A conversion that does not exist is a save-time error (UNIT_MISMATCH), not a pricing-time surprise. An archived, missing or unpriced component makes the kit unpriced, never zero.

kit_components #

One table for kits. It replaces item_components and the five empty assembly_* tables, and recipes move here out of quote-catalogs/default.json5.

• No cycles (checked on save), no self-reference, and at most one row per component per kit.
• Measured assemblies with formulas (ceil(length / 2.4)) are not part of v1. Kits priced per unit cover hand-built quotes, and the expression language stays available if a real case needs it. The retaining-wall engine is covered under Quotes.

Suppliers and imports #

Kept as built: suppliers, item_suppliers (supplier code, pack quantity, default supplier) and staged price_imports / price_import_rows with a diff before apply. They are empty today, so the UI hides them until a supplier exists rather than showing empty columns.

Quotes and invoices #

Today a quote is about a dozen files per job. quote.json is built by the voice-recording engine, even for a hand-built quote: createManualJob writes a stand-in transcript and evidence pack, and every save reruns the full build. Prices on a row can come from five override layers. Totals and GST are computed in seven places, and GST comes from a json5 file rather than the item's tax code. v2 makes quotes and invoices ordinary rows.

erDiagram
  quotes ||--o{ quote_sections : "grouped into"
  quotes ||--o{ quote_lines : contains
  quote_sections ||--o{ quote_lines : holds
  quote_lines ||--o{ quote_lines : "kit shows"
  items |o--o{ quote_lines : "priced from"
  item_prices |o--o{ quote_lines : "frozen from"
  quotes ||--o{ payment_milestones : "paid by"
  quotes ||--o{ invoices : "billed by"
  invoices ||--o{ invoice_lines : contains
  invoices ||--o{ payments : "settled by"
  quotes ||--o{ document_events : "history"
  invoices ||--o{ document_events : "history"
  quotes ||--o{ issued_documents : "sent as"
  invoices ||--o{ issued_documents : "sent as"

quotes #

One row per quote version. A revision is a new row with the same number and the next version. The previous row becomes superseded.

Built (#6, migration 0010_quote_rows), with these differences:

• A version is unique per job, (org_uid, job_id, version), not per number. The audit found quote numbers that collide across jobs, so (number, version) is only indexed until numbers come from document_number_counters. The backfill lists any number two jobs share.
• issued_document_uid links the issued document the version was sent as. source_digest is a hash of the files the rows were mapped from, so an unchanged version is not rewritten.
• terms_text and catalog_version are null for rows mapped from files: terms print from the business settings, and quote.json does not record the catalogue version.
• Totals are stored on every version, not only when sent, and are always quoteTotals over the lines being written.
• GST as printed, in one case only. Until GST was rounded exactly (#2), the renderer worked it out in binary floating point. When the exact tax falls on half a cent ($21.15 at 10 % is $2.115), a PDF could print a cent less than exact rounding ($2.11, not $2.12): 3,277 of the first 2,000,000 possible subtotals. Field now shows $2.12 for such a quote. A sent version whose sent copy printed the lower GST keeps it, with tax_total_source = 'printed' and the reason; its subtotal must still equal what Field shows. The service refuses a printed GST in any other case, and new quotes always compute it.
• Sent never changes, in the database. A quote is frozen once it is sent, accepted or declined, or has a sent_at. Triggers then refuse inserting, updating or deleting its sections and lines, changing its number, money, customer or wording, setting it back to draft, replacing its issued document, and deleting it, for the table owner too. Its status may still move on (superseded, accepted, void).

quote_sections #

The groups the customer sees ("Retaining wall", "Drainage"). This replaces organizer group nodes. Sections are flat, ordered and optionally subtotalled.

uid (qsc_…), quote_uid, title, sort_order, show_subtotal (built, with source_node_id, the organizer group it came from).

quote_lines #

Every line stores the values it prints, whether or not it came from the catalogue.

Rules:

• Add from catalogue: the server copies the item's current price into the line and records item_uid, price_uid / price_key. A kit can go on as one line, or as one line with component children for display. The kit line carries the price either way, so component lines never add to the total twice.
• Draft refresh: the server compares each line's price_uid / price_key with the item's current price and lists the lines that changed (old → new). The estimator applies all, some or none. Lines with is_price_override are listed but never changed silently. This replaces the organizer's catalogue diff, and closes the gap where a kit's frozen price went stale, by construction.
• Totals: one function, quoteTotals(lines). It sums line_total over priced, selected lines for the subtotal, works GST out once on that subtotal (round(subtotal × rate, 2) per tax rate, not per line), and adds them for total. The PDF, the email, the list view and the API all read it. There is no per-line tax: it would not add up to the GST charged.
• New lines round their rate. A line added from now on takes the rate rounded to cents, so qty × rate always gives its total and the line is computed. Only lines frozen from documents already issued are printed.
• Send freezes. Sending sets status = sent and stores the totals. After that, a trigger refuses any UPDATE or DELETE on the quote's lines and sections. To change a sent quote, create a new version, which copies its lines into a new draft. Sending needs no lineage or attestation check: every line already holds its own frozen price, so a quote can no longer be refused for missing line-item lineage.

Built (#6), with these differences:

• section_uid is null for a line outside any section (a top-level row). parent_line_uid also puts a row under a note heading, not only a component under its kit.
• is_optional and is_selected are built, because today's "listed only" rows are exactly that: printed with a price, not charged.
• item_uid, price_uid and price_key are not foreign keys. The catalogue can still delete an item a quote used, and a sent line must keep naming it. price_uid holds today's item_prices id.
• unit_code is text, not a foreign key: quote rows carry units the units table may not have.
• tax_code is GST at the quote's rate: today one rate (the catalogue file's gstRate) applies to the whole quote.
• line_tax is not built: GST is worked out on the subtotal (decided 2026-10-12), so a per-line tax would not add up to what was charged.
• line_total_source and line_total_reason record how a line's total was set (see "Numbers, money and rounding").

Invoices and payments #

Milestone invoicing is used on 51 of 65 jobs, so it gets proper tables.

Decisions, 2026-10-12:

• An issued invoice is never revised in place. It is corrected with a credit (adjustment) note against it, then a new invoice. Today's in-place revisions (issuedRevision, revisionHistory, the -R2 and -R3 numbers, reviseJobMilestoneInvoice) migrate as a credit note plus a new invoice (step 4b).
• Numbers: INV-YYYY-M-N, one sequence per organisation, allocated in the issue transaction, with the job number as a required reference (see "Identity"). Numbers already issued (EI-…-M<n>, -R<k>, ER-… receipts) stay exactly as issued.
• Bytes go in document_blobs, with the R2 replica (#12).
• A document is issued when it is finalised. Email is delivery, tracked separately (document_events).
• Milestone invoices show claim lines, one per milestone, each referencing the quote ("Deposit, 50 % of EQ-2501-03 v2"), not the full quote schedule.
• Milestone defaults come from account rules by contract value, entered as data and never hard-coded, with per-job overrides that are visibly marked. A rule can cap a milestone, and each cap either warns or blocks issuing. An example rule set for a South Australian builder: a deposit of at most $1,000 under a $20,000 contract value, and at most 5 % from $20,000.
• GST is worked out once on the subtotal per tax rate, in integer cents, half up (shared/money.js taxOnSubtotal). Money columns follow "Numbers, money and rounding".

• payment_milestones: uid, quote_uid, label ("Deposit", "On completion"), percent or amount, sort_order. Defaults come from the account's rules.
• invoices: uid (inv_…), number (INV-YYYY-M-N), quote_uid, job_id (the required reference), milestone_uid null, kind (deposit, progress, final, variation), status (draft, issued, paid, void), issued_on, due_on, subtotal, tax_total, total, amount_paid. An issued invoice is frozen the same way a sent quote is, and is corrected only by a credit note.
• credit_notes: an adjustment against one issued invoice, with its own number, lines and issued document (document_type credit_note).
• invoice_lines: the same shape as quote_lines (iln_…). A milestone invoice has claim lines, one per milestone ("40 % deposit on EQ-2501-03 v2"), each pointing at the quote.
• payments: uid, invoice_uid, amount, paid_on, method, reference. Receipts are generated from payments.

Built (step 4a, #27, migration 0013_invoice_rows), with these differences:

• payment_milestones belongs to the job (job_id, sort_order = today's milestone index) and points at the quote version it bills (quote_uid, null while that version has no rows). It keeps due_days, and is_default_schedule is ready for step 4c. Nothing today is known to come from account rules, so it is false.

• invoices keep their numbers as issued (EI-…-M<n>, EI-…-M<n>-R<k>). INV-YYYY-M-N arrives with step 4b. status also has credited: a revision that was superseded in place is its own row, credited, and its successor names it in supersedes_invoice_uid, until step 4b adds the credit note that corrects it. A revision returned to draft (unsent, or marked unpaid) is void; re-issuing the same content restores it under the same number. revision, quote_version (with quote_version_inferred for an invoice from before revisions were tracked), issued_at, issued_document_uid and reference (the job number; required from step 4b) are columns. tax_total_source works as on quotes: a milestone's GST is its share of the quote's GST, so where that differs from GST on its own subtotal the invoice keeps the GST it was issued with, printed, with the reason.

• invoice_lines hold what the invoice PDF claims: one claim line, the milestone's share of the quote ex GST, against the quote. Since step 4b that is all the PDF claims; invoices issued earlier also printed the quote's schedule, which is the quote's rows.

• credit_notes and credit_note_lines exist with their checks and triggers. Step 4b writes them (see "How step 4b credits an invoice").

• payments belong to the invoice they were recorded against (sourceInvoiceNumber), keep voided_at, void_reason and voided_by, and are never deleted. A payment the files drop ("mark unpaid" clears them) is voided. An invoice's amount_paid is the sum of its active payments.

• receipts are one per payment. Today a receipt is issued for a milestone once it is paid in full. Its row is for the payment that cleared it, with the amount it acknowledges, and is voided if that payment is. Built (step 4c, #29, migration 0022_milestone_rules): milestone rules. The owner's decisions (2026-10-13): rules are settings, never code, so Field gives no legal or business advice; a rule set for a region is the organisation's and only an owner changes it, in Settings; a job's own schedule is an override; each cap is hard (blocks issuing) or soft (alerts).

• milestone_rules: one row per band of contract value in one region: country (ISO 3166-1, null for every region) and region (a state or province, null for the whole country), min_value (inclusive) and max_value (exclusive, null for no upper end), value_basis (inc-gst, the default, or ex-gst), name, note (why, shown in cap messages) and sort_order. Two bands in one region may not overlap. milestone_rule_milestones are its default milestones (label, percent or amount, due days); none means Field's default schedule. milestone_rule_caps are at most one per milestone kind (deposit, progress, final, variation, as invoiceKind names an invoice): max_percent of the contract value and/or max_amount, the lower applying, and mode hard or soft. business_settings gains country and region.

• Which rule. A job's region is its site address when that names a state (shared/regions.js), else the business region (Settings, else the business address). Of the rules whose band holds the contract value (the quote total with or without GST, as the rule says), the most specific region's applies: the state, then the country, then every region.

• When it applies. The first time a job's milestones are created (the job lands, or "Set up invoices") with no schedule of its own, the rule's milestones become its schedule, marked source.kind: "rule" beside it (and payment_milestones.is_default_schedule). A schedule set on the job (the quote editor, generate, MCP patch.paymentSchedule) is an override, source.kind: "override", naming the rule it departs from; applyAccountRule puts the rule's schedule back. A schedule from before rules, or with none, has no source and is never re-marked.

• Caps at issue. Before an invoice is issued (authorised, sent, credited and reissued), the caps of the rule that applies to the job now are checked against what it issues. A hard cap refuses the issue, before any number is allocated, with a message that names the rule and what it allows (409 MILESTONE_CAP_EXCEEDED, with findings). A soft cap issues it, and the alert is kept with the invoice: on its revision in the files (milestoneRule, with whether the schedule was the rule's or an override) and in its issued document's details. GET /api/jobs/:id/milestone-rules shows all of it before issue. An invoice already issued keeps what it was issued with: rules that change later never touch it.

• Issued never changes, in the database. Once an invoice or credit note has an issue time, triggers refuse any change to its number, money, lines or issue time, setting it back to draft, and deleting it, for the table owner too. Its status, amount paid, due date, kind and note may change, and links missing when it was written are filled once. Payments may only be voided, once; receipts may only be voided. TRUNCATE is always refused.

document_events and issued_documents #

Built (migration 0009_issued_documents). Every document a customer was issued has its own uid, its exact bytes and an append-only history. In this step the job files are still the source of truth: the tables are filled alongside them and read only by the by-uid routes.

• document_blobs: the bytes. sha256 (primary key per organisation), byte_length, content_type, bytes (bytea), created_at. The database checks that the hash matches the bytes. This is not durable storage's field_blobs: that table mirrors the data directory, has no organisation and is retired in phase 3b.
• issued_documents: one row per document as issued. uid (doc_…), job_id, document_type (quote, invoice, receipt, credit_note), number as printed (EQ-2501-01 v1, EI-2501-01-M1, EI-2501-01-M1-R2, ER-2501-01-M1; a quote's number carries its version, because the quote number alone is shared by every version), quote_version, revision, issued_at, issued_by, pdf_sha256 (a foreign key into document_blobs), source (live, ledger-backfill, invoice-revision-backfill, legacy-sent-attachment, legacy-stored-version) and details (frozen business, customer and money details where they were known). (org_uid, document_type, number) is unique.
• document_events: uid (dev_…), issued_document_uid (null for an event with no issued document, such as an email that failed before its document was issued), job_id, document_type, event (created, issued, emailed, email_failed, paid, voided, credited), at, by, data (recipients, Gmail message and thread ids, the delivery attempt) and an idempotency_key, so a retried write adds nothing.
• document_number_counters: (org_uid, document_type, period) and last_value. The invoice issue service advances the invoice counter (period YYYY-MM, zero-padded so periods compare in order; the printed number drops the zero) inside the issue transaction (step 4b). Quotes and receipts do not use it yet.

Rules:

• Issued once, never changed. Triggers refuse UPDATE, DELETE and TRUNCATE on blobs and events, and on every issued_documents column except details, for the table owner too. field_app is granted no more.
• A document is issued when it is finalised; email is delivery (decided 2026-10-12). The issued event and the emailed event are separate facts. Step 2 records both and does not change when today's code considers something issued: a quote is issued when it is emailed, an invoice revision when it is frozen. Since step 4b an invoice is issued at finalisation by the issue service, and its emails are emailed or email_failed events that carry the hash of the bytes sent. Quotes follow with documents built from rows.
• Same number, same bytes, or refused. Recording a number again with the same bytes is a no-op. A resend that renders the PDF again keeps the issued document as it was and stores the bytes that were sent with its emailed event (bytesMatchIssued: false).
• The byte store is an interface. server/documents/blob-store.js is the only code that touches document_blobs, through put(bytes) → sha256 and get(sha256) → bytes.
• A locked R2 replica (#12, built, migration 0012_document_replicas). PostgreSQL stays the store of record. With FIELD_DOCUMENT_REPLICA=r2, each blob is copied after its issue transaction commits to a Cloudflare R2 bucket with a bucket lock, at <org_uid>/<sha256> (server/documents/replicator.js). The copy is create-only: HEAD first, an object with the same size and hash counts as done, different bytes are an integrity alarm, never an overwrite. A scheduler tick retries with backoff and backfills older blobs a few a minute. document_blob_replicas records r2_replicated_at, attempts and the last error code per blob. Reads stay on PostgreSQL and fall back to R2, hash-checked, only when PostgreSQL cannot give the bytes. npm run documents:verify-r2 checks every issued document is in the bucket with its hash. Operating it: docs/REPLIT.md "Issued documents in R2".

These tables replace quote-issuance.json and its issued-documents/ folder, the issued-PDF fields on milestone-invoices/state.json, the legacy sent-quote lookup, and later quote-lifecycle.json, sent-emails.jsonl and the quote_snapshots table. How they are filled today, and what moves next, is under Phases.

Business settings #

business_settings (one row) holds the business name, ABN, bank details, default terms, quote validity days and numbering prefixes. Built so far (migration 0016_business_settings, #28): one row per organisation with credit_note_on_reissue (see "How step 4b credits an invoice"); the rest is still config. All of these come out of quote-catalogs/default.json5, whose gstRate is replaced by item tax codes.

Everything else moves to tables too #

Quotes are not the only thing kept as files. Jobs, invoices, logs, the email outbox and tokens live as JSON files in the data directory, with a SQLite field.db as the job index and notes store. Since the Replit cutover all of it is mirrored into PostgreSQL as opaque blobs (field_files, field_sqlite_images). That makes the files durable, but they still can't be queried, have no foreign keys, are saved several files at a time rather than in one transaction, and have no field-level history. The end state is every record a row, and files only for documents.

What stays a file: photos, uploaded attachments and every PDF a customer received. Each is stored once by SHA-256 and referenced by a row (job_files, issued_documents). Issued PDFs are in document_blobs, a table of their own behind a two-call interface, not in durable storage's field_blobs (see document_events and issued_documents). Writes go through one service per aggregate (job, quote, invoice, email) in a single database transaction, and every change is recorded in audit_log. Once nothing reads the data directory, durable storage's file mirror (server/storage/) and the per-job generation locks are retired.

What goes away #

Hand-built quotes run through all of this today, and none of it is needed once quotes are rows. The figures are approximate lines of code when this plan was written.

That is roughly 30k lines removed, against perhaps 5k of new tables, services and tests.

Moving today's data #

Production on 2026-10-11 has 174 active catalogue items and 57 jobs (65 job folders) with 541 catalogue-linked rows, 611 manual rows, 84 groups, and 51 jobs with milestone state (6 issued invoices). The catalogue data problems behind the price-book noise:

Rules for the migration:

• No price values change except rounding sells to cents, which is recorded. Codes, types and categories are applied from a proposal file that the operator approves first: proposed changes are written to a CSV, reviewed, then applied in one transaction behind a point-in-time restore point.

• Uids never change, so every existing link survives.

• Quotes: every job's current quote and each version becomes quotes, quote_sections and quote_lines rows:

  • Organizer groups become sections.
  • Organizer rows become lines, with their frozen values as printed.
  • Catalogue links become item_uid and price_uid.
  • Engine lines (10 jobs) become custom lines.
  • Sent versions arrive as sent with their stored PDF in issued_documents.

  The migration verifies, per quote, that the new totals equal the totals on the PDF the customer received, to the cent. Any mismatch is reported and refuses the migration. Built as scripts/backfill-quote-rows.js (#6; see "Phase 3, step by step"), which refuses per job, and run at boot as a data migration (#36).

• Milestone state becomes payment_milestones, and issued revisions become issued invoices with their stored PDFs. Built as scripts/backfill-invoice-rows.js (#27), which verifies every issued invoice against its PDF and refuses per job, and run at boot as a data migration (#36).

• The old files stay read-only in the job folder until the watch period ends.

Price book UI #

Built on Field's design system (DESIGN.md), not inline styles. The price book at /pricing (client/src/features/catalogue/) uses the fx- primitives; this plan was written against the older kit in client/src/components/field/, whose parts it names:

• the grid is DataTable, HeaderCell, Row and Cell (numeric, mono), with formatMoney (always 2 decimals) and formatPercent;
• the item pane is a docked SideDrawer;
• the filters are SegmentedControl, Select, FilterChip and SearchField;
• statuses are StatusBadge.

Light and dark mode both come from the kit's tokens. Filled controls use --t-primary and --t-on-primary, and screens never hard-code a colour.

What is wrong today, from the price book at /pricing:

• Engine noise in every row: generated codes, kit-6 badges, + tags under every name, mode words (fixed, kit) in the Markup column, and empty Supplier and Variant columns.
• Inconsistent numbers: $1,654.5632 next to $132.00, and margin without a clear basis.
• Categories: a strip of free-text chips that mixes types and trades, plus an "Uncategorised" bucket.
• Two catalogue editors: the Price book tab, and an Item editor tab that embeds the quote sheet's catalogue panel.

The v2 price book:

1. One screen, two panes. The grid on the left; selecting a row opens the item in a right-hand drawer. There is no separate editor tab, and the search box and filters stay put while you drill into a kit.
2. Grid columns (default): Name · Type · Unit · Cost · Sell · Markup % · Margin %. Optional: Category, Supplier, Last changed, Status. Money is right-aligned, monospaced, always 2 decimals. Kits show a small kit icon after the name, not a text badge. Empty optional columns are hidden, not filled with dashes.
3. Filters: a segmented Type control (All · Materials · Labour · Equipment · Subcontract · Fees · Kits), a Category select (the trade hierarchy) and Status (Active · Draft · Archived), plus one search box over name, category, tags and supplier code (legacy codes still match, unseen). The category chip strip goes.
4. Item drawer:
   • Header: name, type, unit, category.
   • Pricing: cost, method (markup or fixed), sell, markup and margin. Editing shows the before → after.
   • Kit components: an inline table with quantity and unit, the component's sell and the extended amount, plus a search to add components without leaving the drawer.
   • "Used in": kits, and draft and sent quotes, so an operator sees what depends on an item before deleting it.
   • Price history: a dated list, and the point-in-time price.
5. Editing keeps your place: renaming does not jump the row (it re-sorts on blur, then scrolls the row into view), and a kit's numbers refresh as soon as a component changes.
6. Bulk actions on a selection: set markup, adjust cost or sell by %, change category, archive. Each shows a preview diff before applying (built).
7. Quote builder picker: the same search component, dockable instead of a fixed popup. Adding a line shows its frozen price, and a draft shows a "N prices changed" banner with the diff.

Phases #

Each phase is one or more PRs. Each ends with production working and the offline quote and invoice proof passing (npm run qa:quote-invoice-proof).

Phases 1–2 and 3–4 can overlap. 5 builds on Field's design system (DESIGN.md).

Phase 1 as built (part one) #

Built (migration 0007, server/catalog/price.js):

• kit_components (was item_components; kit_uid, component_uid).
• items.type with its check; kits typed from their components. Item rows carry type, is_sold and pricing_method.
• items.notes: internal notes, separate from the customer-facing description.
• The empty assembly_* tables dropped.
• One identity: legacy codes are aliases and never change (migration 0006). This replaces the code format CHECK, which the 2026-10-12 direction change retired with codes.
• price() and the price-equality gate (npm run catalog:price-gate).

Not built yet, and why:

• category_uid: the category name is unique per organisation and already the key the price book, bulk edits and imports use; the category tree lands with the clean-up's categories, as rows with parent_id.
• Money precision (numeric(12,2) sells): 84 production sell rows carry more than 2 decimals, so narrowing the column would change prices. That needs its own decision; until then price() returns sells as stored. Quote lines carry rates to four decimals (decided 2026-10-12), so quote rows do not wait for it, and catalogue data is not changed.
• pricing_method as a column, and dropping kind, visibility, tags, price_reference, cost_mode and sell_mode: the price book redesign still reads them. The API serves the new names alongside; the columns go once nothing reads the old ones.
• waste_pct and show_on_quote on kit components: the roll-up does not apply waste and quotes do not show components from rows yet (phase 3), so the columns would be promises nothing keeps.
• Recipes out of json5: the lawn, irrigation and drainage recipes are measured formulas, which kit_components deliberately cannot express (see "kit_components"); they leave with the engine in phase 4.
• audit_log (replaces catalog_history, which works) and business_settings (read by quote documents): they arrive with phases 3 and 3b, which are their first readers.

Phase 3, step by step #

Phase 3 is several PRs. Each one is additive and leaves the quote and invoice proof byte-identical. The steps follow the rebuild order the owner set on 2026-10-12: document store, quotes as rows, invoices as rows, then jobs and the rest. Work starts now, beside the catalogue work.

How step 2 fills the tables:

• Live. After a quote, invoice or receipt email is committed (server/job-actions.js, finalizeAndProjectDelivery), the issue service records the document with the exact bytes that were attached and an emailed event with the Gmail message id. An invoice revision is also recorded when the generation that froze it commits, whether or not it is emailed. A failed email is an email_failed event. None of this can fail a send: an error is logged and counted in GET /api/storage/status (issuedDocuments). Without a database it is skipped with a log line.
• Backfill. node scripts/backfill-issued-documents.js [--dry-run] walks every job and records the issuance ledger, every issued invoice revision (superseded ones too) and quotes sent before the ledger, with their original bytes. Each file's hash is checked against its record; a mismatch is reported and skipped, never repaired. A second run records nothing new. It is not yet a boot step of the data-migration runner (server/data-migrations/); it becomes one after its first production dry run.

How step 3 part one fills the quote tables (server/quotes/). The job files stay the source of truth, and nothing reads the rows yet.

• Mapping (from-artifact.js). A version's rows are its customer schedule as the renderer resolves it, each row with the values it prints. A top-level organizer group is a section; a nested group is a note heading. A catalogue-linked row is an item line with the row's item uid, price id and price key. Manual and engine rows are custom lines. Rows under a priced row (kit components, engine breakdowns, rows under a fixed price) are component lines, shown and never counted. A group with a fixed price is one custom line at that price. Every line keeps the total it printed and the row's own rate to four decimals; the total is computed when qty × rate gives it and printed, with the reason, otherwise (an amount today's renderer rounded in floating point, a fixed price no whole-cent rate reaches). A fixed price on a row keeps the row's quantity and takes the whole-cent rate it works out to, when there is one; the rate the PDF printed goes into override_reason. "Listed only" rows are optional and not selected. Rows excluded from the price are left out, because the PDF does not print them.
• Status (job-quotes.js), from the evidence the rest of Field uses. The newest version that was emailed (the issuance ledger, or before it the send fields) is the customer's: accepted when the job is landed, declined when lost, otherwise sent. Other emailed versions are superseded, older unsent ones superseded, the newest unsent one draft. A version only moved to Sent by hand is not sent (it is accepted or declined when the job is landed or lost).
• Checks (sync.js). quoteTotals over the rows must equal the totals Field shows to the cent (the renderer's subtotal, GST and total, which the PDF prints); lines kept as printed are listed as warnings. A sent version must also equal the totals on the PDF the customer was sent: the issued document's bytes, else the issuance ledger's PDF (or the quote markdown stored with it when the PDF cannot be read), else for a quote sent before the ledger the copy legacy-sent-quote.js finds. Totals are read from the PDF's own text (issued-totals.js), never re-rendered.
• Live. After every committed job generation, the recorder writes the versions that changed. A version that fails a check is not written, its draft rows are removed, and it is counted with both numbers in GET /api/storage/status (quoteRows). After a quote email is recorded, the send path syncs again so the sent version links its issued document. Nothing here can fail a save or a send. Without a database it is skipped with a log line.
• Backfill. node scripts/backfill-quote-rows.js [--dry-run] [--json] checks every job's versions as above and writes a job only when all of its versions pass. A failing job is reported per version with both numbers, nothing is written for it, and the run exits 2. A second run writes nothing new. Without a database, --dry-run checks the files alone. Since #36 production runs it at boot as the data migration 2026-10-13-quote-rows-backfill: every job that verifies is written, each refused job is logged by uid and mismatch kind (the dry run shows the numbers), and the migration is recorded only when nothing is refused, so a later boot retries (docs/REPLIT.md, "The row backfills").
• Every sent PDF's totals reproduce. With the 2026-10-12 decisions (GST on the subtotal, line totals as printed, four-decimal rates), the three cases the first version of this step could not reproduce (GST per line, a rate with more than two decimals, a fixed price no whole-cent rate reaches) all reproduce. What still fails a check is a version whose files disagree with the PDF that was sent, which the backfill reports and never writes.

How step 3 part two reads the quote tables (server/quotes/read-model.js, schedule.js, concurrency.js). The files are still written alongside.

• Display columns (migration 0011). Lines and sections also keep what the documents print besides money: excluded from the price (kept, never printed or counted), amount hidden or blank, collapsed, row style and notes; lines also how the PDF styles them (row_kind), the rate printed beside a fixed price (display_unit_sell) and the cost behind the amount (line_cost, internal). Sections and lines share one sort_order sequence, so the printed order of sections and top-level lines is kept.
• Printed only when exact. The dual-write and the backfill now also check that a version's rows print exactly the schedule its files print (every printed row's label, depth, quantity, unit, rate, amount, style and visibility, and the cost); a version that would not is not written. A sent version written before 0011 keeps its rows and is never printed from them (its PDF is its issued copy anyway).
• Where a read comes from. The version's rows in the database when they were written from the same files under the current mapping; otherwise the rows the files map to (the same rows the dual-write stores; a quote being built renders before its rows are committed); otherwise the files. FIELD_QUOTE_READS=files sends every read to the files, for rollback. Reads are counted by source under quoteReads in GET /api/storage/status.
• What reads them. The quote PDF (built, previewed and sent; receipts still print the quote's schedule from the files, and milestone invoices print claim lines since step 4b), the quote email's totals, the job's cached totals (the job list), and the job detail's customerPricing, which the client and the MCP quote tool read.
• Saves. GET /api/jobs/:id and every quote save answer with X-Field-Quote-Rows-Version ("q<version>-<lock>"). The editor sends it back as If-Match on POST /api/jobs/:id/quote-update; a save against rows that moved on since is refused with 412 (QUOTE_ROWS_CHANGED) inside the job's mutation lock. A request without If-Match (CLI, MCP) is not checked. The save is written to the rows through the quote service before the response, which says so in X-Field-Quote-Rows.
• Not yet. The editor still edits the organizer tree in the browser: its engine rows point at engine line items that rows do not carry until the engine goes (phase 4). It reads its saved totals from the rows through the job detail. Editing rows directly is part three.

How step 4a fills the invoice tables (server/invoices/, #27). The job files (milestone-invoices/state.json) stay the source of truth, and nothing reads the rows yet. No customer document changes.

• Mapping (from-milestones.js). Each milestone is a payment_milestones row. Each issued revision is an issued invoice under its number exactly as issued: the current one issued (or paid), one superseded by a revision credited, one returned to draft void. An invoice issued before revisions were frozen maps from its stored record. A draft milestone is a draft invoice under its provisional number. Totals are as issued and never recomputed. Payments keep their dates, method, reference and void details. A paid milestone's receipt keeps the number it was issued with (ER-…, or RCT-… since step 4b).
• Checks (sync.js). Each issued invoice's subtotal, GST and total must equal its stored revision and, where its PDF can be read (the issued document's bytes, else the revision's stored PDF, hash-checked), the totals the PDF printed (issued-totals.js reads the "This claim" box). Each milestone's active payments must add up to the amount paid Field shows. Issued invoices must not claim more than the quote. Where the drafts were built against an earlier quote, the difference is a warning: Field rebuilds them on the next milestone action. A job that fails is reported with both numbers, and nothing is written for it.
• What was sent decides (#60). Before 2026-08-05, an invoice's milestone record and its PDF could come from different quote versions. Where an issued invoice disagrees with one of its PDFs:
  • Field may hold hash-verified copies of the emailed PDF (an issued document with an emailed event, or an issuance-ledger delivery; sent-copies.js). If they agree, the rows take the emailed amounts, with tax_total_source = printed and a reason that names both versions. That is a warning, not a refusal. Every later sync of an unsettled legacy invoice does the same, so the rows never conflict. A stored PDF that differs from the emailed copy is reported as not the copy that was sent.
  • Without such a copy, the job is refused. Its entry lists the archived emails of the invoice: when it was sent, and the quote version it was built against.
  • An owner settles the invoice through GET/POST /api/admin/invoices/amount-disagreements (amount-evidence.js). A settled invoice's rows carry the settled amounts, as printed, with the decision.
• Live. After every committed job generation, after the quote rows, the recorder writes the job's invoice rows. After an invoice or receipt email the send path syncs again, so the rows link the issued document. A failure is logged and counted under invoiceRows in GET /api/storage/status, and never fails the action. Without a database it is skipped with a log line.
• Backfill. node scripts/backfill-invoice-rows.js [--dry-run] [--json] [--data-dir <dir> | --from-storage] writes every job that passes and refuses the rest (exit 2). A second run writes nothing new. Run the quote-row backfill first, so invoices link their quote versions. Production runs it at boot as the data migration 2026-10-13-invoice-rows-backfill, after the quote rows (#36; docs/REPLIT.md, "The row backfills").
• What does not reproduce exactly. A payment recorded against a revision that was later superseded stays on that revision (that is what the payment record says), so the new revision's amount_paid can be lower than the milestone's amount paid in the files; step 4b's credit note carries it across. A receipt today acknowledges everything paid on the milestone, so its row's amount can be more than the one payment it points at.

How step 4b issues invoices (server/invoices/issue.js, #28, part one). The job files stay the source of truth for everything else; an invoice's number and bytes now come from PostgreSQL.

• When. An invoice is issued when it is finalised: authorised ("Mark as sent"), sent (before the email is attempted), or issued as a revision. persistMilestoneInvoiceState (server/job-actions.js) finds every milestone whose issued revision has no document yet, and issues each one through the service before the job generation commits.
• One transaction. Under the organisation's issue lock (pg_advisory_xact_lock), the service allocates INV-YYYY-M-N from document_number_counters (period: the issue time's month in the server's local time, the date the PDF prints), renders the PDF once with that number and the job reference, stores the bytes in document_blobs with an issued_documents row and an issued event, and writes the issued invoices row and its claim line (migration 0014_invoice_issue: issue_key, a check that such an invoice has its reference and a sequence number, and a sequence number unique in the organisation). After it commits, the R2 replica copies the bytes.
• No gaps, never reused. The counter only moves in that transaction: an issue that fails (the render throws, the job has no job number) rolls it back. The milestone takes the number and the stored bytes are written at its PDF path, so the file and the issued document are the same bytes.
• Idempotent. The issue key names the job, the milestone, the revision and a hash of the money. A retried issue (say the job generation failed after the transaction committed) returns the same invoice, number and bytes and allocates nothing.
• Reference. The job number (the quote's, else the job's, else the job part of the quote number) is the invoice's required reference, stored on the row. With none, issuing is refused. Since #93 the issue also records the line the invoice prints with the quote it bills, "Reference: Job 2610-07 · Quote EQ-2610-07 v2" (no "v1"; the quote number from the quote row), stored with the issued document and sent as its Xero invoice's Reference. Invoices issued before print "Job reference", and so do their reconstructed copies.
• Drafts. A draft is tracked under its provisional EI-…-M<n> and its preview prints "Draft, not yet issued" and no payment reference. After an unsend it goes back to the provisional number; issuing the same content again restores the invoice it was, under its number.
• Email is delivery. The emailed event carries the hash of the bytes sent; a resend sends the stored bytes. A failed email is an email_failed event and never undoes the issue.
• Receipts have their own series, RCT-YYYY-M-N (the month not zero-padded: RCT-2026-1-1), from the same allocator as invoices and credit notes (owner's decision, 2026-10-13). When a milestone that was not paid becomes paid, issueReceipt allocates the number, renders the receipt once with it and the INV-… invoice it pays ("For invoice:" in its details), and stores it as an issued document with its issued event; the milestone carries the number (receiptNumber, issuedReceipt), and sending the receipt sends those stored bytes. The receipt row is written by the dual-write, which names the payment. A milestone that stops being paid (marked unpaid, a payment voided) keeps the issued receipt in its receiptHistory, marked voided, and its row becomes void; paying it again issues a new receipt. Receipts issued before keep their ER-…-M<n> numbers, and a milestone paid before this release keeps its receipt. Until it is paid, a milestone's receipt is tracked under the provisional ER-…-M<n>. A stored receipt that was lost is drawn again with its number, marked "Reconstructed copy".
• Without a database the server installs an issuer that refuses, so authorising or sending an invoice answers 503; invoice and quote sends already need the database for their snapshots.
• Invoice rows. The row the issue writes is mapped exactly as the job's files map it afterwards (mapInvoiceForIssue), so the dual-write finds it unchanged and only fills its links.

How step 4b credits an invoice (#28, part two; migration 0015_credit_notes). An issued invoice is never revised in place.

• Credit and reissue. The operator credits an issued invoice with a reason ("Credit and reissue" in the job's invoices, field credit-invoice, POST /api/jobs/:id/milestones/:index/credit-and-reissue; /revise and revise-invoice are the older names). Field mints the next revision from the current quote, then the issue service, in one transaction under the issue lock: allocates CN-YYYY-M-N (counter credit_note) and INV-YYYY-M-N; renders and stores the credit note's PDF and the new invoice's; writes the credit_notes row (the credited invoice in full, its lines each pointing at the invoice line they credit, the reason, who did it, replacement_invoice_uid) and the new invoice (supersedes_invoice_uid); sets the credited invoice to credited; adds a credited event to its issued document; and moves its payments.

• The credit note PDF is an adjustment note: titled "Adjustment note", the supplier and ABN, the recipient (always printed; the ATO requires it where the original was $1,000 or more), date and number, the original invoice and job reference, the reason, the amount of the adjustment and the GST adjustment, and the price difference between the original invoice and its replacement. Its line says what it credits in plain words ("Credit of INV-2026-10-1: Deposit: 50% of the quoted price"), with the quote on a quieter line ("Quote EQ-2610-03, accepted 14 September 2026"; "revision 2" only when the customer was sent more than one version, and never "v1"; server/invoices/customer-wording.js). Credit notes are numbered CN-YYYY-M-N, the month not zero-padded (CN-2026-1-1). The replacement invoice prints "Replaces" and "Credit note".

• Payments move as allocations. A payment is never changed: a payment_allocations row (append-only) moves it from the credited invoice to the replacement. The invoice that holds a payment is the to_invoice_uid of its latest allocation, else the invoice it was recorded against, and an invoice's amount_paid is the active payments it holds.

• Revisions made in place before credit notes (-R<k>) stay as issued (owner's decision, 2026-10-13). No credit note is invented for them: no client was ever issued a credit note, and an invented one would not match the accounts in Xero. The superseded revision's invoice row is credited with the note "Revised in place before credit notes: superseded by . No credit note was issued." Its payments stay on the invoice they were recorded against; the backfill reports each as a payment-on-superseded warning and changes nothing. Credit notes apply from this release on.

• An invoice returned to draft and reissued (decided 2026-10-13). When an invoice is marked not sent or unpaid and then issued again with different content, it gets a new number, and the account setting creditNoteOnReissue (business_settings, migration 0016_business_settings; Settings, "Quotes and invoices") decides whether the issue service credits the old one first, in the same transaction:

  • when-emailed (the default, best practice): only when Field has evidence the customer was sent it through Field: an emailed event on its issued document, or a delivered send record (a sent quote snapshot of it). With no such evidence it was never delivered, so it is left void and reissued under a new number with no credit note;
  • always: a credit note every time;
  • never: never a credit note; the old invoice stays void.

  The issue service reads the setting and the evidence inside its transaction. "Credit and reissue" always makes a credit note, whatever the setting says: that action is the operator saying the customer has the invoice. Issuing the same content again still restores the invoice it was, under its number, with no credit note.

• Sending the replacement. A credit note is not emailed on its own. Its stored PDF is an issued document of the job (GET /api/jobs/:id/documents, GET /api/documents/:uid/pdf). When the replacement invoice is emailed, the email editor offers "Also attach the adjustment note": ticked, the credit note's stored bytes go with the invoice (attachCreditNote on POST /api/jobs/:id/email-quote). Attaching other Field documents is part of the email editor's redesign.

How step 4b prints a milestone invoice (#28, part three). Only invoices issued from now on change; an issued PDF never does.

• Claim lines, not the quote's schedule. The PDF has one claim line per milestone it bills, in plain words ("Deposit: 50% of the quoted price"), with the quote on a quieter second line ("Quote EQ-2610-03, accepted 14 September 2026", or "sent …" when it was not accepted) and its subtotal, GST and total. "Revision 2" is added only when the customer was sent more than one version of the quote (the job's send history); a customer never sees "v1" (owner, 2026-10-13; server/invoices/customer-wording.js). The invoice rows keep their own line names with the quote version, for the record. Then the claim box ("This claim (ex GST)", "GST (10%)", "Amount Due", the labels issued-totals.js reads) and the quote summary, two columns the width of the claim table: "All amounts include GST" once in its heading, the same quote line, then contract value, previously claimed and this claim, a hairline, and "Remaining after this claim" in bold. Amounts are right-aligned in figures of one width. The quote's schedule is not printed: the quote is its own document.
• A tax invoice. An issued milestone invoice is titled "Tax invoice" and prints what the ATO asks of one: the supplier's name and ABN, the date, the recipient, a description of what is claimed and the GST, with the job reference. A draft preview stays "Invoice" with "Draft, not yet issued".
• A lost PDF drawn again is marked "Reconstructed copy" (owner, 2026-10-13). An invoice issued before step 4b (an EI-… number) is drawn in the layout it was issued with: titled "Invoice", with the quote's schedule and the claim box. One issued from the sequence (INV-…) is drawn in the step 4b layout. An invoice not yet issued always uses the step 4b layout.
• A receipt prints as before, with its number and "For invoice: INV-…" in its details. An invoice for a job with no milestones prints as before.