Deal Workspace: Addi Architecture Disclosure

What it is

Where one deal is seen whole

The deal workspace is the single place where one deal is seen whole. It composes everything the platform knows about a property into one surface: the versioned report artifacts, the ladder that runs from immutable findings through editable system fields to operator-authored custom fields, plus the deal's documents, notes, tasks, and its map. Other modules produce the pieces; this unit is where an investor or operator reads them together and works the deal.

The composition principle matters more than the layout. Every element on the workspace reads from a named, typed contract exposed by the module that owns the underlying data. Nothing on this screen reaches into another module's tables. That is not a styling preference; it is what lets storage and internals change underneath while the workspace keeps rendering, and it is what makes the surface auditable: for any value on screen we can say which contract served it and what provenance it carries.

The questions it answers

For the investor or operator standing in front of it

What do we actually know about this deal, and where did each piece come from?
Which values are machine-produced findings, which are fields I may edit, and which are notes my own team added?
Which report versions are current, and has a re-run superseded what I relied on before?
What is waiting on me here: proposals to accept, documents to review, tasks to close?

Scope and boundaries

What it owns, and what it does not

The unit owns the composition of one deal and the write door for the deal-local material an operator authors: field edits, custom fields, documents, notes, and tasks. It does not own the report artifacts it composes; the reports unit does, and the workspace reads them through that unit's contract and shows them in place. What it does not compose, it does not claim either: the verdict belongs to the buy box, the stage to the pipeline board, and the underwriting numbers to the calculator.

One boundary is lane-shaped. The platform runs one codebase across two production lanes, and some review-and-push surfaces inside the workspace are internal-lane only. They are not hidden on the user lane; they are dead there, server-side, because a feature that is off refuses writes rather than merely disappearing from the screen.

What it is NOT

It is not a wiki. Free-form surfaces exist (notes, documents), but the workspace as a whole is a composition of typed contracts, not a page of prose anyone appends to. It is also not the place where analysis happens; it is where the results of analysis are read, corrected through the proper door, and acted on.

Withheld by design Tier 2

Deeper interface detail, including the full surface inventory and its controls, is held at Tier 2.

The contract

The unit's public shape

The unit's contract at shape altitude: what it is responsible for, the one door through which it is written, the events it announces, what it guarantees, and what it refuses. No fields, no schemas, no payloads appear here; that detail is held at Tier 2.

Responsibilities

Compose one deal from the contracts of the modules that own its parts: report artifacts, the findings-to-fields ladder, documents, notes, tasks, and the map.
Own the deal-local material an operator authors on this surface, and own the single write door those authorship actions pass through.
Preserve the distinction between the three layers of the field ladder: immutable findings, editable system fields, and operator-authored custom fields. The workspace renders the distinction; it never blurs it.
Keep internal-lane review-and-push surfaces off the user lane, enforced server-side, not cosmetically.

The write door

Like every module, this unit has exactly one write door, and its commands are named for the business action an operator would say out loud, never for a table operation. The door admits a small set of business-named commands covering the deal-local material this unit owns: field edits, custom fields, documents, notes, tasks, and the acceptance of proposals.

The same door serves the human at the screen and the agent over MCP. There is no second, softer entrance for machines. When the actor is a machine and the target field carries a human-confirmed value, the door does not write; it queues a proposal, and acceptance by a human stamps the value human-confirmed. That is the write law operating at this unit's door, not a special case built for it.

Withheld by design Tier 2

The full command roster and per-command authorization detail are held at Tier 2.

Events announced

The unit announces business facts, not data dumps: that a field value changed and under what provenance, that a document was attached, that a proposal was accepted. An event carries identity plus the fact. Consumers who need the full picture come back through the contract; they do not get the picture pushed at them.

Guarantees

Every value the workspace shows is served by a named contract and carries resolvable provenance: a human, the agent, a report, an import, or a template produced it, and the surface can say which.
Findings shown here are immutable. Correcting the record happens in the editable field layer, through the door, and the edit is attributed.
A human-confirmed value is never silently overwritten by any machine actor, the platform's own jobs included.
Writes refuse cleanly when the module is off for the tenant. Feature off means dead, and dead means the door refuses, not that the button is hidden.

Refusals

It refuses cross-module table reads, in both directions: it does not reach into other modules' storage, and its own tables are not readable by them.
It refuses to move a deal through the pipeline. Stage transitions belong to the pipeline board's door, with its human-approval gates.
It refuses to mutate report artifacts. Re-running analysis creates a new version through the reports unit; the workspace only reads versions.
It refuses machine writes over human-confirmed values, as above, converting them to proposals rather than erroring them away.

What done means

The gates a change passes

Done for this unit is not "the page renders". Done is the composition holding its promises in the cases that would break them, proven on the live surface against the real backend. We hold every build of this unit to the gates below, and we state the failing cases as failures because that is how they are treated: any one of them stops the build.

The contract gate. Every element on the surface is traced to the named contract that serves it. This is checked by reading the code, not by trusting the screenshot: a surface can look right while reading the wrong thing.
The write-law gate. The door's behavior is exercised for both actor kinds. Machine writes into empty or machine-sourced fields land; machine writes against human-confirmed values queue as proposals; acceptance stamps the value. Load-bearing rules like this one are expressed as code, a server-side check and its failing test, never as prose in a document someone is trusted to remember.
The lane gate. Internal-only surfaces are verified dead on the user lane at the server, by attempting the write, not by observing the missing button.
The four-states gate. The live surface holds up in all four states: loading, empty, error, and content. A workspace that only demos well when a deal is fully populated is not done.
The review pair. A program review asks whether the code keeps every promise in the cases that would break it, with real tests as the proof; a separate code review covers security, understandability, and consistency with the codebase. The writer of the change is never its auditor.

The failing cases

A surface element reads raw storage instead of a named contract. The build fails even if the rendered result is identical, because the guarantee we sell is the contract seam, not the pixels.
A machine write lands over a human-confirmed value. This is the one failure we treat as closest to unforgivable anywhere in the platform, and the workspace is where it would hurt most, because this is where humans confirm things.
A finding is editable, or an edit silently mutates a finding. Findings are the immutable end of the evidence chain; if they can be rewritten in place, provenance stops meaning anything.
An internal review-and-push surface answers on the user lane. Hidden is not acceptable; only dead is.
A value renders with no resolvable provenance. An unattributed number on this surface is a defect, not a cosmetic gap.
Any of the four states is missing or broken on the live surface.

Honest-state behaviors

The workspace inherits the platform's honesty doctrine and is expected to show it rather than smooth it over. Empty is rendered as empty, never padded with placeholders that read as data. Where the underlying reports disagree or carry limited confidence, the workspace surfaces what the reports unit says about it; it never averages the disagreement away in the name of a cleaner screen. And when a public record is wrong and a human correction has short-circuited downstream reads, the workspace shows the corrected value with its human provenance, so the reader can see that a person overrode the record and that the override is itself on the record.

Where it connects

The spine sections this unit realizes

Section 7, modules and boundaries: this unit is a consumer of many modules' contracts and the owner of exactly one write door of its own.
Section 8, provenance and the write law: every edit made here is governed by the provenance ladder.
Section 9, the evidence chain: the findings-to-fields ladder the workspace renders is the visible middle of that chain.
Section 5, one product, two lanes: the internal-only surfaces described above.