@shadowforge0/aquifer-memory 1.8.0 → 1.9.0

package/core/finalization-inspector.js

@@ -0,0 +1,164 @@
+'use strict';
+
+function parseJsonObject(value, fallback = {}) {
+  if (value === null || value === undefined) return fallback;
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value);
+      return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : fallback;
+    } catch {
+      return fallback;
+    }
+  }
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : fallback;
+}
+
+function uniquePresent(values) {
+  return [...new Set(values.filter(value => value !== null && value !== undefined && value !== ''))];
+}
+
+function hashPrefix(value) {
+  if (!value) return null;
+  return String(value).slice(0, 12);
+}
+
+function countBy(rows = [], field, fallback = 'unknown') {
+  const counts = {};
+  for (const row of rows) {
+    const key = (row && row[field]) || fallback;
+    counts[key] = (counts[key] || 0) + 1;
+  }
+  return counts;
+}
+
+function countEvidenceRefs(candidateRows = [], envelope = {}) {
+  let total = 0;
+  for (const row of candidateRows) {
+    const provenance = parseJsonObject(row.provenance, {});
+    const refs = provenance.evidenceRefs || provenance.evidence_refs;
+    if (Array.isArray(refs)) total += refs.length;
+  }
+  const envelopeCandidates = Array.isArray(envelope.candidates) ? envelope.candidates : [];
+  for (const candidate of envelopeCandidates) {
+    const refs = candidate && (candidate.evidenceRefs || candidate.evidence_refs);
+    if (Array.isArray(refs)) total += refs.length;
+  }
+  return total;
+}
+
+function summarizeFinalizationListRow(row = {}) {
+  const envelope = parseJsonObject(row.candidate_envelope, {});
+  const candidateCount = Number.isFinite(row.candidate_count)
+    ? row.candidate_count
+    : (Array.isArray(envelope.candidates) ? envelope.candidates.length : 0);
+  return {
+    id: row.id,
+    status: row.status,
+    sessionId: row.session_id,
+    agentId: row.agent_id,
+    source: row.source,
+    host: row.host,
+    mode: row.mode,
+    phase: row.phase,
+    transcriptHashPrefix: hashPrefix(row.transcript_hash),
+    finalizerModel: row.finalizer_model || null,
+    scopeKind: row.scope_kind || null,
+    scopeKey: row.scope_key || null,
+    contextKey: row.context_key || null,
+    topicKey: row.topic_key || null,
+    candidateEnvelopeHash: row.candidate_envelope_hash || null,
+    candidateEnvelopeVersion: row.candidate_envelope_version || envelope.version || null,
+    candidateCount,
+    error: row.error || null,
+    claimedAt: row.claimed_at || null,
+    finalizedAt: row.finalized_at || null,
+    createdAt: row.created_at || null,
+    updatedAt: row.updated_at || null,
+  };
+}
+
+function summarizeCandidateRow(row = {}) {
+  return {
+    id: row.id,
+    index: row.candidate_index,
+    action: row.action,
+    reason: row.reason || null,
+    memoryType: row.memory_type || null,
+    canonicalKey: row.canonical_key || null,
+    summary: row.summary || null,
+    memoryRecordId: row.memory_record_id || null,
+    factAssertionId: row.fact_assertion_id || null,
+    candidateHash: row.candidate_hash || null,
+    createdAt: row.created_at || null,
+    updatedAt: row.updated_at || null,
+  };
+}
+
+function summarizeCandidateCounts(candidateRows = [], envelope = {}) {
+  const counts = countBy(candidateRows, 'action');
+  const envelopeCandidateCount = Array.isArray(envelope.candidates) ? envelope.candidates.length : 0;
+  return {
+    total: candidateRows.length || envelopeCandidateCount,
+    promote: counts.promote || 0,
+    quarantine: counts.quarantine || 0,
+    skip: (counts.skip || 0) + (counts.skipped || 0),
+    supersede: counts.supersede || 0,
+    error: counts.error || 0,
+    actionCounts: counts,
+    reasons: countBy(candidateRows, 'reason'),
+  };
+}
+
+function buildFinalizationInspection(row = {}, candidateRows = [], lineageSummary = {}) {
+  const envelope = parseJsonObject(row.candidate_envelope, {});
+  const memoryResult = parseJsonObject(row.memory_result, {});
+  const coverage = parseJsonObject(row.coverage, {});
+  const metadata = parseJsonObject(row.metadata, {});
+  const candidates = candidateRows.map(summarizeCandidateRow);
+  const memoryRecordIds = uniquePresent([
+    ...(Array.isArray(lineageSummary.memoryRecordIds) ? lineageSummary.memoryRecordIds : []),
+    ...candidates.map(candidate => candidate.memoryRecordId),
+  ]);
+  const factAssertionIds = uniquePresent([
+    ...(Array.isArray(lineageSummary.factAssertionIds) ? lineageSummary.factAssertionIds : []),
+    ...candidates.map(candidate => candidate.factAssertionId),
+  ]);
+  const evidenceRefCount = Number.isFinite(lineageSummary.evidenceRefCount)
+    ? lineageSummary.evidenceRefCount
+    : countEvidenceRefs(candidateRows, envelope);
+  const evidenceItemCount = Number.isFinite(lineageSummary.evidenceItemCount)
+    ? lineageSummary.evidenceItemCount
+    : 0;
+
+  return {
+    readOnly: true,
+    finalization: summarizeFinalizationListRow(row),
+    review: {
+      humanReviewText: row.human_review_text || '',
+      sessionStartText: row.session_start_text || '',
+    },
+    memoryResult,
+    candidateEnvelope: {
+      version: row.candidate_envelope_version || envelope.version || null,
+      hash: row.candidate_envelope_hash || null,
+      candidateCount: Array.isArray(envelope.candidates) ? envelope.candidates.length : 0,
+      coverage,
+    },
+    candidateSummary: summarizeCandidateCounts(candidateRows, envelope),
+    lineage: {
+      memoryRecordIds,
+      factAssertionIds,
+      evidenceRefCount,
+      evidenceItemCount,
+    },
+    safety: {
+      safetyGate: metadata.safetyGate || metadata.safety_gate || null,
+    },
+    candidates,
+  };
+}
+
+module.exports = {
+  buildFinalizationInspection,
+  summarizeFinalizationListRow,
+};