From d45d882437cd1eabf4872d279483ef7484d533c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jos=C3=A9=20Ren=C3=A9=20White=20Enciso?= Date: Sun, 22 Feb 2026 01:30:02 -0600 Subject: [PATCH] feat(stage3): scaffold task-001 baseline - WHY: establish Stage 3 task-001 execution baseline per repo intent - WHAT: add minimal solution/project skeleton and boundary docs - RULE: apply stage3 execution runtime and repository workflow directives --- BuildingBlock.Catalog.slnx | 8 ++++++ .../catalog-contract-boundary.puml | 22 ++++++++++++++++ docs/contracts/catalog-contract-catalog.md | 17 ++++++++++++ docs/contracts/catalog-versioning-policy.md | 12 +++++++++ .../ICatalogCapabilityContract.cs | 8 ++++++ .../BuildingBlock.Catalog.Contracts.csproj | 7 +++++ .../Products/ProductContract.cs | 8 ++++++ .../Tags/TagContract.cs | 9 +++++++ .../Tags/TagOverrideContract.cs | 9 +++++++ .../Tags/TagTypeContract.cs | 8 ++++++ ...ngBlock.Catalog.Contracts.UnitTests.csproj | 20 ++++++++++++++ .../ContractShapeTests.cs | 26 +++++++++++++++++++ 12 files changed, 154 insertions(+) create mode 100644 BuildingBlock.Catalog.slnx create mode 100644 docs/architecture/catalog-contract-boundary.puml create mode 100644 docs/contracts/catalog-contract-catalog.md create mode 100644 docs/contracts/catalog-versioning-policy.md create mode 100644 src/BuildingBlock.Catalog.Contracts/Abstractions/ICatalogCapabilityContract.cs create mode 100644 src/BuildingBlock.Catalog.Contracts/BuildingBlock.Catalog.Contracts.csproj create mode 100644 src/BuildingBlock.Catalog.Contracts/Products/ProductContract.cs create mode 100644 src/BuildingBlock.Catalog.Contracts/Tags/TagContract.cs create mode 100644 src/BuildingBlock.Catalog.Contracts/Tags/TagOverrideContract.cs create mode 100644 src/BuildingBlock.Catalog.Contracts/Tags/TagTypeContract.cs create mode 100644 tests/BuildingBlock.Catalog.Contracts.UnitTests/BuildingBlock.Catalog.Contracts.UnitTests.csproj create mode 100644 tests/BuildingBlock.Catalog.Contracts.UnitTests/ContractShapeTests.cs diff --git a/BuildingBlock.Catalog.slnx b/BuildingBlock.Catalog.slnx new file mode 100644 index 0000000..07cae25 --- /dev/null +++ b/BuildingBlock.Catalog.slnx @@ -0,0 +1,8 @@ + + + + + + + + diff --git a/docs/architecture/catalog-contract-boundary.puml b/docs/architecture/catalog-contract-boundary.puml new file mode 100644 index 0000000..570a67c --- /dev/null +++ b/docs/architecture/catalog-contract-boundary.puml @@ -0,0 +1,22 @@ +@startuml +skinparam packageStyle rectangle + +package "building-block-catalog" { + package "BuildingBlock.Catalog.Contracts" { + class Products + class Tags + interface Abstractions + } +} + +package "furniture-dal" as FurnitureDal +package "furniture-service" as FurnitureService +package "furniture-bff" as FurnitureBff + +FurnitureDal --> Products +FurnitureDal --> Tags +FurnitureService --> Products +FurnitureService --> Tags +FurnitureBff --> Products +FurnitureBff --> Tags +@enduml diff --git a/docs/contracts/catalog-contract-catalog.md b/docs/contracts/catalog-contract-catalog.md new file mode 100644 index 0000000..c62c4d3 --- /dev/null +++ b/docs/contracts/catalog-contract-catalog.md @@ -0,0 +1,17 @@ +# Catalog Contract Catalog + +## Package + +- `BuildingBlock.Catalog.Contracts` + +## Contract Groups + +- `Products`: product contract shapes. +- `Tags`: tag, tag type, and tag override contract shapes. +- `Abstractions`: marker abstraction for contract ownership. + +## Ownership Boundary + +- This repository owns reusable catalog capability contracts. +- Persistence and transport concerns remain outside this package. +- Identity abstractions remain Thalos-owned. diff --git a/docs/contracts/catalog-versioning-policy.md b/docs/contracts/catalog-versioning-policy.md new file mode 100644 index 0000000..c4ba152 --- /dev/null +++ b/docs/contracts/catalog-versioning-policy.md @@ -0,0 +1,12 @@ +# Catalog Versioning Policy + +## Policy + +- Prefer additive contract evolution to keep consumer compatibility. +- Breaking changes require major version increments. +- Deprecated members remain through one deprecation cycle. + +## Compatibility Notes + +- Consumers (`furniture-dal`, `furniture-service`, `furniture-bff`) update explicitly. +- Transport-specific adapters are out of scope for this contracts package. diff --git a/src/BuildingBlock.Catalog.Contracts/Abstractions/ICatalogCapabilityContract.cs b/src/BuildingBlock.Catalog.Contracts/Abstractions/ICatalogCapabilityContract.cs new file mode 100644 index 0000000..9a24416 --- /dev/null +++ b/src/BuildingBlock.Catalog.Contracts/Abstractions/ICatalogCapabilityContract.cs @@ -0,0 +1,8 @@ +namespace BuildingBlock.Catalog.Contracts.Abstractions; + +/// +/// Marker contract for catalog capability request/response definitions. +/// +public interface ICatalogCapabilityContract +{ +} diff --git a/src/BuildingBlock.Catalog.Contracts/BuildingBlock.Catalog.Contracts.csproj b/src/BuildingBlock.Catalog.Contracts/BuildingBlock.Catalog.Contracts.csproj new file mode 100644 index 0000000..6c3a887 --- /dev/null +++ b/src/BuildingBlock.Catalog.Contracts/BuildingBlock.Catalog.Contracts.csproj @@ -0,0 +1,7 @@ + + + net10.0 + enable + enable + + diff --git a/src/BuildingBlock.Catalog.Contracts/Products/ProductContract.cs b/src/BuildingBlock.Catalog.Contracts/Products/ProductContract.cs new file mode 100644 index 0000000..51030af --- /dev/null +++ b/src/BuildingBlock.Catalog.Contracts/Products/ProductContract.cs @@ -0,0 +1,8 @@ +namespace BuildingBlock.Catalog.Contracts.Products; + +/// +/// Catalog product contract. +/// +/// Product identifier in catalog capability scope. +/// Product display name. +public sealed record ProductContract(string ProductId, string DisplayName); diff --git a/src/BuildingBlock.Catalog.Contracts/Tags/TagContract.cs b/src/BuildingBlock.Catalog.Contracts/Tags/TagContract.cs new file mode 100644 index 0000000..5c58050 --- /dev/null +++ b/src/BuildingBlock.Catalog.Contracts/Tags/TagContract.cs @@ -0,0 +1,9 @@ +namespace BuildingBlock.Catalog.Contracts.Tags; + +/// +/// Catalog tag contract. +/// +/// Tag identifier. +/// Tag type identifier. +/// Tag value. +public sealed record TagContract(string TagId, string TagTypeId, string Value); diff --git a/src/BuildingBlock.Catalog.Contracts/Tags/TagOverrideContract.cs b/src/BuildingBlock.Catalog.Contracts/Tags/TagOverrideContract.cs new file mode 100644 index 0000000..f9dcf94 --- /dev/null +++ b/src/BuildingBlock.Catalog.Contracts/Tags/TagOverrideContract.cs @@ -0,0 +1,9 @@ +namespace BuildingBlock.Catalog.Contracts.Tags; + +/// +/// Catalog tag override contract for consumer-specific overrides. +/// +/// Tag identifier. +/// Override target scope. +/// Override value. +public sealed record TagOverrideContract(string TagId, string TargetScope, string OverrideValue); diff --git a/src/BuildingBlock.Catalog.Contracts/Tags/TagTypeContract.cs b/src/BuildingBlock.Catalog.Contracts/Tags/TagTypeContract.cs new file mode 100644 index 0000000..b4e1a06 --- /dev/null +++ b/src/BuildingBlock.Catalog.Contracts/Tags/TagTypeContract.cs @@ -0,0 +1,8 @@ +namespace BuildingBlock.Catalog.Contracts.Tags; + +/// +/// Catalog tag type contract. +/// +/// Tag type identifier. +/// Tag type name. +public sealed record TagTypeContract(string TagTypeId, string Name); diff --git a/tests/BuildingBlock.Catalog.Contracts.UnitTests/BuildingBlock.Catalog.Contracts.UnitTests.csproj b/tests/BuildingBlock.Catalog.Contracts.UnitTests/BuildingBlock.Catalog.Contracts.UnitTests.csproj new file mode 100644 index 0000000..6ee89d2 --- /dev/null +++ b/tests/BuildingBlock.Catalog.Contracts.UnitTests/BuildingBlock.Catalog.Contracts.UnitTests.csproj @@ -0,0 +1,20 @@ + + + net10.0 + enable + enable + false + + + + + + + + + + + + + + diff --git a/tests/BuildingBlock.Catalog.Contracts.UnitTests/ContractShapeTests.cs b/tests/BuildingBlock.Catalog.Contracts.UnitTests/ContractShapeTests.cs new file mode 100644 index 0000000..2013c3b --- /dev/null +++ b/tests/BuildingBlock.Catalog.Contracts.UnitTests/ContractShapeTests.cs @@ -0,0 +1,26 @@ +using BuildingBlock.Catalog.Contracts.Products; +using BuildingBlock.Catalog.Contracts.Tags; + +namespace BuildingBlock.Catalog.Contracts.UnitTests; + +public class ContractShapeTests +{ + [Fact] + public void ProductContract_WhenCreated_StoresRequiredValues() + { + var contract = new ProductContract("PRD-001", "Chair"); + + Assert.Equal("PRD-001", contract.ProductId); + Assert.Equal("Chair", contract.DisplayName); + } + + [Fact] + public void TagOverrideContract_WhenCreated_StoresRequiredValues() + { + var contract = new TagOverrideContract("TAG-001", "furniture", "featured"); + + Assert.Equal("TAG-001", contract.TagId); + Assert.Equal("furniture", contract.TargetScope); + Assert.Equal("featured", contract.OverrideValue); + } +}