suaveplan/openspec/specs/api-plugin-events/spec.md

<!-- markdownlint-disable MD024 -->

# Capability Spec Delta: api-plugin-events (add-api-plugin-events)

**Package**: `@suaveplan/api-plugin-events`
**Status**: PROPOSED

> Every requirement below carries a `**Verified by:**` line at authoring time.

## ADDED Requirements

### Requirement: Plugin factory and lifecycle

The package SHALL export `createEventsPlugin(options?: EventsPluginConfigInput)` returning a `PluginDescriptor<EventsPluginConfig>` that mounts event-management routes against `@suaveplan/api`. The factory SHALL Zod-validate input via `EventsPluginOptionsSchema` at the boundary and throw `EventsPluginError(INVALID_CONFIG)` carrying the `ZodError` as `cause` on invalid input.

#### Scenario: valid options produce a descriptor

- **WHEN** `createEventsPlugin({ basePath: "/v1/events" })` is called
- **THEN** the returned descriptor has `name === "events"`, `dependencies: ["database"]`, and `defaults.basePath === "/v1/events"`

#### Scenario: invalid options fail fast

- **WHEN** `createEventsPlugin({ maxInvitesPerRequest: -1 })` is called
- **THEN** the call throws `EventsPluginError` with `code === EVENTS_PLUGIN_CODES.INVALID_CONFIG` and `cause instanceof ZodError`

#### Scenario: onInit registers repositories

- **WHEN** the descriptor's `onInit(ctx)` runs with a real `db` service in the registry
- **THEN** `ctx.getService("eventRepository")` and `ctx.getService("rsvpRepository")` resolve to non-null repository instances

#### Scenario: onInit fails without database service

- **WHEN** `onInit(ctx)` runs with no `db` service registered
- **THEN** it throws `EventsPluginError` with `code === EVENTS_PLUGIN_CODES.SERVICE_NOT_AVAILABLE`

#### Scenario: onReady mounts routes under basePath

- **WHEN** `onReady(ctx)` runs after `onInit`
- **THEN** `ctx.getService("app").routes` contains entries whose `path` begins with the configured `basePath`

#### Scenario: onReady refuses to double-mount

- **WHEN** `onReady(ctx)` is invoked twice against the same app instance
- **THEN** the second call throws `EventsPluginError` with `code === EVENTS_PLUGIN_CODES.ROUTE_PREFIX_COLLISION`

#### Scenario: onClose clears repositories

- **WHEN** `onClose()` is invoked after a successful boot
- **THEN** subsequent lifecycle methods on the descriptor's `runtime` see cleared `eventRepository` / `rsvpRepository` state and the registry's slots are no longer accessed by the plugin

**Verified by:** `src/plugin/plugin.test.ts::"createEventsPlugin returns descriptor with defaults"` AND `src/plugin/plugin.test.ts::"createEventsPlugin throws INVALID_CONFIG for bad options"` AND `src/plugin/plugin.test.ts::"onInit registers eventRepository and rsvpRepository"` AND `src/plugin/plugin.test.ts::"onInit throws SERVICE_NOT_AVAILABLE without db"` AND `src/plugin/plugin.test.ts::"onReady mounts routes under basePath"` AND `src/plugin/plugin.test.ts::"onReady throws ROUTE_PREFIX_COLLISION on double-mount"` AND `src/plugin/plugin.test.ts::"onClose clears runtime state"`

---

### Requirement: Configuration schema

The package SHALL expose `EventsPluginOptionsSchema` (Zod) producing `EventsPluginConfig` with three fields: `basePath: string` (default `/events`), `enableNotifications: boolean` (default `false`), `maxInvitesPerRequest: integer between 1 and 100` (default `50`).

#### Scenario: defaults apply when input is empty

- **WHEN** `EventsPluginOptionsSchema.parse({})` is called
- **THEN** the returned object equals `{ basePath: "/events", enableNotifications: false, maxInvitesPerRequest: 50 }`

#### Scenario: out-of-range invite cap rejected

- **WHEN** `EventsPluginOptionsSchema.safeParse({ maxInvitesPerRequest: 0 })` is called
- **THEN** `success === false` and `error.issues[0].path` includes `maxInvitesPerRequest`

