@hex-di/guard-validation

GxP validation protocols (IQ/OQ/PQ) and traceability matrix generation for @hex-di/guard. Provides programmatic qualification runners that produce structured evidence for regulated environments.

Features

• Installation Qualification (IQ) -- verifies package installation, Node.js version, subpath exports, and peer dependencies
• Operational Qualification (OQ) -- verifies policy evaluation correctness, API export presence, error types, and mutation score thresholds
• Performance Qualification (PQ) -- benchmarks evaluation latency (p50/p95/p99), memory overhead, and concurrent evaluation determinism
• Traceability matrix -- maps requirements to source modules, test files, and coverage status with filtering support
• Structured evidence -- every protocol returns typed ValidationResult with step-by-step evidence and failure details

Background

In GxP-regulated environments (pharmaceutical, biotech, medical devices), computerized systems must be validated through a qualification lifecycle:

| Protocol | Purpose | | ----------------------------------- | ----------------------------------------------------------------------------- | | IQ (Installation Qualification) | Confirms the software is installed correctly and all dependencies are present | | OQ (Operational Qualification) | Confirms the software operates correctly under expected conditions | | PQ (Performance Qualification) | Confirms the software performs reliably under realistic workloads |

These protocols produce auditable evidence for regulatory compliance (FDA 21 CFR Part 11, EU GMP Annex 11, GAMP 5).

Installation

pnpm add @hex-di/guard-validation

Dependencies: @hex-di/guard

Quick Start

import { runIQ, runOQ, runPQ, generateTraceabilityMatrix } from "@hex-di/guard-validation";

// Run all three qualification protocols
const iq = runIQ({ packageName: "@hex-di/guard" });
const oq = runOQ({ mutationScore: 92, totalTestsPassed: 150 });
const pq = runPQ({ maxP99LatencyMs: 10 });

console.log(`IQ: ${iq.passed ? "PASS" : "FAIL"} (${iq.steps.length} steps)`);
console.log(`OQ: ${oq.passed ? "PASS" : "FAIL"} (${oq.steps.length} steps)`);
console.log(`PQ: ${pq.passed ? "PASS" : "FAIL"} (${pq.steps.length} steps)`);

// Generate traceability matrix
const matrix = generateTraceabilityMatrix();
console.log(`${matrix.coveragePercent}% of requirements covered`);

Installation Qualification (IQ)

Verifies that @hex-di/guard is installed correctly and the environment meets requirements.

import { runIQ } from "@hex-di/guard-validation";

const result = runIQ({
  packageName: "@hex-di/guard",
  minNodeVersion: "18.0.0",
  expectedExports: ["."],
});

// result.passed — overall pass/fail
// result.steps — individual verification steps with evidence
// result.evidence — IQEvidence with package/version details
// result.failedSteps — only the steps that failed

Verification steps: package name resolution, Node.js version check, core module importability, subpath exports verification, peer dependency presence.

Operational Qualification (OQ)

Verifies that the guard system operates correctly under expected conditions.

import { runOQ } from "@hex-di/guard-validation";

const result = runOQ({
  mutationScore: 92,
  mutationScoreThreshold: 80,
  totalTestsPassed: 150,
  totalTestsFailed: 0,
  expectedTestCount: 150,
  verifiedDodItems: ["DoD-001", "DoD-002"],
});

// result.evidence — OQEvidence with test counts and mutation score

Verification steps: policy evaluation correctness (allow and deny), API export presence, signature export accessibility, error type availability, mutation score threshold, DoD item verification, test count completeness.

Performance Qualification (PQ)

Benchmarks the guard system under realistic workloads.

import { runPQ } from "@hex-di/guard-validation";

const result = runPQ({
  maxP95LatencyMs: 5,
  maxP99LatencyMs: 10,
  benchmarkIterations: 1000,
  integrationTestsPassed: true,
});

// result.evidence.evaluationLatency — { p50, p95, p99 } in ms
// result.evidence.memoryOverheadBytes — heap overhead for 100 policies

Verification steps: p95/p99 latency thresholds, memory overhead for policy objects, integration test status, concurrent evaluation determinism.

Traceability Matrix

Maps requirements to source modules, test files, and coverage status. Supports filtering by requirement pattern and test type.

import { generateTraceabilityMatrix } from "@hex-di/guard-validation";

// Full matrix
const matrix = generateTraceabilityMatrix();

// Filter by requirement pattern
const guardOnly = generateTraceabilityMatrix({
  requirementPattern: "REQ-GUARD-.*",
});

// Filter by test type
const gxpTests = generateTraceabilityMatrix({
  testTypes: ["gxp"],
});

// Inspect the matrix
for (const row of matrix.rows) {
  console.log(`${row.requirementId}: ${row.status} (${row.testType})`);
}

API Reference

Protocol Runners

| Export | Kind | Description | | ----------------- | -------- | --------------------------------------- | | runIQ(options) | function | Run Installation Qualification protocol | | runOQ(options?) | function | Run Operational Qualification protocol | | runPQ(options?) | function | Run Performance Qualification protocol |

Traceability

| Export | Kind | Description | | -------------------------------------- | -------- | ------------------------------------------- | | generateTraceabilityMatrix(options?) | function | Generate a requirements traceability matrix |

Types

| Export | Kind | Description | | ---------------------- | ---- | --------------------------------------------------- | | ValidationStepResult | type | Result of a single qualification step | | ValidationResult | type | Complete result with steps, evidence, and timestamp | | IQEvidence | type | Evidence from Installation Qualification | | IQResult | type | ValidationResult<IQEvidence> | | OQEvidence | type | Evidence from Operational Qualification | | OQResult | type | ValidationResult<OQEvidence> | | PQEvidence | type | Evidence from Performance Qualification | | PQResult | type | ValidationResult<PQEvidence> | | TraceabilityRow | type | A single row in the traceability matrix | | TraceabilityMatrix | type | Complete traceability matrix report | | TraceabilityOptions | type | Filtering options for matrix generation | | IQOptions | type | Options for runIQ() | | OQOptions | type | Options for runOQ() | | PQOptions | type | Options for runPQ() |

Related Packages

| Package | Description | | ----------------------- | ------------------------------------------------------------- | | @hex-di/guard | Core guard library: permissions, roles, policies, evaluation | | @hex-di/guard-testing | Test utilities: memory adapters, fixtures, conformance suites | | @hex-di/guard-react | React integration: SubjectProvider, Can/Cannot, hooks |

License

MIT