Coder Legion - Recent posts tagged dotnet

Day 2: An Overview of Definition-Driven Architecture

Sat, 31 Oct 2026 01:00:08 +0000

The previous post, Why ERP Needs a Definition-Driven Framework, ended by promising this one would be about which decisions a framework should make on its users' behalf.

The difference between a framework and a library is usually explained as "you call a library, a framework calls you." That describes the mechanism, not the price. The real price is that once control is inverted, the framework's defaults become your defaults. It decides what data looks like, how a request flows, and where the extension points are. You are free to disagree, and the cost of disagreeing is working around it, which is usually more expensive than not using it at all.

So the question to ask about a framework is not what it can do. The more things it can do, the fewer decisions it has made for you, and the same decision has to be made again for every single form.

This post answers the four questions a definition-driven framework has to settle first. Every other design choice is a consequence of these four answers:

Which layer holds the single source of truth
Which layers are derived from it
What is left to the application
Where this whole approach does not hold

None of the four can be left blank. If the framework does not answer them, the people using it will answer them individually, and their answers will not agree. This module puts the truth in an entity, that one puts it in the table, a third puts it in a form configuration file on the front end. A good part of the three long-standing problems from the previous post grows out of exactly that.

1. Which layer holds the single source of truth

First, a distinction that is easy to blur: a Code-First stack is not short of definitions. The API contract is a definition, the migration script is a definition, so is the database's own metadata. The difference is not whether definitions exist. It is which way the arrow points. Those definitions are dumped out as products. Editing them is meaningless, because the next generation run overwrites them.

So the question is not whether to have definition files. It is where the arrow should point, and there are only three candidates:

Candidate	Paradigm	The catch
Code	Code-First	A type system is wide enough to hold any semantics you can think of. The price is that the only reader of the truth is the compiler, and changing the truth means going through compilation, packaging and deployment
The database	Database-First	Data is the final fact, but the type system is too narrow
Definitions	Definition-Driven	Has to satisfy two conditions at once

Where the database is narrow: it knows that total_amount is a decimal(18,4), but not whether that number is an amount, a quantity or an exchange rate. It does not know whether the value should be rounded, how many digits to show, whether it is required, whether it can be edited, or whether it belongs in the query list. Those semantics have nowhere to live, so they end up somewhere else, and the truth has scattered again.

For definitions to be the truth, two conditions, neither optional

Wide enough to carry semantics beyond structure
They are data, not code, which was the whole subject of the previous post

In this framework, what a single field can declare falls into six categories:

Category	What is declared	Can the database hold it?
Structure	Field name, data type, length, default value	✅
Behavior	Required, read only, visible	Partly
Presentation	Caption, control type, display format, width	❌
Semantics	What kind of number this is, which field carries the currency, which field carries the unit of measure	❌
Relationships	The related form, the field mapping, the display field	❌
Security	Data scope roles, sensitive data classification	❌

Code can hold all six, but only as a stack of attributes, and once they are stacked someone still has to parse them back into data before anything can use them.

The width of that declaration is deliberate. It has to cover the UI, the database and validation in one pass.

A single source of truth is not a claim, it is a dependency direction

Any framework can write "this framework treats X as the single source of truth" in its documentation. To verify it, the dependency direction is enough: the layer holding the truth should depend on nobody, and everybody should depend on it.

The definition layer package has an extremely short reference list. It does not know a database exists, or HTTP, or a UI. In the other direction, data access, business logic, the API contract, the client, and every front end all reference it.

That direction buys two things:

The definition layer can be processed by tools on its own. A definition editor, a generator, a batch checking script: each needs to reference only this one package, without dragging in the entire database and API stack. The claim in the previous post that a thousand definitions can be swept by one script rests on this.
AI benefits too. To make it understand a system, feeding it the definitions is more efficient than having it scan the whole code base, and the conclusions are more reliable. The difference is not file size. It is whether relationships are declared or inferred. Ask which forms an order touches, and reading the definitions means reading relationships that were already declared; reading the code means chasing types, chasing queries, chasing configuration, and then inferring intent, and inference gets things wrong.

The tokens saved are a side effect. As for the business judgments that definitions do not cover, the code still has to be read.

2. Which layers are derived from definitions

The previous post used plain language: the UI, the database, CRUD SQL, validation rules. The precise list comes in two kinds. Most of it is generation:

What is generated	From
The single record form layout	The form structure (master block plus detail block)
The list layout	The list fields the form structure declares
The lookup window layout	The queryable fields the form structure declares
The physical table structure	Every table in the form structure
INSERT / UPDATE / DELETE	The form structure's field set
SELECT, including cross table joins	The form structure's fields and declared relationships
The structure of the data container that crosses layers	The form structure's field set

The other kind is evaluation. Here the framework does not build anything; it takes the rules and expressions declared in the definition and evaluates them. Validation rules are evaluated at save and delete. Computed fields are recalculated the moment the user changes a field they depend on.

When a requirement converges into a new shared behavior, a matching mechanism grows. The query criteria screen for a report, for example, is essentially a set of fields plus editors, and a layout definition can describe it.

Grouped by who consumes it:

Form structure definition
│
├─ Generates
│   ├─ Three layouts: single record / list / lookup window  ->  screens on every front end
│   ├─ Physical table structure  ->  the database
│   ├─ Two kinds of SQL: write / query, including cross table joins  ->  data access
│   └─ The cross layer data container structure  ->  transport
│
└─ Evaluates
    ├─ Validation rules  ->  at save and delete
    └─ Computed fields  ->  the moment a dependent field changes

Generating code, or generating objects

Growing something out of a definition at build time and at run time produces completely different results:

A build time generator produces code. When the definition changes, you regenerate, recompile and redeploy. Not one step of the delivery path from the previous post has been removed, and everything saved earlier is handed back at the final gate.
Run time derivation produces objects in memory. Swap the definition, and the next read is the new one. This is exactly where "no compilation, packaging or deployment between changing a definition and having it take effect" holds.

Two things are paid for it:

Compile time type checking is gone. A misspelled field name is not discovered until run time, and how that debt gets repaid is the subject of Data and Definitions Split Apart, So Forms Need No Types of Their Own.
Cache invalidation goes from an optimization to a problem that must be solved. Definitions will be cached for performance, so the framework needs a notification mechanism that carries a definition changed on one node out to every other node.

3. What is left to the application

Where the framework should stop has two rules, one positive and one negative.

The positive one: any behavior that is standardized and repetitive should converge into a framework mechanism.

This is not merely about writing fewer lines:

There is one way to do each thing, and a fix goes in one place, which saves maintenance
New joiners, consultants and whoever inherits the system learn it once, and understanding one form means understanding all of them, which saves training and is the most commonly underestimated of the two

The symptoms of losing control listed in the previous post are all invoices issued by the absence of a general mechanism, and they are reissued per person, per year.

The negative rule is a single test: would every ERP in the world do this the same way? What is the same belongs to the framework. What differs belongs to the application.

By that line the framework stays out of three areas:

Business judgment: how a status transitions, when shipping must be blocked. Every company differs.
SQL for reports and batch jobs: multi table joins, aggregation, dynamic criteria, performance tuning. Forcing these into definitions only makes them more complicated.
The application shell: the login screen, connection settings, navigation menu, windows and theme.

Staying out is not the same as ignoring. Having handed those three over, the framework picks up two obligations it must get right:

A registry that maps a form identifier to the class you wrote
A few extension points at unambiguous positions, so your logic can hook into the save and delete flows

How well those two are done decides directly whether the application is pleasant or awkward to write, and a later chapter takes them apart.

Handing work over does not reduce complexity either. What definitions can absorb is repetition, not the inherent difficulty of the business. The hard parts have not disappeared. They have been concentrated in one place and given to whoever knows why they are hard.

The third area is clearest in the case study. The Northwind front end has one UI project shared by every front end, and only four hand written screens: the main window, login, connection settings, and the layer that hosts forms. All four are shell. Not one of the eight business forms needs screen code.

You can see where the line is drawn at a glance: the hand written part is precisely the part definitions did not take over.

4. Architectural patterns: three sources, one piece from each

With the first three questions answered, the shape of the framework is fixed. Before the fourth, one description that gets applied to it deserves handling: a hybrid of N-Tier, Clean Architecture and MVVM. "Hybrid" turns into a decorative word very easily, so here is what was taken and what was not.

Source	What was taken	What was not
N-Tier	The layer boundaries and the cross layer data container. One request travels front end, API, business object, repository, data access infrastructure, database, and each layer knows only its neighbor. The most completely taken of the three	Nothing
Clean Architecture	The inward dependency direction from the first section, verifiable by opening the project reference lists	Its requirement on the domain. The pure approach gives every business concept its own strongly typed domain entity, and modeling a thousand tables one at a time is the scale cost from the previous post itself
MVVM	All three roles are present. The model is the cross layer data container, the view is rendered from the layout definition, and the view model is a framework provided `DataObject`	Nothing; the only difference is who writes the view model

That DataObject carries the full job: wrapping the data container, exposing field reads and writes for screen binding, raising notifications for value changes and unsaved state, managing the start and cancellation of detail row editing, and loading, saving and deleting against the back end. The difference is that it is not hand written per form. Its shape comes from the definition. The price is that the screen binds not to a property like order.CustomerId but to a field name.

The cross layer data container is not a custom type either, and a later post is devoted to what that choice costs.

5. Systems this should not be applied to

Three questions before you commit. If any one of them does not survive, seriously consider not applying this.

Q1: Are your screens standardized forms?
Definitions can drive layout only because the layout patterns converged, and what converged here is a block of master fields plus a detail block. Dashboards, charts, drag and drop scheduling and maps are not in the pattern. The framework's answer is not "we support those too." It is that this road does not go through definitions, and you write it yourself.

Q2: Is your request a single document?
The cross layer data container is self describing, and the price is that every response carries the field structure with it. For one order that is worth it. For an event stream at tens of thousands per second it is not.

Q3: How long does your system have to live?
The cost is concentrated up front and the return does not show for three to five years. A system that ships, closes and gets rewritten wholesale three years later pays the cost and never collects.

Not many scenarios satisfy all three at once, and internal enterprise management systems happen to hit every one. Finance, purchasing, inventory, sales, HR, customer relations: the screens are almost all standardized forms, the requests are almost all documents, and once it goes live it lives a long time.

These boundaries are not "the framework has not got there yet." They are places where getting there would make things worse. A framework that can do anything has made no decisions for you, and the decisions are exactly where a framework's value is.

The Northwind case study: how much one definition does

The order in the case study has a single form structure definition, and it states:

One master with one detail
Three cross table relationships on the master, to customer, employee and shipper, each a lookup window that brings one record back
Each detail row picks a product
Amounts are not typed by anyone. They are calculated from quantity, unit price and discount
Three validation rules have to pass before saving

Once that one definition is written, everything in the table from the second section is in place. The tables are created from it, the list and lookup window layouts grow directly out of it, the write and query SQL is assembled by the framework, the data carries its structure with it across layers, and the validation rules are checked at the moment of saving. Not one of those requires additional code.

The same definition is read by four front ends: desktop, browser, iOS and Android, all sharing one UI project.

The value of a framework is not how much it can do. It is whether it can tell which decisions belong to it: the thing that is identical a thousand times over is its, and the thing that differs every time is yours. Draw that line crooked and both sides carry the weight. Draw it too conservatively and you redo the same work a thousand times. Draw it too greedily and you spend more effort working around it.

The next post, The Northwind Case Study: Eight Forms and a Custom Business Object, brings the case study on stage.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-02-framework-decisions

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

How to Build Better Full Stack Applications by Solving Small Problems First

Fri, 30 Oct 2026 05:33:07 +0000

As a full stack developer, I’ve learned that building a web application is not just about writing code or choosing the right framework. It’s about understanding problems, finding practical solutions, and making sure everything works together smoothly.

When working with technologies like .NET, SQL Server, JavaScript, MVC, and Angular, even a small issue can affect the entire application.

The Problem: Small Issues Can Become Big Problems

Imagine building a web application with a login page, a dashboard, and a database. Everything seems fine during development, but after deployment, users start experiencing slow page loading, incorrect data, or unexpected errors.

These problems often happen because different parts of the application are developed without considering how they interact with each other.

For example:

A SQL Server query takes too long to return results.
An API returns more data than the frontend actually needs.
A form submits duplicate requests when a user clicks the button multiple times.
An Angular component displays outdated information.
An MVC controller contains too much business logic, making it difficult to maintain.

Each issue may look small on its own, but together they can affect performance, reliability, and the user experience.

How I Approach These Problems

Instead of trying to fix everything at once, I prefer breaking the problem into smaller pieces.

1. Understand the root cause

Before changing code, I try to understand what is actually going wrong. Checking error messages, reviewing application logs, inspecting network requests, and examining SQL queries can help identify the real issue.

2. Keep the backend organized

In .NET applications, separating responsibilities makes the code easier to understand and maintain. Controllers should handle HTTP requests, while business logic and database operations should be organized appropriately.

This structure also makes testing and future improvements easier.

3. Optimize database operations

SQL Server performance can significantly affect the overall application. Reviewing queries, checking execution plans, adding appropriate indexes, and retrieving only the required data can help reduce unnecessary work.

4. Improve frontend communication

The frontend and backend need to communicate reliably. Using clear API responses, handling loading states, validating user input, and displaying useful error messages can make an application more predictable.

5. Test the complete workflow

A feature might work perfectly in isolation but fail when connected to the database or another component. Testing the entire workflow helps uncover issues that individual unit tests may not catch.

A Practical Example

Consider a product management page where users can search, filter, and update thousands of records.

A simple approach might load every record into the browser and filter the results using JavaScript. This may work with a small dataset, but performance can deteriorate as the data grows.

A better solution is to implement server-side pagination and filtering.

The Angular frontend sends the search term, page number, and page size to a .NET API. The backend validates the request and retrieves only the necessary records from SQL Server.

The API returns the requested data along with pagination information, and the frontend displays the results.

The result is less unnecessary data transfer, better scalability, and a smoother user experience.

This example shows why good full stack development requires thinking beyond a single component.

Where AI Can Help

AI tools can also be useful during development. They can help explain unfamiliar code, suggest SQL optimizations, generate test cases, and identify possible edge cases.

However, generated solutions still need to be reviewed and tested. A suggested query may be logically correct but inefficient for a particular database. A generated API implementation may overlook authorization or input validation.

I see AI as a development assistant rather than a replacement for understanding the application.

Final Thoughts

Building reliable web applications is a continuous process of identifying problems, testing assumptions, and improving solutions.

Whether I’m working with .NET, SQL Server, MVC, JavaScript, or Angular, I believe the goal should be to create software that is easy to understand, maintain, and improve over time.

Good development is not about writing more code. It’s about solving the right problem with a solution that works today and remains useful tomorrow.

I'm interested in learning how other developers approach these challenges.

What do you usually check first when a web application becomes slow: the frontend, the API, or the database?

ERP Architect's Notes: Designing a Definition-Driven Framework · Series Index

Fri, 30 Oct 2026 01:23:04 +0000

The complexity of an ERP is not in how hard any single feature is. It is in how many times the same fact gets restated, multiplied by how many tables, multiplied again by how many customizations.

A thirty-post series written for iThome Ironman 2026, a thirty-day technical writing challenge in Taiwan, published from 2026-08-17 to 2026-09-15. The series is complete.

This series is not about building one form with a framework. It is about designing a framework that can drive hundreds of forms: the single source of truth lives in definitions rather than code, and the database structure, SQL, screens for multiple front ends, validation and computation, multiple languages, multi-tenancy and customization are all derived from the same layer of definitions. The Northwind case study verifies it, but the case study is evidence, not the subject.

It is about mechanisms and trade-offs, not a usage tutorial, and the cost of every design is written as plainly as its benefits.

Chapter One · Why Definition-Driven

What the problem is, where the paradigms diverge, and the case study's first appearance. This chapter sets side by side how many places one field touches under each paradigm.

Day 1 · Why ERP Needs a Definition-Driven Framework
Day 2 · An Overview of Definition-Driven Architecture
Day 3 · The Northwind Case Study: Eight Forms and a Custom Business Object

Chapter Two · Definition Layer

What kinds of definition files there are, why their lifecycles differ, and how one structural description grows into the database structure, CRUD SQL, screens for multiple front ends and business rules.

Day 4 · The Purpose and Classification of Definition Files
Day 5 · How FormSchema Drives SQL
Day 6 · TableSchema and Database Structure Upgrades
Day 7 · FormLayout and Screen Generation for Multiple Front Ends
Day 8 · Declarative Business Rules and Computed Fields

Chapter Three · Data Access and Caching

Without writing DTOs, how data crosses layers; the only two things multiple databases have in common; and how a cache knows its source has changed.

Day 9 · Data and Definitions Split Apart, So Forms Need No Types of Their Own
Day 10 · Multi-Database Support: CRUD and Structure Upgrades
Day 11 · Connections, Transactions and Query Conditions in the Data Access Layer
Day 12 · Cross-Node Invalidation for Definition and Data Caches

Chapter Four · Business Logic and API

Who takes over the part definitions cannot express, where the extension points open, and what a call passes through on its way from the caller to the business object.

Day 13 · Session Management and Lifecycle
Day 14 · Extension Points on a Business Object and When to Override Them
Day 15 · API Contract Layering and the Type Registry
Day 16 · JSON-RPC 2.0: Protocol Choice and the Request Pipeline
Day 17 · The Connector and the Convergence of Client Responsibilities
Day 18 · The Error Contract and User Visible Messages

Chapter Five · Multi-Tenancy and Customization

How one codebase lets every company look different without branching and without recompiling or redeploying. Where the customization work currently stops is stated plainly too.

Day 19 · The Scope of the Customization Layer and Overlay Granularity
Day 20 · Multilingual Customization and Resource Structure
Day 21 · Business Logic Customization and the Four Plugin Stages

Chapter Six · Transport, Security and Audit

What data looks like when it is sent, which protections it passes through, who is allowed to call, and what can be looked up afterward.

Day 22 · The Division of Labor Between XML, JSON and MessagePack
Day 23 · The API Payload Security Pipeline: Order, Protection Levels and Keys
Day 24 · The Three Axes of Permissions: Action, Row and Column
Day 25 · The Audit Trail and the Before and After Values of a Change

Chapter Seven · Data Semantics

Amounts, quantities, dates and times of day: how the meaning of these values is kept from the definition all the way to the database, without any layer quietly changing it along the way.

Day 26 · Numeric Semantics, Multiple Currencies and Units of Measure
Day 27 · The Semantic Boundaries Between Date, DateTime and Time
Day 28 · Time Zone Conversion of DateTime

Chapter Eight · Case Review and The Big Picture

The Northwind application examined item by item: which part definitions, the framework and application code each own. Then a single big picture, and the systems this design does not suit.

Day 29 · Which Part Definitions, the Framework and Application Code Each Own
Day 30 · Three Depths of Development and the Big Picture of the Framework

About the framework behind this series

The mechanisms discussed in the series are all built into an open source framework, bee-library. The case study is a separate repository, bee-northwind-avalonia, which pulls the framework in as a package and holds only the application's own definition files and code.

Update: Bee.NET (bee-library), the framework used when this series was written, has since been taken over by Polhem. The mechanisms carry over, the framework has been substantially refactored, and it is open source under the MIT license. The bee-library and bee-northwind-avalonia repositories are archived; type names and code in the posts follow bee-library as it was at the time of writing.

The framework's only role in this series is to show that these ideas are not just talk on paper. You can skip it entirely, take away only the idea of letting definitions be the source, and build that idea in the languages and tools you know.

📘 Original index on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/ironman-2026

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

Day 1: Why ERP Needs a Definition-Driven Framework

Fri, 30 Oct 2026 01:23:02 +0000

This is the first post in a thirty-part series, ERP Architect's Notes: Designing a Definition-Driven Framework.

What follows is not about building one form with some framework. It is about designing a framework that can drive hundreds of forms: which decisions it should make on your behalf, which ones it should leave to you, and why each mechanism ended up shaped the way it is. Every claim is checked against a working application built on the Northwind sample database, but the case study is evidence, not the subject.

This post covers:

The three layers of ERP development cost: a single change, scale, and delivering customization
The three long-standing problems those layers converge on, and why tooling does not remove them
The point where the paradigms diverge: is the single source of truth code, or definitions?
A controlled experiment: how many places does one field touch under each paradigm?

Who I am

I have spent more than twenty years as a software architect in packaged ERP and HRM products. Packaged software has a very long product cycle, ten or twenty years is normal, and over that span the system is not merely maintained. It has to grow a new face every time the front-end generation turns over. I have been through three of them: desktop, web, and mobile apps. Each time the question was the same. Do we rebuild all several hundred screens?

On a product line like that, an architectural decision does not get rewritten by someone else three years later. You watch it grow for ten years and then keep maintaining it. I stayed in the same role the whole time. I never moved into managing projects or teams and left the code behind, so I did not miss the consequences of a single one of those decisions.

About the framework, and about this series

Some of the ideas I accumulated over those years were built inside real projects. More of them were only ever thought through, because writing all of it alone was never worth the cost. That cost is different now. I used Claude Code to build the ones I never got to, and the result is an open source framework, bee-library. The Northwind case study in later posts runs on it.

The case study itself lives in a separate repository, bee-northwind-avalonia. The framework repository holds the mechanisms; the case study repository holds only the application's own definition files and code, with the framework pulled in as a package. If you want to know what applying this framework actually requires, which definition files you prepare and what code you still have to write, the case study repository shows it more clearly than the framework does.

The framework is still moving. Things that deserve to become mechanisms will keep being folded in, interfaces will change with them, and breaking changes will happen. If you want to reference the packages directly today, that has to be part of your calculation. You can also clone the whole thing and shape it into what you need.

This series is not a manual for it. The framework has exactly one job here: to show that these ideas are not just talk. What the thirty posts discuss is the mechanisms that already exist, what problem each one ran into, how it was solved, what it cost, and why that option rather than another. Implementation details are not walked through line by line. You are entirely free not to use it, and to take only the idea that definitions should be the source, and build it in whatever language and tools you already know.

The whole series rests on one sentence:

The complexity of an ERP is not in how hard any single feature is. It is in how many times the same fact gets restated, multiplied by how many tables, multiplied again by how many customizations.

1. The cost of a single change: how many places one field lands in

The requirement: orders need one more field, Required Date. No calculation, no dependent behavior, no effect on existing logic. The user says this is "just one field, it should be easy," and the user is right.

In a typical Code-First stack, ORM plus web API plus front end, that field lands in thirteen places:

#	Location	What changes
1	Entity class	Add a property
2	Type mapping configuration	Precision, nullability, column name mapping
3	Migration	Generate it, review it, commit it, run it at deployment
4	Query projections	The `Select` for list queries, the column list for reports
5	DTOs	Once for the request, once for the response
6	Mapper configuration	Entity to DTO
7	Validation	Required, range, ordering relative to the order date
8	API contract	The OpenAPI schema, republished to consumers
9	Front-end types	A TypeScript interface or a C# model
10	Front-end form	Control, label, position in the layout
11	Front-end list	Column, width, sorting
12	Localization resources	One per language
13	Test data	Fixtures, seeds, fake data generators

To be fair, several of those can be generated. Migrations come from a tool, OpenAPI is produced by scanning assemblies, front-end types can be generated from OpenAPI. The number you actually hand write is closer to five or six.

But the number you hand write is not the point:

The single fact that "Required Date is a date, it is required, and it shows after the order date" has been restated thirteen times in this stack.

Every restatement is a place where the copies can disagree:

Forgot the DTO, and the value reaches the database but never the front end
Forgot the validation, and users submit it empty
Forgot the list column, and users ask why they cannot see it on the query screen

None of these are hard problems. They are counting problems, and each inconsistency has to be found by a test or by a user report.

A team boundary runs straight through that table

Items 1 through 8 are back end. Items 9 through 13 are front end. If those are two teams, the line cuts through the middle of the table, and every item that crosses it changes character. It stops being editing and becomes coordination.

A request to add one field then grows into this:

A meeting to agree the contract first, then separate scheduling on each side
Sequencing: until the back end ships there is nothing for the front end to consume, so starting early means hand rolling a mock
Release windows: whichever side goes first has to cope with the other not having caught up
And during integration, the discovery that one side read "required" as a front end block and the other read it as a back end block

Not one of those activities is writing the field. What they consume is not effort, it is waiting. The user counts the time from asking to shipping; the engineer counts the time actually spent working. So one side asks why changing a single field takes this long, and the other side does not feel it was slacking. Both are right, because the cost is real, it just does not land on the part where anyone is typing.

2. The cost of scale: multiply that table by a thousand

A full packaged ERP covers finance, purchasing, inventory, manufacturing, sales and HR. Business tables run into the thousands.

The founding premise of an ORM is that objects map to tables, so:

thousands of business tables
  -> thousands of entity classes
  -> plus DTOs, usually more than one: List / Detail / Create / Update
  -> plus mapper configuration
  -> plus repositories

The overwhelming majority of those classes resemble each other. The entity for Supplier and the entity for Shipper differ in field names and field count; structurally they came from the same mold.

This is not an argument that ORMs are bad. An ORM works well in the setting it was designed for. The problem is quantity. When the same pattern has to be copied a few thousand times, the copying itself becomes the dominant cost.

Relationships then multiply that quantity again:

ERP tables are densely connected by nature. An order points at a customer, a salesperson and a shipper; a shipment points at an order, a warehouse and a lot number.
Every one of those relationships needs someone to decide how it is expressed, how it is loaded, and who maintains it. Each decision is reasonable on its own. Spread a few thousand tables out at once and nobody can hold the whole picture.

Take the thirteen slots from the first section and multiply them by a few thousand, and multiply the team boundary along with them. Cross team coordination is not paid once per table, it is paid once per request, and the number of requests is itself proportional to the number of tables.

This is not inconvenience. It is loss of control. Anyone who has maintained a large system recognizes the symptoms:

Nobody dares touch shared classes, because nobody is sure who depends on them
New joiners take a long time before they will go near core modules
The same concept has several different spellings across modules, because different people grew them at different times

3. The cost of customization: how do you deliver it once it is done

The first two layers are about how much work a change takes. The third one is more fundamental, and there is no way around it, because:

An ERP that gets installed and simply used essentially does not exist.

Every rollout comes with customization. This client numbers documents differently, that one calculates cost differently, this department wants two extra fields, that report needs a different grouping. The only variable is the path the customization travels down.

Under Code-First, all thirteen of those places are code, and code has exactly one delivery path:

edit -> compile -> test -> package -> deploy

The same path hurts in three different ways depending on the deployment shape:

Deployment shape	Where customization hurts
A single organization's internal system	The simplest case: schedule one maintenance window. But changing a decimal scale from 2 to 4 still means a full build, test and deploy
Packaged software sold to many customers, each with their own deployment	Only two options. Put it in the trunk behind a switch, and the switches accumulate until nobody dares delete any of them. Or branch, and every branch evolves on its own while every fix in the trunk has to be carried across one at a time
Multi-tenant SaaS on shared assemblies	Tenant A changes one formula, and that means coordinating a maintenance window across all tenants and regression testing every tenant's functionality. If any one tenant breaks, the whole batch rolls back

Three shapes, one conclusion:

The size of the requirement and the cost of delivering it have come completely apart.

Whether the requirement is changing a decimal scale from 2 to 4 or reworking an entire module, it travels the same delivery path and carries the same deployment risk. The result is that small requirements have to be scheduled into the release rhythm too, and the engineering team is forced to treat every change as a significant event.

The root of that decoupling is that customization was expressed as code. The deployment shape only decides how much it hurts. It does not decide whether it hurts.

This layer is what definition-driven design is actually for:

Definitions are data, not code. Changing data requires neither recompilation nor redeployment of assemblies.

4. Three problems that never got solved

The costs from the first three sections converge into these:

Long-standing problem	Symptom
Specifications scattered across three layers	The same field is defined once in the UI, once in the DTO and once in a database migration, and they drift apart easily
Business logic scattered	Different modules are maintained by different engineers, styles diverge, and the same work gets done more than once
Customization that resists standardization	Custom logic cannot flow back into the standard product, and accumulates as technical debt nobody can govern

For the past twenty years the usual answer has been more tooling: code generators, project templates, smarter mappers, more automatic migrations. Those tools genuinely made each restatement cheaper.

What they did not change is the structure in which one fact gets restated thirteen times. They only made restating it faster.

For the third layer, customization cost, tooling helps even less. Generated code is still code, and still has to be compiled and deployed. The reason the third problem has been open for twenty years is right here.

5. Where the paradigms diverge

The problem is not the tooling. It is the paradigm. There is only one question to answer:

Is the single source of truth in this system the code, or the definitions?

Code-First: the entity class is the source. The database is derived from it through migrations, the API contract is derived from it through OpenAPI, and front-end types are derived from that. Definition files are a by-product.
Definition-Driven: a structural description is the source. The UI, the database, the CRUD SQL and the validation rules are all derived from it. Code appears only where a real business judgment has to be made.

The difference is not that a file extension changed from .cs to .xml. It is the nature of the source:

	Code is the source	Definitions are the source
How a thousand tables are represented	A thousand classes	A thousand definition records
What you can bring to bear on them	Compilers, IDEs, refactoring tools	All of that, plus batch scripts, generators, programmatic checks, and AI
The delivery path for a change	Compile, package, deploy	Swap in a different definition
How customization is represented	Branches or switches scattered through source	A layer of data stacked on top of the standard definition
How the front end learns which fields exist	A second, hand-written set of types kept in sync by contract and by people	Fetching the same definition at run time
What a new front-end generation costs	Rebuilding every screen	Writing one new rendering layer
Who can change it	Developers	Developers, consultants, tools, and even users

Two of those rows deserve more than a line:

A thousand classes and a thousand definition records are the same count, but managing them is not the same order of magnitude. A thousand structurally identical XML files can be swept by one script that checks whether every amount field has the right decimal scale. That takes minutes. Doing the equivalent check across a thousand classes is considerably harder.
Generational cost is the one I feel most strongly. Front-end technology turns over roughly every ten years. If screens are written by hand one at a time, a generation change means rebuilding all of them. If screens grow out of definitions, a generation change means writing one new rendering layer. The more forms you have, the wider the gap.

That is also the reason layout deserves to be its own layer of definition. Structure is stable and follows the business; layout is volatile and follows the front-end generation. Once they are separated, what gets rewritten at generation change is the rendering layer, not the thousands of structural definitions.

6. A controlled experiment: how many places for the same field

Back to adding Required Date to orders. I counted it in this series' case study application, and the answer is three definition edits and zero lines of code.

Table structure:

<DbField FieldName="required_date" Caption="Required Date" DbType="Date" />

Form structure:

<FormField FieldName="required_date" Caption="Required Date" DbType="Date" />

Layout:

<LayoutField FieldName="required_date" Caption="Required Date" />

What follows automatically after that: the database column, the form control, the list column, the SQL for insert, update and delete, and transport across layers.

No entity class to keep in sync, because the SQL is assembled from the definition at run time
No DTO or mapper to keep in sync, because the data crossing layers carries its own structural description

The count moves by one in either direction depending on the situation, but the count is not the point. The point is that all three places are definition data.

What happened to the team boundary

The front end no longer declares the field a second time. It asks the back end for that definition at run time and renders accordingly:

front end starts -> asks the back end for the definition -> grows controls, list columns and validation from it

The contract does not have to be negotiated, because the contract is that definition. There is no second copy that could disagree with it.
There is nothing to wait for. The back end changes the definition, and the front end gets the new one the next time it asks.
The coordination, scheduling, sequencing and release windows from the first section mostly just disappear.

What is left is half of the first step: what this field is called in business terms, where it goes, and whether it is required. Somebody was always going to decide that. It is a business judgment, not communication overhead.

The boundary has not vanished, though. It moved.

The front end still needs a rendering layer that knows how to read definitions, and somebody has to build it. The difference is that it gets built once, and after that every form and every field is free.
The team boundary drops from "every field" down to "the rendering layer," and the frequency of conversation changes from "every request" to "whenever framework capability changes."
Anything that genuinely cannot be declared as a definition still has to be discussed. A rule about when a document may not be shipped still needs someone to decide who blocks it, at which layer, and what the message says. No architecture escapes that. What definition-driven design can eliminate is structural restatement, not semantic negotiation.

After the change lands

Two practical problems remain, and the framework has to absorb both:

The physical database does not have that column yet. The framework compares the definition against the actual structure and adds the column, so nobody hand writes a migration. A later post takes this apart.
The system is running, so how does it know the definition changed? The node that edited the definition has to be able to notify the others so their cached copies are invalidated. Cross-Node Invalidation for Definition and Data Caches covers that.

The point is one sentence: between changing a definition and having it take effect there is no compilation, no packaging and no assembly deployment.

7. A map of the thirty posts

Chapter	Theme
One (posts 1 to 3)	Why Definition-Driven
Two (posts 4 to 8)	Definition Layer
Three (posts 9 to 12)	Data Access and Caching
Four (posts 13 to 18)	Business Logic and API
Five (posts 19 to 21)	Multi-Tenancy and Customization
Six (posts 22 to 25)	Transport, Security and Audit
Seven (posts 26 to 28)	Data Semantics
Eight (posts 29 to 30)	Case Review and The Big Picture

Every post is written roughly the same way. First what the problem requires you to weigh, then how the framework is designed and why it was designed that way, and where a case study can verify it, a closing section with the actual Northwind definitions.

Two things to be clear about up front:

The subject is long term cost, not development speed. In the short term Code-First wins almost every time: mature tooling, a complete ecosystem, a fast start. The cost of definition-driven design is concentrated at the beginning, and the return does not show until year three or year five. If your system ships, closes, and gets rewritten wholesale three years later, this series is of limited value to you. It is written for people who know they will be maintaining something for a long time.
Trade-offs and costs will be written as plainly as benefits. The value of a framework is not in what it claims to do. It is in knowing precisely what it does not do, and why. Highly dynamic UIs, dashboards, reports and anything that is not form-shaped will only hurt more if you force them into this model.

A thread to pick up later

The next post, An Overview of Definition-Driven Architecture, is about which decisions a framework should make on its users' behalf. The one after that, The Northwind Case Study: Eight Forms and a Custom Business Object, brings the case study on stage.

The case study builds a complete application out of Northwind: eight forms, master-detail, three cross-table relationships, validation, all of it. Exactly one of those forms needs code written for it. What is inside that one, and which places we deliberately chose not to express as definitions, gets reconciled item by item in Which Part Definitions, the Framework and Application Code Each Own.

The enemy of ERP is not complexity. It is restatement. And the reason tooling cannot eliminate restatement is that restatement is a product of the paradigm. As long as code is the source, the same fact is condemned to be said many times over.

📚 Part of the thirty-post series ERP Architect's Notes: Designing a Definition-Driven Framework

📘 Original article on HackMD, in Traditional Chinese:
👉 https://hackmd.io/@jeff377/day-01-why-definition-driven

📢 You are welcome to republish this, please credit the source.
📬 Follow for more engineering notes:
Facebook ｜ HackMD ｜ GitHub ｜ NuGet

A JSON-RPC Library With No Method Registration: How Does It Decide What Can Be Called?

Thu, 29 Oct 2026 16:15:05 +0000

JSON-RPC 2.0 is a small specification: the client sends {"jsonrpc":"2.0","method":"...","params":{...},"id":1}, and the server answers with a result or an error. REST makes you decide on routes, HTTP verbs and status codes; JSON-RPC only cares about which method to call and with what parameters. For an API where you own both the front end and the back end, that is pleasant to work with.

Polhem.JsonRpc is a set of .NET packages for JSON-RPC 2.0: a transport-independent server, an ASP.NET Core endpoint and a client, built on System.Text.Json alone. It started as the API layer of the Polhem framework. I have now extracted it into standalone packages that do not depend on the framework, so other projects can reference them directly. The source is on GitHub under the MIT license, and the packages are on NuGet.

1️⃣ What it covers

Full JSON-RPC 2.0: ordinary calls, notifications (calls that expect no response), and batches (several calls in one message). An id can be a string, an integer or null.
A transport-independent server: the dispatcher (the part that finds and runs the method) knows nothing about HTTP. The ASP.NET Core endpoint is a separate package.
A client: an HTTP transport, batches, notifications, and interceptors that can rewrite the parameters and result of each call.
Optional payload encryption: the parameters and result go into an envelope that can be compressed and encrypted, and replayed calls can be rejected.

It is split into several NuGet packages, so an application references only what it needs:

Package	Use
Polhem.JsonRpc	Message types, error codes and the transport abstraction shared by the server and the client
Polhem.JsonRpc.Server	The dispatcher: method resolution, parameter binding and filters
Polhem.JsonRpc.AspNetCore	The ASP.NET Core endpoint, `MapJsonRpc`
Polhem.JsonRpc.Client	The client, `JsonRpcConnector`
Polhem.JsonRpc.Payload	Optional: the payload envelope, compression, encryption and replay protection
Polhem.JsonRpc.Payload.Client	Optional: a client that seals the parameters and opens the result of every call
Polhem.JsonRpc.Payload.Server	Optional: opens the envelope and checks for replays on the server

The server references Polhem.JsonRpc.AspNetCore, and the client references only Polhem.JsonRpc.Client. The split keeps a client, whether a desktop app or a mobile app, from pulling in ASP.NET Core and the reflection-based dispatcher.

