Motor Evaluador FARO Connect MVP

{
  "name": "@faro/evaluator",
  "version": "1.1.0",
  "description": "FARO Connect MVP Evaluation Engine (ENG-003 + ENG-003.1)",
  "type": "module",
  "scripts": {
    "dev": "tsx src/cli.ts",
    "evaluate": "tsx src/cli.ts evaluate",
    "dry-run": "tsx src/cli.ts dry-run",
    "explain": "tsx src/cli.ts explain",
    "typecheck": "tsc --noEmit",
    "test": "vitest run",
    "test:unit": "vitest run tests/unit",
    "test:integration": "vitest run tests/integration"
  },
  "dependencies": {
    "commander": "^12.1.0",
    "dotenv": "^16.4.5",
    "pg": "^8.13.1",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "@types/node": "^22.10.0",
    "@types/pg": "^8.11.10",
    "tsx": "^4.19.2",
    "typescript": "^5.7.2",
    "vitest": "^2.1.8"
  }
}

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "strict": true,
    "strictNullChecks": true,
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "outDir": "dist",
    "rootDir": ".",
    "types": ["node"]
  },
  "include": ["src/**/*.ts", "tests/**/*.ts"]
}

# Conexion PostgreSQL (RLS habilitado, schema faro)
DATABASE_URL=postgresql://faro_app:password@localhost:5432/faro

# Empresa Demo Cuyo S.A. + usuario service
FARO_DEFAULT_COMPANY_ID=10000000-0000-0000-0000-000000000001
FARO_DEFAULT_USER_ID=12000000-0000-0000-0000-000000000001
FARO_DEFAULT_ROLE_CODES=integration_service,faro_owner,company_admin

# Modo de evaluacion y flags
FARO_EVALUATION_MODE=normal
FARO_CREATE_ACTIONS=true
FARO_CREATE_NOTIFICATIONS=false
FARO_STRICT_CONFIDENCE=true

import pg from "pg";
import dotenv from "dotenv";

dotenv.config();
const { Pool } = pg;

if (!process.env.DATABASE_URL) {
  throw new Error("DATABASE_URL is required");
}

export const pool = new Pool({ connectionString: process.env.DATABASE_URL });

export async function withFaroDbContext<T>(
  context: { companyId: string; userId: string | null; roleCodes: string[] },
  fn: (client: pg.PoolClient) => Promise<T>
): Promise<T> {
  const client = await pool.connect();
  try {
    await client.query("BEGIN");
    await client.query(`SELECT set_config('app.company_id', $1, true)`, [context.companyId]);
    if (context.userId) {
      await client.query(`SELECT set_config('app.user_id', $1, true)`, [context.userId]);
    }
    await client.query(`SELECT set_config('app.role_codes', $1, true)`, [context.roleCodes.join(",")]);
    const result = await fn(client);
    await client.query("COMMIT");
    return result;
  } catch (error) {
    await client.query("ROLLBACK");
    throw error;
  } finally {
    client.release();
  }
}

import type pg from "pg";
import type { RuleDefinition } from "../types/rule.types.js";

function mapRule(row: any): RuleDefinition {
  return {
    ruleId: row.rule_id,
    companyId: row.company_id,
    ruleCode: row.rule_code,
    name: row.name,
    description: row.description,
    ruleType: row.rule_type,
    ruleFormat: row.rule_format,
    ruleBody: row.rule_body,
    severityDefault: row.severity_default,
    isMvp: row.is_mvp,
    status: row.status,
    version: row.version
  };
}

export async function getActiveRulesForCompany(
  client: pg.PoolClient,
  companyId: string
): Promise<RuleDefinition[]> {
  const result = await client.query(
    `
    SELECT *
    FROM faro.rule_definitions
    WHERE status = 'active'
      AND rule_type = 'tension'
      AND (company_id IS NULL OR company_id = $1)
    ORDER BY
      CASE WHEN company_id = $1 THEN 0 ELSE 1 END,
      rule_code,
      version DESC
    `,
    [companyId]
  );

  const latestByRuleCode = new Map<string, RuleDefinition>();
  for (const row of result.rows) {
    const rule = mapRule(row);
    if (!latestByRuleCode.has(rule.ruleCode)) {
      latestByRuleCode.set(rule.ruleCode, rule);
    }
  }
  return Array.from(latestByRuleCode.values());
}

