[codex] Structure checkpoint diff failures

[juliusmarminge]

Summary

• replace generic checkpoint detail errors with distinct Schema-backed failure types
• attach operation, thread, turn-range, and checkpoint-position context
• keep existing caller-facing messages while narrowing store error types

Validation

• vp test apps/server/src/checkpointing/Errors.test.ts apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Localized error-model refactor in checkpoint diff query paths; behavior and messages are preserved and covered by tests, with no auth or data-path changes.

Overview
Replaces CheckpointInvariantError and CheckpointUnavailableError with five Schema-backed tagged errors in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError. Each carries operation, threadId, and scenario-specific fields (turn range, from/to checkpoint side) instead of free-form detail strings.

CheckpointDiffQuery now fails with the matching type at each validation step in getTurnDiff and getFullThreadDiff. User-facing message text is derived from that context and stays aligned with prior wording (including the “Checkpoint invariant violation in …” prefix where applicable).

CheckpointStoreError is narrowed to VcsError only; diff-layer failures are listed on CheckpointServiceError. Adds Errors.test.ts for message derivation and tightens the missing-thread test to assert CheckpointThreadNotFoundError shape and message.

^{Reviewed by Cursor Bugbot for commit 779124a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic checkpoint errors with structured error classes in CheckpointDiffQuery

• Introduces five new TaggedError subclasses in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError.
• Each error carries structured fields (e.g. operation, threadId, requestedTurnCount, availableTurnCount, checkpoint) and derives a human-readable message from them.
• getTurnDiff and getFullThreadDiff in CheckpointDiffQuery.ts now throw these specific errors instead of the removed generic CheckpointInvariantError and CheckpointUnavailableError.
• CheckpointServiceError is updated to include the new error classes; CheckpointStoreError is narrowed to VcsError only.
• Behavioral Change: callers catching CheckpointInvariantError or CheckpointUnavailableError will no longer match these error paths.

^{Macroscope summarized 779124a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2fdbd171-a438-4e6a-94f7-575a07d26349

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-checkpoint-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

Mechanical refactor replacing generic error classes with more specific, structured error types. No business logic changes - same error conditions, just with typed fields for better error reporting and handling.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

Summary

• replace generic checkpoint detail errors with distinct Schema-backed failure types
• attach operation, thread, turn-range, and checkpoint-position context
• keep existing caller-facing messages while narrowing store error types

Validation

• vp test apps/server/src/checkpointing/Errors.test.ts apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Localized error-model refactor in checkpoint diff query paths; behavior and messages are preserved and covered by tests, with no auth or data-path changes.

Overview
Replaces CheckpointInvariantError and CheckpointUnavailableError with five Schema-backed tagged errors in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError. Each carries operation, threadId, and scenario-specific fields (turn range, from/to checkpoint side) instead of free-form detail strings.

CheckpointDiffQuery now fails with the matching type at each validation step in getTurnDiff and getFullThreadDiff. User-facing message text is derived from that context and stays aligned with prior wording (including the “Checkpoint invariant violation in …” prefix where applicable).

CheckpointStoreError is narrowed to VcsError only; diff-layer failures are listed on CheckpointServiceError. Adds Errors.test.ts for message derivation and tightens the missing-thread test to assert CheckpointThreadNotFoundError shape and message.

^{Reviewed by Cursor Bugbot for commit 779124a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic checkpoint errors with structured error classes in CheckpointDiffQuery

• Introduces five new TaggedError subclasses in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError.
• Each error carries structured fields (e.g. operation, threadId, requestedTurnCount, availableTurnCount, checkpoint) and derives a human-readable message from them.
• getTurnDiff and getFullThreadDiff in CheckpointDiffQuery.ts now throw these specific errors instead of the removed generic CheckpointInvariantError and CheckpointUnavailableError.
• CheckpointServiceError is updated to include the new error classes; CheckpointStoreError is narrowed to VcsError only.
• Behavioral Change: callers catching CheckpointInvariantError or CheckpointUnavailableError will no longer match these error paths.

^{Macroscope summarized 779124a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2fdbd171-a438-4e6a-94f7-575a07d26349

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-checkpoint-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

Mechanical refactor replacing generic error classes with more specific, structured error types. No business logic changes - same error conditions, just with typed fields for better error reporting and handling.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

Summary

• replace generic checkpoint detail errors with distinct Schema-backed failure types
• attach operation, thread, turn-range, and checkpoint-position context
• keep existing caller-facing messages while narrowing store error types

Validation

• vp test apps/server/src/checkpointing/Errors.test.ts apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Localized error-model refactor in checkpoint diff query paths; behavior and messages are preserved and covered by tests, with no auth or data-path changes.

Overview
Replaces CheckpointInvariantError and CheckpointUnavailableError with five Schema-backed tagged errors in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError. Each carries operation, threadId, and scenario-specific fields (turn range, from/to checkpoint side) instead of free-form detail strings.

CheckpointDiffQuery now fails with the matching type at each validation step in getTurnDiff and getFullThreadDiff. User-facing message text is derived from that context and stays aligned with prior wording (including the “Checkpoint invariant violation in …” prefix where applicable).

CheckpointStoreError is narrowed to VcsError only; diff-layer failures are listed on CheckpointServiceError. Adds Errors.test.ts for message derivation and tightens the missing-thread test to assert CheckpointThreadNotFoundError shape and message.

^{Reviewed by Cursor Bugbot for commit 779124a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic checkpoint errors with structured error classes in CheckpointDiffQuery

• Introduces five new TaggedError subclasses in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError.
• Each error carries structured fields (e.g. operation, threadId, requestedTurnCount, availableTurnCount, checkpoint) and derives a human-readable message from them.
• getTurnDiff and getFullThreadDiff in CheckpointDiffQuery.ts now throw these specific errors instead of the removed generic CheckpointInvariantError and CheckpointUnavailableError.
• CheckpointServiceError is updated to include the new error classes; CheckpointStoreError is narrowed to VcsError only.
• Behavioral Change: callers catching CheckpointInvariantError or CheckpointUnavailableError will no longer match these error paths.

^{Macroscope summarized 779124a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2fdbd171-a438-4e6a-94f7-575a07d26349

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-checkpoint-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

Mechanical refactor replacing generic error classes with more specific, structured error types. No business logic changes - same error conditions, just with typed fields for better error reporting and handling.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

Summary

• replace generic checkpoint detail errors with distinct Schema-backed failure types
• attach operation, thread, turn-range, and checkpoint-position context
• keep existing caller-facing messages while narrowing store error types

Validation

• vp test apps/server/src/checkpointing/Errors.test.ts apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Localized error-model refactor in checkpoint diff query paths; behavior and messages are preserved and covered by tests, with no auth or data-path changes.

Overview
Replaces CheckpointInvariantError and CheckpointUnavailableError with five Schema-backed tagged errors in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError. Each carries operation, threadId, and scenario-specific fields (turn range, from/to checkpoint side) instead of free-form detail strings.

CheckpointDiffQuery now fails with the matching type at each validation step in getTurnDiff and getFullThreadDiff. User-facing message text is derived from that context and stays aligned with prior wording (including the “Checkpoint invariant violation in …” prefix where applicable).

CheckpointStoreError is narrowed to VcsError only; diff-layer failures are listed on CheckpointServiceError. Adds Errors.test.ts for message derivation and tightens the missing-thread test to assert CheckpointThreadNotFoundError shape and message.

^{Reviewed by Cursor Bugbot for commit 779124a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic checkpoint errors with structured error classes in CheckpointDiffQuery

• Introduces five new TaggedError subclasses in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError.
• Each error carries structured fields (e.g. operation, threadId, requestedTurnCount, availableTurnCount, checkpoint) and derives a human-readable message from them.
• getTurnDiff and getFullThreadDiff in CheckpointDiffQuery.ts now throw these specific errors instead of the removed generic CheckpointInvariantError and CheckpointUnavailableError.
• CheckpointServiceError is updated to include the new error classes; CheckpointStoreError is narrowed to VcsError only.
• Behavioral Change: callers catching CheckpointInvariantError or CheckpointUnavailableError will no longer match these error paths.

^{Macroscope summarized 779124a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2fdbd171-a438-4e6a-94f7-575a07d26349

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-checkpoint-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

Mechanical refactor replacing generic error classes with more specific, structured error types. No business logic changes - same error conditions, just with typed fields for better error reporting and handling.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

Summary

• replace generic checkpoint detail errors with distinct Schema-backed failure types
• attach operation, thread, turn-range, and checkpoint-position context
• keep existing caller-facing messages while narrowing store error types

Validation

• vp test apps/server/src/checkpointing/Errors.test.ts apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Localized error-model refactor in checkpoint diff query paths; behavior and messages are preserved and covered by tests, with no auth or data-path changes.

Overview
Replaces CheckpointInvariantError and CheckpointUnavailableError with five Schema-backed tagged errors in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError. Each carries operation, threadId, and scenario-specific fields (turn range, from/to checkpoint side) instead of free-form detail strings.

CheckpointDiffQuery now fails with the matching type at each validation step in getTurnDiff and getFullThreadDiff. User-facing message text is derived from that context and stays aligned with prior wording (including the “Checkpoint invariant violation in …” prefix where applicable).

CheckpointStoreError is narrowed to VcsError only; diff-layer failures are listed on CheckpointServiceError. Adds Errors.test.ts for message derivation and tightens the missing-thread test to assert CheckpointThreadNotFoundError shape and message.

^{Reviewed by Cursor Bugbot for commit 779124a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic checkpoint errors with structured error classes in CheckpointDiffQuery

• Introduces five new TaggedError subclasses in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError.
• Each error carries structured fields (e.g. operation, threadId, requestedTurnCount, availableTurnCount, checkpoint) and derives a human-readable message from them.
• getTurnDiff and getFullThreadDiff in CheckpointDiffQuery.ts now throw these specific errors instead of the removed generic CheckpointInvariantError and CheckpointUnavailableError.
• CheckpointServiceError is updated to include the new error classes; CheckpointStoreError is narrowed to VcsError only.
• Behavioral Change: callers catching CheckpointInvariantError or CheckpointUnavailableError will no longer match these error paths.

^{Macroscope summarized 779124a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2fdbd171-a438-4e6a-94f7-575a07d26349

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-checkpoint-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

Mechanical refactor replacing generic error classes with more specific, structured error types. No business logic changes - same error conditions, just with typed fields for better error reporting and handling.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

Summary

• replace generic checkpoint detail errors with distinct Schema-backed failure types
• attach operation, thread, turn-range, and checkpoint-position context
• keep existing caller-facing messages while narrowing store error types

Validation

• vp test apps/server/src/checkpointing/Errors.test.ts apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Localized error-model refactor in checkpoint diff query paths; behavior and messages are preserved and covered by tests, with no auth or data-path changes.

Overview
Replaces CheckpointInvariantError and CheckpointUnavailableError with five Schema-backed tagged errors in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError. Each carries operation, threadId, and scenario-specific fields (turn range, from/to checkpoint side) instead of free-form detail strings.

CheckpointDiffQuery now fails with the matching type at each validation step in getTurnDiff and getFullThreadDiff. User-facing message text is derived from that context and stays aligned with prior wording (including the “Checkpoint invariant violation in …” prefix where applicable).

CheckpointStoreError is narrowed to VcsError only; diff-layer failures are listed on CheckpointServiceError. Adds Errors.test.ts for message derivation and tightens the missing-thread test to assert CheckpointThreadNotFoundError shape and message.

^{Reviewed by Cursor Bugbot for commit 779124a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic checkpoint errors with structured error classes in CheckpointDiffQuery

• Introduces five new TaggedError subclasses in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError.
• Each error carries structured fields (e.g. operation, threadId, requestedTurnCount, availableTurnCount, checkpoint) and derives a human-readable message from them.
• getTurnDiff and getFullThreadDiff in CheckpointDiffQuery.ts now throw these specific errors instead of the removed generic CheckpointInvariantError and CheckpointUnavailableError.
• CheckpointServiceError is updated to include the new error classes; CheckpointStoreError is narrowed to VcsError only.
• Behavioral Change: callers catching CheckpointInvariantError or CheckpointUnavailableError will no longer match these error paths.

^{Macroscope summarized 779124a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2fdbd171-a438-4e6a-94f7-575a07d26349

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-checkpoint-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

Mechanical refactor replacing generic error classes with more specific, structured error types. No business logic changes - same error conditions, just with typed fields for better error reporting and handling.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

Summary

• replace generic checkpoint detail errors with distinct Schema-backed failure types
• attach operation, thread, turn-range, and checkpoint-position context
• keep existing caller-facing messages while narrowing store error types

Validation

• vp test apps/server/src/checkpointing/Errors.test.ts apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Localized error-model refactor in checkpoint diff query paths; behavior and messages are preserved and covered by tests, with no auth or data-path changes.

Overview
Replaces CheckpointInvariantError and CheckpointUnavailableError with five Schema-backed tagged errors in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError. Each carries operation, threadId, and scenario-specific fields (turn range, from/to checkpoint side) instead of free-form detail strings.

CheckpointDiffQuery now fails with the matching type at each validation step in getTurnDiff and getFullThreadDiff. User-facing message text is derived from that context and stays aligned with prior wording (including the “Checkpoint invariant violation in …” prefix where applicable).

CheckpointStoreError is narrowed to VcsError only; diff-layer failures are listed on CheckpointServiceError. Adds Errors.test.ts for message derivation and tightens the missing-thread test to assert CheckpointThreadNotFoundError shape and message.

^{Reviewed by Cursor Bugbot for commit 779124a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic checkpoint errors with structured error classes in CheckpointDiffQuery

• Introduces five new TaggedError subclasses in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError.
• Each error carries structured fields (e.g. operation, threadId, requestedTurnCount, availableTurnCount, checkpoint) and derives a human-readable message from them.
• getTurnDiff and getFullThreadDiff in CheckpointDiffQuery.ts now throw these specific errors instead of the removed generic CheckpointInvariantError and CheckpointUnavailableError.
• CheckpointServiceError is updated to include the new error classes; CheckpointStoreError is narrowed to VcsError only.
• Behavioral Change: callers catching CheckpointInvariantError or CheckpointUnavailableError will no longer match these error paths.

^{Macroscope summarized 779124a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2fdbd171-a438-4e6a-94f7-575a07d26349

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-checkpoint-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

Mechanical refactor replacing generic error classes with more specific, structured error types. No business logic changes - same error conditions, just with typed fields for better error reporting and handling.

^{You can customize Macroscope's approvability policy. Learn more.}

[juliusmarminge]

Summary

• replace generic checkpoint detail errors with distinct Schema-backed failure types
• attach operation, thread, turn-range, and checkpoint-position context
• keep existing caller-facing messages while narrowing store error types

Validation

• vp test apps/server/src/checkpointing/Errors.test.ts apps/server/src/checkpointing/CheckpointDiffQuery.test.ts
• vp check
• vp run typecheck

---

Note

Low Risk
Localized error-model refactor in checkpoint diff query paths; behavior and messages are preserved and covered by tests, with no auth or data-path changes.

Overview
Replaces CheckpointInvariantError and CheckpointUnavailableError with five Schema-backed tagged errors in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError. Each carries operation, threadId, and scenario-specific fields (turn range, from/to checkpoint side) instead of free-form detail strings.

CheckpointDiffQuery now fails with the matching type at each validation step in getTurnDiff and getFullThreadDiff. User-facing message text is derived from that context and stays aligned with prior wording (including the “Checkpoint invariant violation in …” prefix where applicable).

CheckpointStoreError is narrowed to VcsError only; diff-layer failures are listed on CheckpointServiceError. Adds Errors.test.ts for message derivation and tightens the missing-thread test to assert CheckpointThreadNotFoundError shape and message.

^{Reviewed by Cursor Bugbot for commit 779124a. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Replace generic checkpoint errors with structured error classes in CheckpointDiffQuery

• Introduces five new TaggedError subclasses in Errors.ts: CheckpointDiffResultInvalidError, CheckpointThreadNotFoundError, CheckpointWorkspacePathMissingError, CheckpointTurnRangeUnavailableError, and CheckpointRefUnavailableError.
• Each error carries structured fields (e.g. operation, threadId, requestedTurnCount, availableTurnCount, checkpoint) and derives a human-readable message from them.
• getTurnDiff and getFullThreadDiff in CheckpointDiffQuery.ts now throw these specific errors instead of the removed generic CheckpointInvariantError and CheckpointUnavailableError.
• CheckpointServiceError is updated to include the new error classes; CheckpointStoreError is narrowed to VcsError only.
• Behavioral Change: callers catching CheckpointInvariantError or CheckpointUnavailableError will no longer match these error paths.

^{Macroscope summarized 779124a.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

Run ID: 2fdbd171-a438-4e6a-94f7-575a07d26349

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/structure-checkpoint-errors

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[macroscopeapp]

Approvability

Verdict: Approved

Mechanical refactor replacing generic error classes with more specific, structured error types. No business logic changes - same error conditions, just with typed fields for better error reporting and handling.

^{You can customize Macroscope's approvability policy. Learn more.}