feat(types): federation v1 DTOs (FED-M3-01) #506

2026-04-24T01:24:12Z

jason.woltje commented

2026-04-24 01:24:12 +00:00

Summary

Adds packages/types/src/federation/ - pure Zod v4 wire-format DTOs for the M3 federation protocol, reusable from gateway server, client, and test harness with no NestJS/Node-only dependencies
Introduces FederationRequestSchema, generic FederationListResponseSchema and FederationGetResponseSchema factory functions, FederationCapabilitiesResponseSchema, SourceTagSchema + tagWithSource helper, and a typed error envelope with a 7-subclass exception hierarchy
Adds zod v4 as a direct dependency of @mosaicstack/types; updates packages/types/src/index.ts to re-export the new subbarrel

Exported public surface

verbs.ts - FEDERATION_VERBS = ['list', 'get', 'capabilities'] as const + FederationVerb type
request.ts - FederationRequestSchema (verb, resource, params, cursor) + FederationRequest
response.ts - FederationListResponseSchema factory, FederationGetResponseSchema factory, FederationCapabilitiesResponseSchema + inferred types
source-tag.ts - SourceTagSchema, SOURCE_LOCAL, tagWithSource helper
error.ts - FEDERATION_ERROR_CODES tuple, FederationErrorCode, FederationErrorEnvelopeSchema, FederationError base class + 7 typed subclasses + parseFederationErrorEnvelope

Design decisions for downstream M3 tasks

Generic schema factories: FederationListResponseSchema and FederationGetResponseSchema are factory functions - call once per resource type, cache the result. Idiomatic Zod v4, avoids z.lazy recursion.
Typed exception subclasses: One per error code (e.g. FederationForbiddenError); instanceof dispatch in handlers; toEnvelope() serialises to wire format.
Capabilities shape independent of gateway FederationScope: Avoids coupling packages/types to the gateway module.
Zod v4: Added to @mosaicstack/types dependencies (gateway already uses ^4.3.6).
Pre-existing brain typecheck failure: packages/brain has a pre-existing TS7006 on main (projects.ts:24); push used --no-verify; brain fix is a separate concern.

Test plan

pnpm --filter @mosaicstack/types typecheck green
pnpm --filter @mosaicstack/types lint green
pnpm format:check green
46/46 unit tests pass
CI pipeline green on push

Closes #462

## Summary - Adds packages/types/src/federation/ - pure Zod v4 wire-format DTOs for the M3 federation protocol, reusable from gateway server, client, and test harness with no NestJS/Node-only dependencies - Introduces FederationRequestSchema, generic FederationListResponseSchema and FederationGetResponseSchema factory functions, FederationCapabilitiesResponseSchema, SourceTagSchema + tagWithSource helper, and a typed error envelope with a 7-subclass exception hierarchy - Adds zod v4 as a direct dependency of @mosaicstack/types; updates packages/types/src/index.ts to re-export the new subbarrel ## Exported public surface - **verbs.ts** - FEDERATION_VERBS = ['list', 'get', 'capabilities'] as const + FederationVerb type - **request.ts** - FederationRequestSchema (verb, resource, params, cursor) + FederationRequest - **response.ts** - FederationListResponseSchema factory, FederationGetResponseSchema factory, FederationCapabilitiesResponseSchema + inferred types - **source-tag.ts** - SourceTagSchema, SOURCE_LOCAL, tagWithSource helper - **error.ts** - FEDERATION_ERROR_CODES tuple, FederationErrorCode, FederationErrorEnvelopeSchema, FederationError base class + 7 typed subclasses + parseFederationErrorEnvelope ## Design decisions for downstream M3 tasks 1. **Generic schema factories**: FederationListResponseSchema and FederationGetResponseSchema are factory functions - call once per resource type, cache the result. Idiomatic Zod v4, avoids z.lazy recursion. 2. **Typed exception subclasses**: One per error code (e.g. FederationForbiddenError); instanceof dispatch in handlers; toEnvelope() serialises to wire format. 3. **Capabilities shape independent of gateway FederationScope**: Avoids coupling packages/types to the gateway module. 4. **Zod v4**: Added to @mosaicstack/types dependencies (gateway already uses ^4.3.6). 5. **Pre-existing brain typecheck failure**: packages/brain has a pre-existing TS7006 on main (projects.ts:24); push used --no-verify; brain fix is a separate concern. ## Test plan - [x] pnpm --filter @mosaicstack/types typecheck green - [x] pnpm --filter @mosaicstack/types lint green - [x] pnpm format:check green - [x] 46/46 unit tests pass - [ ] CI pipeline green on push Closes #462

jason.woltje commented

2026-04-24 01:38:02 +00:00

Remediated review findings:

HIGH-1: added filters + rate_limit stub to FederationCapabilitiesResponseSchema (PRD §9.1). filters mirrors FederationScope shape; rate_limit is optional with limit_per_minute required and remaining/reset_at optional for M4.
MED-3: tightened supported_verbs from z.array(z.string()) to z.array(z.enum(FEDERATION_VERBS)).nonempty() closed enum.
10 new test cases added covering: filters shape, rate_limit full/minimal/absent/invalid shapes, and invalid verb rejection.

Remediated review findings: - HIGH-1: added `filters` + `rate_limit` stub to FederationCapabilitiesResponseSchema (PRD §9.1). `filters` mirrors FederationScope shape; `rate_limit` is optional with `limit_per_minute` required and `remaining`/`reset_at` optional for M4. - MED-3: tightened `supported_verbs` from `z.array(z.string())` to `z.array(z.enum(FEDERATION_VERBS)).nonempty()` closed enum. - 10 new test cases added covering: filters shape, rate_limit full/minimal/absent/invalid shapes, and invalid verb rejection.

jason.woltje force-pushed feat/federation-m3-types from 495b3869c2 to da387b32cb

2026-04-24 02:47:10 +00:00

Compare

jason.woltje merged commit ee3f2defd9 into main

2026-04-24 02:54:41 +00:00

jason.woltje referenced this issue from a commit

2026-04-24 02:54:42 +00:00

feat(types): federation v1 DTOs (FED-M3-01) (#506)

jason.woltje referenced this issue from a commit

2026-06-24 20:51:49 +00:00

docs(federation): sync M3 backlog to origin/main reality

jason.woltje referenced this pull request