Add deterministic schema stamping, hashing, versioning, and JSON export with CI integration #22
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…n tracking, and comprehensive tests Co-authored-by: JerrettDavis <2610199+JerrettDavis@users.noreply.github.com>
…g feature Co-authored-by: JerrettDavis <2610199+JerrettDavis@users.noreply.github.com>
Co-authored-by: JerrettDavis <2610199+JerrettDavis@users.noreply.github.com>
Copilot
AI
changed the title
[WIP] Add source generator–based config schema stamping and versioning
Add deterministic schema stamping, hashing, and versioning for configuration governance
Dec 31, 2025
JerrettDavis
requested changes
Dec 31, 2025
Owner
JerrettDavis
left a comment
JerrettDavis
left a comment
There was a problem hiding this comment.
We should compute and include the schema json for the solution. We need to also update our release workflow to include schema files for each module with configuration. We need to ensure this project includes the source generators in all the relevant projects.
Co-authored-by: JerrettDavis <2610199+JerrettDavis@users.noreply.github.com>
Contributor
Author
Implemented in commit c40cafe: ✅ Schema JSON Export: Created ✅ Release Workflow: Updated
✅ Source Generator Integration: Added Generators project as analyzer reference to:
✅ Generator Tool: Created
Each release now produces:
All 18 schema tests still passing. |
Copilot
AI
changed the title
Add deterministic schema stamping, hashing, and versioning for configuration governance
Add deterministic schema stamping, hashing, versioning, and JSON export with CI integration
Dec 31, 2025
JerrettDavis
approved these changes
Dec 31, 2025
Code Coverage |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #22 +/- ##
=======================================
Coverage ? 83.13%
=======================================
Files ? 176
Lines ? 6459
Branches ? 1103
=======================================
Hits ? 5370
Misses ? 1089
Partials ? 0
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Implements build-time configuration schema stamping using deterministic FNV-1a hashing to enable automated version tracking, migration detection, and audit trails for enterprise configuration governance. Includes JSON schema export and automated release artifact generation.
Core Infrastructure
Schema Hashing (
SchemaHasher.cs)Version Tracking (
SchemaVersionTracker.cs)Schema Models (
Schema/directory)SchemaMetadata: Hash, version, extension name, generation timestampSchemaDefinition: Normalized schema representation with type/property metadataUnifiedSchemaDocument: Solution-wide schema aggregationSchema Export (
SchemaExporter.cs)Source Generator (
ConfigSchemaGenerator.cs)Config/Configuration/Options/SettingsSchema Generator Tool (
tools/ExperimentFramework.SchemaGenerator/)CI/CD Integration
Release Workflow (
.github/workflows/ci.yml)Configuration.schema.jsonGovernance.Persistence.schema.jsonExperimentFramework.unified.schema.jsonProject Integration
ExperimentFramework.ConfigurationExperimentFramework.Governance.PersistenceUsage
Test Coverage
Documentation
docs/user-guide/schema-stamping.mdsamples/ExperimentFramework.SchemaStampingSample/Design Decisions
Why FNV-1a? Fast (sub-millisecond), deterministic, sufficient for change detection. Not cryptographically secure by design.
Why patch increments? Breaking vs. additive change detection requires semantic analysis, deferred to future enhancement.
Why per-extension? Independent schema evolution without cross-module coordination overhead.
Why JSON export? Machine-readable format for CI/CD validation, external tooling, and audit trails. Enables schema diffing across releases.
Original prompt
This section details on the original issue you should resolve
<issue_title>Feature Request: Source Generator–Based Config Schema Stamping, Hashing, and Versioning</issue_title>
<issue_description>### Summary
Introduce a source generator–driven configuration schema stamping and versioning system that produces a deterministic, fast, non-cryptographic schema hash and embeds it directly into the generated schema metadata. This hash is used to determine when a new schema version is required, enabling reliable detection of breaking or additive changes and driving schema migration workflows.
This feature is foundational for enterprise-grade configuration governance, auditability, and safe rollout of configuration-driven experiments.
Problem Statement
ExperimentFramework increasingly relies on declarative configuration (YAML/JSON DSLs, plugin manifests, provider definitions, selection strategies, etc.). Today:
For enterprise adoption, configuration schemas must be:
Proposed Solution
Implement a C# source generator that performs schema stamping and versioning at build time.
Core Concepts
Per-Extension Schema Ownership
Each extension (core, plugins, providers, backplanes, etc.) defines and maintains its own config schema
Schemas may be authored via:
The generator treats each schema as an independent unit of change
Deterministic Schema Hash
The generator computes a fast, non-cryptographic, deterministic hash of each schema definition
Hash characteristics:
Example candidates:
Hash input should be a normalized representation of the schema structure
Sequential Versioning Based on Hash Changes
Each schema embeds:
SchemaHashSchemaVersion(SemVer-like)A new version is only generated when the computed hash differs from the previous build
Version progression is sequential and monotonic
Hash + version together determine whether a migration is required
Unified Schema Output
Although schemas are defined independently, the generator produces:
This unified schema represents the authoritative configuration contract for the application
Build & Release Artifacts
Each publish or release must emit:
These artifacts are intended for:
Expected Outcomes
Non-Goals
Follow-On Opportunities
This feature unlocks several future capabilities:
Acceptance Criteria
<agent_instructions>All code must fully covered by BDD-style TinyBDD tests, as present in the rest of the library. Aim for DRY, SOLID, clean code. Favor generation over boilerplate. All code must be thoroughly and completely documented in our docs fo...
💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.