export async function getKpiSnapshotsForRule(
  client: pg.PoolClient,
  params: {
    companyId: string;
    periodStart: string;
    periodEnd: string;
    kpiCodes: string[];
    dimensionType?: string;
    dimensionId?: string | null;
  }
): Promise<KpiSnapshotMap> {
  const result = await client.query(
    `
    SELECT *
    FROM faro.kpi_snapshots
    WHERE company_id = $1
      AND period_start = $2
      AND period_end = $3
      AND kpi_code = ANY($4)
      AND dimension_type = COALESCE($5, dimension_type)
      AND ($6::uuid IS NULL OR dimension_id = $6::uuid)
    `,
    [params.companyId, params.periodStart, params.periodEnd, params.kpiCodes,
     params.dimensionType ?? null, params.dimensionId ?? null]
  );

  const map: KpiSnapshotMap = {};
  for (const row of result.rows) {
    const snapshot = mapKpi(row);
    map[snapshot.kpiCode] = snapshot;
  }
  return map;
}

import type { TensionDefinition } from "../types/catalog.types.js";

function mapTensionDefinition(row: any): TensionDefinition {
  return {
    tensionDefinitionId: row.tension_definition_id,
    tensionCode: row.tension_code,
    name: row.name,
    shortName: row.short_name,
    areaCode: row.area_code,
    moduleCode: row.module_code,
    businessQuestion: row.business_question,
    description: row.description,
    executiveDiagnosis: row.executive_diagnosis,
    triggerLogic: row.trigger_logic,
    requiredKpis: row.required_kpis ?? [],
    recommendedActions: row.recommended_actions ?? [],
    evidenceRequired: row.evidence_required ?? [],
    defaultSeverity: row.default_severity,
    severityLogic: row.severity_logic,
    defaultOwnerRole: row.default_owner_role,
    approverRole: row.approver_role,
    scoreDimension: row.score_dimension,
    scoreImpactMin: Number(row.score_impact_min),
    scoreImpactMax: Number(row.score_impact_max),
    mvpPriority: row.mvp_priority,
    demoRelevance: row.demo_relevance,
    industryScope: row.industry_scope ?? [],
    moduleScope: row.module_scope ?? [],
    status: row.status,
    version: Number(row.version),
    metadata: row.metadata ?? {}
  };
}

export async function getActiveTensionDefinition(
  client: pg.PoolClient,
  tensionCode: string
): Promise<TensionDefinition | null> {
  const result = await client.query(
    `
    SELECT *
    FROM faro.tension_definitions
    WHERE tension_code = $1
      AND status = 'active'
    ORDER BY version DESC
    LIMIT 1
    `,
    [tensionCode]
  );
  return result.rows[0] ? mapTensionDefinition(result.rows[0]) : null;
}

export async function assertTensionCodeExists(
  client: pg.PoolClient,
  tensionCode: string
): Promise<void> {
  const definition = await getActiveTensionDefinition(client, tensionCode);
  if (!definition) {
    throw new Error(
      `UNKNOWN_TENSION_CODE: ${tensionCode} does not exist in faro.tension_definitions`
    );
  }
}

export async function getActiveActionDefinitionsByCodes(
  client: pg.PoolClient,
  actionCodes: string[]
): Promise<Map<string, ActionDefinition>> {
  if (actionCodes.length === 0) return new Map();
  const result = await client.query(
    `
    SELECT *
    FROM faro.action_definitions
    WHERE action_code = ANY($1)
      AND status = 'active'
    ORDER BY action_code, version DESC
    `,
    [actionCodes]
  );
  const map = new Map<string, ActionDefinition>();
  for (const row of result.rows) {
    const def = mapActionDefinition(row);
    if (!map.has(def.actionCode)) map.set(def.actionCode, def);
  }
  return map;
}

export async function assertActionCodesExist(
  client: pg.PoolClient,
  actionCodes: string[]
): Promise<void> {
  const defs = await getActiveActionDefinitionsByCodes(client, actionCodes);
  const missing = actionCodes.filter((c) => !defs.has(c));
  if (missing.length > 0) {
    throw new Error(`UNKNOWN_ACTION_CODE: ${missing.join(", ")}`);
  }
}

export async function getActiveEvidenceDefinitionsByCodes(
  client: pg.PoolClient,
  evidenceCodes: string[]
): Promise<Map<string, EvidenceDefinition>> {
  if (evidenceCodes.length === 0) return new Map();
  const result = await client.query(
    `
    SELECT *
    FROM faro.evidence_definitions
    WHERE evidence_code = ANY($1)
      AND status = 'active'
    ORDER BY evidence_code, version DESC
    `,
    [evidenceCodes]
  );
  const map = new Map<string, EvidenceDefinition>();
  for (const row of result.rows) {
    const def = mapEvidenceDefinition(row);
    if (!map.has(def.evidenceCode)) map.set(def.evidenceCode, def);
  }
  return map;
}

export function toEvidenceRequirementPayload(
  d: EvidenceDefinition
): EvidenceRequirementPayload {
  return {
    evidence_code: d.evidenceCode,
    name: d.name,
    evidence_type: d.evidenceType,
    trust_level: d.trustLevel,
    requires_review: d.requiresReview,
    can_close_action: d.canCloseAction,
    confidence_weight: d.confidenceWeight,
    allowed_submission_modes: d.allowedSubmissionModes,
    allowed_file_types: d.allowedFileTypes,
    required_metadata_keys: d.requiredMetadataKeys
  };
}

