Remap Cut 6 under C: binaries in the tree, a release workflow, no registry

The deploy tarball is a git archive of two package directories, so only
committed files reach Yggdrasil and cultmesh-ts does not ride at all
today. Under C the binding resolves binaries from an environment variable
or the package's own native directory, a workflow builds the Linux artifact
in a debian:13 container and attaches it to a release with a manifest and
digests, and the operator smoke ships its own archive. Registry publication
is parked with its seam named. One question remains: whether the four
binaries are committed or fetched at deploy time.

The corrected npm premise is recorded in the operator's words: reachable,
publication deferred by choice.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Meta Vens 2026-09-16 15:28:31 +02:00
commit 4a2fdafa61

View file

@ -6,14 +6,20 @@ Status: Imagination output for the target in
`docs/typescript-quic-realtime-target.md` (operator-accepted 2026-09-16). No
code in this document has been written. Nothing here is committed by
Imagination; the root agent commits. Q5, Q6 and Q7 were ruled the same day
(section 13, Rulings); Q5 was then re-ruled from A to C because npmjs is
unreachable from this network. **Cut 6 and the registry-dependent lines of
Cuts 4 and 7 are being remapped under C**; until that lands, their text
describes ruling A. No operator question is open. Cut 1 has not started.
(section 13, Rulings); Q5 was then re-ruled from A to C: no registry in this
campaign, registry publication parked for a later pass by choice. Cut 6,
section 5.4, the binary-resolution and dependency lines of Cut 4, and Cut 7's
ledger are remapped under C (landed 2026-09-16, same day). One operator
question is open: Q8 in section 11, whether the built binaries are committed
to the tree or fetched from a GitHub Release by the deploy path. Cut 1 has
not started.
Anchor: repo `F:\Projects\CultLib`, branch `main`, HEAD
`f2cd2eb4641269c653977bdba9b4bce2a26d870c`. Every `file:line` below is read
against that commit. If HEAD moves, re-anchor before cutting.
`8d8ad568aa280bac34bf123503a9e38c175eb558`. The three commits since the
original anchor `f2cd2eb4` (`bf9f6f7`, `3c29fc9`, `8d8ad56`) touch only this
document `(probe: git log --stat)`, so every `file:line` below, read against
`f2cd2eb4`, is still exact at `8d8ad568`. If HEAD moves, re-anchor before
cutting.
How to read this document: section 1 prices the largest liability first, as
the target requires, because if that price had turned out to dominate the
@ -35,13 +41,14 @@ Two corrections to the target, recorded here rather than silently absorbed:
(`CultMeshRealtimeDelivery` at :8-13, `CultMeshRealtimeFrame` at :19-44,
`ICultMeshRealtimeTransport` at :46-52,
`ICultMeshRealtimeTransportConnector` at :55-63) `(source read)`.
- The target says the binding is "shipped through a registry". Today only
`@gamecult/cultcache-ts` has a registry publish job
- This map's first issue attributed the phrase "shipped through a registry"
to the target. The target contains no such phrase and no word "registry"
`(probe: rg)`; the reading was the map's, and it is withdrawn. What is
true: today only `@gamecult/cultcache-ts` has a registry publish job
(`.github/workflows/publish-packages.yml:20-24`, `:40-76`); `cultnet-ts`,
`cultmesh-ts` and `cultmesh-browser` have none, and every external consumer
reaches them by `file:` path (section 3). Registry delivery of the binding
therefore also means registry delivery of `cultnet-ts` and `cultmesh-ts`,
which is a naming decision the operator has not yet made. See Q5.
reaches them by `file:` path (section 3). Q5 was ruled C on that Body: no
registry in this campaign, publication parked.
## 1. The largest liability, priced first
@ -381,18 +388,40 @@ Sizing consequences:
- Owner: `scripts/build-quic-native.ps1` (Windows x64) and the new
`scripts/build-quic-native.sh` (Linux x64) own producing the bridge
artifact; `.github/workflows/publish-packages.yml` owns turning artifacts
into registry packages.
artifact; the new `.github/workflows/quic-native.yml` owns producing the
release-grade artifact for both platforms (Q6 A) and attaching it to a
GitHub Release; the committed tree `packages/cultmesh-ts/native/` owns
delivery to consumers (Q5 C): whatever carries the package directory (a
`git archive`, an `npm pack` tarball, a pnpm `file:` copy) carries the
binaries with it, and `packages/cultmesh-ts/native/MANIFEST.txt` plus
`SHA256SUMS` own provenance (MsQuic version, build host, digest per file).
- Inputs: pinned MsQuic 2.5.9 (Schannel NuGet on Windows; `libmsquic` deb on
Linux) with SHA-256 checks; the bridge source.
Linux) with SHA-256 checks; the bridge source; the pinned `debian:13` image
digest for the Linux builder.
- Outputs: `gamecult_mesh_quic_native.dll` + `msquic.dll` (win32-x64),
`libgamecult_mesh_quic_native.so` + `libmsquic.so.2` (linux-x64), each with
the MsQuic license.
- Derived state: `artifacts/` (git-ignored, `.gitignore:66`).
- Forbidden writers: no `postinstall` compile step in any published package;
a consumer host never needs CMake or a compiler.
- Deletion line: none; the Windows script is kept and the Unity package script
keeps calling it.
`libgamecult_mesh_quic_native.so` + `libmsquic.so.2` (linux-x64), the MsQuic
license, and the two provenance files.
- Derived state: `artifacts/` (git-ignored, `.gitignore:66`) is the
development-loop build output and never delivery; the Unity plugin copies at
`unity/org.gamecult.cultlib/Runtime/Plugins/x86_64/` remain the Unity
package's own body (section 8, operator-only rebuild), not a source for
Node.
- Forbidden writers: no `postinstall` compile or download step in any
package; a consumer host never needs CMake, a compiler, or registry access
for the binding; no workflow commits binaries to `main` (the operator
commits from a Release asset whose digest the manifest records, Q8);
`realtime-quic-native.ts` never searches `node_modules` for a platform
package.
- Deletion line: the platform packages
`packages/cultmesh-quic-native/{win32-x64,linux-x64}` and
`optionalDependencies` from the ruling-A map are never created; the Windows
script is kept and the Unity package script keeps calling it.
- Parked seam (registry publication, later pass): the same `quic-native.yml`
artifacts are the payload a publish job would wrap; the reattachment point
is a `cultmesh-ts` job shaped like `publish-packages.yml:39-78` that depends
on the two build jobs, plus `optionalDependencies` in
`packages/cultmesh-ts/package.json` and a `node_modules` branch in the
resolver. None of that exists under C.
## 6. Cut 1 (subtraction): one TypeScript route verifier
@ -696,10 +725,16 @@ Deletes: none.
Adds:
- `packages/cultmesh-ts/src/realtime-quic-native.ts` (about 260 lines): the
koffi binding. Resolves the platform package (`@gamecult/cultmesh-quic-native-win32-x64`
or `-linux-x64`, Q5) or, when `CULTMESH_QUIC_NATIVE_DIR` is set, a directory
(this is how the repo's own tests point at `artifacts/quic-native/<platform>`
without a registry). Loads `msquic` first, then the bridge, by absolute path
koffi binding. Resolves the binary directory as `CULTMESH_QUIC_NATIVE_DIR`
when set (the development loop and CI point it at
`artifacts/quic-native/<platform>` straight from a build), otherwise
`path.join(__dirname, "..", "native", `${process.platform}-${process.arch}`)`,
the committed tree cut 6 lands (Q5 C; `__dirname` is `dist/` at runtime, so
the path holds in the repo, in an `npm pack` tarball, and in a pnpm `file:`
copy alike). No `node_modules` lookup, no platform package, no registry.
When neither directory holds `msquic` and the bridge, throw one error naming
both paths tried and the env var; until cut 6 lands, that is the error every
caller outside the test suite gets. Loads `msquic` first, then the bridge, by absolute path
(the probe showed the dependent library must be resolvable before the
bridge loads). Declares the twelve v2 prototypes. Exposes
`CultMeshQuicNativeRuntime` with a single event pump: a loop that awaits
@ -736,11 +771,14 @@ Adds:
beside the RUDP ones at `:6008-6186`: `parseQuicRealtimeEndpoint`,
`createQuicRealtimeConnector(options)`, `createQuicRealtimeSessionManager(options)`,
and in cut 5 `createQuicRealtimeProvider(options)`.
- `packages/cultmesh-ts/package.json:44-48` gains `"koffi": "3.3.0"` (exact)
and `optionalDependencies` for the two platform packages (names per Q5).
`koffi` is required lazily inside `realtime-quic-native.ts` so consumers
that never touch QUIC (AetheriaEve Electron, Odin, Stonks, weksa) load
nothing native.
- `packages/cultmesh-ts/package.json:44-48` gains `"koffi": "3.3.0"` (exact).
No `optionalDependencies`: under Q5 C the binaries are files of this
package, not packages of their own. `koffi` is required lazily inside
`realtime-quic-native.ts` so consumers that never touch QUIC (AetheriaEve
Electron, Odin, Stonks, weksa) load nothing native. `koffi` itself is a
registry dependency like `@msgpack/msgpack` (`:45`); every consumer host
already installs from the registry (`deploy-streampixels-preview.sh:102`),
so this adds no new kind of fetch.
- `packages/cultmesh-ts/test/realtime-quic-native.test.ts` (about 150 lines):
the cut-3 FFI smoke, now against the runtime class.
- `packages/cultmesh-ts/test/realtime-quic-consumer.test.ts` (about 250
@ -883,56 +921,354 @@ Verification:
nothing on the provider side.
- Operator-only: none.
## 11. Cut 6 (packaging and release)
## 11. Cut 6 (packaging and release, remapped under Q5 C)
Purpose: a consumer host with no toolchain installs the binding.
Purpose: a consumer host with no toolchain and no registry access for the
binding gets it by receiving the `cultmesh-ts` package directory, which is how
every consumer already receives the package (P16, P17). Registry publication
is parked, not ruled out; the seam it reattaches to is named at the end of
this section.
Adds:
### 11.1 Body facts this cut stands on
- `packages/cultmesh-quic-native/win32-x64/package.json` and
`packages/cultmesh-quic-native/linux-x64/package.json` (names per Q5), each
with `os`/`cpu` fields, `files` listing the two binaries and
`MSQUIC-LICENSE.txt`, no scripts, and a `README.md` naming the MsQuic
version and the build host. Their contents are copied from
`artifacts/quic-native/<platform>` by the publish job, never committed.
- `.github/workflows/publish-packages.yml`: tag prefixes `cultnet-ts-v*`,
`cultmesh-ts-v*`, `cultmesh-quic-native-v*` (`:20-24`); a `cultnet-ts` job
and a `cultmesh-ts` job shaped like the `cultcache-ts` job (`:40-76`); a
native job with two runners: `windows-latest` running
`scripts/build-quic-native.ps1`, and `ubuntu-latest` with
`container: debian:13` running `scripts/build-quic-native.sh` (Q6), each
publishing its platform package, then the `cultmesh-ts` job depends on both.
- `scripts/test-typescript-package-closure.mjs:9` adds the platform packages
to the pack list on the matching host and `:63-72` adds
`assert.equal(typeof mesh.CultMesh.createQuicRealtimeConnector, "function")`
plus a runtime smoke that opens and closes a `CultMeshQuicNativeRuntime`
from the installed tarballs (proves the optional dependency resolves and the
binaries load from `node_modules`, not from a repo path).
- `.github/workflows/cultnet-interop.yml` gains a step after the C# RUDP
step that builds the Windows bridge (`build-quic-native.ps1`) and runs the
`QUIC realtime` lanes with `CULTMESH_QUIC_NATIVE_DIR` set. Linux CI
coverage of the lanes needs a Linux runner with dotnet and the deb; add a
second job `interop-quic-linux` on `ubuntu-latest` + `container: debian:13`
running only the QUIC lanes.
- The deploy tarball is a `git archive`. The Idunn actuator on Starfire runs
`git -C CultLib archive --format=tar --output=<tar> origin/main packages/cultnet-ts packages/cultcache-ts`
(`F:\Projects\Odin\scripts\deploy-yggdrasil-streampixels.ps1:59`), uploads
it by `sftp` (`:127`), and `deploy-streampixels-preview.sh:95-99` extracts it
into `/srv/streampixels/CultLib` after deleting only those two package
directories (`:97`) `(source read)`. Two consequences: only committed files
ride (a `git archive` cannot carry untracked or ignored files), and
`packages/cultmesh-ts` is not in the archive today at all, although
StreamPixels declares it (`apps/service/package.json:26`). Adding it to the
archive list and to `:97` is deploy work in Odin and gamecult-ops, outside
this campaign (section 16); the Yggdrasil smoke below therefore ships its
own archive of the same shape rather than waiting on that change.
- pnpm materialises a `file:` directory dependency as a copy of the
package's `files` entries only: with `pnpm 10.33.0`, `node_modules/cultmesh-ts`
held `README.md`, `dist`, `package.json` and nothing else (no `src`, no
`test`) `(probe: scratch consumer with file: overrides)`. `files` is the
gate, so `native` must be listed in it.
- The MsQuic binaries the koffi probe loaded (P2) are the Unity plugin copies
at `unity/org.gamecult.cultlib/Runtime/Plugins/x86_64/` (`probe.js:4-7`),
committed in plain git (`git ls-files`; `.gitattributes` is `* text=auto`
only, no LFS), `gamecult_mesh_quic_native.dll` 40,448 bytes and
`msquic.dll` 536,928 bytes `(probe)`. Committing binaries beside the code
that loads them is therefore existing practice in this repo, not a new one.
- The Linux runtime is one file: `libmsquic.so.2 -> libmsquic.so.2.5.9`,
7,375,872 bytes, inside the pinned deb (P7); the deb also carries
`libmsquic.lttng.so.2.5.9` and `datapath_raw_xdp_kern.o`, neither needed
`(probe: dpkg-deb -c in debian:13)`. The repo pack is 31.68 MiB today
`(probe: git count-objects)`.
- `debian:13` resolved to digest
`sha256:f324c7ff54321e8d9c588493a20244965938ce0aa50bbd1022d38010e9ffc4b1`
on 2026-09-16 and carries `g++ 4:14.2.0-1` `(probe: docker pull; apt-cache
policy)`. The builder is pinned by that digest, not by the moving tag.
- `GameCult/CultLib` is public `(probe: gh repo view)` and already carries two
GitHub Releases with binary assets, `cultlib-unity-v1.0.3`
(`org.gamecult.cultlib-1.0.3.tgz`) and `gamecult-geometry-v0.1.0` (a crate
and nupkgs) `(probe: gh release view)`; nothing in `scripts/`, `docs/` or
`.github/` creates them, so they were cut by hand `(source read: rg)`.
Release assets on a public repo download with plain `curl`, no token.
- The npm registry is reachable from Starfire: `npm ping` answers `PONG`,
`npm view koffi` is HTTP 200, and `npm view @gamecult/cultcache-ts` is a
404 because it was never published `(probe)`. This confirms the corrected
premise in section 13: C is deferral, not necessity.
- `.gitignore` ignores `artifacts/` (`:66`) and `node_modules`; it has no rule
for `*.so` or `*.dll` `(source read)`, so nothing blocks the commit path.
- The root `package-lock.json` is committed `(probe: git ls-files)`, so
`npm ci` is the real install path (as `publish-packages.yml:55` uses it);
`cultnet-interop.yml:95` uses `npm install --no-package-lock` instead, a
pre-existing inconsistency this cut does not touch.
### 11.2 Q8, the fork C surfaces (operator decision, recommended option first)
Where do the built binaries live so that the `git archive` above carries
them to the host?
- **Option 1, commit them.** `packages/cultmesh-ts/native/{win32-x64,linux-x64}/`
hold the four binaries, committed by the operator from the Release assets
the workflow attaches, with `MANIFEST.txt` and `SHA256SUMS` beside them.
Price: about 8.0 MB in the tree (7,375,872 + 536,928 + 40,448 + the bridge
`.so`, on the order of 60 KB); pack growth roughly the compressed size,
about 3 MB, and that only when the MsQuic pin moves, because
`libmsquic.so.2` and `msquic.dll` are copies of Microsoft's files and
change with the pin, not with the bridge. A bridge rebuild adds tens of KB.
A CI job checks `sha256sum -c SHA256SUMS` on every push, so the manifest
and the bytes cannot drift. Deploy path change required: none beyond the
`packages/cultmesh-ts` archive-list fix already owed. Human step: download,
verify, commit (operator-only, section 11.7).
- **Option 2, fetch them.** `native/<platform>/` is git-ignored; the tree
commits only `MANIFEST.txt`, `SHA256SUMS` and a `scripts/fetch-quic-native.mjs`
(about 80 lines) that downloads the Release assets and verifies digests.
Price: zero binary bytes in git, but every carrier of the package directory
becomes incomplete until the fetch runs: a fresh clone, every worktree,
Heimdall's vendored copy, `npm pack` (a tarball without binaries looks
valid), and the actuator, which must run the fetch and then `tar --append`
the ignored files after `git archive` (cross-repo edit in Odin), or the
deploy script must fetch from GitHub on Yggdrasil at deploy time (cross-repo
edit in gamecult-ops, plus GitHub egress the StreamPixels path does not
have today). It is the "tarball with a `.so` in it by hand" failure the
original Q5 text warned about, moved one step left.
**Recommended: Option 1.** The tarball is a `git archive`, so committed is the
only state that rides it without a second mechanism; the repo already commits
the same `msquic.dll` for Unity; and the growth is bounded by the MsQuic pin,
not by bridge iteration. Everything below is written for Option 1; Option 2
changes only 11.4's manifest paragraph, the closure smoke, and the operator
steps, and is not mapped further unless chosen.
### 11.3 Deletes
None in the tree. The ruling-A surfaces (`packages/cultmesh-quic-native/*`,
`optionalDependencies`, `cultnet-ts`/`cultmesh-ts` publish jobs, new tag
prefixes in `publish-packages.yml:20-24`) are never created; that is the
subtraction, and it is an estimate change, not a diff (section 11.8).
The existing `@gamecult/cultcache-ts` publish job
(`.github/workflows/publish-packages.yml:39-78`) stays. It is out of this
campaign's scope: it publishes a package this migration does not touch, its
only consumer today reaches it by `file:` (`F:\Projects\Heimdall\package.json:22`
`(source read)`), and it is the shape the parked registry pass will copy for
`cultnet-ts` and `cultmesh-ts`. Whether it should run before then is a
question for that pass.
### 11.4 Keeps and moves
- `scripts/build-quic-native.ps1` and the Unity plugin binaries are untouched
(5.4 deletion line). `scripts/build-quic-native.sh` is the cut-3 script,
unchanged here.
- The MsQuic license text already committed at
`unity/org.gamecult.cultlib/Third Party Notices/MSQUIC-LICENSE.txt` is
copied, not referenced, to `packages/cultmesh-ts/native/MSQUIC-LICENSE.txt`,
because the package directory must be self-contained once copied out of the
repo (11.1, pnpm). Same MIT text for both platforms.
### 11.5 Adds
- `packages/cultmesh-ts/native/win32-x64/gamecult_mesh_quic_native.dll`,
`packages/cultmesh-ts/native/win32-x64/msquic.dll`,
`packages/cultmesh-ts/native/linux-x64/libgamecult_mesh_quic_native.so`,
`packages/cultmesh-ts/native/linux-x64/libmsquic.so.2` (the real file, not
the symlink; `RPATH $ORIGIN` from cut 3 resolves it beside the bridge).
Directory names are exactly `${process.platform}-${process.arch}` so the
cut-4 resolver needs no table.
- `packages/cultmesh-ts/native/SHA256SUMS`: `sha256sum` format, one line per
binary, relative paths, generated by the workflow and committed verbatim.
- `packages/cultmesh-ts/native/MANIFEST.txt` (about 20 lines, `key=value`):
`msquic.version=2.5.9`; `msquic.windows.source` = the NuGet URL at
`build-quic-native.ps1:30` with its SHA-256 from `:14`;
`msquic.linux.source` = the deb pool URL from P7 with its SHA-256;
`bridge.commit` = the CultLib commit the bridge was built from;
`build.workflow_run` = the Actions run URL; `build.release` = the Release
tag; `build.win32-x64.host` = runner image plus MSVC version as printed by
the job; `build.linux-x64.host` = `ubuntu-latest` plus the `debian:13`
digest plus `g++` version as printed; and the date. Every value is copied
from the run log by the operator, then the CI check below keeps the file
and the bytes agreeing. The binding never reads this file; it exists for
readers and for the digest check.
- `.github/workflows/quic-native.yml` (about 120 lines), four jobs:
- `build-win32-x64` on `windows-latest`: checkout, run
`scripts/build-quic-native.ps1 -OutputDirectory artifacts/quic-native/win32-x64`,
print `cl.exe` version and `Get-FileHash` of both files, upload
`actions/upload-artifact` named `quic-native-win32-x64`.
- `build-linux-x64` on `ubuntu-latest` with
`container: debian:13@sha256:f324c7ff54321e8d9c588493a20244965938ce0aa50bbd1022d38010e9ffc4b1`
(Q6 A; the digest is the pin, the tag is the label): `apt-get install -y
cmake ninja-build g++ curl ca-certificates dpkg`, run
`scripts/build-quic-native.sh`, print `g++ --version` and `sha256sum`,
upload `quic-native-linux-x64`. No Node in this job; loading is proven by
the interop job below, on the same image.
- `release`, `needs` both, `if: startsWith(github.ref, 'refs/tags/cultmesh-quic-native-v')`,
`permissions: contents: write`: download both artifacts, write
`SHA256SUMS` and a draft `MANIFEST.txt` with every value the jobs printed,
and run `gh release create "$GITHUB_REF_NAME" --verify-tag` with the two
per-platform `.tar.gz` files, `SHA256SUMS` and `MANIFEST.txt` as assets
(`GH_TOKEN: ${{ github.token }}`; `gh` is preinstalled on hosted runners,
no third-party release action). The release notes are the manifest.
- `verify-committed` on `push` and `pull_request`, `ubuntu-latest`, one
step: `cd packages/cultmesh-ts/native && sha256sum -c SHA256SUMS`. This is
the check that the tree's bytes are the bytes the manifest names.
- Triggers: `push` to `main` and `pull_request` run `verify-committed`
only; `workflow_dispatch` runs the two builds (dry run, uploads
artifacts, no release); a `cultmesh-quic-native-v*` tag runs all four.
Only `release` has write permission.
- `packages/cultmesh-ts/package.json:14-16`: `"files": ["dist", "native"]`.
No version bump: under C nothing keys on the version; provenance keys on
the commit in `MANIFEST.txt`.
- `packages/cultmesh-ts/src/realtime-quic-native.ts` (cut 4): the runtime
class gains a readonly `nativeDirectory` (the absolute directory it loaded
from). Diagnostic only; the closure smoke asserts on it.
- `scripts/test-typescript-package-closure.mjs`:
- `:39-41`: for `cultmesh-ts`, assert the packed file list contains all
four binaries, `native/SHA256SUMS`, `native/MANIFEST.txt` and
`native/MSQUIC-LICENSE.txt`, on every host (the tarball carries both
platforms; the host only decides which loads).
- `:59-70`: the runtime smoke adds
`assert.equal(typeof mesh.CultMesh.createQuicRealtimeConnector, "function")`,
the same for `createQuicRealtimeProvider`, then opens a
`CultMeshQuicNativeRuntime`, asserts
`runtime.nativeDirectory` ends with `node_modules/cultmesh-ts/native/<platform>`
(path separators normalised), and closes it. The child at `:70` runs with
`CULTMESH_QUIC_NATIVE_DIR` deleted from its env so the default path is the
one exercised. The point: the binaries load from the installed copy of the
package, not from a repo path or a registry.
- `.github/workflows/cultnet-interop.yml`:
- After the C# RUDP step (`:127-128`): a step building the Windows bridge
(`scripts/build-quic-native.ps1 -OutputDirectory artifacts/quic-native/win32-x64`)
and a step running the `QUIC realtime` lanes with
`CULTMESH_QUIC_NATIVE_DIR` set to that directory, so CI proves the lanes
against a fresh build, then a second run of
`node scripts/test-typescript-package-closure.mjs` proves the committed
Windows binaries load without the env var.
- A second job `interop-quic-linux` on `ubuntu-latest` with the same pinned
`debian:13` container: `apt-get install` the build tools plus `libicu`
(dotnet's runtime need), `actions/setup-dotnet@v4` 10.0.x and
`actions/setup-node@v4` 24 (both work inside a container), build the
bridge with `scripts/build-quic-native.sh`, `npm ci`, run only the
TypeScript-provider-to-managed-connector and TypeScript-to-TypeScript
lanes (section 15: the native-connector lane is Windows by design), then
the closure script without the env var. The container is not optional:
the artifact is linked against Debian 13's glibc 2.41 and `ubuntu-latest`
(24.04) carries glibc 2.39 `(probe: ldd --version in both images)`, so a
symbol version the bridge or `libmsquic` references can be absent on the
bare runner; run the lanes on the image the artifact targets rather than
discover that per symbol.
- `README.md` of `packages/cultmesh-ts` gains a "QUIC Realtime Plane" section
after "RUDP Helpers" (`README.md:332`) with provider and consumer examples
matching the C# README (`src/GameCult.Mesh.Quic/README.md:13-62`).
matching the C# README (`src/GameCult.Mesh.Quic/README.md:13-62`), and a
"Native binaries" paragraph: where they live, that a `file:` dependency or
an `npm pack` tarball carries them, the `CULTMESH_QUIC_NATIVE_DIR`
override, the two provenance files, Windows x64 and Linux x64 (Debian 13
glibc) only, and the four `libmsquic` runtime dependencies (P7) a Linux host
must already have.
Verification:
### 11.6 Per-file changes
- `node scripts/test-typescript-package-closure.mjs` on Windows.
- Manual dispatch of `publish-packages.yml` with `package=cultmesh-ts` builds
and tests without publishing (`:24-32` semantics).
- Operator-only: the tag pushes that publish; `NPM_TOKEN` scope for new
package names; and the Yggdrasil verification: `ssh gamecultadmin@yggdrasil.gamecult.org`,
`mkdir /tmp/cultmesh-quic-smoke && cd $_ && npm init -y && npm i cultmesh-ts@<version>`,
then `node -e "require('cultmesh-ts').CultMesh.createQuicRealtimeProvider({...}).then(p => { console.log(p.advertisedEndpoint); return p.dispose(); })"`
with a throwaway PKCS12 from `openssl`, followed by a loopback dial from a
second `node` process on the same host. `libmsquic`'s runtime dependencies
(`libssl3t64`, `libnuma1`, `libxdp1`, `libnl-route-3-200`, P7) must be
present on Yggdrasil; the smoke will say so if not. This is the only place
the Linux artifact is proven on the deploy host, and only the operator holds
the key.
- `packages/cultmesh-ts/package.json:14-16`, `files` gains `"native"`.
- `packages/cultmesh-ts/src/realtime-quic-native.ts` (cut 4 file), one
readonly field `nativeDirectory` set at load.
- `scripts/test-typescript-package-closure.mjs:39-41`, `:59-70` as above;
`:9` unchanged (no new packages).
- `.github/workflows/cultnet-interop.yml`, two steps after `:128`, one job
after `:140`.
- `.github/workflows/quic-native.yml`, new.
- `.github/workflows/publish-packages.yml`, unchanged.
- `packages/cultmesh-ts/native/` (seven files), new, four of them binary and
operator-committed (11.7).
- `packages/cultmesh-ts/README.md`, one section after `:332`.
### 11.7 Verification
- `node scripts/test-typescript-package-closure.mjs` on Windows, with
`CULTMESH_QUIC_NATIVE_DIR` unset in the shell. Pins: the tarball carries
both platforms and the provenance files; the installed copy loads its own
binaries.
- `cd packages/cultmesh-ts/native && sha256sum -c SHA256SUMS` (Git Bash on
Windows). Pins: committed bytes equal the manifest.
- `git check-ignore -v packages/cultmesh-ts/native/linux-x64/libmsquic.so.2`
must exit 1 (not ignored), and
`git ls-files packages/cultmesh-ts/native | wc -l` must print 7. Pins: the
binaries are tracked, so a `git archive` carries them.
- `npm pack packages/cultmesh-ts --dry-run --json | node -p "JSON.parse(require('fs').readFileSync(0,'utf8'))[0].files.map(f=>f.path).filter(p=>p.startsWith('native/')).join('\n')"`
must list seven `native/` paths; the closure script already asserts this,
this is the one-liner for a reader.
- `workflow_dispatch` of `quic-native.yml`: both build jobs green, artifacts
present, no release created. A tag push `cultmesh-quic-native-v<n>`
creates the Release with four assets. Pins: Q6 A, the builder is a Linux
host on the deploy OS and the artifact has a public, digest-named home.
- Negative greps (must return nothing):
`rg -n "optionalDependencies|cultmesh-quic-native-(win32|linux)|@gamecult/cultmesh-quic-native" packages scripts .github --glob '!**/node_modules/**' --glob '!**/dist*/**'`
(no platform packages exist);
`rg -n "node_modules|require\.resolve" packages/cultmesh-ts/src/realtime-quic-native.ts`
(the resolver never searches for a package);
`rg -n "\"(pre|post)install\"" packages/*/package.json` (no install-time
compile or download);
`rg -n "NPM_TOKEN|npm publish|registry-url" .github/workflows/quic-native.yml`
(the native workflow publishes to no registry).
- Operator-only, in order:
1. After the tag build, download the Release assets, compare every digest
with the run log and with `SHA256SUMS`, place the binaries under
`packages/cultmesh-ts/native/<platform>/`, fill `MANIFEST.txt` from the
log, commit. This is the only path bytes take into the tree; no workflow
writes to `main`.
2. Yggdrasil smoke, which installs from what C ships (the archived tree)
and nothing else. On Starfire, at the commit from step 1:
`git -C F:\Projects\CultLib archive --format=tar --output=$env:TEMP\cultlib-quic-smoke.tar <commit>`
(the actuator's own mechanism, `deploy-yggdrasil-streampixels.ps1:51,59`,
whole tree), then `sftp` it to `gamecultadmin@yggdrasil.gamecult.org:/home/gamecultadmin/`.
On Yggdrasil:
`mkdir -p /tmp/cultmesh-quic-smoke && tar -xf ~/cultlib-quic-smoke.tar -C /tmp/cultmesh-quic-smoke && cd /tmp/cultmesh-quic-smoke`;
`(cd packages/cultmesh-ts/native && sha256sum -c SHA256SUMS)` (the bytes
that arrived are the bytes the manifest names);
`ldd packages/cultmesh-ts/native/linux-x64/libmsquic.so.2 | grep "not found"`
must print nothing. If it prints, the missing ones are among
`libnuma1`, `libxdp1`, `libnl-route-3-200` (P7; `libssl3t64` is base):
under C nothing installs them because the deb itself is never installed
on the host, so `sudo apt-get install` them once and record it in
`gamecult-ops/inventory.md` beside the Node line (`:660`). Then
`npm ci` (registry access from Yggdrasil is the deploy path's own
assumption, `deploy-streampixels-preview.sh:102`) and
`node scripts/test-typescript-package-closure.mjs` with the env var
unset: this is the same smoke CI runs, now on Node 24.14.1 (P8) on the
deploy host, loading `node_modules/cultmesh-ts/native/linux-x64`.
Then the handshake: `npm run test --workspace packages/cultmesh-ts`
(builds `dist-test` and runs the cut-4/5 suites on the host), then a
throwaway PKCS12
(`openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 -nodes -subj /CN=127.0.0.1 -days 2 -keyout k.pem -out c.pem && openssl pkcs12 -export -inkey k.pem -in c.pem -passout pass:smoke -out smoke.p12`),
`node packages/cultmesh-ts/dist-test/test/interop/cultmesh-quic-peer.js serve --frames 5 --delivery latest-only --pkcs12 smoke.p12 --password smoke`
in one shell (it prints the advertised endpoint), and
`node packages/cultmesh-ts/dist-test/test/interop/cultmesh-quic-peer.js dial --endpoint <printed> --expect 5`
in a second, which must print five frames. If cut 5 landed `serve` with
a generated certificate instead of `--pkcs12/--password` flags, add the
flags in this cut; the smoke needs a certificate it can name. Finish
with `rm -rf /tmp/cultmesh-quic-smoke ~/cultlib-quic-smoke.tar`. This is
the only place the Linux artifact is proven on the deploy host, and only
the operator holds the key.
3. Nothing here touches `/srv/streampixels`; StreamPixels adoption
(archive list, `:97`, its stale lockfile) is consumer work (section 15,
section 16).
### 11.8 Subtraction estimate delta against section 14
Row 6 of the table read `0 removed, 60 (manifests) + 130 (workflow) + 30
(closure) + 60 (README) = +280` with `+2 optional platform packages` and `+3
publish jobs` in the dependencies line. Under C:
- Removed: 0 (the `cultcache-ts` job stays, 11.3).
- Added text: about 120 (`quic-native.yml`) + 40 (interop workflow) + 30
(closure) + 70 (README) + 25 (`MANIFEST.txt`, `SHA256SUMS`) + 1
(`package.json`) = about +285, the same order as before; the 60 lines of
platform-package manifests are gone and the release/verify jobs take their
place.
- Added binary: four files, about 8.0 MB in the tree under Option 1, 0 under
Option 2. Section 14 has no column for this; it is the real price of C and
is stated here so it is not hidden in a line count.
- Dependencies line becomes: +0 optional platform packages (was +2); +0
publish jobs (was +3); +1 workflow file with four jobs (two builds, one
release, one digest check) and +1 job in the interop workflow (was "+1 CI
job"). Runtime dependency unchanged: `koffi` only.
- Campaign total: about +3,900 source lines, unchanged; plus 8.0 MB of
committed binaries.
### 11.9 Parked seam: registry publication (later pass)
Not in this campaign, by the operator's choice (section 13). When it is
picked up, it reattaches here without remapping the rest:
- `publish-packages.yml` gains `cultnet-ts` and `cultmesh-ts` jobs shaped like
`:39-78`, tag prefixes at `:20-24`, dispatch options at `:30-33`; the
`cultmesh-ts` job `needs` the two `quic-native.yml` build jobs (or the
workflow is merged) and publishes the artifacts they already produce as
`@gamecult/cultmesh-quic-native-{win32-x64,linux-x64}` platform packages.
- `packages/cultmesh-ts/package.json` gains `optionalDependencies` on those
two names; `realtime-quic-native.ts` gains a third resolution branch after
the env var and before the committed `native/` directory, or the committed
directory is retired in the same pass.
- Naming (unscoped `cultnet-ts`/`cultmesh-ts` versus `@gamecult/*`) is the
original Q5 A/B fork, still open for that pass; P14 recorded all names
unclaimed on 2026-09-16.
- Its Body precondition is an `NPM_TOKEN` repository secret minted on
npmjs.com, which the operator can now reach (section 13).
## 12. Cut 7 (documentation and ledgers)
@ -955,9 +1291,21 @@ Verification:
the `ICultMeshRealtimeLookupSource` port as the seam (Q7).
- `docs/typescript-quic-realtime-target.md:5-7`: status line updated to point
at this map.
- Under Q5 C, the delivery story every document tells is the one in section
11: the binding ships inside `packages/cultmesh-ts/native/`, provenance
lives in `MANIFEST.txt` and `SHA256SUMS`, and consumers keep `file:` paths.
`native/GameCult.Mesh.Quic.Native/README.md` (cut 3) and
`packages/cultmesh-ts/README.md` (cut 6) both point at `MANIFEST.txt` as the
provenance owner rather than restating versions or digests. The parity row
above says "bindings shipped in the `cultmesh-ts` package tree", not
"published". Registry publication is described in exactly one place, as
parked: section 11.9 of this map.
Verification: `rg -n "CultMeshRealtimeTransports.cs" docs src/GameCult.Mesh/docs`
returns only correct paths.
returns only correct paths;
`rg -n -i "registry|npm publish|platform package|optionalDependencies" packages/cultmesh-ts/README.md native/GameCult.Mesh.Quic.Native/README.md docs/runtime-parity-scope.md src/GameCult.Mesh/docs/transport-planes.md`
returns nothing (the only permitted mentions are this map's sections 11.9 and
13 and the target's history).
## 13. Operator questions
@ -1012,18 +1360,23 @@ Each is now a standing ruling; the options above are history.
- **Q5 ruled A, then re-ruled C the same day.** A had `cultnet-ts` and
`cultmesh-ts` publishing under their unscoped names with only the two native
platform packages scoped. It fell to a Body fact the map had not recorded,
in the operator's words: "we don't even have npm access and cannot get it
because our entire subnet is blocked." The publish job needs an `NPM_TOKEN`
minted on npmjs.com by a logged-in user; nobody on this network can mint
one, which is also why the existing `cultcache-ts` job has never run.
**C stands: no registry.** Consumers keep `file:` paths. The native binaries
ship inside the CultLib tree the deploy path already carries, and Q6's
Actions build attaches the Linux artifact to a GitHub Release instead of
publishing a package. Q5's naming question dissolves with it. Cut 6 is
remapped under C below; Cut 4's binary resolution and Cut 7's ledgers
follow it. Any line in this map that still says "publish", "registry" or
"platform package" describes A and is history.
platform packages scoped. The re-ruling was first stated as necessity ("we
don't even have npm access and cannot get it because our entire subnet is
blocked"); the operator corrected that Body fact the same day after
reaching npm signup: "apparently that was true yesterday." The registry is
reachable from Starfire (`npm ping` answers, section 11.1 `(probe)`), and an
`NPM_TOKEN` can be minted. **C still stands for this campaign, by choice:
no registry.** In the operator's words, registry publication is "still for
a later pass". Consumers keep `file:` paths. The native binaries ship inside
the `cultmesh-ts` package tree that the deploy path's `git archive` carries,
and Q6's Actions build attaches both platform artifacts to a GitHub Release
instead of publishing packages. Registry publication of `cultnet-ts`,
`cultmesh-ts` and the native binaries is parked, not ruled out; section 11.9
names the seam it reattaches to, and the original A/B naming fork stays
open for that pass. Cut 6 is remapped under C (section 11); section 5.4,
Cut 4's binary resolution and dependency lines, and Cut 7's ledger follow
it. The one fork C surfaces, whether the binaries are committed or fetched
from the Release, is Q8 in section 11.2 and is open.
- **Q6 ruled A.** The Linux release artifact is built by GitHub Actions on
`ubuntu-latest` inside `container: debian:13`, published by the workflow,
and verified by the operator smoke on Yggdrasil in cut 6. The Docker
@ -1051,10 +1404,13 @@ Both sides of the number, by cut, in source lines (tests included, generated
| Total | ~350 | ~4,260 | about +3,900 |
Dependencies: +1 runtime dependency on `cultmesh-ts` (`koffi`, 1.7 MB, MIT,
loaded lazily); +2 optional platform packages; +0 build-time Node
loaded lazily); +0 optional platform packages; +0 build-time Node
dependencies (no node-gyp, no node-addon-api, no cmake-js). Targets: +0 .NET
projects (the C# interop peer gains one project reference); +1 CMake platform
branch; +1 shell build script; +3 publish jobs; +1 CI job.
branch; +1 shell build script; +1 workflow file with four jobs; +1 job in
the interop workflow; and, under Q8 option 1, about 8.0 MB of committed
binaries. *(This line first read "+2 optional platform packages; +3 publish
jobs; +1 CI job" under ruling A; section 11.8 carries the delta.)*
Why the number is positive and still acceptable: the target orders a new
capability (a QUIC realtime plane in a runtime that has none), and every line
@ -1087,7 +1443,16 @@ about line count.
TypeScript-to-TypeScript lanes only. The native-connector lane is Windows
by design, matching where Unity runs.
- **The `cultcache-ts` naming split** across consumers (section 3). Out of
scope; noted because Q5's answer should not make it worse.
scope. Q5 C touches no package name and publishes nothing, so it makes the
split neither better nor worse; the split becomes the parked registry
pass's problem (section 11.9), where the A/B naming fork is still open.
One consequence to carry there: StreamPixels' lockfile resolves
`cultmesh-ts`'s cache dependency as unscoped `cultcache-ts`
(`F:\Projects\StreamPixels\pnpm-lock.yaml:2561-2564` `(source read)`) while
`packages/cultmesh-ts/package.json:46` now names `@gamecult/cultcache-ts`,
so a `pnpm install --frozen-lockfile` against the current tree would refuse
before any QUIC code is reached. Consumer work, recorded so the Yggdrasil
smoke in section 11.7 is not mistaken for StreamPixels adoption.
## 16. Reminder of what a wrong cut looks like