DEV Community: MICHAEL-MAURICE

The Shadow Model Issued a Refund: 7 Mistakes That Make LLM Model Upgrades in .NET Riskier Than They Look

MICHAEL-MAURICE — Fri, 30 Oct 2026 12:56:08 +0000

"Let's shadow the new model first, then canary it." Everyone agrees with that sentence in planning. It sounds like the careful option, and it is, as long as the shadow can't do anything and the canary is the same set of users on every server.

I built a model-upgrade pipeline for a .NET 10 support assistant on Microsoft.Extensions.AI 10.11.0. The assistant has three tools: get_order, issue_refund and escalate_to_human. Two of them move money or create work for people. That's on purpose, because a shadow setup that's harmless for a chatbot can be dangerous for an agent.

Here are seven mistakes I made, or nearly made, on the way. The code is trimmed to the shape, and the trimmed parts are marked.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. The complete, working, tested version of this shadow and canary project is inside, with full source and an in-depth PDF guide. Join Tech Skill Builder

Mistake 1: Thinking you're upgrading a model id

The pull request says "switch to the new model". It usually also changes the system prompt "while we're at it", and maybe the temperature. Any one of those can change behavior. If your metrics only know the model id, you can't tell which change caused what, and two different prompts on the same model look like one release.

Fix: release the three together and give the combination a fingerprint:

public sealed record ModelRelease(string Name, string ModelId, PromptVersion Prompt,
    float? Temperature = null, int? MaxOutputTokens = null)
{
    public string Fingerprint => Hashing.Short(/* model id + prompt hash + options, culture-invariant (full version in the complete project) */);
}

In the project, a ReleaseChatClient (a plain DelegatingChatClient) pins a provider client to one release, so nothing in the app can quietly swap the prompt. The prompt registry is append-only: change a released prompt and you have a new release with a new fingerprint.

Mistake 2: Mirroring the whole request

This is the one in the title. The obvious shadow design sends each request through a second pipeline and compares the final answers. With tools, that second pipeline runs its own tool calls. In my demo, the "shadow" candidate rounded a refund up, and the order book ended with two refunds: 20.50 EUR from the live model and 21.00 EUR from the shadow. The shadow wasn't watching. It acted.

Fix: put the shadow under FunctionInvokingChatClient, so it compares one model turn at a time, and give the candidate the tools as declarations only:

public static ChatOptions DeclarationsOnly(ChatOptions? options)
{
    var o = options?.Clone() ?? new ChatOptions();
    // replace every AIFunction in o.Tools with f.AsDeclarationOnly(): same name and schema, not invocable
    // (full version in the complete project)
    return o;
}

The candidate decides with the same information, and its tool calls come back as FunctionCallContent that nothing executes. As a belt-and-braces check, the shadow runner asks the pipeline for GetService<FunctionInvokingChatClient>() and refuses to start if it finds one.

A nice side effect: comparing per turn gives you a precise, cheap signal. issue_refund {"amount":20.5} against issue_refund {"amount":21} doesn't need a judge to be flagged.

Mistake 3: Letting the shadow job hold references

The shadow runs later, on a background worker. If the job keeps references to the request's objects, it compares against something that has changed in the meantime.

Three ways this bit me:

Middleware that isn't under function invocation receives the caller's own message list. The app appends to it, so by the time the worker ran, the "input" had 3 messages instead of 1.
ChatMessage.Clone() is shallow. The clone and the original share one Contents list.
The request's cancellation token is cancelled when the request ends, which is exactly when shadow work starts.

Fix: snapshot on the request thread, with new messages and copied content lists, and give the runner its own timeout (through TimeProvider, so tests run on fake time) that's linked only to host shutdown.

Mistake 4: Trusting the channel to count what it dropped

The shadow must never slow down a real request, so jobs go into a bounded channel and are dropped when it's full. Fine. Then I counted the drops with the return value of TryWrite.

With BoundedChannelFullMode.DropWrite, TryWrite returns true for items it drops. In the demo, five writes into a channel of capacity two all returned true, and three of the jobs were gone.

Fix: count in the itemDropped callback you pass to Channel.CreateBounded, which is the only honest signal:

_channel = Channel.CreateBounded<ShadowJob>(
    new BoundedChannelOptions(capacity) { FullMode = BoundedChannelFullMode.DropWrite },
    dropped => { /* count it, and remember which job it was (omitted) */ });

Why it matters beyond ops: a queue that drops under load drops at peak hours, so your shadow sample quietly turns into a sample of quiet hours. The project's shadow gate holds when drops exceed a tenth of the enqueued jobs.

Mistake 5: Gating on "agreement"

The first gate I wrote said: promote if the candidate agrees with the current model often enough. On one simulated day, the shadow compared 898 turns and agreement was 58.4%. Was that bad?

Mostly it was style. The new prompt asked for a warmer tone, and "Good news! Your order is shipped..." scores low against "Order shipped." A terse model that gets dates wrong could score higher. Agreement measures voice as much as quality.

Fix: gate on mechanical red flags, each with its denominator, instead of on overall similarity:

the candidate refused where the current model answered (2.6% that day; my limit is 1%)
a different tool or different arguments on tool turns (13.0%; limit 2%)
text-versus-tool decision flips, candidate failures and timeouts, latency, and the drop rate

That first candidate held on refusals and tool divergence. And a shadow gate never rolls back on its own, because no user is exposed yet. It holds and waits for a person.

Mistake 6: Bucketing users with `GetHashCode()`

Once the shadow is clean, real users get the candidate. Each user must land on the same side on every request, every pod and every restart. Math.Abs(userId.GetHashCode()) % 100 looks fine and isn't: string hashing in .NET is randomized per process, so your 1% is a different 1% on every instance.

Fix: a stable hash with a per-rollout salt:

public static int Of(string salt, string subject)
{
    // SHA-256 over salt + separator + subject, first 8 bytes as an unsigned number,
    // modulo 10,000 buckets (full version in the complete project)
}

public static bool InCanary(string salt, string subject, int canaryBasisPoints) =>
    canaryBasisPoints > 0 && Of(salt, subject) < Math.Min(canaryBasisPoints, Buckets);

The salt keeps the same unlucky users from testing every model you ever ship. The "less than" makes the ramp monotonic, so going from 5% to 25% only adds users. Requests without a user stay on the current model during the canary.

Mistake 7: Fallbacks that hide failures, and gates that can't say "not sure"

When the candidate throws, retry the turn on the current model, so users on the canary get a slower answer instead of an error. Good. But if the retry also hides the failure from your metrics, you've built a slower way to promote a broken model. In the demo, a candidate that failed every third call caused 32 failed turns in 200 requests and zero user-visible failures, and the gates still saw all 32. A hard stop (at least 5 failures at a 20% rate or more) rolled it back immediately.

The second half of this mistake is a gate with only two answers. With small samples, "0 violations in 400 turns" doesn't prove much. The project's rate checks use a Wilson interval and have three outcomes: clearly worse (roll back), clearly fine (pass), or not conclusive yet (hold). At a half-point margin, 400 clean turns still leave the upper bound at 0.95%; you need about 800. At 1% of traffic that can take days, which tells you how short a 1% step is allowed to be.

Not every failed gate should roll back, either. Harm (failures, contract violations, p95 latency, negative feedback) rolls back automatically. A correct but slow candidate at 50% was rolled back on a p95 of 1,971 ms against 575 ms. Cost only holds for a person, because a more expensive model can be the right call.

A pre-flight list for your next model upgrade

[ ] Model id, prompt and options ship together under one fingerprint
[ ] The shadow compares single turns and can't execute tools
[ ] Shadow inputs are deep-copied on the request thread
[ ] Dropped shadow jobs are counted from the drop callback
[ ] Gates use refusals, tool divergence and flips, not raw agreement
[ ] Canary buckets come from a salted stable hash, not GetHashCode()
[ ] Fallbacks protect users but never hide failures from the gates
[ ] Every rate gate can answer "not conclusive yet"

What I tested, and what I didn't

The project has 206 passing tests (193 unit, 13 WebApplicationFactory integration tests), and none needs an API key. An offline support model has switchable bad habits (rounds refunds, refuses legal questions, fails every third call, runs slow), so each scenario above is a test, and a 10-scene CLI demo runs it all on fake time. The library behaviors I mention (the shallow Clone(), the shared message list, TryWrite under DropWrite, randomized string hashes) were checked with spikes against 10.11.0 and .NET 10, and are pinned as tests.

What I didn't do: run a rollout against real providers with real users. The traffic and every number in this post come from simulated days, so your thresholds will need tuning on your own traffic.

Get the complete project

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. This project is already inside: the full .NET 10 solution with releases and the prompt registry, the shadow pipeline that never acts, the response comparer, the sticky canary router with fallback, the Wilson-bounded gates, the rollout controller with its kill switch, the offline models, a minimal API and the 206 tests, plus a PDF guide that goes much deeper than this post, including how to decide when thousands of shadow disagreements are safe enough to promote. You also get the other complete, tested .NET + AI projects in the membership, with new ones added regularly.

Join Tech Skill Builder for $5/month

Which of these seven is hiding in your current upgrade plan?

Review Your LLM Tool Like a Public Endpoint: 8 Questions to Ask Before You Merge an AIFunction in .NET 10

MICHAEL-MAURICE — Fri, 30 Oct 2026 12:54:51 +0000

If a teammate opened a pull request that added a public HTTP endpoint, you'd ask questions. What happens with bad input? What does the caller see on error? Who is the caller, and how do we know? What happens when someone renames a field?

Now look at the last pull request that added an LLM tool. In .NET 10 it's often a method with a [Description] on it and one call to AIFunctionFactory.Create. It probably got approved in two minutes, because there was barely anything to read.

That's the trap. A tool is an endpoint. The caller is a model that writes its own arguments, and it will send you strings where you wanted numbers, parameters that don't exist and times in formats you never mentioned. So here are the eight questions I now ask in review for every tool, based on a room-booking assistant I built on Microsoft.Extensions.AI 10.11.0. The code below is trimmed to the shape. The trimmed parts are marked.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. The complete, working, tested version of this tool-contract project is inside, with full source and an in-depth PDF guide. Join Tech Skill Builder

Question 1: Who chose the tool's name?

If the answer is "the compiler", send it back. AIFunctionFactory.Create on a lambda without a Name gets a generated name like RunAsync_1_0, and that's what the model is shown. The model will call it. It just has no idea what it does.

Method names aren't much better. People rename methods freely, and the tool name is part of the wire contract. In my project the name lives in an attribute, separate from the method:

[Tool("book_room", Effect = ToolEffect.Writes)]
[Description("Book a room for the current user. Use a roomId returned by find_rooms. Fails if the slot was taken meanwhile.")]
public BookingConfirmation BookRoom(
    CallerContext caller,   // bound from the request, not the model (Question 6)
    [Description("Room id from find_rooms, for example R-102."), RegularExpression("^R-[0-9]{3}$")] string roomId,
    // date, start, durationMinutes, attendees: described and bounded the same way (omitted)
    [Description("Short meeting title shown on the room display."), StringLength(80, MinimumLength = 3)] string title)
{
    // full implementation in the complete project
}

Tool is my own attribute, not part of the library. It also records whether the tool writes anything, and that flag ends up in the contract snapshot (Question 8). OpenAI only accepts function names matching ^[a-zA-Z0-9_-]{1,64}$, so check that too.

Question 2: What happens when an argument breaks the schema?