export type Severity = "low" | "medium" | "high" | "critical";

export type RuleOperator =
  | ">" | ">=" | "<" | "<=" | "==" | "!="
  | "between" | "in" | "not_in"
  | "exists" | "missing"
  | "changed_by_pct" | "older_than_days";

export type Condition = {
  kpi: string;
  metric: string;
  operator: RuleOperator;
  value?: number | string | boolean | Array<number | string>;
};

export type ConditionGroup = {
  all?: Condition[];
  any?: Condition[];
  none?: Condition[];
};

import type { Condition, ConditionGroup } from "../types/rule.types.js";
import type { KpiSnapshotMap } from "../types/kpi.types.js";
import type { ConditionDiagnostic } from "../types/evaluation.types.js";

function getMetricValue(c: Condition, snapshots: KpiSnapshotMap): unknown {
  const s = snapshots[c.kpi];
  if (!s) return undefined;
  switch (c.metric) {
    case "value": return s.value;
    case "reference_value": return s.referenceValue;
    case "delta_value": return s.deltaValue;
    case "delta_pct": return s.deltaPct;
    case "confidence_score": return s.confidenceScore;
    case "status": return s.status;
    default: return (s as any)[c.metric];
  }
}

function compare(actual: unknown, op: string, expected: unknown): boolean {
  if (op === "exists") return actual !== undefined && actual !== null;
  if (op === "missing") return actual === undefined || actual === null;
  if (op === "in") return Array.isArray(expected) && expected.includes(actual as any);
  if (op === "not_in") return Array.isArray(expected) && !expected.includes(actual as any);
  if (op === "between") {
    if (!Array.isArray(expected) || expected.length !== 2) return false;
    if (typeof actual !== "number") return false;
    return actual >= Number(expected[0]) && actual <= Number(expected[1]);
  }
  if (typeof actual !== "number" || typeof expected !== "number") {
    if (op === "==") return actual === expected;
    if (op === "!=") return actual !== expected;
    return false;
  }
  switch (op) {
    case ">": return actual > expected;
    case ">=": return actual >= expected;
    case "<": return actual < expected;
    case "<=": return actual <= expected;
    case "==": return actual === expected;
    case "!=": return actual !== expected;
    case "changed_by_pct": return Math.abs(actual) >= expected;
    case "older_than_days": return actual > expected;
    default: return false;
  }
}

function evaluateCondition(c: Condition, snapshots: KpiSnapshotMap): ConditionDiagnostic {
  const actual = getMetricValue(c, snapshots);
  const passed = compare(actual, c.operator, c.value);
  return {
    kpi: c.kpi, metric: c.metric, operator: c.operator,
    expected: c.value, actual, passed,
    message: passed
      ? `Condition passed: ${c.kpi}.${c.metric} ${c.operator} ${c.value}`
      : `Condition failed: ${c.kpi}.${c.metric} ${c.operator} ${c.value}; actual=${actual}`
  };
}

export function evaluateConditionGroup(
  group: ConditionGroup,
  snapshots: KpiSnapshotMap
): { passed: boolean; diagnostics: ConditionDiagnostic[] } {
  const diagnostics: ConditionDiagnostic[] = [];
  let allPassed = true, anyPassed = true, nonePassed = true;

  if (group.all?.length) {
    const r = group.all.map((c) => evaluateCondition(c, snapshots));
    diagnostics.push(...r);
    allPassed = r.every((x) => x.passed);
  }
  if (group.any?.length) {
    const r = group.any.map((c) => evaluateCondition(c, snapshots));
    diagnostics.push(...r);
    anyPassed = r.some((x) => x.passed);
  }
  if (group.none?.length) {
    const r = group.none.map((c) => evaluateCondition(c, snapshots));
    diagnostics.push(...r);
    nonePassed = r.every((x) => !x.passed);
  }
  return { passed: allPassed && anyPassed && nonePassed, diagnostics };
}

import type { RuleDefinition, Severity } from "../types/rule.types.js";
import type { KpiSnapshotMap } from "../types/kpi.types.js";
import { evaluateConditionGroup } from "./conditionEvaluator.js";

export function calculateSeverity(
  rule: RuleDefinition,
  snapshots: KpiSnapshotMap
): Severity {
  const severity = rule.ruleBody.severity;
  for (const escalation of severity.escalation ?? []) {
    const result = evaluateConditionGroup(escalation.when, snapshots);
    if (result.passed) return escalation.set;
  }
  return severity.default;
}

import type { Severity } from "../types/rule.types.js";
import { evaluatorConfig } from "../config/evaluator.config.js";

