macrame-db 0.7.0__tar.gz

macrame_db-0.7.0/.cargo/config.toml

@@ -0,0 +1,119 @@
+# Test-harness settings for R15 (see the risk register in docs/).
+#
+# libSQL faults with STATUS_ACCESS_VIOLATION (0xc0000005) when local databases
+# are opened *concurrently* in one process. It is not a Macrame defect: it
+# reproduces with no Macrame types in the loop, it is not confined to any one
+# test binary -- storage_boundary, vector_filter, replay_snapshot, write_path
+# and the property binaries have all died mid-run -- and upgrading the
+# dependency 0.6.0 -> 0.9.30 did not change it.
+#
+# ---------------------------------------------------------------------------
+# If you are here because the build went red, read this paragraph first.
+# ---------------------------------------------------------------------------
+#
+# Re-run the failing binary on its own. Every binary that has died during a
+# suite run is clean in isolation -- four of them at 0/15 each, 60 isolated runs
+# with no fault. A binary that fails alone is a real failure; one that only
+# fails inside the suite is almost certainly this.
+#
+# And note the reporting hazard, because it is the opposite of what you expect:
+# the fault kills the process, so the tests that already printed `ok` are
+# reported, the ones behind it are silent, and that binary's `test result:` line
+# never appears. **A pass-count sum therefore comes back SMALLER with no
+# failures rather than red.** Anything gating on this suite must key on the
+# absence of a per-target result line, and `--no-fail-fast` is not optional or
+# everything alphabetically behind the fault is skipped as well.
+#
+# ---------------------------------------------------------------------------
+# What is known, and what was believed here and is not true
+# ---------------------------------------------------------------------------
+#
+# The trigger is CONCURRENT OPEN. A standalone reproducer separates the two
+# candidate variables directly (libsql 0.9.30, Windows, release, tokio
+# multi-thread, one file per task):
+#
+#     500 opens, sequential, one process         0/10
+#     4 / 8 / 16 concurrent opens                0/10 each
+#     32 concurrent opens                        2/12
+#     128 concurrent opens                       5/12
+#     128 concurrent, nothing dropped until end  3/12
+#
+# The threshold sits between 16 and 32 concurrent opens on this machine. The
+# last row is the sharp one: holding every handle alive until the end still
+# faults, so this is concurrent *open*, not an open/drop race and not teardown.
+#
+# REFUTED, and it was written here as the diagnosis until 0.6.0: that the
+# correlate is database open/drop CHURN. The suite data reads that way -- the
+# property binaries open one database per generated case and fault ~3/4 alone,
+# where an ordinary 20-test binary is 0/15 -- but 500 sequential opens in one
+# process is 0/10. Churn is not sufficient; concurrency is. The suite table
+# cannot distinguish the two, and no inference of that kind should be drawn
+# from it.
+#
+# ---------------------------------------------------------------------------
+# What this setting does, and what it does not
+# ---------------------------------------------------------------------------
+#
+# Serialising libtest REDUCES THE RATE. It does not remove the fault, and an
+# earlier version of this file said that it did:
+#
+#     0.5.4, full suite, libtest default (parallel)   1/20 bad runs
+#     0.5.4, full suite, --test-threads=1             0/30 bad runs
+#     0.5.6, full suite, --test-threads=1             5/10 bad runs
+#
+# Same dependency version throughout, and the last row was measured WITH this
+# setting in force. Either the rate rose with the suite (171 -> 221 tests) or
+# the original 0/30 was a lucky streak. Read 0/30 as a data point, not as a
+# guarantee this file provides.
+#
+# One thing this does not explain, flagged rather than guessed at: every binary
+# is 0/15 alone while the suite that runs those same binaries serially is 5/10,
+# all under RUST_TEST_THREADS = "1". If concurrent opens are required, the
+# suite-level runs are finding concurrency that per-binary runs do not, and this
+# data does not say where. `Database::open` taking three connections (four with
+# the cadence) is the obvious suspect and is not evidence.
+#
+# `[env]` does not override a value already in the environment, so setting
+# RUST_TEST_THREADS yourself still works -- which is how you reproduce the fault
+# if you are chasing it, or check whether an upstream release has fixed it.
+#
+# The three generated-history targets (doctrine, integrity, graph) are behind
+# the `property-tests` feature and run as their own step, because a property
+# case needs a database of its own and serialising does not save them:
+# doctrine_property_tests faulted 3/4 and integrity_property_tests 1/4 in the
+# same session, against ~3/25 recorded at 0.5.4. Quarantined, not silenced --
+# proptest replays every previously found failure from .proptest-regressions
+# before a single new case is generated.
+#
+# Re-measured at 0.7.0 on a larger sample: doctrine_property_tests alone,
+# **9 crashes in 15 runs**, on a machine that had been building wheels all
+# session. That sits between the two figures above rather than contradicting
+# either, and it is the clearest statement of why these are quarantined: at 60%
+# no retry budget makes them a gate. The Rust source was unchanged across the
+# whole of that measurement -- P4-P6 touched only the binding crate, tests_py
+# and docs -- so the variable is load, not code.
+#
+# It also produced a textbook demonstration of the reporting hazard. With
+# --no-fail-fast the run came back **308 passed, 0 failed** and exit 101: eight
+# tests silently absent, and nothing in the pass/fail line saying so. See
+# `tests_py/run_suite.py` for the Python-side gate built around exactly this,
+# and D-107 for why the two sides need different checks.
+#
+# ---------------------------------------------------------------------------
+# Production exposure
+# ---------------------------------------------------------------------------
+#
+# Soaked and defended in 0.6.0 (T5.2, D-092), in the sharpened form -- ONE
+# PROCESS, ONE FILE, A BOUNDED SET OF CONNECTIONS OPENED ONCE AND NEVER CHURNED.
+# That wording matters: the old claim was about one `Database` handle, and a
+# handle is not what the fault counts.
+#
+#     cargo run --release --example r15_soak -- --arm claim   --secs 60 --runs 6
+#     cargo run --release --example r15_soak -- --arm control --secs 15 --runs 10
+#
+# claim is 0/6 at 60s and 0/10 at 15s; control, which adds 48 concurrent opens
+# to the same load, is 2/10. The control is what makes the claim arm mean
+# anything -- a clean claim run on its own is indistinguishable from a harness
+# that provoked nothing. Run both or neither.
+[env]
+RUST_TEST_THREADS = "1"

