Registry contract

What a Mapparoo registry means.

Every guide is built from registries — structured records of what the plan says, what the repository shows, and where the two differ. This page is the public contract for those records: the schema for each version, and what each value in them means. If you hold an exported registry, this is how to read it.

Schema versions

Each version is served at a stable address and does not change once published. A change that would break an existing registry is announced on this page before it ships.

v1.3.0 Supported

Accepted by the validator. Current runs emit this version.

Adds plan findings: where the plan disagrees with itself, and where it asks for something no document specifies — each names the statements concerned, and an unspecified request names the documents and versions searched. A finding’s next action can carry its verb (fix now, fix later, decide, no action). Adds the build and test output as run-level evidence, the run a registry’s repository reading was reused from, and the run type. Every earlier field is unchanged.

JSON Schema · /contract/registry/v1.3.json

v1.2.0 Supported

No longer emitted; still accepted.

Adds journeys: the paths a user takes through the product, as the plan describes them. Adds declared Principles — a statement can be marked as a Principle, and each document records how it entered the corpus. Adds the recognised planning-tool layout as a document label. Tightens formats: document and evidence hashes are full SHA-256, dates are YYYY-MM-DD, and every evidence pin gives its location.

JSON Schema · /contract/registry/v1.2.json

v1.1.0 Supported

No longer emitted; still accepted.

Every Plan statement carries a promise class — a checkable promise, an aspiration, or a task claim. Aspirations are recorded separately, with what would make them checkable, and are never raised as findings. The coverage banner gains each document’s original format and genre.

JSON Schema · /contract/registry/v1.1.json

v1.0.0 Frozen

No longer emitted or validated. Kept exactly as published.

The first published contract: the Plan, Build and Gap views; evidence stored once and cited by id; verification recorded as the tier that was eligible, attempted and achieved, with an outcome; and integrity notices for attempted manipulation of the analysis.

JSON Schema · /contract/registry/v1.0.json

Severity

Every finding is assigned one of four severity levels. This is the same rubric published on the severity rubric page.

high · Decide now: A core product promise fails, data loss is exposed, a security issue is plausibly exploitable, or launch is blocked.
medium · Follow up: Real product risk or meaningful divergence that should be addressed before you scale, ship broadly, or hand off — but not an immediate stop-ship.
low · Housekeeping: Hygiene, consistency, or maintainability issues that matter over time but do not block the product today.
info · Evidence supports the plan: Supporting evidence — the audit reports agreement as diligently as divergence. Each supporting finding names the verification tier that supports it.

Examples for each level →

Verification tiers

Verification is recorded as the tier a component was eligible for, the tier attempted, and the tier achieved — never as a single word.

Tier 1: Static presence: what the repository shows, read without running it. Always available. On its own it never raises a component above unverified.
Tier 2: The declared build and tests, executed in the audit environment — for recognised Node and TypeScript configurations. It attaches to a component only through a traceable link: a test file, a build target, or a dependency. Otherwise it is recorded for the run as a whole.

Verification outcomes

What happened when verification was attempted, or why it was not.

not-attempted: Verification was not attempted.
unrecognized-stack: The repository’s stack is outside the recognised set, so only static analysis (tier 1) applies.
unrunnable-suite: A test suite was found but could not be started.
environment-limitation: The audit environment could not provide something the build or tests needed.
failing-test: The declared tests ran, and at least one failed.
build-failed: The declared build ran and did not complete.
build-completed: The declared build completed in the audit environment.
tests-completed: The declared build and tests completed in the audit environment. The strongest result an audit records today.
unknown: No outcome was recorded.

Status vocabularies

Each statement carries a status on one or more dimensions. Each dimension has a closed set of values, listed here.

`requirement` plan view

What the plan says about whether it must exist.

required: The plan says it must exist.
optional: The plan allows it but does not require it.
deferred: The plan puts it off to later.
rejected: The plan rules it out.
unknown: The plan does not say.

`claimed` plan view

What the documents claim about progress. A claim is what the documents say, never something an audit has confirmed.

not-started: The documents claim it has not been started.
underway: The documents claim it is underway.
documented-complete: The documents claim it is complete. No audit has tested that claim.
no-claim: The documents make no claim either way.
unknown: The claim could not be read.

`implementation` build view

What the repository shows.

present: Present in the repository.
partial: Partly present.
trace: Only a trace found — some sign of it in the repository, short of an implementation.
absent: Not found in the repository.
unknown: Whether it is present could not be determined.

The coverage banner

Every guide carries a coverage banner, on every view and in every edition, including editions shared with stakeholders. It can be collapsed to one line; it cannot be removed. It records:

Which documents were read, and at which versions.
Which repository snapshot was analysed, and any scope set on it.
What was executed and at which tier — or that nothing was executed, and why.
Which findings the verification pass examined.
The analysis’s own named limits: the limits of its defence against manipulated input, document pages that were not read, and whether every sentence became a statement.
For converted or ticket-style documents: what conversion discarded, and the document’s genre.
For a Plan side: how many checkable promises it holds, how they divide across promise classes, and whether it includes declared Principles — or consists only of them.
For a guide with journeys: how many were read, or that none could be.

What "independent" means

Independent means independent analysis — not a different vendor. Mapparoo runs on Anthropic’s Claude models, the same family many founders build with. What makes the audit independent is how it is built, not who made the model. Your documents and your repository are read separately, with nothing shared between the two readings. The stages that judge and verify see only the validated results of those readings — never your raw documents, never your code, and never any session of the agent that wrote it. The verification pass tries to prove findings wrong, and the guide says which findings it examined. And every run records which model and prompt version each stage used. So no model grades work it produced, in a context it produced it in.