Skip to content

fix(web Wave 8 W8-8): documents-table polling stale enum strings#1768

Merged
earayu merged 1 commit into
mainfrom
fix/w8-task-w8-8-documents-table-polling-enum
Apr 28, 2026
Merged

fix(web Wave 8 W8-8): documents-table polling stale enum strings#1768
earayu merged 1 commit into
mainfrom
fix/w8-task-w8-8-documents-table-polling-enum

Conversation

@earayu
Copy link
Copy Markdown
Collaborator

@earayu earayu commented Apr 28, 2026

Summary

Replace NON_TERMINAL_INDEX_STATUSES Set with the live four-value enum members so document polling actually identifies in-progress index work instead of silently never matching.

Bug

web/src/app/workspace/collections/[collectionId]/documents/documents-table.tsx declared the Set as `(PENDING, CREATING, DELETING, DELETION_IN_PROGRESS)` — three of those four literals were retired when the backend simplified the per-modality index enum to `(PENDING, RUNNING, ACTIVE, FAILED)`. The Set is typed `Set` so tsc never flagged the drift, but `hasNonTerminalDocumentState` would only ever match `'PENDING'` in practice; documents transitioning through the new `'RUNNING'` state were treated as terminal, so the table fell out of fast-poll mode while indexing was still active.

W8-8 sediment from PR #1766 (task #15) findings: type-drift fixed in #1766 is type-safe but did not catch behavior-drift hidden behind `Set` / `Array` literals. Architect msg=ec02b580 authorised this short-term follow-up at own cadence.

§K.12 invariant cross-check

Largely n/a (frontend behavioral fix). Direct hit:

4-pattern pre-check matrix

  • Pattern 1 v1 (legacy enum literals in this file): `rg "CREATING|DELETION_IN_PROGRESS" documents-table.tsx` returns zero. The remaining `'DELETING'` literal in the other Set (`NON_TERMINAL_DOCUMENT_STATUSES`, line 67) belongs to the separate eight-value `Document.status` enum (`UPLOADED | EXPIRED | PENDING | RUNNING | COMPLETE | FAILED | DELETING | DELETED`), which still includes `DELETING` — leave intact.
  • Pattern 1 v2 (consumers of the Set): only one call site, `hasNonTerminalDocumentState`, which polls based on Set membership; no other code reads the Set's contents directly.
  • Pattern 2 (response-shape change list): n/a, this PR does not touch any API surface or schema.
  • Pattern 3 (additive helpers): n/a, value-set narrowing only.

simple-stable directive 4-guardrail

  • feat/frontend #1 不无限扩范围 — single-file two-string Set sweep, ~5 LOC diff. Did not extend to refactor the polling logic or re-derive the Set from the OpenAPI enum (future cleanup, not in scope for the immediate behavior fix).
  • feat: auth bearer token support #2 尽快上线 — small targeted fix, ~30 min after task fix: poetry dependencies #15 merge.
  • feat: api test #3 简单稳定 — the Set now matches the live enum verbatim (`PENDING`, `RUNNING`); no fragile string-to-string mappings introduced.
  • fix: upload token #4 私有化部署免维护 — fix is invisible to operators; restores intended polling behaviour.

Test plan

  • yarn tsc --noEmit shows the same 5 pre-existing errors as on main; no new errors introduced.
  • Static read: `hasNonTerminalDocumentState` Set membership now returns true for `'PENDING'` and `'RUNNING'` index states (the actual non-terminal states).
  • Manual smoke (out of session env): create a fresh collection, upload a document, observe that `documents-table` stays in fast-poll while `vector_index_status === 'RUNNING'` instead of falling back to slow-poll.

🤖 Generated with Claude Code

…rings

Replace `NON_TERMINAL_INDEX_STATUSES` with the live four-value
enum members so the document polling loop actually identifies
in-progress index work instead of silently never matching.

The previous Set declared (`PENDING`, `CREATING`, `DELETING`,
`DELETION_IN_PROGRESS`) — three of those four literals were
retired when the backend simplified the per-modality index
enum to (`PENDING`, `RUNNING`, `ACTIVE`, `FAILED`). The Set is
typed `Set<string>` so tsc never flagged the drift, but
`hasNonTerminalDocumentState` would only ever match `'PENDING'`
in practice; documents transitioning through the new `'RUNNING'`
state were treated as terminal, so the table fell out of fast-
poll mode while indexing was still active.

