Skip to content

Quartermaster 0.1.0

Latest
Latest

Choose a tag to compare

View all tags
@JumpTechCode JumpTechCode released this 22 Jun 16:47
v0.1.0
993e849
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

First tagged release. Quartermaster is a warehouse inventory engine that aims to stay correct under concurrent load: stock tracked per (SKU, location) and driven by inbound (receiving → putaway) and outbound (allocate → pick → pack → ship) document flows, where every command is idempotent, two state machines decide which transitions are legal, and the inventory invariants — stock never negative, reservations never exceeding stock, no SKU oversold, the books in balance — are enforced by Postgres under real concurrent traffic.

This is young software: interfaces may still change, and it has not yet seen production use.

What's in this release (V1)

  • Domain core — entities, two state machines (Receipt/inbound, Order/outbound) with line-level partiality, and the invariant set, in a pure leaf layer.
  • Postgres persistence — invariant-guarded conditional writes for stock, state/version CAS for documents, an exactly-once idempotency store, and an append-only movement ledger.
  • Application + API — command handlers wrapped in a one-transaction-per-command envelope with bounded OCC retry, and a FastAPI surface with Idempotency-Key handling.
  • Workers — reservation reaper, backorder sweep, and idempotency-key reaper.
  • Correctness-under-load harness — a high-concurrency mixed workload with an invariant oracle over the result and the ledger, including a naive falsification control that oversells and trips the oracle, giving the green runs their meaning. A scaled-down deterministic run gates every PR.

Not in scope yet

Lots/serials/license plates, multiple warehouses, wave/batch picking, allocation beyond greedy, carrier integration, and a UI — deliberate, documented boundaries (see the README's Scope section).

Verification

Builds and is tested under CI: ruff, mypy --strict, import-linter boundary contracts, the pytest suite (unit + real-Postgres integration) at ≥80% coverage, pip-audit, and CodeQL. Significant decisions are recorded as 32 ADRs under docs/adr.

Install

Not on PyPI yet. Attached are a built wheel and sdist; or build from the tag with uv build.

Licensed under Apache-2.0.

Assets 4
Loading