@transitrix/diagrams 1.8.21 → 1.10.0

package/dist/repo-validate/check-versioned-attributes.js

@@ -0,0 +1,105 @@
+// Versioned-attribute sidecar checks (CONTRACT.md §9) — `VERSIONED-001..005`.
+//
+// A sidecar is any doc under `canon/elements/**` shaped like one (`target` +
+// `attribute_versions`, no `id` — same "no id -> not an element" convention
+// `docId` already uses to skip these docs everywhere else in this file's
+// sibling checks). Both halves of §9.3 live here:
+//   - VERSIONED-001 — a sidecar's `target` must resolve to an admitted
+//     primitive in this same model.
+//   - VERSIONED-002/003/005 — the sidecar's own array shape, delegated to
+//     the shared `../versioned-attribute` module (needs VERSIONED-005's
+//     bound: the target's own `valid_from`/`valid_to`, read from the
+//     resolved target doc).
+//   - VERSIONED-004 — a field declared `time_varying` present inline on its
+//     primitive, instead of only in the sidecar.
+//
+// `TIME_VARYING_FIELDS` is deliberately narrower than the full candidate
+// list in CONTRACT.md §9.4: it only enforces fields already `time_varying`
+// on methodology's *currently-merged* notation specs. `capability` covers
+// `current_maturity`, `target_maturity`, `owner_role`, `target_date` per
+// `05-capability-map.md` §13/§14. Applications-catalogue `maturity` (and its
+// sibling `owner_role`/`vendor`) is on the same 2026-08-02 maturity ADR but
+// is not enforced here yet — it lives on the `applications[]` list inside a
+// catalogue view document, not on a standalone element primitive, and this
+// check only walks `elements`.
+import { parseSidecar, validateSidecar } from '../versioned-attribute/index.js';
+import { docId } from './validate-repo.js';
+const PScope = 'repo';
+const TIME_VARYING_FIELDS = {
+    capability: ['current_maturity', 'target_maturity', 'owner_role', 'target_date'],
+};
+function readString(data, key) {
+    const v = data[key];
+    return typeof v === 'string' && v.length > 0 ? v : undefined;
+}
+/** VERSIONED-004 — a time_varying field present inline on its primitive. */
+function checkInlineTimeVarying(elements, findings) {
+    for (const doc of elements) {
+        if (!doc.data)
+            continue;
+        const id = docId(doc);
+        if (!id)
+            continue; // sidecars carry no id — not a primitive
+        const notation = doc.data['notation'];
+        if (typeof notation !== 'string')
+            continue;
+        const fields = TIME_VARYING_FIELDS[notation];
+        if (!fields)
+            continue;
+        for (const field of fields) {
+            if (doc.data[field] !== undefined) {
+                findings.push({
+                    scope: PScope,
+                    id,
+                    ruleId: 'VERSIONED-004',
+                    message: `VERSIONED-004: '${id}' declares '${field}' inline; it is time_varying and belongs in ` +
+                        `the sidecar '${id}.history.yaml' (CONTRACT.md §9), not on the primitive.`,
+                });
+            }
+        }
+    }
+}
+/** VERSIONED-001/002/003/005 — every sidecar doc found under `canon/elements/**`. */
+function checkSidecars(elements, findings) {
+    const elementById = new Map();
+    for (const doc of elements) {
+        const id = docId(doc);
+        if (id)
+            elementById.set(id, doc);
+    }
+    for (const doc of elements) {
+        if (!doc.data || docId(doc))
+            continue; // sidecars have no id
+        const sidecar = parseSidecar(doc.data);
+        if (!sidecar)
+            continue; // not shaped like a sidecar — ignore, same as docId's element/non-element split
+        const targetDoc = elementById.get(sidecar.target);
+        if (!targetDoc) {
+            findings.push({
+                scope: PScope,
+                id: sidecar.target,
+                ruleId: 'VERSIONED-001',
+                message: `VERSIONED-001: sidecar '${doc.path}' target '${sidecar.target}' does not resolve to an admitted primitive.`,
+            });
+            continue;
+        }
+        const targetValidFrom = targetDoc.data ? readString(targetDoc.data, 'valid_from') : undefined;
+        const validToRaw = targetDoc.data?.['valid_to'];
+        const targetValidTo = validToRaw === null ? null : typeof validToRaw === 'string' ? validToRaw : undefined;
+        for (const f of validateSidecar(sidecar, targetValidFrom, targetValidTo)) {
+            findings.push({
+                scope: PScope,
+                id: sidecar.target,
+                ruleId: f.code,
+                severity: f.severity,
+                message: `${f.code}: sidecar '${doc.path}' ${f.message}`,
+            });
+        }
+    }
+}
+/** Run the versioned-attribute sidecar checks (VERSIONED-001..005) over the
+ *  loaded element set and append findings. Pure, deterministic order. */
+export function checkVersionedAttributes(input, findings) {
+    checkInlineTimeVarying(input.elements, findings);
+    checkSidecars(input.elements, findings);
+}

