Technical notes & release report
Electrical Fault-Finding Laboratory • 24 V DC • 8 November 2026
Release report
# IES Electrical Fault-Finding Laboratory: V1.1 release report Release: 8 November 2026. Existing route: https://ieskills.org.uk/simulations/electrical-fault-finding Application release: 1.1. Engineering model: dc-v1.0 (unchanged). ## Implemented changes ### A. Guided practicals All five existing IDs (01–05) and numeric questions/tolerances are preserved. Each practical now presents eight stages: objective, theory, equipment preparation, prediction, measurements, evidence, interpretation and completion feedback. Progress, Previous, Next and Resume controls retain work. Next requires preparation confirmation, a written prediction, at least three valid measurements and written interpretation/explanation before completion. One guided draft is saved on the current browser profile. Refresh followed by Resume restores the activity ID, attempt UUID, step, notes, readings, meter/probe state and circuit/protection state. Changing modes does not discard that stored practical. Drafts are validated before restoration. Completed investigations are separate from drafts and require explicit account save or export. The application checks evidence count and numeric answers; measurement relevance and written reasoning still require lecturer judgement. ### B. Schematic and equipment synchronisation One investigation owns one electrical LabState. Both views use the same solved Snapshot. Component selection, active probe and selected node persist across view changes. A shared component catalogue maps the existing component IDs to electrical nodes. Selecting a terminal in the diagram, terminal pad or probe selector dispatches the same meter action. Selected components and relevant nodes have outline/pattern emphasis; R+ and COM labels supplement probe colours. The inspector shows nominal details and observable operating states, not concealed fault parameters. ### C. Multimeter workflow An accessible live summary states function, red point, black point and socket. Separate text status identifies valid calculated readings, invalid configurations, floating nodes, OL resistance paths, Q1 trips and meter fuse operation. The source network, 10 MΩ voltmeter, 0.1 Ω shunt, relay and protection calculations are unchanged. Voltage polarity, current insertion across opened J1, isolation and persistent fuse/trip behaviour remain enforced by the original engine. ### D. Independent Challenge One fault remains concealed per attempt. Submission is rejected until at least three valid records, a suspected fault, supporting explanation and alternative-diagnosis discussion exist. Rejected submissions do not reveal the fault. After submission the outcome compares the suspected fault with the injected fault, summarises recorded functions/node pairs and suggests further voltage-drop or isolated-resistance work based on measurement coverage. Written reasoning is retained for lecturer review and is explicitly not automatically graded. Once submitted, the workflow preserves completed readings and notes; another experiment is required to edit evidence. ### E. Results and recovery The existing session, database table, ownership rules and account permissions are retained. There is no schema migration. Optional V1.1 fields add explicit model/release versions, stable activity ID, prediction, interpretation, alternatives and per-reading apparatus/socket context. Existing V1 records and JSON exports remain readable; absent historic context is not fabricated. Learners can open their own completed investigations read-only. Single-attempt retrieval applies member ID, activity kind and attempt key predicates on the server. Missing and non-owned attempts both return 404. Client-supplied member IDs cannot change ownership. New My IES activity links reopen the specific attempt. Historical readings are displayed without recalculation, and reopening leaves the current circuit untouched. Corrupt stored metadata is excluded safely. CSV and JSON exports are retained. A new escaped standalone lecturer HTML record includes model, attempt, outcome, reasoning, alternative diagnoses, timestamps, readings, probe positions, socket and apparatus states. It can be printed or saved as PDF through the browser. Anonymous device copies and exports remain available. Completed cloud records still use the existing backward-compatible POST update/retry behaviour; this is not a tamper-proof assessment system. ### F. Responsive and accessible interaction The diagram retains a readable minimum width and scrolls within its own region on narrow screens. A separate terminal pad gives all seven nodes large native buttons. Component and terminal controls support keyboard activation and accessible labels. Stage navigation moves focus to its heading; opening a saved record moves focus to the read-only panel. Focus outlines, text status and patterned highlights supplement colour. The meter stacks on narrow screens. Classroom display mode enlarges controls, diagram labels and the meter reading to 44 px. Reduced motion follows the system preference and remains manually selectable. ### G. Shared interfaces The reusable calculation, instrument and fault interfaces are retained. New workflow, selection, activity-guide, result-validation and result-document interfaces are documented in architecture.md. Result schema version 1 remains backward-compatible through optional fields. No future simulator or hardware connection has been built. ## Automated tests and build The production build and all 58 automated tests passed; zero test failures in the final suite. - All 15 original electrical/framework groups pass, including 5,488 fault/power/function/socket/probe combinations, independent series/parallel reference calculations, KCL/power conservation, relay switching, short/high/open faults, instrument loading, socket errors, Q1/fuse latching, isolation and reset repeatability. - Eleven new workflow groups cover the five stable activities, stage gates, Previous preservation, exact draft round-trip, synchronised probes/polarity, measurement-status categories, concealed-fault rejection, invalid-record exclusion, immutable completed workflow evidence, V1/V1.1 result compatibility, lecturer export escaping and component inspection. - The existing isolated Miniflare/D1 integration test now also covers single-attempt recovery, guessed foreign attempt IDs returning 404, malformed IDs returning 400, forged client member IDs ignored, optional V1.1 fields preserved, deep My IES links, old V1 defaults, corrupt stored rows, anonymous/inactive rejection and existing-resource preservation. Synthetic accounts only; no production learner records used. - Existing public routes, membership/billing restrictions, administration, resources, announcements, curriculum, regions, qualification navigator, tensile and beam regression tests pass. - Strict checking of the new pure framework/workflow modules passes. The whole-repository TypeScript check still reports the same pre-existing diagnostics outside the laboratory (nullable organisation, Cloudflare Worker types, commercial BufferSource typing, seed-content and example D1 typing). These are unresolved baseline issues, not claimed fixed; the production build succeeds. - Core engine files are byte-identical to the V1 source: core/network.ts, electrical-model.ts, instruments.ts and faults.ts. No reference solution, electrical constant or protection threshold changed. ## Browser regression results Scripted Chromium checks passed on the local preview before publication: | Check | Observed result | |---|---| | Desktop shared probes | X/0 gives 13.01 V. Equipment-to-schematic switch retains the same probes and R1 selection. Changing black to PS gives -10.99 V. Enter and Space activate terminal controls. | | Guided practical | Preparation gate blocks early Next. Prediction, three distinct records and interpretation are retained. Refresh/Resume restores step 6, the same attempt and meter state; Previous preserves the readings. 109.09 mA is accepted for the ideal series calculation. | | Completed recovery | A completed device record reopens read-only with versions, attempt, prediction, explanation, interpretation and three historical measurements. Returning to the experiment leaves the meter at 23.85 V. | | Challenge concealment | Zero records rejected. Three records without alternatives rejected. No fault selector is displayed. Supporting evidence and alternatives permit submission; an open-J1 investigation was correctly diagnosed from 24.00 V source, 0 V X and 23.92 V K. The fault appears only after submission and controls then preserve the evidence. | | Mobile (390 px outer; 375 px content) | Terminal keyboard input and view switch retain 13.01 V and the full meter summary. Native terminal targets at least 74.75 × 52 px. No page-wide horizontal overflow. Q1 trip status remains clear. | | Tablet (768 px outer; 753 px content) | Same probe/view regression passes. Targets at least 89.94 × 52 px. Incorrect A-socket placement opens the virtual fuse. Open-J1 current measurement gives 0.1084 A; Reset restores isolated supply and 0 V. | | Classroom (1920 px outer; 1905 px content) | Same probe/view regression passes without body overflow. Classroom mode enlarges the meter output to 44 px. | | Reduced motion | Selecting the option applies the reduced-motion state. Existing electrical results have no animation dependency. | | Lecturer export | Browser download of the standalone HTML record succeeds. Serializer tests verify escaped learner content and preserved OL readings. | The reusable responsive script is tests/browser/electrical-v11.cua.js. It uses supported browser interactions and read-only DOM measurements; no application state is injected. Same-origin iframe viewport checks test responsive Chromium layout, not physical iOS/Android, Safari/Firefox, a physical 75-inch board or assistive-technology certification. ## Engineering assumptions The V1 dc-v1.0 model is unchanged: linear steady-state 24 V DC; finite source, switch, link and contact resistances; constant-resistance lamps and coil; hysteretic relay switching; voltage input loading; current shunt burden; finite fault impedance; simplified instantaneous latching Q1 and meter fuse. No heating, inductive flyback, contact bounce, AC, arcing, real fuse time-current curves, transient waveforms or calibrated luminous intensity. Floating measurements are explicitly identified. No industrial-grade accuracy, certification or qualification credit is claimed. ## Issues and limitations - Physical-device/browser/screen-reader validation and an independent engineering/education review remain outstanding. - Browser drafts are one practical per browser profile, shared by users of that profile. Drafts do not synchronise between devices or accounts. Completed account evidence can be reopened on another authenticated device. - Account ownership and recovery are tested in isolated D1; no real production learner account was used for QA. - Formative outcomes and narratives are client-reported. The software checks numeric answers/evidence count and fault selection, not the quality of free-text reasoning or practical competence. - The existing whole-repository TypeScript diagnostics described above remain unresolved. - There is no arbitrary wiring editor, multiple simultaneous injected faults, lecturer cohort dashboard, certificate, hardware link or newly verified qualification mapping. - The development preview and build were initially blocked by automatic review over possible Cloudflare disclosure. Inspection confirmed local Miniflare use. Development bindings are now explicitly local and Wrangler usage telemetry is disabled; the safer build and preview then ran successfully. Production hosting/audience and authentication were not changed by this local-tooling adjustment. ## Publication gate Publication is permitted only after the complete test suite, production build and scripted browser checks above pass. Source is versioned in the existing Site repository. Successful deployment and live smoke verification must be confirmed separately; this report does not substitute for that confirmation.
Architecture, assumptions & interfaces
# IES Virtual Engineering Laboratories: V1.1 interfaces and V1 model ## V1.1 interface refinement (8 November 2026) The physics model remains dc-v1.0. `core/network.ts`, `electrical-model.ts`, `instruments.ts` and `faults.ts` are unchanged from V1. V1.1 adds learner workflow and presentation state around that engine. - `workflow.ts` defines `Investigation`, `InvestigationAction`, `investigationReducer`, `newInvestigation`, `validateDraft`, `selectTerminal`, `meterSummary` and `measurementStatus`. The investigation owns exactly one `LabState`. Electrical actions still call the existing engine transition; UI view and selection data never supply readings. - `activity-guides.ts` adds objective, preparation, prediction, measurements and interpretation to the five stable activity identifiers 01–05. Existing `activities.ts` identifiers, numeric questions, tolerances and answers remain compatible. Eight stages include progress, Previous, Next and Resume. Next gates preparation confirmation, prediction, evidence count and interpretation. Recorded measurement usefulness still requires learner/lecturer judgement. - `circuit-view.tsx` draws equipment and schematic from the same snapshot. `components.ts` maps existing component IDs to the same node names. Selection is presentational. Changing a terminal dispatches one shared meter action. Nominal component details do not disclose internal injected fault values. Operating states reflect observable physical behaviour. - `guided-practical.tsx` manages accessible stage presentation and heading focus. The browser draft key `ies-electrical-guided-draft-v11` retains one current guided practical, including step, attempt, circuit, notes and measurements. Resume validates that the fault matches the guided activity and re-settles the existing engine. Drafts are local to the browser profile, not account-owned cloud records. No identity/session token is stored in a draft. Completed attempts are removed from draft storage and must be explicitly saved/exported. - Result `version: 1` and simulator `electrical-dc-v1` are retained. Optional fields: `modelVersion`, `releaseVersion`, `activityId`, `prediction`, `interpretation`, `alternatives`; optional per-reading `context` stores socket, power, S1/J1 and protection state. Legacy records missing these fields remain valid. Missing model version defaults to dc-v1.0. Nothing invents old apparatus context or recalculates historical readings. - `/api/account/laboratory-results?attemptId=...` retrieves one completed attempt with member, kind and content-key predicates applied on the server. Non-owned/missing records return the same 404. List reads also validate stored records and skip corrupt metadata. POST retains the existing same-attempt update behaviour, session authentication and member scoping. New My IES activity links include the attempt identifier. No database migration or entitlement change. - `investigation-record.tsx` reopens historical evidence read-only, moves focus to its panel, and exports CSV, JSON and escaped standalone lecturer HTML. `resultHtml` is a document serializer with no executable learner HTML. Client-reported formative outcomes remain unsuitable for secure examination or certification. - The completed evidence object is captured at submission and frozen by the learner workflow. Additional circuit/text/record actions are rejected until a new attempt is started. Server POST remains backward-compatible with V1 retry/update semantics; this is not a tamper-proof assessment store. - `tests/electrical-workflow.test.mjs` covers workflow, drafts, probes, disclosure gates, compatibility and exports. The D1 integration test covers legacy/new recovery, guessed attempt IDs, client-supplied member-ID rejection and malformed metadata. `tests/browser/electrical-v11.cua.js` records the scripted responsive regression using supported browser controls and read-only DOM geometry. The production model still makes all assumptions stated below. No additional discipline, hardware connection, time-current curve or qualification reference is introduced. 8 November 2026. Existing Vinext / React / Cloudflare D1 platform retained. Existing public electrical simulator route upgraded in place. Authentication, membership checks, published resources and other physics modules are unchanged. My IES dashboard launch tile now opens the electrical lab; all laboratories remain available through My Simulations. | Module | Interface and responsibility | Automated coverage | |---|---|---| | A: engineering | `core/network.ts`: `solve(Network): Solution`, `resistance(nodes, branches, red, black): number`; SI units, named nodes and positive finite resistors, fixed voltages, optional injected currents. Returns voltages (null when floating), branch currents/powers and maximum KCL residual. `electrical-model.ts`: state transitions, relay and protection settling. | Ohm law, series/parallel, energy, KCL, disconnected nodes, invalid topology, reference fixtures, state changes and repeatability | | B: interface | `scene.ts`: `visualState(Snapshot)` and node coordinates. `electrical-lab.tsx`: controls dispatch typed `Action`; equipment/schematic render the same solved snapshot. Rendering never supplies electrical values. | Scene contract, rendered route tests; manual browser interactions | | C: instruments | `instruments.ts`: `meterReading(LabState, Solution, passiveBranches): Measurement`. Voltage loading and current shunt stamped into the network by `networkFor`. Socket choice affects circuit even with wrong dial function. | Loading, polarity, missing/equal probes, live-ohms rejection, in-circuit parallel resistance, series insertion, incorrect socket and fuse | | D: faults | `faults.ts`: `injectFault(Branch[], FaultId): Branch[]`; removes components, increases resistance or adds finite short; no lookup table of readings. `chooseFault(random)` selects one fault using a supplied random fraction. | Topology and all component-fault reference cases; challenge selection | | E: learning | `activities.ts`: five `Activity` objects, numeric tolerances, theory/steps and lecturer explanations; `checkAnswer`, `assessDiagnosis`. Unknown faults concealed in controls until accepted submission. | Activity count, numeric boundaries, evidence gate and diagnosis feedback | | F: results | `core/contracts.ts`: versioned `LabResult`, `MeasurementRecord`. `core/results.ts`: validates and bounds untrusted result data, CSV escaping. `/api/account/laboratory-results`: authenticated GET/POST, own-member predicates, existing `member_activity.metadata`, no migration. Formative client-reported outcome, not secure examination grading. | Contract validation, CSV protection; API integration tests | | G: equipment | `EquipmentAdapter`: equipment code, catalogue URL, model version, `connection: virtual-only`. Links to existing IES-ET01 concept. | Equipment contract / scene tests | ## Shared framework `SimulationEngine<State, Action, Snapshot>` provides initial state, pure transitions and snapshot. The electrical engine conforms structurally; additional disciplines can implement their own states and solvers and reuse measurement, evidence and equipment contracts. Materials, PLC, structural, fluids, thermal, automotive, aircraft and Arduino physics/hardware protocols are not added here. Existing tensile and beam laboratories are retained, not migrated in this release. A true hardware digital twin needs a separately authenticated device adapter, calibration metadata, timing/quality flags and input validation. No hardware control or telemetry occurs in V1. ## Electrical network Source PS is 24 V relative to 0 when enabled and disconnected when off. PS-to-P: 0.5 Ω source plus 0.1 Ω Q1 resistance. P-to-S: S1 0.1 Ω. S-to-L: removable J1 0.02 Ω. L-to-X: R1 100 Ω. X-to-0: R2 120 Ω. S-to-0: K1 coil 1200 Ω. P-to-K: K1 normally open contact 0.1 Ω. K-to-0: H1 240 Ω. Relay pickup at 18 V coil voltage, dropout below 8 V. Coil-open fault cannot actuate. Welded contact stays conductive independently of coil state. Faults: J1 internal open, +900 Ω at R1, L-to-0 short of 0.05 Ω, open coil, open lamp, welded contact. The displayed nominal schematic intentionally conceals injected internal faults. Test-point labels and component values correspond to actual nodes; rings and probe leads indicate the actual selected node. Colour is not the sole status indicator. Q1: over 0.50 A source-branch current latches the branch open. A port: 0.1 Ω shunt; over 0.25 A shunt current latches the meter fuse open. At each static step the finite network is solved, thresholds checked, protection latched, relay hysteresis settled and the final topology solved again. If both devices exceed thresholds in the same static step both open; there is no selective-coordination claim. A direct PS-to-0 A-port connection is upstream of Q1 and only the meter fuse protects that path. Rearm/replace is permitted only with power isolated; a persistent fault trips again. Final displayed currents are post-trip values. There is no elapsed-time waveform or estimate of interruption energy. Voltage mode has 10 MΩ input resistance and includes loading. The A socket stamps a shunt regardless of dial selection, unless its fuse is blown. Current across closed J1 is a parallel-path measurement, explicitly identified; valid series work requires isolation, opening J1 and placing probes S/L. V/Ω current mode is rejected. Resistance and continuity are blocked whenever supply is enabled, even if S1 is open or Q1 has tripped. An isolated ohmmeter uses an equivalent 1 A mathematical injection to calculate resistance (not a claimed physical test current). The source branch is removed and coil released; all remaining parallel paths are included. A disconnected path gives OL. Continuity below 30 Ω is a visual indication, with no audio dependency. ## Assumptions and limits Linear steady-state DC only. Lamps are constant resistance and displayed as fraction of nominal electrical power, not calibrated luminous intensity. Relay coil has resistance only. No tolerance distributions, thermal effects, inductance, flyback, transient contact behaviour, capacitance, arcing, actual fuse time-current curves, AC or manufacturer accuracy/range specifications. Floating potentials are not fabricated. No industrial accuracy, certified training, electrical installation competence or safety authorisation is claimed. Do not transfer simulated procedures to mains equipment. ## Reference validation `tests/fixtures/dc-reference.json` is prepared independently using rational series/parallel reduction. Its values are not read by production code. Healthy control branch: 0.1 + [1200 || (0.02 + 100 + 120)]. Lamp branch: 0.1 + 240. The two branches are parallel behind 0.6 Ω source/protection resistance. Fault fixtures adjust reductions analytically. Open/high/coil/lamp/welded cases are compared for source current and P/S/X/K potentials to 1e-8 absolute tolerance; maximum KCL residual below 1e-9 A. Elementary tests use exact V/R, series/parallel and power conservation. This is independently calculated reference evidence, not an external engineer's sign-off. Primary background references (reviewed 8 November 2026): - SpiceSharp nodal-analysis documentation: https://spicesharp.github.io/SpiceSharp/articles/custom_components/modified_nodal_analysis.html - Fluke resistance measurement guidance: https://www.fluke.com/en-us/learn/blog/digital-multimeters/how-to-measure-resistance - Fluke 3000 FC user manual, measurement safety: https://media.fluke.com/437e18a0-de4d-4090-ab8a-b0df016de4fd_original%20file.pdf No third-party source certifies this implementation. ## Qualification mapping A `QualificationMapping` must record awarding organisation, qualification, specification version, unit, learning outcome, criterion, official source URL, verifier, verification date, activity IDs and evidence description. `publishableMapping` rejects unverified entries. The published mapping list is empty in V1: no specification references have been verified in this development task. Proposed conceptual coverage: DC principles, safe instrument configuration, series/parallel circuits, systematic diagnosis and recording evidence. These topics do not establish qualification compliance. ## Results and boundaries Each explicit submission produces a UUID-keyed formative attempt. Save uses the existing account session. Existing `member_activity` rows of other kinds are untouched. Authenticated results are listed in My IES recent activity and accessible in the lab's saved-results panel. Anonymous users can export CSV/JSON; a failed/unauthenticated Save stores a single device copy if local storage is available and says so. Device copies are shared by anyone using that browser profile; no authentication token is stored there. Saved outcome is learner-reported and may be tampered with; no certificates or entitlement changes follow. Limited to 100 readings per attempt and 30 recent server records per results query. Full apparatus session restoration and lecturer cohort analytics are outstanding.