@transitrix/diagrams 1.14.0-rc.0 → 1.15.0

package/src/repo-validate/check-strategy-chain.ts

@@ -1,3 +1,4 @@
+import { validateActionFields } from '../activities/action-fields.js';
 // Strategy-chain semantic checks — the error-severity subset of DSM's Go
 // `Validate*` functions (`api02/internal/importer/{goals,activities,fgca}.go`
 // in transitrix-dsm), ported onto the standalone-element repo shape
@@ -5,9 +6,8 @@
 // can drop those Go functions without regressing the checks they enforce
 // today.
 //
-// Rule codes are DSM's own (`GOALS-010`, `ACT-006`..`009`, `FGCA-008`..`011`)
-// — not invented here — so DSM can map a CLI finding straight back onto its
-// import-log taxonomy (`RepoFinding.ruleId`).
+// ACTION identities follow the versioned element contract; schedule ACT codes
+// remain separate. Stored historical findings must retain their original codes.
 //
 // Scope — DSM's full rule set is now ported except GOALS-008 (see below).
 // `RepoFinding` grew a `severity` field precisely so DSM's warn-severity
@@ -43,20 +43,20 @@
 //
 // Ported (error-severity, blocking):
 //   GOALS-010 — GOAL `parent` chain contains a cycle.
-//   ACT-006   — ACTION `predecessors` graph contains a cycle.
-//   ACT-007   — ACTION lists itself as its own predecessor.
-//   ACT-008   — ACTION `start_date`/`end_date` unparseable, or end before start.
-//   ACT-009   — ACTION numeric field (`duration`/`duration_days`, `labor_cost`,
+//   ACTION-008   — ACTION `predecessors` graph contains a cycle.
+//   ACTION-009   — ACTION lists itself as its own predecessor.
+//   ACTION-010   — ACTION `start_date`/`end_date` unparseable, or end before start.
+//   ACTION-011   — ACTION numeric field (`duration`/`duration_days`, `labor_cost`,
 //               `resources_cost`, `effort`, `score`) is negative.
-//   FGCA-008  — GOAL.factors references an undefined DRIVER.
-//   FGCA-009  — CHANGE.goals references an undefined GOAL.
-//   FGCA-010  — ACTION.delivers_changes references an undefined CHANGE.
-//   FGCA-011  — ACTION.goals references an undefined GOAL.
+//   DGCA-REPO-008  — GOAL.factors references an undefined DRIVER.
+//   DGCA-REPO-009  — CHANGE.goals references an undefined GOAL.
+//   DGCA-REPO-010  — ACTION.delivers_changes references an undefined CHANGE.
+//   DGCA-REPO-011  — ACTION.goals references an undefined GOAL.
 //
 // Ported (warning-severity, advisory):
 //   GOALS-009 — GOAL.parent is set but does not resolve to a known GOAL (orphan).
 //   GOALS-011 — GOAL has no `parent` and `level` >= 1 (backlog).
-//   ACT-005   — ACTION.predecessors entry or ACTION.parent does not resolve
+//   ACTION-007   — ACTION.predecessors entry or ACTION.parent does not resolve
 //               to a known ACTION (orphan).
 //   FGCA-012  — a DRIVER is not referenced by any GOAL.factors (unreferenced).
 //   FGCA-013  — a GOAL is not referenced by any CHANGE.goals or ACTION.goals
@@ -244,34 +244,34 @@ function checkGoalParentResolution(goals: ChainElement[], findings: RepoFinding[
   }
 }
 
-/** ACT-007 — an ACTION cannot list itself as its own predecessor. */
+/** ACTION-009 — an ACTION cannot list itself as its own predecessor. */
 function checkActionSelfPredecessor(actions: ChainElement[], findings: RepoFinding[]): void {
   for (const a of actions) {
     if (readStringArray(a.data, 'predecessors').includes(a.id)) {
       findings.push({
         scope: PScope,
         id: a.id,
-        ruleId: 'ACT-007',
-        message: `ACT-007: action '${a.id}' lists itself as a predecessor.`,
+        ruleId: 'ACTION-009',
+        message: `ACTION-009: action '${a.id}' lists itself as a predecessor.`,
       });
     }
   }
 }
 
