vericify 0.1.0

package/src/api.js

@@ -0,0 +1,12 @@
+export {
+  DEFAULT_ADAPTER,
+  attachAdapter,
+  detectAdapters,
+  listAvailableAdapters,
+  listDefaultWorkspacePaths,
+  loadWorkspaceState,
+} from "./adapters/index.js";
+export { buildRunComparison, findRunById } from "./compare/engine.js";
+export { projectWorkspaceState } from "./projection/runs.js";
+export { publishRunArtifact } from "./publish/artifact.js";
+export { enqueueSyncOutboxItem } from "./sync/outbox.js";

package/src/checkpoints/policy.js

@@ -0,0 +1,96 @@
+export const CHECKPOINT_POLICY_VERSION = "1.0.0";
+
+const CHECKPOINT_TRIGGER_RULES = [
+  { trigger_kind: "handoff", source: "handoff_history", capture_mode: "semantic" },
+  { trigger_kind: "status_transition", source: "status_event", capture_mode: "semantic" },
+  { trigger_kind: "process_milestone", source: "process_post", capture_mode: "semantic" },
+  { trigger_kind: "ledger_update", source: "run_ledger", capture_mode: "semantic" },
+  { trigger_kind: "operator_save", source: "workspace_rollup", capture_mode: "semantic" },
+  { trigger_kind: "branch_fork", source: "explicit_branch_signal", capture_mode: "hybrid" },
+];
+
+function checkpointMeta(triggerKind, triggerReason, captureMode = "semantic") {
+  return {
+    checkpoint_policy_version: CHECKPOINT_POLICY_VERSION,
+    trigger_kind: triggerKind,
+    trigger_reason: triggerReason,
+    capture_mode: captureMode,
+  };
+}
+
+function captureModeForRecord(record) {
+  return record?.git_commit_sha || record?.payload?.git_commit_sha || record?.metadata?.git_commit_sha ? "hybrid" : "semantic";
+}
+
+export function listCheckpointTriggerRules() {
+  return [...CHECKPOINT_TRIGGER_RULES];
+}
+
+export function checkpointTriggerFromHandoff(handoff, entry) {
+  const status = entry?.status ?? handoff?.status ?? "open";
+  return checkpointMeta(
+    "handoff",
+    `Handoff ${status} between ${handoff?.from ?? "unknown"} and ${handoff?.to ?? "unknown"}.`,
+    captureModeForRecord(entry)
+  );
+}
+
+export function checkpointTriggerFromWorkspaceSummary() {
+  return checkpointMeta(
+    "operator_save",
+    "Workspace rollup checkpoint summarizing current task, event, ledger, and process-post state."
+  );
+}
+
+export function checkpointTriggerFromStatusEvent(event, previousEvent) {
+  const branchFork = Boolean(event?.payload?.branch_id) && previousEvent?.payload?.branch_id !== event?.payload?.branch_id;
+  if (branchFork) {
+    return checkpointMeta(
+      "branch_fork",
+      `Status event ${event?.event_type ?? "unknown"} moved execution onto branch ${event?.payload?.branch_id}.`,
+      captureModeForRecord(event)
+    );
+  }
+  return checkpointMeta(
+    "status_transition",
+    `Status event ${event?.event_type ?? "unknown"} recorded ${event?.status ?? "planned"}.`,
+    captureModeForRecord(event)
+  );
+}
+
+export function checkpointTriggerFromProcessPost(post) {
+  if (post?.branch_id) {
+    return checkpointMeta(
+      "branch_fork",
+      `Process post ${post?.kind ?? "progress"} referenced branch ${post.branch_id}.`,
+      captureModeForRecord(post)
+    );
+  }
+  if (post?.checkpoint_ref) {
+    return checkpointMeta(
+      "operator_save",
+      `Process post ${post?.kind ?? "progress"} pinned checkpoint ${post.checkpoint_ref}.`,
+      captureModeForRecord(post)
+    );
+  }
+  if (post?.kind === "handoff_note") {
+    return checkpointMeta(
+      "handoff",
+      `Process post recorded a handoff note from ${post?.agent_id ?? "unknown"}.`,
+      captureModeForRecord(post)
+    );
+  }
+  return checkpointMeta(
+    "process_milestone",
+    `Process post ${post?.kind ?? "progress"} from ${post?.agent_id ?? "unknown"}.`,
+    captureModeForRecord(post)
+  );
+}
+
+export function checkpointTriggerFromLedgerEntry(entry) {
+  return checkpointMeta(
+    entry?.category === "regression" ? "status_transition" : "ledger_update",
+    `Run-ledger ${entry?.category ?? "update"} from ${entry?.tool ?? "unknown"}.`,
+    captureModeForRecord(entry)
+  );
+}

