pyproject.toml

# Substrate — concurrent streaming dataflow runtime.
# Distribution name: substrate-kernel (the bare "substrate" is registered to an unrelated
# party on PyPI). Import name: substrate. Decided 2026-07-24 (BLACKBOARD ## Decisions).
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "substrate-kernel"
version = "1.0.0"
description = "A Python runtime that coordinates models and anything else you want through a single append-only log. Replay, diff, and trace every run."
requires-python = ">=3.12"          # D-6: 3.12+ only (msgspec C ext, per-task eager exec)
license = "Apache-2.0"              # D-1
readme = "README.md"
authors = [{ name = "Green Rose Systems" }]
keywords = ["dataflow", "runtime", "event-sourcing", "llm", "orchestration", "replay", "append-only-log"]
classifiers = [
  "Development Status :: 5 - Production/Stable",
  "Intended Audience :: Developers",
  "Programming Language :: Python :: 3.12",
  "Programming Language :: Python :: 3.13",
  "Programming Language :: Python :: 3.14",
  "Operating System :: MacOS",
  "Operating System :: POSIX :: Linux",
  "Topic :: Software Development :: Libraries :: Python Modules",
  "Typing :: Typed",
]

dependencies = [
  "msgspec>=0.21,<0.22",            # D-3: validation + encoding + schema + to_builtins
  "rfc8785",                        # D-7: RFC 8785 canonical JSON (the bytes everything hashes over)
  "python-ulid",                    # run_id generation
  "typing_extensions",              # python-ulid 3.x imports it at runtime but doesn't declare it;
                                    # without this a base `pip install substrate` fails at import
  "click",                          # CLI parsing
  "rich",                           # the CLI's stderr narration channel ([config]/[lock]/[FAIL]
  # status lines); record DATA goes to stdout via plain click.echo
]

[project.optional-dependencies]
dev = [
  "pytest", "pytest-asyncio", "pytest-benchmark", "pytest-timeout",
  # ruff PINNED: `ruff format` output is version-sensitive, so an unpinned ruff silently re-drifts the
  # CI format gate across releases (it stranded the repo red before 2026-07-02). Bump deliberately +
  # reformat in one commit. mypy/pytest are behaviour-stable enough to float.
  "mypy", "ruff==0.15.17", "hypothesis", "coverage",
  "import-linter",                  # enforces the F-API-6 cli-imports-only-api contract (below)
  "httpx",                          # so dev + CI type-check/test the [openai-compat] reference adapter
]
openai-compat = ["httpx"]           # optional extra; kernel imports none of these
# The SWE-bench confirmatory + host + agent scripts hard-import `datasets` (HuggingFace, to
# load the Lite split) and `swebench` (the official grading harness). Neither is a runtime dep
# of the kernel — they're only needed on the Architect's box for a real Docker eval run.
# `uv sync --extra swebench` installs both in one command so a new operator does not have to
# know to pip-install them by hand (the pre-2026-08-08 tribal state).
swebench = ["datasets", "swebench"]

[project.urls]
Repository = "https://github.com/laffeyp/Substrate"
Changelog = "https://github.com/laffeyp/Substrate/blob/main/CHANGELOG.md"

[project.scripts]
substrate = "substrate.cli:main"

[tool.hatch.build.targets.wheel]
packages = ["src/substrate"]

