codetrap 0.1.2 → 0.1.4

package/src/lib/store.ts

@@ -1,5 +1,4 @@
-import { openGlobal, openProject } from "../db/connection";
-import { TrapRepository, type TrapStats } from "../db/repository";
+import type { TrapStats } from "../db/repository";
 import {
   type Trap,
   type TrapDetails,
@@ -11,9 +10,15 @@ import {
   type TrapUpdate,
 } from "../domain/trap";
 import type { SearchMode, TrapStatus } from "./constants";
-import { createDefaultEmbeddingProvider, type EmbeddingProvider } from "./embedder";
-import { findProjectRoot } from "./scope";
+import { createDefaultEmbeddingProvider, embeddingConfig, type EmbeddingConfig, type EmbeddingProvider } from "./embedder";
+import { summarizeEmbeddingState, type EmbeddingStateSummary, type EmbeddingStatsResult } from "./embedding-health";
+import { normalizeScope, ScopedRepositoryContext, type ScopedRepository } from "./scope-context";
 import { importTrapArchive } from "./trap-archive";
+import {
+  resolveScopedMutation,
+  type AddTrapEvidenceResult,
+  type TrapMutationResult,
+} from "./trap-mutation-result";
 
 export {
   type TrapInput,
@@ -26,47 +31,51 @@ export {
   type TrapStats,
 };
 
-type Scope = "project" | "global";
+export type { EmbeddingStateSummary };
+export type TrapEmbeddingStats = EmbeddingStatsResult;
 
 export class TrapStore {
-  private projectRoot: string | null;
-  private globalRepository?: TrapRepository;
-  private projectRepository?: TrapRepository;
+  private readonly scopes: ScopedRepositoryContext;
   private readonly embedder?: EmbeddingProvider;
 
   constructor(cwd: string, embedder: EmbeddingProvider | undefined = createDefaultEmbeddingProvider()) {
-    this.projectRoot = findProjectRoot(cwd);
     this.embedder = embedder;
+    this.scopes = new ScopedRepositoryContext(cwd, embedder);
   }
 
   add(input: TrapInput): { id: number; scope: string } {
     const scope = normalizeScope(input.scope);
-    if (scope === "project" && !this.projectRoot) {
+    if (scope === "project" && !this.scopes.hasProject()) {
       throw new Error("Not in a project. Run 'codetrap init' first, or use --scope global.");
     }
 
-    const id = this.repositoryFor(scope).add({
+    const id = this.scopes.repositoryFor(scope).add({
       ...input,
       scope,
-      project_path: scope === "project" ? this.projectRoot : null,
+      project_path: scope === "project" ? this.scopes.projectRoot() : null,
     });
     return { id, scope };
   }
 
   async search(
     query: string,
-    opts: { category?: string; scope?: string; limit?: number; mode?: SearchMode; status?: TrapStatus | "all" } = {}
+    opts: { category?: string; scope?: string; limit?: number; mode?: SearchMode; status?: TrapStatus | "all"; path?: string; module?: string; owner?: string; rerank?: boolean; includeRankingSignals?: boolean } = {}
   ): Promise<{ results: TrapSearchResult[]; scope: string }[]> {
     const out: { results: TrapSearchResult[]; scope: string }[] = [];
     const limit = opts.limit ?? 20;
 
-    for (const scoped of this.repositoriesForRead(opts.scope)) {
+    for (const scoped of this.scopes.repositoriesForRead(opts.scope)) {
       const results = await scoped.repository.search(query, {
         category: opts.category,
         scope: scoped.scope,
         limit,
         mode: opts.mode ?? "hybrid",
         status: opts.status,
+        path: opts.path,
+        module: opts.module,
+        owner: opts.owner,
+        rerank: opts.rerank,
+        includeRankingSignals: opts.includeRankingSignals,
       });
       if (results.length > 0) out.push({ results, scope: scoped.scope });
     }
@@ -75,7 +84,7 @@ export class TrapStore {
   }
 
   get(id: number, scope?: string): { trap: Trap; scope: string } | null {
-    for (const scoped of this.repositoriesForRead(scope)) {
+    for (const scoped of this.scopes.repositoriesForRead(scope)) {
       const trap = scoped.repository.get(id);
       if (trap) return { trap, scope: scoped.scope };
     }
@@ -83,17 +92,17 @@ export class TrapStore {
   }
 
   getDetails(id: number, scope?: string): TrapDetails | null {
-    for (const scoped of this.repositoriesForRead(scope)) {
+    for (const scoped of this.scopes.repositoriesForRead(scope)) {
       const details = scoped.repository.getDetails(id, scoped.scope);
       if (details) return details;
     }
     return null;
   }
 
-  list(opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatus | "all" } = {}): { traps: Trap[]; scope: string }[] {
+  list(opts: { category?: string; scope?: string; limit?: number; offset?: number; status?: TrapStatus | "all"; path?: string; module?: string; owner?: string } = {}): { traps: Trap[]; scope: string }[] {
     const out: { traps: Trap[]; scope: string }[] = [];
 
-    for (const scoped of this.repositoriesForRead(opts.scope)) {
+    for (const scoped of this.scopes.repositoriesForRead(opts.scope)) {
       const traps = scoped.repository.list({ ...opts, scope: scoped.scope });
       if (traps.length > 0) out.push({ traps, scope: scoped.scope });
     }
@@ -101,36 +110,36 @@ export class TrapStore {
     return out;
   }
 
-  update(id: number, input: TrapUpdate, scope?: string): { scope: string; success: boolean } {
-    for (const scoped of this.repositoriesForWrite(scope)) {
-      const success = scoped.repository.update(id, input);
-      if (success || scope) return { scope: scoped.scope, success };
-    }
-    return { scope: "global", success: false };
+  update(id: number, input: TrapUpdate, scope?: string): TrapMutationResult {
+    return this.resolveMutation(scope, (scoped) => ({
+      success: scoped.repository.update(id, input),
+    }));
   }
 
-  delete(id: number, scope?: string): { scope: string; success: boolean } {
-    for (const scoped of this.repositoriesForWrite(scope)) {
-      const success = scoped.repository.delete(id);
-      if (success || scope) return { scope: scoped.scope, success };
-    }
-    return { scope: "global", success: false };
+  delete(id: number, scope?: string): TrapMutationResult {
+    return this.resolveMutation(scope, (scoped) => ({
+      success: scoped.repository.delete(id),
+    }));
   }
 
-  addEvidence(id: number, input: TrapEvidenceInput, scope?: string): { scope: string; evidence_id: number | null; success: boolean } {
-    for (const scoped of this.repositoriesForWrite(scope)) {
+  addEvidence(id: number, input: TrapEvidenceInput, scope?: string): AddTrapEvidenceResult {
+    return this.resolveMutation(
+      scope,
+      (scoped) => {
       const evidenceId = scoped.repository.addEvidence(id, input);
-      if (evidenceId || scope) return { scope: scoped.scope, evidence_id: evidenceId, success: evidenceId !== null };
-    }
-    return { scope: "global", evidence_id: null, success: false };
+        return {
+          evidence_id: evidenceId,
+          success: evidenceId !== null,
+        };
+      },
+      () => ({ evidence_id: null, success: false })
+    );
   }
 
-  archive(id: number, scope?: string): { scope: string; success: boolean } {
-    for (const scoped of this.repositoriesForWrite(scope)) {
-      const success = scoped.repository.archive(id);
-      if (success || scope) return { scope: scoped.scope, success };
-    }
-    return { scope: "global", success: false };
+  archive(id: number, scope?: string): TrapMutationResult {
+    return this.resolveMutation(scope, (scoped) => ({
+      success: scoped.repository.archive(id),
+    }));
   }
 
   supersede(
@@ -138,16 +147,14 @@ export class TrapStore {
     supersededById: number,
     scope?: string,
     stateKey?: string
-  ): { scope: string; success: boolean } {
-    for (const scoped of this.repositoriesForWrite(scope)) {
-      const success = scoped.repository.supersede(id, supersededById, stateKey);
-      if (success || scope) return { scope: scoped.scope, success };
-    }
-    return { scope: "global", success: false };
+  ): TrapMutationResult {
+    return this.resolveMutation(scope, (scoped) => ({
+      success: scoped.repository.supersede(id, supersededById, stateKey),
+    }));
   }
 
   hit(id: number, scope?: string): void {
-    for (const scoped of this.repositoriesForRead(scope)) {
+    for (const scoped of this.scopes.repositoriesForRead(scope)) {
       if (scope || scoped.repository.get(id)) {
         scoped.repository.hit(id);
         return;
@@ -157,17 +164,60 @@ export class TrapStore {
 
   topTraps(scope: string, limit = 20): Trap[] {
     const resolvedScope = normalizeScope(scope);
-    return this.repositoryFor(resolvedScope).top(resolvedScope, limit);
+    return this.scopes.repositoryFor(resolvedScope).top(resolvedScope, limit);
   }
 
-  stats(): { project: TrapStats | null; global: TrapStats } {
-    const project = this.projectRoot ? this.projectRepo().stats() : null;
-    return { project, global: this.globalRepo().stats() };
+  stats(opts: { scope?: string } = {}): { project: TrapStats | null; global: TrapStats | null } {
+    const scope = opts.scope ? normalizeScope(opts.scope) : null;
+    const project = scope === "global"
+      ? null
+      : this.scopes.repositoryEntry("project")?.repository.stats({ scope: "project" }) ?? null;
+    const global = scope === "project"
+      ? null
+      : this.scopes.repositoryFor("global").stats({ scope: "global" });
+    return { project, global };
+  }
+
+  embeddingStats(opts: { scope?: string } = {}): TrapEmbeddingStats {
+    const scope = opts.scope ? normalizeScope(opts.scope) : null;
+    const config = this.embeddingConfig();
+    const project = scope === "global"
+      ? null
+      : this.scopes.repositoryEntry("project")
+      ? summarizeEmbeddingState(this.scopes.repositoryFor("project").embeddingStats(config, { scope: "project" }), config)
+      : null;
+    const global = scope === "project"
+      ? null
+      : summarizeEmbeddingState(this.scopes.repositoryFor("global").embeddingStats(config, { scope: "global" }), config);
+    return {
+      project,
+      global,
+    };
+  }
+
+  diagnostics(): {
+    mis_scoped_traps: {
+      global_db_project_traps: Pick<Trap, "id" | "title" | "scope" | "project_path" | "status">[];
+    };
+  } {
+    return {
+      mis_scoped_traps: {
+        global_db_project_traps: this.scopes.repositoryFor("global")
+          .listMisScoped("global")
+          .map((trap) => ({
+            id: trap.id,
+            title: trap.title,
+            scope: trap.scope,
+            project_path: trap.project_path,
+            status: trap.status,
+          })),
+      },
+    };
   }
 
   exportAll(opts: { scope?: string } = {}): TrapExportRecord[] {
     const traps: TrapExportRecord[] = [];
-    for (const scoped of this.repositoriesForRead(opts.scope)) {
+    for (const scoped of this.scopes.repositoriesForRead(opts.scope)) {
       traps.push(...scoped.repository.exportAll());
     }
     return traps;
@@ -181,11 +231,23 @@ export class TrapStore {
   }
 
   hasProject(): boolean {
-    return this.projectRoot !== null;
+    return this.scopes.hasProject();
   }
 
   getProjectRoot(): string | null {
-    return this.projectRoot;
+    return this.scopes.projectRoot();
+  }
+
+  hasEmbeddingProvider(): boolean {
+    return this.embedder !== undefined;
+  }
+
+  embeddingConfig(): EmbeddingConfig | null {
+    return this.embedder ? embeddingConfig(this.embedder) : null;
+  }
+
+  forCwd(cwd: string): TrapStore {
+    return new TrapStore(cwd, this.embedder);
   }
 
   async ensureEmbeddings(opts: { scope?: string; category?: string; limit?: number; force?: boolean; batchSize?: number } = {}): Promise<{
@@ -199,7 +261,7 @@ export class TrapStore {
     let skipped = 0;
     let batches = 0;
 
-    for (const scoped of this.repositoriesForRead(opts.scope)) {
+    for (const scoped of this.scopes.repositoriesForRead(opts.scope)) {
       const result = await scoped.repository.ensureEmbeddings({
         scope: scoped.scope,
         category: opts.category,
@@ -216,57 +278,16 @@ export class TrapStore {
     return { generated, skipped, batches, scopes };
   }
 
-  private repositoriesForRead(scope?: string): { scope: Scope; repository: TrapRepository }[] {
-    const resolvedScope = optionalScope(scope);
-    if (resolvedScope) return this.repositoryEntry(resolvedScope) ? [this.repositoryEntry(resolvedScope)!] : [];
-
-    const repositories: { scope: Scope; repository: TrapRepository }[] = [];
-    const project = this.repositoryEntry("project");
-    if (project) repositories.push(project);
-    repositories.push({ scope: "global", repository: this.globalRepo() });
-    return repositories;
+  private resolveMutation<TExtra extends object = {}>(
+    scope: string | undefined,
+    mutate: (scoped: ScopedRepository) => { success: boolean } & TExtra,
+    fallback: () => { success: false } & TExtra = () => ({ success: false } as { success: false } & TExtra)
+  ): { scope: "project" | "global"; success: boolean } & TExtra {
+    return resolveScopedMutation(
+      this.scopes.repositoriesForWrite(scope),
+      { explicitScope: scope !== undefined },
+      mutate,
+      fallback
+    );
   }
-
-  private repositoriesForWrite(scope?: string): { scope: Scope; repository: TrapRepository }[] {
-    return this.repositoriesForRead(scope);
-  }
-
-  private repositoryEntry(scope: Scope): { scope: Scope; repository: TrapRepository } | null {
-    if (scope === "project") {
-      return this.projectRoot ? { scope, repository: this.projectRepo() } : null;
-    }
-    return { scope, repository: this.globalRepo() };
-  }
-
-  private repositoryFor(scope: Scope): TrapRepository {
-    if (scope === "project") return this.projectRepo();
-    return this.globalRepo();
-  }
-
-  private projectRepo(): TrapRepository {
-    if (!this.projectRoot) {
-      throw new Error("Not in a project. Run 'codetrap init' first, or use --scope global.");
-    }
-    if (!this.projectRepository) {
-      this.projectRepository = new TrapRepository(openProject(this.projectRoot), this.embedder);
-    }
-    return this.projectRepository;
-  }
-
-  private globalRepo(): TrapRepository {
-    if (!this.globalRepository) {
-      this.globalRepository = new TrapRepository(openGlobal(), this.embedder);
-    }
-    return this.globalRepository;
-  }
-}
-
-function normalizeScope(scope: string): Scope {
-  if (scope === "project" || scope === "global") return scope;
-  throw new Error(`Invalid scope: ${scope}`);
-}
-
-function optionalScope(scope?: string): Scope | null {
-  if (!scope) return null;
-  return normalizeScope(scope);
 }

package/src/lib/trap-archive.ts

@@ -1,17 +1,17 @@
 import {
-  buildTrapEvidenceInput,
-  type TrapEvidence,
   type TrapEvidenceInput,
-  type TrapExportEvidence,
   type TrapImportEvidence,
   type TrapImportRecord,
   type TrapInput,
 } from "../domain/trap";
 import {
-  parseEvidenceRelatedFiles,
-  parseOptionalEvidenceRelatedFiles,
-  parseOptionalTrapTags,
-} from "./trap-json-fields";
+  importEvidenceToTrapInput,
+  importRecordToTrapInput,
+  normalizeEvidenceForExport,
+  normalizeTrapForExport,
+} from "./trap-codec";
+
+export { normalizeEvidenceForExport, normalizeTrapForExport };
 
 export interface TrapArchiveImportAdapter {
   add(input: TrapInput): { id: number; scope: string };
@@ -22,13 +22,6 @@ export interface TrapArchiveImportAdapter {
   ): { scope: string; evidence_id: number | null; success: boolean };
 }
 
-export function normalizeEvidenceForExport(evidence: TrapEvidence): TrapExportEvidence {
-  return {
-    ...evidence,
-    related_files: parseEvidenceRelatedFiles(evidence.related_files),
-  };
-}
-
 export function importTrapArchive(
   records: TrapImportRecord[],
   adapter: TrapArchiveImportAdapter
@@ -36,7 +29,7 @@ export function importTrapArchive(
   let count = 0;
   for (const record of records) {
     try {
-      const result = adapter.add(toTrapInput(record));
+      const result = adapter.add(importRecordToTrapInput(record));
       importEvidenceRecords(record.evidence ?? [], result, adapter);
       count++;
     } catch {
@@ -55,7 +48,7 @@ function importEvidenceRecords(
     try {
       adapter.addEvidence(
         trap.id,
-        buildTrapEvidenceInput(toEvidenceInput(evidence)),
+        importEvidenceToTrapInput(evidence),
         trap.scope
       );
     } catch {
@@ -63,29 +56,3 @@ function importEvidenceRecords(
     }
   }
 }
-
-function toTrapInput(record: TrapImportRecord): TrapInput {
-  return {
-    title: record.title,
-    category: record.category,
-    tags: parseOptionalTrapTags(record.tags),
-    scope: record.scope,
-    context: record.context,
-    mistake: record.mistake,
-    fix: record.fix,
-    before_code: record.before_code ?? undefined,
-    after_code: record.after_code ?? undefined,
-    severity: record.severity ?? undefined,
-    project_path: record.project_path ?? undefined,
-  };
-}
-
-function toEvidenceInput(evidence: TrapImportEvidence): Record<string, unknown> {
-  return {
-    source_type: evidence.source_type,
-    source_ref: evidence.source_ref ?? undefined,
-    observed_at: evidence.observed_at ?? undefined,
-    related_files: parseOptionalEvidenceRelatedFiles(evidence.related_files),
-    note: evidence.note ?? undefined,
-  };
-}

package/src/lib/trap-codec.ts

@@ -0,0 +1,113 @@
+import type {
+  Trap,
+  TrapEvidence,
+  TrapEvidenceInput,
+  TrapExportEvidence,
+  TrapExportRecord,
+  TrapImportEvidence,
+  TrapImportRecord,
+  TrapInput,
+  TrapUpdate,
+} from "../domain/trap";
+import { buildTrapEvidenceInput } from "../domain/trap";
+import {
+  parseEvidenceRelatedFiles,
+  parseOptionalEvidenceRelatedFiles,
+  parseOptionalTrapPathGlobs,
+  parseOptionalTrapTags,
+  parseTrapPathGlobs,
+  parseTrapTags,
+  encodeTrapPathGlobs,
+  encodeTrapTags,
+} from "./trap-json-fields";
+import { buildTrapSearchText } from "./trap-search-document";
+
+export type JsonTrap = Omit<Trap, "tags" | "path_globs"> & {
+  tags: string[];
+  path_globs: string[];
+};
+
+export type JsonTrapEvidence = Omit<TrapEvidence, "related_files"> & {
+  related_files: string[];
+};
+
+export function toTrapJson(trap: Trap): JsonTrap {
+  return {
+    ...trap,
+    tags: parseTrapTags(trap.tags),
+    path_globs: parseTrapPathGlobs(trap.path_globs),
+  };
+}
+
+export function toTrapEvidenceJson(evidence: TrapEvidence): JsonTrapEvidence {
+  return {
+    ...evidence,
+    related_files: parseEvidenceRelatedFiles(evidence.related_files),
+  };
+}
+
+export function normalizeTrapForExport(trap: Trap): Omit<TrapExportRecord, "evidence"> {
+  return {
+    ...trap,
+    path_globs: parseTrapPathGlobs(trap.path_globs),
+  };
+}
+
+export function normalizeEvidenceForExport(evidence: TrapEvidence): TrapExportEvidence {
+  return {
+    ...evidence,
+    related_files: parseEvidenceRelatedFiles(evidence.related_files),
+  };
+}
+
+export function importRecordToTrapInput(record: TrapImportRecord): TrapInput {
+  return {
+    title: record.title,
+    category: record.category,
+    tags: parseOptionalTrapTags(record.tags),
+    scope: record.scope,
+    context: record.context,
+    mistake: record.mistake,
+    fix: record.fix,
+    before_code: record.before_code ?? undefined,
+    after_code: record.after_code ?? undefined,
+    severity: record.severity ?? undefined,
+    project_path: record.project_path ?? undefined,
+    path_globs: parseOptionalTrapPathGlobs(record.path_globs),
+    module: record.module ?? undefined,
+    owner: record.owner ?? undefined,
+  };
+}
+
+export function importEvidenceToTrapInput(evidence: TrapImportEvidence): TrapEvidenceInput {
+  return buildTrapEvidenceInput({
+    source_type: evidence.source_type,
+    source_ref: evidence.source_ref ?? undefined,
+    observed_at: evidence.observed_at ?? undefined,
+    related_files: parseOptionalEvidenceRelatedFiles(evidence.related_files),
+    note: evidence.note ?? undefined,
+  });
+}
+
+export function encodeTrapInsertFields(input: TrapInput): {
+  tags: string;
+  path_globs: string;
+  search_text: string;
+} {
+  const tags = encodeTrapTags(input.tags);
+  const pathGlobs = encodeTrapPathGlobs(input.path_globs);
+  return {
+    tags,
+    path_globs: pathGlobs,
+    search_text: buildTrapSearchText({ ...input, tags, path_globs: pathGlobs }),
+  };
+}
+
+export function mergeTrapUpdateForSearchText(current: Trap, input: TrapUpdate): Trap {
+  return {
+    ...current,
+    ...input,
+    tags: input.tags !== undefined ? encodeTrapTags(input.tags) : current.tags,
+    path_globs: input.path_globs !== undefined ? encodeTrapPathGlobs(input.path_globs) : current.path_globs,
+  };
+}

package/src/lib/trap-json-fields.ts

@@ -12,6 +12,18 @@ export function encodeTrapTags(value: TrapStringArrayInput): string {
   return JSON.stringify(parseTrapTags(value));
 }
 
+export function parseTrapPathGlobs(value: TrapStringArrayInput): string[] {
+  return parseStringArrayField(value);
+}
+
+export function parseOptionalTrapPathGlobs(value: TrapStringArrayInput): string[] | undefined {
+  return emptyToUndefined(parseTrapPathGlobs(value));
+}
+
+export function encodeTrapPathGlobs(value: TrapStringArrayInput): string {
+  return JSON.stringify(parseTrapPathGlobs(value));
+}
+
 export function parseEvidenceRelatedFiles(value: TrapStringArrayInput): string[] {
   return parseStringArrayField(value);
 }

package/src/lib/trap-lifecycle.ts

@@ -0,0 +1,37 @@
+import type { Trap } from "../domain/trap";
+
+export type TrapLifecycleAdapter = {
+  get(id: number): Trap | null;
+  transaction<T>(callback: () => T): T;
+  markArchived(id: number): boolean;
+  markSuperseded(id: number, stateKey: string): boolean;
+  markSuperseding(id: number, supersedesId: number, stateKey: string): boolean;
+};
+
+export function archiveTrapLifecycle(adapter: TrapLifecycleAdapter, id: number): boolean {
+  return adapter.markArchived(id);
+}
+
+export function supersedeTrapLifecycle(
+  adapter: TrapLifecycleAdapter,
+  id: number,
+  supersededById: number,
+  stateKey?: string
+): boolean {
+  if (id === supersededById) return false;
+
+  const oldTrap = adapter.get(id);
+  const newTrap = adapter.get(supersededById);
+  if (!oldTrap || !newTrap) return false;
+
+  const key = lifecycleStateKey(oldTrap, newTrap, stateKey);
+  return adapter.transaction(() => {
+    adapter.markSuperseded(id, key);
+    adapter.markSuperseding(supersededById, id, key);
+    return true;
+  });
+}
+
+export function lifecycleStateKey(oldTrap: Trap, newTrap: Trap, requested?: string): string {
+  return requested ?? oldTrap.state_key ?? newTrap.state_key ?? `trap:${oldTrap.id}`;
+}

package/src/lib/trap-mutation-result.ts

@@ -0,0 +1,36 @@
+import type { Scope } from "./constants";
+
+export type TrapMutationResult = {
+  scope: Scope;
+  success: boolean;
+};
+
+export type AddTrapEvidenceResult = TrapMutationResult & {
+  evidence_id: number | null;
+};
+
+export type ScopedMutationTarget = {
+  scope: Scope;
+};
+
+export function resolveScopedMutation<TTarget extends ScopedMutationTarget, TExtra extends object>(
+  targets: TTarget[],
+  opts: { explicitScope: boolean; fallbackScope?: Scope },
+  mutate: (target: TTarget) => { success: boolean } & TExtra,
+  fallback: () => { success: false } & TExtra
+): ({ scope: Scope; success: boolean } & TExtra) {
+  for (const target of targets) {
+    const result = mutate(target);
+    if (result.success || opts.explicitScope) {
+      return { scope: target.scope, ...result };
+    }
+  }
+  return { scope: opts.fallbackScope ?? "global", ...fallback() };
+}
+
+export function mutationJsonPayload<T extends { success: boolean }>(
+  value: T,
+  error: string
+): T | (T & { error: string }) {
+  return value.success ? value : { ...value, error };
+}