Decision records
One record per significant choice, numbered, never rewritten after acceptance. Template: 0000-template.md. "Accepted (provisional)" means adopted on a recommendation while Mik's answer is pending (see 0001).
| # | Decision | Status |
|---|---|---|
| 0001 | Record architecture decisions | Accepted |
| 0002 | Organise the repository into bounded contexts | Provisional |
| 0003 | The glossary is part of the specification | Provisional |
| 0004 | Dependency rules, enforced in CI | Accepted |
| 0005 | Code as prose | Provisional |
| 0006 | Contract-first parallel work with sub-agents | Provisional |
| 0007 | Lynx behind an engine adapter | Subject to spike |
| 0008 | Rust compiler using oxc and lightningcss | Provisional |
| 0009 | Licence: MIT OR Apache-2.0 | Provisional |
| 0010 | Codename "strata" until the public name is chosen | Superseded by 0161 |
| 0011 | Provisional answers to the planning decisions list | Provisional |
| 0012 | Build a thin walking skeleton for web before Specification v0 | Provisional |
| 0013 | Control flow is written as markup: show, otherwise and keyed lists | Proposed |
| 0014 | Derived values, two-way binding and the new events | Proposed |
| 0015 | Components are files in components/, imported explicitly, with props declared in the script | Proposed |
| 0016 | Grow the utility vocabulary from data, with fixed scales beside theme tokens | Proposed |
| 0017 | Add hover, and md and lg window-size prefixes at 768px and 1024px | Proposed |
| 0018 | A project theme is a schema-checked theme.yaml that also chooses the colour scheme | Proposed |
| 0019 | Write the data core ourselves, behind the adapter meant for TanStack Query | Accepted |
| 0020 | The data layer is objects with reactive properties, named as in the brief | Accepted |
| 0021 | Environment values reach a page as a global set by the build | Proposed |
| 0022 | One formatting style for page files; the script block is kept as written | Accepted (provisional) |
| 0023 | The TextMate grammar is generated from the language definition | Accepted (provisional) |
| 0025 | The language server runs on Volar, with the compiler built to WebAssembly | Proposed |
| 0026 | One TypeScript "script view" per page for editor intelligence | Proposed |
| 0027 | The language definition says how each attribute is written and what each handler receives | Proposed |
| 0031 | Routes come from file names, layouts wrap folders, and an app is a stack of screens | Accepted |
| 0032 | Transitions are kinds of navigation, and each target plays its own movement | Proposed |
| 0033 | A screen guards itself with guard(...), and screens share state by name | Accepted |
| 0028 | Kit parts are .duo components built into the compiler and imported from @duolith/kit | Proposed |
| 0029 | Language additions the kit needs: conditional classes, bindable props, pieces, roles, disabled and four elements | Proposed |
| 0030 | A small built-in icon set, placed with icon | Proposed |
| 0034 | One overlay element, with a kind, shown in one overlay layer | Proposed |
| 0035 | Overlay parts open with bind:open or a trigger piece; menus take their items as data | Proposed |
| 0036 | toast() is a runtime function from @duolith/client, shown by the kit's Toast region | Proposed |
| 0037 | Navigation keys, Tab stops, spinbutton values and new roles for pickers and tabs | Proposed |
| 0038 | Images load through a runtime cache: one fetch and one decode per address | Proposed |
| 0039 | Chips are toggle buttons; zoom is an image zoomable mode, shown by an ImageViewer part | Proposed |
| 0040 | The kit's navigation parts sit on the router: tabs match the route, a tab bar can become a rail, and three new roles | Proposed |
| 0041 | canGoBack() and backTitle() say whether a screen was pushed, and from what | Accepted |
| 0042 | A project's public/ folder is copied to the site as it is | Proposed |
| 0045 | Native output is ReactLynx, written against an engine adapter; styles become looks | Proposed |
| 0046 | The native output is verified without a device (snapshots, tsc, a Lynx bundle, Lynx for Web); a checklist covers the rest | Proposed |
| 0047 | On native, the engine plays screen transitions and places anchored overlays, and the build makes up for CSS that Lynx drops | Proposed |
| 0048 | On native, effects cross one JSON bridge, and an effect not built for native fails the build | Proposed |
| 0049 | A native build honours each feature or stops with an error, and says how a style opts out of a phone | Proposed |
| 0065 | duolith test builds the project and runs *.test.ts files in Chromium with @duolith/testing | Accepted |
| 0066 | The compiler service gives a page outline; the language server's features come in six checked groups | Accepted |
| 0067 | Editions, and duolith upgrade moves a project to one with migrations | Accepted |
| 0068 | The reference docs are generated from spec/, and the CLI's commands are spec too | Proposed |
| 0069 | duolith dev emits source maps, and our own debug adapter puts breakpoints on page lines | Proposed |
| 0080 | Lint rules are coded warnings, set per project in duolith.yaml, run by duolith lint | Accepted |
| 0050 | Effects are imported by name from @duolith/effects; each contract has an app-facing half and a platform half | Accepted |
| 0051 | Permission declarations are written at build time from the effects an app imports | Accepted |
| 0052 | On the web, secure storage encrypts with a non-extractable key, and sign-in redirects with PKCE | Proposed |
| 0053 | The production adapters run on native with the shell as their host | Accepted |
| 0054 | Native motion, morphs and skeletons live in the engine adapter, not crates/runtime | Accepted |
| 0055 | Elements move by themselves when shows and lists change, and motion= names a preset | Accepted |
| 0056 | Morphs and the back gesture ride on the screen transition | Accepted |
| 0057 | A load directive makes a placed component an island | Accepted |
| 0058 | <boundary> catches failures, and shows its <fallback> with a retry | Accepted |
| 0059 | Skeletons are derived from the layout, or remembered from the last real one | Accepted |
| 0060 | The agent reference (llms.txt and llms/) is generated from spec/ and docs/, and split by topic | Accepted |
| 0061 | The tool server answers through the Duolith command; create is a node command for now | Accepted |
| 0062 | A skill's evaluation is a task, a check and a reference solution, run both ways | Accepted |
| 0070 | Production adapters are one package of ports, imported like the runtime, with two runtime hooks | Accepted |
| 0071 | Consent gates analytics and crash reporting, by category, and honours Global Privacy Control | Proposed |
| 0072 | Translation is t() with ICU messages in locales/<locale>.json, checked at build time | Accepted |
| 0073 | duolith scan gives each npm dependency a verdict for the targets | Proposed |
| 0074 | Crash reports carry the screen, breadcrumbs and frames mapped to .duo files | Proposed |
| 0075 | Rung 0: a file whose expressions are all constants is built as tables | Proposed |
| 0076 | Rung 1 ships source until the spike's timing opens the bytecode gate; rung 2 stays closed | Accepted |
| 0077 | The web keeps keyed list moves in TypeScript; the Rust version is for native | Proposed |
| 0078 | Rust modules live in modules/<name>/, are imported by folder, and are built with wasm-bindgen and UniFFI | Accepted |
| 0079 | duolith build --report writes build-report.json and prints a summary | Accepted |
| 0090 | The docs site is generated from the repository by a small script, not built as a Duolith app | Proposed |
| 0091 | Release names are placeholders until Mik chooses them, and the pipeline is a dry run | Accepted |
| 0092 | One version for everything, worked out from the change notes | Proposed |
| 0095 | Every typed position in markup is checked by TypeScript, through the script view | Accepted |
| 0096 | duolith check runs the real TypeScript checker, and every build and dev server runs it | Proposed |
| 0097 | Pages are checked with the strictest practical TypeScript options | Accepted |
| 0098 | A <match> element for unions, and a resource's states as a union | Accepted |
| 0099 | Paths written as text are checked when the app is built | Proposed |
| 0085 | Editor shells beyond VS Code: LSP4IJ and the TextMate bundle in JetBrains, the HTML tree-sitter grammar elsewhere | Proposed |
| 0100 | Page files are highlighted everywhere from the TextMate and tree-sitter grammars; every registry and upstream submission waits for Mik | Accepted |
| 0101 | The device effects, and how each says a platform cannot | Accepted |
| 0102 | The device effects ask for no more than they use, and the build says what a phone would refuse | Accepted |
| 0103 | Platform looks, and per-part overrides in theme.yaml | Accepted |
| 0104 | A typed API client from an OpenAPI description | Accepted |
| 0105 | Environment files, and a typed environment() | Accepted |
| 0106 | autocomplete on fields, mapped to each platform's autofill | Accepted |
| 0107 | An optimized web build: minified, with hashed names and an import map | Accepted |
| 0108 | Sixteen more kit parts, and the expanded and sorted attributes | Accepted |
| 0109 | The typed client types every part of an operation, or refuses it | Accepted |
| 0121 | on:swipe, and the gesture parts built on it | Accepted |
| 0110 | Every effect is built for native: sign-in, push, purchases and camera on iOS and Android | Accepted |
| 0140 | The app manifest is a group of duolith.yaml, and duolith ship builds store releases from it | Accepted |
| 0141 | Links reach the router through the shell, other sites open in the system, and a dev server reloads the app on a phone | Accepted |
| 0145 | An installed Duolith carries its Node companions, and the templates carry tests | Accepted |
| 0146 | duolith add decides what to add by what the name is, and keeps a package only when it can ship | Accepted |
| 0147 | Tests mock any effect named in effects.yaml, and compare screens with a tolerance | Accepted |
| 0148 | duolith locales extract adds a key for each untranslated text, named after its page | Accepted |
| 0149 | Editors run tests, previews and other project jobs through the Duolith command | Accepted |
| 0150 | A strict Content-Security-Policy on every web build, set in duolith.yaml | Accepted |
| 0151 | The effect bridge has one typed contract, generated for Kotlin and Swift and checked in debug builds | Accepted |
| 0152 | Behaviours: script written once and used from any file's script | Accepted |
| 0160 | Packs: Duolith's and an app's rules and skills, one topic each, proved by the compiler and served to agents | Accepted |
| 0161 | The public name is Duolith, and pages are .duo files | Accepted |
| 0162 | A web build writes each page's HTML, and ships script only where a page runs | Accepted |
| 0163 | A server companion renders on request only what the build cannot write (the server after version 1, its serverless stages in it) | Accepted |
| 0164 | Domain files generate an API's models, validators, client and server wiring (after version 1) | Accepted |
| 0165 | Every server request runs one pipeline, compiled per operation, with templates an app can replace (after version 1) | Accepted |
| 0166 | Transports, live updates and resilience are options on the domain, with measured defaults (after version 1) | Accepted |
| 0167 | A workflow is declared on the domain, checkpointed in the store, and always reaches an end (after version 1) | Accepted |
| 0168 | The build sizes the system, prices it and generates its infrastructure (after version 1) | Accepted |
| 0169 | Any domain, operation or function can be moved to its own server by naming it, and the move is tracked until the old place is retired (after version 1) | Accepted |
| 0170 | The server work is built in full, and proven on one example: a social app and its website (after version 1) | Accepted |
| 0171 | The server is a small core, and every target, store, engine, broker and library is a module, added by the CLI and checked on every upgrade (after version 1) | Accepted |
| 0172 | An agent works in one scope, named by something the build already knows (a domain, an operation, a page, a tier, a server, a module), and a change outside it is refused | Proposed |
| 0173 | Database code, starter domains and an admin are each added by choice, and the framework never requires an ORM (after version 1) | Proposed |