Coverage: Addi Architecture Disclosure

What it is

The truth about what we hold

Coverage is the unit that tells the truth about our proprietary data assets: for any market area a user cares about, it answers whether our zoning intelligence corpus and our market reference layer actually hold data there. It maintains an honest coverage state per area, at three levels: covered, partial, and not yet. When the answer is not yet, it gives the user a way to ask, and that request becomes a recorded business fact rather than a support ticket lost in email.

We built this as its own unit for a reason worth stating plainly. Our data assets are owned and grown in-house, not licensed feeds, so coverage is genuinely uneven while the corpus compounds. The tempting design is to hide that unevenness behind best-effort answers. We rejected it. Fabricated completeness is worse than an honest gap, because an investor who acts on invented zoning data loses real money, and an investor who is told "not yet, ask us" loses nothing and can ask. Coverage exists so the rest of the platform never has to improvise an answer about what we hold.

The questions it answers

For the investor or operator reading this

Is my market covered, and how much of it?
When the platform says covered, what is that claim grounded in?
What happens when I bring an address in an area it does not hold yet?
How do I request an area, and does that request go anywhere?

Scope and boundaries

What it owns, and what it does not

In scope: the coverage state of the data assets, the surfaces that report it, and the request flow for missing areas. Coverage reads what the data assets actually hold and reports it; it never generates data and never triggers acquisition on its own.

Out of scope: producing the data (that is the zoning data factory and the analysis compute engine's reference layer), and deciding what gets acquired next.

Withheld by design Tier 3

The acquisition pipeline and its prioritization are held at Tier 3.

What it is NOT

Not a coverage map product. We publish states, not the geography of our asset in detail; the shape of the corpus is itself an asset. Counts and maps are deal-contingent and held at Tier 3.
Not an acquisition scheduler. Requests are recorded facts; they do not start pipelines. What gets acquired next is decided elsewhere and held at Tier 3.
Not a data quality report. Quality is enforced where the data is made; coverage only reports presence and extent.

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. Contract shape only; fields, schemas, and payloads are held at Tier 2.

Responsibilities

Hold the coverage state of our data assets per market area, at three honest levels: covered, partial, not yet.
Answer coverage queries for every other surface and for the agent, through a composed, typed read contract, never raw tables.
Record coverage requests: when a user asks for an area we do not hold, that ask becomes a durable business fact with the requester's identity attached.
Keep the reported state consistent with what the assets actually contain. Coverage is a read over reality, not a marketing layer over it.

The write door

One write door, a small set of business-named commands, as everywhere in the platform. The action the door exists for is the coverage request: a user or the agent asks for an area we do not hold, and the ask becomes a durable business fact. The reported coverage state itself follows what the assets actually hold and changes as the assets grow. Every write re-verifies tenant identity like every write in the system, and the door refuses when the module is off for the tenant.

Withheld by design Tier 2

The command roster is held at Tier 2.

Events announced

Events carry identity plus the business fact, never a data dump. The unit announces the fact that coverage was asked for. Downstream consumers subscribe to the fact, not to our tables. A downstream surface can react to the fact without coverage knowing or caring who is listening.

Guarantees

No fabricated completeness. If we do not hold it, the answer is not yet, and that answer is as first-class as covered.
Partial is a real state, not an apology. It is reported as partial everywhere the data appears, so a downstream surface can qualify what it shows.
A recorded request is durable and attributable. Asking is never a dead end.
The read contract is stable: the storage underneath the assets can change (the designed warehouse move) without the coverage answer changing shape.

Refusals

It refuses to guess. There is no interpolated, inferred, or best-effort coverage state; an area is covered, partial, or not yet, on evidence.
It refuses to report an area as covered without the asset behind it. State follows what the assets actually hold; a covered answer always has data behind it.
It refuses all writes when the module is disabled for the tenant. Feature off means dead, server-side, here as everywhere.

Withheld by design Tier 3

One boundary here belongs to this package rather than to the unit. Counts and maps of coverage, the extent and geography of the corpus itself, are deal-contingent and held at Tier 3; the asset's shape is part of the asset.

What done means

The gates a change passes

Done for coverage is not a rendered status badge. Done is: every coverage claim on every surface traces to data the assets actually hold, the request flow is reachable from every place a gap is shown, and the unit behaves correctly in the states nobody demos: the empty tenant, the half-covered market, the request against an area that later comes online.

We hold this unit to the same definition of done as the rest of the platform. The spec settles the outcome and the logic before code; every load-bearing rule here is expressed as code, a typed contract or a server-side check or a failing test, never as prose in a document; and the live surface is verified against the real backend in all four states: loading, empty, error, and content. For coverage specifically, the empty state is not an edge case to survive but the core product moment, because not yet is an answer we expect real users to see.

The program review: does the code keep the unit's promises in the cases that would break them, proven by real tests. For coverage the breaking cases are the honesty cases: a partial area queried at full precision, a state read racing a state change, a request submitted twice.
The code review: security, understandability, consistency with the codebase.
The write-door checks: tenant identity re-verified on every command, module entitlement resolved fail-closed, refusal paths exercised, not assumed.
Independent verification: the writer is never the auditor. The claims this unit makes about what the assets hold are checked by an independent reviewer against the assets themselves, not against the implementation's own read path.

The failing cases

It is a failure if any surface presents an area as covered when the assets hold partial or no data for it. This is the unit's founding rule and the first thing a review checks.
It is a failure if partial coverage renders indistinguishably from full coverage anywhere downstream. The qualifier must survive composition; a consuming surface that drops it fails, not just this unit.
It is a failure if a user can reach a not-yet answer with no way to request the area. An honest gap without a path is half the design.
It is a failure if a disabled coverage module still accepts requests or still renders state. Off means dead server-side, and the review exercises the refusal, not the happy path.

Honest-state behaviors

Not yet is a designed state with real copy, a recorded request flow, and no visual shame. It is the state we expect a growing corpus to show often, so it is built as a front-door experience, not an error page.
Partial says what it means in plain words on the surface where the data appears, so an investor can weigh what they are looking at. This follows the platform's honesty doctrine: data is never presented at finer completeness than it has.
Gaps arrive as named states. When an analysis runs against a gap, the analysis completes fail-soft and the report says which read was thin and why; coverage is the reason that admission is a state the system can name instead of a silence.
A recorded request is durable and attributable; asking is never a dead end.

Where it connects

The spine sections this unit realizes

Section 3, the failure model: unmapped jurisdictions are one of the named failure modes this unit answers.
Section 7, modules and boundaries: coverage is a module like any other, one write door, events for facts, no cross-module table reads.
Section 12, proprietary data assets: the assets whose honest state this unit reports.
Section 11, the compute engine and the warehouse seam: analysis is fail-soft per producer, and coverage is why a gap arrives as an honest state instead of a silent hole in a report.