-/** ACT-006 — the ACTION `predecessors` graph must not contain a cycle. */
+/** ACTION-008 — the ACTION `predecessors` graph must not contain a cycle. */
 function checkActionPredecessorCycle(actions: ChainElement[], findings: RepoFinding[]): void {
   const cyc = findPredecessorCycle(actions);
   if (cyc) {
     findings.push({
       scope: PScope,
       id: cyc,
-      ruleId: 'ACT-006',
-      message: `ACT-006: predecessor graph contains a cycle involving action '${cyc}'.`,
+      ruleId: 'ACTION-008',
+      message: `ACTION-008: predecessor graph contains a cycle involving action '${cyc}'.`,
     });
   }
 }
 
-/** ACT-005 — an ACTION `predecessors` entry or `parent` that does not resolve
+/** ACTION-007 — an ACTION `predecessors` entry or `parent` that does not resolve
  *  to a known ACTION is an orphan reference (warning — advisory in DSM, same
  *  as the goal-parent orphan checks above). */
 function checkActionOrphanReferences(actions: ChainElement[], findings: RepoFinding[]): void {
@@ -282,9 +282,9 @@ function checkActionOrphanReferences(actions: ChainElement[], findings: RepoFind
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'ACT-005',
+          ruleId: 'ACTION-007',
           severity: 'warning',
-          message: `ACT-005: action '${a.id}' predecessor '${p}' does not resolve to a known action.`,
+          message: `ACTION-007: action '${a.id}' predecessor '${p}' does not resolve to a known action.`,
         });
       }
     }
@@ -293,9 +293,9 @@ function checkActionOrphanReferences(actions: ChainElement[], findings: RepoFind
       findings.push({
         scope: PScope,
         id: a.id,
-        ruleId: 'ACT-005',
+        ruleId: 'ACTION-007',
         severity: 'warning',
-        message: `ACT-005: action '${a.id}' parent '${parent}' does not resolve to a known action.`,
+        message: `ACTION-007: action '${a.id}' parent '${parent}' does not resolve to a known action.`,
       });
     }
   }
@@ -316,34 +316,34 @@ function parseIsoDate(value: string): Date | undefined {
   return dt;
 }
 
-/** ACT-008 — `start_date`/`end_date` must be valid ISO dates, and `end_date`
+/** ACTION-010 — `start_date`/`end_date` must be valid ISO dates, and `end_date`
  *  must not be before `start_date` (equal is allowed — e.g. a milestone). */
 function checkActionDates(actions: ChainElement[], findings: RepoFinding[]): void {
   for (const a of actions) {
-    const startRaw = readString(a.data, 'start_date');
-    const endRaw = readString(a.data, 'end_date');
+    const startRaw = a.data.start_date == null ? undefined : a.data.start_date;
+    const endRaw = a.data.end_date == null ? undefined : a.data.end_date;
     let start: Date | undefined;
     let end: Date | undefined;
 
     if (startRaw !== undefined) {
-      start = parseIsoDate(startRaw);
+      start = typeof startRaw === 'string' ? parseIsoDate(startRaw) : undefined;
       if (!start) {
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'ACT-008',
-          message: `ACT-008: action '${a.id}' start_date '${startRaw}' is not a valid YYYY-MM-DD date.`,
+          ruleId: 'ACTION-010',
+          message: `ACTION-010: action '${a.id}' start_date '${startRaw}' is not a valid YYYY-MM-DD date.`,
         });
       }
     }
     if (endRaw !== undefined) {
-      end = parseIsoDate(endRaw);
+      end = typeof endRaw === 'string' ? parseIsoDate(endRaw) : undefined;
       if (!end) {
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'ACT-008',
-          message: `ACT-008: action '${a.id}' end_date '${endRaw}' is not a valid YYYY-MM-DD date.`,
+          ruleId: 'ACTION-010',
+          message: `ACTION-010: action '${a.id}' end_date '${endRaw}' is not a valid YYYY-MM-DD date.`,
         });
       }
     }
@@ -351,36 +351,24 @@ function checkActionDates(actions: ChainElement[], findings: RepoFinding[]): voi
       findings.push({
         scope: PScope,
         id: a.id,
-        ruleId: 'ACT-008',
-        message: `ACT-008: action '${a.id}' end_date '${endRaw}' is before start_date '${startRaw}'.`,
+        ruleId: 'ACTION-010',
+        message: `ACTION-010: action '${a.id}' end_date '${endRaw}' is before start_date '${startRaw}'.`,
       });
     }
   }
 }
 
