#pragma once
// usage_scan — the extension-side shell of the instance-usage seam (see
// sample_usage.h for the pure core and fail-safe folds). At prune-scan time it
// answers one question: which project-relative bank paths are held by a live
// ReaSampler 9000 instance — or must the prune abort because a usage record
// could not be read?
//
// Three reads, no writes: (1) enumerate every "rsusage_<guid>" key and decode
// each record — unreadable/undecodable folds to abortPrune; (2) enumerate
// every ReaSampler 9000 FX instance (all tracks incl. master, normal +
// record/input chains, containers recursively, take FX) via
// sample_usage::identityMatches; (3) fold with the pure liveness rule — zero
// instances identified anywhere protects every record's paths.
//
// Feeds prune_reconcile::mergeReferenced in persist's scanPruneOrphans — a
// held capture can never be an orphan. abortPrune propagates to the action,
// which halts.
//
// REAPER-facing: the .cpp includes reaper_plugin_functions.h WITHOUT
// REAPERAPI_IMPLEMENT (main.cpp owns the API pointers). The header stays
// REAPER-free (`proj` is the opaque ReaProject* passed as void*).

#include <string>
#include <vector>

namespace reasampler {

// When abortPrune is true, a present rsusage_* record could not be read or
// decoded — the caller MUST halt the prune. offendingKeys names the exact
// keys that triggered the abort, so the action can print them for recovery
// (clear via ReaScript: reaper.SetProjExtState(0, "reasampler", "<key>", "")).
// heldPaths on abort is the protect-all set — a belt-and-braces fallback; the
// abort flag is authoritative. Otherwise heldPaths is every project-relative
// path held by a live instance, de-duped, in record order.
struct UsageScanResult {
    bool abortPrune = false;
    std::vector<std::string> offendingKeys;  // non-empty iff abortPrune
    std::vector<std::string> heldPaths;
};

// Scan `proj` (nullptr = active project). READ-ONLY: no ext-state write, no project
// mutation.
UsageScanResult liveInstanceHeldPaths(void* proj);

}  // namespace reasampler
