Module registry 

Structs

CommandSpec

OwnedPolicy

Functions

build_registry

canonical_name

The canonical command name cmd resolves to via the registry’s alias map (gcat → cat, glink → ln). Returns cmd unchanged when it is already canonical or unknown, so callers can canonicalize unconditionally. This is what lets the engine’s path-gate dispatch reach an aliased invocation: without it, gcat /etc/shadow misses every resolver and falls through to the (ungated) legacy classifier. Custom registry first (an override may rename), then TOML.

check_handler_policy

Validate tokens against cmd_name’s named flag policy declared in a [command.handler_policy.KEY] block. Returns false if no such policy is declared or the tokens fail it. Used by handlers whose dispatch logic genuinely can’t move to TOML (e.g. gh’s sub × action matrix) but whose per-policy WordSets should live in TOML rather than as Rust WordSet constants.

custom_dispatch

Looks up the command in the runtime custom registry (project-local .safe-chains.toml, then user-level ~/.config/safe-chains.toml). A match here wins over the built-in hardcoded handlers, which is how an override of gh takes effect.

dispatch_spec

is_eval_safe_invocation

Returns true iff this invocation is tagged eval-safe — meaning its stdout is documented shell-init code that can safely be substituted inside eval "$(...)".

load_toml

Build every command definition in source, or the first reason one is invalid.

toml_command_docs

toml_command_names

toml_dispatch

try_fallback_grammar

Apply cmd_name’s TOML-declared [command.fallback] grammar. Returns None if no fallback is declared.

try_matrix_dispatch

Dispatch tokens against cmd_name’s [[command.matrix]] blocks. Looks at tokens[1] (parent) and tokens[2] (action), finds the first matrix whose parents contains the parent and whose actions map contains the action, then validates tokens[2..] against the named policy (and a guard flag if the matrix entry declared one). Returns None if no matrix matched — the handler can then fall through to its remaining special cases or deny.

try_sub_dispatch

Look up cmd_name’s TOML-declared subs (set via [[command.sub]] blocks alongside handler = "...") and dispatch the one whose name matches tokens[1]. Returns None if no sub matched, so the handler can fall through to its fallback grammar (or deny).