🔌 Integrator

Plugin Hook Reference

3 min readPlugin author · Integratorv0.9.0a1 stable

What this page covers

The 22-hook surface defined for PR 4-INF.1 and used by the v0.9.0aN plugin infrastructure. Aligned with node/src/stigmem_node/plugins/hooks.py.

Do not add hook names beyond this list for v0.9.0a1-compatible plugins.

For a complete package example, start with the Plugin Author Guide.

Handler semantics

Every handler receives a PluginContext as its first positional argument. Hook-site payloads are passed as keyword arguments unless the semantic says a current value is passed positionally.

Semantic

Registry

Handler shape · return

voting

fire_voting

def handler(ctx, **kwargs) -> Allow | Deny. Return Allow() or Deny("reason").

filter_chain

fire_filter_chain

def handler(ctx, value, **kwargs) -> T. The transformed value. Returning None is an error.

score_delta

fire_score_delta

def handler(ctx, scored_results, **kwargs) -> dict[str, float]. Score deltas keyed by result or fact id. Summed across handlers.

fire_and_forget

fire_fire_and_forget

def handler(ctx, **kwargs) -> None. Audit hooks marked strict raise on handler failure.

Ordering policies

Policy

Order

Meaning

core_first

core → plugins

Core handlers run first, then plugin handlers in deterministic plugin order.

plugins_first

plugins → core

Plugin handlers run before any core handlers.

core_only_default

core baseline

Core behavior is the default path; plugins may observe or extend where registered.

plugin_only

plugins only

Only plugin handlers run for the hook.

Stable hook surface

Hook

Semantic · Ordering

Notes

pre_assert_authorize

voting · core_first

Authorize a fact assertion before validation and persistence.

pre_assert_validate

voting · core_first

Validate an assertion payload before transformation.

pre_assert_transform

filter_chain · plugins_first

Rewrite or normalize the assertion payload.

post_assert_persist

fire_and_forget · plugin_only

Observe post-persistence assertion effects.

post_assert_propagate

fire_and_forget · plugin_only

Observe propagation scheduling after assertion.

post_assert_audit

fire_and_forget · core_only_default

Strict audit hook. Handler failure is surfaced.

pre_recall_authorize

voting · core_first

Authorize a recall request.

pre_recall_rewrite

filter_chain · plugins_first

Rewrite the recall query or request payload.

recall_filter

filter_chain · plugins_first

Filter recall candidates or result collections.

recall_rank

score_delta · plugins_first

Add rank score deltas by result or fact id.

post_recall_audit

fire_and_forget · core_only_default

Strict audit hook for recall completion.

federation_peer_authenticate

voting · core_first

Authenticate a federation peer.

federation_inbound_validate

voting · core_first

Validate inbound federation data.

federation_inbound_filter

filter_chain · plugins_first

Filter or rewrite inbound federation facts.

federation_outbound_filter

filter_chain · plugins_first

Filter outbound federation payloads.

federation_outbound_sign

filter_chain · plugins_first

Add or transform outbound signing material.

identity_resolve

filter_chain · core_first

Resolve identity context from authentication material.

tenant_resolve

filter_chain · core_first

Resolve tenant context for a request.

capability_check

voting · core_first

Authorize capability use.

migration_register

filter_chain · core_only_default

Register plugin-owned migrations; must remain namespaced to their declaring plugin.

audit_emit

fire_and_forget · core_only_default

Strict audit hook for normalized audit events. Handler failure is surfaced.

config_validate

voting · core_first

Validate plugin or node configuration before registration proceeds.

Lifecycle health is not a hook

health_check is a PluginManifest lifecycle callable, not a hook.

It is used by operator inspection and health reporting. It is not part of the 22-hook PR 4-INF.1 surface and must not appear in the manifest hooks mapping.