@goodandready/dsh-approval-gate 0.1.21 → 0.1.23

package/lib/ledger.js

@@ -1,164 +1,264 @@
-// lib/ledger.js
-// Quality and Anomaly Ledger for dsh-approval-gate (#88).
-// Tracks session health, consecutive denials, and execution anomalies.
-
-export const MAX_LEDGER_EVENTS_PER_SESSION = 50;
-
-/**
- * @typedef {Object} LedgerEvent
- * @property {number} timestamp
- * @property {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
- * @property {string} reason
- * @property {string} [detail]
- * @property {string} [tool]
- */
-
-/**
- * @typedef {Object} SessionLedger
- * @property {string} sessionId
- * @property {number} totalDecisions
- * @property {number} allowedCount
- * @property {number} deniedCount
- * @property {number} askCount
- * @property {number} anomalyCount
- * @property {number} consecutiveDenies
- * @property {boolean} breakerTripped
- * @property {boolean} retryExhausted
- * @property {LedgerEvent[]} recentEvents
- */
-
-export class QualityLedger {
-  constructor() {
-    /** @type {Map<string, SessionLedger>} */
-    this.sessions = new Map();
-  }
-
-  /**
-   * @private
-   */
-  _getOrCreate(sessionId) {
-    const key = sessionId || "default";
-    let ledger = this.sessions.get(key);
-    if (!ledger) {
-      ledger = {
-        sessionId: key,
-        totalDecisions: 0,
-        allowedCount: 0,
-        deniedCount: 0,
-        askCount: 0,
-        anomalyCount: 0,
-        consecutiveDenies: 0,
-        breakerTripped: false,
-        retryExhausted: false,
-        recentEvents: [],
-      };
-      this.sessions.set(key, ledger);
-    }
-    return ledger;
-  }
-
-  /**
-   * Record a decision or system event in the ledger.
-   *
-   * @param {string} sessionId
-   * @param {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
-   * @param {{ reason?: string, detail?: string, tool?: string }} [details]
-   */
-  record(sessionId, type, details = {}) {
-    const ledger = this._getOrCreate(sessionId);
-    const now = Date.now();
-
-    const event = {
-      timestamp: now,
-      type,
-      reason: details.reason || "",
-      detail: details.detail ? String(details.detail).slice(0, 200) : undefined,
-      tool: details.tool || "",
-    };
-
-    ledger.recentEvents.push(event);
-    if (ledger.recentEvents.length > MAX_LEDGER_EVENTS_PER_SESSION) {
-      ledger.recentEvents.shift();
-    }
-
-    if (type === "allow") {
-      ledger.totalDecisions += 1;
-      ledger.allowedCount += 1;
-      ledger.consecutiveDenies = 0;
-    } else if (type === "deny") {
-      ledger.totalDecisions += 1;
-      ledger.deniedCount += 1;
-      ledger.consecutiveDenies += 1;
-      if (ledger.consecutiveDenies > 1) {
-        ledger.anomalyCount += 1;
-      }
-    } else if (type === "ask") {
-      ledger.totalDecisions += 1;
-      ledger.askCount += 1;
-    } else if (type === "exhaustion") {
-      ledger.retryExhausted = true;
-      ledger.anomalyCount += 1;
-    } else if (type === "breaker") {
-      ledger.breakerTripped = true;
-      ledger.anomalyCount += 1;
-    } else if (type === "error") {
-      ledger.anomalyCount += 1;
-    }
-  }
-
-  /**
-   * Returns a quality summary for the session.
-   *
-   * @param {string} sessionId
-   * @returns {{
-   *   sessionId: string,
-   *   totalDecisions: number,
-   *   allowedCount: number,
-   *   deniedCount: number,
-   *   askCount: number,
-   *   anomalyCount: number,
-   *   consecutiveDenies: number,
-   *   qualityScore: number,
-   *   degradationWarning: boolean,
-   *   recentEvents: LedgerEvent[]
-   * }}
-   */
-  getSummary(sessionId) {
-    const ledger = this._getOrCreate(sessionId);
-    const total = ledger.totalDecisions;
-
-    // Quality score: 1.0 down towards 0.0 based on denial & anomaly ratio
-    let score = 1.0;
-    if (total > 0) {
-      const penalty = (ledger.deniedCount * 0.2 + ledger.anomalyCount * 0.3) / total;
-      score = Math.max(0, Math.min(1.0, 1.0 - penalty));
-    }
-
-    const degradationWarning = ledger.consecutiveDenies >= 2 ||
-      ledger.retryExhausted ||
-      ledger.breakerTripped ||
-      (total >= 3 && ledger.deniedCount / total >= 0.5);
-
-    return {
-      sessionId: ledger.sessionId,
-      totalDecisions: ledger.totalDecisions,
-      allowedCount: ledger.allowedCount,
-      deniedCount: ledger.deniedCount,
-      askCount: ledger.askCount,
-      anomalyCount: ledger.anomalyCount,
-      consecutiveDenies: ledger.consecutiveDenies,
-      qualityScore: Number(score.toFixed(2)),
-      degradationWarning,
-      recentEvents: ledger.recentEvents.map((e) => ({ ...e })),
-    };
-  }
-
-  reset(sessionId) {
-    const key = sessionId || "default";
-    this.sessions.delete(key);
-  }
-
-  clear() {
-    this.sessions.clear();
-  }
-}
+// lib/ledger.js
+// Quality and Anomaly Ledger for dsh-approval-gate (#88, #73).
+// Tracks session health, consecutive denials, and execution anomalies with schema versioning.
+
+export const MAX_LEDGER_EVENTS_PER_SESSION = 50;
+
+export const CURRENT_SCHEMA_VERSION = 3;
+export const SUPPORTED_SCHEMA_VERSIONS = Object.freeze([1, 2, 3]);
+
+/**
+ * Migrates a verdict record across schema versions (v1 -> v2 -> v3) (#73).
+ * - v1: { id, verdict, ruleId, timestamp, riskBucket }
+ * - v2: + { reviewDecision, bandVerdict, mitigation, auditSummary }
+ * - v3: + { track, dossier, driftScore, driftWarning, schema_version: 3 }
+ *
+ * @param {Record<string, any>} record
+ * @param {number} [targetVersion=CURRENT_SCHEMA_VERSION]
+ * @returns {Record<string, any>}
+ */
+export function migrateVerdictRecord(record, targetVersion = CURRENT_SCHEMA_VERSION) {
+  if (!record || typeof record !== "object") return record;
+
+  let currentVersion = record.schema_version;
+  if (!currentVersion) {
+    // Infer version from fields
+    if (record.reviewDecision !== undefined || record.bandVerdict !== undefined) {
+      currentVersion = 2;
+    } else {
+      currentVersion = 1;
+    }
+  }
+
+  let migrated = { ...record };
+
+  // v1 -> v2 migration
+  if (currentVersion < 2 && targetVersion >= 2) {
+    migrated.reviewDecision = migrated.reviewDecision || migrated.verdict || "allow";
+    migrated.bandVerdict = migrated.bandVerdict || migrated.verdict || "allow";
+    migrated.mitigation = migrated.mitigation || null;
+    migrated.auditSummary = migrated.auditSummary || null;
+    migrated.schema_version = 2;
+    currentVersion = 2;
+  }
+
+  // v2 -> v3 migration
+  if (currentVersion < 3 && targetVersion >= 3) {
+    migrated.track = migrated.track || "external";
+    migrated.dossier = migrated.dossier || null;
+    migrated.driftScore = typeof migrated.driftScore === "number" ? migrated.driftScore : 0;
+    migrated.driftWarning = Boolean(migrated.driftWarning);
+    migrated.schema_version = 3;
+    currentVersion = 3;
+  }
+
+  migrated.schema_version = currentVersion;
+  return migrated;
+}
+
+/**
+ * @typedef {Object} LedgerEvent
+ * @property {number} timestamp
+ * @property {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
+ * @property {string} reason
+ * @property {string} [detail]
+ * @property {string} [tool]
+ * @property {number} [schema_version]
+ */
+
+/**
+ * @typedef {Object} SessionLedger
+ * @property {string} sessionId
+ * @property {number} totalDecisions
+ * @property {number} allowedCount
+ * @property {number} deniedCount
+ * @property {number} askCount
+ * @property {number} anomalyCount
+ * @property {number} consecutiveDenies
+ * @property {boolean} breakerTripped
+ * @property {boolean} retryExhausted
+ * @property {LedgerEvent[]} recentEvents
+ */
+
+export class QualityLedger {
+  constructor() {
+    /** @type {Map<string, SessionLedger>} */
+    this.sessions = new Map();
+  }
+
+  /**
+   * @private
+   */
+  _getOrCreate(sessionId) {
+    const key = sessionId || "default";
+    let ledger = this.sessions.get(key);
+    if (!ledger) {
+      ledger = {
+        sessionId: key,
+        totalDecisions: 0,
+        allowedCount: 0,
+        deniedCount: 0,
+        askCount: 0,
+        anomalyCount: 0,
+        consecutiveDenies: 0,
+        breakerTripped: false,
+        retryExhausted: false,
+        recentEvents: [],
+      };
+      this.sessions.set(key, ledger);
+    }
+    return ledger;
+  }
+
+  /**
+   * Record a decision or system event in the ledger.
+   *
+   * @param {string} sessionId
+   * @param {string} type - "allow" | "deny" | "ask" | "exhaustion" | "breaker" | "error"
+   * @param {{ reason?: string, detail?: string, tool?: string, track?: string, dossier?: any }} [details]
+   */
+  record(sessionId, type, details = {}) {
+    const ledger = this._getOrCreate(sessionId);
+    const now = Date.now();
+
+    const rawEvent = {
+      timestamp: now,
+      type,
+      reason: details.reason || "",
+      detail: details.detail ? String(details.detail).slice(0, 200) : undefined,
+      tool: details.tool || "",
+      track: details.track,
+      dossier: details.dossier,
+      schema_version: CURRENT_SCHEMA_VERSION,
+    };
+
+    const event = migrateVerdictRecord(rawEvent, CURRENT_SCHEMA_VERSION);
+
+    ledger.recentEvents.push(event);
+    if (ledger.recentEvents.length > MAX_LEDGER_EVENTS_PER_SESSION) {
+      ledger.recentEvents.shift();
+    }
+
+    if (type === "allow") {
+      ledger.totalDecisions += 1;
+      ledger.allowedCount += 1;
+      ledger.consecutiveDenies = 0;
+    } else if (type === "deny") {
+      ledger.totalDecisions += 1;
+      ledger.deniedCount += 1;
+      ledger.consecutiveDenies += 1;
+      if (ledger.consecutiveDenies > 1) {
+        ledger.anomalyCount += 1;
+      }
+    } else if (type === "ask") {
+      ledger.totalDecisions += 1;
+      ledger.askCount += 1;
+    } else if (type === "exhaustion") {
+      ledger.retryExhausted = true;
+      ledger.anomalyCount += 1;
+    } else if (type === "breaker") {
+      ledger.breakerTripped = true;
+      ledger.anomalyCount += 1;
+    } else if (type === "error") {
+      ledger.anomalyCount += 1;
+    }
+  }
+
+  /**
+   * Returns a quality summary for the session.
+   *
+   * @param {string} sessionId
+   * @returns {{
+   *   sessionId: string,
+   *   totalDecisions: number,
+   *   allowedCount: number,
+   *   deniedCount: number,
+   *   askCount: number,
+   *   anomalyCount: number,
+   *   consecutiveDenies: number,
+   *   qualityScore: number,
+   *   degradationWarning: boolean,
+   *   recentEvents: LedgerEvent[]
+   * }}
+   */
+  getSummary(sessionId) {
+    const ledger = this._getOrCreate(sessionId);
+    const total = ledger.totalDecisions;
+
+    // Quality score: 1.0 down towards 0.0 based on denial & anomaly ratio
+    let score = 1.0;
+    if (total > 0) {
+      const penalty = (ledger.deniedCount * 0.2 + ledger.anomalyCount * 0.3) / total;
+      score = Math.max(0, Math.min(1.0, 1.0 - penalty));
+    }
+
+    const degradationWarning = ledger.consecutiveDenies >= 2 ||
+      ledger.retryExhausted ||
+      ledger.breakerTripped ||
+      (total >= 3 && ledger.deniedCount / total >= 0.5);
+
+    return {
+      sessionId: ledger.sessionId,
+      totalDecisions: ledger.totalDecisions,
+      allowedCount: ledger.allowedCount,
+      deniedCount: ledger.deniedCount,
+      askCount: ledger.askCount,
+      anomalyCount: ledger.anomalyCount,
+      consecutiveDenies: ledger.consecutiveDenies,
+      qualityScore: Number(score.toFixed(2)),
+      degradationWarning,
+      recentEvents: ledger.recentEvents.map((e) => ({ ...e })),
+    };
+  }
+
+  /**
+   * Serializes session ledger state with current schema version (#73).
+   * @param {string} sessionId
+   * @returns {Record<string, any>}
+   */
+  serializeSession(sessionId) {
+    const ledger = this._getOrCreate(sessionId);
+    return {
+      schema_version: CURRENT_SCHEMA_VERSION,
+      sessionId: ledger.sessionId,
+      totalDecisions: ledger.totalDecisions,
+      allowedCount: ledger.allowedCount,
+      deniedCount: ledger.deniedCount,
+      askCount: ledger.askCount,
+      anomalyCount: ledger.anomalyCount,
+      consecutiveDenies: ledger.consecutiveDenies,
+      breakerTripped: ledger.breakerTripped,
+      retryExhausted: ledger.retryExhausted,
+      recentEvents: ledger.recentEvents.map((e) => migrateVerdictRecord(e, CURRENT_SCHEMA_VERSION)),
+    };
+  }
+
+  /**
+   * Restores session ledger state from serialized data with automatic migration (#73).
+   * @param {Record<string, any>} data
+   */
+  deserializeSession(data) {
+    if (!data || !data.sessionId) return;
+    const ledger = this._getOrCreate(data.sessionId);
+    ledger.totalDecisions = data.totalDecisions || 0;
+    ledger.allowedCount = data.allowedCount || 0;
+    ledger.deniedCount = data.deniedCount || 0;
+    ledger.askCount = data.askCount || 0;
+    ledger.anomalyCount = data.anomalyCount || 0;
+    ledger.consecutiveDenies = data.consecutiveDenies || 0;
+    ledger.breakerTripped = Boolean(data.breakerTripped);
+    ledger.retryExhausted = Boolean(data.retryExhausted);
+    ledger.recentEvents = Array.isArray(data.recentEvents)
+      ? data.recentEvents.map((e) => migrateVerdictRecord(e, CURRENT_SCHEMA_VERSION))
+      : [];
+  }
+
+  reset(sessionId) {
+    const key = sessionId || "default";
+    this.sessions.delete(key);
+  }
+
+  clear() {
+    this.sessions.clear();
+  }
+}

