Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

10.2 KB
Raw Blame
/**
 * Pure verdicts for the post-merge gate audit (#12549).
 *
 * The merge-admission lease and the "required CI is green" rule are prompt
 * instructions; an agent with full forge access can still merge around them.
 * Given what the forge reports about a merged head and what PortOS recorded
 * about the run's admission leases, these functions decide whether the merge
 * respected both gates. No I/O: `services/mergeGateAudit.js` gathers the inputs.
 */

export const MERGE_GATE_VIOLATIONS = Object.freeze({
  NO_ADMISSION_LEASE: 'no-admission-lease',
  CHECKS_NOT_GREEN_AT_MERGE: 'checks-not-green-at-merge',
});

// Lease timestamps are local, `mergedAt` is the forge's clock; tolerate drift
// without letting a merge made well outside the hold pass as covered.
export const LEASE_CLOCK_SKEW_MS = 30 * 1000;
// Agent leases hold at most 5 minutes (`AGENT_LEASE_MAX_HOLD_MS`): past that a
// holder must re-acquire, so a merge later than this is not covered. It also
// bounds when a legacy `lastMergeAdmission` (release time only) began.
const LEASE_MAX_HOLD_MS = 5 * 60 * 1000;

const GREEN_CONCLUSIONS = new Set(['success', 'neutral', 'skipped']);
const RED_CONCLUSIONS = new Set(['failure', 'timed_out', 'startup_failure']);

const time = (value) => {
  const ms = Date.parse(value);
  return Number.isFinite(ms) ? ms : null;
};

const isGreen = (check, mergedMs) => check.status === 'completed' && GREEN_CONCLUSIONS.has(String(check.conclusion || '').toLowerCase())
  && mergedMs !== null && time(check.completed_at) !== null && time(check.completed_at) <= mergedMs;

/**
 * Reduce the forge's check-run and commit-status history for a head to one
 * record per check, as the merge saw it.
 *
 * A rerun adds an attempt rather than replacing one, and a status context is
 * re-posted in place, so the newest record can postdate the merge. Each check's
 * attempts are dated by when they existed: a run's first attempt by its suite's
 * creation (a run queued before the merge may not start until well after it), a
 * rerun by its start (the check-runs API exposes no creation time, so a rerun
 * queued before the merge but started after it is not seen), a status by its post time. A check none of whose attempts
 * existed at `mergedAt` was never something the merge could wait for. Of the rest,
 * an attempt that was green before the merge stands for the check; otherwise the
 * newest attempt does, so a head still red (or fixed only after the merge) is
 * reported as it now stands.
 *
 * Forge timestamps on both sides, so no clock-skew allowance applies.
 *
 * @param {object} evidence
 * @param {Array<{id?: number, name?: string, status?: string, conclusion?: string|null, suite?: number, started_at?: string|null, completed_at?: string|null}>} evidence.runs every attempt (`filter=all`)
 * @param {Array<{id?: number, created_at?: string|null}>} evidence.suites
 * @param {Array<{context?: string, state?: string, created_at?: string|null}>} evidence.statuses every status posted, in any order
 * @param {string} mergedAt
 * @returns {Array<{name: string, status: string, conclusion: string|null, completed_at: string|null}>}
 */
export function foldHeadChecks({ runs, suites, statuses }, mergedAt) {
  const mergedMs = time(mergedAt);
  const suiteCreated = new Map(suites.map((suite) => [suite.id, time(suite.created_at)]));
  const groups = new Map();
  const add = (key, attempt) => groups.set(key, [...(groups.get(key) || []), attempt]);

  for (const run of [...runs].sort((a, b) => (a.id ?? 0) - (b.id ?? 0))) {
    const key = `run:${run.suite}:${run.name}`;
    const first = !groups.has(key);
    const created = suiteCreated.get(run.suite) ?? null;
    const at = first ? created : (time(run.started_at) ?? created);
    add(key, { at, check: { name: run.name, status: run.status, conclusion: run.conclusion ?? null, completed_at: run.completed_at ?? null } });
  }
  const orderedStatuses = statuses.map((status, index) => ({ status, index, at: time(status.created_at) }))
    .sort((a, b) => (a.at ?? 0) - (b.at ?? 0) || b.index - a.index);
  for (const { status, at } of orderedStatuses) {
    add(`status:${status.context}`, { at, check: {
      name: status.context,
      status: status.state === 'pending' ? 'in_progress' : 'completed',
      conclusion: status.state === 'error' ? 'failure' : status.state,
      completed_at: status.created_at ?? null,
    } });
  }

  const folded = [];
  for (const attempts of groups.values()) {
    const existing = attempts.filter((attempt) => attempt.at === null || mergedMs === null || attempt.at <= mergedMs);
    if (existing.length === 0) continue;
    const atMerge = existing[existing.length - 1].check;
    folded.push(isGreen(atMerge, mergedMs) ? atMerge : attempts[attempts.length - 1].check);
  }
  return folded;
}

/**
 * Classify a merged head's folded checks (`foldHeadChecks`) against the moment it merged.
 *
 * Absent and empty are different: `checks === null` means the forge could not be
 * read, and no verdict is possible. An empty list is a repository with no CI on
 * that head, which has nothing to wait for.
 *
 * @param {Array<{name?: string, status?: string, conclusion?: string|null, completed_at?: string|null}>|null} checks
 * @param {string} mergedAt
 * @returns {{ readable: boolean, notGreenAtMerge: string[], failing: string[], settled: boolean }}
 */
