@transitrix/diagrams 1.14.0-rc.0 → 1.15.0

package/src/applications/validate.ts

@@ -1,3 +1,4 @@
+import { schemaFinding } from '../schema-finding.js';
 import type { ApplicationsCatalogueFile, ApplicationType, ApplicationStatus, IntegrationDirection } from './types.js';
 import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
 
@@ -27,23 +28,23 @@ export function validateApplicationsCatalogue(input: unknown): ValidationResult
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
-  if (!input || typeof input !== 'object') {
-    return { valid: false, errors: [{ code: 'APP-001', message: 'Input must be an object' }], warnings };
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return { valid: false, errors: [schemaFinding('applications inline', '$', 'mapping', input)], warnings };
   }
 
   const raw = input as Record<string, unknown>;
 
   // APP-001: notation header
   if (!('notation' in raw)) {
-    errors.push({ code: 'APP-001', message: 'Missing required field: notation' });
+    errors.push({ code: 'HDR-001', message: 'notation field is missing' });
   } else if (raw['notation'] !== 'applications') {
-    errors.push({ code: 'APP-001', message: `notation must be "applications", got "${raw['notation']}"` });
+    errors.push({ code: 'HDR-002', message: 'notation must be applications' });
   }
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 
   // APP-002: catalogue header fields
-  if (!raw['applications_catalogue'] || typeof raw['applications_catalogue'] !== 'object') {
+  if (!raw['applications_catalogue'] || typeof raw['applications_catalogue'] !== 'object' || Array.isArray(raw['applications_catalogue'])) {
     errors.push({ code: 'APP-002', message: 'Missing required field: applications_catalogue' });
     return { valid: false, errors, warnings };
   }
@@ -62,9 +63,9 @@ export function validateApplicationsCatalogue(input: unknown): ValidationResult
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 
-  // APP-007: updated_at format
+  // Schema: updated_at format
   if (!DATE_RE.test(cat['updated_at'] as string)) {
-    errors.push({ code: 'APP-007', message: `applications_catalogue.updated_at must be YYYY-MM-DD, got "${cat['updated_at']}"` });
+    errors.push(schemaFinding('applications inline', 'applications_catalogue.updated_at', 'YYYY-MM-DD string', cat['updated_at']));
   }
 
   const applications = cat['applications'];
@@ -73,55 +74,55 @@ export function validateApplicationsCatalogue(input: unknown): ValidationResult
     return { valid: false, errors, warnings };
   }
 
-  // APP-008: unique app_id
+  // Schema: unique app_id
   const seenIds = new Set<string>();
 
   for (let i = 0; i < applications.length; i++) {
     const rawApp = applications[i];
     const idx = `applications[${i}]`;
 
-    if (!rawApp || typeof rawApp !== 'object') {
-      errors.push({ code: 'APP-003', message: `${idx} must be an object` });
+    if (!rawApp || typeof rawApp !== 'object' || Array.isArray(rawApp)) {
+      errors.push(schemaFinding('applications inline', `${idx}`, 'mapping', rawApp));
       continue;
     }
     const a = rawApp as Record<string, unknown>;
 
-    // APP-003: required per-application fields
+    // Schema: required per-application fields
     if (!a['app_id'] || typeof a['app_id'] !== 'string' || !(a['app_id'] as string).trim()) {
-      errors.push({ code: 'APP-003', message: `${idx}: app_id is required` });
+      errors.push(schemaFinding('applications inline', `${idx}.app_id`, 'nonempty string', a['app_id']));
     } else {
       const aid = a['app_id'] as string;
       if (seenIds.has(aid)) {
-        errors.push({ code: 'APP-008', message: `Duplicate app_id: "${aid}"` });
+        errors.push(schemaFinding('applications inline', `${idx}.app_id`, 'unique identifier', a['app_id']));
       }
       seenIds.add(aid);
     }
 
     if (!a['name'] || typeof a['name'] !== 'string' || !(a['name'] as string).trim()) {
-      errors.push({ code: 'APP-003', message: `${idx}: name is required` });
+      errors.push(schemaFinding('applications inline', `${idx}.name`, 'nonempty string', a['name']));
     }
     if (!a['type']) {
-      errors.push({ code: 'APP-003', message: `${idx}: type is required` });
+      errors.push(schemaFinding('applications inline', `${idx}.type`, `one of ${[...VALID_TYPES].join(", ")}`, a['type']));
     }
     if (!a['status']) {
-      errors.push({ code: 'APP-003', message: `${idx}: status is required` });
+      errors.push(schemaFinding('applications inline', `${idx}.status`, `one of ${[...VALID_STATUSES].join(", ")}`, a['status']));
     }
 
-    // APP-004: type enum
+    // Schema: type enum
     if (a['type'] && !VALID_TYPES.has(a['type'] as ApplicationType)) {
-      errors.push({ code: 'APP-004', message: `${idx}: type "${a['type']}" must be one of: application, integration, platform, data_store` });
+      errors.push(schemaFinding('applications inline', `${idx}.type`, `one of ${[...VALID_TYPES].join(", ")}`, a['type']));
     }
 
-    // APP-005: status enum (4 values)
+    // Schema: status enum (4 values)
     if (a['status'] && !VALID_STATUSES.has(a['status'] as ApplicationStatus)) {
-      errors.push({ code: 'APP-005', message: `${idx}: status "${a['status']}" must be one of: Draft, Active, Deprecated, Decommissioning` });
+      errors.push(schemaFinding('applications inline', `${idx}.status`, `one of ${[...VALID_STATUSES].join(", ")}`, a['status']));
     }
 
-    // APP-006: maturity range
+    // Schema: maturity range
     if (a['maturity'] !== undefined) {
       const m = a['maturity'];
       if (typeof m !== 'number' || !Number.isInteger(m) || m < 1 || m > 5) {
-        errors.push({ code: 'APP-006', message: `${idx}: maturity must be an integer 1–5, got "${m}"` });
+        errors.push(schemaFinding('applications inline', `${idx}.maturity`, 'integer in 1–5', a['maturity']));
       }
     }
 
@@ -137,18 +138,18 @@ export function validateApplicationsCatalogue(input: unknown): ValidationResult
       }
     }
 
