loopforge 3.9.2 → 4.0.7

package/dist/recovery.js

@@ -0,0 +1,234 @@
+/** v3.9.7: checkpoint selection and committed rollback-directive facts.
+ *
+ * The Agent owns the decision to abandon a branch and the checkpoint it
+ * selects. This module only resolves a checkpoint reference against the
+ * current branch, validates the reference/manifest binding, and derives the
+ * rollback directive facts. It never chooses a target, never judges a reason,
+ * and never mutates the workspace. Restore execution lives in
+ * `workspace-restore.ts`.
+ */
+import { deriveFindingId } from "./token-utils.js";
+import { branchRounds, } from "./committed-round.js";
+function invalid(reason, detail) {
+    return { ok: false, code: "recovery_invalid", reason, detail };
+}
+function unavailable(reason, detail) {
+    return { ok: false, code: "recovery_unavailable", reason, detail };
+}
+function refsOfSnapshot(snapshot) {
+    if (!snapshot)
+        return [];
+    const refs = [];
+    if (snapshot.beforeCheckpoint)
+        refs.push(snapshot.beforeCheckpoint);
+    for (const ref of snapshot.checkpoints ?? [])
+        refs.push(ref);
+    return refs;
+}
+function sameTarget(refs) {
+    if (refs.length <= 1)
+        return true;
+    const first = refs[0];
+    return refs.every((ref) => ref.role === first.role &&
+        ref.round === first.round &&
+        ref.redoRound === first.redoRound &&
+        ref.contentHash === first.contentHash);
+}
+/** Resolve a checkpoint id against the held transaction and the current
+ *  branch's committed evaluation transactions. The held reference wins when
+ *  the same state also appears in committed history (retry re-binding).
+ *
+ *  This function is pure: it only uses committed read models and the held
+ *  snapshot. The caller loads and validates the manifest. */
+export function findCheckpointRef(input) {
+    const { checkpointId } = input;
+    if (!/^ck-[a-f0-9]{24}$/.test(checkpointId)) {
+        return invalid("invalid_checkpoint_id", "checkpoint id must be ck-<24 hex>");
+    }
+    const heldRefs = refsOfSnapshot(input.held).filter((ref) => ref.checkpointId === checkpointId);
+    const committedRefs = [];
+    for (const view of branchRounds(input.entries)) {
+        if (view.kind !== "evaluation")
+            continue;
+        for (const ref of [
+            ...(view.beforeCheckpoint ? [view.beforeCheckpoint] : []),
+            ...view.checkpoints,
+        ]) {
+            if (ref.checkpointId === checkpointId)
+                committedRefs.push(ref);
+        }
+    }
+    const all = [...heldRefs, ...committedRefs];
+    if (all.length === 0) {
+        return invalid("target_not_visible", `checkpoint ${checkpointId} is not referenced by the held transaction or a committed evaluation on the current branch`);
+    }
+    if (!sameTarget(all)) {
+        return invalid("ambiguous_checkpoint", `checkpoint ${checkpointId} resolves to conflicting role/round/contentHash references`);
+    }
+    return { ok: true, ref: heldRefs[0] ?? committedRefs[0] };
+}
+/** Validate the manifest against its reference. Content/blob/HEAD checks
+ *  belong to the restore preflight (they need the workspace and object store). */
+export function validateCheckpointManifest(ref, manifest) {
+    if (!manifest) {
+        return unavailable("manifest_missing", `manifest for ${ref.checkpointId} is missing or unreadable`);
+    }
+    if (manifest.checkpointId !== ref.checkpointId ||
+        manifest.contentHash !== ref.contentHash ||
+        manifest.role !== ref.role ||
+        manifest.round !== ref.round ||
+        manifest.loopId.length === 0) {
+        return unavailable("manifest_mismatch", `manifest for ${ref.checkpointId} does not match its transaction reference`);
+    }
+    const fingerprintPaths = new Set(Object.keys(manifest.fingerprints));
+    for (const path of manifest.contents) {
+        if (!fingerprintPaths.has(path)) {
+            return unavailable("manifest_mismatch", `manifest content path ${path} has no boundary fingerprint`);
+        }
+    }
+    return { ok: true, manifest };
+}
+/** The before-image that represents the state at the start of `redoRound`.
+ *  Used by machine backtrack: the state after round T is the before-image of
+ *  round T+1. Returns null when that image was never materialized. */
+export function checkpointForRoundBoundary(input) {
+    const { redoRound } = input;
+    if (input.heldRound === redoRound && input.heldBeforeCheckpoint) {
+        return input.heldBeforeCheckpoint;
+    }
+    const view = branchRounds(input.entries).find((round) => round.round === redoRound && round.kind === "evaluation");
+    return view?.beforeCheckpoint ?? null;
+}
+function observationFingerprints(observation) {
+    if (!observation || observation.kind !== "git" || observation.status !== "observed") {
+        return null;
+    }
+    const data = observation.data;
+    return data && typeof data === "object" && data.fingerprints &&
+        typeof data.fingerprints === "object"
+        ? data.fingerprints
+        : null;
+}
+function firstObservedGit(observations) {
+    return observations.find((observation) => observation.kind === "git" && observation.status === "observed");
+}
+function arrayStrings(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+/** Union-key comparison against the target snapshot. Paths whose content or
+ *  type differs — including additions and deletions — are the abandoned work
+ *  seen since the checkpoint. A file changed and changed back is not a net
+ *  difference, matching the round-delta semantics. */
+function addBoundaryDiff(target, observation, into) {
+    const fingerprints = observationFingerprints(observation);
+    if (!fingerprints)
+        return;
+    const keys = new Set([...Object.keys(target), ...Object.keys(fingerprints)]);
+    for (const key of keys) {
+        if (target[key] !== fingerprints[key])
+            into.add(key);
+    }
+}
+/** Derive the committed directive. Pure: the caller has validated the target
+ *  and collected the abandoned/current evidence. `skipped_files` is report
+ *  data (never a restore gate); discoveries are preserved only from committed
+ *  abandoned rounds, never from a rejected/in-flight trigger attempt. */
+export function deriveRecoveryDirective(input) {
+    const observedSkippedFiles = new Set();
+    const reportedSkippedFiles = new Set();
+    const skippedDiscoveries = [];
+    const machineFailedRounds = [];
+    const approaches = [];
+    const wrongAssumptions = [];
+    const addDiscovery = (text) => {
+        if (text && !skippedDiscoveries.includes(text))
+            skippedDiscoveries.push(text);
+    };
+    const addAssumption = (text) => {
+        if (text && !wrongAssumptions.includes(text)) {
+            wrongAssumptions.push(text.slice(0, 500));
+        }
+    };
+    for (const view of input.abandonedRounds) {
+        addBoundaryDiff(input.targetManifest.fingerprints, firstObservedGit(view.afterEvidence), observedSkippedFiles);
+        for (const file of arrayStrings(view.executionReport?.files_changed)) {
+            reportedSkippedFiles.add(file);
+        }
+        // v4.0.3: only a MACHINE-detected failure is a failed round. An agent's
+        // output_summary is a report, even when the agent chose to abandon.
+        if (input.origin === "machine" &&
+            view.verificationFlags.some((flag) => flag.severity === "error")) {
+            machineFailedRounds.push(view.round);
+        }
+        if (view.outputSummary?.trim()) {
+            approaches.push(view.outputSummary.trim().slice(0, 200));
+        }
+        for (const assumption of arrayStrings(view.evaluation?.wrong_assumptions)) {
+            addAssumption(assumption);
+        }
+        for (const discovery of arrayStrings(view.evaluation?.discovered_constraints)) {
+            addDiscovery(discovery);
+        }
+    }
+    // The current in-flight transaction is not committed history: it can
+    // contribute its machine net-diff and its trigger assumptions, but never a
+    // discovery that would become an active constraint.
+    addBoundaryDiff(input.targetManifest.fingerprints, firstObservedGit(input.currentAfterEvidence), observedSkippedFiles);
+    if (input.triggerEvaluation) {
+        for (const assumption of arrayStrings(input.triggerEvaluation.wrong_assumptions)) {
+            addAssumption(assumption);
+        }
+        const summary = input.triggerEvaluation.output_summary?.trim() ?? "";
+        if (summary && input.triggerRound !== undefined) {
+            const approach = summary.slice(0, 200);
+            if (!approaches.includes(approach))
+                approaches.push(approach);
+            if (input.origin === "machine" &&
+                !machineFailedRounds.includes(input.triggerRound)) {
+                machineFailedRounds.push(input.triggerRound);
+            }
+        }
+    }
+    const findings = [];
+    const seenFindings = new Set();
+    for (const flag of input.triggerFindings ?? []) {
+        const id = deriveFindingId(flag);
+        if (seenFindings.has(id))
+            continue;
+        seenFindings.add(id);
+        findings.push({ ...flag, detail: flag.detail.slice(0, 500) });
+        if (findings.length >= 12)
+            break;
+    }
+    const target = {
+        checkpoint_id: input.targetRef.checkpointId,
+        content_hash: input.targetRef.contentHash,
+        role: input.targetRef.role,
+        round: input.targetRef.round,
+        round_id: input.targetRef.roundId,
+        transaction_id: input.targetRef.transactionId,
+        redo_round: input.targetRef.redoRound,
+    };
+    const observed = [...observedSkippedFiles].sort();
+    const reported = [...reportedSkippedFiles].sort();
+    const skipped = [...new Set([...observed, ...reported])].sort();
+    return {
+        origin: input.origin,
+        reason: input.reason.slice(0, 500),
+        ...(input.triggerRule ? { trigger_rule: input.triggerRule } : {}),
+        target,
+        skipped_files: skipped,
+        observed_skipped_files: observed,
+        reported_skipped_files: reported,
+        abandoned_rounds: input.abandonedRounds.map((view) => view.round),
+        skipped_discoveries: skippedDiscoveries,
+        failed_rounds: machineFailedRounds,
+        approaches,
+        wrong_assumptions: wrongAssumptions,
+        ...(findings.length > 0 ? { trigger_findings: findings } : {}),
+        transaction_id: input.transactionId,
+    };
+}
+//# sourceMappingURL=recovery.js.map

package/dist/recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recovery.js","sourceRoot":"","sources":["../src/recovery.ts"],"names":[],"mappings":"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"}

package/dist/replay.d.ts

@@ -1,21 +1,55 @@
-/** ReplayBackend — time-travel queries over loop lineage.
+/** ReplayBackend — time-travel queries over committed rounds.
  *
  * Depends on LoopStore interface — no direct filesystem access.
- * Enables audit, comparison, and timeline analysis of loop rounds.
+ * Every query loads the same committed history once and reads the branch's
+ * `CommittedRoundView`s; there is no second decode pass and no synthesized
+ * lineage-shaped entry.
  */
-import type { LoopStore, VaultEntry } from "./loop-store.js";
-import type { LegacyRound } from "./committed-round.js";
+import type { LoopStore } from "./loop-store.js";
+import type { CommittedRoundView, LegacyRound } from "./committed-round.js";
+export declare const REPLAY_DEFAULT_ROUNDS = 10;
+export declare const REPLAY_MAX_WINDOW_ROUNDS = 50;
+/** Invalid explicit replay window. The MCP boundary maps this to
+ *  `invalid_argument`. */
+export declare class ReplayWindowError extends Error {
+    readonly code = "invalid_argument";
+    constructor(message: string);
+}
+export interface ReplayWindowOptions {
+    start?: number;
+    end?: number;
+}
+export interface ReplayWindow {
+    /** First round POSITION returned (legacy rows included); 0 when empty. */
+    start: number;
+    /** Last round POSITION returned (legacy rows included); 0 when empty. */
+    end: number;
+    /** Distinct committed round positions on the branch, INCLUDING legacy
+     *  envelopes that are not parseable history. The loss stays counted. */
+    totalRounds: number;
+    /** Round positions exist before this window. */
+    hasBefore: boolean;
+    /** Round positions exist after this window. */
+    hasAfter: boolean;
+}
+export interface ReplayPage {
+    timeline: Record<string, unknown>[];
+    window: ReplayWindow;
+}
 export declare class ReplayBackend {
     private readonly store;
     constructor(store: LoopStore);
-    getRound(loopId: string, roundNum: number): VaultEntry | null;
+    getRound(loopId: string, roundNum: number): CommittedRoundView | null;
     replay(loopId: string, opts?: {
         start?: number;
         end?: number;
-    }): VaultEntry[];
-    timeline(loopId: string): Record<string, unknown>[];
+    }): CommittedRoundView[];
+    /** v4.0.2: the paged timeline. The returned `window` tells the Agent
+     *  whether more committed rounds exist before/after this page. */
+    page(loopId: string, opts?: ReplayWindowOptions): ReplayPage;
+    /** Backwards-compatible array view. Defaults to the same bounded page. */
+    timeline(loopId: string, opts?: ReplayWindowOptions): Record<string, unknown>[];
     /** v3.9.1: explicit legacy-envelope report for the tool envelope. */
     legacyRounds(loopId: string): LegacyRound[];
