Chapter 7.4 — Deprecation as a discipline

🎯 Objective

Show that deprecation is engineering, not a flag in the registry.

🧠 Recommended tool deprecation flow

1. Mark it as deprecated in the registry.
2. Record the reason and the replacement.
3. Measure current usage.
4. Notify consumers and owners.
5. Block new uses via policy/registry.
6. Maintain temporary compatibility for existing consumers.
7. Create regression tests for the replacement.
8. Migrate consumers gradually.
9. Remove after the planned window.
10. Keep an audit of historical usage.

⚠️ Marking metadata as deprecated does not prevent a model from trying to call it. The real block must be in the harness, executor, registry, policy engine or authorization layer.

🧠 Items that require a deprecation plan

• Model.
• Prompt.
• Tool.
• MCP server.
• Output schema.
• Embedding model.
• RAG index.
• Agent.

📊 Consolidated table

Item	Versioning strategy	Deprecation strategy
Prompt	prompt_name@major.minor	Window with the previous version; eval regression
Tool	Semver + registry	Deprecated -> read-only -> removed
MCP server	Semver + capabilities	Dual server for a period
Schema	Semver + contract tests	Accept v1 and v2 temporarily
Model	Controlled alias + fixed version	Shadow eval before the swap
Embeddings	Model version + index	Parallel index and re-embedding
Vector DB	Index version + migration	Dual-write/dual-read
Policy	Versioned bundle	Short window with controlled override
Memory	Schema + data version	Migration or expiration
Agent	agent@major.minor.patch	Deactivation by tenant/phase

🧰 Related practical example (planned)

• EX-LIFE-01 — an example of tool deprecation with an adapter and usage logs.

---