Metadata-Version: 2.4
Name: dbl-core
Version: 0.3.6
Summary: Deterministic Boundary Layers core substrate on KL Kernel Logic
Author-email: Lukas Pfister <228201683+lukaspfisterch@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://github.com/lukaspfisterch/dbl-core
Project-URL: Repository, https://github.com/lukaspfisterch/dbl-core
Project-URL: Issues, https://github.com/lukaspfisterch/dbl-core/issues
Keywords: dbl,deterministic,audit,event-log,governance
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: kl-kernel-logic<0.6.0,>=0.5.0
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.5; extra == "dev"
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Dynamic: license-file

# DBL Core

[![CI / Tests](https://github.com/lukaspfisterch/dbl-core/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/lukaspfisterch/dbl-core/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/dbl-core.svg?label=PyPI)](https://pypi.org/project/dbl-core/)
[![Python >=3.11](https://img.shields.io/pypi/pyversions/dbl-core.svg?label=Python)](https://pypi.org/project/dbl-core/)
[![Typing: Typed](https://img.shields.io/badge/typing-typed-2d7f5e.svg)](https://pypi.org/project/dbl-core/)

DBL Core is a deterministic event substrate for the Deterministic Boundary Layer (DBL). It records intent, decisions, and executions as a single ordered stream.

## Why DBL Core exists

DBL Core exists to provide a deterministic, audit-stable event substrate for systems that need to separate:

- intent from decision
- decision from execution
- normative history from observational artifacts

It is designed for systems where replayability, auditability, and governance correctness matter more than convenience or performance.

## Mental Model

DBL Core maintains a single append-only event stream V:

INTENT → DECISION → (optional) EXECUTION → (optional) PROOF

Only DECISION events are normative.
All other data is treated as observational and excluded from digests.

## Scope
- Single-stream event model with deterministic t_index.
- Canonical serialization and digest for events and behavior logs.
- Gate decision events (ALLOW or DENY) as explicit Deltas.
- Embeds kernel traces as observational artifacts with canonical integrity digests.

## Non-Goals
- No policy engine or templates.
- No execution of user tasks.
- No orchestration, UX flows, or intelligence.
- No time, randomness, or I/O side effects.

## What DBL Core is not

DBL Core is intentionally minimal.
It is not:

- a workflow engine
- a policy engine
- a domain framework
- an execution orchestrator
- an LLM wrapper

If you need domain semantics, validation, or verdict logic,
implement a domainrunner on top of DBL Core.

## Contract-first design

DBL Core behavior is defined by a stable, normative contract.

- Code must conform to the contract.
- Tests enforce contract invariants.
- Domain-specific semantics are explicitly out of scope.

See:
- [DBL Core Contract](docs/dbl_contract.md)
- [Domainrunner Contract](docs/dbl_contract_domainrunner.md)

## Contract
- [DBL Core Contract](docs/dbl_contract.md)

## Install

```bash
pip install dbl-core
```
Requires kl-kernel-logic>=0.5.0 and Python 3.11+.

## Public API
- DblEvent, DblEventKind
- BehaviorV
- GateDecision
- normalize_trace is a canonicalization adapter only

## Ordering
Ordering is derived from t_index (position in V). Timestamps and runtime fields are observational only.