export function calculatePriorityScore(params: {
  severity: Severity;
  confidenceScore: number | null;
  scoreImpact: number | null;
}): number {
  const base = evaluatorConfig.priority[params.severity];

  // confianza alta → bonus; baja → penalty
  const confidenceAdjustment =
    params.confidenceScore === null
      ? -10
      : params.confidenceScore >= 85
        ? 5
        : params.confidenceScore < 70
          ? -10
          : 0;

  // impacto absoluto en Score, clamp a 10
  const impactAdjustment =
    params.scoreImpact === null
      ? 0
      : Math.min(10, Math.abs(params.scoreImpact));

  const result = base + confidenceAdjustment + impactAdjustment;
  return Math.max(0, Math.min(100, Number(result.toFixed(2))));
}

export function validateConfidence(
  rule: RuleDefinition,
  snapshots: KpiSnapshotMap
): { passed: boolean; confidenceScore: number | null; warnings: string[] } {
  const requiredKpis = rule.ruleBody.data_requirements.required_kpis;
  const minimum = rule.ruleBody.data_requirements.minimum_confidence_score;
  const confidenceValues: number[] = [];
  const warnings: string[] = [];

  for (const kpiCode of requiredKpis) {
    const s = snapshots[kpiCode];
    if (!s) continue;
    if (s.confidenceScore === null) {
      warnings.push(`KPI ${kpiCode} has no confidence_score`);
      continue;
    }
    confidenceValues.push(s.confidenceScore);
    if (s.confidenceScore < minimum) {
      warnings.push(`KPI ${kpiCode} confidence ${s.confidenceScore} is below minimum ${minimum}`);
    }
  }

  if (confidenceValues.length === 0) {
    return { passed: false, confidenceScore: null, warnings: ["No confidence scores available"] };
  }
  const avg = confidenceValues.reduce((sum, v) => sum + v, 0) / confidenceValues.length;
  return { passed: avg >= minimum, confidenceScore: Number(avg.toFixed(2)), warnings };
}

// Estados abiertos (tensiones que cuentan para deduplicacion).
// 'escalated' es evento, no estado terminal: la tension sigue abierta.
export const OPEN_TENSION_STATUSES = [
  "new",
  "in_analysis",
  "in_execution",
  "in_verification",
  "expired",
  "escalated"
];

export function buildEvaluationKey(params: {
  companyId: string;
  tensionCode: string;
  periodStart: string;
  periodEnd: string;
  dimensionType?: string;
  dimensionId?: string | null;
}): string {
  return [
    params.companyId,
    params.tensionCode,
    params.periodStart,
    params.periodEnd,
    params.dimensionType ?? "company",
    params.dimensionId ?? "null"
  ].join(":");
}

export function calculateScoreImpact(params: {
  base: number;
  max?: number;
  severity: Severity;
}): number {
  const severityMultiplier: Record<Severity, number> = {
    low: 0.5, medium: 0.75, high: 1, critical: 1.25
  };
  const raw = params.base * severityMultiplier[params.severity];
  if (params.max === undefined) return Number(raw.toFixed(2));
  const maxAbs = Math.abs(params.max);
  if (raw < 0) return Number(Math.max(raw, -maxAbs).toFixed(2));
  return Number(Math.min(raw, maxAbs).toFixed(2));
}

import type pg from "pg";
import type { RuleDefinition } from "../types/rule.types.js";
import { assertTensionCodeExists } from "../db/tensionCatalogRepository.js";
import { assertActionCodesExist } from "../db/actionCatalogRepository.js";
import { assertEvidenceCodesExist } from "../db/evidenceCatalogRepository.js";

export async function validateRuleAgainstCatalogs(
  client: pg.PoolClient,
  rule: RuleDefinition
): Promise<{ valid: boolean; warnings: string[] }> {
  const warnings: string[] = [];

  // 1. Tension code DEBE existir en catalogo
  await assertTensionCodeExists(client, rule.ruleBody.tension_code);

  // 2. Action codes DEBEN existir todos
  const actionCodes = rule.ruleBody.output.recommended_actions ?? [];
  await assertActionCodesExist(client, actionCodes);

  // 3. Evidence codes DEBEN existir todos
  const evidenceCodes = rule.ruleBody.output.evidence_required ?? [];
  await assertEvidenceCodesExist(client, evidenceCodes);

  // 4. Warning si RULE-TNS-XXX no coincide con TNS-XXX
  const ruleNumber = rule.ruleCode.replace("RULE-TNS-", "");
  const tensionNumber = rule.ruleBody.tension_code.replace("TNS-", "");
  if (ruleNumber !== tensionNumber) {
    warnings.push(
      `RULE_TENSION_CODE_MISMATCH: ${rule.ruleCode} points to ${rule.ruleBody.tension_code}`
    );
  }

  return { valid: true, warnings };
}

