feat: keep API contracts connected to modeled behavior

docs/explanation/architecture-resource-roadmap.md

@@ -43,19 +43,19 @@ versions, reference discovery, guarded mutations and branch behavior.
 Runtime evidence comes from the linked executable tests. Component review
 coverage does not establish deployed-browser or production readiness.
 
-## Next resource slice: Specification and API contracts
+## Implemented Specification and API resources
 
 The [Specification/API contract](../reference/specification-and-api-contracts.md)
-defines the next native resource slice. Its schema and runtime implementation
-are pending. The [acceptance fixture](../reference/specification-and-api-acceptance.md)
-records required queries, identity changes, authorization and lifecycle cases;
-it does not claim executable evidence.
-
-Implementation must add the entity/member representations, identified
-associations, authorized admission, exact reference discovery and lifecycle
-handling together. Native manifest, CLI/MCP and Studio support must preserve
-those selections. No source connector or additional format compiler is required
-by this slice.
+defines native retained artifacts, selectable members and identified
+associations. Backend admission and exact reference resolution preserve separate
+request/response mappings and explicit provider usage. Native manifest, CLI/MCP
+and Studio review surfaces preserve these selections. The
+[acceptance reference](../reference/specification-and-api-acceptance.md) links
+the executable fixture and identity, authorization and lifecycle regressions.
+
+Retained opaque formats and selectors do not imply semantic format validation,
+a source connector or another format compiler. Deployment and production-scale
+evidence remain distinct from the linked local tests.
 
 ## Follow-on contracts
 

docs/explanation/wire-compatibility.md

@@ -116,12 +116,19 @@ retired for that stored entity incarnation, and connection references also pin
 the owner's system UID so delete and recreate cannot revive a stale reference.
 
 Contract revision 10 adds Channel and DataStore entity kinds with identified
-associations and reference admission. Both mutation compatibility floors are
-revision 10: clients and servers must understand these owners and preserve
+associations and reference admission. That revision raised both mutation
+compatibility floors to 10: clients and servers must understand these owners and preserve
 their association IDs and pinned observation references. Upgrade the server
 and clients together before authoring these resources. Existing revision-9
 entities retain their stored identities.
 
+The current contract revision is 11, with both mutation compatibility floors
+also at 11. It adds Specification members, exact member/content pins and
+identified API associations. Writers must preserve member IDs as well as
+connection IDs, request/response roles and provider selections. Upgrade clients
+and server before authoring these resources; an exact entity version alone
+does not pin a mutable contract's content or member incarnation.
+
 ## Supported combinations
 
 | Client vs server | Mutations |

docs/reference/channel-and-datastore-contracts.md

@@ -251,8 +251,8 @@ policy enforcement and credential management remain outside Atlas execution.
 
 ## Reference scan budget
 
-Resource reference and impact scans use an independent budget of 5,000 Channel
-and DataStore rows, combined, across the caller's visible namespaces. They
+Resource reference and impact scans use an independent budget of 5,000 Channel,
+DataStore and Specification rows, combined, across the caller's visible namespaces. They
 supplement capped model projections so a missing projection row cannot silently
 remove an inbound architecture dependency. Exceeding this visible scan budget
 returns `RESOURCE_EXHAUSTED`.

docs/reference/connection-identity.md

@@ -23,11 +23,21 @@ The identity fields are:
 | `Swimlane.Transition.Next` | `connection_id` |
 | `UI.Transition` | `connection_id` |
 | `ChannelBinding`, `ReadModelAttachment` | `connection_id` |
+| `SchemaDefinition`, `SchemaBinding`, `MessageReadModelMapping` | `connection_id` |
+| `OperationMessage`, `ChannelOperationBinding` | `connection_id` |
+| `ProviderExposure`, `ApiUsage`, `ContractDependency` | `connection_id` |
 
 The typed edges include slice endpoints and storyboard entry/outcome endpoints.
 Their ownership is the containing entity, not the referenced primitive. A local
 ID does not introduce a new top-level entity or another behavioral primitive.
 
