Per-object `/batch` (non-atomic default) stops at the first failing record — no `NOT_ATTEMPTED`, `succeeded + failed != total`, the valid tail row never lands

[huangyiirene]

Symptom

POST /api/v1/data/showcase_private_note/batch with no options (so atomic defaults to false on this door) and three records — valid, failing, valid — answers:

200 {
  "total": 3,
  "succeeded": 1,
  "failed": 1,
  "results": [ { idx 0: ok }, { idx 1: VALIDATION_FAILED } ]
}

Four things are wrong in one body:

• only 2 results for 3 records;
• no NOT_ATTEMPTED entry for idx 2 — the caller cannot tell it was skipped;
• succeeded + failed (2) != total (3), so the counters do not reconcile;
• the third, valid record returns 0 rows on re-read — it was never attempted, and no amount of reading the response says so.

Expected per ADR-0119 D4 (atomic defaults false on this door): valid rows land, and neither valid row is blocked by the other. Reproduced 2/2.

Two same-run controls isolate it:

variant	result
continueOnError: true	3 results, both valid rows persisted
atomic: true	the correct ROLLED_BACK / VALIDATION_FAILED / NOT_ATTEMPTED triple

(The rest of the checklist item passes: the discovery bit matches live behaviour incl. $ref parenting and BATCH_UNRESOLVED_REF; atomic:false on the cross-object door is refused 400 BATCH_NOT_ATOMIC; cross-object rollback held at both write-time and validation-time failures; BATCH_TOO_LARGE brackets exactly at 200/201 on all three doors.)

Root cause

The non-atomic loop breaks out of the record loop on the first failure, while buildBatchDataResponse (packages/metadata-protocol/src/protocol.ts) reports total = records.length. The un-attempted tail is therefore invisible twice over: it produces no results[] entry and it is not counted in either bucket, so the arithmetic mismatch is the only trace of it.

Same family, recorded in the run's smaller observations: per-object bulk counters under-report whenever a row fails without continueOnError — worth fixing in the same pass. Related but distinct: #4620 (closed/completed) covered deleteManyData / updateManyData atomicity, not this loop's break-and-miscount.

Reproduction

1. Boot showcase on a fresh isolated file DB (SqlDriver / better-sqlite3); authenticate as admin@objectos.ai.
2. POST /api/v1/data/showcase_private_note/batch with no options key and three records: valid, one that fails validation, valid.
3. Observe 200 {total:3, succeeded:1, failed:1, results:[idx0 ok, idx1 VALIDATION_FAILED]} — no idx 2 entry.
4. Re-read the object: the third record is absent (0 rows).
5. Controls: repeat with options.continueOnError = true → 3 results, both valid rows persisted; repeat with options.atomic = true → ROLLED_BACK / VALIDATION_FAILED / NOT_ATTEMPTED.

Source

Extracted from the QA run #7463 (framework a86db17).

[os-zhuang]

Claimed — domain:metadata seat.

• Session: session_016gd2bypaK4KYs78q8RP38G
• Branch: claude/issue-7539-batch-not-attempted
• Worktree: ../objectstack-7539 (dedicated)
• File surface: packages/metadata-protocol/src/protocol.ts — the non-atomic batch loop and buildBatchDataResponse, plus new pins.

The dispatch splits this card in two, because the halves have different confidence levels:

(A) The reporting defect is unambiguous and is being fixed outright. Under every reading of the semantics, a response whose succeeded + failed != total and which silently omits results[] entries is wrong. NOT_ATTEMPTED entries and reconciling counters are in scope, along with the same-family under-reporting the card notes for per-object bulk counters.

(B) Whether the valid tail row should LAND is a semantics question, and the dev is told to let ADR-0119 D4 rule it rather than guess. The card states the expected behaviour is that both valid rows land — but the same run shows continueOnError: true already produces exactly that, which would make continueOnError redundant if atomic:false alone meant the same thing. If D4 settles it, the dev implements it and quotes it. If D4 does not settle it, the dev ships (A) only and reports the open question rather than inventing the semantics — the two readings produce different products, and shipping the wrong one silently is worse than shipping half.

#4620 is explicitly out of scope (it covered deleteManyData/updateManyData atomicity, not this loop's break-and-miscount).

---

Generated by Claude Code

[claude]

Implemented — PR #7581 (draft).

ADR-0119 D4 RULES ON (B), and it rules against this card's "Expected" line. D4's test plan item 5 pins non-atomic batches to "behave exactly as before", and D4's body defers continuation to continueOnError — "whose own description already scopes it to atomic=false". That description (BatchOptionsSchema.continueOnError) reads: "If true (and atomic=false), continue processing remaining records after errors."

