Skip to content

feat(dashboard): explain processing and always capture recall diagnostics - #2664

Open
happy-v587 wants to merge 15 commits into
oceanbase:masterfrom
happy-v587:codex/1984-business-diagnostics
Open

happy-v587 wants to merge 15 commits into
oceanbase:masterfrom
happy-v587:codex/1984-business-diagnostics

Conversation

@happy-v587

@happy-v587 happy-v587 commented Nov 16, 2026 •

Copy link
Copy Markdown
Collaborator

Which issue or RFC does this PR close?

Refs #1984, #1980 and #1356. Integrates RFC 1435 without changing the public Receipt schema.

Rationale for this change

Operators need to see where accepted Sources stop processing and why retrieved memories do or do not reach a prepared context. Separate logs, counters and Receipts require manual reconstruction and do not retain the actual candidate text for relevance checks.

What changes are included in this PR?

  • Add source-processing diagnostics with consumption cursor/head, recorded blockers, last processing evidence and next checks, while keeping durable facts separate from process-local observations.
  • Add Server-side recall capture with no switch. Every prepare writes one record from the same execution: the original query, per-family search results, rerank inputs/outputs, assembly candidates, exact final text and the existing Receipt. Capture does not replay retrieval or call models again; failures do not replace the normal prepare result or suppress cancellation.
  • Add read-only recall history and a separate detail page ordered as query → retrieval → reranking → budget assembly → final context. Each stage combines counts, outcomes, reasons and actual text, and shows the stage duration in the stage heading. Artifact versions link to their existing exact readers after current authorization; unavailable historical evidence stays explicit.
  • Add the diagnostic store through one additive revision, v1_5_0_006, whose create statement already includes the nullable UTF-8 query_text column. Preserve the published plugin revision v1_5_0_005 and all earlier resources. Register both source bridges and SQLite/MySQL layouts.
  • Document the private diagnostic extension in both locales. Public Receipts and operational telemetry remain body-free. Diagnostics do not write Source or Bootstrap receipt storage.

Are there any user-facing changes?

A new recall diagnostics page and additional source-processing details are available in Dashboard. Capture always runs on the Server and retains query and candidate/final text permanently; this change adds no expiry or cleanup action. Standalone SDK use does not write this Server store. Reads preserve current Scope/Artifact authorization, completed audit and no-store responses.

Existing managed databases require explicit migration before startup. The additive revision does not rewrite existing domain data. The public prepare response and reuse behavior remain unchanged. Prepared context does not prove host injection, model use or task benefit.

How was this change tested?

  • Persistence and migration regression: uv run pytest tests/builtin/persistence tests/test_migration_revision_names.py tests/test_managed_atomic_maintenance.py tests/test_managed_processing_maintenance.py tests/test_registered_source_maintenance_cli.py -q — 1023 passed, 135 skipped. The skipped cases are seekDB and OceanBase probes that were not enabled; no live native-backend upgrade acceptance is claimed.
  • Focused Dashboard, capture and migration regression: uv run pytest tests/test_dashboard_context_capture.py tests/test_dashboard_context_diagnostics.py tests/test_dashboard_processing_status.py tests/test_migration_revision_names.py tests/builtin/persistence/test_diagnostic_query_migration.py tests/e2e/test_dashboard_business_diagnostics.py -q — 43 passed.
  • make check — passed, including the lock file, all pre-commit hooks and ty check.
  • make docs-test — passed, including the bilingual build and verification of 1,114 exported public pages.
  • Browser acceptance used isolated SQLite fixtures and a deterministic reranker. It verified original text, exact versions, stage order, merged tables and mobile overflow; it does not establish real-provider or installed-host acceptance. No business database was migrated.

AI usage statement

Implemented with OpenAI Codex. Changes were inspected against repository contracts and exercised with local automated checks and controlled browser fixtures.

@happy-v587

Copy link
Copy Markdown
Collaborator Author

新增“召回数据”的可观测

image image

@happy-v587 happy-v587 changed the title feat(dashboard): explain processing and retain opt-in recall diagnostics feat(dashboard): explain processing and always capture recall diagnostics Nov 16, 2026
… stages

Remove the context diagnostics switch so the Server always writes the
prepare diagnostic store, and rework the detail page:

- group exact selected references by family
- show each stage duration in its heading and drop the stage table
- keep only Receipt-selected candidates in the assembly text column
- report the retrieval-stage count from the same-execution snapshot
- move the Receipt ID into the query card footer
- explain that the byte budget counts UTF-8 bytes, not characters
- clarify omission wording and drop the placeholder count for not_retrieved

Sync en/zh docs and RFC 1435.
Revision v1_5_0_007 only added pc_context_prepare_diagnostics.query_text,
and both revisions are unmerged. Fold the column into the v1_5_0_006
create statement so the diagnostic store is one additive revision.

Delete the v1_5_0_007 schemas, scripts and state layouts, refresh the
manifest, the MySQL history and the release upgrade-support digest, and
update the tests that asserted the removed revision.
…-diagnostics

# Conflicts:
#	release/upgrade-support.json
#	tests/native/test_oceanbase_engine_recovery.py
#	tests/native/test_personal_service_lifecycle.py
…-diagnostics

# Conflicts:
#	docs/en/docs/operate/database-migrations.md
#	docs/zh/docs/operate/database-migrations.md
#	release/upgrade-support.json
@happy-v587

Copy link
Copy Markdown
Collaborator Author

PTAL @AlexStocks @hidb4ai @hireview001

@hidb4ai hidb4ai left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

One non-blocking design note on the retention policy; this is not a request for changes.

PR oceanbase#2674 registers the same v1_5_0_006 ID and adds identically named
migration files; two linear chains cannot share a revision ID. Renumber
the prepare diagnostics revision, its schema resources, manifest
registrations, docs and target-revision assertions, and refresh the
compatibility review digest.

Co-Authored-By: Claude Code <noreply@anthropic.com>
@happy-v587

Copy link
Copy Markdown
Collaborator Author

The renumbered revision run (44080115039) completed with one failure: script-installation / installation (macos-latest). The log shows the runner classified its download region as cn (timezone) and routed Python package installs through the Tsinghua PyPI mirror, where the setuptools wheel for the jieba sdist build returned 404; uv retried four times over 132s and then failed in tests/native/test_installation.py. The same install script passed on ubuntu-latest, all migration/diagnostic tests are green, and other branches (including master) hit infra failures in the same window, so this is an upstream mirror flake unrelated to the revision renumbering. Requesting a rerun of that job.

…-diagnostics

# Conflicts:
#	docs/en/docs/operate/database-migrations.md
#	docs/zh/docs/operate/database-migrations.md
#	release/upgrade-support.json
@happy-v587

Copy link
Copy Markdown
Collaborator Author

Follow-up on run 44101725008: desktop-validation / macos (macos-15-intel) failed in the Rust test diagnostic_process::tests::timeout_and_live_cancellation_terminate_spawned_descendants, which panicked at src/diagnostic_process_macos.rs:450 with Result::unwrap() on Err(NotFound) — the test could not read a child PID file it expects a spawned descendant to write. The same job passed in the previous run of this PR (44080115039) and the branch's desktop sources are unchanged by the renumbering/merge commits, so this is an environment-dependent flake (process spawn timing on the shared Intel runner), not a regression from this change. The job has been rerun.

…-diagnostics

# Conflicts:
#	release/upgrade-support.json
@happy-v587

Copy link
Copy Markdown
Collaborator Author

Follow-up on run 44136372151: dsh-package failed two tests in tests/companion-memory.spec.ts (propagates valid per-call parents... and reuses the running transport...). The failing assertions come from #2656 (companion memory + trace propagation), which this branch does not touch — the integration sources are unchanged by this PR, and two other PR runs that include the same commit (44125488931, 44124818203) failed the same two tests with identical assertions. Rerunning the failed jobs.

@happy-v587

Copy link
Copy Markdown
Collaborator Author

