Clarify Opskit contract scope and readiness metadata

component.go

@@ -35,6 +35,12 @@ type ComponentInfo struct {
 // Workerkit loops, or application-owned execution paths. Admission control
 // should use ReadinessContributor when a component needs readiness semantics
 // that differ from Status.Ready.
+//
+// Component implementations must be safe for concurrent calls to ComponentInfo,
+// Status, and any optional Opskit capability methods when shared across
+// registries, probes, admin routes, CLIs, tests, or execution layers. Opskit
+// protects registry state, but it does not serialize or synchronize component
+// internals.
 type Component interface {
 	ComponentInfo() ComponentInfo
 	Status(context.Context) Status

doc.go

@@ -11,4 +11,9 @@
 // component registry. It must not execute checks, dispatch commands, schedule
 // work, authorize operations, export telemetry, own lifecycle, or decide
 // application policy.
+//
+// Registry methods are safe for concurrent use, but component implementations
+// may be called concurrently by different callers. Components that expose
+// mutable state through Opskit interfaces are responsible for their own
+// synchronization.
 package opskit

docs/api.md

@@ -140,8 +140,9 @@ dashboards, and admin presentation. Labels must be safe to expose anywhere
 `ComponentInfo` appears. Do not use labels for secrets, user data, request IDs,
 dynamic health details, or high-cardinality values.
 
-Use `Attribute` fields on status, inspection, checks, commands, and future event
-records for runtime or result-specific metadata.
+Use `Attribute` fields on status, inspection, checks, and commands for runtime
+or result-specific metadata. If Opskit later defines a passive event envelope,
+that event shape can use the same safe attribute model.
 
 ### `ComponentFunc`
 

docs/design.md

@@ -154,6 +154,12 @@ descriptive methods when asked, and exposes optional capabilities.
 
 It does not own the lifecycle of the components it stores.
 
+The registry is safe for concurrent use, but it does not make component
+internals safe. Servekit routes, readiness probes, CLIs, tests, and Workerkit
+execution may call component methods at the same time. Component implementations
+that expose mutable state through Opskit interfaces must provide their own
+synchronization.
+
 ## Core Contract
 
 Every registered component implements one required interface:

registry.go

@@ -15,6 +15,10 @@ import (
 // expose registry data through probes or admin endpoints should pass bounded
 // contexts.
 //
+// Registry methods are safe for concurrent use. Component methods may also be
+// called concurrently through registry read paths, so component implementations
+// must protect their own mutable state.
+//
 // The zero value is ready to use.
 type Registry struct {
 	mu            sync.RWMutex