refactor(intrinsics): remove deprecation shims; rewrite intrinsics_and_adapters.md; write 3 tutorials (Epic #929 Phase 4)

[planetf1]

Parent epic: #929
Design proposal: PR #1080 §16 Phase 4, Part I §5 Q4
Phase: 4
Depends on: #1141, #1142, #1516, #1465, #1466, #1018 (all Phase 2 complete) + at least 1 minor release elapsed (deprecation window)

⏳ DEFERRED — do not start until all Phase 2 issues are merged and at least one minor release has elapsed. The deprecation window is a minimum of one minor release (≈ 4–6 weeks), extendable if user impact warrants. Per PR #1080 Part I §5 Q4 (Resolved by Paul/Jake).

---

Problem

After Phase 1 ships, the old IntrinsicAdapter, EmbeddedIntrinsicAdapter, and CustomIntrinsicAdapter classes exist as deprecation shims with one minor release of warnings. The structural refactor is not complete until these are removed.

Additionally, docs/dev/intrinsics_and_adapters.md describes the old four-class hierarchy — it will be actively misleading once the shims are gone.

Agreed design

Delete the three shim classes. Rewrite (not edit) the dev doc. Write three tutorials.

If the IBM adapter function symbol rename has been confirmed by the time this lands, fold it in here. Otherwise keep separate.

Docs rewrite

docs/dev/intrinsics_and_adapters.md — rewrite (not edit) to document the final Adapter + WeightsBinding + IOContract model. The design proposal §15 explicitly says rewrite.

Three tutorials (§15)

1. "Adding a custom adapter function in 20 lines" — replaces the CustomIntrinsicAdapter monkey-patch story
2. "Handling a breaking schema change without breaking users" — requirement-check v1→v2 worked example; HF revision pinning and AdapterSchemaMismatchError
3. "Reading adapter function telemetry" — short dashboard-building guide referencing mellea.adapter_function.parse_failures, mellea.adapter_function.phase_duration, and the span tree

Scope

• Delete IntrinsicAdapter, EmbeddedIntrinsicAdapter, CustomIntrinsicAdapter from mellea/backends/adapters/__init__.py and definitions
• Update changelog with removal + migration note
• Rewrite docs/dev/intrinsics_and_adapters.md
• Write at least two of the three tutorials; link from docs/docs/advanced/intrinsics.md

Out of scope

Any new functionality. IBM symbol rename (separate issue if not yet confirmed).

Acceptance criteria

• Shim classes removed
• No internal references to old class names remain (grep gate)
• Changelog entry with migration note (import path change)
• docs/dev/intrinsics_and_adapters.md rewritten; describes Adapter + WeightsBinding + IOContract; no references to deleted class names
• At least two of three tutorials written and linked from docs/docs/advanced/intrinsics.md
• All tutorial code examples validated against current source
• markdownlint clean on all touched docs
• Existing tests pass (callers already on new types)

Test plan

• grep for old class names in mellea/ — no hits (gate this in CI)
• grep for old class names in docs/ — no hits in rewritten docs
• Existing test suite passes
• npx markdownlint-cli2 "docs/dev/intrinsics_and_adapters.md"
• Tutorial examples: uv run pytest (mark with # pytest: e2e, hf or appropriate markers)

Breaking changes

• Removal of IntrinsicAdapter, EmbeddedIntrinsicAdapter, CustomIntrinsicAdapter — by design, after the deprecation window. Anyone still importing these breaks. Document in changelog with migration path.

References

• PR docs: design proposal for adapter lifecycle (#929) — review channel, do not merge #1080 §16 Phase 4, §15 (tutorial list), Part I §5 Q4
• All Phase 1 issues — must be merged for callers to be off the old classes
• All Phase 2 issues — must be merged for backend surface on new types