Run the company lab: a quote, a lost receipt and a partial payment

I wanted the series to contain something you can execute without configuring cloud accounts or handing an agent access to your inbox. The reading kit therefore includes a compact Python implementation of the contracts we have been discussing.

The scenario is deliberately ordinary: qualify an enquiry, prepare a quote, stop for review, dispatch through a simulated provider, lose the acknowledgement, restart the local store and reconcile. Then apply a deposit event twice and verify that the remaining balance is still correct. If those operations are understandable, the larger architecture becomes much easier to reason about.

Download and run

Download the reading kit from the series page and extract it. Use Python 3.10 or newer. The examples use the standard library, local temporary storage and fictional records; they make no external network calls.

cd examples
python3 -m company_lab.demo
python3 -m unittest discover -s tests -v
python3 operating_lab.py

The first command prints the end-to-end result. The second runs the 62-test reference suite. The third runs the original single-file lab and its 18 checks. The two labs overlap in some concepts; they are separate teaching implementations, not 80 distinct production guarantees.

{
  "lead_score": "62.00",
  "qualified": true,
  "episode": "AWAITING_APPROVAL",
  "after_timeout": "UNKNOWN",
  "after_restart": "CONFIRMED",
  "provider_effects": 1,
  "outstanding_minor": 400000,
  "external_network_calls": 0
}

The numbers come from the supplied fixture: a S$6,000 quote and S$2,000 deposit. They are test inputs and observed local outputs, not business-impact metrics.

Follow the package by responsibility

These are paths in the public downloadable lab. The implementation is separate from the internal platform and contains no client source or credentials.

Inspect the state transition first

The store creates an object at version one. A change must name that version. The store then writes the new object, history and outbox event in one transaction. A stale writer fails rather than replacing another decision.

from company_lab.store import Store, Conflict

store = Store()
store.create("studio", "opportunity-017", "opportunity", {"state": "QUALIFIED"})
updated = store.change("studio", "opportunity-017", 1,
    {"state": "QUOTE_REVIEWED"}, "review-017", "quote.reviewed")
assert updated["version"] == 2
try:
    store.change("studio", "opportunity-017", 1,
        {"state": "OTHER_TERMS"}, "review-018", "quote.reviewed")
    raise AssertionError("stale update should fail")
except Conflict:
    pass

The fixture's reviewed state is not a complete approval system. The original single-file lab demonstrates version-bound review in more detail. A live API must authenticate the actor, apply the relevant policy and bind approval to the exact action before reaching dispatch.

Inspect the uncertainty boundary

The connector records UNKNOWN before calling the provider. The fixture creates a message, then deliberately loses the acknowledgement. On the next call, dispatch consults the existing receipt and looks up the provider operation. It does not blindly send again.

If lookup finds no evidence, the reference retains uncertainty. That conservative choice avoids claiming that absence from one lookup proves the original request never succeeded. A real adapter needs the provider's actual retention, consistency and idempotency guarantees to decide what happens next.

The demo closes and reopens the SQLite connection between attempts. The fake provider remains the same fixture object, representing an external system whose state survives the local worker restart. This is a store-restart exercise, not a full distributed crash test across separate machines.

Change one condition at a time

Try a new payload under the same operation ID. The digest check should reject it. Change the tenant and verify that the local receipt is separate. Expire a lease, let another worker claim it and verify that the old epoch cannot finish the job.

For the invoice, repeat an allocation with a different amount. The rule should request review. Change the currency and observe the same boundary. These changes are small enough to understand and directly connected to business consequences.

from company_lab.business import outstanding, Review

try:
    outstanding(600000, "SGD", [
        ("deposit-1", 200000, "SGD"),
        ("deposit-1", 250000, "SGD"),
    ])
    raise AssertionError("conflicting receipt should fail")
except Review:
    pass

What the tests do not establish

The package does not authenticate users, send email, transfer money, implement all fourteen workflows or deploy a cloud service. Its pure business functions assume validated inputs beyond the checks shown. Its fake provider has known idempotency semantics; real connectors require separate conformance tests.

The scripted model demonstrates control flow. It does not show that a language model will choose the correct action. To measure that, implement a model adapter, retain the same tool and action boundaries, run a versioned scenario set and report the observed outcomes and cost.

The next implementation step is one live read-only connector in shadow mode. Preserve the local fixtures as regression tests, add provider-specific cases and keep external writes disabled until review and recovery are exercised. The lab is useful when it gives you a small contract you can explain, test and carry into that next step.