FMAE Audit Engine — Architecture Overview

Technical-Documentation • — • 4 min read

Audience: Technical Reviewers • Auditors • Integration Engineers
Last Reviewed: July 2026
Updated: Version 1.0

Executive Summary

The FMAE audit engine processes a workbook through five stages executed in a fixed order — parsing and workbook ingestion, dependency graph construction, rule engine execution, risk scoring, and report generation. Each stage consumes the previous stage's output and exposes nothing about how any later stage will use it, so the stages can be documented, tested, and read about independently. This page is the map; the detail behind each stage lives on its own Technical Documentation page as those pages are published.

Key Takeaways

✓ The engine runs a fixed five-stage pipeline — ingestion, dependency graph, rule engine, scoring, report — each stage's output is the next stage's only input.
✓ Rules are registered and executed as a versioned, named rule pack (fmae.structural) through a narrow public interface, not called individually.
✓ The rule engine, scoring methodology, and finding data model are internal to gcc_audit/; the only supported integration surface for code outside that package is a deliberately narrow internal contract, not a public API.
✓ No stage in this pipeline uses a language model or probabilistic inference — every stage is deterministic, and the same input workbook produces the same findings and score on every run.

What This Page Documents¶

This page is the single entry point for how the FMAE audit engine actually processes a financial model, from an uploaded .xlsx file to a finished audit report. It exists so a technical reviewer, an integration engineer, or an auditor validating a specific finding has one place to see how the stages fit together before going to the detail page for the stage they actually need.

Nothing on this page discloses a proprietary detection heuristic, threshold, or algorithm. Each stage below states what it does and why it exists in that position in the pipeline — the conceptual level appropriate for a reader deciding whether, and how, to rely on the engine's output.

The Five-Stage Pipeline¶

The engine runs the same five stages, in the same fixed order, for every audit:

Parsing & Workbook Ingestion — the uploaded workbook is loaded and converted into a structured, internal representation (a manifest): every formula cell, hardcoded cell, and worksheet is identified, and each worksheet is classified into a structural role (an input sheet, a calculation sheet, and so on).
Dependency Graph Construction — a directed graph is built from every formula's cell references, linking each cell to the cells it depends on. This graph is what circularity detection and several structural rules operate against.
Rule Engine Execution — a named, versioned collection of rules (a rule pack) is executed against the manifest and dependency graph. Each rule inspects the model for one specific structural pattern and emits zero or more findings, recorded in the Finding Data Model with supporting evidence and provenance and a coverage disclosure of what the dependency graph was and was not able to resolve.
Risk Scoring — every triggered rule's declared weight is summed and normalized against a fixed basis to produce a single numeric score and letter grade, with specific rules able to override the grade regardless of the numeric score.
Report Generation — the score, the findings, their supporting evidence, and the engine's provenance (which engine version, which rule pack version) are assembled into a structured report.

Each stage is documented on its own Technical Documentation page, and every stage above is published, alongside the Rule Taxonomy the rule engine classifies its rules against, the full Rule Reference, the Integration Surface, and Version History.

Why the Pipeline Is Ordered This Way¶

The ordering is a dependency chain, not an arbitrary sequence. Rule execution (stage 3) cannot run before the dependency graph exists (stage 2), because several rules — including the two rules that detect broken links and error propagation — read graph facts the parser has already computed rather than re-deriving them. Scoring (stage 4) cannot run before rule execution, because a score is a function of which rules triggered. Report generation (stage 5) is the only stage that reads the output of every prior stage at once, which is why it is the last stage and not, for example, run in parallel with scoring.

What the Rule Engine Actually Executes¶

Rules are not called individually. They are registered into a single named, versioned rule pack — fmae.structural, version 1.0.0 — and the engine executes that pack by identity through a narrow public interface (register_rule_pack / execute_rule_pack), rather than through direct access to individual rule classes. This matters for two reasons:

Reproducibility. A finding's provenance records exactly which rule pack version produced it, so a finding from an audit run six months ago can be attributed to the exact rule logic that was live at the time.
Extensibility, stated honestly. The engine's architecture already generalizes beyond one rule pack — the interface does not assume fmae.structural is the only pack that will ever exist — but as of this writing, fmae.structural is the only published, public rule pack. This page does not describe or imply any other rule pack, because none is public today.

Determinism as an Architectural Property¶

Every stage in this pipeline is deterministic: the same workbook, parsed by the same engine version and scored against the same rule pack version, produces the same manifest, the same findings, and the same score on every run. No stage in the pipeline calls a language model, and no finding is the product of probabilistic inference. This is a structural property of the architecture, not a claim added for this page — it follows directly from the fact that every stage above is implemented as ordinary, testable code operating on a structured representation of the workbook, not on a model's interpretation of it.

FMAE Rule Taxonomy — the six-category classification the rule pack's 26 rules are organized under.
FMAE Scoring Engine — SM-2.0 Methodology — the full detail behind stage 4.
Rule Reference — individually addressable pages for each rule executed in stage 3.
What Is a Financial Model Audit? — the buyer-facing definition of what an audit is, for context on why this pipeline exists.

How OXXON tests thisRun a free structural check with FMAE

Frequently Asked Questions

How does FMAE's audit engine work end to end?

A workbook is parsed into a structured manifest, a formula dependency graph is built from that manifest, a versioned rule pack executes its rules against the graph to produce findings, the findings are scored against a fixed weighted basis, and a report is assembled from the score, findings, and supporting evidence.

Does FMAE use a language model anywhere in this pipeline?

No. Every stage described on this page is deterministic — implemented in Python against the parsed workbook structure, not against a language model's interpretation of it. The same workbook produces the same findings and the same score every time it is run.

Is there a public API for this pipeline?

Not currently. There is a narrow internal Python integration surface used by one internal consumer today; this is documented honestly, not as a public API, on the Integration Surface page.

Where can I read the detail behind each stage?

Each stage links to its own Technical Documentation page. Every stage — Parsing & Workbook Ingestion, Dependency Graph & Circularity Detection, Rule Engine & Rule Packs, the Rule Taxonomy, Finding Data Model & Confidence, Evidence & Provenance, Coverage & Disclosure, the SM-2.0 Scoring Methodology, Report Generation, the Integration Surface, Version History, and the full Rule Reference — is published.

FMAE Rule Taxonomy

Every rule in the FMAE structural rule pack declares a category attribute at the point it is defined in source — this is not a classification imposed on the rules afterward for documentation purposes, it is the classification the engine itself uses. Six categories cover all 26 rules — Structural (18 rules), Assumptions Governance (1), Integrity Controls (2), Structural Hygiene (1), Aggregation Logic (1), and Model Governance (3). This page publishes that taxonomy as the FMAE equivalent of a control catalog's classification scheme, cross-linked to the Rule Reference page for each member rule.

FMAE Scoring Engine — SM-2.0 Methodology

FMAE computes a model's risk score as 100 minus the triggered rules' combined weight, normalized against a fixed basis, currently 207.0 under the active SM-2.0 methodology. SM-1.0, the engine's original scoring basis (170.0, covering R001–R021), is retained as a frozen historical reference rather than deleted from the record. Five rules — R001, R002, R004, R006, and R023 — are critical-override rules. If any of them triggers, the resulting letter grade is capped so a model cannot be graded A or B regardless of how high its numeric score is. This page documents the exact formula, the versioning between SM-1.0 and SM-2.0, and a fully worked example.

Rule Reference Index

The Rule Reference is a set of individually addressable pages, one per FMAE structural rule, living at /fmae-knowledge-centre/rule-reference/ — the FMAE equivalent of an AWS error-code reference or a NIST control catalog. Each rule page states its purpose, detection logic at a conceptual level, severity, evidence produced, remediation guidance, and its sibling rules within the same taxonomy category. All 26 rule pages are now published; this index page explains how the Rule Reference is organized and links to every rule page in taxonomy order.

Parsing & Workbook Ingestion

