[Epic] Embeddable engine: stable contracts for front-ends, orchestrators and CI dashboards that drive ForgeLM #1027

Closed as not planned (2026-10-20). The six sub-issues were triaged into the existing wave epics, so this epic is no longer needed; the closing comment says where each one went. The principles and the stage order below remain the design background those issues cite.

Epic · Embeddable engine · 6 sub-issues (EMB-01 … EMB-06)

Scope

ForgeLM is a headless, config-driven engine: a GUI or web application is out of scope for this repository (product strategy, "What ForgeLM Is NOT"). A separate program can still drive it — a desktop or web front-end, a pipeline dashboard, a chat-ops bot — and on 2026-10-20 the project owner decided that any such front-end will be a new application built on top of ForgeLM, not a feature added to it.

That only works if the engine offers contracts a program can rely on without scraping human-readable output. A review of development at 2059b59 against that use case found six gaps. Each has its own issue with the evidence, the proposed design, the alternatives that were rejected and acceptance criteria.

Principles every sub-issue follows

1. The engine never depends on a front-end. A need raised by a front-end enters ForgeLM only as a general library, CLI or config feature with tests and documentation. There is no UI code, UI-specific flag or UI-only behaviour in this repository.
2. Additive by default. New CLI flags, config fields, JSON keys and events are MINOR changes (release.md). Exit codes 0–6, the --output-format json envelope and the meaning of existing audit events do not change.
3. New code goes in new small modules. forgelm/trainer.py and forgelm/compliance.py are over the module-size ceiling with no-growth budgets (their splits are Split forgelm/trainer.py into a sub-package (_kwargs, _runtime, _finalize, _artifacts) — deferred until Phase 16 S4 and S8 have landed #904 and Split forgelm/compliance.py into a sub-package (_audit_log, _annex_iv, _provenance, _gdpr) — deferred until Phase 16 S9 has landed #906); the new behaviour lives in new modules and the existing files gain only the lines that attach it.
4. Config-driven and opt-in. Behaviour is chosen by validated YAML fields with unchanged defaults; no environment-variable sniffing for behaviour.
5. Proved on all three desktop platforms. Each contract is tested on Linux, macOS and Windows. Today Windows and macOS tests run only when a release tag is pushed (Tests run on Windows and macOS only when a release tag is pushed #962); that job is a dependency of EMB-03.
6. Documented in English and Turkish in the same pull request, with the CI guards the project already has.

When: stages and the reason for the order

Sequencing is driven by which files Phase 16 steps still own (trainer.py: S4, S8; compliance.py: S8, S9 — S2 and S3 have landed) and by decision "behaviour before contracts before docs".

Recommendation for a first front-end (MVP): EMB-01 (Experimental tier) + EMB-03 + EMB-06 are the minimum; EMB-02 is strongly advised because a front-end needs a Stop button. EMB-04 and EMB-05 widen trust and platform reach but do not block an MVP.

How to work on it

Claim one sub-issue at a time (see CONTRIBUTING, Finding Work). Each sub-issue states its own acceptance criteria and open design decisions; the decisions are recorded as dated rows in docs/roadmap/risks-and-decisions.md before the code lands.

Done when

• Every sub-issue is closed (done, or closed with a reason).
• docs/guides/embedding.md (and its Turkish mirror) describes only contracts that exist and are tested.

_{Raised on 2026-10-20 from an architecture decision (ForgeLM stays a headless engine; front-ends are separate programs built on it). Code links point at 2059b59 on development; line numbers may have moved. Tracking IDs EMB-01 … EMB-06 are stable references for commits and pull requests.}