@transitrix/diagrams 1.14.0-rc.0 → 1.14.0

package/dist/scenarios/validate.js

@@ -24,6 +24,10 @@ export function validateScenario(input) {
     }
     if (errors.length > 0)
         return { valid: false, errors, warnings };
+    if (('view_config' in raw || 'view' in raw || 'scenarios' in raw) && !('scenario' in raw)) {
+        return { valid: true, errors, warnings: [{ code: 'NOTATION-SKIP-001',
+                    message: 'scenarios projection or scenario-set form is unsupported and remains unvalidated.' }] };
+    }
     const scn = raw['scenario'];
     if (!scn || typeof scn !== 'object') {
         errors.push({ code: 'SCN-002', message: 'Missing required field: scenario' });

package/dist/schema-finding.d.ts

@@ -0,0 +1,3 @@
+import type { ValidationError } from './validation-types.js';
+/** Shared schema identity; callers supply the owning form and exact field. */
+export declare function schemaFinding(form: string, path: string, expected: string, actual: unknown): ValidationError;

package/dist/schema-finding.js

@@ -0,0 +1,6 @@
+/** Shared schema identity; callers supply the owning form and exact field. */
+export function schemaFinding(form, path, expected, actual) {
+    const type = actual === null ? 'null' : Array.isArray(actual) ? 'array' : typeof actual;
+    return { code: 'SCHEMA_INVALID', path,
+        message: `${form} field '${path}': expected ${expected}; actual ${type} (${String(actual)}).` };
+}

package/dist/webview/entry.js

@@ -185,8 +185,13 @@ function dispatchValidate(kind, doc) {
             return renderFromValidation('process-map', validateProcessMap(doc), () => renderProcessMapHtml(doc.process_map));
         case 'scenarios':
             return renderFromValidation('scenarios', validateScenario(doc), () => renderScenarioHtml(doc.scenario));
-        case 'capability-map':
-            return renderFromValidation('capability-map', validateCapabilityMap(doc), () => renderCapabilityMapHtml(doc.capability_map));
+        case 'capability-map': {
+            const validation = validateCapabilityMap(doc);
+            const unresolved = validation.warnings.find(w => w.code === 'NOTATION-SKIP-001');
+            if (validation.valid && unresolved)
+                return errorResult('capability-map', unresolved.code, unresolved.message);
+            return renderFromValidation('capability-map', validation, () => renderCapabilityMapHtml(doc.capability_map));
+        }
         default:
             return errorResult(kind, 'NOTATION-NOT-WIRED', `Notation '${kind}' is not wired into the IntelliJ bundle yet.`);
     }

package/dist/webview/render-goals.js

@@ -41,7 +41,8 @@ export function renderGoalsSvg(tree, options = {}) {
     const title = treeName
         ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(`Goal tree — ${treeName}`)}</text>`
         : '';
-    return renderGoalsLayoutSvg(layout, { curvature, entryCurvature, edgeStyle, title, embedCssTheme: 'transitrix' });
+    // Reserve a separate header row; the theme centers text on its y coordinate.
+    return renderGoalsLayoutSvg(layout, { curvature, entryCurvature, edgeStyle, title, topInset: title ? PAD : 0, embedCssTheme: 'transitrix' });
 }
 /**
  * The single goals SVG emitter shared by every host. Takes an already-computed

package/package.json

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

package/src/activities/action-fields.ts

@@ -0,0 +1,31 @@
+/** ACTION field types and the manifest-selected 7.0.0 numeric boundary. */
+export function validateActionFields(
+  action: Record<string, unknown>, methodologyVersion?: string,
+): Array<{ code: string; message: string; path: string }> {
+  const errors: Array<{ code: string; message: string; path: string }> = [];
+  const version = /^(\d+)\.(\d+)\.(\d+)(-[^+]+)?(?:\+.*)?$/.exec(methodologyVersion ?? '');
+  const nonnegative = version !== null && (Number(version[1]) > 7 ||
+    (Number(version[1]) === 7 && (Number(version[2]) > 0 || Number(version[3]) > 0 || !version[4])));
+  const type = (value: unknown): string => value === null ? 'null' : Array.isArray(value) ? 'array' : typeof value;
+  const schema = (path: string, expected: string, value: unknown) => errors.push({
+    code: 'SCHEMA_INVALID', path,
+    message: `ACTION field '${path}' expected ${expected}, actual ${type(value)} (${String(value)}).`,
+  });
+  for (const field of ['duration', 'duration_days', 'labor_cost', 'resources_cost', 'effort', 'score', 'sort']) {
+    const value = action[field];
+    if (value === undefined || (value === null && (field === 'duration' || field === 'duration_days'))) continue;
+    const integer = field === 'score' || field === 'sort';
+    if (typeof value !== 'number' || !Number.isFinite(value) || (integer && !Number.isInteger(value))) {
+      schema(field, integer ? 'finite integer' : 'finite number', value);
+    } else if (nonnegative && field !== 'sort' && value < 0) {
+      errors.push({ code: 'ACTION-011', path: field, message: `ACTION field '${field}' is negative (${value}).` });
+    }
+  }
+  if (action.predecessors !== undefined) {
+    if (!Array.isArray(action.predecessors)) schema('predecessors', 'array of strings', action.predecessors);
+    else action.predecessors.forEach((value, index) => {
+      if (typeof value !== 'string') schema(`predecessors[${index}]`, 'string', value);
+    });
+  }
+  return errors;
+}

package/src/activities/validate.ts

@@ -1,3 +1,4 @@
+import { validateActionFields } from './action-fields.js';
 import type {
   ActivityDoc,
   Activity,
@@ -8,6 +9,11 @@ import type {
 import { isObject, str, reachesRootViaParent } from '../canon-resolver-utils.js';
 import { ACT_021_OMITTED_KEY } from './resolver.js';
 
+function validDate(value: string): boolean {
+  const date = new Date(value);
+  return DATE_RE.test(value) && Number.isFinite(date.getTime()) && date.toISOString().slice(0, 10) === value;
+}
+
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 const VALID_WEEKDAYS = new Set(['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']);
 
@@ -61,7 +67,7 @@ function collectAct021FromAuthored(
   return out;
 }
 
-export function validateActivities(input: unknown): ActivityValidationResult {
+export function validateActivities(input: unknown, options: { methodologyVersion?: string } = {}): ActivityValidationResult {
   const errors: ActivityValidationError[] = [];
   const warnings: ActivityValidationWarning[] = [];
 
@@ -104,7 +110,7 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     warnings.push(...collectAct021FromAuthored(raw, rawArray));
   }
 
-  // ACT-014 / ACT-015: project.calendar validation (run before per-activity loop;
+  // ACT-007 / ACT-008: project.calendar validation (run before per-activity loop;
   // surfaces clearly even when activities also have issues).
   if (raw.project && typeof raw.project === 'object') {
     const project = raw.project as Record<string, unknown>;
@@ -113,7 +119,7 @@ export function validateActivities(input: unknown): ActivityValidationResult {
       const calendar = cal as Record<string, unknown>;
       if (calendar.working_days !== undefined) {
         if (!Array.isArray(calendar.working_days)) {
-          errors.push({ code: 'ACT-014', message: 'project.calendar.working_days must be an array of weekday names', path: 'project.calendar.working_days' });
+          errors.push({ code: 'ACT-007', message: 'project.calendar.working_days must be an array of weekday names', path: 'project.calendar.working_days' });
         } else {
           const seen = new Set<string>();
           for (let i = 0; i < calendar.working_days.length; i++) {
@@ -121,13 +127,13 @@ export function validateActivities(input: unknown): ActivityValidationResult {
             const day = typeof raw === 'string' ? raw.toLowerCase() : '';
             if (!VALID_WEEKDAYS.has(day)) {
               errors.push({
-                code: 'ACT-014',
+                code: 'ACT-007',
                 message: `project.calendar.working_days[${i}] "${String(raw)}" must be one of: mon, tue, wed, thu, fri, sat, sun`,
                 path: `project.calendar.working_days[${i}]`,
               });
             } else if (seen.has(day)) {
               errors.push({
-                code: 'ACT-014',
+                code: 'ACT-007',
                 message: `project.calendar.working_days has duplicate entry "${day}"`,
                 path: `project.calendar.working_days[${i}]`,
               });
@@ -139,13 +145,13 @@ export function validateActivities(input: unknown): ActivityValidationResult {
       }
       if (calendar.holidays !== undefined) {
         if (!Array.isArray(calendar.holidays)) {
-          errors.push({ code: 'ACT-015', message: 'project.calendar.holidays must be an array of ISO 8601 dates', path: 'project.calendar.holidays' });
+          errors.push({ code: 'ACT-008', message: 'project.calendar.holidays must be an array of ISO 8601 dates', path: 'project.calendar.holidays' });
         } else {
           for (let i = 0; i < calendar.holidays.length; i++) {
             const h = calendar.holidays[i];
-            if (typeof h !== 'string' || !DATE_RE.test(h)) {
+            if (typeof h !== 'string' || !validDate(h)) {
               errors.push({
-                code: 'ACT-015',
+                code: 'ACT-008',
                 message: `project.calendar.holidays[${i}] "${String(h)}" must be an ISO 8601 date (YYYY-MM-DD)`,
                 path: `project.calendar.holidays[${i}]`,
               });
@@ -204,15 +210,8 @@ export function validateActivities(input: unknown): ActivityValidationResult {
       idSet.add(id);
     }
 
-    // ACT-009: non-negative numeric fields
-    const numericFields = ['duration', 'duration_days', 'labor_cost', 'resources_cost', 'effort', 'score', 'sort'] as const;
-    for (const field of numericFields) {
-      const val = act[field];
-      if (val !== undefined && val !== null) {
-        if (typeof val !== 'number' || val < 0) {
-          errors.push({ code: 'ACT-009', message: `Activity "${id}" field "${field}" must be a non-negative number, got ${String(val)}`, path });
-        }
-      }
+    for (const error of validateActionFields(act, options.methodologyVersion)) {
+      errors.push({ ...error, message: `Inline action actions[${i}].${error.path}: ${error.message}`, path: `actions[${i}].${error.path}` });
     }
 
     // ACT-011: warn if no duration (duration_days is accepted as an alias)
@@ -229,19 +228,23 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     const a = doc.activities[i];
     const path = `activities[${i}]`;
 
-    // ACT-007: self-loop
+    // ACTION-009: self-loop
     if (Array.isArray(a.predecessors) && a.predecessors.includes(a.id)) {
-      errors.push({ code: 'ACT-007', message: `Activity "${a.id}" lists itself as a predecessor`, path });
+      errors.push({ code: 'ACTION-009', message: `Activity "${a.id}" lists itself as a predecessor`, path });
+    }
+
+    if (typeof a.parent === 'string' && !idSet.has(a.parent)) {
+      warnings.push({ code: 'ACTION-007', message: `Action "${a.id}" parent "${a.parent}" does not resolve`, path: `${path}.parent` });
     }
 
-    // ACT-005: predecessor existence (intra-document)
+    // ACTION-007: predecessor existence (intra-document)
     for (const predId of (a.predecessors ?? [])) {
       if (!idSet.has(predId)) {
-        errors.push({ code: 'ACT-005', message: `Activity "${a.id}" references unknown predecessor "${predId}"`, path });
+        warnings.push({ code: 'ACTION-007', message: `Activity "${a.id}" references unknown predecessor "${predId}"`, path });
       }
     }
 
-    // ACT-008: date format validation + end_date >= start_date.
+    // ACTION-010: date format validation + end_date >= start_date.
     // The orchestrator's pre-release review flagged that the raw lexicographic
     // string compare is only correct for strict YYYY-MM-DD, with no format
     // check applied. Now we validate the format first; the order compare runs
@@ -249,28 +252,28 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     // be misleading).
     let startValid = true;
     let endValid = true;
-    if (a.start_date !== undefined) {
-      if (typeof a.start_date !== 'string' || !DATE_RE.test(a.start_date)) {
-        errors.push({ code: 'ACT-008', message: `Activity "${a.id}" start_date "${String(a.start_date)}" must be ISO 8601 YYYY-MM-DD`, path });
+    if (a.start_date !== undefined && a.start_date !== null) {
+      if (typeof a.start_date !== 'string' || !validDate(a.start_date)) {
+        errors.push({ code: 'ACTION-010', message: `Activity "${a.id}" start_date "${String(a.start_date)}" must be ISO 8601 YYYY-MM-DD`, path });
         startValid = false;
       }
     }
-    if (a.end_date !== undefined) {
-      if (typeof a.end_date !== 'string' || !DATE_RE.test(a.end_date)) {
-        errors.push({ code: 'ACT-008', message: `Activity "${a.id}" end_date "${String(a.end_date)}" must be ISO 8601 YYYY-MM-DD`, path });
+    if (a.end_date !== undefined && a.end_date !== null) {
+      if (typeof a.end_date !== 'string' || !validDate(a.end_date)) {
+        errors.push({ code: 'ACTION-010', message: `Activity "${a.id}" end_date "${String(a.end_date)}" must be ISO 8601 YYYY-MM-DD`, path });
         endValid = false;
       }
     }
     if (a.start_date && a.end_date && startValid && endValid) {
       if (a.end_date < a.start_date) {
-        errors.push({ code: 'ACT-008', message: `Activity "${a.id}" end_date "${a.end_date}" is before start_date "${a.start_date}"`, path });
+        errors.push({ code: 'ACTION-010', message: `Activity "${a.id}" end_date "${a.end_date}" is before start_date "${a.start_date}"`, path });
       }
     }
   }
 
   if (errors.length > 0) return { valid: false, errors, warnings };
 
-  // ACT-006: no cycles
+  // ACTION-008: no cycles
   const cycleError = detectCycle(doc.activities);
   if (cycleError) errors.push(cycleError);
 
@@ -375,7 +378,7 @@ export function validateActivities(input: unknown): ActivityValidationResult {
     }
   }
 
-  // ACT-019: Gantt view will not render when neither project.start_date nor
+  // ACT-009: Gantt view will not render when neither project.start_date nor
   // any per-activity pinned date pair is present. Network view is unaffected.
   const hasProjectStart = typeof doc.project?.start_date === 'string' && doc.project.start_date.length > 0;
   const hasPinnedActivity = doc.activities.some(
@@ -383,7 +386,7 @@ export function validateActivities(input: unknown): ActivityValidationResult {
   );
   if (!hasProjectStart && !hasPinnedActivity) {
     warnings.push({
-      code: 'ACT-019',
+      code: 'ACT-009',
       message: 'Gantt view will not render: project.start_date is absent and no activity has both start_date and end_date pinned. Network view is unaffected.',
     });
   }
@@ -408,7 +411,7 @@ function detectCycle(activities: Activity[]): ActivityValidationError | null {
   for (const a of activities) inDegree.set(a.id, 0);
   for (const a of activities) {
     for (const pred of (a.predecessors ?? [])) {
-      inDegree.set(a.id, (inDegree.get(a.id) ?? 0) + 1);
+      if (successors.has(pred)) inDegree.set(a.id, (inDegree.get(a.id) ?? 0) + 1);
     }
   }
 
@@ -430,7 +433,7 @@ function detectCycle(activities: Activity[]): ActivityValidationError | null {
 
   if (processed < activities.length) {
     const cycleNodes = activities.filter(a => (inDegree.get(a.id) ?? 0) > 0).map(a => a.id);
-    return { code: 'ACT-006', message: `Cycle detected in activity dependency graph involving: ${cycleNodes.join(', ')}` };
+    return { code: 'ACTION-008', message: `Cycle detected in activity dependency graph involving: ${cycleNodes.join(', ')}` };
   }
   return null;
 }

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