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 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

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, and apply the high-assurance risk gate in rumo-coding-guidelines 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:

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.