Prop Firm Technology For FTMO's Consistency Rule Change: A Versioned Rule Engine Pinned To Order Time, With Reproducible Payout Decisions

// Node 20+: node --test, through a TypeScript loader such as tsx or after compiling
import { test } from "node:test";
import assert from "node:assert/strict";
import { buildRegistry, evaluate, platformTimeToUtc, type DailyResult } from "./ruleRegistry";

// 60% is an illustration for these tests only. Real thresholds come from the firm's published rule text.
const registry = buildRegistry({ bestDayMaxShareBps: 6_000, consistencyMaxShareBps: 6_000, passOnEqual: true });
const bestDay = registry.byId("best-day.v1");
const consistency = registry.byId("consistency.v2");

// FinanceFeeds' worked example, in integer cents.
const days: DailyResult[] = [
  { tradingDay: "2026-10-12", netCents: 400_000 },
  { tradingDay: "2026-10-13", netCents: 200_000 },
  { tradingDay: "2026-10-14", netCents: -200_000 },
  { tradingDay: "2026-10-15", netCents: 200_000 },
  { tradingDay: "2026-10-16", netCents: -100_000 },
];
const withDay5 = (netCents: number) =>
  days.map((d) => (d.tradingDay === "2026-10-16" ? { ...d, netCents } : d));

test("Best Day Rule: $4,000 divided by $8,000 of positive days is 50%", () => {
  const r = evaluate(bestDay, days);
  assert.equal(r.bestDayCents, 400_000);
  assert.equal(r.denominatorCents, 800_000);
  assert.equal(r.shareBps, 5_000);
  assert.equal(r.status, "MET");
});

test("Consistency rule: $4,000 divided by $5,000 of total profit is 80%", () => {
  const r = evaluate(consistency, days);
  assert.equal(r.denominatorCents, 500_000);
  assert.equal(r.shareBps, 8_000);
  assert.equal(r.status, "NOT_YET_MET"); // not a breach: the account keeps trading
});

test("a bigger loss on day 5 moves only the Consistency share", () => {
  assert.equal(evaluate(bestDay, withDay5(-150_000)).shareBps, 5_000);
  assert.equal(evaluate(consistency, withDay5(-150_000)).shareBps, 8_889); // 4,000 / 4,500
});

test("no net profit means no share, and no share is never met", () => {
  const r = evaluate(consistency, withDay5(-600_000));
  assert.equal(r.shareBps, null);
  assert.equal(r.status, "NOT_YET_MET");
});

test("the rule is pinned by order creation time in platform time (GMT+3)", () => {
  assert.equal(registry.forOrder(platformTimeToUtc("2026-10-12T08:59:59", 180)).id, "best-day.v1");
  assert.equal(registry.forOrder(platformTimeToUtc("2026-10-12T09:00:00", 180)).id, "consistency.v2");
  // 08:30 in London (BST, UTC+1) is 10:30 GMT+3: already the new rule.
  assert.equal(registry.forOrder(Date.parse("2026-10-12T08:30:00+01:00")).id, "consistency.v2");
});

// Node 20+, no dependencies. Money is integer cents; time is UTC epoch milliseconds.
import { createHash } from "node:crypto";

export type Formula = "BEST_DAY_OVER_POSITIVE_DAYS" | "BEST_DAY_OVER_TOTAL_PROFIT";

/** One row per closed trading day, summed by the platform's trading day, not the server's. */
export interface DailyResult { tradingDay: string; netCents: number }

export interface RuleVersion {
  id: string;
  formula: Formula;
  maxShareBps: number;             // from the firm's published rule text; 10_000 bps = 100%
  passOnEqual: boolean;            // does a share exactly at the threshold meet it?
  ordersFromUtc: number;           // inclusive, by order creation time
  ordersBeforeUtc: number | null;  // exclusive; null marks the current version
  sourceRef: string;               // the rule text this version implements
}