This is the question that surprised me most. The factory reads your DataAnnotations and puts them in the schema: [Range(15, 240)] becomes minimum and maximum, [RegularExpression] becomes pattern. Lovely. Then I called the raw function with durationMinutes: 300, and the method ran. The attributes describe the schema. Nothing checks them when the tool is invoked.

"We use OpenAI strict mode" is not an answer either. Strict mode guarantees the shape (right keys, right types, no extras), but the OpenAI adapter moves keywords like minimum, maximum and pattern into the description text to fit the supported schema subset. Your bound reaches the model as a sentence.

So the review question becomes: where in our code is the schema enforced? In my project, every factory-created function is wrapped in a DelegatingAIFunction that validates against the same schema the model was shown, before anything runs:

public sealed class ContractEnforcingFunction(AIFunction inner, /* validator, options, audit... */)
    : DelegatingAIFunction(inner)
{
    protected override async ValueTask<object?> InvokeCoreAsync(AIFunctionArguments arguments, CancellationToken ct)
    {
        // 1. validate `arguments` against JsonSchema (types, ranges, patterns, formats, unknown keys)
        // 2. on problems: return a structured error and do NOT call the method
        // 3. otherwise: await base.InvokeCoreAsync(...) and wrap the result
        // (full implementation in the complete project)
    }
}

The model still sees exactly the schema the factory generated. The wrapper just makes it true.

Question 3: What happens with an argument that doesn't exist?

With the raw factory function: nothing. Unknown keys are silently ignored. A model that sends duration instead of durationMinutes on a parameter with a default gets the default. A model that sends floor: 3 gets rooms on every floor and never learns there's no floor parameter.

For a public API you'd return a 400 listing the unknown field. Do the same here. My validator rejects unknown arguments and, when there's an obvious near-match, includes a suggestion ("suggestion": "durationMinutes"). Also note that argument names are case-sensitive in the binder, so DurationMinutes is "unknown" too unless you decide otherwise.

Question 4: Which near-misses do we fix, and which do we refuse?

Rejecting everything that isn't perfect costs a round trip, and round trips cost latency and tokens. Accepting everything means guessing. You want a written policy, not whatever the serializer happens to do. Mine is roughly:

"6" for an integer: accept as 6, and tell the model in a note.
"projector" for the enum value Projector: accept with a note. It can only mean one thing.
9:30 for 09:30: accept with a note.
9:30am, "six", integer enum values: refuse and say what format is expected.

The line is ambiguity. "Probably 09:30" is how a meeting ends up at 21:30. The notes go back with the successful result, and in practice the model switches to the canonical form on its next call. There's also a strict policy that refuses every coercion, handy in tests.

Question 5: What does the model read when the tool fails?

Throw an exception from a tool, and with the default IncludeDetailedErrors = false, FunctionInvokingChatClient gives the model exactly this:

Error: Function failed.

That default is right, because exception messages leak internals. But the model now knows nothing about which of its arguments was wrong, so it guesses. Turning detailed errors on mostly tells it how your binder works.

The review question is: are errors results? In my project, validation and business-rule failures come back as a structured envelope the model reads like any other output:

{"ok": false, "error": {"code": "invalid_arguments",
  "message": "2 arguments need fixing; nothing was executed.",
  "retryable": true, "problems": ["...one entry per argument, with path, code and expected..."]}}

"Nothing was executed" is there on purpose. For a write tool, the model needs to know whether retrying will book a second room. Unexpected exceptions still stay in your logs; the model gets an error id, not a stack trace.

Question 6: Can the model decide who the user is?

If the tool has a userId parameter, the answer is yes, and that's a finding. Every argument the model writes is something the prompt can influence.

AIFunctionFactoryOptions.ConfigureParameterBinding lets you take a parameter out of the schema and bind it yourself:

ConfigureParameterBinding = p => p.ParameterType == typeof(CallerContext)
    ? new AIFunctionFactoryOptions.ParameterBindingOptions
      {
          ExcludeFromSchema = true,
          BindParameter = (_, args) => /* read CallerContext from args.Context, or fail closed */,
      }
    : default,

The caller comes from the authenticated request and is copied into AIFunctionArguments.Context by a custom FunctionInvoker. A model that adds "userId": "admin" gets unknown_argument, because the contract doesn't have that parameter. No signed-in user means unauthorized, not a booking that belongs to nobody.

Question 7: How many times is the model allowed to be wrong?

Structured errors bring a new failure mode: a model that reads the error, apologizes and sends the same bad arguments again. FunctionInvokingChatClient has MaximumIterationsPerRequest and MaximumConsecutiveErrorsPerRequest, but a structured error isn't an exception, so the second limit never fires.

So each tool gets an invalid-argument budget per request (two, by default). On the last allowed failure the error says "retryable": false and tells the model to ask the user instead. If it calls the tool anyway, the custom invoker ends the loop:

ficc.FunctionInvoker = async (ctx, ct) =>
{
    // copy the caller into ctx.Arguments.Context (omitted)
    var result = await ctx.Function.InvokeAsync(ctx.Arguments, ct);
    if (/* this request has used up a tool's budget */) ctx.Terminate = true;
    return result;
};

The project's offline test model has a quirk that ignores error hints on purpose, and a test checks that it's stopped after two calls.

Question 8: What does this tool cost, and who notices when it changes?

Tool definitions are prompt text, sent and billed on every request that carries them. Two cheap CI checks answer this:

A linter. Mine has 16 rules: valid names, no compiler-generated names, every tool and parameter described, no untyped object parameters, no pairs of booleans that allow nonsense states, descriptions that aren't essays. On a deliberately sloppy tool class it reports 38 issues. The real tools: zero.
A size budget. The four real tools come to 2,787 characters, about 700 tokens by a chars/4 estimate. The useful number is the change when someone adds a tool with a three-paragraph description.

And then the part most teams skip: the schema is generated from method signatures, so renaming a parameter changes your API and the compiler doesn't care. A snapshot test of every advertised tool catches the change. What it should demand before anyone regenerates the snapshot, when old conversations still contain the old names, is the hard part, and it's a whole chapter of the guide.

The checklist version

Paste this into your PR template:

[ ] Tool name is explicit, stable and matches ^[a-zA-Z0-9_-]{1,64}$
[ ] Ranges, patterns and formats are enforced in our code, not only in the schema
[ ] Unknown arguments are rejected, with a suggestion when there's a near-match
[ ] There's a written coercion policy; anything ambiguous is refused
[ ] Failures come back as structured results that say whether anything executed
[ ] Identity comes from the request, never from a model-written argument
[ ] Each tool has an invalid-call budget, and the loop actually stops
[ ] Lint, size budget and schema snapshot run in CI

What I tested, and what I didn't

The project has 201 passing tests (190 unit, 11 WebApplicationFactory integration tests), and none of them needs an API key. A deterministic stand-in model with switchable bad habits (truncated names, string numbers, lowercase enums, 12-hour times, invented user ids, ignoring hints) makes every recovery path above a test. The library behaviors I describe (unenforced annotations, dropped unknown keys, "Function failed.", lambda names) were checked against Microsoft.Extensions.AI 10.11.0 and are pinned as tests, so a package update that changes one turns the build red.

What I didn't do in the tests: call a real model. You can flip one setting to run the same pipeline against OpenAI, but the numbers in this post come from the offline runs.

Get the complete project

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. This project is already inside: the full .NET 10 solution with the contract wrapper and validator, the coercion policy, caller binding, the retry budget, the linter, size budget and snapshot tools, the offline quirky model, a minimal API and the 201 tests, plus a PDF guide that goes much deeper than this post, including how to rename a tool without breaking the conversations already in flight. You also get the other complete, tested .NET + AI projects in the membership, with new ones added regularly.

Join Tech Skill Builder for $5/month

Which of these eight questions would your newest tool fail?

Stripe Will Send It Again: 7 Deliveries to Replay Against Your .NET Webhook Before Launch

MICHAEL-MAURICE — Thu, 29 Oct 2026 12:02:19 +0000

Most Stripe webhook endpoints get tested exactly once. You run stripe listen, trigger a checkout, see a 200, and move on.

That test proves the easy part. The hard part is everything Stripe promises in its docs: events arrive at least once, in no guaranteed order, and anything that doesn't get a 2xx is retried (in live mode, for up to three days). Your endpoint will meet all of that in production. It's much cheaper to meet it in a test first.

So instead of a build walkthrough, here's a replay list: seven deliveries I throw at a .NET 10 webhook endpoint before I trust it, what should happen for each, and how I check it. The code is trimmed to the shape. The trimmed parts are marked.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. You get complete, working, tested .NET + AI projects with full source code and PDF guides. Join Tech Skill Builder

Need payments and subscriptions in your .NET 10 app? Stripe Integration for .NET 10 is $20 on Gumroad. More about it at the end.

The setup in one picture

POST /webhooks/stripe
  verify Stripe-Signature on the raw bytes   -> bad: 400
  parse the event; type we don't handle      -> 200 "ignored"
  insert into an inbox keyed by event id     -> 200 "queued" or 200 "duplicate"
                                                (database down: 503)
background worker: claim one row with a lease -> run the handler -> done / retry later / dead

The endpoint never runs business logic. It stores and answers. Keep that in mind, because most of the replays below are really testing that split.

Delivery 1: The plain retry

Replay: send the same event twice. Stripe signs every attempt again, so the second copy has a new timestamp and a new signature but the same event id.

Expected: both get 200. The second says duplicate, and the inbox has one row.

Watch the status code. It's tempting to answer a duplicate with 409. Don't: any non-2xx tells Stripe to try again, so you'd get retries of an event you already have.

Delivery 2: Fifty copies at the same moment

Replay: fire the same event 50 times in parallel.

Expected: exactly one queued, 49 duplicate, and one fulfillment.

This is the replay that kills "check if it exists, then insert". Two requests both check, both find nothing, both insert. The fix is to let the database decide, with a primary key on the event id and a single statement:

INSERT INTO webhook_inbox (event_id, type, payload, received_at)
VALUES ($id, $type, $payload, $now)
ON CONFLICT (event_id) DO NOTHING;
-- 1 row affected: first time. 0 rows: duplicate. (full column list in the complete project)

When I removed the primary key and the ON CONFLICT on purpose, four tests failed, including this one. That's how I know the test can actually catch the bug.

Delivery 3: Two different events for the same payment

Replay: two events with different ids that describe the same Checkout Session.

Expected: one fulfillment.

Stripe's docs mention that it sometimes sends two separate Event objects for one change. Your event-id inbox treats them as two events, correctly. So the inbox can't be your only line of defence. The handler also deduplicates on the business key, here the Checkout Session id, with its own unique constraint. There's another reason you need this: if the worker crashes after fulfilling but before marking the row done, the lease expires and the same event runs again.

Delivery 4: "Updated" arrives after "deleted"

Replay: customer.subscription.deleted, then a late customer.subscription.updated with status: "active".

Expected: the subscription stays canceled.

Stripe doesn't guarantee order, and its docs warn against sorting by created (one-second resolution). A naive upsert brings the subscription back to life. My handler never overwrites a terminal state:

-- inside the upsert's DO UPDATE:
WHERE subscriptions.status NOT IN ('canceled', 'incomplete_expired');

There's a second, optional defence: treat the event as a "something changed" signal and re-read the current subscription from Stripe. In my project that's an ISubscriptionSource interface, faked in the tests. I didn't wire it to the real Stripe API.

Delivery 5: A completed checkout that isn't paid

Replay: checkout.session.completed with payment_status: "unpaid", then checkout.session.async_payment_succeeded.

Expected: nothing is fulfilled on the first event; the order ships on the second.

