The Cash Seam Build Standard

1. What this standard covers

Any business that takes an enquiry, quotes it, does the work, bills it and chases it, with a job system and a ledger underneath. If you are building any two of the four standards below, this is the one that makes them one system instead of four.

• ✓Booked After Hours writes the job on the call.
• ✓Quote Out drafts a quote from that job, priced only from the book.
• ✓Invoice Out raises the invoice from the accepted quote or the completed job.
• ✓Debtor Chasing chases off the live ledger.

Each of those passes on its own, and none of them fails if the id dies between two of them. That is the gap. This standard restates nothing the four already say. Every check below is about what crosses from one to the next: the id, the event that wakes the next step, and the exception with a name on it.

What cannot meet it. A job system with no API cannot hand its job id to anything, so the chain cannot start from it. Tradify is the common case: a Tradify business can run Quote Out, Invoice Out and Debtor Chasing from the ledger alone, with the job entered by a person, but not the seam from the call. The standard says so rather than claiming a link that does not exist.

2. The objects, and what is in them

Five objects, all of them already in the job system or the ledger. The seam adds no table of its own: it adds one field to each record, the id of the record before it, and an owner on every exception.

Enquiry                           # one per call or form
  - id, phone, door (phone | web)
  - duplicate_of (job_id, when it attached to an open job)

Job                               # the job system's record
  - id (issued by the job system; the only key anything downstream uses)
  - customer, phone, status (open | complete)
  - enquiry_ids[]
  - trigger (the event that woke the write)
  - exception { reason, owner } (nullable)

Quote                             # the job system's record
  - id (issued by the job system)
  - job_id                         # the upstream id, never null
  - status (draft | released | sent | accepted)

Invoice                           # the ledger's record
  - id (issued by the ledger; null means the write did not happen)
  - quote_id (the accepted quote, where there is one)
  - job_id                         # always
  - status (draft | released | sent), due_at

Chase                             # a send, not a record of its own
  - invoice_id                     # read off the ledger in the same run
  - released_by (person) | released_by_rule (rule name)
  - trigger

A Quote with no job_id, an Invoice whose job_id came from a name search, and a Chase whose invoice_id was not in the ledger read before it are the three defects this standard makes visible. None of them is wrong inside its own standard. All three are wrong at the seam.

3. The checks, in order

The order is the claim. Identity comes first because every other check is about carrying it. The null id comes before the chain because a chain that carries a null forward is worse than one that stops. The trigger and the owner come last because they are what keeps the chain moving when nobody is watching, and what stops it safely when something goes wrong.

1. Every downstream step takes its id from the system of record, never from a name or a phone number. Once a job exists, every later step reads the upstream record's id from the job system or the ledger: from the event that woke it, or from a read of that record by id. It never mints its own key and never matches on a customer name or a phone number.
2. One job per enquiry: a repeat call or a second door attaches to the open job. Before writing a job, the build reads for an open job on that customer or number. A repeat call, or the same customer arriving through a second door, attaches to the open job with duplicate_of set. A second job is a fail.
3. A write that comes back without an external id is treated as not written. A write into the job system or the ledger that returns a null or missing external_id did not happen, as far as the chain is concerned. The build escalates it and nothing downstream acts on it: no quote from that job, no send of that quote, no chase of that invoice.
4. The quote carries the job id, the invoice carries the quote or job id, and the chase reads the invoice id off the live ledger. Each record carries the id of the one before it. The quote names the job. The invoice names the accepted quote and the job. The chase names an invoice id the ledger returned when the build read it. A break anywhere in the chain is a fail.
5. A chat or connector confirmation is not a write and not a release. A write counts only when it is read back through the port from the system of record. Every send to the customer, the quote, the invoice and the chase, waits for a release that names a person or a named rule. The model saying it is done is neither.
6. Every hop starts from a named event, and none waits for a chat session. Each hop is woken by a named event arriving by webhook, schedule or polling: job created, quote accepted, job completed, invoice overdue. A build that only moves while somebody has a chat window open fails, and so does one that acts on a chat message as if it were an event.
7. An exception names its owner, travels with the record, and the next step does not pass it. A parked or escalated item names the person who owns it, taken from the owners the business set for that stage. The exception stays on the record, and the next step reads it and stops rather than proceeding past it.
8. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
9. The pass test passes. On the business's own job system and ledger: the same caller rings twice, the quote is accepted, the job completes and the invoice goes overdue. Exactly one job, one quote, one invoice and one chase exist, each carrying the upstream id. A null external id injected anywhere stops the chain.

4. The three handovers