Native AOT compiles an app to native code at publish time, so nothing can rely on reflection at run time; iOS and WebAssembly both need it. The shared package, the client and the payload packages are marked AOT-compatible, and CI publishes a test program with Native AOT and runs it. The server package finds methods by reflection, so it does not support AOT. The target framework is net10.0.

2️⃣ Getting started

ASP.NET Core server (Minimal API)

The server uses ASP.NET Core Minimal APIs (endpoints mapped directly in Program.cs with MapXxx, without MVC controllers). MapJsonRpc creates a POST endpoint at the given path, and every JSON-RPC call comes in through it. AddControllers is not needed.

Program.cs needs three things: register the object factory, register the JSON-RPC services, and map the endpoint.

using Polhem.JsonRpc.AspNetCore;
using Polhem.JsonRpc.Server;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddSingleton<IJsonRpcObjectFactory, AppObjectFactory>();
builder.Services.AddJsonRpcServer();

var app = builder.Build();
app.MapJsonRpc("/api");
await app.RunAsync();

AddJsonRpcServer takes two sets of options. The first configures the server itself, such as filters, the method policy, the batch limit and serializer options. The second configures the HTTP endpoint, such as the request body size limit and which HTTP status code an error returns. Leave them out and the defaults apply.

builder.Services.AddJsonRpcServer(
    options =>
    {
        options.MaxBatchSize = 50;
        options.Filters.Add(new ApiKeyFilter(apiKey)); // see section 5
    },
    http => http.MaxRequestBodySize = 1024 * 1024);

MapJsonRpc returns the same thing as any other Minimal API endpoint, so authorization, CORS and rate limiting chain on the usual way, for example app.MapJsonRpc("/api").RequireAuthorization();.

The object factory and the class that handles the calls:

public sealed class AppObjectFactory : IJsonRpcObjectFactory
{
    public object? CreateObject(string progId, JsonRpcRequestContext context) => progId switch
    {
        "Calculator" => new Calculator(),
        _ => null,
    };
}

public sealed class Calculator
{
    public AddResponse Add(AddRequest request) => new() { Sum = request.A + request.B };
}

Client

using var http = new HttpClient { BaseAddress = new Uri("http://localhost:5080/api") };
var rpc = new JsonRpcConnector(new HttpTransport(http));

var added = await rpc.InvokeAsync<AddResponse>("Calculator.Add", new AddRequest { A = 1, B = 2 });

That is enough to call Calculator.Add. Note that the server has no AddMethod or similar registration, and Calculator carries no attribute.

3️⃣ With no registration, which methods can be called?

Skipping registration is convenient, but it raises a worry: if one day I add a public method to the class for internal use, can it be called from the network too? When the server receives Calculator.Add, it runs the following checks in order.

Name format. The method name must be ProgId.Action. A ProgId (program identifier) may contain letters, digits, underscores and hyphens; an action letters, digits and underscores; each at most 64 characters. A malformed name is rejected before any lookup.

The application decides the object. The ProgId is passed to your implementation of IJsonRpcObjectFactory.CreateObject, which decides which object to create; returning null means the ProgId is unknown. The packages keep no registry of names, so which ProgIds exist is entirely up to the factory. After the call, the object is passed to ReleaseObjectAsync to be released.

Method signature. An action maps only to a public, non-generic instance method with exactly one parameter. Static methods, property accessors and methods declared by object do not count. If two or more methods with the same name qualify, the server does not pick one; it treats the method as not found.

Naming convention. The parameter type must be named {Action}Request, and the return type (or the result type of Task<T> or ValueTask<T>) must be named {Action}Response. Add takes an AddRequest and returns an AddResponse. This is the default method policy; any public method that does not follow it is treated as nonexistent and answered with -32601 Method not found. An internal helper method that does not follow this naming cannot be called from outside.

The rule can be replaced through JsonRpcServerOptions.MethodPolicy. The Polhem framework replaces it with one that reads its own access-control attribute.

Policy before filters. The method policy runs before every filter, so filters such as authorization checks or decryption only ever see calls that are allowed to run.

Only after these checks are the params bound. params must be a JSON object, deserialized into the request class with camelCase names by default; missing params or an array (positional parameters) are answered with -32602 Invalid params. To return a custom error, a method throws JsonRpcErrorException; any other exception is answered with -32603 Internal error, and the exception message is not sent to the client.

4️⃣ The client

An error returned by the server becomes a JsonRpcErrorException, which carries the error code and message:

try
{
    await rpc.InvokeAsync<DivideResponse>("Calculator.Divide", new DivideRequest { Dividend = 1, Divisor = 0 });
}
catch (JsonRpcErrorException ex)
{
    Console.WriteLine($"Error {ex.Code}: {ex.Message}");
}

Notifications and batches:

// The server runs it but does not respond.
await rpc.NotifyAsync("Calculator.Log", new LogRequest { Message = "Hello" });

// Two calls sent in the same message.
var batch = rpc.CreateBatch();
var first = batch.Add<AddResponse>("Calculator.Add", new AddRequest { A = 2, B = 3 });
var second = batch.Add<AddResponse>("Calculator.Add", new AddRequest { A = 4, B = 5 });
await batch.SendAsync();
Console.WriteLine($"{(await first)!.Sum}, {(await second)!.Sum}");

The request and response classes usually live in a project shared by both sides, which is how the samples in the repo are arranged.

5️⃣ Extension points: filters and interceptors

A server filter wraps every call. It can reject the call, rewrite the parameters before the method runs, and rewrite the result afterwards. For example, checking an API key:

public sealed class ApiKeyFilter(string expectedKey) : IJsonRpcFilter
{
    public ValueTask InvokeAsync(JsonRpcRequestContext context, JsonRpcFilterDelegate next)
    {
        context.Transport.Headers.TryGetValue("X-Api-Key", out var key);
        if (!CryptographicOperations.FixedTimeEquals(
                Encoding.UTF8.GetBytes(key ?? ""), Encoding.UTF8.GetBytes(expectedKey)))
        {
            throw new JsonRpcErrorException(-32001, "Unauthorized");
        }
        return next(context);
    }
}

builder.Services.AddJsonRpcServer(options => options.Filters.Add(new ApiKeyFilter(apiKey)));

To add an HTTP header on the client, use HttpClient's own DelegatingHandler; the packages add no layer of their own. To rewrite the parameters and result of every call, add an IJsonRpcClientInterceptor.

The Polhem framework plugs its sessions and authorization checks into these extension points (the object factory, the method policy and filters). None of that logic is in the packages themselves.

6️⃣ Encrypted payloads

HTTPS protects the connection. If the parameters and results also need end-to-end protection, or a call must not run a second time when it is resent, add the optional payload packages.

They put params and result into an envelope with three formats: plain JSON, encoded (serialized, then gzip-compressed), and encrypted (AES-256-CBC with HMAC-SHA256, encrypt-then-MAC). A frame carrying a timestamp and a sequence number can also be put in front of the content, so the server can reject expired or repeated requests; that is the replay protection.

// Server: the application's policy decides the keys and which methods must be encrypted or replay-protected.
builder.Services.AddJsonRpcServer(options => options.UsePayload(payloadOptions, new MyPayloadPolicy()));

// Client: called the same way as an ordinary call; each call seals its parameters and opens its result.
var rpc = new PayloadConnector(connector, new PayloadProcessor(payloadOptions),
    new PayloadConnectorOptions { KeyProvider = () => sessionKey });
var added = await rpc.InvokeAsync<AddResponse>("Calculator.Add", request);

A few more security details:

The HMAC is compared in constant time and verified before anything is decrypted.
The HMAC covers the method name and the direction, so an intercepted call cannot be redirected to another method, and a response cannot be sent back as a request.
A method can require a minimum format; a request in a lower format is rejected before any key is asked for.

How keys are negotiated (exchanged after sign-in, provisioned in advance, and so on) is outside the packages and left to the application.

7️⃣ How it differs from common libraries

There are quite a few JSON-RPC libraries for .NET; here are two common ones for comparison. The version in each column header is the latest stable release on NuGet as of October 2026, and the details come from that release's documentation and NuGet dependency list. Later releases may differ.

	StreamJsonRpc 2.25.29	Tochka.JsonRpc 7.4.1	Polhem.JsonRpc 1.2.0
JSON library	Newtonsoft.Json by default, switchable to System.Text.Json; the package still depends on Newtonsoft.Json and MessagePack	System.Text.Json	System.Text.Json, with no other dependencies
Transport model	Full duplex over a Stream, WebSocket or Pipe	HTTP on ASP.NET Core MVC	HTTP request and response on ASP.NET Core Minimal APIs
Client	Yes, with proxies generated from interfaces	Yes	Yes
How methods are registered	`AddLocalRpcTarget` adds a target object whose public methods become callable	Controllers that inherit `JsonRpcControllerBase`; each action is a method	No registration; found by `ProgId.Action` and the naming convention
Native AOT	Partially supported, within the limits its documentation lists	Tied to MVC, not supported	The shared package, the client and the payload packages support it; the server does not
Good fit	Two-way communication, such as Visual Studio extensions or LSP	You already use MVC and want to keep writing controllers	An API where you own both ends, possibly with desktop or mobile clients

StreamJsonRpc is the most complete, with cancellation, progress reporting and server-to-client calls, but it is designed for streams and full duplex; turning it into an HTTP request/response API means building the endpoint yourself.

Tochka.JsonRpc is the closest in scope to Polhem.JsonRpc. It builds on MVC controllers, so MVC filters and model binding work as they are, at the cost of sharing MVC's lack of AOT support.

Polhem.JsonRpc goes in a different direction: it trades a fixed call shape for "no registration" and "an API that can evolve", as the next section explains.

8️⃣ Design trade-offs

The fixed call shape is there so the API can evolve. The ProgId.Action name, one request class and one response class are a deliberate restriction. When a member is added to a request or response class, a member an older front end does not send binds to its default on the server, and a result member an older front end does not know is simply skipped when read. Old and new front ends call the same method, with no v1 and v2 endpoints to maintain. Positional parameters cannot do this: add, remove or reorder one parameter and every caller has to change.

Defaults follow the specification. The internal error code is -32603, a response carries only jsonrpc, result or error, and id, and id is always written, as null when it cannot be determined. The Polhem framework's original response format differed from the specification in places; when the packages were extracted, it was the framework that changed to follow the specification, not the packages that bent to the old format.

The reasoning behind each decision is recorded as ADRs (Architecture Decision Records) in the repo's maintainers/adr/, and the security design is summarized in docs/security.md.

✅ Wrapping up

Install the server and client packages:

dotnet add package Polhem.JsonRpc.AspNetCore
dotnet add package Polhem.JsonRpc.Client

The repo includes samples: an ASP.NET Core Minimal API server, a console client (ordinary calls, error handling, notifications and batches), and a server and client using encrypted payloads.

These packages do convention-based JSON-RPC, not general-purpose JSON-RPC. Protocols whose method names and parameters are defined by someone else, such as the Language Server Protocol, MCP or an Ethereum node's API (names like textDocument/didOpen and eth_call with positional parameters), cannot be implemented with them; StreamJsonRpc or the MCP C# SDK fit those better. Nor do they offer a full-duplex connection where the server calls the client: one call is one HTTP request and its response.

If you own both ends of your API, want JSON-RPC that relies on System.Text.Json alone, or have clients that run as desktop or mobile apps, give it a try. Feedback, issues and pull requests are welcome.

A Stopwatch Needs an Isolated Lane

Wed, 28 Oct 2026 10:49:36 +0000

Timing tests look wonderfully objective. Start a stopwatch, call the component, stop the watch, and compare the result with a budget.

The number is precise. The experiment may not be.

That distinction matters in continuous integration, where many tests share CPU time, thread pools, network stacks, containers, and database capacity. A wall-clock assertion can fail because the product became slower. It can also fail because the test runner became busier. If we cannot distinguish those two explanations, the test is producing urgency without producing useful evidence.

The contract was reasonable

Consider a service with separate liveness and readiness checks. Liveness says the process is still running. Readiness says the instance can safely accept work.

One integration test deliberately points the service at an unreachable dependency. The expected behavior is not success. The service should return an unavailable response, and it should do so within a fixed upper bound. That is a meaningful reliability contract: an orchestrator needs a quick, honest answer rather than a request that hangs behind retry policies intended for normal user operations.

The test boots the real host, makes the request, verifies the unavailable result, and checks elapsed time.

So far, so good.

The failure blamed the wrong interval

The timing assertion began failing repeatedly in CI. Raising the limit would have made the build green. Adding an automatic retry might also have hidden the symptom.

Neither action would have explained the result.

The endpoint implementation had not changed during the relevant window. More importantly, the surrounding timing evidence showed that host startup in the same test took roughly as long as the delay attributed to the readiness request. The test also ran beside many parallel integration classes doing heavier work.

The stopwatch was attached to one request, but that request still depended on threads scheduled in a shared process. Under contention, continuation work can wait. Startup can wait. Connection failure can be observed later than expected. The test reports wall-clock time, not pure execution time.

This does not prove the service is fast. It proves the original experiment was unable to tell product latency from runner contention.

Keep the budget before changing it

When a timing test turns red, I prefer to keep the bound intact while investigating. The bound represents a real operational expectation. Relaxing it before understanding the measurement destroys evidence that may still be valuable.

A useful first pass is to separate three intervals:

Setup — host boot, fixture creation, migrations, container startup, and test data.
Contention — time spent waiting for CPU, threads, sockets, database slots, or another shared resource.
Behavior — the operation whose latency the assertion is meant to protect.

Instrumenting those boundaries does not require a production profiler. Even a few carefully placed timestamps can reveal that the supposedly slow operation accounts for only a small part of the elapsed test.

Isolate the claim, not the whole suite

The narrow repair was to move only the timing proof into a non-parallel test collection.

The response status did not change. The time budget did not change. The endpoint code did not change. Functional readiness tests stayed in the normal parallel suite. Only the test making a wall-clock claim received an isolated measurement lane.

That scope matters. Serializing an entire integration project can turn a useful diagnosis into an expensive habit. Parallel tests are valuable because they shorten feedback cycles and expose accidental shared state. The aim is not to remove parallelism. It is to stop using an uncontrolled parallel environment as a precision instrument.

I like to keep separate tests for separate questions:

Does the check return the correct status when the dependency is unavailable?
Does the response avoid leaking infrastructure details?
Does the host remain alive while readiness is false?
Under controlled contention, does the readiness answer stay within its operational budget?

Only the last question necessarily needs timing isolation.

The trade-off is real

An isolated collection adds a serial tail to the build. It also creates another test boundary that future maintainers must understand. If many tests demand exclusive execution, the suite can become slow and the isolation can conceal real capacity problems.

That is why this technique should be applied to the measurement contract, not used as a blanket cure for flakiness.

In return, failures become more actionable. A red timing check is less likely to mean “the runner happened to be crowded” and more likely to mean “the protected latency contract changed.” The team spends less time rerunning the same experiment and less time normalizing noise by widening budgets.

A practical review checklist

Before changing a failed CI time limit, ask:

Did the measured implementation change?
Is setup included in the timed region?
Which resources are shared with parallel tests?
Does the test need fixtures it is currently competing for?
Can functional correctness remain parallel while the timing proof runs alone?
Would the same isolation exist in the production condition we care about?

The last question prevents overfitting. An isolated test should remove irrelevant test-runner noise, not erase meaningful load. If the production contract is specifically about behavior under concurrency, create a controlled load test with explicit pressure instead of relying on incidental CI contention.

Precision is a property of the experiment

A stopwatch does not make a test scientific by itself. The environment, boundaries, and competing work determine what the number means.

Keep meaningful budgets. Investigate before retrying. Isolate the smallest timing claim that needs a controlled lane, and leave the rest of the suite parallel.

The result is not merely a greener pipeline. It is a test whose failure tells you something you can act on.

From Anemic Models to Rich Domain Models, DDD Base Entities, and C# Records

Tue, 27 Oct 2026 10:51:17 +0000

When building enterprise applications in C#, a common architectural trap is writing procedural code disguised as object-oriented code. This usually happens when we rely entirely on anemic data bags (public get; set; DTOs) for business logic, forcing our application services to manage all validation and state changes manually.

In this guide, we will tie together Object-Oriented Programming (OOP), the Single Responsibility Principle (SRP), Domain-Driven Design (DDD) Entity base classes, C# Records for Value Objects, Combining Interfaces & Abstract Classes, EF Core Persistence, and Unit Testing into a complete, publication-ready reference.

Part 1: The Anti-Pattern (Anemic Models & DTO Misuse)

An anemic model treats classes as passive data structures with zero behavior. When every model exposes public setters, any part of the codebase can mutate state arbitrarily, bypassing business rules.

The Problematic Approach

// 1. The Anemic Entity (Just a data bag)
public class OrderDto
{
    public Guid Id { get; set; }
    public string CustomerEmail { get; set; }
    public decimal TotalAmount { get; set; }
    public string Status { get; set; } // Can be set to anything from anywhere!
}

// 2. The God Service handling all procedural logic
public class OrderService
{
    public void ProcessOrder(OrderDto order)
    {
        // Business logic scattered in services instead of living in the model
        if (order.TotalAmount <= 0) throw new Exception("Invalid amount");
        order.Status = "Processed"; // Direct mutation without invariant checks
    }
}

Why Anemic Models Fail

Repeated Validation Checks: Since anemic models can't check their own rules, every service or controller writes the same validation code over and over. If a developer forgets one check, a business rule breaks silently.
Unprotected Data (Broken States): Public setters mean code can accidentally create broken data—like a negative order total or an incomplete order marked as completed—which then gets saved to the database.
Hard-to-Fix Rules ("Shotgun Surgery"): When business rules change, you have to hunt through 10 different files and controllers to update identical if statements.

Part 2: DDD Foundation — Entity Base Class & C# Records

