@nebulacomponents/citable 1.18.0 → 1.18.2

package/src/shared/runPackageVerifier.js

@@ -0,0 +1,153 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson, sha256File } from './io.js';
+import { validateAgainst } from './schemaValidator.js';
+
+export class RunVerificationError extends Error {
+  constructor(message, details = {}) {
+    super(message);
+    this.name = 'RunVerificationError';
+    this.code = details.code || 'RUN_VERIFICATION_FAILED';
+    this.details = details;
+  }
+}
+
+/**
+ * Verifies the cryptographic and structural integrity of an audit run evidence package.
+ *
+ * Checks:
+ * 1. Existence of run directory and manifest.json
+ * 2. Manifest compliance with run.schema.json
+ * 3. Existence and validity of checksums.json
+ * 4. Exact sha256 hash match for all sealed artifacts in checksums.json
+ * 5. Run completion status (rejecting failed or partial runs in contractual contexts)
+ * 6. Findings structural validity
+ */
+export function verifyRunPackage(runDir, options = {}) {
+  const {
+    requireFindings = true,
+    requireCompleted = false,
+    requireChecksums = true,
+  } = options;
+
+  if (!runDir || !fs.existsSync(runDir)) {
+    throw new RunVerificationError(`Run directory not found: ${runDir}`, { code: 'RUN_NOT_FOUND', runDir });
+  }
+
+  const manifestPath = path.join(runDir, 'manifest.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw new RunVerificationError(`Run package is missing manifest.json at ${manifestPath}`, {
+      code: 'MANIFEST_MISSING',
+      runDir,
+    });
+  }
+
+  let manifest;
+  try {
+    manifest = readJson(manifestPath);
+  } catch (err) {
+    throw new RunVerificationError(`Run manifest.json is invalid JSON: ${err.message}`, {
+      code: 'MANIFEST_INVALID',
+      runDir,
+    });
+  }
+
+  const schemaValidation = validateAgainst('run.schema.json', manifest);
+  if (!schemaValidation.valid) {
+    throw new RunVerificationError(`Run manifest violates run.schema.json: ${schemaValidation.errors.join('; ')}`, {
+      code: 'MANIFEST_SCHEMA_INVALID',
+      errors: schemaValidation.errors,
+      runDir,
+    });
+  }
+
+  if (requireCompleted && manifest.status !== 'completed' && manifest.status !== 'success') {
+    throw new RunVerificationError(`Run status is "${manifest.status}"; expected completed/success`, {
+      code: 'RUN_INCOMPLETE',
+      status: manifest.status,
+      runDir,
+    });
+  }
+
+  // Verify checksums.json
+  const checksumsPath = path.join(runDir, 'checksums.json');
+  let checksumsVerified = false;
+  if (fs.existsSync(checksumsPath)) {
+    let checksums;
+    try {
+      checksums = readJson(checksumsPath);
+    } catch (err) {
+      throw new RunVerificationError(`checksums.json is invalid JSON: ${err.message}`, {
+        code: 'CHECKSUMS_INVALID',
+        runDir,
+      });
+    }
+
+    const tamperedFiles = [];
+    const missingFiles = [];
+
+    for (const [relPath, expectedHash] of Object.entries(checksums)) {
+      const artifactPath = path.join(runDir, relPath);
+      if (!fs.existsSync(artifactPath)) {
+        missingFiles.push(relPath);
+        continue;
+      }
+      const actualHash = sha256File(artifactPath);
+      if (actualHash !== expectedHash) {
+        tamperedFiles.push({ file: relPath, expected: expectedHash, actual: actualHash });
+      }
+    }
+
+    if (tamperedFiles.length > 0 || missingFiles.length > 0) {
+      throw new RunVerificationError(
+        `Cryptographic verification failed for run package: ${tamperedFiles.length} tampered files, ${missingFiles.length} missing files`,
+        {
+          code: 'CHECKSUM_MISMATCH',
+          tamperedFiles,
+          missingFiles,
+          runDir,
+        }
+      );
+    }
+    checksumsVerified = true;
+  } else if (requireChecksums) {
+    throw new RunVerificationError(`Run package is missing checksums.json at ${checksumsPath}`, {
+      code: 'CHECKSUMS_MISSING',
+      runDir,
+    });
+  }
+
+  // Findings verification if present or required
+  const findingsPath = path.join(runDir, 'findings.json');
+  let findings = null;
+  if (fs.existsSync(findingsPath)) {
+    try {
+      findings = readJson(findingsPath);
+      if (!Array.isArray(findings)) {
+        throw new Error('findings.json must contain an array of findings');
+      }
+    } catch (err) {
+      throw new RunVerificationError(`findings.json is malformed: ${err.message}`, {
+        code: 'FINDINGS_MALFORMED',
+        runDir,
+      });
+    }
+  } else if (requireFindings) {
+    throw new RunVerificationError(`Run package is missing findings.json at ${findingsPath}`, {
+      code: 'FINDINGS_MISSING',
+      runDir,
+    });
+  }
+
+  return {
+    valid: true,
+    runId: manifest.run_id,
+    timestamp: manifest.timestamp,
+    status: manifest.status,
+    manifest,
+    checksumsVerified,
+    findingsPath: fs.existsSync(findingsPath) ? findingsPath : null,
+    findingsCount: Array.isArray(findings) ? findings.length : 0,
+    findings,
+  };
+}

