function [cases, ctx] = osi_test_cases(ctx)
%OSI_TEST_CASES Canonical 5-case battery for OSI stability-margin indicators.
% Each case isolates ONE failure mechanism, so an indicator can be scored on what
% it actually catches. Cases 1-3 keep the binding mode in M7's 25-42 Hz band
% (what M7 is built for); cases 4-5 MIGRATE the mode out of that band (the cases
% that expose a fixed-band assumption) -- case 4 by integral action, case 5 by
% pure phase lag (gain unchanged).
%
%   [cases, ctx] = osi_test_cases()        % loads models from saved_results
%   [cases, ctx] = osi_test_cases(ctx)     % reuse a loaded ctx (C0,Hh,Hd,dt,sigma)
%
% cases(i) fields: id, name, mechanism, tests, C (controller tf), H (plant tf,
%   discrete), delay_samples, expect_inband (binding mode in 25-42 Hz?).

if nargin < 1 || isempty(ctx)
    here = fileparts(mfilename('fullpath'));
    main = fileparts(fileparts(fileparts(here)));
    sr = fullfile(main,'saved_results'); dt = 1/2048;
    H7 = load(fullfile(sr,'exp_tf','tf_sp_1_7000_20260627_210411.mat'));
    H5 = load(fullfile(sr,'exp_tf','tf_sp1_5000_20260627_233333.mat'));
    pv = H7.pid_values;
    ctx.dt = dt; ctx.sigma = H7.source_noise_std;
    ctx.C0 = tf(pid(pv.P,pv.I,pv.D,1/pv.derivative_filter_N,dt, ...
        'IFormula','ForwardEuler','DFormula','ForwardEuler'));
    ctx.Hh = H7.models.H_dc_dm_d;          % healthy plant dc->dm (discrete)
    ctx.Hd = H5.models.H_dc_dm_d;          % measured damaged plant
end
dt = ctx.dt;
CI = tf(pid(0.15, 200, 0.0015, 1/512, dt, ...   % integral-heavy controller (case 4)
    'IFormula','ForwardEuler','DFormula','ForwardEuler'));

cases = struct( ...
 'id',{'C1','C2','C3','C4','C5'}, ...
 'name',{'Healthy', 'Gain damage (measured)', 'Excess gain (extrapolated)', ...
         'Integral-driven', 'Phase-lag (added delay)'}, ...
 'mechanism',{'none -- reference, must not false-alarm', ...
   'H_dc_dm gain rises ~2.4x (the 7000->5000 specimen)', ...
   'H_dc_dm gain rises ~3.8x (damage beyond the measured specimen)', ...
   'integral action raised 10x (I:20->200), gain unchanged', ...
   'pure transport delay added (160 samples ~ 78 ms), gain unchanged'}, ...
 'tests',{'no false alarm during calibrated-healthy operation', ...
   'the in-band design case (binding mode ~37-40 Hz)', ...
   'deeper in-band damage -- margin lower, still in band', ...
   'binding mode MIGRATES to ~20 Hz -- out of a fixed 25-42 Hz band', ...
   'PHASE-driven instability; mode migrates to ~3 Hz -- out of band'}, ...
 'C',{ctx.C0, ctx.C0, ctx.C0, CI, ctx.C0}, ...
 'H',{ctx.Hh, ctx.Hd, 3.8*ctx.Hh, ctx.Hh, ctx.Hh}, ...
 'delay_samples',{0, 0, 0, 0, 160}, ...
 'expect_inband',{true, true, true, false, false});
end