// **The forge module takes an act of the seat git once by its ask id** (novox/hq design 47 H2 §775; H-A-381, H-A-400): a // kept call carries its ask id (the runtime names it in the call's `_meta`, mesh-sdk askIdOf), and the forge module keeps // each id it took in its state `taken`, key `git.`, for `ask-taken-bound` (a setting, default 10 minutes, the // largest caller's bound). An ask given again while its act runs joins that act and gets its answer; given again after // the act ended, it answers the act's state as it stands, read afresh from the forge (a merge call answers each pull // request as it is: merged, with its merge commit), and the act is never performed twice. No answer is kept in `taken`. // The key is kept only for an act that acted: an answer that performed nothing (away, a transport fault, a refusal // before any act) drops it, so the kept call's repeat under the same id acts (H-A-400 (1)). A repeat for which the // forge's state says the act that acted never happened is a refusal naming it. import { takeOnce, takenKey, TAKEN_STATE, type State } from "@novox/mesh-sdk/state"; /** The seat the forge module takes asks of. */ export const SEAT = "git"; /** ask-taken-bound's default (H-A-381 (2)). */ export const ASK_TAKEN_BOUND_DEFAULT = "10m"; /** A duration as the mesh writes one ("10m", "1h30m", "45s", "500ms"), in milliseconds; null when it is none. */ export function durationMs(text: string): number | null { const s = text.trim(); if (!/^(\d+(\.\d+)?(ms|h|m|s))+$/.test(s)) return null; let ms = 0; for (const [, n, , unit] of s.matchAll(/(\d+(\.\d+)?)(ms|h|m|s)/g)) { ms += Number(n) * ({ ms: 1, s: 1_000, m: 60_000, h: 3_600_000 } as Record)[unit]; } return ms > 0 ? ms : null; } /** ask-taken-bound in milliseconds, from the word the node-engine composes for it (H-A-370, H-A-400 (2)); the default when * it is unset. A value that is no duration is said and the default taken. */ export function askTakenBoundMs(env: NodeJS.ProcessEnv = process.env, log: (line: string) => void = () => {}): number { const raw = env.MESH_CONFIG_ASK_TAKEN_BOUND; const fallback = durationMs(ASK_TAKEN_BOUND_DEFAULT)!; if (raw === undefined || raw.trim() === "") return fallback; const ms = durationMs(raw); if (ms === null) { log(`the setting ask-taken-bound is ${JSON.stringify(raw)}, no duration: the default ${ASK_TAKEN_BOUND_DEFAULT} holds`); return fallback; } return ms; } /** The state taken, as the forge module reaches it: take an ask once, drop a key whose act performed nothing. */ export interface Taken { /** Whether this holder takes the ask now (mesh-sdk takeOnce: created, refused when the key exists). */ take(ask: string): Promise; /** Drops the key of an ask whose act performed nothing, so its repeat acts. */ drop(ask: string): Promise; } /** The module's state taken over the runtime, its keys living ask-taken-bound. */ export function takenState(st: Pick, "delete">, boundMs: number): Taken { return { take: (ask) => takeOnce(SEAT, ask, boundMs, TAKEN_STATE), drop: (ask) => st.delete(takenKey(SEAT, ask)), }; } /** Whether an act's answer performed nothing: an error answer, or a merge call that merged no member. */ export function performedNothing(answer: object): boolean { const a = answer as Record; if (a["error-kind"] !== undefined) return true; if (Array.isArray(a.members)) return !a.members.some((m: any) => m?.state === "merged"); return false; } /** * Takes an act once by its ask id: `act` runs for an ask this holder takes now; an ask given while its act runs joins it; * an ask taken before whose act ended answers `standing`, the act's state read afresh. An act with no ask id acts as * before. The taken key is dropped when the act performed nothing. */ export class Once { private readonly running = new Map>(); constructor(private readonly taken: Taken, private readonly log: (line: string) => void = () => {}) {} async run(ask: string, act: () => Promise, standing: () => Promise): Promise { if (!ask) return act(); const joined = this.running.get(ask); if (joined) return joined; if (!(await this.taken.take(ask))) { // Taken before, and its act ended (or another process runs it): what it did, read afresh, never done again. return this.running.get(ask) ?? standing(); } const acting = (async () => { let answer: object; try { answer = await act(); } catch (err) { await this.taken.drop(ask).catch(() => {}); throw err; } if (performedNothing(answer)) { await this.taken.drop(ask).catch((err) => this.log(`the ask ${ask} performed nothing and its taken key could not be dropped, so its repeat is answered as it stands — ${err instanceof Error ? err.message : err}`)); } return answer; })(); this.running.set(ask, acting); try { return await acting; } finally { this.running.delete(ask); } } }