DEV Community: L Anil Kumar Singha

Incident Context: tracing production failures without guessing

L Anil Kumar Singha — Sun, 20 Sep 2026 16:58:42 +0000

This is a submission for the Sanity Challenge, Path One: Ship an Agent That Queries Real Content.

What I Built

Incident Context is an incident-investigation agent for questions that cannot afford a confident but unsupported answer.

During an outage, evidence is rarely contained in one document. It is spread across services and dependencies, deployments and released versions, configuration changes, previous incidents, and version-specific runbooks.

Incident Context models those records as connected Sanity documents. The agent follows their relationships through a Sanity Context MCP Knowledge Base, separates confirmed evidence from inference, and preserves the source paths behind every report.

The Problem

A keyword search can find "timeout" in both INC-142 and INC-208. But correlation is not causation.

Both incidents were production outages on consecutive days. Both involved configuration changes. Both mentioned timeouts. That is not enough to determine whether they share a root cause or require the same remediation.

The useful answer is not a matching paragraph. It is a supported path across an incident, an affected service, a deployment, a configuration change, and an applicable runbook.

The Solution

The agent models operational records as a connected graph:

Service    → depends on → Service
Deployment → belongs to → Service
Deployment → includes   → Change
Change     → modifies   → Service
Runbook    → applies to → Service
Incident   → affects    → Service
Incident   → relates to → Deployment
Incident   → relates to → Change
Incident   → references → Runbook

When you ask it to compare the two incidents, the agent follows the structured path, not keyword matches:

INC-208
→ affected checkout-api
→ related deployment checkout-api v2.3.0
→ included PAYMENT_TIMEOUT_MS configuration change
→ reduced from 5000ms to 1500ms

This traversal becomes an evidence trail in the interface:

Notice the evidence trail at the top. It shows the relationships the agent followed: INC-142 affected payment-api and was caused by a DB_POOL_SIZE reduction; INC-208 affected checkout-api and was caused by a PAYMENT_TIMEOUT_MS reduction. Two different paths. Two different root causes.

Below that: 4 confirmed evidence items, 0 inferences, 2 sources. The model did not guess or correlate. It followed the graph.

Why This Matters

Operational data contains many correlations:

a deployment happened before an incident
two incidents mention timeouts
a runbook belongs to an affected service
a configuration value changed near an outage

Those relationships are useful evidence. They are not automatically proof of causation.

The agent preserves the distinction. Every investigation returns:

A direct answer — plain language, grounded in the evidence
An evidence trail — the relationship path the agent followed
Confirmed evidence — facts from the Knowledge Base
Inferences — what the model had to infer (or in this case, nothing)
A recommended next step — actionable based on what was discovered
Sources — exact Sanity paths for verification

If Sanity Context cannot be reached, the application does not generate an unsupported fallback answer.

How I Used Sanity

Sanity is not being used as a generic document store behind a chat box. Its references form the investigation graph.

The project defines five document types: service, deployment, change, runbook, incident. Their references encode the operational relationships.

During the build, I included the references required for an investigation:

service.dependencies[] → service
deployment.service → service
deployment.changes[] → change
change.service → service
runbook.service → service
incident.affectedServices[] → service
incident.relatedDeployments[] → deployment
incident.relatedChanges[] → change
incident.relatedRunbook → runbook

Sanity Context distilled those connected documents into navigable, source-linked entries. At investigation time, the agent reads the Knowledge Base outline through initial_context, selects relevant entries, retrieves them through Knowledge Base tools, and traces explicit relationships. The system prompt explicitly forbids turning correlation into confirmed causation.

The Demo

Live application: https://incident-context.vercel.app/

No login is required.

The dataset represents a small production system:

web-app → checkout-api → payment-api → postgres

Try these questions:

What changed before INC-208?
Trace the services affected by INC-208.
Which runbook applies to INC-142?
Compare INC-142 and INC-208.

The comparison question is the strongest demonstration. It asks the agent to distinguish incidents that share related terminology but have different evidence paths.

Code

Repository: https://github.com/anilloutombam/incident-context

The repository contains two standalone applications:

agent/   Next.js investigation interface and API
sanity/  Sanity Studio, schemas, and demo data

Runtime Architecture

flowchart LR
    User[Incident question] --> UI[Next.js interface]
    UI -->|POST /api/chat| API[Next.js API]
    API --> Loop[AI SDK agent loop]
    Loop <-->|model requests| Gemini[Gemini 3.5 Flash-Lite]
    Loop <-->|MCP tool calls| MCP[Sanity Context MCP]

    Content[Sanity Content Lake<br/>Services · Deployments · Changes<br/>Runbooks · Incidents]
    Content -->|builds| KB[Sanity Knowledge Base]
    KB -->|serves cited entries| MCP

    Loop --> Report[Zod-validated report]
    Report -->|JSON response| UI
    UI --> Output[Evidence trail · Confirmed evidence<br/>Inferences · Next step · Sources]

The Gemini key and Sanity organization token remain on the server. The browser receives a validated report, not credentials.

Structured Output

The API validates the final response against a Zod schema instead of asking the model to return arbitrary Markdown:

{
  answer,
  evidenceTrail: [
    {
      from,
      relationship,
      to,
      source
    }
  ],
  confirmedEvidence,
  inferences,
  recommendedNextStep,
  sources: [
    {
      label,
      path
    }
  ]
}

This allows the interface to render relationships, facts, inferences, and sources as distinct product elements instead of parsing presentation from a generated string.

Production Safeguards

The deployed agent includes:

per-client request rate limiting
a 500-character question limit
a 30-second request timeout
explicit Gemini, Sanity, timeout, and rate-limit errors
no unsupported answer when the Knowledge Base is unavailable
a health endpoint at /api/health
server-only Gemini and Sanity credentials

Testing the MCP Dependency

The project uses the published mcp-failure-lab package to test the dependency the agent cannot operate without.

The live compatibility scenario calls initial_context and verifies that the Sanity Context endpoint responds within ten seconds.

A separate local resilience suite covers bounded delays, hanging requests, malformed MCP responses, and connection loss.

pnpm test:mcp
pnpm test:mcp:live
pnpm test:mcp:faults

What I Learned

The difficult part was not connecting a model to an MCP endpoint. It was deciding what the model was allowed to claim.

I initially let the model connect any dots it found—deployments before incidents, shared keywords, related services. The output looked authoritative. But INC-142 and INC-208 both mentioned timeouts and both affected the payment path. One was a database connection exhaustion issue. One was a configuration change that had been too aggressive. The model could see both, but it could not reliably say which caused which.

I had to split facts from guesses in the output, enforce it in the system prompt, and then show that separation in the UI. Because incident responders need to know what you are certain about.

The useful answer is not a matching paragraph. It is a supported path, with source citations, and an explicit boundary between evidence and inference.

I Injected the Same Failures Into 5 MCP SDKs. Here’s What I Found.

L Anil Kumar Singha — Sat, 19 Sep 2026 15:24:28 +0000

I've been building MCP Failure Lab, a deterministic failure-injection toolkit for testing Model Context Protocol clients and servers beyond the happy path.

Instead of asking whether an MCP client can successfully call a tool, I wanted to ask a different set of questions:

What happens when the connection disappears?
What happens when a response arrives twice?
What happens when the server sends malformed JSON-RPC?
Does the client recover?
Is the same behavior observable across SDKs?

Over the last few releases, I've been running the same failures against multiple official MCP SDKs.

Some of the differences turned out to be more interesting than I expected.

The test setup

The important part of these tests is determinism.

MCP Failure Lab deliberately produces a specific failure so that the same scenario can be replayed against different clients.

For the latest duplicate-response tests, I used:

mcp-failure-lab@0.10.0

with both:

stdio
Streamable HTTP

The clients tested were:

Client	Version
TypeScript SDK	1.30.0
Python SDK	2.2.0
Go SDK	1.7.0
Rust SDK (`rmcp`)	3.4.0
C# SDK	2.2.0

The runtime environment was macOS arm64 with Node.js 26.5.0, Python 3.12.14, Go 1.27.1, Rust 1.98.1 and .NET SDK 10.0.401.

The goal wasn't simply to see whether a request failed.

I also wanted to know whether the same session remained usable afterward.

Finding #1: HTTP disconnect recovery differed between TypeScript and Python