"Completed" means the customer finished the checkout form, not that the money arrived. With delayed methods like bank debits, the payment lands later. The handler checks payment_status (paid or no_payment_required) and returns early otherwise:

if (paymentStatus is not ("paid" or "no_payment_required"))
{
    // log it and wait for checkout.session.async_payment_succeeded
    return;
}
// insert the fulfillment, unique on checkout_session_id (omitted)

Delivery 6: A body that was touched, and a secret mid-roll

Replay A: take a validly signed event, re-format the JSON (same data, different whitespace), and send it.

Expected: 400. The signature covers the exact bytes, so verify the raw body, never something you deserialized and serialized again.

Replay B: sign with the old secret while you're rolling to a new one. Stripe keeps the old secret alive for up to 24 hours and sends one v1 per active secret.

Expected: 200. My verifier tries every v1 entry against every configured secret, which is why I wrote it myself instead of using Stripe.net's EventUtility.ConstructEvent (that takes one secret). The tests use Stripe.net as an oracle: seven headers, including stale, future, wrong-secret and "bad v1 before a good one", go through both Stripe.net's check and mine, and they agree on all seven.

foreach (var secret in options.Value.SigningSecrets)
{
    // HMAC-SHA256 over "{t}." + raw body, keyed with the UTF-8 bytes of the whole whsec_ string
    // compare to every v1 with CryptographicOperations.FixedTimeEquals (full verifier omitted)
}
// then: |now - t| must be within 300 seconds, in both directions

Delivery 7: Your side is broken

Replay A: the inbox write throws (database down).

Expected: 503. This is the one case where you want Stripe to retry, because the next attempt can succeed.

Replay B: the event is stored fine, but the handler throws (say, the ERP times out).

Expected: Stripe already got its 200. The worker retries, with backoff (10 s, doubling, capped at an hour), and after 8 attempts parks the row as dead for a human. Stripe never hears about your ERP.

The status code table

Situation	Answer	Will Stripe retry?
Stored for the first time	200 `queued`	no
Already stored	200 `duplicate`	no
A type you don't handle	200 `ignored`	no
Bad, missing or stale signature; not an event	400	yes (fine: fix the secret and the retries recover)
Body over your size limit	413	yes
Inbox write failed	503	yes, on purpose

The rule behind it: choose each code by asking "would a retry help?"

What I tested, and what I didn't

The demo project has 52 passing xUnit tests, covering every replay above, plus a smoke run against the real host and worker. Every signature was made locally, with Stripe.net's helper and with Python's hmac.

What I didn't verify: a real Stripe account or the Stripe CLI, Stripe's real retry timing, a real ISubscriptionSource, or several app instances on one database. The inbox is SQLite, so it's single-host. For more instances, move the same unique key and claim query to Postgres or SQL Server.

Want the full Stripe integration?

Stripe Integration for .NET 10 is $20, one-time, from Elite Solutions. It's a Clean Architecture + DDD solution (Domain, Application, Infrastructure, Api) with CQRS and MediatR, EF Core and Swagger, with Stripe.net wrapped in a StripeService. It covers customers, products and prices, Payment Intents, Checkout Sessions, refunds, subscriptions, invoices and webhooks with signature verification and deduplication by Stripe event ID, plus unit tests. To be clear: the replay demo from this post (the SQLite inbox, the worker and the 52 tests) is a separate project and is not part of the kit.

And if you learn best from complete code you can run, Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. You get complete, working, tested .NET + AI projects with full source code and step-by-step PDF guides, and new ones are added regularly.

Join Tech Skill Builder for $5/month

Which of these seven would your endpoint fail today?

Half Price Until You Pay Twice: 6 Ways an OpenAI Batch Job in .NET Quietly Costs You More

MICHAEL-MAURICE — Thu, 29 Oct 2026 12:01:25 +0000

The pitch for the OpenAI Batch API is simple. You have a pile of work nobody needs answered in two seconds, say 40,000 rows to classify overnight. You put the requests in a JSONL file, upload it, and the provider finishes within 24 hours at half the price of the normal API.

The discount is real. What eats it is the code around the batch. A batch job lives for hours, and anything that lives for hours meets crashes, retries and deadlines. Each of those can quietly turn "half price" into "full price, twice", or into results that are silently missing.

Here are six mistakes I made or nearly made while building a batch pipeline in .NET 10 (official OpenAI 2.14.0 package, SQLite for state). The steps are general. The code is trimmed to the shape, and the trimmed parts are marked.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. The complete, working, tested version of this batch project is inside, with full source and an in-depth PDF guide. Join Tech Skill Builder

Mistake 1: Creating the batch again after a crash

This is the expensive one. Your worker uploads the file, calls "create batch", and dies before it saves the batch id. On restart, your database says this shard was never sent, so you send it again. Now two batches run the same requests, and you pay for both.

The fix doesn't need extra infrastructure. Batches accept metadata, so tag each one with your own shard id when you create it. On restart, before re-sending a shard that has no batch id, list the recent batches and look for that tag:

var metadata = new Dictionary<string, string>
{
    ["job_id"] = job.Id,
    ["shard_id"] = shard.Id,
};
// create the batch with this metadata, then save the batch id (full flow in the complete project)

// on restart, for a shard with no saved batch id:
var match = recent.FirstOrDefault(b =>
    b.Metadata.TryGetValue("shard_id", out var sid) && sid == shard.Id);
// match found: adopt it. none found: send it. Never both.

The other half of the rule: save your state before every provider call (planned, then uploaded, then created), so a restart always knows how far it got.

Mistake 2: Retrying everything that failed

A batch comes back with failures, and the easy move is "put the failures in the next batch". Some of those failures will fail again no matter how often you send them. A 400 for a malformed request or a model refusal gets the same answer the second time, and you pay for it again.

So sort the failures before you retry anything:

Retry: 408, 409, 429 and 5xx, batch_expired, lines that never came back, and output that parsed but broke your schema.
Retry with more room: finish_reason: length. The next attempt doubles max_completion_tokens, up to a cap.
Don't retry: other 4xx, refusals and content-filter stops.

And give every item an attempt budget (three in my project). When it runs out, the item goes to a dead-letter state with its last reason instead of looping forever.

One more thing on cost: when an attempt is truncated, you still paid for its tokens. My store adds each attempt's tokens to the item rather than replacing them, so the cost report shows what you actually paid.

Mistake 3: Looping over the output file

The docs say it plainly: output lines may not come back in input order. That part most people catch, and they join on custom_id. The subtler bug is which side you loop over.

If you loop over the output file, items with no line at all simply never show up. Cancelled batches, expired batches and the occasional lost line all look like that. The job reports "done" and a few hundred rows were never processed.

Loop over what you sent instead, and look each one up:

foreach (var (itemId, attempt) in shard.Members)
{
    if (decisions.ContainsKey(itemId)) continue;   // a line came back for it
    // no line at all: retry, with a reason like "missing_after_cancel" or "missing_after_expiry"
    // ... (reason mapping and the rest of the reconciler are in the complete project)
}

Also read the second file. Failed requests go to a separate error file, and that's where expired requests show up.

Mistake 4: Reusing the same custom_id on a retry

Item r-042 fails in batch one and goes into batch two. If its custom_id is still r-042, a late line from batch one is indistinguishable from the fresh answer, and it can overwrite a newer result.

Put the attempt number in the id. My format is {jobId}:{itemId}:a{attempt}, so the retry is ...:r-042:a2. Any line carrying a1 after that is stale, and the reconciler ignores it. Lines from another job are ignored the same way, and a second line for the same id counts as a duplicate.

The database side gets the same treatment: an update only lands if the item is still at that attempt and still waiting for a result, so a late line can't overwrite newer state.

Mistake 5: Letting the JSON encoder inflate your file

Each input file has limits: 50,000 requests and 200 MB. The default System.Text.Json encoder escapes every non-ASCII character as \uXXXX. For English text, that changes nothing. For Arabic it hurts. In my measurement, one short Arabic ticket went from 116 bytes to 324.

On long non-English rows, the byte limit starts to bind before the 50,000-request limit, so the same job needs more files and more batches. One option fixes it:

var options = new JsonWriterOptions { Encoder = JavaScriptEncoder.UnsafeRelaxedJsonEscaping };
// write custom_id, method, url, body with a Utf8JsonWriter using these options (builder omitted)

Despite the scary name, it still escapes control characters, so a newline inside a row can't split a JSONL line. I have a test for exactly that, because it's the first thing I'd worry about.

While you're there, validate the file locally before uploading: unique custom_ids, one model per file, url equal to the batch endpoint, no stream: true, and within the limits. A mistake caught locally costs nothing.

Mistake 6: Panicking at the deadline

The Batch API promises 24 hours. Your report is due at 08:00. At 07:40 the batch is still running and half the rows are done.

The panic move is "cancel it and run everything through the normal API". That pays full price for the rows the batch already finished, and a cancelled batch still produces output for what it completed, which you're billed for too.

The better question is when to stop trusting the batch, and how to finish only what's left without paying twice. My project answers that with a deadline planner. How it decides, and what it costs, is in the complete project and its PDF guide, not here.

The pre-flight checklist

[ ] State saved before every provider call
[ ] Every batch tagged with your shard id; crash recovery adopts before it re-sends
[ ] Failures classified: retry, retry with more tokens, or fail for good
[ ] Attempt budget and a dead-letter state
[ ] Tokens added across attempts, not replaced
[ ] Reconcile over what you sent, using both the output file and the error file
[ ] Attempt number inside custom_id; stale and foreign lines ignored
[ ] Relaxed JSON encoder, and a local file validator
[ ] A deadline plan that doesn't throw away finished work

What I tested, and what I didn't

The project has 162 passing tests (146 unit, 16 integration), with no API key needed. An offline simulator covers the documented batch lifecycle, including failed, expired and cancelled batches, and a test crashes the process right after "create batch" to prove recovery adopts the existing batch instead of creating a second one.

What I didn't do: run it against the live Batch API. The OpenAI adapter was tested against an in-process server that speaks the documented Files and Batches format, not against OpenAI itself. Also note that BatchClient is marked experimental (OPENAI001) in the 2.14.0 SDK, so expect it to change.

Get the complete project

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. This batch project is already inside: the full .NET 10 solution with the 162 tests, the crash recovery, the reconciler, the deadline planner, a minimal API with idempotent job creation, and a PDF guide that goes much deeper than this post. You also get the other complete, tested .NET + AI projects in the membership, with new ones added regularly.

Join Tech Skill Builder for $5/month

Which of these six would hit your batch job first?

Your Telegram AI Assistant Can Email Anyone as You: 6 Checks to Run Before the Model Does

MICHAEL-MAURICE — Wed, 28 Oct 2026 17:46:36 +0000

Picture the assistant: you hold the mic in Telegram, say "find 30 minutes with Sara on Thursday and email her the options", and a minute later the email is in her inbox. n8n makes that easy. A Telegram Trigger, a Whisper transcription, an AI Agent with Gmail and Calendar tools, and you're most of the way there.

Notice what you just built, though: a bot that can send email as you, triggered by anyone who can reach a webhook. The model is the least interesting risk here. The interesting ones happen before the model runs.

I built this with n8n plus a small ASP.NET Core API (.NET 10) that makes the decisions I don't want a model to make. The general steps below are the ones that matter. Code is trimmed to the shape.

Tech Skill Builder is $5/month for a very limited time (normally $10) — grab it now before it goes back to $10. Complete, tested .NET + AI projects with full source and PDF guides. 👉 Join Tech Skill Builder