package/src/compare/engine.js

@@ -0,0 +1,220 @@
+import { calculateJaccard, similarityFromText } from "../similarity/semantic-hash.js";
+import { isoNow, unique } from "../core/util.js";
+
+function latestCheckpoint(run) {
+  return run?.recent_checkpoints?.at(-1);
+}
+
+function latestDelta(run) {
+  return run?.deltas?.at(-1);
+}
+
+function asSet(values) {
+  return new Set((values ?? []).filter(Boolean));
+}
+
+function overlap(leftValues, rightValues) {
+  const left = asSet(leftValues);
+  const right = asSet(rightValues);
+  const shared = [...left].filter((value) => right.has(value));
+  const leftOnly = [...left].filter((value) => !right.has(value));
+  const rightOnly = [...right].filter((value) => !left.has(value));
+  return {
+    score: calculateJaccard(left, right),
+    shared,
+    left_only: leftOnly,
+    right_only: rightOnly,
+  };
+}
+
+function activeNodeLabels(run) {
+  return unique((run?.nodes ?? []).filter((node) => node.status !== "done").map((node) => node.title));
+}
+
+function actorIds(run) {
+  return unique((run?.lanes ?? []).map((lane) => lane.agent_id));
+}
+
+function layerIds(run) {
+  return unique(latestDelta(run)?.layers ?? []);
+}
+
+function checkpointSummary(run) {
+  return latestCheckpoint(run)?.process_summary ?? "";
+}
+
+function lineSummary(run) {
+  return checkpointSummary(run).split("\n")[0] ?? "-";
+}
+
+function scoreRunSimilarity(metrics) {
+  return Math.max(
+    0,
+    Math.min(
+      1,
+      metrics.checkpoint_similarity * 0.5 +
+        metrics.actor_overlap * 0.2 +
+        metrics.node_overlap * 0.15 +
+        metrics.layer_overlap * 0.15
+    )
+  );
+}
+
+function layerGrid(leftRun, rightRun) {
+  const layers = unique([...layerIds(leftRun), ...layerIds(rightRun)]);
+  return layers.map((layer) => ({
+    layer,
+    left_present: layerIds(leftRun).includes(layer),
+    right_present: layerIds(rightRun).includes(layer),
+    status: layerIds(leftRun).includes(layer) && layerIds(rightRun).includes(layer)
+      ? "shared"
+      : layerIds(leftRun).includes(layer)
+        ? "left_only"
+        : "right_only",
+  }));
+}
+
+function buildSimilarityExplanations(metrics, leftRun, rightRun) {
+  const rows = [];
+  if (metrics.checkpoint_similarity >= 0.35) {
+    rows.push(`Latest checkpoints read similarly at ${(metrics.checkpoint_similarity * 100).toFixed(0)}%.`);
+  }
+  if (metrics.actor.shared.length) {
+    rows.push(`Shared actors: ${metrics.actor.shared.join(", ")}.`);
+  }
+  if (metrics.nodes.shared.length) {
+    rows.push(`Shared active nodes: ${metrics.nodes.shared.join(", ")}.`);
+  }
+  if (metrics.layers.shared.length) {
+    rows.push(`Shared delta layers: ${metrics.layers.shared.join(", ")}.`);
+  }
+  if (!rows.length) {
+    rows.push(`Runs ${leftRun.run.run_id} and ${rightRun.run.run_id} share little surface area.`);
+  }
+  return rows;
+}
+
+function buildDivergenceExplanations(metrics, leftRun, rightRun) {
+  const rows = [];
+  if (leftRun.run.status !== rightRun.run.status) {
+    rows.push(`Run status diverged: ${leftRun.run.status} vs ${rightRun.run.status}.`);
+  }
+  if ((leftRun.branches?.length ?? 0) !== (rightRun.branches?.length ?? 0)) {
+    rows.push(`Branch topology diverged: ${(leftRun.branches?.length ?? 0)} vs ${(rightRun.branches?.length ?? 0)} branches.`);
+  }
+  if ((leftRun.lanes?.length ?? 0) !== (rightRun.lanes?.length ?? 0)) {
+    rows.push(`Lane load diverged: ${(leftRun.lanes?.length ?? 0)} vs ${(rightRun.lanes?.length ?? 0)} lanes.`);
+  }
+  if (metrics.nodes.left_only.length || metrics.nodes.right_only.length) {
+    rows.push(
+      `Active node focus differs: left-only ${metrics.nodes.left_only.join(", ") || "none"} | right-only ${metrics.nodes.right_only.join(", ") || "none"}.`
+    );
+  }
+  if (metrics.checkpoint_similarity < 0.35) {
+    rows.push(`Latest checkpoint narratives are materially different at only ${(metrics.checkpoint_similarity * 100).toFixed(0)}% similarity.`);
+  }
+  if (!rows.length) rows.push("Primary run shape is aligned.");
+  return rows;
+}
+
+function buildRecoveryExplanations(metrics, leftRun, rightRun) {
+  if (rightRun.run.status === "completed") {
+    return [
+      `Use ${rightRun.run.run_id} as a recovery template because it completed with ${(metrics.similarity_score * 100).toFixed(0)}% composite similarity.`,
+      `Replay from checkpoint: ${lineSummary(rightRun)}.`,
+    ];
+  }
+  if (rightRun.run.status === "blocked") {
+    return [
+      `Treat ${rightRun.run.run_id} as a failure echo and intervene before matching its blocked shape.`,
+      `Watch for: ${lineSummary(rightRun)}.`,
+    ];
+  }
+  return [
+    `Peer run ${rightRun.run.run_id} is still active; use it as a live comparison, not a template.`,
+  ];
+}
+
+function buildRecommendedActions(metrics, leftRun, rightRun) {
+  const actions = [];
+  if (rightRun.run.status === "completed" && metrics.similarity_score >= 0.3) {
+    actions.push(`Compare the latest completed checkpoint from ${rightRun.run.run_id} against ${leftRun.run.run_id}.`);
+  }
+  if (rightRun.run.status === "blocked" && metrics.similarity_score >= 0.3) {
+    actions.push(`Review the divergence that precedes ${rightRun.run.run_id}'s blocked checkpoint.`);
+  }
+  if ((leftRun.lanes?.length ?? 0) < (rightRun.lanes?.length ?? 0)) {
+    actions.push(`Investigate whether ${leftRun.run.run_id} is under-provisioned relative to ${rightRun.run.run_id}.`);
+  }
+  if (metrics.nodes.left_only.length) {
+    actions.push(`Validate whether left-only active nodes are expected: ${metrics.nodes.left_only.join(", ")}.`);
+  }
+  if (!actions.length) actions.push("No urgent operator action. Monitor the latest checkpoint pulse.");
+  return actions;
+}
+
+export function buildRunComparison(leftRun, rightRun) {
+  if (!leftRun || !rightRun) {
+    throw new Error("Run comparison requires two run details.");
+  }
+
+  const actor = overlap(actorIds(leftRun), actorIds(rightRun));
+  const nodes = overlap(activeNodeLabels(leftRun), activeNodeLabels(rightRun));
+  const layers = overlap(layerIds(leftRun), layerIds(rightRun));
+  const checkpointSimilarity = similarityFromText(checkpointSummary(leftRun), checkpointSummary(rightRun));
+  const metrics = {
+    checkpoint_similarity: checkpointSimilarity,
+    actor_overlap: actor.score,
+    node_overlap: nodes.score,
+    layer_overlap: layers.score,
+    branch_delta: Math.abs((leftRun.branches?.length ?? 0) - (rightRun.branches?.length ?? 0)),
+    lane_delta: Math.abs((leftRun.lanes?.length ?? 0) - (rightRun.lanes?.length ?? 0)),
+    actor,
+    nodes,
+    layers,
+  };
+  metrics.similarity_score = scoreRunSimilarity(metrics);
+
+  return {
+    schema_version: "1.0.0",
+    compared_at: isoNow(),
+    left_run_id: leftRun.run.run_id,
+    right_run_id: rightRun.run.run_id,
+    similarity_score: metrics.similarity_score,
+    checkpoint_similarity: metrics.checkpoint_similarity,
+    actor_overlap: metrics.actor_overlap,
+    node_overlap: metrics.node_overlap,
+    layer_overlap: metrics.layer_overlap,
+    layer_grid: layerGrid(leftRun, rightRun),
+    shared_actors: metrics.actor.shared,
+    shared_nodes: metrics.nodes.shared,
+    shared_layers: metrics.layers.shared,
+    divergence_explanations: buildDivergenceExplanations(metrics, leftRun, rightRun),
+    similarity_explanations: buildSimilarityExplanations(metrics, leftRun, rightRun),
+    recovery_explanations: buildRecoveryExplanations(metrics, leftRun, rightRun),
+    recommended_actions: buildRecommendedActions(metrics, leftRun, rightRun),
+    left: {
+      run_id: leftRun.run.run_id,
+      title: leftRun.run.title,
+      status: leftRun.run.status,
+      branch_count: leftRun.branches?.length ?? 0,
+      lane_count: leftRun.lanes?.length ?? 0,
+      latest_checkpoint_id: latestCheckpoint(leftRun)?.checkpoint_id,
+      latest_checkpoint_summary: lineSummary(leftRun),
+    },
+    right: {
+      run_id: rightRun.run.run_id,
+      title: rightRun.run.title,
+      status: rightRun.run.status,
+      branch_count: rightRun.branches?.length ?? 0,
+      lane_count: rightRun.lanes?.length ?? 0,
+      latest_checkpoint_id: latestCheckpoint(rightRun)?.checkpoint_id,
+      latest_checkpoint_summary: lineSummary(rightRun),
+    },
+    summary: `${leftRun.run.run_id} vs ${rightRun.run.run_id} | ${(metrics.similarity_score * 100).toFixed(0)}% composite similarity`,
+  };
+}
+
+export function findRunById(projected, runId) {
+  return (projected?.runs ?? []).find((run) => run.run.run_id === runId);
+}