One of the earlier tests injected an HTTP disconnect and then attempted another request.

The TypeScript SDK recovered and the next request succeeded.

With Python SDK 2.2.0, the connection closed and the following request failed in the scenario I tested.

That was interesting because the injected failure was identical, but the observable recovery behavior wasn't.

I reported the reproduction upstream:

https://github.com/modelcontextprotocol/python-sdk/issues/3522

This was one of the first results that convinced me that failure testing across implementations was worth pursuing.

Happy-path interoperability doesn't necessarily imply recovery-path interoperability.

Finding #2: `rmcp` accepted a malformed JSON-RPC response

The next finding came from the Rust SDK.

MCP Failure Lab's malformed_message tool can intentionally return a JSON-RPC response containing both result and error.

Conceptually:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [],
    "resultType": "complete"
  },
  "error": {
    "code": -32603,
    "message": "injected error"
  }
}

A JSON-RPC response should contain either result or error, not both.

I expected the client to reject it.

With rmcp 3.4.0, however, call_tool returned:

Ok(CallToolResult)

The result was accepted and the error field was effectively ignored.

I reproduced this over both stdio and Streamable HTTP.

A subsequent normal request also succeeded, so this wasn't a connection-recovery problem. It was a message-validation difference.

The C# MCP SDK 2.2.0 rejected the same malformed wire response.

The likely Rust parsing path involves the untagged JsonRpcMessage representation: the response can deserialize into the JsonRpcResponse shape while Serde ignores the unexpected error field.

I reported that upstream as well:

https://github.com/modelcontextprotocol/rust-sdk/issues/1283

This is exactly the kind of issue that's difficult to notice when every server you're testing against sends valid messages.

Finding #3: Five SDKs survived a duplicate response, but exposed it differently

For MCP Failure Lab 0.10.0, I added a focused duplicate-response compatibility test.

The sequence was deliberately simple:

client
  |
  | tools/call
  v
server
  |
  | response #1
  | response #1 again
  v
client
  |
  | ping using the SAME session
  v
server

A passing recovery check required the final ping to succeed.

Here were the results:

Client	stdio	Streamable HTTP	Duplicate behavior	Same-session ping
TypeScript	Pass	Pass	Unknown-response-ID diagnostic	Pass
Python	Pass	Pass	No call-level duplicate error observed	Pass
Go	Pass	Pass	No call-level duplicate error observed	Pass
Rust	Pass	Pass	No call-level duplicate error observed	Pass
C#	Pass	Pass	No call-level duplicate error observed	Pass

The good news is straightforward:

all five clients remained usable.

None of them allowed the duplicate response to corrupt the session.

But their observable behavior wasn't identical.

TypeScript made the duplicate visible

The TypeScript SDK accepted the first response normally.

When the duplicate arrived, that request ID was no longer pending, so the SDK reported the repeated response through its error callback as a response for an unknown ID.

The diagnostic did not close the session.

The next ping succeeded.

The other four didn't expose a call-level error

Python, Go, Rust and C# also returned the first result and successfully completed the following ping.

But my harness didn't observe an equivalent call-level duplicate diagnostic from those clients.

That does not mean they failed to detect the duplicate.

There are several possible implementations:

response arrives
       |
lookup pending request ID
       |
       +-- found --> resolve request
       |
       +-- missing --> report?
                      log?
                      discard?

The current experiment only establishes what was observable through the public paths instrumented by the harness.

I did not instrument private SDK internals, so I can't claim that those four SDKs silently ignored the response internally.

That's a distinction worth preserving.

A "pass" isn't always the whole result

This has been one of the more useful lessons from these experiments.

If I reduced the duplicate-response test to:

TypeScript: PASS
Python:     PASS
Go:         PASS
Rust:       PASS
C#:         PASS

I'd lose most of the interesting information.

All five passed the recovery invariant.

But one implementation exposed an unexpected response to the application while the others didn't expose an equivalent call-level diagnostic in my harness.

That matters when you're debugging a production MCP system.

Two clients can both recover successfully while giving developers very different visibility into what happened.

Why test the request after the failure?

I've started treating this as one of the most important parts of the test.

Triggering a fault only tells you what happened during the fault.

It doesn't tell you whether the protocol state survived it.

So a typical Failure Lab scenario now looks conceptually like:

normal operation
      ↓
inject deterministic failure
      ↓
observe client behavior
      ↓
send normal request
      ↓
verify recovery

A timeout that returns an error but leaves the session healthy is very different from a timeout that poisons every request afterward.

Likewise, rejecting malformed JSON-RPC is different from accepting it while keeping the connection alive.

The post-failure request gives us that second dimension.

These aren't necessarily SDK bugs

Another thing I've tried to avoid is turning every behavioral difference into an upstream issue.

Different observable behavior isn't automatically incorrect behavior.

For example, the duplicate-response test currently shows an interoperability difference in diagnostics, but all five clients recover.

Before calling that a bug, the next step is to trace how each SDK handles a response whose request ID has already been completed:

duplicate response
       ↓
request ID no longer pending
       ↓
what does the SDK do?
       ↓
report / log / discard / reject

If an implementation violates a protocol requirement, that's worth reporting.

If it's simply an intentional observability choice, it's better documented as a compatibility difference.

The malformed Rust response was different: there was a concrete validation behavior to reproduce and compare, so I opened an upstream issue.

What I'm testing next

The next step isn't simply adding more SDK names to a table.

I'm more interested in expanding the failure dimensions.

Some of the scenarios I'm looking at include:

late responses after client timeout
session loss
server restart and recovery
duplicate SSE delivery
malformed or partial transport messages
cancellation races
responses with unexpected IDs
transient HTTP failures followed by recovery

Then the same failure can be replayed against multiple implementations.

That should eventually produce something more useful than a basic compatibility matrix:

a map of how MCP implementations behave when the protocol stops being perfect.

Reproducing the tests

MCP Failure Lab is open source:

https://github.com/anilloutombam/mcp-failure-lab

The published package is available through npm:

npx -y mcp-failure-lab@0.10.0 serve

The focused 0.10.0 duplicate-response compatibility report, including exact SDK and runtime versions, is here:

https://github.com/anilloutombam/mcp-failure-lab/blob/main/docs/compatibility/v0.10.0.md

The project documentation is also available at:

https://mcplab.dev/

If you're maintaining an MCP client, SDK or host and there is a failure mode you think would be useful to reproduce deterministically, I'd be interested in testing it.

The happy path tells us whether implementations can talk to each other.

I'm more interested in what happens after something goes wrong.

What Happens When an MCP Tool Call Never Returns?

L Anil Kumar Singha — Thu, 27 Aug 2026 04:57:27 +0000

A normal MCP tool call is straightforward: the client sends a request, the server runs the tool, and a response comes back.

A hang is different. The server accepts the call but never returns a result or an error.

I wanted to test how an MCP client behaves in that case without relying on network tricks or manually killing a process.

Reproducing a hang

MCP Failure Lab has a hang tool specifically for this.

The behavior is intentionally simple: once called, it doesn't resolve.

That gives us a repeatable failure instead of trying to approximate one with a very long delay.

A scenario for it looks like this:

{
  "name": "hung tool call times out",
  "call": {
    "tool": "hang",
    "args": {}
  },
  "timeoutMs": 1000,
  "expect": {
    "outcome": "timeout"
  }
}

The server behavior and the expected client behavior are separate here.

The server hangs.

The client is expected to time out after one second.

That distinction matters because a hung server doesn't produce a timeout by itself. The timeout has to be enforced by the client or by something around the request.

Hang vs delay

I originally treated a long delay as being close enough to a hang, but they're useful for testing different things.

A delayed call still has a completion point:

request ---- 5 seconds ----> response

A hung call doesn't:

request -------------------->
        -------------------->
        -------------------->

With a delay, a response can still arrive after the client has timed out.

With a hang, there is no eventual response.

That difference starts to matter when testing cancellation and cleanup.

A timeout only tells you what the client saw

Suppose a client calls a tool and gets a timeout.

It's tempting to treat that as meaning the operation failed.

That's not necessarily true.

Consider a tool that changes some state:

client                    server
   |                         |
   | ---- request ---------->|
   |                         | changes state
   |                         |
   |       response lost     X
   |
   | ---- timeout

