docs: ADR-0032 — propose durable/Azure Functions repo extraction

docs/decisions/0032-durable-azure-functions-extraction.md

@@ -0,0 +1,104 @@
+---
+status: Accepted
+contact: cgillum
+date: 2026-07-21
+deciders: cgillum, vrdmr, chetantoshniwal
+consulted: westey-m, eavanvalkenburg, kshyju, larohra, ahmedmuhsin
+informed:
+---
+
+# Extract Durable Task and Azure Functions hosting into a separate repository
+
+## Context and Problem Statement
+
+The Durable Task and Azure Functions hosting integrations (`agent-framework-durabletask`,
+`agent-framework-azurefunctions`, plus their samples, docs, and CI) currently live in the
+`microsoft/agent-framework` (MAF) monorepo. They carry heavyweight specialized dependencies
+(Azure Functions runtime, Durable Task) and need integration-test infrastructure (Functions Core
+Tools, Azurite, a DTS emulator) that the core repo otherwise does not.
+
+This ADR proposes moving them into a dedicated repository
+([`microsoft/agent-framework-durable-extension`](https://github.com/microsoft/agent-framework-durable-extension))
+and considers how to do so without breaking existing users who import them today.
+
+## Decision Drivers
+
+- **Independent lifecycle** — the hosting integrations should be able to version and release on their
+  own cadence, decoupled from core (extends [ADR-0008](0008-python-subpackages.md)'s goal of keeping
+  heavyweight/optional dependencies out of the main package).
+- **Dependency & CI isolation** — keep core lean and its PR pipeline free of heavyweight hosting
+  dependencies and integration-test prerequisites.
+- **Ownership** — a dedicated repo would give the integrations their own issues, CODEOWNERS, and
+  contribution flow.
+- **No breaking change** — existing `from agent_framework.azure import …` code and
+  `pip install agent-framework[all]` should keep working (stable-import-path guarantee, ADR-0008).
+
+## Considered Options
+
+1. **Keep in the MAF repo** (status quo).
+2. **Move out, drop the core shim** — the extension becomes standalone; core stops re-exporting the
+   types and removes them from `[all]`.
+3. **Move out, keep core's backward-compat shim + `[all]`** (proposed) — the code would live in the
+   new repo; core would still lazily re-export the entry-point types from `agent_framework.azure` and
+   keep both packages in the `[all]` extra (resolved from PyPI).
+
+## Decision Outcome
+
+Proposed choice: **Option 3.** Extract the integrations for lifecycle, dependency, and ownership
+isolation, while preserving the existing import surface so the move is invisible to consumers.
+Option 1 forgoes the isolation benefits; Option 2 achieves them but would be a breaking change for
+existing imports and the `[all]` extra.
+
+### Consequences
+
+- Good — would give independent release cadence, a leaner/faster core repo and CI, and clear
+  ownership for the hosting integrations.
+- Good — no user-visible break: existing imports and `agent-framework[all]` would continue to work
+  unchanged.
+- Neutral — type *definitions* would live once in the extension; the core shim would re-export only a
+  curated subset of entry-point types (no metadata duplication). The extension's own samples/docs
+  would import directly from `agent_framework_durabletask` / `agent_framework_azurefunctions`; the
+  shim would be compatibility-only.
+- Neutral — users may still open GitHub issues against the core repo for problems in the extension,
+  but the extension's own repo would be the primary place for issues and PRs. These issues would
+  need to be triaged and transferred to the extension repo.
+- Neutral — **.NET public API boundary.** The extension should prefer the smallest stable public core
+  API over friend-assembly access where the capability is useful to external hosts or tooling. For
+  workflow routing metadata, the agreed first step is to expose a read-only `Workflow.Edges` view plus
+  public `EdgeData.Connection` and `FanOutEdgeData`, while keeping graph construction internal
+  ([#7448](https://github.com/microsoft/agent-framework/issues/7448),
+  [#7459](https://github.com/microsoft/agent-framework/pull/7459)). This reduces internal coupling but
+  adds a public API compatibility commitment. Any remaining internal dependencies would still need to
+  be evaluated individually before retaining `InternalsVisibleTo`.
+- Bad — **Python version coordination.** Core's shim correctness would track the extension's publish
+  cadence. In the other direction, when an extension package adopts a new core API, maintainers would
+  need to choose per feature between raising its minimum core version (simpler, but forces every
+  extension user to upgrade) and conditional imports with fallback behavior (preserves support for
+  older core versions, but adds implementation and testing complexity).
+
+## Validation
+
+Compliance would be validated by:
+
+- Python: `uv lock --check` passing with both packages resolving from PyPI; the shim entry-point
+  symbols importing at runtime after `uv sync --all-extras`; `pyright` staying clean on
+  `agent_framework/azure/__init__.pyi`; and extension tests running against both the minimum supported
+  and current core versions when conditional compatibility behavior is used.
+- .NET: tests from an external assembly confirming that workflow routing metadata is inspectable
+  through the agreed public surface while graph construction remains internal.
+
+A known risk is **publish-lag**: if a symbol is added to core's shim before the extension has
+published a release that exports it, that symbol would not resolve at runtime. The mitigation would
+be to omit any such symbol from the shim until the extension publishes it, then add the entry and
+re-lock.
+
+## More Information
+
+- Related: [ADR-0008](0008-python-subpackages.md) (vendor namespaces + stable import paths),
+  [ADR-0021](0021-provider-leading-clients.md) (lazy-loading gateways),
+  [issue #7448](https://github.com/microsoft/agent-framework/issues/7448) and
+  [PR #7459](https://github.com/microsoft/agent-framework/pull/7459) (.NET workflow routing API).
+- Follow-ups: during extraction, keep the shim's re-exported symbols in sync with each newly
+  published extension release (adding any symbol only once the extension publishes it); document the
+  direct-import convention in the extension's samples READMEs so samples are not switched back to the
+  shim.