fix!: one authority for which hooks exist

[araujof]

Description

BUILTIN_HOOK_METADATA is now the single authority for the hooks the engine dispatches. It held ten of thirteen, builtin_hook_types() restated the set by hand with six of sixteen entries right, and two more constant modules named hooks nothing fires. Nothing consumed either enumeration, so the drift was never caught.

define_hooks! emits a hook's name constant and its metadata row from one declaration, making a constant without a row unrepresentable. Adds cmf.http_response so the L7 path has a return half.

Closes: #37

Breaking

• hooks::types::hook_names and cmf_hook_names removed — 16 constants with no dispatch site. Use cmf::constants plus identity::HOOK_IDENTITY_RESOLVE, delegation::HOOK_TOKEN_DELEGATE, elicitation::HOOK_ELICIT, whose paths and values are unchanged.
• hooks::lookup returns Option<HookMetadata>; unknown() is now permissive(). Migrate with .unwrap_or_else(HookMetadata::permissive).
• An unknown hooks: entry now refuses the config, and load_config / from_config validate where they previously did not. A host with its own hooks must call register_hook_metadata before loading config naming them.
• cmf.http_request gaining an entity type narrows dispatch as well as correcting its phase: a row-less hook matched every entity type.

Full notes in CHANGELOG.md.

[praxis-bot]

Review: fix!: one authority for which hooks exist

Well-structured fix. The define_hooks! macro makes the drift between name constants and metadata rows unrepresentable at compile time, which is the right solution for a class of bugs that tests cannot fully catch (any test walking the table is itself a second hand-maintained list). Config-time hook name validation, the Option return from lookup, and the normalization of every load path are all clean.

One test gap noted below.

Severity	Count
Medium	1

[praxis-bot]

[Medium] The test verifies the response handler installs for a post-only config but does not assert the request handler is absent. Without the negative check, a regression that installs both handlers whenever either set of phases is declared would pass this test (the both_http_halves_install_and_evaluate_independently test checks both install, but nothing checks that a single-phase config installs only one).

Add a companion assertion:

assert!(
    !mgr.has_hooks_for(HOOK_CMF_HTTP_REQUEST),
    "a post-only global policy must not install the request handler",
);

The symmetrical gap exists for the pre-only test above this PR's changes, but establishing the pattern here prevents it from widening.

[terylt]

Overall

The core idea is great.

Specific things that hold up well:

• The const-fn flattening of HOOK_TABLES into BUILTIN_HOOK_METADATA is careful, and HOOK_COUNT deriving the length from the tables avoids restating it.
• Tests are anchored on hook names rather than on the table's own length or key order. the_enumeration_names_the_hooks_that_dispatch names each hook the old hand-maintained list got wrong, so it would have failed against the previous code. Comparing a projection to the thing it projects cannot fail, and the author says so in the test.
• authority_holds_every_declared_hook guards the one gap the macro leaves, which is a module table dropped from HOOK_TABLES.
• Turning lookup into Option<HookMetadata> and making the caller ask for permissive() is the right shape. dispatch_plan.rs preserves the old behavior explicitly with .unwrap_or_else(HookMetadata::permissive).

Finding: MessageView::is_pre and is_post are a second phase authority

crates/ppe-core/src/cmf/view.rs:226-233

pub fn is_pre(&self)  -> bool { self.hook.is_some_and(|h| h.contains("pre")) }
pub fn is_post(&self) -> bool { self.hook.is_some_and(|h| h.contains("post")) }

Neither of the two hooks this PR adds contains the substring it would need. cmf.http_response has no post in it, and cmf.http_request has no pre. So the PR registers cmf.http_response with phase: Post in the authority while is_post() answers false for it, and is_pre() answers false for cmf.http_request.

Both feed to_dict as the policy-visible is_pre and is_post fields (crates/ppe-core/src/cmf/constants.rs:15-17).

Reproduced on the PR head. A probe printing the authority next to the accessors:

authority: cmf.http_request  = Pre
authority: cmf.http_response = Post
view:      cmf.http_request  is_pre=false is_post=false
view:      cmf.http_response is_pre=false is_post=false

Severity is limited. Nothing in the workspace calls is_pre, is_post, to_dict, or iter_views outside view.rs itself, so there is no live regression. It matters because these are public API for plugin authors, and because it leaves a second phase authority standing in a PR whose thesis is that there should be one.

Suggested fix, which was applied and tested:

fn phase_is(&self, phase: HookPhase) -> bool {
    self.hook
        .is_some_and(|h| lookup_hook_metadata(h).is_some_and(|meta| meta.phase == phase))
}

with is_pre and is_post delegating to it. That also removes a latent problem in the heuristic, which is that any hook name containing pre as a substring reads as pre-phase. express contains p, r, e consecutively.

What the fix surfaces

Applying it turns up exactly one dependent, and it is worth looking at rather than just patching:

to_dict_emits_every_context_field_it_is_given builds its view with the hook name cmf.resource_pre_read and asserts is_pre == true. There is no such hook. The dispatched name is cmf.resource_pre_fetch, and cmf.resource_pre_read appears nowhere in the authority. The substring heuristic classified a hook that does not exist, which is the same class of drift this PR exists to remove.

Pointing that fixture at cmf.resource_pre_fetch and re-running gives 508 passing, 0 failing, including a probe asserting both new HTTP hooks agree with their registered phase.

Note: the test fixture is order-dependent by construction

register_fixture_hooks() in crates/ppe-core/src/engine.rs mutates a process-global registry. Once any of the 29 tests that call it has run, test_hook stays registered for the rest of the process.

I parsed all 84 tests in the PR's engine.rs and found no test that names test_hook in a config without calling it, so this is correct as it stands. The concern is the next test someone adds: forgetting the call yields a test that passes or fails on thread scheduling rather than failing outright.

Registering inside make_config, which is the shared helper that builds the configs naming test_hook, would make it structural instead of a convention each new test has to remember.

Note: global registry against per-instance engine

register_hook_metadata is process-wide while PolicyEngine is per-instance, so two engines in one process share hook metadata and one host's custom hook validates in the other host's config.

This is pre-existing, but the PR promotes it from affecting dispatch defaults to gating whether a config is accepted at all. Worth a line in the breaking-change notes, since the failure it produces is a config that loads in one process layout and refuses in another.

Smaller observations

• validate_declared_hooks returns on the first unknown hook, so an operator with three typos does three load-and-fail cycles. The duplicate-name check immediately below it returns early the same way, so this matches house style and is not worth changing on its own.
• edit_distance is a correct two-row Levenshtein. I checked the recurrence, the initial row, and both empty-string cases.
• nearest_known_hook bounds the suggestion by distance * 2 <= longest and counts chars on both sides rather than bytes, which is the right call for a multi-byte name. The three tests cover a suggestion that lands, a different one that lands, and a name far enough away to get none.
• The global HTTP catch-all now installs a Post handler as well as a Pre one, so global response filtering works on the entity-less HTTP path. That is a behavior addition rather than a refactor, and global_http_authz.rs covers it.

What was and was not run

Run: cargo test -p praxis-policy-core on the PR head (508 passing), the probe above, and the same suite again with the suggested fix and the corrected test fixture (508 passing).

Not run: the rest of the workspace, make ci, and the --all-features pass. No live host was involved, so nothing here says how the new HTTP catch-all Post handler behaves under a real proxy.

The two notes below the finding are from reading, not from execution. The test-ordering one is backed by parsing all 84 tests in the PR's engine.rs and finding no test that names test_hook without registering it, which says the current suite is correct, not that the pattern is safe.

[terylt]

Some small change requests above.. nothing big.