The client saw a timeout, but the server may have already completed the operation.

If the client automatically retries, the operation might run twice.

This is one reason I'm interested in keeping the observed outcome separate from server state in Failure Lab.

It's also where simple timeout testing stops being enough.

What should happen after the timeout?

There are a few things worth checking beyond whether a timeout was thrown:

Is the original operation cancelled?
Is the MCP session still usable?
Can another tool call succeed?
Does the client retry?
Can you determine whether the original operation changed state?

The last one is particularly useful for tools with side effects.

Failure Lab supports an independent observe call for scenarios where state needs to be checked after the main call.

That lets a test distinguish between:

client observed: timeout
server state: unchanged

and:

client observed: timeout
server state: changed

Those are very different outcomes even though the client reported the same error.

Keeping the failure deterministic

The main reason I built the hang fault wasn't to simulate an unreliable network.

It was to remove the unreliable part from the test.

If the server hangs deterministically, I can run different clients against the same behavior and compare what they do.

The path still goes through MCP:

scenario
   ↓
MCP client
   ↓
transport
   ↓
MCP server
   ↓
hang

Only the failure is controlled.

That makes bugs around timeout handling much easier to reproduce.

Try it

The project is open source:

npx mcp-failure-lab demo

GitHub: https://github.com/anilloutombam/mcp-failure-lab

I'm working through other failure cases as well, particularly cancellation, session loss, malformed responses, and cases where the client reports failure even though the server changed state.

If you've hit an MCP failure that was difficult to reproduce, open an issue. I'd rather turn real failure cases into deterministic scenarios than invent them.

Introducing MCP Failure Lab: Testing MCP Beyond the Happy Path

L Anil Kumar Singha — Sat, 15 Aug 2026 19:21:09 +0000

Most MCP examples focus on successful tool calls. That is useful for getting started, but production systems also need to handle calls that stall, exceed their timeout, get cancelled, or lose their connection.

I started building MCP Failure Lab to make those failure paths controlled, repeatable, and easier to test.

What is MCP Failure Lab?

MCP Failure Lab is an open-source TypeScript toolkit for testing how MCP clients and related systems respond to failure conditions.

The project currently includes:

Deterministic delay, hang, and disconnect fault tools
A TypeScript CLI and stdio MCP server
A code-first scenario runner
Success, error, timeout, and duration assertions
Unit and integration tests
CI, coverage, dependency, and security checks

Instead of relying on unreliable network conditions or arbitrary sleeps, the goal is to provide explicit failure behavior that can be reproduced in a test suite.

Why build this?

A successful tool call only proves the happy path.

It does not tell us whether a client:

Enforces request timeouts
Cancels work correctly
Cleans up resources after failure
Distinguishes tool errors from transport failures
Recovers after a connection is interrupted
Produces useful diagnostic information

These behaviors become increasingly important as MCP integrations move beyond local experiments.

Current architecture

Fault tools are registered directly on an MCP server. Tests connect through MCP transports and exercise the same protocol path used by real tool calls.

The scenario runner adds a small testing layer around those calls. A scenario describes:

Which tool to call
Which arguments to provide
The request timeout
The expected outcome
Optional duration limits

The runner records the observed result and evaluates the configured assertions.

This keeps the project code-first, type-safe, and suitable for existing TypeScript test suites.

What comes next?

The project is still early, and there are several areas where contributions would be valuable:

Each issue includes its expected behavior, acceptance criteria, limitations, and relevant files.

Before starting substantial work, please comment on the issue with your proposed approach and ask to be assigned. This helps avoid duplicated work and gives us a place to discuss the design first.

Contributions are welcome

If you work with MCP, TypeScript, resilience testing, or developer tooling, I would value your feedback.

You can contribute code, review the design, improve documentation, test the project, or suggest failure modes that are worth supporting.

MCP Failure Lab is available on GitHub:

https://github.com/anilloutombam/mcp-failure-lab

If the project is useful to you, consider starring it, opening a discussion, or picking up one of the contributor-ready issues. I would be glad to build it with others.

How I Designed a Production Global Search System on PostgreSQL

L Anil Kumar Singha — Fri, 14 Aug 2026 16:41:28 +0000

Search often starts as a text box.

Then the requirements arrive.

Users want to search by a specific field. Then multiple fields. Then exclusions. Date ranges. Multi-select filters. AND, OR, NOT. Parentheses. Nested conditions.

Eventually, this:

payment approval

turns into this:

(
  "payment approval"
  OR (
    department:finance
    AND (status:open OR status:pending)
  )
)
AND NOT (
  owner:system
  OR category:archived
)

At that point, you're no longer building a text box.

You're designing a query language.

I ran into exactly this while designing a global search system for a production application.

From the user's perspective, I wanted the experience to remain simple: one global search surface, similar to the issue-search experience developers are familiar with in tools like GitHub or GitLab.

Underneath, the requirements evolved into a Lucene-style query model supporting:

free-text search
key:value filters
quoted phrases
AND, OR, and NOT
parentheses and grouping
recursively nested expressions
text filters
date ranges
multi-select fields
column-level filtering

But there was one requirement I considered just as important as the query language itself:

Users shouldn't need to understand the query language to use it.

So the system supported two ways of expressing the same search intent.

Power users could write the query directly.

Everyone else could build it through column-level filters. Depending on the field, the UI provided a text input, date-range picker, multi-select dropdown, or Boolean condition and constructed the expression as the user filtered.

Then the production dataset grew, and a second problem emerged:

free-text search performance.

That eventually led to another architectural decision:

Do I introduce a dedicated search engine, or can PostgreSQL continue owning search?

I kept PostgreSQL.

After profiling the expensive path and moving the free-text workload to a GIN-backed indexing strategy, measured search latency dropped from roughly 40ms to 12ms on a production dataset containing more than 20,000 records at the time.

The performance number is useful, but it isn't the most interesting part of the story.

What interested me more was how one search box ended up touching UX design, language parsing, recursive data structures, database performance, and infrastructure trade-offs.

One search box, different levels of precision

I didn't want advanced search to make basic search harder.

Someone should always be able to type:

payment approval

and search normally.

Nothing else should be required.

A user who knows exactly what they're looking for can be more specific:

status:open

or:

owner:"John Doe"

Free text and structured conditions can be combined:

"payment approval" AND status:open

And power users can go much further:

("payment approval" OR refund)
AND (status:open OR status:pending)
AND NOT owner:system

This gave the search experience progressive complexity.

You don't need to understand the language to start searching.

But when you need more precision, the language is there.

The next problem was usability.

Most users shouldn't have to learn that syntax.

So I didn't make them.

The UI could write the query for you

Alongside the global search input, I designed column-level filtering.

The control shown to the user depended on the type of data being filtered.

For text:

Owner
┌────────────────────────┐
│ John                   │
└────────────────────────┘

For dates:

Created Date

From: 01 Aug 2026
To:   14 Aug 2026

For predefined values:

Status

✓ Open
✓ Pending

Conditions could also include or exclude values:

Status
AND
Open

or:

Status
NOT
Archived

As users interacted with those controls, the application constructed the corresponding search expression.

A user might interact with something like:

Search: payment approval

Status:
  ✓ Open
  ✓ Pending

Owner:
  NOT System

Created:
  Aug 1 → Aug 14

while the system represented the same intent as something equivalent to:

"payment approval"
AND (status:open OR status:pending)
AND NOT owner:system
AND createdDate:[2026-08-01 TO 2026-08-14]

The user didn't need to write that.

The UI did it for them.

That became an important principle in the design:

A system can support a sophisticated query language without requiring users to speak that language.

Two interfaces, one search model

I didn't want the visual filter builder and the advanced query input to become two independent search implementations.

That would eventually create two sets of semantics, two places for bugs, and two implementations that could disagree about what the same filter means.

Instead, both interfaces converged on the same search model.

        ┌─────────────────────────┐
        │    Global Search Box    │
        │                         │
        │ Lucene-style syntax     │
        └────────────┬────────────┘
                     │
                     ▼
              Search Expression
                     ▲
                     │
        ┌────────────┴────────────┐
        │ Column Filter Builder   │
        │                         │
        │ • Text input            │
        │ • Date range            │
        │ • Multi-select          │
        │ • AND / NOT             │
        └─────────────────────────┘