-    // APP-009: integrations[].direction enum
+    // Schema: integrations[].direction enum
     if (Array.isArray(a['integrations'])) {
       const integrations = a['integrations'] as unknown[];
       for (let j = 0; j < integrations.length; j++) {
         const rawIntg = integrations[j];
-        if (!rawIntg || typeof rawIntg !== 'object') {
-          errors.push({ code: 'APP-009', message: `${idx}.integrations[${j}] must be an object` });
+        if (!rawIntg || typeof rawIntg !== 'object' || Array.isArray(rawIntg)) {
+          errors.push(schemaFinding('applications inline', `${idx}.integrations[${j}]`, 'mapping', rawIntg));
           continue;
         }
         const intg = rawIntg as Record<string, unknown>;
         if (intg['direction'] !== undefined && !VALID_DIRECTIONS.has(intg['direction'] as IntegrationDirection)) {
-          errors.push({ code: 'APP-009', message: `${idx}.integrations[${j}]: direction "${intg['direction']}" must be one of: inbound, outbound, bidirectional` });
+          errors.push(schemaFinding('applications inline', `${idx}.integrations[${j}].direction`, 'inbound | outbound | bidirectional', intg['direction']));
         }
 
         // INT-001 — when interface_semantics: true, four fields become required.

package/src/capability-map/validate.ts

@@ -1,3 +1,5 @@
+import type { ResolvedCapabilityAttributes } from './resolve-maturity.js';
+import { schemaFinding } from '../schema-finding.js';
 import type { CapabilityType } from './types.js';
 import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
 
@@ -11,31 +13,25 @@ const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 // canonical prefix do not break; migration is tracked separately.
 const CAP_ID_RE = /^(CAPABILITY-)?(V|H)\d+(\.\d+)*$/;
 
-export function validateCapabilityMap(input: unknown): ValidationResult {
+export function validateCapabilityMap(input: unknown, options: { resolvedAttributes?: ReadonlyMap<string, ResolvedCapabilityAttributes> } = {}): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
-  if (!input || typeof input !== 'object') {
-    return { valid: false, errors: [{ code: 'CMAP-001', message: 'Input must be an object' }], warnings };
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return { valid: false, errors: [schemaFinding('capability-map inline', '$', 'mapping', input)], warnings };
   }
   const raw = input as Record<string, unknown>;
 
-  // HDR-001/002 — DSM's own rule codes for the same header check CMAP-001
-  // already makes (api02/internal/importer/capabilities.go ValidateCapMap),
-  // added alongside it (not instead of it) so DSM can map a finding straight
-  // back onto its own import-log taxonomy while CMAP-001 stays the richer,
-  // pre-existing Studio-native code for this notation's own validator.
+  // Shared header rules have precedence over generic schema findings.
   if (!('notation' in raw)) {
-    errors.push({ code: 'CMAP-001', message: 'Missing required field: notation' });
     errors.push({ code: 'HDR-001', message: 'notation field is missing' });
   } else if (raw['notation'] !== 'capability-map') {
-    errors.push({ code: 'CMAP-001', message: `notation must be "capability-map", got "${raw['notation']}"` });
     errors.push({ code: 'HDR-002', message: `notation must be "capability-map", got "${raw['notation']}"` });
   }
   if (errors.length > 0) return { valid: false, errors, warnings };
 
   const map = raw['capability_map'];
-  if (!map || typeof map !== 'object') {
+  if (!map || typeof map !== 'object' || Array.isArray(map)) {
     errors.push({ code: 'CMAP-002', message: 'Missing required field: capability_map' });
     return { valid: false, errors, warnings };
   }
@@ -51,7 +47,7 @@ export function validateCapabilityMap(input: unknown): ValidationResult {
   if (errors.length > 0) return { valid: false, errors, warnings };
 
   if (!DATE_RE.test(m['assessment_date'] as string))
-    errors.push({ code: 'CMAP-007', message: `capability_map.assessment_date must be YYYY-MM-DD, got "${m['assessment_date']}"` });
+    errors.push(schemaFinding('capability-map inline', 'capability_map.assessment_date', 'YYYY-MM-DD string', m['assessment_date']));
 
   const caps = m['capabilities'];
   if (!Array.isArray(caps)) {
@@ -60,7 +56,7 @@ export function validateCapabilityMap(input: unknown): ValidationResult {
   }
 
   const seenIds = new Set<string>();
-  validateCapabilityTree(caps, 'capabilities', errors, seenIds);
+  validateCapabilityTree(caps, 'capabilities', errors, seenIds, warnings, options.resolvedAttributes);
 
   return { valid: errors.length === 0, errors, warnings };
 }
@@ -70,57 +66,65 @@ function validateCapabilityTree(
   pathPrefix: string,
   errors: ValidationError[],
   seenIds: Set<string>,
+  warnings: ValidationWarning[],
+  resolved?: ReadonlyMap<string, ResolvedCapabilityAttributes>,
 ): void {
   for (let i = 0; i < nodes.length; i++) {
     const rawNode = nodes[i];
     const nodePath = `${pathPrefix}[${i}]`;
 
-    if (!rawNode || typeof rawNode !== 'object') {
-      errors.push({ code: 'CMAP-003', message: `${nodePath} must be an object` });
+    if (!rawNode || typeof rawNode !== 'object' || Array.isArray(rawNode)) {
+      errors.push(schemaFinding('capability-map inline', `${nodePath}`, 'mapping', rawNode));
       continue;
     }
     const node = rawNode as Record<string, unknown>;
 
     if (!node['id'] || typeof node['id'] !== 'string' || !(node['id'] as string).trim()) {
-      errors.push({ code: 'CMAP-003', message: `${nodePath}: id is required` });
+      errors.push(schemaFinding('capability-map inline', `${nodePath}.id`, 'nonempty string', node['id']));
     } else {
       const id = node['id'] as string;
       if (seenIds.has(id)) {
-        errors.push({ code: 'CMAP-008', message: `Duplicate capability id: "${id}"` });
+        errors.push(schemaFinding('capability-map inline', `${nodePath}.id`, 'unique identifier', node['id']));
       }
       seenIds.add(id);
       if (!CAP_ID_RE.test(id)) {
-        errors.push({ code: 'CMAP-009', message: `${nodePath}: id "${id}" must match the canonical pattern CAPABILITY-V[n] or CAPABILITY-H[n] with optional .n segments (e.g. CAPABILITY-V1, CAPABILITY-V1.2, CAPABILITY-H1.3); the bare V[n] / H[n] form is also accepted for legacy compatibility` });
+        errors.push(schemaFinding('capability-map inline', `${nodePath}.id`, 'CAPABILITY-V[n] / CAPABILITY-H[n] (legacy V[n] / H[n]) with optional .n segments', node['id']));
       }
     }
 
     if (!node['name'] || typeof node['name'] !== 'string' || !(node['name'] as string).trim())
-      errors.push({ code: 'CMAP-003', message: `${nodePath}: name is required` });
+      errors.push(schemaFinding('capability-map inline', `${nodePath}.name`, 'nonempty string', node['name']));
 
-    if (node['current_maturity'] === undefined) {
-      errors.push({ code: 'CMAP-003', message: `${nodePath}: current_maturity is required` });
+    for (const field of ['current_maturity', 'target_maturity', 'target_date', 'owner_role']) {
+      if (node[field] !== undefined) errors.push({code: 'VERSIONED-004', path: `${nodePath}.${field}`,
+        message: `${nodePath}.${field} belongs in ${String(node['id'])}.history.yaml, not inline.`});
+    }
+    const currentMaturity = node['current_maturity'] ?? resolved?.get(String(node['id']))?.current_maturity;
+    if (currentMaturity === undefined && resolved === undefined) {
+      warnings.push({code: 'NOTATION-SKIP-001', path: `${nodePath}.current_maturity`,
+        message: `${nodePath}.current_maturity cannot be checked without the capability sidecar catalogue; this file remains unvalidated.`});
     } else {
-      const cm = node['current_maturity'];
+      const cm = currentMaturity;
       if (typeof cm !== 'number' || !Number.isInteger(cm) || cm < 1 || cm > 5)
-        errors.push({ code: 'CMAP-005', message: `${nodePath}: current_maturity must be an integer 1–5, got "${cm}"` });
+        errors.push(schemaFinding('capability-map inline', `${nodePath}.current_maturity`, 'integer in 1–5 from the sidecar at the assessment date', currentMaturity));
     }
 
     if (node['target_maturity'] !== undefined) {
       const tm = node['target_maturity'];
       if (typeof tm !== 'number' || !Number.isInteger(tm) || tm < 1 || tm > 5)
-        errors.push({ code: 'CMAP-006', message: `${nodePath}: target_maturity must be an integer 1–5, got "${tm}"` });
+        errors.push(schemaFinding('capability-map inline', `${nodePath}.target_maturity`, 'integer in 1–5', node['target_maturity']));
     }
 
     if (node['type'] !== undefined && !VALID_TYPES.has(node['type'] as CapabilityType))
-      errors.push({ code: 'CMAP-004', message: `${nodePath}: type "${node['type']}" must be one of: domain, supporting` });
+      errors.push(schemaFinding('capability-map inline', `${nodePath}.type`, `one of ${[...VALID_TYPES].join(", ")}`, node['type']));
 
     if (node['target_date'] !== undefined) {
       if (typeof node['target_date'] !== 'string' || !DATE_RE.test(node['target_date'] as string))
-        errors.push({ code: 'CMAP-007', message: `${nodePath}: target_date must be YYYY-MM-DD, got "${node['target_date']}"` });
+        errors.push(schemaFinding('capability-map inline', `${nodePath}.target_date`, 'YYYY-MM-DD string', node['target_date']));
     }
 
     if (node['applications'] !== undefined && !Array.isArray(node['applications']))
-      errors.push({ code: 'CMAP-003', message: `${nodePath}: applications must be an array` });
+      errors.push(schemaFinding('capability-map inline', `${nodePath}.applications`, 'array', node['applications']));
 
     // LIFECYCLE-001/004 — DSM's own rule codes (capabilities.go
     // ValidateCapMap/validateCapMapNodes) for `valid_from`/`valid_to`, the
@@ -157,9 +161,9 @@ function validateCapabilityTree(
 
     if (node['children'] !== undefined) {
       if (!Array.isArray(node['children'])) {
-        errors.push({ code: 'CMAP-003', message: `${nodePath}: children must be an array` });
+        errors.push(schemaFinding('capability-map inline', `${nodePath}.children`, 'array', node['children']));
       } else {
-        validateCapabilityTree(node['children'] as unknown[], `${nodePath}.children`, errors, seenIds);
+        validateCapabilityTree(node['children'] as unknown[], `${nodePath}.children`, errors, seenIds, warnings, resolved);
       }
     }
   }

package/src/codex/validate.ts

@@ -2,7 +2,7 @@
 //
 // 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-002 — external artefact frontmatter (jurisdiction, effective_date).
 // CODEX-004 — internal artefact frontmatter (issuing_authority, effective_date for
 //             POLICY/INTERNAL_STANDARD; statement, rationale for PRINCIPLE — §4.1).
 // CODEX-005 — jurisdiction must match the parent folder under codex/external/
@@ -92,7 +92,7 @@ export function validateCodex(input: unknown, options: CodexValidateOptions = {}
   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' });
+      errors.push({ code: 'CODEX-002', message: 'jurisdiction is required for external codex artefacts.', path: 'jurisdiction' });
     } else if (options.folderJurisdiction && jurisdiction.toLowerCase() !== options.folderJurisdiction.toLowerCase()) {
       errors.push({
         code: 'CODEX-005',
@@ -101,7 +101,7 @@ export function validateCodex(input: unknown, options: CodexValidateOptions = {}
       });
     }
     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' });
+      errors.push({ code: 'CODEX-002', message: 'effective_date is required for external codex artefacts.', path: 'effective_date' });
     }
   }
 

package/src/compliance/coverage-metric.ts

@@ -117,13 +117,13 @@ export function collectCoverageViewResolutionFindings(
     const t = catalog.typeOf(id);
     if (t === undefined) {
       findings.push({
-        code: 'COVMET-REF',
+        code: 'COVMET-003',
         severity: 'error',
         message: `subjects.products: "${id}" does not resolve to an admitted artefact.`,
       });
     } else if (t !== 'PRODUCT') {
       findings.push({
-        code: 'COVMET-REF',
+        code: 'COVMET-003',
         severity: 'error',
         message: `subjects.products: "${id}" resolves to ${t}, not PRODUCT.`,
       });
@@ -133,7 +133,7 @@ export function collectCoverageViewResolutionFindings(
   for (const id of config.regimes?.include ?? []) {
     if (!codexIds.has(id)) {
       findings.push({
-        code: 'COVMET-REF',
+        code: 'COVMET-003',
         severity: 'error',
         message: `regimes.include: "${id}" does not resolve to an admitted codex artefact.`,
       });

package/src/compliance/impact.ts

@@ -111,13 +111,13 @@ export function collectImpactViewResolutionFindings(
       const t = catalog.typeOf(id);
       if (t === undefined) {
         findings.push({
-          code: 'COMPIMP-REF',
+          code: 'COMPIMP-003',
           severity: 'error',
           message: `${path}: "${id}" does not resolve to an admitted artefact.`,
         });
       } else if (t !== expectedType) {
         findings.push({
-          code: 'COMPIMP-REF',
+          code: 'COMPIMP-003',
           severity: 'error',
           message: `${path}: "${id}" resolves to ${t}, not ${expectedType}.`,
         });
@@ -129,7 +129,7 @@ export function collectImpactViewResolutionFindings(
     const t = catalog.typeOf(id);
     if (t === undefined || t !== 'REQUIREMENT') {
       findings.push({
-        code: 'COMPIMP-REF',
+        code: 'COMPIMP-003',
         severity: 'error',
         message: `obligations.include: "${id}" does not resolve to an admitted REQUIREMENT.`,
       });
@@ -139,7 +139,7 @@ export function collectImpactViewResolutionFindings(
   for (const id of config.obligations.filter?.derived_from_codex ?? []) {
     if (!codexIds.has(id)) {
       findings.push({
-        code: 'COMPIMP-REF',
+        code: 'COMPIMP-003',
         severity: 'error',
         message: `obligations.filter.derived_from_codex: "${id}" does not resolve to an admitted codex artefact.`,
       });

package/src/fgca/parse-canonical.ts

@@ -1,3 +1,4 @@
+import { RESOLVED_DGCA } from './projection-origin.js';
 /**
  * Canonical-form FGCA parser + validator.
  *
@@ -167,6 +168,15 @@ export function parseCanonicalFGCA(
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 
+  if (!(input as { [RESOLVED_DGCA]?: boolean })[RESOLVED_DGCA]) {
+    for (const [field, values] of [['factors', factorsRaw], ['goals', goalsRaw], ['actions', activitiesRaw], ['changes', changesRaw]] as const) {
+      if (field === 'changes' && isDgcaChangesLayerOff(raw)) continue;
+      if (values?.length === 0) errors.push({ code: 'DGCA-004', path: field,
+        message: `Inline DGCA ${field} must be nonempty.` });
+    }
+    if (errors.length > 0) return { valid: false, errors, warnings };
+  }
+
   // From here we know all four arrays exist.
   const factors = factorsRaw!;
   const goals = goalsRaw!;
@@ -435,7 +445,10 @@ export function parseCanonicalFGA(
   // changes. Per-layer / per-ref checks all reuse the FGCA implementation;
   // codes are remapped on the way out. FGCA-009 / 010 / 014 (changes-related)
   // are unreachable here because `changes` is empty.
-  const synth = { ...raw, notation: 'dgca', id: 'DGCA-FROM-DGA-1', changes: [] };
+  const vc = raw.view_config && typeof raw.view_config === 'object' ? raw.view_config as Record<string, unknown> : {};
+  const layers = vc.layers && typeof vc.layers === 'object' ? vc.layers as Record<string, unknown> : {};
+  const synth = { ...raw, notation: 'dgca', id: 'DGCA-FROM-DGA-1', changes: [],
+    view_config: { ...vc, layers: { ...layers, changes: 'off' } } };
   const r = parseCanonicalFGCA(synth, outOfScopeGoalIds, outOfScopeFactorIds, progressData);
   const remap: Record<string, string> = {
     'FGCA-001': 'FGA-001',

package/src/fgca/projection-origin.ts

@@ -0,0 +1,2 @@
+/** Marks an in-memory projection result without admitting a YAML override. */
+export const RESOLVED_DGCA = Symbol.for('@transitrix/diagrams/resolved-dgca');

package/src/fgca/resolver.ts

@@ -1,3 +1,4 @@
+import { RESOLVED_DGCA } from './projection-origin.js';
 /**
  * FGCA canon resolver — assembles a flat canonical FGCA document from a
  * view_config projection and a canon element/relation store (VP-3).
@@ -182,6 +183,7 @@ export function resolveFGCA(
   }
 
   return {
+    [RESOLVED_DGCA]: true,
     notation: 'dgca',
     id: viewDoc['id'],
     name: viewDoc['name'],

package/src/products/validate.ts

@@ -1,3 +1,4 @@
+import { schemaFinding } from '../schema-finding.js';
 import type { ProductsCatalogueFile, ProductType, ProductStatus } from './types.js';
 import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
 
@@ -11,8 +12,8 @@ export function validateProductsCatalogue(input: unknown): ValidationResult {
   const errors: ValidationError[] = [];
   const warnings: ValidationWarning[] = [];
 
-  if (!input || typeof input !== 'object') {
-    return { valid: false, errors: [{ code: 'PROD-001', message: 'Input must be an object' }], warnings };
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return { valid: false, errors: [schemaFinding('products inline', '$', 'mapping', input)], warnings };
   }
 
   const raw = input as Record<string, unknown>;
@@ -26,84 +27,89 @@ export function validateProductsCatalogue(input: unknown): ValidationResult {
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 
+  if (('view_config' in raw || 'view' in raw) && !('products_catalogue' in raw)) {
+    return { valid: true, errors, warnings: [{ code: 'NOTATION-SKIP-001',
+      message: 'products projection form is unsupported and remains unvalidated.' }] };
+  }
+
   // PROD-002: catalogue header fields
   const cat = (raw['products_catalogue'] ?? {}) as Record<string, unknown>;
-  if (!raw['products_catalogue'] || typeof raw['products_catalogue'] !== 'object') {
-    errors.push({ code: 'PROD-002', message: 'Missing required field: products_catalogue' });
+  if (!raw['products_catalogue'] || typeof raw['products_catalogue'] !== 'object' || Array.isArray(raw['products_catalogue'])) {
+    errors.push(schemaFinding('products inline', 'products_catalogue', 'mapping', raw['products_catalogue']));
     return { valid: false, errors, warnings };
   }
   if (!cat['id'] || typeof cat['id'] !== 'string' || !(cat['id'] as string).trim()) {
-    errors.push({ code: 'PROD-002', message: 'products_catalogue.id is required' });
+    errors.push(schemaFinding('products inline', 'products_catalogue.id', 'nonempty string', cat['id']));
   }
   if (!cat['name'] || typeof cat['name'] !== 'string' || !(cat['name'] as string).trim()) {
-    errors.push({ code: 'PROD-002', message: 'products_catalogue.name is required' });
+    errors.push(schemaFinding('products inline', 'products_catalogue.name', 'nonempty string', cat['name']));
   }
   if (!cat['updated_at'] || typeof cat['updated_at'] !== 'string') {
-    errors.push({ code: 'PROD-002', message: 'products_catalogue.updated_at is required' });
+    errors.push(schemaFinding('products inline', 'products_catalogue.updated_at', 'YYYY-MM-DD string', cat['updated_at']));
   }
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 
-  // PROD-007: updated_at format
+  // Schema: updated_at format
   if (!DATE_RE.test(cat['updated_at'] as string)) {
-    errors.push({ code: 'PROD-007', message: `products_catalogue.updated_at must be YYYY-MM-DD, got "${cat['updated_at']}"` });
+    errors.push(schemaFinding('products inline', 'products_catalogue.updated_at', 'YYYY-MM-DD string', cat['updated_at']));
   }
 
   const products = cat['products'];
   if (!Array.isArray(products)) {
-    errors.push({ code: 'PROD-002', message: 'products_catalogue.products must be an array' });
+    errors.push(schemaFinding('products inline', 'products_catalogue.products', 'array', cat['products']));
     return { valid: false, errors, warnings };
   }
 
-  // PROD-008: unique product_id
+  // Schema: unique product_id
   const seenIds = new Set<string>();
 
   for (let i = 0; i < products.length; i++) {
     const rawProduct = products[i];
     const idx = `products[${i}]`;
 
-    if (!rawProduct || typeof rawProduct !== 'object') {
-      errors.push({ code: 'PROD-003', message: `${idx} must be an object` });
+    if (!rawProduct || typeof rawProduct !== 'object' || Array.isArray(rawProduct)) {
+      errors.push(schemaFinding('products inline', `${idx}`, 'mapping', rawProduct));
       continue;
     }
     const p = rawProduct as Record<string, unknown>;
 
-    // PROD-003: required per-product fields
+    // Schema: required per-product fields
     if (!p['product_id'] || typeof p['product_id'] !== 'string' || !(p['product_id'] as string).trim()) {
-      errors.push({ code: 'PROD-003', message: `${idx}: product_id is required` });
+      errors.push(schemaFinding('products inline', `${idx}.product_id`, 'nonempty string', p['product_id']));
     } else {
       const pid = p['product_id'] as string;
       if (seenIds.has(pid)) {
-        errors.push({ code: 'PROD-008', message: `Duplicate product_id: "${pid}"` });
+        errors.push(schemaFinding('products inline', `${idx}.product_id`, 'unique identifier', p['product_id']));
       }
       seenIds.add(pid);
     }
 
     if (!p['name'] || typeof p['name'] !== 'string' || !(p['name'] as string).trim()) {
-      errors.push({ code: 'PROD-003', message: `${idx}: name is required` });
+      errors.push(schemaFinding('products inline', `${idx}.name`, 'nonempty string', p['name']));
     }
     if (!p['type']) {
-      errors.push({ code: 'PROD-003', message: `${idx}: type is required` });
+      errors.push(schemaFinding('products inline', `${idx}.type`, `one of ${[...VALID_TYPES].join(", ")}`, p['type']));
     }
     if (!p['status']) {
-      errors.push({ code: 'PROD-003', message: `${idx}: status is required` });
+      errors.push(schemaFinding('products inline', `${idx}.status`, `one of ${[...VALID_STATUSES].join(", ")}`, p['status']));
     }
 
-    // PROD-004: type enum
+    // Schema: type enum
     if (p['type'] && !VALID_TYPES.has(p['type'] as ProductType)) {
-      errors.push({ code: 'PROD-004', message: `${idx}: type "${p['type']}" must be one of: digital_product, service, platform, bundle` });
+      errors.push(schemaFinding('products inline', `${idx}.type`, `one of ${[...VALID_TYPES].join(", ")}`, p['type']));
     }
 
-    // PROD-005: status enum
+    // Schema: status enum
     if (p['status'] && !VALID_STATUSES.has(p['status'] as ProductStatus)) {
-      errors.push({ code: 'PROD-005', message: `${idx}: status "${p['status']}" must be one of: Draft, Active, Deprecated` });
+      errors.push(schemaFinding('products inline', `${idx}.status`, `one of ${[...VALID_STATUSES].join(", ")}`, p['status']));
     }
 
-    // PROD-006: maturity range
+    // Schema: maturity range
     if (p['maturity'] !== undefined) {
       const m = p['maturity'];
       if (typeof m !== 'number' || !Number.isInteger(m) || m < 1 || m > 5) {
-        errors.push({ code: 'PROD-006', message: `${idx}: maturity must be an integer 1–5, got "${m}"` });
+        errors.push(schemaFinding('products inline', `${idx}.maturity`, 'integer in 1–5', p['maturity']));
       }
     }
   }