DEV Community: Ivan Rossouw

A Green Build Is Not a Route Test

Ivan Rossouw — Tue, 01 Sep 2026 06:21:34 +0000

A Blazor Hybrid application can compile successfully and still fail as soon as its router starts.

The uncomfortable part is that nothing needs to be wrong with the individual components. The failure can live in the composition of otherwise valid Razor pages: two scanned assemblies declare the same route, and the conflict is only discovered at runtime.

That makes route ownership an architectural contract, not just an @page detail.

The invisible route set

Multi-head applications often share UI through a Razor class library. A web host, a progressive web app, and a .NET MAUI host may each scan two places:

the host's own assembly; and
a shared UI assembly.

This is useful. Shared pages can be implemented once while each host keeps pages that depend on its own authentication model, platform services, or startup behaviour.

It also creates a set that the compiler does not reason about: all routes visible to one router.

Imagine the shared assembly contains:

@page "/settings"

Later, a host-specific page independently declares the same path. Both components are valid. Both assemblies compile. The duplicate becomes visible only when that host's router scans the combined set.

Why a green build is insufficient

Compilation proves that each project is structurally valid. It does not prove that independently compiled route tables are unique when combined.

This is a general modularity problem. A module can be correct in isolation while the application graph is invalid after composition. Dependency-injection cycles, duplicate HTTP endpoints, conflicting configuration keys, and route collisions all share this shape.

For Blazor, the timing makes the failure especially awkward. The collision can wait until the router initialises on first load. A pipeline may restore, compile, and test successfully, while the person opening the application becomes the integration test.

Why the MAUI host changes the decision

Web applications can cheaply receive post-deploy smoke coverage: request a page and assert that it renders instead of returning an error.

A MAUI build is different. Producing an Android or iOS binary does not prove that a BlazorWebView can start, compose its scanned assemblies, and navigate. A real-device or emulator startup test is valuable, but it adds workload installation, boot time, device management, and another source of CI instability.

In the committed change I reviewed, the web-facing heads had page smoke coverage while the MAUI workflow had no equivalent startup check. That made a fast structural guard a sensible intermediate layer.

Build a focused collision guard

The guard does not need to reproduce the whole Razor runtime. It needs to answer one architectural question:

Within the assemblies scanned by each host, is any route declared more than once?

A practical implementation can:

enumerate .razor source files for a host and its shared UI project;
ignore generated bin and obj trees;
remove Razor and HTML comments;
recognise only complete @page directive lines;
normalise paths with an explicit case policy; and
group the resulting declarations by route.

Run the same assertion for every head. A collision report should name the generalized host and the two source locations so a developer can resolve ownership quickly.

This test is intentionally narrow. It does not need a browser, emulator, dependency container, or application server. Its value is that it turns a late composition failure into an early, deterministic signal.

Make the guard prove itself

Source guards have a dangerous failure mode: they can pass because the parser found nothing.

That is why a negative assertion such as “there are no duplicates” is incomplete. Add an anti-vacuous test that requires the parser to find a few routes that must exist. If a future Razor syntax change, path change, or parser bug empties the result, the test fails instead of giving false confidence.

Test false positives too. Comments often contain route examples:

@* Do not duplicate @page "/settings" in this host. *@

A naïve text search counts that as a declaration. A focused parser should ignore it, and a test should pin that behaviour. Excluding generated copies matters for the same reason; otherwise every route can appear to collide with itself.

The trade-off

A source-level guard is fast and portable, but it is coupled to project layout and Razor syntax. It does not exercise the real router, dependency injection, native lifecycle, or device packaging.

A device startup test provides higher-fidelity evidence, but it is slower and more operationally expensive. The two tests answer different questions:

source guard: is the declared route set structurally unique for every host?
device smoke test: can the packaged application actually start and navigate in its platform environment?

Use the source guard for immediate feedback, then add at least one device-startup path when the release risk justifies the cost.

A practical checklist

Before adding or moving a shared Razor page:

Write down every assembly each host scans.
Decide whether the route is shared or host-owned.
Assert uniqueness across each host's complete scanned set.
Prove the guard finds known routes.
Prove comments and generated output do not create false routes.
Keep a device startup check on the roadmap, because structural tests are not runtime proof.

Shared UI is valuable precisely because it removes duplication. The price is making the composition rules explicit. A green build tells you the parts compile. A route test tells you whether those parts can safely meet.

Your PowerShell Script Has a .NET Runtime Too

Ivan Rossouw — Mon, 31 Aug 2026 06:25:23 +0000

A PowerShell script can parse cleanly, pass review, and still fail before it performs any useful deployment work.

The missing part of the compatibility statement is often the runtime underneath the shell.

A recent CI/CD fix in a shared .NET repository exposed a compact example. A deployment-proof script needed case-aware substring checks, so it called this overload:

$text.Contains(
    $expected,
    [System.StringComparison]::OrdinalIgnoreCase)

In a minimal two-host smoke check, that expression works in modern PowerShell running on current .NET. On Windows PowerShell 5.1, backed by the older .NET Framework, the isolated call fails with a method-resolution error because that overload is not available.

The script's syntax is valid in both places. The API surface is not.

PowerShell is also a .NET API client

