Skip to content

Design

Design records for Comline — the why behind a decision and the state of its rollout, not a usage guide. For how to use a feature, see the Guide.

Each page carries a status and links the issues / PRs that carry it out.

Decisions

  • Consumer generation configuration — where generated code goes and who owns that choice (config.idp vs comline.toml).
  • Multi-version generation — emitting bindings for several historical package versions at once. Implemented.
  • IR freezing & the version state — freezing into .comline/, automatic versioning, and the comline clean redesign. Partly implemented.
  • Codegen by language — worked examples of one schema across Rust, Python, TypeScript, Luau. Sketch.
  • Validators — validator declarations and the @validators field annotation: the intended shape and what has to change to get there. Not implemented.
  • Generation — what codegen / libgen / runtime each mean, moving the generators out of core, and the generation repo de-rot plan. Partly built.
  • Runtime & generation repository structure — how to keep the runtime and libgen trees from getting heavy as languages are added. Decided — one repo per target language (Option E); reverses the earlier phased plan.
  • The core ↔ target contract — the boundary every comline-<lang> repo builds against: schema IR, config IR, the codegen contract, the core-runtime API, the FFI ABI. Draft.
  • Playground & tutorial — an in-browser, real-time compile / codegen / runtime demo, and the WASM vs compile-server question behind it. Discussion.
  • Playground simulation — Phase 1 — wiring two protocol instances over @comline/runtime's in-memory transport, with a frame inspector: the buildable plan for the "simulate machines" demo. Built (Phase 1).
  • Playground simulation — Phase 2 — many connections, fault injection, a virtual clock, record & replay, sandboxed user behaviours, and route A (the real generated module in the browser). The staged plan for everything Phase 1 deferred. Planned.
  • Brand assets — ComlineProject/brand as the single source of truth for the mark and colours, and how consumers vendor a pinned copy. In use.