This repository contains the Purview.ValueObjects package: runtime contracts, an incremental source generator,
a diagnostic analyzer, a code fix, tests, samples, and documentation for scalar and complex value objects.
- This file is the repository-wide source of truth for AI agents. More-specific
AGENTS.mdfiles, if added later, take precedence for their subtrees. - Follow explicit user instructions first, then the nearest applicable repository instructions, then established code patterns.
- Operate only in this repository unless the user explicitly expands the scope.
- Never read, copy, log, or commit secrets from excluded files, environment variables, user profiles, local configuration, test output, or provider credentials.
| Path | Purpose |
|---|---|
src/ValueObjects.slnx |
Canonical solution for restore, build, test, and pack |
src/src/ValueObjects |
Runtime contracts ([Scalar], [ValueObject], IValueObject, ScalarJsonConverterFactory) |
src/src/SourceGenerator |
Roslyn incremental generator and analyzer metadata |
src/src/SourceGenerator.Refactorings |
Code fixes (add partial modifier) |
src/tests |
Unit and source-generator tests, plus the multi-framework Entity Framework Core compatibility project |
samples |
Runnable examples |
docs |
User-facing guidance |
Directory.Packages.props |
Centrally managed NuGet versions |
src/Directory.Build.props / src/Directory.Build.targets |
Solution-wide SDK, package, analyzer, and build behavior |
global.json |
Required .NET SDK and Microsoft.Testing.Platform selection |
package.json |
Authoritative repository/package version |
Justfile |
Repository-specific recipes; imports the shared modules in .build/just/ (copied verbatim from the purview-buildsdk-justfile skill) |
skills |
Authored agent skills, installable with the skills CLI (see Agent skills) |
.agents/skills |
Skills installed from other repositories - a local install the CLI owns, gitignored (see Installed skills) |
skills-lock.json |
The record of that install - committed, so a fresh clone restores it |
- Read this file, inspect the working tree, and locate the implementation, tests, documentation, and existing patterns relevant to the task.
- Confirm behavior from code and tests rather than relying on memory or documentation alone.
- Make the smallest coherent change. Preserve public behavior unless the task explicitly changes it.
- Update tests for fixes and behavior changes. Update documentation when public behavior changes.
- Run the narrowest meaningful validation first, then broader validation in proportion to risk.
- Review the diff for unrelated edits, generated noise, compatibility risks, and missing docs or tests.
- Keep value objects immutable, validation deterministic, and equality/hash behavior aligned with every value that defines identity.
- Preserve the
Create(strict) /Hydrate(replay-safe) split.OnNormalize/OnValidatehooks are the supported customization points. - Preserve generated API shape:
Create,Hydrate,TryCreate,Empty, comparison, equality, implicit conversions, enum properties, and JSON converters. - Preserve
ValueObjectDeserializationModesemantics (Hydratedefault,Strictre-validates). - Treat
[Scalar]/[ValueObject]/[ValueObjectDefaults], the interfaces, serialized payload shapes, diagnostic IDs, and generated method signatures as compatibility-sensitive contracts. - Scalar value objects serialize as their underlying primitive value; do not change that without a schema/version strategy.
- The generator targets
netstandard2.0; do not use APIs unavailable to that target. - Follow Roslyn incremental-generator practices: derive output from declared inputs, keep transforms deterministic, avoid mutable global state and filesystem/environment dependencies, and make cancellation effective.
- Generated output must be stable for identical input.
- Diagnostics are public developer experience: preserve IDs and meanings, choose accurate locations and severity,
and update
AnalyzerReleases.*.mdfor newly introduced or changed diagnostics. - Cross-component contracts must go through public members. The artifact that consumers (and Visual Studio)
load is the merged, self-contained assembly the
Purview.SourceGeneratorFrameworkmerge pass produces, and that pass strips everyInternalsVisibleTodeclaration. A component that reads another component's internals (for example a code fix reading a diagnostic descriptor) therefore compiles against the unmerged build output and throwsFieldAccessExceptionat runtime in the IDE. Do not addInternalsVisibleTobetween Roslyn components; expose the shared identity publicly (seeDiagnosticLibrary). - Source-generator changes normally require tests in
src/tests/SourceGenerator.UnitTests.
- The runtime targets
net10.0;net11.0, selected throughPurviewTargetFrameworkSet=Supportedrather than a literal list, so the set moves withPurview.BuildSdk. .NET 8 and .NET 9 were dropped at the .NET 11 GA: they are out of support and the package's minimum is the current LTS. Static abstract interface members (IScalarValueObject) require a net7+ floor, which this preserves. - C# 15 language features are available only on the
net11.0leg, so do not put C# 15 syntax in generated output, which has to compile on both targets.closedwas evaluated forScalarOptionsAttributeand is not applicable: a generic descendant's type parameter must appear in the closed base's specification, andScalarAttribute<TValue>derives from that non-generic base (CS9383). A future fixed hierarchy can use it behind#if NET11_0_OR_GREATER, keeping thenet10.0declaration equivalent. - A C#
uniondeclaration always boxes value-type cases. If the public surface ever needs a union, use the custom non-boxing pattern ([Union]plusHasValueandTryGetValueoverloads) rather than theunionkeyword, and keep the net10.0 polyfill honest. No union is required by the current API: theCreate/Hydrate/TryCreatecontract is deliberately unchanged. - The
.NET 11updated memory-safety rules stay off repo-wide (MemorySafetyRules=0): they are a preview feature, the repository has no unsafe code, and the in-box System.Text.Json source generator emits the previewsafemodifier when they are on, which fails withCS8652unless every consuming project selectsLangVersion=preview. Runtime Async stays on (PurviewRuntimeAsync=true). Do not flip either without reproving the System.Text.Json source-generated contexts onnet11.0. ScalarJsonConverterFactoryuses only reflection overScalarAttribute+Create/Hydrate/constructor; keep it free of event-sourcing dependencies.- Keep the runtime package dependency-free (System.Text.Json is in-box for the supported TFMs).
- Purview.ZodSharp 3 ships
net10.0/net11.0only, the same set as the runtime. A project that references it usesPurviewTargetFrameworkSet=Supported; the runtime package does not reference it.
- The generated, default path for every value object must stay trimming- and Native AOT-safe: no reflection, no
Type.MakeGenericType, no expression-tree compilation, no reflection-basedJsonSerializeroverloads, and no unannotated[RequiresUnreferencedCode]/[RequiresDynamicCode]call sites. - The runtime package sets
IsAotCompatible, so the trim and AOT analyzers run as part of every build. A new trim/AOT warning is a defect, not noise. ScalarJsonConverterFactoryis the only permitted reflection-based component. It must keep its[RequiresUnreferencedCode]/[RequiresDynamicCode]annotations at the opt-in construction point and its suppressions accurate. Do not add reflection anywhere else in the runtime.- Never weaken or delete an AOT/trim annotation or suppression to silence a warning; fix the call site or move the reflection into the annotated factory.
- A feature is not complete until the generated path is confirmed clean under the trim/AOT analyzers. The in-repo
projects never trim-analyze generated code, so the proof is the packed-consumer gate (
just smoke-packed-consumers,scripts/test-packed-consumers.ps1): it publishes a Native AOT console and a Blazor WebAssembly app (trimmed andRunAOTCompilation) from the packed package with-warnaserror, runs them, and leak-scans every output. - Generated JSON converters read and write through
ValueObjectJson(runtime), never through theJsonSerializeroverloads that take onlyJsonSerializerOptions. The generated Entity Framework Core JSON-column converters likewise go throughValueObjectJson.Serialize/Deserializewith the type's converter; only a value object with no usable converter (VO1017) keepsJsonSerializer. - The runtime declares
<SupportedPlatform Include="browser" />, so the platform compatibility analyzer runs for Blazor WebAssembly. A new CA1416 warning is a defect, like a trim/AOT warning.
- This repository uses TUnit on Microsoft.Testing.Platform, selected in
global.json. Do not add xUnit, NUnit, MSTest, or FluentAssertions patterns unless explicitly requested. - TUnit test methods use
[Test], and assertion calls are awaited, for exampleawait Assert.That(actual).IsEqualTo(expected);. - Use
--treenode-filterfor test filtering, notdotnet test --filter. - Unit tests should cover domain logic, contracts, failure behavior, and regressions without external infrastructure.
- Entity Framework Core version differences are covered by
src/tests/ValueObjects.EFCompatibility.IntegrationTests, which targetsnet10.0with EF Core 10 andnet11.0with EF Core 11. Add version-dependent behavior there (and, where a synthetic reference set is enough, toSourceGenerator.IntegrationTests) rather than weakening generated output gated onIsEF8Referenced. - Source-generator tests assert generated code and diagnostics using the existing testing framework
(
Purview.SourceGeneratorFramework.Testing.TUnit).
- Keep
README.md, package READMEs, anddocs/aligned with actual supported behavior. - Examples must compile conceptually against current public APIs. Use placeholders for credentials and environment-specific values.
Prefer the Justfile recipes or their equivalent commands:
./scripts/restore-dotnet-tools.ps1
just restore
just build
just test
just lint-check
just pack
just pipeline-pr
just smoke-packed-consumers
just verify-pack-rules
just smoke-packed-consumers is the packed-consumer gate (Native AOT, Blazor WebAssembly trimmed and AOT in a
headless browser, Blazor Server, net10.0, compiler-host leak scan). It needs the Native AOT toolchain, the
wasm-tools workload and Chrome or Edge; dependency versions not yet on nuget.org restore from
LOCAL_NUGET_FEED_PATH. Run it when generated code, the runtime, packaging or a dependency version changes.
The repository uses the shared Purview.Build pipeline (purview-build.json at the root). just pipeline-pr
restores the local tools with scripts/restore-dotnet-tools.ps1, which installs the pinned Purview.Build from
.config/dotnet-tools.json and retries a cold-cache dotnet tool restore failure (see that script's help).
Local CI-equivalent validation:
dotnet restore src/ValueObjects.slnx
dotnet build src/ValueObjects.slnx --no-restore --configuration Release
dotnet test src/ValueObjects.slnx --no-build --configuration Release --ignore-exit-code 8 -- --treenode-filter "/*/*/*/*[Category=Unit]"
dotnet csharpier check .
Use dotnet csharpier check . for validation and dotnet csharpier format . to fix formatting. Pack when package
assets, public package dependencies, analyzers, build targets, or packaging metadata change.
package.jsonis the authoritative release/package version. Do not manually diverge project versions.- Release is automatic on push to
main: theReleaseworkflow runs the sharedPurview.Buildpipeline withRelease:Mode=NuGet, publishing packages and creating thev<version>GitHub release only when that tag does not already exist. - Never create release tags or publish packages manually unless the user explicitly requests a documented recovery procedure.
Before handing work back:
- Confirm the requested behavior and scope are satisfied.
- Confirm only intended files changed.
- Review public API, serialization, and package-content implications.
- Confirm trimming/Native AOT safety: the generated path adds no reflection and no new
[RequiresUnreferencedCode]/[RequiresDynamicCode]call sites, and theIsAotCompatiblebuild is clean. - Add or update focused tests for code changes.
- Update all affected docs, samples, analyzer metadata, and release notes when applicable.
- Run appropriate build, test, formatting, and pack checks in proportion to risk.
- State exactly what validation ran. If a check was skipped or blocked, give the concrete reason and remaining risk.
Specialist guidance this repository depends on - the Purview engineering playbook, Purview.BuildSdk
configuration, the Purview.SourceGeneratorFramework generator and test APIs, and the ZodSharp integration - is
published by the repositories that own it, and installed here by the skills CLI. The install is local and not
tracked: .agents/skills/** is gitignored, because it is the CLI's copy of someone else's skills - committing it
would publish them as this repository's own, make a skill this repository installs but does not publish findable
through npx skills add purview-dev/value-objects (which discovers the root skills/ folder, not them), and put a
second writer on a path the CLI owns. The CLI's skills-lock.json (source, skill path and content hash of every
entry) is committed, so a fresh clone restores the exact recorded set with just skills-install.
| Skill | Source | Load before |
|---|---|---|
purview-engineering-principles |
purview-dev/engineering-playbook |
setting up, reviewing or rationalising the repository against the Purview conventions |
purview-architecture |
purview-dev/engineering-playbook |
deciding project shape or generating substantial implementation code |
purview-architecture-testing |
purview-dev/engineering-playbook |
adding or changing architecture tests |
purview-testing-conventions |
purview-dev/engineering-playbook |
writing or reviewing tests (TUnit, AAA, naming, builders) |
purview-persistence |
purview-dev/engineering-playbook |
choosing a storage approach, abstracting EF Core, or a GUID primary-key strategy |
purview-telemetry |
purview-dev/engineering-playbook |
adding or reviewing observability |
purview-buildsdk-* (8 skills) |
purview-dev/build-sdk |
build/SDK configuration, project layout and detection, testing, skill installation and skill tests |
purview-sourcegenerator-codewriter |
purview-dev/sourcegenerator-framework |
writing or reviewing emitter code (CodeWriter, scopes) |
purview-sourcegenerator-pipeline |
purview-dev/sourcegenerator-framework |
changing the incremental pipeline or its value-equatable models |
purview-sourcegenerator-diagnostics |
purview-dev/sourcegenerator-framework |
adding or changing a VO1xxx diagnostic or the analyzer |
purview-sourcegenerator-packaging |
purview-dev/sourcegenerator-framework |
changing how the generator is packed or merged |
purview-sourcegenerator-testing |
purview-dev/sourcegenerator-framework |
writing generator, analyzer or code-fix tests (CodeQuery) |
purview-sourcegenerator-tunit-tests |
purview-dev/sourcegenerator-framework |
the TUnit base classes and assertion extensions |
purview-zodsharp-* (6 skills) |
purview-dev/zodsharp |
the [ZodSchema] integration, custom rules, JSON, ASP.NET Core and ZODSGEN diagnostics |
Skills are installed into the universal .agents/skills/ location only. Never install copies into .claude/
or any other per-agent folder, and never add a CLAUDE.md: AGENTS.md is the one instruction file. Both folders
are gitignored, so neither an installed copy nor a per-agent one can be committed. Pass -a universal, which writes
.agents/skills/ and nothing else:
# add or update every skill from a source
npx -y skills@1 add purview-dev/engineering-playbook -s '*' -a universal -y
npx -y skills@1 add purview-dev/build-sdk -s '*' -a universal -y
npx -y skills@1 add purview-dev/sourcegenerator-framework -s '*' -a universal -y
npx -y skills@1 add purview-dev/zodsharp -s '*' -a universal -y
# restore the recorded set from skills-lock.json (a fresh clone has no install)
npx -y skills@1 experimental_installCommit skills-lock.json when it changes, in its own chore commit, and never commit anything under
.agents/skills/ - the ignore rule refuses it, and git add -f is not the way around that: a committed copy would
make a skill this repository installs but does not publish findable through
skills add purview-dev/value-objects. Do not edit anything under .agents/skills/ by hand either: the CLI is its
only writer, and a hand edit no longer matches the lockfile's hash. Purview.BuildSdk's InstallPurviewSkills
target delegates to the same CLI; src/Directory.Build.props sets PurviewSkillsAgents=universal so it is
restricted the same way rather than defaulting to every agent (*).
src/tests/Repository.UnitTests/InstalledSkillTests.cs keeps this honest: .agents/skills/ and /.claude/ are
ignored, every skills-lock.json entry records a source, skill path and hash a clone can restore, an install that is
present holds exactly what the lockfile records, no skill authored in skills/ is copied into .agents/skills/, no
.claude/skills/ copy exists, and there is no CLAUDE.md (at the root or in .github/). The install checks are
skipped when no install is present, because a fresh clone legitimately has none.
Authored skills live in the repository-root skills/ folder. Nothing packs them: Purview.BuildSdk
delivers skills through the skills CLI, which clones the git repository and only discovers a root
skills/ folder.
.agents/skills/ holds the skills installed from other repositories (above) - a gitignored local install. This
repository's own skills are never installed into it — that would leave two copies to drift apart. Read them at their
authored path, skills/<name>/SKILL.md.
Consumers install these skills with:
npx skills add purview-dev/value-objects| Skill | Answers |
|---|---|
skills/purview-value-objects/ |
modelling a value object: scalar, complex, contextual, Create/Hydrate, normalization, typed identifiers |
skills/purview-value-objects-efcore/ |
persisting one with EF Core: converters, complex-type vs JSON, keys, generated key values, migrations |
skills/purview-value-objects-zodsharp/ |
validating one with ZodSharp: [ZodSchema], ZodSchemaMode, OnZodValidate, custom rules, Problem Details |
skills/purview-value-objects-diagnostics/ |
what a VO1xxx means and how to fix it |
Every skill carries the purview-value-objects prefix. Skills install into one flat directory per
agent, shared with every skill a developer has installed from anywhere, so an unprefixed name
collides and the loser is whichever installed second.
src/tests/Repository.UnitTests/SkillTests.cs validates them on every test run, through
Purview.Skills.Testing's rule set (the Agent Skills specification: frontmatter fields, name and
description constraints, bundled links, body size). The [InheritsTests] attribute on that class is
load-bearing — TUnit does not walk base types during discovery, so without it the run is green and
nothing is checked. That project pins net10.0 rather than taking the repository's Supported set,
because it asserts something about the repository rather than about the runtime's reach.
A relative link from one SKILL.md into another skill's folder is a rule violation: only a skill's
own folder is installed with it, so such a link works here and nowhere else. Name the other skill in
prose instead.