PowerShell makes .NET methods feel like part of the language. That convenience can hide an important dependency.

When a script calls an instance method, overload resolution happens against the runtime loaded by the current host. A method introduced in a newer .NET version does not become available merely because the PowerShell syntax parser accepts the expression.

This creates a portability stack:

PowerShell language version;
underlying .NET runtime and API surface;
installed modules;
native tools and their versions; and
host operating-system behaviour.

“It is a PowerShell script” names only the first layer.

Preserve the semantics, not just the outcome

The fix was to use an older-compatible API while keeping the comparison rule explicit:

$text.IndexOf(
    $expected,
    [System.StringComparison]::OrdinalIgnoreCase) -ge 0

IndexOf returning zero or greater means the value was found. More importantly, the explicit StringComparison preserves the original case and culture semantics.

A tempting rewrite is:

$text -like "*$expected*"

That may be acceptable in some scripts, but it changes the contract. Wildcard metacharacters, default case behaviour, and culture expectations can produce different results. Compatibility work should not quietly change meaning.

When replacing an unavailable API, write down the behaviour being preserved:

ordinal or culture-aware comparison;
case-sensitive or case-insensitive matching;
literal text or wildcard pattern;
null and empty-value behaviour; and
success and failure return conventions.

Choose a support strategy deliberately

There are two honest approaches.

Standardise on a modern host. Pin PowerShell 7 and a known .NET runtime in every supported runner. This gives scripts a cleaner API surface and reduces compatibility branches.

Support the oldest required host. If a deployment server still runs Windows PowerShell 5.1, treat that environment as part of the product contract. Use compatible APIs and test there.

Neither choice is free. Upgrading a runner may involve operating-system constraints, security review, module changes, or a carefully staged deployment. Supporting multiple engines increases the test matrix and can make otherwise simple expressions more verbose.

The expensive option is pretending the choice has not been made.

Put the real runtime in the test loop

A source guard can stop a known incompatible pattern from returning. For example, a repository test might require the supported IndexOf form and reject the problematic Contains overload in a critical script.

That is useful, but it is structural evidence. It proves that one text pattern is absent; it does not prove the script runs on the target host.

A stronger CI matrix adds a small runtime smoke test:

$engines = @(
    @{ Name = "legacy"; Command = "powershell.exe" },
    @{ Name = "modern"; Command = "pwsh" }
)

foreach ($engine in $engines) {
    & $engine.Command -NoProfile -File ./verify-script-contract.ps1
    if ($LASTEXITCODE -ne 0) {
        throw "Runtime contract failed for $($engine.Name)"
    }
}

In a real pipeline, run this on actual runner images rather than assuming both commands on one machine represent production. Keep the smoke test narrow: load the script, exercise compatibility-sensitive helpers, and avoid invoking external side effects.

Build a runtime manifest

For deployment automation, a small machine-readable manifest can make assumptions reviewable:

shells:
  - windows-powershell-5.1
  - powershell-7
requiredModules:
  - name: Example.Module
    minimumVersion: 2.4.0
nativeTools:
  - name: dotnet
    version: 10.0.x

The exact format is less important than ownership. Someone must decide when an old engine leaves the support set, who validates runner images, and how a toolchain change is rolled out.

The practical review

When a CI or deployment script changes, ask:

Which shell executable will run it?
Which .NET runtime backs that shell?
Are called method overloads present there?
Are comparison semantics explicit?
Are module and native-tool versions pinned or checked?
Does at least one test execute on the oldest supported runner?

Portability is not a property of syntax alone. It is an agreement between the script and the complete execution environment.

Make that environment explicit, test the oldest supported boundary, and choose compatibility shims only when they preserve the behaviour you intended.

Email Is Not a Web Page

Ivan Rossouw — Sun, 30 Aug 2026 08:25:08 +0000

An HTML email can be generated correctly, accepted by a provider, and delivered successfully—then arrive with its most important image missing or transformed.

That is not only a design problem. It is an architectural reminder: email is a delivered document, not a miniature web page.

A web page runs in a renderer you can observe and update. An email leaves your boundary and enters clients that may block remote images, proxy them, cache them, rewrite markup, or alter colours for dark mode. When a visual matters to recognition or comprehension, a normal web asset reference can be a surprisingly weak contract.

The hidden web-page assumption

A remote image looks attractive because it keeps the message small and lets many messages share one cached asset. It also assumes several things outside your control:

the client permits a network fetch;
the remote address remains reachable;
a privacy proxy preserves the response;
the client supports the markup as expected; and
colour transformations do not destroy contrast.

Those assumptions may be acceptable for decoration. They are less comfortable when the visual helps a recipient recognise the sender or understand the message.

Classify content by consequence

Before choosing an image strategy, classify the content.

Critical to recognition or understanding: consider embedding it in the message, give it useful alternative text, and test the degraded path.

Decorative: a remote image may be sufficient. Its absence should not change the meaning.

Essential information: express it as real text. An amount, deadline, action, warning, or status should never exist only inside pixels.

This classification is more useful than a blanket rule that every image must be embedded.

Put critical pixels inside the message

Most mail formats can carry an inline attachment with a content identifier. The HTML references that identifier instead of asking the client to fetch a public resource.

