@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

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,
+};

package/core/finalization-review.js

@@ -1,40 +1,19 @@
 'use strict';
 
-const TYPE_LABELS = {
-  state: '狀態',
-  decision: '決策',
-  fact: '事實',
-  preference: '偏好',
-  constraint: '限制',
-  entity_note: '註記',
-  open_loop: '未完成',
-  conclusion: '判斷',
-};
-
-const SESSION_START_TYPE_PRIORITY = {
-  state: 0,
-  open_loop: 1,
-  constraint: 2,
-  preference: 3,
-  decision: 4,
-  fact: 5,
-  conclusion: 6,
-  entity_note: 7,
-};
-
-const AUTHORITY_PRIORITY = {
-  user_explicit: 0,
-  executable_evidence: 1,
-  manual: 2,
-  system: 3,
-  verified_summary: 4,
-  llm_inference: 5,
-  raw_transcript: 6,
-};
+const {
+  assistantShapingMetadata,
+  authoritySortPriority,
+  memoryTypeBootstrapPriority,
+  memoryTypeLabel,
+} = require('./memory-type-policy');
 
 const MEMORY_KEYS = [
   'summary',
   'title',
+  'guidance',
+  'policy',
+  'boundary',
+  'rule',
   'decision',
   'item',
   'conclusion',
@@ -49,13 +28,15 @@ const MEMORY_KEYS = [
 ];
 
 const STRUCTURED_FIELDS = [
+  ['assistant_shaping', 'assistant_shaping'],
+  ['assistant_shaping_memories', 'assistant_shaping'],
+  ['constraints', 'constraint'],
   ['states', 'state'],
   ['state', 'state'],
   ['decisions', 'decision'],
+  ['preferences', 'preference'],
   ['important_facts', 'fact'],
   ['facts', 'fact'],
-  ['preferences', 'preference'],
-  ['constraints', 'constraint'],
   ['conclusions', 'conclusion'],
   ['entity_notes', 'entity_note'],
   ['open_loops', 'open_loop'],
@@ -105,7 +86,7 @@ function memoryTypeOf(value) {
 }
 
 function labelFor(type) {
-  return TYPE_LABELS[type] || TYPE_LABELS[String(type || '').toLowerCase()] || '記憶';
+  return memoryTypeLabel(type);
 }
 
 function pushUnique(out, text) {
@@ -122,6 +103,43 @@ function asLine(type, text, suffix = '') {
   return `${labelFor(type)}：${body}${suffix}`;
 }
 
+function shapingSuffix(type, value = {}) {
+  if (String(type || '').toLowerCase() !== 'assistant_shaping') return '';
+  const metadata = assistantShapingMetadata(value);
+  if (metadata.length === 0) return '';
+  return `（${metadata.map(([key, text]) => `${key}: ${text}`).join('，')}）`;
+}
+
+function reviewTypePriority(type) {
+  return memoryTypeBootstrapPriority(type);
+}
+
+function reviewAuthorityPriority(authority) {
+  return authoritySortPriority(authority);
+}
+
+function reviewAcceptedAt(value) {
+  return Date.parse(value || '') || 0;
+}
+
+function sortReviewEntries(entries = []) {
+  return entries.slice().sort((left, right) => {
+    const leftType = reviewTypePriority(left.type);
+    const rightType = reviewTypePriority(right.type);
+    if (leftType !== rightType) return leftType - rightType;
+
+    const leftAuthority = reviewAuthorityPriority(left.authority);
+    const rightAuthority = reviewAuthorityPriority(right.authority);
+    if (leftAuthority !== rightAuthority) return leftAuthority - rightAuthority;
+
+    const leftAcceptedAt = reviewAcceptedAt(left.acceptedAt);
+    const rightAcceptedAt = reviewAcceptedAt(right.acceptedAt);
+    if (leftAcceptedAt !== rightAcceptedAt) return rightAcceptedAt - leftAcceptedAt;
+
+    return (left.index ?? 0) - (right.index ?? 0);
+  });
+}
+
 function truncate(text, max = 220) {
   const normalized = sanitizeHumanText(text);
   if (normalized.length <= max) return normalized;
@@ -129,6 +147,8 @@ function truncate(text, max = 220) {
 }
 
 function addStructuredItems(out, structuredSummary = {}, filter = null) {
+  const entries = [];
+  let index = 0;
   for (const [field, type] of STRUCTURED_FIELDS) {
     if (filter && !filter(type)) continue;
     const items = Array.isArray(structuredSummary[field]) ? structuredSummary[field] : [];
@@ -138,19 +158,45 @@ function addStructuredItems(out, structuredSummary = {}, filter = null) {
       const owner = type === 'open_loop' && item && typeof item === 'object' && normalizeText(item.owner)
         ? `（owner: ${normalizeText(item.owner)}）`
         : '';
-      pushUnique(out, asLine(type, text, owner));
+      entries.push({
+        type,
+        text,
+        suffix: owner || shapingSuffix(type, item),
+        authority: item && typeof item === 'object' ? (item.authority || item.payload?.authority) : null,
+        acceptedAt: item && typeof item === 'object'
+          ? (item.acceptedAt || item.accepted_at || item.payload?.acceptedAt || item.payload?.accepted_at)
+          : null,
+        index: index++,
+      });
     }
   }
+  for (const entry of sortReviewEntries(entries)) {
+    pushUnique(out, asLine(entry.type, entry.text, entry.suffix));
+  }
 }
 
 function promotedMemoryLines(memoryResults = []) {
-  const lines = [];
+  const entries = [];
+  let index = 0;
   for (const result of memoryResults || []) {
     if (!result || result.action !== 'promote') continue;
     const memory = result.memory || result.record || result.candidate || {};
     const type = memoryTypeOf(memory);
     if (type === 'open_loop') continue;
-    pushUnique(lines, asLine(type, firstText(memory)));
+    const text = firstText(memory);
+    if (!text) continue;
+    entries.push({
+      type,
+      text,
+      suffix: shapingSuffix(type, memory),
+      authority: memory.authority,
+      acceptedAt: memory.acceptedAt || memory.accepted_at,
+      index: index++,
+    });
+  }
+  const lines = [];
+  for (const entry of sortReviewEntries(entries)) {
+    pushUnique(lines, asLine(entry.type, entry.text, entry.suffix));
   }
   return lines;
 }
@@ -285,12 +331,12 @@ function buildSessionStartContext(records = [], opts = {}) {
   }
 
   active.sort((a, b) => {
-    const aType = SESSION_START_TYPE_PRIORITY[memoryTypeOf(a.record)] ?? 99;
-    const bType = SESSION_START_TYPE_PRIORITY[memoryTypeOf(b.record)] ?? 99;
+    const aType = memoryTypeBootstrapPriority(memoryTypeOf(a.record));
+    const bType = memoryTypeBootstrapPriority(memoryTypeOf(b.record));
     if (aType !== bType) return aType - bType;
 
-    const aAuth = AUTHORITY_PRIORITY[a.record.authority] ?? 99;
-    const bAuth = AUTHORITY_PRIORITY[b.record.authority] ?? 99;
+    const aAuth = authoritySortPriority(a.record.authority);
+    const bAuth = authoritySortPriority(b.record.authority);
     if (aAuth !== bAuth) return aAuth - bAuth;
 
     const aAccepted = Date.parse(a.record.acceptedAt || a.record.accepted_at || '') || 0;
@@ -302,7 +348,7 @@ function buildSessionStartContext(records = [], opts = {}) {
   const lines = [];
   for (const { record } of active.slice(0, limit)) {
     const type = memoryTypeOf(record);
-    pushUnique(lines, asLine(type, firstText(record)));
+    pushUnique(lines, asLine(type, firstText(record), shapingSuffix(type, record)));
   }
   let selected = lines;
   let text = `下一段只需要帶：\n${linesOrNone(selected)}\n`;