feat(ext-api): phase stop endpoint (#1290) by zbnerd · Pull Request #1300 · zbnerd/probabilistic-valuation-engine

zbnerd · 2026-06-18T06:54:52Z

Summary

Adds POST /api/internal/stop/phase/{phaseName} to gracefully halt an in-flight ext-api phase at its chunk/page boundary
Phase transitions to STOPPED (new terminal value) on stop; slot record persists, next acquire overwrites
Cross-phase safe: stop on phase A does not affect phase B
Per-phase AtomicBoolean map (PhaseStopSignal) checked at every batch/page boundary
PhaseStoppedException thrown by phase beans, caught specifically in scheduler whenComplete handlers

Spec

docs/superpowers/specs/2026-06-18-issue-1290-phase-stop-endpoint-design.md
docs/superpowers/plans/2026-06-18-issue-1290-phase-stop-endpoint.md

Components

PhaseStopSignal — ConcurrentHashMap<PipelinePhase, AtomicBoolean> with CAS requestStop
PhaseStoppedException — control-flow signal (not BaseException; not an error)
PipelinePhase.STOPPED — new terminal enum value
RunStatus.isTerminal — extended to include STOPPED
RunStatusTracker.stopRun — terminal-but-retainable (slot persists, next acquire overwrites)
Each of 4 phase beans — injects signal, checks at chunk/page boundary, throws PhaseStoppedException
ExternalApiScheduler.requestPhaseStop — sets the flag if slot has non-terminal run
ExternalApiScheduler.runXxxPhase whenComplete — 3 branches: STOPPED → stopRun + clear, exception → failRun + release + clear, success → completeRun + clear
InternalApiController.stopPhase — POST endpoint (202 STOP_REQUESTED, 200 NOT_RUNNING, 400 INVALID_PHASE)

Acceptance criteria

POST /api/internal/stop/phase/ITEM_EQUIPMENT halts within one chunk boundary (≤30s) — BatchFetchSupport loop-top check
Same endpoint works for each phase
Stopped phase shows phase=STOPPED in /run-status, terminal
Not-running returns 200 NOT_RUNNING (not 404/409)
No half-written chunks in MinIO (ChunkedSnapshotSink atomic temp-file move)
A new phase can be triggered immediately after a stop (terminal-overwrite CAS)
Existing daily unaffected by stop on different phase (per-phase flag)

Test plan

./gradlew :module-external-api:compileKotlin :module-external-api:compileJava --continue BUILD SUCCESSFUL
./gradlew :module-external-api:test BUILD SUCCESSFUL — all tests pass
Manual smoke test deferred (Nexon API in maintenance, per [ext-api] Phase trigger endpoint: HTTP API for running a single phase standalone #1289 precedent)

🤖 Generated with Claude Code

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…ponse Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The default value '= PipelinePhase.IDLE' added in 2221e23 defeated the spec's intended compile-failure handshake between T5 and T8/T9. Removing it so T8/T9 must add 'phase = PipelinePhase.XXX' to existing call sites before the build is restored. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…ase ctor Follows the same fix applied in T6 (RankingFetchPhase) — T7 missed updating this test file when adding the stopSignal ctor param. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The check was in processPages, but execute() reads chunkingProperties before invoking processPages — NPE on mocked configFor fired before the stop check could trip. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…dling Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Thread.sleep(5) is a no-op with Clock.fixed — Instant.now(clock) returns the same value every call. The two ordering-dependent tests relied on distinct startedAt timestamps but with fixed clock the values were identical, exposing hash-iteration-order dependence. Use a per-test advancing Clock for these two tests. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4cdb650579

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-18T06:57:52Z

+        if (stopSignal.isStopRequested(PipelinePhase.RANKING_FETCH)) {
+            throw PhaseStoppedException(PipelinePhase.RANKING_FETCH)
+        }


Poll the stop flag inside ranking page processing

When /api/internal/stop/phase/RANKING_FETCH is called after execute has already started, requestPhaseStop sets the flag but this phase only checks it once before any page work begins. processPages then recursively fetches all remaining pages without consulting stopSignal, so the stop endpoint can return 202 while the current ranking run continues to completion and is marked COMPLETED; polling at each page boundary, like the other phases do at batch boundaries, is needed.

Useful? React with 👍 / 👎.

chatgpt-codex-connector · 2026-06-18T06:57:52Z

+        val hadNonTerminal = runStatusTracker.hasNonTerminalRun(phase) != null
+        if (hadNonTerminal) {
+            stopSignal.requestStop(phase)


Avoid leaving stale stop flags after completion races

If a stop request races with normal phase completion, hasNonTerminalRun can observe the run before the phase's whenComplete clears the signal, then requestStop sets the flag after that clear has already happened. That stale flag makes later stop calls report STOP_REQUESTED even with no running slot, and the next run of the same phase can stop immediately before doing work; recheck the slot after setting the flag or bind the signal to the observed runId.

Useful? React with 👍 / 👎.

Consolidate 4 near-identical whenComplete blocks (runRankingPhase, runOcidPhase, runCharBasicPhase, runItemEquipmentPhase) into a single private helper. Behavior unchanged: stop/fail/success branches with per-phase metrics drain and signal clear in all branches. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

…abasic ExternalApiSchedulerStopTest previously exercised only runItemEquipmentPhase's stop/fail/success branches. After extracting handlePhaseTerminal helper, all 4 phases share the same logic, but per-phase dispatch (enum + label) is still per-method. Add thin regression tests for the other 3 phases. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The isStopRequested fallback was defensive but unreachable — flag is only set inside the hadNonTerminal branch and cleared in all 3 whenComplete branches, so hadNonTerminal=false implies isStopRequested=false. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

zbnerd · 2026-06-19T04:18:14Z

@codex review

chatgpt-codex-connector · 2026-06-19T04:18:22Z

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

zbnerd and others added 18 commits June 18, 2026 07:12

docs(spec): issue #1290 phase stop endpoint design

28ab2dc

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs(plan): issue #1290 phase stop endpoint implementation plan

ee9bde8

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs(plan): drain SchedulerMetrics on stop + echo airflowRunId in res…

fa3a88f

…ponse Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): add STOPPED to PipelinePhase + extend isTerminal

f4aa2e9

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): add PhaseStoppedException

05b44ec

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): add PhaseStopSignal component

