// **The call is written before its first merge** (novox/hq design 47 H §766; H-A-18, H-A-47, H-A-71): before it merges // anything, the forge module writes the call's key `call.` in its own template state `calls` (the seat git's // definition declares it): `by`, the bus account the tool runner proved, `at`, the members, each with its base `branch` // and `state` judged, merged with its commit, or refused with why, and `said`, whether its `merge-called` was said. Each // member is updated as it merges. A call is kept `call-retention` (a setting, default 30 days), then deleted by the forge // module on each new call's write, oldest first, with no timer (H-A-47). import { readFileSync } from "node:fs"; import type { State } from "@novox/mesh-sdk/state"; import { callsByCallCallKey, mergeCalledSubject, parseCallsByCallCallKey, type Call, type CallMember, type MergeCalledEvent, } from "@novox/mesh-delivery-contracts-git"; /** call-retention's default, in days (§766). */ export const CALL_RETENTION_DAYS = 30; /** call-retention as the module's config file says it, in days; the default when it says none (mainrules.ts' form). */ export function callRetentionDays(env: NodeJS.ProcessEnv = process.env): number { const file = env.MESH_GITEA_CONFIG_FILE; if (!file) return CALL_RETENTION_DAYS; try { const v = Number((JSON.parse(readFileSync(file, "utf8")) as Record)["call-retention"]); return Number.isInteger(v) && v >= 1 ? v : CALL_RETENTION_DAYS; } catch { return CALL_RETENTION_DAYS; } } /** One kept call with its id. */ export interface KeptCall extends Call { call: string; } /** The state `calls`: one key per merge call. */ export class Calls { constructor(private readonly st: State, private readonly retentionDays: () => number = () => CALL_RETENTION_DAYS, private readonly log: (line: string) => void = () => {}) {} /** Every call kept, newest first. */ async all(): Promise { const out: KeptCall[] = []; for (const key of await this.st.keys()) { const parsed = parseCallsByCallCallKey(key); if (!parsed) continue; const e = await this.st.get(key); if (e?.value) out.push({ ...(e.value as Call), call: parsed.call }); } return out.sort((a, b) => (a.at < b.at ? 1 : a.at > b.at ? -1 : a.call < b.call ? 1 : -1)); } /** One call, or undefined. */ async get(call: string): Promise { const e = await this.st.get(callsByCallCallKey(call)); return e?.value ? { ...(e.value as Call), call } : undefined; } /** Writes a call. A new call (none kept under its key) first deletes the calls past call-retention, oldest first. */ async put(call: string, value: Call, now: Date = new Date()): Promise { if (!(await this.st.get(callsByCallCallKey(call)))?.value) await this.expire(now); await this.st.put(callsByCallCallKey(call), value); } /** Deletes the calls whose `at` is past call-retention before now, oldest first; answers the calls deleted. */ async expire(now: Date): Promise { const before = now.getTime() - this.retentionDays() * 86_400_000; const old = (await this.all()).filter((c) => (Date.parse(c.at) || 0) < before).reverse(); for (const c of old) await this.st.delete(callsByCallCallKey(c.call)); if (old.length) this.log(`${old.length} merge calls past ${this.retentionDays()} days deleted: ${old.map((c) => c.call).join(", ")}`); return old.map((c) => c.call); } } /** A kept member of a call. */ export const keptMember = (m: { repository: string; number: number; branch: string; head: string; state: CallMember["state"]; commit?: string; why?: string }): CallMember => ({ repository: m.repository, number: m.number, branch: m.branch, head: m.head, state: m.state, ...(m.commit ? { commit: m.commit } : {}), ...(m.why ? { why: m.why } : {}) }); /** Says a seat event on its subject, under an id the bus keeps once. */ export type Say = (subject: string, body: unknown, id?: string) => Promise; /** The merge-called of a kept call (design 47 H §736, §767): its landed members, each with its base and merge commit, and its * refused ones; undefined for a call that landed no member, which says none. */ export function mergeCalledOf(c: KeptCall): MergeCalledEvent | undefined { const landed = c.members.filter((m) => m.state === "merged" && m.commit); if (landed.length === 0) return undefined; // A member judged and not merged (a stop mid-call) is in neither: its head is an untaken head (§740). const refused = c.members.filter((m) => m.state === "refused"); return { call: c.call, by: c.by, account: c.account, at: c.at, members: landed.map((m) => ({ repository: m.repository, number: m.number, branch: m.branch, head: m.head, commit: m.commit! })), ...(refused.length ? { refused: refused.map((m) => ({ repository: m.repository, number: m.number, why: m.why ?? "not merged" })) } : {}) }; } /** Says a call's merge-called, when it landed a member; answers whether it said one. */ export async function sayCall(c: KeptCall, say: Say): Promise { const body = mergeCalledOf(c); if (!body) return false; await say(mergeCalledSubject(c.call), body, `merge-called.${c.call}`); return true; } /** At the start (§766): every call whose event is not said says merge-called for what landed, and is kept said, so a stop * between the last merge and the event loses nothing it recorded. Answers the calls said. */ export async function sayUnsaid(calls: Calls, say: Say, log: (line: string) => void = () => {}): Promise { const said: string[] = []; for (const c of await calls.all()) { if (c.said) continue; if (await sayCall(c, say)) said.push(c.call); const { call, ...value } = c; await calls.put(call, { ...value, said: true }); } if (said.length) log(`merge-called said again at the start for ${said.join(", ")}`); return said; }