Census, inclusion choice and governance gate

Three engines prepare a reporting build and decide nothing on your behalf. The census counts what a repository actually uses, the inclusion choice turns that count into the question of what the business layer holds, and the governance gate lists the elements no business table will hold. The build itself runs in the AI Power Tools MCP Server for Sparx EA, not here: see Reporting business layer for the operations and Reporting business layer for how the server builds the layer.

Used by: ea-reporting-database, whenever a reporting profile is created and before each build. The census also serves ea-mdg-assess, ea-mdg-author and ea-mdg-model-build, so the reporting skill and the modeling-language skills never disagree about what a repository contains.

Runs where: local code execution. All three need Python 3 and only its standard library. None of them calls the repository, reads or writes a file, or reads a clock: the AI reads the rows with direct queries through AI Power Tools (Direct queries), with Enterprise Architect running and the repository open, and passes them in. The technology's definition comes from get_mdg_from_runtime (Discovering technologies). Without code execution none of the three is available (see How code engines work).

The census is taken over the reporting scope, not the whole repository: the root packages in the profile and everything under them, less the packages left out. A defect or a gap outside the scope would otherwise stop the work or be offered as a decision about content the build never reads.

The census

What it does. The census (ea_census) counts the elements and connectors in scope by the stereotype each one carries and the technology that stereotype is bound to. It exists because the stereotype name Enterprise Architect shows does not say which language it belongs to, and holds only an element's first stereotype. EA keeps the binding to a technology in a separate record, one per element or connector, holding every stereotype applied. The census reads that record:

• A stereotype is the technology's only when EA recorded the binding. The same name typed without a binding is counted as an ad hoc application, and a name bound to another language is counted under that language. Neither is ever counted as the technology's stereotype.
• An element with two stereotypes is counted under both, and once in the total.
• Nothing is dropped silently. An element or connector with no binding record still counts, from its stereotype name, as ad hoc. Elements and connectors with no stereotype are counted apart, connectors by connector type. EA's own machinery and the scaffolding of a technology's source model (the profile, stereotype and metaclass elements an MDG author builds) are left out and counted, so the totals add up.
• One entry per bound stereotype, whatever element type it is drawn on, with the mix of element types reported. An ad hoc stereotype is keyed by its name and element type, because a bare name can mean different things in different languages. A connector stereotype is keyed by its name and connector type.
• Tag coverage counts populated values, not the tag rows present. EA creates a tag row whenever a stereotype is applied, filled in or not, so a count of rows reports full coverage on a tag nobody has filled in.

Declared and observed usage. Given the technology's definition, the census compares what the technology declares with what the repository uses, for elements and for connectors (connector drift). The findings:

The census matches on stereotype names and works out the technology's own namespace from the stereotypes it declares, because a technology's id, its display name and the namespace EA records against its stereotypes are often three different names.

Logic: Deterministic for reading the binding records and counting. Rule-based for the probable-misassignment finding and for any list of values inferred from use.

What it needs. The rows for elements, connectors, their tags and their stereotype binding records, read through AI Power Tools' direct queries; the technology's definition for the comparison.

What an architect checks.

