elenctic 1.0.0__tar.gz

elenctic-1.0.0/.dockerignore

@@ -0,0 +1,15 @@
+.venv
+.pixi
+.git
+.pytest_cache
+.mypy_cache
+.ruff_cache
+__pycache__
+*.pyc
+.coverage
+htmlcov
+dist
+build
+*.egg-info
+/tmp
+scratch

elenctic-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+name: ci
+on:
+  push:
+    branches: [main]
+  pull_request:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+jobs:
+  # A secondary check that the package installs and its tests pass under uv, on Python 3.14 and 3.15,
+  # from the tracked uv.lock. The gate itself is the pixi job below.
+  uv-install:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --locked --python ${{ matrix.python }} --extra theory
+      - run: uv run pytest
+  pixi:
+    # The gate: format, lint, strict types, import contracts, tests.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.10
+      - run: pixi run -e theory check
+  recipe:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: prefix-dev/setup-pixi@v0.8.10
+      - run: pixi global install rattler-build
+      - name: Build the recipe from this checkout
+        run: |
+          mkdir -p "$RUNNER_TEMP/recipe"
+          sed "s|  url: .*|  path: $GITHUB_WORKSPACE|; /  sha256:/d" \
+            recipe/recipe.yaml > "$RUNNER_TEMP/recipe/recipe.yaml"
+          rattler-build build --recipe "$RUNNER_TEMP/recipe/recipe.yaml"

elenctic-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,66 @@
+name: release
+on:
+  push:
+    tags: ["v*"]
+permissions:
+  contents: read
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          python-version: "3.14"
+      - run: uv sync --locked --no-dev
+      - name: Check the tag and schema
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          uv run --locked --no-dev python - <<'PY'
+          import os
+          import runpy
+          import tomllib
+          from pathlib import Path
+
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          if os.environ["RELEASE_TAG"] != f"v{version}":
+              raise SystemExit("tag must match the package version")
+          schema = runpy.run_path("scripts/write_output_schema.py")
+          if schema["TARGET"].read_text() != schema["render"]():
+              raise SystemExit("regenerate the output schema")
+          PY
+      - run: uv build --python 3.14
+      - name: Check the shipped schema
+        run: |
+          uv run --locked --no-dev python - <<'PYTHON'
+          from pathlib import Path
+          from zipfile import ZipFile
+
+          with ZipFile(next(Path("dist").glob("*.whl"))) as wheel:
+              if wheel.read("elenctic/output-v1.schema.json") != Path(
+                  "docs/reference/output-v1.schema.json"
+              ).read_bytes():
+                  raise SystemExit("wheel must ship the output schema")
+          PYTHON
+      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/elenctic
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: distributions
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # release/v1

elenctic-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+.venv/
+__pycache__/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.hypothesis/
+.coverage
+dist/
+*.egg-info/
+.pixi/

elenctic-1.0.0/CHANGELOG.md

