@quantiya/codevibe-core 2.0.1 → 2.0.3

package/dist/local-executor/merge-conflict-extract.d.ts

@@ -0,0 +1,34 @@
+import type { ConflictHunk } from './conflict-types';
+/** A parsed segment of a conflicted file: verbatim context, or a conflict region. */
+export type ConflictSegment = {
+    kind: 'context';
+    lines: string[];
+} | {
+    kind: 'conflict';
+    hunkOrdinal: number;
+    oursLines: string[];
+    baseLines: string[];
+    theirsLines: string[];
+};
+/**
+ * Parse a diff3-style conflicted blob into ordered segments. Conflict regions
+ * get a deterministic 0-based `hunkOrdinal` (their order of appearance).
+ * Throws on a malformed marker structure (an unterminated/misordered conflict)
+ * so the caller FAILS CLOSED (route-to-human) rather than mis-resolve. Requires
+ * the diff3 base section (the pinned `merge.conflictStyle=diff3`); a 2-way
+ * conflict missing `|||||||` is treated as malformed (fail closed).
+ */
+export declare function parseDiff3Conflicts(blob: string): ConflictSegment[];
+/** Extract the conflict hunks (the resolvable units) from parsed segments. */
+export declare function hunksFromSegments(segments: ConflictSegment[]): ConflictHunk[];
+/**
+ * Recompose a clean file from the parsed segments + a map of resolved hunk
+ * lines keyed by `hunkOrdinal`. Context segments pass through verbatim; each
+ * conflict region is replaced by its resolved lines. Throws if a conflict hunk
+ * has no resolution (the caller must resolve EVERY hunk before composing — a
+ * missing one is a bug, fail closed). Returns the composed file bytes.
+ */
+export declare function composeResolvedFile(segments: ConflictSegment[], resolvedByOrdinal: ReadonlyMap<number, string[]>): Buffer;
+/** True if a blob still carries any conflict marker (a safety re-check after
+ * composition — a composed file must be marker-free or we FAIL CLOSED). */
+export declare function hasConflictMarkers(blob: string): boolean;

package/dist/local-executor/merge-conflict-resolve.d.ts

