Repository navigation
forgeyard python system architecture
Document type: Dedicated language ecosystem System & Architecture
Project: Forgeyard CI/CD
Subsystem: First-class Python build, test, packaging, reproducibility, dependency resolution, native-extension integration, distribution, and release architecture
Implementation direction: Rust-first Forgeyard core with native integration to the Python ecosystem
Status: Target production architecture
Relationship to Forgeyard: This document defines the dedicated Python subsystem that integrates with Forgeyard's pipeline IR, hermetic build system, scheduler, runners, CAS, functional store, provenance, packaging, distribution, and deployment architecture.
Python looks simple at source level but production CI/CD can become highly mutable because Python projects often depend on:
- interpreter version;
- interpreter implementation;
- ABI;
- platform tag;
- wheel compatibility;
- sdist build behavior;
-
pyproject.toml; - PEP 517 build backends;
- build-system requirements;
- dependency resolver behavior;
- index state;
- private package indexes;
- wheel availability;
- native C/C++/Rust extensions;
- system libraries;
- virtual environment state;
- global site-packages;
- editable installs;
- environment variables;
- package-manager caches;
- generated code;
- platform-specific dependencies;
- lockfile semantics;
- dynamic project metadata;
- build-time network access;
- setuptools/distutils legacy behavior;
- manylinux/musllinux compatibility;
- macOS deployment targets;
- Windows CRT/toolchain behavior.
Forgeyard therefore needs a dedicated Python subsystem whose central rule is:
A Python build is defined by source + interpreter + ABI/platform contract + dependency lock graph + build backend + packaging configuration + native-extension closure + controlled environment.
Forgeyard Python MUST:
- support CPython as the primary interpreter;
- permit PyPy or additional implementations through adapters;
- support
pyproject.toml; - support PEP 517 build isolation;
- support wheels and sdists;
- support uv as a preferred first-class modern resolver/installer;
- support pip;
- support Poetry;
- support
requirements*.txt; - support lockfile-oriented workflows;
- support virtual environments;
- support workspaces/monorepos where tooling permits;
- support private indexes;
- support fully offline builds after input fetching;
- support native C/C++ extensions;
- support Rust/PyO3/maturin extensions;
- support Linux manylinux/musllinux packaging;
- support Windows wheels;
- support macOS wheels;
- support cross-platform test matrices;
- support pytest;
- support unittest;
- support typing with mypy/pyright adapters;
- support linting/formatting with Ruff and other tools;
- support coverage;
- support property testing;
- support reproducible wheels and source distributions;
- support SBOM/provenance;
- support deterministic package promotion;
- support local-first and distributed Forgeyard modes.
Forgeyard does not replace:
- CPython;
- uv;
- pip;
- Poetry;
- setuptools;
- Hatchling;
- Flit;
- PDM;
- maturin;
- pytest;
- Ruff;
- mypy;
- Pyright.
Forgeyard resolves, locks, isolates, verifies, caches, packages, and orchestrates these tools.
flowchart TB
Src["Python Source"]
Detect["Python Detector"]
Model["PythonProjectSpec"]
Py["Interpreter Resolver"]
Dep["Dependency Resolver"]
BuildSys["Build Backend Resolver"]
Native["Native Extension Resolver"]
Lock["Python Lock Graph"]
Graph["Build/Test Graph"]
Sched["Forgeyard Scheduler"]
Runner["Python Runner"]
Sand["Hermetic Sandbox"]
Build["Python Build Adapter"]
Tests["Tests / Typing / Lint / Coverage"]
CAS["Forgeyard CAS + Functional Store"]
Repro["Reproducibility Verifier"]
Pack["Wheel / sdist / App Packaging"]
Prov["SBOM / Provenance / Signing"]
Dist["Promotion / Distribution"]
Src --> Detect
Detect --> Model
Model --> Py
Model --> Dep
Model --> BuildSys
Model --> Native
Py --> Lock
Dep --> Lock
BuildSys --> Lock
Native --> Lock
Lock --> Graph
Graph --> Sched
Sched --> Runner
Runner --> Sand
Sand --> Build
Build --> Tests
Build --> CAS
Tests --> CAS
CAS --> Repro
Repro --> Pack
Pack --> Prov
Prov --> Dist
crates/
├── forgeyard-python/
├── forgeyard-python-model/
├── forgeyard-python-detect/
├── forgeyard-python-interpreter/
├── forgeyard-python-lock/
├── forgeyard-python-resolver/
├── forgeyard-python-uv/
├── forgeyard-python-pip/
├── forgeyard-python-poetry/
├── forgeyard-python-build/
├── forgeyard-python-pep517/
├── forgeyard-python-wheel/
├── forgeyard-python-sdist/
├── forgeyard-python-native/
├── forgeyard-python-maturin/
├── forgeyard-python-test/
├── forgeyard-python-analysis/
├── forgeyard-python-coverage/
├── forgeyard-python-package/
└── forgeyard-python-provenance/
pub struct PythonProjectSpec {
pub source: SourceRef,
pub interpreter: PythonInterpreterRequest,
pub project_metadata: PythonProjectMetadata,
pub dependencies: PythonDependencyPolicy,
pub build_backend: PythonBuildBackendSpec,
pub build_platform: BuildPlatform,
pub target_platform: TargetPlatform,
pub native_extensions: NativeExtensionPolicy,
pub testing: PythonTestPolicy,
pub typing: TypingPolicy,
pub analysis: PythonAnalysisPolicy,
pub reproducibility: ReproducibilityPolicy,
}pub enum PythonImplementation {
CPython,
PyPy,
Other(String),
}
pub struct PythonVersion(String);
pub struct PythonAbiTag(String);
pub struct PythonPlatformTag(String);
pub struct PythonInterpreterId(Digest);
pub struct PythonLockGraphId(Digest);Detect:
pyproject.toml
setup.py
setup.cfg
requirements.txt
requirements-*.txt
uv.lock
poetry.lock
Pipfile.lock
tox.ini
pytest.ini
mypy.ini
ruff.toml
.pylintrc
Detection produces evidence; explicit Forgeyard configuration remains authoritative.
pub struct PythonDetection {
pub pyproject: bool,
pub build_backend: Option<DetectedBuildBackend>,
pub lockfiles: Vec<DetectedPythonLockfile>,
pub requirement_files: Vec<VirtualPath>,
pub native_extension_risk: DetectionState,
pub test_frameworks: Vec<DetectedTestFramework>,
}Interpreter version string alone is insufficient.
Identity should include:
implementation
version
binary
stdlib
ABI
platform
build configuration
runtime shared library where relevant
Logical identity:
PythonInterpreterId = H(interpreter closure)
First-class CPython support.
Record:
major/minor/micro version
ABI flags/tag
platform
stdlib identity
libpython if present
build options where relevant
Optional adapter.
Treat PyPy as separate implementation/ABI.
Never reuse CPython native wheels blindly.
pub enum PythonInterpreterMode {
LockedManaged,
PlatformProvided,
AuditedHost,
}Preferred CI:
LockedManaged
pub enum PythonInterpreterTrust {
Unverified,
DigestVerified,
VendorVerified,
OrganizationApproved,
Revoked,
}This is the central project metadata/configuration source.
Forgeyard records relevant sections:
[build-system]
[project]
[project.optional-dependencies]
[project.scripts]
[project.entry-points]
tool-specific sections
The exact file digest is also part of source identity.
Model:
backend name
backend package/version
backend dependencies
backend config settings
Common adapters:
setuptools.build_meta
hatchling
flit_core
pdm-backend
maturin
poetry-core
custom PEP 517 backend
PEP 517 build environment is created hermetically.
Build requirements are resolved/fetched before build.
No global site-packages.
BuildBackendId =
H(
backend package closure,
config,
Python interpreter,
build-system requirements
)
Supported modes:
uv lock
Poetry lock
pip requirements with hashes/constraints
Forgeyard-generated immutable resolution
vendor/wheelhouse
Strict release prefers an immutable resolved dependency graph.
Make uv a first-class preferred integration because it supports fast modern Python environment and package workflows.
Forgeyard should still remain independent from uv's implementation details.
Record:
uv binary/version/digest
uv.lock digest
Python interpreter constraint
resolved packages
index/source metadata
Strict build uses frozen/locked behavior.
Support pip as a first-class compatibility path.
Strict pip workflows should prefer:
constraints
hashes
wheelhouse
offline install
rather than mutable resolution during build.
Record:
Poetry version
poetry.lock
pyproject.toml
groups/extras
source indexes
Poetry's environment/cache is not authoritative.
Support:
requirements.txt
requirements-dev.txt
constraints.txt
but production-grade reproducibility should require exact pins and preferably hashes.
Outer Forgeyard lock:
interpreter identity
dependency graph identity
build backend identity
source package/wheel identities
native toolchain identities
python: (
interpreter: (
implementation: CPython,
version: "3.x.y",
digest: "blake3:...",
),
resolver: (
kind: Uv,
digest: "blake3:...",
),
lock_graph: "blake3:...",
)Support:
PyPI-compatible index
private index
direct URL
Git/VCS
local path
workspace package
vendored wheel/sdist
All mutable inputs are resolved into immutable content.
Separate:
public package index
private index
organization mirror
air-gap mirror
Enterprise can deny direct public fetch.
Credentials are fetch-stage secrets.
They do not enter the build environment or artifact identity.
Lock:
URL
expected digest
package metadata
Remote byte changes cause verification failure.
Resolve:
repository
requested revision
commit
tree/content digest
Production builds never follow moving branches.
Local package path resolves inside source snapshot.
Never depend on arbitrary external host directories.
root project
↓
direct dependencies
↓
transitive packages
↓
platform/python-version markers
The resolved graph is target/interpreter-sensitive.
Python dependency selection can depend on:
python_version
platform_system
platform_machine
implementation_name
extra
These conditions are part of derivation identity.
Selected extras are explicit:
pub struct PythonExtras(BTreeSet<String>);Changing extras changes dependency closure.
Development/test/docs groups are separate from runtime dependencies.
Do not ship dev tooling in runtime environments unless required.
Forgeyard prefers wheels for installation when trusted/compatible.
If only sdist exists:
sdist
↓
PEP 517 build derivation
↓
wheel
↓
immutable wheel object
Wheel filename contains semantic tags, but Forgeyard identity is content digest.
Record:
distribution
version
python tag
ABI tag
platform tag
content digest
Forgeyard validates wheel tags against target interpreter/platform.
Never install incompatible wheels because filenames superficially match.
Typically:
py3-none-any
or related compatible tags.
Still lock wheel content.
Platform-specific.
Examples:
manylinux
musllinux
win_amd64
macosx_...
Native toolchain/platform identity matters.
Python extensions may use:
C
C++
Cython
Rust/PyO3
Fortran
other native toolchains
Forgeyard must model them explicitly.
Use Forgeyard C/C++ subsystem for:
compiler
linker
sysroot
native libraries
runtime linkage
Use Forgeyard Rust subsystem for:
rustc
cargo
Cargo.lock
target
PyO3/maturin build
First-class adapter for Rust-backed Python wheels.
Record:
maturin binary
Rust toolchain
Cargo lock
Python interpreter/ABI
wheel target
Cython version and generated C/C++ source are build inputs.
Generated code may be:
committed and verified
or
generated in a dedicated build stage
After building an extension:
.so / .pyd / dylib-related object
validate dynamic dependencies using Forgeyard C/C++ linkage subsystem.
Strict Python build sees:
locked interpreter
dependency wheel/sdist closure
isolated virtual environment
build backend
native toolchains if needed
controlled cache
source snapshot
It does not see:
system site-packages
user site-packages
developer virtualenv
global pip config
arbitrary compiler
random `/usr/local` libraries
Forgeyard controls:
PATH
HOME
VIRTUAL_ENV
PYTHONHOME where appropriate
PYTHONPATH
PYTHONNOUSERSITE
PIP_CONFIG_FILE
PIP_CACHE_DIR
UV_CACHE_DIR
POETRY_CACHE_DIR
TMPDIR
LANG
TZ
SOURCE_DATE_EPOCH
and native build variables as required.
Strict mode does not inherit host PYTHONPATH.
Project source paths are explicitly configured.
Set/ensure:
PYTHONNOUSERSITE
or equivalent isolation policy.
User-installed packages must never affect CI.
Virtualenv is a materialized environment, not dependency truth.
Identity comes from:
interpreter
locked dependency graph
installation policy
Virtualenv may be recreated at any time.
Can be cached as acceleration if keyed strongly.
Do not rely on arbitrary developer .venv.
Editable installs are useful for development/testing.
Release packaging should validate normal built distributions too.
Editable behavior is never assumed equivalent to installed wheel behavior.
Standard path:
source
↓
PEP 517 isolated build
↓
wheel/sdist
↓
content hash
Source distribution should be deterministic.
Normalize:
file ordering
timestamps
ownership/permissions where format supports it
generated metadata
Potential nondeterminism:
ZIP timestamps
file ordering
generated metadata
native linker output
build paths
generated C/Rust code
Forgeyard verifies actual wheel content independently.
Wheel RECORD integrity data must correspond to final package contents.
Forgeyard validates wheel structure before publication.
Validate:
METADATA
WHEEL
entry_points
top-level packages
RECORD
license files
If project metadata is computed dynamically, the tool/backend performing that computation is part of derivation identity.
Avoid environment-derived version surprises.
Recommended deterministic source:
explicit version
or
immutable VCS-derived version
Avoid wall-clock/random version generation for release packages.
If used, Forgeyard supplies immutable source revision metadata.
Do not depend on arbitrary Git state outside source snapshot.
Release default:
dirty source = denied
Local mode may allow dirty snapshot with content digest.
Release build default:
network = denied
after dependency/build requirements are fetched.
[build-system].requires dependencies are fetched and locked before realization.
Build backend cannot silently fetch new packages.
resolver/download cache
wheel cache
virtualenv cache
test cache
Forgeyard action cache
Forgeyard CAS
All have different semantics.
Disposable acceleration.
Never a source of dependency identity.
Same principle.
Forgeyard may prewarm/manage it but correctness rests on locked artifacts.
High-assurance model:
resolved wheel/sdist closure
↓
Forgeyard immutable wheelhouse
↓
offline install
Bundle:
Python interpreter
resolver/installer
wheel/sdist closure
build backend packages
native toolchains
source
lock graph
Then build/test offline.
First-class:
pytest
unittest
doctest adapters
tox/nox adapters
Track:
pytest version
plugins
config
markers
selected extras
pytest plugins are dependencies and can execute arbitrary code.
pub struct PythonTestPlan {
pub runner: PythonTestRunner,
pub environments: Vec<PythonTestEnvironment>,
pub shards: u32,
pub coverage: CoveragePolicy,
pub timeout: Duration,
}Common library CI:
3.x
3.y
3.z
Each interpreter version is a distinct derivation/test environment.
For native packages:
Linux
Windows
macOS
and architecture variants.
Optional adapter.
Forgeyard may consume tox environment definitions.
But Forgeyard scheduler remains authoritative.
Same principle.
Sessions become Forgeyard test/task plans where practical.
Shard by:
test files
packages
markers
historical duration
while preserving fixtures/ordering requirements.
Forgeyard should record retries separately.
A passing retry must not erase the initial failure.
Support:
coverage.py
pytest-cov
native-extension coverage adapters
Coverage data is evidence, not build identity.
Normalize paths across runners.
Merge shards only if source/interpreter/test configuration matches.
First-class adapters:
mypy
Pyright
basedpyright
Tool version/config participates in analysis action identity.
Track:
mypy version
config
plugins
Python target version
typeshed/dependency stubs
Track:
Pyright binary/package identity
config
Python target
type stubs
Preferred first-class:
Ruff
plus adapters for:
Pylint
Flake8
custom tools
Track:
Ruff binary/version
config
target Python version
selected rules
Support verification:
ruff format
Black
CI reports a diff rather than mutating source.
Ruff/isort adapters.
Again, verification stage should not silently rewrite release source.
Hypothesis-based tests are ordinary test evidence.
Seeds/examples are recorded when failures occur.
Python fuzz adapters can exist, especially for parsers/native extensions.
Fuzzing is separate evidence, not package identity.
Potential integrations:
dependency vulnerability scanner
Bandit adapter
Semgrep adapter
native-extension security analysis
Tools are locked.
Each package source has trust state:
Unverified
HashVerified
IndexVerified
OrganizationApproved
Revoked
Forgeyard should flag:
private/public namespace collisions
new package source
unexpected index
direct URL additions
VCS dependency changes
Example:
requests 2.x -> 3.x
4 transitive packages changed
1 sdist introduced
1 native wheel introduced
index changed
license changed
sdist requires executing a build backend.
Policy can prefer wheels and flag new sdist builds for review.
Record:
compiler
linker
sysroot
native dependencies
Python ABI
platform tag
Linux wheel builds must explicitly model compatibility policy.
Forgeyard should use controlled manylinux-compatible build environments where required.
Treat musllinux separately from manylinux/glibc.
Do not label both generically as Linux.
Model:
architecture
libc family
compatibility baseline
Python ABI
Model:
Windows architecture
Python ABI
MSVC/native runtime requirements
Native extension build integrates with Forgeyard C/C++ Windows toolchain.
Model:
architecture
deployment target
Python ABI
universal2 policy where used
Native build requires macOS runner/toolchain as appropriate.
If producing universal2 wheel, both architecture slices/toolchain behavior are explicit.
Adapters may use ecosystem-standard repair tools.
The tool binary/version is locked.
Repair is a separate deterministic packaging derivation.
Any rewritten/bundled native libraries must be validated after repair.
Potential:
wheel
zipapp
PEX adapter
shiv adapter
container image
Forgeyard native app bundle
These are separate package adapters.
Recommended:
immutable wheel/application artifact
+
runtime dependency closure
+
runtime config
+
secrets
Do not install unpinned packages at deployment time.
Use immutable base image digest.
Prefer installing from Forgeyard wheelhouse rather than live PyPI.
source
↓
wheel/app artifact X
↓
test X
↓
reproduce X
↓
stage X
↓
production X
Publishing to PyPI/private index is separate from build.
verified immutable wheel/sdist
↓
approval
↓
publish exact files
Never rebuild during publish.
pub struct PythonReleaseManifest {
pub version: Version,
pub distributions: Vec<PythonDistributionRef>,
pub sbom: Digest,
pub provenance: Digest,
}Same derivation:
Runner A -> wheel X
Runner B -> wheel Y
Compare actual package content.
For pure Python wheels, bit-for-bit should often be achievable.
Native wheels depend on native toolchain reproducibility.
Potential:
different physical runner
different pool
same interpreter/toolchain/target identity
Quarantine package.
Inspect:
wheel ZIP metadata
METADATA/WHEEL
native libraries
build paths
generated source
timestamps
VCS metadata
sdist can also be independently reproduced and compared.
Synthetic HOME prevents:
pip.conf
.pypirc
Poetry user config
global credentials
user site-packages
from silently affecting build.
Project-local config is source input.
User-global config is ignored in strict mode.
Secrets are supplied through fetch policy only.
Build-time variables affecting output are explicit.
Runtime secrets/config must not become wheel identity unless intentionally baked.
For tests/tools where deterministic hash iteration matters, Forgeyard may set a deterministic value.
Do not claim this alone makes application behavior deterministic.
Strict defaults:
LANG=C.UTF-8
LC_ALL=C.UTF-8
TZ=UTC
unless explicitly configured.
Use stable virtual source/build roots.
Native compilers receive prefix-map rules through C/C++ integration where supported.
Examples:
protobuf stubs
OpenAPI clients
Cython output
ORM generated files
version files
Generator identity is explicit.
If generated files are committed:
regenerate
↓
diff
↓
fail if stale
.pyc is generally deployment/runtime cache, not source identity.
Forgeyard package policy should avoid treating arbitrary host-generated bytecode as authoritative unless deliberately produced.
Validate:
console_scripts
gui_scripts
plugin entry points
against installed package content.
After building/installing wheel in clean environment:
import package
run CLI --help/version
as configured.
fresh virtualenv
↓
install wheel from Forgeyard wheelhouse
↓
no network
↓
import/smoke test
This directly tests package completeness.
Separate:
runtime
test
typecheck
lint
docs
build
to avoid giant universal environments.
Forgeyard may cache environments by immutable environment identity.
InterpreterId
+
DependencyGraphId
+
selected groups/extras
Good candidates:
test shards
typecheck
lint
wheel builds
platform wheel matrix
pub struct PythonRunnerCapabilities {
pub interpreters: Vec<PythonInterpreterId>,
pub platforms: Vec<PythonPlatform>,
pub native_toolchains: Vec<CppToolchainId>,
pub rust_toolchains: Vec<RustToolchainId>,
pub sandbox: SandboxCapabilities,
}Filter by:
interpreter/ABI
target platform
native compiler requirement
Rust extension requirement
macOS/Windows native wheel requirement
trust tier
memory
Score:
wheelhouse locality
interpreter locality
native toolchain locality
cache warmth
queue delay
resource headroom
Prefetch:
Python interpreters
common wheels
build backends
native toolchains
For pure-Python library:
full Python-version matrix
+
one or two primary OSes
For native extension:
Python version x OS x architecture
matrix is materially larger.
Use package/module/test mapping where reliable.
Python import dynamics limit certainty.
If uncertain:
run broader safe set
Support multiple Python packages/projects within one repository.
Each package gets:
source root
pyproject
dependency graph
build/test targets
Local package dependencies resolve to immutable repository paths/content.
Can use historical duration to balance shards.
Preserve fixtures/session dependencies.
Record:
initial failure
retry count
final state
Never erase flakiness evidence.
Support:
pytest-benchmark adapter
pyperf adapter
custom benchmarks
Use dedicated stable runner class.
Record:
CPU
Python interpreter
OS
native dependencies
runner class
Dedicated Python panels:
Interpreter
ABI/platform
Dependency graph
Build backend
Wheel matrix
Native extensions
Tests
Typing
Lint
Coverage
Reproducibility
Package contents
Show:
implementation
version
ABI
platform
digest
trust
Show:
package
version
source
wheel/sdist
hash
direct/transitive
runtime/dev group
native-extension marker
Show wheel targets:
Python tag
ABI tag
platform tag
build status
reproducibility status
Display:
extension
language
compiler/toolchain
runtime linkage
wheel targets
Recommended:
forgeyard python detect
forgeyard python lock
forgeyard python fetch
forgeyard python env
forgeyard python build
forgeyard python wheel
forgeyard python sdist
forgeyard python test
forgeyard python typecheck
forgeyard python lint
forgeyard python format-check
forgeyard python coverage
forgeyard python analyze
forgeyard python reproduce
forgeyard python package
forgeyard python explain
forgeyard python explain-rebuild
forgeyard python deps
forgeyard python interpreter
Shows:
interpreter
ABI
resolver
lock graph
build backend
selected extras/groups
native extensions
wheel target
sandbox
cache
Examples:
Python interpreter changed
uv.lock changed
build backend changed
extra selected
platform tag changed
native compiler changed
Cython changed
pub enum PythonFailure {
DetectionFailure,
InterpreterFailure,
LockFailure,
DependencyResolutionFailure,
FetchFailure,
BuildBackendFailure,
WheelBuildFailure,
SdistBuildFailure,
NativeExtensionFailure,
TestFailure,
TypingFailure,
AnalysisFailure,
PackagingFailure,
ReproducibilityFailure,
}pub struct PythonDiagnostic {
pub severity: Severity,
pub tool: ToolIdentity,
pub package: Option<String>,
pub file: Option<VirtualPath>,
pub line: Option<u32>,
pub message: String,
}Python dependency unavailable offline
package:
example-lib==1.2.3
required artifact:
source distribution
suggestion:
forgeyard python fetch
Native extension hermeticity violation
attempted library:
/usr/local/lib/libfoo.so
reason:
outside declared native closure
forgeyard python dev
provides:
interpreter
locked dependency groups
test tools
type checker
linter
build backend
matching CI identity.
Export:
interpreter path
virtual environment
typing config
project roots
for editors/IDEs.
Standalone Forgeyard supports:
interpreter resolution
dependency fetch
environment materialization
build
test
wheel/sdist
package
without remote services.
daemon
↓
Python task
↓
remote runner
↓
interpreter + wheelhouse
↓
build/test
↓
CAS
Adds:
private package mirror
approved interpreter mirror
signed lock approval
OIDC/RBAC
wheel build farm
independent reproducers
multi-region CAS
air-gap support
Potential gates:
hash required
untrusted index denied
new sdist flagged
native extension flagged
private/public collision denied
revoked dependency denied
Combine:
locked Python dependency graph
built distributions
native runtime closure
interpreter identity
Record:
source digest
pyproject digest
lock graph
interpreter ID
build backend ID
resolver ID
selected extras/groups
wheel target
native toolchain if used
output digest
runner
sandbox policy
wheel
sdist
zipapp
PEX adapter
container
native application bundle adapter
Forgeyard package
For libraries:
wheel set
sdist
SBOM
provenance
signatures
For apps:
application artifact
runtime dependency closure
interpreter/runtime requirement
config schema
SBOM/provenance
Use immutable base images.
Install from Forgeyard wheelhouse offline.
Avoid live package resolution inside Dockerfile during release assembly.
source
↓
wheel/app artifact X
↓
test X
↓
reproduce X
↓
stage X
↓
production X
Recommended:
locked interpreter
locked resolver
locked dependency graph
PEP 517 isolation
offline build
synthetic HOME
no user site-packages
no ambient PYTHONPATH
private credentials fetch-only
native toolchains locked
clean install verification
independent reproduction
May allow:
warm caches
editable install
dirty source
reduced matrix
with visible reproducibility status.
Forgeyard should detect/reject:
global site-packages leakage
ambient PYTHONPATH
ambient pip/Poetry config
unlocked index resolution
live network during release build
local path dependency outside source snapshot
unhashed direct URL
unexpected sdist execution
native extension using host compiler/library
incompatible wheel tag
stale lockfile
dynamic wall-clock version
rebuilding artifact during publish
detect
↓
lock verification
↓
format check
↓
lint
↓
typecheck
↓
unit tests
↓
wheel build
↓
clean install smoke test
Python version matrix
x
primary OS matrix
Native projects expand OS/architecture coverage.
full interpreter matrix
full platform tests
coverage
security analysis
native wheel matrix
dependency vulnerability refresh
reproducibility sampling
clean source
↓
locked interpreter/resolver
↓
offline dependency closure
↓
PEP 517 wheel/sdist build
↓
test built wheel in clean env
↓
typing/lint/security evidence
↓
native linkage validation if needed
↓
independent reproduction
↓
SBOM/provenance
↓
sign
↓
publish/promote exact package bytes
Implement:
PythonProjectSpec
pyproject detection
build backend detection
lockfile detection
native extension detection
Exit:
Forgeyard accurately describes common Python repositories.
Implement:
CPython import/store
InterpreterId
ABI/platform model
toolchain trust
Implement:
uv adapter
pip compatibility
private index fetch
wheel/sdist store
offline installation
Implement:
build-system requirements
isolated build environment
wheel
sdist
metadata validation
Implement:
pytest
unittest
Ruff
mypy
Pyright adapter
coverage
Integrate:
C/C++ extensions
Cython
maturin/PyO3
native linkage validation
Implement:
manylinux
musllinux
Windows
macOS
wheel repair/validation
Implement:
deterministic wheel/sdist policies
content comparison
independent rebuild
quarantine
Implement:
release manifest
PyPI/private-index publisher
OCI
application bundles
promotion
Implement:
wheelhouse locality
test sharding
wheel build farms
interpreter prewarming
multi-platform scheduling
- Remove host Python: locked interpreter build succeeds.
- Change global site-packages: strict build unchanged.
- Change ambient
PYTHONPATH: strict build unchanged. - Change pip/Poetry user config: strict build unchanged.
- Disable network after fetch: install/build succeeds.
- Change interpreter micro version: derivation changes.
- Change lockfile: dependency graph changes.
- Direct URL content changes: digest verification fails.
- Local path outside source snapshot: strict build rejects.
- New sdist requires undeclared build dependency: build fails before hidden fetch.
- Native extension uses
/usr/local/lib: strict build rejects. - Wheel platform tag incompatible: install validation fails.
- Clean virtualenv installs built wheel without network.
- Independent runner reproduces pure-Python wheel.
- Reproducer mismatch quarantines wheel.
- Publishing uses exact verified wheel digest.
- Native wheel compiler change changes derivation.
-
pyproject.tomlbuild backend change changes derivation.
Do not call Python support production-ready until:
interpreter identity is stable
uv/pip lock workflows are correct
private indexes work securely
offline installation works
PEP 517 isolation is correct
user/global Python state cannot leak
wheel compatibility validation works
native extensions integrate with C/C++/Rust
manylinux/musllinux distinctions are correct
Windows/macOS wheel builds are tested
clean-install verification works
reproducibility verifier detects wheel differences
publish pipeline never rebuilds artifacts
- Python version string alone is not interpreter identity.
- Strict release does not resolve dependency versions from live indexes.
-
pyproject.tomland lock state are explicit build inputs. - Build-system requirements are locked before PEP 517 build.
- Global/user site-packages are never trusted CI inputs.
- Ambient
PYTHONPATHis denied in strict mode. - Virtual environments are materializations, not dependency truth.
- Wheel/sdist content is cryptographically identified.
- sdist builds are isolated and explicit.
- Native extensions introduce native toolchain identity.
- Rust extensions introduce Rust toolchain identity.
- Wheel compatibility tags are validated.
- Private-index credentials are fetch-only secrets.
- Generated code is explicit.
- Release versions must be deterministic.
- Built wheel is tested in a clean install environment.
- Reproducibility compares actual distribution bytes/content.
- Publishing promotes exact verified files.
- Cache layers are disposable acceleration.
- Correctness takes precedence over minimizing test/build work.
Python Project
│
▼
Forgeyard Python Detector
│
▼
PythonProjectSpec
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
Interpreter Resolver Dependency Resolver Build Backend Resolver
│ │ │
└──────────────────────┼──────────────────────┘
▼
Immutable Python Lock
│
▼
Build / Test / Wheel Graph
│
▼
Forgeyard Scheduler
│
▼
Hermetic Python Runner
│
┌────────────┼────────────┐
▼ ▼ ▼
PEP 517 Tests Type/Lint
│ │ │
└────────────┼────────────┘
▼
Native Extension Validation
when applicable
│
▼
Wheel / sdist Output
│
▼
Independent Reproducer
│
▼
Clean Install Verification
│
▼
SBOM / Provenance / Sign
│
▼
Forgeyard Distribution
For a pure Python project:
Source snapshot
+
Python interpreter
+
ABI/platform contract
+
pyproject.toml
+
dependency lock graph
+
resolver/installer
+
PEP 517 build backend
+
selected extras/groups
+
controlled environment
+
hermetic sandbox
=
Python derivation
For native extensions:
Python derivation
+
C/C++ or Rust toolchain
+
native sysroot
+
native dependency closure
+
Python ABI
=
native Python derivation
A trustworthy release requires:
Derivation
↓
offline hermetic dependency installation
↓
isolated PEP 517 build
↓
actual wheel/sdist digest
↓
clean-install tests
↓
typing / lint / tests / coverage/security evidence
↓
native linkage validation when required
↓
independent reproduction
↓
SBOM + provenance
↓
signature
↓
publication/promotion of identical files
This gives Forgeyard a Python subsystem that is fast and developer-friendly while preventing global site-packages, mutable indexes, ambient virtualenv state, hidden native libraries, uncontrolled build backends, and other common "works on my machine" failure modes.
(
python_release_policy: (
source: (
dirty_tree: Denied,
),
interpreter: (
locked: Required,
),
dependencies: (
locked: Required,
hashes: RequiredWhereSupported,
build_network: Denied,
),
environment: (
user_site_packages: Denied,
ambient_pythonpath: Denied,
user_package_manager_config: Denied,
),
pep517: (
isolation: Required,
build_requirements_locked: Required,
),
native_extensions: (
toolchain_locked: RequiredWhenPresent,
runtime_linkage_validation: RequiredWhenPresent,
),
verification: (
clean_install_test: Required,
),
reproducibility: (
independent_rebuilds: 1,
distinct_host: true,
comparison: BitForBitOrNormalizedDistribution,
),
release: (
sbom: Required,
provenance: Required,
signing: Required,
rebuild_on_publish: Denied,
),
),
)python: (
interpreter: Locked("cpython"),
dependencies: Uv(
lockfile: "uv.lock",
frozen: true,
),
build_backend: FromPyProject,
testing: (
runner: Pytest,
),
analysis: (
lint: Ruff,
typing: Mypy,
),
reproducibility: (
network: Denied,
independent_rebuilds: 1,
),
)python: (
interpreter: Locked("cpython"),
native_extension: (
kind: Cpp,
toolchain: Locked("clang-linux-x86_64"),
sysroot: Locked("manylinux-sysroot"),
),
wheel_target: (
python_tag: "cp3xx",
abi_tag: "cp3xx",
platform: "manylinux_x86_64",
),
)| Area | First-class |
|---|---|
| Interpreter | CPython |
| Additional interpreter | PyPy adapter |
| Resolver/install | uv, pip |
| Project manager | Poetry adapter |
| Metadata/build |
pyproject.toml, PEP 517 |
| Build backends | setuptools, Hatchling, Flit, maturin, custom PEP 517 |
| Packaging | wheel, sdist |
| Testing | pytest, unittest |
| Typing | mypy, Pyright adapter |
| Lint/format | Ruff, Black adapter |
| Coverage | coverage.py / pytest-cov |
| Native C/C++ | Forgeyard C/C++ subsystem |
| Native Rust | Forgeyard Rust/maturin integration |
| Linux wheels | manylinux, musllinux |
| Windows wheels | CPython ABI + MSVC/native closure |
| macOS wheels | deployment target + architecture |
| Reproducibility | offline hermetic build + independent distribution rebuild |
Forgeyard CI/CD & Build Platform · Wiki Index · GitHub Repository · Architecture Specifications
All architecture specifications are released under project governance guidelines.
Core Foundations & Source Domain
Storage, CAS & Data Plane
- Storage & Metadata
- CAS & Artifact Data Plane
- Cache Architecture, Build Acceleration, Remote Cache & Cache Correctness
- Data Lifecycle, Retention, Archival, Deletion, Legal Hold & Privacy Governance
- Artifact Registry, Package Repository, OCI Distribution & Internal Software Distribution
- Database Schema Migration, Online Backfill, Data Transformation & Zero-Downtime Change Orchestration
Pipeline Engine, IR, State Machine & Scheduling
- Pipeline IR, Parsing, Normalization & Planning
- Run / Job State Machine
- Scheduler
- Events, Event Delivery & Reconciliation
- Pipeline Triggers, Schedules, Manual Dispatch & Event-Driven Execution
- Workflow Concurrency, Distributed Locks, Idempotency Keys, Reservations & Exclusive Resource Coordination
- Job Checkpointing, Suspend/Resume, Preemption, Graceful Cancellation & Spot/Interruptible Runner Recovery
Runners, Sandboxing, Transport & Fleet Orchestration
- Runner / Agent
- Sandbox & Executor
- Transport, QUIC & Internal Protocol
- Device Lab
- Runner Fleet Autoscaling, Capacity Provisioning & Infrastructure Provider
- Runner Image Factory, Golden Image, Patch Management & Fleet Baseline Attestation
- Network Connectivity, Private Resource Access, Egress Control, Tunneling & Zero-Trust Service Connectivity
Security, Policy, Secrets & Supply Chain
Packaging, Releases, Deployment & Delivery
- Packaging
- Release
- Deployment
- Release Distribution, Update Delivery, Installer, Channel & Client Update
- Environment Promotion, Progressive Delivery, Feature Rollout, Canary Analysis & Automated Rollback Governance
- Artifact Promotion Policy, Release Train, Environment Channel & Lifecycle Governance
- Hermetic Build, Functional Packaging & Reproducible Distribution
Observability, Diagnostics, Testing & Quality
- Observability, Health & Doctor
- Search, Indexing, Query & Operational Analytics
- Test Results, Quality Gates, Coverage & Flaky-Test Intelligence
- Benchmarking, Performance Regression, Load-Test & Capacity Intelligence
- Static Analysis, Code Quality, Security Scanning & Findings Management
- Failure Diagnosis, Debugging, Reproduction, Bisect & Root-Cause Intelligence
- Reliability Engineering, SLO, Error Budget, Availability & Resilience Governance
- Test Data, Fixtures, Ephemeral Databases, Service Virtualization & Integration-Test Environment
- Incident Management, On-Call, Escalation, Response Coordination & Postmortem
API, UI, DevEx & Service Portal
- API / Axum
- Dioxus UI / GUI
- Developer Experience, Local Dev Environment, CLI Workflows & Reproducible Workstation
- Workflow Templates, Reusable Pipelines, Organization Standards & Golden Paths
- Service Catalog, Component Ownership, Environment Inventory & Developer Portal
- API/ABI/Schema/Protocol Compatibility, Contract Evolution & Breaking-Change Governance
- Remote Development Environments, Cloud Workspaces, Codespaces-Style Sessions & Developer Workspace Orchestration
Distributed Coordination, Federation & Operations
- SCM Provider Integrations
- High Availability, Coordination & Raft
- Remote Build Execution (RBE) Interoperability
- Plugin & Extension
- Operations, Backup, Upgrade & Disaster Recovery
- Self-Hosting, Bootstrap & Release-of-Forgeyard
- Notifications, Alerting & Human Workflow
- Entitlements, Licensing, Subscription & Commercial Access-Control
- Monorepo Intelligence, Dependency Graph, Affected-Change & Incremental Execution
- Dependency, Package Registry, Artifact Mirror & Software-Source Governance
- Configuration, Feature Flags, Runtime Settings & Dynamic Configuration Governance
- Cost Accounting, FinOps, Chargeback/Showback & Resource Economics
- CI/CD Migration, Import, Compatibility & Legacy-System Interoperability
- Multi-Region Federation, Edge Sites, Disconnected Operation & Cross-Site Replication
- Infrastructure-as-Code, Environment Provisioning, Preview Environments & Drift Reconciliation
- Merge Queue, Speculative Integration, Batch Validation & Protected Target Submission
- AI-Assisted CI Optimization, Engineering Copilot & Autonomous Recommendation Governance
- Build Graph Replay, Historical Reproducibility, Time-Travel CI & Evidence Reconstruction
- Change Risk Assessment, Preflight Simulation, Policy Preview & What-If Analysis
- Configuration Drift Detection, Desired-State Convergence, Runtime Reconciliation & Environment Consistency
- Dependency Update Automation, Version Maintenance, Vulnerability Remediation & Upgrade Campaign