docs: correct the bridge-address mechanism AGENTS.md still describes - #76
Conversation
PR #75 swapped the helper name to sdk.host.getBridgeAddress but kept the clause describing the mechanism it replaced — resolution via sdk.getOsIp plus the binding's assigned external port. getOsIp is no longer called anywhere in startos/, and reading the assigned port is the coupling the helper exists to remove. Records why the RPC lookup passes ssl: false and the P2P one passes no discriminator, and drops 'mapped', which named an argument the deleted local helper took and getBridgeAddress does not.
MattDHill
left a comment
There was a problem hiding this comment.
Verified against current master (2574ec6). Both claims hold: getOsIp appears nowhere under startos/, and the RPC/P2P ssl: asymmetry is correct — bitcoind binds RPC protocol: 'http' (secure: null + generated addSsl), so BindInfo::new allocates both ports and the bridge publishes a plaintext and a TLS leg; P2P is secure: {ssl:false}, one leg. Dropping the SDK docstring's "only one of those is ever populated" is the right call — that overstatement is false for an http binding and should be fixed at the source in start-sdk.
No republish, confirmed rather than assumed: 0.11.1:13 is now on community-prod at git hash 2574ec6, so the Check production registry step returns non-empty and sets skip=true, which gates both Force-push release tag and the entire Release job. The startos/main.ts hunk rides along for free.
Why
AGENTS.mdis auto-loaded by every agent working in this repo (CLAUDE.mdis literally@AGENTS.md), so a wrong mechanism description there propagates.#75 updated the helper name to
sdk.host.getBridgeAddressbut kept the clause describing the mechanism #74 removed:Both halves are now false.
git grep getOsIp -- 'startos/**'returns nothing, and reading the assigned port is precisely the couplinggetBridgeAddressexists to remove — it resolves the binding's own derived address instead.What changed
Two lines, docs only.
AGENTS.md— describes what the code does now, and records the one genuinely non-obvious decision inbitcoindBridge: why the RPC lookup passesssl: falseand the P2P lookup passes nothing.startos/main.ts— "the mapped address" named themapcallback the deleted local helper took.getBridgeAddresshas no such parameter, so a reader following the word intoutils.tsfinds no mapping step. Now "the bridge address". Comment text only.On the
ssl:rationaleWorth stating precisely, because the SDK's own docstring is loose here and I initially inherited its looseness:
protocol: 'http', which desugars tosecure: nullplus a generatedaddSsl.BindInfo::newonly skipsassigned_portwhensecure.ssl == trueandaddSslis set, so this binding carries both ports and publishes a plaintext and a TLS bridge address side by side. The discriminator is genuinely required; an undiscriminated lookup is order-dependent.protocol: null, addSsl: null, secure: {ssl: false}, so plaintext only. Notessl: falsethere would in fact match (the filter isssl === undefined || a.ssl === ssl) — it is not that a discriminator selects nothing, it is that pinning one re-asserts bitcoind's TLS arrangement, which is the coupling being removed.So the doc no longer claims "only one of
assignedPort/assignedSslPortis ever populated" — for anhttpbinding both are, and that overstatement would send someone debugging a null address down the wrong path.Verification
npm run checkand prettier clean. No republish:tagAndRelease.ymlhaspaths-ignore: ['*.md'], andmain.ts's change is comment-only, so no version bump is warranted.