Skip to main content
Version: Next

Known Issues and Behavior Differences

Version: v3.1.0 Status: Normative (text), Illustrative (diagrams only) Scope: Tracks ALL known discrepancies between documented requirements and actual implementation behavior, including requirements violations, implementation bugs, documentation errors, and test infrastructure limitations Domain: KNOWN-ISSUES


Statement

This is the single authoritative registry of known issues for the project, consolidating findings from Pass C code review (KI-001, KI-002), STD reconciliation testing (KI-003 through KI-012, TI-001), v3.1.0 upgrade investigation (KI-013, KI-014), and browser/config mode test investigation (KI-015, KI-016, KI-017).

Each entry links to affected requirements, test references, and resolution options, ensuring traceability between documented requirements and delivered functionality. TI-002 and TI-003 have been resolved and moved to Appendix B. KI-014 resolved (Session 41) and moved to Appendix B. KI-015 was added from browser test investigation (2026-03-10). KI-016 and KI-017 were added from v3.1.0 regression testing (2026-03-11/12).


Issue Lifecycle Overview (Illustrative)

This diagram illustrates the issue lifecycle. It does not specify specific workflows, tooling, or approval processes.


Definitions

TermDefinition
Known IssueA documented discrepancy between SRS requirements and implemented behavior
SeverityImpact level: Low (cosmetic/minor), Medium (functional impact), High (critical functionality)
Gap IDReference identifier linking to the gap analysis register
Intentional DeviationA deliberate implementation decision that differs from the original requirement
Test Infrastructure IssueA limitation that prevents test execution but does not affect production behavior

Active Issues -- Requirements Violations

KI-001: Display Name Uniqueness Not Enforced

AttributeValue
IDKI-001
SeverityLow
StatusOpen
RequirementREQ-USERSET-002
DiscoveredPass C Code Review (2026-01-19)

Actual Behavior: Code validates format only (nullable|max:40), not uniqueness. Multiple users can have the same display name.

Impact: Duplicate display names possible, may cause confusion in user tagging or comments.

Affected Files: code/app/Http/Requests/UpdateAuthUserRequest.php

Resolution Options: (1) Add unique:users,display_name validation rule, or (2) update SRS to clarify uniqueness is not required.


KI-002: S3 Structure Toggle Migrates Files

AttributeValue
IDKI-002
SeverityMedium
StatusOpen - Intentional
RequirementREQ-SITE-002 AC-05
DiscoveredPass C Code Review (2026-01-19)

Actual Behavior: Code DOES migrate files when preserve_s3_structure_for_first_site toggle changes -- Storage::move() relocates Runs/ and LIMS_Reports/ between site folder and root. SRS states "Changing the toggle shall not migrate existing files."

Impact: External integrations expecting files at original S3 paths may break. Lambda triggers are updated by the code.

Affected Files: code/app/Actions/Sites/UpdatePreserveS3StructureForFirstSiteAction.php

Resolution Options: (1) Remove Storage::move() calls, (2) update REQ-SITE-002 AC-05 to state files ARE migrated, or (3) add config option to control migration behavior.


KI-003: NOTTSQM CF=0 Treated as No Multiplier

AttributeValue
IDKI-003
SeverityLow
StatusOpen
RequirementREQ-RULES-NOTTSQM-001
DiscoveredSTD Reconciliation (2026-02-03)

Actual Behavior: When concentration_factor = 0, the system returns the base quantity (100) instead of multiplying by zero. CF=0 is treated as "no multiplier" (equivalent to CF=1 or null).

Impact: Edge case only. Whether this is a bug or intentional depends on business requirements -- zero CF may mean "not configured."

Test Reference: BT-9201, TV-NOTTSQM-001-004 (test expects actual behavior: 100).


KI-004: NOTTSQM Negative CF Causes MySQL Overflow

AttributeValue
IDKI-004
SeverityLow
StatusOpen
RequirementREQ-RULES-NOTTSQM-001
DiscoveredSTD Reconciliation (2026-02-03)

Actual Behavior: When concentration_factor = -1, computed quantity (-100) triggers SQLSTATE[22003]: Numeric value out of range on the unsigned DECIMAL quantity column. Entire run upload fails.

Impact: 1 KCI scenario. Run processing crashes on negative CF values.