**Verified by:** `src/schemas/options.test.ts::"parses empty input to defaults"` AND `src/schemas/options.test.ts::"rejects out-of-range maxInvitesPerRequest"`

---

### Requirement: EventRepository CRUD

The package SHALL expose `EventRepository` implementing `IEventRepository` with `findAll(query?)`, `findById(id)`, `create(userId, data)`, `update(id, data)`, `delete(id)`, `isCreator(eventId, userId)`, and `updateAttendeeCount(eventId, status, increment)`. Every method SHALL accept user IDs with or without the `user:` prefix and event IDs with or without the `event:` prefix, normalising both forms internally.

#### Scenario: findAll applies status / upcoming / past filters

- **WHEN** `findAll({ status: 1, upcoming: true, limit: 10, offset: 5 })` is called
- **THEN** the underlying adapter receives a SELECT with `WHERE status = $p0 AND end_time > time::now()` and positional params `[1]` plus pagination clauses

#### Scenario: findById returns null when missing

- **WHEN** `findById("nonexistent")` runs and the adapter returns `[]`
- **THEN** the method returns `null`

#### Scenario: create raises FAILURE on empty response

- **WHEN** `create("user:1", data)` runs and the adapter returns `[]`
- **THEN** the method throws `EventsPluginError` with `code === EVENTS_PLUGIN_CODES.EVENT_CREATE_FAILED`

#### Scenario: update emits only provided fields

- **WHEN** `update("1", { title: "X" })` is called
- **THEN** the SET clause includes `title = $p0` and does not include `description`, `start_time`, etc.

#### Scenario: isCreator handles RecordId / object / string shapes

- **WHEN** the adapter returns `{ creator: { tb: "user", id: "1" } }` and `isCreator("event:1", "user:1")` is called
- **THEN** the method returns `true`

#### Scenario: updateAttendeeCount no-ops for not_going

- **WHEN** `updateAttendeeCount("event:1", "not_going", 1)` is called
- **THEN** no adapter query runs

**Verified by:** `src/repositories/event-repository/event-repository.test.ts::"findAll applies status and upcoming filters"` AND `src/repositories/event-repository/event-repository.test.ts::"findById returns null when not found"` AND `src/repositories/event-repository/event-repository.test.ts::"create raises EVENT_CREATE_FAILED on empty response"` AND `src/repositories/event-repository/event-repository.test.ts::"update only emits provided fields"` AND `src/repositories/event-repository/event-repository.test.ts::"isCreator handles RecordId object"` AND `src/repositories/event-repository/event-repository.test.ts::"updateAttendeeCount no-ops for not_going"`

---

### Requirement: RsvpRepository surface

The package SHALL expose `RsvpRepository` implementing `IRsvpRepository` with `findByEventAndUser`, `findAttendees`, `upsert`, `delete`, `createInvitations`, and `countByStatus`. The repository SHALL idempotently skip existing invitations when `createInvitations` is called with a user that already has an RSVP row.

#### Scenario: upsert creates when no row exists

- **WHEN** `upsert("event:1", "user:1", { status: "going" })` runs against an empty table
- **THEN** the adapter receives a CREATE statement and the returned RSVP has `status === "going"`

#### Scenario: upsert updates when a row exists

- **WHEN** `upsert("event:1", "user:1", { status: "maybe" })` runs and a row already exists for the same (event, user)
- **THEN** the adapter receives an UPDATE statement instead of CREATE

#### Scenario: delete returns the prior status

- **WHEN** `delete("event:1", "user:1")` runs and the prior row had `status: "going"`
- **THEN** the method returns `"going"` and the row is deleted

#### Scenario: createInvitations skips existing rows

- **WHEN** `createInvitations("event:1", ["user:1", "user:2"])` runs and `user:1` already has an RSVP
- **THEN** the returned array has length 1 (only `user:2`)

#### Scenario: countByStatus returns 0 on empty

- **WHEN** `countByStatus("event:1", "going")` runs and the adapter returns `[]`
- **THEN** the method returns `0`