export interface Evaluation {
  ruleVersionId: string;
  ruleVersionHash: string;
  bestDayCents: number;
  denominatorCents: number;
  shareBps: number | null;         // rounded, for display only
  status: "MET" | "NOT_YET_MET";   // neither rule can be breached: not met means keep trading
}

/** "2026-10-12T09:00:00" at the offset the firm published for that instant, to UTC. */
export function platformTimeToUtc(local: string, offsetMinutes: number): number {
  if (!/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/.test(local)) throw new Error(`not a platform timestamp: ${local}`);
  return Date.parse(`${local}Z`) - offsetMinutes * 60_000;
}

// FTMO trading update, 8 October 2026: new orders from 12 October 2026, 9:00 GMT+3 (06:00 UTC).
export const CUTOVER_UTC = platformTimeToUtc("2026-10-12T09:00:00", 180);

const sha256 = (s: string) => createHash("sha256").update(s).digest("hex");

export const versionHash = (v: Readonly<RuleVersion>) =>
  sha256(JSON.stringify([v.id, v.formula, v.maxShareBps, v.passOnEqual, v.ordersFromUtc, v.ordersBeforeUtc]));

export class RuleRegistry {
  private readonly versions: readonly Readonly<RuleVersion>[];

  constructor(versions: RuleVersion[]) {
    if (new Set(versions.map((v) => v.id)).size !== versions.length) throw new Error("duplicate rule version id");
    const sorted = [...versions].sort((a, b) => a.ordersFromUtc - b.ordersFromUtc);
    sorted.forEach((v, i) => {
      const next = sorted[i + 1];
      if (v.maxShareBps <= 0 || v.maxShareBps > 10_000) throw new Error(`${v.id}: threshold out of range`);
      if (next ? v.ordersBeforeUtc !== next.ordersFromUtc : v.ordersBeforeUtc !== null) {
        throw new Error(`${v.id}: windows must be contiguous, and only the last may be open-ended`);
      }
    });
    this.versions = Object.freeze(sorted.map((v) => Object.freeze({ ...v })));
  }

  /** Fixed by when the order was created. Never by "now", never by account activation. */
  forOrder(orderCreatedAtUtc: number): Readonly<RuleVersion> {
    const v = this.versions.find((r) => orderCreatedAtUtc >= r.ordersFromUtc &&
      (r.ordersBeforeUtc === null || orderCreatedAtUtc < r.ordersBeforeUtc));
    if (!v) throw new Error(`no rule version for an order created at ${new Date(orderCreatedAtUtc).toISOString()}`);
    return v;
  }

  byId(id: string): Readonly<RuleVersion> {
    const v = this.versions.find((r) => r.id === id);
    if (!v) throw new Error(`unknown rule version ${id}`);
    return v;
  }
}

/** Thresholds are configuration reviewed against the firm's rule text, never constants in code. */
export function buildRegistry(cfg: { bestDayMaxShareBps: number; consistencyMaxShareBps: number; passOnEqual: boolean }) {
  return new RuleRegistry([
    { id: "best-day.v1", formula: "BEST_DAY_OVER_POSITIVE_DAYS", maxShareBps: cfg.bestDayMaxShareBps,
      passOnEqual: cfg.passOnEqual, ordersFromUtc: 0, ordersBeforeUtc: CUTOVER_UTC,
      sourceRef: "Trading Objectives: Best Day Rule" },
    { id: "consistency.v2", formula: "BEST_DAY_OVER_TOTAL_PROFIT", maxShareBps: cfg.consistencyMaxShareBps,
      passOnEqual: cfg.passOnEqual, ordersFromUtc: CUTOVER_UTC, ordersBeforeUtc: null,
      sourceRef: "Trading update, 8 October 2026; Trading Objectives: Consistency rule" },
  ]);
}

