[ThomasK33]

Why

The notes row in docs/explanation/wire-compatibility.md keeps a stale
expected_notes_ref_sha on the legacy body forms (POST .../notes and
the deprecated DELETE body) at 412 precondition_failed. Its reason
named only "the SDKs" and result.status. The new SDKs on SDK main
fa4c317 send two of the three note writes to forms that already answer
409, but their note create still gets our 412. The row did not say
so. #648 fixed the same gap in the commit-pack, diff-commit and
restore-commit rows, and its merge record on #647 listed this row as a
follow-up.

What changed

The notes row now states:

1. What SDK 1.17.1 (@pierre/storage, pierre-storage and
   code-storage-go) does. It sends every note write in the body form
   and builds a RefUpdateError whose status is result.status, here
   precondition_failed. Upstream's 409 has result.status
conflict.
2. What the new SDKs (@pierre/sdk, pierre-sdk and
   github.com/pierrecomputer/sdk/go) do. An append goes to
   POST .../notes/append and a delete sends its guard as the
   expected_notes_ref_sha query parameter, so both get our 409. A
   note create still sends POST .../notes with the guard in the body.
   The SDKs pick RefGuardError only for the code ref_guard_failed,
   so our 412 becomes a RefUpdateError. A caller that retries a
   create with current_sha works against upstream and fails against
   open.storage. A delete that sends its guard only in the deprecated
   body field expected_ref_sha (new Python and TypeScript SDKs) gets
   the 412 too.
3. That the deviation ends when gate G1 of api: problem-details later tiers (specific codes, instance, result envelope, git/LFS writers, problem+json) — held on SDK trigger #352 fires, with links to
   api: problem-details later tiers (specific codes, instance, result envelope, git/LFS writers, problem+json) — held on SDK trigger #352 and Upstream drift (SDK main fa4c317): the new SDKs branch on ref_guard_failed; end the #533 412 stale-guard deviations when G1 fires #647.

No code changes.

Evidence

I read each claim in the SDK source (github.com/pierrecomputer/sdk):

• Tag packages/code-storage-go/v1.17.1 (35610abb, all three packages
  at 1.17.1). Body forms: Go repo.go:716 (delete) and :775
  (create and append), TypeScript src/index.ts:1336, :1383 and
  :1447, Python pierre_storage/repo.py:1705-1725 and :2417-2436.
  Error status from result.status: Go repo.go:722-733 and
  :781-796, TypeScript src/index.ts:1340-1350 and :1451-1465,
  Python pierre_storage/repo.py:2491-2503.
• SDK main fa4c317, routes: Go go/repos_gen.go:1403-1406 (append),
  :1447-1450 (create), :1476-1490 (delete, guard in the query).
  Python python/src/pierre/_generated/namespaces/repos.py:633-636,
  :661-664, :690-698, and :2323-2333 (the delete body still takes
  expected_ref_sha). TypeScript
  typescript/src/generated/operations/repos.ts:1215-1217,
  :1251-1269 and :1303-1316.
• SDK main fa4c317, error type: Go go/errors.go:244-258, Python
  python/src/pierre/_errors.py:191-194, TypeScript
  typescript/dist/runtime/errors.js:150-153. Each checks the code
  ref_guard_failed first. Otherwise a body with a result object
  gives RefUpdateError.
• The vendored spec gives the upstream notes 409 result.status
conflict (docs/upstream/openapi.yaml:8303 for POST, :7992 for
  DELETE).
• Our code: only the append route and a delete with the
  expected_notes_ref_sha query parameter answer 409
  (internal/api/handlers_write_refs.go:939-955, :1032-1038). The
  412 body from wrefNoteFail (:684-695) has a result object and
  no code or error member.

Validation

• python3 scripts/check-doc-links.py: broken links: 0. This includes
  the README link and citation checks from ci(scripts): check links in every README #638 and ci(scripts): check README code citations #639.
• python3 scripts/test_check_doc_links.py: 29 tests OK.

Refs #647

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

[ThomasK33]

@codex review

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-30T07:07:23.915956Z	258e6bb	Manual request
🔒 Security Review	✅ Completed 2026-10-30T07:07:27.493336Z	258e6bb	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. You're on a roll.

Reviewed commit: 258e6bba00

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: 258e6bba00

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.