PCFC11 / PyCForge integration agreement
Recorded 2026-10-24; compiler checkpoint 0.2.8

Status and purpose

This is the agreed future product plan. Implementation follows compiler quality,
performance and application validation. This source package does not install
PCFC11, modify PyCForge, or contain the planned installers. PyCForge is distributed
independently of GitHub; this plan requires no GitHub repository or service.

PyCForge should provide a dependable path from successful Python-to-C conversion
to a compiled program, with PCFC11 included in the product. Keep PyCForge's
single-wheel installation model. Include two installer payloads, initially for
native Windows x64 and Linux x86-64, and select the matching payload at setup.
Both use the same PCFC11 source release. Define and test supported OS/runtime
versions; these two payloads do not imply ARM64 or macOS support. Measure the
combined download/install size and validate package compatibility metadata.

IDE behavior

Place PCFC11 COMPILE immediately to the right of TRANSPILE. Its left-side icon
is an eagle's talon/foot gripping a python head, drawn as a bold silhouette that
remains legible at button size. Keep the text label and accessible button name.

Enable the button after a successful conversion of the current source bundle.
Disable it after a failed conversion, when no generated C is available, or when
the primary source or a participating module changes. Use the existing bundle
identity and freshness checks. Prevent duplicate setup/build operations.

Successful conversion enables the button even before PCFC11 is installed.
On click, verify the configured compiler, supported architecture, version/process
API, and working assembly/linking tools. If setup is needed, show the PCFC11
installation/configuration dialog and use the included host installer. Record
the resulting configuration automatically, then return to the build workflow.
Cancellation or failure must leave a clear, recoverable state.

Use a dedicated PCFC11 build route. Remove PCFC11 from the existing general
compiler-choice list when this integration lands; retain the other compiler
choices. Reuse the existing build service and source-mapped diagnostics. Provide
output selection and an entry-function choice where needed; successful C
conversion alone does not guarantee an executable entry point. Object output
remains available where appropriate. Preserve prior output on failed builds and
invalidate results if the source changes. Compilation does not automatically run
the generated program. Remember suitable settings for later compilations.

Windows package and handoff

CC supplies a native Windows ZIP from the agreed release: pcfc11.exe, its entire
matching include/ directory, build/toolchain version information, license and
provenance files, and the native Windows feedback ZIP. Use a prepared collection
script to gather the toolchain payload and dependency inventory; do not require
CC to identify DLLs and library dependencies manually.

Prepare the Windows installer definition and packaging/build instructions around
that payload. Build and validate the final installer on Windows, using CC's
machine or an explicitly selected Windows build environment. Start with ordinary
per-user installation and automatic PyCForge configuration.

Bundle a tested native x64 MinGW-w64/UCRT toolchain with its required assembler,
linker, libraries, headers and supporting DLLs, preserving its directory layout.
Invoke its executables through configured paths. Users should not have to set
up the full MSYS2 shell/package-management environment or locate gcc.exe by hand.
Keep version compatibility and redistribution materials with the payload.
The public-release signing approach is a later packaging decision.

Linux package

Prepare the Linux compiler build, matching headers, install/remove scripts,
toolchain checks and PyCForge configuration from the same source release.
Initially use the supported distribution's native GCC-compatible tools and C
development files, with guided setup when they are missing. This route can
require distribution packages, network access and package-manager permissions.
Install PCFC11 in a user application directory where practical.

A fully self-contained, offline Linux toolchain has not been agreed or validated.
Decide that requirement explicitly before promising offline compilation on a
clean machine. It would require a defined distribution/libc baseline and its own
complete dependency payload and portability tests. Including both PCFC11
installers in the wheel does not by itself settle that dependency decision.

Installation and release checks

Installers should identify compatible existing installations, support recovery
from interrupted setup and controlled upgrades, and provide removal behavior
that does not delete user projects or unrelated compiler installations. Verify
payload integrity and record the actual compiler/toolchain versions. Configure
the build process directly so it does not depend on an unrelated global PATH.
Run a small compile-and-link verification before declaring setup successful.

Validate both installers on clean supported systems, followed by actual
PyCForge GUI conversion and compilation, multi-module freshness checks, output
preservation, paths with spaces/Unicode, cancellation, upgrade and removal.
Test generated programs and their runtime dependencies separately from the
compiler installation. Windows release testing includes native execution;
Linux instruction models cannot replace it. Keep quality gates in
RELEASE_TESTING.txt and the remaining compiler work in docs/ROADMAP.md.

Current evidence and next work

PCFC11 0.2.8 passes the supplied 20-phase native Windows standalone run, including
130 bit-field layouts, all 49 PyCForge C fixtures and 207 robustness cases.
Linux self-compilation and other release evidence are retained. This establishes
a tested compiler checkpoint, not completed integration or full C11 conformance.
The division-performance gap, broader mixed-feature conversion workloads,
remaining language/library/ABI audits and native application checks precede
final bundling. Record later changes to this agreement here.

0.2.9 development checkpoint: reduce O1 scalar initialization overhead and
retain the compiler regression/self-compilation/sanitizer gates. Native Windows
0.2.9 validation is pending. The installer and IDE agreement above is unchanged;
this compiler release does not implement or publish the integration.