/** Pure and deterministic: same version, same rows, same answer on any machine. */
export function evaluate(v: Readonly<RuleVersion>, days: readonly DailyResult[]): Evaluation {
  const seen = new Set<string>();
  for (const d of days) {
    if (!Number.isSafeInteger(d.netCents)) throw new Error(`${d.tradingDay}: P&L must be integer cents`);
    if (seen.has(d.tradingDay)) throw new Error(`${d.tradingDay}: duplicate trading day`);
    seen.add(d.tradingDay);
  }
  const bestDayCents = days.reduce((m, d) => Math.max(m, d.netCents), 0);
  const denominatorCents = v.formula === "BEST_DAY_OVER_POSITIVE_DAYS"
    ? days.reduce((s, d) => s + Math.max(d.netCents, 0), 0)  // Positive Days' Profit only
    : days.reduce((s, d) => s + d.netCents, 0);             // total profit: losing days count
  const base = { ruleVersionId: v.id, ruleVersionHash: versionHash(v), bestDayCents, denominatorCents };
  if (bestDayCents <= 0 || denominatorCents <= 0) return { ...base, shareBps: null, status: "NOT_YET_MET" };

  // Decide on exact integers. The rounded share is for the dashboard, never for the decision.
  const lhs = bestDayCents * 10_000;
  const rhs = v.maxShareBps * denominatorCents;
  const met = v.passOnEqual ? lhs <= rhs : lhs < rhs;
  return { ...base, shareBps: Math.round(lhs / denominatorCents), status: met ? "MET" : "NOT_YET_MET" };
}

// Node 20+. Recompute from the ledger, record what was used, and send every refusal to a person.
import { createHash, randomUUID } from "node:crypto";
import { evaluate, type DailyResult, type Evaluation, type RuleRegistry } from "../rules/ruleRegistry";

export interface FundedAccount {
  accountId: string;
  orderId: string;
  orderCreatedAtUtc: number;     // from the order record, never from account activation
  pinnedRuleVersionId: string;   // written once, when the order was created
}

export interface Ledger {
  /** Closed trading days only, summed by the platform's trading day from the deal history. */
  dailyResults(accountId: string, throughTradingDay: string): Promise<DailyResult[]>;
}
export interface AuditLog { append(event: { kind: string } & Record<string, unknown>): Promise<void> } // insert-only
export interface ReviewQueue { enqueue(d: EligibilityDecision): Promise<void> }
export interface PayoutApprovals { request(d: EligibilityDecision): Promise<{ approvalId: string }> } // a second person releases money
export interface KillSwitch { isOn(scope: "payouts"): Promise<boolean> }

export interface EligibilityDecision {
  decisionId: string; accountId: string; orderId: string; decidedAt: string; engineVersion: string;
  throughTradingDay: string; amountCents: number;
  days: DailyResult[]; inputsHash: string;   // the rows themselves, and proof they have not changed
  evaluation: Evaluation;
  dashboardShareBps: number | null;           // the figure the trader was shown
  outcome: "SEND_FOR_APPROVAL" | "REFER_TO_REVIEWER";
  reasons: string[];
}

const ENGINE_VERSION = process.env.RULE_ENGINE_VERSION ?? "";   // e.g. the git SHA of this build
const MAX_AUTO_PAYOUT_CENTS = Number(process.env.MAX_AUTO_PAYOUT_CENTS ?? "0");
if (!ENGINE_VERSION) throw new Error("RULE_ENGINE_VERSION is required: every decision names the code that made it");

const sha256 = (s: string) => createHash("sha256").update(s).digest("hex");
const canonical = (days: readonly DailyResult[]): DailyResult[] =>
  days.map(({ tradingDay, netCents }) => ({ tradingDay, netCents }))
    .sort((a, b) => a.tradingDay.localeCompare(b.tradingDay));
const COMPARED = ["ruleVersionHash", "bestDayCents", "denominatorCents", "shareBps", "status"] as const;

