chore(building-block-catalog): merge contract integration branch

docs/architecture/catalog-contract-boundary.puml

@@ -3,16 +3,24 @@ skinparam packageStyle rectangle
 
 package "building-block-catalog" {
   package "BuildingBlock.Catalog.Contracts" {
+    class Conventions
     class Products
     class Tags
+    interface Adapters
+    class Grpc
     interface Abstractions
   }
 }
 
+package "blueprint-platform" {
+  interface IBlueprintPackageContract
+}
+
 package "furniture-dal" as FurnitureDal
 package "furniture-service" as FurnitureService
 package "furniture-bff" as FurnitureBff
 
+Conventions ..> IBlueprintPackageContract
 FurnitureDal --> Products
 FurnitureDal --> Tags
 FurnitureService --> Products

docs/contracts/catalog-contract-catalog.md

@@ -6,12 +6,16 @@
 
 ## Contract Groups
 
-- `Products`: product contract shapes.
-- `Tags`: tag, tag type, and tag override contract shapes.
+- `Conventions`: transport-neutral request/response and envelope conventions.
+- `Products`: transport-neutral product contract shapes.
+- `Tags`: transport-neutral tag, tag type, and tag override contract shapes.
 - `Abstractions`: marker abstraction for contract ownership.
+- `Adapters`: protocol adapter boundaries.
+- `Grpc`: gRPC contract shapes for adapter translation.
 
 ## Ownership Boundary
 
 - This repository owns reusable catalog capability contracts.
-- Persistence and transport concerns remain outside this package.
+- Contract metadata consumes `Core.Blueprint.Common.Contracts` and does not redefine Blueprint contracts.
+- Persistence and transport implementations remain outside this package.
 - Identity abstractions remain Thalos-owned.

docs/contracts/catalog-versioning-policy.md

@@ -6,7 +6,12 @@
 - Breaking changes require major version increments.
 - Deprecated members remain through one deprecation cycle.
 
+## Blueprint Compatibility
+
+- Package descriptor metadata is implemented via `IBlueprintPackageContract` from `Core.Blueprint.Common.Contracts`.
+- Catalog contracts consume Blueprint common contract primitives rather than redefining them.
+
 ## Compatibility Notes
 
 - Consumers (`furniture-dal`, `furniture-service`, `furniture-bff`) update explicitly.
-- Transport-specific adapters are out of scope for this contracts package.
+- Protocol adapters remain edge concerns; catalog contracts remain transport-neutral.

src/BuildingBlock.Catalog.Contracts/Adapters/ICatalogGrpcContractAdapter.cs

@@ -0,0 +1,25 @@
+using BuildingBlock.Catalog.Contracts.Grpc;
+using BuildingBlock.Catalog.Contracts.Products;
+using BuildingBlock.Catalog.Contracts.Responses;
+
+namespace BuildingBlock.Catalog.Contracts.Adapters;
+
+/// <summary>
+/// Defines adapter boundary for catalog gRPC contract translation.
+/// </summary>
+public interface ICatalogGrpcContractAdapter
+{
+    /// <summary>
+    /// Maps transport-neutral product contract into gRPC shape.
+    /// </summary>
+    /// <param name="contract">Transport-neutral product contract.</param>
+    /// <returns>gRPC product contract shape.</returns>
+    CatalogProductGrpcContract ToGrpcProduct(ProductContract contract);
+
+    /// <summary>
+    /// Maps gRPC product contract into transport-neutral response.
+    /// </summary>
+    /// <param name="contract">gRPC product contract shape.</param>
+    /// <returns>Transport-neutral product response contract.</returns>
+    ProductContractResponse FromGrpcProduct(CatalogProductGrpcContract contract);
+}

src/BuildingBlock.Catalog.Contracts/BuildingBlock.Catalog.Contracts.csproj

@@ -4,4 +4,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
   </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\blueprint-platform\src\Core.Blueprint.Common\Core.Blueprint.Common.csproj" />
+  </ItemGroup>
 </Project>

src/BuildingBlock.Catalog.Contracts/Conventions/CatalogContractEnvelope.cs

@@ -0,0 +1,8 @@
+namespace BuildingBlock.Catalog.Contracts.Conventions;
+
+/// <summary>
+/// Defines transport-neutral envelope metadata for catalog contract messages.
+/// </summary>
+/// <param name="ContractVersion">Contract schema version.</param>
+/// <param name="CorrelationId">Correlation identifier for cross-service tracing.</param>
+public sealed record CatalogContractEnvelope(string ContractVersion, string CorrelationId);