Test Reference: BT-9201, TV-NOTTSQM-001-008 tagged @KNOWN_CODE_ISSUE.


KI-005: MIXMISS Cross-Run Resolution Partially Fixed

AttributeValue
IDKI-005
SeverityMedium
StatusOpen (partially fixed in v3.0.1)
RequirementREQ-RULES-MIXMISS-003 (allow_other_runs=true)
DiscoveredSTD Reconciliation (2026-02-06)

Actual Behavior: When allow_other_runs=true, the MIXMISS rule should resolve missing-mix errors by finding the mix in another run. In v3.0.0-beta.31, cross-run resolution caused an indefinite hang. In v3.0.1, the hang is fixed (cross-run association guard commit a7ecd68), but the resolution logic itself still does not clear the "Mixes are missing from the run" status.

Impact: 10 KCI scenarios. Cross-run mix resolution feature is partially fixed -- no longer hangs, but resolution status is not updated.

Test Reference: BT-9515 TV-MIXMISS-001-019, TV-MIXMISS-003-004; BT-9577, BT-9639, BT-9641 (additional KCI).


KI-006: REPEATSAMP Hardcoded Threshold Ignores Config

AttributeValue
IDKI-006
SeverityLow
StatusOpen
RequirementREQ-RULES-REPEATSAMP-001
DiscoveredSTD Reconciliation (2026-02-08)

Actual Behavior: WrepRule.php line 58 hardcodes the WREP log quant threshold at 0.5. The config parameter wrep_log_quant_threshold is silently ignored.

Impact: 3 KCI scenarios. Rule functions correctly with the hardcoded value; custom thresholds have no effect.

Affected Files: code/app/Analyzer/Rules/WrepRule.php (line 58)

Test Reference: BT-9533 TV-REPEATSAMP-G-002, BT-9601 TV-REPEATSAMP-001-011, TV-REPEATSAMP-001-012 (all tagged @KNOWN_CODE_ISSUE).


KI-007: INHQUANT Null IC Observation Guard Makes TVs Unreachable

AttributeValue
IDKI-007
SeverityMedium
StatusOpen
RequirementREQ-RULES-INHQUANT-001 (TV-001-017, TV-001-018)
DiscoveredSTD Reconciliation (2026-02-08)

Actual Behavior: (1) No-IC-observation case: well never reaches PICQUANT because FILEIMPORT fires "Mix tag is missing" first -- the skip condition is unreachable. (2) Null IC CT case: PicquantSerumRule lacks explicit null guard, proceeds through inhibition path setting ICQUANT_INHN instead of skipping.

Impact: 2 KCI scenarios. Tests pass documenting actual behavior — wells get ICQUANT_INHN instead of skip.

Affected Files: code/app/Analyzer/Rules/PicquantRule.php (line 45-48), PicquantSerumRule.php (line 45)

Test Reference: BT-9547 TV-INHQUANT-001-017, TV-INHQUANT-001-018 tagged @KNOWN_CODE_ISSUE.


KI-008: ADJ Null Contaminating Threshold Not Validated

AttributeValue
IDKI-008
SeverityLow
StatusOpen
RequirementREQ-RULES-ADJ-001 (config import validation)
DiscoveredSTD Reconciliation (2026-02-17)

Actual Behavior: ContaminationValueValidator checks potential_contaminated for null but has NO equivalent check for potential_contaminating. When contaminating is null, validation passes but DB insert crashes with integrity constraint violation.

Impact: 1 KCI scenario (BT-9555). Config import crashes on blank potential_contaminating values.

Affected Files: code/app/Actions/Adjacents/ImportSupport/Validate/Validators/ContaminationValueValidator.php

Test Reference: BT-9555 TV-ADJ-006-002 tagged @KNOWN_CODE_ISSUE.


KI-009: REANALYZE EditSampleRole Does Not Propagate WG Reanalysis

AttributeValue
IDKI-009
SeverityMedium
StatusOpen
RequirementREQ-REANALYZE-008 AC3
DiscoveredSTD Reconciliation (2026-02-17)

Actual Behavior: When a control well's role is edited (e.g., LO POS to HI POS), the system does NOT trigger "Reanalysis required (Westgard)" on affected future runs. Only extraction date/instrument changes propagate. Westgard series membership is not recalculated after role change.