+Specification associations belong to the containing Specification incarnation,
+including associations nested in members. Their endpoint identity includes the
+containing member and declared role or selection. Selectable members have
+separate `ContractMemberId` values and use `ContractMemberRef`; they are not
+connections. The [Specification contract](specification-and-api-contracts.md)
+defines member restoration, immutable content pins and local selection rules.
+
 `ConnectionRef` contains `owner: EntityRef`, `owner_uid` and `id: ConnectionId`.
 The core resolver checks the exact owner kind/version, incarnation and unique
 stored occurrence. Missing, duplicate, malformed or removed selections do not

docs/reference/specification-and-api-acceptance.md

@@ -1,9 +1,9 @@
 # Specification and API acceptance fixture
 
-Status: required acceptance criteria for the
-[Specification/API contract](specification-and-api-contracts.md). The resource
-schema, service implementation, CLI/MCP support and Studio surfaces are pending.
-This fixture describes required outcomes; it is not executable test evidence.
+Status: implemented native resource slice. This reference records acceptance
+criteria for the [Specification/API contract](specification-and-api-contracts.md)
+and links executable evidence below. Local service, store, authoring and
+component tests do not establish production or deployed-browser readiness.
 
 ## Connected fixture
 
@@ -114,14 +114,45 @@ preview. Invalid or forbidden target diagnostics must not expose hidden data.
 | Exceed the visible resource reporting budget during guarded deletion | Reporting may be incomplete under its explicit policy; authorization must still use the complete incoming-reference guard. |
 | Encounter a complete-guard scan error or timeout | Refuse deletion. An incomplete scan is not proof that a target is unreferenced. |
 
-## Implementation evidence required
+## Executable coverage and limits
 
-The implementation PR must replace this pending status with links to executable
-public-service regressions, real store reference-guard tests, native manifest
-round trips, CLI/MCP coverage and Studio review coverage. Assert absence of
-invented provider cross-products and behavioral edges, not just the presence of
-the intended references.
+- The [connected public-service fixture](../../rsworkspace/crates/trogon-atlas-server/tests/specification_fixture.rs)
+  creates the behavioral graph, Channel, native Schema, TypeLibrary and pinned
+  external schema. It checks independent roles and ReadModels, selective provider
+  usage, nested references, absence of invented behavioral edges and exact native
+  manifest export.
+- [Backend regressions](../../rsworkspace/crates/trogon-atlas-server/tests/specification_resources.rs)
+  exercise atomic admission, immutable content, exact member/type pins, branch
+  tombstones, permitted unresolved declarations, selected-library compilation,
+  out-of-projection anchors and authenticated hidden-referrer protection through
+  real gRPC authorization. Existing TypeLibrary compatibility rules still guard
+  breaking edits; forced deletion exercises retained unresolved diagnostics.
+- [Core identity regressions](../../rsworkspace/crates/trogon-atlas-core/tests/specification.rs)
+  cover member/connection identity, no-op manifests, concurrent removal and
+  explicit restoration, cloning, local reference repair, immutable byte pins,
+  selector presence, value limits and retargeting. Malformed or ambiguous
+  persisted member identity sets fail resolution.
+- [Store reference guards](../../rsworkspace/crates/trogon-atlas-store/tests/reference_guards.rs)
+  include nested Specification targets in complete multi-target scans and merged
+  branch tombstone behavior.
+- [CLI round trips](../../rsworkspace/crates/trogon-atlas-cli/tests/export_cli_integration.rs)
+  and [MCP transport round trips](../../rsworkspace/crates/trogon-atlas-mcp/tests/mcp_integration.rs)
+  preserve authoritative member/association IDs, CRLF source bytes, digests and
+  unchanged reapply identity through native authoring surfaces.
+- [Studio review tests](../../tsworkspace/webapps/studio/src/components/SpecificationDetails.test.tsx)
+  cover declared API classification, member/pin display, role separation,
+  provider selection and explicitly unverified opaque selectors. The production
+  [protobuf-loading regression](../../tsworkspace/webapps/studio/server/devops-contract.test.mjs)
+  checks the new kind and retained values through the actual service-package
+  codec. [Validation-context tests](../../tsworkspace/webapps/studio/src/lib/validation-context.test.ts)
+  cover nested typed reference discovery without treating artifact content or
+  arbitrary annotation payloads as reference declarations.
 
