Module diagnostics 

JSONL event rendering for wrapper-made diagnostics. What: Render wrapper diagnostics as the JSONL events callers already parse. Why: Agents and hooks read cli-git’s event stream line by line; every wrapper-made event must be one compact JSON object per line with stable field order.

In TS you’d write (pseudocode):

// process.stderr.write(JSON.stringify({ schemaVersion: 1, sequence: 0, type: 'engine-failure', ... }) + '\n');

Enums

EngineFailureCode

What: The stable causes of an engine failure this foundation and its successors report. #[derive(...)] generates copying, debug printing and ==. Why: A closed set keeps the wire spelling in one place. Codes that described plugins and trust are not carried over. A shipped policy that could not finish is reported by cause: ContentUnavailable when something it had to read could not be read, PolicyIncomplete when its own machinery failed.

Constants

LEGACY_CONFIG_IGNORED_CODE

Code of the warning for a legacy executable configuration left beside a JSONC file.

SCHEMA_VERSION

What: The event schema version every line carries. u32 is an unsigned 32-bit integer (siblings u8, u64, usize). Why: Consumers branch on this number; u32 is ample for a version counter.

Functions

engine_failure_code_name

What: The wire spelling of a failure code. &'static str borrows text compiled into the executable for its whole run. Why: Events print exactly the spellings the incumbent emitted.

json_string

What: Encode text as a JSON string literal, exactly as JSON.stringify would. &str borrows the text; String is the owned, quoted result. Why: Messages contain file paths, quotes and user-written keys. Each character is encoded at this final step so no value can break out of its JSON string or its line: quotes, backslashes and every control character are escaped.

render_configuration_warning

What: Render one configuration-warning event as a line-terminated JSON object. Why: A warning about configuration itself (a legacy file left beside the JSONC file) belongs on the machine stream as an event, never as free prose there. Unlike the incumbent’s per-policy warn-unsafe warning it has no policy or trigger, so it carries a path instead.

render_engine_failure

What: Render one engine-failure event as a line-terminated JSON object. u64 is an unsigned 64-bit integer for the per-invocation event number. Why: Field order and spelling match the incumbent’s JSON.stringify output, so existing consumers parse native events unchanged.

render_engine_failure_with_hint

What: Render one engine-failure event with the hint the caller chooses, or with none. Why: A hint is a guess about the goal that depends on the code alone. A message that already says what the person can do (a retained transaction names the file to remove or restore, and what the wrapper then does) must not carry the code’s generic hint, which may not apply to it.