docs: name the two divergences measured against the live service

[TonyStack2026]

Two differences between this emulator and a live MaxCompute project were measured on the wire earlier
and never written down — docs/protocol.md in fact still said the service's HTTP status had not been
read back. This documents them and corrects that sentence. No behavior changes.

What the docs now say

README gains Known divergences from the real service (plus its Chinese mirror), one section per gap,
each with the scenario, both readings, who observes it and what to assert instead:

• A refused chunked merge comes back with different codes. Service: 500 InternalServerError with
  ODPS-0421213 … The merged file's signature does not match! when the assembled payload does not match
  the MD5 in the merge body, and 409 ObjectAlreadyExists with ODPS-0421121 when the target name
  already exists. Emulator: 400 InvalidParameter and 400 ResourceAlreadyExists. What agrees is worth
  depending on and is stated as such — which parts a refusal consumes or keeps, and 404 NoSuchObject
  for a manifest naming a part that was never uploaded.
• A TABLE resource may point at a table that does not exist. Service: 404 NoSuchObject with
  ODPS-0422111: Table not found, nothing created. Emulator: 201 Created, the resource is listed and
  ?meta echoes x-odps-copy-table-source. A local run cannot catch the typo'd or not-yet-created name;
  the row says to create the table in the seed or assert it in fixture setup.

The section then lists what the readings do not cover, rather than letting them read as universal: one
project, one endpoint, plain http:// (no TLS termination or gateway in the path), Linux/amd64, and only
these refusal shapes — so another region, another service version, a public HTTPS path, a BSD/macOS native
build, and any third divergence are all explicitly unmeasured.

docs/protocol.md: the （HTTP 状态未回读） note is replaced by the measured codes plus the round and
conditions they came from, and the pointer to the new section. That row also attributed the emulator's
duplicate-target merge answer to 400 InvalidParameter; the emulator answers 400 ResourceAlreadyExists (internal/server/resources.go, asserted by resources_test.go), so the row now
names it correctly. The same stale sentence in a tests/python/run.py comment is fixed — comment only.

Verification

The commands the new text cites were run against this tree, not quoted from memory:

check	result
go test ./internal/server -run TestResourceRESTContract -count=1	ok (0.118s)
python tests/python/run.py http://127.0.0.1:<port> test_project (PyODPS 0.13.2)	33 passed, 0 failed
POST /projects/test_project/resources with x-odps-resource-type: TABLE and x-odps-copy-table-source naming a table that was never created	201, ?meta → 200 with the reference echoed, payload download → 400 UnsupportedOperation, delete then ?meta → 404; nothing left behind
git diff --check	clean; no .go file, no server behavior, no test assertion touched

The third row is why the doc can print 201 Created: the earlier measurement recorded that merge/create
call as "accepted" through a client that does not surface the status, so the number is now a reading.

Not in this PR, on purpose

No error-code or status-code change, no feature flag, no refactor, no new test case. Aligning either row
with the service is a contract decision — both codes are asserted by tests in this repository today — and
until it is taken, the section is the tracking list. Two honesty notes inside it: row 2 has no case in
this repo (the Go test registers a TABLE resource against a table that does exist), and the
declared-byte-count reading in the same docs/protocol.md cell ("4400 申报 / 304 实际") predates this
change and was not re-measured here, so this PR does not vouch for it beyond pointing at it.

Review request: my account cannot attach reviewers or assignees on this repo (pull: true, push: false, triage: false — re-checked at the time of opening), so dingxin-tech is not set here; the link is
sent directly instead.

---

Updates on this PR (kept as appends; the text above is unchanged)

f11ce23 - version scope. The Quick start pins the 1.1.0 image, and that image has no resource plane:
the PyODPS probe against a 1.1.0 build (2026-09-21) ended at 1 passed, 29 failed, those calls answered
as not found. So the two rows now say they describe main, and anyone needing the resource plane is pointed
at a source build or a post-1.1.0 tag. Docs only.

47d1220 - one claim had no archived log behind it. The ?rOpMerge row said the service "only validates
an upper limit" and accepted a 304-byte merge declared as 4400. Re-measured on 2026-10-08 against a live
project (single part, correct manifest MD5, header declaring 4400): accepted, and the published resource
is exactly those 304 bytes - so the acceptance half stands with a fresh reading, the upper-limit half does
not, and the row now stops where the readings do. The README's "what these readings do not cover" bullet also
names the third, opposite-direction difference instead of implying two rows is the whole list: the service
ignores a wrong declared total, this emulator refuses it (documented in docs/protocol.md, because it is the
emulator being stricter rather than missing a capability).

Verification for 47d1220: citation check 12 claims over 3 docs and 11 logs, 0 failures, with eight
counter-example directions (including two new ones aimed at the logs added in this commit) all rejected;
link/anchor check 0 broken; the reading is reproducible from the public request shape - post one part,
then send ?rOpMerge with the correct manifest MD5 and a declared total that does not match the bytes. go test ./internal/server -run TestResourceRESTContract (ok) and the PyODPS contract probe
(33 passed / 0 failed) were run on f6d9e78 - this commit changes documentation text only, and neither can
be moved by it, so they are not claimed here for 47d1220.

