feat: decouple Fournos from FORGE — multi-engine support

[ashtarkb]

Summary

Make Fournos engine-agnostic so any execution engine (not just FORGE) can run on the platform. Introduces two modes: a built-in generic pipeline (zero-code path) and a custom engine contract (/opt/fournos/entrypoint).

This is the Fournos-side counterpart to the FORGE entrypoint contract work (ashtarkb/forge#2).

Motivation

Previously, Fournos was tightly coupled to FORGE:

• The resolve Job template (config/forge/resolve_job.yaml) contained ~90 lines of inline FORGE-specific bash
• The deploy Makefile target applied FORGE workflows
• Settings, docs, and code all referenced FORGE as the only engine

This meant only FORGE jobs could run on Fournos. Teams with simpler workloads (e.g. a Python benchmark script in a container) had to build a full FORGE project just to use Fournos scheduling.

Architecture

After this change, Fournos supports two modes:

Mode 1: Generic Pipeline (zero Fournos code in your project)

Users provide only a container image + FournosJob YAML:

spec:
  pipeline: fournos-generic
  executionEngine:
    generic:
      image: quay.io/myteam/my-job:latest
      command: ["python", "run.py"]
      env: { MODEL: gpt-4, RATE: "10" }

The built-in runner creates a child K8s Job with the user's container. No SDK, no /opt/fournos/entrypoint, no Tekton Pipeline to write.

Mode 2: Custom Engine (advanced, e.g. FORGE)

Engines provide their own Tekton Pipeline/Task and a container image with /opt/fournos/entrypoint. Full lifecycle control. spec.executionEngine.<name> is opaque to Fournos.

---

Changes

Core: Engine-agnostic resolve template

• Deleted config/forge/resolve_job.yaml (90 lines of inline FORGE bash)
• New config/resolve/resolve_job.yaml — engine-agnostic template that just calls command: ["/opt/fournos/entrypoint"]. The image is selected per-Pipeline via fournos.dev/resolve-image annotation.
• Modified fournos/settings.py — default path: config/forge/ → config/resolve/
• Modified fournos/core/resolve.py — docstring updated to reflect engine-agnostic semantics
• Modified fournos/core/tekton.py — set serviceAccountName: fournos on PipelineRun taskRunTemplate

Built-in generic pipeline (config/generic/)

File	Purpose
pipeline.yaml	fournos-generic Tekton Pipeline — references fournos-generic-step Task
task.yaml	fournos-generic-step Tekton Task — runs the runner image
runner.py	Generic runner: fetches FournosJob spec, reads spec.executionEngine.generic.*, creates child K8s Job, polls for completion, streams logs, cleans up
Containerfile	Runner image: UBI9 + oc CLI + PyYAML + runner.py → /opt/fournos/entrypoint
rbac.yaml	ClusterRole: read FournosJobs, create/manage child Jobs, stream pod logs, common workload resources
requirements.txt	PyYAML dependency

Optional Engine SDK (fournos/sdk/engine.py)

• FournosEngine class with @on_resolve / @on_run decorators
• Handles all plumbing: env var reading, FournosJob fetch, config extraction from spec.executionEngine.<engine_name>, resolve/run routing, error handling
• EngineContext dataclass with fjob_name, namespace, step, artifact_dir, fjob_spec
• For advanced engines that want Python integration — most users will never need this

Contract documentation (docs/execution-engine-contract.md)

• Formalizes Mode 1 (generic) and Mode 2 (custom engine)
• Documents /opt/fournos/entrypoint requirements, environment variables, resolve phase behavior
• References the optional SDK

Dev/test infrastructure

• dev/mock-resolve/Dockerfile — now creates /opt/fournos/entrypoint symlink (matches production contract)
• dev/mock-resolve/resolve_job.yaml — explicit command: ["/opt/fournos/entrypoint"] + missing env vars
• dev/mock-generic/ — new directory: mock runner image, mock user image, sample FournosJob for local kind testing
• dev/setup.sh — +110 lines: builds/loads mock generic images, applies generic Pipeline/Task/RBAC to kind
• Makefile — deploy target now applies generic assets instead of FORGE workflows; new dev-test-generic target

Documentation updates

• README.md — updated quick-start, deployment instructions, settings table, added generic pipeline docs
• Fournos_Design_Document.md — rewritten Sections 7-8 for multi-engine architecture

File inventory

File	Status
config/forge/resolve_job.yaml	🔴 Deleted
config/resolve/resolve_job.yaml	🟢 New
config/generic/pipeline.yaml	🟢 New
config/generic/task.yaml	🟢 New
config/generic/runner.py	🟢 New
config/generic/Containerfile	🟢 New
config/generic/rbac.yaml	🟢 New
config/generic/requirements.txt	🟢 New
fournos/sdk/__init__.py	🟢 New
fournos/sdk/engine.py	🟢 New
docs/execution-engine-contract.md	🟢 New
dev/mock-generic/* (5 files)	🟢 New
fournos/settings.py	🟡 Modified
fournos/core/resolve.py	🟡 Modified
fournos/core/tekton.py	🟡 Modified
dev/mock-resolve/Dockerfile	🟡 Modified
dev/mock-resolve/resolve_job.yaml	🟡 Modified
dev/setup.sh	🟡 Modified
Makefile	🟡 Modified
Fournos_Design_Document.md	🟡 Modified
README.md	🟡 Modified

Key metrics

Metric	Value
Lines of FORGE bash removed from Fournos	~90
Lines of FORGE code remaining in Fournos	0
Engine modes supported	2 (generic + custom)
New files	16
Modified files	9
Deleted files	1