export async function buildEvidenceRequirementsPayload(
  client: pg.PoolClient,
  evidenceCodes: string[]
): Promise<{
  evidenceCodes: string[];
  requirements: EvidenceRequirementPayload[];
  missingEvidenceCodes: string[];
}> {
  const uniqueCodes = Array.from(new Set(evidenceCodes));
  const definitions = await getActiveEvidenceDefinitionsByCodes(client, uniqueCodes);

  const requirements: EvidenceRequirementPayload[] = [];
  const missingEvidenceCodes: string[] = [];

  for (const code of uniqueCodes) {
    const definition = definitions.get(code);
    if (!definition) {
      missingEvidenceCodes.push(code);
      continue;
    }
    requirements.push(toEvidenceRequirementPayload(definition));
  }
  return { evidenceCodes: uniqueCodes, requirements, missingEvidenceCodes };
}

// Helpers de merge (declarados al inicio del archivo)
function uniqueArray(values: string[]): string[] {
  return Array.from(new Set(values.filter(Boolean)));
}

// ====== Bloque que reemplaza la creacion vieja de tension ======

if (!result.triggered) {
  continue;
}

summary.rulesTriggered++;

if (!rule.ruleBody.output.create_tension) {
  continue;
}

// 1. Validar la regla contra los tres catalogos (bloquea si falta algo)
const catalogValidation = await validateRuleAgainstCatalogs(client, rule);

// 2. Cargar TensionDefinition canonica
const tensionDefinition = await getActiveTensionDefinition(
  client,
  rule.ruleBody.tension_code
);

if (!tensionDefinition) {
  summary.errors++;
  console.error(`Missing canonical tension definition: ${rule.ruleBody.tension_code}`);
  continue;
}

const yamlOutput = rule.ruleBody.output;

// 3. Merge: YAML + catalogo → lista canonica de acciones recomendadas
const recommendedActionCodes = uniqueArray([
  ...(yamlOutput.recommended_actions ?? []),
  ...(tensionDefinition.recommendedActions ?? [])
]);

// 4. Merge: YAML + catalogo → lista canonica de evidencia requerida
const evidenceCodes = uniqueArray([
  ...(yamlOutput.evidence_required ?? []),
  ...(tensionDefinition.evidenceRequired ?? [])
]);

// 5. Cargar payload enriquecido de cada evidencia (bloquea si falta una)
const evidencePayload = await buildEvidenceRequirementsPayload(client, evidenceCodes);

if (evidencePayload.missingEvidenceCodes.length > 0) {
  throw new Error(
    `UNKNOWN_EVIDENCE_CODE for ${tensionDefinition.tensionCode}: ${evidencePayload.missingEvidenceCodes.join(", ")}`
  );
}

// 6. Resolver responsable: YAML > catalogo > fallback "general_manager"
const ownerRole =
  yamlOutput.assign_to_role ||
  tensionDefinition.defaultOwnerRole ||
  "general_manager";

const approverRole =
  yamlOutput.approver_role ||
  tensionDefinition.approverRole ||
  "director";

const responsibleUserId = await resolveResponsibleUser(client, {
  companyId: context.companyId,
  logicalRole: ownerRole
});

const approverUserId = approverRole
  ? await resolveResponsibleUser(client, {
      companyId: context.companyId,
      logicalRole: approverRole
    })
  : null;

// 7. Diagnostico: template YAML > executive_diagnosis catalogo > description catalogo
const diagnosis = buildDiagnosisText({
  template:
    yamlOutput.diagnosis_template ||
    tensionDefinition.executiveDiagnosis ||
    tensionDefinition.description,
  diagnostics: result.diagnostics
});

// 8. Idempotencia: buscar tension abierta del mismo periodo/dimension
const existing = await findOpenTension(client, {
  companyId: context.companyId,
  tensionCode: tensionDefinition.tensionCode,
  periodStart: context.periodStart,
  periodEnd: context.periodEnd,
  dimensionType: context.dimensionType ?? "company",
  dimensionId: context.dimensionId ?? null
});

let tensionId: string;

// 9. Payload canonico enriquecido para la tension
const tensionPayload = {
  canonical: true,
  catalog_source: "faro.tension_definitions",
  tension_definition_id: tensionDefinition.tensionDefinitionId,
  tension_code: tensionDefinition.tensionCode,
  tension_name: tensionDefinition.name,
  business_question: tensionDefinition.businessQuestion,
  executive_diagnosis: tensionDefinition.executiveDiagnosis,
  trigger_logic: tensionDefinition.triggerLogic,
  score_dimension: tensionDefinition.scoreDimension,
  rule_code: rule.ruleCode,
  rule_version: rule.version,
  period_start: context.periodStart,
  period_end: context.periodEnd,
  dimension_type: context.dimensionType ?? "company",
  dimension_id: context.dimensionId ?? "null",
  diagnostics: result.diagnostics,
  warnings: [
    ...result.warnings,
    ...(catalogValidation.warnings ?? [])
  ],
  recommended_actions: recommendedActionCodes,
  evidence_required: evidencePayload.evidenceCodes,
  evidence_requirements: evidencePayload.requirements,
  missing_evidence_codes: evidencePayload.missingEvidenceCodes
};

