stack/docs/scratchpads/FED-M3-09-query-source.md

FED-M3-09 — Query Source Service Scratchpad

Objective

Implement apps/gateway/src/federation/client/query-source.service.ts for source: "local" | "federated:<host>" | "all" routing.

Scope

• Add QuerySourceService in gateway federation client layer.
• Unit-test local-only, single federated peer, all-source fan-out/merge, and per-peer partial failures.
• Keep docs/federation/TASKS.md read-only per project agent guidance.

Constraints / assumptions

• Issue: #462.
• Branch: feat/federation-m3-query-source from origin/main (e0e7be70).
• ASSUMPTION: federated:<host> should match active outbound peers by commonName first and by endpointUrl host/hostname as compatibility fallback; source tags use peer.commonName per @mosaicstack/types source-tag docs.
• ASSUMPTION: QuerySourceService provides list/fan-out behavior; get/source routing can be layered later because card acceptance says merge rows.
• ASSUMPTION: source: "all" cannot safely return a single continuation cursor for multiple sub-sources; any subquery cursor marks the merged response _partial: true + _truncated: true while omitting nextCursor.
• Budget: no explicit hard cap from orchestrator; working cap ~8K-12K tokens for card 1 implementation + tests + PR cycle.
• OpenBrain unavailable: credential loader failed with missing /home/jarvis/.config/mosaic/credentials.json; not blocking code delivery.

Plan

1. Review federation client/types/db patterns.
2. Write unit tests for source behavior.
3. Implement QuerySourceService and export/register it in FederationModule.
4. Run scoped tests, typecheck, lint, format.
5. Run codex uncommitted review and remediate.
6. Commit, queue guard, push, PR via wrapper.

Progress

• 2026-06-24: Intake complete; using isolated worktree to avoid dirty orchestrator files in original checkout.
• 2026-06-24: Added QuerySourceService, module export, barrel export, and 7 unit tests.
• 2026-06-24: First Codex review found pagination and port-host matching issues; both remediated with tests.

Tests run

• pnpm --filter @mosaicstack/gateway test -- query-source.service.spec.ts — PASS (7 tests).
• pnpm --filter @mosaicstack/gateway typecheck — PASS.
• pnpm --filter @mosaicstack/gateway lint — PASS.
• pnpm format:check — PASS.
• pnpm typecheck — PASS (41/41 turbo tasks).
• pnpm lint — PASS (23/23 turbo tasks).
• pnpm test — FAIL in pre-existing/live-DB integration suite: apps/gateway/src/__tests__/cross-user-isolation.test.ts cleanup hit relation "messages" does not exist against local PostgreSQL. Changed QuerySource unit tests passed; failure is outside FED-M3-09 surface and appears tied to local DB schema state.

Review evidence

• ~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted — first pass request-changes, 2 should-fix findings (all-source cursor handling; endpoint port host matching).
• Remediation: _partial + _truncated when any all-source subquery has nextCursor; endpoint match accepts URL host and hostname; added tests for both.
• ~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted — PASS/approve, no findings.
• ~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted — PASS, risk level none, no findings.

Risks / blockers

• Federation query layer is not yet wired; service API needs to be stable and easy to compose.
• Must avoid hard-failing source: all on remote peer failures.

Acceptance evidence mapping

Acceptance criterion	Evidence
local source returns local rows tagged _source: local	query-source.service.spec.ts local test; scoped test PASS
federated:<host> queries selected peer and tags rows with peer source	query-source.service.spec.ts commonName/endpoint-host tests; scoped test PASS
all fans out local + active outbound peers in parallel and merges tagged rows	query-source.service.spec.ts all-source call-order/merge test; scoped test PASS
per-peer failure on all returns _partial: true, not throw	query-source.service.spec.ts peer failure test; scoped test PASS