---
name: diesel2
description: Design decisions for the d2 (diesel2) prototype, recorded as they were agreed. Append-only; newest last.
project: diesel2
---

# diesel2: project log

The design decisions behind this prototype, one entry each, in the order they were made. The long form lives in the spec topics on the metals reactor; this log is the short, dated record of what was decided and by whom.

## 2026-09-23 · A new code base

- **Decided by:** Razie
- **Decision:** d2 is a new code base replacing diesel (d1). No code is reused; only the core principles, the functionality and some design elements carry over.
- **Where:** [[metals.Topic:Diesel2|Diesel2]] (the spec)

## 2026-09-23 · TypeScript on Node for the prototype

- **Decided by:** Razie
- **Decision:** The prototype is written in TypeScript on Node.
- **Why:** It's a learning vehicle; the final build may move to another language.
- **Where:** [[metals.Topic:Diesel2Prototype1|Diesel2Prototype1]]

## 2026-09-23 · Its own box, deployed by the AI

- **Decided by:** Razie
- **Decision:** The prototype runs at d2.aidieselapps.com on a cloud box of its own, and Claude deploys to it through the box's admin API.
- **Why:** Fast turnaround: changes go from chat to a running system in minutes.
- **Where:** [[metals.Topic:Diesel2Prototype1|Diesel2Prototype1]] section 2

## 2026-09-24 · WPATH stays realm.Class:key

- **Decided by:** Razie
- **Decision:** Object paths keep d1's form, `realm.Class:key`. A `realm/Class:key` form was noted and not adopted.
- **Where:** [[metals.Topic:Diesel2|Diesel2]]

## 2026-09-24 · Containment means ownership

- **Decided by:** Razie
- **Decision:** When a class contains a keyed class, it owns it. Inverse relationships are inferred, and declaring both sides is an error. No nested URLs.
- **Where:** [[metals.Topic:Diesel2|Diesel2]], [[Skill:domain-modelling]]

## 2026-09-24 · Its own engine: sync first

- **Decided by:** Razie
- **Decision:** d2 builds its own rule engine: synchronous first, asynchronous layered on top, single-threaded.
- **Where:** [[metals.Topic:Diesel2|Diesel2]]

## 2026-09-24 · Int is Java's long

- **Decided by:** Razie
- **Decision:** `Int` is a signed 64-bit integer that wraps on overflow, like Java's `long`; no big-integer arithmetic.
- **Why:** The final code may be generated in Java, and the two must agree.
- **Where:** [[metals.Topic:Diesel2Expressions|Diesel2Expressions]] section 2; proto1 v0.3.2

## 2026-09-24 · Each rule works on its own copy of the payload

- **Decided by:** Razie
- **Decision:** A rule works on a local copy of the payload, which goes back to the caller only when the rule ends. Scope is the rule, not the block.
- **Why:** It avoids concurrency problems. The step-by-step payload pipeline is taken from MuleSoft's flow language.
- **Where:** [[metals.Topic:Diesel2Expressions|Diesel2Expressions]]

## 2026-09-24 · Operators that read like English

- **Decided by:** Razie
- **Decision:** The expression language prefers words (`and`, `or`, `not`, `is` for equality); the usual symbols (`&&`, `==`) work too.
- **Why:** The language should sound natural.
- **Where:** [[metals.Topic:Diesel2Expressions|Diesel2Expressions]]; try it in the [Fiddle](/fiddle)

## 2026-09-24 · Stylesheets as topics

- **Decided by:** Razie asked for it; Claude proposed the design; Razie approved.
- **Decision:** A stylesheet can be a `Style:` topic, with the logo text (`brand`) as part of it. A broken one is listed with its errors and can't be picked.
- **Why:** A user's AI can then make a new look through the ordinary topics API, with nothing new to learn.
- **Where:** [[metals.Topic:Diesel2Ui|Diesel2Ui]] section 4; [Styles](/styles); proto1 v0.7.0