A small value object keeps the template independent of storage details:

public sealed record EmailVisual(
    string Reference,
    string MediaType,
    ReadOnlyMemory<byte>? Content,
    string? RemoteFallback);

If Content is present, the sender adds one inline attachment and renders the image source as cid: plus Reference. If only RemoteFallback is present, the template retains the remote form.

The important idea is not the record shape. It is that the template receives a resolved rendering decision rather than opening files or guessing media types itself.

Separate resolution from sending

In ASP.NET Core, a narrow resolver can use the host's file abstraction to load a trusted, deployed asset, derive a MIME type from its configured filename, and carry that resolved value with the bytes.

public EmailVisual Resolve()
{
    if (string.IsNullOrWhiteSpace(options.LocalAsset))
        return EmailVisualFactory.Remote(options.FallbackAddress);

    var file = files.GetFileInfo(options.LocalAsset);

    if (!file.Exists)
    {
        logger.LogWarning("Configured email visual was not found");
        return EmailVisualFactory.Remote(options.FallbackAddress);
    }

    try
    {
        using var stream = file.CreateReadStream();
        using var buffer = new MemoryStream();
        stream.CopyTo(buffer);

        return EmailVisualFactory.Inline(
            reference: "message-visual",
            mediaType: MediaTypes.For(file.Name),
            content: buffer.ToArray(),
            fallback: options.FallbackAddress);
    }
    catch (IOException exception)
    {
        logger.LogWarning(exception, "Email visual could not be loaded");
        return EmailVisualFactory.Remote(options.FallbackAddress);
    }
}

This example is deliberately general. In production, validate the configured path, bound the asset size, map only allowed media types, and catch only failures the resolver can safely degrade.

Keeping resolution separate gives the template, transport adapter, and tests one stable contract.

Degrade presentation without failing composition

A missing decorative or recognition image should usually not prevent an otherwise useful transactional message from being composed.

That makes fallback behaviour part of the design. If a configured local asset is missing or unreadable, retain a safe remote reference and emit an operational warning. If no local path is configured, the remote representation can remain the expected path rather than an error. The message still contains its text, links, and actions.

This is not the same as pretending nothing happened. Composition continues, while telemetry records that presentation degraded. If the image contains essential meaning, the safer fix is to move that meaning into text rather than make message composition depend on image resolution.

Design for client transformations

Embedding solves the remote-fetch dependency. It does not make every client render identically.

Transparent artwork that looks good on a web page can lose contrast when a mail client applies dark-mode transformations. An email-specific asset with an explicit light canvas and sufficient internal contrast can make the intended result more stable.

That is a separate rendering asset, so name and own it as one. Do not silently assume the main web image is suitable for mail.

Test the contracts you own

Useful automated tests focus on decisions within the application boundary:

A configured local asset resolves to the expected bytes and media type.
A missing or unreadable asset returns the remote fallback without throwing.
No configured local asset keeps the remote path.
Embedded content becomes exactly one inline attachment.
The HTML references the matching content identifier.
Remote-only rendering does not create an unnecessary attachment.
Render snapshots select the intended email-specific asset.

These tests prove composition and degradation behaviour. They do not prove universal compatibility across every mail client. A small real-client review matrix is still valuable for high-volume templates.

The trade-off

Inline assets increase message size and remove shared caching. Rendering-specific variants create another file to maintain. Content identifiers and media types add composition rules that remote images avoid.

In return, critical pixels travel with the message and do not depend on a public fetch when inline resolution succeeds. A fallback keeps local image resolution non-fatal.

The practical rule is simple: embed what matters, keep essential meaning in text, and let presentation degrade without stopping the message.

Catch by Recovery Policy, Not Convenience

Ivan Rossouw — Sat, 29 Aug 2026 07:55:14 +0000

Liquid syntax error: 'raw' tag was never closed

Gate New Actions, Keep Recovery Open

Ivan Rossouw — Fri, 28 Aug 2026 06:53:30 +0000

Liquid syntax error: 'raw' tag was never closed

Gate New Actions, Keep Recovery Open

Ivan Rossouw — Fri, 28 Aug 2026 06:10:57 +0000

Liquid syntax error: 'raw' tag was never closed

Counts Match. The Data Can Still Be Wrong

Ivan Rossouw — Thu, 27 Aug 2026 06:26:55 +0000

Many systems eventually need to repartition one persisted record. A batch becomes several processing groups. A container becomes several parcels. A work queue becomes several assignments.

The domain changes, but the risk is consistent: every child must move from one source into exactly one result without being invented, duplicated, or lost.

The tempting safeguard is a count comparison:

The source contains twelve items.
The proposed results contain twelve items altogether.
Therefore, the split must be valid.

Unfortunately, equal counts prove only cardinality. They do not prove identity.

The blind spot in a passing count

Imagine that a source contains the item IDs A, B, and C.

A proposed split contains:

Result one: A, A
Result two: C

The source and outputs both contain three entries. A count check passes, even though A was duplicated and B disappeared.

Another invalid proposal might contain A, B, and D. Again, the count matches, but an unknown item has replaced a valid one.

These are not arithmetic failures. They are failures of identity conservation.

