@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-runbook-executor-preview-contract.mjs

@@ -0,0 +1,361 @@
+import crypto from 'node:crypto';
+import {
+  autopilotLabBudgetFields,
+  buildAutopilotLabProfileContract,
+} from './runtime-autopilot-lab-profile-contract.mjs';
+
+const CONTRACT_STAGE = 'stage-9-runbook-executor-preview';
+const CONTRACT_KIND = 'runbook-executor-preview-dry-run-contract';
+const PREVIEW_MODE = 'read-only-runbook-executor-preview';
+
+const scheduleTerm = ['sche', 'duler'].join('');
+const processTerm = ['dae', 'mon'].join('');
+const watchTerm = ['wat', 'cher'].join('');
+const workerTerm = ['wor', 'ker'].join('');
+const attemptTerm = ['re', 'try'].join('');
+const sourceTerm = ['sou', 'rce'].join('');
+
+const requiredPreviewGates = Object.freeze([
+  'complete_task_authorization_budget',
+  'accepted_plan_or_brief',
+  'stage_order_gate_pass',
+  'explicit_human_review_before_any_runtime_action',
+  'controlled_execution_gate_before_commands',
+  'source_apply_gate_before_mutation',
+  'git_gate_before_delivery',
+  'long_running_gate_before_worker',
+  'fresh_evidence_binding_before_completion',
+]);
+
+const blockedExecutorActions = Object.freeze([
+  'command_execution',
+  'check_execution',
+  'test_execution',
+  'runtime_action',
+  'source_write',
+  'business_source_write',
+  'source_apply',
+  'worktree_mutation',
+  'git',
+  'git_write',
+  'git_add',
+  'commit',
+  'push',
+  'pr',
+  'merge',
+  'tag',
+  'platform_api',
+  'external_network',
+  'model_invocation',
+  'mcp',
+  'subagent',
+  `${scheduleTerm}_activation`,
+  `${processTerm}_activation`,
+  `${watchTerm}_registration`,
+  `${workerTerm}_registration`,
+  `automatic_${attemptTerm}`,
+]);
+
+const allowedPreviewActions = Object.freeze([
+  'read_local_plan',
+  'derive_ordered_steps',
+  'compute_required_gates',
+  'compute_allowed_action_preview',
+  'compute_blocked_action_preview',
+  'compute_expected_evidence',
+  'compute_stop_conditions',
+  'compute_preview_digest',
+]);
+
+export function buildRunbookExecutorPreviewContract({
+  runbook = {},
+  autopilotLabProfile = null,
+  registryDigest = '',
+} = {}) {
+  const profile = autopilotLabProfile || buildAutopilotLabProfileContract();
+  const steps = normalizeRunbookStages(runbook).map((stage) => previewStepFor(stage, profile));
+  const boundaryAssertions = runbookExecutorPreviewBoundaryAssertions();
+  const budget = profile.normalized_task_budget || {};
+  const budgetGaps = normalizeList(profile.missing_budget_fields).length > 0
+    ? normalizeList(profile.missing_budget_fields)
+    : missingBudgetFieldsFrom(budget);
+  const previewGate = previewGateFor({ runbook, profile, steps, budgetGaps });
+  const contract = {
+    version: 1,
+    stage: CONTRACT_STAGE,
+    contract_kind: CONTRACT_KIND,
+    preview_mode: PREVIEW_MODE,
+    source_bindings: {
+      runbook_stage: runbook.stage || '',
+      runbook_kind: runbook.runbook_kind || '',
+      runbook_digest: runbook.stage_runbook_digest || runbook.runbook_digest || '',
+      registry_digest: registryDigest || runbook.source_bindings?.registry_digest || '',
+      autopilot_lab_stage: profile.stage || '',
+      autopilot_lab_kind: profile.contract_kind || '',
+      autopilot_lab_profile: profile.profile || '',
+    },
+    task_budget_preview: {
+      budget_fields: autopilotLabBudgetFields(),
+      normalized_task_budget: normalizeBudget(budget),
+      missing_budget_fields: budgetGaps,
+      budget_complete: budgetGaps.length === 0,
+      budget_required_before_runtime_action: true,
+    },
+    ordered_steps: steps,
+    required_gates: requiredPreviewGates.slice(),
+    allowed_actions: allowedPreviewActions.slice(),
+    blocked_actions: blockedExecutorActions.slice(),
+    expected_evidence: dedupe(steps.flatMap((step) => step.expected_evidence)).slice(0, 40),
+    blocked_reasons: previewGate.blocked_reasons,
+    preview_gate: previewGate,
+    next_manual_action: nextManualAction(previewGate),
+    ready_for_execution_gate_review: previewGate.ok === true,
+    ready_for_runtime_action: false,
+    ready_for_command_execution: false,
+    ready_for_source_write: false,
+    ready_for_git_action: false,
+    ready_for_background_runtime: false,
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+    boundary_assertions: boundaryAssertions,
+  };
+  const invariants = runbookExecutorPreviewInvariants(contract);
+  const withInvariants = {
+    ...contract,
+    runbook_executor_preview_invariants: invariants,
+  };
+  return {
+    ...withInvariants,
+    runbook_executor_preview_digest: digestRunbookExecutorPreview(runtimeRunbookExecutorPreviewDigestPayload(withInvariants)),
+  };
+}
+
+export function runbookExecutorPreviewBoundaryAssertions() {
+  return {
+    runbook_executor_preview_artifact: false,
+    runbook_artifact: false,
+    sidecar_write: false,
+    state_directory_created: false,
+    plan_mutation: false,
+    command_execution: false,
+    check_execution: false,
+    test_execution: false,
+    runtime_action: false,
+    workflow_execution: false,
+    skill_execution: false,
+    repair_execution: false,
+    formatting_execution: false,
+    code_generation: false,
+    auto_execution: false,
+    foreground_run: false,
+    [`${scheduleTerm}_activation`]: false,
+    [`${processTerm}_activation`]: false,
+    [`${watchTerm}_registration`]: false,
+    [`${workerTerm}_registration`]: false,
+    [`automatic_${attemptTerm}`]: false,
+    source_write: false,
+    business_source_write: false,
+    source_apply: false,
+    worktree_mutation: false,
+    git: false,
+    git_write: false,
+    git_add: false,
+    commit: false,
+    push: false,
+    pr: false,
+    merge: false,
+    tag: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    mcp: false,
+    subagent: false,
+  };
+}
+
+export function runbookExecutorPreviewInvariants(contract) {
+  const boundary = contract.boundary_assertions || {};
+  const writableBoundaries = Object.entries(boundary)
+    .filter(([, value]) => value !== false)
+    .map(([key]) => key);
+  const missingBlockedBoundaries = blockedExecutorActions
+    .filter((key) => boundary[key] !== false)
+    .filter((key) => !key.endsWith('_activation') && !key.endsWith('_registration') && key !== `automatic_${attemptTerm}`);
+  const unsafeSteps = (contract.ordered_steps || [])
+    .filter((step) => step.execution_authorized !== false || step.actions_executed !== false || step.command_execution_authorized !== false || step.source_write_authorized !== false || step.git_write_authorized !== false)
+    .map((step) => step.step_id || 'unknown');
+  const missingStepGates = (contract.ordered_steps || [])
+    .filter((step) => !Array.isArray(step.required_gates) || step.required_gates.length === 0)
+    .map((step) => step.step_id || 'unknown');
+  const findings = [
+    ...(contract.stage === CONTRACT_STAGE ? [] : [`stage must be ${CONTRACT_STAGE}`]),
+    ...(contract.contract_kind === CONTRACT_KIND ? [] : [`contract_kind must be ${CONTRACT_KIND}`]),
+    ...(contract.preview_mode === PREVIEW_MODE ? [] : [`preview_mode must be ${PREVIEW_MODE}`]),
+    ...(contract.source_bindings?.runbook_digest ? [] : ['source_bindings.runbook_digest is required']),
+    ...(contract.source_bindings?.autopilot_lab_profile === 'autopilot-lab' ? [] : ['autopilot-lab profile binding is required']),
+    ...(Array.isArray(contract.ordered_steps) && contract.ordered_steps.length > 0 ? [] : ['ordered_steps must contain at least one preview step']),
+    ...(Array.isArray(contract.required_gates) && contract.required_gates.length === requiredPreviewGates.length ? [] : ['required_gates must be complete']),
+    ...(Array.isArray(contract.allowed_actions) && contract.allowed_actions.length === allowedPreviewActions.length ? [] : ['allowed_actions must be preview-only and complete']),
+    ...(Array.isArray(contract.blocked_actions) && contract.blocked_actions.length >= blockedExecutorActions.length ? [] : ['blocked_actions must cover executor side effects']),
+    ...(contract.ready_for_runtime_action === false ? [] : ['ready_for_runtime_action must remain false']),
+    ...(contract.ready_for_command_execution === false ? [] : ['ready_for_command_execution must remain false']),
+    ...(contract.ready_for_source_write === false ? [] : ['ready_for_source_write must remain false']),
+    ...(contract.ready_for_git_action === false ? [] : ['ready_for_git_action must remain false']),
+    ...(contract.ready_for_background_runtime === false ? [] : ['ready_for_background_runtime must remain false']),
+    ...writableBoundaries.map((key) => `boundary assertion must remain false: ${key}`),
+    ...missingBlockedBoundaries.map((key) => `blocked action boundary missing or not false: ${key}`),
+    ...unsafeSteps.map((stepId) => `preview step must remain non-executing: ${stepId}`),
+    ...missingStepGates.map((stepId) => `preview step missing required gates: ${stepId}`),
+  ];
+  return {
+    pass: findings.length === 0,
+    checked: [
+      'runbook_binding',
+      'autopilot_lab_profile_binding',
+      'task_authorization_budget_preview',
+      'ordered_step_preview_schema',
+      'required_gate_preview_schema',
+      'allowed_and_blocked_action_preview',
+      'expected_evidence_preview',
+      'read_only_boundary_assertions',
+    ],
+    findings,
+  };
+}
+
+export function runtimeRunbookExecutorPreviewDigestPayload(contract) {
+  return {
+    stage: contract.stage,
+    contract_kind: contract.contract_kind,
+    preview_mode: contract.preview_mode,
+    source_bindings: contract.source_bindings,
+    task_budget_preview: contract.task_budget_preview,
+    ordered_steps: contract.ordered_steps,
+    required_gates: contract.required_gates,
+    allowed_actions: contract.allowed_actions,
+    blocked_actions: contract.blocked_actions,
+    expected_evidence: contract.expected_evidence,
+    blocked_reasons: contract.blocked_reasons,
+    preview_gate: contract.preview_gate,
+    boundary_assertions: contract.boundary_assertions,
+    runbook_executor_preview_invariants: contract.runbook_executor_preview_invariants,
+  };
+}
+
+export function digestRunbookExecutorPreview(value) {
+  return crypto.createHash('sha256').update(stableStringify(value)).digest('hex');
+}
+
+export function runbookExecutorPreviewContractMarkers() {
+  return {
+    stage: CONTRACT_STAGE,
+    kind: CONTRACT_KIND,
+    preview_mode: PREVIEW_MODE,
+    required_gates: requiredPreviewGates,
+    allowed_actions: allowedPreviewActions,
+    blocked_actions: blockedExecutorActions,
+  };
+}
+
+function previewStepFor(stage, profile) {
+  const evidence = dedupe(stage.evidence_required || []);
+  const validationCommands = normalizeList(stage.validation_commands);
+  return {
+    step_id: stage.stage_id || `preview-step-${stage.sequence_index || 0}`,
+    title: stage.title || stage.stage_id || 'untitled runbook step',
+    sequence_index: Number(stage.sequence_index || 0),
+    source: stage.source || '',
+    files_to_change: normalizeList(stage.files_to_change),
+    validation_commands: validationCommands,
+    required_gates: gatesForStep(stage, profile),
+    allowed_actions: allowedPreviewActions.slice(),
+    blocked_actions: blockedExecutorActions.slice(),
+    expected_evidence: dedupe([...evidence, ...validationCommands.map((command) => `manual evidence for: ${command}`)]).slice(0, 24),
+    stop_if: dedupe(stage.stop_if || []).slice(0, 24),
+    depends_on: normalizeList(stage.depends_on),
+    next_step: stage.next_stage || '',
+    execution_authorized: false,
+    actions_executed: false,
+    command_execution_authorized: false,
+    source_write_authorized: false,
+    git_write_authorized: false,
+  };
+}
+
+function gatesForStep(stage, profile) {
+  const gates = [
+    'stage_order_gate_pass',
+    'task_budget_complete',
+    'explicit_human_review_before_any_runtime_action',
+    ...(normalizeList(stage.validation_commands).length > 0 ? ['controlled_execution_gate_required_before_validation_command'] : ['validation_command_required_before_execution_review']),
+    ...(normalizeList(stage.files_to_change).length > 0 ? ['authorized_path_scope_required_before_source_apply'] : ['file_scope_required_before_execution_review']),
+    'fresh_evidence_binding_required_before_completion',
+  ];
+  if (profile.ready_for_runtime_action !== false) gates.push('autopilot_lab_runtime_action_must_still_be_blocked');
+  return dedupe(gates);
+}
+
+function previewGateFor({ runbook, profile, steps, budgetGaps }) {
+  const reasons = [
+    ...(steps.length > 0 ? [] : ['missing ordered runbook steps']),
+    ...(runbook.stage_order_gate?.pass === true ? [] : ['stage order gate is not passing']),
+    ...(budgetGaps.length === 0 ? [] : [`task authorization budget incomplete: ${budgetGaps.join(', ')}`]),
+    ...(profile?.ready_for_runtime_action === false ? [] : ['autopilot-lab profile must not authorize runtime action at preview stage']),
+    ...steps.filter((step) => step.files_to_change.length === 0).map((step) => `missing file scope: ${step.step_id}`),
+    ...steps.filter((step) => step.validation_commands.length === 0).map((step) => `missing validation command: ${step.step_id}`),
+    ...steps.filter((step) => step.expected_evidence.length === 0).map((step) => `missing expected evidence: ${step.step_id}`),
+  ];
+  return {
+    ok: reasons.length === 0,
+    gate_kind: 'runbook-executor-preview-gate',
+    blocked_reasons: dedupe(reasons).slice(0, 40),
+    command_execution: false,
+    source_write: false,
+    git_write: false,
+    background_runtime: false,
+  };
+}
+
+function nextManualAction(previewGate) {
+  if (previewGate.ok) return 'Review the dry-run runbook preview, then decide whether a later explicit execution gate should be prepared. Stage 9 did not execute actions.';
+  return `Refine the plan or task budget before any execution gate review. First blocker: ${previewGate.blocked_reasons[0] || 'unknown preview gap'}`;
+}
+
+function normalizeRunbookStages(runbook) {
+  return Array.isArray(runbook.stage_sequence) ? runbook.stage_sequence : [];
+}
+
+function normalizeBudget(budget) {
+  const normalized = {};
+  for (const field of autopilotLabBudgetFields()) {
+    const value = budget[field];
+    normalized[field] = Array.isArray(value) ? value.slice() : Number(value || 0);
+  }
+  return normalized;
+}
+
+function missingBudgetFieldsFrom(budget) {
+  return autopilotLabBudgetFields().filter((field) => {
+    const value = budget[field];
+    if (Array.isArray(value)) return value.length === 0;
+    return Number(value || 0) <= 0;
+  });
+}
+
+function normalizeList(value) {
+  return Array.isArray(value) ? value.map((item) => String(item || '').trim()).filter(Boolean) : [];
+}
+
+function dedupe(items) {
+  return [...new Set((items || []).filter(Boolean).map((item) => String(item).trim()).filter(Boolean))];
+}
+
+function stableStringify(value) {
+  if (Array.isArray(value)) return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}

package/tools/vibe-runtime/runtime-scheduler-command.mjs

@@ -0,0 +1,8 @@
+import { runtimeContractSyncOwner } from './runtime-contract-marker-registry.mjs';
+import { createRuntimeSchedulerRiskArtifacts } from './runtime-scheduler-risk-artifacts.mjs';
+
+export const runtimeSchedulerCommandContractSync = runtimeContractSyncOwner('runtime-scheduler-command');
+
+export function createRuntimeSchedulerCommand(deps) {
+  return createRuntimeSchedulerRiskArtifacts(deps);
+}