**Verified by:** `src/repositories/rsvp-repository/rsvp-repository.test.ts::"upsert creates new row when none exists"` AND `src/repositories/rsvp-repository/rsvp-repository.test.ts::"upsert updates when row exists"` AND `src/repositories/rsvp-repository/rsvp-repository.test.ts::"delete returns prior status"` AND `src/repositories/rsvp-repository/rsvp-repository.test.ts::"createInvitations skips existing rows"` AND `src/repositories/rsvp-repository/rsvp-repository.test.ts::"countByStatus returns 0 on empty result"`

---

### Requirement: Route surface (9 endpoints)

The package SHALL expose `createEventRoutes({ eventRepository, rsvpRepository, emitEvent? })` returning an `OpenAPIHono` instance with these routes (relative to the mount prefix): `GET /`, `GET /{id}`, `POST /`, `PUT /{id}`, `DELETE /{id}`, `POST /{id}/rsvp`, `DELETE /{id}/rsvp`, `GET /{id}/my-rsvp`, `GET /{id}/attendees`, `POST /{id}/invite`. Each route SHALL be wrapped with `@hono/zod-openapi` `createRoute`, validating request bodies / params / queries through the package's Zod schemas. Every route SHALL require an authenticated user (`c.get("user")`) and return `401` with `EVENTS_PLUGIN_CODES.UNAUTHENTICATED` when absent.

#### Scenario: unauthenticated request returns 401

- **WHEN** a request reaches `GET /` without `user` set in the Hono context
- **THEN** the response status is `401` and the body is `{ error: "Authentication required" }`

#### Scenario: list returns paginated events

- **WHEN** `GET /` runs with `user` set and `eventRepository.findAll` returns 2 events
- **THEN** the response is `200` and the body is `{ data: [event1, event2] }`

#### Scenario: get returns 404 when event missing

- **WHEN** `GET /missing-id` runs with `user` set and `findById` returns `null`
- **THEN** the response is `404` with body `{ error: "Event not found" }`

#### Scenario: create emits event and returns 201

- **WHEN** `POST /` runs with valid body and `user.id = "user:1"`
- **THEN** the response is `201`, the body is the created event, and `emitEvent` is called with `{ type: "event:created", payload: { eventId, creatorId: "user:1" } }`

#### Scenario: update requires creator

- **WHEN** `PUT /{id}` runs with a user who is not the event creator
- **THEN** the response is `403` with body `{ error: "Only event creator can update this event" }`

#### Scenario: delete by non-creator forbidden

- **WHEN** `DELETE /{id}` runs with a non-creator user
- **THEN** the response is `403`

#### Scenario: rsvp updates attendee counts

- **WHEN** `POST /{id}/rsvp` runs with `status: "going"` and no prior RSVP
- **THEN** `eventRepository.updateAttendeeCount` is called with `(id, "going", 1)` and `emitEvent` fires `rsvp:created`

#### Scenario: cancel-rsvp returns 404 when no prior RSVP

- **WHEN** `DELETE /{id}/rsvp` runs and the user has no RSVP row
- **THEN** the response is `404`

#### Scenario: attendees returns paginated list

- **WHEN** `GET /{id}/attendees` runs
- **THEN** the response is `200` with body `{ data: [...], total: <count> }`

#### Scenario: invite requires creator

- **WHEN** `POST /{id}/invite` runs with a non-creator
- **THEN** the response is `403`

#### Scenario: invite enforces maxInvitesPerRequest

- **WHEN** `POST /{id}/invite` is called with a `user_ids` array longer than `maxInvitesPerRequest`
- **THEN** validation fails at the Zod boundary with a `400`

