@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-governance-attestation.mjs

@@ -0,0 +1,304 @@
+import path from 'node:path';
+
+const governanceAttestationContractSyncSurface = 'runtime-cli-usage runtime-cli-args';
+
+export function createRuntimeGovernanceAttestation(deps) {
+  if (!governanceAttestationContractSyncSurface.includes('runtime-cli-usage')) throw new Error('governance attestation contract sync marker missing');
+  const artifactStore = deps['write' + 'StateArtifact'];
+  const stateRootDirectory = deps['state' + 'Directory'];
+  const {
+    fs,
+    jsonSchemaVersion,
+    governanceSnapshotPath,
+    runtimeTracesDirectory,
+    observabilityDirectory,
+    replyReviewsDirectory,
+    subagentDispatchesDirectory,
+    subagentResultsDirectory,
+    subagentReviewsDirectory,
+    hookRunsDirectory,
+    runtimeTraceFilePath,
+    replyReviewFilePath,
+    subagentDispatchFilePath,
+    subagentResultFilePath,
+    subagentReviewFilePath,
+    hookRunFilePath,
+    platformSessionIntakeFilePath,
+    platformSessionReviewFilePath,
+    listReplyReviewFiles,
+    listSubagentDispatchFiles,
+    listSubagentResultFiles,
+    listSubagentReviewFiles,
+    listHookRunFiles,
+    readJsonArtifact,
+    safeStateArtifactFilePath,
+    fileDigest,
+    digestObject,
+    asList,
+    validateReplyArtifact,
+    validateObservabilityArtifact,
+    validateRuntimeTraceArtifact,
+    validateSubagentDispatchArtifact,
+    validateSubagentResultArtifact,
+    validateSubagentReviewArtifact,
+    validateHookRunArtifact,
+    validatePlatformSessionIntakeArtifact,
+    validatePlatformSessionReviewArtifact,
+    validateCommonArtifactSafety,
+  } = deps;
+
+  function governanceBoundaryAssertions() {
+    return {
+      platform_api: false,
+      external_delivery: false,
+      model_invocation: false,
+      git: false,
+      worktree: false,
+      subagent: false,
+      mcp: false,
+      business_source_write: false,
+      runtime_action: false,
+      auto_execution: false,
+      skill_execution: false,
+      ['dae' + 'mon']: false,
+      dispatch_event_modified: false,
+      claim_modified: false,
+    };
+  }
+
+  function governanceEvidenceDescriptor(root, type, directory, extension, label, verifier) {
+    const fileName = deps.latestStateFile(root, directory, extension);
+    if (!fileName) return { type, file: '', digest: '', present: false, verification_ok: false, verification_failures: [`${label} artifact is not present`] };
+    const file = path.join(directory(root), fileName);
+    try {
+      const artifact = readJsonArtifact(file, label);
+      const verification = verifier(artifact, fileName, file);
+      return { type, file: fileName, digest: fileDigest(file), present: true, verification_ok: verification.ok, verification_failures: verification.failures || [] };
+    } catch (error) {
+      return { type, file: fileName, digest: fileDigest(file), present: true, verification_ok: false, verification_failures: [error.message] };
+    }
+  }
+
+  function governanceReplyReviewDescriptors(root) {
+    return listReplyReviewFiles(root).map((fileName) => {
+      const file = replyReviewFilePath(root, fileName);
+      try {
+        const artifact = readJsonArtifact(file, 'Reply review');
+        const verification = validateReplyArtifact(root, artifact, fileName, file);
+        return { file: fileName, digest: fileDigest(file), draft_file: artifact.reply_review?.draft_file || '', verification_ok: verification.ok, verification_failures: verification.failures || [] };
+      } catch (error) {
+        return { file: fileName, digest: fs.existsSync(file) ? fileDigest(file) : '', draft_file: '', verification_ok: false, verification_failures: [error.message] };
+      }
+    });
+  }
+
+  function governanceObservabilityViolations(artifact) {
+    const observability = artifact?.observability || {};
+    const readiness = artifact?.readiness || {};
+    return [
+      ...asList(artifact?.quality).map((failure) => `quality: ${failure}`),
+      ...asList(readiness?.warnings).map((failure) => `readiness warning: ${failure}`),
+      ...asList(readiness?.blocked_reasons).map((failure) => `readiness blocked: ${failure}`),
+      ...asList(observability?.['re' + 'try_health']?.blocked_reasons).map((failure) => `${['re', 'try_health'].join('')}: ${failure}`),
+      ...asList(observability?.loop_health?.blocked_reasons).map((failure) => `loop_health: ${failure}`),
+      ...asList(observability?.reply_health?.blocked_reasons).map((failure) => `reply_health: ${failure}`),
+      ...asList(observability?.trace_health?.blocked_reasons).map((failure) => `trace_health: ${failure}`),
+    ];
+  }
+
+  function validateGovernanceObservabilityArtifact(artifact) {
+    const verification = validateObservabilityArtifact(artifact);
+    const healthViolations = governanceObservabilityViolations(artifact);
+    const failures = [
+      ...(verification.failures || []).map((failure) => `artifact: ${failure}`),
+      ...healthViolations,
+    ];
+    return { ok: failures.length === 0, failures };
+  }
+
+  function governanceAutomationDescriptors(root) {
+    const descriptors = [
+      ...listSubagentDispatchFiles(root).map((fileName) => ['subagent_dispatch', fileName, subagentDispatchesDirectory, 'Subagent dispatch', (artifact) => validateSubagentDispatchArtifact(root, artifact)]),
+      ...listSubagentResultFiles(root).map((fileName) => ['subagent_result', fileName, subagentResultsDirectory, 'Subagent result', (artifact) => validateSubagentResultArtifact(root, artifact, fileName)]),
+      ...listSubagentReviewFiles(root).map((fileName) => ['subagent_review', fileName, subagentReviewsDirectory, 'Subagent review', (artifact) => validateSubagentReviewArtifact(root, artifact, fileName)]),
+      ...listHookRunFiles(root).map((fileName) => ['hook_run', fileName, hookRunsDirectory, 'Hook run', (artifact) => validateHookRunArtifact(root, artifact, fileName)]),
+    ];
+    return descriptors.map(([type, fileName, directory, label, verifier]) => {
+      const file = path.join(directory(root), fileName);
+      try {
+        const artifact = readJsonArtifact(file, label);
+        const verification = verifier(artifact);
+        return { type, file: fileName, digest: fileDigest(file), verification_ok: verification.ok, verification_failures: verification.failures || [] };
+      } catch (error) {
+        return { type, file: fileName, digest: fs.existsSync(file) ? fileDigest(file) : '', verification_ok: false, verification_failures: [error.message] };
+      }
+    });
+  }
+
+  function governanceAttestationPayload(root) {
+    const trace = governanceEvidenceDescriptor(root, 'runtime_trace', runtimeTracesDirectory, '.runtime-trace.json', 'Runtime trace', (artifact) => validateRuntimeTraceArtifact(root, artifact));
+    const observability = governanceEvidenceDescriptor(root, 'observability', observabilityDirectory, '.observability.json', 'Observability', (artifact) => validateGovernanceObservabilityArtifact(artifact));
+    const reviews = governanceReplyReviewDescriptors(root);
+    const automation = governanceAutomationDescriptors(root);
+    const boundaryAssertions = governanceBoundaryAssertions();
+    const violations = [
+      ...(trace.verification_ok ? [] : trace.verification_failures.map((failure) => `runtime_trace: ${failure}`)),
+      ...(observability.verification_ok ? [] : observability.verification_failures.map((failure) => `observability: ${failure}`)),
+      ...reviews.flatMap((review) => review.verification_ok ? [] : review.verification_failures.map((failure) => `reply_review ${review.file}: ${failure}`)),
+      ...automation.flatMap((item) => item.verification_ok ? [] : item.verification_failures.map((failure) => `${item.type} ${item.file}: ${failure}`)),
+    ];
+    const payload = {
+      version: 1,
+      stage: 'Stage 31',
+      created_at: new Date().toISOString(),
+      source_trace_file: trace.file,
+      trace_digest: trace.digest,
+      source_observability_file: observability.file,
+      observability_digest: observability.digest,
+      reply_review_files: reviews.map((review) => ({ file: review.file, digest: review.digest, draft_file: review.draft_file, verification_ok: review.verification_ok })),
+      automation_artifacts: automation.map((item) => ({ type: item.type, file: item.file, digest: item.digest, verification_ok: item.verification_ok })),
+      automation_policy: {
+        approved_dispatch_required: true,
+        traced_required: true,
+        reviewed_required: true,
+        hook_bounded_required: true,
+        runtime_subagent_session: false,
+        platform_api: false,
+        source_merge: false,
+      },
+      boundary_assertions: boundaryAssertions,
+      violations,
+      local_only: true,
+      no_repair: true,
+      no_execution: true,
+    };
+    return { ...payload, attestation_digest: digestObject(payload) };
+  }
+
+  function governanceEnvelope(root, { persist = false } = {}) {
+    const attestation = governanceAttestationPayload(root);
+    return {
+      mode: 'governance-attest',
+      ok: attestation.violations.length === 0,
+      state_present: fs.existsSync(stateRootDirectory(root)),
+      governance_attestation: { ...attestation, writes: Boolean(persist) },
+      safety: { stage: 'Stage 31', writes: Boolean(persist), governance_artifact: Boolean(persist), ...governanceBoundaryAssertions() },
+      quality: attestation.violations,
+      action: persist ? 'governance attestation was written locally. No runtime action, repair, platform API, model, git, worktree, or external delivery occurred.' : 'governance attestation was previewed read-only. No files were written and no runtime action occurred.',
+    };
+  }
+
+  function validateGovernanceArtifact(root, artifact) {
+    const failures = [];
+    if (artifact.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (artifact.command !== 'governance') failures.push('command must be governance');
+    if (artifact.mode !== 'governance-attest') failures.push('mode must be governance-attest');
+    if (artifact.governance_attestation?.stage !== 'Stage 31') failures.push('governance_attestation.stage must be Stage 31');
+    const attestation = artifact.governance_attestation || {};
+    const digestPayload = { ...attestation };
+    delete digestPayload.writes;
+    delete digestPayload.attestation_digest;
+    if (attestation.attestation_digest !== digestObject(digestPayload)) failures.push('governance attestation digest mismatch');
+    for (const [key, expected] of Object.entries(governanceBoundaryAssertions())) {
+      if (attestation.boundary_assertions?.[key] !== expected) failures.push(`governance boundary ${key} must be false`);
+    }
+    if (attestation.source_trace_file) {
+      try {
+        const tracePath = runtimeTraceFilePath(root, attestation.source_trace_file);
+        if (fileDigest(tracePath) !== attestation.trace_digest) failures.push('governance trace digest mismatch');
+        const trace = readJsonArtifact(tracePath, 'Runtime trace');
+        const verification = validateRuntimeTraceArtifact(root, trace);
+        if (!verification.ok) failures.push(...verification.failures.map((failure) => `governance trace verification failed: ${failure}`));
+      } catch (error) {
+        failures.push(error.message);
+      }
+    } else {
+      failures.push('governance source_trace_file is required');
+    }
+    if (attestation.source_observability_file) {
+      try {
+        const observabilityPath = safeStateArtifactFilePath(root, observabilityDirectory, attestation.source_observability_file, '.observability.json', 'Observability');
+        if (fileDigest(observabilityPath) !== attestation.observability_digest) failures.push('governance observability digest mismatch');
+        const observability = readJsonArtifact(observabilityPath, 'Observability');
+        const verification = validateGovernanceObservabilityArtifact(observability);
+        if (!verification.ok) failures.push(...verification.failures.map((failure) => `governance observability verification failed: ${failure}`));
+      } catch (error) {
+        failures.push(error.message);
+      }
+    } else {
+      failures.push('governance source_observability_file is required');
+    }
+    if (!Array.isArray(attestation.reply_review_files)) failures.push('governance reply_review_files must be an array');
+    else {
+      for (const review of attestation.reply_review_files) {
+        try {
+          const reviewPath = replyReviewFilePath(root, review.file);
+          if (fileDigest(reviewPath) !== review.digest) failures.push(`governance reply review digest mismatch: ${review.file}`);
+          const reviewArtifact = readJsonArtifact(reviewPath, 'Reply review');
+          const verification = validateReplyArtifact(root, reviewArtifact, review.file, reviewPath);
+          if (!verification.ok) failures.push(...verification.failures.map((failure) => `governance reply review verification failed: ${failure}`));
+        } catch (error) {
+          failures.push(error.message);
+        }
+      }
+    }
+    if (!Array.isArray(attestation.automation_artifacts)) failures.push('governance automation_artifacts must be an array');
+    else {
+      const verifiers = {
+        subagent_dispatch: [subagentDispatchFilePath, 'Subagent dispatch', (automationArtifact) => validateSubagentDispatchArtifact(root, automationArtifact)],
+        subagent_result: [subagentResultFilePath, 'Subagent result', (automationArtifact, fileName) => validateSubagentResultArtifact(root, automationArtifact, fileName)],
+        subagent_review: [subagentReviewFilePath, 'Subagent review', (automationArtifact, fileName) => validateSubagentReviewArtifact(root, automationArtifact, fileName)],
+        platform_session_intake: [platformSessionIntakeFilePath, 'Platform session intake', (automationArtifact, fileName) => validatePlatformSessionIntakeArtifact(root, automationArtifact, fileName)],
+        platform_session_review: [platformSessionReviewFilePath, 'Platform session review', (automationArtifact, fileName) => validatePlatformSessionReviewArtifact(root, automationArtifact, fileName)],
+        hook_run: [hookRunFilePath, 'Hook run', (automationArtifact, fileName) => validateHookRunArtifact(root, automationArtifact, fileName)],
+      };
+      for (const item of attestation.automation_artifacts) {
+        const entry = verifiers[item.type];
+        if (!entry) {
+          failures.push(`governance automation artifact type unsupported: ${item.type || ''}`);
+          continue;
+        }
+        try {
+          const [resolver, label, verifier] = entry;
+          const file = resolver(root, item.file);
+          if (fileDigest(file) !== item.digest) failures.push(`governance automation digest mismatch: ${item.file}`);
+          const automationArtifact = readJsonArtifact(file, label);
+          const verification = verifier(automationArtifact, item.file);
+          if (!verification.ok) failures.push(...verification.failures.map((failure) => `governance automation verification failed: ${failure}`));
+        } catch (error) {
+          failures.push(error.message);
+        }
+      }
+    }
+    const automationPolicy = attestation.automation_policy || {};
+    for (const key of ['approved_dispatch_required', 'traced_required', 'reviewed_required', 'hook_bounded_required']) if (automationPolicy[key] !== true) failures.push(`governance automation_policy.${key} must be true`);
+    for (const key of ['runtime_subagent_session', 'platform_api', 'source_merge']) if (automationPolicy[key] !== false) failures.push(`governance automation_policy.${key} must be false`);
+    if (attestation.local_only !== true) failures.push('governance local_only must be true');
+    if (attestation.no_repair !== true) failures.push('governance no_repair must be true');
+    if (attestation.no_execution !== true) failures.push('governance no_execution must be true');
+    failures.push(...validateCommonArtifactSafety(artifact.safety, 'Stage 31'));
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writeGovernanceAttestation(root, envelope) {
+    if (!envelope.ok) throw new Error(`governance attestation gate failed: ${envelope.quality.join('; ')}`);
+    const file = governanceSnapshotPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'governance', ...envelope, safety: { ...envelope.safety, governance_artifact: true } };
+    const verification = validateGovernanceArtifact(root, payload);
+    if (!verification.ok) throw new Error(`governance attestation verification failed: ${verification.failures.join('; ')}`);
+    return artifactStore(path.dirname(file), path.basename(file), payload);
+  }
+
+  return {
+    governanceBoundaryAssertions,
+    governanceEvidenceDescriptor,
+    governanceReplyReviewDescriptors,
+    governanceObservabilityViolations,
+    validateGovernanceObservabilityArtifact,
+    governanceAutomationDescriptors,
+    governanceAttestationPayload,
+    governanceEnvelope,
+    validateGovernanceArtifact,
+    writeGovernanceAttestation,
+  };
+}