What I Built

Demo

How I Used Bright Data’s Infrastructure

Performance Improvements

This is a follow-up to a Cursor Forum feature request I posted in late April 2026: “we already have the mailbox (files), we just need the doorbell.” Colin recommended the Agent SDK. We built CodeFlow on top of it. This is what happened 18 days later.

I. Three stages — three fundamentally different things

Stage One: OCR + CDP (passive scanning)

FCoP’s early multi-agent workflow ran on a Python script that used OCR + CDP (Chrome DevTools Protocol) to simulate human clicks on the Cursor UI, forcing agents to “see” new tasks. It polled every few seconds. The screen had to stay on. The window couldn’t be obscured.

This was passive scanning. The agent wasn’t notified — it was pushed in front of a task by brute force. This wasn’t communication. It was surveillance.

Stage Two: The SDK pipe worked — but the agent could only “chat”

CodeFlow replaced OCR/CDP with the Cursor Agent SDK (@cursor/sdk): InboxWatcher watches for files landing, agent.send() delivers tasks directly to the agent. Real notification. No more scanning.

But one line in every session JSON stayed the same:

"tool_calls_count": 0

The agent received the message, “replied” with something, and exited. No files written. No reports created.

The reason: MCPInjector was in mode="stub" — no actual MCP server was injected into the SDK. The agent had no write_report, no write_task. No tools means no action. Only chat.

The doorbell rang. The agent answered with empty hands.

Stage Three: MCP injection — the first real communication

Passive scanning → real notification → real notification + tool calls + filed report.

tool_calls_count: 0 → 7 is not just a number changing — it’s the qualitative shift from “being pushed along” to “acting on its own.”

II. Finding the door

The key was reading the Cursor SDK type definitions.

In agent.d.ts, SendOptions had an easily-overlooked field:

interface SendOptions {
    model?: ModelSelection;
    mcpServers?: Record<string, McpServerConfig>;  // ← here
    local?: { force?: boolean };
    // ...
}

agent.send(text, options) can receive MCP server configuration at call time. No need to refactor anything. Every send, just pass the MCP server config directly.

At the same time, fcop-mcp‘s entry point confirmed the other half:

# python -m fcop_mcp → stdio MCP server
# uses FCOP_PROJECT_DIR environment variable to locate the project root

Solution: in _buildSendOptions(), inject fcop-mcp as a stdio MCP server.

III. Three changes, one breakthrough

AgentSdkAdapter.ts: Add mcpServers to CursorSdkAdapterOptions; pass it into every agent.send() call.

sdk-factory.ts: Automatically assemble the fcop-mcp stdio configuration:

fcop: {
    type: "stdio",
    command: pythonBin,
    args: ["-m", "fcop_mcp"],
    env: { FCOP_PROJECT_DIR: projectRoot }
}

main.ts: Resolve fcopProjectRoot before building the SDK adapter.

And a fourth change — the easiest to overlook, and equally important:

TaskDispatcher.ts: Before each task dispatch, prepend a role context header to the task text — telling the agent who it is, what tools it has, and that it must follow the FCoP 4-step workflow to completion.

IV. Tools aren’t enough — you also need to know how to use them

If you inject the MCP server but add no role context, the agent might not use the tools. It might describe what files should be written, in natural language, and then exit.

Tool injection solves the “can” problem. Context injection solves the “how” problem — what format, what fields, what protocol.

Only when the agent simultaneously knows “I have a write_report tool” and “FCoP requires me to write a report after completing work — and here’s the exact format and fields” will it actually call the tool and produce a properly structured file.

V. That number

tool_calls_count: 7

On May 13, 2026, at 14:55 UTC+8, session-1-mp3pfym2 completed — the first session in CodeFlow’s history with tool_calls_count > 0.

The agent (DEV-01) called fcop-mcp tools 7 times in 55 seconds and wrote:

fcop/reports/REPORT-20260513-014-DEV-to-PM-hello-world-smoke-task.md

Below is the complete content of that file, archived verbatim, unmodified:

---
report_id: REPORT-20260513-014-DEV-to-PM-hello-world-smoke-task
date: 2026-05-13
from: DEV-01
to: PM
re: TASK-20260509-999-PM-to-DEV
status: DONE
---

Receipt: Hello World — CodeFlow v0.1.0-rc.1 Smoke Task

Task ID: TASK-20260509-999-PM-to-DEVGoal: Verify that CodeFlow v0.1.0-rc.1’s nine-step end-to-end governance loop works correctly.

DEV-01’s self-constructed nine-step verification table:

Status: DONE

No one told it what format to use. It read the protocol, called the tools, and wrote the file.

VI. The first complete cycle

Three things happened together for the first time:

1. Notification received: InboxWatcher detected the task file landing — a real doorbell, not an OCR script simulating a click.

2. Autonomous communication: DEV-01 received the task via the Cursor Agent SDK, understood what FCoP protocol required, and autonomously decided what to do and which tools to call. 7 fcop-mcp tool calls. 55 seconds.

3. Report filed: A complete, protocol-compliant Markdown file appeared in fcop/reports/. Not AI-generated text — a file written autonomously by an agent through protocol-driven tool calls.

Not “the agent can run now.” But: the agent was genuinely notified, genuinely communicated in protocol language, and genuinely wrote the result into a file.

VII. Where it all started

In late April 2026, I posted a feature request on the Cursor Forum:

“Feature request: chat-notify primitive — we already have the mailbox (files), we just need the doorbell”

Colin replied:

“Hi @joinwell52! While not a first-class feature in the IDE, the new Agent SDK might get you partway there today. Agent.create() gives you a long-lived agent with persistent context across multiple .send() calls, and Agent.resume(agentId) lets an external script pick up that same agent later. It can also run locally against your working tree too, not just cloud. Worth a look!”

Agent.create(), Agent.resume(), agent.send() — those three functions became the skeleton of CodeFlow’s entire pipeline. InboxWatcher is the doorbell, FCoP task files are the mail, @cursor/sdk is the postal service.

From a feature-request post to the first tool_calls_count: 7: approximately 18 days.

VIII. FCoP’s own transformation

As the agent transformed, so did FCoP.

FCoP began as a pure text protocol — conventions written in Markdown. Its enforcement relied on reading. With fcop-mcp, FCoP underwent a fundamental change:

Before, agents knew the FCoP spec and decided whether to follow it. Now, the FCoP spec becomes the tools — write_report, write_task, write_issue. Calling the tool is executing the protocol.

This is the leap from specification to infrastructure.

Epilogue: Thank you, Cursor Agent SDK

Long-lived agents: Agent.create() maintains context across multiple .send() calls. PM, DEV, QA, OPS each carry their identity and state across tasks.

External resumability: Agent.resume(agentId) lets InboxWatcher re-enter the same agent when a new task arrives. No amnesia, no cold starts.

Local execution: The SDK runs against your local working tree. FCoP’s file protocol is inherently local — a natural match.

mcpServers injection: agent.send(text, { mcpServers: {...} }) accepts MCP server configuration at call time. This single field unlocked CodeFlow’s entire tool layer.

Together these design choices describe something fundamental: An agent is not a one-shot function. It’s a long-lived entity with identity, memory, and the capacity to be coordinated by external systems.

That’s almost exactly how FCoP defines an agent role.

Thank you to the Cursor team. Thank you, Colin, for that reply.

Related

• FCoP on GitHub — Protocol spec, source, and all essays
• Full essay (GitHub)
• Cursor Forum discussion
• When Agents Learn From Their Own Wreckage — A field report from the same project

*FCoP Maintainers · May 13, 2026

[Tutorial] Building Confidential Tokenized Real Estate on Midnight

Full Source Code: Midnight-dApps/confidential-real-estate

Target audience: Developers building privacy-preserving fintech on the Midnight Network

Tokenizing real estate has been “the next big thing” for nearly a decade. The technology has been ready since the first ERC-20; the regulatory model has always been the blocker. Every public REIT-on-chain attempt has either had to publicly leak shareholder positions (killing institutional adoption) or punt to off-chain custodians (defeating the point of being on-chain).

Midnight changes that. In this tutorial we build a DApp where:

• Property sponsors tokenize a building, issue fractional shares, and pay rental yield each cycle.
• Investors prove ownership and claim rental cashflows without revealing which wallet they are, how many shares they hold, or when they joined the cap table.
• Regulators and auditors can still verify in zero-knowledge that every payout went to a legitimate shareholder and that no double-claims occurred.

Prerequisites

• Node.js v20+
• A Midnight wallet (1AM or Lace) on Preprod
• Some Preprod tNIGHT + tDUST from the faucet
• Docker (we run the proof server locally)
• The compact compiler:

curl --proto '=https' --tlsv1.2 -LsSf 
  https://github.com/midnightntwrk/compact/releases/latest/download/compact-installer.sh | sh

The contract: the privacy bricks

The whole privacy story rests on three Compact primitives:

1. Commitment — a hash of (secretKey, propertyId) that the investor computes off-chain and shares with the sponsor. The sponsor learns nothing useful from it.
2. Merkle tree — the sponsor inserts each commitment into a HistoricMerkleTree<10, Bytes<32>>. Anyone can compute the root, nobody can enumerate leaves.
3. Nullifier — a deterministic hash of (secretKey, propertyId, cycle) that gets inserted into a Set the moment a yield claim is processed. Same investor + same cycle = same nullifier = double-claim is rejected.

Here is the contract heart:

export ledger ownershipCommitments: HistoricMerkleTree<10, Bytes<32>>;
export ledger yieldClaimNullifiers: Set<Bytes<32>>;
export ledger rentalPoolAvailable: Uint<64>;

witness localSecretKey(): Bytes<32>;
witness findOwnershipPath(commit: Bytes<32>): MerkleTreePath<10, Bytes<32>>;

constructor(sponsorSk: Bytes<32>) {
    sponsor = disclose(publicKey(sponsorSk));
}

export circuit issueShare(holderCommit: Bytes<32>): [] {
    const sk = localSecretKey();
    assert(sponsor == disclose(publicKey(sk)), "Not the sponsor");
    ownershipCommitments.insert(disclose(holderCommit));
    totalShares.increment(1);
}

export circuit proveOwnership(propertyId: Bytes<32>): Boolean {
    const sk = localSecretKey();
    const commit = ownershipCommit(sk, propertyId);
    const path = findOwnershipPath(commit);
    assert(
        ownershipCommitments.checkRoot(disclose(merkleTreePathRoot<10, Bytes<32>>(path))),
        "Not an owner of this property"
    );
    return disclose(true);
}

Note the symmetry with the attestation pattern in the fullstack DApp tutorial: the sponsor here plays the same role as the authority there.

Compile it:

npx compact compile contracts/Contract.compact src/contracts

This emits src/contracts/managed/realestate/contract/index.js plus the ZK proving keys and verifier under src/contracts/managed/realestate/keys/.

The investor identity

Storing private keys in localStorage is a recipe for losing user funds the moment they clear cookies. Midnight DApps solve this by deriving the key deterministically each session from password + wallet.shieldedCoinPublicKey:

const masterKey = await deriveKeyFromPassword(password, shieldedCoinPublicKey);
const investorSk = await deriveKey(masterKey, 'realestate:investor');
const sponsorSk  = await deriveKey(masterKey, 'realestate:sponsor');

Same wallet + same password ⇒ same secret key forever. Lose the password and the identity is unrecoverable — by design.

Generating the ownership commitment

The investor computes the commitment off-chain and DMs it to the sponsor. The sponsor never sees the secret key, only the hash:

const commitment = contractModule.pureCircuits.getOwnershipCommitment(
  investorSk,
  padTo32Bytes(propertyId)
);

In src/pages/Home.tsx we wire that up to a property-ID input box so the investor can copy a commitment with two clicks.

Issuing shares

Once the sponsor has a commitment, they call issueShare. The Midnight transaction pipeline does the heavy lifting — the witness localSecretKey() resolves the sponsor secret from local private state, the contract enforces sponsor == publicKey(sk), and a ZK proof is generated and submitted by the wallet:

const txInterface = createCircuitCallTxInterface(
  providers, finalContract, contractAddress, PRIVATE_STATE_ID
);
await txInterface.issueShare(hexToUint8Array(holderCommit));

The on-chain effect: one new leaf in the ownershipCommitments tree, totalShares incremented. No wallet address, no investor name.

Proving ownership

When an investor needs to prove they own some share of a property — say, to log into a private investor portal — they call proveOwnership:

await txInterface.proveOwnership(padTo32Bytes(propertyId));

The witness findOwnershipPath(commit) fetches the Merkle path locally (the investor’s private state has been syncing in the background). The circuit asserts the path roots match a historic root of the tree, generating a ZK proof that the investor’s commitment is in the tree without revealing which leaf.

Claiming rental yield

The sponsor periodically calls depositRent(amount) which adds to the rentalPoolAvailable. Investors then call claimYield:

export circuit claimYield(
  propertyId: Bytes<32>, cycle: Bytes<32>, amount: Uint<64>
): Boolean {
    const sk = localSecretKey();
    const commit = ownershipCommit(sk, propertyId);
    const path = findOwnershipPath(commit);
    assert(
        ownershipCommitments.checkRoot(disclose(merkleTreePathRoot<10, Bytes<32>>(path))),
        "Not an owner of this property"
    );
    const nul = yieldNullifier(sk, propertyId, cycle);
    assert(!yieldClaimNullifiers.member(disclose(nul)), "Yield already claimed this cycle");
    assert(rentalPoolAvailable >= amount, "Insufficient rental pool");
    yieldClaimNullifiers.insert(disclose(nul));
    rentalPoolAvailable = (rentalPoolAvailable - amount) as Uint<64>;
    totalYieldClaims.increment(1);
    return disclose(true);
}

Two assertions matter:

• checkRoot(...) proves ownership.
• !usedNullifiers.member(nul) blocks double-claims for the same (investor, property, cycle).

The chain learns: someone who owns this property has claimed amount for this cycle. It never learns who.

Front-end wallet integration

Connection follows the same pattern as the reference fullstack-dapp:

const wallets = getCompatibleWallets();           // discover injected wallets
setWallet(selected);                              // remember the selection
const connectedApi = await wallet.connect('preprod');
const addresses = await connectedApi.getShieldedAddresses();

The Zustand store in src/hooks/useWallet.ts keeps connectedApi, addresses, and balances reactive across pages.

Reading aggregate state

Anyone — including unauthenticated users — can query the indexer to get aggregate stats:

const provider = indexerPublicDataProvider(INDEXER_HTTP, INDEXER_WS);
const state = await provider.queryContractState(contractAddress);
const ledger = contractModule.ledger(state.data);
// ledger.totalShares          → bigint
// ledger.totalYieldClaims     → bigint
// ledger.rentalPoolAvailable  → bigint

These are perfect for a public marketing page: “12 properties, $4.2M rental pool, 318 anonymous holders” — no individual holdings disclosed.

What this unlocks

• Family offices can hold real-estate exposure without their portfolio leaking to LPs, prime brokers, or the chain.
• REIT issuers can demonstrate compliance (every payout went to a verified holder) without surrendering shareholder lists.
• Auditors can verify aggregate flows match deposits and that no nullifier was reused.

Troubleshooting

• Wallet not detected → install Lace or 1AM, refresh.
• Tx failing → make sure your wallet has tDUST and the proof server is running on :6300.
• Not an owner of this property → the sponsor hasn’t issued you a share yet, or you’re computing the commitment with a different password.
• Yield already claimed this cycle → the nullifier check is doing its job.

Environment

[Conclusion] Summary of the Cause and Solution

For those who want a quick fix, here is the summary of the cause and the solution.
The sleep wake-up failure that had been occurring for years was actually a combination of two independent issues: the “driver” and the “BIOS”.

A clean installation of the driver only provided a “temporary relief.” The root cause lay in the motherboard’s BIOS. If dump file analysis points to a driver issue, but reinstalling the driver doesn’t stop the problem from recurring, updating the BIOS is highly likely the only way to achieve a complete fix.

Timeline of the Issue

4 Years Ago (Initial Windows 11 Installation)

When I migrated to Windows 11 right after its release, my PC started failing to wake from sleep, automatically restarting a few minutes later instead.

I tweaked settings and reinstalled drivers, but nothing worked. Because my work kept getting interrupted by these random reboots, I quickly downgraded (rolled back) to Windows 10 to escape the nightmare.

Around Fall 2025

As the end of support for Windows 10 approached, I gathered my courage and upgraded to Windows 11 once again.

Remembering the nightmare from four years ago, I hesitantly put the PC to sleep. Surprisingly, instead of the post-restart screen, the screen woke up with all my active applications fully restored.
It seemed that over the past 4 years (likely via Windows Updates), the system’s behavior had changed. Putting it to “sleep” actually triggered “Hibernation,” from which it could restore. While it wasn’t a pure sleep wake-up, I compromised and kept using it since my work state was preserved.

Right After Installing the GPU

Wanting to run a local AI, I installed a new graphics card (ASUS DUAL-RX9060XT-16G).

The very next day, when I tried to wake the PC from sleep (hibernation) as usual, the exact same initial symptom from four years ago returned: “failed to wake from sleep -> auto-restart.”

Details of the Symptoms

I had my keyboard configured to trigger the wake-up process. The behavior was as follows:

1. Pressing a key on the keyboard did nothing; the monitor remained completely dark.
2. After a few minutes passed, the BIOS splash screen suddenly appeared.
3. The OS would then reboot entirely (losing all pre-sleep work states).

There was no Blue Screen of Death (BSOD); I just found myself at the sign-in screen.

Phase 1: Identifying the Driver as the Cause & Temporary Fix

Step 1: Checking Status with Reliability Monitor and Event Viewer

First, I used “View reliability history” (searchable from the taskbar) to pinpoint the exact date of the error. Then, I checked the Event Viewer for details.

How to check Event Viewer:

1. Right-click the Start button -> Select “Event Viewer”.
2. From the left tree, select “Windows Logs” -> “System”.
3. Click “Filter Current Log” and check “Critical” and “Error” to narrow down the results.

Main errors identified:

In the Reliability Monitor, I also found the following error:

• LiveKernelEvent 141 (Video Hardware Error): Indicates that the GPU driver stopped responding for a certain period, and Windows attempted to forcibly reset it.

Step 2: Analyzing the Dump File with WinDbg

Since Event Viewer only told me that the “GPU driver crashed,” I proceeded to analyze the dump file (.dmp) to find the underlying cause.

Dump file location: C:WindowsMinidump

Analysis steps:

1. Install Microsoft’s official “WinDbg” (available via Microsoft Store or Windows SDK).
2. Open the dump file (.dmp) in WinDbg.
3. Run the analysis command !analyze -v to get the debug log.
4. Paste the obtained log into a Generative AI for analysis.

Note:
Simply passing the raw debug log to a Generative AI yields highly accurate analysis. Even if you aren’t familiar with WinDbg, you can get through this just by copy-pasting the logs.

What the analysis revealed:

BugCheck: 0x000000a0 (INTERNAL_POWER_ERROR)
Parameter 1: 0xf1

0xa0 with Parameter 0xf1 means a failure to transition to Modern Standby (S0 Low Power Idle). It turned out that during the transition to or from sleep, the AMD Radeon graphics driver amdkmdag.sys stopped responding (hung), leading the OS to interpret it as a “fatal power error” and forcibly restart the system.

Step 3: Clean Installation of the Driver

Since the cause was narrowed down to the AMD driver, I performed a clean install using the official “AMD Cleanup Utility”.

Important Warning:
The AMD Cleanup Utility runs in Safe Mode, which may disconnect your internet. Make sure to download the latest driver installer BEFORE starting this process.

Driver used this time: AMD Software: Adrenalin Edition 26.3.1 (WHQL Recommended)

Interestingly, I was already using the latest driver when the issue occurred. The problem wasn’t the version itself, but rather incomplete driver remnants left behind by normal uninstallations. Complete removal via the AMD Cleanup Utility and subsequent reinstallation was required.

Clean Installation Steps:

1. Preparation (Download)

• Download the latest “AMD Software: Adrenalin Edition” installer from the official AMD website.
• Download the “AMD Cleanup Utility” (amdcleanuputility.exe) from the official AMD support page.

2. Removing Current Drivers

1. Run amdcleanuputility.exe.
2. A prompt will ask if you want to reboot into Safe Mode. Click “Yes”.
3. The PC will automatically restart and boot into Safe Mode.
4. Once in Safe Mode, the tool launches automatically. When it asks to remove all AMD drivers and components, click “OK”.
5. The screen may flicker during removal—this is normal.
6. When it says “AMD Cleanup Utility has successfully completed,” click “OK” -> “Yes (Reboot)”.

3. Reinstalling the Driver

1. Once Windows boots normally, run the installer you downloaded earlier.
2. Follow the on-screen instructions to complete the installation.
3. Restart the PC one more time just to be safe.

With this fix, the system stopped relying on the “fake sleep” (hibernation) workaround, and the sleep wake-up failure seemed temporarily resolved.

Alternative solutions suggested by GenAI (Not needed in this case)

Based on the dump analysis, the Generative AI also suggested the following workarounds, but they were irrelevant to my environment:

• Disabling the integrated graphics (iGPU)
• Disabling PCIe Link State Power Management
• Disabling Modern Standby (via registry/settings)

These are often BIOS-level settings, which might not exist depending on your motherboard, or might have already been addressed by default.

Phase 2: Recurrence & Identifying the Root Cause

Recurrence After 1 Week

About a week after the driver update, the automatic restart due to sleep wake-up failure happened again.

Narrowing Down Reproduction Conditions

After repeated testing, I identified a specific trigger: The wake-up failure occurred when I put the PC to sleep while leaving an AI model loaded in “Lemonade” (a local server software for running LLMs).

I strongly suspected that entering sleep mode while heavily occupying the GPU VRAM was the trigger.

Re-investigation

I analyzed the dump files with WinDbg again and consulted the GenAI, but it gave the same response as before: “Driver issue (amdkmdag.sys).” No new clues were found there.

I then manually searched Reddit and international forums. There, I found multiple reports stating, “Updating the BIOS fixed the sleep wake-up bug.” This raised the possibility of a fundamental flaw in the motherboard’s firmware.

Phase 3: Root Cause Resolution via BIOS Update

BIOS Update Procedure

For ASUS motherboards, you can use “ASUS EZ Flash 3” to update the BIOS directly from the BIOS screen without relying on the OS, as long as you have the BIOS image file.

Steps:

1. Download the latest BIOS for your motherboard (TUF GAMING X570-PLUS) from the ASUS official website.
2. Place the BIOS file in the root directory of a FAT-formatted USB flash drive.
3. Restart the PC and enter the BIOS screen (by pressing the Delete key).
4. Navigate to “Tool” -> “ASUS EZ Flash 3 Utility”.
5. Select the USB flash drive, choose the BIOS file, and execute the update.
6. The PC will automatically restart upon completion.

Warning:
A failed BIOS update carries the risk of rendering your PC unbootable (bricking). Please ensure the following before proceeding:

• Use a UPS or ensure a highly stable power connection to prevent power loss during the update.
• Take note of your current BIOS settings just in case.

Results

After the update, I tested putting the PC to sleep while leaving the AI model loaded. It woke up perfectly without any issues. The long-standing bug was finally and completely resolved.

Side Effects of BIOS Updates & Workarounds

Updating the BIOS causes the following side effects. I highly recommend preparing for them in advance.

1. Windows Sign-in PIN Gets Reset

After a BIOS update, the PIN used for Windows Hello is cleared.

What to do beforehand:

• Ensure you can sign in using your Microsoft account password.
• Make sure you have access to your Microsoft account recovery email (a verification code may be sent when logging into the OS).

Note:
In my case, I happened to have my Windows login password safely stored in a custom-built Android app I created for password and account management, so I was able to sign in without any trouble.

2. Passkeys Are Disabled

Because the PIN is reset, any passkeys tied to your PC via Windows Hello (such as for your Google account) will become unusable. Even if you set your PIN back to exactly what it was, they won’t recover. You will need to re-register your passkeys for each respective service.

Conclusion

While the WinDbg dump analysis consistently pointed only to a crash in amdkmdag.sys, the breakthrough that led me to suspect the BIOS came from information found on international forums.

The key takeaway from this experience is that sleep-related bugs are surprisingly often caused by the BIOS.
I hope this log helps anyone dealing with the same frustrating issue!

JSON Schema is a vocabulary that lets you describe the structure of your JSON data and validate it automatically. It’s been around since 2009 and is now a draft standard under the IETF. If you work with APIs, configs, or any structured JSON, it’s worth knowing.

What JSON Schema actually does

A JSON Schema is itself a JSON document that describes what valid JSON looks like. Here’s a minimal example:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "email"],
  "properties": {
    "id": { "type": "integer" },
    "email": { "type": "string", "format": "email" },
    "age": { "type": "integer", "minimum": 0, "maximum": 150 }
  }
}

This schema says: the JSON must be an object with id (integer) and email (string, email format) as required fields. age is optional but, if present, must be a non-negative integer under 150.

Run any JSON against this schema and you get a pass/fail result with specific error messages.

The core keywords you need to know

Type keywords: "type": "string", "type": "integer", "type": "number", "type": "boolean", "type": "array", "type": "object", "type": "null". You can allow multiple types with an array: "type": ["string", "null"].

String constraints: minLength, maxLength, pattern (regex). For example: "pattern": "^[a-z]{2,3}$" would match a 2–3 character lowercase language code.

Number constraints: minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf.

Array constraints: items (schema for each element), minItems, maxItems, uniqueItems. With uniqueItems: true, duplicate entries fail validation.

Object constraints: properties (per-key schemas), required (list of required keys), additionalProperties (set to false to ban keys not listed in properties).

Combining schemas: allOf, anyOf, oneOf, not. These let you compose complex validation rules from simpler ones.

A real-world example

Say you’re calling a payment API that returns transaction objects. You want to catch bad responses before they reach your business logic:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["transaction_id", "amount", "currency", "status"],
  "properties": {
    "transaction_id": { "type": "string", "minLength": 1 },
    "amount": { "type": "number", "exclusiveMinimum": 0 },
    "currency": { "type": "string", "pattern": "^[A-Z]{3}$" },
    "status": { "type": "string", "enum": ["pending", "completed", "failed", "refunded"] },
    "metadata": { "type": "object" }
  },
  "additionalProperties": false
}

