@fluado/enmetu 0.0.0-stage → 0.2.0

package/dist/sync/syncCycleController.d.ts

@@ -0,0 +1,71 @@
+import type { CommitLocalChanges } from '../commit/commitLocalChangesController.js';
+import type { IClock } from '../contracts/IClock.js';
+import type { IGitReader } from '../contracts/IGitReader.js';
+import type { IGitWriter } from '../contracts/IGitWriter.js';
+import type { IHaltStore } from '../contracts/IHaltStore.js';
+import type { ILogger } from '../contracts/ILogger.js';
+import type { IPathQuarantine } from '../contracts/IPathQuarantine.js';
+import type { SyncCycleInput, SyncCycleResult } from '../contracts/ISyncCycle.js';
+import type { IntegrateUpstream } from './integrateUpstreamController.js';
+/**
+ * Consecutive cycles whose rebase git refused to start before the cycle
+ * reports paused REBASE_REFUSED instead of busy (design 12.7, Decision 82).
+ */
+export declare const REBASE_REFUSED_AFTER = 3;
+export type { SyncCycleInput, SyncCycleResult };
+export interface SyncCycleDeps {
+    readonly git: IGitReader;
+    /** HaltGuardGitWriter in production. */
+    readonly writer: IGitWriter;
+    readonly halt: IHaltStore;
+    /** Only for step 4, a memento left pending by an earlier cycle; holding is integrate's. */
+    readonly quarantine: IPathQuarantine;
+    /** integrateUpstreamController with its deps bound (the same guarded writer, journal and quarantine). */
+    readonly integrate: IntegrateUpstream;
+    /** commitLocalChangesController with its deps bound; step 5 commits through it (design 12.7). */
+    readonly commit: CommitLocalChanges;
+    readonly logger: ILogger;
+    readonly clock: IClock;
+}
+/**
+ * Controller: one sync cycle, the same chain for every trigger (design 1.10).
+ * GIT_INDEX_LOCKED thrown by any step returns busy.
+ *
+ * 1. Halt gate: halt.read(); no git call precedes it (D3).
+ * 2. Repository gate: index.lock busy, foreign operation and detached HEAD pause.
+ * 3. Upstream of the checked-out branch, every cycle (D6): none pauses NO_UPSTREAM,
+ *    a local one (remote '.') pauses UPSTREAM_NOT_REMOTE (Decision 28).
+ * 4. Pending quarantine memento: restore it; failed halts QUARANTINE_RESTORE_FAILED.
+ * 5. Commit local changes, skipped on a clean status (which also clears the
+ *    memory's partialStagingSince): after the status read the repository
+ *    state is read again (Decision 52), then deps.commit runs with the commit
+ *    memory (design 12.7); busy and paused return, committed and nothing go
+ *    on, waiting goes on and is the outcome unless a later step returns
+ *    something else. The check right before the commit is the commit step's,
+ *    under index.lock.
+ * 6. Remote check: ls-remote, tracking ref, verified ref (seeded from tracking when missing).
+ * 7. Verify and fetch: fetch into the incoming ref when the remote moved; the remote sha
+ *    must descend from the verified sha, else halt UPSTREAM_REWRITTEN; then move the
+ *    tracking and verified refs with compare-and-swap.
+ * 8. Divergence against the remote sha.
+ * 9. Integrate when behind (deps.integrate); conflict, busy, paused and halted are returned unchanged.
+ *    When step 5 returned waiting PARTIAL_SELECTION_STAGED, or waiting and
+ *    git.hasStagedChanges() says the real index differs from HEAD (git would
+ *    refuse the rebase), integrate is skipped, UNPUSHED reported and waiting
+ *    returned (Decision 84).
+ *    not-started: the count of consecutive refusals (input.notStartedRebases)
+ *    goes up by one; the first logs REBASE_NOT_STARTED with git's first stderr
+ *    line; UNPUSHED is reported; the outcome is busy, or paused REBASE_REFUSED
+ *    from REBASE_REFUSED_AFTER on (Decision 82). Any other integrate result, or
+ *    a branch not behind, resets the count to 0; a cycle that returns before
+ *    step 8 carries it unchanged.
+ * 10. Push when ahead: the branch's commit, resolved once, pushed by its sha;
+ *     the verified ref moves to that sha (Decision 111). A branch gone since
+ *     step 2 pauses BRANCH_CHANGED.
+ * 11. synced.
+ * UNPUSHED is logged with the count on every cycle that reaches the remote check and ends
+ * with local commits not on the upstream, halts aside (D2); the pauses and the busy index
+ * of steps 2, 3 and 5 return before it and are reported once (Decision 53).
+ * PAUSED, BUSY and OFFLINE are the runner's to log, once per change.
+ */
+export declare function syncCycleController(input: SyncCycleInput, deps: SyncCycleDeps): Promise<SyncCycleResult>;