@@ -0,0 +1,101 @@
+import { type ConflictModelCaller } from './class2-resolver';
+import { type AgenticResolutionRecord, type ConflictResolutionRecord, type ConflictResolutionStore } from './conflict-resolution-store';
+import type { AgenticResolveOutcome } from './agentic-resolve';
+import type { AgentKind } from './types';
+import { type ResolutionSetIndex } from './resolution-set-index';
+import type { SharedContractDetectorOptions } from './shared-contract-detector';
+/** Per-task resolver wiring (the merge-train threads this when the model is set). */
+export interface ConflictResolverContext {
+    /** The durable ConflictResolution store (§4.5 audit/replay). */
+    store: ConflictResolutionStore;
+    /**
+     * The durable RESOLUTION-SET INDEX (Wave B §2.3) — maps a resolved slot's
+     * `resolution_set_hash` to its `{conflictIds, class-by-id, composed-file
+     * hashes}` so the promote gate can PROVE the final-tip Tier-2 trigger across a
+     * resume (LOCK #C14-W3-TIER2-AUTHORITY) instead of trusting the single-pass
+     * boolean. Written audit-before-ref alongside the `ConflictResolution` records.
+     */
+    resolutionSetIndex: ResolutionSetIndex;
+    /** The brokered class-2 model caller (§8 — CP-7 broker; fail-closed). Used only
+     * in the LEGACY (non-agentic) mode; ignored when `resolveAgentic` is wired. */
+    caller: ConflictModelCaller;
+    /**
+     * CP-14 WB2 — when wired, the slot's class-2 conflicts are resolved AGENTICALLY
+     * (whole-slot: the incoming track's implementor resolves read+write in a
+     * disposable repo, fd-safe selective-import), NOT per-hunk prompt→JSON. The LE
+     * builds this closure (it owns the implementor spawn + the scan + the workspace
+     * dir); `resolveSlotConflicts` passes the conflicted tree + the class-2 paths +
+     * the incoming track's identity. Returns the resolved bytes per path, or a
+     * fail-closed human-gate. Absent → legacy per-hunk `caller` path.
+     */
+    resolveAgentic?: (args: {
+        conflictedTree: string;
+        class2Paths: readonly string[];
+        implementorAgent: string;
+        implementorTaskId: string;
+    }) => Promise<AgenticResolveOutcome>;
+    /** Shared-contract detector tuning (always-gate globs + planner shared_contracts). */
+    detectorOpts?: SharedContractDetectorOptions;
+    /** Max class-2 prompt bytes; over-budget → human gate (§8). */
+    maxContextBytes: number;
+    /** Touched paths carrying Git-LFS (from the W2 pre-scan) → class-3. */
+    lfsPaths?: ReadonlySet<string>;
+    /** Touched paths carrying a dangerous `.gitattributes` driver → class-3. */
+    dangerousAttrPaths?: ReadonlySet<string>;
+}
+/** A path that could not be auto-resolved and must go to the human gate. */
+export interface HumanGatedConflict {
+    path: string;
+    trigger: string;
+    reason: string;
+}
+/** The outcome of resolving one slot's conflicts. */
+export type SlotResolveResult = {
+    status: 'resolved';
+    /** The clean resolved tree OID (no conflict markers). */
+    resolvedTree: string;
+    /** Hash of the sorted conflict_id set — the merge-commit `resolution_set` trailer. */
+    resolutionSetHash: string;
+    /** The recorded ConflictResolution set (already durable in the store). */
+    records: ConflictResolutionRecord[];
+    /**
+     * CP-14 WB2 — the per-slot agentic record (already durable via `putAgentic`),
+     * present iff this slot had ≥1 class-2 conflict resolved agentically. Binds
+     * the resolved tree OID + the instance identity for the promote-gate verify.
+     */
+    agenticRecord?: AgenticResolutionRecord;
+} | {
+    /** At least one path needs a human — the WHOLE slot escalates (no partial). */
+    status: 'human_gate';
+    gated: HumanGatedConflict[];
+};
+/**
+ * Resolve every conflicting path for one merge-train slot. See the module header
+ * for the per-path flow + the audit-before-ref invariant. Pure of ref/worktree
+ * mutation — it only READS (extract) + WRITES OBJECTS (resolved blobs/tree) +
+ * PERSISTS audit records; the caller commits + advances the ref afterward.
+ */
+export declare function resolveSlotConflicts(args: {
+    repoDir: string;
+    /** The current integration tip (ours / §4.5 counterpart) — `mergeTreeOffBranch` arg 1. */
+    oursCommit: string;
+    /** The merging track tip (theirs) — `mergeTreeOffBranch` arg 2. */
+    theirsCommit: string;
+    /** The conflicted tree OID from `mergeTreeOffBranch` (patched into the resolved tree). */
+    conflictedTree: string;
+    /** The conflicting paths (sorted, from `mergeTreeOffBranch`). */
+    conflictPaths: readonly string[];
+    repoId: string;
+    mergeImplId: string;
+    ctx: ConflictResolverContext;
+    /**
+     * CP-14 WB2 — the INCOMING track's implementor identity (it is re-dispatched as
+     * the agentic resolver). REQUIRED when `ctx.resolveAgentic` is wired; an agentic
+     * slot with these absent FAILS CLOSED to the human gate (the resolver can't be
+     * dispatched / a pre-B2 journal track lacks the identity).
+     */
+    incomingImplementorAgent?: AgentKind;
+    incomingImplementorTaskId?: string;
+    /** CP-14 WB2 — tags durable records PENDING for this resolve attempt (recovery case 3). */
+    attemptId?: string;
+}): Promise<SlotResolveResult>;

package/dist/local-executor/merge-journal-store.d.ts

