Skip to content

Commit 32457de

Browse files
docs(eng): CAP-01-ATTEST-READER-01 repair - duplicate same-name attestations fail closed (V1 liveness limit)
#806's ONE allowed semantic repair, by operator decision (Option A), for P1 4201892749: a re-run that re-executes the emitter may leave more than one ci-attest-v1 artifact on the same run (GitHub has been observed listing one per attempt, cli/cli#12437). Documentation clarification only; the two-operation plan is unchanged: - Section 4 re-run note: duplicates are deliberately "unavailable" (UNKNOWN downstream). LOCATE never chooses among them. Liveness only: no false success, no older or newer pick by heuristic, no readiness. Recovery is a NEW workflow run (push, a close and reopen, or any legitimate higher run_number), which can become the current-run frontier. A failed-jobs re-run that skips the emitter is unaffected; a re-run-all that leaves duplicates may stay UNKNOWN, as accepted for V1. - Producer unchanged: overwrite stays false, with one artifact per executed attempt. No unproven cross-attempt overwrite, no created_at or artifact-id ordering, and no download-all selection by runAttempt. - Fixture A3: two or more valid-looking artifacts for one run id give "unavailable", with no download and no selection. A1, A2 and A4 kept. - Section 16 records the spent repair; one evidence row. No new request, loop, ordering or attempt-selection rule. Docs only (T0). #802 untouched. Co-Authored-By: Claude Opus 5.5 (1M context) <[email protected]>
1 parent 2aa208c commit 32457de

1 file changed

Lines changed: 22 additions & 1 deletion

File tree

‎docs/decisions/cap-01-github-capability-boundary.md‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -245,6 +245,20 @@ order, and nothing else: no loop, no second page, and no caller-selected route,
245245

246246
Any failure, including a `410 Gone`, returns the *unavailable* result.
247247

248+
- **Re-runs — a deliberate V1 liveness limitation.** A re-run that re-executes the attestation emitter may leave more
249+
than one `ci-attest-v1` artifact on the same workflow run: GitHub has been observed listing one such artifact per
250+
attempt (Appendix). V1 fails closed. LOCATE never chooses among duplicates; the run's result is *unavailable*, and
251+
the CI binding record treats it as UNKNOWN. This affects liveness only. It cannot grant CI success, choose an older
252+
or a newer attestation by any heuristic, or make a pull request ready. Recovery is a **new** workflow run — a push,
253+
a close and reopen that starts a fresh `pull_request` run, or any other legitimate new run with a higher
254+
`run_number` — which can become the CI binding record's current-run frontier; there is no selection within the
255+
ambiguous run. A re-run of failed jobs that does not re-execute the upstream emitter keeps its one attestation and is
256+
unaffected. A "re-run all jobs" that leaves duplicates may stay UNKNOWN, and V1 accepts that.
257+
- **Producer unchanged.** The CI binding record's emitter keeps `overwrite: false` and produces one artifact per
258+
executed attempt; the reader requires one unambiguous artifact for the run. V1 does not assume that `overwrite: true`
259+
deletes an earlier attempt's artifact; that is unproven. An artifact record exposes no documented attempt selector,
260+
and neither `created_at` nor the artifact id is attempt identity. Downloading every duplicate to choose by the
261+
payload's `runAttempt` would add a loop and move attempt selection into the transport.
248262
- **What crosses the boundary.** Only the normalized attestation record with its frozen artifact metadata, or the
249263
*unavailable* result. The raw list response, the artifact id, the redirect URL and the zip bytes never leave the
250264
transport package. The CI binding record classifies an *unavailable* result (CI-ATTEST-01: INVALID).
@@ -257,7 +271,7 @@ Required attestation-reader fixtures, for the transport's implementation tests:
257271
|---|---|---|
258272
| A1 | exactly one valid `ci-attest-v1` artifact | DOWNLOAD runs |
259273
| A2 | no `ci-attest-v1` artifact | *unavailable*; no download |
260-
| A3 | two `ci-attest-v1` artifacts | *unavailable*; no download |
274+
| A3 | two or more valid-looking `ci-attest-v1` artifacts for one run id — for example after a re-run that re-executed the emitter | *unavailable*; no download and no selection |
261275
| A4 | the one artifact is expired | *unavailable*; no download |
262276
| A5 | a `total_count` different from the number of artifacts returned | *unavailable*; no download |
263277
| A6 | more than 100 matching artifacts, so paging would be required | *unavailable*; no second page and no download |
@@ -575,6 +589,12 @@ reader-state family → **stop**.
575589
**Review budget.** One exact-head review round. One semantic repair is allowed. A second P0–P2 in the same family →
576590
**stop**, with no patch loop.
577591

592+
**Spent.** Codex's review of `2aa208c678` raised P1 `4201892749`: a re-run can leave several same-name artifacts on one
593+
run, which LOCATE's exactly-one rule makes *unavailable*. By operator decision (Option A), this is accepted as a
594+
documented V1 liveness limitation (§4). Duplicates are deliberately *unavailable*, recovery is a new run, and no
595+
attempt-selection rule, extra request or ordering was added. A further P0–P2 in the attestation-reader or
596+
re-run-artifact family → **stop**.
597+
578598
---
579599

580600
## Appendix — evidence (2026-10-06, read only)
@@ -595,3 +615,4 @@ reader-state family → **stop**.
595615
| REST `actions/list-workflow-run-artifacts` (OpenAPI), for §16 | query `name`, `per_page` and `page`; the response holds `total_count` and `artifacts`; an artifact's `digest` is a nullable string |
596616
| REST `actions/download-artifact` (OpenAPI), for §16 | `GET …/actions/artifacts/{artifact_id}/{archive_format}`, where the format must be `zip`; it answers `302` with a `Location` URL that expires after one minute, or `410` |
597617
| PR #802, ready-triggered review `5436100752`, for §16 | P1 `4201792798`: reading an attestation takes two GitHub operations, and §4 allowed one |
618+
| GitHub CLI issue `cli/cli#12437` (open, 2026-01-07), for §4's re-run note | after a re-run, one run's name-filtered artifact list returned two same-name artifacts, one per attempt (`pmd/pmd` run `20775770442`; those artifacts have since expired) |

0 commit comments

Comments
 (0)