PlantAI-dev/docs/manifest_scope_artifact_audit_job_1779966938704_2026-05-29.md

Manifest scope/artifact audit: job_1779966938704_aa384a

Date: 2026-05-29

Job:

job_1779966938704_aa384a

Workspace:

/home/xia-lab/wutx/00test/bbav5_0502_Yang_Tihuan.7880/workspace/job_1779966938704_aa384a

Input:

/home/xia-lab/wutx/00test/bbav5_0502_Yang_Tihuan.7880/input/job_1779966938704_aa384a

Audit purpose

This audit checks the current completed job manifests to identify:

• Which stages already record scope_id and usable artifacts.
• Which outputs correctly preserve frontend-friendly file names such as Lc.SPL.target_plus_reference.combo.png.
• Which places still rely on filename/prefix conventions instead of authoritative manifest identity.
• Which manifest names are compatibility artifacts and should not become the future naming standard.

Snapshot command set

find workspace/job_1779966938704_aa384a/final -maxdepth 1 -type f -name '*.manifest.json' | wc -l
find workspace/job_1779966938704_aa384a/final -maxdepth 1 -type f -name '*.manifest.json' -printf '%T@ %f\n' | sort -nr | head -20

The final/ directory is still a live workspace directory. During this audit the manifest count was observed at 106, with a few newer records appended after the earlier baseline count. Therefore, this document should be read as a current audit snapshot, not as an immutable file-count ledger.

Current stage summary

All inspected artifact paths resolved to existing files when full_path was used first and path was resolved relative to the job workspace.

Stage	Manifest count	Manifests with scope	Manifests with artifacts	Missing artifact paths	SPL.SPL filename count
config_autofill	1	0	1	0	0
genome_prepare	1	0	1	0	0
identify	11	11	11	0	4
identify_refine	6	6	6	0	0
phylogeny	17	17	17	0	7
motif	12	12	12	0	6
structure	12	12	12	0	6
domain	12	12	12	0	6
msa_region_plot	11	0	11	0	0
reference_classification	20	20	20	0	7
subfamily_confirm	3	0	3	0	0

What is already in good shape

The core chain mostly records scope identity and artifacts correctly:

• identify
• identify_refine
• phylogeny
• motif
• structure
• domain
• reference_classification

For these stages, the successful manifests generally contain:

• scope_id
• analysis_route
• member_set_id or related route identity
• output_prefix
• artifacts
• real artifact paths that resolve to existing files

This means the system has enough data to use manifest-first status and display logic for the main gene-family chain.

Frontend-friendly names are correctly recorded

The frontend-friendly combo files are not a mistake. They are present and recorded inside reference_classification artifacts.

Examples:

Lc.SPL.target_plus_reference.combo.png
Lc.SPL.target_plus_reference.combo.pdf
Dl.SPL.target_plus_reference.combo.png
Cp.SPL.target_plus_reference.combo.png
Os.SPL.target_plus_reference.combo.png
PPY.SPL.target_plus_reference.combo.png
Sl.SPL.target_plus_reference.combo.png

Representative manifest registration:

Target.SPL.target-Lc.ref-At.subfamily_prediction.reference_classification.manifest.json
  per_species_evidence_combo_Lc_SPL_target_plus_reference_combo_png
  -> final/Lc.SPL.target_plus_reference.combo.png

Conclusion: keep Species.Family.target_plus_reference.* as user-facing/UI artifact names. The fix direction is to make readers trust the manifest artifact entry, not to remove these files.

Compatibility names that should not spread

There are 36 manifest files whose filenames contain .SPL.SPL..

Examples:

Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.phylogeny.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.motif.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.structure.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.domain.manifest.json
Lc.SPL.SPL.target-Lc.ref-At.target_plus_reference.reference_classification.manifest.json
Target.SPL.SPL.target-Dl-Lc-Cp-Os-PPY-Sl.ref-At.target_plus_reference.reference_classification.manifest.json

These files are not completely broken: they contain usable scope_id and artifacts. But the filename itself mixes the user prefix and machine scope in a confusing way.

Interpretation:

• Safe to read as legacy/compatibility manifests.
• Should not be used as the preferred new output naming pattern.
• New readers should prefer manifest identity fields over filename parsing.
• New writers should avoid creating more *.SPL.SPL.* names unless explicitly writing a compatibility alias.

Stages that still rely too much on filename/prefix context

msa_region_plot

Current state:

• 11 manifests.
• All have artifacts.
• None record scope_id.
• Species/reference/route are only inferable from filenames such as:

Target.SPL.target-Lc.ref-At.subfamily_evidence.msa_conserved_region_427_486.manifest.json
Target.SPL.target-Lc.ref-At.subfamily_prediction.msa_conserved_region_429_488.manifest.json

Risk:

• Status/result display has to infer route from the prefix string.
• It is hard to distinguish evidence route versus prediction route without parsing names.

Required direction:

• Add scope_id, scope_mode, analysis_route, member_set_id, target/reference species, and stage_context to msa_region_plot manifests.

subfamily_confirm

Current observed confirmed manifests:

Cp.SPL.subfamily_confirm.manifest.json
Dl.SPL.subfamily_confirm.manifest.json
Lc.SPL.subfamily_confirm.manifest.json

Current state:

• All have artifacts.
• analysis_route=confirmed_subfamily.
• member_set_id exists, for example Lc.SPL:confirmed_subfamily:all_members.
• scope_id is empty.
• target_species, reference_species, and selected_species are empty in stage_context.

Risk:

