docs(design): tier-2 forge e2e leg, agent to server (RIG-3823) - #1276
Draft
rigel-mintaka wants to merge 1 commit into
Draft
rigel-mintaka wants to merge 1 commit into
rigel-mintaka wants to merge 1 commit into
Conversation
The forge chain is tested at every seam and assembled nowhere: the TS tool against FakeTransport, the gateway against fakeForgeRelay, the server arm against forge.FakeProvider, and the provider against the real API. A mis-plumbed oneof arm or a field dropped between the TS tool and proto is invisible today, and `grep -Ric forge go/e2e/` returns zero files. RIG-3331 T7 found that class one layer down: workflowStatesQuery declared $team as String! against an ID position, so the first hop of TransitionIssueState 400d and the whole Linear transition path was dead in production, green in every test above it. Tier 2 stops at the provider boundary, so it needs no forge credentials and adds no egress: a loopback HTTPS GitHub-shaped stub the real *forge.GitHub dials via the configured host, with throwaway per-run RSA keys for the App mint. Four open questions are parked for Matt, including Linear, which needs a production config seam first. Co-authored-by: Matt Wilkinson <matt@rigel.build>
|
Merging to
After your PR is submitted to the merge queue, this comment will be automatically updated with its status. If the PR fails, failure details will also be posted here |
|
Compass engineering docs preview: https://compass-forge-rig-3823-e2e-d.compass-eng-docs.pages.dev Deployed from Changed pages: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The design record for RIG-3823: a tier-2 e2e leg proving an agent's forge tool call traverses agent → server with its payload intact. Record only — no implementation.
Why
The forge chain is tested at every seam and assembled nowhere. Every layer is verified against a fake of its neighbour:
forge.test.tsFakeTransportgateway/forge_test.gofakeForgeRelayforgeService)forge_transition_test.go(17 tests)forge.FakeProvider+fakeForgeStorelivegithub_test.go(RIG-3331 T7)grep -Ric 'forge' go/e2e/returns zero files — control-verified (the same matcher findsfunc Testinharness_test.go; re-checked after #1258 landed). So a mis-plumbedForgeCallRequestoneof arm or a field dropped between the TS tool and proto is invisible today.Not hypothetical: RIG-3331 T7 found
workflowStatesQuerydeclaring$team: String!against anIDposition, 400ing the first hop ofTransitionIssueState. The whole Linear transition path was dead in production, green in every test above it. Golden replay cannot catch that class — a fixture answers our request and prelude entries pin response bodies, never query text, which is DL-210's stated reason for two tiers.The tiering (Matt's ruling)
Two tiers, not three. Tier 1 (provider ↔ real API) is done. Tier 2 is this record, and it stops at the provider boundary — so it needs no forge credentials and adds no egress, which is what made it feasible at all.
Load-bearing decisions
forge.FakeProvider. The server is a child process here, so the pgtesthub.SetForgeCallerseam is unreachable and config is the only injectable one. More importantly, the bug class this exists for lives in the bytes the real provider client emits — injecting a fake would reintroduce the blind spot at the exact layer the$teambug lived in.PrivateKeyaccepts any PKCS#1/chore: exclude vendored fork subtrees from secret scanning #8 PEM, so the fixture generates one per run (astestAppPEMalready does); secrets ride the dotenv provider; mint is lazy and no boot path touches the forge withCOMPASS_FORGE_REPOSunset, making the stub's request log a complete ledger. This was the main feasibility risk and it is resolved from code, not asserted.A production bug found while grounding this
RIG-3870, filed separately and verified hop-by-hop:
buildForgeWriteServiceregisters the Linear coordinate with an empty host,registermakes that empty string the provider'sdefaultHost(so the A3 fallback cannot rescue it), andrecordpasses it toRecordAuthoredArtifact, whosevalidCoordinaterejectshost == "". A Linearforge_create_issuecreates the issue on Linear and then fails, leaving no DL-055 row and no F3 memo — so a retry authors a second issue. No test covers it: the only Linear call through that registry is the PR-unsupported case, which returns beforerecord(). Out of scope here; tracked there.Open questions for you
buildLinearTokenSourcehardcodes the token URL and mints at boot, failingServe. Either expose an endpoint override as its own issue then add a Linear leg, or leave Linear on tier 1 + golden. I lean the former.SSL_CERT_FILE(recommended, zero production surface) vs a--forge-caserver flag.t.Setenvin the fixture option (recommended) vs aServerEnvfield onstack.Config.Verification
rumdl checkclean. Every cited symbol verified present onorigin/main(appAPIBaseand theaccess_tokensmint path,testAppPEM,certgen.Generate,WithCannedScript,NewFixture,remainingHeader's -1 no-signal return). Zeropath:linecitations, per the house convention. Rebased ontof8b22385.Ledger-impact: none — T4 proposes a row in the record for the driver to rule on rather than editing
DECISIONS.md.