68 lines
4.4 KiB
Markdown
68 lines
4.4 KiB
Markdown
# 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 |
|