Before any rule runs, FMAE loads the workbook twice — once to read formula text, once to read Excel's last-calculated values — because the engine cannot itself evaluate formulas. Every worksheet is then classified into one of seven structural roles (Input, Interface, Calculation, Output, Lookup, Mixed, or Unknown) using signals openpyxl can observe directly, with no language model and no external calls. The result — every formula cell, every hardcoded cell, workbook-level metadata, and each worksheet's classification — is assembled into a single structured manifest that every later stage reads from and none of them re-parses independently.

Dependency Graph & Circularity Detection

FMAE builds a directed graph linking every formula cell to the cells its formula references, then applies strongly-connected-component (SCC) analysis — a well-established computer-science technique for finding groups of nodes that are mutually reachable from one another — to identify every circular calculation in the workbook, however large or deeply nested. Each detected circular group is condensed into a single node in a further graph (the condensation graph), which is guaranteed acyclic and supports reachability analysis used elsewhere in the engine, such as measuring how far a finding's impact could propagate downstream.

Rule Engine & Rule Packs

FMAE's 26 structural rules are not called individually. They are registered into a single named, versioned rule pack — fmae.structural, version 1.0.0 — and executed as a unit through a narrow public interface (register_rule_pack / execute_rule_pack), never through direct access to individual rule classes from outside the engine. Every finding the pack produces is stamped with exactly which engine version and rule pack version produced it, so a finding from any past audit remains attributable to the exact rule logic that generated it.

Finding Data Model & Confidence

Every FMAE finding carries the same fixed structure — which rule triggered it and that rule's identity at the time it ran, its evidence, a narrative explanation, and a confidence label of high, medium, or low. Confidence is a deterministic categorical label derived from how strongly a row's cells agree on a pattern, not a machine-learning probability estimate. Stating this plainly matters, since describing FMAE's confidence as AI-derived or probabilistic would overstate what the engine actually does.

Evidence & Provenance

FMAE separates two concerns that are easy to blur together — evidence (the specific facts that justify a finding) and provenance (the record of what engine, rule pack, and source file produced it). An evidence bundle is a deterministic export of facts the platform has already computed elsewhere — the manifest's own provenance and coverage disclosure, an explicit set of findings, and any circular dependency regions those findings touch — copied verbatim, never recomputed or inferred at export time.

Coverage & Disclosure

Every FMAE audit carries a coverage disclosure — a machine-readable statement of what kinds of references the engine's reference resolver did and did not resolve into graph edges for that parse. Rather than silently assuming full coverage of a workbook's reference graph, FMAE states plainly what it resolved (single-cell references) and what, in this version of the platform, it does not (structured table references, most dynamic references), and counts how many instances of each were present. This is a transparency mechanism, not a marketing claim, and is a genuine limitation stated honestly rather than omitted.

Report Generation

Report Generation is the final stage of the FMAE audit pipeline, composing the outputs of every earlier stage — the score, the findings, their evidence, and the engine's provenance — into a structured report document. Two generations of report engine exist in the codebase today, one retired and one canonical. RT-3, the original report engine, is being retired; RT-3.1 is the current, canonical reporting engine, producing two on-demand report models rather than one monolithic document — an Executive Decision Report and a separate supporting Annex.

Integration Surface

FMAE does not have a public, external REST API as of this writing. What it does have is a deliberately narrow internal Python integration contract — a single module that re-exports only the specific names another internal package genuinely needs, growing one name at a time only when a concrete use case requires it. This page states plainly that no external API exists today, and documents the shape of the internal contract that does, since "does this tool have an API" is a common and legitimate integration question that deserves an honest answer either way.

Version History & Release Notes

This page tracks FMAE's engine version history using ENGINE_VERSION, the identifier stamped onto every audit's provenance and referenced throughout this Technical Documentation library as "as of engine version X.X.X." A second version identifier exists in the codebase, tracking product releases rather than the engine itself, and is not fully synchronized with ENGINE_VERSION as of this writing — this page states that honestly rather than presenting a single, false unified version number. The most detailed, dated engine change on record is the R015 rule redesign, documented in full as a Research Library case study.