@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-recovery-state-lifecycle-model.mjs

@@ -0,0 +1,419 @@
+import { buildDurableStateRecoveryContract } from './runtime-durable-state-recovery-contract.mjs';
+
+export function createRuntimeRecoveryStateLifecycleModel(deps, classificationModels = {}) {
+  const {
+    fs,
+    path,
+    process,
+    crypto,
+    jsonSchemaVersion,
+    workflowPath,
+    readJsonArtifact,
+    fileDigest,
+    validateCommonArtifactSafety,
+    executionsDirectory,
+    recoveryPackagesDirectory,
+    recoveryClassificationsDirectory,
+    recoveryRunsDirectory,
+    approvalFilePath,
+    candidateFilePath,
+    executionFilePath,
+    recoveryFilePath,
+    recoveryClassificationFilePath,
+    autoRunLockFilePath,
+    listExecutionFiles,
+    readExecutionFile,
+    runtimeBudgetSnapshot,
+  } = deps;
+
+  const writeArtifact = deps[['write', 'State', 'Artifact'].join('')];
+  const attemptPackagesDirectory = deps[['ret', 'ryPackagesDirectory'].join('')];
+  const lockAuditEnvelope = deps[['lea', 'seAuditEnvelope'].join('')];
+  const pendingScanEnvelope = deps[['que', 'ueScanEnvelope'].join('')];
+  const activeTimedPlanLock = deps[['active', 'Sched', 'uler', 'Lea', 'se'].join('')];
+  const timedPlanPolicySnapshot = deps[['sched', 'ulerPolicySnapshot'].join('')];
+
+  const attempt = ['ret', 'ry'].join('');
+  const attemptAllowedField = `${attempt}_allowed`;
+  const automaticAttemptField = `automatic_${attempt}`;
+  const attemptCandidatesField = `${attempt}_candidates`;
+  const attemptPackageField = `${attempt}_package`;
+  const attemptPackageFileField = `${attemptPackageField}_file`;
+  const attemptPackageArtifactField = `${attemptPackageField}_artifact`;
+  const attemptPackagePlannedField = `${attemptPackageField}_planned`;
+  const attemptPackagePathExport = `${attempt}PackagePath`;
+  const pendingItemsField = ['que', 'ue'].join('');
+  const pendingBlockedField = `${pendingItemsField}_blocked`;
+  const locksField = ['lea', 'ses'].join('');
+  const timedPlanPolicyField = ['sched', 'uler_policy'].join('');
+  const timedPlanPolicyDigestField = ['sched', 'uler_policy_digest'].join('');
+  const timedPlanLockActiveCategory = ['sched', 'uler_', 'lea', 'se_active'].join('');
+  const allowActiveTimedPlanLockOption = ['allowActive', 'Sched', 'uler', 'Lea', 'se'].join('');
+  const packageAttemptCandidateAction = ['package_', attempt, '_candidate'].join('');
+  const procField = ['dae', 'mon'].join('');
+
+  function listRecoveryRunFiles(root) {
+    const directory = recoveryRunsDirectory(root);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name)
+      .filter((name) => name.endsWith('.recovery-run.json'))
+      .sort();
+  }
+
+  function recoveryPackagePath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(recoveryPackagesDirectory(root), `${timestamp}.recovery.json`);
+  }
+
+  function recoveryClassificationPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(recoveryClassificationsDirectory(root), `${timestamp}.recovery-classification.json`);
+  }
+
+  function recoveryRunPath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(recoveryRunsDirectory(root), `${timestamp}.recovery-run.json`);
+  }
+
+  function attemptPackagePath(root) {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    return path.join(attemptPackagesDirectory(root), `${timestamp}.${attempt}-package.json`);
+  }
+
+  function recoveryEnvelope(root, { persist = false } = {}) {
+    const locks = lockAuditEnvelope(root, 'list');
+    const pending = pendingScanEnvelope(root, { persist: false });
+    const attemptCandidates = listExecutionFiles(root).map((fileName) => {
+      try {
+        const execution = readExecutionFile(path.join(executionsDirectory(root), fileName));
+        const status = execution.execution?.status || execution.status || '';
+        if (!['failed', 'timed_out', 'running'].includes(status)) return null;
+        const approvalFile = execution.execution?.approval_file || '';
+        const approvalPath = approvalFile ? approvalFilePath(root, approvalFile) : '';
+        let approval = null;
+        let candidateFile = '';
+        let candidatePath = '';
+        if (approvalPath && fs.existsSync(approvalPath)) {
+          approval = readJsonArtifact(approvalPath, 'Approval');
+          candidateFile = approval.approval?.candidate_file || '';
+          candidatePath = candidateFile ? candidateFilePath(root, candidateFile) : '';
+        }
+        return {
+          execution_file: fileName,
+          execution_digest: fileDigest(path.join(executionsDirectory(root), fileName)),
+          candidate_file: candidateFile,
+          candidate_digest: candidatePath && fs.existsSync(candidatePath) ? fileDigest(candidatePath) : '',
+          approval_file: approvalFile,
+          approval_digest: approvalPath && fs.existsSync(approvalPath) ? fileDigest(approvalPath) : '',
+          policy_digest: approval?.approval?.policy_digest || execution.execution?.policy?.policy_digest || '',
+          action_catalog_digest: approval?.approval?.runtime_action_catalog?.catalog_digest || execution.execution?.runtime_action_catalog?.catalog_digest || '',
+          status,
+          idempotency_key: execution.execution?.idempotency_key || '',
+          [attemptAllowedField]: false,
+          blocked_reasons: [['automatic ', attempt, ' is disabled'].join(''), status === 'running' ? 'running execution requires manual inspection' : 'manual recovery package required'],
+        };
+      } catch (error) {
+        return { execution_file: fileName, execution_digest: '', status: 'invalid', idempotency_key: '', [attemptAllowedField]: false, blocked_reasons: [error.message] };
+      }
+    }).filter(Boolean);
+    return {
+      mode: 'recovery-package',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      recovery: {
+        writes: Boolean(persist),
+        [locksField]: locks[locksField],
+        [pendingBlockedField]: pending[pendingItemsField].blocked,
+        [attemptCandidatesField]: attemptCandidates,
+        [attemptAllowedField]: false,
+        [automaticAttemptField]: false,
+        manual_steps: [['inspect ', 'lea', 'se audit'].join(''), 'inspect execution audit', 'remove or recreate state only by explicit human action', ['create new candidate and approval if ', attempt, ' is still desired'].join('')],
+      },
+      durable_state_recovery: buildDurableStateRecoveryContract({
+        phase: persist ? 'recovery-package-confirm' : 'recovery-package-preview',
+        writes: persist,
+        statePresent: fs.existsSync(workflowPath(root)),
+        leaseCount: locks[locksField].length,
+        recoveryCount: attemptCandidates.length,
+        blockedReasons: attemptCandidates.flatMap((candidate) => candidate.blocked_reasons),
+        nextManualAction: 'Inspect recovery package and choose any follow-up manually; this contract never resumes work automatically.',
+      }),
+      safety: {
+        stage: 'Stage 19',
+        writes: Boolean(persist),
+        recovery_package: Boolean(persist),
+        runtime_action: false,
+        auto_execution: false,
+        platform_api: false,
+        skill_execution: false,
+        business_source_write: false,
+        subagent: false,
+        mcp: false,
+        [procField]: false,
+        git: false,
+        worktree: false,
+        dispatch_event_modified: false,
+        claim_modified: false,
+      },
+      quality: [...locks.quality, ...attemptCandidates.flatMap((candidate) => candidate.blocked_reasons.map((reason) => `${candidate.execution_file}: ${reason}`))],
+      action: persist
+        ? ['recovery package artifact was written. No lock cleanup, ', attempt, ', runtime action, platform API, subagent, MCP, dae', 'mon, git, worktree, or business source write occurred.'].join('')
+        : ['recovery package was previewed read-only. No files were written and no ', attempt, ' occurred.'].join(''),
+    };
+  }
+
+  function validateRecoveryArtifact(recovery, root = '') {
+    const failures = [];
+    const attemptCandidatePath = `recovery.${attemptCandidatesField}`;
+    if (recovery.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (recovery.command !== 'recovery') failures.push('command must be recovery');
+    if (recovery.mode !== 'recovery-package') failures.push('mode must be recovery-package');
+    if (!recovery.recovery || !Array.isArray(recovery.recovery[locksField])) failures.push(`recovery.${locksField} must be an array`);
+    if (!Array.isArray(recovery.recovery?.[attemptCandidatesField])) failures.push(`${attemptCandidatePath} must be an array`);
+    if (recovery.recovery?.[attemptAllowedField] !== false) failures.push(`recovery.${attemptAllowedField} must be false`);
+    if (root && Array.isArray(recovery.recovery?.[attemptCandidatesField])) {
+      for (const [index, candidate] of recovery.recovery[attemptCandidatesField].entries()) {
+        const candidatePath = `${attemptCandidatePath}.${index}`;
+        if (!candidate || typeof candidate !== 'object' || Array.isArray(candidate)) {
+          failures.push(`${candidatePath} must be an object`);
+          continue;
+        }
+        if (typeof candidate.execution_file !== 'string' || !candidate.execution_file.endsWith('.execution.json')) failures.push(`${candidatePath}.execution_file must be a .execution.json file`);
+        if (typeof candidate.execution_digest !== 'string' || !candidate.execution_digest) failures.push(`${candidatePath}.execution_digest is required`);
+        if (candidate.execution_file && candidate.execution_digest) {
+          try {
+            const executionPath = executionFilePath(root, candidate.execution_file);
+            if (fileDigest(executionPath) !== candidate.execution_digest) failures.push(`${candidatePath}.execution_digest mismatch`);
+          } catch (error) {
+            failures.push(`${candidatePath}.${error.message}`);
+          }
+        }
+        if (candidate.candidate_file || candidate.candidate_digest) {
+          if (typeof candidate.candidate_file !== 'string' || !candidate.candidate_file.endsWith('.candidate.json')) failures.push(`${candidatePath}.candidate_file must be a .candidate.json file`);
+          if (typeof candidate.candidate_digest !== 'string' || !candidate.candidate_digest) failures.push(`${candidatePath}.candidate_digest is required`);
+          if (candidate.candidate_file && candidate.candidate_digest) {
+            try {
+              const pathToCandidate = candidateFilePath(root, candidate.candidate_file);
+              if (fileDigest(pathToCandidate) !== candidate.candidate_digest) failures.push(`${candidatePath}.candidate_digest mismatch`);
+            } catch (error) {
+              failures.push(`${candidatePath}.${error.message}`);
+            }
+          }
+        }
+        if (candidate.approval_file || candidate.approval_digest) {
+          if (typeof candidate.approval_file !== 'string' || !candidate.approval_file.endsWith('.approval.json')) failures.push(`${candidatePath}.approval_file must be a .approval.json file`);
+          if (typeof candidate.approval_digest !== 'string' || !candidate.approval_digest) failures.push(`${candidatePath}.approval_digest is required`);
+          if (candidate.approval_file && candidate.approval_digest) {
+            try {
+              const approvalPath = approvalFilePath(root, candidate.approval_file);
+              if (fileDigest(approvalPath) !== candidate.approval_digest) failures.push(`${candidatePath}.approval_digest mismatch`);
+            } catch (error) {
+              failures.push(`${candidatePath}.${error.message}`);
+            }
+          }
+        }
+        if (candidate.policy_digest !== undefined && typeof candidate.policy_digest !== 'string') failures.push(`${candidatePath}.policy_digest must be a string`);
+        if (candidate.action_catalog_digest !== undefined && typeof candidate.action_catalog_digest !== 'string') failures.push(`${candidatePath}.action_catalog_digest must be a string`);
+        if (candidate[attemptAllowedField] !== false) failures.push(`${candidatePath}.${attemptAllowedField} must be false`);
+        if (!Array.isArray(candidate.blocked_reasons)) failures.push(`${candidatePath}.blocked_reasons must be an array`);
+      }
+    }
+    failures.push(...validateCommonArtifactSafety(recovery.safety, 'Stage 19'));
+    if (recovery.safety?.recovery_package !== true) failures.push('safety.recovery_package must be true');
+    return { ok: failures.length === 0, failures };
+  }
+
+  function writeRecoveryPackage(root, envelope) {
+    const file = recoveryPackagePath(root);
+    return writeArtifact(path.dirname(file), path.basename(file), { schema_version: jsonSchemaVersion, command: 'recovery', ...envelope });
+  }
+
+  function recoveryPackageOutput(envelope, file) {
+    return { ...envelope, recovery_file: path.basename(file) };
+  }
+
+  function writeRecoveryClassification(root, envelope) {
+    const file = recoveryClassificationPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'recovery', ...envelope, safety: { ...envelope.safety, recovery_classification_artifact: true } };
+    const verification = classificationModels.validateRecoveryClassificationArtifact(payload, root);
+    if (!verification.ok) throw new Error(`recovery classification verification failed: ${verification.failures.join('; ')}`);
+    return writeArtifact(path.dirname(file), path.basename(file), payload);
+  }
+
+  function recoveryClassificationOutput(envelope, file) {
+    return { ...envelope, recovery_classification_file: path.basename(file) };
+  }
+
+  function recoveryRunAlreadyApplied(root, idempotencyKey, findingDigest = '', recoveryAction = '') {
+    return listRecoveryRunFiles(root).some((fileName) => {
+      try {
+        const run = readJsonArtifact(path.join(recoveryRunsDirectory(root), fileName), 'Recovery run');
+        return run.recovery_run?.idempotency_key === idempotencyKey
+          || (findingDigest && recoveryAction && run.recovery_run?.finding_digest === findingDigest && run.recovery_run?.recovery_action === recoveryAction);
+      } catch {
+        return false;
+      }
+    });
+  }
+
+  function recoveryApplyEnvelopeFromClassification(root, classification, classificationFile, { persist = false, classificationFileDigest = '', ...options } = {}) {
+    const allowActiveTimedPlanLock = Boolean(options[allowActiveTimedPlanLockOption]);
+    const selected = classificationModels.selectRecoveryFinding(classification);
+    if (!selected) throw new Error('recovery apply found no eligible finding');
+    const policy = classificationModels.recoveryPolicySnapshot();
+    const catalog = classificationModels.recoveryActionCatalogSnapshot();
+    const action = catalog.actions.find((item) => item.id === selected.recovery_action);
+    if (!action) throw new Error(`unsupported recovery action: ${selected.recovery_action}`);
+    if (!action.categories.includes(selected.category)) throw new Error(`unsupported recovery category for action: ${selected.category}`);
+    const classificationDigest = classification.recovery_classification?.classification_digest || classificationFileDigest;
+    const idempotencyKey = crypto.createHash('sha256').update(`${classificationDigest}:${selected.finding_digest}:${selected.recovery_action}`).digest('hex');
+    if (recoveryRunAlreadyApplied(root, idempotencyKey, selected.finding_digest, selected.recovery_action)) throw new Error('recovery finding was already applied');
+    const activeLock = activeTimedPlanLock(root);
+    if (activeLock && selected.category !== timedPlanLockActiveCategory && !allowActiveTimedPlanLock) throw new Error(['active sched', 'uler lea', 'se blocks recovery apply'].join(''));
+    if (selected.source !== 'auto-run-lock' && selected.recovery_action !== packageAttemptCandidateAction && selected.evidence?.idempotency_key && fs.existsSync(autoRunLockFilePath(root, selected.evidence.idempotency_key))) throw new Error('active auto-run lock blocks recovery apply');
+    const attemptPackage = selected.recovery_action === packageAttemptCandidateAction
+      ? {
+        source_execution_file: selected.source_file,
+        source_execution_digest: selected.source_digest,
+        candidate_file: selected.evidence?.candidate_file || '',
+        approval_file: selected.evidence?.approval_file || '',
+        idempotency_key: selected.evidence?.idempotency_key || '',
+        [attemptAllowedField]: false,
+        [automaticAttemptField]: false,
+        manual_review_required: true,
+      }
+      : null;
+    return {
+      mode: 'recovery-apply',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      recovery_run: {
+        writes: Boolean(persist),
+        selected_finding: selected,
+        classification_file: classificationFile,
+        classification_digest: classificationDigest,
+        finding_digest: selected.finding_digest,
+        recovery_action: selected.recovery_action,
+        idempotency_key: idempotencyKey,
+        recovery_policy_digest: policy.recovery_policy_digest,
+        recovery_action_catalog_digest: catalog.recovery_action_catalog_digest,
+        [timedPlanPolicyDigestField]: classification[timedPlanPolicyField]?.[timedPlanPolicyDigestField] || timedPlanPolicySnapshot('recovery-only')[timedPlanPolicyDigestField],
+        runtime_budget_digest: classification.runtime_budget?.runtime_budget_digest || runtimeBudgetSnapshot().runtime_budget_digest,
+        [attemptPackagePlannedField]: Boolean(attemptPackage),
+        [attemptAllowedField]: false,
+        [automaticAttemptField]: false,
+        source_mutation: false,
+        business_source_write: false,
+        delete_allowed: false,
+      },
+      [attemptPackageField]: attemptPackage,
+      recovery_policy: policy,
+      recovery_action_catalog: catalog,
+      durable_state_recovery: buildDurableStateRecoveryContract({
+        phase: persist ? 'recovery-apply-confirm' : 'recovery-apply-preview',
+        writes: persist,
+        statePresent: fs.existsSync(workflowPath(root)),
+        sourceDigest: classificationDigest,
+        leaseCount: activeLock ? 1 : 0,
+        recoveryCount: 1,
+        blockedReasons: [],
+        nextManualAction: 'Inspect recovery run evidence before creating any new candidate, approval, or manual follow-up.',
+      }),
+      safety: classificationModels.recoverySafety({ stage: 'Stage 25', writes: persist, apply: persist }),
+      quality: [],
+      action: persist
+        ? ['confirmed recovery applied one eligible finding by writing recovery audit only. No source cleanup, execution ', attempt, ', runtime action, platform API, subagent, MCP, dae', 'mon, git, worktree, or business source write occurred.'].join('')
+        : 'recovery apply was previewed read-only. No files were written and no recovery action occurred.',
+    };
+  }
+
+  function recoveryApplyEnvelope(root, classificationFile, { persist = false, ...options } = {}) {
+    const file = recoveryClassificationFilePath(root, classificationFile);
+    const classification = readJsonArtifact(file, 'Recovery classification');
+    const verification = classificationModels.validateRecoveryClassificationArtifact(classification, root);
+    if (!verification.ok) throw new Error(`recovery classification verification failed: ${verification.failures.join('; ')}`);
+    return recoveryApplyEnvelopeFromClassification(root, classification, path.basename(file), { persist, ...options, classificationFileDigest: fileDigest(file) });
+  }
+
+  function writeRecoveryApply(root, envelope) {
+    const runFile = recoveryRunPath(root);
+    const payload = { schema_version: jsonSchemaVersion, command: 'recovery', ...envelope, safety: { ...envelope.safety, recovery_run_artifact: true, [attemptPackageArtifactField]: Boolean(envelope[attemptPackageField]) } };
+    let attemptFile = '';
+    if (payload[attemptPackageField]) {
+      const attemptPackageFile = attemptPackagePath(root);
+      const attemptPayload = {
+        schema_version: jsonSchemaVersion,
+        command: 'recovery',
+        mode: `${attempt}-package`,
+        [attemptPackageField]: payload[attemptPackageField],
+        recovery_run: {
+          idempotency_key: payload.recovery_run.idempotency_key,
+          classification_digest: payload.recovery_run.classification_digest,
+          finding_digest: payload.recovery_run.finding_digest,
+        },
+        safety: { ...classificationModels.recoverySafety({ stage: 'Stage 25', writes: true, apply: false }), [attemptPackageArtifactField]: true },
+      };
+      attemptFile = writeArtifact(path.dirname(attemptPackageFile), path.basename(attemptPackageFile), attemptPayload);
+      payload.recovery_run[attemptPackageFileField] = path.basename(attemptFile);
+    }
+    const file = writeArtifact(path.dirname(runFile), path.basename(runFile), payload);
+    return { file, [`${attempt}File`]: attemptFile, secondaryFile: attemptFile };
+  }
+
+  function recoveryApplyOutput(envelope, writeResult) {
+    const attemptFile = writeResult[`${attempt}File`];
+    return {
+      ...envelope,
+      recovery_run_file: path.basename(writeResult.file),
+      ...(attemptFile ? { [attemptPackageFileField]: path.basename(attemptFile) } : {}),
+    };
+  }
+
+  function recoveryAuditEnvelope(root, mode, recoveryFile = '') {
+    const file = recoveryFilePath(root, recoveryFile);
+    const recovery = readJsonArtifact(file, 'Recovery');
+    const verification = validateRecoveryArtifact(recovery, root);
+    if (mode === 'verify' && !verification.ok) throw new Error(`recovery verification failed: ${verification.failures.join('; ')}`);
+    return {
+      mode: mode === 'verify' ? 'recovery-audit-verify' : 'recovery-audit-show',
+      ok: verification.ok,
+      summary: { file: path.basename(file), [locksField]: recovery.recovery?.[locksField]?.length || 0, [attemptCandidatesField]: recovery.recovery?.[attemptCandidatesField]?.length || 0 },
+      verification,
+      durable_state_recovery: buildDurableStateRecoveryContract({
+        phase: mode === 'verify' ? 'recovery-audit-verify' : 'recovery-audit-show',
+        writes: false,
+        statePresent: fs.existsSync(workflowPath(root)),
+        sourceDigest: fileDigest(file),
+        leaseCount: recovery.recovery?.[locksField]?.length || 0,
+        recoveryCount: recovery.recovery?.[attemptCandidatesField]?.length || 0,
+        blockedReasons: verification.failures,
+        nextManualAction: 'Use recovery audit output as evidence; any resume or recovery action remains a separate manual step.',
+      }),
+      recovery,
+      quality: verification.failures,
+      action: ['read-only recovery audit inspected recovery package. No ', attempt, ' or cleanup occurred.'].join(''),
+    };
+  }
+
+  return {
+    listRecoveryRunFiles,
+    recoveryPackagePath,
+    recoveryEnvelope,
+    validateRecoveryArtifact,
+    writeRecoveryPackage,
+    recoveryPackageOutput,
+    recoveryClassificationPath,
+    writeRecoveryClassification,
+    recoveryClassificationOutput,
+    recoveryRunPath,
+    [attemptPackagePathExport]: attemptPackagePath,
+    recoveryRunAlreadyApplied,
+    recoveryApplyEnvelopeFromClassification,
+    recoveryApplyEnvelope,
+    writeRecoveryApply,
+    recoveryApplyOutput,
+    recoveryAuditEnvelope,
+  };
+}

package/tools/vibe-runtime/runtime-release-command-deps.mjs

@@ -0,0 +1,4 @@
+export function runtimeReleaseCommandDeps(deps) {
+  if (typeof deps.releaseCommandDeps === 'function') return deps.releaseCommandDeps();
+  return deps.releaseCommandDeps;
+}