const title =
  yamlOutput.title ||
  tensionDefinition.name ||
  tensionDefinition.tensionCode;

const description = [
  diagnosis,
  tensionDefinition.executiveDiagnosis
    ? `Lectura ejecutiva:\n${tensionDefinition.executiveDiagnosis}`
    : null
].filter(Boolean).join("\n\n");

// 10. Crear o actualizar tension (respeta idempotencia)
if (context.dryRun) {
  tensionId = "dry-run";
} else if (existing) {
  tensionId = existing.tension_id;
  await updateExistingTension(client, {
    tensionId,
    ruleEvaluationId,
    severity: result.severity ?? tensionDefinition.defaultSeverity,
    priorityScore: result.priorityScore ?? 0,
    confidenceScore: result.confidenceScore,
    description,
    scoreImpact: result.scoreImpact,
    payload: tensionPayload
  });
  summary.tensionsUpdated++;
} else {
  tensionId = await createTension(client, {
    companyId: context.companyId,
    ruleEvaluationId,
    tensionCode: tensionDefinition.tensionCode,
    title,
    description,
    severity: result.severity ?? tensionDefinition.defaultSeverity,
    priorityScore: result.priorityScore ?? 0,
    confidenceScore: result.confidenceScore,
    responsibleUserId,
    dueAt: null,
    scoreImpact: result.scoreImpact,
    payload: tensionPayload
  });
  summary.tensionsCreated++;
}

// 11. Crear acciones desde catalogo (action_definitions, no hardcoded)
const shouldCreateActions =
  context.createActions ?? evaluatorConfig.defaultCreateActions;

if (shouldCreateActions && !context.dryRun) {
  const actionsResult = await createRecommendedActions({
    client,
    companyId: context.companyId,
    tensionId,
    tensionCode: tensionDefinition.tensionCode,
    actionCodes: recommendedActionCodes,
    responsibleUserId,
    approverUserId,
    fallbackPriority: mapSeverityToPriority(result.severity),
    fallbackSlaDays: yamlOutput.default_sla_days,
    createdBy: context.userId,
    evidenceRequiredCodesFromRule: evidencePayload.evidenceCodes
  });

  summary.actionsCreated += actionsResult.createdActionIds.length;

  if (actionsResult.missingActionCodes.length > 0) {
    summary.warnings += actionsResult.missingActionCodes.length;
    console.warn(
      `Missing action definitions for ${tensionDefinition.tensionCode}: ${actionsResult.missingActionCodes.join(", ")}`
    );
  }
}

// ANTES (ENG-003 base): objeto hardcodeado dentro del archivo
// const ACTION_CATALOG = { "ACT-COM-001": { title, description, ... } };
// DESPUES (ENG-003.1 aplicado): consulta action_definitions, sin hardcoded.

import { getActiveActionDefinitionsByCodes } from "../db/actionCatalogRepository.js";
import { buildEvidenceRequirementsPayload } from "./evidenceRequirementService.js";

