feat(compass-agent): agent comms tools — post and list over the Runner socket

go/internal/comms/harness_test.go

@@ -12,6 +12,74 @@
 // an already-running Postgres instead of starting a container.
 //
 // Build-tagged `pgtest` so it is not part of the default `go test` gate.
+//
+// WHY BOTH DELIVERY PATHS ARE PINNED SEPARATELY. forwardComms drains
+// sub.Replay (a snapshot taken at Subscribe()) and then tails sub.Live. Both
+// carry the same event shapes, so a test asserting only that a MessagePosted
+// arrived passes identically whether live delivery works or the subscriber is
+// merely draining history. Correlating on a minted id does NOT close that gap
+// here: the ring snapshot is taken under the same lock that registers the live
+// subscriber, so a concurrently-posted message legitimately arrives by EITHER
+// path. A minted id proves the event is this test's; it does not name the
+// mechanism that carried it.
+//
+// So the discrimination was measured, not argued — each path deleted in turn,
+// against the real handler and a real Postgres:
+//
+//	kill the live tail (return before the sub.Live loop)  -> 6 red
+//	  TestCreateChannelEmitsChannelChanged
+//	  TestPostMessageWriteThrough
+//	  TestRespondToAskHappyPathEmitsMessageUpdated
+//	  TestSubscribeCommsPostDeliversMessagePosted
+//	  TestSubscribeCommsPrivateMessageLeakBlockedLiveTail
+//	  TestPostMessageIdempotentRetrySuppressesDuplicatePublish
+//
+//	force sub.Replay empty                                -> 9 red
+//	  TestForwardCommsDeliversVisibleEvent
+//	  TestForwardCommsFailsClosedOnStoreFault
+//	  TestForwardCommsSkipsNonVisibleEventAndContinues
+//	  TestSubscribeCommsPrivateMessageLeakBlocked
+//	  TestSubscribeCommsChannelChangedSharedVisibleToNonMember
+//	  TestSubscribeCommsAccountChangedDirectoryScoping
+//	  TestSubscribeCommsRemovedMemberGetsFinalChannelChanged
+//	  TestSubscribeCommsChannelGroupChangedScoping
+//	  TestPostMessageIdempotentRetrySuppressesDuplicatePublish
+//
+// Written out in full rather than as counts or a glob: a name can be checked
+// against the file, "all three" cannot. TestForwardComms* in fact matches FOUR
+// tests — TestForwardCommsCleanEndOnCancellation stays green under both
+// mutations, since it asserts a clean end rather than a delivery — so the glob
+// would have overstated the replay set by one.
+//
+// Near-disjoint, with exactly one deliberate overlap: the idempotent-retry test
+// spans both because it asserts a SET ("exactly one MessagePosted across a post
+// and its retry"), reading the first event off the live tail and then bounding
+// the total by draining the replay to a canary. Every other test names one path
+// only. Neither path can be deleted without a test noticing, and the two failure
+// sets barely intersect — that is the property, and it is what a passing suite
+// alone does not establish.
+//
+// The canary is what makes a completeness claim possible at all. mkCanary +
+// drainReplayAsActor (visibility_filter_test.go) post a globally-visible event
+// AFTER the mutation under test and drain until it arrives, bounding the
+// complete set the channel emitted. An assertion that stops at the first match
+// can observe neither an absence nor a duplicate; "exactly one" is unprovable
+// without a terminator.
+//
+// Re-run both mutations if this harness is refactored: the numbers above are a
+// measurement, and a refactor that collapses the two paths would leave them
+// silently wrong. In subscribe.go's forwardComms, one at a time:
+//
+//	live tail: insert `return nil` immediately before the `for { select {`
+//	           that reads sub.Live
+//	replay:    change `range sub.Replay` to range over an empty slice
+//
+// then `go test -tags pgtest ./internal/comms/` — the WHOLE package, never a
+// -run filter. The first attempt at this measurement used
+// -run 'TestSubscribeComms|TestPostMessage', a pattern that cannot match
+// TestCreateChannelEmitsChannelChanged or TestRespondToAskHappyPath...; it
+// reported 4 red where the truth is 6. A filter narrower than the claim is
+// structurally incapable of falsifying it.
 
 package comms
 

packages/compass-agent/package.json

@@ -13,7 +13,8 @@
 		"@connectrpc/connect-node": "^2.1.0",
 		"@oh-my-pi/pi-agent-core": "^16.4.8",
 		"@oh-my-pi/pi-ai": "^16.4.8",
-		"@oh-my-pi/pi-coding-agent": "^16.4.8"
+		"@oh-my-pi/pi-coding-agent": "^16.4.8",
+		"arktype": "2.2.3"
 	},
 	"devDependencies": {
 		"@types/bun": "catalog:",