Kernel Stability Contract

pyGOTM exposes a small kernel surface for external tools. The kernel remains a simulation package; tools interact through commands, stdin/stdout JSON-RPC, and NetCDF files.

Stable Public Surface

The following contracts are stable after the first public kernel release:

  • Public CLI command names and documented flags.

  • JSON keys from pygotm version --json.

  • JSON-lines event shapes from pygotm run --progress json.

  • pygotm serve request, response, and event schema.

  • NetCDF global attributes listed by pygotm schema netcdf-attrs --json.

  • pygotm_config_schema_version and pygotm_output_schema_version.

Additive keys, commands, variables, or optional fields are minor-version changes. Removing a key, renaming a key, or changing a documented meaning requires a major-version bump or a documented deprecation period.

Exit Codes

Click parse and usage errors keep Click’s exit code 2. Runtime commands map known failures to these public codes:

Code

Meaning

0

Success.

1

Validation completed but the verdict is not full parity.

2

CLI usage or parse error from Click.

10

Config, YAML validation, or schema error.

11

Unsupported compiled-runtime configuration.

12

Runtime execution failure after setup.

13

Input/output file error.

14

Dependency or environment unavailable.

70

Unexpected internal error.

Tracebacks are hidden by default for public CLI use. Pass --debug to pygotm run when developing against the kernel and needing the original Python traceback.

Progress Events

pygotm run --progress json writes newline-delimited JSON events to stderr. The default mode remains silent. Hydro-only runs currently report progress_mode: "indeterminate" for integration, because the compiled hydro runtime is invoked as one call and does not have parity-tested chunked progress. FABM-active runs can emit determinate chunk progress.

NetCDF Contract

Every pyGOTM output includes global attributes for version, environment, configuration hashes, timestamps, turbulence closure, ice model, and FABM status. The source YAML hash is the raw file-byte SHA-256. The effective YAML hash is computed from a canonical materialized YAML document and is portable across machine path relocations.