This rejects: zero or negative amounts, currencies that aren’t 3-letter ISO codes, statuses outside the defined enum, and any unexpected extra fields.

Where JSON Schema is used

• API contract testing — validate responses from external APIs before processing
• Configuration files — VS Code uses JSON Schema to provide autocomplete and inline validation for settings.json, launch.json, and many extension configs
• Form validation — libraries like Ajv run schema validation client-side
• CI pipeline checks — validate generated artifacts before deploying
• OpenAPI specs — OpenAPI 3.x uses JSON Schema for request/response body definitions

Draft versions and compatibility

The most widely supported version is draft-07. Draft-04 is still common in older codebases. Newer drafts (2019-09, 2020-12) add features like $defs, unevaluatedProperties, and prefixItems for tuple validation, but library support is patchy.

If you’re starting fresh, use draft-07 — you get broad tool and library support with minimal compatibility headaches.

Validating quickly without writing code

If you want to test a schema against some JSON right now without setting up a project, you can use a browser-based validator. I built one at SnappyTools JSON Formatter for formatting and validating JSON structure — paste your JSON, see errors highlighted instantly, all client-side with no data sent anywhere.

For schema-specific validation (pairing a schema with an instance and seeing which keywords fail), tools like jsonschema.dev and jsonschemavalidator.net are useful references.

The quick takeaway

JSON Schema is the most practical way to add a validation layer between your app and untrusted JSON data. You don’t need a library for simple cases — just knowing the keywords lets you write schemas by hand and reason about what JSON your code will accept.

Start with type, required, and properties. Add minimum/maximum for numbers, pattern for strings, and enum for fixed value sets. That covers 80% of real-world validation needs.

5 Common JSON Errors That Break APIs (and How to Fix Them)

If you’ve worked with APIs for even a short time, you’ve probably run into this:

“Why is this JSON not working?!”

Everything looks fine… until your parser throws an error and your app breaks.

The truth is, most JSON issues are small but deadly — a missing comma, a trailing bracket, or an incorrect structure can completely break your API flow.

In this post, I’ll walk through the 5 most common JSON errors developers face, along with simple fixes and examples.

1. Missing Commas Between Fields

This is probably the most common issue.

Invalid JSON:

{
  "name": "John"
  "age": 30
}

Fixed JSON:

{
  "name": "John",
  "age": 30
}

Why it happens:
When manually editing JSON, it’s easy to forget commas between key-value pairs.

2. Trailing Commas

Some languages allow trailing commas — JSON does NOT.

Invalid JSON:

{
  "name": "John",
  "age": 30,
}

Fixed JSON:

{
  "name": "John",
  "age": 30
}

Tip:
If you’re copying JSON from JavaScript objects, watch out for this.

3. Unquoted Keys or Strings

JSON requires double quotes for keys and string values.

Invalid JSON:

{
  name: "John",
  age: 30
}

Fixed JSON:

{
  "name": "John",
  "age": 30
}

4. Incorrect Data Types

Sometimes values are accidentally wrapped as strings instead of numbers or booleans.

Problematic JSON:

{
  "isActive": "true",
  "count": "10"
}

Better JSON:

{
  "isActive": true,
  "count": 10
}

Why it matters:
Your backend or frontend logic may behave incorrectly if types are wrong.

5. Unclosed Brackets or Braces

This is another classic.

Invalid JSON:

{
  "user": {
    "name": "John"

Fixed JSON:

{
  "user": {
    "name": "John"
  }
}

How to Fix JSON Faster

Manually debugging JSON is frustrating — especially with large API responses.

A better approach is to use a tool that can:

• Validate JSON instantly
• Highlight errors
• Format and beautify the structure
• Fix common issues automatically

I’ve been using a simple tool called Fixzi for this:

https://fixzi.ai/json-validator

It helps quickly:

• Validate JSON
• Fix invalid structures
• Format and clean large payloads
• Compare JSON responses (useful for APIs)

Final Thoughts

JSON errors are small, but they can cause big production issues — especially when working with APIs, webhooks, or third-party integrations.

If you’re debugging JSON frequently:

• Always validate before using it
• Use proper formatting tools
• Avoid manual edits when possible

If you’ve faced other tricky JSON issues, I’d love to hear them

Check Your Access to Foundry

Microsoft Foundry (formerly Azure AI Studio) is a unified, enterprise-grade AI platform-as-a-service designed for developers to build, customize, and deploy AI applications and agents.

1. Go to https://ai.azure.com/nextgen
2. Click Build on the top navigation bar
3. Click Models in the side menu

Make sure your organization already has Claude models deployed in Foundry (for example claude-opus-4-7).

Connect Foundry Models to Claude Code

I recommend using Entra ID + Azure CLI authentication. It’s safer and more convenient than managing API keys manually.

Install Azure CLI before continuing:

• https://learn.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest

After installing Azure CLI, sign in with:

az login

Set the following environment variables to enable Microsoft Foundry integration in Claude Code.

I usually put them in my .zshrc.

# Enable Microsoft Foundry integration
export CLAUDE_CODE_USE_FOUNDRY=1

# Azure resource name (replace {resource} with your resource name)
export ANTHROPIC_FOUNDRY_RESOURCE={resource}

# Or provide the full base URL:
# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic

In the current Foundry UI, resource are renamed to project.

Set the model variables to match your deployment names.

By default, the opus alias on Foundry may still resolve to Opus 4.6. To make sure Claude Code uses Opus 4.7, explicitly set:

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-4-6'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'

Common Issues

Wrong Azure tenant

If your company uses multiple Azure tenants, az login may authenticate against the wrong one.

Check your current tenant with:

az account show

Switch tenants if needed:

az login --tenant <tenant-id>

Deployment name mismatch

The model name in Claude Code must match the deployment name configured in Foundry.

For example:

export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-7'

must exactly match the deployment name shown in the Foundry Models page.

Side Notes

Some companies provide Azure subscriptions or enterprise credits for internal development.

So even if your IT team has not deployed Claude models yet, you may still be able to deploy them yourself.

Just make sure you have permission before creating resources.

Mastering Regular Expressions in JavaScript: From Basics to Real-World Validation

At first glance, a regex pattern looks like a cat walked across your keyboard,a chaotic string of slashes, brackets, and symbols. However, once you decode the syntax, it becomes one of the most powerful tools in your developer toolkit.
Below is the break down of how regex works in JavaScript and build a robust pattern to validate something we use every day: email addresses.

What is a Regular Expression anyways?

A Regular Expression is an object that describes a pattern of characters. In JavaScript, you can create them in two ways:

1. Literal Notation: /pattern/flags
2. Constructor: new RegExp(‘pattern’, ‘flags’)
   ### The Core Building Blocks
   Before we tackle the email login, we need to understand the “alphabet” of regex:
3. Character Classes:
   • d: Matches any digit (0-9).
   • w: Matches any alphanumeric character (letters, numbers, and underscores).
   • s: Matches whitespace (spaces, tabs).
   • .: The wildcard—matches any character except a newline.
4. Quantifiers:
   • +: Matches 1 or more of the preceding element.
   • *: Matches 0 or more.
   • {n,m}: Matches between n and m times.
5. Anchors:
   • ^: Forces the match to start at the beginning of the string.
   • $: Forces the match to end at the end of the string.
     ### Deep Dive: Validating an Email Address
     When we log in to a platform, the first line of defense is ensuring the input actually looks like an email. Let’s build a regex for a standard email like zone01.recode@company.co.ke.
     #### 1. The Local Part (zone01 .recode)
     We want to allow letters, numbers, dots, and underscores.
6. Pattern: ^[a-zA-Z0-9._%+-]+
7. Explanation: We start at the beginning (^) and allow a set of characters inside the square brackets. The + ensures there is at least one character.
   #### 2. The “@” Symbol
   We just need the literal character.
8. Pattern: @
   #### 3. The Domain (company)
   Similar to the local part, but usually without the special symbols.
9. Pattern: [a-zA-Z0-9.-]+
   #### 4. The TLD (.co.ke or .com)
   We need a literal dot, followed by letters. Since a dot . is a wildcard in regex, we must escape it with a backslash ..
10. Pattern: .[a-zA-Z]{2,}$
11. Explanation: This looks for a dot and at least two letters at the very end of the string ($).
    #### Putting it all together:

const emailRegex = /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+.[a-zA-Z]{2,}$/;

const testEmail = "dev_user123@zone01.edu";
console.log(emailRegex.test(testEmail)); // Output: true

Common Use Cases in Web Apps

Beyond login forms, regex is used everywhere in full-stack development:

• Password Strength: Checking for at least one capital letter, one number, and one special character.
• URL Parsing: Extracting slugs or IDs from a browser’s address bar.
• Data Scrubbing: Removing formatting from phone numbers (e.g., changing +254 712-345-678 to 254712345678).
• Search and Replace: Swapping specific words across a whole document using the global /g flag.
  ### Helpful Methods in JavaScript
  To use your patterns, you’ll mostly use these two methods:
• regex.test(string): Returns true or false. Perfect for form validation.
• string.match(regex): Returns an array of matches. Great for extracting information from a large block of text.
  > Pro Tip: Use tools like RegEx101 to test your patterns in real-time before putting them into your code. It provides a “flavor” setting—make sure to select ECMAScript (JavaScript).
  >
  ### Conclusion
  Regex might feel like a steep climb, but it is a “learn once, use everywhere” skill. Whether you are working on a Go backend or a JavaScript frontend, the logic remains largely the same. Keep practicing by trying to validate other common inputs like phone numbers or postal codes!

If you’ve ever stored a URL in a database and later regretted it, this is for you.

It’s a familiar scenario: a service needs to keep a reference to a resource that lives in another service. The obvious solution is to store the URL. It works — until the host changes, the API gets a new version, or the team decides to restructure the paths. Suddenly all the stored references are broken, and tracking down the impact becomes a bigger problem than it should be.

The root issue is that a URL mixes two different things: what the resource is and where it lives. When you store a URL, you’re betting that location won’t change. In systems that evolve, that’s usually a losing bet.

The idea

What if instead of storing where the resource lives, you store your own identifier that a gateway knows how to resolve?

commerce:orders/order:id=ARG-2024-00091872
finance:accounts/customer:status:id=109234
health:coverage/credential:patient-id=12345678

Whoever stores the reference doesn’t need to know where the resource lives or how to access it. That’s the gateway’s responsibility. If the API changes, if the service migrates, if a new system appears: only the resolver changes. The stored references remain valid.

I called this scheme Delegated Resource Identifier (DRI).

What this pattern is not

• It’s not a standard
• It requires a gateway as intermediary: it doesn’t apply when the client needs to access the resource directly without going through any intermediary
• It doesn’t impose a context taxonomy: each team defines their own

It’s a useful convention when you need persistent references to resources in a controlled ecosystem and want to centralize the resolution logic.

How it’s built

The identifier has two parts separated by /:

<context>/<resource>

• Context (left side): identifies the domain that knows how to resolve this type of resource. The gateway uses it for routing.
• Resource (right side): identifies the concrete resource. Its structure is defined by whoever implements the resolver.

commerce:orders/order:id=ARG-2024-00091872
└─── routing ───┘└─── concrete resource ──┘

: separates hierarchical levels. = assigns values. Each side defines its own internal convention.

The identifier is built by whoever stores the reference, from the data they already have and the context they know. No external call required. A billing service that receives an order ID knows it belongs to commerce:orders and builds the DRI when persisting the reference.

The context can be omitted if the gateway has a default resolver:

/order:id=ARG-2024-00091872

Some use cases

E-commerce: retrieving an order

A customer service system stores references to orders that can come from different channels: own store, marketplace, mobile app. Each channel has its own API.

commerce:orders/order:id=ARG-2024-00091872
commerce:orders/order:id=MKT-2024-00034521

The commerce:orders resolver determines which channel each order belongs to based on the ID prefix and routes to the corresponding API. The identifier remains stable even if the channel’s API changes.

Fintech: customer account status

A bank with legacy and modern systems running side by side. The resolver determines which system the customer lives in based on the ID value: customers with id < 50000 are in the legacy system, the rest in the modern one.

finance:accounts/customer:status:id=109234
finance:accounts/customer:status:id=002871

The resolver also encapsulates the decision of which API version to use. And here something interesting emerges: the DRI has two moments in its lifecycle. When persisted, it’s just the identifier. When used for a query, it can be enriched with additional context using the same syntax:

finance:accounts/customer:status:id=109234:date=20260101

The resolver can use that date to determine which API version applies. The persisted DRI doesn’t change; the additional context is added at query time.

Health: member coverage credential

A member’s coverage can change over time: provider migration, gaps in coverage, or coverage with more than one provider. Storing the provider as a fixed value would produce outdated references.

health:coverage/credential:patient-id=12345678

The resolver applies a fallback strategy: it queries the first available provider and if the credential isn’t found, tries the next one. The DRI resolves at query time, always reflecting the current state.

Multinational with tenant: supplier by legal entity

A SaaS platform used by a company operating in multiple countries. Each country has its own supplier management system, its own API, and its own tax identifier format.

tenant:acme:ar/supplier:cuit=20123456789
tenant:acme:cl/supplier:rut=76354921-5
tenant:acme:mx/supplier:rfc=XYZ123456789

The left side combines tenant and legal entity by country. The right side respects the local convention without the gateway knowing anything about it. Adding a new subsidiary or tenant means registering an additional resolver, without touching existing references. The context hierarchy grows naturally with the system.

How the gateway works

The resolution flow is simple: the gateway receives the identifier, extracts the context, and delegates to the corresponding resolver.

client  →  gateway  →  resolver(commerce:orders)  →  actual service

1. Receives the identifier
2. Extracts the context (left side)
3. Delegates to the registered resolver for that context
4. The resolver fetches the resource and returns the response

The gateway has no knowledge of concrete resources. As an orientative reference, a possible Java implementation:

gateway.register("commerce:orders",   new OrderResolver());
gateway.register("finance:accounts",  new AccountResolver());
gateway.register("health:coverage",   new CoverageResolver());

public interface ResourceResolver {
    Response resolve(ResourceIdentifier identifier);
}

Optional preferences

The identifier supports expressing preferences about how the resource should be resolved, with a syntax inspired by HTTP’s Accept header. For example, when querying available payment methods, you can indicate a preference for debit over credit:

payments:methods/available:customer:id=109234;debit,q=0.9;credit,q=0.7

The meaning of q is defined by the contract between whoever builds the reference and whoever resolves it. The gateway doesn’t need to interpret it. This capability is completely optional.

I implemented this in Java and found it useful in practice. If you try it in your own context or have ideas to improve it, I’d love to read them in the comments.

Si alguna vez guardaste una URL en una base de datos y después te arrepentiste, esto es para vos.

Es un escenario conocido: un servicio necesita mantener una referencia a un recurso que vive en otro servicio. La solución más obvia es guardar la URL. Funciona, hasta que el host cambia, la API sube de versión, o el equipo decide reestructurar los paths. De repente todas las referencias guardadas están rotas, y rastrear el impacto se convierte en un problema mayor de lo que debería ser.

El problema de fondo es que una URL mezcla dos cosas distintas: qué es el recurso y dónde está. Cuando guardás una URL estás apostando a que esa ubicación no va a cambiar. En sistemas que evolucionan, esa apuesta suele perderse.

La idea

¿Qué pasaría si en lugar de guardar dónde está el recurso, guardás un identificador propio que un gateway sabe cómo resolver?

comercio:pedidos/orden:id=ARG-2024-00091872
finanzas:cuentas/cliente:estado:id=109234
salud:cobertura/credencial:patient-id=12345678

Quien guarda la referencia no necesita saber dónde vive el recurso ni cómo se accede. Esa responsabilidad la tiene el gateway. Si la API cambia, si el servicio migra, si aparece un sistema nuevo: solo cambia el resolver. Las referencias guardadas siguen siendo válidas.

A este esquema lo llamé Delegated Resource Identifier (DRI).

Lo que este patrón no es

• No es un estándar
• Requiere un gateway como intermediario: no aplica cuando el cliente necesita acceder directamente al recurso sin pasar por ningún intermediario
• No impone una taxonomía de contextos: cada equipo define la suya

Es una convención útil cuando necesitás referencias persistentes a recursos en un ecosistema controlado, y querés centralizar la lógica de resolución.

Cómo se construye

El identificador tiene dos partes separadas por /:

<contexto>/<recurso>

• Contexto (lado izquierdo): identifica el dominio que sabe resolver este tipo de recurso. El gateway lo usa para rutear.
• Recurso (lado derecho): identifica el recurso concreto. Su estructura la define quien implementa el resolver.

comercio:pedidos/orden:id=ARG-2024-00091872
└─── ruteo ──────┘└─── recurso concreto ──┘

Los : separan niveles jerárquicos. El = asigna valores. Cada lado define su propia convención interna.

El identificador lo construye quien guarda la referencia, a partir del dato que ya tiene y el contexto que conoce. No requiere ninguna llamada externa. Un servicio de facturación que recibe el ID de una orden sabe que pertenece a comercio:pedidos y construye el DRI al momento de persistir la referencia.

El contexto puede omitirse si el gateway tiene un resolver por defecto:

/orden:id=ARG-2024-00091872

Algunos casos de uso

E-commerce: recuperar una orden

Un servicio de atención al cliente guarda referencias a órdenes que pueden venir de distintos canales: tienda propia, marketplace, app móvil. Cada canal tiene su propia API.

comercio:pedidos/orden:id=ARG-2024-00091872
comercio:pedidos/orden:id=MKT-2024-00034521

El resolver de comercio:pedidos determina a qué canal pertenece cada orden a partir del prefijo del ID y rutea hacia la API correspondiente. El identificador es estable aunque la API del canal cambie.

Fintech: estado de cuenta de un cliente

Un banco con sistemas legacy y modernos conviviendo. El resolver determina en qué sistema vive el cliente según el valor del ID: clientes con id < 50000 en el sistema legacy, el resto en el moderno.

finanzas:cuentas/cliente:estado:id=109234
finanzas:cuentas/cliente:estado:id=002871

El resolver encapsula también la decisión de qué versión de la API usar. Y acá aparece algo interesante: el DRI tiene dos momentos de vida. Cuando se persiste es solo el identificador. Cuando se usa para consultar, puede enriquecerse con contexto adicional usando la misma sintaxis:

finanzas:cuentas/cliente:estado:id=109234:fecha=20260101

El resolver puede usar esa fecha para determinar qué versión de la API corresponde. El DRI persistido no cambia; el contexto adicional se agrega en el momento de la consulta.

Salud: credencial de cobertura de un afiliado

La cobertura de un afiliado puede cambiar en el tiempo: migración de proveedor, períodos sin cobertura, cobertura en más de uno. Guardar el proveedor como dato fijo generaría referencias desactualizadas.

salud:cobertura/credencial:patient-id=12345678

El resolver aplica una estrategia de fallback: consulta al primer proveedor disponible y si no encuentra la credencial prueba con el siguiente. El DRI resuelve en el momento de la consulta, reflejando siempre el estado actual.

Multinacional con tenant: proveedor por entidad legal

Una plataforma SaaS con operaciones en múltiples países. Cada país tiene su propio sistema, su propia API y su propio formato de identificador fiscal.

tenant:acme:ar/proveedor:cuit=20123456789
tenant:acme:cl/proveedor:rut=76354921-5
tenant:acme:mx/proveedor:rfc=XYZ123456789

El lado izquierdo combina tenant y entidad legal por país. El lado derecho respeta la convención local. Agregar una nueva filial o un nuevo tenant es registrar un resolver adicional, sin tocar las referencias existentes. La jerarquía del contexto crece naturalmente con el sistema.

Cómo funciona el gateway

El flujo de resolución es simple: el gateway recibe el identificador, extrae el contexto y delega al resolver correspondiente.

cliente  →  gateway  →  resolver(comercio:pedidos)  →  servicio real

1. Recibe el identificador
2. Extrae el contexto (lado izquierdo)
3. Delega al resolver registrado para ese contexto
4. El resolver obtiene el recurso y devuelve la respuesta

El gateway no conoce recursos concretos. A modo de referencia orientativa, una posible implementación en Java:

gateway.register("comercio:pedidos", new OrderResolver());
gateway.register("finanzas:cuentas", new AccountResolver());
gateway.register("salud:cobertura",  new CoverageResolver());

public interface ResourceResolver {
    Response resolve(ResourceIdentifier identifier);
}

Preferencias opcionales

El identificador admite expresar preferencias sobre cómo debe resolverse el recurso, con una sintaxis inspirada en el header Accept de HTTP. Por ejemplo, al consultar medios de pago se puede indicar preferencia por débito sobre crédito:

pagos:medios/disponibles:cliente:id=109234;debito,q=0.9;credito,q=0.7

El significado de q lo define el contrato entre quien construye la referencia y quien la resuelve. El gateway no necesita interpretarlo. Esta capacidad es completamente opcional.

Lo implementé en Java y me resultó útil en la práctica. Si lo probás en tu contexto o tenés ideas para mejorarlo, me interesa leerlo en los comentarios.

Three things Rust already gives you for free

1. Pin> = a suspended computation

Think about it: a reactive effect is “a piece of code paused, waiting for its dependencies to change, then re-executing.” That’s exactly what a future stuck at Poll::Pending is.

scope.spawn(async move {
loop {
count.changed().await; // suspends here
println!(“count = {}”, count.read());
}
});

The SignalChangedFuture::poll() checks a monotonic version number. If unchanged, it subscribes a callback and returns Poll::Pending. The async executor polls other tasks. When the signal changes, the version bumps, the callback fires, the waker wakes, the executor re-polls. That’s the entire effect lifecycle — no custom scheduler, no effect graph traversal, no create_effect() abstraction.

The executor’s poll loop IS the effect scheduler. You don’t need a separate one.

1. Waker = the notification dispatcher

A reactive library has to decide “which effects need to re-run when signal X changes.” In the async model, this maps directly to “which futures should be re-polled.” The waker IS that dispatch mechanism:

fn poll(self: Pin<&mut Self>, cx: &mut Context<‘_>) -> PollSelf::Output {
if version_changed {
return Poll::Ready(self.signal.read());
}
// subscribe a callback that calls cx.waker().wake_by_ref()
// executor re-polls this future on next flush
Poll::Pending
}

No separate notification queue. No topological sort of dependents. Just “wake the waker, executor picks it up.”

1. Drop = cleanup

Drop the scope that owns the tasks → all futures drop → each future’s Drop impl proactively unsubscribes from its signals → zero dangling subscribers. No manual on_cleanup() tokens, no effect disposal bookkeeping. Rust’s ownership does the work.

For deeply nested scopes (think UI component trees with hundreds of levels), cancellation uses BFS to collect all descendants, then iterates leaf-to-root — no recursive drop, no stack overflow.

The 20% Rust doesn’t give you: re-entrancy prevention

Here’s where pure async breaks down. If Signal::set() calls subscriber callbacks synchronously:

set() → callback → set() on same signal → callback → infinite loop
set() → callback → subscribe new callback → mutate subscriber list during iteration → RefCell panic
set() → callback → drop owning scope → borrow conflict

The async model alone can’t prevent this. You need a deferred notification state machine.

The approach: Signal::set() never invokes callbacks directly. It bumps the version, snapshots the subscriber list, and pushes a closure into the executor’s deferred callback queue. The executor drains this queue at the start of every flush, before polling any tasks.

Three states, two flags:

notifying = false, dirty = false → normal. Snapshot subscribers, push notification, set dirty.
notifying = true → re-entrant set during callback. Just set dirty, no new notification.
dirty = true, notifying=false → notification already queued. No-op.

After callbacks complete: check dirty. If a re-entrant set() happened during the callback round, schedule a follow-up notification using a fresh subscriber snapshot (so newly-added subscribers from the callback round are included).

This covers every edge case: re-entrant set, subscribe/unsubscribe during callback iteration, scope drop during callback (cancelled flag is a Cell outside the RefCell, always writable), set-from-Drop (deferred to next flush via set_deferred()).

The tradeoff

A traditional reactive scheduler can run effects in topological order — dependencies before dependents, guaranteeing each memo recomputes at most once. An async executor runs tasks in whatever order they wake up. If two effects both read a dirty memo, they might each trigger its recomputation (the second read sees it’s already clean and skips the work, but the first poll of each effect triggers the check).

Correctness is preserved — version checking + lazy memo recompute guarantees eventual consistency. But optimality is best-effort, not guaranteed.

For UI frame-level reactivity this is fine. For a compiler’s incremental analysis it probably isn’t. I think the simplicity trade is worth it for most applications, but I’d be curious to hear counterarguments.

Why bother?

If you squint, reactive programming and async programming are solving the same problem from different directions. One suspends computation waiting for data changes; the other suspends computation waiting for I/O. The primitives overlap almost completely. The question isn’t “can you build reactivity on async” — it’s “why wouldn’t you?”

The only genuinely novel piece needed is a safe way to fire subscriber callbacks without re-entrancy. Everything else is already in the language.

I built a working implementation of this (~1800 lines across two crates, #![forbid(unsafe_code)], zero external deps for the signal layer). I’d genuinely love technical feedback — especially on:

• Whether the lack of topological ordering has bitten anyone in real UI projects, or if it’s mostly a theoretical concern.
• Whether there’s a simpler alternative to the generational slot table I’m using for executor routing.

If I’ve missed an edge case, or if any of the tradeoffs feel wrong to you, I’m all ears. This is still my own learning process, and I’d rather get corrected now than find out later.

If you’re experiencing issues when executing flutter run --release or flutter build web, despite the app running smoothly in development mode using flutter run -d chrome, you’re not alone. This is a common dilemma that many Flutter developers face when transitioning their app from a debug build to a release build. In this article, we’ll explore why these errors occur and provide step-by-step solutions to resolve them.

Why Are You Facing Errors in Flutter Web Release?

When you attempt to create a release build using Flutter for the web, several factors could be causing errors. These include:

• Dependencies Mismatch: Conflicts with certain package versions might only present themselves in release mode.
• Incorrect Environment Configurations: Sometimes, configurations for web releases differ from those in your development environment.
• Code Compilation Issues: Certain code elements may function in a debug environment but can break during a release build due to optimizations or tree-shaking mechanisms.
• CORS Policy Issues: If your web app requires resources from different origins, you may run into CORS policy issues that appear in production but not in development.

Next, let’s delve into the solutions you can try to rectify these issues.

Step-by-Step Solutions to Fix Flutter Web Release Errors

1. Upgrade Flutter SDK

Before trying any complex solutions, ensure your Flutter SDK is up-to-date. Run the following command:

flutter upgrade

Check your current Flutter version using:

flutter --version

This ensures that any bug fixes or improvements related to the release mode are included.

2. Check Your Dependencies

Ensure that your pubspec.yaml file contains compatible versions of all packages. You can upgrade all your packages to the latest compatible versions by running:

flutter pub upgrade

After upgrading, don’t forget to run:

flutter pub get

This ensures that any new dependencies are correctly added.

3. Inspect Your Code for Errors

To efficiently identify issues in your code:

• Comment out parts of your app to determine which sections are failing.
• Pay particular attention to asynchronous operations, external API calls, and other functionalities that may not trigger errors in the debug mode.

4. Using Flutter Clean

If you’ve tried changing packages or configurations but are still facing release issues, performing a clean build often helps. Use:

flutter clean

Then try rebuilding:

flutter build web

This command removes the build directory and ensures you start fresh.

5. Check Browser Console for Errors

Open the developer console in the Chrome browser (using F12 or right-click and select ‘Inspect’) to see any JavaScript errors or warnings being logged when your web app runs. These messages may provide clues as to what’s wrong.

6. Adjust Build Configurations

Sometimes, specific build configurations need to be set for optimal success:

• Open your web/index.html file and ensure you have the correct base href set if you’re deploying to a subdirectory.
• Check your asset files path to ensure they’re correctly referenced.

7. Review the Flutter Web Configuration

Ensure that your web folder has all the necessary files (including index.html, favicon.png, etc.). Sometimes missing files can lead to errors during the release process.

Frequently Asked Questions (FAQ)

Q1: Why does my app work fine in debug mode but fails in release mode?

A1: Debug mode runs in an environment optimized for development, often ignoring error-checking mechanisms that a release build adheres to. This can expose hidden bugs.

Q2: How can I know if my package versions are compatible?

A2: Use the pubspec.lock file for a record of what versions are currently being used. You can also check the package’s repository for compatibility information.

Q3: What should I do if performance is significantly lower in release mode?

A3: Ensure that all images and assets are properly optimized for the web and consider using lazy loading for images to improve load times.

Conclusion

Addressing the errors occurring during Flutter web release builds can seem daunting, but by following the outlined steps and tips above, you should be able to identify and fix the underlying issues. Whether it’s updating dependencies, cleaning your project, or inspecting your code, tackling the problem methodically will get your web application up and running in release mode. Always review the console for output and logs as they can offer significant insights that aid in your debugging efforts. Happy coding!

Compass v1.1.0 · the recall consumption fix

We shipped nautilus-compass v1.1.0
12 hours after v1.0.0. v1.0.0 was the public stable cut. v1.1.0 fixes a
class of failure that v1.0.0 surfaces but does not catch · which we
caught in our own usage 5 hours after launch.

The bug we caught in production

A sister Claude Code dialog was supposed to publish a long-form article
to wechat using a 6-step quality pipeline (audit-gate, xhs-cards-embed,
specific account login flow). The pipeline was documented in cross-session
memory · a file called publisher_quality_pipeline_20260430.md.

Compass recall fired correctly · the file appeared in the agent’s
UserPromptSubmit hook output:

🟢 [3h old] memory/publisher_quality_pipeline_20260430.md
       audit-gate / xhs-cards-embed / wxid · v6 必须先过 critic 6 维评分再发布

The agent saw the title. Saw the 80-character description. Acted. It
did not Read the file body. The actual rules — how to walk audit-gate,
which wxid, what xhs-cards-embed structure looks like — those rules
were in the body. None of them entered the agent’s working context.

The agent then reproduced exactly the failure mode the file was written
to prevent: ad-hoc _tmp_publish_v8.cjs scripts, no critic round, wrong
login path.

The user’s diagnosis was sharp:

compass 召回到了 · 我没消费 · 这是 agent 层的人格漂移 · 不是 compass 本身的失败

That’s half right. Recall surfaced the right file. The agent failed to
consume. But the shape of the recall response made the failure easy —
we returned title + 120-char description. Easy to skim. Easy to assume
you have read it when you have only read the index.

This is structural. Not the agent’s fault.

The three-layer fix in v1.1.0

v0 · embed body in top-3 hits

Top-3 recall hits now embed the first 800 characters of post-frontmatter
body in an indented │ block:

🟢 score=0.84 · [3h old] memory/publisher_quality_pipeline_20260430.md
       audit-gate / xhs-cards-embed / wxid · v6 必须先过 critic 6 维评分
       │ # Publisher quality pipeline
       │
       │ Six-step pipeline mandatory before publishing to wechat:
       │ 1. audit-gate · V6 critic checks against 6 dimensions ...
       │ 2. xhs-cards-embed · embed cards into article body via ...
       │ 3. wxid login flow · use wxid `chunxiaox` not openid_of_first_follower
       │ ...
       │ … (+1273 more · Read publisher_quality_pipeline_20260430.md for rest)

The agent now has the rules in its working context. No additional Read
tool call required. Tail hits 4..K stay header-only to keep the response
bounded (~3KB total).

v1 · embed past-mistake body in anti-anchor alerts

Compass’s drift detector matches the current prompt against 35 negative
anchors learned from prior mistakes ("我猜应该是这样 · 反正用户不查",
"假装上次说定了的方案 · 用户应该忘了", …).

Until v1.1.0 the alert just said: “matched anti-anchor X with cos=0.625”.
Same problem as v0 — label visible, body invisible, agent shrugs.

v1.1.0 alerts now embed body from the most-relevant past lesson session.
Two-tier match: substring 6-gram against the anchor + lesson-type
frontmatter (Tier 1, precise) · falls back to recent drift!=green
sessions (Tier 2, the agent’s own self-reported slip-ups). Every alert
becomes actionable, not decorative.

v2 · detect “recall fired but not consumed”

The most direct signal: did the agent actually open any of the files
recall surfaced?

recall_consumption.py (new module) walks back through the live session
jsonl file, finds N most-recent recall blocks, extracts memory file
paths, then checks subsequent assistant turns for matching Read tool
calls. If recall surfaced N paths and 0 got read, that is the failure
signature.

Wired into:

• drift_check MCP tool result — runs even when the BGE daemon is
  unreachable, since the audit is pure file traversal
• mid_session_hook every 25 tool calls — only nags when ≥3 unconsumed
  AND ratio < 0.3 (real signal, not noise)

Tested on a 130MB / 32k-line session: 41 recall hits surfaced, 0 consumed.
Smoking gun for “label != consumption” drift.

V7 v0.2 · the governance plan that scales without templates

v1.0.0 shipped a thin V7 governance layer with three tools:
governance_dispatch (fan-out router), governance_audit (cross-agent
fake-closure scanner), governance_lock_check (L0 hash lock for the
immutable core). 13 MCP tools total.

v0.1 dispatch worked but it was a fan-out router — given channels=
[dev.to, x, github] it produced one bounty per channel via static dict
lookup. A user asked the right question:

千行百业有各种不同的任务类型永远不可能覆盖。

Right. Templates cannot cover the long tail of industries. The platform
side already solved this for publishing — channel adapters + anchor
pack registry — so adding a new channel or vertical = data change, not
code change.

v1.1.0 brings the same idea to decomposition. The new
governance_plan MCP tool reads two file-exported registries:

1. _platform_registry/agents_capabilities.json — what each executor
   declares it can do (id, outputs, optional domains, optional anchor
   packs)
2. _platform_registry/anchor_packs_phases.json — per-domain DAG of
   phases, each phase says requires_capability and depends_on

For each phase, V7 ranks executors by capability score (+10 capability
match, +5 domain match, +3 anchor pack match), picks the highest, emits
a queue file with depends_on_phase_ids so platform-side cron mints
bounties in the right order.

Verified on two domains:

• marketing/dev-tools → 4 phases routed V5/V5/V5/Kairos
• caishen-finance/audit → 5 phases · V6 wins for numeric-audit
  (V5 doesn’t declare it · V5 takes write+publish)

Adding medical/literature-review next: 1 row in platform_anchor_packs

• 1 row in platform_agents.metadata.capabilities[]. Zero V7 source
  change. Zero MCP tool surface change.

What stayed unchanged · the eval headlines

Eval numbers are still the v1.0.0 locked numbers from 2026-05-08:

v1.1.0 doesn’t move the eval numbers. It moves the consumption
numbers — the ratio of recall hits whose body actually lands in the
agent’s working context. We do not have a clean benchmark for that yet
(suggestions welcome) but in our own sessions it went from “skim the
title and proceed” to “rules-in-context by default.”

Try it

pip install nautilus-compass==1.1.0
# or
npm install nautilus-compass@1.1.0

Two papers on arxiv (drift detection + memory pipeline). 228 pytests
all green. MIT (anchors CC0).

Repo: github.com/chunxiaoxx/nautilus-compass

In-browser drift demo (no install): huggingface.co/spaces/chunxiaox/nautilus-compass

Postscript · what we believe

Recall != consumption · 看正文才算消费 · 不然命中等于零

Long-running agents drift. They forget rules they read three sessions
ago. They reproduce mistakes someone else already paid for. The fix is
not a smarter model · it is making the rules unmissably present in the
working context, then auditing whether they were actually consumed,
then making the audit cheap enough to run every 25 tool calls.

That is what v1.1.0 ships.

Remove text and watermarks from any image — one API call

Most image-cleanup APIs make you do half the work yourself. You draw a mask, you upload the mask, you cross your fingers. We got tired of that. POST /v1/image/remove-text finds the text for you, erases it, and hands back a clean image. One call. One URL. Done.

What it does

remove-text is an auto-detect-and-erase pipeline for visible text in images. Point it at any public image URL and it segments out the text regions on its own — watermarks, captions, signage, burned-in timestamps, the corner-of-the-frame copyright text — then inpaints what was underneath using the surrounding image context. The output is the same image, minus the text, with the rest of the scene left intact.

The endpoint is POST /v1/image/remove-text. The request is JSON. The response is the cleaned image. There is nothing else to configure for the default path.

If you want finer control, three fields are exposed:

• image_url — public URL of the source image. Required.
• regions — an optional list of bounding boxes. Pass these if you want removal restricted to specific parts of the image instead of the whole frame. Useful when there is legitimate text you want to keep (a sign behind the subject, a label on a product) and text you want gone (a watermark over the foreground).
• preserve_layout — boolean, defaults to true. With it on, the surrounding objects, edges, and structure stay where they are; the inpainting only fills the text region and blends to the local context. Turn it off only if you specifically want a freer regeneration of the masked area.

That is the whole surface. No mask uploads. No multi-step flow where you call a detection endpoint, post-process the boxes, and then call a separate inpainting endpoint. The detection and the inpainting happen on our side, in one round trip.

A few things worth being explicit about, since the FACTS block keeps me honest:

• It targets visible text. Watermarks, captions, signage, timestamps — the kinds of overlays that appear in pixels, not metadata.
• It works on arbitrary backgrounds. The inpainting uses surrounding context, so it handles sky, skin, fabric, asphalt, foliage — whatever happens to be behind the text.
• It is built so you do not have to author the mask. That is the whole point of the detection step happening on our side.

If you have used image-cleanup tooling before, you will notice the request body is almost empty. That is deliberate.

Why we built it

Every team that ships images at scale ends up needing this. Stock-photo workflows. Archive digitization. Re-use of legacy creative. Security-footage ingestion. Marketplaces scraping seller-supplied photos. The pattern is always the same: somebody, somewhere in the pipeline, baked text into the pixels, and now you need it gone before the image moves to the next stage.

The existing options are not great. The traditional path is: run a detector, get bounding boxes, draw a mask, post the mask plus the original image to an inpainting endpoint, hope the seams match. That is two or three services, two or three round trips, and a glue layer you now own. Most rival APIs expose only the inpainting half and expect you to bring the mask. Which is fine if you are a Photoshop user doing one image. It is a problem if you are a backend.

Our angle is simple: detect and remove in one call. We run our own segmentation step on the image, build the mask from the detected text regions, and then inpaint the masked area with surrounding context — all server-side, all in the same request. You do not see the mask. You do not need to see the mask. You get the finished image back.

A few design choices fall out of that:

• No mask upload path. We deliberately did not ship a “bring your own mask” mode at launch. The point of the API is that you do not need one. If you have very specific requirements about where removal can happen, that is what regions is for — coarse bounding boxes are enough to constrain the work, and far easier to author than a pixel-precise mask.
• preserve_layout defaults to on. The most common failure mode of generative inpainting is that it cheerfully invents new objects in the cleared area. For text removal specifically, you almost never want that — you want the same scene, minus the text. So that is the default behavior, not an opt-in.
• Single endpoint, single response. No job IDs, no polling, no callback URLs for the default case. You call it, you get the image. We host the infrastructure so you do not have to figure out batch queues for what is, conceptually, a one-shot transform.

The thing we want to make boring is the part that is usually annoying: getting a clean image out of a dirty one.

Quickstart

The minimal call is one curl. Drop your API key in, point image_url at any reachable image, and you are done.

curl -X POST https://api.pixelapi.dev/v1/image/remove-text 
  -H "Authorization: Bearer YOUR_API_KEY" 
  -H "Content-Type: application/json" 
  -d '{"image_url": "https://example.com/source.jpg"}'

Same thing in Python using requests:

import os
import requests

API_KEY = os.environ["PIXELAPI_KEY"]

resp = requests.post(
    "https://api.pixelapi.dev/v1/image/remove-text",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "image_url": "https://example.com/source.jpg",
    },
    timeout=60,
)
resp.raise_for_status()
result = resp.json()
print(result)

That covers the default case: full-image scan, layout preserved, text gone.

If you want to scope the removal — say, you only want to clean the bottom-right corner where the timestamp lives, and you want to leave the rest of the image untouched even if there happens to be incidental text in it — pass regions:

resp = requests.post(
    "https://api.pixelapi.dev/v1/image/remove-text",
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "image_url": "https://example.com/cam-frame.jpg",
        "regions": [
            {"x": 1500, "y": 1000, "width": 380, "height": 60}
        ],
        "preserve_layout": True,
    },
    timeout=60,
)

And that is the API. There is no step three.

Use cases

Cleaning up timestamps burned into security-camera frames

If you operate any kind of CCTV or DVR pipeline, you know the problem. The camera firmware burns a timestamp directly into every frame — usually white text in a corner, sometimes with a black background block, sometimes not. The metadata is also in the file, so the burned-in copy is redundant. But the moment you want to do anything downstream — train a model on the frames, use the footage in an internal incident report, hand a snapshot to a customer — that timestamp is sitting there in the pixels and it cannot be turned off retroactively. Running each frame through remove-text with a regions box around the corner where the timestamp lives gives you a clean frame, with the rest of the scene unchanged. Wire it into your ingest path and the burned-in copy never leaves your pipeline. The metadata stays where it belongs — in the file headers — and the visual frame is yours to use.

Stripping captions off stock-photo previews you’ve licensed

Stock-photo workflows are full of friction. You browse, you license, you download the high-resolution version — and the licensed copy is supposed to come without the preview watermark. In practice, half the asset systems we have talked to end up with watermarked previews mixed into their working folders, either because someone grabbed a comp earlier in the process, or because a partner sent a reference file by mistake, or because the asset got cached at the preview stage and the clean version never replaced it. For images you have legitimately licensed, remove-text lets you reclaim those preview copies without re-downloading from the source. Detection handles the irregular placement of caption strips — corner, diagonal, full-frame tile — and the inpainting fills the area using whatever is around it. You end up with a usable working file from an asset you already paid for.

Erasing brand markings before re-using your own product imagery in a new campaign

Every brand team eventually hits this: a beautiful product photo from a previous campaign, where the photographer (or the agency, or the in-house designer) baked the campaign tagline or the old SKU label into the corner. Now you want to re-use the shot for a new campaign, and that old text is a non-starter. The traditional fix is a designer round-trip — open the file, clone-stamp the area, retouch the edges, save out, version, ship. For one image, fine. For two hundred, painful. remove-text handles the cleanup programmatically: point it at the originals, get back versions with the legacy markings gone, and let your designers spend their time on the new creative instead of erasing the old. With preserve_layout on, the product itself stays exactly where it was — only the text disappears.

Pricing

Pricing is per-call, flat, no tiers to negotiate.

• Credits per call: 16
• Price in INR: ₹0.011 per call
• Price in USD: $0.00013 per call

That is the cleared-image, end-to-end price. Detection plus inpainting. No separate charge for the segmentation step. No surcharge for using the regions field. If the call succeeds, it costs 16 credits; if it fails, it does not.

At those numbers, a hundred thousand images is around ₹1,100 / $13. Most teams discover that the cost of running this in production is dwarfed by the cost of not running it — the manual cleanup hours, the back-and-forth with vendors over watermarked deliverables, the asset-management tickets that pile up because someone has to find a designer to redo a corner of a photo.

Try it

Sign in at https://pixelapi.dev/dashboard to get your API key. New accounts come with starter credits, so you can hit the endpoint with one of your own images before deciding anything.

Full reference for the request body, error codes, response format, and the regions and preserve_layout fields lives in the docs at https://pixelapi.dev/docs.

If you ship images at any kind of scale, give remove-text a real workload — a folder of timestamps, a batch of legacy product shots, a directory of licensed previews — and see what comes back. The whole point of this endpoint is that there is nothing else to learn. One URL in, one clean image out.