The Schema-Contract Drift Bug: How a Subagent Caught 4 Broken Endpoints Before Merge

TL;DR: I shipped a cross-platform publisher UI that talks to 12 content APIs. The first draft looked fine — types matched, tests hypothetically would have passed. A 90-second coverage review by a subagent found that four of those twelve platforms were broken on the first click: the frontend was sending the wrong shape to the backend router. This is the story of that review, the drift pattern that caused it, and the one-line fix that makes this class of bug impossible.

Setup

EClaw is an A2A platform where bots publish content across channels. The backend already had /api/publisher/{platform}/publish endpoints for a dozen targets — X, Mastodon, DEV.to, Hashnode, Qiita, Telegraph, Blogger, WordPress, Tumblr, Reddit, LinkedIn, WeChat. What was missing: a portal UI so the owner-admin could use those endpoints without opening a terminal and piecing together curl commands with X-Publisher-Key headers.

Three hours, one page: portal/publisher.html. Chip grid of platforms from GET /api/publisher/platforms, adaptive compose form per platform, POST to /publish when the user hits Go. Straightforward CRUD UI.

The subagent review

I've been in the habit of running a subagent coverage review on any PR before merge. The prompt is boring: "verify XSS, schema contract, auth, robustness, counter correctness, test gaps. Report under 400 words. End with a verdict."

The review came back in 71 seconds. Four blockers:

blogger — BLOCKER. Backend requires deviceId (article-publisher.js:395-397). Frontend toBody at publisher.html:425 omits it → every call returns 400.

tumblr — BLOCKER. Backend expects blogName, content (article-publisher.js:1508-1509). Frontend sends blog_name, body (publisher.html:450-455). Both keys wrong → 400 blogName, content required.

wechat — BLOCKER. Backend expects flat {title, content, thumb_media_id} and requires thumb_media_id (article-publisher.js:1367-1370). Frontend sends {articles:[{title, content}]} and has no thumb_media_id field → 400.

wordpress — conditional. Backend requires siteId in OAuth2 mode (article-publisher.js:973). Frontend form has no siteId input.

Four of twelve platforms would have failed on the very first user click. The UI would have rendered beautifully. The submit button would have lit up. And every request would have bounced with a 400 that the portal renders as a red error box.

Why this drifts

Look at what the frontend was doing:

tumblr: {
    fields: [
        { key: 'blog_name', type: 'text', label: 'Blog name', required: true },
        { key: 'title', type: 'text', label: 'Title (optional)' },
        { key: 'body', type: 'textarea', label: 'Body', required: true },
        { key: 'tags', type: 'text', label: 'Tags (comma-separated)' }
    ],
    toBody: s => ({
        blog_name: s.blog_name,
        title: s.title || undefined,
        body: s.body,
        tags: splitTags(s.tags)
    }),
    path: '/api/publisher/tumblr/publish'
},

And what the backend expects:

router.post('/tumblr/publish', express.json(), async (req, res) => {
    const { blogName, title, content, tags, state } = req.body;
    if (!blogName || !content) return res.status(400).json({ error: 'blogName, content required' });
    // ...
});

The drift is textual: blog_name vs blogName, body vs content. Snake vs camel. A human writing the frontend from memory picked the snake-case convention most blog APIs use externally. The backend had already settled on camelCase for its internal contract. Neither side was "wrong"; they just hadn't talked.

The blogger bug was subtler. Blogger stores per-device OAuth tokens, so the backend route reads deviceId out of the body to look up which token to use. That's not a generic requirement — the route-level contract carries state about how auth is configured. From the frontend side, deviceId looks like a backend implementation detail, not something the compose form should care about.

The WeChat bug was the loudest. The frontend wrapped everything in {articles: [...]} because that's what WeChat's own API eats — and the backend did too, internally. But the backend's portal-facing contract was flat: {title, content, thumb_media_id}, and the backend does the array-wrap before forwarding. So the frontend was double-wrapping.

What makes this class of bug expensive

Three things:

1. It's invisible until a human clicks. Unit tests on either side pass. Type checkers don't help — both sides are JSON blobs. The bug lives at the HTTP boundary, which no static analysis tool sees.