macrame_db-0.7.0/.github/workflows/ci.yml

@@ -0,0 +1,137 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call: # so release.yml can gate on exactly this
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  lint:
+    name: clippy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: rustfmt, clippy
+      - uses: Swatinem/rust-cache@v2
+
+      # `--all-targets` covers benches and examples, which is where several of
+      # this project's diagnostics live and where clippy has caught real defects
+      # (D-075's oversized DbError came out of a clippy warning). Verified clean
+      # under `-D warnings` at 0.6.0, so this is a gate that currently passes.
+      #
+      # `-D warnings` is scoped to this step rather than set for the workflow:
+      # as a global RUSTFLAGS it also applies to the `cargo publish --dry-run`
+      # verification build, where a warning from a dependency's build would fail
+      # a packaging check that has nothing to do with warnings.
+      - name: clippy
+        run: cargo clippy --all-targets --features metrics
+        env:
+          RUSTFLAGS: -D warnings
+
+      # **Report-only, deliberately.** This repo has never been rustfmt-clean —
+      # 246 diffs at 0.6.0, essentially all in tests and benches — so a blocking
+      # gate would go red on its first run for a pre-existing condition, and the
+      # only way to green it is a repo-wide reformat nobody reviewed. Adopting
+      # rustfmt is a decision worth taking on purpose: run `cargo fmt --all` in
+      # its own commit, then delete `continue-on-error` here.
+      - name: rustfmt (advisory)
+        run: cargo fmt --all -- --check
+        continue-on-error: true
+
+  # The README carries an MSRV badge and `Cargo.toml` a `rust-version`, and
+  # both are claims. Nothing else in the build would notice them going stale:
+  # the crate is developed on stable, so a newly used std method raises the real
+  # floor silently and the declared one stays where it was.
+  #
+  # `--all-targets` deliberately: tests and benches use `OnceLock` and other
+  # items the library does not, and a contributor hitting a build failure the
+  # badge said would not happen is the same defect as a wrong badge.
+  msrv:
+    name: MSRV (rust-version in Cargo.toml)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - id: msrv
+        run: echo "v=$(grep -m1 '^rust-version' Cargo.toml | sed 's/.*= *//; s/\"//g')" >> "$GITHUB_OUTPUT"
+      - uses: dtolnay/rust-toolchain@master
+        with:
+          toolchain: ${{ steps.msrv.outputs.v }}
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo check --all-features --all-targets
+
+  test:
+    name: test (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      # `.cargo/config.toml` sets RUST_TEST_THREADS = "1" for R15 and applies
+      # here automatically. Read that file before changing anything below.
+      #
+      # R15 is an intermittent libSQL access violation (0xC0000005) triggered by
+      # concurrent database opens. It kills the process, so cargo reports
+      # "error: N targets failed" and the run goes red for a reason that has
+      # nothing to do with the change under test — measured at ~5/10 full-suite
+      # runs on Windows. A gate that fails half the time trains people to ignore
+      # red, which is this project's own stated position, so the run is retried
+      # rather than tolerated or ignored.
+      #
+      # Three attempts, not unlimited: R15 has always passed on re-run, so a
+      # genuine failure still goes red after three, and the attempt count is
+      # visible in the log rather than hidden by a `continue-on-error`.
+      - name: test (with R15 retry)
+        shell: bash
+        run: |
+          for attempt in 1 2 3; do
+            echo "::group::cargo test, attempt $attempt"
+            if cargo test --features metrics --no-fail-fast; then
+              echo "::endgroup::"
+              echo "passed on attempt $attempt"
+              exit 0
+            fi
+            echo "::endgroup::"
+            echo "::warning::attempt $attempt failed; see R15 in .cargo/config.toml"
+          done
+          echo "::error::three consecutive test runs failed — this is not R15"
+          exit 1
+
+      # The generated-history binaries are quarantined behind a feature (see
+      # .cargo/config.toml): a property case opens a database of its own, which
+      # is exactly R15's trigger, so they fault far more often than the rest.
+      # Run as their own step so their noise cannot be mistaken for the suite's.
+      - name: property tests (quarantined, R15-prone)
+        shell: bash
+        run: |
+          for attempt in 1 2 3; do
+            if cargo test --features property-tests --no-fail-fast; then
+              exit 0
+            fi
+            echo "::warning::property attempt $attempt failed"
+          done
+          echo "::error::property tests failed three times"
+          exit 1
+
+  # A `cargo publish` failure after a tag is pushed is expensive: the tag is
+  # already public and the version number is spent. This runs the same
+  # packaging and verification step on every PR, so the release job's only new
+  # variable is the upload itself.
+  package:
+    name: cargo publish --dry-run
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo publish --dry-run

macrame_db-0.7.0/.github/workflows/python.yml

@@ -0,0 +1,187 @@
+name: Python
+
+# The Python side of the project: the binding crate compiles, the extension
+# builds and installs the way a user installs it, and the 337-test suite passes
+# on every platform this repository claims to support.
+#
+# ## Why this does not call `ci.yml` first
+#
+# The plan (§10) sketched this file as `rust: uses ./.github/workflows/ci.yml`
+# with everything else behind `needs: rust`. That shape belonged to a file that
+# also built the wheels — "the crate must be green before the wheel is built".
+# P5 moved the wheel matrix into `wheels.yml`, tag-triggered, and what is left
+# here is a test job whose failure mode is independent of the Rust suite's.
+#
+# `workflow_call` does not deduplicate: gating here would re-run clippy, MSRV,
+# the two-OS Rust matrix (each with its own three R15 retries) and the publish
+# dry-run on every pull request that already ran them, and would hold the Python
+# answer behind ~15 minutes of work it does not depend on. Two independent
+# signals, reported separately, is strictly more information than one signal
+# reported late.
+#
+# Where the two *must* be green together is before an upload, and that is what
+# `workflow_call` above is for: `wheels.yml`'s publish job gates on this file,
+# exactly as `release.yml` gates on `ci.yml`. See D-108.
+#
+# ## The gap this closes
+#
+# `bindings/python` is a workspace *member* but never a *default* member — the
+# root package is itself a member, so Cargo scopes bare commands to it alone,
+# which is the property `tests/packaging_tests.rs` pins and the reason `cargo
+# publish` stayed a one-package operation (D-098). The cost of that choice, not
+# noticed until now: **nothing in CI ever compiled the binding crate.** Until
+# this file existed, a pull request could break `bindings/python/src/*.rs` and
+# every check would go green, because the only thing that built it was
+# `wheels.yml`, which runs on tags.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call: # so wheels.yml can gate an upload on exactly this
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  # `-p macrame-py` explicitly. Every other clippy invocation in this repository
+  # is scoped to the root package by Cargo's own default, so this one has to
+  # name the crate or it lints the same code `ci.yml` already linted.
+  #
+  # Deliberately **without** `--features extension-module`: that feature is
+  # turned on by `pyproject.toml` for maturin's build only, and the binding
+  # manifest states the crate must build without it. A check that silently
+  # required it would make that statement untestable.
+  lint:
+    name: clippy (binding crate)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy
+      - uses: Swatinem/rust-cache@v2
+      - name: clippy
+        run: cargo clippy -p macrame-py --all-targets
+        env:
+          RUSTFLAGS: -D warnings
+
+      # `tests_py/test_stubs.py` compares the stub's *names* against the
+      # extension in both directions. It cannot see a wrong **type** — a stub
+      # that says `-> int` where the runtime answers a `datetime` passes every
+      # one of those checks. A type checker is what reads the annotations, so
+      # one runs here, over the stub and the package that re-exports it.
+      #
+      # No Rust toolchain needed and no extension built: `--strict` on a `.pyi`
+      # is a pure text analysis. Measured clean at 0.7.0, so this is a gate that
+      # passes rather than a backlog.
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - name: mypy (the stub, and the package that re-exports it)
+        run: |
+          python -m pip install --upgrade pip mypy
+          python -m mypy --strict python/macrame
+
+  test:
+    name: suite (${{ matrix.os }}, py${{ matrix.python }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      # One platform failing must not hide the others: R15 is platform-sensitive
+      # and the whole point of a three-OS matrix is knowing which ones it hit.
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            python: "3.13"
+          # The floor `pyproject.toml` declares. `requires-python = ">=3.10"` is
+          # a claim pip enforces against users and nothing enforces against us.
+          - os: ubuntu-latest
+            python: "3.10"
+          - os: windows-latest
+            python: "3.13"
+          # macOS has never run this suite. `wheels.yml` builds a universal2
+          # wheel and smoke-tests it with six lines; this is the first time the
+          # ledger's Python surface is exercised on Apple silicon at all.
+          - os: macos-latest
+            python: "3.13"
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      # `pip install .` rather than `maturin develop`: it goes through the PEP
+      # 517 backend, which means it reads `[tool.maturin]` and therefore builds
+      # with `--features extension-module` and in release, i.e. it is the same
+      # path a user takes. `maturin develop` would need a virtualenv here and
+      # would test a build configuration nobody installs.
+      - name: install the extension the way a user installs it
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install .
+          python -m pip install pytest
+
+      # **Not bare pytest** (D-107). R15 is an intermittent libSQL access
+      # violation on concurrent open, reproduced through this binding at 2 in 12
+      # runs, and it kills the interpreter rather than raising. `run_suite.py`
+      # distinguishes the four ways this suite can end — CRASH, FAILED,
+      # INCOMPLETE, TEARDOWN — retries only the first, three times, and reports
+      # the rest red on the first attempt. A green summary is not sufficient
+      # here and neither is a zero exit; it checks them against each other.
+      - name: python suite (through the R15 gate)
+        run: python tests_py/run_suite.py
+
+  # abi3 is what turns a 4-platform × 5-version matrix into 4 builds, and the
+  # claim underneath it — "one wheel serves CPython 3.10 through whatever ships
+  # next" — is not tested by any job above, because each of those builds and
+  # runs on a single interpreter.
+  #
+  # So: build once on the floor, install that same artifact into an interpreter
+  # it has never seen, and run the whole suite through it. If pyo3's abi3
+  # feature were ever dropped, every other job here would still pass and the
+  # wheel matrix would quietly become wrong by a factor of five.
+  abi3:
+    name: one wheel, two interpreters
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        id: floor
+        with:
+          python-version: "3.10"
+      - uses: actions/setup-python@v5
+        id: newest
+        with:
+          python-version: "3.13"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      # Debug, deliberately: this job asks what the wheel is *tagged* and
+      # whether it imports, not how fast it runs. `wheels.yml` builds the
+      # release artifact.
+      - name: build one wheel, on 3.10
+        shell: bash
+        run: |
+          "${{ steps.floor.outputs.python-path }}" -m pip install --upgrade pip maturin
+          "${{ steps.floor.outputs.python-path }}" -m maturin build --out dist
+
+      - name: the tag names the ABI, not the interpreter that built it
+        shell: bash
+        run: |
+          ls -la dist
+          if ! ls dist/*-abi3-*.whl >/dev/null 2>&1; then
+            echo "::error::no abi3 wheel — pyo3's abi3-py310 feature is off, and"
+            echo "::error::the wheel matrix in wheels.yml is now wrong per Python version"
+            exit 1
+          fi
+
+      - name: run the whole suite on 3.13, against the wheel built by 3.10
+        shell: bash
+        run: |
+          "${{ steps.newest.outputs.python-path }}" -m pip install --upgrade pip pytest
+          "${{ steps.newest.outputs.python-path }}" -m pip install --no-index --find-links dist macrame-db
+          "${{ steps.newest.outputs.python-path }}" tests_py/run_suite.py

macrame_db-0.7.0/.github/workflows/release.yml

@@ -0,0 +1,87 @@
+name: Release
+
+# Two ways in, and only one of them can publish.
+#
+#   * push a tag `v0.6.0`  -> verify, then upload to crates.io
+#   * run it by hand       -> verify and dry-run only, unless `publish` is
+#                             explicitly set to `true`
+#
+# The manual dry run exists so the whole path can be exercised without spending
+# a version number. A crates.io version cannot be re-uploaded once taken, even
+# if it is yanked, so a failed publish costs the number permanently.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: 'Actually upload to crates.io (otherwise dry-run only)'
+        type: boolean
+        default: false
+
+env:
+  CARGO_TERM_COLOR: always
+
+permissions:
+  contents: read
+
+jobs:
+  # The full CI matrix, reused rather than reimplemented — a release gate that
+  # is a second copy of the test job is a gate that drifts from it.
+  verify:
+    uses: ./.github/workflows/ci.yml
+
+  # Cheap, and it runs *before* anything is uploaded: a tag that disagrees with
+  # the manifest publishes a version nobody can find from the tag, and the only
+  # fix is another version number.
+  check-version:
+    name: tag matches Cargo.toml
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - name: compare
+        shell: bash
+        run: |
+          manifest=$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].version')
+          tag="${GITHUB_REF_NAME#v}"
+          echo "manifest=$manifest  tag=$tag"
+          if [ "$manifest" != "$tag" ]; then
+            echo "::error::tag $GITHUB_REF_NAME does not match Cargo.toml version $manifest"
+            exit 1
+          fi
+
+  publish:
+    name: publish to crates.io
+    needs: [verify, check-version]
+    runs-on: ubuntu-latest
+    # Tag pushes publish; a manual run publishes only when asked. `always()` is
+    # deliberately absent — if `check-version` is skipped on a manual run, this
+    # still requires `verify` to have succeeded.
+    if: |
+      startsWith(github.ref, 'refs/tags/v') ||
+      inputs.publish == true
+    environment: crates-io # add a required reviewer here to gate uploads
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+
+      - name: publish
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish
+
+  # Runs on manual invocations that did not ask to publish: the same packaging
+  # and verification `cargo publish` performs, stopping before the upload.
+  dry-run:
+    name: publish --dry-run
+    needs: verify
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' && inputs.publish != true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - run: cargo publish --dry-run