docs(agents): the index digest, not the platform manifest, matches imageID #20

Merged

jlxq0 merged 2 commits from docs/index-digest-not-platform-manifest into main

2026-08-27 03:31:08 +00:00

jlxq0 commented

2026-08-27 03:29:36 +00:00

Owner

I reported the wrong digest for v0.2.15 upward before catching this.

docker manifest inspect -v on an image index returns an array of per-platform manifests. [0].Descriptor.digest is the linux/amd64 manifest; a pod's imageID carries the index digest. Every jmap-mcp tag is an application/vnd.oci.image.index.v1+json.

Calibration

Run against v0.2.14, whose deployed imageID was already known:

pod imageID                          sha256:316e64a8…
registry HEAD Docker-Content-Digest  sha256:316e64a8…   match
manifest inspect -v [0].Descriptor   sha256:50831874…   no match

The -v array holds [linux/amd64] and an [unknown/unknown] attestation entry. Neither is the index.

The check here is a registry HEAD on /v2/jlxq0/jmap-mcp/manifests/<tag> with the index media types in Accept, reading Docker-Content-Digest, with a registry token from /v2/token rather than the Forgejo API token.

Why the precondition was never visible

Measured across the five deployed MCP servers:

service	shape	`-v` vs pod `imageID`
`jmap-mcp`	index, array(2)	neither entry matches
`caldav-mcp`	single	match
`hevy-mcp`	single	match
`matrix-mcp`	single	match
`typst-mcp`	single	match

Four of five are single-manifest, where the fleet form is correct. jmap-mcp is the only index.

The direction it fails in

A platform manifest compared against a correctly deployed imageID reports a mismatch on a healthy image, which is the sentence that triggers a rollback. A correct instruction with an unstated precondition is worse than an incomplete one: the reader gets a definite wrong answer rather than an error.

Caught by dry-running the check against a tag whose answer was already known, before relying on it for the release just cut. Pointed at v0.2.15 alone, both numbers look equally like a digest.

Docs only.

I reported the wrong digest for `v0.2.15` upward before catching this. `docker manifest inspect -v` on an **image index** returns an array of per-platform manifests. `[0].Descriptor.digest` is the `linux/amd64` manifest; a pod's `imageID` carries the **index** digest. Every `jmap-mcp` tag is an `application/vnd.oci.image.index.v1+json`. ## Calibration Run against `v0.2.14`, whose deployed `imageID` was already known: ``` pod imageID sha256:316e64a8… registry HEAD Docker-Content-Digest sha256:316e64a8… match manifest inspect -v [0].Descriptor sha256:50831874… no match ``` The `-v` array holds `[linux/amd64]` and an `[unknown/unknown]` attestation entry. Neither is the index. The check here is a registry `HEAD` on `/v2/jlxq0/jmap-mcp/manifests/<tag>` with the index media types in `Accept`, reading `Docker-Content-Digest`, with a **registry** token from `/v2/token` rather than the Forgejo API token. ## Why the precondition was never visible Measured across the five deployed MCP servers: | service | shape | `-v` vs pod `imageID` | |---|---|---| | `jmap-mcp` | index, array(2) | **neither entry matches** | | `caldav-mcp` | single | match | | `hevy-mcp` | single | match | | `matrix-mcp` | single | match | | `typst-mcp` | single | match | Four of five are single-manifest, where the fleet form is correct. `jmap-mcp` is the only index. ## The direction it fails in A platform manifest compared against a correctly deployed `imageID` reports a mismatch on a healthy image, which is the sentence that triggers a rollback. A correct instruction with an unstated precondition is worse than an incomplete one: the reader gets a definite wrong answer rather than an error. Caught by dry-running the check against a tag whose answer was already known, before relying on it for the release just cut. Pointed at `v0.2.15` alone, both numbers look equally like a digest. Docs only.

jlxq0 added 2 commits

2026-08-27 03:29:36 +00:00

docs(agents): the index digest, not the platform manifest, matches imageID 8c620946f2

docker manifest inspect -v on an OCI image index returns an array of
per-platform manifests. Reading [0].Descriptor.digest gives the linux/amd64
manifest, which never equals a pod's imageID.

Calibrated against v0.2.14, whose deployed imageID is known: the registry HEAD
Docker-Content-Digest matches it and manifest inspect -v [0] does not. Every
jmap-mcp tag is an OCI image index, so the fleet rule's -v form is wrong here.

I had already reported the wrong digest for v0.2.15 upward before catching it.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

docs(agents): note jmap-mcp is the only multi-arch image of the five

CI / tag-ancestry (pull_request) Successful in 3s

Details

CI / cargo (pull_request) Successful in 57s

Details

CI / docker (pull_request) Successful in 14s

Details

4fa0a1374b

Measured across the deployed MCP servers: caldav, hevy, matrix and typst all
publish a single manifest, where the fleet rule's -v form is correct. jmap-mcp
is the only index, which is why the precondition had never been visible.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

jlxq0 merged commit f97562bbac into main

2026-08-27 03:31:08 +00:00

jlxq0 deleted branch docs/index-digest-not-platform-manifest

2026-08-27 03:31:08 +00:00

jlxq0 referenced this pull request from a commit

2026-08-27 03:31:09 +00:00

Merge pull request 'docs(agents): the index digest, not the platform manifest, matches imageID' (#20) from docs/index-digest-not-platform-manifest into main