**Verified by:** `src/routes/events-routes/events-routes.test.ts::"GET / returns 401 without user"` AND `src/routes/events-routes/events-routes.test.ts::"GET / returns paginated events"` AND `src/routes/events-routes/events-routes.test.ts::"GET /{id} returns 404 when missing"` AND `src/routes/events-routes/events-routes.test.ts::"POST / emits event:created and returns 201"` AND `src/routes/events-routes/events-routes.test.ts::"PUT /{id} returns 403 for non-creator"` AND `src/routes/events-routes/events-routes.test.ts::"DELETE /{id} returns 403 for non-creator"` AND `src/routes/events-routes/events-routes.test.ts::"POST /{id}/rsvp updates attendee count"` AND `src/routes/events-routes/events-routes.test.ts::"DELETE /{id}/rsvp returns 404 when none"` AND `src/routes/events-routes/events-routes.test.ts::"GET /{id}/attendees returns list"` AND `src/routes/events-routes/events-routes.test.ts::"POST /{id}/invite returns 403 for non-creator"` AND `src/schemas/rsvp-schemas.test.ts::"InviteUsersSchema enforces user_ids length"`

---

### Requirement: Error code registry

The package SHALL expose `EVENTS_PLUGIN_CODES = defineCodes("EVENTS_PLUGIN", [...])` covering 12 stable codes: `INVALID_CONFIG`, `SERVICE_NOT_AVAILABLE`, `ROUTE_PREFIX_COLLISION`, `EVENT_CREATE_FAILED`, `EVENT_UPDATE_FAILED`, `RSVP_CREATE_FAILED`, `RSVP_UPDATE_FAILED`, `RSVP_NOT_FOUND`, `EVENT_NOT_FOUND`, `UNAUTHENTICATED`, `FORBIDDEN`, `INVITE_LIMIT_EXCEEDED`. The namespace `"EVENTS_PLUGIN"` (not `"EVENTS"`) prevents collision with `@suaveplan/events`. Every code SHALL be thrown by at least one production path.

#### Scenario: every code is reachable

- **WHEN** the conformance test reflects over `EVENTS_PLUGIN_CODES` and grep-asserts each value appears in a `new EventsPluginError(<code>, ...)` call site under `src/`
- **THEN** every code resolves to ≥1 match

**Verified by:** `src/error-codes/error-codes.test.ts::"every EVENTS_PLUGIN_CODES value is thrown by src/"`

---

### Requirement: OTel instruments

The package SHALL emit 5 OpenTelemetry instruments via `metrics.getMeter("@suaveplan/api-plugin-events")`: `eventsCreatedTotal` (Counter), `eventsUpdatedTotal` (Counter), `eventsDeletedTotal` (Counter), `rsvpsWrittenTotal` (Counter, labelled by `status`), `invitationsSentTotal` (Counter). Instruments SHALL be lazily built and cached; `resetEventsInstruments()` SHALL clear the cache for test re-binding.

#### Scenario: instruments emit on real production paths

- **WHEN** a freshly-installed in-memory `MeterProvider` is set, `resetEventsInstruments()` is called, then `POST /` succeeds
- **THEN** the next `forceFlush` of the in-memory reader contains `events.created_total` with value `1`

**Verified by:** `src/otel/instruments.test.ts::"getEventsInstruments returns the same bundle on repeated calls"` AND `src/otel/instruments.test.ts::"emits events.created_total when a create succeeds"` AND `src/otel/instruments.test.ts::"resetEventsInstruments rebinds against a fresh provider"`

---

### Requirement: Service registry augmentation

The package SHALL augment `@suaveplan/api-plugin/service-registry` `ServiceRegistry` with `eventRepository: IEventRepository` and `rsvpRepository: IRsvpRepository` slots so downstream plugins resolve them via `ctx.getService("eventRepository")` with full typing.

#### Scenario: registered services resolve with the augmented type

- **WHEN** a downstream `PluginContext` calls `ctx.getService("eventRepository")` after the events plugin's `onInit` ran
- **THEN** the value is an `IEventRepository` (compile-time + runtime)

**Verified by:** `src/api-plugin-events.spec-conformance.test.ts::"ServiceRegistry exposes eventRepository and rsvpRepository slots"`

---

### Requirement: Public surface (subpath exports)

The package SHALL expose the following subpath exports in `package.json`: `.`, `./plugin/plugin`, `./schemas/options`, `./schemas/event-schemas`, `./schemas/rsvp-schemas`, `./error-codes/error-codes`, `./otel/instruments`, `./repositories/event-repository/event-repository`, `./repositories/rsvp-repository/rsvp-repository`, `./routes/events-routes/events-routes`, `./types/types`. The root barrel SHALL re-export every public symbol via explicit named exports (rule 10 — no `export *` outside generated forwarders).