Root cause found for the dsh-package failure (reproduced locally at 77b0ca8 and at this branch's head, so it is deterministic, not a flake): #2656's squash merge landed companion-memory.ts with import { scrubSecrets } from './secrets.ts', but #2644 had just moved scrubSecrets to prompt-privacy.ts (secrets.ts now exports only hasSecretContent). Under Vitest's SSR transform the stale named import resolves to undefined, so scrubSecrets(...) throws inside run(), the .catch(() => unavailable) swallows it, client.request is never reached (0 fetch calls), and both tests fail exactly as observed (traceparent never propagates; the service reports unavailable). The fix is a one-line change on the #2656 side: import scrubSecrets from ./prompt-privacy.ts. This branch's DSH sources are byte-identical to master here and the PR does not touch them.

@hireview001 hireview001 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

  • CI failed: CI result (failure).
  • CI failed: dsh-package (failure).
  • CI failed: Main (failure). Failed steps: dsh-package / Test DSH package; CI result / Require successful selected checks.

happy-v587 and others added 2 commits November 18, 2026 07:18
The fixed five-family list in selected_by_family, final_candidates and the
assembly text snapshots dropped plugin-family selections (for example a
'notes' section), so the Dashboard budget table omitted a family the
Receipt cited. Seed the family counts with the requested plugin sections,
count their hits in final_candidates, and capture their same-execution
assembly text snapshot.

Co-Authored-By: Claude Code <noreply@anthropic.com>
…-diagnostics

# Conflicts:
#	release/upgrade-support.json
@frf12

frf12 commented Nov 18, 2026

Copy link
Copy Markdown
Member

The old queued CI run was cancelled while migrating eligible Linux checks to the internal runner pools in #2711.

At head dcd1c3eb8, this PR has merge conflicts with master 07621c869. Conflicts affect the English/Chinese migration and troubleshooting docs, upgrade/migration manifests, and related tests, including:

  • docs/en/docs/operate/database-migrations.md
  • release/upgrade-support.json
  • tests/e2e/test_source_write.py

Please sync the branch with master, resolve the conflicts, and push the update. GitHub cannot start a new pull_request workflow while the conflicts remain; eligible Linux checks can then use the updated internal-runner routing.

…-diagnostics

# Conflicts:
#	docs/en/docs/operate/database-migrations.md
#	docs/en/docs/operate/troubleshoot.md
#	docs/zh/docs/operate/database-migrations.md
#	docs/zh/docs/operate/troubleshoot.md
#	release/upgrade-support.json
#	src/powercontext/builtin/persistence/migrations/server_resources/manifest.json
#	src/powercontext/builtin/persistence/migrations/server_sources/1.4.0/manifest.json
#	tests/builtin/persistence/test_atomic_description_vector_layout.py
#	tests/builtin/persistence/test_atomic_evidence_upgrade_history.py
#	tests/builtin/persistence/test_full_server_migrations.py
#	tests/builtin/persistence/test_mysql_initialization_preflight.py
#	tests/builtin/persistence/test_mysql_migration_runner.py
#	tests/builtin/persistence/test_plugin_storage_migration.py
#	tests/builtin/persistence/test_portable_storage_migration.py
#	tests/builtin/persistence/test_release140_server_migrations.py
#	tests/e2e/test_atomic_memory_description_upgrade.py
#	tests/e2e/test_source_citation_locators.py
#	tests/e2e/test_source_write.py
#	tests/native/test_oceanbase_engine_recovery.py
#	tests/native/test_personal_service_lifecycle.py
#	tests/test_managed_atomic_maintenance.py
#	tests/test_managed_processing_maintenance.py
#	tests/test_migration_revision_names.py
#	tests/test_registered_source_maintenance_cli.py
@hidb4ai

hidb4ai commented Nov 18, 2026

Copy link
Copy Markdown
Contributor

Re-review of 2cee427: the previous migration-chain issue is fixed against current master: the tail is v1_5_0_005 -> v1_5_2_pr2639 -> v1_5_0_007, with a single head. The migration upgrade and plugin-family capture regressions pass locally, and the persistence review digest matches. No new blocking correctness finding from this incremental review.

CI is still a merge-readiness blocker: run 44279936034 timed out in CI preflight / Check License Header (The action has timed out.), without reporting a missing license header. Most downstream checks were skipped; the failed aggregate gates are not evidence that those suites ran and failed. Please rerun or repair the preflight timeout and obtain the required checks on this head before merging. This is separate from the now-resolved merge conflicts.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

1.6.0 v1.6.0 release tracking

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants