Skip to content

ci(visual): shard the matrix across the runner's cores - #1214

Open
HugoXK wants to merge 5 commits into
mainfrom
dev3/1208-parallel-matrix
Open

HugoXK wants to merge 5 commits into
mainfrom
dev3/1208-parallel-matrix

Conversation

@HugoXK

@HugoXK HugoXK commented Nov 21, 2026 •

Copy link
Copy Markdown
Owner

Written-by: HugoXK
Author: Fledge Platform Dev-3

Fixes #1208

Large-PR: 6 files, 846 changed lines — the serial loop (155 lines removed) becomes a coordinator plus a share mode, the partition and its aggregate guard, and the red test that pins the three failure modes; no hunk can go without losing one of the card's four acceptance clauses.

What changed

The visual gate's sweep is a cross-product of independent cells, and it was
one serial loop: its wall time was the sum of every cell (54 s and 66 s on two
attempts of the same commit) inside a 79–88 s job. The cells are now cut into
contiguous shares and run one share per core, inside the same visual check.

  • src/lib/visualMatrix.ts gains the workload model: visualWorkload() builds
    the sweep and the gate from the exported lists (no second copy), cellLabel()
    names a cell with the exact prefix its failure already used, partitionWorkload()
    cuts the workload into contiguous balanced shares, and shardFailures() is the
    aggregate's guard.
  • scripts/visual-matrix.ts is now a coordinator plus a share mode (--share I/N).
    The coordinator spawns one share per core (four by default, VISUAL_SHARDS
    overrides it), each in its own process with its own server, port and temporary
    database, then reads each share's visual-matrix/shares/shard-<i>.json and
    prints the aggregate. A page reused its browser context per locale and mode, so
    a share does not pay context setup per cell.
  • The aggregate refuses to read green when: a share was assigned no cells, a
    share's result never arrived, a share dropped a cell it was assigned, a cell was
    measured twice, or a share exited nonzero without naming a failure. Every share
    failure is printed verbatim by the aggregate, so a failing cell in share 2
    reaches the job output, not only that share's artifact.
  • visual keeps its name and its place: the job is unchanged, ci-ok and
    main-health still needs a check called visual, and no required-check list
    moved. The job graph is not touched; the parallel work sits inside the check.
  • docs/architecture.md and docs/ui.md now describe the sharded run instead of
    the single serial app.

Why this shape

The card's own numbers are the argument: the matrix is 54–66 s of a 79–88 s job,
the browser cache was worth ~3 s against 12 s of run-to-run noise, and the job's
critical path is therefore the serial sweep. Running N independent shares on a
multi-core runner makes the gate about as long as one share.

Alternatives considered

  • Separate CI jobs per shard plus an aggregating job named visual. Rejected:
    it changes the job graph and the jobs that depend on visual by name, which the
    card's third acceptance clause and the Lead's scope both forbid.
  • Round-robin partition. Rejected: it hops between locales and modes on every
    cell, so each share would rebuild its browser context per cell — the partition is
    contiguous on purpose.
  • One server shared by every share. Rejected: SQLite is single-writer and the
    server is one Node process, so the shares would serialize on the resource the
    shard exists to spread; a share that crashed the server would also be measured
    by its neighbours.
  • Keeping the browser cache in this PR. Not used. The card allows it but the
    cache is ci: keep the console visual matrix fast and deterministic #787's mechanism and its allowlist is ci: allow actions/cache on the reviewed list so a workflow can cache its browser layer #1206; sharding stands alone.

Red first

test/visualMatrixShards.test.ts at the pin 044c7515 with only the test
committed: 6 tests, 5 fail, 1 pass. test/visualMatrixShards.test.ts sha256
359ab9d1d77b56f2e9e9b3e0b2c0f3250e8717ac9e6f0a8ef2a5f0be6e8ec905
(tmp/1208/red-base.log). The file reaches the new API through the module object,
so it loads at the pin and names the missing function instead of dying at import.