Impact: 3 KCI scenarios (BT-9561: 1, BT-9564: 2). REQ-REANALYZE-008 AC3 not fulfilled.

Affected Files: code/features/Support/EditSampleRole.php

Test Reference: BT-9561 GAP-003, BT-9564 edit-role variants.


KI-010: ADJZIKA PHP String Sort for Well Ordering

AttributeValue
IDKI-010
SeverityLow
StatusOpen
RequirementREQ-RULES-ADJZIKA-003
DiscoveredSTD Reconciliation (2026-02-19)

Actual Behavior: AdjZikaRule.php line 40 sorts wells via ->sortByDesc(fn ($well) => $well->getWellNumber()). PHP string comparison means A2 > A10 (character "2" > "1" at position 1). STD specifies natural/numeric ordering.

Impact: Low. Well history selection order differs from spec for multi-digit well numbers.

Affected Files: code/app/Analyzer/Rules/AdjZikaRule.php (line 40)

Test Reference: BT-9585 TV-ADJZIKA-003-004 documents actual code behavior.


KI-011: DELTACT Null CT Handling

AttributeValue
IDKI-011
SeverityLow
StatusUnder Review
RequirementREQ-RULES-DELTACT-001
DiscoveredSTD Reconciliation (2026-02-02)

Actual Behavior: abs(30 - null) = 30 -- null CT is treated as zero in delta calculation instead of triggering a skip or error. All three IC skip tests passed with v31 config (code may implement IC exclusion correctly, or fixtures coincidentally avoid triggering the issue).

Impact: Low. Functional behavior matches spec in tests conducted so far. Further code-level investigation needed.

Affected Files: code/app/Analyzer/Rules/DeltaCtRule.php

Test Reference: BT-9101 TV-DELTACT-001-007/008/009 (originally tagged @KNOWN_CODE_ISSUE, all passed).


KI-012: UNEXPFL Raw-Max vs Normalized Fluorescence Comparison

AttributeValue
IDKI-012
SeverityLow
StatusOpen - Not Yet Confirmed
RequirementREQ-RULES-UNEXPFL-001
DiscoveredSTD Reconciliation (2026-02-19)

Actual Behavior: BT-9596 references a discrepancy between raw-max and normalized fluorescence values used in the unexpected fluorescence threshold comparison. The exact nature of the mismatch has not been formally investigated.

Impact: 1 KCI scenario (BT-9596). Needs formal confirmation.

Test Reference: BT-9596 TV-UNEXPFL (1 KCI).


KI-013: PatientWell testcode_name Nulled During Re-analysis

AttributeValue
IDKI-013
SeverityMedium
StatusOpen
RequirementREQ-ANALYZER-001 (well property persistence during re-analysis)
Discoveredv3.1.0 Upgrade Investigation (2026-03-10)

Actual Behavior: In PatientWell::setRequiredPropertiesFromInputs(), when a well has specimen_name set (which is always the case during re-analysis), the code enters the specimen_name branch and skips the testcode_name branch entirely. setTestcodeName() is never called, so getTestcodeName() returns null. UpdateRunAction then writes testcode_name = NULL to the database. On subsequent re-analysis, PatientValidator fires TESTCODE_MISSING and the well receives a "Test code tag (C) is missing" outcome instead of its correct result.

Impact: 31 KCI scenarios across three legacy feature files (rule-combout-viracor-225, rule-combout-viracor-219, rule-sysinh-viracor-prod). All are multi-run re-analysis tests where specimen_name is set.

Potential Fix: In the specimen_name branch of setRequiredPropertiesFromInputs(), add a call to setTestcodeName() when the input data contains a valid testcode_name, preserving it even when specimen_name is set.

Affected Files: code/app/Analyzer/PatientWell.php (setRequiredPropertiesFromInputs())

Test Reference: BT-5347, BT-5264 (combout-viracor-225); BT-5350, BT-5349, BT-5348 (combout-viracor-219); BT-5684, BT-5683, BT-5658, BT-5634, BT-5109, BT-5108, BT-5107, BT-5086, BT-5012, BT-5011, BT-5009 (sysinh-viracor-prod). All tagged @KNOWN_CODE_ISSUE.


KI-015: Help Data Toggle Not Implemented on Config Mode Pages