package/dist/sync/syncCycleController.js

@@ -0,0 +1,345 @@
+import { EnmetuError } from '../contracts/errors.js';
+import { EMPTY_COMMIT_MEMORY, } from '../contracts/syncTypes.js';
+import { withLastMove } from '../core/commit/commitMemory.js';
+import { withCycleId } from '../core/errors/withCycleId.js';
+import { incomingRefFor, verifiedRefFor } from '../core/git/enmetuRefs.js';
+import { logRestoreWarnings } from '../core/quarantine/restoreWarnings.js';
+import { recordHalt } from '../halt/recordHalt.js';
+/** The remote name git gives an upstream that is a branch of this repository. */
+const LOCAL_REMOTE = '.';
+const SHORT_SHA_LENGTH = 7;
+/**
+ * Consecutive cycles whose rebase git refused to start before the cycle
+ * reports paused REBASE_REFUSED instead of busy (design 12.7, Decision 82).
+ */
+export const REBASE_REFUSED_AFTER = 3;
+/**
+ * Controller: one sync cycle, the same chain for every trigger (design 1.10).
+ * GIT_INDEX_LOCKED thrown by any step returns busy.
+ *
+ * 1. Halt gate: halt.read(); no git call precedes it (D3).
+ * 2. Repository gate: index.lock busy, foreign operation and detached HEAD pause.
+ * 3. Upstream of the checked-out branch, every cycle (D6): none pauses NO_UPSTREAM,
+ *    a local one (remote '.') pauses UPSTREAM_NOT_REMOTE (Decision 28).
+ * 4. Pending quarantine memento: restore it; failed halts QUARANTINE_RESTORE_FAILED.
+ * 5. Commit local changes, skipped on a clean status (which also clears the
+ *    memory's partialStagingSince): after the status read the repository
+ *    state is read again (Decision 52), then deps.commit runs with the commit
+ *    memory (design 12.7); busy and paused return, committed and nothing go
+ *    on, waiting goes on and is the outcome unless a later step returns
+ *    something else. The check right before the commit is the commit step's,
+ *    under index.lock.
+ * 6. Remote check: ls-remote, tracking ref, verified ref (seeded from tracking when missing).
+ * 7. Verify and fetch: fetch into the incoming ref when the remote moved; the remote sha
+ *    must descend from the verified sha, else halt UPSTREAM_REWRITTEN; then move the
+ *    tracking and verified refs with compare-and-swap.
+ * 8. Divergence against the remote sha.
+ * 9. Integrate when behind (deps.integrate); conflict, busy, paused and halted are returned unchanged.
+ *    When step 5 returned waiting PARTIAL_SELECTION_STAGED, or waiting and
+ *    git.hasStagedChanges() says the real index differs from HEAD (git would
+ *    refuse the rebase), integrate is skipped, UNPUSHED reported and waiting
+ *    returned (Decision 84).
+ *    not-started: the count of consecutive refusals (input.notStartedRebases)
+ *    goes up by one; the first logs REBASE_NOT_STARTED with git's first stderr
+ *    line; UNPUSHED is reported; the outcome is busy, or paused REBASE_REFUSED
+ *    from REBASE_REFUSED_AFTER on (Decision 82). Any other integrate result, or
+ *    a branch not behind, resets the count to 0; a cycle that returns before
+ *    step 8 carries it unchanged.
+ * 10. Push when ahead: the branch's commit, resolved once, pushed by its sha;
+ *     the verified ref moves to that sha (Decision 111). A branch gone since
+ *     step 2 pauses BRANCH_CHANGED.
+ * 11. synced.
+ * UNPUSHED is logged with the count on every cycle that reaches the remote check and ends
+ * with local commits not on the upstream, halts aside (D2); the pauses and the busy index
+ * of steps 2, 3 and 5 return before it and are reported once (Decision 53).
+ * PAUSED, BUSY and OFFLINE are the runner's to log, once per change.
+ */
+export async function syncCycleController(input, deps) {
+    const carried = {
+        commitMemory: input.commitMemory,
+        notStartedRebases: input.notStartedRebases,
+    };
+    const outcome = (cycleOutcome) => resultOf(cycleOutcome, null, carried);
+    try {
+        return await runCycle(input, deps, carried, outcome);
+    }
+    catch (error) {
+        if (error instanceof EnmetuError && error.code === 'GIT_INDEX_LOCKED') {
+            return outcome({ kind: 'busy' });
+        }
+        throw withCycleId(error, input.cycleId);
+    }
+}
+async function runCycle(input, deps, carried, outcome) {
+    const { cycleId } = input;
+    // --- Step 1: halt gate, before any git call (D3) ---
+    const haltRecord = await deps.halt.read();
+    if (haltRecord !== null) {
+        return outcome({ kind: 'halted', code: haltRecord.code });
+    }
+    // --- Step 2: repository gate ---
+    const state = await deps.git.repositoryState();
+    if (state.indexLocked) {
+        return outcome({ kind: 'busy' });
+    }
+    if (state.operation !== null) {
+        // A person's rebase, merge, cherry-pick, revert or bisect is never touched.
+        return outcome({ kind: 'paused', reason: 'FOREIGN_OPERATION' });
+    }
+    if (state.branchRef === null) {
+        return outcome({ kind: 'paused', reason: 'DETACHED_HEAD' });
+    }
+    const branchRef = state.branchRef;
+    // --- Step 3: the upstream of whatever branch is checked out now (D6) ---
+    const upstream = await deps.git.upstream(branchRef);
+    if (upstream === null) {
+        return outcome({ kind: 'paused', reason: 'NO_UPSTREAM' });
+    }
+    if (upstream.remote === LOCAL_REMOTE) {
+        // A branch switched to mid-run whose upstream is another local branch: a
+        // push would fast-forward that branch, which nobody asked enmetu to touch.
+        return outcome({ kind: 'paused', reason: 'UPSTREAM_NOT_REMOTE' });
+    }
+    // --- Step 4: a memento an earlier cycle left pending is restored first ---
+    if (await deps.quarantine.hasPending()) {
+        const restore = await deps.quarantine.restore();
+        if (restore.kind === 'failed') {
+            return outcome(await haltWith('QUARANTINE_RESTORE_FAILED', `restoring a pending quarantine memento failed (${restore.detail}); the memento is kept`, cycleId, deps));
+        }
+        if (restore.kind === 'restored') {
+            logRestoreWarnings(restore, cycleId, deps.logger);
+        }
+    }
+    // --- Step 5: commit local changes; a clean status writes nothing to the index ---
+    let waiting = null;
+    // The commit's parent when this cycle committed: step 9 records the pull
+    // from there, so the repair covers the commit and the pull in one move.
+    let committedFrom = null;
+    if ((await deps.git.status()).length > 0) {
+        // A person's merge, cherry-pick or revert that stopped after step 2 is in
+        // that status; the commit step would only find it under index.lock (Decision 52).
+        if ((await deps.git.repositoryState()).operation !== null) {
+            return outcome({ kind: 'paused', reason: 'FOREIGN_OPERATION' });
+        }
+        const committed = await deps.commit({
+            cycleId,
+            memory: carried.commitMemory ?? EMPTY_COMMIT_MEMORY,
+            branchRef,
+        });
+        carried.commitMemory = committed.memory;
+        if (committed.kind === 'busy') {
+            return outcome({ kind: 'busy' });
+        }
+        if (committed.kind === 'paused') {
+            return outcome({ kind: 'paused', reason: committed.reason });
+        }
+        if (committed.kind === 'waiting') {
+            waiting = committed.reason;
+        }
+        if (committed.kind === 'committed') {
+            committedFrom = committed.memory.lastMove?.from ?? null;
+        }
+    }
+    else if (carried.commitMemory !== undefined) {
+        // A clean tree has no staged selection, so a wait for one is over.
+        carried.commitMemory = {
+            partialStagingSince: null,
+            rejection: carried.commitMemory.rejection,
+            residueTree: carried.commitMemory.residueTree,
+            lastMove: carried.commitMemory.lastMove,
+        };
+    }
+    // --- Step 6: remote check ---
+    const verifiedRef = verifiedRefFor(branchRef);
+    const remoteHead = await deps.git.remoteHead(upstream.remote, upstream.remoteRef);
+    const trackingSha = await deps.git.resolveCommit(upstream.trackingRef);
+    let verifiedSha = await deps.git.resolveCommit(verifiedRef);
+    if (remoteHead.kind === 'unreachable') {
+        await reportUnpushedAgainstLastKnown(trackingSha ?? verifiedSha, upstream, cycleId, deps);
+        return outcome({ kind: 'offline' });
+    }
+    if (remoteHead.kind === 'absent') {
+        // A deleted remote branch is never recreated by enmetu, so commits pile
+        // up locally while it is gone; they are reported every cycle (D2).
+        await reportUnpushedAgainstLastKnown(trackingSha ?? verifiedSha, upstream, cycleId, deps);
+        return outcome({ kind: 'paused', reason: 'UPSTREAM_GONE' });
+    }
+    const remoteSha = remoteHead.sha;
+    if (verifiedSha === null && trackingSha !== null) {
+        // First start: the tracking ref is the best reference point there is.
+        await deps.writer.updateRef(verifiedRef, trackingSha, null);
+        verifiedSha = trackingSha;
+    }
+    // --- Step 7: verify and fetch; refs move only after the ancestry check ---
+    if (remoteSha !== trackingSha) {
+        const fetched = await deps.writer.fetch(upstream.remote, upstream.remoteRef, incomingRefFor(branchRef));
+        if (fetched.kind === 'failed') {
+            await reportUnpushedAgainstLastKnown(trackingSha ?? verifiedSha, upstream, cycleId, deps);
+            return outcome({ kind: 'offline' });
+        }
+    }
+    // Checked even when the fetch was skipped: a person's own fetch may already
+    // have moved the tracking ref to a rewritten upstream.
+    if (verifiedSha !== null && verifiedSha !== remoteSha) {
+        if (!(await deps.git.isAncestor(verifiedSha, remoteSha))) {
+            return outcome(await haltWith('UPSTREAM_REWRITTEN', `${upstream.remote} ${upstream.remoteRef} now points at ${remoteSha}, which does not descend from ${verifiedSha}, the upstream enmetu last verified; the upstream was rewritten`, cycleId, deps));
+        }
+    }
+    if (trackingSha !== remoteSha) {
+        await deps.writer.updateRef(upstream.trackingRef, remoteSha, trackingSha);
+    }
+    if (verifiedSha !== remoteSha) {
+        await deps.writer.updateRef(verifiedRef, remoteSha, verifiedSha);
+    }
+    // --- Step 8: divergence against the verified remote sha ---
+    const divergence = await deps.git.divergence(remoteSha);
+    const behind = divergence.behind;
+    let ahead = divergence.ahead;
+    // --- Step 9: integrate when behind ---
+    if (behind === 0) {
+        carried.notStartedRebases = resetCount(carried.notStartedRebases);
+    }
+    else {
+        // git rebase refuses an index that differs from HEAD (Decision 84). A
+        // selection step 5 waited for holds integrate back even when the person
+        // committed it since: step 5 committed nothing, so the person's other
+        // edits are still uncommitted, and the quarantine would hold them while a
+        // rebase runs under the person's hands; the next cycle commits first.
+        if (waiting === 'PARTIAL_SELECTION_STAGED' ||
+            (waiting !== null && (await deps.git.hasStagedChanges()))) {
+            reportUnpushed(ahead, upstream, cycleId, deps);
+            return outcome({ kind: 'waiting', reason: waiting });
+        }
+        const pulledFrom = committedFrom ?? (await deps.git.headCommit());
+        const integrated = await deps.integrate({
+            cycleId,
+            branchRef,
+            ontoSha: remoteSha,
+            behind,
+            knownConflict: input.knownConflict,
+        });
+        if (integrated.kind === 'not-started') {
+            const refusals = (carried.notStartedRebases ?? 0) + 1;
+            carried.notStartedRebases = refusals;
+            if (refusals === 1) {
+                deps.logger.log({
+                    level: 'WARN',
+                    code: 'REBASE_NOT_STARTED',
+                    message: `git did not start the rebase onto ${shortSha(remoteSha)} (${firstLine(integrated.detail)}); enmetu retries on the next cycle`,
+                    cycleId,
+                });
+            }
+            reportUnpushed(ahead, upstream, cycleId, deps);
+            return outcome(refusals >= REBASE_REFUSED_AFTER
+                ? { kind: 'paused', reason: 'REBASE_REFUSED' }
+                : { kind: 'busy' });
+        }
+        carried.notStartedRebases = resetCount(carried.notStartedRebases);
+        if (integrated.kind === 'conflict') {
+            reportUnpushed(ahead, upstream, cycleId, deps);
+            return resultOf({ kind: 'conflict' }, integrated.conflict, carried);
+        }
+        if (integrated.kind === 'halted') {
+            // recordHalt already logged HALTED with the reason.
+            return outcome(integrated);
+        }
+        if (integrated.kind !== 'rebased') {
+            // Behind and not rebased, so nothing is pushed this cycle (D2).
+            reportUnpushed(ahead, upstream, cycleId, deps);
+            return outcome(integrated);
+        }
+        // A git command of the person's that read the index before the rebase
+        // and writes it afterwards puts the pre-pull entries back (Decision 98).
+        const pulledTo = await deps.git.headCommit();
+        if (pulledFrom !== null && pulledTo !== null && pulledTo !== pulledFrom) {
+            carried.commitMemory = withLastMove(carried.commitMemory ?? EMPTY_COMMIT_MEMORY, { from: pulledFrom, to: pulledTo });
+        }
+        ahead = (await deps.git.divergence(remoteSha)).ahead;
+    }
+    // --- Step 10: push when ahead ---
+    if (ahead > 0) {
+        // The branch's commit, read once and pushed by its sha: HEAD may be
+        // detached at a person's half-done replay by now, and the verified ref
+        // must name what the remote received (Decision 111).
+        const pushedSha = await deps.git.resolveCommit(branchRef);
+        if (pushedSha === null) {
+            // The branch step 2 resolved is gone; the next cycle reads it again.
+            reportUnpushed(ahead, upstream, cycleId, deps);
+            return outcome({ kind: 'paused', reason: 'BRANCH_CHANGED' });
+        }
+        const pushed = await deps.writer.push(upstream.remote, pushedSha, upstream.remoteRef);
+        if (pushed.kind !== 'pushed') {
+            deps.logger.log({
+                level: 'WARN',
+                code: pushed.kind === 'rejected' ? 'PUSH_REJECTED' : 'PUSH_FAILED',
+                message: pushed.detail,
+                cycleId,
+            });
+            reportUnpushed(ahead, upstream, cycleId, deps);
+            return outcome({ kind: 'push-failed' });
+        }
+        deps.logger.log({
+            level: 'INFO',
+            code: 'PUSHED',
+            message: ahead === 1 ? '1 commit' : `${ahead} commits`,
+            cycleId,
+        });
+        await deps.writer.updateRef(verifiedRef, pushedSha, remoteSha);
+    }
+    // --- Step 11: synced, or still waiting for what step 5 could not commit ---
+    return outcome(waiting === null ? { kind: 'synced' } : { kind: 'waiting', reason: waiting });
+}
+/** The result with what the cycle carries; every outcome but a conflict has no conflict key. */
+function resultOf(cycleOutcome, conflict, carried) {
+    return {
+        outcome: cycleOutcome,
+        conflict,
+        commitMemory: carried.commitMemory,
+        notStartedRebases: carried.notStartedRebases,
+    };
+}
+/** A count the input carried goes back to 0; an absent one stays absent, which means 0. */
+function resetCount(count) {
+    return count === undefined ? undefined : 0;
+}
+function shortSha(sha) {
+    return sha.slice(0, SHORT_SHA_LENGTH);
+}
+function firstLine(text) {
+    return (text.trim().split('\n')[0] ?? '').trim();
+}
+async function haltWith(code, message, cycleId, deps) {
+    await recordHalt({ code, message, cycleId }, deps);
+    return { kind: 'halted', code };
+}
+function reportUnpushed(ahead, upstream, cycleId, deps) {
+    if (ahead === 0) {
+        return;
+    }
+    deps.logger.log({
+        level: 'WARN',
+        code: 'UNPUSHED',
+        message: `${ahead === 1 ? '1 local commit' : `${ahead} local commits`} not on ${upstream.remote} ${upstream.remoteRef}`,
+        cycleId,
+    });
+}
+/**
+ * Remote not readable or gone: counted against the last known upstream, the
+ * tracking ref or else enmetu's verified ref, uncounted only when neither exists.
+ * The tracking ref comes first because a person's fetch keeps it the newer
+ * observation of the remote; the verified ref covers a tracking ref that
+ * `git fetch --prune` removed after the remote branch was deleted.
+ */
+async function reportUnpushedAgainstLastKnown(lastKnownSha, upstream, cycleId, deps) {
+    if (lastKnownSha === null) {
+        deps.logger.log({
+            level: 'WARN',
+            code: 'UNPUSHED',
+            message: `local commits may not be on ${upstream.remote} ${upstream.remoteRef} (count unknown: no upstream was ever fetched or verified)`,
+            cycleId,
+        });
+        return;
+    }
+    const { ahead } = await deps.git.divergence(lastKnownSha);
+    reportUnpushed(ahead, upstream, cycleId, deps);
+}