The three existing runner-shape tests in test/visualMatrix.test.ts that pinned
the serial loop's text now assert the same contracts against visualWorkload():
the narrow case still goes through the overflow walk with locale/width/path, the
landing page is still the one cell captured signed out, and the gate still covers
every path at GATE_WIDTHS × GATE_SCHEMES. No assertion was dropped.

Mechanism exercised without a browser

No local Playwright browser is installed in this workspace (the CDN download is
not usable at this speed), so the browser pass itself is CI-side. The
orchestration was still run for real: VISUAL_SHARDS=2 npx tsx scripts/visual-matrix.ts
spawned both shares, each started its own server and reached chromium.launch,
each wrote visual-matrix/shares/shard-<i>.json with zero cells, and the
aggregate failed with 190 failures — both share stops plus every one of the
188 cells named as never measured — exit 1 (tmp/1208/smoke-2-share.log). That
is the survival half of #787 running in the direction that bites: a share that
measured nothing does not read green.

Acceptance measurement

Product's ruling on #1208 (comment 7067745172) fixes the method: every run
under 66 s, all on the same head, gated on the job total. Three consecutive runs
of the visual job at 405bda6f6eed41d2a9d0a935ff929dd2367b211c, all success:

Run, attempt Job npm ci playwright install visual:matrix upload Job total
44938519599 #1 136950603599 1 s 14 s 22 s 2 s 46 s
44938519599 #2 136951463756 1 s 13 s 25 s 2 s 48 s
44938519599 #3 136952575665 2 s 17 s 30 s 2 s 60 s

All three are under the 66 s cap; the slowest has 6 s of headroom. The matrix
step is 22–30 s against the card's 54–66 s baseline for the same 188 cells; the
rest of the total is the install, the build and the upload, which this card does
not change.

Tuning evidence at earlier heads, deliberately not counted in the three above:
ee61b76e measured a 70 s job whose install was 26 s (job 136948961541), and
02850622, with the default set to two shares per core, measured a 35 s
matrix and a 64 s job (job 136949780225). Eight shares are slower than four on
this runner, so the default is one share per core and VISUAL_SHARDS overrides
it for a measurement.

Not claimed: the local smoke run's wall time. It has no browser and demonstrates
only the aggregate's refusal.

Ran:

  • npm run check at ee61b76e — lint, typecheck, 3299 tests / 3299 pass, build: pass (tmp/1208/check-tip-ee61b76e.log)
  • npx tsx --test test/visualMatrixShards.test.ts — 6/6 at the tip; at 044c7515 the same file is 1/6
  • node scripts/risk-gate.mjs --base 044c7515 — risk-tier: T3; basis: scripts/visual-matrix.ts
  • node scripts/changelog.mjs check and node scripts/version.mjs check — pass
  • VISUAL_SHARDS=2 npx tsx scripts/visual-matrix.ts — aggregate refused with 190 named failures, exit 1 (no browser in this workspace)

Not run: the visual matrix in a real browser, and therefore the timing — no local Playwright browser; CI owns both, and the run ids and totals go into this body.
Not run: docker and any other flag-set job that is not visual.

Changelog-not-needed: this changes the CI gate's scheduling only; no user-visible behaviour or surface changes.

@HugoXK
HugoXK requested a review from HugoXK-bot November 21, 2026 18:54
Fledge Platform Dev-3 added 5 commits November 21, 2026 19:10
The sweep is a cross-product of independent cells, so its wall time was the sum
of every cell. Partition the workload in src/lib/visualMatrix.ts (built from the
same lists), run one share per core in its own process with its own server and
port, and let the aggregate refuse to read green when a share measured nothing,
dropped a cell, or never wrote its result. Per-cell failure messages keep the
cell label, so a failure raised in share 2 reaches the job output.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

ci(visual): run the matrix's independent cells in parallel so the gate is not one serial sweep

1 participant