export function classifyHeadChecks(checks, mergedAt) {
  if (!Array.isArray(checks)) return { readable: false, notGreenAtMerge: [], failing: [], settled: false };
  const mergedMs = time(mergedAt);
  const notGreenAtMerge = [];
  const failing = [];
  let settled = true;
  for (const check of checks) {
    const name = String(check?.name || 'unnamed check');
    const completed = check?.status === 'completed';
    if (!completed) settled = false;
    if (completed && RED_CONCLUSIONS.has(String(check?.conclusion || '').toLowerCase())) failing.push(name);
    if (!isGreen(check || {}, mergedMs)) notGreenAtMerge.push(name);
  }
  return { readable: true, notGreenAtMerge, failing, settled };
}

/** One agent-lease interval, whatever shape recorded it. */
function leaseInterval(entry) {
  const releasedMs = time(entry?.releasedAt);
  if (releasedMs === null) return null;
  const acquiredMs = time(entry?.acquiredAt) ?? releasedMs - LEASE_MAX_HOLD_MS;
  return { repository: entry?.repository, outcome: entry?.outcome, acquiredMs, releasedMs };
}

/**
 * Did the run hold the repository's merge-admission lease at `mergedAt`?
 *
 * @param {object} evidence
 * @param {string} evidence.repository
 * @param {string} evidence.mergedAt
 * @param {Array<object>} [evidence.history] released leases (`mergeAdmissionHistory` and the legacy `lastMergeAdmission`)
 * @param {{repository?: string, acquiredAt?: string}|null} [evidence.heldLease] a lease the run still holds
 */
function leaseCoversMerge({ repository, mergedAt, history = [], heldLease = null }) {
  const mergedMs = time(mergedAt);
  if (mergedMs === null) return false;
  if (heldLease?.repository === repository) {
    const acquiredMs = time(heldLease.acquiredAt);
    if (acquiredMs !== null && acquiredMs <= mergedMs + LEASE_CLOCK_SKEW_MS && mergedMs <= acquiredMs + LEASE_MAX_HOLD_MS + LEASE_CLOCK_SKEW_MS) return true;
  }
  return history.some((entry) => {
    const lease = leaseInterval(entry);
    return lease && lease.repository === repository && lease.outcome === 'merged'
      && lease.acquiredMs <= mergedMs + LEASE_CLOCK_SKEW_MS && lease.releasedMs >= mergedMs - LEASE_CLOCK_SKEW_MS
      && mergedMs <= lease.acquiredMs + LEASE_MAX_HOLD_MS + LEASE_CLOCK_SKEW_MS;
  });
}

const sameHandoff = (receipt, prUrl, headSha) => String(receipt?.prUrl || '').toLowerCase() === String(prUrl || '').toLowerCase()
  && String(receipt?.headSha || '').toLowerCase() === String(headSha || '').toLowerCase();

/**
 * Was this PR handed to the pending-merge coordinator without the coordinator
 * having recorded a merge of it? The coordinator marks its receipt just after
 * its merge call succeeds, so within that window an unmarked receipt cannot yet
 * tell the coordinator's merge from the run's own.
 */
export function awaitsCoordinatorMark({ receipts = [], prUrl, headSha }) {
  const matching = receipts.filter((receipt) => sameHandoff(receipt, prUrl, headSha));
  return matching.length > 0 && !matching.some((receipt) => receipt.coordinatorMergedAt);
}

/**
 * Judge one merged claim PR.
 *
 * A head the pending-merge coordinator merged under its own admission is never
 * flagged. Only a receipt the coordinator marked `coordinatorMergedAt` when its
 * own merge call succeeded counts: a bare handoff proves nothing about who
 * merged, and a run that merged around the queue leaves its receipt unmarked.
 *
 * @param {object} input
 * @param {string} input.repository
 * @param {string} input.headSha
 * @param {string} input.mergedAt
 * @param {string} input.prUrl the audited PR; a head can back several PRs (main and a release branch)
 * @param {Array<{prUrl?: string, headSha?: string, coordinatorMergedAt?: string}>} [input.receipts] handoff receipts recorded on the run
 * @param {Array<object>} [input.history]
 * @param {object|null} [input.heldLease]
 * @param {Array<object>|null} input.checks check runs of the merged head; null when unreadable
 * @returns {{ exempt: boolean, violations: Array<{code: string, message: string}>, checks: ReturnType<typeof classifyHeadChecks> }}
 */
export function assessMergeGate({ repository, prUrl, headSha, mergedAt, receipts = [], history = [], heldLease = null, checks }) {
  const classification = classifyHeadChecks(checks, mergedAt);
  if (receipts.some((receipt) => receipt?.coordinatorMergedAt && sameHandoff(receipt, prUrl, headSha))) {
    return { exempt: true, violations: [], checks: classification };
  }
  const violations = [];
  if (!leaseCoversMerge({ repository, mergedAt, history, heldLease })) {
    violations.push({
      code: MERGE_GATE_VIOLATIONS.NO_ADMISSION_LEASE,
      message: 'merged without holding the repository merge-admission lease',
    });
  }
  if (classification.notGreenAtMerge.length > 0) {
    violations.push({
      code: MERGE_GATE_VIOLATIONS.CHECKS_NOT_GREEN_AT_MERGE,
      message: `merged before ${classification.notGreenAtMerge.length} check(s) on the head finished green`,
    });
  }
  return { exempt: false, violations, checks: classification };
}