Underwriting Calculator: Addi Architecture Disclosure

Overview · Modules · Underwriting Calculator

What it is

Where a deal's numbers get decided

The underwriting calculator is where a deal's numbers get decided. One shared engine serves both the human working the calculator on screen and the agent working the same deal over its connection; there is no second math path, so a number the agent quotes and a number the operator sees can never disagree by construction. Strategies are data, not code: multiple financing strategies, configured per tenant as data, shape what the calculator asks for and what it computes.

Every standard assumption routes through an overridable per-deal template. We label defaults as defaults, always, because markets differ and a silently trusted default is how an underwrite goes quietly wrong. Under every number sit plain words saying where that number came from, and cash-to-close is itemized to zero, so nothing rides in an unexplained remainder.

The calculator sits at the end of the evidence chain. It consumes the findings snapshot that reports project into system fields; it never reaches into report internals. When a human has confirmed a value, the write law holds here as everywhere: no machine write lands over it; the machine's better idea arrives as a proposal instead.

The questions it answers

For the investor working a deal

Does this deal work under the strategy I intend, and by how much?
Where did each number in that answer come from, and which ones did I set myself?
Which assumptions are still riding on defaults I have not looked at?
What exactly do I bring to the closing table, itemized to zero?
If the calculator cannot answer, what exactly is blocking it and what fixes it?

Scope and boundaries

What it owns, and what it does not

The unit owns underwriting computation and the per-deal assumption state: strategy selection, the assumption template and its overrides, the computed statement, and the provenance trail under each value. It reads the deal's findings snapshot through the composed contract, never another module's tables. It writes only through its own door. It serves the human surface and the agent identically through the same engine and the same door.