From there, the expression entered the same processing pipeline:

Search Expression
       │
       ▼
   Tokenizer
       │
       ▼
     Parser
       │
       ▼
      AST
       │
       ▼
   Validation
       │
       ▼
 Query Compiler
       │
       ▼
 Prisma / SQL
       │
       ▼
  PostgreSQL

There weren't two search engines.

There were two ways of expressing the same search intent.

That distinction kept the architecture much easier to reason about.

When search became a language

Boolean operators changed the nature of the problem.

Consider:

status:open OR status:pending AND priority:high

With normal Boolean precedence, that means:

status:open
OR
(status:pending AND priority:high)

which is different from:

(status:open OR status:pending)
AND priority:high

Now add NOT:

(status:open OR status:pending)
AND NOT owner:system

Then nested grouping:

(
  status:open
  OR (
    status:pending
    AND (
      priority:high
      OR priority:critical
    )
  )
)
AND NOT owner:system

At this point, .split("AND") isn't an architecture.

Neither is continuing to grow a regular expression until nobody wants to touch it.

The requirement had crossed an architectural boundary.

I needed a parser.

Treating search like a small compiler

I ended up treating the search input similarly to a small language-processing pipeline:

Raw Query
    │
    ▼
Tokenizer
    │
    ▼
 Parser
    │
    ▼
   AST
    │
    ▼
Validator
    │
    ▼
Compiler
    │
    ▼
PostgreSQL

Each stage had a narrow responsibility.

The tokenizer identified meaningful pieces of the language.

The parser determined how those pieces related to each other.

The AST represented the user's intent independently of the original string.

The validator ensured that only supported fields and operations could be used.

The compiler translated that structured representation into database conditions.

That separation mattered.

The parser didn't need to understand how PostgreSQL executed search.

PostgreSQL didn't need to understand our user-facing syntax.

And the database layer didn't need to repeatedly reinterpret an arbitrary search string.

From a query string to structured data

Take:

(payment OR refund) AND status:open

The tokenizer can identify units such as:

LPAREN
TEXT(payment)
OR
TEXT(refund)
RPAREN
AND
FIELD(status, open)

Quoted values remain intact:

owner:"John Doe"

as do quoted free-text phrases:

"payment approval"

Parentheses and Boolean operators remain explicit because they determine the structure of the expression.

Now consider:

(payment OR refund) AND NOT status:archived

Instead of carrying that string through the application, the parser can represent its meaning as a tree:

                 AND
                /   \
              OR     NOT
             /  \      \
      payment  refund   FIELD
                         │
                   status:archived

A simplified TypeScript representation could look like:

type SearchNode =
  | {
      type: "text";
      value: string;
    }
  | {
      type: "field";
      field: string;
      value: string;
    }
  | {
      type: "and" | "or";
      left: SearchNode;
      right: SearchNode;
    }
  | {
      type: "not";
      operand: SearchNode;
    };

The exact TypeScript isn't the interesting part.

The boundary is.

The user's arbitrary string has become structured data that can be validated, transformed, tested, and compiled.

Supporting N-level nested search

I didn't want the grammar to contain a hard-coded concept of:

level 1
level 2
level 3

Expressions are recursive.

Conceptually:

Expression :=
    FreeText
  | FieldCondition
  | NOT Expression
  | (Expression)
  | Expression AND Expression
  | Expression OR Expression

An expression can contain another expression, which can contain another expression.

So:

A AND (B OR (C AND (D OR (E AND NOT F))))

doesn't require special handling.

It's simply a deeper tree:

The compiler recursively walks the tree.

There is no fixed application-level nesting depth in the search grammar.

That lets users continue composing conditions when they need more precision instead of running into an arbitrary maximum number of filter groups.

Of course, that doesn't mean execution has infinite resources.

Request size, runtime behavior, query complexity, timeouts, and infrastructure still create practical boundaries.

Those are operational constraints rather than artificial limits in the grammar.

Search fields are an API, not database columns

Supporting:

status:open

raises another question.

What happens if someone tries:

someInternalDatabaseField:value

A search language shouldn't automatically become an interface to the underlying database schema.

Instead, searchable fields should be explicitly supported.

A simplified mapping might look like:

const searchableFields = {
  status: /* internal mapping */,
  owner: /* internal mapping */,
  category: /* internal mapping */,
  priority: /* internal mapping */,
};

The actual implementation can contain considerably more metadata because different fields require different controls, validation rules, and database behavior.

But the principle is simple:

The search language has its own contract.

A field becomes searchable because the application deliberately exposes it, not because a similarly named PostgreSQL column happens to exist.

That also gives the database schema room to evolve without necessarily breaking the query syntax users already know.

Then the dataset grew

The most complicated-looking part of this architecture wasn't where I encountered the main performance problem.

The parser worked.

Recursive expressions worked.

Structured filters worked.

The problem appeared somewhere much less exotic:

free-text search.

When the dataset was smaller, the existing implementation performed well enough.

Then production data accumulated.

The same kind of free-text search now had increasingly more data to work through.

The code hadn't necessarily regressed.

The workload had changed.

That's an important distinction.

A query that behaves perfectly well at one data volume can have very different characteristics as that volume grows.

So I didn't start by optimizing the parser.

I started by measuring the database path.

Measure before changing the architecture

I wanted to understand what PostgreSQL was actually doing.

EXPLAIN ANALYZE was part of that investigation.

EXPLAIN ANALYZE
SELECT ...

I was looking for answers to concrete questions:

How many rows are being examined?
Are we scanning more data than necessary?
Are the indexes I expect actually being used?
Which part of the generated condition is expensive?
Where is execution time being spent?
How does the execution plan behave as the dataset grows?

This distinction mattered.

The system contained sophisticated application code, but optimizing the most complicated-looking code wouldn't help if PostgreSQL was doing the expensive work.

Optimize what the measurements tell you is expensive, not what looks complicated.

Why GIN fit the workload

Structured filters and free text have different access patterns.

A B-tree index is a natural fit for many structured conditions:

WHERE status = 'OPEN'

Free-text search asks a different kind of question:

Which records contain these searchable terms?

That's where an inverted index becomes useful.

PostgreSQL already provides this capability through GIN — Generalized Inverted Index.

At a high level, an inverted index maintains relationships between searchable terms and the records containing them.

payment ─────► Record 12
        ├────► Record 48
        └────► Record 91

approval ────► Record 12
         └───► Record 103

invoice ─────► Record 27
        └────► Record 91

A simplified PostgreSQL example might look like:

CREATE INDEX idx_records_search
ON records
USING GIN (
  to_tsvector('english', searchable_text)
);

with a corresponding full-text condition:

SELECT id, title
FROM records
WHERE
  to_tsvector('english', searchable_text)
  @@ plainto_tsquery('english', 'payment approval');

The production implementation was more involved because free text could appear alongside structured conditions and recursively nested Boolean expressions.

Architecturally, though, the responsibilities remained separate:

                     Search AST
                         │
               ┌─────────┴─────────┐
               ▼                   ▼
         Structured            Free Text
          Conditions              Search
               │                   │
               ▼                   ▼
          Appropriate             GIN
           indexes               index
               │                   │
               └─────────┬─────────┘
                         ▼
                     PostgreSQL

The query language remained expressive while the expensive free-text path could be optimized independently.

From roughly 40ms to 12ms

After optimizing the free-text path around the appropriate PostgreSQL indexing strategy, measured search latency moved approximately from:

Before       After
 ~40ms   →    ~12ms

That's roughly a 70% reduction for the workload we measured.

The production dataset contained more than 20,000 records at the time.

That result needs context.

It does not mean:

Add GIN and PostgreSQL becomes 70% faster.

Database performance depends on schema, data distribution, query shape, hardware, cache state, and workload.

The useful part is the process:

Observe
   ↓
Measure
   ↓
Inspect the execution plan
   ↓
Understand the access pattern
   ↓
Choose the appropriate index
   ↓
Measure again

GIN fit our access pattern.

The decision came from the workload, not the other way around.

Why I didn't introduce Elasticsearch

Once free-text search became a performance discussion, a dedicated search engine was an obvious option to consider.

Elasticsearch could handle this kind of search.

But capability alone wasn't enough reason for me to introduce another system.

PostgreSQL was already part of the production architecture and remained the source of truth.

