jobtrackingapp/docs/performance/PERF-01_RULES_FRESHNESS.md

PERF-01 Rules settings freshness

Source baseline: 9c9fe48d5f321c653049f09ced5b7e27701fe2a8; isolated branch codex/perf-rules-freshness.

Successful Rules settings saves previously left the API's owner-keyed 30-second cache unchanged. Settings could therefore display the saved values while Applications, Board filtering, details, reminders and readiness continued using old thresholds. Invalidating only the owner's entry would also miss global-fallback dependencies and permit an older asynchronous cache fill to repopulate stale data.

The job controller now reads through the existing RulesEngine.GetSettings owner/fallback implementation on each request. There is no rules cache to repopulate, including across separate API processes. Existing database/query-filter contracts and global AddMemoryCache remain unchanged. The unused optional constructor cache argument is removed; the following optional checklist argument retains its name and all existing callers compile. Create and AI-refresh responses share the same corrected settings read; neither endpoint is activated by these tests.

The cost is one owner-primary-key settings lookup per job request, plus a singleton lookup when no override exists. This correctness fix is not a measured latency or throughput improvement. No distributed invalidation infrastructure was introduced. A read begun before a committed update may return its earlier snapshot; a completed older response cannot cache that snapshot for later requests.

Verification

• RED: Seven real SQLite cases with a shared MemoryCache failed before the application change, all with expected True / actual False at the post-save freshness assertion. These cover list, Board follow-up filtering, detail, reminders, readiness, owner isolation and global fallback. Local receipt: JobTrackerApi.Tests/TestResults/rules-red.trx.
• PASSED: The final focused regression run passed 35 distinct tests, including eight new freshness cases, plus query parity, workflow signals, prospect rules and concurrent initialization. The eighth case pauses an older detail request at a mock identity lookup after rule evaluation, saves new rules, verifies a fresh request, completes the older response and verifies another fresh read. This uses no model or provider. Local receipt: JobTrackerApi.Tests/TestResults/rules-regression.trx.
• PASSED: dotnet build "Job tracker.sln" --no-restore --verbosity quiet: zero warnings/errors.
• PASSED: git diff --check.
• PASSED: graphify update . rebuilt the local AST graph without API/model use. It reported missing optional PDF/SQL parsers and files without extracted symbols; those are graph coverage limits, not application test failures. Generated graphify-out/ remains local and untracked, as at the source worktree.

Durable machine-readable red/final result names, outcomes, counts and timestamps: verification.json. Exact native red, development-green and final-regression TRX files are preserved as .trx.gz files alongside it. native-receipts.json records raw/compressed SHA256 hashes and byte lengths; gzip decompression reproduces the original receipts without text transformations. The seven-test development-green run overlaps the final regression run.

Commands use the installed C:\Users\Connor\.dotnet\dotnet.exe SDK; the runtime-only Program Files executable cannot execute SDK commands. Test command: dotnet test JobTrackerApi.Tests/JobTrackerApi.Tests.csproj --no-restore --filter "FullyQualifiedName~RuleSettingsFreshnessTests|FullyQualifiedName~JobQueryParityTests|FullyQualifiedName~JobApplicationsWorkflowSignalsTests|FullyQualifiedName~RulesEngineProspectTests|FullyQualifiedName~ConcurrentInitializationTests".

Limits and rollback

The seven-test green development run overlaps the final 35-test run and is not added to its total. The controlled older-request check is not a database isolation stress test. Failed-save injection, hosted MariaDB execution, multi-process load and production latency were not run. This does not qualify Phase 10, integrated security or release readiness. Reverting the package restores the old caching behavior and reintroduces the reproduced stale-settings defect. Publication/integration remains with the parent development lane.