This is the W8-8 sediment from PR #1766 (task #15) findings:
type-drift fixed there is type-safe but did not catch
behavior-drift cases hidden behind `Set<string>` / `Array<string>`
literals. architect msg=ec02b580 authorised cuiwenbo to ship
this short-term follow-up at own cadence.

§K.12 invariant cross-check
============================
Largely n/a (frontend behavioral fix, not graph-layer):

- #12 (grep-zero LightRAG) — `rg -i lightrag web/src/` returns
  zero hits both before and after, no narrative mention added.

4-pattern pre-check matrix
==========================
- Pattern 1 v1 (legacy enum literals in this file):
  `rg "CREATING|DELETION_IN_PROGRESS" documents-table.tsx`
  shows zero remaining hits. The remaining `'DELETING'` literal
  in `NON_TERMINAL_DOCUMENT_STATUSES` (line 67) belongs to the
  separate eight-value `Document.status` enum (`UPLOADED |
  EXPIRED | PENDING | RUNNING | COMPLETE | FAILED | DELETING |
  DELETED`), which still includes `DELETING` — leave intact.
- Pattern 1 v2 (consumers of the Set): only one call site,
  `hasNonTerminalDocumentState`, which polls based on Set
  membership; no other code reads the Set's contents directly.
- Pattern 2 (response-shape change list): n/a, this PR does
  not touch any API surface or schema.
- Pattern 3 (additive helpers): n/a, value-set narrowing only.

simple-stable directive 4-guardrail
===================================
- #1 不无限扩范围 — single-file two-string Set sweep, ~5 LOC
  diff. Did not extend to refactor the polling logic or
  re-derive the Set from the OpenAPI enum (a future cleanup,
  not in scope for the immediate behavior fix).
- #2 尽快上线 — small targeted fix, ~30 min after task #15
  merge.
- #3 简单稳定 — the Set now matches the live enum verbatim
  (`PENDING`, `RUNNING`); no fragile string-to-string mappings
  introduced.
- #4 私有化部署免维护 — fix is invisible to operators; restores
  intended polling behaviour.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Copy link
Copy Markdown
Collaborator Author

@earayu earayu left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 LGTM ✅ (huangheng pass-1) — verdict = ready to merge

1 file / +1 / -3 — 严格 W8-8 scope,behavior bug fix 干净(Set 从 stale 4-string (PENDING, CREATING, DELETING, DELETION_IN_PROGRESS) 改 live 2-string (PENDING, RUNNING)),polling 在 RUNNING 恢复 fast-poll。

Pattern 1 v1 验证 ✅

cuiwenbo 显式 paste 了 NON_TERMINAL_DOCUMENT_STATUSES (line 67, 8-value Document.status enum 含 DELETING) 与本 PR NON_TERMINAL_INDEX_STATUSES (4-value DocumentIndexStatus enum) 区分清楚 — DELETING 留在 _DOCUMENT_STATUSES 是正确,没误改。这种"两个看起来相似的 Set 区别"的精细辨析是行家级 review 防御。👍

simple-stable 4-guardrail

  • #1 不无限扩范围 ✅ 单文件 2-string sweep,不重构 polling 不 derive Set 自 OpenAPI enum (future cleanup 留 W8-9 / W8-10)
  • #2 尽快上线 ✅ ~5 LOC after task #15 merge
  • #3 简单稳定 ✅ Set 与 live enum verbatim 一致
  • #4 私有化免维护 ✅ operator-invisible, 恢复 intended 行为

测试 sediment

manual smoke 显式 defer "out of session env" — 可接受 (cuiwenbo 没本地 backend,task #11 narrative e2e 也 cover indexing flow 一部分;本 fix 是 client-side pure-compute 行为)。如未来需 e2e verify,sediment 进 W8-9 ("frontend behavioral test coverage" candidate)。

@符炫炜 LGTM,可 merge。
@cuiwenbo task #15 type drift + W8-8 behavior drift 双重 sweep + Pattern 1 v1 邻居 Set 辨析精细 — frontend 高质量 follow-up 模板。👍

@earayu earayu merged commit 66377a1 into main Apr 28, 2026
7 checks passed
@earayu earayu deleted the fix/w8-task-w8-8-documents-table-polling-enum branch April 28, 2026 02:47
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant