Commit 2f641366 authored by Dimitrios Gogos's avatar Dimitrios Gogos
Browse files

docs(tf-sdk): point SRM citations at the four-part SRM spec 

Nine citations still named srm/persistence-model.md or
canonical-parameters-schema.md, which 8b88bd07 merged into the SRM
contract, design and delivery files. ADR mentions stay as plain text,
as 8b88bd07 left them.

Co-Authored-By: default avatarClaude Opus 5.5 <noreply@anthropic.com>
parent 52137f84

tf-sdk/implementation-and-delivery.md

+1 −1
Changes for tf-sdk/implementation-and-delivery.md: 1 added line, 1 removed line.
Original line number Diff line number Diff line
@@ -191,7 +191,7 @@ clear-text subscriber identifier. Per call also emit outcome, retry count, typed 
without the split, NFR-TFSDK-01's 5 ms p99 is unverifiable and an incident

cannot tell a slow backend from a slow adapter.

`srm_adapter_call_duration_seconds{control_path_ref}` is the SRM-side metric

(persistence-model.md §E).

([SRM delivery §R](/srm/implementation-and-delivery.md#r-observability)).



Health is the registry's: `/readyz` checks that the ControlPathRegistry loaded

(ADR-0004). An adapter exposes no endpoint.

tf-sdk/overview-and-architecture.md

+3 −3
Changes for tf-sdk/overview-and-architecture.md: 3 added lines, 3 removed lines.
Original line number Diff line number Diff line
@@ -122,7 +122,7 @@ one call: 
|---|---|---|

| `capability.kind`, passed as `capability_kind` | What a capability *is* | `workload`, `qod_session`, `traffic_influence`, `location_context`, `device_status`, `query_available_resources`, … (open; no DB CHECK) |

| `capability_type` | The same thing, under the field name DataBus command payloads use | The same values |

| `capability_instance.kind` | **Lifecycle category only**, never the capability type (persistence-model.md §B.4) | `activation`, `subscription`, `binding`, `reservation`, `lifecycle`, `custom` |

| `capability_instance.kind` | **Lifecycle category only**, never the capability type ([SRM contract §H.3](/srm/interface-contract.md#h3-runtime-tables)) | `activation`, `subscription`, `binding`, `reservation`, `lifecycle`, `custom` |

| **adapter kind** | Which adapter the factory builds, and what `capability_surface` keys on (ADR-0041) | open; declared per control path |

| `runtime_kind`, listed as `supported_runtime_kinds` | The artifact format a deployment carries | `helm`, `k8s_manifest`, `container`, `vm`, `function`, `custom` |

| `zone.kind`, `domain.kind` | Scope, and semantic family | closed; see §K.1 of requirements |
@@ -181,7 +181,7 @@ no external surface, so it neither enforces nor undermines it. 
|---|---|---|

| E1 | SRM passes a fully resolved target — zone, domain, capability, binding, `control_path_ref` already chosen | An adapter would have to choose, which ADR-0057 forbids (High) |

| E2 | Connection config arrives in the control path's config map, secrets as `secret://` refs resolved outside the adapter (ADR-0004) | Credentials land in `srm_db` or adapter-owned storage (High) |

| E3 | SRM validates canonical shapes before invocation (canonical-parameters-schema.md §5) | Per-adapter validation duplicates across every vendor (Medium) |

| E3 | SRM validates canonical shapes before invocation ([SRM contract §G.5](/srm/interface-contract.md#g5-validation-discipline)) | Per-adapter validation duplicates across every vendor (Medium) |

| E4 | One adapter instance serves one control path | Config for the wrong backend reaches a call (Medium) |

| E5 | Backends are reachable from the SRM process at call time | Every operation degrades to a transient-failure retry (Low) |
@@ -237,7 +237,7 @@ answered in a minute. 
Requirements §L.4 carries the interim rule.



**F4. Adapter-side idempotency within one order.** SRM checks `service_order`

by `operation_id` before starting work (persistence-model.md §B.4). This

by `operation_id` before starting work ([SRM design §J.1](/srm/requirements-and-design.md#j1-command-intake-validation-and-idempotency)). This

prevents a completed duplicate order in the ordinary path, but does not by

itself guarantee exactly-once backend effects: a crash after a backend call

and before persisting its result can leave the same order to be recovered.

tf-sdk/requirements-and-design.md

+5 −5
Changes for tf-sdk/requirements-and-design.md: 5 added lines, 5 removed lines.
Original line number Diff line number Diff line
@@ -129,7 +129,7 @@ Every level is optional in a response. 
| `ControlPathBinding` | `ref`, `control_path_ref`, `supported_runtime_kinds`, `supported_actions`, `priority`, `is_default`, `state`, `metadata` | — |



The second column matters. `srm_db` gives `zone` and `domain` no columns beyond

those four plus `metadata` (persistence-model.md §B.3), so a transport field

those four plus `metadata` ([SRM contract §H.2](/srm/interface-contract.md#h2-topology-tables)), so a transport field

listed there is not queryable as a column, and whether SRM persists it at all is

SRM's choice — an adapter must not assume either way.
@@ -154,7 +154,7 @@ review: 
**`unknown` versus the column default.** `srm_db` defaults `state` to `'active'`

on insert while discovery reports `unknown` when the source declares none, so

SRM must write a reported `unknown` explicitly rather than omit the column.

Placement matches only `state='active'` (persistence-model.md §B.2): a surface

Placement matches only `state='active'` ([SRM design §M.3](/srm/requirements-and-design.md#m3-topology-state)): a surface

that silently becomes `active` asserts reachability nobody declared, one that

silently becomes `unknown` is invisible.
@@ -186,7 +186,7 @@ The adapter-visible execution identity: `zone_ref`/`zone_kind`, 


These `*_ref` values are internal (ADR-0028). For an existing realization the

adapter acts via `external_id`, not via a `*_ref` and not via the caller-facing

id (persistence-model.md §B.4).

id ([SRM design §L.3](/srm/requirements-and-design.md#l3-identity-and-addressing)).



### K.4 Request and response models
@@ -231,7 +231,7 @@ onto one method is the observation behind overview §F2. 
### L.2 Query versus lifecycle



Lifecycle methods manage runtime state; query methods return a synchronous

read-only result and create no inventory (persistence-model.md §A.3).

read-only result and create no inventory ([SRM contract §E.2](/srm/interface-contract.md#e2-synchronous-query-endpoints)).



| `capability_kind` | Method |

|---|---|
@@ -252,7 +252,7 @@ kinds**, not two actions on one. 
SRM holds no reservations ([ADR-0002](/decisions/0002-no-stored-capacity.md)).

Capacity truth stays with the backend. Where supported, SRM resolves and queries

`query_available_resources` as a pre-placement check, controlled by the

requirement's `policy.capacity_check` mode (persistence-model.md §B.2). A

requirement's `policy.capacity_check` mode ([SRM design §K.3](/srm/requirements-and-design.md#k3-capacity-policy)). A

positive answer is not a reservation.



### L.4 Error model