#### Scenario: every documented symbol is re-exported by the root

- **WHEN** the spec-conformance test imports the package root and reflects over expected symbols
- **THEN** every expected symbol resolves to a non-`undefined` value

**Verified by:** `src/api-plugin-events.spec-conformance.test.ts::"re-exports every documented symbol"`

---

### Requirement: SurrealDB migration payload

The package SHALL ship `surql/tables/event.surql` defining the SCHEMAFULL tables `event` and `event_rsvp` plus the supporting indexes (`event_start_idx`, `event_rsvp_unique_idx`). The migration SHALL parse and execute cleanly against a real SurrealDB v3 instance with no cross-plugin function references — the upstream cross-plugin permission rules and helper functions (`fn::bitwise::*`, `fn::event::*`, `fn::group::*`, `fn::notification::*`) and the auxiliary `event_update` table are intentionally scoped out (see proposal `## Out of scope`) because they depend on plugins that do not yet exist on genesis. Permissions are enforced at the route / repository layer, not the database layer.

#### Scenario: surql loads cleanly

- **WHEN** the full-boot integration test executes the migration against a real SurrealDB v3 container
- **THEN** subsequent `CREATE event` and `CREATE event_rsvp` statements succeed and round-trip the inserted fields

**Verified by:** `tests/integration/full-boot.test.ts::"boots, creates event, records rsvp, increments count, cleans up"`

---

### Requirement: Integration boot

The package SHALL boot end-to-end against a real SurrealDB v3 instance: `createEventsPlugin` → `onInit` → `onReady` → CRUD a real event → RSVP → delete. The integration test SHALL skip cleanly when `isSurrealDBAvailable()` is `false`.

#### Scenario: full lifecycle against real Surreal

- **WHEN** a SurrealDB v3 testcontainer is running and the integration test invokes the full boot
- **THEN** an `event` is created, an `rsvp` is recorded, the attendee count rises by 1, the rsvp is cancelled, and the event is deleted — every step round-trips through `db.query` without throwing

**Verified by:** `tests/integration/full-boot.test.ts::"boots, creates event, records rsvp, increments count, cleans up"`

### Requirement: ICS export endpoint

The package SHALL expose a `GET /:id/ics` route mounted by `createEventsPlugin` under the configured `basePath`. The route SHALL return HTTP `200` with `Content-Type: text/calendar; charset=utf-8` and a body containing one RFC 5545 `VCALENDAR` block enclosing a single `VEVENT` for the requested event. The response SHALL carry `Content-Disposition: attachment; filename="event-<id>.ics"` where `<id>` is the URL-safe event id. Authentication SHALL be required: a request without `c.get("user")` SHALL return HTTP `401` with body `{ error: "Authentication required", code: "EVENTS_PLUGIN.UNAUTHENTICATED" }`. A request whose event id does not resolve in `eventRepository.findById` SHALL return HTTP `404` with code `EVENTS_PLUGIN.EVENT_NOT_FOUND`.

#### Scenario: unauthenticated request returns 401

- **WHEN** `GET /event:1/ics` runs without `user` set in the Hono context
- **THEN** the response status is `401` and the body contains `code: "EVENTS_PLUGIN.UNAUTHENTICATED"`

#### Scenario: 200 success returns VCALENDAR with single VEVENT

- **WHEN** `GET /event:1/ics` runs with `user` set and `eventRepository.findById` returns an event
- **THEN** the response status is `200`, `Content-Type` is `text/calendar; charset=utf-8`, `Content-Disposition` is `attachment; filename="event-event:1.ics"`, and the body matches `/^BEGIN:VCALENDAR\r\n[\s\S]+\r\nEND:VCALENDAR\r\n$/` containing exactly one `BEGIN:VEVENT` / `END:VEVENT` pair

#### Scenario: missing event returns 404

- **WHEN** `GET /missing/ics` runs and `findById` returns `null`
- **THEN** the response status is `404` and the body carries `code: "EVENTS_PLUGIN.EVENT_NOT_FOUND"`

