Skip to content

Write the container readback rule next to the data it applies to - #434

Merged
TennyZhuang merged 1 commit into
mainfrom
docs/container-readback-rule
Aug 9, 2026
Merged

Write the container readback rule next to the data it applies to#434
TennyZhuang merged 1 commit into
mainfrom
docs/container-readback-rule

Conversation

@TennyZhuang

Copy link
Copy Markdown
Contributor

Comment only. No behaviour change. 16 added lines in one file.

/api/admin/container/build already separates could not read from read an unstamped
image
. My shorthand for it undid that separation one layer up — I wrote "before the
rollout → stamped:false (old image)", which holds only when the container answered
healthily.

response meaning
ok:true status:200 stamped:false the old image is serving
ok:false status:5xx stamped:false answered but unhealthy — not measured
unreachable container throws; there is no stamped field at all

Only the first line is a statement about which image is up. Everything else is "not
measured".

Caught by @sentinel on the shorthand rather than on the code, which is exactly the
reason for this PR: the next person reads the summary, not the implementation, so the
qualifier has to live where the fields are.

stamped:true gets no matching qualifier, deliberately — the running image has no code
that emits build, so a true cannot come from anywhere but a rebuilt image. The
asymmetry is correct and should not be evened out for tidiness.

Verification

  • worker tsc --noEmit: 0 errors
  • full worker suite: 403 passed, 35 files
  • diff is 16 added comment lines, no executable change

Comment only; no behaviour change.

The endpoint already separates "could not read" from "read an unstamped image",
and my own shorthand for it undid that separation one layer up: I wrote "before
the rollout -> stamped:false (old image)", which is true only when the container
answered healthily. Three cases produce a falsy stamp and only one of them is a
statement about which image is serving:

  ok:true   status:200  stamped:false  -> the old image is serving
  ok:false  status:5xx  stamped:false  -> answered but unhealthy; NOT MEASURED
  (unreachable container throws, so no stamped field exists at all)

Caught by Sentinel on the shorthand rather than on the code, which is the point:
the next person reads the summary, not the implementation, so the qualifier has
to live where the fields are.

`stamped:true` gets no matching qualifier, deliberately. The running image has no
code emitting `build`, so a true cannot come from anywhere but a rebuilt image.
The asymmetry is correct and should not be evened out for tidiness.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@TennyZhuang
TennyZhuang merged commit c5afd6e into main Aug 9, 2026
6 checks passed
@TennyZhuang
TennyZhuang deleted the docs/container-readback-rule branch August 9, 2026 10:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant