codetrap 0.1.6 → 0.1.8

package/src/lib/session-store.ts

@@ -3,12 +3,22 @@ import {
   existsSync,
   mkdirSync,
   readFileSync,
+  rmSync,
   writeFileSync,
 } from "node:fs";
 import { join } from "node:path";
 import type { CandidateTrap, CandidateTrapDocument, SessionIndexDocument, SessionMetadata, SessionNote } from "../domain/session";
 import { parseSessionNoteKind, SESSION_VERSION } from "../domain/session";
 import { CODETRAP_DIR } from "./constants";
+import {
+  acceptCandidateInDocument,
+  addCandidateToDocument,
+  recordCandidateConflictCheckInDocument,
+  rejectCandidateInDocument,
+  removeCandidatesFromDocument,
+  saveCandidateTrapInDocument,
+  type CandidateDocumentUpdateResult,
+} from "./session-candidate-document";
 import {
   ACTIVE_SESSION_FILE,
   CANDIDATES_FILE,
@@ -22,13 +32,14 @@ import {
   recapSummary,
   RECAP_FILE,
   sessionIndexEntry,
+  sessionRelativeDir,
   SESSION_FILE,
   SESSION_INDEX_FILE,
   sessionRelativeFile,
   SESSIONS_DIR,
 } from "./session-codec";
-import { proposeCandidateTraps } from "./session-capture";
-import { scoreCandidateTrap } from "./trap-quality";
+import { uniqueStrings } from "./string-list";
+import { mergeCandidateTraps, proposeCandidateTraps, type CandidateDraft } from "./session-capture";
 
 export interface StartSessionArgs {
   goal: string;
@@ -48,7 +59,6 @@ export interface CloseSessionResult {
   session: SessionMetadata;
   recap_path: string;
   candidate_count: number;
-  traps_written: number;
 }
 
 export interface AcceptCandidateResult {
@@ -60,6 +70,38 @@ export interface AcceptCandidateResult {
   superseded_id: number | null;
 }
 
+export interface DeleteSessionResult {
+  session_id: string;
+  deleted: boolean;
+  active_cleared: boolean;
+  session_dir: string;
+}
+
+export interface PruneSessionsResult {
+  cutoff: string;
+  dry_run: boolean;
+  deleted_count: number;
+  sessions: {
+    id: string;
+    goal: string;
+    status: string;
+    created_at: string;
+    closed_at: string | null;
+  }[];
+}
+
+export interface RemoveSessionCandidatesResult {
+  session: SessionMetadata;
+  removed_count: number;
+  removed_candidate_ids: string[];
+  candidates: CandidateTrap[];
+}
+
+export interface AddSessionCandidateArgs {
+  sessionId: string;
+  draft: CandidateDraft;
+}
+
 export class SessionStore {
   constructor(private readonly projectRoot: string) {}
 
@@ -190,7 +232,10 @@ export class SessionStore {
 
     const closedAt = now.toISOString();
     const notes = this.readNotes(session.id);
-    const candidates = proposeTraps ? proposeCandidateTraps(session, notes) : this.readCandidateDocument(session.id).candidates;
+    const existingCandidates = this.readCandidateDocument(session.id).candidates;
+    const candidates = proposeTraps
+      ? mergeCandidateTraps(existingCandidates, proposeCandidateTraps(session, notes))
+      : existingCandidates;
     if (proposeTraps) this.writeCandidateDocument(session.id, candidates);
 
     const updated = {
@@ -208,7 +253,6 @@ export class SessionStore {
       session: updated,
       recap_path: sessionRelativeFile(updated.id, RECAP_FILE),
       candidate_count: candidates.length,
-      traps_written: 0,
     };
   }
 
@@ -224,6 +268,22 @@ export class SessionStore {
     return { session, candidate };
   }
 
+  addCandidate(args: AddSessionCandidateArgs): { session: SessionMetadata; candidate: CandidateTrap; candidates_path: string; duplicate: boolean } {
+    const session = this.requireSession(args.sessionId);
+    const document = this.readCandidateDocument(session.id);
+    const added = addCandidateToDocument(document.candidates, args.draft);
+    if (!added.duplicate) {
+      this.writeCandidateDocument(session.id, added.candidates);
+      this.refreshSessionSummaries(session.id);
+    }
+    return {
+      session: this.requireSession(session.id),
+      candidate: added.candidate,
+      candidates_path: sessionRelativeFile(session.id, CANDIDATES_FILE),
+      duplicate: added.duplicate,
+    };
+  }
+
   recordCandidateConflictCheck(
     candidateId: string,
     args: {
@@ -236,17 +296,16 @@ export class SessionStore {
     const sessionId = this.resolveSessionId(args.sessionId);
     const session = this.requireSession(sessionId);
     const document = this.readCandidateDocument(sessionId);
-    const candidate = document.candidates.find((item) => item.id === candidateId);
-    if (!candidate) throw new Error(`Candidate ${candidateId} not found in session ${sessionId}.`);
-    if (candidate.status !== "proposed") throw new Error(`Candidate ${candidateId} is already ${candidate.status}.`);
-
-    if (args.trap) candidate.trap = args.trap;
-    candidate.quality.conflict_checked = true;
-    candidate.quality.conflict_status = args.conflictStatus;
-    candidate.quality.suggested_action = args.suggestedAction;
-    this.writeCandidateDocument(session.id, document.candidates);
-    this.refreshSessionSummaries(session.id);
-    return { session, candidate };
+    return this.saveCandidateDocumentMutation(session, recordCandidateConflictCheckInDocument(
+      document.candidates,
+      candidateId,
+      {
+        sessionId,
+        trap: args.trap,
+        conflictStatus: args.conflictStatus,
+        suggestedAction: args.suggestedAction,
+      }
+    ));
   }
 
   saveCandidateTrap(
@@ -259,17 +318,11 @@ export class SessionStore {
     const sessionId = this.resolveSessionId(args.sessionId);
     const session = this.requireSession(sessionId);
     const document = this.readCandidateDocument(sessionId);
-    const candidate = document.candidates.find((item) => item.id === candidateId);
-    if (!candidate) throw new Error(`Candidate ${candidateId} not found in session ${sessionId}.`);
-    if (candidate.status !== "proposed") throw new Error(`Candidate ${candidateId} is already ${candidate.status}.`);
-
-    const scored = scoreCandidateTrap({ trap: args.trap, evidence: candidate.evidence });
-    candidate.trap = args.trap;
-    candidate.quality_score = scored.score;
-    candidate.quality = scored.quality;
-    this.writeCandidateDocument(session.id, document.candidates);
-    this.refreshSessionSummaries(session.id);
-    return { session, candidate };
+    return this.saveCandidateDocumentMutation(session, saveCandidateTrapInDocument(
+      document.candidates,
+      candidateId,
+      { sessionId, trap: args.trap }
+    ));
   }
 
   acceptCandidate(
@@ -290,24 +343,24 @@ export class SessionStore {
     const sessionId = this.resolveSessionId(args.sessionId);
     const session = this.requireSession(sessionId);
     const document = this.readCandidateDocument(sessionId);
-    const candidate = document.candidates.find((item) => item.id === candidateId);
-    if (!candidate) throw new Error(`Candidate ${candidateId} not found in session ${sessionId}.`);
-    if (candidate.status !== "proposed") throw new Error(`Candidate ${candidateId} is already ${candidate.status}.`);
-
-    if (args.trap) candidate.trap = args.trap;
-    candidate.status = "accepted";
-    candidate.accepted_trap_id = args.trapId;
-    candidate.accepted_scope = args.scope === "project" ? "project" : "global";
-    candidate.accepted_at = now.toISOString();
-    candidate.quality.conflict_checked = args.conflictChecked ?? candidate.quality.conflict_checked;
-    candidate.quality.conflict_status = args.conflictStatus ?? candidate.quality.conflict_status;
-    candidate.quality.suggested_action = args.suggestedAction ?? candidate.quality.suggested_action;
-    this.writeCandidateDocument(session.id, document.candidates);
-    this.refreshSessionSummaries(session.id);
+    const accepted = this.saveCandidateDocumentMutation(session, acceptCandidateInDocument(
+      document.candidates,
+      candidateId,
+      {
+        sessionId,
+        trap: args.trap,
+        trapId: args.trapId,
+        scope: args.scope,
+        conflictChecked: args.conflictChecked,
+        conflictStatus: args.conflictStatus,
+        suggestedAction: args.suggestedAction,
+      },
+      now
+    ));
 
     return {
       session,
-      candidate,
+      candidate: accepted.candidate,
       trap_id: args.trapId,
       scope: args.scope,
       evidence_id: args.evidenceId,
@@ -323,16 +376,73 @@ export class SessionStore {
     const sessionId = this.resolveSessionId(args.sessionId);
     const session = this.requireSession(sessionId);
     const document = this.readCandidateDocument(sessionId);
-    const candidate = document.candidates.find((item) => item.id === candidateId);
-    if (!candidate) throw new Error(`Candidate ${candidateId} not found in session ${sessionId}.`);
-    if (candidate.status !== "proposed") throw new Error(`Candidate ${candidateId} is already ${candidate.status}.`);
+    return this.saveCandidateDocumentMutation(session, rejectCandidateInDocument(
+      document.candidates,
+      candidateId,
+      { sessionId, reason: args.reason },
+      now
+    ));
+  }
 
-    candidate.status = "rejected";
-    candidate.rejected_at = now.toISOString();
-    if (args.reason) candidate.rejection_reason = args.reason;
-    this.writeCandidateDocument(session.id, document.candidates);
-    this.refreshSessionSummaries(session.id);
-    return { session, candidate };
+  removeCandidates(sessionId: string | undefined, candidateIds: string[]): RemoveSessionCandidatesResult {
+    const resolvedSessionId = this.resolveSessionId(sessionId);
+    const session = this.requireSession(resolvedSessionId);
+    const document = this.readCandidateDocument(session.id);
+    const removed = removeCandidatesFromDocument(document.candidates, candidateIds);
+    if (removed.removed.length > 0) {
+      this.writeCandidateDocument(session.id, removed.candidates);
+      this.refreshSessionSummaries(session.id);
+    }
+
+    return {
+      session,
+      removed_count: removed.removed.length,
+      removed_candidate_ids: removed.removed.map((candidate) => candidate.id),
+      candidates: removed.candidates,
+    };
+  }
+
+  deleteSession(id: string): DeleteSessionResult {
+    this.requireSession(id);
+    const active_cleared = this.readActive()?.active_session_id === id;
+    rmSync(this.sessionDir(id), { recursive: true, force: true });
+    this.removeIndexEntry(id);
+    if (active_cleared) this.clearActive();
+    return {
+      session_id: id,
+      deleted: true,
+      active_cleared,
+      session_dir: sessionRelativeDir(id),
+    };
+  }
+
+  pruneSessions(args: { cutoff: Date; dryRun?: boolean }): PruneSessionsResult {
+    const cutoffTime = args.cutoff.getTime();
+    const candidates = this.readIndex().sessions
+      .filter((entry) => entry.status === "closed")
+      .filter((entry) => {
+        const closedAt = entry.closed_at ? Date.parse(entry.closed_at) : Date.parse(entry.created_at);
+        return Number.isFinite(closedAt) && closedAt < cutoffTime;
+      });
+
+    if (!args.dryRun) {
+      for (const session of candidates) {
+        this.deleteSession(session.id);
+      }
+    }
+
+    return {
+      cutoff: args.cutoff.toISOString(),
+      dry_run: args.dryRun ?? false,
+      deleted_count: args.dryRun ? 0 : candidates.length,
+      sessions: candidates.map((session) => ({
+        id: session.id,
+        goal: session.goal,
+        status: session.status,
+        created_at: session.created_at,
+        closed_at: session.closed_at,
+      })),
+    };
   }
 
   readNotes(id: string): SessionNote[] {
@@ -387,6 +497,15 @@ export class SessionStore {
     return candidate;
   }
 
+  private saveCandidateDocumentMutation(
+    session: SessionMetadata,
+    mutation: CandidateDocumentUpdateResult
+  ): { session: SessionMetadata; candidate: CandidateTrap } {
+    this.writeCandidateDocument(session.id, mutation.candidates);
+    this.refreshSessionSummaries(session.id);
+    return { session, candidate: mutation.candidate };
+  }
+
   private readCandidateDocument(id: string): CandidateTrapDocument {
     const path = this.candidatesPath(id);
     if (!existsSync(path)) {
@@ -436,6 +555,13 @@ export class SessionStore {
     writeFileSync(this.indexPath(), `${JSON.stringify({ version: SESSION_VERSION, sessions } satisfies SessionIndexDocument, null, 2)}\n`);
   }
 
+  private removeIndexEntry(id: string): void {
+    this.ensureSessionsDir();
+    const index = this.readIndex();
+    const sessions = index.sessions.filter((entry) => entry.id !== id);
+    writeFileSync(this.indexPath(), `${JSON.stringify({ version: SESSION_VERSION, sessions } satisfies SessionIndexDocument, null, 2)}\n`);
+  }
+
   private readActive(): { active_session_id: string | null; updated_at: string } | null {
     const path = this.activePath();
     if (!existsSync(path)) return null;
@@ -497,7 +623,3 @@ export class SessionStore {
     return join(this.sessionDir(id), CANDIDATES_FILE);
   }
 }
-
-function uniqueStrings(values: string[]): string[] {
-  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
-}

package/src/lib/store.ts

@@ -1,3 +1,4 @@
+import type { EmbeddingProfileSummary } from "../db/embedding-queries";
 import type { TrapStats } from "../db/repository";
 import {
   type Trap,
@@ -10,7 +11,20 @@ import {
   type TrapUpdate,
 } from "../domain/trap";
 import type { SearchMode, TrapStatus } from "./constants";
-import { createDefaultEmbeddingProvider, embeddingConfig, type EmbeddingConfig, type EmbeddingProvider } from "./embedder";
+import type { EmbeddingConfig } from "./embedder";
+import {
+  defaultEmbeddingRuntime,
+  embeddingRuntimeFrom,
+  type EmbeddingRuntime,
+  type EmbeddingRuntimeInput,
+  type EmbeddingRuntimeStatus,
+} from "./embedding-runtime";
+import {
+  type ConfigWriteResult,
+  type EmbeddingSettings,
+  loadCodetrapConfig,
+  setCodetrapEmbeddingSettings,
+} from "./config";
 import { summarizeEmbeddingState, type EmbeddingStateSummary, type EmbeddingStatsResult } from "./embedding-health";
 import { normalizeScope, ScopedRepositoryContext, type ScopedRepository } from "./scope-context";
 import { importTrapArchive } from "./trap-archive";
@@ -33,14 +47,32 @@ export {
 
 export type { EmbeddingStateSummary };
 export type TrapEmbeddingStats = EmbeddingStatsResult;
+export type TrapEmbeddingProfiles = {
+  project: EmbeddingProfileSummary[] | null;
+  global: EmbeddingProfileSummary[] | null;
+};
+export type EmbeddingScopeStatus = EmbeddingStateSummary & {
+  profiles: EmbeddingProfileSummary[];
+};
+export type TrapEmbeddingStatus = {
+  runtime: EmbeddingRuntimeStatus;
+  project: EmbeddingScopeStatus | null;
+  global: EmbeddingScopeStatus | null;
+};
 
 export class TrapStore {
   private readonly scopes: ScopedRepositoryContext;
-  private readonly embedder?: EmbeddingProvider;
-
-  constructor(cwd: string, embedder: EmbeddingProvider | undefined = createDefaultEmbeddingProvider()) {
-    this.embedder = embedder;
-    this.scopes = new ScopedRepositoryContext(cwd, embedder);
+  private readonly embeddings: EmbeddingRuntime;
+
+  constructor(
+    cwd: string,
+    embeddings?: EmbeddingRuntimeInput,
+    private readonly home?: string
+  ) {
+    this.embeddings = embeddings === undefined
+      ? defaultEmbeddingRuntime(process.env, loadCodetrapConfig(home))
+      : embeddingRuntimeFrom(embeddings);
+    this.scopes = new ScopedRepositoryContext(cwd, this.embeddings, home);
   }
 
   add(input: TrapInput): { id: number; scope: string } {
@@ -195,6 +227,34 @@ export class TrapStore {
     };
   }
 
+  embeddingProfiles(opts: { scope?: string } = {}): TrapEmbeddingProfiles {
+    const scope = opts.scope ? normalizeScope(opts.scope) : null;
+    const project = scope === "global"
+      ? null
+      : this.scopes.repositoryEntry("project")
+      ? this.scopes.repositoryFor("project").embeddingProfiles({ scope: "project" })
+      : null;
+    const global = scope === "project"
+      ? null
+      : this.scopes.repositoryFor("global").embeddingProfiles({ scope: "global" });
+    return { project, global };
+  }
+
+  async embeddingStatus(opts: { scope?: string } = {}): Promise<TrapEmbeddingStatus> {
+    const runtime = await this.embeddingRuntimeHealth();
+    const stats = this.embeddingStats(opts);
+    const profiles = this.embeddingProfiles(opts);
+    return {
+      runtime,
+      project: stats.project
+        ? { ...stats.project, profiles: profiles.project ?? [] }
+        : null,
+      global: stats.global
+        ? { ...stats.global, profiles: profiles.global ?? [] }
+        : null,
+    };
+  }
+
   diagnostics(): {
     mis_scoped_traps: {
       global_db_project_traps: Pick<Trap, "id" | "title" | "scope" | "project_path" | "status">[];
@@ -238,16 +298,24 @@ export class TrapStore {
     return this.scopes.projectRoot();
   }
 
-  hasEmbeddingProvider(): boolean {
-    return this.embedder !== undefined;
+  embeddingConfig(): EmbeddingConfig | null {
+    return this.embeddings.config();
   }
 
-  embeddingConfig(): EmbeddingConfig | null {
-    return this.embedder ? embeddingConfig(this.embedder) : null;
+  embeddingRuntimeStatus(): EmbeddingRuntimeStatus {
+    return this.embeddings.status();
+  }
+
+  embeddingRuntimeHealth(): Promise<EmbeddingRuntimeStatus> {
+    return this.embeddings.health();
+  }
+
+  configureEmbeddings(settings: EmbeddingSettings): ConfigWriteResult {
+    return setCodetrapEmbeddingSettings(settings, this.home);
   }
 
   forCwd(cwd: string): TrapStore {
-    return new TrapStore(cwd, this.embedder);
+    return new TrapStore(cwd, this.embeddings, this.home);
   }
 
   async ensureEmbeddings(opts: { scope?: string; category?: string; limit?: number; force?: boolean; batchSize?: number } = {}): Promise<{

package/src/lib/string-list.ts

@@ -0,0 +1,3 @@
+export function uniqueStrings(values: string[]): string[] {
+  return [...new Set(values.map((value) => value.trim()).filter(Boolean))];
+}

package/src/lib/text-lines.ts

@@ -0,0 +1,7 @@
+export function trimOuterBlankLines(lines: string[]): string[] {
+  let start = 0;
+  let end = lines.length;
+  while (start < end && lines[start].trim() === "") start++;
+  while (end > start && lines[end - 1].trim() === "") end--;
+  return lines.slice(start, end);
+}

package/src/lib/trap-search-document.ts

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import type { Trap, TrapInput, TrapUpdate } from "../domain/trap";
-import type { EmbeddingConfig, StoredEmbedding } from "./embedder";
+import { embeddingProfileId, type EmbeddingConfig, type StoredEmbedding } from "./embedder";
 import { buildSearchText, SEARCH_TEXT_FIELD_NAMES, type SearchTextFields } from "./search-normalizer";
 import { parseTrapPathGlobs, parseTrapTags } from "./trap-json-fields";
 
@@ -74,6 +74,7 @@ export function embeddingIsFresh(trap: Trap, embedding: StoredEmbedding | null,
       embedding.provider === config.provider &&
       embedding.model === config.model &&
       embedding.dimensions === config.dimensions &&
+      embedding.profile_id === embeddingProfileId(config) &&
       embedding.passage_version === config.passageVersion &&
       embedding.passage_hash === passageHashForTrap(trap)
   );

package/src/lib/value-types.ts

@@ -0,0 +1,3 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/web/client-review.ts

@@ -0,0 +1,171 @@
+export type ReviewSessionLike = {
+  id: string;
+  pending_count?: number | null;
+};
+
+export type ReviewCandidateView = "inbox" | "reviewed";
+
+export type ReviewCandidateLike = {
+  id: string;
+  status: string;
+  quality_score: number;
+};
+
+export type ReviewSummaryLike = {
+  pending_count?: number | null;
+  pending_session_count?: number | null;
+  high_quality_pending_count?: number | null;
+  needs_edit_count?: number | null;
+};
+
+export type ReviewCandidateDraftFields = Record<string, unknown>;
+
+export type ReviewCandidateTrapDraft = {
+  title: string;
+  category: string;
+  scope: string;
+  severity: string;
+  tags: string[];
+  path_globs: string[];
+  module: string | null;
+  owner: string | null;
+  context: string;
+  mistake: string;
+  fix: string;
+};
+
+export type ReviewCandidateMutationPayloadArgs = {
+  projectRoot: string | null;
+  sessionId: string | null;
+  candidateId: string | null;
+  trap: ReviewCandidateTrapDraft;
+  extra?: Record<string, unknown>;
+};
+
+export type ReviewCandidateMutationPayload = {
+  projectRoot: string | null;
+  sessionId: string | null;
+  candidateId: string | null;
+  trap: ReviewCandidateTrapDraft;
+} & Record<string, unknown>;
+
+export type ReviewQueueModelArgs<TCandidate extends ReviewCandidateLike> = {
+  candidates: TCandidate[];
+  candidateView: ReviewCandidateView;
+  candidateId?: string | null;
+  candidateReview?: ReviewSummaryLike | null;
+};
+
+export function selectedReviewSessionId(
+  sessions: ReviewSessionLike[],
+  currentSessionId: string | null | undefined
+): string | null {
+  if (currentSessionId && sessions.some((session) => session.id === currentSessionId)) {
+    return currentSessionId;
+  }
+  return sessions.find((session) => (session.pending_count || 0) > 0)?.id || sessions[0]?.id || null;
+}
+
+export function reviewQueueModel<TCandidate extends ReviewCandidateLike>(
+  args: ReviewQueueModelArgs<TCandidate>
+) {
+  const pendingCount = args.candidates.filter((candidate) => candidate.status === "proposed").length;
+  const reviewedCount = args.candidates.length - pendingCount;
+  const visibleCandidates = sortedReviewCandidates(args.candidates, args.candidateView);
+  return {
+    pendingCount,
+    reviewedCount,
+    visibleCandidates,
+    selectedCandidateId: selectedReviewCandidateId(visibleCandidates, args.candidateId),
+    summary: visibleReviewSummary(args.candidateReview),
+  };
+}
+
+export function sortedReviewCandidates<TCandidate extends ReviewCandidateLike>(
+  candidates: TCandidate[],
+  candidateView: ReviewCandidateView
+): TCandidate[] {
+  return [...candidates]
+    .filter((candidate) => candidateVisibleInReviewView(candidate, candidateView))
+    .sort((a, b) => reviewStatusRank(a.status) - reviewStatusRank(b.status) || b.quality_score - a.quality_score);
+}
+
+export function selectedReviewCandidateId(
+  candidates: ReviewCandidateLike[],
+  currentCandidateId: string | null | undefined
+): string | null {
+  if (currentCandidateId && candidates.some((candidate) => candidate.id === currentCandidateId)) {
+    return currentCandidateId;
+  }
+  return candidates[0]?.id || null;
+}
+
+export function visibleReviewSummary(summary: ReviewSummaryLike | null | undefined): ReviewSummaryLike | null {
+  if (!summary || (summary.pending_count || 0) === 0) return null;
+  return summary;
+}
+
+export function candidateVisibleInReviewView(
+  candidate: ReviewCandidateLike,
+  candidateView: ReviewCandidateView
+): boolean {
+  return candidateView === "inbox" ? candidate.status === "proposed" : candidate.status !== "proposed";
+}
+
+export function reviewStatusRank(status: string): number {
+  return status === "proposed" ? 0 : status === "accepted" ? 1 : 2;
+}
+
+export function reviewCandidateTrapDraft(fields: ReviewCandidateDraftFields): ReviewCandidateTrapDraft {
+  return {
+    title: String(fields.title || ""),
+    category: String(fields.category || ""),
+    scope: String(fields.scope || ""),
+    severity: String(fields.severity || ""),
+    tags: reviewSplitList(fields.tags),
+    path_globs: reviewSplitList(fields.path_globs),
+    module: reviewBlankToNull(fields.module),
+    owner: reviewBlankToNull(fields.owner),
+    context: String(fields.context || ""),
+    mistake: String(fields.mistake || ""),
+    fix: String(fields.fix || ""),
+  };
+}
+
+export function reviewCandidateMutationPayload(args: ReviewCandidateMutationPayloadArgs): ReviewCandidateMutationPayload {
+  return {
+    projectRoot: args.projectRoot,
+    sessionId: args.sessionId,
+    candidateId: args.candidateId,
+    trap: args.trap,
+    ...(args.extra || {}),
+  };
+}
+
+function reviewSplitList(value: unknown): string[] {
+  const values = Array.isArray(value) ? value : String(value || "").split(",");
+  return [...new Set(values.map((item) => String(item).trim()).filter(Boolean))];
+}
+
+function reviewBlankToNull(value: unknown): string | null {
+  const text = String(value || "").trim();
+  return text ? text : null;
+}
+
+const CLIENT_REVIEW_FUNCTIONS = [
+  selectedReviewSessionId,
+  reviewQueueModel,
+  sortedReviewCandidates,
+  selectedReviewCandidateId,
+  visibleReviewSummary,
+  candidateVisibleInReviewView,
+  reviewStatusRank,
+  reviewCandidateTrapDraft,
+  reviewCandidateMutationPayload,
+  reviewSplitList,
+  reviewBlankToNull,
+];
+
+export const WEB_REVIEW_CLIENT_SCRIPT = CLIENT_REVIEW_FUNCTIONS
+  .map((fn) => `    ${fn.toString().replace(/\n/g, "\n    ")}`)
+  .join("\n\n");