FORGE-1: failed-steps reads the body's fingerprint; a step-ended without it writes step-unread
The forge module keeps a step's failure at the step-ended body's fingerprint alone, consumes step-ended on its <module>.<branch>.<commit> subject, and writes step-unread (scope module, keyed <run>.<module>.<step>, warning, resolver operator) for a step-ended without its fingerprint, cleared by the step's later step-ended with it. Builds: design 47 H §735 (failed-steps from step-ended); G §585; H-A-18, H-A-47 (FORGE-1 builds step-unread), H-A-93 Claude-Session: https://claude.ai/code/session_01JG73KHUnBze48rdua8u2sy
This commit is contained in:
@@ -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<string, any> } {
|
||||
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<unknown> = 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<StateFill> = askFill) {}
|
||||
private readonly fillOf: () => Promise<StateFill> = askFill,
|
||||
/** The module's state findings, where step-unread is written (G §585, H-A-93); none writes no finding. */
|
||||
private readonly findings?: State<unknown>) {}
|
||||
|
||||
private turn<T>(act: () => Promise<T>): Promise<T> {
|
||||
const r = this.chain.then(act, act);
|
||||
@@ -98,9 +117,13 @@ export class FailedSteps {
|
||||
|
||||
private record(ev: StepEndedEvent): Promise<void> {
|
||||
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 `<run>.<module>.<step>`, 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<void> {
|
||||
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<Judged | null> {
|
||||
return this.turn(async () => {
|
||||
|
||||
@@ -410,7 +410,8 @@ const calls = new Calls(state<unknown>("calls"), () => callRetentionDays(), (lin
|
||||
const partials = new Partials(state<unknown>("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<unknown>("failed-steps"), (line) => console.log(`[gitea] ${line}`), (commit) => heldHeads.has(commit));
|
||||
const failedSteps = new FailedSteps(state<unknown>("failed-steps"), (line) => console.log(`[gitea] ${line}`), (commit) => heldHeads.has(commit),
|
||||
undefined, state<unknown>("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<StepEndedEvent>(`${RUNNER}.${RUNNER_EVENTS.stepEnded}`, (event) => failedSteps.stepEnded(event.body)));
|
||||
// The runner's step-ended is said on step-ended.<module>.<branch>.<commit> (the seat's definition).
|
||||
const stepEnded = `${RUNNER}.${RUNNER_EVENTS.stepEnded}.*.*.*`;
|
||||
void bindUntilHeld(stepEnded, () => on<StepEndedEvent>(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<BranchMovedEvent>(`${GIT}.${GIT_EVENTS.branchMoved}`, async (event) => {
|
||||
const { repository, branch } = event.body;
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -20,7 +20,7 @@ function memory() {
|
||||
}
|
||||
const ended = (commit: string, outcome: string, extra: Record<string, unknown> = {}, over: Record<string, unknown> = {}) => ({
|
||||
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 <run>.<module>.<step>, 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");
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user