package/dist/repo-validate/validate-repo.js

@@ -28,6 +28,8 @@
 // deferred per the ADR.
 import { checkStrategyChainSemantics } from './check-strategy-chain.js';
 import { checkElementHygiene } from './check-element-hygiene.js';
+import { checkVersionedAttributes } from './check-versioned-attributes.js';
+import { checkCandidateFields } from './check-candidate-fields.js';
 const PScope = 'repo';
 /** Statuses that, per lint.py's policy check, require an owner. */
 const OWNER_REQUIRED_STATUSES = new Set(['Active', 'Production']);
@@ -412,5 +414,10 @@ export function validateRepoModel(input) {
     // Phase 8 — standalone-element envelope rules ported from DSM's Go
     // Validate*Element functions (GOAL-ELEM-001..003, ACTION-001/002/005).
     checkElementHygiene(input, findings);
+    // Phase 9 — versioned-attribute sidecar rules (CONTRACT.md §9, VERSIONED-001..005).
+    checkVersionedAttributes(input, findings);
+    // Phase 10 — candidate-only fields on admitted canon (ELEMENT_PRIMITIVES.md
+    // §7.29, ADMIT-009).
+    checkCandidateFields(input, findings);
     return findings;
 }

package/dist/requirement/index.d.ts

@@ -1,4 +1,4 @@
-export type { Requirement, RequirementSeverity, GateChecks } from './types.js';
-export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+export type { Requirement, RequirementSeverity, RequirementLevel, RequirementKind, GateChecks } from './types.js';
+export { REQUIREMENT_DERIVED_FROM_TYPES, REQUIREMENT_LEVELS, REQUIREMENT_KINDS } from './types.js';
 export { validateRequirement } from './validate.js';
 export type { RequirementValidateOptions } from './validate.js';

package/dist/requirement/index.js

@@ -1,2 +1,2 @@
-export { REQUIREMENT_DERIVED_FROM_TYPES } from './types.js';
+export { REQUIREMENT_DERIVED_FROM_TYPES, REQUIREMENT_LEVELS, REQUIREMENT_KINDS } from './types.js';
 export { validateRequirement } from './validate.js';

package/dist/requirement/types.d.ts

@@ -1,3 +1,4 @@
+import type { AgreementValue } from '../agreement.js';
 export type RequirementSeverity = 'high' | 'medium' | 'low';
 /** Standard canon admission gate checks (CONTRACT.md §6). */
 export interface GateChecks {
@@ -6,7 +7,13 @@ export interface GateChecks {
     completeness?: string;
 }
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
-export declare const REQUIREMENT_DERIVED_FROM_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD"];
+export declare const REQUIREMENT_DERIVED_FROM_TYPES: readonly ["LAW", "REGULATION", "POLICY", "INTERNAL_STANDARD", "PRINCIPLE"];
+/** ISO/IEC/IEEE 29148 specification-tier ladder (15-requirement.md §2.5, REQ-005). */
+export type RequirementLevel = 'stakeholder' | 'system' | 'software';
+export declare const REQUIREMENT_LEVELS: readonly RequirementLevel[];
+/** Functional vs quality classification (15-requirement.md §2.6, REQ-006). */
+export type RequirementKind = 'functional' | 'quality';
+export declare const REQUIREMENT_KINDS: readonly RequirementKind[];
 export interface Requirement {
     notation: 'requirement';
     id: string;
@@ -14,8 +21,19 @@ 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;
+    /** `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;
     zone: 'canon';
     admitted_at: string;
     admitted_by: string;

package/dist/requirement/types.js

@@ -1,4 +1,6 @@
 // REQUIREMENT — motivation-layer positive obligation.
 // Schema: methodology notations/elements/15-requirement.md §2.
 /** TYPEs a requirement may be derived from (15-requirement.md §2, REQ-003). */
-export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD'];
+export const REQUIREMENT_DERIVED_FROM_TYPES = ['LAW', 'REGULATION', 'POLICY', 'INTERNAL_STANDARD', 'PRINCIPLE'];
+export const REQUIREMENT_LEVELS = ['stakeholder', 'system', 'software'];
+export const REQUIREMENT_KINDS = ['functional', 'quality'];

package/dist/requirement/validate.js

@@ -9,7 +9,8 @@
 // supplied; the TYPE check (REQ-003) is derivable from the id prefix and runs
 // either way.
 import { typeOfId, isCanonicalIdOfType } 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';
 const REQUIRED_FIELDS = [
     'notation', 'name', 'description', 'zone', 'admitted_at', 'admitted_by', 'gate_checks', 'valid_from',
 ];
@@ -77,5 +78,25 @@ export function validateRequirement(input, options = {}) {
             });
         }
     }
