Technical architecture.
This page is for the engineer your estimator forwards the link to. It is the command, the files a run writes, the hash that identifies it, the schema a finding has to satisfy, the boundary between the model and the arithmetic, and the tests that hold that boundary in place. Nothing here is a summary of the code. It is the code, stated.
Command line, local No network in the run path Byte-identical replay Import graph enforced by test
One command. Three files. No upload.
Blueprint is a command line program. You point bre run at a
package model, one or more rule packs and an output directory, and it writes its output
next to your work. The console prints how many items came back, how many are blocking,
and the hash that identifies the run. The transcript below is the
division_seam golden fixture, reproduced verbatim.
$ bre run --model tests/golden/division_seam/spatial_model.json \ --documents tests/golden/division_seam/document_model.json \ --packs packs/division_seam.json --packs packs/scope_boundary.json \ --out out/ 5 risk item(s), 0 blocking. config_hash 27793629219d1c37 wrote out/report.md wrote out/engine_output.json wrote out/placement.json (0 coverage band(s), 0 placed device(s))
The summary line is emitted in exactly that form: item count, blocking count, then the first 16 characters of the run's config hash. The placement line appears only when a spatial model was supplied. A run that loads the seam pack without a document model is refused rather than run, because five seam rules evaluated against nothing would report no findings and look identical to a clean package.
The deliverable
Markdown. Leads with the risk register, then the validation results with their computed values, then the bill of materials as supporting evidence, then the rule trace as the audit record behind both. The run header prints the engine version, the config hash, the seed, the jurisdiction assumed, and every input with its sha256.
The same thing, machine readable
Six top-level keys: schema_version,
run, rule_trace,
risk_register, validation_results and
bill_of_materials. The trace records what fired and what was
suppressed. It validates against the published risk register schema. No wall clock
timestamp appears anywhere in it, because one timestamp would defeat replay on the
first rerun.
Coverage geometry, when there is any
Coverage bands and placed devices. Written only when a spatial model was supplied, because there is nothing to place without one. A run on text documents alone is a first class run: scope boundary findings are read off the words and need no floor plan.
Same inputs, same packs, same seed.
Byte-identical register.
The config hash is a SHA-256 over the sorted input hashes, the pack identities and their versions, the engine version and the seed. It prints on the console, it sits in the run manifest, and it heads the report. Two runs that agree on it produced the same bytes. Two runs that disagree tell you exactly which input moved.
This was verified by running the command above three times into three separate output
directories and diffing the results. All three runs printed
config_hash 27793629219d1c37 and all three output trees are
identical, file for file and byte for byte. Golden tests compare the full output the
same way, and no wall clock timestamp is written anywhere in the output.
This is not a feature for the engineer. It is a feature for the estimator. A finding you cannot reproduce is a finding you cannot take to the design team, because the first question is always "run it again and show me", and a tool that answers differently the second time has ended the conversation.
- config_hash
- SHA-256 over sorted input hashes, pack identities and versions, engine version, and seed. The console prints its first 16 characters; the manifest carries all 64. Sorted, so the order the packs were passed on the command line does not change the run identity.
- seed
- Part of the hash, so a run that changed only its seed is a different run and says so, rather than quietly producing a different answer under the same identity.
- inputs
- Every input recorded by role, path and sha256, with the pack id and pack version where the input is a pack. This is the replay instruction: hand it to somebody else and they can reconstruct the run.
What a risk item carries, and what it cannot be built without.
Every item in the register is one record with thirteen fields, declared in
schemas/risk_register.schema.json and enforced by the model layer
that emits it. The estimator-facing walk through these fields is on the product page.
What follows is the declaration.
| Field | Carries |
|---|---|
| rank | Deterministic position. Severity, then exposure band low, then high, then rule id. The rule id makes the ordering total. |
| rule_id, pack_id, pack_version | Provenance to a published rule at a published version. Rule ids are permanent and never renumbered. |
| severity | BLOCKING, HIGH, MEDIUM or LOW. |
| category | LIFE_SAFETY, SCOPE_GAP, QUANTITY, POWER, INFRASTRUCTURE, DOCUMENT_CONTRADICTION, FIELD_VERIFICATION or EXTRACTION_CONFIDENCE. |
| target | Entity type, entity id and a human label. Named, not described. |
| finding | The statement of what is wrong, in one sentence. |
| rationale | Why it matters commercially, not a restatement of the condition that fired. |
| authority | The code section, standard or manufacturer document the rule stands on. |
| evidence | Citations with document, page, detail or schedule row, and the verbatim quote. minItems 1. |
| computed_values | The numbers a validator actually produced, reported on a pass as well as on a failure. |
| exposure_estimate | An order-of-magnitude band from the pack's own exposure table, carrying its basis, its key and a calibrated flag. Every band shipped today is uncalibrated, and no band is published to customers. |
| recommended_pre_bid_action | One action, specific enough to take today. |
| confidence | Zero to one, never defaulted. Where a finding rests on two extracted statements it is the minimum of the two, not an average and not a lift. |
| review_required | True where the documents do not settle the matter and the honest output is a flag rather than a verdict. |
Evidence is non-empty by construction.
minItems: 1 on the evidence array is not a validation step that
runs after the fact and rejects a bad item. It is a constraint on the type, so an item
with no citation is unconstructable: there is no code path anywhere in the engine that
can produce one, and no reviewer has to catch it. The same constraint applies to a rule
firing record, a suppressed rule record, a validation result and a bill of materials
line. Nothing in the output can assert something without saying where it read it.
A model may read. It may never decide.
A model may read, extract, classify, transcribe, locate and match. A model may never compute a quantity, assign a part number, produce a risk score, or determine compliance. That is the whole architecture in two sentences, and a sentence in a document is not an architecture, so it is asserted by a test.
The import graph, walked
tests/unit/test_architecture.py parses every Python file in
engine/, validators/,
scoring/ and risk/, resolves the
imports at every level of granularity, and fails if any of those packages can reach a
model client, an HTTP client, or the extraction package. Relative imports are resolved
rather than skipped. importlib.import_module and
__import__ with a literal string are resolved too, because
that idiom is already used in this tree.
The benchmark harness is covered too
The directive names four packages and bench/ is not one of
them, because it did not exist as code when the directive was written. The test covers
it anyway. A benchmark is the evidence that the engine works, and a model deciding
whether a flag was correct is a model grading its own homework. The same test also
fails the harness for calling eval or
exec, and fails if the harness has been deleted.
What is on the forbidden list
Vendor SDKs: anthropic, openai, cohere, google, mistralai, ollama, transformers,
litellm. Anything that could reach one: httpx, requests, aiohttp, urllib, http,
socket, asyncio and the rest. Orchestration frameworks: langchain, langgraph,
llama_index, haystack, autogen, crewai. And the quarantine boundary itself,
bre.extraction and bre.narration,
quarantined in both directions.
Where the boundary is kept in the CLI
bre run is the deterministic path and does not import the
model-authored package at all. The one command that can make a model call,
bre chat, imports bre.narration inside
the command body rather than at module level, so the model-authored package is not
even in the import graph of a deterministic run. Where two extraction vendors
disagree, no entity is emitted and the disagreement is surfaced for review. There is
no arbitration and no averaging.
What the suite reports.
A green suite is evidence that the tests ran, not that the code is right. These numbers are stated because they are checkable, not because they are a quality claim. What we publish is measured. What isn't measured is labeled accordingly.
| Measure | Result |
|---|---|
| Python tests passing | 1,419 |
| Skipped | 6 |
| Expected failures | 1 xfailed |
| Python modules | 38 |
| Lines of Python | about 13,700 |
mypy --strict over src/bre and bench | clean |
Rule packs shipped, all jurisdiction: CA-DSA, all pack_version 0.1.0 | 4 |
No accuracy figure, no precision figure and no recall figure appears here, because none exists. The measurement method is published and the scoring harness is written; the results table is empty on purpose until a package has been adjudicated.
The rest of the record.
Published rules
Every check the engine performs, with conditions, rationale and cited authority, taken verbatim from the pack files. The id blocks that are reserved and still empty are listed too.
Inspect the rulesBenchmark method
What will be counted, how a human adjudicates a flag against a change order actually issued, and the rules that stop the benchmark from flattering the engine. Published before any result exists.
Read the methodHow it works
The pipeline end to end: what is read, what is extracted, where the rules run, and which stage of it a model is allowed anywhere near.
Follow the pipelineDiagrams
The same architecture drawn: the module boundaries, the data flow through a run, and where the quarantine sits in the import graph.
See the diagrams