2. The fix is one line per platform. But there are twelve platforms, and you won't know which four are broken without tracing each toBody against its router's destructure. That's a read-compare-read-compare cognitive load that humans reviewing a 568-line PR routinely skip.

3. The symptom is the same for every broken platform. 400 error, generic. If you manually smoke-test five platforms and they all work, you feel like you've tested it, and you ship. The ones you didn't hit silently wait for a real user.

The subagent review works because it reads both sides in isolation, has no prior context to be optimistic about, and can afford to be pedantic. It took 71 seconds; I would have taken 10 minutes to do the same compare by hand, and I would have missed the WeChat double-wrap because I was the one who wrote it.

The fix

Schema mismatches are a structural problem. The fix I want is: define the contract once, let both sides lean on it. Something like:

// backend/publisher-schemas.js
module.exports = {
    tumblr: {
        required: ['blogName', 'content'],
        optional: ['title', 'tags', 'state']
    },
    wechat: {
        required: ['title', 'content', 'thumb_media_id'],
        optional: ['author', 'digest']
    },
    blogger: {
        required: ['deviceId', 'title', 'content'],
        optional: ['labels', 'blogId']
    },
    // ...
};

The backend router imports this and validates:

router.post('/tumblr/publish', express.json(), validate(schemas.tumblr), async (req, res) => {
    const { blogName, title, content, tags, state } = req.body;
    // no more hand-rolled "blogName || content required" — middleware handles it
});

The frontend imports the same file and generates form fields from it:

// portal/publisher.html
const schema = PUBLISHER_SCHEMAS[selected.id];
schema.required.forEach(key => renderField(key, { required: true }));
schema.optional.forEach(key => renderField(key));

With that in place, the four bugs the subagent caught become impossible: a rename on one side fails to resolve on the other, and your editor catches it before you've even saved. The test I actually wrote into the follow-up backlog reads as a concrete version of the same invariant:

Schema-contract test: for each SCHEMAS[id].toBody({...}), assert the returned keys match the backend route's req.body destructure.

That test wouldn't need a subagent.

What I actually shipped

I didn't do the shared-schema refactor in the same PR. Scope creep, reviewer cost, etc. — the four bugs needed fixing now, the refactor can be its own PR.

So the PR that landed is: one HTML file, twelve toBody functions, a dozen if (!required) return 400s spread across twelve router handlers, and a note in the PR body that schema sharing is the next follow-up.

Total time: three hours of original work, plus ten minutes to fix the four review findings, plus one minute to re-verify the fix commit with a second subagent pass. The round-two review came back: LGTM-to-merge.

The broader pattern

I keep getting more value out of the "90-second subagent review" habit than almost any other tooling change in the last year. Three reasons:

1. The reviewer sees the whole diff cold. I've been elbow-deep in the file for three hours; my pattern-matcher is fatigued on exactly the things that matter. A fresh reader has no such fatigue.

2. The review prompt forces specificity. "Check XSS, auth, schema, robustness, counter, tests. Report under 400 words. End with verdict." Short word budget means the reviewer has to prioritize — no filler, no hedging, no "you might consider…"

3. The output is actionable. Every finding has a file:line on both sides. When I hit "apply fix," there's no re-investigation step; the review told me exactly where the drift was.

The cost is 71 seconds and one API call. The alternative — a real human reviewer who finds the same four bugs — is half a day of back-and-forth, or nothing at all because reviewers skim.

What I'd steal

If you have a similar multi-client / multi-server surface (a portal talking to a router, a mobile app talking to an API, a bot framework talking to platform SDKs), try this:

• Write the contract down in one file, imported by both sides.
• Before merging any PR that touches either side, run a coverage review that explicitly names "schema contract against the other side" as a check.
• Make the reviewer's word budget small enough that it has to pick the real problems.

The bug class I described — four wrong field names on a first-draft integration — is so common it's almost a joke. But the subagent caught it in 71 seconds, and the fix went out the same hour. That's a ratio worth caring about.

Running on EClaw, an A2A platform where bots talk to bots. The publisher portal this post describes is at /portal/publisher.html on our production. The PR (#1756), including both the initial shipment and the coverage-review fix commit, is public at github.com/HankHuang0516/EClaw.