src/BuildingBlock.Catalog.Contracts/Conventions/CatalogPackageContract.cs

@@ -0,0 +1,15 @@
+using Core.Blueprint.Common.Contracts;
+
+namespace BuildingBlock.Catalog.Contracts.Conventions;
+
+/// <summary>
+/// Defines package descriptor metadata for catalog contracts package.
+/// </summary>
+public sealed class CatalogPackageContract : IBlueprintPackageContract
+{
+    /// <inheritdoc />
+    public BlueprintPackageDescriptor Descriptor { get; } = new(
+        "BuildingBlock.Catalog.Contracts",
+        PackageVersionPolicy.Minor,
+        ["Core.Blueprint.Common"]);
+}

src/BuildingBlock.Catalog.Contracts/Conventions/ICatalogContractRequest.cs

@@ -0,0 +1,9 @@
+namespace BuildingBlock.Catalog.Contracts.Conventions;
+
+/// <summary>
+/// Defines transport-neutral request contract shape for catalog capability operations.
+/// </summary>
+/// <typeparam name="TResponse">Response contract type.</typeparam>
+public interface ICatalogContractRequest<out TResponse>
+{
+}

src/BuildingBlock.Catalog.Contracts/Grpc/CatalogProductGrpcContract.cs

@@ -0,0 +1,8 @@
+namespace BuildingBlock.Catalog.Contracts.Grpc;
+
+/// <summary>
+/// Defines minimal gRPC contract shape for catalog product adapter translation.
+/// </summary>
+/// <param name="ProductId">Product identifier.</param>
+/// <param name="DisplayName">Product display name.</param>
+public sealed record CatalogProductGrpcContract(string ProductId, string DisplayName);

src/BuildingBlock.Catalog.Contracts/Products/ProductContract.cs

@@ -1,8 +1,15 @@
+using BuildingBlock.Catalog.Contracts.Conventions;
+
 namespace BuildingBlock.Catalog.Contracts.Products;
 
 /// <summary>
-/// Catalog product contract.
+/// Transport-neutral catalog product contract.
 /// </summary>
+/// <param name="Envelope">Contract envelope metadata.</param>
 /// <param name="ProductId">Product identifier in catalog capability scope.</param>
 /// <param name="DisplayName">Product display name.</param>
-public sealed record ProductContract(string ProductId, string DisplayName);
+public sealed record ProductContract(
+    CatalogContractEnvelope Envelope,
+    string ProductId,
+    string DisplayName)
+    : ICatalogContractRequest<Responses.ProductContractResponse>;

src/BuildingBlock.Catalog.Contracts/Responses/ProductContractResponse.cs

@@ -0,0 +1,14 @@
+using BuildingBlock.Catalog.Contracts.Conventions;
+
+namespace BuildingBlock.Catalog.Contracts.Responses;
+
+/// <summary>
+/// Transport-neutral catalog product response contract.
+/// </summary>
+/// <param name="Envelope">Contract envelope metadata.</param>
+/// <param name="ProductId">Product identifier in catalog capability scope.</param>
+/// <param name="DisplayName">Product display name.</param>
+public sealed record ProductContractResponse(
+    CatalogContractEnvelope Envelope,
+    string ProductId,
+    string DisplayName);

src/BuildingBlock.Catalog.Contracts/Tags/TagContract.cs

@@ -1,9 +1,16 @@
+using BuildingBlock.Catalog.Contracts.Conventions;
+
 namespace BuildingBlock.Catalog.Contracts.Tags;
 
 /// <summary>
-/// Catalog tag contract.
+/// Transport-neutral catalog tag contract.
 /// </summary>
+/// <param name="Envelope">Contract envelope metadata.</param>
 /// <param name="TagId">Tag identifier.</param>
 /// <param name="TagTypeId">Tag type identifier.</param>
 /// <param name="Value">Tag value.</param>
-public sealed record TagContract(string TagId, string TagTypeId, string Value);
+public sealed record TagContract(
+    CatalogContractEnvelope Envelope,
+    string TagId,
+    string TagTypeId,
+    string Value);

src/BuildingBlock.Catalog.Contracts/Tags/TagOverrideContract.cs

@@ -1,9 +1,16 @@
+using BuildingBlock.Catalog.Contracts.Conventions;
+
 namespace BuildingBlock.Catalog.Contracts.Tags;
 
 /// <summary>
