libLogit

LOGIT Lifecycle And Compatibility Rules

This page explains how a LOGIT is expected to behave over time, not just what fields it contains.

If the contract matrix answers “what is a LOGIT?”, this page answers:

• how a LOGIT starts
• how it emits
• when flush() and close() matter
• what a binding should do when it does not support an optional field

The Portable Lifecycle

Every binding should preserve the same conceptual flow:

1. create a blank LOGIT
2. configure output and level during startup
3. emit events directly or through a builder/stream helper
4. flush when deterministic visibility is required
5. close when the application or subsystem is shutting down

The punctuation varies. The lifecycle should not.

Construction Rules

A blank LOGIT should be safe to create before the app has finished deciding where logs belong.

That means:

• blank construction should not require a config file
• blank construction should not require a database file
• blank construction should not fail just because no local path is set yet
• console is the only implied sink until a path or explicit sink list changes that picture

Emit Rules

libLogit currently supports three public emit shapes:

Shape	Meaning
logit.log(level, message)	Direct/immediate event emission.
logit(level) << "a" << "b"	Streaming emission.
logit.at(level).append("a").append("b").commit()	Builder-style emission.

All three should map to the same event model:

• one logger
• one selected level
• one final rendered message
• one metadata merge decision where supported
• one sink-selection decision

Builder Rules

Builder or stream helpers should follow these rules:

• fragment order is preserved
• an empty builder does not emit by default
• an invalid level fails before writing
• the builder emits at most once
• explicit commit is the deterministic completion path

Current Alpha evidence is strongest in Python, where tests already verify:

• repeated commit() does not double-write
• empty builders stay quiet
• invalid levels raise before file output
• destructor fallback can emit uncommitted content as best effort

Flush And Close

The Beta contract direction is:

flush()

Use flush() when the caller needs buffered data made visible before normal shutdown.

Bindings with buffered or persisted sinks should treat flush() as:

• write pending buffered events
• flush file handles where needed
• flush database writes where needed

close()

Use close() when the owning application or subsystem is done with the logger.

Bindings with persisted sinks should treat close() as:

• flush pending buffered events
• release file handles
• release database connections
• leave the logger in a terminal or reconfigurable state depending on the binding design

Destructor And Finalizer Behavior

Destructor or finalizer emission is allowed as best effort. It is not the portable deterministic contract.

Public docs should always prefer explicit commit, explicit flush, and explicit close when the caller needs reliable visibility.

That is especially important because languages handle object destruction very differently.

Unsupported Field Rules

Optional or advanced fields are where SDK drift starts if we are not careful.

A binding must never silently suggest support it does not actually have.

For any optional field, a binding should do one of these:

1. implement it and test it
2. reject it clearly during setup/config load
3. document it as a no-op with explicit limits

The thing a binding should not do is accept a field quietly and then leave the user believing it worked.

Compatibility Aliases Versus Canonical Names

The current repo still accepts several compatibility names for migration:

• local_path
• output_directory
• path_mode
• remote_path
• database_path
• file_location
• network_file_location

The Beta direction is:

• keep compatibility where it helps migration
• teach canonical names first in public docs
• keep schema and parser behavior explicit
• avoid letting transitional names define the long-term product vocabulary

What Is Portable Today

You can teach these as the stable public story today:

• blank LOGIT
• localPath
• outputDirectory
• pathMode
• remotePath
• level
• direct logging
• builder/stream logging
• explicit commit
• explicit flush and close where the binding exposes them

What Still Needs Beta Hardening

These areas still need stronger cross-binding proof:

• flush/close parity across all bindings
• builder lifecycle parity across all bindings
• rejection-versus-no-op policy for every advanced field in every binding
• final canonical schema vocabulary after migration aliases are sorted out

Related Sources

• LOGIT contract matrix
• Config schema audit
• Developer instructions
• Shared LOGIT spec
• Streaming API spec