525dbd4

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): add RunStatusTracker.stopRun

314c6be

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): BatchFetchSupport phase-aware stop check

2221e23

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): RankingFetchPhase stop boundary check

5c0f9ea

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): OcidLookupPhase stop boundary check

b7313b4

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): CharacterBasicFetchPhase wires ctx.phase

e31bbf9

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): ItemEquipmentFetchPhase wires ctx.phase

8c5a464

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test(ext-api): wire stopSignal into DataflowContractTest OcidLookupPh…

12a5020

…ase ctor Follows the same fix applied in T6 (RankingFetchPhase) — T7 missed updating this test file when adding the stopSignal ctor param. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): scheduler requestPhaseStop + PhaseStoppedException han…

74727ac

…dling Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

feat(ext-api): POST /api/internal/stop/phase/{phaseName} endpoint

4cdb650

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

chatgpt-codex-connector Bot reviewed Jun 18, 2026

View reviewed changes

zbnerd and others added 3 commits June 18, 2026 09:01

zbnerd merged commit a8653e0 into develop Jun 18, 2026

zbnerd mentioned this pull request Jun 18, 2026

[ext-api] Phase stop endpoint: gracefully halt a running phase #1290

Closed

7 tasks

zbnerd deleted the feature/issue-1290-stop-endpoint branch June 18, 2026 07:21

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(ext-api): phase stop endpoint (#1290)#1300

feat(ext-api): phase stop endpoint (#1290)#1300
zbnerd merged 21 commits into
developfrom
feature/issue-1290-stop-endpoint

zbnerd commented Jun 18, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 18, 2026

Uh oh!

chatgpt-codex-connector Bot Jun 18, 2026

Uh oh!

zbnerd commented Jun 19, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

zbnerd commented Jun 18, 2026

Summary

Spec

Components

Acceptance criteria

Test plan

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector Bot Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

zbnerd commented Jun 19, 2026

Uh oh!

chatgpt-codex-connector Bot commented Jun 19, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant