harnery 0.45.0 → 0.45.2

package/dist/core/context/index.js

@@ -6,16 +6,15 @@
  */
 import { spawnSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import { dirname, isAbsolute, join } from "node:path";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.js";
 import { resolveBinName } from "../config.js";
 import { peerInbox } from "../inbox/peer-messages.js";
 import { project } from "../inbox/service.js";
 import { stateFileMode } from "../storage/modes.js";
-import { acquireNoClobberLease } from "../workflow/workspaces/leases.js";
-import { observationsComparable } from "./observation.js";
-export { observationsComparable } from "./observation.js";
+import { repoComparisonProblems } from "./observation.js";
+export { repoComparisonProblems } from "./observation.js";
 export const CONTEXT_SCHEMA_VERSION = 1;
 export const MAX_CAPSULE_BYTES = 32 * 1024;
 const MAX_SNAPSHOT_PATHS = 15;
@@ -70,26 +69,24 @@ export function extractContextSample(payload, options) {
 }
 /** Persist a latest context sample. Identical measurements are a no-op. */
 export function recordContextSample(coordRoot, instanceId, sample) {
-    return withContextMutation(coordRoot, sample.session_id, () => {
-        const current = readContextState(coordRoot, sample.session_id);
-        const state = current?.instance_id === instanceId
-            ? current
-            : {
-                ...newState({ sessionId: sample.session_id, instanceId, now: sample.observed_at }),
-                generation: current?.generation ?? 0,
-            };
-        const changed = !sameMeasurement(state.latest_context, sample);
-        if (!changed)
-            return { state, changed: false };
-        const next = {
-            ...state,
-            instance_id: instanceId,
-            latest_context: sample,
-            updated_at: sample.observed_at,
+    const current = readContextState(coordRoot, sample.session_id);
+    const state = current?.instance_id === instanceId
+        ? current
+        : {
+            ...newState({ sessionId: sample.session_id, instanceId, now: sample.observed_at }),
+            generation: current?.generation ?? 0,
         };
-        writeState(coordRoot, next);
-        return { state: next, changed: true };
-    });
+    const changed = !sameMeasurement(state.latest_context, sample);
+    if (!changed)
+        return { state, changed: false };
+    const next = {
+        ...state,
+        instance_id: instanceId,
+        latest_context: sample,
+        updated_at: sample.observed_at,
+    };
+    writeState(coordRoot, next);
+    return { state: next, changed: true };
 }
 /**
  * Snapshot external work state. Repeated PreCompact events reuse the existing
@@ -97,105 +94,100 @@ export function recordContextSample(coordRoot, instanceId, sample) {
  * create a new generation.
  */
 export function checkpointContext(coordRoot, input) {
-    return withContextMutation(coordRoot, input.sessionId, () => {
-        const now = new Date().toISOString();
-        const previous = readContextState(coordRoot, input.sessionId);
-        const current = previous?.instance_id === input.instanceId
-            ? previous
-            : {
-                ...newState({ sessionId: input.sessionId, instanceId: input.instanceId, now }),
-                generation: previous?.generation ?? 0,
+    const now = new Date().toISOString();
+    const previous = readContextState(coordRoot, input.sessionId);
+    const current = previous?.instance_id === input.instanceId
+        ? previous
+        : {
+            ...newState({ sessionId: input.sessionId, instanceId: input.instanceId, now }),
+            generation: previous?.generation ?? 0,
+        };
+    if (input.reason === "pre_compact" && current.phase === "checkpointed") {
+        const existing = readLatestCapsule(coordRoot, input.sessionId);
+        if (existing && capsuleMatchesState(current, existing, input) && current.latest_capsule) {
+            return {
+                capsule: existing,
+                path: join(coordRoot, ".harnery", current.latest_capsule),
+                state: current,
+                reused: true,
             };
-        if (input.reason === "pre_compact" && current.phase === "checkpointed") {
-            const existing = readLatestCapsule(coordRoot, input.sessionId);
-            if (existing && capsuleMatchesState(current, existing, input) && current.latest_capsule) {
-                return {
-                    capsule: existing,
-                    path: join(coordRoot, ".harnery", current.latest_capsule),
-                    state: current,
-                    reused: true,
-                };
-            }
         }
-        const heartbeat = readHeartbeat(coordRoot, input.instanceId);
-        const generation = current.generation + 1;
-        const capsule = {
-            schema_version: CONTEXT_SCHEMA_VERSION,
-            capsule_id: randomUUID(),
-            generation,
-            created_at: now,
-            reason: input.reason,
-            session: {
-                session_id: input.sessionId,
-                instance_id: input.instanceId,
-                adapter: input.adapter,
-                model: input.model ?? current.latest_context?.model ?? heartbeat?.model,
-            },
-            context: current.latest_context,
-            work: buildWorkSnapshot(heartbeat, input.continuationNote),
-            repo: snapshotRepo(input.cwd),
-        };
-        const relativePath = capsuleRelativePath(input.sessionId, generation);
-        const absolutePath = join(coordRoot, ".harnery", relativePath);
-        writeBoundedJson(absolutePath, capsule, MAX_CAPSULE_BYTES);
-        const next = {
-            ...current,
+    }
+    const heartbeat = readHeartbeat(coordRoot, input.instanceId);
+    const generation = current.generation + 1;
+    const capsule = {
+        schema_version: CONTEXT_SCHEMA_VERSION,
+        capsule_id: randomUUID(),
+        generation,
+        created_at: now,
+        reason: input.reason,
+        session: {
+            session_id: input.sessionId,
             instance_id: input.instanceId,
-            phase: "checkpointed",
-            generation,
-            latest_capsule: relativePath,
-            updated_at: now,
-            recovered_at: undefined,
-            compaction_completed_at: undefined,
-            degraded_reason: undefined,
-        };
-        writeState(coordRoot, next);
-        return { capsule, path: absolutePath, state: next, reused: false };
-    });
+            adapter: input.adapter,
+            model: input.model ?? current.latest_context?.model ?? heartbeat?.model,
+        },
+        context: current.latest_context,
+        work: buildWorkSnapshot(heartbeat, input.continuationNote),
+        repo: snapshotRepo(input.cwd),
+    };
+    const relativePath = capsuleRelativePath(input.sessionId, generation);
+    const absolutePath = join(coordRoot, ".harnery", relativePath);
+    writeBoundedJson(absolutePath, capsule, MAX_CAPSULE_BYTES);
+    const next = {
+        ...current,
+        instance_id: input.instanceId,
+        phase: "checkpointed",
+        generation,
+        latest_capsule: relativePath,
+        updated_at: now,
+        recovered_at: undefined,
+        compaction_completed_at: undefined,
+        degraded_reason: undefined,
+    };
+    writeState(coordRoot, next);
+    return { capsule, path: absolutePath, state: next, reused: false };
 }
 /** Prepare a briefing without claiming that a adapter has accepted it yet. */
 export function prepareContextRecovery(coordRoot, input) {
-    return withContextMutation(coordRoot, input.sessionId, () => {
-        const now = new Date().toISOString();
-        const current = readContextState(coordRoot, input.sessionId) ??
-            newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
-        // A reused provider ID does not transfer the prior task's context.
-        if (current.instance_id !== input.instanceId)
-            return null;
-        const capsule = readLatestCapsule(coordRoot, input.sessionId);
-        if (!capsule || !capsuleMatchesState(current, capsule, input)) {
-            const degraded = {
-                ...current,
-                instance_id: input.instanceId,
-                phase: "degraded",
-                updated_at: now,
-                degraded_reason: capsule
-                    ? "continuity checkpoint does not match the requesting instance and state"
-                    : "post-compaction signal arrived without a continuity checkpoint",
-            };
-            writeState(coordRoot, degraded);
-            return null;
-        }
-        const liveRepo = snapshotRepo(input.cwd);
-        const briefing = [
-            renderRecoveryBriefing(capsule, liveRepo),
-            renderRecoveryInput(coordRoot, input.instanceId),
-        ]
-            .filter(Boolean)
-            .join("\n\n");
-        return {
-            state: current,
-            capsule,
-            briefing,
-            checkpoint: Object.freeze({
-                session_id: input.sessionId,
-                instance_id: input.instanceId,
-                generation: capsule.generation,
-                capsule_id: capsule.capsule_id,
-                capsule_sha256: capsuleDigest(capsule),
-            }),
+    const now = new Date().toISOString();
+    const current = readContextState(coordRoot, input.sessionId) ??
+        newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
+    // A reused provider ID does not transfer the prior task's context.
+    if (current.instance_id !== input.instanceId)
+        return null;
+    const capsule = readLatestCapsule(coordRoot, input.sessionId);
+    if (!capsule || !capsuleMatchesState(current, capsule, input)) {
+        const degraded = {
+            ...current,
+            instance_id: input.instanceId,
+            phase: "degraded",
+            updated_at: now,
+            degraded_reason: capsule
+                ? "continuity checkpoint does not match the requesting instance and state"
+                : "post-compaction signal arrived without a continuity checkpoint",
         };
-    });
+        writeState(coordRoot, degraded);
+        return null;
+    }
+    const liveRepo = snapshotRepo(input.cwd);
+    const briefing = [
+        renderRecoveryBriefing(capsule, liveRepo),
+        renderRecoveryInput(coordRoot, input.instanceId),
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+    return {
+        state: current,
+        capsule,
+        briefing,
+        checkpoint: Object.freeze({
+            session_id: input.sessionId,
+            instance_id: input.instanceId,
+            generation: capsule.generation,
+            capsule_id: capsule.capsule_id,
+        }),
+    };
 }
 /** Recovery lists input without surfacing it again or changing its receipts. */
 function renderRecoveryInput(coordRoot, instanceId) {
@@ -244,66 +236,61 @@ function inputLine(messageId, status, body) {
 }
 /**
  * Advance continuity only after the adapter accepted the prepared briefing.
- * Missing, altered, foreign or superseded checkpoints refuse without writing.
- * Repeating the same accepted checkpoint is an exact no-op.
+ * A foreign or superseded checkpoint refuses without writing, and repeating
+ * the same accepted checkpoint is an exact no-op. The write is a
+ * compare-and-write: if the state changed after it was read, for example
+ * because a newer checkpoint landed, completion refuses instead of
+ * overwriting it.
  */
 export function completeContextRecovery(coordRoot, input) {
-    return withContextMutation(coordRoot, input.sessionId, () => {
-        const current = readContextState(coordRoot, input.sessionId);
-        const checkpoint = input.checkpoint;
-        if (!current ||
-            !checkpoint ||
-            checkpoint.session_id !== input.sessionId ||
-            checkpoint.instance_id !== input.instanceId ||
-            !Number.isSafeInteger(checkpoint.generation) ||
-            checkpoint.generation < 1 ||
-            typeof checkpoint.capsule_id !== "string" ||
-            !checkpoint.capsule_id ||
-            !/^[a-f0-9]{64}$/.test(checkpoint.capsule_sha256) ||
-            (current.phase !== "checkpointed" && current.phase !== "recovered"))
-            return null;
-        const capsule = readLatestCapsule(coordRoot, input.sessionId);
-        if (!capsule ||
-            !capsuleMatchesState(current, capsule, input) ||
-            checkpoint.generation !== capsule.generation ||
-            checkpoint.capsule_id !== capsule.capsule_id ||
-            checkpoint.capsule_sha256 !== capsuleDigest(capsule))
-            return null;
-        if (current.phase === "recovered")
-            return current;
-        const now = new Date().toISOString();
-        const recovered = {
-            ...current,
-            phase: "recovered",
-            updated_at: now,
-            recovered_at: now,
-            degraded_reason: undefined,
-        };
-        writeState(coordRoot, recovered);
-        return recovered;
-    });
+    const path = statePath(coordRoot, input.sessionId);
+    const observed = readText(path);
+    if (observed === null)
+        return null;
+    const current = parseJson(observed);
+    const { checkpoint } = input;
+    if (!current ||
+        checkpoint.session_id !== input.sessionId ||
+        checkpoint.instance_id !== input.instanceId ||
+        checkpoint.generation !== current.generation ||
+        (current.phase !== "checkpointed" && current.phase !== "recovered"))
+        return null;
+    const capsule = readLatestCapsule(coordRoot, input.sessionId);
+    if (!capsule ||
+        !capsuleMatchesState(current, capsule, input) ||
+        capsule.capsule_id !== checkpoint.capsule_id)
+        return null;
+    if (current.phase === "recovered")
+        return current;
+    const now = new Date().toISOString();
+    const recovered = {
+        ...current,
+        phase: "recovered",
+        updated_at: now,
+        recovered_at: now,
+        degraded_reason: undefined,
+    };
+    return writeBoundedJson(path, recovered, MAX_CAPSULE_BYTES, observed) ? recovered : null;
 }
 /** Record that the adapter, rather than Harnery, reported compaction complete. */
 export function markContextCompactionCompleted(coordRoot, input) {
-    return withContextMutation(coordRoot, input.sessionId, () => {
-        const now = input.observedAt ?? new Date().toISOString();
-        const current = readContextState(coordRoot, input.sessionId) ??
-            newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
-        if (current.instance_id !== input.instanceId)
-            return current;
-        const next = {
-            ...current,
-            instance_id: input.instanceId,
-            phase: current.latest_capsule ? current.phase : "degraded",
-            compaction_completed_at: now,
-            updated_at: now,
-            degraded_reason: current.latest_capsule
-                ? current.degraded_reason
-                : "post-compaction signal arrived without a continuity checkpoint",
-        };
-        writeState(coordRoot, next);
-        return next;
-    });
+    const now = input.observedAt ?? new Date().toISOString();
+    const current = readContextState(coordRoot, input.sessionId) ??
+        newState({ sessionId: input.sessionId, instanceId: input.instanceId, now });
+    if (current.instance_id !== input.instanceId)
+        return current;
+    const next = {
+        ...current,
+        instance_id: input.instanceId,
+        phase: current.latest_capsule ? current.phase : "degraded",
+        compaction_completed_at: now,
+        updated_at: now,
+        degraded_reason: current.latest_capsule
+            ? current.degraded_reason
+            : "post-compaction signal arrived without a continuity checkpoint",
+    };
+    writeState(coordRoot, next);
+    return next;
 }
 /** Convenience API for callers whose injection is synchronous and guaranteed. */
 export function recoverContext(coordRoot, input) {
@@ -337,25 +324,9 @@ export function readContextState(coordRoot, sessionId) {
 }
 export function readLatestCapsule(coordRoot, sessionId) {
     const state = readContextState(coordRoot, sessionId);
-    if (typeof state?.latest_capsule !== "string" || !state.latest_capsule)
-        return null;
-    const capsule = readJson(join(coordRoot, ".harnery", state.latest_capsule));
-    if (!capsule ||
-        !record(capsule.repo) ||
-        !record(capsule.work) ||
-        typeof capsule.repo.cwd !== "string" ||
-        !Array.isArray(capsule.repo.dirty_paths) ||
-        !capsule.repo.dirty_paths.every((path) => typeof path === "string") ||
-        !Array.isArray(capsule.work.files_held) ||
-        !capsule.work.files_held.every((path) => typeof path === "string")) {
+    if (!state?.latest_capsule)
         return null;
-    }
-    capsule.repo.observation = repoObservation(capsule.repo.observation);
-    capsule.repo.observation_detail = clampString(string(capsule.repo.observation_detail), MAX_OBSERVATION_DETAIL_CHARS);
-    capsule.repo.branch = string(capsule.repo.branch)?.trim() || undefined;
-    capsule.repo.head = string(capsule.repo.head)?.trim() || undefined;
-    capsule.repo.root = string(capsule.repo.root)?.trim() || undefined;
-    return capsule;
+    return readJson(join(coordRoot, ".harnery", state.latest_capsule));
 }
 export function renderRecoveryBriefing(capsule, liveRepo) {
     const lines = [
@@ -369,44 +340,20 @@ export function renderRecoveryBriefing(capsule, liveRepo) {
     if (capsule.work.files_held.length > 0) {
         lines.push(`Files held: ${capsule.work.files_held.join(", ")}`);
     }
-    const unknown = [];
-    if (!observationsComparable(capsule.repo, liveRepo)) {
-        for (const [label, repo] of [
-            ["checkpoint", capsule.repo],
-            ["current repository", liveRepo],
-        ]) {
-            if (repo.observation !== "ok") {
-                const detail = clampString(string(repo.observation_detail), MAX_OBSERVATION_DETAIL_CHARS);
-                unknown.push(`${label}: ${repoObservation(repo.observation)}${detail ? ` (${detail})` : ""}`);
-            }
-        }
-    }
-    if (capsule.repo.dirty_paths_truncated || liveRepo.dirty_paths_truncated) {
-        unknown.push("dirty path list is truncated");
-    }
-    if (!capsule.repo.root ||
-        !liveRepo.root ||
-        !isAbsolute(capsule.repo.root) ||
-        !isAbsolute(liveRepo.root)) {
-        unknown.push("repository root is unknown");
-    }
-    else if (capsule.repo.root !== liveRepo.root) {
-        unknown.push("repository root differs from the checkpoint");
-    }
-    if (!capsule.repo.branch?.trim() || !liveRepo.branch?.trim())
-        unknown.push("branch is unknown");
-    if (!capsule.repo.head?.trim() || !liveRepo.head?.trim())
-        unknown.push("HEAD is unknown");
+    const unknown = repoComparisonProblems(capsule.repo, liveRepo, [
+        "checkpoint",
+        "current repository",
+    ]);
     if (unknown.length > 0) {
         lines.push(`Repository could not be verified against the checkpoint: ${unknown.join("; ")}. Re-check before editing.`);
         return lines.join("\n");
     }
     const drift = [];
-    if (capsule.repo.branch && liveRepo.branch && capsule.repo.branch !== liveRepo.branch) {
+    if (capsule.repo.branch !== liveRepo.branch) {
         drift.push(`branch changed ${capsule.repo.branch} -> ${liveRepo.branch}`);
     }
-    if (capsule.repo.head && liveRepo.head && capsule.repo.head !== liveRepo.head) {
-        drift.push(`HEAD changed ${capsule.repo.head.slice(0, 8)} -> ${liveRepo.head.slice(0, 8)}`);
+    if (capsule.repo.head !== liveRepo.head) {
+        drift.push(`HEAD changed ${capsule.repo.head?.slice(0, 8)} -> ${liveRepo.head?.slice(0, 8)}`);
     }
     const beforeDirty = new Set(capsule.repo.dirty_paths);
     const afterDirty = new Set(liveRepo.dirty_paths);
@@ -510,39 +457,13 @@ function newState(input) {
         updated_at: input.now,
     };
 }
+/** The capsule is the one the state names, written for the requesting task. */
 function capsuleMatchesState(state, capsule, input) {
-    return (state.session_id === input.sessionId &&
-        state.instance_id === input.instanceId &&
-        capsule.session?.session_id === input.sessionId &&
-        capsule.session?.instance_id === input.instanceId &&
-        capsule.schema_version === CONTEXT_SCHEMA_VERSION &&
-        Number.isSafeInteger(capsule.generation) &&
-        capsule.generation > 0 &&
+    return (state.instance_id === input.instanceId &&
+        capsule.session.instance_id === input.instanceId &&
         capsule.generation === state.generation &&
-        typeof capsule.capsule_id === "string" &&
-        capsule.capsule_id.length > 0 &&
         state.latest_capsule === capsuleRelativePath(input.sessionId, capsule.generation));
 }
-function capsuleDigest(capsule) {
-    return createHash("sha256").update(JSON.stringify(capsule)).digest("hex");
-}
-/** Every state writer shares the same crash-recoverable session reservation. */
-function withContextMutation(coordRoot, sessionId, action) {
-    const authority = createHash("sha256").update(sessionId).digest("hex");
-    const lease = acquireNoClobberLease({
-        path: join(contextDir(coordRoot, sessionId), "mutation.lease"),
-        scope: "context-continuity",
-        authoritySha256: authority,
-        staleAfterMs: 30_000,
-        validateStaleOwner: (owner) => owner.authority_sha256 === authority,
-    });
-    try {
-        return action();
-    }
-    finally {
-        lease.release();
-    }
-}
 function writeState(coordRoot, state) {
     writeBoundedJson(statePath(coordRoot, state.session_id), state, MAX_CAPSULE_BYTES);
 }
@@ -558,7 +479,12 @@ function contextDir(coordRoot, sessionId) {
 function sessionKey(sessionId) {
     return createHash("sha256").update(sessionId).digest("hex").slice(0, 24);
 }
-function writeBoundedJson(path, value, maxBytes) {
+/**
+ * Atomically replace a record. With `expected`, the replacement happens only
+ * while the file still holds exactly those bytes, so a concurrent writer's
+ * newer record is never overwritten by a decision made on older state.
+ */
+function writeBoundedJson(path, value, maxBytes, expected) {
     const text = `${JSON.stringify(value, null, 2)}\n`;
     const bytes = Buffer.byteLength(text, "utf8");
     if (bytes > maxBytes) {
@@ -567,18 +493,33 @@ function writeBoundedJson(path, value, maxBytes) {
     mkdirSync(dirname(path), { recursive: true });
     const temp = `${path}.tmp.${process.pid}.${randomUUID()}`;
     writeFileSync(temp, text, { encoding: "utf8", mode: stateFileMode() });
+    if (expected !== undefined && readText(path) !== expected) {
+        unlinkSync(temp);
+        return false;
+    }
     renameSync(temp, path);
+    return true;
 }
-function readJson(path) {
-    if (!existsSync(path))
+function readText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
         return null;
+    }
+}
+function parseJson(text) {
     try {
-        return JSON.parse(readFileSync(path, "utf8"));
+        return JSON.parse(text);
     }
     catch {
         return null;
     }
 }
+function readJson(path) {
+    const text = readText(path);
+    return text === null ? null : parseJson(text);
+}
 function git(cwd, args) {
     try {
         const result = spawnSync("git", args, { cwd, encoding: "utf8", timeout: 2_000 });
@@ -601,9 +542,6 @@ function git(cwd, args) {
         return { ok: false, reason: "spawn_error" };
     }
 }
-function repoObservation(value) {
-    return value === "ok" || value === "partial" ? value : "unavailable";
-}
 function sameMeasurement(a, b) {
     if (!a)
         return false;

package/dist/core/context/observation.d.ts

@@ -1,9 +1,9 @@
 /**
  * Repository observation contract shared by context recovery and workflow proof.
  *
- * This module has no runtime imports so read-only consumers (the Codec
- * dashboard, proof readers) can use it without reaching the Git-running
- * snapshot code in ./index.ts.
+ * This module runs no Git and touches no files, so read-only consumers (the
+ * Codec dashboard, proof readers) can use it without reaching the
+ * Git-running snapshot code in ./index.ts.
  */
 export type RepoObservation = "ok" | "unavailable" | "partial";
 export interface RepoSnapshot {
@@ -17,10 +17,10 @@ export interface RepoSnapshot {
     dirty_paths: string[];
     dirty_paths_truncated?: boolean;
 }
-/** Only explicitly successful observations can establish repository drift. */
-export declare function observationsComparable(a: {
-    observation?: string;
-}, b: {
-    observation?: string;
-}): boolean;
+/**
+ * Every reason two snapshots cannot establish repository drift. Only an empty
+ * list lets a caller compare branch, HEAD and dirty paths; anything else
+ * leaves the whole comparison unknown.
+ */
+export declare function repoComparisonProblems(a: RepoSnapshot, b: RepoSnapshot, labels: readonly [string, string]): string[];
 //# sourceMappingURL=observation.d.ts.map

package/dist/core/context/observation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../../../src/core/context/observation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,aAAa,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,eAAe,CAAC;IAC7B,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,8EAA8E;AAC9E,wBAAgB,sBAAsB,CACpC,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3B,CAAC,EAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1B,OAAO,CAET"}
+{"version":3,"file":"observation.d.ts","sourceRoot":"","sources":["../../../src/core/context/observation.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,aAAa,GAAG,SAAS,CAAC;AAE/D,MAAM,WAAW,YAAY;IAC3B,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,eAAe,CAAC;IAC7B,uEAAuE;IACvE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,CAAC,EAAE,YAAY,EACf,CAAC,EAAE,YAAY,EACf,MAAM,EAAE,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,MAAM,EAAE,CA0BV"}

package/dist/core/context/observation.js

@@ -1,11 +1,42 @@
 /**
  * Repository observation contract shared by context recovery and workflow proof.
  *
- * This module has no runtime imports so read-only consumers (the Codec
- * dashboard, proof readers) can use it without reaching the Git-running
- * snapshot code in ./index.ts.
+ * This module runs no Git and touches no files, so read-only consumers (the
+ * Codec dashboard, proof readers) can use it without reaching the
+ * Git-running snapshot code in ./index.ts.
  */
-/** Only explicitly successful observations can establish repository drift. */
-export function observationsComparable(a, b) {
-    return a.observation === "ok" && b.observation === "ok";
+import { isAbsolute } from "node:path";
+/**
+ * Every reason two snapshots cannot establish repository drift. Only an empty
+ * list lets a caller compare branch, HEAD and dirty paths; anything else
+ * leaves the whole comparison unknown.
+ */
+export function repoComparisonProblems(a, b, labels) {
+    const sides = [
+        [labels[0], a],
+        [labels[1], b],
+    ];
+    const failed = sides.flatMap(([label, repo]) => repo.observation === "ok"
+        ? []
+        : [
+            // Snapshots recorded before observations existed carry none.
+            `${label} snapshot is ${repo.observation ?? "unavailable"}${repo.observation_detail ? ` (${repo.observation_detail})` : ""}`,
+        ]);
+    if (failed.length > 0)
+        return failed;
+    const problems = [];
+    if (a.dirty_paths_truncated || b.dirty_paths_truncated) {
+        problems.push("dirty path list is truncated");
+    }
+    if (!a.root || !b.root || !isAbsolute(a.root) || !isAbsolute(b.root)) {
+        problems.push("repository root is unknown");
+    }
+    else if (a.root !== b.root) {
+        problems.push("repository roots differ");
+    }
+    if (!a.branch?.trim() || !b.branch?.trim())
+        problems.push("branch is unknown");
+    if (!a.head?.trim() || !b.head?.trim())
+        problems.push("HEAD is unknown");
+    return problems;
 }