Module policy_engine 

Ordered policy execution for one lifecycle point. What: Run shipped policies in registry order for one lifecycle point and settle the outcome: which events were produced and whether the command may proceed. Why: Every lifecycle shares one execution contract: a policy runs only for the triggers it declares, at the configured severity, unless it is filtered out, escaped or off; the first error finding stops the pass unless the caller asked to keep going; and a policy or lifecycle this executable cannot evaluate is reported as unavailable, never as clean.

In TS you’d write (pseudocode):

// const stage = await runPolicyStage({ policies, context, trigger, severities, selectedPolicyIds, escapedPolicyIds, keepGoing });

Structs

PolicyFinding

What: One thing a policy reports. A struct is a record with named fields; String is owned UTF-8 text; Option<T> is “a value or nothing”; &'static str is text baked into the program. Why: A policy describes what it found; the engine adds the trigger, the policy name and the configured severity when it turns the finding into an event.

StageRequest

What: The settings of one stage. A struct that owns its values: PolicyConfig, Controls and Vec<PolicyId> are copies made once per invocation. Why: Owning small copies keeps the record free of borrowing rules, so it can be handed to every stage of an invocation as one plain value.

StageResult

What: The events of one stage and how it ended. Vec<PolicyEvent> is an owned list. Why: Events gathered before a stop are still reported.

Enums

PolicyOutcome

What: What one policy check returned. An enum is a closed set of named alternatives; Failed { code, message } carries named fields. Why: “Nothing found”, “cannot be evaluated here” and “could not finish” are three different answers; folding the last two into an empty finding list would let an unchecked command through. A policy that could not finish names its cause: content-unavailable when candidate bytes or a repository fact could not be read, policy-incomplete when its own machinery failed.

StageEnd

What: How a stage ended. Why: The caller continues only after Completed; each other ending has its own exit code.

Unavailable

What: Why a pass could not be evaluated by this executable. Why: The refusal names either a whole lifecycle or one policy and what it needs.

Constants

BLOCKED_EXIT_CODE

What: Exit code when a pass ends with an error finding or a fixed-transform rejection. i32 is a signed 32-bit integer, the type of process exit codes. Why: Callers branch on 1 for “policy said no” and on 2 for “could not decide”.

Traits

PolicyChecks

What: The policies behind the stage. A trait is a named set of methods a type promises to provide, like a TS interface; &mut self lends the provider for writing, because a check may cache repository facts. Why: The stage owns order, severity and stopping; this seam owns what each policy reads. Tests drive the stage with a scripted provider, the executable with real Git.

Functions

any_policy_applies

What: Whether any of policies would be evaluated for this request. Why: A lifecycle that only exists for its policies (manual push) is not applicable when none is enabled, and the caller must know that before asking the stage.

pass_exit_code

What: The exit code of a pass that did not reach Git, from its events and its ending. &[PolicyEvent] borrows the events of every stage of the pass. Why: 0 means clean or warnings only, 1 means an error finding, a fixed-transform rejection or a pending correction, and 2 means the pass could not decide.

run_policy_stage

What: Run policies in the given order. &mut dyn PolicyChecks lends “any provider of checks” for writing (dyn means the concrete type is chosen at run time, like a TS interface value). Why: One policy at a time, in registry order, so findings and their numbers are reproducible. A trigger whose lifecycle is not ported ends the stage before any policy runs.