package/lib/lineage.js

@@ -0,0 +1,182 @@
+// lib/lineage.js
+// Subagent hierarchy and parentSession lineage authority (#98).
+// Tracks session ancestry trees and propagates authority/policies down the lineage chain.
+
+export class LineageManager {
+  constructor() {
+    /** @type {Map<string, string>} childSessionId -> parentSessionId */
+    this.parentMap = new Map();
+    /** @type {Map<string, string>} childSessionId -> explicit rootSessionId */
+    this.rootMap = new Map();
+    /** @type {Map<string, Set<string>>} parentSessionId -> Set of childSessionIds */
+    this.childrenMap = new Map();
+  }
+
+  /**
+   * Registers parent-child session relationship.
+   * Prevents circular parent-child references.
+   *
+   * @param {string} childSessionId
+   * @param {string} parentSessionId
+   * @param {string} [rootSessionId]
+   * @returns {boolean} True if successfully registered, false if invalid or circular
+   */
+  registerLineage(childSessionId, parentSessionId, rootSessionId = null) {
+    if (!childSessionId || !parentSessionId) return false;
+    if (childSessionId === parentSessionId) return false;
+
+    // Check circular references: walking upwards from parent must not reach child
+    let curr = parentSessionId;
+    const visited = new Set([childSessionId]);
+    while (curr) {
+      if (visited.has(curr)) return false;
+      visited.add(curr);
+      curr = this.parentMap.get(curr);
+    }
+
+    this.parentMap.set(childSessionId, parentSessionId);
+    if (rootSessionId && rootSessionId !== childSessionId) {
+      this.rootMap.set(childSessionId, rootSessionId);
+    }
+
+    if (!this.childrenMap.has(parentSessionId)) {
+      this.childrenMap.set(parentSessionId, new Set());
+    }
+    this.childrenMap.get(parentSessionId).add(childSessionId);
+
+    return true;
+  }
+
+  /**
+   * Retrieves the direct parent session ID for a session.
+   * @param {string} sessionId
+   * @returns {string|null}
+   */
+  getParent(sessionId) {
+    if (!sessionId) return null;
+    return this.parentMap.get(sessionId) || null;
+  }
+
+  /**
+   * Retrieves the ultimate root session ID for a session.
+   * @param {string} sessionId
+   * @returns {string}
+   */
+  getRoot(sessionId) {
+    if (!sessionId) return "";
+    if (this.rootMap.has(sessionId)) {
+      return this.rootMap.get(sessionId);
+    }
+
+    let curr = sessionId;
+    const visited = new Set();
+    while (curr && !visited.has(curr)) {
+      visited.add(curr);
+      const parent = this.parentMap.get(curr);
+      if (!parent) break;
+      curr = parent;
+    }
+    return curr;
+  }
+
+  /**
+   * Returns ancestry array from current session up to root: [sessionId, parentId, ..., rootId].
+   * @param {string} sessionId
+   * @returns {string[]}
+   */
+  getLineage(sessionId) {
+    if (!sessionId) return [];
+    const chain = [];
+    let curr = sessionId;
+    const visited = new Set();
+
+    while (curr && !visited.has(curr)) {
+      visited.add(curr);
+      chain.push(curr);
+      curr = this.parentMap.get(curr);
+    }
+
+    return chain;
+  }
+
+  /**
+   * Checks whether ancestorSessionId is an ancestor of childSessionId.
+   * @param {string} childSessionId
+   * @param {string} ancestorSessionId
+   * @returns {boolean}
+   */
+  hasLineageAuthority(childSessionId, ancestorSessionId) {
+    if (!childSessionId || !ancestorSessionId) return false;
+    if (childSessionId === ancestorSessionId) return true;
+
+    const lineage = this.getLineage(childSessionId);
+    return lineage.includes(ancestorSessionId);
+  }
+
+  /**
+   * Resolves effective policy walking up the lineage hierarchy.
+   * Evaluates getPolicyFn(sessionId). If undefined or null, falls back to parent, then root.
+   *
+   * @param {string} sessionId
+   * @param {(id: string) => any} getPolicyFn
+   * @returns {any}
+   */
+  resolveEffectivePolicy(sessionId, getPolicyFn) {
+    if (!sessionId || typeof getPolicyFn !== "function") return null;
+
+    const lineage = this.getLineage(sessionId);
+    for (const sid of lineage) {
+      try {
+        const policy = getPolicyFn(sid);
+        if (policy !== undefined && policy !== null) {
+          return {
+            policy,
+            sourceSessionId: sid,
+            inherited: sid !== sessionId,
+          };
+        }
+      } catch {
+        // Continue upward traversal on error
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Removes tracking for a session and unlinks from its parent.
+   * @param {string} sessionId
+   * @returns {boolean}
+   */
+  clearSession(sessionId) {
+    if (!sessionId) return false;
+    const parent = this.parentMap.get(sessionId);
+    if (parent && this.childrenMap.has(parent)) {
+      this.childrenMap.get(parent).delete(sessionId);
+    }
+    this.parentMap.delete(sessionId);
+    this.rootMap.delete(sessionId);
+    this.childrenMap.delete(sessionId);
+    return true;
+  }
+
+  /**
+   * Clears all lineage mappings.
+   */
+  clearAll() {
+    this.parentMap.clear();
+    this.rootMap.clear();
+    this.childrenMap.clear();
+  }
+
+  /**
+   * Returns current statistics for debugging and auditing.
+   * @returns {{ trackedSessions: number, rootSessions: number }}
+   */
+  getStats() {
+    return {
+      trackedSessions: this.parentMap.size,
+      parentCount: this.childrenMap.size,
+    };
+  }
+}

package/lib/measure-kinds.js

@@ -56,6 +56,9 @@ const SYSTEM_LEVEL_TOOLS = new Set([
  */
 export function classifyMeasureKind(execution, context = {}) {
   if (!execution) return MEASURE_KINDS.LOCAL_SINGLE;
+  if (typeof execution === "string") {
+    execution = { name: "bash", arguments: { command: execution } };
+  }
 
   const toolName = execution.name || execution.tool || "";
   const args = execution.arguments || {};