It does not own the findings it consumes (reports do), the fields it seeds from (the deal workspace's findings-to-fields ladder does), or the pipeline consequences of a good or bad result (the pipeline and buy-box units do; a favorable underwrite never moves a deal on its own).

What it is NOT

It is not a spreadsheet dressed up as software: the engine is shared code, not per-deal formulas an operator maintains. It is not a black-box verdict: every number explains itself in plain words. It is not a deal mover: it informs the human decision at the gate and never advances a stage itself.

Withheld by design Tier 3

Formulas, rates, constants, the template's default values, and the strategy selection math are held at Tier 3.

The contract

The unit's public shape

What it is responsible for, how it is written to, what it announces, what it guarantees, and what it refuses. No fields, no schemas, no payloads; that detail is held at Tier 2.

Responsibilities

Compute the underwrite for a deal under the selected strategy from the deal's findings snapshot plus the per-deal assumption state.
Hold the per-deal assumption state: the template-seeded defaults, the operator's overrides, and the provenance of each, so the workbench can say in plain words where every number came from.
Serve the human calculator surface and the agent through the same engine, so the two can never disagree.
Present every computed answer with its provenance in plain words and cash-to-close itemized to zero.
Keep the provenance ladder current: which values are defaults, which a report produced, which the agent proposed, which a human confirmed.

The write door

One door, a small set of commands named by the business action, covering the start of an underwrite, the working of strategies and assumptions, the acceptance of proposals, and re-runs. Human and agent callers use the same door. The door applies the write law before anything lands, and agent output passes the mechanical house-style gate at this door like every other.

Withheld by design Tier 2

The command roster is held at Tier 2, along with all interface detail.

Events announced

Events announce business facts and carry identity plus the fact, never a data dump. The concrete event list is held at Tier 2; the facts below are illustrative of the kind this unit announces: an underwrite was computed for a deal, an assumption was overridden by a human, a proposed value was accepted and stamped human-confirmed, a strategy was selected. Downstream units (the deal workspace, the buy box) react to the fact; they never read this unit's tables.

Guarantees

One answer. The engine is shared; the human surface and the agent compute through the same code, so for the same deal state they see the same numbers.
Labeled defaults. Every assumption still riding on the template says so on its face. Nothing is silently trusted, because markets differ.
Provenance under every number, in plain words. The reader never has to guess whether a value came from a finding, a default, an agent proposal, or their own hand.
The write law. A machine write lands freely into an empty or machine-sourced assumption and never over a human-confirmed one; it queues as a proposal, and acceptance stamps the value human-confirmed.
Snapshot consumption. The calculator reads the findings snapshot through the composed contract. Report internals can change shape without the calculator noticing.
Itemization to zero. Cash-to-close carries no unexplained remainder.
Specific failure. When the calculator cannot compute, the error names the exact blocker and the fix, never a generic apology.

Refusals

It refuses machine writes over human-confirmed values. There is no path around the law for any caller: a machine write over a human-confirmed value queues as a proposal, and nothing else.
It refuses to compute past a blocker and present a confident-looking answer; the honest state is the specific error.
It refuses writes entirely when the module is off for the tenant. Feature off means dead server-side: the door refuses, the jobs deactivate, the notifications drop.
It refuses to move a deal. A favorable underwrite is information at the human gate, never a pipeline action.
It refuses to disclose its internals through this package: formulas, rates, constants, the template's default values, and the strategy selection math are held at Tier 3.

What done means

The gates a change passes

Done is not "the math runs". Done is the live workbench holding up against the real backend in every state it can be in: loading, empty, error, and content. Done is every load-bearing rule expressed as a validator, a typed contract, a server-side check, or a failing test, because a rule that lives only in prose is a rule that will be broken politely. And done is the spec settled before the code: the outcome and the logic that keeps each promise in the cases that would break it, agreed first, with the code mostly transcription.

The program review: does the change keep every promise in the cases that would break it, proven by real tests against the shared engine, not by inspection.
The code review: security, understandability, consistency with the codebase.
The parity gate: the human path and the agent path exercise the same engine in the same tests. A change that only one caller sees cannot pass.
The contract gate: the calculator's reads go through the composed findings contract and its writes through its own door; the typed contracts make most illegal shortcuts loud at compile time, and the boundary itself is held by convention and enforced in review.
The write-law gate: server-side checks, exercised by tests, prove that a machine write over a human-confirmed value queues as a proposal and nothing else.
The reviewer is never the writer. Verification is independent and adversarial by standing rule.

Withheld by design Tier 2

The gate implementation detail is held at Tier 2.

The failing cases

It is a failure if the agent's computed answer and the human surface's computed answer differ for the same deal state.
It is a failure if a default reaches the screen unlabeled, however reasonable the default.
It is a failure if any rendered number lacks its plain-words origin.
It is a failure if cash-to-close leaves a remainder unexplained.
It is a failure if a machine write lands over a human-confirmed value, even once, even improved.
It is a failure if an error state says something went wrong without naming the exact blocker and the fix.
It is a failure if the calculator reads report internals past the findings snapshot, or another module's tables.
It is a failure if a disabled tenant's calculator accepts a write.

Honest-state behaviors

The calculator prefers a smaller true answer to a larger confident one.

Missing input is a named condition, not a zero. If a finding the strategy needs is absent, the workbench says which one and what produces it, rather than computing around the hole.
Defaults confess. An underwrite riding heavily on template defaults looks like one; the operator can see at a glance which numbers nobody has examined for this deal.
Provenance survives editing. When a human overrides a value, the trail shows the override as theirs; when they accept an agent proposal, the value stamps human-confirmed and the write law protects it from then on.
Blocked means blocked, specifically. Every error branch names its exact blocker and the fix.

Where it connects

The spine sections this unit realizes

Section 6, the configuration kernel: strategies and assumption templates are configuration data, published and versioned like everything else.
Section 7, modules and boundaries: one write door, business-named commands, no cross-module table reads.
Section 8, provenance and the write law: the ladder under every value; proposals over human-confirmed values.
Section 9, the evidence chain: the calculator seeds from the findings snapshot, the last link in the one-way chain.
Section 10, the agent as principal: the agent underwrites through the same engine and the same door as the human.