Residiuum

Residiuum is a deterministic relational document engine that lets developers build nested application artefacts directly from relational data, using explicit enrichment semantics instead of hidden joins and ORM hydration.

---

Production maturity

Not production-ready yet (features are still iterating; see DEF notes in startup output).

Definitive implementation sequence and current starting task: MASTER_DELIVERY_PLAN.md.

Document hierarchy, state, and canonical sources: doc/README.md.

Security

Document	Purpose
SECURITY.md	Vulnerability disclosure process (DEF-063-A)
doc/reference/operations/SUPPORTED_VERSIONS.md	Supported-version policy
doc/wip/security/THREAT_MODEL.md	In-tree threat model (draft)
doc/wip/security/SECURITY_AUDIT_PACKAGE.md	Evidence pack for independent auditors

Do not open public issues for exploit details. Prefer private forge reporting as described in SECURITY.md. Independent external audit is still required before production security claims.

---

Console / CLI

Residiuum includes a small CLI binary named residiuum.

Run an interactive console

residiuum console ./path/to/store

The console reads RQL commands from stdin (one command per line is typical) and executes them against the provided store directory.

Example (piped)

printf '%s\n' \
  'PUT ./tmp/store users/user-1 {"name":"hello"}' \
  'GET ./tmp/store users/user-1' \
| residiuum console ./tmp/store

Non-interactive usage

For scripted usage, pipe commands into the console and terminate with QUIT.

---

The problem

Modern applications usually choose between two compromises.

Relational databases provide:

• strong relationships;
• mature indexing;
• transactional semantics.

But application developers often rebuild the final shape through:

database rows
    ↓
SQL joins
    ↓
ORM hydration
    ↓
application objects
    ↓
API JSON

Document databases provide convenient shapes, but relationships often move into application code.

Residiuum treats relationship formation and document construction as first-class database operations.

---

See the model

Example:

enrich customer using customers
  matching customer_id = id
  expect exactly_one
enrich items using items
  matching id = order_id
  expect many
enrich product using products
  matching product_id = id
  expect exactly_one
project {
  order_id,
  customer.name,
  items {
    quantity,
    product.name
  }
}

This is not a hidden join.