In Domain-Driven Design, Entities are defined by their unique identity rather than their attributes, while Value Objects (idiomatically implemented using C# records) are defined entirely by their structural values and are strictly immutable.

1. DDD Entity Base Class

Notice how EqualityComparer<TId> is used below to robustly handle generic identifier comparisons across different types (Guid, int, string, etc.) while ensuring unpersisted entities do not falsely equal each other:

public abstract class Entity<TId>
{
    public TId Id { get; protected set; }

    public override bool Equals(object? obj)
    {
        if (obj is not Entity<TId> other) return false;
        if (ReferenceEquals(this, other)) return true;
        if (GetType() != other.GetType()) return false;

    if (EqualityComparer<TId>.Default.Equals(Id, default!) || 
        EqualityComparer<TId>.Default.Equals(other.Id, default!))
        return false;


        return EqualityComparer<TId>.Default.Equals(Id, other.Id);
    }

public override int GetHashCode() => (GetType().ToString() + Id).GetHashCode();

public static bool operator ==(Entity<TId>? a, Entity<TId>? b) => a?.Equals(b) ?? b is null;
public static bool operator !=(Entity<TId>? a, Entity<TId>? b) => !(a == b);

2. C# Records for Value Objects

Using record gives us value-based structural equality out-of-the-box and immutability by default (init setters).

public record EmailAddress
{
    public string Value { get; init; }

    public EmailAddress(string value)
    {
        if (string.IsNullOrWhiteSpace(value) || !value.Contains("@"))
            throw new ArgumentException("Invalid email format.");
        Value = value;
    }
}

Part 3: Combining Interfaces, Abstract Classes, and DDD Entities

Now we structure our customer hierarchy by inheriting from our DDD Entity<Guid>, implementing our ICustomer interface, and using our EmailAddress value object.

// 1. The Interface defines the full contract
public interface ICustomer
{
    Guid Id { get; }
    EmailAddress Email { get; }
    decimal TotalSpent { get; }
    
    decimal CalculateDiscount(decimal orderAmount);
    void RecordPurchase(decimal amount);
}

// 2. The Abstract Base Class inherits from DDD Entity and implements ICustomer
public abstract class CustomerBase : Entity<Guid>, ICustomer
{
    public EmailAddress Email { get; private set; }
    public decimal TotalSpent { get; private set; }

    protected CustomerBase(Guid id, EmailAddress email)
    {
        Id = id;
        Email = email ?? throw new ArgumentNullException(nameof(email));
        TotalSpent = 0m;
    }

    public void RecordPurchase(decimal amount)
    {
        if (amount <= 0) throw new ArgumentException("Purchase amount must be positive.");
        TotalSpent += amount;
    }

    public abstract decimal CalculateDiscount(decimal orderAmount);
}

// 3. Concrete Implementations
public class RegularCustomer : CustomerBase
{
    public RegularCustomer(Guid id, EmailAddress email) : base(id, email) { }

    public override decimal CalculateDiscount(decimal orderAmount) => 0m;
}

public class VipCustomer : CustomerBase
{
    public decimal CreditLimit { get; private set; }

    public VipCustomer(Guid id, EmailAddress email, decimal creditLimit) : base(id, email)
    {
        if (creditLimit < 0) throw new ArgumentException("Credit limit cannot be negative.");
        CreditLimit = creditLimit;
    }

    public override decimal CalculateDiscount(decimal orderAmount) => orderAmount * 0.10m;
}

Part 4: The Rich Domain Model (`Order`)

Our Order inherits from Entity<Guid>, enforces business invariants, and coordinates with ICustomer.

public class Order : Entity<Guid>
{
    public ICustomer Customer { get; }
    public decimal TotalAmount { get; private set; }
    public OrderStatus Status { get; private set; }

    public Order(Guid id, ICustomer customer, decimal initialAmount)
    {
        Id = id;
        Customer = customer ?? throw new ArgumentNullException(nameof(customer));
        
        if (initialAmount <= 0)
            throw new ArgumentException("Order amount must be greater than zero.");

        TotalAmount = initialAmount;
        Status = OrderStatus.Draft;

        ApplyCustomerDiscount();
    }

    private void ApplyCustomerDiscount()
    {
        decimal discount = Customer.CalculateDiscount(TotalAmount);
        TotalAmount -= discount;
    }

    public void AddItem(decimal itemPrice)
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException("Cannot modify an order after it has been submitted.");

        TotalAmount += itemPrice;
    }

    public void SubmitPayment()
    {
        if (Status != OrderStatus.Draft)
            throw new InvalidOperationException("Order is already processed.");

        Status = OrderStatus.Submitted;
    }
}

public enum OrderStatus { Draft, Submitted, Completed }

Part 5: Orchestrating with SRP and Dependency Injection

Our application service (OrderProcessor) focuses purely on coordination (following the Single Responsibility Principle).

public class OrderProcessor
{
    private readonly IOrderRepository _repository;
    private readonly IPaymentGateway _paymentGateway;
    private readonly IEmailNotifier _notifier;
    private readonly ILogger<OrderProcessor> _logger;

    public OrderProcessor(
        IOrderRepository repository,
        IPaymentGateway paymentGateway,
        IEmailNotifier notifier,
        ILogger<OrderProcessor> logger)
    {
        _repository = repository;
        _paymentGateway = paymentGateway;
        _notifier = notifier;
        _logger = logger;
    }

    public async Task ProcessAsync(Guid orderId)
    {
        var order = await _repository.GetByIdAsync(orderId);
        if (order == null) throw new KeyNotFoundException("Order not found.");

        order.SubmitPayment();

        if (!await _paymentGateway.ChargeAsync(order.TotalAmount))
        {
            throw new InvalidOperationException("Payment failed.");
        }

        order.Customer.RecordPurchase(order.TotalAmount);

        await _repository.SaveAsync(order);
        await _notifier.SendConfirmationAsync(order.Customer.Email.Value);

        _logger.LogInformation("Successfully processed order {OrderId}", order.Id);
    }
}

Part 6: Persistence with EF Core (Mapping Records & TPH)

Using EF Core Entity configurations to map our DDD entities, value objects (records via owned types), and inheritance hierarchy.

public class AppDbContext : DbContext
{
    public DbSet<CustomerBase> Customers => Set<CustomerBase>();
    public DbSet<Order> Orders => Set<Order>();

    protected override void OnModelCreating(ModelBuilder modelBuilder)
    {
        // Configure Customer Inheritance (TPH)

modelBuilder.Entity()

        .HasKey(c => c.Id);

    modelBuilder.Entity<CustomerBase>()
        .OwnsOne(c => c.Email, email =>
        {
            email.Property(e => e.Value).HasColumnName("Email").IsRequired();
        });

    modelBuilder.Entity<CustomerBase>()
        .HasDiscriminator<string>("CustomerType")
        .HasValue<RegularCustomer>("Regular")
        .HasValue<VipCustomer>("VIP");

    // Configure Order Entity
    modelBuilder.Entity<Order>()
        .HasKey(o => o.Id);

    modelBuilder.Entity<Order>()
        .HasOne(o => o.Customer)
        .WithMany()
        .HasForeignKey("CustomerId");

}
}

Part 7: Unit Testing with Records & Entities

public class DomainTests
{
    [Fact]
    public void VipCustomer_WithValidData_CalculatesDiscountAndTracksSpend()
    {
        var email = new EmailAddress("*Emails are not allowed*");
        ICustomer customer = new VipCustomer(Guid.NewGuid(), email, 5000.00m);
        var order = new Order(Guid.NewGuid(), customer, 200.00m);

        // 200 - 10% = 180
        Assert.Equal(180.00m, order.TotalAmount);

        customer.RecordPurchase(order.TotalAmount);
        Assert.Equal(180.00m, customer.TotalSpent);
    }
}

References & Further Reading

Martin Fowler (2003): AnemicDomainModel — Read article.
Eric Evans (2003): Domain-Driven Design: Tackling Complexity in the Heart of Software — Addison-Wesley Professional.
Robert C. Martin (2017): Clean Architecture: A Craftsman's Guide to Software Structure and Design — Prentice Hall.

Tuesday Coding Tip 28 — (de)serializing JSON string enum in C#

Tue, 27 Oct 2026 09:59:00 +0000

Tuesday coding tips are super short posts about various tidbits mainly from C++, but also from other programming languages I use. You can also follow the #TuesdayCodingTips hashtag on Mastodon and Linkedin.

Last time I covered C# JSON serialization, I only showcased the Newtonsoft.Json library. This time, I will also show the System.Text.Json way.

You might want to (de)serialize enums as strings, rather than numeric values. Since C# does not support enums with an underlying type of string, you need to do some extra work. Namely, you have to annotate each value using the EnumMember annotation and then select the correct converter, once again using annotations.

using System.Runtime.Serialization;
using Newtonsoft.Json;
using Newtonsoft.Json.Converters;

public enum Mood
{
    [EnumMember(Value = "happy")]
    Happy,
    [EnumMember(Value = "sad")]
    Sad,
}

public class Object
{
    [JsonProperty("mood")]

    [JsonConverter(typeof(StringEnumConverter))]
    public Mood Mood { get; set; }
}

public static class Program
{
    public static void Main()
    {
        string json = JsonConvert.SerializeObject(new Object
        {
            Mood = Mood.Sad
        });

        Console.WriteLine(json);
        // {"mood":"sad"}
        Console.WriteLine(JsonConvert.DeserializeObject<Object>(json)!.Mood);
        // Sad
    }
}

However, System.Text.Json doesn’t support EnumMember annotations out of the box. It takes the literal name of the property instead. You can play with capitalization using options object, but that’s it. Or you can write your own converter. Or you can just use one of the dozen converters from the Internet that do the hard work for you.

using System.Runtime.Serialization;
using System.Text.Json.Serialization;

public enum Mood
{
    [EnumMember(Value = "happy")]
    Happy,
    [EnumMember(Value = "sad")]
    Sad,
}

public class Object
{
    [JsonPropertyName("mood")]
    // To use EnumMember annotations, install Macross.Json.Extensions nuget
    // and use a different converter
    // [JsonConverter(typeof(JsonStringEnumMemberConverter))]
    [JsonConverter(typeof(JsonStringEnumConverter))]
    public Mood Mood { get; set; }
}

public static class Program
{
    public static void Main()
    {
        Object obj = new()
        {
            Mood = Mood.Sad,
        };

        string json = System.Text.Json.JsonSerializer.Serialize(obj);
        Console.WriteLine(json);
        // {"mood":"Sad"}
        Console.WriteLine(System.Text.Json.JsonSerializer.Deserialize<Object>(json)!.Mood);
        // Sad
    }
}

A Query Window Is Not a Calendar Day

Mon, 26 Oct 2026 20:12:29 +0000

Software often uses broad time windows for good reasons. A dashboard may need recent history, work that is actionable now, and the next scheduled item. Fetching all of that in one bounded query can be efficient and easy to reason about.

The trouble begins when the retrieval window quietly becomes the business definition of “today.”

This is a small distinction with a very visible failure mode: shortly after midnight, yesterday’s missed item appears under today’s heading. The query is returning exactly what it was asked to return. The selection rule is wrong.

Retrieval and meaning are different jobs

Imagine a “Today” screen that loads items from several hours in the past through the next day. The look-back allows the screen to include work that recently closed or may still be open. The look-ahead allows it to show what comes next.

That range is a retrieval concern. It answers:

Which records could be relevant enough to inspect?

It does not answer:

Which record belongs to the user’s current calendar day?

If selection simply chooses the first item whose state is due or missed, a previous day’s missed item can win after midnight. If display text assumes every future item is later today, tomorrow morning can be described as though it were later tonight.

Both errors come from using temporal proximity as a substitute for calendar meaning.

Define “today” in the relevant time zone

Server time is rarely the correct authority for a human-facing day. UTC is excellent for storing instants and comparing elapsed time. It is not a user’s calendar.

The safer sequence is:

Read the current instant from an injected clock.
Convert it once into the time zone that owns the workflow.
Derive a local date from that value.
Use that date when classifying calendar-bound states.

Computing the value once matters. It keeps every decision in one request anchored to the same instant, including the unlikely case where execution crosses midnight.

The relevant time zone also needs to be explicit. It may belong to a person, site, account, or workflow. The correct choice is a domain decision, not an infrastructure default.

Preserve the exception that actually matters

A tempting fix is to discard every record whose local date is not today. That is neat and wrong when an actionable window crosses midnight.

Suppose a task opened before midnight and remains valid until shortly afterwards. A strict date filter would hide it at the exact moment it still needs attention.

This is where explicit domain rules beat blanket filtering:

missed and completed items count as current only when their local date is today;
a still-open item remains current while it is actionable, regardless of its start date;
a scheduled item on another day can still appear as next, but its wording names that day.

The rule is slightly longer because the product meaning is slightly richer. That extra branch is not accidental complexity. It records why two superficially similar records are treated differently.

Make wording part of correctness

Time bugs are not confined to sorting and filtering. Labels can encode false claims too.

“Later today” is only correct if the next item is on the same local day. “Between 08:00 and 09:00” may be ambiguous when viewed the night before. Adding “tomorrow” or a concrete day makes the model visible to the user.

That wording also gives tests a useful public outcome. A test can verify that the screen says tomorrow without reaching into a private helper or asserting a particular LINQ expression.

Test the boundary as a sequence

A single test at noon will not find this class of defect. The useful test moves a controllable clock through the state transition.

One focused integration scenario can prove three behaviours:

On the item’s own evening, the missed item is still classified as belonging to today.
The next day’s scheduled item is labelled explicitly as tomorrow.
After midnight, the old missed item no longer becomes the current card.

Using the real persistence provider is valuable when stored dates, generated occurrences, or query translation participate in the behaviour. The clock is the external boundary worth controlling; internal services do not need to be mocked if the public result proves the rule.

Also test a window that genuinely spans midnight. Without that case, a cleanup that filters everything by date can look correct while introducing a different regression.

The engineering trade-off

Explicit local-date classification costs a few things:

more branches than a simple state check;
a time-zone conversion at the application boundary;
boundary-focused tests and more deliberate copy.

In return, the system becomes predictable at the moment when implicit assumptions fail most often. Retrieval can remain broad for performance and completeness. Domain selection becomes precise. User-facing language reflects the same model.

The broader leadership lesson is to ask two questions whenever a time range appears in code:

Is this range finding candidates, or defining business membership?
Whose calendar gives words such as today, tomorrow, and missed their meaning?

Keeping those answers separate prevents an implementation convenience from becoming an accidental policy.

Practical checklist

When building a day-oriented view:

store and compare instants consistently;
identify the domain-owned time zone;
derive the local date once per operation;
keep retrieval windows separate from classification rules;
preserve intentionally actionable cross-midnight windows;
make off-day wording explicit;
test before midnight, after midnight, and a spanning window.

The code may still query eighteen or thirty hours. The user should experience a calendar day.

Idempotency Should Resume Partial Work, Not Hide It

Sun, 25 Oct 2026 19:34:58 +0000

Idempotency is usually introduced with a simple promise: run the operation again and it will not create a duplicate.

That promise is useful, but it can become dangerous when we apply it to an entire workflow instead of the specific durable step it protects.

I recently reviewed a recurring integration job with two independent writes. First, it appended a status note to an external record. Second, it moved that record into a terminal state. The note contained a unique marker, so retries could see that the note had already been written.

The marker worked. The workflow did not.

When the state transition failed once, the note remained. On the next sweep, the job saw the marker and skipped the record completely. A local sign of success for step one had accidentally become a global completion flag for steps one and two.

That is a subtle reliability bug because the automation appears idempotent while the real process is only half finished.

A checkpoint is not the whole journey

Consider a generalized background job:

Write a durable note with a unique operation marker.
Move the remote record into a terminal workflow state.
Repeat the scan for a bounded period so temporary failures can heal.

The marker proves exactly one fact: the note exists.

It does not prove that the state move succeeded. It does not prove that a notification was delivered, a file was copied, or a later API call completed. Yet it is tempting to write an early return such as “marker found, therefore this item is done.”

The safer model gives each durable step its own completion evidence. In this case, the marker suppresses only another note. Later sweeps still inspect the remote record and decide whether the second step is pending.

This sounds like a small distinction. In production, it is the difference between duplicate prevention and recovery prevention.

Reconciliation makes partial completion explicit

A resumable job expects to encounter intermediate states:

no note and no terminal state;
note present but transition still pending;
note present and record already terminal;
note present but a person changed the record afterwards;
remote workflow metadata that no longer matches our assumptions;
a temporary failure that should be tried again;
a permanent incompatibility that needs attention.

Those are not exotic edge cases. They are the normal state space of a multi-step integration.

The repaired design runs the state decision on every bounded reconciliation sweep. If the note is missing, it writes the note once. Whether the note was just written or already existed, it then evaluates the transition separately.

That separation makes the control flow honest. We can retry the unfinished part without repeating the finished part.

Ask the external system what its workflow means

The original failure was also a reminder that external state names are rarely universal. One workflow may call its terminal state “Done”; another may use a different label. Hard-coding one friendly name works until a customized process rejects it.

The stronger approach reads the record's type and the available states for that type. It prefers an explicitly configured state when that state exists. Otherwise, it can select a state by semantic category, such as completed or removed.

This adds metadata reads and some branching. It also moves compatibility knowledge to the boundary where it belongs. The integration stops pretending that its vocabulary is the external system's vocabulary.

That fallback must remain bounded. If no suitable category exists, the job should surface the incompatibility rather than inventing a transition.

Human intent outranks automation

Retrying forever is not the same as reconciling safely.

Suppose the automation wrote its note yesterday, then a person deliberately reopened or reclassified the record today. A later sweep should not force the record back into the automation's preferred state.

The reconciliation rule therefore needs ordering evidence. If the external state changed after our durable note, leave it alone. If ordering is unknown, prefer the conservative choice and do not overwrite. If the record is already in any terminal category, there is nothing to repair.

This is an important boundary: the job owns completion of its own intent, not the external workflow itself.

Retry by failure class

Not every failure deserves the same response.

A timeout or temporary service error can be retried by the next sweep. A missing permission or incompatible workflow definition will not improve through repetition. That condition should be reported, with noise controlled, while unrelated records continue.

This classification keeps the job useful during partial outages. One bad record does not starve the batch, and operators are not flooded with alerts for failures that the normal reconciliation loop can heal.

Caching workflow metadata for the duration of one sweep can also limit API traffic without letting old assumptions live indefinitely.

Test the half-finished states

Happy-path tests are not enough for resumable automation. The valuable tests begin after something durable has already happened.

I would want focused coverage proving that:

an existing marker prevents a duplicate note but not a pending transition;
a previously failed transition is attempted on a later sweep;
different state names can resolve through semantic metadata;
terminal records are left untouched;
a newer human change is preserved;
unknown ordering is handled conservatively;
one record's failure does not block the others;
temporary and permanent failures take different paths.

These tests describe the recovery contract more clearly than a mock verifying one ideal call sequence.

The practical rule

For every multi-step job, list the durable evidence produced by each step. Then ask what the next run should do when execution stops after any one of them.

Idempotency should let a workflow resume safely. If an “already processed” check prevents the system from finishing later steps, it is not protecting reliability. It is hiding incomplete work.

Let the Router Own the Next Paint

Sat, 24 Oct 2026 07:06:52 +0000

Navigation bugs are often judged by their final state. Did the correct page appear? Did the authorization check pass? Did the URL settle on the expected address?

Those questions matter, but they can miss the frame that users actually notice.

In a recent component-based web fix, the destination page was correct. The address was correct. The authorization result was correct. Yet, between the address change and the destination render, the departing page painted once more. Because the framework also applied its scroll reset during that interval, users briefly saw stale content at the top of the viewport before the new page arrived.

The repair produced a useful general lesson: after an address change, the router should own the next visible paint.

A correct destination can still have a wrong journey

An end-state test sees a simple sequence:

start on page A;
navigate to page B;
assert that page B is visible.

The browser may have seen something richer:

page A is visible at the user’s current scroll position;
the address changes to B;
page A renders again under B’s address;
a framework scroll reset moves that stale page to the top;
page B finally renders.

Steps three and four may last only one frame. They are still part of the product.

This is why navigation correctness is not only about eventual state. It also includes the ordered render sequence between the user action and the destination becoming authoritative.

The hidden effect of an event receiver

The source of the extra paint was subtle. An asynchronous navigation callback was registered with the component that hosted the route tree as its receiver.

In many component frameworks, completing an event callback schedules a render of the receiving component. That behaviour is normally helpful: event handlers change state, so the framework redraws the owner automatically.

Navigation is different. The callback prepared the transition, but the router—not the departing component—owned the destination. When the receiver-bound callback completed, the framework rendered the old route tree once more. The router rendered the new page immediately afterward, but it was no longer responsible for the first batch after the address changed.

The fix did not add a delay, loading overlay, or animation. It removed the accidental receiver. The callback still ran, but its completion no longer implied that the departing route component needed to render. The router’s destination batch became the first visible paint after the address change.

Measure the interval, not just the answer

The strongest part of the repair was the test shape.

Instead of sleeping and hoping to catch a flicker, the test marked the instant the address changed. It then counted every component render until the destination page entered the render tree.

Before the change, that interval contained twelve render notifications in the exercised path. After the change, it contained zero.

The specific number is less important than the invariant:

Nothing else paints after the address changes and before the destination appears.

That assertion is deterministic. It does not depend on monitor refresh rate, screenshot timing, or a human noticing a flash. It also fails for the causal behaviour rather than a visual approximation of the symptom.

Keeping the old page has a boundary

There is a reasonable usability goal behind retaining the current page: an established screen is often a better placeholder than a blank shell while the destination prepares.

But retained content needs a strict boundary. The old page belongs to the source route and its source authorization decision. It must not start making decisions for the new address, consume state prepared for the destination, or imply that access to the destination has been granted.

Security invalidation is the important exception. If the user signs out or loses a role, the retained page must stop being authoritative immediately. Smoothness must never extend stale permission.

That gives us two complementary rules:

retain a certified source view only until its replacement is ready;
invalidate it immediately when the identity or authorization basis changes.

The result is continuity without authority leakage.

Test the negative space

A good transition test suite should cover more than the successful move between two ordinary pages.

Useful cases include:

an allowed destination;
a refused destination;
a layout or shell change;
sign-out during preparation;
role loss during preparation;
an older asynchronous result completing after a newer transition;
a callback that finishes on a different scheduling context.

These cases reveal who truly owns the transition. If several components can repaint or decide access for the same interval, the design is probably carrying more than one authority.

A practical review method

When reviewing client-side navigation, draw a short timeline: user action, address change, preparation, first destination render, and interaction-ready state.

For each gap, ask:

Which component may render?
Which route does that render belong to?
Which authorization decision supports it?
Can an event callback schedule an incidental redraw?
What happens if identity changes or an older task completes late?

Then write at least one sequence assertion. Final-state tests remain valuable, but they should be paired with a guard over the transition when a single wrong frame matters.

The leadership lesson

Small visual defects often expose unclear ownership rather than missing polish. A loading spinner might hide the flash, but it would not explain why the departing component could repaint under the destination address.

The more durable repair is to assign one owner to the critical interval and test that ownership directly.

Users experience every frame, not only the last one. Our tests should be willing to do the same.

Tolerant Decoding, Strict Release Gates

Fri, 23 Oct 2026 06:38:59 +0000

A release verifier has two jobs that are easy to blur together. It must understand the representation produced by the build chain, and it must enforce the policy that decides whether an artifact may leave that chain.

Those jobs need different attitudes.

Decoding can be narrowly tolerant of documented, meaning-preserving variation. Release policy should remain exact and fail closed.

That distinction surfaced in a recent mobile build repair. A generated JSON settings file could begin with the optional UTF-8 byte-order marker. The JSON content was valid, but the verifier decoded it as plain UTF-8 and failed before it could evaluate the values that actually governed release safety.

The fix was not to “clean up” the input generally. It was to accept one specific encoding variation, then run the same strict semantic checks as before.

Representation is not policy

A byte-order marker sits at the representation boundary. In this case, accepting UTF-8 with or without that marker did not change the JSON values.

An endpoint or feature-handoff setting is different. It changes what the package will do after installation. That is policy-bearing data.

Treating both categories as raw bytes creates a brittle gate: a harmless encoding detail can block a valid package. Treating both categories as broadly normalisable creates a permissive gate: a meaningful difference may be trimmed, defaulted, coerced, or discarded before verification sees it.

The useful middle ground is narrow tolerance:

Decode only the representation variants the producer is documented to emit.
Parse into an explicit data shape.
Compare policy-bearing values exactly.
Publish nothing until every check has passed.

This is a small design choice, but it keeps compatibility and authority in their proper layers.

Why broad normalisation is risky

“Normalise before comparing” sounds sensible. Sometimes it is. The danger is that normalisation is often written without naming which differences are harmless.

Should surrounding whitespace be trimmed? Should an empty string become null? Should a missing value receive a default? Should a hostname lose its trailing separator? Should key casing be ignored?

Each transformation might be correct for one contract and wrong for another. Once a release gate performs all-purpose cleanup, reviewers can no longer see which deviations the gate intentionally accepts.

A better question is: who owns this variation?

The decoder owns permitted encoding markers. The JSON parser owns JSON syntax. The release policy owns the approved endpoint and capability settings. Package signing owns artifact identity. Device acceptance owns behaviour on the target platform.

Let each boundary make only the decision it has enough information to make.

Test tolerance and strictness together

A positive test for the newly accepted variant is necessary, but it is not enough. It proves compatibility; it does not prove that policy remained intact.

The stronger test set combines the representation variant with both approved and disallowed semantics:

a marker-bearing file with approved values passes;
the verifier emits a clean, parseable receipt;
a marker-bearing file with an unapproved endpoint fails;
a marker-bearing file with an unapproved handoff configuration fails;
either failure produces no distributable package and no success receipt.

Those negative cases are the important counterweight. They show that the change expanded the accepted representation, not the accepted deployment policy.

The no-output assertions also matter. A verifier that reports failure after copying the package has already lost the race. Publication must happen after verification, not alongside it. The absence of a receipt is useful too: downstream automation must not mistake a partially completed run for approval.

Make the artifact boundary transactional

File-based pipelines rarely have a database transaction around the whole release. We can still design them with transactional thinking.

Build into a private staging location. Verify the package, its embedded settings, its signature, and any required metadata there. Only after the full decision succeeds should the pipeline copy or promote the artifact and write the corresponding receipt.

On failure, the public output location should remain unchanged.

This ordering turns the output directory into a simple commit boundary. Before promotion, the candidate is merely work in progress. After promotion, the package and its evidence agree.

A practical review checklist

When one tool generates a file and another tool gates a release from it, review four things:

1. Enumerate representation variants

Record the encodings, markers, line endings, ordering guarantees, and optional fields the producer may legitimately emit. Avoid accepting variants merely because a parser can.

2. Identify policy-bearing fields

List the values that change destination, authority, enabled capabilities, signing identity, or runtime behaviour. Compare them deliberately rather than through a generic object cleanup step.

3. Add crossed tests

Test each permitted representation with approved values and with at least one disallowed value. This catches the accidental move from narrow compatibility to broad permissiveness.

4. Prove fail-closed publication

Assert not only that verification returns failure, but also that no package, receipt, or other success signal appears in the publish location.

The leadership lesson

Strictness is not the same as rejecting every variation. Good gates are precise about what they tolerate and equally precise about what they refuse.

That precision makes a pipeline easier to operate. Engineers can fix harmless toolchain differences without weakening release policy. Reviewers can see the exact compatibility allowance. Operators can trust that a failed gate did not leave an ambiguous artifact behind.

The goal is not a gate that never bends. It is a gate that bends only where meaning is unchanged—and stays immovable where deployment meaning begins.

An Empty Field Is Still Signed Data

Thu, 22 Oct 2026 06:11:15 +0000

An empty form field looks unimportant. In ordinary application logic, treating an empty value like a missing value is often reasonable. In signature verification, that assumption can reject a legitimate message—or, in a different protocol, verify a representation the sender never signed.

The important lesson is simple: canonicalization is not generic data cleanup. It is part of the cryptographic protocol.

The tidy abstraction that hid a real difference

Consider an integration with two flows:

The application builds an outbound form and signs it.
A provider later sends an inbound form notification that the application verifies.

Both flows need URL encoding, ordered key=value pairs, a digest, and a comparison. A shared helper therefore seems sensible.

But suppose the protocol defines different empty-field rules. The outbound form omits empty values. The inbound notification includes every posted field, even an empty one represented as description=. Reusing the outbound rule during verification silently removes part of the inbound canonical representation.

Nothing is wrong with the network message. Nothing is wrong with the secret. The application simply hashes different bytes from the sender.

That is the dangerous kind of bug: the code is deterministic, the crypto primitive behaves correctly, and the abstraction looks clean. The failure lives in the representation contract.

Empty and absent are different inputs

Application code tends to reason semantically:

note= means there is no useful note.
no note field also means there is no useful note.

A signing algorithm reasons syntactically. It may see:

reference=abc&note=&status=complete

as a different message from:

reference=abc&status=complete

The same applies to field order, repeated keys, character encoding, spaces, escaping, decimal formatting, and line endings. Two representations can produce the same business meaning while producing different signatures.

That is why “normalize before verifying” is unsafe advice unless the protocol defines the normalization precisely. The verifier’s job is not to improve the input. Its job is to reconstruct exactly what the other side signed.

The repair pattern I prefer keeps the truly common pieces together while making direction-specific rules visible.

Shared mechanics may include:

the exact form-encoding routine;
digest calculation;
secret or passphrase handling;
fixed-time signature comparison;
consistent fail-closed behaviour.

The canonicalization policies remain separate:

outbound signing can omit empty fields when the outbound specification says so;
inbound verification can retain empty fields when the inbound specification says so;
both can exclude the signature field itself;
both can preserve their required ordering.

This introduces a small amount of repetition. That is a healthy trade when the alternative is a boolean option buried inside a generic helper whose callers must remember invisible protocol rules. If a shared primitive is retained, give the public operations names and documentation that make the distinction impossible to miss.

Test the representation, not your implementation

Signature tests often contain a subtle circularity: the test calls the production signing helper to create the expected signature, then asks the same helper to verify it. The test proves internal consistency, not compatibility with the protocol.

A stronger test builds the canonical input independently. For the inbound case, start from a literal ordered field sequence containing several key= entries. Calculate the expected digest with a small test-only oracle or a published fixture. Then submit the body to the real verification path.

Useful negative cases include:

remove one empty field and expect rejection;
change field order and expect rejection when order is significant;
replace an empty field with an absent field;
vary spaces and reserved characters;
include a blank expected signature and fail closed;
change only the signature field and confirm it is excluded from canonical input.

These tests describe the protocol boundary directly. They are harder for a refactor to accidentally “update” into agreeing with the bug.

Exercise the framework pipeline too

A pure canonicalization test is necessary, but it is not sufficient for a web endpoint.

Framework model binding and form parsing can consume a request stream, decode characters, merge values, or present fields through an API with different ordering behaviour. Middleware can also affect buffering or body access. A verifier that works against a handcrafted dictionary may still fail when the real HTTP pipeline handles the request first.

Add one focused integration test that:

creates the literal encoded body;
independently calculates the signature over that exact representation;
sends an actual form POST through the application’s HTTP stack;
verifies that the original body remains available where required;
proves the request reaches the normal accepted outcome.

This is not an argument for turning every edge case into a slow end-to-end test. Keep the combinatorial matrix in fast unit tests. Use the HTTP-level case as a boundary witness that the framework and your canonicalization contract still agree.

Verification is necessary, not complete trust

Correct signature verification answers a narrow question: does this message match the shared signing contract and secret?

It does not automatically prove that the event is fresh, unique, authorized for the referenced resource, or safe to apply twice. Production handlers may still need replay protection, timestamp or nonce validation, amount and ownership checks, idempotency, audit evidence, and careful failure handling.

Keeping that claim bounded matters. Strong security engineering is usually a chain of explicit checks, not one impressive cryptographic step.

A practical review checklist

When reviewing a signed integration, ask:

What exact bytes or characters are signed in each direction?
Are empty and missing values distinct?
Is field order defined and preserved?
When does decoding or encoding happen?
Are repeated fields possible?
Does the comparison avoid timing leaks?
Do invalid inputs fail closed?
Is at least one expected signature calculated independently?
Does a real HTTP test cover framework parsing?

The broader engineering principle is worth carrying elsewhere: an abstraction should share sameness, not erase difference. At a cryptographic boundary, the awkward representational details are often the contract itself.

Put the Concurrency Gate Before the Side Effect

Wed, 21 Oct 2026 05:40:24 +0000

Many concurrency bugs begin with code that looks entirely reasonable:

Read the current row.
Check that the operation is still allowed.
Create something durable elsewhere.
Save the original row as complete.

Run once, the workflow is correct. Run twice at almost the same time, and both callers can pass the check before either caller records completion. If step three is irreversible, the system can create duplicate work even though every individual condition was true when evaluated.

The core lesson is simple: when a state transition guards a side effect, make the database choose the winner before the side effect begins.

Why read-then-check is not ownership

An application-level check answers, “What did I observe?” It does not answer, “Do I exclusively own this transition?”

Imagine a parent record representing an open request. Accepting one option creates a downstream record and closes the parent. Two callers can follow this timeline:

Caller A reads the parent as open.
Caller B reads the same parent as open.
Caller A creates a downstream record.
Caller B creates another downstream record.
Both callers try to close the parent.

Optimistic concurrency on the final save may reject one update, but by then the rejected caller may already have created the duplicate side effect. Detecting a conflict after the irreversible action is too late.

Move the decision forward

A stronger shape puts a conditional write immediately before downstream creation. In generalized SQL, the intention is:

UPDATE WorkItems
SET ClaimToken = @token, ClaimedAt = @now
WHERE Id = @id
  AND Status = 'Open'
  AND ClaimToken IS NULL;

The affected-row count becomes the decision:

One affected row means this caller owns the transition.
Zero affected rows means another caller won, or the operation is no longer valid.

That losing result is not exceptional. It is a normal concurrency outcome and should stop before any downstream creation call.

This is stronger than reading again because the predicate and the update are evaluated atomically by the database. There is no application-level gap between “still open” and “now mine.”

The claim is a state, not a boolean trick

Once a claim exists, the domain has an in-progress state whether or not the schema calls it that. Treating it explicitly improves the design.

The workflow needs to answer:

Can a user retry while a claim is fresh?
Which failures can safely release the claim?
When is a claim considered abandoned?
Can another caller take over an abandoned claim?
What happens if the process fails after downstream creation?

A practical rule is to release ownership only when the system knows that no durable side effect exists. If downstream creation fails before producing a record, clearing the claim can make a retry safe. Once a durable result may exist, blindly clearing the claim risks creating another one.

A timeout is recovery policy, not exactly once

A bounded stale-claim timeout prevents an interrupted process from blocking the workflow forever. A new caller may take over only if the stored claim and timestamp still match what it read, so competing recovery attempts cannot both win.

That solves abandoned ownership before the side effect. It does not solve every crash window.

Suppose the downstream service successfully creates a record and the process dies before the parent records completion. After the timeout, replaying the operation could create a second record. The conditional claim narrowed the risk, but it did not create a distributed transaction.

For that boundary, choose an additional mechanism according to the cost of duplication:

Pass a stable idempotency key to the downstream operation.
Record an outbox message in the same transaction as the claim.
Make downstream creation upsert by the originating command identity.
Reconcile incomplete claims against downstream records before replay.

The honest claim is “one winner during concurrent admission,” not “exactly once under every failure.”

Test the overlap, not two sequential calls

A concurrency fix deserves a test that opens the original race window deliberately.

Hold the first caller inside downstream creation. While it is paused, submit the same command again and also submit a competing choice. Then release the first caller.

The useful assertions are concrete:

The downstream creation service was called once.
One winner completed.
Both competing calls received a clear losing result.
The parent stored one selected result.
Other candidates moved to their expected terminal state.

Add two recovery tests as well. First, make downstream creation fail before producing anything and prove that a retry can acquire the released claim. Second, seed a fresh claim and an expired claim, proving that the fresh claim blocks while the expired one can be reclaimed.

This test shape is more valuable than sending two tasks and hoping their timing overlaps. A controlled pause makes the race deterministic and keeps the assertion focused on the contract.

A compact design checklist

Before shipping a command that crosses a data boundary:

Identify the first irreversible side effect.
Put the ownership decision before it.
Use one conditional database write, not a read-then-write promise.
Treat zero affected rows as a normal loser.
Release only when no durable effect exists.
Define stale ownership and takeover semantics.
Add idempotency or reconciliation for the post-side-effect crash window.
Test with a deliberately paused winner and active losers.

The broader principle is not limited to any framework. Checks describe observations. Conditional writes grant ownership. When a workflow can create something you cannot casually undo, that distinction is part of correctness.

Test the Owner, Not the Teardown

Tue, 20 Oct 2026 17:41:25 +0000

Flaky lifecycle tests often produce a tempting diagnosis: the cleanup code must be unreliable. Sometimes that is true. Sometimes the test is asking a framework harness to prove a narrower ownership contract, and the harness is free to finish work on a different schedule.

That distinction matters in interactive server-side UI systems. A component may subscribe to live updates, start a timer, register an observer, or attach a callback. The resource needs a clear owner and a reliable release path. But the test for that contract should not depend entirely on whether a whole rendered tree has completed teardown at one particular instant.

The shape of the failure

Consider a header component that subscribes to a process-local notification service. A child pop-up also owns a separate subscription. The component test renders the tree, publishes an update, observes the visual change, disposes the test context, and immediately expects the global subscription count to be zero.

That sounds reasonable. It is also broader than the claim we really want to prove.

Under a full test-suite load, the notification can overlap a render. The harness teardown call may return while the renderer still has a queued batch. At that instant the header might not yet have received its disposal callback. The non-zero count is therefore ambiguous: either the header leaked, or the harness has not disposed it yet.

A test with two possible explanations is a weak regression guard.

Waiting is not the same as proving

The first instinct is usually to add a retry window: wait for the subscription count to reach zero, perhaps for a few seconds.

That is appropriate when the product contract is genuinely eventual. It is not a universal cure for lifecycle tests. If the harness has left the component alive, waiting merely spends more time observing the wrong boundary. The test remains dependent on incidental scheduling and can still fail without a cleanup defect.

The key question is not, “How long should we wait?” It is, “Which object owns the resource, and what exact behaviour are we trying to prove?”

Put the assertion at the ownership boundary

The stronger test calls the owning component's disposal contract directly, on the correct renderer context, and checks only the resource that component owns.

If the header owns one subscription and a still-rendered child owns another, disposing the header should reduce the count by one. Expecting zero would incorrectly make the header test responsible for the child's lifetime as well.

That narrower assertion is not weaker. It is more precise:

the owner releases its resource;
an independently owned resource is not silently claimed by the parent test;
the result does not depend on whole-tree teardown timing; and
removing the owner's cleanup call makes the test fail consistently.

That last point is especially valuable. A small mutation check—temporarily disabling the cleanup call—shows whether the test detects the regression it claims to detect. If the test still passes, it is probably measuring something else.

Production code still needs lifecycle discipline

A focused test does not excuse fragile implementation. Cleanup should normally be idempotent because framework callbacks, navigation, error handling, and explicit shutdown can converge on the same release path.

The object should also refuse to acquire new resources after disposal. An asynchronous load may resume after the component has gone away. If its continuation subscribes again, a perfectly correct earlier disposal becomes irrelevant because nothing will release the new subscription.

The same reasoning applies beyond subscriptions. Failed in-flight loads should close or abandon temporary buffers. Retained arrivals should have a sensible bound. Work dispatched to another recipient should not accidentally carry ambient request state from the publisher. These are all lifecycle questions: who owns the state, when does ownership end, and what context is allowed to cross the boundary?

Keep two layers of evidence

Direct ownership tests and integration tests answer different questions.

An owner-level test asks: when this component is disposed, does it release what it owns, and can it remain released?

An integration test asks: does navigation, circuit shutdown, or framework teardown actually invoke the right lifecycle path across the rendered tree?

Both matter. The mistake is using only the second, broad test as proof of the first, narrow contract. When the broad test fails, you cannot tell whether ownership or orchestration is broken.

Separating the layers improves diagnosis. A direct test failure points toward the owner. An integration-only failure points toward wiring, scheduling, or framework interaction. The test suite becomes a map of contracts instead of a collection of timing guesses.

A practical checklist

For each subscription, timer, observer, or callback:

Name the owner explicitly.
Make release safe to call more than once.
Prevent acquisition after the owner is disposed.
Test the owner's release contract directly.
Give child-owned resources separate coverage.
Keep one integration test for the framework path.
Prove the test's sensitivity by breaking cleanup locally and seeing it fail.

The trade-off is a few more focused tests and slightly more explicit lifecycle code. In return, failures become actionable. You know whether the owner leaked, the child still legitimately owns something, or the framework has not completed teardown.

Reliable tests do not merely wait longer. They make ownership visible.

Unlocking Static Polymorphism in C# 11: Static Abstract Interface Members

Mon, 19 Oct 2026 15:15:36 +0000

For years, C# interfaces were limited strictly to instance members.

If you wanted to define a contract requiring a class or struct to implement a static method like a string parser or a factory method you had to rely on reflection, runtime type checks, or messy workarounds.

C# 11 changed this by introducing static abstract and static virtual members in interfaces (Microsoft Learn, 2025).

What Does It Look Like?
Consider the built-in IParsable interface from the .NET class library:

public interface IParsable<TSelf> where TSelf : IParsable<TSelf>
{
    static abstract TSelf Parse(string s, IFormatProvider? provider);
}

Any type implementing IParsable (such as int, Guid, or DateTime) must provide a concrete implementation of this static Parse method.

Why Are They Useful?
Before C# 11, interfaces could only enforce behavior on object instances. Allowing static abstract members solves several everyday C# design challenges:

Type-Safe Factories and Parsers: You can write generic methods that
rely on types to create or parse themselves, completely eliminating
the need for slow runtime reflection (Almada, 2023).
Compile-Time Polymorphism: The compiler resolves static interface
calls at compile time, ensuring maximum performance with zero runtime
overhead (Microsoft Learn, 2025).
Clean Contract Enforcement: Domain models can cleanly enforce that
implementing types provide specific static builder or creation
methods.

A Simple Code Example
Here is how you can write a straightforward generic method that parses any IParsable type:

public static T ParseValue<T>(string input) where T : IParsable<T>
{
    return T.Parse(input, null);
}

int number = ParseValue<int>("123");
DateTime date = ParseValue<DateTime>("2026-06-06");

By adding the constraint where T : IParsable, the compiler guarantees that T has a static Parse method, making your generic utility code both clean and 100% type-safe.

References Almada, A. (2023). Generic math in .NET. Antão Almada
Blog. https://antaoalmada.dev/posts/Generic-math-in-dotnet/
Microsoft Learn. (2025). Generic interfaces (C# Programming Guide).
Microsoft Corporation.
https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/generics/generic-interfaces

Hand Off Intent, Not Authority

Sun, 18 Oct 2026 08:36:51 +0000

Moving a user from one application host to another often looks harmless. A button opens a browser, the user continues, and the original client waits for them to return.

Architecturally, that is not merely navigation. It is a trust-boundary decision.

This becomes especially important when one user experience runs across several .NET hosts: perhaps an ASP.NET Core site, a Blazor WebAssembly client, and a .NET MAUI hybrid app. The shared components may look identical, but the hosts do not own the same secrets, sessions, callbacks, or security guarantees.

The lesson is simple: when a workflow crosses hosts, hand off intent, not authority.

The tempting shortcut

Suppose a client has already loaded an order-like resource and can display the next sensitive action. It is tempting to let every host render the same provider form or carry the current access proof into the browser.

That preserves continuity, but it also widens the boundary. A client that only needed to display state may now receive signed fields, transaction details, callback assumptions, or a reusable proof. Putting any of that into a query string or fragment creates more problems: URLs are copied, logged, cached, placed in browser history, exposed to extensions, and sometimes sent as referrers.

Shared UI does not imply shared authority. Reuse the presentation and state model where it helps, but make each host's capabilities explicit.

A narrower handoff

A safer design gives the less-trusted client one small capability: open a fixed public entry point on the authoritative host.

The destination should be deliberately boring. It should not contain an order reference, email address, one-time code, access token, signed provider fields, or a claimed outcome. It should have no dynamic query string or fragment. It communicates only this intent: “the user wants to continue this workflow on the web.”

The authoritative host then starts again from its own security context. It asks for the identifiers appropriate to the workflow, performs anti-forgery checks, verifies ownership through its normal mechanism, and only then exposes the sensitive action.

That separation gives each statement a precise meaning:

Opening the browser is navigation.
Proving ownership grants access in the destination host.
Starting the action is a separate command.
A callback or authoritative read confirms the outcome.

None of those statements is allowed to stand in for another.

Treat public configuration as an API

Installable browser clients need runtime configuration, but a generated client configuration document is still a public API. Do not serialize a server configuration tree and hope that only safe values happen to be present.

Build a small allowlist instead. For this kind of handoff, the browser might receive an enablement flag and a reviewed public origin. That is enough. Return the document with a no-store policy so a stale capability does not linger after an operational change.

Validate the destination before the application starts. Require the exact shape you intend: HTTPS, a root origin, no embedded credentials, no path, no query, no fragment, and no unexpected local or alternate-port destination. Keep the feature disabled when configuration is absent. If someone explicitly enables it with an invalid value, fail startup with a value-free error rather than echoing the bad input into logs.

Failing closed here is not pessimism. It turns configuration from ambient text into an enforceable security boundary.

Make the destination defensive too

The source client should generate a clean URL, but the destination should not trust that promise.

If someone arrives with a query string, canonicalize to the fixed entry before rendering. Apply no-store and a restrictive referrer policy. Do not pre-fill sensitive identifiers from URL input. Start with the ordinary ownership flow and its existing anti-forgery protection.

This matters because links escape their intended callers. They are bookmarked, pasted into messages, opened by scanners, and reconstructed by users. A robust boundary remains safe even when the source is not your application.

Failure must remain boring

A browser launch can fail for mundane reasons: platform policy, missing handlers, lifecycle changes, or an exception from the native shell. None of those failures should mutate domain state.

The client should report only that the launch did not happen. It should not create the sensitive form, mark work as started, grant access, or imply success. Concurrent clicks can be collapsed while an open attempt is running, but a failed attempt should be retryable.

This is a useful design test: if navigation failure requires compensation, the handoff probably carried too much authority.

Test the negative space

Most happy-path tests prove that a button eventually opens the right page. Boundary tests need to prove what cannot happen.

Useful tests include:

the capability is off by default;
malformed enablement and invalid destinations fail safely;
the client opens only the fixed path;
the URL contains no proof or private state;
each host renders only its intended action;
public configuration contains only allowlisted fields;
the web entry removes unexpected query data before rendering;
caching and referrer protections are present;
ownership and anti-forgery checks happen in the destination;
launch failure changes no workflow state; and
repeated clicks do not create duplicate launches.

These are negative properties. They are easy to lose during refactoring unless tests name them directly.

The trade-off is honest friction

Fresh ownership proof adds a step. A dedicated entry route, host-specific capability registration, and configuration validation add code. The boundary also needs maintenance as new hosts appear.

That cost buys something valuable: the sensitive operation stays with the host designed to own it. The other clients remain simpler, public configuration stays small, and failures have a narrow blast radius.

When reviewing any cross-host workflow, write down four things: the exact destination, the data allowed to cross, the authority that must be re-established, and the state a failed launch may change. If those answers are vague, the implementation probably is too.

Intent can cross a boundary. Authority should have to earn its way back in.

Soft Delete Is a Model Contract, Not a Repository Habit

Sat, 17 Oct 2026 05:45:59 +0000

Soft deletion often begins innocently: add an IsDeleted flag, remember to exclude retained rows, and move on. That works until the application grows into several modules, several DbContext types, and configuration spread across assemblies.

At that point, soft deletion is no longer a local query concern. It is a visibility boundary for the complete EF Core model.

The difference is practical. A repository predicate protects the query paths that remember to use it. A model contract protects ordinary reads by default and makes exceptional reads visible in code review.

The dangerous partial success

Imagine a shared base context that scans the entity types it knows and installs a query filter. Later, a module applies another configuration assembly and adds more entities. The base code is correct for the model it saw, but its timing was wrong. Some retained rows are hidden and others are returned normally.

This failure is uncomfortable because both sides look reasonable in isolation. The entity has the deletion marker. The shared context contains filter code. A few tests pass. Yet the effective model has uneven visibility rules.

The lesson is to configure cross-cutting rules at a lifecycle point where the model is complete. An EF Core model-finalising convention can inspect every registered type after the contexts and configuration assemblies have contributed their mappings.

For each root entity carrying the deletion marker, the convention can add the standard predicate. Owned types follow their owner, and derived types inherit the root filter. Existing filters must be preserved: combine with an anonymous filter, or add a separate named filter when the model uses named filters. Any always-visible audit type should be an explicit, narrow exception rather than an accidental omission.

Test the effective predicate

Checking that a filter exists is too weak.

An entity might have an unrelated visibility filter. It might even mention the deletion marker beneath a logical OR:

not deleted OR visible to this user

That expression can still admit a retained row. The required property is stronger: not deleted must be a mandatory conjunct of the effective filter.

A reusable model audit can enumerate all root entity types with the marker, exclude only documented exceptions, and fail if any type lacks that mandatory predicate. It should have tests against itself: prove that it rejects an unrelated filter and rejects the OR case. Otherwise the audit risks becoming a green check that does not guard the boundary it names.

Provider-backed tests add the next layer of evidence. Insert one active row and one retained row. Show that normal queries return only the active row, while an explicit bypass can retrieve both. This verifies the generated query and provider behaviour rather than only evaluating a compiled expression in memory.

A correct filter changes workflows

When global filtering becomes consistent, previously accidental behaviour may break. That is useful information.

Restoration is the clearest example. Suppose a retained row still owns a unique business slot. A normal lookup cannot see it, so a naive create path tries to insert a replacement and collides with the database constraint.

The solution is not to weaken the global filter. Give the restoration path an explicit way to ignore model filters, then make its intention precise:

creating into a slot held by a retained row restores that same row;
editing a different active row into the reserved slot is refused;
failure leaves both rows unchanged;
historical or restoration reads are the only paths allowed to bypass the boundary.

Putting the bypass on a named specification or dedicated query object is easier to review than scattering IgnoreQueryFilters() through services. The name communicates why the exception exists, and focused tests can pin its scope.

Watch required navigations

Global filters also interact with relationship shape. If a required navigation uses an inner join and the principal is filtered out, the dependent can disappear from a query even when the dependent itself is active.

That may be correct, but it should be a decision.

An inventory of required relationships that cross filtered and unfiltered types gives reviewers a bounded list of hazards. For each one, choose deliberately: align filters on both sides, make the navigation optional, change the query shape, or accept and test the disappearance.

This is one reason metadata-driven verification scales better than a long list of hand-written repository tests. The model can tell you what exists now, including a new entity or relationship added by a future module.

A practical verification stack

A durable soft-delete boundary has four layers:

Apply the convention after the model is complete.
Audit every soft-deletable root for the exact mandatory predicate.
Keep bypasses explicit and limited to restoration or historical use.
Run real-provider tests for visibility, restoration, uniqueness, and required-navigation behaviour.

There is a cost: more model infrastructure, a deliberate exception list, and tests that can expose old assumptions. Some teams may decide that hard deletion or temporal tables better match particular data. The point is not that soft deletion is always right.

The point is that, once chosen, it must behave like one coherent contract.

The most valuable outcome is not the filter itself. It is that a future entity cannot quietly arrive outside the boundary—and that exceptional access reads like an exception.

Queued Work Is a Snapshot, Not the Truth

Fri, 16 Oct 2026 05:43:57 +0000

Background work is usually introduced to make a system more reliable. We persist an intent, let the request finish, and deliver the external side effect later. That protects the user-facing path from temporary provider failures and gives us room for retries.

It also creates a time gap.

Inside that gap, the world can change. A task can be completed. A new task can appear. A recipient can lose access. A preference can change. Another worker can advance the same operation. The queued record may still be durable and validly serialized while the message it would produce is already wrong.

The lesson is simple: queued intent is evidence about an earlier snapshot. It is not timeless authority.

Store the promise, not the presentation

Suppose a service groups several outstanding items into one reminder. The tempting design is to serialize the titles, amounts, names, and finished message into an outbox row. Delivery is then easy: deserialize and send.

That convenience turns the row into a stale cache of user-facing truth. It may also retain more sensitive data than the queue needs.

A safer durable record can be much smaller. Keep the routing identity, recipient identity, sequence, source, and a deterministic fingerprint of the complete set the message was created for. The fingerprint represents the promise: “this message describes exactly this observed set.”

The display payload is rebuilt later from authoritative state. The durable row says what snapshot was intended without pretending that its old presentation is still current.

Rebuild from the complete current set

At execution time, re-read what the authoritative source currently exposes to the recipient. Then run the same grouping rules again and compare the resulting fingerprint with the stored fingerprint.

Why the complete set? Because stale work changes in two directions.

The obvious case is subtraction. An item was completed or removed after the reminder was queued. The old message now overstates what is outstanding.

The less obvious case is addition. A new item appeared after the reminder was queued. If the worker checks only the item keys remembered by the row, every remembered item may still be valid. The worker can still send a message that understates the current request.

Reconstructing the whole set catches both. If the current fingerprint differs, the old intent is superseded. Stop it. Let the current state produce a new intent under a new identity.

Keep authorization in the authoritative read

The background worker should not invent a second, simplified version of the authorization and status rules used by the foreground feature. That duplicate will drift.

Prefer a shared underlying read path with an explicit recipient parameter. The interactive request and the delayed worker should agree on what the recipient is currently allowed to see and how current status is mapped.

This also makes an important distinction possible. “Nothing remains” is not the same as “the recipient is no longer authorized.” Both may yield an empty visible set, but they mean different things operationally and in an audit trail.

Completion can finish the old intent. Revocation should stop disclosure for a security reason. A missing source integration is different again: it is usually a retryable deployment fault, not evidence that the work is complete.

Model more than send or fail

A robust recheck tends to produce several outcomes:

Send: the complete current snapshot still matches, preferences allow delivery, and the operation sequence is current.
Stop as completed: the intended work no longer exists.
Stop as changed: the set still exists but is no longer the set the queued message promised to describe.
Stop as revoked: the recipient no longer has authority.
Stop as superseded: a later sequence has already advanced the operation.
Defer: authoritative evaluation is temporarily unavailable.

These outcomes can feel verbose compared with a Boolean. That verbosity is useful. It prevents a temporary infrastructure gap from being filed as success, and it prevents a security revocation from being misreported as ordinary completion.

Test addition as carefully as subtraction

The most valuable regression test in this pattern is often the one teams forget: add something after the row is written.

A focused suite should cover an unchanged set, a removed item, an added item, an empty set, revoked authority, changed preferences, a superseded sequence, and an unavailable source. It should also prove that each evaluation performs a fresh authoritative read rather than accidentally reusing stored data.

These tests do more than exercise branches. They define the temporal contract of the workflow: which facts may age, which facts must be refreshed, and which outcome owns each kind of change.

The trade-off is real

This design adds a database read at the most sensitive point, deterministic reconstruction, fingerprint maintenance, and more explicit state transitions. At high volume, that cost deserves measurement. Poorly indexed rechecks can simply move a reliability problem into the database.

The benefit is not that fingerprints make distributed systems magically consistent. They do not. There is still a race between the final read and the external side effect, and systems with stricter requirements may need provider idempotency, transactional boundaries, or domain-specific reservations.

The narrower claim is valuable enough: a delayed worker should not knowingly act on an obsolete snapshot when it can cheaply revalidate current truth.

A practical review checklist

When reviewing delayed email, push, webhook, export, billing, or approval work, ask:

What exact snapshot did this row promise to act on?
Does the queue store minimal identity or stale presentation data?
Can the worker re-read the full authoritative set?
Are additions detected as well as removals?
Are completion, revocation, supersession, and temporary unavailability distinct?
Is the external side effect itself idempotent or otherwise bounded?

Durability keeps work from disappearing. Revalidation keeps durable work from becoming confidently wrong.

Isolation Is Sometimes a Feature, Not a Smell

Thu, 15 Oct 2026 06:01:03 +0000

Two projects expose similar helpers. One has no project references. It is missing from the solution most developers build every day. The obvious reaction is understandable: share the code, add the reference, and bring the lonely project back into the fold.

That cleanup can be exactly wrong.

A recent architecture correction I reviewed was a useful reminder that repository shape is not the whole system. Build agents, installed workloads, runtime origins, signing steps, and release pipelines are part of the architecture too. An isolated .NET MAUI head looked neglected when viewed only from the solution file. Viewed from its release path, the isolation was load-bearing.

Start With the Delivery Graph

Before deduplicating across project boundaries, ask how each project is actually built and shipped.

In the case I reviewed, a server-focused solution deliberately excluded the mobile head. That kept routine server builds from requiring mobile workloads on every developer machine and CI runner. The mobile app was still real software: a separate pipeline restored, built, signed, and released it independently.

Adding a shared project reference would therefore do more than remove a few repeated lines. It would expand the mobile restore graph and couple its release path to a project the mobile pipeline had never needed. Adding the mobile project to the server solution would impose a different cost in the other direction: machines building the server product would now need tooling they did not otherwise use.

Neither consequence is visible in a tidy dependency diagram. Both matter in production delivery.

Similar Code Can Encode Different Assumptions

The same review contained two link resolvers that appeared ripe for consolidation. The browser implementation derived an external base address from its hosting origin. That was valid because the browser app was served by the web host.

The mobile app ran inside an embedded web view. Its internal origin did not identify the external service it needed to reach. Reusing the browser resolver would not create elegant sharing; it would import an invalid environment assumption.

This is a useful test for any proposed abstraction: are the implementations merely similar in syntax, or are they equivalent in authority and context?

Imagine a browser client and a desktop client that both produce a download URL. The browser can safely resolve a relative path against the page origin. The desktop client may need an explicitly configured service endpoint. A common interface can still be useful, but a common implementation may be actively misleading.

Duplication is not automatically good. It is sometimes the smallest honest representation of two different worlds.

Guard the Constraint—and Its Reason

Documentation corrected the misleading story, but the stronger improvement was an architecture test suite.

The tests did not merely assert that the mobile head had no project references and stayed outside the server solution. They also checked that the separate mobile build path still existed. That second half changes the character of the rule.

Without it, the test says: “keep this isolated forever.”

With it, the test says: “keep this isolated while this independent delivery path remains true.”

That is a healthier architectural guard. It protects a decision without pretending the decision is timeless. If the separate pipeline disappears, the guard fails and asks maintainers to reconsider the boundary. The test becomes executable rationale rather than fossilized preference.

This pattern generalizes well. If a component must stay dependency-free because it is loaded by a restricted host, test both the dependency rule and the existence of that host. If a migration assembly must remain separate because tooling discovers it independently, guard both the assembly boundary and the discovery path.

The Trade-Off Is Still Real

Deliberate isolation has costs.

Separate helpers can drift. A visual shell copied for a second head may receive fixes later. Architecture tests add maintenance, and source-shape checks can become brittle if they assert incidental text instead of meaningful structure.

The answer is not to ignore those costs. It is to compare them with the coupling being avoided.

Prefer the smallest duplication that preserves the boundary. Keep behavioural contracts aligned where the behaviour truly is shared. Document the assumptions that must differ. Review the boundary when release topology changes. And avoid broad claims such as “this project shares nothing” when the important truth is more precise: it ships independently and intentionally owns a narrow set of platform-specific choices.

A Practical Review Checklist

Before merging apparently duplicate code across application heads, ask:

Which pipeline builds and releases each head?
What workloads and SDKs does each build environment guarantee?
Will a new reference expand the restore or signing boundary?
Do the implementations rely on different origins, storage, identity, or lifecycle rules?
Can we test the constraint and the continuing fact that justifies it?
What event should trigger reconsideration of the decision?

These questions turn “DRY versus duplication” into a more useful discussion about operational ownership.

Architecture Includes the Way Software Leaves the Repository

The most valuable lesson for me was a leadership one: do not label unusual structure before tracing its history and delivery path.

An isolated project may be forgotten. It may also be a carefully bounded product whose release assumptions are invisible from the main solution. We should investigate before simplifying, explain the decision in language that cannot be mistaken for neglect, and encode the rationale where future changes will encounter it.

Clean architecture is not the fewest projects or the fewest repeated lines. It is a system whose dependencies match the realities of how it runs and ships—and whose exceptions are specific, reviewable, and allowed to expire.

A Passing Test Can Still Prove Nothing

Wed, 14 Oct 2026 06:12:33 +0000

Some of the most misleading tests are not flaky, slow, or obviously incomplete. They are fast, deterministic, and green.

They also pass for the wrong reason.

That is especially dangerous in fault-tolerant code. A test may claim that a failed dependency is contained, a fallback runs, or an established workflow continues. Yet its assertion may observe an outcome that can occur both before and after the recovery boundary. The suite reports confidence while the behaviour named by the test remains unproved.

The false-positive shape

Imagine a dispatcher with an optional policy source in front of an established workflow. The intended behaviour is straightforward:

Ask the policy source whether the old workflow should stand down.
If that optional source fails, contain the fault.
Continue into the established downstream path.

The unit test configures a policy source that throws. It also uses a strict downstream test double that throws if reached, because the rest of that workflow is outside the test's concern.

Then it asserts only that dispatch throws an exception.

At first glance, this can feel reasonable. An exception from the strict downstream dependency appears to prove that execution continued. But the same broad assertion also accepts the earlier exception from the policy source. If the recovery logic is deleted, the first exception simply escapes and the test remains green.

The assertion recognizes the shape of the final outcome, not the path that produced it.

Test the claim, not the punctuation

The claim is not “an exception occurs.” The claim is “a fault at this boundary does not stop progress into the established path.”

That distinction changes what the test must observe.

A useful test needs a stable witness on the far side of the boundary. Depending on the design, that witness could be:

a recorded call to the downstream collaborator;
a domain result that only the fallback path can produce;
a distinct exception identity from a deliberately strict dependency;
a state transition committed after the failed operation; or
an emitted event that occurs only after recovery has completed.

The specific technique matters less than the causal guarantee. The witness must be impossible—or at least deliberately difficult—to observe if execution stops at the failure being contained.

In the example above, the corrected test distinguishes the downstream failure from the policy-source failure. It therefore passes only when execution crosses the recovery boundary. A recording test double would also work and may be clearer when the downstream call itself is the contract.

Why mutation testing helped

Code coverage could not expose this weakness. Both the recovery code and the test might execute during the normal run. Coverage tells us which lines ran; it does not tell us whether an assertion depended on their behaviour.

Mutation testing asks a sharper question: if a meaningful piece of behaviour is changed or removed, does a test fail?

Removing the recovery behaviour created a surviving mutant. That was valuable evidence. It did not necessarily mean the production design was wrong. It meant the suite could not distinguish the intended implementation from a broken one.

This is one of mutation testing's best uses: finding assertions that observe something adjacent to the claim rather than the claim itself.

You do not need mutation tooling to apply the same reasoning in review. Mentally invert the behaviour:

If the catch disappeared, would the test fail?
If the fallback were skipped, would the test fail?
If execution stopped one step early, would the test fail?
Could a different branch produce the same asserted result?

If the answer is uncomfortable, look for a witness beyond the boundary.

The trade-off: path awareness without brittleness

Path-sensitive assertions carry a real cost. A test that verifies every internal call order can become coupled to implementation detail and obstruct harmless refactoring. Replacing one collaborator with another should not require rewriting an entire suite if the observable contract is unchanged.

The answer is not to avoid path awareness altogether. It is to choose the smallest stable witness that represents the behaviour promised by the test.

Prefer domain-visible evidence when it exists: a returned decision, a committed state, a durable message, or a recorded recovery status. Use collaborator verification when crossing that collaborator boundary is itself the contract. Use exception type or identity when a strict test double intentionally marks progress, but make that intent explicit so a future reader understands why the exception matters.

This produces a useful hierarchy:

Assert the externally meaningful result when it uniquely proves recovery.
Assert a durable checkpoint when the final result is produced asynchronously.
Assert a boundary interaction when progress across that boundary is the behaviour under test.
Use a distinct failure identity as a narrow witness when a strict dependency deliberately terminates the test.

The closer the witness is to the real reliability contract, the less brittle the test will be.

A practical review habit

When reading a test name, underline the verb: continues, retries, falls back, persists, publishes, or rejects. Then find the assertion that proves that verb happened.

If you can only find evidence that something threw, returned, or logged, ask whether the same evidence could appear before the named behaviour occurred.

Green is not the standard. Discrimination is. A useful test must distinguish the system we intended from a nearby broken version.

For fault-tolerance tests in particular, do not merely observe the aftermath of a failure. Prove that the system crossed the boundary it promised to survive.

Tuesday Coding Tip 26 — JSON (de)serialization in C#

Tue, 13 Oct 2026 09:59:00 +0000

In need of a JSON (de)serializer in C#? One option could be to use the built-in System.Text.Json functionality. Probably the most popular way is to use the Newtonsoft.Json library which has a richer feature set while maintaining overall simplicity.

Things are as simple as having a class with a bunch of public attributes and calling serialize on it. Those attributes don’t even have to be trivial types — anything from DateTime to HashSet can be easily handled.

Deserialization is similarly easy — if a key is present, it will be deserialized. If not, the default value for the attribute will be picked instead.

using Newtonsoft.Json;

namespace NetSandbox;

public class ExtendedValues
{
    public long ErrorCode { get; set; }

    public string Message { get; set; } = string.Empty;
};

public class Property
{
    public string Value { get; set; } = "";
};

public class Protocol
{
    public long Version { get; set; } = -1;

    [JsonProperty("extended", NullValueHandling = NullValueHandling.Ignore)]
    public ExtendedValues? ExtendedValues { get; set; } = default;


    [JsonProperty("machineGuid")]
    public Guid MachineGuid { get; set; }

    public List<Property> Properties { get; set; } = new List<Property>();
};

public static class Program
{
    public static void Main()
    {
        Protocol schema = new()
        {
            Version = 1,
            MachineGuid = Guid.NewGuid(),
            Properties = new List<Property> {
                new Property {
                    Value = "hello"
                },
                new Property {
                    Value = "world"
                }
            }
        };

        var json = JsonConvert.SerializeObject(schema);
        // {"Version":1,"machineGuid":"156717fd-0904-47af-bcb8-ad74d23b9cc7","Properties":[{"Value":"hello"},{"Value":"world"}]}

        var obj = JsonConvert.DeserializeObject<Protocol>(
            """{"machineGuid": "156717fd-0904-47af-bcb8-ad74d23b9cc7"}""");
        // obj.Version contains -1
        // obj.MachineGuid containts "156717fd-0904-47af-bcb8-ad74d23b9cc7"
        // obj.ExtendedValues is null
        // obj.Properties is empty list
    }
}

If you need to, you can use annotations to for example customize the name of the serialized property or whether it will be serialized when it is null.

Extra thought: I originally wrote this post in late 2023. Since then, many people would probably advice you System.Text.Json on the merit of being faster and getting more and more on-part with Newtonsoft on each major release. Since we did a switch to it some time ago, I cannot wholeheartedly recommend it - it is great for simple use cases, but once you have some data structure that evolved over time and you need to be lenient of what you accept over wire and strict in what you send, working with System.Text.Json is a bigger pain, especially around NullValueHandling and DefaultValueHandling.

A Route Is Not a Feature Until Someone Can Reach It

Tue, 13 Oct 2026 07:01:11 +0000

Modern applications are often assembled from modules. That is good for ownership, deployment boundaries, and keeping large codebases understandable. It also creates a subtle user-experience failure mode: a page can compile, carry a valid route, pass its local tests, and still be effectively absent because no one can discover it from a real entry point.

This is not primarily a visual-design problem. It is an architecture-contract problem.

Routable is not reachable

Imagine an administrative application with pages spread across two modules. The team already has a test that scans routed pages and checks that each one appears in a navigation catalogue. The test is green, so the navigation surface looks covered.

Later, someone discovers that the scan only walks one module. The second route tree was outside its boundary. Pages there could be added indefinitely without the test knowing they existed.

That is the first important lesson: a completeness check is only as complete as its discovery mechanism.

When the scan is expanded, it finds an entry screen that has documentation and valid follow-on steps, but no link from the application itself. The workflow exists technically. Operationally, it begins with “type this URL.” That is not a usable feature contract.

Define a genuine entry point

The tempting fix is to accept any reference to the route. Perhaps another page links to it. Perhaps it appears on a tab rail. Perhaps a help article mentions it.

Those references are not equivalent.

A help article explains a feature; it is not application navigation. A link on a neighbouring screen can be useful, but it may make discoverability depend on an accidental journey. A tab rail is particularly deceptive: it helps someone move within an area only after they have reached one of its pages. It cannot prove that the area itself has an entrance.

The architectural rule should therefore name the user-facing property you actually want. For example:

Every static administrative workflow page must be represented by a discoverable entry in the primary hub available to its entitled audience.

That sentence is stricter than “the route is mentioned somewhere,” and that is precisely why it is useful.

Test pages, not strings

Route graphs have legitimate shapes that a simple string search will misclassify.

A parameterised detail page is usually reached from a list or search result. Giving every detail route a top-level card would be noisy and misleading. The test can classify routes containing parameters as downstream pages rather than entry pages.

The reverse case also matters. One page may answer on two route aliases for compatibility. Requiring two navigation cards would duplicate the same destination. The unit of the contract is the page, with at least one discoverable canonical route—not every literal route declaration.

These distinctions keep the test strict without making it simplistic.

Make the scan fail honestly

Source-scanning tests have a dangerous failure mode: they can pass after discovering nothing. A changed directory, glob, parser, or build layout can turn the result set into an empty collection, after which every “all pages are covered” assertion becomes vacuously true.

Add a coarse lower bound to the discovered page count. It does not need to encode the exact inventory. It only needs to make a broken scan conspicuous. Pair that with a useful failure message that lists uncovered entry pages and explains the intended remedy.

Exceptions deserve the same discipline. Sometimes an exception is legitimate, but an exemption list easily becomes a hiding place. Store a reason beside each exception, keep the list narrow, and assert that every exception still corresponds to a real uncovered case. Once navigation is fixed, the stale exception should fail the next test run.

That turns exceptions into temporary, reviewable decisions rather than permanent silence.

Align visibility with authorization

Navigation and authorization answer related but different questions.

Navigation visibility asks, “Should this person be offered this destination?” Authorization asks, “May this request proceed?” A hidden card is not a security boundary. Someone can still follow a saved link or construct a request directly.

The useful contract is alignment: the navigation entry should use the same entitlement expressed by the destination policy, while the page or endpoint continues to enforce that policy independently.

This check often exposes ambiguity. If a destination has only broad authentication while its navigation card is restricted to a privileged audience, do not quietly declare the card to be protection. Flag the mismatch for an explicit security decision. Navigation work should reveal authorization uncertainty, not accidentally resolve it.

The trade-off is real

A strict hub contract has costs. The catalogue grows. New pages require deliberate placement and wording. A hub can become crowded if every capability is presented at the same level.

The alternative, however, is not free. A loose rule produces accidental journeys, invisible capabilities, and tests that certify the presence of links without certifying usable discovery.

The practical balance is to keep the entry-point contract strict while allowing the interface to group, search, filter, and progressively disclose destinations. The architecture test should protect reachability; the visual design can protect clarity.

A small checklist

For a modular routed application:

Inventory every route tree, not only the first one the test was written for.
Classify static entry pages, parameterised downstream pages, and route aliases.
Identify the navigation roots users can actually reach.
Require every entry page to appear from an appropriate root.
Add a minimum discovery count to catch broken scans.
Make exemptions explicit, reasoned, narrow, and self-cleaning.
Align link visibility with destination authorization, while enforcing security at the destination.

The deeper lesson is that architecture includes the path a person can take through the system. If a feature has no honest entrance, its route is an implementation detail—not a delivered capability.

Don’t Turn Delegated Access Into an Identity Oracle

Mon, 12 Oct 2026 06:01:17 +0000

Delegated access often starts with an innocent mismatch.

A person knows an email address. The authorization system knows an account identifier. The obvious bridge is a search box: enter the address, find the account, then grant access.

That bridge can become a privacy leak.

If the screen behaves differently for a known address and an unknown one, every attempt answers a sensitive question: “Does this person have an account here?” An authenticated caller can repeat that question across many addresses. The feature may be correctly authorized for its intended task while still exposing more identity information than the task requires.

The deeper lesson is simple: account discovery is not a necessary prerequisite for delegated access. Identity can be resolved later, at the moment the recipient proves ownership and gives consent.

The convenient design carries a hidden query

Consider a generic workflow in which one person wants to share a limited capability with another.

The direct version usually looks like this:

Enter the recipient’s address.
Search for a matching account.
Show whether a match exists.
Create access against that account.

Authorization to share the resource does not make the lookup harmless. Even subtle differences disclose the answer: different text, a disabled button, a profile preview, an HTTP status, or noticeably different timing.

This is a useful design-review question: what does the caller need to accomplish, and what does the interface reveal merely because it is convenient?

Move identity resolution to acceptance

An invitation workflow changes the order of proof.

The initiator provides an address and the intended scope. The system records an invitation and returns the same public outcome whether the address currently belongs to an account or not. Nothing attempts to answer the account-existence question.

Most importantly, the invitation itself grants no access.

When the recipient follows the invitation, they authenticate. The system compares the account’s confirmed address with the invited address. Only a match may inspect the offer and accept it. The access record is then created against the identity that actually accepted.

That ordering gives the workflow better semantics:

the initiator names a person in a form they genuinely know;
the system does not reveal whether an account already exists;
possession of a link is insufficient on its own;
the recipient proves control of the invited address;
access records consent rather than an assumption made by the initiator.

A token is necessary, but not sufficient

Invitation links are bearer secrets, so their handling deserves the same care as password-reset links.

Persist a one-way hash rather than the raw token. Submit the token in a request body when practical so routine URL logging does not repeat it across server, proxy, and browser records.

Bind the token to the intended identity as well. A forwarded or screenshotted link should not be enough to inspect the offer. Requiring a signed-in account with the matching confirmed address contains that failure mode.

Resending needs a clear contract: mint a new token and invalidate the old one. Otherwise each resend increases the live secrets while the interface still shows one invitation.

Finally, build the link from trusted server configuration. Request-controlled host information should not decide where a live token is sent.

Retry safety belongs in the workflow

Mobile networks fail at awkward boundaries. The server may commit an invitation and send the message while the response never reaches the device.

If pressing the button again creates a fresh invitation, one uncertain response can produce two live tokens. The interface may show only one of them.

A stable command identity lets the server recognize a replay and return the original result without sending again. That identity must describe the request as well as the button press: reusing it with different arguments should be rejected, not silently mapped to an unrelated result.

Delivery outcomes need honest language. A definite rejection differs from an unknown result after handoff. “Unknown” is safer than encouraging a duplicate.

Acceptance changes two facts: the invitation is consumed, and access is created.

Persist those facts together.

If access is written but the invitation remains pending, the token may be accepted again. That can create a second grant that nobody sees. Revoking the visible grant would leave the duplicate active.

One transaction makes the invariant explicit: there is no state in which acceptance succeeded while the invitation is still redeemable.

Re-check the initiator’s authority inside this transition too. Authority can change between invitation and acceptance. An invitation should not outlive the permission that allowed it to be created.

Test the negative space

The most valuable tests are not only happy-path checks. They prove what the workflow refuses to reveal or create:

known and unknown addresses produce indistinguishable initiator results;
an invitation alone authorizes nothing;
a different or unconfirmed account cannot inspect or accept it;
retrying does not send again;
resending invalidates the previous token;
stale initiator authority blocks new access;
repeated acceptance does not create duplicate grants;
consumption and access creation succeed or fail together.

The trade-off is deliberate complexity

This design adds states, expiry, delivery handling, retry receipts, token rotation, concurrency, and tests. It is unquestionably more work than a directory lookup followed by an insert.

The added complexity corresponds to uncertainty the simpler design hides. The invitation makes privacy, consent, identity proof, and atomicity explicit.

The practical takeaway is to inspect every workflow that translates a human-readable identifier into an account. Ask whether the caller truly needs account discovery, or whether identity can be resolved by the recipient at acceptance.

Often, the safer flow is also the more truthful one.

When the Tool Cannot See the Whole Model

Sun, 11 Oct 2026 06:55:17 +0000

Modular architecture creates an uncomfortable class of failure: the application can understand its complete model while design-time tooling sees only a legitimate subset.

That difference is easy to misread as drift. It is also dangerous to dismiss. The useful engineering move is to identify exactly what the tool cannot observe, then relocate each safety check to a boundary with enough context to answer the question correctly.

The warning was real, but its conclusion was wrong

Consider a shared EF Core context that can be extended by optional runtime modules. Each module contributes mappings without forcing the lower-level persistence package to reference every higher-level feature package. That dependency direction is valuable: the shared module remains reusable, and optional features remain optional.

At runtime, the host loads the contributing modules and the complete model is assembled. At design time, the tooling process starts from a narrower package. Loading one contributor directly would create a dependency cycle, so that contributor is absent.

The migration snapshot still represents the complete model. The design-time model does not. A comparison therefore reports a difference and may propose removing an object that is not obsolete at all; it is merely invisible from that process.

The warning accurately says, “these two views differ.” It cannot establish why they differ.

Separate database update from migration authoring

The first mistake would be treating every operation as though it asks the same question.

A database update applies migrations that have already passed review and validation. If a known model subset causes a framework warning to block that operation, a narrowly scoped suppression can be reasonable. The important word is narrowly. The exception belongs in the design-time path that has the structural blind spot, with an explanation of why the complete model cannot be assembled there.

Migration authoring is different. A scaffolder turns its limited view into proposed schema changes. If it cannot see an extension-owned table, a removal operation may look perfectly logical. Suppressing a warning does nothing to make that proposal safe.

So the second boundary needs a stronger invariant: inspect the generated migration operations and fail if they remove, rename, or destructively alter protected extension data. That converts a warning in prose into an executable gate.

This distinction matters. “Allow the known update path” and “trust every future generated migration” are not the same decision.

Keep a complete-model drift check

Once a noisy comparison is suppressed, the obvious risk is hiding real drift. The answer is not to pretend the partial view became authoritative. Keep a separate test that runs in a host where all contributors are loaded, builds the complete runtime model, and compares that model with the snapshot.

Now each check has one clear responsibility:

the design-time update path tolerates the known subset;
the full-model test detects genuine model-to-snapshot drift;
the migration-operation test blocks destructive scaffolding.

This is more precise than relying on one framework signal for three different questions.

Prove the guard is not vacuously green

Negative tests deserve a positive control.

Imagine a test that scans every migration and asserts that none removes a protected table. It passes. Good news, perhaps. But it also passes if migration discovery silently returns an empty collection.

Add a companion assertion that the scan finds the migration that originally created the protected object. If discovery breaks, the positive control fails. The pair proves both that the dangerous operation is absent and that the evidence set is present.

This pattern generalizes beyond migrations. Any test that says “no forbidden item exists” should make you ask whether it would still pass when the scanner found nothing.

Shared process state is another hidden boundary

The same change exposed a smaller reliability lesson. Tests for design-time factories temporarily set a process-wide configuration value. Separate test classes ran concurrently, and one could restore the value while another was still using it. Each class passed alone; together they failed intermittently.

The repair was not another retry. The tests were placed in one non-parallel collection because they share mutable process state.

That is the same ownership principle in miniature: the scope of the resource determines the scope of coordination. A process-wide variable cannot safely be treated as test-local state.

The trade-off is explicit complexity

This approach is not free. There is now a documented exception, a complete-model drift test, a migration-operation guard, a positive control, and serialized tests around shared environment state. Future maintainers must understand why those pieces exist.

But the alternative is false simplicity: a generic warning that blocks legitimate work, generated operations that can target valid data, and flaky tests that disguise the real contract.

The practical rule I keep is this:

When tooling has a structural blind spot, narrow the exception and move safety to executable checks that can observe the complete truth.

Do not silence evidence broadly. Do not force an architectural dependency merely to satisfy a tool. Give each check the context it needs, and make dangerous assumptions fail before they become database changes.

The Weekend After: HeadlessAi Has Entered the Workshop

Sat, 10 Oct 2026 06:54:10 +0000

Last weekend, we introduced some of the toys we're building at The Singularity Workshop. This weekend, we've got more! (All are c#)

HeadlessAi — Connecting .NET applications to AI endpoints through a straightforward, extensible interface.
Profiles — Exploring identity, relationships, privacy, and user-controlled data sharing.
Ontology — Organizing information in flexible, meaningful structures.
MicroBundleIngestor — Exploring new ways to bring MicroBundles into the ecosystem.
Economy — Beginning to explore the foundations of an interconnected digital economy.

So, what makes the Workshop different?

We don't just build packages and leave you to figure them out. We explain the what, why, and how behind them—from the underlying theory to practical examples you can learn from and build upon.

You don't have to be an expert programmer to start exploring. We're building an ecosystem designed to help you understand the technology, connect the pieces, and bring your own ideas to life.

Don't just use the tools. Learn to build with them.

Come explore: The Singularity Workshop on GitHub

The Async Result Belongs to the Snapshot That Started It

Sat, 10 Oct 2026 06:01:28 +0000

Modern client components are long-lived, reactive, and full of asynchronous work. That combination creates a subtle class of defect: a response can be factually correct for the request that produced it, yet wrong for the screen that exists when it arrives.

This is especially important when a component mixes route parameters with identity-scoped state. The user can navigate while a request is in flight. Authentication can resolve, refresh, or change. The component instance may survive both events. Unless the component tracks which context owns each result, an older task can update a newer view.

The core rule is simple:

An awaited result belongs to the input snapshot that started it.

That snapshot is more than a component reference. It can include the current route value, the current authentication-state operation, and a monotonically increasing generation number.

How the race forms

Imagine a detail page that loads an item, then asks whether the current viewer has reacted to it. The page shows a highlighted action when the answer is yes.

The component begins loading item A for identity A. Before the viewer-specific request returns, the user signs out and another identity becomes current—or the same component navigates to item B. The old request then completes with a truthful answer: identity A did react to item A.

If the continuation writes directly to a shared isActive field, that truth is now displayed in the wrong context. Item B may appear active, or identity B may see state derived from identity A.

This is not merely a cosmetic race. Identity-derived state can influence which actions are enabled, what ownership badges appear, and which command a user can submit next.

Make ownership explicit

A practical pattern is to treat every meaningful input change as a new generation.

When a route or authentication input changes:

Increment the generation.
Capture the route and authentication input in local variables.
Clear state derived from the previous identity.
Disable identity-scoped actions while the new identity is unresolved.
After each await, confirm that the generation and captured inputs are still current.
Apply results only when those checks pass.

The checks matter after every awaited boundary, not only at the end. A component may load the main item, related content, entitlement state, reaction state, and cart state in sequence. Any await is a point where navigation or identity can change.

Cancellation tokens can reduce wasted work, and they are worth using when the underlying operation supports cancellation. But cancellation alone is not the ownership proof. Cancellation can race with completion, and some dependencies cannot cancel promptly. The continuation still needs to ask, “Does this result belong to the current snapshot?”

Fail closed while identity is unknown

There is another important state between old identity and new identity: unresolved identity.

Keeping the old viewer-specific UI visible during that interval is convenient, but unsafe. The component should clear ownership badges, active reactions, and similar derived state before awaiting the new authentication result. Any action that depends on identity should be disabled until the new snapshot is ready.

That brief disabled state is honest. The application does not yet know which identity owns the next command.

This principle also prevents an action from being sent using newly refreshed credentials while the visible UI still describes the previous viewer. Read state and write authority move together.

Test the interleaving, not only the outcome

Ordinary happy-path tests rarely expose this defect because requests finish in the same order they started.

A stronger component test controls the schedule:

Start a viewer-specific read and hold its response.
Change the route or authentication identity.
Wait for the new screen to settle.
Release the old response.
Assert that the current screen does not adopt the old result.

A separate test should hold authentication unresolved and verify that identity-scoped actions remain disabled. This proves that the UI fails closed during the transition.

There is also a useful counter-test: rerender with exactly the same inputs while a valid request is pending. The component should not discard or duplicate work merely because the framework rendered again. The boundary is a meaningful input change, not every render cycle.

These tests are valuable because they verify time and ownership, not just a final value. They turn a race that might appear once in a thousand interactions into a deterministic scenario.

The trade-off

Generation markers, captured snapshots, and repeated currentness checks add code. Temporarily disabling an action can introduce a small pause. Overusing the pattern can also make a component difficult to read.

The answer is not to attach a counter to every asynchronous line. Use the pattern where results are scoped to changing inputs: routes, selected records, authentication identity, workspace, locale, or another boundary that can change while the component remains mounted. Extract a small helper when the same ownership rule appears repeatedly.

The payoff is larger than visual correctness. Explicit async ownership reduces stale-route updates, prevents state from crossing identity boundaries, and stops commands from being enabled under an unresolved context.

The humble takeaway is this: asynchronous correctness is not only about receiving the right answer. It is also about proving that the answer still belongs here.

Building Reliable Backend Applications with C# and .NET

Tue, 06 Oct 2026 02:40:20 +0000

Backend development is more than writing code that works. For me, it is about building systems that are reliable, maintainable, secure, and capable of supporting real business needs.

My main experience is with C#, .NET, ASP.NET Core, SQL Server, and Entity Framework. I enjoy working on backend systems where there are real requirements to understand, databases to design, APIs to build, and performance problems to solve.

Turning Business Requirements into Backend Solutions

A typical project starts with understanding what the business actually needs. Before writing code, I try to understand the workflow, the data involved, and how different parts of the application will communicate.

Once the requirements are clear, I focus on creating a backend structure that is easy to maintain and can grow with the application.

This usually involves:

Designing backend architecture
Developing APIs with ASP.NET Core
Working with SQL Server databases
Creating data models with Entity Framework
Implementing authentication and authorization
Writing business logic in C#
Improving database queries and application performance
Debugging and maintaining existing applications

Working with Databases

A backend application is only as good as the data layer behind it.

I have worked extensively with SQL Server and Entity Framework, including database design, relationships, queries, stored procedures, migrations, and performance optimization.

One thing I have learned is that database performance should not be treated as an afterthought. A poorly designed query or database structure can affect the entire application.

Efficient database design and optimized queries can make a huge difference in application performance.

Building Secure APIs

Modern applications often depend heavily on APIs. I focus on creating APIs that are organized, predictable, and secure.

From handling requests and validation to authentication, authorization, error handling, and database communication, every layer needs to work together properly.

I also believe that an API should be designed with the consumers in mind. Clear responses, consistent error handling, and proper validation make applications much easier to maintain.

Performance and Problem Solving

Backend development often involves finding problems that are not immediately obvious.

An application may work correctly but become slow when the amount of data increases. A database query may work with a few records but become inefficient with thousands or millions of records.

That is where debugging and performance analysis become important.

I enjoy investigating these types of problems, finding the root cause, and improving the implementation rather than simply applying a temporary fix.

Maintaining Existing Applications

Not every project starts from scratch.

A large part of backend development can involve working with existing applications, understanding someone else's code, fixing bugs, improving functionality, and gradually making the system better.

This requires patience and the ability to understand existing architecture before making changes.

Good backend development is not always about rewriting code. Sometimes the best solution is improving what already exists.

Continuous Learning

Technology keeps changing, so there is always something new to learn.

Even while working primarily with C# and .NET, I continue exploring better development practices, modern backend architecture, API design, database optimization, and new tools that can improve the development process.

For me, programming is a continuous process of learning, building, debugging, and improving.

I enjoy taking a business requirement, breaking it down into smaller technical problems, and eventually turning those ideas into a backend system that people can actually use.

Always learning. Always building. Always looking for a better way to solve the problem.

It’s the Weekend. The Workshop Has Toys. Come Play.

Sat, 03 Oct 2026 07:14:18 +0000

It’s the weekend.

Instead of writing another 2,000-word manifesto on what The Singularity Workshop might become someday, I’m just going to open the toy box.

I’ve been building.

Some of it is foundational. Some of it is highly experimental. Some of it is definitely still alpha software. But enough of it has crossed the line from “whiteboard diagram” to running code that it’s time to put it out in public.

You can download it, read the source, compile it, and—most importantly—break it.

Where to Start: NuGet

The easiest way to see what is actually breathing right now is NuGet.

Search for TheSingularityWorkshop and make sure Include prerelease is enabled.

Search The Singularity Workshop packages on NuGet

Most of what I'm pushing right now is deliberately prerelease.

These aren't polished commercial products with a marketing department hiding the machinery behind a landing page. They are architectural experiments that have finally become real enough for someone else to get their hands dirty with.

That is exactly the point.

The Toy Box

Here is what is currently sitting on the workbench.

FSM_API

NuGet | GitHub

This is the bedrock.

The core premise is that behavior can be represented explicitly as state, allowing state-driven behavior to remain separate from the data objects it operates on.

FSM_API is a framework-agnostic C# finite-state-machine system with explicit state definitions, transitions, contexts, processing groups, lifecycle handling, and runtime behavior.

If you want to start at the absolute beginning of the Workshop, start here.

This is where the behavior machinery begins.

FSM_COS

NuGet | GitHub

This is where the pieces start becoming a system.

FSM_COS is the composition kernel.

A runtime manifest says what is requested. FSM_COS resolves the MicroBundle dependency closure, propagates configuration, loads the required capabilities, arbitrates them toward convergence, and produces a RuntimeAssembly.

Conceptually:

Runtime Manifest
       |
       v
    FSM_COS
       |
       +-- resolve MicroBundles
       +-- resolve dependencies
       +-- propagate configuration
       +-- load/install
       +-- arbitrate
       +-- converge
       |
       v
RuntimeAssembly
       |
       v
host / manifestation

The important part is what FSM_COS doesn't do.

It doesn't become the application.

It doesn't become the GUI.

It doesn't become the storage system.

It doesn't become the Experience.

It assembles the machine and hands the resulting composition to something else.

The crane doesn't become the machine.

MicroBundleDomain

NuGet | GitHub

This one is particularly important to the architecture.

MicroBundleDomain is a neutral contract for independently authored capabilities.

A MicroBundle is a focused unit of capability that can identify itself, declare dependencies and providers, accept configuration, enter a runtime, and participate in composition without requiring the host to understand its private domain.

The important architectural separation is:

What is this capability?
        |
        v
MicroBundleDomain

Where do I get it?
        |
        v
MicroBundleRepository

How do I compose it?
        |
        v
FSM_COS

That means MicroBundleDomain does not belong underneath FSM_COS as an implementation dependency.

It is the neutral seam.

That matters because someone should be able to author a capability without permanently welding their package to my composition engine.

MicroBundleRepository

GitHub

If MicroBundleDomain answers what, the Repository answers where.

The repository explores durable delivery of versioned MicroBundle artifacts, currently using Azure Blob Storage as the storage substrate.

The distinction is deliberately sharp:

Blob Storage
    = substrate

Repository
    = artifact delivery boundary

FSM_COS
    = composition boundary

Artifacts have deterministic identity based on the MicroBundle ID, explicit version, and SHA-256 content identity.

The repository doesn't become a database.

It doesn't arbitrate.

It doesn't compose Experiences.

It doesn't become a GUI.

It answers a much smaller question:

Given this artifact address, where are the bytes and can I verify them?

I am having entirely too much fun ruthlessly separating these concerns.

GUI

GitHub

There is a platform-neutral GUI core in here, alongside manifestations for Blazor and WPF.

But the real experiment isn't drawing buttons.

It's asking:

Can an object describe itself structurally well enough that a generic GUI can just render it?

That led to a reflection-driven GUI architecture where the domain model doesn't need to know about the editor that happens to display it.

The basic idea is:

Domain model
     |
     | describes itself
     v
Reflection / semantic projection
     |
     v
GUI.Core
     |
     +--------+--------+
     v                 v
  Blazor              WPF

So if you're interested in semantic interface construction, reflection, recursive GUI structures, and separating what something means from how it looks, poke around in this one.

There is considerably more going on here than “make a button.”

FSM_Serialization

NuGet | GitHub

This isn't an experiment in shouting “my serializer is the fastest.”

It's an experiment in strict ownership.

The domain owns what its data means.

The serialization layer owns how that data crosses a byte boundary.

The host decides where those bytes ultimately go.

The package deliberately stays out of databases, filesystems, HTTP, application configuration, object-graph magic, and other concerns that belong somewhere else.

It's small, tight, and opinionated.

I wrote a deeper dive on this one:

I Built a Serializer That Refuses to Own Your Data

FSM_REST

GitHub

This isn't another web framework.

FSM_REST provides a reusable boundary for describing and composing REST capabilities.

The interesting part is that a REST capability can be represented as a capability recipe rather than dragging an entire web application into the runtime.

Conceptually:

REST capability
      |
      v
FSM_REST
      |
      +-- capability description
      +-- request construction
      +-- transport boundary
      |
      v
remote API
      |
      v
current data

The MicroBundle can describe what is needed to obtain the capability without pretending that the remote API's current response data belongs inside the bundle.

That distinction becomes increasingly useful when capabilities are composed dynamically.

ProtocolAI & GrammarAI

ProtocolAI: GitHub
GrammarAI: GitHub

These sound like AI wrappers.

They aren't.

They explore the boundary where deterministic application-owned meaning meets probabilistic language models.

ProtocolAI is the WHAT.

It gives application-owned meaning a deterministic semantic address space.

GrammarAI is the HOW.

It gives those identities a structural language for describing how they can be connected.

LLM
 |
 | probability
 v
ProtocolAI
   WHAT
 |
 v
GrammarAI
   HOW
 |
 v
host / adapter
 |
 v
application

There is deliberately no LLM hidden inside either package.

No provider SDK.

No inference engine.

No chatbot.

No API-key management.

The application owns the meaning.

The model supplies probability.

The deterministic boundary sits in between.

I wrote more about the idea here:

ProtocolAI and GrammarAI: Giving AI a Language Software Can Actually Own

The Hosts

Architecture diagrams are great.

Eventually, though, somebody has to push a button.

AnyApp

GitHub

AnyApp is the desktop proof of the composition architecture.

It is the Windows desktop counterpart to the browser-facing WebPage/WebForge host.

The important part is that AnyApp is trying very hard to remain a host, rather than becoming an application-specific framework.

Startup is now manifest-driven:

AnyApp
  |
  v
startup / last Experience
  |
  v
Forge fallback when necessary
  |
  v
FSM_COS
  |
  v
RuntimeAssembly
  |
  v
host manifestation

The host doesn't need to know every Experience it might eventually run.

It hosts the composition.

That's the experiment.

And yes, the current window is tiny.

That's part of the fun.

WebPage

GitHub

This is the public proving ground.

WebPage is the ephemeral web manifestation of the larger Workshop: public-facing surface, demonstration environment, and experimental place where the architecture gets to meet an actual visitor.

The guiding idea is simple:

Make the mundane magical. Then show the machinery that made it possible.

Instead of merely putting diagrams on a webpage explaining that the GUI is dynamic, the page itself should eventually behave dynamically.

A button can breathe.

A GUI can reproduce.

The reproduction can become a swarm.

The swarm can overwhelm the screen.

The system can freeze.

Gravity can take over.

And suddenly the visitor isn't just reading about the architecture anymore.

They're watching the architecture become the experience.

That's what the WebPage repository is for.

You Don't Need to Understand All of This

Seriously.

You don't need to read every README.

You don't need to understand FSM_COS before touching FSM_API.

You don't need to understand MicroBundle arbitration before playing with the GUI.

You certainly don't need to agree with my architecture.

You don't need to know what a “semantic address space” is.

You don't need to know what “arbitration” means.

You don't even need to know why I keep naming things with increasingly suspicious acronyms.

Just pick one piece that looks interesting.

Install it.

Read the source.

Build a tiny experiment.

Benchmark it.

Break it.

Tell me why it's broken.

That is the entire point of publishing early.

Software has to meet reality.

And reality includes other developers.

Some APIs will change.

Some experiments will become load-bearing infrastructure.

Some ideas that seem perfectly reasonable right now will probably turn out to be terrible.

Some will get thrown away.

That's normal.

Actually, that's part of the process.

The important thing is that these aren't only diagrams anymore.

They're code.

They're packages.

They're repositories.

They're things you can actually touch.

The Workshop Is Open

So, that's the current toy box.

Not everything is finished.

Not everything is stable.

Not everything is even guaranteed to survive.

That's why I'm putting it out now.

If something catches your eye, go play with it.

And if you find something interesting, confusing, inefficient, backwards, brilliant, terrible, or just plain weird—

tell me.

That's how experiments turn into software.

And how software turns into infrastructure.

The toy box is open.

It's the weekend. Come play.

Support Our Work:

Patreon Page:
[https://www.patreon.com/c/TheSingularityWorkshop][1]

Support Us (PayPal Donation):
[https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J][2]

We'd love to hear your thoughts! Please Like this post, Love the code, and Share your feedback in the comments.

A Row Version Is a Cross-Layer Contract

Sat, 03 Oct 2026 06:24:18 +0000

A concurrency column can exist in the database and still be wrong.

The name may match. The migration may have run. Inserts may appear healthy. Yet optimistic concurrency can still be weaker than the application assumes because the runtime model, the physical schema, and the test environment disagree about what that column means.

The lesson is broader than one ORM feature: database-generated values are cross-layer contracts. Treating them as a property of only the entity class or only the table leaves a gap exactly where correctness matters.

What the contract actually contains

For a database-generated row version, at least five facts need to agree:

the physical type has true row-version semantics;
the value is non-nullable;
the database generates it on insert and update;
the ORM marks it as a concurrency token;
existing values remain intact during alignment or deployment.

A binary column of the expected length is not automatically equivalent. A nullable token changes the invariant. A model that knows about concurrency but not database generation can try to write a value the database owns. Conversely, a correctly generated database column provides little application protection if the runtime model never includes it in optimistic-concurrency checks.

The useful mental model is not “there is a column.” It is “every layer agrees who owns this value and how a stale write is detected.”

Prefer verification over destructive repair

Suppose the shipped database already has the correct non-null generated token, but the current EF Core model describes it incompletely. A tempting fix is to alter or recreate the column until the migration history looks tidy.

That can be the riskiest part of the change. Replacing a generated token can touch every row, invalidate values held by active writers, or disguise an unexpected schema. The safer move is often smaller:

align the runtime mapping with the physical contract;
add a forward-only migration that asserts the exact expected shape;
refuse to proceed when the real schema differs.

This kind of assertion migration changes no business data. It asks the database whether the table, column, type, length, nullability, and generation semantics match the known contract. Running it twice should be safe. Encountering a missing, nullable, or look-alike column should fail clearly.

Failing a rollout is inconvenient. Quietly weakening stale-write protection is worse. A fail-closed migration turns unknown drift into an explicit operational decision instead of an accidental data-integrity change.

Test at three different levels

No single test provider can prove the whole contract efficiently. A layered suite gives each test one honest job.

1. Model metadata

A cheap unit test can inspect EF Core metadata. It should verify that the property is required, marked as a concurrency token, and generated on add or update. This catches accidental mapping changes quickly, without starting a database.

Metadata tests do not prove the database behaves that way. They prove the application describes its expectation correctly.

2. Lightweight application flows

In-memory providers are useful for service and orchestration tests, but they do not automatically behave like a relational engine with generated row versions. Once a token becomes required, fixtures may fail because no value is produced.

A narrowly scoped, test-only save interceptor can generate a fresh fixed-length token for inserted or modified entities. That keeps fast tests representative of the required-value lifecycle. It should be described honestly as an emulator, not provider parity.

The emulator proves that application code can carry changing tokens through its flows. It cannot prove the SQL type, migration assertion, or actual stale-write mechanics.

3. A focused real-database proof

The decisive test uses the real provider. Create the shipped shape, insert a synthetic row, and retain its generated token. Apply the alignment migration—ideally twice—and verify that both the row and original token survive.

Then load the same row through two contexts. Save through the first and confirm its token changes. Attempt to save the stale copy through the second. The expected concurrency exception is the behavioural proof that the contract works end to end.

Negative cases matter too. A missing table, missing column, nullable token, or ordinary binary column should be refused. These cases prevent a permissive assertion from becoming ceremonial.

Put the expensive proof on the required path

A real-database test that developers can skip forever is documentation, not a gate. Register the small provider-faithful suite in the required CI job and include the relevant file scopes in change detection.

This does not mean every application test should use a full database. That would make feedback slower and fixtures harder to maintain. The trade-off is deliberate separation:

metadata tests are cheap and broad;
in-memory tests exercise application flows;
real-database tests prove database-owned behaviour.

The suite costs more than one happy-path unit test. In return, failures become easier to interpret because each layer states what it can and cannot guarantee.

A practical review checklist

When reviewing a database-generated concurrency token, ask:

Does the runtime model match the shipped type, nullability, and generation rules?
Does the migration preserve rows and existing token values?
Does unexpected schema fail closed?
Do fast fixtures represent the required token lifecycle without claiming provider equivalence?
Does a real-provider test prove token change and stale-write rejection?
Is that proof part of required CI?

The broader engineering habit is simple: when a value is owned by the database, verify the contract where each promise is made. Model tests describe intent. Fast tests protect application flow. Only the real provider can prove the final integrity boundary.

Project the Response, Not the Cache

Thu, 01 Oct 2026 05:50:20 +0000

A response can be correct for one caller and still leave the application in a worse state for everyone who follows.

This is an easy trap in ASP.NET Core when a result filter, formatter, or middleware needs to change a few fields before a response leaves the server. Localization is a useful example: a DTO contains source-language text, the current request asks for another language, and the pipeline replaces selected strings before serialization.

The first response looks right. The implementation may even be pleasantly small.

The danger is ownership. If the returned DTO came from an in-process cache, the response pipeline may be holding the same object instance that another request, background job, or command path will read later. What looked like response formatting was actually a write to shared state.

The broader lesson is this: request-specific presentation should be a projection, not a mutation.

The Bug Hides Behind a Successful Response

Imagine a cached catalogue item with a description in the system’s source language. A request asks for a translated version. The tempting implementation walks the object graph and assigns the translated string to the DTO property.

The response is translated correctly. A test that checks only that response passes.

Now consider the next reader. If the cache returns the same instance, the cached item is no longer in its authoritative source form. A source-language request may receive translated text. A command that maps the DTO back into another model may persist presentation text as source data. A background process may observe a value chosen for somebody else’s request.

Nothing about the first HTTP response reveals this. The defect is temporal: the observable failure belongs to a later reader.

That is why “the output is correct” is not a sufficient assertion when inputs can be shared.

Draw the Ownership Boundary Explicitly

A useful model is to separate three things:

The cached or domain DTO is authoritative input.
Request context selects presentation rules.
The HTTP payload is response-owned output.

Once those roles are explicit, several safe implementations become available. You can map into a dedicated response model. You can clone the graph and change the clone. Or you can project replacement values at the serialization boundary.

In the last approach, the traversal discovers which string properties need different values but never assigns those values to the source objects. The serializer then substitutes the replacements while creating a JSON tree owned by the response. Nested objects, collections, readonly wrappers, and init-only properties keep their wire shape because the original serializer contract still defines the payload.

The important property is not the particular API used. It is that no request-specific operation writes into caller-owned or cache-owned objects.

This idea also applies to redaction, unit formatting, enrichment, API-version shaping, and field masking. If the transformation varies by caller or request, it probably belongs in an output projection.

Preserve the Common-Case Fast Path

Projection has a cost. It may require an additional JSON materialization, replacement lookup, and short-lived allocations. That cost should be acknowledged rather than hidden behind a correctness slogan.

The practical response is to make the cheap path obvious. When the request already uses the source representation, pass the original result through untouched. Only requests that need transformation pay for projection.

Failure behavior also matters. If the projection cannot handle an unusual graph, the pipeline should not leave a half-mutated object behind. A safe fallback retains the original result and logs the failure according to the application’s policy. Whether returning the untransformed payload is acceptable depends on the feature and data classification; sensitive redaction may need to fail closed instead.

Security-sensitive payloads and error results may also deserve explicit exclusion. Presentation machinery should not accidentally inspect tokens, secrets, or payload shapes that were never part of its contract.

Test the Second Reader

The highest-value test is a sequence, not a snapshot:

Put a source-language object into the real cache implementation used by the host.
Request a transformed response and verify its output.
Read the cached object again and verify that it is unchanged.
Issue a source-language request and verify that it still receives the source value.

Run that sequence through the real result filter and serializer options, not only a mocked translation service. The ownership bug lives in the composition between cache identity, result handling, graph traversal, and serialization.

Add focused cases for ordinary object results and explicit JSON results, nested collections, readonly response wrappers, init-only properties, error responses, exempt payloads, and projection failure. These tests establish both the intended transformation and the things it must never change.

A mutation-resistance assertion is especially valuable: keep a reference to the original object and prove its properties retain their exact values after the response executes.

The Trade-Off Is Isolation Versus Local Simplicity

In-place mutation is easy to understand in one method and can avoid an extra materialization. Its cost appears elsewhere: temporal coupling, language or user context leaking between requests, and tests that pass individually while failing in sequence.

Response projection adds code, allocations, and serializer-specific reasoning. In return, it makes ownership visible. The cache remains authoritative, requests remain isolated, and failures cannot leave shared objects partially transformed.

That is a trade I will usually take. I would still measure the transformed path with representative payload sizes and keep the source path cheap. But performance work should begin after the ownership contract is correct.

The practical rule is short: if a value is shared, treat it as immutable. If presentation depends on the request, produce response-owned output. And when you test it, always ask what the next reader sees.

Treat Every ID as an Authorization Claim

Wed, 30 Sep 2026 10:38:55 +0000

Authentication answers one important question: who made this request? It does not answer a second question that often hides inside an ordinary-looking query parameter: may this caller name the record represented by this identifier?

That gap is easy to miss in APIs that accept a parent ID, child ID, account ID, project ID, or tenant ID. The route is authenticated. The identifier has the correct shape. The query returns a valid result. Yet none of those facts proves that the record belongs inside the caller's authorized scope.

A useful engineering rule is to treat every caller-supplied identifier as an authorization claim before treating it as a query input.

Authentication Is Not Object Ownership

Imagine an endpoint that returns activities for a supplied household record. The controller requires a signed-in user, then passes the supplied ID into a query service. If the ID is changed in transit, the query may still succeed—just for somebody else's data.

The vulnerable assumption is subtle: “signed in” becomes “allowed to ask about any existing record.” The database faithfully answers the question it receives. The missing control belongs before the query.

The server should derive the caller's authority from trusted identity and relationship data. For an ordinary user, that might mean resolving the account to its authoritative person record, then traversing explicit relationships to the permitted records. For an operational role, a specific permission may allow a wider scope because that role already performs work requiring the same visibility.

This also explains why email equality is a poor ownership rule. Addresses are corrected, reused, shared by families, copied into contact fields, and sometimes retained after account changes. An email can help locate a candidate during migration, but it should not silently replace an authoritative account-to-person relationship.

Put the Boundary Before the Query

A safe request pipeline makes the order explicit:

Identify the caller from trusted authentication state.
Resolve the caller's authoritative records and relationships on the server.
Evaluate each supplied identifier against that scope.
Only then construct and execute the data query.

This order prevents a common failure mode: retrieving a broad result and hoping a later projection removes everything sensitive. Late filtering spreads the security contract across repositories, mappers, and UI code. Early scope resolution gives the query a smaller, already-authorized input.

Do not bundle independent identifiers into one vague decision. If a request contains both a parent filter and a child filter, check each one. Mixed requests are exactly where “one valid field makes the request valid” bugs appear. A valid parent must not bless an unrelated child; an unrelated parent must not erase a valid child's boundary.

Reject by Default, Narrow Only Deliberately

For most data-specific routes, a cross-scope identifier should be rejected. Rejection is direct, observable, and easier to reason about. It tells the client that its request crossed a boundary and gives operators a signal worth investigating.

Legacy mobile clients complicate that clean answer. An installed client may send an old identifier shape, interpret a forbidden response as a session failure, or sign the user out. Waiting for every old version to disappear can leave a real data boundary open longer than necessary.

There is a narrow alternative: compatibility-preserving narrowing. The server validates every supplied identifier, discards any that are not authorized, and executes only a known-safe baseline query. The key invariant is monotonicity: removing an unauthorized filter must never widen the response into the requested protected data.

For example, a calendar route might combine household-specific entries with public entries. If an old client sends an account ID where a domain record ID is expected, the server can remove that invalid household filter and return only the public baseline. It must not substitute another household, guess from a weak attribute, or run an unscoped “all entries” query.

This is not a general recommendation to hide authorization failures. It is an endpoint-specific migration tool. Document why it exists, record how it is used, and give it a removal condition.

Test the Boundary, Not Just the Happy Path

Authorization tests should form a matrix around relationships and permissions:

the caller names their own authoritative record;
the caller names a related child record;
the caller names another household's record;
the caller has no corresponding relationship;
a shared or copied email appears on a record the caller does not own;
a staff role lacks the exact cross-scope permission;
a staff role holds that permission;
one filter is authorized while another is not;
the legacy request shape still receives the same safe baseline.

The last two cases are especially valuable. Mixed filters catch accidental “any match” logic. Legacy-shape tests prevent a future cleanup from turning a deliberate compatibility response back into either a leak or a destructive client error.

Tests should assert returned data as well as status codes. A successful response is safe only if its contents stay inside the proven scope. A forbidden response is useful only if the client contract can tolerate it.

Make the Exception Expensive to Forget

Compatibility code tends to become permanent when its rationale lives only in memory. Keep the exception close to the boundary, name the safe baseline, add telemetry that contains no sensitive identifiers, and define the client version or date after which strict rejection can replace narrowing.

The trade-off is real. Strict rejection gives a simpler model and clearer misuse signals. Narrowing adds policy, tests, and the possibility of masking a broken client. Its value is speed: the server can close the data boundary now while preserving a safe experience for older installations.

The practical standard is modest but powerful: never let a caller-provided ID reach a query merely because it parses. First prove that the caller may name it. If compatibility forces an exception, make the request narrower, make the safe response explicit, and make the exception temporary.

A Lifetime Is a Hold, Not the Worker

Tue, 29 Sep 2026 05:58:20 +0000

IDisposable and IAsyncDisposable make lifetime management feel pleasantly local: acquire something, use it, dispose it. That model is reliable when the acquired value has exclusive ownership of an independent resource.

It becomes dangerous when several activations share one background worker.

Mobile applications encounter this more often than it first appears. Returning online can reconcile a capability that is already running. A foreground transition can overlap an earlier activation. A bounded startup wait can stop waiting for slow native work, while that work completes after a newer activation has already joined the same resource.

If every returned lifetime means “stop the worker,” one participant can tear down work that another still needs. The sharper contract is: a returned lifetime is a hold on shared work. Disposing it releases only that participant’s hold. The worker stops when the final hold leaves.

The bug hides behind a reasonable API

Imagine a mobile shell with two optional capabilities: a small status refresher and a device-token relay. Each activation returns an asynchronous lifetime to the orchestrator. The orchestrator keeps the latest lifetime and disposes the one it replaces.

That sounds tidy, but activations are not necessarily independent. The second activation may join the refresher or event relay started by the first. If the first lifetime calls a global StopAsync, disposing the replaced lifetime stops the shared worker beneath the second activation.

The state machine can now tell a convincing lie. Its newest activation completed successfully, so the capability still appears ready. Underneath, polling has stopped or the event handler has been removed.

Warning, cancellation, and stale-completion paths deserve the same scrutiny. Cleanup code is often written defensively in several branches. If each branch performs terminal teardown, one failed attempt can shut down a resource held by a successful attempt.

Write the ownership sentence first

Before implementing the lifetime, describe what disposal means:

Disposing this value releases this activation’s participation. It does not necessarily stop the shared resource.

That sentence changes the design. Starting becomes “start or join, then take a hold.” Releasing becomes “release this hold, then stop only if it was the last.” Both transitions need one synchronization boundary.

It is not enough to increment a counter and subscribe in separate steps. Another thread can observe the gap. A release can unsubscribe after a new hold has been counted, or two starts can install duplicate listeners. The zero-to-one decision and the actual start belong in one atomic operation. So do the one-to-zero decision and the stop.

The hold itself should release at most once. A double Dispose must not decrement the count twice. A failed start must not record a hold, otherwise the next activation may “join” work that never started.

Old holds must not reach into new runs

Reference counting alone is not sufficient when the resource can stop and restart.

Suppose an old activation holds generation A. The application moves offline, so generation A is stopped. Later, the application returns online and starts generation B. If the late lifetime from A merely decrements a global count, it can steal a hold from B and stop the restarted worker.

Bind each hold to the run it joined. Releasing a hold from an ended run becomes a no-op for the current one.

The orchestrator may need a run identity too. Some stop events invalidate a broad session lease; others, such as backgrounding or going offline, may intentionally leave that session identity unchanged. A slow activation can therefore finish with a lease that still looks current even though the capability run it belonged to has ended. Tracking the capability run separately prevents that late completion from being adopted as ready.

This distinction is useful beyond mobile software. Connection pools, shared subscriptions, refresh loops, file watchers, and in-process event relays all have “same logical session, different resource run” failure modes.

Test transitions, not only outcomes

A happy-path test that starts and stops once proves very little about shared ownership.

Useful tests make each boundary visible:

take two holds, release one, and prove the worker remains active;
release the final hold and prove the worker stops exactly once;
dispose one hold twice and prove it releases once;
fail the first start and prove a later acquisition tries again;
restart the resource and prove an old hold cannot affect the new run;
complete an abandoned activation after a newer one and prove the newer work survives; and
repeatedly take, inspect, and release holds from two threads while the count crosses zero.

That last test is important. A single-thread loop can leave mutation survivors because it never exposes the gap between “count says active” and “listener is actually active.” Two competing threads make zero crossings collide with acquisition and release, which is where split synchronization shows itself.

Concurrency tests still need discipline: bounded rounds, a clear invariant, and no claim that passing them mathematically proves correctness. Their job is to exercise the race window while deterministic tests pin the state-machine rules.

The honest trade-off

Counted holds add a lock, a run identifier, idempotent release state, and more involved tests. They also force a clear distinction between releasing one participant and terminally disposing the owning dependency scope.

The simpler design is to prohibit overlap. That can be the right choice when the orchestrator can guarantee one activation at a time, cancel it reliably, and wait for completion before starting another. But if native calls can outlive a budget, or reconciliation can join already-running work, the simplicity is imaginary.

The practical takeaway is broader than reference counting: make ownership semantics part of the public contract. When a lifetime represents participation in shared work, call it a hold and test it like one. A local cleanup action should never silently become a global stop.

I Built a Serializer That Refuses to Own Your Data

Mon, 28 Sep 2026 23:36:42 +0000

I Built a Serializer That Refuses to Own Your Data

How The Singularity Workshop turned a recurring binary-IO problem into a tiny .NET boundary—and why the smallest part of the design may be the most important part.

There is a particular kind of software problem that appears harmless at first.

You have some state.

You need to turn it into bytes.

So you write a serializer.

Then another part of the application needs bytes, so you add another serializer.

Then a cache needs them.

Then a manifest needs them.

Then a transport layer needs them.

Then somebody decides JSON is better here, binary is better there, and suddenly the architecture has six different opinions about what a piece of data is.

That was the problem I was running into while building The Singularity Workshop.

The interesting part is that I didn't actually need a giant serialization framework.

I needed a boundary.

So I built one.

It is called:

TheSingularityWorkshop.FSM_Serialization

And it is deliberately small.

That is the point.

The Problem Wasn't Turning Objects Into Bytes

Serialization is usually described as a mechanical operation:

object → serializer → bytes

That description hides something important.

An object has meaning.

Bytes do not.

Bytes are a representation of meaning.

That distinction becomes increasingly important as an architecture grows.

The Workshop ecosystem is being built around several deliberately separated responsibilities:

FSM_API
    │
    │ behavior and state
    ▼
FSM_COS
    │
    │ composition and runtime assembly
    ▼
FSM_Serialization
    │
    │ representation
    ▼
storage / transport / host

I didn't want FSM_COS to become a serializer.

I didn't want a MicroBundle to have to know how a filesystem works.

I didn't want a database abstraction hiding inside a representation layer.

And I definitely didn't want every higher-level system inventing its own binary stream interface.

So I extracted the smallest reusable boundary I could identify.

That boundary became FSM_Serialization.

The First Design Decision

The most important rule in the package is also the simplest:

The type that owns the meaning should own the representation rules.

FSM_Serialization provides the machinery for crossing the byte boundary.

It does not decide what your data means.

That means the package doesn't contain some enormous reflection-based object graph engine that looks at your class and decides what should be serialized.

Instead, the type explicitly says:

public interface IBinaryPackable
{
    void Pack(IBinaryStream stream);
}

And the reverse direction is equally explicit:

public interface IBinaryUnpackable
{
    void Unpack(IBinaryStream stream);
}

If a type needs both:

public interface IBinarySerializable :
    IBinaryPackable,
    IBinaryUnpackable
{
}

That's the entire conceptual model.

No magic.

No global serializer registry.

No reflection-based guesswork.

No framework deciding that a private field suddenly became part of your persistent format.

The domain owns that decision.

Why I Didn't Just Use `System.IO.Stream`

This is probably the first question a .NET developer will ask.

And honestly, it is a good question.

.NET already has System.IO.Stream.

Why introduce another interface?

Because I wasn't trying to replace Stream.

I was trying to establish a package-owned contract.

The current abstraction is:

public interface IBinaryStream : IDisposable
{
    bool CanRead { get; }
    bool CanWrite { get; }

    long Position { get; set; }
    long Length { get; }

    int Read(Span<byte> buffer);
    void Write(ReadOnlySpan<byte> buffer);
    void Flush();
}

Notice what isn't there.

There is no:

filename;
filesystem;
database;
socket;
HTTP request;
serializer registry;
schema;
domain metadata;
application configuration.

The interface only knows about the byte boundary.

That makes it possible to write serialization code against one very small abstraction while letting the host decide what is actually underneath it.

The Two Directions Matter

There is another small decision here that I think becomes important in larger systems.

Packing and unpacking are separate capabilities.

A type that produces a representation does not necessarily need to consume one.

Likewise, a type may consume a representation without being responsible for producing it.

So the package doesn't force everything into one giant:

Serialize()
Deserialize()

method.

Instead:

                 DOMAIN TYPE
                     │
          ┌──────────┴──────────┐
          │                     │
        Pack                  Unpack
          │                     │
          ▼                     ▲
     representation          representation
          │                     │
          └──────────┬──────────┘
                     ▼
                byte stream

That separation costs almost nothing.

But architecturally, it keeps the ownership visible.

The Smallest Possible Example

Let's make this concrete.

Imagine a domain object containing one integer.

That's intentionally boring.

Boring is useful here because it lets us see exactly where the responsibility lives.

using System.Buffers.Binary;
using TheSingularityWorkshop.FSM_Serialization;

public sealed class ExampleState : IBinarySerializable
{
    public int Value { get; private set; }

    public ExampleState()
    {
    }

    public ExampleState(int value)
    {
        Value = value;
    }

    public void Pack(IBinaryStream stream)
    {
        Span<byte> buffer = stackalloc byte[sizeof(int)];

        BinaryPrimitives.WriteInt32LittleEndian(
            buffer,
            Value);

        stream.Write(buffer);
    }

    public void Unpack(IBinaryStream stream)
    {
        Span<byte> buffer = stackalloc byte[sizeof(int)];

        if (stream.Read(buffer) != buffer.Length)
            throw new EndOfStreamException();

        Value = BinaryPrimitives.ReadInt32LittleEndian(buffer);
    }
}

There is no serializer object.

There is no configuration object.

There is no registration step.

The object itself defines its representation.

That is intentional.

Now Let's Actually Serialize Something

The package includes MemoryBinaryStream, which is exactly what it sounds like: an in-memory implementation of IBinaryStream.

That makes testing and temporary representations extremely simple.

using var stream = new MemoryBinaryStream();

var original = new ExampleState(42);

original.Pack(stream);

stream.Position = 0;

var restored = new ExampleState();

restored.Unpack(stream);

Console.WriteLine(restored.Value);

Output:

That's it.

The complete flow is:

ExampleState
     │
     │ Pack
     ▼
MemoryBinaryStream
     │
     │ bytes
     ▼
Position = 0
     │
     │ Unpack
     ▼
ExampleState

The package supplied the boundary.

The domain supplied the meaning.

Installation

If you want to try it yourself, the current published alpha is:

dotnet add package TheSingularityWorkshop.FSM_Serialization --version 0.1.0-alpha.2

Or:

<PackageReference
    Include="TheSingularityWorkshop.FSM_Serialization"
    Version="0.1.0-alpha.2" />

The current package targets .NET 8.

This is intentionally an alpha release.

That doesn't mean the contracts are casual.

Quite the opposite.

A binary representation is one of those things where small assumptions can become enormous compatibility problems later.

So I'm treating the package as alpha while treating its architectural boundaries seriously.

What About Real Files?

This is where StreamBinaryStream enters.

The package includes an adapter around an ordinary .NET Stream:

using var file = File.OpenRead("state.bin");
using var stream = new StreamBinaryStream(file);

Now the same domain serialization code can operate against the package abstraction without knowing that a file exists.

The relationship is:

ExampleState
     │
     ▼
IBinaryStream
     │
     ▼
StreamBinaryStream
     │
     ▼
System.IO.Stream
     │
     ▼
file / memory / whatever the host provides

That is a very different architecture from:

ExampleState
     │
     ▼
ExampleStateSerializer
     │
     ▼
FileSystemSerializerManager
     │
     ▼
ApplicationStorageService

The latter might be useful somewhere.

It just doesn't belong in this package.

The Stream Adapter Is Supposed to Be Boring

This is one of those cases where boring code is a compliment.

StreamBinaryStream essentially delegates:

public int Read(Span<byte> buffer)
    => _stream.Read(buffer);

public void Write(ReadOnlySpan<byte> buffer)
    => _stream.Write(buffer);

public void Flush()
    => _stream.Flush();

That's not a weakness.

It's the point.

The adapter is not supposed to invent behavior.

It establishes a stable contract between two layers.

Then I Ran Into a Very Important Detail

A byte stream is not the same thing as an array.

This matters:

int count = stream.Read(buffer);

You cannot blindly assume:

count == buffer.Length

So a fixed-width decoder in FSM_Serialization explicitly checks:

if (stream.Read(buffer) != buffer.Length)
    throw new EndOfStreamException();

That may look like a tiny implementation detail.

It isn't.

It establishes an architectural rule:

Never interpret an incomplete representation as a complete value.

The serializer shouldn't quietly manufacture missing data.

If the representation is incomplete, the domain implementation gets to decide what that means.

In the current examples, that means rejecting it.

Serialization Is Not Storage

This distinction became increasingly important as the Workshop architecture grew.

Consider these questions:

Serialization

How are these values represented as bytes?

Storage

Where do those bytes live?

Transport

How do those bytes move between boundaries?

Those are three different questions.

So:

                 SEMANTIC DATA
                      │
                      ▼
                representation
                      │
                      ▼
              FSM_Serialization
                      │
              ┌───────┴───────┐
              ▼               ▼
           storage         transport

A database is not a serializer.

A filesystem is not a serializer.

An HTTP endpoint is not a serializer.

A cache is not a serializer.

They may all consume serialized data.

That doesn't make them the same architectural layer.

This is exactly the kind of distinction that seems unnecessary when an application is small and becomes incredibly valuable when an ecosystem starts growing.

Why Binary?

I am not claiming that binary is universally superior to JSON.

It isn't.

JSON is fantastic for many things.

Text is fantastic for many things.

Human-readable configuration is valuable.

Debugging matters.

Authoring matters.

Interoperability with external systems matters.

The reason I created this package is narrower.

There are situations where I want an explicit, compact, byte-oriented representation.

For example:

runtime state;
manifests;
dependency metadata;
compact configuration;
cache entries;
identity records;
version records;
lineage metadata;
persistence;
transport payloads.

The important thing is that the semantic model shouldn't have to become identical to its wire representation.

Deterministic Does Not Mean Magical

The package's NuGet description talks about deterministic binary serialization.

There is an important qualification.

Implementing:

IBinaryPackable

does not magically make your representation deterministic.

You have to define deterministic rules.

For example, suppose your object contains a collection that is semantically unordered.

If you serialize it in whatever order happens to be present at runtime, two semantically identical objects could produce different byte sequences.

If deterministic bytes matter, the domain needs something like:

semantic collection
        │
        ▼
canonical ordering
        │
        ▼
explicit representation
        │
        ▼
deterministic bytes

That distinction matters if bytes are later used for:

caching;
content identity;
synchronization;
comparison;
reproducible builds;
lineage;
integrity checks.

Again, the package supplies the boundary.

It does not pretend to know your domain's canonical ordering rules.

Versioning Gets Interesting

This is another reason I didn't want a magical object serializer.

Once bytes leave your process, they can outlive the code that created them.

Imagine:

Application v1
      │
      ▼
    bytes
      │
      │ time passes
      ▼
Application v2

What happens?

That is a representation contract question.

A durable binary format may need to distinguish between:

semantic object version
format version
dependency version

Those are not necessarily the same thing.

Your semantic object can change while the representation remains compatible.

Your representation can change while the semantic concept remains the same.

A dependency can change independently of both.

FSM_Serialization intentionally doesn't impose one universal versioning strategy.

Different domains need different compatibility policies.

What it does is make the boundary explicit enough that you can actually have that conversation.

The Package Came From a Real Application

This is probably the most important part of the story.

FSM_Serialization wasn't created because I thought:

"The world needs another serialization library."

There are already plenty of serialization libraries.

The package emerged from building the Workshop itself.

The development pattern was:

working application
       │
       │ repeated infrastructure appears
       ▼
explicit contract
       │
       │ extract
       ▼
reusable package
       │
       │ consume again
       ▼
working application

That distinction matters.

I wasn't trying to abstract everything before I had a reason to abstract it.

The application became the proving ground.

Once the boundary became clear, I extracted it.

That is a much healthier way to create infrastructure.

And This Is Where FSM_COS Enters the Story

The larger ecosystem is becoming increasingly compositional.

FSM_COS is concerned with questions like:

What runtime composition was requested?

Which MicroBundles are required?

What dependencies are reachable?

How do those capabilities reconcile?

When is the composition stable enough to hand to a host?

FSM_Serialization answers a different question:

How do we represent the values that need to cross a byte boundary?

That means a future conceptual flow can look something like:

Runtime Manifest
      │
      ▼
    FSM_COS
      │
      │ composition
      ▼
Runtime Assembly
      │
      │ representation
      ▼
FSM_Serialization
      │
      ▼
     bytes

And then those bytes might eventually go somewhere else:

                 FSM_Serialization
                        │
             ┌──────────┼──────────┐
             ▼          ▼          ▼
          storage    transport    cache
             │          │          │
             └──────────┼──────────┘
                        ▼
                      host

The serializer doesn't become FSM_COS.

FSM_COS doesn't become a serializer.

That separation is exactly what I'm trying to preserve.

The Tests Tell the Same Story

The package currently has a deliberately small test surface.

It verifies things such as:

an empty MemoryBinaryStream is readable and writable;
bytes survive a write/read round trip;
existing byte arrays can initialize a memory stream;
null input is rejected;
end-of-input returns zero;
positioning and overwriting work;
StreamBinaryStream delegates correctly;
null wrapped streams are rejected;
writes reach the underlying stream;
IBinaryPackable and IBinaryUnpackable can round-trip;
IBinarySerializable combines both contracts;
incomplete binary input is rejected.

One of the tests is essentially the entire architectural idea in executable form:

var original = new TestValue(123456789);

using var stream = new MemoryBinaryStream();

original.Pack(stream);

stream.Position = 0;

var restored = new TestValue();

restored.Unpack(stream);

Assert.Equal(original.Value, restored.Value);

Tests aren't merely protecting the implementation here.

They are defining the boundary.

I Also Benchmarked It

Because eventually somebody is going to ask:

"Okay, but what does that abstraction cost?"

Good.

Let's measure it.

The companion benchmark project uses BenchmarkDotNet against .NET 8 and exercises payloads from 16 bytes through 100,000 bytes.

The interesting result isn't that FSM_Serialization magically beats MemoryStream.

It doesn't.

That's not what I was trying to prove.

The useful result is that the abstraction can remain extremely close to the underlying primitive for substantial workloads.

At 100,000 bytes, the benchmark measured approximately:

MemoryStream write:
39,894.85 ns

MemoryBinaryStream write:
40,005.59 ns

That's effectively the same scale.

Likewise, the adapter path was approximately:

MemoryStream read:
2,272.47 ns

StreamBinaryStream read:
2,298.40 ns

Again, very close.

And the end-to-end IBinarySerializable benchmark measured:

16 bytes       64.08 ns
1,024 bytes   207.47 ns
10,000 bytes  1,481.61 ns
100,000 bytes 60,152.74 ns

But there is an important qualification.

The benchmark measures the whole operation, including things like creating the test value, creating the stream, packing, rewinding, allocating the destination payload, and unpacking.

So I'm not going to pretend those numbers represent some universal "serialization speed."

They represent a measured workload.

That's much more useful.

The Benchmark Question I Actually Care About

The interesting engineering question isn't:

"Is my interface faster than MemoryStream?"

The interface isn't supposed to be the star of the show.

The question is:

Can I establish a useful architectural boundary without making the underlying operation prohibitively expensive?

The current measurements suggest that, for these workloads, the answer is yes.

And that's exactly where I want infrastructure to live.

The abstraction should be visible architecturally and nearly invisible computationally.

What I Deliberately Did Not Build

This may be the most important section of the entire package.

FSM_Serialization should not become:

an FSM engine;
a game framework;
a GUI framework;
a browser framework;
a Unity integration layer;
a database abstraction;
a filesystem framework;
an HTTP client;
an application configuration system;
a MicroBundle implementation;
an Experience runtime;
a reflection-driven object graph serializer;
a global serializer registry.

Those things may all be useful.

They just aren't this thing.

That restraint is part of the architecture.

A small package becomes powerful when other systems can depend on it without having to inherit the systems it was never supposed to understand.

So What Would You Actually Use It For?

If you're building a .NET application and you have a domain type whose state needs to cross a byte-oriented boundary, the starting point is incredibly small.

Install the package:

dotnet add package TheSingularityWorkshop.FSM_Serialization --version 0.1.0-alpha.2

Define your representation:

public sealed class MyState : IBinarySerializable
{
    public int Id { get; set; }

    public void Pack(IBinaryStream stream)
    {
        Span<byte> buffer = stackalloc byte[sizeof(int)];

        BinaryPrimitives.WriteInt32LittleEndian(
            buffer,
            Id);

        stream.Write(buffer);
    }

    public void Unpack(IBinaryStream stream)
    {
        Span<byte> buffer = stackalloc byte[sizeof(int)];

        if (stream.Read(buffer) != buffer.Length)
            throw new EndOfStreamException();

        Id = BinaryPrimitives.ReadInt32LittleEndian(buffer);
    }
}

Use memory when you need a temporary representation:

using var stream = new MemoryBinaryStream();

state.Pack(stream);

byte[] bytes = stream.ToArray();

Use a normal .NET stream when the host provides one:

using var file = File.Create("state.bin");
using var stream = new StreamBinaryStream(file);

state.Pack(stream);

And that's basically the entire learning curve.

The difficult part isn't learning the API.

The difficult part is deciding what your domain actually means by its representation.

I think that's exactly where the difficult part belongs.

A Serializer Shouldn't Become Your Architecture

This is the idea that kept resurfacing while I built the package.

It's very easy for infrastructure to become the thing it was supposed to merely support.

A serializer starts storing metadata.

Then it starts deciding schemas.

Then it starts managing versions.

Then it starts talking to databases.

Then it starts managing transports.

Then it starts discovering domain types.

Eventually your "serialization library" is quietly running your architecture.

I wanted the opposite.

I wanted something I could put underneath the architecture and forget about until I actually needed to cross the boundary.

So the package can be reduced to one equation:

semantic state
      +
explicit representation rules
      +
byte boundary
      =
portable representation

Not:

object
  +
magic serializer
  =
architecture

That's the difference.

The Boundary I Want to Preserve

The entire package can ultimately be reduced to this:

                 DOMAIN
                   │
          owns meaning and rules
                   │
                   ▼
          Pack / Unpack contract
                   │
                   ▼
          FSM_Serialization
                   │
              byte boundary
                   │
        ┌──────────┴──────────┐
        ▼                     ▼
     storage               transport
        │                     │
        └──────────┬──────────┘
                   ▼
                  HOST
                   │
             manifestation

The serializer owns the boundary.

The domain owns the meaning.

The host owns the destination.

That is the architecture.

Why I Think Small Infrastructure Is Worth Talking About

There is a tendency in software writing to focus on the enormous systems.

The massive framework.

The clever algorithm.

The huge benchmark.

The complicated application.

But some of the most consequential architectural decisions are tiny.

An interface.

A boundary.

A decision about ownership.

A decision about what a component doesn't know.

FSM_Serialization is one of those experiments.

It isn't trying to replace every serialization technology in .NET.

It isn't trying to declare that binary is the future.

It is much more modest:

I needed a clean byte boundary for a growing compositional architecture, so I built the smallest one I could.

Then I tested it.

Then I benchmarked it.

Then I packaged it.

And now I'm putting it out there so somebody else can kick it.

You Don't Have to Take My Word for It

That's ultimately why I publish these projects.

Install it.

Implement one type.

Serialize something you actually care about.

Put it under your own workload.

Decide whether the ownership model makes sense to you.

Measure it.

Break it.

Tell me where the boundary doesn't hold.

That's much more interesting to me than somebody simply agreeing with the architecture.

The package is available now as an alpha.

And if you find a place where this tiny boundary lets you remove a surprisingly large amount of architectural mess, I'd genuinely like to hear about it.

Support Our Work:

Patreon Page:
https://www.patreon.com/c/TheSingularityWorkshop

Support Us (PayPal Donation):
https://www.paypal.com/donate/?hosted_button_id=3Z7263LCQMV9J

We'd love to hear your thoughts! Please Like this post, Love the code, and Share your feedback in the comments.

Design the Cursor, Not Just the Query

Mon, 28 Sep 2026 06:23:05 +0000

Pagination is often introduced as a performance improvement: fetch fewer rows, render less markup, and keep response sizes predictable. That is only half the job.

For an operational queue that changes while people work, pagination also defines what it means to continue reading. If that contract is weak, the database can answer every query correctly while the person using the screen still sees duplicates or misses work.

The important design question is not merely, “How many rows should this query return?” It is, “What does the next request mean after the underlying set has changed?”

Why offset paging drifts

Consider a queue ordered newest first. A reviewer asks for the first twenty-five rows. The next request uses an offset of twenty-five.

Between those requests, a new row arrives at the top. Every earlier row has moved down one position. The second query now begins with the final row from page one, so the reviewer sees a duplicate. More importantly, one unseen row has been pushed beyond the requested range.

This is not an exotic race. Append-mostly queues invite it because adding work is the ordinary operation. Offset paging treats positions as stable even though insertion changes every position below it.

Mutable sorting creates a similar problem. If the queue is ordered by status or last-updated time, an operator’s decision can move a row while the walk is in progress. A continuation based on that value inherits the instability of the workflow.

Continue from an immutable boundary

A stronger contract says: continue after the boundary returned by the previous read.

For a newest-first queue, that boundary can be an immutable creation or submission timestamp. New rows arriving above the boundary are not part of the current walk. They will appear when the reviewer starts again from the top, but they do not shift the meaning of “next.”

Equal timestamps need deliberate handling. Adding an identifier as a tie-breaker becomes fragile when data providers sort that type differently.

Another approach is to carry the boundary timestamp plus the number of rows already consumed at that exact timestamp. The database remains responsible for its native ordering within the tie, while the continuation records how far through that tie the walk has progressed. The detail matters less than the invariant: ties must neither duplicate nor hide rows.

Make the continuation part of the contract

An opaque cursor should not be a loosely encoded page number. It is protocol state, so treat it that way.

Useful safeguards include:

a version, so the format can evolve deliberately;
a strict length limit and parse validation;
the immutable boundary and tie position;
the active filter identity; and
sensible bounds on any stored count.

Binding the cursor to its filter is especially important. A position in “all open items” does not mean the same thing in “items for one category.” Reusing the cursor after changing filters can silently skip work. Rejecting that request is clearer than pretending the cursor is still meaningful.

Likewise, a malformed continuation should fail explicitly. Silently dropping it and returning the first page converts a bad request into a plausible-looking duplicate page. Operational software benefits from visible invalid states.

Keep every downstream read bounded

Paging the primary table is not enough if enrichment still loads data for the entire result set.

A common pattern reads the page, extracts its identifiers, and then fetches related summaries in a second query. That identifier list must come from the bounded page. Otherwise the visible query is paged while a hidden IN clause continues growing with the queue.

Fetching one extra primary row is a simple way to determine whether a continuation is needed. Return the requested page size, and issue a next cursor only when the extra row exists. The presence of that cursor—not whether the current page happens to be full—becomes the authoritative “has more” signal.

This also avoids an exact count on every read. For many live queues, “Page 3” plus Previous and Next is the more honest interface.

Carry the contract into the Blazor UI

Server-side continuation paging should not be wrapped in a client component that first downloads the entire queue. The UI has to follow the same contract.

A practical Blazor page can keep a small trail containing the cursor used to open each visited page. Next stores the returned cursor. Previous reuses the earlier cursor to re-read that logical page. After an operator records a decision, refresh the current page rather than throwing them back to the beginning.

Page changes should also clear any pending confirmation tied to a row that is no longer visible. That is a small state-management detail with a large clarity benefit: the user should never be asked to confirm an action on an item they cannot see.

Test the movement, not only the shape

Happy-path tests that assert “twenty-five rows returned” do not prove a paging contract.

The valuable cases exercise movement:

insert a newer row after reading page one, then verify page two has no gap or duplicate;
create several rows with the same boundary timestamp;
reject zero, negative, and excessive page sizes;
reject malformed, oversized, and filter-mismatched cursors;
verify related-data queries receive only current-page identifiers;
navigate Next and Previous in the component; and
perform an action and confirm the current page is refreshed.

These tests describe the promise a reviewer experiences, not merely an implementation detail.

The honest trade-off

Continuation paging is more work than offset paging. It needs a stable sort, a cursor format, versioning, filter binding, careful tie semantics, and focused tests. It also makes random access and exact page counts less convenient.

That cost is justified when the list is both live and operationally important. Bounded queries protect the system under bursty load; stable continuation protects the human workflow under concurrent change.

Takeaway: choose pagination from the mutation pattern, not from the table widget. If ordinary inserts can change what “next” means, the continuation itself deserves first-class design.

When EF Core's Design-Time Model Is Supposed to Be Incomplete

Sat, 26 Sep 2026 06:02:03 +0000

Framework warnings are useful because they compress hard-earned experience into an early signal. But a signal is not an invariant. In an extensible EF Core architecture, design-time tooling can legitimately see less of the model than the running application. If that difference is intentional, treating every pending-model warning as real drift can block a safe database update—or encourage a destructive migration.

The answer is not to ignore the warning casually. It is to understand exactly why it is false, then replace the lost signal with checks that understand the real architecture.

How a Valid Model Becomes Invisible

Consider a modular .NET application with a DbContext owned by a foundational module. Higher-level modules can contribute entity configurations through runtime discovery. This keeps the dependency direction clean: the foundational data module does not need references back to every feature that extends it.

At runtime, the host loads the feature assemblies and the DbContext receives the complete set of configurations. At design time, the EF Core tooling starts from the foundational project. Loading a higher-level contributor from there would create a circular dependency, so the design-time process builds a smaller model.

The migration snapshot still represents the complete model. The design-time differ compares that snapshot with its partial view and concludes that the contributed entity has disappeared. A probe migration may therefore contain a drop operation for a table that remains valid and necessary at runtime.

The tool is behaving consistently with the inputs it can see. The architectural context is what it lacks.

Prove the False Positive Before Suppressing It

Before changing warning behaviour, reduce the difference to something explainable.

Generate a disposable probe migration and inspect every operation. If the only reported difference is the known extension entity that design time cannot load, you have evidence for a visibility gap. If the probe also changes columns, indexes, relationships, or unrelated tables, stop: that may be genuine drift.

Then verify the full model independently. Run a snapshot comparison in a test process where all contributing assemblies are loaded. That test should compare the migration snapshot against the same model the application actually builds.

Only after both checks agree should the design-time factory suppress the specific pending-model warning. The suppression belongs at the narrow boundary where the false positive occurs, not in a broad configuration that hides the warning for unrelated contexts.

This is an important distinction: the warning is disabled because a stronger source of truth exists, not because the warning is inconvenient.

Turn the Destructive Failure Mode Into a Build Failure

Even after database update is unblocked, migration scaffolding may still use the incomplete design-time model. A future developer can generate a migration and receive a plausible-looking drop operation.

Comments and runbooks help, but they do not stop a merge. An executable guard can.

Inspect every migration's operations and fail if a protected extension table is dropped, renamed, or destructively altered. Cover structured operations such as table drops and column drops, but also inspect raw SQL for equivalent destructive statements. The goal is not a general SQL parser. It is a focused tripwire for the known architectural blind spot.

Add a positive control as well. The suite should prove that migration discovery found the migration which creates the protected table. Without that check, a broken scanner could inspect zero migrations and report a reassuring green result. A rejection-only test cannot distinguish “nothing is wrong” from “nothing ran.”

That small positive assertion dramatically improves the credibility of the safety test.

Keep the Test Harness Honest

Design-time factory tests often need temporary configuration, such as a process-wide environment variable containing a connection string. Two test classes that mutate the same variable can race: one restores the original value while the other is still constructing its context.

That creates a flaky failure which disappears when either class runs alone.

Treat process-wide configuration as shared mutable state. Put those tests in one serialized collection, restore the previous value in a finally block, and make it explicit that the connection value is only used to construct options when no database call is required.

This detail is adjacent to the model problem, but it matters. A safety test that flakes trains people to distrust or bypass it.

The Trade-Off Is Custom Safety Work

This approach is not free. The team must maintain a full-model snapshot test, a focused migration-operation guard, a positive control, serialized environment-sensitive tests, and documentation explaining which CLI signal is intentionally unreliable for this context.

The alternative is worse: reverse the dependency direction, abandon modular extension points, block legitimate database updates, or risk committing a destructive migration produced by a partial model.

The general rule is simple:

Identify why the generic check is wrong.
Prove the exact boundary of the false positive.
Suppress only at that boundary.
Replace the lost signal with a stronger invariant.
Add a positive control so the invariant cannot pass vacuously.

Framework defaults are valuable, but architecture-specific evidence is stronger. When design time and runtime intentionally see different worlds, make that difference explicit—and make the dangerous interpretation impossible to merge unnoticed.

A Page Is Not Shipped Until People Can Find It

Fri, 25 Sep 2026 06:06:10 +0000

A routed page can compile, pass its authorization checks, have documentation, and still be functionally absent. If the people entitled to use it cannot discover a normal way in, the product behaves as though the capability was never built.

That is easy to miss in a modular Blazor application. One team adds pages in one project, another module owns a second page tree, and a central hub or navigation catalogue tries to present the whole product coherently. Each local change can look correct while the experience between modules quietly breaks.

The remedy is not another release checklist. It is an executable discoverability contract.

Define the invariant at the page boundary

A useful rule is simple:

Every static operational page must have one intentional entry point whose visibility matches the page's access rule.

“Static” matters. A detail page with an identifier in its route is normally reached from a list, search result, or parent screen. It does not need a global menu item. A screen that answers on two route aliases is still one page; adding two cards would create duplication rather than discoverability.

The rule should cover pages, not merely strings that resemble URLs. That keeps the test aligned with the product concept people actually use.

It should also say “intentional entry point,” not “mentioned somewhere.” A link buried inside another page may technically make a route reachable, but it does not necessarily make the capability findable. Likewise, a help article that names a screen is documentation, not navigation. Requiring a deliberate card or menu entry forces the information architecture to be explicit.

Scan every module, not only the original tree

Architecture tests often begin with a useful local assumption: all administrative pages live under one directory, namespace, or assembly. The test passes for years. Then a new module introduces another tree and the guard continues to report green because it never sees the new pages.

This is a particularly awkward failure because both the feature and the guard are “working as designed.” The design boundary is simply stale.

The test therefore needs a completeness check as well as a matching check. Enumerate every known page tree. Parse the routed components. Exclude only clearly contextual routes. Then compare the resulting pages with the navigation catalogue.

Add a sanity assertion too. If a mature tree suddenly produces zero—or far fewer—pages, the parser or directory assumption probably broke. Without that guard, a failed scan can look like perfect compliance.

When a new module owns pages, extending the scan is part of integrating that module. This turns architectural coverage into an explicit responsibility rather than inherited folklore.

The navigation entry should use the same access decision as the destination page. If the card is broader, people see an invitation that ends in refusal. If it is narrower, people who are entitled to use the page cannot find it.

It is tempting to reuse a nearby permission because it is convenient. That can be wrong in both directions. When no existing decision expresses the page's real audience, adding a focused visibility flag is usually clearer than bending an unrelated one.

But matching visibility does not turn navigation into security. A hidden card only changes what the interface presents. A direct request, a bookmarked address, or another client can still reach the endpoint. The page or server operation must continue to enforce authorization independently.

This separation produces a healthy pair of invariants:

navigation makes entitled capabilities discoverable;
authorization rejects requests that are not entitled.

Testing both is stronger than asking either mechanism to do two jobs.

Prefer a precise contract over “linked somewhere”

A broad reachability scan can be a good first diagnostic. Search the codebase for links to each route and identify pages that have no inbound reference. That quickly reveals obvious orphans.

As a permanent contract, however, “linked somewhere” is weak. A tab rail is visible only after someone has already reached a page in that tab set. A contextual link may depend on data or state. A help page may mention the route without providing product navigation. Source text can prove that a string exists; it cannot prove that the intended audience has a clear entry point.

Tightening the rule to require the chosen navigation catalogue makes the standard less ambiguous. It also creates useful pressure: when a page fits nowhere, the team must decide whether the navigation model is incomplete, the page is contextual, or the feature should not be exposed yet.

Accept the maintenance cost deliberately

The stricter contract adds work. New pages need catalogue entries, accurate visibility mapping, and suitable grouping. Route conventions must be understood well enough for the test to distinguish static pages, detail pages, and aliases. Large navigation surfaces may expose sections that no longer fit their historical categories.

Those are not test problems to hide with a long exemption list. They are product and architecture decisions the test has made visible.

Keep exemptions small, named, and justified by a navigation model rather than by inconvenience. Fail when an exemption becomes stale. If a page genuinely belongs behind a list or workflow, encode that reason. If it is an operational destination, give it an intentional entry point.

The payoff is modest but durable: completed capabilities do not disappear between modules, permission drift becomes easier to see, and a new page cannot quietly land outside the product's navigation contract.

A page is not shipped merely because its route exists. It is shipped when the right person can find it—and the wrong person still cannot execute it.

A Retry Is Not Safe Until the Side Effect Is Safe

Thu, 24 Sep 2026 05:56:30 +0000

A retry can duplicate a side effect even when the original command completed successfully.

This is easy to miss in a method that does two ordinary things: save a record and send a message. Each operation is understandable on its own. The difficult part is the uncertainty between them.

Suppose an endpoint creates an invitation, persists it, asks an email provider to deliver a link, and returns a response. The database commit succeeds. The provider may accept the message. Then the network drops the response. The client cannot tell whether anything happened, so it retries.

If the server repeats the whole method, it can create another record, another secret, or another email. The code has turned a lost response into duplicated authority-bearing side effects.

The lesson is broader than invitations: design the durable commit point, provider boundary, and retry contract as one workflow.

Commit the fact before announcing it

Sending before saving creates the most confusing failure mode. A recipient receives a plausible link, but the backing operation never committed. To them, the system appears to reject a valid action for no visible reason.

A safer ordering is:

Validate the command.
Create the durable operation.
Store an idempotency receipt that points to that operation.
Commit both together.
Only then ask the external provider to send.

The durable record becomes the source of truth. The message announces a fact that already exists rather than promising that a later write will probably succeed.

This does not make the database and email provider atomic. It gives the gap between them explicit semantics.

Make replay return, not repeat

An idempotency key is useful only when it protects the irreversible side effect too.

The receipt should bind a caller-generated command key to a stable fingerprint of the request. If the same key returns with the same request, the service reads and returns the original result. It does not send again. If the key returns with different input, the service rejects the conflict rather than guessing which request the caller intended.

The database should also enforce uniqueness. Two identical requests can arrive concurrently before either sees the other's receipt. Let one commit win; have the loser load and return the winning result. Otherwise a perfectly designed application check can still race.

The important invariant is not merely “one row.” It is “one durable result and one automatic send for one command.” Tests should assert both.

Unknown is not the same as failed

Provider calls rarely produce only success or failure. They produce at least three useful outcomes:

Accepted: the provider acknowledged the message.
Definitely rejected: the provider did not accept it.
Unknown: the caller lost certainty, often through a timeout or interrupted response.

Unknown is the dangerous one. The message may already be queued. Reporting a definite failure can encourage an immediate retry and a second message.

This is a small state-model decision with a large operational effect. Do not collapse “I do not know” into “it did not happen.” Preserve uncertainty so the recovery path can respond deliberately.

Keep a recovery handle

If delivery is definitely rejected after the database commit, deleting or closing the record may feel tidy. It also removes the user's only handle on the problem.

Keeping the durable operation pending can be more honest. The UI can show that it exists, report that delivery failed, and offer an explicit resend. That resend is a new action, not a transparent replay of the original command.

For a message carrying a secret, explicit resend should rotate the secret, invalidate the old link, persist the new state, and then send. Leaving both links active multiplies hidden authority. Reusing a raw secret is often impossible or unsafe if only its hash was stored.

This recovery model needs expiry, status visibility, observability, and clear language. “Pending” must not imply “delivered.” The system should say what it knows and avoid claiming what it cannot know.

Test the gaps, not only the happy path

The valuable tests live at the boundaries:

Repeating the same command returns the same result, leaves one durable record, and sends once.
Concurrent duplicates converge on one receipt and one result.
A definite pre-provider rejection is reported while the recovery record remains available.
An unknown outcome is not presented as definite non-delivery.
Explicit resend invalidates the earlier secret before attempting delivery again.
The provider is never called before the database commit succeeds.

These tests express the reliability contract better than a broad “request succeeds” test. They also make later refactoring safer because the order and meaning of side effects are visible.

The trade-off is honest complexity

This design is not free. It introduces command receipts, request fingerprints, provider outcome types, pending states, expiry, and explicit recovery. Operators need enough telemetry to distinguish rejected sends from unknown outcomes. Product language must explain uncertainty without alarming users.

The alternative is simpler code with less truthful behaviour: phantom links, duplicate messages, or retries that silently create extra authority.

My practical review question is: for every workflow that combines a database write with an external side effect, can we point to the commit point, replay rule, uncertainty model, and recovery action?

If those four answers are explicit, retries become a designed part of the workflow rather than a hopeful repetition of it.

When a Green Test Protects the Wrong Authorization Rule

Tue, 22 Sep 2026 07:08:12 +0000

An automated test is useful only when its assertion represents the rule we intend to preserve. That sounds obvious until a test passes for the exact condition that should make a reviewer uneasy.

A recent Blazor change offered a concrete reminder. Two routed administrative pages required a signed-in user but did not assert a permission policy at the page. The links that led to them were filtered by permission. That made the interface look appropriately restricted, while a signed-in person could still enter the URL directly. Two existing tests expected the permissive page attributes, so the green suite helped the gap survive.

The engineering lesson is broader than those pages: when a test blesses an authorization omission, fix the assertion and add an invariant that catches the next omission. Keep the invariant honest about what it can and cannot prove.

Consider an administrative interface with a configuration card. The card appears only when the current viewer has a configuration permission. The destination page, however, asks only whether the viewer is signed in. Hiding the card changes what the viewer sees; it does not change what the route accepts.

The direct URL is the simplest counterexample. If the user knows or guesses it, the navigation filter is bypassed. A page-level policy is needed to decide whether that route may render for the viewer. The underlying API or command must make its own authorization decision as well. These checks serve different entry points, so one cannot stand in for the other.

In the inspected change, the page policies were added. One data endpoint already had a stricter authorization rule and kept it. The lesson is to review each boundary on its own terms: visible link, routed page, and operation.

Read assertions as product decisions

The surprising part was not that a page attribute was too broad. It was that tests explicitly expected that breadth. One assertion accepted the absence of a policy; another looked for a bare sign-in attribute. Those statements had made an implementation detail into a contract.

When correcting a test like this, start by naming the intended behaviour in plain language. For example: “This routed configuration page requires the configuration policy.” Then inspect the compiled authorization attribute and assert that policy. This makes the test follow the behaviour the framework will see, rather than a particular text fragment in a Razor file.

That specific test matters even if a broader scan exists. A scan can report that a policy is present, but a policy for an unrelated administrative task could still pass it. The page-specific assertion checks the narrower decision about which permission belongs there.

Turn the omission into an invariant

The change also added a structural test over routed administrative pages in two application areas. It checks whether each page asserts a permission policy. The test has a nonempty coverage guard, because a scan that accidentally finds zero pages is worse than a failing scan: it can look reassuring while doing nothing.

This is a useful pattern for requirements that should apply across a family of files. A single page test protects a known case. A route scan makes it harder for a new page to repeat the same omission. Neither test needs to simulate every user and role to answer the structural question, “Did this route declare a permission policy?”

The boundary of that answer is important. The scan does not prove that every declared policy is correct. It does not prove that an API rejects unauthorized calls. It does not prove that authorization is complete across the product. Those claims require different tests and review.

Make exceptions accountable

Some landing pages can legitimately be available to any signed-in viewer because their contents filter themselves by the viewer's permissions. A blanket rule that rejects every such page would create noise and encourage people to weaken the test. The committed scan therefore allows explicit exemptions with reasons.

An exemption is still a maintenance obligation. If a page is deleted, renamed, or later gains a policy, its old exemption should disappear. A second test checks for those stale entries. It keeps the exception list from becoming a historical catalogue that a future developer might mistake for permission to add more exceptions.

The two corrected pages are pinned separately. That matters because someone could otherwise make the broad scan green by putting a vulnerable page on the exemption list. The pinned tests say those particular pages must keep their policies and cannot be exempted.

The same change initially documented a separate unresolved permission decision as a known gap. A follow-up commit assigned that page a policy after an owner made the decision. Recording the gap first kept the review honest while the right policy was decided rather than guessed from a neighbouring page.

The practical review sequence

When a green test has protected the wrong rule, I use this sequence:

Reproduce the bypass at the relevant entry point in a controlled test or review, such as direct route access rather than clicking the navigation card.
State the intended permission and correct the local assertion so it checks the framework-visible attribute.
Add a structural invariant if the same omission can recur across many pages.
Give every real exception a reason, and make stale exceptions fail.
Keep page and operation authorization under separate review; presence of a page policy is only one piece of evidence.

This approach costs some test and exception-list maintenance. The benefit is a much earlier signal when another route omits a policy, while the specific assertions preserve the decisions that matter most. A green suite should mean that our intended boundary is holding, not merely that yesterday's implementation has stayed the same.

Offline Readiness Is a State-Machine Contract

Mon, 21 Sep 2026 06:07:42 +0000

“Make it work offline” often turns into a storage task: serialize the last successful response, read it when the network fails, and move on.

That is necessary, but it is not the hard part.

The hard part is deciding what the stored response means across launch, failure, reconnect, configuration change, and session recovery. Once a mobile application depends on runtime configuration, offline readiness becomes a state-machine contract. A cache is only one implementation detail inside that contract.

Find the contradictory assumptions first

Consider a .NET MAUI wrapper hosting a Blazor UI. A lower startup layer may correctly treat a reachability probe as diagnostic: the network can be absent, so failure should not prevent launch. But a higher layer may immediately call a runtime-configuration endpoint and require a successful answer before activating the application scope.

Each layer looks reasonable in isolation. Together they disagree.

The lower layer says, “reachability is not a launch gate.” The higher layer says, “no live response, no ready state.” A short outage is then presented as invalid configuration even though nothing has been invalidated.

This is why I like to draw the complete launch state machine before changing storage. List the states—uninitialised, resolving, ready from live data, ready from fallback data, unavailable—and name the events that move between them. Contradictions become much easier to see when they are transitions rather than scattered if statements.

Classify failure before consulting the cache

Not every failed request grants permission to use stale data.

A timeout, lost connection, or temporary server error says, “the current answer is unavailable.” A recent cached configuration may be the best safe answer.

An authoritative not-found or gone response says something different: “this configuration no longer exists here.” Serving the cache would override current server knowledge with old local knowledge. That is not resilience; it is refusal to accept invalidation.

So the order matters:

Attempt the live load.
Classify the failure.
Consider fallback only for the transient class.
Clear the fallback when an authoritative response makes it wrong.

This distinction is reusable well beyond configuration. Offline permissions, feature manifests, routing metadata, and other control-plane data all need an explicit invalidation rule.

Make “recent enough” a real policy

Even a transient failure does not make every cached value safe.

A useful policy checks at least four things. The entry must belong to the same logical scope. It must come from the same configured source. Its age must be within a deliberate bound. Its timestamp must not be implausibly far in the future.

Source binding is easy to miss. Runtime configuration often contains addresses and capability switches. If an application is repointed but continues serving a cache captured from the old source, it may look healthy while sending work to the wrong place. Treating a source change as a cache miss is safer and easier to reason about.

The age bound is a product and operational decision, not a magic constant. It should cover the outages the application is expected to tolerate while still placing a limit on how long retired configuration can survive. Document the reasoning so the next engineer knows whether changing it is a reliability decision or a cosmetic edit.

Clock skew deserves a rule too. A future-dated entry can otherwise remain “fresh” for far longer than intended.

Preserve continuity when connectivity returns

An application that opens from fallback data is usable, but not settled. It should carry an explicit “needs refresh” hint.

When connectivity returns, the tempting implementation is to rerun the entire startup pipeline. That can be surprisingly destructive. Full reinitialisation may advance a session epoch, cancel in-flight requests, clear actor state, restart background rails, and remount the renderer. On a flapping connection, users can pay that cost repeatedly.

Prefer an in-place refresh while the current scope remains valid. Update the runtime configuration, clear the refresh hint, and let the active session continue. Escalate to full resolution only if the refresh proves that the scope disappeared or changed in a way that makes continuity unsafe.

This gives reconnect two distinct transitions:

unavailable to online: resolve fully because there is no active scope to preserve;
ready-from-fallback to online: refresh in place because there is useful state to protect.

Those transitions may share a network event, but they should not share an indiscriminate reset.

Let storage fail softly—and test the wiring

Device storage is another dependency, not a certainty. Reads can fail, writes can fail, and cleanup can fail. If a cache exists to make cold start more resilient, an escaping storage exception must not become a new cold-start crash.

Fail-soft behaviour should be intentional: a failed read behaves like a miss, a failed write loses future offline convenience, and a failed clear remains bounded by the expiry policy. Cancellation is different and should still propagate.

Test the serializer separately with round trips. A cache that writes successfully but cannot read its own format is indistinguishable from having no fallback at all.

Also test dependency-injection resolution through the real container. Optional constructor dependencies are convenient, but they can compile and quietly fall back to a null implementation when registration is missing. A focused integration test proves that the platform adapter actually reaches the service.

The trade-off is explicit complexity

This design is more complex than “try the network, then read a file.” It introduces failure classification, cache provenance, expiry, clock rules, lifecycle state, reconnect transitions, serialization, and a wider test matrix.

That complexity is buying something concrete: continuity without pretending stale configuration is always correct.

The practical review question is not, “Do we have a cache?” Ask instead:

Which state are we in, what evidence permits this fallback, and what is the least disruptive path back to live truth?

If the implementation can answer that clearly, offline readiness has become a deliberate contract rather than an accidental side effect.

Pagination Is a Consistency Contract

Sun, 20 Sep 2026 07:52:36 +0000

Page numbers feel harmless. They are familiar, easy to render, and easy to explain. But on a mutable work queue, they can lie.

Imagine a reviewer reading a newest-first queue. They load the first 25 items. Before they request the next page, a new item arrives at the top. An offset such as skip 25 now starts one row later than it would have a moment ago. The last row from page one may appear again, and the row displaced by the insert may never appear in that walk.

Nothing crashed. No error was logged. The interface simply presented an inconsistent view of the work.

The engineering lesson is that pagination over changing data is a consistency contract, not a decorative control beneath a table.

Begin with the mutation model

The right pagination strategy depends on how the collection changes.

For an append-mostly queue ordered newest first, new work normally arrives above the operator's current position. Other fields, such as workflow status, may change while the operator is reviewing an item. Those two facts suggest a useful boundary: continue from something fixed when the item entered the queue, not from a mutable field and not from the current numeric position.

A submission timestamp can provide that boundary if it is frozen when the item is created. Status usually cannot; ordering by status lets a decision move rows between pages while someone is walking the list.

The principle is broader than timestamps: choose an ordering key whose meaning remains stable for the duration of a walk.

Make the server own the continuation

A client should not reconstruct position from a page number, a visible row, or a guessed offset. The server should return an opaque continuation and accept it unchanged on the next request.

For a newest-first queue, a continuation can describe the last timestamp boundary and how many rows at that exact instant have already been emitted. The next query includes rows at or below the boundary, skips only the already-seen ties at that boundary, and takes one extra row to determine whether another page exists.

Why count ties instead of comparing an identifier? Identifier ordering is not always portable across database providers. Let the query provider apply its established ordering, and record only how far through the boundary group the walk has progressed.

Opaque does not mean unchecked. Reject blank, malformed, oversized, or unsupported continuations. A bad continuation should not silently restart at the top, because a restart looks like valid data with unexplained duplicates.

Bind position to query context

A continuation names a position in one specific ordered result set. Change the filter and that position may no longer mean anything.

Suppose page one was filtered to one workflow cycle, then the same continuation was replayed with the filter removed. Honouring it could skip rows that were never part of the original walk. The continuation should therefore carry enough context to prove it belongs to the active query. If the context differs, refuse the request and let the client restart explicitly.

The same discipline applies to page size. Put a small upper bound in the contract and reject values outside it. Quietly shrinking an oversized request hides caller mistakes; accepting it defeats the point of paging.

Bounding the first query is only half the work. If each row needs evidence, comments, or another related record, fetch those details only for identifiers on the current page. Otherwise an apparently paged endpoint can still perform an unbounded secondary read.

Preserve the operator's place

Continuation cursors naturally move forward. A usable review screen also needs Back and refresh.

The client can keep a short trail of the server-provided continuations used to open each visited page. Previous then replays the cursor that originally opened the prior page. The client is not interpreting the cursor; it is remembering the path.

After a reviewer changes an item, refresh the page they are currently viewing. Returning to page one after every decision is technically simple and operationally punishing. It also encourages people to work around the interface rather than trust it.

There is one awkward edge case: a later page may become empty before it is refreshed. Do not render a global empty-state message that implies the entire queue has vanished. Reset to the first page and show the current truth from a valid starting position.

Test the walk, not only the query

Happy-path tests that assert “25 rows returned” are not enough. The important properties live between requests.

Useful executable checks include:

a new item arriving above the boundary neither duplicates nor hides an existing row;
a workflow status change does not alter page membership;
several items sharing one timestamp are neither repeated nor lost;
a continuation cannot be replayed with a different filter;
malformed continuations and invalid page sizes are refused;
forward and backward navigation use the exact server continuations;
a write refreshes the active page; and
an empty later page recovers without claiming the whole queue is empty.

These tests describe the contract more clearly than the word “paged” ever could.

The trade-off is explicit complexity

Cursor paging asks more of both sides. The server must define and validate a stable continuation. The client must retain a small history. Ties and disappearing pages need deliberate behaviour. Troubleshooting is less intuitive than looking at page=3 in a URL.

In return, database work stays bounded and a reviewer can walk a changing queue without silent duplicates or gaps. That is a worthwhile trade whenever missing one item matters more than keeping the paging code superficially simple.

Before choosing offsets for a mutable list, simulate one insert and one update between consecutive requests. If the same walk no longer produces the same set of rows, the pager needs a stronger contract.

When EF Core Sees Only Part of Your Model

Sat, 19 Sep 2026 12:18:35 +0000

Framework warnings are valuable because they turn hidden risk into visible friction. But a warning is still an interpretation of the evidence available to the tool. In a modular application, the command-line process may not load the same assemblies as the running application. When that happens, the design-time model can be a projection rather than the whole truth.

That creates an uncomfortable situation: a migration warning may be both technically correct about the model it sees and dangerously wrong about the database operation it proposes.

The answer is not to ignore warnings casually. It is to identify the boundary, narrow the exception, and replace the lost signal with a stronger executable invariant.

The model can change with the process

Consider a lower-level persistence module that owns a database context. At runtime, higher-level modules can contribute entity configurations through a discovery mechanism. This preserves the dependency direction: the lower-level module does not need references back to every feature that extends it.

Now run command-line migration tooling from the lower-level project. The higher-level contributor may not be loaded, because adding that reference would create a project cycle. The tool builds a valid model, but it is only the portion visible from that process.

The migration snapshot, meanwhile, includes the contributed table. It was created from the full application model and must remain there for every host that uses the shared schema.

The differ compares those two views and concludes that the table exists in the snapshot but not in the current model. Its proposed fix is logical from that narrow perspective: drop the table.

From the system’s perspective, that operation is destructive.

Regenerating the snapshot until the warning disappears is tempting. It is also exactly the wrong response when the design-time model is incomplete by construction.

The first diagnostic question should be: what is the entire proposed difference? A probe migration can make the answer concrete. If the only change is removal of a table supplied by a module that the tooling process cannot load, the warning describes a visibility gap—not necessarily real drift.

This distinction matters. “The warning is a false positive” is too broad. A particular warning, for a particular context, under a documented loading boundary may be a false positive. Other differences could still be real.

The safe decision is therefore narrow: allow the legitimate database-update path to proceed despite that one known condition, while keeping a separate full-model comparison as the authoritative drift test.

Suppression spends a safety signal

Ignoring a warning removes friction. It does not remove the underlying ambiguity.

If a design-time factory suppresses a known pending-model warning, the team has spent a safety signal. That signal should be replaced with evidence closer to the failure mode.

In this case, the feared outcome is not an abstract “model mismatch.” It is a migration that drops, renames, or damages a table the design-time process cannot see. That can be tested directly.

An executable migration guard can inspect the operations produced by every committed migration and fail when it finds:

a drop of the protected table;
a rename that moves it out of the contract;
a column removal targeting that table; or
raw SQL containing the destructive operation.

This is more specific than the original warning, and that specificity is a strength. The test says exactly which invariant must survive.

Negative guards need positive controls

There is a subtle testing trap here. A test that scans migrations and finds no forbidden operation can pass because the migrations are safe—or because discovery found nothing.

That is a vacuous pass.

Add a positive control that proves the scan sees the migration that originally created the protected table. Now the pair of tests establishes both halves of the claim:

the evidence set is present; and
none of that evidence violates the destructive-operation invariant.

This pattern generalizes well. Whenever a test says “nothing bad exists,” pair it with proof that the search space is populated. It is useful for dependency scans, authorization maps, route inventories, migration checks, and reflection-based conventions.

Keep the full model as the authority

The migration guard protects one known destructive edge. It does not prove that every legitimate model change has a migration.

For that, retain a snapshot comparison that runs in a process where all runtime contributors are loaded. That test compares the snapshot with the full model rather than the design-time projection.

These checks have different jobs:

the full-model comparison detects real snapshot drift;
the migration guard blocks the known destructive artifact;
the positive control proves the guard actually inspected meaningful input; and
the narrowly scoped suppression keeps the operational update path usable.

Together, they are stronger than treating one framework warning as universally authoritative.

The trade-off is deliberate maintenance

This approach is not free. The guard knows about a specific architectural boundary. If extension mechanics change, the tests and documentation must change with them. Contributors need to understand why the suppression exists and why generated migration output still requires review.

The alternative is worse: either block legitimate operations forever, or normalize a habit of dismissing warnings and accepting generated drops.

The practical review rule is simple: when tooling sees only a projection, document the blind spot, scope the exception, and encode the real safety property as a failing test. Framework diagnostics are excellent inputs. Your architecture still owns the final claim.

A Successful Security Call May Prove Nothing

Sat, 19 Sep 2026 11:45:44 +0000

Security integrations often fail in a surprisingly polite way. The library loads. Initialization succeeds. The function returns. Nothing crashes. Yet the protection we expected may not have participated at all.

That distinction matters when an application accepts untrusted documents that another person may later open. The relevant question is not “did the scanning API answer?” It is “did a real security engine inspect this content and produce a trustworthy verdict?”

A recent engineering change reinforced a pattern worth carrying into other systems: prove the capability end to end, fail closed when the proof is missing, and preserve the difference between malicious content and content that has not been judged.

Integration health is not capability health

Suppose an operating-system security interface sits between your application and whichever antimalware product is installed. It is tempting to treat successful initialization as a health check. A clean transport result feels even stronger: the call returned normally and reported nothing detected.

But an integration layer and its downstream provider are separate things. The interface can be present while the engine behind it is stopped, unavailable, or incorrectly registered. In that condition, a nominal response may demonstrate only that the front door opened.

This is a general reliability problem, not an accusation against one API. Message brokers can accept a connection while a critical consumer is stalled. A secrets client can authenticate while the expected key is unavailable. A feature-flag SDK can initialize while serving stale defaults. Health must be defined by the capability the application depends on, not by the first component in the chain.

For a document scanner, “the library loaded” is weak evidence. “A known signal travelled through the production scanning path and produced the expected security verdict” is much stronger.

Test the behaviour you actually depend on

The design used a harmless standard test signal that security engines are expected to recognize. The literal signal does not belong in application content or public examples; what matters is its role.

At startup, the application sends that signal through the same in-memory scanning boundary used for uploaded bytes. The feature is registered only if the expected detection comes back. On unsupported hosts, or when no live engine answers, the risky upload capability remains unavailable.

That is a capability probe. It asks the downstream system to demonstrate the exact category of behaviour the application needs before the application trusts it.

The same proof is repeated when a scan begins. Startup checks become stale. A service can stop, a provider can be disabled, or policy can change while the host remains running. Rechecking at the point of use makes failure visible before untrusted content is accepted as safe.

This does add work. A liveness probe consumes a small amount of time, and the application may temporarily deny uploads during a dependency outage. That cost is deliberate. Availability is being traded for an honest security boundary rather than for a comforting but unsupported status flag.

“Malicious” and “not judged” are different states

Failing closed does not mean treating every failure as malware.

A positive engine verdict can justify refusing a document. An administrator policy may also explicitly block it. Those are security decisions based on evidence.

An exception is different. The bytes may be missing. The scanning interface may fail to initialize. The engine may disappear between startup and use. None of those facts proves that the document is malicious. They prove that the system does not have a verdict.

A useful state model keeps at least three outcomes separate:

Cleared: the control produced an acceptable verdict.
Refused: the control positively detected or blocked the content.
Pending: the system could not obtain a trustworthy verdict.

Collapsing the third state into “cleared” silently weakens security. Collapsing it into “refused” creates false certainty and can turn a temporary infrastructure fault into a permanent user-facing decision. Leaving the item pending supports a retry, an operational alert, or a safe recovery path while remaining truthful about what happened.

Keep adjacent boundaries aligned

The scan is only one part of the upload boundary. The storage layer still owns how opaque keys resolve to files, including protection against paths escaping the intended root. The scanner should use that existing resolver rather than copying path logic into a second component.

That avoids a subtle split-brain problem: storage accepts one interpretation of a key while scanning uses another. Security checks are strongest when every stage inspects the same bytes through the same trusted boundary.

Tests should reflect those boundaries too. Pure verdict mapping can be tested with ordinary inputs, but the liveness question deserves at least one test against the real host integration where the platform permits it. A mock can prove that our code handles the answer we programmed the mock to return. It cannot prove that the downstream engine is actually answering.

Useful tests include clean content, blocked-result ranges, an unavailable provider, missing bytes, and traversal attempts. Together they exercise the difference between a positive verdict, an operational failure, and an invalid storage request.

A practical review checklist

When reviewing a security or reliability integration, I now ask:

What observable behaviour proves the downstream capability is alive?
Are we checking a transport, a library, or the outcome we actually need?
Can the dependency fail after startup, and is it checked again at use time?
Does failure disable the risky capability or quietly weaken it?
Are positive security verdicts kept distinct from operational errors?
Does the test suite cross the real boundary that a mock would hide?

The broader lesson is simple: successful plumbing is not the same as successful protection. Trust the capability only after it demonstrates the behaviour your application depends on—and keep uncertainty visible when it cannot.

Your Reader Cannot Be Stricter Than Your Schema

Thu, 17 Sep 2026 08:20:48 +0000

SingleOrDefault looks like a small query choice. In practice, it is an assertion about your data model: for this predicate, zero or one row may exist.

That assertion is valuable when storage enforces the same rule. When the database permits duplicates, however, the reader is relying on an invariant that does not exist. One unexpected row can turn an ordinary lookup into an exception before validation, authorization, or other normal handling begins.

I recently reviewed a committed recovery for exactly that class of mismatch. The useful lesson was not the specific lookup. It was how to contain the exception without pretending the data had become correct.

A query can encode a hidden contract

Consider a generalized account table:

Rows permitted by storage: 0..many per normalized key
Rows expected by reader:    0..1 per normalized key

The read path might be perfectly reasonable in isolation:

var record = await records.SingleOrDefaultAsync(x => x.LookupKey == key);

But the method name does not create uniqueness. It only checks cardinality at read time. If two rows match, the query throws.

This is why I now treat Single and SingleOrDefault as executable invariant assertions. During review, I ask: what proves the invariant? A unique index? A constrained aggregate? A transactionally protected write path? Or only an earlier existence check that can race?

Containment is not repair

When duplicate data already exists, immediately adding a unique index may be unsafe. Migration can fail on the existing rows. Previously accepted imports or registrations may begin failing without a useful remediation path.

At the same time, leaving a critical read path to throw can make a narrow data defect disproportionately disruptive.

A staged response separates two goals:

Containment: provide a deterministic, non-crashing resolution path while preserving security and making the defect visible.
Correction: repair the existing data and enforce the intended rule for future writes.

The distinction matters. A tolerant reader is a recovery mechanism, not evidence that duplicates are acceptable.

Properties of a safe recovery path

A useful containment pattern keeps the normal case boring:

try
{
    return await ReadExpectedSingleAsync(key);
}
catch (InvalidOperationException)
{
    var matches = await ReadBoundedCandidatesAsync(key);
    if (matches.Count < 2)
        throw;

    ReportCollision(matches.Select(x => x.OpaqueId));
    return ChooseDeterministically(matches);
}

This sketch is intentionally incomplete, but it highlights several important properties.

Keep the fast path unchanged

Most lookups are not ambiguous. Do not make every request pay for a corruption-recovery query. Invoke the fallback only after the expected lookup demonstrates the precise failure you are prepared to handle.

Prove ambiguity before handling it

InvalidOperationException can come from many places. Catching it and returning “not found” would turn an unrelated store failure into a silent wrong answer. Re-query narrowly; if there are not actually multiple matches, rethrow the original fault.

Choose deterministically

Never accept database enumeration order as a resolution policy. Define explicit ranking from legitimate domain facts, then add a stable final tie-break. The same data must produce the same candidate on every attempt.

Determinism does not make the selected record correct. It prevents the recovery itself from becoming random.

Preserve downstream verification

Resolving one candidate must not grant access, approve a transaction, or bypass an eligibility rule. Credential checks, authorization, state validation, and other security decisions still run after resolution. Containment should make the lookup deterministic, not weaken the boundaries that follow it. A legitimate candidate may still lose the ranking, so some affected operations can remain unavailable until the data is repaired.

Bound and observe the fallback

A pathological key should not cause an unbounded scan during a critical request. Cap diagnostic reads, raise a high-signal operational event, and log only what responders need. Opaque record identifiers may support repair; the sensitive lookup value often does not belong in logs.

The stronger end state lives in storage

After containment, the work is not finished. The durable sequence is usually:

inventory collisions
-> decide merge or deletion policy
-> repair existing rows
-> reject or reconcile conflicting writes
-> add the storage constraint
-> remove or narrow temporary recovery code

For relational data, that often means a unique index aligned with the normalization and null semantics used by the application. The write path should return a useful domain result when the constraint rejects a conflict. A pre-insert lookup can improve the message, but the database remains the concurrency-safe authority.

There is a real trade-off. Immediate enforcement gives the cleanest future guarantee but can break deployment against historical data. Temporary tolerance contains the exception but adds policy, cannot guarantee later verification will succeed, and can become permanent by neglect. Treat it as migration work with an owner, telemetry, and an exit condition.

Test the invariant and the escape hatch

Focused tests should cover more than “duplicates do not throw.” I would pin:

the ordinary single-row path remains untouched;
selection is stable when candidates arrive in different orders;
inactive or retired records cannot outrank valid ones;
unrelated exceptions escape unchanged;
downstream verification still decides the outcome;
diagnostics contain repairable identifiers but no sensitive key;
the candidate read is bounded;
the future uniqueness constraint rejects a conflicting concurrent write.

The deeper lesson is architectural: reads, writes, and storage must agree on cardinality. If a reader says “exactly one,” make that promise explicit at the boundary able to enforce it. Until then, the code is not reading an invariant. It is discovering, at runtime, whether the hope was true.

Realtime Is a Hint, Not Your Source of Truth

Thu, 17 Sep 2026 08:20:15 +0000

A notification badge looks like a small feature. In a distributed application, it can expose a large architectural assumption.

I recently investigated a badge that sometimes stayed stale in an ASP.NET Core and Blazor application running across multiple server instances. The notification itself had been created successfully. Durable state was correct. A separate push path could also complete. Yet the visible count did not always change until the user left the screen and returned.

The bug was not really about arithmetic. It was about assigning too much authority to a realtime transport.

The hidden assumption

The UI initially loaded its count from the server and then relied on live events to remain current. That feels reasonable while developing against one server with a stable connection. In production, several ordinary conditions weaken the assumption:

The client can disconnect briefly.
A load balancer can place the sender and receiver on different instances.
A workflow can create the same durable state without passing through the page that happens to broadcast.
A transport or hub can fail after the database operation has already succeeded.
An idempotent retry can revisit work that should not increment the UI again.

None of these conditions makes realtime technology a poor choice. They simply mean that a realtime message should usually be treated as a hint that fresh state is available, not as the state itself.

A three-layer reliability pattern

The repair became much clearer once the responsibilities were separated into three layers.

First, persist the truth

The durable record must be committed independently of whether any connected client is listening. If the user closes the app, changes networks, or connects to another instance, the correct unread state must still be recoverable later.

This ordering matters. Broadcasting first can produce a convincing UI update for data that subsequently fails to commit. Persisting first means a missed broadcast can be healed; an invented broadcast cannot be trusted.

Second, broadcast from the business chokepoint

The live update originally depended on a narrower UI workflow. Other creation paths could produce the same durable result without emitting the event. Moving the broadcast to the shared dispatch path made the behavior consistent across interactive and background work.

The broadcast was also tied to the outcome of the durable write. A genuinely new record emits a hint. An idempotent replay that finds the work already completed does not. That prevents duplicate increments and makes the event reflect a real state transition rather than merely an attempted command.

Third, reconcile periodically

Even a correctly placed broadcast can be missed. The client therefore refreshes the authoritative count on a bounded interval. The loop is cancelled when the component is disposed, and a transient refresh failure does not kill future attempts.

This is not polling as the primary experience. Realtime still gives the fast path. Polling is the repair path.

The trade-off

Hybrid delivery is not free.

Periodic reconciliation adds read traffic. The interval also defines a maximum period of visible staleness when a realtime event is missed. A very short interval increases load and can waste battery or bandwidth on mobile clients. A long interval lowers cost but leaves stale UI visible for longer.

That makes the interval a product and operational decision, not a magic constant. Ask how damaging stale information is, how expensive the read is, how many active clients exist, and whether the endpoint can use a cheap aggregate or cache.

For a badge, bounded staleness may be acceptable. For a payment confirmation or permission change, the interaction may require an immediate authoritative read instead. The pattern stays the same, but the recovery budget changes.

Failure boundaries matter too. Once durable work has succeeded, a hub failure should not turn the whole operation into a failure. Otherwise a temporary transport problem can encourage retries of already-completed business work. Log the broadcast failure, observe it, and let reconciliation repair the presentation.

Test the contract, not the transport

The most useful tests were not attempts to prove that a network never fails. They pinned the business boundary:

New durable state produces one realtime hint.
Previously completed or deduplicated work produces no new hint.
A failing realtime transport does not invalidate successful durable work.

Client-side tests can add the complementary guarantees: an initial authoritative load occurs, the reconciliation loop refreshes state, transient errors do not stop later ticks, and disposal cancels the loop.

These tests document the intended hierarchy. The database-backed read is authoritative. Realtime reduces latency. Reconciliation restores convergence.

A practical review checklist

When reviewing a live-update feature, I now ask five questions:

What is the source of truth?
Where is the single shared point that knows a real state transition occurred?
Can the live event be safely missed or duplicated?
How and how quickly does the client converge again?
What happens if the transport fails after the business operation succeeds?

If those answers are vague, the feature may look realtime in a demo while remaining fragile in production.

The broader lesson is modest: reliability often comes from combining mechanisms with explicit roles. Durable storage provides truth. Realtime provides speed. Periodic reconciliation provides healing. None needs to pretend it can do the others’ job.

That separation made a small badge easier to trust, and it is a pattern I would reuse for dashboards, counters, presence indicators, job progress, and other derived UI state.

Twinify 1.1.0: Map Without Profiles, Hide Secrets With Attributes, and Ship Native AOT

Tue, 15 Sep 2026 05:17:00 +0000

If you missed the earlier posts on Twinify: Twinify is a MIT-licensed object mapper for .NET 8, 9, and 10. You call mapper.Map<UserDto>(user) and it copies matching members. Profiles still exist when names are not enough.

1.0.2 was about speed. 1.1.0 is about less boilerplate, safer DTOs, and Native AOT.

dotnet add package Twinify
dotnet add package Twinify.DependencyInjection

NuGet: Twinify

The idea

You still inject IMapper and you still call Map. Existing profile-only apps keep the same behaviour. Everything below is additive.

1. Mapping without a profile

Matching names used to still need CreateMap. Not anymore.

builder.Services.AddTwinify();

public class UserService(IMapper mapper)
{
    public UserDto ToDto(User user) => mapper.Map<UserDto>(user);
}

No CreateMap. Twinify copies same-name members, flattens Address.City → AddressCity, and walks nested objects and collections.

No DI? Same thing:

var mapper = new Mapper();
var dto = mapper.Map<UserDto>(user);

2. Keep your profiles. Auto-map the rest.

Registering a profile is still classic Twinify: only declared top-level pairs map.

Want both? One flag:

builder.Services.AddTwinify(cfg => cfg.AddProfile<UserProfile>())
    .AllowMappingWithoutProfiles();

CreateMap always wins for that pair. Nested types inside an explicit map still auto-map — you do not need CreateMap<Address, AddressDto>() just because User has an Address.

3. Attributes instead of another `ForMember`

Hide secrets

public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; } = "";

    [IgnoreMap]
    public string? Password { get; set; }
}

Rename or flatten without a profile

public class UserDto
{
    [MapFrom("Address.City")]
    public string Town { get; set; } = "";
}

Pick a constructor when the destination has more than one: [MapConstructor].

Need to turn attributes off? UseMappingAttributes(false).

4. Native AOT: a source generator in the same package

JIT apps still compile maps at runtime. Native AOT cannot do that.

The Twinify package now ships Twinify.SourceGenerator. Mark the pair; Twinify emits a static, reflection-free map at compile time.

[Twinify(typeof(User))]
public class UserDto
{
    public int Id { get; set; }
    public string Name { get; set; } = "";
}

Or at assembly scope:

[assembly: TwinifyMap(typeof(User), typeof(UserDto))]

Uncustomized CreateMap in a profile constructor can be generated too. Nested convention-compatible members of a generated pair are included.

Honest limitation: fluent ForMember / ConvertUsing are not generated. Prefer [MapFrom] / [IgnoreMap] on AOT, or keep those pairs on JIT. A pair with no generated map throws MappingNotFoundException on Native AOT.

That is the 1.0.2 “what’s next” item, shipped.

5. Records, in-place map, fail at boot

Records bind constructor parameters by name. Extra settable properties still copy after construction.

public record Person(int Id, string Name);
public record PersonDto(int Id, string Name);

var dto = mapper.Map<PersonDto>(new Person(1, "Ada"));

Update an existing instance:

mapper.Map(user, existingDto);

Catch bad maps at startup instead of on the first request:

builder.Services.AddTwinify(cfg => cfg.AddProfile<UserProfile>())
    .ValidateMappings();

Still stuck? mapper.Explain<User, UserDto>() shows where each destination member gets its value.

Upgrade path

You have	You do
Profile-only 1.0.x app	Update the package. Behaviour stays the same.
Tired of `CreateMap` for identical DTOs	`AllowMappingWithoutProfiles()` or drop profiles for those pairs.
Native AOT / trimming	Add `[Twinify]` or `[TwinifyMap]` and prefer attributes over fluent customizations.

IMapper and Map<TDestination>(source) did not change.

Try it

dotnet add package Twinify --version 1.1.0
dotnet add package Twinify.DependencyInjection --version 1.1.0

NuGet: https://www.nuget.org/packages/Twinify
Release notes: Twinify 1.1.0

If you map DTOs in ASP.NET Core, workers, or AOT apps, I would love a try, a star, or a comment about the pair that still feels too noisy.

Twinify — object mapping without the ceremony.

C# API CRUD Done Wrong, Then Done Right: A Complete Bad-Practices-vs-Best-Practices Walkthrough

Fri, 04 Sep 2026 14:12:06 +0000

Most bad-code examples in tutorials are contrived - obviously wrong in a way real code never actually looks. This post takes a different approach: a complete, realistic Product CRUD API, built with thirteen anti-patterns that genuinely show up in codebases. Each endpoint is walked through one at a time - the bad version, exactly what's wrong with it and why, then the good version, right next to each other, so nothing needs to be hunted down elsewhere on the page.

The scope: a Product entity, five CRUD endpoints - GetAll, GetById, Create, Update, Delete.

Shared Setup: Program.cs

Bad version:

var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddControllers();
builder.Services.AddSingleton<ProductsController>();
 
var app = builder.Build();
app.MapControllers();
app.Run();
 
// Inside ProductsController itself:
private readonly string _connectionString =
    "Server=prod-sql-01;Database=Products;User Id=sa;Password=Passw0rd123!;";

Issues:

Hardcoded connection string. A literal password is committed directly into source code. Anyone with repository access, including, eventually, anyone the repository is ever accidentally exposed to, has the production database password in plain text.
The fix: load the connection string from configuration, appsettings.json locally, environment variables or Key Vault in production, never as a literal string in a class.
Incorrect service lifetime, AddSingleton for a controller. Manually registering the controller itself with AddSingleton means exactly one instance of ProductsController is created and shared across every single request for the entire lifetime of the application, rather than the framework creating a fresh instance per request the normal way. This becomes genuinely dangerous the moment that controller, or anything it depends on, holds any per-request state, and it gets worse once a Scoped dependency like a DbContext enters the picture, since DbContext is explicitly not thread-safe and is designed to live for exactly one request. A Singleton capturing a Scoped dependency is a well-known anti-pattern called a "captive dependency" - the Scoped service effectively gets trapped inside the Singleton's lifetime, silently becoming a de facto singleton itself, shared across requests and threads it was never designed to be shared across.
The fix: never manually register a controller at all, AddControllers() already handles controller instantiation correctly per request, and give each dependency the lifetime that actually matches how it's meant to be used, which for something wrapping a DbContext means Scoped.

Good version:

var builder = WebApplication.CreateBuilder(args);
 
builder.Services.AddDbContext<ProductDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("ProductsDb")));
 