25f734d - the version-scope claim, checked against the artifact. The sentence above about 1.1.0 was
backed by a probe run against a 1.1.0 source build. What a reader actually pulls is the image, so it was
re-verified against maxcompute/maxcompute-emulator:1.1.0 (digest sha256:57d1d257…dee2d3) today:
GET /projects/<project>/resources → 404 UnsupportedOperation: unsupported endpoint, /capabilities
returns 11 keys and none of them is resources/functions/unsupported, and the current 33-case PyODPS
probe ends at 1 passed, 32 failed - the one case that passes there passes because the whole endpoint is
refused. The source-build run from 2026-09-21 stays as corroboration. README text only, both languages;
nothing else moves.

2b73069 - three more differences found while re-verifying row 1. Re-running the duplicate-target merge
today against a live project and against main confirmed the headline (409 ObjectAlreadyExists +
ODPS-0421121, so row 1 stands - not overturned) but exposed three further differences in the same
request, now documented inside row 1 instead of as new rows:

same ?rOpMerge	service	emulator
no x-odps-resource-merge-total-bytes	400 InvalidParameter + ODPS-0420051: Missing header... - header required	header optional; answers for the target (400 ResourceAlreadyExists)
wrong declared total + target exists	409 - target check first, declared total never compared	400 on the declared total - emulator's own check first
the part a pre-read refusal keeps	addressable by name, absent from every listing (exact-name prefix query included)	addressable by name and listed

Two consequences stated in the README: the advice to "assert the part state" is now explicitly by name
(Resource.exists() / ?meta) because a list_resources(prefix=...)-based cleanup assertion reads clean in
the cloud while the object still exists; and the header-mandatory asymmetry means a client that omits it
passes locally and fails against the service - whether the emulator should require it too is a contract
decision, left open here (this PR changes documentation only).

Disclosure on how the readings came about: my first probe today omitted that required header, hit 400, and
briefly looked like it contradicted the documented 409. Running the same cell with the header correct, absent,
and wrong is what separated "the service changed" from "my request was different". Verification for this
commit: the citation check covers 16 claims over 3 docs and 16 logs with 0 failures, and 11 counter-example
directions all reject (two new ones aimed at these logs - a service-only 409 claimed as an emulator reading,
and a listing reading the emulator log never printed). Link/anchor check 0 broken. Docs only, so the Go test
and the PyODPS probe are not claimed as re-run on this head; CI runs the full suite on it.

3d6ca56 - second verification round, recorded. Both rows were re-measured today and neither was
overturned: row 1's 409 ObjectAlreadyExists + ODPS-0421121 reproduced, row 2's 404 NoSuchObject +
ODPS-0422111 reproduced for a table exist_table confirms missing. The provenance paragraph now names both
rounds with dates rather than one range, and states the trap that produced a false alarm this morning: the
first attempt at row 1 answered 400 InvalidParameter because the request omitted x-odps-resource-merge-total-bytes,
which the service requires (ODPS-0420051: Missing header in HTTP request) and which is checked before the
target exists - so a 400 there is a different failure, not a changed answer for the duplicate target.
Docs only; the emulator's answers are unchanged. Citation check: 18 claims over 3 docs and 18 logs, 0 failures,
12 counter-example directions all rejected (two new ones aimed at today's row-2 logs).

aad7b0a - self-review pass over the section. Six hand edits to the same section had left it
inconsistent with itself, which only shows when you read the rendered section rather than the diffs: the
Chinese README carried the "how to re-measure against a live project" recipe twice and the "stated as
unverified" lead-in twice; row 1 still said "two refusal shapes were compared" and "only the shape of the
refusal differs" after the section grew to five differences (one of them about listing visibility, not
shape); the closing line still asked for "two runs agreeing", which the second round had already done. All
corrected, plus the reproduction recipe now warns that a hand-built ?rOpMerge without
x-odps-resource-merge-total-bytes is answered 400 (ODPS-0420051) before the target is examined - the trap
this section hit during its own re-measurement today. Wording and provenance only; no claim, reading, status
code or test changed. Citation check unchanged at 18 claims / 18 logs, 0 failures, 12 counter-example
directions rejected; link check 0 broken.

[TonyStack2026]

Adding a second commit for a discoverability problem the first one had, on README only (no behavior touched).

The Quick start pins maxcompute/maxcompute-emulator:1.1.0, and that tag has no resource plane at all: running the PyODPS contract probe against a 1.1.0 build (2026-09-21) ended at 1 passed, 29 failed, those calls answered as not found. Sitting right under the Quick start, the two rows read like behavior to expect from the image a user just pulled - when on that tag there is nothing to diverge from.

f11ce23 says which build the rows describe (main), keeps the probe reading with its date, notes that the case count grows with the probe while the missing-capability answer is what stayed, and points anyone needing the resource plane at a source build or a post-1.1.0 tag.

Re-run against the tree as it now stands (04:4x): citation check - 10 claims over 3 docs and 9 logs, 0 failures, all six counter-example directions still REJECT; link/anchor check - 0 broken. The Go test (TestResourceRESTContract ok) and the PyODPS probe (33 passed / 0 failed) were run on f6d9e78; this commit changes README text only, so it cannot move those two, and I am not claiming them for f11ce23.