Technical Documentation

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.

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.

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.

FMAE Audit Engine — Architecture Overview

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.

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.

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.

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.

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.

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.

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.

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.

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.