auth-yes/forum/experiments/state_machine_poc.ts

import { assert } from "https://deno.land/std@0.224.0/assert/mod.ts";

// Define the structure of the transitions.json configuration
interface TransitionRule {
  requires: string[];
}

type TransitionsConfig = Record<string, TransitionRule>;

// Mock transitions.json content (in a real scenario, this is read from .forum/transitions.json)
const MOCK_TRANSITIONS_JSON = `
{
  "Coder": {
    "requires": ["Gatekeeper_Approval"]
  },
  "Gatekeeper": {
    "requires": []
  },
  "Evaluator": {
    "requires": ["Coder_Completion"]
  }
}
`;

// Simulated state of the repository/pipeline
const currentSystemState = {
  activeFlags: new Set<string>(), // e.g., 'Gatekeeper_Approval', 'Coder_Completion'
};

/**
 * The Evaluator script that mathematically enforces pipeline progression.
 * It checks the transitions matrix to see if a specific Agent Role is allowed to execute based on the current flags.
 */
function canAgentExecute(
  roleName: string,
  config: TransitionsConfig,
  currentState: Set<string>,
): boolean {
  const rule = config[roleName];
  if (!rule) {
    throw new Error(
      `Role ${roleName} is not defined in the transitions matrix. Execution denied.`,
    );
  }

  // Bounded Model Checking: All required flags must be present in the current state.
  return rule.requires.every((req) => currentState.has(req));
}

async function runStateMachinePoC() {
  console.log("--- Agent Forum: State Machine & Governance PoC ---");

  // 1. Parse the machine-readable matrix
  const matrix: TransitionsConfig = JSON.parse(MOCK_TRANSITIONS_JSON);
  console.log("Loaded Transitions Matrix:", Object.keys(matrix));

  // 2. Attempt to run Coder BEFORE Gatekeeper has approved
  console.log(
    "\nScenario 1: Attempting to run 'Coder' with empty system state...",
  );
  const canCoderRunInitial = canAgentExecute(
    "Coder",
    matrix,
    currentSystemState.activeFlags,
  );
  console.log(`Result: Coder execution allowed? ${canCoderRunInitial}`);
  assert(
    canCoderRunInitial === false,
    "Coder should NOT be able to run without Gatekeeper_Approval",
  );

  // 3. Gatekeeper runs (it has no requirements)
  console.log("\nScenario 2: Running 'Gatekeeper'...");
  const canGatekeeperRun = canAgentExecute(
    "Gatekeeper",
    matrix,
    currentSystemState.activeFlags,
  );
  console.log(`Result: Gatekeeper execution allowed? ${canGatekeeperRun}`);
  assert(canGatekeeperRun === true, "Gatekeeper should be able to run");

  // Simulate Gatekeeper finishing its job and setting the flag in the meta-state
  console.log("Gatekeeper finished. Setting 'Gatekeeper_Approval' flag...");
  currentSystemState.activeFlags.add("Gatekeeper_Approval");

  // 4. Attempt to run Coder AFTER Gatekeeper has approved
  console.log(
    "\nScenario 3: Attempting to run 'Coder' with updated system state...",
  );
  const canCoderRunNow = canAgentExecute(
    "Coder",
    matrix,
    currentSystemState.activeFlags,
  );
  console.log(`Result: Coder execution allowed? ${canCoderRunNow}`);
  assert(
    canCoderRunNow === true,
    "Coder SHOULD be able to run now that Gatekeeper_Approval is present",
  );

  console.log(
    "\nPoC Successful: Bounded Model Checking mathematically prevents out-of-order execution.",
  );
}

if (import.meta.main) {
  runStateMachinePoC().catch((err) => {
    console.error("PoC Failed:", err);
    Deno.exit(1);
  });
}