GERC (gerc crate)

gerc is the Rust lowering and emission layer in the parc -> linc -> gerc toolchain.

It produces Rust-facing output from translated C-side inputs:

• a RustProjection
• emitted Rust source
• emitted crate directories and build.rs
• raw rustc link arguments
• metadata sidecars for downstream consumers

Scoped Production Statement

The current Level 1 production claim for the whole pipeline is:

• Linux/ELF-first
• canonical-corpus-backed
• conservative rejection of unsupported layouts and declarations

For GERC specifically, that means:

• production-ready for the documented source-only and evidence-aware canonical corpus
• not a claim that every native surface lowers cleanly
• not a claim that every rejected declaration family is a bug

Level 1 Support Matrix

Area	Level 1 status	Notes
source-only lowering on canonical corpus	primary production scope	zlib, libpng, sqlite3, and support-tier anchors are the core floor.
evidence-aware Linux/ELF lowering	primary production scope	This is the intended first production path.
Apple framework lowering	secondary confidence scope	Good proof surface, not the primary production claim.
Windows system-library lowering	secondary confidence scope	Good proof surface, not the primary production claim.
bitfield-bearing records	rejected	Explicit rejection is part of the contract.
incomplete but pointer-safe opaque families	supported	Supported as opaque-pointer-compatible lowering.
incomplete embedded layout-sensitive families	rejected	Honest layout is required.

What GERC Actually Exposes Today

The crate is source-first, but its public API is not only generate() plus a few helpers.

It currently exposes:

• GercInput, GercConfig, GercOutput, and the root generation helpers
• staged gate and lower modules
• a large crate-owned C-side model in gerc::c
• emission and crate-writing helpers
• consumer/sidecar helpers

The docs need to match that breadth rather than flattening everything into one perfectly clean layer.

Responsibilities

• intake of GERC-owned source and evidence contracts
• conservative gating of declarations
• lowering into RustProjection
• deterministic Rust source emission
• crate/build output generation
• Cargo and raw rustc link metadata rendering

Non-responsibilities

• parsing or preprocessing C source
• direct native binary inspection
• inventing missing ABI facts
• runtime loader policy
• library-level dependency on parc or linc

Boundary