-/// Catalog tag override contract for consumer-specific overrides.
+/// Transport-neutral catalog tag override contract.
 /// </summary>
+/// <param name="Envelope">Contract envelope metadata.</param>
 /// <param name="TagId">Tag identifier.</param>
 /// <param name="TargetScope">Override target scope.</param>
 /// <param name="OverrideValue">Override value.</param>
-public sealed record TagOverrideContract(string TagId, string TargetScope, string OverrideValue);
+public sealed record TagOverrideContract(
+    CatalogContractEnvelope Envelope,
+    string TagId,
+    string TargetScope,
+    string OverrideValue);

src/BuildingBlock.Catalog.Contracts/Tags/TagTypeContract.cs

@@ -1,8 +1,14 @@
+using BuildingBlock.Catalog.Contracts.Conventions;
+
 namespace BuildingBlock.Catalog.Contracts.Tags;
 
 /// <summary>
-/// Catalog tag type contract.
+/// Transport-neutral catalog tag type contract.
 /// </summary>
+/// <param name="Envelope">Contract envelope metadata.</param>
 /// <param name="TagTypeId">Tag type identifier.</param>
 /// <param name="Name">Tag type name.</param>
-public sealed record TagTypeContract(string TagTypeId, string Name);
+public sealed record TagTypeContract(
+    CatalogContractEnvelope Envelope,
+    string TagTypeId,
+    string Name);

tests/BuildingBlock.Catalog.Contracts.UnitTests/ContractShapeTests.cs

@@ -1,26 +1,57 @@
+using BuildingBlock.Catalog.Contracts.Conventions;
 using BuildingBlock.Catalog.Contracts.Products;
+using BuildingBlock.Catalog.Contracts.Responses;
 using BuildingBlock.Catalog.Contracts.Tags;
+using Core.Blueprint.Common.Contracts;
 
 namespace BuildingBlock.Catalog.Contracts.UnitTests;
 
 public class ContractShapeTests
 {
     [Fact]
-    public void ProductContract_WhenCreated_StoresRequiredValues()
+    public void ProductContract_WhenCreated_StoresTransportNeutralValues()
     {
-        var contract = new ProductContract("PRD-001", "Chair");
+        var envelope = new CatalogContractEnvelope("1.0.0", "corr-123");
+        var contract = new ProductContract(envelope, "PRD-001", "Chair");
 
+        Assert.Equal("1.0.0", contract.Envelope.ContractVersion);
+        Assert.Equal("corr-123", contract.Envelope.CorrelationId);
         Assert.Equal("PRD-001", contract.ProductId);
         Assert.Equal("Chair", contract.DisplayName);
     }
 
     [Fact]
-    public void TagOverrideContract_WhenCreated_StoresRequiredValues()
+    public void TagOverrideContract_WhenCreated_StoresTransportNeutralValues()
     {
-        var contract = new TagOverrideContract("TAG-001", "furniture", "featured");
+        var envelope = new CatalogContractEnvelope("1.0.0", "corr-123");
+        var contract = new TagOverrideContract(envelope, "TAG-001", "furniture", "featured");
 
+        Assert.Equal("1.0.0", contract.Envelope.ContractVersion);
+        Assert.Equal("corr-123", contract.Envelope.CorrelationId);
         Assert.Equal("TAG-001", contract.TagId);
         Assert.Equal("furniture", contract.TargetScope);
         Assert.Equal("featured", contract.OverrideValue);
     }
+
+    [Fact]
+    public void CatalogPackageContract_WhenCreated_UsesBlueprintDescriptorContract()
+    {
+        IBlueprintPackageContract contract = new CatalogPackageContract();
+
+        Assert.Equal("BuildingBlock.Catalog.Contracts", contract.Descriptor.PackageId);
+        Assert.Equal(PackageVersionPolicy.Minor, contract.Descriptor.VersionPolicy);
+        Assert.Contains("Core.Blueprint.Common", contract.Descriptor.DependencyPackageIds);
+    }
+
+    [Fact]
+    public void ProductContractResponse_WhenCreated_StoresTransportNeutralValues()
+    {
+        var envelope = new CatalogContractEnvelope("1.0.0", "corr-456");
+        var response = new ProductContractResponse(envelope, "PRD-001", "Chair");
+
+        Assert.Equal("1.0.0", response.Envelope.ContractVersion);
+        Assert.Equal("corr-456", response.Envelope.CorrelationId);
+        Assert.Equal("PRD-001", response.ProductId);
+        Assert.Equal("Chair", response.DisplayName);
+    }
 }