-/** ACT-009 — numeric scheduling/cost fields must not be negative. `duration`
- *  and `duration_days` are both checked — the canonical field is `duration`
- *  (elements/24-action.md §2), but `duration_days` is an accepted alias in
- *  this codebase's document-form validator (activities/validate.ts) and is
- *  the field acme_corp's own ACTION elements actually use. */
-function checkActionNegativeNumbers(actions: ChainElement[], findings: RepoFinding[]): void {
-  const fields = ['duration', 'duration_days', 'labor_cost', 'resources_cost', 'effort', 'score'] as const;
+/** Shared ACTION type and versioned numeric checks. */
+function checkActionFields(actions: ChainElement[], findings: RepoFinding[], version?: string): void {
   for (const a of actions) {
-    for (const field of fields) {
-      const v = readFiniteNumber(a.data, field);
-      if (v !== undefined && v < 0) {
-        findings.push({
-          scope: PScope,
-          id: a.id,
-          ruleId: 'ACT-009',
-          message: `ACT-009: action '${a.id}' field '${field}' is negative (${v}).`,
-        });
-      }
+    for (const error of validateActionFields(a.data, version)) {
+      findings.push({ scope: PScope, id: a.id, ruleId: error.code,
+        message: `${a.doc.path}: canonical action '${a.id}' ${error.message}` });
     }
   }
 }
 
-/** FGCA-008..011 — inline strategy-chain cross-references must resolve within
+/** DGCA-REPO-008..011 — inline strategy-chain cross-references must resolve within
  *  the repo: GOAL.factors -> DRIVER, CHANGE.goals -> GOAL, ACTION.goals ->
  *  GOAL, ACTION.delivers_changes -> CHANGE (ELEMENT_PRIMITIVES.md §7.1-§7.4). */
 function checkStrategyChainReferences(
@@ -400,8 +388,8 @@ function checkStrategyChainReferences(
         findings.push({
           scope: PScope,
           id: g.id,
-          ruleId: 'FGCA-008',
-          message: `FGCA-008: goal '${g.id}' references undefined driver '${f}'.`,
+          ruleId: 'DGCA-REPO-008',
+          message: `DGCA-REPO-008: goal '${g.id}' references undefined driver '${f}'.`,
         });
       }
     }
@@ -412,8 +400,8 @@ function checkStrategyChainReferences(
         findings.push({
           scope: PScope,
           id: c.id,
-          ruleId: 'FGCA-009',
-          message: `FGCA-009: change '${c.id}' references undefined goal '${g}'.`,
+          ruleId: 'DGCA-REPO-009',
+          message: `DGCA-REPO-009: change '${c.id}' references undefined goal '${g}'.`,
         });
       }
     }
@@ -424,8 +412,8 @@ function checkStrategyChainReferences(
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'FGCA-010',
-          message: `FGCA-010: action '${a.id}' references undefined change '${c}'.`,
+          ruleId: 'DGCA-REPO-010',
+          message: `DGCA-REPO-010: action '${a.id}' references undefined change '${c}'.`,
         });
       }
     }
@@ -434,8 +422,8 @@ function checkStrategyChainReferences(
         findings.push({
           scope: PScope,
           id: a.id,
-          ruleId: 'FGCA-011',
-          message: `FGCA-011: action '${a.id}' references undefined goal '${g}'.`,
+          ruleId: 'DGCA-REPO-011',
+          message: `DGCA-REPO-011: action '${a.id}' references undefined goal '${g}'.`,
         });
       }
     }
@@ -505,8 +493,8 @@ function checkStrategyChainOrphans(
 }
 
 /**
- * Run the strategy-chain semantic checks (GOALS-009..011, ACT-005..009,
- * FGCA-008..014 except GOALS-008 — see the module header) over the loaded
+ * Run the strategy-chain semantic checks (GOALS-009..011, ACTION-007..011,
+ * DGCA-REPO-008..014 except GOALS-008 — see the module header) over the loaded
  * element set and append findings. Called from `validateRepoModel` after the
  * structural phases. Pure, deterministic order.
  */