export async function createRecommendedActions(params: {
  client: pg.PoolClient;
  companyId: string;
  tensionId: string;
  tensionCode: string;
  actionCodes: string[];
  responsibleUserId: string | null;
  approverUserId: string | null;
  fallbackPriority: string;
  fallbackSlaDays: number;
  createdBy: string | null;
  evidenceRequiredCodesFromRule: string[];
}): Promise<{
  createdActionIds: string[];
  skippedActionCodes: string[];
  missingActionCodes: string[];
}> {
  const createdActionIds: string[] = [];
  const skippedActionCodes: string[] = [];
  const missingActionCodes: string[] = [];

  const uniqueActionCodes = Array.from(new Set(params.actionCodes));
  const definitions = await getActiveActionDefinitionsByCodes(params.client, uniqueActionCodes);

  for (const actionCode of uniqueActionCodes) {
    const definition = definitions.get(actionCode);

    if (!definition) {
      missingActionCodes.push(actionCode);
      continue; // warning, no error (la accion no esta en catalogo)
    }

    const existing = await findExistingActionForTension(params.client, {
      companyId: params.companyId,
      tensionId: params.tensionId,
      actionCode
    });
    if (existing) {
      skippedActionCodes.push(actionCode);
      continue; // idempotencia: ya existe abierta
    }

    // Responsable: explicito > catalogo > fallback
    const responsibleUserId =
      params.responsibleUserId ??
      (await resolveResponsibleUser(params.client, {
        companyId: params.companyId,
        logicalRole: definition.defaultOwnerRole
      }));

    const approverUserId =
      params.approverUserId ??
      (definition.approverRole
        ? await resolveResponsibleUser(params.client, {
            companyId: params.companyId,
            logicalRole: definition.approverRole
          })
        : null);

    // Evidencia: catalogo de la accion > evidencia heredada de la regla
    const evidenceCodes =
      definition.evidenceRequiredCodes.length > 0
        ? definition.evidenceRequiredCodes
        : params.evidenceRequiredCodesFromRule;

    const evidencePayload = await buildEvidenceRequirementsPayload(
      params.client, evidenceCodes
    );

    if (evidencePayload.missingEvidenceCodes.length > 0) {
      throw new Error(
        `UNKNOWN_EVIDENCE_CODE for action ${actionCode}: ${evidencePayload.missingEvidenceCodes.join(", ")}`
      );
    }

    const dueDate = addDays(new Date(), definition.defaultSlaDays || params.fallbackSlaDays);

    const expectedRecovery =
      definition.expectedScoreRecoveryMax > 0
        ? definition.expectedScoreRecoveryMax
        : null;

    const actionId = await createAction(params.client, {
      companyId: params.companyId,
      tensionId: params.tensionId,
      actionCode: definition.actionCode,
      title: definition.name,
      description: definition.description,
      actionType: definition.actionType,
      responsibleUserId,
      approverUserId,
      priority: definition.defaultPriority || params.fallbackPriority,
      dueDate,
      evidenceRequired: definition.evidenceRequired,
      closureCriteria: definition.closureCriteria,
      createdBy: params.createdBy,
      expectedImpact: definition.expectedBusinessImpact,
      expectedImpactAmount: expectedRecovery,
      payload: {
        created_by_engine: true,
        catalog_source: "faro.action_definitions",
        action_definition_id: definition.actionDefinitionId,
        action_family: definition.actionFamily,
        executive_purpose: definition.executivePurpose,
        success_metric: definition.successMetric,
        score_dimension: definition.scoreDimension,
        expected_score_recovery_min: definition.expectedScoreRecoveryMin,
        expected_score_recovery_max: definition.expectedScoreRecoveryMax,
        triggered_by_tension_code: params.tensionCode,
        evidence_required_codes: evidencePayload.evidenceCodes,
        evidence_requirements: evidencePayload.requirements
      }
    });

    createdActionIds.push(actionId);
  }

  return { createdActionIds, skippedActionCodes, missingActionCodes };
}

import { withFaroDbContext } from "../db/db.js";
import { getActiveRulesForCompany } from "../db/ruleRepository.js";
import { getActiveTensionDefinition } from "../db/tensionCatalogRepository.js";

export async function explainCommand(params: {
  companyId: string;
  periodStart: string;
  periodEnd: string;
}) {
  await withFaroDbContext(
    {
      companyId: params.companyId,
      userId: null,
      roleCodes: ["integration_service", "faro_owner", "company_admin"]
    },
    async (client) => {
      const rules = await getActiveRulesForCompany(client, params.companyId);

      console.log("FARO Evaluation Context");
      console.log("-----------------------");
      console.log(`Company: ${params.companyId}`);
      console.log(`Period:  ${params.periodStart} → ${params.periodEnd}`);
      console.log(`Active rules: ${rules.length}`);
      console.log("");

      for (const rule of rules) {
        // NEW: resolver definicion canonica de la tension
        const definition = await getActiveTensionDefinition(
          client,
          rule.ruleBody.tension_code
        );

        console.log(
          `${rule.ruleCode} → ${rule.ruleBody.tension_code} · ${definition?.name ?? rule.name}`
        );
        console.log(`  KPIs: ${rule.ruleBody.data_requirements.required_kpis.join(", ")}`);
        console.log(`  Score dimension: ${definition?.scoreDimension ?? "unknown"}`);
        console.log(
          `  Owner role: ${definition?.defaultOwnerRole ?? rule.ruleBody.output.assign_to_role}`
        );
        console.log(
          `  Actions: ${(definition?.recommendedActions ?? rule.ruleBody.output.recommended_actions).join(", ")}`
        );
        console.log(
          `  Evidence: ${(definition?.evidenceRequired ?? rule.ruleBody.output.evidence_required).join(", ")}`
        );
        console.log("");
      }
    }
  );
}

# Dry-run (no escribe, solo evalua)
tsx src/cli.ts dry-run \
  --company-id 10000000-0000-0000-0000-000000000001 \
  --period-start 2026-05-01 \
  --period-end 2026-05-31 \
  --user-id 12000000-0000-0000-0000-000000000001 \
  --roles integration_service,faro_owner,company_admin

# Evaluacion real (crea tensions + actions enriquecidas)
tsx src/cli.ts evaluate \
  --company-id 10000000-0000-0000-0000-000000000001 \
  --period-start 2026-05-01 \
  --period-end 2026-05-31

