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

+6 -3
View File
@@ -118,9 +118,12 @@ type RegistryConfig struct {
// modpack's Kaniko build context is pinned. It belongs to the §16 build
// subsystem's input domain (the build-context store), introduced by the
// user-directed modpack approval lane (see internal/submit package doc). The
// lane derives {UserUploadsContext}/{submissionID}/context.tar.gz; the upload
// transport that places the blob there is a separate, deferred integration
// (INTEGRATION-ONLY). It is kept distinct from [archive] on purpose — a world
// lane derives {UserUploadsContext}/{submissionID}/context.tar.gz; both transports
// that place the blob there now ship (submit.LocalContextStore for a local path,
// submit.S3ContextStore for an s3:// base, selected in cmd/felis by the shape of
// this value). What stays deferred is the far end — Kaniko reading that context
// from inside the build Pod (INTEGRATION-ONLY, see submit/blobstore.go). It is
// kept distinct from [archive] on purpose — a world
// archive (§19 WorldArchiver) and a build context (§16) are different artifacts
// with different lifecycles, so the two must not share a store binding.
UserUploadsContext string `toml:"user_uploads_context"`