[ThomasK33]

Why

Three rows in docs/explanation/wire-compatibility.md keep a stale
expected_target_sha on commit-pack, diff-commit and
restore-commit at 412 precondition_failed (#533). Their reason
named only the Go SDK 1.17.1. The new SDKs on SDK main fa4c317
handle this 412 in a different way, and the rows did not say so. This
is part 1 of #647. Part 2 changes the status code and waits for gate G1
of #352.

What changed

The three rows now state:

1. What SDK 1.17.1 (@pierre/storage, pierre-storage and
   code-storage-go) does with our 412. It 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. They pick RefGuardError
   only for the code ref_guard_failed, so our 412 becomes a
   RefUpdateError. A caller that retries with current_sha works
   against upstream and fails against open.storage.
3. That the deviations end 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):

• SDK main fa4c317, Go: go/errors.go:110 (RefGuardError), :163
  (refGuardFailed), :244-258 (the code check runs first, then a body
  with result gives RefUpdateError).
• SDK main fa4c317, Python: python/src/pierre/_errors.py:119-124
  (RefGuardError), :184-194 (_REF_GUARD_FAILED and the same order
  in api_error).
• SDK main fa4c317, TypeScript: typescript/dist/runtime/errors.js:83
  (RefGuardError), :145-153 (REF_GUARD_FAILED and the same order
  in apiError).
• Tag packages/code-storage-go/v1.17.1 (35610abb, all three packages
  at 1.17.1): Go commit_pack.go:77-96 and repo.go:1483-1503,
  TypeScript src/commit-pack.ts:63-77 and src/index.ts:2026-2043,
  Python pierre_storage/commit.py:142-176 and repo.py:2232-2246.
  Each one takes the error status from result.status and falls back
  to the HTTP status. None of them knows ref_guard_failed.
• The vendored spec gives the upstream 409 body result.status
conflict (docs/upstream/openapi.yaml:5455).
• Our 412 body has a result object and no top-level code
  (wcFail, internal/api/handlers_write_commit.go:127, used at :555).

Upstream audit evidence: 2026-10-30-0558UTC.

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-30T06:11:48.538460Z	0a74fdf	Manual request
🔒 Security Review	✅ Completed 2026-10-30T06:10:56.588695Z	0a74fdf	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 Security Review

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

Reviewed commit: 0a74fdfe35

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.

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Chef's kiss.

Reviewed commit: 0a74fdfe35

ℹ️ 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".