corvid-python 0.3.3__cp311-abi3-win_amd64.whl

corvid/__init__.py

@@ -0,0 +1,50 @@
+"""corvid — the Python binding for the corvid embedded database.
+
+The whole public surface is implemented natively (the pyo3 crate in
+this repo, built by maturin as ``corvid._native``): the ``Db`` /
+``Collection`` / ``Query`` classes, the ``field()`` predicate builder,
+and the ``CorvidError`` exception. This package re-exports it; the
+type stubs in ``__init__.pyi`` (shipped with ``py.typed``) carry the
+full typing.
+
+Engine semantics, the value mapping, and the error-code table are
+documented in docs/PLAN.md and README.md in the repository.
+"""
+
+from corvid._native import (
+    CorvidError,
+    Db,
+    ErrorCode,
+    FieldRef,
+    GeoHit,
+    Page,
+    Predicate,
+    Query,
+    Row,
+    SchemaField,
+    and_,
+    field,
+    ffi_version,
+    not_,
+    or_,
+)
+
+__all__ = [
+    "CorvidError",
+    "Db",
+    "ErrorCode",
+    "FieldRef",
+    "GeoHit",
+    "Page",
+    "Predicate",
+    "Query",
+    "Row",
+    "SchemaField",
+    "and_",
+    "field",
+    "ffi_version",
+    "not_",
+    "or_",
+]
+
+__version__ = "0.1.0"

corvid/__init__.pyi

