=== AuctionEngine ===
Contributors: imtaqin
Tags: auction, procurement, lpse, vickrey, zig
Requires Zig: 0.14.0
Stable tag: 0.2.0
License: MIT
License URI: https://opensource.org/licenses/MIT

Deterministic, high-performance auction mechanism library written in Zig.
Supports six mechanisms including Indonesian government LPSE procurement algorithms.


== Description ==

AuctionEngine is a standalone Zig library for evaluating auction outcomes.
It has no external dependencies and produces sub-millisecond results even
for large bid sets.

Supported mechanisms:

  * First-Price Sealed-Bid (FPSB)
  * Vickrey / Second-Price Sealed-Bid
  * English Auction (ascending, state machine)
  * Dutch Auction (descending, state machine)
  * LPSE Harga Terendah / Reverse Auction (Perpres 16/2018)
  * LPSE Sistem Nilai / Merit Point (70/30 tech+price weighting)

The LPSE mechanisms implement Indonesian government e-procurement rules
including HPS ceiling enforcement, TKDN domestic-content preference,
and bobot teknis/harga weighted scoring.

All mechanisms are deterministic: identical inputs always produce identical
outputs. Tie-breaking uses submission timestamp, never randomness.


== Installation ==

1. Ensure Zig 0.14.0 or later is installed.

2. Clone the repository:

     git clone https://github.com/imtaqin/AuctionEngine.git

3. Build the library:

     zig build

4. Build in release mode (recommended for production):

     zig build -Doptimize=ReleaseSafe

5. To build as a C-compatible shared library for FFI integration:

     zig build ffi

6. To cross-compile for a specific target:

     zig build cross


== Usage — JSON CLI ==

The CLI reads a JSON request from stdin or a file argument and writes
a JSON response to stdout.

  echo '{"mechanism":"vickrey","bids":[{"bidder_id":1,"amount":5000000,"timestamp":1},{"bidder_id":2,"amount":4000000,"timestamp":2}]}' | AuctionEngine

  AuctionEngine request.json

Supported top-level fields in the request object:

  mechanism       (required) one of: first_price, vickrey, english, dutch,
                  reverse_auction, sistem_nilai

  bids            array of bid objects with bidder_id, amount, timestamp.
                  LPSE mechanisms also accept technical_score and tkdn_pct.

  lpse_config     required for reverse_auction and sistem_nilai. Fields:
                  pagu_anggaran, hps, bobot_teknis, bobot_harga,
                  use_tkdn_preference, min_tkdn_for_preference,
                  tkdn_preference_pct

  config          optional for first_price, vickrey, english, dutch. Fields:
                  reserve_price, min_increment, max_bids_per_bidder,
                  deadline_ns, allow_late_bids

  events          required for english and dutch. Array of event objects
                  with type (raise, drop, finalize), bidder_id, amount.

  bidders         required for english. Array of participant bidder IDs.

  start_price     required for dutch.
  floor_price     optional for dutch.
  decrement       optional for dutch (default: 1).

Response fields:

  ok              boolean, true on success
  mechanism       echoed mechanism name
  winner_id       winning bidder ID
  winning_bid     winning bid amount
  price_paid      amount the winner actually pays
  combined_score  sistem_nilai only, winner composite score x100
  eval_price      LPSE mechanisms, evaluation price used for comparison
  err             present only on error, Zig error name string


== LPSE Configuration ==

pagu_anggaran         Budget ceiling. Bids above this are rejected outright.
hps                   Harga Perkiraan Sendiri (owner's price estimate).
                      Bids above HPS are rejected.
bobot_teknis          Technical score weight (0-100). Must sum with
                      bobot_harga to 100.
bobot_harga           Price score weight (0-100).
use_tkdn_preference   Enable TKDN domestic-content price preference.
min_tkdn_for_preference  Minimum TKDN percentage to qualify for preference.
tkdn_preference_pct   Preference discount applied to evaluation price only
                      (not to actual payment).

TKDN preference reduces the evaluated price used for ranking:
  eval_price = amount x (100 - tkdn_preference_pct) / 100

The winner still pays their original submitted amount.


== Frequently Asked Questions ==

= Why Zig? =

Zig offers explicit, allocator-based memory management with no hidden
allocations, comptime metaprogramming for zero-cost generics, and
built-in cross-compilation. These properties are valuable for a library
that must be auditable, deterministic, and embeddable in diverse host
environments.

= Can I call this from Python, Go, or Rust? =

Yes. Build with `zig build ffi` to produce a shared library exposing a
C ABI. Then use ctypes (Python), cgo (Go), or the Rust FFI to call it.
See include/auction_engine.h for the complete API surface.

= Are results reproducible? =

Yes. Given the same input, the engine always produces the same output.
Tie-breaking is by timestamp (earlier wins), never by random selection.
There is no global mutable state.

= What is the performance profile? =

Benchmarks on a modern x86-64:
  FPSB n=1 000    approx 10 microseconds
  FPSB n=10 000   approx 92 microseconds
  Vickrey n=1 000 approx 11 microseconds
  Dutch 100 ticks approx 60 nanoseconds

See docs/performance.md for full benchmark methodology and results.

= Is this suitable for production procurement? =

The engine implements the mathematical algorithm correctly per
Perpres 16/2018 rules. Production deployments must integrate with
proper authentication, audit logging, and regulatory compliance layers
that are outside this library's scope.


== Changelog ==

= 0.2.0 =
* Added LPSE Harga Terendah (reverse auction, Perpres 16/2018)
* Added LPSE Sistem Nilai (merit-point, 70/30 tech+price)
* Added TKDN domestic-content preference support
* Added C ABI FFI layer with auction_engine.h header
* Added JSON CLI (stdin or file argument, stdout JSON)
* Added property-based tests (14 properties, 1000 iterations each)
* Added benchmarks and performance tests
* Fixed validation from O(n2) to O(n) using adaptive hash set
* Cross-compile targets: linux-x64, linux-arm64, windows-x64,
  macos-arm64, wasm32-wasi

= 0.1.0 =
* First-Price Sealed-Bid mechanism
* Vickrey / Second-Price Sealed-Bid mechanism
* English Auction state machine
* Dutch Auction state machine
* Core types, validation, and error handling
* Unit tests with edge-case coverage
* Arena allocator and comptime specialization utilities


== License ==

MIT License

Copyright (c) 2026 imtaqin

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.