# R-Machine

> A stable namespace is the contract; the implementation behind it is free to change.

https://rmachine.dev

https://github.com/codecarvings/r-machine/tree/RM-alpha-12
Warning: R-Machine is still in active development - API may change before stable release.

---

R-Machine is not an i18n library. It is not a DI container. It is not a state management library. It does what all three do, but classifying it as any one of them — or as a bundle of three — misses the design. The unification is structural, not packaged: there is one declaration syntax, one consumer primitive, and one testing primitive across all of them.

Because the dependency graph is explicit and named rather than implicit, a change behind a namespace is statically verifiable — which makes the codebase predictable to refactor, for humans and for coding agents alike.

---

## Core concepts

### Resource families

Every resource belongs to one of six families, declared via folder prefix in `defineLayout`:

| Family | Composer | Stateful? | Locale-aware? | Consumed by |
|---|---|---|---|---|
| `gear:inner` | `InnerGear` | no | no | `ServerPlug` (RSC only) |
| `gear:base` | `BaseGear` | no | no | other gears and shells (via `bridgeGears`) |
| `gear:outer` | `OuterGear` | optional | no | `Plug` / `ClientPlug` |
| `gear:outer(vertex)` | `OuterGear` | optional | no | `Plug` / `ClientPlug`, instance-per-component |
| `shell` | `Shell` | no | yes | `Plug` / `ClientPlug` / `ServerPlug` |
| `shell(mono)` | `Shell` | no | yes | `Plug` / `ClientPlug` / `ServerPlug` |

The dep-graph is asymmetric by design: no path connects `gear:inner` to `gear:outer` or `Shell`. Enforced at compile time.

### Composers

All four composers expose the same chain — every step except `define` is optional:

```
InnerGear / BaseGear / Shell  →  withDeps → withPorts → define
OuterGear                     →  withDeps → withPorts → withState → define
```

`define(...)` returns a `ResMatrix` (`r`): the canonical export of every resource module.

### Consumer primitive: Plug

One primitive, three runtime variants:

- `Plug` — React standard strategy, client-side, sync (suspends if unresolved)
- `ClientPlug` — Next.js Client Component, sync
- `ServerPlug` — Next.js RSC, async (`await plug.useR(params)`)

All three support single-resource, list, and map call forms.

### Shell: locale-aware resources

A `shell` resource has one canonical file per locale. The canonical file (`en.ts`) defines the shape; variant files (`it.ts`) use `localized(namespace, value)`, which performs exact-keyed type validation. A `shell(mono)` is a single-file locale-aware resource (formatters, parsers) — no variant files.

### Testing: `mockPlug`

Single primitive, uniform across all families:

```ts
mockPlug(plug).with({ /* type-checked override */ });
```

Overrides are structurally checked against the plug's resolved shape. `verifyResourceAtlas` catches missing locale variants and loader misconfigurations at CI time.

---

## Setup

Two configuration files by convention:

- `resource-atlas.ts` — declares the layout (folder → family mapping) and the resource type map
- `setup.ts` — calls `RMachine.create(...)`, exports composers, locale type, and framework strategy

---

## Packages

- `r-machine` — core (composers, `Plug`, `mockPlug`)
- `@r-machine/react` — `ReactStandardStrategy`
- `@r-machine/next` — `NextAppPathStrategy`, `NextAppFlatStrategy`, `NextAppOriginStrategy`
- `@r-machine/testing` — `mockPlug`, `verifyResourceAtlas`

---

## Full documentation

Complete API reference (composers, cursor primitives, strategies, testing, diagnostics, file conventions):
https://rmachine.dev/llms-full.txt

---

rev 2026-06-08.016
Copyright (c) 2026 Sergio Turolla.
https://codecarvings.com