Keeping search there meant the architecture remained roughly:

              Application
                   │
                   ▼
              PostgreSQL
             ┌─────┴─────┐
             │           │
       Structured     Free Text
         Search         Search
             │           │
        Appropriate     GIN
         indexes        index

Introducing another search datastore changes that:

                   Application
                        │
                ┌───────┴───────┐
                ▼               ▼
           PostgreSQL      Search Engine
                │               ▲
                └───── Sync ────┘

That synchronization arrow looks small on an architecture diagram.

Operationally, it isn't.

It introduces concerns around:

data synchronization
eventual consistency
failed indexing operations
retry and replay
index rebuilding
mappings
monitoring
deployments and upgrades
infrastructure cost
another failure domain

None of those make Elasticsearch a bad choice.

They're simply part of the cost of owning another system.

For our workload, PostgreSQL was already there, GIN matched the free-text access pattern, and the resulting performance satisfied the requirements.

Adding another datastore would have increased the operational surface without solving a problem we still had.

So I didn't add one.

GIN was an architectural decision, not just an index

It's easy to summarize the change as:

I added a GIN index and made search faster.

That's technically part of what happened.

But the architectural decision was larger.

I effectively had three directions:

                  Growing Search Cost
                         │
            ┌────────────┼────────────┐
            ▼            ▼            ▼
         Leave it     Optimize     Introduce
          as-is       PostgreSQL   Search Engine
                          │
                          ▼
                         GIN

Doing nothing wasn't going to age well.

A dedicated search engine could solve the problem, but it would introduce another operational component.

Optimizing PostgreSQL gave me a middle path:

Use more of the capabilities of the system we already operate before introducing another one.

That kept PostgreSQL as the source of truth.

No search synchronization pipeline.

No additional datastore.

No additional operational dependency.

And it met the performance requirements.

The question wasn't which technology was more powerful.

The question was which architecture introduced the right amount of complexity for the problem we actually had.

When I would introduce a dedicated search engine

This isn't an argument that PostgreSQL should replace Elasticsearch.

I'd revisit the architecture if the requirements started demanding things such as:

sophisticated relevance ranking
advanced fuzzy matching and typo tolerance
complex language-specific analysis
significantly larger search workloads
independent scaling of search
complex search aggregations
search-specific availability requirements

At that point, specialized search infrastructure may provide enough value to justify its operational cost.

The useful question isn't:

PostgreSQL or Elasticsearch?

It's:

Have the requirements crossed the point where owning another system is justified?

For us, they hadn't.

Leaving room to evolve without building the future

There was another reason I was comfortable keeping PostgreSQL.

The query language wasn't directly coupled to it.

The boundary looked roughly like:

User Intent
     │
     ▼
Search Expression
     │
     ▼
    AST
     │
     ▼
Validation
     │
     ▼
PostgreSQL Compiler
     │
     ▼
PostgreSQL

PostgreSQL was the current execution strategy.

It wasn't the definition of the search language.

If the requirements eventually justify another backend, there's a natural architectural seam:

                       AST
                        │
                ┌───────┴───────┐
                ▼               ▼
          PostgreSQL        Dedicated
           Compiler       Search Compiler

I wouldn't implement that second compiler today.

That's an important distinction.

Designing a boundary is useful. Building hypothetical infrastructure isn't.

What I'd do differently today

If I were starting this feature again, I'd formalize the query language earlier.

Search requirements tend to grow incrementally.

payment

becomes:

status:open

then:

payment AND status:open

then:

payment AND (status:open OR status:pending)

and eventually:

(
  payment
  OR (
    refund
    AND (status:open OR status:pending)
  )
)
AND NOT owner:system

At some point, you've created a language without explicitly deciding to create one.

Once structured fields, Boolean operators, and grouping start appearing in the requirements, I'd define the boundaries early:

Grammar
   ↓
Tokenizer
   ↓
Parser
   ↓
AST
   ↓
Validation
   ↓
Compilation
   ↓
Execution

That makes everything that follows easier to reason about and test.

What I took away from building it

Looking back, what appeared to be one feature was really three different engineering problems.

Expressiveness

Free text gradually became a query language:

free text
key:value
AND / OR / NOT
parentheses
recursive expressions

That required treating search as structured input:

tokenize → parse → AST → validate → compile

Usability

The query language could be powerful without becoming a prerequisite for using search.

The column-level filter builder exposed controls appropriate to the underlying data—text inputs, date ranges, multi-selects, and Boolean conditions—and generated the same search representation underneath.

Two interfaces. One search model.

The complexity stayed in the system instead of being pushed onto every user.

Scale

The part that looked complicated wasn't the part that eventually became expensive.

As the dataset grew, free-text search became the bottleneck.

The response wasn't to rewrite the parser or immediately introduce another datastore.

It was to measure the query path, inspect what PostgreSQL was doing, and optimize the access pattern that was actually expensive.

For our workload, a GIN-backed strategy brought measured search latency from roughly 40ms to 12ms while allowing PostgreSQL to remain the source of truth.

Could a dedicated search engine become the right architecture later?

Absolutely.

But I didn't want to pay the synchronization, consistency, infrastructure, and operational costs of another system before the requirements justified them.

That's probably the main thing I took away from building this:

Good architecture isn't about eliminating complexity. It's about putting complexity in the right place—and only introducing it when the problem actually requires it.

Your Dog Has Thoughts. I Built an AI to Translate Them 🐶

L Anil Kumar Singha — Fri, 14 Aug 2026 12:03:00 +0000

This is a submission for the Weekend Challenge: Dog Days Edition.

What I Built

I built Dog Mind, a playful AI-powered web app that turns a dog photo into an entertaining interpretation of the dog’s mood, visible body language, personality signals, and imaginary inner monologue.

Upload a photo and Dog Mind generates:

A cautious breed or dog-type guess
A mood and confidence score
Happiness, energy, and mischief ratings
Observations based on visible body-language signals
A short personality summary
A funny, family-friendly imaginary thought
A matching voice personality

After the analysis, users can hear the dog’s imagined thought spoken aloud, ask up to three follow-up questions, and download or share the final result card.

No dog photo available? The Try a sample dog button opens a pre-generated experience without consuming an AI request.

Dog Mind is made for entertainment. It does not claim to read a dog’s mind or provide veterinary or behavioral advice.

Demo

🐶 Live app: dog-mind-eight.vercel.app

To try it:

Upload a JPG, PNG, or WebP photo of a dog.
Select Analyze my dog.
Review the dog’s mood, signals, and imaginary inner monologue.
Select Hear this dog’s voice.
Ask the dog up to three playful questions.
Share or download the result card.

You can also select Try a sample dog for an instant preview.

Code

The complete source code is available on GitHub:

🐙 github.com/anilloutombam/dog-mind

How I Built It

Dog Mind uses:

Next.js
React
TypeScript
Tailwind CSS
Google Gemini
ElevenLabs
Zod
pnpm
Vercel

Multimodal dog analysis with Google Gemini

When a user uploads a photo, the browser sends it to a server-side Next.js route as multipart form data.

Before contacting Gemini, the server checks:

The declared MIME type
The file size
The actual binary image signature

This prevents renamed or unsupported files from being accepted based only on their extensions.

Gemini first determines whether the primary subject is a dog. For a valid dog photo, it returns structured JSON containing:

breedGuess
breedConfidence
dogSize
voiceStyle
mood
confidence
signals
observations
thought
summary

The shared Zod schema validates the complete response before it reaches the interface. It also enforces the same character and number limits expected by downstream features.

The prompt asks Gemini to interpret only clearly visible signals, avoid medical claims, make cautious breed guesses, and keep the imaginary thought short and family-friendly.

Giving the dog a voice with ElevenLabs

Dog Mind sends the generated inner monologue to ElevenLabs only after the user selects Hear this dog’s voice.

Gemini recommends one of six controlled voice personalities:

Bright
Warm
Bold
Dramatic
Gentle
Gruff

Each personality maps to approved ElevenLabs stability, style, and speed settings.

The voice choice is inspired by the dog’s visible size, expression, and energy. It is a playful creative decision, not a scientific claim about breed behavior.

Generated audio is cached by text and voice personality. Replaying the same voice can reuse the existing audio, while New take deliberately requests a fresh performance.