• The totals account for everything. Correct: the report gives the excluded counts (EA's machinery, source-model scaffolding), the untyped elements and connectors, and the elements with several stereotypes. Red flag: a total lower than the usage you see in EA with nothing to explain the difference.
• Bound against ad hoc, per stereotype. A stereotype you expected to be the technology's that shows up as ad hoc means EA never recorded the binding for those elements or connectors. Check one in EA's Properties window.
• Every coverage figure has a denominator, and counts populated values.
• The scope is the reporting scope. A census over the whole repository answers a different question from the build.
• A probable misassignment is evidence, not proof. Look at the elements in EA before acting on it.

Limitations. A list of values inferred from use shows only what was used; the technology's declared list is the authority. The misassignment finding compares tag names, so it says nothing about elements that carry no tags, and it is not computed for connectors. A tag holding several comma-joined values is one value unless the AI splits it deliberately, because a comma can also be part of a single value. The census is a reading of the rows at the moment they were read.

The inclusion choice

What it does. The inclusion choice (inclusion) works out, from the element and connector censuses and the technology, what each of three answers would put in the business layer, and turns your answer into the reporting profile's inclusion section. The three answers:

• Only what the technology defines. The technology's element stereotypes and connector stereotypes, nothing else.
• Everything in the repository. The technology's stereotypes, plus a table for every other stereotype observed, or for every element type where elements carry no stereotype.
• Gap by gap. The technology's stereotypes, plus each gap you choose to include. Every element stereotype and connector stereotype the technology does not declare is a gap, listed with its count and an example name so you can recognize it. For each one you include it, exclude it, or send it to the modeling-language skills to be declared.

For each answer it reports declared and observed keys, distinct elements (an element in two tables counts once) and connectors. A stereotype counts as the technology's only when it is bound to the technology: the same name carried ad hoc, or bound to another language, is a gap. Unstereotyped notes, text, boundaries and package objects are never model content and are neither counted nor offered. How many connector tables a connector stereotype yields depends on the source and target combinations the technology allows, which the build decides.

It reports two data defects apart from the gaps, because they are mistakes to fix in the repository, not questions:

• a connector whose stereotype is stored as qualified text with no binding, for example WBA::Uses. While any remains, no profile is produced;
• an element carrying two of the technology's stereotypes. It is flagged with the count and the combination; if you continue, the element is placed in both tables.

Your answer, recorded. It turns your answer into the profile's inclusion section and a record saved with it: which answer you gave, which gaps you excluded, and what the technology declared, with its version, at the time. The profile lists only what is included, so without the record a later census could not tell a gap you excluded from one that appeared since. It refuses to produce the inclusion section while any unbound connector remains, while any gap is undecided or marked to be declared in the technology, or while elements carry two declared stereotypes and you have not chosen to continue. "Declare it in the technology" is a hand-off to ea-mdg-model-build, followed by a fresh census, not an answer.

On a later census it compares the census with the saved choice and lists, for you to decide: stereotypes that a gap-by-gap answer does not cover and that you did not exclude; and a stereotype added to or removed from the technology, or a different technology version. It flags; it never decides. Builds and refreshes in the server raise their own drift flags from the same record (Reporting business layer).

Logic: Deterministic. You give the answer, and decide each gap.

What it needs. The two censuses and the rows they were taken from (for the element type of unstereotyped elements and an example name per gap), and the technology's definition.

What an architect checks.

• All three answers were put to you, with counts, before the profile was written. Red flag: a profile whose inclusion you did not choose.
• Gap by gap: every gap was shown with its count and an example, and each has your decision.
• No unbound connectors remain when the profile is written.
• The record is saved with the profile. Without it, every later census reports every gap you excluded as uncovered.
• After a hand-off to declare a gap, the census was taken again and the stereotype is declared, bound to the technology.

Limitations. It counts stereotypes and instances, not tables. It covers only what the census read, so a census over the wrong scope gives the wrong counts.

The governance gate

What it does. The governance gate (governance_gap) runs before the build. It lists the in-scope elements that carry no stereotype at all. Such an element is in no business table unless your inclusion answer includes its element type. Elements that carry populated tagged values come first: someone entered governance data on them deliberately, and no report would show it. Then it sorts by element type and name, so two runs give the same list. Package objects are skipped, because EA stores each package once more as an element that nobody stereotypes.

Each element gets one of three outcomes, kept apart on purpose:

The signals, in the order they discriminate: the element type is a hard filter, never a tiebreak; package locality decides; tag fit works only downward, so an element that carries only the common tags is not offered a stereotype that declares several more it does not have. Tag fit alone rarely separates candidates, because technologies tend to give many stereotypes the same core tag set. In the Westbrook Bank illustration, ten of fifteen element stereotypes declare the same six tags.

Applying a stereotype is a model write and is yours to approve. The skill takes a baseline first, applies the bare stereotype name through update_element while the technology is loaded (EA records the binding itself), then takes the census again to confirm the element is placed. Declining is a valid answer; the AI then states which elements will be missing from the reporting layer. See ea-reporting-database.

Logic: Rule-based for the outcome and the suggestion. Deterministic for the list and its order. It only reports; nothing in it changes a repository.

What it needs. The in-scope element rows with their package, the tag rows, and the shape of each declared stereotype (its element type and tag names) from the census.

What an architect checks.

• Elements with governance data are listed first, with their tags. Correct: every element carrying populated tags is named. Red flag: a total with no names.
• Every suggestion carries its reason, for example how many stereotyped neighbors in the same package carry that stereotype.
• "Several candidates" is never presented as a recommendation. Red flag: the AI picking one without saying the gate refused to.
• "No candidate" is never followed by a suggestion. Applying a stereotype that does not extend the element's type is the way to have EA accept a write and drop it.
• After a stereotype is applied, the census shows the element under the technology's stereotype, bound, not ad hoc.

Limitations. Locality evidence holds where a repository is organized by type; a repository organized by domain gives few votes, and those elements come out with several candidates rather than a weak suggestion. The gate looks at elements only, not connectors. It lists elements with no stereotype at all; an element carrying a stereotype that your inclusion answer leaves out is not on its list.