adaptive-multi-protocol-gateway/docs/state-contract.md

State Contract

Status: draft | Updated 2026-07-06 | Applies to: managed daemon state

AMPG keeps managed daemon state under gateway.state_dir. The state contract describes which files AMPG owns, which files daemons or adapters write, which paths may contain private keys, and which public address files addresses capture reads.

Command

python3 -m ampg --config gateway.toml state-contract
python3 -m ampg --config gateway.toml state-contract --profile mobile-i2p
python3 -m ampg --config gateway.toml state-contract --protocol tor

Each AMPG_STATE row includes:

• role: state directory, daemon config, identity key, address file, log file, or similar.
• owner: ampg, daemon, or operator.
• required: whether a managed deployment expects the path.
• sensitive: whether the path may contain private identity material.
• path: resolved path under gateway.state_dir unless an adapter documents otherwise.

Address Capture

addresses capture uses the same contract. For each enabled protocol it checks explicit address_file config first, then contract address-file entries in order.

Current managed defaults:

Protocol	Preferred captured address file	Sensitive identity path
Tor	<state_dir>/<site>/tor/hidden-service/hostname	<state_dir>/<site>/tor/hidden-service
I2P	<state_dir>/<site>/i2p/hostname.txt	<state_dir>/<site>/i2p/<keys_file>
Reticulum/IPFS/custom	<state_dir>/<site>/<protocol>/address.txt	adapter-specific

Safety

AMPG must never delete sensitive contract paths without an explicit destructive command. apply --dry-run --write-artifacts prints AMPG_APPLY_STATE_COPY rows that show which reviewed artifacts would be copied into managed state and AMPG_APPLY_SUPERVISOR rows for the services that would be registered or started. The accompanying AMPG_APPLY_PREFLIGHT verdict includes those rows so live apply can refuse mutation when state or supervisor inputs still need review. Live apply should perform reviewed copies, start daemons, capture public addresses, and then run published health checks.