Products / Binary formats
Three file engines. Separate contracts. A shared engineering discipline.
A monorepo containing the active ICFG configuration, ILOG log-container and IUPD update-package engines, together with native C99 code, .NET libraries and tools, tests, vectors and build infrastructure.
IronFamily.FileEngine develops binary formats for three different jobs while keeping each format's structure and validation rules explicit.
ICFG represents configuration data. ILOG packages log or stream payloads with profile-dependent layers. IUPD represents update packages and their validation and application flow. The monorepo gives these engines common build infrastructure, host tooling, tests and vector assets; it does not turn them into one format or one API.
The canonical native direction is portable C99. The .NET 8 code remains a substantial part of the system: repository scope documents assign it host tooling, reference behavior, vector generation, tests, parity support and bindings support. It is not merely a wrapper around C.
docs/ARCHITECTURE_SCOPE.md names ICFG, ILOG and IUPD as the active engine set.The repository treats each engine as its own format, validation problem and current implementation surface.
ICFG is the configuration format. Its public C API exposes ironcfg_open, fast and strict validation, and zero-copy accessors for the root object, schema and optional string pool.
The compatibility document records a .NET writer that emits version 2 and a .NET reader that accepts versions 1 and 2. The C header under libs/ironcfg-c exposes version-1 constants, so the managed version rule does not imply the same support in C.
ILOG organizes log or stream data through a file header and table of contents, with optional index, archive and seal layers. Documented profiles distinguish minimal, integrity, searchable, archived and audited layouts.
The current .NET implementation documents a version-1 surface. A C reader API and native validation tests are present; implementation notes and tests remain the authority for what each C path checks.
IUPD models package headers, chunk tables, manifests, apply order, payloads and profile-dependent integrity or signature material. The .NET reader accepts v1 and v2 while its writer emits v2.
The native strict verifier in native/ironfamily_c is a separate C99 surface focused on v2 verification. Its header documents a fail-closed profile whitelist of SECURE or OPTIMIZED. Incremental update application is exposed through adjacent native helpers with its own constraints.
These summaries describe repository surfaces. They do not assert full feature equivalence or a shared support level for every profile.
The architecture is easiest to understand by following where code lives and what each surface is responsible for.
The C build makes this division concrete: IronFamily::ICFG and IronFamily::ILOG are built from libs/ironcfg-c; IronFamily::IUPD comes from native/ironfamily_c. The older in-memory IUPD compatibility API under libs/ironcfg-c is separately opt-in and is not the same verifier.
Native code is a set of C99 targets, not one all-format library that mirrors every .NET capability.
libs/ironcfg-c builds IronFamily::ICFG and IronFamily::ILOG. Their C headers expose buffer-based validation and views.native/ironfamily_c builds the IronFamily::IUPD verifier and adjacent IUPD metadata, delta and OTA apply helpers.iron_reader_t callback, file size, 32-byte Ed25519 public key and expected minimum update sequence. It returns a verification error and writes the extracted sequence on success.iron_error_t err = iron_iupd_verify_strict(
&reader,
package_size,
public_key_32,
expected_min_sequence,
&verified_sequence
);
if (err != IRON_OK) {
/* Reject package; policy stays with caller. */
}The native tree uses CMake 3.20+, C99 with extensions disabled, and exports installable CMake targets. First-party targets can opt into strict warnings (/W4 /WX on MSVC or -Wall -Wextra -Wpedantic -Werror on GCC/Clang) and sanitizer instrumentation where supported. These are development options; ordinary consumers are not forced to use them.
The managed tree contains engine work as well as developer-facing tooling.
Repository scope assigns .NET roles including host tooling, reference implementation, vector generation, parity support and bindings support. The solution also contains separate managed projects for core IronConfig, common code, ILOG and tooling, with .NET 8 as their declared target.
Tests cover readers, writers, profiles, compatibility paths, malformed data, signatures and update application. The tools/megabench tree contains dataset validators and benchmark runners; reproduction scripts and stored baselines are present. This is measurement infrastructure, not a performance claim. Read any result with its dataset, runner and baseline.
Use the .NET API contract for managed consumers. Use the matching C header and native tests to establish the C surface. Shared names and vectors do not erase differences in implementation scope.
The repository stores small vectors by format and additional success/refusal vectors for incremental updates, with manifests and tests that refer to those artifacts.
A particular implementation accepts, rejects or decodes fixture bytes according to a tested expectation. Negative fixtures can target malformed structures or refusal cases.
They do not prove every operation, profile, limit, writer or failure mode is equivalent across .NET and native C. The repository requires explicit tests or gates for parity claims.
The evidence workflow runs a selected-claim verifier. Its behavior-test step is currently commented out because of API mismatches; the verifier and broader regression test command are separate steps. This page therefore describes configured checks, not universal parity success.
The compatibility document distinguishes writer and reader versions and keeps native APIs separate.
| Engine | Managed behavior documented | Native surface | Boundary |
|---|---|---|---|
| ICFG | .NET writer emits v2; .NET reader accepts v1 and v2. | Public C API under libs/ironcfg-c; header carries version-1 constants. | Do not infer C v2 support from the managed reader rule. |
| ILOG | Current implementation docs describe a version-1 surface. | Buffer-backed C reader API and native validation tests are present. | Interpret profiles against implementation docs and tests. |
| IUPD | .NET reader accepts v1/v2; writer emits v2. | Strict verifier is a v2 surface; an older C in-memory API is compatibility-only and opt-in. | Native verifier profile support is narrower than the .NET matrix. |
Public breaking changes should be recorded in CHANGELOG.md. Historical formats are outside active supported-engine scope. The release process requires inspecting actual tags and repository state before making release claims.
The security document scopes active work to parsing untrusted configuration, validating log containers and verifying/applying update packages under explicit rules.
ICFG and ILOG expose validation paths intended to reject malformed files. Structural and integrity checks are format-specific; a successful parse is not a general trust decision.
CRC32 and BLAKE3 appear in documented profiles. They detect changes according to coverage; CRC32 and an unkeyed hash do not authenticate a producer.
The strict native IUPD verifier checks Ed25519 signature material for its accepted v2 path and enforces package limits. Sequence enforcement depends on signed transcript coverage; its header says a positive minimum with an unauthenticated sequence fails closed.
OpenSSL is not required by the default native build. Optional legacy codec builds may require it. Historical codec code is outside the active security model for ICFG, ILOG and IUPD.
Workflow files show what is wired into CI. A configured gate is not a report that the latest run passed.
No hardware-validation result is claimed. The files audited define build, test, vector and tooling paths; they do not establish validation on a named production device.
Use the .NET solution for managed libraries and tests; use the native CMake tree for C99 targets.
dotnet restore libs/ironconfig-dotnet/IronConfig.sln
dotnet build libs/ironconfig-dotnet/IronConfig.sln -c Release --no-restore
dotnet test libs/ironconfig-dotnet/IronConfig.sln -c Release --no-buildcmake -S native -B native/build
cmake --build native/build --config Release
ctest --test-dir native/build -C Release --output-on-failurecmake --install native/build --config Release --prefix <install-prefix>
# Consumer configuration:
cmake -S <consumer-source> -B <consumer-build> \
-DIronFamily_DIR=<install-prefix>/lib/cmake/IronFamilyThe install exports CMake targets and a package config for find_package(IronFamily CONFIG REQUIRED). The default native build does not require OpenSSL. Enabling optional historical codec targets can require it, so the complete repository is not dependency-free.
This view follows docs/IMPLEMENTATION_STATUS.md, architecture and compatibility documents audited on 18 September 2026.
The .NET solution, tests and host tooling are present. Scope documents assign managed code reference, vector and tooling roles.
libs/ironcfg-c exposes ICFG/ILOG libraries; native/ironfamily_c exposes IUPD verification and adjacent helpers. Scope differs by engine.
There is no repository-wide equivalence claim. Each parity statement needs a named test or gate for its exact API, profile and behavior.
Historical codecs are outside active supported engines. The older C IUPD API is opt-in and not the strict native v2 verifier.