OPERATION AND ASSURANCE

CLI and Python API

The command line, desktop workspace, and public Python API call the same converter and preserve the same complete-unit acceptance contract.

Command-line interface

# Convert and atomically write C
pycforge convert input.py --output generated.c

# Emit the structured result as JSON
pycforge --format json convert input.py

# Validate source without publishing C to a destination
pycforge validate --source input.py

# Inspect a saved stage artifact
pycforge inspect stage.json

# Compare two serialized results
pycforge diff left.json right.json

# Display the exact installed command surface
pycforge --help
pycforge convert --help

An explicit output path does not hide semantic rejection. Existing output is left untouched and the rejection result is emitted. Process exit status distinguishes success, rejection, cancellation, I/O failure, internal failure, and audit failure.

Python API

from pycforge import ConversionRequest, PythonToCConverter

source = """\
def add(left: int, right: int) -> int:
    return left + right
"""

request = ConversionRequest.from_source(source)
result = PythonToCConverter().convert(request)

if result.generated_c is not None:
    print(result.generated_c)
else:
    for diagnostic in result.diagnostics:
        print(diagnostic)

Inspect result.status rather than treating non-null output as the only result contract. Structured diagnostics, fingerprints, mappings, summary, trace, telemetry, and stage artifacts are available according to the request's observation settings.

Explicit multi-document request

from pycforge import (
    ConversionRequest,
    PythonToCConverter,
    SourceBundle,
    SourceDocumentInput,
)

bundle = SourceBundle(
    primary=SourceDocumentInput("main.py", main_text, "main"),
    companions=(
        SourceDocumentInput(
            "math_tools.py", tools_text, "math_tools"
        ),
    ),
)
result = PythonToCConverter().convert(
    ConversionRequest(source_bundle=bundle)
)

The request can also carry explicit target, semantic, rule-set, renderer, helper, container, module, record, numeric, runtime, resource, and observation contracts. Defaults select the current Phase 16 profile. Requests may lower resource limits but cannot raise trusted hard ceilings.

Result-handling checklist

1. Require a success status appropriate to the calling policy.
2. Review warnings and approximations if a historical contract can emit them.
3. Bind saved artifacts to the request and output fingerprints.
4. Do not publish generated C after source or identity changes make it stale.
5. Treat cancellation and internal failure as distinct from semantic rejection.