Posture & maturity
On Why you see what your data estate looks like and how ready it is: each business
area’s health, the domains and how they relate, and the readiness indicators.
PostureService serves those figures and grounds the other agents.
| RPC | What it does |
|---|---|
GetHealthScore | Serves the latest fetch’s posture snapshot. With no snapshot, it runs the deterministic posture analysis. |
BuildDomainGraph | The fast half of a session fetch. It derives data domains and their relationships deterministically, with no LLM call. |
AnalyzeEstateCausal | A do-calculus intervention over the connected estate (see below). |
ListIncidents | Data-maturity assessments (DataMaturityAssessment). |
GetContext | Semantic context items for an agent type. |
What is measured
Each domain gets a DomainHealth. Its figures come from computeStructuralMaturity,
which is deterministic Go over what the profiler read, not a model. Only what the
profiler measures carries a value, and each value has its *_measured flag set:
| Gauge | How it’s measured |
|---|---|
quality_stability_pct | Filled values ÷ sampled values, whatever the share. quality_sampled_values and quality_filled_values give the n. |
risk_pii_pct | The share of columns whose names match personal-data patterns. |
lineage_pct, freshness_pct, policy_pct, cost_efficiency_pct | Not measured: left at 0 with the flag false. |
There is no letter grade and no health score. Both were cut at fixed numbers no
tenant set (a grade of A at 0.85, a lineage base of 0.55 plus 0.35 for a key), so a
domain read “Lineage 90%” whatever its joins. What the profiler observes instead is a
fact: a join key or a timestamp column is present or not, values were left empty or
not, PII-like columns are present or not. issues lists them, for example “no join
key detected (lineage risk)” or “incomplete sample values: 49 of 120 filled”.
Readiness findings are those facts. Each gap above is one assessment and one
measure to take. Its severity is Not graded: no target is set for it. The
scoreboard indicators state the same facts with rating 0 (unrated); a model’s
rating is not carried. Quality pillars and risk checks pass or fail on a fact (a key
or timestamp present, no PII-like columns) and read Not graded where they carry a
measured share with no target.
A snapshot written before these changes still holds a grade, baseline gauges and ratings. They are cleared when it is read.
A failed scan returns an error, not a grade of F. With no connected data source,
the local path answers FailedPrecondition: “connect a data source first”.
The empty_trip category is always empty. Nothing in the platform measures
empty-trip or deadhead running, so the server clears it on every response. A client
must show it as not measured, never as zero.
Measure wording records where it came from. OptimizationSOP.provenance
(MeasureProvenance) is one of:
MEASURED: read from a source.DERIVED: computed in Go from measured data.MODEL_GENERATED: written by the posture agent.
Only MODEL_GENERATED may be labelled as AI-generated.
Lineage
A join key present is a schema property, not observed lineage. It reads the same whether a source has been pulled a thousand times or never, because it depends only on whether a join key exists.
Observed lineage is a separate record, written by the backend’s lineage recorder:
- Where records come from. Every tabular connector is wrapped by one lineage decorator, so each extraction and each delivery is recorded. Camera ingests are recorded at their own seam.
- How they’re stored. Records are append-only Avro in the object store, partitioned by UTC day.
- What they contain. Structure only: column names, counts, durations, a literal-free query shape and a fingerprint, and a closed-set error class. Never result values, driver messages or credentials. A test with sentinel values enforces this.
- How to read them.
LineageService.GetSourceActivityreturns per-connection activity over a window:extractions,deliveriesandrows.- The outcome mix:
ok,emptyandfailed.emptymeans the source connected and returned nothing, which is neither a failure nor a delivery. error_classes,destinations, and thelast_columnsnames.durableanddurable_reason, which say whether the records survive a restart. Without a durable sink, the process keeps only a small in-memory ring.
Some reads aren’t in the log. A camera frame ingest is recorded with a row count of zero, because a camera sends frames, not rows. See Vision & CCTV.
The domain graph
In the FACE app, the estate is mapped by the fetch itself: its business-domains phase derives the domains and their relationships from the connections the fetch reads, and Why shows the result. A newly confirmed connection joins the map at the next fetch. There is no manual control to map it again.
BuildDomainGraph derives domains (structuralCommunities) and structural edges
deterministically. It computes no correlations. Measured CORRELATED_WITH edges come
from the fetch pipeline’s time-series EDA instead. See
Fetch pipeline.
When connected sources are read, each edge’s relation names its evidence class. The
classes are a closed set, listed from strongest to weakest:
DECLARED_FOREIGN_KEY: the source’s own constraint.CATALOGUE_CONTAINMENTINFERRED_FROM_DECLARED_KEYINFERRED_SHARED_VOCABULARYINFERRED_FROM_VALUE_OVERLAPGUESSED_COLUMN_OVERLAP: a guess, and named as one.
Value sampling is on by default, because sampled values are real evidence about what a
table is. metadata_only_connection_ids turns it off per connection. Sampled values
reach only counts and shapes in the graph. They never appear in a log line, an error,
a lineage record or a model prompt.
FACE still serves include_connected_sources for API clients and for
AnalyzeEstateCausal. The FACE app calls GetHealthScore only; BuildDomainGraph,
AnalyzeEstateCausal, ListIncidents and GetSourceActivity are API calls.
Estate causal analysis
AnalyzeEstateCausal runs an intervention over columns of the connected estate. A
node is <qualified dataset>.<column>, carrying the source’s own aggregate over that
column.
FACE separates structure from magnitude:
- Structure. The estate may propose an edge only from a
DECLARED_FOREIGN_KEY, and only where both columns have a measured value. No weaker evidence class proposes anything. - Magnitude. The coefficient is always the caller’s (
EstateCausalCoefficient), because nothing in a catalogue or a sample measures how much one column moves another. Values that aren’t finite are refused.
How to read the response:
- Read
answeredfirst. With no admitted edge, the RPC refuses and explains why inrefusal. It never returns an effect of 0 with an OK status. weakest_basisis the weakest basis among the edges the effect travelled along:OPERATOR_ASSERTED: the caller named both endpoints.DECLARED_KEY_REPURPOSED: the endpoints came from a declared key, which is weaker because a referential constraint is being read as a causal one.
basis_statementis written to be shown verbatim beside the number.node_refusals,edge_refusals,nodes_addedandcolumns_refusedgive the denominators. A graph of four columns out of nine hundred measurable ones is not a causal graph of the estate.
Reading the results
- The facts reflect structure, not how the data is used. A key, a timestamp and no PII-like columns don’t mean the data is correct, current or governed.
- A join key present is not lineage. Use
GetSourceActivityfor what was actually read and delivered. - A declared foreign key is a referential constraint, not a causal claim.
- An estate causal answer reflects the coefficients you supplied. It rests on those coefficients, over the columns that had measurements.