The audio cache uses a fixed size and removes older entries so it cannot grow indefinitely.

Ask Your Dog

After the initial analysis, users can continue the imaginary conversation by asking the dog up to three questions.

The follow-up request sends only the established dog persona and the new question. It does not upload the image again.

Gemini also acts as a topic guard. It rejects:

Unrelated questions
Role-changing instructions
Prompt-injection attempts
Requests to reveal internal prompts

Dog health questions receive no diagnosis or treatment advice.

The three-question limit is enforced on the server instead of relying only on a disabled client button. Conversation records expire after 24 hours, expired entries are pruned, and the process-local store has a maximum size.

The client persists the successful question count and synchronizes it between browser tabs. When the limit is reached, the API returns a machine-readable terminal state so the interface hides the form instead of displaying a misleading retry button.

Caching repeated image analysis

Gemini API requests are valuable, especially while working within free-tier limits.

Dog Mind calculates a SHA-256 digest of each uploaded image and uses it as a cache key. If the same image is analyzed again during the browser session, the validated result can be reused without another Gemini request.

Cached values are validated when they are read and written. Invalid stored values are removed instead of being trusted.

Handling stale requests

A user can select another image, reset the experience, or open the sample result while an earlier request is still running.

To prevent an old response from replacing a newer state, Dog Mind:

Assigns a generation number to each analysis
Cancels superseded requests with AbortController
Checks the generation after asynchronous operations
Discards responses that no longer belong to the active image

This keeps the UI consistent even when users move quickly between states.

Friendly failure and quota handling

AI APIs can fail because of temporary capacity, rate limits, exhausted quotas, network problems, or invalid responses.

Dog Mind provides:

Friendly Gemini 429 messages
Retry timing from response metadata
Live retry countdowns
Disabled retry controls during cooldowns
Retry actions for analysis, voice generation, and dog chat
Provider timeouts
Safe request IDs for diagnostics
Graceful handling for non-dog images

The app also includes a pre-generated sample so visitors can still explore the main interface when the AI provider is temporarily unavailable.

Security and privacy

Security was an important part of the implementation:

Gemini and ElevenLabs credentials remain server-side
Images are checked in both the browser and server
Binary signatures are verified
Uploads are limited to 5 MB
AI responses are schema-validated
Client errors do not reveal credentials or stack traces
Follow-up prompts receive minimal dog context
API routes use request throttling and provider timeouts
Security headers prevent framing and MIME sniffing
Camera, microphone, and location access are disabled

Building the experience

I wanted Dog Mind to feel playful without becoming confusing.

The interface includes:

Drag-and-drop uploads
Full-image previews without cropping
Animated analysis progress
A running dog progress indicator
Rotating dog facts
Screen-reader announcements
Reduced-motion support
Responsive layouts
Native sharing where supported
Downloadable square result cards

The codebase uses a feature-first structure. Route files compose the page, feature modules own the workflow, and server utilities centralize validation, throttling, and safe error handling.

Interesting Challenges

Keeping playful AI output honest

Dog Mind creates a humorous interpretation of a dog’s expression, but the result should never be confused with a diagnosis or a factual reading of the animal’s thoughts.

The prompts, interface copy, and error messages consistently describe the output as an imaginary interpretation based on visible clues.

Coordinating multiple AI services

Gemini and ElevenLabs have different request formats, limits, errors, and response types.

Keeping both integrations behind server routes gave the browser one consistent application API while protecting provider credentials.

Designing useful recovery states

A failed request should not leave the user stuck.

Retry buttons, cooldown countdowns, cached results, audio reuse, stale-request cancellation, and the sample experience all help users continue without restarting the entire flow.

Prize Categories

Best Use of Google AI

Google Gemini powers the core multimodal experience. It examines dog photos, identifies visible body-language signals, produces structured mood data, creates the imaginary inner monologue, recommends a controlled voice personality, and handles guarded follow-up conversations.

Best Use of ElevenLabs

ElevenLabs transforms the dog’s imaginary thought and optional follow-up replies into expressive voice performances. Controlled presets adapt stability, speed, and expression to complement the visual analysis.

What I Learned

Dog Mind began with a funny question:

What if AI could translate the look your dog gives you?

Building it showed me that playful AI products still need careful engineering.

Schema validation, file-signature checks, caching, rate-limit handling, stale-request protection, prompt-injection resistance, accessibility, and honest disclaimers made the experience more reliable and enjoyable.

The best AI experience is not only about generating an answer. It is also about presenting that answer with the right personality, boundaries, and recovery path when something goes wrong.

Thanks for checking out Dog Mind! 🐾

Fixing an Infinite Loading State in the npmx Code Browser

L Anil Kumar Singha — Mon, 03 Aug 2026 08:23:15 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

npmx is an open-source package explorer for the npm ecosystem. It helps developers inspect package metadata, releases, dependencies, documentation, comparisons, and published source files.

Bug Fix or Performance Improvement

The npmx code browser has a fallback for files that exceed its supported display size. It should show a “File too large” warning and provide an option to open the raw file.

Instead, selecting an oversized file left the page displaying its loading state indefinitely.

The issue can be reproduced here:

https://npmx.dev/package-code/@types/vscode/v/1.118.0/index.d.ts

The corrected behaviour can be verified on the PR preview:

https://npmx-h3s403v0g-npmx.vercel.app/package-code/@types/vscode/v/1.118.0/index.d.ts

Code

GitHub issue: https://github.com/npmx-dev/npmx.dev/issues/2732

Pull request: https://github.com/npmx-dev/npmx.dev/pull/3120

The production fix is one line:

if (isFileTooLarge.value) return false

It was added to the page’s loading-state calculation:

const isLoading = computed<boolean>(() => {
  if (!isViewingFile.value) {
    return treeStatus.value !== 'success' && treeStatus.value !== 'error'
  }

  if (isFileTooLarge.value) return false

  return !fileStatus.value || fileStatus.value === 'pending' || fileStatus.value === 'idle'
})

My Improvements

The page already knew when a selected file exceeded the size limit. In that situation, it intentionally skipped the file-content request.

Because the request never started, its status remained idle. The loading logic treated that status as if the file were still waiting to load, so the loading skeleton prevented the existing fallback from appearing.

The new condition makes the page stop reporting a loading state when the file is already known to be too large. This allows the existing warning and raw-file action to render without changing the server limit or downloading unnecessary content.

I also added a regression test that verifies:

The large-file warning is displayed.
The page does not remain in its loading state.
The file-content endpoint is not called.
The raw-file action points to the correct jsDelivr URL.

The code change is small, but it fixes an important state-handling edge case: an idle request is not always waiting to begin. Sometimes the application has intentionally decided that it should not run.

If you're interested in more of my open-source work and engineering projects, you can explore my portfolio or follow my work on GitHub.

Fixing a Search Race Condition in npmx

L Anil Kumar Singha — Sat, 01 Aug 2026 07:55:07 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

npmx is a modern browser for the npm registry. It provides package search, version timelines, dependency information, comparisons, and other tools for exploring npm packages.

I've been contributing to npmx recently, mostly around search behavior and edge cases. One of those contributions started with a particularly interesting symptom:

The search failed the first time, but worked after a refresh.

Bug Fix or Performance Improvement

The bug was reported in issue #2617.

The reproduction was quite specific.

With instant search disabled and a saved page size of 50 or higher:

Open the search page.
Search for a package.
No package results appear.
The organization suggestion can still appear.
Refresh the exact same page.
The package results suddenly show up.

Same query. Same page size. Same application.

The refresh behavior was the interesting part.

If the packages didn't exist, refreshing shouldn't make them appear. And if the search request itself was fundamentally broken, I'd expect the second attempt to fail too.

That pointed away from the search data itself and toward what was happening during the initialization of the page.

Following the timing

npmx stores the user's preferred search page size locally.

On the first navigation to the search page, however, the initial search could begin before that saved preference had finished loading.

The sequence looked roughly like this:

Search page opens
        ↓
Initial search starts
(page size = 25)
        ↓
Saved preference loads
        ↓
Page size changes to 50
        ↓
fetchMore() runs
        ↓
Initial search is still pending

Individually, none of these operations were wrong.

The problem was when they happened relative to each other.

fetchMore() could run while the initial Algolia search was still pending.

At that moment, the search result hadn't arrived yet. fetchMore() could therefore read the temporary empty response and store that value in the search cache.

