Hook Definition

A Hook Definition declares a Hook — a piece of behaviour that observes or intercepts Transactions. Two kinds:

  • Pre-commit runs at gate 4 of the approval pipeline. Synchronous. Veto-capable. Fail-closed on timeout or error.
  • Post-commit runs after the atomic commit. Fire-and-forget. Cannot retroactively decline. May submit follow-up Transactions, subject to registry-enforced depth limits and cycle detection.

Phase 1: code-at-init

In Phase 1 the Hook's logic is code compiled into the registry binary. On service init the registry walks the set of shipped hooks and publishes a HookDefinition document for each, so every hook is discoverable through the same queries that surface everything else. Post-commit only in Phase 1; pre-commit is wired in Phase 4.

Trigger matching

A HookDefinition declares what Transactions it cares about — a predicate set, a target Type, a named-graph selector, or a free-form SHACL pattern over the Transaction payload. The registry pre-compiles matchers and fires the hook whenever an incoming Transaction matches.

Failure policy

  • Pre-commit: timeout or error → the transaction declines with a gate-4 reason identifying the hook.
  • Post-commit: retry with exponential backoff up to a configurable limit; after that, log + emit a sdg:hookDeliveryFailed event (which post-commit monitoring hooks can observe).

Later-phase upgrades

Phase 4+ adds HTTP webhook transport, signing, retry policy, dynamic external registration without redeploy, and the pre-commit gate wiring.