isitright 0.1.0.dev0__tar.gz → 0.1.0.dev5__tar.gz

{isitright-0.1.0.dev0 → isitright-0.1.0.dev5}/.github/workflows/ci.yml

@@ -9,10 +9,11 @@ permissions:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
       matrix:
+        os: [ubuntu-latest, windows-latest]
         python-version: ["3.11", "3.12", "3.13"]
     steps:
       - uses: actions/checkout@v4
@@ -20,12 +21,14 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
           enable-cache: true
-      - run: uv sync --extra dev
+      - run: uv sync --locked --extra dev
       - run: uv run ruff check .
       - run: uv run mypy src
+      - run: uv run python tools/export_schemas.py --check
       - run: uv run pytest
       - run: uv build
       - name: Verify wheel imports without network
+        if: runner.os == 'Linux'
         shell: bash
         run: |
           uv pip install --reinstall --no-deps dist/*.whl

{isitright-0.1.0.dev0 → isitright-0.1.0.dev5}/.github/workflows/publish.yml

@@ -16,9 +16,10 @@ jobs:
         with:
           python-version: "3.11"
           enable-cache: true
-      - run: uv sync --extra dev
+      - run: uv sync --locked --extra dev
       - run: uv run ruff check .
       - run: uv run mypy src
+      - run: uv run python tools/export_schemas.py --check
       - run: uv run pytest
       - run: uv build
       - run: uv run python -m twine check dist/*
@@ -65,6 +66,7 @@ jobs:
       - name: Install runtime dependencies from PyPI
         run: >-
           python -m pip install
+          "jsonschema>=4.23,<5"
           "pydantic>=2.10,<3"
           "pyyaml>=6.0.2,<7"
           "sqlglot>=27,<29"

{isitright-0.1.0.dev0 → isitright-0.1.0.dev5}/.gitignore

@@ -7,6 +7,7 @@ __pycache__/
 .ruff_cache/
 .venv/
 .tools/
+.test-tmp/
 build/
 dist/
 htmlcov/

isitright-0.1.0.dev5/.hypothesis/.gitignore

@@ -0,0 +1,9 @@
+# This .gitignore file was automatically created by Hypothesis. Hypothesis gitignores
+# .hypothesis by default, because we generally recommend that .hypothesis not be checked
+# into version control.
+#
+# If you *would* like to check .hypothesis into version control, you should delete this
+# file. Hypothesis will not re-create this .gitignore unless .hypothesis is deleted (and
+# if it does, that's a bug - please report it!)
+
+*

isitright-0.1.0.dev5/.hypothesis/constants/138e20931e4591f0

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/comparison.py
+# hypothesis_version: 6.170.8
+
+['column names differ']

isitright-0.1.0.dev5/.hypothesis/constants/13bb09d05f9f2565

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/minimize.py
+# hypothesis_version: 6.170.8
+
+[100, '"', '""', "'", "''", '(-1e999)', '(1e999)', ', ', ':memory:', ';', 'BEGIN;', "CAST('NaN' AS REAL)", 'COMMIT;', 'NULL', 'required']

isitright-0.1.0.dev5/.hypothesis/constants/2ce41665bf5d28a0

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/sql_analysis.py
+# hypothesis_version: 6.170.8
+
+[', ', 'Alter', 'Attach', 'Command', 'Commit', 'Create', 'Delete', 'Detach', 'Drop', 'Insert', 'Merge', 'Pragma', 'Rollback', 'Transaction', 'Update', 'Use', 'distinct', 'order', 'sqlite']

isitright-0.1.0.dev5/.hypothesis/constants/5a4eb57a5003d8fd

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/models.py
+# hypothesis_version: 6.170.8
+
+[1e-12, 1e-09, 30.0, 100, 500, 10000, '0.1', 'AMBIGUOUS_TASK', 'BOTH_DEFECTIVE', 'CANDIDATE_DEFECT', 'COUNTEREXAMPLE_FOUND', 'DOMAIN_VALIDATED', 'INCONCLUSIVE', 'INDETERMINATE', 'INVALID', 'NOT_ASSESSED', 'REFERENCE_DEFECT', 'SCHEMA_VALID_ONLY', 'UNDETERMINED', 'UNSUPPORTED', 'after', 'any-counterexample', 'auto', 'before', 'binary', 'boolean', 'both', 'by_name', 'candidate_sql', 'case_id', 'date', 'datetime', 'decimal', 'engine_specific', 'exact', 'float', 'forbid', 'headline', 'integer', 'isclose', 'json', 'markdown', 'metadata', 'names_and_positions', 'none', 'null', 'ordered', 'positional', 'question', 'reference_sql', 'text', 'time', 'unordered']

isitright-0.1.0.dev5/.hypothesis/constants/60aa59f228998242

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/reports.py
+# hypothesis_version: 6.170.8
+
+['## Errors', '## Ranked cases', '## Totals', '### Candidate output', '### Reference output', '-_', '_', '```', '```json', 'case_report.json', 'case_report.md', 'cases', 'counterexample.sql', 'json', 'not determined', 'suite_report.json', 'suite_report.md', 'utf-8']

isitright-0.1.0.dev5/.hypothesis/constants/6212aba6bd141f0d

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/search.py
+# hypothesis_version: 6.170.8
+
+['comparison_ambiguous', 'counterexample.sql', 'domain_constraint', 'query results differ', 'query_error', 'sqlite_constraint']

isitright-0.1.0.dev5/.hypothesis/constants/62ee6945b12f58df

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/sqlite_sandbox.py
+# hypothesis_version: 6.170.8
+
+[100, 10000, ':memory:', 'BLOB', 'INTEGER', 'NULL', 'REAL', 'SQLITE_ALTER_TABLE', 'SQLITE_ANALYZE', 'SQLITE_ATTACH', 'SQLITE_CREATE_INDEX', 'SQLITE_CREATE_TABLE', 'SQLITE_CREATE_VIEW', 'SQLITE_CREATE_VTABLE', 'SQLITE_DELETE', 'SQLITE_DETACH', 'SQLITE_DROP_INDEX', 'SQLITE_DROP_TABLE', 'SQLITE_DROP_TRIGGER', 'SQLITE_DROP_VIEW', 'SQLITE_DROP_VTABLE', 'SQLITE_INSERT', 'SQLITE_PRAGMA', 'SQLITE_REINDEX', 'SQLITE_SAVEPOINT', 'SQLITE_TRANSACTION', 'SQLITE_UPDATE', 'SQLiteSandbox', 'TEXT', 'ascii', 'interrupted', 'load_extension', 'ok', 'unknown']

isitright-0.1.0.dev5/.hypothesis/constants/6d9a121e66990019

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/__init__.py
+# hypothesis_version: 6.170.8
+
+['AttributionStatus', 'CandidateStateView', 'CanonicalValue', 'CanonicalValueKind', 'CaseResult', 'CheckConfig', 'EffectiveOrdering', 'EquivalenceStatus', 'FailOnPolicy', 'FloatComparisonMode', 'InputError', 'OrderingPolicy', 'ReportFormat', 'StateValidityStatus', 'SuiteCase', 'SuiteResult', 'ValidationFinding', 'ValidatorResult', 'ValidatorStatus', '__version__', 'check', 'check_suite']

isitright-0.1.0.dev5/.hypothesis/constants/73fff1d137b8fc55

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/schema.py
+# hypothesis_version: 6.170.8
+
+[]

isitright-0.1.0.dev5/.hypothesis/constants/8852c69b1b671205

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/suite.py
+# hypothesis_version: 6.170.8
+
+['utf-8']

isitright-0.1.0.dev5/.hypothesis/constants/8c7d64892d6df551

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/validation.py
+# hypothesis_version: 6.170.8
+
+['INDETERMINATE', 'INVALID', 'VALID']

isitright-0.1.0.dev5/.hypothesis/constants/932c5ef926e9db10

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/__about__.py
+# hypothesis_version: 6.170.8
+
+['0.1.0.dev5']

isitright-0.1.0.dev5/.hypothesis/constants/95e21ddbbfc96db7

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/generation.py
+# hypothesis_version: 6.170.8
+
+[100, '"', '""', '.', '0123456789', 'A', 'BLOB', 'CHAR', 'CLOB', 'DEC', 'DOUB', 'FLOA', 'INT', 'NUM', 'REAL', 'TEXT', '\\^\\[A-Z\\]\\{(\\d+)\\}\\$', 'aggregation', 'boundary', 'const', 'duplicate', 'enum', 'filtering', 'integer', 'isitright', 'items', 'join', 'minLength', 'minimum', 'null', 'number', 'pattern', 'properties', 'string', 'type']

isitright-0.1.0.dev5/.hypothesis/constants/a535a77ea503a2af

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/constraints.py
+# hypothesis_version: 6.170.8
+
+['"', '""', '$', '/', 'sqlite', 'utf-8']

isitright-0.1.0.dev5/.hypothesis/constants/b279a7097109fb82

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/api.py
+# hypothesis_version: 6.170.8
+
+[1024, '-', 'AMBIGUOUS_COMPARISON', 'CASE_INTERNAL_ERROR', 'QUERY_ERROR', 'QUERY_RESOURCE_LIMIT', 'QUERY_TIMEOUT', 'UNSUPPORTED_SQL', '_', 'candidate', 'case', 'case_id', 'cases', 'cases_file', 'comparison', 'constraints', 'counterexample.sql', 'database', 'domain-validated', 'effective_ordering', 'input', 'metadata', 'original_state', 'query results differ', 'rb', 'reference', 'schema-valid', 'seed', 'utf-8']

isitright-0.1.0.dev5/.hypothesis/constants/ba4514884b02f405

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/.venv/bin/pytest
+# hypothesis_version: 6.170.8
+
+['-script.pyw', '.exe', '__main__']

isitright-0.1.0.dev5/.hypothesis/constants/e28b89c0245e60b9

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/replay.py
+# hypothesis_version: 6.170.8
+
+['--fixture', '--report', ':memory:', 'SQLITE_ALTER_TABLE', 'SQLITE_ANALYZE', 'SQLITE_ATTACH', 'SQLITE_CREATE_VIEW', 'SQLITE_CREATE_VTABLE', 'SQLITE_DELETE', 'SQLITE_DETACH', 'SQLITE_DROP_INDEX', 'SQLITE_DROP_TABLE', 'SQLITE_DROP_TRIGGER', 'SQLITE_DROP_VIEW', 'SQLITE_DROP_VTABLE', 'SQLITE_REINDEX', '__main__', 'candidate_result', 'defer_foreign_keys', 'foreign_keys', 'json', 'load_extension', 'reference_result', 'reproduced', 'utf-8']

isitright-0.1.0.dev5/.hypothesis/constants/e8b7cda348f27b24

@@ -0,0 +1,4 @@
+# file: /home/runner/work/isitright/isitright/src/isitright/cli.py
+# hypothesis_version: 6.170.8
+
+[1e-12, 1e-09, 0.001, 30.0, 100, 500, 10000, '--candidate', '--constraints', '--format', '--reference', '--version', 'Show version.', '__main__', 'artifacts/check', 'artifacts/suite', 'check', 'isitright', 'suite', 'utf-8']

isitright-0.1.0.dev5/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes are documented here. The project follows semantic versioning;
+development releases may still refine the versioned `0.1` report contract before
+the stable `0.1.0` release.
+
+## 0.1.0.dev5 — Stage 4 candidate
+
+- Added SQLite authorizer defense in depth and configurable result-row limits.
+- Added property-based comparator tests and SQLite schema regression coverage.
+- Added checked-in JSON Schemas with automated freshness verification.
+- Expanded CI to Python 3.11–3.13 on Linux and Windows.
+- Documented the supported SQL surface, known limitations, contribution workflow,
+  security policy, and release process.
+
+## 0.1.0.dev4 — Stage 3
+
+- Added constraint-preserving minimization, suites, deterministic reproduction,
+  offline replay, ranked reports, and `--fail-on` policies.
+
+## 0.1.0.dev3 — Stage 2
+
+- Added constraint-aware generated-state search across six mutation families.
+
+## 0.1.0.dev2 — Stage 1
+
+- Added safe SQLite execution and policy-driven result comparison.
+
+## 0.1.0.dev0 — Stage 0
+
+- Established package, CLI, report contracts, fixtures, tests, and CI.

isitright-0.1.0.dev5/CONTRIBUTING.md

@@ -0,0 +1,33 @@
+# Contributing
+
+Thank you for helping improve `isitright`.
+
+## Development setup
+
+Python 3.11 or newer and `uv` are required.
+
+```console
+uv sync --locked --extra dev
+uv run ruff check .
+uv run mypy src
+uv run python tools/export_schemas.py --check
+uv run pytest
+uv build
+```
+
+Tests must run offline after dependencies are installed and must not require API
+keys. Add a regression test for every bug fix. Changes to report models require
+running `uv run python tools/export_schemas.py` and committing the updated files in
+`schemas/`.
+
+## Pull requests
+
+- Branch from the current `main` branch and keep changes focused.
+- Preserve the separation between observed disagreement, state validity, and defect
+  attribution.
+- Do not describe bounded agreement as equivalence.
+- Document user-visible behavior and known limitations.
+- Confirm Ruff, strict mypy, tests, schema freshness, and package builds locally.
+
+Fixture semantics require owner review because they define expected behavior rather
+than merely exercising implementation details.

isitright-0.1.0.dev5/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: isitright
+Version: 0.1.0.dev5
+Summary: Evidence-first stress testing for text-to-SQL evaluations
+Project-URL: Repository, https://github.com/isitright-ai/isitright
+Author: isitright contributors
+License: MIT License
+        
+        Copyright (c) 2026 isitright contributors
+        
+        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.
+        
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: pyyaml<7,>=6.0.2
+Requires-Dist: sqlglot<29,>=27
+Requires-Dist: typer<1,>=0.15
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.2.2; extra == 'dev'
+Requires-Dist: hypothesis<7,>=6.115; extra == 'dev'
+Requires-Dist: mypy<2,>=1.14; extra == 'dev'
+Requires-Dist: pytest-cov<8,>=6; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3; extra == 'dev'
+Requires-Dist: ruff<1,>=0.9; extra == 'dev'
+Requires-Dist: twine<7,>=6.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# isitright
+
+`isitright` is an evidence-first tool for stress-testing text-to-SQL evaluations.
+Given reference and candidate SQL, the v0.1 engine will search for a valid
+database state on which their outputs differ and emit a minimized, replayable
+counterexample. A disagreement is evidence, not automatic attribution of fault.
+
+## Current status: Stage 4 review gate
+
+The v0.1 candidate safely compares queries on the supplied SQLite database and runs
+a deterministic, schema-aware generated-state search. Search harvests referenced
+tables, columns, and literals and tries boundary, NULL, duplicate, join, filtering,
+and aggregation mutations in priority order.
+
+Every generated state is checked against SQLite integrity and foreign-key rules,
+an optional JSON Schema constraints document, and an optional trusted validator.
+Finding no divergence is reported as `AGREEMENT_ON_TESTED_STATES`; it is not a
+claim of equivalence. Findings are minimized across generated and background rows,
+revalidated, and exported as deterministic `counterexample.sql` files. Suite mode,
+ranked reports, and opt-in `--fail-on` policies are active.
+
+## Quick start
+
+```python
+from isitright import check
+
+result = check(
+    database="example.sqlite",
+    reference_sql="SELECT province FROM tribute ORDER BY province",
+    candidate_sql="SELECT DISTINCT province FROM tribute ORDER BY province",
+)
+print(result.headline)
+print(result.original_state.outputs_match)
+print(result.search.model_dump())
+```
+
+The CLI reads each query from a UTF-8 file and writes versioned JSON plus a concise
+Markdown rendering by default:
+
+```console
+isitright check --database example.sqlite --reference gold.sql \
+  --candidate agent.sql --output-dir artifacts/check
+```
+
+When a counterexample is found, replay the emitted fixture and verify both recorded
+outputs without touching the source database:
+
+```console
+cd artifacts/check
+python -m isitright.replay --report case_report.json --fixture counterexample.sql
+```
+
+## Development
+
+Python 3.11 or newer is required. With `uv` installed:
+
+```console
+uv sync --extra dev
+uv run ruff check .
+uv run mypy src
+uv run pytest
+uv build
+```
+
+The package exposes single-case and JSONL suite commands:
+
+```console
+isitright --version
+isitright check --help
+isitright suite --help
+```
+
+```console
+isitright suite --database example.sqlite --cases cases.jsonl \
+  --output-dir artifacts/suite --fail-on domain-counterexample
+```
+
+Suite cases run independently and are ranked with domain-validated findings first,
+then schema-only findings, inconclusive/unsupported cases, and observed agreement.
+Both commands accept `--fail-on none`, `domain-counterexample`, or
+`any-counterexample`; a matched opt-in policy exits with code `3` after artifacts
+have been written.
+
+The Stage 4 preview is versioned `0.1.0.dev5`. It is intentionally a development
+release and must not be presented as the complete v0.1 search engine.
+
+## Contract highlights
+
+- Result statuses keep observed equivalence, state validity, and attribution separate.
+- Unordered query results are compared as multisets, preserving duplicates.
+- Automatic ordering honors a top-level `ORDER BY` on either query; otherwise results
+  are unordered.
+- Engine-native values are normalized into explicit, portable canonical kinds.
+- JSON Schema and trusted callback validation are applied before generated states
+  are admitted, and every rejection is counted by reason.
+- Reports use schema version `0.1`; package versioning remains pre-release until the
+  v0.1 engine is complete.
+
+Generation is intentionally bounded and lightweight. It creates small
+insertions by adapting existing rows or synthesizing complete rows for empty
+referenced tables, including required foreign-key parent rows. It does not perform
+AST-diff-guided search or prove that exhausted candidates cover every admissible
+state. Minimization is also bounded; if its budget is exhausted, the smallest
+verified state found so far is returned with `minimization_complete: false`.
+
+See [the contract reference](docs/contracts.md) and
+[the fixture proposal](tests/fixtures/proposals/README.md). The precise supported
+SQL surface and known limitations are documented in
+[Supported SQL and limitations](docs/supported-sql.md).
+
+Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Security issues
+should follow the private reporting process in [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT
+

isitright-0.1.0.dev5/README.md

@@ -0,0 +1,117 @@
+# isitright
+
+`isitright` is an evidence-first tool for stress-testing text-to-SQL evaluations.
+Given reference and candidate SQL, the v0.1 engine will search for a valid
+database state on which their outputs differ and emit a minimized, replayable
+counterexample. A disagreement is evidence, not automatic attribution of fault.
+
+## Current status: Stage 4 review gate
+
+The v0.1 candidate safely compares queries on the supplied SQLite database and runs
+a deterministic, schema-aware generated-state search. Search harvests referenced
+tables, columns, and literals and tries boundary, NULL, duplicate, join, filtering,
+and aggregation mutations in priority order.
+
+Every generated state is checked against SQLite integrity and foreign-key rules,
+an optional JSON Schema constraints document, and an optional trusted validator.
+Finding no divergence is reported as `AGREEMENT_ON_TESTED_STATES`; it is not a
+claim of equivalence. Findings are minimized across generated and background rows,
+revalidated, and exported as deterministic `counterexample.sql` files. Suite mode,
+ranked reports, and opt-in `--fail-on` policies are active.
+
+## Quick start
+
+```python
+from isitright import check
+
+result = check(
+    database="example.sqlite",
+    reference_sql="SELECT province FROM tribute ORDER BY province",
+    candidate_sql="SELECT DISTINCT province FROM tribute ORDER BY province",
+)
+print(result.headline)
+print(result.original_state.outputs_match)
+print(result.search.model_dump())
+```
+
+The CLI reads each query from a UTF-8 file and writes versioned JSON plus a concise
+Markdown rendering by default:
+
+```console
+isitright check --database example.sqlite --reference gold.sql \
+  --candidate agent.sql --output-dir artifacts/check
+```
+
+When a counterexample is found, replay the emitted fixture and verify both recorded
+outputs without touching the source database:
+
+```console
+cd artifacts/check
+python -m isitright.replay --report case_report.json --fixture counterexample.sql
+```
+
+## Development
+
+Python 3.11 or newer is required. With `uv` installed:
+
+```console
+uv sync --extra dev
+uv run ruff check .
+uv run mypy src
+uv run pytest
+uv build
+```
+
+The package exposes single-case and JSONL suite commands:
+
+```console
+isitright --version
+isitright check --help
+isitright suite --help
+```
+
+```console
+isitright suite --database example.sqlite --cases cases.jsonl \
+  --output-dir artifacts/suite --fail-on domain-counterexample
+```
+
+Suite cases run independently and are ranked with domain-validated findings first,
+then schema-only findings, inconclusive/unsupported cases, and observed agreement.
+Both commands accept `--fail-on none`, `domain-counterexample`, or
+`any-counterexample`; a matched opt-in policy exits with code `3` after artifacts
+have been written.
+
+The Stage 4 preview is versioned `0.1.0.dev5`. It is intentionally a development
+release and must not be presented as the complete v0.1 search engine.
+
+## Contract highlights
+
+- Result statuses keep observed equivalence, state validity, and attribution separate.
+- Unordered query results are compared as multisets, preserving duplicates.
+- Automatic ordering honors a top-level `ORDER BY` on either query; otherwise results
+  are unordered.
+- Engine-native values are normalized into explicit, portable canonical kinds.
+- JSON Schema and trusted callback validation are applied before generated states
+  are admitted, and every rejection is counted by reason.
+- Reports use schema version `0.1`; package versioning remains pre-release until the
+  v0.1 engine is complete.
+
+Generation is intentionally bounded and lightweight. It creates small
+insertions by adapting existing rows or synthesizing complete rows for empty
+referenced tables, including required foreign-key parent rows. It does not perform
+AST-diff-guided search or prove that exhausted candidates cover every admissible
+state. Minimization is also bounded; if its budget is exhausted, the smallest
+verified state found so far is returned with `minimization_complete: false`.
+
+See [the contract reference](docs/contracts.md) and
+[the fixture proposal](tests/fixtures/proposals/README.md). The precise supported
+SQL surface and known limitations are documented in
+[Supported SQL and limitations](docs/supported-sql.md).
+
+Contributions are welcome; see [CONTRIBUTING.md](CONTRIBUTING.md). Security issues
+should follow the private reporting process in [SECURITY.md](SECURITY.md).
+
+## License
+
+MIT
+

isitright-0.1.0.dev5/SECURITY.md

@@ -0,0 +1,21 @@
+# Security policy
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities privately through GitHub's **Security →
+Report a vulnerability** workflow for `isitright-ai/isitright`. Do not open a public
+issue before maintainers have had an opportunity to investigate.
+
+Include the affected version, a minimal reproduction, expected impact, and any known
+workarounds. Maintainers will acknowledge the report, assess severity, and coordinate
+disclosure and a patched release.
+
+## Security boundary
+
+`isitright` treats SQL and database files as untrusted inputs, but programmatic
+validator callbacks as trusted local code. It does not load Python callbacks from
+constraint documents. Analysis uses disposable in-memory SQLite copies with parser,
+query-only, authorizer, deadline, and result-size controls. These controls reduce
+risk. Replay separately authorizes only the DDL and inserts needed by generated
+fixtures and denies database attachment and extension loading. These controls are
+not a general sandbox for hostile native SQLite extensions.