@@ -0,0 +1,395 @@
+"""Type stubs for the corvid package — the fully typed public API.
+
+The implementations are native (pyo3); this stub is the typing source
+of truth, shipped with ``py.typed``.
+
+The value mapping (docs/PLAN.md §4):
+
+==================  ===============  ===================================
+Python (in)         engine Value     Python (out)
+==================  ===============  ===================================
+``None``            Null             ``None``
+``bool``            Bool             ``bool``
+``int``             Int (full i64)   ``int`` (arbitrary precision)
+``float``           Float            ``float`` (f64 bits preserved —
+                                     NaN payloads, ``-0.0``, ``±inf``)
+``str``             Text             ``str``
+``bytes``/``bytes`` Bytes            ``bytes``
+``array('f')``      Vector           ``array('f')`` (f32-exact)
+``list``/``tuple``  Array            ``list``
+``dict``            Map              ``dict`` (engine key order)
+==================  ===============  ===================================
+
+Out-of-i64 ints raise ``CorvidError`` code 12 (``ErrorCode.INVALID_ARGUMENT``).
+"""
+
+from array import array
+from collections.abc import Callable, Sequence
+from typing import Literal, TypeAlias, Union
+
+__all__ = [
+    "CorvidError",
+    "Db",
+    "ErrorCode",
+    "FieldRef",
+    "GeoHit",
+    "Page",
+    "Predicate",
+    "Query",
+    "Row",
+    "SchemaField",
+    "and_",
+    "field",
+    "ffi_version",
+    "not_",
+    "or_",
+]
+
+__version__: str
+
+#: A document key: `str` (UTF-8) or `bytes` (raw; non-UTF-8 keys come back as `bytes`).
+Key: TypeAlias = Union[str, bytes]
+#: A float32 vector — exactly ``array.array('f', ...)`` (other typecodes are rejected).
+Vector: TypeAlias = array[float]
+#: Any corvid document value (see the table in the module docstring).
+CorvidValue: TypeAlias = Union[
+    None,
+    bool,
+    int,
+    float,
+    str,
+    bytes,
+    Vector,
+    Sequence["CorvidValue"],
+    dict[str, "CorvidValue"],
+]
+#: All field types a schema may declare.
+FieldType: TypeAlias = Literal["any", "bool", "int", "float", "text", "bytes", "vector", "array", "map"]
+Metric: TypeAlias = Literal["cosine", "dot", "l2"]
+Quantization: TypeAlias = Literal["none", "binary", "scalar"]
+
+#: The C-ABI FFI generation this binding covers (docs/FFI.md §1.3; value 1).
+def ffi_version() -> int: ...
+
+class CorvidError(Exception):
+    """Every engine failure — carries the C-ABI error ``code`` (1..=19,
+    see :class:`ErrorCode`) and the engine ``message``."""
+
+    code: int
+    message: str
+
+class ErrorCode:
+    """The frozen C-ABI error-code table (docs/FFI.md §1.3) — never renumbered."""
+
+    DATABASE: int
+    TRANSACTION: int
+    TABLE: int
+    STORAGE: int
+    COMMIT: int
+    SET_DURABILITY: int
+    COMPACTION: int
+    DECODE: int
+    CORRUPT_INDEX: int
+    RESERVED_COLLECTION: int
+    INVALID_NAME: int
+    INVALID_ARGUMENT: int
+    INCOMPATIBLE_FORMAT: int
+    EMPTY_INDEX_TRAINING: int
+    SCHEMA_VIOLATION: int
+    INVALID_DUMP: int
+    BACKUP_TARGET_EXISTS: int
+    IO: int
+    BUSY: int
+
+class SchemaField:
+    """One declared schema field (``Collection.set_schema`` / ``Collection.schema``)."""
+
+    name: str
+    ty: FieldType
+    required: bool
+    unique: bool
+
+    def __init__(self, name: str, ty: FieldType, required: bool = False, unique: bool = False) -> None: ...
+
+class Row:
+    """One query result row (``Query.run``)."""
+
+    key: Key
+    #: RRF-fused rank score (``0.0`` for pure filter/order queries).
+    score: float
+    #: The full (or projected) stored document.
+    document: CorvidValue
+
+class Page:
+    """One page of keyset-paginated rows (``Collection.page``)."""
+
+    #: The ``(key, doc)`` rows, in key order.
+    rows: list[tuple[Key, CorvidValue]]
+    #: The resume cursor (pass as the next call's ``after``), or ``None`` at the end.
+    next: Key | None
+
+class GeoHit:
+    """One geo-search hit (``Collection.geo_within_radius`` / ``geo_within_bbox`` / ``geo_nearest``)."""
+
+    key: Key
+    #: Distance from the query center in km (the ``0.0`` sentinel for bbox searches).
+    distance_km: float
+    document: CorvidValue
+
+class Predicate:
+    """An opaque predicate (built by ``field()…`` / ``and_`` / ``or_`` / ``not_``).
+    Pass to ``Query.filter()`` or ``Collection.delete_where()``."""
+
+class FieldRef:
+    """A field-path predicate builder: ``field('a.b').gt(2)`` — the dotted
+    path may descend maps and (by integer segment) arrays."""
+
+    def eq(self, value: CorvidValue) -> Predicate:
+        """Field equals ``value`` (engine semantic equality: ``NaN == NaN``,
+        ``-0.0 == 0.0``, numeric interop across int/float)."""
+
+    def ne(self, value: CorvidValue) -> Predicate: ...
+    def lt(self, value: CorvidValue) -> Predicate: ...
+    def le(self, value: CorvidValue) -> Predicate: ...
+    def gt(self, value: CorvidValue) -> Predicate: ...
+    def ge(self, value: CorvidValue) -> Predicate: ...
+    def exists(self) -> Predicate:
+        """The path exists (any value, including ``None``, at the path)."""
+
+    def in_(self, values: Sequence[CorvidValue]) -> Predicate: ...
+    def between(self, low: CorvidValue, high: CorvidValue) -> Predicate: ...
+    def starts_with(self, prefix: str) -> Predicate: ...
+    def contains(self, substring: str) -> Predicate: ...
+    def within_km(self, lat: float, lon: float, radius_km: float) -> Predicate: ...
+
+def field(path: str) -> FieldRef:
+    """Build a predicate over a (dotted) field path."""
+
+def and_(*preds: Predicate) -> Predicate:
+    """Logical AND (Python keyword → trailing underscore)."""
+
+def or_(*preds: Predicate) -> Predicate:
+    """Logical OR."""
+
+def not_(pred: Predicate) -> Predicate:
+    """Logical NOT."""
+
+class Db:
+    """A database handle. ``Db('app.redb')`` / ``Db.open(path)`` for a file,
+    ``Db()`` / ``Db.open_memory()`` for a private in-memory database."""
+
+    def __init__(self, path: str | None = None) -> None: ...
+
+    @classmethod
+    def open(cls, path: str) -> Db: ...
+    @classmethod
+    def open_memory(cls) -> Db: ...
+
+    def __enter__(self) -> Db: ...
+    def __exit__(self, *exc: object) -> None: ...
+
+    def collection(self, name: str) -> Collection:
+        """Acquire a collection handle (lazily created by the engine on first
+        write; names are validated at write time)."""
+
+    def collections(self) -> list[str]:
+        """The names of the database's collections, in engine order."""
+
+    def backup(self, path: str) -> None:
+        """Copy the database to ``path`` (which must not already exist)."""
+
+    def dump_to_path(self, path: str) -> None:
+        """Dump the whole database (documents, indexes, schemas, TTLs, edges,
+        auto-id counters) to ``path``."""
+
+    def load_from_path(self, path: str) -> None:
+        """Replay a dump file into this database (merging)."""
+
+    def load_from_path_with_renames(self, path: str, renames: dict[str, str]) -> None:
+        """Replay a dump file, renaming collections per ``renames``
+        (``{from: to}``; targets validated before the stream is read)."""
+
+    def compact(self) -> bool:
+        """Compact the database file. Requires quiescence: every
+        ``Collection``/``Query`` derived from this db must be closed (or have
+        executed), otherwise a ``Busy`` ``CorvidError`` (code 19) is raised.
+        Returns whether any data was moved out."""
+
+    def close(self) -> None:
+        """Close the handle (idempotent). Derived handles may legitimately
+        outlive it — the engine lives until the last handle drops."""
+
+class Collection:
+    """A collection handle (a context manager; ``close()`` is idempotent)."""
+
+    name: str
+
+    def __enter__(self) -> Collection: ...
+    def __exit__(self, *exc: object) -> None: ...
+    def __len__(self) -> int: ...
+
+    # -- mutations -----------------------------------------------------------
+    def insert(self, key: Key, doc: CorvidValue) -> None:
+        """Insert (replace) ``doc`` at ``key``."""
+
+    def insert_many(self, entries: Sequence[tuple[Key, CorvidValue]]) -> None:
+        """Bulk atomic insert (``put_many``): one transaction; a violating
+        pair rolls the whole batch back."""
+
+    def insert_auto(self, doc: CorvidValue) -> Key:
+        """Insert with an engine-generated key (20-digit, strictly monotonic
+        per collection); returns the key."""
+
+    def update(
+        self,
+        key: Key,
+        fn: Callable[[CorvidValue | None], CorvidValue | None],
+    ) -> None:
+        """Read-modify-write: ``fn`` receives the current document (or ``None``
+        when absent) and returns the new document — ``None`` to delete. A
+        raising callback aborts with code 12 and writes nothing. ``fn`` must
+        NOT call methods on this same Collection (non-reentrant handle lock)."""
+
+    def patch(self, key: Key, patch: CorvidValue) -> None:
+        """Merge the top-level fields of ``patch`` into the document at ``key``
+        (creating it if absent)."""
+
+    def compare_and_set(
+        self, key: Key, expected: CorvidValue | None, replacement: CorvidValue | None
+    ) -> bool:
+        """Atomically write ``replacement`` only if the current value equals
+        ``expected`` (``None`` = must be absent; ``replacement=None`` deletes
+        on match). Equality is the engine's semantic equality. Returns whether
+        the write was applied."""
+
+    def delete(self, key: Key) -> bool: ...
+    def delete_where(self, pred: Predicate) -> int: ...
+    def delete_batch(self, keys: Sequence[Key]) -> int: ...
+
+    # -- TTL -----------------------------------------------------------------
+    def insert_with_ttl(self, key: Key, doc: CorvidValue, expires_at: int) -> None:
+        """Insert with an expiry instant (``expires_at``, epoch units of your choosing)."""
+
+    def set_ttl(self, key: Key, expires_at: int) -> None: ...
+    def get_ttl(self, key: Key) -> int | None: ...
+    def purge_expired(self, now: int) -> int: ...
+
+    # -- reads ---------------------------------------------------------------
+    def get(self, key: Key) -> CorvidValue | None: ...
+    def scan(self) -> list[tuple[Key, CorvidValue]]: ...
+    def scan_each(self, cb: Callable[[Key, CorvidValue], bool]) -> int:
+        """Stream with a callback ``fn(key, doc) -> bool`` — a falsy return
+        stops the walk early (not an error). Returns the rows visited. The
+        callback must NOT call methods on this same Collection."""
+
+    def page(self, after: Key | None = None, limit: int = 10) -> Page: ...
+    def is_empty(self) -> bool: ...
+
+    # -- indexes ---------------------------------------------------------------
+    def create_scalar_index(self, field: str) -> None: ...
+    def create_compound_index(self, fields: Sequence[str]) -> None: ...
+    def phrase_search(self, field: str, phrase: str, k: int) -> list[Row]:
+        """DIRECT positional phrase search (engine v0.3.0; no query builder):
+        consecutive, in-order analyzed tokens; stop words collapse out of
+        adjacency. Most relevant first, ties by key, up to ``k`` rows;
+        ``Row.score`` is the BM25 phrase sum. ``k == 0`` answers ``[]``.
+        """
+        ...
+    def create_text_index(self, field: str) -> None: ...
+    def create_text_index_ondisk(self, field: str) -> None: ...
+    def create_geo_index(self, field: str) -> None: ...
+    def create_vector_index(self, field: str, metric: Metric) -> None: ...
+    def create_vector_index_quantized(self, field: str, metric: Metric, quant: Quantization) -> None: ...
+    def create_vector_index_ondisk(self, field: str, metric: Metric) -> None: ...
+    def create_vector_index_ondisk_quantized(self, field: str, metric: Metric, quant: Quantization) -> None: ...
+    def create_vector_index_pq(self, field: str, metric: Metric, m: int, k: int) -> None:
+        """In-memory product-quantized HNSW index (``dim % m == 0`` required)."""
+
+    def create_vector_index_ondisk_pq(self, field: str, metric: Metric, m: int, k: int) -> None: ...
+
+    # -- schema ----------------------------------------------------------------
+    def set_schema(self, fields: Sequence[SchemaField]) -> None:
+        """Declare the collection's schema; replaces any previous one."""
+
+    def schema(self) -> list[SchemaField] | None: ...
+
+    # -- graph -----------------------------------------------------------------
+    # The native ``from`` parameter is a Python keyword — the stub spells it
+    # ``src``; pass edge endpoints positionally.
+    def link(self, src: Key, relation: str, to: Key) -> None: ...
+    def link_weighted(self, src: Key, relation: str, to: Key, weight: float) -> None: ...
+    def unlink(self, src: Key, relation: str, to: Key) -> bool: ...
+    def neighbors(self, src: Key, relation: str) -> list[Key]: ...
+    def in_neighbors(self, to: Key, relation: str) -> list[Key]: ...
+    def neighbors_weighted(self, src: Key, relation: str) -> list[tuple[Key, float]]: ...
+    def traverse(self, start: Key, relation: str, hops: int) -> list[Key]:
+        """BFS ``hops`` out over ``relation`` (cycle-safe)."""
+
+    # -- geo ---------------------------------------------------------------------
+    def geo_within_radius(self, field: str, lat: float, lon: float, radius_km: float) -> list[GeoHit]: ...
+    def geo_within_bbox(
+        self, field: str, min_lat: float, min_lon: float, max_lat: float, max_lon: float
+    ) -> list[GeoHit]: ...
+    def geo_nearest(self, field: str, lat: float, lon: float, k: int) -> list[GeoHit]: ...
+
+    # -- queries -------------------------------------------------------------------
+    def query(self) -> Query:
+        """Begin a fluent query over this collection (one execution per builder)."""
+
+    def close(self) -> None:
+        """Release the handle (idempotent); also runs on GC."""
+
+class Query:
+    """The fluent query builder (mirrors the engine's ``QueryBuilder``).
+    Fluent setters return the same builder — ``q.filter(...).vector(...).run()``.
+    The terminal ops (``run`` and every aggregation) consume the builder;
+    ``close()`` abandons it without executing."""
+
+    def __enter__(self) -> Query: ...
+    def __exit__(self, *exc: object) -> None: ...
+
+    def filter(self, pred: Predicate) -> Query:
+        """Restrict to documents matching ``pred`` (multiple filters AND together)."""
+
+    def vector(self, field: str, query: Vector, k: int, metric: Metric = "cosine") -> Query:
+        """Add a vector source (``query`` an ``array('f')``) contributing up to ``k`` candidates."""
+
+    def text(self, field: str, query: str, k: int) -> Query:
+        """Add a BM25 text source contributing up to ``k`` candidates."""
+
+    def fuse_rrf(self, k: float) -> Query:
+        """Set the Reciprocal Rank Fusion constant (default 60; validated at execution)."""
+
+    def rerank_mmr(self, lambda_: float) -> Query:
+        """Rerank fused candidates for diversity (``lambda`` in ``[0, 1]``)."""
+
+    def approx(self) -> Query:
+        """Prefer index-backed approximate execution where available."""
+
+    def limit(self, n: int) -> Query: ...
+    def offset(self, n: int) -> Query: ...
+    def order_by(self, field: str, descending: bool = False) -> Query: ...
+    def select(self, fields: Sequence[str]) -> Query:
+        """Project results to the named top-level fields."""
+
+    def run(self) -> list[Row]:
+        """Execute; rows as :class:`Row` objects (score ``0.0`` for pure
+        filter/order queries). Consumes the builder."""
+
+    def count(self) -> int:
+        """Count matching documents (sources/ranking/limit ignored). Consumes the builder."""
+
+    def count_distinct(self, field: str) -> int: ...
+    def sum(self, field: str) -> float: ...
+    def avg(self, field: str) -> float | None: ...
+    def min(self, field: str) -> CorvidValue | None: ...
+    def max(self, field: str) -> CorvidValue | None: ...
+    def group_count(self, field: str) -> dict[str, int]:
+        """Group counts in the engine's ascending order. Group keys are the
+        engine's formatting (text bare, int/float type-tagged ``i:1``/``f:0.5``)."""
+
+    def group_sum(self, group_field: str, value_field: str) -> dict[str, float]: ...
+    def group_avg(self, group_field: str, value_field: str) -> dict[str, float]: ...
+
+    def close(self) -> None:
+        """Abandon the builder without executing."""

