alva/felsokning/docs/modules/evidence-engine.md

Module: The Evidence Engine (ECM — Evidence & Compliance Matrix)

Canonical version. Swedish: evidence-engine.sv.md. Code identifiers are Swedish and appear verbatim.

Version: ECM v2.0 · ECM is its own subsystem — not a table in the database — and the engine that governs the whole platform: it decides what documentation is required, when documentation is missing, what level of evidence has been reached, which rules apply, and whether a case may be closed. The system can never write a conclusion that ECM has not approved.

The rule library is versioned and separate from the application logic (src/felsokning/ecm.ts); the views only call the engine's pure functions.

The six engines

1. Evidence Engine

Catalogues all evidence from the event log. Each evidence entry receives an id, timestamp, technician, category, evidence level, summary and a content hash — the same entry always yields the same hash, and the append-only log (database triggers) makes every attempt at alteration impossible.

Level	Type	Probative value
E0	No supporting evidence	0 %
E1	Technician's observation	Low
E2	Photo	Medium
E3	Video (with sound — for what makes noise or moves)	High
E4	Measured value	High
E5	Diagnostic data / document	Very high
E6	Multiple independent sources	Highest

2. Rule Engine

The documentation requirements: the methodology's krav field per check, plus the automatic rules — can it be photographed → require a photo; does it make noise → video with sound; does it move → video; is it measured → a measured value; does a display show the information → photograph the display; does a document exist → photograph the document. The exemption reasons ("supporting evidence cannot be obtained") live here.

3. Compliance Engine

The case type determines which rules apply on top of the methodology. The case type is chosen in the identity row and logged (arendetyp_satt):

Case type	Additional requirements (v2.0)
Warranty	Odometer documented · service history checked · claim/warranty number
Goodwill	Odometer · service history
Insurance	Claim reference · photographic evidence
Complaint	History and previous attempts checked
Used-vehicle warranty	Odometer

The ECM Knowledge Library is implemented: the rules are declarative data (requirement type, not code) and are distributed from the platform via GET /api/ecm/regler (services/plattform/ecm-regler.json — replaceable in the cluster via a ConfigMap and the environment variable ECM_REGLER_FIL). The client fetches the pack on page load, caches it, and falls back to its built-in default pack when offline; broken packs and unknown requirement types are filtered out. The rule pack's version travels with every traceability package. New rules — warranty terms per manufacturer, insurers' requirements, consumer complaint legislation, OEM checkpoints — are added in operations without rebuilding the application.

4. Validation Engine

No claims without support, in three layers: (a) the orchestrator's base prompt — never "OK / checked / no faults / repaired" without evidence, instead "Evidens saknas" (evidence missing) plus a request for the right documentation; (b) the projections — hypotheses can never become confirmed faults; (c) the quality gate below.

5. Completion Engine

The quality gate before the final report and closing — printing is blocked until every mandatory row is green:

Check	Requirement
Vehicle/object identification verified	Mandatory
Work order read in	Recommended
Vehicle history checked or justified	Mandatory
Incoming odometer reading documented	Mandatory
Customer's fault description verified	Recommended
Customer's decision on the repair proposal	Mandatory when work has been performed
Repair documented or justified	Mandatory on closing
Quality check performed	Mandatory on closing after a repair
Outgoing odometer reading	Mandatory on closing
Methodology checks: evidence or documented exemption	Mandatory
Photos for photo-requiring checks	Mandatory
The case type's compliance requirements	Mandatory
Technician's conclusion signed	Automatic on closing
Evidence level above E0	Mandatory

6. Traceability Engine

Every export carries a traceability package: ECM version, case type, evidence level, gate status per rule id, and all evidence entries with their hashes. Together with the log, every conclusion can be traced: which image → which measurement → which technician → which rule → which rule-set version → when.

Pre-Diagnostic Validation

No diagnosis begins until the basic checks are performed or documented as justified — the methodology unlocks only afterwards:

1. Vehicle history — the system automatically retrieves the organisation's earlier cases on the same object (registration/VIN) together with their documented root causes (GET /api/fordon/{identifierare}/historik; the local store when offline) and shows them in the history step. The technician can link the causal chain to the current case with one tap ("linked to earlier case #N — …"), acknowledge the check — or answer No with a mandatory reason → quality warning.
2. Incoming odometer reading — the instrument cluster is photographed; the image interpretation proposes the value and the technician confirms it. The photo becomes the official incoming reading.
3. Customer's fault description verified — additional symptoms are documented as separate observations, never mixed in with the customer's description.
4. Early observations — traces of previous repair, modifications, damage, leakage and so on are documented with a photo or observation, or acknowledged as "none further".

The outgoing odometer reading is photographed before closing and becomes mandatory in the gate when the case is closed. The report shows in and out.

