vericify 0.1.0

package/src/publish/artifact.js

@@ -0,0 +1,91 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { buildRunComparison, findRunById } from "../compare/engine.js";
+import { hashText, isoNow, slugify } from "../core/util.js";
+import { resolveStoreLayout } from "../store/paths.js";
+import { writeJson } from "../core/fs.js";
+
+function markdownFromArtifact(artifact) {
+  const lines = [
+    `# ${artifact.title}`,
+    "",
+    `Published: ${artifact.published_at}`,
+    `Run ID: ${artifact.run.run_id}`,
+    `Status: ${artifact.run.status}`,
+    `Workspace: ${artifact.workspace.label ?? artifact.workspace.root_path}`,
+    "",
+    "## Current Pulse",
+    "",
+    `- Objective: ${artifact.run.objective ?? "-"}`,
+    `- Latest checkpoint: ${artifact.latest_checkpoint?.process_summary.split("\n")[0] ?? "-"}`,
+    `- Branches: ${artifact.run.branch_ids?.length ?? 0}`,
+    `- Lanes: ${artifact.run.lane_ids?.length ?? 0}`,
+    "",
+    "## Adapters",
+    "",
+    ...artifact.adapter_profiles.map((adapter) => `- ${adapter.label}: ${adapter.detection_status}`),
+    "",
+  ];
+  if (artifact.compare_report) {
+    lines.push(
+      "## Comparison",
+      "",
+      `- Summary: ${artifact.compare_report.summary}`,
+      ...artifact.compare_report.divergence_explanations.map((row) => `- Divergence: ${row}`),
+      ...artifact.compare_report.recovery_explanations.map((row) => `- Recovery: ${row}`),
+      "",
+      "## Recommended Actions",
+      "",
+      ...artifact.compare_report.recommended_actions.map((row) => `- ${row}`),
+      ""
+    );
+  }
+  lines.push(
+    "## Recent Checkpoints",
+    "",
+    ...artifact.recent_checkpoints.slice(-5).map((checkpoint) => `- ${checkpoint.timestamp}: ${checkpoint.process_summary.split("\n")[0]}`),
+    ""
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+export function buildPublishedRunArtifact({ projected, runId, compareRunId, title }) {
+  const run = findRunById(projected, runId);
+  if (!run) throw new Error(`Unknown run id: ${runId}`);
+  const compareRun = compareRunId ? findRunById(projected, compareRunId) : undefined;
+  if (compareRunId && !compareRun) throw new Error(`Unknown compare run id: ${compareRunId}`);
+  const compareReport = compareRun ? buildRunComparison(run, compareRun) : undefined;
+  const artifactId = `pub-${slugify(title ?? runId) || "artifact"}-${hashText(`${runId}:${compareRunId ?? "none"}:${isoNow()}`).slice(0, 10)}`;
+  return {
+    schema_version: "1.0.0",
+    artifact_id: artifactId,
+    published_at: isoNow(),
+    title: title ?? `${run.run.title} run artifact`,
+    workspace: projected.workspace,
+    adapter_profiles: projected.adapter_profiles ?? [],
+    run: run.run,
+    run_summary: run.run_summary,
+    latest_checkpoint: run.recent_checkpoints.at(-1),
+    recent_checkpoints: run.recent_checkpoints,
+    deltas: run.deltas,
+    similarity: run.similarity,
+    compare_report: compareReport,
+  };
+}
+
+export function publishRunArtifact({ workspaceRoot, projected, runId, compareRunId, title }) {
+  const artifact = buildPublishedRunArtifact({ projected, runId, compareRunId, title });
+  const layout = resolveStoreLayout(workspaceRoot);
+  const directory = resolve(layout.vericify.publishedRoot, artifact.artifact_id);
+  const artifactPath = resolve(directory, "run-artifact.json");
+  const summaryPath = resolve(directory, "SUMMARY.md");
+  mkdirSync(dirname(artifactPath), { recursive: true });
+  writeJson(artifactPath, artifact);
+  mkdirSync(dirname(summaryPath), { recursive: true });
+  writeFileSync(summaryPath, markdownFromArtifact(artifact));
+  return {
+    artifact_path: artifactPath,
+    summary_path: summaryPath,
+    artifact,
+  };
+}

package/src/similarity/semantic-hash.js

@@ -0,0 +1,95 @@
+import { hashText } from "../core/util.js";
+
+export function getShingles(text, k = 3) {
+  const clean = text.replace(/\s+/g, " ").toLowerCase();
+  const shingles = new Set();
+  for (let i = 0; i <= clean.length - k; i++) {
+    shingles.add(clean.substring(i, i + k));
+  }
+  return shingles;
+}
+
+export function calculateJaccard(setA, setB) {
+  if (setA.size === 0 && setB.size === 0) return 1;
+  if (setA.size === 0 || setB.size === 0) return 0;
+  let intersection = 0;
+  const smaller = setA.size <= setB.size ? setA : setB;
+  const larger = setA.size <= setB.size ? setB : setA;
+  for (const value of smaller) {
+    if (larger.has(value)) intersection += 1;
+  }
+  return intersection / (setA.size + setB.size - intersection);
+}
+
+function seededRandom(seed) {
+  let value = seed >>> 0;
+  return () => {
+    value = (value * 1664525 + 1013904223) >>> 0;
+    return value;
+  };
+}
+
+export class MinHash {
+  constructor(numPermutations = 64, seed = 42) {
+    this.numPermutations = numPermutations;
+    this.prime = 4294967311n;
+    this.maxHash = 4294967295;
+    this.permutations = [];
+    const rng = seededRandom(seed);
+    for (let i = 0; i < numPermutations; i += 1) {
+      this.permutations.push({
+        a: BigInt((rng() % this.maxHash) + 1),
+        b: BigInt((rng() % this.maxHash) + 1),
+      });
+    }
+  }
+
+  hashString(text) {
+    let hash = 5381;
+    for (let i = 0; i < text.length; i += 1) {
+      hash = ((hash << 5) + hash + text.charCodeAt(i)) >>> 0;
+    }
+    return hash;
+  }
+
+  computeSignature(shingles) {
+    const signature = new Array(this.numPermutations).fill(Infinity);
+    if (shingles.size === 0) return signature.fill(0);
+    for (const shingle of shingles) {
+      const h = BigInt(this.hashString(shingle));
+      for (let i = 0; i < this.numPermutations; i += 1) {
+        const { a, b } = this.permutations[i];
+        const permuted = Number((a * h + b) % this.prime);
+        if (permuted < signature[i]) signature[i] = permuted;
+      }
+    }
+    return signature;
+  }
+
+  estimateSimilarity(left, right) {
+    if (left.length !== right.length) return 0;
+    let matches = 0;
+    for (let i = 0; i < left.length; i += 1) {
+      if (left[i] === right[i]) matches += 1;
+    }
+    return matches / left.length;
+  }
+}
+
+const defaultHasher = new MinHash();
+
+export function fingerprintText(text) {
+  const shingles = getShingles(text, 3);
+  return {
+    signature_version: "v1-minhash64",
+    minhash_signature: defaultHasher.computeSignature(shingles),
+    content_hashes: [hashText(text)],
+    jaccard_basis_size: shingles.size,
+  };
+}
+
+export function similarityFromText(leftText, rightText) {
+  const left = fingerprintText(leftText);
+  const right = fingerprintText(rightText);
+  return defaultHasher.estimateSimilarity(left.minhash_signature, right.minhash_signature);
+}

package/src/store/adapter-attachments.js

@@ -0,0 +1,47 @@
+import { readJson, writeJson } from "../core/fs.js";
+import { isoNow } from "../core/util.js";
+import { resolveStoreLayout } from "./paths.js";
+
+export function normalizeAdapterAttachment(input, existing = {}) {
+  const adapterId = String(input.adapter_id ?? existing.adapter_id ?? "").trim();
+  if (!adapterId) throw new Error("Adapter attachments require --adapter.");
+  return {
+    adapter_id: adapterId,
+    attached_at: existing.attached_at ?? isoNow(),
+    updated_at: isoNow(),
+    capture_mode: String(input.capture_mode ?? existing.capture_mode ?? "manual").trim() || "manual",
+    session_id: input.session_id ?? existing.session_id,
+    label: input.label ?? existing.label,
+    notes: input.notes ?? existing.notes,
+  };
+}
+
+export function readAdapterAttachments(workspaceRoot) {
+  const layout = resolveStoreLayout(workspaceRoot);
+  return readJson(layout.vericify.adapterAttachments, {
+    version: 1,
+    updated_at: null,
+    attachments: [],
+  });
+}
+
+export function upsertAdapterAttachment(workspaceRoot, input) {
+  const layout = resolveStoreLayout(workspaceRoot);
+  const current = readAdapterAttachments(workspaceRoot);
+  const attachments = new Map(
+    (Array.isArray(current.attachments) ? current.attachments : []).map((attachment) => [attachment.adapter_id, attachment])
+  );
+  const next = normalizeAdapterAttachment(input, attachments.get(String(input.adapter_id ?? "").trim()));
+  attachments.set(next.adapter_id, next);
+  const value = {
+    version: current.version ?? 1,
+    updated_at: isoNow(),
+    attachments: [...attachments.values()].sort((left, right) => left.adapter_id.localeCompare(right.adapter_id)),
+  };
+  writeJson(layout.vericify.adapterAttachments, value);
+  return {
+    path: layout.vericify.adapterAttachments,
+    attachment: next,
+    value,
+  };
+}

package/src/store/common.js

@@ -0,0 +1,38 @@
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { readJson, writeJson } from "../core/fs.js";
+
+export function shouldMirrorPath(path) {
+  return existsSync(path) || existsSync(dirname(path));
+}
+
+export function appendNdjsonRecord(path, record) {
+  mkdirSync(dirname(path), { recursive: true });
+  appendFileSync(path, `${JSON.stringify(record)}\n`);
+}
+
+export function writeJsonWithMirrors({ primary, mirrors, fallback, update }) {
+  const current = readJson(primary, fallback);
+  const next = update(current);
+  writeJson(primary, next);
+  const mirrored_paths = [];
+  for (const mirrorPath of mirrors) {
+    if (!shouldMirrorPath(mirrorPath)) continue;
+    const mirrorCurrent = readJson(mirrorPath, fallback);
+    const mirrorNext = update(mirrorCurrent);
+    writeJson(mirrorPath, mirrorNext);
+    mirrored_paths.push(mirrorPath);
+  }
+  return { path: primary, mirrored_paths, value: next };
+}
+
+export function appendNdjsonWithMirrors({ primary, mirrors, record }) {
+  appendNdjsonRecord(primary, record);
+  const mirrored_paths = [];
+  for (const mirrorPath of mirrors) {
+    if (!shouldMirrorPath(mirrorPath)) continue;
+    appendNdjsonRecord(mirrorPath, record);
+    mirrored_paths.push(mirrorPath);
+  }
+  return { path: primary, mirrored_paths, record };
+}

package/src/store/handoffs.js

@@ -0,0 +1,64 @@
+import { isoNow } from "../core/util.js";
+import { resolveStoreLayout } from "./paths.js";
+import { writeJsonWithMirrors } from "./common.js";
+
+export function normalizeHandoff(input, existing = {}) {
+  const timestamp = input.timestamp ?? isoNow();
+  const handoffId = String(input.handoff_id ?? existing.handoff_id ?? "").trim();
+  const from = String(input.from ?? existing.from ?? "").trim();
+  const to = String(input.to ?? existing.to ?? "").trim();
+  const title = String(input.title ?? existing.title ?? "").trim();
+  const status = String(input.status ?? existing.status ?? "").trim();
+  if (!handoffId) throw new Error("Handoffs require --id.");
+  if (!from) throw new Error("Handoffs require --from.");
+  if (!to) throw new Error("Handoffs require --to.");
+  if (!title) throw new Error("Handoffs require --title.");
+  if (!status) throw new Error("Handoffs require --status.");
+  const note = String(input.note ?? "").trim();
+  const actor = String(input.actor ?? input.agent_id ?? from).trim();
+  const history = [...(Array.isArray(existing.history) ? existing.history : [])];
+  history.push({
+    timestamp_utc: timestamp,
+    status,
+    actor,
+    note: note || title,
+  });
+  return {
+    handoff_id: handoffId,
+    created_at: existing.created_at ?? timestamp,
+    updated_at: timestamp,
+    from,
+    to,
+    title,
+    task_type: input.task_type ?? existing.task_type,
+    priority: input.priority ?? existing.priority,
+    source_file: input.source_file ?? existing.source_file,
+    status,
+    history,
+  };
+}
+
+export function upsertHandoff(workspaceRoot, input) {
+  const layout = resolveStoreLayout(workspaceRoot);
+  const handoffId = String(input.handoff_id ?? "").trim();
+  if (!handoffId) throw new Error("Handoffs require --id.");
+  const result = writeJsonWithMirrors({
+    primary: layout.vericify.handoffRegistry,
+    mirrors: [layout.partner.handoffRegistry],
+    fallback: { version: 1, updated_at: isoNow(), handoffs: {} },
+    update(current) {
+      const handoffs = { ...(current.handoffs ?? {}) };
+      const existing = handoffs[handoffId] ?? {};
+      handoffs[handoffId] = normalizeHandoff(input, existing);
+      return {
+        version: current.version ?? 1,
+        updated_at: isoNow(),
+        handoffs,
+      };
+    },
+  });
+  return {
+    ...result,
+    handoff: result.value.handoffs[handoffId],
+  };
+}

package/src/store/paths.js

@@ -0,0 +1,40 @@
+import { resolve } from "node:path";
+
+export const STORE_LAYOUT = {
+  vericify: {
+    adapterAttachments: ".vericify/adapters.json",
+    handoffRegistry: ".vericify/handoffs.json",
+    todoState: ".vericify/todo-state.json",
+    runLedger: ".vericify/run-ledger.json",
+    statusEvents: ".vericify/status-events.ndjson",
+    processPosts: ".vericify/process-posts.json",
+    publishedRoot: ".vericify/published",
+    syncOutboxRoot: ".vericify/sync-outbox",
+  },
+  partner: {
+    handoffRegistry: "agent-state/handoff-registry.json",
+    todoState: "agent-state/todo-state.json",
+    runLedger: "agent-state/run-ledger.json",
+    statusEvents: "agent-state/STATUS_EVENTS.ndjson",
+    processPosts: "agent-state/vericify/process-posts.json",
+  },
+};
+
+export function resolveStoreLayout(workspaceRoot) {
+  return {
+    vericify: Object.fromEntries(
+      Object.entries(STORE_LAYOUT.vericify).map(([key, relPath]) => [key, resolve(workspaceRoot, relPath)])
+    ),
+    partner: Object.fromEntries(
+      Object.entries(STORE_LAYOUT.partner).map(([key, relPath]) => [key, resolve(workspaceRoot, relPath)])
+    ),
+  };
+}
+
+export function listStorePaths(workspaceRoot) {
+  const layout = resolveStoreLayout(workspaceRoot);
+  return [
+    ...Object.values(layout.vericify),
+    ...Object.values(layout.partner),
+  ];
+}

package/src/store/run-ledger.js

@@ -0,0 +1,46 @@
+import { asArray, hashText, isoNow, slugify } from "../core/util.js";
+import { resolveStoreLayout } from "./paths.js";
+import { writeJsonWithMirrors } from "./common.js";
+
+export function normalizeRunLedgerEntry(entry) {
+  const timestamp = entry.timestamp_utc ?? isoNow();
+  const tool = String(entry.tool ?? "").trim();
+  const category = String(entry.category ?? "").trim();
+  const message = String(entry.message ?? "").trim();
+  if (!tool) throw new Error("Run-ledger entries require --tool.");
+  if (!category) throw new Error("Run-ledger entries require --category.");
+  if (!message) throw new Error("Run-ledger entries require --message.");
+  return {
+    id: entry.id ?? `ledger-${slugify(`${tool}-${category}`) || "entry"}-${hashText(`${timestamp}:${tool}:${message}`).slice(0, 10)}`,
+    timestamp_utc: timestamp,
+    tool,
+    category,
+    message,
+    artifacts: asArray(entry.artifacts),
+    metadata: entry.metadata ?? {},
+  };
+}
+
+export function appendRunLedgerEntry(workspaceRoot, input) {
+  const layout = resolveStoreLayout(workspaceRoot);
+  const entry = normalizeRunLedgerEntry(input);
+  const result = writeJsonWithMirrors({
+    primary: layout.vericify.runLedger,
+    mirrors: [layout.partner.runLedger],
+    fallback: { version: 1, updated_at: isoNow(), entries: [] },
+    update(current) {
+      const entries = [...(Array.isArray(current.entries) ? current.entries : []), entry].sort((left, right) =>
+        String(left.timestamp_utc).localeCompare(String(right.timestamp_utc))
+      );
+      return {
+        version: current.version ?? 1,
+        updated_at: isoNow(),
+        entries,
+      };
+    },
+  });
+  return {
+    ...result,
+    entry,
+  };
+}

package/src/store/status-events.js

@@ -0,0 +1,39 @@
+import { hashText, isoNow, slugify } from "../core/util.js";
+import { resolveStoreLayout } from "./paths.js";
+import { appendNdjsonWithMirrors } from "./common.js";
+
+export function normalizeStatusEvent(event) {
+  const timestamp = event.timestamp ?? isoNow();
+  const sourceModule = String(event.source_module ?? "").trim();
+  const eventType = String(event.event_type ?? "").trim();
+  const status = String(event.status ?? "").trim();
+  if (!sourceModule) throw new Error("Status events require --source-module.");
+  if (!eventType) throw new Error("Status events require --event-type.");
+  if (!status) throw new Error("Status events require --status.");
+  return {
+    schema_version: event.schema_version ?? "1.0.0",
+    event_id: event.event_id ?? `evt-${slugify(`${sourceModule}-${eventType}`) || "event"}-${hashText(`${timestamp}:${sourceModule}:${eventType}:${status}`).slice(0, 10)}`,
+    trace_id: event.trace_id,
+    timestamp,
+    source_module: sourceModule,
+    event_type: eventType,
+    status,
+    objective_id: event.objective_id,
+    decision_id: event.decision_id,
+    payload: event.payload ?? {},
+  };
+}
+
+export function appendStatusEvent(workspaceRoot, input) {
+  const layout = resolveStoreLayout(workspaceRoot);
+  const event = normalizeStatusEvent(input);
+  const result = appendNdjsonWithMirrors({
+    primary: layout.vericify.statusEvents,
+    mirrors: [layout.partner.statusEvents],
+    record: event,
+  });
+  return {
+    ...result,
+    event,
+  };
+}

package/src/store/todo-state.js

@@ -0,0 +1,49 @@
+import { asArray, isoNow, unique } from "../core/util.js";
+import { resolveStoreLayout } from "./paths.js";
+import { writeJsonWithMirrors } from "./common.js";
+
+export function normalizeTodoNode(input, existing = {}) {
+  const nodeId = String(input.id ?? existing.id ?? "").trim();
+  const title = String(input.title ?? existing.title ?? "").trim();
+  const status = String(input.status ?? existing.status ?? "").trim();
+  if (!nodeId) throw new Error("Todo writes require --id.");
+  if (!title) throw new Error("Todo writes require --title.");
+  if (!status) throw new Error("Todo writes require --status.");
+  return {
+    id: nodeId,
+    title,
+    section: input.section ?? existing.section,
+    source_line: input.source_line ?? existing.source_line,
+    depends_on: unique(asArray(input.depends_on ?? existing.depends_on ?? [])),
+    status,
+    priority: input.priority ?? existing.priority,
+  };
+}
+
+export function upsertTodoNode(workspaceRoot, input) {
+  const layout = resolveStoreLayout(workspaceRoot);
+  const nodeId = String(input.id ?? "").trim();
+  if (!nodeId) throw new Error("Todo writes require --id.");
+  const result = writeJsonWithMirrors({
+    primary: layout.vericify.todoState,
+    mirrors: [layout.partner.todoState],
+    fallback: { version: 1, updated_at: isoNow(), order: [], nodes: {} },
+    update(current) {
+      const nodes = { ...(current.nodes ?? {}) };
+      const existing = nodes[nodeId] ?? {};
+      nodes[nodeId] = normalizeTodoNode(input, existing);
+      const order = unique([...(Array.isArray(current.order) ? current.order : []), nodeId]);
+      return {
+        version: current.version ?? 1,
+        updated_at: isoNow(),
+        source_todo_path: current.source_todo_path ?? input.source_todo_path,
+        order,
+        nodes,
+      };
+    },
+  });
+  return {
+    ...result,
+    node: result.value.nodes[nodeId],
+  };
+}

package/src/sync/outbox.js

@@ -0,0 +1,29 @@
+import { resolve } from "node:path";
+import { writeJson } from "../core/fs.js";
+import { hashText, isoNow, slugify } from "../core/util.js";
+import { resolveStoreLayout } from "../store/paths.js";
+
+export function enqueueSyncOutboxItem({ workspaceRoot, artifact, artifactPath, endpoint, target = "vericify-cloud-v1" }) {
+  const layout = resolveStoreLayout(workspaceRoot);
+  const queuedAt = isoNow();
+  const item = {
+    schema_version: "1.0.0",
+    outbox_item_id: `sync-${slugify(artifact?.run?.run_id ?? artifact?.artifact_id ?? "artifact")}-${hashText(`${queuedAt}:${artifactPath}:${target}`).slice(0, 10)}`,
+    queued_at: queuedAt,
+    status: "queued",
+    target,
+    endpoint,
+    workspace: artifact?.workspace,
+    run_id: artifact?.run?.run_id,
+    compare_run_id: artifact?.compare_report?.right_run_id,
+    artifact_path: artifactPath,
+    artifact_hash: hashText(JSON.stringify(artifact)),
+    delivery_mode: endpoint ? "manual-http-push" : "manual-export",
+  };
+  const path = resolve(layout.vericify.syncOutboxRoot, `${item.outbox_item_id}.json`);
+  writeJson(path, item);
+  return {
+    path,
+    item,
+  };
+}