AttributeValue
IDKI-015
SeverityLow
StatusOpen
RequirementREQ-SPECIMEN-012
DiscoveredBrowser Test Investigation (2026-03-10)

Actual Behavior: The help_items feature flag and Help Data toggle button are documented in REQ-SPECIMEN-012 (and similar REQs for other Config Mode domains) but the Vue component TargetNameSuffixToSpecimen.vue does not implement the toggle. The Specimen Types page (Specimens.vue) may also be missing it. The Rule Tags page (RuleTags.vue) DOES implement it -- suggesting this is an incomplete rollout across Config Mode pages.

Impact: 3 browser test scenarios (TC-SPECIMEN-012 TV-001, TV-002, TV-003) tagged @KNOWN_CODE_ISSUE will fail until the feature is implemented.

Workaround: None needed -- cosmetic feature, does not affect core functionality.

Affected Files: code/resources/frontend/src/views/TargetNameSuffixToSpecimen.vue

Test Reference: BT-9761 TC-SPECIMEN-012 (3 scenarios in specimen-access.feature).


KI-016: EnrichConfigurationsWithRuleMappings Crash on Proposed Configs

AttributeValue
IDKI-016
SeverityLow
StatusOpen
RequirementREQ-CFGMODE (proposed configuration enrichment)
Discoveredv3.1.0 Regression Testing (2026-03-11)

Actual Behavior: EnrichConfigurationsWithRuleMappings.php line 124 throws Undefined array key 'id' when fetching proposed configurations that have rule mapping changes. The enrichment logic assumes all rule mappings have an id key, but newly proposed mappings do not yet have a database ID.

Impact: 1 KCI scenario in cfgmode-proposals.feature. Only affects proposed (not active) configurations.

Affected Files: code/app/Actions/Configurations/EnrichConfigurationsWithRuleMappings.php (line 124)

Test Reference: 1 scenario tagged @KNOWN_CODE_ISSUE.


KI-017: EditCrossoverRole Uses Dead RoleToTargetMapping Table

AttributeValue
IDKI-017
SeverityLow
StatusOpen
RequirementN/A (test support infrastructure)
Discoveredv3.1.0 Regression Testing (2026-03-12)

Actual Behavior: code/features/Support/EditCrossoverRole.php in v3.1.0-beta.65 queries the dead RoleToTargetMapping table instead of ControlLabel. The role_to_target_mappings table is never populated during v3.x config import -- it was replaced by the control_labels table in the v3.0.0 migration (v3_0_0_2024_07_20_041500). The application code (validators) correctly uses ControlLabel, but the upstream commit changed the test support file's findCrossoverRole() to use RoleToTargetMapping::where('role_alias', $value) instead of ControlLabel::where('role_alias', $value).

Impact: 2 scenarios in rule-fileimport-crossover.feature fail with "Crossover Role 'CC1' not found". This is test support code only -- no application behavior impact.

Fix Required: 3 lines in EditCrossoverRole.php: change use App\RoleToTargetMapping to use App\ControlLabel, change the return type, and change the query class.

Workaround: None -- requires upstream code fix.

Test Reference: 2 scenarios tagged @KNOWN_CODE_ISSUE in rule-fileimport-crossover.feature.


Active Issues -- Test Infrastructure (Appendix A)

These issues affect test execution rather than production behavior.

No active test infrastructure issues. TI-001, TI-002, and TI-003 have all been resolved (see Appendix B below).


Resolved Issues (Appendix B)

