CDIN Backend

The headless coordinator between the CDIN Kernel, Runtime and Frontends.

CDIN Backend is the native core that hosts the Kernel and Runtime, provides operating-system services, manages editor sessions, and connects Frontends. It is written in C11 and is designed to run without a display toolkit or an attached Frontend.

What is Backend?

When a user edits a document, the Backend connects the parts that need to work together. It does not decide what an editor command means and it does not draw the screen. Its job is to host the components that do those things and provide the services they need.

The parts of CDIN have separate responsibilities:

Part	Responsibility
Frontend	Receives input and displays the editor. It owns pixels, terminal cells, visual layout and drawing.
Runtime	Coordinates commands, key bindings, views, settings, extensions and the semantic UI model.
Backend	Owns the session, hosts Kernel and Runtime, provides OS services, and relays Frontend Protocol messages.
Kernel	Owns document bytes, edits, versions, snapshots, notifications and undo/redo history.

This separation prevents the Backend or Runtime from keeping a second, authoritative copy of document contents. Kernel operations go through the Kernel's public C ABI, and only the Backend's Kernel adapter includes the Kernel header.

Current status

This repository contains Backend library version 1.2.0, the shared Frontend Protocol 1.0.0 codec/server, reusable OS/job services, Kernel adapter, PUC Lua 5.4 bridge, Runtime UI-model projection, owner-thread inbound event dispatcher, version-pinned line-read service, Headless Frontend harness and integration workflows. It is not yet a complete runnable CDIN editor: the paired Runtime 1.0.0-rc.1 source now advertises the required Frontend Protocol 1.0.0, but live Lua + Kernel integration, concrete Unix Socket/Windows Named Pipe transport, and the complete native OS matrix remain release gates.

The CDIN specification is the source of truth for cross-project contracts. This README describes the current state of this repository; it does not override the specification. See Spec traceability for the exact requirements and decisions that shape the implementation.

Try it

You need a C11 compiler, GNU Make or CMake, curl, and pkg-config. On Windows, use the MSYS2 UCRT64 environment and its matching compiler and build tools.

Clone the repository and install the pinned Kernel binary package:

git clone https://github.com/cdin-editor/backend.git
cd backend
make deps

The dependency installer downloads the matching release archive, verifies its SHA-256 checksum, and installs headers and libraries under .deps/kernel/. The source of cdin/kernel is not copied into this repository and no sibling Kernel checkout is needed.

Run the tests and build the library:

make services
make e2e
make all
make integration

make services builds the reusable OS/job library without Kernel. make e2e runs real filesystem, process and concurrency workflows. make integration links against the installed Kernel and tests Backend session behavior plus real document operations such as replace, transaction, undo/redo, snapshots, notifications and search. For the complete local gate, install markdownlint-cli2 and run:

make check

CI and releases run through m-mdy-m/pipeline. The task graph is in pipeline.toml; see Build and test.

A small example

A Backend object is created first, then started. This minimal example disables Lua so it can be used to verify the native Kernel connection without requiring a Lua development package:

#include "cdin/backend.h"

int main(void)
{
    cdin_backend_config config;
    cdin_backend *backend = NULL;

    cdin_backend_config_init(&config);
    config.enable_lua = 0;
    config.enable_headless_protocol = 0;

    if (cdin_backend_create(&config, &backend) != CDIN_BACKEND_OK) return 1;
    if (cdin_backend_start(backend) != CDIN_BACKEND_OK) {
        cdin_backend_destroy(backend);
        return 1;
    }

    /* The application pumps Backend work from this same owner thread. */
    if (cdin_backend_shutdown(backend, 0) != CDIN_BACKEND_OK) {
        cdin_backend_destroy(backend);
        return 1;
    }
    cdin_backend_destroy(backend);
    return 0;
}

The full source and link commands are in the Getting started guide. A static Backend archive does not contain Kernel code; the final executable links the Backend and the Kernel package. pkg-config --static --libs cdin-kernel returns the Kernel and its private logger link requirements together.

What it provides

• Backend lifecycle, session identity and document/view metadata.
• A single Kernel ABI adapter with ABI/feature checks, handle mapping and error detail translation.
• A Runtime Host bridge, with Lua state owned by the Backend's creating thread.
• An optional trusted extension source resolver, disabled unless an application configures an administrator-managed root; nested modules remain confined to each extension namespace and source/module/aggregate reads are bounded.
• Bounded worker queues and owner-thread completion delivery.
• Portable path, bounded binary-safe file reads, atomic filesystem writes, clock, thread and argument-vector process services.
• In-process Frontend handshake, Driver/Observer roles, bounded input/output queues, atomic UI snapshots, ui.flush groups, acknowledgements and backpressure.
• Runtime UI Model projection and owner-thread inbound event dispatch.
• Version-pinned view.request_lines service backed by Kernel Snapshots and the public Kernel line APIs.
• Kernel-owned logging, with Backend diagnostics routed through the Kernel log API rather than a second logger.

Native Backend messages use stable component prefixes such as [BACKEND][CORE], [BACKEND][SESSION], [BACKEND][PROTOCOL], [BACKEND][JOBS], [BACKEND][RUNTIME] and [BACKEND][KERNEL]. Each record includes its source file, line and function. Configure log_level to TRACE, DEBUG, INFO, WARN, ERROR or FATAL when diagnosing startup, queue pressure, Frontend handshakes or shutdown.

Documentation

Guide	What it covers
Getting started	Build the library and use the first Backend lifecycle.
Dependencies	Download, checksum verification and linking of the Kernel binary package.
Architecture	Module ownership, thread model and lifecycle.
Runtime Host API	Services exposed to the Lua Runtime.
Extension resolver	Trusted extension source layout, path confinement, opt-in configuration and read limits.
Frontend Protocol	Message schemas, UI projection, inbound dispatch, line reads and transport limits.
OS services	Files, paths, processes, jobs, clocks and thread primitives.
Reuse services	Use the standalone cdin_backend_services library in other projects.
Integration testing	Real-world E2E and Kernel integration scenarios.
Spec traceability	Exact requirement and open-decision references in source and docs.
Development guide	Build, test, lint, Pipeline and gix workflow.
Known limitations	Behavior that is incomplete or remains controlled by open Spec decisions.
Changelog	Changes recorded for each version.

CDIN ecosystem

Backend is one part of CDIN. These repositories describe the neighboring projects:

Project	Role
CDIN	The editor application and composition root.
Kernel	The binary-safe document and text engine.
Runtime	The Lua editor-behavior layer.
Specification	Shared contracts and architecture decisions.
Pipeline	Reusable task runner and CI workflows.
gix	Repository branch-flow tooling.

Contributing

Focused bug fixes, tests, documentation improvements and portability work are welcome. Read CONTRIBUTING.md before changing a component boundary or a cross-project contract. Public APIs and implementation choices must remain traceable to the Spec; open decisions must not be treated as accepted design.

License

GNU GPL v3 or later — see LICENSE. Third-party dependencies retain their own licenses; see NOTICE.