Then the original search completed with the real package results.

But it was too late.

The empty cached value could take priority, leaving the UI showing no packages even though the search had successfully returned them.

That also explained why refreshing appeared to magically fix the problem.

It wasn't magic.

The initialization timing had changed.

Code

The fix is in npmx-dev/npmx.dev#3109.

Instead of allowing fetchMore() to continue while the initial search is unresolved, it now checks whether that search is still pending and waits for it:

if (asyncData.status.value === 'pending') {
  await asyncData.refresh({ dedupe: 'defer' })
}

The important detail here is:

dedupe: 'defer'

I didn't want fetchMore() to cancel the search that was already running and replace it with another request.

It needed to join the existing in-flight request.

So the flow changed from something like:

Initial search ────────────────► package results
        │
        └── fetchMore()
                ↓
          reads empty state
                ↓
          empty value cached

to:

Initial search ────────────────► package results
                                      ↓
                               fetchMore() continues
                                      ↓
                               results preserved

It's a small change in code, but it changes the ordering guarantee between the two asynchronous operations.

My Improvements

The main fix was making fetchMore() wait for the pending initial search before consuming its result.

But a race-condition fix also needs a test that can reliably reproduce the timing that caused it.

Otherwise, the test might pass simply because the operations happened in a convenient order that particular time.

So I added a regression test that deliberately recreates the problematic sequence.

The test:

Starts the initial Algolia search.
Keeps that request pending.
Changes the requested page size.
Triggers the additional result-loading path.
Resolves the original search.
Verifies that the completed package results are preserved.

That was important because the test isn't relying on the race condition happening naturally.

It controls the timing.

After the fix, users with a saved page size of 50 or higher get their package results on the first search without needing to refresh the page.

What I took away from this bug

What made this issue interesting wasn't the amount of code required to fix it.

It was the symptom:

It doesn't work the first time, but refreshing fixes it.

That can be a useful debugging clue.

When persisted client state, initialization, caching, and asynchronous requests interact, a refresh can change the order in which those operations happen.

In this case, the individual pieces were working.

The initial search worked.

The saved preference worked.

fetchMore() worked.

The problem only appeared when they ran in a particular order.

The final fix wasn't to make the search faster or add another request.

It was simply to make one asynchronous operation respect another operation that was already in progress.

Sometimes fixing a race condition is less about doing more work and more about making sure the work you already have happens in the right order.

If you're interested in more of my open-source work and engineering projects, you can explore my portfolio or follow my work on GitHub.

Midnight Ramen: A Rainy CSS Art Love Letter to Comfort Food

L Anil Kumar Singha — Fri, 31 Jul 2026 15:29:29 +0000

This is a submission for Frontend Challenge - Comfort Food Edition, CSS Art.

Inspiration

My inspiration was a warm bowl of ramen on a quiet, rainy night—the kind of meal that feels comforting before you even take the first bite.

I wanted to capture more than the food itself, so I created a complete midnight ramen-shop scene. The steaming bowl is surrounded by a glowing lantern, falling rain, a handwritten order slip, shelves of ingredients, and a tiny shop cat peeking over the counter.

Demo

You can also explore the source code on GitHub.

Journey

I created the illustration using HTML and CSS, without image assets or JavaScript. The bowl, broth, noodles, egg, chashu pork, nori, narutomaki, mushrooms, scallions, lantern, window, furniture, and cat are all composed from regular HTML elements.

The visual details rely on:

Layered CSS gradients
Borders and border radii
Pseudo-elements
Transforms and clipping
CSS custom properties
Responsive media queries
Subtle keyframe animations

The scene also includes CSS-only interactions. The chili-oil control changes the appearance of the broth and introduces small animated spice sparks. A compact day/night control changes the window, lantern, steam, and surrounding color palette without JavaScript.

The ingredient labels can be revealed with a mouse or keyboard. I also included prefers-reduced-motion support so visitors who disable animation receive a calmer version of the scene.

The most challenging part was creating depth while keeping the markup understandable. The ramen bowl contains several overlapping layers, and each topping needs to remain recognizable without using an image. Careful positioning, contrast, shadows, and restrained animation helped the individual pieces feel like one cohesive illustration.

I am particularly proud that the finished project requires only two files for the artwork: index.html and style.css. It can run directly in a browser without a framework, build process, or external JavaScript.

This project reminded me that CSS is not only a styling language—it can also be an expressive illustration medium.

Source

The complete source is available on GitHub.

The project is shared under the MIT License.

If you'd like to see more of what I'm building, you can explore my portfolio or find me on GitHub.

Fixing Exact Package Search Relevance in npmx

L Anil Kumar Singha — Fri, 31 Jul 2026 10:27:09 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

npmx is an open-source alternative interface for exploring packages from the npm registry. It provides package details, documentation, version history, dependencies, search tools, and other information for JavaScript developers.

Bug Fix or Performance Improvement

I worked on issue #2978, which was reported by another contributor.

When Algolia was selected as the search provider, the page displayed “Relevance” as the active sorting option. However, an exact package-name match did not always appear first.

For example, searching for napkin could show other packages above the exact match. Switching to “Downloads/wk” and then back to “Relevance” changed the results and moved napkin to the top.

I reproduced this behavior locally before investigating the cause.

Code

Issue #2978
Pull request: https://github.com/npmx-dev/npmx.dev/pull/3103

Before and after

Before

private-user-images.githubusercontent.com

After

private-user-images.githubusercontent.com

My Improvements

npmx already made an additional Algolia request to check whether a package with the exact searched name existed.

However, this request retrieved only the package name and used the result only as an existence check. If the exact package was missing from the initial batch of results, the application knew it existed but did not have enough information to display it.

I updated the exact-package request to retrieve the complete package information. When the returned package name matches the searched name, it is placed at the beginning of the results.

Before adding it, the code removes any existing occurrence of the same package. This prevents duplicate results.

I also added two safety checks during review:

A missing Algolia hits array falls back to an empty array.
A returned hit is promoted only when its name matches the requested package.

Finally, I added a regression test that supplies a regular search result and a separate exact-package result. The test verifies that the exact package is detected and placed first.

I validated the change by running the focused Nuxt tests, TypeScript checks, lint and formatting checks, and by testing the behavior manually in the local UI.

After the fix, an exact package-name match appears at the top immediately when “Relevance” is selected.

Fixing a False “TypeScript Types Removed” Event in npmx

L Anil Kumar Singha — Fri, 31 Jul 2026 08:43:14 +0000

This is a submission for DEV's Summer Bug Smash: Clear the Lineup powered by Sentry.

Project Overview

npmx is an open-source browser for the npm registry. It helps developers explore package metadata, versions, dependencies, documentation, and other information.

I worked on npmx issue #2791, which reported an incorrect event in the package-version timeline. npmx could say that a package had removed its TypeScript types even though valid declaration files were still included in the published package.

My fix is available in npmx PR #3102.

Bug Fix or Performance Improvement

A package can expose TypeScript declarations explicitly through fields such as types or typings. It can also provide declarations implicitly by placing them beside its JavaScript entry points.

For example:

dist/index.mjs
dist/index.d.mts

TypeScript can use dist/index.d.mts even when package.json does not contain a top-level types field.

npmx already understood this pattern on its package-analysis page. However, the timeline endpoint used hasBuiltInTypes(), which only checked package metadata.

This caused the two parts of npmx to disagree:

The package page correctly showed “Types included.”
The timeline incorrectly showed “TypeScript types removed.”

Code

The fix keeps the fast metadata check as the first step. It performs the more expensive published-file analysis only for visible versions that could be part of a type-removal sequence.

The latest implementation selects every untyped version that has an older typed version somewhere earlier in the package’s history:

const possibleTypeRemovals = visibleVersions.filter(version => {
  if (version.hasTypes) return false

  const versionIndex = allVersions.indexOf(version)
  return allVersions
    .slice(versionIndex + 1)
    .some(previousVersion => previousVersion.hasTypes)
})

Checking the full sequence is important. Consider these versions:

1.0.0 — explicit types field
2.0.0 — colocated .d.mts declaration
3.0.0 — colocated .d.mts declaration

An earlier version of my fix analyzed only 2.0.0, because it was directly beside the metadata transition. The latest version also analyzes 3.0.0 and any other affected version in the sequence.