So atomic: false alone promises best-effort that stops at the first failure; continueOnError is the knob that buys continuation. The dispatch's suspicion was correct — if atomic: false alone continued, continueOnError would be inert.

Symptom 4 ("the third, valid record never lands") is therefore correct behaviour, not a defect. The caller's remedy is continueOnError: true, which the skipped row's message now names. The break is unchanged.

Symptoms 1–3 are real and are fixed. results now covers all total records; the un-attempted tail carries errors[0].code: NOT_ATTEMPTED — the registered ADR-0112 code the atomic arm has emitted since #4793; and succeeded + failed === total === results.length. The same-family under-report the card notes for per-object bulk counters (updateManyData / deleteManyData) is fixed in the same pass through one shared reconciler rather than a third and fourth copy.

Both same-run controls were re-measured at base 9051802 and behave exactly as recorded (continueOnError: true → 3 results, both valid rows persisted; atomic: true → ROLLED_BACK / VALIDATION_FAILED / NOT_ATTEMPTED). They are kept as GUARD cases, green in both directions. Reverse verification turned exactly the 8 predicted pins red and left all 4 GUARDs green; one missed prediction is disclosed with its cause in the PR.

#4620 is not folded in, per the dispatch.

---

Generated by Claude Code

[os-zhuang]

ACCEPT — PR #7581, reviewed and being driven to landing.

The card's "Expected" line was wrong, and the dev is right to have said so in the open. This card asserted that under ADR-0119 D4 both valid rows should land on a non-atomic batch. They should not. D4's test plan item 5 pins non-atomic batches to "behave exactly as before", and D4 defers continuation to continueOnError, "whose own description already scopes it to atomic=false" — and that description reads "If true (and atomic=false), continue processing remaining records after errors." So atomic: false alone is best-effort that stops at the first failure; continueOnError is what buys continuation. If atomic: false alone continued, continueOnError would be inert — declared-but-unenforced, the exact shape ADR-0049 exists to eliminate. The tell was in the card's own evidence: the continueOnError: true control already produced the "expected" result. Symptom 4 ("the third, valid record never lands") is therefore correct behaviour, not a defect, and the break is deliberately unchanged. Recording this here so the next reader inherits the corrected premise rather than the card's original claim.

What ships — the three real defects, all of them reporting defects:

• results now covers all total records; the un-attempted tail carries errors[0].code: NOT_ATTEMPTED, the registered ADR-0112 code the atomic arm has emitted since fix(metadata-protocol)!: batch 逐行结果迁移到 BatchOperationResultSchema 形状 —— 方案 B 已拍板,硬切 + 诚实迁移说明(Blocked-by #4620) #4793.
• succeeded + failed === total === results.length, with failed counting every non-success row — matching buildRolledBackBatchResponse, so one reading of the envelope serves both arms. No schema field added or removed.
• The same-family under-report on updateManyData / deleteManyData is fixed through one shared reconciler, not a third and fourth copy of the arithmetic.

Verified independently of the report, not from its own claims:

• The boundary the value has to cross. REST is a genuine pass-through for this surface — const result = await p.batchData!({…}); res.json(result); with no status or counter derivation — so the wire shape moves exactly with the protocol and the fix survives to the client.
• No copy of the old position survives. The two NOT_ATTEMPTED files the PR does not touch (protocol.batch-row-conformance.test.ts, protocol.bulk-record-not-found.test.ts) pin only atomic-arm cases and all-success runs, unaffected by the non-atomic reconciler. The four assertions that literally encoded the bug are rewritten, each with the old line quoted in a comment.
• Generated-artifact path. The diff touches content/docs/references/api/batch.mdx, which .gitattributes routes to merge=os-regen. main's one new commit (97b6658) also touches that tree but a different file (content/docs/references/qa/testing.mdx), so the two are disjoint — no residue for the driver locally and no textual conflict in the queue, where no custom driver runs.
• Fixes is the right first line: no half of this card is left in the decision box — (B) was answered from the record rather than deferred.
• Gate jobs read personally: ESLint success, TypeScript Type Check success, 26/26 green.

The disclosed missed prediction is a good-run signal, not a blemish. The semantics GUARD was predicted green at base and came back red, because two assertions about results[2]'s shape had been placed in a control whose job is the semantics — and at base results[2] does not exist, that being the defect under repair. A both-directions guard must not depend on the thing being fixed. Correctly diagnosed and correctly relocated; reverse verification then turned exactly the 8 predicted pins red and left all 4 guards green.

#4620 stays out of scope, as dispatched.

---

Generated by Claude Code