libLogit

Binding Implementation Playbook

This playbook defines how a language-specific libLogit binding moves from idea to supported Beta status.

Binding Principle

Do not invent a new product for each language. Implement the same LOGIT contract with syntax that feels natural in the target ecosystem.

The user should recognize this flow everywhere:

LOGIT LogIT = []
LogIT.localPath = "logs/app.log"
LogIT.level = DEBUG
LogIT(INFO) << "service started"

Support Tiers

Tier	Definition
Supported	Installable package, documented API, examples, shared fixture runner, CI/release evidence, and maintainer ownership.
Incubating	Working implementation or design sketch that follows the contract but lacks one or more supported-tier gates.
Future	Language has an intake record, user demand signal, or community interest but no supported implementation yet.

Only supported bindings count toward v1 Beta readiness.

Required API Surface

Each supported binding must provide:

Capability	Requirement
Blank construction	A user can create a default LOGIT without a config file.
Structure-fed setup	A user can pass a dictionary, object, struct, builder, or JSON-like shape.
Config-loaded setup	A user can load named loggers from the shared config schema.
Level parsing	trace, debug, info, warn, error, and fatal map to the same order.
Console sink	An event can appear immediately in console output.
Local file sink	A configured path writes UTF-8 log output.
Path rules	Exact file path and directory-derived path semantics are documented.
Formatter	Text output is required; JSON-lines output is required for Beta-supported status unless explicitly waived.
Flush/close	Buffered or file-backed bindings expose deterministic shutdown behavior.
Errors	Sink failures follow documented warning/drop/raise/retry/fallback behavior where implemented.

Package Expectations

Each supported binding needs:

• Package metadata with name, version, license, repository, and description.
• A normal install command for the target ecosystem.
• A direct construction example.
• A config-loaded example.
• A release artifact verification step.
• Documentation linked from the root README or docs home.

Conformance Expectations

Each supported binding must run shared fixtures that prove:

• Level thresholds filter the same events.
• Config fields map to the same behavior.
• Text output contains expected message and level information.
• JSON-lines output uses stable field names.
• Fixed-clock metadata is deterministic.
• Local path and directory path rules match the spec.
• Unsupported optional fields fail clearly or are documented as no-ops.

Bindings should also be able to participate in the machine-readable runner contract described in tests/conformance/runner-contract.md. The runner may emit JSON directly or be wrapped by a repository script that normalizes its result into the shared report shape.

Promotion Checklist

Move a binding through these gates:

Gate	Output	Acceptance Criteria
Intake	docs/bindings/<language>.md or proposal issue	Target users, package manager, minimum runtime, risks, and owner are named.
Skeleton	Source tree and minimal tests	Blank LOGIT can be constructed and called.
Config	Schema adapter	Shared sample config loads or fails with clear diagnostics.
Sinks	Console and file output	Local smoke tests prove immediate output and file append.
Fixtures	Conformance runner	Shared fixtures pass in local verification.
Package	Ecosystem artifact	Package can be built and inspected.
CI	Hosted workflow	Required job runs on supported OS/runtime.
Docs	README/docs updates	Install, direct example, config example, and limitations are public.
Supported	Release checklist entry	Maintainers agree it counts toward Beta readiness.

Design Rules

• Prefer the target ecosystem’s naming and construction style.
• Preserve the shared field vocabulary where reasonable: localPath, path, pathMode, remotePath, level, format, metadata, sinks, rotation, and retention.
• Keep advanced features optional until the binding passes core conformance.
• Document unsupported fields instead of silently pretending they work.
• Avoid syntax tricks that make common logging harder to read.
• Add tests before promoting a binding from incubating to supported.