Learn / Chapter 02
Engineering Information Models
If the criterion or configuration changes, what must we check again?
Learning objective: identify a changed definition, validate its structure and references, re-evaluate it, and explain which evidence still applies.
Prerequisite: From Engineering Intent to Evidence.
Start with a proposed change
The monitoring team has a failing reference configuration. Someone suggests a lower coverage threshold; another person suggests a larger sensor footprint. Either proposal might produce a passing result, but they change different engineering definitions. Before comparing their outcomes, we must be able to say exactly what each proposal changes.
Chapter 1 separated the operator’s intent from a geometric criterion and its evidence. Now we need that distinction to survive an edit. The operator’s need has not changed merely because someone alters a number. Nor does an old result automatically apply to the revised definition. We need an information model that makes those dependencies inspectable.
An engineering information model defines the kinds of records we maintain, the fields they contain and the meanings of their relationships. Here it is small: a need, requirement, scenario, model registration and test registration. YAML stores the canonical definitions; Zod contracts and reference checks enforce supported structure. No specialized modeling tool is required to inspect them.
Ask three different questions
First: is the record well formed? A requirement needs an identity, statement, threshold and verification references. A scenario needs valid area dimensions, a finite sensor position and a nonnegative radius. Parsing YAML establishes readable syntax; checking the schema establishes allowed fields and values. Neither check determines whether the engineering choice is justified.
Second: do the references resolve consistently? The requirement’s source_need identifies its motivating need. Its verification fields identify a scenario, model and test. These are different roles, even when drawn as arrows in one chain. Replacing the need ID with an unknown value breaks a relationship; it does not create a new need.
Third: does the definition make engineering sense? A valid threshold can still lack an operational basis. A resolvable model reference can still point to an idealization unsuitable for a decision. Our 50% threshold is explicitly a teaching assumption. Schema and reference validation do not convert that assumption into an approved requirement.
The stable ID REQ-COV-001 lets us discuss the requirement across revisions. It is not a version identifier. A meaningful comparison needs the changed field values and the source revision or temporary proposal context. Inspect the actual field relationships before treating two records with the same ID as equivalent evidence targets.
Experiment: change the criterion or the configuration
- Begin with Reset proposal. Predict the baseline outcome.
- Try the lower-threshold example. Compare estimated coverage, outcome, statement and field differences with the unchanged baseline.
- Reset, then try the larger-radius example. Which definition and numerical output change this time?
- Break the source_need reference. Explain why no proposal result should remain visible. Restore it and check the result again.
- Write one sentence explaining what each passing trial establishes, and one additional justification you would need before recommending it.
A definition change, not an approval
Temporary, unapproved browser proposal. This workspace changes a copy of the definitions. It does not edit YAML, execute TEST-COV-001, retain evidence or approve a requirement. Reset restores the baseline; leaving or reloading discards edits.
Canonical baseline from this site build
Requirement REQ-COV-001: 50%. Scenario SCN-001: radius 35, center (50, 50), area 100 × 100 model units.
Under reference scenario SCN-001 and the V0 model assumptions, the monitoring configuration shall cover at least 50 percent of the defined area geometrically.
FAIL — 38.52% estimated coverage. Margin: -11.48 percentage points.
This is a build-time calculation, not a displayed CI verification artifact. The baseline stays unchanged while you edit.
Enable JavaScript to validate and evaluate a temporary proposal.
Exact field differences
The requirement statement and basis change with the threshold so the proposed definition stays consistent. These differences describe the current trial, not a committed revision.
| Field | Baseline | Proposal |
|---|
Inspect the validated proposed definition
No proposal evaluated yet.
Both calculations use MODEL-COV-001 v0.1.0: a 100 × 100 cell-center area estimate. No physical sensor calibration, terrain, occlusion, directional effects, time, uncertainty, faults or communications are modeled. A PASS establishes neither operational suitability nor an optimal design.
Interpret the difference, not just the label
In the criterion trial, the configuration is unchanged: the same rectangle, position and radius are supplied to the same coverage model. The coverage estimate therefore stays the same. The evaluator compares it with a different threshold, which can change the outcome and margin. Relaxing a criterion has not improved the sensor’s geometric performance.
In the radius trial, the criterion stays fixed while the proposed scenario changes. Coverage must be recalculated before evaluation. That hypothetical footprint may satisfy the geometric criterion, but the model provides no evidence that a physical sensor can produce it. It also contains no cost, installation or optimization objective that would establish which proposal is best.
The proposed statement must agree with its numeric threshold. Otherwise readers and software would be evaluating different definitions. This exercise updates both together and marks the proposed basis as unapproved. It rejects unsupported baseline wording rather than silently changing a sentence it cannot interpret. Reset restores the canonical definition without overwriting its YAML.
Bind evidence to what was evaluated
The existing reference test, TEST-COV-001, deliberately checks the unchanged 50% criterion under SCN-001. A passing browser proposal does not replace that reference outcome. The model remains MODEL-COV-001 v0.1.0; changing a threshold is not a new implementation of the coverage calculation.
Both browser proposals and the repository exercise call the same analysis function, which validates definitions and uses the existing coverage function and evaluator. The browser workspace is temporary. It creates neither a versioned source change nor a retained verification artifact, and it does not execute the reference test against its altered definitions.
For a reproducible repository trial, follow the proposal exercise from an identified checkout. Keep the canonical records and reference assertions intact. Add an isolated fixture with a unique proposal ID, inspect the diff, and run validation, tests and proposal analysis. Commit valid source changes before requesting revision-bound evidence; an uncommitted local run must report its dirty working tree honestly.
A retained proposal analysis records the complete baseline and proposed definitions, their differences, exact inputs, threshold, model version, method, grid and results. Its execution metadata identifies the source commit, working-tree state, timestamp and context. It explicitly says the reference test was not executed against the proposal. The separate reference evidence record retains its original meaning. Inspect both through the artifact instructions; an analysis ID or PASS label alone is insufficient.
For a threshold change, the existing coverage calculation can support reasoning about unchanged geometry, but the old requirement evaluation does not establish the new criterion’s outcome. For a scenario change, rerun both coverage and evaluation. For an invalidated assumption, reconsider interpretation even if a numerical result happens to repeat. These are engineering judgments about specific dependencies, not automatic approval rules.
Check your reasoning
Answer before revealing each explanation.
1. The threshold changes and PASS replaces FAIL, but coverage is identical. What improved?
No modeled geometric performance improved. The comparison criterion changed. Whether that new criterion is justified requires separate engineering reasoning.
2. Can a valid record describe an unjustified requirement?
Yes. Schema validation and resolvable references establish structure and consistency. They do not establish the operational basis of a threshold or the suitability of the modeling assumptions.
3. Is changing source_need to an unknown ID equivalent to changing a radius?
No. The first breaks a reference and blocks evaluation. The second can be a valid scenario change that requires fresh calculation and evaluation.
4. Which result belongs to a changed definition?
A result whose exact evaluated definition, inputs, method and source context match that change. A stable requirement ID alone does not establish the match; inspect the revision and proposed fields.
Next: follow the dependencies
We can now describe a change without confusing a requirement with its scenario or its evidence. The next question is how to keep larger sets of these relationships useful as definitions evolve. Begin with the explicit meanings already present in the source view. Chapter 3: Digital Threads and Knowledge Graphs develops that reasoning using the same bounded single-sensor example.