# Explain con catalogo canonico (patch 003.1)
tsx src/cli.ts explain \
  --company-id 10000000-0000-0000-0000-000000000001 \
  --period-start 2026-05-01 \
  --period-end 2026-05-31

import { describe, expect, it } from "vitest";
import { evaluateConditionGroup } from "../src/engine/conditionEvaluator.js";
import { evaluateRule } from "../src/engine/evaluator.js";

describe("FARO evaluator", () => {
  it("evaluates all conditions as true", () => {
    const result = evaluateConditionGroup(
      { all: [{ kpi: "KPI-SAL-001", metric: "delta_pct", operator: ">=", value: 0.1 }] },
      {
        "KPI-SAL-001": {
          kpiSnapshotId: "1", companyId: "company", kpiCode: "KPI-SAL-001",
          periodStart: "2026-05-01", periodEnd: "2026-05-31",
          dimensionType: "company", dimensionId: null,
          value: 100, referenceValue: 80, deltaValue: 20, deltaPct: 0.25,
          status: "ok", confidenceScore: 90,
          sourceSnapshot: {}, calculatedAt: new Date().toISOString()
        }
      }
    );
    expect(result.passed).toBe(true);
  });
});

describe("Catalog integration", () => {
  it("loads canonical tension definition", async () => {
    await withTestDbContext({ companyId: COMPANY_ID }, async (client) => {
      const def = await getActiveTensionDefinition(client, "TNS-001");
      expect(def).toBeTruthy();
      expect(def?.name).toBe("Crecimiento no rentable");
      expect(def?.recommendedActions).toContain("ACT-COM-001");
      expect(def?.evidenceRequired).toContain("EVD-007");
    });
  });

  it("creates actions enriched with evidence requirements", async () => {
    await withTestDbContext({ companyId: COMPANY_ID, userId: USER_ID }, async (client) => {
      const summary = await runEvaluation(client, {
        companyId: COMPANY_ID, userId: USER_ID,
        roleCodes: ["integration_service", "faro_owner", "company_admin"],
        periodStart: "2026-05-01", periodEnd: "2026-05-31",
        dryRun: false, createActions: true
      });
      expect(summary.rulesEvaluated).toBeGreaterThan(0);
      expect(summary.errors).toBe(0);

      const result = await client.query(`
        SELECT a.action_code, a.payload->'evidence_requirements' AS er
        FROM faro.actions a
        WHERE a.company_id = $1
          AND a.payload->>'created_by_engine' = 'true'
      `, [COMPANY_ID]);

      expect(result.rows.length).toBeGreaterThan(0);
      for (const row of result.rows) {
        expect(row.er).toBeTruthy();
        expect(row.er.length).toBeGreaterThan(0);
      }
    });
  });
});

{
  "canonical": true,
  "catalog_source": "faro.tension_definitions",
  "tension_definition_id": "...",
  "tension_code": "TNS-001",
  "tension_name": "Crecimiento no rentable",
  "business_question": "¿Estamos vendiendo mas pero ganando menos?",
  "executive_diagnosis": "La empresa crece en volumen pero sacrifica rentabilidad.",
  "trigger_logic": "Ventas netas suben + margen bruto cae + descuento promedio sube.",
  "score_dimension": "commercial_health",
  "rule_code": "RULE-TNS-001",
  "rule_version": 1,
  "period_start": "2026-05-01",
  "period_end": "2026-05-31",
  "recommended_actions": ["ACT-COM-001", "ACT-COM-002", "ACT-COM-003"],
  "evidence_required": ["EVD-007", "EVD-012"],
  "evidence_requirements": [
    {
      "evidence_code": "EVD-007",
      "name": "Cambio de politica",
      "evidence_type": "policy_change",
      "trust_level": "critical",
      "requires_review": true,
      "can_close_action": true,
      "confidence_weight": 0.95
    },
    {
      "evidence_code": "EVD-012",
      "name": "Validacion de direccion",
      "evidence_type": "executive_validation",
      "trust_level": "critical",
      "requires_review": true,
      "can_close_action": true,
      "confidence_weight": 1.0
    }
  ]
}

{
  "created_by_engine": true,
  "catalog_source": "faro.action_definitions",
  "action_definition_id": "...",
  "action_family": "commercial",
  "executive_purpose": "Recuperar margen y evitar crecimiento comprado con descuentos excesivos.",
  "success_metric": "Reduccion del descuento promedio y recuperacion de margen bruto.",
  "score_dimension": "commercial_health",
  "expected_score_recovery_min": 3,
  "expected_score_recovery_max": 8,
  "triggered_by_tension_code": "TNS-001",
  "evidence_required_codes": ["EVD-007", "EVD-012"],
  "evidence_requirements": [/* mismo formato canonico */]
}