[Bug]: SQLError Failed to execute OrchestrationCommandReceiptRepository.upsert.query

[Sy-D]

Before submitting

• I searched existing issues and did not find a duplicate.
• I included enough detail to reproduce or investigate the problem.

Area

apps/desktop

Steps to reproduce

Couldnt replicate for now.

Expected behavior

No error.

Actual behavior

Impact

Minor bug or occasional failure

Version or commit

0.0.30-nightly.20260728.931

Environment

macOS 26.3

Logs or stack traces

Screenshots, recordings, or supporting files

No response

Workaround

No response

[Sy-D]

I dug into this against 1b4830ff0. Short version: the message cannot show its own cause, so the screenshot alone can never identify the root failure.

Why the message is empty of information

apps/server/src/persistence/Errors.ts:41

override get message(): string {
  return this.detail === undefined
    ? `SQL error in ${this.operation}`
    : `SQL error in ${this.operation}: ${this.detail}`;
}

apps/server/src/persistence/Errors.ts:76

export function toPersistenceSqlError(operation: string) {
  return (cause: unknown): PersistenceSqlError =>
    new PersistenceSqlError({
      operation,
      detail: `Failed to execute ${operation}`,
      cause,
    });
}

detail restates operation, so the rendered message is the operation name twice. The real failure is captured in cause, it just never reaches the message.

Worth noting: Errors.test.ts already contains a test named "keeps SQL operation context without a tautological detail", which constructs the error without a detail and asserts the message is SQL error in AuthSessionRepository.list:query. The intent is documented and tested; toPersistenceSqlError is the path that does not honour it, and it is the path this repository uses.

Which call site produced it

Two callers of OrchestrationCommandReceiptRepository.upsert:

• OrchestrationEngine.ts:281 — the rejected-command path, which ends in .pipe(Effect.catch(() => Effect.void)). It cannot surface anything.
• OrchestrationEngine.ts:190 — the accepted-command path, running inside withTransaction alongside eventStore.append and the projection pipeline.

So this came from the accepted path, mid-transaction.

What I deliberately cannot conclude

The underlying cause. Given the upsert runs inside a transaction with other writers, SQLITE_BUSY / "database is locked" is plausible. So is a Request schema encode failure, which toPersistenceSqlError would relabel as a "SQL error" despite not being one. Those two want opposite fixes, and the current message cannot distinguish them — which is presumably why this is filed as not reproducible.

Proposed first step

Make the failure diagnosable: drop the tautological detail and surface the actual cause instead, so the next occurrence names SQLITE_BUSY or the parse failure outright.

Two things I would want a maintainer's view on before opening a PR:

1. Blast radius. toPersistenceSqlError shapes every persistence error message in the app. The diff is small; the effect is broad.
2. The payload rule. The neighbouring test "maps schema errors without copying rejected payloads into diagnostics" establishes that rejected values must not leak into diagnostics. A SQLite driver message is safe, but a schema error can carry values, so the change has to distinguish them rather than copy cause.message blindly.

This would not fix the SQL failure itself — it makes it findable. Happy to open that PR if the direction is agreeable, and to follow up on the real cause once an occurrence reports one.

[Sy-D]

Opened #4837 for the first step described above.

It does not fix the SQL failure — it stops the message from hiding it. SQLITE_BUSY or a schema encode failure will now name itself, and the two are distinguishable, which they were not before.

Both caveats I raised are handled in the PR: a schema cause contributes only issue tags so no rejected value can reach the message, with a test asserting it, and the broad reach of the mapper is called out for a deliberate look rather than slipped through.

I will follow up on the underlying failure once an occurrence reports an actual cause.