@shadowforge0/aquifer-memory 1.8.1 → 1.9.0

package/core/memory-review.js

@@ -0,0 +1,891 @@
+'use strict';
+
+const { resolveApplicableRecords } = require('./memory-bootstrap');
+
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+const MAX_FETCH_LIMIT = 400;
+const DEFAULT_VISIBILITY = 'either';
+const DEFAULT_RESOLUTION_LIMIT = 10;
+const RESOLUTION_ACTIONS = ['resolved', 'ignored', 'deferred'];
+
+const ISSUE_FEEDBACK_TYPES = [
+  'incorrect',
+  'sensitive',
+  'scope_mismatch',
+  'authority_mismatch',
+  'stale',
+  'expired',
+  'conflict',
+  'superseded',
+  'archive',
+  'irrelevant',
+];
+
+const SEVERITY_SCORE = {
+  incorrect: 100,
+  sensitive: 95,
+  scope_mismatch: 85,
+  authority_mismatch: 80,
+  stale: 75,
+  expired: 70,
+  conflict: 65,
+  superseded: 60,
+  archive: 50,
+  irrelevant: 40,
+};
+
+function clampLimit(value, fallback = DEFAULT_LIMIT) {
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.min(MAX_LIMIT, parsed);
+}
+
+function parseCounts(value) {
+  if (!value || typeof value !== 'object') return {};
+  return Object.fromEntries(
+    Object.entries(value)
+      .map(([key, count]) => [key, Number.parseInt(count, 10) || 0])
+      .filter(([, count]) => count > 0)
+      .sort(([left], [right]) => left.localeCompare(right)),
+  );
+}
+
+function severityCaseSql() {
+  const clauses = Object.entries(SEVERITY_SCORE)
+    .map(([type, score]) => `WHEN '${type}' THEN ${score}`)
+    .join(' ');
+  return `CASE feedback_type ${clauses} ELSE 0 END`;
+}
+
+function normalizeFeedbackType(value) {
+  if (!value || value === true) return null;
+  const type = String(value).trim();
+  return type || null;
+}
+
+function normalizeList(value) {
+  if (Array.isArray(value)) return value.map(String).map(s => s.trim()).filter(Boolean);
+  if (!value || value === true) return [];
+  return String(value).split(',').map(s => s.trim()).filter(Boolean);
+}
+
+function normalizeVisibility(value) {
+  if (!value || value === true) return DEFAULT_VISIBILITY;
+  const visibility = String(value).trim();
+  if (!['bootstrap', 'recall', 'either', 'both'].includes(visibility)) {
+    throw new Error('review visibility must be one of: bootstrap, recall, either, both');
+  }
+  return visibility;
+}
+
+function normalizeIsoOrNull(value) {
+  if (!value || value === true) return null;
+  const date = new Date(value);
+  return Number.isFinite(date.getTime()) ? date.toISOString() : null;
+}
+
+function requireIso(value, label) {
+  const iso = normalizeIsoOrNull(value);
+  if (!iso) throw new Error(`${label} must be a valid ISO timestamp`);
+  return iso;
+}
+
+function normalizeReason(value) {
+  if (!value || value === true) return null;
+  const text = String(value).replace(/\s+/g, ' ').trim();
+  if (!text) return null;
+  return text.length > 200 ? `${text.slice(0, 197)}...` : text;
+}
+
+function normalizeActorKind(value) {
+  if (!value || value === true) return 'user';
+  const actorKind = String(value).trim();
+  if (!['user', 'agent', 'system', 'curator'].includes(actorKind)) {
+    throw new Error('review resolution actorKind must be one of: user, agent, system, curator');
+  }
+  return actorKind;
+}
+
+function normalizeResolution(value) {
+  if (!value || value === true) throw new Error('review.resolve requires resolution');
+  const resolution = String(value).trim();
+  if (!RESOLUTION_ACTIONS.includes(resolution)) {
+    throw new Error('review resolution must be one of: resolved, ignored, deferred');
+  }
+  return resolution;
+}
+
+function scopePathFromOpts(opts = {}) {
+  const path = normalizeList(opts.activeScopePath);
+  if (path.length > 0) return path;
+  const key = opts.scopeKey || opts.activeScopeKey || 'global';
+  return [String(key)];
+}
+
+function scopeContextFromOpts(opts = {}) {
+  const activeScopePath = scopePathFromOpts(opts);
+  return {
+    activeScopeKey: opts.activeScopeKey || opts.scopeKey || activeScopePath[activeScopePath.length - 1] || 'global',
+    activeScopePath,
+  };
+}
+
+function issueTypes(input) {
+  return Array.isArray(input) && input.length > 0
+    ? input.map(String)
+    : ISSUE_FEEDBACK_TYPES.slice();
+}
+
+function issueTypesForResolution(input = {}) {
+  return issueTypes(input.issueFeedbackTypes);
+}
+
+function severityLabel(score) {
+  const value = Number.parseInt(score, 10) || 0;
+  if (value >= 85) return 'high';
+  if (value >= 65) return 'medium';
+  return 'low';
+}
+
+function normalizeQueueRow(row = {}) {
+  const severityScore = Number.parseInt(row.severity_score, 10) || 0;
+  const resolution = normalizeResolutionRow({
+    id: row.resolution_id,
+    memory_id: row.resolution_memory_id || row.memory_id,
+    canonical_key: row.resolution_canonical_key || row.canonical_key,
+    scope_id: row.resolution_scope_id || row.scope_id,
+    resolution: row.resolution,
+    reason: row.resolution_reason,
+    actor_kind: row.resolution_actor_kind,
+    actor_id: row.resolution_actor_id,
+    issue_feedback_types: row.resolution_issue_feedback_types,
+    resolved_through_feedback_id: row.resolution_resolved_through_feedback_id,
+    resolved_through_feedback_at: row.resolution_resolved_through_feedback_at,
+    defer_until: row.resolution_defer_until,
+    resolved_at: row.resolved_at,
+    created_at: row.resolution_created_at,
+  });
+  return {
+    memoryId: row.memory_id === null || row.memory_id === undefined ? null : String(row.memory_id),
+    canonicalKey: row.canonical_key,
+    memoryType: row.memory_type,
+    status: row.status,
+    visibility: {
+      bootstrap: row.visible_in_bootstrap === true,
+      recall: row.visible_in_recall === true,
+    },
+    authority: row.authority || null,
+    acceptedAt: row.accepted_at || null,
+    updatedAt: row.updated_at || null,
+    scope: {
+      id: row.scope_id === null || row.scope_id === undefined ? null : String(row.scope_id),
+      kind: row.scope_kind || null,
+      key: row.scope_key || null,
+      inheritanceMode: row.inheritance_mode || null,
+    },
+    feedbackCounts: parseCounts(row.feedback_counts),
+    feedbackCount: Number.parseInt(row.feedback_count, 10) || 0,
+    issueCount: Number.parseInt(row.issue_count, 10) || 0,
+    matchingFeedbackCount: Number.parseInt(row.matching_feedback_count, 10) || 0,
+    severity: severityLabel(severityScore),
+    severityScore,
+    firstFeedbackAt: row.first_feedback_at || null,
+    latestFeedbackAt: row.latest_feedback_at || null,
+    latestIssueFeedbackId: row.latest_issue_feedback_id === null || row.latest_issue_feedback_id === undefined
+      ? null : String(row.latest_issue_feedback_id),
+    latestIssueFeedbackAt: row.latest_issue_feedback_at || null,
+    resolution,
+    queueState: row.queue_state || (resolution ? resolution.resolution : 'open'),
+  };
+}
+
+function normalizeFeedbackEvent(row = {}) {
+  return {
+    id: row.id === null || row.id === undefined ? null : String(row.id),
+    feedbackType: row.feedback_type,
+    actorKind: row.actor_kind || null,
+    actorId: row.actor_id || null,
+    createdAt: row.created_at || null,
+  };
+}
+
+function normalizeResolutionRow(row = {}) {
+  if (!row || row.id === null || row.id === undefined) return null;
+  return {
+    id: String(row.id),
+    memoryId: row.memory_id === null || row.memory_id === undefined ? null : String(row.memory_id),
+    canonicalKey: row.canonical_key || null,
+    scopeId: row.scope_id === null || row.scope_id === undefined ? null : String(row.scope_id),
+    resolution: row.resolution,
+    reason: row.reason || null,
+    actorKind: row.actor_kind || null,
+    actorId: row.actor_id || null,
+    issueFeedbackTypes: Array.isArray(row.issue_feedback_types) ? row.issue_feedback_types : [],
+    resolvedThroughFeedbackId: row.resolved_through_feedback_id === null || row.resolved_through_feedback_id === undefined
+      ? null : String(row.resolved_through_feedback_id),
+    resolvedThroughFeedbackAt: row.resolved_through_feedback_at || null,
+    deferUntil: row.defer_until || null,
+    resolvedAt: row.resolved_at || null,
+    createdAt: row.created_at || null,
+  };
+}
+
+function compareIso(left, right) {
+  if (!left || !right) return null;
+  const leftTime = new Date(left).getTime();
+  const rightTime = new Date(right).getTime();
+  if (!Number.isFinite(leftTime) || !Number.isFinite(rightTime)) return null;
+  if (leftTime === rightTime) return 0;
+  return leftTime > rightTime ? 1 : -1;
+}
+
+function createMemoryReview({ pool, schema, defaultTenantId }) {
+  function assertPool() {
+    if (!pool || typeof pool.query !== 'function') {
+      throw new Error('memory.review requires a pool with query(sql, params)');
+    }
+  }
+
+  function buildQueueQuery(opts = {}) {
+    const params = [opts.tenantId || defaultTenantId, issueTypes(opts.issueFeedbackTypes)];
+    const filters = [];
+    const feedbackType = normalizeFeedbackType(opts.feedbackType);
+    const memoryTypes = normalizeList(opts.memoryType || opts.memoryTypes);
+    const visibility = normalizeVisibility(opts.visibility);
+    const scopeContext = scopeContextFromOpts(opts);
+    const severityExpr = severityCaseSql();
+    const includeResolved = opts.includeResolved === true;
+    const feedbackFilters = [];
+    let matchTypeExpr = `NULL::text`;
+
+    if (opts.dateFrom) {
+      params.push(String(opts.dateFrom));
+      feedbackFilters.push(`created_at >= $${params.length}`);
+    }
+    if (opts.dateTo) {
+      params.push(String(opts.dateTo));
+      feedbackFilters.push(`created_at < ($${params.length}::date + INTERVAL '1 day')`);
+    }
+    if (feedbackType && feedbackType !== 'all') {
+      params.push(feedbackType);
+      matchTypeExpr = `$${params.length}::text`;
+      filters.push(`r.matching_feedback_count > 0`);
+    } else if (feedbackType === 'all') {
+      filters.push(`r.feedback_count > 0`);
+    } else {
+      filters.push(`r.issue_count > 0`);
+    }
+
+    params.push(scopeContext.activeScopePath);
+    filters.push(`s.scope_key = ANY($${params.length}::text[])`);
+    filters.push(`m.status = 'active'`);
+    params.push(normalizeIsoOrNull(opts.asOf));
+    const asOfRef = `$${params.length}::timestamptz`;
+    filters.push(`(m.valid_from IS NULL OR m.valid_from <= COALESCE(${asOfRef}, now()))`);
+    filters.push(`(m.valid_to IS NULL OR m.valid_to > COALESCE(${asOfRef}, now()))`);
+    filters.push(`(m.stale_after IS NULL OR m.stale_after > COALESCE(${asOfRef}, now()))`);
+    if (opts.canonicalKey) {
+      params.push(String(opts.canonicalKey));
+      filters.push(`m.canonical_key = $${params.length}`);
+    }
+    if (memoryTypes.length > 0) {
+      params.push(memoryTypes);
+      filters.push(`m.memory_type = ANY($${params.length}::text[])`);
+    }
+    if (visibility === 'bootstrap') {
+      filters.push(`m.visible_in_bootstrap = true`);
+    } else if (visibility === 'recall') {
+      filters.push(`m.visible_in_recall = true`);
+    } else if (visibility === 'both') {
+      filters.push(`m.visible_in_bootstrap = true AND m.visible_in_recall = true`);
+    } else {
+      filters.push(`(m.visible_in_bootstrap = true OR m.visible_in_recall = true)`);
+    }
+
+    const requestedLimit = clampLimit(opts.limit);
+    const fetchLimit = Math.min(MAX_FETCH_LIMIT, Math.max(requestedLimit * 4, requestedLimit));
+    params.push(fetchLimit);
+    const limitRef = `$${params.length}`;
+    return {
+      params,
+      sql: `
+        WITH feedback_counts AS (
+          SELECT
+            target_id,
+            feedback_type,
+            COUNT(*)::int AS count,
+            MIN(created_at) AS first_feedback_at,
+            MAX(created_at) AS latest_feedback_at,
+            MAX(id)::bigint AS latest_feedback_id,
+            MAX(${severityExpr})::int AS severity_score
+          FROM ${schema}.feedback
+          WHERE tenant_id = $1
+            AND target_kind = 'memory_record'
+            ${feedbackFilters.length > 0 ? `AND ${feedbackFilters.join('\n            AND ')}` : ''}
+          GROUP BY target_id, feedback_type
+        ),
+        feedback_rollup AS (
+          SELECT
+            target_id,
+            jsonb_object_agg(feedback_type, count ORDER BY feedback_type) AS feedback_counts,
+            SUM(count)::int AS feedback_count,
+            SUM(CASE WHEN feedback_type = ANY($2::text[]) THEN count ELSE 0 END)::int AS issue_count,
+            SUM(CASE WHEN ${matchTypeExpr} IS NOT NULL AND feedback_type = ${matchTypeExpr} THEN count ELSE 0 END)::int AS matching_feedback_count,
+            MIN(first_feedback_at) AS first_feedback_at,
+            MAX(latest_feedback_at) AS latest_feedback_at,
+            MAX(CASE WHEN feedback_type = ANY($2::text[]) THEN latest_feedback_id ELSE NULL END)::bigint AS latest_issue_feedback_id,
+            MAX(CASE WHEN feedback_type = ANY($2::text[]) THEN latest_feedback_at ELSE NULL END) AS latest_issue_feedback_at,
+            MAX(severity_score)::int AS severity_score
+          FROM feedback_counts
+          GROUP BY target_id
+        ),
+        latest_resolution AS (
+          SELECT DISTINCT ON (memory_id)
+            id,
+            memory_id,
+            canonical_key,
+            scope_id,
+            resolution,
+            reason,
+            actor_kind,
+            actor_id,
+            issue_feedback_types,
+            resolved_through_feedback_id,
+            resolved_through_feedback_at,
+            defer_until,
+            resolved_at,
+            created_at
+          FROM ${schema}.memory_review_resolutions
+          WHERE tenant_id = $1
+          ORDER BY memory_id, resolved_at DESC, id DESC
+        )
+        SELECT
+          m.id AS memory_id,
+          m.canonical_key,
+          m.memory_type,
+          m.status,
+          m.visible_in_bootstrap,
+          m.visible_in_recall,
+          m.authority,
+          m.accepted_at,
+          m.updated_at,
+          m.scope_id,
+          s.scope_kind,
+          s.scope_key,
+          s.inheritance_mode,
+          r.feedback_counts,
+          r.feedback_count,
+          r.issue_count,
+          r.matching_feedback_count,
+          r.severity_score,
+          r.first_feedback_at,
+          r.latest_feedback_at,
+          r.latest_issue_feedback_id,
+          r.latest_issue_feedback_at,
+          lr.id AS resolution_id,
+          lr.memory_id AS resolution_memory_id,
+          lr.canonical_key AS resolution_canonical_key,
+          lr.scope_id AS resolution_scope_id,
+          lr.resolution,
+          lr.reason AS resolution_reason,
+          lr.actor_kind AS resolution_actor_kind,
+          lr.actor_id AS resolution_actor_id,
+          lr.issue_feedback_types AS resolution_issue_feedback_types,
+          lr.resolved_through_feedback_id AS resolution_resolved_through_feedback_id,
+          lr.resolved_through_feedback_at AS resolution_resolved_through_feedback_at,
+          lr.defer_until AS resolution_defer_until,
+          lr.resolved_at,
+          lr.created_at AS resolution_created_at,
+          CASE
+            WHEN lr.id IS NULL THEN 'open'
+            WHEN lr.resolved_through_feedback_id IS NULL THEN 'open'
+            WHEN lr.resolved_through_feedback_id < r.latest_issue_feedback_id THEN 'open'
+            WHEN lr.resolution = 'deferred'
+             AND lr.defer_until IS NOT NULL
+             AND lr.defer_until > COALESCE(${asOfRef}, now()) THEN 'deferred'
+            WHEN lr.resolution IN ('resolved','ignored') THEN lr.resolution
+            ELSE 'open'
+          END AS queue_state
+        FROM feedback_rollup r
+        JOIN ${schema}.memory_records m
+          ON m.tenant_id = $1
+         AND r.target_id = m.id::text
+        JOIN ${schema}.scopes s
+          ON s.id = m.scope_id
+         AND s.tenant_id = m.tenant_id
+        LEFT JOIN latest_resolution lr
+          ON lr.memory_id = m.id
+        WHERE ${filters.join('\n          AND ')}
+          ${includeResolved ? '' : `AND (
+            lr.id IS NULL
+            OR lr.resolved_through_feedback_id IS NULL
+            OR lr.resolved_through_feedback_id < r.latest_issue_feedback_id
+            OR (
+              lr.resolution = 'deferred'
+              AND (
+                lr.defer_until IS NULL
+                OR lr.defer_until <= COALESCE(${asOfRef}, now())
+              )
+            )
+          )`}
+        ORDER BY
+          r.severity_score DESC,
+          r.issue_count DESC,
+          r.latest_feedback_at DESC NULLS LAST,
+          m.id DESC
+        LIMIT ${limitRef}`,
+    };
+  }
+
+  async function queue(opts = {}) {
+    assertPool();
+    const query = buildQueueQuery(opts);
+    const result = await pool.query(query.sql, query.params);
+    const feedbackType = normalizeFeedbackType(opts.feedbackType);
+    const memoryTypes = normalizeList(opts.memoryType || opts.memoryTypes);
+    const visibility = normalizeVisibility(opts.visibility);
+    const scopeContext = scopeContextFromOpts(opts);
+    const requestedLimit = clampLimit(opts.limit);
+    const applicableRows = resolveApplicableRecords(result.rows || [], scopeContext);
+    const items = applicableRows.slice(0, requestedLimit).map(normalizeQueueRow);
+    const feedbackTypeCounts = {};
+    const severityCounts = {};
+    const queueStateCounts = {};
+    const latestResolutionCounts = {};
+    for (const item of items) {
+      severityCounts[item.severity] = (severityCounts[item.severity] || 0) + 1;
+      const queueState = item.queueState || 'open';
+      queueStateCounts[queueState] = (queueStateCounts[queueState] || 0) + 1;
+      if (item.resolution?.resolution) {
+        latestResolutionCounts[item.resolution.resolution] = (latestResolutionCounts[item.resolution.resolution] || 0) + 1;
+      }
+      for (const [type, count] of Object.entries(item.feedbackCounts)) {
+        feedbackTypeCounts[type] = (feedbackTypeCounts[type] || 0) + count;
+      }
+    }
+    return {
+      readOnly: true,
+      derived: true,
+      available: true,
+      items,
+      reviewQueue: items,
+      scope: {
+        activeScopeKey: scopeContext.activeScopeKey,
+        activeScopePath: scopeContext.activeScopePath,
+      },
+      filters: {
+        feedbackTypes: feedbackType ? [feedbackType] : issueTypes(opts.issueFeedbackTypes),
+        memoryTypes,
+        visibility,
+        dateFrom: opts.dateFrom || null,
+        dateTo: opts.dateTo || null,
+        asOf: opts.asOf || null,
+        scopeKey: scopeContext.activeScopeKey,
+        canonicalKey: opts.canonicalKey || null,
+        includeResolved: opts.includeResolved === true,
+        limit: requestedLimit,
+      },
+      summary: {
+        scanned: applicableRows.length,
+        queued: items.length,
+        truncated: applicableRows.length > requestedLimit,
+        severityCounts,
+        feedbackTypeCounts,
+        queueStateCounts,
+        resolutionCounts: queueStateCounts,
+        latestResolutionCounts,
+      },
+      totals: {
+        items: items.length,
+        issueFeedback: items.reduce((sum, item) => sum + item.issueCount, 0),
+        allFeedback: items.reduce((sum, item) => sum + item.feedbackCount, 0),
+      },
+    };
+  }
+
+  async function findMemory(input = {}) {
+    const tenantId = input.tenantId || defaultTenantId;
+    const visibility = normalizeVisibility(input.visibility);
+    const scopeContext = scopeContextFromOpts(input);
+    const memoryId = input.memoryId || input.id || null;
+    let canonicalKey = input.canonicalKey || null;
+    if (!memoryId && !canonicalKey) {
+      throw new Error('review.inspect requires memoryId or canonicalKey');
+    }
+
+    function addCurrentFilters(params, filters) {
+      params.push(scopeContext.activeScopePath);
+      filters.push(`s.scope_key = ANY($${params.length}::text[])`);
+      filters.push(`m.status = 'active'`);
+      params.push(normalizeIsoOrNull(input.asOf));
+      const asOfRef = `$${params.length}::timestamptz`;
+      filters.push(`(m.valid_from IS NULL OR m.valid_from <= COALESCE(${asOfRef}, now()))`);
+      filters.push(`(m.valid_to IS NULL OR m.valid_to > COALESCE(${asOfRef}, now()))`);
+      filters.push(`(m.stale_after IS NULL OR m.stale_after > COALESCE(${asOfRef}, now()))`);
+      if (visibility === 'bootstrap') {
+        filters.push(`m.visible_in_bootstrap = true`);
+      } else if (visibility === 'recall') {
+        filters.push(`m.visible_in_recall = true`);
+      } else if (visibility === 'both') {
+        filters.push(`m.visible_in_bootstrap = true AND m.visible_in_recall = true`);
+      } else {
+        filters.push(`(m.visible_in_bootstrap = true OR m.visible_in_recall = true)`);
+      }
+    }
+
+    if (memoryId && !canonicalKey) {
+      const targetParams = [tenantId, String(memoryId)];
+      const targetFilters = [`m.tenant_id = $1`, `m.id::text = $2`];
+      addCurrentFilters(targetParams, targetFilters);
+      const target = await pool.query(
+        `SELECT m.canonical_key
+         FROM ${schema}.memory_records m
+         JOIN ${schema}.scopes s
+           ON s.id = m.scope_id
+          AND s.tenant_id = m.tenant_id
+         WHERE ${targetFilters.join(' AND ')}
+         LIMIT 1`,
+        targetParams,
+      );
+      canonicalKey = target.rows?.[0]?.canonical_key || null;
+      if (!canonicalKey) return null;
+    }
+
+    const params = [tenantId, String(canonicalKey)];
+    const filters = [`m.tenant_id = $1`, `m.canonical_key = $2`];
+    addCurrentFilters(params, filters);
+
+    const result = await pool.query(
+      `SELECT
+         m.id AS memory_id,
+         m.canonical_key,
+         m.memory_type,
+         m.status,
+         m.visible_in_bootstrap,
+         m.visible_in_recall,
+         m.authority,
+         m.accepted_at,
+         m.updated_at,
+         m.scope_id,
+         s.scope_kind,
+         s.scope_key,
+         s.inheritance_mode
+       FROM ${schema}.memory_records m
+       JOIN ${schema}.scopes s
+         ON s.id = m.scope_id
+        AND s.tenant_id = m.tenant_id
+       WHERE ${filters.join(' AND ')}
+       ORDER BY CASE WHEN m.status = 'active' THEN 0 ELSE 1 END, m.updated_at DESC NULLS LAST, m.id DESC
+       LIMIT 20`,
+      params,
+    );
+    const rows = resolveApplicableRecords(result.rows || [], scopeContext);
+    if (memoryId) {
+      return rows.find(row => String(row.memory_id) === String(memoryId)) || null;
+    }
+    if (rows.length > 1) {
+      throw new Error('Multiple memory records matched. Use --memory-id to inspect one row.');
+    }
+    return rows[0] || null;
+  }
+
+  async function loadFeedback(targetId, opts = {}) {
+    const tenantId = opts.tenantId || defaultTenantId;
+    const limit = clampLimit(opts.limit, 20);
+    const params = [tenantId, String(targetId)];
+    const filters = [];
+    const feedbackType = normalizeFeedbackType(opts.feedbackType);
+    if (feedbackType && feedbackType !== 'all') {
+      params.push(feedbackType);
+      filters.push(`feedback_type = $${params.length}`);
+    }
+    if (opts.dateFrom) {
+      params.push(String(opts.dateFrom));
+      filters.push(`created_at >= $${params.length}`);
+    }
+    if (opts.dateTo) {
+      params.push(String(opts.dateTo));
+      filters.push(`created_at < ($${params.length}::date + INTERVAL '1 day')`);
+    }
+    const where = filters.length > 0 ? `\n           AND ${filters.join('\n           AND ')}` : '';
+    const eventParams = params.concat([limit]);
+    const [events, counts] = await Promise.all([
+      pool.query(
+        `SELECT id, feedback_type, actor_kind, actor_id, created_at
+         FROM ${schema}.feedback
+         WHERE tenant_id = $1
+           AND target_kind = 'memory_record'
+           AND target_id = $2
+           ${where}
+         ORDER BY created_at DESC, id DESC
+         LIMIT $${eventParams.length}`,
+        eventParams,
+      ),
+      pool.query(
+        `SELECT feedback_type, COUNT(*)::int AS count
+         FROM ${schema}.feedback
+         WHERE tenant_id = $1
+           AND target_kind = 'memory_record'
+           AND target_id = $2
+           ${where}
+         GROUP BY feedback_type
+         ORDER BY feedback_type`,
+        params,
+      ),
+    ]);
+    return {
+      recentFeedback: (events.rows || []).map(normalizeFeedbackEvent),
+      feedbackCounts: parseCounts(Object.fromEntries((counts.rows || []).map(row => [row.feedback_type, row.count]))),
+    };
+  }
+
+  async function loadResolutions(targetId, opts = {}) {
+    const tenantId = opts.tenantId || defaultTenantId;
+    const limit = clampLimit(opts.resolutionLimit || opts.limit, DEFAULT_RESOLUTION_LIMIT);
+    const result = await pool.query(
+      `SELECT
+         id,
+         memory_id,
+         canonical_key,
+         scope_id,
+         resolution,
+         reason,
+         actor_kind,
+         actor_id,
+         issue_feedback_types,
+         resolved_through_feedback_id,
+         resolved_through_feedback_at,
+         defer_until,
+         resolved_at,
+         created_at
+       FROM ${schema}.memory_review_resolutions
+       WHERE tenant_id = $1
+         AND memory_id::text = $2
+       ORDER BY resolved_at DESC, id DESC
+       LIMIT $3`,
+      [tenantId, String(targetId), limit],
+    );
+    const resolutions = (result.rows || []).map(normalizeResolutionRow).filter(Boolean);
+    return {
+      latestResolution: resolutions[0] || null,
+      recentResolutions: resolutions,
+    };
+  }
+
+  async function loadIssueFeedbackWatermark(targetId, opts = {}) {
+    const tenantId = opts.tenantId || defaultTenantId;
+    const types = issueTypesForResolution(opts);
+    const result = await pool.query(
+      `SELECT
+         feedback_type,
+         COUNT(*)::int AS count,
+         MAX(id)::bigint AS latest_feedback_id,
+         MAX(created_at) AS latest_feedback_at
+       FROM ${schema}.feedback
+       WHERE tenant_id = $1
+         AND target_kind = 'memory_record'
+         AND target_id = $2
+         AND feedback_type = ANY($3::text[])
+       GROUP BY feedback_type
+       ORDER BY feedback_type`,
+      [tenantId, String(targetId), types],
+    );
+    const counts = parseCounts(Object.fromEntries((result.rows || []).map(row => [row.feedback_type, row.count])));
+    const latest = (result.rows || [])
+      .map(row => row.latest_feedback_at)
+      .filter(Boolean)
+      .reduce((max, value) => {
+        const time = new Date(value).getTime();
+        if (!Number.isFinite(time)) return max;
+        if (!max || time > max.time) return { time, value };
+        return max;
+      }, null)?.value || null;
+    const latestId = (result.rows || [])
+      .map(row => Number.parseInt(row.latest_feedback_id, 10))
+      .filter(Number.isFinite)
+      .reduce((max, value) => Math.max(max, value), 0);
+    return {
+      issueFeedbackTypes: types,
+      issueFeedbackCounts: counts,
+      latestIssueFeedbackId: latestId > 0 ? String(latestId) : null,
+      issueFeedbackLatestAt: latest,
+      issueFeedbackCount: Object.values(counts).reduce((sum, count) => sum + count, 0),
+    };
+  }
+
+  async function inspect(input = {}) {
+    assertPool();
+    const memory = await findMemory(input);
+    if (!memory) throw new Error('Memory record not found');
+    const normalized = normalizeQueueRow({
+      ...memory,
+      feedback_counts: {},
+      feedback_count: 0,
+      issue_count: 0,
+      matching_feedback_count: 0,
+      severity_score: 0,
+    });
+    const feedback = await loadFeedback(normalized.memoryId, input);
+    const resolutions = await loadResolutions(normalized.memoryId, input);
+    const issueSet = new Set(issueTypes(input.issueFeedbackTypes));
+    const issueCount = Object.entries(feedback.feedbackCounts)
+      .filter(([type]) => issueSet.has(type))
+      .reduce((sum, [, count]) => sum + count, 0);
+    const issueWatermark = await loadIssueFeedbackWatermark(normalized.memoryId, input);
+    return {
+      readOnly: true,
+      derived: true,
+      available: true,
+      memory: normalized,
+      review: {
+        severity: severityLabel(Math.max(...Object.keys(feedback.feedbackCounts).map(type => SEVERITY_SCORE[type] || 0), 0)),
+        feedbackCounts: feedback.feedbackCounts,
+        issueCount,
+        feedbackCount: Object.values(feedback.feedbackCounts).reduce((sum, count) => sum + count, 0),
+        latestIssueFeedbackId: issueWatermark.latestIssueFeedbackId,
+        latestIssueFeedbackAt: issueWatermark.issueFeedbackLatestAt,
+        recentFeedback: feedback.recentFeedback,
+        latestResolution: resolutions.latestResolution,
+        recentResolutions: resolutions.recentResolutions,
+      },
+    };
+  }
+
+  async function resolve(input = {}) {
+    assertPool();
+    const memory = await findMemory(input);
+    if (!memory) throw new Error('Memory record not found');
+    const resolution = normalizeResolution(input.resolution || input.action);
+    const deferUntil = input.deferUntil || input.defer_until || null;
+    if (resolution === 'deferred') {
+      requireIso(deferUntil, 'review.resolve deferUntil');
+    } else if (deferUntil) {
+      throw new Error('review.resolve deferUntil is only valid for deferred resolution');
+    }
+    const reason = normalizeReason(input.reason || input.note);
+    if ((resolution === 'ignored' || resolution === 'deferred') && !reason) {
+      throw new Error(`review.resolve reason is required for ${resolution}`);
+    }
+    const expectedIssueFeedbackId = input.expectedLatestIssueFeedbackId || input.expected_latest_issue_feedback_id || null;
+    const expectedIssueFeedbackAt = input.expectedLatestIssueFeedbackAt || input.expected_latest_issue_feedback_at || null;
+    if (!expectedIssueFeedbackId && !expectedIssueFeedbackAt) {
+      throw new Error('review.resolve requires expectedLatestIssueFeedbackId or expectedLatestIssueFeedbackAt');
+    }
+    const issueFeedback = await loadIssueFeedbackWatermark(memory.memory_id, input);
+    if (issueFeedback.issueFeedbackCount <= 0 || !issueFeedback.latestIssueFeedbackId) {
+      throw new Error('review.resolve requires current issue feedback on the memory record');
+    }
+    if (expectedIssueFeedbackId && String(expectedIssueFeedbackId) !== String(issueFeedback.latestIssueFeedbackId)) {
+      throw new Error(`review.resolve stale issue feedback snapshot: expected latest issue feedback id ${expectedIssueFeedbackId}, current ${issueFeedback.latestIssueFeedbackId}`);
+    }
+    if (expectedIssueFeedbackAt) {
+      const expectedIso = requireIso(expectedIssueFeedbackAt, 'review.resolve expectedLatestIssueFeedbackAt');
+      const currentIso = requireIso(issueFeedback.issueFeedbackLatestAt, 'review.resolve current issueFeedbackLatestAt');
+      if (compareIso(expectedIso, currentIso) !== 0) {
+        throw new Error(`review.resolve stale issue feedback snapshot: expected latest issue feedback at ${expectedIso}, current ${currentIso}`);
+      }
+    }
+    const tenantId = input.tenantId || defaultTenantId;
+    const params = [
+      tenantId,
+      memory.memory_id,
+      memory.canonical_key,
+      memory.scope_id,
+      resolution,
+      reason,
+      normalizeActorKind(input.actorKind || input.actor_kind),
+      input.actorId || input.actor_id || input.agentId || null,
+      issueFeedback.issueFeedbackTypes,
+      issueFeedback.latestIssueFeedbackId,
+      issueFeedback.issueFeedbackLatestAt,
+      resolution === 'deferred' ? requireIso(deferUntil, 'review.resolve deferUntil') : null,
+      {
+        publicSurface: 'memoryReviewResolve',
+        issueFeedbackCounts: issueFeedback.issueFeedbackCounts,
+        issueFeedbackCount: issueFeedback.issueFeedbackCount,
+        memoryStatus: memory.status || null,
+      },
+    ];
+    const inserted = await pool.query(
+      `INSERT INTO ${schema}.memory_review_resolutions (
+         tenant_id,
+         memory_id,
+         canonical_key,
+         scope_id,
+         resolution,
+         reason,
+         actor_kind,
+         actor_id,
+         issue_feedback_types,
+         resolved_through_feedback_id,
+         resolved_through_feedback_at,
+         defer_until,
+         metadata
+       )
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::text[],$10,$11,$12,$13::jsonb)
+       RETURNING
+         id,
+         memory_id,
+         canonical_key,
+         scope_id,
+         resolution,
+         reason,
+         actor_kind,
+         actor_id,
+         issue_feedback_types,
+         resolved_through_feedback_id,
+         resolved_through_feedback_at,
+         defer_until,
+         resolved_at,
+         created_at`,
+      params,
+    );
+    const normalizedMemory = normalizeQueueRow({
+      ...memory,
+      feedback_counts: issueFeedback.issueFeedbackCounts,
+      feedback_count: issueFeedback.issueFeedbackCount,
+      issue_count: issueFeedback.issueFeedbackCount,
+      matching_feedback_count: issueFeedback.issueFeedbackCount,
+      severity_score: Math.max(...issueFeedback.issueFeedbackTypes.map(type => SEVERITY_SCORE[type] || 0), 0),
+      latest_issue_feedback_id: issueFeedback.latestIssueFeedbackId,
+      latest_issue_feedback_at: issueFeedback.issueFeedbackLatestAt,
+    });
+    return {
+      appendedOnly: true,
+      appendOnly: true,
+      memoryMutated: false,
+      feedbackMutated: false,
+      available: true,
+      memory: normalizedMemory,
+      resolution: normalizeResolutionRow(inserted.rows?.[0]),
+      review: {
+        issueFeedbackTypes: issueFeedback.issueFeedbackTypes,
+        issueFeedbackCounts: issueFeedback.issueFeedbackCounts,
+        issueFeedbackCount: issueFeedback.issueFeedbackCount,
+        latestIssueFeedbackId: issueFeedback.latestIssueFeedbackId,
+        issueFeedbackLatestAt: issueFeedback.issueFeedbackLatestAt,
+      },
+      queue: {
+        wasQueued: true,
+        nowQueued: false,
+        suppressedBy: resolution,
+        reopensAt: resolution === 'deferred' ? requireIso(deferUntil, 'review.resolve deferUntil') : null,
+        reopensOnNewIssueFeedback: true,
+      },
+    };
+  }
+
+  return {
+    queue,
+    inspect,
+    resolve,
+    ISSUE_FEEDBACK_TYPES: ISSUE_FEEDBACK_TYPES.slice(),
+    RESOLUTION_ACTIONS: RESOLUTION_ACTIONS.slice(),
+  };
+}
+
+module.exports = {
+  ISSUE_FEEDBACK_TYPES,
+  createMemoryReview,
+};