[tool.pytest.ini_options]
asyncio_mode = "auto"
testpaths = ["tests"]
# The suite is FUNCTION-tests only (def test_*, with underscore-prefixed helper classes). Disable
# class-based collection so a DOMAIN record whose name starts with "Test" (e.g. the locked vocabulary
# record `TestResults`) isn't mistaken for a test class when imported into a test module.
python_classes = []
markers = [
  # real-model demos run a topology against a LIVE local LLM (Ollama) and verify the claim from the
  # record. Self-skip when the models are absent (so CI / other machines stay green); run here.
  # Deselect with `-m "not realmodel"`. The per-test timeouts override the 30s suite default below.
  "realmodel: runs against a live local model (Ollama); skips if the model is absent",
  # SWE-bench harness binding gold-differential checks. Runs the OFFICIAL swebench evaluation harness
  # in Docker against a real instance (gold patch → resolved; empty patch → not-resolved). The one
  # end-to-end check that pins substrate.assay.swebench's binding to the harness on-disk contract.
  # Skips when swebench isn't importable OR Docker isn't running OR the eval image isn't pullable.
  # Long: an emulated x86 image pull + evaluation on arm64 can take 10+ min. Deselect with
  # `-m "not swebench_harness"`. Restored from the deleted swebench_smoke.py + assay_swebench_smoke.py
  # after Sprint 146 removed them without pytest coverage equivalents (sprint 146a).
  "swebench_harness: pins the swebench 4.x harness binding via a live Docker gold-differential run",
]
# Hard safety net: any test (e.g. a never-quiescent writer or a self-feeding Trigger
# loop) FAILS FAST instead of wedging the machine. Each test finishes well under a second (this timeout is PER-TEST, not whole-suite); 30s is
# generous headroom that still catches non-termination immediately.
timeout = 30

[tool.ruff]
target-version = "py312"
line-length = 100
# docs/specs/kernel_spec/ and docs/proof/ hold scratch / spec-history Python (audit-trail, hard
# rule 12); they are not part of the package and are excluded from both lint and format gates.
extend-exclude = ["docs/specs/kernel_spec", "docs/proof"]

[tool.mypy]
python_version = "3.12"
strict = true
files = ["src/substrate"]

# `swebench` is an optional, env-gated dependency: the SWE-bench Adapter (substrate.assay.swebench)
# lazy-imports it only on the Architect's box for a real Docker eval run. It ships no type stubs and is
# not installed in CI, so declare its imports untyped here rather than scattering fragile inline
# `type: ignore[import-not-found]` comments (which churn as mypy dedups the missing package).
[[tool.mypy.overrides]]
module = "swebench.*"
ignore_missing_imports = true

# HuggingFace `datasets` — no bundled stubs; the loader is used only by scripts (bench + confirmatory).
[[tool.mypy.overrides]]
module = "datasets"
ignore_missing_imports = true

# F-API-6: the CLI is the standing proof that the public API suffices — `substrate.cli` may
# import `substrate.api` (and stdlib / third-party) but NO other `substrate.*` module. Enforced
# by `uv run lint-imports` (import-linter), run in CI. The src layout means the package must be
# importable; the editable install (`uv pip install -e`) provides that.
[tool.importlinter]
root_package = "substrate"

[[tool.importlinter.contracts]]
name = "cli imports only substrate.api"
type = "forbidden"
source_modules = ["substrate.cli"]
# Only DIRECT cli imports are constrained: cli -> api is allowed, and api -> internals is fine
# (that is the whole point — api is the facade). Without this, the cli -> api -> internal chain
# would be flagged. The rule we enforce is "cli's own imports touch no private module".
allow_indirect_imports = true
# Every internal surface EXCEPT substrate.api. cli may import only the public facade. Naming the
# four internal SUBPACKAGES (kernel/record/projections/conformance) forbids all their submodules at
# once, so a new private module dropped inside one is covered automatically — no per-module denylist
# to keep in sync (the old flat list had to enumerate all ~25). The remaining top-level leaves
# (types/protocols/errors/constants/encoding) + testing are named directly. A miss is still caught
# by the CLI's own AST import-lint test, tests/test_cli.py::test_cli_imports_only_substrate_api.
forbidden_modules = [
  "substrate.kernel", "substrate.record", "substrate.projections", "substrate.conformance",
  "substrate.types", "substrate.protocols", "substrate.errors", "substrate.constants",
  "substrate.encoding", "substrate.testing",
]