libLogit

LOGIT Contract Matrix

This page is the public-facing contract inventory for libLogit v1 Beta work. It answers a simple question: what does a LOGIT mean across bindings, and what is stable versus still being hardened?

Why This Page Exists

The repo already has the raw contract in spec/logit-object.md and the current Alpha API surface in docs/api/README.md.

What was missing was one bridge document that:

This page is that bridge.

Contract Status Vocabulary

Status Meaning
Beta baseline Part of the portable contract every supported Beta binding should converge on.
Alpha proven Exists in the current Alpha baseline and has concrete repo evidence today.
Binding-specific Real behavior exists, but it is not yet expected everywhere.
Compatibility alias Accepted for migration or ergonomics, but not the preferred canonical name.
Beta-track Planned for Beta hardening or expansion, but not yet frozen across bindings.

Core LOGIT Identity And Output Fields

Field Canonical meaning Status Notes
name Stable logger identifier. Beta baseline, Alpha proven Blank LOGIT starts as default.
localPath Preferred local file destination field. Beta baseline, Alpha proven User-facing mutable field/property name across bindings where practical.
path Portable config/local destination field. Beta baseline, Alpha proven Often maps to the same underlying local destination as localPath.
outputDirectory User-friendly directory-mode local destination. Beta baseline, Alpha proven Implies local directory mode when accepted.
pathMode file or directory interpretation for path-like outputs. Beta baseline, Alpha proven outputDirectory must not be combined with pathMode = file.
remotePath Secondary remote/network file destination. Beta baseline, Alpha proven Alpha treats non-socket values as file-like destinations.
databasePath Local SQLite log-store destination. Binding-specific, Alpha proven Strongest today in the Python reference binding.

Core Runtime Control Fields

Field Canonical meaning Status Notes
level Minimum severity threshold. Beta baseline, Alpha proven Ordered as trace < debug < info < warn < error < fatal.
enabled Fast on/off switch for the logger. Beta baseline, Alpha proven False drops events before sinks receive them.
sinks Explicit destination selection. Beta baseline, Alpha proven Current vocabulary includes console, file, network, and Python database.
format Text versus JSON-lines rendering mode. Beta baseline, Alpha proven text and json are the current public values.
timestamp Whether rendered/stored events carry time information. Beta baseline, Alpha proven Important for deterministic conformance when disabled.
tag_level Whether text output includes the textual level label. Beta baseline, Alpha proven Canonical config spelling remains snake_case today.
metadata Static event metadata map. Beta baseline, Alpha proven Python also proves static plus per-message metadata merging.

Persistence And Retention Fields

Field Canonical meaning Status Notes
rotation.maxBytes File-size limit before rotation. Beta baseline, Alpha proven Proven strongest in Python.
rotation.maxFiles Number of rotated backups to keep. Beta baseline, Alpha proven File-count semantics still need broader binding parity.
retention.maxRecords Maximum retained database records. Beta baseline, Alpha proven Python Alpha retained-store proof.
retention.maxAgeSeconds Maximum age for retained database rows. Binding-specific, Alpha proven Currently strongest in Python.
retention.maxBytes Logical payload byte budget for retained database rows. Binding-specific, Alpha proven Currently strongest in Python.

Advanced Runtime Fields

Field Canonical meaning Status Notes
buffering Sync/async or batched output policy. Binding-specific, Beta-track Python reference has the deepest implementation today.
failurePolicy Per-event sink failure behavior. Binding-specific, Beta-track Python proves warn, drop, raise, retry, and fallback.
redaction Key and pattern masking before sinks receive data. Binding-specific, Beta-track Strong Python proof, not yet portable parity.

Blank LOGIT Baseline

The current portable blank-LOGIT baseline is:

Behavior Expected baseline
Initial name default
Initial local path unset
Initial remote path unset
Initial path mode file
Initial level info
Initial enabled state true
Initial format text
Initial console behavior console is the only implied sink until a path is assigned

This baseline is already documented in the spec and directly asserted in binding tests across the MVP language set.

Call And Emit Semantics

The punctuation changes, but the event model should not.

Style Meaning
LogIT(INFO) << "message" Streaming/object-bound emit path.
LogIT.log(INFO, "message") Direct/immediate emit path.
LogIT.at(INFO).append("message").commit() Builder-style emit path used in bindings that prefer explicit commit.

The Beta goal is that these all represent the same event concepts:

Compatibility Aliases Still Present

These names exist for migration or cross-language ergonomics, but the Beta docs should steer new users toward the canonical names where possible.

Alias Preferred direction Why it exists
local_path localPath Snake_case compatibility and config ergonomics.
output_directory outputDirectory Snake_case compatibility and config ergonomics.
path_mode pathMode Snake_case compatibility and config ergonomics.
remote_path remotePath Snake_case compatibility and config ergonomics.
database_path databasePath Snake_case compatibility and config ergonomics.
file_location path / localPath v0.1 migration alias.
network_file_location remotePath v0.1 migration alias.
database_location databasePath Legacy compatibility alias.

Binding Surface Expectations

Every supported Beta binding should provide all of the following:

Capability Expected outcome
Blank construction A user can create a default LOGIT safely.
Structure-fed setup A user can provide a dict/object/struct/builder-like setup shape.
Config-loaded setup A user can load named loggers from the shared config format.
Direct or object-bound logging A user can emit through the logger object itself.
Console output Immediate developer-visible output exists.
Local file output A configured path or output directory persists logs locally.
Limitations clarity Unsupported advanced fields are rejected clearly or documented honestly.

What Is Frozen Enough To Teach Publicly

Today the docs can confidently teach:

The docs should still be careful around: