Merge branch 'docs/tf-sdk-spec' into 'develop'

# ADR-0027: TF-SDK exposes one generic `CapabilityExecutionAdapter` interface across all domains

**Status:** accepted

**Status:** accepted — the four discovery methods are moved off this interface onto a separate `TopologyDiscoveryAdapter` by [ADR-0055](/decisions/0055-topology-discovery-is-a-separate-adapter-interface.md) (they were "optional" members here, which left an empty result ambiguous). [ADR-0061](/decisions/0061-use-short-execution-action-vocabulary.md) proposes shorter method names; the generic execution interface and `capability_kind` dispatch stand.

**Date:** 2026-07-07

**Affects:** [platform/architecture.md](/platform/architecture.md), [platform/future-architecture.md](/platform/future-architecture.md), [srm/architecture.md](/srm/architecture.md), TF-SDK

discovery methods (`get_zones`, `get_domains`, `get_capabilities`, `get_control_path_bindings`) —

implemented uniformly across compute, network, and future domains (charging, consent,

intelligence, data, business, trust, custom). Capability-specific behavior is selected by a

`capability_kind` string (e.g. `deploy_workload`, `qod_session`, `traffic_influence`) carried in

`capability_kind` string (e.g. `workload`, `qod_session`, `traffic_influence`) carried in

the normalized request, never by a distinct adapter base class per domain. Adapter/executor

resolution itself is governed separately by ADR-0004 (`control_path_ref` via the runtime

ControlPathRegistry); this decision is scoped to the shape of the interface SRM codes against,

---

type: Decision Record

title: "ADR-0055: Topology discovery is a separate TopologyDiscoveryAdapter interface, not optional methods on CapabilityExecutionAdapter"

description: "Discovery moves off the generic execution interface onto its own abstract interface, so an implementation can answer what can be reached without claiming it can execute anything, and vice versa."

tags: [adr, tf-sdk, srm]

timestamp: 2026-09-23T00:00:00Z

status: "accepted"

---

# ADR-0055: Topology discovery is a separate `TopologyDiscoveryAdapter` interface

**Status:** accepted

**Date:** 2026-09-23

**Affects:** [tf-sdk/overview-and-architecture.md](/tf-sdk/overview-and-architecture.md), [tf-sdk/requirements-and-design.md](/tf-sdk/requirements-and-design.md), [srm/architecture.md](/srm/architecture.md), TF-SDK; amends [ADR-0027](/decisions/0027-tfsdk-generic-capability-adapter-interface.md)

## Context

[ADR-0027](/decisions/0027-tfsdk-generic-capability-adapter-interface.md) put

the four discovery methods on the generic interface as **optional** members:

> a single generic interface — `activate_capability` / `update_capability` /

> `deactivate_capability` / `query_capability` / `get_capability_runtime_state`,

> plus optional discovery methods (`get_zones`, `get_domains`,

> `get_capabilities`, `get_control_path_bindings`)

The quotation preserves ADR-0027's original names; [ADR-0061](/decisions/0061-use-short-execution-action-vocabulary.md)

proposes the current public execution names.

Implementing the discovery slice made the cost of "optional" concrete. The two

method groups differ in every property that matters:

- **Who implements them.** Execution is per backend: one adapter per NEF, per

  cluster. Discovery is per *source of the surface*, and the first working

  implementation reads a bootstrap declaration and calls no backend at all. It

  can answer every discovery method and execute nothing.

- **When they are called.** Discovery runs at bootstrap and reconciliation,

  against SRM's planning surface. Execution runs per operation, against a

  target SRM has already resolved.

- **What a missing method means.** An execution adapter that cannot answer

  `get_zones` is not broken — its zones come from elsewhere. But an optional

  method has no honest "not mine" answer: it returns an empty list, which is

  also what "I looked and there are none" returns. A planner cannot tell a

  silent non-implementer from an empty backend.

`can_serve_target` is genuinely optional in the ADR-0040 sense — it has a

specified default (`can_serve`) that is correct when unimplemented. The

discovery methods have no such default, which is what makes them a different

kind of optional.

Options considered:

- **(a) Keep them optional on one interface.** No new type; leaves empty-list

  ambiguity and forces every execution adapter to carry four methods it has no

  source for.

- **(b) A capability-declaration flag** — an adapter states whether it supports

  discovery. Removes the ambiguity, adds a runtime check where a type would

  do, and the flag can disagree with the implementation.

- **(c, chosen) A separate abstract interface.** An implementation declares by

  its type which questions it answers.

## Decision

Topology discovery is `TopologyDiscoveryAdapter`, an abstract interface with

four required methods: `get_zones`, `get_domains`, `get_capabilities`,

`get_control_path_bindings`. Every argument is a filter; a ref matching nothing

yields an empty list, never an error.

Capability execution stays on `CapabilityExecutionAdapter` exactly as ADR-0027

decided, keeping `can_serve_target` as its one genuinely optional member.

A concrete adapter may implement either interface or both. Implementing

`TopologyDiscoveryAdapter` means every discovery method is answered; the empty

list therefore recovers its single meaning.

**The interface speaks platform vocabulary, not backend vocabulary.**

`get_zones` asks what the platform's capability surface looks like within the

adapter's configured scope — it does not ask what objects the backend holds. A

NEF has no zones; a cluster does not know it is a compute domain. This is why

the two interfaces normally have different implementers rather than being two

halves of one adapter: the execution half speaks Helm releases and

`AsSessionWithQoSSubscription`, the discovery half speaks `zone`, `domain` and

`capability`, and only the second is a concept the platform owns.

This amends ADR-0027's "plus optional discovery methods" clause. Everything

else in that record stands: one generic execution interface across every

domain, behavior selected by `capability_kind`, no per-domain base class, and

no change to SRM's adapter-dispatch code when a domain is added.

## Consequences

What becomes easier:

- A bootstrap-declaration topology source is a first-class implementation

  rather than a partial adapter, and the shipped one is exactly that.

- An empty discovery result means one thing.

- An execution adapter carries four fewer methods it has no business answering.

  `zone`, `domain` and `capability` are OOP's normalization vocabulary, not

  backend concepts — a NEF has no zones, and a cluster does not know it is a

  compute domain — so the surface is declared by the platform, not reported by

  the backend an execution adapter is bound to.

What becomes harder:

- Two interfaces to version instead of one — three surfaces once

  [ADR-0058](/decisions/0058-adapters-declare-their-own-executable-surface.md)'s

  `capability_surface` function is counted. A change to the normalized topology

  models now touches a contract that execution adapters may not implement, so

  the compatibility rules in

  [tf-sdk/requirements-and-design.md](/tf-sdk/requirements-and-design.md) §I

  apply to each independently.

- Naming a "discovery interface" invites backend introspection to be bolted

  onto it — list the namespaces, list the configured DNNs. Those are backend

  vocabulary and answer a different question, so they belong behind their own

  surface rather than behind these four methods.

  Reaching `zone`/`domain`/`capability` from such results takes two steps that

  should not be collapsed. Translating backend facts into normalized form is

  TF-SDK's by charter. **Assigning** them a place in the topology — this cluster

  *is* domain X in zone Y — is not a translation at all: no property of a

  cluster makes it a compute domain, and the assignment is an operator decision

  recorded in a declaration. Serving that decision is this interface's job

  ([ADR-0059](/decisions/0059-topology-bootstrap-goes-through-the-discovery-interface.md)); making it is nobody's code's.

Deferred or excluded:

- Whether SRM bootstraps from its own configuration or from these methods at

  launch. Settled separately by [ADR-0059](/decisions/0059-topology-bootstrap-goes-through-the-discovery-interface.md): it calls these methods.

- Adapter construction, which stays with

  [ADR-0041](/decisions/0041-tfsdk-owns-adapter-construction.md): the factory

  returns whatever the adapter kind builds, and the caller uses whichever

  interface it needs.

Revisit trigger:

- A backend requiring discovery and execution to share state — a session, a

  connection pool, a cursor — such that splitting them costs a round trip per

  operation.

---

type: Decision Record

title: "ADR-0056: capability_kind names what a capability is, never what is being done to it"

description: "A capability is a thing, not an action. It is a kind of its own unless it operates on something another capability already created, in which case it is an action carried by the method and by supported_actions."

tags: [adr, tf-sdk, srm]

timestamp: 2026-09-23T00:00:00Z

status: "accepted"

---

# ADR-0056: `capability_kind` names what a capability is, never what is being done to it

**Status:** accepted

**Date:** 2026-09-23

**Affects:** [tf-sdk/overview-and-architecture.md](/tf-sdk/overview-and-architecture.md), [tf-sdk/requirements-and-design.md](/tf-sdk/requirements-and-design.md), [srm/persistence-model.md](/srm/persistence-model.md), [srm/interface-contract.md](/srm/interface-contract.md), SRM, TF-SDK; composes with [ADR-0027](/decisions/0027-tfsdk-generic-capability-adapter-interface.md), [ADR-0004](/decisions/0004-capability-surface-topology.md)

## Context

[ADR-0027](/decisions/0027-tfsdk-generic-capability-adapter-interface.md) made

`capability_kind` the discriminator for adapter behavior without saying what a

kind may name. A working contract revision then named kinds after operations:

`update_workload`, `scale_workload`, `terminate_workload` and

`get_workload_runtime_state` alongside `deploy_workload` — five names for one

thing and the four things you do to it. This revision renames the remaining

kind to `workload` to name the resource rather than its creation operation.

Two failures follow, and neither announces itself.

**A request finds nothing, and "nothing" is ambiguous.** SRM narrows candidates

by `capability.kind` before any other filter

([interface-contract.md §B.5](/srm/interface-contract.md) step 1). Ask for

`scale_workload` when no adapter registered that name and you get zero

candidates, which surfaces as "no available zone/domain" — indistinguishable

from a real capacity problem. The operator debugs topology; the fault is

vocabulary.

**The catalogue starts claiming impossible things.** `scale_workload` as its own

capability says a domain could support scaling without supporting deployment.

No backend is ever in that state.

The shape that avoids both is resource orientation, as in Kubernetes RBAC

(`resources: [deployments]`, `verbs: [get, create, update]`), which has

`kind: Deployment` and no `kind: ScaleDeployment`.

Options: **(a)** a naming convention in guidance, which decides no ambiguous

case; **(b)** a closed enum of kinds, which removes ADR-0027's property that a

new domain needs only a new value and an adapter; **(c, chosen)** a structural

test.

## Decision

**A capability is a thing, not an action.** `kind` names the thing. Verbs live

on the invoked method and on `ControlPathBinding.supported_actions`, where SRM

reads them during planning — and on `ResolvedCapabilityTarget.action` for as

long as that field survives [tf-sdk/overview-and-architecture.md](/tf-sdk/overview-and-architecture.md) §F2.

**The test is one question:**

> *Am I operating on something another capability already created?*

> **Yes** → it is an action on that capability. **No** → it is a kind of its own.

| What you do | Operating on another capability's creation? | Verdict |

|---|---|---|

| Deploy a workload | No — you create it | kind `workload` |

| Change its replicas | Yes — same object | action `update` |

| Terminate it | Yes — same object | action `terminate` |

| Read its state | Yes — same object | action `read_runtime_state` |

| Open a QoD session | No — your own object, your own `external_id` | kind `qod_session` |

| Ask where a device is | No — you touch nobody's realization | kind `location_context` |

The contracted vocabulary is therefore `workload`, `qod_session`,

`traffic_influence`, `location_context`, `device_status` and

`query_available_resources`. `update_workload`, `scale_workload`,

`terminate_workload` and `get_workload_runtime_state` are **not kinds** — each

is an action on `workload`'s realization.

The same question settles what is not contracted yet: a one-off SIM-swap check

and a SIM-swap subscription are **two kinds**, because the subscription creates

an object of its own and the check creates nothing.

**The question decides whether an operation is a separate kind.** The old name

`deploy_workload` passed that structural test, but `workload` names the

capability more clearly and is the sole contracted kind for its lifecycle.

`query_available_resources` also passes the test because it does not operate

on another capability's creation; its operation word is a naming smell, not a

second resource identity. Its name is unchanged by this decision.

Adapters must not advertise one capability under more than one kind.

SRM requirements, topology declarations and TF-SDK adapter surfaces must use

`workload` together. `deploy_workload` is not a compatibility alias; migrate

persisted requirements and capability rows before switching an existing

deployment, and do not mix the old and new values during planning.

## Consequences

What becomes easier:

- The silent non-match is closed at source: there is no second name for a

  request to miss, and `supported_actions` becomes the single place a planner

  reads what can be done.

What becomes harder:

- `capability.kind` carries no CHECK in `srm_db`

  ([persistence-model.md §B.3](/srm/persistence-model.md)) and gains none here,

  so the schema cannot enforce this. Neither can a test, fully: the rule turns on

  capability identity, and two kinds may share a surface legitimately —

  `location_context` and `device_status` do. The contract test in

  [tf-sdk/implementation-and-delivery.md](/tf-sdk/implementation-and-delivery.md) §S.2

  asserts the named non-kinds and leaves the rest a review obligation.

  Whether a lifecycle category on the capability definition could make part of

  this structural instead is [tf-sdk/overview-and-architecture.md](/tf-sdk/overview-and-architecture.md) §F7.

- Answering the question needs an adapter-implementer's knowledge of whether a

  backend object exists with its own lifecycle. Review a new domain's kinds

  before advertising them: a wrong call is costly to undo once bindings exist.

- The rule is silent below the kind. Update and scale both invoke

  `update`, so `supported_actions` cannot advertise them apart.

  Kubernetes answers this with subresources; the equivalent here is widening the

  action vocabulary to intent, left open as

  [tf-sdk/overview-and-architecture.md](/tf-sdk/overview-and-architecture.md) §F2.

Deferred or excluded:

- The mechanics of migrating already persisted kind values; the coordinated

  SRM/TF-SDK rollout must provide them before adopting `workload` in a running

  deployment.

Revisit trigger: an operation that creates a backend object whose lifetime is

not its own, where the question needs a third answer rather than a judgement.

---

type: Decision Record

title: "ADR-0057: an adapter that cannot execute the resolved target fails with a typed error and never substitutes another"

description: "Once SRM has resolved a zone, domain, capability, binding and control path, an adapter executes that target or raises InvalidTargetRef. Choosing a different one would make SRM's inventory a record of something that did not happen."

tags: [adr, tf-sdk, srm]

timestamp: 2026-09-23T00:00:00Z

status: "accepted"

---

# ADR-0057: an adapter never silently substitutes a resolved target

**Status:** accepted

**Date:** 2026-09-23

**Affects:** [tf-sdk/overview-and-architecture.md](/tf-sdk/overview-and-architecture.md), [tf-sdk/requirements-and-design.md](/tf-sdk/requirements-and-design.md), [srm/persistence-model.md](/srm/persistence-model.md), TF-SDK; composes with [ADR-0038](/decisions/0038-device-targeted-control-path-resolution.md), [ADR-0040](/decisions/0040-target-serveability-is-a-tri-state.md), [ADR-0045](/decisions/0045-pin-narrows-candidates-not-probing.md)

## Context

Several accepted records place selection firmly in SRM.

[ADR-0038](/decisions/0038-device-targeted-control-path-resolution.md) keeps the

candidate loop and the choice in SRM.

[ADR-0040](/decisions/0040-target-serveability-is-a-tri-state.md) has the

adapter answer only for its own control path.

[srm/interface-contract.md](/srm/interface-contract.md) §B states it directly:

"Selection is never delegated to TF-SDK."

What none of them state is what an adapter must do when the target it was

handed turns out to be unusable at execution time — the backend moved, the

namespace is gone, the binding points at a cluster this instance cannot reach.

At that moment the adapter frequently *can* see an alternative: a second

cluster in the same domain, another endpoint on the same NEF. Reaching for it

looks like resilience.

It is not. SRM records the resolved binding in

`capability_instance.control_path_binding_id` and reconciles against it. An

adapter that executed elsewhere produces a success whose inventory row points

at a backend that holds nothing, and reconciliation will find drift it cannot

explain — or, worse, find none, because the adapter reports state from the

backend it actually used. The failure is silent, durable, and surfaces as an

unrelated incident weeks later.

The hazard is not hypothetical for this boundary specifically: an adapter

holds exactly the vendor knowledge that makes a plausible alternative easy to

find, and none of the orchestration context that would say whether it is

allowed.

Options considered:

- **(a) Leave it implied.** [interface-contract.md §B.5](/srm/interface-contract.md)

  already says "Selection is never delegated to TF-SDK", and the TF-SDK working

  contract carries it in an anti-pattern list. But both speak about *resolution*

  time; neither states what an adapter must do when the target fails at

  *execution* time, which is when the temptation appears.

- **(b) Allow substitution within the same domain**, on the grounds that the

  domain was what SRM actually chose. Rejected: the binding, not the domain, is

  what is persisted and reconciled against, and a domain may span backends with

  different state.

- **(c, chosen) Fail with a typed error, always.**

## Decision

When an adapter cannot execute through the `control_path_ref` or binding SRM

resolved, it raises a typed `TFSDKError` — `InvalidTargetRef`

(`INVALID_TARGET_REF`, not retryable) for an unresolvable zone, domain,

capability, binding or control-path reference.

It does not switch to another backend, zone, domain, capability or binding, and

it does not widen its own scope to find one. The route check happens **before**

the backend call, so a refusal leaves nothing partially applied — and the check

itself is local. A route check that queried the backend would turn an outage

into `InvalidTargetRef`, which is not retryable, so SRM would permanently fail

an operation it should have retried.

SRM owns what happens next: fallback or failover policy, re-resolution against a

different candidate, or failing the operation — that policy needs orchestration

context the adapter does not have. SRM's existing refusal-mapping rules apply

unchanged: a typed error that reports the control path could not answer is an

operator-side fault, answered `503 .../capability-execution-failed` on the sync

path, never a `4xx` that would assert something about the subscriber

([interface-contract.md §E.2](/srm/interface-contract.md)).

This makes explicit what ADR-0038, ADR-0040 and ADR-0045 assume at resolution

time and extend to execution time.

## Consequences

What becomes easier:

- An inventory row's `control_path_binding_id` is true by construction: either

  the recorded binding executed, or the operation failed.

- Reconciliation compares like with like, because observed state comes from the

  backend the record names.

- Fallback becomes an SRM policy that can be stated, reviewed and changed in

  one place, rather than per-adapter behaviour discovered during an incident.

What becomes harder:

- A deployment whose backends genuinely are interchangeable loses a free

  retry: SRM must model the alternative as a second binding for the same

  capability and let placement choose it.

- An adapter author must resist an obviously available fix. The contract test

  in [tf-sdk/implementation-and-delivery.md](/tf-sdk/implementation-and-delivery.md) §S.2

  asserts that an unresolvable target raises *and performs no backend call*,

  because raising after acting is the version of this mistake that review

  misses.

Deferred or excluded:

- Bounded technical retries against the **same** target are unaffected. A

  connection reset retried against the resolved backend is not substitution.

- Whether SRM re-resolves automatically after `InvalidTargetRef`, and under

  what policy, is SRM's and not settled here.

- Detection of the related fault — a binding whose `control_path_ref` the

  running registry never loaded — is

  [srm/architecture.md](/srm/architecture.md) §F5, still open.

Revisit trigger:

- A capability whose execution semantics make the specific backend genuinely

  irrelevant to the recorded realization, so that substitution could not make

  an inventory row false.