package/dist/sync/syncCycleRunner.d.ts

@@ -0,0 +1,24 @@
+import type { ILogger } from '../contracts/ILogger.js';
+import type { ISyncCycle } from '../contracts/ISyncCycle.js';
+import type { ISyncCycleRunner } from '../contracts/ISyncCycleRunner.js';
+import { type CycleOutcomeKind } from '../contracts/syncTypes.js';
+/**
+ * Service: the memory that spans cycles. Numbers cycles c1, c2, ...; passes
+ * the previous ConflictKey in and replaces it with the result's, and does the
+ * same for the commit memory and the count of refused rebases (design 12.7);
+ * logs WAITING, PAUSED, BUSY and OFFLINE when they begin or change and RESUMED
+ * when they end; turns a thrown error into CYCLE_FAILED and outcome 'failed'.
+ */
+export declare class SyncCycleRunner implements ISyncCycleRunner {
+    private readonly cycle;
+    private readonly logger;
+    private cycleCount;
+    private knownConflict;
+    private quiet;
+    /** null until a cycle carried a commit memory or a refusal count; absent means empty and 0 (design 12.7). */
+    private carried;
+    constructor(cycle: ISyncCycle, logger: ILogger);
+    run(): Promise<CycleOutcomeKind>;
+    private inputFor;
+    private reportQuietTransition;
+}

