@starci/hfs 4.3.0 → 4.4.0

package/runtime/scripts/hfs/rules/assets.mjs

@@ -0,0 +1,79 @@
+// assets.mjs - R282: small build-time binaries belong in be.assets; user media, model weights and datasets do not belong in git.
+// The owner assets policy has no numeric cap yet. 512000 bytes follows the existing repo.docs-media budget in slots.yaml;
+// ruleParams.be.assets {bytes (or maxBytes), extensions} supplies a manifest's explicit cap and build-time extension allowlist.
+import fs from 'node:fs';
+import path from 'node:path';
+import { editionRuleParams } from '../edition-slots.mjs';
+import { found } from './read.mjs';
+
+export const HFS_ASSET_OVERSIZE = 'HFS_ASSET_OVERSIZE';
+export const HFS_ASSET_KIND = 'HFS_ASSET_KIND';
+export const DEFAULT_ASSET_BYTES = 512000;
+const BUILD_EXTENSIONS = ['.ttf', '.otf', '.woff', '.woff2', '.eot', '.png', '.svg', '.webp', '.jpg', '.jpeg', '.gif', '.ico', '.avif', '.bmp', '.tif', '.tiff'];
+const MEDIA_EXTENSIONS = new Set(['.mp3', '.mp4', '.wav', '.ogg', '.oga', '.opus', '.flac', '.aac', '.m4a', '.wma', '.aiff', '.aif', '.mid', '.midi', '.mov', '.m4v', '.webm', '.avi', '.mkv', '.mpeg', '.mpg', '.wmv', '.flv', '.3gp']);
+const IMAGE_EXTENSIONS = new Set(BUILD_EXTENSIONS.filter((ext) => !['.ttf', '.otf', '.woff', '.woff2', '.eot'].includes(ext)));
+const MODEL_EXTENSIONS = new Set(['.onnx', '.pt', '.pth', '.ckpt', '.safetensors', '.gguf', '.ggml', '.tflite', '.keras', '.caffemodel', '.h5', '.hdf5', '.npy', '.npz', '.pkl', '.pickle', '.joblib', '.weights']);
+const DATASET_EXTENSIONS = new Set(['.parquet', '.arrow', '.feather', '.avro', '.tfrecord', '.tfrecords', '.jsonl', '.ndjson']);
+const COMPRESSED = /\.(?:gz|bz2|xz|zst|zip|tar|tgz)$/i;
+const SOURCE_OR_DOC = /\.(?:[cm]?[jt]sx?|md|mdx|rst)$/i;
+const DATA_DIRECTORY = /(?:^|\/)(?:datasets?|training-data|training-set|weights|checkpoints)(?:\/|$)/i;
+const MODEL_DIRECTORY = /(?:^|\/)models?(?:\/|$)/i;
+const DOCS_MEDIA = /^docs\/.+\.(?:png|svg|webp)$/i;
+const USER_ASSET_DIRECTORY = /^src\/assets\/(?:media|uploads?|music|audio|videos?)(?:\/|$)/i;
+const MODEL_BINARY = /(?:^|\/)(?:[^/]*[-_.])?(?:model|weights|checkpoint)(?:[-_.][^/]*)?\.bin$/i;
+
+function assetPolicy(manifest, edition) {
+  const config = editionRuleParams(manifest?.ruleParams?.be ?? {}, edition).assets ?? {};
+  const cap = config.bytes ?? config.maxBytes;
+  const bytes = Number.isSafeInteger(cap) && cap > 0 ? cap : DEFAULT_ASSET_BYTES;
+  const extensions = Array.isArray(config.extensions) ? config.extensions : BUILD_EXTENSIONS;
+  return { bytes, extensions: new Set(extensions.filter((ext) => typeof ext === 'string').map((ext) => `.${ext.replace(/^\./, '').toLowerCase()}`)) };
+}
+
+function uncompressedName(file) {
+  let name = file;
+  while (COMPRESSED.test(name)) name = name.replace(COMPRESSED, '');
+  return name;
+}
+
+function refusedKind(file, extensions) {
+  const name = uncompressedName(file);
+  const ext = path.posix.extname(name).toLowerCase();
+  const asset = file.startsWith('src/assets/');
+  if (MODEL_EXTENSIONS.has(ext) || MODEL_BINARY.test(name) || (ext === '.bin' && MODEL_DIRECTORY.test(file))) return 'model weights';
+  if (DATASET_EXTENSIONS.has(ext)) return 'a dataset or model artifact';
+  // repo.docs-media owns these images even when their subject is a dataset, weights or checkpoints.
+  if (DOCS_MEDIA.test(file)) return null;
+  if (DATA_DIRECTORY.test(file) && !SOURCE_OR_DOC.test(file)) return 'a dataset or model artifact';
+  if (MEDIA_EXTENSIONS.has(ext) || USER_ASSET_DIRECTORY.test(file)) return 'user media';
+  if (asset) {
+    if (!/^src\/assets\/[^/]+\/.+/.test(file)) return 'an asset outside a per-kind folder';
+    if (!extensions.has(path.posix.extname(file).toLowerCase())) return 'an asset extension outside ruleParams.be.assets.extensions';
+  } else if (IMAGE_EXTENSIONS.has(ext)) return 'media outside be.assets';
+  return null;
+}
+
+function fileBytes(repoRoot, file) {
+  try {
+    const stat = fs.lstatSync(path.join(repoRoot, file));
+    return stat.isFile() ? stat.size : null;
+  } catch { return null; }
+}
+
+/** Side-relative tracked paths only: the app root and FE are left to their own rules, avoiding duplicate root/side findings. */
+export function assetsFindings({ repoRoot, files = [], repo, manifest, isRoot = false, inScope = () => true }) {
+  const edition = repo?.edition ?? 'full';
+  if (isRoot || repo?.profile !== 'be' || !['lite', 'full'].includes(edition)) return [];
+  const policy = assetPolicy(manifest, edition);
+  const findings = [];
+  for (const raw of new Set(files)) {
+    if (!inScope(raw)) continue;
+    const file = raw.replaceAll('\\', '/');
+    const kind = refusedKind(file, policy.extensions);
+    if (kind) findings.push(found(HFS_ASSET_KIND, file, `${file} is ${kind}; keep only small build-time binaries in src/assets/<kind>/, put user media in object storage, and keep model weights and datasets outside git`));
+    if (!file.startsWith('src/assets/')) continue;
+    const bytes = fileBytes(repoRoot, file);
+    if (bytes !== null && bytes > policy.bytes) findings.push(found(HFS_ASSET_OVERSIZE, file, `${file} is ${bytes} bytes, above the ${policy.bytes}-byte per-file build-time asset budget; store it externally and fetch it at runtime`, { bytes, maxBytes: policy.bytes }));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/boot-proof.mjs

@@ -0,0 +1,16 @@
+// R272: lite proves each app's real Nest composition with doubles; full keeps its e2e proof.
+import fs from 'node:fs';
+import path from 'node:path';
+import { appWiring } from '../app-wiring.mjs';
+
+export const BE_APP_BOOT_PROOF_MISSING = 'BE_APP_BOOT_PROOF_MISSING';
+
+/** Root scopes delegate to the be side, so each app is compiled once. */
+export function bootProofFindings({ repoRoot, files, all = files, repo, isRoot = Boolean(repo?.sides), inScope = () => true }) {
+  if (repo?.edition !== 'lite' || isRoot || repo?.profile === 'fe' || repo?.kind === 'fe') return [];
+  // Dependencies not installed (a fresh scaffold, a lint-only checkout): the Nest graph cannot be compiled, so the proof is unavailable here; CI and every installed app judge it.
+  const installed = [repoRoot, path.dirname(repoRoot ?? '.')].some((dir) => dir && fs.existsSync(path.join(dir, 'node_modules')));
+  return appWiring({ repoRoot, files: all, repo }).findings
+    .filter(finding => installed || finding.reason !== 'module or proof could not be compiled')
+    .filter(finding => inScope(finding.path));
+}

package/runtime/scripts/hfs/rules/canon-copy-drift.mjs

@@ -0,0 +1,59 @@
+// canon-copy-drift.mjs - HFS_CANON_COPY_DRIFT (R253): a handful of scaffolded files are hash-sensitive canon,
+// not files to edit. The drift judgement is one sha256 against the bytes of the be/skeleton template the file was
+// scaffolded from - the file equals canon, or it has drifted. A finding carries the path and both hashes, never
+// file content.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { found } from './read.mjs';
+
+const CANON_COPY = 'HFS_CANON_COPY_DRIFT';
+const TEMPLATE_ROOTS = [
+  path.resolve(import.meta.dirname, '../../../packages/hfs/templates'),
+  path.resolve(import.meta.dirname, '../../../../templates'),
+];
+const TEMPLATE_DIR = 'be/skeleton/';
+
+// The three managed files the standard's secret-custody law pins byte-for-byte.
+const CANON_PATHS = [
+  'src/modules/platform/config/env-source.config.ts',
+  'src/modules/platform/http-security/origin.guard.ts',
+  'src/modules/platform/http-security/webhook-signature.service.ts',
+];
+const REGEX_ESCAPE = String.raw`\$&`;
+const CANON_SUFFIX = new RegExp(`(?:^|/)(${CANON_PATHS.map((rel) => rel.replace(/[.*+?^${}()|[\]\\]/g, REGEX_ESCAPE)).join('|')})$`);
+
+const templateBytes = (rel) => {
+  for (const root of TEMPLATE_ROOTS) {
+    const file = path.join(root, TEMPLATE_DIR, rel);
+    try {
+      const bytes = fs.readFileSync(file);
+      if (bytes.length) return bytes;
+    } catch { /* next root */ }
+  }
+  return null;
+};
+const sha256 = (bytes) => crypto.createHash('sha256').update(bytes).digest('hex');
+
+export function canonCopyDriftFindings({ repoRoot, files, inScope }) {
+  const findings = [];
+  for (const file of files.filter((f) => !inScope || inScope(f))) {
+    const hit = CANON_SUFFIX.exec(file.replaceAll('\\', '/'));
+    if (!hit) continue;
+    const expected = templateBytes(hit[1]);
+    if (!expected) continue;
+    let actual;
+    try {
+      actual = fs.readFileSync(path.join(repoRoot, file));
+    } catch {
+      continue;
+    }
+    const expectedHash = sha256(expected);
+    const actualHash = sha256(actual);
+    if (actualHash === expectedHash) continue;
+    findings.push(found(CANON_COPY, file,
+      `${file} differs from the canon copy it was scaffolded from (sha256 ${actualHash.slice(0, 12)} vs ${expectedHash.slice(0, 12)}); restore the managed file's bytes - it is hash-sensitive canon, not a file to edit`,
+      { expectedHash, actualHash }));
+  }
+  return findings;
+}

package/runtime/scripts/hfs/rules/contract.mjs

@@ -9,13 +9,68 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { found, readText } from './read.mjs';
 import { safeRemove } from '../../api/fs/safe-remove.mjs';
 import { makeTempDir } from '../../api/fs/make-temp-dir.mjs';
+import { loadTypescript } from '../../lib/package-at.mjs';
 
 export const CONTRACT_SNAPSHOT_DRIFT = 'HFS_CONTRACT_SNAPSHOT_DRIFT';
 const GRAPHQL_TRANSPORT_SLOT = 'be.transport.graphql';
 const SNAPSHOT_OF = { graphql: 'schema.graphql', json: 'openapi.json' };
+const GRAPHQL_PLATFORM = /^src\/modules\/platform\/graphql(?:\/|\.ts$|$)/;
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/** A side-relative source import through a relative path or the canonical backend aliases. */
+function sourcePath(from, specifier) {
+  const alias = [['@modules/', 'src/modules/'], ['@features/', 'src/features/']].find(([prefix]) => specifier.startsWith(prefix));
+  let relative = null;
+  if (alias) relative = `${alias[1]}${specifier.slice(alias[0].length)}`;
+  else if (specifier.startsWith('.')) relative = path.posix.join(path.posix.dirname(from), specifier);
+  return relative === null ? null : path.posix.normalize(relative).replace(/\.js$/, '.ts');
+}
+
+/** A tracked source file of an import, including directory entries and JavaScript-extension TypeScript imports. */
+function sourceOf(base, tracked) {
+  return [base, `${base}.ts`, `${base}/index.ts`].find(file => tracked.has(file)) ?? null;
+}
+
+/** Runtime imports and re-exports, parsed by the same TypeScript loader as the neighbouring content rules. */
+function runtimeSpecifiers(ts, file, text) {
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+  const specifiers = [];
+  const visit = node => {
+    if (ts.isImportTypeNode(node)) return;
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+      const clause = node.importClause ?? node;
+      const bindings = ts.isImportDeclaration(node) ? clause.namedBindings : node.exportClause;
+      const onlyTypes = clause.isTypeOnly || (!clause.name && bindings?.elements?.length && bindings.elements.every(item => item.isTypeOnly));
+      if (!onlyTypes && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) specifiers.push(node.moduleSpecifier.text);
+      return;
+    }
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword && node.arguments[0] && ts.isStringLiteral(node.arguments[0])) specifiers.push(node.arguments[0].text);
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return specifiers;
+}
+
+/** The import closure of one app's composition, including its groups and the feature transports it owns. */
+function servesGraphql(app, tracked, classified, sources) {
+  if ([...classified.values()].some(file => file.slot === GRAPHQL_TRANSPORT_SLOT && file.bindings?.app === app.name)) return true;
+  const pending = [`apps/${app.name}/src/app.module.ts`];
+  const seen = new Set();
+  while (pending.length) {
+    const file = pending.pop();
+    if (seen.has(file) || !tracked.has(file)) continue;
+    seen.add(file);
+    if (classified.get(file)?.slot === GRAPHQL_TRANSPORT_SLOT) return true;
+    const bases = sources(file).map(specifier => sourcePath(file, specifier)).filter(base => base !== null);
+    if (bases.some(base => GRAPHQL_PLATFORM.test(base))) return true;
+    pending.push(...bases.map(base => sourceOf(base, tracked)).filter(Boolean));
+  }
+  return false;
+}
 
 /** sha256 of a file's text with line endings folded, or null when it cannot be read. */
 function contractHash(file) {
@@ -26,13 +81,19 @@ function contractHash(file) {
 export function contractFindings({ repoRoot, files, repo, resolver }) {
   const findings = [];
   if (repo.profile !== 'be') return findings;
-  const serves = files.some((file) => resolver.classifyPath(file).slot === GRAPHQL_TRANSPORT_SLOT);
   const tracked = new Set(files);
+  const classified = new Map(files.map(file => [file, resolver.classifyPath(file)]));
+  const ts = loadTypescript(repoRoot, HERE);
+  const imports = new Map();
+  const sources = file => {
+    if (!imports.has(file)) imports.set(file, ts ? runtimeSpecifiers(ts, file, readText(repoRoot, file) ?? '') : []);
+    return imports.get(file);
+  };
   for (const app of repo.apps.filter((a) => a.kind === 'api')) {
     const operations = `contracts/${app.name}/${SNAPSHOT_OF.json}`;
     if (tracked.has(`apps/${app.name}/src/operations.ts`) && !tracked.has(operations)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, operations, `${app.name} declares an operation table (apps/${app.name}/src/operations.ts) but ${operations} is not committed; declare be.contract.openapi in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
-    // An app serves GraphQL when its root module composes the platform graphql capability; a repository with a GraphQL transport slot does not make every api app one.
-    if (!serves || !(readText(repoRoot, `apps/${app.name}/src/app.module.ts`) ?? '').includes('platform/graphql')) continue;
+    // Composition groups and transport ownership are app-specific: another service's GraphQL files do not apply here.
+    if (!servesGraphql(app, tracked, classified, sources)) continue;
     const snapshot = `contracts/${app.name}/${SNAPSHOT_OF.graphql}`;
     if (!tracked.has(snapshot)) findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${app.name} serves GraphQL but ${snapshot} is not committed; declare be.contract.graphql in hfs.json sides.be.optionalSlots, run \`npm run contract:emit\` and commit the snapshot`, { app: app.name }));
   }
@@ -62,8 +123,8 @@ function artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emi
   }
   const fresh = contractHash(path.join(scratch, snapshot));
   if (committed === null) {
-    // the uncommitted snapshot itself is reported by contractFindings above; here it only counts as not judged
     apps.push({ app: app.name, artifact, status: 'not-committed' });
+    findings.push(found(CONTRACT_SNAPSHOT_DRIFT, snapshot, `${app.name} emits ${snapshot} but it is not committed or readable; run \`npm run contract:emit\` and commit the snapshot`, { app: app.name, drift: 'not-committed' }));
   } else if (committed === fresh) {
     apps.push({ app: app.name, artifact, status: 'fresh' });
   } else {
@@ -76,7 +137,7 @@ function artifactFindings({ repoRoot, tracked, scratch, app, artifact, what, emi
  * R23, full pass: each committed `contracts/<app>/schema.graphql` and `contracts/<app>/openapi.json` equals what `emit` writes for
  * the app now. `emit({ repoRoot, declaration, outDir })` is `emitContracts` of packages/hfs/emit and answers `{ written, skipped }`;
  * it is injected because the runtime scripts do not import the hfs package. Every api app is emitted on its own into a temp
- * directory, so one app that cannot emit does not hide the others; an uncommitted snapshot is contractFindings' finding. Answers
+ * directory, so one app that cannot emit does not hide the others; an uncommitted emitted snapshot is a finding here too. Answers
  * `{ findings, apps }`, `apps` being what was judged: `[{ app, artifact, status }]`, `artifact` being `schema.graphql` or
  * `openapi.json` and `status` one of `fresh`, `stale`, `not-committed`, `none` (nothing emitted, nothing committed; GraphQL only),
  * `left-behind` (committed, nothing emitted) or `emit-failed`.

package/runtime/scripts/hfs/rules/coverage-below.mjs

@@ -0,0 +1,230 @@
+// R273: an explicitly supplied lcov report proves 100% per measured logic file in either edition.
+// The denominator is the existing slot-derived coverage scope, never the source records present in the report.
+// lcov carries lines, functions and branches; the unit runner also enforces its statement threshold.
+import fs from 'node:fs';
+import path from 'node:path';
+import { coverageScope } from '../coverage-scope.mjs';
+import { editionRuleParams, effectiveSlot, slotInEdition } from '../edition-slots.mjs';
+import { globExpression } from '../../lib/glob.mjs';
+import { byCodeUnit } from '../../lib/list.mjs';
+import { found } from './read.mjs';
+
+export const HFS_COVERAGE_BELOW = 'HFS_COVERAGE_BELOW';
+const METRICS = ['lines', 'functions', 'branches'];
+const SUMMARY = { LF: ['lines', 'found'], LH: ['lines', 'hit'], FNF: ['functions', 'found'], FNH: ['functions', 'hit'], BRF: ['branches', 'found'], BRH: ['branches', 'hit'] };
+const SOURCE = /\.ts$/;
+const SPEC = /(?:\.(?:spec|test)|-spec)\.ts$/;
+const countOf = (value) => /^\d+$/.test(value) && Number.isSafeInteger(Number(value)) ? Number(value) : null;
+const slash = (value) => path.posix.normalize(String(value).replaceAll('\\', '/'));
+
+const emptyRecord = (source) => ({ source, lines: new Map(), functions: new Map(), branches: new Map(), summary: {}, problems: [] });
+const addHits = (map, key, hits) => map.set(key, Math.min(Number.MAX_SAFE_INTEGER, (map.get(key) ?? 0) + hits));
+const parseProblem = (record, line, tag) => record.problems.push(`invalid ${tag} at lcov line ${line}`);
+
+function lineData(record, value, line) {
+  const [number, count] = value.split(',');
+  const hits = countOf(count ?? '');
+  if (countOf(number) === null || Number(number) < 1 || hits === null) parseProblem(record, line, 'DA');
+  else addHits(record.lines, String(Number(number)), hits);
+}
+
+function functionData(record, tag, value, line) {
+  const at = value.indexOf(',');
+  const count = countOf(value.slice(0, at));
+  let name = value.slice(at + 1);
+  // FN permits an optional end line before the function name; FNDA's names may themselves contain commas.
+  if (tag === 'FN' && /^\d+,/.test(name)) name = name.slice(name.indexOf(',') + 1);
+  if (at < 0 || count === null || !name || (tag === 'FN' && count < 1)) parseProblem(record, line, tag);
+  else if (tag === 'FN') { if (!record.functions.has(name)) record.functions.set(name, 0); }
+  else addHits(record.functions, name, count);
+}
+
+function branchData(record, value, line) {
+  const parts = value.split(',');
+  const hits = parts[3] === '-' ? 0 : countOf(parts[3] ?? '');
+  if (parts.length !== 4 || parts.slice(0, 3).some((part) => countOf(part) === null) || Number(parts[0]) < 1 || hits === null) parseProblem(record, line, 'BRDA');
+  else addHits(record.branches, parts.slice(0, 3).map(Number).join(','), hits);
+}
+
+function summaryData(record, tag, value, line) {
+  const count = countOf(value);
+  if (count === null || Object.hasOwn(record.summary, tag)) parseProblem(record, line, tag);
+  else record.summary[tag] = count;
+}
+
+function recordData(record, tag, value, line, problems) {
+  if (!['DA', 'FN', 'FNDA', 'BRDA', ...Object.keys(SUMMARY)].includes(tag)) return;
+  if (!record) { problems.push(`${tag} outside a source record at lcov line ${line}`); return; }
+  if (tag === 'DA') lineData(record, value, line);
+  else if (tag === 'FN' || tag === 'FNDA') functionData(record, tag, value, line);
+  else if (tag === 'BRDA') branchData(record, value, line);
+  else summaryData(record, tag, value, line);
+}
+
+/** Parse conventional lcov records without executing or reading any referenced source path. */
+function parseLcov(text) {
+  const records = [];
+  const problems = [];
+  let current = null;
+  const flush = () => { if (current) records.push(current); current = null; };
+  for (const [index, raw] of String(text).replace(/^\uFEFF/, '').split(/\r?\n/).entries()) {
+    const line = raw.trim();
+    if (!line) continue;
+    if (line === 'end_of_record') { flush(); continue; }
+    const colon = line.indexOf(':');
+    const tag = line.slice(0, colon);
+    const value = line.slice(colon + 1);
+    if (tag === 'SF') {
+      flush();
+      if (!value || value.includes('\0')) problems.push(`invalid SF at lcov line ${index + 1}`);
+      else current = emptyRecord(value);
+      continue;
+    }
+    recordData(current, tag, value, index + 1, problems);
+  }
+  flush();
+  if (!records.length) problems.push('lcov has no source records');
+  return { records, problems };
+}
+
+/** Apply the same edition data view as the slot resolver before deriving the coverage scope. */
+function manifestOfEdition(manifest, edition) {
+  return {
+    ...manifest,
+    slots: manifest.slots.filter((slot) => slotInEdition(manifest, slot, edition)).map((slot) => effectiveSlot(slot, 'be', edition)),
+    ruleParams: { ...manifest.ruleParams, be: editionRuleParams(manifest.ruleParams.be, edition) },
+  };
+}
+
+function inventory({ files, all, repo, manifest }) {
+  const prefix = repo.profile === 'app' || repo.sides ? 'be/' : '';
+  const effective = manifestOfEdition(manifest, repo.edition ?? 'full');
+  const scope = coverageScope(effective, repo.providers ?? repo.sides?.be?.providers ?? []);
+  const roots = scope.roots.map((dir) => globExpression(`${dir}**`));
+  const excludes = scope.excludes.map((dir) => globExpression(`${dir}**`));
+  const candidates = [...new Set((all ?? files ?? []).map(slash))].filter((file) => file.startsWith(prefix) && SOURCE.test(file) && !SPEC.test(file)).sort(byCodeUnit);
+  const measured = [];
+  const unmeasured = [];
+  for (const file of candidates) {
+    const relative = file.slice(prefix.length);
+    const role = /\.([a-z][a-z0-9-]*)\.ts$/.exec(relative)?.[1];
+    const measuredFile = scope.roles.includes(role) && roots.some((root) => root.test(relative)) && !excludes.some((exclude) => exclude.test(relative));
+    (measuredFile ? measured : unmeasured).push(file);
+  }
+  return { measured, unmeasured, unmeasuredScopes: scope.none.map((entry) => `${prefix}${entry}`), scope, prefix };
+}
+
+function sourcePath(source) {
+  if (source.startsWith('file:')) {
+    try {
+      const uri = new URL(source);
+      source = decodeURIComponent(uri.pathname).replace(/^\/([a-z]:\/)/i, '$1');
+    } catch { return null; }
+  }
+  return slash(source);
+}
+
+function matchesSource(source, file, prefix) {
+  const relative = prefix && file.startsWith(prefix) ? file.slice(prefix.length) : file;
+  const choices = [file, relative, ...(prefix ? [] : [`be/${file}`])];
+  const windows = /^[a-z]:\//i.test(source) || source.startsWith('//');
+  const absolute = source.startsWith('/') || windows;
+  const key = windows ? source.toLowerCase() : source;
+  return choices.some((choice) => {
+    const candidate = windows ? choice.toLowerCase() : choice;
+    return key === candidate || (absolute && key.endsWith(`/${candidate}`));
+  });
+}
+
+function recordsByFile(records, measured, prefix) {
+  const mapped = new Map(measured.map((file) => [file, []]));
+  const problems = [];
+  for (const record of records) {
+    const source = sourcePath(record.source);
+    const matches = source === null ? [] : measured.filter((file) => matchesSource(source, file, prefix));
+    if (matches.length > 1) problems.push(`lcov source ${record.source} matches more than one measured file`);
+    else if (matches.length === 1) mapped.get(matches[0]).push(record);
+  }
+  return { mapped, problems };
+}
+
+function metricOf(record, metric) {
+  const tags = Object.keys(SUMMARY).filter((tag) => SUMMARY[tag][0] === metric);
+  const [foundTag, hitTag] = tags;
+  const details = record[metric];
+  const found = (details.size > 0 || record.summary[foundTag] === 0) ? details.size : record.summary[foundTag];
+  const hit = details.size ? [...details.values()].filter((count) => count > 0).length : record.summary[hitTag];
+  const problems = [];
+  if (found === undefined || hit === undefined) problems.push(`${metric} coverage is unavailable`);
+  else if (hit > found) problems.push(`${metric} hits exceed the denominator`);
+  if (details.size) {
+    if (record.summary[foundTag] !== undefined && record.summary[foundTag] !== found) problems.push(`${foundTag} disagrees with its records`);
+    if (record.summary[hitTag] !== undefined && record.summary[hitTag] !== hit) problems.push(`${hitTag} disagrees with its records`);
+  }
+  return { found, hit, problems, detailed: details.size > 0 };
+}
+
+function measuredMetric(records, metric) {
+  const values = records.map((record) => metricOf(record, metric));
+  const problems = values.flatMap((value) => value.problems);
+  const details = new Map();
+  for (const record of records) for (const [key, hits] of record[metric]) addHits(details, key, hits);
+  // Detailed test-name records merge by line/function/branch identity. Without identities, every summary must prove 100%.
+  const hasOnlyDetails = values.every((value) => value.detailed || value.found === 0);
+  const valid = values.every((value) => !value.problems.length);
+  const worst = values.reduce((lowest, value) => {
+    const rate = (entry) => entry.found === 0 ? 1 : (entry.hit ?? 0) / (entry.found ?? 1);
+    return rate(value) < rate(lowest) || (rate(value) === rate(lowest) && value.found > lowest.found) ? value : lowest;
+  });
+  const found = hasOnlyDetails ? details.size : (worst.found ?? 0);
+  const hit = hasOnlyDetails ? [...details.values()].filter((count) => count > 0).length : (worst.hit ?? 0);
+  let percent = null;
+  if (valid) percent = found === 0 ? 100 : 100 * hit / found;
+  if (valid && hit !== found) problems.push(`${metric} ${hit}/${found} (${(100 * hit / found).toFixed(2)}%) is below 100%`);
+  return { metric: { found, hit, percent }, problems };
+}
+
+function measuredResult(file, records) {
+  const problems = records.flatMap((record) => record.problems);
+  const metrics = {};
+  if (!records.length) return { path: file, metrics, problems: ['no lcov source record for this measured logic file'], ok: false };
+  for (const metric of METRICS) {
+    const result = measuredMetric(records, metric);
+    metrics[metric] = result.metric;
+    problems.push(...result.problems);
+  }
+  return { path: file, metrics, problems: [...new Set(problems)], ok: problems.length === 0 };
+}
+
+/**
+ * Read-only R273 report for an app or be side. `lcov` injects report text; `coverageFrom` selects a path relative to repoRoot.
+ * Only an explicit report enables the check; ordinary app check does not infer a stale report from coverage/lcov.info.
+ */
+export function coverageBelowReport({ repoRoot, files, all, repo, manifest, coverageFrom, lcov } = {}) {
+  const enabled = coverageFrom !== undefined || lcov !== undefined;
+  const reportPath = typeof coverageFrom === 'string' && coverageFrom ? slash(coverageFrom) : '<lcov>';
+  const empty = { ok: true, enabled, reportPath, metrics: METRICS, measured: [], unmeasured: [], unmeasuredScopes: [], results: [], findings: [] };
+  if (!enabled || !repo || !['app', 'be'].includes(repo.profile)) return empty;
+  const boundary = inventory({ files, all, repo, manifest });
+  const report = { ...empty, ...boundary };
+  const reportFailure = (message) => { report.findings.push(found(HFS_COVERAGE_BELOW, reportPath, message)); };
+  if (lcov === undefined) {
+    if (typeof coverageFrom !== 'string' || !coverageFrom) reportFailure('--coverage-from needs an lcov file path');
+    else {
+      try { lcov = fs.readFileSync(path.resolve(repoRoot, coverageFrom), 'utf8'); }
+      catch (error) { reportFailure(`lcov report cannot be read (${error.code ?? 'read failure'}); provide a fresh unit coverage report`); }
+    }
+  }
+  if (lcov !== undefined) {
+    const parsed = parseLcov(lcov);
+    const { mapped, problems } = recordsByFile(parsed.records, boundary.measured, boundary.prefix);
+    for (const problem of [...parsed.problems, ...problems]) reportFailure(problem);
+    report.results = boundary.measured.map((file) => measuredResult(file, mapped.get(file)));
+    for (const result of report.results.filter((entry) => !entry.ok)) report.findings.push(found(HFS_COVERAGE_BELOW, result.path, `${result.path}: ${result.problems.join('; ')}; measured logic files require 100% lines, functions and branches`, { coverage: result.metrics }));
+  }
+  report.ok = report.findings.length === 0;
+  return report;
+}
+
+/** Synchronous finder for the alpha.15 registry; explicit coverage reports may also be passed through extraFindings. */
+export const coverageBelowFindings = (context) => coverageBelowReport(context).findings;