IDOriginalCategoryResolutionSession
--ISSUE-002ConfigWrong config diagnosis -- switched BT-9101 to v31 configS4
--ISSUE-003RetractedTest fixture issue -- patient well role not in DELTA_CT config mappingS4
--ISSUE-004RetractedSame root cause as ISSUE-003S4
--ISSUE-007ConfigMINCONTROLS used wrong rule -- MIN_CONTROLS vs MINEXTRACT for extraction-enabled configsS5
--ISSUE-008ConfigAMB config fixed (missing CODE column, wildcard target names, oversized sheets)S5
--ISSUE-009Resolved (v3.1.0)FIXED in v3.1.0. is_exclude_from_ic_delta_check was dead code in v3.0.x but is now functional in v3.1.0-beta.65. Tests updated with correct v3.1.0 assertions and tagged @V3_1_0. Originally reclassified as "Not a Bug" in S14 based on v3.0.x code review.S40
--ISSUE-016DeferredINHSERUMQUANT null IC CT as above-threshold -- PHP null <= 35 evaluates false. Low impact edge caseS17
--DOC-001Doc FixANALYZER: bypass_accession_validation changed to allowed_characters_in_accessions (array, not boolean)S15
--DOC-002Doc FixENGINE: per-well filtering clarification addedS15
--DOC-003Doc FixINHQUAL: PICQUAL/PICQUANT attribution disambiguation note addedS15
--DOC-004Doc FixLINREG: SKIP slope/intercept correction (-5 changed to -2)S15
--DOC-005Doc FixWDCTC: fluorescence skip requires Neg CLS -- added classification column, new TVS15
--DOC-006Doc FixINHSERUMQUANT: boundary > changed to >= for 10k thresholdS15
--DOC-007Doc FixRQUAL: decision table inversion fixed (12 outcome values corrected)S17
--DOC-008Doc FixMNGQTY: sequential preg_replace_array replacement clarification addedS17
KI-014ISSUE-023ResolvedCACHE_DRIVER changed from file to array in .env (Session 41, 2026-03-10). Array cache is per-process, correct for parallel test isolation. Intermittent ConfigDataImportJob null progress crashes eliminated.S41
TI-001ISSUE-014Resolved (v3.0.1)Archive step definition added in v3.0.1 (commit ba735a8). The When Archive the :fileName step now exists in FeatureContext. Archive dependency tracking infrastructure also added (REQ-REANALYZE-009 through -013). ~27 previously blocked scenarios are now executable.S35
TI-002ISSUE-015ResolvedEC cascade claim was incorrect -- all GAPDH_ENT scenarios pass with original Viracor_PROD config. Stale @KNOWN_CODE_ISSUE tags removed.S31
TI-003ISSUE-019ResolvedAdded Behat step Given the client configuration "{key}" is set to "{value}" to toggle use_sample_type after import. TV-COMBOUT-002-023 passes.S31

Cross-Reference Table

New IDOriginal IDSRS RequirementSeverityStatusKCI Count
KI-001--REQ-USERSET-002LowOpen0
KI-002--REQ-SITE-002 AC-05MediumOpen - Intentional0
KI-003ISSUE-005REQ-RULES-NOTTSQM-001LowOpen0
KI-004ISSUE-006REQ-RULES-NOTTSQM-001LowOpen1
KI-005ISSUE-010REQ-RULES-MIXMISS-003MediumOpen (partially fixed v3.0.1)2
KI-006ISSUE-012REQ-RULES-REPEATSAMP-001LowOpen3
KI-007ISSUE-013REQ-RULES-INHQUANT-001MediumOpen2
KI-008ISSUE-017REQ-RULES-ADJ-001LowOpen2
KI-009ISSUE-018REQ-REANALYZE-008 AC3MediumOpen3
KI-010ISSUE-020REQ-RULES-ADJZIKA-003LowOpen0
KI-011ISSUE-001REQ-RULES-DELTACT-001LowUnder Review0
KI-012ISSUE-021REQ-RULES-UNEXPFL-001LowNot Confirmed1
KI-013ISSUE-022REQ-ANALYZER-001MediumOpen37
KI-014ISSUE-023N/A (test infra)LowResolved (S41)0
KI-015ISSUE-024REQ-SPECIMEN-012LowOpen3
KI-016ISSUE-025REQ-CFGMODELowOpen1
KI-017ISSUE-026N/A (test support)LowOpen2
TI-001ISSUE-014REANALYZE/ArchiveMediumResolved (v3.0.1)0
TI-002ISSUE-015SYSINH/EC cascadeLowResolved0
TI-003ISSUE-019COMBOUT specimenLowResolved0

KCI Summary: ~75 total KCI scenarios (37 KI-013 testcode_name + 14 Westgard resolution + 3 KI-015 help toggle + 3 KI-006 REPEATSAMP + 3 KI-009 REANALYZE + 2 KI-008 ADJ + 2 KI-007 INHQUANT + 2 KI-005 MIXMISS + 2 KI-017 crossover + 1 KI-004 NOTTSQM + 1 KI-012 UNEXPFL + 1 KI-016 EnrichConfigurations).


Issue Lifecycle