The shape

Telegram Trigger -> guard API (allowed?) -> voice or text?
   voice -> download -> Whisper -> prompt
   text  ----------------------> prompt
prompt -> AI Agent (tools: contacts, calendar, free slots, email) -> reply on Telegram

The first node after the trigger asks the API one question: may this update run at all? Everything that costs money or has side effects sits behind the answer. Here are six checks, in roughly the order a message meets them. The first four live in that guard; the last two protect the tools the agent calls.

Check 1: Is this chat one of mine?

The Telegram Trigger already checks the secret token, and in my local run the webhook was registered with it. That proves the request came from Telegram. It does not prove you wrote the message. Anyone on Telegram can message your bot.

So: an allowlist of chat IDs, and everyone else is ignored without a reply. A reply tells a stranger the bot exists and is listening.

Check 2: Have I seen this update before?

Telegram retries a delivery when it doesn't get a fast 2xx (a restart, a slow node, a proxy hiccup). A retried "email Sara the report" is two emails.

Remember each update_id for a window and let only the first one through. Two retries can land at the same moment, so a "check, then add" pair isn't enough. It needs one atomic operation:

// one atomic step, not "if (!seen.Contains(id)) seen.Add(id)"
if (!_seen.TryAdd(updateId, now))
{
    // already there: duplicate inside the window, or expired and re-added (omitted)
}

The test I trust here fires the same update many times in parallel and expects exactly one to pass.

Check 3: Is it stale?

After an hour of downtime you don't want ten queued commands to fire at once. n8n's trigger can drop pending updates when you re-publish (in my local run it registered the webhook with drop_pending_updates), but I still compare the message date with the clock and refuse anything older than ten minutes (a setting).

Check 4: How big is this voice note?

A 20-minute voice note isn't a command, it's a transcription bill. Read the duration from the update and refuse before downloading anything. In my setup the limit is 120 seconds, and the bot answers "please keep it under 2 minutes".

public GuardDecision Evaluate(TelegramUpdate update)
{
    // ... bot check, allowlist, duplicate, age (the checks above, in this order)
    if (m.Voice is { } voice && voice.Duration > o.MaxVoiceSeconds)
        return new(false, "voice_too_long", m.Chat.Id);
    // ... allowed: return kind, text or voice file id
}

The order matters: cheap checks first, anything that costs money last.

Check 5: Which "Omar"?

Ask a model to email Omar and it may produce omar@company.com with total confidence. Make the contact lookup a tool, and make its answer one of three: found, ambiguous, not_found. The system prompt then says: never guess an address; on anything but found, ask which person and stop.

In my run, a voice note saying "book 30 minutes with Omar" ended with the bot asking which of the two Omars I meant, and nothing was sent.

Check 6: What time did the model mean?

Models send "2026-10-29T10:00:00", no offset. Deserialize that into a DateTimeOffset and you get the server's offset. I checked: on a box with TZ=UTC it parsed as 10:00+00:00, three hours off for an assistant living in Cairo.

So the API takes the time as a string, and treats an offset-less value as the assistant's own zone:

local = DateTime.SpecifyKind(local, DateTimeKind.Unspecified);
// handle a time that doesn't exist (spring-forward gap): omitted
var utc = TimeZoneInfo.ConvertTimeToUtc(local, zone);

The same goes for working hours: convert them to UTC per day, not once from the first day's offset. A clock change between two days is where the shortcut breaks. When I swapped the per-day conversion for the shortcut, exactly two tests failed, which is how I know the tests cover it.

What I checked, and what I didn't

The API has 43 passing xUnit tests. I also ran the whole n8n workflow locally (n8n 2.43.8) against the real API, with a fake Telegram, OpenAI and Google. It covered a text request, a Telegram retry (ignored), a voice note about an ambiguous contact, a voice note that was too long, a stranger's chat (ignored) and a missing or wrong secret token (HTTP 403).

What I didn't check: real Telegram, real Whisper, real Gmail and Calendar (no credentials, so those nodes were only validated against n8n's node schemas), and how well a real model picks tools. The dedup store is in memory, so with more than one instance you'd move it to Redis or a database key.

The checklist

[ ] Allowlist of chat IDs; strangers get silence
[ ] Atomic dedup on update_id
[ ] Stale messages refused
[ ] Voice duration capped before download
[ ] Contact lookup is a tool with found / ambiguous / not_found
[ ] Offset-less times get your zone, not the server's
[ ] Cheap checks first, paid steps last

Want to skip the n8n part?

If you'd rather start from a finished Telegram assistant than wire the nodes yourself, the n8n Workflow Vault is $29 one-time: the AI Phone-Calling Personal Assistant for Telegram (voice and text, Whisper, Google Sheets contacts, phone, email and calendar agents), the Ultimate n8n Workflow Pack with 2,000+ templates, the multi-agent orchestration workflow and the UGC ad video generator. You bring your own API keys. The guard API from this post is a separate demo and is not part of the Vault.

And if you learn best from complete code you can run, Tech Skill Builder is $5/month for a very limited time (normally $10) — grab it now before it goes back to $10. You get complete, working, tested .NET + AI projects with full source code and step-by-step PDF guides, and new ones are added regularly. 👉 Join Tech Skill Builder

Which of these six would your bot fail first?

Deleted, Emptied, Half-Written: 6 Files a Nightly RAG Ingestion Job Gets Wrong in .NET 10

MICHAEL-MAURICE — Tue, 27 Oct 2026 11:59:48 +0000

Most RAG ingestion demos end after the first run: a folder of Markdown goes in, the chat answers a question, done. But a knowledge base changes all the time. Pages get deleted, trimmed, moved and rewritten, and an ingestion job that runs every night has to keep the vector index in step with all of that.

I built a small help-center ingestion service on .NET 10 with Microsoft.Extensions.DataIngestion (10.11.0-preview.1.26513.7, still a preview package) and the in-memory vector store. The pipeline itself (read, chunk, enrich, embed, write) was the quick part. Most of my time went into six ordinary things that can happen to a file. For each one there's a simple question: what should the index hold the next morning?

Code below is trimmed to the shape; omitted parts are marked.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. The complete ingestion service from this post, with an in-depth PDF guide, is inside Tech Skill Builder.

The one idea behind all six

Don't treat ingestion as "process this folder". Treat it as a sync between two things: the files on disk, and a ledger that records what the index is supposed to hold for each document (content hash, generation number, chunk count, status). Every run compares the two and decides one action per document:

public enum PlannedAction
{
    Add, Update, Reindex, Repair, Retry, Skip, Quarantined, Delete,
}
// IngestionPlanner.Plan(sources, ledger, fingerprint, liveChunkCounts): a pure function,
// full implementation in the complete project

Because the planner does no I/O, every branch below has a plain unit test.

File 1: the page you deleted

Somebody removes welcome.md. The pipeline only processes files that exist, so it never hears about this one. Its chunks stay in the index, and the assistant keeps quoting a page that's gone.

Rule: anything in the ledger but no longer on disk is a Delete. The job first stops serving it, then deletes its chunks and the ledger row. In the demo that run makes zero model calls and zero embedding calls, and removes the page's one chunk.

Test: Deleted_file_loses_its_chunks_and_ledger_row.

File 2: the page cut down to its title

Someone trims invoices.md to a single heading. It now produces zero chunks.

This one surprised me. The library's writer has an incremental mode (IncrementalIngestion, on by default) that replaces a document's old chunks, but it does that when the first new chunk arrives. With no new chunks, nothing triggers it, and the old three chunks stay searchable. A characterization test in the project pins that behaviour: Builtin_incremental_mode_keeps_old_chunks_when_the_new_version_is_empty.

Rule: I turn the built-in mode off and replace by generation myself. A successful run with zero chunks still deletes the old generation, and the document is marked Empty instead of quietly serving its previous version.

Test: Emptied_file_loses_its_chunks.

File 3: the page that didn't change, in a folder that moved

Same files, new deploy path. By default the reader uses FileInfo.FullName as the document id, so /srv/release-41/billing/refunds.md and /srv/release-42/billing/refunds.md are two different documents, and the index ends up with two copies of everything.

Rule: the id is the path relative to the source root, with forward slashes (billing/refunds.md). A small reader decorator makes sure the pipeline uses that id too:

public sealed class StableIdReader(IngestionDocumentReader inner, string root) : IngestionDocumentReader
{
    // both ReadAsync overrides map FileInfo.FullName to the root-relative id
    // full implementation in the complete project
}

While you're there, hash the content after normalizing line endings and stripping a BOM. Otherwise a Windows build agent with core.autocrlf makes every file look edited.

Test: Moving_the_source_folder_does_not_duplicate_anything (second run: 6 of 6 unchanged, same chunk count).

File 4: the page that grew too big

Someone pastes a huge log into a page and it goes over the size limit (2,000,000 bytes by default in my settings). A scanner that just leaves it out of its list has a nasty side effect: next to the ledger, a missing file looks exactly like a deleted one.

Rule: oversized files are reported as skipped, and the job refuses to delete them from the index. The index keeps serving the last good version until someone fixes the file.

Test: Too_large_file_is_skipped_but_not_deleted.

File 5: the page whose embedding call died halfway

close-account.md changes, and the embedding provider returns a 503 after two chunks of the new version are already written. Now the index holds half of the new version next to the complete old one.

Rule: every write is a new generation (a small chunk processor stamps the generation number on each chunk). The commit order is: save the ledger, publish the new generation, then delete the old ones. On failure, delete whatever part of the new generation landed and leave the ledger pointing at the old one:

if (!result.Succeeded)
{
    var partial = await _index.DeleteAsync(id, g => g == generation, ct);
    // record the failure (hash, count, error) in the ledger: in the complete project
}

The demo's run report says it in one line: removed 2 partial chunk(s); previous version still served.

Test: Mid_write_failure_removes_partial_chunks_and_keeps_serving_the_old_version.

File 6: the page that fails every single night

If the failure is in the content itself (or the provider keeps rejecting it), a naive job retries every night forever, paying for enrichment calls each time.

Rule: count failures per content hash. After 3 failures of the same content (MaxAttempts), the document is Quarantined and skipped with zero model calls. Any edit to the file releases it, and reverting the file to the version that's still live clears the failure.

Tests: Repeated_failures_quarantine_until_the_file_changes, Editing_a_quarantined_file_releases_it.

The cheap part: nothing changed

All six rules rely on the planner, and the planner gives you the best one for free. In the offline demo, the first run over six files made 18 model calls and embedded 17 texts. The second run, with no changes, made 0 model calls and embedded 0 texts, in 4 ms. Unchanged files never reach the pipeline.

Checklist