corvid_python-0.3.3.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: corvid-python
+Version: 0.3.3
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Rust
+Classifier: Topic :: Database
+Classifier: Topic :: Database :: Database Engines/Servers
+License-File: LICENSE
+Summary: Python binding for the corvid embedded database — the engine compiled in via pyo3, exposed as idiomatic OOP
+Keywords: database,embedded,vector,search,ai
+Author: corvid-db
+License-Expression: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+
+# corvid-python
+
+Python binding for [corvid](https://github.com/corvid-db/corvid) — an
+embedded database with typed values, vector/text/hybrid search, graph
+edges, geo, TTL, and schemas. The engine is compiled in (a Rust pyo3
+crate pinned to an exact corvid release tag) and exposed as idiomatic
+synchronous OOP: `Db`, `Collection`, a fluent `Query` builder, and
+`field()` predicates. No SQL, no JSON, no serialization on the data
+path — values map natively (see the value mapping below).
+
+Its correctness story is the engine's **golden suite**: the same
+267-line fixture files the C ABI smoke harness runs are replayed
+against this binding's public API on every CI run
+(`tests/test_golden.py`).
+
+## Install
+
+Pending first publish: the package is **not on PyPI yet** — everything
+is prepared (maturin wheel config, one abi3 wheel per platform), and
+publishing waits on the first release tag (docs/PLAN.md §6). Until
+then, build from source — Python 3.11–3.14 (the floor is 3.11; CI
+exercises 3.14/3.13/3.12/3.11 on every wheel platform), Rust ≥ 1.88,
+and a C toolchain:
+
+```sh
+pip install maturin
+maturin develop --release    # into the active venv
+```
+
+The wheel is abi3 (cp311), so one wheel per platform covers every
+Python ≥ 3.11. Planned platform matrix: `linux-x64` /
+`linux-arm64` / `macos-arm64` / `windows-x64`.
+
+## Usage
+
+```python
+from array import array
+
+from corvid import Db, field
+
+db = Db.open("app.redb")               # or Db.open_memory()
+docs = db.collection("docs")
+
+docs.insert("p1", {
+    "title": "rust embedded database",
+    "kind": "doc",
+    "v": array("f", [1.0, 0.0]),
+})
+
+# hybrid retrieval: filter + vector + BM25, fused (RRF) + reranked (MMR)
+rows = (
+    docs.query()
+    .filter(field("kind").eq("doc"))
+    .vector("v", array("f", [1.0, 0.0]), 10, "cosine")
+    .text("title", "rust database", 10)
+    .fuse_rrf(60)
+    .rerank_mmr(1.0)
+    .limit(5)
+    .run()
+)                                      # [Row(key, score, document), ...]
+
+for row in rows:
+    print(row.key, row.score, row.document["title"])
+
+# predicates everywhere (queries and deletes)
+docs.delete_where(field("kind").eq("draft"))
+
+# scalar/compound/text/geo/vector indexes (incl. quantized + PQ + on-disk)
+docs.create_vector_index("v", "cosine")
+
+# TTL, graph, geo, schema, CAS, bulk writes, dump/backup/compact …
+docs.close()
+db.close()
+```
+
+Every failure raises a native `CorvidError` with the engine error
+`code` (the C ABI's frozen 1–19 table, exported as `ErrorCode`) and
+the engine `message`. Type stubs ship in-package (`py.typed`) — the
+public API is fully typed.
+
+## Examples
+
+Six runnable programs in [`examples/`](examples/) — one per concept,
+deterministic output, executed on every CI leg:
+
+| File | What it shows |
+| --- | --- |
+| `quickstart.py` | open, insert 3 docs, kNN vector query, print |
+| `hybrid.py` | filter + vector + BM25, RRF fusion, MMR rerank, limit |
+| `vector_index.py` | in-memory / on-disk / binary-quantized HNSW vs exact, reopen |
+| `text_search.py` | BM25 ranking, English + CJK (bigram segmentation) |
+| `graph.py` | link/neighbors/traverse + the delete cascade |
+| `geo.py` | radius / bbox / nearest-k over real coordinates (haversine km) |
+
+```sh
+maturin develop && python examples/hybrid.py
+```
+
+## Value mapping
+
+| Python | engine |
+| --- | --- |
+| `None`, `bool`, `str` | Null / Bool / Text |
+| `int` | Int (full i64 — out-of-range ints raise code 12) |
+| `float` | Float |
+| `bytes` / `bytearray` | Bytes |
+| `array('f')` | Vector (other typecodes are rejected) |
+| `list` / `tuple` | Array |
+| `dict` (str keys) | Map |
+
+Reading back: Int → `int` (arbitrary precision — no ±2^53 boundary,
+unlike the JS binding's number/BigInt split), Float → `float` with
+**f64 bits preserved exactly** — NaN payloads, `-0.0`, and `±inf` all
+round-trip bit-exactly (CPython floats are unboxed C doubles; pyo3
+copies them by value — the fidelity corner where V8 canonicalizes NaN
+payloads at the N-API boundary; Python has no such caveat). Vector →
+`array('f')` (f32-exact both directions), Map → `dict` in the
+engine's key order. Keys are `str` (UTF-8) or `bytes` (non-UTF-8 keys
+come back as `bytes`).
+
+Python marks the Int/Float distinction natively (`2` is an int, `2.0`
+a float), so the mapping is a clean bijection — there is no
+Int/Float collapse and no typed-float escape hatch (the JS binding
+needs `CorvidFloat` for CAS/unique/group-key corners).
+
+## Surface manifest (docs/SURFACE.tsv)
+
+Every construct of the engine's public surface (the radar-enforced list the
+engine publishes as `scripts/bindings/surface.tsv` at each release tag) is
+resolved in `docs/SURFACE.tsv`: the Python API exposing it plus the test that
+proves it (golden fixture line references), or `N/A` + reason where the v1
+binding deliberately does not expose it. `scripts/surface-gate.sh` fails CI
+when a line is unresolved, a cell is empty, or the N/A count drifts from the
+committed baseline — so an engine pin bump that changes the surface lands in
+this gate, not in a user's bug report.
+
+## Development
+
+```sh
+python -m venv .venv && source .venv/bin/activate
+pip install maturin pytest
+maturin develop               # build the native extension
+pytest tests                  # the golden suite (267 fixture lines)
+cargo fmt --check             # + cargo clippy --all-targets -- -D warnings
+```
+
+The plan — architecture ruling (engine compiled in via pyo3 vs
+Python-side ctypes/cffi FFI), the full OOP surface, the value
+contract, and follow-up tasks — is [docs/PLAN.md](docs/PLAN.md).
+
+## License
+
+MIT.
+

corvid_python-0.3.3.dist-info/RECORD

@@ -0,0 +1,9 @@
+corvid/__init__.py,sha256=7GN4PgxgstZE-uBnVXX_zlauzknsFvLvttzhDnROf_A,1072
+corvid/__init__.pyi,sha256=EqE3xLo_P-F_mD8KkmfYtUdgKqcVAxa4NBeHyJA0OAk,16667
+corvid/_native.pyd,sha256=dtIM56wr3KCX_x1ZTrXB4EMFAZsKGWZIeQ0p0uNi7Yc,2947072
+corvid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+corvid_python-0.3.3.dist-info/METADATA,sha256=lBqjr3vCmVt00o9ysulzPwAWxyu-C2uvI9ywNhMBvlE,6771
+corvid_python-0.3.3.dist-info/WHEEL,sha256=I37eTNpE2wbBLxuGAyG7p6lFvJQiIjnLN05rBA0wN9g,96
+corvid_python-0.3.3.dist-info/licenses/LICENSE,sha256=l-CaqWP1EJRlSkbP5KHYC_y4J5WY5xuL1dup-QxrXnY,1083
+corvid_python-0.3.3.dist-info/sboms/corvid-python.cyclonedx.json,sha256=0n592dUBcqtDg3cdga17Pxcv-XWa9D6Nm3f3qLplOdw,22961
+corvid_python-0.3.3.dist-info/RECORD,,

corvid_python-0.3.3.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: maturin (1.15.0)
+Root-Is-Purelib: false
+Tag: cp311-abi3-win_amd64

corvid_python-0.3.3.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rocky
+
+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.