create-safest-tools 0.2.0

package/template/src/report-admin.ts

@@ -0,0 +1,342 @@
+import { canonicalJson } from "./audit";
+import { decodeApiCursor, encodeApiCursor } from "./api-cursor";
+import { ApiError } from "./report-http";
+import type { OperatorSession, ReportState } from "./report-types";
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function parsed(value: unknown, fallback: unknown = null): unknown {
+  if (typeof value !== "string") return fallback;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return fallback;
+  }
+}
+
+function auditStatement(
+  db: D1Database,
+  input: {
+    key: string;
+    action: string;
+    session: OperatorSession;
+    targetType: string;
+    targetId: string;
+    details: unknown;
+    createdAt: string;
+  },
+): D1PreparedStatement {
+  return db.prepare(`
+    INSERT INTO audit_events (
+      id, idempotency_key, action, actor_type, actor_id, target_type,
+      target_id, details_json, created_at
+    ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+  `).bind(
+    crypto.randomUUID(), input.key, input.action, input.session.actor.type,
+    input.session.actor.id, input.targetType, input.targetId,
+    canonicalJson(input.details), input.createdAt,
+  );
+}
+
+async function mutationReplay(
+  db: D1Database,
+  key: string,
+  action: string,
+  session: OperatorSession,
+  targetId: string,
+): Promise<Record<string, unknown> | null> {
+  const row = await db.prepare(`
+    SELECT action, actor_id AS actorId, target_id AS targetId, details_json AS detailsJson
+    FROM audit_events WHERE idempotency_key = ?1 LIMIT 1
+  `).bind(key).first<{ action: string; actorId: string; targetId: string; detailsJson: string }>();
+  if (!row) return null;
+  if (row.action !== action || row.actorId !== session.actor.id || row.targetId !== targetId) {
+    throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was already used for another operation.");
+  }
+  const details = parsed(row.detailsJson, {});
+  return details && typeof details === "object" && !Array.isArray(details)
+    ? (details as Record<string, unknown>) : {};
+}
+
+interface ReportOperationRow {
+  id: string;
+  state: ReportState;
+  queueId: string | null;
+  queueVersionId: string | null;
+}
+
+async function reportOperationRow(db: D1Database, reportId: string): Promise<ReportOperationRow> {
+  const report = await db.prepare(`
+    SELECT id, state, queue_id AS queueId, queue_version_id AS queueVersionId
+    FROM reports WHERE id = ?1 LIMIT 1
+  `).bind(reportId).first<ReportOperationRow>();
+  if (!report) throw new ApiError(404, "report_not_found", "The report does not exist.");
+  return report;
+}
+
+interface ActiveQueueRow {
+  id: string;
+  versionId: string;
+  managementMode: "human" | "ai" | "hybrid";
+  rolloutMode: "off" | "shadow" | "assist" | "autonomous_low_priority";
+}
+
+async function activeReportQueue(db: D1Database, queueId: string): Promise<ActiveQueueRow> {
+  const queue = await db.prepare(`
+    SELECT q.id, q.active_version_id AS versionId,
+      v.management_mode AS managementMode, v.mode AS rolloutMode
+    FROM queue_definitions q JOIN queue_versions v ON v.id = q.active_version_id
+    WHERE q.id = ?1 AND q.purpose = 'reports' AND q.status = 'active'
+      AND v.published_at IS NOT NULL AND v.retired_at IS NULL
+    LIMIT 1
+  `).bind(queueId).first<ActiveQueueRow>();
+  if (!queue) throw new ApiError(409, "report_queue_unavailable", "The destination must be an active report queue with a published policy.");
+  return queue;
+}
+
+export async function reassignReport(
+  db: D1Database,
+  reportId: string,
+  queueId: string,
+  reason: string,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<Record<string, unknown>> {
+  const key = `report-reassign:${idempotencyKey}`;
+  const replay = await mutationReplay(db, key, "report.reassigned", session, reportId);
+  if (replay) return { ...replay, idempotentReplay: true };
+  const [report, queue] = await Promise.all([reportOperationRow(db, reportId), activeReportQueue(db, queueId)]);
+  if (["resolved_by_human", "resolved_by_ai", "closed"].includes(report.state)) {
+    throw new ApiError(409, "report_reassignment_terminal", "A resolved or closed report must be reopened before reassignment.");
+  }
+  const nextState: ReportState = queue.managementMode === "human" || queue.rolloutMode === "off"
+    ? "human_review" : "ai_review";
+  const createdAt = now();
+  const result = {
+    reportId,
+    previousQueueId: report.queueId,
+    queueId: queue.id,
+    queueVersionId: queue.versionId,
+    state: nextState,
+  };
+  await db.batch([
+    db.prepare(`
+      UPDATE reports SET queue_id = ?2, queue_version_id = ?3, state = ?4,
+        routing_status = 'complete', routing_error_code = NULL, updated_at = ?5
+      WHERE id = ?1
+    `).bind(reportId, queue.id, queue.versionId, nextState, createdAt),
+    db.prepare(`DELETE FROM review_claims WHERE report_id = ?1`).bind(reportId),
+    db.prepare(`
+      INSERT INTO report_state_history (
+        id, report_id, from_state, to_state, reason_code, actor_type, actor_id, created_at
+      ) VALUES (?1, ?2, ?3, ?4, 'operator_reassigned', ?5, ?6, ?7)
+    `).bind(crypto.randomUUID(), reportId, report.state, nextState, session.actor.type, session.actor.id, createdAt),
+    auditStatement(db, {
+      key, action: "report.reassigned", session, targetType: "report", targetId: reportId,
+      details: { ...result, reason }, createdAt,
+    }),
+  ]);
+  return { ...result, idempotentReplay: false };
+}
+
+export async function closeReport(
+  db: D1Database,
+  reportId: string,
+  reason: string,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<Record<string, unknown>> {
+  const key = `report-close:${idempotencyKey}`;
+  const replay = await mutationReplay(db, key, "report.closed", session, reportId);
+  if (replay) return { ...replay, idempotentReplay: true };
+  const report = await reportOperationRow(db, reportId);
+  if (report.state === "closed") throw new ApiError(409, "report_already_closed", "The report is already closed.");
+  const createdAt = now();
+  const result = { reportId, previousState: report.state, state: "closed", reason };
+  await db.batch([
+    db.prepare(`UPDATE reports SET state = 'closed', resolved_at = COALESCE(resolved_at, ?2), updated_at = ?2 WHERE id = ?1`)
+      .bind(reportId, createdAt),
+    db.prepare(`DELETE FROM review_claims WHERE report_id = ?1`).bind(reportId),
+    db.prepare(`UPDATE human_tasks SET state = 'cancelled', updated_at = ?2 WHERE report_id = ?1 AND state IN ('open','claimed')`)
+      .bind(reportId, createdAt),
+    db.prepare(`UPDATE human_task_claims SET released_at = ?2, release_reason = 'report_closed' WHERE task_id IN (SELECT id FROM human_tasks WHERE report_id = ?1) AND released_at IS NULL`)
+      .bind(reportId, createdAt),
+    db.prepare(`
+      INSERT INTO report_state_history (id, report_id, from_state, to_state, reason_code, actor_type, actor_id, created_at)
+      VALUES (?1, ?2, ?3, 'closed', ?4, ?5, ?6, ?7)
+    `).bind(crypto.randomUUID(), reportId, report.state, reason, session.actor.type, session.actor.id, createdAt),
+    auditStatement(db, {
+      key, action: "report.closed", session, targetType: "report", targetId: reportId,
+      details: result, createdAt,
+    }),
+  ]);
+  return { ...result, idempotentReplay: false };
+}
+
+export async function reopenReport(
+  db: D1Database,
+  reportId: string,
+  queueId: string,
+  reason: string,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<Record<string, unknown>> {
+  const key = `report-reopen:${idempotencyKey}`;
+  const replay = await mutationReplay(db, key, "report.reopened", session, reportId);
+  if (replay) return { ...replay, idempotentReplay: true };
+  const [report, queue] = await Promise.all([reportOperationRow(db, reportId), activeReportQueue(db, queueId)]);
+  if (!["resolved_by_human", "resolved_by_ai", "closed"].includes(report.state)) {
+    throw new ApiError(409, "report_not_reopenable", "Only a resolved or closed report can be reopened.");
+  }
+  const nextState: ReportState = queue.managementMode === "human" || queue.rolloutMode === "off"
+    ? "human_review" : "ai_review";
+  const createdAt = now();
+  const result = { reportId, previousState: report.state, queueId: queue.id, queueVersionId: queue.versionId, state: nextState, reason };
+  await db.batch([
+    db.prepare(`UPDATE reports SET state = ?2, queue_id = ?3, queue_version_id = ?4, resolved_at = NULL, updated_at = ?5 WHERE id = ?1`)
+      .bind(reportId, nextState, queue.id, queue.versionId, createdAt),
+    db.prepare(`
+      INSERT INTO report_state_history (id, report_id, from_state, to_state, reason_code, actor_type, actor_id, created_at)
+      VALUES (?1, ?2, ?3, ?4, 'operator_reopened', ?5, ?6, ?7)
+    `).bind(crypto.randomUUID(), reportId, report.state, nextState, session.actor.type, session.actor.id, createdAt),
+    auditStatement(db, {
+      key, action: "report.reopened", session, targetType: "report", targetId: reportId,
+      details: result, createdAt,
+    }),
+  ]);
+  return { ...result, idempotentReplay: false };
+}
+
+export async function listReportFindings(db: D1Database, reportId: string): Promise<Record<string, unknown>[]> {
+  const timestamp = now();
+  const rows = await db.prepare(`
+    SELECT f.id, f.run_id AS runId, f.step_run_id AS stepRunId,
+      f.component_version_id AS componentVersionId, f.ai_run_id AS aiRunId,
+      f.finding_type AS findingType, f.subject_type AS subjectType,
+      f.subject_reference AS subjectReference, f.status, f.confidence, f.summary,
+      f.data_json AS dataJson, f.provenance_json AS provenanceJson,
+      f.uncertainty_json AS uncertaintyJson, f.input_digest AS inputDigest,
+      f.output_digest AS outputDigest, f.expires_at AS expiresAt,
+      f.created_at AS createdAt, f.superseded_at AS supersededAt,
+      cv.version AS componentVersion, cd.component_key AS componentKey
+    FROM findings f
+    LEFT JOIN component_versions cv ON cv.id = f.component_version_id
+    LEFT JOIN component_definitions cd ON cd.id = cv.definition_id
+    WHERE f.report_id = ?1 ORDER BY f.created_at DESC, f.id DESC
+    LIMIT 500
+  `).bind(reportId).all<Record<string, unknown>>();
+  return rows.results.map((row) => ({
+    ...row,
+    freshness: row.status === "available" && row.expiresAt && String(row.expiresAt) <= timestamp ? "stale" : row.status,
+    data: parsed(row.dataJson, {}),
+    provenance: parsed(row.provenanceJson, {}),
+    uncertainty: parsed(row.uncertaintyJson, []),
+    dataJson: undefined,
+    provenanceJson: undefined,
+    uncertaintyJson: undefined,
+  }));
+}
+
+export async function listReportActions(db: D1Database, reportId: string): Promise<Record<string, unknown>[]> {
+  const [proposals, decisions] = await Promise.all([
+    db.prepare(`
+      SELECT p.id, 'proposal' AS recordKind, p.run_id AS runId, p.step_run_id AS stepRunId,
+        p.decision_id AS decisionId, p.action_code AS actionCode, p.state,
+        p.payload_digest AS payloadDigest, p.authority_mode AS authorityMode,
+        p.operation_id AS operationId, p.compensates_proposal_id AS compensatesProposalId,
+        p.delivery_attempt_count AS attemptCount, p.last_error_code AS errorCode,
+        p.delivery_terminal AS terminal, p.created_at AS createdAt, p.updated_at AS updatedAt
+      FROM action_proposals p WHERE p.report_id = ?1 ORDER BY p.created_at DESC, p.id DESC
+    `).bind(reportId).all<Record<string, unknown>>(),
+    db.prepare(`
+      SELECT a.id, 'decision_outbox' AS recordKind, a.decision_id AS decisionId,
+        a.action_code AS actionCode, a.status AS state, a.idempotency_key AS operationId,
+        a.attempt_count AS attemptCount, a.last_error_code AS errorCode,
+        a.terminal, a.created_at AS createdAt, a.updated_at AS updatedAt
+      FROM decision_action_outbox a WHERE a.report_id = ?1 ORDER BY a.created_at DESC, a.id DESC
+    `).bind(reportId).all<Record<string, unknown>>(),
+  ]);
+  const combined: Record<string, unknown>[] = [...proposals.results, ...decisions.results];
+  return combined
+    .map<Record<string, unknown>>((row) => ({ ...row, terminal: row.terminal === 1 }))
+    .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)) || String(b.id).localeCompare(String(a.id)));
+}
+
+type TimelineCursor = { createdAt: string; id: string };
+
+export async function loadReportTimeline(
+  db: D1Database,
+  reportId: string,
+  input: { cursor: string | null; cursorSecret: string; limit: number },
+): Promise<{ events: Record<string, unknown>[]; nextCursor: string | null }> {
+  await reportOperationRow(db, reportId);
+  const cursorScope = `report-timeline:${reportId}`;
+  const cursor = await decodeApiCursor<TimelineCursor>(input.cursorSecret, cursorScope, input.cursor);
+  if (cursor && (typeof cursor.createdAt !== "string" || cursor.createdAt.length > 50
+    || typeof cursor.id !== "string" || cursor.id.length > 100)) {
+    throw new ApiError(400, "cursor_invalid", "cursor is invalid or does not belong to this query.");
+  }
+  const limit = Math.max(1, Math.min(100, input.limit));
+  const cursorCreatedAt = cursor?.createdAt ?? null;
+  const cursorId = cursor?.id ?? null;
+  const sourceLimit = limit + 1;
+  const sources = await Promise.all([
+    db.prepare(`SELECT h.id, h.created_at AS createdAt, 'state_transition' AS eventType, h.reason_code AS code, h.actor_type AS actorType, h.actor_id AS actorId, json_object('from_state', h.from_state, 'to_state', h.to_state) AS detailsJson FROM report_state_history h WHERE h.report_id = ?1 AND (?2 IS NULL OR h.created_at < ?2 OR (h.created_at = ?2 AND h.id < ?3)) ORDER BY h.created_at DESC, h.id DESC LIMIT ?4`).bind(reportId, cursorCreatedAt, cursorId, sourceLimit).all<Record<string, unknown>>(),
+    db.prepare(`SELECT d.id, d.created_at AS createdAt, 'decision' AS eventType, d.decision_code AS code, d.maker_type AS actorType, d.maker_id AS actorId, json_object('policy_code', d.policy_code, 'policy_version_id', d.policy_version_id) AS detailsJson FROM decisions d WHERE d.report_id = ?1 AND (?2 IS NULL OR d.created_at < ?2 OR (d.created_at = ?2 AND d.id < ?3)) ORDER BY d.created_at DESC, d.id DESC LIMIT ?4`).bind(reportId, cursorCreatedAt, cursorId, sourceLimit).all<Record<string, unknown>>(),
+    db.prepare(`SELECT f.id, f.created_at AS createdAt, 'finding' AS eventType, f.finding_type AS code, 'component' AS actorType, COALESCE(f.component_version_id, f.ai_run_id, 'system') AS actorId, json_object('status', f.status, 'summary', f.summary, 'confidence', f.confidence) AS detailsJson FROM findings f WHERE f.report_id = ?1 AND (?2 IS NULL OR f.created_at < ?2 OR (f.created_at = ?2 AND f.id < ?3)) ORDER BY f.created_at DESC, f.id DESC LIMIT ?4`).bind(reportId, cursorCreatedAt, cursorId, sourceLimit).all<Record<string, unknown>>(),
+    db.prepare(`SELECT cr.id, cr.created_at AS createdAt, 'component_run' AS eventType, cr.state AS code, 'component' AS actorType, cr.component_version_id AS actorId, json_object('attempt_count', cr.attempt_count, 'error_code', cr.error_code, 'finding_id', cr.finding_id) AS detailsJson FROM component_runs cr WHERE cr.report_id = ?1 AND (?2 IS NULL OR cr.created_at < ?2 OR (cr.created_at = ?2 AND cr.id < ?3)) ORDER BY cr.created_at DESC, cr.id DESC LIMIT ?4`).bind(reportId, cursorCreatedAt, cursorId, sourceLimit).all<Record<string, unknown>>(),
+    db.prepare(`SELECT wr.id, wr.created_at AS createdAt, 'workflow_run' AS eventType, wr.state AS code, 'workflow' AS actorType, wr.workflow_version_id AS actorId, json_object('run_kind', wr.run_kind, 'authority_mode', wr.authority_mode, 'error_code', wr.error_code) AS detailsJson FROM workflow_runs wr WHERE wr.report_id = ?1 AND (?2 IS NULL OR wr.created_at < ?2 OR (wr.created_at = ?2 AND wr.id < ?3)) ORDER BY wr.created_at DESC, wr.id DESC LIMIT ?4`).bind(reportId, cursorCreatedAt, cursorId, sourceLimit).all<Record<string, unknown>>(),
+    db.prepare(`SELECT m.id, m.created_at AS createdAt, 'message' AS eventType, m.direction AS code, m.sender_type AS actorType, m.sender_id AS actorId, json_object('audience', m.audience, 'automated', m.automated, 'delivery_state', m.delivery_state) AS detailsJson FROM case_messages m WHERE m.report_id = ?1 AND (?2 IS NULL OR m.created_at < ?2 OR (m.created_at = ?2 AND m.id < ?3)) ORDER BY m.created_at DESC, m.id DESC LIMIT ?4`).bind(reportId, cursorCreatedAt, cursorId, sourceLimit).all<Record<string, unknown>>(),
+    db.prepare(`SELECT p.id, p.created_at AS createdAt, 'action' AS eventType, p.state AS code, p.created_by_type AS actorType, p.created_by_id AS actorId, json_object('action_code', p.action_code, 'payload_digest', p.payload_digest, 'operation_id', p.operation_id) AS detailsJson FROM action_proposals p WHERE p.report_id = ?1 AND (?2 IS NULL OR p.created_at < ?2 OR (p.created_at = ?2 AND p.id < ?3)) ORDER BY p.created_at DESC, p.id DESC LIMIT ?4`).bind(reportId, cursorCreatedAt, cursorId, sourceLimit).all<Record<string, unknown>>(),
+  ]);
+  const combined = sources.flatMap((source) => source.results)
+    .sort((left, right) => String(right.createdAt).localeCompare(String(left.createdAt)) || String(right.id).localeCompare(String(left.id)));
+  const page = combined.slice(0, limit).map<Record<string, unknown>>((row) => ({
+    ...row,
+    details: parsed(row.detailsJson, {}),
+    detailsJson: undefined,
+  }));
+  const last = page.at(-1);
+  return {
+    events: page,
+    nextCursor: combined.length > limit && last
+      ? await encodeApiCursor(input.cursorSecret, cursorScope, { createdAt: String(last.createdAt), id: String(last.id) })
+      : null,
+  };
+}
+
+export async function loadDecisionDetail(db: D1Database, decisionId: string): Promise<Record<string, unknown> | null> {
+  const decision = await db.prepare(`
+    SELECT d.id, d.report_id AS reportId, r.public_reference AS reportReference,
+      d.decision_code AS decisionCode, d.policy_version_id AS policyVersionId,
+      d.policy_code AS policyCode, d.rationale, d.evidence_references_json AS evidenceReferencesJson,
+      d.maker_type AS makerType, d.maker_id AS makerId, d.queue_version_id AS queueVersionId,
+      d.ai_run_id AS aiRunId, d.proposed_action_code AS proposedActionCode,
+      d.supersedes_decision_id AS supersedesDecisionId, d.created_at AS createdAt
+    FROM decisions d JOIN reports r ON r.id = d.report_id WHERE d.id = ?1 LIMIT 1
+  `).bind(decisionId).first<Record<string, unknown>>();
+  if (!decision) return null;
+  const [decisionActions, proposals, notices, appeal] = await Promise.all([
+    db.prepare(`SELECT id, action_code AS actionCode, status, attempt_count AS attemptCount, last_error_code AS errorCode, terminal, created_at AS createdAt, updated_at AS updatedAt FROM decision_action_outbox WHERE decision_id = ?1 ORDER BY created_at, id`)
+      .bind(decisionId).all<Record<string, unknown>>(),
+    db.prepare(`SELECT id, action_code AS actionCode, state, payload_digest AS payloadDigest, operation_id AS operationId, created_at AS createdAt, updated_at AS updatedAt FROM action_proposals WHERE decision_id = ?1 ORDER BY created_at, id`)
+      .bind(decisionId).all<Record<string, unknown>>(),
+    db.prepare(`SELECT id, audience, delivery_state AS deliveryState, created_at AS createdAt, updated_at AS updatedAt FROM notices WHERE decision_id = ?1 ORDER BY created_at, id`)
+      .bind(decisionId).all<Record<string, unknown>>(),
+    db.prepare(`SELECT id, appellant_audience AS appellantAudience, state, submitted_at AS submittedAt, resolved_at AS resolvedAt FROM appeals WHERE decision_id = ?1 ORDER BY submitted_at DESC LIMIT 1`)
+      .bind(decisionId).first<Record<string, unknown>>(),
+  ]);
+  return {
+    ...decision,
+    evidenceReferences: parsed(decision.evidenceReferencesJson, []),
+    evidenceReferencesJson: undefined,
+    actions: [
+      ...proposals.results.map((row) => ({ ...row, recordKind: "proposal" })),
+      ...decisionActions.results.map((row) => ({ ...row, recordKind: "decision_outbox", terminal: row.terminal === 1 })),
+    ],
+    notices: notices.results,
+    appeal: appeal ?? null,
+  };
+}