@transitrix/diagrams 1.8.20 → 1.9.18

package/src/requirement/types.ts

@@ -1,6 +1,8 @@
 // REQUIREMENT — motivation-layer positive obligation.
 // Schema: methodology notations/elements/15-requirement.md §2.
 
+import type { AgreementValue } from '../agreement.js';
+
 export type RequirementSeverity = 'high' | 'medium' | 'low';
 
 /** Standard canon admission gate checks (CONTRACT.md §6). */
@@ -13,6 +15,16 @@ export interface GateChecks {
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
 export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'] as const;
 
+/** ISO/IEC/IEEE 29148 specification-tier ladder (15-requirement.md §2.5, REQ-005). */
+export type RequirementLevel = 'stakeholder' | 'system' | 'software';
+
+export const REQUIREMENT_LEVELS: readonly RequirementLevel[] = ['stakeholder', 'system', 'software'];
+
+/** Functional vs quality classification (15-requirement.md §2.6, REQ-006). */
+export type RequirementKind = 'functional' | 'quality';
+
+export const REQUIREMENT_KINDS: readonly RequirementKind[] = ['functional', 'quality'];
+
 export interface Requirement {
   notation: 'requirement';
   id: string;
@@ -20,8 +32,21 @@ export interface Requirement {
   description: string;
   /** Organisation-defined priority. */
   severity?: RequirementSeverity;
+  /** ISO/IEC/IEEE 29148 specification tier (§2.5, REQ-005). */
+  level?: RequirementLevel;
+  /** Functional vs quality classification (§2.6, REQ-006). */
+  kind?: RequirementKind;
   /** Typed IDs of the codex source documents this requirement is drawn from. */
   derived_from?: string[];
+  /** Typed ID of the upstream NEED this requirement traces to (§2.7, REQ-SERVES-001). Optional, singular. */
+  serves?: string;
+
+  // Agreement axis (CONTRACT.md §6.3, when present) — independent of admission.
+  /** `draft` \| `agreed` \| `disputed`. Absent ⇒ `agreed` (back-compat). */
+  agreement?: AgreementValue;
+  /** Required whenever `agreement` is present (AGREE-003). Written only by a human when `agreement: agreed` (AGREE-002). */
+  agreed_by?: string;
+  agreed_at?: string;
 
   // Admission record (CONTRACT.md §6).
   zone: 'canon';

package/src/requirement/validate.ts

@@ -11,7 +11,8 @@
 
 import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
 import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
-import { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+import { checkAgreement } from '../agreement.js';
+import { REQUIREMENT_DERIVED_FROM_TYPES, REQUIREMENT_LEVELS, REQUIREMENT_KINDS } from './types.js';
 
 export interface RequirementValidateOptions {
   /** When provided, REQ-002 enforces that each `derived_from` id is admitted. */
@@ -88,5 +89,28 @@ export function validateRequirement(input: unknown, options: RequirementValidate
     }
   }
 
+  // REQ-005 — level closed vocabulary (optional; only checked when present).
+  if (r.level !== undefined && !(REQUIREMENT_LEVELS as readonly string[]).includes(r.level as string)) {
+    errors.push({ code: 'REQ-005', message: `level "${String(r.level)}" must be one of ${REQUIREMENT_LEVELS.join(', ')}.`, path: 'level' });
+  }
+
+  // REQ-006 — kind closed vocabulary (optional; only checked when present).
+  if (r.kind !== undefined && !(REQUIREMENT_KINDS as readonly string[]).includes(r.kind as string)) {
+    errors.push({ code: 'REQ-006', message: `kind "${String(r.kind)}" must be one of ${REQUIREMENT_KINDS.join(', ')}.`, path: 'kind' });
+  }
+
+  // REQ-SERVES-001 — serves resolves to an admitted NEED (optional, singular).
+  if (r.serves !== undefined) {
+    const serves = r.serves;
+    if (typeof serves !== 'string' || serves.trim() === '' || typeOfId(serves) !== 'NEED') {
+      errors.push({ code: 'REQ-SERVES-001', message: `serves "${String(serves)}" must be a typed NEED id.`, path: 'serves' });
+    } else if (options.catalog && options.catalog.typeOf(serves) === undefined) {
+      errors.push({ code: 'REQ-SERVES-001', message: `serves "${serves}" does not resolve to an admitted NEED.`, path: 'serves' });
+    }
+  }
+
+  // AGREE-001..003 — agreement axis (CONTRACT.md §6.3.1), optional; absent ⇒ agreed.
+  errors.push(...checkAgreement(r));
+
   return { valid: errors.length === 0, errors, warnings };
 }

package/src/risk/index.ts

@@ -0,0 +1,4 @@
+export type { Risk, RiskLevel } 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

@@ -0,0 +1,35 @@
+// RISK — motivation-layer projected event (no ArchiMate counterpart).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.26.
+
+import type { GateChecks } from '../requirement/types.js';
+
+/** Likelihood / impact / residual severity vocabulary (§7.26). */
+export type RiskLevel = 'low' | 'medium' | 'high';
+
+export const RISK_LEVELS: readonly RiskLevel[] = ['low', 'medium', 'high'];
+
+export interface Risk {
+  notation: 'risk';
+  id: string;
+  name: string;
+  likelihood: RiskLevel;
+  impact: RiskLevel;
+  residual: RiskLevel;
+  /** ROLE-… accountable for tracking and treating this risk. */
+  owner_role: string;
+  /** Typed IDs of the elements this risk threatens. Non-empty; any TYPE. */
+  threatens: string[];
+  /** Typed IDs (REQUIREMENT-… / CONSTRAINT-…) of the treatment obligations. */
+  treated_by?: string[];
+  description?: string;
+
+  // Admission record (CONTRACT.md §6).
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  // Primitive lifecycle (CONTRACT.md §7).
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/risk/validate.ts

@@ -0,0 +1,121 @@
+// RISK validator — methodology ELEMENT_PRIMITIVES.md §7.26 / §9.
+//
+// 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-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).
+//   RISK-004 — a treated_by entry does not resolve, or resolves to a TYPE
+//              other than REQUIREMENT / CONSTRAINT.
+//   RISK-COVERAGE-001 (warning) — treated_by is empty/absent (an untreated
+//              risk). Unlike the cross-cutting *-COVERAGE-001 rules this
+//              reads only the RISK element's own field — no catalogue scan
+//              required — so it is implemented inline here rather than via
+//              the compliance reverse-index.
+//
+// Resolution rules (RISK-003/004) that need artefact *existence* run only
+// when a `CanonCatalog` is supplied; the TYPE check RISK-004 also carries is
+// derivable from the id prefix and runs either way.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { RISK_LEVELS } from './types.js';
+
+export interface RiskValidateOptions {
+  /** When provided, RISK-003/004 enforce artefact existence for cross-refs. */
+  catalog?: CanonCatalog;
+}
+
+const TREATED_BY_TYPES = ['REQUIREMENT', 'CONSTRAINT'] as const;
+
+export function validateRisk(input: unknown, options: RiskValidateOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'RISK-001', message: 'Risk must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const r = input as Record<string, unknown>;
+
+  // RISK-001 — id grammar + notation tag + envelope + plain per-type fields.
+  if (!isCanonicalIdOfType(r.id, 'RISK')) {
+    errors.push({ code: 'RISK-001', message: `id "${String(r.id)}" must match RISK-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (r.notation !== 'risk') {
+    errors.push({ code: 'RISK-001', message: 'notation must be the fixed value "risk".', path: 'notation' });
+  }
+  if (r.zone !== 'canon') {
+    errors.push({ code: 'RISK-001', message: 'zone is required and must be "canon".', path: 'zone' });
+  }
+  for (const f of ['name', 'admitted_at', 'admitted_by', 'valid_from', 'owner_role'] as const) {
+    if (typeof r[f] !== 'string' || (r[f] as string).trim() === '') {
+      errors.push({ code: 'RISK-001', message: `${f} is required.`, path: f });
+    }
+  }
+  if (r.gate_checks === null || typeof r.gate_checks !== 'object') {
+    errors.push({ code: 'RISK-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in r) || !(typeof r.valid_to === 'string' || r.valid_to === null)) {
+    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) {
+    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 });
+    }
+  }
+
+  // threatens — required non-empty list (RISK-001), each entry resolves (RISK-003).
+  const threatens = r.threatens;
+  if (!Array.isArray(threatens) || threatens.length === 0) {
+    errors.push({ code: 'RISK-001', message: 'threatens is required and must be a non-empty list of typed IDs.', path: 'threatens' });
+  } else {
+    threatens.forEach((ref, i) => {
+      const type = typeOfId(ref);
+      if (!type) {
+        errors.push({ code: 'RISK-003', message: `threatens[${i}] "${String(ref)}" is not a resolvable typed ID.`, path: `threatens[${i}]` });
+        return;
+      }
+      if (options.catalog && options.catalog.typeOf(ref as string) === undefined) {
+        errors.push({ code: 'RISK-003', message: `threatens[${i}] "${String(ref)}" does not resolve to an admitted element.`, path: `threatens[${i}]` });
+      }
+    });
+  }
+
+  // treated_by — optional list; each entry must resolve to REQUIREMENT/CONSTRAINT (RISK-004).
+  const treatedBy = r.treated_by;
+  if (treatedBy !== undefined) {
+    if (!Array.isArray(treatedBy)) {
+      errors.push({ code: 'RISK-001', message: 'treated_by must be a list of typed IDs.', path: 'treated_by' });
+    } else {
+      treatedBy.forEach((ref, i) => {
+        const type = typeOfId(ref);
+        if (!type || !(TREATED_BY_TYPES as readonly string[]).includes(type as typeof TREATED_BY_TYPES[number])) {
+          errors.push({ code: 'RISK-004', message: `treated_by[${i}] "${String(ref)}" must resolve to a REQUIREMENT or CONSTRAINT.`, path: `treated_by[${i}]` });
+          return;
+        }
+        if (options.catalog && options.catalog.typeOf(ref as string) === undefined) {
+          errors.push({ code: 'RISK-004', message: `treated_by[${i}] "${String(ref)}" does not resolve to an admitted artefact.`, path: `treated_by[${i}]` });
+        }
+      });
+    }
+  }
+
+  // RISK-COVERAGE-001 (warning) — untreated risk; single-file check, no catalogue needed.
+  if (!Array.isArray(treatedBy) || treatedBy.length === 0) {
+    warnings.push({
+      code: 'RISK-COVERAGE-001',
+      message: 'treated_by is empty or absent — this risk has no recorded treatment obligation.',
+      path: 'treated_by',
+    });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/schema-version.ts

@@ -4,13 +4,16 @@
  *
  * Source of truth: the methodology `methodology_version`, declared in an adopter
  * repository's `transitrix.yaml` per the methodology `notations/MANIFEST.md`
- * (single source of truth for a repo's conformance). The current methodology
- * release is **0.5.0**.
+ * (single source of truth for a repo's conformance).
+ *
+ * This is the release this build *targets*, not the newest release that exists —
+ * the methodology may be ahead. Raise it only together with the vocabulary and
+ * rule coverage that release requires, so the two never disagree. Individual
+ * hardcoded vocabulary literals may still lag the declared release; the
+ * per-module drift check is what makes such a gap visible, not this constant.
  *
  * This constant is kept in lockstep with the project manifest's
  * `transitrix.methodologyVersion` (`package.json`); the
- * `tests/schema-version.test.ts` unit test asserts the two are equal. A CI guard
- * that additionally asserts both equal the methodology's published SoT lands
- * separately (SV-1 PR2) — do not bundle it here.
+ * `tests/schema-version.test.ts` unit test asserts the two are equal.
  */
-export const SCHEMA_VERSION = '0.5.0';
+export const SCHEMA_VERSION = '3.1.0';

package/src/theme/themes.ts

@@ -118,7 +118,7 @@ function shellCss(): string {
   const cv = CSS_VAR;
   const t = TYPOGRAPHY;
   // Full-height flex chain lifted from blocks-preview / activities-preview
-  // into the shared shell (per strategy hub #35). Body is a flex column
+  // into the shared shell. Body is a flex column
   // sized to the iframe; #canvas takes the remaining height with its own
   // scroll region. Without this, #canvas was content-height and any
   // overflow-x scrollbar landed mid-panel with empty space below it — the
@@ -184,7 +184,8 @@ ${levelRules}
 .tree-maturity-5{fill:var(${cv.treeMaturity5});}
 .tree-collapse-btn{cursor:pointer;fill:white;stroke:var(${cv.nodeStroke});stroke-width:1.5;}
 .tree-collapse-btn:hover{fill:var(${cv.bgElevated});}
-.tree-collapse-lbl{fill:var(${cv.textSecondary});font-family:${t.fontFamily};font-size:12px;font-weight:700;dominant-baseline:central;pointer-events:none;}`;
+.tree-collapse-lbl{fill:var(${cv.textSecondary});font-family:${t.fontFamily};font-size:12px;font-weight:700;dominant-baseline:central;pointer-events:none;}
+.blocks-grid-border{fill:none;stroke:var(${cv.border});}`;
 }
 
 /**

package/src/validation/index.ts

@@ -0,0 +1,4 @@
+export type { Validation, ValidationMethod, ValidationOutcome } from './types.js';
+export { VALIDATION_METHODS, VALIDATION_OUTCOMES, CLOSED_VALIDATION_OUTCOMES } from './types.js';
+export { validateValidation } from './validate.js';
+export type { ValidationValidateOptions } from './validate.js';

package/src/validation/types.ts

@@ -0,0 +1,57 @@
+// VALIDATION — validation-domain claim against a NEED.
+// Schema: methodology notations/elements/28-validation.md §2.
+//
+// VALIDATION is the validation-domain counterpart to VERIFICATION (same claim
+// shape, anchored one layer further upstream on NEED instead of REQUIREMENT).
+
+import type { GateChecks } from '../requirement/types.js';
+import type { Evidence } from '../assertion/types.js';
+
+/** Validation method vocabulary (28-validation.md §3). */
+export type ValidationMethod = 'user_acceptance' | 'field_trial' | 'stakeholder_review' | 'usability_study';
+
+export const VALIDATION_METHODS: readonly ValidationMethod[] = [
+  'user_acceptance',
+  'field_trial',
+  'stakeholder_review',
+  'usability_study',
+];
+
+/** Pass/fail judgement vocabulary (28-validation.md §3). */
+export type ValidationOutcome = 'pass' | 'fail' | 'inconclusive' | 'not_yet_run';
+
+export const VALIDATION_OUTCOMES: readonly ValidationOutcome[] = [
+  'pass',
+  'fail',
+  'inconclusive',
+  'not_yet_run',
+];
+
+/** Outcomes that count as "closed" — the trace link has resolved one way or
+ *  the other, distinct from still-open (`not_yet_run` / `inconclusive`)
+ *  (28-validation.md §5, NEED-VALIDATION-COVERAGE-002). */
+export const CLOSED_VALIDATION_OUTCOMES: readonly ValidationOutcome[] = ['pass', 'fail'];
+
+export interface Validation {
+  notation: 'validation';
+  id: string;
+  /** Typed ID of the NEED this validation targets. */
+  validates: string;
+  method: ValidationMethod;
+  protocol: string;
+  result?: string;
+  outcome: ValidationOutcome;
+  evidence?: Evidence[];
+  performed_at?: string;
+  performed_by?: string;
+
+  // Admission record (CONTRACT.md §6).
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  // Primitive lifecycle (CONTRACT.md §7).
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/validation/validate.ts

@@ -0,0 +1,113 @@
+// VALIDATION validator — methodology notations/elements/28-validation.md §5.
+//
+// Implements VALID-001..006. The shared HDR-/LIFECYCLE- rules and the
+// cross-cutting NEED-VALIDATION-COVERAGE-001/002 reverse-trace rules are
+// owned elsewhere (CONTRACT.md §8) and are out of scope for this
+// single-artefact validator — same posture as `validateVerification`
+// (../verification/validate.ts), which VALIDATION mirrors one layer upstream
+// (anchored on NEED instead of REQUIREMENT).
+//
+// Resolution rules (VALID-002/005) that need artefact *existence* run only
+// when a `CanonCatalog` is supplied; the TYPE check VALID-002 also carries is
+// derivable from the id prefix and runs either way.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { VALIDATION_METHODS, VALIDATION_OUTCOMES } from './types.js';
+
+export interface ValidationValidateOptions {
+  /** When provided, the resolution rules enforce artefact existence. */
+  catalog?: CanonCatalog;
+}
+
+export function validateValidation(input: unknown, options: ValidationValidateOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+  const { catalog } = options;
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'VALID-001', message: 'Validation must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const v = input as Record<string, unknown>;
+
+  // ── VALID-001 — id grammar + plain required fields ───────────────────────
+  if (!isCanonicalIdOfType(v.id, 'VALIDATION')) {
+    errors.push({ code: 'VALID-001', message: `id "${String(v.id)}" must match VALIDATION-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (v.notation !== 'validation') {
+    errors.push({ code: 'VALID-001', message: 'notation must be the fixed value "validation".', path: 'notation' });
+  }
+  if (v.zone !== 'canon') {
+    errors.push({ code: 'VALID-001', message: 'zone is required and must be "canon".', path: 'zone' });
+  }
+  for (const f of ['admitted_at', 'admitted_by', 'valid_from', 'protocol'] as const) {
+    if (typeof v[f] !== 'string' || (v[f] as string).trim() === '') {
+      errors.push({ code: 'VALID-001', message: `${f} is required.`, path: f });
+    }
+  }
+  if (v.gate_checks === null || typeof v.gate_checks !== 'object') {
+    errors.push({ code: 'VALID-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in v) || !(typeof v.valid_to === 'string' || v.valid_to === null)) {
+    errors.push({ code: 'VALID-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+
+  // ── VALID-002 — validates → NEED ─────────────────────────────────────────
+  const validates = v.validates;
+  if (typeof validates !== 'string' || validates.trim() === '') {
+    errors.push({ code: 'VALID-002', message: 'validates is required and must be a typed NEED id.', path: 'validates' });
+  } else if (catalog) {
+    const t = catalog.typeOf(validates);
+    if (t === undefined) {
+      errors.push({ code: 'VALID-002', message: `validates "${validates}" does not resolve to an admitted artefact.`, path: 'validates' });
+    } else if (t !== 'NEED') {
+      errors.push({ code: 'VALID-002', message: `validates "${validates}" resolves to a ${t}, not a NEED.`, path: 'validates' });
+    }
+  } else if (typeOfId(validates) !== 'NEED') {
+    errors.push({ code: 'VALID-002', message: `validates "${validates}" must be a NEED typed id.`, path: 'validates' });
+  }
+
+  // ── VALID-003 — method enum ───────────────────────────────────────────────
+  const method = v.method;
+  if (method === undefined || method === null) {
+    errors.push({ code: 'VALID-001', message: 'method is required.', path: 'method' });
+  } else if (!VALIDATION_METHODS.includes(method as never)) {
+    errors.push({ code: 'VALID-003', message: `method "${String(method)}" must be one of ${VALIDATION_METHODS.join(', ')}.`, path: 'method' });
+  }
+
+  // ── VALID-004 — outcome enum ──────────────────────────────────────────────
+  const outcome = v.outcome;
+  if (outcome === undefined || outcome === null) {
+    errors.push({ code: 'VALID-001', message: 'outcome is required.', path: 'outcome' });
+  } else if (!VALIDATION_OUTCOMES.includes(outcome as never)) {
+    errors.push({ code: 'VALID-004', message: `outcome "${String(outcome)}" must be one of ${VALIDATION_OUTCOMES.join(', ')}.`, path: 'outcome' });
+  }
+
+  // ── VALID-005 — canonical_ref evidence resolves ──────────────────────────
+  if (v.evidence !== undefined) {
+    if (!Array.isArray(v.evidence)) {
+      errors.push({ code: 'VALID-001', message: 'evidence must be a list.', path: 'evidence' });
+    } else {
+      v.evidence.forEach((e, i) => {
+        if (e === null || typeof e !== 'object') return;
+        const entry = e as Record<string, unknown>;
+        if (entry.kind !== 'canonical_ref') return;
+        const ref = entry.ref;
+        if (!typeOfId(ref)) {
+          errors.push({ code: 'VALID-005', message: `evidence[${i}] canonical_ref "${String(ref)}" is not a resolvable typed ID.`, path: `evidence[${i}].ref` });
+        } else if (catalog && catalog.typeOf(ref as string) === undefined) {
+          errors.push({ code: 'VALID-005', message: `evidence[${i}] canonical_ref "${String(ref)}" does not resolve.`, path: `evidence[${i}].ref` });
+        }
+      });
+    }
+  }
+
+  // ── VALID-006 (warning) — pass outcome with no evidence ──────────────────
+  const evidenceEmpty = !Array.isArray(v.evidence) || v.evidence.length === 0;
+  if (evidenceEmpty && outcome === 'pass') {
+    warnings.push({ code: 'VALID-006', message: 'outcome "pass" has no evidence — an undefended positive claim.', path: 'evidence' });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/verification/index.ts

@@ -0,0 +1,4 @@
+export type { Verification, VerificationMethod, VerificationOutcome } from './types.js';
+export { VERIFICATION_METHODS, VERIFICATION_OUTCOMES, CLOSED_VERIFICATION_OUTCOMES } from './types.js';
+export { validateVerification } from './validate.js';
+export type { VerificationValidateOptions } from './validate.js';

package/src/verification/types.ts

@@ -0,0 +1,48 @@
+// VERIFICATION — engineering V&V claim against a REQUIREMENT.
+// Schema: methodology notations/elements/27-verification.md §2.
+
+import type { GateChecks } from '../requirement/types.js';
+import type { Evidence } from '../assertion/types.js';
+
+/** V&V method vocabulary (27-verification.md §3). */
+export type VerificationMethod = 'test' | 'analysis' | 'inspection' | 'demonstration';
+
+export const VERIFICATION_METHODS: readonly VerificationMethod[] = [
+  'test', 'analysis', 'inspection', 'demonstration',
+];
+
+/** Pass/fail judgement vocabulary (27-verification.md §3). */
+export type VerificationOutcome = 'pass' | 'fail' | 'inconclusive' | 'not_yet_run';
+
+export const VERIFICATION_OUTCOMES: readonly VerificationOutcome[] = [
+  'pass', 'fail', 'inconclusive', 'not_yet_run',
+];
+
+/** Outcomes that count as "closed" — the trace link has resolved one way or
+ *  the other, distinct from still-open (`not_yet_run` / `inconclusive`)
+ *  (27-verification.md §5, REQ-VERIF-COVERAGE-002). */
+export const CLOSED_VERIFICATION_OUTCOMES: readonly VerificationOutcome[] = ['pass', 'fail'];
+
+export interface Verification {
+  notation: 'verification';
+  id: string;
+  /** Typed ID of the REQUIREMENT this verification targets. */
+  verifies: string;
+  method: VerificationMethod;
+  protocol: string;
+  result?: string;
+  outcome: VerificationOutcome;
+  evidence?: Evidence[];
+  performed_at?: string;
+  performed_by?: string;
+
+  // Admission record (CONTRACT.md §6).
+  zone: 'canon';
+  admitted_at: string;
+  admitted_by: string;
+  gate_checks: GateChecks;
+
+  // Primitive lifecycle (CONTRACT.md §7).
+  valid_from: string;
+  valid_to: string | null;
+}

package/src/verification/validate.ts

@@ -0,0 +1,111 @@
+// VERIFICATION validator — methodology notations/elements/27-verification.md §5.
+//
+// Implements VERIF-001..006. The shared HDR-/LIFECYCLE- rules and the
+// cross-cutting REQ-VERIF-COVERAGE-001/002 reverse-trace rules are owned
+// elsewhere (CONTRACT.md §8) and are out of scope for this single-artefact
+// validator — same posture as `validateAssertion` (../assertion/validate.ts).
+//
+// Resolution rules (VERIF-002/005) that need artefact *existence* run only
+// when a `CanonCatalog` is supplied; the TYPE check VERIF-002 also carries is
+// derivable from the id prefix and runs either way.
+
+import type { ValidationError, ValidationWarning, ValidationResult } from '../validation-types.js';
+import { typeOfId, isCanonicalIdOfType, type CanonCatalog } from '../typed-id.js';
+import { VERIFICATION_METHODS, VERIFICATION_OUTCOMES } from './types.js';
+
+export interface VerificationValidateOptions {
+  /** When provided, the resolution rules enforce artefact existence. */
+  catalog?: CanonCatalog;
+}
+
+export function validateVerification(input: unknown, options: VerificationValidateOptions = {}): ValidationResult {
+  const errors: ValidationError[] = [];
+  const warnings: ValidationWarning[] = [];
+  const { catalog } = options;
+
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    errors.push({ code: 'VERIF-001', message: 'Verification must be a YAML mapping.' });
+    return { valid: false, errors, warnings };
+  }
+  const v = input as Record<string, unknown>;
+
+  // ── VERIF-001 — id grammar + plain required fields ───────────────────────
+  if (!isCanonicalIdOfType(v.id, 'VERIFICATION')) {
+    errors.push({ code: 'VERIF-001', message: `id "${String(v.id)}" must match VERIFICATION-[<middle>-]<INTEGER>.`, path: 'id' });
+  }
+  if (v.notation !== 'verification') {
+    errors.push({ code: 'VERIF-001', message: 'notation must be the fixed value "verification".', path: 'notation' });
+  }
+  if (v.zone !== 'canon') {
+    errors.push({ code: 'VERIF-001', message: 'zone is required and must be "canon".', path: 'zone' });
+  }
+  for (const f of ['admitted_at', 'admitted_by', 'valid_from', 'protocol'] as const) {
+    if (typeof v[f] !== 'string' || (v[f] as string).trim() === '') {
+      errors.push({ code: 'VERIF-001', message: `${f} is required.`, path: f });
+    }
+  }
+  if (v.gate_checks === null || typeof v.gate_checks !== 'object') {
+    errors.push({ code: 'VERIF-001', message: 'gate_checks is required and must be a mapping.', path: 'gate_checks' });
+  }
+  if (!('valid_to' in v) || !(typeof v.valid_to === 'string' || v.valid_to === null)) {
+    errors.push({ code: 'VERIF-001', message: 'valid_to is required (an ISO date string or null).', path: 'valid_to' });
+  }
+
+  // ── VERIF-002 — verifies → REQUIREMENT ───────────────────────────────────
+  const verifies = v.verifies;
+  if (typeof verifies !== 'string' || verifies.trim() === '') {
+    errors.push({ code: 'VERIF-002', message: 'verifies is required and must be a typed REQUIREMENT id.', path: 'verifies' });
+  } else if (catalog) {
+    const t = catalog.typeOf(verifies);
+    if (t === undefined) {
+      errors.push({ code: 'VERIF-002', message: `verifies "${verifies}" does not resolve to an admitted artefact.`, path: 'verifies' });
+    } else if (t !== 'REQUIREMENT') {
+      errors.push({ code: 'VERIF-002', message: `verifies "${verifies}" resolves to a ${t}, not a REQUIREMENT.`, path: 'verifies' });
+    }
+  } else if (typeOfId(verifies) !== 'REQUIREMENT') {
+    errors.push({ code: 'VERIF-002', message: `verifies "${verifies}" must be a REQUIREMENT typed id.`, path: 'verifies' });
+  }
+
+  // ── VERIF-003 — method enum ───────────────────────────────────────────────
+  const method = v.method;
+  if (method === undefined || method === null) {
+    errors.push({ code: 'VERIF-001', message: 'method is required.', path: 'method' });
+  } else if (!VERIFICATION_METHODS.includes(method as never)) {
+    errors.push({ code: 'VERIF-003', message: `method "${String(method)}" must be one of ${VERIFICATION_METHODS.join(', ')}.`, path: 'method' });
+  }
+
+  // ── VERIF-004 — outcome enum ──────────────────────────────────────────────
+  const outcome = v.outcome;
+  if (outcome === undefined || outcome === null) {
+    errors.push({ code: 'VERIF-001', message: 'outcome is required.', path: 'outcome' });
+  } else if (!VERIFICATION_OUTCOMES.includes(outcome as never)) {
+    errors.push({ code: 'VERIF-004', message: `outcome "${String(outcome)}" must be one of ${VERIFICATION_OUTCOMES.join(', ')}.`, path: 'outcome' });
+  }
+
+  // ── VERIF-005 — canonical_ref evidence resolves ──────────────────────────
+  if (v.evidence !== undefined) {
+    if (!Array.isArray(v.evidence)) {
+      errors.push({ code: 'VERIF-001', message: 'evidence must be a list.', path: 'evidence' });
+    } else {
+      v.evidence.forEach((e, i) => {
+        if (e === null || typeof e !== 'object') return;
+        const entry = e as Record<string, unknown>;
+        if (entry.kind !== 'canonical_ref') return;
+        const ref = entry.ref;
+        if (!typeOfId(ref)) {
+          errors.push({ code: 'VERIF-005', message: `evidence[${i}] canonical_ref "${String(ref)}" is not a resolvable typed ID.`, path: `evidence[${i}].ref` });
+        } else if (catalog && catalog.typeOf(ref as string) === undefined) {
+          errors.push({ code: 'VERIF-005', message: `evidence[${i}] canonical_ref "${String(ref)}" does not resolve.`, path: `evidence[${i}].ref` });
+        }
+      });
+    }
+  }
+
+  // ── VERIF-006 (warning) — pass outcome with no evidence ──────────────────
+  const evidenceEmpty = !Array.isArray(v.evidence) || v.evidence.length === 0;
+  if (evidenceEmpty && outcome === 'pass') {
+    warnings.push({ code: 'VERIF-006', message: 'outcome "pass" has no evidence — an undefended positive claim.', path: 'evidence' });
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}

package/src/versioned-attribute/index.ts

@@ -0,0 +1,4 @@
+export type { AttributeVersionEntry, VersionedAttributeSidecar } from './types.js';
+export { resolveAttributeValue, resolveAttributes, todayIso } from './resolve.js';
+export type { AttributeArrayFinding } from './validate.js';
+export { parseSidecar, validateAttributeArray, validateSidecar } from './validate.js';