package/dist/sync/syncCycleRunner.js

@@ -0,0 +1,169 @@
+import { EMPTY_COMMIT_MEMORY, } from '../contracts/syncTypes.js';
+import { errorMessage } from '../core/errors/errorMessage.js';
+const WAITING_MESSAGES = {
+    PARTIAL_SELECTION_STAGED: 'waiting: a partial selection is staged; nothing is committed or pulled until you commit or unstage it, and after partialStagingWaitMs enmetu commits everything',
+    COMMIT_HOOK_REJECTED: 'waiting: a commit hook rejected the commit; enmetu tries again when the files change',
+};
+/**
+ * Service: the memory that spans cycles. Numbers cycles c1, c2, ...; passes
+ * the previous ConflictKey in and replaces it with the result's, and does the
+ * same for the commit memory and the count of refused rebases (design 12.7);
+ * logs WAITING, PAUSED, BUSY and OFFLINE when they begin or change and RESUMED
+ * when they end; turns a thrown error into CYCLE_FAILED and outcome 'failed'.
+ */
+export class SyncCycleRunner {
+    cycle;
+    logger;
+    cycleCount = 0;
+    knownConflict = null;
+    quiet = null;
+    /** null until a cycle carried a commit memory or a refusal count; absent means empty and 0 (design 12.7). */
+    carried = null;
+    constructor(cycle, logger) {
+        this.cycle = cycle;
+        this.logger = logger;
+    }
+    async run() {
+        this.cycleCount += 1;
+        const cycleId = `c${this.cycleCount}`;
+        try {
+            const result = await this.cycle.run(this.inputFor(cycleId));
+            // A busy cycle carries no key, so the next cycle re-runs the rebase
+            // that the lock interrupted (Decision 11).
+            this.knownConflict = result.conflict;
+            if (this.carried !== null ||
+                result.commitMemory !== undefined ||
+                result.notStartedRebases !== undefined) {
+                this.carried = {
+                    commitMemory: result.commitMemory ?? EMPTY_COMMIT_MEMORY,
+                    notStartedRebases: result.notStartedRebases ?? 0,
+                };
+            }
+            this.reportQuietTransition(result.outcome, cycleId);
+            return result.outcome.kind;
+        }
+        catch (error) {
+            // No result, so neither the conflict key, the commit memory, the
+            // refusal count nor the quiet state is replaced: a throw says nothing
+            // about whether any of them has ended.
+            this.logger.log({
+                level: 'ERROR',
+                code: 'CYCLE_FAILED',
+                message: describeError(error),
+                cycleId,
+            });
+            return 'failed';
+        }
+    }
+    inputFor(cycleId) {
+        if (this.carried === null) {
+            return { cycleId, knownConflict: this.knownConflict };
+        }
+        return {
+            cycleId,
+            knownConflict: this.knownConflict,
+            commitMemory: this.carried.commitMemory,
+            notStartedRebases: this.carried.notStartedRebases,
+        };
+    }
+    reportQuietTransition(outcome, cycleId) {
+        const previous = this.quiet;
+        const current = asQuiet(outcome);
+        if (current !== null) {
+            this.quiet = current;
+            if (previous === null || !sameQuiet(previous, current)) {
+                this.logger.log(quietEntry(current, cycleId));
+            }
+            return;
+        }
+        // A halt is reported by the controller and ends the run; calling it a
+        // resumption would contradict the HALTED line that precedes it.
+        if (outcome.kind === 'halted') {
+            return;
+        }
+        this.quiet = null;
+        if (previous !== null) {
+            this.logger.log({
+                level: 'INFO',
+                code: 'RESUMED',
+                message: `sync resumed after ${describeQuiet(previous)}`,
+                cycleId,
+            });
+        }
+    }
+}
+function asQuiet(outcome) {
+    switch (outcome.kind) {
+        case 'paused':
+        case 'busy':
+        case 'offline':
+        case 'waiting':
+            return outcome;
+        default:
+            return null;
+    }
+}
+function sameQuiet(left, right) {
+    if (left.kind === 'paused' && right.kind === 'paused') {
+        return left.reason === right.reason;
+    }
+    if (left.kind === 'waiting' && right.kind === 'waiting') {
+        return left.reason === right.reason;
+    }
+    return left.kind === right.kind;
+}
+function quietEntry(outcome, cycleId) {
+    switch (outcome.kind) {
+        case 'paused':
+            return {
+                level: 'WARN',
+                code: 'PAUSED',
+                message: `sync paused: ${outcome.reason}`,
+                cycleId,
+            };
+        case 'busy':
+            return {
+                level: 'WARN',
+                code: 'BUSY',
+                message: 'git is busy in this repository; retrying on the next cycle',
+                cycleId,
+            };
+        case 'offline':
+            return {
+                level: 'WARN',
+                code: 'OFFLINE',
+                message: 'remote unreachable; retrying on every poll',
+                cycleId,
+            };
+        case 'waiting':
+            return {
+                level: 'WARN',
+                code: 'WAITING',
+                message: WAITING_MESSAGES[outcome.reason],
+                cycleId,
+            };
+    }
+}
+function describeQuiet(outcome) {
+    switch (outcome.kind) {
+        case 'paused':
+            return `pause ${outcome.reason}`;
+        case 'busy':
+            return 'busy git';
+        case 'offline':
+            return 'offline';
+        case 'waiting':
+            return `waiting ${outcome.reason}`;
+    }
+}
+/** The message, prefixed with the structured code when the error carries one (EnmetuError, Node errno errors). */
+function describeError(error) {
+    const message = errorMessage(error);
+    if (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string') {
+        return `${error.code}: ${message}`;
+    }
+    return message;
+}

