vdm/core/include/vdm/rules/match.hpp

// vdm/rules/match.hpp — the pure evaluation half of the rules engine
// (contracts/schema/types/Rule.schema.json): given a rule table and what's known about one
// candidate download, decide which rule fires and what it says to do.
//
// DAEMON owns the rule table itself — storage, `rules.upsert`/`rules.list`, the wire
// `Rule` type generated from the contract. It decodes its own JSON/SQL representation into
// the plain structs below and calls in; core never sees JSON, SQL, or the generated
// protocol types (CLAUDE.md §3) — these structs mirror the contract's shape in CORE's own
// vocabulary, the same relationship `util/error.hpp`'s `Error` has to the wire error codes.
//
// Pure and total: no I/O, no throw, no crash on any input (an empty table, an empty
// pattern, a rule with every match clause absent).
//
// This header compiles standalone.

#ifndef VDM_RULES_MATCH_HPP
#define VDM_RULES_MATCH_HPP

#include <cstdint>
#include <optional>
#include <string>
#include <string_view>
#include <vector>

namespace vdm::rules {

enum class StartMode { now, later, queue };        // mirrors contracts' StartMode
enum class CaptureVerdict { take, ignore };          // mirrors RuleAction.capture

// All present clauses must match; an absent clause is not a constraint
// (contracts/schema/types/Rule.schema.json's own wording for RuleMatch).
struct RuleMatch {
    std::optional<std::vector<std::string>> extensions;  // no leading '.'; matched
                                                           // case-insensitively
    std::optional<std::vector<std::string>> mime_types;   // matched case-insensitively
    std::optional<std::string> host_pattern;               // glob_match against the host
    std::optional<std::string> url_pattern;                 // glob_match against the whole URL
    std::optional<std::uint64_t> min_size_bytes;             // inclusive
    std::optional<std::uint64_t> max_size_bytes;             // inclusive
};

// What to do with a matching download.
struct RuleAction {
    std::optional<std::string> category_id;
    std::optional<std::string> save_dir;
    std::optional<std::string> queue_id;
    std::optional<std::uint32_t> segments;
    std::optional<StartMode> start_mode;
    std::optional<CaptureVerdict> capture;
};

// One row of the rules engine.
struct Rule {
    std::string rule_id;
    bool enabled = true;
    std::int64_t priority = 0;  // lower runs first
    RuleMatch match;
    RuleAction action;
};

// What's known about one candidate download, to match rules against. A field being empty
// (not `std::nullopt` — these are plain strings, not optionals) means "unknown, matches no
// non-empty clause that needs it" — e.g. `size_bytes` is absent pre-probe, so any rule with
// a size clause simply doesn't match yet; the caller is expected to re-run matching once
// the probe fills it in, same as DownloadSpec itself gets refined post-probe.
struct MatchInput {
    std::string extension;  // lowercased, no leading '.'; empty if none
    std::string mime_type;  // lowercased; empty if unknown
    std::string host;       // lowercased effective-URL host
    std::string url;        // the whole effective URL
    std::optional<std::uint64_t> size_bytes;
};

// Rules are tried in ascending `priority` order (ties broken by table order), skipping
// disabled rows; the first whose every present match clause is satisfied wins.
// `std::nullopt` means no rule matched — the caller falls back to its own default category
// (this function has no notion of a default; that policy lives with the caller).
[[nodiscard]] std::optional<RuleAction> match_rules(const std::vector<Rule> &rules,
                                                     const MatchInput &input);

// Case-insensitive glob: '*' matches any run of characters including none, '?' matches
// exactly one character. No character classes, no escaping — rule patterns are meant to
// stay simple (contracts/schema/types/Rule.schema.json's own hostPattern/urlPattern
// description gives only "*.example.com" as the example). Exposed on its own because
// hostPattern and urlPattern are both just this against different text, and because it has
// its own test table worth keeping separate from match_rules's.
[[nodiscard]] bool glob_match(std::string_view pattern, std::string_view text) noexcept;

}  // namespace vdm::rules

#endif  // VDM_RULES_MATCH_HPP