0
0
plan: docs/plans/0007-compute-provider-kcp.yaml
item: M1-FC-INVENTORY
written: "2026-10-12"
gold_standard: >-
hono-compute-provider lib/compute-provider-firecracker (TypeScript), with lib/microvm-firecracker,
lib/node-image-firecracker, lib/oidc-issuer-hono (the provisioning enricher and issuer) and the
atproto-market lib/common/cloud-init-common modules a firecracker guest's user_data composes. Each entry is
one learning the Go side (cmd/socialweb-nodeboot, cmd/socialweb-nodeimage, internal/nodevm,
internal/nodefirecracker, and the planned internal/vmruntime + internal/computevm ComputeVM controller)
must meet, must not inherit, or that is dropped.
parity_boundary: >-
M2-BACKPORT: the VMSpec handed to vmruntime.Prepare, the seed drive's bytes, fc.json, the bid config
record and the issuer's droplet view. One recorded RFP fixture (testdata/compute-parity/: vm record,
requester, accept bundle, contract) is run through ts/hono-compute-provider/test/compute_parity_test.ts (the
firecracker provider, microvm stubbed at that boundary) and internal/computevm/parity_test.go (the Go
controller, unit start stubbed at the same boundary); names and addresses the fixture marks as allocated
are excluded. A parity id written TestParityX names one case run by BOTH files against that fixture; any
other id names the test file and case that proves the entry.
fields:
id: FC-<learning>
source: TypeScript file:line or file:start-end, relative to the root of this repository
behaviour: what the TypeScript does and why, including the live reading that taught it
go_side: "meets: yes | partial | no | not-applicable (the behaviour stays TypeScript by design), and where"
parity_test: the test ids that will prove the Go side (or prove the removal)
status: "port | removed-legacy (non-iroh guest transport or the guest JSR registry: not ported, still in the TypeScript) | removed (removed from the TypeScript by 0008 M1-STRIP-LEGACY-TRANSPORTS; a source written path@<commit>:lines cites the code as it was at that commit, the last one before the removal) | superseded-by-<plan item>"
covers: exported functions, constants and logger events of compute-provider-firecracker/mod.ts and microvm-firecracker/mod.ts this entry accounts for (checked by hono-compute-provider test/requirements_inventory_test.ts)
legacy_decision: >-
docs/research/2026-10-11-vm-lifecycle/user-decisions.md (2026-10-12, multi-server-to-kcp section 7 cont.):
STRIP ALL NON-IROH GUEST TRANSPORTS as legacy (cloud-init-common tunnel / fedproxy-ssh / fedproxy-web /
web-terminal modules, websocat ProxyCommand paths, relay-fqdn guest addresses); this removes the guest JSR
registry. Entries with status removed-legacy are not ported; entries with status removed are also gone from
the TypeScript (0008 M1-STRIP-LEGACY-TRANSPORTS; atproto-market b78adc1 and hono-compute-provider 54d1b8f
carry them).
requirements:
- id: FC-USERDATA-REQUIRED
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:634-645
behaviour: >-
An RFP with no user_data is refused before a name, a work dir or an address is allocated. On this
provider the user_data IS the guest: a guest started without one reaches Running with no sshd, no
transport and no secrets, unreachable.
go_side:
meets: yes
detail: >-
M2-BACKPORT: compute-provider-kcp refuses an RFP with no user_data before a name exists; the ComputeVM
controller waits for the user_data Secret and fails a ComputeVM whose Secret holds no user-data before
Prepare clones anything (internal/computevm userData, boot).
parity_test:
- TestParityAnRfpWithoutUserDataIsRefusedBeforePrepare
status: port
covers: [createComputeProviderFirecracker]
- id: FC-GUEST-NAME
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:116
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:151-162
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:646-647
behaviour: >-
A guest's name is fc-<12 hex of a hash of the requester DID>-<8 hex of a random UUID>. The one name is
the providerId, the runner container's name, the work dir's last segment, the cloud-init instance-id
and local-hostname, and the droplet id the provisioning nonce is bound to (associateWithDroplet). It
never reaches the requester as an address (FC-OIDC-REPORTER-NO-HOSTNAME).
go_side:
meets: yes
detail: >-
M2-BACKPORT: One name: the ComputeVM name is the providerId, the HostProcess child vm-<name>, the unit
socialweb-vm-<hid>-<name>, the work dir <state>/handles/<hid>/vms/<name>, the seed's instance-id and
local-hostname (internal/vmruntime Prepare) and the droplet id the nonce is bound to.
parity_test:
- TestParityTheGuestNameIsTheProviderIdInstanceIdAndNonceBinding
status: port
- id: FC-ENRICH-ORDER
source:
- ts/atproto-market/lib/market-bidder-compute/mod.ts:376-387
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:652-671
behaviour: >-
user_data is enriched in a fixed order, each step reading what the earlier ones wrote: (1) the bidder
injects the accept bundle (with guest_onnetwork_url) before provision; (2) the OIDC enricher adds the
provisioning-token exchange and its on-network reporter; (3) withOnNetworkReporter (no-op when a
reporter is present); (4) withOnNetworkBaseUrl (no-op when base_url is named); (5) injectJsrUrl
(legacy, FC-JSR-REGISTRY); (6) the host address is the requester-named relay.localhost address, else
the runtime's host address, logged as guest_host_address; (7) pointGuestAtHost (TLS port rewrite,
/etc/hosts, .curlrc); (8) the result is written to <workDir>/user-data.yaml, which is exactly the seed.
go_side:
meets: not-applicable
detail: >-
Decided in M2-BACKPORT: pure enrichment stays TypeScript (compute-provider-common, applied by
compute-provider-kcp before the ComputeVM is written); the Go side writes the enriched bytes into the
cidata drive unchanged and never re-composes them.
parity_test:
- TestParityTheSeedUserDataEqualsTheProvidersByteForByte
status: port
covers: [guest_host_address]
- id: FC-ENRICH-ONCE
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:322-348
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:524-559
- ts/atproto-market/lib/common/cloud-init-common/mod.ts:168-214
- ts/atproto-market/lib/common/cloud-init-common/mod.ts:276-345
behaviour: >-
The reporter and base_url steps detect themselves by marker (guest-onnetwork.service, the base_url
path) and are idempotent; buildUserData dedupes write_files by path (later wins, first position keeps),
set-unions packages and bootcmd, puts runcmdPrepend before the base runcmd and re-asserts the resolver
once at the end. Two steps are NOT idempotent: the OIDC enricher mints a new nonce and token per call,
and pointGuestAtHost appends its /etc/hosts runcmd and .curlrc entry again. So enrichment must run
exactly once per guest.
go_side:
meets: not-applicable
detail: >-
compute-provider-kcp enriches once and stores the result on the ComputeVM spec; a controller restart,
re-adoption or a re-Prepare reads the stored bytes and never enriches again.
parity_test:
- TestParityAReadoptedComputeVMKeepsItsSeedBytes
- ts/hono-compute-provider/test/compute_parity_test.ts::"enrichment runs once per ComputeVM"
status: port
- id: FC-ACCEPT-BUNDLE
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:164-170
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:937-938
- ts/atproto-market/lib/common/cloud-init-common/mod.ts:346-369
- ts/atproto-market/lib/market-bidder-compute/mod.ts:376-384
behaviour: >-
The accept bundle {$type market.accept, accept, rfp, bid, bid_config (strongRef wrapper {uri, cid,
value}), vm, guest_onnetwork_url} is written as JSON at the accept path (DEFAULT_ACCEPT_PATH_VM,
/root/secrets/publicdomainrelay.com/market/accept.json), root:root 0600, its parent created 0700 by a
prepended runcmd. It is per contract and never baked into an image.
go_side:
meets: not-applicable
detail: >-
Composed in TypeScript; the Go side carries it inside the seed bytes. M2-VM-RUNTIME's cidata drive
must hold the user-data verbatim so the path and mode survive.
parity_test:
- TestParityTheAcceptBundleIsAtTheAcceptPathWithMode0600
status: port
covers: [injectAcceptBundle]
- id: FC-ONNETWORK-URL
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:172-182
- ts/atproto-market/lib/market-bidder-compute/mod.ts:383
behaviour: >-
The guest reports to the URL in the bundle's guest_onnetwork_url (the bidder's own /v1/on-network,
which holds the accept-to-receipt map and submits the wrapped event); with none, this provider's issuer
URL + /v1/on-network.
go_side:
meets: not-applicable
detail: >-
The route stays TypeScript (compute-provider-kcp, M4-ONNETWORK; a guest-facing DenoPod after
M4-BIDDER-VAULT). The port derivation from the tunnel subscriber's --ingress-proxy-host flag in
guestOnNetworkUrl is legacy (FC-LEGACY-TUNNEL-MODULE). As built in Go (plan 0034): the guest posts
to the bidder GuestControlPlane's POST /v1/events at http://192.0.2.1:<port>, with the ingress URL as
fallback; /v1/on-network is gone.
parity_test:
- ts/hono-compute-provider/test/firecracker_onnetwork_reporter_test.ts::"the bundle's guest_onnetwork_url is what the guest reports to"
- TestParityTheSeedUserDataEqualsTheProvidersByteForByte
status: port
covers: [onNetworkUrlFromBundle]
- id: FC-ONNETWORK-TARGETS
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:184-211
behaviour: >-
The report is tried at the URL as written and, when the user_data names `<ip> relay.localhost` and the
URL's host is a .localhost name, again with curl --resolve <host>:<port>:<ip>: the guest's /etc/hosts
line for a relay name may be the microVM's gateway, which carries no arbitrary port.
go_side:
meets: not-applicable
detail: TypeScript enrichment; on the Go side the address in the alias is the constant pasta gateway (FC-HOST-ADDRESS).
parity_test:
- ts/hono-compute-provider/test/firecracker_onnetwork_reporter_test.ts::"a relay name behind a dispatcher is also tried at the address the guest reaches it on"
status: port
covers: [onNetworkTargets]
- id: FC-REQUESTER-NAMED-HOST
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:510-522
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:667
behaviour: >-
A host address the requester already named (`<ip> relay.localhost`, the market network's guestHostAliases) is the
one the provider uses for every .localhost name: cloud-init resolves before the provider's runcmd can
append a second line, so a different address would be the line that never wins.
go_side:
meets: yes
detail: >-
M2-BACKPORT: compute-provider-kcp points every .localhost name at the address the requester named
(addressTheRequesterNamed), else the constant pasta host address 192.0.2.1; pasta forwards both to the
host.
parity_test:
- ts/hono-compute-provider/test/firecracker_network_test.ts::"a host address the requester already named is the one the guest is given"
- TestParityARequesterNamedRelayAddressWins
status: port
covers: [addressTheRequesterNamed]
- id: FC-HOST-ADDRESS
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:53-65
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:297-302
behaviour: >-
The address a guest dials this host at is the runner container's default bridge gateway
(backend.defaultGateway()), not pasta's gateway, which is the container itself and answers nothing.
go_side:
meets: no
detail: >-
No container on the Go side. Decided 2026-10-11: every guest gets the identical address plan inside
its private pasta user+net namespace and the host address is pasta's mapped gateway, a constant
vmruntime exports and compute-provider-kcp uses for enrichment (M2-VM-RUNTIME).
parity_test:
- TestParityTheHostAddressIsThePastaMappedGateway
status: superseded-by-M2-VM-RUNTIME
- id: FC-ONNETWORK-REPORTER-FALLBACK
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:213-304
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:338-348
behaviour: >-
When no OIDC enricher composed a reporter, the provider composes its own (two reporters would race to
publish the same event): waits up to 180 s for /run/guest-fqdn, posts {acceptUri, acceptCid, address}
to each target, 5 rounds 6 s apart, stops at the first 200, logs to journal+console. Script and unit
ride in user_data, never in the image.
go_side:
meets: not-applicable
detail: >-
TypeScript enrichment. Ported with the rules the live run taught the OIDC reporter: ordered after
iroh.service, never posts a hostname (FC-OIDC-REPORTER-NO-HOSTNAME); its tunnel-subscriber ordering
is FC-LEGACY-REPORTER-TUNNEL-ORDERING.
parity_test:
- ts/hono-compute-provider/test/firecracker_onnetwork_reporter_test.ts::"user_data that already reports the FQDN is left alone"
- TestParityTheSeedUserDataEqualsTheProvidersByteForByte
status: port
covers: [onNetworkReporterModule, withOnNetworkReporter]
- id: FC-ONNETWORK-BASE-URL
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:306-336
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:469-482
behaviour: >-
With no issuer, the provider writes <SECRETS_PREFIX>/base_url (the report URL's origin, 0600) so the
reporter does not fall back to the public dispatcher and 404. It is skipped whenever the user_data
names that path, because provisioning-token.service has ConditionPathExists=!base_url and a pre-written
base_url would stop the token exchange.
go_side:
meets: not-applicable
detail: TypeScript enrichment; carried in the seed bytes.
parity_test:
- ts/hono-compute-provider/test/firecracker_onnetwork_reporter_test.ts::"the guest is told where to report, without an OIDC exchange having to succeed"
status: port
covers: [withOnNetworkBaseUrl]
- id: FC-OIDC-REPORTER-NO-HOSTNAME
source:
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:484-541
- ts/atproto-market/lib/abc/compute-request/mod.ts:269-275
behaviour: >-
Live hat-8 2026-10-11T23:53Z (hono-compute-provider 033a8c0, atproto-market 6099aac): the reporter
waited 60 s and then posted $(hostname), and the requester polled wss://fc-1379be663dd9-762b64d5/ until
timeout. Now it waits 600 s for /run/guest-fqdn, is ordered After=iroh.service with
TimeoutStartSec=900, logs to journal+console, never falls back to the hostname, and on giving up dumps
pending jobs and the transport units' status and fails the unit; the requester classifies a
single-label address as a hostname and keeps waiting. With no base_url the reporter now exits 1 instead
of falling back to a public dispatcher, and a provisioning whose issuer has no http(s) base URL is
refused at provision time (plan 0007 M3-OIDC-ISSUER-INSTANCE).
go_side:
meets: not-applicable
detail: TypeScript enricher; carried in the seed bytes.
parity_test:
- ts/hono-compute-provider/test/oidc_onnetwork_reporter_test.ts::"the oidc reporter never publishes the guest's hostname as its address"
- ts/hono-compute-provider/test/oidc_onnetwork_reporter_test.ts::"the oidc reporter waits for the transport long enough for a slow boot and says why when it gives up"
- ts/hono-compute-provider/test/compute_parity_test.ts::"the reporter has no fallback base URL"
- ts/hono-compute-provider/test/oidc_issuer_instances_test.ts::"the on-network reporter has no hardcoded base URL and fails closed without one"
status: port
- id: FC-IROH-LISTENER-ORDERING
source:
- ts/atproto-market/lib/common/cloud-init-common/mod.ts:562-726
behaviour: >-
Live hat-8 2026-10-11T23:53Z (atproto-market ad659c1): `systemctl enable --now ssh` in runcmd never
returned and iroh.service was ordered After=ssh.service, so no ticket reached /run/guest-fqdn in time.
Now iroh.service is After=network-online.target only (dumbpipe dials 127.0.0.1:22 per stream), runcmd
enables and starts it --no-block before ssh, ssh starts --no-block, the ticket is written as
iroh://<ticket> to /run/guest-fqdn through a temp file and mv, IROH_SECRET persists 0600 so the
endpoint id survives restarts, Restart=always. Re-run: ticket 6.5 s after boot, ssh ready ~20 s after
the request. iroh is the only guest transport kept.
go_side:
meets: partial
detail: >-
The module stays TypeScript and rides in the seed. The guest image (M1-GUEST-IMAGE) must not bake any
unit that orders iroh after ssh; dumbpipe is still fetched from GitHub at boot by setup-iroh.sh unless
the image carries the pinned version.
parity_test:
- ts/atproto-market/test/cloud_init_snapshot_test.ts::"iroh listener never waits on sshd and no runcmd step blocks on a unit start"
- TestParityTheSeedUserDataEqualsTheProvidersByteForByte
status: port
- id: FC-BID-CONFIG-TOKEN-PATH
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:27
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:35
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:659-675
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:460-465
- ts/atproto-market/lib/common/cloud-init-common/mod.ts:362-490
behaviour: >-
The bid config record (com.publicdomainrelay.temp.compute.config.wif.simple) carries accept_path,
issuer_uri, to_issue exchange-firecracker-oidc, actx (last segment of the bidder DID), and under
SECRETS_PREFIX /root/secrets/digitalocean.com/serviceaccount: actx_path team_uuid, token_path token,
url_path base_url; url_route /v1/oidc/issue; subject actx:{actx}:plc:{did-plc-key}:role:{role}.
token_path must be the file provisioning-token.sh writes: before 4d7da59 it named another path and
setup-secrets.service, which reads bid_config.value (or the inline record) from accept.json, waited for
a token that never appeared.
go_side:
meets: yes
detail: >-
M2-BACKPORT: compute-provider-kcp createBidConfig writes the same wif.simple record (accept_path,
issuer_uri, exchange-firecracker-oidc, actx, SECRETS_PREFIX token, team_uuid and base_url paths).
parity_test:
- TestParityTheBidConfigRecordEqualsTheProviders
- ts/hono-compute-provider/test/firecracker_secrets_path_test.ts::"the firecracker bid config points the guest at the token the provisioning script writes"
status: port
covers: [SECRETS_PREFIX, WIF_SIMPLE_NSID]
- id: FC-GUEST-TLS-PORT-AND-CURLRC
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:524-559
- ts/atproto-market/request-vm-ssh/mod.ts:329-333
behaviour: >-
With guestTlsPort set (a market network dispatcher off 443), every https://<name>.localhost URL without a port is
rewritten to :<guestTlsPort>, /root/.curlrc gets `resolve = *:<port>:<hostAddress>`, and every
.localhost name gets a prepended runcmd line `<hostAddress> <name>` in /etc/hosts; a user_data that is
not YAML is refused. .curlrc reaches systemd units only when CURL_HOME is set, which the market network requester
does with `systemctl set-environment CURL_HOME=/root` in bootcmd.
go_side:
meets: yes
detail: >-
M2-BACKPORT: compute-provider-kcp applies pointGuestAtHost with the bidder's guest TLS port before the
ComputeVM is written; the seed carries the bytes verbatim.
parity_test:
- TestParityTheGuestTlsPortRewriteHostsAndCurlrc
status: port
- id: FC-NETWORK-RANGE-INDEX
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:108-110
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:132-149
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:570
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:648
behaviour: >-
Each guest gets a /30 out of rangeBase (default 172.30.0.0): pasta .0, gateway .1, guest .2. The index
is a process-local counter, never reused, 16384 blocks, exhausted rather than wrapped.
go_side:
meets: no
detail: >-
Decided 2026-10-11: an IDENTICAL address plan for every guest inside its private pasta namespace; the
network-index allocator is deleted. nodevm.Network has one default plan today
(internal/nodevm/spec.go:37-43, 156-232).
parity_test:
- TestParityEveryGuestGetsTheSameAddressPlan
- internal/vmruntime TestPrepareWritesASeedDriveAndFcJsonAndNoHostToolIsExecd
status: superseded-by-M2-VM-RUNTIME
covers: [networkFor]
- id: FC-GUEST-MAC
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:118-130
behaviour: >-
The guest MAC is 06:00:<the guest IPv4's four octets in hex>, so the guest's network setup configures
the address the host routed; it is derived only from an IPv4 address.
go_side:
meets: yes
detail: >-
nodevm.DefaultGuestMAC 06:00:ac:10:00:02 encodes 172.16.0.2 by the same rule
(internal/nodevm/spec.go:39, 241-242); with the identical plan it is the constant fc.json
network-interfaces MAC.
parity_test:
- TestParityFcJsonMacEncodesTheGuestAddress
status: port
covers: [guestMacFor]
- id: FC-GUEST-IS-NOT-GATEWAY
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:202-208
behaviour: >-
A guest addressed as its own gateway is refused before anything starts: it would ARP for itself and
its frames would be answered by the interface that sent them.
go_side:
meets: yes
detail: nodevm Network.Validate refuses guest == gateway and pasta == gateway (internal/nodevm/spec.go:156-232).
parity_test:
- TestParityTheConstantAddressPlanValidates
status: port
- id: FC-RESOLVER-GATEWAY
source:
- ts/atproto-market/lib/common/cloud-init-common/mod.ts:117-129
- ts/atproto-market/lib/common/cloud-init-common/mod.ts:287-319
behaviour: >-
/etc/resolv.conf names the DNS gateway first, then 1.1.1.1 and 9.9.9.9, then any nameserver a caller
wrote; it is written in write_files and re-asserted last in bootcmd and in runcmd. The default gateway
172.30.0.1 is the first block of the TypeScript provider's range.
go_side:
meets: yes
detail: >-
M2-BACKPORT: The identical guest network's gateway is 172.30.0.1 (internal/guestnet Gateway, pasta
--dns-forward), the same address as DEFAULT_DNS_GATEWAY.
parity_test:
- TestParityTheResolverNamesTheConstantGatewayFirst
status: port
- id: FC-PACKAGES-GUARD
source:
- ts/atproto-market/lib/common/cloud-init-common/mod.ts:207-249
behaviour: >-
Packages the modules ask for leave cloud-init's apt module and become the first runcmd entry, a dpkg -s
guard that runs apt only for what the image lacks; package_update is false; names are validated before
entering a shell command. A baked image therefore runs no apt at boot.
go_side:
meets: not-applicable
detail: TypeScript composer; the image must carry the packages (FC-PREINSTALL-MANIFEST).
parity_test:
- TestParityTheSeedUserDataEqualsTheProvidersByteForByte
status: port
- id: FC-PREINSTALL-MANIFEST
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:350-508
behaviour: >-
The image's baked list is derived from module ids only (a module function is refused: it closes over
one contract, e.g. its accept.json). A package, file or prepended command is baked only when the module
emits it identically with and without instance values; everything else is left to boot. The last
module to write a path wins; prepended commands keep their order; argv commands are shell-quoted; files
owned by anyone but root, apt sources and non-command runcmd entries are refused rather than baked
wrong.
go_side:
meets: partial
detail: >-
cmd/socialweb-nodeimage applies a manifest in a chroot on the bidder (preinstall.go:32 LoadPreinstall,
:140 chrootPreinstall; ensure.go:209 refuses an image that does not carry it). M1-GUEST-IMAGE bakes
the manifest in scripts/build-guest-image.sh on a build host instead.
parity_test:
- ts/hono-compute-provider/test/preinstall_manifest_test.ts
- build-pipeline TestTheImageCarriesThePreinstallManifest
status: port
covers: [preinstallManifest, shellCommandLine]
- id: FC-IMAGE-ENSURE
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:597-611
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:940-942
- ts/hono-compute-provider/lib/node-image-firecracker/mod.ts:19-126
behaviour: >-
`socialweb-nodeimage -ensure -json [-reuse-stale] [-preinstall p] -config c`; the last JSON line is
the status {state present|built|reused, fingerprint, dir, config, rootfsMiB, ...}; a build that exits
non-zero is an error unless the state is present or reused. Ensured at setup and lazily on first
provision, then cached; the fingerprint is the image dir and is reported as imageFingerprint. Logged
node_image_ready / node_image_status.
go_side:
meets: yes
detail: >-
Today cmd/socialweb-nodeimage/ensure.go:96 (Ensure) and internal/nodefirecracker/manifest.go:40
(RecordedFingerprint). Superseded: internal/guestimage fetches, verifies and stores images keyed by
(hypervisor, arch, sha256) from versions.json pins.
parity_test:
- internal/guestimage TestAnImageWhoseShaDiffersIsRefused
- internal/guestimage TestAnImageIsFetchedOnceAndReusedByHash
status: superseded-by-M1-GUEST-IMAGE
covers: [node_image_ready]
- id: FC-IMAGE-REUSE-STALE
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:54
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:598-608
behaviour: >-
reuseStale lets a bidder boot an earlier image whose fingerprint differs from what the inputs name,
with a warning node_image_reused {askedFor, using}.
go_side:
meets: yes
detail: >-
cmd/socialweb-nodeimage -reuse-stale today. Superseded: a pinned sha256 mismatch is refused; there
is no stale reuse.
parity_test:
- internal/guestimage TestAnImageWhoseShaDiffersIsRefused
status: superseded-by-M1-GUEST-IMAGE
covers: [node_image_reused]
- id: FC-IMAGE-PROVENANCE
source:
- ts/hono-compute-provider/lib/node-image-firecracker/mod.ts:73-109
behaviour: >-
The image is built on the bidder from that host's own kernel and module tree by socialweb-nodeimage
(root, chroot, apt, a go toolchain), so two bidders boot different kernels.
go_side:
meets: no
detail: >-
Decided 2026-10-11: images are built by scripts/build-guest-image.sh on a build host per hypervisor x
arch, pinned by sha256, shipped as assets; bidders need no root, chroot, apt or go.
parity_test:
- build-pipeline TestTheGuestKernelConfigHasTheGracefulStopAndVirtioMmioDrivers
- build-pipeline TestTheRootfsCarriesNoSshHostKeyAndEnablesGrowpart
status: superseded-by-M1-GUEST-IMAGE
- id: FC-IMAGE-ROOTFS-SIZE
source:
- ts/hono-compute-provider/lib/node-image-firecracker/mod.ts:40-49
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:572
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:600
behaviour: >-
ensure must report a positive rootfsMiB: a provider compares the contract's disk with it, and a
template larger than the disk cannot be shrunk. The provider records it but does not yet use it.
go_side:
meets: yes
detail: >-
M2-BACKPORT: The controller logs the image rootfs size beside the contract's disk at prepare;
guestdisk.GrowTo never shrinks the clone below it.
parity_test:
- TestParityAContractDiskBelowTheImageNeverShrinksTheRootfs
status: port
- id: FC-DISK-FROM-CONTRACT
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:613-615
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:675
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:685
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:22
behaviour: >-
The contract's disk is parsed like mem and passed as diskMib whatever the number; a spelling nothing
parses leaves the guest at the image's own size.
go_side:
meets: yes
detail: >-
M2-BACKPORT: spec.vm.disk is parsed like mem (internal/computevm ParseMiB) and the clone is truncated up
to it; a spelling nothing parses keeps the image's own size.
parity_test:
- TestParityTheVMSpecDiskEqualsTheContract
- ts/hono-compute-provider/test/disk_semantics_test.ts::"a contract that asks for a bigger disk boots a guest grown to it"
- internal/vmruntime TestTheSeedIsASeparateCidataDriveAndTheRootfsIsNotEdited
status: port
- id: FC-MEM-AND-VCPU
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:683-684
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:868-883
behaviour: >-
mem matches /^\s*(\d+)\s*([KMGT])?i?B?\s*$/i: no unit is MiB, K rounds to at least 1 MiB, G x 1024,
T x 1024 x 1024; anything else leaves the image default. vcpu is passed only when it is a positive
number.
go_side:
meets: yes
detail: >-
M2-BACKPORT: internal/computevm ParseMiB parses spec.vm.mem by the same rule; cpus is used only when
positive; anything else leaves the image default (compute-provider-kcp writes 0 and an empty string when
the RFP names none).
parity_test:
- TestParityMemAndVcpuParseLikeTheProvider
- ts/hono-compute-provider/test/firecracker_network_test.ts::"the memory an RFP asks for is read in the units the lexicon writes it in"
status: port
covers: [parseMemMiB]
- id: FC-ISSUER-DROPLET-VIEW
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:608-614
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:710-745
behaviour: >-
The issuer's droplet for a guest this process holds is {id, tags [oidc-sub:plc:<plc>,
oidc-sub:role:<role>]}; /v1/oidc/prove builds the subject actx:<actx>:plc:<plc>:role:<role> from the
three-part oidc-sub tags and issues a token naming droplet_id. An unknown id is undefined and the
exchange is refused. containerName and networks went with the host-side key scan (FC-HOSTKEY-SCAN,
0007 M4-HOST-KEYS).
go_side:
meets: yes
detail: >-
M2-BACKPORT: compute-provider-kcp getDroplet reads {id, oidc-sub tags} from the ComputeVM (dropletOf);
host keys come from the guest's report into status.market.
parity_test:
- TestParityTheIssuersDropletViewEqualsTheProviders
- ts/hono-compute-provider/test/oidc_hostkeys_test.ts::"a firecracker guest's proven host keys reach the bidder under its provider id; pasta forwards no inbound port"
status: port
covers: [createFirecrackerComputeProvider]
- id: FC-HOSTKEY-SCAN
source:
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts@964f1fd44fef:106-152
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts@964f1fd44fef:576-599
behaviour: >-
provisioningValidate learned the guest's ed25519 host key by ssh-keyscan, through `container exec` into
the runner container when the droplet named one, retrying 300 s, and checked the guest's prove-sshd
signature over its provisioning token against it.
go_side:
meets: not-applicable
detail: >-
Deleted, not ported. Removed from the TypeScript by 0007 M4-HOST-KEYS: the guest reports its host keys
with a prove-sshd signature over its provisioning token (FC-GUEST-HOSTKEYS-REPORT) and provisioningValidate
verifies the prove signature against the reported key bound to the same token (ssh-keygen -Y verify;
the old check-novalidate never compared the signer with the scanned key).
parity_test:
- ts/hono-compute-provider/test/oidc_hostkeys_test.ts::"provisioningValidate verifies against the reported key and nothing in lib execs ssh-keyscan"
status: removed
- id: FC-GUEST-HOSTKEYS-REPORT
source:
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:551-600
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:672-708
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:616-644
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:739
behaviour: >-
The enricher writes the provisioning token to a 0600 file and composes cloud-init-common's
hostKeysReporterModule (guest-hostkeys.service, ordered before provisioning-token.service): the guest
posts every /etc/ssh/ssh_host_*_key.pub with a prove-sshd signature over the token to <issuer>/v1/host-keys.
The issuer binds the ed25519 key to the token's nonce only when the signature verifies with it (403
otherwise; a different key for the same nonce 409), then the provider maps the nonce to the guest it
provisioned and hands {id, keys} to the bidder (ComputeProvider.onHostKeys), which publishes
vm.hostKeys; events guest_hostkeys_forwarded, guest_hostkeys_unknown_guest (404),
guest_hostkeys_no_listener (503).
go_side:
meets: no
detail: >-
Planned with M4-ONNETWORK / M5-BIDDER-COMPONENTS: the guest-facing DenoPod serves /v1/host-keys beside
/v1/on-network and the ComputeVM's nonce maps the report to its receipt; the seed carries the reporter.
parity_test:
- ts/hono-compute-provider/test/oidc_hostkeys_test.ts
- ts/atproto-market/test/cloud_init_hostkeys_test.ts
- ts/atproto-market/test/vm_hostkeys_bidder_test.ts
status: port
covers: [guest_hostkeys_forwarded, guest_hostkeys_unknown_guest, guest_hostkeys_no_listener]
- id: FC-PROVISIONING-EXCHANGE
source:
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:426-575
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:680-714
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:602-611
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:652-654
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:695
behaviour: >-
The enricher mints a 15-minute provisioning token (sub actx:<team>:role:provisioning:nonce:<n>) and
composes provisioning-token.sh/.service: sign the token with the guest's ed25519 host key (namespace
prove-sshd), POST it to <issuer>/v1/oidc/prove, write token, team_uuid and base_url under
SECRETS_PREFIX; root ssh dir 0700; key-only root login. The nonce is bound to the guest name only after
boot succeeded and is single use.
go_side:
meets: not-applicable
detail: >-
Stays TypeScript (the issuer moves to the bidder's guest-facing DenoPod after M4-BIDDER-VAULT);
carried in the seed bytes. The DigitalOcean /etc/shadow edit is harmless on firecracker.
parity_test:
- ts/hono-compute-provider/test/oidc_workload_identity_integration_test.ts
- TestParityTheSeedUserDataEqualsTheProvidersByteForByte
status: port
- id: FC-IN-MEMORY-STATE
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:566-570
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts:65-78
behaviour: >-
The guests map, the rbac refs, the watches, the address index and the issuer's nonce store live in
process memory: a bidder restart forgets every running guest (no watch, no droplet view, no prove), and
only destroy-by-name still finds the work dir.
go_side:
meets: no
detail: >-
Re-population from ComputeVM plus live VMM state by the tri-state Verdict (M2-CONTROLLER); nothing a
restart needs lives only in memory.
parity_test:
- internal/computevm TestAKcpRestartStopsNoVMAndEveryVMIsReadoptedAfter
- internal/computevm TestACoreRestartUnderTheProcBackendAdoptsEveryVMUnit
status: superseded-by-M2-CONTROLLER
- id: FC-OIDC-ISSUER-MOUNT
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:904-927
behaviour: >-
The provider mounts the OIDC issuer its own guests are told to call on its own serve when the relay
connects (serviceUrl from ingressRef); without it /v1/oidc/prove answers 404, no accept bundle secrets
are fetched and the guest reads as one that never joined.
go_side:
meets: not-applicable
detail: >-
Stays TypeScript; decided 2026-10-12 the bidder's guest-facing endpoints (OIDC issuer, /v1/on-network)
split into their own DenoPods after M4-BIDDER-VAULT.
parity_test:
- ts/hono-compute-provider/test/compute_provider_kcp_test.ts::"the issuer and the on-network route are mounted on the provider's serve"
status: port
covers: ["firecracker oidc issuer mounted"]
- id: FC-ONNETWORK-ROUTE
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:32-45
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:807-863
behaviour: >-
POST /v1/on-network: an OIDC bearer the issuer validates; acceptUri and acceptCid required (400); the
accept-to-contract map keyed `<acceptUri>#<acceptCid>` must know it (404 UnknownAccept); a vm.onNetwork
record {address, createdAt} is created and wrapped in a signed market.event {receipt, payload} that is
submitted to the requester's submitEvent when the accept named one, firehose otherwise; a submit
failure is logged and does not fail the guest.
go_side:
meets: not-applicable
detail: >-
Kept by compute-provider-kcp, which also applies status.market {onNetworkUri, address, reportedAt}
(M4-ONNETWORK). As built in Go (plan 0034): GuestControlPlane POST /v1/events {acceptUri, acceptCid,
record} replaces /v1/on-network; record.$type is vm.onNetwork (with kind), guest.publicKey or
guest.signalWebRTC.
parity_test:
- ts/hono-compute-provider/test/compute_provider_kcp_onnetwork_test.ts
status: port
covers:
- ON_NETWORK_NSID
- EVENT_NSID
- SUBMIT_EVENT_NSID
- "guest.onNetwork: unknown accept ref"
- "guest.onNetwork submitEvent failed"
- "guest.onNetwork recorded with event"
- "guest.onNetwork recorded (no event wrapper)"
- "firecracker guest event routes mounted"
- id: FC-RBAC-RECORDS
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:70-82
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:714-724
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:749-755
behaviour: >-
After a boot, an rbac record for the guest's role and requester is created when a provisioner is
configured; its ref is kept per guest and the record is deleted on destroy and on the guest's own
exit, a failed delete swallowed.
go_side:
meets: yes
detail: >-
M2-BACKPORT: compute-provider-kcp creates the rbac record after Running and deletes it on destroy and
when the guest is gone.
parity_test:
- TestParityTheRbacRecordIsCreatedOnProvisionAndDeletedOnRelease
status: port
- id: FC-PROVISION-RESULT
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:673
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:726-745
behaviour: >-
provision returns providerId = the name and metadata {name, ip, mode firecracker, sshReady true,
vmmPid, console, imageFingerprint}, logging provisioning microvm and microvm provisioned. sshReady is
asserted, not measured: readiness is the guest's on-network report.
go_side:
meets: yes
detail: >-
M2-BACKPORT: compute-provider-kcp returns {name, ip, mode kcp, sshReady true, vmmPid, console,
imageFingerprint} (plus hostAddress, imageRef, imageSha256) from ComputeVM status.
parity_test:
- TestParityTheProvisionResultMetadataEqualsTheProviders
status: port
covers: ["provisioning microvm", "microvm provisioned"]
- id: FC-BOOT-RESULT-JSON
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:28-38
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:132-163
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:262-275
behaviour: >-
Boot is complete when result.json appears in the work dir with non-empty name, guest_ip, socket,
console, work_dir and positive vmm_pid, pasta_pid (fingerprint optional); polled every 300 ms; logged
microvm_booted.
go_side:
meets: yes
detail: >-
nodeboot writes result.json today (cmd/socialweb-nodeboot/main.go:356-385). Superseded: there is no
resident writer; Start records RuntimeRef {backend, unit, InvocationID, pid, startTime, hostBootID,
vmmID} and Running is firecracker GET / {id == vmmID, state Running}.
parity_test:
- internal/vmruntime TestStartRecordsTheRuntimeRefAndPollsGetRootForRunning
status: superseded-by-M2-VM-RUNTIME
covers: [microvm_booted]
- id: FC-BOOT-TIMEOUT
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:77
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:276-295
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:689-694
behaviour: >-
A boot is bounded (180 s default): a runner that exits before reporting, a runner that vanished, or the
deadline each fail the boot with the runner's last output, and the provider then stops the guest and
removes its work dir before rethrowing (microvm_stop_failed when that fails).
go_side:
meets: yes
detail: >-
M2-BACKPORT: The boot is bounded (vmruntime Await, firecracker GET / Running) and the TypeScript side
bounds the whole ComputeVM at 300 s; a failed boot is Failed with the VMM log and console tail, its unit
stopped and its work dir removed before the status is written.
parity_test:
- internal/vmruntime TestCleanupRemovesTheWorkDirAndSocketForEveryTerminalOutcome
status: port
covers: [microvm_stop_failed]
- id: FC-WORKDIR-TWO-WRITERS
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:210-222
behaviour: >-
The work dir is written by the bidder (spec, result read) and by the runner as another uid (rootfs
copy, seed, result), so it is chmod 0777.
go_side:
meets: no
detail: >-
Must not be inherited: the work dir is 0700 and one uid; the VMM's slot uid gets POSIX ACL entries on
exactly its own files (M2-VM-RUNTIME).
parity_test:
- internal/vmruntime TestPrepareGrantsTheSlotUidItsOwnWorkFilesByACLAndNothingElse
- internal/vmruntime TestTheVMMUidOwnsNoBidderFile
status: superseded-by-M2-VM-RUNTIME
- id: FC-RUNNER-CONTAINER
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:165-180
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:224-260
behaviour: >-
Each guest boots inside a privileged docker container (pasta sandboxes itself and no capability subset
sufficed) holding /dev/kvm and /dev/net/tun, the image dir mounted read-only and the work dir mounted
read-write at the same paths.
go_side:
meets: no
detail: >-
Decided 2026-10-07/11: no docker; one transient unit per VM whose tree is pasta -> firecracker in a
per-VM subuid user namespace, /dev/kvm by the kvm group (M2-VM-RUNTIME, M0-VM-USERNS).
parity_test:
- internal/vmruntime TestTheVMUnitsTreeIsPastaAndTheStandInOnly
- internal/vmruntime TestTwoVMUnitsMapDisjointSubRanges
- ts/hono-compute-provider/test/microvm_work_dir_test.ts::"container labels parse from key=value pairs and refuse anything else"
status: superseded-by-M2-VM-RUNTIME
covers: [createFirecrackerMicrovm, parseLabels]
- id: FC-SEED-TRANSPORT
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:649
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:671
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:106-112
behaviour: >-
user_data is a file in the work dir named by boot-spec.json; the runner (nodeboot) writes it into the
rootfs copy as a NoCloud seed with debugfs.
go_side:
meets: no
detail: >-
Today cmd/socialweb-nodeboot/main.go:516-580 (writeSeed, debugfsRun). Decided 2026-10-12: a separate
pure-Go NoCloud cidata drive; the rootfs is not edited.
parity_test:
- internal/vmruntime TestTheSeedIsASeparateCidataDriveAndTheRootfsIsNotEdited
- internal/vmruntime TestPrepareWritesASeedDriveAndFcJsonAndNoHostToolIsExecd
status: superseded-by-M2-VM-RUNTIME
- id: FC-CONSOLE
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:34
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:193-197
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:766-771
behaviour: >-
The console path is reported in the result; on exit the runner container's last log lines (tail 60,
4000 chars, 2000 logged) go into the bidder's log with microvm_exited, so tenant console bytes reach the
host's logs.
go_side:
meets: no
detail: >-
Decided 2026-10-11: the console is a capped file in the work dir (StandardOutput=append:<work>/console.log),
rotated by the controller, deleted with the work dir; tenant data never enters the host journal.
parity_test:
- internal/vmruntime TestTheConsoleFileIsCappedByRotation
status: superseded-by-M2-VM-RUNTIME
- id: FC-GRACEFUL-STOP
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:303-318
behaviour: >-
Stop is kill + rm of the runner container (SIGKILL): the guest is never asked to shut down.
go_side:
meets: no
detail: >-
Decided 2026-10-11: SendCtrlAltDel over the API socket, a measured grace (0.21 s on an idle guest,
E8), then the unit stops with KillSignal=SIGKILL; aarch64 goes straight to SIGKILL.
parity_test:
- internal/vmruntime TestStopSendsCtrlAltDelThenWaitsTheGraceThenStopsTheUnit
- internal/vmruntime TestStopOnAarch64GoesStraightToStopUnit
status: superseded-by-M2-VM-RUNTIME
- id: FC-GUEST-DEATH-WATCH
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:40-45
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:181-191
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:331-355
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:705-712
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:761-789
behaviour: >-
Live E8 defect a (hat-8, fixed by hono-compute-provider 96147f0): a guest that powered off was never
noticed. Now each guest's runner is polled every 5 s; when it exited or was removed the provider drops
the guest, releases its rbac record, stops it (removing the work dir) and fires GuestGone {id, reason,
exitCode} to every listener, a failing listener isolated (microvm_exited, microvm_exit_handling_failed,
guest_gone_listener_failed). A destroy cancels the watch and never reports.
go_side:
meets: yes
detail: >-
M2-BACKPORT: Not inherited: the VMM is pasta's only child, the controller consumes the unit watch and
every Lost verdict reaches compute-provider-kcp's onGuestGone (vm.terminated); a guest that powers off
resets through the system-shutdown hook compute-provider-kcp adds, so firecracker exits.
parity_test:
- internal/vmruntime TestAVMMThatExitsOnItsOwnEndsItsUnitAndLeavesNoProcess
- internal/computevm TestAVMMExitObservedByWatchMakesTheComputeVMLostWithinOneEvent
- ts/hono-compute-provider/test/firecracker_guest_lifecycle_test.ts::"a guest that dies on its own is reported gone, released and cleaned up"
status: port
covers: [microvm_exited, microvm_exit_handling_failed, guest_gone_listener_failed]
- id: FC-WORKDIR-REMOVAL
source:
- ts/hono-compute-provider/lib/microvm-firecracker/mod.ts:303-330
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:757-759
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:791-805
behaviour: >-
Live E8 defect b (32 dirs, 63 GB on hat-8; fixed by 96147f0): work dirs were never removed. Now stop
removes the work dir only after the runner is confirmed gone (kept while it exists: removing it under a
live guest deletes the disk it runs on), logging microvm_work_dir_removed; destroy of a well-named
guest this process never booted still stops it and removes its dir, any other unknown name is logged
microvm_destroy_unknown.
go_side:
meets: yes
detail: >-
M2-BACKPORT: Not inherited: the finalizer goes only after Cleanup removed the work dir and the API
socket (checked by stat) for released, Lost and Failed VMs; orphan work dirs of this instance go after
10 minutes.
parity_test:
- internal/vmruntime TestCleanupRemovesTheWorkDirAndSocketForEveryTerminalOutcome
- internal/computevm TestTheFinalizerStaysUntilTheWorkDirIsGoneForReleasedLostAndFailed
- internal/computevm TestAWorkDirWithNoComputeVMAndNoUnitIsRemovedAfterTheGrace
- ts/hono-compute-provider/test/firecracker_guest_lifecycle_test.ts::"a work directory is kept while its container still exists"
status: port
covers: [microvm_work_dir_removed, microvm_destroy_unknown]
- id: FC-VM-TERMINATED
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:776
- ts/atproto-market/lib/market-bidder-compute/mod.ts:58-69
- ts/atproto-market/lib/market-bidder-compute/mod.ts:202-242
behaviour: >-
A GuestGone reason `runner container exited|removed` is mapped by the bidder to vm.terminated (exited
with code 0 -> guest_poweroff, else vmm_exited), published as a signed market.event to submitEvent or
the firehose, with a tombstone so a late vm.delete answers 200. Live hat-8 2026-10-12T01:44Z: 5.6 s from
guest poweroff to the requester's session end, no vm.delete sent.
go_side:
meets: yes
detail: >-
The string heuristic is replaced by explicit Lost reasons (HostRebooted -> host_reboot,
GuestPoweroff -> guest_poweroff, UnitGone/UnitFailed/VMMExited -> vmm_exited, OOMKilled -> oom,
IdentityMismatch -> identity_mismatch). GuestPoweroff is a VM whose VMM logged "Firecracker exiting
successfully. exit_code=0": the guest powered off or reset (reboot=k, the i8042 reset), and
firecracker exited by itself. The unit status cannot tell it apart: the unit watch reads a VMM
killed by SIGKILL and a clean exit alike as inactive, result success, code 0 status 0.
parity_test:
- internal/computevm TestEveryLostVerdictCarriesTheTerminatedReason
- ts/hono-compute-provider/test/compute_provider_kcp_test.ts::"a ComputeVM going Lost fires onGuestGone with its reason"
status: superseded-by-M4-TERMINATION-EVENT
- id: FC-OAUTH-SCOPE-NEW-COLLECTIONS
source:
- ts/typescript-helpers/lib/oauth-scope/mod.ts:33-34
- ts/typescript-helpers/lib/oauth-scope/mod.ts:139-150
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:833-847
behaviour: >-
Live hat-8 2026-10-12T01:32:39Z: the bidder's vm.terminated publish failed with 403 ScopeMissingError
because the collection was not in BIDDER_OAUTH_SCOPE. Every collection the bidder writes (onNetwork,
market.event, wif.simple, terminated, and next vm.hostKeys) needs the role-set scope
(typescript-helpers 5b071fe), the regenerated QR client scope deployed (did-key-associator 3cde452) and
a re-sign-in; a token refresh keeps the old scopes.
go_side:
meets: not-applicable
detail: >-
Any record the Go-backed provider adds (vm.hostKeys first) follows the new-NSID checklist before a
live run.
parity_test:
- ts/atproto-market/test/role_scope_coverage_test.ts
- ts/did-key-associator/test/oauth_scope_drift_test.ts
status: superseded-by-M1-PROTOCOL-CHECKLIST
- id: FC-JSR-REGISTRY
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts@1fd0c5234b55:614-629
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts@1fd0c5234b55:710
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts@1fd0c5234b55:719
- ts/hono-compute-provider/lib/compute-provider-local/mod.ts@1fd0c5234b55:614-632
- ts/hono-compute-provider/lib/compute-provider-digitalocean/mod.ts@1fd0c5234b55:151-162
- ts/atproto-market/lib/common/cloud-init-common/mod.ts@d5b75305c3ba:1257-1263
behaviour: >-
The provider serves the workspace's unpublished packages from a host JSR registry on TCP port 0
(0.0.0.0) and points the tunnel subscriber at it with JSR_URL, because jsr.io answers 404 for them.
Only the tunnel transport fetches packages at boot.
go_side:
meets: not-applicable
detail: Removed, not ported (non-iroh guest transports stripped; the guest JSR registry goes with them).
parity_test:
- TestParityTheSeedNamesNoJsrUrlAndNoTunnelSubscriber
- ts/hono-compute-provider/test/no_guest_jsr_registry_test.ts::"no guest JSR registry is served and no user_data names JSR_URL"
status: removed
covers: ["jsr registry mounted on TCP"]
- id: FC-LEGACY-TUNNEL-MODULE
source:
- ts/atproto-market/lib/common/cloud-init-common/mod.ts@d5b75305c3ba:370-433
- ts/atproto-market/lib/common/cloud-init-common/mod.ts@d5b75305c3ba:1249-1255
- ts/atproto-market/lib/market-bidder-compute/mod.ts@d5b75305c3ba:85-117
behaviour: >-
The tunnel module runs the deno tunnel subscriber that dials the relay dispatcher
(--ingress-proxy-host) and writes the dispatcher FQDN to /run/guest-fqdn; guestOnNetworkUrl derives the
report URL's port from that flag.
go_side:
meets: not-applicable
detail: Removed, not ported.
parity_test:
- TestParityTheSeedNamesNoJsrUrlAndNoTunnelSubscriber
- ts/atproto-market/test/no_legacy_guest_transport_test.ts::"the user_data registry holds no tunnel, fedproxy-ssh, fedproxy-web or web-terminal module"
- ts/atproto-market/test/market_bidder_guest_onnetwork_url_test.ts::"a guest reports to the relay's own /v1/on-network"
status: removed
- id: FC-LEGACY-FEDPROXY-SSH
source:
- ts/atproto-market/lib/common/cloud-init-common/mod.ts@d5b75305c3ba:441-590
- ts/atproto-market/lib/common/cloud-init-common/mod.ts@d5b75305c3ba:1238-1247
behaviour: The fedproxy-ssh module (fedproxy client SSH transport through the relay).
go_side:
meets: not-applicable
detail: Removed, not ported.
parity_test:
- ts/atproto-market/test/cloud_init_snapshot_test.ts::"the registry holds only iroh, secrets and k3s"
status: removed
- id: FC-LEGACY-FEDPROXY-WEB
source:
- ts/atproto-market/lib/common/cloud-init-common/mod.ts@d5b75305c3ba:593-647
behaviour: The fedproxy-web module (fedproxy client web ingress for a guest port).
go_side:
meets: not-applicable
detail: Removed, not ported.
parity_test:
- ts/atproto-market/test/cloud_init_snapshot_test.ts::"the registry holds only iroh, secrets and k3s"
status: removed
- id: FC-LEGACY-WEB-TERMINAL
source:
- ts/atproto-market/lib/common/cloud-init-common/mod.ts@d5b75305c3ba:649-844
behaviour: The browser web-terminal module (a web terminal reached through fedproxy).
go_side:
meets: not-applicable
detail: Removed, not ported.
parity_test:
- ts/atproto-market/test/cloud_init_snapshot_test.ts::"the registry holds only iroh, secrets and k3s"
status: removed
- id: FC-LEGACY-WEBSOCAT
source:
- ts/atproto-market/lib/requester-xrpc/mod.ts@d5b75305c3ba:602-631
- ts/atproto-market/lib/requester-xrpc/mod.ts@d5b75305c3ba:868-912
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts@1fd0c5234b55:327
behaviour: >-
The requester reaches a relay-FQDN guest with ssh ProxyCommand `websocat --binary wss://<fqdn>/`, and
the provisioning script kicks setup-websocat.service after its token exchange.
go_side:
meets: not-applicable
detail: Removed, not ported; the requester's ssh path is iroh only, with known_hosts from vm.hostKeys (M4-HOST-KEYS).
parity_test:
- ts/atproto-market/test/vm_hostkeys_requester_test.ts
- TestParityTheSeedNamesNoJsrUrlAndNoTunnelSubscriber
- ts/atproto-market/test/no_legacy_guest_transport_test.ts::"the ssh ProxyCommand for a non-iroh address is refused instead of a websocket bridge"
status: removed
- id: FC-LEGACY-RELAY-FQDN-ADDRESS
source:
- ts/atproto-market/lib/abc/compute-request/mod.ts@d5b75305c3ba:264-270
- ts/atproto-market/lib/abc/compute-request/mod.ts:269-275
- ts/atproto-market/lib/compute-request-xrpc/mod.ts:410-413
behaviour: >-
A guest address that is not an iroh ticket or an IP is taken as a relay FQDN the requester polls over
wss; a single-label name is a hostname and skipped.
go_side:
meets: not-applicable
detail: Removed, not ported; the only reportable guest address is iroh://<ticket>, and a dotted name is refused (guestAddressKind "refused").
parity_test:
- ts/atproto-market/test/no_legacy_guest_transport_test.ts::"a guest address that is a relay name is refused, only an iroh ticket is a guest address"
status: removed
- id: FC-LEGACY-REPORTER-TUNNEL-ORDERING
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts@1fd0c5234b55:296-297
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts@1fd0c5234b55:316-318
- ts/hono-compute-provider/lib/oidc-issuer-hono/mod.ts@1fd0c5234b55:389-390
behaviour: >-
The reporters are ordered After= and Wants= tunnel-subscriber.service and dump its journal on giving
up.
go_side:
meets: not-applicable
detail: Removed, not ported; the reporter orders on iroh.service only (FC-IROH-LISTENER-ORDERING).
parity_test:
- TestParityTheSeedNamesNoJsrUrlAndNoTunnelSubscriber
- ts/hono-compute-provider/test/no_guest_jsr_registry_test.ts::"the guest's on-network reporter waits on the iroh listener, never a tunnel subscriber"
status: removed
- id: FC-LEGACY-PASTA-SSH-FORWARD
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts@964f1fd44fef:111-113
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts@964f1fd44fef:737
behaviour: >-
pasta was told to forward 0.0.0.0/22 in the runner's namespace to the guest's sshd, for the host-side
keyscan and direct TCP probes.
go_side:
meets: not-applicable
detail: >-
Removed, not ported: a guest is reached only over its own iroh endpoint (outbound dials, no inbound
port) and host keys are guest-reported; pasta gets no -t forward. Removed from the TypeScript by 0007
M4-HOST-KEYS together with the host-side key scan it served (FC-HOSTKEY-SCAN); the OIDC token exchange
proves the guest's host key through the reported key (FC-GUEST-HOSTKEYS-REPORT).
parity_test:
- internal/vmruntime TestTheVMUnitSpecPastaHasNoInboundForward
- ts/hono-compute-provider/test/oidc_hostkeys_test.ts::"a firecracker guest's proven host keys reach the bidder under its provider id; pasta forwards no inbound port"
status: removed
- id: FC-ADOPT-AFTER-RESTART
source:
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:131
- ts/hono-compute-provider/lib/compute-provider-firecracker/mod.ts:808-840
behaviour: >-
After a bidder restart the provider adopts each guest its ContractStore names instead of booting it
again: it reads the guest.json the provision wrote (with the host boot id), re-watches a runner that is
still up and serves it to the OIDC issuer again; a guest whose runner is gone is reported gone
(vmm_exited, or host_reboot when the boot id changed) so the bidder emits vm.terminated. Added by
0007 M4-CONTRACT-STORE-FILE (hono-compute-provider ac3a1f5) after live restarts leaked guests.
go_side:
meets: partial
detail: >-
The ComputeVM controller re-adopts from ComputeVM objects plus live unit identity (Running|Lost|Unknown)
and compares the recorded boot id; the TypeScript store and guest.json are replaced by ComputeVM status.
parity_test:
- internal/computevm TestARunningComputeVMIsAdoptedAfterARestartNotBootedAgain
- internal/computevm TestABootIDChangeMarksEveryComputeVMLostAsHostReboot
status: superseded-by-M2-CONTROLLER
covers: [readHostBootId, microvm_adopt_unknown, microvm_adopted, microvm_gone_at_adopt]