gerc/src/** must stay independent from parc and linc.

Cross-package translation belongs in tests, examples, or external harnesses. The library consumes its own input model and emits its own artifacts.

Fastest Working Paths

Source-first generation:

use gerc::{generate_from_source, emit_source, GercConfig};
use gerc::{SourceDeclaration, SourceFunction, SourcePackage, SourceType};

let mut source = SourcePackage::default();
source.declarations.push(SourceDeclaration::Function(SourceFunction {
    name: "demo_init".into(),
    parameters: vec![],
    return_type: SourceType::Int,
    variadic: false,
    source_offset: None,
}));

let output = generate_from_source(source, &GercConfig::new("demo_sys")).unwrap();
println!("{}", emit_source(&output.projection));

Staged workflow:

use gerc::gate::gate_package;
use gerc::lower::lower_package;

That staged flow is still public and tested.

Artifact Boundary

gerc owns its own lowering and emission model plus the emitted build-side artifacts.

The durable boundaries are:

• the crate-owned intake model in gerc::c
• emitted Rust source
• emitted crate directories and build.rs
• rendered raw rustc link-argument files
• metadata sidecars for downstream consumers

Cross-package translation still belongs outside gerc/src/**. GERC can be used in integration tests and harnesses, but its library code is not where upstream parc or linc wiring should live.

Tested Scope

The suite covers:

• source-only generation
• evidence-aware generation
• staged gate/lower usage
• root API re-exports
• emitted crate output
• raw rustc argument output
• larger fixture surfaces and artifact-boundary tests
• OpenSSL, libpng, and combined Linux event-loop link-directive generation
• explicit gate, lowering, and pipeline failure matrices

The tests are the best statement of what GERC actually supports.

Level 1 Contract

For the Level 1 production claim, GERC's contract is:

• supported families lower deterministically on the named canonical corpus
• evidence-aware lowering may expand support beyond source-only mode
• explicitly rejected families remain rejected until an honest representation strategy exists
• conservative rejection is part of the production contract, not a temporary defect marker

Hardening Matrix

The current hardening ladder is easiest to read in four buckets:

• hermetic vendored baselines
  • source-only zlib lowering
  • source-only libpng lowering
  • emitted crate output on deterministic vendored surfaces
• host-dependent evidence ladders
  • OpenSSL link-directive generation
  • libcurl link-directive generation
  • libxml2 link-directive generation
  • combined Linux event-loop link-directive generation
• failure and conservative-lowering surfaces
  • anonymous-type fallback and rejection paths
  • incomplete-handle support for pointer-only opaque families
  • packed struct and packed union acceptance when representation evidence is explicit
  • bitfield-bearing record rejection when representation would be unsound
  • keyword-safe placeholder emission for unresolved named types
  • unsupported layout and ABI-sensitive gating
  • source-only degradation when link evidence is absent
  • explicit gate, lowering, and pipeline failure matrices
• determinism anchors
  • source-only sqlite3 projection
  • source-only zlib projection
  • source-only libpng projection
  • libxml2 link directives when available
  • OpenSSL link directives when available
  • Apple framework link directives
  • Windows system-library link directives
  • combined Linux event-loop link directives

Read those as the current confidence anchors, not as a claim that every native surface lowers equally well today.

Release Gates

gerc should only be treated as release-ready when all of these remain green:

• make build
• make test
• source-only suites
• evidence-aware suites
• emitted-crate output checks
• raw rustc argument checks
• incomplete-handle source-only support checks
• framework-link evidence support checks
• packed-union acceptance checks
• keyword-safe placeholder emission checks
• sqlite3 emitted-crate checks
• at least one OpenSSL-style host-dependent evidence target
• at least one libxml2-style host-dependent evidence target
• at least one libcurl-style host-dependent API target
• at least one Apple framework target
• at least one Windows system-library target
• at least one combined Linux/system link-directive target

The Level 1 production floor is the hermetic subset of those gates:

• source-only zlib
• source-only libpng
• source-only sqlite3
• emitted crate output from deterministic fixtures
• source-only pointer-only opaque-handle lowering
• packed-union acceptance checks
• keyword-safe placeholder emission checks

The host-dependent confidence-raise layer is:

• OpenSSL link directives
• libxml2 link directives
• libcurl link directives
• Apple framework link directives
• Windows system-library link directives
• combined Linux event-loop link directives

The current canonical generation surfaces are:

• source-only zlib
• source-only libpng
• source-only sqlite3
• source-only support-tier widget fixture
• emitted crate output from deterministic fixtures
• OpenSSL link directives
• libxml2 link directives
• Apple framework link directives
• Windows system-library link directives
• libcurl link directives
• combined Linux event-loop link directives

Canonical Corpus

The current GERC production corpus is intentionally named:

• hermetic vendored
  • source-only zlib
  • source-only libpng
  • source-only sqlite3
  • deterministic emitted-crate checks on vendored fixtures
• hermetic support-tier anchors
  • source-only supported widget fixture
  • source-only rejected bitfield fixture
  • evidence-aware link-plan fixture
  • pointer-only incomplete-handle fixture
  • keyword-placeholder emission fixture
• host-dependent raises
  • OpenSSL evidence-aware generation
  • libxml2 evidence-aware generation
  • Apple framework evidence-aware generation
  • Windows system-library evidence-aware generation
  • combined Linux event-loop evidence-aware generation
• conservative-failure anchors
  • anonymous-type rejection ledger
  • explicit gate/lower/pipeline failure matrices

Those are the generation surfaces GERC should be judged against first.

Build And Test

make build
make test