@@ -522,7 +510,24 @@ export function checkStrategyChainSemantics(input: RepoModelInput, findings: Rep
   checkActionPredecessorCycle(actions, findings);
   checkActionOrphanReferences(actions, findings);
   checkActionDates(actions, findings);
-  checkActionNegativeNumbers(actions, findings);
+  checkActionFields(actions, findings, input.methodologyVersion);
   checkStrategyChainReferences(goals, actions, drivers, changes, findings);
-  checkStrategyChainOrphans(goals, actions, drivers, changes, findings);
+  if (!usesCoverageObservations(input)) checkStrategyChainOrphans(goals, actions, drivers, changes, findings);
+}
+
+
+function usesCoverageObservations(input: RepoModelInput): boolean {
+  return /^\d+\./.test(input.methodologyVersion ?? '') && Number(input.methodologyVersion!.split('.')[0]) >= 5;
+}
+
+/** Removed FGCA orphan rules become visible coverage observations, not new aliases. */
+export function collectStrategyCoverageObservations(input: RepoModelInput): Array<{id: string; kind: 'unreferenced'; message: string}> {
+  if (!usesCoverageObservations(input)) return [];
+  const findings: RepoFinding[] = [];
+  checkStrategyChainOrphans(
+    collectByNotation(input.elements, isGoalNotation),
+    collectByNotation(input.elements, isActionNotation),
+    collectByNotation(input.elements, isDriverNotation),
+    collectByNotation(input.elements, isChangeNotation), findings);
+  return findings.map(f => ({ id: f.id, kind: 'unreferenced', message: f.message.replace(/^FGCA-01[234]: /, '') }));
 }

package/src/repo-validate/types.ts

