function [summary, rows] = appendMpiReductionDspOutput(db, run_id, occurrence_idx, dspOutput, dsp_options, options)
%appendMpiReductionDspOutput Store one DSP occurrence in MpiReductionResults.

arguments
    db
    run_id
    occurrence_idx
    dspOutput struct
    dsp_options struct = struct()
    options.study_name string = "mpi_reduction_v1"
    options.dry_run (1,1) logical = false
    options.verbose (1,1) logical = false
end

summary = emptySummary();
rows = {};

packageNames = fieldnames(dspOutput);
if isempty(packageNames)
    return
end

block_update = resolveBlockUpdate(dspOutput, dsp_options);
wh = DataStorage(struct( ...
    "run_id", double(run_id), ...
    "block_update", double(block_update)));

hasPackages = false;
for packageIdx = 1:numel(packageNames)
    packageName = packageNames{packageIdx};
    package = dspOutput.(packageName);
    if isempty(package)
        continue
    end

    if iscell(package)
        packageCell = package;
    else
        packageCell = {package};
    end

    wh.addStorage(packageName);
    wh.addValueToStorageByLinIdx(packageCell, packageName, 1);
    hasPackages = true;
end

if ~hasPackages
    return
end

dsp_options_local = dsp_options;
dsp_options_local.start_occurence = occurrence_idx;
dsp_options_local.userParameters.block_update = block_update;

[summary, rows] = appendMpiReductionWarehouse(db, wh, run_id, dsp_options_local, ...
    "study_name", options.study_name, ...
    "dry_run", options.dry_run, ...
    "verbose", options.verbose);

end

function summary = emptySummary()
    summary = struct( ...
        "rows_considered", 0, ...
        "rows_inserted", 0, ...
        "rows_skipped_duplicate", 0, ...
        "rows_skipped_existing_key", 0, ...
        "rows_skipped_empty", 0);
end

function block_update = resolveBlockUpdate(dspOutput, dsp_options)
    if isfield(dsp_options, "userParameters") && ...
            isfield(dsp_options.userParameters, "block_update") && ...
            isscalar(dsp_options.userParameters.block_update)
        block_update = dsp_options.userParameters.block_update;
        return
    end

    packageNames = fieldnames(dspOutput);
    for packageIdx = 1:numel(packageNames)
        package = dspOutput.(packageNames{packageIdx});
        if isempty(package)
            continue
        end
        if iscell(package)
            package = package{1};
        end
        if isstruct(package) && ...
                isfield(package, "mpi_reduction_config") && ...
                isfield(package.mpi_reduction_config, "params") && ...
                isfield(package.mpi_reduction_config.params, "block_update")
            block_update = package.mpi_reduction_config.params.block_update;
            return
        end
    end

    error("appendMpiReductionDspOutput:MissingBlockUpdate", ...
        "Could not resolve scalar block_update from dsp_options or package metadata.");
end