Docs

Shaping

The Shaping panel button (“Apply policy”) enqueues a policy_jobs.kind='apply_policy' row and signals the worker to render + publish. Today this is render managed artifacts + bump epoch — see docs/operate/POLICY.md for the honesty note.

Release B (matrix M53d) adds managed/shaping.toml with the IP warmup ladder and per-domain throttles.

Ladder

`warm_state`	`messages_per_day`	`max_burst`
`cold`	100	1
`warming`	1000	10
`hot`	unlimited (-1)	unlimited (0)

The ladder is rendered into managed/shaping.toml on every apply; the Kumo shaping helper consumes it on the next epoch bump. Source:

# AUTO-GENERATED by MTAIG shaping render — do not hand-edit
# M53d Release B — warmup ladder per warm_state.

[warmup]
cold = "100/day", max_burst=1
warming = "1000/day", max_burst=10
hot = "unlimited", unlimited

[sources]
ip-1 = { source_address = "203.0.113.10", warm_state = "cold", rate = "100/day" }
ip-2 = { source_address = "203.0.113.11", warm_state = "warming", rate = "1000/day" }
ip-3 = { source_address = "203.0.113.12", warm_state = "hot", rate = "unlimited" }

[domain_throttle]
example.com = { max_per_hour = 5000 }

Endpoints

Path	Auth	Purpose
`POST /v1/panel/jobs/apply-policy`	operator+	enqueue apply job (worker drains + epoch bumps)
`GET /v1/panel/jobs`	viewer+	list recent jobs with status + epoch result

Provider split

SHAPING_PROVIDER env flag selects the renderer:

SHAPING_PROVIDER=mock (default) — emits the same shaping.toml in-process; smoke suite runs without a kumod.
SHAPING_PROVIDER=live — same shape; reserved for future divergence.

UX

Jobs panel section shows the queue + the most recent apply results.
Shaping panel section triggers the apply job.
Toast shows the new epoch on success.

Tests

apps/api/src/policy/shaping.test.ts — ladder values, render output, provider dispatch, file write.
apps/api/src/policyRender.shaping.test.ts — renderWorkspacePolicy integration, including the IP-only and IP+domain scenarios.

Last verified: Sat Jul 11 2026 17:00:00 GMT-0700 (Pacific Daylight Time). Cross-link maintained byscripts/check-docs-drift.sh (M54).

← All docs