@@ -74,6 +74,8 @@ export interface RepoDoc {
  *  canon zone exactly as `lint.py` partitions them (`canon/elements/**` vs
  *  `canon/relations/**`). */
 export interface RepoModelInput {
+  /** Catalogue manifest version; document spec_version never selects compatibility. */
+  methodologyVersion?: string;
   /** Documents found under `canon/elements/**`. */
   elements: RepoDoc[];
   /** Documents found under `canon/relations/**`. */

package/src/repo-validate/validate-repo.ts

@@ -135,6 +135,7 @@ function checkReferentialIntegrity(input: RepoModelInput, findings: RepoFinding[
       findings.push({
         scope: PScope,
         id: relId,
+        ruleId: 'REL-002',
         message: `Referential integrity: relation '${relId || doc.path}' endpoint '${fromId}' (from) does not resolve to a known element.`,
       });
     }
@@ -142,6 +143,7 @@ function checkReferentialIntegrity(input: RepoModelInput, findings: RepoFinding[
       findings.push({
         scope: PScope,
         id: relId,
+        ruleId: 'REL-002',
         message: `Referential integrity: relation '${relId || doc.path}' endpoint '${toId}' (to) does not resolve to a known element.`,
       });
     }

package/src/risk/index.ts

@@ -1,4 +1,4 @@
-export type { Risk, RiskLevel } from './types.js';
+export type { Risk, RiskLevel, RiskScale } from './types.js';
 export { RISK_LEVELS } from './types.js';
 export { validateRisk } from './validate.js';
 export type { RiskValidateOptions } from './validate.js';

package/src/risk/types.ts

@@ -4,7 +4,14 @@
 import type { GateChecks } from '../requirement/types.js';
 
 /** Likelihood / impact / residual severity vocabulary (§7.26). */
-export type RiskLevel = 'low' | 'medium' | 'high';
+export type RiskLevel = 'low' | 'medium' | 'high' | number;
+
+export interface RiskScale {
+  id: string;
+  min: number;
+  max: number;
+  direction: 'higher' | 'lower';
+}
 
 export const RISK_LEVELS: readonly RiskLevel[] = ['low', 'medium', 'high'];
 
@@ -12,6 +19,7 @@ export interface Risk {
   notation: 'risk';
   id: string;
   name: string;
+  risk_scale?: RiskScale;
   likelihood: RiskLevel;
   impact: RiskLevel;
   residual: RiskLevel;

package/src/risk/validate.ts

@@ -3,7 +3,7 @@
 // Codes:
 //   RISK-001 — shape / id grammar / required envelope + per-type fields
 //              (likelihood, impact, residual, owner_role, threatens).
-//   RISK-002 — likelihood / impact / residual outside {low, medium, high}.
+//   RISK-002 — invalid qualitative/numeric degree or adopter scale.
 //   RISK-003 — threatens is empty, or an entry does not resolve to an
 //              admitted element in canon (no TYPE restriction — any core
 //              element may be threatened).
@@ -62,13 +62,27 @@ export function validateRisk(input: unknown, options: RiskValidateOptions = {}):
     errors.push({ code: 'RISK-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
   }
 
-  // likelihood / impact / residual — required (RISK-001) + enum (RISK-002).
-  for (const f of ['likelihood', 'impact', 'residual'] as const) {
+  // Authored numeric degrees use one explicitly declared adopter scale.
+  const fields = ['likelihood', 'impact', 'residual'] as const;
+  const scale = r.risk_scale as Record<string, unknown> | undefined;
+  const finite = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
+  const validScale = scale !== null && typeof scale === 'object' && !Array.isArray(scale)
+    && typeof scale.id === 'string' && scale.id.trim().length > 0
+    && finite(scale.min) && finite(scale.max) && scale.min < scale.max
+    && (scale.direction === 'higher' || scale.direction === 'lower');
+  if ((scale !== undefined || fields.some(f => typeof r[f] === 'number')) && !validScale) {
+    errors.push({ code: 'RISK-002', message: 'risk_scale requires id, finite min < max, and direction higher or lower.', path: 'risk_scale' });
+  }
+  for (const f of fields) {
     const v = r[f];
     if (v === undefined || v === null || v === '') {
       errors.push({ code: 'RISK-001', message: `${f} is required.`, path: f });
-    } else if (!(RISK_LEVELS as readonly string[]).includes(v as string)) {
-      errors.push({ code: 'RISK-002', message: `${f} "${String(v)}" must be one of ${RISK_LEVELS.join(', ')}.`, path: f });
+    } else if (typeof v === 'number') {
+      if (!finite(v) || (validScale && (v < (scale!.min as number) || v > (scale!.max as number)))) {
+        errors.push({ code: 'RISK-002', message: `${f} must be finite and within risk_scale bounds.`, path: f });
+      }
+    } else if (!(RISK_LEVELS as readonly unknown[]).includes(v)) {
+      errors.push({ code: 'RISK-002', message: `${f} must be low, medium, high, or a number with risk_scale.`, path: f });
     }
   }
 

package/src/scenarios/validate.ts

@@ -38,6 +38,11 @@ export function validateScenario(input: unknown): ValidationResult {
   }
   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/src/schema-finding.ts

@@ -0,0 +1,8 @@
+import type { ValidationError } from './validation-types.js';
+
+/** Shared schema identity; callers supply the owning form and exact field. */
+export function schemaFinding(form: string, path: string, expected: string, actual: unknown): ValidationError {
+  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/src/standalone/history.ts

@@ -0,0 +1,45 @@
+// Strict raw history validation. Never filter malformed entries before checking them.
+import type { ValidationResult } from '../validation-types.js';
+import { mapping, isoDate, type StandaloneOptions } from './validate.js';
+import { validateAttributeArray } from '../versioned-attribute/validate.js';
+import { isCanonicalIdOfType } from '../typed-id.js';
+
+export function validateHistory(input: unknown, options: StandaloneOptions = {}): ValidationResult {
+  const errors: ValidationResult['errors'] = [], warnings: ValidationResult['warnings'] = [];
+  const fail = (field: string, expected: string, actual: unknown, code = 'SCHEMA_INVALID') => errors.push({code, message: `history sidecar: ${field}: expected ${expected}; actual ${JSON.stringify(actual) ?? 'missing'}.`, path:field});
+  if (!mapping(input)) { fail('$', 'mapping', input); return {valid:false, errors, warnings}; }
+  const d = input;
+  if (typeof d.target !== 'string' || !d.target.trim()) fail('target', 'canonical target ID', d.target, 'VERSIONED-001');
+  const target = typeof d.target === 'string' ? options.documents?.get(d.target) : undefined;
+  if (options.documents && (!target || !options.catalog?.typeOf(d.target as string))) fail('target', 'admitted primitive', d.target, 'VERSIONED-001');
+  const notation = target?.notation;
+  const attributes: Record<string, string[]> = {capability: ['current_maturity','target_maturity','target_date','owner_role'], application: ['maturity','vendor','owner_role']};
+  const allowed = typeof notation === 'string' ? attributes[notation] : undefined;
+  if (!allowed) warnings.push({code:'NOTATION-SKIP-001', message: 'History target schema is unavailable; attribute coverage remains unvalidated.'});
+  if (!mapping(d.attribute_versions)) fail('attribute_versions', 'mapping', d.attribute_versions);
+  else for (const [attribute, entries] of Object.entries(d.attribute_versions)) {
+    const field = `attribute_versions.${attribute}`;
+    if (allowed && !allowed.includes(attribute)) fail(field, 'declared time_varying attribute', attribute);
+    if (!Array.isArray(entries)) { fail(field, 'array', entries); continue; }
+    const checked: {valid_from: string; value: string | number | boolean | null}[] = [];
+    for (const [i, entry] of entries.entries()) {
+      const key = `${field}[${i}]`;
+      if (!mapping(entry)) { fail(key, 'mapping', entry); continue; }
+      if (!isoDate(entry.valid_from)) fail(`${key}.valid_from`, 'ISO calendar date', entry.valid_from);
+      const value = entry.value;
+      const scalar = value === null || ['string','number','boolean'].includes(typeof value);
+      if (!('value' in entry) || !scalar) fail(`${key}.value`, 'scalar or null', value);
+      if (scalar && isoDate(entry.valid_from)) checked.push({valid_from: entry.valid_from, value: value as string | number | boolean | null});
+      if (value === null || !allowed?.includes(attribute)) continue;
+      if (['current_maturity','target_maturity','maturity'].includes(attribute) && !(Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 5)) fail(`${key}.value`, 'integer 1..5 or null', value);
+      if (attribute === 'target_date' && !isoDate(value)) fail(`${key}.value`, 'ISO calendar date or null', value);
+      if (attribute === 'vendor' && typeof value !== 'string') fail(`${key}.value`, 'string or null', value);
+      if (attribute === 'owner_role' && (!isCanonicalIdOfType(value, 'ROLE') || (options.catalog && options.catalog.typeOf(value as string) !== 'ROLE'))) fail(`${key}.value`, 'admitted ROLE reference or null', value);
+    }
+    for (const finding of validateAttributeArray(attribute, checked, typeof target?.valid_from === 'string' ? target.valid_from : undefined, target?.valid_to === null || typeof target?.valid_to === 'string' ? target.valid_to : undefined)) {
+      (finding.severity === 'error' ? errors : warnings).push({code:finding.code, message:finding.message});
+    }
+  }
+  for (const key of ['notation','id','zone','admitted_at','admitted_by','valid_from','valid_to']) if (key in d) fail(key, 'absent on headerless history sidecar', d[key]);
+  return {valid:errors.length === 0, errors, warnings};
+}

package/src/standalone/validate.ts

@@ -0,0 +1,93 @@
+// Standalone forms from ELEMENT_PRIMITIVES and CONTRACT (Methodology 7).
+// Field payloads are opaque: only their published identity/admission contract is checked.
+import { isCanonicalIdOfType, typeOfId, type CanonCatalog } from '../typed-id.js';
+import type { ValidationResult } from '../validation-types.js';
+
+export const mapping = (v: unknown): v is Record<string, unknown> => !!v && typeof v === 'object' && !Array.isArray(v);
+const text = (v: unknown): v is string => typeof v === 'string' && v.trim().length > 0;
+export const isoDate = (v: unknown): v is string => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(v) && Number.isFinite(Date.parse(v)) && new Date(v).toISOString().slice(0, 10) === v;
+const capabilityId = (v: unknown) => typeof v === 'string' && /^CAPABILITY-[VH][1-9]\d*(?:\.[1-9]\d*)*$/.test(v);
+export interface StandaloneOptions { catalog?: CanonCatalog; documents?: ReadonlyMap<string, Record<string, unknown>> }
+
+export function validateStandalone(notation: string, input: unknown, options: StandaloneOptions = {}): ValidationResult {
+  const errors: ValidationResult['errors'] = [], warnings: ValidationResult['warnings'] = [];
+  const fail = (field: string, expected: string, actual: unknown, code = 'SCHEMA_INVALID') => errors.push({code, message: `${notation} standalone: ${field}: expected ${expected}; actual ${JSON.stringify(actual) ?? 'missing'}.`, path: field});
+  if (!mapping(input)) { fail('$', 'mapping', input); return {valid:false, errors, warnings}; }
+  const d = input, field = ['draft', 'observation'].includes(notation);
+  const requiredText = (key: string) => { if (!text(d[key])) fail(key, 'nonempty string', d[key]); };
+  const optionalText = (key: string) => { if (key in d && !text(d[key])) fail(key, 'nonempty string', d[key]); };
+  if (d.notation !== notation && !(field && d.notation === undefined && d.type === notation.toUpperCase())) fail('notation', notation, d.notation);
+  if (!(notation === 'capability' ? capabilityId(d.id) : isCanonicalIdOfType(d.id, notation.toUpperCase()))) fail('id', `${notation.toUpperCase()} canonical ID`, d.id);
+  if (!field) requiredText('name'); else optionalText('name');
+  if (d.zone !== (field ? 'field' : 'canon')) fail('zone', field ? 'field' : 'canon', d.zone);
+  requiredText('admitted_by');
+  if (!isoDate(d.admitted_at)) fail('admitted_at', 'ISO calendar date', d.admitted_at);
+  if (!mapping(d.gate_checks)) fail('gate_checks', 'mapping', d.gate_checks);
+  else for (const key of field ? ['provenance'] : ['uniqueness', 'consistency', 'completeness']) {
+    if (!text(d.gate_checks[key])) fail(`gate_checks.${key}`, 'nonempty check outcome', d.gate_checks[key]);
+  }
+  if (!field) {
+    if (!isoDate(d.valid_from)) fail('valid_from', 'ISO calendar date', d.valid_from, 'LIFECYCLE-001');
+    if (!(d.valid_to === null || isoDate(d.valid_to))) fail('valid_to', 'ISO calendar date or null', d.valid_to, 'LIFECYCLE-002');
+    if (isoDate(d.valid_from) && isoDate(d.valid_to) && d.valid_to < d.valid_from) fail('valid_to', 'date on or after valid_from', d.valid_to, 'LIFECYCLE-003');
+  }
+  const ref = (key: string, value: unknown, types: string[]) => {
+    const type = typeOfId(value);
+    if (!type || !types.includes(type) || !(type === 'CAPABILITY' ? capabilityId(value) : isCanonicalIdOfType(value, type))) { fail(key, types.join('|') + ' canonical reference', value); return; }
+    if (options.catalog && !types.includes(options.catalog.typeOf(value as string) ?? '')) fail(key, 'reference to admitted ' + types.join('|'), value);
+  };
+  const reference = (key: string, types: string[], required = false) => { if (required || key in d) ref(key, d[key], types); };
+  const references = (key: string, types: string[], required = false) => {
+    if (!required && !(key in d)) return;
+    const values = d[key];
+    if (!Array.isArray(values) || (required && values.length === 0)) { fail(key, required ? 'nonempty list of references' : 'list of references', values); return; }
+    values.forEach((v, i) => ref(`${key}[${i}]`, v, types));
+  };
+  optionalText('description');
+  if (notation === 'product') {
+    if (!['digital_product','service','platform','bundle'].includes(d.type as string)) fail('type', 'digital_product|service|platform|bundle', d.type);
+    optionalText('domain'); reference('owner_role', ['ROLE']);
+    if ('maturity' in d && !(Number.isInteger(d.maturity) && Number(d.maturity) >= 1 && Number(d.maturity) <= 5)) fail('maturity', 'integer 1..5', d.maturity);
+    references('capabilities', ['CAPABILITY']); references('processes', ['PROCESS']); references('supporting_apps', ['APPLICATION']);
+  } else if (notation === 'capability') {
+    if (!['domain','supporting'].includes(d.type as string)) fail('type', 'domain|supporting', d.type);
+    for (const key of ['current_maturity','target_maturity','owner_role','target_date']) if (key in d) fail(key, 'attribute in history sidecar, absent inline', d[key], 'VERSIONED-004');
+    reference('business_process', ['PROCESS']); references('applications', ['APPLICATION']);
+  } else if (notation === 'role') {
+    optionalText('responsibility_area'); reference('unit', ['ACTOR']);
+    const unit = typeof d.unit === 'string' ? options.documents?.get(d.unit) : undefined;
+    if (unit && unit.type !== 'business_unit') fail('unit', 'ACTOR of type business_unit', d.unit);
+  } else if (notation === 'assessment') {
+    requiredText('description'); reference('assesses', ['DRIVER','FACTOR'], true);
+    for (const key of ['method','source']) optionalText(key);
+    if ('observed_at' in d && !isoDate(d.observed_at)) fail('observed_at', 'ISO calendar date', d.observed_at);
+    for (const key of ['polarity','swot','type']) if (key in d) fail(key, 'absent on assessment', d[key]);
+    if ('geographic_scope' in d) {
+      const values = d.geographic_scope;
+      // Country vocabulary is checked by the shared jurisdiction set below.
+      if (!Array.isArray(values) || !values.length || values.some(v => typeof v !== 'string' || !COUNTRIES.has(v.toLowerCase())) || (values.some(v => typeof v === 'string' && v.toLowerCase() === 'global') && values.length !== 1)) fail('geographic_scope', 'nonempty ISO country/eu list, or [global]', values, 'ASSESS-001');
+    }
+  } else if (notation === 'scenario') {
+    references('pursues', ['GOAL'], true); reference('arrives_at', ['TARGET_STATE'], true); references('steps', ['ACTION','CHANGE'], true);
+    const target = typeof d.arrives_at === 'string' ? options.documents?.get(d.arrives_at) : undefined;
+    if (target?.type === 'base') fail('arrives_at', 'target plateau, not base', d.arrives_at);
+    for (const key of ['type','vision','factors_view','status','drivers','capabilities','processes','applications','products']) if (key in d) fail(key, 'absent on standalone scenario', d[key]);
+    optionalText('link');
+  } else if (field) {
+    const provenance = d.provenance;
+    if (provenance === undefined || provenance === null || (typeof provenance === 'string' && !provenance.trim()) || (mapping(provenance) && Object.keys(provenance).length === 0)) fail('provenance', 'recorded source evidence', provenance);
+    else if (!mapping(provenance)) warnings.push({code:'NOTATION-SKIP-001',message:'Field provenance form is unsupported; source evidence remains unvalidated.'});
+    else {
+      // Two supported evidence forms: captured source and versioned source import.
+      // Other forms remain visible as unsupported, not falsely validated or forbidden.
+      const captured = text(provenance.captured_by) && isoDate(provenance.captured_on) && text(provenance.setting);
+      const imported = text(provenance.source_revision) && text(provenance.original_path) && text(provenance.source_hash) && isoDate(provenance.captured_on);
+      if (!captured && !imported) warnings.push({code:'NOTATION-SKIP-001',message:'Field provenance form is unsupported: source, capture date and context cannot all be checked.'});
+    }
+    if ('source_quality' in d && !['authoritative','corroborated','single_source','unverified'].includes(d.source_quality as string)) fail('source_quality', 'authoritative|corroborated|single_source|unverified', d.source_quality);
+  }
+  return {valid: errors.length === 0, errors, warnings};
+}
+
+// ISO 3166-1 alpha-2 vocabulary, plus the published eu/global scope tokens.
+const COUNTRIES = new Set(('ad ae af ag ai al am ao aq ar as at au aw ax az ba bb bd be bf bg bh bi bj bl bm bn bo bq br bs bt bv bw by bz ca cc cd cf cg ch ci ck cl cm cn co cr cu cv cw cx cy cz de dj dk dm do dz ec ee eg eh er es et fi fj fk fm fo fr ga gb gd ge gf gg gh gi gl gm gn gp gq gr gs gt gu gw gy hk hm hn hr ht hu id ie il im in io iq ir is it je jm jo jp ke kg kh ki km kn kp kr kw ky kz la lb lc li lk lr ls lt lu lv ly ma mc md me mf mg mh mk ml mm mn mo mp mq mr ms mt mu mv mw mx my mz na nc ne nf ng ni nl no np nr nu nz om pa pe pf pg ph pk pl pm pn pr ps pt pw py qa re ro rs ru rw sa sb sc sd se sg sh si sj sk sl sm sn so sr ss st sv sx sy sz tc td tf tg th tj tk tl tm tn to tr tt tv tw tz ua ug um us uy uz va vc ve vg vi vn vu wf ws ye yt za zm zw eu global').split(' '));

package/src/webview/entry.ts

@@ -275,10 +275,14 @@ function dispatchValidate(kind: NotationKind, doc: unknown): RenderResult {
       return renderFromValidation('scenarios', validateScenario(doc), () =>
         renderScenarioHtml((doc as ScenarioFile).scenario),
       );
-    case 'capability-map':
-      return renderFromValidation('capability-map', validateCapabilityMap(doc), () =>
+    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 as CapabilityMapFile).capability_map),
       );
+    }
     default:
       return errorResult(
         kind,

package/src/webview/render-goals.ts

@@ -56,7 +56,8 @@ export function renderGoalsSvg(tree: GoalTree, options: RenderGoalsOptions = {})
     ? `<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' });
 }
 
 export interface RenderGoalsLayoutOptions {

package/src/webview/styles.css

@@ -70,6 +70,14 @@ body {
   margin-left: 6px;
 }
 
+/* The bundled SVG renderer uses its light palette independently of IDE chrome.
+ * Give transparent SVG titles and edges a matching canvas. */
+.tx-svg-host {
+  background: #ffffff;
+  color: #0d2b35;
+  min-height: calc(100vh - 24px);
+}
+
 .tx-svg-host svg {
   max-width: 100%;
   height: auto;