[ ] Ids relative to the source root, never absolute paths
[ ] Content hashes that ignore line endings and a BOM
[ ] Deleted files are purged, with a test
[ ] Emptied files are purged, with a test (the built-in incremental mode won't do it)
[ ] Oversized files are skipped and reported, never treated as deleted
[ ] A failed write removes its partial chunks and keeps the old version live
[ ] Repeated failures of the same content are quarantined
[ ] Unchanged files cost zero model calls

There's one problem I haven't covered here: while a document is being replaced, a search can briefly see chunks from two versions. How search avoids that, with one live generation per document, is covered in the project and the PDF.

Get the complete project

The snippets above are the outline. The complete .NET 10 solution, Production RAG Ingestion for .NET 10, is in Tech Skill Builder: the scanner and pure planner, generation-based commits, quarantine, store-loss repair, an orphan sweep after crashes, redaction before chunking, an enrichment contract on top of the library's best-effort enrichers, live-generation search, an ASP.NET Core minimal API and a 15-scene CLI demo. It has 131 offline tests (118 unit, 13 integration), including 10 characterization tests that pin the preview library's behaviour, plus an in-depth PDF guide. No API key needed to run it.

Tech Skill Builder gives you complete, working, tested .NET projects with full source code and step-by-step PDF guides, with new ones added regularly. Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. Join Tech Skill Builder

Which of these six has your ingestion job already got wrong?

One Clarifying Question, One Line of C#: 5 Interview Bugs I Planted on Purpose

MICHAEL-MAURICE — Tue, 27 Oct 2026 11:58:54 +0000

Most advice about coding interviews says "ask clarifying questions". It rarely says why the interviewer cares. My answer: every good clarifying question ends up as one specific line of code. If you can point at that line while you talk, you've shown you write code from requirements, not from memory.

To check that idea, I took a small practice project (four classic problems in C# on .NET 10, each with a brute force and an optimized version, 34 xUnit v3 tests) and broke one line at a time. Each line is the answer to a question you should ask out loud. Then I counted how many tests failed.

Four of the five bugs were caught. One got through all 34 tests, and that one taught me the most.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. Complete, working, tested .NET projects with full source code and step-by-step PDF guides: Tech Skill Builder.

If you're preparing for .NET backend interviews in general, my .NET Backend Interview Masterclass (2026 Edition) goes much wider than algorithms. More on it at the end.

How the experiment works

Every problem has one extra test besides the hand-picked cases: run the brute force and the optimized version on 500 random small inputs with a fixed seed, and require the same answer. The brute force is slow, but it's easy to trust, so it works as the reference for the fast one.

For each bug below I changed one line, ran dotnet test, wrote down what failed, and reverted the change.

Bug 1: "Can I use the same element twice?"

Two Sum, the hash map version. The answer "no" is enforced by the order of two lines: look up the complement first, insert the current value second.

for (var j = 0; j < nums.Count; j++)
{
    long complement = (long)target - nums[j];
    if (seen.TryGetValue(complement, out var i)) return (i, j); // 1. look up
    seen.TryAdd(nums[j], j);                                    // 2. then insert
}
// null check, doc comment and brute force: in the complete project

What I broke: I moved the insert above the lookup.

What noticed: 3 tests. [3] with target 6 now "finds" a pair (index 0 with itself), [3, 3] returns (0, 0) instead of two different indices, and the random comparison failed too.

Say it out loud: "I check before I insert, so an element can't pair with itself."

Bug 2: "How big can the numbers get?" (the one that got through)

The same method does its math in long, because int.MaxValue + 1 silently wraps around in an int. The project even has a test row for it: [int.MaxValue, 1, int.MinValue] with target -1.

What I broke: I switched both the brute force and the optimized version to plain int arithmetic.

What noticed: nothing. 34 of 34 passed.

The reason is a little embarrassing. In that test row, the correct pair (int.MaxValue + int.MinValue = -1) doesn't overflow at all, so int math still finds it. The row looks like overflow coverage, but it can't fail. And the random test couldn't help: it uses small values, and I had broken both versions in the same way, so they still agreed.

The case that does catch it is one where wrapping creates a false match:

{ [int.MaxValue, 1], int.MinValue, false }, // int math: MaxValue + 1 wraps to MinValue

I added that row in a scratch copy, and the int version failed it straight away (the real long version passes). It isn't in the project yet.

Say it out loud: "If the values can be near int.MaxValue, I'll add in long. And my test for that needs a case where wrapping would produce a wrong yes, not just one where it happens to work."

Bug 3: "What if the repeat is already outside my window?"

Longest substring without repeating characters, sliding window version. This one isn't a question for the interviewer. It's a question you ask yourself while you trace an example.

if (lastIndex.TryGetValue(s[right], out var previous))
    left = Math.Max(left, previous + 1); // the left edge never moves backwards
// rest of the loop (update lastIndex, track best): in the complete project

What I broke: left = previous + 1; without the Math.Max.

What noticed: 2 tests: the "abba" row (the broken version returns 3, the right answer is 2) and the random comparison.

Say it out loud: "Let me trace abba. At the last a, the previous a is at index 0, which is already outside the window, so left must stay where it is."

Bug 4: "Must the subarray be non-empty?"

Maximum subarray (Kadane). If the answer is "yes, take at least one element", then an all-negative array returns its largest single value, not 0. That decision lives in the seed:

long endingHere = nums[0], best = nums[0]; // not 0
// the loop and the empty-input guard: in the complete project

What I broke: seeded both with 0.

What noticed: 2 tests: [-3, -1, -2] (expected -1) and the random comparison.

Say it out loud: "You said non-empty, so I seed with the first element. Otherwise an all-negative input would return 0, which isn't the sum of any subarray."

Bug 5: "If one meeting ends at 10 and the next starts at 10, can they share a room?"

Meeting rooms, sort-and-sweep version. If the end time is exclusive, a room is freed when the next start is at or after the earliest end. That's one character:

while (e < ends.Length && ends[e] <= start) { e++; rooms--; }
// sorting starts and ends, and counting rooms: in the complete project

What I broke: <= to <.

What noticed: 2 tests: back-to-back meetings 9-10, 10-11, 11-12 (expected 1 room) and the random comparison.

Say it out loud: "That <= is your answer from earlier. Back-to-back meetings can share a room."

What the scoreboard says

Bug	Clarifying question	Tests that failed
Insert before lookup	Same element twice?	3
`int` instead of `long`	How big are the values?	0
No `Math.Max` on `left`	Repeat outside the window?	2
Kadane seeded with 0	Non-empty subarray?	2
`<` instead of `<=`	Exclusive end time?	2

Two things I took from it:

The random brute-force comparison was in every catch. It failed on its own for all four bugs that were caught. In an interview you won't have time to write it, but one sentence earns credit: "With more time, I'd check this against the brute force on random small inputs."
A test named after an edge case isn't proof that the edge case is covered. The overflow row looked right and couldn't fail. Breaking the line on purpose is the quickest way to find out.

Your practice checklist

[ ] Ask the question, then write the answer as a comment or a test case
[ ] Point at the line that implements each answer
[ ] Trace one awkward input by hand (abba, all negative, back-to-back)
[ ] For overflow, test a case where wrapping gives a false yes
[ ] Mention the brute-force cross-check, even if you can't write it

Want to go further?

The .NET Backend Interview Masterclass (2026 Edition) is a 142-page guide ($20) with 200+ C# questions with full code, a system design playbook with 7 high-frequency scenarios (webhooks, payments, feed pagination and more) and a 6-box thinking script, EF Core and SQL performance, the ASP.NET Core runtime, security and reliability, a 14-day prep plan, a STAR+L behavioral bank and 8 printable cheat sheets. To be upfront: the small kata project from this post is my own and isn't part of the guide.

And if you learn best from complete code you can run, Tech Skill Builder gives you complete, working, tested .NET projects with full source code and step-by-step PDF guides, with new ones added regularly. Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. Join Tech Skill Builder

Which clarifying question has saved you in a real interview?

Your First AI Feature in .NET 10 in 15 Minutes

MICHAEL-MAURICE — Tue, 27 Oct 2026 09:56:12 +0000

You don't need a vector database, an agent framework or a weekend to ship your first AI feature in .NET. You need one interface, IChatClient, and about fifteen minutes.

In this post we'll build a small but real feature: a support ticket triage endpoint. You POST a customer email, and you get back a category, a priority and a one-line summary as a typed C# object. Then we'll stream a reply draft and make the model swappable with one line.

📄 Want the full version of every snippet here? Grab the free .NET AI Starter Cheat Sheet. Enter your email and get it free: 8 pages of copy-paste C# covering the whole .NET AI stack, tool calling, structured output, RAG, MCP and a production checklist.

🔥 Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. Complete, tested .NET + AI projects with full source and step-by-step PDF guides: Join Tech Skill Builder

The plan (and the clock)

Minutes	Step
0 to 2	Create the project and add two packages
2 to 5	Register `IChatClient` once, in DI
5 to 9	Typed triage with structured output
9 to 12	Stream a reply draft
12 to 15	Guardrails, and swapping the model

The code below shows the shape of each step. Some parts are trimmed and marked as such.

Minute 0 to 2: project and packages

dotnet new webapi -n TicketTriage --use-minimal-apis
cd TicketTriage
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.AI.OpenAI
dotnet user-secrets init
dotnet user-secrets set "OpenAI:Key" "<your-key>"

Microsoft.Extensions.AI gives you the abstractions (IChatClient, ChatMessage, ChatOptions) and the middleware. Microsoft.Extensions.AI.OpenAI is the adapter that turns the OpenAI SDK client into an IChatClient. Your app code will only ever see the interface.

Keep the key in user secrets (or environment variables in production). Never in appsettings.json, and never in Git.

Minute 2 to 5: one registration, used everywhere

The mistake I see most often in first AI features is new OpenAIClient(...) inside a controller. Register the client once and inject the interface instead:

using Microsoft.Extensions.AI;
using OpenAI;

builder.Services
    .AddChatClient(sp => new OpenAIClient(builder.Configuration["OpenAI:Key"])
        .GetChatClient("gpt-4o-mini")
        .AsIChatClient())
    .UseLogging();
    // more middleware (telemetry, caching, tool calls): see the cheat sheet

That builder is a pipeline. Every call goes through the middleware you add, in order, before it reaches the model. Logging is enough for today.

Minute 5 to 9: typed triage, not string parsing

Here's the part that makes it feel like a real feature. Don't ask the model for "JSON please" and then fight JsonSerializer. Ask for a C# type:

public enum Priority { Low, Normal, High, Urgent }

public record Triage(string Category, Priority Priority, string Summary);
public record TicketRequest(string Body);

app.MapPost("/tickets/triage", async (IChatClient ai, TicketRequest req) =>
{
    ChatResponse<Triage> res = await ai.GetResponseAsync<Triage>(
    [
        new(ChatRole.System, "You triage support emails for an online shop. ..."),
        new(ChatRole.User, req.Body)
    ]);

    // ... validate res.Result before trusting it (step 5)
    return Results.Ok(res.Result);
});

GetResponseAsync<T> generates a JSON schema from your record, sends it with the request and deserializes the answer into Triage. Using an enum for Priority means the model can't invent a "Kinda urgent" level.

The system prompt matters more than the code here. Mine lists the allowed categories and says what counts as urgent. I've cut it short above because the wording is where most of the tuning goes.

Minute 9 to 12: stream the reply draft

A triage result is small, so waiting for it is fine. A reply draft is longer, and a spinner for six seconds feels broken. Stream it:

app.MapPost("/tickets/draft", (IChatClient ai, TicketRequest req) =>
    StreamDraft(ai, req));

static async IAsyncEnumerable<string> StreamDraft(IChatClient ai, TicketRequest req)
{
    await foreach (var update in ai.GetStreamingResponseAsync(/* system + user messages */))
        yield return update.Text;
}

Returning IAsyncEnumerable<string> from a minimal API endpoint sends the chunks as they arrive. The front end shows the text as the model writes it. Cancellation, retries and Server-Sent Events are the next layer up, and you can skip them for a first version.

Minute 12 to 15: guardrails and the one-line swap

Three things I'd add before anyone else uses this:

Cap the cost. Pass new ChatOptions { MaxOutputTokens = 300, Temperature = 0.1f } for triage. Low temperature for classification, a little higher for drafts.
Don't trust the result blindly. If Summary is empty or the category isn't in your list, fall back to "Needs a human". The model will be wrong sometimes, and your code should expect that.
Cap the input. Truncate the email body before sending it. A 40-page pasted log shouldn't cost you a dollar.

And the payoff for coding against the interface: switching to a local model for development is one registration change.

// dev: a local model through Ollama (OllamaSharp implements IChatClient)
builder.Services.AddChatClient(new OllamaApiClient(new Uri("http://localhost:11434"), "llama3.2"));

Your endpoints, prompts and records don't change at all.

What we skipped on purpose

To keep it to fifteen minutes I left out tool calling (letting the model look up the customer's order), RAG (answering from your own help-center docs), telemetry and evals. Those are the steps that turn a demo into something you'd put in front of customers, and each one has a few traps.

Get the full version, free

Every snippet in this post, completed, plus tool calling, RAG in six steps, an MCP server in C# and a production checklist, is in the free .NET AI Starter Cheat Sheet. Enter your email and get it free. 📄

When you're ready for complete projects instead of snippets, Tech Skill Builder gives you working, tested .NET + AI solutions with full source and step-by-step PDF guides. Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. Join Tech Skill Builder

What was the first AI feature you shipped in .NET, or the one you're planning? Tell me in the comments.

Parameterized Queries Can't Help Here: 6 SQLite Traps When an LLM Writes Your SQL

MICHAEL-MAURICE — Mon, 26 Oct 2026 12:02:16 +0000

The standard answer to SQL injection is "use parameterized queries". It's good advice, and it doesn't help at all once a language model writes the entire statement. There's no user value to bind. The query itself is the untrusted input.

I spent a week building the guard for an "ask your shop data" assistant on .NET 10 with SQLite. The big design decision came early: don't parse SQL in C#. SQLite already has a full parser for its own dialect, so the guard compiles each statement and asks the engine what it would do. The surprises came later, in the details. Here are six SQLite and Microsoft.Data.Sqlite behaviours that would each have let something through.

The project uses Microsoft.Data.Sqlite 10.0.13 (SQLite 3.53 via SQLitePCLRaw) and Microsoft.Extensions.AI 10.11.0 for the structured model output. Code below is trimmed to the shape; omitted parts are marked.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. The complete text-to-SQL guard from this post, with a step-by-step PDF, is inside Tech Skill Builder.

Trap 1: you read one row, and the DELETE still runs

I ran SELECT id FROM orders LIMIT 1; DELETE FROM orders through a plain SqliteCommand, read a single row, and let the using block dispose the reader. Afterwards the table had zero rows.

That's documented behaviour: Microsoft.Data.Sqlite supports batches, and disposing the reader executes any statements that haven't been consumed yet. So a guard that only looks at the first statement passes, and the second one runs anyway.

The fix is to compile the statement yourself with sqlite3_prepare_v2 and then compile the tail. If the tail produces a real statement handle, refuse:

var rc = raw.sqlite3_prepare_v2(db, sql, out sqlite3_stmt stmt, out string tail);
using (stmt)
{
    if (rc != raw.SQLITE_OK) { /* a SQL error, not a violation: eligible for repair */ }
    if (HasAnotherStatement(db, tail)) { /* refuse: multiple_statements */ }
    // read-only, EXPLAIN, bound parameters and result-column checks: in the complete project
}

Don't settle for "the tail isn't empty", by the way. Models love ending with ; -- done, and a comment-only tail compiles to an empty handle, which is fine.

Trap 2: "read-only" is narrower than it sounds

sqlite3_stmt_readonly looks like the perfect check. But per the SQLite docs, it reports true for BEGIN, ATTACH and DETACH, because they don't write to the database file. That's correct from SQLite's point of view, and it's not what you want for model output.

So I still use it, but it isn't the main lock. The main lock is the next one.

Trap 3: SQLITE_IGNORE turns a refusal into wrong data

sqlite3_set_authorizer registers a callback that SQLite calls while compiling: once per table/column read, per function, per statement type. That's the real allowlist. My callback allows SELECT and RECURSIVE, allows reads only of columns in the catalog, allows about 30 listed functions, and denies everything else:

internal PolicyViolation? Decide(int actionCode, string? p0, string? p1) => actionCode switch
{
    raw.SQLITE_SELECT or raw.SQLITE_RECURSIVE => null,
    raw.SQLITE_FUNCTION => DecideFunction(p1),       // allowlisted names only
    raw.SQLITE_READ     => DecideRead(p0 ?? "", p1 ?? ""), // catalog tables and columns only
    _ => new("statement_not_allowed", ActionName(actionCode)),
};
// DecideFunction, DecideRead and ActionName: full implementation in the complete project

The trap is the return value. For a column read, SQLITE_IGNORE makes SQLite return NULL instead of failing. Nothing errors, and that's exactly the problem: "show me customer emails" answers with a column of NULLs, and the user concludes you have no emails on file. I return SQLITE_DENY, so the statement fails to compile and the user gets an honest refusal.

Trap 4: count(*) reads a column with no name

Hiding a table from the catalog isn't enough if SELECT count(*) FROM payout_accounts still works. It tells an attacker how many rows exist.

The authorizer does fire for that query, just with an empty string as the column name (the SQLite docs describe exactly this). It's easy to write a rule that treats "no column" as "nothing to check". Mine allows the empty column only for catalog tables and denies it for any real table that isn't in the catalog. A test named Denies_hidden_tables_even_for_count_star keeps it that way.

Trap 5: pooled connections keep your hooks

Since version 6.0, Microsoft.Data.Sqlite pools connections by default. The authorizer and the progress handler (which I use for query deadlines) live on the native sqlite3 handle, not on your SqliteConnection object.

In a spike I installed a deny-all-reads authorizer, closed the connection, opened a new one with the same connection string, and ran a simple SELECT. It failed with "access to orders.id is prohibited". The hook had survived through the pool. With Pooling=False, the same second query worked.

Either direction is bad: unrelated code can inherit your guard, or your guarded path can get a handle without it. Every guarded connection in the project is unpooled and opened read-only, and both hooks are removed in a finally. There's a test for it, Hooks_do_not_leak_between_runs.

Trap 6: the repair loop becomes a search engine

Models get column names wrong, and feeding SQLite's error back ("no such column: category_name") usually fixes it on the next try. So a repair loop is worth having.

But only for honest mistakes. If you also send back "access to customers.email is prohibited", you've told the model what's off limits and asked it to try another way in. In my service, SQL errors get up to two repair rounds (MaxRepairAttempts = 2). Policy violations end the request as Refused immediately, the model never sees why, and timeouts aren't repaired either:

if (run.Kind == QueryRunKind.SqlError && calls < maxCalls)
{
    // add the draft and PromptBuilder.RepairMessage(run.Error) to the conversation, try again
}
// violations: Refused, codes only, no repair (full flow in the complete project)

The checklist

[ ] Compile the SQL and the tail; exactly one statement or refuse
[ ] Don't treat sqlite3_stmt_readonly as the main lock
[ ] An authorizer allowlist for tables, columns, functions and statement types
[ ] SQLITE_DENY, never SQLITE_IGNORE
[ ] Hidden tables denied even for count(*)
[ ] Unpooled, read-only connections, hooks removed in finally
[ ] A deadline (progress handler) plus row and cell caps
[ ] Repair SQL errors, never policy violations, with a hard limit

The project has 134 offline tests (121 unit, 13 integration with WebApplicationFactory) and a fake model that misbehaves on purpose: it writes DELETEs, stacks statements, goes after hidden columns and writes a recursive CTE that never ends.

All of this still assumes one shop per database. Put 40 shops in the same tables and a perfectly "allowed" SELECT SUM(total) FROM orders reads everyone's revenue. Where the tenant boundary should live is the hardest part, and I cover it in the project and the PDF.

Get the complete project

The snippets above are the outline. The complete .NET 10 solution is in Tech Skill Builder: the semantic catalog that drives both the prompt and the allowlist, the statement inspector, the authorizer, a per-tenant sandbox, deadlines and caps, the bounded repair loop, a privacy-aware audit trail, an ASP.NET Core minimal API, a 21-scene CLI demo and all 134 tests, plus an in-depth PDF guide. No API key needed to run it.

Which of these would your current text-to-SQL feature fall for?

5 Traps When One IChatClient Fronts OpenAI, Azure, Gemini and Anthropic (.NET 10)

MICHAEL-MAURICE — Mon, 26 Oct 2026 12:01:18 +0000

"Just put an interface in front of the LLM" is advice everyone agrees with. In .NET the interface even exists already: IChatClient from Microsoft.Extensions.AI, with adapters for OpenAI (which also covers Azure OpenAI), and official SDKs from Anthropic and Google that expose AsIChatClient() themselves.

So I built a small support-ticket triage API on .NET 10 that can run on any of the four, switched by one config value. Getting the interface in place took an afternoon. Making it actually hold took longer. Here are the five traps I hit, and the check I now use for each one.

Packages, as used in the project: Microsoft.Extensions.AI 10.11.0, OpenAI 2.14.0, Anthropic 13.3.0, Google.GenAI 1.27.0. Code below is trimmed to the shape; omitted parts are marked.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. Complete, working, tested .NET projects with full source code and PDF guides: Tech Skill Builder.

If you want a ready-made starter instead of wiring this yourself, my Clean Architecture .NET 9 Web API with Unified AI Integration covers six providers out of the box. More on it at the end.

Trap 1: the interface is there, but the SDK leaked anyway

The whole point is that the Application layer knows IChatClient and nothing else. In practice, someone adds using OpenAI; to a handler "just for one option", and the abstraction is gone without anyone noticing in review.

A rule you can't see is a rule you don't have. So I don't rely on discipline; a test reads the compiled Application assembly's references and fails if any vendor SDK shows up:

[Fact]
public void Application_knows_only_the_AI_abstractions_never_a_vendor_SDK()
{
    var refs = typeof(TriageTicketHandler).Assembly.GetReferencedAssemblies()
        .Select(a => a.Name!).ToArray();
    Assert.Contains("Microsoft.Extensions.AI.Abstractions", refs);
    // assert none of: OpenAI, Anthropic, Google.GenAI, Microsoft.Extensions.AI(.OpenAI)
    // (full list in the complete project)
}

The Application project only references Microsoft.Extensions.AI.Abstractions. Everything vendor-specific lives in one factory in Infrastructure.

Trap 2: treating Azure OpenAI as a fifth SDK

My first instinct was "Azure needs its own client". It doesn't anymore. Azure OpenAI's v1 API is OpenAI-compatible, so the factory uses the plain OpenAI SDK pointed at your resource's /openai/v1/ base URL, with the deployment name as the model and no api-version.

That makes the endpoint the fragile part. Forget the /openai/v1/ suffix and you get requests that look almost right. So the Azure branch always goes through one small helper:

AiProvider.AzureOpenAI => CreateOpenAI(provider, s, endpoint: AzureV1Endpoint(s.Endpoint!)),

internal static Uri AzureV1Endpoint(string resourceEndpoint)
{
    // normalizes https://your-resource.openai.azure.com/ to .../openai/v1/
    // (handles trailing slashes and an already-present suffix; see the complete project)
}

I checked that a test actually guards this: when I swapped AzureV1Endpoint(...) for the raw endpoint, exactly one test went red, the Azure adapter test. Then I reverted it.

Trap 3: failover works, and now you don't know who answered

Microsoft.Extensions.AI 10.11.0 ships OrderedFailoverChatClient. It tries clients in order, fails over only before any streaming output was exposed, and doesn't treat cancellation as a failure. It's marked experimental (MEAI001), so I suppress that warning locally, in the one registration that uses it.

The catch: after a failover, asking the outer client for its ChatClientMetadata doesn't tell you which vendor produced this response. For logs, cost tracking and support tickets, that matters.

My fix is a tiny DelegatingChatClient around each provider that stamps the configured provider name onto every response, under a key the Application owns:

internal sealed class ProviderNameChatClient(IChatClient inner, string providerName, string? model)
    : DelegatingChatClient(inner)
{
    public override async Task<ChatResponse> GetResponseAsync(
        IEnumerable<ChatMessage> messages, ChatOptions? options = null, CancellationToken ct = default)
    {
        var response = await base.GetResponseAsync(messages, options, ct);
        (response.AdditionalProperties ??= [])[AiResponseKeys.Provider] = providerName;
        return response;
    }
    // streaming override and GetService(ChatClientMetadata): in the complete project
}

The use case reads a plain string. It never sees a vendor type.

Trap 4: the missing key shows up on the first customer request

With one config value choosing the provider, it's very easy to deploy Provider = Anthropic to an environment where only the OpenAI key exists. Without validation, you find out when the first real request fails.

I bind the settings to an options class, register an IValidateOptions<AiOptions> and call ValidateOnStart(). The validator only checks the providers you actually selected (primary and fallback), and it also rejects a fallback that's the same as the primary. Running with AI__Provider=OpenAI and no key now stops the app at startup:

Microsoft.Extensions.Options.OptionsValidationException: AI:OpenAI:ApiKey is required.

There's also a Fake provider that needs no settings at all, so the app and its tests run offline by default.

Trap 5: mocking IChatClient tests your code, not your wiring

The obvious test double is a fake IChatClient. It's useful for the use case, but it skips everything that breaks in real life: the endpoint, the auth header, how ChatOptions gets translated into each vendor's request body.

Because every SDK gets its HttpClient from IHttpClientFactory, the tests can build the real registration and replace only the network:

services.AddUnifiedAi(configuration);
services.ConfigureHttpClientDefaults(b => b.ConfigurePrimaryHttpMessageHandler(() => stub));
// stub records each request and returns a hand-written response in that vendor's format

Now each provider test asserts what the real SDK put on the wire: the URL, the auth header, and JSON mode and the system prompt mapped into that vendor's shape. This caught one wrong assumption on the first run. I expected Anthropic's SDK to send an x-api-key header, but Anthropic 13.3.0 sends the key as Authorization: Bearer. The SDK's XML docs confirm it, so the test now pins that.

The same stub makes failover testable too. Answer Anthropic with a 529 overloaded_error, and the test checks there was one request to Anthropic, then one to Gemini, and that the result reports Gemini.

To be clear about limits: these tests never hit a live vendor. The responses are written by hand in each documented format, so real model output, rate limits and streaming from the actual services aren't covered.

The checklist I'd use on any multi-vendor setup

[ ] A test fails if the Application layer references a vendor SDK
[ ] Azure OpenAI goes through one endpoint helper, and a test breaks if you bypass it
[ ] Every response says which provider answered, even after failover
[ ] Missing keys or models for the selected providers stop the app at startup
[ ] Adapter tests check the real HTTP request, not a mocked interface
[ ] Business rules (like "a data breach is always Urgent") live in the domain, so no model can override them

The project behind this has 42 offline xUnit tests: 9 provider-adapter, 12 failover and configuration, 10 use-case, 5 domain, 2 architecture and 4 API tests. No API key needed.

Want the ready-made version?

The Clean Architecture .NET 9 Web API - Unified AI Integration starter kit ($8) is the bigger, production-style take on this idea: Domain / Application / Infrastructure / API layers with CQRS and MediatR, six providers (OpenAI, Azure OpenAI, Gemini, Anthropic, Cohere, Hugging Face), endpoints for text generation, image generation, image analysis, provider listing, model discovery and provider health, plus Serilog, HealthChecks, Swagger and an MIT license. It targets .NET 9. To be upfront: the small .NET 10 triage demo from this post is my own and isn't part of the kit.

Which of these five has bitten you when switching LLM vendors?

When the Guard Itself Breaks: Making .NET AI Agent Guardrails Fail Closed

MICHAEL-MAURICE — Sun, 25 Oct 2026 11:56:46 +0000

We test guardrails by sending them bad input: an injection, a card number, a refund that's too big. That's necessary, but it only tests the guard when the guard is working. The more uncomfortable question is: what does your agent do when the guard itself breaks? It throws, its dependency is down, it gets wired into the pipeline wrong, or it runs in a code path you didn't expect.

In my experience the answer is usually "it allows the request", and nobody notices until much later. So I went through the guard layers of a .NET helpdesk agent and broke each one on purpose. Below is every place one of them wanted to fail open, and what I changed so it fails closed instead.

The stack is .NET 10 with Microsoft.Agents.AI 1.25.0 and Microsoft.Extensions.AI 10.11.0. The model in the tests is an offline fake that behaves badly on purpose: it calls tools it was never offered, loops, and ignores refusals. Code below is trimmed to the shape; omitted parts are marked.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. The complete guarded agent from this post, with a step-by-step PDF, is inside Tech Skill Builder.

Quick map: where the guards sit

Agent Framework gives you three middleware hooks, and I use all of them:

agent run middleware: sees the incoming messages and the final response (input screen, caller check)
function calling middleware: sees every tool call the model makes (the tool policy)
IChatClient middleware: sees every model call (budgets, output scrubbing)

Each of the failures below happened at one of these layers.

Break 1: the guard throws, and the agent carries on

My first "halt this run" was an exception thrown from the function middleware. It didn't halt anything. FunctionInvokingChatClient caught it, sent "Error: Function failed." back to the model as the tool result, and the loop kept going. That's the documented behaviour of MaximumConsecutiveErrorsPerRequest: exceptions are reported to the model and only rethrown once the limit (3 by default) is reached.

So a guard that "stops" a run by throwing actually gives the model up to three more tries. The fix is to set it to zero, so exceptions propagate immediately:

.UseFunctionInvocation(configure: f =>
{
    f.MaximumConsecutiveErrorsPerRequest = 0; // guard halts must propagate
    f.IncludeDetailedErrors = false;          // no exception text to the model
    // iteration limit set from the model-call budget (complete project)
})

But that creates the opposite problem: now a flaky database aborts runs too. So the tool guard catches real tool bugs itself and lets only its own halts escape:

try { result = await next(context, ct); }
catch (OperationCanceledException) when (ct.IsCancellationRequested) { throw; }
catch (GuardHaltException) { throw; }            // ours: end the run
catch (Exception)
{
    // audit as "tool_error", then return a generic result
    // (exception text never goes back into the context window)
    return ToolErrorResult;
}

Break 2: the classifier is down

The input screen calls an IInputClassifier to score prompt-injection risk. If that classifier is a remote service, at some point it will time out. The tempting code is catch { verdict = Safe; } so users aren't blocked by an outage.

That's a guard that quietly becomes "allow" exactly when you can't see what's happening. Mine blocks instead, with its own rule id so it's visible on a dashboard:

try { verdict = await classifier.ClassifyAsync(text, ct); }
catch (Exception ex) when (ex is not OperationCanceledException)
{
    return Block(run, "classifier_unavailable"); // fail closed
}

The user gets "temporarily unavailable, try again shortly", not an agent with no screen. A test (Classifier_outage_fails_closed) plugs in a classifier that always throws and checks that the rule fired and the model was called zero times.

Break 3: nobody said who's asking

Every policy decision depends on the caller: a customer can refund up to $50, staff up to $500, and customers only see their own orders. The caller comes from AgentRunOptions.AdditionalProperties, set by the host, never by the model.

So what happens when the host forgets to set it? The easy default is an anonymous caller with some role, and the run continues. Mine blocks the run as no_caller before the model is called at all. The test asserts exactly that: outcome Blocked, zero model calls.

Break 4: a layer runs outside the pipeline you designed

The function and chat middleware need per-run state (the caller, counters, rules that fired). I pass it through an AsyncLocal scope opened by the run guard. The question is what a layer should do if that scope is missing, for example because someone registered the tool middleware on a different agent, or called the chat client directly.

Skipping the check ("no scope, nothing to enforce") is failing open. Mine treats it as a wiring bug and halts:

public static GuardRun Require(string layer) =>
    CurrentRun.Value ?? throw new GuardHaltException(
        "no_guard_scope", $"{layer} ran outside a guarded agent run");

Outside_a_guarded_run_the_guard_fails_closed pins it.

Break 5: streaming takes a different path

Two separate streaming surprises:

If you register agent run middleware with only the non-streaming function, the docs warn that streaming calls "will only run in non-streaming mode". I checked: the stream came back as one update. Register both delegates.
An AsyncLocal value set inside an async iterator doesn't survive across yield return. So a scope opened once at the top of the streaming run guard is gone by the time the inner stream reaches a tool call. Because of Break 4, the result is a halt with no_guard_scope, not an unguarded tool call, and a streaming test with a tool call shows exactly that without the fix. The fix is to re-establish the scope around every MoveNextAsync of the inner stream:

// inside RunStreamingAsync
while (true)
{
    ValueTask<bool> step;
    using (GuardScope.Begin(run)) step = e.MoveNextAsync();
    // await step, turn GuardHaltException into a refusal, yield e.Current
    // (full loop, hold-back redaction and final outcome in the complete project)
}

This is the best argument I know for Break 4: a guard that halts on missing state turned a silent bypass into a failing test.

Break 6: the model just keeps asking

A denial is not an error. The tool guard returns a short reason-only result (DENIED by policy (rule id), never the arguments) and the model is free to try again. A stubborn or manipulated model will. Two limits stop that from turning into a loop:

a tool-call budget per run (6 by default), halted as tool_budget_exceeded
a denial budget: after 3 denied calls in one run, the next one halts the run as repeated_policy_denials

A halted turn isn't persisted, and a test checks that the session's stored history afterwards is identical to what it was before the halted turn.

One I chose not to use

FunctionInvocationContext.Terminate = true ends the loop after the current call. It sounds like a halt, but the Learn docs warn it can leave the history inconsistent, and in my spike the run ended on a function result with empty text. Fine for "we're done", not something I'd hang a security decision on.

The checklist

[ ] Guard exceptions end the run (MaximumConsecutiveErrorsPerRequest = 0), tool bugs don't
[ ] A broken dependency of the guard blocks, with its own rule id
[ ] A missing caller blocks before the first model call
[ ] A layer with no run state halts instead of skipping its checks
[ ] Both streaming and non-streaming paths are registered and tested
[ ] Denials and tool calls have per-run budgets
[ ] Every fail-closed path has a test that forces it

The project behind this has 94 offline tests (85 unit, 9 integration with WebApplicationFactory), and a good share of them exist only to force a guard into one of the failures above.

There's also one case none of this covers: every call the model makes passes every policy, and the action is still wrong, because the instruction came from the data the agent read, not from the user. The project handles that too, and the PDF walks through how.

Get the complete project

The snippets here are the outline. The complete .NET 10 solution is in Tech Skill Builder: all three guard layers, the per-tool policy catalog, the secret redactor, the streaming hold-back redactor, the text-free audit trail, an ASP.NET Core minimal API with SSE streaming, a CLI demo with 13 scenes and all 94 tests, plus an in-depth PDF guide. No API key needed to run it.

What does your agent do today when its guard throws?

Write the Boring Scenarios First: A Spec Checklist Before Your AI Coder Writes C#

MICHAEL-MAURICE — Sun, 25 Oct 2026 11:55:27 +0000

The scenario I almost didn't write was the dull one: a customer tries a coupon on a 50.00 cart, gets rejected because the minimum is 100.00, then adds items and tries again at 150.00. Should the second attempt work? Obviously yes. But "obviously" is not in any prompt, and code that records a redemption before checking the rules will happily use up the coupon on the failed attempt.

That's the part of spec-driven development I want to focus on here. Not the tooling or the commands, just the spec itself: what does a set of acceptance scenarios need before you hand it to an AI coding agent, so the agent has nothing left to guess?

I worked through this on a small .NET 10 feature, coupon redemption at checkout, with the spec written in GitHub Spec Kit's file layout and every scenario running as an xUnit test (37 tests in total). Code below is trimmed to the shape; omitted parts are marked.

Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. Complete, working, tested .NET projects with full source and PDF guides are inside Tech Skill Builder.

If you want the whole spec-driven workflow explained end to end, I also have a PDF guide on it: Spec Driven Ai Development ($10). More at the end.

The checklist

Every scenario has an ID a test can find
Every boundary is written from both sides
The clock and the calendar are named
Rounding is stated, once
Failures say what they do NOT change
Every rejection has a name
No open question is left in the file

Here's why each one is on the list.

1. Every scenario has an ID a test can find

A scenario without an ID is a paragraph. A scenario with an ID like AS-2.3, citing requirements like FR-006, is something a test can be matched against. I keep each scenario as one row of data, Given / When / Then:

public sealed record Scenario(
    string Id, string[] Covers,                       // "AS-2.3", ["FR-006", "FR-009"]
    DateTimeOffset Now, PriorAttempt[] Before,        // Given
    string Customer, decimal Subtotal, string Code,   // When
    RedemptionResult Expected);                       // Then

// AcceptanceScenarios.All = [ ...one row per AS-x.y in spec.md... ]
// (all 14 rows in the complete project)

Then a test reads spec.md itself and fails if the IDs in the file and the IDs in the test data drift apart:

[Fact]
public void Every_scenario_in_the_spec_has_a_test_case_and_vice_versa()
{
    // parse **AS-x.y** markers out of spec.md, compare with AcceptanceScenarios.All
    // (regexes and the FR coverage checks are in the complete project)
}

That one test is what turns the spec from documentation into a contract. If the agent (or you) adds a scenario to the spec and forgets the test, the build goes red.

2. Every boundary is written from both sides

"Orders of 100.00 or more qualify" sounds complete. It isn't, until you write the two rows that pin the line:

**AS-2.3** Given a 10% coupon MIN100 with a 100.00 minimum, When it is applied to
99.99, Then it is rejected with BelowMinimumSubtotal.
**AS-2.4** Given the same coupon, When it is applied to exactly 100.00,
Then it is accepted with a 10.00 discount.

The first row alone passes with > or >=. Only the pair catches the wrong one. I checked that by flipping >= to > in the implementation: exactly one test failed, AS-2.4, and everything else stayed green.

3. The clock and the calendar are named

"Valid until October 23" has three hidden questions: inclusive or not, in which time zone, and whose clock. My spec answers them in a clarification (inclusive, until the end of that date in the store's time zone, Africa/Cairo) and then pins it with another boundary pair:

2026-10-23 20:59:59 UTC (23:59:59 in Cairo): accepted
2026-10-23 21:00:00 UTC (midnight in Cairo): rejected as Expired

The constitution adds the rule that makes this testable at all: domain code reads time from an injected TimeProvider, never DateTime.UtcNow. That also lets a test cover daylight saving. Egypt leaves summer time on Oct 29, 2026, so a coupon valid until Oct 31 must still work at 21:59:59 UTC and be expired at 22:00 UTC that day. If the spec never names the time zone, no agent will write that test for you.

4. Rounding is stated, once

A 15% coupon on 10.30 is 1.545 off. Is that 1.54 or 1.55? In .NET, Math.Round(1.545m, 2) returns 1.54, because the default is round-half-to-even (banker's rounding). If the business expects 1.55, the spec has to say "2 decimals, midpoint away from zero", and the constitution says where rounding is allowed to happen: one Money.Round method, nowhere else.

public static decimal Round(decimal amount) =>
    decimal.Round(amount, 2, MidpointRounding.AwayFromZero);

That one is complete; it really is that small. The hard part was writing the sentence in the spec, not the code.

5. Failures say what they do NOT change

This is the scenario from the intro, and it's the one I see missing most often. Specs describe what success does. They rarely describe what a failure must leave untouched. My spec has two rules for that:

a rejection never changes the total (it equals the subtotal)
a failed attempt does not use up the coupon (AS-3.3: rejected at 50.00, then accepted at 150.00)

A domain test backs it up: two rejected attempts, zero entries in the redemption log; one valid attempt, one entry. And because "once per customer" is also a concurrency rule, another test fires 50 parallel redemptions for the same customer and expects exactly one applied and 49 AlreadyRedeemed.

6. Every rejection has a name

"Return an error if the coupon can't be used" lets the agent pick one generic failure. Naming the reasons (UnknownCode, Expired, BelowMinimumSubtotal, AlreadyRedeemed) forces two useful decisions: the UI can tell the customer what actually happened, and someone has to decide the order of the checks (an expired coupon on a small cart: which reason wins?). The plan fixes that order; the spec only has to demand a specific reason.

7. No open question is left in the file

Spec Kit's template lets a first draft mark gaps with [NEEDS CLARIFICATION: ...], and its clarify step asks about them and writes the answers back into the spec. The cheap trick is to make leftovers fail the build:

[Fact]
public void Spec_has_no_open_clarifications() =>
    Assert.DoesNotContain("[NEEDS CLARIFICATION", Spec);
// Spec = spec.md copied to the test output (setup in the complete project)

Does the checklist actually catch anything?

To find out, I kept a second, "just prompted" implementation next to the real one. To be clear, I wrote it by hand to mirror what a one-sentence prompt leaves open (exact string match, UTC dates, >, default rounding, no cap, no clamp, no redemption log); it is not captured AI output. Run against the same 14 scenarios, it missed 7 of them. Every miss is a decision the one-sentence prompt never made: case and spaces in the code, rounding, the cap, a negative total, the minimum boundary, the time zone, and the second redemption. Three of them (boundary, time zone, rounding) are exactly the items from this checklist that the clarification step answered.

The implementation written from the finished spec passed all 14 scenarios on its first test run. The full suite is 37 tests: 14 acceptance scenarios, 5 traceability checks, 2 comparison tests and 16 domain tests, on .NET SDK 10.0.401 with xUnit v3, with -warnaserror on and 0 warnings.

What I didn't verify

I wrote the spec, plan and tasks by hand in Spec Kit's layout and template format. I did not run the Specify CLI or an AI agent through the commands for this example. I also didn't test the Africa/Cairo time zone lookup on Windows, or any persistence beyond in-memory stores.

Short version

[ ] Every scenario has an ID, and a test fails if spec and tests drift
[ ] Every "at least", "until" and "up to" has a row on each side of the line
[ ] The spec names the time zone, and the code reads an injected clock
[ ] Rounding mode is written down, and lives in one method
[ ] Failures state what they leave unchanged
[ ] Every rejection reason has a name
[ ] [NEEDS CLARIFICATION] can't survive into a green build

Go further

If you want the full spec-driven workflow (Constitution, Specify, Clarify, Plan, Tasks, Analyze, Implement) explained step by step, Spec Driven Ai Development is my $10 PDF guide on it, with review checklists, reusable prompt patterns and guidance for existing projects. It's an independent guide, not an official GitHub publication, and the coupon example from this post isn't part of it.

And if you learn best from complete code, Tech Skill Builder is where I put complete, working, tested .NET + AI projects with full source code and step-by-step PDF guides, with new ones added regularly. Tech Skill Builder is $5/month for a very limited time only (normally $10). Grab it now before it goes back to $10. Join Tech Skill Builder

Which "obvious" scenario did your AI coder get wrong because nobody wrote it down?

DEV Community: MICHAEL-MAURICE

The Shadow Model Issued a Refund: 7 Mistakes That Make LLM Model Upgrades in .NET Riskier Than They Look

Mistake 1: Thinking you're upgrading a model id

Mistake 2: Mirroring the whole request

Mistake 3: Letting the shadow job hold references

Mistake 4: Trusting the channel to count what it dropped

Mistake 5: Gating on "agreement"

Mistake 6: Bucketing users with GetHashCode()

Mistake 7: Fallbacks that hide failures, and gates that can't say "not sure"

A pre-flight list for your next model upgrade

What I tested, and what I didn't

Get the complete project

Review Your LLM Tool Like a Public Endpoint: 8 Questions to Ask Before You Merge an AIFunction in .NET 10

Question 1: Who chose the tool's name?

Question 2: What happens when an argument breaks the schema?

Question 3: What happens with an argument that doesn't exist?

Question 4: Which near-misses do we fix, and which do we refuse?

Question 5: What does the model read when the tool fails?

Question 6: Can the model decide who the user is?

Question 7: How many times is the model allowed to be wrong?

Question 8: What does this tool cost, and who notices when it changes?

The checklist version

What I tested, and what I didn't

Get the complete project

Stripe Will Send It Again: 7 Deliveries to Replay Against Your .NET Webhook Before Launch

The setup in one picture

Delivery 1: The plain retry

Delivery 2: Fifty copies at the same moment

Delivery 3: Two different events for the same payment

Delivery 4: "Updated" arrives after "deleted"

Delivery 5: A completed checkout that isn't paid

Delivery 6: A body that was touched, and a secret mid-roll

Delivery 7: Your side is broken

The status code table

What I tested, and what I didn't

Want the full Stripe integration?

Half Price Until You Pay Twice: 6 Ways an OpenAI Batch Job in .NET Quietly Costs You More

Mistake 1: Creating the batch again after a crash

Mistake 2: Retrying everything that failed

Mistake 3: Looping over the output file

Mistake 4: Reusing the same custom_id on a retry

Mistake 5: Letting the JSON encoder inflate your file

Mistake 6: Panicking at the deadline

The pre-flight checklist

What I tested, and what I didn't

Get the complete project

Your Telegram AI Assistant Can Email Anyone as You: 6 Checks to Run Before the Model Does

The shape

Check 1: Is this chat one of mine?

Check 2: Have I seen this update before?

Check 3: Is it stale?

Check 4: How big is this voice note?

Check 5: Which "Omar"?

Check 6: What time did the model mean?

What I checked, and what I didn't

The checklist

Want to skip the n8n part?

Deleted, Emptied, Half-Written: 6 Files a Nightly RAG Ingestion Job Gets Wrong in .NET 10

The one idea behind all six

File 1: the page you deleted

File 2: the page cut down to its title

File 3: the page that didn't change, in a folder that moved

File 4: the page that grew too big

File 5: the page whose embedding call died halfway

File 6: the page that fails every single night

The cheap part: nothing changed

Checklist

Get the complete project

One Clarifying Question, One Line of C#: 5 Interview Bugs I Planted on Purpose

How the experiment works

Bug 1: "Can I use the same element twice?"

Bug 2: "How big can the numbers get?" (the one that got through)

Bug 3: "What if the repeat is already outside my window?"

Bug 4: "Must the subarray be non-empty?"

Bug 5: "If one meeting ends at 10 and the next starts at 10, can they share a room?"

What the scoreboard says

Your practice checklist

Want to go further?

Your First AI Feature in .NET 10 in 15 Minutes

The plan (and the clock)

Mistake 6: Bucketing users with `GetHashCode()`