builder.Services.AddScoped<IProductService, ProductService>();
builder.Services.AddControllers();
 
var app = builder.Build();
app.MapControllers();
app.Run();

The connection string now comes from configuration. IProductService is registered as Scoped, not Singleton, one instance per HTTP request, matching the lifetime of the DbContext it wraps, and avoiding the captive dependency problem entirely. The controller itself is never manually registered at all; AddControllers() handles that correctly on its own.

Shared Setup: The Product Entity

public class Product
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public int StockQuantity { get; set; }
    public string InternalSupplierNotes { get; set; }
    public decimal CostPrice { get; set; }
}

Identical in both versions - the entity itself isn't the problem. InternalSupplierNotes and CostPrice are genuinely internal fields, what the business actually pays a supplier, never meant for a customer-facing API to expose. What differs between versions is whether this exact class ever gets returned to a caller directly, covered in the GetById section below.

Endpoint 1: GetAll

Bad version:

[HttpGet]
public IActionResult GetAll()
{
    var products = GetAllProductsAsync().Result;
    return Ok(products);
}
 
private async Task<List<Product>> GetAllProductsAsync()
{
    var products = new List<Product>();
    using var connection = new SqlConnection(_connectionString);
    await connection.OpenAsync();
 
    var command = new SqlCommand("SELECT * FROM Products", connection);
    var reader = await command.ExecuteReaderAsync();
 
    while (await reader.ReadAsync())
    {
        products.Add(new Product
        {
            Id = reader.GetInt32(0),
            Name = reader.GetString(1),
            Price = reader.GetDecimal(2)
        });
    }
    return products;
}

