docs: index the deferred integration seams and correct two stale markers

INTEGRATION-ONLY and KNOWN-LIMITATION are grep-able, but the grep answers the
wrong question. Thirty-four Go sites share the two markers and they carry four
different meanings: "declared, nothing implements it" reads exactly like
"implemented, only its I/O is unreachable from here", and neither reads
differently from a limitation that was accepted on purpose and is not coming
back. docs/deferred-seams.md sorts them, following the bucketed shape
internal/updater/doc.go already uses for its own package rather than starting a
second convention.

Sorting them turned up two markers that had outlived the condition they describe.

config.go called the modpack upload transport a deferred integration after both
backends had shipped -- LocalContextStore and S3ContextStore, selected in
cmd/felis by the shape of user_uploads_context, with the uploads PVC mounted and
the felis-uploads-s3 Secret rendered. What is still deferred is the far end:
Kaniko reading that context from inside the build Pod.

updater/doc.go listed the `felis update` CLI and the off-cluster Velocity jar read
under REMAINING INTEGRATION. Both exist -- cmd/felis/update.go, and
gatherer_host.go, which answers Velocity from the installed jar's manifest and
felis-api from the running binary's build stamp. The two nil seams that bullet
also names are real, but they belong to the in-cluster gatherer only, so the
bullet now says which caller has what and which is still empty.

The index also records the collision that makes a naive grep misleading:
docs/troubleshooting.md uses [INTEGRATION-ONLY] for something else, defined in its
own opening at :19 -- the symptom is produced by the kubelet, kaniko or a live
handshake, so it cannot be reproduced from the repository. Those twelve marks say
where a failure comes from, not that something is unbuilt, and are excluded.

Both code changes are comments. Every file:line the index cites was checked
against the line it points at.
This commit is contained in:
flyemoji committed 2026-07-28 17:27:01 +09:00
1 parent 23792d6251
commit afdbfac7a8
3 files changed
+130 -10

No files matched your search

+11 -7
View File
@@ -41,11 +41,15 @@
// read and a CLI read agree instead of the image masquerading as a prerelease. The
// CLI seam (execRunner) is wired for real; only its exec I/O is un-verified here.
//
// - REMAINING INTEGRATION (genuinely I/O-bound — needs a node/cluster/mailbox): the
// two current-version PRODUCING seams the gatherer still lacks — the k8s read of the
// control-plane Deployment's image (felis-api) and the off-cluster Velocity jar
// inspection, both left nil so those components surface a gather error rather than a
// wrong version — plus the concrete Notifier (SMTP + in-game) and Applier
// (control-plane image bump, cloudflared swap), the `felis update` CLI + CronJob
// entry point, and the runtime append of the live Pinned Minecraft fleet.
// - REMAINING INTEGRATION (genuinely I/O-bound — needs a cluster/mailbox): the two
// current-version PRODUCING seams NewSysGatherer still leaves nil — the k8s read of
// the control-plane Deployment's image (felis-api) and the Velocity jar inspection —
// so an IN-CLUSTER caller surfaces a gather error rather than a wrong version. The
// ON-HOST caller has both: NewHostGatherer (gatherer_host.go) answers felis-api from
// the running binary's build stamp and Velocity from the installed jar's manifest,
// and that is what the built `felis update` CLI runs on. Still absent: the concrete
// Notifier (SMTP + in-game) and Applier (control-plane image bump, cloudflared swap)
// — the CLI passes nil for both on purpose, so it reports and never applies — the
// in-cluster CronJob entry point, and the runtime append of the live Pinned
// Minecraft fleet.
package updater