Install end to end against a real Jellyfin server, in the environment-bound harness

[iderex]

Depends on #21 and on the publication pipeline.

Everything else in this plan tests the catalogue against its own idea of what a
Jellyfin server does. This is the one test that asks the server.

It matters because the failure it catches is the one nobody sees coming: a
manifest that is well-formed, passes every check here, and renders as an empty
repository on a real server because of a field the server reads differently than
expected. A target ABI that does not match, an identifier the server rejects, a
content type that makes it refuse the body, a version format it will not parse.
None of those are visible from this side.

It needs a running server and a network, so under #13 it lives in the
environment-bound harness and the merge gate never depends on it. The name should
say what it needs.

What it does: start a server, add the published address as a repository, assert
the catalogue lists what it should, install one plugin, and assert the server
reports it installed. The install step is the one that verifies the checksum, so
it is also the only place the artifact pairing rule is proven against something
other than a fixture.

Done when

The harness runs against a real server, adds the address, lists the catalogue and
installs a plugin, and fails when the manifest is deliberately given a mismatched
checksum. The merge gate passes with the harness entirely absent.
Machine-decidable.

[iderex]

Not closable yet. #21 owes the environment-bound harness and is open, and there
is no published address for the test to add:

curl -sS -o /dev/null -w "%{http_code}\n" https://flowfin.dev/manifest.json
404

Run 2026-08-08. The publication route is #31.

Two constraints worth writing into the issue now, because both are cheaper to
design for than to retrofit.

The server this test starts has to run without elevation, under #13. A container
is the only shape of this that satisfies that on every machine somebody might run
it on, and anything that would raise an elevation prompt is skipped with the skip
disclosed rather than worked around. A harness that quietly needs elevation is a
harness that passes on one machine and is never run on any other.

The negative half of the Done-when is the half that will be forgotten. The merge
gate has to pass with the harness entirely absent, which means the gate cannot
discover tests by walking the tree, and that is a property of how #18 is built
rather than of this test. Worth stating there as well as here.

[iderex]

Not closed and not attempted. Three of its four preconditions are absent, and the
fourth is a property of the machine this would run on.

What is absent

The environment-bound harness is #21 and there is no suite for it to be a mode of:

git ls-tree -r --name-only origin/main | grep -c '\.go$'
0

Run 2026-08-08 against origin/main at b50ff37.

There is no published address to add as a repository. The address is entry 2 of #1
and the name it would use does not resolve, which #34 carries with its command.
There is also no manifest to serve at it, since the generator is milestone 3.

The part that is about this machine rather than about the tree

This test starts a server. Under decisions/headless-and-unelevated.md the way it
does that may not need administrator rights, may not bind a port below 1024, may not
register a service or a scheduled task, and may not change a machine-wide setting.
Every one of those is reachable by accident when somebody reaches for the shortest
way to get a server listening, and the failure is not a red test: on a machine with
somebody sitting at it, it is a consent prompt that takes the screen away.

So the harness owes an unprivileged high port and a server started as an ordinary
process or container, and that constraint belongs in the test's name and setup
rather than in a comment. No such start was attempted here and nothing in this
comment was produced by running a server.

The half that is worth stating now

The issue's last sentence is the one that will be hardest to keep: the merge gate
passes with the harness entirely absent. That is testable the day both exist, by
running the gate on a tree with the harness's build tag unset, and it is the check
that stops this test from quietly becoming a gate dependency the first time
somebody wants its coverage.

The mismatched-checksum case is the valuable half of the rest. It is the only place
the pairing rule in decisions/artifact-checksum-pairing.md gets proven against a
server rather than against a fixture, and a version of this test that installs a
plugin successfully and never plants a bad checksum proves the happy path only.

What is left

#21, the generator, and the address. In milestone order this is correctly last.

[iderex]

Measured against main at b50ff37, 2026-08-08.

There is no harness for this to live in and no address for it to add. The
published address answers with the site and not with the file:

curl -sS -o /dev/null -w "%{http_code}\n" https://flowfin.dev/manifest.json
404

and there is no module for a harness to be written in:

git ls-tree -r --name-only origin/main | grep -E '\.go$|^go\.(mod|sum)$' ; echo "exit=$?"
exit=1

So this follows #21 and the publication work in milestone 4. Nothing was started
or installed here: no server was run, no container runtime was launched, and no
step that could ask for elevation was attempted.

Two constraints on the shape are worth writing down now, because they conflict
with the plain reading of the Done-when.

The negative half cannot use the published address. The Done-when asks the
harness to fail when the manifest is deliberately given a mismatched checksum,
and decisions/manifest-address.md treats that address as a promise that cannot
be withdrawn. Publishing a knowingly broken manifest there, even briefly, is
served to every operator polling it. So the mismatch case runs against a
manifest the harness serves itself, which means the harness needs a listener the
server under test can reach, and only the positive half can point at the real
address.

That listener is bounded by decisions/headless-and-unelevated.md, which refuses
a port below 1024. The harness therefore serves on a high port and the address it
hands the server carries that port, which is worth stating in the test rather
than discovering when the bind fails. The same file names the tag this run
carries, needs-jellyfin, and the merge gate passing with the harness entirely
absent is the property that keeps somebody else's server outage out of the gate.

[iderex]

Measured against main at c99d26f, 2026-08-10, in a checkout git status --short
prints nothing for.

Correcting what is recorded here rather than restating it. One of the three
things named above as absent has landed, and part of the Done-when turns out to
be held already, so what is left is shorter and different from every list on this
issue.

The harness is here, and the requirement this test belongs to is declared

#21 is closed. The requirement exists, carries the name the issue asks for, and
nothing carries its tag:

go run . harness
needs-jellyfin
  tag       needs_jellyfin
  reaches   a running server: adding the repository address, listing the catalogue, installing a plugin and watching it load
  costs     a Jellyfin server to talk to, brought up for the run and torn down after it, and a failure that can be the server rather than the plugin
  runs      go test -tags needs_jellyfin ./... -count=1 -v
  carried by nothing yet

So the shape of this test is fixed and needs nothing built for it: a file
carrying the needs_jellyfin build constraint, run by the job of that name.

The last sentence of the Done-when, in the three states it is actually in

The sentence is that the merge gate passes with the harness entirely absent.

Held and measured. Nothing carries needs_jellyfin, the gate is green over that
absence, and it prints the absence rather than passing quietly:

go run . gate
gate examined 14 of 14 legs.
...
the harness did not run here, and none of the 3 requirements below was asked for.
no leg above depends on any of them, so this verdict is complete and not partial.

Held and measured. A gate leg cannot pick up a dependency on a requirement
without the suite refusing it. TestTheGateDependsOnNoRequirement in
internal/harness refuses a leg named after a requirement and a leg whose
command carries a requirement's tag. The second is the mistake somebody makes
reaching for this test's coverage from the gate, so that is the one planted, on
the test leg, one argument added:

-    Argv:    []string{"go", "test", "./..."},
+    Argv:    []string{"go", "test", "-tags", "needs_jellyfin", "./..."},

go test ./internal/harness -run TestTheGateDependsOnNoRequirement -count=1
--- FAIL: TestTheGateDependsOnNoRequirement (0.00s)
    harness_test.go:64: gate leg test runs "needs_jellyfin", which is a harness tag
FAIL    flowfin.dev/hub/internal/harness    2.253s

Run 2026-08-10, reverted afterwards, and main is unchanged.

Not measured. The gate over a tree with the harness removed altogether. Four
files carry needs_network, so the harness is not absent today in the literal
sense the sentence uses, and neither run above stands in for that one.

What is left

There is nothing at the address for a server to read:

curl -sS -o /dev/null -w "%{http_code}\n" https://flowfin.dev/
200
curl -sS -o /dev/null -w "%{http_code}\n" https://flowfin.dev/manifest.json
404

Run 2026-08-10. The route that puts a file there is #31, and the run that
produces the file is milestone 3. The mismatched-checksum half is bounded by what
is already recorded here, against a manifest served on a high port rather than at
the published address, and it still needs a manifest to damage and a server to
refuse it. So both halves follow the same two things, and neither is here.

No server was started, no container runtime was launched, and no step that could
ask for elevation was attempted.

[iderex]

The clause this issue records as not measured has now been measured, and it holds.

Measured against main at 3f46a80, 2026-08-12, starting from a checkout
git status --short prints nothing for.

The gate over a tree carrying no harness-tagged file

Four files carry a tag and the other two requirements are carried by nothing:

go run . harness | grep 'carried by'
  carried by internal/address/answered_test.go, internal/freshness/published_test.go, internal/links/elsewhere_test.go, internal/sources/world_test.go
  carried by nothing yet
  carried by nothing yet

Taking all four out of the tracked tree and running the gate over what is left:

go clean -testcache
git rm -q internal/address/answered_test.go internal/freshness/published_test.go \
          internal/links/elsewhere_test.go internal/sources/world_test.go
git commit -q -s -m "scratch: remove every harness-tagged file"
go run . gate
gate examined 14 of 14 legs.
  build                           passed
  test                            passed
  format                          passed
  editorconfig                    passed
  tests-reach-nothing             passed
  no-hardcoded-names              passed
  site-fetches-nothing-outside    passed
  site-links-resolve              passed
  coverage                        passed
  site-declares-its-language      passed
  install-address-is-answered     passed
  focus-stands-off-every-surface  passed
  page-matches-the-token-file     passed
  pr-hygiene                      passed

So the merge gate passes with the harness entirely absent, in the literal sense
the Done-when uses rather than only with the tags unset. That commit was made in
a throwaway checkout and pushed nowhere, and main is unchanged at 3f46a80.

The shorter route to this measurement answers a different question

Deleting the four files from the working copy and leaving them in the tracked
set is the obvious way to try it, and the red it produces says nothing about the
harness:

rm internal/address/answered_test.go internal/freshness/published_test.go \
   internal/links/elsewhere_test.go internal/sources/world_test.go
go test ./internal/address ./internal/format -count=1
--- FAIL: TestNoTrackedFilePrintsAnUnansweredInstallAddress (0.08s)
FAIL    flowfin.dev/hub/internal/address 0.635s
--- FAIL: TestTrackedTreeIsFormatted (0.13s)
FAIL    flowfin.dev/hub/internal/format  0.660s

Both read the tracked file list and open every path in it, so a path git still
lists and the disk no longer holds is a missing file rather than an absent
harness. The detail line under each failure is the operating system's own open
error, and it is left out because it arrives in the machine's language rather
than in this repository's.

One more thing about repeating it. The test cache decides which leg the wrong
version reddens at: two runs over the same working copy stopped at different
legs, once at test and once at editorconfig, until the cache was cleared. So
go clean -testcache belongs in front of the run rather than after a confusing
result.

What is not measured here

The positive half of the Done-when. No server was started, no container runtime
was launched, and no step that could ask for elevation was attempted. What that
half waits on is recorded above and has not moved.

[iderex]

I measured this against main at 65766c9, 2026-08-13, in a checkout
git status --short prints nothing for.

I started no server, launched no container runtime, and attempted no step that
could ask for elevation.

What this waits on has not moved and is recorded above. What is not recorded is
that the half of it which is not a test file is also missing, and that nothing in
the tree would say so.

Asking for the requirement today refuses rather than passing

go run . harness needs-jellyfin
no test file carries needs_jellyfin, so there is nothing to run and a green here would say nothing
exit status 1

Worth having on the issue because it fixes which way the risk runs. The
requirement is not quietly green while its test is absent. It goes from that
refusal to a real run the moment one file carries the tag, and the run it goes to
is the one below.

The job that would run it supplies neither thing the requirement costs

go run . harness | sed -n '/^needs-jellyfin/,$p'
needs-jellyfin
  tag       needs_jellyfin
  reaches   a running server: adding the repository address, listing the catalogue, installing a plugin and watching it load
  costs     a Jellyfin server to talk to, brought up for the run and torn down after it, and a failure that can be the server rather than the plugin
  runs      go test -tags needs_jellyfin ./... -count=1 -v
  carried by nothing yet

sed -n '/^  needs-jellyfin:/,$p' .github/workflows/harness.yml
  needs-jellyfin:
    name: needs-jellyfin
    if: inputs.requirement == 'needs-jellyfin'
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          persist-credentials: false
      - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
        with:
          go-version-file: go.mod
      - run: go run . harness needs-jellyfin

Checkout, a toolchain, and the entry point. Nothing brings a server up and
nothing hands the run an address, so a test file landing against that job runs
against neither of the two things its requirement is named for. Which of the two
places the server comes up in, the job or the test, is a choice this issue still
has; that it comes up nowhere today is not.

The needs-network job in the same file already shows the shape the address
half takes. It receives one as a repository variable and the file states beside
it that unset is a refusal in the check rather than a skip, so a run cannot pass
by not having looked.

Nothing refuses a job that names a requirement and supplies none of it

grep -rn "services" --include=*.go --include=*.yml . ; echo "exit=$?"
exit=1

The suite reads that workflow as text, and what it reads is the entry-point step
and the absence of any other toolchain step:

sed -n '103,127p' internal/harness/harness_test.go
func TestEveryHarnessJobRunsTheEntryPointForItsOwnRequirement(t *testing.T) {
...
	for _, r := range Requirements() {
		want := "run: go run . harness " + r.Name
		if !strings.Contains(text, want) {
			t.Errorf("%s does not carry a step running %q", WorkflowPath, want)
		}
	}

So a job carrying the correct one-line step and none of what its runner needs
passes every check here. That is the job as it stands, and it is the part of this
issue that no amount of writing the test will reach.