**Verified by:** `src/routes/ics-export/ics-export.test.ts::"GET /:id/ics returns 401 without user"` AND `src/routes/ics-export/ics-export.test.ts::"GET /:id/ics returns 200 with single VEVENT VCALENDAR"` AND `src/routes/ics-export/ics-export.test.ts::"GET /:id/ics returns 404 when event missing"` AND `src/routes/ics-export/ics-export.test.ts::"GET /:id/ics sets Content-Disposition attachment header"`

---

### Requirement: VEVENT body content

The single `VEVENT` block SHALL emit the following properties, sourced from the event fields shipped on `EventSchema`: `UID` as `${eventId}@suaveplan.events`; `DTSTAMP` from the injected `Clock` formatted as UTC `YYYYMMDDTHHMMSSZ` per §3.3.5; `DTSTART` from `event.start_time` formatted as UTC `YYYYMMDDTHHMMSSZ`; `DTEND` from `event.end_time` formatted the same way; `SUMMARY` from `event.title` with §3.3.11 escaping applied; `DESCRIPTION` from `event.description` if present, also escaped; `LOCATION` from `event.location.name` if present, also escaped; `STATUS` mapped from the event status integer (`0`→`TENTATIVE`, `1`→`CONFIRMED`, `2`→`CANCELLED`) per §3.8.1.11; and `SEQUENCE:0`. `ORGANIZER` SHALL NOT be emitted in v0.1 because the event schema does not carry a host email — the empty slot is documented in the proposal and remains reserved for a future schema field.

#### Scenario: every required property is present in order

- **WHEN** the builder runs against an event with title `"T"`, description `"d"`, location name `"L"`, start `2026-01-01T10:00:00Z`, end `2026-01-01T12:00:00Z`, status `1`
- **THEN** the body contains exactly one of each line in order: `BEGIN:VEVENT`, `UID:event:1@suaveplan.events`, `DTSTAMP:...Z`, `DTSTART:20260101T100000Z`, `DTEND:20260101T120000Z`, `SUMMARY:T`, `DESCRIPTION:d`, `LOCATION:L`, `STATUS:CONFIRMED`, `SEQUENCE:0`, `END:VEVENT`

#### Scenario: status maps draft → TENTATIVE and cancelled → CANCELLED

- **WHEN** the builder runs with `status: 0` and again with `status: 2`
- **THEN** the first body contains `STATUS:TENTATIVE` and the second contains `STATUS:CANCELLED`

#### Scenario: optional fields omit when absent

- **WHEN** the builder runs with `description` undefined and `location` undefined
- **THEN** the body contains no `DESCRIPTION:` or `LOCATION:` line

**Verified by:** `src/ics/ics-builder/ics-builder.test.ts::"emits every required VEVENT property in canonical order"` AND `src/ics/ics-builder/ics-builder.test.ts::"maps status integer to RFC 5545 STATUS value"` AND `src/ics/ics-builder/ics-builder.test.ts::"omits DESCRIPTION and LOCATION when absent"`

---

### Requirement: Text escape rules per §3.3.11