Issues:

Missing await, .Result blocks the thread. GetAllProductsAsync().Result synchronously blocks the calling thread while waiting for the async method to complete, defeating the entire purpose of async and await, since the thread sits idle instead of being released back to the pool. In certain synchronization contexts, classic ASP.NET, WPF, WinForms, this specific pattern can cause a genuine deadlock.
The fix: use await all the way up the call chain, never call .Result or .Wait() on an async method.
Undisposed SqlCommand and SqlDataReader. Both command and reader implement IDisposable, but only connection gets a using statement here. SqlDataReader in particular keeps the underlying connection in a busy state until it's explicitly closed, so under real load, with many concurrent requests each doing this, connections return to the pool later than they need to, risking pool exhaustion faster than necessary. The outer using on connection happens to clean these up indirectly when it disposes, which is what keeps this specific method from actively breaking right now, but relying on that indirect cleanup rather than disposing each IDisposable explicitly is fragile, and won't hold up if the method returns early or the pattern changes later.
The fix: wrap every IDisposable in its own using statement, not just the outermost one.

Good version:

[HttpGet]
public async Task<ActionResult<List<ProductDto>>> GetAll()
{
    var products = await _productService.GetAllAsync();
    return Ok(products);
}
 
// Inside ProductService:
public async Task<List<ProductDto>> GetAllAsync()
{
    return await _context.Products
        .Select(p => new ProductDto
        {
            Id = p.Id,
            Name = p.Name,
            Price = p.Price,
            StockQuantity = p.StockQuantity
        })
        .ToListAsync();
}