-    private maxRound;
 }
 //# sourceMappingURL=replay.d.ts.map

package/dist/replay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAO7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAMxD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAEtB,KAAK,EAAE,SAAS;IAM5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IA+B7D,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GACtC,UAAU,EAAE;IAkBf,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IA0DnD,qEAAqE;IACrE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE;IAS3C,OAAO,CAAC,QAAQ;CAMjB"}
+{"version":3,"file":"replay.d.ts","sourceRoot":"","sources":["../src/replay.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAO5E,eAAO,MAAM,qBAAqB,KAAK,CAAC;AACxC,eAAO,MAAM,wBAAwB,KAAK,CAAC;AAY3C;0BAC0B;AAC1B,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,IAAI,sBAAsB;gBACvB,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,KAAK,EAAE,MAAM,CAAC;IACd,yEAAyE;IACzE,GAAG,EAAE,MAAM,CAAC;IACZ;4EACwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;IACnB,+CAA+C;IAC/C,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACpC,MAAM,EAAE,YAAY,CAAC;CACtB;AAsGD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAY;gBAEtB,KAAK,EAAE,SAAS;IAM5B,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,kBAAkB,GAAG,IAAI;IASrE,MAAM,CACJ,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GACtC,kBAAkB,EAAE;IAUvB;sEACkE;IAClE,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,UAAU;IA0N5D,0EAA0E;IAC1E,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE;IAI/E,qEAAqE;IACrE,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,EAAE;CAG5C"}