package/dist/sync/syncScheduler.d.ts

@@ -0,0 +1,32 @@
+import type { IClock } from '../contracts/IClock.js';
+import type { ISyncCycleRunner } from '../contracts/ISyncCycleRunner.js';
+import type { ISyncScheduler } from '../contracts/ISyncScheduler.js';
+import { type SchedulerTiming } from '../core/schedule/schedulerStep.js';
+type EndReason = 'stopped' | 'halted';
+/**
+ * Service, the imperative shell around schedulerStep: it holds the state,
+ * feeds events in, and executes the effects with IClock and the runner. It
+ * contains no timing rule of its own.
+ */
+export declare class SyncScheduler implements ISyncScheduler {
+    private readonly runner;
+    private readonly clock;
+    private readonly timing;
+    private state;
+    private quietTimer;
+    private pollTimer;
+    private running;
+    private endReason;
+    private resolveEnd;
+    constructor(runner: ISyncCycleRunner, clock: IClock, timing: SchedulerTiming);
+    run(): Promise<EndReason>;
+    notifyChange(): void;
+    stop(): void;
+    private dispatch;
+    private execute;
+    private startCycle;
+    private finishCycle;
+    /** A deadline already passed (a late timer callback) fires at once. */
+    private delayUntil;
+}
+export {};