• The system knows that Lc.SPL has a confirmed table, but not which target/reference classification scope it confirms.
• In multi-species workflows, this can make “already predicted”, “needs confirmation”, and “confirmed” harder to separate.

Required direction:

• subfamily_confirm should inherit the source prediction scope where possible.
• If confirmation is intentionally species-level only, manifest should still record target_species=["Lc"], family="SPL", and a link to the source prediction manifest or source prediction prefix.

Combo manifest finding

No independent *combo*manifest*.json was observed in this job.

This is acceptable if combo is treated as a visualization artifact of reference_classification or subfamily evidence. It becomes a problem only if frontend/status code expects a separate combo stage manifest as the authoritative source.

Required direction:

• For subfamily review, read combo evidence from reference_classification manifest artifacts first.
• Treat standalone combo manifest lookup as optional/backward-compatible, not required.

Code areas related to the audit

Observed manifest-first or partially manifest-first code:

• gfa_core/mas/tools/stage_status.py
  • Validates scope_id when provided.
  • Can find equivalent scoped manifests.
  • Still has non-strict fallback glob behavior when no scope is provided.
• apps/web/vue3/main.py
  • _subfamily_evidence_assets reads reference-classification manifest artifacts and same-scope manifests first.
  • It still falls back to prefix glob patterns.
• apps/web/pipeline_backend.py
  • The multi-species reference-classification branch writes per-species results and stores direct combo paths.
  • It also writes legacy aggregate manifest aliases.
• apps/web/vue3/index.html
  • The subfamily popup prefix collection still constructs candidate prefixes such as Target.{family}.target-{sp}.ref-{ref}.subfamily_prediction and ${sp}.${family}.

These fallbacks are useful for compatibility, but they should not be the primary identity model.

Immediate conclusions

1. The main analysis chain is not missing artifacts. The audit found no unresolved artifact paths after resolving full_path correctly.
2. Lc.SPL.target_plus_reference.* and equivalent species-level outputs should be preserved as frontend-friendly artifacts.
3. The biggest cleanup targets are identity consistency, not raw file existence:
   • eliminate new SPL.SPL manifest names except compatibility aliases;
   • add scope/stage context to msa_region_plot;
   • connect subfamily_confirm back to its source prediction scope;
   • keep subfamily review and result display manifest-first.
4. The current job is good enough as a regression baseline because it contains both the desired UI artifacts and the legacy names that readers still need to tolerate.

Suggested next code-level tasks

1. Update manifest writing so new scoped stage manifests use clean machine prefixes and only write SPL.SPL files as explicit compatibility aliases if still needed.
2. Update run_subfamily_confirm.py so confirmation manifests preserve source scope_id, target/reference species, and source prediction manifest/prefix.
3. Update run_msa_region_plot.py so MSA conserved-region manifests record scope identity instead of relying on filename parsing.
4. Keep _subfamily_evidence_assets manifest-first and add regression tests that fail if combo evidence can only be found by filename glob.
5. Add a manifest audit regression script that checks:
   • all scoped stages have scope_id;
   • all manifest artifacts resolve;
   • UI combo artifacts are present in reference-classification artifacts;
   • no new non-compatibility *.SPL.SPL.* manifests are produced.

Follow-up fix: MSA region plot scope identity

Implemented on 2026-05-29 after this audit.

Files updated:

• apps/cli/run_msa_region_plot.py
• apps/cli/run_phylogeny.py
• apps/web/pipeline_backend.py
• tests/unit/test_msa_region_plot_scope.py

Behavior after the fix:

• run_msa_region_plot.py accepts --scope-file, --analysis-route, --member-set-id, and --source-manifest.
• Standalone MSA region plotting can inherit scope identity from an existing phylogeny/reference-classification manifest.
• Phylogeny's automatic conserved-region MSA plot now passes the current scope identity into the helper before the phylogeny manifest is written.
• Existing MSA region file names are preserved; the change only enriches manifest identity.

Real-data validation used the current Lc subfamily-prediction MSA from job_1779966938704_aa384a and wrote outputs to /tmp/bbav5_msa_region_scope_real_20260529/final without modifying the real job. The generated manifest contained:

scope_id = SPL.target-Lc.ref-At.target_plus_reference
target_species = ['Lc']
reference_species = ['At']
analysis_route = subfamily_prediction
member_set_id = SPL.target-Lc.ref-At.target_plus_reference:subfamily_prediction:all_members

Follow-up fix: legacy scoped manifest aliases

Implemented on 2026-05-29 after validating the existing job_1779966938704_aa384a manifests.

Files updated:

• gfa_core/gene_family_stage_context.py
• gfa_core/mas/tools/stage_status.py
• gfa_core/mas/agents/result_parser.py
• tests/unit/test_legacy_manifest_alias.py

Behavior after the fix:

• New compatibility copies written as prefix.scope_id.stage.manifest.json are marked with compatibility_alias=true, alias_type=legacy_scoped_manifest, and a canonical_manifest pointer.
• Stage status resolves marked aliases back to the canonical short manifest before validating artifacts.
• Existing unmarked legacy copies from old jobs are also redirected when their manifest output_prefix points to an existing canonical manifest.
• ResultParser's cumulative-report manifest lookup follows the same alias-to-canonical rule.

Real-data validation used workspace/job_1779966938704_aa384a/final, which currently contains 40 *.SPL.SPL.*.manifest.json legacy files. Strict status checks for Lc phylogeny, reference classification, domain, and subfamily confirmation all resolved to canonical non-SPL.SPL manifests and completed with no missing artifacts. The restarted 7880 /api/stage-status endpoint returned completed=True, empty errors, and non-alias manifest paths for the same stages.