avorelo 0.1.0

package/scripts/lib/session-timing.js

@@ -0,0 +1,315 @@
+"use strict";
+
+// ── Session Timing Evidence v1 ────────────────────────────────────────────────
+//
+// Records and derives timing events for Avorelo sessions.
+// Timing is EVIDENCE — not savings. Duration does not automatically become
+// "time saved". Activation timing is readiness timing, not savings timing.
+// No network. No secrets.
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+const SCHEMA_VERSION = 1;
+const CONTRACT = "avorelo.sessionTiming.v1";
+const SESSION_TIMING_DIR_REL = ".claude/cco/orchestration/session-timing";
+const SESSION_TIMING_LATEST_REL = ".claude/cco/orchestration/session-timing/latest-session-timing.json";
+const SESSION_TIMING_EVENTS_REL = ".claude/cco/events/session-timing.jsonl";
+
+// Receipt paths to read timestamps from
+const ACTIVATION_STATE_REL = ".claude/cco/state/activation.json";
+const SESSION_CONTEXT_REL = ".claude/cco/orchestration/session-context/latest-context.json";
+const OPERATING_VALUE_REL = ".claude/cco/orchestration/operating-value/latest-value.json";
+const PROOF_REL = ".claude/cco/receipts/latest-proof.json";
+const WORK_CONTROL_REL = ".claude/cco/orchestration/work-control/latest-receipt.json";
+
+function shortId() {
+  return crypto.randomBytes(4).toString("hex");
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function ensureDirFor(filePath) {
+  const dir = path.dirname(filePath);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+function safeReadJson(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function fileModTimeIso(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return null;
+    return new Date(fs.statSync(filePath).mtimeMs).toISOString();
+  } catch {
+    return null;
+  }
+}
+
+function parseIso(s) {
+  if (!s) return null;
+  const d = new Date(s);
+  return isNaN(d.getTime()) ? null : d.getTime();
+}
+
+function diffMs(startIso, endIso) {
+  const s = parseIso(startIso);
+  const e = parseIso(endIso);
+  if (s === null || e === null) return null;
+  const diff = e - s;
+  return diff >= 0 ? diff : null;
+}
+
+// ── Read timing events from existing orchestration artifacts ──────────────────
+
+function gatherTimingEvents(cwd) {
+  const events = [];
+
+  // Activation event — from activation state file or its mtime
+  const activationPath = path.resolve(cwd, ACTIVATION_STATE_REL);
+  const activationData = safeReadJson(activationPath);
+  const activationTs = (activationData && (activationData.createdAt || activationData.activatedAt))
+    || fileModTimeIso(activationPath);
+  if (activationTs) {
+    events.push({
+      event: "activation_completed",
+      timestamp: activationTs,
+      source: activationData ? "activation_state_json" : "file_mtime",
+      sessionId: activationData && activationData.activationId || null,
+      evidencePath: ACTIVATION_STATE_REL,
+    });
+  }
+
+  // Session context handoff event
+  const scPath = path.resolve(cwd, SESSION_CONTEXT_REL);
+  const scData = safeReadJson(scPath);
+  const scTs = (scData && scData.createdAt) || fileModTimeIso(scPath);
+  if (scTs) {
+    events.push({
+      event: "session_context_generated",
+      timestamp: scTs,
+      source: scData ? "session_context_json" : "file_mtime",
+      sessionId: scData && scData.contextId || null,
+      evidencePath: SESSION_CONTEXT_REL,
+    });
+  }
+
+  // Work control receipt event
+  const wcPath = path.resolve(cwd, WORK_CONTROL_REL);
+  const wcData = safeReadJson(wcPath);
+  const wcTs = (wcData && wcData.createdAt) || fileModTimeIso(wcPath);
+  if (wcTs) {
+    events.push({
+      event: "work_control_receipt_written",
+      timestamp: wcTs,
+      source: wcData ? "work_control_json" : "file_mtime",
+      sessionId: wcData && wcData.receiptId || null,
+      evidencePath: WORK_CONTROL_REL,
+    });
+  }
+
+  // Proof event
+  const proofPath = path.resolve(cwd, PROOF_REL);
+  const proofData = safeReadJson(proofPath);
+  const proofTs = (proofData && proofData.createdAt) || fileModTimeIso(proofPath);
+  if (proofTs) {
+    events.push({
+      event: "proof_written",
+      timestamp: proofTs,
+      source: proofData ? "proof_json" : "file_mtime",
+      sessionId: proofData && proofData.proofId || null,
+      evidencePath: PROOF_REL,
+    });
+  }
+
+  // Operating value event
+  const ovPath = path.resolve(cwd, OPERATING_VALUE_REL);
+  const ovData = safeReadJson(ovPath);
+  const ovTs = (ovData && ovData.createdAt) || fileModTimeIso(ovPath);
+  if (ovTs) {
+    events.push({
+      event: "operating_value_generated",
+      timestamp: ovTs,
+      source: ovData ? "operating_value_json" : "file_mtime",
+      sessionId: ovData && ovData.valueId || null,
+      evidencePath: OPERATING_VALUE_REL,
+    });
+  }
+
+  // Sort chronologically
+  events.sort((a, b) => {
+    const ta = parseIso(a.timestamp) || 0;
+    const tb = parseIso(b.timestamp) || 0;
+    return ta - tb;
+  });
+
+  return events;
+}
+
+// ── Derive timing summary ─────────────────────────────────────────────────────
+
+function deriveTimingSummary(events) {
+  const byEvent = {};
+  events.forEach((e) => { byEvent[e.event] = e.timestamp; });
+
+  const activationTs = byEvent["activation_completed"];
+  const handoffTs = byEvent["session_context_generated"];
+  const proofTs = byEvent["proof_written"];
+  const ovTs = byEvent["operating_value_generated"];
+
+  // Session window: earliest to latest event timestamp
+  const timestamps = events.map((e) => parseIso(e.timestamp)).filter(Boolean);
+  const sessionStart = timestamps.length ? new Date(Math.min(...timestamps)).toISOString() : null;
+  const sessionEnd = timestamps.length ? new Date(Math.max(...timestamps)).toISOString() : null;
+
+  return {
+    activationDurationMs: null, // cannot measure activation duration without start+end within activation
+    timeToHandoffMs: diffMs(activationTs, handoffTs),
+    timeToDashboardReadyMs: diffMs(activationTs, ovTs),
+    timeToProofMs: diffMs(activationTs, proofTs),
+    sessionDurationMs: diffMs(sessionStart, sessionEnd),
+    timeToFirstUsefulActionMs: null, // requires explicit first-useful-action marker
+    sessionStart,
+    sessionEnd,
+  };
+}
+
+// ── Record a timing event ─────────────────────────────────────────────────────
+
+function recordTimingEvent(cwd, eventName, meta = {}) {
+  const eventsPath = path.resolve(cwd, SESSION_TIMING_EVENTS_REL);
+  ensureDirFor(eventsPath);
+  const entry = {
+    event: eventName,
+    timestamp: nowIso(),
+    source: "explicit_mark",
+    ...meta,
+  };
+  fs.appendFileSync(eventsPath, JSON.stringify(entry) + "\n", "utf8");
+  return entry;
+}
+
+// ── Build session timing summary ──────────────────────────────────────────────
+
+function buildSessionTimingSummary(cwd, options = {}) {
+  const timingId = `st-${Date.now()}-${shortId()}`;
+  const createdAt = nowIso();
+
+  const artifactEvents = gatherTimingEvents(cwd);
+
+  // Also read explicit events from session-timing.jsonl
+  const explicitEventsPath = path.resolve(cwd, SESSION_TIMING_EVENTS_REL);
+  const explicitEvents = [];
+  if (fs.existsSync(explicitEventsPath)) {
+    try {
+      const lines = fs.readFileSync(explicitEventsPath, "utf8").split("\n").filter(Boolean);
+      lines.forEach((line) => {
+        try { explicitEvents.push(JSON.parse(line)); } catch {}
+      });
+    } catch {}
+  }
+
+  // Merge and deduplicate by event name (prefer explicit over artifact)
+  const explicitByEvent = {};
+  explicitEvents.forEach((e) => { explicitByEvent[e.event] = e; });
+
+  const allEvents = [...artifactEvents];
+  explicitEvents.forEach((ee) => {
+    if (!allEvents.find((ae) => ae.event === ee.event && ae.timestamp === ee.timestamp)) {
+      allEvents.push(ee);
+    }
+  });
+  allEvents.sort((a, b) => {
+    const ta = parseIso(a.timestamp) || 0;
+    const tb = parseIso(b.timestamp) || 0;
+    return ta - tb;
+  });
+
+  // First-useful-action from explicit events
+  const fuaEvent = explicitByEvent["first_useful_action"];
+  const activationEvent = allEvents.find((e) => e.event === "activation_completed");
+  const timeToFirstUsefulActionMs = fuaEvent && activationEvent
+    ? diffMs(activationEvent.timestamp, fuaEvent.timestamp)
+    : null;
+
+  const derived = deriveTimingSummary(allEvents);
+  derived.timeToFirstUsefulActionMs = timeToFirstUsefulActionMs;
+
+  const caveats = [
+    "Timing is evidence, not savings. Duration does not automatically mean time saved.",
+    "Activation timing measures readiness readiness, not time saved versus a baseline.",
+    "Timestamps from file mtimes may be imprecise for files updated outside Avorelo.",
+  ];
+
+  return {
+    schemaVersion: SCHEMA_VERSION,
+    contract: CONTRACT,
+    timingId,
+    createdAt,
+    cwd,
+    events: allEvents,
+    derived,
+    confidence: allEvents.length >= 3 ? "medium" : "low",
+    caveats,
+    redacted: true,
+  };
+}
+
+// ── Write / read ───────────────────────────────────────────────────────────────
+
+function writeSessionTiming(cwd, timing) {
+  const latestPath = path.resolve(cwd, SESSION_TIMING_LATEST_REL);
+  ensureDirFor(latestPath);
+  fs.writeFileSync(latestPath, JSON.stringify(timing, null, 2), "utf8");
+}
+
+function readSessionTiming(cwd) {
+  const latestPath = path.resolve(cwd, SESSION_TIMING_LATEST_REL);
+  return safeReadJson(latestPath);
+}
+
+// ── Text format ────────────────────────────────────────────────────────────────
+
+function formatSessionTimingText(timing) {
+  if (!timing) return "Session timing unavailable.\n";
+  const d = timing.derived;
+  const fmtMs = (ms) => ms === null ? "unavailable" : ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+  const lines = [
+    "Avorelo Session Timing",
+    "",
+    `  Events recorded: ${timing.events.length}`,
+    `  Confidence:      ${timing.confidence}`,
+    "",
+    `  Time to handoff:       ${fmtMs(d.timeToHandoffMs)}`,
+    `  Time to dashboard:     ${fmtMs(d.timeToDashboardReadyMs)}`,
+    `  Time to proof:         ${fmtMs(d.timeToProofMs)}`,
+    `  Session duration:      ${fmtMs(d.sessionDurationMs)}`,
+    d.timeToFirstUsefulActionMs !== null
+      ? `  First useful action:   ${fmtMs(d.timeToFirstUsefulActionMs)}`
+      : null,
+    "",
+    "  Note: Timing is evidence — not savings. No time-saved claim is made from duration alone.",
+    "",
+  ].filter((l) => l !== null);
+  return lines.join("\n");
+}
+
+module.exports = {
+  CONTRACT,
+  SESSION_TIMING_LATEST_REL,
+  SESSION_TIMING_EVENTS_REL,
+  buildSessionTimingSummary,
+  writeSessionTiming,
+  readSessionTiming,
+  recordTimingEvent,
+  formatSessionTimingText,
+};