baesian 0.0.0-stage → 1.0.1

package/dist/sync.js

@@ -0,0 +1,797 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, rmSync, rmdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { cite } from "./cite.js";
+import { isShallow, rootCommits } from "./git.js";
+import { Offline, REQUEST_MS, SignedOut, readGrant, reason, refreshGrant } from "./login.js";
+import { parseDoc } from "./frontmatter.js";
+import { CARD_ID, CardDraft, DefaultBranch, Presence, RelayState, asWritten, isLedgerBody, newestFormat, readRelayEntry, upgradeFile } from "./schema.js";
+import { alreadyExists, checkPath } from "./storage.js";
+import { DEFAULT_BRANCH } from "./store.js";
+import { readTrustFile } from "./trust.js";
+import { RELEASE_HEADER, TOO_OLD, VERSION } from "./version.js";
+// The CLI's side of the relay (M9d, Hosted Service sections 1 and 2): pulling the project's log into the live layer, as
+// if each file had been written here; pushing the files an agent writes, in order; `relay.json`, what this machine
+// keeps of the relay (P16 section 8); and, while `baesian wait` runs, the relay's live socket (B-bv49e) and the waiting
+// marker's heartbeat. There's no daemon: the commands sync when they already touch the live layer (`syncRelay()`,
+// `aroundFiling()`, `waitWithRelay()`). Offline, or signed out, everything local works as before, and what's new goes up
+// at the next command that reaches the relay. What counts is the store's to say: in a hosted repo, only what the service
+// signed (D138), and what was in the record when the repo was linked (B-45xz8). Those answers from before linking go up
+// once, at first link, before anyone answers on the website (B-3zjjx).
+/** `relay.json` in the live layer. */
+export const RELAY_STATE = "relay.json";
+/**
+ * The live layer's top folders a relay's log may write into: the files it holds, with the ledger and merges another
+ * machine found (D181). Never presence, cursors or markers.
+ */
+const PULLED = new Set(["cards", "decks", "verdicts", "rules", "topics", "preferences", "trust", "attachments", "ledger", "merges"]);
+const ID = CARD_ID.source.replace(/^\^|\$$/g, "");
+const REVISION = new RegExp(`^cards/(${ID})/r(\\d+)\\.md$`);
+const CARD_FILE = new RegExp(`^cards/(${ID})/(?:gate-r\\d+-cli\\.json|withdrawn\\.json|fallback-[0-9a-z]+\\.json)$`);
+const ATTACHMENT = new RegExp(`^attachments/(${ID})-[0-9a-z]+\\.json$`);
+const DECK = /^decks\/[a-z0-9][a-z0-9-]*\.md$/;
+const LEDGER = new RegExp(`^ledger/(${ID})-[0-9a-z]+\\.md$`);
+const MERGE = /^merges\/(?:[0-9a-f]{40}|[0-9a-f]{64})-[0-9a-f]{12}\.json$/;
+/**
+ * Whether a live-layer file is one of the kinds an agent writes, which a machine pushes (Hosted Service section 1): card
+ * revisions, the CLI's gate records, withdrawals, fallbacks, attachments and decks; and what the hooks write (D181), the
+ * ledger's entries and merges. Waiting markers go up only while `baesian wait` runs. Everything a person writes comes
+ * down, signed, and never goes up.
+ */
+export function agentWritten(rel) {
+    return DECK.test(rel) || REVISION.test(rel) || CARD_FILE.test(rel) || ATTACHMENT.test(rel) || LEDGER.test(rel) || MERGE.test(rel);
+}
+/** The card a file belongs to, if any: a ledger entry is its card's. */
+const cardOf = (rel) => (REVISION.exec(rel) ?? CARD_FILE.exec(rel) ?? ATTACHMENT.exec(rel) ?? LEDGER.exec(rel))?.[1];
+/**
+ * Whether a ledger entry may leave the machine (D181): its body is the one line naming the commit's short ID and the card
+ * (`ledgerBody()`), and it names its commit. Entries written before D120 listed the commit's files, and stay here.
+ */
+export function plainLedger(bytes) {
+    try {
+        const { meta, body } = parseDoc(Buffer.from(bytes).toString("utf8"));
+        const m = meta;
+        return typeof m.commit === "string" && typeof m.card === "string" && isLedgerBody(body, m.commit, m.card);
+    }
+    catch {
+        return false;
+    }
+}
+const encode = (text) => new TextEncoder().encode(text);
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const same = (a, b) => Buffer.from(a.buffer, a.byteOffset, a.byteLength).equals(Buffer.from(b.buffer, b.byteOffset, b.byteLength));
+const encodePath = (rel) => rel.split("/").map(encodeURIComponent).join("/");
+/** The relay answered, but not as hoped: a refusal that isn't about the grant. */
+export class RelayError extends Error {
+}
+/**
+ * The relay refused this Baesian as too old to read what it holds (B-4p43b), naming the release to install. Nothing was
+ * pulled or pushed; everything local works as before.
+ */
+export class TooOld extends RelayError {
+}
+// ---------------------------------------------------------------- the relay's addresses (B-7z97x)
+/**
+ * A machine's client for one project's relay: every address under `/v1/projects/{project}/`, with the grant's access
+ * token as `Authorization: Bearer`. The token is refreshed when it's within a minute of expiring, and on a 401: unless
+ * another command on this machine refreshed meanwhile, whose tokens it then takes from the grant file.
+ */
+export class RelayClient {
+    grant;
+    http;
+    constructor(grant, http = {}) {
+        this.grant = grant;
+        this.http = http;
+    }
+    get service() {
+        return this.grant.service;
+    }
+    get project() {
+        return this.grant.project;
+    }
+    /** The access token, refreshed first when it has less than a minute left. */
+    async token() {
+        if (Date.parse(this.grant.access_expires) - Date.now() < 60_000)
+            this.grant = await refreshGrant(this.grant, this.http);
+        return this.grant.access_token;
+    }
+    /** One request to the project's relay: its status and its JSON, if any. */
+    async request(method, rest, body) {
+        for (let attempt = 0;; attempt++) {
+            const token = await this.token();
+            const signal = this.http.signal ? AbortSignal.any([this.http.signal, AbortSignal.timeout(REQUEST_MS)]) : AbortSignal.timeout(REQUEST_MS);
+            let r;
+            try {
+                r = await (this.http.fetch ?? fetch)(`${this.service}/v1/projects/${encodeURIComponent(this.project)}/${rest}`, {
+                    method,
+                    headers: { authorization: `Bearer ${token}`, accept: "application/json", [RELEASE_HEADER]: VERSION, ...(body ? { "content-type": "application/octet-stream" } : {}) },
+                    ...(body ? { body } : {}),
+                    signal,
+                });
+            }
+            catch (e) {
+                throw new Offline(`couldn't reach ${this.service} (${reason(e)})`);
+            }
+            if (r.status === 401 && attempt === 0) {
+                await r.body?.cancel();
+                const current = readGrant(this.project);
+                if (!current || current.service !== this.service)
+                    throw new SignedOut(`this machine isn't signed in to project ${this.project} any more`);
+                this.grant = current.access_token !== token ? current : await refreshGrant(current, this.http);
+                continue;
+            }
+            if (r.status === 401)
+                throw new SignedOut(`${this.service} refused this machine's grant for project ${this.project}`);
+            const text = await r.text().catch(() => "");
+            let json;
+            try {
+                json = text ? JSON.parse(text) : undefined;
+            }
+            catch {
+                json = undefined;
+            }
+            // The relay serves no Baesian too old to read what it holds (B-4p43b): it says so before anything is pulled.
+            if (r.status === TOO_OLD && typeof json?.minimum === "string")
+                throw new TooOld(errorOf({ status: r.status, json }));
+            return { status: r.status, json };
+        }
+    }
+    /** The live updates' address (B-bv49e), as a WebSocket URL. */
+    liveUrl() {
+        return `${this.service.replace(/^http/, "ws")}/v1/projects/${encodeURIComponent(this.project)}/live`;
+    }
+}
+/**
+ * The service's spare keys (B-x47ek), from `GET /v1/keys`: service key files whose private halves are kept offline and
+ * which the service never signs with, for CI to pin beside the key in use. Or why they couldn't be read.
+ */
+export async function spareKeys(service, http = {}) {
+    const signal = http.signal ? AbortSignal.any([http.signal, AbortSignal.timeout(REQUEST_MS)]) : AbortSignal.timeout(REQUEST_MS);
+    let body;
+    try {
+        const r = await (http.fetch ?? fetch)(`${service}/v1/keys`, { headers: { accept: "application/json", [RELEASE_HEADER]: VERSION }, signal });
+        if (r.status !== 200) {
+            await r.body?.cancel();
+            return { keys: [], problem: `${service} didn't give its keys (HTTP ${r.status})` };
+        }
+        body = (await r.json());
+    }
+    catch (e) {
+        return { keys: [], problem: `couldn't read ${service}'s keys (${reason(e)})` };
+    }
+    const keys = [];
+    const problems = typeof body.problem === "string" ? [`${service} names a spare key it can't read: ${body.problem}`] : [];
+    for (const [i, raw] of (Array.isArray(body.spare) ? body.spare : []).entries()) {
+        try {
+            const k = readTrustFile(raw, `${service}'s spare key ${i + 1}`);
+            if (k.type === "service-key")
+                keys.push(k);
+        }
+        catch (e) {
+            problems.push(e instanceof Error ? e.message.split("\n")[0] : String(e));
+        }
+    }
+    return problems.length ? { keys, problem: problems.join("; ") } : { keys };
+}
+/** A relay's refusal, in its own words. */
+const errorOf = (r) => {
+    const e = r.json?.error;
+    return typeof e === "string" ? e.split("\n")[0] : `HTTP ${r.status}`;
+};
+/**
+ * Why this checkout mustn't sync with the project its config names (B-5gnea), or nothing: its history must start at the
+ * project's first commit, so a copy, such as one made from a template, doesn't mix its cards with the original's. A
+ * shallow clone can't see its first commit, and skips the check.
+ */
+export function linkProblem(store, c = store.config()) {
+    if (!c.project || !store.hasRepo)
+        return undefined;
+    if (!c.first_commit)
+        return `\`${store.personal ? ".git/baesian/config.json" : ".baesian/config.json"}\` names project ${c.project} but not the repo's first commit, so this checkout can't be told from a copy${cite("B-5gnea")}: run \`baesian login\` to link it again`;
+    const top = store.repo.toplevel;
+    if (isShallow(top))
+        return undefined;
+    const roots = rootCommits(top);
+    if (!roots)
+        return `this checkout has no commits yet, so it can't be checked against project ${c.project}'s first commit${cite("B-5gnea")}: it doesn't sync until it has one`;
+    if (roots.includes(c.first_commit))
+        return undefined;
+    return `this checkout's history doesn't start at project ${c.project}'s first commit (${c.first_commit.slice(0, 12)}), so it's a copy of that repo, such as one made from a template, not the repo itself: it doesn't sync with that project${cite("B-5gnea")}. Run \`baesian login\` to link it to a project of its own.`;
+}
+/** Whether this repo syncs, and if it does, the client to sync with: the config's service and project, and this machine's grant. */
+export function relayFor(store, http = {}) {
+    const c = store.config();
+    if (!c.service || !c.project)
+        return { kind: "off" };
+    const problem = linkProblem(store, c);
+    if (problem)
+        return { kind: "stopped", why: `relay: ${problem}` };
+    let grant;
+    try {
+        grant = readGrant(c.project);
+    }
+    catch (e) {
+        return { kind: "signed-out", why: `relay: ${e instanceof Error ? e.message : String(e)}` };
+    }
+    if (!grant || grant.service !== c.service) {
+        return {
+            kind: "signed-out",
+            why: `relay: this machine isn't signed in to project ${c.project} on ${c.service}, so nothing goes to the reviewer or comes back: ask the person to run \`baesian login\` here. Everything else works as before.`,
+        };
+    }
+    return { kind: "on", client: new RelayClient(grant, http) };
+}
+/** This machine's state for a relay, from `relay.json`; afresh when there's none, or it's for another relay, or unreadable. */
+export function readRelayState(store, service, project) {
+    const fresh = { type: "relay", format: newestFormat("relay"), service, project, pulled: 0, uploaded: [], at: new Date(0).toISOString() };
+    const bytes = store.storage.read(RELAY_STATE);
+    if (!bytes)
+        return fresh;
+    try {
+        const s = RelayState.parse(upgradeFile("relay", JSON.parse(Buffer.from(bytes).toString("utf8")), RELAY_STATE));
+        return s.service === service && s.project === project ? s : fresh;
+    }
+    catch {
+        // unreadable, or a newer Baesian's: pulling again from the start is harmless, since every file is written once
+        return fresh;
+    }
+}
+/** Replace `relay.json` whole (`Storage.replace`): a reader sees the old state or the new. */
+function saveState(store, w) {
+    const state = RelayState.parse({ type: "relay", format: newestFormat("relay"), service: w.service, project: w.project, pulled: w.pulled, uploaded: [...w.uploaded].sort(), ...(w.defaultBranch ? { default_branch: w.defaultBranch } : {}), at: new Date().toISOString() });
+    store.storage.replace(RELAY_STATE, encode(`${JSON.stringify(asWritten("relay", state), null, 2)}\n`));
+}
+const report = (state, notes = []) => ({ state, notes, pulled: [], pushed: [], replaced: [], renamed: [] });
+/** Whether the worktree's record holds a file of the live layer's. */
+function inRecord(store, rel) {
+    return store.hasRepo && existsSync(join(store.record, ...rel.split("/")));
+}
+/**
+ * Take a card whose ID another machine's card took on the relay out of this machine's layer and record, keeping what its
+ * agent filed, so the relay's card can come down under that ID, and this one be filed again under a new one.
+ */
+function takeOut(store, id) {
+    const latest = store.card(id);
+    if (!latest)
+        return undefined;
+    const asked = store.gateRecordBy(id, latest.meta.revision, "cli")?.asked;
+    const fields = new Set(Object.keys(CardDraft.shape));
+    const draft = Object.fromEntries(Object.entries(latest.meta).filter(([k]) => fields.has(k) && k !== "level" && k !== "type" && k !== "format"));
+    const out = { id, draft: { ...draft, ...(asked ? { level: asked } : {}) }, body: latest.body, agent: latest.meta.source_agent, model: latest.meta.source_model, withdrawn: store.withdrawal(id) !== undefined };
+    for (const f of store.storage.list(`cards/${id}`)) {
+        const rel = `cards/${id}/${f}`;
+        const bytes = store.storage.read(rel);
+        store.storage.remove(rel);
+        if (!store.hasRepo || !bytes)
+            continue;
+        const copy = join(store.record, "cards", id, f);
+        if (existsSync(copy) && same(readFileSync(copy), bytes))
+            rmSync(copy);
+    }
+    if (store.hasRepo) {
+        const dir = join(store.record, "cards", id);
+        if (existsSync(dir) && readdirSync(dir).length === 0)
+            rmdirSync(dir);
+    }
+    return out;
+}
+/**
+ * Write a file the relay sent, as if it had been written here: an exclusive create. If this machine wrote other bytes at
+ * that path first, the relay's copy is everyone's, so it replaces this one, in the worktree's record too, and the agent
+ * is told: a revision was revised on another machine first, as the local API's 409 says of a stale verdict. A card's
+ * first revision means another machine's new card took this one's ID: this one is taken out, to be filed again.
+ */
+function put(store, rel, bytes, run) {
+    try {
+        store.storage.create(rel, bytes);
+        run.out.pulled.push(rel);
+        return;
+    }
+    catch (e) {
+        if (!alreadyExists(e))
+            throw e;
+    }
+    const here = store.storage.read(rel);
+    if (here && same(here, bytes))
+        return;
+    const m = REVISION.exec(rel);
+    const taken = m?.[2] === "1" && !run.w.uploaded.has(rel) ? takeOut(store, m[1]) : undefined;
+    // Two machines found the same merge (D181), and said it differently (the cards each knew of, when): the relay's stands.
+    if (MERGE.test(rel)) {
+        store.storage.replace(rel, bytes);
+        run.out.replaced.push(rel);
+        return;
+    }
+    if (taken) {
+        run.refiles.push(taken);
+        store.storage.create(rel, bytes);
+        run.out.pulled.push(rel);
+        return;
+    }
+    store.storage.replace(rel, bytes);
+    if (store.hasRepo && here) {
+        const copy = join(store.record, ...rel.split("/"));
+        if (existsSync(copy) && same(readFileSync(copy), here))
+            writeFileSync(copy, bytes);
+    }
+    run.out.replaced.push(rel);
+    run.out.notes.push(m
+        ? `relay: ${m[1]} r${m[2]} was revised on another machine first, so yours wasn't sent, and the relay's r${m[2]} replaces it here: read it with \`baesian show ${m[1]}\`, and if yours still applies, revise again once it's returned to you`
+        : `relay: ${rel} was written first by another machine, with other bytes: the relay's copy replaces this machine's`);
+}
+/** Apply one entry of the relay's log: its file, with its `.sig` written first, so no reader sees it signed but without one. */
+function apply(store, e, run) {
+    let rel;
+    try {
+        rel = checkPath(e.path);
+    }
+    catch {
+        run.out.notes.push(`relay: skipped an entry that isn't a path in the live layer (${JSON.stringify(e.path)})`);
+        return;
+    }
+    if (!PULLED.has(rel.split("/")[0]) || rel.endsWith(".sig") || rel.endsWith(".tmp")) {
+        run.out.notes.push(`relay: skipped ${rel}, which isn't a kind of file the relay holds`);
+        return;
+    }
+    // Its body was removed by retention once it was delivered and its card finished (D137, B-9jqt4, B-ec3kj, M9f):
+    // nothing to write. What this machine already has, here or in the record, is unchanged; if it has neither, it's told.
+    if (e.body === undefined) {
+        if (!store.storage.read(rel) && !inRecord(store, rel))
+            run.missing.push(rel);
+        return;
+    }
+    const bytes = Buffer.from(e.body, "base64");
+    if (bytes.byteLength !== e.size || sha256(bytes) !== e.digest) {
+        run.out.notes.push(`relay: skipped ${rel}, whose bytes don't match the digest its entry gives`);
+        return;
+    }
+    if (e.sig !== undefined)
+        put(store, `${rel}.sig`, Buffer.from(e.sig, "base64"), run);
+    put(store, rel, bytes, run);
+    // An answer from before linking another machine uploaded (B-3zjjx) is one the relay has: this machine counts it only
+    // where its own record at the linking commit holds it (B-45xz8).
+    if (agentWritten(rel) || e.before_linking)
+        run.w.uploaded.add(rel);
+}
+/**
+ * Pull the log after the last sequence number pulled, page by page (`GET log`), into the live layer; then file again,
+ * under new IDs, the cards whose IDs another machine's cards took.
+ */
+async function pull(store, client, run) {
+    for (;;) {
+        const r = await client.request("GET", `log?after=${run.w.pulled}`);
+        if (r.status !== 200)
+            throw new RelayError(`the relay didn't give its log (${errorOf(r)})`);
+        const page = r.json;
+        // A log shorter than what this machine pulled is a project deleted with its owner's account and made again (B-b46z3,
+        // M9f): this machine starts afresh, so everything an agent wrote here goes up again.
+        if (typeof page?.head === "number" && page.head < run.w.pulled) {
+            run.out.notes.push(`relay: the project's log on ${client.service} is shorter than what this machine had pulled, so it was deleted and made again: this machine starts afresh, and sends everything its agents wrote`);
+            run.w.pulled = 0;
+            run.w.uploaded = new Set();
+            run.w.defaultBranch = undefined;
+            continue;
+        }
+        const entries = Array.isArray(page?.entries) ? page.entries : [];
+        for (const raw of entries) {
+            const e = readRelayEntry(raw);
+            apply(store, e, run);
+            run.w.pulled = Math.max(run.w.pulled, e.seq);
+        }
+        if (!page?.more || !entries.length)
+            break;
+    }
+    const missing = run.missing.splice(0);
+    if (missing.length) {
+        const cards = [...new Set(missing.map((p) => /(B-[0-9a-hjkmnp-tv-z]{5})/.exec(p)?.[1]).filter((c) => c !== undefined))];
+        run.out.notes.push(`relay: ${missing.length === 1 ? "a file" : `${missing.length} files`}${cards.length ? ` of ${cards.join(", ")}` : ""} had been sent to the project's other machines and then removed from the relay, after the time it keeps them${cite("B-9jqt4", "B-ec3kj")}, before this machine pulled ${missing.length === 1 ? "it" : "them"}: ${missing.length === 1 ? "it isn't" : "they aren't"} here or in this branch's record; a branch where another machine committed ${missing.length === 1 ? "it" : "them"} has ${missing.length === 1 ? "it" : "them"}`);
+    }
+    for (const r of run.refiles.splice(0)) {
+        if (r.withdrawn) {
+            run.out.notes.push(`relay: ${r.id} was already taken on the relay by another machine's card; yours was withdrawn, so it isn't filed again`);
+            continue;
+        }
+        const to = store.fileCard(r.draft, r.body, { agent: r.agent, model: r.model, force: true }).card.meta.id;
+        run.out.renamed.push({ from: r.id, to });
+        run.out.notes.push(`relay: ${r.id} was already taken on the relay by another machine's card, so yours is filed again as ${to}: use ${to} from now on (\`baesian show ${to}\`)`);
+    }
+}
+/**
+ * The agent-written files the relay doesn't have yet, in the order it takes them (M9c): decks first, then card
+ * revisions, each card's in order, then the rest (the CLI's gate records, withdrawals, fallbacks, attachments), then the
+ * ledger's entries whose body names only the commit (`plainLedger()`) and the merges (D181). When a repo is first linked,
+ * that's every one in the live layer (B-6k0rk).
+ */
+export function unsent(store, uploaded) {
+    const list = (dir) => store.storage.list(dir).sort();
+    const decks = list("decks").map((f) => `decks/${f}`).filter((p) => DECK.test(p));
+    const revisions = [];
+    const rest = [];
+    for (const id of list("cards")) {
+        const files = list(`cards/${id}`).map((f) => `cards/${id}/${f}`);
+        const revs = files.flatMap((p) => {
+            const m = REVISION.exec(p);
+            return m ? [{ p, n: Number(m[2]) }] : [];
+        });
+        revisions.push(...revs.sort((a, b) => a.n - b.n).map((r) => r.p));
+        rest.push(...files.filter((p) => CARD_FILE.test(p)));
+    }
+    rest.push(...list("attachments").map((f) => `attachments/${f}`).filter((p) => ATTACHMENT.test(p)));
+    const ledger = list("ledger").map((f) => `ledger/${f}`).filter((p) => LEDGER.test(p) && !uploaded.has(p) && plainLedger(store.storage.read(p) ?? new Uint8Array()));
+    const merges = list("merges").map((f) => `merges/${f}`).filter((p) => MERGE.test(p));
+    return [...decks, ...revisions, ...rest, ...ledger, ...merges].filter((p) => !uploaded.has(p));
+}
+/** The folders of what a person writes: answers, rules, topic merges and preference files (Hosted Service section 3). */
+const ANSWERS = ["verdicts", "rules", "topics", "preferences"];
+/**
+ * Whether someone has answered on the website, as far as this machine has pulled: anything in the answers' folders with
+ * the service's signature. The relay then takes no more answers from before linking (B-3zjjx), so none are offered.
+ */
+function answeredOnWebsite(store) {
+    return ANSWERS.some((dir) => store.storage.list(dir).some((f) => f.endsWith(".sig")));
+}
+/**
+ * The answers, rules, topic merges and preference files from before linking that the relay doesn't have yet (B-3zjjx):
+ * those that count here as B-45xz8 counts them, in the order it takes them. None once someone has answered on the website.
+ */
+export function unsentBeforeLinking(store, uploaded) {
+    if (answeredOnWebsite(store))
+        return [];
+    return store.answersFromBeforeLinking().filter((p) => !uploaded.has(p));
+}
+/**
+ * Push what the relay doesn't have yet: what agents wrote, then, at first link, the answers from before linking
+ * (B-3zjjx). A file another machine wrote first, with other bytes, is refused (409); the pull that follows brings the
+ * relay's copy, and tells the agent (`put()`). A card whose text the relay removed (410, M9f) takes nothing more: its
+ * files stay here and in the record, and aren't offered again. Anything else refused stays here, and is offered again at
+ * the next sync. Returns whether anything was refused for being written elsewhere first.
+ */
+async function push(store, client, run) {
+    const blocked = new Set();
+    const removed = new Set();
+    let conflicted = false;
+    const files = unsent(store, run.w.uploaded);
+    const early = unsentBeforeLinking(store, run.w.uploaded);
+    if (files.length + early.length)
+        run.sending?.(files.length + early.length);
+    for (const rel of files) {
+        const card = cardOf(rel);
+        if (card && removed.has(card)) {
+            run.w.uploaded.add(rel);
+            continue;
+        }
+        if (card && blocked.has(card))
+            continue;
+        const bytes = store.storage.read(rel);
+        if (!bytes)
+            continue;
+        const r = await client.request("PUT", `files/${encodePath(rel)}`, bytes);
+        if (r.status === 200 || r.status === 201) {
+            run.w.uploaded.add(rel);
+            run.out.pushed.push(rel);
+            continue;
+        }
+        if (r.status === 410) {
+            // The relay removed this card's text after the time it keeps it (M9f): it takes nothing more for the card. Its files
+            // stay here and in the record, and aren't offered again.
+            run.w.uploaded.add(rel);
+            if (card)
+                removed.add(card);
+            run.out.notes.push(`relay: ${card ?? rel}'s text was removed from the relay after the time it keeps it${cite("B-9jqt4", "B-ec3kj")}, so what's new for it stays here and in the repo's record, and the website won't show it`);
+            continue;
+        }
+        if (card)
+            blocked.add(card);
+        if (r.status === 503)
+            throw new RelayError(`the relay can't take files just now (${errorOf(r)})`);
+        if (r.status === 409)
+            conflicted = true;
+        else
+            run.out.notes.push(`relay: refused ${rel} (${errorOf(r)}); it stays here, and is offered again at the next sync`);
+    }
+    for (const rel of early) {
+        const bytes = store.storage.read(rel);
+        if (!bytes)
+            continue;
+        const r = await client.request("PUT", `files/${encodePath(rel)}`, bytes);
+        if (r.status === 200 || r.status === 201) {
+            run.w.uploaded.add(rel);
+            run.out.pushed.push(rel);
+            continue;
+        }
+        if (r.status === 503)
+            throw new RelayError(`the relay can't take files just now (${errorOf(r)})`);
+        if (r.json?.before_linking === "closed") {
+            run.out.notes.push(`relay: someone has answered on the website, so the answers from before linking that hadn't gone up stay in git, where they still count${cite("B-45xz8")}; the website shows their cards as waiting${cite("B-3zjjx")}`);
+            break;
+        }
+        run.out.notes.push(`relay: refused ${rel}, from before linking (${errorOf(r)}); it stays here, and is offered again at the next sync`);
+    }
+    await pushDefaultBranch(store, client, run);
+    return conflicted;
+}
+/**
+ * Send the repo's default branch (B-jr8mk), as git says it here (`Store.defaultBranch`), when it isn't what this machine
+ * last sent: `default-branch.json`, only its name, which the relay keeps in place of the one before, for the website's
+ * branches panel. Quietly: one the relay doesn't take (an older relay's) is offered again at the next sync, and it's
+ * never counted among the files sent. Only a machine whose reading changed sends it, so two that read it differently
+ * don't take turns.
+ */
+async function pushDefaultBranch(store, client, run) {
+    if (!store.hasRepo)
+        return;
+    const branch = store.defaultBranch();
+    if (!branch || branch === run.w.defaultBranch)
+        return;
+    let bytes;
+    try {
+        bytes = encode(`${JSON.stringify(asWritten("default-branch", DefaultBranch.parse({ type: "default-branch", format: newestFormat("default-branch"), branch })))}\n`);
+    }
+    catch {
+        return; // not a name git allows: nothing to send
+    }
+    const r = await client.request("PUT", `files/${DEFAULT_BRANCH}`, bytes);
+    if (r.status === 200 || r.status === 201)
+        run.w.defaultBranch = branch;
+}
+/** Pull, push, or both, with this client, keeping `relay.json` up to date with whatever got done. */
+async function syncWith(store, client, o) {
+    const s = readRelayState(store, client.service, client.project);
+    const run = { w: { service: s.service, project: s.project, pulled: s.pulled, uploaded: new Set(s.uploaded), defaultBranch: s.default_branch }, out: report("synced"), refiles: [], missing: [], ...(o.sending ? { sending: o.sending } : {}) };
+    try {
+        if (o.pull)
+            await pull(store, client, run);
+        // A push refused for what another machine wrote first pulls the relay's copy, then pushes again: a card filed again
+        // under a new ID goes up in the next round.
+        if (o.push)
+            for (let round = 0; round < 3 && (await push(store, client, run)); round++)
+                await pull(store, client, run);
+    }
+    catch (e) {
+        run.out.state = e instanceof SignedOut ? "signed-out" : "offline";
+        run.out.notes.push(failureNote(e, client.service));
+    }
+    finally {
+        saveState(store, run.w);
+    }
+    return run.out;
+}
+/** What the agent is told when a sync couldn't finish. */
+function failureNote(e, service) {
+    if (e instanceof Offline)
+        return `relay: ${e.message}. Everything here works as before; what's new goes up at the next command that reaches the relay.`;
+    if (e instanceof SignedOut)
+        return `relay: ${e.message}. Ask the person to run \`baesian login\` here; until then nothing goes to the reviewer or comes back.`;
+    if (e instanceof TooOld)
+        return `relay: ${service} refused this Baesian${cite("B-4p43b")}: ${e.message} Everything here works as before; until it's upgraded, nothing goes to the reviewer or comes back.`;
+    return `relay: syncing with ${service} stopped: ${e instanceof Error ? e.message.split("\n")[0] : String(e)}`;
+}
+/**
+ * Sync this repo with its relay, if it's linked: pull, then push. Never throws for the network, the grant or the relay:
+ * what went wrong is in the report's notes, and the live layer works as before. A repo that isn't linked does nothing.
+ */
+export async function syncRelay(store, o = {}) {
+    const link = relayFor(store, o);
+    if (link.kind === "off")
+        return report("off");
+    if (link.kind !== "on")
+        return report(link.kind, [link.why]);
+    return syncWith(store, link.client, { pull: o.pull ?? true, push: o.push ?? true, ...(o.sending ? { sending: o.sending } : {}) });
+}
+/**
+ * A filing command (Hosted Service section 1): pull first, so the filing check sees other machines' open cards (D36),
+ * then run it, then push what it wrote. When the pull couldn't reach the relay, the push isn't tried: the command doesn't
+ * wait twice. Returns what the command returned, and the notes for the agent.
+ */
+export async function aroundFiling(store, op, http = {}) {
+    const before = await syncRelay(store, { ...http, push: false });
+    const value = await op();
+    const after = before.state === "synced" ? await syncRelay(store, { ...http, pull: false }) : undefined;
+    return { value, notes: [...before.notes, ...(after?.notes ?? [])] };
+}
+// ---------------------------------------------------------------- waiting on the relay (B-bv49e)
+/** How long a closed or failed live socket waits before it's opened again, by attempt. */
+const RECONNECT_MS = [1000, 2000, 5000, 10_000];
+/**
+ * How often a wait pulls without being told to (B-xnae9): a wait in the background may run for hours, over a laptop's
+ * sleep or a socket that died without closing, and a `changed` message missed then would leave it waiting on an answer
+ * already given.
+ */
+export const RESYNC_MS = 5 * 60_000;
+/** Several markers refreshed at one beat read the reviewer's presence once. */
+const PRESENCE_GAP_MS = 5000;
+/**
+ * While `baesian wait` runs in a linked repo: the relay's live socket, `GET /v1/projects/{p}/live`, whose `changed`
+ * messages each start a pull, so an answer reaches the live layer within a moment and the wait's own poll finds it; the
+ * waiting markers, sent up with each beat and removed when their cards are answered or the wait ends (D90); and the
+ * reviewer's presence from the relay's state, written into the live layer when it's newer, so the wait knows when they're
+ * away (D41). A socket opened again pulls at once, for what changed while it was closed; and it pulls every `RESYNC_MS`
+ * besides. Until a sync both ways has gone through (`unsynced`: the wait started offline), each pull pushes too, so the
+ * cards reach the reviewer.
+ */
+class Listener {
+    store;
+    client;
+    unsynced;
+    ws;
+    closed = false;
+    opened = false;
+    attempts = 0;
+    timer;
+    resync;
+    pulling;
+    again = false;
+    presenceAt = 0;
+    queue = Promise.resolve();
+    notes = [];
+    constructor(store, client, unsynced = false) {
+        this.store = store;
+        this.client = client;
+        this.unsynced = unsynced;
+    }
+    /** Open the socket. A failure is retried until the wait ends; the wait goes on either way. */
+    async open() {
+        if (this.closed)
+            return;
+        if (!this.resync) {
+            this.resync = setInterval(() => this.pull(), RESYNC_MS);
+            this.resync.unref?.();
+        }
+        let token;
+        try {
+            token = await this.client.token();
+        }
+        catch (e) {
+            this.note(e);
+            return this.retry();
+        }
+        if (this.closed)
+            return;
+        const ws = new WebSocket(this.client.liveUrl(), { headers: { authorization: `Bearer ${token}`, [RELEASE_HEADER]: VERSION } });
+        this.ws = ws;
+        ws.onopen = () => {
+            this.attempts = 0;
+            // Opened again, after a close: what changed meanwhile sent no message here. Or the first sync didn't go through.
+            if (this.opened || this.unsynced)
+                this.pull();
+            this.opened = true;
+        };
+        ws.onmessage = (m) => {
+            try {
+                if (JSON.parse(String(m.data)).type === "changed")
+                    this.pull();
+            }
+            catch {
+                // not a message the relay sends: ignored
+            }
+        };
+        ws.onclose = () => {
+            if (this.ws === ws)
+                this.ws = undefined;
+            this.retry();
+        };
+        ws.onerror = () => {
+            // onclose follows, and retries
+        };
+    }
+    retry() {
+        if (this.closed || this.timer)
+            return;
+        const ms = RECONNECT_MS[Math.min(this.attempts++, RECONNECT_MS.length - 1)];
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.open();
+        }, ms);
+    }
+    note(e) {
+        const line = failureNote(e, this.client.service);
+        if (!this.notes.includes(line))
+            this.notes.push(line);
+    }
+    /** Pull now, or once more after the pull that's running: changes that come while pulling aren't missed. */
+    pull() {
+        if (this.pulling) {
+            this.again = true;
+            return;
+        }
+        this.pulling = (async () => {
+            do {
+                this.again = false;
+                const both = this.unsynced;
+                const r = await syncWith(this.store, this.client, { pull: true, push: both });
+                if (both && r.state === "synced")
+                    this.unsynced = false;
+                for (const n of r.notes)
+                    if (!this.notes.includes(n))
+                        this.notes.push(n);
+            } while (this.again && !this.closed);
+        })().finally(() => {
+            this.pulling = undefined;
+        });
+    }
+    /** A waiting marker, written or refreshed (PUT, with the presence read afresh) or removed (DELETE), in order. */
+    marker(m) {
+        this.queue = this.queue
+            .then(async () => {
+            if (m.removed) {
+                await this.client.request("DELETE", `files/${encodePath(m.path)}`);
+                return;
+            }
+            const bytes = this.store.storage.read(m.path);
+            if (bytes)
+                await this.client.request("PUT", `files/${encodePath(m.path)}`, bytes);
+            await this.presence();
+        })
+            .catch((e) => this.note(e));
+    }
+    /** The reviewer's presence on the relay (`GET state`), into the live layer when it's newer than what's there. */
+    async presence() {
+        if (Date.now() - this.presenceAt < PRESENCE_GAP_MS)
+            return;
+        this.presenceAt = Date.now();
+        const r = await this.client.request("GET", "state");
+        if (r.status !== 200)
+            return;
+        const p = Presence.safeParse(r.json?.presence);
+        if (!p.success)
+            return;
+        const here = this.store.presence();
+        if (here && Date.parse(here.at) >= Date.parse(p.data.at))
+            return;
+        this.store.storage.replace("presence.json", encode(`${JSON.stringify(asWritten("presence", p.data))}\n`));
+    }
+    /** Close the socket and stop retrying; let the markers' removal and a pull in progress finish, for a few seconds at most. */
+    async close() {
+        this.closed = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        if (this.resync)
+            clearInterval(this.resync);
+        this.resync = undefined;
+        try {
+            this.ws?.close();
+        }
+        catch {
+            // already closing
+        }
+        let limit;
+        await Promise.race([Promise.all([this.queue, this.pulling]), new Promise((done) => (limit = setTimeout(done, 3000)))]);
+        clearTimeout(limit);
+    }
+}
+/**
+ * `baesian wait` in a linked repo (B-bv49e): sync first, so the cards are on the relay and any answer already given is
+ * here; then run the wait it's given (`waitOp`, or `waitAllOp` on several cards, B-xnae9), with the relay's live socket
+ * starting a pull at each change, and the waiting markers going up as a heartbeat. Offline or signed out, it waits on the
+ * live layer alone, as before; but a wait with no time limit (`WaitOptions.untilAnswered`) that starts offline listens
+ * all the same, syncing once the socket opens, since it may run for hours.
+ */
+export async function waitWithRelay(store, wait, opts, http = {}) {
+    const link = relayFor(store, http);
+    if (link.kind === "off")
+        return { value: await wait(opts), notes: [] };
+    if (link.kind !== "on")
+        return { value: await wait(opts), notes: [link.why] };
+    const first = await syncWith(store, link.client, { pull: true, push: true });
+    const listen = first.state === "synced" || (first.state === "offline" && opts.untilAnswered === true);
+    if (!listen)
+        return { value: await wait(opts), notes: first.notes };
+    const live = new Listener(store, link.client, first.state !== "synced");
+    await live.open();
+    try {
+        const value = await wait({
+            ...opts,
+            onMarker: (m) => {
+                live.marker(m);
+                opts.onMarker?.(m);
+            },
+        });
+        return { value, notes: [...first.notes, ...live.notes] };
+    }
+    finally {
+        await live.close();
+    }
+}
+//# sourceMappingURL=sync.js.map