add-foks-error-type

name	add-foks-error-type
description	Use when adding a new error / status code to FOKS. Wires a new StatusCode through proto-src/lib/status.snowp (enum + variant Status arm), regenerates proto with `make proto`, and mirrors it as a Go error in lib/core/errors.go (type + both conversion switches). Canonical precedent: TeamAdhocCreatorIncludedError (@7101).

Add a new FOKS error type

FOKS errors are StatusCodes defined in a .snowp proto source, then mirrored as Go error types in lib/core/errors.go. Both halves must be wired for the error to round-trip over the wire. The canonical example is TeamAdhocCreatorIncludedError (TEAM_ADHOC_CREATOR_INCLUDED_ERROR @7101).

Do NOT hand-edit generated files under proto/lib, proto/rem, proto/lcl. They are generated from proto-src/*.snowp via make proto. (Hand-written *extras.go files are the only editable generated-package files.)

Steps

1. Pick a status code in proto-src/lib/status.snowp

Add an enum entry with a new unique @NNNN number, grouped near related codes:

TEAM_ADHOC_OPEN_VIEWERSHIP_ERROR @7102;

2. Add it to the correct arm of variant Status switch (sc : StatusCode)

Same file, further down. Pick the arm by the error's payload:

• No payload (a Go struct{} error): add to the big case OK, ... : void; arm.
• Carries a message string: add to the @1: Text arm.
• Typed payload: add to (or create) the matching arm.

Most new errors are struct{} -> the void arm. Place the new code next to a sibling.

3. Regenerate

make proto

Confirm proto/lib/status.go gained: the StatusCode_<NAME> = NNNN const, a NewStatusWith<CamelName>() constructor, and the new code inside the void-case list. Do not edit that file by hand.

4. Mirror as a Go error in lib/core/errors.go

Three edits, each next to the TeamAdhocCreatorIncludedError precedent:

a. The error type + Error():

type TeamAdhocOpenViewershipError struct{}

func (t TeamAdhocOpenViewershipError) Error() string {
	return "ad-hoc teams require an open-viewership host"
}

b. In the Go-error -> Status switch:

case TeamAdhocOpenViewershipError:
	return proto.NewStatusWithTeamAdhocOpenViewershipError()

c. In the Status -> Go-error switch:

case proto.StatusCode_TEAM_ADHOC_OPEN_VIEWERSHIP_ERROR:
	return TeamAdhocOpenViewershipError{}

For errors with a message payload, the type is type FooError string with func (f FooError) Error() string { return string(f) }, and the switches use the @1: Text constructor/accessor instead of the payload-less forms — again, copy the nearest precedent that uses the same arm.

5. Throw it

Return the Go error value (e.g. core.TeamAdhocOpenViewershipError{}) at the relevant client and/or server chokepoint. It serializes to the status code and reconstitutes as the same Go type on the other side.

6. Verify

gofmt -w <hand-edited .go files>
go build ./...