State the stronger invariant

For a valid repartition, the original identity set must equal the disjoint union of the output identity sets.

That gives us three useful requirements:

Every original ID appears in the outputs.
No unknown ID appears in the outputs.
No ID appears more than once.

Set equality proves membership. A duplicate check proves disjointness. Cardinality remains useful, but only as one part of the invariant.

Validate before mutation

A generalized C# guard can make that rule explicit:

static void EnsureExactPartition(
    IReadOnlyCollection<Guid> originalIds,
    IEnumerable<IReadOnlyCollection<Guid>> partitions)
{
    var original = originalIds.ToHashSet();
    var output = partitions.SelectMany(ids => ids).ToArray();

    var sourceHasDuplicates = original.Count != originalIds.Count;
    var outputHasDuplicates = output.Distinct().Count() != output.Length;

    if (sourceHasDuplicates ||
        outputHasDuplicates ||
        output.Length != original.Count ||
        !original.SetEquals(output))
    {
        throw new InvalidOperationException(
            "The requested split is not an exact partition.");
    }
}

This example is deliberately small. In a real application, authorization, lifecycle state, concurrency, and ownership rules may add further checks. The important ordering is that the complete proposal is validated before tracked entities or database state are changed.

That ordering makes failure cheap. An invalid request becomes a rejected request, not a cleanup exercise.

Move tracked children instead of copying them

When the children already exist as tracked entities, repartitioning should preserve their identities.

Creating new child objects by copying fields can accidentally turn a move into duplication. It may also lose historical references, introduce new primary keys, or leave the originals attached to the source.

Instead, load the authorized source and its children, resolve each requested ID to the existing tracked instance, and re-parent that instance to its destination. With EF Core, this usually means updating the relationship through the navigation property or foreign key and allowing relationship fix-up to track the move.

The output records are new. The children are not.

Make the whole transition atomic

A valid split still should not become partially visible.

Creating two results, failing on the third, and leaving the source marked as processed produces a state that is difficult to reason about and harder to retry safely.

Treat these changes as one unit:

Create every result.
Move every child.
Transition the source record.
Save the complete state atomically.

A single SaveChanges call is transactional for supported relational providers. If the workflow requires multiple saves or coordinates additional durable work, use an explicit transaction or an outbox-style boundary.

The desired outcome is simple: observers see either the original state or the complete repartitioned state, never a mixture.

Give every result an idempotency scope

Operation-level idempotency is helpful, but a split produces several distinct results. Each result therefore needs a stable scope of its own.

A compound uniqueness boundary such as (operationId, stableResultKey) lets a retry identify each intended result independently. The result key should come from stable input or deterministic content, not an array position whose meaning may change when ordering changes.

A database uniqueness constraint should enforce this promise. Application checks improve error messages; the constraint protects correctness under concurrency.

The trade-off is intentional friction

Exact set validation allocates collections. Transactions hold resources. Unique indexes add storage and write cost. The implementation is more involved than comparing two integers.

For very large partitions, validation may need to move closer to the database or use streaming and batching. That changes the mechanism, not the invariant.

The additional friction buys something valuable: failures occur before mutation, concurrent retries converge, and the persisted model remains explainable.

Tests that expose the boundary

A compact test suite should include:

A valid partition in a different order
One duplicated ID
One omitted ID
One foreign ID
A retry using the same per-result scopes

The negative cases should fail before any entity is re-parented or source state is changed.

The practical lesson is modest: whenever one persisted record becomes many, ask more than, “Did the counts match?”

Ask, “Did every identity move exactly once?”

A Secret Store Is Not a Boundary Until It Is the Only One

Ivan Rossouw — Wed, 26 Aug 2026 06:29:16 +0000

Moving long-lived credentials into a managed secret store is a good security change. It is also easy to stop that migration too early.

The uncomfortable question is not, “Do we have a secure store?” It is, “Can this credential still travel through any other path?”

A recent C# and ASP.NET Core hardening change brought that distinction into focus. The intended store was secure, but older disk-backed helpers—including an SDK-backed file cache—still existed. The destination had improved; the authority model had not yet become singular.

The migration illusion

OAuth integrations often accumulate several generations of code:

a first version that writes a token file;
a later service that saves a reference to a protected or managed secret;
a legacy SDK helper configured with its own file-backed cache;
a compatibility controller or helper that can still read the old files; and
an environment fallback added to keep development convenient.

Each part can look reasonable in isolation. Together, they create multiple credential authorities.

That matters because an attacker, operator, or future maintainer does not care which path the architecture diagram calls canonical. If an older reader can authenticate with a disk file, or a library can write a fresh cache beside the managed store, that alternate path is part of the real boundary.

Security posture follows the weakest active route.

Define one credential authority

A useful target state is closed-world: every credential read and write is accounted for, and anything outside the approved store is rejected.

For a server-side integration, that might mean:

Resolve client configuration directly from the configuration providers and parse it in memory.
Exchange authorization codes without allowing the SDK to persist tokens.
Store refresh tokens only through the application-owned credential service.
Persist an opaque reference and provider metadata, never the plaintext token.
Retrieve and retire the token through that same service.

The key phrase is “only through”. A secure store is not merely another destination. It is the sole authority.

