Reference / source traceability
Follow the engineering sources.
These source views are bundled from the canonical repository files when the site builds. Editing controls in the lab does not alter them.
For change-impact reasoning, return to Chapter 3.
For numerical method and reproduction, return to Chapter 4.
For controlled configuration comparisons, return to Chapter 5.
For test execution and evidence interpretation, return to Chapter 6.
For bounded task contracts and proposal review, return to Chapter 7.
For source context and action authority, return to Chapter 8.
For automated feedback and evidence applicability, return to Chapter 9.
For bounded claims, evidence gaps and review responsibility, return to Chapter 10.
For configurations and evidence reuse, return to Chapter 11.
For the integrated handover exercise, return to Chapter 12.
Intent → definition → evidence
- NEED-001 is the source need of REQ-COV-001.
- The requirement is evaluated under SCN-001 using MODEL-COV-001.
- TEST-COV-001 evaluates that reference configuration against the requirement’s threshold.
- An evidence execution creates a
RESULT-*record with the inputs, result, model version, source commit and run context. The validation workflow retains these as downloadable CI artifacts for 30 days. No saved CI result is displayed here.
These are different relationships, not a general-purpose knowledge graph. A browser what-if run is temporary, and a changed configuration is no longer the unmodified reference scenario.
Read the relationship roles
These rows come from the canonical fields. Identity and relationship roles are distinct from the revision of each definition.
| Source | Field | Target | Meaning |
|---|---|---|---|
| REQ-COV-001 | source_need | NEED-001 | Motivating operational need |
| REQ-COV-001 | verification.scenario_id | SCN-001 | Reference inputs for verification |
| REQ-COV-001 | verification.model_id | MODEL-COV-001 | Model used to estimate the measure |
| REQ-COV-001 | verification.test_id | TEST-COV-001 | Registered reference test |
| SCN-001 | model_id | MODEL-COV-001 | Model interpreting these inputs |
| TEST-COV-001 | requirement_id | REQ-COV-001 | Criterion evaluated by the reference test |
| TEST-COV-001 | scenario_id | SCN-001 | Reference scenario evaluated by the test |
| TEST-COV-001 | model_id | MODEL-COV-001 | Executable model used by the test |
Proposal analysis is a different record
The same validation runs retain a separate proposal-analysis-<commit> artifact. Download a chosen revision’s JSON and inspect definition.baseline, definition.proposed, differences, calculation and execution context. Its kind is unapproved-proposal-analysis and verification.testExecuted is false: it does not claim TEST-COV-001 verified the proposal.
These artifacts also expire after 30 days and may require GitHub sign-in. Reproduce them at the intended revision with npm ci, npm run check and npm run proposals. Browser proposals never create these retained records.
Return to Chapter 2’s evidence interpretation · Repository exercise
Inspect a retained reference evaluation record
npm run evidence calculates and evaluates canonical inputs; it does not itself invoke Vitest. The record’s test ID associates the registered reference context. Inspect the separate test command and workflow logs to establish assertion execution. Reproduce and review both activities.
- Open the main-branch validation runs and select a successful run for the revision you want to inspect.
- Download its
reference-evidence-<commit>artifact (GitHub sign-in may be required). Artifacts expire after 30 days. - Open
reference-evidence.json. Checkexecution.sourceCommit,runTimestamp,workingTreeDirtyandcontextbefore interpretingdefinitionandcalculation.
The record includes exact inputs, model version, sampling method/resolution, threshold, result and requirement outcome. No live “latest PASS” is implied by this page. If an artifact has expired, reproduce a local record with npm ci, npm test and npm run evidence at the intended source revision; that new run has its own timestamp and context.
Return to interpreting evidence · Explore a temporary browser configuration
NEED-001
Intent: operational need · engineering/needs/NEED-001.yaml
id: NEED-001
title: Observation of a designated area
statement: Provide the operator with geometric observation coverage of a designated industrial area.
REQ-COV-001
Definition: proposed system requirement · engineering/requirements/REQ-COV-001.yaml
id: REQ-COV-001
title: Geometric monitoring coverage
source_need: NEED-001
statement: >
Under reference scenario SCN-001 and the V0 model assumptions,
the monitoring configuration shall cover at least 50 percent
of the defined area geometrically.
threshold_percent: 50
threshold_basis: Teaching assumption; not derived from operational analysis.
verification:
method: simulation
model_id: MODEL-COV-001
test_id: TEST-COV-001
scenario_id: SCN-001
SCN-001
Definition: reference inputs · engineering/scenarios/SCN-001.yaml
id: SCN-001
title: Single-sensor reference configuration
area:
width: 100
height: 100
sensor:
x: 50
y: 50
radius: 35
units: model-units
model_id: MODEL-COV-001
MODEL-COV-001
Definition: executable model · models/coverage/coverage.ts
import { coverageInputSchema } from '../../schemas/engineering.js';
import type { z } from 'zod';
export type CoverageInput = z.infer<typeof coverageInputSchema>;
export type Area = CoverageInput['area'];
export type Sensor = CoverageInput['sensor'];
export const MODEL_VERSION = '0.1.0';
export const GRID_WIDTH = 100;
export const GRID_HEIGHT = 100;
export type CoverageResult = {
coveredCells: number; totalCells: number; coveragePercent: number;
method: 'cell-center-grid'; gridWidth: number; gridHeight: number;
};
/** Fixed 100×100 equal-area cell centers; disk boundary is inclusive.
* An estimate of area fraction, not detection probability or exact geometry.
*/
export function calculateCoverage(input: CoverageInput): CoverageResult {
const { area, sensor } = coverageInputSchema.parse(input);
let coveredCells = 0;
// Radius zero is explicitly zero coverage, even at a cell center.
if (sensor.radius > 0) {
for (let row = 0; row < GRID_HEIGHT; row++) {
const y = ((row + 0.5) / GRID_HEIGHT) * area.height;
for (let col = 0; col < GRID_WIDTH; col++) {
const x = ((col + 0.5) / GRID_WIDTH) * area.width;
// hypot avoids overflow from squaring otherwise valid finite inputs.
if (Math.hypot(x - sensor.x, y - sensor.y) <= sensor.radius) coveredCells++;
}
}
}
const totalCells = GRID_WIDTH * GRID_HEIGHT;
return { coveredCells, totalCells, coveragePercent: 100 * coveredCells / totalCells,
method: 'cell-center-grid', gridWidth: GRID_WIDTH, gridHeight: GRID_HEIGHT };
}
TEST-COV-001
Definition: verification test · models/coverage/verification.test.ts
import { expect, it } from 'vitest';
import { loadSources } from '../../scripts/sources.js';
import { calculateCoverage } from './coverage.js';
import { evaluateCoverage } from './evaluate.js';
it('TEST-COV-001: evaluates REQ-COV-001 independently of the site', () => {
const { requirement, scenario } = loadSources();
const result = calculateCoverage({ area: scenario.area, sensor: scenario.sensor });
const evaluation = evaluateCoverage(result, requirement.threshold_percent);
expect(result.coveragePercent).toBeGreaterThan(38);
expect(result.coveragePercent).toBeLessThan(39);
expect(requirement.threshold_percent).toBe(50);
expect(evaluation.pass).toBe(false);
expect(evaluation.marginPercentagePoints).toBeLessThan(0);
});
Model and test registration
model:
id: MODEL-COV-001
version: 0.1.0
source: models/coverage/coverage.ts
method: cell-center-grid
grid_width: 100
grid_height: 100
boundary_rule: distance <= radius
assumptions:
- One fixed ideal circular footprint in a uniformly weighted rectangular area.
- No terrain, occlusion, uncertainty, time, faults, or communication effects.
test:
id: TEST-COV-001
source: models/coverage/verification.test.ts
requirement_id: REQ-COV-001
scenario_id: SCN-001
model_id: MODEL-COV-001
Evaluation rule
import { percentSchema } from '../../schemas/engineering.js';
import type { CoverageResult } from './coverage.js';
/** Compare the unrounded estimate. Equality passes. */
export function evaluateCoverage(result: CoverageResult, requiredPercent: number) {
const measured = percentSchema.parse(result.coveragePercent);
const threshold = percentSchema.parse(requiredPercent);
return { pass: measured >= threshold, marginPercentagePoints: measured - threshold };
}