export class PayoutEligibilityWorkflow {
  constructor(
    private readonly registry: RuleRegistry, private readonly ledger: Ledger, private readonly audit: AuditLog,
    private readonly reviewers: ReviewQueue, private readonly approvals: PayoutApprovals, private readonly kill: KillSwitch,
  ) {}

  async decide(acc: FundedAccount, throughTradingDay: string, amountCents: number,
    dashboardShareBps: number | null): Promise<EligibilityDecision> {
    const reasons: string[] = [];
    if (await this.kill.isOn("payouts")) reasons.push("payout kill switch is on");

    // The pin is the contract. If it disagrees with the order time, a person decides; code never re-pins.
    const fromOrderTime = this.registry.forOrder(acc.orderCreatedAtUtc).id;
    if (fromOrderTime !== acc.pinnedRuleVersionId) {
      reasons.push(`pinned ${acc.pinnedRuleVersionId}, order time gives ${fromOrderTime}`);
    }
    const rule = this.registry.byId(acc.pinnedRuleVersionId);

    // Recompute from the ledger every time. A cached metric is a claim, not an input.
    const days = canonical(await this.ledger.dailyResults(acc.accountId, throughTradingDay));
    const evaluation = evaluate(rule, days);
    if (evaluation.status === "NOT_YET_MET") reasons.push(`${rule.id} not yet met: not a breach, the account keeps trading`);
    if (dashboardShareBps !== evaluation.shareBps) {
      reasons.push(`dashboard showed ${dashboardShareBps} bps, ledger gives ${evaluation.shareBps}`);
    }
    if (!Number.isSafeInteger(amountCents) || amountCents <= 0 || amountCents > MAX_AUTO_PAYOUT_CENTS) {
      reasons.push("amount outside the automatic limit");
    }

    const decision: EligibilityDecision = {
      decisionId: randomUUID(), accountId: acc.accountId, orderId: acc.orderId, decidedAt: new Date().toISOString(),
      engineVersion: ENGINE_VERSION, throughTradingDay, amountCents, days, inputsHash: sha256(JSON.stringify(days)),
      evaluation, dashboardShareBps, outcome: reasons.length ? "REFER_TO_REVIEWER" : "SEND_FOR_APPROVAL", reasons,
    };
    await this.audit.append({ kind: "eligibility_decided", ...decision }); // no audit record, no decision

    if (decision.outcome === "REFER_TO_REVIEWER") {
      await this.reviewers.enqueue(decision);
    } else {
      const { approvalId } = await this.approvals.request(decision);
      await this.audit.append({ kind: "payout_approval_requested", decisionId: decision.decisionId, approvalId });
    }
    return decision;
  }

  /** For a dispute: same pinned rule, same rows, same answer. Any difference is the finding. */
  replay(d: EligibilityDecision) {
    const rows = canonical(d.days);
    const now = evaluate(this.registry.byId(d.evaluation.ruleVersionId), rows);
    return {
      now,
      rowsUnchanged: sha256(JSON.stringify(rows)) === d.inputsHash,
      sameAnswer: COMPARED.every((k) => now[k] === d.evaluation[k]),
      sameEngine: d.engineVersion === ENGINE_VERSION,
    };
  }

  /** Every refusal ends here: a named reviewer, a written reason and a replay, all logged. */
  async review(d: EligibilityDecision, reviewerId: string, verdict: "UPHOLD" | "OVERTURN", note: string) {
    if (d.outcome !== "REFER_TO_REVIEWER") throw new Error("only referred decisions are reviewed");
    if (!note.trim()) throw new Error("a review needs a written reason");
    if (verdict === "OVERTURN" && (await this.kill.isOn("payouts"))) throw new Error("payout kill switch is on");
    const replay = this.replay(d);
    await this.audit.append({ kind: "eligibility_reviewed", decisionId: d.decisionId, reviewerId, verdict, note, ...replay });
    // An overturn still goes through payout approval: the reviewer decides eligibility, not the transfer.
    return verdict === "OVERTURN" ? this.approvals.request(d) : null;
  }
}