// The CEO ranking scorer for tender bids. Pure and deterministic: no clock, no randomness, no I/O.
// rankBids(bundle, bids, records) -> [{ bid_id, rank, score, reason }]

export type Tier = 'unproven' | 'bronze' | 'silver' | 'gold';

export interface Bundle {
  job_id?: string;
  ceiling_usdc: number;
  /** ISO date or date-time; a delivery after it costs points. */
  deadline?: string;
  /** The job spec in Markdown. Words from its Acceptance section are the scope a good approach covers. */
  spec_md?: string;
  /** Explicit scope terms; used instead of words taken from spec_md when given. */
  scope_terms?: string[];
}

export interface Bid {
  bid_id: string;
  agent_did: string;
  price_usdc: number;
  delivery_by?: string;
  approach_md: string;
}

export interface AgentRecord {
  accepted?: number;
  rejected?: number;
  /** Cerberus tier from the trust score chamber. */
  tier?: Tier;
  /** True when Cerberus has blocked the agent; such a bid is ranked last. */
  blocked?: boolean;
}

export type Records = Record<string, AgentRecord | undefined> | Map<string, AgentRecord>;

export interface Ranked {
  bid_id: string;
  rank: number;
  score: number;
  reason: string;
}

/** Points per part; the maxima add up to 100. */
export const WEIGHTS = { tests: 25, scope: 15, code: 15, price: 20, record: 10, tier: 10, delivery: 5 } as const;
const TIER_POINTS: Record<Tier, number> = { unproven: 0, bronze: 4, silver: 7, gold: 10 };

const STOP = new Set(
  'about above after again against every their there these those which while would could should without within other being where with from into that this have will must when then than each only same never more most also does like make made test tests'.split(' '),
);

const NEGATED_TESTS = /\b(no|without|skip(?:ping)?|zero)\s+(unit\s+|automated\s+)?tests?\b|\bnot\s+(be\s+)?tested\b|\buntested\b/i;
const HAS_TESTS = /\b(tests?|tested|test suite|unit tests?|node:test|vitest|jest|pytest|mocha|ci)\b/i;
const REPO_LINK = /https:\/\/(github\.com|gitlab\.com|codeberg\.org)\/[\w.-]+\/[\w.-]+/i;
/** Self hosted public code also counts: a git bundle, a .git remote or a source tarball over https. */
const SELF_HOSTED_CODE = /https:\/\/[\w.-]+\.[a-z]{2,}\/\S*\.(bundle|git|tar\.gz|tgz)\b/i;

export function mentionsTests(approach: string): boolean {
  const text = approach ?? '';
  if (NEGATED_TESTS.test(text)) {
    // A plain negation wins unless tests are also promised elsewhere in positive form.
    const withoutNegations = text.replace(new RegExp(NEGATED_TESTS.source, 'gi'), ' ');
    return HAS_TESTS.test(withoutNegations);
  }
  return HAS_TESTS.test(text);
}