StatusDescription
OpenIssue identified, awaiting resolution decision
Open - IntentionalBehavior difference is intentional, documented for awareness
Under ReviewInvestigation ongoing, may not be a real issue
In ProgressResolution underway
ClosedIssue resolved (code fix or requirement update)

Known Test Limitations (@KNOWN_LIMITATION)

These test cases are deferred due to infrastructure constraints, not code bugs. Each is tagged @KNOWN_LIMITATION in the test suite.

KL-CALIB-MOCK: Calibrator External API Mock Required

Affected TCs: TC-CALIB-006 (start calibration), TC-CALIB-018 (failure notification), TC-CALIB-019 (recalibration)

Constraint: These TCs require a mock of the App\Calibrator\Calibrator external API at api.pcr.ai. The mock pattern exists in tests/Feature/Calibration/AssayCalibrationTest.php (Laravel feature test), but Behat tests need a /_test/mock-calibrator route to bind a mock Calibrator into the Laravel container at runtime.

Fix: Add a test-only route that binds a mock Calibrator into the Laravel container, similar to the existing /_test/login and /_test/seed routes.

KL-CALIB-S3: S3 Storage for Calibration Activation

Affected TCs: TC-CALIB-013 (activate calibration)

Constraint: Activation requires S3 storage for the BSON calibration file via SaveCalibrationFileAction. The test environment does not have S3 configured.

Fix: Add a test route that calls Storage::fake('s3') before the activation request, or configure a local S3-compatible store for the test environment.

KL-WEBSOCKET: Multi-Session WebSocket Verification

Affected TCs: TC-CFGMODE-013 TV-003, TC-CFGMODE-017 (all 4 TVs), TC-CALIB-017

Constraint: These TCs require verifying that Pusher WebSocket events propagate DOM changes across multiple browser sessions simultaneously. The current Behat/Mink infrastructure supports a single browser session per scenario.

Fix: Build a dual-browser test harness with cross-session DOM assertion capability (two Chrome instances, two Mink sessions, coordinated assertions).

KL-DND: HTML5 Drag and Drop Simulation

Affected TCs: TC-CFGMODE-004 (drag-drop reorder)

Constraint: HTML5 Drag and Drop API simulation is fragile across browser versions. The DataTransfer object is read-only in programmatic events, making synthetic drag events unreliable in headless Chrome.

Fix: Implement native DnD event synthesis via CDP (Chrome DevTools Protocol) Input.dispatchDragEvent, or test the functional outcome via API workaround (verify reorder result after manual trigger).


Notes

  • v3.1.0 update (2026-03-12): KI-014 resolved (CACHE_DRIVER=array). KI-016 added (EnrichConfigurationsWithRuleMappings proposed config crash). KI-017 added (EditCrossoverRole dead table query). ISSUE-009 reclassified from "Not a Bug" to "FIXED in v3.1.0" (is_exclude_from_ic_delta_check now functional). Known Limitations section added for deferred infrastructure-blocked TCs.
  • v3.0.1 update (2026-03-05): TI-001 resolved (Archive step definition added). KI-005 partially fixed (hang resolved, resolution still broken). The limsStatusIsExcluded() bug (|| changed to && in commit be60a17) was a pre-existing defect in v3.0.0-beta.31 that was never reported as a KI because the bug made the check always true for non-null lims_status, so it had no visible negative effect on test outcomes. The fix in v3.0.1 enables proper EXCLUDE-only filtering for cross-run well comparisons (REQ-ANALYZER-002).
  • This document consolidates the former code-issues-log.md (ISSUE-NNN and DOC-NNN entries from STD reconciliation) with the original Pass C review findings (KI-001, KI-002). The code-issues-log.md file has been deleted (all content is here).
  • Issues discovered during Pass C Code Review are tagged with discovery date "2026-01-19."
  • Issues discovered during STD reconciliation are tagged with discovery dates from February 2026.
  • DocRef comments in code may reference known issues for developer awareness.
  • Resolution decisions should be documented in issue updates before closing.
  • Intentional deviations remain documented even after acknowledgment.
  • @KNOWN_CODE_ISSUE Behat tag marks scenarios that pass against actual code behavior but contradict the STD specification.
  • @KNOWN_LIMITATION Behat tag marks scenarios constrained by test infrastructure rather than code bugs.