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

  1. NEED-001 is the source need of REQ-COV-001.
  2. The requirement is evaluated under SCN-001 using MODEL-COV-001.
  3. TEST-COV-001 evaluates that reference configuration against the requirement’s threshold.
  4. 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.

Existing source fields and their meanings
SourceFieldTargetMeaning
REQ-COV-001source_needNEED-001Motivating operational need
REQ-COV-001verification.scenario_idSCN-001Reference inputs for verification
REQ-COV-001verification.model_idMODEL-COV-001Model used to estimate the measure
REQ-COV-001verification.test_idTEST-COV-001Registered reference test
SCN-001model_idMODEL-COV-001Model interpreting these inputs
TEST-COV-001requirement_idREQ-COV-001Criterion evaluated by the reference test
TEST-COV-001scenario_idSCN-001Reference scenario evaluated by the test
TEST-COV-001model_idMODEL-COV-001Executable model used by the test

Return to Chapter 2’s validation checks.

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.

  1. Open the main-branch validation runs and select a successful run for the revision you want to inspect.
  2. Download its reference-evidence-<commit> artifact (GitHub sign-in may be required). Artifacts expire after 30 days.
  3. Open reference-evidence.json. Check execution.sourceCommit, runTimestamp, workingTreeDirty and context before interpreting definition and calculation.

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 };
}