@transitrix/diagrams 1.6.0 → 1.7.6

package/dist/goals/parse-canonical.d.ts

@@ -26,4 +26,9 @@ export interface CanonicalGoalsResult extends ValidationResult {
     /** On success, the internal-form GoalTree derived from the canonical input. */
     parsed?: GoalTree;
 }
+/** Display id for previews — canonical `GOAL-…` when present, else internal numeric id. */
+export declare function displayGoalId(goal: {
+    id: number;
+    canonical_id?: string;
+}): string;
 export declare function parseCanonicalGoals(input: unknown): CanonicalGoalsResult;

package/dist/goals/parse-canonical.js

@@ -22,6 +22,10 @@
  */
 const GOAL_ID_RE = /^GOAL(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
 const GOALS_DOC_ID_RE = /^GOALS(-[A-Z0-9][A-Z0-9_]*)*-\d+$/;
+/** Display id for previews — canonical `GOAL-…` when present, else internal numeric id. */
+export function displayGoalId(goal) {
+    return goal.canonical_id ?? String(goal.id);
+}
 function isNonEmptyString(v) {
     return typeof v === 'string' && v.trim().length > 0;
 }
@@ -240,6 +244,7 @@ export function parseCanonicalGoals(input) {
         const parentId = isNonEmptyString(parent) && idToInternal.has(parent) ? idToInternal.get(parent) : 0;
         return {
             id: idToInternal.get(o['id']),
+            canonical_id: o['id'],
             name: o['name'],
             type: o['type'],
             level: o['level'],

package/dist/goals/types.d.ts

@@ -8,6 +8,8 @@ export interface Factor {
 }
 export interface Goal {
     id: number;
+    /** Canonical typed id from the YAML (`GOAL-…`) when parsed from canonical form. */
+    canonical_id?: string;
     name: string;
     type: string;
     level: number;

package/dist/repo-validate/types.js

@@ -4,9 +4,8 @@
 // referential integrity, atomicity, ID uniqueness, policy — the checks that the
 // methodology's Python `.validators/lint.py` owns today. This converges those
 // checks onto the shared TypeScript model so there is a single validation
-// runtime (methodology ADR
-// `2026-06-11-validation-two-axis-model.md`; Studio referencing ADR
-// `docs/decisions/2026-06-11-validation-runtime-convergence.md`).
+// runtime (methodology ADR "Validation Two-Axis Model"; Studio decision
+// "Validation Runtime Convergence").
 //
 // The finding shape is deliberately minimal — `{ scope, id, message }`. The
 // richer `target` / `category` reporting taxonomy is explicitly DEFERRED per the

package/dist/webview/__tests__/render-goals.test.js

@@ -58,8 +58,22 @@ describe('renderGoalsSvg', () => {
         expect(svg).toContain('width="0"');
         expect(svg).toContain('height="0"');
     });
-    it('omits the title block when treeName is missing', () => {
-        const svg = renderGoalsSvg(SIMPLE_TREE);
-        expect(svg).not.toContain('Goal tree —');
+    it('shows canonical goal ids in node labels when present', () => {
+        const tree = {
+            goal_types: [{ name: 'Strategy', level: 0 }],
+            goals: [
+                {
+                    id: 1,
+                    canonical_id: 'GOAL-REVENUE-1',
+                    name: 'Triple revenue',
+                    type: 'Strategy',
+                    level: 0,
+                    parent_id: 0,
+                },
+            ],
+        };
+        const svg = renderGoalsSvg(tree);
+        expect(svg).toContain('GOAL-REVENUE-1');
+        expect(svg).not.toMatch(/>\s*1\s*</);
     });
 });

package/dist/webview/render-goals.js

@@ -11,6 +11,7 @@
  * Step 4 will follow the same shape for the remaining ten notations.
  */
 import { layoutGoalTree } from '../goals/layout.js';
+import { displayGoalId } from '../goals/parse-canonical.js';
 import { horizontalCubicEdgePath, DEFAULT_EDGE_CURVATURE } from '../edge-path.js';
 import { generateSvgEmbedCss } from '../theme/index.js';
 import { escXml } from './render-util.js';
@@ -102,7 +103,7 @@ export function renderGoalsLayoutSvg(layout, options = {}) {
         const typeY = twoLines ? y + 43 : y + 35;
         const idY = twoLines ? y + 59 : y + 55;
         const typeLabel = n.data.type ?? '';
-        const idText = String(n.data.id);
+        const idText = displayGoalId(n.data);
         return `<g>
   <rect class="diagram-node level-${level}" x="${x}" y="${y}" width="${n.width}" height="${n.height}" rx="${ENTITY_NODE_RX}"/>
   <text class="text-primary" x="${x + n.width / 2}" y="${nameY1}" text-anchor="middle" dominant-baseline="central">${escXml(line1)}</text>${twoLines ? `

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@transitrix/diagrams",
-  "version": "1.6.0",
+  "version": "1.7.6",
   "type": "module",
   "description": "Shared rendering, validation, and pure mutations for Transitrix custom diagram formats.",
   "license": "MIT",

package/src/codex/__tests__/example.test.ts

@@ -0,0 +1,40 @@
+// Conformance test for CODEX worked examples under
+// `tests/fixtures/notation-corpus/codex/` — pins #518 Phase C2 corpus signal.
+
+import { describe, it, expect } from 'vitest';
+import { readFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { validateCodex, folderJurisdictionFromPath } from '../validate.js';
+
+const corpusRoot = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '../../../../../tests/fixtures/notation-corpus/codex',
+);
+
+function codexFixturePaths(): Array<{ rel: string; folderJurisdiction?: string }> {
+  const out: Array<{ rel: string; folderJurisdiction?: string }> = [];
+  for (const zone of ['external/EU', 'internal']) {
+    const dir = path.join(corpusRoot, zone);
+    for (const f of readdirSync(dir).filter((x) => x.endsWith('.yaml'))) {
+      const rel = path.join('codex', zone, f).replace(/\\/g, '/');
+      out.push({
+        rel,
+        folderJurisdiction: folderJurisdictionFromPath(rel),
+      });
+    }
+  }
+  return out;
+}
+
+describe('codex worked examples (notation-corpus)', () => {
+  for (const { rel, folderJurisdiction } of codexFixturePaths()) {
+    it(`validates ${rel} without error`, () => {
+      const data = yaml.load(readFileSync(path.join(corpusRoot, rel.replace(/^codex\//, '')), 'utf-8'));
+      const v = validateCodex(data, { folderJurisdiction });
+      expect(v.valid, JSON.stringify(v.errors)).toBe(true);
+      expect(v.errors).toHaveLength(0);
+    });
+  }
+});

package/src/codex/__tests__/validate.test.ts

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import {
+  validateCodex,
+  isCodexDoc,
+  folderJurisdictionFromPath,
+} from '../validate.js';
+
+const VALID_EXTERNAL = {
+  zone: 'codex',
+  id: 'LAW-GDPR-1',
+  name: 'General Data Protection Regulation',
+  type: 'LAW',
+  jurisdiction: 'eu',
+  effective_date: '2018-05-25',
+  admitted_at: '2026-06-01',
+  admitted_by: 'legal.team',
+  gate_checks: { uniqueness: 'pass' },
+};
+
+const VALID_INTERNAL = {
+  zone: 'codex',
+  id: 'INTERNAL_STANDARD-coding-conventions-1',
+  name: 'Engineering Coding Conventions',
+  type: 'INTERNAL_STANDARD',
+  issuing_authority: 'VP Engineering',
+  effective_date: '2026-01-01',
+  admitted_at: '2026-05-27',
+  admitted_by: 'vp.engineering',
+  gate_checks: { source_authority: 'VP Engineering' },
+};
+
+describe('validateCodex', () => {
+  it('accepts a valid external artefact', () => {
+    const r = validateCodex(VALID_EXTERNAL, { folderJurisdiction: 'eu' });
+    expect(r.valid, JSON.stringify(r.errors)).toBe(true);
+  });
+
+  it('accepts a valid internal artefact', () => {
+    expect(validateCodex(VALID_INTERNAL).valid).toBe(true);
+  });
+
+  it('CODEX-001 rejects non-mapping input', () => {
+    expect(validateCodex(null).errors.some((e) => e.code === 'CODEX-001')).toBe(true);
+  });
+
+  it('CODEX-001 rejects wrong zone', () => {
+    const r = validateCodex({ ...VALID_EXTERNAL, zone: 'canon' });
+    expect(r.errors.some((e) => e.code === 'CODEX-001' && e.path === 'zone')).toBe(true);
+  });
+
+  it('CODEX-002 rejects type/id prefix mismatch', () => {
+    const r = validateCodex({ ...VALID_EXTERNAL, type: 'REGULATION' });
+    expect(r.errors.some((e) => e.code === 'CODEX-002')).toBe(true);
+  });
+
+  it('CODEX-003 requires jurisdiction on external artefacts', () => {
+    const r = validateCodex({ ...VALID_EXTERNAL, jurisdiction: '' });
+    expect(r.errors.some((e) => e.code === 'CODEX-003' && e.path === 'jurisdiction')).toBe(true);
+  });
+
+  it('CODEX-005 enforces folder jurisdiction match', () => {
+    const r = validateCodex(VALID_EXTERNAL, { folderJurisdiction: 'ge' });
+    expect(r.errors.some((e) => e.code === 'CODEX-005')).toBe(true);
+  });
+
+  it('CODEX-004 requires issuing_authority on internal artefacts', () => {
+    const r = validateCodex({ ...VALID_INTERNAL, issuing_authority: '' });
+    expect(r.errors.some((e) => e.code === 'CODEX-004')).toBe(true);
+  });
+});
+
+describe('isCodexDoc', () => {
+  it('detects zone: codex', () => {
+    expect(isCodexDoc({ zone: 'codex', id: 'LAW-1' })).toBe(true);
+    expect(isCodexDoc({ zone: 'canon' })).toBe(false);
+  });
+});
+
+describe('folderJurisdictionFromPath', () => {
+  it('parses codex/external/<jurisdiction>/ paths', () => {
+    expect(folderJurisdictionFromPath('codex/external/eu/LAW-GDPR-1.yaml')).toBe('eu');
+    expect(folderJurisdictionFromPath('codex/internal/POLICY-1.yaml')).toBeUndefined();
+  });
+});

package/src/codex/index.ts

@@ -0,0 +1,4 @@
+export { CODEX_ARTEFACT_TYPES, EXTERNAL_CODEX_TYPES, INTERNAL_CODEX_TYPES } from './types.js';
+export type { CodexArtefactType } from './types.js';
+export { validateCodex, isCodexDoc, folderJurisdictionFromPath } from './validate.js';
+export type { CodexValidateOptions } from './validate.js';

package/src/codex/types.ts

@@ -0,0 +1,13 @@
+// Codex artefact — external laws/regulations and internal policies/standards.
+// Schema: methodology notations/elements/14-codex.md §3–§4.
+
+/** TYPE prefixes admitted in the codex zone (REQ-003 / 14-codex.md). */
+export const CODEX_ARTEFACT_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'] as const;
+
+export type CodexArtefactType = (typeof CODEX_ARTEFACT_TYPES)[number];
+
+/** External codex artefacts (codex/external/<jurisdiction>/). */
+export const EXTERNAL_CODEX_TYPES: readonly CodexArtefactType[] = ['LAW', 'REGULATION'];
+
+/** Internal codex artefacts (codex/internal/). */
+export const INTERNAL_CODEX_TYPES: readonly CodexArtefactType[] = ['POLICY', 'INTERNAL_STANDARD'];

package/src/codex/validate.ts

@@ -0,0 +1,125 @@
+// CODEX validator — methodology notations/elements/14-codex.md §4.
+//
+// CODEX-001 — shape, zone, id grammar, admission envelope.
+// CODEX-002 — `type` field matches the id TYPE prefix when present.
+// CODEX-003 — external artefact frontmatter (jurisdiction, effective_date).
+// CODEX-004 — internal artefact frontmatter (issuing_authority, effective_date).
+// CODEX-005 — jurisdiction must match the parent folder under codex/external/
+//             (when `folderJurisdiction` is supplied by the repo sweep).
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { isCanonicalId, typeOfId } from '../typed-id.js';
+import {
+  CODEX_ARTEFACT_TYPES,
+  EXTERNAL_CODEX_TYPES,
+  INTERNAL_CODEX_TYPES,
+  type CodexArtefactType,
+} from './types.js';
+
+export interface CodexValidateOptions {
+  /** Lowercased jurisdiction folder segment from `codex/external/<jurisdiction>/`. */
+  folderJurisdiction?: string;
+}
+
+function isCodexType(type: string | null): type is CodexArtefactType {
+  return type !== null && (CODEX_ARTEFACT_TYPES as readonly string[]).includes(type);
+}
+
+function normalizeType(value: unknown): string | undefined {
+  if (typeof value !== 'string' || value.trim() === '') return undefined;
+  return value.trim().toUpperCase();
+}
+
+export function validateCodex(input: unknown, options: CodexValidateOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'CODEX-001', message: 'Codex artefact must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const c = input as Record<string, unknown>;
+
+  if (c.zone !== 'codex') {
+    errors.push({ code: 'CODEX-001', message: 'zone must be the fixed value "codex".', path: 'zone' });
+  }
+
+  const idType = typeOfId(c.id);
+  if (!isCanonicalId(c.id) || !isCodexType(idType)) {
+    errors.push({
+      code: 'CODEX-001',
+      message: `id "${String(c.id)}" must be a typed codex id (LAW, REGULATION, POLICY, or INTERNAL_STANDARD).`,
+      path: 'id',
+    });
+  }
+
+  if (typeof c.name !== 'string' || c.name.trim() === '') {
+    errors.push({ code: 'CODEX-001', message: 'name is required.', path: 'name' });
+  }
+  for (const field of ['admitted_at', 'admitted_by'] as const) {
+    const v = c[field];
+    if (typeof v !== 'string' || v.trim() === '') {
+      errors.push({ code: 'CODEX-001', message: `${field} is required.`, path: field });
+    }
+  }
+  if (c.gate_checks === null || typeof c.gate_checks !== 'object' || Array.isArray(c.gate_checks)) {
+    errors.push({ code: 'CODEX-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+
+  const declaredType = normalizeType(c.type);
+  if (declaredType !== undefined && idType && declaredType !== idType) {
+    errors.push({
+      code: 'CODEX-002',
+      message: `type "${String(c.type)}" does not match the id TYPE prefix "${idType}".`,
+      path: 'type',
+    });
+  }
+
+  const artefactType = (declaredType ?? idType) as CodexArtefactType | null;
+
+  if (artefactType && (EXTERNAL_CODEX_TYPES as readonly string[]).includes(artefactType)) {
+    const jurisdiction = typeof c.jurisdiction === 'string' ? c.jurisdiction.trim() : '';
+    if (!jurisdiction) {
+      errors.push({ code: 'CODEX-003', message: 'jurisdiction is required for external codex artefacts.', path: 'jurisdiction' });
+    } else if (options.folderJurisdiction && jurisdiction.toLowerCase() !== options.folderJurisdiction.toLowerCase()) {
+      errors.push({
+        code: 'CODEX-005',
+        message: `jurisdiction "${jurisdiction}" must match the parent folder "${options.folderJurisdiction}" (CODEX-001).`,
+        path: 'jurisdiction',
+      });
+    }
+    if (typeof c.effective_date !== 'string' || c.effective_date.trim() === '') {
+      errors.push({ code: 'CODEX-003', message: 'effective_date is required for external codex artefacts.', path: 'effective_date' });
+    }
+  }
+
+  if (artefactType && (INTERNAL_CODEX_TYPES as readonly string[]).includes(artefactType)) {
+    if (typeof c.issuing_authority !== 'string' || c.issuing_authority.trim() === '') {
+      errors.push({
+        code: 'CODEX-004',
+        message: 'issuing_authority is required for internal codex artefacts.',
+        path: 'issuing_authority',
+      });
+    }
+    if (typeof c.effective_date !== 'string' || c.effective_date.trim() === '') {
+      errors.push({ code: 'CODEX-004', message: 'effective_date is required for internal codex artefacts.', path: 'effective_date' });
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+/** True when a parsed document is a codex-zone artefact candidate. */
+export function isCodexDoc(data: unknown): boolean {
+  if (data === null || typeof data !== 'object' || Array.isArray(data)) return false;
+  return (data as Record<string, unknown>).zone === 'codex';
+}
+
+/** Infer codex folder jurisdiction from a repo-relative path such as
+ *  `codex/external/eu/LAW-GDPR-1.yaml` → `eu`. */
+export function folderJurisdictionFromPath(filePath: string): string | undefined {
+  const parts = filePath.replace(/\\/g, '/').toLowerCase().split('/');
+  const extIdx = parts.indexOf('external');
+  if (extIdx < 0 || extIdx + 1 >= parts.length) return undefined;
+  return parts[extIdx + 1] || undefined;
+}

package/src/compliance/__tests__/canon-catalog.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  admitDocumentToCatalog,
+  buildComplianceScan,
+  catalogFromMap,
+} from '../canon-catalog.js';
+
+describe('buildComplianceScan', () => {
+  it('admits codex, requirement, and assertion ids into the catalogue', () => {
+    const docs = [
+      {
+        path: 'codex/external/ge/LAW-PERSONAL-DATA-2017-1.yaml',
+        data: {
+          zone: 'codex',
+          id: 'LAW-PERSONAL-DATA-2017-1',
+          name: 'Law',
+          type: 'LAW',
+        },
+      },
+      {
+        path: 'canon/elements/01_motivation/requirements/REQUIREMENT-DATA-ERASURE-1.yaml',
+        data: {
+          notation: 'requirement',
+          id: 'REQUIREMENT-DATA-ERASURE-1',
+          name: 'Erasure',
+          derived_from: ['LAW-PERSONAL-DATA-2017-1'],
+        },
+      },
+      {
+        path: 'canon/elements/02_business/products/PRODUCT-MOBILE-1.yaml',
+        data: { notation: 'product', id: 'PRODUCT-MOBILE-1', name: 'Mobile' },
+      },
+      {
+        path: 'canon/assertions/ASSERTION-MOBILE-DATA-ERASURE-1.yaml',
+        data: {
+          notation: 'assertion',
+          id: 'ASSERTION-MOBILE-DATA-ERASURE-1',
+          about: 'REQUIREMENT-DATA-ERASURE-1',
+          subject: 'PRODUCT-MOBILE-1',
+          status: 'compliant',
+        },
+      },
+    ];
+
+    const { catalog, complianceCanon, pathById } = buildComplianceScan(docs);
+    expect(catalog.typeOf('LAW-PERSONAL-DATA-2017-1')).toBe('LAW');
+    expect(catalog.typeOf('REQUIREMENT-DATA-ERASURE-1')).toBe('REQUIREMENT');
+    expect(catalog.typeOf('PRODUCT-MOBILE-1')).toBe('PRODUCT');
+    expect(complianceCanon.requirements).toHaveLength(1);
+    expect(complianceCanon.assertions).toHaveLength(1);
+    expect(complianceCanon.codex).toHaveLength(1);
+    expect(pathById.get('REQUIREMENT-DATA-ERASURE-1')).toContain('requirements/');
+  });
+});
+
+describe('admitDocumentToCatalog', () => {
+  it('uses explicit codex type when the id prefix is ambiguous', () => {
+    const map = new Map<string, string>();
+    admitDocumentToCatalog(map, {
+      zone: 'codex',
+      id: 'INTERNAL_STANDARD-coding-conventions-1',
+      type: 'INTERNAL_STANDARD',
+    });
+    const catalog = catalogFromMap(map);
+    expect(catalog.typeOf('INTERNAL_STANDARD-coding-conventions-1')).toBe('INTERNAL_STANDARD');
+  });
+});

package/src/compliance/__tests__/view-resolution.test.ts

@@ -0,0 +1,80 @@
+import { describe, it, expect } from 'vitest';
+
+import { emptyCanon } from '../classify.js';
+import { catalogFromMap } from '../canon-catalog.js';
+import { collectImpactViewResolutionFindings } from '../impact.js';
+import { collectCoverageViewResolutionFindings } from '../coverage-metric.js';
+import type { ImpactViewConfig } from '../impact.js';
+import type { CoverageMetricConfig } from '../coverage-metric.js';
+
+const catalog = catalogFromMap(
+  new Map([
+    ['PRODUCT-ECOMM-1', 'PRODUCT'],
+    ['REQUIREMENT-GDPR-1', 'REQUIREMENT'],
+    ['LAW-GDPR-1', 'LAW'],
+  ]),
+);
+
+const complianceCanon = emptyCanon();
+complianceCanon.products.push({ id: 'PRODUCT-ECOMM-1', name: 'E-Commerce' });
+complianceCanon.requirements.push({ id: 'REQUIREMENT-GDPR-1', name: 'GDPR req' });
+complianceCanon.codex.push({ id: 'LAW-GDPR-1', name: 'GDPR' });
+
+describe('collectImpactViewResolutionFindings', () => {
+  const base: ImpactViewConfig = {
+    id: 'test-impact',
+    name: 'Test',
+    subjects: { products: ['PRODUCT-ECOMM-1'], processes: [], capabilities: [] },
+    obligations: { filter: { derived_from_codex: ['LAW-GDPR-1'] } },
+    status_display: { show: ['compliant'] },
+    empty_cells: {},
+    order_rows_by: 'id',
+  };
+
+  it('passes when subjects and regimes resolve', () => {
+    expect(collectImpactViewResolutionFindings(base, catalog, complianceCanon)).toEqual([]);
+  });
+
+  it('flags unresolved subjects and regimes', () => {
+    const findings = collectImpactViewResolutionFindings(
+      {
+        ...base,
+        subjects: { products: ['PRODUCT-MISSING-1'], processes: [], capabilities: [] },
+        obligations: { include: ['REQUIREMENT-MISSING-1'], filter: { derived_from_codex: ['LAW-MISSING-1'] } },
+      },
+      catalog,
+      complianceCanon,
+    );
+    expect(findings.some((f) => f.code === 'COMPIMP-REF' && f.message.includes('PRODUCT-MISSING-1'))).toBe(true);
+    expect(findings.some((f) => f.message.includes('REQUIREMENT-MISSING-1'))).toBe(true);
+    expect(findings.some((f) => f.message.includes('LAW-MISSING-1'))).toBe(true);
+  });
+});
+
+describe('collectCoverageViewResolutionFindings', () => {
+  const base: CoverageMetricConfig = {
+    id: 'test-coverage',
+    name: 'Test',
+    thresholds: { green: 0.9, amber: 0.7 },
+    subjects: { products: ['PRODUCT-ECOMM-1'] },
+    regimes: { include: ['LAW-GDPR-1'] },
+  };
+
+  it('passes when products and regimes resolve', () => {
+    expect(collectCoverageViewResolutionFindings(base, catalog, complianceCanon)).toEqual([]);
+  });
+
+  it('flags unresolved product and regime refs', () => {
+    const findings = collectCoverageViewResolutionFindings(
+      {
+        ...base,
+        subjects: { products: ['PRODUCT-MISSING-1'] },
+        regimes: { include: ['LAW-MISSING-1'] },
+      },
+      catalog,
+      complianceCanon,
+    );
+    expect(findings.some((f) => f.code === 'COVMET-REF')).toBe(true);
+    expect(findings).toHaveLength(2);
+  });
+});

package/src/compliance/canon-catalog.ts

@@ -0,0 +1,76 @@
+// CanonCatalog builder — repo-scope cross-reference resolution (#518 Phase C3).
+//
+// Scans admitted YAML documents and builds the `{ typeOf }` catalogue that
+// `validateRequirement` / `validateAssertion` accept for REQ-002 and
+// ASSERT-002..005 resolution.
+
+import { typeOfId, type CanonCatalog } from '../typed-id.js';
+import { emptyCanon, ingestComplianceDoc, type ComplianceCanon } from './classify.js';
+
+export interface ScannedYamlDoc {
+  path: string;
+  data: unknown;
+}
+
+export interface ComplianceScanResult {
+  complianceCanon: ComplianceCanon;
+  catalog: CanonCatalog;
+  /** First path where each admitted id was seen (for gap-dashboard warnings). */
+  pathById: Map<string, string>;
+}
+
+function strId(doc: unknown): string | undefined {
+  if (doc === null || typeof doc !== 'object' || Array.isArray(doc)) return undefined;
+  const id = (doc as Record<string, unknown>).id;
+  return typeof id === 'string' && id.trim() !== '' ? id.trim() : undefined;
+}
+
+/** Admit one parsed document into the id → TYPE map. */
+export function admitDocumentToCatalog(map: Map<string, string>, doc: unknown): string | undefined {
+  const id = strId(doc);
+  if (!id) return undefined;
+
+  const fromPrefix = typeOfId(id);
+  if (fromPrefix) {
+    map.set(id, fromPrefix);
+    return id;
+  }
+
+  if (doc !== null && typeof doc === 'object' && !Array.isArray(doc)) {
+    const d = doc as Record<string, unknown>;
+    if (d.zone === 'codex') {
+      const explicit = typeof d.type === 'string' ? d.type.trim().toUpperCase() : undefined;
+      if (explicit) {
+        map.set(id, explicit);
+        return id;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Build a read-only `CanonCatalog` from a populated id → TYPE map. */
+export function catalogFromMap(map: Map<string, string>): CanonCatalog {
+  return { typeOf: (id: string) => map.get(id) };
+}
+
+/** Ingest compliance projections and admit cross-reference targets from a batch
+ *  of already-parsed YAML documents (no IO). */
+export function buildComplianceScan(docs: ScannedYamlDoc[]): ComplianceScanResult {
+  const complianceCanon = emptyCanon();
+  const catalogMap = new Map<string, string>();
+  const pathById = new Map<string, string>();
+
+  for (const { path, data } of docs) {
+    const ingested = ingestComplianceDoc(complianceCanon, data);
+    if (ingested) pathById.set(ingested, path);
+    const admitted = admitDocumentToCatalog(catalogMap, data);
+    if (admitted && !pathById.has(admitted)) pathById.set(admitted, path);
+  }
+
+  return {
+    complianceCanon,
+    catalog: catalogFromMap(catalogMap),
+    pathById,
+  };
+}

package/src/compliance/coverage-metric.ts

@@ -8,6 +8,7 @@
 import type { AssertionStatus } from '../assertion/types.js';
 import type { ComplianceCanon } from './classify.js';
 import { buildComplianceIndex } from './reverse-index.js';
+import type { CanonCatalog } from '../typed-id.js';
 import type { IndexAssertion } from './types.js';
 
 // ── Config types ─────────────────────────────────────────────────────────────
@@ -93,6 +94,55 @@ export interface CoverageMatrix {
   thresholds: CoverageMetricThresholds;
 }
 
+/** Repo-scope cross-reference finding for a coverage-metric view (#518 C3). */
+export interface CoverageViewFinding {
+  code: string;
+  severity: 'error' | 'warning';
+  message: string;
+}
+
+/**
+ * Repo-scope cross-reference checks for a parsed coverage-metric view config.
+ * Surfaces unresolved product and regime ids before `buildCoverageMatrix` runs.
+ */
+export function collectCoverageViewResolutionFindings(
+  config: CoverageMetricConfig,
+  catalog: CanonCatalog,
+  complianceCanon: ComplianceCanon,
+): CoverageViewFinding[] {
+  const findings: CoverageViewFinding[] = [];
+  const codexIds = new Set(complianceCanon.codex.map((c) => c.id));
+
+  for (const id of config.subjects?.products ?? []) {
+    const t = catalog.typeOf(id);
+    if (t === undefined) {
+      findings.push({
+        code: 'COVMET-REF',
+        severity: 'error',
+        message: `subjects.products: "${id}" does not resolve to an admitted artefact.`,
+      });
+    } else if (t !== 'PRODUCT') {
+      findings.push({
+        code: 'COVMET-REF',
+        severity: 'error',
+        message: `subjects.products: "${id}" resolves to ${t}, not PRODUCT.`,
+      });
+    }
+  }
+
+  for (const id of config.regimes?.include ?? []) {
+    if (!codexIds.has(id)) {
+      findings.push({
+        code: 'COVMET-REF',
+        severity: 'error',
+        message: `regimes.include: "${id}" does not resolve to an admitted codex artefact.`,
+      });
+    }
+  }
+
+  return findings;
+}
+
 // ── Parser ───────────────────────────────────────────────────────────────────
 
 function parseRegimes(raw: Record<string, unknown>): { regimes?: CoverageMetricRegimes; warnings: string[] } {