Close SDK persistence explicitly

Third-party SDKs often provide convenient persistence helpers. Those are useful in a desktop sample and risky in a multi-user server process.

Make the decision visible in every active flow:

var flow = new AuthorizationFlow(new AuthorizationFlowOptions
{
    ClientConfiguration = ResolveInMemory(configuration),
    CredentialStore = new NoOpCredentialStore()
});

The names here are deliberately generic, but the principle is concrete: do not leave persistence semantics implicit or assume another layer owns them. Supply the no-op implementation where the SDK accepts its persistence dependency.

Then enumerate all flows. Initial connection, token refresh, and API-client construction may each build their own authorization object. Fixing two out of three still leaves a second authority.

Delete the old path

Deprecating a credential path in a comment is not the same as removing it.

Delete obsolete file readers, writers, controllers, helper services, configuration keys, and package references. Remove their dependency-injection registrations. Stop copying old credential assets into build output. If a compatibility period is unavoidable, give it an owner, an expiry condition, and telemetry that proves whether it is still used.

Deletion reduces the proof surface. Reviewers can reason about what exists instead of relying on a promise that reachable code “should no longer run”.

Test that the forbidden path stays absent

Behaviour tests are essential, but some architecture regressions are difficult to trigger naturally. A convenience helper could be restored with file-backed caching while happy-path authorization tests remain green.

This is one of the rare cases where a focused structural guard is useful. It can:

take a non-empty census of the relevant production sources;
require every known authorization flow to opt into the no-op store;
reject known disk-store types, filenames, and helper calls; and
assert that retired endpoints and directories remain absent.

The non-empty census matters. A source scan that finds zero files can pass while proving nothing.

Pair that guard with behavioural tests. Place a plausible legacy credential file where old code would have found it and prove the application ignores it. Simulate a managed-store write failure and prove the operation fails without persisting plaintext. For a development-only protected fallback, prove stored material differs from the original token and can be recovered only through the protector.

Structural tests protect the shape; behavioural tests protect the outcome.

Fail closed by environment

Development and production do not need identical storage mechanisms, but both need explicit policy.

A local environment can use a protected, developer-owned store when a managed service would make ordinary work impractical. That fallback should be named and enabled deliberately. In non-development environments, the default should be no fallback: if the managed store is unavailable, the connection attempt fails.

That is an operational trade-off. Availability decreases during a store outage. The alternative is worse: a silent downgrade that creates a credential copy in a less controlled location precisely when the primary control is unavailable.

The engineering trade-off

One authority means stricter configuration, fewer emergency shortcuts, more failure-path tests, and a migration that touches more than the storage class. It may expose outages that a permissive fallback previously hid.

In return, incident response becomes clearer. There is one place to rotate, audit, revoke, and monitor. A failure cannot quietly change the protection level. Future maintainers have a smaller state space to understand.

Before calling a credential migration complete, draw every reader and writer—including SDK helpers. If you cannot point to the single authority for each environment, the boundary is still open.

Idempotence Must Survive the Clock

Ivan Rossouw — Tue, 25 Aug 2026 07:24:23 +0000

Calling an operation twice with the same input is a useful idempotence check. For scheduled automation, it is not always enough.

The second real invocation does not happen at the same instant. If current time influences classification, rendering, or persistence, then time is another input to the contract—even when the business state has not changed.

That distinction matters because a test can prove same-instant repeatability while missing repeated side effects on every future run.

The comfortable test that was incomplete

Consider a monitor that periodically evaluates a condition and maintains one notification. Its write plan is sensible:

Classify the current state.
Render the notification that should exist.
Compare it with the notification already stored.
Perform no write when the two are equal.

The first regression test might call the planner twice, pass the first output back as the stored value, and assert that the second call returns NoWrite.

That is valuable. It catches an implementation that always updates. But if both calls share a frozen clock, they exercise only one moment. They do not simulate two scheduler runs.

How time turns stable state into different output

The failure appears when the rendered body includes relative age:

The condition has been active for 2.0 hours.

Several minutes later, the underlying condition is identical, but the renderer produces:

The condition has been active for 2.1 hours.

A byte comparison is doing exactly what it was asked to do: the bodies differ, so it plans an update. The monitor writes again, subscribers may be notified again, and the audit trail gains another event even though nothing meaningful happened.

The defect is not in the equality check. It is in the definition of desired output. A volatile presentation value has accidentally become part of message identity.

Separate decision time from message identity

Elapsed time may still be essential to the decision. A monitor often needs to ask whether a condition has lasted long enough to deserve attention. Removing the clock entirely would weaken the behaviour.

The cleaner design is to separate classification from representation:

var state = Classify(input, clock.UtcNow);
var desired = Render(state, since: input.StartedAt);

return Normalise(previous) == Normalise(desired)
    ? Plan.NoWrite
    : Plan.Update(desired);

Here, current time helps decide whether the state has crossed a threshold. The persisted message uses an immutable event timestamp such as “active since 09:30 UTC”. As long as the underlying event is the same, the desired body remains stable.

The exact language and types will differ between systems. The useful boundary is consistent: use volatile time for decisions; use stable facts for identity.

