Rumo Interface

---
name: rumo-interface
description: Use when adding, changing, deprecating, or reviewing anything another process, version, or product reads or writes, such as an HTTP/JSON endpoint or OpenAPI contract, DTO, event or queue message, protocol, configuration field, database representation, persisted file, or export. Trace every producer and consumer, define old/new compatibility and rollout order, and for HTTP routes also cover authentication, authorization, idempotency, rate limits, pagination, and response cost. Do not use for purely internal refactors with no external reader.
---

# Rumo Interface

Anything that crosses a process, storage, deployment-version, module, or product boundary is an interface. Change it as a contract, not as local code. Database writes themselves go through `rumo-database-change-safety`.

## 1. Inventory

Before editing, identify:

- the authority for names, types, units, nullability, defaults, enum values, identifiers, ordering, and error semantics;
- every production producer and consumer: frontends, services, clients, middleware, reports, imports and exports, scripts, sibling products, supported branches;
- everything derived from the authority: generated clients, schemas, mappers, fixtures, examples, deployment configuration, docs;
- instances that outlive one process version: stored rows, queued messages, files, caches;
- how it rolls out: atomic replacement, rolling deploy, offline upgrade, delayed workers, customer packages, mixed versions in the field.

A search is discovery, not proof of absence. Check reflection, dynamic deserialization, SQL, templates, external integrations, and deployed configuration.

## 2. Classify

For each producer and consumer pair, the change is one of: additive and ignored by old readers; additive but required by new readers; a meaning change to an existing field; restrictive, renamed, removed, reordered, or retyped; durable, so old stored values persist; or intentionally incompatible within a declared window. "JSON ignores unknown fields" is not compatibility: required values, enums, defaults, validation, UI assumptions, SQL projections, signatures, and side effects can still break old consumers.

## 3. Plan The Transition

When versions overlap, expand, migrate, then contract:

1. Make readers accept both old and new shapes without changing meaning.
2. Ship compatible readers before new writers.
3. Switch writers and migrate stored data with bounded, observable progress.
4. Confirm old producers, queued messages, files, and supported clients are drained or upgraded.
5. Remove the compatibility code only once its supported lifetime is over.

To deprecate a route, field, message, or format, and only when removal is authorized: ship and document the replacement, find and notify consumers, expose the established deprecation or sunset signal, measure usage per consumer, rehearse migration and rollback, and remove only when the agreed support window and usage criteria are both met. Age alone never proves something is safe to remove; consumers you cannot observe stay recorded as unverified.

Resolve defaults in the owning parser or config layer, not in scattered null checks. Fail early and loudly on invalid referents, fields, enum values, units, or versions. Keep unknown values only when passing them through is an explicit requirement; otherwise reject them with a diagnostic that names the field without echoing sensitive content. Use opaque stable identifiers. Version durable formats whose interpretation can change: say who bumps the version, which versions each reader accepts, and whether an unsupported version fails, migrates, or opens read-only. Never reinterpret old data silently.

## 4. Failure And Rollback

Define error categories, partial success, retry safety, duplicate handling, and whether bad input is rejected before side effects. Put validation in one owner. Treat rollback as a matrix: can the old version read what the new one wrote, can messages be replayed, does a down-migration lose data, and when is the last safe rollback point.

## 5. HTTP Routes

For HTTP/JSON surfaces, read [references/http.md](references/http.md) and work through its checklist: convention, contract, compatibility with existing callers, authentication, authorization and isolation, retries and idempotency, cost and incident control, collections, response cost, errors, and leaked internals.

## 6. Verify The Matrix

| Producer | Consumer | Evidence |
| --- | --- | --- |
| old | old | existing behavior still pinned |
| old | new | defaults, migration, and old stored values work |
| new | new | new meaning and invalid cases work |
| new | old | compatible, or the rollout explicitly forbids this pair |

Add invalid types, missing required values, unknown enums, boundaries, duplicate delivery, serialization round trips, reload of stored data, and rollback where they apply. Check the assembled route or artifact when generation, packaging, proxies, or deployment can differ from source tests. Plan coverage with `rumo-test`, applying its high-assurance risk gate before implementation; check the final diff with `rumo-verify`; record a material compatibility or versioning policy with `rumo-plan`.

## Report

The authority, producers, consumers, classification, rollout order, migration owner, failure behavior, rollback cutoff, evidence obtained, and any external or field consumer still unverified.

A plan for adding `PARTIALLY_REFUNDED` to the order status enum:

```text
Authority: OrderStatus in orders/model.py; serialized as a string.
Consumers: web list filter, finance report SQL (reports/daily.sql:40), reconciliation export, mobile app 3.x.
Old readers: the web filter drops unknown values; mobile 3.x throws on an unknown status.
Rollout: ship readers that map unknown statuses to "other", wait until mobile < 3.4 is unsupported,
then enable writers; no stored rows change.
Rollback cutoff: after the first PARTIALLY_REFUNDED row exists, roll back only to a reader-compatible version.
Unverified: third-party reconciliation tool, owner not identified.
```

Not a plan: "JSON ignores unknown fields, so adding a value is compatible." Mobile 3.x throws, and the report SQL's `IN (...)` list silently drops the new rows.