feat: auto-liner

[wei3erHase]

AutoLiner

Summary

This PR adds AutoLiner, a utility contract that manages per-collateral SAFEEngine.debtCeiling over time so the live ceiling tracks debt usage while respecting a governance-defined cap, a minimum floor, and a cooldown between updates.

The contract introduces a clean split between:

• AutoLiner local params as the source of truth for the desired configuration
• SAFEEngine.debtCeiling as the live enforced ceiling

Motivation

Before AutoLiner, SAFEEngine.debtCeiling was both:

• the value governance wanted
• the value currently enforced

That makes dynamic headroom management awkward, because lowering the live ceiling also overwrites the long-term intended cap.

With AutoLiner enabled for a collateral:

• AutoLiner.ceilingCap is the desired cap
• SAFEEngine.debtCeiling is the live execution value
• updateCeiling(cType) reconciles the live ceiling with current debt conditions

Behavior

For an initialized and active collateral, the target ceiling is:

min(max(minDebt, currentDebt + gap), ceilingCap)

Special case:

if (gap == type(uint256).max) target = ceilingCap;

updateCeiling(cType):

• reverts if the collateral is not initialized in AutoLiner
• reverts if the collateral is locally deactivated (ceilingCap == 0)
• reverts if the live SAFEEngine.debtCeiling == 0
• no-ops if the current live ceiling already matches the target
• otherwise enforces cooldown before updating the live ceiling in SAFEEngine

Configuration Model

Global params

• cooldown

Per-collateral params

• ceilingCap
• minDebt
• gap

Per-collateral state

• lastUpdateTime

Lifecycle

Onboarding

To enable AutoLiner for a collateral:

1. initialize the collateral in SAFEEngine with a non-zero debtCeiling
2. initialize the collateral in AutoLiner with non-zero:
   • ceilingCap
   • minDebt
   • gap
3. authorize AutoLiner on SAFEEngine
4. call updateCeiling(cType)

Local deactivation

Governance can disable AutoLiner for a collateral by setting:

ceilingCap = 0

This:

• stops future AutoLiner management for that collateral
• does not change the current live SAFEEngine.debtCeiling

If governance wants a different live ceiling after deactivation, it must update SAFEEngine directly.

SAFEEngine disable

Setting:

SAFEEngine.debtCeiling = 0

blocks AutoLiner execution for that collateral, but does not erase local AutoLiner config.

Implementation Notes

• AutoLiner now uses the default ModifiablePerCollateral initialization flow
• the init-only ceilingCap > 0 rule is enforced in _initializeCollateralType
• per-collateral params are loaded once in _getNextDebtCeiling() for a cleaner read path
• there are no global defaults for gap or minDebt; all active collaterals must be explicitly configured

Tests

Added and updated full coverage for:

• constructor validation
• global and per-collateral param changes
• initialization requirements
• local deactivation behavior
• target ceiling computation
• minDebt floor behavior
• ceilingCap clamping
• gap == maxUint behavior
• cooldown enforcement on both increases and decreases
• SAFEEngine-disabled and uninitialized collateral paths
• end-to-end debt draw / repay flows against the full system

Current results

• forge test --match-path test/unit/AutoLiner.t.sol
• forge test --match-path test/e2e/E2EAutoLiner.t.sol

Result:

• 43 unit tests passed
• 2 e2e tests passed

Docs

The PRD was updated at:

• docs/src/detailed/utils/autoliner.md

It now documents:

• the source-of-truth split between AutoLiner and SAFEEngine
• onboarding and deactivation procedures
• the exact target formula
• the distinction between local deactivation and live ceiling shutdown