@@ -0,0 +1,193 @@
+# Changelog
+
+All notable changes are recorded here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project follows
+[Semantic Versioning](https://semver.org/).
+
+## [1.0.0] - 2026-11-06
+
+### Added
+- `--root DIR`: one root for every path and `#include` of a run, so a subtree whose cases include
+  files from a sibling directory can be tested on its own.
+- `Containerfile`: a local multi-stage recipe for the CLI (uv sync from the lockfile with the
+  theory extra). Build it yourself; there is no published image and no CI image build.
+- Pixi environments `py314` and `py315` for the test suite under those Pythons (`pixi run -e py314 test`).
+- JSON Schema for the `--json` document: `docs/reference/output-v1.schema.json`, generated from the
+  result types `encode` walks (`elenctic.json_view.schema_document`); regenerate with
+  `scripts/write_output_schema.py`. A test fails if the committed file is stale.
+- `python -m elenctic` runs the same CLI as the `elenctic` console script (`src/elenctic/__main__.py`).
+- Import contracts (import-linter, in `pyproject.toml`): the layering, clingo reached only by the fifteen
+  modules that read and run programs, clingcon only by `theory`, and `spans` free of both. They run
+  in `pixi run check` and in CI.
+- Library: `Program`, `ground`, `solve` with `Limits` and a cancelable `Interrupt`; results as
+  `Consistent | Inconsistent | Inconclusive` over `AnswerSets` or `Consequences`.
+- Query kernel in the public API: `Literal`, `Pattern`, `Query` (`Literal | Pattern | All | Any`), `Answer`,
+  `answer`, `bindings`, over a `WorldView` that only an exhausted search yields.
+- A row for every name of `elenctic.__all__` in `docs/reference/reference.md`, checked by a test.
+- `mgu(first, second)` and `Unifier`: the most general unifier of two patterns, renamed apart, and
+  the pattern both become. Public for answering queries and for the interactive session to come.
+- `unify(first, second)`: the same unifier for two patterns that share their variables by name, as a
+  `Substitution`. It is what query answering calls; against a ground pattern it agrees with `mgu`.
+- Contracts read from comments with source spans: `@expect`, `@count`, `@answer-set`, `@cautious`,
+  `@brave`, `@query` with optional `= { bindings }`, and an `assuming { … }` form on any claim.
+- `check` with the verdicts `pass`, `fail` and `undecided`.
+- Command line with `--json`, `--verbose`, `--max-seconds` and `--max-answer-sets`; exit codes `CLAIMS_HOLD` (0), `CLAIM_UNMET` (1) and
+  `FAULT` (2), and `INTERNAL_ERROR` (3) for a failure of elenctic itself, reported as one line on
+  stderr. They are the members of `elenctic.report.Exit`, an `IntEnum`, the outcome of `test`; `version` has its
+  own, `elenctic.about.VersionExit` (`REPORTED` 0, `INTERNAL_ERROR` 3), so no member is shared.
+- Native cautious and brave consequences (`Grounded.consequences`), used by `check` when a search
+  holds only such claims.
+- Minimal unsatisfiable cores over assumptions: `Refutation` is `These | NotThese | NoAssumptions`.
+- Optimization: `Grounded.optimize` returns `Optimum` or `Incumbent`; claims `@answer-set optimal`,
+  `@cautious optimal`, `@brave optimal`, `@optimal { L }`, `@count optimal n` and `@cost { … }`.
+- `@query optimal …`: the same three-valued query path over Opt(P); unqualified `@query` still reads
+  AS(P).
+- Preconditions that make a misreadable contract an error: theory atoms, an objective that grounds
+  away, a nested `@count optimal`.
+- `Report.lints`: notes when a query reads a literal the program can derive and does not `#show`.
+- Subcommands: `elenctic test` (the default) and the reserved `repl`, `why`, `ask`, `explain`.
+- `elenctic version`, `--version` and `-V`: one text with the version, the license, the holder and the
+  versions of clingo and clingcon that are loaded. `--version` and `-V` are options of `elenctic`
+  itself: valid before the command and winning over the rest of the line, not taken by a command.
+- Every type that a public signature names is exported, so a signature can be read and a value built
+  from `elenctic` alone: the readings `Satisfiable`, `Census`, `Witness`, `Entails`, `Asks`, `Binds`
+  and their union `Reading`, the query parts `All` and `Any`, `Shown`, `Found` and `Cut`. A test walks
+  the signatures of `__all__` and fails on a type left out. `elenctic.Any` is the disjunction of
+  queries, not `typing.Any`.
+- Examples with real output in `docs/reference/examples.md`, checked by a test.
+- Packaging for uv, pixi and conda-forge (`recipe/recipe.yaml`).
+- clingcon: `% @elenctic solver clingcon` in a contract, claims `@assign [optimal] { x=1, … }` and
+  `@answer-set … where { x=1, … }`, the library types `Solver`, `Assignment`, `Valuation` and
+  `AnswerSet.assignment`. An answer under clingcon is a shown set with its assignment, and `@count`
+  counts those. Optional: `elenctic[theory]`, or the pixi `theory` environment; a contract that
+  declares clingcon without it is an error (`FAULT`, 2).
+
+- `--color auto|always|never` (default `auto`) and `--icons[=WHEN]` (Nerd Font glyphs, off unless asked),
+  each decided per stream, and valid before the command as well as after it. `auto` follows
+  `NO_COLOR`, `TERM=dumb`, then whether the stream is a terminal, so a redirected stream stays plain; only `--color always` colors it. `CLICOLOR_FORCE`,
+  `CLICOLOR` and `FORCE_COLOR` are not read. This governs elenctic's own report and diagnostics;
+  the help and usage messages are colored as Python's `argparse` does by default. See the output
+  section of the reference.
+
+### Fixed
+- Docs: JSON `exit_code` includes 3; guides state `world_view` on a truncation; `@expect`-only searches stop once satisfiability is decided.
+- Guides: an interrupted `check` yields undecided findings; `solve` yields `Inconclusive`.
+- An `#include` that resolves outside the root is refused before the case is run; the diagnostic names the escaping path and never its contents.
+- Non-ASCII outside strings and comments is refused with a located diagnostic before clingo sees
+  it (program text, `#include`d files, and tag payloads), so a bad character never aborts the
+  process; `--json` still emits a document.
+- Binding sets keep tuple structure: `{ (1,2) }` for one variable is one binding, and `{ ((1,2),3) }` for two is accepted; a bare `{ a, 1 }` for arity 2 is refused.
+- A named `.lp` with no contract tag is a fault (exit 2), not a silent `0/0 passed`; a UTF-8 BOM is refused with a located diagnostic; a walked library whose `@tag` looks misspelled is a note.
+- Search groups that read only shown identities project onto `#show`, so `@count` and `@answer-set` no longer enumerate hidden variation; optimal groups prove the cost first, then enumerate at that bound; witness-only groups stop once every claim is decided.
+
+
+- Undecided truncated claims carry an `Ended` detail in JSON; `world_view` and `optimal_view` range over full answer sets by default; the hidden-read lint covers a query's contrary; `bindings` takes a single `Pattern`.
+
+- JSON entries carry `verdict` and `solver`, omit program `text`; diagnostic `label`/`children` are optional in the schema; `$id` points at the raw file under `docs/reference/`; the schema ships in the wheel.
+
+- An unexpected failure while checking one source is recorded for that source and the rest of the corpus still runs; the run exits 3.
+
+- Satisfiability-only groups keep no answer-set symbols; signatures come from clingo; atom→literal is looked up on demand.
+
+- A refutation core shows `not L` for an assumption that does not hold.
+- A one-element tuple keeps its trailing comma when rendered.
+- A query that is empty or uses `not` is refused as such; a variable query's help cites the user's pattern.
+- `@count optimal 0` under `@expect sat` names `optimal` in the contradiction.
+- Empty braces render as `{ }`; `@count` accepts only ASCII digits.
+- At most one `@count` per scenario and range.
+- `@expect` alone is admitted over a theory objective.
+
+- A second SIGINT restores the default handler so the process can exit 130.
+
+### Changed
+- The include refusal says `outside the root DIR` and has a help line.
+- An unknown `@model` is told the tag is spelled `@answer-set`; a walked library or a named file
+  whose tags are not tags says so (`@model` is not a tag) with the same help as an unknown tag.
+- A missing clingcon's help no longer names a pixi environment.
+- Consistency across docs, help and internals: truncation prose; reserved-command helps as imperatives; `--help` says "answer set programs"; `(default: …)` in the reference; "source" for a checked unit; stderr prefix rule; `render_run`, `holds_flag`, `Classes.merge`; CLI writes with `write` only; American-spelling and reading-name notes in the README; mechanical checks in `tests/test_consistency.py`.
+- Diagnostics follow the rustc model by default (`--format full`): `error: message`, ` --> path:line:col`, a source snippet with carets and a primary label, then `= note:` / `= help:` lines. `--format short` keeps today's one-line gcc form; `--json` is an alias of `--format json`. Messages are lowercase with no trailing period; fix-it wording stands only on `help`. Clingo's byte columns are converted to Unicode scalar columns so carets land. The JSON schema keeps `SCHEMA = 1` and adds optional `label`, `children`, and `code` on `diagnostic` (no codes in 1.0).
+- CI cancels superseded pull-request runs (`concurrency` with `cancel-in-progress` on pull requests only).
+- `uv.lock` pins clingo 5.8.3 and clingcon 5.2.2 so Python 3.15 installs from wheels.
+- The bindings of a query pattern are its most general unifiers with the cautious consequences of
+  the full answer sets: yes where it unifies with one, no where its contrary does. The brave
+  consequences give only the unknown instances (entertained, neither yes nor no). A ground literal
+  is yes when cautious and no when its contrary is. A conjunction or disjunction is still answered
+  over each answer set. The answers are unchanged; how they are found is not.
+- Limits are named for what they bound: `--max-seconds` (was `--budget`) and `--max-answer-sets` (was
+  `--models`), `Limits.max_seconds` and `Limits.max_answer_sets`, `DEFAULT_MAX_SECONDS` and
+  `DEFAULT_MAX_ANSWER_SETS`, and the truncations `MAX_SECONDS` and `MAX_ANSWER_SETS`. `UNLIMITED` is gone: use `Limits()`.
+- One answer set is an answer set everywhere: the tag `@answer-set` (was `@model`), the types `AnswerSet` (was
+  `Model`) and `AnswerSets` (was `Models`), `Atoms` (was `AnswerSet`), `Optimum.answer_sets`,
+  `Incumbent.answer_set`, `Seen.answer_set` and `search.answer_sets()`, and the same keys in the JSON.
+  The old names are gone.
+- Every enum value in the JSON is snake_case, and each is its member's name in lower case, so the
+  truncations are `max_answer_sets`, `max_seconds` and `interrupted`; the command-line flags keep their
+  hyphens.
+- The `kind` of every JSON object is its type's name in snake case (`report`, `entails`, `answer_set`), derived in
+  one place, `json_view.kind_of`.
+- A search cut short is worded for people by the text view: `search ended: answer-set limit reached
+  (--max-answer-sets)`, `time limit reached (--max-seconds)` or `interrupted`, where the text said
+  `max_answer_sets`. A finding's `detail` is text or `Ended` (the `Truncation`, and whether an optimum went
+  unproven), which is an object in the JSON; `Detail` and `Ended` are exported. The option names come from
+  `determination.option`, which the command line uses too.
+
+- Diagnostics for a source that could not be checked go to stderr, with the reserved-command note
+  and the internal-error line; verdicts and the summary stay on stdout. `--json` is all on stdout.
+- The terminal text is `elenctic.human`, the JSON is `elenctic.json_view` (`encode`, moved from
+  `elenctic.report`, which holds the run's values); escape sequences are written by `elenctic.paint`
+  alone.
+- `pixi run -e theory check` is the one documented gate; `check.sh` only runs it. `uv.lock` is tracked.
+  The CI uv job is a secondary install check (`uv sync --locked`, then the tests).
+- `--max-seconds` and `--max-answer-sets` take a positive number or the word `all` (no limit); `--max-answer-sets` defaults to
+  100,000 (`DEFAULT_MAX_ANSWER_SETS`), so a search that would read more is `undecided`; `--max-answer-sets all` lifts
+  it. The library default stays `Limit.UNBOUNDED`. `0` and negative values are a usage error: `--max-seconds 0` used to mean no limit and `--max-answer-sets 0`
+  an immediate cut. `Limits.max_seconds` and `Limits.max_answer_sets` are a number or `Limit.UNBOUNDED`, replacing
+  `None`.
+- A refutation by assumptions whose core may not be minimal (the search was cut short) now says so.
+- `@cost` over `#maximize` is accepted: costs are clingo's minimized sums, so a maximized level is
+  negated.
+- A query that reads a literal the program can derive and does not `#show` is noted (a lint on the
+  report), not refused; the note does not change the exit. The old refusal of such queries, and the
+  refusal of a `no`/`unknown` query whose contrary was derivable and unshown, are gone: full
+  answer-set evaluation makes both gates redundant for correctness. A later `--strict` may promote
+  the notes to faults; that flag is not built yet.
+- A theory atom with no `#theory` declaration is reported with elenctic's own message and location
+  rather than clingo's.
+- The theory-atom error points at the first theory atom, not at line 1.
+
+### Removed
+- `Pattern.match`, `Pattern.bindings_in` and the module `elenctic.matching`, a one-sided matcher of a
+  pattern against ground symbols. Query answering unifies instead (`unify`, the algorithm of `mgu`);
+  there is one mechanism for "does this pattern have this instance".
+
+### Fixed
+- Reference: `elenctic version` exits `REPORTED` (0), not `CLAIMS_HOLD`.
+- A binding query with an anonymous variable, `@query yes { p(_, X) } = { … }`, is refused where it
+  is read (`FAULT`, 2: "an anonymous variable has no binding to state: name it") instead of
+  failing inside elenctic (`INTERNAL_ERROR`, 3); `bindings` raises `ValueError` for it. An instance
+  of such a pattern is not ground, so it has no answer to give.
+- Documented that an objective only ranks answer sets and never removes any: unqualified claims and
+  every `@query` read all answer sets, and only `optimal` claims and `@cost` read the optimal ones
+  (`docs/explanation/semantics.md`, which the reference and the guides point to). The behavior is unchanged.
+- Queries evaluate over the full answer sets, not the shown projection: `-b. #show b/0.` with
+  `@query yes { -b }` is yes, and `-p. #show p/0.` with `@query yes { p }` reports no (not unknown).
+- An empty `no` binding is no longer a vacuous pass when a contrary holds:
+  `-p(1). #show p/1.` with `@query no { p(X) } = { }` fails; the no-set is `{1}`.
+- A variable `#show X : q(X).` no longer makes every predicate "shown" for coverage checks, and a
+  conditional `#show p : r.` no longer counts as unconditionally showing `p`.
+- `Program.read` accepts any path-like (`str | PathLike`).
+- A search is about 2.3 times faster: an answer set is read into literals only once it is kept, and each
+  clingo symbol is converted once.
+- Native `@cautious`/`@brave` under a limit on answer sets are decided from the solver, not the cut search.
+- A minimal core is tested on a non-trivial case and under a time limit (`minimal=False`).
+- A native `@cautious`/`@brave` claim is judged only from a search that ran to its end; if the search
+  was cut by a limit on seconds or answer sets, or by an interrupt, it is undecided, where it was reported as a pass or a
+  fail on the partial set.
+- A term nested thousands deep in a theory atom, an objective or a `#show` is checked or refused
+  instead of raising `RecursionError`.
+- Program text in the terminal report is shown with control characters escaped, so a program cannot
+  write terminal control sequences; JSON is unchanged.
+- A file that is not UTF-8 is a refusal of the request (`FAULT`, 2), not a traceback.
+- `pixi run check` prints the number of tests: pytest was given `-q` twice.
+
+[1.0.0]: https://github.com/GregoryGelfond/elenctic/releases/tag/v1.0.0

elenctic-1.0.0/Containerfile

@@ -0,0 +1,24 @@
+# syntax=docker/dockerfile:1
+# Minimal image whose only purpose is running elenctic (CLI entrypoint; clingo and clingcon included).
+#
+# Build:  docker build -f Containerfile -t elenctic .
+# Run:    docker run --rm -v "$PWD":/work:ro elenctic [elenctic arguments]
+# No published image; no CI build — ship the recipe only.
+
+FROM docker.io/library/python:3.14-slim-trixie@sha256:af8a5aa14780025dbfbcfbc81bd8a91ebd87711dd5b0f48ed71090949dd7cb1d AS build
+COPY --from=docker.io/astral/uv:0.13.7@sha256:96f40d3904aad8d0bd010539001d36c8e2188b981e1334471a90c4a1d93bb490 /uv /bin/uv
+ENV UV_COMPILE_BYTECODE=1 UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=never
+WORKDIR /src
+COPY pyproject.toml uv.lock README.md ./
+COPY src ./src
+COPY docs/reference/output-v1.schema.json ./docs/reference/output-v1.schema.json
+RUN uv venv /opt/elenctic \
+ && UV_PROJECT_ENVIRONMENT=/opt/elenctic uv sync --frozen --no-dev --extra theory --no-editable \
+ && /opt/elenctic/bin/python -c "import clingo, clingcon; import elenctic"
+
+FROM docker.io/library/python:3.14-slim-trixie@sha256:af8a5aa14780025dbfbcfbc81bd8a91ebd87711dd5b0f48ed71090949dd7cb1d
+COPY --from=build /opt/elenctic /opt/elenctic
+ENV PATH=/opt/elenctic/bin:$PATH
+USER 65534:65534
+WORKDIR /work
+ENTRYPOINT ["elenctic"]

elenctic-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gregory Gelfond
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elenctic-1.0.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: elenctic
+Version: 1.0.0
+Summary: Contracts and queries for answer set programs: a library first, a command line second
+Project-URL: Homepage, https://github.com/GregoryGelfond/elenctic
+Project-URL: Documentation, https://github.com/GregoryGelfond/elenctic/blob/main/docs/index.md
+Project-URL: Changelog, https://github.com/GregoryGelfond/elenctic/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/GregoryGelfond/elenctic/issues
+Author-email: Gregory Gelfond <gregory_gelfond@fastmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.14
+Requires-Dist: clingo<5.9,>=5.8.2
+Provides-Extra: theory
+Requires-Dist: clingcon<5.3,>=5.2.1; extra == 'theory'
+Description-Content-Type: text/markdown
+
+# elenctic
+
+[![CI](https://github.com/GregoryGelfond/elenctic/actions/workflows/ci.yml/badge.svg)](https://github.com/GregoryGelfond/elenctic/actions/workflows/ci.yml)
+[![Python 3.14 | 3.15](https://img.shields.io/badge/python-3.14%20%7C%203.15-blue)](https://www.python.org/downloads/)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+[![Checked with mypy](https://www.mypy-lang.org/static/mypy_badge.svg)](https://mypy-lang.org/)
+[![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv)
+[![Pixi](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/prefix-dev/pixi/main/assets/badge/v0.json)](https://pixi.sh)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![PyPI](https://img.shields.io/pypi/v/elenctic)](https://pypi.org/project/elenctic/)
+<!-- TODO(conda-forge): enable once the package is available on conda-forge.
+[![conda-forge](https://img.shields.io/conda/vn/conda-forge/elenctic)](https://anaconda.org/conda-forge/elenctic)
+-->
+
+A testing and analysis library for answer set programs, with a thin CLI. Claims about a program
+live in its own comments (`@expect`, `@count`, `@answer-set`, `@cautious`, `@brave`, `@query`,
+`@cost`) and are checked under clingo or clingcon.
+
+*Elenctic*, from Greek ἐλεγκτικός (ἔλεγχος, *elenchos*), "serving to refute by
+cross-examination": the Socratic elenchus. A contract is a thesis about the program; `FAIL` is
+its refutation, and `UNDECIDED` is aporia, an honest "cannot say" rather than a false "no".
+
+## Install
+
+Requires Python 3.14+ and clingo 5.8. The optional `theory` extra pulls in clingcon 5.2 for
+contracts that declare `% @elenctic solver clingcon`.
+
+```bash
+# pip
+pip install elenctic
+pip install 'elenctic[theory]'
+
+# uv — as a project dependency, or as a tool on PATH
+uv add elenctic
+uv add 'elenctic[theory]'
+uv tool install elenctic
+uv tool install 'elenctic[theory]'
+
+# pixi — from PyPI
+pixi add --pypi elenctic
+pixi add --pypi 'elenctic[theory]'
+```
+
+<!-- TODO(conda-forge): enable once the package is available on conda-forge.
+```bash
+# pixi — from conda-forge
+pixi add elenctic
+
+# conda / mamba (conda-forge)
+conda install -c conda-forge elenctic
+mamba install -c conda-forge elenctic
+```
+-->
+
+From source, straight from Git or from a clone:
+
+```bash
+pip install 'elenctic[theory] @ git+https://github.com/GregoryGelfond/elenctic'
+
+git clone https://github.com/GregoryGelfond/elenctic && cd elenctic
+pip install '.[theory]'
+uv tool install '.[theory]'
+pixi install -e theory     # the locked environment
+```
+
+### Container
+
+No prebuilt image is published. The `Containerfile` is a local recipe: build it yourself with
+Docker or Podman, then mount a directory of `.lp` files and run a check.
+
+```bash
+docker build -f Containerfile -t elenctic .
+podman build -f Containerfile -t elenctic .
+
+docker run --rm -v "$PWD":/work:ro elenctic drinks.lp
+podman run --rm -v "$PWD":/work:ro elenctic drinks.lp
+```
+
+The image includes the `theory` extra (clingo and clingcon). The entrypoint is `elenctic`; pass
+the same arguments you would on the host.
+
+## Quick start
+
+Save this as `drinks.lp`:
+
+```
+% @expect sat
+% @count 2
+% @brave { tea, coffee }
+% @cautious { biscuit }
+% @query unknown { tea }
+{ tea; coffee } = 1.
+biscuit.
+#show tea/0.
+#show coffee/0.
+#show biscuit/0.
+```
+
+```bash
+$ elenctic drinks.lp
+1/1 passed
+```
+
+Change `@count 2` to `@count 3` and run again:
+
+```bash
+$ elenctic drinks.lp
+drinks.lp — FAIL
+  [FAIL] @count 3 (line 2): 3 expected, 2 distinct shown answer sets
+
+0/1 passed, 1 fail
+```
+
+`elenctic PATH…` is `elenctic test PATH…`. From Python the same check is silent and returns a
+value:
+
+```python
+from elenctic import Limits, Program, check
+
+report = check(Program.read("drinks.lp"), limits=Limits(max_seconds=10))
+```
+
+## Usage
+
+| | |
+|---|---|
+| `elenctic [test] PATH…` | check programs against their contracts ([reference](docs/reference/reference.md#command-line)) |
+| `--format full\|short\|json` | rustc multi-line diagnostics (default), one-line short, or JSON ([output](docs/reference/reference.md#output), [diagnostics](docs/reference/reference.md#diagnostics)) |
+| Exit `0` / `1` / `2` / `3` | claims hold, claim unmet, fault, internal error ([exit codes](docs/reference/reference.md#exit-codes)) |
+
+Claims with real command output: [docs/reference/examples.md](docs/reference/examples.md).
+Tutorial: [docs/tutorial/first-contract.md](docs/tutorial/first-contract.md). Full map:
+[docs/index.md](docs/index.md).
+
+## Develop
+
+```bash
+pixi install -e theory
+pixi run -e theory check   # format, lint, strict types, import contracts, tests
+pixi run -e py314 test     # or -e py315
+```
+
+`pixi run check` is the one gate; `./check.sh` runs it. `uv.lock` is tracked so
+`uv sync --locked` reproduces the same dependencies.
+
+## License
+
+Licensed under the [MIT license](LICENSE). Changes are in the [changelog](CHANGELOG.md).