@transitrix/diagrams 1.8.21 → 1.9.18

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

package/dist/verification/types.d.ts

@@ -0,0 +1,31 @@
+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 declare const VERIFICATION_METHODS: readonly VerificationMethod[];
+/** Pass/fail judgement vocabulary (27-verification.md §3). */
+export type VerificationOutcome = 'pass' | 'fail' | 'inconclusive' | 'not_yet_run';
+export declare const VERIFICATION_OUTCOMES: readonly VerificationOutcome[];
+/** 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 declare const CLOSED_VERIFICATION_OUTCOMES: readonly VerificationOutcome[];
+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;
+    zone: 'canon';
+    admitted_at: string;
+    admitted_by: string;
+    gate_checks: GateChecks;
+    valid_from: string;
+    valid_to: string | null;
+}

package/dist/verification/types.js

@@ -0,0 +1,12 @@
+// VERIFICATION — engineering V&V claim against a REQUIREMENT.
+// Schema: methodology notations/elements/27-verification.md §2.
+export const VERIFICATION_METHODS = [
+    'test', 'analysis', 'inspection', 'demonstration',
+];
+export const VERIFICATION_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`)
+ *  (27-verification.md §5, REQ-VERIF-COVERAGE-002). */
+export const CLOSED_VERIFICATION_OUTCOMES = ['pass', 'fail'];

package/dist/verification/validate.d.ts

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

package/dist/verification/validate.js

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

package/dist/versioned-attribute/index.js

@@ -0,0 +1,2 @@
+export { resolveAttributeValue, resolveAttributes, todayIso } from './resolve.js';
+export { parseSidecar, validateAttributeArray, validateSidecar } from './validate.js';

package/dist/versioned-attribute/resolve.d.ts

@@ -0,0 +1,15 @@
+import type { AttributeVersionEntry, VersionedAttributeSidecar } from './types.js';
+/** Pick the entry with the largest `valid_from <= atDate`.
+ *  Returns `undefined` when no entry has taken effect yet as of `atDate`
+ *  (the attribute has not yet taken its first value — CONTRACT.md §9.2 rule
+ *  4). Returns `null` when the resolved entry is itself a gap marker
+ *  (`value: null` — attribute currently unset). */
+export declare function resolveAttributeValue(entries: AttributeVersionEntry[] | undefined, atDate: string): unknown;
+/** Resolve every attribute in a sidecar at `atDate`. An attribute with no
+ *  entry yet in effect is omitted from the result (equivalent to
+ *  `resolveAttributeValue` returning `undefined`) rather than reported as
+ *  `null`, which is reserved for an explicit gap marker. */
+export declare function resolveAttributes(sidecar: VersionedAttributeSidecar | null | undefined, atDate: string): Record<string, unknown>;
+/** Today, as a quoted-ISO-8601 date string — the default projection date
+ *  every resolver/renderer falls back to when the caller supplies none. */
+export declare function todayIso(): string;

package/dist/versioned-attribute/resolve.js

@@ -0,0 +1,37 @@
+// Current-value resolution for a versioned attribute — CONTRACT.md §9.2.
+/** Pick the entry with the largest `valid_from <= atDate`.
+ *  Returns `undefined` when no entry has taken effect yet as of `atDate`
+ *  (the attribute has not yet taken its first value — CONTRACT.md §9.2 rule
+ *  4). Returns `null` when the resolved entry is itself a gap marker
+ *  (`value: null` — attribute currently unset). */
+export function resolveAttributeValue(entries, atDate) {
+    if (!entries || entries.length === 0)
+        return undefined;
+    let best;
+    for (const entry of entries) {
+        if (entry.valid_from <= atDate && (!best || entry.valid_from > best.valid_from)) {
+            best = entry;
+        }
+    }
+    return best ? best.value : undefined;
+}
+/** Resolve every attribute in a sidecar at `atDate`. An attribute with no
+ *  entry yet in effect is omitted from the result (equivalent to
+ *  `resolveAttributeValue` returning `undefined`) rather than reported as
+ *  `null`, which is reserved for an explicit gap marker. */
+export function resolveAttributes(sidecar, atDate) {
+    const out = {};
+    if (!sidecar)
+        return out;
+    for (const name of Object.keys(sidecar.attribute_versions)) {
+        const value = resolveAttributeValue(sidecar.attribute_versions[name], atDate);
+        if (value !== undefined)
+            out[name] = value;
+    }
+    return out;
+}
+/** Today, as a quoted-ISO-8601 date string — the default projection date
+ *  every resolver/renderer falls back to when the caller supplies none. */
+export function todayIso() {
+    return new Date().toISOString().slice(0, 10);
+}