Metadata-Version: 2.4
Name: substratum-cli
Version: 0.1.0
Summary: Substratum: verified-or-refused code, with provenance. The terminal over the comprehension engine.
Author: Substratum
License: LicenseRef-Proprietary
Project-URL: Homepage, https://substratum-api.fly.dev
Keywords: code-generation,verification,deterministic,provenance,developer-tools
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Provides-Extra: engine
Requires-Dist: numpy>=1.24; extra == "engine"

# Substratum

**Verified-or-refused code, with provenance.** Substratum is a deterministic comprehension engine
for code. It never streams tokens and hopes — it produces a change only when that change passes a
gate, and otherwise returns an honest, actionable refusal. Every result carries a run id you can
replay byte-for-byte.

```
pip install substratum-cli
```

Then, in any repository:

```
substratum                      # open the interactive session (warms, then drives)
```

## What it does

- **`summarize`** — describe the codebase in plain English, grounded in its real symbols (not a guess).
- **`failing`** — run the suite and list the failing tests; each becomes a ready fix target.
- **`verify`** — gate a diff (stdin, `--staged`, `--commit`): PASS / FAIL / per-hunk. The wedge — point
  it at any tool's diff and it tells you, deterministically, whether the change is real.
- **`fix`** — produce a verified fix for a failing test, or a named refusal.
- **`write`** — greenfield code from plain intent (derive-or-refuse; no test required).
- **`runs` / `show` / `replay` / `undo` / `apply` / `commit`** — a proof-carrying memory of every run.

`summarize`, `failing`, and `verify` run **entirely on your machine** — no account, no network, no code
leaves your repo. They work air-gapped.

## The hosted engine (optional)

`fix` and `write` draw on a large mined library. During the demo that library is hosted:

```
substratum login                # GitHub device flow; connects to the hosted engine
```

When logged in, `write` sends only your intent + signature, and `fix` receives a *candidate* that your
machine then gates locally — so your code and your tests never leave your machine. `substratum logout`
returns to fully-local operation.

## The law

Never render unproven code. A refusal is a deliverable, not an error. Determinism is a button you
press to catch us: run the same request twice and get the same run id, or `replay` any run and get a
byte-identical result.

Coverage grows with data. Today the engine refuses more than it resolves, by design — the surface is
built to feel complete at thin coverage, and the same commands silently resolve more as the library
scales, with zero change on your end.