Genuinely awaited from the controller all the way through the service call. EF Core's LINQ query is also parameterized automatically and projects directly to ProductDto - a preview of the DTO pattern the next endpoint introduces properly. There's also no manual connection, command, or reader to dispose at all here - EF Core's DbContext and its query execution manage the underlying ADO.NET resources internally, which is one more reason the disposal issue from the bad version simply can't occur in this version.

Endpoint 2: GetById

Bad version:

[HttpGet("{id}")]
public IActionResult GetById(int id)
{
    using var connection = new SqlConnection(_connectionString);
    connection.Open();
 
    var query = "SELECT * FROM Products WHERE Id = " + id;
    var command = new SqlCommand(query, connection);
    var reader = command.ExecuteReader();
 
    if (!reader.Read())
    {
        return Ok(null);
    }
 
    var product = new Product
    {
        Id = reader.GetInt32(0),
        Name = reader.GetString(1),
        Price = reader.GetDecimal(2)
    };
 
    return Ok(product);
}

Issues:

SQL injection. The id parameter is concatenated directly into the query string. A request to /api/products/1;DROP TABLE Products-- executes exactly that.
The fix: never build SQL by concatenating user input, use a parameterized query, or an ORM like EF Core that parameterizes automatically.
Ok(null) instead of NotFound(). When the product doesn't exist, this returns a 200 OK with an empty body. The caller can't distinguish "found nothing" from "succeeded, and the answer happens to be nothing," both look identical on the wire.
The fix: return NotFound(), a genuine 404, so the status code itself carries the information.
No DTO, full entity exposed. The returned product is the raw entity, including InternalSupplierNotes and CostPrice, fields that should never reach an API caller.
The fix: map to a ProductDto containing only the fields meant to be public.