-Documentation checks establish link and formatting integrity only. They do not
-establish a generated wire contract, backend enforcement, format compatibility,
-runtime behavior or deployed-browser readiness.
+The protobuf string representation accepts UTF-8 artifact text; binary codecs
+and semantic parsing of retained formats are outside this release. Opaque
+selectors remain unverified. Native TypeLibrary compilation does not establish
+compatibility of those opaque documents.
+
+Documentation checks establish formatting and link integrity. Executable local
+tests establish the behaviors they exercise, not deployed UI operation,
+production scale or a complete proof of every possible concurrency schedule.

docs/reference/specification-and-api-contracts.md

@@ -1,10 +1,9 @@
 # Specification and API contracts
 
-Status: native first-release contract; schema, backend, CLI/MCP and Studio
-implementation is pending. Names below describe the required model, not
-existing protobuf messages or allocated field numbers. The
-[acceptance contract](specification-and-api-acceptance.md) defines the connected
-fixture and failure cases required before implementation can be called complete.
+Status: native schema, backend, CLI/MCP and Studio review support are
+implemented. The [protobuf contract](../../proto/trogonatlas/eventmodel/v1alpha1/specification.proto)
+defines the wire representation. The [acceptance reference](specification-and-api-acceptance.md)
+links executable coverage and distinguishes it from deployment evidence.
 
 ## Behavioral scope
 

proto/trogonatlas/eventmodel/v1alpha1/event_model.proto

@@ -79,6 +79,7 @@ import "trogonatlas/type/v1alpha1/system_meta.proto";    // for SystemMeta
 import "trogonatlas/eventmodel/v1alpha1/reliability.proto";
 import "trogonatlas/eventmodel/v1alpha1/type_library.proto";
 import "trogonatlas/eventmodel/v1alpha1/architecture.proto";
+import "trogonatlas/eventmodel/v1alpha1/specification.proto";
 
 // =============================================================================
 // Event Modeling schema.
@@ -601,6 +602,7 @@ message Entity {
     TypeLibrary type_library = 30;
     Channel channel = 31;
     DataStore data_store = 32;
+    Specification specification = 33;
   }
   trogonatlas.type.v1alpha1.SystemMeta system = 29;
 }

proto/trogonatlas/eventmodel/v1alpha1/identity.proto

@@ -12,6 +12,9 @@ import "trogonatlas/type/v1alpha1/id.proto";
 // EventExample/CommandExample/ReadModelExample, inside TypeRef, etc.).
 // Where a connection between entities can carry data (slice endpoints,
 // storyboard entry/outcome), the schema uses Edge messages instead.
+message SpecificationRef { trogonatlas.type.v1alpha1.Id id = 1; }
+message SchemaRef { trogonatlas.type.v1alpha1.Id id = 1; }
+
 message ChannelRef { trogonatlas.type.v1alpha1.Id id = 1; }
 message DataStoreRef { trogonatlas.type.v1alpha1.Id id = 1; }
 
@@ -88,4 +91,5 @@ enum EntityKind {
   ENTITY_KIND_TYPE_LIBRARY = 29;
   ENTITY_KIND_CHANNEL = 30;
   ENTITY_KIND_DATA_STORE = 31;
+  ENTITY_KIND_SPECIFICATION = 32;
 }