Symptom Verification Protocol (SVP)

A fault is never diagnosed straight from a vague customer description. The chain is always: documented → clarified → reproduced, or documented as not reproducible.

• The customer's description is recorded verbatim at case start and verified in pre-diagnostics; new symptoms become separate observations.
• Clarification happens through the methodology's symptom questions (when / where / how / conditions / frequency — the generic methodology carries the full SVP question set).
• Reproduction (Yes / Partly / No) is documented before closing: Yes requires how and under what conditions; Partly requires what could and could not be recreated; No requires a justification. The system never writes "fault confirmed" without reproduction or other verification — instead: "The customer's description could not be reproduced under the conditions that prevailed during the examination." (also encoded in the orchestrator's base prompt).
• The report's chain of evidence always separates: the customer's description → verified observation → root-cause analysis → recommended action.

Root-cause analysis

A case never closes with merely "component defective, replace component". Every confirmed fault requires four mandatory answers:

1. Observed deviation — the quality rule rejects generic phrasing ("broken", "defective", "worn", "needs replacing") without explanation.
2. Most probable cause — one or more categories (normal wear, material fatigue, manufacturing defect, poor maintenance, incorrect previous repair, external influence, corrosion, overheating, modification … plus Unknown cause, which requires a justification).
3. Supporting evidence — at least one evidence source, and the source is validated against the log: "Photo" is accepted only if a photo actually exists.
4. Confidence level — high / medium / low; at medium or low, the technician must state which further checks would strengthen the assessment.

The close button is blocked until SVP and the root-cause analysis are documented, and the quality gate makes both mandatory when the case is closed. The fleet data is already running: the root-cause statistics in the supervisor view (GET /api/statistik/felorsaker) aggregate the cause categories across the organisation — which components fail from wear, which after previous repairs, which point to a design problem.

Customer approval before work

The workshop may never carry out proposed work without the customer's decision being recorded and traceable:

• The repair proposal is written in the guide (pre-filled from the root-cause analysis's recommended action) with any estimated cost, and is shown to the customer in Live Share — it is customer-shareable material.
• The customer's decision is recorded with an outcome (approved / declined / partial), a channel (telephone, in person, e-mail, SMS, share link) and a justification when declined or partial. The log entry carries who at the workshop received the decision and when.
• The "Document work performed" button is locked as long as a proposal has no decision — and stays locked when the decision is a refusal. The "No work performed" path is open and refers to the recorded decision.
• The quality gate requires a recorded decision when work has been performed, and flags the conflict "Work performed despite a declined proposal" as a hard error.

The customer can answer directly in their share link (POST /api/delad/{kod}/beslut) — the only writing public route in the entire API, with six safeguards, each verified in the integration test:

1. Only shares at customer level (partner and internal links may never answer on the customer's behalf) and never revoked ones.
2. The case's original share code has no recorded level and therefore cannot answer either.
3. There must be a repair proposal to answer.
4. One decision per case — the answer cannot be changed afterwards (contact the workshop instead).
5. Only godkant / avbojt / delvis plus a comment of at most 500 characters; nothing else can be written to the log by that route.
6. Rate limiting per share code.

The decision is logged as kundbeslut with the channel Delningslänk (share link) and the sender "Kund via delningslänk" — the workshop's own entries (telephone, in person …) work exactly as before.

The repair phase (Repair & Verification)

The loop opened by symptom verification is closed here — a case cannot be finished without it being clear what was done and whether it helped:

1. Repair documented or justified — either what was actually performed (with any parts), or why no work was done (the customer declined, waiting for a part, investigation only, quotation submitted, repair at another workshop).
2. Quality check — mandatory when a repair has actually been performed: is the symptom gone, does it remain wholly or partly, or could it not be verified? The outcome is documented together with how the verification was carried out (the same conditions under which the symptom was reproduced).

A remaining symptom is never hidden: the gate states in writing that the case should not be closed as repaired. The close button is blocked until the chain symptom verification → root-cause analysis → repair → quality check is complete, and the report presents it in its own sections.

Case identity and vehicle context

The vehicle object is the connecting thread: the identity is recorded once (normally via the work-order scan, which now also reads claim/warranty numbers and insurance references) and is then reused everywhere:

• Identity row in the workspace — work order, claim, insurance reference, vehicle, registration, VIN, odometer, responsible technician, plus the case type selector.
• Live Share — a locked panel at the top with vehicle, references and status, derived from the level-filtered record.
• First page of the final report — case information and vehicle information, automatically.
• The export — identity plus traceability package in every JSON.

Terminology

The product is never described as an "AI app" but as an evidence-based diagnostic system / intelligent decision support. In the user interface and in documents the words used are the system, the analysis, the assessment, the interpretation, the image interpretation, the decision support, the rule engine — not "AI", unless technically necessary.