mosaicstack/stack
1
0
Fork 0
Code Issues 18 Pull Requests 1 Actions Packages Projects Releases 13 Wiki Activity

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

Merged
jason.woltje merged 2 commits from feat/federation-m3-types into main 2026-04-24 02:54:41 +00:00
Conversation 1 Commits 2 Files Changed 10 +951 -3
jason.woltje commented 2026-04-24 01:24:12 +00:00
Owner
Copy Link

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

  • 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 added 1 commit 2026-04-24 01:24:13 +00:00
feat(types): federation v1 wire-format DTOs (FED-M3-01)
Some checks failed
ci/woodpecker/pr/ci Pipeline failed
Details
ci/woodpecker/push/ci Pipeline failed
Details
ac475d240d 
Add packages/types/src/federation/ with Zod v4 schemas and inferred TS
types for the M3 federation wire protocol. Includes verbs constant,
request schema, list/get/capabilities response factories, _source tag
helper, and typed error envelope + exception hierarchy. 46 unit tests;
typecheck, lint, and format:check all green.

Closes #462

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
jason.woltje added 1 commit 2026-04-24 01:37:39 +00:00
fix(types): capabilities response — add filters + rate_limit stub + tighten supported_verbs (review remediation)
Some checks are pending
ci/woodpecker/push/ci Pipeline is running
Details
ci/woodpecker/pr/ci Pipeline is running
Details
495b3869c2 
- HIGH-1: add `filters` field (mirrors FederationScope PRD §8.1) and `rate_limit` stub (PRD §9.1) to FederationCapabilitiesResponseSchema; M4 populates remaining/reset_at
- MED-3: tighten supported_verbs from z.array(z.string()) to z.array(z.enum(FEDERATION_VERBS)) closed enum
- Add 10 new test cases covering filters shape, rate_limit full/minimal/absent/invalid, and invalid verb rejection

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
jason.woltje commented 2026-04-24 01:38:02 +00:00
Author
Owner
Copy Link

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
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
jason.woltje
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#506
Delete Branch "feat/federation-m3-types"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?