The phone number is allowed in exactly one place: at intake, to find an open job before writing a new one. After that, it is never a key. Two customers share a name more often than anyone expects, and one customer changes their number more often than that.

Every hop is woken by a named event, by webhook, schedule or polling. A chat window is a fine place to ask a question. It is not a trigger, and a build that only moves while somebody has one open stops on the first weekend.

5. When a write comes back empty

A write into a job system or a ledger can return a success code and no id: a timeout after the record was made, an empty body, a rate limit halfway through a batch. A connector can report that it created a quote before the quote exists. In both cases the honest answer is that nothing was written, so the build escalates and the chain stops there.

The test is a read through the port. A record counts once the job system or the ledger returns it by its id. Until then there is nothing to quote from, nothing to send and nothing to chase, and an exception is on the record with the name of the person who owns it. The next step reads that exception and does not go past it.

6. What stays with a person

• ✓Every exception, by the owner the business named for that stage: the job, the quote, the invoice, the chase.
• ✓The release of every send, or the rule a person set that stands in for it.
• ✓Deciding two enquiries are the same job when the number does not say so.
• ✓Everything the four standards it binds already keep with a person: prices, variations, disputes and hardship.

The parts that move

8. Provider: what to stub, and what not to hand-roll

One step not to hand-roll, and it is the same step at every hop: identity from the system of record, and the authenticated single write into the job system or the ledger that returns its id. Everything else is wiring a coding agent builds against the stub in an afternoon.

provider:
  stub:       local.mock_cash_path
  production: office_voice.recover      # Office Voice / Recover, sold as Get Paid
  default:    stub                       # no live mapping in the conformance kit yet

the live steps                       # each named on its own standard
  - the job write and the quote draft: Office Voice Front Desk, sold as
    Booked After Hours
  - the invoice draft and the chase: Office Voice Recover, sold as
    Get Paid

stays local                          # yours, and the standard
  - the open-job read at intake, and duplicate_of
  - carrying each id to the next hop
  - the triggers: webhook, schedule or polling
  - the exception owners per stage, and the release rule

cannot meet the standard
  - a job system with no API, for the first hop. Ledger-only is the
    honest route there.

A vendor selling an end-to-end cash flow is usually selling four screens that each look right. Ask them one thing: when a customer rings twice and pays late, which id is on the chase, and where did it come from?

9. Conformance checklist

Hold a DIY build or a vendor to this. If a box is empty, it is not in production.

• ✓1. Every downstream step takes its id from the system of record, never from a name or a phone number. Once a job exists, every later step reads the upstream record's id from the job system or the ledger: from the event that woke it, or from a read of that record by id. It never mints its own key and never matches on a customer name or a phone number.
• ✓2. One job per enquiry: a repeat call or a second door attaches to the open job. Before writing a job, the build reads for an open job on that customer or number. A repeat call, or the same customer arriving through a second door, attaches to the open job with duplicate_of set. A second job is a fail.
• ✓3. A write that comes back without an external id is treated as not written. A write into the job system or the ledger that returns a null or missing external_id did not happen, as far as the chain is concerned. The build escalates it and nothing downstream acts on it: no quote from that job, no send of that quote, no chase of that invoice.
• ✓4. The quote carries the job id, the invoice carries the quote or job id, and the chase reads the invoice id off the live ledger. Each record carries the id of the one before it. The quote names the job. The invoice names the accepted quote and the job. The chase names an invoice id the ledger returned when the build read it. A break anywhere in the chain is a fail.
• ✓5. A chat or connector confirmation is not a write and not a release. A write counts only when it is read back through the port from the system of record. Every send to the customer, the quote, the invoice and the chase, waits for a release that names a person or a named rule. The model saying it is done is neither.
• ✓6. Every hop starts from a named event, and none waits for a chat session. Each hop is woken by a named event arriving by webhook, schedule or polling: job created, quote accepted, job completed, invoice overdue. A build that only moves while somebody has a chat window open fails, and so does one that acts on a chat message as if it were an event.
• ✓7. An exception names its owner, travels with the record, and the next step does not pass it. A parked or escalated item names the person who owns it, taken from the owners the business set for that stage. The exception stays on the record, and the next step reads it and stops rather than proceeding past it.
• ✓8. It survives the builder. Someone other than the builder can explain what it does, and it runs on an account the business owns.
• ✓9. The pass test passes. On the business's own job system and ledger: the same caller rings twice, the quote is accepted, the job completes and the invoice goes overdue. Exactly one job, one quote, one invoice and one chase exist, each carrying the upstream id. A null external id injected anywhere stops the chain.