Test the next scheduled run

The regression test should advance the clock while holding business state fixed:

var first = Plan(input, previous: null, at: t0);

var afterFourHours = Plan(input, previous: first.Body, at: t0.AddHours(4));
var afterOneDay = Plan(input, previous: first.Body, at: t0.AddDays(1));

afterFourHours.Action.Should().Be(NoWrite);
afterOneDay.Action.Should().Be(NoWrite);

Then add the complementary test: change the meaningful state and assert one update. Idempotence does not mean “never write again”. It means “repeat the same side effect only when the contract says the desired state changed”.

For a renderer whose output is intended to be stable, an even sharper assertion compares bodies across widely separated times. This catches any newly introduced current-time field, not just the one that caused the original defect.

The engineering trade-off

Relative wording is pleasant. “Active for two hours” saves the reader from doing mental arithmetic. An immutable timestamp is slightly less immediate.

Stable output, however, avoids redundant writes, rate-limit pressure, noisy audit history, repeated notifications, and eventually alert fatigue. Once people learn that a monitor repeats itself without new information, they stop trusting a signal that may later matter.

There are reasonable middle paths. A client can calculate relative age at display time without rewriting the stored message. A monitor can update only at meaningful threshold crossings, such as warning and critical. Or the volatile age can live in a dashboard while the notification remains a stable pointer to the underlying event.

The right choice depends on who reads the output and what an update triggers. The important part is to choose deliberately.

A practical review checklist

When reviewing scheduled or retryable automation, I now ask:

Is the clock injected so tests can move it?
Which decisions legitimately depend on current time?
Does any persisted or compared output contain a drifting value?
Can two runs with unchanged business state produce different bytes?
Does a no-op plan truly perform zero external writes?
Do tests cover both advanced time and changed state?

The small mental shift is this: do not test only “run it twice”. Test “run it now, then run it later with nothing meaningful changed”.

Where could a friendly relative timestamp be quietly turning your idempotent automation into a recurring side effect?

When Helper Text Becomes the Field Name: A Blazor Accessibility Lesson

Ivan Rossouw — Mon, 24 Aug 2026 12:14:27 +0000

A form can look correct, submit correctly, and contain valid HTML while still giving assistive technology the wrong name for a control.

I recently inspected a committed Blazor accessibility fix with exactly that shape. Several fields placed their helper prose inside the field's <label>. Visually, the layout was tidy. Semantically, every helpful sentence had joined the control's accessible name.

The focused lesson is simple: a label names a control; helper text describes it. Those are different contracts, and the markup should preserve the distinction.

The bug that pixels do not reveal

Consider this generalized Razor markup:

<label for="reference">
    Reference
    <input id="reference" />
    <span class="hint">
        Use the reference shown on the original document.
    </span>
</label>

A sighted user sees a short label, a field, and a quieter line of guidance. That visual hierarchy does not determine the accessibility tree.

Text associated through the label contributes to the control's accessible name. A screen reader may therefore announce something closer to “Reference, use the reference shown on the original document” as the field name. Repeat that pattern with a longer warning or policy note and routine form navigation becomes noisy.

The HTML can still validate. A component test can still find the input. A screenshot can remain pixel-for-pixel unchanged. The defect lives in semantics, not appearance.

Name and description are separate contracts

The safer structure keeps the label concise and connects the explanatory text separately:

<div class="field">
    <label for="reference">Reference</label>
    <input id="reference"
           aria-describedby="reference-hint" />
    <span class="hint" id="reference-hint">
        Use the reference shown on the original document.
    </span>
</div>

Now the relationships are explicit:

for and id associate the short name with the control;
the hint has its own unique identifier; and
aria-describedby asks assistive technology to announce the hint as supporting context.

The expected experience is a concise name first, then the explanation. Users who navigate by form control can scan efficiently without losing the useful guidance.

Why this is more than an ARIA edit

Moving the hint changes the document structure. The wrapper may now need to carry layout and typography that the old label supplied through inheritance. Without that CSS work, the semantic fix can cause inputs to change size, weight, spacing, or alignment even though the intended visual design has not changed.

Interactive content deserves another look too. A link nested inside a label can compete with the label's activation behaviour. Moving helper content outside the label makes the click targets honest again: the label activates the control; the link behaves as a link.

That is the engineering trade-off. The corrected markup needs a wrapper, stable IDs, deliberate CSS, and a little more review effort. In return, the field has a predictable name, the guidance remains available, and interactive descendants no longer share a misleading click target.

Test the semantics, not only the markup

The strongest check inspects the browser's computed accessibility tree. It should assert that the control has the expected accessible name and a separate description. That tests the behaviour users actually receive.

Not every test environment exposes that tree. A source guard can still be a useful backstop if its limits are explicit. For example, it can reject a hint nested inside a label, require every hint to have an ID, and require a matching aria-describedby reference.

An absence-only source test has a familiar risk: a wrong directory or broken pattern can find nothing and pass. Give the guard a non-vacuous census so it fails when it has not inspected a credible amount of markup. Then mutation-check it: deliberately move one hint back into a label, remove one description reference, and point the scan at an empty-but-valid directory. Each mutation should make the test fail for the intended reason.