For each candidate, the timeline fetches the package metadata and published file tree. It then reuses the project’s existing analyzePackage() utility:

const { pkg, typesPackage, files } =
  await fetchPackageWithTypesAndFiles(packageName, version.version)

const analysis = analyzePackage(pkg, {
  typesPackage,
  files,
})

if (analysis.types.kind === 'included') {
  version.hasTypes = true
}

If the additional lookup fails, the endpoint preserves the original metadata-only result instead of failing the complete timeline request.

Tests

I started by running the existing test suite and confirming that all 1,716 tests passed before making changes.

I then added a regression test with three package versions:

1.0.0 declares types explicitly.
2.0.0 publishes index.mjs and index.d.mts.
3.0.0 also publishes index.mjs and index.d.mts.

The test verifies that both implicit versions are analyzed and that all three versions report TypeScript types.

expect(fetchPackageWithTypesAndFilesMock)
  .toHaveBeenCalledWith('my-pkg', '2.0.0')

expect(fetchPackageWithTypesAndFilesMock)
  .toHaveBeenCalledWith('my-pkg', '3.0.0')

expect(result.versions).toHaveLength(3)
expect(result.versions[0]?.hasTypes).toBe(true)
expect(result.versions[1]?.hasTypes).toBe(true)
expect(result.versions[2]?.hasTypes).toBe(true)

I also added a genuine-removal test. In that case, the newer version publishes index.mjs without a matching declaration file, so hasTypes correctly remains unset.

The final validation included:

TypeScript type checking
Repository lint checks
The focused timeline test suite
All 82 unit-test files
The complete unit-test suite with the new regression coverage
GitHub continuous-integration checks

My Improvements

The final change improves the timeline in several ways:

It recognizes colocated .d.mts declarations.
It reuses the existing package-analysis implementation.
It handles consecutive implicit-type versions after a metadata transition.
It preserves genuine “types removed” events.
It avoids failing the entire timeline when an additional file lookup is unavailable.
Its tests verify array length before using optional indexed access.

What I Learned

The main lesson was that package metadata does not always describe everything inside a published npm package. Removing a types field does not necessarily mean that TypeScript support was removed.

I also learned why regression tests should cover a sequence rather than only one transition. Testing just 1.0.0 → 2.0.0 missed the behavior of 3.0.0. Extending the test revealed that every affected version after the transition needed file-aware analysis.

Review feedback also improved the test quality. I replaced non-null assertions on indexed versions with an explicit length assertion and optional access.

Most importantly, I reused npmx’s existing analysis logic instead of implementing another declaration-detection algorithm. This keeps the package page and timeline consistent.

Before and After

Before:

1.0.0 — TypeScript types included
2.0.0 — TypeScript types removed
3.0.0 — TypeScript types not detected

This could appear even when 2.0.0 and 3.0.0 contained valid .d.mts declarations.

After:

1.0.0 — TypeScript types included
2.0.0 — TypeScript types included
3.0.0 — TypeScript types included

A release that genuinely removes both the metadata and the declaration files is still treated as a type removal.

Pull Request

The implementation, tests, and review history are available in npmx PR #3102.

Miso & Memory: A CSS-Illustrated Ramen Landing Page for Rainy Nights

L Anil Kumar Singha — Fri, 31 Jul 2026 05:08:24 +0000

This is a submission for Frontend Challenge — Comfort Food Edition, Perfect Landing.

What I Built

I built Miso & Memory, a landing page for an imaginary late-night ramen counter.

The concept is inspired by the feeling of coming home to a hot bowl after a long, rainy day: slow broth, springy noodles, warm light, and the good kind of quiet.

The visual direction combines editorial typography, an earthy restaurant-inspired palette, Japanese print-inspired details, and a steaming ramen bowl illustrated with custom CSS.

The landing page includes:

A responsive CSS-art ramen hero
Animated steam and a scrolling kitchen-principles banner
A curated menu of comfort bowls
The story behind the imaginary restaurant
An interactive “build your comfort bowl” experience
Dynamic topping selection and price calculation
Keyboard-friendly controls and accessible labels
Visible selected and confirmation states
Reduced-motion support
Responsive mobile, tablet, and desktop layouts

Demo

Open Miso & Memory

Source Code

View the source code on GitHub

Journey

I wanted this landing page to feel handcrafted rather than relying on conventional restaurant photography.

The hero illustration is constructed from CSS shapes, borders, clipping paths, shadows, and animation. The bowl contains noodles, a jammy egg, mushrooms, greens, narutomaki, chopsticks, and rising steam.

One of my favorite parts is how the illustration and interface share the same visual language. The rust-red sun becomes the primary action color, broth-inspired gold highlights selected toppings, and forest green carries through the typography and bowl outlines.

I also wanted the page to be functional rather than purely decorative. Visitors can choose from three bowls, add or remove toppings, see the total update immediately, and save their selection.

The interactive controls use semantic buttons, aria-pressed states, and a status message when the bowl is saved. The page also respects prefers-reduced-motion for visitors who prefer a calmer experience.

The project is built with React, TypeScript, Vinext, Vite, and custom CSS. It is deployed publicly on Cloudflare Workers.

What I Learned

This project reminded me how much atmosphere can be created with a restrained color palette, expressive typography, and carefully composed CSS.

I also learned more about:

Constructing detailed illustrations from CSS primitives
Balancing animation with accessibility
Designing responsive editorial layouts
Building keyboard-friendly selection controls
Deploying a Vinext application and its static assets to Cloudflare Workers

AI Assistance

I used Codex as a collaborative development tool for design exploration, implementation, accessibility improvements, troubleshooting, and deployment guidance.

I reviewed and refined the project’s creative direction, interface, content, and interactions before submitting it. The social-preview image was created using an AI image-generation tool. The ramen illustration visible in the website’s hero section is implemented with CSS.

License

The source code is available under the MIT License.

Thanks for stopping by. Your seat at the counter is waiting. 🍜

DEV Community: L Anil Kumar Singha

Incident Context: tracing production failures without guessing

What I Built

The Problem

The Solution

Why This Matters

How I Used Sanity

The Demo

Code

Runtime Architecture

Structured Output

Production Safeguards

Testing the MCP Dependency

What I Learned

I Injected the Same Failures Into 5 MCP SDKs. Here’s What I Found.

The test setup

Finding #1: HTTP disconnect recovery differed between TypeScript and Python

Finding #2: rmcp accepted a malformed JSON-RPC response

Finding #3: Five SDKs survived a duplicate response, but exposed it differently

TypeScript made the duplicate visible

The other four didn't expose a call-level error

A "pass" isn't always the whole result

Why test the request after the failure?

These aren't necessarily SDK bugs

What I'm testing next

Reproducing the tests

What Happens When an MCP Tool Call Never Returns?

Reproducing a hang

Hang vs delay

A timeout only tells you what the client saw

What should happen after the timeout?

Keeping the failure deterministic

Try it

Introducing MCP Failure Lab: Testing MCP Beyond the Happy Path

What is MCP Failure Lab?

Why build this?

Current architecture

What comes next?

Contributions are welcome

How I Designed a Production Global Search System on PostgreSQL

One search box, different levels of precision

The UI could write the query for you

Two interfaces, one search model

When search became a language

Treating search like a small compiler

From a query string to structured data

Supporting N-level nested search

Search fields are an API, not database columns

Then the dataset grew

Measure before changing the architecture

Why GIN fit the workload

From roughly 40ms to 12ms

Why I didn't introduce Elasticsearch

GIN was an architectural decision, not just an index

When I would introduce a dedicated search engine

Leaving room to evolve without building the future

What I'd do differently today

What I took away from building it

Expressiveness

Usability

Scale

Your Dog Has Thoughts. I Built an AI to Translate Them 🐶

What I Built

Demo

Code

How I Built It

Multimodal dog analysis with Google Gemini

Giving the dog a voice with ElevenLabs

Ask Your Dog

Caching repeated image analysis

Handling stale requests

Friendly failure and quota handling

Security and privacy

Building the experience

Interesting Challenges

Keeping playful AI output honest

Coordinating multiple AI services

Designing useful recovery states

Prize Categories

Best Use of Google AI

Finding #2: `rmcp` accepted a malformed JSON-RPC response