Every value written into `SUMMARY`, `DESCRIPTION`, or `LOCATION` SHALL be escaped per RFC 5545 §3.3.11: backslash → `\\`, semicolon → `\;`, comma → `\,`, newline (`\n` and `\r\n`) → `\n` (the literal two characters `\` + `n`). Carriage returns inside text SHALL be normalised away before escaping. Escaping SHALL happen before line folding.

#### Scenario: comma semicolon backslash newline are escaped

- **WHEN** `escapeText("a,b;c\\d\ne")` runs
- **THEN** the result is the exact string `a\,b\;c\\d\ne`

#### Scenario: CRLF in source becomes a single escaped \n

- **WHEN** `escapeText("a\r\nb")` runs
- **THEN** the result is the exact string `a\nb`

**Verified by:** `src/ics/ics-builder/ics-builder.test.ts::"escapeText escapes comma semicolon backslash and newline"` AND `src/ics/ics-builder/ics-builder.test.ts::"escapeText normalises CRLF to a single \\n"`

---

### Requirement: Line folding per §3.1

Every emitted content line longer than 75 octets SHALL be folded: the line is split into 75-octet segments and each subsequent segment is prefixed with a single SPACE on a new CRLF-terminated line, exactly as specified in RFC 5545 §3.1. Folding SHALL operate on the post-escape byte stream so multi-byte UTF-8 sequences are not split mid-codepoint when avoidable (the implementation MAY fold at the nearest safe byte boundary ≤75 octets to preserve UTF-8). Every output line including the final `END:VCALENDAR` SHALL terminate with CRLF (`\r\n`).

#### Scenario: a 200-character DESCRIPTION folds into three CRLF-separated segments

- **WHEN** the builder runs against an event whose escaped `DESCRIPTION` is 200 ASCII octets long
- **THEN** the body contains `DESCRIPTION:` followed by the first 63 octets on the first physical line (75 = `DESCRIPTION:` 12 octets + 63 payload), then `\r\n` (CRLF + space) before each subsequent 74-octet payload segment, and every physical line ends in `\r\n`

#### Scenario: every output line ends in CRLF

- **WHEN** `buildVCalendar` runs against any valid input
- **THEN** the body contains zero `\n` bytes that are not preceded by `\r`

**Verified by:** `src/ics/ics-builder/ics-builder.test.ts::"folds a 200-octet DESCRIPTION into 75-octet continuation segments"` AND `src/ics/ics-builder/ics-builder.test.ts::"every output line ends in CRLF"`

---

### Requirement: RSVP attendee export (?with=rsvps)

When the request includes `?with=rsvps`, the response body SHALL contain one `ATTENDEE` line inside the `VEVENT` per row returned by `rsvpRepository.findAttendees(eventId)`. Each `ATTENDEE` line SHALL carry the `CN` parameter from the attendee's `user_name` if present (escaped per §3.3.11), a `PARTSTAT` parameter mapped from the RSVP status (`going`→`ACCEPTED`, `maybe`→`TENTATIVE`, `not_going`→`DECLINED`, `invited`→`NEEDS-ACTION`), and the CAL-ADDRESS value as `mailto:<user_email>` when `user_email` is present or `mailto:<user_id>@suaveplan.local` as a non-routable fallback when it is not. The `?with=rsvps` variant SHALL require the requester to be the event creator: a non-creator SHALL receive HTTP `403` with code `EVENTS_PLUGIN.FORBIDDEN`. The plain `GET /:id/ics` (no `with` query) SHALL NOT emit any `ATTENDEE` lines and SHALL NOT require creator privileges.

#### Scenario: with=rsvps emits one ATTENDEE per RSVP

- **WHEN** `GET /event:1/ics?with=rsvps` runs with `user` = creator and `findAttendees` returns 2 RSVP rows
- **THEN** the body contains exactly 2 `ATTENDEE` lines, each carrying a `PARTSTAT=` parameter and a `mailto:` value

#### Scenario: with=rsvps maps PARTSTAT values

- **WHEN** the builder runs with attendees of status `going`, `maybe`, `not_going`, `invited`
- **THEN** the corresponding ATTENDEE lines carry `PARTSTAT=ACCEPTED`, `PARTSTAT=TENTATIVE`, `PARTSTAT=DECLINED`, `PARTSTAT=NEEDS-ACTION`

#### Scenario: with=rsvps by non-creator returns 403

- **WHEN** `GET /event:1/ics?with=rsvps` runs with a user where `isCreator` returns `false`
- **THEN** the response status is `403` and the body carries `code: "EVENTS_PLUGIN.FORBIDDEN"`

#### Scenario: invalid with value returns 422

- **WHEN** `GET /event:1/ics?with=bogus` runs
- **THEN** the response status is `422` and the body carries `code: "EVENTS_PLUGIN.ICS_INVALID_QUERY"`

**Verified by:** `src/routes/ics-export/ics-export.test.ts::"GET /:id/ics?with=rsvps emits one ATTENDEE per RSVP"` AND `src/ics/ics-builder/ics-builder.test.ts::"maps RSVP status to ATTENDEE PARTSTAT"` AND `src/routes/ics-export/ics-export.test.ts::"GET /:id/ics?with=rsvps returns 403 for non-creator"` AND `src/routes/ics-export/ics-export.test.ts::"GET /:id/ics returns 422 for invalid with value"`

---

### Requirement: New error code

The package SHALL extend `EVENTS_PLUGIN_CODES` with `ICS_INVALID_QUERY` (registry size 12 → 13). The code SHALL be raised when the Zod schema for the ICS route query rejects an unknown `with` value, surfaced to the client as HTTP `422`. The code SHALL be thrown by at least one production path under `src/routes/ics-export/`.

#### Scenario: ICS_INVALID_QUERY is reachable

- **WHEN** the error-codes conformance test reflects over `EVENTS_PLUGIN_CODES` and greps `src/` for a `new EventsPluginError(EVENTS_PLUGIN_CODES.ICS_INVALID_QUERY, ...)` or `code: EVENTS_PLUGIN_CODES.ICS_INVALID_QUERY` call site
- **THEN** at least one match is found

**Verified by:** `src/error-codes/error-codes.test.ts::"every EVENTS_PLUGIN_CODES value is thrown by src/"`

---

### Requirement: OTel counters

The package SHALL extend `EventsInstruments` with two new counters created against `metrics.getMeter("@suaveplan/api-plugin-events")`: `icsServedTotal` (instrument name `events.ics.served_total`, labelled with `with` taking values `"none"` or `"rsvps"`) and `icsFailedTotal` (instrument name `events.ics.failed_total`, labelled with `reason` taking values `"not_found"`, `"forbidden"`, `"unauthenticated"`, or `"invalid_query"`). Both counters SHALL be lazily built, cached, and cleared by `resetEventsInstruments()`. The ICS route SHALL increment `icsServedTotal` on every successful response and `icsFailedTotal` on every error response.

#### Scenario: success path increments served_total

- **WHEN** a freshly-installed in-memory `MeterProvider` is set, `resetEventsInstruments()` is called, then `GET /event:1/ics` returns 200
- **THEN** the next `forceFlush` of the in-memory reader contains `events.ics.served_total` with attribute `with=none` and value `1`

#### Scenario: 404 path increments failed_total

- **WHEN** the same setup runs and `GET /missing/ics` returns 404
- **THEN** the next `forceFlush` contains `events.ics.failed_total` with attribute `reason=not_found` and value `1`

**Verified by:** `src/otel/instruments.test.ts::"exposes ics served and failed counters"` AND `src/routes/ics-export/ics-export.test.ts::"increments events.ics.served_total on success"` AND `src/routes/ics-export/ics-export.test.ts::"increments events.ics.failed_total on 404"`

---

### Requirement: Public surface (subpath exports + named re-exports)

The package SHALL add two new subpath exports in `package.json`: `./ics/ics-builder/ics-builder` and `./routes/ics-export/ics-export`. The root barrel SHALL add explicit named re-exports of `createIcsExportRoutes`, `buildVCalendar`, `BuildVCalendarInput`, `IcsAttendee`, `IcsExportRoutesConfig`, and `IcsEventStatus` (rule 10 — no `export *` outside generated forwarders).

#### Scenario: new symbols resolve from the package root

- **WHEN** the conformance test imports the package root and asserts the new symbols resolve to non-`undefined`
- **THEN** every expected symbol matches

**Verified by:** `src/api-plugin-events.spec-conformance.test.ts::"re-exports ICS surface (builder + routes)"`

---

### Requirement: Plugin wires ICS routes alongside CRUD routes

`createEventsPlugin`'s `onReady` SHALL mount `createIcsExportRoutes(...)` on the same `OpenAPIHono` instance under the same `basePath` as `createEventRoutes(...)`. Both route modules SHALL share the host-supplied `user` context variable. The plugin SHALL pass `Date.now` as the default `Clock` to the ICS routes; tests MAY override via `createIcsExportRoutes` directly.

#### Scenario: plugin onReady mounts an ICS route

- **WHEN** `onReady` runs against a fresh registry and app
- **THEN** the app's `routes` array contains at least one entry whose `path` ends in `/:id/ics`

**Verified by:** `src/plugin/plugin.test.ts::"onReady mounts the ICS export route"`