[FanouZeng-TT]

Category (Required)

• Core Protocol: Changes to the base communication layer, global context, or breaking refactors. (Requires Technical Council approval)
• Governance/Contributing: Updates to GOVERNANCE.md, CONTRIBUTING.md, or CODEOWNERS. (Requires Governance Council approval)
• Capability: New schemas (Discovery, Cart, etc.) or extensions. (Requires Maintainer approval)
• Documentation: Updates to README, or documentations regarding schema or capabilities. (Requires Maintainer approval)
• Infrastructure: CI/CD, Linters, or build scripts. (Requires DevOps Maintainer approval)
• Maintenance: Version bumps, lockfile updates, or minor bug fixes. (Requires DevOps Maintainer approval)
• SDK: Language-specific SDK updates and releases. (Requires DevOps Maintainer approval)
• Samples / Conformance: Maintaining samples and the conformance suite. (Requires Maintainer approval)
• UCP Schema: Changes to the ucp-schema tool (resolver, linter, validator). (Requires Maintainer approval)
• Community Health (.github): Updates to templates, workflows, or org-level configs. (Requires DevOps Maintainer approval)

Description

Complete Checkout is commented as an "Atomic Inventory Reservation and Completion", but the reservation, the order insert and the checkout update were three independent writes. A technical failure in the middle answered 500 without rolling anything back:

• an order write failure left stock decremented for a checkout that never completed;
• a checkout write failure additionally left an order row the checkout does not reference, so the client could retry and consume stock again.

This change runs the reservation, saveOrder and saveCheckout inside one better-sqlite3 transaction, so any failure rolls the three tables back together and the client can retry safely. An out-of-stock line short-circuits the transaction instead of the previous hand-rolled release of already-reserved items. Webhook delivery stays outside the transaction because external I/O must not hold the SQLite write lock.

Scope

Only the Node reference completion path and its data helper change. The HTTP contract, error envelopes, payment handling, webhook signing/delivery semantics, Python sample and schemas are untouched. The Python idempotency-race fix (#245) is a different failure mode (concurrent requests, one winner) and a different language/runtime; the Node referential-integrity and concurrency candidates are tracked separately and do not overlap these three files.

Tests

Fail-before (with the source changes reverted, fault injected by a SQLite trigger):

• an order write failure rolls back the inventory reservation — expected stock unchanged, got 99 instead of 100.
• a checkout write failure rolls back the order and the reservation — expected stock unchanged, got 98 instead of 99.

Pass-after:

• npm test --prefix rest/nodejs — 173 passed, 0 failed
• npm run build --prefix rest/nodejs
• npx prettier@4.0.0-alpha.8 --check on the three changed files
• git diff --check