The committed test I inspected follows that defensive shape. I did not rerun it, and it is not equivalent to a live screen-reader or browser accessibility-tree test.

A practical review checklist

For each field with helper text, ask:

Is the accessible name short and specific?
Is explanatory prose outside the label?
Does the hint have a unique ID referenced by the control?
Did the wrapper preserve the intended layout and font context?
Are any links or other interactive elements trapped inside a label?
Does at least one test inspect computed accessibility semantics, or clearly document the limits of its structural proxy?

Accessibility bugs often survive because the pixels look reassuring. Treat the accessibility tree as a first-class output of the component, alongside the rendered page and submitted model.

Where in your forms might helpful prose be quietly promoted into a field name?

Completion Is an Ownership Boundary

Ivan Rossouw — Sun, 23 Aug 2026 06:31:57 +0000

An async method can finish its useful work and still be holding lifecycle state that tells the rest of the system it is active.

That sounds like a tiny implementation detail. Under concurrency, it becomes a contract bug.

I recently inspected a committed C# fix where an attempt could settle while two paths still believed they owned the same cancellation source. One path was normal attempt teardown. The other was component disposal. A narrow scheduling window could let one path dispose the source while the other still intended to cancel it.

The lesson is broader than cancellation: completion is an ownership boundary. Before an operation becomes observably complete, its shared lifecycle resources and active-state markers should already have reached their next valid owner or terminal state.

The dangerous gap after the work is done

Consider a reusable client-side workflow that starts one attempt at a time. It stores:

the current task;
a cancellation source for that attempt;
an active-attempt identifier; and
a snapshot published to observers.

The network work finishes. The code builds a settled snapshot, publishes it, completes a TaskCompletionSource, and only then clears the active task and disposes the cancellation source.

For a moment, callers can observe “finished” while internal state still says “active.” A retry may join the stale completed task. Concurrent disposal may capture a source that the attempt is about to dispose. These failures are rare because the state is individually valid on both sides of the gap; only the ordering is wrong.

Give the resource exactly one owner

A cancellation source should not be “shared until somebody disposes it.” It should have one owner at each point in the lifecycle.

Here is deliberately invented C# to show the handoff pattern:

CancellationTokenSource? TakeAttemptCancellation()
{
    lock (_stateLock)
    {
        var owned = _attemptCancellation;
        _attemptCancellation = null;
        return owned;
    }
}

async ValueTask DisposeAsync()
{
    var owned = TakeAttemptCancellation();

    owned?.Cancel();
    await DrainActiveAttemptWithinBudgetAsync();
    owned?.Dispose();
}

The important operation is not Cancel or Dispose. It is the atomic transfer: read the shared field and clear it while holding the state lock. After that, the local variable is the sole owner. Another path entering the same lock finds null and knows it owns nothing.

Cancellation and disposal can then happen outside the lock, avoiding callbacks or slow work while shared state is protected.

Release before publishing completion

The attempt path needs the complementary rule. Clear the active task and detach or dispose its cancellation source before any observer can see the settled result.

In generalized form:

Result? settled = null;

try
{
    settled = await ExecuteAsync();
}
finally
{
    lock (_stateLock)
    {
        _activeAttempt = null;
        _attemptCancellation?.Dispose();
        _attemptCancellation = null;
    }

    if (settled is not null)
    {
        Publish(settled);
        _completion.TrySetResult(settled);
    }
}

This ordering gives completion a useful meaning: if an observer has seen the result or awaited the task, the object is already idle. The next operation cannot accidentally coalesce onto stale work.

This is not a universal instruction to dispose every resource inside a lock. The point is to make the ownership transition atomic. What happens after the transition depends on whether disposal can block, invoke callbacks, or acquire other locks.

Test the ordering, not the odds

A stress loop is useful as a backstop, but it may never hit an extremely narrow scheduling window. A deterministic regression test should control the boundary.

One approach is to block inside the observer that receives the settled snapshot. While publication is paused, inspect the object from another thread. The invariant should already hold:

the previous attempt is no longer active;
a new start cannot receive the stale completed task;
disposal can run without competing for the same source; and
repeated disposal remains harmless.

Also cover disposal while work is in flight. Those tests describe ownership much better than “run this race many times and hope.”

The engineering trade-off

Explicit ownership adds code. The order of lock-protected mutations becomes part of the design, and reviewers must reason about publication, task completion, cancellation, disposal, and retries together.

The return is a lifecycle contract people can explain: one owner at a time; observable completion implies released attempt state; disposal is idempotent; immediate retry starts new work.

The committed change I inspected applied singular cancellation-source ownership in two similar async workflows. In the detailed workflow behind this example, active state is also released before snapshot publication; the sibling workflow releases ownership before completing its returned task while retaining its existing publication path. The committed tests include deterministic settlement-boundary coverage for the detailed workflow plus repeated- and in-flight-disposal coverage across both. I inspected the implementation and test assertions, but I did not rerun the suite or verify runtime behaviour.

A practical review checklist

For every async operation with reusable state, ask:

What exactly does “complete” promise to observers?
Who owns each cancellation source before, during, and after settlement?
Can retry, disposal, or a callback enter between publication and teardown?
Can the ownership transfer be made atomic while expensive work stays outside the lock?
Is there a deterministic test that pauses at the boundary?

