diff --git a/modules/gitea/failedsteps.ts b/modules/gitea/failedsteps.ts index 84473b12f..8e69a721b 100644 --- a/modules/gitea/failedsteps.ts +++ b/modules/gitea/failedsteps.ts @@ -19,6 +19,7 @@ import { failedStepsByModuleFingerprintStepKey as failedKey, type FailedStep, type PullClosedEvent, type PullMergedEvent, type PullUpdatedEvent, } from "@novox/mesh-delivery-contracts-git"; import type { StepEndedEvent } from "@novox/mesh-delivery-contracts-mesh-pipeline-runner"; +import { findingKey } from "./catalog.js"; /** The key prefix of the commits' fingerprints (§487). */ export const SEEN = "seen."; @@ -58,6 +59,22 @@ const safe = (s: string): string => s.replace(/[^A-Za-z0-9_=/-]/g, "_"); export const seenKey = (commit: string, module: string): string => `${SEEN}${commit}.${safe(module)}`; export const failedStepKey = (module: string, fingerprint: string, step: string): string => failedKey(safe(module), safe(fingerprint), safe(step)); +/** The finding of a step-ended the forge module could not record (G §585). */ +export const STEP_UNREAD = "step-unread"; + +/** step-unread of one step of one run (H-A-93): its key in the state findings and its value. */ +export function stepUnreadFinding(run: string, module: string, step: string, at: string): { key: string; value: Record } { + const key = findingKey("module", `${run}.${module}.${step}`, STEP_UNREAD); + const summary = `the step-ended of ${step} of ${module} in run ${run} names no build-input fingerprint, so a failure of it cannot be recorded`; + return { key, value: { + v: 1, key, kind: STEP_UNREAD, subject: { scope: "module", id: module }, severity: "warning", resolver: "operator", summary, + headline: `A step the forge module could not read: ${step} of ${module}`, + explanation: `merge-pull judges a head by the failed required steps at its fingerprint; this step-ended of run ${run} carries no fingerprint, ` + + "so the forge module could not keep it. A later step-ended of the step with its fingerprint clears this.", + resolved: "", evidence: [{ at, said: summary }], source: `gitea.${STEP_UNREAD}`, observer: "gitea", at, + } }; +} + export class FailedSteps { /** Every act runs after the one before it, so a step-ended and a head's loss never interleave their reads and writes. */ private chain: Promise = Promise.resolve(); @@ -66,7 +83,9 @@ export class FailedSteps { /** Whether a commit is now a watched branch's head or an open pull request's head. */ private readonly current: (commit: string) => boolean = () => false, /** The state's fill against its caps: the bundle's state call (§623). */ - private readonly fillOf: () => Promise = askFill) {} + private readonly fillOf: () => Promise = askFill, + /** The module's state findings, where step-unread is written (G §585, H-A-93); none writes no finding. */ + private readonly findings?: State) {} private turn(act: () => Promise): Promise { const r = this.chain.then(act, act); @@ -98,9 +117,13 @@ export class FailedSteps { private record(ev: StepEndedEvent): Promise { const r = ev?.result; - const fingerprint = r?.fingerprint || ev?.fingerprint || ""; - if (!r || !SHA.test(String(ev.commit ?? "")) || !fingerprint || !ev.module) return Promise.resolve(); + // The fingerprint is the body's, the build-input fingerprint the runner fills in every step-ended; no field of the step's + // result is read for it (G §585, H-A-93). + const fingerprint = ev?.fingerprint || ""; + if (!r || !SHA.test(String(ev.commit ?? "")) || !ev.module) return Promise.resolve(); + if (!fingerprint) return this.turn(() => this.unread(ev, true)); return this.turn(async () => { + await this.unread(ev, false); const at = ev.at ?? new Date().toISOString(); const sk = seenKey(ev.commit, ev.module); const held = (await this.st.get(sk))?.value as Seen | undefined; @@ -137,6 +160,26 @@ export class FailedSteps { }); } + /** + * step-unread (G §585, H-A-93): a step-ended without its fingerprint writes the finding, scope module, its subject the step's + * module, keyed `..`, naming the run, the module and the step, severity warning, resolver operator; a + * later step-ended of that step with its fingerprint clears it, so a failure that could not be recorded is seen. + */ + private async unread(ev: StepEndedEvent, raise: boolean): Promise { + if (!this.findings) return; + const step = String(ev.result?.step ?? ""), run = String(ev.pipeline ?? ""); + const { key, value } = stepUnreadFinding(run, ev.module, step, String(ev.at ?? new Date().toISOString())); + if (!raise) { + if ((await this.findings.get(key))?.value) { + await this.findings.delete(key); + this.log(`${ev.module} ${step} of ${run} is read with its fingerprint: step-unread cleared`); + } + return; + } + await this.findings.put(key, value); + this.log(String(value.summary)); + } + /** The failed `required` step that refuses this head, or null: a head with a `seen` key is judged by it, one with none merges (§487). */ judge(head: string): Promise { return this.turn(async () => { diff --git a/modules/gitea/index.ts b/modules/gitea/index.ts index 03d24ebd4..793738a33 100644 --- a/modules/gitea/index.ts +++ b/modules/gitea/index.ts @@ -410,7 +410,8 @@ const calls = new Calls(state("calls"), () => callRetentionDays(), (lin const partials = new Partials(state("findings"), calls, (line) => console.log(`[gitea] ${line}`)); void sayUnsaid(calls, seatPublish, (line) => console.log(`[gitea] ${line}`)).catch((err) => console.error(`[gitea] the merge calls not said could not be said at the start — ${err instanceof Error ? err.message : err}`)); -const failedSteps = new FailedSteps(state("failed-steps"), (line) => console.log(`[gitea] ${line}`), (commit) => heldHeads.has(commit)); +const failedSteps = new FailedSteps(state("failed-steps"), (line) => console.log(`[gitea] ${line}`), (commit) => heldHeads.has(commit), + undefined, state("findings")); // The `seen` keys past their 30 days are deleted at the start, as on each step-ended (design 47 §581). void failedSteps.expireSeen().catch((err) => console.log(`[gitea] the seen keys past 30 days could not be deleted at the start: ${err instanceof Error ? err.message : String(err)}`)); @@ -578,7 +579,9 @@ if (gitea) { const read = await readHeads(forge, registrations.watched, (line) => console.log(`[gitea] ${line}`)); await failedSteps.lost(heldHeads.replace(read.names, read.branches, read.pulls)); }; - void bindUntilHeld(`${RUNNER}.${RUNNER_EVENTS.stepEnded}`, () => on(`${RUNNER}.${RUNNER_EVENTS.stepEnded}`, (event) => failedSteps.stepEnded(event.body))); + // The runner's step-ended is said on step-ended... (the seat's definition). + const stepEnded = `${RUNNER}.${RUNNER_EVENTS.stepEnded}.*.*.*`; + void bindUntilHeld(stepEnded, () => on(stepEnded, (event) => failedSteps.stepEnded(event.body))); // A branch's head is read from the forge, never taken from the event (the seat's definition of branch-moved). void bindUntilHeld(`${GIT}.${GIT_EVENTS.branchMoved}`, () => on(`${GIT}.${GIT_EVENTS.branchMoved}`, async (event) => { const { repository, branch } = event.body; diff --git a/modules/gitea/module.json b/modules/gitea/module.json index 55bc097c4..9941bc4e5 100644 --- a/modules/gitea/module.json +++ b/modules/gitea/module.json @@ -654,7 +654,7 @@ "consumes": [ "mesh-catalog.catalog-revision", "mesh-catalog.registration-changed", - "mesh-pipeline-runner.step-ended", + "mesh-pipeline-runner.step-ended.*.*.*", "git.branch-moved", "git.pull-updated", "git.pull-closed", diff --git a/modules/gitea/test/failedsteps.test.ts b/modules/gitea/test/failedsteps.test.ts index f3b703a94..35347cb0c 100644 --- a/modules/gitea/test/failedsteps.test.ts +++ b/modules/gitea/test/failedsteps.test.ts @@ -20,7 +20,7 @@ function memory() { } const ended = (commit: string, outcome: string, extra: Record = {}, over: Record = {}) => ({ v: 1, pipeline: `main.7.nats-${commit.slice(0, 2)}`, module: "nats", branch: "main", commit, at: "2026-11-11T12:00:00Z", - result: { step: "unit", status: "required", outcome, fingerprint: "fp-1", ...extra }, ...over }) as any; + fingerprint: "fp-1", result: { step: "unit", status: "required", outcome, ...extra }, ...over }) as any; test("a head is refused by a required step that failed at its fingerprint in any run, until a rerun passes it", async () => { const { kv, st } = memory(); @@ -45,12 +45,13 @@ test("a head is refused by a required step that failed at its fingerprint in any // A later commit at the fingerprint is refused too, and a failed optional step refuses nothing. await f.stepEnded(ended(C3, "passed")); await judged("a later commit of the same content", C3, "run-on-request nats unit"); - await f.stepEnded(ended(C3, "failed", { step: "lint", status: "optional", fingerprint: "fp-2" })); + await f.stepEnded(ended(C3, "failed", { step: "lint", status: "optional" }, { fingerprint: "fp-2" })); await judged("a failed optional step", C3, "run-on-request nats unit"); assert.equal(kv.has(failedStepKey("nats", "fp-2", "lint")), false); - // A result that names no fingerprint is kept at the one the seat's step event carries (`fingerprint`). - await f.stepEnded(ended(C3, "failed", { step: "lint", fingerprint: undefined }, { fingerprint: "fp-3" })); + // The fingerprint is the body's alone, never the result's (G §585, H-A-93). + await f.stepEnded(ended(C3, "failed", { step: "lint", fingerprint: "fp-x" }, { fingerprint: "fp-3" })); assert.ok(kv.has(failedStepKey("nats", "fp-3", "lint")), "the event's fingerprint is kept"); + assert.equal(kv.has(failedStepKey("nats", "fp-x", "lint")), false, "the result's is never read"); // A plain pass clears nothing; a rerun that passes clears it. await f.stepEnded(ended(C2, "passed")); await judged("a plain pass", C2, "run-on-request nats unit"); @@ -122,3 +123,21 @@ test("a seen key past 30 days is deleted at the next step-ended, a younger one k const done: any = await runAs({ "mesh/caller": "operator" }, {}, () => tool.run({ why: "stale" })); assert.deepEqual([done.deleted.length, acts[0].verb], [1, "git_seen_expire"]); }); + +// step-unread (G §585, H-A-93): a step-ended of a pipeline's commit without the body's fingerprint records nothing and writes +// the finding, scope module, its subject the step's module, keyed .., warning, resolver operator; a later +// step-ended of that step with its fingerprint clears it. +test("a step-ended without its fingerprint writes step-unread, cleared by the step's later step-ended with it", async () => { + const { stepUnreadFinding } = await import("../failedsteps.js"); + const { kv, st } = memory(); + const findings = memory(); + const f = new FailedSteps(st as any, () => {}, () => true, async () => ({ bytes: 0, keys: 0, max_bytes: 0 }), findings.st as any); + await f.stepEnded(ended(C1, "failed", { fingerprint: "fp-in-result" }, { fingerprint: undefined })); + const { key } = stepUnreadFinding("main.7.nats-" + C1.slice(0, 2), "nats", "unit", ""); + const raised: any = findings.kv.get(key); + assert.deepEqual([raised?.kind, raised?.subject, raised?.severity, raised?.resolver], ["step-unread", { scope: "module", id: "nats" }, "warning", "operator"]); + assert.match(raised.summary, /unit of nats in run main\.7\.nats-/); + assert.equal([...kv.keys()].some((k) => !k.startsWith("seen.")), false, "no failure recorded"); + await f.stepEnded(ended(C1, "failed")); + assert.equal(findings.kv.has(key), false, "cleared by the step's step-ended with its fingerprint"); +});