package/src/core/fs.js

@@ -0,0 +1,86 @@
+import { dirname } from "node:path";
+import { existsSync, mkdirSync, readFileSync, statSync, watch, writeFileSync } from "node:fs";
+
+export function readText(path, fallback = "") {
+  try {
+    return existsSync(path) ? readFileSync(path, "utf8") : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+export function readJson(path, fallback) {
+  try {
+    if (!existsSync(path)) return fallback;
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return fallback;
+  }
+}
+
+export function readNdjson(path) {
+  const raw = readText(path, "");
+  if (!raw.trim()) return [];
+  return raw
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .flatMap((line) => {
+      try {
+        return [JSON.parse(line)];
+      } catch {
+        return [];
+      }
+    });
+}
+
+export function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function createDebouncedWatch(paths, onChange, debounceMs = 120) {
+  const timers = new Map();
+  const watchers = [];
+  const watchRoots = new Set();
+  for (const path of paths) {
+    if (existsSync(path)) {
+      try {
+        watchRoots.add(statSync(path).isDirectory() ? path : path);
+      } catch {
+        // ignore unstable paths
+      }
+    }
+    const parent = dirname(path);
+    if (existsSync(parent)) watchRoots.add(parent);
+  }
+  for (const path of watchRoots) {
+    try {
+      const watcher = watch(path, () => {
+        const existing = timers.get(path);
+        if (existing) clearTimeout(existing);
+        timers.set(
+          path,
+          setTimeout(() => {
+            timers.delete(path);
+            onChange(path);
+          }, debounceMs)
+        );
+      });
+      watchers.push(watcher);
+    } catch {
+      // ignore unwatchable paths
+    }
+  }
+  return () => {
+    for (const timer of timers.values()) clearTimeout(timer);
+    timers.clear();
+    for (const watcher of watchers) {
+      try {
+        watcher.close();
+      } catch {
+        // ignore
+      }
+    }
+  };
+}

package/src/core/util.js

@@ -0,0 +1,59 @@
+import { createHash } from "node:crypto";
+import { basename } from "node:path";
+
+export function slugify(value) {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+}
+
+export function hashText(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+export function isoNow() {
+  return new Date().toISOString();
+}
+
+export function workspaceRef(rootPath) {
+  return {
+    workspace_id: slugify(basename(rootPath) || "workspace"),
+    root_path: rootPath,
+    label: basename(rootPath) || rootPath,
+  };
+}
+
+export function unique(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+export function asArray(value) {
+  return Array.isArray(value) ? value : value === undefined || value === null ? [] : [value];
+}
+
+export function firstDefined(...values) {
+  return values.find((value) => value !== undefined && value !== null && value !== "");
+}
+
+export function formatTimestamp(value) {
+  if (!value) return "-";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return `${date.toLocaleDateString()} ${date.toLocaleTimeString()}`;
+}
+
+export function relativeTimeFromNow(value) {
+  if (!value) return "-";
+  const date = new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  const delta = date.getTime() - Date.now();
+  const abs = Math.abs(delta);
+  const minutes = Math.round(abs / 60000);
+  if (minutes < 1) return "now";
+  if (minutes < 60) return `${delta < 0 ? "" : "+"}${minutes}m`;
+  const hours = Math.round(minutes / 60);
+  return `${delta < 0 ? "" : "+"}${hours}h`;
+}