Good version:

public class ProductDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    public int StockQuantity { get; set; }
}
 
[HttpGet("{id}")]
public async Task<ActionResult<ProductDto>> GetById(int id)
{
    var product = await _productService.GetByIdAsync(id);
 
    if (product == null)
        return NotFound();
 
    return Ok(product);
}
 
// Inside ProductService:
public async Task<ProductDto?> GetByIdAsync(int id)
{
    var product = await _context.Products.FindAsync(id);
    // FindAsync uses the primary key safely - parameterized
    // automatically, no string concatenation anywhere
 
    if (product == null)
        return null;
    // Returning null here is fine - it's the CONTROLLER's
    // job to translate this into the correct HTTP response,
    // not the service's
 
    return new ProductDto
    {
        Id = product.Id,
        Name = product.Name,
        Price = product.Price,
        StockQuantity = product.StockQuantity
    };
}

All three issues fixed together: FindAsync makes SQL injection structurally impossible, NotFound() makes the response honest, and ProductDto makes leaking internal fields impossible rather than something to remember not to do.

Endpoint 3: Create

Bad version:

[HttpPost]
public IActionResult Create(Product product)
{
    using var connection = new SqlConnection(_connectionString);
    connection.Open();
 
    var query = $"INSERT INTO Products (Name, Price) " +
                 $"VALUES ('{product.Name}', {product.Price})";
    var command = new SqlCommand(query, connection);
    command.ExecuteNonQuery();
 
    _logger.LogInformation(
        "Product created by user {Email} with auth token {Token}: {Name}",
        currentUser.Email, currentUser.AuthToken, product.Name);
 
    return Ok(product);
}

Issues:

No validation. A request with an empty Name, a negative Price, or missing fields is accepted exactly as-is.
The fix: add validation attributes to a dedicated input DTO, paired with ApiController's automatic model validation.
SQL injection, again. Same pattern as GetById, product.Name concatenated directly, and this version breaks entirely if the name contains a single quote.
The fix: same as before, EF Core, parameterized automatically.
Wrong status code. Returns 200 OK for a successful creation.
The fix: 201 Created, with a Location header pointing to the new resource, since 200 doesn't communicate "a new thing was created."
Sensitive data logged in plain text. The user's email is reasonable to log, but the auth token is a genuine secret, and it's now sitting in plain text inside Application Insights or Log Analytics, visible to anyone with read access to logs, often retained for weeks or months. A leaked or overly-permissioned log query becomes a credential leak.
The fix: never log secrets, tokens, passwords, or other sensitive fields, log an identifier (a user ID) instead of the credential itself, and if a field must be referenced for debugging, mask or redact it before it reaches the logger.

Good version:

public class CreateProductDto
{
    [Required, MaxLength(200)]
    public string Name { get; set; }
 
    [Range(0.01, 1000000)]
    public decimal Price { get; set; }
 
    [Range(0, int.MaxValue)]
    public int StockQuantity { get; set; }
}
 
[HttpPost]
public async Task<ActionResult<ProductDto>> Create(CreateProductDto dto)
{
    // No manual validation check needed - [ApiController]
    // automatically returns 400 Bad Request if the DTO's
    // validation attributes aren't satisfied, before this
    // method body even runs
 
    var created = await _productService.CreateAsync(dto);
 
    _logger.LogInformation(
        "Product {ProductId} created by user {UserId}",
        created.Id, currentUser.Id);
    // Logs an IDENTIFIER, never a credential or token -
    // enough to trace who did what, without exposing
    // anything an attacker or an over-permissioned log
    // reader could actually use
 
    return CreatedAtAction(
        nameof(GetById),
        new { id = created.Id },
        created);
}
 
// Inside ProductService:
public async Task<ProductDto> CreateAsync(CreateProductDto dto)
{
    var product = new Product
    {
        Name = dto.Name,
        Price = dto.Price,
        StockQuantity = dto.StockQuantity
    };
 
    _context.Products.Add(product);
    await _context.SaveChangesAsync();
 
    return new ProductDto
    {
        Id = product.Id,
        Name = product.Name,
        Price = product.Price,
        StockQuantity = product.StockQuantity
    };
}

CreateProductDto's Required, MaxLength, and Range attributes are checked automatically by ApiController. CreatedAtAction returns the correct 201 with a Location header built from the GetById action. The log statement now records a user ID, not a credential, and EF Core removes the SQL injection path entirely.

Endpoint 4: Update

Bad version:

[HttpPut("{id}")]
public IActionResult Update(int id, Product product)
{
    try
    {
        using var connection = new SqlConnection(_connectionString);
        connection.Open();
 
        var query = $"UPDATE Products SET Name = '{product.Name}', " +
                    $"Price = {product.Price} WHERE Id = {id}";
        var command = new SqlCommand(query, connection);
        command.ExecuteNonQuery();
    }
    catch (Exception ex)
    {
        return Ok(new { error = ex.ToString() });
    }
 
    return Ok();
}

Issues:

Swallowed exception behavior masked as a response. The catch block doesn't silently discard the exception here, but it does something almost as problematic in a different way, it converts a failure into a 200 OK response body, meaning the HTTP status code itself claims success while the actual content says otherwise. Callers checking only the status code, which is the normal way to check for success, will treat this as a successful update.
The fix: return an actual error status code, and don't rely on the response body alone to communicate failure.
SQL injection, again. Same string-concatenation pattern as the previous two endpoints.
Full exception details leaked to the caller. ex.ToString() returns the complete exception message and full stack trace, including internal file paths, method names, and sometimes literal fragments of the failed SQL query itself, all sent directly to whoever called this endpoint. This is genuinely useful reconnaissance for an attacker probing the API, and it's an accidental disclosure of internal implementation detail even to a well-meaning caller.
The fix: log the full exception detail internally, server-side, and return only a generic, safe error message to the caller.

Good version:

[HttpPut("{id}")]
public async Task<IActionResult> Update(int id, CreateProductDto dto)
{
    var success = await _productService.UpdateAsync(id, dto);
 
    if (!success)
        return NotFound();
 
    return NoContent();
}
 
// Inside ProductService:
public async Task<bool> UpdateAsync(int id, CreateProductDto dto)
{
    var product = await _context.Products.FindAsync(id);
    if (product == null)
        return false;
 
    product.Name = dto.Name;
    product.Price = dto.Price;
    product.StockQuantity = dto.StockQuantity;
 
    try
    {
        await _context.SaveChangesAsync();
        return true;
    }
    catch (DbUpdateException ex)
    {
        // The FULL exception, including stack trace, is
        // logged INTERNALLY here - visible to the team via
        // Application Insights, never sent to the caller
        _logger.LogError(ex, "Failed to update product {Id}", id);
        return false;
    }
}

The exception is now caught narrowly, DbUpdateException, not the broad Exception base class, logged internally in full detail with _logger.LogError, and the method returns false so the controller responds with a correct NotFound or, in a fuller version, a generic 500 with a safe message, never the raw exception content itself.

Endpoint 5: Delete

Bad version:

[HttpDelete("{id}")]
public IActionResult Delete(int id)
{
    using var connection = new SqlConnection(_connectionString);
    connection.Open();
 
    var query = "DELETE FROM Products WHERE Id = " + id;
    var command = new SqlCommand(query, connection);
    command.ExecuteNonQuery();
 
    return Ok();
}

Issues:

SQL injection, again. The same concatenation pattern as every other endpoint above.
Wrong status code. Returns 200 OK with no body for a successful delete. The fix: 204 No Content, the correct response when an operation succeeds and there's genuinely nothing further to return.

Good version:

[HttpDelete("{id}")]
public async Task<IActionResult> Delete(int id)
{
    var success = await _productService.DeleteAsync(id);
 
    if (!success)
        return NotFound();
 
    return NoContent();
}
 
// Inside ProductService:
public async Task<bool> DeleteAsync(int id)
{
    var product = await _context.Products.FindAsync(id);
    if (product == null)
        return false;
 
    _context.Products.Remove(product);
    await _context.SaveChangesAsync();
    return true;
}

The Complete Good-Version Service Interface

Pulling every service method from above together into the one interface the controller actually depends on:

public interface IProductService
{
    Task<List<ProductDto>> GetAllAsync();
    Task<ProductDto?> GetByIdAsync(int id);
    Task<ProductDto> CreateAsync(CreateProductDto dto);
    Task<bool> UpdateAsync(int id, CreateProductDto dto);
    Task<bool> DeleteAsync(int id);
}

This is the layer that never existed in the bad version at all, the bad controller talked directly to SqlConnection. Having this interface is also what makes the controller genuinely unit-testable with a mock, something effectively impossible against the bad version's design.

Attribute Reference: What's Doing the Actual Work

ApiController enables automatic model validation, checking a DTO's validation attributes and returning 400 automatically if they fail, before the action method body runs. Present in both versions, but only doing real work in the good one, since the bad version's Product parameter has no validation attributes for it to check.

Route with the controller token sets the base route, "api/products," identical in both versions.

HttpGet, the id-scoped HttpGet, HttpPost, the id-scoped HttpPut, and the id-scoped HttpDelete map each method to its HTTP verb and route, the routing itself was never the problem in the bad version.

Required, MaxLength, and Range on CreateProductDto are declarative validation rules, good version only, paired with ApiController to reject invalid requests automatically, with zero manual if-checks.

Every Issue, At a Glance

Hardcoded connection string, in Program.cs and setup.
Bad: literal password committed in source code.
Good: loaded from configuration or Key Vault.
Incorrect service lifetime, AddSingleton for a controller, in Program.cs and setup.
Bad: the controller manually registered as Singleton, one shared instance forever, risking a captive dependency once a Scoped DbContext enters the picture.
Good: the controller is never manually registered at all, and IProductService is registered as Scoped, matching the DbContext's own lifetime.
Missing await / .Result, in GetAll.
Bad: .Result blocks the thread synchronously.
Good: await released the thread properly, all the way through.
Undisposed SqlCommand and SqlDataReader, in GetAll.
Bad: only connection wrapped in a using, command and reader never explicitly disposed, relying on indirect cleanup that isn't reliable.
Good: EF Core manages the underlying ADO.NET resources internally, so there's no manual disposal to get wrong.
SQL injection, appearing in GetById, Create, Update, and Delete.
Bad: string-concatenated raw SQL.
Good: EF Core LINQ or FindAsync, parameterized automatically.
Ok(null) instead of NotFound(), in GetById.
Bad: 200 OK with a null body when not found.
Good: NotFound(), a genuine 404.
No DTOs, full entity exposed, in GetById.
Bad: internal fields like CostPrice and supplier notes exposed.
Good: ProductDto excludes them entirely, structurally impossible to leak.
No validation, in Create.
Bad: any data accepted as-is.
Good: Required, MaxLength, and Range attributes plus ApiController auto-reject invalid requests.
Wrong status codes, in Create and Delete.
Bad: 200 OK for create and delete.
Good: 201 Created with a Location header for create, 204 No Content for delete.
Sensitive data logged in plain text, in Create.
Bad: an auth token logged directly, sitting in plain text in Application Insights.
Good: only a user ID logged, never a credential or token.
Swallowed exception behavior masked as a response, in Update.
Bad: a failure converted into a 200 OK response body, status code claims success while content says otherwise.
Good: an honest result returned, false propagated up so the controller can respond correctly.
Full exception details leaked to the caller, in Update.
Bad: ex.ToString(), including the full stack trace, returned directly in the API response.
Good: the full exception logged internally only, a generic safe message, if any, returned to the caller.
No service layer, structural, underneath all endpoints.
Bad: controller does raw data access directly.
Good: IProductService and ProductService, separated, testable, the natural home for every other fix.

Key Lessons

Every anti-pattern here is realistic, these are mistakes that genuinely appear in real production code, not exaggerated examples built just to be wrong.

The missing service layer is structurally connected to most of the other issues, a controller doing raw data access directly removes the natural place validation, parameterization, and error handling would otherwise live.

A DTO isn't just extra code, it's what makes leaking internal fields structurally impossible, rather than something a developer has to remember not to do.

Status codes are information, not decoration, Ok(null), 200 for a create, and 200 for a delete each communicate something genuinely false or ambiguous to the caller.

Logging and error responses are both genuine attack surfaces, not just debugging conveniences, a logged token or a leaked stack trace can hand an attacker exactly what they need, even when the code otherwise "works."

A swallowed exception, or one disguised as a success response, is worse than a crash, a crash is visible immediately, a silently hidden failure looks like success and can go unnoticed for a long time.

Summary

Every issue in the bad version compiles, runs, and looks like reasonable code at a glance, which is exactly why these patterns survive in real codebases far longer than obviously broken code ever would. Rebuilding the same five endpoints with a real service layer, correct dependency lifetimes, disciplined resource disposal, DTOs, parameterized queries, genuine async, proper validation, correct status codes, and careful logging doesn't just fix thirteen individual bugs, it changes the shape of the code so that several of those bugs become structurally difficult to reintroduce by accident.

Originally published at TechStack Blog: https://www.techstackblog.com/post.html?slug=csharp-api-crud-bad-vs-good-practices
More from TechStack Blog: C# / .NET: https://www.techstackblog.com/category.html?cat=csharp
CS Fundamentals: https://www.techstackblog.com/category.html?cat=cs-fundamentals

C# Coding Interview Prep Part 1: Variables, Strings, Arrays, Lists, Dictionaries, and Every Basic Building Block

Fri, 04 Sep 2026 14:08:32 +0000

