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. Live apply should perform those reviewed copies, start daemons, capture public addresses, and then run published health checks.