+    // REQ-005 — level closed vocabulary (optional; only checked when present).
+    if (r.level !== undefined && !REQUIREMENT_LEVELS.includes(r.level)) {
+        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.includes(r.kind)) {
+        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/dist/risk/index.d.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/dist/risk/index.js

@@ -0,0 +1,2 @@
+export { RISK_LEVELS } from './types.js';
+export { validateRisk } from './validate.js';

package/dist/risk/types.d.ts

@@ -0,0 +1,25 @@
+import type { GateChecks } from '../requirement/types.js';
+/** Likelihood / impact / residual severity vocabulary (§7.26). */
+export type RiskLevel = 'low' | 'medium' | 'high';
+export declare const RISK_LEVELS: readonly RiskLevel[];
+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;
+    zone: 'canon';
+    admitted_at: string;
+    admitted_by: string;
+    gate_checks: GateChecks;
+    valid_from: string;
+    valid_to: string | null;
+}

package/dist/risk/types.js

@@ -0,0 +1,3 @@
+// RISK — motivation-layer projected event (no ArchiMate counterpart).
+// Schema: methodology notations/ELEMENT_PRIMITIVES.md §7.26.
+export const RISK_LEVELS = ['low', 'medium', 'high'];

package/dist/risk/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidationResult } from '../validation-types.js';
+import { type CanonCatalog } from '../typed-id.js';
+export interface RiskValidateOptions {
+    /** When provided, RISK-003/004 enforce artefact existence for cross-refs. */
+    catalog?: CanonCatalog;
+}
+export declare function validateRisk(input: unknown, options?: RiskValidateOptions): ValidationResult;

package/dist/risk/validate.js

@@ -0,0 +1,108 @@
+// 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 { typeOfId, isCanonicalIdOfType } from '../typed-id.js';
+import { RISK_LEVELS } from './types.js';
+const TREATED_BY_TYPES = ['REQUIREMENT', 'CONSTRAINT'];
+export function validateRisk(input, options = {}) {
+    const errors = [];
+    const warnings = [];
+    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;
+    // 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']) {
+        if (typeof r[f] !== 'string' || r[f].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']) {
+        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.includes(v)) {
+            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) === 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.includes(type)) {
+                    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) === 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/dist/schema-version.d.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 declare const SCHEMA_VERSION = "0.5.0";
+export declare const SCHEMA_VERSION = "3.1.0";

package/dist/schema-version.js

@@ -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/dist/theme/themes.js

@@ -99,7 +99,7 @@ function shellCss() {
     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
@@ -162,7 +162,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});}`;
 }
 /**
  * Generates a self-contained CSS block for embedding inside a standalone SVG file.

package/dist/validation/index.d.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/dist/validation/index.js

@@ -0,0 +1,2 @@
+export { VALIDATION_METHODS, VALIDATION_OUTCOMES, CLOSED_VALIDATION_OUTCOMES } from './types.js';
+export { validateValidation } from './validate.js';

package/dist/validation/types.d.ts

@@ -0,0 +1,31 @@
+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 declare const VALIDATION_METHODS: readonly ValidationMethod[];
+/** Pass/fail judgement vocabulary (28-validation.md §3). */
+export type ValidationOutcome = 'pass' | 'fail' | 'inconclusive' | 'not_yet_run';
+export declare const VALIDATION_OUTCOMES: readonly ValidationOutcome[];
+/** 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 declare const CLOSED_VALIDATION_OUTCOMES: readonly ValidationOutcome[];
+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;
+    zone: 'canon';
+    admitted_at: string;
+    admitted_by: string;
+    gate_checks: GateChecks;
+    valid_from: string;
+    valid_to: string | null;
+}

package/dist/validation/types.js

@@ -0,0 +1,21 @@
+// 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).
+export const VALIDATION_METHODS = [
+    'user_acceptance',
+    'field_trial',
+    'stakeholder_review',
+    'usability_study',
+];
+export const VALIDATION_OUTCOMES = [
+    '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 = ['pass', 'fail'];

package/dist/validation/validate.d.ts

@@ -0,0 +1,7 @@
+import type { ValidationResult } from '../validation-types.js';
+import { type CanonCatalog } from '../typed-id.js';
+export interface ValidationValidateOptions {
+    /** When provided, the resolution rules enforce artefact existence. */
+    catalog?: CanonCatalog;
+}
+export declare function validateValidation(input: unknown, options?: ValidationValidateOptions): ValidationResult;

package/dist/validation/validate.js

@@ -0,0 +1,106 @@
+// 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 { typeOfId, isCanonicalIdOfType } from '../typed-id.js';
+import { VALIDATION_METHODS, VALIDATION_OUTCOMES } from './types.js';
+export function validateValidation(input, options = {}) {
+    const errors = [];
+    const warnings = [];
+    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;
+    // ── 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']) {
+        if (typeof v[f] !== 'string' || v[f].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)) {
+        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)) {
+        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;
+                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) === 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/dist/verification/index.d.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/dist/verification/index.js

@@ -0,0 +1,2 @@
+export { VERIFICATION_METHODS, VERIFICATION_OUTCOMES, CLOSED_VERIFICATION_OUTCOMES } from './types.js';
+export { validateVerification } from './validate.js';