@transitrix/diagrams 1.14.0 → 1.16.0

package/src/compliance/requirement-chain.ts

@@ -7,7 +7,8 @@ import { validateVerification } from '../verification/validate.js';
 
 export const CHAIN_STAGES = ['Source document', 'Driver', 'Need', 'Stakeholder requirement',
   'System requirement', 'Software requirement', 'Unclassified requirement', 'Verification definition', 'Result'] as const;
-export interface ChainScope { catalogue: string; product?: string; release?: string; project?: string }
+export interface ChainSubject { type: 'PRODUCT' | 'APPLICATION'; id: string }
+export interface ChainScope { catalogue: string; subject?: ChainSubject; product?: string; release?: string; project?: string }
 export interface ChainInput {
   index: ComplianceIndex; scope: ChainScope; asAt: string; snapshotId: string;
   sourceRevision?: string; complete: boolean;
@@ -23,7 +24,7 @@ export interface RequirementChainEdge {
 }
 export interface ChainAssignment { requirement: string; nearest: string; depth: number; relations: string[] }
 export interface RequirementChainProjection {
-  contract: 'requirement-chain/0.2'; contractRevision: string; asAt: string; snapshotId: string; sourceRevision?: string;
+  contract: 'requirement-chain/0.2' | 'requirement-chain/0.3'; contractRevision: string; asAt: string; snapshotId: string; sourceRevision?: string;
   scope: ChainScope; completeness: 'complete' | 'incomplete'; scopeFindings: string[];
   populations: { product: ChainSet; release: ChainSet; selected: ChainSet; inactive: ChainSet; unresolved: ChainSet };
   assignments: { here: ChainSet; otherReleaseOnly: ChainSet; unassigned: ChainSet; invalid: ChainSet; provenance: ChainAssignment[] };
@@ -53,9 +54,26 @@ function freeze<T>(value: T): T {
 const CODEX = ['LAW', 'REGULATION', 'STANDARD', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'];
 const FIELD = ['INTERVIEW', 'SURVEY', 'OBSERVATION', 'DRAFT'];
 
-/** Pure, lossless release projection; no legacy coverage verdict is reinterpreted. */
+/** Explicit PRODUCT compatibility adapter for requirement-chain/0.2. */
 export function buildRequirementChain(input: ChainInput): RequirementChainProjection {
+  if (input.scope.subject) throw new Error('Use buildSubjectRequirementChain for explicit subjects');
+  return projectRequirementChain(input);
+}
+
+/** Subject-aware 0.3 entry point; both versions use the same deterministic projection. */
+export function buildSubjectRequirementChain(input: ChainInput & { scope: ChainScope & { subject: ChainSubject } }): RequirementChainProjection {
+  if (input.scope.product !== undefined) throw new Error('Conflicting product and subject selectors');
+  if (!['PRODUCT', 'APPLICATION'].includes(input.scope.subject.type)) throw new Error('Unsupported subject type');
+  return projectRequirementChain(input);
+}
+
+/** Pure, lossless release projection; no legacy coverage verdict is reinterpreted. */
+function projectRequirementChain(input: ChainInput): RequirementChainProjection {
   const { index, asAt, scope } = input;
+  const subject = scope.subject ?? { type: 'PRODUCT', id: scope.product };
+  const membershipKind = subject.type === 'APPLICATION' ? 'application_scope' : 'product_scope';
+  const pairKind = subject.type === 'APPLICATION' ? 'project_application' : 'project_product';
+  const subjectWord = scope.subject ? 'subject' : 'product';
   const findings = structuredClone(index.findings);
   const scopeFindings: string[] = [];
   const records = new Map<string, ChainRecord>();
@@ -64,7 +82,7 @@ export function buildRequirementChain(input: ChainInput): RequirementChainProjec
     const id = `${owner}.${field}`;
     if (!findings.some(f => f.id === id && f.code === code)) findings.push({ id, owner, field, code, message, reference, severity: warning ? 'warning' : 'error' });
   };
-  for (const [id, versions] of index.recordsById) {
+  for (const [id, versions] of [...index.recordsById].sort(([a], [b]) => a.localeCompare(b))) {
     if (versions.length !== 1) {
       finding(id, 'id', 'DUPLICATE', 'Ambiguous catalogue identity'); complete = false;
     } else records.set(id, structuredClone(versions[0]));
@@ -114,7 +132,7 @@ export function buildRequirementChain(input: ChainInput): RequirementChainProjec
       if (r.raw.level !== undefined && level < 0) finding(r.id, 'level', 'REQ-LEVEL', 'Invalid level; displayed as unclassified');
     } else if (r.type === 'NEED') node(r, 2);
     else if (r.type === 'DRIVER') node(r, 1);
-    else if (['PRODUCT', 'RELEASE', 'ACTION'].includes(r.type)) node(r, -1);
+    else if (['PRODUCT', 'APPLICATION', 'RELEASE', 'ACTION'].includes(r.type)) node(r, -1);
     else if (CODEX.includes(r.type) || FIELD.includes(r.type)) {
       node(r, 0);
       if (r.raw.source_document !== undefined) {
@@ -162,6 +180,8 @@ export function buildRequirementChain(input: ChainInput): RequirementChainProjec
     const src = records.get(from), dst = records.get(to);
     const endpoints = kind === 'requirement_parent' ? is(from, 'REQUIREMENT') && is(to, 'REQUIREMENT') :
       kind === 'serves' ? is(from, 'REQUIREMENT') && is(to, 'NEED') :
+      kind === 'application_scope' ? is(from, 'REQUIREMENT') && is(to, 'APPLICATION') :
+      kind === 'project_application' ? isProject(from) && is(to, 'APPLICATION') :
       kind === 'product_scope' ? is(from, 'REQUIREMENT') && is(to, 'PRODUCT') :
       kind === 'project_scope' ? is(from, 'REQUIREMENT') && isProject(to) :
       kind === 'project_product' ? isProject(from) && is(to, 'PRODUCT') :
@@ -198,38 +218,38 @@ export function buildRequirementChain(input: ChainInput): RequirementChainProjec
     }
   }
   const memberships = (id: string, kind: string) => rels.filter(r => usable.has(r.id) && r.raw.type === kind && r.raw.from === id).map(r => String(r.raw.to));
-  const unresolved = requirements.filter(r => active.get(r.id) && memberships(r.id, 'product_scope').length === 0).map(r => r.id);
-  const P = requirements.filter(r => active.get(r.id) && memberships(r.id, 'product_scope').includes(scope.product ?? '')).map(r => r.id);
+  const unresolved = requirements.filter(r => active.get(r.id) && memberships(r.id, 'product_scope').length === 0 && (!scope.subject || memberships(r.id, 'application_scope').length === 0)).map(r => r.id);
+  const P = requirements.filter(r => active.get(r.id) && memberships(r.id, membershipKind).includes(subject.id ?? '')).map(r => r.id);
   let productComplete = complete && unresolved.length === 0;
-  if (unresolved.length) scopeFindings.push('Unresolved product membership');
-  if (requirements.some(r => !envelope.get(r.id)) || rels.some(r => r.raw.type === 'product_scope' && active.get(r.id) && !usable.has(r.id))) productComplete = false;
+  if (unresolved.length) scopeFindings.push(`Unresolved ${subjectWord} membership`);
+  if (requirements.some(r => !envelope.get(r.id)) || rels.some(r => r.raw.type === membershipKind && active.get(r.id) && !usable.has(r.id))) productComplete = false;
   const invalidAssignments = new Set<string>();
   for (const r of rels.filter(r => r.raw.type === 'required_for')) {
     const from = String(r.raw.from), to = records.get(String(r.raw.to));
     const historical = chainDate(r.raw.valid_to) && r.raw.valid_to < asAt;
     const future = chainDate(r.raw.valid_from) && r.raw.valid_from > asAt;
-    if (!historical && !future && (!usable.has(r.id) || !memberships(from, 'product_scope').includes(String(to?.raw.of)))) {
+    if (!historical && !future && (!usable.has(r.id) || ![...memberships(from, 'product_scope'), ...(scope.subject ? memberships(from, 'application_scope') : [])].includes(String(to?.raw.of)))) {
       invalidAssignments.add(from);
-      finding(r.id, 'to', 'ASSIGNMENT', 'Invalid, dangling or wrong-product assignment', true);
+      finding(r.id, 'to', 'ASSIGNMENT', `Invalid, dangling or wrong-${subjectWord} assignment`, true);
       if (!envelope.get(r.id)) productComplete = false;
     }
   }
   let selectedComplete = complete;
-  if (!is(scope.product, 'PRODUCT')) { productComplete = false; selectedComplete = false; scopeFindings.push('Product unselected or unresolved'); }
-  if (!is(scope.release, 'RELEASE') || records.get(scope.release ?? '')?.raw.of !== scope.product) {
-    selectedComplete = false; scopeFindings.push('Release unselected, unresolved or wrong product');
+  if (!is(subject.id, subject.type)) { productComplete = false; selectedComplete = false; scopeFindings.push(scope.subject ? 'Subject unselected or unresolved' : 'Product unselected or unresolved'); }
+  if (!is(scope.release, 'RELEASE') || records.get(scope.release ?? '')?.raw.of !== subject.id) {
+    selectedComplete = false; scopeFindings.push(`Release unselected, unresolved or wrong ${subjectWord}`);
   }
-  if (scope.project && (!isProject(scope.project) || !memberships(scope.project, 'project_product').includes(scope.product ?? ''))) {
-    selectedComplete = false; scopeFindings.push('Invalid or unmodelled project/product pair');
+  if (scope.project && (!isProject(scope.project) || !memberships(scope.project, pairKind).includes(subject.id ?? ''))) {
+    selectedComplete = false; scopeFindings.push(`Invalid or unmodelled project/${subjectWord} pair`);
   }
   function query(release: string): { ids: string[]; provenance: ChainAssignment[]; complete: boolean } {
     const chain: string[] = []; let cursor: string | undefined = release; let valid = true;
     while (cursor) {
       const r: ChainRecord | undefined = records.get(cursor);
-      if (chain.includes(cursor) || !is(cursor, 'RELEASE') || r?.raw.of !== scope.product) {
+      if (chain.includes(cursor) || !is(cursor, 'RELEASE') || r?.raw.of !== subject.id) {
         valid = false;
         finding(chain[chain.length - 1] ?? release, 'predecessor', 'RELEASE-SCOPE',
-          chain.includes(cursor) ? 'Release predecessor cycle' : 'Missing, invalid or cross-product predecessor');
+          chain.includes(cursor) ? 'Release predecessor cycle' : `Missing, invalid or cross-${subjectWord} predecessor`);
         break;
       }
       chain.push(cursor);
@@ -251,13 +271,13 @@ export function buildRequirementChain(input: ChainInput): RequirementChainProjec
   if (scope.project && L.some(id => memberships(id, 'project_scope').length === 0 || rels.some(r => r.raw.type === 'project_scope' && r.raw.from === id && active.get(r.id) && !usable.has(r.id)))) {
     selectedComplete = false; scopeFindings.push('Unresolved project membership');
   }
-  if (rels.some(r => ['product_scope', 'project_scope', 'required_for'].includes(String(r.raw.type)) && !envelope.get(r.id))) selectedComplete = false;
-  if (scope.project && L.some(id => memberships(id, 'project_scope').some(project => !memberships(project, 'project_product').includes(scope.product ?? '')))) {
-    selectedComplete = false; scopeFindings.push('Inconsistent project/product membership');
+  if (rels.some(r => [membershipKind, 'project_scope', 'required_for'].includes(String(r.raw.type)) && !envelope.get(r.id))) selectedComplete = false;
+  if (scope.project && L.some(id => memberships(id, 'project_scope').some(project => !memberships(project, pairKind).includes(subject.id ?? '')))) {
+    selectedComplete = false; scopeFindings.push(`Inconsistent project/${subjectWord} membership`);
   }
   const S = L.filter(id => !scope.project || memberships(id, 'project_scope').includes(scope.project));
   const elsewhere = new Set<string>();
-  for (const release of records.values()) if (release.type === 'RELEASE' && release.raw.of === scope.product) {
+  for (const release of records.values()) if (release.type === 'RELEASE' && release.raw.of === subject.id) {
     const q = query(release.id); productComplete &&= q.complete; q.ids.forEach(id => elsewhere.add(id));
   }
   const unassigned = P.filter(id => !elsewhere.has(id) && !invalidAssignments.has(id));
@@ -307,7 +327,7 @@ export function buildRequirementChain(input: ChainInput): RequirementChainProjec
     const owners = new Set(ancestors);
     for (const v of verifications) if (v.raw.verifies === r.id) owners.add(v.id);
     for (const rel of rels) {
-      const ownScope = ['product_scope', 'project_scope', 'required_for'].includes(String(rel.raw.type));
+      const ownScope = [membershipKind, 'project_scope', 'required_for'].includes(String(rel.raw.type));
       if (ownScope ? rel.raw.from === r.id : owners.has(String(rel.raw.from))) owners.add(rel.id);
     }
     for (const f of findings) if (owners.has(f.owner)) (affectedRequirements[f.id] ??= []).push(r.id);
@@ -326,15 +346,16 @@ export function buildRequirementChain(input: ChainInput): RequirementChainProjec
   const selectedRefs = refs.filter(f => affectedRequirements[f.id]?.some(id => S.includes(id)));
   const broken = S.filter(id => selectedRefs.some(f => affectedRequirements[f.id]?.includes(id)));
   for (const n of nodes) if (records.get(n.recordId)?.type === 'REQUIREMENT' && !S.includes(n.recordId)) {
-    n.context.push(!active.get(n.recordId) ? 'inactive' : !P.includes(n.recordId) ? 'unresolved or other product' :
+    n.context.push(!active.get(n.recordId) ? 'inactive' : !P.includes(n.recordId) ? `unresolved or other ${subjectWord}` :
       !L.includes(n.recordId) ? 'other release or unassigned' : 'other project');
   }
+  if (scope.subject && (!is(subject.id, subject.type) || !is(scope.release, 'RELEASE') || records.get(scope.release ?? '')?.raw.of !== subject.id)) productComplete = false;
   const unassignedSet = set(unassigned, productComplete);
   const result: RequirementChainProjection = {
-    contract: 'requirement-chain/0.2', contractRevision: '97c9d41819011ead8fe192c266cba32707eae82f', asAt, snapshotId: input.snapshotId, sourceRevision: input.sourceRevision,
+    contract: scope.subject ? 'requirement-chain/0.3' : 'requirement-chain/0.2', contractRevision: scope.subject ? 'a131b1862d86f34be8feb729e1cc6ebc994c3891' : '97c9d41819011ead8fe192c266cba32707eae82f', asAt, snapshotId: input.snapshotId, sourceRevision: input.sourceRevision,
     scope: structuredClone(scope), completeness: productComplete && selectedComplete ? 'complete' : 'incomplete', scopeFindings: sorted(scopeFindings),
     populations: { product: set(P, productComplete), release: set(L, selectedComplete), selected: set(S, selectedComplete),
-      inactive: set(requirements.filter(r => envelope.get(r.id) && !active.get(r.id) && rels.some(rel => rel.raw.type === 'product_scope' && rel.raw.from === r.id && rel.raw.to === scope.product && envelope.get(rel.id))).map(r => r.id), complete),
+      inactive: set(requirements.filter(r => envelope.get(r.id) && !active.get(r.id) && rels.some(rel => rel.raw.type === membershipKind && rel.raw.from === r.id && rel.raw.to === subject.id && envelope.get(rel.id))).map(r => r.id), complete),
       unresolved: set(unresolved, complete) },
     assignments: { here: set(L, selectedComplete), otherReleaseOnly: set(P.filter(id => elsewhere.has(id) && !L.includes(id)), productComplete),
       unassigned: unassignedSet, invalid: set(P.filter(id => invalidAssignments.has(id)), complete), provenance: selected.provenance.sort((a, b) => a.requirement.localeCompare(b.requirement)) },
@@ -408,6 +429,7 @@ export function requirementReleaseCounts(p: RequirementChainProjection) {
   const contextUnits = { 0: 'source documents', 1: 'drivers', 2: 'needs', 7: 'definition parts', 8: 'result parts' } as const;
   for (const stage of [0, 1, 2, 7, 8] as const) add('context-' + stage, CHAIN_STAGES[stage],
     set(view.nodes.filter(n => n.stage === stage).map(n => n.id), p.populations.selected.completeness === 'complete'), contextUnits[stage]);
+  if (p.scope.subject) for (const count of Object.values(counts)) count.label = count.label.replace(/whole product/g, 'whole subject').replace('Product requirements', 'Subject requirements');
   return freeze(counts);
 }
 
@@ -421,7 +443,10 @@ export class RequirementChainSnapshot {
     try {
       const input = await load();
       if (generation !== this.generation) return false;
-      this.current = buildRequirementChain(input); this.stale = false; return true;
+      this.current = input.scope.subject
+        ? buildSubjectRequirementChain({ ...input, scope: { ...input.scope, subject: input.scope.subject } })
+        : buildRequirementChain(input);
+      this.stale = false; return true;
     } catch {
       if (generation === this.generation) this.stale = true;
       return false;

package/src/products/types.ts

@@ -1,4 +1,4 @@
-export type ProductType = 'digital_product' | 'service' | 'platform' | 'bundle';
+export type ProductType = 'physical_product' | 'digital_product' | 'service' | 'platform' | 'bundle';
 export type ProductStatus = 'Draft' | 'Active' | 'Deprecated';
 
 export interface Product {

package/src/products/validate.ts

@@ -4,7 +4,7 @@ import type { ValidationError, ValidationWarning, ValidationResult } from '../va
 
 export type { ValidationError, ValidationWarning, ValidationResult };
 
-const VALID_TYPES = new Set<ProductType>(['digital_product', 'service', 'platform', 'bundle']);
+const VALID_TYPES = new Set<ProductType>(['physical_product', 'digital_product', 'service', 'platform', 'bundle']);
 const VALID_STATUSES = new Set<ProductStatus>(['Draft', 'Active', 'Deprecated']);
 const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
 

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,129 @@
+// Standalone forms from ELEMENT_PRIMITIVES and CONTRACT (Methodology 7).
+// Field payloads are opaque: only their published identity/admission contract is checked.
+import { isCanonicalId, 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 (!['physical_product', 'digital_product','service','platform','bundle'].includes(d.type as string)) fail('type', 'physical_product|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 === 'process') {
+    reference('owner_role', ['ROLE']); reference('capability', ['CAPABILITY']);
+    references('participants', ['ROLE', 'ACTOR']);
+    optionalText('goal'); optionalText('result');
+    for (const key of ['parent', 'bpmn_file', 'maturity']) if (key in d) fail(key, 'absent inline; use canonical relations, flow or history', d[key]);
+    if (Array.isArray(d.participants) && new Set(d.participants).size !== d.participants.length) fail('participants', 'unique references', d.participants);
+    if ('flow' in d) {
+      if (!mapping(d.flow)) fail('flow', 'mapping', d.flow);
+      else {
+        const flow = d.flow;
+        const steps = Array.isArray(flow.steps) ? flow.steps : [];
+        const sequence = Array.isArray(flow.sequence) ? flow.sequence : [];
+        if (!Array.isArray(flow.steps) || !steps.length) fail('flow.steps', 'nonempty list', flow.steps);
+        if (!Array.isArray(flow.sequence)) fail('flow.sequence', 'list', flow.sequence);
+        const ids = new Set<string>();
+        const types = ['startEvent', 'endEvent', 'task', 'userTask', 'serviceTask', 'exclusiveGateway', 'parallelGateway'];
+        steps.forEach((step, i) => {
+          const key = `flow.steps[${i}]`;
+          if (!mapping(step)) { fail(key, 'mapping', step); return; }
+          if (!isCanonicalId(step.id) || ids.has(step.id)) fail(`${key}.id`, 'unique canonical step ID', step.id);
+          else ids.add(step.id);
+          if (!types.includes(step.type as string)) fail(`${key}.type`, types.join('|'), step.type);
+          if ((!['startEvent','endEvent'].includes(step.type as string) || 'name' in step) && !text(step.name)) fail(`${key}.name`, 'nonempty string', step.name);
+          ref(`${key}.performed_by`, step.performed_by, ['ROLE','ACTOR']);
+          if (!Array.isArray(d.participants) || !d.participants.includes(step.performed_by)) fail(`${key}.performed_by`, 'member of participants', step.performed_by);
+          if ('supported_by_application' in step) ref(`${key}.supported_by_application`, step.supported_by_application, ['APPLICATION']);
+        });
+        sequence.forEach((edge, i) => {
+          const key = `flow.sequence[${i}]`;
+          if (!mapping(edge)) { fail(key, 'mapping', edge); return; }
+          for (const end of ['from', 'to']) if (typeof edge[end] !== 'string' || !ids.has(edge[end] as string)) fail(`${key}.${end}`, 'ID in flow.steps', edge[end]);
+          if ('condition' in edge && !text(edge.condition)) fail(`${key}.condition`, 'nonempty string', edge.condition);
+          if ('default' in edge && typeof edge.default !== 'boolean') fail(`${key}.default`, 'boolean', edge.default);
+        });
+      }
+    }
+  } 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/render-activities.ts

@@ -26,7 +26,7 @@ import type {
 } from '../activities/types.js';
 import { horizontalCubicEdgePath, bowedCubicEdgePath, DEFAULT_EDGE_CURVATURE } from '../edge-path.js';
 import { parseNodeSizePreset, resolveActionNodeSize, type NodeSizePreset } from '../node-size-presets.js';
-import { generateSvgEmbedCss } from '../theme/index.js';
+import { generateSvgEmbedCss, type ThemeId } from '../theme/index.js';
 import { emitCenteredTextSvg, layoutCenteredEntityText } from './entity-text-layout.js';
 import { escXml } from './render-util.js';
 
@@ -235,6 +235,11 @@ export interface RenderActivitiesOptions {
    * Action name in the view header.
    */
   suppressProjectNodes?: boolean;
+  /**
+   * Theme CSS embedded as `<style>` so the SVG is self-contained.
+   * Defaults to `'transitrix'`. VS Code live preview uses body emitters + webview CSS instead.
+   */
+  embedCssTheme?: ThemeId;
 }
 
 /**
@@ -259,6 +264,7 @@ export function renderActivitiesSvg(doc: ActivityDoc, options: RenderActivitiesO
     curvature = DEFAULT_EDGE_CURVATURE,
     entryCurvature,
     suppressProjectNodes = true,
+    embedCssTheme = 'transitrix',
   } = options;
   const nodeSize = resolveActionNodeSize(parseNodeSizePreset(nodeSizePreset));
   const layoutGaps: ActivitiesLayoutOptions = {
@@ -300,7 +306,7 @@ export function renderActivitiesSvg(doc: ActivityDoc, options: RenderActivitiesO
   // drop the SVG into the DOM and styling resolves without any cooperation from
   // the host stylesheet. Matches what the VS Code path produces via
   // `prepareSvgForExport`.
-  const embedCss = generateSvgEmbedCss('transitrix') + ACTIVITIES_NETWORK_CSS;
+  const embedCss = generateSvgEmbedCss(embedCssTheme) + ACTIVITIES_NETWORK_CSS;
 
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
 <style>${embedCss}</style>

package/src/webview/render-activity-card.ts

@@ -31,7 +31,7 @@ import type {
   ResolvedActivityCard,
   ResolvedMilestone,
 } from '../activity-card/types.js';
-import { generateSvgEmbedCss } from '../theme/index.js';
+import { generateSvgEmbedCss, type ThemeId } from '../theme/index.js';
 import { escXml } from './render-util.js';
 
 const PAD = 24;
@@ -39,6 +39,11 @@ const EMPTY_SVG = `<svg xmlns="http://www.w3.org/2000/svg" width="0" height="0"
 
 export interface RenderActivityCardOptions {
   title?: string;
+  /**
+   * Theme CSS embedded as `<style>` so the SVG is self-contained.
+   * Defaults to `'transitrix'`. VS Code live preview uses body emitters + webview CSS instead.
+   */
+  embedCssTheme?: ThemeId;
 }
 
 function truncate(text: string, maxChars: number): string {
@@ -241,7 +246,7 @@ export function renderActivityCardSvg(
   // §5.1 class convention the layout applies; keeps the import meaningful.
   void ARCHIMATE_CLASS;
 
-  const { title = '' } = options;
+  const { title = '', embedCssTheme = 'transitrix' } = options;
   const resolved = resolveSingleDoc(doc);
   const layout = layoutActivityCard(resolved);
 
@@ -259,7 +264,7 @@ export function renderActivityCardSvg(
     ? `<text class="text-header" x="${PAD}" y="${PAD + 14}">${escXml(`Activity Card — ${title}`)}</text>`
     : '';
 
-  const embedCss = generateSvgEmbedCss('transitrix');
+  const embedCss = generateSvgEmbedCss(embedCssTheme);
 
   return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}">
 <style>${embedCss}</style>

package/src/webview/render-blocks.ts

@@ -41,6 +41,11 @@ export interface RenderBlocksOptions {
   title?: string;
   nodeSizePreset?: NodeSizePreset;
   layoutOptions?: BlocksLayoutOptions;
+  /**
+   * Theme CSS embedded via {@link renderBlocksLayoutSvg}.
+   * Defaults to `'transitrix'` for self-contained host-neutral SVG.
+   */
+  embedCssTheme?: ThemeId;
 }
 
 /**
@@ -133,7 +138,7 @@ ${parts.join('\n')}
  * with the shared theme CSS embedded so the output is self-contained.
  */
 export function renderBlocksSvg(doc: BlocksFile, options: RenderBlocksOptions = {}): string {
-  const { title = '', nodeSizePreset = 'normal', layoutOptions } = options;
+  const { title = '', nodeSizePreset = 'normal', layoutOptions, embedCssTheme = 'transitrix' } = options;
   const leaf = resolveBlocksLeafSize(parseNodeSizePreset(nodeSizePreset));
 
   const layout: BlocksLayout = layoutNestedBlocks(doc, {
@@ -150,7 +155,7 @@ export function renderBlocksSvg(doc: BlocksFile, options: RenderBlocksOptions =
     ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(`Nested Blocks — ${title}`)}</text>`
     : '';
 
-  return renderBlocksLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
+  return renderBlocksLayoutSvg(layout, { title: titleSvg, embedCssTheme });
 }
 
 /**
@@ -285,11 +290,16 @@ ${body}
 export interface RenderGridOptions {
   title?: string;
   layoutOptions?: GridLayoutOptions;
+  /**
+   * Theme CSS embedded via {@link renderGridLayoutSvg}.
+   * Defaults to `'transitrix'` for self-contained host-neutral SVG.
+   */
+  embedCssTheme?: ThemeId;
 }
 
 /** Host-neutral grid (matrix subset) renderer (IntelliJ/UI). */
 export function renderGridSvg(doc: GridFile, options: RenderGridOptions = {}): string {
-  const { title = '', layoutOptions } = options;
+  const { title = '', layoutOptions, embedCssTheme = 'transitrix' } = options;
   const layout = layoutGrid(doc, layoutOptions);
 
   if (layout.columns.length === 0 || layout.rows.length === 0) {
@@ -300,5 +310,5 @@ export function renderGridSvg(doc: GridFile, options: RenderGridOptions = {}): s
     ? `<text class="text-header" x="${PAD}" y="${PAD - 6}">${escXml(`Nested Blocks — ${title}`)}</text>`
     : '';
 
-  return renderGridLayoutSvg(layout, { title: titleSvg, embedCssTheme: 'transitrix' });
+  return renderGridLayoutSvg(layout, { title: titleSvg, embedCssTheme });
 }

package/src/webview/render-fgca.ts

@@ -24,7 +24,7 @@ import {
 import type { FGCADoc } from '../fgca/validate.js';
 import { previewEdgePath, DEFAULT_EDGE_CURVATURE, type EdgeStyle } from '../edge-path.js';
 import { parseNodeSizePreset, resolveDgcaNodeSize, type NodeSizePreset } from '../node-size-presets.js';
-import { generateSvgEmbedCss } from '../theme/index.js';
+import { generateSvgEmbedCss, type ThemeId } from '../theme/index.js';
 import { emitCenteredTextSvg, layoutCenteredEntityText, truncateLine } from './entity-text-layout.js';
 import { escXml } from './render-util.js';
 
@@ -137,6 +137,11 @@ export interface RenderFgcaOptions {
   scopeCaption?: boolean;
   /** Show completion percent badges on action nodes. */
   showCompletionPercent?: boolean;
+  /**
+   * Theme CSS embedded as `<style>` so the SVG is self-contained.
+   * Defaults to `'transitrix'`. VS Code live preview uses body emitters + webview CSS instead.
+   */
+  embedCssTheme?: ThemeId;
 }
 
 export function renderFgcaSvg(doc: FGCADoc, options: RenderFgcaOptions = {}): string {
@@ -150,6 +155,7 @@ export function renderFgcaSvg(doc: FGCADoc, options: RenderFgcaOptions = {}): st
     layoutOptions,
     scopeCaption = false,
     showCompletionPercent = true,
+    embedCssTheme = 'transitrix',
   } = options;
   const hideChanges = variant === 'dga' || doc.hideChanges === true;
   const nodeSize = resolveDgcaNodeSize(parseNodeSizePreset(nodeSizePreset));
@@ -180,7 +186,7 @@ export function renderFgcaSvg(doc: FGCADoc, options: RenderFgcaOptions = {}): st
     ? `<text class="text-caption" x="${PAD}" y="${height + 16}">${escXml('This diagram is shown for the selected goal scope. Actions on it may also serve goals outside that scope.')}</text>`
     : '';
 
-  const embedCss = generateSvgEmbedCss('transitrix');
+  const embedCss = generateSvgEmbedCss(embedCssTheme);
 
   // Calculate final height including caption if present
   const finalHeight = scopeCaption ? height + 24 : height;

package/src/webview/render-goals.ts

@@ -30,6 +30,11 @@ export interface RenderGoalsOptions {
   entryCurvature?: number;
   edgeStyle?: EdgeStyle;
   nodeSizePreset?: NodeSizePreset;
+  /**
+   * Theme CSS embedded via {@link renderGoalsLayoutSvg}.
+   * Defaults to `'transitrix'` for self-contained host-neutral SVG.
+   */
+  embedCssTheme?: ThemeId;
 }
 
 /**
@@ -38,7 +43,14 @@ export interface RenderGoalsOptions {
  * with the shared theme CSS embedded so the output is self-contained.
  */
 export function renderGoalsSvg(tree: GoalTree, options: RenderGoalsOptions = {}): string {
-  const { treeName = '', curvature = DEFAULT_EDGE_CURVATURE, entryCurvature, edgeStyle, nodeSizePreset = 'normal' } = options;
+  const {
+    treeName = '',
+    curvature = DEFAULT_EDGE_CURVATURE,
+    entryCurvature,
+    edgeStyle,
+    nodeSizePreset = 'normal',
+    embedCssTheme = 'transitrix',
+  } = options;
   const nodeSize = resolveGoalsNodeSize(parseNodeSizePreset(nodeSizePreset));
 
   const layout: GoalTreeLayout = layoutGoalTree(tree, {
@@ -57,7 +69,14 @@ export function renderGoalsSvg(tree: GoalTree, options: RenderGoalsOptions = {})
     : '';
 
   // 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' });
+  return renderGoalsLayoutSvg(layout, {
+    curvature,
+    entryCurvature,
+    edgeStyle,
+    title,
+    topInset: title ? PAD : 0,
+    embedCssTheme,
+  });
 }
 
 export interface RenderGoalsLayoutOptions {