@@ -0,0 +1,311 @@
+/** The current merge-journal schema version (append-only; bump on a breaking shape change). */
+export declare const MERGE_JOURNAL_VERSION: 1;
+/**
+ * The per-(track,repo) coordinate captured ONCE at train start — the worktree path
+ * + the persistent track branch the train consumes (§3.2 "worktree path + branch per
+ * (track,repo)"). `trackTip` is the resolved track-branch tip at order-resolution time;
+ * recovery uses it to replay the EXACT inputs the order was derived from.
+ */
+export interface MergeJournalTrack {
+    trackIndex: number;
+    repoId: string;
+    /** The persistent track branch name (`codevibe/track/<group>/<idx>`). */
+    trackBranch: string;
+    /** The track-branch tip the order was resolved against. */
+    trackTip: string;
+    /**
+     * CP-14 WB2 — the implementor agent + its per-spawn task id that authored this
+     * track. The agentic class-2 resolver re-dispatches the INCOMING track's
+     * implementor under this identity, and these are folded into the GENERATION
+     * IDENTITY ({@link tracksEqual}) so a re-gate / metadata-repair with a different
+     * agent or task is a NEW generation (the steps reset). Persisted as plain
+     * strings; absent on a pre-B2 record → a mismatch against any current id →
+     * re-merge (fail-safe), mirroring the `mergeImplId` FIX-1 migration.
+     */
+    implementorAgent?: string;
+    implementorTaskId?: string;
+    /** The implementor's worktree-shadow path, when one is recorded (informational). */
+    worktreePath?: string | null;
+}
+/**
+ * CP-14 WB2 (#C14-WB2-RESOLVE-WAL) — the `resolution_recorded` WAL marker for an
+ * AGENTIC class-2 slot. Written on the started step AFTER the §4.5 ConflictResolution
+ * records + the resolution-set index are durable, and BEFORE the merge commit — so a
+ * durable marker IMPLIES the load-bearing records exist (preserves audit-before-ref).
+ * Recovery reads it: a started slot WITH this marker = case 2 (re-authenticate the
+ * records against `resolvedTreeOid`, then commit THAT tree agent-free — never a
+ * non-deterministic re-dispatch); a started slot WITHOUT it = case 3 (pending records
+ * are non-authoritative → clear + fresh re-dispatch). Carries the agentic INSTANCE
+ * identity (`#C14-WB2-AGENTIC-IDENTITY`) so a different surrounding tree is a distinct
+ * instance, never a stale replay. Clean / class-1-only slots do NOT write this marker
+ * (they re-derive deterministically — §2.5).
+ */
+export interface MergeResolutionRecordedMarker {
+    /** The agentic resolution INSTANCE id = hash of `(conflict_id, conflictedTree OID, resolver agent/task, conflict-set)`. */
+    instanceId: string;
+    /** The full committed resolved tree OID this WAL authenticates (recovery commits exactly this). */
+    resolvedTreeOid: string;
+    /** The durable resolution-set hash (the §4.5 set this marker's records belong to). */
+    resolutionSetHash: string;
+    /** conflictMeta — the conflicted paths/ids covered (audit + recovery re-authentication scope). */
+    conflictIds?: string[];
+}
+/**
+ * A single merge-train STEP (one order slot). Written write-ahead: `merge_started`
+ * BEFORE the off-branch merge, then `merge_committed` after the integration ref
+ * CAS-advances, or `merge_aborted` on a deterministic conflict-halt.
+ */
+export interface MergeStepRecord {
+    /** The 0-based slot in the resolved merge-train order. */
+    orderSlot: number;
+    trackIndex: number;
+    repoId: string;
+    /** The integration tip the step merges ONTO (`ours`) — known before the merge. */
+    preTip: string;
+    /** The track branch tip the step merges IN (`theirs`) — known before the merge. */
+    trackTip: string;
+    /** The pinned merge-implementation id (§4.2) folded into the key. */
+    mergeImplId: string;
+    /**
+     * `sha256(pre_tip, track_tip, repoId, trackIndex, merge_impl_id)` (§3.2 r2-H1) —
+     * PRE-merge inputs ONLY. The merge commit is stamped with this in its
+     * `Codevibe-Merge-Key:` trailer, so recovery's `git log --grep` can find a landed
+     * merge whose `merge_committed` write was lost.
+     */
+    expectedMergeKey: string;
+    /**
+     * The merge commit SHA — written only on `merge_committed`. `null` while still
+     * `merge_started`. The committed integration tip after this slot.
+     */
+    mergeCommit: string | null;
+    state: 'merge_started' | 'merge_committed' | 'merge_aborted';
+    /** Why the step aborted (a deterministic conflict-halt) — set only on `merge_aborted`. */
+    abortReason?: string | null;
+    /** The conflicting paths surfaced on a conflict-halt — set only on `merge_aborted`. */
+    conflictPaths?: string[] | null;
+    /**
+     * CP-14 WB2 (#C14-WB2-RESOLVE-WAL) — the `resolution_recorded` WAL marker, set on a
+     * still-`merge_started` AGENTIC slot AFTER its §4.5 records are durable and BEFORE the
+     * commit. Its presence on a started step = recovery case 2 (commit the recorded tree
+     * agent-free); absent on a started step = case 3 (clear pending records + re-dispatch).
+     * `null`/absent for clean / class-1 slots (they re-derive deterministically).
+     */
+    resolutionRecorded?: MergeResolutionRecordedMarker | null;
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+/** The durable merge-journal record (§3.2). One per `(group, repo)`. */
+export interface MergeJournalRecord {
+    version: typeof MERGE_JOURNAL_VERSION;
+    taskGroupId: string;
+    repoId: string;
+    /** The per-repo base snapshot = user repo HEAD at dispatch. */
+    baseSha: string;
+    /** The per-repo integration branch the train advances (`codevibe/integration/<group>/<repo>`). */
+    integrationBranch: string;
+    /**
+     * Codex r6 FIX 1 (HIGH) — the GROUP-level pinned merge-implementation id this generation was
+     * produced under ({@link resolveMergeImplId} = `git-<version>+<DETERMINISM_CONTRACT_ID>`). It is
+     * folded into the GENERATION IDENTITY (see {@link MergeJournalStore.writeGroup}): a re-gate whose
+     * current `mergeImplId` DIFFERS from the stored one (host git upgraded, or the determinism
+     * contract bumped across a deploy) is a NEW generation → the steps reset → the train re-merges
+     * under the new impl, so a crash-recovery never ADOPTS an OLD-impl committed merge commit by its
+     * trailer. Stored on every generation write; `null`/absent on a pre-FIX-1 record (treated as a
+     * mismatch against any current id → re-merge, fail-safe). Each per-step {@link MergeStepRecord}
+     * ALSO carries its own `mergeImplId` — the step-level check (FIX 1 guard b) is the belt to this
+     * group-level suspenders.
+     */
+    mergeImplId?: string | null;
+    /** The per-(track,repo) coordinates the order was resolved over (§4.1). */
+    tracks: MergeJournalTrack[];
+    /**
+     * The RESOLVED, canonical merge-train order as a list of `trackIndex` in execution
+     * order (§4.1, r2-L + r3 Codex: "persists the canonical resolved order in the journal
+     * so recovery never re-derives a different order from a since-mutated input").
+     */
+    resolvedOrder: number[];
+    /**
+     * Stage-2 r2 H1 — the DURABLE re-anchor marker. When a CHANGED-input re-gate starts a
+     * fresh generation (`writeGroup` reset the steps), the LIVE integration ref still carries
+     * the PRIOR generation's advanced tip (e.g. merge(A)). The train must RE-ANCHOR that ref
+     * back to `base_sha` BEFORE slot 0, else slot 0 builds on the stale tip and stale bytes
+     * promote. The CAS reset is a SEPARATE step after the (durable) generation write, so a
+     * crash between them would lose the reset INTENT — on restart recovery would see no started
+     * steps (`nothing_to_do`) and the next same-order `writeGroup` (`stepsReset:false`) would
+     * build slot 0 on the STALE tip. This field makes the reset intent DURABLE: it is set to
+     * the `base_sha` to re-anchor to, ATOMICALLY with the steps-reset generation write (so it
+     * survives a crash), and CLEARED only after the CAS reset is confirmed. Recovery HONORS a
+     * set marker on restart — it completes the CAS reset to this SHA before proceeding. `null`
+     * (or absent on an old record) when there is no pending re-anchor.
+     */
+    reanchorPending?: string | null;
+    /** The per-slot write-ahead step records, indexed by `orderSlot`. */
+    steps: MergeStepRecord[];
+    createdAtMs: number;
+    updatedAtMs: number;
+}
+/** The group-level inputs the engine hands to {@link MergeJournalStore.writeGroup}. */
+export interface MergeGroupInput {
+    baseSha: string;
+    integrationBranch: string;
+    tracks: MergeJournalTrack[];
+    resolvedOrder: number[];
+    /**
+     * Codex r6 FIX 1 (HIGH) — the pinned merge-implementation id the train will run under
+     * ({@link resolveMergeImplId}). Folded into the generation identity: a re-gate whose `mergeImplId`
+     * differs from a prior record's is a NEW generation (the steps reset → re-merge under the new
+     * impl), so a crash-recovery never adopts an old-implementation committed merge. OPTIONAL on the
+     * input for backward-compat with callers/tests that do not pass it (then it is NOT part of the
+     * identity — same as before FIX 1); the live {@link runMergeTrain} always passes it.
+     */
+    mergeImplId?: string;
+}
+/**
+ * The result of {@link MergeJournalStore.writeGroup} — the durable record PLUS whether
+ * this call RESET the per-step entries (Stage-2 r1 H1). `stepsReset` is `true` when the
+ * group inputs DIFFERED from a prior record (a genuinely new generation — e.g. a track tip
+ * moved to a replacement), so the caller (`runMergeTrain`) knows to RE-ANCHOR the
+ * integration ref back to `base_sha` (the prior generation's advanced tip is stale and must
+ * NOT be carried into the new train). `false` on a first-ever write (no prior record) and on
+ * an idempotent same-order redelivery (the in-flight steps are kept).
+ */
+export interface MergeGroupWriteResult extends MergeJournalRecord {
+    stepsReset: boolean;
+}
+/** The per-step pre-merge inputs the engine hands to {@link MergeJournalStore.writeStarted}. */
+export interface MergeStepInput {
+    orderSlot: number;
+    trackIndex: number;
+    repoId: string;
+    preTip: string;
+    trackTip: string;
+    mergeImplId: string;
+}
+/**
+ * The pre-input-only merge key (§3.2 r2-H1). A `sha256` over the ordered PRE-MERGE
+ * inputs (we use sha256 — the codebase's hash primitive — in lieu of blake3; the
+ * design's "blake3" is the discipline, not a binding algorithm choice, and the
+ * #589/W1 stores hash with sha256 too). It depends ONLY on inputs known BEFORE the
+ * merge (not post-resolution hashes, which don't exist at WAL-write time and can't
+ * be recomputed after a crash). Identical inputs → identical key → a crash-redelivered
+ * merge step dedups + recovery can find the landed commit by its trailer.
+ */
+export declare function computeMergeKey(args: {
+    preTip: string;
+    trackTip: string;
+    repoId: string;
+    trackIndex: number;
+    mergeImplId: string;
+}): string;
+/**
+ * The pure durable merge-journal store. ONE instance per desktop; all paths derive
+ * from {@link rootDir} (overridable for deterministic tests). Mirrors the #589
+ * `RevertManifestStore` / W1 `PromoteWalStore` at-rest guards exactly.
+ */
+export declare class MergeJournalStore {
+    private readonly rootDir;
+    constructor(opts?: {
+        rootDir?: string;
+    });
+    /** The per-`(group, repo)` directory `<root>/<taskGroupId>/<repoId>/`. */
+    private repoDir;
+    /**
+     * Validate `seg` is a safe SINGLE path segment so a malicious id can't escape
+     * `<root>/` (defense-in-depth, mirrors #589-G / W1 `PromoteWalStore.safeSegment`).
+     */
+    private safeSegment;
+    private mkdirSecure;
+    /**
+     * Refuse to operate under a path whose any in-`rootDir` component is a symlink
+     * (LOCK #589-G "no symlink following"). lstat each component from `rootDir`
+     * down; a symlinked component throws. Missing components are fine.
+     */
+    private assertNoSymlinkComponents;
+    /** Atomic write: `<final>.tmp.<pid>.<rand>` (0600) → fsync → rename → fsync(dir). */
+    private atomicWrite;
+    private readJson;
+    /**
+     * Write (or idempotently re-establish) the GROUP-level merge-journal record at
+     * train start — `base_sha`, the integration branch, the per-(track,repo)
+     * coordinates, and the RESOLVED canonical order (§4.1). Written ONCE, BEFORE any
+     * step. Idempotent: a re-call for the SAME `(group, repo)` whose `resolvedOrder`
+     * + `baseSha` + `integrationBranch` match an existing record RETURNS it WITHOUT
+     * losing any already-written steps (a crash-redelivered train start dedups). A
+     * re-call whose group inputs DIFFER (a genuinely new order — e.g. a track tip
+     * moved, changing the resolution) overwrites the group fields + RESETS the steps
+     * (the old per-step entries keyed against the prior order are no longer valid) and
+     * returns `stepsReset: true` (Stage-2 r1 H1) so the train RE-ANCHORS the integration
+     * ref back to `base_sha` instead of carrying the prior generation's stale advanced tip.
+     */
+    writeGroup(taskGroupId: string, repoId: string, input: MergeGroupInput): Promise<MergeGroupWriteResult>;
+    /**
+     * Write a `merge_started` step record BEFORE the off-branch merge (§3.2). The
+     * `expected_merge_key` is computed from the PRE-merge inputs. Idempotent: a re-call
+     * for the SAME `(group, repo, orderSlot)` whose key matches an existing step
+     * RETURNS it WITHOUT re-writing (a crash-redelivered step dedups). A NON-matching
+     * key for the same slot — only possible if the inputs changed — OVERWRITES the
+     * slot's step (the prior key is stale). A `merge_committed`/`merge_aborted` step is
+     * IMMUTABLE here: it is returned unchanged (a started record's restart writes a
+     * fresh started step only over a started/absent slot).
+     */
+    writeStarted(taskGroupId: string, repoId: string, input: MergeStepInput): Promise<MergeStepRecord>;
+    /**
+     * RE-ARM a slot's step back to `merge_started` with a fresh PRE-merge key — used
+     * ONLY by crash-recovery's re-merge (§3.2 r4: "reset invalidates later slots"). Unlike
+     * {@link writeStarted} (which leaves a `merge_committed`/`merge_aborted` step IMMUTABLE,
+     * so the normal forward train never re-arms a terminal slot), recovery legitimately
+     * RE-MERGES a later slot whose commit was invalidated by an earlier-slot reset — so its
+     * journal step MUST honestly transition back to `merge_started` (NOT silently re-use a
+     * stale key). The fresh key is computed from the CURRENT pre-inputs (the rewound
+     * `preTip` + the track tip), so the re-armed step + its trailer reflect the actual
+     * re-merge, never a coincidentally-equal stale value. Throws if there is no group record.
+     */
+    reArmStarted(taskGroupId: string, repoId: string, input: MergeStepInput): Promise<MergeStepRecord>;
+    /**
+     * Stage-2 r2 H1 — CLEAR the durable re-anchor marker after the train (or recovery) has
+     * CONFIRMED the CAS reset of the integration ref to `base_sha`. Idempotent: a no-op when
+     * there is no record or the marker is already clear. NEVER called before the CAS reset is
+     * confirmed — so a crash between the reset and this clear simply re-honors the (still-set)
+     * marker on the next recovery, which re-does the now-idempotent CAS reset (the ref is
+     * already at `base_sha`) and clears it. Read the marker via {@link readRecord}'s
+     * `reanchorPending`.
+     */
+    clearReanchorPending(taskGroupId: string, repoId: string): Promise<void>;
+    /**
+     * Mark a started step COMMITTED, recording the landed merge commit (§3.2). No-op
+     * when there is no group record or no started step at the slot. Idempotent.
+     */
+    writeCommitted(taskGroupId: string, repoId: string, orderSlot: number, mergeCommit: string): Promise<void>;
+    /**
+     * CP-14 WB2 (#C14-WB2-RESOLVE-WAL) — write the `resolution_recorded` WAL marker on a
+     * still-`merge_started` AGENTIC slot, AFTER its §4.5 records + the resolution-set index
+     * are durable and BEFORE the merge commit. A durable marker therefore IMPLIES the
+     * load-bearing records exist (audit-before-ref). Idempotent: a re-call with the SAME
+     * marker returns without rewriting. NEVER sets the marker on a `merge_committed` /
+     * `merge_aborted` step (terminal) or when there is no step (no-op). Recovery reads
+     * `step.resolutionRecorded` to distinguish case 2 (present → commit the recorded tree
+     * agent-free) from case 3 (absent → clear pending records + re-dispatch).
+     */
+    writeResolutionRecorded(taskGroupId: string, repoId: string, orderSlot: number, marker: MergeResolutionRecordedMarker): Promise<void>;
+    /**
+     * Mark a started step TERMINALLY ABORTED — a deterministic conflict-halt at this
+     * slot. NOTHING was committed past slot k-1; the integration ref is where slot k-1
+     * left it (the train halted BEFORE this commit). `listStartedNotCommitted` EXCLUDES
+     * a `merge_aborted` step, so a completed conflict-halt is never mistaken for a
+     * crash. NEVER downgrades a `merge_committed` step (immutable-once-committed). No-op
+     * when there is no record/step. Idempotent.
+     */
+    markAborted(taskGroupId: string, repoId: string, orderSlot: number, abortReason: string, conflictPaths?: string[]): Promise<void>;
+    /**
+     * The started-but-not-committed STEPS for one `(group, repo)` — the recovery
+     * work-set (§3.2). A `merge_committed`/`merge_aborted` step is excluded. Returned
+     * in ascending `orderSlot` so recovery walks the train forward.
+     */
+    listStartedNotCommitted(taskGroupId: string, repoId: string): Promise<MergeStepRecord[]>;
+    /** Read the journal record for `(group, repo)`, or `null` if none. */
+    readRecord(taskGroupId: string, repoId: string): Promise<MergeJournalRecord | null>;
+    private upsertStep;
+    private writeRecord;
+    /** Delete the journal record for `(group, repo)` (terminal cleanup / GC). */
+    deleteRecord(taskGroupId: string, repoId: string): Promise<void>;
+}