This is a refresher built while preparing for C# coding interviews, and shared as a resource, because a genuinely comprehensive, practice-oriented guide is hard to find in one place. This series doesn't skip the basics to get to the "interesting" parts - the basics are exactly what trips people up under interview pressure, when a simple question about arrays suddenly requires recalling details nobody thinks about in day-to-day coding. Every topic in this series follows the same format: a plain-English explanation, an analogy, a code example, and a practice question at the end, so this can genuinely be used to test yourself, not just read passively.

This is Part 1 of three. Part 1 covers the basics - variables, data types, strings, arrays, List, Dictionary<TKey,TValue>, HashSet, tuples, value vs reference types, operators, control flow, loops, methods, enums, structs vs classes, nullable types, type conversion, and basic exception handling. Part 2 covers mid-level concepts - LINQ, generics, delegates and events, interfaces vs abstract classes, and exception handling in depth. Part 3 covers advanced concepts - async and Task, reflection, memory management and garbage collection, design patterns in practice, and performance considerations.

Topic 1: Variables and Data Types

A variable is a named storage location holding a value of a specific type. C# is statically typed - once a variable is declared with a type, it can only ever hold values of that type, or something compatible with it.

Think of a labeled storage box. A box labeled "int" can only hold integers - trying to put a sentence in it doesn't work, the same way a shoebox labeled for shoes doesn't neatly fit a stack of books.

// Value types - the actual data lives directly
// in the variable
int age = 30;
double price = 19.99;
bool isPublished = true;
char grade = 'A';
decimal exactMoney = 19.99m;  // decimal for money -
                               // no floating point
                               // rounding errors
 
// var - the compiler infers the type at compile
// time, this is still statically typed, NOT dynamic
var name = "Alex";  // compiler infers string
 
// Reference types - the variable holds a reference
// (address) to where the actual data lives
string title = "C# Basics";
int[] numbers = { 1, 2, 3 };
Post post = new Post();
 
// Constants - value is fixed at compile time,
// cannot ever change
const double Pi = 3.14159;
 
// Nullable value types - value types normally
// cannot be null, this opts in
int? nullableAge = null;

Practice question: What is the difference between const and readonly in C#? Write one example of each.

Topic 2: Strings and String Methods

A string is a sequence of characters, and in C# it's a reference type - but with a critical twist: strings are immutable. Once created, a string's actual content in memory never changes. Every operation that appears to modify a string actually creates a brand new string.

Think of a printed book page. You cannot erase and rewrite a word on a printed page - if you want different text, you print an entirely new page. Modifying a string works the same way: the old string still exists in memory until garbage collected, and a new one is created for the result.

string greeting = "Hello";
string name = "Manohari";
 
// Concatenation - creates a NEW string, does not
// modify 'greeting'
string message = greeting + ", " + name;
 
// String interpolation - cleaner syntax, same result
string message2 = $"{greeting}, {name}";
 
// Common string methods
string text = "  C# Interview Prep  ";
Console.WriteLine(text.Trim());           // "C# Interview Prep"
Console.WriteLine(text.ToUpper());        // "  C# INTERVIEW PREP  "
Console.WriteLine(text.Contains("Prep")); // true
Console.WriteLine(text.Replace("C#", "CSharp"));
Console.WriteLine(text.Split(' ').Length);
Console.WriteLine(text.Substring(2, 4));  // extracts a portion
Console.WriteLine(text.IndexOf("Prep"));  // position found at
 
// String comparison - == checks VALUE equality
// for strings specifically (special-cased), not
// reference equality
string a = "hello";
string b = "hello";
Console.WriteLine(a == b);         // true - value equality
Console.WriteLine(a.Equals(b));    // true - same result
 
// StringBuilder - for heavy concatenation, avoid
// creating thousands of throwaway strings in a loop
var sb = new StringBuilder();
for (int i = 0; i < 1000; i++)
{
    sb.Append(i).Append(", ");
}
string result = sb.ToString();

Practice question: Write a method that reverses a string without using any built-in reverse method.

Topic 3: Arrays

An array is a fixed-size, ordered collection of elements of the same type. The size is set at creation and cannot change afterward - to "resize," a new array must be created and the old data copied over.

Think of a row of numbered parking spaces painted onto pavement. The number of spaces is fixed the moment the lot is built - adding more spaces means literally repaving with a new, larger layout, not just adding to the existing one.

// Declaration and initialization
int[] numbers = { 1, 2, 3, 4, 5 };
string[] names = new string[3];  // size 3, all null initially
names[0] = "Alex";
names[1] = "Priya";
names[2] = "Sam";
 
// Accessing and modifying
Console.WriteLine(numbers[0]);   // 1
numbers[0] = 100;                // arrays ARE mutable in
                                  // content, just fixed size
 
// Iterating
foreach (var n in numbers)
{
    Console.WriteLine(n);
}
 
// Multi-dimensional array
int[,] grid = new int[3, 3];
grid[0, 0] = 1;
grid[1, 1] = 5;
 
// Jagged array - array of arrays, each inner
// array can be a different length
int[][] jagged = new int[3][];
jagged[0] = new int[] { 1, 2 };
jagged[1] = new int[] { 1, 2, 3, 4 };
 
// Common Array methods
Array.Sort(numbers);
Array.Reverse(numbers);
int index = Array.IndexOf(numbers, 100);
bool found = Array.Exists(numbers, n => n > 50);

Practice question: Given an integer array, write a method that finds the second largest number without sorting the entire array.

Topic 4: List

List is a resizable, ordered collection - the generic, flexible alternative to a fixed-size array. Internally it's backed by an array that gets replaced with a larger one automatically as items are added beyond current capacity.

Think of an expandable file folder versus a fixed shoebox. As more documents come in, the expandable folder just grows - you never have to buy a new one and manually move everything over, even though internally that's conceptually similar to what List does behind the scenes automatically.

var posts = new List<string>();
 
posts.Add("First Post");
posts.Add("Second Post");
posts.Insert(0, "Inserted at start");
 
posts.Remove("First Post");     // removes by value
posts.RemoveAt(0);               // removes by index
 
bool exists = posts.Contains("Second Post");
int index = posts.IndexOf("Second Post");
 
Console.WriteLine(posts.Count);  // current item count
 
// Iterating
foreach (var post in posts)
{
    Console.WriteLine(post);
}
 
// Converting between List and Array
int[] array = { 1, 2, 3 };
List<int> fromArray = array.ToList();
int[] backToArray = fromArray.ToArray();
 
// Sorting and searching
var numbers = new List<int> { 5, 2, 8, 1 };
numbers.Sort();
numbers.Sort((a, b) => b.CompareTo(a));  // descending,
                                            // custom comparer

Practice question: Write a method that removes all duplicate values from a List while preserving the original order.

Topic 5: Dictionary<TKey, TValue>

A Dictionary stores key-value pairs and provides fast, close-to-O(1) lookup by key, using a hash table internally. Every key must be unique.

Think of a labeled filing cabinet drawer system, where every drawer has exactly one unique name on it. Finding "the invoices drawer" doesn't require checking every drawer one by one - you go directly to the one labeled correctly.

var postsBySlug = new Dictionary<string, string>();
 
postsBySlug["csharp-basics"] = "C# Basics Post";
postsBySlug["csharp-linq"] = "LINQ Deep Dive";
 
// Safe lookup - does not throw if key is missing
if (postsBySlug.TryGetValue("csharp-basics", out var title))
{
    Console.WriteLine(title);
}
 
// Direct access - throws KeyNotFoundException if missing
string result = postsBySlug["csharp-basics"];
 
bool hasKey = postsBySlug.ContainsKey("csharp-linq");
postsBySlug.Remove("csharp-linq");
 
// Iterating - gives KeyValuePair<TKey,TValue>
foreach (var kvp in postsBySlug)
{
    Console.WriteLine($"{kvp.Key}: {kvp.Value}");
}
 
// Just keys or just values
foreach (var key in postsBySlug.Keys) { }
foreach (var value in postsBySlug.Values) { }
 
// Update or add in one call
postsBySlug["csharp-basics"] = "Updated Title";  // overwrites

Practice question: Given an array of words, write a method using a Dictionary that counts how many times each word appears.

Topic 6: HashSet

A HashSet stores unique values only, with no guaranteed order, and provides fast O(1) average lookup for "does this exist" checks - much faster than checking a List with Contains for large collections.

Think of a guest list at the door of an event, where a bouncer just needs to answer "is this name already checked in" as fast as possible - not caring about the order names were added, just whether a given name is present at all.

var uniqueTags = new HashSet<string>();
 
uniqueTags.Add("Azure");
uniqueTags.Add("C#");
uniqueTags.Add("Azure");  // silently ignored - duplicate
 
Console.WriteLine(uniqueTags.Count);  // 2
 
bool hasAzure = uniqueTags.Contains("Azure");  // O(1) check
 
// Set operations
var setA = new HashSet<int> { 1, 2, 3, 4 };
var setB = new HashSet<int> { 3, 4, 5, 6 };
 
setA.IntersectWith(setB);  // setA becomes {3, 4}
// UnionWith, ExceptWith also available

Practice question: Given two integer arrays, write a method that returns only the numbers that appear in both arrays, using a HashSet.

Topic 7: Tuples

A tuple bundles multiple values together into one object without needing to define a custom class. Modern C# tuples support named elements, making them readable at the point of use.

Think of a small labeled tray carrying a few different items together - a tray with "coffee" and "muffin" compartments lets you carry both at once without needing a whole custom carrying case built just for that specific combination.

// Named tuple
(string Name, int Age) person = ("Alex", 30);
Console.WriteLine(person.Name);  // "Alex"
Console.WriteLine(person.Age);   // 30
 
// Returning multiple values from a method
(int Min, int Max) FindMinMax(int[] numbers)
{
    return (numbers.Min(), numbers.Max());
}
 
var result = FindMinMax(new[] { 5, 2, 8, 1 });
Console.WriteLine($"Min: {result.Min}, Max: {result.Max}");
 
// Deconstruction
var (min, max) = FindMinMax(new[] { 5, 2, 8, 1 });
Console.WriteLine(min);
Console.WriteLine(max);
 
// Tuple vs custom class - when to use which
// Tuple: quick, internal, 2-3 short-lived values
// Class: the shape has real meaning, gets passed
// around broadly, or needs its own behavior/methods

Practice question: Write a method that takes a list of numbers and returns a tuple containing the sum, average, and count in one call.

Topic 8: Value Types vs Reference Types

This is one of the most frequently tested distinctions in C# interviews. Value types - int, bool, double, struct - store their actual data directly in the variable. Reference types - class, array, string, List, Dictionary - store a reference, a memory address, to where the actual data lives on the heap. The variable itself just holds that address.

Think of a value type as writing a number directly on a sticky note - the note is the data. A reference type is like writing a house address on a sticky note - the note points to where the actual house is, and copying the note just copies the address, not the house itself.

// Value type - assignment COPIES the actual value
int a = 5;
int b = a;   // b gets its OWN copy of 5
b = 10;
Console.WriteLine(a);  // still 5 - a was never touched
 
// Reference type - assignment copies the REFERENCE,
// both variables point to the SAME object
var list1 = new List<int> { 1, 2, 3 };
var list2 = list1;   // list2 points to the SAME list
list2.Add(4);
Console.WriteLine(list1.Count);  // 4 - list1 sees the
                                   // change too, because
                                   // it's the same object
 
// Passing to methods - same rule applies
void ModifyValue(int x) { x = 100; }
void ModifyReference(List<int> list) { list.Add(999); }
 
int number = 5;
ModifyValue(number);
Console.WriteLine(number);  // still 5
 
var myList = new List<int> { 1, 2 };
ModifyReference(myList);
Console.WriteLine(myList.Count);  // 3 - the SAME list
                                    // object was modified
 
// string is a special case - reference type, but
// immutable, so it BEHAVES like a value type in
// most practical situations
string s1 = "hello";
string s2 = s1;
s2 = s2 + " world";  // creates a NEW string for s2
Console.WriteLine(s1);  // still "hello" - unaffected

Practice question: Without running the code, predict the output: create a struct Point with a public int X, create var p1 = new Point with X set to 1, assign var p2 = p1, then set p2.X to 99. What is p1.X afterward, and why?

Topic 9: Operators

Operators perform operations on values - arithmetic, comparison, logical, and a few special ones worth knowing well for interviews specifically.

// Arithmetic
int sum = 5 + 3;
int remainder = 10 % 3;   // modulo - remainder after division
 
// Comparison
bool isEqual = (5 == 5);
bool isGreater = (5 > 3);
 
// Logical
bool result = true && false;   // AND
bool result2 = true || false;  // OR
bool result3 = !true;           // NOT
 
// Null-coalescing - returns left if not null,
// otherwise returns right
string name = null;
string display = name ?? "Unknown";  // "Unknown"
 
// Null-conditional - safely accesses a member,
// returns null instead of throwing if the object
// itself is null
Post post = null;
string title = post?.Title;  // null, no exception thrown
 
// Null-coalescing assignment
string cachedValue = null;
cachedValue ??= "default";  // assigns only if currently null
 
// Ternary conditional
int age = 20;
string category = age >= 18 ? "Adult" : "Minor";
 
// Increment/decrement
int count = 0;
count++;      // post-increment
++count;      // pre-increment - subtle difference in
              // expressions, same end result standalone

Practice question: What is the difference between x++ and ++x when used inside a larger expression, like int y = x++ + 1 versus int y = ++x + 1? Write out what each assigns to x and y given x starts at 5.

Topic 10: Control Flow - if, else, switch

Control flow statements decide which code actually runs based on conditions.

int score = 85;
 
// if / else if / else
if (score >= 90)
{
    Console.WriteLine("A");
}
else if (score >= 80)
{
    Console.WriteLine("B");
}
else
{
    Console.WriteLine("C or below");
}
 
// switch statement
string grade;
switch (true)
{
    case bool _ when score >= 90:
        grade = "A";
        break;
    case bool _ when score >= 80:
        grade = "B";
        break;
    default:
        grade = "C or below";
        break;
}
 
// switch expression (modern C#, more concise)
string grade2 = score switch
{
    >= 90 => "A",
    >= 80 => "B",
    _ => "C or below"
};
 
// Pattern matching in switch
object value = 42;
string description = value switch
{
    int i when i > 0 => "positive integer",
    int i when i < 0 => "negative integer",
    string s => $"a string: {s}",
    null => "null value",
    _ => "something else"
};

Practice question: Write a method using a switch expression that takes an integer representing a day of the week (1-7) and returns whether it's a "Weekday" or "Weekend".

Topic 11: Loops

Loops repeat a block of code, either a fixed number of times, while a condition holds, or once per element in a collection.

// for loop - when you know the iteration count
// or need the index
for (int i = 0; i < 5; i++)
{
    Console.WriteLine(i);
}
 
// while loop - condition checked BEFORE each iteration
int count = 0;
while (count < 5)
{
    Console.WriteLine(count);
    count++;
}
 
// do-while - condition checked AFTER each iteration,
// so the body ALWAYS runs at least once
int x = 10;
do
{
    Console.WriteLine(x);
    x++;
} while (x < 5);  // runs once even though condition
                    // is false from the start
 
// foreach - iterates every element in a collection,
// no manual index management
var posts = new List<string> { "A", "B", "C" };
foreach (var post in posts)
{
    Console.WriteLine(post);
}
 
// break and continue
for (int i = 0; i < 10; i++)
{
    if (i == 3) continue;  // skip this iteration
    if (i == 7) break;     // exit the loop entirely
    Console.WriteLine(i);
}

Practice question: Write a program using a loop that prints the Fibonacci sequence up to the 10th number.

Topic 12: Methods and Parameters

A method is a named, reusable block of code. Parameters pass data into a method; a return type defines what comes back out.

// Basic method
int Add(int a, int b)
{
    return a + b;
}
 
// Optional parameters - must come after required ones
void Greet(string name, string greeting = "Hello")
{
    Console.WriteLine($"{greeting}, {name}");
}
Greet("Alex");               // uses default "Hello"
Greet("Alex", "Hi");         // overrides default
 
// Named arguments - can be passed in any order
Greet(greeting: "Hey", name: "Alex");
 
// params - accepts a variable number of arguments
int Sum(params int[] numbers)
{
    int total = 0;
    foreach (var n in numbers) total += n;
    return total;
}
Sum(1, 2, 3);        // works
Sum(1, 2, 3, 4, 5);  // also works, any count
 
// ref - passes by REFERENCE, method can modify
// the caller's actual variable
void Double(ref int number)
{
    number = number * 2;
}
int value = 5;
Double(ref value);
Console.WriteLine(value);  // 10 - actually changed
 
// out - similar to ref, but the method MUST assign
// a value before returning, commonly used for
// "try" pattern methods
bool TryParse(string input, out int result)
{
    return int.TryParse(input, out result);
}
 
// Method overloading - same name, different
// parameter signatures
int Multiply(int a, int b) => a * b;
double Multiply(double a, double b) => a * b;

Practice question: What is the actual difference between ref and out parameters? Write a method using each that demonstrates the difference.

Topic 13: Enums

An enum defines a named set of related constant values, making code more readable than using raw numbers or strings for a fixed set of options.

public enum OrderStatus
{
    Pending,     // 0 by default
    Processing,  // 1
    Shipped,     // 2
    Delivered    // 3
}
 
var status = OrderStatus.Processing;
Console.WriteLine(status);          // "Processing"
Console.WriteLine((int)status);      // 1
 
// Assigning explicit values
public enum HttpStatusCode
{
    Ok = 200,
    NotFound = 404,
    ServerError = 500
}
 
// Converting from an int
var code = (HttpStatusCode)404;
Console.WriteLine(code);  // NotFound
 
// Parsing from a string
var parsed = Enum.Parse<OrderStatus>("Shipped");
 
// Switching on an enum
string GetMessage(OrderStatus status) => status switch
{
    OrderStatus.Pending => "Order received",
    OrderStatus.Shipped => "On its way",
    OrderStatus.Delivered => "Completed",
    _ => "Unknown status"
};

Practice question: Create an enum for days of the week, and write a method that returns true if a given day is a weekend.

Topic 14: Structs vs Classes

Both structs and classes group related data and behavior together, but a struct is a value type, copied on assignment, while a class is a reference type, shared on assignment - the same fundamental distinction as value types versus reference types, applied to your own custom types.

// struct - value type, typically small, simple data
public struct Point
{
    public int X;
    public int Y;
}
 
var p1 = new Point { X = 1, Y = 2 };
var p2 = p1;       // COPIES the values
p2.X = 99;
Console.WriteLine(p1.X);  // still 1 - p1 untouched
 
// class - reference type, typically larger objects
// with behavior, identity, and mutable state over time
public class Post
{
    public string Title;
    public int ViewCount;
}
 
var post1 = new Post { Title = "Hello", ViewCount = 0 };
var post2 = post1;  // SHARES the same object
post2.ViewCount = 5;
Console.WriteLine(post1.ViewCount);  // 5 - same object

Use a struct for small, immutable-feeling data with no real identity - a Point, a Color, a Money amount. Use a class for anything with real identity, larger data, or behavior that changes over the object's lifetime - a Post, a Customer, a Service. Most day-to-day domain modeling uses classes; structs are the exception, reached for deliberately.

Practice question: Explain why using a struct for a large object with 15 fields would generally be a bad idea, based on what you know about value type copying.

Topic 15: Nullable Types

Value types - int, bool, DateTime - cannot normally hold null; they always have some default value. Nullable value types, written as int?, opt into allowing null, useful for representing "no value provided" distinctly from an actual zero or false.

int? age = null;
int regularAge = 0;  // 0 is a real value,
                       // different from "no value"
 
if (age.HasValue)
{
    Console.WriteLine(age.Value);
}
 
// GetValueOrDefault - safe access with a fallback
int actualAge = age.GetValueOrDefault(18);
 
// Null-coalescing works here too
int displayAge = age ?? 18;
 
// Nullable reference types (C# 8+) - a compiler
// feature (not a runtime type change) that WARNS
// when a reference type that should never be null
// might actually be null
string? nullableName = null;   // explicitly allowed
string nonNullableName = "Alex"; // compiler warns if
                                   // this is ever assigned
                                   // null somewhere

Practice question: Why might a nullable int? be a better choice than a regular int for a "discount percentage" field on an order, where most orders have no discount at all?

Topic 16: Type Conversion and Casting

Converting a value from one type to another - sometimes safe and implicit, sometimes requiring an explicit cast, and sometimes needing a parsing method entirely.

// Implicit conversion - safe, no data loss possible,
// compiler does it automatically
int number = 100;
double asDouble = number;  // int fits safely into double
 
// Explicit conversion (casting) - REQUIRED when data
// loss is possible, forces you to acknowledge the risk
double price = 19.99;
int roundedDown = (int)price;  // 19 - truncates,
                                 // does not round
 
// Parsing strings to numbers
string input = "42";
int parsed = int.Parse(input);        // throws if invalid
bool success = int.TryParse(input, out int result);
                                        // safe, returns
                                        // false instead of
                                        // throwing
 
// Convert class - handles more conversions, including
// null handling
string text = Convert.ToString(42);
int fromString = Convert.ToInt32("42");
 
// as vs cast for reference types
object obj = "hello";
string s1 = (string)obj;      // throws if obj isn't
                                // actually a string
string s2 = obj as string;    // returns null instead
                                // of throwing if it fails
 
// is keyword with pattern matching
if (obj is string str)
{
    Console.WriteLine(str.Length);
}

Practice question: What is the actual difference between int.Parse() and int.TryParse()? When would you genuinely prefer one over the other?

Topic 17: Basic Exception Handling

Exceptions represent errors that occur during execution. try/catch lets code handle an error gracefully instead of crashing the entire program.

try
{
    int result = 10 / int.Parse("0");
}
catch (DivideByZeroException ex)
{
    Console.WriteLine($"Cannot divide by zero: {ex.Message}");
}
catch (FormatException ex)
{
    Console.WriteLine($"Invalid number format: {ex.Message}");
}
catch (Exception ex)
{
    // Generic catch-all - should be LAST, since more
    // specific catches above it would never be reached
    // if this came first
    Console.WriteLine($"Unexpected error: {ex.Message}");
}
finally
{
    // ALWAYS runs, whether an exception occurred or not -
    // used for cleanup (closing files, connections, etc.)
    Console.WriteLine("Cleanup runs here regardless");
}
 
// Throwing your own exceptions
void ValidateAge(int age)
{
    if (age < 0)
    {
        throw new ArgumentException("Age cannot be negative", nameof(age));
    }
}
 
// Custom exception types
public class InsufficientFundsException : Exception
{
    public InsufficientFundsException(string message) : base(message) { }
}

Practice question: Write a method that safely divides two numbers, catching a divide-by-zero error and returning 0 instead of letting the exception propagate.

Key Lessons

Value types copy on assignment; reference types share the same underlying object - this single distinction explains a huge share of "unexpected" C# behavior.

Arrays are fixed size; List resizes automatically - default to List unless the size is genuinely fixed and known.

Dictionary<TKey,TValue> gives fast key-based lookup; HashSet gives fast existence checks with no duplicates.

Strings are immutable - every apparent modification creates a new string, which is exactly why StringBuilder exists for heavy concatenation.

ref and out both pass by reference, but out requires the method to assign a value before returning, commonly used in the TryParse pattern.

Structs and classes mirror the value versus reference type distinction for your own custom types - most everyday modeling uses classes.

What's Next

Part 2 covers mid-level concepts - LINQ, generics, delegates and events, interfaces versus abstract classes, and exception handling in real depth.

Summary

Every C# codebase, no matter how advanced, is built from these same basic pieces - variables and types, strings, collections, control flow, methods, and basic error handling. Interview questions on these topics aren't testing whether you've memorized syntax - they're testing whether the underlying model, value versus reference, mutable versus immutable, fixed versus resizable, is genuinely internalized, since that's what actually predicts whether unfamiliar code will behave the way you expect it to.

Originally published at TechStack Blog: https://www.techstackblog.com/post.html?slug=csharp-interview-prep-basics-part1

More from TechStack Blog: C# / .NET: https://www.techstackblog.com/category.html?cat=csharp
CS Fundamentals: https://www.techstackblog.com/category.html?cat=cs-fundamentals

Twinify 1.0.2: A Look at the Latest Performance Improvements

Thu, 27 Aug 2026 05:21:17 +0000

Over the past few weeks, the performance and memory efficiency of Twinify has been improved, twinify is an open-source object-to-object mapping library for .NET.

The latest release, Twinify 1.0.2, brings some encouraging improvements compared with the initial 1.0.0 release.

I also wanted to keep the benchmarking honest, so the tests include AutoMapper 16.2.0 as a reference point.

Twinify is designed to make object mapping simple, while supporting common scenarios such as nested objects, collections, flattening, constructor mapping, and custom mappings.

The Benchmark

The benchmark uses:

.NET 10
BenchmarkDotNet 0.15.8
Windows 11
Intel Core i7-1355U
Twinify 1.0.0
Twinify 1.0.2
AutoMapper 16.2.0

The object graph being mapped is not just a simple flat object.

The benchmark maps:

User
 ├── Address
 └── Orders
      ├── Order
      │    └── OrderItems
      └── Order
           └── OrderItems

Two scenarios are tested:

Mapping a single User to UserDto
Mapping 1,000 users to UserDto

Memory allocation and GC activity are also measured using BenchmarkDotNet's MemoryDiagnoser.

Performance Progress

Here are the results.

Scenario	Metric	Twinify 1.0.0	Twinify 1.0.2	AutoMapper 16.2.0
Single User	Mean	3.819 μs	4.087 μs	1.066 μs
Single User	Allocated	3,304 B	1,848 B	848 B
1,000 Users	Mean	4,420.174 μs	2,420.444 μs	1,108.267 μs
1,000 Users	Allocated	3,320,120 B	1,864,120 B	864,120 B
1,000 Users	Gen0	523.4375	296.8750	136.7188
1,000 Users	Gen1	242.1875	171.8750	78.1250

45% Faster Bulk Mapping

The biggest improvement can be seen when mapping 1,000 users.

Twinify 1.0.0:

4,420.174 μs

Twinify 1.0.2:

2,420.444 μs

That's approximately a 45% reduction in execution time.

The performance gap with AutoMapper has also become much smaller.

AutoMapper 16.2.0 completes the same benchmark in:

1,108.267 μs

There is still a gap, but the improvement from the initial Twinify release is significant.

44% Less Memory Allocation

Performance isn't only about execution time.

For the 1,000-user benchmark:

Twinify 1.0.0
3,320,120 B

Twinify 1.0.2
1,864,120 B

That's approximately 44% less memory allocation.

This is particularly important for applications performing large numbers of mappings because unnecessary allocations can increase GC pressure.

Reduced GC Pressure

The reduction in allocations is also reflected in the GC measurements.

For the 1,000-user benchmark, Gen0 collections dropped from:

523.4375 → 296.8750

That's approximately a 43% reduction.

Gen1 also decreased:

242.1875 → 171.8750

or approximately 29%.

These improvements are encouraging because they show that the memory optimizations are not simply reflected in the allocation column; they are also reducing GC activity.

What About AutoMapper?

AutoMapper 16.2.0 is still ahead in this benchmark.

For 1,000 users:

Twinify 1.0.2   2,420.444 μs
AutoMapper      1,108.267 μs

And in allocations:

Twinify 1.0.2   1,864,120 B
AutoMapper        864,120 B

So there is still work to do.

What's Next?

The next optimization targets are clear.

I'm particularly interested in reducing:

Mapping execution overhead
Allocations during nested and collection mapping
Reflection or dynamic dispatch on the hot path
Temporary objects and collections
GC pressure during large mapping operations

The current results already show that there is plenty of room for optimization.

The next milestone is to continue closing the gap while keeping Twinify's API simple and predictable.

Why Benchmark?

One of the things I want to emphasize with Twinify is that performance claims should be backed by reproducible benchmarks.

Rather than simply saying that a mapper is "fast", I'm trying to track actual changes between releases.

For example:

Twinify 1.0.0
      ↓
4.42 ms / 1,000 users
      ↓
Twinify 1.0.2
      ↓
2.42 ms / 1,000 users

That gives future releases something concrete to improve against.

Try Twinify

Twinify is available on NuGet and the documentation contains examples covering profiles, nested mappings, collections, dependency injection, and other mapping scenarios.

Documentation:
Twinify Documentation

NuGet:
Twinify on NuGet

The current NuGet listing identifies 1.0.2 as the latest Twinify release.

Final Thoughts

Twinify 1.0.2 is another step forward.

The current benchmark shows:

45% faster bulk mapping compared with Twinify 1.0.0
44% less memory allocation
♻️ 43% fewer Gen0 collections
A significantly smaller performance gap compared with the initial release

There is still a lot of optimization ahead, and that's part of the fun.

I'm looking forward to seeing how far Twinify can go.

If you're interested in .NET object mapping, performance optimization, or open-source development, I'd love to hear your thoughts and feedback.

Twinify — Object Mapping Made Simple.

dotnet #csharp #opensource #performance

Getting Started with Twinify: A Free, Open-Source Object Mapper for Modern .NET

Thu, 27 Aug 2026 05:20:33 +0000

Lightweight. Familiar. MIT Licensed. Built for .NET 8, 9, and 10.

Following AutoMapper's recent licensing changes, many .NET developers have started looking for an open-source alternative that doesn't require rewriting years of mapping code.

That's one of the reasons I built Twinify.

Twinify is a lightweight, high-performance object-to-object mapper that provides a familiar fluent API, making it easy to map DTOs, entities, view models, records, and complex object graphs while remaining completely open source under the MIT License.

If you're already using AutoMapper, you'll find the transition straightforward for many common mapping scenarios.

Why Twinify?

✔ MIT Licensed

✔ Built for .NET 8, .NET 9 & .NET 10

✔ Familiar AutoMapper-style Fluent API

✔ Dependency Injection Support

✔ Automatic Convention-Based Mapping

✔ Nested Objects & Collections

✔ Flattening

✔ Record & Constructor Mapping

✔ Mapping Diagnostics with Explain<TSource, TDestination>()

Installation

Install the required packages.

dotnet add package Twinify
dotnet add package Twinify.DependencyInjection

Step 1 — Create a Mapping Profile

Define your mappings by inheriting from MappingProfile.

public class UserProfile : MappingProfile
{
    public UserProfile()
    {
        CreateMap<User, UserDto>()
            .ForMember(d => d.FullName,
                opt => opt.MapFrom(s => $"{s.FirstName} {s.LastName}"))
            .ForMember(d => d.Password,
                opt => opt.Ignore());
    }
}

Twinify uses a familiar fluent configuration model that should feel natural to developers coming from AutoMapper.

Step 2 — Register Twinify

builder.Services.AddTwinify(cfg =>
{
    cfg.AddProfile<UserProfile>();
});

Step 3 — Map Your Objects

Inject IMapper wherever it's needed.

public class UserService(IMapper mapper)
{
    public UserDto GetUser(User user)
    {
        return mapper.Map<UserDto>(user);
    }
}

That's all you need.

Twinify automatically maps properties with matching names while allowing full customization when required.

Features

Automatic Convention Mapping

Properties with identical names are mapped automatically.

User.Name
        ↓
UserDto.Name

No configuration required.

Automatic Flattening

Nested properties are flattened automatically.

Source

User.Address.City

↓

Destination

UserDto.AddressCity

Nested Object Mapping

Twinify recursively maps nested object graphs.

Order
 └── Customer
 └── Address
 └── Contacts

↓

OrderDto
 └── CustomerDto
 └── AddressDto
 └── ContactDtos

Collection Mapping

Supports:

Lists
Arrays
Dictionaries
Nested collections

Constructor & Record Mapping

Twinify automatically constructs destination types, including:

Immutable objects
Records
Parameterized constructors

Fluent Configuration

Twinify supports a rich configuration API, including:

CreateMap
ForMember
MapFrom
Ignore
Condition
ConvertUsing
BeforeMap
AfterMap
ReverseMap
IncludeBase
PreserveReferences

Explain Your Mappings

One feature that sets Twinify apart is mapping diagnostics.

mapper.Explain<User, UserDto>();

Instead of guessing why a property mapped the way it did, Explain() shows exactly where every destination member receives its value, making debugging significantly easier.

Migrating from AutoMapper

Many existing AutoMapper projects can migrate with only a few mechanical changes.

AutoMapper	Twinify
`Profile`	`MappingProfile`
`CreateMap()`	Same familiar API
`ForMember()`	Same familiar API
`MapFrom()`	Same familiar API
`ReverseMap()`	Supported
`AddAutoMapper()`	`AddTwinify()`
Custom resolvers	`ConvertUsing()` and member configuration

Migration Guide

1. Remove AutoMapper

dotnet remove package AutoMapper

2. Install Twinify

dotnet add package Twinify
dotnet add package Twinify.DependencyInjection

3. Update Your Profiles

Replace

public class UserProfile : Profile

with

public class UserProfile : MappingProfile

4. Update Dependency Injection

Replace

builder.Services.AddAutoMapper(...);

with

builder.Services.AddTwinify(cfg =>
{
    cfg.AddProfile<UserProfile>();
});

5. Build & Test

Many existing CreateMap() and ForMember() configurations should require little or no modification.

As with any migration, it's recommended to run your existing mapping tests to validate behavior.

Why I Built Twinify

I wanted a mapper that is:

Open source
Lightweight
Easy to understand
Familiar to existing AutoMapper users
Built specifically for modern .NET

Rather than forcing developers to learn an entirely new API, Twinify focuses on keeping the transition intuitive while continuing to evolve with community feedback.

Getting Started

NuGet

dotnet add package Twinify

Documentation

https://github.com/StevenKamwaza/Twinify.Docs

Source Code

https://github.com/StevenKamwaza/Twinify

⭐ If Twinify helps your project, consider giving the repository a star and sharing your feedback. Community contributions and feature requests are always welcome.

Happy Coding!

Built with ❤️ for the .NET community.

Have questions, feature ideas, or migration feedback?

Open an issue or start a discussion on GitHub—I'd love to hear how you're using Twinify in your projects.

dotnet #csharp #dotnet8 #dotnet9 #dotnet10 #opensource #nuget #softwareengineering #backend #webdevelopment #cleanarchitecture #developer #coding #programming #github #aspnetcore #entityframework #architecture #productivity #developers #devcommunity #100DaysOfCode #BuildInPublic #OSS #AutoMapper #Twinify

Coder Legion - Recent posts tagged dotnet

Day 2: An Overview of Definition-Driven Architecture

1. Which layer holds the single source of truth

For definitions to be the truth, two conditions, neither optional

A single source of truth is not a claim, it is a dependency direction

2. Which layers are derived from definitions

Generating code, or generating objects

3. What is left to the application

4. Architectural patterns: three sources, one piece from each

5. Systems this should not be applied to

The Northwind case study: how much one definition does

How to Build Better Full Stack Applications by Solving Small Problems First

The Problem: Small Issues Can Become Big Problems

How I Approach These Problems

A Practical Example

Where AI Can Help

Final Thoughts

ERP Architect's Notes: Designing a Definition-Driven Framework · Series Index

Chapter One · Why Definition-Driven

Chapter Two · Definition Layer

Chapter Three · Data Access and Caching

Chapter Four · Business Logic and API

Chapter Five · Multi-Tenancy and Customization

Chapter Six · Transport, Security and Audit

Chapter Seven · Data Semantics

Chapter Eight · Case Review and The Big Picture

About the framework behind this series

Day 1: Why ERP Needs a Definition-Driven Framework

Who I am

About the framework, and about this series

1. The cost of a single change: how many places one field lands in

A team boundary runs straight through that table

2. The cost of scale: multiply that table by a thousand

3. The cost of customization: how do you deliver it once it is done

4. Three problems that never got solved

5. Where the paradigms diverge

6. A controlled experiment: how many places for the same field

What happened to the team boundary

After the change lands

7. A map of the thirty posts

A thread to pick up later

A JSON-RPC Library With No Method Registration: How Does It Decide What Can Be Called?

1️⃣ What it covers

2️⃣ Getting started

ASP.NET Core server (Minimal API)

Client

3️⃣ With no registration, which methods can be called?

4️⃣ The client

5️⃣ Extension points: filters and interceptors

6️⃣ Encrypted payloads

7️⃣ How it differs from common libraries

8️⃣ Design trade-offs

✅ Wrapping up

Further reading

A Stopwatch Needs an Isolated Lane

The contract was reasonable

The failure blamed the wrong interval

Keep the budget before changing it

Isolate the claim, not the whole suite

The trade-off is real

A practical review checklist

Precision is a property of the experiment

From Anemic Models to Rich Domain Models, DDD Base Entities, and C# Records

Part 1: The Anti-Pattern (Anemic Models & DTO Misuse)

The Problematic Approach

Why Anemic Models Fail

Part 2: DDD Foundation — Entity Base Class & C# Records

1. DDD Entity Base Class

2. C# Records for Value Objects

Part 3: Combining Interfaces, Abstract Classes, and DDD Entities

Part 4: The Rich Domain Model (Order)

Part 5: Orchestrating with SRP and Dependency Injection

Part 6: Persistence with EF Core (Mapping Records & TPH)

Part 7: Unit Testing with Records & Entities

References & Further Reading

Tuesday Coding Tip 28 — (de)serializing JSON string enum in C#

A Query Window Is Not a Calendar Day

Retrieval and meaning are different jobs

Define “today” in the relevant time zone

Preserve the exception that actually matters

Part 4: The Rich Domain Model (`Order`)