package/src/sow/admissibilityGate.js

@@ -1,5 +1,3 @@
-import { safePath } from '../detectors/framework.js';
-
 /**
  * Enterprise Scope Admissibility Gate
  *
@@ -7,32 +5,139 @@ import { safePath } from '../detectors/framework.js';
  * work packages, explicitly refusing findings that are exploratory, unverified,
  * economically unjustified, out of organizational boundary, or lack testable acceptance.
  */
+
+export const DEFAULT_ROLE_MAPPINGS = {
+  TECH: 'Supplier Engineering Lead',
+  TECHNICAL: 'Supplier Engineering Lead',
+  CRO: 'Supplier CRO Architect',
+  AEO: 'Supplier Discovery Specialist',
+  ANS: 'Supplier Discovery Specialist',
+  GEO: 'Supplier Discovery Specialist',
+  SCHEMA: 'Supplier Data Engineer',
+  ENTITY: 'Supplier Data Engineer',
+  SEO: 'Supplier Search Strategist',
+};
+
+/**
+ * Check whether a target subject falls within declared in-scope properties.
+ *
+ * Supported scope modes:
+ * - 'HOST_AND_SUBDOMAINS' (default): matches host and any subdomains
+ * - 'HOST': matches exact host only
+ * - 'EXACT_ORIGIN': matches exact scheme + host + port
+ * - 'PATH_PREFIX': matches host/subdomain and path prefix
+ * - 'EXACT_RESOURCE': matches exact host and path
+ */
+export function checkScopeBoundary(subject, inScopeProperties = [], scopeMode = 'HOST_AND_SUBDOMAINS') {
+  if (!inScopeProperties || inScopeProperties.length === 0) return true;
+  if (!subject) return false;
+
+  const subjectStr = typeof subject === 'string' ? subject : (subject.url || subject.identifier || '');
+  if (!subjectStr) return false;
+
+  const isRelative = !/^[a-zA-Z][a-zA-Z0-9+.-]*:\/\/|^\/\//.test(subjectStr);
+
+  for (const prop of inScopeProperties) {
+    let propUrl;
+    try {
+      propUrl = new URL(prop.includes('://') ? prop : `https://${prop}`);
+    } catch {
+      continue;
+    }
+    const propHost = propUrl.hostname.toLowerCase();
+    const propPath = propUrl.pathname.replace(/\/+$/, '');
+
+    if (isRelative) {
+      if (scopeMode === 'PATH_PREFIX') {
+        const normSubj = subjectStr.startsWith('/') ? subjectStr : `/${subjectStr}`;
+        if (normSubj.startsWith(propPath || '/')) return true;
+      } else if (scopeMode === 'EXACT_RESOURCE') {
+        const normSubj = subjectStr.startsWith('/') ? subjectStr : `/${subjectStr}`;
+        if (normSubj === (propPath || '/')) return true;
+      } else {
+        return true;
+      }
+      continue;
+    }
+
+    let subjUrl;
+    try {
+      subjUrl = new URL(subjectStr);
+    } catch {
+      continue;
+    }
+
+    const subjHost = subjUrl.hostname.toLowerCase();
+    const subjPath = subjUrl.pathname.replace(/\/+$/, '');
+
+    switch (scopeMode) {
+      case 'EXACT_ORIGIN':
+        if (subjUrl.origin.toLowerCase() === propUrl.origin.toLowerCase()) return true;
+        break;
+      case 'HOST':
+        if (subjHost === propHost) return true;
+        break;
+      case 'HOST_AND_SUBDOMAINS':
+        if (subjHost === propHost || subjHost.endsWith(`.${propHost}`)) return true;
+        break;
+      case 'PATH_PREFIX':
+        if ((subjHost === propHost || subjHost.endsWith(`.${propHost}`)) &&
+            (subjPath === propPath || subjPath.startsWith(`${propPath}/`))) return true;
+        break;
+      case 'EXACT_RESOURCE':
+        if (subjHost === propHost && subjPath === propPath) return true;
+        break;
+      default:
+        if (subjHost === propHost || subjHost.endsWith(`.${propHost}`)) return true;
+    }
+  }
+
+  return false;
+}
+
 export function evaluateScopeAdmissibility(findings = [], {
   inScopeProperties = [],
+  scopeMode = 'HOST_AND_SUBDOMAINS',
   minIceScore = 8.0,
   allowedDisciplines = ['seo', 'aeo', 'geo', 'technical', 'schema', 'entity', 'cro'],
   allowExperimental = false,
   excludedDetectors = [],
+  roleMapping = null,
+  ownerMappingVersion = '1.0',
+  rejectTemplateDefaultOwner = false,
 } = {}) {
   const admitted = [];
   const refused = [];
 
   let reqIndex = 1;
   let testIndex = 1;
+  const seenFindingIds = new Map();
 
   for (let i = 0; i < findings.length; i++) {
     const f = findings[i];
-    const detectorId = f.detector_id || `FINDING-${i + 1}`;
-    const subject = f.subject?.identifier || f.subject?.url || '/';
+    const subject = f.subject?.identifier || f.subject?.url || (typeof f.subject === 'string' ? f.subject : '/');
+    const detectorId = f.detector_id || (f.finding_id ? f.finding_id.replace(/^F-/, '') : `FINDING-${i + 1}`);
+
+    const rawFindingId = f.finding_id || f.id || f.detector_id || `FINDING-${i + 1}`;
+    let findingId = rawFindingId;
+    if (seenFindingIds.has(rawFindingId)) {
+      const count = seenFindingIds.get(rawFindingId) + 1;
+      seenFindingIds.set(rawFindingId, count);
+      findingId = `${rawFindingId}:${subject || count}`;
+    } else {
+      seenFindingIds.set(rawFindingId, 1);
+    }
+
     const severity = f.classification?.severity || 'medium';
     const confidence = f.classification?.confidence || 'observed';
     const evidenceList = f.observation?.evidence || [];
-    const remediation = f.remediation?.preferred || '';
+    const remediation = f.remediation?.preferred || (typeof f.remediation === 'string' ? f.remediation : '');
 
     // Gate 1: Excluded detectors / explicitly blacklisted checks
-    if (excludedDetectors.includes(detectorId)) {
+    if (excludedDetectors.includes(detectorId) || excludedDetectors.includes(findingId)) {
       refused.push({
-        finding_id: detectorId,
+        finding_id: findingId,
+        detector_id: detectorId,
         subject,
         gate_failed: 'excluded_detector',
         refusal_code: 'REFUSE-EXCLUDED',
@@ -45,7 +150,8 @@ export function evaluateScopeAdmissibility(findings = [], {
     // Gate 2: Evidence Maturity Gate
     if (!allowExperimental && (confidence === 'experimental' || f.classification?.finding_type === 'experimental')) {
       refused.push({
-        finding_id: detectorId,
+        finding_id: findingId,
+        detector_id: detectorId,
         subject,
         gate_failed: 'evidence_maturity',
         refusal_code: 'REFUSE-EXPERIMENTAL',
@@ -55,9 +161,10 @@ export function evaluateScopeAdmissibility(findings = [], {
       continue;
     }
 
-    if (evidenceList.length === 0) {
+    if (!Array.isArray(evidenceList) || evidenceList.length === 0) {
       refused.push({
-        finding_id: detectorId,
+        finding_id: findingId,
+        detector_id: detectorId,
         subject,
         gate_failed: 'evidence_maturity',
         refusal_code: 'REFUSE-NO-EVIDENCE',
@@ -67,17 +174,13 @@ export function evaluateScopeAdmissibility(findings = [], {
       continue;
     }
 
-    // Gate 3: Scope Boundary Gate
+    // Gate 4: Scope Boundary Gate
     if (inScopeProperties.length > 0) {
-      const isInScope = inScopeProperties.some((prop) => {
-        const pStem = prop.replace(/^https?:\/\//, '').replace(/\/+$/, '').toLowerCase();
-        const sStem = subject.replace(/^https?:\/\//, '').replace(/\/+$/, '').toLowerCase();
-        return sStem.includes(pStem) || pStem.includes(sStem);
-      });
-
-      if (!isInScope) {
+      const inScope = checkScopeBoundary(f.subject || subject, inScopeProperties, scopeMode);
+      if (!inScope) {
         refused.push({
-          finding_id: detectorId,
+          finding_id: findingId,
+          detector_id: detectorId,
           subject,
           gate_failed: 'scope_boundary',
           refusal_code: 'REFUSE-OUT-OF-SCOPE',
@@ -88,28 +191,30 @@ export function evaluateScopeAdmissibility(findings = [], {
       }
     }
 
-    // Gate 4: Technical Feasibility & Remediation Safety
-    if (!remediation || remediation.toLowerCase().includes('consult external legal') || remediation.toLowerCase().includes('out of scope')) {
+    // Gate 5: Technical Feasibility & Remediation Safety
+    const remLower = remediation.toLowerCase();
+    if (!remediation || remLower.includes('consult external legal') || remLower.includes('out of scope') || remLower.includes('unfeasible')) {
       refused.push({
-        finding_id: detectorId,
+        finding_id: findingId,
+        detector_id: detectorId,
         subject,
         gate_failed: 'technical_feasibility',
         refusal_code: 'REFUSE-UNFEASIBLE-REMEDIATION',
-        refusal_rationale: 'Finding requires external legal advice or lacks defined engineering remediation method.',
-        suggested_handling: 'Refer to customer legal counsel; exclude from engineering delivery.',
+        refusal_rationale: 'Finding requires external legal advice, lacks defined engineering remediation method, or is declared technically unfeasible.',
+        suggested_handling: 'Refer to customer legal counsel or appropriate third party; exclude from engineering delivery.',
       });
       continue;
     }
 
-    // Gate 5: Commercial Materiality & ICE-BV Gate
-    // High & critical severity are automatically material; medium/low must meet ICE threshold or be key conversion/vitals defects
-    const isCoreSeverity = ['critical', 'high'].includes(severity);
+    // Gate 6: Commercial Materiality & ICE-BV Gate
+    const isCoreSeverity = ['critical', 'high'].includes(severity.toLowerCase());
     const isVitalsOrFunnel = ['TECH-001', 'TECH-002', 'CRO-001', 'CRO-002', 'CRO-005', 'CRO-006', 'CRO-007', 'CRO-013', 'CRO-021', 'SCHEMA-001'].includes(detectorId);
-    const iceScore = f.ice_score || (isCoreSeverity ? 12 : 6);
+    const iceScore = typeof f.ice_score === 'number' ? f.ice_score : (isCoreSeverity ? 12 : 6);
 
     if (!isCoreSeverity && !isVitalsOrFunnel && iceScore < minIceScore) {
       refused.push({
-        finding_id: detectorId,
+        finding_id: findingId,
+        detector_id: detectorId,
         subject,
         gate_failed: 'commercial_materiality',
         refusal_code: 'REFUSE-LOW-MATERIALITY',
@@ -119,11 +224,17 @@ export function evaluateScopeAdmissibility(findings = [], {
       continue;
     }
 
-    // Gate 6: Objectively Testable Acceptance Gate
-    const rerunDetector = f.verification?.detector_to_rerun || detectorId;
-    if (!rerunDetector && !f.verification?.method) {
+    // Gate 7: Objectively Testable Acceptance Gate
+    const hasVerification = Boolean(
+      f.verification?.detector_to_rerun ||
+      f.verification?.method ||
+      f.verification?.acceptance_test
+    );
+
+    if (!hasVerification) {
       refused.push({
-        finding_id: detectorId,
+        finding_id: findingId,
+        detector_id: detectorId,
         subject,
         gate_failed: 'measurable_acceptance',
         refusal_code: 'REFUSE-UNVERIFIABLE',
@@ -133,36 +244,109 @@ export function evaluateScopeAdmissibility(findings = [], {
       continue;
     }
 
-    // Passed All 6 Gates -> Admitted to Contractual SOW Scope
-    const discipline = (f.discipline?.[0] || detectorId.split('-')[0] || 'TECH').toUpperCase();
+    // Gate 8: Ownership Clarity Gate
+    const effectiveRoles = { ...DEFAULT_ROLE_MAPPINGS, ...(roleMapping || {}) };
+    const disciplineKey = (f.discipline?.[0] || detectorId.split('-')[0] || 'TECH').toUpperCase();
+
+    let resolvedOwner = null;
+    let ownerSource = null;
+
+    if (f.delivery_owner && f.delivery_owner !== 'UNRESOLVED') {
+      resolvedOwner = f.delivery_owner;
+      ownerSource = 'finding.delivery_owner';
+    } else if (f.remediation?.owner && f.remediation.owner !== 'UNRESOLVED') {
+      resolvedOwner = f.remediation.owner;
+      ownerSource = 'finding.remediation.owner';
+    } else if (f.owner && f.owner !== 'UNRESOLVED') {
+      resolvedOwner = f.owner;
+      ownerSource = 'finding.owner';
+    } else if (roleMapping && (roleMapping[disciplineKey] || roleMapping[detectorId])) {
+      resolvedOwner = roleMapping[disciplineKey] || roleMapping[detectorId];
+      ownerSource = 'engagement_role_mapping';
+    } else if (effectiveRoles[disciplineKey] && effectiveRoles[disciplineKey] !== 'UNRESOLVED') {
+      resolvedOwner = effectiveRoles[disciplineKey];
+      ownerSource = 'built_in_template_default';
+    } else if (effectiveRoles[detectorId] && effectiveRoles[detectorId] !== 'UNRESOLVED') {
+      resolvedOwner = effectiveRoles[detectorId];
+      ownerSource = 'built_in_template_default';
+    }
+
+    if (!resolvedOwner || resolvedOwner === 'UNRESOLVED' || resolvedOwner.toLowerCase() === 'unassigned') {
+      refused.push({
+        finding_id: findingId,
+        detector_id: detectorId,
+        subject,
+        gate_failed: 'ownership_clarity',
+        refusal_code: 'REFUSE-OWNER-UNRESOLVED',
+        refusal_rationale: `Responsible delivery owner could not be resolved for finding ${findingId} (discipline: ${disciplineKey}).`,
+        suggested_handling: 'Specify delivery_owner on finding or map discipline to accountable delivery role in SOW configuration.',
+      });
+      continue;
+    }
+
+    if (rejectTemplateDefaultOwner && ownerSource === 'built_in_template_default') {
+      refused.push({
+        finding_id: findingId,
+        detector_id: detectorId,
+        subject,
+        gate_failed: 'ownership_clarity',
+        refusal_code: 'REFUSE-TEMPLATE-DEFAULT-OWNER',
+        refusal_rationale: `Responsible delivery owner for finding ${findingId} relies on built-in template default. Contractual SOW requires an explicit finding owner or engagement role mapping.`,
+        suggested_handling: 'Specify delivery_owner on finding or map discipline in engagement role mapping.',
+      });
+      continue;
+    }
+
+    // Gate 8b: Discipline Authorization Gate
+    const rawDisciplines = Array.isArray(f.discipline)
+      ? f.discipline
+      : (f.discipline ? [f.discipline] : [detectorId.split('-')[0]]);
+    const findingDisciplines = rawDisciplines.map((d) => String(d).toLowerCase());
+
+    if (allowedDisciplines && allowedDisciplines.length > 0) {
+      const normAllowed = allowedDisciplines.map((d) => String(d).toLowerCase());
+      const isAuthorized = findingDisciplines.some((d) => normAllowed.includes(d));
+      if (!isAuthorized) {
+        refused.push({
+          finding_id: findingId,
+          detector_id: detectorId,
+          subject,
+          gate_failed: 'discipline_authorization',
+          refusal_code: 'REFUSE-DISCIPLINE-NOT-AUTHORIZED',
+          refusal_rationale: `Discipline (${findingDisciplines.join(', ')}) is not authorized under contracted delivery disciplines (${allowedDisciplines.join(', ')}).`,
+          suggested_handling: 'Expand authorized disciplines in SOW engagement terms or contract under separate statement of work.',
+        });
+        continue;
+      }
+    }
+
+    // Passed all gates -> Admitted to Contractual SOW Scope
     let wpId = 'WP-TECH-01';
     let wpName = 'Technical Search & Performance Infrastructure';
     let deliverableId = 'DELIV-01';
-    let owner = 'Supplier Engineering Lead';
 
-    if (discipline === 'CRO' || detectorId.startsWith('CRO-')) {
+    if (disciplineKey === 'CRO' || detectorId.startsWith('CRO-')) {
       wpId = 'WP-CRO-02';
       wpName = 'Conversion Funnel & Offer Architecture Optimization';
       deliverableId = 'DELIV-02';
-      owner = 'Supplier CRO Architect';
-    } else if (discipline === 'AEO' || discipline === 'GEO' || discipline === 'ANS') {
+    } else if (disciplineKey === 'AEO' || disciplineKey === 'GEO' || disciplineKey === 'ANS') {
       wpId = 'WP-AEO-03';
       wpName = 'Answer-Engine (AEO) & Generative Search Extraction';
       deliverableId = 'DELIV-03';
-      owner = 'Supplier Discovery Specialist';
-    } else if (discipline === 'SCHEMA' || discipline === 'ENTITY') {
+    } else if (disciplineKey === 'SCHEMA' || disciplineKey === 'ENTITY') {
       wpId = 'WP-SCHEMA-04';
       wpName = 'Structured Data & Entity Knowledge Graph Architecture';
       deliverableId = 'DELIV-04';
-      owner = 'Supplier Data Engineer';
     }
 
     const sowReqId = `REQ-SOW-${String(reqIndex++).padStart(3, '0')}`;
     const accTestId = `ACC-TEST-${String(testIndex++).padStart(3, '0')}`;
-    const evidenceId = evidenceList[0] || `EVD-OBS-${detectorId}`;
+    const evidenceId = evidenceList[0];
+    const detectorToRerun = f.verification?.detector_to_rerun || detectorId;
 
     admitted.push({
-      finding_id: detectorId,
+      finding_id: findingId,
+      detector_id: detectorId,
       sow_requirement_id: sowReqId,
       work_package_id: wpId,
       work_package_name: wpName,
@@ -172,9 +356,13 @@ export function evaluateScopeAdmissibility(findings = [], {
       severity,
       confidence,
       recommendation: remediation,
-      acceptance_test: `Execute closed-loop verification: citable verify remediation --finding ${detectorId} --target ${subject} (Expect status: RESOLVED, zero regressions)`,
-      owner,
+      acceptance_test: f.verification?.acceptance_test || `Execute closed-loop verification: citable verify remediation --finding ${detectorToRerun} --target ${subject} (Expect status: RESOLVED, zero regressions)`,
+      acceptance_basis: f.verification?.method ? 'empirical_verification_method' : (f.verification?.detector_to_rerun ? 'automated_detector_rerun' : 'deterministic_remediation_test'),
+      owner: resolvedOwner,
+      owner_source: ownerSource,
+      owner_mapping_version: ownerMappingVersion,
       evidence_id: evidenceId,
+      evidence_ids: [...evidenceList],
       commercial_priority: isCoreSeverity ? 'P1_CRITICAL' : 'P2_HIGH_VALUE',
       ice_bv_score: iceScore,
     });