Rare races often survive because each line looks reasonable in isolation. Naming the ownership boundary makes the ordering reviewable.

Where does your API announce completion before it has finished releasing the attempt?

A Valid Lookup Can Still Be Historically Wrong

Ivan Rossouw — Sat, 22 Aug 2026 07:20:20 +0000

A configuration lookup can succeed, return a perfectly valid object, and still give the wrong answer.

The problem appears when we ask a present-day source to explain a past decision. Configuration answers, “What is true now?” Historical records often need to answer, “What was the user told then?” Those questions look similar in code, but they have different integrity requirements.

The bug hiding inside a successful lookup

Imagine a C# service that creates user-visible hand-off instructions. At creation time it resolves a destination from configuration, generates a reference, saves an instruction record, and returns both values to the user.

Later, the destination changes. Perhaps a fulfilment route changes or an external service is replaced. When the user reopens the old instruction, the application resolves the destination again.

The lookup succeeds. The new destination is valid. The old reference is valid.

Together, however, they describe an instruction that never existed.

No exception is thrown. Monitoring stays quiet. Every component may satisfy its local contract while the system rewrites its own history.

A valid lookup can still be historically wrong.

Persist the issued output

The safer design is to store the minimum output that the user or another system acted on when the record is created.

Here is a deliberately invented example:

public sealed class InstructionRecord
{
    public Guid Id { get; init; }
    public string Reference { get; init; } = "";

    public string? IssuedDestinationName { get; init; }
    public string? IssuedDestinationCode { get; init; }

    public bool HasIssuedSnapshot =>
        !string.IsNullOrWhiteSpace(IssuedDestinationName) &&
        !string.IsNullOrWhiteSpace(IssuedDestinationCode);
}

The write path resolves configuration once, then saves the resulting values with the record:

var destination = await destinationProvider.ResolveAsync(request.Route, ct);

var record = new InstructionRecord
{
    Id = Guid.NewGuid(),
    Reference = referenceFactory.Create(),
    IssuedDestinationName = destination.DisplayName,
    IssuedDestinationCode = destination.Code
};

db.Instructions.Add(record);
await db.SaveChangesAsync(ct);

The important detail is not the syntax. It is the source of truth. A later read reconstructs the old instruction from the stored snapshot, not from the current provider.

Persisting only the route or configuration key is often insufficient. That key tells us which branch was chosen, but the branch can still return different values later. If exact re-display matters, save the issued result.

Treat legacy nulls as honest uncertainty

Adding snapshots to an established table creates a difficult question: what should happen to existing rows?

An additive EF Core migration with nullable columns is often a practical deployment choice. New application code can write snapshots without requiring a risky backfill or a lockstep release. Old records remain readable.

But a null snapshot has meaning: the system cannot prove what was issued.

Backfilling those rows from current configuration would make the database look complete while inventing historical facts. That is worse than leaving the uncertainty visible.

A safer read model makes the distinction explicit:

DestinationSnapshot? snapshot = record.HasIssuedSnapshot
    ? new(record.IssuedDestinationName!, record.IssuedDestinationCode!)
    : null;

The user experience can then behave conservatively. For a snapshotted record, offer exact re-display. For a legacy row, withhold that action and ask the user to create a fresh instruction. This is not a temporary fallback to delete after rollout. Unless trustworthy historical evidence becomes available, it is the permanent safe behaviour.

In data modelling, “unknown” is often a valuable state. Hiding it with a guessed value does not improve integrity.

The trade-off is real

Snapshots duplicate data, and duplicated data demands discipline. You need bounded field lengths, appropriate access controls, retention rules, and a clear decision about which values are necessary. If the generated output includes secrets or sensitive personal data, copying it casually may create a larger problem than the one being solved.

Snapshots are also stale by design. That is their purpose. Current configuration remains authoritative for new instructions; the stored snapshot is authoritative for explaining an old one.

The benefit is a self-contained historical record. Support teams do not need to search messages or logs to reconstruct what happened. Users see the same instruction again. Audits can distinguish two records created under different configuration, even if both are inspected after the configuration changed.

The cost is extra schema and a permanent compatibility path. The return is historical correctness.

Test the boundary, not only the calculation

Useful tests for this pattern focus on the seam between mutable configuration and durable history:

the exact resolved values are persisted at creation;
different configuration branches produce distinguishable stored snapshots;
reads use the snapshot rather than resolving current configuration;
a legacy row without a snapshot does not enable exact re-display;
changing configuration after creation does not change the old instruction.

The lesson here came from read-only inspection of a recent committed change and its focused tests. I inspected what those tests assert, but I did not rerun them. That supports a design observation, not a claim about the current runtime or build state.

A practical decision rule

Before adding a snapshot, ask:

Did a person or external system act on this output?
Can the source values change independently?
Must we reproduce the old output later?
Would reconstructing it incorrectly cause harm or confusion?

If the answers point toward history, persist the minimum safe output at write time. Keep current configuration for new decisions, stored snapshots for past decisions, and null for history you genuinely cannot prove.

That separation is small in code, but it prevents a successful lookup from quietly changing the past.