gitea: merge-pull merges plainly only from a watched-branches view read since the last change

An unread or stale view held no entry for a watched repository, so every
member would have merged plainly with the note no delivery: a merge that
reports success and delivers nothing. The registrations holder now keeps
the time of its last read and of the last registration-changed heard; the
merge call refuses every member ("the watched branches are not read yet")
while the view is not read since that change, and a read that fails is
said and asked again with the module's growing wait until it answers.

Builds: design 47 H2 H-A-471 (second addendum); review finding H-A-471 addendum (2)
This commit is contained in:
2026-11-22 14:14:09 +01:00
parent 319f535002
commit 7ae223d4ff
6 changed files with 129 additions and 25 deletions
+1 -1
View File
@@ -304,7 +304,7 @@ void failedSteps.expireSeen().catch((err) => console.log(`[gitea] the seen keys
registerModuleTools("gitea", () => [eventsTool(pace), ...readAllTools(readAll), ...writeTools(writes), ...statusTools("gitea", "gitea_first_views", "gitea_first_view_again", followers, firstViews,
async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }),
...(gitea ? seatTools(gitea, { run, container: FORGE_CONTAINER, registered: () => registrations.written, judge: (head) => failedSteps.judge(head),
watched: () => registrations.watched, calls, say: seatPublish, partials, once }) : []),
watched: () => (registrations.current ? registrations.watched : null), calls, say: seatPublish, partials, once }) : []),
...callTools(calls, partials, seatPublish, async (act) => { await broker().request("seat:mesh-hand-acts.hand-act", act); }),
...(gitea ? [mergedTool(gitea, calls)] : []),
tokenLeaseTool(processVaultAndLease().vault, processVaultAndLease().lease,
+14 -6
View File
@@ -9,7 +9,9 @@
// (no entry, or an empty set, in the registrations' watched branches) is the forge's business alone (H2 H-A-471 and its
// addendum): judged against nothing of the module graph, merged plainly in the order named, answered and kept merged with
// the note no delivery, and left out of merge-called, so it starts no delivery. A watched repository whose base is no
// watched branch stays refused.
// watched branch stays refused. A member is merged plainly only from a view of the watched branches read since the last
// registration-changed heard (the second addendum): while the view is unread or stale, every member is refused, never
// merged with the note.
import { randomBytes } from "node:crypto";
import { UNPROVEN, callerOf } from "@novox/mesh-sdk/callers";
@@ -24,8 +26,9 @@ import type { Partials } from "./partials.js";
export interface CallDeps {
/** Whether the first registrations were written: until then no merge is made (design 47 §95). */
registered: () => boolean;
/** The watched branches the registrations name, by their origin repository `<owner>/<name>`. */
watched: () => ReadonlyMap<string, ReadonlySet<string>>;
/** The watched branches the registrations name, by their origin repository `<owner>/<name>`; null while they are not
* read since the last registration-changed heard (H-A-471, second addendum). */
watched: () => ReadonlyMap<string, ReadonlySet<string>> | null;
/** The failed `required` step that refuses a head, or null (failedsteps.ts). */
judge: (head: string) => Promise<Judged | null>;
/** A new call's id: 16 lowercase hex characters (H-A-24). */
@@ -63,6 +66,9 @@ export interface Member {
/** The note of a member merged plainly: it starts no delivery (H-A-471). */
export const NO_DELIVERY = "no delivery: the repository has no watched branch";
/** Why every member is refused while the watched branches are unread or stale (H-A-471, second addendum). */
export const NOT_READ = "the watched branches are not read yet";
const SHA = /^[0-9a-f]{40}$/;
export const CALL = /^[0-9a-f]{16}$/;
@@ -89,7 +95,7 @@ export function membersOf(raw: unknown): Member[] {
}
/** Why a member is refused at judging, or "" when it is judged. */
async function judgeMember(forge: CallForge, deps: CallDeps, m: Member): Promise<string> {
async function judgeMember(forge: CallForge, deps: CallDeps, watched: ReadonlyMap<string, ReadonlySet<string>>, m: Member): Promise<string> {
const pull = await forge.getPullRequest(m.owner, m.repo, m.number);
m.branch = String(pull.base ?? "");
if (pull.merged) {
@@ -100,7 +106,7 @@ async function judgeMember(forge: CallForge, deps: CallDeps, m: Member): Promise
if (pull.head_sha !== m.head) {
return `head-moved: its head is ${String(pull.head_sha).slice(0, 12)}, not the ${m.head.slice(0, 12)} the caller names`;
}
const branches = deps.watched().get(m.repository);
const branches = watched.get(m.repository);
// A repository of no module: no build-input fingerprint and no required step judge it (H-A-471).
if (!branches || branches.size === 0) {
m.plain = true;
@@ -147,10 +153,12 @@ export async function mergeCall(forge: CallForge, args: Record<string, unknown>,
if (!deps.registered()) throw new Refused("no module is registered yet: the catalog has said no registration-changed, so no merge is made until the first registrations are written");
const call = (deps.newCall ?? newCallId)();
if (!CALL.test(call)) throw new Error(`the call's id ${JSON.stringify(call)} is not 16 lowercase hex characters`);
// One view judges the whole call; unread or stale, it judges no member (H-A-471, second addendum).
const watched = deps.watched();
// Every member is judged before any is merged (§735).
let refused = false;
for (const m of members) {
const why = await judgeMember(forge, deps, m);
const why = watched ? await judgeMember(forge, deps, watched, m) : NOT_READ;
if (why) {
m.state = "refused";
m.why = why;
+59 -15
View File
@@ -4,11 +4,17 @@
// two ways, both through the seat `mesh-catalog`: its verb `registrations` asked at the start (a restart after the first
// registrations were written), and its event `registration-changed` (the first being written, or heard again from the
// seat's kept stream). Neither is the holder's state or a module named.
//
// **A plain merge needs a view read since the last change heard** (design 47 H2 H-A-471, second addendum): the holder keeps
// the time of its last read of the watched branches and of the last registration-changed it heard; the view is current only
// when a read asked after that change has answered. A read that fails is said and asked again with a growing wait until it
// answers, so an unread view is never taken as "no watched branch".
import {
seat as CATALOG, verbs as CATALOG_VERBS, events as CATALOG_EVENTS,
type RegistrationChangedEvent, type RegistrationsAnswer, type RegistrationsInput,
} from "@novox/mesh-delivery-contracts-mesh-catalog";
import { bindWait } from "./bind.js";
/** The seat verb asked, as the manifest's `invokes` names it. */
export const REGISTRATIONS_VERB = `seat:${CATALOG}.${CATALOG_VERBS.registrations}`;
@@ -18,8 +24,18 @@ export const REGISTRATION_CHANGED_EVENT = `${CATALOG}.${CATALOG_EVENTS.registrat
export class Registrations {
private first = false;
private byRepository = new Map<string, Set<string>>();
/** The registration-changed events heard; the count a read was asked at, once it answered (-1: never read). */
private changes = 0;
private readAtChange = -1;
/** The reads asked, and the latest whose answer is the view (an older answer landing later is not taken). */
private asked = 0;
private applied = 0;
private lastRead?: Date;
private lastChange?: Date;
constructor(private readonly ask: (verb: string, input: RegistrationsInput) => Promise<unknown>,
private readonly log: (line: string) => void = () => {}) {}
private readonly log: (line: string) => void = () => {},
private readonly sleep: (ms: number) => Promise<void> = (ms) => new Promise((r) => setTimeout(r, ms)),
private readonly now: () => Date = () => new Date()) {}
/** Whether the first registrations are written: the one fact the merge switches on. */
get written(): boolean {
@@ -31,6 +47,19 @@ export class Registrations {
return this.byRepository;
}
/** Whether the watched branches were read since the last registration-changed heard (H-A-471, second addendum). */
get current(): boolean {
return this.readAtChange === this.changes;
}
/** The time the last read that answered was asked, and of the last registration-changed heard. */
get readAt(): Date | undefined {
return this.lastRead;
}
get changedAt(): Date | undefined {
return this.lastChange;
}
/** One `registration-changed`: the first registration written, however many were before this module started. */
hear(ev: RegistrationChangedEvent | undefined): void {
if (!ev || typeof ev.module !== "string" || ev.module === "") {
@@ -38,25 +67,40 @@ export class Registrations {
}
if (!this.first) this.log(`the first registration is written (${ev.module}); merge-pull merges from here`);
this.first = true;
this.changes++;
this.lastChange = this.now();
}
/** The start's first view, asked again after each `registration-changed`: any registration held is the first written, and its
* watched branches are read. A failed ask is said and left to the event. */
* watched branches are read. A failed ask is said and asked again with a growing wait until it answers (H-A-471, second
* addendum); until then no member is merged plainly. */
async start(): Promise<void> {
try {
let a: unknown = await this.ask(REGISTRATIONS_VERB, {});
if (typeof a === "string") a = JSON.parse(a);
const r = (a as RegistrationsAnswer | undefined)?.registrations;
if (!Array.isArray(r)) throw new Error(`${REGISTRATIONS_VERB} answered no registrations: ${JSON.stringify(a ?? null).slice(0, 200)}`);
const by = new Map<string, Set<string>>();
for (const x of r) for (const b of x.branches ?? []) (by.get(x.origin) ?? by.set(x.origin, new Set()).get(x.origin)!).add(b);
this.byRepository = by;
if (r.length > 0) {
this.first = true;
this.log(`${r.length} registrations are held; merge-pull merges`);
for (let attempt = 1; ; attempt++) {
const at = this.changes, seq = ++this.asked, askedAt = this.now();
try {
let a: unknown = await this.ask(REGISTRATIONS_VERB, {});
if (typeof a === "string") a = JSON.parse(a);
const r = (a as RegistrationsAnswer | undefined)?.registrations;
if (!Array.isArray(r)) throw new Error(`${REGISTRATIONS_VERB} answered no registrations: ${JSON.stringify(a ?? null).slice(0, 200)}`);
if (seq < this.applied) return;
const by = new Map<string, Set<string>>();
for (const x of r) for (const b of x.branches ?? []) (by.get(x.origin) ?? by.set(x.origin, new Set()).get(x.origin)!).add(b);
this.byRepository = by;
this.applied = seq;
this.readAtChange = at;
this.lastRead = askedAt;
if (attempt > 1) this.log(`the registrations are read after ${attempt} attempts`);
if (r.length > 0) {
this.first = true;
this.log(`${r.length} registrations are held; merge-pull merges`);
}
return;
} catch (err) {
const wait = bindWait(attempt);
this.log(`the registrations could not be read: ${err instanceof Error ? err.message : String(err)}; ` +
`no member is merged plainly until they are, asked again in ${wait / 1000}s`);
await this.sleep(wait);
}
} catch (err) {
this.log(`the registrations could not be read: ${err instanceof Error ? err.message : String(err)}; merge-pull waits for registration-changed`);
}
}
}
+3 -2
View File
@@ -54,8 +54,9 @@ export interface SeatDeps {
registered: () => boolean;
/** The failed `required` step that refuses a head, judged from the module's own state `failed-steps` (failedsteps.ts), or null. */
judge: (head: string) => Promise<Judged | null>;
/** The watched branches the registrations name, by their origin repository (registrations.ts): a member's base is one. */
watched: () => ReadonlyMap<string, ReadonlySet<string>>;
/** The watched branches the registrations name, by their origin repository (registrations.ts): a member's base is one;
* null while they are not read since the last registration-changed heard (H-A-471, second addendum). */
watched: () => ReadonlyMap<string, ReadonlySet<string>> | null;
/** The state calls (calls.ts): each merge call written before its first merge (design 47 H §766). */
calls?: Calls;
/** Says merge-called on the seat (mesh-sdk runtime.seatPublish; design 47 H §736). */
+4 -1
View File
@@ -570,7 +570,10 @@ test("the first registrations are learned from the seat mesh-catalog's verb at t
const held = reg(JSON.stringify({ registrations: [{ module: "mesh-sdk" }] }));
await held.start();
assert.equal(held.written, true, "a registration held at the start");
const down = reg(new Error("no responders"));
// A failed first view is said and asked again (H-A-471, second addendum): the test's wait answers it with none.
let downAnswer: unknown = new Error("no responders");
const down = new Registrations(async () => { if (downAnswer instanceof Error) throw downAnswer; return downAnswer; }, (l) => said.push(l),
async () => { downAnswer = { registrations: [] }; });
await down.start();
assert.equal(down.written, false);
assert.match(said.join("\n"), /could not be read: no responders/, "a failed first view is said, never taken as none silently");
+48
View File
@@ -125,6 +125,54 @@ test("a member of a repository with no watched branch is merged plainly, noted n
}
});
// **A plain merge needs a view read since the last change heard** (design 47 H2 H-A-471, second addendum): while the
// watched branches are unread, or were read before a later registration-changed, every member is refused ("the watched
// branches are not read yet"), never merged with the note; a view read after the change merges the unwatched member
// plainly. A read that fails is said and asked again until it answers.
test("a member is merged plainly only from a watched-branches view read since the last registration-changed", async () => {
const { Registrations } = await import("../dist/registrations.js");
const NOT_READ = "the watched branches are not read yet";
const said: string[] = [];
const waits: number[] = [];
let answer: unknown = new Error("no responders");
const reg = new Registrations(async () => { if (answer instanceof Error) throw answer; return answer; }, (l) => said.push(l),
async (ms) => { waits.push(ms); answer = { registrations: [{ module: "app", origin: "novox/app", branches: ["main"] }] }; });
const hq = { by: "lead@shanks", pulls: [{ repository: "novox/hq", number: 799, head: B }, two.pulls[0]] };
const pulls = () => Object.assign(open(), { "novox/hq#799": { base: "main", head: B, state: "open", merged: false } });
const view = () => (reg.current ? reg.watched : null);
reg.hear({ module: "app", moved: ["watch"], version: 1, warrant: "q-1" });
// Unread: every member refused, nothing merged.
const f1 = forge(pulls());
const unread = await call(f1, hq, { watched: view });
assert.deepEqual([f1.merges, unread.members.map((m: any) => [m.state, m.why, m.note])],
[[], [["refused", NOT_READ, undefined], ["refused", NOT_READ, undefined]]], "an unread view refuses every member");
// A failed read is said and asked again until it answers; read, the view is current.
await reg.start();
assert.deepEqual([waits, reg.current], [[2_000], true]);
assert.match(said.join("\n"), /could not be read: no responders; no member is merged plainly until they are, asked again in 2s/);
assert.ok(reg.readAt && reg.changedAt && reg.readAt >= reg.changedAt, "the times of the last read and the last change are kept");
// A registration-changed heard after the read: stale, every member refused again.
reg.hear({ module: "app", moved: ["watch"], version: 2, warrant: "q-2" });
const f2 = forge(pulls());
const stale = await call(f2, hq, { watched: view });
assert.deepEqual([f2.merges, stale.members.map((m: any) => m.why)], [[], [NOT_READ, NOT_READ]], "a view read before a later change refuses");
// A change heard while a read is asked leaves the view stale.
let release!: () => void;
answer = { registrations: [{ module: "app", origin: "novox/app", branches: ["main"] }] };
const slow = new Registrations(() => new Promise((r) => { release = () => r(answer); }));
const asking = slow.start();
slow.hear({ module: "app", moved: ["watch"], version: 3, warrant: "q-3" });
release();
await asking;
assert.equal(slow.current, false, "a read asked before the change heard is not since it");
// Read again after the change: the unwatched member merges plainly with the note, the watched one as any call's.
await reg.start();
const f3 = forge(pulls());
const landed = await call(f3, hq, { watched: view });
assert.deepEqual([f3.merges, landed.members.map((m: any) => [m.state, m.note])],
[["novox/hq#799", "novox/app#5"], [["merged", "no delivery: the repository has no watched branch"], ["merged", undefined]]]);
});
test("a call is refused whole with no proved caller, no by, no registration or no pull request", async () => {
const f = forge(open());
await assert.rejects(call(f, two, {}, ""), /proved no caller account/);