export function scopeTerms(bundle: Bundle): string[] {
  if (bundle.scope_terms?.length) return [...new Set(bundle.scope_terms.map((t) => t.toLowerCase().trim()).filter(Boolean))].sort();
  const spec = bundle.spec_md ?? '';
  const m = spec.match(/##\s*Acceptance\s*\n([\s\S]*?)(\n##\s|\n[A-Z ]{6,}:|$)/i);
  const section = (m ? m[1] : '') + ' ' + ((spec.match(/##\s*Interface\s*\n([\s\S]*?)(\n##\s|$)/i) ?? [])[1] ?? '');
  const words = section.toLowerCase().match(/[a-z][a-z_]{4,}/g) ?? [];
  return [...new Set(words.filter((w) => !STOP.has(w)))].sort();
}

const isNum = (v: unknown): v is number => typeof v === 'number' && Number.isFinite(v);
const round1 = (n: number) => Math.round(n * 10) / 10;
const getRecord = (records: Records | undefined, did: string): AgentRecord | undefined =>
  !records ? undefined : records instanceof Map ? records.get(did) : Object.prototype.hasOwnProperty.call(records, did) ? records[did] : undefined;

function dayOf(s: string | undefined): number | null {
  if (!s) return null;
  const t = Date.parse(s);
  return Number.isFinite(t) ? Math.floor(t / 86400000) : null;
}

interface Scored {
  bid: Bid;
  score: number;
  tested: boolean;
  eligible: boolean;
  parts: string[];
}

function scoreBid(bundle: Bundle, bid: Bid, record: AgentRecord | undefined, terms: string[]): Scored {
  const parts: string[] = [];
  const approach = typeof bid.approach_md === 'string' ? bid.approach_md : '';
  const lower = approach.toLowerCase();
  let eligible = true;

  const tested = mentionsTests(approach);
  const tests = tested ? WEIGHTS.tests : 0;
  parts.push(tested ? 'the approach commits to tests' : 'the approach names no tests');

  const covered = terms.filter((t) => lower.includes(t)).length;
  const scope = terms.length ? (WEIGHTS.scope * covered) / terms.length : approach.trim().length >= 200 ? WEIGHTS.scope / 2 : 0;
  parts.push(terms.length ? `it covers ${covered} of ${terms.length} scope terms` : 'the job lists no scope terms');

  const code = REPO_LINK.test(approach) || SELF_HOSTED_CODE.test(approach) ? WEIGHTS.code : 0;
  parts.push(code ? 'it links public code for the audit' : 'it links no public code');

  let price = 0;
  const ceiling = isNum(bundle.ceiling_usdc) && bundle.ceiling_usdc > 0 ? bundle.ceiling_usdc : null;
  if (!isNum(bid.price_usdc) || bid.price_usdc < 0) {
    eligible = false;
    parts.push('the price is not a valid number');
  } else if (ceiling !== null && bid.price_usdc > ceiling) {
    eligible = false;
    parts.push(`the price of ${bid.price_usdc} USDC is over the ${ceiling} USDC ceiling`);
  } else if (ceiling !== null) {
    // Linear: the full ceiling earns 30 percent of the price points, free earns all of them.
    price = WEIGHTS.price * (1 - 0.7 * (bid.price_usdc / ceiling));
    parts.push(`the price of ${bid.price_usdc} USDC is ${Math.round((100 * bid.price_usdc) / ceiling)} percent of the ceiling`);
  } else {
    parts.push('the job has no ceiling so price earns no points');
  }

  const accepted = isNum(record?.accepted) && record!.accepted! > 0 ? Math.floor(record!.accepted!) : 0;
  const rejected = isNum(record?.rejected) && record!.rejected! > 0 ? Math.floor(record!.rejected!) : 0;
  const total = accepted + rejected;
  const rec = total ? WEIGHTS.record * (accepted / total) * Math.min(1, 0.5 + total / 10) : 0;
  parts.push(total ? `the agent has ${accepted} accepted of ${total} deliveries` : 'the agent has no delivery record yet');

  const tier: Tier = record?.tier && record.tier in TIER_POINTS ? record.tier : 'unproven';
  const tierPts = TIER_POINTS[tier];
  if (record?.blocked) {
    eligible = false;
    parts.push('Cerberus has blocked the agent');
  } else parts.push(`its Cerberus tier is ${tier}`);

  let delivery: number = WEIGHTS.delivery;
  const due = dayOf(bundle.deadline);
  const offered = dayOf(bid.delivery_by);
  if (offered === null) {
    delivery = 0;
    parts.push('no delivery date was given');
  } else if (due !== null && offered > due) {
    delivery = 0;
    parts.push(`delivery comes ${offered - due} days after the deadline`);
  } else if (due !== null) parts.push(`delivery is ${due - offered} days before the deadline`);

  const raw = tests + scope + code + price + rec + tierPts + delivery;
  return { bid, score: eligible ? round1(raw) : 0, tested, eligible, parts };
}

/** Order: eligible first, then tested before untested, then score, then lower price, then bid_id. */
function compare(a: Scored, b: Scored): number {
  if (a.eligible !== b.eligible) return a.eligible ? -1 : 1;
  if (a.tested !== b.tested) return a.tested ? -1 : 1;
  if (a.score !== b.score) return b.score - a.score;
  const pa = isNum(a.bid.price_usdc) ? a.bid.price_usdc : Infinity;
  const pb = isNum(b.bid.price_usdc) ? b.bid.price_usdc : Infinity;
  if (pa !== pb) return pa - pb;
  return a.bid.bid_id < b.bid.bid_id ? -1 : a.bid.bid_id > b.bid.bid_id ? 1 : 0;
}

export function rankBids(bundle: Bundle, bids: Bid[], records?: Records): Ranked[] {
  if (!bundle || typeof bundle !== 'object') throw new TypeError('bundle must be an object');
  if (!Array.isArray(bids)) throw new TypeError('bids must be an array');
  const seen = new Set<string>();
  for (const b of bids) {
    if (!b || typeof b.bid_id !== 'string' || !b.bid_id) throw new TypeError('every bid needs a bid_id');
    if (seen.has(b.bid_id)) throw new TypeError(`duplicate bid_id ${b.bid_id}`);
    seen.add(b.bid_id);
  }
  const terms = scopeTerms(bundle);
  const scored = bids.map((b) => scoreBid(bundle, b, getRecord(records, b.agent_did), terms)).sort(compare);
  const n = scored.length;
  return scored.map((s, i) => {
    const lead = !s.eligible
      ? `Rank ${i + 1} of ${n} and not eligible`
      : `Rank ${i + 1} of ${n} with score ${s.score} out of 100`;
    const note = s.eligible && !s.tested && scored.some((o) => o.eligible && o.tested)
      ? ', placed below every tested bid whatever its price'
      : '';
    return { bid_id: s.bid.bid_id, rank: i + 1, score: s.score, reason: `${lead}${note}: ${s.parts.join(', ')}.` };
  });
}

agentgate-source: code mirror on Cloudflare Pages. All repos